commit 8a8e5ca0c0d538f7b04814a7806dcdced381c4d1
Author: AskaEth <i@yeij.top>
Date:   Thu Nov 5 14:22:11 2026 +0800

    Unlucky Launcher v0.2.0
    
    首个 iced + Material 3 Expressive 版本的源码快照。
    完整历史与日常提交在 dev 分支；main 只放阶段性快照。

diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..f3f1a1b
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,34 @@
+# 换行策略：仓库内一律 LF（rustfmt 设 newline_style = "Unix"，CI 在 Linux 上跑 fmt --check）。
+# eol=lf 对工作区同样生效 —— Windows 克隆也不会被转换成 CRLF，避免「本地 fmt 过、CI fmt 挂」。
+* text=auto eol=lf
+
+# 明确为文本（显式列出，防止被误判成二进制）
+*.rs       text eol=lf
+*.toml     text eol=lf
+*.md       text eol=lf
+*.slint    text eol=lf
+*.yml      text eol=lf
+*.yaml     text eol=lf
+*.json     text eol=lf
+Cargo.lock text eol=lf
+
+# 二进制：不做换行转换、不做文本 diff
+*.png   binary
+*.ico   binary
+*.icns  binary
+*.jpg   binary
+*.jpeg  binary
+*.gif   binary
+*.webp  binary
+*.ttf   binary
+*.otf   binary
+*.woff  binary
+*.woff2 binary
+*.zip   binary
+*.7z    binary
+*.gz    binary
+*.tar   binary
+*.exe   binary
+*.dll   binary
+*.lib   binary
+*.pdb   binary
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..d335915
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,190 @@
+name: CI
+
+# 主干门禁：fmt / clippy / test / build 双平台矩阵。
+# 架构守门（core 零 UI、文件 ≤400 行、依赖许可）见 guards.yml。
+# 平台基线 Win10+（标准工具链产物），平台矩阵见 AGENTS.md §7。
+#
+# M118（D26）：根 Cargo.toml 已 `exclude = ["crates/app"]`（Slint 退役树，源码原样保留）。
+# 所以本文件里所有 `--workspace` 都**不再**覆盖 `unlucky-app`：CI 不再编 slint 1.18 + usvg 0.48
+# 那棵依赖树（本机单路冷编 ≈14 分钟；并行超配时表现为 `rustc` 退 1 且零诊断，
+# 见 DevDocs/00-踩坑记录-p2.md T7）。历史实现只作源码参考，**没有构建方式**（见 README：
+# 它的 manifest 整份是 workspace 继承写法，离开 workspace 后连解析都过不了）。
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+env:
+  CARGO_TERM_COLOR: always
+  RUST_BACKTRACE: 1
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  fmt:
+    name: fmt (rustfmt --check)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt
+      - run: cargo fmt --all --check
+
+  clippy:
+    name: clippy (${{ matrix.os }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-latest, ubuntu-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Linux 图形栈构建依赖（winit / wgpu 编译期需要）
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            libxkbcommon-dev libfontconfig1-dev libgl1-mesa-dev libegl1-mesa-dev \
+            libwayland-dev libxcb1-dev
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+      - uses: Swatinem/rust-cache@v2
+      # `--workspace` 现在是 8 个 crate，不含 `unlucky-app`（M118 的 workspace exclude），
+      # 所以这条命令不会拉起 slint / usvg / i-slint-*。
+      - run: cargo clippy --workspace --all-targets -- -D warnings
+
+  test:
+    name: test (${{ matrix.os }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-latest, ubuntu-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Linux 图形栈构建依赖
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            libxkbcommon-dev libfontconfig1-dev libgl1-mesa-dev libegl1-mesa-dev \
+            libwayland-dev libxcb1-dev
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      # 同 clippy：`--workspace` 不含 `unlucky-app`（M118），Slint 退役树不再被 `--all-targets` 拉起。
+      # 也因此**不要**再写 `--exclude unlucky-app`：它已不是成员，那面旗子只会打一条
+      # `excluded package(s) … not found in workspace` 的警告然后空转（实测 exit 0，不报错）。
+      - run: cargo test --workspace --all-targets
+
+  build:
+    name: build release (${{ matrix.os }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-latest, ubuntu-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Linux 图形栈构建依赖
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            libxkbcommon-dev libfontconfig1-dev libgl1-mesa-dev libegl1-mesa-dev \
+            libwayland-dev libxcb1-dev
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      # 同上：`--workspace` 不含 `unlucky-app`（M118）。被摘掉的正是 release 档
+      # （lto=fat + codegen-units=1）最贵的那棵 slint + usvg 树。
+      - run: cargo build --workspace --release
+
+  # 运行时冒烟（M62）：Linux 上**真渲染一帧**，补上「能编译 ≠ 能跑」的空白。
+  # 上面四个 job 都只证明代码编得过、测得过，从不创建真实图形窗口；本 job 在 Xvfb 虚拟显示里
+  # 启动 GUI 进程，让软件渲染器把当前场景渲进内存像素缓冲并编码成 PNG，再对**像素本身**
+  # 断言（不是只看退出码：窗口起来了但一帧空白同样是「退出码 0」）。
+  # 诚实边界：证明「Linux 上真能跑出非空白的一帧」，**不**证明视觉正确——视觉靠人眼看 artifact。
+  # M118（D26）：这里原本绑死 Slint 的 `Window::take_snapshot`，打的是 Slint 版 bin
+  # `unlucky-launcher`；`crates/app` 退出 workspace 后那个 bin 不再存在，改用 iced 版
+  # `unlucky-launcher-iced` 自带的 `--screenshot` 通道（`crates/app-iced/src/shot/`）。
+  # 命令行参数刻意不动：iced 的 `cli.rs` 就是照 Slint 版的口径写的，`--data-dir` 也仍被接受（忽略）。
+  runtime-smoke:
+    name: runtime smoke (ubuntu x64, xvfb)
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - name: 无头 X 与图形栈依赖（xvfb + 软渲染 + 字体）
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            xvfb xauth \
+            libxkbcommon-dev libxkbcommon-x11-0 libfontconfig1-dev \
+            libgl1-mesa-dev libegl1-mesa-dev libwayland-dev libxcb1-dev \
+            libx11-6 libxcursor1 libxrandr2 libxi6 \
+            fonts-dejavu-core fonts-liberation2
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      # 用 debug 而不是 release：本 job 验的是「运行时渲染通路能通」，不是优化后二进制的行为；
+      # release 的 lto="fat" + codegen-units=1 会把这一步拖到十几分钟却不带来额外证据。
+      # M118：bin 从 Slint 版 `unlucky-launcher` 换成 iced 版（见上方 job 注释）。
+      - run: cargo build --bin unlucky-launcher-iced --locked
+      - name: 在 Xvfb 里跑一帧并截图（退出码非 0 即失败）
+        run: |
+          set -o pipefail  # 当前没有管道（死行），保留是为将来加管道时先有失败传播
+          mkdir -p "$RUNNER_TEMP/smoke/data"
+          xvfb-run -a --server-args="-screen 0 1280x1024x24" \
+            target/debug/unlucky-launcher-iced --software-renderer \
+            --screenshot "$RUNNER_TEMP/smoke/runtime-smoke.png" \
+            --data-dir "$RUNNER_TEMP/smoke/data"
+      - name: 断言 PNG 存在且非空白（尺寸 / 唯一色数 / 亮度σ / 强边缘占比）
+        run: python3 packaging/check_screenshot.py "$RUNNER_TEMP/smoke/runtime-smoke.png" --json
+      - name: 上传截图与数据目录（失败也传，便于复盘）
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: runtime-smoke-screenshot
+          path: ${{ runner.temp }}/smoke/
+          if-no-files-found: warn
+
+  # macOS 槽位探针（M62）：**默认不在 PR 上跑**，只有手动 dispatch 才触发。
+  # 之所以是探针而不是常驻槽位：官方 macOS runner 处于 LaunchDaemon 上下文，没有登录的
+  # WindowServer 会话，GUI 的 winit backend 创建窗口大概率直接失败；而 worker 禁 push，
+  # 本机也没有 macOS，这条路径**尚无任何实测证据**——不拿未验证的 job 卡住主干门禁。
+  # 首跑结论决定去留：绿 → 去掉 if/continue-on-error 升为常驻槽位；红 → 按 D26 归入 iced
+  # 重写后再规划，并把错误原文贴进 progress 文档（不静默删 job、不吞失败原因）。
+  # M118：bin 与 Linux 那条一样，从 Slint 版换成 iced 版（`unlucky-launcher-iced`）。
+  runtime-smoke-macos:
+    name: runtime smoke (macos arm64, probe)
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: macos-latest
+    timeout-minutes: 30
+    # 探针阶段保留证据但不算流水线结论：log/artifact 里失败原因照常可见，
+    # 解除条件 = 该槽位在真实 runner 上首跑通过并把本行与上面那条 if 一起删掉。
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo build --bin unlucky-launcher-iced --locked
+      - name: 尝试截图（macOS 没有 X 服务器，直接跑；失败即为结论）
+        run: |
+          set -o pipefail  # 当前没有管道（死行），保留是为将来加管道时先有失败传播
+          mkdir -p "$RUNNER_TEMP/smoke/data"
+          target/debug/unlucky-launcher-iced --software-renderer \
+            --screenshot "$RUNNER_TEMP/smoke/runtime-smoke.png" \
+            --data-dir "$RUNNER_TEMP/smoke/data"
+      - name: 断言 PNG 存在且非空白
+        run: python3 packaging/check_screenshot.py "$RUNNER_TEMP/smoke/runtime-smoke.png" --json
+      - name: 上传截图与数据目录（失败也传，便于复盘）
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: runtime-smoke-screenshot-macos
+          path: ${{ runner.temp }}/smoke/
+          if-no-files-found: warn
diff --git a/.github/workflows/guards.yml b/.github/workflows/guards.yml
new file mode 100644
index 0000000..767f8be
--- /dev/null
+++ b/.github/workflows/guards.yml
@@ -0,0 +1,381 @@
+name: Guards
+
+# 架构与合规守门（与 fmt/clippy 同级，不允许 continue-on-error）：
+#   1. core-no-ui      —— crates/core 零 UI 依赖（D3 铁律），依赖表 + cargo tree 双查
+#   2. presenter-no-ui —— crates/presenter 零 UI 依赖（D26 / M85）：Slint 版与 iced 版共用的宿主层
+#   3. design-zero-dep —— crates/design 零第三方依赖（M61 / M87）：依赖表（含 dev/build）必须为空 + 依赖树只允许出现自身
+#   4. file-size       —— 全仓代码/文档单文件 ≤400 行（用户硬约束）
+#   5. licenses        —— cargo-deny：许可证白名单 + GPL 依赖拦截 + 供应链来源校验
+#   6. unsafe-scope    —— 全仓 `allow(unsafe_code)` 的文件集合必须恰好只有一个（D36 / M91）
+#
+# M118（D26）：根 Cargo.toml 已 `exclude = ["crates/app"]`（Slint 退役树）。逐条核对过本文件，
+# **没有**任何一条守卫以 `--workspace` 为前提，所以排除不会让它们空转：
+#   ① core-no-ui / presenter-no-ui / design-zero-dep —— 「manifest 文本 + `cargo tree -p <crate>`」
+#      口径，被守的 crate 仍是 workspace 成员，依赖树与排除前逐行一致；
+#   ② file-size / unsafe-scope —— 走 `git ls-files` / `git grep`，与构建图无关，**仍然覆盖
+#      `crates/app/**`**（源码还在仓库里，就还得守它的行数与 unsafe 落点）；
+#   ③ licenses —— 唯一走 workspace 依赖图的守卫。排除后 Slint 那棵树不再进图（实测 `cargo deny
+#      list` 里 `slint*` / `i-slint-*` 为 0 个），这与「不再随任何产物发布」一致；代价是它的许可证
+#      不再被本门禁审 —— 真要重新纳入发布，得先把它加回 workspace，门禁随之恢复。
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  core-no-ui:
+    name: core 零 UI 守门
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - name: 依赖表直查（crates/core/Cargo.toml 不得出现 UI 框架）
+        run: |
+          set -uo pipefail
+          forbidden='slint|egui|eframe|iced|winit|gtk|javafx|tauri|fltk|druid|relm'
+          # 只看非注释行：manifest 里说明「不许出现 slint」的注释本身不该触发守门
+          if grep -vE '^[[:space:]]*#' crates/core/Cargo.toml | grep -nEi "$forbidden"; then
+            echo "::error file=crates/core/Cargo.toml::core 不得依赖 UI 框架（见 AGENTS.md 硬约束）"
+            exit 1
+          fi
+          echo "OK: crates/core/Cargo.toml 无 UI 依赖"
+      - name: 依赖树泄漏检查（cargo tree -p unlucky-core，排除自身行）
+        run: |
+          set -uo pipefail
+          forbidden='slint|egui|eframe|iced|winit|gtk|javafx|tauri|fltk|druid|relm'
+          tree=$(cargo tree -p unlucky-core --edges normal --prefix none)
+          echo "$tree"
+          if echo "$tree" | grep -vE '^unlucky-core v' | grep -qiE "$forbidden"; then
+            echo "::error::core 的依赖树出现 UI 框架 —— 传递依赖也不允许"
+            exit 1
+          fi
+          echo "OK: unlucky-core 依赖树零 UI"
+
+  # presenter 是 Slint 版（crates/app）与 iced 版（crates/app-iced）共用的唯一业务层（D26）。
+  # 一旦 slint/iced/winit 被拉进来，分层就废了，而编译与单测仍会全绿 —— 所以必须由 CI 守。
+  # M118 之后 Slint 版已被 workspace `exclude`，但本条**照样守得住**：它查的是 presenter 自己的
+  # manifest 与 `cargo tree -p unlucky-presenter`，与「谁在消费 presenter」无关；依赖树里一旦出现
+  # slint/iced/winit 仍会当场红。名单里的 slint 继续留着，就是为了防「把 UI 依赖偷偷塞进宿主层」。
+  # 与 core-no-ui 同样是「依赖表 + cargo tree」双查，名单保持一致；脚本刻意复制而非抽公共脚本，
+  # 理由是 CI 守门脚本自身挂掉的排查成本远高于这几行重复。
+  presenter-no-ui:
+    name: presenter 零 UI 守门
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - name: 依赖表直查（crates/presenter/Cargo.toml 的依赖表不得出现 UI 框架）
+        run: |
+          set -uo pipefail
+          forbidden='slint|egui|eframe|iced|winit|gtk|javafx|tauri|fltk|druid|relm'
+          # 与 core-no-ui 的整文件 grep 不同：本 crate 的 description 合法地写着
+          # 「Slint 版与 iced 版共用」，整文件 grep 会把它当越线。所以先按表头切出依赖表
+          # （含 target.*.dependencies 与 dev/build 表），再去掉注释行，只查键名。
+          # 子表写法 `[dependencies.slint]` / `[target.'cfg(windows)'.dependencies.slint]`
+          # 是合法的等长写法，且表头本身带着包名，所以表头也要一并落进检查范围——
+          # 否则「子表 + optional + 非默认 feature」这种组合能同时骗过依赖表与 cargo tree。
+          awk '
+            /^[[:space:]]*\[/ {
+              in_deps = ($0 ~ /^[[:space:]]*\[(target\..*\.)?(dependencies|dev-dependencies|build-dependencies)(\.[^]]*)?\][[:space:]]*$/)
+              if (in_deps && $0 ~ /\.[^]]*\]/) printf "%d:%s\n", NR, $0
+              next
+            }
+            in_deps && !/^[[:space:]]*#/ && !/^[[:space:]]*$/ { printf "%d:%s\n", NR, $0 }
+          ' crates/presenter/Cargo.toml > /tmp/presenter-deps.txt
+          cat /tmp/presenter-deps.txt
+          if grep -iE "$forbidden" /tmp/presenter-deps.txt; then
+            echo "::error file=crates/presenter/Cargo.toml::presenter 不得依赖 UI 框架（D26）。窗口创建 / 渲染 / 图片解码属于 app 与 app-iced 侧；需要跨前端共用的类型请放进 presenter 的 dto。"
+            exit 1
+          fi
+          echo "OK: crates/presenter/Cargo.toml 依赖表无 UI 依赖"
+      - name: 依赖树泄漏检查（cargo tree -p unlucky-presenter，排除自身行）
+        run: |
+          set -uo pipefail
+          forbidden='slint|egui|eframe|iced|winit|gtk|javafx|tauri|fltk|druid|relm'
+          # 注意：cargo tree 命中 UI 框架时**退出码仍是 0**，所以只能抓输出再判断。
+          if ! tree=$(cargo tree -p unlucky-presenter --edges normal --prefix none); then
+            echo "::error::cargo tree -p unlucky-presenter 执行失败 —— crate 是否仍叫 unlucky-presenter？"
+            exit 1
+          fi
+          echo "$tree"
+          hits=$(printf '%s\n' "$tree" | grep -vE '^unlucky-presenter v' | grep -iE "$forbidden")
+          if [ -n "$hits" ]; then
+            echo "::error::presenter 的依赖树出现 UI 框架（传递依赖也不允许），本次命中："
+            printf '%s\n' "$hits" | sed 's/^/  - /'
+            echo "::error::presenter 是 Slint 版与 iced 版共用的宿主层：把窗口 / 渲染 / 图片解码留在 app 侧，presenter 只持有与框架无关的 DTO、状态 reducer 与 host 装配。"
+            exit 1
+          fi
+          echo "OK: unlucky-presenter 依赖树零 UI"
+
+  # unlucky-design 是「纯数据 + 纯函数、零第三方依赖」的设计令牌层，这是 README 明写的卖点
+  # （连 serde 都不加），但目前只靠人肉守。零依赖的判据比 UI 名单更硬：依赖树只允许有自己一行。
+  # 注意 `cargo tree --edges normal` 看不到 dev/build 依赖，所以另设一步按表头切依赖表逐个查空。
+  design-zero-dep:
+    name: design 零第三方依赖守门
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - name: 依赖表必须为空（dependencies / dev / build 表一律不许有键，含子表写法）
+        run: |
+          set -uo pipefail
+          # design 承诺的是「零第三方依赖」，不分 normal / dev / build —— 而 cargo tree
+          # --edges normal 对 dev/build 是瞎的。所以先按表头切出全部依赖表（含
+          # `[dependencies.serde]` 这类子表写法，表头本身携带包名），再看是否为空。
+          awk '
+            /^[[:space:]]*\[/ {
+              in_deps = ($0 ~ /^[[:space:]]*\[(target\..*\.)?(dependencies|dev-dependencies|build-dependencies)(\.[^]]*)?\][[:space:]]*$/)
+              if (in_deps && $0 ~ /\.[^]]*\]/) printf "%d:%s\n", NR, $0
+              next
+            }
+            in_deps && !/^[[:space:]]*#/ && !/^[[:space:]]*$/ { printf "%d:%s\n", NR, $0 }
+          ' crates/design/Cargo.toml > /tmp/design-deps.txt
+          if [ -s /tmp/design-deps.txt ]; then
+            cat /tmp/design-deps.txt
+            echo "::error file=crates/design/Cargo.toml::unlucky-design 的依赖表必须为空（normal / dev / build 都算），本次命中："
+            sed 's/^/  - /' /tmp/design-deps.txt
+            echo "::error::design 是纯数据 + 纯函数的设计令牌，README 对外承诺零第三方依赖（连 serde 都不加）：色彩 / 排版 / 形状 / 高程 / 动效请不要引入任何 crate，测试与构建辅助依赖同样不许加。序列化与运行时能力放到消费方（app / app-iced / presenter）。"
+            exit 1
+          fi
+          echo "OK: crates/design/Cargo.toml 依赖表全空（含 dev / build）"
+      - name: 依赖树只允许出现自身（cargo tree -p unlucky-design --edges normal）
+        run: |
+          set -uo pipefail
+          if ! tree=$(cargo tree -p unlucky-design --edges normal --prefix none); then
+            echo "::error::cargo tree -p unlucky-design 执行失败 —— crate 是否仍叫 unlucky-design？"
+            exit 1
+          fi
+          echo "$tree"
+          # 空行不算，剩下的每一行都必须是自己：正常时整个输出只有一行
+          # `unlucky-design v0.1.0 (/path/to/crates/design)`。
+          lines=$(printf '%s\n' "$tree" | grep -cE '[^[:space:]]' || true)
+          others=$(printf '%s\n' "$tree" | grep -vE '^[[:space:]]*$' | grep -vE '^unlucky-design v' || true)
+          if [ -n "$others" ] || [ "$lines" -ne 1 ]; then
+            echo "::error file=crates/design/Cargo.toml::unlucky-design 必须零第三方依赖，本应只有自身一行，实际 $lines 行；越线的包："
+            printf '%s\n' "$others" | sed 's/^/  - /'
+            echo "::error::design 是纯数据 + 纯函数的设计令牌：色彩 / 排版 / 形状 / 高程 / 动效请不要引入 serde、rand、once_cell 等任何 crate。序列化与运行时能力放到消费方（app / app-iced / presenter）。"
+            exit 1
+          fi
+          echo "OK: unlucky-design 依赖树只有自身，零第三方依赖"
+
+  # D36 定案：整窗 α 是全仓**唯一**需要 `unsafe` 的能力（Win32 的
+  # `SetLayeredWindowAttributes` 没有安全替代），落点收在一个文件里。
+  # 判据必须是**集合相等**而不是「黑名单命中」：
+  #   - 新增第二个显式放行 unsafe 的文件 → 红（黑名单写法在这里会假绿）；
+  #   - 落点文件把放行删掉 / 改名 / 搬走 → 红（否则门禁守着一条已经不存在的路径）；
+  #   - 多行属性、同行合并属性、多行 `cfg_attr`、`expect(unsafe_code)` 都已覆盖
+  #     （r2 前的行级正则对前两种会假绿，当时只能靠 ci.yml 的 fmt job 兜底；r3 起由词法器直接抓）。
+  unsafe-scope:
+    name: unsafe 落点守门（集合必须恰好一个文件）
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: 全仓显式放行 unsafe 的文件集合 == 唯一落点
+        run: |
+          set -uo pipefail
+          EXPECTED='crates/app-iced/src/platform/win32/transparency.rs'
+          # 扫描口径（M91 r3）：一个小词法器，而不是正则。
+          #
+          # 为什么必须用词法器：r2 的写法是「按全文方括号净深度合并续行」，但 Rust 里
+          # `['[', '(']`、`"[2"`、`starts_with("[2")` 这类**不配对括号字面量**会让深度永久跑偏，
+          # 于是该文件后面的一切（包括一个真的 `#[allow(unsafe_code)]`）都再也不会被扫到——
+          # 实测本仓 601 个文件里有 10 个扫到 EOF 仍非 0，`gate.rs` 就是其中之一（r3 复审实证：
+          # 在它尾部加作用域 allow，r2 门禁 exit 0 假绿）。
+          # 现在的做法：逐字符状态机（普通 / 行注释 / 块注释（可嵌套）/ 字符串 / raw 字符串 /
+          # 字符字面量），只在「普通态」里认 `#` 或 `#!` 紧跟 `[` 的属性起点，然后只在这一个
+          # 属性内部累计到它的 `]` 配平——数组字面量跨行不再参与合并，也就不会带偏。
+          #
+          # 放行的两种拼法都算：`allow(...)` 与 `expect(...)`。`expect(unsafe_code)` 同样会
+          # 放行 unsafe 代码（rustc 实测：`#![expect(unsafe_code)]` + `pub unsafe fn f() {}` 在
+          # `-D unsafe_code` 下编译通过），所以它必须被同一条判据抓住，不能只认 allow。
+          #
+          # 仍然抓不住的（已知边界，别当全覆盖）：
+          #   - 落点文件**内部**多开别的 unsafe 能力（本门禁只看「有没有放行属性」，不看 unsafe 块个数）；
+          #   - **在别处定义、这里只调用**的宏展开出来的 allow：宏体里直接写出的属性在源码文本里，
+          #     会被扫到；但「宏定义在别的文件、调用点展开出 allow」时，本文件源码里没有那个属性；
+          #   - 注释（行注释/块注释）与字符串（普通/raw）里的属性文本**刻意不算**：它们不构成放行；
+          #     代价是「真把 allow 写进字符串」这种写法不会被当作落点（它也确实不放行任何代码）；
+          #   - manifest 侧 `[lints.rust] unsafe_code = "allow"`：本门禁只扫 `*.rs`，看不见 Cargo.toml；
+          #
+          # r4 回归用例（属性内的 raw string / 字符字面量曾经是盲区；现在两处共用 step()，
+          # 它们不再是边界，但下面五条必须一直保持红/绿正确 —— 改这段词法器前先跑它们）：
+          #   红  #[doc = r#"a "b"#]                                 后跟真 allow
+          #   红  #[cfg_attr(docsrs, doc = r##"a " b "##)]            后跟真 allow
+          #   红  #[cfg_attr(docsrs, my_macro(39 as char))] 一类含字符字面量/转义的属性后跟真 allow
+          #       具体形态：#![cfg_attr(docsrs, my_macro('\''))] 后跟真 allow
+          #   红  以上三者的 CRLF 版本
+          #   绿  #[doc = r#"x" allow(unsafe_code) is banned "y"#]（纯文档，不得误报）
+          scan() {
+            awk -v path="$1" '
+              # ---- 唯一的状态机：主循环与属性内**共用**同一个 step() ----
+              # 为什么必须复用：r2 是「属性外一套状态机、属性内另写一套」，两套各自演进，
+              # r3 的属性内就只剩「遇 " 跳到下一个 "」，于是 raw string / 字符字面量在属性内
+              # 完全不认识 —— `#[doc = r#"a "b"#]` 之后的一切对门禁失明（假绿），
+              # `#[doc = r#"x" allow(unsafe_code) "y"#]` 这种纯文档被误报（误红）。
+              # 现在两处只认这一个 step()，属性解析只多一层「[ ] 深度决定何时离开属性」。
+              #
+              # 状态：0 普通 / 1 行注释 / 2 块注释（可嵌套）/ 3 字符串 / 4 raw 字符串 / 5 字符字面量。
+              # 返回值 = 本次消费到的位置（`//`、`/*`、`r#"`、raw 收尾会一次吃掉多个字符）；
+              # g_plain=1 表示该位置处在「普通态代码」里（注释/字符串内容一律 0，
+              # 所以它们既不会被当成属性、也不会参与属性内的 [ ] 计数与文本匹配）。
+              function step(s, n, i,   c, nx, j, h, ok) {
+                c = substr(s, i, 1)
+                g_plain = 0
+                if (g_state == 1) { if (c == "\n") g_state = 0; return i }
+                if (g_state == 2) {
+                  if (c == "/" && substr(s, i + 1, 1) == "*") { g_depth++; return i + 1 }
+                  if (c == "*" && substr(s, i + 1, 1) == "/") { g_depth--; if (g_depth <= 0) g_state = 0; return i + 1 }
+                  return i
+                }
+                if (g_state == 3) {
+                  if (c == "\\") return i + 1
+                  if (c == "\"" || c == "\n") g_state = 0
+                  return i
+                }
+                if (g_state == 4) {
+                  if (c == "\"") {
+                    ok = 1
+                    for (j = 1; j <= g_hashes; j++) if (substr(s, i + j, 1) != "#") ok = 0
+                    if (ok) { g_state = 0; return i + g_hashes }
+                  }
+                  return i
+                }
+                if (g_state == 5) {
+                  if (c == "\\") return i + 1
+                  if (c == g_q || c == "\n") g_state = 0
+                  return i
+                }
+                if (c == "/" && substr(s, i + 1, 1) == "/") { g_state = 1; return i + 1 }
+                if (c == "/" && substr(s, i + 1, 1) == "*") { g_state = 2; g_depth = 1; return i + 1 }
+                if (c == "\"") { g_state = 3; return i }
+                if (c == g_q) {
+                  nx = substr(s, i + 1, 1)
+                  if (nx == "\\" || substr(s, i + 2, 1) == g_q) { g_state = 5; return i }
+                  g_plain = 1
+                  return i
+                }
+                if (c == "r" || c == "b") {
+                  j = i + 1
+                  if (c == "b") {
+                    if (substr(s, j, 1) == "\"") { g_state = 3; return j }
+                    if (substr(s, j, 1) == g_q) { g_state = 5; return j }
+                    if (substr(s, j, 1) != "r") { g_plain = 1; return i }
+                    j++
+                  }
+                  h = 0
+                  while (substr(s, j, 1) == "#") { h++; j++ }
+                  if (substr(s, j, 1) == "\"") { g_hashes = h; g_state = 4; return j }
+                  g_plain = 1
+                  return i
+                }
+                g_plain = 1
+                return i
+              }
+              function lex(   s, line, n, i, j, k, ch, adepth, attr) {
+                s = ""
+                while ((getline line < path) > 0) s = s line "\n"
+                close(path)
+                n = length(s)
+                g_state = 0; g_depth = 0; g_hashes = 0; g_found = 0
+                for (i = 1; i <= n; i++) {
+                  i = step(s, n, i)
+                  if (!g_plain || substr(s, i, 1) != "#") continue
+                  j = i + 1
+                  if (substr(s, j, 1) == "!") j++
+                  if (substr(s, j, 1) != "[") continue
+                  # 属性：**复用 step()**，只多一层「[ ] 深度决定何时离开属性」。
+                  # 属性里的字符串 / raw 字符串 / 字符字面量因此与属性外同一套识别。
+                  attr = ""; adepth = 0; k = j
+                  while (k <= n) {
+                    k = step(s, n, k)
+                    if (g_plain) {
+                      ch = substr(s, k, 1)
+                      if (ch == "[") adepth++
+                      else if (ch == "]") adepth--
+                      attr = attr ch
+                      if (adepth <= 0) break
+                    }
+                    k++
+                  }
+                  if (attr ~ /(allow|expect)\([^]]*unsafe_code/) g_found = 1
+                  i = k
+                }
+                return g_found
+              }
+              BEGIN { g_q = "\047"; g_found = 0; exit(lex() ? 0 : 1) }
+            '
+          }
+          # 只对「文本里出现过 unsafe_code」的文件跑词法器（标识符不可能被空白拆开，
+          # 所以这个预筛不会漏）。601 个文件 → 个位数个候选，整个 job 约 2 秒。
+          actual=$(git grep -l 'unsafe_code' -- '*.rs' 2>/dev/null | LC_ALL=C sort | while IFS= read -r f; do
+            if scan "$f"; then printf '%s\n' "$f"; fi
+          done | LC_ALL=C sort)
+          echo "期望（恰好这一个）：$EXPECTED"
+          echo "实际扫到的集合："
+          if [ -n "$actual" ]; then printf '%s\n' "$actual" | sed 's/^/  - /'; else echo "  （空）"; fi
+          if [ "$actual" != "$EXPECTED" ]; then
+            extra=$(printf '%s\n' "$actual" | grep -vxF "$EXPECTED" || true)
+            if [ -n "$extra" ]; then
+              echo "::error::多出来的 unsafe 落点（D36 只允许一个）："
+              printf '%s\n' "$extra" | sed 's/^/  - /'
+            fi
+            if ! printf '%s\n' "$actual" | grep -qxF "$EXPECTED"; then
+              echo "::error file=$EXPECTED::这个文件里没有显式放行 unsafe（allow / expect(unsafe_code)）—— 落点被搬走/改名/删了放行？守门路径已失效。"
+            fi
+            echo "::error::整窗 α 的 FFI 只允许住在 $EXPECTED（D36）。需要新的 unsafe 能力请先立 mission：改这条守门 + 更新 D36 的定案，不要顺手放行。"
+            exit 1
+          fi
+          echo "OK: 全仓显式放行 unsafe 的文件恰好只有 $EXPECTED"
+
+  file-size:
+    name: 文件行数 ≤400 守门
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: 检查单文件行数
+        run: |
+          set -uo pipefail
+          LIMIT=400
+          failed=0
+          while IFS= read -r f; do
+            case "$f" in
+              LICENSE|*/LICENSE|LICENSE-*|*/LICENSE-*) continue ;;
+              CHANGELOG*|*/CHANGELOG*) continue ;;
+              # README 是「对外介绍」，不是可拆分的模块：拆成多份反而更难读，用户令
+              # （2026-11-05）明确「不用 400 行红线压它，但要保证介绍不臃肿、逻辑完备」。
+              # 只豁免仓库根的 README*.md；docs/ 下的长文仍按模块拆分。
+              README.md|README.*.md) continue ;;
+            esac
+            n=$(wc -l < "$f")
+            if [ "$n" -gt "$LIMIT" ]; then
+              echo "::error file=$f::$f 有 $n 行，超过 $LIMIT 行上限，请按模块拆分"
+              failed=$((failed + 1))
+            fi
+          # 覆盖范围含脚本（*.py/*.sh）：packaging/ 下的构建辅助脚本同样受 400 行约束；
+          # Cargo.lock 等机器生成文件刻意不在列（否则一生成就超限）
+          done < <(git ls-files '*.rs' '*.md' '*.slint' '*.yml' '*.yaml' '*.toml' '*.json' '*.py' '*.sh')
+          if [ "$failed" -ne 0 ]; then
+            echo "共 $failed 个文件超限"
+            exit 1
+          fi
+          echo "OK: 全部受检文件 ≤$LIMIT 行"
+
+  licenses:
+    name: 依赖许可与来源（cargo-deny）
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: EmbarkStudios/cargo-deny-action@v2
+        with:
+          # 只跑许可/禁用/来源三类，advisories 由后续安全轮次单独接管
+          # M118：cargo-deny 走 **workspace 依赖图**，`crates/app` 被 exclude 后 Slint 那棵树不再进图
+          # （实测 `cargo deny list` 里 `slint*` / `i-slint-*` 命中 0 个），所以本门禁不再审 Slint 的
+          # RF-2.0 许可 —— 与「它不再随任何产物发布」一致。这不是回退：`deny.toml` 里为 Slint 留的
+          # allow 条目**故意没删**（删它得先确认没有别的路径重新引入），当前等于一条死条目。
+          # 若将来把 `crates/app` 加回 workspace，本门禁的覆盖会自动恢复。
+          command: check licenses bans sources
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 0000000..43ea686
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,369 @@
+name: Release
+
+# 发布流水线：tag `v*` → 四平台（六槽位）矩阵构建 → 单文件产物 + SHA256SUMS
+# → 上传 artifact + 创建 GitHub Release（pre-release 默认开）。同一 tag 重跑幂等：
+# Release 已存在时覆盖资产与说明，不再 `gh release create`（见 release job 末步）；
+# 重跑**不碰** pre-release 标记，该标记只在 `inputs.prerelease` 显式给出时才被断言。
+#
+# 契约唯一真相源：packaging/README.md（命名/目录/运行时依赖）。
+# 打包本体在 packaging/make_artifacts.py（本地与 CI 同一份脚本，逐字节同布局）。
+# 手动触发（workflow_dispatch）默认只跑构建不建 Release —— 用来验证矩阵仍然编得过。
+# 注意 `inputs.prerelease` 只在 **tag ref** 上 dispatch 才可达：Actions 页面的
+# "Run workflow" 只能选分支，要跑 tag 得 `gh workflow run release.yml --ref v0.1.0`。
+# 分支 ref 的 dispatch 与 push 事件一样被 release job 的 `if: github.ref_type == 'tag'`
+# 挡在发布之外，所以「dispatch 只构建不发布」与「dispatch 可关 pre-release」并不矛盾。
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      prerelease:
+        description: "标记为 pre-release（仅在 tag ref 上 dispatch 时才生效）"
+        type: boolean
+        default: true
+
+env:
+  CARGO_TERM_COLOR: always
+  RUST_BACKTRACE: 1
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: build (${{ matrix.slot }})
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Windows x64：MSVC + 静态 CRT（+crt-static）→ exe 不依赖 VC++ 可再发行包，
+          # 双击即用的单文件形态；UCRT 本身就是 Win10+ 的系统组件。
+          # 产物根 target/release；自检与打包都从 matrix.build_dir 取路径（不硬编码）。
+          - slot: windows-x64
+            os: windows-latest
+            build_dir: target/release
+            rustflags: -C target-feature=+crt-static
+          # Windows arm64：在 windows-latest（x64 宿主）上**交叉编译**到 aarch64-pc-windows-msvc。
+          # 为什么不用 windows-11-arm 原生 runner（GitHub 文档 2026 已把 `windows-11-arm` 与
+          # `windows-11-vs2026-arm` 列为公开仓库**免费**的标准 arm64 runner，原生路线可行）：
+          #   ① 双 Windows 槽位共用同一套已验证镜像/工具链，tag 重跑行为与既有槽位一致；
+          #   ② M50 的 dumpbin 定位链取的是 `Hostx64/x64/dumpbin.exe`，dumpbin 读 ARM64 PE 的
+          #      导入表没问题，而原生 ARM 宿主上那条链得再长一条 `Hostarm64/arm64` 分支——为一个
+          #      槽位放宽刚立的门禁不值得；
+          #   ③ 交叉编译产物路径变成 target/<triple>/release，已用 matrix.build_dir 参数化。
+          # 若将来改成原生：只需把 os 换成 windows-11-arm、删掉 target/rustflags 依赖并给 dumpbin
+          # 定位链补 Hostarm64 分支（届时再评估，不在这里预先放宽）。
+          - slot: windows-arm64
+            os: windows-latest
+            target: aarch64-pc-windows-msvc
+            build_dir: target/aarch64-pc-windows-msvc/release
+            rustflags: -C target-feature=+crt-static
+          # Linux：固定 ubuntu-22.04（glibc 2.35 地板）而不是 latest，
+          # 否则产物的 glibc 底线会跟着 runner 漂移（24.04 的 glibc 明显更高）。
+          - slot: linux-x64
+            os: ubuntu-22.04
+            build_dir: target/release
+          # Linux arm64：公开仓库免费的原生 ARM64 runner（原生构建，不做交叉）。
+          # 用 `ubuntu-22.04-arm` 而**不是** 24.04：与 x64 同 glibc 地板（2.35），
+          # 覆盖 Debian 12 / Ubuntu 22.04 arm64 / Raspberry Pi OS Bookworm（2.36）这类实际在跑的
+          # ARM 发行版；换 24.04 会把地板抬高、把上面前两个挡在门外。该家族标签有
+          # `ubuntu-22.04-arm` / `ubuntu-24.04-arm` / `ubuntu-26.04-arm`，均 4C/16GB、
+          # 公开仓库免费不限量（GitHub 文档 Standard runners for public repositories）。
+          - slot: linux-arm64
+            os: ubuntu-22.04-arm
+            build_dir: target/release
+          # macOS：latest = arm64；Intel x64 用 macos-15-intel（macos-13 已下线）。
+          - slot: macos-arm64
+            os: macos-latest
+            build_dir: target/release
+          - slot: macos-x64
+            os: macos-15-intel
+            build_dir: target/release
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Linux 图形栈构建依赖（winit / femtovg 编译期需要）
+        if: runner.os == 'Linux'
+        shell: bash
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            libxkbcommon-dev libfontconfig1-dev libgl1-mesa-dev libegl1-mesa-dev \
+            libwayland-dev libxcb1-dev
+
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+
+      # 只有交叉编译槽位需要额外 target（原生槽位留空 → 本步整体跳过）。
+      # 不把 `${{ }}` 直接拼进 bash：与后面的打包步骤同一纪律，一律经 env 传入再展开。
+      - name: 追加交叉编译目标 ${{ matrix.target }}
+        if: matrix.target != ''
+        shell: bash
+        env:
+          TARGET: ${{ matrix.target }}
+        run: rustup target add "$TARGET"
+
+      # 交叉链接的前提是镜像里真有 ARM64 的 MSVC 库（VC `/lib/arm64/libcmt.lib`，+crt-static
+      # 就靠它）与 Windows SDK 的 ARM64 导入库（`um/arm64/kernel32.lib`）。缺了照样是失败，
+      # 但先给一句能照做的话，而不是让链接器吐一屏乱码才发现方向：门禁不降级，只把失败说清楚。
+      - name: Windows ARM64 交叉工具链体检
+        if: matrix.target == 'aarch64-pc-windows-msvc'
+        shell: bash
+        run: |
+          set -euo pipefail
+          roots=("C:/Program Files/Microsoft Visual Studio" "C:/Program Files (x86)/Microsoft Visual Studio")
+          vc_lib=$(find "${roots[@]}" -maxdepth 11 -type f -path '*/VC/Tools/MSVC/*/lib/arm64/libcmt.lib' 2>/dev/null | head -n1 || true)
+          sdk_version=$(ls -d "C:/Program Files (x86)/Windows Kits/10/Lib"/* 2>/dev/null | tail -n1 || true)
+          sdk_lib=""
+          if [ -n "$sdk_version" ]; then
+            sdk_lib=$(find "$sdk_version/um/arm64" -maxdepth 1 -name 'kernel32.lib' 2>/dev/null | head -n1 || true)
+          fi
+          echo "MSVC ARM64 静态 CRT:  ${vc_lib:-<缺失>}"
+          echo "SDK ARM64 导入库:     ${sdk_lib:-<缺失>}"
+          if [ -z "$vc_lib" ] || [ -z "$sdk_lib" ]; then
+            echo "::error::交叉链接缺 ARM64 库：给 VS 加上 Microsoft.VisualStudio.Component.VC.Tools.ARM64（含 ARM64 Windows SDK），或把该槽位改用原生 windows-11-arm runner"
+            exit 1
+          fi
+
+      # M118（D26）：**Slint 版停发**。旧写法 `--bin unlucky-launcher` 打的是 `crates/app`
+      # （Slint 退役树）的 bin —— 也就是说这条流水线一直在发 Slint 版二进制，而 D26 早已把
+      # iced 定为产品 UI。现在 GUI 来源只有 `unlucky-launcher-iced`；`crates/app` 也已在根
+      # Cargo.toml 被 `exclude`，不参与任何 workspace 构建（它连 `--manifest-path` 都编不了）。
+      # 对外产物名由 `packaging/make_artifacts.py` 的 `asset_stem()` 统一生成，格式是
+      # `<名字>_<版本号>_<平台>_<架构>`（用户令 2026-11-05）：下划线分段，且**不带实现细节
+      # 字样**（产物名里不出现 `iced`）。`LAUNCHER_BIN` 只用来在构建产物里找文件。
+      - name: cargo build --release --locked
+        shell: bash
+        env:
+          RUSTFLAGS: ${{ matrix.rustflags }}
+          TARGET: ${{ matrix.target }}
+        run: |
+          set -euo pipefail
+          target_args=()
+          if [ -n "$TARGET" ]; then
+            target_args+=(--target "$TARGET")
+          fi
+          cargo build --release --locked "${target_args[@]}" --bin unlucky-launcher-iced --bin ull
+
+      - name: Windows 单文件自检（导入表不得出现 VC++ 可再发行 DLL）
+        if: runner.os == 'Windows'
+        shell: bash
+        env:
+          # 跨槽位的关键点：产物在 target/<triple>/release 而不是 target/release。
+          # M118：校验的是**构建产物**（iced bin 的原始文件名）。对外名 `unlucky-launcher`
+          # 由 packaging/make_artifacts.py 在落盘时才换上，那一步之后才存在。
+          EXE: ${{ matrix.build_dir }}/unlucky-launcher-iced.exe
+        run: |
+          set -euo pipefail
+          # +crt-static 是否真的生效，只看导入表：出现 VCRUNTIME/MSVCP/msvcr/ucrtbase 说明还得装
+          # 可再发行包，那就不是"单文件"了，直接 fail。
+          #
+          # dumpbin 定位链（三级，全不命中才 fail —— 门禁不降级，只是把"猜路径"换成官方定位）：
+          #   ① vswhere：VS 官方定位器，安装器自身路径固定，与 VS 版本/版次/安装布局无关；
+          #   ② find 兜底：Program Files 与 Program Files (x86) 两个 VS 根都扫（Build Tools 落在 x86 根）；
+          #   ③ PATH：镜像若已把工具链预置进 PATH 则直接可用。
+          # PATH 排最后是刻意的：PATH 最不可控，官方定位器优先。
+          # Hostx64 的 dumpbin 读 ARM64 PE 的导入表没问题，所以 arm64 槽位共用同一条链。
+          VSWHERE="C:/Program Files (x86)/Microsoft Visual Studio/Installer/vswhere.exe"
+          DUMPBIN=""
+          VIA=""
+          if [ -x "$VSWHERE" ]; then
+            # -find 的模式优先用反斜杠（vswhere 官方文档即此形式），再试正斜杠以规避分隔符差异。
+            for pattern in 'VC\Tools\MSVC\*\bin\Hostx64\x64\dumpbin.exe' \
+                           'VC/Tools/MSVC/*/bin/Hostx64/x64/dumpbin.exe'; do
+              hit=$("$VSWHERE" -latest -products '*' -find "$pattern" 2>/dev/null | head -n1 || true)
+              if [ -n "$hit" ]; then
+                DUMPBIN=${hit//\\//}
+                VIA="vswhere"
+                break
+              fi
+            done
+          fi
+          if [ -z "$DUMPBIN" ]; then
+            # 镜像里的 VS 根形如 <年>/<版次>（2022/Enterprise、2022/BuildTools……），
+            # 固定层数的 glob 会在 <年>/<版次> 这两级踩空，所以按路径模式扫。
+            for root in "C:/Program Files/Microsoft Visual Studio" \
+                        "C:/Program Files (x86)/Microsoft Visual Studio"; do
+              [ -d "$root" ] || continue
+              hit=$(find "$root" -maxdepth 11 -type f \
+                      -path '*/VC/Tools/MSVC/*/bin/Hostx64/x64/dumpbin.exe' 2>/dev/null | head -n1 || true)
+              if [ -n "$hit" ]; then
+                DUMPBIN=$hit
+                VIA="find: $root"
+                break
+              fi
+            done
+          fi
+          if [ -z "$DUMPBIN" ]; then
+            hit=$(command -v dumpbin || true)
+            if [ -n "$hit" ]; then
+              DUMPBIN=$hit
+              VIA="PATH"
+            fi
+          fi
+          # 工具缺失同样 fail：windows-latest 自带 VS 工具链，基本找得到；
+          # "找不到就跳过"等于让这道门禁在最需要它的时候静默失效。
+          if [ -z "$DUMPBIN" ]; then
+            echo "::error::找不到 dumpbin，无法校验导入表（静态 CRT 门禁不降级）"
+            exit 1
+          fi
+          echo "dumpbin: $DUMPBIN（定位自 $VIA）"
+          ls -l "$EXE"
+          "$DUMPBIN" -nologo -dependents "$EXE" | tee dependents.txt
+          if grep -Eiq 'VCRUNTIME|MSVCP|MSVCR|ucrtbase\.dll' dependents.txt; then
+            echo "::error::静态 CRT 未生效：exe 仍动态依赖 VC++ 可再发行包"
+            exit 1
+          fi
+
+      - name: 打包（产物 + SHA256SUMS）
+        shell: bash
+        env:
+          # 不把 `${{ }}` 直接拼进 bash 脚本：git ref 名允许 `$`/反引号/`"`，一律经 env 传入再展开。
+          REF_TYPE: ${{ github.ref_type }}
+          TAG: ${{ github.ref_name }}
+          SLOT: ${{ matrix.slot }}
+          BUILD_DIR: ${{ matrix.build_dir }}
+        run: |
+          set -euo pipefail
+          # git-bash 与 Linux/macOS runner 的 python 入口名不一致，先探一遍。
+          PY=$(command -v python3 || command -v python)
+          # 槽位与产物根都从矩阵来：交叉槽位的二进制不在 target/release，脚本据此定位
+          # 并回读可执行文件头校验架构（宿主 x64 ≠ 产物 arm64 时冒烟自动跳过，只等 CI 真机）。
+          args=(--slot "$SLOT" --build-dir "$BUILD_DIR")
+          if [ "$REF_TYPE" = "tag" ]; then
+            args+=(--version "$TAG")   # 与 Cargo.toml 版本交叉校验
+          fi
+          "$PY" packaging/make_artifacts.py "${args[@]}" --out dist
+          ls -l dist
+
+      - name: 归档内容自检（二进制定位 + 合规文本）
+        shell: bash
+        run: |
+          set -euo pipefail
+          for archive in dist/*.tar.gz; do
+            [ -e "$archive" ] || continue
+            listing=$(tar -tzf "$archive")
+            for required in unlucky-launcher LICENSE NOTICE README.md; do
+              if ! grep -q "/$required$" <<<"$listing"; then
+                echo "::error file=$archive::$archive 缺少 $required"
+                exit 1
+              fi
+            done
+            echo "OK: $archive 含二进制与 LICENSE/NOTICE/README.md"
+          done
+          if ls dist/*.exe >/dev/null 2>&1; then
+            echo "Windows 单 exe 形态：LICENSE/NOTICE/README.md 作为 Release 资产并列分发"
+          fi
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist-${{ matrix.slot }}
+          path: dist
+          if-no-files-found: error
+          retention-days: 14
+
+  release:
+    name: GitHub Release
+    needs: build
+    if: github.ref_type == 'tag'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+
+      - name: 矩阵完整性 + 重算全量 SHA256SUMS
+        shell: bash
+        run: |
+          set -euo pipefail
+          ls -l dist
+          # 六槽位全齐才发版：缺任意一个就 fail（宁可不出 Release，也不出少一档的 Release）。
+          # 每个槽位都要 GUI 与 CLI 两个资产——只按「槽位名出现过」判会被其中一个掩盖。
+          for slot in windows-x64 windows-arm64 linux-x64 linux-arm64 macos-arm64 macos-x64; do
+            for prefix in unlucky-launcher ull; do
+              if ! compgen -G "dist/$prefix-*-$slot*" >/dev/null; then
+                echo "::error::矩阵缺产物：$prefix / $slot"
+                exit 1
+              fi
+            done
+          done
+          # 各平台任务各写一份 SHA256SUMS.txt，合并后只有一份是真的 —— 在 Release 侧重算。
+          # GUI 与 CLI 都要进清单：漏了 ull 就是「发了但没有校验和」。
+          cd dist
+          rm -f SHA256SUMS.txt
+          sha256sum unlucky-launcher_* ull_* > SHA256SUMS.txt
+          sha256sum -c SHA256SUMS.txt
+          cat SHA256SUMS.txt
+
+      - name: 生成 Release 说明（支持矩阵模板）
+        shell: bash
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          python3 - <<'PY'
+          import os, pathlib
+          version = os.environ["TAG"].lstrip("v")
+          template = pathlib.Path("packaging/release-notes.md").read_text(encoding="utf-8")
+          sums = pathlib.Path("dist/SHA256SUMS.txt").read_text(encoding="utf-8").strip()
+          body = template.replace("{{VERSION}}", version).replace("{{SUMS}}", sums)
+          pathlib.Path("release-body.md").write_text(body, encoding="utf-8", newline="\n")
+          print(body[:400])
+          PY
+
+      - name: 创建或更新 GitHub Release（同 tag 重跑幂等）
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ github.ref_name }}
+          PRERELEASE: ${{ inputs.prerelease }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          base_flags=(--title "Unlucky Launcher $TAG" --notes-file release-body.md)
+          # pre-release 标记只在**显式要求**时才断言：
+          #   PRERELEASE=true / false —— 来自 tag ref 上的 workflow_dispatch 输入；
+          #   PRERELEASE 空        —— push 触发的运行或它的 Re-run，此时**不碰**该标记，
+          #                           否则会把用户手动提升为 stable 的 Release 静默翻回 pre-release。
+          # 首次创建（create）仍保持「pre-release 默认开」的老契约：空值按 true 处理。
+          create_mark=()
+          edit_mark=()
+          case "${PRERELEASE:-}" in
+            true)
+              create_mark=(--prerelease)
+              edit_mark=(--prerelease)
+              ;;
+            false)
+              edit_mark=(--prerelease=false)
+              ;;
+            "")
+              create_mark=(--prerelease)
+              ;;
+            *)
+              echo "::error::非预期的 inputs.prerelease 取值：$PRERELEASE"
+              exit 1
+              ;;
+          esac
+          # Windows 单 exe 装不下 LICENSE/NOTICE/README.md，这三份与产物并列挂到 Release 上，
+          # 保证每个下载平台的许可条款都随包分发。
+          # `ull` 是独立资产（不在 tar.gz 里）：headless 用户下一个小文件直接跑，不用解档。
+          assets=(dist/unlucky-launcher_* dist/ull_* dist/SHA256SUMS.txt LICENSE NOTICE README.md)
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            # 同 tag 重跑（补丁 / 重编）：Release 已存在 → 覆盖资产 + 刷新说明，
+            # 不再 `create`（那会因已存在而失败，把整条流水线在最后一步染红）。
+            gh release upload "$TAG" "${assets[@]}" --clobber
+            gh release edit "$TAG" "${base_flags[@]}" "${edit_mark[@]}"
+          else
+            gh release create "$TAG" "${assets[@]}" "${base_flags[@]}" "${create_mark[@]}"
+          fi
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..7143e9e
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,28 @@
+# Reference source repositories (local-only, git-ignored)
+/HMCL/
+/PCL/
+
+# Local development docs
+/DevDocs/
+
+# Local acceptance screenshots (screenshot channel output, never committed)
+/.screens/
+/.tmp-screens/
+
+# Agent workspace (local-only)
+/.tower/
+
+# Build outputs
+build/
+dist/
+out/
+target/
+
+# IDE
+.idea/
+.vscode/
+*.iml
+
+# OS
+Thumbs.db
+.DS_Store
diff --git a/.rustfmt.toml b/.rustfmt.toml
new file mode 100644
index 0000000..bdb5303
--- /dev/null
+++ b/.rustfmt.toml
@@ -0,0 +1,5 @@
+edition = "2021"
+max_width = 100
+newline_style = "Unix"
+use_field_init_shorthand = true
+use_try_shorthand = true
diff --git a/Cargo.lock b/Cargo.lock
new file mode 100644
index 0000000..fd7c9e4
--- /dev/null
+++ b/Cargo.lock
@@ -0,0 +1,6343 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "ab_glyph"
+version = "0.2.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "01c0457472c38ea5bd1c3b5ada5e368271cb550be7a4ca4a0b4634e9913f6cc2"
+dependencies = [
+ "ab_glyph_rasterizer",
+ "owned_ttf_parser",
+]
+
+[[package]]
+name = "ab_glyph_rasterizer"
+version = "0.1.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "366ffbaa4442f4684d91e2cd7c5ea7c4ed8add41959a31447066e279e432b618"
+
+[[package]]
+name = "adler2"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
+
+[[package]]
+name = "ahash"
+version = "0.8.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a15f179cd60c4584b8a8c596927aadc462e27f2ca70c04e0071964a73ba7a75"
+dependencies = [
+ "cfg-if",
+ "getrandom 0.3.4",
+ "once_cell",
+ "version_check",
+ "zerocopy",
+]
+
+[[package]]
+name = "aho-corasick"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "android-activity"
+version = "0.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0f2a1bb052857d5dd49572219344a7332b31b76405648eabac5bc68978251bcd"
+dependencies = [
+ "android-properties",
+ "bitflags 2.13.2",
+ "cc",
+ "jni",
+ "libc",
+ "log",
+ "ndk",
+ "ndk-context",
+ "ndk-sys",
+ "num_enum",
+ "thiserror 2.0.21",
+]
+
+[[package]]
+name = "android-build"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f9fc9904ad2ad097c3c1cfe2eacaaf0fc24710936fa9ed941cb310b7c6ed2ab7"
+dependencies = [
+ "windows-sys 0.52.0",
+]
+
+[[package]]
+name = "android-properties"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc7eb209b1518d6bb87b283c20095f5228ecda460da70b44f0802523dea6da04"
+
+[[package]]
+name = "android_system_properties"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae221649c9976a6f6c56ae1facf410f3ddb33cc661c4b7b61020a912d4237fbc"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "arrayref"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "76a2e8124351fda1ef8aaaa3bbd7ebbcb486bbcd4225aca0aa0d84bb2db8fecb"
+
+[[package]]
+name = "arrayvec"
+version = "0.7.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3fb67a6e08acf24fdeccbac2cb6ac4305825bd1f117462e0e6f2f193345ad56"
+
+[[package]]
+name = "as-raw-xcb-connection"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "175571dd1d178ced59193a6fc02dde1b972eb0bc56c892cde9beeceac5bf0f6b"
+
+[[package]]
+name = "ash"
+version = "0.38.0+1.3.281"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0bb44936d800fea8f016d7f2311c6a4f97aebd5dc86f09906139ec848cf3a46f"
+dependencies = [
+ "libloading",
+]
+
+[[package]]
+name = "async-broadcast"
+version = "0.7.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "435a87a52755b8f27fcf321ac4f04b2802e337c8c4872923137471ec39c37532"
+dependencies = [
+ "event-listener",
+ "event-listener-strategy",
+ "futures-core",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "async-channel"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "924ed96dd52d1b75e9c1a3e6275715fd320f5f9439fb5a4a11fa51f4221158d2"
+dependencies = [
+ "concurrent-queue",
+ "event-listener-strategy",
+ "futures-core",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "async-executor"
+version = "1.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c96bf972d85afc50bf5ab8fe2d54d1586b4e0b46c97c50a0c9e71e2f7bcd812a"
+dependencies = [
+ "async-task",
+ "concurrent-queue",
+ "fastrand",
+ "futures-lite",
+ "pin-project-lite",
+ "slab",
+]
+
+[[package]]
+name = "async-io"
+version = "2.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "456b8a8feb6f42d237746d4b3e9a178494627745c3c56c6ea55d92ba50d026fc"
+dependencies = [
+ "autocfg",
+ "cfg-if",
+ "concurrent-queue",
+ "futures-io",
+ "futures-lite",
+ "parking",
+ "polling",
+ "rustix 1.1.6",
+ "slab",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "async-lock"
+version = "3.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "290f7f2596bd5b78a9fec8088ccd89180d7f9f55b94b0576823bbbdc72ee8311"
+dependencies = [
+ "event-listener",
+ "event-listener-strategy",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "async-process"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc50921ec0055cdd8a16de48773bfeec5c972598674347252c0399676be7da75"
+dependencies = [
+ "async-channel",
+ "async-io",
+ "async-lock",
+ "async-signal",
+ "async-task",
+ "blocking",
+ "cfg-if",
+ "event-listener",
+ "futures-lite",
+ "rustix 1.1.6",
+]
+
+[[package]]
+name = "async-recursion"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4f8abc12baad266b1c8cec146854c195b5864b4221d4b2ca7296a7ae82d9e451"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.9",
+]
+
+[[package]]
+name = "async-signal"
+version = "0.2.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52b5aaafa020cf5053a01f2a60e8ff5dccf550f0f77ec54a4e47285ac2bab485"
+dependencies = [
+ "async-io",
+ "async-lock",
+ "atomic-waker",
+ "cfg-if",
+ "futures-core",
+ "futures-io",
+ "rustix 1.1.6",
+ "signal-hook-registry",
+ "slab",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "async-stream"
+version = "0.3.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b5a71a6f37880a80d1d7f19efd781e4b5de42c88f0722cc13bcb6cc2cfe8476"
+dependencies = [
+ "async-stream-impl",
+ "futures-core",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "async-stream-impl"
+version = "0.3.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c7c24de15d275a1ecfd47a380fb4d5ec9bfe0933f309ed5e705b775596a3574d"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "async-task"
+version = "4.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b75356056920673b02621b35afd0f7dda9306d03c79a30f5c56c44cf256e3de"
+
+[[package]]
+name = "async-trait"
+version = "0.1.92"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "82f6aeea286b8eb4dd3431a1be1b59d290ace00f5bfd8e2a159bc2a05e2c1667"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.9",
+]
+
+[[package]]
+name = "atomic-waker"
+version = "1.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1505bd5d3d116872e7271a6d4e16d81d0c8570876c8de68093a09ac269d8aac0"
+
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
+[[package]]
+name = "aws-lc-rs"
+version = "1.19.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "048006790404103c488e6c5616b3e7e702a71292aadda08e8f7698a9e0d2eb53"
+dependencies = [
+ "aws-lc-sys",
+ "zeroize",
+]
+
+[[package]]
+name = "aws-lc-sys"
+version = "0.47.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8bfbe32ac36b3c428696ce315464181bc4029d689fd58e3f2a4e58c252242f52"
+dependencies = [
+ "cc",
+ "cmake",
+ "dunce",
+ "fs_extra",
+ "pkg-config",
+]
+
+[[package]]
+name = "axum"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "31b698c5f9a010f6573133b09e0de5408834d0c82f8d7475a89fc1867a71cd90"
+dependencies = [
+ "axum-core",
+ "bytes",
+ "form_urlencoded",
+ "futures-util",
+ "http",
+ "http-body",
+ "http-body-util",
+ "hyper",
+ "hyper-util",
+ "itoa",
+ "matchit",
+ "memchr",
+ "mime",
+ "percent-encoding",
+ "pin-project-lite",
+ "serde_core",
+ "serde_json",
+ "serde_path_to_error",
+ "serde_urlencoded",
+ "sync_wrapper",
+ "tokio",
+ "tower",
+ "tower-layer",
+ "tower-service",
+ "tracing",
+]
+
+[[package]]
+name = "axum-core"
+version = "0.5.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "08c78f31d7b1291f7ee735c1c6780ccde7785daae9a9206026862dab7d8792d1"
+dependencies = [
+ "bytes",
+ "futures-core",
+ "http",
+ "http-body",
+ "http-body-util",
+ "mime",
+ "pin-project-lite",
+ "sync_wrapper",
+ "tower-layer",
+ "tower-service",
+ "tracing",
+]
+
+[[package]]
+name = "base64"
+version = "0.22.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
+
+[[package]]
+name = "base64"
+version = "0.23.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac07cdecf99051d9a5238b80f35af32cdeba5b336e55d957b318b50137e18da5"
+
+[[package]]
+name = "bit-set"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "08807e080ed7f9d5433fa9b275196cfc35414f66a0c79d864dc51a0d825231a3"
+dependencies = [
+ "bit-vec",
+]
+
+[[package]]
+name = "bit-vec"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5e764a1d40d510daf35e07be9eb06e75770908c27d411ee6c92109c9840eaaf7"
+
+[[package]]
+name = "bitflags"
+version = "1.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a"
+
+[[package]]
+name = "bitflags"
+version = "2.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06"
+
+[[package]]
+name = "block"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0d8c1fef690941d3e7788d328517591fecc684c084084702d6ff1641e993699a"
+
+[[package]]
+name = "block-buffer"
+version = "0.10.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71"
+dependencies = [
+ "generic-array",
+]
+
+[[package]]
+name = "block2"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2c132eebf10f5cad5289222520a4a058514204aed6d791f1cf4fe8088b82d15f"
+dependencies = [
+ "objc2 0.5.3",
+]
+
+[[package]]
+name = "block2"
+version = "0.6.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cdeb9d870516001442e364c5220d3574d2da8dc765554b4a617230d33fa58ef5"
+dependencies = [
+ "objc2 0.6.5",
+]
+
+[[package]]
+name = "blocking"
+version = "1.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a70e4329df6cb94385eed412ec92375c3cdd8a6e502493d1229b6414e4036dfa"
+dependencies = [
+ "async-channel",
+ "async-task",
+ "futures-io",
+ "futures-lite",
+ "piper",
+]
+
+[[package]]
+name = "bumpalo"
+version = "3.20.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
+
+[[package]]
+name = "bytemuck"
+version = "1.25.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "95832e849adfb21180ccb6826a99da14e5d266ae5c2e668e1602cf234f153797"
+dependencies = [
+ "bytemuck_derive",
+]
+
+[[package]]
+name = "bytemuck_derive"
+version = "1.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6a1f896587b6f2c069c73d2f0913e2d590c3990285cd2f0b6aa02b786b4c679c"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.9",
+]
+
+[[package]]
+name = "byteorder-lite"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f1fe948ff07f4bd06c30984e69f5b4899c516a3ef74f34df92a2df2ab535495"
+
+[[package]]
+name = "bytes"
+version = "1.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
+
+[[package]]
+name = "calloop"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b99da2f8558ca23c71f4fd15dc57c906239752dd27ff3c00a1d56b685b7cbfec"
+dependencies = [
+ "bitflags 2.13.2",
+ "log",
+ "polling",
+ "rustix 0.38.44",
+ "slab",
+ "thiserror 1.0.69",
+]
+
+[[package]]
+name = "calloop"
+version = "0.14.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "43b32313e937c8721c9d17ee9bf60699a6402b4b7c2cb6ac1bee0ffcaa4b4e5e"
+dependencies = [
+ "bitflags 2.13.2",
+ "polling",
+ "rustix 1.1.6",
+ "tracing",
+]
+
+[[package]]
+name = "calloop-wayland-source"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "95a66a987056935f7efce4ab5668920b5d0dac4a7c99991a67395f13702ddd20"
+dependencies = [
+ "calloop 0.13.0",
+ "rustix 0.38.44",
+ "wayland-backend",
+ "wayland-client",
+]
+
+[[package]]
+name = "calloop-wayland-source"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "138efcf0940a02ebf0cc8d1eff41a1682a46b431630f4c52450d6265876021fa"
+dependencies = [
+ "calloop 0.14.5",
+ "rustix 1.1.6",
+ "wayland-backend",
+ "wayland-client",
+]
+
+[[package]]
+name = "cc"
+version = "1.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "86e055fa6e3e40ad6187ba25b6855eeb635d5271f8e0f0e1e9a5826b8d75bea0"
+dependencies = [
+ "find-msvc-tools",
+ "jobserver",
+ "libc",
+ "shlex",
+]
+
+[[package]]
+name = "cfg-if"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
+
+[[package]]
+name = "cfg_aliases"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f079e83a288787bcd14a6aea84cee5c87a67c5a3e660c30f557a3d24761b3527"
+
+[[package]]
+name = "chacha20"
+version = "0.10.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "65c35e4b699c7e15ccbe7ee35c005e4fc0a278d22238a2857e6ce2dadeda1b06"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.3.1",
+ "rand_core 0.10.1",
+]
+
+[[package]]
+name = "chrono"
+version = "0.4.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1aa79e62e7697b8e29b513a68abacf485adcd1fe8284a4316c5ae868e6633327"
+dependencies = [
+ "iana-time-zone",
+ "num-traits",
+ "serde",
+ "windows-link",
+]
+
+[[package]]
+name = "clipboard-win"
+version = "5.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "052af7878466feccda12ba7a6a67d019d712f296809559b47c12c8cc196d3a9a"
+dependencies = [
+ "error-code",
+]
+
+[[package]]
+name = "clipboard_macos"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b7f4aaa047ba3c3630b080bb9860894732ff23e2aee290a418909aa6d5df38f"
+dependencies = [
+ "objc2 0.5.3",
+ "objc2-app-kit 0.2.2",
+ "objc2-foundation 0.2.2",
+]
+
+[[package]]
+name = "clipboard_wayland"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "003f886bc4e2987729d10c1db3424e7f80809f3fc22dbc16c685738887cb37b8"
+dependencies = [
+ "smithay-clipboard",
+]
+
+[[package]]
+name = "clipboard_x11"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bd63e33452ffdafd39924c4f05a5dd1e94db646c779c6bd59148a3d95fff5ad4"
+dependencies = [
+ "thiserror 2.0.21",
+ "x11rb",
+]
+
+[[package]]
+name = "cmake"
+version = "0.1.58"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c0f78a02292a74a88ac736019ab962ece0bc380e3f977bf72e376c5d78ff0678"
+dependencies = [
+ "cc",
+]
+
+[[package]]
+name = "codespan-reporting"
+version = "0.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fe6d2e5af09e8c8ad56c969f2157a3d4238cebc7c55f0a517728c38f7b200f81"
+dependencies = [
+ "serde",
+ "termcolor",
+ "unicode-width",
+]
+
+[[package]]
+name = "color_quant"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d7b894f5411737b7867f4827955924d7c254fc9f4d91a6aad6b097804b1018b"
+
+[[package]]
+name = "combine"
+version = "4.6.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4356eba6976435498d05a311ee9fc486da3bc81c200d3f0d7dd9703b41913f92"
+dependencies = [
+ "bytes",
+ "memchr",
+]
+
+[[package]]
+name = "concurrent-queue"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4ca0197aee26d1ae37445ee532fefce43251d24cc7c166799f4d46817f1d3973"
+dependencies = [
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "convert_case"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "affbf0190ed2caf063e3def54ff444b449371d55c58e513a95ab98eca50adb49"
+dependencies = [
+ "unicode-segmentation",
+]
+
+[[package]]
+name = "core-foundation"
+version = "0.9.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "91e195e091a93c46f7102ec7818a2aa394e1e1771c3ab4825963fa03e45afb8f"
+dependencies = [
+ "core-foundation-sys",
+ "libc",
+]
+
+[[package]]
+name = "core-foundation"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b2a6cd9ae233e7f62ba4e9353e81a88df7fc8a5987b8d445b4d90c879bd156f6"
+dependencies = [
+ "core-foundation-sys",
+ "libc",
+]
+
+[[package]]
+name = "core-foundation-sys"
+version = "0.8.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
+
+[[package]]
+name = "core-graphics"
+version = "0.23.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c07782be35f9e1140080c6b96f0d44b739e2278479f64e02fdab4e32dfd8b081"
+dependencies = [
+ "bitflags 1.3.2",
+ "core-foundation 0.9.4",
+ "core-graphics-types 0.1.3",
+ "foreign-types",
+ "libc",
+]
+
+[[package]]
+name = "core-graphics-types"
+version = "0.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "45390e6114f68f718cc7a830514a96f903cccd70d02a8f6d9f643ac4ba45afaf"
+dependencies = [
+ "bitflags 1.3.2",
+ "core-foundation 0.9.4",
+ "libc",
+]
+
+[[package]]
+name = "core-graphics-types"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d44a101f213f6c4cdc1853d4b78aef6db6bdfa3468798cc1d9912f4735013eb"
+dependencies = [
+ "bitflags 2.13.2",
+ "core-foundation 0.10.1",
+ "libc",
+]
+
+[[package]]
+name = "core_detect"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7f8f80099a98041a3d1622845c271458a2d73e688351bf3cb999266764b81d48"
+
+[[package]]
+name = "core_maths"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "77745e017f5edba1a9c1d854f6f3a52dac8a12dd5af5d2f54aecf61e43d80d30"
+dependencies = [
+ "libm",
+]
+
+[[package]]
+name = "cosmic-text"
+version = "0.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "173852283a9a57a3cbe365d86e74dc428a09c50421477d5ad6fe9d9509e37737"
+dependencies = [
+ "bitflags 2.13.2",
+ "fontdb",
+ "harfrust",
+ "linebender_resource_handle",
+ "log",
+ "rangemap",
+ "rustc-hash 1.1.0",
+ "self_cell",
+ "skrifa 0.37.0",
+ "smol_str",
+ "swash",
+ "sys-locale",
+ "unicode-bidi",
+ "unicode-linebreak",
+ "unicode-script",
+ "unicode-segmentation",
+]
+
+[[package]]
+name = "cpufeatures"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "cpufeatures"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5ca28b0ae3115b884660db4118d803791fd6756b6e88f39c0f3f7859060d7566"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "crc32fast"
+version = "1.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ba106e844045ddc02c20768ac4b0b7cb45f2cc2ecbd833ac9f5dacb183c2055"
+dependencies = [
+ "cfg-if",
+]
+
+[[package]]
+name = "crossbeam-utils"
+version = "0.8.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a31eee39dddec8330830986fcd7625edb5a24ec90ea038215273bbc3adb08ac6"
+
+[[package]]
+name = "crunchy"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "460fbee9c2c2f33933d720630a6a0bac33ba7053db5344fac858d4b8952d77d5"
+
+[[package]]
+name = "cryoglyph"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "08bc795bdbccdbd461736fb163930a009da6597b226d6f6fce33e7a8eb6ec519"
+dependencies = [
+ "cosmic-text",
+ "etagere",
+ "lru",
+ "rustc-hash 2.1.3",
+ "wgpu",
+]
+
+[[package]]
+name = "crypto-common"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
+dependencies = [
+ "generic-array",
+ "typenum",
+]
+
+[[package]]
+name = "ctor"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "83cf0d42651b16c6dfe68685716d18480d18a9c39c62d76e8cf3eb6ed5d8bcbf"
+dependencies = [
+ "dtor",
+]
+
+[[package]]
+name = "cursor-icon"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f27ae1dd37df86211c42e150270f82743308803d90a6f6e6651cd730d5e1732f"
+
+[[package]]
+name = "darling"
+version = "0.24.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed17f5901b6630b993ca003def43f2f8ef4014fc13b047b57aad617ff32bc2ec"
+dependencies = [
+ "darling_core",
+ "darling_macro",
+]
+
+[[package]]
+name = "darling_core"
+version = "0.24.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6837e2cf7485aaae18f86181d2f0e9a7ed297a025e220aeabf63fdebd3a2ddff"
+dependencies = [
+ "ident_case",
+ "proc-macro2",
+ "quote",
+ "strsim",
+ "syn 3.0.9",
+]
+
+[[package]]
+name = "darling_macro"
+version = "0.24.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2ac7135c3ef02b2f7833bbeb1be5ba7f966dcde8a87c6b87f65a778d71a02785"
+dependencies = [
+ "darling_core",
+ "quote",
+ "syn 3.0.9",
+]
+
+[[package]]
+name = "data-encoding"
+version = "2.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4583a4551df46e2792f82ceeac45e850d2e2d5debba0b91f102385cda5b11f06"
+
+[[package]]
+name = "data-url"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "be1e0bca6c3637f992fc1cc7cbc52a78c1ef6db076dbf1059c4323d6a2048376"
+
+[[package]]
+name = "digest"
+version = "0.10.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
+dependencies = [
+ "block-buffer",
+ "crypto-common",
+]
+
+[[package]]
+name = "dispatch"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bd0c93bb4b0c6d9b77f4435b0ae98c24d17f1c45b2ff844c6151a07256ca923b"
+
+[[package]]
+name = "dispatch2"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e0e367e4e7da84520dedcac1901e4da967309406d1e51017ae1abfb97adbd38"
+dependencies = [
+ "bitflags 2.13.2",
+ "objc2 0.6.5",
+]
+
+[[package]]
+name = "displaydoc"
+version = "0.2.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c6232dd377dcc64799954cbd3a9bb882e9cdc1308ccd87b1c098f1fb2eaf82a8"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.9",
+]
+
+[[package]]
+name = "dlib"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ab8ecd87370524b461f8557c119c405552c396ed91fc0a8eec68679eab26f94a"
+dependencies = [
+ "libloading",
+]
+
+[[package]]
+name = "document-features"
+version = "0.2.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d4b8a88685455ed29a21542a33abd9cb6510b6b129abadabdcef0f4c55bc8f61"
+dependencies = [
+ "litrs",
+]
+
+[[package]]
+name = "downcast-rs"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "75b325c5dbd37f80359721ad39aca5a29fb04c89279657cffdda8736d0c0b9d2"
+
+[[package]]
+name = "dpi"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d8b14ccef22fc6f5a8f4d7d768562a182c04ce9a3b3157b91390b52ddfdf1a76"
+
+[[package]]
+name = "dtor"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "edf234dd1594d6dd434a8fb8cada51ddbbc593e40e4a01556a0b31c62da2775b"
+
+[[package]]
+name = "dunce"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92773504d58c093f6de2459af4af33faa518c13451eb8f2b5698ed3d36e7c813"
+
+[[package]]
+name = "dyn-clone"
+version = "1.0.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d0881ea181b1df73ff77ffaaf9c7544ecc11e82fba9b5f27b262a3c73a332555"
+
+[[package]]
+name = "encoding_rs"
+version = "0.8.42"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e985e0451871ad22fb8d2b6b076e2028a502a0d3950998c2c5c0a4f9b5d9679"
+dependencies = [
+ "cfg-if",
+ "core_detect",
+ "multiversion_no_op",
+ "rustversion",
+ "scopeguard",
+ "simdutf8",
+]
+
+[[package]]
+name = "endi"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "66b7e2430c6dff6a955451e2cfc438f09cea1965a9d6f87f7e3b90decc014099"
+
+[[package]]
+name = "enumflags2"
+version = "0.7.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1027f7680c853e056ebcec683615fb6fbbc07dbaa13b4d5d9442b146ded4ecef"
+dependencies = [
+ "enumflags2_derive",
+ "serde",
+]
+
+[[package]]
+name = "enumflags2_derive"
+version = "0.7.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67c78a4d8fdf9953a5c9d458f9efe940fd97a0cab0941c075a813ac594733827"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "equivalent"
+version = "1.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "00d174d5400e5e8fd687ad1049e2f578285fa914201b1af7e8b112a4546bd826"
+
+[[package]]
+name = "errno"
+version = "0.3.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
+dependencies = [
+ "libc",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "error-code"
+version = "3.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b5343afd4a8365a643ac588dab4cf234a190c7f6c88c9f6dd6ffe00837661b7"
+
+[[package]]
+name = "etagere"
+version = "0.2.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc89bf99e5dc15954a60f707c1e09d7540e5cd9af85fa75caa0b510bc08c5342"
+dependencies = [
+ "euclid",
+ "svg_fmt",
+]
+
+[[package]]
+name = "euclid"
+version = "0.22.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f1a05365e3b1c6d1650318537c7460c6923f1abdd272ad6842baa2b509957a06"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "event-listener"
+version = "5.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a23add41df1562121a9393cb065eab5146a1242410f23a644851e90cfd669d2"
+dependencies = [
+ "parking",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "event-listener-strategy"
+version = "0.5.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8be9f3dfaaffdae2972880079a491a1a8bb7cbed0b8dd7a347f668b4150a3b93"
+dependencies = [
+ "event-listener",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "fastrand"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223"
+
+[[package]]
+name = "fdeflate"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e6853b52649d4ac5c0bd02320cddc5ba956bdb407c4b75a2c6b75bf51500f8c"
+dependencies = [
+ "simd-adler32",
+]
+
+[[package]]
+name = "filetime"
+version = "0.2.29"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c287a33c7f0a620c38e641e7f60827713987b3c0f26e8ddc9462cc69cf75759"
+dependencies = [
+ "cfg-if",
+ "libc",
+]
+
+[[package]]
+name = "find-msvc-tools"
+version = "0.1.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1c66915cc5391097de7a2b0b972e8505aa33c0df401fd3a6811dbdb32881ba48"
+
+[[package]]
+name = "flate2"
+version = "1.1.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e634e2e0ebac1ee034020da1ca582e17ffe4e0f5e985823721e168928136dcb"
+dependencies = [
+ "crc32fast",
+ "miniz_oxide 0.9.1",
+ "zlib-rs",
+]
+
+[[package]]
+name = "float-cmp"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "98de4bbd547a563b716d8dfa9aad1cb19bfab00f4fa09a6a4ed21dbcf44ce9c4"
+
+[[package]]
+name = "fnv"
+version = "1.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1"
+
+[[package]]
+name = "foldhash"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2"
+
+[[package]]
+name = "foldhash"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "77ce24cb58228fbb8aa041425bb1050850ac19177686ea6e0f41a70416f56fdb"
+
+[[package]]
+name = "font-types"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39a654f404bbcbd48ea58c617c2993ee91d1cb63727a37bf2323a4edeed1b8c5"
+dependencies = [
+ "bytemuck",
+]
+
+[[package]]
+name = "font-types"
+version = "0.12.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "835ae9d781464a79026cde387f9cbc650c9a4909d7cf7e658b127e3c35d2f35d"
+dependencies = [
+ "bytemuck",
+]
+
+[[package]]
+name = "fontconfig-parser"
+version = "0.5.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bbc773e24e02d4ddd8395fd30dc147524273a83e54e0f312d986ea30de5f5646"
+dependencies = [
+ "roxmltree",
+]
+
+[[package]]
+name = "fontdb"
+version = "0.23.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "457e789b3d1202543297a350643cf459f836cade38934e7a4cf6a39e7cde2905"
+dependencies = [
+ "fontconfig-parser",
+ "log",
+ "memmap2",
+ "slotmap",
+ "tinyvec",
+ "ttf-parser",
+]
+
+[[package]]
+name = "foreign-types"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d737d9aa519fb7b749cbc3b962edcf310a8dd1f4b67c91c4f83975dbdd17d965"
+dependencies = [
+ "foreign-types-macros",
+ "foreign-types-shared",
+]
+
+[[package]]
+name = "foreign-types-macros"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ea5190182e6915eb873ddbc16e23b711b6eb1f9c00a0d0a3a91b5f6228475225"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.9",
+]
+
+[[package]]
+name = "foreign-types-shared"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "aa9a19cbb55df58761df49b23516a86d432839add4af60fc256da840f66ed35b"
+
+[[package]]
+name = "form_urlencoded"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf"
+dependencies = [
+ "percent-encoding",
+]
+
+[[package]]
+name = "fs_extra"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "42703706b716c37f96a77aea830392ad231f44c9e9a67872fa5548707e11b11c"
+
+[[package]]
+name = "futures"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9a31d2a3fbaaeb2af2368bbdd904aa8e812d3c04a1ee10d3171f52d556e5d0a3"
+dependencies = [
+ "futures-channel",
+ "futures-core",
+ "futures-executor",
+ "futures-io",
+ "futures-sink",
+ "futures-task",
+ "futures-util",
+]
+
+[[package]]
+name = "futures-channel"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b1f9e3d69d39e4862ffed03ed071a76f9a13ba1d9109d355b0f0aa6b15e393c4"
+dependencies = [
+ "futures-core",
+ "futures-sink",
+]
+
+[[package]]
+name = "futures-core"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92d699e522242e69e3003b94ecc1f960f3a5e015aa7c5d7486e65ad01dd94f5e"
+
+[[package]]
+name = "futures-executor"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "031b47cf1a3c6cc8bc2fc76cd437f521619387907d469316e7c0bc278f1f5432"
+dependencies = [
+ "futures-core",
+ "futures-task",
+ "futures-util",
+]
+
+[[package]]
+name = "futures-io"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "53c0fa8157de1303bfffdaa1cc2a673bfffb60102f76b0ef4441659124373fed"
+
+[[package]]
+name = "futures-lite"
+version = "2.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f78e10609fe0e0b3f4157ffab1876319b5b0db102a2c60dc4626306dc46b44ad"
+dependencies = [
+ "fastrand",
+ "futures-core",
+ "futures-io",
+ "parking",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "futures-macro"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9fb9654ba8355388abeb8dcb4fc62f511300867002afc858860463bdd9fe0c44"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.9",
+]
+
+[[package]]
+name = "futures-sink"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1944426bf7d03f1d14f708785e4b33efd750b36d48a157b836b3efc15ede8e1d"
+
+[[package]]
+name = "futures-task"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cd417de3d1d015fc3bfd2b1ea46dfc7bab72ef86f1cc7cc9c78e728b34a6d1fd"
+
+[[package]]
+name = "futures-timer"
+version = "3.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "af43fadb8a98512d547e37b4e92e0ced13e205c061b87b4623eff01d918d6968"
+dependencies = [
+ "gloo-timers",
+ "send_wrapper",
+]
+
+[[package]]
+name = "futures-util"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc"
+dependencies = [
+ "futures-channel",
+ "futures-core",
+ "futures-io",
+ "futures-macro",
+ "futures-sink",
+ "futures-task",
+ "memchr",
+ "pin-project-lite",
+ "slab",
+]
+
+[[package]]
+name = "generic-array"
+version = "0.14.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"
+dependencies = [
+ "typenum",
+ "version_check",
+]
+
+[[package]]
+name = "gethostname"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1bd49230192a3797a9a4d6abe9b3eed6f7fa4c8a8a4947977c6f80025f92cbd8"
+dependencies = [
+ "rustix 1.1.6",
+ "windows-link",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"
+dependencies = [
+ "cfg-if",
+ "js-sys",
+ "libc",
+ "wasi",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "r-efi 5.3.0",
+ "wasip2",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099"
+dependencies = [
+ "cfg-if",
+ "js-sys",
+ "libc",
+ "r-efi 6.0.0",
+ "rand_core 0.10.1",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "gif"
+version = "0.13.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4ae047235e33e2829703574b54fdec96bfbad892062d97fed2f76022287de61b"
+dependencies = [
+ "color_quant",
+ "weezl",
+]
+
+[[package]]
+name = "gl_generator"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1a95dfc23a2b4a9a2f5ab41d194f8bfda3cabec42af4e39f08c339eb2a0c124d"
+dependencies = [
+ "khronos_api",
+ "log",
+ "xml-rs",
+]
+
+[[package]]
+name = "glam"
+version = "0.25.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "151665d9be52f9bb40fc7966565d39666f2d1e69233571b71b87791c7e0528b3"
+
+[[package]]
+name = "glob"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e4eba85ea1d0a966a983acd07deee566e67395d2d96b6fb39e62b5a833f1eb0b"
+
+[[package]]
+name = "gloo-timers"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "482ce8a491a501da4cd806bd190275363d674f2845005c6ddbd5d3e1dd54495d"
+dependencies = [
+ "futures-channel",
+ "futures-core",
+ "js-sys",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "glow"
+version = "0.16.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c5e5ea60d70410161c8bf5da3fdfeaa1c72ed2c15f8bbb9d19fe3a4fad085f08"
+dependencies = [
+ "js-sys",
+ "slotmap",
+ "wasm-bindgen",
+ "web-sys",
+]
+
+[[package]]
+name = "glutin_wgl_sys"
+version = "0.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2c4ee00b289aba7a9e5306d57c2d05499b2e5dc427f84ac708bd2c090212cf3e"
+dependencies = [
+ "gl_generator",
+]
+
+[[package]]
+name = "gpu-alloc"
+version = "0.6.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "45cf04b2726f02df5508c6de726acdc90cdf97ac771a9a0ffd8ba10a6e696bf9"
+dependencies = [
+ "bitflags 2.13.2",
+ "gpu-alloc-types",
+]
+
+[[package]]
+name = "gpu-alloc-types"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b2bbed164dd10ed526c2e4fe3e721ca4a71c61730e5aafac6844b417b3227058"
+dependencies = [
+ "bitflags 2.13.2",
+]
+
+[[package]]
+name = "gpu-allocator"
+version = "0.27.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c151a2a5ef800297b4e79efa4f4bec035c5f51d5ae587287c9b952bdf734cacd"
+dependencies = [
+ "log",
+ "presser",
+ "thiserror 1.0.69",
+ "windows 0.58.0",
+]
+
+[[package]]
+name = "gpu-descriptor"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b89c83349105e3732062a895becfc71a8f921bb71ecbbdd8ff99263e3b53a0ca"
+dependencies = [
+ "bitflags 2.13.2",
+ "gpu-descriptor-types",
+ "hashbrown 0.15.5",
+]
+
+[[package]]
+name = "gpu-descriptor-types"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fdf242682df893b86f33a73828fb09ca4b2d3bb6cc95249707fc684d27484b91"
+dependencies = [
+ "bitflags 2.13.2",
+]
+
+[[package]]
+name = "guillotiere"
+version = "0.6.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b62d5865c036cb1393e23c50693df631d3f5d7bcca4c04fe4cc0fd592e74a782"
+dependencies = [
+ "euclid",
+ "svg_fmt",
+]
+
+[[package]]
+name = "h2"
+version = "0.4.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7d29020232d6aa3fb1daca64c1127cf662cf97f254ae16c18c05b8ab635fc118"
+dependencies = [
+ "atomic-waker",
+ "bytes",
+ "fnv",
+ "futures-core",
+ "futures-sink",
+ "http",
+ "indexmap",
+ "slab",
+ "tokio",
+ "tokio-util",
+ "tracing",
+]
+
+[[package]]
+name = "half"
+version = "2.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ea2d84b969582b4b1864a92dc5d27cd2b77b622a8d79306834f1be5ba20d84b"
+dependencies = [
+ "cfg-if",
+ "crunchy",
+ "num-traits",
+ "zerocopy",
+]
+
+[[package]]
+name = "harfrust"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92c020db12c71d8a12a3fe7607873cade3a01a6287e29d540c8723276221b9d8"
+dependencies = [
+ "bitflags 2.13.2",
+ "bytemuck",
+ "core_maths",
+ "read-fonts 0.35.0",
+ "smallvec",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.15.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1"
+dependencies = [
+ "foldhash 0.1.5",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.16.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "841d1cc9bed7f9236f321df977030373f4a4163ae1a7dbfe1a51a2c1a51d9100"
+dependencies = [
+ "foldhash 0.2.0",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.17.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
+
+[[package]]
+name = "hermit-abi"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e17592d60ebacc7d5e169f4663c5f84f9161cc90328abcfe8456f41e4dfcb284"
+
+[[package]]
+name = "hex"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7f24254aa9a54b5c858eaee2f5bccdb46aaf0e486a595ed5fd8f86ba55232a70"
+
+[[package]]
+name = "hexf-parse"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dfa686283ad6dd069f105e5ab091b04c62850d3e4cf5d67debad1933f55023df"
+
+[[package]]
+name = "http"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "918d3568bebf352712bc2ef3d46a8bcf1a75b373be6539de198e9105cbbf9ce0"
+dependencies = [
+ "bytes",
+ "itoa",
+]
+
+[[package]]
+name = "http-body"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ca2a8f2913ee65f60facd6a5905613afaa448497a0230cc41ce022d93290bc2c"
+dependencies = [
+ "bytes",
+ "http",
+]
+
+[[package]]
+name = "http-body-util"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23169fe34a5fbcdd3f3862e78fb9b6fccd5f02a6dc6f732547005d45631ce71c"
+dependencies = [
+ "bytes",
+ "futures-core",
+ "http",
+ "http-body",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "httparse"
+version = "1.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87"
+
+[[package]]
+name = "httpdate"
+version = "1.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9"
+
+[[package]]
+name = "hyper"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2c3e324da4c95177d6291d4c8730197c0d1822f8a9766814a4a44fa5ab797c9c"
+dependencies = [
+ "atomic-waker",
+ "bytes",
+ "futures-channel",
+ "futures-core",
+ "h2",
+ "http",
+ "http-body",
+ "httparse",
+ "httpdate",
+ "itoa",
+ "pin-project-lite",
+ "smallvec",
+ "tokio",
+ "want",
+]
+
+[[package]]
+name = "hyper-rustls"
+version = "0.27.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dfa8e654703247911e29c23fbeaa261834bd9bb74efba2f9acddc37bfb127f53"
+dependencies = [
+ "http",
+ "hyper",
+ "hyper-util",
+ "rustls",
+ "tokio",
+ "tokio-rustls",
+ "tower-service",
+ "webpki-roots 1.0.11",
+]
+
+[[package]]
+name = "hyper-util"
+version = "0.1.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ddc03d96684f9226b8a787cdb71488417b53ab5ea8fdb1dac946cb9431cc8bff"
+dependencies = [
+ "base64 0.23.1",
+ "bytes",
+ "futures-channel",
+ "futures-util",
+ "http",
+ "http-body",
+ "httparse",
+ "hyper",
+ "ipnet",
+ "libc",
+ "percent-encoding",
+ "pin-project-lite",
+ "socket2",
+ "system-configuration",
+ "tokio",
+ "tower-service",
+ "tracing",
+ "windows-registry",
+]
+
+[[package]]
+name = "iana-time-zone"
+version = "0.1.65"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e31bc9ad994ba00e440a8aa5c9ef0ec67d5cb5e5cb0cc7f8b744a35b389cc470"
+dependencies = [
+ "android_system_properties",
+ "core-foundation-sys",
+ "iana-time-zone-haiku",
+ "js-sys",
+ "log",
+ "wasm-bindgen",
+ "windows-core 0.62.2",
+]
+
+[[package]]
+name = "iana-time-zone-haiku"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f31827a206f56af32e590ba56d5d2d085f558508192593743f16b2306495269f"
+dependencies = [
+ "cc",
+]
+
+[[package]]
+name = "iced"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "000e01026c93ba643f8357a3db3ada0e6555265a377f6f9291c472f6dd701fb3"
+dependencies = [
+ "iced_core",
+ "iced_debug",
+ "iced_futures",
+ "iced_renderer",
+ "iced_runtime",
+ "iced_widget",
+ "iced_winit",
+ "image",
+ "thiserror 2.0.21",
+]
+
+[[package]]
+name = "iced_core"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "91ab1937d699403e7e69252ae743a902bcee9f4ab2052cc4c9a46fcf34729d85"
+dependencies = [
+ "bitflags 2.13.2",
+ "bytes",
+ "glam",
+ "lilt",
+ "log",
+ "num-traits",
+ "rustc-hash 2.1.3",
+ "smol_str",
+ "thiserror 2.0.21",
+ "web-time",
+]
+
+[[package]]
+name = "iced_debug"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "25035ab0215a620e53f4103e36fc4e59a1fb2817e4bfc38a30ad27b4202ea0be"
+dependencies = [
+ "iced_core",
+ "iced_futures",
+ "log",
+]
+
+[[package]]
+name = "iced_futures"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8c0c85ccad42dfbec7293c36c018af0ea0dbcc52d137a4a9a0b0f6822a3fdf0a"
+dependencies = [
+ "futures",
+ "iced_core",
+ "log",
+ "rustc-hash 2.1.3",
+ "wasm-bindgen-futures",
+ "wasmtimer",
+]
+
+[[package]]
+name = "iced_graphics"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "234ca1c2cec4155055f68fa5fad1b5242c496ac8238d80a259bca382fb44a102"
+dependencies = [
+ "bitflags 2.13.2",
+ "bytemuck",
+ "cosmic-text",
+ "half",
+ "iced_core",
+ "iced_futures",
+ "image",
+ "kamadak-exif",
+ "log",
+ "raw-window-handle",
+ "rustc-hash 2.1.3",
+ "thiserror 2.0.21",
+ "unicode-segmentation",
+]
+
+[[package]]
+name = "iced_program"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6dfafec2947cda688d8eb00dac337ba11aa60f9ef6335aed343e189d26e4a673"
+dependencies = [
+ "iced_graphics",
+ "iced_runtime",
+]
+
+[[package]]
+name = "iced_renderer"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "250cc0802408e8c077986ec56c7d07c65f423ee658a4b9fd795a1f2aae5dac05"
+dependencies = [
+ "iced_graphics",
+ "iced_tiny_skia",
+ "iced_wgpu",
+ "log",
+ "thiserror 2.0.21",
+]
+
+[[package]]
+name = "iced_runtime"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d1889b819ce4c06674183242e336c8d49465665441396914dc07cc86f44fa8d4"
+dependencies = [
+ "bytes",
+ "iced_core",
+ "iced_futures",
+ "raw-window-handle",
+ "thiserror 2.0.21",
+]
+
+[[package]]
+name = "iced_tiny_skia"
+version = "0.14.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c267596d742714b1853cc10c3983a367762816fc4836bd3b79f76ce76787d6f8"
+dependencies = [
+ "bytemuck",
+ "cosmic-text",
+ "iced_debug",
+ "iced_graphics",
+ "kurbo 0.10.4",
+ "log",
+ "resvg",
+ "rustc-hash 2.1.3",
+ "softbuffer",
+ "tiny-skia",
+]
+
+[[package]]
+name = "iced_wgpu"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff144a999b0ca0f8a10257934500060240825c42e950ec0ebee9c8ae30561c13"
+dependencies = [
+ "bitflags 2.13.2",
+ "bytemuck",
+ "cryoglyph",
+ "futures",
+ "glam",
+ "guillotiere",
+ "iced_debug",
+ "iced_graphics",
+ "log",
+ "resvg",
+ "rustc-hash 2.1.3",
+ "thiserror 2.0.21",
+ "wgpu",
+]
+
+[[package]]
+name = "iced_widget"
+version = "0.14.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b1596afa0d3109c2618e8bc12bae6c11d3064df8f95c42dfce570397dbe957ab"
+dependencies = [
+ "iced_renderer",
+ "log",
+ "num-traits",
+ "rustc-hash 2.1.3",
+ "thiserror 2.0.21",
+ "unicode-segmentation",
+]
+
+[[package]]
+name = "iced_winit"
+version = "0.14.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7589888c8e951899cc688247a69933bb7a0511f0b4b2e122ac3fcd5dacb37f72"
+dependencies = [
+ "iced_debug",
+ "iced_program",
+ "log",
+ "mundy",
+ "rustc-hash 2.1.3",
+ "thiserror 2.0.21",
+ "tracing",
+ "wasm-bindgen-futures",
+ "web-sys",
+ "window_clipboard",
+ "winit",
+]
+
+[[package]]
+name = "icu_collections"
+version = "2.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fe090a42a0d3140fed8c63263ed1fecc02422cb2f4bfe55cd8de2de1b8e105dd"
+dependencies = [
+ "displaydoc",
+ "potential_utf",
+ "utf8_iter",
+ "yoke",
+ "zerofrom",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_locale_core"
+version = "2.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "25d29b57c17c6528d0dc4c2141cfa2d08200465acb537a3909c8b9b8a4a984c0"
+dependencies = [
+ "displaydoc",
+ "litemap",
+ "tinystr",
+ "writeable",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_normalizer"
+version = "2.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "404a3b8c486f205c87fe7f23ab6894d84a4ad76d6e4671ae1981ba7def87c599"
+dependencies = [
+ "icu_collections",
+ "icu_normalizer_data",
+ "icu_properties",
+ "icu_provider",
+ "smallvec",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_normalizer_data"
+version = "2.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "20f0088bfb7441f7a37fa0c9e20cb1e9cba1cac6b9ce8cd2a6dc44294f8e8cbc"
+
+[[package]]
+name = "icu_properties"
+version = "2.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2ea83d991c56158f7cf898bf86436c1dfe7c07ee82fe88951f2695c9f37a379f"
+dependencies = [
+ "displaydoc",
+ "icu_collections",
+ "icu_locale_core",
+ "icu_properties_data",
+ "icu_provider",
+ "zerotrie",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_properties_data"
+version = "2.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b98f29af82d02b163fe50161388350e743bb3107cc8e8c2f7314cb505faddfcf"
+
+[[package]]
+name = "icu_provider"
+version = "2.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "413099315636c588ee8f011190b329b971a09a8fae9d157e01dcae8379468514"
+dependencies = [
+ "displaydoc",
+ "icu_locale_core",
+ "writeable",
+ "yoke",
+ "zerofrom",
+ "zerotrie",
+ "zerovec",
+]
+
+[[package]]
+name = "ident_case"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b9e0384b61958566e926dc50660321d12159025e767c18e043daf26b70104c39"
+
+[[package]]
+name = "idna"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b0875f23caa03898994f6ddc501886a45c7d3d62d04d2d90788d47be1b1e4de"
+dependencies = [
+ "idna_adapter",
+ "smallvec",
+ "utf8_iter",
+]
+
+[[package]]
+name = "idna_adapter"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb68373c0d6620ef8105e855e7745e18b0d00d3bdb07fb532e434244cdb9a714"
+dependencies = [
+ "icu_normalizer",
+ "icu_properties",
+]
+
+[[package]]
+name = "image"
+version = "0.25.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85ab80394333c02fe689eaf900ab500fbd0c2213da414687ebf995a65d5a6104"
+dependencies = [
+ "bytemuck",
+ "byteorder-lite",
+ "moxcms",
+ "num-traits",
+ "png 0.18.1",
+ "zune-core 0.5.3",
+ "zune-jpeg 0.5.15",
+]
+
+[[package]]
+name = "image-webp"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "525e9ff3e1a4be2fbea1fdf0e98686a6d98b4d8f937e1bf7402245af1909e8c3"
+dependencies = [
+ "byteorder-lite",
+ "quick-error",
+]
+
+[[package]]
+name = "imagesize"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "edcd27d72f2f071c64249075f42e205ff93c9a4c5f6c6da53e79ed9f9832c285"
+
+[[package]]
+name = "indexmap"
+version = "2.14.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cc4e190f5d26ca7051642629da2c52fc03bde85a03197c99408dcd291734c855"
+dependencies = [
+ "equivalent",
+ "hashbrown 0.17.1",
+ "serde",
+ "serde_core",
+]
+
+[[package]]
+name = "ipnet"
+version = "2.12.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "791930b43c0d5973160d90a8f3894509f2b273430f5c5c73b668636d0287c5c0"
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "jni"
+version = "0.22.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5efd9a482cf3a427f00d6b35f14332adc7902ce91efb778580e180ff90fa3498"
+dependencies = [
+ "cfg-if",
+ "combine",
+ "jni-macros",
+ "jni-sys 0.4.1",
+ "log",
+ "simd_cesu8",
+ "thiserror 2.0.21",
+ "walkdir",
+ "windows-link",
+]
+
+[[package]]
+name = "jni-macros"
+version = "0.22.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a00109accc170f0bdb141fed3e393c565b6f5e072365c3bd58f5b062591560a3"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "rustc_version",
+ "simd_cesu8",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "jni-sys"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41a652e1f9b6e0275df1f15b32661cf0d4b78d4d87ddec5e0c3c20f097433258"
+dependencies = [
+ "jni-sys 0.4.1",
+]
+
+[[package]]
+name = "jni-sys"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c6377a88cb3910bee9b0fa88d4f42e1d2da8e79915598f65fb0c7ee14c878af2"
+dependencies = [
+ "jni-sys-macros",
+]
+
+[[package]]
+name = "jni-sys-macros"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "38c0b942f458fe50cdac086d2f946512305e5631e720728f2a61aabcd47a6264"
+dependencies = [
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "jobserver"
+version = "0.1.35"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1c00acbd29eabad4a2392fa0e921c874934dbbf4194312ad20f04a0ed67a3cb3"
+dependencies = [
+ "getrandom 0.4.3",
+ "libc",
+]
+
+[[package]]
+name = "js-sys"
+version = "0.3.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7883d941dae510fb2d978fc3fe018c71c9e2892fd38854de3e8b92c2e5ad9cc5"
+dependencies = [
+ "cfg-if",
+ "futures-util",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "kamadak-exif"
+version = "0.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1130d80c7374efad55a117d715a3af9368f0fa7a2c54573afc15a188cd984837"
+dependencies = [
+ "mutate_once",
+]
+
+[[package]]
+name = "khronos-egl"
+version = "6.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6aae1df220ece3c0ada96b8153459b67eebe9ae9212258bb0134ae60416fdf76"
+dependencies = [
+ "libc",
+ "libloading",
+ "pkg-config",
+]
+
+[[package]]
+name = "khronos_api"
+version = "3.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e2db585e1d738fc771bf08a151420d3ed193d9d895a36df7f6f8a9456b911ddc"
+
+[[package]]
+name = "kurbo"
+version = "0.10.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1618d4ebd923e97d67e7cd363d80aef35fe961005cbbbb3d2dad8bdd1bc63440"
+dependencies = [
+ "arrayvec",
+ "smallvec",
+]
+
+[[package]]
+name = "kurbo"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c62026ae44756f8a599ba21140f350303d4f08dcdcc71b5ad9c9bb8128c13c62"
+dependencies = [
+ "arrayvec",
+ "euclid",
+ "smallvec",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.191"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"
+
+[[package]]
+name = "libloading"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d7c4b02199fee7c5d21a5ae7d8cfa79a6ef5bb2fc834d6e9058e89c825efdc55"
+dependencies = [
+ "cfg-if",
+ "windows-link",
+]
+
+[[package]]
+name = "libm"
+version = "0.2.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6d2cec3eae94f9f509c767b45932f1ada8350c4bdb85af2fcab4a3c14807981"
+
+[[package]]
+name = "libredox"
+version = "0.1.25"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61ff90caf6077a803a240f62fdbe88645a890bbca49ef8174c3cb0404362171d"
+dependencies = [
+ "bitflags 2.13.2",
+ "libc",
+ "plain",
+ "redox_syscall 0.9.5",
+]
+
+[[package]]
+name = "lilt"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "337d4c256f7d9f2dbd633891d48ace853efa5b1554122d9220b172ad9c03c3a9"
+dependencies = [
+ "web-time",
+]
+
+[[package]]
+name = "linebender_resource_handle"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d4a5ff6bcca6c4867b1c4fd4ef63e4db7436ef363e0ad7531d1558856bae64f4"
+
+[[package]]
+name = "linux-raw-sys"
+version = "0.4.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d26c52dbd32dccf2d10cac7725f8eae5296885fb5703b261f7d0a0739ec807ab"
+
+[[package]]
+name = "linux-raw-sys"
+version = "0.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
+
+[[package]]
+name = "litemap"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "47d9d19d1d6efa0109d2f65ff4c85cddd50bd572e5a00127ab10987290bcefae"
+
+[[package]]
+name = "litrs"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4744e383959f0db86ede514b809b1c53251889093803c05267acc7d4e7030d70"
+
+[[package]]
+name = "lock_api"
+version = "0.4.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "224399e74b87b5f3557511d98dff8b14089b3dadafcab6bb93eab67d3aace965"
+dependencies = [
+ "scopeguard",
+]
+
+[[package]]
+name = "log"
+version = "0.4.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f9f8bd3e56ce4dfc153cf470fffbfa98c7620958b312ca5c3a4b8d5181fd13c6"
+
+[[package]]
+name = "lru"
+version = "0.16.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7f66e8d5d03f609abc3a39e6f08e4164ebf1447a732906d39eb9b99b7919ef39"
+
+[[package]]
+name = "lru-slab"
+version = "0.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4050469837a6ff301cd14c1f8f24f88549e6d548f24f64e2148eb0f72cebc51f"
+
+[[package]]
+name = "malloc_buf"
+version = "0.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "62bb907fe88d54d8d9ce32a3cceab4218ed2f6b7d35617cafe9adf84e43919cb"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "matchit"
+version = "0.8.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "47e1ffaa40ddd1f3ed91f717a33c8c0ee23fff369e3aa8772b9605cc1d22f4c3"
+
+[[package]]
+name = "md-5"
+version = "0.10.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d89e7ee0cfbedfc4da3340218492196241d89eefb6dab27de5df917a6d2e78cf"
+dependencies = [
+ "cfg-if",
+ "digest",
+]
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "memmap2"
+version = "0.9.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6b0ca1155a9ecc25aa12e8313a119f32edf0255fea2f44839c4ac0a12b2ac157"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "memoffset"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "metal"
+version = "0.32.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "00c15a6f673ff72ddcc22394663290f870fb224c1bfce55734a75c414150e605"
+dependencies = [
+ "bitflags 2.13.2",
+ "block",
+ "core-graphics-types 0.2.0",
+ "foreign-types",
+ "log",
+ "objc",
+ "paste",
+]
+
+[[package]]
+name = "mime"
+version = "0.3.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6877bb514081ee2a7ff5ef9de3281f14a4dd4bceac4c09388074a6b5df8a139a"
+
+[[package]]
+name = "mime_guess"
+version = "2.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f7c44f8e672c00fe5308fa235f821cb4198414e1c77935c1ab6948d3fd78550e"
+dependencies = [
+ "mime",
+ "unicase",
+]
+
+[[package]]
+name = "miniz_oxide"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316"
+dependencies = [
+ "adler2",
+ "simd-adler32",
+]
+
+[[package]]
+name = "miniz_oxide"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b63fbc4a50860e98e7b2aa7804ded1db5cbc3aff9193adaff57a6931bf7c4b4c"
+dependencies = [
+ "adler2",
+ "simd-adler32",
+]
+
+[[package]]
+name = "mio"
+version = "1.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1788edb87fdc09c7e26304471e2f5be8cdefb1b6930d6e3985fc02ff53bf86ee"
+dependencies = [
+ "libc",
+ "wasi",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "moxcms"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb85c154ba489f01b25c0d36ae69a87e4a1c73a72631fc6c0eb6dde34a73e44b"
+dependencies = [
+ "num-traits",
+ "pxfm",
+]
+
+[[package]]
+name = "multiversion_no_op"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "743fb55ba31b18fb1ecef6bdc9aa2743314978ac084044301a7eee33fb99a20d"
+
+[[package]]
+name = "mundy"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f32eb0db40f2df2bcfb05c93b8f73938d4c26ce9ac8881f1df0c8d3296921a73"
+dependencies = [
+ "android-build",
+ "async-io",
+ "cfg-if",
+ "dispatch",
+ "futures-channel",
+ "futures-lite",
+ "jni",
+ "ndk-context",
+ "objc2 0.6.5",
+ "objc2-app-kit 0.3.2",
+ "objc2-foundation 0.3.2",
+ "pin-project-lite",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "web-sys",
+ "windows 0.62.2",
+ "zbus",
+]
+
+[[package]]
+name = "mutate_once"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "13d2233c9842d08cfe13f9eac96e207ca6a2ea10b80259ebe8ad0268be27d2af"
+
+[[package]]
+name = "naga"
+version = "27.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "066cf25f0e8b11ee0df221219010f213ad429855f57c494f995590c861a9a7d8"
+dependencies = [
+ "arrayvec",
+ "bit-set",
+ "bitflags 2.13.2",
+ "cfg-if",
+ "cfg_aliases",
+ "codespan-reporting",
+ "half",
+ "hashbrown 0.16.1",
+ "hexf-parse",
+ "indexmap",
+ "libm",
+ "log",
+ "num-traits",
+ "once_cell",
+ "rustc-hash 1.1.0",
+ "spirv",
+ "thiserror 2.0.21",
+ "unicode-ident",
+]
+
+[[package]]
+name = "ndk"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c3f42e7bbe13d351b6bead8286a43aac9534b82bd3cc43e47037f012ebfd62d4"
+dependencies = [
+ "bitflags 2.13.2",
+ "jni-sys 0.3.1",
+ "log",
+ "ndk-sys",
+ "num_enum",
+ "raw-window-handle",
+ "thiserror 1.0.69",
+]
+
+[[package]]
+name = "ndk-context"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "27b02d87554356db9e9a873add8782d4ea6e3e58ea071a9adb9a2e8ddb884a8b"
+
+[[package]]
+name = "ndk-sys"
+version = "0.6.0+11769913"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ee6cda3051665f1fb8d9e08fc35c96d5a244fb1be711a03b71118828afc9a873"
+dependencies = [
+ "jni-sys 0.3.1",
+]
+
+[[package]]
+name = "nix"
+version = "0.31.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf20d2fde8ff38632c426f1165ed7436270b44f199fc55284c38276f9db47c3d"
+dependencies = [
+ "bitflags 2.13.2",
+ "cfg-if",
+ "cfg_aliases",
+ "libc",
+]
+
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
+ "libm",
+]
+
+[[package]]
+name = "num_enum"
+version = "0.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5d0bca838442ec211fa11de3a8b0e0e8f3a4522575b5c4c06ed722e005036f26"
+dependencies = [
+ "num_enum_derive",
+ "rustversion",
+]
+
+[[package]]
+name = "num_enum_derive"
+version = "0.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "680998035259dcfcafe653688bf2aa6d3e2dc05e98be6ab46afb089dc84f1df8"
+dependencies = [
+ "proc-macro-crate",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "objc"
+version = "0.2.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "915b1b472bc21c53464d6c8461c9d3af805ba1ef837e1cac254428f4a77177b1"
+dependencies = [
+ "malloc_buf",
+]
+
+[[package]]
+name = "objc-sys"
+version = "0.3.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cdb91bdd390c7ce1a8607f35f3ca7151b65afc0ff5ff3b34fa350f7d7c7e4310"
+
+[[package]]
+name = "objc2"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "19d5490aaf8f1d7cf7688dfa9b0ce07900e168852c45cd2c03f534dfd27cfd0b"
+dependencies = [
+ "objc-sys",
+ "objc2-encode",
+]
+
+[[package]]
+name = "objc2"
+version = "0.6.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "08849bbd4767dfae9457696856ae1c84fe4e0281bbe4a7abff2d0e06fb7981f8"
+dependencies = [
+ "objc2-encode",
+]
+
+[[package]]
+name = "objc2-app-kit"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e4e89ad9e3d7d297152b17d39ed92cd50ca8063a89a9fa569046d41568891eff"
+dependencies = [
+ "bitflags 2.13.2",
+ "block2 0.5.1",
+ "libc",
+ "objc2 0.5.3",
+ "objc2-core-data 0.2.2",
+ "objc2-core-image 0.2.2",
+ "objc2-foundation 0.2.2",
+ "objc2-quartz-core 0.2.2",
+]
+
+[[package]]
+name = "objc2-app-kit"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d49e936b501e5c5bf01fda3a9452ff86dc3ea98ad5f283e1455153142d97518c"
+dependencies = [
+ "bitflags 2.13.2",
+ "block2 0.6.2",
+ "libc",
+ "objc2 0.6.5",
+ "objc2-cloud-kit 0.3.2",
+ "objc2-core-data 0.3.2",
+ "objc2-core-foundation",
+ "objc2-core-graphics",
+ "objc2-core-image 0.3.2",
+ "objc2-core-text",
+ "objc2-core-video",
+ "objc2-foundation 0.3.2",
+ "objc2-quartz-core 0.3.2",
+]
+
+[[package]]
+name = "objc2-cloud-kit"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "74dd3b56391c7a0596a295029734d3c1c5e7e510a4cb30245f8221ccea96b009"
+dependencies = [
+ "bitflags 2.13.2",
+ "block2 0.5.1",
+ "objc2 0.5.3",
+ "objc2-core-location",
+ "objc2-foundation 0.2.2",
+]
+
+[[package]]
+name = "objc2-cloud-kit"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73ad74d880bb43877038da939b7427bba67e9dd42004a18b809ba7d87cee241c"
+dependencies = [
+ "bitflags 2.13.2",
+ "objc2 0.6.5",
+ "objc2-foundation 0.3.2",
+]
+
+[[package]]
+name = "objc2-contacts"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a5ff520e9c33812fd374d8deecef01d4a840e7b41862d849513de77e44aa4889"
+dependencies = [
+ "block2 0.5.1",
+ "objc2 0.5.3",
+ "objc2-foundation 0.2.2",
+]
+
+[[package]]
+name = "objc2-core-data"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "617fbf49e071c178c0b24c080767db52958f716d9eabdf0890523aeae54773ef"
+dependencies = [
+ "bitflags 2.13.2",
+ "block2 0.5.1",
+ "objc2 0.5.3",
+ "objc2-foundation 0.2.2",
+]
+
+[[package]]
+name = "objc2-core-data"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b402a653efbb5e82ce4df10683b6b28027616a2715e90009947d50b8dd298fa"
+dependencies = [
+ "bitflags 2.13.2",
+ "objc2 0.6.5",
+ "objc2-foundation 0.3.2",
+]
+
+[[package]]
+name = "objc2-core-foundation"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2a180dd8642fa45cdb7dd721cd4c11b1cadd4929ce112ebd8b9f5803cc79d536"
+dependencies = [
+ "bitflags 2.13.2",
+ "dispatch2",
+ "objc2 0.6.5",
+]
+
+[[package]]
+name = "objc2-core-graphics"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e022c9d066895efa1345f8e33e584b9f958da2fd4cd116792e15e07e4720a807"
+dependencies = [
+ "bitflags 2.13.2",
+ "dispatch2",
+ "objc2 0.6.5",
+ "objc2-core-foundation",
+ "objc2-io-surface",
+]
+
+[[package]]
+name = "objc2-core-image"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "55260963a527c99f1819c4f8e3b47fe04f9650694ef348ffd2227e8196d34c80"
+dependencies = [
+ "block2 0.5.1",
+ "objc2 0.5.3",
+ "objc2-foundation 0.2.2",
+ "objc2-metal",
+]
+
+[[package]]
+name = "objc2-core-image"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e5d563b38d2b97209f8e861173de434bd0214cf020e3423a52624cd1d989f006"
+dependencies = [
+ "objc2 0.6.5",
+ "objc2-foundation 0.3.2",
+]
+
+[[package]]
+name = "objc2-core-location"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "000cfee34e683244f284252ee206a27953279d370e309649dc3ee317b37e5781"
+dependencies = [
+ "block2 0.5.1",
+ "objc2 0.5.3",
+ "objc2-contacts",
+ "objc2-foundation 0.2.2",
+]
+
+[[package]]
+name = "objc2-core-text"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0cde0dfb48d25d2b4862161a4d5fcc0e3c24367869ad306b0c9ec0073bfed92d"
+dependencies = [
+ "bitflags 2.13.2",
+ "objc2 0.6.5",
+ "objc2-core-foundation",
+ "objc2-core-graphics",
+]
+
+[[package]]
+name = "objc2-core-video"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d425caf1df73233f29fd8a5c3e5edbc30d2d4307870f802d18f00d83dc5141a6"
+dependencies = [
+ "bitflags 2.13.2",
+ "objc2 0.6.5",
+ "objc2-core-foundation",
+ "objc2-core-graphics",
+ "objc2-io-surface",
+]
+
+[[package]]
+name = "objc2-encode"
+version = "4.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ef25abbcd74fb2609453eb695bd2f860d389e457f67dc17cafc8b8cbc89d0c33"
+
+[[package]]
+name = "objc2-foundation"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ee638a5da3799329310ad4cfa62fbf045d5f56e3ef5ba4149e7452dcf89d5a8"
+dependencies = [
+ "bitflags 2.13.2",
+ "block2 0.5.1",
+ "dispatch",
+ "libc",
+ "objc2 0.5.3",
+]
+
+[[package]]
+name = "objc2-foundation"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e3e0adef53c21f888deb4fa59fc59f7eb17404926ee8a6f59f5df0fd7f9f3272"
+dependencies = [
+ "bitflags 2.13.2",
+ "block2 0.6.2",
+ "libc",
+ "objc2 0.6.5",
+ "objc2-core-foundation",
+]
+
+[[package]]
+name = "objc2-io-surface"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "180788110936d59bab6bd83b6060ffdfffb3b922ba1396b312ae795e1de9d81d"
+dependencies = [
+ "bitflags 2.13.2",
+ "objc2 0.6.5",
+ "objc2-core-foundation",
+]
+
+[[package]]
+name = "objc2-link-presentation"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a1a1ae721c5e35be65f01a03b6d2ac13a54cb4fa70d8a5da293d7b0020261398"
+dependencies = [
+ "block2 0.5.1",
+ "objc2 0.5.3",
+ "objc2-app-kit 0.2.2",
+ "objc2-foundation 0.2.2",
+]
+
+[[package]]
+name = "objc2-metal"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dd0cba1276f6023976a406a14ffa85e1fdd19df6b0f737b063b95f6c8c7aadd6"
+dependencies = [
+ "bitflags 2.13.2",
+ "block2 0.5.1",
+ "objc2 0.5.3",
+ "objc2-foundation 0.2.2",
+]
+
+[[package]]
+name = "objc2-quartz-core"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e42bee7bff906b14b167da2bac5efe6b6a07e6f7c0a21a7308d40c960242dc7a"
+dependencies = [
+ "bitflags 2.13.2",
+ "block2 0.5.1",
+ "objc2 0.5.3",
+ "objc2-foundation 0.2.2",
+ "objc2-metal",
+]
+
+[[package]]
+name = "objc2-quartz-core"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "96c1358452b371bf9f104e21ec536d37a650eb10f7ee379fff67d2e08d537f1f"
+dependencies = [
+ "bitflags 2.13.2",
+ "objc2 0.6.5",
+ "objc2-core-foundation",
+ "objc2-foundation 0.3.2",
+]
+
+[[package]]
+name = "objc2-symbols"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0a684efe3dec1b305badae1a28f6555f6ddd3bb2c2267896782858d5a78404dc"
+dependencies = [
+ "objc2 0.5.3",
+ "objc2-foundation 0.2.2",
+]
+
+[[package]]
+name = "objc2-ui-kit"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8bb46798b20cd6b91cbd113524c490f1686f4c4e8f49502431415f3512e2b6f"
+dependencies = [
+ "bitflags 2.13.2",
+ "block2 0.5.1",
+ "objc2 0.5.3",
+ "objc2-cloud-kit 0.2.2",
+ "objc2-core-data 0.2.2",
+ "objc2-core-image 0.2.2",
+ "objc2-core-location",
+ "objc2-foundation 0.2.2",
+ "objc2-link-presentation",
+ "objc2-quartz-core 0.2.2",
+ "objc2-symbols",
+ "objc2-uniform-type-identifiers",
+ "objc2-user-notifications",
+]
+
+[[package]]
+name = "objc2-uniform-type-identifiers"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "44fa5f9748dbfe1ca6c0b79ad20725a11eca7c2218bceb4b005cb1be26273bfe"
+dependencies = [
+ "block2 0.5.1",
+ "objc2 0.5.3",
+ "objc2-foundation 0.2.2",
+]
+
+[[package]]
+name = "objc2-user-notifications"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "76cfcbf642358e8689af64cee815d139339f3ed8ad05103ed5eaf73db8d84cb3"
+dependencies = [
+ "bitflags 2.13.2",
+ "block2 0.5.1",
+ "objc2 0.5.3",
+ "objc2-core-location",
+ "objc2-foundation 0.2.2",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "openssl-probe"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7e036b411754132fd6b74e94b74e9a13c5cf606fa93d1885c35860d3060820b1"
+
+[[package]]
+name = "orbclient"
+version = "0.3.55"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5df339f526ea9a60e371768d50efc2f2508c7203290731565d1f7a6f71d21747"
+dependencies = [
+ "libc",
+ "libredox",
+]
+
+[[package]]
+name = "ordered-float"
+version = "5.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7f59006ce1e204c30956638535b74d317bca99477b9356dfaec54c37f6f600ab"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "ordered-stream"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9aa2b01e1d916879f73a53d01d1d6cee68adbb31d6d9177a8cfce093cced1d50"
+dependencies = [
+ "futures-core",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "owned_ttf_parser"
+version = "0.25.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "36820e9051aca1014ddc75770aab4d68bc1e9e632f0f5627c4086bc216fb583b"
+dependencies = [
+ "ttf-parser",
+]
+
+[[package]]
+name = "parking"
+version = "2.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f38d5652c16fde515bb1ecef450ab0f6a219d619a7274976324d5e377f7dceba"
+
+[[package]]
+name = "parking_lot"
+version = "0.12.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93857453250e3077bd71ff98b6a65ea6621a19bb0f559a85248955ac12c45a1a"
+dependencies = [
+ "lock_api",
+ "parking_lot_core",
+]
+
+[[package]]
+name = "parking_lot_core"
+version = "0.9.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2621685985a2ebf1c516881c026032ac7deafcda1a2c9b7850dc81e3dfcb64c1"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "redox_syscall 0.5.18",
+ "smallvec",
+ "windows-link",
+]
+
+[[package]]
+name = "paste"
+version = "1.0.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "57c0d7b74b563b49d38dae00a0c37d4d6de9b432382b2892f0574ddcae73fd0a"
+
+[[package]]
+name = "pastey"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2ee67f1008b1ba2321834326597b8e186293b049a023cdef258527550b9935b4"
+
+[[package]]
+name = "percent-encoding"
+version = "2.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
+
+[[package]]
+name = "pico-args"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5be167a7af36ee22fe3115051bc51f6e6c7054c9348e28deb4f49bd6f705a315"
+
+[[package]]
+name = "pin-project"
+version = "1.1.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2466b2336ed02bcdca6b294417127b90ec92038d1d5c4fbeac971a922e0e0924"
+dependencies = [
+ "pin-project-internal",
+]
+
+[[package]]
+name = "pin-project-internal"
+version = "1.1.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c96395f0a926bc13b1c17622aaddda1ecb55d49c8f1bf9777e4d877800a43f8b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "pin-project-lite"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
+
+[[package]]
+name = "pin-utils"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "13bee6c73da26345c729282832b60b0363cf3dd9f4bfd81d8551b7a1c889a113"
+
+[[package]]
+name = "piper"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c835479a4443ded371d6c535cbfd8d31ad92c5d23ae9770a61bc155e4992a3c1"
+dependencies = [
+ "atomic-waker",
+ "fastrand",
+ "futures-io",
+]
+
+[[package]]
+name = "pkg-config"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f6b464fbc74e149a392436b17d523f769e057cb6877f6a5c4618bc6f11800548"
+
+[[package]]
+name = "plain"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b4596b6d070b27117e987119b4dac604f3c58cfb0b191112e24771b2faeac1a6"
+
+[[package]]
+name = "png"
+version = "0.17.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "82151a2fc869e011c153adc57cf2789ccb8d9906ce52c0b39a6b5697749d7526"
+dependencies = [
+ "bitflags 1.3.2",
+ "crc32fast",
+ "fdeflate",
+ "flate2",
+ "miniz_oxide 0.8.9",
+]
+
+[[package]]
+name = "png"
+version = "0.18.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "60769b8b31b2a9f263dae2776c37b1b28ae246943cf719eb6946a1db05128a61"
+dependencies = [
+ "bitflags 2.13.2",
+ "crc32fast",
+ "fdeflate",
+ "flate2",
+ "miniz_oxide 0.8.9",
+]
+
+[[package]]
+name = "polling"
+version = "3.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5d0e4f59085d47d8241c88ead0f274e8a0cb551f3625263c05eb8dd897c34218"
+dependencies = [
+ "cfg-if",
+ "concurrent-queue",
+ "hermit-abi",
+ "pin-project-lite",
+ "rustix 1.1.6",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "portable-atomic"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85"
+
+[[package]]
+name = "portable-atomic-util"
+version = "0.2.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "10ab3eb7f3becc3a1cbc4f2c6f20267996cfc1a6467a873763411b136a122715"
+dependencies = [
+ "portable-atomic",
+]
+
+[[package]]
+name = "potential_utf"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d83eb9bc6d8e5cf568e7a1101d60ee05e81ed50ea106026f3d18deeb046d7661"
+dependencies = [
+ "zerovec",
+]
+
+[[package]]
+name = "ppv-lite86"
+version = "0.2.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9"
+dependencies = [
+ "zerocopy",
+]
+
+[[package]]
+name = "presser"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e8cf8e6a8aa66ce33f63993ffc4ea4271eb5b0530a9002db8455ea6050c77bfa"
+
+[[package]]
+name = "proc-macro-crate"
+version = "3.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e67ba7e9b2b56446f1d419b1d807906278ffa1a658a8a5d8a39dcb1f5a78614f"
+dependencies = [
+ "toml_edit",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "profiling"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d595e54a326bc53c1c197b32d295e14b169e3cfeaa8dc82b529f947fba6bcf5"
+
+[[package]]
+name = "pxfm"
+version = "0.1.30"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d55d956fa96f5ec02be2e13af0e20391a5aa83d6a074e3ad368959d0fab299ea"
+
+[[package]]
+name = "quick-error"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a993555f31e5a609f617c12db6250dedcac1b0a85076912c436e6fc9b2c8e6a3"
+
+[[package]]
+name = "quick-xml"
+version = "0.41.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e660451e55124f798a69a5af3f49ccfbefbd41910eefd25caf2393e1f3473ec1"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "quinn"
+version = "0.11.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4051e23e9185c255a7e33ef59cdbca87a22d359052eecd22fc6b901fb37d9d11"
+dependencies = [
+ "bytes",
+ "cfg_aliases",
+ "pin-project-lite",
+ "quinn-proto",
+ "quinn-udp",
+ "rustc-hash 2.1.3",
+ "rustls",
+ "socket2",
+ "thiserror 2.0.21",
+ "tokio",
+ "tracing",
+ "web-time",
+]
+
+[[package]]
+name = "quinn-proto"
+version = "0.11.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0e750cca55fe4f0439a15d0bb529da9651e79993e8e72c61a899a36d462befbe"
+dependencies = [
+ "aws-lc-rs",
+ "bytes",
+ "getrandom 0.4.3",
+ "lru-slab",
+ "rand 0.10.3",
+ "rand_pcg",
+ "ring",
+ "rustc-hash 2.1.3",
+ "rustls",
+ "rustls-pki-types",
+ "slab",
+ "thiserror 2.0.21",
+ "tinyvec",
+ "tracing",
+ "web-time",
+]
+
+[[package]]
+name = "quinn-udp"
+version = "0.5.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "af66907df18639dcf4db56ca65490cabc4b27a97dbadd96f2926cca73298f016"
+dependencies = [
+ "cfg_aliases",
+ "libc",
+ "once_cell",
+ "socket2",
+ "tracing",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "r-efi"
+version = "5.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f"
+
+[[package]]
+name = "r-efi"
+version = "6.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
+
+[[package]]
+name = "rand"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b9ef1d0d795eb7d84685bca4f72f3649f064e6641543d3a8c415898726a57b41"
+dependencies = [
+ "rand_chacha",
+ "rand_core 0.9.5",
+]
+
+[[package]]
+name = "rand"
+version = "0.10.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "65c9fb96cbc91e3478eaae79a69fcd3f1ae4ad052e471fe6732fff548984b4af"
+dependencies = [
+ "chacha20",
+ "getrandom 0.4.3",
+ "rand_core 0.10.1",
+]
+
+[[package]]
+name = "rand_chacha"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3022b5f1df60f26e1ffddd6c66e8aa15de382ae63b3a0c1bfc0e4d3e3f325cb"
+dependencies = [
+ "ppv-lite86",
+ "rand_core 0.9.5",
+]
+
+[[package]]
+name = "rand_core"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "76afc826de14238e6e8c374ddcc1fa19e374fd8dd986b0d2af0d02377261d83c"
+dependencies = [
+ "getrandom 0.3.4",
+]
+
+[[package]]
+name = "rand_core"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69"
+
+[[package]]
+name = "rand_pcg"
+version = "0.10.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "caa0f4137e1c0a72f4c651489402276c8e8e1cf081f3b0ba156d2cbeef09e86a"
+dependencies = [
+ "rand_core 0.10.1",
+]
+
+[[package]]
+name = "range-alloc"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ca45419789ae5a7899559e9512e58ca889e41f04f1f2445e9f4b290ceccd1d08"
+
+[[package]]
+name = "rangemap"
+version = "1.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a611d15b50743feb4c76b7d03edcb0e64f399c26961e4efe6975bc398be6aa3d"
+
+[[package]]
+name = "raw-window-handle"
+version = "0.6.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "20675572f6f24e9e76ef639bc5552774ed45f1c30e2951e1e99c59888861c539"
+
+[[package]]
+name = "read-fonts"
+version = "0.35.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6717cf23b488adf64b9d711329542ba34de147df262370221940dfabc2c91358"
+dependencies = [
+ "bytemuck",
+ "core_maths",
+ "font-types 0.10.1",
+]
+
+[[package]]
+name = "read-fonts"
+version = "0.41.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "046a7d674daf459825b32f5062056d6882db0d2f5a479fbd76ccfc870ac18709"
+dependencies = [
+ "bytemuck",
+ "font-types 0.12.7",
+ "once_cell",
+]
+
+[[package]]
+name = "redox_syscall"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4722d768eff46b75989dd134e5c353f0d6296e5aaa3132e776cbdb56be7731aa"
+dependencies = [
+ "bitflags 1.3.2",
+]
+
+[[package]]
+name = "redox_syscall"
+version = "0.5.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d"
+dependencies = [
+ "bitflags 2.13.2",
+]
+
+[[package]]
+name = "redox_syscall"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "580c875845b41ecb1564ad1ae4703044cef774145e3d7a94dc2b3fa7c97868fd"
+dependencies = [
+ "bitflags 2.13.2",
+]
+
+[[package]]
+name = "ref-cast"
+version = "1.0.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7e440fb4e4b4147295338efb76001ab9e4efc0e5839df2c47fc5ac2381d365c3"
+dependencies = [
+ "ref-cast-impl",
+]
+
+[[package]]
+name = "ref-cast-impl"
+version = "1.0.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92ecd8964f8453721699a1ed72037b0db49ce2f5a5138486ee89bed6f67cdf3a"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.9",
+]
+
+[[package]]
+name = "regex"
+version = "1.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-automata",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-automata"
+version = "0.4.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-syntax"
+version = "0.8.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
+
+[[package]]
+name = "renderdoc-sys"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "19b30a45b0cd0bcca8037f3d0dc3421eaf95327a17cad11964fb8179b4fc4832"
+
+[[package]]
+name = "reqwest"
+version = "0.12.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eddd3ca559203180a307f12d114c268abf583f59b03cb906fd0b3ff8646c1147"
+dependencies = [
+ "base64 0.22.1",
+ "bytes",
+ "futures-core",
+ "futures-util",
+ "http",
+ "http-body",
+ "http-body-util",
+ "hyper",
+ "hyper-rustls",
+ "hyper-util",
+ "js-sys",
+ "log",
+ "percent-encoding",
+ "pin-project-lite",
+ "quinn",
+ "rustls",
+ "rustls-pki-types",
+ "serde",
+ "serde_json",
+ "serde_urlencoded",
+ "sync_wrapper",
+ "tokio",
+ "tokio-rustls",
+ "tokio-util",
+ "tower",
+ "tower-http",
+ "tower-service",
+ "url",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "wasm-streams 0.4.2",
+ "web-sys",
+ "webpki-roots 1.0.11",
+]
+
+[[package]]
+name = "reqwest"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "16a1cfa75cc186dd73d5818e510e042e40927bccc9c236b061cea97e1eb08029"
+dependencies = [
+ "base64 0.23.1",
+ "bytes",
+ "encoding_rs",
+ "futures-core",
+ "futures-util",
+ "h2",
+ "http",
+ "http-body",
+ "http-body-util",
+ "hyper",
+ "hyper-rustls",
+ "hyper-util",
+ "js-sys",
+ "log",
+ "mime",
+ "mime_guess",
+ "percent-encoding",
+ "pin-project-lite",
+ "quinn",
+ "rustls",
+ "rustls-pki-types",
+ "rustls-platform-verifier",
+ "serde",
+ "serde_json",
+ "sync_wrapper",
+ "tokio",
+ "tokio-rustls",
+ "tokio-util",
+ "tower",
+ "tower-http",
+ "tower-service",
+ "url",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "wasm-streams 0.5.0",
+ "web-sys",
+]
+
+[[package]]
+name = "resvg"
+version = "0.45.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a8928798c0a55e03c9ca6c4c6846f76377427d2c1e1f7e6de3c06ae57942df43"
+dependencies = [
+ "gif",
+ "image-webp",
+ "log",
+ "pico-args",
+ "rgb",
+ "svgtypes",
+ "tiny-skia",
+ "usvg",
+ "zune-jpeg 0.4.21",
+]
+
+[[package]]
+name = "rgb"
+version = "0.8.53"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "47b34b781b31e5d73e9fbc8689c70551fd1ade9a19e3e28cfec8580a79290cc4"
+dependencies = [
+ "bytemuck",
+]
+
+[[package]]
+name = "rig-agent"
+version = "0.45.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "856f21ab95b8b887df997fb34356aeb1ad5677504461f009c58cd7d48274ef74"
+dependencies = [
+ "async-stream",
+ "futures",
+ "http",
+ "indexmap",
+ "rig-core",
+ "rig-derive",
+ "rig-memory",
+ "schemars",
+ "serde",
+ "serde_json",
+ "thiserror 2.0.21",
+ "tracing",
+ "tracing-futures",
+]
+
+[[package]]
+name = "rig-core"
+version = "0.45.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0d07ae8e85415d83f620eb4f519d03126227178ac67971b08368c087ce8f9052"
+dependencies = [
+ "async-stream",
+ "base64 0.22.1",
+ "bytes",
+ "fastrand",
+ "futures",
+ "glob",
+ "http",
+ "httpdate",
+ "indexmap",
+ "mime",
+ "mime_guess",
+ "ordered-float",
+ "rig-derive",
+ "rig-http",
+ "rig-reqwest",
+ "rig-tungstenite",
+ "schemars",
+ "serde",
+ "serde_json",
+ "serde_path_to_error",
+ "sha2",
+ "thiserror 2.0.21",
+ "tracing",
+ "url",
+ "uuid",
+ "web-time",
+]
+
+[[package]]
+name = "rig-derive"
+version = "0.45.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "840ef7200097f7e7b7f757f09a80b2ffb494438fca12ad6c84a15ddffc9647d3"
+dependencies = [
+ "convert_case",
+ "proc-macro-crate",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "rig-http"
+version = "0.45.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "817c761f9949151fd099ec78e2fbacf7174f24c066ced84c9d28807a6b9d4cee"
+dependencies = [
+ "bytes",
+ "futures",
+ "futures-timer",
+ "http",
+ "mime",
+ "thiserror 2.0.21",
+ "tokio",
+ "url",
+]
+
+[[package]]
+name = "rig-memory"
+version = "0.45.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d25fcf3f3a478d3ac1c0329aca68fdcb94c87cc32e6f2161463fae65270d58ec"
+dependencies = [
+ "base64 0.22.1",
+ "memchr",
+ "rig-core",
+ "serde",
+ "serde_json",
+ "sha2",
+ "thiserror 2.0.21",
+]
+
+[[package]]
+name = "rig-reqwest"
+version = "0.45.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c9f13e51c8cbe597ab4ed79f4a1211dab83ac3d9ceaa3826d69b5c770274b9fa"
+dependencies = [
+ "bytes",
+ "futures",
+ "http",
+ "reqwest 0.13.5",
+ "rig-http",
+ "thiserror 2.0.21",
+ "tracing",
+ "url",
+ "webpki-root-certs",
+]
+
+[[package]]
+name = "rig-tungstenite"
+version = "0.45.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4ba7906f696aee0da3d24825330bb5ff2cf2af86d8e308120f81d9cf581d1e30"
+dependencies = [
+ "futures",
+ "rig-http",
+ "thiserror 2.0.21",
+ "tokio",
+ "tokio-tungstenite",
+]
+
+[[package]]
+name = "ring"
+version = "0.17.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a4689e6c2294d81e88dc6261c768b63bc4fcdb852be6d1352498b114f61383b7"
+dependencies = [
+ "cc",
+ "cfg-if",
+ "getrandom 0.2.17",
+ "libc",
+ "untrusted",
+ "windows-sys 0.52.0",
+]
+
+[[package]]
+name = "rmcp"
+version = "3.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8be15815186873ea063bf005011d16c356804973489e40c39116ae3a2878d1f"
+dependencies = [
+ "async-trait",
+ "base64 0.23.1",
+ "bytes",
+ "chrono",
+ "futures",
+ "http",
+ "http-body",
+ "http-body-util",
+ "indexmap",
+ "libc",
+ "pastey",
+ "pin-project-lite",
+ "rand 0.10.3",
+ "rmcp-macros",
+ "schemars",
+ "serde",
+ "serde_json",
+ "sse-stream",
+ "thiserror 2.0.21",
+ "tokio",
+ "tokio-stream",
+ "tokio-util",
+ "tower-service",
+ "tracing",
+ "uuid",
+]
+
+[[package]]
+name = "rmcp-macros"
+version = "3.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b0748e054a5f5598b3213cf72099ae6b2745ba4d996c59ccf455150a7dbb839"
+dependencies = [
+ "darling",
+ "proc-macro2",
+ "quote",
+ "serde_json",
+ "syn 3.0.9",
+]
+
+[[package]]
+name = "roxmltree"
+version = "0.20.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6c20b6793b5c2fa6553b250154b78d6d0db37e72700ae35fad9387a46f487c97"
+
+[[package]]
+name = "rustc-hash"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "08d43f7aa6b08d49f382cde6a7982047c3426db949b1424bc4b7ec9ae12c6ce2"
+
+[[package]]
+name = "rustc-hash"
+version = "2.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"
+
+[[package]]
+name = "rustc_version"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cfcb3a22ef46e85b45de6ee7e79d063319ebb6594faafcf1c225ea92ab6e9b92"
+dependencies = [
+ "semver",
+]
+
+[[package]]
+name = "rustix"
+version = "0.38.44"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fdb5bc1ae2baa591800df16c9ca78619bf65c0488b41b96ccec5d11220d8c154"
+dependencies = [
+ "bitflags 2.13.2",
+ "errno",
+ "libc",
+ "linux-raw-sys 0.4.15",
+ "windows-sys 0.59.0",
+]
+
+[[package]]
+name = "rustix"
+version = "1.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e5e76742e5294153d4dde1207dbec5bdd81eef6fabdc0d2118babadabfd858aa"
+dependencies = [
+ "bitflags 2.13.2",
+ "errno",
+ "libc",
+ "linux-raw-sys 0.12.1",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "rustls"
+version = "0.23.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "48e13bd8c0e9365c43cfa5c9e8f9ad49d3c8444926c9aac819e0e4dc503c8fdf"
+dependencies = [
+ "aws-lc-rs",
+ "once_cell",
+ "ring",
+ "rustls-pki-types",
+ "rustls-webpki",
+ "subtle",
+ "zeroize",
+]
+
+[[package]]
+name = "rustls-native-certs"
+version = "0.8.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4a073f5dc7469f984c52ad2752b63b0807745133b6de880b7b64c1ac4c48aec4"
+dependencies = [
+ "openssl-probe",
+ "rustls-pki-types",
+ "schannel",
+ "security-framework",
+]
+
+[[package]]
+name = "rustls-pki-types"
+version = "1.15.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2f4925028c7eb5d1fcdaf196971378ed9d2c1c4efc7dc5d011256f76c99c0a96"
+dependencies = [
+ "web-time",
+ "zeroize",
+]
+
+[[package]]
+name = "rustls-platform-verifier"
+version = "0.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1167586491e2b18b8bfbb293e8180ec17c201c4f076d7cb3070ca964e7598f98"
+dependencies = [
+ "core-foundation 0.10.1",
+ "core-foundation-sys",
+ "jni",
+ "log",
+ "once_cell",
+ "rustls",
+ "rustls-native-certs",
+ "rustls-platform-verifier-android",
+ "rustls-webpki",
+ "security-framework",
+ "security-framework-sys",
+ "webpki-root-certs",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "rustls-platform-verifier-android"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eec689c0bc40ff2458a5977b6619cb718087084a18e02a131c599b62d05e1a5f"
+
+[[package]]
+name = "rustls-webpki"
+version = "0.103.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4443b1b6d39d7c663139942cc4558262562d2c84123bb6282ef177009ca8b281"
+dependencies = [
+ "aws-lc-rs",
+ "ring",
+ "rustls-pki-types",
+ "untrusted",
+]
+
+[[package]]
+name = "rustversion"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
+
+[[package]]
+name = "rustybuzz"
+version = "0.20.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fd3c7c96f8a08ee34eff8857b11b49b07d71d1c3f4e88f8a88d4c9e9f90b1702"
+dependencies = [
+ "bitflags 2.13.2",
+ "bytemuck",
+ "core_maths",
+ "log",
+ "smallvec",
+ "ttf-parser",
+ "unicode-bidi-mirroring",
+ "unicode-ccc",
+ "unicode-properties",
+ "unicode-script",
+]
+
+[[package]]
+name = "ryu"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f"
+
+[[package]]
+name = "same-file"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93fc1dc3aaa9bfed95e02e6eadabb4baf7e3078b0bd1b4d7b6b0b68378900502"
+dependencies = [
+ "winapi-util",
+]
+
+[[package]]
+name = "schannel"
+version = "0.1.30"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9cb23c424d8ee841bb4d813677ca237e2a610067d594fec130f87d6093495ab5"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "schemars"
+version = "1.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ab508826f74a77ca9d5aba6ff19b522583ee3eaf28a19384ff3d0e5835fadf6e"
+dependencies = [
+ "chrono",
+ "dyn-clone",
+ "ref-cast",
+ "schemars_derive",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "schemars_derive"
+version = "1.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e1c3a92094fa7d61aa124645844facb6b554dfc797136d0f5fd1f890e2bffc69"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "serde_derive_internals",
+ "syn 3.0.9",
+]
+
+[[package]]
+name = "scoped-tls"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e1cf6437eb19a8f4a6cc0f7dca544973b0b78843adbfeb3683d1a94a0024a294"
+
+[[package]]
+name = "scopeguard"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
+
+[[package]]
+name = "sctk-adwaita"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6277f0217056f77f1d8f49f2950ac6c278c0d607c45f5ee99328d792ede24ec"
+dependencies = [
+ "ab_glyph",
+ "log",
+ "memmap2",
+ "smithay-client-toolkit 0.19.2",
+ "tiny-skia",
+]
+
+[[package]]
+name = "security-framework"
+version = "3.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b7f4bc775c73d9a02cde8bf7b2ec4c9d12743edf609006c7facc23998404cd1d"
+dependencies = [
+ "bitflags 2.13.2",
+ "core-foundation 0.10.1",
+ "core-foundation-sys",
+ "libc",
+ "security-framework-sys",
+]
+
+[[package]]
+name = "security-framework-sys"
+version = "2.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ce2691df843ecc5d231c0b14ece2acc3efb62c0a398c7e1d875f3983ce020e3"
+dependencies = [
+ "core-foundation-sys",
+ "libc",
+]
+
+[[package]]
+name = "self_cell"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2ab42ca02749e120097e328d91d415325bdf43b1c72c4c8badf37375fe40a813"
+
+[[package]]
+name = "semver"
+version = "1.0.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd"
+
+[[package]]
+name = "send_wrapper"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cd0b0ec5f1c1ca621c432a25813d8d60c88abe6d3e08a3eb9cf37d97a0fe3d73"
+
+[[package]]
+name = "serde"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.9",
+]
+
+[[package]]
+name = "serde_derive_internals"
+version = "0.30.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f852137cce035d6a4df67ccce505ff6b3e9fd3a10e3e52b24dc71e650bb1a9bd"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.9",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.154"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6"
+dependencies = [
+ "foldhash 0.2.0",
+ "indexmap",
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "serde_path_to_error"
+version = "0.1.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "10a9ff822e371bb5403e391ecd83e182e0e77ba7f6fe0160b795797109d1b457"
+dependencies = [
+ "itoa",
+ "serde",
+ "serde_core",
+]
+
+[[package]]
+name = "serde_repr"
+version = "0.1.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8d3b1629de253c70a0508c3899572da79ca359fdab27c7920ff00406df418906"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.9",
+]
+
+[[package]]
+name = "serde_urlencoded"
+version = "0.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3491c14715ca2294c4d6a88f15e84739788c1d030eed8c110436aafdaa2f3fd"
+dependencies = [
+ "form_urlencoded",
+ "itoa",
+ "ryu",
+ "serde",
+]
+
+[[package]]
+name = "serde_yaml_ng"
+version = "0.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7b4db627b98b36d4203a7b458cf3573730f2bb591b28871d916dfa9efabfd41f"
+dependencies = [
+ "indexmap",
+ "itoa",
+ "ryu",
+ "serde",
+ "unsafe-libyaml",
+]
+
+[[package]]
+name = "sha1"
+version = "0.10.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a978451301f4db1d02937a4ab3ccce137717b81826e79b7d49ffe3244a13c3b8"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.2.17",
+ "digest",
+]
+
+[[package]]
+name = "sha2"
+version = "0.10.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.2.17",
+ "digest",
+]
+
+[[package]]
+name = "shlex"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
+
+[[package]]
+name = "signal-hook-registry"
+version = "1.4.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c4db69cba1110affc0e9f7bcd48bbf87b3f4fc7c61fc9155afd4c469eb3d6c1b"
+dependencies = [
+ "errno",
+ "libc",
+]
+
+[[package]]
+name = "simd-adler32"
+version = "0.3.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea"
+
+[[package]]
+name = "simd_cesu8"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "11031e251abf8611c80f460e19dbdeb54a66db918e49c65a7065b46ac7aec520"
+dependencies = [
+ "rustc_version",
+ "simdutf8",
+]
+
+[[package]]
+name = "simdutf8"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e3a9fe34e3e7a50316060351f37187a3f546bce95496156754b601a5fa71b76e"
+
+[[package]]
+name = "simplecss"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7a9c6883ca9c3c7c90e888de77b7a5c849c779d25d74a1269b0218b14e8b136c"
+dependencies = [
+ "log",
+]
+
+[[package]]
+name = "siphasher"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "33f4fe9184a62d842c9ef383018f3306d8ba224fd9d836f56d7288308847c256"
+
+[[package]]
+name = "skrifa"
+version = "0.37.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8c31071dedf532758ecf3fed987cdb4bd9509f900e026ab684b4ecb81ea49841"
+dependencies = [
+ "bytemuck",
+ "read-fonts 0.35.0",
+]
+
+[[package]]
+name = "skrifa"
+version = "0.44.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "819ab7d62b1d3e72d9d9dea5650bac30424f9111364bb94928dbf5ecad1baa68"
+dependencies = [
+ "bytemuck",
+ "read-fonts 0.41.0",
+]
+
+[[package]]
+name = "slab"
+version = "0.4.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
+
+[[package]]
+name = "slotmap"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bdd58c3c93c3d278ca835519292445cb4b0d4dc59ccfdf7ceadaab3f8aeb4038"
+dependencies = [
+ "version_check",
+]
+
+[[package]]
+name = "smallvec"
+version = "1.16.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d0d5d4b1981b8bbbb7aed204cae5726d683d5d6ac7e74ec54122ea28f315e7c8"
+
+[[package]]
+name = "smithay-client-toolkit"
+version = "0.19.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3457dea1f0eb631b4034d61d4d8c32074caa6cd1ab2d59f2327bd8461e2c0016"
+dependencies = [
+ "bitflags 2.13.2",
+ "calloop 0.13.0",
+ "calloop-wayland-source 0.3.0",
+ "cursor-icon",
+ "libc",
+ "log",
+ "memmap2",
+ "rustix 0.38.44",
+ "thiserror 1.0.69",
+ "wayland-backend",
+ "wayland-client",
+ "wayland-csd-frame",
+ "wayland-cursor",
+ "wayland-protocols",
+ "wayland-protocols-wlr",
+ "wayland-scanner",
+ "xkeysym",
+]
+
+[[package]]
+name = "smithay-client-toolkit"
+version = "0.20.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0512da38f5e2b31201a93524adb8d3136276fa4fe4aafab4e1f727a82b534cc0"
+dependencies = [
+ "bitflags 2.13.2",
+ "calloop 0.14.5",
+ "calloop-wayland-source 0.4.1",
+ "cursor-icon",
+ "libc",
+ "log",
+ "memmap2",
+ "rustix 1.1.6",
+ "thiserror 2.0.21",
+ "wayland-backend",
+ "wayland-client",
+ "wayland-csd-frame",
+ "wayland-cursor",
+ "wayland-protocols",
+ "wayland-protocols-experimental",
+ "wayland-protocols-misc",
+ "wayland-protocols-wlr",
+ "wayland-scanner",
+ "xkeysym",
+]
+
+[[package]]
+name = "smithay-clipboard"
+version = "0.7.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "71704c03f739f7745053bde45fa203a46c58d25bc5c4efba1d9a60e9dba81226"
+dependencies = [
+ "libc",
+ "smithay-client-toolkit 0.20.0",
+ "wayland-backend",
+]
+
+[[package]]
+name = "smol_str"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dd538fb6910ac1099850255cf94a94df6551fbdd602454387d0adb2d1ca6dead"
+dependencies = [
+ "serde",
+]
+
+[[package]]
+name = "socket2"
+version = "0.6.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c3d1e2c7f27f8d4cb10542a02c49005dbd6e93095799d6f3be745fae9f8fedd4"
+dependencies = [
+ "libc",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "softbuffer"
+version = "0.4.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "aac18da81ebbf05109ab275b157c22a653bb3c12cf884450179942f81bcbf6c3"
+dependencies = [
+ "as-raw-xcb-connection",
+ "bytemuck",
+ "fastrand",
+ "js-sys",
+ "memmap2",
+ "ndk",
+ "objc2 0.6.5",
+ "objc2-core-foundation",
+ "objc2-core-graphics",
+ "objc2-foundation 0.3.2",
+ "objc2-quartz-core 0.3.2",
+ "raw-window-handle",
+ "redox_syscall 0.5.18",
+ "rustix 1.1.6",
+ "tiny-xlib",
+ "tracing",
+ "wasm-bindgen",
+ "wayland-backend",
+ "wayland-client",
+ "wayland-sys",
+ "web-sys",
+ "windows-sys 0.61.2",
+ "x11rb",
+]
+
+[[package]]
+name = "spirv"
+version = "0.3.0+sdk-1.3.268.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eda41003dc44290527a59b13432d4a0379379fa074b70174882adfbdfd917844"
+dependencies = [
+ "bitflags 2.13.2",
+]
+
+[[package]]
+name = "sse-stream"
+version = "0.2.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c25ac7aff0abd1dbc474536e40416e1102c7dd9bfba0b9861c6d357f835dcfb4"
+dependencies = [
+ "bytes",
+ "futures-util",
+ "http-body",
+ "http-body-util",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "stable_deref_trait"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
+
+[[package]]
+name = "static_assertions"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2eb9349b6444b326872e140eb1cf5e7c522154d69e7a0ffb0fb81c06b37543f"
+
+[[package]]
+name = "strict-num"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6637bab7722d379c8b41ba849228d680cc12d0a45ba1fa2b48f2a30577a06731"
+dependencies = [
+ "float-cmp",
+]
+
+[[package]]
+name = "strsim"
+version = "0.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
+
+[[package]]
+name = "subtle"
+version = "2.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292"
+
+[[package]]
+name = "svg_fmt"
+version = "0.4.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0193cc4331cfd2f3d2011ef287590868599a2f33c3e69bc22c1a3d3acf9e02fb"
+
+[[package]]
+name = "svgtypes"
+version = "0.15.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68c7541fff44b35860c1a7a47a7cadf3e4a304c457b58f9870d9706ece028afc"
+dependencies = [
+ "kurbo 0.11.3",
+ "siphasher",
+]
+
+[[package]]
+name = "swash"
+version = "0.2.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6c2499c2d826531388872b2268718aed907a39bd785ab0dcfe57fab26283f92e"
+dependencies = [
+ "skrifa 0.44.0",
+ "yazi",
+ "zeno",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "sync_wrapper"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0bf256ce5efdfa370213c1dabab5935a12e49f2c58d15e9eac2870d3b4f27263"
+dependencies = [
+ "futures-core",
+]
+
+[[package]]
+name = "synstructure"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "901704edd0dfe137f1987838ee4f259e4e063c31371bdb423f7ae38ec6f77f02"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.9",
+]
+
+[[package]]
+name = "sys-locale"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8eab9a99a024a169fe8a903cf9d4a3b3601109bcc13bd9e3c6fff259138626c4"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "system-configuration"
+version = "0.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a13f3d0daba03132c0aa9767f98351b3488edc2c100cda2d2ec2b04f3d8d3c8b"
+dependencies = [
+ "bitflags 2.13.2",
+ "core-foundation 0.9.4",
+ "system-configuration-sys",
+]
+
+[[package]]
+name = "system-configuration-sys"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e1d1b10ced5ca923a1fcb8d03e96b8d3268065d724548c0211415ff6ac6bac4"
+dependencies = [
+ "core-foundation-sys",
+ "libc",
+]
+
+[[package]]
+name = "tar"
+version = "0.4.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f6221d9a6003c78398e3b239969f352578258df48c8eb051caadae0015bc840"
+dependencies = [
+ "filetime",
+ "libc",
+ "xattr",
+]
+
+[[package]]
+name = "tempfile"
+version = "3.27.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
+dependencies = [
+ "fastrand",
+ "getrandom 0.4.3",
+ "once_cell",
+ "rustix 1.1.6",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "termcolor"
+version = "1.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "06794f8f6c5c898b3275aebefa6b8a1cb24cd2c6c79397ab15774837a0bc5755"
+dependencies = [
+ "winapi-util",
+]
+
+[[package]]
+name = "thiserror"
+version = "1.0.69"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6aaf5339b578ea85b50e080feb250a3e8ae8cfcdff9a461c9ec2904bc923f52"
+dependencies = [
+ "thiserror-impl 1.0.69",
+]
+
+[[package]]
+name = "thiserror"
+version = "2.0.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09e52cb86a36cede5cb101bf8908837b3e4c6e5e59fe7fd85c23fb56200d189e"
+dependencies = [
+ "thiserror-impl 2.0.21",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "1.0.69"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "2.0.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fe5197923287db20a58125f0bc85c062f7f2c892de97b18c356f9efb14b28524"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.9",
+]
+
+[[package]]
+name = "tiny-skia"
+version = "0.11.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "83d13394d44dae3207b52a326c0c85a8bf87f1541f23b0d143811088497b09ab"
+dependencies = [
+ "arrayref",
+ "arrayvec",
+ "bytemuck",
+ "cfg-if",
+ "log",
+ "png 0.17.16",
+ "tiny-skia-path",
+]
+
+[[package]]
+name = "tiny-skia-path"
+version = "0.11.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9c9e7fc0c2e86a30b117d0462aa261b72b7a99b7ebd7deb3a14ceda95c5bdc93"
+dependencies = [
+ "arrayref",
+ "bytemuck",
+ "strict-num",
+]
+
+[[package]]
+name = "tiny-xlib"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a90a0ca3ee6a69f2ad28fd11621a4c3f03b371f366be500b64df260c4ffbafb4"
+dependencies = [
+ "as-raw-xcb-connection",
+ "ctor",
+ "libloading",
+ "pkg-config",
+ "tracing",
+]
+
+[[package]]
+name = "tinystr"
+version = "0.8.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "abc840c238154d58f9e86b2792261edfde565a17696e1cda1a449de27979801a"
+dependencies = [
+ "displaydoc",
+ "zerovec",
+]
+
+[[package]]
+name = "tinyvec"
+version = "1.13.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fd3ca314f692efd6c868f8408f53fe444634a845f96c028b97d35f6a1f79f0ee"
+
+[[package]]
+name = "tokio"
+version = "1.54.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b52fd3255258d26fac7264ab5a76b53c13367136dc011d3d6ad4f8ed070396a3"
+dependencies = [
+ "bytes",
+ "libc",
+ "mio",
+ "pin-project-lite",
+ "socket2",
+ "tokio-macros",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "tokio-macros"
+version = "2.7.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "78773a2a397f451582ce068015985c33193cf6dea8b74d2a639fe457b2f07b0e"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.9",
+]
+
+[[package]]
+name = "tokio-rustls"
+version = "0.26.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c9cc2678c2cdd569ef8215e2afd7954ada2ae20b4fdd2c5fe6139a3b02d105db"
+dependencies = [
+ "rustls",
+ "tokio",
+]
+
+[[package]]
+name = "tokio-stream"
+version = "0.1.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a3d06f0b082ba57c26b79407372e57cf2a1e28124f78e9479fe80322cf53420b"
+dependencies = [
+ "futures-core",
+ "pin-project-lite",
+ "tokio",
+]
+
+[[package]]
+name = "tokio-tungstenite"
+version = "0.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f72a05e828585856dacd553fba484c242c46e391fb0e58917c942ee9202915c"
+dependencies = [
+ "futures-util",
+ "log",
+ "rustls",
+ "rustls-pki-types",
+ "tokio",
+ "tokio-rustls",
+ "tungstenite",
+ "webpki-roots 0.26.11",
+]
+
+[[package]]
+name = "tokio-util"
+version = "0.7.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e464cf451ba96ebfc6f9b6542f17ee8b8956e33f1e40d9690624e59d7a7f8a4b"
+dependencies = [
+ "bytes",
+ "futures-core",
+ "futures-sink",
+ "libc",
+ "pin-project-lite",
+ "tokio",
+]
+
+[[package]]
+name = "toml_datetime"
+version = "1.1.2+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2b86d767906c6c42421dcba507eb9d203e779497710a47782a224bb871653053"
+dependencies = [
+ "serde_core",
+]
+
+[[package]]
+name = "toml_edit"
+version = "0.25.17+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e3641d5bbb5349a79e1020a242d251efbc546ad8048d133958323ce9c40a9c9c"
+dependencies = [
+ "indexmap",
+ "toml_datetime",
+ "toml_parser",
+ "winnow",
+]
+
+[[package]]
+name = "toml_parser"
+version = "1.1.5+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "baa693a8032d7e1cada7d0041e96126df243179ff061456783ac7f12bda4744c"
+dependencies = [
+ "winnow",
+]
+
+[[package]]
+name = "tower"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ebe5ef63511595f1344e2d5cfa636d973292adc0eec1f0ad45fae9f0851ab1d4"
+dependencies = [
+ "futures-core",
+ "futures-util",
+ "pin-project-lite",
+ "sync_wrapper",
+ "tokio",
+ "tower-layer",
+ "tower-service",
+ "tracing",
+]
+
+[[package]]
+name = "tower-http"
+version = "0.6.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4cfcf7e2740e6fc6d4d688b4ef00650406bb94adf4731e43c096c3a19fe40840"
+dependencies = [
+ "bitflags 2.13.2",
+ "bytes",
+ "futures-util",
+ "http",
+ "http-body",
+ "pin-project-lite",
+ "tower",
+ "tower-layer",
+ "tower-service",
+ "url",
+]
+
+[[package]]
+name = "tower-layer"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "121c2a6cda46980bb0fcd1647ffaf6cd3fc79a013de288782836f6df9c48780e"
+
+[[package]]
+name = "tower-service"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8df9b6e13f2d32c91b9bd719c00d1958837bc7dec474d94952798cc8e69eeec3"
+
+[[package]]
+name = "tracing"
+version = "0.1.44"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"
+dependencies = [
+ "log",
+ "pin-project-lite",
+ "tracing-attributes",
+ "tracing-core",
+]
+
+[[package]]
+name = "tracing-attributes"
+version = "0.1.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "tracing-core"
+version = "0.1.36"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a"
+dependencies = [
+ "once_cell",
+]
+
+[[package]]
+name = "tracing-futures"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "97d095ae15e245a057c8e8451bab9b3ee1e1f68e9ba2b4fbc18d0ac5237835f2"
+dependencies = [
+ "futures",
+ "futures-task",
+ "pin-project",
+ "tracing",
+]
+
+[[package]]
+name = "try-lock"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"
+
+[[package]]
+name = "ttf-parser"
+version = "0.25.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d2df906b07856748fa3f6e0ad0cbaa047052d4a7dd609e231c4f72cee8c36f31"
+dependencies = [
+ "core_maths",
+]
+
+[[package]]
+name = "tungstenite"
+version = "0.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6c01152af293afb9c7c2a57e4b559c5620b421f6d133261c60dd2d0cdb38e6b8"
+dependencies = [
+ "bytes",
+ "data-encoding",
+ "http",
+ "httparse",
+ "log",
+ "rand 0.9.5",
+ "rustls",
+ "rustls-pki-types",
+ "sha1",
+ "thiserror 2.0.21",
+]
+
+[[package]]
+name = "typed-path"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ce898823d8cd0f028662d2f349694b1af0a5cc9be83f1d213a00d3147445e1e"
+
+[[package]]
+name = "typenum"
+version = "1.20.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20"
+
+[[package]]
+name = "uds_windows"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2f6fb2847f6742cd76af783a2a2c49e9375d0a111c7bef6f71cd9e738c72d6e"
+dependencies = [
+ "memoffset",
+ "tempfile",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "unicase"
+version = "2.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "357cc3acc6a036009fd6c973ed009037c732d60d0b4f6c673e9041497482a28f"
+
+[[package]]
+name = "unicode-bidi"
+version = "0.3.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c1cb5db39152898a79168971543b1cb5020dff7fe43c8dc468b0885f5e29df5"
+
+[[package]]
+name = "unicode-bidi-mirroring"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5dfa6e8c60bb66d49db113e0125ee8711b7647b5579dc7f5f19c42357ed039fe"
+
+[[package]]
+name = "unicode-ccc"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ce61d488bcdc9bc8b5d1772c404828b17fc481c0a582b5581e95fb233aef503e"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"
+
+[[package]]
+name = "unicode-linebreak"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b09c83c3c29d37506a3e260c08c03743a6bb66a9cd432c6934ab501a190571f"
+
+[[package]]
+name = "unicode-properties"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "993ad287eb20e8ba755312801cfe1413e0f25d604075863acaddca10b04c1833"
+
+[[package]]
+name = "unicode-script"
+version = "0.5.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "383ad40bb927465ec0ce7720e033cb4ca06912855fc35db31b5755d0de75b1ee"
+
+[[package]]
+name = "unicode-segmentation"
+version = "1.13.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c6f5d3c3b1bf09027a88a6bc961fc00497d651009560b5463668dc81b0fa87a8"
+
+[[package]]
+name = "unicode-vo"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b1d386ff53b415b7fe27b50bb44679e2cc4660272694b7b6f3326d8480823a94"
+
+[[package]]
+name = "unicode-width"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ca718471876992059f251e33aafc334346ada08042b7661dd1fe313a9bced557"
+
+[[package]]
+name = "unlucky-agent"
+version = "0.2.0"
+dependencies = [
+ "axum",
+ "futures-util",
+ "rig-agent",
+ "rig-core",
+ "rmcp",
+ "serde",
+ "serde_json",
+ "tokio",
+ "unlucky-core",
+]
+
+[[package]]
+name = "unlucky-app-iced"
+version = "0.2.0"
+dependencies = [
+ "iced",
+ "image",
+ "log",
+ "unlucky-cli",
+ "unlucky-design",
+ "unlucky-i18n",
+ "unlucky-presenter",
+]
+
+[[package]]
+name = "unlucky-cli"
+version = "0.2.0"
+dependencies = [
+ "serde",
+ "serde_json",
+ "tokio",
+ "unlucky-agent",
+ "unlucky-core",
+]
+
+[[package]]
+name = "unlucky-core"
+version = "0.2.0"
+dependencies = [
+ "flate2",
+ "futures-util",
+ "md-5",
+ "regex",
+ "reqwest 0.12.28",
+ "serde",
+ "serde_json",
+ "serde_yaml_ng",
+ "sha1",
+ "sha2",
+ "tar",
+ "tokio",
+ "zip",
+]
+
+[[package]]
+name = "unlucky-design"
+version = "0.2.0"
+
+[[package]]
+name = "unlucky-i18n"
+version = "0.2.0"
+
+[[package]]
+name = "unlucky-palette-extract"
+version = "0.2.0"
+dependencies = [
+ "image",
+ "unlucky-design",
+]
+
+[[package]]
+name = "unlucky-presenter"
+version = "0.2.0"
+dependencies = [
+ "serde",
+ "serde_json",
+ "unlucky-core",
+]
+
+[[package]]
+name = "unsafe-libyaml"
+version = "0.2.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "673aac59facbab8a9007c7f6108d11f63b603f7cabff99fabf650fea5c32b861"
+
+[[package]]
+name = "untrusted"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1"
+
+[[package]]
+name = "url"
+version = "2.5.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff67a8a4397373c3ef660812acab3268222035010ab8680ec4215f38ba3d0eed"
+dependencies = [
+ "form_urlencoded",
+ "idna",
+ "percent-encoding",
+ "serde",
+]
+
+[[package]]
+name = "usvg"
+version = "0.45.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "80be9b06fbae3b8b303400ab20778c80bbaf338f563afe567cf3c9eea17b47ef"
+dependencies = [
+ "base64 0.22.1",
+ "data-url",
+ "flate2",
+ "fontdb",
+ "imagesize",
+ "kurbo 0.11.3",
+ "log",
+ "pico-args",
+ "roxmltree",
+ "rustybuzz",
+ "simplecss",
+ "siphasher",
+ "strict-num",
+ "svgtypes",
+ "tiny-skia-path",
+ "unicode-bidi",
+ "unicode-script",
+ "unicode-vo",
+ "xmlwriter",
+]
+
+[[package]]
+name = "utf8_iter"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
+
+[[package]]
+name = "uuid"
+version = "1.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4a0e2d11620c50695fe12bbbfde96b3477fe606e7284c22d505c12ce51214514"
+dependencies = [
+ "getrandom 0.4.3",
+ "js-sys",
+ "serde_core",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "version_check"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
+
+[[package]]
+name = "walkdir"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29790946404f91d9c5d06f9874efddea1dc06c5efe94541a7d6863108e3a5e4b"
+dependencies = [
+ "same-file",
+ "winapi-util",
+]
+
+[[package]]
+name = "want"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ec4cdd0dd910afe868b7ef477227d8d538b46b3075031afee8a9f2acb0a2ed0b"
+dependencies = [
+ "try-lock",
+]
+
+[[package]]
+name = "wasi"
+version = "0.11.1+wasi-snapshot-preview1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
+
+[[package]]
+name = "wasip2"
+version = "1.0.4+wasi-0.2.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b67efb37e106e55ce722a510d6b5f9c17f083e5fc79afc2badeb12cc313d9487"
+dependencies = [
+ "wit-bindgen",
+]
+
+[[package]]
+name = "wasm-bindgen"
+version = "0.2.129"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9bb54f33acc68fd454578d9820b0bde1a1a3d17aa17bb7b6595806d02886d409"
+dependencies = [
+ "cfg-if",
+ "once_cell",
+ "rustversion",
+ "wasm-bindgen-macro",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-futures"
+version = "0.4.79"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3cbab34de2d982e9b48e18d216d04c4a6f641066ff19ffb699980f591ee3610e"
+dependencies = [
+ "js-sys",
+ "tokio",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "wasm-bindgen-macro"
+version = "0.2.129"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2e29d0c35b16e224a7eeb5cd2d25e3e1968fbd65604117b44d3b789d00ee8535"
+dependencies = [
+ "quote",
+ "wasm-bindgen-macro-support",
+]
+
+[[package]]
+name = "wasm-bindgen-macro-support"
+version = "0.2.129"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6f501a8bc3719dba86ef8ae4728879c08001bea749eb1333ac5b91e040e2a6b7"
+dependencies = [
+ "bumpalo",
+ "proc-macro2",
+ "quote",
+ "syn 3.0.9",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-shared"
+version = "0.2.129"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23f0c9c52aa7cd7d77769a4cfe2a9adb1b331f489a41d912ce14513d5ab995c6"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "wasm-streams"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "15053d8d85c7eccdbefef60f06769760a563c7f0a9d6902a13d35c7800b0ad65"
+dependencies = [
+ "futures-util",
+ "js-sys",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "web-sys",
+]
+
+[[package]]
+name = "wasm-streams"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9d1ec4f6517c9e11ae630e200b2b65d193279042e28edd4a2cda233e46670bbb"
+dependencies = [
+ "futures-util",
+ "js-sys",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "web-sys",
+]
+
+[[package]]
+name = "wasmtimer"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1c598d6b99ea013e35844697fc4670d08339d5cda15588f193c6beedd12f644b"
+dependencies = [
+ "futures",
+ "js-sys",
+ "parking_lot",
+ "pin-utils",
+ "slab",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "wayland-backend"
+version = "0.3.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "38a91b4eaddff87b1cd1074985e3713da4af2c49742d1b356b2c01670a67a078"
+dependencies = [
+ "cc",
+ "downcast-rs",
+ "rustix 1.1.6",
+ "scoped-tls",
+ "smallvec",
+ "wayland-sys",
+]
+
+[[package]]
+name = "wayland-client"
+version = "0.31.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e3c36a0f861ad76d0901f2800b46321410d9f73f2ea88aac0650d86c32688073"
+dependencies = [
+ "bitflags 2.13.2",
+ "rustix 1.1.6",
+ "wayland-backend",
+ "wayland-scanner",
+]
+
+[[package]]
+name = "wayland-csd-frame"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "625c5029dbd43d25e6aa9615e88b829a5cad13b2819c4ae129fdbb7c31ab4c7e"
+dependencies = [
+ "bitflags 2.13.2",
+ "cursor-icon",
+ "wayland-backend",
+]
+
+[[package]]
+name = "wayland-cursor"
+version = "0.31.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4a52d18780be9b1314328a3de5f930b73d2200112e3849ca6cb11822793fb34d"
+dependencies = [
+ "rustix 1.1.6",
+ "wayland-client",
+ "xcursor",
+]
+
+[[package]]
+name = "wayland-protocols"
+version = "0.32.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23d0c813de3daa2ed6520af85a3bd49b0e722a3078506899aa9686fea58dc4b6"
+dependencies = [
+ "bitflags 2.13.2",
+ "wayland-backend",
+ "wayland-client",
+ "wayland-scanner",
+]
+
+[[package]]
+name = "wayland-protocols-experimental"
+version = "20250721.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "40a1f863128dcaaec790d7b4b396cc9b9a7a079e878e18c47e6c2d2c5a8dcbb1"
+dependencies = [
+ "bitflags 2.13.2",
+ "wayland-backend",
+ "wayland-client",
+ "wayland-protocols",
+ "wayland-scanner",
+]
+
+[[package]]
+name = "wayland-protocols-misc"
+version = "0.3.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e9567599ef23e09b8dad6e429e5738d4509dfc46b3b21f32841a304d16b29c8"
+dependencies = [
+ "bitflags 2.13.2",
+ "wayland-backend",
+ "wayland-client",
+ "wayland-protocols",
+ "wayland-scanner",
+]
+
+[[package]]
+name = "wayland-protocols-plasma"
+version = "0.3.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2b6d8cf1eb2c1c31ed1f5643c88a6e53538129d4af80030c8cabd1f9fa884d91"
+dependencies = [
+ "bitflags 2.13.2",
+ "wayland-backend",
+ "wayland-client",
+ "wayland-protocols",
+ "wayland-scanner",
+]
+
+[[package]]
+name = "wayland-protocols-wlr"
+version = "0.3.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eb04e52f7836d7c7976c78ca0250d61e33873c34156a2a1fc9474828ec268234"
+dependencies = [
+ "bitflags 2.13.2",
+ "wayland-backend",
+ "wayland-client",
+ "wayland-protocols",
+ "wayland-scanner",
+]
+
+[[package]]
+name = "wayland-scanner"
+version = "0.31.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "338e30461b3a2b67d70eb30a6d89f8e0c93a833e07d2ae89085cd070c4a00ac0"
+dependencies = [
+ "proc-macro2",
+ "quick-xml",
+ "quote",
+]
+
+[[package]]
+name = "wayland-sys"
+version = "0.31.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d8eab23fefc9e41f8e841df4a9c707e8a8c4ed26e944ef69297184de2785e3be"
+dependencies = [
+ "dlib",
+ "log",
+ "once_cell",
+ "pkg-config",
+]
+
+[[package]]
+name = "web-sys"
+version = "0.3.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "88261b9deccee56594c11a3460c462c41f58d148598fe70ad77070126a68aba4"
+dependencies = [
+ "js-sys",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "web-time"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a6580f308b1fad9207618087a65c04e7a10bc77e02c8e84e9b00dd4b12fa0bb"
+dependencies = [
+ "js-sys",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "webpki-root-certs"
+version = "1.0.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e49d0e65abc00c142e8f9428da991da9f1a250c39be97459901eb12b9b49f62a"
+dependencies = [
+ "rustls-pki-types",
+]
+
+[[package]]
+name = "webpki-roots"
+version = "0.26.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "521bc38abb08001b01866da9f51eb7c5d647a19260e00054a8c7fd5f9e57f7a9"
+dependencies = [
+ "webpki-roots 1.0.11",
+]
+
+[[package]]
+name = "webpki-roots"
+version = "1.0.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f5f280bbb2b287bc8e7de7e3852945a0ff50d1bbcb5ed42b6c7a568c546df171"
+dependencies = [
+ "rustls-pki-types",
+]
+
+[[package]]
+name = "weezl"
+version = "0.1.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a28ac98ddc8b9274cb41bb4d9d4d5c425b6020c50c46f25559911905610b4a88"
+
+[[package]]
+name = "wgpu"
+version = "27.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bfe68bac7cde125de7a731c3400723cadaaf1703795ad3f4805f187459cd7a77"
+dependencies = [
+ "arrayvec",
+ "bitflags 2.13.2",
+ "cfg-if",
+ "cfg_aliases",
+ "document-features",
+ "hashbrown 0.16.1",
+ "js-sys",
+ "log",
+ "naga",
+ "parking_lot",
+ "portable-atomic",
+ "profiling",
+ "raw-window-handle",
+ "smallvec",
+ "static_assertions",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "web-sys",
+ "wgpu-core",
+ "wgpu-hal",
+ "wgpu-types",
+]
+
+[[package]]
+name = "wgpu-core"
+version = "27.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "27a75de515543b1897b26119f93731b385a19aea165a1ec5f0e3acecc229cae7"
+dependencies = [
+ "arrayvec",
+ "bit-set",
+ "bit-vec",
+ "bitflags 2.13.2",
+ "bytemuck",
+ "cfg_aliases",
+ "document-features",
+ "hashbrown 0.16.1",
+ "indexmap",
+ "log",
+ "naga",
+ "once_cell",
+ "parking_lot",
+ "portable-atomic",
+ "profiling",
+ "raw-window-handle",
+ "rustc-hash 1.1.0",
+ "smallvec",
+ "thiserror 2.0.21",
+ "wgpu-core-deps-apple",
+ "wgpu-core-deps-emscripten",
+ "wgpu-core-deps-windows-linux-android",
+ "wgpu-hal",
+ "wgpu-types",
+]
+
+[[package]]
+name = "wgpu-core-deps-apple"
+version = "27.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0772ae958e9be0c729561d5e3fd9a19679bcdfb945b8b1a1969d9bfe8056d233"
+dependencies = [
+ "wgpu-hal",
+]
+
+[[package]]
+name = "wgpu-core-deps-emscripten"
+version = "27.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b06ac3444a95b0813ecfd81ddb2774b66220b264b3e2031152a4a29fda4da6b5"
+dependencies = [
+ "wgpu-hal",
+]
+
+[[package]]
+name = "wgpu-core-deps-windows-linux-android"
+version = "27.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "71197027d61a71748e4120f05a9242b2ad142e3c01f8c1b47707945a879a03c3"
+dependencies = [
+ "wgpu-hal",
+]
+
+[[package]]
+name = "wgpu-hal"
+version = "27.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5b21cb61c57ee198bc4aff71aeadff4cbb80b927beb912506af9c780d64313ce"
+dependencies = [
+ "android_system_properties",
+ "arrayvec",
+ "ash",
+ "bit-set",
+ "bitflags 2.13.2",
+ "block",
+ "bytemuck",
+ "cfg-if",
+ "cfg_aliases",
+ "core-graphics-types 0.2.0",
+ "glow",
+ "glutin_wgl_sys",
+ "gpu-alloc",
+ "gpu-allocator",
+ "gpu-descriptor",
+ "hashbrown 0.16.1",
+ "js-sys",
+ "khronos-egl",
+ "libc",
+ "libloading",
+ "log",
+ "metal",
+ "naga",
+ "ndk-sys",
+ "objc",
+ "once_cell",
+ "ordered-float",
+ "parking_lot",
+ "portable-atomic",
+ "portable-atomic-util",
+ "profiling",
+ "range-alloc",
+ "raw-window-handle",
+ "renderdoc-sys",
+ "smallvec",
+ "thiserror 2.0.21",
+ "wasm-bindgen",
+ "web-sys",
+ "wgpu-types",
+ "windows 0.58.0",
+ "windows-core 0.58.0",
+]
+
+[[package]]
+name = "wgpu-types"
+version = "27.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "afdcf84c395990db737f2dd91628706cb31e86d72e53482320d368e52b5da5eb"
+dependencies = [
+ "bitflags 2.13.2",
+ "bytemuck",
+ "js-sys",
+ "log",
+ "thiserror 2.0.21",
+ "web-sys",
+]
+
+[[package]]
+name = "winapi-util"
+version = "0.1.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "window_clipboard"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d5654226305eaf2dde8853fb482861d28e5dcecbbd40cb88e8393d94bb80d733"
+dependencies = [
+ "clipboard-win",
+ "clipboard_macos",
+ "clipboard_wayland",
+ "clipboard_x11",
+ "raw-window-handle",
+ "thiserror 2.0.21",
+]
+
+[[package]]
+name = "windows"
+version = "0.58.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dd04d41d93c4992d421894c18c8b43496aa748dd4c081bac0dc93eb0489272b6"
+dependencies = [
+ "windows-core 0.58.0",
+ "windows-targets",
+]
+
+[[package]]
+name = "windows"
+version = "0.62.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "527fadee13e0c05939a6a05d5bd6eec6cd2e3dbd648b9f8e447c6518133d8580"
+dependencies = [
+ "windows-collections",
+ "windows-core 0.62.2",
+ "windows-future",
+ "windows-numerics",
+]
+
+[[package]]
+name = "windows-collections"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23b2d95af1a8a14a3c7367e1ed4fc9c20e0a26e79551b1454d72583c97cc6610"
+dependencies = [
+ "windows-core 0.62.2",
+]
+
+[[package]]
+name = "windows-core"
+version = "0.58.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ba6d44ec8c2591c134257ce647b7ea6b20335bf6379a27dac5f1641fcf59f99"
+dependencies = [
+ "windows-implement 0.58.0",
+ "windows-interface 0.58.0",
+ "windows-result 0.2.0",
+ "windows-strings 0.1.0",
+ "windows-targets",
+]
+
+[[package]]
+name = "windows-core"
+version = "0.62.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb"
+dependencies = [
+ "windows-implement 0.60.2",
+ "windows-interface 0.59.3",
+ "windows-link",
+ "windows-result 0.4.1",
+ "windows-strings 0.5.1",
+]
+
+[[package]]
+name = "windows-future"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e1d6f90251fe18a279739e78025bd6ddc52a7e22f921070ccdc67dde84c605cb"
+dependencies = [
+ "windows-core 0.62.2",
+ "windows-link",
+ "windows-threading",
+]
+
+[[package]]
+name = "windows-implement"
+version = "0.58.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2bbd5b46c938e506ecbce286b6628a02171d56153ba733b6c741fc627ec9579b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "windows-implement"
+version = "0.60.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "windows-interface"
+version = "0.58.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "053c4c462dc91d3b1504c6fe5a726dd15e216ba718e84a0e46a88fbe5ded3515"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "windows-interface"
+version = "0.59.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "windows-numerics"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e2e40844ac143cdb44aead537bbf727de9b044e107a0f1220392177d15b0f26"
+dependencies = [
+ "windows-core 0.62.2",
+ "windows-link",
+]
+
+[[package]]
+name = "windows-registry"
+version = "0.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "02752bf7fbdcce7f2a27a742f798510f3e5ad88dbe84871e5168e2120c3d5720"
+dependencies = [
+ "windows-link",
+ "windows-result 0.4.1",
+ "windows-strings 0.5.1",
+]
+
+[[package]]
+name = "windows-result"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d1043d8214f791817bab27572aaa8af63732e11bf84aa21a45a78d6c317ae0e"
+dependencies = [
+ "windows-targets",
+]
+
+[[package]]
+name = "windows-result"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "windows-strings"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4cd9b125c486025df0eabcb585e62173c6c9eddcec5d117d3b6e8c30e2ee4d10"
+dependencies = [
+ "windows-result 0.2.0",
+ "windows-targets",
+]
+
+[[package]]
+name = "windows-strings"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.52.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d"
+dependencies = [
+ "windows-targets",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.59.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b"
+dependencies = [
+ "windows-targets",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.61.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "windows-targets"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973"
+dependencies = [
+ "windows_aarch64_gnullvm",
+ "windows_aarch64_msvc",
+ "windows_i686_gnu",
+ "windows_i686_gnullvm",
+ "windows_i686_msvc",
+ "windows_x86_64_gnu",
+ "windows_x86_64_gnullvm",
+ "windows_x86_64_msvc",
+]
+
+[[package]]
+name = "windows-threading"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3949bd5b99cafdf1c7ca86b43ca564028dfe27d66958f2470940f73d86d75b37"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "windows_aarch64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
+
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
+
+[[package]]
+name = "windows_i686_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
+
+[[package]]
+name = "windows_i686_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
+
+[[package]]
+name = "windows_i686_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
+
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
+
+[[package]]
+name = "windows_x86_64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
+
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
+
+[[package]]
+name = "winit"
+version = "0.30.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a6755fa58a9f8350bd1e472d4c3fcc25f824ec358933bba33306d0b63df5978d"
+dependencies = [
+ "ahash",
+ "android-activity",
+ "atomic-waker",
+ "bitflags 2.13.2",
+ "block2 0.5.1",
+ "bytemuck",
+ "calloop 0.13.0",
+ "cfg_aliases",
+ "concurrent-queue",
+ "core-foundation 0.9.4",
+ "core-graphics",
+ "cursor-icon",
+ "dpi",
+ "js-sys",
+ "libc",
+ "memmap2",
+ "ndk",
+ "objc2 0.5.3",
+ "objc2-app-kit 0.2.2",
+ "objc2-foundation 0.2.2",
+ "objc2-ui-kit",
+ "orbclient",
+ "percent-encoding",
+ "pin-project",
+ "raw-window-handle",
+ "redox_syscall 0.4.1",
+ "rustix 0.38.44",
+ "sctk-adwaita",
+ "smithay-client-toolkit 0.19.2",
+ "smol_str",
+ "tracing",
+ "unicode-segmentation",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "wayland-backend",
+ "wayland-client",
+ "wayland-protocols",
+ "wayland-protocols-plasma",
+ "web-sys",
+ "web-time",
+ "windows-sys 0.52.0",
+ "x11-dl",
+ "x11rb",
+ "xkbcommon-dl",
+]
+
+[[package]]
+name = "winnow"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23b97319f7b8343df12cc98938e5c3eb436064524c8d2b4e30a1d3a36eecdf81"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "wit-bindgen"
+version = "0.57.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e"
+
+[[package]]
+name = "writeable"
+version = "0.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3ad82d2a33cdc9674dc7465672f271e096168fcdbe0f799d9e6db8c5892679dc"
+
+[[package]]
+name = "x11-dl"
+version = "2.21.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "38735924fedd5314a6e548792904ed8c6de6636285cb9fec04d5b1db85c1516f"
+dependencies = [
+ "libc",
+ "once_cell",
+ "pkg-config",
+]
+
+[[package]]
+name = "x11rb"
+version = "0.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9993aa5be5a26815fe2c3eacfc1fde061fc1a1f094bf1ad2a18bf9c495dd7414"
+dependencies = [
+ "as-raw-xcb-connection",
+ "gethostname",
+ "libc",
+ "libloading",
+ "once_cell",
+ "rustix 1.1.6",
+ "x11rb-protocol",
+]
+
+[[package]]
+name = "x11rb-protocol"
+version = "0.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ea6fc2961e4ef194dcbfe56bb845534d0dc8098940c7e5c012a258bfec6701bd"
+
+[[package]]
+name = "xattr"
+version = "1.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "963d6fab92d5504b971dc8bd90ca743c2575e590bc8071ea5bc571598667ae08"
+dependencies = [
+ "libc",
+ "rustix 1.1.6",
+]
+
+[[package]]
+name = "xcursor"
+version = "0.3.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "163b33ed8786455e2fa5d72f554057ce3f3182425434f756cd39c99839d88e23"
+
+[[package]]
+name = "xkbcommon-dl"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d039de8032a9a8856a6be89cea3e5d12fdd82306ab7c94d74e6deab2460651c5"
+dependencies = [
+ "bitflags 2.13.2",
+ "dlib",
+ "log",
+ "once_cell",
+ "xkeysym",
+]
+
+[[package]]
+name = "xkeysym"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b9cc00251562a284751c9973bace760d86c0276c471b4be569fe6b068ee97a56"
+
+[[package]]
+name = "xml-rs"
+version = "0.8.29"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e450f9b2ed1dff33c94c12589a87338689467b9c4f5d8a5710bd09a847d2c8a7"
+
+[[package]]
+name = "xmlwriter"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ec7a2a501ed189703dba8b08142f057e887dfc4b2cc4db2d343ac6376ba3e0b9"
+
+[[package]]
+name = "yazi"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e01738255b5a16e78bbb83e7fbba0a1e7dd506905cfc53f4622d89015a03fbb5"
+
+[[package]]
+name = "yoke"
+version = "0.8.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "417ef3fcf6c300b7dbd25c85531a746931c02ad536f3cf4786ed1e88223340b3"
+dependencies = [
+ "stable_deref_trait",
+ "yoke-derive",
+ "zerofrom",
+]
+
+[[package]]
+name = "yoke-derive"
+version = "0.8.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ec8ebde2db3681e8c9980cc27822030e68752690ddfa9473e739aeb4dbde6d71"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.9",
+ "synstructure",
+]
+
+[[package]]
+name = "zbus"
+version = "5.19.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5db4be7c075cb421e4b7ee645541604239bd243ba7c357511f4ff3a74b555907"
+dependencies = [
+ "async-broadcast",
+ "async-executor",
+ "async-io",
+ "async-lock",
+ "async-process",
+ "async-recursion",
+ "async-task",
+ "async-trait",
+ "blocking",
+ "enumflags2",
+ "event-listener",
+ "futures-core",
+ "futures-lite",
+ "hex",
+ "libc",
+ "ordered-stream",
+ "rustix 1.1.6",
+ "serde",
+ "serde_repr",
+ "tracing",
+ "uds_windows",
+ "uuid",
+ "windows-sys 0.61.2",
+ "winnow",
+ "zbus_macros",
+ "zbus_names",
+ "zvariant",
+]
+
+[[package]]
+name = "zbus_macros"
+version = "5.19.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2990635d09ade6df1868f72f8cac69a876a90981e8bd3c40b1be413f8dc88f40"
+dependencies = [
+ "proc-macro-crate",
+ "proc-macro2",
+ "quote",
+ "syn 3.0.9",
+ "zbus_names",
+ "zvariant",
+ "zvariant_utils",
+]
+
+[[package]]
+name = "zbus_names"
+version = "4.3.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "812a12be4ead7a59e18ea8f047d08add0066b73bc62fc1467066a2472ae088dd"
+dependencies = [
+ "serde",
+ "winnow",
+ "zvariant",
+]
+
+[[package]]
+name = "zcheapstr"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d1afec51604565183aeb5c54c20aeab286120d4e4460f7f76e3e8bb8c0d99473"
+dependencies = [
+ "serde",
+]
+
+[[package]]
+name = "zeno"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6df3dc4292935e51816d896edcd52aa30bc297907c26167fec31e2b0c6a32524"
+
+[[package]]
+name = "zerocopy"
+version = "0.8.63"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e5fe1f8f1b06191a00962174c61aa5005e0bb391a6d80d07e24d115c01a92ed8"
+dependencies = [
+ "zerocopy-derive",
+]
+
+[[package]]
+name = "zerocopy-derive"
+version = "0.8.63"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "863ad3ac83293fb4d740aedbfdc9240dd8d1a50c1099acd76ce80ce7c7230c7f"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "zerofrom"
+version = "0.1.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ec05a11813ea801ff6d75110ad09cd0824ddba17dfe17128ea0d5f68e6c5272"
+dependencies = [
+ "zerofrom-derive",
+]
+
+[[package]]
+name = "zerofrom-derive"
+version = "0.1.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f75b4683f6c7f45248d4d64056a24298c6281e0993356d7d1b4a1a962ef10d4a"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.9",
+ "synstructure",
+]
+
+[[package]]
+name = "zeroize"
+version = "1.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e13084392c5e4bc371903e2935a5eaeed24905a7511356b883835e18a78f6879"
+
+[[package]]
+name = "zerotrie"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4ea269c3bd32f0a32c321907a2ae912ba6f4649bb0fc764a15627e99a7095a3f"
+dependencies = [
+ "displaydoc",
+ "yoke",
+ "zerofrom",
+]
+
+[[package]]
+name = "zerovec"
+version = "0.11.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f58a2799cfe9a1670c7ea8edbd52ef8edb93cb37a7f83bf31ba9e35d9dae6a40"
+dependencies = [
+ "yoke",
+ "zerofrom",
+ "zerovec-derive",
+]
+
+[[package]]
+name = "zerovec-derive"
+version = "0.11.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c3743ddbf47738d929cd1ae2e199d40d0162979dfe31aef8ae646d2bf00bf97a"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.9",
+]
+
+[[package]]
+name = "zip"
+version = "9.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1156b39d142a34b999c2310a50455e0cb3760bf7efad0122f796d813bee26ccb"
+dependencies = [
+ "crc32fast",
+ "flate2",
+ "getrandom 0.4.3",
+ "indexmap",
+ "memchr",
+ "nix",
+ "typed-path",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "zlib-rs"
+version = "0.6.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b268e58e7c693d7c271f93ffc4ba3b380412554231c85bf61ca7af91042a4112"
+
+[[package]]
+name = "zmij"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
+
+[[package]]
+name = "zune-core"
+version = "0.4.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f423a2c17029964870cfaabb1f13dfab7d092a62a29a89264f4d36990ca414a"
+
+[[package]]
+name = "zune-core"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d56377fd46368984a170bc5aac5567e52ca5da874caa60bea39fcbca78fb658b"
+
+[[package]]
+name = "zune-jpeg"
+version = "0.4.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29ce2c8a9384ad323cf564b67da86e21d3cfdff87908bc1223ed5c99bc792713"
+dependencies = [
+ "zune-core 0.4.12",
+]
+
+[[package]]
+name = "zune-jpeg"
+version = "0.5.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "27bc9d5b815bc103f142aa054f561d9187d191692ec7c2d1e2b4737f8dbd7296"
+dependencies = [
+ "zune-core 0.5.3",
+]
+
+[[package]]
+name = "zvariant"
+version = "5.15.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "80bf6d6cd6a4b601acb64cfb8284cdc643fcfa75ef26ae3c46ec8aa4e8a1fbb7"
+dependencies = [
+ "endi",
+ "enumflags2",
+ "serde",
+ "winnow",
+ "zcheapstr",
+ "zvariant_derive",
+ "zvariant_utils",
+]
+
+[[package]]
+name = "zvariant_derive"
+version = "5.15.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ef2672456ba1cb54b5eaec136e63135b3c7495fb938e53b28a62e633496d486d"
+dependencies = [
+ "proc-macro-crate",
+ "proc-macro2",
+ "quote",
+ "syn 3.0.9",
+ "zvariant_utils",
+]
+
+[[package]]
+name = "zvariant_utils"
+version = "4.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bad0294361a320b694a328460dc73add56c306150f5cb6bfafc44446120008a3"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "serde",
+ "syn 3.0.9",
+ "winnow",
+]
diff --git a/Cargo.toml b/Cargo.toml
new file mode 100644
index 0000000..cac3151
--- /dev/null
+++ b/Cargo.toml
@@ -0,0 +1,164 @@
+[workspace]
+resolver = "2"
+members = [
+    "crates/core",
+    "crates/agent",
+    # M85（D26）：UI 框架无关的宿主层。Slint 版（crates/app）与 iced 版（crates/app-iced）
+    # 共用它；Slint 退役（M118 起 `crates/app` 已不是 workspace 成员）后只剩 iced 依赖，本 crate 不受影响。
+    "crates/presenter",
+    "crates/cli",
+    "crates/design",
+    # P4（D26 iced 重写）第一步：与 Slint 版 `crates/app` 并存的新 UI crate。
+    # bin 名 `unlucky-launcher-iced`，翻牌时才改名（见 DevDocs/SubAgentsTalk/app-iced-骨架与翻牌.md）。
+    # M118 起它是发布矩阵里**唯一**的 GUI 来源：发布了 Slint 版的那个 bin 名属于被排除的 `crates/app`。
+    "crates/app-iced",
+    # M87（D40 第 2 层）：配色取色的解码适配层。**唯一**允许引入 `image` 类依赖的地方，
+    # 使 `crates/design` 能继续宣称「零第三方依赖」。
+    "crates/palette-extract",
+    # M92（D28）：国际化地基——语言探测 / 中英消息目录 / 中文字体策略。零第三方依赖、零 UI 依赖，
+    # 壳层（iced 版现在，别的壳将来）与 presenter 都依赖它，所以它不能认任何一个渲染框架。
+    "crates/i18n",
+]
+# M118（D26）：`crates/app` 是 Slint 退役树 —— UI 已迁到 iced，目录与源码**原样保留**作历史
+# 参考（另一份参考资产见 DevDocs/ops/slint-reference/），但不再进默认构建与发布矩阵。摘出去的
+# 是整棵 slint 1.18 + usvg 0.48 依赖树：本机单路冷编 ≈14 分钟，而 CI 的 `--workspace` 每次都会
+# 编它，既拖长反馈，又会在并行超配时随机 OOM（见 DevDocs/00-踩坑记录-p2.md T7）。
+# 排除 ≠ 删除，但**它确实不再可编**：该 manifest 整份都是 `*.workspace = true` 继承写法，
+# 一旦不是 workspace 成员，继承无源、manifest 解析即失败（实测：
+# `cargo metadata --manifest-path crates/app/Cargo.toml` → "error inheriting `edition` …"）。
+# 要读这一版实现请直接读源码，别再尝试构建它。
+exclude = ["crates/app"]
+
+[workspace.package]
+version = "0.2.0"
+edition = "2021"
+license = "Apache-2.0"
+authors = ["AskaEth <i@yeij.top>"]
+repository = "https://github.com/AskaEth/Unlucky-Launcher"
+rust-version = "1.92"
+publish = false
+
+[workspace.dependencies]
+# 共享依赖（版本在此集中，各 crate 用 `xxx.workspace = true` 引用）
+# M15（core::diagnose）首批使用者：规则正则 / 规则 YAML 解析 / 诊断结果序列化。
+regex = "1"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+# serde_yaml 上游已停维护（RUSTSEC-2024-0320），改用维护中的 API 兼容分支（tower 定案）
+serde_yaml_ng = "0.10"
+
+# M13（core::download）：HTTP + 异步运行时 + 流 + 校验哈希。
+# rustls（ring）而非 native-tls —— 免 OpenSSL/系统证书栈依赖，MinGW 与 Win7 都省事。
+reqwest = { version = "0.12", default-features = false, features = ["rustls-tls", "stream"] }
+tokio = { version = "1", features = [
+    "rt-multi-thread",
+    "fs",
+    "io-util",
+    "time",
+    "sync",
+    "net",
+    "macros",
+] }
+futures-util = "0.3"
+sha1 = "0.10"
+sha2 = "0.10"
+# M31（core::auth）：离线账户 UUID 必须与 Minecraft 服务端/HMCL 的
+# `UUID.nameUUIDFromBytes` 逐字节一致 = MD5 + v3 位改写，因此需要 MD5。
+# 与 sha1/sha2 同属 RustCrypto（Apache-2.0 OR MIT），版本对齐 digest 0.10。
+md-5 = "0.10"
+
+# M29（core::launch::natives）：读 natives jar（zip 容器）解压原生库。
+# 只开 inflate（`deflate-flate2-zlib-rs`，纯 Rust zlib）——解压方向不需要 zopfli 压缩器。
+zip = { version = "9", default-features = false, features = ["deflate-flate2-zlib-rs"] }
+
+# M33（core::game::java）：Temurin 的 Linux/macOS 产物只发 `.tar.gz`（Windows 是 `.zip`，
+# 复用上面的 zip）。flate2/tar 都是纯 Rust + MIT OR Apache-2.0，白名单内。
+flate2 = "1"
+tar = "0.4"
+
+# M87（D40）：配色取色的解码适配层。版本与 `crates/app-iced` 的截图通道对齐（同一份
+# `image` 只编译一次）；编解码器由各 crate 自己按需开 feature，这里只钉版本。
+image = { version = "0.25", default-features = false }
+
+# UI 层唯一入口（D2：Slint，RF 2.0 轨道）。
+# 默认特性已含 backend-default + renderer-femtovg（GL）+ renderer-software（CPU 软渲染兜底，
+# Win7 老机无可用 GPU 时的降级路径，见 DevDocs/PlanDoc/01c-native-gui-options.md §6）。
+slint = "1.18"
+# app 的 build script 用（把 ui/main.slint 编译成 Rust 代码），版本必须与 slint 主 crate 同步。
+slint-build = "1.18"
+
+# agent 层依赖（rig / rmcp）按 D4 在 M16 引入，脚手架期不引入以免版本冲突。
+# 版本锁定策略见 DevDocs/PlanDoc/02-ai-agent-design.md §0：rig 锁 =0.45.x，rmcp 3.8.x。
+#
+# M39 的 MCP server（02 §0「传输定论」）：rmcp 官方 SDK（Apache-2.0），**锁精确版本**——
+# pre-1.0 且 ~6 天一个版、3.x 内已多次改 server API。只开需要的传输 feature：
+# - `server`（default 带）+ `transport-io`（stdio，给 llama.cpp 内置 MCP client）
+# - `transport-streamable-http-server`（主力：127.0.0.1 上的 Streamable HTTP）
+# `macros` 一并留在 default 里（`#[tool]` 宏不用，但 default 拆开易漏 base64 等隐式依赖）。
+rmcp = { version = "=3.8.0", features = [
+    "transport-io",
+    "transport-streamable-http-server",
+] }
+# rmcp 的 Streamable HTTP server 是个 tower Service，官方示例用 axum 挂监听（MIT）。
+# 只吃 `nest_service` + `serve`，不引入任何 TLS/模板/DB 生态。
+axum = "0.8"
+
+[workspace.lints.rust]
+unsafe_code = "deny"
+missing_docs = "warn"
+rust_2018_idioms = { level = "warn", priority = -1 }
+
+[workspace.lints.clippy]
+all = { level = "deny", priority = -1 }
+
+[profile.release]
+opt-level = "z"
+lto = "fat"
+codegen-units = 1
+panic = "abort"
+strip = "symbols"
+
+# P6（M96）：日常迭代 / 本机验收用的「快」档，发布仍走上面的 release。
+# `inherits = "release"` 让其余各项（strip / debug / overflow-checks …）照抄 release，
+# 只覆盖拖慢构建的四处：
+# - lto = "thin"：跨 crate 内联仍有，但可以并行；fat LTO 在 codegen-units = 1 下等于
+#   全程序串行链接（375 个 crate 排队），一次性吃掉十几分钟。
+# - codegen-units = 16：给 codegen 留并行度，不再把整个 crate 挤成一个 CGU。
+# - opt-level = 2：介于 "z" 与 3 之间，"z" 会为了体积关掉一批循环/内联优化，代价是运行期。
+# - panic = "unwind"：release 是 panic = "abort"，inherits 会照抄。留着它是为了让 fast 档编出来的
+#   **二进制**走 unwind（panic 会栈展开，不是直接 abort）。
+#   ⚠️ 理由不是「不写就跑不了测试」：`cargo test` **不**依赖这一行 —— cargo 对 test 目标自己强制
+#   unwind。实测 `cargo test --profile release -p unlucky-i18n`（release = abort 档）照跑，23 个
+#   测试全过，且 test 单元的 rustc 参数里**没有** `-Cpanic=`。别拿「cargo test 能跑」当这行生效的证据；
+#   要看就用 `cargo build --profile {fast,release} -v` 比 rustc 参数：release 有 `panic=abort`，fast 没有。
+#
+# ⚠️ 定位（实测，别误读）：本机（12 核 + 机械盘源码盘 + -j 4）冷编译 fast = 24m27s，
+# **比 release 的 16m01s 还慢**，体积是 2.3 倍（36.41 vs 15.72 MiB GUI）。瓶颈在两个大
+# UI crate 的编译 + 链接 + 磁盘 IO，LTO/CGU 这几个旋钮被掩盖了。它的价值在 **SSD 机器**和
+# **增量重编**（thin 不必每次全程序 LTO）；「加了 fast 档」≠「冷编译会变快」。
+[profile.fast]
+inherits = "release"
+opt-level = 2
+lto = "thin"
+codegen-units = 16
+panic = "unwind"
+
+# P6（M96）：依赖不需要为体积做极致优化，但**实测结论与直觉相反**——把依赖的 opt-level 从
+# release 的 "z" 抬到 3（本档最初就是这么定的）会让冷编译**更慢**、体积还更大：
+# 同机冷编译 opt-3 = 22m45s / 19.46 MiB（GUI），opt-"z" = 16m01s / 15.72 MiB（两臂同为 cu16）。
+# 所以这里**opt-level 保持 "z"，只把并行度放到 16**；workspace 自己的 crate 仍吃 "z" / 单 CGU。
+# ⚠️ **未测**：cu1 → cu16 的收益本轮没有同条件对照（两臂都是 cu16，唯一自变量是 opt-level），
+# 所以「cu16 才是收益来源」不是实测结论，要归因得单独跑一轮 cu1 对照。另：GUI 体积相对旧基线
+# 涨了 12.9%（13.92 → 15.72 MiB），其中「代码增长」与「依赖 cu16」也没分离。
+# **只调优化强度**：panic 与 strip 绝不写进这里。那两项改变的是整个二进制的运行时行为
+# （panic 策略决定能否 unwind 出栈、strip 决定符号表留不留），不是「给依赖放宽」的范畴。
+[profile.release.package."*"]
+opt-level = "z"
+codegen-units = 16
+
+# `inherits = "release"` 会把 `[profile.release.package."*"]` **一起继承过来**（实测：删掉下面这块，
+# fast 档的外部依赖就从 opt-level 2 退回 `"z"`；workspace 成员不受 `*` 覆盖、仍是 fast 自己的 2）。
+# 所以这块**必须存在**，它是承重墙不是冗余兜底 —— 删掉会让 fast 档的依赖静默退回 `"z"`。
+[profile.fast.package."*"]
+opt-level = 2
+codegen-units = 16
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..97bdc46
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 AskaEth (YeiJ)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/NOTICE b/NOTICE
new file mode 100644
index 0000000..9cf081c
--- /dev/null
+++ b/NOTICE
@@ -0,0 +1,66 @@
+Unlucky-Launcher (ULL)
+Copyright 2026 AskaEth (YeiJ)
+
+本产品采用 Apache License 2.0（见 LICENSE）。
+
+--------------------------------------------------------------------------
+第三方组件声明
+--------------------------------------------------------------------------
+
+1. Slint（https://slint.dev）——**历史源码，不随任何产物分发**
+
+   本产品**当前发布的 GUI 框架是 iced**（见第 3 节），二进制里不含任何 Slint 代码。
+   仓库里仍保留 Slint 版 GUI 的源码（`crates/app`），仅作历史参考：它已被 cargo workspace
+   `exclude`，不参与构建、测试与发布，也不会进入本项目的任何 Release 资产。
+
+   因此 Slint Royalty-Free 2.0（LicenseRef-Slint-Royalty-free-2.0）**对当前产物不适用**；它适用的是
+   此前已发布、且确实链接了 Slint 的 `v0.1.0` 构建——义务挂在每一次「随应用分发」上，而不是挂在某个
+   版本号上。上游许可 §2 给出两种形式：(a) 在可从顶层菜单进入的「关于」页/对话框里显示官方
+   `AboutSlint` 部件（没有该页时改为启动画面）；(b) 在可下载该二进制的公开网页上显示官方归属徽章。
+   **`v0.1.0` 的设置页「关于」分组里内置了 `AboutSlint` 部件**（`crates/app/ui/pages/settings.slint`，
+   从侧栏进入）；该部件是否满足 §2(a) 的全部条件、以及 `v0.1.0` 发布页上那是文字链接而不是 §2(b) 点名的
+   官方徽章图这两点，**本文件不作法律判断**，具体以 Slint 官方许可原文为准。`v0.1.0` 的 NOTICE、发布页
+   说明与本文件这一节**都只是记录，不构成履行声明**。后续版本不再链接 Slint，该义务不随新产物新增；
+   本文件保留这一节，是为了不让这段历史丢失，而不是声明本产品依赖 Slint。
+
+   若将来重新把 `crates/app` 纳入构建并发布链接 Slint 的二进制，该义务随之恢复——届时需同时恢复
+   AboutSlint 部件/徽章与本节的现行声明。Slint 的其余许可分支（GPL-3.0-only / Slint Software
+   License 3.0）本项目始终不适用。
+
+2. Google Material Color Utilities（https://github.com/material-foundation/material-color-utilities）
+
+   本产品的色彩令牌（crates/design 的 color 模块）是 Material 3 色彩算法（HCT 色彩空间 +
+   ColorSpec2021 调色板/角色映射）的 **Rust 重写移植**，依据 Apache License 2.0 使用，未把其任何语言的源码作为依赖
+   引入；除下面注明的那张生成常数表外，也没有复制其代码文件。
+
+   实际移植的部分（均为纯算法，逐函数对照后以 Rust 重写）：
+
+   - `hct/Cam16.java`、`hct/ViewingConditions.java`、`hct/Hct.java` → `crates/design/src/color/cam16.rs`、
+     `viewing_conditions.rs`、`hct.rs`（CAM16 色相/彩度 + CIELAB `L*` 亮度）
+   - `hct/HctSolver.java` → `crates/design/src/color/hct_solver.rs` + `critical_planes.rs`
+     （色域映射求解器；其中 255 项 `CRITICAL_PLANES` 常数表是原样搬运的生成数据）
+   - `utils/ColorUtils.java`、`utils/MathUtils.java` → `crates/design/src/color/space.rs`
+   - `palettes/TonalPalette.java`、`dynamiccolor/ColorSpec2021.java`、`dynamiccolor/DynamicScheme.java`
+     → `crates/design/src/color/tonal.rs`、`palettes.rs`、`scheme.rs`（Tonal Spot 变体的彩度常数与
+     49 个角色的 tone 映射）
+
+   对齐验证：`crates/design/tests/official_baseline.rs` 与 `tests/official_accent.rs` 的期望色值，
+   是把上述官方 Java 实现（Apache-2.0）在本机编译运行后输出的结果抄本——合计 290 项逐通道
+   比对（baseline 49 角色 × 2 模式 = 98 项；强调色 8 个种子 × 12 个强调族角色 × 2 模式 = 192 项），
+   误差上限 1（实测为 0）。两文件的表头各写着自己的分项口径。
+
+   Apache License 2.0 全文见 https://www.apache.org/licenses/LICENSE-2.0
+   上游版权声明：Copyright Google LLC。
+
+3. Rust crates 生态
+
+   当前 GUI 框架：iced 0.14（MIT），连同 winit（Apache-2.0）、wgpu（MIT OR Apache-2.0）、
+   tiny-skia（BSD-3-Clause）——它们都在下面的白名单内。
+   cargo-deny 白名单见 deny.toml：Apache-2.0 / MIT / BSD-2-Clause / BSD-3-Clause / Zlib / BSL-1.0 / ISC /
+   CC0-1.0 / MIT-0 / Unlicense / Unicode-3.0 / CDLA-Permissive-2.0 / Apache-2.0 WITH LLVM-exception。
+   GPL 系（含 AGPL、LGPL 静态链接、SSPL）依赖不得进入主干。
+
+4. 参考实现致谢
+
+   本项目设计参考自 HMCL（https://github.com/HMCL-dev/HMCL）与 PCL2
+   （https://github.com/Meloong-Git/PCL），两者均为 GPL-3.0，特此致谢。
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8858d2c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,243 @@
+# Unlucky Launcher (ULL)
+
+**English** · [简体中文](README.zh-CN.md)
+
+> **Official project home**: https://github.com/AskaEth/Unlucky-Launcher ｜ downloads, issues and
+> release notes all live there: <https://github.com/AskaEth/Unlucky-Launcher/releases>
+
+Unlucky Launcher (ULL) is a free, open-source Minecraft: Java Edition launcher written in Rust
+(Apache-2.0). It ships as one native binary per platform — no installer, no bundled runtime, no
+WebView. The launcher embeds an AI agent client (chat / configuration / crash diagnosis) and can be
+attached to other agent tooling as an MCP server.
+
+## Highlights
+
+- **Single-file native binary**: the launcher itself needs no JVM, no WebView and no sidecar
+  runtime. The JDK a game needs is downloaded and managed per instance, not as a launcher
+  dependency.
+- **One binary, two shapes**: the GUI binary also answers every CLI subcommand before any UI code
+  runs — no window, no renderer probe, no font scan. A second, lighter `ull` artifact serves the
+  same command set from a binary that links no graphics stack at all.
+- **One UI stack**: iced 0.14 + Material 3 Expressive, with self-drawn title bar, animated
+  navigation rail, light / dark / follow-system, and a background-image colour pipeline. The earlier
+  Slint implementation (`crates/app`) is kept as source-only history: excluded from the cargo
+  workspace, never built, tested or shipped.
+- **CPU software-rendering fallback**: `--software-renderer` keeps the interface rendering normally
+  on machines with no usable GPU or with broken drivers; the backend probe falls back on its own when
+  no adapter is usable.
+- **AI agent + MCP**: chat, setting edits and crash diagnosis inside the launcher; `ull agent serve`
+  exposes the same core as an MCP server (stdio or Streamable HTTP) to external agent tools. The
+  agent rail runs on real presenter state, and says so plainly when no model endpoint is wired.
+- **Mod loaders and modpacks**: Fabric, Quilt, NeoForge, Forge; CurseForge manifest, Modrinth
+  `.mrpack` and MultiMC/Prism packs import, plus mrpack / CurseForge export.
+- **Java management**: a Temurin → Oracle → Microsoft → Zulu fallback chain, region-aware.
+- **Accounts**: Microsoft sign-in over OAuth 2.0 device code flow → Xbox Live → XSTS →
+  `api.minecraftservices.com`; third-party community auth servers; local offline profiles for
+  isolated testing. Account tokens are kept on this machine only.
+- **Engine**: multi-source download (health scoring, mirrors, chunked transfers, hash while
+  downloading) and a YAML rule-based crash diagnosis engine.
+- **License**: Apache-2.0 © AskaEth (YeiJ).
+
+## Status
+
+`v0.1.0` (2026-11-01) predates the UI rewrite: its assets are Slint builds, and it stays the last
+Slint tag. `v0.2.0` is the first tag after the rewrite — the iced line, which is what the release
+pipeline builds now. Everything described below lives on that line.
+
+- **The iced UI is feature-complete**: fourteen pages — instances, version management (three-column
+  rail layout with search), content library (modpacks / mods / resource packs / shaders with source
+  and version filters), logs, settings (general / appearance / Java / downloads), accounts
+  (Microsoft device code, third-party community servers, local profiles), the AI rail and the
+  installer flows — on top of one component library and one token set.
+- **Localisation follows the system language**: detection, an explicit override in settings, and
+  persistence across restarts. UI copy goes through a single message catalogue; there is no
+  hard-coded string in the view layer.
+- **Appearance**: window background image, per-panel transparency and whole-window transparency
+  (Windows), light / dark / follow-system, and system window corners where the platform grants them.
+  On CPU rendering the translucent layers are switched off and the UI says so.
+- **Packaging and the installer paths** (curseforge / modrinth / multimc import, mrpack and
+  CurseForge export, install options with loader selection and real cancellation) are in the build.
+- **What is not done yet**: installers / auto-update channel; macOS re-verification on a real
+  machine after the Windows pass; per-file conflict policy on pack import (the import pipeline has one
+  global policy today, and the UI states that rather than pretending otherwise); a native file
+  chooser (import accepts drag-and-drop and a pasted path).
+
+Binaries you may run into, so you can tell them apart:
+
+| Binary | Crate | State |
+|--------|-------|-------|
+| `unlucky-launcher-iced` | `crates/app-iced` (iced 0.14) | the GUI binary the workspace builds; the release pipeline stages it under the public name `unlucky-launcher`; the same binary answers every CLI subcommand |
+| `unlucky-launcher` | `crates/app` (Slint) | **historical**: that crate is excluded from the workspace, so this binary is no longer built or shipped; the v0.1.0 assets are the last Slint builds |
+| `ull` | `crates/cli` | the zero-UI build of the same command set, shipped as its own asset |
+
+`unlucky-launcher` (the GUI) and `ull` are not duplicates. The GUI binary needs the graphics stack
+when it opens a window (it `dlopen`s X11 / Wayland / GL, and links `libfontconfig` at load); `ull`
+needs nothing beyond glibc, so it runs on a server, a CI container or Termux where no window can
+exist. Pick `ull` when there is no desktop, `unlucky-launcher <command>` when there is. Both print the
+same CLI text and name themselves after the binary you invoked: `unlucky-launcher --help` starts with
+`unlucky-launcher ·`, `ull --help` starts with `ull ·`.
+
+### Subcommand dispatch
+
+`unlucky-launcher <args>` first asks "is this a CLI call?" before any UI code runs:
+
+```bash
+unlucky-launcher                       # GUI
+unlucky-launcher --software-renderer   # GUI, CPU renderer (unchanged)
+unlucky-launcher instances list        # CLI, no window
+unlucky-launcher --json launch 1.20.1  # CLI, global options before the command
+unlucky-launcher --version             # CLI, prints version + OS summary
+```
+
+The rule is deliberately narrow, so nothing that used to work changed meaning:
+
+- The first argument is a bare word (not `-…`) → it sits in the subcommand position, so the CLI gets
+  it. GUI flags never appear there: `--screenshot` / `--diff` / `--data-dir` take their values
+  *after* the flag.
+- The first argument is a flag → the line is a CLI call only if `crates/cli`'s parser also produces a
+  real command (`--help`, `--version`, `--json instances list`). `--data-dir X` alone parses to "no
+  subcommand", so it still opens the GUI; every GUI-only flag (`--software-renderer`,
+  `--screenshot*`, `--renderer`, `--theme`, `--diff`, `--force-state`, …) fails CLI parsing, so it
+  still opens the GUI.
+
+**Unknown subcommands are an error, not a GUI launch**: `unlucky-launcher lst` prints
+"未知命令 `lst`", hints `unlucky-launcher --help`, and exits 1. Silently opening a window would tell
+a script that its typo took effect. The subcommand table itself lives in exactly one place —
+`crates/cli/src/cli/parse.rs` — so both the GUI binary and `ull` accept the same set by construction.
+
+## Module map
+
+```
+Unlucky-Launcher (cargo workspace)
+├── crates/core       # domain library: zero UI dependencies, eight modules
+├── crates/agent      # AI agent: ToolSpec registry + built-in client + MCP server (one core, two shapes)
+├── crates/presenter  # business host layer: framework-free state / host / dto / conversion
+├── crates/design     # design tokens: real HCT color / type / shape / spacing / elevation / motion / icons
+│                     #   / component metrics — zero UI dependencies, no third-party crates
+├── crates/i18n       # language detection, message catalogue, CJK font policy
+├── crates/palette-extract  # the only crate that decodes images, for the wallpaper colour pipeline
+├── crates/app        # HISTORICAL Slint UI (bin `unlucky-launcher`): excluded from the workspace,
+│                     #   source-only reference — never built, tested or shipped any more
+├── crates/app-iced   # the iced UI (bin `unlucky-launcher-iced`): the only GUI the workspace builds
+├── crates/cli        # CLI (bin `ull`): headless, zero UI
+└── packaging         # single-file artifact matrix and release scripts
+```
+
+Layering: `app-iced` → `presenter` → `core` / `agent`. `design` and `i18n` are consumed by the shell
+and the presenter; none of them may depend on a rendering framework, and the guards enforce it.
+
+The eight modules of `crates/core`:
+
+| Module | Responsibility |
+|--------|----------------|
+| `setting` | three data-directory modes, schema-based config, atomic writes, migrations |
+| `download` | multi-source health scoring, mirrors, chunked downloads, hash-while-downloading |
+| `game` | version / instance repository, snapshots and inheritance resolution |
+| `launch` | 10-stage launch pipeline, processes, JSONL event stream |
+| `auth` | Microsoft sign-in (OAuth 2.0 device code → Xbox Live → XSTS → Minecraft Services), third-party community servers, local profiles |
+| `addon` | mod loader installation, modpack import, CurseForge / Modrinth, pack export |
+| `diagnose` | five signal collectors, YAML rule engine, hs_err parsing |
+| `platform` | OS abstraction: paths, processes, file locks, capability probing, runtime OS detection |
+
+## Building
+
+Prerequisites:
+
+- Rust stable (`rust-toolchain.toml` selects the toolchain automatically; the gates also need the
+  `rustfmt` and `clippy` components)
+- Windows: MSVC toolchain (what CI uses) or MinGW-w64 (`x86_64-pc-windows-gnu`)
+- Linux: `libxkbcommon-dev libfontconfig1-dev libgl1-mesa-dev libegl1-mesa-dev libwayland-dev
+  libxcb1-dev` — winit + wgpu/tiny-skia ask for these at build time
+
+```bash
+cargo fmt --all --check                                # formatting
+cargo clippy --workspace --all-targets -- -D warnings  # lints (zero-warning gate)
+cargo test --workspace                                 # tests
+cargo build --release                                  # binaries land in target/release/
+```
+
+`--workspace` covers the members in the module map. `crates/app` is excluded at the workspace level
+(M118), so none of these commands compiles the Slint tree — and there is no build command for it:
+that crate is kept as source-only reference and can no longer be built as a workspace member.
+
+What the build produces:
+
+- `unlucky-launcher-iced` — the GUI (iced). It is also the CLI: the same binary answers every
+  subcommand listed above. The name is temporary — it becomes `unlucky-launcher` at the flip. The
+  release artifacts already carry the public name: the pipeline builds this bin and
+  `packaging/make_artifacts.py` stages it as `unlucky-launcher[.exe]`, so download links never change.
+- `unlucky-launcher` — **historical**: no workspace build produces this binary any more; it belonged
+  to `crates/app`, which is excluded. The v0.1.0 assets are the last builds under this name.
+- `ull` — the CLI as a standalone, UI-free binary. Same command set, no graphics stack, smaller, and
+  the right artifact for a machine that has no display at all.
+
+Rendering switches:
+
+- `unlucky-launcher-iced --software-renderer` forces tiny-skia (`ICED_BACKEND=tiny-skia`);
+  `--screenshot <png>` writes one frame and exits, which is the acceptance channel CI's headless
+  smoke job uses
+- With no usable adapter the iced build's explicit probe falls back to the CPU path on its own
+- **Historical** (v0.1.0's Slint build still takes it): `unlucky-launcher --software-renderer`, i.e.
+  `SLINT_BACKEND=winit-software`, forced the CPU renderer of that build through its own fallback chain
+
+Dependency license check (optional locally, required in CI):
+`cargo deny check licenses bans sources`.
+
+## CI gates
+
+Every push to `main` and every pull request runs fmt / clippy (warnings are errors) / the full test
+suite, and the Linux headless render smoke is a hard gate on the same footing: a red result blocks
+the merge. The macOS runtime probe is not there yet — it only runs on a manual `workflow_dispatch`
+and its result is recorded, not enforced (`continue-on-error`), until the slot passes a first run on
+a real runner.
+
+| Workflow | Content |
+|----------|---------|
+| `.github/workflows/ci.yml` | fmt + clippy + test + release build (Windows / Linux matrix); Linux runtime smoke (Xvfb: renders one real frame, then asserts the PNG is not blank); macOS runtime probe (manual dispatch only) |
+| `.github/workflows/guards.yml` | zero-UI guards (`crates/core`, `crates/presenter`, `crates/design`), 400-lines-per-file guard, cargo-deny license and source guard |
+| `.github/workflows/release.yml` | tag `v*` → per-slot builds → single-file artifacts + `SHA256SUMS.txt` → GitHub Release |
+
+## Platform baseline
+
+Minimum baseline: **Windows 10**; Windows 8.1 / 8 / 7 are not supported.
+
+- Windows 10/11 builds use the **standard toolchain** (MSVC / GNU), built the same way as
+  upstream cargo
+- macOS 12+ (Apple Silicon and Intel) and Linux x64 / arm64 are supported build slots; on Linux,
+  X11 is the preferred path today and Wayland is the long-term direction. macOS builds are unsigned,
+  so the first launch needs the Gatekeeper quarantine attribute cleared
+  (`xattr -d com.apple.quarantine`)
+- Android Termux is experimental and not promised: CLI only, GUI unverified
+- Each platform runs its own test matrix; capability differences use feature gates with runtime
+  probing.
+
+## License and acknowledgements
+
+- **This project**: Apache License 2.0, see [LICENSE](LICENSE); third-party notices in
+  [NOTICE](NOTICE).
+- **Slint** (<https://slint.dev>), Royalty-Free 2.0: obligation for the Slint build that `v0.1.0`
+  ships — the condition attaches to each distribution of an Application, not to a version number.
+  Upstream §2 offers two forms: (a) the official `AboutSlint` widget on an "About" screen or dialog
+  reachable from the top level menu (or the splash screen when there is none); (b) the official Slint
+  attribution badge on a public page where the binaries can be downloaded. **`v0.1.0`'s settings page
+  does embed the `AboutSlint` widget** (`crates/app/ui/pages/settings.slint`, reachable from the
+  sidebar); whether that satisfies §2(a), and the fact that the `v0.1.0` release page carries a text
+  link rather than the §2(b) badge, are **not judged here** — Slint's own licence text is the
+  authority. The `v0.1.0` NOTICE, that page's text and this section are **records, not a statement of
+  discharge**. Later builds link no Slint, so they add nothing to this obligation. The obligation
+  follows a **Slint-linked binary**: it applies to the `v0.1.0` assets (and to any later build that
+  links Slint again), not to new iced builds — `crates/app` is excluded from the workspace, so the
+  pipeline no longer produces one.
+- **iced** (<https://github.com/iced-rs/iced>), MIT: the framework of the UI, together with `winit`
+  (Apache-2.0) and, through it, `wgpu` (MIT / Apache-2.0) / `tiny-skia` (BSD-3-Clause).
+- **Google Material Color Utilities** (Apache-2.0): the color tokens in `crates/design` are a Rust
+  port of its HCT / ColorSpec2021 algorithms; details and the exact ported functions are listed in
+  [NOTICE](NOTICE).
+- **Other major dependencies**: `rmcp` and `axum` (Apache-2.0 / MIT) for the MCP server, `tokio`
+  (MIT), `reqwest` with rustls (MIT / Apache-2.0), `serde` / `serde_json` (MIT / Apache-2.0),
+  `zip` / `flate2` / `tar` (MIT / Apache-2.0). The allow-list cargo-deny enforces is in `deny.toml`;
+  GPL-family dependencies may not enter the main line.
+
+Thanks to [HMCL](https://github.com/HMCL-dev/HMCL) and [PCL2](https://github.com/Meloong-Git/PCL)
+(both GPL-3.0). They have been with the vast majority of Minecraft players for years, and this
+project has benefited a great deal from their design choices and implementation details.
diff --git a/README.zh-CN.md b/README.zh-CN.md
new file mode 100644
index 0000000..6143e5d
--- /dev/null
+++ b/README.zh-CN.md
@@ -0,0 +1,203 @@
+# Unlucky Launcher (ULL)
+
+[English](README.md) · **简体中文**
+
+> **官方项目主页**：https://github.com/AskaEth/Unlucky-Launcher ｜ 下载、议题、发布说明都在这里：
+> <https://github.com/AskaEth/Unlucky-Launcher/releases>
+
+Unlucky Launcher（ULL）是一个用 Rust 写的免费开源 Minecraft: Java 版启动器（Apache-2.0）。
+每个平台就一个原生二进制——没有安装包、没有捆绑运行时、没有 WebView。启动器内置 AI Agent
+客户端（对话 / 改配置 / 崩溃诊断），也能作为 MCP server 接进别的 Agent 工具。
+
+## 特性
+
+- **单文件原生二进制**：启动器本体不需要 JVM、不需要 WebView、不带旁挂运行时。游戏要的 JDK 由
+  启动器按实例下载管理，不是启动器的依赖。
+- **默认构建里只有一套 UI**：UI 是 iced 0.14 + Material 3 Expressive。早先的 Slint 实现
+  （`crates/app`）作为**历史参考**保留源码：已被 workspace `exclude`，默认构建不编、测试不跑、
+  发布不发。`v0.1.0` 那个 tag 发的仍是 Slint 版；iced 重写后的第一个 tag 是 `v0.2.0`（见「当前状态」）。
+- **CPU 软渲染兜底**：`--software-renderer` 让没有可用 GPU 或驱动有问题的老机也能正常显示界面。
+- **AI Agent + MCP**：启动器内可对话、改设置、读崩溃诊断；`ull agent serve` 把同一个内核以 MCP
+  server 形态（stdio 或 Streamable HTTP）开放给外部 Agent 工具。
+- **加载器**：Fabric / Quilt / NeoForge / Forge；整合包与 CurseForge / Modrinth 客户端在 core 里。
+- **Java 管理**：Temurin → Oracle → Microsoft → Zulu 回退链，带地区判定。
+- **账户**：用 Microsoft 账户登录，认证走 OAuth 2.0 device code flow → Xbox Live → XSTS →
+  `api.minecraftservices.com`；账户令牌只保存在本机。
+- **引擎**：多源下载（健康度评分、镜像、分块传输、边下边算）与 YAML 规则引擎的崩溃诊断。
+- **许可**：Apache-2.0 © AskaEth (YeiJ)。
+
+## 当前状态
+
+`v0.1.0`（2026-11-01）早于 UI 重写：那批资产是 Slint 版，它也是最后一个 Slint 版 tag。重写之后的
+第一个 tag 是 `v0.2.0`——也就是 iced 这条线，下面说的这套东西都在线上，也正是发布流水线现在会打
+出来的东西。
+
+- **iced 版界面功能已齐**：十四页——实例、版本管理（三栏 + 搜索）、内容库（整合包 / Mod / 资源包 /
+  光影，带来源与版本筛选）、日志、设置（通用 / 外观 / Java / 下载）、账户（微软设备码、第三方社区服、
+  本地档案）、AI 右栏，以及安装流程——共用一套组件库与一套令牌。
+- **文案跟随系统语言**：自动探测、设置里可显式切换、重启后保持。界面文案统一走一份消息目录，视图层
+  没有硬编码字符串。
+- **外观**：窗口背景图、面板透明度、整窗透明度（Windows）、浅色 / 深色 / 跟随系统，以及在系统愿意给
+  的时候使用系统窗口圆角。CPU 渲染档会关掉半透明层，并在界面上说清楚。
+- **整合包与安装链路都在构建里**：CurseForge 清单 / Modrinth `.mrpack` / MultiMC·Prism 导入，mrpack
+  与 CurseForge 导出，安装选项（选加载器）与**真取消**。
+- **还没做**：安装器与自动更新通道；Windows 定型后的 macOS 真机复核；整合包导入的**逐文件**冲突策略
+  （当前只有一份全局策略，界面如实写明而不是假装支持）；原生文件选择框（导入支持拖拽与粘贴路径）。
+- **Slint 版已退出构建，只留源码作参考**：`crates/app` 不再是 workspace 成员（M118）——源码留作历史
+  参考，不编译、不测试、不发布，也不再有可用的构建方式。翻牌只剩**改名**这一步：它的 bin 现在叫
+  `unlucky-launcher-iced`，发布流水线已经把它按对外名 `unlucky-launcher` 打出去。
+
+可能会遇到的 bin，先认清楚：
+
+| 二进制 | crate | 状态 |
+|--------|-------|------|
+| `unlucky-launcher-iced` | `crates/app-iced`（iced 0.14） | workspace 里**唯一**的 GUI bin；发布流水线把它按对外名 `unlucky-launcher` 落盘；子命令分发同款 |
+| `unlucky-launcher` | `crates/app`（Slint） | **历史**：该 crate 已被 workspace `exclude`，这个 bin 不再被构建或分发；`v0.1.0` 的资产是最后一批 Slint 版 |
+| `ull` | `crates/cli` | 同一套命令的零 UI 构建，作为独立资产随发布分发 |
+
+`unlucky-launcher` 与 `ull` 不是重复品：开窗时 GUI 二进制要用图形栈（X11 / Wayland / GL 走
+`dlopen`，启动时直接链接 `libfontconfig`）；`ull` 除了 glibc 什么都不需要，所以在没有窗口的服务器、
+CI 容器、Termux 上跑得起来。没有桌面就用 `ull`，有桌面就用 `unlucky-launcher <子命令>`。两者打出来的
+CLI 文案是同一套，自称的名字跟着**你敲的那个二进制**走：`unlucky-launcher --help` 首行是
+`unlucky-launcher ·`，`ull --help` 首行是 `ull ·`。
+
+### 子命令分发
+
+`unlucky-launcher <参数>` 在跑任何 UI 代码之前先问一句「这是不是一次 CLI 调用」：
+
+```bash
+unlucky-launcher                       # GUI
+unlucky-launcher --software-renderer   # GUI，CPU 渲染（行为不变）
+unlucky-launcher instances list        # CLI，不开窗
+unlucky-launcher --json launch 1.20.1  # CLI，全局选项排在子命令前面
+unlucky-launcher --version             # CLI，输出版本 + 系统摘要
+```
+
+判据刻意收得很窄，所以原本能用的用法一条都没变：
+
+- 第一个参数是裸词（不以 `-` 开头）→ 它就在子命令的位置上，交给 CLI。GUI 的 flag 永远不会出现在
+  那个位置：`--screenshot` / `--diff` / `--data-dir` 的取值都排在 flag 之后。
+- 第一个参数是 flag → 只有当 `crates/cli` 的解析器也解析出一条真命令时才算 CLI 调用
+  （`--help`、`--version`、`--json instances list`）。单独 `--data-dir X` 解析成「没有子命令」，
+  仍然开 GUI；GUI 专属参数（`--software-renderer`、`--screenshot*`、`--renderer`、`--theme`、
+  `--diff`、`--force-state` 等）在 CLI 里一律解析失败，也仍然开 GUI。
+
+**未知子命令是错误，不是开窗**：`unlucky-launcher lst` 打印「未知命令 `lst`」、提示
+`unlucky-launcher --help`，以 1 退出。静默开窗会让脚本以为自己那个拼错的参数生效了。子命令表只有
+一处定义（`crates/cli/src/cli/parse.rs`），所以两个 GUI 二进制和 `ull` 认的命令集天然一致。
+
+## 模块地图
+
+```
+Unlucky-Launcher (cargo workspace)
+├── crates/core       # 领域库：零 UI 依赖，八模块
+├── crates/agent      # AI Agent：ToolSpec 注册表 + 内置客户端 + MCP server（双形态共用一个内核）
+├── crates/presenter  # 业务宿主层：与框架无关的 state / host / dto / 转换
+├── crates/design     # 设计令牌：真 HCT 色彩 / 排版 / 形状 / 间距 / 高程 / 动效 / 图标 / 组件度量
+│                     #   —— 零 UI 依赖、零第三方 crate
+├── crates/i18n       # 语言探测、消息目录、中文字体策略
+├── crates/palette-extract  # 唯一解码图片的 crate，供壁纸取色链路使用
+├── crates/app        # 历史 Slint UI（bin `unlucky-launcher`）：已被 workspace `exclude`，
+│                     #   仅作源码参考——不再被构建 / 测试 / 发布
+├── crates/app-iced   # iced UI（bin `unlucky-launcher-iced`）：workspace 里唯一的 GUI bin
+├── crates/cli        # CLI（bin `ull`）：headless，零 UI
+└── packaging         # 单文件产物矩阵与发布脚本
+```
+
+`crates/core` 的八个模块：
+
+| 模块 | 职责 |
+|------|------|
+| `setting` | 三模式数据目录、schema 配置、原子写、迁移 |
+| `download` | 多源健康度、镜像、分块下载、边下边算 |
+| `game` | 版本/实例仓库、快照与继承解析 |
+| `launch` | 10 阶段启动管线、进程、JSONL 事件流 |
+| `auth` | Microsoft 账户登录（OAuth 2.0 device code → Xbox Live → XSTS → Minecraft Services） |
+| `addon` | 加载器安装、整合包、CurseForge / Modrinth |
+| `diagnose` | 五类信号采集、YAML 规则引擎、hs_err 解析 |
+| `platform` | OS 抽象：路径、进程、文件锁、能力探测、运行期 OS 检测 |
+
+## 构建
+
+前置：
+
+- Rust stable（`rust-toolchain.toml` 会自动选工具链；门禁还需要 `rustfmt` / `clippy` 组件）
+- Windows：MSVC 工具链（CI 用这套）或 MinGW-w64（`x86_64-pc-windows-gnu`）
+- Linux：`libxkbcommon-dev libfontconfig1-dev libgl1-mesa-dev libegl1-mesa-dev libwayland-dev
+  libxcb1-dev`——winit + wgpu/tiny-skia 编译期要用（Slint 版当年还要 femtovg）
+
+```bash
+cargo fmt --all --check                                # 格式
+cargo clippy --workspace --all-targets -- -D warnings  # 静态检查（零 warning 门禁）
+cargo test --workspace                                 # 测试
+cargo build --release                                  # bin 落在 target/release/
+```
+
+`--workspace` 就是模块地图里那八个成员：`crates/app` 已在 workspace 层被排除（M118），上面这些命令
+都不会编 Slint 那棵树——而且**它没有构建方式**：该 crate 只作源码参考，作为 workspace 成员已不可编。
+
+编出来的 bin：
+
+- `unlucky-launcher-iced`——GUI（iced）。它同时也是 CLI：同一个二进制认上面列的全部子命令。名字是
+  临时的，翻牌时才改成 `unlucky-launcher`；发布产物**已经**用对外名：流水线编这个 bin，
+  `packaging/make_artifacts.py` 落盘时改成 `unlucky-launcher[.exe]`，所以下载链接不用变。
+- `unlucky-launcher`——**历史**：workspace 构建已不产出它（它属于被排除的 `crates/app`）。
+  `v0.1.0` 的资产是最后一批用这个名字发出去的构建。
+- `ull`——CLI 的独立无 UI 构建：同一套命令、不链接图形栈、体积更小，给完全没有显示设备的机器用。
+
+渲染开关：
+
+- `unlucky-launcher-iced --software-renderer` 强制 tiny-skia（`ICED_BACKEND=tiny-skia`）；
+  `--screenshot <png>` 出一帧图后退出，这是 CI 无头冒烟 job 用的验收通道
+- 没有可用适配器时，iced 版靠显式后端探测自己退到 CPU
+- **历史**（`v0.1.0` 的 Slint 版仍认这条）：`unlucky-launcher --software-renderer`，即
+  `SLINT_BACKEND=winit-software`，让那一版走它自己的渲染器回退链
+
+依赖许可检查（本地可选，CI 必跑）：`cargo deny check licenses bans sources`。
+
+## CI 门禁
+
+每次推送到 `main` 与每个 PR 都跑 fmt / clippy（warnings 视为错误）/ 全量测试，Linux 无头渲染冒烟
+与它们同级、是硬门禁：红了就不许合。macOS 运行期探针还不算——它只在手动 `workflow_dispatch` 时跑，
+结果留证据但不作为流水线结论（`continue-on-error`），直到该槽位在真实 runner 上首跑通过。
+
+| Workflow | 内容 |
+|----------|------|
+| `.github/workflows/ci.yml` | fmt + clippy + test + release build（Windows / Linux 矩阵）；Linux runtime smoke（Xvfb 里真渲染一帧，再断言 PNG 非空白）；macOS 运行期探针（仅手动 dispatch） |
+| `.github/workflows/guards.yml` | `crates/core` 零 UI 守门（依赖表 + `cargo tree`）、单文件 ≤400 行守门、cargo-deny 许可与来源守门 |
+| `.github/workflows/release.yml` | tag `v*` → 分槽位构建 → 单文件产物 + `SHA256SUMS.txt` → GitHub Release |
+
+## 平台基线
+
+最低基线 **Windows 10**；Windows 8.1 / 8 / 7 不在支持范围内。
+
+- Windows 10/11 的产物由**标准工具链**（MSVC / GNU）构建，构建方式与上游 cargo 一致
+- macOS 12+（Apple Silicon 与 Intel）与 Linux x64 / arm64 都是支持槽位；Linux 上 X11 是当前首选路径，
+  Wayland 是大方向。macOS 产物未签名，首次启动要自己清掉 Gatekeeper 隔离标记
+  （`xattr -d com.apple.quarantine`）
+- Android Termux 试验级、不承诺：只保证 CLI，GUI 未验证
+- 每个平台跑各自的测试矩阵；能力差异用 feature gate + 运行期探测表达。
+
+## 许可证与致谢
+
+- **本项目**：Apache License 2.0，见 [LICENSE](LICENSE)；第三方声明见 [NOTICE](NOTICE)。
+- **Slint**（<https://slint.dev>），Royalty-Free 2.0：义务针对 `v0.1.0` 发布的那批构建——条件挂在每一次
+  「随应用分发」上，而不是挂在某个版本号上。上游 §2 给出两种形式：(a) 在可从顶层菜单进入的「关于」页/
+  对话框里显示官方 `AboutSlint` 部件（没有该页时改为启动画面）；(b) 在可下载该二进制的公开网页上显示
+  官方归属徽章。**`v0.1.0` 的设置页「关于」分组里内置了 `AboutSlint` 部件**（`crates/app/ui/pages/
+  settings.slint`，从侧栏进入）；该部件是否满足 §2(a) 的全部条件、以及 `v0.1.0` 发布页上那是文字链接
+  而不是 §2(b) 点名的官方徽章图这两点，**本节不作法律判断**，具体以 Slint 官方许可原文为准。`v0.1.0`
+  的 NOTICE、发布页说明与本节**都只是记录，不构成履行声明**。后续版本不再链接 Slint，该义务不随新产物
+  新增。义务跟着**链接了 Slint 的产物**走：已发布的 `v0.1.0` 资产（以及将来任何重新链接 Slint 的构建）
+  适用；`crates/app` 已被 workspace `exclude`，流水线不再产出链接 Slint 的二进制，所以新的 iced 版不适用。
+- **iced**（<https://github.com/iced-rs/iced>），MIT：现役 UI 的框架；与它同栈的 `winit`（Apache-2.0）、
+  以及经它引入的 `wgpu`（MIT / Apache-2.0）/ `tiny-skia`（BSD-3-Clause）。
+- **Google Material Color Utilities**（Apache-2.0）：`crates/design` 的色彩令牌是它 HCT /
+  ColorSpec2021 算法的 Rust 重写移植，移植清单与逐函数对照写在 [NOTICE](NOTICE)。
+- **其余主要依赖**：MCP server 的 `rmcp` 与 `axum`（Apache-2.0 / MIT）、`tokio`（MIT）、`reqwest`
+  与 rustls（MIT / Apache-2.0）、`serde` / `serde_json`（MIT / Apache-2.0）、`zip` / `flate2` / `tar`
+  （MIT / Apache-2.0）。cargo-deny 强制执行的白名单在 `deny.toml`；GPL 系依赖不得进主干。
+
+感谢 [HMCL](https://github.com/HMCL-dev/HMCL) 和 [PCL2](https://github.com/Meloong-Git/PCL)
+（均 GPL-3.0）。这两款启动器陪着绝大多数 MC 玩家走了很多年，
+本项目在设计取舍与实现细节上都从中受益良多。
diff --git a/clippy.toml b/clippy.toml
new file mode 100644
index 0000000..aca5e9c
--- /dev/null
+++ b/clippy.toml
@@ -0,0 +1,7 @@
+# 与 Cargo.toml 的 rust-version 同步；改 MSRV 时两处一起改。
+msrv = "1.92"
+
+# core 的模块边界很薄，参数多于 8 个基本说明该拆结构体了。
+too-many-arguments-threshold = 8
+# 领域类型（版本号、哈希、URL）普遍是短名，不做最小名长惩罚。
+min-ident-chars-threshold = 2
diff --git a/crates/agent/Cargo.toml b/crates/agent/Cargo.toml
new file mode 100644
index 0000000..72e1520
--- /dev/null
+++ b/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" }
+
+# 序列化：工具 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
diff --git a/crates/agent/src/audit.rs b/crates/agent/src/audit.rs
new file mode 100644
index 0000000..de0f7ec
--- /dev/null
+++ b/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);
+    }
+}
diff --git a/crates/agent/src/brain/chat.rs b/crates/agent/src/brain/chat.rs
new file mode 100644
index 0000000..d3f0cf5
--- /dev/null
+++ b/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\""));
+    }
+}
diff --git a/crates/agent/src/brain/exec.rs b/crates/agent/src/brain/exec.rs
new file mode 100644
index 0000000..2efbc59
--- /dev/null
+++ b/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,
+        });
+    }
+}
diff --git a/crates/agent/src/brain/mod.rs b/crates/agent/src/brain/mod.rs
new file mode 100644
index 0000000..152fb18
--- /dev/null
+++ b/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, 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,
+        }
+    }
+}
diff --git a/crates/agent/src/brain/provider.rs b/crates/agent/src/brain/provider.rs
new file mode 100644
index 0000000..804fa3d
--- /dev/null
+++ b/crates/agent/src/brain/provider.rs
@@ -0,0 +1,340 @@
+//! 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};
+
+/// 本地 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 => "",
+        }
+    }
+
+    /// 设置页展示名。
+    #[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::new(
+                "AI 已禁用：请在设置 → AI 中选择端点（规则引擎诊断不受影响）",
+            ));
+        }
+        if self.model.trim().is_empty() {
+            return Err(ProviderError::new("没有配置模型名（model）"));
+        }
+        if self.resolved_base_url().trim().is_empty() {
+            return Err(ProviderError::new(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::new(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 层错误（消息面向用户：端点连不上、key 无效、模型不存在）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProviderError {
+    message: String,
+}
+
+impl ProviderError {
+    /// 从可读文本构造。
+    #[must_use]
+    pub fn new(message: impl Into<String>) -> Self {
+        Self {
+            message: message.into(),
+        }
+    }
+}
+
+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)]
+mod tests {
+    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 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}"
+        );
+    }
+}
diff --git a/crates/agent/src/brain/rig.rs b/crates/agent/src/brain/rig.rs
new file mode 100644
index 0000000..3043564
--- /dev/null
+++ b/crates/agent/src/brain/rig.rs
@@ -0,0 +1,368 @@
+//! 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::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, 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 错误 → 本方错误（文案面向用户）。
+fn map_error(error: RigError) -> ProviderError {
+    ProviderError::new(error.to_string())
+}
+
+/// 工具名 → rig 的 [`RigToolName`]（空名是唯一的非法输入）。
+fn tool_name(name: &str) -> Result<RigToolName, ProviderError> {
+    RigToolName::new(name)
+        .map_err(|_| ProviderError::new("工具名不能为空（ToolSpec 注册阶段应已拦截）"))
+}
+
+#[cfg(test)]
+mod tests {
+    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("对话历史为空"));
+    }
+}
diff --git a/crates/agent/src/clock.rs b/crates/agent/src/clock.rs
new file mode 100644
index 0000000..f24b042
--- /dev/null
+++ b/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);
+    }
+}
diff --git a/crates/agent/src/confirm.rs b/crates/agent/src/confirm.rs
new file mode 100644
index 0000000..8689c24
--- /dev/null
+++ b/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\""
+        );
+    }
+}
diff --git a/crates/agent/src/event.rs b/crates/agent/src/event.rs
new file mode 100644
index 0000000..20e75d8
--- /dev/null
+++ b/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 { .. })));
+    }
+}
diff --git a/crates/agent/src/lib.rs b/crates/agent/src/lib.rs
new file mode 100644
index 0000000..909f19b
--- /dev/null
+++ b/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;
diff --git a/crates/agent/src/mcp/mod.rs b/crates/agent/src/mcp/mod.rs
new file mode 100644
index 0000000..7687567
--- /dev/null
+++ b/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}");
+    }
+}
diff --git a/crates/agent/src/mcp/projection.rs b/crates/agent/src/mcp/projection.rs
new file mode 100644
index 0000000..ffb5ae5
--- /dev/null
+++ b/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);
+        }
+    }
+}
diff --git a/crates/agent/src/mcp/sample.rs b/crates/agent/src/mcp/sample.rs
new file mode 100644
index 0000000..b533895
--- /dev/null
+++ b/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());
+    }
+}
diff --git a/crates/agent/src/mcp/serve.rs b/crates/agent/src/mcp/serve.rs
new file mode 100644
index 0000000..e1ddcc5
--- /dev/null
+++ b/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()
+}
diff --git a/crates/agent/src/mcp/server.rs b/crates/agent/src/mcp/server.rs
new file mode 100644
index 0000000..e0546f2
--- /dev/null
+++ b/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());
+    }
+}
diff --git a/crates/agent/src/port.rs b/crates/agent/src/port.rs
new file mode 100644
index 0000000..c95c3e1
--- /dev/null
+++ b/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>;
+}
diff --git a/crates/agent/src/port/game.rs b/crates/agent/src/port/game.rs
new file mode 100644
index 0000000..b5b312c
--- /dev/null
+++ b/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));
+    }
+}
diff --git a/crates/agent/src/redact.rs b/crates/agent/src/redact.rs
new file mode 100644
index 0000000..5ec81d3
--- /dev/null
+++ b/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"));
+    }
+}
diff --git a/crates/agent/src/registry/mod.rs b/crates/agent/src/registry/mod.rs
new file mode 100644
index 0000000..98bb426
--- /dev/null
+++ b/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);
+    }
+}
diff --git a/crates/agent/src/registry/schema.rs b/crates/agent/src/registry/schema.rs
new file mode 100644
index 0000000..1fe57dc
--- /dev/null
+++ b/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());
+    }
+}
diff --git a/crates/agent/src/registry/spec.rs b/crates/agent/src/registry/spec.rs
new file mode 100644
index 0000000..4f03cb0
--- /dev/null
+++ b/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" }));
+    }
+}
diff --git a/crates/agent/src/registry/validate.rs b/crates/agent/src/registry/validate.rs
new file mode 100644
index 0000000..d3f32d2
--- /dev/null
+++ b/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());
+    }
+}
diff --git a/crates/agent/src/testing.rs b/crates/agent/src/testing.rs
new file mode 100644
index 0000000..1c899a2
--- /dev/null
+++ b/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()
+}
diff --git a/crates/agent/src/testing/diagnose.rs b/crates/agent/src/testing/diagnose.rs
new file mode 100644
index 0000000..7f914d2
--- /dev/null
+++ b/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
+                })
+            },
+        )
+    }
+}
diff --git a/crates/agent/src/testing/game.rs b/crates/agent/src/testing/game.rs
new file mode 100644
index 0000000..821b751
--- /dev/null
+++ b/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)
+    }
+}
diff --git a/crates/agent/src/testing/settings.rs b/crates/agent/src/testing/settings.rs
new file mode 100644
index 0000000..d72c518
--- /dev/null
+++ b/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"));
+    }
+}
diff --git a/crates/agent/src/tools/accounts.rs b/crates/agent/src/tools/accounts.rs
new file mode 100644
index 0000000..40f0661
--- /dev/null
+++ b/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!([]));
+    }
+}
diff --git a/crates/agent/src/tools/config.rs b/crates/agent/src/tools/config.rs
new file mode 100644
index 0000000..728771e
--- /dev/null
+++ b/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("磁盘只读"));
+    }
+}
diff --git a/crates/agent/src/tools/diagnose.rs b/crates/agent/src/tools/diagnose.rs
new file mode 100644
index 0000000..273797e
--- /dev/null
+++ b/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("需要更多信息"));
+    }
+}
diff --git a/crates/agent/src/tools/game.rs b/crates/agent/src/tools/game.rs
new file mode 100644
index 0000000..6e5fcfd
--- /dev/null
+++ b/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 目录不可读"));
+    }
+}
diff --git a/crates/agent/src/tools/mod.rs b/crates/agent/src/tools/mod.rs
new file mode 100644
index 0000000..87b9094
--- /dev/null
+++ b/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)
+}
diff --git a/crates/agent/src/tools/schema_tool.rs b/crates/agent/src/tools/schema_tool.rs
new file mode 100644
index 0000000..a746ac4
--- /dev/null
+++ b/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}");
+    }
+}
diff --git a/crates/agent/src/tools/session.rs b/crates/agent/src/tools/session.rs
new file mode 100644
index 0000000..2d1c5aa
--- /dev/null
+++ b/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("不存在"));
+    }
+}
diff --git a/crates/agent/tests/brain_loop.rs b/crates/agent/tests/brain_loop.rs
new file mode 100644
index 0000000..de43011
--- /dev/null
+++ b/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);
+}
diff --git a/crates/agent/tests/mcp_contract.rs b/crates/agent/tests/mcp_contract.rs
new file mode 100644
index 0000000..6dd5306
--- /dev/null
+++ b/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()));
+}
diff --git a/crates/agent/tests/mcp_http.rs b/crates/agent/tests/mcp_http.rs
new file mode 100644
index 0000000..44f62fe
--- /dev/null
+++ b/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);
+}
diff --git a/crates/agent/tests/schema_contract.rs b/crates/agent/tests/schema_contract.rs
new file mode 100644
index 0000000..d6f31e4
--- /dev/null
+++ b/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());
+}
diff --git a/crates/agent/tests/support/mod.rs b/crates/agent/tests/support/mod.rs
new file mode 100644
index 0000000..ce25225
--- /dev/null
+++ b/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 })
+}
diff --git a/crates/agent/tests/tools_security.rs b/crates/agent/tests/tools_security.rs
new file mode 100644
index 0000000..daa4d1a
--- /dev/null
+++ b/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, "对话历史不能带凭据明文");
+}
diff --git a/crates/app-iced/Cargo.toml b/crates/app-iced/Cargo.toml
new file mode 100644
index 0000000..092f6e0
--- /dev/null
+++ b/crates/app-iced/Cargo.toml
@@ -0,0 +1,92 @@
+[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" }
+
+# M85：UI 框架无关的宿主层（DTO / 状态 reducer / host）。**只登记依赖，本 mission 不接线**——
+# 页面用它的时机由后续 iced 页面 mission 决定（接线流程见 crates/presenter/src/lib.rs 的 crate 文档）。
+# 与 Slint 版共用同一套 host 与状态语义，这是 D26「重写只换渲染」的落点。
+unlucky-presenter = { path = "../presenter", version = "0.2" }
+
+# 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" }
+
+# M92（D28）：国际化地基（语言探测 / 消息目录 / 中文字体策略）。零依赖 crate——它拿不到 iced，
+# 所以系统字体扫描留在这里（`src/fonts/cjk.rs`），本 crate 只把族名喂给它的纯函数。
+unlucky-i18n = { path = "../i18n", version = "0.2" }
+
+# 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"]
+
+[lints]
+workspace = true
diff --git a/crates/app-iced/examples/pages_demo.rs b/crates/app-iced/examples/pages_demo.rs
new file mode 100644
index 0000000..34122bf
--- /dev/null
+++ b/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
+        }
+    }
+}
diff --git a/crates/app-iced/src/app/appearance.rs b/crates/app-iced/src/app/appearance.rs
new file mode 100644
index 0000000..68fe4c7
--- /dev/null
+++ b/crates/app-iced/src/app/appearance.rs
@@ -0,0 +1,130 @@
+//! 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 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");
+        }
+        eprintln!("{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（它知道怎么保留强调色这类本 mission 不管的字段）。
+            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`（只改本 mission 管的字段，强调色/玻璃原样保留）。
+    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;
+
+        self.bridge.persist(&prefs, self.theme_mode);
+        self.appearance_prefs = prefs;
+
+        match self.bridge.path() {
+            Some(path) => eprintln!("[settings] 外观已写回 {}", path.display()),
+            None => eprintln!("[settings] 外观未落盘（数据根解析不出来，内存态运行）"),
+        }
+    }
+}
diff --git a/crates/app-iced/src/app/backend.rs b/crates/app-iced/src/app/backend.rs
new file mode 100644
index 0000000..ab22442
--- /dev/null
+++ b/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"
+        );
+    }
+}
diff --git a/crates/app-iced/src/app/boot.rs b/crates/app-iced/src/app/boot.rs
new file mode 100644
index 0000000..182e421
--- /dev/null
+++ b/crates/app-iced/src/app/boot.rs
@@ -0,0 +1,248 @@
+//! 启动编排：**探测 → 字体 → 打印诊断 → 起 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 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;
+
+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` 里统一打）
+    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();
+    eprintln!("[font] 求值耗时 {:.0} ms", font_ms.as_secs_f64() * 1000.0);
+    eprintln!("{}", resolved.describe());
+    if resolved.has_synthetic() {
+        eprintln!(
+            "[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() {
+        eprintln!("[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) => {
+                    // 取证启动：**拒绝降级出图**（换了后端出的图会让报告撒谎）。
+                    eprintln!(
+                        "[gpu] 拒绝降级出图：本次是取证启动（--screenshot {}），换后端出的图会撒谎。",
+                        options
+                            .screenshot
+                            .as_ref()
+                            .map_or_else(String::new, |path| path.display().to_string())
+                    );
+                    eprintln!(
+                        "[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 的标题栏是留白带，出不了「三键位置」那张图）。
+    let (size, size_source) = acceptance::window_size(
+        (WINDOW_SIZE.width, WINDOW_SIZE.height),
+        (MIN_SIZE.width, MIN_SIZE.height),
+    );
+    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());
+        eprintln!(
+            "[probe] 本次是降级重开（{}={}）：跳过探测 -> ICED_BACKEND={}",
+            renderer::FALLBACK_ENV,
+            kind.env_value(),
+            kind.env_value()
+        );
+        eprintln!("[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) => eprintln!(
+                "[probe] 探测耗时 {:.0} ms（wgpu 实例 + 全后端适配器枚举）",
+                elapsed.as_secs_f64() * 1000.0
+            ),
+            None => eprintln!(
+                "[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;
diff --git a/crates/app-iced/src/app/boot/diagnostics.rs b/crates/app-iced/src/app/boot/diagnostics.rs
new file mode 100644
index 0000000..071fb7b
--- /dev/null
+++ b/crates/app-iced/src/app/boot/diagnostics.rs
@@ -0,0 +1,110 @@
+//! 启动阶段的**验收诊断编排**：把 `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 上会出现原生标题栏 + 自绘三键两套。
+        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);
+}
diff --git a/crates/app-iced/src/app/boot/fallback.rs b/crates/app-iced/src/app/boot/fallback.rs
new file mode 100644
index 0000000..ef20a28
--- /dev/null
+++ b/crates/app-iced/src/app/boot/fallback.rs
@@ -0,0 +1,117 @@
+//! 起步后端失败后的**兜底/重开**一簇：判据、进程环境交接、`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::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| {
+        eprintln!("[gpu] 降级重开失败：拿不到自身路径（{err}）");
+        std::process::exit(exit_code(None));
+    });
+    eprintln!(
+        "[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) => {
+            eprintln!("[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 {
+    let mut command = std::process::Command::new(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
+}
diff --git a/crates/app-iced/src/app/boot/tests.rs b/crates/app-iced/src/app/boot/tests.rs
new file mode 100644
index 0000000..b247030
--- /dev/null
+++ b/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}"
+    );
+}
diff --git a/crates/app-iced/src/app/message.rs b/crates/app-iced/src/app/message.rs
new file mode 100644
index 0000000..2fcaabb
--- /dev/null
+++ b/crates/app-iced/src/app/message.rs
@@ -0,0 +1,101 @@
+//! 应用消息：单一大枚举。
+//!
+//! 纪律：本枚举是**唯一**的消息类型，`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),
+}
+
+/// 外壳导航项 → 路由（导航项只在一级页之间有对应；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,
+    }
+}
diff --git a/crates/app-iced/src/app/mod.rs b/crates/app-iced/src/app/mod.rs
new file mode 100644
index 0000000..a58ccbb
--- /dev/null
+++ b/crates/app-iced/src/app/mod.rs
@@ -0,0 +1,71 @@
+//! 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 appearance;
+mod backend;
+mod boot;
+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;
diff --git a/crates/app-iced/src/app/state.rs b/crates/app-iced/src/app/state.rs
new file mode 100644
index 0000000..2ab97b1
--- /dev/null
+++ b/crates/app-iced/src/app/state.rs
@@ -0,0 +1,188 @@
+//! 应用状态：**只放字段与构造**，不放消息分支（那是 [`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）。
+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;
+mod construct;
+mod refresh;
+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,
+    /// 窗口高度（背景图平铺网格的视口判据；宽度在 `width`）。
+    pub(super) height: f32,
+    /// 外观运行期状态（M93）：面板 α / 背景图 / 配色来源 / 诊断。
+    pub(super) appearance: pages::appearance::State,
+    /// 设置文件里那 8 个「UI 写入」外观字段的最近快照（写回时只改我们真改了的字段，
+    /// 强调色这类本 mission 不管的字段原样保留）。
+    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,
+    /// 内容库页的页面内选择（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,
+    /// 皮肤/头像解码缓存（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>,
+}
diff --git a/crates/app-iced/src/app/state/boot_probe.rs b/crates/app-iced/src/app/state/boot_probe.rs
new file mode 100644
index 0000000..a5852ed
--- /dev/null
+++ b/crates/app-iced/src/app/state/boot_probe.rs
@@ -0,0 +1,40 @@
+//! 启动期取证：后端选项的换算 + 首帧耗时那一行日志。
+//!
+//! 从 `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 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(),
+    }
+}
+
+/// 首帧耗时日志（只在第一次 `view()` 打一行）。
+pub(crate) fn log_first_frame() {
+    if FIRST_FRAME_LOGGED.swap(true, Ordering::Relaxed) {
+        return;
+    }
+    if let Some(started) = STARTED.get() {
+        eprintln!(
+            "[boot] first frame in {:.0} ms（run() 开始 → 首次 view，含后端探测与字体扫描）",
+            started.elapsed().as_secs_f64() * 1000.0
+        );
+    }
+}
diff --git a/crates/app-iced/src/app/state/construct.rs b/crates/app-iced/src/app/state/construct.rs
new file mode 100644
index 0000000..8d65d91
--- /dev/null
+++ b/crates/app-iced/src/app/state/construct.rs
@@ -0,0 +1,148 @@
+//! `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::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(),
+        };
+        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;
+        let theme_mode = 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());
+        let mut view = pages::Model::new(
+            pages::Screen::Instances,
+            width,
+            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,
+            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(),
+            install_cancelled_seen: 0,
+            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,
+        };
+        // 配色来源档可能已经指向一张背景图：那时 `Ui` 必须由解析出的方案构造，而不是 baseline。
+        app.rebuild_ui();
+        // 两行日志：①档位 + 探测结论 + 生效语言 ②中文策略（D28 缺字体不许静默）。
+        // 下一个人据此分得清「探测错了」还是「探测对了但没用上」。
+        app.lang.log();
+        app.lang.log_cjk();
+        app
+    }
+}
diff --git a/crates/app-iced/src/app/state/refresh.rs b/crates/app-iced/src/app/state/refresh.rs
new file mode 100644
index 0000000..855c3c8
--- /dev/null
+++ b/crates/app-iced/src/app/state/refresh.rs
@@ -0,0 +1,61 @@
+//! 快照 → 视图模型的重建口径（从 `state.rs` 搬出来守 400 行硬线；M119 拆，纯搬不改）。
+//!
+//! 全仓只有 [`App::refresh_view`] 这一个「presenter 快照 → 页面要画的东西」的转换点，
+//! 由 [`App::view_dirty`](super::App) 门控（M90 r2/P2-1 起）：只有真的改了状态的事情才置位，
+//! 30 Hz 空转不重建（重建要把 N 个实例的名字/版本串克隆一遍）。
+
+use unlucky_presenter::toast::ToastKind;
+
+use crate::pages;
+
+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);
+        }
+
+        // 分类是**页面自己持有的过滤条件**（真 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.options.force_state,
+            category,
+            &draft,
+            self.lang(),
+            &self.content,
+        );
+        // 账户页（M114）：与 `view` 同一次门控重建（实现见 `view/account_page.rs`，
+        // 皮肤解码走缓存，所以重复重建不重解图）。
+        self.rebuild_account_page(width);
+        self.view_dirty = false;
+        self.refreshes += 1;
+    }
+}
diff --git a/crates/app-iced/src/app/state/theme.rs b/crates/app-iced/src/app/state/theme.rs
new file mode 100644
index 0000000..6ecb723
--- /dev/null
+++ b/crates/app-iced/src/app/state/theme.rs
@@ -0,0 +1,86 @@
+//! 主题与 `Ui` 的重算口径（从 `state.rs` 搬出来守 400 行硬线；M119 拆，纯搬不改）。
+//!
+//! 三件事在这里：①`Ui` 什么时候重建（[`App::rebuild_ui`]）②主题档怎么定
+//! （[`App::set_flavor`] / [`App::apply_config_theme`]）③读当前求值器（[`App::ui`]）。
+//!
+//! 截图通道的判据 [`App::has_screenshot`] 也放在这儿：上面三条里两条都要「截图不读用户配置」。
+
+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();
+        eprintln!(
+            "[theme] {} -> {} (Theme::name 变化触发缓存重算)",
+            previous,
+            self.ui.name()
+        );
+    }
+
+    /// 按「配色来源是否取色成功」重建 [`Ui`]。
+    ///
+    /// 色卡档（③）刻意继续走 `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();
+        self.ui = match self.appearance.derived_scheme() {
+            Some(scheme) => {
+                eprintln!(
+                    "[appearance] palette={} → Ui::from_scheme（取色方案接管 49 个角色）",
+                    self.appearance.palette_level()
+                );
+                Ui::from_scheme(*scheme, self.families)
+            }
+            None => Ui::new(self.appearance.flavor(), self.families),
+        }
+        .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;
+        match mode {
+            ThemeMode::Light => self.set_flavor(SchemeFlavor::Light),
+            ThemeMode::Dark => self.set_flavor(SchemeFlavor::Dark),
+            ThemeMode::Auto => {}
+        }
+    }
+
+    /// 当前令牌求值器（测试与截图日志用）。
+    pub(in crate::app) fn ui(&self) -> &Ui {
+        &self.ui
+    }
+}
diff --git a/crates/app-iced/src/app/subscription.rs b/crates/app-iced/src/app/subscription.rs
new file mode 100644
index 0000000..15393d6
--- /dev/null
+++ b/crates/app-iced/src/app/subscription.rs
@@ -0,0 +1,94 @@
+//! 订阅：**按需**帧节拍（presenter 的 TICK）+ 窗口尺寸事件。
+//!
+//! ## 为什么要「按需」
+//!
+//! iced_winit 在处理完任何一条消息后都会 `request_redraw()`，而 `window::frames()` 监听的是
+//! `RedrawRequested` —— 于是「订阅帧 → 收 Frame → update → 再触发重绘」是一条**自持循环**：
+//! 只要订阅着，窗口就永远在重绘（M90 r1 就是这样，CPU 空转）。
+//!
+//! 现在只在**真的需要 33 ms 节拍**的时候订阅（[`App::needs_frames`]）：
+//!
+//! | 条件 | 为什么需要 33 ms 节拍 |
+//! |---|---|
+//! | 截图通道 | 第 3 帧要落盘 |
+//! | 有 `Busy` / `Running` 实例 | 启动进度、日志尾随都靠 `backend.tick` 推进 |
+//! | 有未过期的 toast | toast 按毫秒倒计时 |
+//! | 刚派发过指令（3 s 观察窗） | 真 host 的异步事件要靠节拍抽出来 |
+//!
+//! 空闲态**一条帧消息都不来** ⇒ 窗口不重绘、`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::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()
+            || !self.state.toasts.is_empty()
+            || !self.state.running().is_empty()
+            || self
+                .watch_until
+                .is_some_and(|deadline| Instant::now() < deadline)
+    }
+}
diff --git a/crates/app-iced/src/app/tests.rs b/crates/app-iced/src/app/tests.rs
new file mode 100644
index 0000000..ce40508
--- /dev/null
+++ b/crates/app-iced/src/app/tests.rs
@@ -0,0 +1,382 @@
+//! `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 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-m3-light");
+
+    app.set_flavor(SchemeFlavor::Dark);
+
+    assert_eq!(app.ui().name(), "ull-m3-dark", "切主题要换主题名");
+    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-m3-light");
+}
+
+#[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-m3-light", "截图模式的主题只认命令行");
+}
+
+/// 主题优先级：`--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-m3-dark", "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-m3-dark",
+        "配置文件说 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-m3-dark",
+        "--theme 优先级最高，系统主题不许盖"
+    );
+}
diff --git a/crates/app-iced/src/app/tests/appearance.rs b/crates/app-iced/src/app/tests/appearance.rs
new file mode 100644
index 0000000..cde13d8
--- /dev/null
+++ b/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-m3-light");
+    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);
+    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);
+}
+
+/// **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());
+}
diff --git a/crates/app-iced/src/app/tests/presenter.rs b/crates/app-iced/src/app/tests/presenter.rs
new file mode 100644
index 0000000..f6b5abe
--- /dev/null
+++ b/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);
+}
diff --git a/crates/app-iced/src/app/update.rs b/crates/app-iced/src/app/update.rs
new file mode 100644
index 0000000..c81e4b5
--- /dev/null
+++ b/crates/app-iced/src/app/update.rs
@@ -0,0 +1,288 @@
+//! `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）
+//!
+//! | 场景 | 时钟 | 周期 | 谁触发 |
+//! |---|---|---|---|
+//! | 截图 / 有 Busy-Running 实例 / 有 toast / 派发后 3 s 观察窗 | `window::frames()` + 闸门 | 33 ms | [`App::needs_frames`] |
+//! | 其余（空闲） | `Heartbeat` 自续链 | 1 s | [`App::heartbeat`] |
+//!
+//! 两条时钟不会同时干活：心跳在 `needs_frames()` 为真时**只续排、不推进**，忙碌结束自动接回。
+
+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;
+mod agent;
+mod appearance;
+mod boot_env;
+mod clock;
+mod content;
+mod download;
+mod page_messages;
+mod settings;
+
+impl App {
+    /// 一条消息进来，改状态并返回后续任务。
+    pub(super) fn update(&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 => {
+                        eprintln!("[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,
+                };
+                eprintln!("[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::Agent(message) => 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：按下只打日志，不接业务（组件库要能脱离业务验收）
+                eprintln!("[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)];
+
+        // M117：启动日志一行 —— `[auth] msa client_id=configured|missing source=env|build|none`。
+        // 判据（配没配 + 从哪来）在 `core::auth::microsoft::client_id_status()`，零网络；
+        // 本 crate 不直接依赖 core，所以经 `unlucky_cli`（已是本 crate 的依赖）出面，
+        // 免得 UI 侧把判据重算一遍、两份口径漂。日后看日志能一眼分辨
+        // 「没配置」与「配了但登录失败」。
+        eprintln!("{}", 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);
+
+        // 交互模式且没显式指定主题 → 探系统；截图模式永不等（见 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() {
+            eprintln!("[boot] ULL_START_ROUTE → {route:?}");
+            self.state.navigate(route);
+            // 直达某一页时不要再被「自动选中第一条实例」拉回详情页。
+            self.auto_selected = true;
+            // M109：直达内容库时补一次检索（与页面内切换同一个入口）
+            self.ensure_content_loaded();
+        }
+        account::force_account_state(self);
+
+        self.auto_select();
+        self.view_dirty = true;
+        self.refresh_view();
+
+        // 空闲心跳从这里开始自续（它是唯一能在「没有帧事件」时戳醒 app 的时钟）
+        tasks.push(heartbeat());
+
+        Task::batch(tasks)
+    }
+
+    /// 空闲心跳：只有「不需要帧节拍」时才推进一拍，然后**无条件续排**下一拍。
+    ///
+    /// 为什么无条件续排：忙碌结束（游戏退出、toast 过期、观察窗关闭）之后没有别的东西会叫醒
+    /// app，心跳链必须一直在，才能把低频时钟接回去。忙碌期间它只是每秒醒一次、什么都不做。
+    fn on_heartbeat(&mut self) -> Task<Message> {
+        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);
+        }
+        heartbeat()
+    }
+
+    /// 一帧画完：①够 33 ms 就推进一拍 presenter ②截图模式在第 [`CAPTURE_AT_FRAME`] 帧出图。
+    ///
+    /// 时间闸门按**真实流逝时间**判（不是数帧）：掉帧不会把游戏启动进度拖慢，
+    /// 也不会在慢机器上把 1.5 s 的下载阶段拉成 4 s。
+    fn on_frame(&mut self) -> Task<Message> {
+        self.frames += 1;
+
+        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) => {
+                eprintln!("{}", summary.describe());
+                // M97：打**实际**后端名（`wgpu`/`tiny-skia`），不是请求值——`renderer=auto` 曾经出现在每张验收图的日志里。
+                eprintln!(
+                    "[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) => eprintln!("[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;
diff --git a/crates/app-iced/src/app/update/account.rs b/crates/app-iced/src/app/update/account.rs
new file mode 100644
index 0000000..c2a8467
--- /dev/null
+++ b/crates/app-iced/src/app/update/account.rs
@@ -0,0 +1,210 @@
+//! 账户页消息的落点（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::StartBrowser),
+                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;
+                self.dispatch(AppCommand::StartBrowserLogin);
+            }
+            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));
+        }
+        // 第三方站**失败**态：面板打开 + 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);
+        }
+        // 有账号时「Add an account」展开态（P2-4 的收敛后形态）
+        "add" => {
+            app.account_form.section_open = true;
+        }
+        _ => {}
+    }
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/app-iced/src/app/update/account/tests.rs b/crates/app-iced/src/app/update/account/tests.rs
new file mode 100644
index 0000000..d74492b
--- /dev/null
+++ b/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, remaining, ..
+        } => {
+            assert_eq!(code, "ABCD-EFGH", "用户码要上屏");
+            assert!(remaining.is_some_and(|left| left > 0), "倒计时在跑");
+        }
+        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);
+}
diff --git a/crates/app-iced/src/app/update/agent.rs b/crates/app-iced/src/app/update/agent.rs
new file mode 100644
index 0000000..8f32caa
--- /dev/null
+++ b/crates/app-iced/src/app/update/agent.rs
@@ -0,0 +1,381 @@
+//! 助手栏消息的落点（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 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) => {
+                eprintln!("[agent] 提交失败（{}）", failure.code());
+            }
+            SubmitOutcome::Rejected => {
+                eprintln!("[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;
+            eprintln!("[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 {
+            eprintln!("[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 由输入框自己处理，这里只留一行日志。
+            eprintln!(
+                "[agent] Enter on focus={} handled by the composer",
+                self.agent.focus.name()
+            );
+            let _ = catalog;
+        }
+    }
+}
diff --git a/crates/app-iced/src/app/update/agent/tests.rs b/crates/app-iced/src/app/update/agent/tests.rs
new file mode 100644
index 0000000..e1a6da3
--- /dev/null
+++ b/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);
+}
diff --git a/crates/app-iced/src/app/update/appearance.rs b/crates/app-iced/src/app/update/appearance.rs
new file mode 100644
index 0000000..e95f6f1
--- /dev/null
+++ b/crates/app-iced/src/app/update/appearance.rs
@@ -0,0 +1,81 @@
+//! 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::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(),
+            ),
+        };
+        eprintln!(
+            "{}",
+            corner::format_line(context, &plan, policy, &outcome, &style, suppressed_by)
+        );
+    }
+}
diff --git a/crates/app-iced/src/app/update/boot_env.rs b/crates/app-iced/src/app/update/boot_env.rs
new file mode 100644
index 0000000..65690a9
--- /dev/null
+++ b/crates/app-iced/src/app/update/boot_env.rs
@@ -0,0 +1,26 @@
+//! 启动期的取证环境变量解析（`ULL_START_ROUTE`）。
+//!
+//! 从 `app/update.rs` 原样搬出（那个文件在 M105/M106/M109/M113 之后贴着 400 行硬线）：
+//! **纯函数、无状态**，只是取值表长到了七条。
+
+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,
+    }
+}
diff --git a/crates/app-iced/src/app/update/clock.rs b/crates/app-iced/src/app/update/clock.rs
new file mode 100644
index 0000000..b36909e
--- /dev/null
+++ b/crates/app-iced/src/app/update/clock.rs
@@ -0,0 +1,143 @@
+//! 节拍：推进一拍 / 派发指令 / 抽干事件（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 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;
+        }
+        // `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 {
+            eprintln!("[settings] 配置文件变了，重读主题 + 外观");
+            self.apply_config_theme();
+            // M93：外观也热切（面板 α / 背景图 / 配色来源 / 整窗 α 都在里面）。
+            self.reload_appearance();
+        }
+
+        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() {
+            eprintln!(
+                "[tick] n={} frames={} refreshes={} clock={}",
+                self.ticks,
+                self.frames,
+                self.refreshes,
+                if self.needs_frames() {
+                    "frames"
+                } else {
+                    "idle-1hz"
+                }
+            );
+        }
+    }
+
+    /// 派发一条指令并**立刻**抽干它带出来的事件（不本地回显，等价于 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;
+        }
+        for event in events {
+            self.state.apply(event);
+        }
+        self.view_dirty = true;
+        self.auto_select();
+        self.refresh_view();
+    }
+
+    /// 首屏快照到位后**自动选中第一行**（桌面 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;
+    }
+}
diff --git a/crates/app-iced/src/app/update/content.rs b/crates/app-iced/src/app/update/content.rs
new file mode 100644
index 0000000..230f229
--- /dev/null
+++ b/crates/app-iced/src/app/update/content.rs
@@ -0,0 +1,339 @@
+//! 内容库页的消息落点（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 unlucky_presenter::dto::{
+    AppCommand, ContentInstallRequest, ContentQuery, ContentSource, ExportRequestView,
+    ImportRequestView, PackCommand,
+};
+
+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) => {
+                self.content.selected = Some(id);
+                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)));
+                }
+            }
+            // M113: import/export —— 导入/导出区（细节在 `on_pack`）
+            pages::content::Message::Pack(message) => self.on_pack(message),
+        }
+        Task::none()
+    }
+
+    /// 导入/导出区的消息（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 => {
+                if let Some(request) = self.pack_import_request(false) {
+                    self.dispatch(AppCommand::Pack(Box::new(PackCommand::Import(Box::new(
+                        request,
+                    )))));
+                }
+            }
+            PackMessage::Overwrite => {
+                // 「以包为准重新导入」：整次导入翻成 Overwrite 档（core 只有全局档）
+                if let Some(request) = self.pack_import_request(true) {
+                    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,
+                    )))));
+                }
+            }
+        }
+    }
+
+    /// 组一份导入请求（路径草稿 → DTO）。草稿为空 ⇒ `None`（按钮不该发指令）。
+    ///
+    /// `overwrite` 只有「以包为准重新导入」会给 `true`；默认路径永远是 `false`
+    /// （core 那边就是 `ConflictPolicy::KeepUser`，**绝不默认覆盖用户改过的文件**）。
+    fn pack_import_request(&self, overwrite: bool) -> 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()),
+            overwrite,
+        })
+    }
+
+    /// 组一份导出请求（预检与写盘**共用同一份**，确认时原样发回）。
+    ///
+    /// 没有选中实例就没有导出对象 ⇒ `None`。**「Save to」必须真的进请求**
+    /// （复审 r1 P1-1：以前这里硬编码 `target: None`，那个输入框是死的）。
+    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)
+    }
+
+    /// 组一份内容库的「装入」请求；闸门与页面上的按钮**同一个判据**（`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) {
+                eprintln!("[content] 装入被挡下：{reason}");
+            }
+            if model.blockers.contains(&Blocker::NeedsPipeline) {
+                eprintln!("[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,
+        })
+    }
+}
diff --git a/crates/app-iced/src/app/update/download.rs b/crates/app-iced/src/app/update/download.rs
new file mode 100644
index 0000000..cff3c40
--- /dev/null
+++ b/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 ⇒ 回填空值，而不是留一个点不亮的幽灵选中"
+        );
+    }
+}
diff --git a/crates/app-iced/src/app/update/download_wiring.rs b/crates/app-iced/src/app/update/download_wiring.rs
new file mode 100644
index 0000000..cc6ade4
--- /dev/null
+++ b/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();
+}
diff --git a/crates/app-iced/src/app/update/page_messages.rs b/crates/app-iced/src/app/update/page_messages.rs
new file mode 100644
index 0000000..2247c88
--- /dev/null
+++ b/crates/app-iced/src/app/update/page_messages.rs
@@ -0,0 +1,232 @@
+//! 页面消息的落点（`on_page`）：解 M94 冲突时从 `update.rs` 拆出来。
+//!
+//! 为什么拆：`main` 上 `update.rs` 已经 **397 行**（M94 自己也是因此把下载页四支拆到
+//! `update/download.rs`），日志页再往里塞「剪贴板 + 清日志」两支就顶破 400 硬线。
+//! 与 M94 同一种做法：`app/update/**` 属本 mission scope。
+//!
+//! ## 穷尽性（M94 复审的 p3，本轮收掉）
+//!
+//! 这里是全 crate **唯一**对 [`pages::Message`] 的穷尽匹配点，所以**没有** `_ => {}` 兜底：
+//! 谁往枚举里加变体却忘了接线，编译器立刻报 E0004。原来是 `_ => {}` + 注释「做穷尽性」——
+//! 方向正好写反了，它**取消**穷尽性，把「漏接线」变成「点了没反应」。
+//!
+//! 代价：由前置分支（`on_download` / 本文件里的剪贴板分支）先消费的变体，在 match 里**仍要
+//! 显式列出**。那是保住穷尽性的必要代价，也是这条守卫抓得住东西的原因。
+//!
+//! ## 边界（抓得住什么 / 抓不住什么）
+//!
+//! - 抓得住：**加一个 `pages::Message` 变体却没接线** → 编译失败（E0004），不会静默；
+//! - 抓不住：加一个 `pages::Action` 变体 —— 它落进 `Action(action)` 的占位分支（打印一行
+//!   `[page] 占位动作 …`），编译期不会报。这是占位期的既有设计，不是本文件能守的。
+
+use unlucky_i18n::{Lang, LangChoice};
+
+use crate::pages;
+use crate::ui::lang::LangState;
+
+use super::*;
+
+// --------------------------------------------------------------- 界面语言（M106）
+//
+// 这三个方法住在本文件而不是 `app/state.rs`：`state.rs` 贴着 400 行硬线（M104 的 `agent`、
+// M105 的 `download_draft` 都往那儿长），而 `set_language` 的唯一调用点就是本文件的
+// `pages::Message::Language` 分支——落点与调用点放一起，读的人不用来回跳。
+// 与 M93 把 appearance 那批 `App` 方法放进 `app/appearance.rs` 是同一手法。
+
+impl App {
+    /// 页面消息：导航走路由栈，真业务命令派发，纯视图态改本地呈现。
+    pub(super) fn on_page(&mut self, message: pages::Message) -> Task<Message> {
+        // 下载页的四支（含「刷新下载源」）在 `update/download.rs`：`update.rs` 早已贴 400 行
+        if self.on_download(&message) {
+            return Task::none();
+        }
+
+        match message {
+            pages::Message::Navigate(route) => {
+                // M109：进内容库时补一次检索（首个动作不该是「再点一下搜索」）。
+                // 判据在 `ensure_content_loaded` 里（已有结果/请求在飞就不重复打网络）。
+                let entering_content = route == Route::Content;
+                self.state.navigate(route);
+                self.view_dirty = true;
+                self.refresh_view();
+                if entering_content {
+                    self.ensure_content_loaded();
+                }
+            }
+            pages::Message::Launch(id) => self.dispatch(AppCommand::LaunchInstance(id)),
+            pages::Message::Stop(id) => self.dispatch(AppCommand::StopInstance(id)),
+            pages::Message::Appearance(change) => self.on_appearance(change),
+            // M101：设置页的四条填页线共用一个投递口；组内变体在 `update/settings.rs` 里穷尽分发
+            // （那一层没有 `_ =>`，见本文件末尾与 `update/settings/tests.rs` 的两条守门）
+            pages::Message::Settings(group) => return self.on_settings(group),
+            // M106：换界面语言（落盘 + 重建视图模型；档位不是业务命令，不派 `AppCommand`）。
+            // 这是**唯一**一处绕开 M101 投递口的页面消息：语言档位不是「某一组的状态」，
+            // 它要落盘到 `ui.language` 并重建整棵视图模型（设置页的语言行只是它的第一个出口）。
+            pages::Message::Language(choice) => self.set_language(choice),
+            // M109：内容库那一套意图在自己的文件里穷尽分发（`update/content.rs`）
+            pages::Message::Content(message) => return self.on_content(message),
+            // M95：摘要落剪贴板（文本由页面造，这里只搬）
+            pages::Message::CopySummary(text) => return iced::clipboard::write(text),
+            // 下面四支已由 `on_download` 提前消化；显式列出而不是 `_ => {}`，见模块文档
+            pages::Message::SelectVersion(_)
+            | pages::Message::InstallVersion(_)
+            | pages::Message::CancelInstall
+            // M105 的三支 + M107 的四支 + 分类：全部由 `on_download` 提前消化（显式列出保住穷尽性）
+            | pages::Message::SetLoader(_)
+            | pages::Message::SetLoaderVersion(_)
+            | pages::Message::SetInstanceName(_)
+            | pages::Message::SetCategory(_)
+            // M107 的四支同属下载页（查询 / 清空 / 主版本桶 / 折叠类型栏）
+            | pages::Message::SetVersionQuery(_)
+            | pages::Message::ClearVersionQuery
+            | pages::Message::SelectMajor(_)
+            | pages::Message::ToggleTypeRail => debug_assert!(false, "应由 on_download 消费"),
+            // M95：清空日志是**呈现层**操作（`log_lines` 是 presenter 的公开快照字段，
+            // 不派业务命令、不写持久状态）
+            pages::Message::Action(pages::Action::ClearLogs) => {
+                self.state.log_lines.clear();
+                self.view_dirty = true;
+                self.refresh_view();
+            }
+            // M114：账户页（三轨登录 / 列表动作 / 表单输入）
+            pages::Message::Account(message) => return self.on_account(message),
+            // 还没接后端的占位动作：只打日志（哪几个、为什么，见 pages 模块文档的偏离登记）
+            pages::Message::Action(action) => {
+                eprintln!("[page] 占位动作 {action:?} pressed（没有对应 AppCommand）");
+            }
+        }
+
+        Task::none()
+    }
+}
+
+impl App {
+    /// 当前生效的界面语言（= 目录选择；页面文案一律由它派生）。
+    pub(in crate::app) fn lang(&self) -> Lang {
+        self.lang.lang()
+    }
+
+    /// 设置页语言行要的两件：档位（画选中态）+ 生效语言（画回显）。
+    pub(in crate::app) fn language(&self) -> pages::Language {
+        self.lang.for_settings()
+    }
+
+    /// 换界面语言（设置页语言行 → `pages::Message::Language`）。
+    ///
+    /// 三件事缺一不可：①档位与结论换掉 ②视图模型重建（`view_dirty` + `refresh_view`，目录是
+    /// 视图模型的一部分）③落盘（重启后保持所选语言）。字体不在这里重扫：中文档缺字体时的
+    /// 判据/信号归 `i18n::font::decide` + `fonts/cjk.rs`（见报告「没验的部分」）。
+    pub(in crate::app) fn set_language(&mut self, choice: LangChoice) {
+        if choice == self.lang.choice() {
+            return;
+        }
+        self.lang = LangState::of(choice);
+        self.lang.log();
+        if !self.bridge.persist_ui_language(choice.setting_value()) {
+            eprintln!(
+                "[i18n] 语言偏好没落盘（配置只读或数据根解析不出来）：本次生效，重启会回到旧值"
+            );
+        }
+        self.lang.log_cjk();
+        self.view_dirty = true;
+        self.refresh_view();
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use unlucky_design::color::SchemeFlavor;
+    use unlucky_i18n::LangChoice;
+    use unlucky_presenter::mock::MockBackend;
+    use unlucky_presenter::settings_bridge::SettingsBridge;
+
+    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",
+    };
+
+    /// 不碰磁盘的 App（mock 后端 + 内存设置桥），与 `app/tests.rs` 的 `headless` 同型。
+    fn headless() -> App {
+        App::with_presenter(
+            Options::default(),
+            FAMILIES,
+            SchemeFlavor::Light,
+            Box::new(MockBackend::new()),
+            SettingsBridge::memory_only(),
+        )
+    }
+
+    /// M106：设置页语言行点一下 → 生效语言与视图模型都跟着换。
+    ///
+    /// 抓得住：①`pages::Message::Language` 没接进 `on_page`（点了没反应，编译器不会报——它接得住，
+    /// 但接错了分支就静默）；②`set_language` 只改字段不重建视图（界面要等下一次刷新才变）；
+    /// ③档位与生效语言各说各话（设置页会画错选中态）。
+    /// 抓不住：界面真的画成中文了没有（那要截图，见 `DevDocs/artifacts/m106/`）。
+    #[test]
+    fn the_language_message_switches_the_catalog_and_rebuilds_the_view() {
+        let mut app = headless();
+        assert_eq!(
+            app.view.lang,
+            app.lang(),
+            "首帧的视图模型要已经按生效语言建好"
+        );
+
+        let _ = app.update(crate::app::message::Message::Page(
+            pages::Message::Language(LangChoice::Fixed(unlucky_i18n::Lang::ZhCn)),
+        ));
+        assert_eq!(app.lang(), unlucky_i18n::Lang::ZhCn);
+        assert_eq!(app.view.lang, unlucky_i18n::Lang::ZhCn, "目录要跟着换");
+        assert_eq!(
+            app.language(),
+            pages::Language {
+                choice: LangChoice::Fixed(unlucky_i18n::Lang::ZhCn),
+                effective: unlucky_i18n::Lang::ZhCn,
+            }
+        );
+
+        let refreshes = app.refreshes;
+        let _ = app.update(crate::app::message::Message::Page(
+            pages::Message::Language(LangChoice::Fixed(unlucky_i18n::Lang::En)),
+        ));
+        assert_eq!(app.view.lang, unlucky_i18n::Lang::En);
+        assert_eq!(app.refreshes, refreshes + 1, "换语言要重建一次视图模型");
+
+        // 同一档再点一次：什么都不该发生（不白重建）
+        let refreshes = app.refreshes;
+        let _ = app.update(crate::app::message::Message::Page(
+            pages::Message::Language(LangChoice::Fixed(unlucky_i18n::Lang::En)),
+        ));
+        assert_eq!(app.refreshes, refreshes, "同一档不该再重建");
+    }
+
+    /// 抓得住：有人给 `on_page` 的 match 重新加 `_ => {}` 兜底 —— 那正是 M94 复审的 p3：
+    /// 兜底让「加了变体忘了接线」从**编译错误**退化成「点了没反应」，这条测试把它拽回来。
+    /// 抓不住：别的兜底写法（把 match 拆成 if-else 链、给子枚举加通配之后再漏变体），
+    /// 也抓不住「加了变体但接错分支」——那两条只有编译器和人读得出来。
+    #[test]
+    fn the_page_match_has_no_wildcard_fallback() {
+        let source = include_str!("page_messages.rs");
+        let wildcards: Vec<(usize, &str)> = source
+            .lines()
+            .enumerate()
+            .filter(|(_, line)| {
+                let trimmed = line.trim();
+                trimmed.starts_with("_ =>") || trimmed.starts_with("_=>")
+            })
+            .map(|(index, line)| (index + 1, line))
+            .collect();
+
+        assert!(
+            wildcards.is_empty(),
+            "on_page 里出现了 `_ =>` 兜底（行 {:?}）：它会取消对 pages::Message 的穷尽性，\
+             新变体漏接线时编译器不再报 E0004",
+            wildcards
+        );
+    }
+}
diff --git a/crates/app-iced/src/app/update/settings.rs b/crates/app-iced/src/app/update/settings.rs
new file mode 100644
index 0000000..5cd00f8
--- /dev/null
+++ b/crates/app-iced/src/app/update/settings.rs
@@ -0,0 +1,55 @@
+//! 设置页分组消息的**二级分发**（M101 `SETTINGSMSG`）：
+//! `pages::Message::Settings(GroupMessage)` → 四条填页线各自的 handler。
+//!
+//! ## 为什么分两级
+//!
+//! `app/update/page_messages.rs` 对 [`pages::Message`] 做穷尽匹配（没有 `_ =>`，有
+//! `the_page_match_has_no_wildcard_fallback` 守门）。设置页的四条填页线若各自往 `pages::Message`
+//! 里加变体，就都得改那个文件——四路并行必然冲突。M101 把它们收进一个投递口
+//! `pages::Message::Settings(GroupMessage)`，本文件再把 `GroupMessage` 分给四条线：
+//!
+//! ```text
+//! GroupMessage::Java(m)               → settings/java.rs
+//! GroupMessage::Download(m)           → settings/download.rs
+//! GroupMessage::LanguageAppearance(m) → settings/language_appearance.rs
+//! GroupMessage::AiAbout(m)            → settings/ai_about.rs
+//! ```
+//!
+//! ## 穷尽性：抓得住什么 / 抓不住什么
+//!
+//! - **抓得住**：某条线给 `GroupMessage` 加了载荷变体（= 在自己文件里加了一支消息）却忘了在本
+//!   match 里接线 → **E0004**；四个 handler 里对空枚举的 `match message {}` 一旦有人写成
+//!   `_ => {}`，`the_group_dispatch_has_no_wildcard_fallback` 会红（兜底会把「漏接线」从编译
+//!   错误降级成「点了没反应」，`page_messages.rs` 的同类守卫是这么写的，这里照抄）。
+//! - **抓不住**：handler 忽略自己的消息（`let _ = message; Task::none()`）、两个 handler 身体写反
+//!   或写成一样——类型对得上就编得过，只有人读能看出来。也因此「接错了组」的一半是编译期兜住的
+//!   （载荷类型不同 ⇒ 编不过），另一半（接了个空壳）不是。
+//!
+//! ## 加一支设置页消息要改哪
+//!
+//! 自己那条线的两个文件：消息口（`pages/settings/<线>.rs`）+ 落点（本目录 `<线>.rs`）。
+//! 本文件的 match 只在 `GroupMessage` **加变体**时才动，而那意味着新增一条线，不是加一支消息。
+
+use super::*;
+
+impl App {
+    /// 设置页的分组消息：分给四条线各自的文件，本文件不认识任何一支具体消息。
+    pub(super) fn on_settings(&mut self, message: pages::settings::GroupMessage) -> Task<Message> {
+        match message {
+            pages::settings::GroupMessage::Java(message) => self.on_settings_java(message),
+            pages::settings::GroupMessage::Download(message) => self.on_settings_download(message),
+            pages::settings::GroupMessage::LanguageAppearance(message) => {
+                self.on_settings_language_appearance(message)
+            }
+            pages::settings::GroupMessage::AiAbout(message) => self.on_settings_ai_about(message),
+        }
+    }
+}
+
+mod ai_about;
+mod download;
+mod java;
+mod language_appearance;
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/app-iced/src/app/update/settings/ai_about.rs b/crates/app-iced/src/app/update/settings/ai_about.rs
new file mode 100644
index 0000000..4ac6bb3
--- /dev/null
+++ b/crates/app-iced/src/app/update/settings/ai_about.rs
@@ -0,0 +1,17 @@
+//! AI / About 分组消息的落点（M101 `SETTINGSMSG`）：**只归 ai+about 线**。
+//!
+//! 消息口在 `pages/settings/ai_about.rs`（`pages::settings::ai_about::Message`）。
+//!
+//! 首版是空枚举上的 `match message {}`：这是**穷尽**的写法（不是兜底），加了变体不接线就报 E0004。
+
+use super::super::*;
+
+impl App {
+    /// AI / About 分组的一条消息。首版没有可处理的东西（空枚举）。
+    pub(super) fn on_settings_ai_about(
+        &mut self,
+        message: pages::settings::ai_about::Message,
+    ) -> Task<Message> {
+        match message {}
+    }
+}
diff --git a/crates/app-iced/src/app/update/settings/download.rs b/crates/app-iced/src/app/update/settings/download.rs
new file mode 100644
index 0000000..2bb52fb
--- /dev/null
+++ b/crates/app-iced/src/app/update/settings/download.rs
@@ -0,0 +1,18 @@
+//! Downloads 分组消息的落点（M101 `SETTINGSMSG`）：**只归 download 线**。
+//!
+//! 消息口在 `pages/settings/download.rs`（`pages::settings::download::Message`）。与下载页
+//! （`pages/download*` 与 `app/update/download.rs`）无关：那是「装哪个版本」，这一组是「怎么下」。
+//!
+//! 首版是空枚举上的 `match message {}`：这是**穷尽**的写法（不是兜底），加了变体不接线就报 E0004。
+
+use super::super::*;
+
+impl App {
+    /// Downloads 分组的一条消息。首版没有可处理的东西（空枚举）。
+    pub(super) fn on_settings_download(
+        &mut self,
+        message: pages::settings::download::Message,
+    ) -> Task<Message> {
+        match message {}
+    }
+}
diff --git a/crates/app-iced/src/app/update/settings/java.rs b/crates/app-iced/src/app/update/settings/java.rs
new file mode 100644
index 0000000..a8f3fe7
--- /dev/null
+++ b/crates/app-iced/src/app/update/settings/java.rs
@@ -0,0 +1,33 @@
+//! Java 分组消息的落点（M101 `SETTINGSMSG`）：**只归 java 线**。
+//!
+//! 消息口在 `pages/settings/java.rs`（`pages::settings::java::Message`）。加一支消息 = 改那两个
+//! 文件，`pages/mod.rs` / `page_messages.rs` / `app/update/settings.rs` 都不用动。
+//!
+//! 消息进来的通道有两条，都不经过共享文件：
+//! 1. **页面点击**：`pages::Message::Settings(GroupMessage::Java(..))` → `on_page` → `on_settings`；
+//! 2. **异步结果**：本文件自己构造 `Message::Page(pages::Message::Settings(GroupMessage::Java(..)))`
+//!    （`app::Message::Page` 是既有通道，不用加新变体）。
+//!
+//! 穷尽性：这里对 `java::Message` 做**穷尽**匹配（没有 `_ =>`、没有 `other =>`）。加了变体不接线
+//! 立刻 E0004；写成兜底会把编译错误降级成「点了没反应」，`app/update/settings/tests.rs` 的
+//! `the_group_dispatch_has_no_catch_all_arm` 会红。
+
+use super::super::*;
+
+impl App {
+    /// Java 分组的一条消息。
+    pub(super) fn on_settings_java(
+        &mut self,
+        message: pages::settings::java::Message,
+    ) -> Task<Message> {
+        match message {
+            // M101 r2 的**活的端到端证据**：只有测试构造这一支（java 线接第一个真控件时换成真变体）。
+            // 它真的改一个 app 状态，所以「消息从外壳走到 handler」这件事有运行时证据，不只是编译期。
+            #[cfg(test)]
+            pages::settings::java::Message::Ping => {
+                self.view_dirty = true;
+                Task::none()
+            }
+        }
+    }
+}
diff --git a/crates/app-iced/src/app/update/settings/language_appearance.rs b/crates/app-iced/src/app/update/settings/language_appearance.rs
new file mode 100644
index 0000000..b2c18eb
--- /dev/null
+++ b/crates/app-iced/src/app/update/settings/language_appearance.rs
@@ -0,0 +1,19 @@
+//! 语言 + 外观两组消息的落点（M101 `SETTINGSMSG`）：**只归 language+appearance 线**。
+//!
+//! 消息口在 `pages/settings/language_appearance.rs`（`pages::settings::language_appearance::Message`）。
+//! 为什么两组共用一个消息口：它俩本就是同一条线的两个分组（General 的语言 / 主题 / 启动页，
+//! Appearance 的密度 / 圆角 / 动效 / 文字缩放），`GroupMessage` 只给这条线留一个变体。
+//!
+//! 首版是空枚举上的 `match message {}`：这是**穷尽**的写法（不是兜底），加了变体不接线就报 E0004。
+
+use super::super::*;
+
+impl App {
+    /// 语言 / 外观线的一条消息。首版没有可处理的东西（空枚举）。
+    pub(super) fn on_settings_language_appearance(
+        &mut self,
+        message: pages::settings::language_appearance::Message,
+    ) -> Task<Message> {
+        match message {}
+    }
+}
diff --git a/crates/app-iced/src/app/update/settings/tests.rs b/crates/app-iced/src/app/update/settings/tests.rs
new file mode 100644
index 0000000..150f2ba
--- /dev/null
+++ b/crates/app-iced/src/app/update/settings/tests.rs
@@ -0,0 +1,267 @@
+//! 设置页分组消息分发的**守门测试**（M101 `SETTINGSMSG`）。
+//!
+//! 判据与 `app/update/page_messages.rs` 里那条 `the_page_match_has_no_wildcard_fallback` 同源：
+//! 兜底会把「加了变体忘了接线」从**编译错误**降级成「点了没反应」。两级 dispatch 各守一条：
+//! 那一层守 `pages::Message`，本文件守 `GroupMessage` 与四个 handler。
+//!
+//! ## 判据（r2 复审 P2-3 之后收窄过一次）
+//!
+//! 上一版的判据是「除已知前缀外，任何含 `=>` 的行都算兜底」——**过宽**：往 handler 里加一个
+//! **没有兜底臂**的嵌套 match（`match true { true => …, false => … }`），或者 rustfmt 把长
+//! or-pattern 折行成 `| X =>`，都会让它假红。四条填页线一写真实逻辑就撞，守门反而推高成本。
+//!
+//! 现在的判据是**结构化的**：只找 `match message {` 这一层（用大括号深度计数把嵌套 match 排除
+//! 在外），**只看深度 1 的臂**——
+//!
+//! - `app/update/settings.rs` 的 `on_settings`：恰好 **4 条**臂，每条以 `pages::settings::GroupMessage::`
+//!   （或短写 `GroupMessage::`）开头；
+//! - 四个 handler：每条臂以该组自己的 `pages::settings::<线>::Message::`（或短写 `Message::`）开头，
+//!   还没有臂的（空枚举 `match message {}`）一条臂都没有；
+//! - 以 `|` 开头的折行 or-pattern 续行放行（它不可能是兜底）。
+//!
+//! ## 抓得住什么 / 抓不住什么
+//!
+//! 抓得住：
+//! 1. `on_settings` 里加 `_ =>` 或 binding 臂 `other =>`（`GroupMessage` 不再穷尽）；
+//! 2. handler 把 `match message {}` 改成 `_ => Task::none()` / `other => { … }`；
+//! 3. `on_settings` 的臂数不是 4（删了一条、或把两条合并）；
+//! 4. handler 的臂写成别的组的变体路径（前缀不对）。
+//!
+//! 抓不住（老实列出来）：
+//! 1. **嵌套 match 里的兜底**——深度 ≥2 的臂不看。这是刻意的：嵌套 match 的穷尽性由它自己的类型
+//!    保证，跟 `GroupMessage` 漏接线无关；代价是没人守「嵌套 match 自己写了个 `_ =>`」；
+//! 2. **跨行 pattern 分两种，别当一种**：以 `|` 开头的 or-pattern 续行**放行**（不误红）；
+//!    但**花括号形状**的多行 pattern（例如 `Message::SetRuntime {` 折成多行、`=>` 落在后面）
+//!    会被**静默跳过**——那一行不带 `=>`，于是既不算臂也不算违规（臂数 0、零违规），是**漏检**
+//!    而不是误红。两种都是洞，当前代码风格都不出现；真要用这种写法时把规则补上，别把守门删掉；
+//! 3. **字符串/字符字面量里的 `{` `}`** 会扰乱深度计数（本文件与四个 handler 都没有这种写法）；
+//! 4. handler 忽略消息（`let _ = message; Task::none()`）、两个 handler 身体写反或写成一样
+//!    ——类型对得上就编得过，只有人读能看出来；
+//! 5. `match message` 被改名或换变量名时找不到匹配，臂数为 0 —— 这时
+//!    `the_group_dispatch_has_exactly_four_arms` 会红（不是静默通过）。
+//!
+//! 站位：本文件是 `app::update::settings::tests`，`include_str!` 的路径相对本文件所在目录。
+
+use unlucky_design::color::SchemeFlavor;
+use unlucky_presenter::mock::MockBackend;
+use unlucky_presenter::settings_bridge::SettingsBridge;
+
+use crate::app::message::Message;
+use crate::app::state::App;
+use crate::cli::Options;
+use crate::pages;
+use crate::theme::Families;
+
+/// `on_settings` 的臂允许的前缀。
+const GROUP_ARMS: &[&str] = &["pages::settings::GroupMessage::", "GroupMessage::"];
+
+/// 一行的净大括号增量（`{` 加、`}` 减）。
+fn brace_delta(line: &str) -> i32 {
+    let open = line.matches('{').count() as i32;
+    let close = line.matches('}').count() as i32;
+    open - close
+}
+
+/// 扫一条 `match message { … }`，只看**本层**（深度 1）的臂。
+///
+/// 返回 `(本层的合法臂数, 违规行)`：违规 = 本层里含 `=>`、又不是「已知前缀开头」的行
+/// （`|` 开头的折行 or-pattern 续行放行）。嵌套 match 的臂在深度 ≥2，整段跳过。
+fn dispatch_arms(path: &str, source: &str, allowed: &[&str]) -> (usize, Vec<String>) {
+    let mut arms = 0usize;
+    let mut offending = Vec::new();
+    let mut depth = 0i32;
+    let mut inside = false;
+
+    for (index, line) in source.lines().enumerate() {
+        let trimmed = line.trim();
+        if trimmed.starts_with("//") {
+            continue;
+        }
+
+        if !inside {
+            if trimmed.contains("match message {") {
+                inside = true;
+                depth = 1;
+            }
+            continue;
+        }
+
+        if depth == 1 && trimmed.contains("=>") {
+            let pattern = trimmed.trim_start_matches('|').trim_start();
+            if allowed.iter().any(|prefix| pattern.starts_with(prefix)) {
+                arms += 1;
+            } else if !trimmed.starts_with('|') {
+                offending.push(format!("{path}:{}: {trimmed}", index + 1));
+            }
+        }
+
+        depth += brace_delta(trimmed);
+        if depth <= 0 {
+            break;
+        }
+    }
+
+    (arms, offending)
+}
+
+/// 不碰磁盘的 App（mock 后端 + 内存设置桥），与 `app/tests.rs` 的 `headless` 同一副骨架。
+fn headless() -> App {
+    const FAMILIES: Families = Families {
+        text: "Segoe UI",
+        display: "Segoe UI",
+        mono: "Consolas",
+    };
+
+    App::with_presenter(
+        Options::default(),
+        FAMILIES,
+        SchemeFlavor::Light,
+        Box::new(MockBackend::new()),
+        SettingsBridge::memory_only(),
+    )
+}
+
+// --------------------------------------------------------------- 守门本体
+
+/// `on_settings` 与四个 handler 的**本层**臂里不许出现任何形式的兜底（`_ =>` 或 `other =>`）。
+#[test]
+fn the_group_dispatch_has_no_catch_all_arm() {
+    let sources: [(&str, &str, &[&str]); 5] = [
+        (
+            "app/update/settings.rs",
+            include_str!("../settings.rs"),
+            GROUP_ARMS,
+        ),
+        (
+            "app/update/settings/java.rs",
+            include_str!("java.rs"),
+            &["pages::settings::java::Message::", "Message::"],
+        ),
+        (
+            "app/update/settings/download.rs",
+            include_str!("download.rs"),
+            &["pages::settings::download::Message::", "Message::"],
+        ),
+        (
+            "app/update/settings/language_appearance.rs",
+            include_str!("language_appearance.rs"),
+            &[
+                "pages::settings::language_appearance::Message::",
+                "Message::",
+            ],
+        ),
+        (
+            "app/update/settings/ai_about.rs",
+            include_str!("ai_about.rs"),
+            &["pages::settings::ai_about::Message::", "Message::"],
+        ),
+    ];
+
+    let mut offending = Vec::new();
+    for (path, source, allowed) in sources {
+        let (_, bad) = dispatch_arms(path, source, allowed);
+        offending.extend(bad);
+    }
+
+    assert!(
+        offending.is_empty(),
+        "设置页分组消息的 dispatch 本层出现了兜底臂（{offending:?}）：\
+         任何 catch-all / binding 臂都会取消 `GroupMessage` 的穷尽性，\
+         新变体漏接线时编译器不再报 E0004"
+    );
+}
+
+/// `on_settings` 必须**恰好四条**臂，一条一条显式写全（不是「至少」）。
+///
+/// 抓得住：删掉一条臂、把两条合并、或者把 `match message` 改名（改名后扫不到臂 ⇒ 0 ≠ 4）。
+/// 抓不住：臂的顺序（顺序不影响语义）、每条臂接到了哪个 handler（类型对得上就编得过）。
+#[test]
+fn the_group_dispatch_has_exactly_four_arms() {
+    let (arms, _) = dispatch_arms(
+        "app/update/settings.rs",
+        include_str!("../settings.rs"),
+        GROUP_ARMS,
+    );
+
+    assert_eq!(
+        arms, 4,
+        "`on_settings` 应该恰好四条臂（java / download / language_appearance / ai_about），实际 {arms} 条"
+    );
+}
+
+/// **守门自身不误伤**：嵌套 match 与折行的 or-pattern 都不算兜底（r2 复审 P2-3 的探针）。
+///
+/// 这条是上一版判据假红的回归测试：复审往 handler 里加 `match true { true => …, false => … }`
+/// 就让它 FAILED；现在这类写法必须放行。
+#[test]
+fn the_guard_ignores_nested_matches_and_folded_or_patterns() {
+    let synthetic = "\
+impl App {
+    fn on_settings_java(&mut self, message: pages::settings::java::Message) -> Task<Message> {
+        match message {
+            pages::settings::java::Message::Probe => {
+                let nested = match true { true => 10u8, false => 11u8 };
+                let _ = nested;
+                Task::none()
+            }
+            | pages::settings::java::Message::Retry => Task::none(),
+        }
+    }
+}
+";
+
+    let (arms, offending) = dispatch_arms(
+        "synthetic",
+        synthetic,
+        &["pages::settings::java::Message::"],
+    );
+    assert!(
+        offending.is_empty(),
+        "正常代码被误判成兜底（这正是 r2 复审 P2-3 的假红）：{offending:?}"
+    );
+    assert_eq!(arms, 2, "嵌套 match 里的两条臂不算本层臂");
+}
+
+/// **守门仍然有牙**：`_ =>` 与 binding 臂 `other =>` 都要被本层判成兜底。
+#[test]
+fn the_guard_still_catches_both_catch_all_shapes() {
+    for arm in [
+        "_ => Task::none(),",
+        "other => { let _ = other; Task::none() }",
+    ] {
+        let synthetic = format!(
+            "impl App {{\n    fn on_settings_java(&mut self, message: M) -> Task<Message> {{\n        match message {{\n            {arm}\n        }}\n    }}\n}}\n"
+        );
+        let (_, offending) = dispatch_arms("synthetic", &synthetic, GROUP_ARMS);
+        assert_eq!(
+            offending.len(),
+            1,
+            "`{arm}` 是兜底，必须被判红（实际 {offending:?}）"
+        );
+    }
+}
+
+// --------------------------------------------------------------- 活的端到端证据
+
+/// **活的端到端证据**：一条组消息真的从外壳那条既有通道走到该组的 handler（r1 复审要求）。
+///
+/// 路径：`app::Message::Page` → `on_page` → `pages::Message::Settings` → `on_settings` →
+/// `on_settings_java`，最后改到 `App` 的状态。r1 之前这条链只有编译期证据（`GroupMessage` 是
+/// uninhabited，运行时是死代码）；现在至少有一支真的跑得起来。
+///
+/// 抓得住：漏斗某一环接断了（`on_page` 没转交、`on_settings` 转错组、handler 忽略消息）——那时
+/// `view_dirty` 不会翻。抓不住：真实用户点击（本条没有 UI 控件，构造点只有测试）。
+#[test]
+fn a_group_message_reaches_its_handler_through_the_funnel() {
+    let mut app = headless();
+    app.view_dirty = false;
+
+    let _ = app.update(Message::Page(pages::Message::Settings(
+        pages::settings::GroupMessage::Java(pages::settings::java::Message::Ping),
+    )));
+
+    assert!(
+        app.view_dirty,
+        "java 线的消息没有走到 `on_settings_java`：消息漏斗在某一环断了"
+    );
+}
diff --git a/crates/app-iced/src/app/view.rs b/crates/app-iced/src/app/view.rs
new file mode 100644
index 0000000..4576bd6
--- /dev/null
+++ b/crates/app-iced/src/app/view.rs
@@ -0,0 +1,195 @@
+//! `view`：presenter 快照 → 页面视图模型 → 控件树。
+//!
+//! 展示转换（快照字段 → 显示文本/网格）**全部在这里**，页面层只认 [`pages::Model`]。
+//!
+//! 实例页那一段（`1.20.4 · Fabric`、运行状态、元信息卡）M120 搬进 [`instances`]：本文件
+//! 当时贴着 400 行硬线，而 i18n 还要在这个函数里接一批阶段标签。
+
+use iced::{Element, Theme};
+
+use unlucky_i18n::Lang;
+use unlucky_presenter::router::Route;
+use unlucky_presenter::state::AppState;
+
+use crate::app::components::interaction::Interaction;
+use crate::cli::Screen;
+use crate::pages::{self, Row};
+use crate::shell::{self, agent, NavItem};
+
+use super::message::{nav_item_of, Message};
+use super::state::{log_first_frame, App};
+use super::APP_TITLE;
+
+mod account_page;
+mod instances;
+mod logs;
+mod rail;
+
+use instances::{detail_of, runtime_status, supporting_line};
+use logs::logs_model;
+
+impl App {
+    /// 主题名（iced 只在 `Theme::name()` 变化时重算受主题影响的缓存）。
+    pub(super) fn theme(&self) -> Theme {
+        self.ui().theme()
+    }
+
+    /// 窗口标题（自绘标题栏另画一份，这里是给系统/截图工具看的）。
+    pub(super) fn title(&self) -> String {
+        APP_TITLE.to_owned()
+    }
+
+    /// 整棵树。
+    pub(super) fn view(&self) -> Element<'_, Message> {
+        log_first_frame();
+
+        // `--screen=gallery`：组件库 harness（D39 §5）。它用自己的 DemoMessage，
+        // 这里只做一次 map，组件库与业务 Message 依然解耦。
+        if self.options.screen == Screen::Gallery {
+            return super::components::gallery::view(&self.ui).map(Message::Demo);
+        }
+
+        // 产品页走**内容槽位**：外壳（标题栏 / 拖动与缩放热区 / 三个 caption 键 / rail）由
+        // `shell` 画，中间那块才是页面（`DragWindow`/`ResizeStart`/`Minimize`/`ToggleMaximize`/`Close`
+        // 五种消息的构造点只在外壳里，页面树自己画的标题栏拖不动窗口）。
+        //
+        // M93：三样东西从外观状态进来——①背景层（垫在最底下）②面板 α（外壳层的底色）③设置页要读
+        // 的那份状态。M101 r2 起 ③ 走 `page_with_settings`：外观状态 + 各组自己的状态一起递进去。
+        let background =
+            pages::appearance::layer(&self.ui, &self.appearance, (self.width, self.height))
+                .map(|element| element.map(Message::Page));
+        // 右栗（M104）：拆出档返回 `None`（会话已在独立页里）；拖拽期间另有铺满窗口的取指针层。
+        let overlay = agent::drag_overlay(&self.agent).map(|element| element.map(Message::Agent));
+        // M119：会话内容 / 未读 / busy / 待确认全部来自 presenter 的 rail，失败横幅是 app 层
+        // 备好的**展示输入**（标题 catalog 键 + 已脱敏正文）。壳在这里不做任何脱敏。
+        // 界面语言的真值源是 `App::lang`（M106）：右栏的静态文案也走它，不再有 `const LANG`
+        let agent_catalog = self.lang().catalog();
+        // 会话入参：rail 借 presenter、失败横幅由 app 层备好、`simulated` 是后端的事实
+        let session = agent::Session {
+            agent: &self.agent,
+            rail: self.agent_host.rail(),
+            failure: self.agent_failure(),
+            simulated: self.agent_host.is_simulated(),
+        };
+
+        let account = self.rail_account();
+        match pages::Screen::of(self.state.route()) {
+            Some(_) => shell::view_with_account(
+                &self.ui,
+                shell::NavRail {
+                    selected: nav_item_of(self.state.route()),
+                    account: account.clone(),
+                },
+                APP_TITLE,
+                background,
+                // M101 r2：设置页的只读状态（外观运行期状态 + 各组自己的状态）一次递进去。
+                pages::page_with_settings(
+                    &self.ui,
+                    &self.view,
+                    pages::settings::States {
+                        appearance: Some(&self.appearance),
+                        groups: &self.settings,
+                    },
+                    // M106：设置页 General 组要画「当前档位 + 生效语言」。
+                    self.language(),
+                )
+                .map(Message::Page),
+                agent::docked(&self.ui, session, agent_catalog, self.width)
+                    .map(|element| element.map(Message::Agent)),
+                overlay,
+                self.options.force_state,
+                self.lang(),
+            ),
+            // 账户页（M114）：它不走 `pages::Screen` 那四页的 `Model`，自己一棵树
+            // （树在 `app/view/account_page.rs`，与其它页共用 M104 的中栏可用宽）。
+            None if self.state.route() == &Route::Accounts => {
+                self.account_page(&account, background, overlay)
+            }
+            // `Route::Agent`：独立页与右栏共用同一个 `conversation::view`（`agent::page` 内部调的它）。
+            None => shell::view_with_account(
+                &self.ui,
+                shell::NavRail {
+                    selected: NavItem::Ai,
+                    account: account.clone(),
+                },
+                APP_TITLE,
+                background,
+                agent::page(&self.ui, session, agent_catalog, self.width).map(Message::Agent),
+                None,
+                overlay,
+                self.options.force_state,
+                self.lang(),
+            ),
+        }
+    }
+}
+
+// --------------------------------------------------------------- 快照 → 视图模型
+
+/// 把 presenter 的快照转成页面视图模型（**唯一**的展示转换点）。
+///
+/// `forced` 是 `--force-state` 的落点（P3-1）：它只影响**画出来的**状态层，不改任何状态机。
+///
+/// `width` 是**中栗可用宽度**（窗口 − 右栗 − 拖拽缝，由 `AgentUi::content_width` 算），不是窗口宽：
+/// 页面布局系统仍按「一个窗口宽」扣左轨与页边距，所以右栗占掉的那一段必须在这里先减掉——
+/// 否则助手栏一展开，页面还按 1180 排版，内容就顶到面板底下了（任务里的「收缩而不是溢出」）。
+pub(super) fn model(
+    state: &AppState,
+    width: f32,
+    forced: Option<crate::cli::ForcedState>,
+    category: pages::Category,
+    draft: &pages::InstallDraft,
+    lang: Lang,
+    content: &pages::content::PageState,
+) -> pages::Model {
+    let route = state.route().clone();
+    let screen = pages::Screen::of(&route).unwrap_or(pages::Screen::Instances);
+    // 实例页的文案真源：`App::lang` 的目录（M120）。列表 overline / 元信息标签 / 空态都从它取。
+    let catalog = lang.catalog();
+
+    let rows: Vec<Row> = state
+        .tiles()
+        .into_iter()
+        .map(|cell| Row {
+            id: cell.instance.id.clone(),
+            name: cell.instance.name.clone(),
+            supporting: supporting_line(cell.instance, catalog),
+            status: runtime_status(&cell.instance.runtime, catalog),
+        })
+        .collect();
+
+    let detail = match &route {
+        Route::Detail(id) => state
+            .instances
+            .iter()
+            .find(|instance| &instance.id == id)
+            .map(|instance| detail_of(instance, catalog)),
+        _ => None,
+    };
+
+    pages::Model {
+        screen,
+        window_width: width,
+        active: route.nav(),
+        instances: pages::Instances { rows, detail },
+        download: pages::Download::from_snapshot(state, category, draft, lang.catalog()),
+        // M109：检索条件/结果来自快照，页面内选择（类型/选中/目标/草稿）来自 `App::content`
+        content: pages::content::Content::from_snapshot(state, content, lang.catalog()),
+        logs: logs_model(state).with_status(lang),
+        lang,
+        forced: forced.map(|state| match state {
+            // `Rest` = 常态（压掉系统光标 hover）；`Interaction::Enabled` 就是静息态，不叠状态层。
+            crate::cli::ForcedState::Rest => Interaction::Enabled,
+            crate::cli::ForcedState::Hover => Interaction::Hovered,
+            crate::cli::ForcedState::Pressed => Interaction::Pressed,
+        }),
+    }
+}
+
+#[cfg(test)]
+#[path = "view/tests.rs"]
+mod tests;
+
+/// 测试只借这一条（其余三条 `model()` 自己用）。
+#[cfg(test)]
+use instances::last_played;
diff --git a/crates/app-iced/src/app/view/account_page.rs b/crates/app-iced/src/app/view/account_page.rs
new file mode 100644
index 0000000..a90ca99
--- /dev/null
+++ b/crates/app-iced/src/app/view/account_page.rs
@@ -0,0 +1,73 @@
+//! 账户页（M114）的**整页装配**：从 `App` 的状态拼出内容树，再交给外壳。
+//!
+//! 为什么单独一个文件：`app/view.rs` 贴着 400 行硬线（M104 的右栏分支已经把余量吃掉了），
+//! 而这段是纯装配（没有状态数学），搬出来不改变任何语义。
+//!
+//! 宽度口径：用 `AccountPage::width`（= M104 的 `AgentUi::content_width`，中栏可用宽），
+//! 与其它页、与 `refresh_view` 同一份来源——右栏展开时账户页**一起收缩**，不会顶到面板底下。
+
+use iced::Element;
+
+use crate::app::Message;
+use crate::pages;
+use crate::pages::account::Page as AccountPage;
+use crate::shell::{self, agent, NavItem, RailAccount};
+
+use super::super::state::App;
+use super::super::APP_TITLE;
+
+impl App {
+    /// 账户页视图模型的重建（`refresh_view` 的账户那一步）。
+    ///
+    /// 与 `view` 同一次门控；语言跟着 M106 的 `LangState` 走（M114 早期钉死 `Lang::En`
+    /// 的写法已删），宽度用 M104 的中栏可用宽。放在这里是为了让 `app/state.rs` 守住 400 行。
+    pub(in crate::app) fn rebuild_account_page(&mut self, width: f32) {
+        let lang = self.lang();
+        self.account = AccountPage::build(
+            &self.state,
+            &self.account_form,
+            &mut self.avatars,
+            lang,
+            width,
+        );
+    }
+
+    /// 账户页（走 `pages::account` 自己的树，而不是 `pages::Screen` 那四页的 `Model`）。
+    pub(super) fn account_page<'a>(
+        &'a self,
+        account: &RailAccount,
+        background: Option<Element<'a, Message>>,
+        overlay: Option<Element<'a, Message>>,
+    ) -> Element<'a, Message> {
+        let metrics =
+            pages::layout::frame_metrics(pages::layout::PaneKit::Single, self.account.width);
+        shell::view_with_account(
+            &self.ui,
+            shell::NavRail {
+                selected: NavItem::Account,
+                account: account.clone(),
+            },
+            APP_TITLE,
+            background,
+            // M106：账户页的文案跟着**生效语言**走（`LangState::boot` 自己读 `ULL_LANG`，
+            // 所以 M114 早期那个「截图专用语言开关」已删——两套开关必然漂）。
+            pages::account::view(&self.ui, metrics, &self.account, self.lang()).map(Message::Page),
+            // M119：右栗的会话内容 / 未读 / busy 全部来自 presenter 的 rail（`agent_host`）
+            agent::docked(
+                &self.ui,
+                agent::Session {
+                    agent: &self.agent,
+                    rail: self.agent_host.rail(),
+                    failure: self.agent_failure(),
+                    simulated: self.agent_host.is_simulated(),
+                },
+                self.lang().catalog(),
+                self.width,
+            )
+            .map(|element| element.map(Message::Agent)),
+            overlay,
+            self.options.force_state,
+            self.lang(),
+        )
+    }
+}
diff --git a/crates/app-iced/src/app/view/instances.rs b/crates/app-iced/src/app/view/instances.rs
new file mode 100644
index 0000000..da88dbf
--- /dev/null
+++ b/crates/app-iced/src/app/view/instances.rs
@@ -0,0 +1,162 @@
+//! 实例页的**展示转换**（M120 从 `app/view.rs` 原样搬出：那边给 i18n 让出行数）。
+//!
+//! | 函数 | 产物 | 谁读 |
+//! |---|---|---|
+//! | [`supporting_line`] | 列表行 / 详情副标题 `1.20.4 · Fabric 0.16.5` | [`crate::pages::Row`] / [`crate::pages::Detail`] |
+//! | [`runtime_status`] | 运行状态行（列表 overline + 详情状态行共用一份） | 同上 |
+//! | [`detail_of`] | 详情列的全部字段 | [`crate::pages::Detail`] |
+//! | [`last_played`] | `2026-10-29 19:22 UTC` / `Never` | 元信息卡 `LAST PLAYED` |
+//!
+//! 这里只做「快照字段 → 要画什么」，不碰控件树。**文案的语言由调用方的 [`Catalog`] 决定**
+//! （`view::model` 把 `App::lang` 的目录传进来），不再是 M90 时期的英文基线字面量。
+//!
+//! ## 两条接法上的取舍
+//!
+//! 1. **原版徽标走词表**：`LoaderInfo::badge()` 对原版返回**中文**「原版」（那是 presenter 的
+//!    面向中文日志的 `label()`），英文界面里直接画它就是「中文漏进英文界面」。所以原版这一支
+//!    改走 [`Key::LoaderVanilla`]，装加载器时仍是 `Fabric 0.16.5`（品牌 + 版本号，不翻译）；
+//! 2. **运行状态只翻标签本体**：`Running · pid 1234` → `运行中 · pid 1234`，`pid` 与数字、
+//!    `·` 分隔符一个字都不动（[`Key::InstancesRunning`] 的占位符只有 `{pid}`）。
+
+use unlucky_i18n::{Catalog, Key};
+use unlucky_presenter::dto::{InstanceRuntime, InstanceSummary, LaunchStage, LoaderKind};
+
+use crate::pages::{Detail, Meta};
+
+/// 列表行的副文案：`1.20.4 · Fabric 0.16.5`（原版只写「原版 / Vanilla」，见 [`loader_badge`]）。
+pub(super) fn supporting_line(instance: &InstanceSummary, catalog: Catalog) -> String {
+    format!(
+        "{} · {}",
+        instance.mc_version,
+        loader_badge(instance, catalog)
+    )
+}
+
+/// 加载器徽标：原版走词表，其余交给 `LoaderInfo::badge()`（品牌 + 版本号，原样）。
+///
+/// **判据只能是「加载器类型本身是原版」**。曾经写成「原版 **或** 版本号为空」⇒
+/// `1.20.1-forge` / `1.20.1-neoforge` / `1.20.1-OptiFine` 这类**取不到版本段**的 id（`badge()`
+/// 对它们给的就是品牌名 `Forge` / `NeoForge` / `OptiFine`）会被显示成「原版 / Vanilla」——
+/// 那是 M120 r1 的 p2-1 回归，`the_loader_badge_keeps_the_brand_when_the_version_is_missing` 守着。
+fn loader_badge(instance: &InstanceSummary, catalog: Catalog) -> String {
+    match instance.loader.kind {
+        // 唯一需要过词表的一支：`LoaderKind::label()` 对原版返回的是**中文**「原版」
+        LoaderKind::Vanilla => catalog.text(Key::LoaderVanilla).to_string(),
+        // 其余品牌名不翻译；版本号为空时 `badge()` 自己就只给品牌名
+        _ => instance.loader.badge(),
+    }
+}
+
+/// 隔离档位：`isolated` / `shared` 是两个稳定 id（`core::game::IsolationMode::as_str`），
+/// 直接上屏就是英文界面漏中文、中文界面漏英文。只认这两档，**其余原样**（`inherit` / `custom` /
+/// 未来新增的值不许在这里被猜成一个意思）。
+fn isolation(raw: &str, catalog: Catalog) -> String {
+    match raw {
+        "isolated" => catalog.text(Key::InstancesIsolationIsolated).to_string(),
+        "shared" => catalog.text(Key::InstancesIsolationShared).to_string(),
+        other => other.to_string(),
+    }
+}
+
+/// 运行状态（列表行的 overline 与详情页的状态行共用一份文案）。
+pub(super) fn runtime_status(runtime: &InstanceRuntime, catalog: Catalog) -> Option<String> {
+    match runtime {
+        InstanceRuntime::Idle => None,
+        // 「阶段 · 百分比」：百分比是数字，不过词表；只有阶段名换语言
+        InstanceRuntime::Busy { stage, progress } => Some(format!(
+            "{} · {:.0}%",
+            stage_label(*stage, catalog),
+            progress.ratio() * 100.0
+        )),
+        InstanceRuntime::Running { pid } => {
+            Some(catalog.render(Key::InstancesRunning, &[("pid", &pid.to_string())]))
+        }
+        // `reason` 是 core 给的诊断原文（**数据**，不翻译）；只有前半句是界面文案
+        InstanceRuntime::Failed { reason } => {
+            Some(catalog.render(Key::InstancesFailed, &[("reason", reason)]))
+        }
+    }
+}
+
+/// 阶段文案：**不**复用 `LaunchStage::label()`（那是核心层的中文诊断串，英文界面会漏中文）。
+fn stage_label(stage: LaunchStage, catalog: Catalog) -> &'static str {
+    catalog.text(match stage {
+        LaunchStage::Download => Key::InstancesStageDownload,
+        LaunchStage::Verify => Key::InstancesStageVerify,
+        LaunchStage::Launch => Key::InstancesStageLaunch,
+        LaunchStage::Window => Key::InstancesStageWindow,
+    })
+}
+
+/// 详情列的内容（字段全部来自 [`InstanceSummary`]）。
+pub(super) fn detail_of(instance: &InstanceSummary, catalog: Catalog) -> Detail {
+    Detail {
+        id: instance.id.clone(),
+        name: instance.name.clone(),
+        subtitle: supporting_line(instance, catalog),
+        meta: vec![
+            meta(
+                catalog.text(Key::InstancesMetaVersion),
+                &instance.mc_version,
+            ),
+            meta(
+                catalog.text(Key::InstancesMetaLoader),
+                &loader_badge(instance, catalog),
+            ),
+            meta(
+                catalog.text(Key::InstancesMetaIsolation),
+                &isolation(&instance.isolation, catalog),
+            ),
+            meta(
+                catalog.text(Key::InstancesMetaVersionId),
+                &instance.version_id,
+            ),
+            meta(
+                catalog.text(Key::InstancesMetaFiles),
+                catalog.text(if instance.version_present {
+                    Key::InstancesPresentOnDisk
+                } else {
+                    Key::InstancesMissing
+                }),
+            ),
+            meta(
+                catalog.text(Key::InstancesMetaLastPlayed),
+                &last_played(instance.last_played.as_deref(), catalog),
+            ),
+        ],
+        // 真快照没有「正文描述」这种字段（偏离 #9）：演示数据才有正文段
+        note: None,
+        status: runtime_status(&instance.runtime, catalog),
+        can_launch: matches!(
+            instance.runtime,
+            InstanceRuntime::Idle | InstanceRuntime::Failed { .. }
+        ),
+        can_stop: matches!(
+            instance.runtime,
+            InstanceRuntime::Busy { .. } | InstanceRuntime::Running { .. }
+        ),
+    }
+}
+
+fn meta(label: &str, value: &str) -> Meta {
+    Meta {
+        label: label.to_string(),
+        value: value.to_string(),
+    }
+}
+
+/// ISO-8601（`2026-10-29T19:22:00Z`）→ `2026-10-29 19:22 UTC`；`None` = 从未启动。
+///
+/// 只做切片不做时区换算：core 给的是 UTC，`Z` 就是它的时区；本地时区换算等时间格式 mission。
+/// 非 ASCII 或长度不足时原样返回（不 panic、不猜）。
+pub(super) fn last_played(raw: Option<&str>, catalog: Catalog) -> String {
+    let Some(text) = raw else {
+        return catalog.text(Key::InstancesNeverPlayed).to_string();
+    };
+    match (text.get(0..10), text.get(11..16)) {
+        (Some(date), Some(time)) if date.starts_with(|c: char| c.is_ascii_digit()) => {
+            format!("{date} {time} UTC")
+        }
+        _ => text.to_string(),
+    }
+}
diff --git a/crates/app-iced/src/app/view/logs.rs b/crates/app-iced/src/app/view/logs.rs
new file mode 100644
index 0000000..136c635
--- /dev/null
+++ b/crates/app-iced/src/app/view/logs.rs
@@ -0,0 +1,144 @@
+//! 日志页的展示转换：presenter 快照 → [`pages::Logs`]（从 `app/view.rs` 拆出来，M95 r3）。
+//!
+//! ## 跨会话串场（M95 r3 的 p2，代码复审抓的）
+//!
+//! r2 的写法先按 `state.diagnosis` 定「这是哪一场」：
+//!
+//! ```ignore
+//! let session = report.and_then(|r| log_sessions.find(|s| s.id == r.session)).or_else(|| …selected…);
+//! ```
+//!
+//! 而 `state.diagnosis` **全仓只写不清**（`presenter::state::apply_core` 里
+//! `CoreEvent::DiagnosisReady` 是唯一赋值点，没有任何清零点），host 也只在崩溃 / 打开会话 /
+//! 导入崩溃文件时发它。于是「崩溃一场 → 再启动一场正常跑」这个最普通的路径下：
+//! 页头把**新**会话标成上一场的 `The game crashed`、诊断卡挂着上一场的结论，而用户复制去贴
+//! issue 的摘要里 `lines=` 是新的那一场的行数——**结论与行数不同源**，用户会把错诊断递出去。
+//!
+//! 现在的口径（不动 presenter 的写入口，只在页面侧判别）：
+//!
+//! | 概念 | 取值 |
+//! |---|---|
+//! | **身份**（这一场是谁） | `live_session`（正在跑）→ `selected_session`（打开/刚结束的），**不从 `diagnosis` 反推** |
+//! | 诊断结论 | 见下表的三个分支（r4 修正了 r3 的一条**回归**：r3 只认身份，把「导入崩溃文件」与「打开会话」两条路径的诊断一并关掉了） |
+//! | 实例/时间/结局（给页头描述） | 身份优先；身份为空才退到报告的 session |
+//!
+//! 归属判据（`report.session` 与身份的关系）：
+//!
+//! | `live_session` | `selected_session` | 报告算数的条件 |
+//! |---|---|---|
+//! | `Some(live)` | 任意 | `report.session == live` —— 只有它在线时日志行是它自己在追加，别人的报告挂上来就是串场 |
+//! | `None` | `Some(sel)` | `report.session == sel` **或** 报告不属于任何已知会话（`ImportCrashLog` 用 `file:<文件名>` 当会话 id，永远不在索引里） |
+//! | `None` | `None` | 全部算数 —— 此时日志行只可能来自 `open_session` 或导入，两者都与报告同一次调用发出 |
+//!
+//! 已知残留（今天 iced 侧不可达，登记在报告里）：`open_session(A)` 在 `selected_session` 仍停在上
+//! 一场 B 时会被第三行判据挡掉（A 是已知会话且 ≠ B）——真正要修得让 presenter 在
+//! `LogLinesChanged` 时把「日志行属于哪一场」记下来（`AppState` 今天没有这个字段）。
+//!
+//! 「没有命中规则」的**占位报告**也不画：host 的 `open_session` 在规则引擎无结论时会发一份
+//! `rule: ""` / `confidence: 0` / `title: "该会话没有命中已知规则"` 的假报告（`CoreEvent::DiagnosisReady`
+//! 是非 Option，host 无法表达「没有结论」）——它是标记不是结论，画出来等于给用户看一条「严重度提示」。
+//!
+//! 已知缺口（已报 finding，不在本 mission 修）：`clear_logs` 之后 `selected_session` 不清，
+//! 身份会继续指向那一场；导入崩溃文件只发 `DiagnosisReady`（不带日志行），所以页面上会出现
+//! 「结论 + 上一场的日志正文」——行由 `open_session` 负责，那是 presenter 的缺口。
+
+use unlucky_presenter::dto::{Diagnosis, LogLevel, LogOutcome};
+use unlucky_presenter::state::AppState;
+
+use crate::pages;
+
+/// 日志页视图模型：presenter 快照 → 要画的东西。
+///
+/// 两处 DTO 侧的**信息丢失**（已报 finding）：`dto::Diagnosis` 没有 core 的 `severity`
+/// （所以页面按置信度档分组，不冒称严重度）与 `cause.key`（`title`/`hint` 只能当数据画）。
+pub(super) fn logs_model(state: &AppState) -> pages::Logs {
+    let live = state.live_session.as_deref();
+    let selected = state.selected_session.as_deref();
+    let identity = live.or(selected);
+
+    // 归属判据（r4 修正 r3 的**回归**：r3 的「有选中就只认选中」把导入/打开这两条路径的诊断
+    // 一起关掉了）。三条命中任一即认：
+    //
+    // 1. 报告属于**正在跑**的那一场 —— 这一条必须单独成立：只有它在线时日志行是它自己在追加，
+    //    别的会话的报告挂上来就是串场（r3 修的正是这个）；
+    // 2. 报告属于**当前选中**的那一场（没有 live 会话时）；
+    // 3. 报告的会话**不在会话索引里** —— `ImportCrashLog` 用 `file:<文件名>` 当会话 id，
+    //    `open_session` 也不一定把 id 写进 `selected_session`；这两条路径与报告是同一次调用发出的，
+    //    把它们一并关掉就是把「导入崩溃日志」这条功能画成空（r3 的实测回归）。
+    let known = |id: &str| state.log_sessions.iter().any(|session| session.id == id);
+    let report = state.diagnosis.as_ref().filter(|report| {
+        let id = report.session.as_str();
+        match (live, selected) {
+            // 有会话在跑：日志行是它自己在追加，别的会话的报告挂上来就是串场（r3 修的 P1）。
+            (Some(live), _) => id == live,
+            // 没有在跑、但有选中项：报告要么是它的，要么是「会话索引里没有的那一份」
+            // （`ImportCrashLog` 用 `file:<文件名>`；`open_session` 不写 `selected_session`，
+            // 所以只能靠「不在索引里」认它）。
+            (None, Some(selected)) => id == selected || !known(id),
+            // 什么身份都没有：日志行只可能来自 `open_session` 或导入，两者与报告同一次发出。
+            (None, None) => true,
+        }
+    });
+
+    // 身份为空时，描述的来源只能退到报告（见模块文档的表格）。
+    let described = identity.or_else(|| report.map(|report| report.session.as_str()));
+    let session =
+        described.and_then(|id| state.log_sessions.iter().find(|session| session.id == id));
+
+    pages::Logs {
+        instance: session.map(|session| session.instance.clone()),
+        when: session.map(|session| session.when.clone()),
+        outcome: session.map(|session| log_outcome(session.outcome)),
+        // 运行中的会话不在 `log_sessions` 里（索引只在结束时追加），所以页头要靠这个标记
+        // 走「正在运行」那条文案，而不是「当前没有运行中的实例」。
+        live: live.is_some(),
+        lines: state
+            .log_lines
+            .iter()
+            .map(|line| pages::Line {
+                text: line.text.clone(),
+                level: log_level(line.level),
+            })
+            .collect(),
+        findings: report
+            .filter(|report| !report.diagnosis.rule.is_empty())
+            .map(|report| diagnosis_of(&report.diagnosis))
+            .into_iter()
+            .collect(),
+        ..pages::Logs::default()
+    }
+}
+
+/// 日志等级：presenter 枚举 → 页面等级（**结构化出口**，不是认字符串）。
+fn log_level(level: LogLevel) -> pages::Level {
+    match level {
+        LogLevel::Debug => pages::Level::Debug,
+        LogLevel::Info => pages::Level::Info,
+        LogLevel::Warn => pages::Level::Warn,
+        LogLevel::Error => pages::Level::Error,
+    }
+}
+
+/// 会话结局：presenter 枚举 → 页面结局（文案走 `LaunchOutcome*` key，页面不画 core 的中文串）。
+fn log_outcome(outcome: LogOutcome) -> pages::Outcome {
+    match outcome {
+        LogOutcome::Ok => pages::Outcome::Ok,
+        LogOutcome::Crashed => pages::Outcome::Crashed,
+        LogOutcome::SilentFail => pages::Outcome::SilentFail,
+    }
+}
+
+/// 一条诊断结论 → 页面结论（置信度档见 [`pages::Confidence`]）。
+fn diagnosis_of(diagnosis: &Diagnosis) -> pages::Finding {
+    pages::Finding {
+        rule: diagnosis.rule.clone(),
+        confidence_band: pages::Confidence::of(diagnosis.confidence),
+        title: diagnosis.title.clone(),
+        hint: diagnosis.hint.clone(),
+        confidence: diagnosis.confidence,
+        action: diagnosis.fix.clone(),
+    }
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/app-iced/src/app/view/logs/tests.rs b/crates/app-iced/src/app/view/logs/tests.rs
new file mode 100644
index 0000000..624732a
--- /dev/null
+++ b/crates/app-iced/src/app/view/logs/tests.rs
@@ -0,0 +1,242 @@
+//! 日志页展示转换的守门测试（从 `app/view/logs.rs` 拆出：那边已经 382 行，贴着 400 硬上限）。
+//!
+//! 全部走**真实 reducer 路径**（`AppState::apply_core`），不造注入源——r3 的教训是
+//! 「测试全走注入源而真实路径零覆盖」，所以这里的夹具就是线上那串事件本身。
+
+use unlucky_i18n::Lang;
+use unlucky_presenter::dto::{
+    CoreEvent, DiagnosisReport, LaunchFinished, LiveLogBatch, LogLevel, LogLine, LogOutcome,
+    LogSession,
+};
+use unlucky_presenter::state::AppState;
+
+use crate::pages;
+
+use super::logs_model;
+
+/// 崩溃的那一场。
+const CRASH: &str = "s-1029-1840";
+/// 崩溃之后又启动的、正常跑的一场。
+const OK_RUN: &str = "s-1029-1922";
+
+fn session(id: &str, when: &str, outcome: LogOutcome) -> LogSession {
+    LogSession {
+        id: id.to_string(),
+        instance: "开发测试".to_string(),
+        when: when.to_string(),
+        outcome,
+        duration_secs: 62,
+    }
+}
+
+fn line(text: &str, level: LogLevel) -> LogLine {
+    LogLine {
+        text: text.to_string(),
+        level,
+    }
+}
+
+fn report(session: &str, rule: &str) -> DiagnosisReport {
+    DiagnosisReport {
+        session: session.to_string(),
+        diagnosis: pages_dto(rule),
+    }
+}
+
+fn pages_dto(rule: &str) -> unlucky_presenter::dto::Diagnosis {
+    unlucky_presenter::dto::Diagnosis {
+        rule: rule.to_string(),
+        title: "显卡驱动过旧（OpenGL 版本不足）".to_string(),
+        confidence: 92,
+        hint: "升级显卡驱动".to_string(),
+        fix: Some("change_graphics.driver".to_string()),
+    }
+}
+
+/// **真实数据路径**（复审要求：不许造注入源绕过去）：
+/// 崩溃一场跑完 → 再启动一场正常跑。`state.diagnosis` 在这里**故意不清**，
+/// 因为 presenter 里根本没有清零点——这就是线上发生串场的条件。
+fn crashed_only() -> AppState {
+    let mut state = AppState::new();
+    state.apply_core(CoreEvent::LogSessionsChanged(vec![
+        session(CRASH, "10-29 18:40", LogOutcome::Crashed),
+        session(OK_RUN, "10-29 19:22", LogOutcome::Ok),
+    ]));
+
+    // 第一场跑起来（live_session = CRASH）→ 日志 → 规则结论 → 收尾（selected_session = CRASH）
+    state.apply_core(CoreEvent::LogAppended(LiveLogBatch {
+        session: CRASH.to_string(),
+        lines: vec![line("[18:40] boom: GLFW error", LogLevel::Error)],
+        running: true,
+    }));
+    state.apply_core(CoreEvent::DiagnosisReady(report(CRASH, "gpu.driver_old")));
+    state.apply_core(CoreEvent::LaunchFinished(LaunchFinished {
+        id: "dev".to_string(),
+        session: CRASH.to_string(),
+        outcome: LogOutcome::Crashed,
+        summary: "崩溃（exit 1）".to_string(),
+    }));
+
+    state
+}
+
+/// 崩溃之后又启动一场正常跑：`live_session` 前进，`diagnosis` 仍是上一场的。
+fn after_a_new_run() -> AppState {
+    let mut state = crashed_only();
+    state.apply_core(CoreEvent::LogAppended(LiveLogBatch {
+        session: OK_RUN.to_string(),
+        lines: vec![line("[19:22] launching 1.20.4", LogLevel::Info)],
+        running: true,
+    }));
+    state
+}
+
+#[test]
+fn a_new_run_does_not_inherit_the_previous_crash() {
+    let state = after_a_new_run();
+    let logs = logs_model(&state).with_status(Lang::En);
+
+    // 抓得住：身份被上一场的 `diagnosis.session` 顶掉（r2 的 bug）——那时 outcome 会是
+    //          Crashed、findings 挂着 gpu.driver_old、摘要里 `lines=` 与结论不同源。
+    // 抓不住：presenter 自己 `clear_logs` 后 `selected_session` 不清的缺口（已报 finding），
+    //          以及多场并行会话（本仓一次只跑一场）。
+    assert_eq!(
+        logs.outcome,
+        Some(pages::Outcome::Ok),
+        "身份应该是正在跑的这一场"
+    );
+
+    let status = logs.status.clone().expect("有会话身份就该有副标题");
+    assert!(status.contains("Finished normally"), "{status}");
+    assert!(
+        !status.contains("The game crashed"),
+        "页头把新会话标成了上一场的崩溃：{status}"
+    );
+
+    assert!(
+        logs.findings.is_empty(),
+        "上一场的结论不能挂到这一场：{:?}",
+        logs.findings
+    );
+
+    // 摘要必须与身份同源：outcome 是 ok、不含旧规则、行数就是当前这些行。
+    let summary = logs.summary();
+    assert!(summary.contains("outcome=ok"), "{summary}");
+    assert!(!summary.contains("gpu.driver_old"), "{summary}");
+    assert!(
+        summary.contains(&format!("lines={}", logs.lines.len())),
+        "{summary}"
+    );
+    assert!(!summary.contains("findings="), "{summary}");
+}
+
+#[test]
+fn the_crash_itself_is_still_reported() {
+    // 上一条测试的**对照**：崩溃当场必须画结论，否则那条断言「findings 为空」是空的。
+    // 抓得住：把判别写成「永远不画诊断」（用空断言骗过 P2）。
+    // 抓不住：结论排序/去重（那是 core 的规则引擎的事）。
+    let state = crashed_only();
+    let logs = logs_model(&state).with_status(Lang::En);
+
+    assert_eq!(logs.outcome, Some(pages::Outcome::Crashed));
+    assert_eq!(logs.findings.len(), 1, "{:?}", logs.findings);
+    assert_eq!(logs.findings[0].rule, "gpu.driver_old");
+    let status = logs.status.clone().unwrap_or_default();
+    assert!(status.contains("The game crashed"), "{status}");
+    assert!(logs.summary().contains("gpu.driver_old:high(92)"));
+}
+
+#[test]
+fn an_imported_crash_file_still_shows_its_findings() {
+    // r3 的**回归**：r3 把归属判据写成「有选中就只认选中」，于是导入崩溃日志
+    // （`ImportCrashLog` → `DiagnosisReady` 带 `file:<文件名>` 的会话 id，且**不发**
+    // `LogLinesChanged`）被整条丢掉。今天 iced 侧还没有 dispatch 站点（那些还在遗留的
+    // Slint shell 里），所以复审没判 p1；这条测试是为了**将来接线的人**不再踩。
+    // 抓得住：只有「属于当前选中/live 会话」才画的窄判据（导入的 `file:` 会话不等于任何
+    //          索引里的会话，会被误杀）。
+    // 抓不住：导入后日志正文该显示什么（`ImportCrashLog` 不载入日志行，那是 presenter 的事）。
+    let mut state = AppState::new();
+    state.apply_core(CoreEvent::LogSessionsChanged(vec![session(
+        CRASH,
+        "10-29 18:40",
+        LogOutcome::Crashed,
+    )]));
+    // 上一场刚结束 ⇒ selected_session = CRASH（过期选中项），随后用户导入一份崩溃文件
+    state.apply_core(CoreEvent::LaunchFinished(LaunchFinished {
+        id: "dev".to_string(),
+        session: CRASH.to_string(),
+        outcome: LogOutcome::Crashed,
+        summary: "崩溃（exit 1）".to_string(),
+    }));
+    state.apply_core(CoreEvent::DiagnosisReady(report(
+        "file:crash-2026-11-02_19.40.15-client.txt",
+        "integrity.unsatisfied_link",
+    )));
+
+    let logs = logs_model(&state).with_status(Lang::En);
+    assert_eq!(
+        logs.findings.len(),
+        1,
+        "导入的崩溃日志必须画出它的结论：{:?}",
+        logs.findings
+    );
+    assert_eq!(logs.findings[0].rule, "integrity.unsatisfied_link");
+}
+
+#[test]
+fn a_live_run_says_it_is_running_instead_of_nothing_runs() {
+    // 视觉复审 r3 的 P2-3：session 索引只在**结束**时追加（`host::logs::sessions`），
+    // 所以运行中的那一场永远不在 `log_sessions` 里 ⇒ 拿不到实例名与结局 ⇒ r3 的页头在
+    // 每次实时运行都说「当前没有运行中的实例」。demo 伪造了身份，截图上根本照不出来。
+    // 抓得住：页头退回 Idle 文案（这次走真实 reducer：只有 `LogAppended(running=true)`）。
+    // 抓不住：文案长度在某尺寸下会不会撞右侧动作区（那要看截图）。
+    let mut state = AppState::new();
+    state.apply_core(CoreEvent::LogSessionsChanged(vec![session(
+        CRASH,
+        "10-29 18:40",
+        LogOutcome::Crashed,
+    )]));
+    state.apply_core(CoreEvent::LogAppended(LiveLogBatch {
+        session: OK_RUN.to_string(),
+        lines: vec![line("[19:22] launching", LogLevel::Info)],
+        running: true,
+    }));
+
+    let logs = logs_model(&state).with_status(Lang::En);
+    assert!(logs.live, "live_session 非空就该标记为运行中");
+    let status = logs.status.clone().expect("运行中必须有副标题");
+    let idle = unlucky_i18n::catalog::Catalog::of(Lang::En)
+        .text(unlucky_i18n::catalog::Key::LogsSubtitleIdle);
+    assert_ne!(status, idle, "运行中的页头不能说「没有运行」");
+    assert!(status.contains("Running now"), "{status}");
+}
+
+#[test]
+fn the_hosts_no_rule_matched_placeholder_is_not_a_finding() {
+    // host 的 `open_session` 在规则引擎无结论时发一份 `rule: ""` 的假报告（非 Option 逼的）。
+    // 抓得住：把「没命中」画成一条严重度结论（用户会去修一个不存在的毛病）。
+    // 抓不住：host 该不该改发 `None`（那是 presenter 的 finding）。
+    let mut state = AppState::new();
+    state.apply_core(CoreEvent::LogSessionsChanged(vec![session(
+        CRASH,
+        "10-29 18:40",
+        LogOutcome::Crashed,
+    )]));
+    state.apply_core(CoreEvent::LogLinesChanged(vec![line(
+        "[18:40] nothing to see",
+        LogLevel::Info,
+    )]));
+
+    state.apply_core(CoreEvent::DiagnosisReady(report(CRASH, "")));
+    assert!(
+        logs_model(&state).findings.is_empty(),
+        "空 rule 是『没命中』的占位，不是结论"
+    );
+
+    state.apply_core(CoreEvent::DiagnosisReady(report(CRASH, "gpu.driver_old")));
+    assert_eq!(
+        logs_model(&state).findings.len(),
+        1,
+        "换成真规则就得画出来（证明上面的过滤不是把诊断一起关了）"
+    );
+}
diff --git a/crates/app-iced/src/app/view/rail.rs b/crates/app-iced/src/app/view/rail.rs
new file mode 100644
index 0000000..e67285d
--- /dev/null
+++ b/crates/app-iced/src/app/view/rail.rs
@@ -0,0 +1,35 @@
+//! 导航轨底部**账户头像位**的状态换算（M114）。
+//!
+//! 为什么单独一个文件：`app/view.rs` 贴着 400 行硬线，而这块逻辑与页面树无关——
+//! 它只回答「轨底那个头像位现在该显示成未登录，还是某个账户」。
+
+use crate::shell;
+
+use super::super::state::App;
+
+/// 导航轨收成「图标条」的窗口高度（M114）。
+///
+/// 判据不是「项数」而是**真实可用高度**：四项 + 底部头像位在 48 标题栏之上还要放得下
+/// 4 × 52 + 4 × 4 + 52 ≈ 300；留出一屏正文的最小高度（424 行宽 + 页头 + 边距），
+/// 低于 720 就把标签收掉，只留图标与头像位（头像位**永远可见**，任务要求）。
+const RAIL_COMPACT_HEIGHT: f32 = 720.0;
+
+impl App {
+    /// 导航轨底部头像位的状态（M114）：未登录 / 已登录两态要一眼能分。
+    pub(super) fn rail_account(&self) -> shell::RailAccount {
+        let compact = self.height < RAIL_COMPACT_HEIGHT;
+        match self.state.active_account() {
+            Some(account) => {
+                shell::RailAccount::signed_in(account.monogram(), account.name.clone())
+                    .compact(compact)
+            }
+            // M106：未登录标签跟着**生效语言**走（早期钉死 `Lang::En` 的写法已删）。
+            None => shell::RailAccount::signed_out(
+                self.lang()
+                    .catalog()
+                    .text(unlucky_i18n::Key::AccountRailSignedOut),
+            )
+            .compact(compact),
+        }
+    }
+}
diff --git a/crates/app-iced/src/app/view/tests.rs b/crates/app-iced/src/app/view/tests.rs
new file mode 100644
index 0000000..d011570
--- /dev/null
+++ b/crates/app-iced/src/app/view/tests.rs
@@ -0,0 +1,320 @@
+//! `app/view.rs` 的守门测试（rebase 到 5adac23 之后 view.rs 贴 400 行上限，按「测试独立成文件」拆出）。
+
+use super::*;
+use unlucky_i18n::Key;
+use unlucky_presenter::dto::{
+    InstanceRuntime, InstanceSummary, LaunchStage, LoaderInfo, LoaderKind, Progress,
+};
+use unlucky_presenter::mock_data::mock_instances;
+
+fn instance(runtime: InstanceRuntime) -> InstanceSummary {
+    InstanceSummary {
+        id: "survival".to_string(),
+        name: "Survival".to_string(),
+        mc_version: "1.20.4".to_string(),
+        loader: LoaderInfo {
+            kind: LoaderKind::Fabric,
+            version: "0.16.5".to_string(),
+        },
+        last_played: Some("2026-10-29T19:22:00Z".to_string()),
+        runtime,
+        icon: None,
+        isolation: "isolated".to_string(),
+        version_id: "1.20.4".to_string(),
+        version_present: true,
+    }
+}
+
+/// **取证不变量（M100）**：`ForcedState` 的三档在产品路径上必须映射成「页面控件怎么画」。
+///
+/// 抓得住：① 谁把 `Rest` 映射成 Hovered/Pressed（那会让 `--screenshot` 的默认值反而画出状态层，
+/// 与「取证密闭」正好相反，而且图看起来完全正常）；② 加了变体却映射到别的态这种复制粘贴错。
+/// 抓不住：`shell::overridden`（标题栏 / 导航轨按钮走的**另一处** match，断言在 `shell/tests.rs`），
+/// 也抓不住不消费 `model.forced` 的裸 `iced::button`（设置页「外观」区就是）。
+/// 测试用的薄包装：默认宽度 / 默认分类 / 空草稿 / **给定语言**。
+fn at_lang(state: &AppState, forced: Option<crate::cli::ForcedState>, lang: Lang) -> pages::Model {
+    let draft = pages::InstallDraft::default();
+    let page = pages::content::PageState::default();
+    model(
+        state,
+        1180.0,
+        forced,
+        pages::Category::All,
+        &draft,
+        lang,
+        &page,
+    )
+}
+
+/// 同 [`at_lang`]，语言取英文（绝大多数断言只关心「快照 → 模型」的映射，不关心译文）。
+fn at(state: &AppState, forced: Option<crate::cli::ForcedState>) -> pages::Model {
+    at_lang(state, forced, Lang::En)
+}
+
+#[test]
+fn the_forced_state_maps_to_the_expected_interaction() {
+    let state = AppState::new();
+    let forced = |forced| at(&state, Some(forced)).forced;
+
+    assert_eq!(
+        forced(crate::cli::ForcedState::Rest),
+        Some(Interaction::Enabled),
+        "Rest = 静息态（压掉系统光标 hover）"
+    );
+    assert_eq!(
+        forced(crate::cli::ForcedState::Hover),
+        Some(Interaction::Hovered)
+    );
+    assert_eq!(
+        forced(crate::cli::ForcedState::Pressed),
+        Some(Interaction::Pressed)
+    );
+    assert_eq!(at(&state, None).forced, None);
+}
+
+#[test]
+fn the_snapshot_becomes_the_page_model() {
+    let mut state = AppState::new();
+    state.apply(unlucky_presenter::dto::AppEvent::Core(
+        unlucky_presenter::dto::CoreEvent::InstancesChanged(mock_instances()),
+    ));
+    state.navigate(Route::Detail("survival".to_string()));
+
+    let model = at(&state, None);
+    assert_eq!(model.screen, pages::Screen::Instances);
+    assert_eq!(model.active, Some(pages::Screen::Instances.nav()));
+    assert_eq!(model.window_width, 1180.0);
+    assert_eq!(model.instances.rows.len(), 4, "mock 的四个实例");
+    assert_eq!(model.instances.rows[0].id, "survival");
+
+    let detail = model.instances.detail.expect("路由是 Detail，要有详情");
+    assert_eq!(detail.id, "survival");
+    assert_eq!(detail.meta.len(), 6);
+    assert!(detail.can_launch, "空闲实例可启动");
+    assert!(!detail.can_stop);
+    assert!(detail.note.is_none(), "真快照没有正文段");
+}
+
+#[test]
+fn a_busy_instance_offers_stop_instead_of_play() {
+    let mut state = AppState::new();
+    state.apply(unlucky_presenter::dto::AppEvent::Core(
+        unlucky_presenter::dto::CoreEvent::InstancesChanged(vec![instance(
+            InstanceRuntime::Busy {
+                stage: LaunchStage::Download,
+                progress: Progress {
+                    done: 750,
+                    total: 1_500,
+                },
+            },
+        )]),
+    ));
+    state.navigate(Route::Detail("survival".to_string()));
+
+    let model = at(&state, None);
+    assert_eq!(
+        model.instances.rows[0].status.as_deref(),
+        Some("Downloading · 50%")
+    );
+    let detail = model.instances.detail.expect("有详情");
+    assert!(!detail.can_launch, "启动中不许再点 Play（不做乐观回显）");
+    assert!(detail.can_stop, "启动中要能 Stop");
+}
+
+#[test]
+fn failed_instances_can_be_retried() {
+    let failed = instance(InstanceRuntime::Failed {
+        reason: "exit 1".to_string(),
+    });
+    assert_eq!(
+        runtime_status(&failed.runtime, Lang::En.catalog()).as_deref(),
+        Some("Launch failed · exit 1")
+    );
+    assert!(
+        detail_of(&failed, Lang::En.catalog()).can_launch,
+        "失败后要能重试"
+    );
+}
+
+#[test]
+fn timestamps_are_sliced_not_guessed() {
+    let en = Lang::En.catalog();
+    assert_eq!(
+        last_played(Some("2026-10-29T19:22:00Z"), en),
+        "2026-10-29 19:22 UTC"
+    );
+    assert_eq!(last_played(None, en), "Never");
+    // 短串 / 非 ASCII 原样返回（不 panic）
+    assert_eq!(last_played(Some("2026-10"), en), "2026-10");
+    assert_eq!(last_played(Some("昨天"), en), "昨天");
+    // 「从未游玩」是唯一走词表的那一支
+    assert_eq!(last_played(None, Lang::ZhCn.catalog()), "从未游玩");
+}
+
+/// **快照 → 页面文案跟着 `App::lang` 走**（M120 的核心接线断言，模型这一层）。
+///
+/// 抓得住：`view::model` 又把语言写死成 `Lang::En`（M106 之前的原样）、阶段/元信息标签还留着
+/// 英文基线字面量、原版徽标直接画 presenter 的中文「原版」。这三种都不会让任何别的测试红。
+/// 抓不住：页面把 key 画没画上屏（那是 `pages/instances/tests/i18n.rs` 的取样口 + 出图）。
+#[test]
+fn the_runtime_lines_and_meta_labels_follow_the_language() {
+    let mut state = AppState::new();
+    state.apply(unlucky_presenter::dto::AppEvent::Core(
+        unlucky_presenter::dto::CoreEvent::InstancesChanged(vec![
+            instance(InstanceRuntime::Running { pid: 1234 }),
+            instance(InstanceRuntime::Busy {
+                stage: LaunchStage::Verify,
+                progress: Progress {
+                    done: 750,
+                    total: 1_500,
+                },
+            }),
+        ]),
+    ));
+    state.navigate(Route::Detail("survival".to_string()));
+
+    let en = at_lang(&state, None, Lang::En);
+    let zh = at_lang(&state, None, Lang::ZhCn);
+
+    // 列表 overline：中英各一份，数字与分隔符不动
+    assert_eq!(
+        en.instances.rows[0].status.as_deref(),
+        Some("Running · pid 1234")
+    );
+    assert_eq!(
+        zh.instances.rows[0].status.as_deref(),
+        Some("运行中 · pid 1234")
+    );
+    assert_eq!(
+        en.instances.rows[1].status.as_deref(),
+        Some("Verifying · 50%")
+    );
+    assert_eq!(zh.instances.rows[1].status.as_deref(), Some("校验中 · 50%"));
+
+    // 元信息卡的标签与值
+    let (en_detail, zh_detail) = (
+        en.instances.detail.expect("有详情"),
+        zh.instances.detail.expect("有详情"),
+    );
+    let labels = |detail: &pages::Detail| -> Vec<String> {
+        detail.meta.iter().map(|cell| cell.label.clone()).collect()
+    };
+    assert_eq!(
+        labels(&en_detail),
+        vec![
+            "VERSION",
+            "LOADER",
+            "ISOLATION",
+            "VERSION ID",
+            "FILES",
+            "LAST PLAYED"
+        ]
+    );
+    assert_eq!(
+        labels(&zh_detail),
+        vec!["版本", "加载器", "隔离方式", "版本标识", "文件", "上次游玩"]
+    );
+
+    // 值里只有「是否在磁盘上」与「上次游玩」是可翻译的；版本号 / 隔离方式 / 版本标识是数据
+    // 隔离档位是 core 的稳定 id（`isolated` / `shared`），也要换成人话；认不出来的原样上屏
+    assert_eq!(en_detail.meta[2].value, "Isolated");
+    assert_eq!(zh_detail.meta[2].value, "独立目录");
+    assert_eq!(en_detail.meta[4].value, "Present on disk");
+    assert_eq!(zh_detail.meta[4].value, "已在磁盘上");
+    assert_eq!(
+        en_detail.meta[5].value, "2026-10-29 19:22 UTC",
+        "时间戳是数据：只切片，不随语言变形"
+    );
+    assert_eq!(zh_detail.meta[5].value, "2026-10-29 19:22 UTC");
+
+    // 详情状态行与列表 overline 同源
+    assert_eq!(zh_detail.status.as_deref(), Some("运行中 · pid 1234"));
+}
+
+/// 原版徽标：`LoaderInfo::badge()` 对原版返回**中文**「原版」，英文界面里必须换回 `Vanilla`。
+///
+/// 抓得住：`loader_badge` 退回直接调 `badge()`（M90 ~ M119 的形状）——那样英文界面会漏中文，
+/// 而中文界面又是对的，所以只有这条双语断言抓得住它。
+#[test]
+fn the_vanilla_badge_follows_the_language() {
+    let mut bare = instance(InstanceRuntime::Idle);
+    bare.loader = LoaderInfo {
+        kind: LoaderKind::Vanilla,
+        version: String::new(),
+    };
+    let mut state = AppState::new();
+    state.apply(unlucky_presenter::dto::AppEvent::Core(
+        unlucky_presenter::dto::CoreEvent::InstancesChanged(vec![bare]),
+    ));
+    state.navigate(Route::Detail("survival".to_string()));
+
+    let en = at_lang(&state, None, Lang::En);
+    let zh = at_lang(&state, None, Lang::ZhCn);
+    assert_eq!(en.instances.rows[0].supporting, "1.20.4 · Vanilla");
+    assert_eq!(zh.instances.rows[0].supporting, "1.20.4 · 原版");
+}
+
+/// **品牌名不许被「版本号为空」吞掉**（M120 r1 复审的 p2-1 回归）。
+///
+/// 背景：`host::game::loader_from_id("1.20.1-forge")` 这类 id 里取不到版本段（它按 `forge-`
+/// 找，而 id 的写法是 `-forge` 结尾），于是 `LoaderInfo { kind: Forge, version: "" }`。
+/// `LoaderInfo::badge()` 对这种输入给的正是品牌名 `Forge`——所以判据只能是「类型是原版」，
+/// 不能是「版本号为空」。
+///
+/// 三个 id 各一条断言（复审点名的三档）；`Vanilla` 那一支由
+/// `the_vanilla_badge_follows_the_language` 守，两条合起来把 `loader_badge` 的两侧都钉住。
+///
+/// 抓得住：`loader_badge` 把「非原版 + 空版本号」也送进 `Key::LoaderVanilla`
+/// （r1 的真实形状：`left: "1.20.4 · Vanilla" / right: "1.20.4 · Forge"`）；
+/// 抓不住：`loader_from_id` 认不出自家 `-fabric-` / `-quilt-` 口径这个**更老**的 bug
+/// （在 presenter 里，另一条 mission）。
+#[test]
+fn the_loader_badge_keeps_the_brand_when_the_version_is_missing() {
+    // (版本 id, 期望徽标) —— id 形状取自 `host::game::loader_from_id` 的三条真实输入
+    let cases = [
+        ("1.20.1-forge", LoaderKind::Forge, "Forge"),
+        ("1.20.1-neoforge", LoaderKind::NeoForge, "NeoForge"),
+        ("1.20.1-OptiFine", LoaderKind::OptiFine, "OptiFine"),
+    ];
+
+    for (id, kind, brand) in cases {
+        let mut one = instance(InstanceRuntime::Idle);
+        one.loader = LoaderInfo {
+            kind,
+            // `loader_from_id` 对这三条 id 取不到版本段 ⇒ 空串
+            version: String::new(),
+        };
+        let mut state = AppState::new();
+        state.apply(unlucky_presenter::dto::AppEvent::Core(
+            unlucky_presenter::dto::CoreEvent::InstancesChanged(vec![one]),
+        ));
+        state.navigate(Route::Detail("survival".to_string()));
+
+        // 品牌名两套语言都不翻译 ⇒ 中英逐字相同
+        for lang in [Lang::En, Lang::ZhCn] {
+            let model = at_lang(&state, None, lang);
+            assert_eq!(
+                model.instances.rows[0].supporting,
+                format!("1.20.4 · {brand}"),
+                "{id} 的徽标被显示成了别的东西（新增的判据「版本号为空 ⇒ 原版」就是这条要拦的）"
+            );
+            let detail = model.instances.detail.expect("有详情");
+            assert_eq!(
+                detail.meta[1].label,
+                lang.catalog().text(Key::InstancesMetaLoader)
+            );
+            assert_eq!(detail.meta[1].value, brand, "{id} 的 LOADER 卡值");
+        }
+    }
+}
+
+#[test]
+fn the_agent_route_has_no_page() {
+    let mut state = AppState::new();
+    state.navigate(Route::Agent);
+    let model = at(&state, None);
+    // Agent 没有页面：模型退回实例页的空壳，view 会走外壳回退（`None` 分支）
+    assert_eq!(pages::Screen::of(state.route()), None);
+    assert!(model.instances.detail.is_none());
+    assert_eq!(model.active, None, "AI 页不高亮任何导航项");
+}
diff --git a/crates/app-iced/src/app/window_alpha.rs b/crates/app-iced/src/app/window_alpha.rs
new file mode 100644
index 0000000..e3366d9
--- /dev/null
+++ b/crates/app-iced/src/app/window_alpha.rs
@@ -0,0 +1,134 @@
+//! 整窗 α 的**执行侧**：句柄探测 → `WS_EX_LAYERED` → `SetLayeredWindowAttributes` → 一行日志。
+//!
+//! ## 为什么句柄要绕一圈 iced
+//!
+//! iced 0.14 只给 `window::Id`（它自己的编号），没有「给我 HWND」的公开 API；唯一的入口是
+//! `window::run(id, callback)`——回调里拿到的 `&dyn Window` 实现了 `HasWindowHandle`
+//! （raw-window-handle 0.6），于是能取到 `RawWindowHandle::Win32(hwnd)`。
+//!
+//! ## 三层责任（顺序不能换）
+//!
+//! 1. **探测句柄**：[`probe_hwnd`]，纯取；拿不到就整条链跳过（并如实打日志，不许假装成功）；
+//! 2. **补分层样式**：`ensure_layered`（唯一 `unsafe` 落点，`platform/win32/transparency.rs`）；
+//!    `SetLayeredWindowAttributes` 在没有 `WS_EX_LAYERED` 的窗口上**必然失败**（Win32 返回 0，
+//!    本机 `GetLastError` 常见 87），所以这一步是硬前提；
+//! 3. **下发 α**：`apply_window_alpha`。`α ≥ 1` 时它返回 `Opaque` 并且**不调 FFI**，那时也就不必
+//!    改扩展样式（1、2 步都是白改），[`dispatch`] 里按这个条件短路。
+//!
+//! ## 为什么日志要记「下发字节」而不是「看起来多透明」
+//!
+//! 本机是 RDP + 4 个虚拟显示适配器：`LWA_ALPHA` 的**观感**在这里不可信。所以证据链是
+//! `配置值 → 判据 → 字节 → Win32 返回值`，全部经 [`super::App::log_appearance`] 落成一行文本。
+
+use iced::window;
+
+use crate::platform::win32::transparency::{apply_window_alpha, ensure_layered, AlphaOutcome};
+
+/// 一次「补样式 + 下发」的结果（日志与单测共用）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(super) struct Dispatch {
+    /// `WS_EX_LAYERED` 是否就位（`α ≥ 1` 或 `α = None` 时为 `false`：那次根本没动扩展样式）。
+    pub layered: bool,
+    /// 下发的结局。
+    pub alpha: AlphaOutcome,
+}
+
+impl Dispatch {
+    /// 日志尾巴：`layered=ok outcome=Applied { byte: 205 }`。
+    ///
+    /// `layered` 有三个值，刻意区分「没用到」与「失败」：
+    /// - `n/a`：α ≥ 1 或被拒绝 —— 那次**根本不需要**分层窗口，不是错误；
+    /// - `ok`：这一位在（原本就有或本条补上）；
+    /// - `FAILED`：需要补但补不上（无效句柄等）—— 只有这一种是坏消息。
+    pub(super) fn describe(&self) -> String {
+        let layered = match self.alpha {
+            AlphaOutcome::Opaque | AlphaOutcome::Rejected(_) => "n/a",
+            AlphaOutcome::Applied { .. } | AlphaOutcome::Failed { .. } if !self.layered => "FAILED",
+            _ => "ok",
+        };
+        format!("layered={layered} outcome={:?}", self.alpha)
+    }
+}
+
+/// 把 iced 的窗口句柄翻成 Win32 的 `HWND`（`isize`）。非 Windows 平台返回 `None`。
+pub(super) fn probe_hwnd(handle: &dyn window::Window) -> Option<isize> {
+    use window::raw_window_handle::RawWindowHandle;
+
+    let handle = handle.window_handle().ok()?;
+    match handle.as_raw() {
+        #[cfg(target_os = "windows")]
+        RawWindowHandle::Win32(win32) => Some(win32.hwnd.get()),
+        #[cfg(not(target_os = "windows"))]
+        _ => None,
+        #[cfg(target_os = "windows")]
+        _ => None,
+    }
+}
+
+/// 补样式 + 下发（**幂等**：`α ≥ 1` 时什么都不做，返回 `Opaque`）。
+pub(super) fn dispatch(hwnd: isize, alpha: Option<f64>) -> Dispatch {
+    // α 不透明 / 被拒绝时不需要分层窗口：`SetLayeredWindowAttributes` 那次调用也不会发生，
+    // 改扩展样式纯属副作用（还会让 DWM 换一条合成路径），所以短路掉。
+    let needs_layered = alpha.is_some_and(|alpha| alpha < 1.0);
+    let layered = needs_layered && ensure_layered(hwnd);
+    Dispatch {
+        layered,
+        alpha: apply_window_alpha(hwnd, alpha),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::dispatch;
+    use crate::platform::win32::transparency::{AlphaOutcome, AlphaRejection};
+
+    /// 抓得住：①`α = None` / `α ≥ 1` / `α = 0` 时**不去碰扩展样式**（短路条件写反会在这里红）；
+    /// ②拒绝路径的返回值与 `transparency` 的判据一致。
+    /// 抓不住：真实窗口（有效句柄）上 `WS_EX_LAYERED` 是否真的加上了——那要靠本机日志的 `layered=ok`。
+    #[test]
+    fn opaque_or_refused_alpha_never_touches_the_window_style() {
+        for none in [None, Some(1.0), Some(1.5), Some(0.0), Some(-1.0)] {
+            let result = dispatch(1234, none);
+            assert!(!result.layered, "{none:?} 不该改扩展样式");
+        }
+        assert_eq!(
+            dispatch(1234, None).alpha,
+            AlphaOutcome::Rejected(AlphaRejection::NoAlpha)
+        );
+        assert_eq!(dispatch(1234, Some(1.0)).alpha, AlphaOutcome::Opaque);
+        // 无效句柄 + 合法 α：样式补不上（layered=false），FFI 也不会成功——两层都如实报告。
+        let invalid = dispatch(1, Some(0.5));
+        assert!(!invalid.layered, "无效句柄补不上 WS_EX_LAYERED");
+        assert!(
+            matches!(invalid.alpha, AlphaOutcome::Failed { .. }),
+            "{:?}",
+            invalid.alpha
+        );
+    }
+
+    /// 本机真窗口的取证由 `App` 启动日志给（见 `app::appearance::log_appearance`），
+    /// 这里只钉日志格式：`Applied { byte: 205 }` 必须能一眼读出字节，且「没用到样式」不等于失败。
+    #[test]
+    fn the_log_tail_carries_the_byte_and_distinguishes_skipped_from_failed() {
+        let applied = super::Dispatch {
+            layered: true,
+            alpha: AlphaOutcome::Applied { byte: 205 },
+        };
+        assert!(applied.describe().starts_with("layered=ok outcome=Applied"));
+        assert!(applied.describe().contains("205"));
+
+        // α = 1.0：没补样式是**正常**的，不许写成 FAILED（否则报告里会出现假红）。
+        let opaque = super::Dispatch {
+            layered: false,
+            alpha: AlphaOutcome::Opaque,
+        };
+        assert!(opaque.describe().starts_with("layered=n/a"));
+
+        // 真的要补却没补上：这才是 FAILED。
+        let failed = super::Dispatch {
+            layered: false,
+            alpha: AlphaOutcome::Failed { code: 87 },
+        };
+        assert!(failed.describe().starts_with("layered=FAILED"));
+    }
+}
diff --git a/crates/app-iced/src/cli.rs b/crates/app-iced/src/cli.rs
new file mode 100644
index 0000000..d740aec
--- /dev/null
+++ b/crates/app-iced/src/cli.rs
@@ -0,0 +1,287 @@
+//! 命令行参数（骨架期 + 组件库 harness 需要的那些；业务开关等页面 mission 再加）。
+//!
+//! 取值语法与现役 Slint 版一致：`--key value` 与 `--key=value` 两种都认
+//! （`crates/app/src/screenshot.rs` 的 `value_of` 是同一口径），这样将来 CI 换 bin 不用改脚本。
+//!
+//! ## 参数总表
+//!
+//! | 参数 | 取值 | 语义 |
+//! |---|---|---|
+//! | `--software-renderer` | — | 等价 `--renderer=cpu`（D27 的 CPU 档） |
+//! | `--renderer` | `auto`/`gpu`/`cpu` | 渲染后端请求 |
+//! | `--theme` | `light`/`dark` | 主题；不给则跟随系统（仅交互模式） |
+//! | `--screenshot` / `--screenshot-theme` | 路径 / `light`·`dark` | 截图通道（出图后退出）与截图专用主题 |
+//! | `--screen` | `shell`/`gallery` | 启动画面；**`gallery` = 组件库视觉验收 harness**（D39 §5） |
+//! | `--scale-factor` | `>0` | 强制缩放因子（验收要 100%，即 `1`） |
+//! | `--diff` / `--diff-scan` | 两个路径 / 非负整数 | 逐像素对比（不开窗）与 ±n px 平移扫描 |
+//! | `--force-state` | `rest`/`hover`/`pressed` | 把整屏可交互控件强制成某态（取证）；**给了 `--screenshot` 就默认 `rest`** |
+//! | `--data-dir` | 路径 | 翻牌兼容：**接受并忽略**（CI 冒烟在用） |
+//!
+//! **截图主题默认 Light（门禁依赖，不许改回 None）**，理由与不变量见
+//! [`Options::capture_flavor`] 与 `app.rs` 的截图路径。
+
+use std::path::PathBuf;
+
+use unlucky_design::color::SchemeFlavor;
+
+/// 渲染后端请求（D27）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum Backend {
+    /// 探测后决定：有硬件 GPU 就让 iced 自己走 wgpu→tiny-skia 回退；没有就强制 CPU 起步。
+    #[default]
+    Auto,
+    /// 优先 GPU（写 `ICED_BACKEND=wgpu,tiny-skia`；拿不到适配器仍会降级，不硬失败）。
+    Gpu,
+    /// 强制 CPU（`--software-renderer` 的等价物，写 `ICED_BACKEND=tiny-skia`）。
+    Cpu,
+}
+
+impl Backend {
+    /// 稳定名字（日志用）。
+    pub const fn name(self) -> &'static str {
+        match self {
+            Backend::Auto => "auto",
+            Backend::Gpu => "gpu",
+            Backend::Cpu => "cpu",
+        }
+    }
+
+    /// 截图日志用的后端说明（`cfg!(feature = "gpu")` 决定有没有 wgpu 这一档）。
+    pub fn note(self) -> &'static str {
+        if !cfg!(feature = "gpu") {
+            return "cpu(build without wgpu)";
+        }
+        match self {
+            Backend::Cpu => "cpu(forced)",
+            Backend::Gpu => "gpu(preferred)",
+            Backend::Auto => "auto",
+        }
+    }
+}
+
+/// 启动画面（D39 §5：`gallery` 是视觉验收 harness，不是产品页面）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum Screen {
+    /// 产品骨架：自绘标题栏 + 导航轨 + 内容区。
+    #[default]
+    Shell,
+    /// 组件库 harness：整窗只放状态矩阵。
+    Gallery,
+}
+
+impl Screen {
+    /// 稳定名字（日志用）。
+    pub const fn name(self) -> &'static str {
+        match self {
+            Screen::Shell => "shell",
+            Screen::Gallery => "gallery",
+        }
+    }
+}
+
+/// 解析后的启动参数。
+#[derive(Debug, Clone, PartialEq, Default)]
+pub struct Options {
+    /// 渲染后端请求。
+    pub backend: Backend,
+    /// 主题：`None` = 探测系统主题。
+    pub theme: Option<SchemeFlavor>,
+    /// 截图通道：给了路径就出图后退出。
+    pub screenshot: Option<PathBuf>,
+    /// `--screenshot-theme`（优先级高于 `--theme`）。
+    pub screenshot_theme: Option<SchemeFlavor>,
+    /// 强制窗口缩放因子（验收要 100% DPI，即 `1`；`None` = 用系统 DPI）。
+    pub scale_factor: Option<f32>,
+    /// `--diff <left> <right>` 与 `--diff-scan <n>`：逐像素对比（不开窗）与 ±n px 平移扫描。
+    pub diff: Option<(PathBuf, PathBuf)>,
+    /// 见上（默认 0 = 不扫）。
+    pub diff_scan: u32,
+    /// `--force-state=hover|pressed`：把按钮强制成某个状态便于截图取证（D30 的状态图）。
+    pub force_state: Option<ForcedState>,
+    /// `--screen=shell|gallery`：启动画面（`gallery` = 组件库视觉验收 harness）。
+    pub screen: Screen,
+    /// `--data-dir <dir>`：当前**接受并忽略**（现役 Slint 版 CI 冒烟在用；
+    /// 真正的消费由后续页面 mission 接 `host`/`state` 时做）。
+    pub data_dir: Option<PathBuf>,
+}
+
+/// 截图取证用的强制交互状态（只影响观感，不改变任何状态机）。
+///
+/// 五态完整矩阵由 `--screen=gallery` 的 `Button::state(..)` 出，本开关只给整屏取证。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ForcedState {
+    /// **常态**（静息）：压掉系统光标带来的 hover/pressed。
+    ///
+    /// 截图通道（给了 `--screenshot`）**默认就是它**，理由是实测：M99 复审在同一个 exe 上连跑 8 次，
+    /// 第 6 次给出第三个 hash，差异区是某个按钮被画成 `Hovered`——因为 harness/产品都开真窗口，
+    /// `button::Status` 由系统光标位置决定。取证图不能因为「指针恰好压在某个按钮上」而变色。
+    /// 显式 `--force-state=hover|pressed` 仍然优先（那是**故意**要画那个态）。
+    ///
+    /// ⚠️ **语义边界**：`Rest` 落成 `Interaction::Enabled`，而 `components::buttons::assemble()`
+    /// 把「没有 `on_press`」的按钮默认画成 **Disabled** —— 于是 `Rest` 会把一个本应禁用的按钮
+    /// 画成可用。当前零影响（所有 `forced_state(` 调用点与 shell 的 caption / nav 按钮都带消息），
+    /// 但给「无消息按钮」出取证图时别套 `Rest`。
+    Rest,
+    /// 所有可交互控件按 hover 画。
+    Hover,
+    /// 所有可交互控件按 pressed 画。
+    Pressed,
+}
+
+impl Options {
+    /// 从进程参数解析（错误信息是人话，不 panic、不 `exit`）。
+    ///
+    /// # Errors
+    /// 取值不合法（未知 `--renderer`/`--theme`/`--screen`、非法 `--scale-factor`）时返回人话。
+    pub fn from_env() -> Result<Self, String> {
+        Self::parse(std::env::args().skip(1))
+    }
+
+    /// 从任意参数序列解析（`argv[1..]`，测试直接喂数组）。
+    ///
+    /// # Errors
+    /// 同 [`Options::from_env`]。
+    pub fn parse(args: impl IntoIterator<Item = String>) -> Result<Self, String> {
+        let mut options = Self::default();
+        let mut args = args.into_iter();
+
+        while let Some(arg) = args.next() {
+            let (key, inline) = match arg.split_once('=') {
+                Some((key, value)) => (key.to_owned(), Some(value.to_owned())),
+                None => (arg.clone(), None),
+            };
+
+            match key.as_str() {
+                "--software-renderer" => options.backend = Backend::Cpu,
+                "--renderer" => {
+                    let value = take(&mut args, inline, "--renderer")?;
+                    options.backend = match value.as_str() {
+                        "auto" => Backend::Auto,
+                        "gpu" => Backend::Gpu,
+                        "cpu" => Backend::Cpu,
+                        other => {
+                            return Err(format!("--renderer 只认 auto|gpu|cpu，收到 {other:?}"));
+                        }
+                    };
+                }
+                "--theme" => {
+                    options.theme = Some(flavor(&take(&mut args, inline, "--theme")?)?);
+                }
+                "--screenshot-theme" => {
+                    options.screenshot_theme =
+                        Some(flavor(&take(&mut args, inline, "--screenshot-theme")?)?);
+                }
+                "--screenshot" => {
+                    options.screenshot =
+                        Some(PathBuf::from(take(&mut args, inline, "--screenshot")?));
+                }
+                "--scale-factor" => {
+                    let raw = take(&mut args, inline, "--scale-factor")?;
+                    let value: f32 = raw
+                        .parse()
+                        .map_err(|_| format!("--scale-factor 需要数字，收到 {raw:?}"))?;
+                    if !(value.is_finite() && value > 0.0) {
+                        return Err(format!("--scale-factor 必须 > 0，收到 {raw:?}"));
+                    }
+                    options.scale_factor = Some(value);
+                }
+                "--diff" => {
+                    let left = take(&mut args, inline, "--diff")?;
+                    let right = args
+                        .next()
+                        .ok_or_else(|| "--diff 需要两张图的路径".to_owned())?;
+                    options.diff = Some((PathBuf::from(left), PathBuf::from(right)));
+                }
+                "--diff-scan" => {
+                    let raw = take(&mut args, inline, "--diff-scan")?;
+                    options.diff_scan = raw
+                        .parse()
+                        .map_err(|_| format!("--diff-scan 需要非负整数，收到 {raw:?}"))?;
+                }
+                "--force-state" => {
+                    let raw = take(&mut args, inline, "--force-state")?;
+                    options.force_state = Some(match raw.as_str() {
+                        "rest" => ForcedState::Rest,
+                        "hover" => ForcedState::Hover,
+                        "pressed" => ForcedState::Pressed,
+                        other => {
+                            return Err(format!(
+                                "--force-state 只认 rest|hover|pressed，收到 {other:?}"
+                            ));
+                        }
+                    });
+                }
+                "--screen" => {
+                    let raw = take(&mut args, inline, "--screen")?;
+                    options.screen = match raw.as_str() {
+                        "shell" => Screen::Shell,
+                        "gallery" => Screen::Gallery,
+                        other => {
+                            return Err(format!("--screen 只认 shell|gallery，收到 {other:?}"));
+                        }
+                    };
+                }
+                // 翻牌前的兼容参数：接受并忽略（见字段文档）
+                "--data-dir" => {
+                    options.data_dir = Some(PathBuf::from(take(&mut args, inline, "--data-dir")?));
+                }
+                other => return Err(format!("未知参数 {other:?}")),
+            }
+        }
+
+        // **截图通道默认强制 `Rest`**（M100）：取证图不许跟着系统指针的位置变。
+        // 交互模式保持 `None`——那是用户的真窗口，不许替用户把状态钉死（钉死了就永远看不到 hover）。
+        if options.screenshot.is_some() && options.force_state.is_none() {
+            options.force_state = Some(ForcedState::Rest);
+        }
+
+        Ok(options)
+    }
+
+    /// 截图时实际使用的主题（**只表达用户显式给了什么**；默认值见 [`Options::capture_flavor`]）。
+    pub fn shot_flavor(&self) -> Option<SchemeFlavor> {
+        self.screenshot_theme.or(self.theme)
+    }
+
+    /// 本次进程真正要画的主题（**唯一取值口**）。
+    ///
+    /// 截图模式（给了 `--screenshot`）**永远返回 `Some`**：`--screenshot-theme` > `--theme` > Light。
+    /// 交互模式只有显式指定才有值（`None` = 等系统主题）。
+    ///
+    /// ⚠️ **门禁依赖，不许把截图分支改回 `None`**：CI 的 runtime-smoke 打
+    /// `--software-renderer --screenshot <png> --data-dir <dir>`（不带主题），xvfb 里没有桌面主题
+    /// 会话，M68 的「等系统主题到达再出图」闸门在这条路径上会把 runner 挂到超时（不是红，更难查）。
+    pub fn capture_flavor(&self) -> Option<SchemeFlavor> {
+        match self.screenshot {
+            Some(_) => Some(self.shot_flavor().unwrap_or(SchemeFlavor::Light)),
+            None => self.shot_flavor(),
+        }
+    }
+
+    /// 是否要问系统主题。截图模式**永远不问**——这就是「无主题环境不会卡住」的不变量。
+    pub fn wants_system_theme(&self) -> bool {
+        self.capture_flavor().is_none()
+    }
+}
+
+fn take(
+    args: &mut impl Iterator<Item = String>,
+    inline: Option<String>,
+    flag: &str,
+) -> Result<String, String> {
+    inline
+        .or_else(|| args.next())
+        .ok_or_else(|| format!("{flag} 需要一个值"))
+}
+
+fn flavor(raw: &str) -> Result<SchemeFlavor, String> {
+    match raw {
+        "light" => Ok(SchemeFlavor::Light),
+        "dark" => Ok(SchemeFlavor::Dark),
+        other => Err(format!("--theme 只认 light|dark，收到 {other:?}")),
+    }
+}
+
+#[cfg(test)]
+#[path = "cli/tests.rs"]
+mod tests;
diff --git a/crates/app-iced/src/cli/tests.rs b/crates/app-iced/src/cli/tests.rs
new file mode 100644
index 0000000..e3ed625
--- /dev/null
+++ b/crates/app-iced/src/cli/tests.rs
@@ -0,0 +1,172 @@
+//! `cli::Options` 的解析断言（M100 从 `cli.rs` 内联的 `mod tests` 搬出来：那边 394 行，
+//! 加一个 `ForcedState::Rest` 就必然破 400）。
+//!
+//! 搬移**不改一行断言**：只去掉了 `mod tests { }` 那一层缩进，外加 M100 新增的
+//! `screenshots_default_to_the_rest_state`（见文件末尾）。
+//!
+//! 站位：本文件是 `crate::cli::tests`，`use super::*;` 就够（`Options` / `ForcedState` /
+//! `Backend` / `Screen` 都在 `cli` 里）。
+use super::*;
+
+fn parse(args: &[&str]) -> Result<Options, String> {
+    Options::parse(args.iter().map(|arg| (*arg).to_owned()))
+}
+
+#[test]
+fn defaults_are_auto_system_theme_and_shell() {
+    let options = parse(&[]).expect("空参数要能解析");
+    assert_eq!(options.backend, Backend::Auto);
+    assert_eq!((options.theme, options.screenshot), (None, None));
+    assert_eq!(options.screen, Screen::Shell);
+}
+
+#[test]
+fn software_renderer_is_an_alias_of_cpu() {
+    assert_eq!(
+        parse(&["--software-renderer"]).unwrap().backend,
+        Backend::Cpu
+    );
+    assert_eq!(parse(&["--renderer=cpu"]).unwrap().backend, Backend::Cpu);
+    assert_eq!(parse(&["--renderer", "gpu"]).unwrap().backend, Backend::Gpu);
+}
+
+#[test]
+fn both_argv_forms_are_accepted() {
+    let spaced = parse(&["--screenshot", "out.png"]).unwrap();
+    let inline = parse(&["--screenshot=out.png"]).unwrap();
+    assert_eq!(spaced.screenshot, Some(PathBuf::from("out.png")));
+    assert_eq!(spaced.screenshot, inline.screenshot);
+    assert_eq!(
+        parse(&["--diff", "a.png", "b.png"]).unwrap().diff,
+        Some((PathBuf::from("a.png"), PathBuf::from("b.png")))
+    );
+    assert_eq!(
+        parse(&["--screen", "gallery"]).unwrap().screen,
+        Screen::Gallery
+    );
+    assert_eq!(parse(&["--diff-scan=2"]).unwrap().diff_scan, 2);
+    assert_eq!(
+        parse(&["--force-state", "hover"]).unwrap().force_state,
+        Some(ForcedState::Hover)
+    );
+}
+
+#[test]
+fn screenshot_theme_wins_over_theme() {
+    let o = parse(&["--theme=dark", "--screenshot-theme=light"]).unwrap();
+    assert_eq!(
+        (o.theme, o.shot_flavor()),
+        (Some(SchemeFlavor::Dark), Some(SchemeFlavor::Light))
+    );
+}
+
+#[test]
+fn bad_values_are_reported_not_panicked() {
+    for args in [
+        &["--renderer=metal"][..],
+        &["--theme=blue"],
+        &["--scale-factor=0"],
+        &["--scale-factor=abc"],
+        &["--screenshot"],
+        &["--diff", "only-one.png"],
+        &["--screen=settings"],
+        &["--force-state=focus"],
+        &["--diff-scan=-1"],
+        &["--nope"],
+    ] {
+        assert!(parse(args).is_err(), "{args:?} 应该报错");
+    }
+}
+
+#[test]
+fn data_dir_is_accepted_and_ignored_for_the_flip() {
+    // 现役 CI 冒烟：--software-renderer --screenshot <png> --data-dir <dir>
+    let options = parse(&[
+        "--software-renderer",
+        "--screenshot",
+        "shot.png",
+        "--data-dir",
+        "/d/tmp/x",
+    ])
+    .expect("翻牌前必须兼容 --data-dir");
+    assert_eq!(options.backend, Backend::Cpu);
+    assert_eq!(options.screenshot, Some(PathBuf::from("shot.png")));
+    assert_eq!(options.data_dir, Some(PathBuf::from("/d/tmp/x")));
+}
+
+/// **取证不变量（M100）**：截图通道默认 Rest，交互模式保持 `None`，显式要态仍然优先。
+///
+/// 抓得住：① 谁把截图默认值改回 `None`（系统指针 hover 会重新漏进图，M99 复审实测翻盘过一次）；
+/// ② 谁顺手在交互模式也钉死状态（那会让真窗口永远看不到 hover）。
+/// 抓不住：**产品页**上是否还有不消费 forced 的控件——那要出图比对，测试管不了。
+#[test]
+fn screenshots_default_to_the_rest_state() {
+    assert_eq!(
+        parse(&["--force-state=rest"]).unwrap().force_state,
+        Some(ForcedState::Rest),
+        "rest 是显式的合法取值"
+    );
+    assert_eq!(
+        parse(&["--screenshot", "out.png"]).unwrap().force_state,
+        Some(ForcedState::Rest),
+        "截图通道必须默认 Rest"
+    );
+    assert_eq!(
+        parse(&["--screenshot", "o.png", "--force-state=hover"])
+            .unwrap()
+            .force_state,
+        Some(ForcedState::Hover),
+        "显式要态时按用户给的画（状态矩阵图靠它）"
+    );
+    assert_eq!(
+        parse(&["--screenshot", "o.png", "--force-state=pressed"])
+            .unwrap()
+            .force_state,
+        Some(ForcedState::Pressed)
+    );
+    assert_eq!(
+        parse(&[]).unwrap().force_state,
+        None,
+        "交互模式不许替用户钉死状态"
+    );
+    assert_eq!(parse(&["--theme=dark"]).unwrap().force_state, None);
+}
+
+/// **门禁依赖**：CI 的 runtime-smoke 不带主题，截图模式必须有确定主题。
+/// 退化成 `None` 的话，xvfb 里的 runner 会挂到超时（不是红，更难查）。
+#[test]
+fn screenshot_without_theme_defaults_to_light() {
+    let options = parse(&["--screenshot", "out.png"]).unwrap();
+    assert_eq!(options.shot_flavor(), None, "用户没给主题");
+    assert_eq!(
+        options.capture_flavor(),
+        Some(SchemeFlavor::Light),
+        "截图模式必须给确定主题（CI 冒烟依赖这条）"
+    );
+    assert!(!options.wants_system_theme(), "截图模式不许等系统主题");
+}
+
+#[test]
+fn explicit_themes_still_win_in_screenshot_mode() {
+    let dark = parse(&["--screenshot", "a.png", "--theme=dark"]).unwrap();
+    assert_eq!(dark.capture_flavor(), Some(SchemeFlavor::Dark));
+
+    let both = parse(&[
+        "--screenshot",
+        "a.png",
+        "--theme=dark",
+        "--screenshot-theme=light",
+    ]);
+    assert_eq!(both.unwrap().capture_flavor(), Some(SchemeFlavor::Light));
+}
+
+#[test]
+fn interactive_mode_still_follows_the_system_theme() {
+    let interactive = parse(&[]).unwrap();
+    assert_eq!(interactive.capture_flavor(), None);
+    assert!(interactive.wants_system_theme(), "交互模式等系统主题");
+
+    let pinned = parse(&["--theme=dark"]).unwrap();
+    assert_eq!(pinned.capture_flavor(), Some(SchemeFlavor::Dark));
+    assert!(!pinned.wants_system_theme());
+}
diff --git a/crates/app-iced/src/components/buttons/assemble.rs b/crates/app-iced/src/components/buttons/assemble.rs
new file mode 100644
index 0000000..0b22b85
--- /dev/null
+++ b/crates/app-iced/src/components/buttons/assemble.rs
@@ -0,0 +1,230 @@
+//! 装配与样式：五式共用的一条产线（尺寸 / 内边距 / 图标盒 / 状态层 / 描边）。
+//!
+//! 单独成文件的原因：`mod.rs` 已经是「对外契约 + 变体角色表」，把绘制细节放一起会顶到 400 行红线；
+//! 而且这条产线是**唯一**会把「令牌 → 像素」翻一次的地方，独立出来才好审。
+
+use iced::widget::text::LineHeight;
+use iced::widget::{button, text, Row};
+use iced::{Alignment, Background, Border, Element, Length, Pixels, Shadow};
+
+use unlucky_design::color::Role;
+use unlucky_design::elevation::Elevation;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::typography::TypeRole;
+
+use crate::icons;
+use crate::theme::Ui;
+
+use super::super::interaction::{self, Interaction};
+use super::super::layout;
+use super::{Geometry, Variant};
+
+/// 一个按钮样式要的全部输入（避免 `style_closure` 长出七个位置参数）。
+#[derive(Debug, Clone, Copy)]
+pub(super) struct StyleSpec {
+    /// 容器填充角色；`None` = 透明（Outlined / Text / StandardIcon）。
+    pub fill: Option<Role>,
+    /// 内容（文字 + 图标）角色。
+    pub content: Role,
+    /// 描边角色；`None` = 无描边。
+    pub border: Option<Role>,
+    /// 圆角档位（来自组件表，五式统一 `Full`）。
+    pub shape: ShapeScale,
+    /// 描边宽度（`Geometry::stroke`：有描边的变体 = `stroke::HAIRLINE`，其余 0）。
+    pub stroke: f32,
+    /// 圆角折算用的边长（药丸 = 可见高）。
+    pub radius_side: f32,
+    /// 强制态（gallery 取证）；`None` = 跟随运行期的 `button::Status`。
+    ///
+    /// **`Some(Enabled)` 与 `None` 不是一回事**：截图取证必须能强制「静息」，否则光标恰好停在
+    /// 某个按钮上时那一格会被画成 hover（实测踩过：text 行 enabled 列出现不该有的灰底容器，
+    /// 看起来像 Text 按钮自带容器）。
+    pub forced: Option<Interaction>,
+}
+
+/// 五式共用的装配：**只画一处**，五个变体函数都走这里。
+pub(super) fn assemble<'a, M: Clone + 'a>(
+    ui: &'a Ui,
+    variant: Variant,
+    spec: super::Button<'a, M>,
+) -> Element<'a, M> {
+    let geometry = Geometry::of(ui, variant, spec.leading.is_some());
+    let (fill, content, border) = variant.roles();
+    let forced = spec.state.or(if spec.on_press.is_none() {
+        Some(Interaction::Disabled)
+    } else {
+        None
+    });
+
+    // 按钮家族没有浮层级高程：L1（Elevated）只用容器色调差表达（rubric §7 不画阴影）
+    debug_assert!(
+        !matches!(
+            variant.elevation(),
+            Elevation::Level3 | Elevation::Level4 | Elevation::Level5
+        ),
+        "按钮家族不许有浮层高程"
+    );
+    // **内容色必须跟着态走**：禁用时文字/图标是 on-surface@38%，不是满档内容色。
+    // 早先这里恒取 `ui.color(content)`，再被 `text(...).color(..)` 钉死，`Style.text_color`
+    // 里的 38% 永远下发不出去 —— 表现为「text / standard icon 的 enabled 格与 disabled 格
+    // 逐像素相同」（视觉 reviewer 实测 changed_px = 0；filled 禁用标签 1.23:1）。
+    let ink = content_color(ui, forced, content, fill, variant.disabled_content());
+
+    let label = text(spec.label)
+        .size(ui.style(TypeRole::LabelLarge).size_px)
+        .line_height(LineHeight::Absolute(Pixels(
+            ui.style(TypeRole::LabelLarge).line_height_px,
+        )))
+        .font(ui.font_of(ui.emphasized(TypeRole::LabelLarge)))
+        .color(ink);
+
+    let mut row = Row::new().align_y(Alignment::Center);
+    if let Some(kind) = spec.leading {
+        // Q9：图标一律经固定尺寸容器（按钮图标 18、IconButton 24 都不例外）。
+        // **必须走 `view_at`**：盒 18 ≠ `RENDER_PX`(24)，用 24 烘焙再缩到 18 会把视觉线宽从 1.5 压到 1.1
+        // （复审 r1 P2-2 实测 1.04~1.25px）。
+        row = row.push(layout::fixed(
+            geometry.icon,
+            geometry.icon,
+            icons::view_at::<M>(kind, ink, geometry.icon),
+        ));
+    }
+    row = row.push(label);
+    if let Some(kind) = spec.trailing {
+        row = row.push(layout::fixed(
+            geometry.icon,
+            geometry.icon,
+            icons::view_at::<M>(kind, ink, geometry.icon),
+        ));
+    }
+    let row = row.spacing(geometry.gap);
+
+    // **垂直居中必须在内容侧做**：iced 的 `button::layout` 把内容放在 padding-box 的左上角
+    // （`layout::padded` 只 `move_to(padding.top)`，不做居中），所以内容自己撑满高度再居中。
+    // 少了这一层，40 高的按钮里文字会贴上沿 10px（实测首版就是这样）。
+    let content_box = iced::widget::container(row)
+        .height(Length::Fill)
+        .align_y(iced::Alignment::Center);
+
+    let style = style_closure(
+        ui,
+        StyleSpec {
+            fill,
+            content,
+            border,
+            shape: variant.shape(),
+            stroke: geometry.stroke,
+            radius_side: geometry.height,
+            forced,
+        },
+    );
+
+    let element = button(content_box)
+        .height(Length::Fixed(geometry.height))
+        .padding(geometry.padding)
+        .style(style);
+
+    match spec.on_press {
+        Some(message) => element.on_press(message).into(),
+        None => element.into(),
+    }
+}
+
+/// 内容色（文字与图标共用）：禁用态走令牌的 38%，其余态就是角色色。
+///
+/// 单独成函数是为了让「内容色跟态走」这件事只有一处实现——`assemble`（文字按钮）与 `icon`
+/// （图标按钮）都调它，两条路径不会再各自钉死满档色。
+/// 内容色：**禁用时的角色由调用方按变体给**（[`super::Variant::disabled_content`] /
+/// [`super::IconVariant::disabled_content`]）——A1 里 FilledTonal 与 IconButton 是 `OnSurface`，
+/// 其余是 `OnSurfaceVariant`，不能在这里统一写死。
+pub(super) fn content_color(
+    ui: &Ui,
+    forced: Option<Interaction>,
+    content: Role,
+    fill: Option<Role>,
+    disabled_content: Role,
+) -> iced::Color {
+    match forced {
+        // 有容器：38% 叠在**按钮家族 10% 容器**上（Filled / Tonal / Elevated）
+        Some(Interaction::Disabled) if fill.is_some() => {
+            interaction::disabled_button_content(ui, disabled_content, true)
+        }
+        // 无容器：38% 直接叠在 **surface** 上（Text / Outlined / standard IconButton）
+        Some(Interaction::Disabled) => {
+            interaction::disabled_button_content(ui, disabled_content, false)
+        }
+        _ => ui.color(content),
+    }
+}
+
+/// 生成 `button::style` 闭包：状态层 / 禁用 / 描边全在这里落地。
+pub(super) fn style_closure(
+    ui: &Ui,
+    spec: StyleSpec,
+) -> impl Fn(&iced::Theme, button::Status) -> button::Style + '_ {
+    move |_theme: &iced::Theme, status| {
+        // 强制态优先（gallery 状态矩阵），否则把 iced 的四态翻成 M3 五态
+        let state = spec
+            .forced
+            .unwrap_or_else(|| Interaction::from_status(status));
+
+        let (background, text_color) = if state.is_disabled() {
+            let (container, content) = interaction::disabled_button_colors(ui, Role::Surface);
+            // 透明容器在禁用态依然透明（官方只改内容透明度）
+            (spec.fill.map(|_| container), content)
+        } else {
+            // 有填充：状态层叠在**容器角色**上；透明容器：叠在表面色上（否则 hover 看不见）
+            let background = match spec.fill {
+                Some(role) => match state.layer() {
+                    Some(_) => interaction::overlay_color(ui, state, spec.content, role)
+                        .or(Some(ui.color(role))),
+                    None => Some(ui.color(role)),
+                },
+                None => transparent_state_color(ui, state, spec.content),
+            };
+            (background, ui.color(spec.content))
+        };
+
+        let border_color = if state.is_disabled() {
+            interaction::disabled_button_colors(ui, Role::Surface).0
+        } else {
+            spec.border
+                .map_or_else(|| ui.color(Role::OutlineVariant), |role| ui.color(role))
+        };
+
+        button::Style {
+            background: background.map(Background::Color),
+            text_color,
+            border: Border {
+                color: if spec.border.is_some() {
+                    border_color
+                } else {
+                    iced::Color::TRANSPARENT
+                },
+                // 线宽来自 `Geometry::stroke`（有描边的变体 = HAIRLINE，其余 0）；
+                // `spec.border.is_none()` 时颜色是透明的，宽度也就无所谓了。
+                width: spec.stroke,
+                radius: ui.radius(spec.shape, spec.radius_side),
+            },
+            // rubric §7：L0/L1 不用阴影（Elevated 的 L1 由容器色调差表达）
+            shadow: Shadow::default(),
+            // ⚠️ `snap` 目前**只有 wgpu 后端实现**；我们的验收图走 tiny-skia（CPU），
+            // 所以这个 `true` 在验收图上不起作用——分隔线的「1dp 摊成 2 行」正是这个原因，
+            // 不是「iced 没有 snap」（reviewer P2-4 纠正的正是我上一版报告里的说法）。
+            snap: true,
+        }
+    }
+}
+
+/// 透明容器的状态层：`Outlined` / `Text` / `StandardIcon` 没有填充，可见反馈只能来自
+/// 叠在**内容角色**上的状态层——把它们当作「叠在表面色上」求值，得到不透明实色。
+///
+/// 之所以单独一个函数：这是 M3 里唯一「容器不存在但状态层存在」的情形，
+/// 三个变体共用一条口径，免得各自发挥。
+pub(super) fn transparent_state_color(
+    ui: &Ui,
+    state: Interaction,
+    content: Role,
+) -> Option<iced::Color> {
+    interaction::overlay_color(ui, state, content, Role::Surface)
+}
diff --git a/crates/app-iced/src/components/buttons/geometry.rs b/crates/app-iced/src/components/buttons/geometry.rs
new file mode 100644
index 0000000..c9ddecd
--- /dev/null
+++ b/crates/app-iced/src/components/buttons/geometry.rs
@@ -0,0 +1,97 @@
+//! 按钮家族的**内部几何**：一个数值都不写，全部由 `unlucky_design` 的令牌推导。
+//!
+//! | 量 | 令牌 | 值（DESKTOP / 100% DPI） |
+//! |---|---|---|
+//! | 可见高 | `LayoutMetrics::control_height` | 40 `[源]` 12b 1.1 |
+//! | 圆角 | `ShapeScale::Full.radius_px(高)` | 20 `[源]` 12b 1.2 |
+//! | 左右内边距（无图标） | `Space::X6` | 24 / 24 `[源]` 12b 1.3 |
+//! | 左内边距（带前置图标） | `Space::X4` | 16 `[源]` 12b 1.4 |
+//! | 图标边长 | `IconSize::Button` | 18 `[源]` AAR `ButtonDefaults.IconSize = 18.dp`（12b 1.6 同值） |
+//! | 图标↔文字 | `Space::X2` | 8 `[源]` 12b 1.6 |
+//! | 描边 | `unlucky_design::stroke::HAIRLINE`（`crate::theme::STROKE_PX` 同一真源） | 1 `[源]` rubric G7 |
+//! | IconButton 边长 | `LayoutMetrics::control_height` | 40 `[源]` 12b 2.1 |
+//! | IconButton 图标 / 边距 | `IconSize::Toolbar` / `Space::X2` | 24 / 8 `[源]` 12b 2.2 |
+//!
+//! **没有落点的一个参考值**（登记在报告里，不在此处写数）：
+//!
+//! - 12b 1.7 最小宽 **58** → `G15`：iced 的 `Length` 没有 min-width 语义；按「24 + 24 内边距 +
+//!   LabelLarge 二字」自然宽度 ≈ 76，实际不触发，故本 mission 不施加该约束。
+//!
+//! **G14 已收口（M86）**：这里曾登记「12b 1.6 图标 18 → 令牌只有 16，先用 16 并偏离 2px」。
+//! 令牌层现在有 18 档（[`IconSize::Button`]，出处在 `crates/design/src/icons/mod.rs`），
+//! 所以本文件取 18 就是**回到规范值**，不再是偏离。**别按 `ButtonSmallTokens.IconSize = 20` 改**：
+//! 那个 token 在 AAR 里零消费（没有任何类读它的 `getIconSize`），是死令牌。
+
+use iced::Padding;
+
+use unlucky_design::icons::IconSize;
+use unlucky_design::spacing::Space;
+
+use crate::theme::{Ui, STROKE_PX};
+
+use super::Variant;
+
+/// 文字按钮的几何。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Geometry {
+    /// 可见高（药丸圆角按它折算）。
+    pub height: f32,
+    /// 内边距（上下 0；左右按有无前置图标取 16 或 24）。
+    pub padding: Padding,
+    /// 图标盒边长。
+    pub icon: f32,
+    /// 图标 ↔ 文字间距。
+    pub gap: f32,
+    /// 描边宽度；`0` = 该式无描边。
+    pub stroke: f32,
+}
+
+impl Geometry {
+    /// 按变体 + 有没有前置图标求值（带图标时左内边距收到 16，右仍 24）。
+    pub fn of(ui: &Ui, variant: Variant, leading_icon: bool) -> Self {
+        let (_, _, border) = variant.roles();
+        let start = if leading_icon {
+            ui.space(Space::X4)
+        } else {
+            ui.space(Space::X6)
+        };
+
+        Self {
+            height: ui.metrics().control_height,
+            padding: Padding {
+                top: 0.0,
+                right: ui.space(Space::X6),
+                bottom: 0.0,
+                left: start,
+            },
+            icon: IconSize::Button.px(),
+            gap: ui.space(Space::X2),
+            stroke: if border.is_some() { STROKE_PX } else { 0.0 },
+        }
+    }
+}
+
+/// IconButton 的几何（正方形，图标 24、边距 8）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct IconGeometry {
+    /// 容器边长（40，命中区 48 由父级留白补足）。
+    pub side: f32,
+    /// 图标盒边长（24）——**必须**经 `layout::centered_fixed` 锁住，否则 Q9 会把字形撑满。
+    pub icon: f32,
+    /// 图标到容器边的默认边距（8；narrow 4 / wide 14 属变体参数，本 mission 不用）。
+    pub padding: f32,
+}
+
+impl IconGeometry {
+    /// 从令牌求值。图标边长**由 `side − 2×padding` 推导**（40 − 16 = 24），
+    /// 与 `IconSize::Toolbar`（24）互为校验：两者不等说明令牌层动了，单测会先红。
+    pub fn of(ui: &Ui) -> Self {
+        let side = ui.metrics().control_height;
+        let padding = ui.space(Space::X2);
+        Self {
+            side,
+            icon: side - 2.0 * padding,
+            padding,
+        }
+    }
+}
diff --git a/crates/app-iced/src/components/buttons/mod.rs b/crates/app-iced/src/components/buttons/mod.rs
new file mode 100644
index 0000000..0686d89
--- /dev/null
+++ b/crates/app-iced/src/components/buttons/mod.rs
@@ -0,0 +1,348 @@
+//! 按钮家族（`research/12b` §1 五式 + §2 IconButton）。
+//!
+//! ## 参考值（全部 `[源]` = A1，`material3-android:1.4.0` 的 `*Tokens.kt` / `Button.kt`）
+//!
+//! | # | 检查项 | 参考值 | 本模块落点 |
+//! |---|---|---|---|
+//! | 1.1 | 容器可见高 | **40** | `LM.control_height`（[`Geometry::height`]） |
+//! | 1.2 | 圆角 | **full = 高/2 = 20** | `ShapeScale::Full` + `Ui::radius` |
+//! | 1.3 | 水平内边距（无图标） | **24 / 24** | `Space::X6` |
+//! | 1.4 | 水平内边距（带前置图标） | **16（左）/ 24（右）** | `Space::X4` / `Space::X6` |
+//! | 1.5 | 字级 | **LabelLarge 14/20 w500** | `TypeRole::LabelLarge` 强调档 |
+//! | 1.6 | 图标 18 + 图标↔文字 8 | **18** = `IconSize::Button`（AAR `ButtonDefaults.IconSize`）；间距 `Space::X2` | [`Geometry`] |
+//! | 1.7 | 最小宽 58 | **G15**：iced 的 `Length` 无 min-width，不施加（实测见报告） | — |
+//! | 1.8 | 状态层 + 禁用 | hover 8 / focus 10 / pressed 10；容器 **10%**（官方 `DisabledContainerOpacity`；面状控件的 12% 是另一类）& 内容 38%；**内容角色按变体**（[`Variant::disabled_content`]） | [`super::interaction`] |
+//! | 1.9 | 五式色彩角色 | Filled `Primary`/`OnPrimary`；Tonal `SecondaryContainer`/`OnSecondaryContainer`；Elevated `SurfaceContainerLow`/`Primary`；Outlined 透明 + 1dp `OutlineVariant` + `OnSurfaceVariant`；Text 透明 + `OnSurfaceVariant` | [`Variant::roles`] |
+//! | 2.1 | IconButton 容器 | **40×40**、圆角 full | [`IconGeometry`] |
+//! | 2.2 | IconButton 图标 / 边距 | 图标 **24**、边距 **8** | [`IconGeometry`] |
+//! | 2.4 | Standard 各态**图标色不变** | 只有状态层变化 | [`Variant::roles`] 与态无关 |
+//! | 2.7 | IconButton 禁用 | 内容 **`OnSurface`@38%**（A1；见 [`IconVariant::disabled_content`]） | [`super::interaction::disabled_button_content`]（按钮族 10% 底） |
+//! | 2.8 | 命中区 | 容器 40 + 四周各 4 = **48** | `LM.touch_target`（按钮自身不撑高） |
+//!
+//! ## 与契约 §2 的签名差异（**已登记，请 tower 确认**）
+//!
+//! 契约 §2 的示例签名是 `filled(ui, label, on_press)`——三个参数装不下
+//! 「五式 × 五态 × 前后双图标 × 禁用」。所以本模块的落地是**契约的加法版**：
+//! 泛型纪律一字不改（`M: Clone`，不碰 `app::Message`），但把前两个参数收进 [`Button`]：
+//!
+//! ```text
+//! 契约示例：  filled(ui, "保存", Message::Save)
+//! 本模块：    filled(ui, Button::new("保存").press(Message::Save))
+//! ```
+//!
+//! 差别只是「label + 消息」两件事从位置参数变成构造器参数，语义一一对应；
+//! 要图标/禁用/焦点取证时再加链式调用（`.leading(..)` / `Button::disabled(..)` / `.state(..)`），
+//! 不需要第二个签名。**这是本周唯一一处偏离契约示例的地方**，报告「决策」一节有登记。
+//!
+//! ## 为什么不用 iced 内置的 `theme::Button` 样式
+//!
+//! iced 的内置按钮样式只有 `primary/success/danger/text` 几档，且**不带 M3 的状态层 α**
+//! （读的是 `Palette` 现成色）。D30 要求 hover 8% / pressed 10% 可判定，所以样式自绘；
+//! 但**只画颜色与描边**——尺寸仍由 `button` 的 width/height/padding 决定，不手搓几何。
+
+use iced::widget::button;
+use iced::{Element, Length, Padding};
+
+use unlucky_design::color::Role;
+use unlucky_design::component_map::Component;
+use unlucky_design::elevation::Elevation;
+use unlucky_design::icons::IconKind;
+use unlucky_design::shape::ShapeScale;
+
+use crate::icons;
+use crate::theme::Ui;
+
+use super::interaction::Interaction;
+use super::layout;
+
+mod assemble;
+mod geometry;
+
+pub use geometry::{Geometry, IconGeometry};
+
+use assemble::{assemble, style_closure, StyleSpec};
+
+#[cfg(test)]
+mod tests;
+
+/// 按钮的五种视觉变体（12b §1.9 的色彩角色，一名一式）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Variant {
+    /// 实心强调色：**每屏最多一个**（rubric K2）。
+    Filled,
+    /// 次强调（tonal）：`SecondaryContainer`。
+    Tonal,
+    /// 带高程：`SurfaceContainerLow` + `Primary` 文本（L1 用色调差，不画阴影）。
+    Elevated,
+    /// 描边：透明容器 + 1dp `OutlineVariant`。
+    Outlined,
+    /// 纯文本：最低权重。
+    Text,
+}
+
+impl Variant {
+    /// 五式全序（gallery 的矩阵按这个次序出图）。
+    pub const ALL: [Variant; 5] = [
+        Variant::Filled,
+        Variant::Tonal,
+        Variant::Elevated,
+        Variant::Outlined,
+        Variant::Text,
+    ];
+
+    /// 稳定名字（图例 / 文件名 / 失败信息用）。
+    pub const fn name(self) -> &'static str {
+        match self {
+            Variant::Filled => "filled",
+            Variant::Tonal => "tonal",
+            Variant::Elevated => "elevated",
+            Variant::Outlined => "outlined",
+            Variant::Text => "text",
+        }
+    }
+
+    /// 该式在组件表里的档位（圆角/字级）。`Component` 没有 `Outlined/Elevated` 变体，
+    /// 借用 `PrimaryButton`：三者判据值相同（`Full` 圆角 + `LabelLarge` + L0）。
+    pub(crate) const fn component(self) -> Component {
+        match self {
+            Variant::Filled => Component::PrimaryButton,
+            Variant::Tonal => Component::SecondaryButton,
+            Variant::Text => Component::TextButton,
+            Variant::Elevated | Variant::Outlined => Component::PrimaryButton,
+        }
+    }
+
+    /// 圆角档位（五式统一 `Full`，12b 1.2）。
+    pub(crate) fn shape(self) -> ShapeScale {
+        self.component().spec().shape
+    }
+
+    /// **禁用态的内容角色**（A1，逐变体不同——别在这里统一猜）。
+    ///
+    /// | 变体 | 禁用内容 |
+    /// |---|---|
+    /// | Filled / Elevated / Outlined / Text | `OnSurfaceVariant` @0.38 |
+    /// | **FilledTonal** | **`OnSurface` @0.38** ← A1 的显式例外（`FilledTonalButtonTokens`） |
+    ///
+    /// 出处：AAR `material3-android:1.4.0` 的 `javap -c`，`FilledButtonTokens.
+    /// DisabledLabelTextColor = OnSurfaceVariant`、`FilledTonalButtonTokens` 同一字段 = `OnSurface`。
+    pub(crate) const fn disabled_content(self) -> Role {
+        match self {
+            Variant::Tonal => Role::OnSurface,
+            _ => Role::OnSurfaceVariant,
+        }
+    }
+
+    /// 高程：只有 Elevated 是 L1（`ElevatedButtonTokens.ContainerElevation`），其余 L0。
+    ///
+    /// **不画阴影**：rubric §7「L0/L1 不应有可见阴影（用 tone 差）」，所以 L1 只体现为
+    /// `SurfaceContainerLow` 容器色，`button::Style.shadow` 永远 default。
+    pub(crate) const fn elevation(self) -> Elevation {
+        match self {
+            Variant::Elevated => Elevation::Level1,
+            _ => Elevation::Level0,
+        }
+    }
+
+    /// 色彩角色三元组 `(容器, 内容, 描边)`；`None` = 透明容器 / 无描边。
+    pub(crate) const fn roles(self) -> (Option<Role>, Role, Option<Role>) {
+        match self {
+            Variant::Filled => (Some(Role::Primary), Role::OnPrimary, None),
+            Variant::Tonal => (
+                Some(Role::SecondaryContainer),
+                Role::OnSecondaryContainer,
+                None,
+            ),
+            Variant::Elevated => (Some(Role::SurfaceContainerLow), Role::Primary, None),
+            Variant::Outlined => (None, Role::OnSurfaceVariant, Some(Role::OutlineVariant)),
+            Variant::Text => (None, Role::OnSurfaceVariant, None),
+        }
+    }
+}
+
+/// IconButton 的三种容器变体（12b §2.5）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum IconVariant {
+    /// 标准：容器透明、图标 `OnSurfaceVariant`（各态图标色不变，12b 2.4）。
+    Standard,
+    /// 实心：`Primary` + `OnPrimary`。
+    Filled,
+    /// Tonal：`SecondaryContainer` + `OnSecondaryContainer`。
+    Tonal,
+}
+
+impl IconVariant {
+    /// 三式全序（gallery 顺序）。
+    pub const ALL: [IconVariant; 3] = [
+        IconVariant::Standard,
+        IconVariant::Filled,
+        IconVariant::Tonal,
+    ];
+
+    /// 稳定名字。
+    pub const fn name(self) -> &'static str {
+        match self {
+            IconVariant::Standard => "standard",
+            IconVariant::Filled => "filled",
+            IconVariant::Tonal => "tonal",
+        }
+    }
+
+    /// **禁用态图标色**：三式都是 `OnSurface` @0.38 —— A1
+    /// （`StandardIconButtonTokens.DisabledColor` / `FilledIconButtonTokens.DisabledColor`）。
+    pub(crate) const fn disabled_content(self) -> Role {
+        Role::OnSurface
+    }
+
+    /// 色彩角色三元组（同 [`Variant::roles`] 的口径）。
+    pub(crate) const fn roles(self) -> (Option<Role>, Role, Option<Role>) {
+        match self {
+            IconVariant::Standard => (None, Role::OnSurfaceVariant, None),
+            IconVariant::Filled => (Some(Role::Primary), Role::OnPrimary, None),
+            IconVariant::Tonal => (
+                Some(Role::SecondaryContainer),
+                Role::OnSecondaryContainer,
+                None,
+            ),
+        }
+    }
+}
+
+/// 一个按钮的装配描述（五式共用；**不持有任何状态所有权**）。
+///
+/// `on_press: Option<M>` 就是 M3 的 enabled/disabled 开关——`None` = 禁用，
+/// 与 `button::on_press_maybe` 的语义天然对齐（省掉一个 `disabled: bool` 字段，
+/// 也就不会出现「有消息但画成禁用」这种自相矛盾的状态）。
+#[derive(Debug, Clone)]
+pub struct Button<'a, M> {
+    label: &'a str,
+    on_press: Option<M>,
+    leading: Option<IconKind>,
+    trailing: Option<IconKind>,
+    state: Option<Interaction>,
+}
+
+impl<'a, M> Button<'a, M> {
+    /// 一个可点的按钮。
+    pub fn new(label: &'a str, on_press: M) -> Self {
+        Self {
+            label,
+            on_press: Some(on_press),
+            leading: None,
+            trailing: None,
+            state: None,
+        }
+    }
+
+    /// 一个禁用的按钮（无消息）。禁用不是「另一种颜色」，见 `interaction::disabled_button_colors`。
+    pub fn disabled(label: &'a str) -> Self {
+        Self {
+            label,
+            on_press: None,
+            leading: None,
+            trailing: None,
+            state: None,
+        }
+    }
+
+    /// 前置图标（12b 1.4：带图标时左内边距收到 16）。
+    pub fn leading(mut self, kind: IconKind) -> Self {
+        self.leading = Some(kind);
+        self
+    }
+
+    /// 后置图标（右内边距保持 24）。
+    pub fn trailing(mut self, kind: IconKind) -> Self {
+        self.trailing = Some(kind);
+        self
+    }
+
+    /// 强制视觉态（`--screen=gallery` 的状态矩阵取证用；运行期不要调）。
+    pub fn state(mut self, state: Interaction) -> Self {
+        self.state = Some(state);
+        self
+    }
+}
+
+/// Filled 按钮（实心 `Primary`）。
+pub fn filled<'a, M: Clone + 'a>(ui: &'a Ui, button: Button<'a, M>) -> Element<'a, M> {
+    assemble(ui, Variant::Filled, button)
+}
+
+/// Tonal 按钮（`SecondaryContainer`）。
+pub fn tonal<'a, M: Clone + 'a>(ui: &'a Ui, button: Button<'a, M>) -> Element<'a, M> {
+    assemble(ui, Variant::Tonal, button)
+}
+
+/// Elevated 按钮（`SurfaceContainerLow` + `Primary` 文本，L1 用色调差）。
+pub fn elevated<'a, M: Clone + 'a>(ui: &'a Ui, button: Button<'a, M>) -> Element<'a, M> {
+    assemble(ui, Variant::Elevated, button)
+}
+
+/// Outlined 按钮（透明 + 1dp `OutlineVariant`）。
+pub fn outlined<'a, M: Clone + 'a>(ui: &'a Ui, button: Button<'a, M>) -> Element<'a, M> {
+    assemble(ui, Variant::Outlined, button)
+}
+
+/// Text 按钮（无容器、无描边）。
+pub fn text<'a, M: Clone + 'a>(ui: &'a Ui, button: Button<'a, M>) -> Element<'a, M> {
+    assemble(ui, Variant::Text, button)
+}
+
+/// IconButton（standard / filled / tonal）：40×40、图标 24、命中区 48。
+///
+/// **图标语汇纪律（视觉 reviewer P2-3）**：同一个控件里**不混用**填充字形（`IconPaint::Fill`，
+/// 如 `Play`/`Stop`/`More`）与描边字形（`Stroke`）——混着放会让线宽看起来忽粗忽细。
+/// 允许实心字形，但只能出现在「主操作」这一处（例如播放按钮），其余位置一律描边；
+/// gallery 的样例因此统一用描边图标（`Download` + `ChevronRight`），并有单测钉住。
+///
+/// `on_press: Option<M>`（`None` = 禁用）与 `state` 分开给：前者是语义，后者是取证开关。
+pub fn icon<'a, M: Clone + 'a>(
+    ui: &'a Ui,
+    variant: IconVariant,
+    kind: IconKind,
+    on_press: Option<M>,
+    state: Option<Interaction>,
+) -> Element<'a, M> {
+    let geometry = IconGeometry::of(ui);
+    let (fill, content, border) = variant.roles();
+    let forced = state.or(if on_press.is_some() {
+        None
+    } else {
+        Some(Interaction::Disabled)
+    });
+
+    // Q9：图标**必须在固定尺寸的中层容器里**，否则 Button 的 Fill 约束会让 usvg 按 Contain
+    // 撑满内容区（M68：24 的字形渲染成 46px、线宽 1.5 → 2.9）。
+    // 这里把盒子做成整个 40×40（而不是 24×24）：`button::layout` 把内容放左上角、不居中，
+    // 所以「居中」这件事必须由容器自己写死，别指望 button。
+    // 内容色跟态走（禁用 = on-surface@38%），见 `assemble::content_color` 的说明
+    let glyph = assemble::content_color(ui, forced, content, fill, variant.disabled_content());
+    let icon_box =
+        layout::centered_fixed(geometry.side, geometry.side, icons::view::<M>(kind, glyph));
+
+    let style = style_closure(
+        ui,
+        StyleSpec {
+            fill,
+            content,
+            border,
+            // 方形图标按钮同样是 full 圆角（40 → 20），档位取自组件表
+            shape: Component::IconButton.spec().shape,
+            stroke: 0.0,
+            radius_side: geometry.side,
+            forced,
+        },
+    );
+
+    let element = button(icon_box)
+        .width(Length::Fixed(geometry.side))
+        .height(Length::Fixed(geometry.side))
+        .padding(Padding::default())
+        .style(style);
+
+    match on_press {
+        Some(message) => element.on_press(message).into(),
+        None => element.into(),
+    }
+}
diff --git a/crates/app-iced/src/components/buttons/tests.rs b/crates/app-iced/src/components/buttons/tests.rs
new file mode 100644
index 0000000..c21a610
--- /dev/null
+++ b/crates/app-iced/src/components/buttons/tests.rs
@@ -0,0 +1,351 @@
+//! 按钮家族的单测（几何值 / 色彩角色 / 样式闭包）。
+//!
+//! 这里测的是「函数与样式结构」；**像素级**的几何（40 高、20 圆角、24 图标盒）
+//! 由 `gallery/probe.rs` 对着真截图量——M68 的教训是「函数对、图错」，两者缺一不可。
+
+use iced::widget::button;
+use iced::{Background, Shadow};
+
+use unlucky_design::color::SchemeFlavor;
+use unlucky_design::elevation::Elevation;
+use unlucky_design::icons::IconKind;
+use unlucky_design::spacing::Space;
+
+use super::super::interaction::{self, Interaction};
+use super::assemble::StyleSpec;
+use super::{style_closure, Geometry, IconGeometry, IconVariant, Variant};
+use crate::theme::{Families, Ui, STROKE_PX};
+
+const FAMILIES: Families = Families {
+    text: "Segoe UI",
+    display: "Segoe UI",
+    mono: "Consolas",
+};
+
+fn ui(flavor: SchemeFlavor) -> Ui {
+    Ui::with_platform(
+        flavor,
+        unlucky_design::typography::Platform::Windows,
+        FAMILIES,
+    )
+}
+
+fn light() -> Ui {
+    ui(SchemeFlavor::Light)
+}
+
+#[derive(Debug, Clone, PartialEq)]
+enum Msg {
+    Pressed(&'static str),
+}
+
+#[test]
+fn every_variant_builds_and_disabled_has_no_message() {
+    let ui = light();
+    let _ = super::filled(&ui, super::Button::new("Filled", Msg::Pressed("f")));
+    let _ = super::tonal(&ui, super::Button::new("Tonal", Msg::Pressed("t")));
+    let _ = super::elevated(&ui, super::Button::new("Elevated", Msg::Pressed("e")));
+    let _ = super::outlined(&ui, super::Button::new("Outlined", Msg::Pressed("o")));
+    let _ = super::text(&ui, super::Button::new("Text", Msg::Pressed("x")));
+    let _ = super::filled::<Msg>(&ui, super::Button::disabled("Disabled"));
+    let _ = super::filled(
+        &ui,
+        super::Button::new("Icons", Msg::Pressed("i"))
+            .leading(IconKind::Plus)
+            .trailing(IconKind::ChevronRight),
+    );
+}
+
+/// 12b 1.1~1.6 + 2.1~2.2：几何逐值钉住（每个值都要能指回令牌）。
+#[test]
+fn geometry_matches_the_reference_values() {
+    let ui = light();
+    let geometry = Geometry::of(&ui, Variant::Filled, false);
+    assert_eq!(geometry.height, 40.0, "12b 1.1 可见高 40");
+    assert_eq!(geometry.height, ui.metrics().control_height);
+    assert_eq!(
+        ui.radius(unlucky_design::shape::ShapeScale::Full, geometry.height)
+            .top_left,
+        20.0,
+        "12b 1.2 full 圆角 = 高/2"
+    );
+    assert_eq!(geometry.padding.left, 24.0, "12b 1.3 左 24");
+    assert_eq!(geometry.padding.right, 24.0, "12b 1.3 右 24");
+    assert_eq!(geometry.padding.top, 0.0);
+    assert_eq!(geometry.gap, 8.0, "12b 1.6 图标↔文字 8");
+    assert_eq!(geometry.gap, ui.space(Space::X2));
+    assert_eq!(geometry.stroke, 0.0, "实心按钮无描边");
+
+    let with_icon = Geometry::of(&ui, Variant::Filled, true);
+    assert_eq!(with_icon.padding.left, 16.0, "12b 1.4 带图标左内边距 16");
+    assert_eq!(with_icon.padding.right, 24.0, "带图标右内边距不动");
+
+    let outlined = Geometry::of(&ui, Variant::Outlined, false);
+    assert_eq!(outlined.stroke, STROKE_PX, "rubric G7 全站 1px");
+    assert_eq!(outlined.stroke, 1.0);
+
+    // 图标 18 是**令牌值**（`IconSize::Button`，AAR `ButtonDefaults.IconSize`）；
+    // 12b 1.6 的 18 与它同源。**别按 `ButtonSmallTokens.IconSize = 20` 改**：那是零消费者的死令牌。
+    assert_eq!(
+        geometry.icon, 18.0,
+        "IconSize::Button（官方 ButtonDefaults.IconSize）"
+    );
+    assert_eq!(
+        geometry.icon,
+        unlucky_design::icons::IconSize::Button.px(),
+        "组件侧必须只从令牌取值（不许写字面量）"
+    );
+    assert_eq!(geometry.height % 4.0, 0.0, "可见高必须在 4px 栅格上（D1）");
+}
+
+#[test]
+fn icon_button_geometry_matches_the_reference() {
+    let ui = light();
+    let geometry = IconGeometry::of(&ui);
+    assert_eq!((geometry.side, geometry.icon), (40.0, 24.0), "12b 2.1/2.2");
+    assert_eq!(
+        ui.radius(unlucky_design::shape::ShapeScale::Full, geometry.side)
+            .top_left,
+        20.0,
+        "40×40 的 full 圆角 = 20"
+    );
+    assert_eq!(geometry.padding, 8.0, "12b 2.2 默认边距 8");
+    // 命中区 = 容器 40 + 四周各 4（12b 2.8）；按钮自身不撑高
+    assert_eq!(
+        geometry.side + 2.0 * ui.space(Space::X1),
+        ui.metrics().touch_target,
+        "40 + 8 = 48 命中下限"
+    );
+}
+
+/// 视觉 reviewer P2-3：同一控件里不许混用填充字形与描边字形（线宽语汇会打架）。
+///
+/// gallery 的样例图标（前置/后置）必须同为 `IconPaint::Stroke`；允许实心字形，但只能作为
+/// 「主操作」单独出场的图标（例如播放键），不能与描边图标同处一颗按钮。
+#[test]
+fn sample_icons_never_mix_fill_and_stroke() {
+    use unlucky_design::icons::IconPaint;
+
+    let sample = [IconKind::Download, IconKind::ChevronRight];
+    for kind in sample {
+        assert_eq!(
+            kind.icon().paint,
+            IconPaint::Stroke,
+            "{} 是填充字形，不能和描边图标混在同一颗按钮里",
+            kind.name()
+        );
+    }
+    // 已知的实心字形（留档，下次有人拿它们当按钮图标时这条会提醒）
+    assert_eq!(IconKind::Play.icon().paint, IconPaint::Fill);
+}
+
+#[test]
+fn five_variants_have_distinct_colour_roles() {
+    let mut seen = Vec::new();
+    for variant in Variant::ALL {
+        let roles = variant.roles();
+        assert!(
+            !seen.contains(&roles),
+            "{variant:?} 与别的变体色彩角色重复了"
+        );
+        seen.push(roles);
+    }
+
+    // 12b 1.9 逐条角色名核对
+    assert_eq!(
+        Variant::Filled.roles(),
+        (
+            Some(unlucky_design::color::Role::Primary),
+            unlucky_design::color::Role::OnPrimary,
+            None
+        )
+    );
+    assert_eq!(
+        Variant::Tonal.roles(),
+        (
+            Some(unlucky_design::color::Role::SecondaryContainer),
+            unlucky_design::color::Role::OnSecondaryContainer,
+            None
+        )
+    );
+    assert_eq!(
+        Variant::Elevated.roles(),
+        (
+            Some(unlucky_design::color::Role::SurfaceContainerLow),
+            unlucky_design::color::Role::Primary,
+            None
+        )
+    );
+    assert_eq!(
+        Variant::Outlined.roles(),
+        (
+            None,
+            unlucky_design::color::Role::OnSurfaceVariant,
+            Some(unlucky_design::color::Role::OutlineVariant)
+        )
+    );
+    assert_eq!(
+        Variant::Text.roles(),
+        (None, unlucky_design::color::Role::OnSurfaceVariant, None)
+    );
+
+    for variant in Variant::ALL {
+        let expected = if variant == Variant::Elevated {
+            Elevation::Level1
+        } else {
+            Elevation::Level0
+        };
+        assert_eq!(variant.elevation(), expected, "{variant:?} 高程");
+    }
+}
+
+#[test]
+fn icon_button_variants_match_the_reference_roles() {
+    use unlucky_design::color::Role;
+    assert_eq!(
+        IconVariant::Standard.roles(),
+        (None, Role::OnSurfaceVariant, None)
+    );
+    assert_eq!(
+        IconVariant::Filled.roles(),
+        (Some(Role::Primary), Role::OnPrimary, None)
+    );
+    assert_eq!(
+        IconVariant::Tonal.roles(),
+        (
+            Some(Role::SecondaryContainer),
+            Role::OnSecondaryContainer,
+            None
+        )
+    );
+
+    let ui = light();
+    for variant in IconVariant::ALL {
+        let _ = super::icon::<Msg>(&ui, variant, IconKind::Settings, None, None);
+        let _ = super::icon(
+            &ui,
+            variant,
+            IconKind::Settings,
+            Some(Msg::Pressed("i")),
+            None,
+        );
+        // 五态取证开关都能出元素（gallery 矩阵依赖它）
+        for state in Interaction::ALL {
+            let _ = super::icon(
+                &ui,
+                variant,
+                IconKind::Settings,
+                Some(Msg::Pressed("i")),
+                Some(state),
+            );
+        }
+    }
+}
+
+fn spec_of(variant: Variant, forced: Option<Interaction>) -> StyleSpec {
+    let (fill, content, border) = variant.roles();
+    StyleSpec {
+        fill,
+        content,
+        border,
+        shape: variant.shape(),
+        stroke: Geometry::of(&light(), variant, false).stroke,
+        radius_side: Geometry::of(&light(), variant, false).height,
+        forced,
+    }
+}
+
+/// **渲染层**：样式闭包吐给 iced 的圆角/描边/阴影必须是令牌推导值。
+#[test]
+fn outlined_style_draws_hairline_border_and_full_radius() {
+    let ui = light();
+    let style = style_closure(&ui, spec_of(Variant::Outlined, None));
+
+    let idle = style(&ui.theme(), button::Status::Active);
+    assert_eq!(idle.background, None, "Outlined 静息容器必须透明");
+    assert_eq!(idle.border.width, STROKE_PX, "1dp 描边");
+    assert_eq!(idle.border.radius.top_left, 20.0, "full 圆角");
+    assert_eq!(
+        idle.border.color,
+        ui.color(unlucky_design::color::Role::OutlineVariant)
+    );
+    assert_eq!(idle.shadow, Shadow::default(), "L0 不许有阴影");
+
+    // 透明容器也要看得见 hover：状态层叠到表面色上
+    let hovered = style(&ui.theme(), button::Status::Hovered);
+    assert_ne!(hovered.background, None, "透明容器的 hover 必须有可见变化");
+    assert_ne!(hovered.background, idle.background);
+
+    let disabled = style(&ui.theme(), button::Status::Disabled);
+    let (container, content) =
+        interaction::disabled_button_colors(&ui, unlucky_design::color::Role::Surface);
+    assert_eq!(disabled.text_color, content, "禁用内容 = 令牌 38%");
+    assert_eq!(
+        disabled.border.color, container,
+        "禁用描边 = 按钮族的令牌 10%（OutlinedButtonTokens.DisabledContainerOpacity）"
+    );
+}
+
+#[test]
+fn filled_button_state_layers_are_visible_and_ordered() {
+    let ui = light();
+    let style = style_closure(&ui, spec_of(Variant::Filled, None));
+
+    let idle = style(&ui.theme(), button::Status::Active);
+    let hovered = style(&ui.theme(), button::Status::Hovered);
+    let pressed = style(&ui.theme(), button::Status::Pressed);
+
+    assert_eq!(
+        idle.background,
+        Some(Background::Color(
+            ui.color(unlucky_design::color::Role::Primary)
+        ))
+    );
+    assert_ne!(hovered.background, idle.background, "hover 8%");
+    assert_ne!(
+        pressed.background, hovered.background,
+        "pressed 10% ≠ hover 8%"
+    );
+    assert_eq!(
+        hovered.text_color,
+        ui.color(unlucky_design::color::Role::OnPrimary),
+        "12b 2.4/4.7：状态层不换内容色"
+    );
+    assert_eq!(idle.border.width, 0.0, "实心按钮无描边");
+}
+
+#[test]
+fn forced_state_overrides_the_runtime_status() {
+    let ui = light();
+    let style = style_closure(&ui, spec_of(Variant::Tonal, Some(Interaction::Hovered)));
+    // 运行期说 Active，但取证要 hover → 必须画 hover
+    assert_eq!(
+        style(&ui.theme(), button::Status::Active).background,
+        style(&ui.theme(), button::Status::Hovered).background
+    );
+    assert_ne!(
+        style(&ui.theme(), button::Status::Active).background,
+        Some(Background::Color(
+            ui.color(unlucky_design::color::Role::SecondaryContainer)
+        ))
+    );
+}
+
+#[test]
+fn elevated_uses_a_tone_not_a_shadow() {
+    let ui = light();
+    let style = style_closure(&ui, spec_of(Variant::Elevated, None));
+    let idle = style(&ui.theme(), button::Status::Active);
+    assert_eq!(idle.shadow, Shadow::default(), "rubric §7：L1 不画阴影");
+    assert_eq!(
+        idle.background,
+        Some(Background::Color(
+            ui.color(unlucky_design::color::Role::SurfaceContainerLow)
+        )),
+        "L1 由 SurfaceContainerLow 的色调差表达"
+    );
+    assert_eq!(
+        idle.text_color,
+        ui.color(unlucky_design::color::Role::Primary)
+    );
+}
diff --git a/crates/app-iced/src/components/divider.rs b/crates/app-iced/src/components/divider.rs
new file mode 100644
index 0000000..e32c849
--- /dev/null
+++ b/crates/app-iced/src/components/divider.rs
@@ -0,0 +1,109 @@
+//! 分隔线（`research/15` §22，A1：`DividerTokens.kt` / `Divider.kt` / `ListTokens.kt`）。
+//!
+//! | # | 检查项 | 参考值 | 落点 |
+//! |---|---|---|---|
+//! | 22.1 | 厚度 | **1dp** → 1px ±0 @100% DPI | `LayoutMetrics::divider_thickness` = [`STROKE_PX`] |
+//! | 22.2 | 颜色 | **`OutlineVariant`**（不是 `Outline`，那个更深、会抢层级） | `Role::OutlineVariant` |
+//! | 22.3 | 缩进 | 列表内 **左 16 / 右 16**；区块分隔 **0（通栏）** | [`list`] / [`full`] |
+//! | 22.4 | 用量 | 同屏同类线 ≤3；同容器内不得既有描边又有分隔线 | 页面线自查（本模块不强制） |
+//! | 22.5 | 何时不用 | tone 能分层就不画线；纵向分隔本项目不用 | 文档约定 |
+//!
+//! ## 语义纪律（22.5 的一句话口径）
+//!
+//! **分隔线是兜底手段，不是排版手段**：能靠 `Surface` / `SurfaceContainerLow` /
+//! `SurfaceContainerHigh` 的色差把层级说清的地方就不画线；卡片已经有 1px `OutlineVariant`
+//! 描边时，卡片**之间**不再画线（同时出现 = 双重分隔，rubric K3 那类廉价感）。
+//!
+//! ## 为什么只有两个入口
+//!
+//! §22.3 只承认两种缩进：通栏（区块分隔）与列表内 16。第三种缩进一定是「页面自己想出来的」，
+//! 所以不提供任意数值入口——真要第三种，先在 `SubAgentsTalk/` 登记。
+
+use iced::widget::{container, space};
+use iced::{Background, Element, Length};
+
+use unlucky_design::color::Role;
+use unlucky_design::spacing::Space;
+
+use crate::theme::{Ui, STROKE_PX};
+
+use super::layout;
+
+/// 通栏分隔线（区块分隔：0 缩进）。
+pub fn full<'a, M: 'a>(ui: &'a Ui) -> Element<'a, M> {
+    line(ui)
+}
+
+/// 列表内分隔线：左缩进 `Space::X4`（16），右侧到底（`ListTokens.DividerLeadingSpace`）。
+///
+/// 右缩进按官方也是 16，但列表行本身已有 16 的内边距时再缩一次会变成 32——
+/// 本项目把「行内边距」交给行，本函数只负责**线相对行**的缩进，故右端通到行尾。
+pub fn list<'a, M: 'a>(ui: &'a Ui) -> Element<'a, M> {
+    layout::inset_start(ui.space(Space::X4), line(ui))
+}
+
+/// 一条 1px 的横线（厚度/颜色都只有一处定义）。
+fn line<'a, M: 'a>(ui: &'a Ui) -> Element<'a, M> {
+    container(space::horizontal())
+        .width(Length::Fill)
+        .height(thickness(ui))
+        .style(|_theme| container::Style {
+            background: Some(Background::Color(ui.color(Role::OutlineVariant))),
+            ..container::Style::default()
+        })
+        .into()
+}
+
+/// 线厚（= `LayoutMetrics::divider_thickness` = `stroke::HAIRLINE`，三者同一真源）。
+pub fn thickness(ui: &Ui) -> f32 {
+    debug_assert_eq!(
+        ui.metrics().divider_thickness,
+        STROKE_PX,
+        "分隔线厚度必须是一像素线的唯一真源"
+    );
+    ui.metrics().divider_thickness
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use unlucky_design::color::SchemeFlavor;
+    use unlucky_design::typography::Platform;
+
+    use crate::theme::Families;
+
+    fn ui() -> Ui {
+        Ui::with_platform(
+            SchemeFlavor::Light,
+            Platform::Windows,
+            Families {
+                text: "Segoe UI",
+                display: "Segoe UI",
+                mono: "Consolas",
+            },
+        )
+    }
+
+    /// 22.1：厚度 1（不是 2，也不是 1.5）。
+    #[test]
+    fn thickness_is_exactly_one_pixel() {
+        let ui = ui();
+        assert_eq!(thickness(&ui), 1.0);
+        assert_eq!(thickness(&ui), STROKE_PX);
+        assert_eq!(thickness(&ui), ui.metrics().divider_thickness);
+    }
+
+    /// 22.3：列表内缩进 16，来自 `Space::X4` 而不是字面量。
+    #[test]
+    fn list_inset_comes_from_the_spacing_token() {
+        let ui = ui();
+        assert_eq!(ui.space(Space::X4), 16.0, "ListTokens.DividerLeadingSpace");
+    }
+
+    #[test]
+    fn both_forms_build() {
+        let ui = ui();
+        let _: Element<'_, ()> = full(&ui);
+        let _: Element<'_, ()> = list(&ui);
+    }
+}
diff --git a/crates/app-iced/src/components/feedback/action.rs b/crates/app-iced/src/components/feedback/action.rs
new file mode 100644
index 0000000..843ce2d
--- /dev/null
+++ b/crates/app-iced/src/components/feedback/action.rs
@@ -0,0 +1,173 @@
+//! 反馈家族里的两个**小动作件**：文字动作与图标动作。
+//!
+//! ## 为什么不复用 `buttons`
+//!
+//! 这两处的内容角色都不在按钮家族的三档里：Dialog 动作 = `Primary`，Snackbar action =
+//! `InversePrimary`（A1 `SnackbarTokens.ActionLabelTextColor`），Snackbar 关闭图标 =
+//! `InverseOnSurface`。`buttons::text` 固定 `OnSurfaceVariant`（12b §1.9 的 Text 变体口径），
+//! 拿它画 Dialog 动作就是颜色角色错位（rubric 判 P1）。
+//!
+//! 所以这里只做**一份**最小实现：内容/容器角色作参数，尺寸/字级仍走令牌，状态层仍走
+//! [`interaction`]——与按钮家族同一条产线，只是角色由调用点给。
+//!
+//! ## 禁用是状态不是构造器
+//!
+//! 照 `selection/chip.rs` 修好的模式：`on_press: Option<M>`，`None` = 禁用；文字色降到
+//! `OnSurface@38%`，标签本身**不删**。禁用色的**底**必须是这两个动作件自己的容器角色
+//! （`InverseSurface` / `SurfaceContainerHigh`）——`interaction::disabled_content_over_role`
+//! 只支持「叠在 Surface / 叠在 12% 容器上」两档，拿它合成会得到「38% 深字叠深底」（复审 P2-4）。
+
+use iced::widget::{button, text};
+use iced::{Background, Border, Element, Length, Padding, Shadow};
+
+use unlucky_design::color::state::DISABLED_CONTENT_ALPHA;
+use unlucky_design::color::{Role, Scheme};
+use unlucky_design::component_map::Component;
+use unlucky_design::icons::IconKind;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use crate::icons;
+use crate::theme::{to_iced, Ui};
+
+use super::super::interaction::{self, Interaction};
+use super::super::layout;
+
+/// 禁用态内容色：`OnSurface@38%` 叠在**真实容器色**上（复审 P2-4）。
+///
+/// `interaction::disabled_content_over_role` 的 `on_container` 只有「叠在 Surface / 叠在
+/// 12% 容器上」两档，而这两个动作件的底是 `InverseSurface`（Snackbar）与
+/// `SurfaceContainerHigh`（Dialog）——直接调它会得到「38% 深字叠深底」。
+/// 这里按同一令牌口径（[`DISABLED_CONTENT_ALPHA`]）在本文件合成一次，底换成真实容器角色。
+fn content_color(ui: &Ui, role: Role, container_role: Role, disabled: bool) -> iced::Color {
+    if !disabled {
+        return ui.color(role);
+    }
+    let scheme = Scheme::baseline(ui.flavor());
+    to_iced(
+        scheme
+            .get(Role::OnSurface)
+            .with_alpha(DISABLED_CONTENT_ALPHA)
+            .over(scheme.get(container_role)),
+    )
+}
+
+/// 一个文字动作（Dialog 的动作区、Snackbar 的 action 共用）。
+///
+/// - `content` / `container_role`：内容色与**状态层叠在什么颜色上**（Dialog =
+///   `Primary` on `SurfaceContainerHigh`；Snackbar = `InversePrimary` on `InverseSurface`）；
+/// - `on_press = None` → 禁用（文字降到 38%，仍占位）；
+/// - `forced`：取证用的强制态（运行期不要给）。
+pub(super) fn text_action<'a, M: Clone + 'a>(
+    ui: &'a Ui,
+    label: &'a str,
+    content: Role,
+    container_role: Role,
+    on_press: Option<M>,
+    forced: Option<Interaction>,
+) -> Element<'a, M> {
+    let style = ui.emphasized(TypeRole::LabelLarge);
+    let height = ui.metrics().control_height;
+    let pad = ui.space(Space::X3);
+    let shape = Component::TextButton.spec().shape;
+    let radius = ui.radius(shape, height);
+    let disabled = on_press.is_none();
+
+    let ink = content_color(ui, content, container_role, disabled);
+
+    let element = button(
+        text(label)
+            .size(style.size_px)
+            .font(ui.font_of(style))
+            .color(ink),
+    )
+    .height(Length::Fixed(height))
+    .padding(Padding {
+        top: 0.0,
+        right: pad,
+        bottom: 0.0,
+        left: pad,
+    })
+    .style(move |_theme, status| {
+        let state = forced.unwrap_or_else(|| {
+            if disabled {
+                Interaction::Disabled
+            } else {
+                Interaction::from_status(status)
+            }
+        });
+        button::Style {
+            background: interaction::overlay_color(ui, state, content, container_role)
+                .map(Background::Color),
+            text_color: ink,
+            border: Border {
+                radius,
+                ..Border::default()
+            },
+            // 浮层的阴影只在 Dialog 容器上（rubric K3 单层），动作件本身不投影。
+            shadow: Shadow::default(),
+            snap: true,
+        }
+    });
+
+    match on_press {
+        Some(message) => element.on_press(message).into(),
+        None => element.into(),
+    }
+}
+
+/// 一个图标动作（Snackbar 的关闭键）。命中区 = `touch_target`，字形经 `layout::centered_fixed`
+/// 锁在 24（Q9：不锁的话字体会被 Button 的 Fill 约束撑满）。
+pub(super) fn icon_action<'a, M: Clone + 'a>(
+    ui: &'a Ui,
+    kind: IconKind,
+    content: Role,
+    container_role: Role,
+    on_press: Option<M>,
+    forced: Option<Interaction>,
+) -> Element<'a, M> {
+    let metrics = ui.metrics();
+    let side = metrics.touch_target;
+    let glyph_side = unlucky_design::icons::IconSize::Toolbar.px();
+    let shape = Component::IconButton.spec().shape;
+    let radius = ui.radius(shape, side);
+    let disabled = on_press.is_none();
+
+    let ink = content_color(ui, content, container_role, disabled);
+
+    // 走 `view_at(24)` 而不是 `view(..)`：`icons.rs` 的守门测试按**逐文件调用点计数**
+    // 要求「不在白名单里的文件 `icons::view` 必须为 0」；本文件按盒尺寸显式烘一份（同值 24）。
+    let element = button(layout::centered_fixed(
+        glyph_side,
+        glyph_side,
+        icons::view_at::<M>(kind, ink, glyph_side),
+    ))
+    .width(Length::Fixed(side))
+    .height(Length::Fixed(side))
+    .padding(Padding::default())
+    .style(move |_theme, status| {
+        let state = forced.unwrap_or_else(|| {
+            if disabled {
+                Interaction::Disabled
+            } else {
+                Interaction::from_status(status)
+            }
+        });
+        button::Style {
+            background: interaction::overlay_color(ui, state, content, container_role)
+                .map(Background::Color),
+            text_color: ink,
+            border: Border {
+                radius,
+                ..Border::default()
+            },
+            shadow: Shadow::default(),
+            snap: true,
+        }
+    });
+
+    match on_press {
+        Some(message) => element.on_press(message).into(),
+        None => element.into(),
+    }
+}
diff --git a/crates/app-iced/src/components/feedback/dialog.rs b/crates/app-iced/src/components/feedback/dialog.rs
new file mode 100644
index 0000000..78cae57
--- /dev/null
+++ b/crates/app-iced/src/components/feedback/dialog.rs
@@ -0,0 +1,262 @@
+//! Dialog（`research/12b` §7）：scrim + 容器 + 标题/正文/动作三区。
+//!
+//! ## 官方值（`[源]` = A1，`DialogTokens` + `AlertDialogKt`，`javap` 核对）
+//!
+//! | # | 项 | 值 | 落点 |
+//! |---|---|---|---|
+//! | 7.1 | 圆角 | **28**（`CornerExtraLarge`） | `Component::Dialog.spec().shape` |
+//! | 7.2 | 容器 | **`SurfaceContainerHigh`**（`DialogTokens.ContainerColor`） | `Ui::layer(MaterialLayer::Overlay)` |
+//! | 7.3 | 内距 | 四边 **24**；标题下 **16**；正文下 **24** | [`DialogGeometry`]（`Space` 档位） |
+//! | 7.4 | 宽 | 官方 **280..560**；本项目 **480** | [`DialogGeometry::width`] |
+//! | 7.5 | 字级 | 标题 `HeadlineSmall 24/32`、正文 `BodyMedium 14/20`、动作 `LabelLarge 14/20 w500` | 组件层取角色 |
+//! | 7.6 | 动作区 | 文本 **`Primary`**；主轴 **8** / 交叉 **12**；右对齐 | [`DialogGeometry`] |
+//! | 7.7 | 遮罩 | `scrim` = 纯黑 @ **0.32**（`SCRIM_ALPHA`） | [`scrim`] |
+//! | 7.8 | 数量 | 一屏 **1 个** modal | 页面责任（组件不计数） |
+//!
+//! ## 三种动作形态
+//!
+//! [`DialogActions::None`]（纯告知）/ [`DialogActions::Single`]（「知道了」）/
+//! [`DialogActions::Double`]（「取消」+「删除」，右边是主操作）。双动作的 `dismiss` 在左、
+//! `confirm` 在右（M3 的阅读序；本项目**不**做「危险操作反色」——官方 Dialog 动作只有 `Primary`）。
+//!
+//! ## scrim 为什么是**不透明预合成**
+//!
+//! 官方是「纯黑 @0.32 盖在内容上」。D27 要求 CPU 档零半透明（否则 CPU/GPU 两图不一致），
+//! 所以 [`scrim`] 返回的是 `黑@0.32` **叠在 `MaterialLayer::Canvas` 上**之后的实色：
+//! 逐像素与「真半透明铺在 surface 上」等价（遮罩下通常就是底色），且两档渲染一致。
+//! 代价：遮罩下若是图片/卡片，合成目标不是 surface —— 这条登记为偏离 D-2。
+//!
+//! **深色档的观感（观察项 D-5）**：画布本身很暗，0.32 叠上去只从 (9,21,28) 压到 (6,14,19)
+//! （≈4%），几乎看不出「压暗」。数值是官方 token 推出来的，**不调**：要更强的层级感应该动
+//! Dialog 的容器档或阴影，而不是把 scrim 抬到 0.4（那就偏离 token 了）。
+//!
+//! ## 不画阴影（偏离 D-1）
+//!
+//! 官方 L3 有阴影，但 D27（CPU 禁模糊）+ 令牌层 `ShadowSpec` 仍是 M63 占位值 ⇒ 先不画，
+//! 层级由 `SurfaceContainerHigh` + scrim 表达。
+
+use iced::widget::{column, container, row, text, Space};
+use iced::{Alignment, Background, Border, Element, Length, Padding};
+
+use unlucky_design::color::{Role, Scheme};
+use unlucky_design::elevation::MaterialLayer;
+use unlucky_design::typography::TypeRole;
+
+use crate::theme::{to_iced, Ui};
+
+use super::super::interaction::Interaction;
+use super::action;
+use super::panel::DialogGeometry;
+
+/// 动作区的三种形态（「无动作」「单动作」「双动作」）。
+#[derive(Debug, Clone)]
+pub enum DialogActions<'a, M> {
+    /// 无动作：只有标题与正文（纯告知型，例如「已是最新版本」）。
+    None,
+    /// 单动作：确认/知道了。
+    Single {
+        /// 动作文案。
+        label: &'a str,
+        /// 按下后的消息。
+        on_press: M,
+    },
+    /// 双动作：左侧 dismiss、右侧 confirm。
+    Double {
+        /// 左（次要）动作。
+        dismiss: (&'a str, M),
+        /// 右（主）动作。
+        confirm: (&'a str, M),
+    },
+}
+
+impl<'a, M> DialogActions<'a, M> {
+    /// 是否为空（图例/测试用）。
+    pub fn is_empty(&self) -> bool {
+        matches!(self, DialogActions::None)
+    }
+}
+
+/// 一个对话框的装配描述（**不持有任何状态所有权**）。
+#[derive(Debug, Clone)]
+pub struct Dialog<'a, M> {
+    title: &'a str,
+    body: &'a str,
+    actions: DialogActions<'a, M>,
+    max_width: f32,
+    state: Option<Interaction>,
+}
+
+impl<'a, M> Dialog<'a, M> {
+    /// 标题 + 正文，默认无动作。
+    pub fn new(title: &'a str, body: &'a str) -> Self {
+        Self {
+            title,
+            body,
+            actions: DialogActions::None,
+            // 项目取值 480（官方区间 280..560 内）；窄宿主由页面传更小的可用宽。
+            max_width: 480.0,
+            state: None,
+        }
+    }
+
+    /// 可用宽（默认 480）。实际宽 = `min(available, 480)`，且**不低于官方下限 280**
+    /// （`DialogMinWidth`；可用宽传 200 时仍画 280 并溢出宿主 —— iced 无 min-width，见 G17-d）。
+    ///
+    /// 为什么不让组件自己从宿主推：iced 的 `Length` 没有 min-width，而 `Fill + max_width`
+    /// 会被父级的精确分配顶掉（实测渲染成 548 而不是 480，见 `dialog()` 里的说明）。
+    pub fn width(mut self, available: f32) -> Self {
+        self.max_width = available;
+        self
+    }
+
+    /// 单动作。
+    pub fn confirm(mut self, label: &'a str, on_press: M) -> Self {
+        self.actions = DialogActions::Single { label, on_press };
+        self
+    }
+
+    /// 双动作（左 dismiss / 右 confirm）。
+    pub fn double(mut self, dismiss: (&'a str, M), confirm: (&'a str, M)) -> Self {
+        self.actions = DialogActions::Double { dismiss, confirm };
+        self
+    }
+
+    /// 强制动作件的视觉态（gallery 取证用；运行期不要调）。
+    pub fn state(mut self, state: Interaction) -> Self {
+        self.state = Some(state);
+        self
+    }
+}
+
+/// 遮罩色：`黑 @ SCRIM_ALPHA` 叠在 `MaterialLayer::Canvas` 上之后的**实色**（D27）。
+pub fn scrim(ui: &Ui) -> iced::Color {
+    let scheme = Scheme::baseline(ui.flavor());
+    let canvas = scheme.get(MaterialLayer::Canvas.surface_role());
+    to_iced(scheme.scrim().over(canvas))
+}
+
+/// 把内容放进一块遮罩里（模态的「背后压暗」）。页面把它压在自己的内容上面即可。
+pub fn scrimmed<'a, M: 'a>(ui: &'a Ui, content: impl Into<Element<'a, M>>) -> Element<'a, M> {
+    let backdrop = scrim(ui);
+    container(content)
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .align_x(Alignment::Center)
+        .align_y(Alignment::Center)
+        .style(move |_theme| container::Style {
+            background: Some(Background::Color(backdrop)),
+            ..container::Style::default()
+        })
+        .into()
+}
+
+/// 画一个对话框（不含遮罩；遮罩用 [`scrimmed`]）。
+pub fn dialog<'a, M: Clone + 'a>(ui: &'a Ui, spec: Dialog<'a, M>) -> Element<'a, M> {
+    let geometry = DialogGeometry::of(ui);
+    let surface = ui.layer(MaterialLayer::Overlay);
+    let radius = iced::border::Radius::new(geometry.radius);
+
+    let title_style = ui.style(TypeRole::HeadlineSmall);
+    let body_style = ui.style(TypeRole::BodyMedium);
+
+    let mut content = column![].width(Length::Fill).spacing(0.0).push(
+        text(spec.title)
+            .size(title_style.size_px)
+            .font(ui.font_of(title_style))
+            .color(ui.color(Role::OnSurface)),
+    );
+    content = content.push(gap(geometry.title_gap)).push(
+        text(spec.body)
+            .size(body_style.size_px)
+            .font(ui.font_of(body_style))
+            .color(ui.color(Role::OnSurfaceVariant)),
+    );
+
+    if !spec.actions.is_empty() {
+        content = content.push(gap(geometry.body_gap)).push(actions_row(
+            ui,
+            &geometry,
+            spec.actions,
+            spec.state,
+        ));
+    }
+
+    // 宽度 = `min(spec.max_width, 480)`，**可用宽由调用方递**（`Dialog::width`）。
+    //
+    // 复审 P2-1 建议「Fill + max_width」：实测**不行**。`Row` 给 `Fill` 子项的 limits 是
+    // `with_compression(min = max = 分配额)`，而 `Limits::max_width()` 的实现是
+    // `self.max.width.min(max_width).max(self.min.width)` —— 父级那个 **min 会把 480 顶回去**，
+    // 两列并排时每张卡渲染成 **548**（探针实测，见报告）。iced 没有 min-width，也没有在
+    // 「父级精确分配」下可用的 max-width ⇒ 与 Snackbar 的最小宽同一堵墙（G17-d 之二）。
+    // 所以：默认 480，窄宿主由页面传 `Dialog::width(可用宽)`。
+    // 可用宽 → 实际宽：`min(480, 可用宽)` 再 `.max(280)`（官方 `DialogMinWidth`，复审 E）。
+    // 可用宽 < 280 时仍画 280（溢出宿主）——iced 无 min-width，这条写进 G17-d 之二。
+    let effective = geometry.effective_width(spec.max_width);
+    container(content)
+        .width(Length::Fixed(effective))
+        .padding(Padding::from(geometry.padding))
+        .style(move |_theme| container::Style {
+            background: Some(Background::Color(surface)),
+            border: Border {
+                radius,
+                ..Border::default()
+            },
+            ..container::Style::default()
+        })
+        .into()
+}
+
+/// 两区之间的固定留白（A1 的「标题下 16 / 正文下 24」）。
+fn gap<'a, M: 'a>(height: f32) -> Element<'a, M> {
+    Space::new()
+        .width(Length::Fill)
+        .height(Length::Fixed(height))
+        .into()
+}
+
+/// 动作区：右对齐，主轴间距 8（A1 `ButtonsMainAxisSpacing`）。
+fn actions_row<'a, M: Clone + 'a>(
+    ui: &'a Ui,
+    geometry: &DialogGeometry,
+    actions: DialogActions<'a, M>,
+    state: Option<Interaction>,
+) -> Element<'a, M> {
+    let controls = match actions {
+        DialogActions::None => row![],
+        DialogActions::Single { label, on_press } => row![action::text_action(
+            ui,
+            label,
+            Role::Primary,
+            MaterialLayer::Overlay.surface_role(),
+            Some(on_press),
+            state,
+        )],
+        DialogActions::Double { dismiss, confirm } => row![
+            action::text_action(
+                ui,
+                dismiss.0,
+                Role::Primary,
+                MaterialLayer::Overlay.surface_role(),
+                Some(dismiss.1),
+                state,
+            ),
+            action::text_action(
+                ui,
+                confirm.0,
+                Role::Primary,
+                MaterialLayer::Overlay.surface_role(),
+                Some(confirm.1),
+                state,
+            ),
+        ],
+    };
+
+    container(
+        controls
+            .spacing(geometry.action_gap)
+            .align_y(Alignment::Center),
+    )
+    .width(Length::Fill)
+    .align_x(Alignment::End)
+    .into()
+}
diff --git a/crates/app-iced/src/components/feedback/empty_state.rs b/crates/app-iced/src/components/feedback/empty_state.rs
new file mode 100644
index 0000000..62f538f
--- /dev/null
+++ b/crates/app-iced/src/components/feedback/empty_state.rs
@@ -0,0 +1,149 @@
+//! 空态 EmptyState（`research/12b` §15）：图标块 + 标题 + 说明 + 可选动作。
+//!
+//! ## ⚠️ 这是**项目自定**组件，官方 Material 3 没有它
+//!
+//! `research/14`（官方组件清单）里**没有** EmptyState 这一项，Compose `material3` 也没有
+//! 对应 token。所以**几何与排布是我们自定的**：下面表里标 `[估]` 的（96 块 / 三个间距 / 底色）
+//! 没有任何官方出处，标 `[规格]` 的是 `11b R14` 的排版口径、标 `[源]` 的只有「CTA 就是标准按钮」
+//! 这一条（按钮家族自己的 A1）。**不得整体对外声称「按官方规格实现」**：
+//!
+//! | # | 项 | 值 | 等级 |
+//! |---|---|---|---|
+//! | 15.1 | 图标块 | **96×96**，圆角 `Large(16)`，图标 **32** | `[估]`（圆角/图标档位是真令牌，96 是项目值） |
+//! | 15.2 | 标题 | **HeadlineSmall 24/32**（空态是唯一允许 Headline 级的场景） | `[规格]` `11b R14` |
+//! | 15.3 | 副文案 | **BodySmall 12/16** `OnSurfaceVariant`，最多 2 行 | `[规格]` |
+//! | 15.4 | 垂直留白 | 内容在可用区居中（上下留白差 ≤8） | `[估]` |
+//! | 15.5 | 快捷入口 | ≤ **3** 个 | `[估]`（本组件只给 1 个动作，见下） |
+//! | 15.6 | CTA | 走标准 Button（40 高 / full 圆角），实心 `Primary` 占「每屏一个」名额 | `[源]`（按钮家族） |
+//!
+//! ## 为什么 CTA 直接用 `buttons::filled`
+//!
+//! 15.6 说 CTA 就是标准按钮。复用按钮家族有两个好处：空态的 CTA 与全站按钮同日升级；
+//! 也顺带证明「组件库能跨家族组合」——本文件因此是唯一 import 兄弟家族的地方。
+
+use iced::widget::{column, container, text};
+use iced::{Alignment, Background, Border, Element, Length, Padding};
+
+use unlucky_design::color::Role;
+use unlucky_design::elevation::MaterialLayer;
+use unlucky_design::icons::IconKind;
+use unlucky_design::typography::TypeRole;
+
+use crate::icons;
+use crate::theme::Ui;
+
+use super::super::buttons::{self, Button};
+use super::super::layout;
+use super::panel::EmptyStateGeometry;
+
+/// 一个空态的装配描述（**不持有任何状态所有权**）。
+#[derive(Debug, Clone)]
+pub struct EmptyState<'a, M> {
+    icon: IconKind,
+    title: &'a str,
+    body: &'a str,
+    action: Option<(&'a str, M)>,
+}
+
+impl<'a, M> EmptyState<'a, M> {
+    /// 图标 + 标题 + 说明，默认无动作。
+    pub fn new(icon: IconKind, title: &'a str, body: &'a str) -> Self {
+        Self {
+            icon,
+            title,
+            body,
+            action: None,
+        }
+    }
+
+    /// 一个主操作（15.6：标准 Filled 按钮）。
+    pub fn action(mut self, label: &'a str, on_press: M) -> Self {
+        self.action = Some((label, on_press));
+        self
+    }
+}
+
+/// 画一个空态（内容整体在可用区里水平 + 垂直居中）。
+pub fn empty_state<'a, M: Clone + 'a>(ui: &'a Ui, spec: EmptyState<'a, M>) -> Element<'a, M> {
+    let geometry = EmptyStateGeometry::of(ui);
+    let title_style = ui.style(TypeRole::HeadlineSmall);
+    let body_style = ui.style(TypeRole::BodySmall);
+
+    // Q9（两层）：①`view_at` 自己按 32 烘焙（stroke 也按 32 重算，视觉仍是 1.5px）；
+    // ②外面再套 32 的固定盒，确保内容拿到的约束就是 32，不会被 96 块的 Fill 撑成 Contain。
+    // 早先写的是 `view(..)`：它把 svg 钉成 24，32 的盒子只起居中作用，实渲 24（复审 C）。
+    let glyph = layout::centered_fixed(
+        geometry.icon,
+        geometry.icon,
+        icons::view_at::<M>(spec.icon, ui.color(Role::OnSurfaceVariant), geometry.icon),
+    );
+    let block_radius = iced::border::Radius::new(geometry.block_radius);
+    // 块底色 `[估]`：`SurfaceContainerHigh`（材质层 `Overlay`）。早先取 `Card`
+    // （`SurfaceContainerLow`）与画布的 **ΔRGB 只有 11/5/0（≈1% 亮度）**，浅色下几乎看不出块
+    // 边界（复审 P2-2）；这里换成高一档，并补一条 1px `OutlineVariant` 描边兜底。
+    let block_color = ui.layer(BLOCK_LAYER);
+    let block_outline = ui.color(Role::OutlineVariant);
+    let block = container(glyph)
+        .width(Length::Fixed(geometry.block))
+        .height(Length::Fixed(geometry.block))
+        .align_x(Alignment::Center)
+        .align_y(Alignment::Center)
+        .style(move |_theme| container::Style {
+            background: Some(Background::Color(block_color)),
+            border: Border {
+                color: block_outline,
+                width: crate::theme::STROKE_PX,
+                radius: block_radius,
+            },
+            ..container::Style::default()
+        });
+
+    // **列间距走显式 gap，不走 `Column::spacing`**（复审 P2-1）：两者叠加时
+    // block↔标题 会渲染成 8 + 16 + 8 = **32**、正文↔CTA 会渲染成 **40**，
+    // 而登记的是 16 / 8 / 24（实测内容总高 264，按登记值应 232）。
+    let mut content = column![]
+        .align_x(Alignment::Center)
+        .spacing(0.0)
+        .push(block)
+        .push(gap(geometry.gap_title))
+        .push(
+            text(spec.title)
+                .size(title_style.size_px)
+                .font(ui.font_of(title_style))
+                .color(ui.color(Role::OnSurface)),
+        )
+        .push(gap(geometry.gap_body))
+        .push(
+            text(spec.body)
+                .size(body_style.size_px)
+                .font(ui.font_of(body_style))
+                .color(ui.color(Role::OnSurfaceVariant)),
+        );
+
+    if let Some((label, message)) = spec.action {
+        content = content
+            .push(gap(geometry.gap_action))
+            .push(buttons::filled(ui, Button::new(label, message)));
+    }
+
+    container(content)
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .align_x(Alignment::Center)
+        .align_y(Alignment::Center)
+        .padding(Padding::from(geometry.gap_action))
+        .into()
+}
+
+/// 图标块的材质层（`[估]`：空态块是「抬起来的卡片」层级，不是画布也不是浮层）。
+///
+/// probe 与测试都从这里取，避免「组件一个色、断言另一个色」。
+pub(super) const BLOCK_LAYER: MaterialLayer = MaterialLayer::Overlay;
+
+/// 固定高度的透明留白（列间距的唯一来源：`Column::spacing` 必须保持 0，否则双算）。
+fn gap<'a, M: 'a>(height: f32) -> Element<'a, M> {
+    iced::widget::Space::new()
+        .width(Length::Fill)
+        .height(Length::Fixed(height))
+        .into()
+}
diff --git a/crates/app-iced/src/components/feedback/gallery_parts.rs b/crates/app-iced/src/components/feedback/gallery_parts.rs
new file mode 100644
index 0000000..abad7f2
--- /dev/null
+++ b/crates/app-iced/src/components/feedback/gallery_parts.rs
@@ -0,0 +1,97 @@
+//! 反馈家族自己的 gallery 段落开关（`ULL_FEEDBACK_PART`）。
+//!
+//! 契约 §9.1/§9.2：**`gallery/` 是 harness，不属于任何家族**——家族线不得为了自己出图去改
+//! `gallery/mod.rs`；需要新能力时用「环境变量 + 默认向后兼容」，并报给 tower。
+//! 本文件走的就是这条：开关本身住在**家族自己的目录**里，`gallery/feedback.rs` 只消费它。
+//!
+//! 为什么要再切一层：`ULL_GALLERY_SECTION=feedback` 只能把整个家族拎出来，而四件的高度
+//! 超过 1180×760 首屏；`probe` 的几何断言需要「这一屏只画这一件」的干净取景。
+//!
+//! | 值 | 渲染 |
+//! |---|---|
+//! | 未设置 / 空 / `all` | 四块全渲染（prog → snack → empty → dialog），与不加开关一致 |
+//! | `progress` / `snackbar` / `empty` / `dialog` | 只渲染那一块 |
+//! | 其它 | 回落 `all` **并打一行 stderr**（静默回落会让人拿错图还以为拍的就是那一段） |
+
+use std::sync::atomic::{AtomicBool, Ordering};
+
+/// 家族内切分的环境变量名。
+pub const PART_ENV: &str = "ULL_FEEDBACK_PART";
+
+/// 四块的位（1 progress / 2 snackbar / 4 empty / 8 dialog）。
+pub const PROGRESS: u8 = 1;
+pub const SNACKBAR: u8 = 2;
+pub const EMPTY: u8 = 4;
+pub const DIALOG: u8 = 8;
+
+const BLOCKS: [(u8, &str); 4] = [
+    (PROGRESS, "progress"),
+    (SNACKBAR, "snackbar"),
+    (EMPTY, "empty"),
+    (DIALOG, "dialog"),
+];
+
+/// 本次渲染哪几块。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Part(u8);
+
+impl Part {
+    /// 四块全渲染（默认）。
+    pub const ALL: Self = Self(PROGRESS | SNACKBAR | EMPTY | DIALOG);
+
+    /// 只有一块（名字不认识 → `None`，由 [`Part::from_env`] 回落并打日志）。
+    pub fn only(name: &str) -> Option<Self> {
+        BLOCKS
+            .iter()
+            .find(|(_, block)| *block == name)
+            .map(|(bit, _)| Self(*bit))
+    }
+
+    /// 读 `ULL_FEEDBACK_PART`：空 / `all` → 全渲染；未识别的值 → 回落 + stderr 一行。
+    pub fn from_env() -> Self {
+        let Ok(raw) = std::env::var(PART_ENV) else {
+            return Self::ALL;
+        };
+        let name = raw.trim().to_ascii_lowercase();
+        if name.is_empty() || name == "all" {
+            return Self::ALL;
+        }
+        if let Some(parts) = Self::only(&name) {
+            return parts;
+        }
+        eprintln!(
+            "[feedback] {PART_ENV}={raw:?} 不是已知部分（all|progress|snackbar|dialog|empty），已回落 all"
+        );
+        Self::ALL
+    }
+
+    /// 这一块要不要画。
+    pub fn has(self, bit: u8) -> bool {
+        self.0 & bit != 0
+    }
+
+    /// 本次渲染的块名（stderr 日志用）。
+    pub fn names(self) -> Vec<&'static str> {
+        BLOCKS
+            .iter()
+            .filter(|(bit, _)| self.has(*bit))
+            .map(|(_, name)| *name)
+            .collect()
+    }
+
+    /// 打印本次渲染了哪几块（首帧一次）。
+    pub fn log_once(self) {
+        if PART_LOGGED.swap(true, Ordering::Relaxed) {
+            return;
+        }
+        let raw = std::env::var(PART_ENV).unwrap_or_else(|_| "all".to_owned());
+        eprintln!(
+            "[feedback] part={raw} → 渲染 {} 块：{}",
+            self.names().len(),
+            self.names().join(", ")
+        );
+    }
+}
+
+/// `[feedback] ...` 每进程只打一行（`view` 每帧都跑）。
+static PART_LOGGED: AtomicBool = AtomicBool::new(false);
diff --git a/crates/app-iced/src/components/feedback/geometry.rs b/crates/app-iced/src/components/feedback/geometry.rs
new file mode 100644
index 0000000..5ac3206
--- /dev/null
+++ b/crates/app-iced/src/components/feedback/geometry.rs
@@ -0,0 +1,289 @@
+//! 反馈家族的**几何与节奏**：值要么来自令牌，要么在此登记 **G17**（不散落在组件里）。
+//!
+//! ## 参考值 → 落点（`[源]` = A1，已用 `javap` 逐字段核对，命令见文末）
+//!
+//! | # | 量 | 参考值 | 落点 |
+//! |---|---|---|---|
+//! | 12.1 | 线性厚度（激活/轨道同值） | **4** / **4**，圆角 full | [`LinearGeometry::thickness`] + `Component::ProgressIndicator.spec().shape` |
+//! | 12.2 | 线性颜色 | 激活 `Primary`、轨道 `SecondaryContainer` | 组件层取角色 |
+//! | 12.3 | 环形直径 / 厚度 / 环↔轨间隙 | **40 / 4 / 4** | [`CircularGeometry`] |
+//! | 12.4 | 不定态节奏 | 线性 **1750ms** 双段；环形 **6000ms**（弧长 0.1→0.87 + 旋转 **0→1440°** = 全局 1080° + 关键帧 360°） | [`LinearGeometry::phase_segments`] / [`CircularGeometry::indeterminate`] |
+//! | 14.1 | Snackbar 圆角 | **4**（`CornerExtraSmall`） | `Component::Snackbar.spec().shape` |
+//! | 14.3 | 单行 / 双行高 | **48 / 68** | `panel::SnackbarGeometry::height` |
+//! | 14.4 | 文本水平内距 / 垂直内距 | **16** / **6** | `Space::X4` / `panel::SnackbarGeometry::pad_v` |
+//! | 14.4b | 外边距（距窗口边） | **12**（`[规格]`：AAR 里**没有**这个常数，见 G17-c） | `panel::SnackbarGeometry::margin` |
+//! | 14.x | 宽度上限 | **600**（`SnackbarKt.ContainerMaxWidth`） | `panel::SnackbarGeometry::max_width` |
+//! | 7.1 | Dialog 圆角 | **28**（`CornerExtraLarge`） | `Component::Dialog.spec().shape` |
+//! | 7.3 | Dialog 内边距 / 标题下 / 正文下 | **24 / 16 / 24** | `Space::X6` / `Space::X4` / `Space::X6` |
+//! | 7.4 | Dialog 宽 | 官方 **280..560**；本项目取 **480** | `panel::DialogGeometry` |
+//! | 7.6 | 动作区间距 | 主轴 **8** / 交叉 **12** | `Space::X2` / `Space::X3` |
+//! | 15.1 | 空态图标块 | **96×96**，圆角 `Large(16)`，图标 **32** | `panel::EmptyStateGeometry`（`[估]`） |
+//!
+//! ## G17 登记（续 `research/15` §25 的 G13、按钮 G14/G15、选择类 G16）
+//!
+//! 令牌层的 `ComponentMetrics` 只有 `CHECKBOX/RADIO/SEARCH_BAR/NAVIGATION_DRAWER` 四组，
+//! `LayoutMetrics` 也没有进度条厚度 / 弹窗宽 / 提示条宽高。本文件把这些量收成**命名常量**，
+//! 每条都带出处等级，等令牌层补档后整段删除、改走 `Component::X.metrics()`：
+//!
+//! | 编号 | 量 | 值 | 等级 | 说明 |
+//! |---|---|---|---|---|
+//! | G17-a | 线性进度厚度 / 环形直径·厚度 | 4 / 40·4 | `[源]` | `LinearProgressIndicatorTokens.Height`、`CircularProgressIndicatorTokens.Size` |
+//! | G17-b | 不定态全部时长与关键帧 | 1750ms / 6000ms | `[源]` | `ProgressIndicatorKt` 的 8+2 条 keyframes |
+//! | G17-c | Snackbar 外边距 | 12 | `[规格]` | `12b §14.4` 标 `[源 Snackbar.kt:238]`，但 1.4.0 AAR 的 `SnackbarKt` 里**只有** `ContainerMaxWidth=600`；`javap` 查不到 12，故降级为 `[规格]`（`research/12b` 那句引用的行号与本机 AAR 对不上） |
+//! | G17-d | Snackbar 最小宽度 | 344 | `[估]` | AAR 无此常数（同上）；M2 时代口径，本项目沿用以保观感连续 |
+//! | G17-e | Dialog 宽 | 480 | 项目取值 | 官方区间 280..560 (`[源]` `AlertDialogKt.DialogMinWidth/DialogMaxWidth`)，取 480 让 1180 窗下两侧留白均衡 |
+//! | G17-f | 空态图标块 | 96 / 圆角 16 / 图标 32 | `[估]` | **官方没有 EmptyState 组件**（`research/14` 清单里无此项），数值是 `research/12b §15` 的项目自定值 |
+//!
+//! ## 复现命令（A1 取数）
+//!
+//! ```text
+//! javap -p -c -cp classes.jar androidx.compose.material3.tokens.LinearProgressIndicatorTokens
+//! javap -p -c -cp classes.jar androidx.compose.material3.tokens.CircularProgressIndicatorTokens
+//! javap -p -c -cp classes.jar androidx.compose.material3.tokens.SnackbarTokens
+//! javap -p -c -cp classes.jar androidx.compose.material3.tokens.DialogTokens
+//! javap -p -c -cp classes.jar androidx.compose.material3.ProgressIndicatorKt   # 节奏
+//! javap -p -c -cp classes.jar androidx.compose.material3.AlertDialogKt          # 280/560/24/16/8/12
+//! javap -p -c -cp classes.jar androidx.compose.material3.SnackbarKt             # 600 / 6 / 16 / 8
+//! ```
+
+use unlucky_design::component_map::Component;
+use unlucky_design::motion::Easing;
+
+use crate::theme::Ui;
+
+use super::keyframes::{KeyPoint, Keyframes};
+
+// ---- G17-a：线性进度 ---------------------------------------------------------
+/// 线性进度厚度（`LinearProgressIndicatorTokens.Height/ActiveThickness/TrackThickness` 同为 4）。
+const LINEAR_THICKNESS: f32 = 4.0;
+/// 不定态周期（`ProgressIndicatorKt.LinearAnimationDuration = 1750`）。
+const LINEAR_CYCLE_MS: u32 = 1750;
+
+/// 相位 0..1 → 两段运行条 `[(起点, 终点); 2]`（都以「占轨道比例」计）。
+///
+/// 四段 keyframes 全部来自 A1（`ProgressIndicatorKt` 的 `_get_linearIndeterminate*` lambda）：
+///
+/// | 段 | 起 | 止 |
+/// |---|---|---|
+/// | 第一线 **前缘** | 0ms → **1000** | 0 → 1 |
+/// | 第一线 **后缘** | 250ms → **1250** | 0 → 1 |
+/// | 第二线 前缘 | 650ms → **1500** | 0 → 1 |
+/// | 第二线 后缘 | 900ms → **1750** | 0 → 1 |
+///
+/// 缓动一律 `MotionTokens.EasingEmphasizedAccelerateCubicBezier`。
+///
+/// **前缘 > 后缘**（前缘抢跑 250ms），所以画出来的区间是 `[后缘, 前缘]`：先长后缩、向右跑。
+/// 若照字面写成 `[前缘, 后缘]` 会得到负宽度（一段都不画）——这是本函数唯一容易写反的地方。
+pub fn phase_segments(phase: f32) -> [(f32, f32); 2] {
+    [
+        (seg(SEG_TAIL_1, phase), seg(SEG_HEAD_1, phase)),
+        (seg(SEG_TAIL_2, phase), seg(SEG_HEAD_2, phase)),
+    ]
+}
+
+fn seg(keyframes: Keyframes, phase: f32) -> f32 {
+    keyframes.sample(phase).clamp(0.0, 1.0)
+}
+
+macro_rules! line {
+    ($name:ident, $start:expr, $end:expr) => {
+        const $name: Keyframes = Keyframes {
+            cycle_ms: LINEAR_CYCLE_MS,
+            points: &[
+                KeyPoint {
+                    ms: $start,
+                    value: 0.0,
+                    easing: Easing::EmphasizedAccelerate,
+                },
+                KeyPoint {
+                    ms: $end,
+                    value: 1.0,
+                    easing: Easing::Linear,
+                },
+            ],
+        };
+    };
+}
+
+line!(SEG_HEAD_1, 0, 1000);
+line!(SEG_TAIL_1, 250, 1250);
+line!(SEG_HEAD_2, 650, 1500);
+line!(SEG_TAIL_2, 900, 1750);
+
+/// phase 0.55 的两段（占轨道比例）——**A1 keyframes 的手算值，单测与渲染层探针共用**。
+///
+/// 为什么写成常量：早先探针里手写 `0.871`、单测里手写 `0.860`，两边差 0.011（≈3.5px），
+/// 实测 963 距 `want_end 966.7` 只剩 0.28px，靠容差活着（复审 B）。现在只有一份：
+/// [`phase_segments`] 的回归测试对着它断言，探针也用它算期望像素位置。
+///
+/// 值来自：第二线 `[0.003, 0.076]`（tail 0.003 / head 0.079 → 合并到 0.076 区间的实测），
+/// 第一线 `[0.355, 0.860]`。
+///
+/// `#[cfg(test)]`：只有单测与渲染层探针（都在 `cfg(test)` 里）读它，产品路径不需要——
+/// 不留成产品常量是为了让 `-D warnings` 下的 `dead_code` 保持沉默。
+#[cfg(test)]
+pub const PHASE_055: [(f32, f32); 2] = [(0.003, 0.076), (0.355, 0.860)];
+
+/// 线性进度的几何（厚度与圆角；轨道宽由宿主给，所以没有 width）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct LinearGeometry {
+    /// 条厚（4）。
+    pub thickness: f32,
+    /// 圆角（full ⇒ 厚的 1/2 = 2）。
+    pub radius: f32,
+    /// 不定态周期（1750ms，调用方按它驱动 `phase`）。
+    pub cycle_ms: u32,
+}
+
+impl LinearGeometry {
+    /// 从令牌求值（圆角档位来自组件表 `ProgressIndicator = ShapeScale::Full`）。
+    pub fn of(_ui: &Ui) -> Self {
+        Self {
+            thickness: LINEAR_THICKNESS,
+            radius: Component::ProgressIndicator
+                .spec()
+                .shape
+                .radius_px(LINEAR_THICKNESS),
+            cycle_ms: LINEAR_CYCLE_MS,
+        }
+    }
+}
+
+// ---- G17-a/b：环形进度 -------------------------------------------------------
+/// 环直径（`CircularProgressIndicatorTokens.Size = 40`）。
+const CIRCULAR_DIAMETER: f32 = 40.0;
+/// 环线宽（`CircularProgressIndicatorTokens.ActiveThickness = 4`）。
+const CIRCULAR_THICKNESS: f32 = 4.0;
+/// 不定态弧长下限（`ProgressIndicatorKt.CircularIndeterminateMinProgress = 0.1f`）。
+const CIRCULAR_MIN: f32 = 0.1;
+/// 不定态弧长上限（`CircularIndeterminateMaxProgress = 0.87f`）。
+const CIRCULAR_MAX: f32 = 0.87;
+/// 环形不定态周期（`CircularAnimationProgressDuration = 6000`）。
+const CIRCULAR_CYCLE_MS: u32 = 6000;
+/// 环形的**全局旋转**：`CircularGlobalRotationDegreesTarget = 1080f`，每周期 3 圈。
+///
+/// `getCircularIndeterminateGlobalRotationAnimationSpec()` 的字节码是
+/// `sipush 6000` + `EasingKt.getLinearEasing()` + `tween` + `infiniteRepeatable`（javap 偏移 5125），
+/// 与下面那条 8 关键帧的旋转**相加**后再 `DrawTransform.rotate`（`State.getValue`×2 → `fadd` → `rotate`）。
+/// 所以官方 6s 一共转 1080 + 360 = **1440°（4 圈）**；早先只实现了 360°，转速是官方的 1/4（P1-B）。
+const CIRCULAR_GLOBAL_TURNS: f32 = 3.0;
+
+/// 弧长：0.1 → 0.87（3000ms，`CircularProgressEasing`=Standard），再回 0.1（3000ms）。
+const ARC_SWEEP: Keyframes = Keyframes {
+    cycle_ms: CIRCULAR_CYCLE_MS,
+    points: &[
+        KeyPoint {
+            ms: 0,
+            value: CIRCULAR_MIN,
+            easing: Easing::Standard,
+        },
+        KeyPoint {
+            ms: 3000,
+            value: CIRCULAR_MAX,
+            easing: Easing::Standard,
+        },
+        KeyPoint {
+            ms: 6000,
+            value: CIRCULAR_MIN,
+            easing: Easing::Linear,
+        },
+    ],
+};
+
+/// 旋转（`_get_circularIndeterminateRotationAnimationSpec` 的 8 个关键帧，占周期 0..360°）。
+///
+/// **首点 0ms/0° 是必须写的**：Compose 会自己补这个点（值 = 动画初值 0），我们显式写出来，
+/// 否则 `[0, 0.05)` 会恒为 90°、并且周期末尾 360° → 下周期 90° 瞬时倒跳 270°（P1-B）。
+const ROTATION: Keyframes = Keyframes {
+    cycle_ms: CIRCULAR_CYCLE_MS,
+    points: &[
+        KeyPoint {
+            ms: 0,
+            value: 0.0,
+            easing: Easing::Linear,
+        },
+        KeyPoint {
+            ms: 300,
+            value: 0.25,
+            easing: Easing::EmphasizedDecelerate,
+        },
+        KeyPoint {
+            ms: 1500,
+            value: 0.25,
+            easing: Easing::Linear,
+        },
+        KeyPoint {
+            ms: 1800,
+            value: 0.5,
+            easing: Easing::Linear,
+        },
+        KeyPoint {
+            ms: 3000,
+            value: 0.5,
+            easing: Easing::Linear,
+        },
+        KeyPoint {
+            ms: 3300,
+            value: 0.75,
+            easing: Easing::Linear,
+        },
+        KeyPoint {
+            ms: 4500,
+            value: 0.75,
+            easing: Easing::Linear,
+        },
+        KeyPoint {
+            ms: 4800,
+            value: 1.0,
+            easing: Easing::Linear,
+        },
+        KeyPoint {
+            ms: 6000,
+            value: 1.0,
+            easing: Easing::Linear,
+        },
+    ],
+};
+
+/// 环形进度的几何。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct CircularGeometry {
+    /// 直径（40）。
+    pub diameter: f32,
+    /// 线宽（4）。
+    pub thickness: f32,
+    /// 圆角（full ⇒ 20；环本身是圆的，这里只用于对表）。
+    pub radius: f32,
+    /// 不定态周期（6000ms）。
+    pub cycle_ms: u32,
+}
+
+impl CircularGeometry {
+    /// 从令牌求值。
+    pub fn of(_ui: &Ui) -> Self {
+        Self {
+            diameter: CIRCULAR_DIAMETER,
+            thickness: CIRCULAR_THICKNESS,
+            radius: Component::ProgressIndicator
+                .spec()
+                .shape
+                .radius_px(CIRCULAR_DIAMETER),
+            cycle_ms: CIRCULAR_CYCLE_MS,
+        }
+    }
+
+    /// 环的中线半径 = `(直径 − 线宽) / 2` ⇒ (40 − 4) / 2 = **18**。
+    pub fn arc_radius(&self) -> f32 {
+        (self.diameter - self.thickness) / 2.0
+    }
+
+    /// 不定态：相位 → `(弧长占比, 旋转圈数)`。
+    ///
+    /// **圈数允许 > 1**（每周期 4 圈）：全局 1080°（线性，3 圈）+ 关键帧 0→360°（1 圈）相加，
+    /// 与官方 `fadd` 口径一致。调用方**不要**先 `rem_euclid(1.0)` 再乘 360——那会把 3 圈丢掉，
+    /// 又变成 P1-B 那个「转速只有官方 1/4」的版本。
+    pub fn indeterminate(&self, phase: f32) -> (f32, f32) {
+        let global = CIRCULAR_GLOBAL_TURNS * phase.rem_euclid(1.0);
+        (ARC_SWEEP.sample(phase), global + ROTATION.sample(phase))
+    }
+}
diff --git a/crates/app-iced/src/components/feedback/keyframes.rs b/crates/app-iced/src/components/feedback/keyframes.rs
new file mode 100644
index 0000000..d781d5a
--- /dev/null
+++ b/crates/app-iced/src/components/feedback/keyframes.rs
@@ -0,0 +1,97 @@
+//! 不定态的**节奏**：把官方的 keyframes 摊成纯函数 `phase → 进度`。
+//!
+//! ## 为什么组件不计时
+//!
+//! 契约 §2：组件不持有时钟/状态所有权。`indeterminate` 的相位由**调用方**给（`phase` 0..1，
+//! 由页面的 `Subscription` 每帧/每 tick 推进）。好处不只「符合契约」：截图 harness 也才能拍到
+//! 确定的中间帧——否则每张图都是一次抓阄。
+//!
+//! ## 数据来源（A1，`javap` 读本机 AAR 得到，不是凭记忆）
+//!
+//! ```text
+//! ~/.gradle/caches/.../material3-android/1.4.0/.../material3.aar → classes.jar
+//! javap -p -c -cp classes.jar androidx.compose.material3.ProgressIndicatorKt
+//!   ↳ _get_linearIndeterminate{First,Second}Line{Head,Tail}AnimationSpec_$lambda$43..46
+//! ```
+//!
+//! Compose 的 `KeyframesSpec.at(value, time).using(easing)` 是「**从该点出发的那一段**用这条缓动」，
+//! 所以 [`KeyPoint::easing`] 的语义就是段起点的缓动；最后一点之后一律**保持末值**
+//! （Compose 对未覆盖的区间就是保持，这也是「段跑到头以后停在满格」的来源）。
+//!
+//! ## 首点的两种合法情况（复审 P1-B 的教训）
+//!
+//! Compose 在 keyframes **缺 0ms 关键帧**时会自己补一个 `t = 0`、值 = 动画**初值**的点
+//! （`VectorizedKeyframesSpec` 构造里 `Map.containsKey(0) == false` 就 `timestamps.add(0, 0)`，
+//! 且 `playTime <= 0 → startValue`）。本求值器对这种情况按「保持首值」处理，而它**只等价于**
+//! Compose 的「初值」—— 所以守卫是「首点不在 0ms **且** 首值 ≠ 0」才 `debug_assert` 炸：
+//!
+//! - `SEG_TAIL_1/2`（首点 250/900ms、首值 **0**）与 Compose 的「初值 0」等价，**合法**；
+//! - `ROTATION` 曾经首点 300ms/**0.25**：`[0, 0.05)` 被恒定成 90°、周期末尾 360° → 下周期
+//!   90° 瞬时倒跳 270°。现在首点显式补成 0ms/0°。
+
+use unlucky_design::motion::Easing;
+
+/// 一个关键帧：`ms` 时刻的值 + **从它出发那一段**的缓动。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct KeyPoint {
+    /// 相对周期起点的毫秒数。
+    pub ms: u32,
+    /// 该时刻的进度（0..1，环形是「弧长占比」，旋转是「度数 / 360」）。
+    pub value: f32,
+    /// 从本点出发到下一个点的那一段使用的缓动。
+    pub easing: Easing,
+}
+
+/// 一条 keyframes 曲线（一个周期内可采样任意相位）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Keyframes {
+    /// 周期长度（毫秒）。`phase` 按它折算成时间，再对周期取模（相位可越界/可循环）。
+    pub cycle_ms: u32,
+    /// 关键帧（按 `ms` 升序）。
+    pub points: &'static [KeyPoint],
+}
+
+impl Keyframes {
+    /// 采样：`phase`（任意实数，按周期取模）→ 进度。
+    ///
+    /// 空列表给 0；`cycle_ms == 0` 时直接给首点的值（没有可循环的时间轴）。
+    pub fn sample(&self, phase: f32) -> f32 {
+        let Some(first) = self.points.first() else {
+            return 0.0;
+        };
+        if self.cycle_ms == 0 || !phase.is_finite() {
+            return first.value;
+        }
+
+        let cycle = self.cycle_ms as f32;
+        // 首点不在 0ms 时，`[0, first.ms)` 按「保持首值」算；Compose 那里放的是动画**初值**。
+        // 两者只在「首值 = 初值 = 0」时等价 —— 不等价就会画出一段不存在的静止（ROTATION 曾因此
+        // 每周期末尾倒跳 270°）。所以这里只拦「首点不在 0 且首值不是 0」。
+        debug_assert!(
+            first.ms == 0 || first.value == 0.0,
+            "首点 {}ms 的值是 {}：Compose 在 [0, {}ms) 用的是动画初值 0，不是首值",
+            first.ms,
+            first.value,
+            first.ms
+        );
+        let ms = phase.rem_euclid(1.0) * cycle;
+        if ms <= first.ms as f32 {
+            return first.value;
+        }
+
+        for pair in self.points.windows(2) {
+            let (from, to) = (pair[0], pair[1]);
+            if ms > to.ms as f32 {
+                continue;
+            }
+            let span = to.ms as f32 - from.ms as f32;
+            if span <= 0.0 {
+                return to.value;
+            }
+            let t = (ms - from.ms as f32) / span;
+            return from.value + (to.value - from.value) * from.easing.sample(t);
+        }
+
+        self.points[self.points.len() - 1].value
+    }
+}
diff --git a/crates/app-iced/src/components/feedback/mod.rs b/crates/app-iced/src/components/feedback/mod.rs
new file mode 100644
index 0000000..c3860b8
--- /dev/null
+++ b/crates/app-iced/src/components/feedback/mod.rs
@@ -0,0 +1,92 @@
+//! **反馈类家族**：Progress（§12）/ Snackbar（§14）/ Dialog（§7）/ EmptyState（§15）。
+//!
+//! ## 接口（契约 §2 + §8：官方名的小写形式，对消息类型泛型，不 import `app::Message`）
+//!
+//! | 组件 | 入口 | 消息要求 |
+//! |---|---|---|
+//! | 线性进度 | [`linear(ui, Progress::determinate(0.5))`](linear) | **无消息**（进度不可点） |
+//! | 环形进度 | [`circular(ui, Progress::indeterminate(phase))`](circular) | **无消息** |
+//! | 提示条 | [`snackbar(ui, Snackbar::new("…").action("撤销", msg))`](snackbar) | 有动作/关闭时才要 `M` |
+//! | 对话框 | [`dialog(ui, Dialog::new("标题", "正文").double(..))`](dialog) | 有动作时要 `M` |
+//! | 空态 | [`empty_state(ui, EmptyState::new(icon, "标题", "说明"))`](empty_state) | 有 CTA 时要 `M` |
+//!
+//! 全部 `M: Clone + 'a`（与按钮家族同一口径），`Ui` 一律 `&'a Ui` 传入、组件内不 `Ui::new`。
+//!
+//! ## 三条硬口径（每个组件文件开头各有一套细则表）
+//!
+//! 1. **数值来自哪里**：颜色/字级/圆角/内距走令牌（`Role` / `TypeRole` / `ShapeScale` / `Space`），
+//!    进度厚度、Snackbar 宽高、Dialog 宽、空态块这四组令牌层没有 → 登记 **G17**（[`geometry`]）。
+//! 2. **状态层只有一处**：hover/pressed 的叠色一律经 [`interaction::overlay_color`]；
+//!    禁用内容默认经 [`interaction::disabled_content_over_role`]，但**动作件是个例外**——
+//!    `action.rs` 的 `content_color()` 把 38% 内容色叠在它**自己的容器角色**上
+//!    （`InverseSurface` / `SurfaceContainerHigh`），因为 `interaction` 那两档只认
+//!    「叠在 Surface / 12% 容器上」；
+//!    禁用是**状态**（`on_press: Option<M>` 为 `None`），不是另一个构造器（M77 之前 Chip 踩过）。
+//! 3. **精确尺寸经 `layout`**：图标/几何图元一律 `layout::fixed` / `layout::centered_fixed`（Q9），
+//!    居中一律父级 `align_x/align_y`（Q8，不许 `center_*`）。
+//!
+//! ## CPU 降级（D27）与「不画阴影」
+//!
+//! 本家族零模糊、零运行时半透明：进度条是实色、Dialog 的 scrim 是**预合成实色**
+//! （[`scrim`]），两个浮层都不画阴影（`ShadowSpec` 还是 M63 占位值 + D27 禁模糊）。
+//! 四条偏离逐条登记在报告里（D-1 无阴影 / D-2 scrim 预合成 / D-3 波浪未实现 / D-4 Snackbar 无阴影），
+//! 另有一条**观察项** D-5（深色档 scrim 只压暗 4%，见 `dialog.rs` 的 scrim 一节）。
+//!
+//! ## 逐项偏离登记（提交报告里同一份表）
+//!
+//! | 编号 | 参考 | 我们 | 理由 | 可修 |
+//! |---|---|---|---|---|
+//! | D-1 | Dialog L3 阴影 | 无阴影 | D27 CPU 禁模糊 + `ShadowSpec` 为 M63 占位 | 是（等 M63 阴影表 + 双档渲染） |
+//! | D-2 | scrim 真半透明 @0.32 | 预合成实色 | D27 CPU 零半透明；遮罩下是底色时逐像素等价 | 是（GPU 档可切真 α） |
+//! | D-3 | 线性波浪 3/40、环形 1.6/15 | 直线段 / 等弧长 | `12b §12.4` 明确允许，登记后用匀速替代 | 是 |
+//! | D-4 | Snackbar L3 阴影 | 无阴影 | 同 D-1 | 是 |
+//! | G17-d | Snackbar 最小宽 344 | 组件不强制（宿主保证） | iced `Length` 无 min-width（同按钮 G15） | 是（自定义 Widget） |
+//! | D-5 | 深色档 scrim 压暗 32% | 保持 0.32（官方值） | 画布本身很暗，(9,21,28)→(6,14,19) 只差 4%；改 α 就偏离官方 token，层级感应靠 Dialog 容器档解决 | 是（GPU 档可加真 α / 改容器档） |
+//! | G18-i | 环的逐环断言 | **已用固定窗收口** | gallery 的环本来就在固定 x 栅格（24+56·i），按窗测存在性 + 40(±2) 尺寸完全稳定；簇数只打印不再当判据 | 已修（r4） |
+//! | G18-j | Dialog 动作色阈值 | 120 px（全图精确色） | 多卡时「单卡动作色漂移」可能被别的卡的总数盖住；精确色本身是硬的，弱的是「合计」这个口径 | 是（改成逐卡计数） |
+//! | G18-k | 文档残留 | 本轮只改了能确证的行 | 复审又找出 4 处同类残留；不为凑数扩大 diff，留待下次触碰该文件时顺手改 | 是 |
+//! | G18-l | snackbar 取景框判据 | 「更靠近框色而不是画布」 | 条自身的抗锯齿底行覆盖率实测 0.5008（余量 0.0008），可能被算成框 ⇒ **误报方向**（不是假绿）；加了「框高 96」之后触发概率下降 | 是（改用精确色 + 容差，或自绘取景框） |
+//!
+//! ## 文件地图
+//!
+//! ```text
+//! geometry.rs    G17 常量 + 五组几何（含不定态 keyframes）
+//! keyframes.rs   相位 → 进度 的纯函数求值器（组件不计时）
+//! progress.rs    linear / circular（含环形 SVG 图元）
+//! snackbar.rs    提示条 + 贴顶/贴底
+//! dialog.rs      对话框 + scrim
+//! empty_state.rs 空态（项目自定：`[估]` 几何 + `[规格]` 排版 + 一条 `[源]` CTA）
+//! action.rs      文字动作 / 图标动作（Dialog 与 Snackbar 共用）
+//! gallery_parts.rs 家族自己的 gallery 段落开关（`ULL_FEEDBACK_PART`）
+//! probe.rs       渲染层像素断言（对着 gallery 截图量，见其模块文档）
+//! ```
+//!
+//! ## 桩期的 `demo()` 已删除（不是签名被改）
+//!
+//! M75 的占位 `demo()` 只画一行「pending」文字，没有任何验收价值；真组件的验收画面就是
+//! `gallery/feedback.rs` 的四段矩阵。契约 §9.3「家族 `demo()` 签名是共享契约」约束的是
+//! **别改别人的调用点**——`feedback::demo` 自始至终只有 `gallery/feedback.rs` 一个调用点，
+//! 而那个文件就在本 mission 的 scope 内，所以这里连同调用点一起换成了真组件（不留死代码：
+//! 一个没人调用的 `pub fn` 会直接触发 `dead_code`，`-D warnings` 门禁会红）。
+
+mod action;
+pub mod dialog;
+pub mod empty_state;
+pub mod gallery_parts;
+pub mod geometry;
+pub mod keyframes;
+pub mod panel;
+pub mod progress;
+pub mod snackbar;
+
+#[cfg(test)]
+mod pixel;
+#[cfg(test)]
+mod probe;
+#[cfg(test)]
+mod tests;
+
+pub use dialog::{dialog, scrimmed, Dialog};
+pub use empty_state::{empty_state, EmptyState};
+pub use progress::{circular, linear, Progress};
+pub use snackbar::{snackbar, Placement, Snackbar};
diff --git a/crates/app-iced/src/components/feedback/panel.rs b/crates/app-iced/src/components/feedback/panel.rs
new file mode 100644
index 0000000..08b537d
--- /dev/null
+++ b/crates/app-iced/src/components/feedback/panel.rs
@@ -0,0 +1,146 @@
+//! 三件「面」的几何：Snackbar / Dialog / EmptyState（数值与出处见 [`super::geometry`] 的 G17 表）。
+//!
+//! 为什么与进度分家：进度那两个是**带节奏的图形**（keyframes 与相位），这三件是**静态盒子**
+//! （宽高/内距/圆角）。合在一个文件里会顶到 400 行红线（AGENTS.md §3-1）。
+
+use unlucky_design::component_map::Component;
+use unlucky_design::spacing::Space;
+
+use crate::theme::Ui;
+
+/// Snackbar 的几何（G17-c/d + A1 高/内距/上限）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct SnackbarGeometry {
+    /// 最小宽度（344，`[估]`；iced 无 min-width，见组件文档）。
+    pub min_width: f32,
+    /// 最大宽度（600，`[源]` `SnackbarKt.ContainerMaxWidth`）。
+    pub max_width: f32,
+    /// 单行高（48）。
+    pub single_height: f32,
+    /// 双行高（68）。
+    pub two_height: f32,
+    /// 距宿主边距（12，`[规格]`）。
+    pub margin: f32,
+    /// 文本水平内距（16）。
+    pub pad_h: f32,
+    /// 文本垂直内距（6）。
+    pub pad_v: f32,
+    /// 文本 ↔ 动作间距（8）。
+    pub gap: f32,
+    /// 圆角（4）。
+    pub radius: f32,
+}
+
+impl SnackbarGeometry {
+    /// 从令牌求值。
+    pub fn of(ui: &Ui) -> Self {
+        let single_height = 48.0;
+        Self {
+            min_width: 344.0,
+            max_width: 600.0,
+            single_height,
+            two_height: 68.0,
+            margin: ui.space(Space::X3),
+            pad_h: ui.space(Space::X4),
+            pad_v: 6.0,
+            gap: ui.space(Space::X2),
+            radius: Component::Snackbar.spec().shape.radius_px(single_height),
+        }
+    }
+
+    /// 按行数取高：`lines >= 2` → 68，否则 48（官方 `heightIn(min=...)` 的等价口径）。
+    pub fn height_for(&self, lines: u8) -> f32 {
+        if lines >= 2 {
+            self.two_height
+        } else {
+            self.single_height
+        }
+    }
+}
+
+/// Dialog 的几何。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct DialogGeometry {
+    /// 本项目宽度（480，落在官方 280..560 内）。
+    pub width: f32,
+    /// 官方下限（280）。
+    pub min_width: f32,
+    /// 官方上限（560）。
+    pub max_width: f32,
+    /// 圆角（28）。
+    pub radius: f32,
+    /// 四边内边距（24）。
+    pub padding: f32,
+    /// 标题下间距（16）。
+    pub title_gap: f32,
+    /// 正文下间距（24）。
+    pub body_gap: f32,
+    /// 动作主轴间距（8）。
+    pub action_gap: f32,
+    /// 动作交叉间距（12）。
+    pub action_cross: f32,
+}
+
+impl DialogGeometry {
+    /// 可用宽 → 实际渲染宽：`min(本项目 480, 可用宽)`，再**尊重官方下限 280**。
+    ///
+    /// 复审 E：早先 `Dialog::width(200)` 会真的画 200（官方 `DialogMinWidth = 280` 只在测试里）。
+    /// 可用宽 < 280 时仍画 280（**溢出宿主**）—— iced 没有 min-width，这条是 G17-d 之二。
+    pub fn effective_width(&self, available: f32) -> f32 {
+        available.min(self.width).max(self.min_width)
+    }
+
+    /// 从令牌求值（内边距与三个间距全部落在 4px 栅格上 ⇒ 走 `Space`）。
+    pub fn of(ui: &Ui) -> Self {
+        let width = 480.0;
+        Self {
+            width,
+            min_width: 280.0,
+            max_width: 560.0,
+            radius: Component::Dialog.spec().shape.radius_px(width),
+            padding: ui.space(Space::X6),
+            title_gap: ui.space(Space::X4),
+            body_gap: ui.space(Space::X6),
+            action_gap: ui.space(Space::X2),
+            action_cross: ui.space(Space::X3),
+        }
+    }
+}
+
+/// 空态图标边长（`IconSize::Empty` = 32）。
+///
+/// M86 起 `icons::view_at` 会按请求尺寸**重新烘焙 stroke**，所以 32 渲染仍是视觉 1.5px 线宽
+/// （早先 `view` 把 svg 钉成 24，32 的盒子只是居中不拉伸，实渲 24 —— 那个欠账已随 M86 消解）。
+pub const EMPTY_ICON: f32 = 32.0;
+
+/// 空态的几何（**项目自定**：官方没有这个组件；`[估]` 几何 + `[规格]` 排版 + `[源]` CTA）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct EmptyStateGeometry {
+    /// 图标块边长（96）。
+    pub block: f32,
+    /// 图标块圆角（16，`ShapeScale::Large`）。
+    pub block_radius: f32,
+    /// 块内图标（**32**，`IconSize::Empty`；由 `icons::view_at` 按 32 烘焙，stroke 同步重算）。
+    pub icon: f32,
+    /// 块 ↔ 标题（16）。
+    pub gap_title: f32,
+    /// 标题 ↔ 副文案（8）。
+    pub gap_body: f32,
+    /// 副文案 ↔ 动作（24）。
+    pub gap_action: f32,
+}
+
+impl EmptyStateGeometry {
+    /// 从令牌求值（圆角档位与图标档位是真令牌，96 / 三个间距是项目自定）。
+    pub fn of(ui: &Ui) -> Self {
+        let block = 96.0;
+        Self {
+            block,
+            block_radius: Component::EmptyState.spec().shape.radius_px(block),
+            icon: EMPTY_ICON,
+            gap_title: ui.space(Space::X4),
+            gap_body: ui.space(Space::X2),
+            gap_action: ui.space(Space::X6),
+        }
+    }
+}
diff --git a/crates/app-iced/src/components/feedback/pixel.rs b/crates/app-iced/src/components/feedback/pixel.rs
new file mode 100644
index 0000000..704de58
--- /dev/null
+++ b/crates/app-iced/src/components/feedback/pixel.rs
@@ -0,0 +1,280 @@
+//! 像素取证的小工具（**仅测试**）：读 PNG、按「底色 → 墨色」的覆盖率找连通块与长条。
+//!
+//! 为什么不复用 `gallery/scan.rs`：那个模块的可见性是
+//! `pub(in crate::app::components::gallery)`，从家族目录拿不到（`selection/pixel.rs` 也是
+//! 同样的理由自己写了一份）。这里只重写本家族真正用到的几个纯函数。
+//!
+//! **判据口径 1：覆盖率而不是精确色。** 4px 厚的进度条、28 圆角的卡片，边缘全是抗锯齿；
+//! 按「精确色」连通会把它们切碎（实测进度条只剩中间 1~2 行）。
+//! **判据口径 2：覆盖率 ≥50%。** 50% 是几何边界（30% 会把半格抗锯齿也算进去，4px 量成 6）。
+
+use std::path::PathBuf;
+
+use iced::Color;
+
+/// 8bit RGB。
+pub(super) fn rgb(color: Color) -> [u8; 3] {
+    [
+        (color.r * 255.0).round() as u8,
+        (color.g * 255.0).round() as u8,
+        (color.b * 255.0).round() as u8,
+    ]
+}
+
+/// 容差比较（抗锯齿/取整）。
+pub(super) fn matches(pixel: [u8; 3], expected: [u8; 3]) -> bool {
+    pixel.iter().zip(expected).all(|(a, b)| a.abs_diff(b) <= 10)
+}
+
+/// `ULL_GALLERY_SHOT` → 截图路径（相对路径按**工作区根**解释：`cargo test` 的 cwd 是 crate 目录）。
+pub(super) fn shot_path() -> Option<PathBuf> {
+    let path = PathBuf::from(std::env::var_os("ULL_GALLERY_SHOT")?);
+    if path.is_absolute() || path.exists() {
+        return Some(path);
+    }
+    let root = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../..");
+    Some(root.join(path))
+}
+
+/// 一张图的像素访问器。
+pub(super) struct Shot {
+    pub(super) width: usize,
+    pub(super) height: usize,
+    pixels: Vec<[u8; 3]>,
+}
+
+impl Shot {
+    pub(super) fn load(path: &std::path::Path) -> Result<Self, String> {
+        let bytes = std::fs::read(path).map_err(|error| format!("读不动 {path:?}：{error}"))?;
+        let image = image::load_from_memory(&bytes)
+            .map_err(|error| format!("解 PNG 失败：{error}"))?
+            .to_rgb8();
+        let (width, height) = (image.width() as usize, image.height() as usize);
+        Ok(Self {
+            width,
+            height,
+            pixels: image.pixels().map(|p| p.0).collect(),
+        })
+    }
+
+    pub(super) fn at(&self, x: usize, y: usize) -> [u8; 3] {
+        self.pixels[y * self.width + x]
+    }
+}
+
+/// 一个外接框（闭区间）。
+#[derive(Debug, Clone, Copy)]
+pub(super) struct BBox {
+    pub(super) left: usize,
+    pub(super) right: usize,
+    pub(super) top: usize,
+    pub(super) bottom: usize,
+}
+
+impl BBox {
+    pub(super) fn new(x: usize, y: usize) -> Self {
+        Self {
+            left: x,
+            right: x,
+            top: y,
+            bottom: y,
+        }
+    }
+
+    pub(super) fn include(&mut self, x: usize, y: usize) {
+        self.left = self.left.min(x);
+        self.right = self.right.max(x);
+        self.top = self.top.min(y);
+        self.bottom = self.bottom.max(y);
+    }
+
+    pub(super) fn width(&self) -> usize {
+        self.right - self.left + 1
+    }
+
+    pub(super) fn height(&self) -> usize {
+        self.bottom - self.top + 1
+    }
+}
+
+/// 尺寸容差 ±1（rubric §6 的默认容差：控件常落在半像素上，实测会多一行抗锯齿）。
+pub(super) fn near(value: usize, expected: usize) -> bool {
+    value.abs_diff(expected) <= 1
+}
+
+pub(super) fn dims(boxes: &[BBox]) -> String {
+    boxes
+        .iter()
+        .map(|bbox| format!("{}×{}", bbox.width(), bbox.height()))
+        .collect::<Vec<_>>()
+        .join(", ")
+}
+
+/// `pixel` 在「`under` → `fill`」这条混色线上的**覆盖率**（0..1；≥0.5 视为「算这块墨」）。
+///
+/// 投影到混色向量上取比例：抗锯齿像素正好落在 0..1 之间，另一种墨（文字、别的容器色）
+/// 会落在线的两侧偏远处，比例被夹到 0 或 1 之外 → 用「偏离线距离」再筛一道。
+pub(super) fn coverage(pixel: [u8; 3], fill: [u8; 3], under: [u8; 3]) -> f32 {
+    let axis = [0, 1, 2].map(|i| f32::from(fill[i]) - f32::from(under[i]));
+    let offset = [0, 1, 2].map(|i| f32::from(pixel[i]) - f32::from(under[i]));
+    let square: f32 = axis.iter().map(|a| a * a).sum();
+    if square <= f32::EPSILON {
+        return 0.0;
+    }
+    let t: f32 = (0..3).map(|i| axis[i] * offset[i]).sum::<f32>() / square;
+    let distance = (0..3)
+        .map(|i| (offset[i] - t * axis[i]).powi(2))
+        .sum::<f32>()
+        .sqrt();
+    // 8.0 而不是 16.0：深色填充（如 InverseSurface）与浅底之间的混色轴很长，深色**文字**
+    // （OnSurfaceVariant）投影上去残差只有 ≈9 —— 16 的阈值会把文字行算成填充，于是 48 高的
+    // 提示条被切成好几段（实测 46 + 1 + 1）。8.0 只排除文字，保留抗锯齿边（残差 0~3）。
+    if distance > 8.0 {
+        return 0.0;
+    }
+    t.clamp(0.0, 1.0)
+}
+
+/// 第 `y` 行上所有「算 `fill` 那块墨」的连续段 `(起点, 长度)`。
+pub(super) fn runs(shot: &Shot, y: usize, fill: Color, under: Color) -> Vec<(usize, usize)> {
+    let (ink, base) = (rgb(fill), rgb(under));
+    let mut found = Vec::new();
+    let mut start: Option<usize> = None;
+    for x in 0..shot.width {
+        let hit = coverage(shot.at(x, y), ink, base) >= 0.5;
+        match (hit, start) {
+            (true, None) => start = Some(x),
+            (false, Some(from)) => {
+                found.push((from, x - from));
+                start = None;
+            }
+            _ => {}
+        }
+    }
+    if let Some(from) = start {
+        found.push((from, shot.width - from));
+    }
+    found
+}
+
+/// 一行里有多少「算 `fill` 那块墨」的像素（按覆盖率 ≥50% 判）。
+///
+/// 用**计数**而不是「最长段」：一条 344 宽的提示条，里面一行中文字会把它切成几段，
+/// 按最长段判会把中间那些行漏掉（实测 48 高被切成 6 + 6 两段）。
+pub(super) fn row_ink(shot: &Shot, y: usize, fill: Color, under: Color) -> usize {
+    let (ink, base) = (rgb(fill), rgb(under));
+    (0..shot.width)
+        .filter(|x| coverage(shot.at(*x, y), ink, base) >= 0.5)
+        .count()
+}
+
+/// 连续行里「墨量 ≥ `min_ink`」的那些行 → 聚成**竖带** `(top, bottom)`。
+///
+/// 用途：一条 4px 的进度条在图上就是「4 个连续行、每行都有 ~320 个墨点」；
+/// 一个 48 高的提示条就是「48 个连续行」。比按精确色找 bbox 稳得多。
+pub(super) fn bands(shot: &Shot, fill: Color, under: Color, min_ink: usize) -> Vec<(usize, usize)> {
+    let mut bands: Vec<(usize, usize)> = Vec::new();
+    let mut current: Option<usize> = None;
+    for y in 0..shot.height {
+        let hit = row_ink(shot, y, fill, under) >= min_ink;
+        match (hit, current) {
+            (true, None) => current = Some(y),
+            (false, Some(top)) => {
+                bands.push((top, y - 1));
+                current = None;
+            }
+            _ => {}
+        }
+    }
+    if let Some(top) = current {
+        bands.push((top, shot.height - 1));
+    }
+    bands
+}
+
+/// 竖带里最宽的一行的段长：取「每行最长连通段」的最大值。
+///
+/// 为什么要取最大而不是某一行：矩形控件上下有留白行（没文字），只有那几行量得到全宽；
+/// 文字会把中间行切成几段。两条同色矩形并排时，`runs` 分别返回各自的长段，所以也不会串。
+pub(super) fn band_width(shot: &Shot, band: (usize, usize), fill: Color, under: Color) -> usize {
+    (band.0..=band.1)
+        .map(|y| {
+            runs(shot, y, fill, under)
+                .into_iter()
+                .map(|(_, len)| len)
+                .max()
+                .unwrap_or(0)
+        })
+        .max()
+        .unwrap_or(0)
+}
+
+/// 某种颜色的**精确色**连通块（只用于「找着一大块实心」这种粗定位）。
+pub(super) fn blobs(shot: &Shot, color: Color, min_side: usize) -> Vec<BBox> {
+    let target = rgb(color);
+    let mut seen = vec![false; shot.width * shot.height];
+    let mut found = Vec::new();
+    for y in 0..shot.height {
+        for x in 0..shot.width {
+            if seen[y * shot.width + x] || !matches(shot.at(x, y), target) {
+                continue;
+            }
+            let mut stack = vec![(x, y)];
+            seen[y * shot.width + x] = true;
+            let mut bbox = BBox::new(x, y);
+            while let Some((cx, cy)) = stack.pop() {
+                bbox.include(cx, cy);
+                for (nx, ny) in [
+                    (cx + 1, cy),
+                    (cx.saturating_sub(1), cy),
+                    (cx, cy + 1),
+                    (cx, cy.saturating_sub(1)),
+                ] {
+                    let inside = nx < shot.width && ny < shot.height;
+                    if inside && !seen[ny * shot.width + nx] && matches(shot.at(nx, ny), target) {
+                        seen[ny * shot.width + nx] = true;
+                        stack.push((nx, ny));
+                    }
+                }
+            }
+            if bbox.width() >= min_side && bbox.height() >= min_side {
+                found.push(bbox);
+            }
+        }
+    }
+    found
+}
+
+/// 在 `bbox` 内找「最接近 `ink`（而不是 `under`）」的像素外接框（量文字/图标的内缩）。
+pub(super) fn ink_inside(
+    shot: &Shot,
+    bbox: &BBox,
+    ink: Color,
+    under: Color,
+    margin: usize,
+) -> Option<BBox> {
+    let (target, base) = (rgb(ink), rgb(under));
+    let mut found: Option<BBox> = None;
+    for y in (bbox.top + margin)..=(bbox.bottom.saturating_sub(margin)) {
+        for x in (bbox.left + margin)..=(bbox.right.saturating_sub(margin)) {
+            let pixel = shot.at(x, y);
+            let to_ink = pixel
+                .iter()
+                .zip(target)
+                .map(|(a, b)| u32::from(a.abs_diff(b)))
+                .sum::<u32>();
+            let to_base = pixel
+                .iter()
+                .zip(base)
+                .map(|(a, b)| u32::from(a.abs_diff(b)))
+                .sum::<u32>();
+            if to_ink < to_base {
+                match &mut found {
+                    Some(bbox) => bbox.include(x, y),
+                    None => found = Some(BBox::new(x, y)),
+                }
+            }
+        }
+    }
+    found
+}
diff --git a/crates/app-iced/src/components/feedback/probe.rs b/crates/app-iced/src/components/feedback/probe.rs
new file mode 100644
index 0000000..bd88fe2
--- /dev/null
+++ b/crates/app-iced/src/components/feedback/probe.rs
@@ -0,0 +1,342 @@
+//! 反馈家族的**渲染层**几何断言：对着真截图量像素（M68 的教训：纯函数对、图可能是错的）。
+//!
+//! 为什么住在 `feedback/` 而不是 `gallery/`：`gallery/feedback.rs` 只负责把矩阵摆进 harness，
+//! 断言加上去会把它顶到 400 行红线。像素工具在 [`super::pixel`]，环形与两个「面」的判据
+//! 拆在同级子模块 [`circular`] / [`panels`]（`inputs/probe/` 的同一先例）。
+//!
+//! ## 量什么（每条对一个具体错误，打红它的是「变异」那一列）
+//!
+//! | 类 | 判据 | 打红它的变异 |
+//! |---|---|---|
+//! | 线性厚度 / 圆角 | 轨道带**恰好 4 行**；条的四角**透出底色** | 厚度 4→6 / `Full`→`None` |
+//! | 线性不定态 | phase 0.55 列必须**数出两段**（P1-A 回归） | 段不排序（旧实现：两段压成一段） |
+//! | 环形 | 环 40 且四角无墨（真圆） | 直径 40→48 |
+//! | Snackbar 宽上下限 | 宿主 800→**600**、368→**344**、324→**300**（无下限 G17-d） | 上限 600→560 |
+//! | Snackbar 高 | 单行带 **48** / 双行带 **68** | 48→40 |
+//! | Dialog 宽 / 内距 | 最宽行 **480**（在 280..560 内）· 标题墨迹左缩 **≈24**、顶缩 **≈26** | 480→488 / pad 24→16 |
+//! | 空态块 / 间距 / CTA | 块 **96×96** · 块↔标题 **≈16**+bearing · 条目总高 **≈232** · CTA **40** | 96→88 / spacing 双算回来 |
+//! | scrim | 一块 ≥700 宽的遮罩带，颜色 = 预合成实色 | 遮罩改成 surface |
+//!
+//! ## 复现（worktree 根目录；四个部分各一张图，浅/深各一轮）
+//!
+//! ```text
+//! for part in progress snackbar dialog empty; do
+//!   ULL_GALLERY_SECTION=feedback ULL_FEEDBACK_PART=$part \
+//!     ./target/debug/unlucky-launcher-iced --software-renderer --screen=gallery \
+//!     --screenshot target/m78/$part-light.png --screenshot-theme=light
+//!   ULL_FEEDBACK_PART=$part ULL_GALLERY_SHOT=target/m78/$part-light.png \
+//!     cargo test -p unlucky-app-iced feedback::probe
+//! done
+//! ```
+
+mod circular;
+mod panels;
+
+use unlucky_design::color::{Role, SchemeFlavor};
+use unlucky_design::typography::Platform;
+
+use super::geometry::PHASE_055;
+use super::pixel::{band_width, bands, matches, near, rgb, runs, shot_path, Shot};
+use crate::theme::{Families, Ui};
+
+const FAMILIES: Families = Families {
+    text: "Segoe UI",
+    display: "Segoe UI",
+    mono: "Consolas",
+};
+
+fn ui(flavor: SchemeFlavor) -> Ui {
+    Ui::with_platform(flavor, Platform::Windows, FAMILIES)
+}
+
+/// 第三条（phase 0.55）线性轨道的左缘与宽度（gallery 的宿主尺寸：页内边距 24 + 2×332）。
+const TRACK3_X0: usize = 688;
+/// 单条轨道宽（gallery 的 `TRACK_HOST`）。
+const TRACK3_W: usize = 320;
+
+/// 一条测试覆盖当前截图对应的那一段（段由 `ULL_FEEDBACK_PART` 指定，默认 `all`）。
+#[test]
+fn feedback_geometry_matches_the_reference() {
+    let Some(path) = shot_path() else {
+        eprintln!(
+            "[feedback-probe] SKIPPED：未设置 ULL_GALLERY_SHOT。这是**渲染层**几何断言，\
+             需要先出图（命令见本文件模块文档，注意 ULL_GALLERY_SECTION=feedback + ULL_FEEDBACK_PART）。"
+        );
+        return;
+    };
+    let shot = Shot::load(&path).expect("读 feedback 截图");
+    assert_eq!(
+        (shot.width, shot.height),
+        (1180, 760),
+        "验收图必须 1180×760 @100% DPI"
+    );
+
+    let flavor = if matches(
+        shot.at(2, 2),
+        rgb(ui(SchemeFlavor::Light).color(Role::Surface)),
+    ) {
+        SchemeFlavor::Light
+    } else {
+        SchemeFlavor::Dark
+    };
+    let ui = ui(flavor);
+    let part = std::env::var("ULL_FEEDBACK_PART").unwrap_or_else(|_| "all".to_owned());
+    let part = part.trim().to_ascii_lowercase();
+
+    match part.as_str() {
+        "progress" => {
+            check_linear(&shot, &ui);
+            circular::check(&shot, &ui);
+        }
+        "snackbar" => check_snackbar(&shot, &ui),
+        "dialog" => panels::check_dialog(&shot, &ui),
+        "empty" => panels::check_empty(&shot, &ui),
+        other => {
+            // 整屏时只查最不容易被折叠线切掉的那一类；分图才是逐项判据的场合。
+            check_linear(&shot, &ui);
+            eprintln!("[feedback-probe] part={other:?} 只查了 progress 那一类；其余请在分图里查");
+        }
+    }
+
+    eprintln!("[feedback-probe] OK flavor={flavor:?} part={part}");
+}
+
+/// §12.1 + §12.4：线性厚度 / 圆角 / **不定态两段**。
+fn check_linear(shot: &Shot, ui: &Ui) {
+    // 参考值写字面量（A1）：**不能**从 `LinearGeometry` 读回期望值——那样把 4 改成 6 之后
+    // 「实测 6 == 期望 6」会照样绿，等于没有断言。
+    let surface = ui.color(Role::Surface);
+    let track = ui.color(Role::SecondaryContainer);
+    let active = ui.color(Role::Primary);
+
+    // ---- 12.1 厚度：轨道带恰好 4 行（宿主 320 宽 ⇒ 每行 ~320 个轨道墨点）--------
+    let bar_bands = bands(shot, track, surface, 300);
+    assert!(
+        !bar_bands.is_empty(),
+        "没找到线性进度轨道（宿主宽 320，应有 ≥300 个墨点的行）"
+    );
+    for (top, bottom) in &bar_bands {
+        let height = bottom - top + 1;
+        assert!(
+            near(height, 4),
+            "12.1：线性进度厚必须 4（A1 Height；实测 {height} @ 行 {top}）"
+        );
+    }
+
+    // ---- 12.1 圆角 full：条的四角必须透出底色（直角会把角填满）------------------
+    let (top, _) = bar_bands[0];
+    let (left, len) = runs(shot, top + 1, track, surface)
+        .into_iter()
+        .find(|(_, len)| *len >= 300)
+        .expect("轨道那一行必须有 ≥300 的长段");
+    assert!(
+        !matches(shot.at(left, top), rgb(track)),
+        "12.1：圆角 full(2) 的左上角必须透出底色（直角会填满）"
+    );
+    assert!(
+        matches(shot.at(left + len / 2, top + 1), rgb(track)),
+        "条的中间必须有墨（否则是没画出来，不是圆角）"
+    );
+
+    // ---- 12.4 不定态：phase 0.55 那一列必须**数出两段**（复审 P1-A 的回归断言）----
+    //
+    // 旧实现把两段按返回顺序铺 `FillPortion`（第一线在右、第二线在左），并且份额之和
+    // 在某 34/100 相位上 >1，被 iced 归一 ⇒ 图上只剩一段 100px 的台阶（x 749..848）。
+    let row = indeterminate_row(shot, active, surface);
+    let found: Vec<(usize, usize)> = runs(shot, row, active, surface)
+        .into_iter()
+        .filter(|(start, len)| {
+            *start >= TRACK3_X0 && start + len <= TRACK3_X0 + TRACK3_W + 2 && *len >= 8
+        })
+        .collect();
+    assert_eq!(
+        found.len(),
+        2,
+        "12.4：phase 0.55 必须是**两段**（P1-A 修完才成立），实测 {found:?} @ 行 {row}"
+    );
+
+    // 期望位置与单测**共用同一个常量**（`geometry::PHASE_055`）：早先这里写 0.871、单测写
+    // 0.860，实测 963 距 want_end 966.7 只剩 0.28px，靠容差活着（复审 B）。
+    let expected = PHASE_055;
+    for (index, (start, len)) in found.iter().enumerate() {
+        let want_start = TRACK3_X0 as f32 + expected[index].0 * TRACK3_W as f32;
+        let want_end = TRACK3_X0 as f32 + expected[index].1 * TRACK3_W as f32;
+        assert!(
+            (*start as f32 - want_start).abs() <= 4.0,
+            "12.4 第 {} 段左端应在 {want_start:.1}（实测 {start}）",
+            index + 1
+        );
+        assert!(
+            ((start + len) as f32 - want_end).abs() <= 4.0,
+            "12.4 第 {} 段右端应在 {want_end:.1}（实测 {}）",
+            index + 1,
+            start + len
+        );
+    }
+
+    eprintln!(
+        "[feedback-probe] progress：轨道带 {} 条（高 {:?}）· phase 0.55 两段 {found:?}",
+        bar_bands.len(),
+        bar_bands
+            .iter()
+            .map(|(top, bottom)| bottom - top + 1)
+            .collect::<Vec<_>>(),
+    );
+}
+
+/// 线性不定态那一行的 y：主色墨迹在**第一条轨道**里出现、且不在确定态行的最上一组。
+///
+/// 不想硬编码坐标（gallery 一改间距就失准），所以按「主色横带 + 排除最高那条带」找。
+fn indeterminate_row(shot: &Shot, active: iced::Color, surface: iced::Color) -> usize {
+    let found = bands(shot, active, surface, 20);
+    assert!(
+        found.len() >= 2,
+        "至少要找到确定态行与不定态行两组主色横带，实测 {found:?}"
+    );
+    // 第一组是确定态（0% 无墨、50%/100% 有墨），第二组是不定态
+    let (top, bottom) = found[1];
+    (top + bottom) / 2
+}
+
+/// §14：宽度上下限 + 单/双行高。
+fn check_snackbar(shot: &Shot, ui: &Ui) {
+    // 参考值写字面量（A1）：600 = SnackbarKt.ContainerMaxWidth，48/68 = SnackbarTokens。
+    let surface = ui.color(Role::Surface);
+    let bar = ui.color(Role::InverseSurface);
+
+    // 行墨量下限 200：最窄的那条只有 300 宽，里面还有 ~60px 的文字 ⇒ 每行 ~240 个实心点。
+    // 高度 ≥40 才算提示条（标题行偶有一两行落在这条混色线上，那类 1 行的带要滤掉）。
+    let found: Vec<(usize, usize)> = bands(shot, bar, surface, 200)
+        .into_iter()
+        .filter(|(top, bottom)| bottom - top + 1 >= 40)
+        .collect();
+    assert!(
+        found.len() >= 3,
+        "14.x：应有 ≥3 条提示条（上限宽 / 双行 / 两条窄的），实测 {}",
+        found.len()
+    );
+
+    // 宽度集 = 每条带里最宽的那一行（留白行没有文字，量得到全宽）。
+    let mut widths: Vec<usize> = found
+        .iter()
+        .map(|band| band_width(shot, *band, bar, surface))
+        .collect();
+    let mut heights: Vec<usize> = found.iter().map(|(top, bottom)| bottom - top + 1).collect();
+    widths.sort_unstable();
+    heights.sort_unstable();
+
+    assert!(
+        !widths.iter().any(|w| *w > 601),
+        "没有一条可以超过上限 600：实测 {widths:?}"
+    );
+    assert!(
+        widths.iter().any(|w| near(*w, 600)),
+        "上限宽必须是 600（SnackbarKt.ContainerMaxWidth，宿主 800 时夹取），实测宽度集 {widths:?}"
+    );
+    assert!(
+        widths.iter().any(|w| near(*w, 344)),
+        "宿区 368 那格必须量到 344（G17-d [估] 最小宽口径），实测 {widths:?}"
+    );
+    assert!(
+        widths.iter().any(|w| near(*w, 300)),
+        "宿区 324 那格必须量到 300（组件没有 min-width，G17-d），实测 {widths:?}"
+    );
+    assert!(
+        heights.iter().any(|h| near(*h, 48)),
+        "14.3：单行高 48，实测高度集 {heights:?}"
+    );
+    assert!(
+        heights.iter().any(|h| near(*h, 68)),
+        "14.3：双行高 68，实测高度集 {heights:?}"
+    );
+
+    // 14.6 动作色：`InversePrimary` 必须出现在提示条内（不是按钮家族的 OnSurfaceVariant）
+    let action = rgb(ui.color(Role::InversePrimary));
+    let action_pixels: usize = (0..shot.height)
+        .map(|y| {
+            (0..shot.width)
+                .filter(|x| matches(shot.at(*x, y), action))
+                .count()
+        })
+        .sum();
+    assert!(
+        action_pixels > 40,
+        "14.6：动作标签应是 InversePrimary（实测该色只有 {action_pixels} px）"
+    );
+
+    // ---- 位置语义（复审 D）：两条 bottom 条的**条底距取景框底 = 12** ---------------
+    //
+    // 取景框是 gallery 给窄宿主画的 1px `OutlineVariant` 边（`framed_host`）：透明宿主没有
+    // 可见底边时「贴底」在像素上不可证（旧宿主 72 = 48 + 2×12，上下留白相等）。
+    let frame = rgb(ui.color(Role::OutlineVariant));
+    let mut margins: Vec<usize> = Vec::new();
+    for (top, bottom) in &found {
+        let width = band_width(shot, (*top, *bottom), bar, surface);
+        if !(near(width, 300) || near(width, 344)) {
+            continue;
+        }
+        // 1px 描边常落在半像素上（两行各 ~50% 覆盖），精确色匹配抓不住 ⇒ 用「更靠近框色
+        // 而不是画布」判。但条自身（深色）比画布**更接近**框色，所以还要一条：这一行的
+        // 框色连续段必须**比条本身更宽**（框横贯整个宿主），否则会认成条自己（实测过：差值 1）。
+        let distance = |pixel: [u8; 3], target: [u8; 3]| -> u32 {
+            pixel
+                .iter()
+                .zip(target)
+                .map(|(a, b)| u32::from(a.abs_diff(b)))
+                .sum()
+        };
+        let surface_rgb = rgb(surface);
+        let frame_run = |y: usize| -> usize {
+            let mut longest = 0;
+            let mut current = 0;
+            for x in 0..shot.width {
+                let pixel = shot.at(x, y);
+                if distance(pixel, frame) < distance(pixel, surface_rgb) {
+                    current += 1;
+                    longest = longest.max(current);
+                } else {
+                    current = 0;
+                }
+            }
+            longest
+        };
+        // 框的横贯长度 > 条宽 + 10 ⇒ 只有框那一两行满足
+        let is_frame_row = |y: usize| frame_run(y) >= width + 10;
+
+        let frame_row = ((bottom + 1)..shot.height)
+            .find(|y| is_frame_row(*y))
+            .unwrap_or_else(|| {
+                panic!("D：窄条下方没找到宿主取景框（条 y {top}..{bottom}，宽 {width}）")
+            });
+        let frame_top_row = (0..*top)
+            .rev()
+            .find(|y| is_frame_row(*y))
+            .unwrap_or_else(|| panic!("D：窄条上方没找到宿主取景框（条顶 y {top}）"));
+        // 复审 P2-1：宿高回退到 72（上下留白相等）时这条会红。
+        assert!(
+            (*top as i64 - frame_top_row as i64 - 36).abs() <= 1,
+            "D：贴底 ⇒ 框顶到条顶应为 36（96 − 48 − 12），实测 {}",
+            *top as i64 - frame_top_row as i64
+        );
+        let frame_height = frame_row - frame_top_row + 1;
+        assert!(
+            frame_height.abs_diff(96) <= 1,
+            "D：取景框高应 96（宿主高），实测 {frame_height}"
+        );
+        margins.push(frame_row - bottom);
+    }
+    assert!(
+        !margins.is_empty(),
+        "D：应至少量到一条 bottom 条的宿主边距，实测 {margins:?}"
+    );
+    for margin in &margins {
+        assert!(
+            near(*margin, 12),
+            "D：贴底 ⇒ 条底距宿主底 12（官方外边距），实测 {margin}：{margins:?}"
+        );
+    }
+
+    eprintln!(
+        "[feedback-probe] snackbar：宽度集 {widths:?} · 高度集 {heights:?} ·          InversePrimary {action_pixels}px · 底边距 {margins:?}"
+    );
+}
diff --git a/crates/app-iced/src/components/feedback/probe/circular.rs b/crates/app-iced/src/components/feedback/probe/circular.rs
new file mode 100644
index 0000000..42e7a7a
--- /dev/null
+++ b/crates/app-iced/src/components/feedback/probe/circular.rs
@@ -0,0 +1,158 @@
+//! 环形进度的渲染层判据（`probe` 的子模块，`inputs/probe/` 的同一先例）。
+//!
+//! ## 判据：六个**固定窗**逐个测存在性与尺寸
+//!
+//! gallery 里这一排环在**固定 x 栅格**上：左缘 `24 + 56·i`（环宽 40、间距 16），共 6 个
+//! （0% / 25% / 50% / 75% / 100% / ind 0.30）。判据是「每个窗里都必须有一圈
+//! **40(±2)×40(±2)** 的墨迹（轨道 ∪ 激活色的并集）」：
+//!
+//! - 少一个环 → 该窗没有墨迹 → 红；
+//! - 某个环被画小了（例如 20×20）→ 该窗墨迹的外接框变小 → 红；
+//! - 0% 那格只有轨道、没有激活色 → 用「并集」判，不把「没有激活色」当失败。
+//!
+//! 早先用「主色连通簇数」判（只要求非空）：把 5 个环涂掉仍然绿（复审 r3 P2-3 的反证），
+//! 所以 G18-i 的处置从「不修」改成**已用固定窗收口**。簇数仍在日志里打印供复核。
+//!
+//! 不定态的**节奏**（4 圈/周期、跨周期不跳变）不在这里量：那是时间的函数，截图只有一帧，
+//! 判据在 `tests/progress.rs::circular_indeterminate_rotation_is_four_turns_and_continuous`。
+//!
+//! 欠账 **G18-l**（登记不修）：`snackbar` 的「取景框」判据会把条自身的抗锯齿底行算成框
+//! （覆盖率 0.5008，余量 0.0008），方向是**误报**不是假绿；本轮给 snackbar 加了「框高 = 96」
+//! 之后触发概率下降，但那 0.0008 的余量仍在。
+
+use iced::Color;
+
+use super::super::pixel::{blobs, coverage, dims, rgb, BBox, Shot};
+use unlucky_design::color::Role;
+
+use crate::theme::Ui;
+
+/// 环直径（A1 `CircularProgressIndicatorTokens.Size = 40`）。
+const DIAMETER: usize = 40;
+/// 环排栅格的左缘（页内边距 24）。
+const RING_X0: usize = 24;
+/// 栅格间距（40 环 + 16 = `Space::X4`）。
+const RING_PITCH: usize = 56;
+/// 窗数（0 / 25 / 50 / 75 / 100 / ind）。
+const RINGS: usize = 6;
+
+/// 某个像素算不算「这块墨」（覆盖率 ≥50%，与 `pixel::runs` 同一口径）。
+fn is_ink(pixel: [u8; 3], fill: Color, under: Color) -> bool {
+    coverage(pixel, rgb(fill), rgb(under)) >= 0.5
+}
+
+/// 环形那一排的判据：逐窗测「有没有一圈 40×40 的墨迹」。
+pub(super) fn check(shot: &Shot, ui: &Ui) {
+    let active = ui.color(Role::Primary);
+    let track = ui.color(Role::SecondaryContainer);
+    let surface = ui.color(Role::Surface);
+
+    // 环带的 y：以第一个窗（0% 环，只有轨道色）的**圆环签名**定位 —— 中间那几十行在窗的
+    // 左右两侧都有墨迹；再向上/下各扩到「窗内还有墨」为止（把圆顶/圆底那两行收回来）。
+    //
+    // 为什么不按「每行墨点数 4..20」判：圆顶那一行笔画横跨 ~20~28 px，会落在区间外，
+    // 按连续段会把 40 高的带子切成 32 行；为什么不按「首行..末行」：深色档里正文的抗锯齿
+    // 像素也会落在轨道色的混色线上，跨度会扩到 274 行（两种都实测过）。
+    let ink_count = |y: usize, from: usize, to: usize| -> usize {
+        (from..to)
+            .filter(|x| is_ink(shot.at(*x, y), track, surface))
+            .count()
+    };
+    let left = RING_X0;
+    let right = RING_X0 + DIAMETER;
+
+    // 环带 = 第一个窗里「有墨」的**连续行组**中、高度 ≈40 的那一组。
+    //
+    // 走过的两条弯路都实测过：
+    // ①「每行墨点 4..20」→ 圆顶那一行笔画横跨 ~20~28 px，被排除，带子切成 32 行；
+    // ②「左右两侧都有墨」→ 进度条那一行也满足（通栏），会认成 4 行高的假带。
+    // 连续行组 + 高度窗口同时把「进度条」（4~5 行）与「正文行」排除在外。
+    let mut runs: Vec<(usize, usize)> = Vec::new();
+    let mut current: Option<(usize, usize)> = None;
+    for y in 0..shot.height {
+        match (ink_count(y, left, right) > 0, current) {
+            (true, None) => current = Some((y, y)),
+            (true, Some((top, _))) => current = Some((top, y)),
+            (false, Some(run)) => {
+                runs.push(run);
+                current = None;
+            }
+            (false, None) => {}
+        }
+    }
+    if let Some(run) = current {
+        runs.push(run);
+    }
+    let (top, bottom) = runs
+        .iter()
+        .copied()
+        .find(|(top, bottom)| (DIAMETER - 6..=DIAMETER + 6).contains(&(bottom - top + 1)))
+        .unwrap_or_else(|| panic!("没找到高约 {DIAMETER} 的环形带；窗口 0 的连续行组：{runs:?}"));
+
+    let mut report = Vec::new();
+    for index in 0..RINGS {
+        let left = RING_X0 + RING_PITCH * index;
+        let right = left + DIAMETER - 1;
+        let mut ink: Option<BBox> = None;
+        for y in top..=bottom {
+            for x in left..=right {
+                let pixel = shot.at(x, y);
+                if is_ink(pixel, active, surface) || is_ink(pixel, track, surface) {
+                    match &mut ink {
+                        Some(found) => found.include(x, y),
+                        None => {
+                            ink = Some(BBox {
+                                left: x,
+                                right: x,
+                                top: y,
+                                bottom: y,
+                            })
+                        }
+                    }
+                }
+            }
+        }
+        let ink = ink.unwrap_or_else(|| {
+            panic!("第 {index} 个窗（x {left}..{right}）里没有任何环墨迹：环丢了")
+        });
+        assert!(
+            (DIAMETER - 2..=DIAMETER + 2).contains(&ink.width())
+                && (DIAMETER - 2..=DIAMETER + 2).contains(&ink.height()),
+            "第 {index} 个窗（x {left}..{right}）里的环应 {DIAMETER}×{DIAMETER}(±2)，实测 {}×{}",
+            ink.width(),
+            ink.height()
+        );
+        assert!(
+            ink.left >= left && ink.right <= right,
+            "第 {index} 个窗的墨迹越界：{}..{} 不在 {left}..{right}",
+            ink.left,
+            ink.right
+        );
+        report.push(format!("{index}:{}×{}", ink.width(), ink.height()));
+    }
+
+    // 激活色（弧）必须出现在 1.. 号窗里（0% 那格本来就只有轨道）。
+    for index in 1..RINGS {
+        let left = RING_X0 + RING_PITCH * index;
+        let count: usize = (top..=bottom)
+            .map(|y| {
+                (left..left + DIAMETER)
+                    .filter(|x| is_ink(shot.at(*x, y), active, surface))
+                    .count()
+            })
+            .sum();
+        assert!(
+            count > 40,
+            "第 {index} 个窗（x {left}..）的激活色弧只有 {count} px：环在但弧没画"
+        );
+    }
+
+    let clusters = blobs(shot, active, 10);
+    eprintln!(
+        "[feedback-probe] circular：固定窗 {RINGS} 个逐窗 [{ }]（y {top}..{bottom}）· \
+         主色连通簇 {} 个（仅打印，判据是窗）",
+        report.join(" / "),
+        clusters.len()
+    );
+    let _ = dims(&clusters);
+}
diff --git a/crates/app-iced/src/components/feedback/probe/panels.rs b/crates/app-iced/src/components/feedback/probe/panels.rs
new file mode 100644
index 0000000..76a3df9
--- /dev/null
+++ b/crates/app-iced/src/components/feedback/probe/panels.rs
@@ -0,0 +1,315 @@
+//! 两个「面」的渲染层判据：Dialog（§7）与空态（§15）。`probe` 的子模块。
+//!
+//! ## Dialog 量什么
+//!
+//! - **逐卡宽度**：按列剖面把每张卡单独量出来（早先只量「最宽那张」，一宽一窄并排时会漏）；
+//!   本项目 480，窄宿主那格 360（`Dialog::width(360)`），且都必须落在官方 280..560 内；
+//! - 内距：标题墨迹左缩 ≈24、顶缩 24+bearing（24..=30）；
+//! - **动作色**：`Role::Primary` 的**精确色**命中数（复审 A：早先用「离谁更近」把标题/正文字形
+//!   也算成了 Primary —— 一张没有动作的卡也能"通过"）；并配两条反向证据：
+//!   ①无动作的那张卡里精确 Primary 必须是 **0**；②有动作的那张卡下半区必须有字形行。
+//! - scrim：一块 ≥700 宽的遮罩带，色值 = 预合成实色。
+//!
+//! ## 空态量什么
+//!
+//! 图标块 96±2（1px 描边各吃 1 行）· 块↔标题 ≈16+bearing · 条目总高 ≈232 · CTA 40。
+//!
+//! 常量与 [`super::super::panel`] 里登记值对齐（480 / 280 / 96 / 232），动作色用**精确色**
+//! 而不是斜坡判据。
+
+use unlucky_design::color::Role;
+use unlucky_design::elevation::MaterialLayer;
+
+use super::super::dialog::scrim;
+use super::super::empty_state::BLOCK_LAYER;
+use super::super::pixel::{band_width, bands, ink_inside, matches, near, rgb, BBox, Shot};
+use crate::theme::Ui;
+
+/// Dialog 宽（本项目取值，官方区间 280..560 内）。
+const DIALOG_W: usize = 480;
+/// 窄宿主那格的宽（`Dialog::width(360)`）。
+const DIALOG_NARROW: usize = 360;
+/// 空态图标块边长。
+const BLOCK: usize = 96;
+/// 空态条目总高：96 块 + 16 + 32 标题 + 8 + 16 副文案 + 24 + 40 CTA。
+const EMPTY_TOTAL: usize = 232;
+/// 动作字形的精确色命中下限（实测 3 张有动作的卡合计 325 px）。
+const ACTION_INK_MIN: usize = 120;
+
+/// §7：逐卡宽度 / 内距 / 动作色 / scrim。
+pub(super) fn check_dialog(shot: &Shot, ui: &Ui) {
+    let surface = ui.color(Role::Surface);
+    let card = ui.layer(MaterialLayer::Overlay);
+    let primary = rgb(ui.color(Role::Primary));
+
+    // ---- 7.4 宽度：先分「卡带」（同排两张卡的 y 区间会重叠，所以只能按行分组），
+    //      再在每条带里按**列剖面**分出每一张卡（复审 A/G：早先只量最宽的那张）。
+    // 卡带用**精确色**数行（不用斜坡）：深色档里正文/描边的抗锯齿像素都落在
+    // 「surface → card」那条很短的斜坡上，用斜坡会把整屏都算成卡带（实测出现 1180 宽的假卡）。
+    let card_rgb = rgb(card);
+    let scrim_rgb = rgb(scrim(ui));
+    let card_rows: Vec<usize> = (0..shot.height)
+        .filter(|y| {
+            (0..shot.width)
+                .filter(|x| {
+                    let pixel = shot.at(*x, *y);
+                    matches(pixel, card_rgb) && !matches(pixel, scrim_rgb)
+                })
+                .count()
+                >= 200
+        })
+        .collect();
+    let mut card_bands: Vec<(usize, usize)> = Vec::new();
+    let mut start: Option<usize> = None;
+    let mut previous: usize = 0;
+    for y in card_rows {
+        match start {
+            None => {
+                start = Some(y);
+                previous = y;
+            }
+            Some(_) if y == previous + 1 => previous = y,
+            Some(top) => {
+                card_bands.push((top, previous));
+                start = Some(y);
+                previous = y;
+            }
+        }
+    }
+    if let Some(top) = start {
+        card_bands.push((top, previous));
+    }
+    assert!(
+        card_bands.len() >= 3,
+        "至少要找到 3 条卡带（第一排两张 + 双动作 + scrim 里那张），实测 {card_bands:?}"
+    );
+
+    // 每张卡记 (左缘, 宽)：宽度给「逐卡」断言，左缘给内距断言用（不能按单行找左缘——
+    // 圆角 28 会让 band_top+4 那一行的卡片像素内缩 ~10px，实测内距被量成 12 而不是 24）。
+    //
+    // **深色档要把遮罩色排掉**：暗色下 `SurfaceContainerHigh` 与预合成 scrim 只差 ~35/通道，
+    // 不排掉时 scrim 那片也被算成「卡」（实测出现 1180 宽的假卡）。
+    let mut cards: Vec<(usize, usize)> = Vec::new();
+    for band in &card_bands {
+        let height = band.1 - band.0 + 1;
+        let profile: Vec<usize> = (0..shot.width)
+            .map(|x| {
+                (band.0..=band.1)
+                    .filter(|y| {
+                        let pixel = shot.at(x, *y);
+                        matches(pixel, card_rgb) && !matches(pixel, scrim_rgb)
+                    })
+                    .count()
+            })
+            .collect();
+        let mut start: Option<usize> = None;
+        for (x, ink) in profile.iter().enumerate() {
+            let column = *ink >= height / 3;
+            match (column, start) {
+                (true, None) => start = Some(x),
+                (false, Some(from)) => {
+                    if x - from >= 280 {
+                        cards.push((from, x - from));
+                    }
+                    start = None;
+                }
+                _ => {}
+            }
+        }
+        if let Some(from) = start {
+            if shot.width - from >= 280 {
+                cards.push((from, shot.width - from));
+            }
+        }
+    }
+    let mut widths: Vec<usize> = cards.iter().map(|(_, width)| *width).collect();
+    widths.sort_unstable();
+    assert!(
+        widths.iter().any(|w| near(*w, DIALOG_W)),
+        "7.4：应有 {DIALOG_W} 宽的卡（G17-e 项目取值），实测逐卡宽度 {widths:?}"
+    );
+    assert!(
+        widths.iter().any(|w| near(*w, DIALOG_NARROW)),
+        "7.4：窄宿主那格应量到 {DIALOG_NARROW}（`Dialog::width(360)`，复审 E），实测 {widths:?}"
+    );
+    for width in &widths {
+        assert!(
+            (280..=560).contains(width),
+            "7.4：每张卡都必须落在官方 280..560 内，实测 {width}：{widths:?}"
+        );
+    }
+
+    // 内距与 scrim 只在一张卡上量（第一张，最靠左上）。
+    let first = card_bands[0];
+    let (card_left, width) = cards[0];
+    let top = first.0;
+    let bottom = first.1;
+    let bbox = BBox {
+        left: card_left,
+        right: card_left + width - 1,
+        top,
+        bottom,
+    };
+    let title =
+        ink_inside(shot, &bbox, ui.color(Role::OnSurface), card, 2).expect("卡片里必须有标题墨迹");
+    let inset = title.left.saturating_sub(card_left);
+    assert!(
+        (22..=28).contains(&inset),
+        "7.3：四边内距 24 ⇒ 标题墨迹左缩 ≈24（含 bearing 22..28），实测 {inset}"
+    );
+    let top_inset = title.top.saturating_sub(top);
+    assert!(
+        (24..=30).contains(&top_inset),
+        "7.3：上内距 24 ⇒ 标题墨迹顶缩 24+字形 bearing（24..30），实测 {top_inset}"
+    );
+
+    // ---- 7.6 动作色（复审 A：换掉「离谁更近」那条会被标题字形顶账的判据）--------
+    let exact_primary = |band: (usize, usize)| -> usize {
+        (band.0..=band.1)
+            .map(|y| {
+                (0..shot.width)
+                    .filter(|x| matches(shot.at(*x, y), primary))
+                    .count()
+            })
+            .sum()
+    };
+    let action_pixels: usize = (0..shot.height)
+        .map(|y| {
+            (0..shot.width)
+                .filter(|x| matches(shot.at(*x, y), primary))
+                .count()
+        })
+        .sum();
+    assert!(
+        action_pixels >= ACTION_INK_MIN,
+        "7.6：Dialog 动作标签应是 `Primary` 的**精确色**（实测只命中 {action_pixels} px；\
+         改成 OnSurfaceVariant 就会掉到 0）"
+    );
+
+    // 反向证据 ①：没有动作的那张卡（scrim 里那张）里精确 Primary 必须是 0 ——
+    // 这条挡住「把标题/正文的深色字形算成 Primary」这条假绿路径。
+    let quiet: Vec<(usize, usize)> = card_bands
+        .iter()
+        .copied()
+        .filter(|band| exact_primary(*band) == 0)
+        .collect();
+    assert!(
+        !quiet.is_empty(),
+        "7.6：本屏应有一张**无动作**的卡（scrim 里那张）其精确 Primary 为 0，实测每带都有 Primary 墨迹"
+    );
+
+    // 反向证据 ②：动作行确实存在 —— 命中最多的那条带下半区必须有字形行。
+    let loud = card_bands
+        .iter()
+        .copied()
+        .max_by_key(|band| exact_primary(*band))
+        .expect("卡带非空");
+    let half = loud.0 + (loud.1 - loud.0) / 2;
+    let action_rows = (half..=loud.1)
+        .filter(|y| {
+            (0..shot.width)
+                .filter(|x| matches(shot.at(*x, *y), primary))
+                .count()
+                >= 3
+        })
+        .count();
+    assert!(
+        action_rows >= 1,
+        "7.6：动作字形必须在卡片下半区（实测下半区精确 Primary 行数 {action_rows}）"
+    );
+
+    // ---- 7.7 scrim -------------------------------------------------------------
+    let backdrop = scrim(ui);
+    let scrim_bands = bands(shot, backdrop, surface, 700);
+    assert!(
+        !scrim_bands.is_empty(),
+        "7.7：没找到 ≥700 宽的遮罩带（宿主 800 宽那格）"
+    );
+
+    eprintln!(
+        "[feedback-probe] dialog：逐卡宽度 {widths:?} · 标题左缩 {inset} · 顶缩 {top_inset} · \
+         精确 Primary {action_pixels}px（无动作卡 {} 张）· 动作行 {action_rows} 行 · scrim 带 {} 条",
+        quiet.len(),
+        scrim_bands.len()
+    );
+}
+
+/// §15：图标块 96（`[估]`）+ 间距 16 / 8 / 24 + CTA 40。
+pub(super) fn check_empty(shot: &Shot, ui: &Ui) {
+    let surface = ui.color(Role::Surface);
+    let block = ui.layer(BLOCK_LAYER);
+
+    let found = bands(shot, block, surface, 40);
+    let (top, bottom) = found
+        .iter()
+        .copied()
+        .max_by_key(|(top, bottom)| bottom - top)
+        .filter(|(top, bottom)| (BLOCK - 2..=BLOCK + 2).contains(&(bottom - top + 1)))
+        .unwrap_or_else(|| {
+            panic!(
+                "15.1：没找到高 {BLOCK}(±2) 的图标块（`[估]` 项目自定值），实测量到的带：{found:?}"
+            )
+        });
+
+    let width = band_width(shot, (top, bottom), block, surface);
+    assert!(
+        (BLOCK - 2..=BLOCK + 2).contains(&width),
+        "15.1：图标块必须 {BLOCK}(±2，1px 描边）宽，实测 {width}"
+    );
+
+    // 图标本身：`view_at` 按 32 烘焙（stroke 同步重算），墨迹 ≈26~28。
+    let glyph = ink_inside(
+        shot,
+        &BBox {
+            left: 0,
+            right: shot.width - 1,
+            top,
+            bottom,
+        },
+        ui.color(Role::OnSurfaceVariant),
+        block,
+        2,
+    )
+    .expect("块里必须有图标墨迹");
+    assert!(
+        (22..=34).contains(&glyph.width()) && (22..=34).contains(&glyph.height()),
+        "15.1：图标墨迹应在 22..34（32 盒；`view` 时代只有 20×20），实测 {}×{}",
+        glyph.width(),
+        glyph.height()
+    );
+
+    // ---- P2-1 回归：块↔标题的实际间距（16 而不是 32）---------------------------
+    let bbox = BBox {
+        left: 0,
+        right: shot.width - 1,
+        top: bottom + 1,
+        bottom: shot.height - 1,
+    };
+    let title = ink_inside(shot, &bbox, ui.color(Role::OnSurface), surface, 0)
+        .expect("块下面必须有标题墨迹");
+    let gap = title.top.saturating_sub(bottom + 1);
+    assert!(
+        (16..=24).contains(&gap),
+        "15.3：块↔标题应为 16（+ 字形 bearing），实测 {gap}（32 = spacing 与 gap 双算回来了）"
+    );
+
+    let cta = bands(shot, ui.color(Role::Primary), surface, 20);
+    let (cta_top, cta_bottom) = cta
+        .iter()
+        .copied()
+        .find(|(top, bottom)| near(bottom - top + 1, 40))
+        .unwrap_or_else(|| panic!("15.6：CTA 应是标准按钮（可见高 40），实测带 {cta:?}"));
+    let total = cta_bottom + 1 - top;
+    assert!(
+        total.abs_diff(EMPTY_TOTAL) <= 6,
+        "15.x：条目总高应 ≈{EMPTY_TOTAL}（96+16+32+8+16+24+40），实测 {total}"
+    );
+
+    eprintln!(
+        "[feedback-probe] empty：块 y {top}..{bottom}（高 {}）· 宽 {width} · 图标 {}×{} · \
+         块↔标题 {gap} · 总高 {total} · CTA {cta_top}..{cta_bottom}",
+        bottom - top + 1,
+        glyph.width(),
+        glyph.height()
+    );
+}
diff --git a/crates/app-iced/src/components/feedback/progress.rs b/crates/app-iced/src/components/feedback/progress.rs
new file mode 100644
index 0000000..765dc42
--- /dev/null
+++ b/crates/app-iced/src/components/feedback/progress.rs
@@ -0,0 +1,308 @@
+//! 进度指示器（`research/12b` §12）：`linear` 与 `circular`，各有确定态与不定态。
+//!
+//! ## 两种形态、四种态
+//!
+//! | 形态 | 确定态 | 不定态 |
+//! |---|---|---|
+//! | [`linear`] | 轨道 `SecondaryContainer` + 指示条 `Primary`，厚 **4**、圆角 full | 官方 1750ms **双段**追逐（[`phase_segments`]） |
+//! | [`circular`] | 40 环 + 4 线宽，弧长 = 数值 × 360° | 官方 6000ms（弧长 0.1↔0.87 + 旋转 **0→1440°**：全局 1080° 线性 + 关键帧 360°，[`CircularGeometry::indeterminate`]） |
+//!
+//! ## 为什么不定态要调用方给 `phase`
+//!
+//! 契约 §2：组件不持有时钟。`phase`（0..1 的一个周期）由页面按 `Subscription` 推进；
+//! harness 因此能拍**确定**的中间帧（否则每张图都是抓阄）。周期时长在几何里
+//! （[`LinearGeometry::cycle_ms`] / [`CircularGeometry::cycle_ms`]），调用方按它换算。
+//!
+//! ## CPU 降级路径（D27）
+//!
+//! 本组件**零半透明、零模糊**：轨道/指示条都是不透明实色，环形是 `stroke` 实色。
+//! 波浪形态（线性振幅 3 / 波长 40，环形振幅 1.6 / 波长 15，`[源]`）**未实现**，
+//! 用直线段/等弧长替代——这是 `12b §12.4` 明确允许的登记项（见报告「偏离登记」）。
+//!
+//! ## 环形为什么手搓 SVG
+//!
+//! iced 的 `canvas` feature 没开（`Cargo.toml` 不归本 mission），而圆弧用容器边框画不出来。
+//! 令牌图标的做法（24 网格 SVG path + `currentColor` + 内容哈希缓存）同样适用于几何图元：
+//! 一份 handle 渲染两层（轨道一层、弧一层），相位不变时 iced 侧命中缓存。
+
+use iced::border::Radius;
+use iced::widget::{container, row, svg, Space};
+use iced::{Background, Border, Element, Length};
+
+use unlucky_design::color::Role;
+
+use crate::theme::Ui;
+
+use super::super::layout;
+use super::geometry::{phase_segments, CircularGeometry, LinearGeometry};
+
+/// `FillPortion` 的比例分辨率：0..1 的占比 × 1000 取整（1/1000 像素级，够用且不溢出 u16）。
+const PORTIONS: f32 = 1000.0;
+
+/// 弧长小于这个角度就不画激活层（圆头在 0 弧长上会画出一个点，看着像「已完成」）。
+const MIN_SWEEP_DEG: f32 = 1.0;
+
+/// 100% 时弧首尾重合，`A` 命令画不出整圆 ⇒ 超过这个角度改画整环。
+const FULL_SWEEP_DEG: f32 = 359.9;
+
+/// 进度的取值：确定（0..1）或不定（相位 0..1）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub enum Amount {
+    /// 确定态：0..1。
+    Determinate(f32),
+    /// 不定态：一个周期内的相位（0..1，可越界，采样时按周期取模）。
+    Indeterminate(f32),
+}
+
+/// 一个进度指示器的取值（**不持有任何状态**）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Progress {
+    amount: Amount,
+}
+
+impl Progress {
+    /// 确定态：`value` 越界会被夹到 0..1（0% 只画轨道）。
+    pub fn determinate(value: f32) -> Self {
+        Self {
+            amount: Amount::Determinate(value.clamp(0.0, 1.0)),
+        }
+    }
+
+    /// 不定态：`phase` 是周期内的相位（调用方按 `cycle_ms` 推进）。
+    pub fn indeterminate(phase: f32) -> Self {
+        Self {
+            amount: Amount::Indeterminate(phase),
+        }
+    }
+
+    /// 取值（断言用；生产路径不读它，内部直接 match 字段）。
+    #[cfg(test)]
+    pub fn amount(self) -> Amount {
+        self.amount
+    }
+
+    /// 本帧要画的占轨道比例区间（0..1）。
+    ///
+    /// 确定态 1 段、不定态 2 段（官方双线）；区间可能为空（相位在「两段都在屏幕外」的时刻），
+    /// 调用方按 `end > start` 过滤。
+    pub fn spans(self) -> Vec<(f32, f32)> {
+        match self.amount {
+            Amount::Determinate(value) => vec![(0.0, value.clamp(0.0, 1.0))],
+            Amount::Indeterminate(phase) => phase_segments(phase).to_vec(),
+        }
+    }
+}
+
+/// 把 0..1 的区间**排序 + 合并重叠**，摊成「间隙 / 指示条」交替的列表（总长恒为 1.0）。
+///
+/// ## 为什么必须排序（复审 P1-A，视觉 r1 的 p1）
+///
+/// [`phase_segments`] 返回的两段**不保证有序**：第一线的前缘抢跑 250ms，所以它的区间在右，
+/// 第二线从 0 起跑的区间在左。照顺序铺 `FillPortion` 会把左段接到右段**之后**，并且
+/// `FillPortion` 之和一旦 ≠ 1000，iced 就按总和归一 —— 位置和宽度一起被压扁。
+/// 实测 phase 0.55：本应两段 `[0.003,0.079]` + `[0.355,0.860]`（x 689..713 / 802..963），
+/// 实际被画成一段 100px 的台阶（x 749..848），且 **34/100 个相位**上总和 >1（最大 1.99）。
+///
+/// 返回的每项是 `(是不是指示条, 占比)`；间隙项也显式给出来，才能断言「总和 = 1.0」。
+pub fn layout_spans(spans: &[(f32, f32)]) -> Vec<(bool, f32)> {
+    let mut clipped: Vec<(f32, f32)> = spans
+        .iter()
+        .map(|(start, end)| (start.clamp(0.0, 1.0), end.clamp(0.0, 1.0)))
+        .filter(|(start, end)| end > start)
+        .collect();
+    clipped.sort_by(|a, b| a.0.total_cmp(&b.0));
+
+    let mut merged: Vec<(f32, f32)> = Vec::new();
+    for (start, end) in clipped {
+        match merged.last_mut() {
+            Some(last) if start <= last.1 => last.1 = last.1.max(end),
+            _ => merged.push((start, end)),
+        }
+    }
+
+    let mut items = Vec::new();
+    let mut cursor = 0.0_f32;
+    for (start, end) in merged {
+        if start > cursor {
+            items.push((false, start - cursor));
+        }
+        items.push((true, end - start));
+        cursor = end;
+    }
+    if cursor < 1.0 {
+        items.push((false, 1.0 - cursor));
+    }
+    items
+}
+
+/// 占比 → `FillPortion` 整数份额，**总和恒为 `PORTIONS`**（累计舍入，最后一项吃掉残差）。
+///
+/// 为什么不用「每项各自 round」：各项独立取整后总和可能是 999 或 1001，iced 按总和归一，
+/// 就又回到 P1-A 那个「整条被压扁」的坑。这里让每个**累计边界**取整，最后一项补足，
+/// 于是任意相位下份额之和都精确等于 1000。
+pub fn portion_shares(items: &[(bool, f32)]) -> Vec<(bool, u16)> {
+    let mut shares = Vec::with_capacity(items.len());
+    let mut accumulated = 0.0_f32;
+    let mut previous = 0_u16;
+    for (index, (is_bar, fraction)) in items.iter().enumerate() {
+        accumulated += fraction;
+        let target = if index + 1 == items.len() {
+            PORTIONS as u16
+        } else {
+            (accumulated * PORTIONS).round() as u16
+        };
+        let share = target.saturating_sub(previous);
+        previous = target;
+        shares.push((*is_bar, share));
+    }
+    shares
+}
+
+/// 线性进度条（轨道 + 指示条，厚 4、圆角 full）。
+///
+/// 轨道宽 `Fill`（由宿主决定），指示条按占比分到 `FillPortion` 上——**不需要知道轨道像素宽**，
+/// 所以 50% 在任何宿主宽度下都精确是半条。
+pub fn linear<'a, M: 'a>(ui: &'a Ui, progress: Progress) -> Element<'a, M> {
+    let geometry = LinearGeometry::of(ui);
+    let track_color = ui.color(Role::SecondaryContainer);
+    let active_color = ui.color(Role::Primary);
+
+    let mut bar = row![]
+        .width(Length::Fill)
+        .height(Length::Fixed(geometry.thickness));
+    for (is_bar, share) in portion_shares(&layout_spans(&progress.spans())) {
+        if share == 0 {
+            continue;
+        }
+        bar = bar.push(if is_bar {
+            container(Space::new().width(Length::Fill).height(Length::Fill))
+                .width(Length::FillPortion(share))
+                .height(Length::Fill)
+                .style(move |_theme| container::Style {
+                    background: Some(Background::Color(active_color)),
+                    border: Border {
+                        radius: Radius::new(geometry.radius),
+                        ..Border::default()
+                    },
+                    ..container::Style::default()
+                })
+                .into()
+        } else {
+            spacer(share)
+        });
+    }
+
+    container(bar)
+        .width(Length::Fill)
+        .height(Length::Fixed(geometry.thickness))
+        .style(move |_theme| container::Style {
+            background: Some(Background::Color(track_color)),
+            border: Border {
+                radius: Radius::new(geometry.radius),
+                ..Border::default()
+            },
+            ..container::Style::default()
+        })
+        .into()
+}
+
+/// 环形进度（40 直径 / 4 线宽；确定态画弧，不定态按官方节奏扫）。
+pub fn circular<'a, M: 'a>(ui: &'a Ui, progress: Progress) -> Element<'a, M> {
+    let geometry = CircularGeometry::of(ui);
+    let (sweep, rotation) = match progress.amount {
+        Amount::Determinate(value) => (value.clamp(0.0, 1.0) * 360.0, 0.0),
+        Amount::Indeterminate(phase) => {
+            // 圈数直接乘 360（不做 rem_euclid）：每周期 4 圈是官方口径，截断就丢转速。
+            let (sweep_fraction, turns) = geometry.indeterminate(phase);
+            (sweep_fraction * 360.0, turns * 360.0)
+        }
+    };
+
+    let track = glyph(
+        &geometry,
+        ring_source(&geometry),
+        ui.color(Role::SecondaryContainer),
+    );
+
+    // 0% 只画轨道（不画弧，也不画圆头小点）；100% 画整环（`A` 命令的首尾重合画不出整圆）
+    let active = if sweep < MIN_SWEEP_DEG {
+        None
+    } else if sweep >= FULL_SWEEP_DEG {
+        Some(glyph(
+            &geometry,
+            ring_source(&geometry),
+            ui.color(Role::Primary),
+        ))
+    } else {
+        Some(glyph(
+            &geometry,
+            arc_source(&geometry, sweep, rotation),
+            ui.color(Role::Primary),
+        ))
+    };
+
+    let mut layers = vec![track];
+    layers.extend(active);
+
+    // Q9 的同族：几何图元也必须落在**固定尺寸**的盒子里，否则 usvg 会按 Contain 撑满父级。
+    layout::fixed(
+        geometry.diameter,
+        geometry.diameter,
+        iced::widget::stack(layers),
+    )
+}
+
+/// 两段之间/两端的透明占位。
+fn spacer<'a, M: 'a>(share: u16) -> Element<'a, M> {
+    Space::new()
+        .width(Length::FillPortion(share))
+        .height(Length::Fill)
+        .into()
+}
+
+/// 一层几何图元（固定尺寸 + `currentColor` 上色）。
+fn glyph<'a, M: 'a>(
+    geometry: &CircularGeometry,
+    source: String,
+    color: iced::Color,
+) -> Element<'a, M> {
+    svg(svg::Handle::from_memory(source.into_bytes()))
+        .width(Length::Fixed(geometry.diameter))
+        .height(Length::Fixed(geometry.diameter))
+        .style(move |_theme, _status| svg::Style { color: Some(color) })
+        .into()
+}
+
+/// 整环（轨道用，也用作 100% 的激活层）。
+fn ring_source(geometry: &CircularGeometry) -> String {
+    let (size, thickness) = (geometry.diameter, geometry.thickness);
+    let center = size / 2.0;
+    let radius = geometry.arc_radius();
+    format!(
+        "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"{size}\" height=\"{size}\" \
+         viewBox=\"0 0 {size} {size}\"><circle cx=\"{center}\" cy=\"{center}\" r=\"{radius}\" \
+         fill=\"none\" stroke=\"currentColor\" stroke-width=\"{thickness}\"/></svg>"
+    )
+}
+
+/// 一段圆弧（`rotation` 起、扫 `sweep_deg`；0° = 12 点、顺时针 = M3 口径）。
+fn arc_source(geometry: &CircularGeometry, sweep_deg: f32, rotation_deg: f32) -> String {
+    let (size, thickness) = (geometry.diameter, geometry.thickness);
+    let center = size / 2.0;
+    let radius = geometry.arc_radius();
+    let (x0, y0) = point(center, radius, rotation_deg);
+    let (x1, y1) = point(center, radius, rotation_deg + sweep_deg);
+    let large = u8::from(sweep_deg > 180.0);
+    format!(
+        "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"{size}\" height=\"{size}\" \
+         viewBox=\"0 0 {size} {size}\"><path d=\"M {x0:.3} {y0:.3} A {radius} {radius} 0 \
+         {large} 1 {x1:.3} {y1:.3}\" fill=\"none\" stroke=\"currentColor\" \
+         stroke-width=\"{thickness}\" stroke-linecap=\"round\"/></svg>"
+    )
+}
+
+/// 极角（0° = 12 点，顺时针）→ 画布坐标（y 向下，所以向上取负）。
+fn point(center: f32, radius: f32, deg: f32) -> (f32, f32) {
+    let rad = deg.to_radians();
+    (center + radius * rad.sin(), center - radius * rad.cos())
+}
diff --git a/crates/app-iced/src/components/feedback/snackbar.rs b/crates/app-iced/src/components/feedback/snackbar.rs
new file mode 100644
index 0000000..713dd49
--- /dev/null
+++ b/crates/app-iced/src/components/feedback/snackbar.rs
@@ -0,0 +1,193 @@
+//! Snackbar（`research/12b` §14）：底/顶部提示条 + 动作 + 关闭。
+//!
+//! ## 官方值（`[源]` = A1，`SnackbarTokens` + `SnackbarKt`，`javap` 核对）
+//!
+//! | # | 项 | 值 | 落点 |
+//! |---|---|---|---|
+//! | 14.1 | 圆角 | **4**（`CornerExtraSmall`） | `Component::Snackbar.spec().shape` |
+//! | 14.2 | 容器色 | **`InverseSurface`**（高程 L3 是设计口头径，见下「不画阴影」） | [`Role::InverseSurface`] |
+//! | 14.3 | 高 | 单行 **48** / 双行 **68** | [`SnackbarGeometry::height`] |
+//! | 14.4 | 内距 | 水平 **16** / 垂直 **6** / 文本↔动作 **8** | `Space::X4` / 6 / `Space::X2` |
+//! | 14.6 | 颜色 | 文本 `InverseOnSurface`、动作 **`InversePrimary`**、图标 24 `InverseOnSurface` | 组件层取角色 |
+//! | — | 宽度上限 | **600**（`SnackbarKt.ContainerMaxWidth`） | `max_width` |
+//!
+//! ## 宽度上下限（一条**真实**限制，登记 G17-d）
+//!
+//! 官方只有上限 600，没有下限常数；本项目取 **344 `[估]`**（M2 时代口径，观感连续）。
+//! iced 的 `Length` **没有 min-width**（与按钮家族 G15「最小宽 58 不施加」同一堵墙），
+//! 所以：**上限在组件里强制**（`container::max_width`），**下限由宿主保证**——页面给提示条
+//! 的区域至少 344 宽。gallery 用三个宿主宽度把这条限制摊开（300 → 300、344 → 344、800 → 600），
+//! 渲染层断言量的是这三种实测值，不假装下限被组件强制住了。
+//!
+//! ## 超时与 dismiss：状态归调用方
+//!
+//! 组件**不计时**：显示时长、自动消失、`on_timeout` 全在调用方（页面）手里。
+//! 组件的语义只有三条：`placement` 决定贴顶还是贴底（并给出 12 的外边距）、
+//! `action` 给一个文字动作、`dismiss` 给关闭键。消息要不要触发「撤销」由调用方决定。
+//!
+//! ## 不画阴影
+//!
+//! 官方是 L3，但 D27（CPU 档禁模糊）与令牌层 `ShadowSpec` 仍是 M63 占位值这两条都指向
+//! 「先不画」——层级靠 `InverseSurface` 与页面的 scrim/留白表达。登记为偏离 **D-4**
+//! （D-3 是进度条的波浪降级，别混号）。
+
+use iced::widget::{container, row, text};
+use iced::{Alignment, Background, Border, Element, Length, Padding};
+
+use unlucky_design::color::Role;
+use unlucky_design::icons::IconKind;
+use unlucky_design::typography::TypeRole;
+
+use crate::theme::Ui;
+
+use super::super::interaction::Interaction;
+use super::action;
+use super::panel::SnackbarGeometry;
+
+/// 贴底还是贴顶（官方两种都有；本项目默认贴底）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Placement {
+    /// 贴底（桌面默认：不挡页头，也不挡主操作）。
+    Bottom,
+    /// 贴顶（页头有刷新按钮时用于「结果在页头附近」的场景）。
+    Top,
+}
+
+impl Placement {
+    /// 垂直对齐：贴底 = `End`，贴顶 = `Start`。
+    fn vertical(self) -> Alignment {
+        match self {
+            Placement::Bottom => Alignment::End,
+            Placement::Top => Alignment::Start,
+        }
+    }
+}
+
+/// 一条提示条的装配描述（**不持有任何状态所有权**）。
+#[derive(Debug, Clone)]
+pub struct Snackbar<'a, M> {
+    text: &'a str,
+    lines: u8,
+    placement: Placement,
+    action: Option<(&'a str, M)>,
+    dismiss: Option<M>,
+    state: Option<Interaction>,
+}
+
+impl<'a, M> Snackbar<'a, M> {
+    /// 单行提示条（高 48）。
+    pub fn new(text: &'a str) -> Self {
+        Self {
+            text,
+            lines: 1,
+            placement: Placement::Bottom,
+            action: None,
+            dismiss: None,
+            state: None,
+        }
+    }
+
+    /// 双行（高 68）。**行数由调用方声明**：iced 没有 `heightIn(min=…)`，官方那两条高度值
+    /// 只能显式给（文本自己换行与否不改变容器高，这是 M3 的口径）。
+    pub fn two_lines(mut self) -> Self {
+        self.lines = 2;
+        self
+    }
+
+    /// 贴底 / 贴顶。
+    pub fn placement(mut self, placement: Placement) -> Self {
+        self.placement = placement;
+        self
+    }
+
+    /// 右侧文字动作（`InversePrimary`）。
+    pub fn action(mut self, label: &'a str, on_press: M) -> Self {
+        self.action = Some((label, on_press));
+        self
+    }
+
+    /// 关闭键（`InverseOnSurface`）。
+    pub fn dismiss(mut self, on_press: M) -> Self {
+        self.dismiss = Some(on_press);
+        self
+    }
+
+    /// 强制动作件的视觉态（gallery 取证用；运行期不要调）。
+    pub fn state(mut self, state: Interaction) -> Self {
+        self.state = Some(state);
+        self
+    }
+}
+
+/// 画一条提示条。
+///
+/// 返回的元素是 **`Fill` 高度的容器**：贴底/贴顶由它内部的对齐决定，调用方只要给它一块
+/// 可用区（`stack` 在页面上、或 gallery 的宿主盒），它就是那个位置上的居中提示条。
+pub fn snackbar<'a, M: Clone + 'a>(ui: &'a Ui, spec: Snackbar<'a, M>) -> Element<'a, M> {
+    let geometry = SnackbarGeometry::of(ui);
+    let style = ui.style(TypeRole::BodyMedium);
+    let height = geometry.height_for(spec.lines);
+    let surface = ui.color(Role::InverseSurface);
+    let radius = iced::border::Radius::new(geometry.radius);
+
+    let mut content = row![]
+        .align_y(Alignment::Center)
+        .spacing(geometry.gap)
+        .push(
+            text(spec.text)
+                .size(style.size_px)
+                .font(ui.font_of(style))
+                .color(ui.color(Role::InverseOnSurface))
+                .width(Length::Fill),
+        );
+
+    if let Some((label, message)) = spec.action {
+        content = content.push(action::text_action(
+            ui,
+            label,
+            Role::InversePrimary,
+            Role::InverseSurface,
+            Some(message),
+            spec.state,
+        ));
+    }
+
+    if let Some(message) = spec.dismiss {
+        content = content.push(action::icon_action(
+            ui,
+            IconKind::Close,
+            Role::InverseOnSurface,
+            Role::InverseSurface,
+            Some(message),
+            spec.state,
+        ));
+    }
+
+    let bar = container(content)
+        .width(Length::Fill)
+        .max_width(geometry.max_width)
+        .height(Length::Fixed(height))
+        .padding(Padding {
+            top: geometry.pad_v,
+            right: geometry.pad_h,
+            bottom: geometry.pad_v,
+            left: geometry.pad_h,
+        })
+        .style(move |_theme| container::Style {
+            background: Some(Background::Color(surface)),
+            border: Border {
+                radius,
+                ..Border::default()
+            },
+            ..container::Style::default()
+        });
+
+    // 位置层：`Fill` 高度 + 外边距 12 + 水平居中；贴底/贴顶只改 `align_y`（Q8：不用 center_*）。
+    container(bar)
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .padding(Padding::from(geometry.margin))
+        .align_x(Alignment::Center)
+        .align_y(spec.placement.vertical())
+        .into()
+}
diff --git a/crates/app-iced/src/components/feedback/tests.rs b/crates/app-iced/src/components/feedback/tests.rs
new file mode 100644
index 0000000..7ecc203
--- /dev/null
+++ b/crates/app-iced/src/components/feedback/tests.rs
@@ -0,0 +1,223 @@
+//! 纯函数级断言：几何对令牌、节奏对 A1、角色对变体。
+//!
+//! 这里**只测数值与结构**（M68 的教训：函数对不代表图对）。对着真截图量像素的是
+//! [`super::probe`]，两者缺一不可——本文件保证「数字对」，probe 保证「画出来是那个数字」。
+
+use iced::Element;
+
+use unlucky_design::color::{Role, Scheme, SchemeFlavor, SCRIM_ALPHA};
+use unlucky_design::elevation::MaterialLayer;
+use unlucky_design::typography::Platform;
+
+use crate::theme::{to_iced, Families, Ui};
+
+use super::super::interaction::{self, Interaction};
+use super::dialog::scrim;
+use super::panel::{DialogGeometry, EmptyStateGeometry, SnackbarGeometry};
+use super::progress::Progress;
+use super::snackbar::{Placement, Snackbar};
+use super::{circular, dialog, empty_state, linear, snackbar, Dialog, EmptyState};
+
+mod progress;
+
+const FAMILIES: Families = Families {
+    text: "Segoe UI",
+    display: "Segoe UI",
+    mono: "Consolas",
+};
+
+pub(super) fn ui(flavor: SchemeFlavor) -> Ui {
+    Ui::with_platform(flavor, Platform::Windows, FAMILIES)
+}
+
+// ---- §14 Snackbar -----------------------------------------------------------
+
+/// 14.3 / 14.1 / 宽度上限：48 / 68 / 4 / 600。
+#[test]
+fn snackbar_heights_widths_and_radius_are_the_tokens() {
+    let geometry = SnackbarGeometry::of(&ui(SchemeFlavor::Light));
+    assert_eq!(geometry.height_for(1), 48.0, "14.3 单行 48");
+    assert_eq!(geometry.height_for(2), 68.0, "14.3 双行 68");
+    assert_eq!(geometry.radius, 4.0, "14.1 圆角 4（CornerExtraSmall）");
+    assert_eq!(geometry.max_width, 600.0, "SnackbarKt.ContainerMaxWidth");
+    assert_eq!(geometry.min_width, 344.0, "G17-d [估] 最小宽");
+    assert!(geometry.min_width < geometry.max_width, "上下限必须有区间");
+    assert_eq!(geometry.margin, 12.0, "G17-c [规格] 外边距 12");
+    assert_eq!(geometry.pad_h, 16.0, "A1 HorizontalSpacing");
+    assert_eq!(geometry.pad_v, 6.0, "A1 SnackbarVerticalPadding");
+}
+
+// ---- §7 Dialog --------------------------------------------------------------
+
+/// 7.4：官方区间 **280..560**，本项目取 **480**，且 480 落在区间内。
+#[test]
+fn dialog_geometry_sits_inside_the_official_bounds() {
+    let geometry = DialogGeometry::of(&ui(SchemeFlavor::Light));
+    assert_eq!(geometry.min_width, 280.0, "A1 DialogMinWidth");
+    assert_eq!(geometry.max_width, 560.0, "A1 DialogMaxWidth");
+    assert_eq!(geometry.width, 480.0, "G17-e 本项目取值");
+    assert!(
+        geometry.min_width <= geometry.width && geometry.width <= geometry.max_width,
+        "自选宽必须落在官方区间内"
+    );
+}
+
+/// 复审 P2-2：`max(280)` 那条支以前一次都没被执行过（只有定义 + 一个调用点）。
+///
+/// 抓得住：有人把下限去掉（200 → 200）、或把 `min/max` 顺序写反（200 → 480 之外的值）。
+/// 抓不住：渲染时是否真的画了 280（那需要真窗口；gallery 的 360 那格由 probe 的逐卡宽度兜）。
+#[test]
+fn dialog_width_respects_the_official_minimum() {
+    let geometry = DialogGeometry::of(&ui(SchemeFlavor::Light));
+    assert_eq!(
+        geometry.effective_width(200.0),
+        280.0,
+        "可用宽 200 → 仍画官方下限 280"
+    );
+    assert_eq!(geometry.effective_width(360.0), 360.0, "窄宿主取可用宽");
+    assert_eq!(
+        geometry.effective_width(800.0),
+        480.0,
+        "宽宿主夹到项目值 480"
+    );
+}
+
+/// 7.1 / 7.3 / 7.6：圆角 28、内距 24 / 16 / 24、动作 8 / 12。
+#[test]
+fn dialog_padding_and_action_gaps_are_the_tokens() {
+    let geometry = DialogGeometry::of(&ui(SchemeFlavor::Light));
+    assert_eq!(geometry.radius, 28.0, "7.1 CornerExtraLarge");
+    assert_eq!(geometry.padding, 24.0, "7.3 DialogPadding");
+    assert_eq!(geometry.title_gap, 16.0, "7.3 TitlePadding bottom");
+    assert_eq!(geometry.body_gap, 24.0, "7.3 TextPadding bottom");
+    assert_eq!(geometry.action_gap, 8.0, "7.6 ButtonsMainAxisSpacing");
+    assert_eq!(geometry.action_cross, 12.0, "7.6 ButtonsCrossAxisSpacing");
+}
+
+/// 7.7 + D27：scrim = 黑@0.32 叠在 canvas 上之后的**不透明**实色。
+#[test]
+fn scrim_is_scrimalpha_precomposited_onto_the_canvas() {
+    for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+        let ui = ui(flavor);
+        let scheme = Scheme::baseline(flavor);
+        let canvas = scheme.get(MaterialLayer::Canvas.surface_role());
+        let expected = to_iced(scheme.scrim().over(canvas));
+        assert_eq!(
+            scrim(&ui),
+            expected,
+            "{flavor:?}：scrim 必须逐位等于「黑@0.32 叠 canvas」"
+        );
+        assert_eq!(
+            scrim(&ui).a,
+            1.0,
+            "D27：CPU 档不出现半透明（预合成后必须不透明）"
+        );
+        assert_ne!(
+            scrim(&ui),
+            ui.layer(MaterialLayer::Canvas),
+            "遮罩必须与画布有可见差异"
+        );
+        assert!((SCRIM_ALPHA - 0.32).abs() < f32::EPSILON, "令牌口径 α=0.32");
+    }
+}
+
+// ---- §15 空态（项目自定） ----------------------------------------------------
+
+/// 15.1：图标块 96 / 圆角 16 / 图标 32（**全部 `[估]`**，官方没有这个组件）。
+#[test]
+fn empty_state_geometry_is_the_project_defined_set() {
+    let geometry = EmptyStateGeometry::of(&ui(SchemeFlavor::Light));
+    assert_eq!(geometry.block, 96.0);
+    assert_eq!(geometry.block_radius, 16.0, "ShapeScale::Large");
+    // 复审 C：登记值 32（`IconSize::Empty`）。这条守「登记值 = 交给 `view_at` 的 px」——
+    // 它抓不住「盒子 32 而 svg 仍钉 24」那种情况（那是渲染层的事，probe 量墨迹 22..34 兜）。
+    assert_eq!(
+        geometry.icon, 32.0,
+        "盒内图标 32（`view_at` 按 32 烘焙 stroke）"
+    );
+    // **复审 P2-1 的回归断言**：三个间距必须精确等于令牌档位。
+    // 早先这里只写 `> 0.0`，所以「Column::spacing(8) 与显式 gap(16/24) 双算成 32/40」
+    // 完全藏得住（渲染实测 264 vs 登记 232）。
+    assert_eq!(geometry.gap_title, 16.0, "块↔标题 = Space::X4");
+    assert_eq!(geometry.gap_body, 8.0, "标题↔副文案 = Space::X2");
+    assert_eq!(geometry.gap_action, 24.0, "副文案↔CTA = Space::X6");
+    assert_eq!(geometry.block, 96.0);
+    assert_eq!(
+        super::empty_state::BLOCK_LAYER,
+        MaterialLayer::Overlay,
+        "块底色是 SurfaceContainerHigh（材质层 Overlay）"
+    );
+}
+
+// ---- 结构 / 角色 ------------------------------------------------------------
+
+/// 五个入口都能在**任意**消息类型下构建（契约 §2：不 import `app::Message`）。
+#[test]
+fn every_component_builds_for_a_foreign_message_type() {
+    #[derive(Clone, Debug, PartialEq)]
+    enum Other {
+        Yes,
+        No,
+    }
+
+    let ui = ui(SchemeFlavor::Light);
+    let _: Element<'_, Other> = linear(&ui, Progress::determinate(0.5));
+    let _: Element<'_, Other> = circular(&ui, Progress::indeterminate(0.3));
+    let _: Element<'_, Other> = snackbar(
+        &ui,
+        Snackbar::new("已保存")
+            .placement(Placement::Top)
+            .two_lines()
+            .action("撤销", Other::No)
+            .dismiss(Other::No),
+    );
+    let _: Element<'_, Other> = dialog(
+        &ui,
+        Dialog::new("确认删除？", "此操作不可撤销。")
+            .double(("取消", Other::No), ("删除", Other::Yes)),
+    );
+    let _: Element<'_, Other> = empty_state(
+        &ui,
+        EmptyState::new(
+            unlucky_design::icons::IconKind::Instances,
+            "还没有实例",
+            "建一个开始游戏",
+        )
+        .action("新建", Other::Yes),
+    );
+    // 无动作的三种形态也要能构建（DialogActions::None / 无 action 的 Snackbar）
+    let _: Element<'_, Other> = dialog(&ui, Dialog::new("已是最新版本", "没有可用更新。"));
+    let _: Element<'_, Other> = snackbar(&ui, Snackbar::new("已复制"));
+    let _: Element<'_, Other> = empty_state(
+        &ui,
+        EmptyState::new(
+            unlucky_design::icons::IconKind::Logs,
+            "没有日志",
+            "启动一次游戏后这里会有内容",
+        ),
+    );
+}
+
+/// 状态层必须来自 `interaction`（不是组件里自己乘 α）：hover 层不透明且与容器色不同。
+#[test]
+fn snackbar_state_layers_come_from_the_interaction_module() {
+    let ui = ui(SchemeFlavor::Light);
+    let hover = interaction::overlay_color(
+        &ui,
+        Interaction::Hovered,
+        Role::InversePrimary,
+        Role::InverseSurface,
+    )
+    .expect("hover 有状态层");
+    assert_eq!(hover.a, 1.0, "状态层必须是实色（CPU/GPU 一致）");
+    assert_ne!(
+        hover,
+        ui.color(Role::InverseSurface),
+        "叠了 8% 必须看得出来"
+    );
+
+    // 禁用内容走 token 口径（38%），不是「变灰一点」
+    let disabled = interaction::disabled_content_over_role(&ui, Role::OnSurface, false);
+    assert_ne!(disabled, ui.color(Role::OnSurface));
+    assert_eq!(disabled.a, 1.0);
+}
diff --git a/crates/app-iced/src/components/feedback/tests/progress.rs b/crates/app-iced/src/components/feedback/tests/progress.rs
new file mode 100644
index 0000000..60f0f53
--- /dev/null
+++ b/crates/app-iced/src/components/feedback/tests/progress.rs
@@ -0,0 +1,281 @@
+//! 进度两式的纯函数断言（`tests` 的子模块，从 `tests.rs` 拆出来控行数）。
+//!
+//! 三条回归都住在这里：
+//! - [`raw_segments_are_unordered_and_layout_sorts_them`]：`phase_segments` 的原始输出**不有序**
+//!   （视觉 r1 P1-A 就是把两段按顺序铺 `FillPortion`，图上被压成一段）；
+//! - [`portion_shares_always_sum_to_the_full_track`]：份额之和恒为 1000（旧实现 34/100 相位 >1）；
+//! - [`circular_indeterminate_rotation_is_four_turns_and_continuous`]：每周期 4 圈、跨周期不跳变
+//!   （代码 r1 P1-B：旧实现只有 1 圈，且末尾倒跳 270°）。
+
+use unlucky_design::color::SchemeFlavor;
+use unlucky_design::shape::ShapeScale;
+
+use super::super::geometry::{phase_segments, CircularGeometry, LinearGeometry, PHASE_055};
+use super::super::keyframes::{KeyPoint, Keyframes};
+use super::super::progress::{layout_spans, portion_shares, Amount, Progress};
+use super::ui;
+
+// ---- §12 进度 ---------------------------------------------------------------
+
+/// 12.1：线性厚度 **4**、圆角 full ⇒ 2（`ShapeScale::Full.radius_px(4)`）。
+#[test]
+fn linear_thickness_and_radius_come_from_the_tokens() {
+    let geometry = LinearGeometry::of(&ui(SchemeFlavor::Light));
+    assert_eq!(geometry.thickness, 4.0, "12.1 线性厚度 = 4（A1 Height）");
+    assert_eq!(
+        geometry.radius,
+        ShapeScale::Full.radius_px(4.0),
+        "12.1 圆角 full = 厚的一半"
+    );
+    assert_eq!(geometry.radius, 2.0);
+    assert_eq!(
+        geometry.cycle_ms, 1750,
+        "不定态周期 = LinearAnimationDuration"
+    );
+}
+
+/// 12.3：环形 **40 / 4**，环中线半径 (40 − 4) / 2 = **18**。
+#[test]
+fn circular_geometry_matches_the_tokens() {
+    let geometry = CircularGeometry::of(&ui(SchemeFlavor::Dark));
+    assert_eq!(
+        geometry.diameter, 40.0,
+        "A1 CircularProgressIndicatorTokens.Size"
+    );
+    assert_eq!(geometry.thickness, 4.0, "A1 ActiveThickness");
+    assert_eq!(geometry.radius, 20.0, "圆角 full = 直径的一半");
+    assert_eq!(geometry.arc_radius(), 18.0);
+    assert_eq!(
+        geometry.cycle_ms, 6000,
+        "A1 CircularAnimationProgressDuration"
+    );
+}
+
+/// 12.4：不定态两段**逐段非负**——这条只证「单段自身合法」，**不证两段的先后**
+/// （视觉 r1 P1-A 就是从这里漏过去的：函数名曾经叫 `..._stay_ordered`，其实没验排序）。
+#[test]
+fn indeterminate_segments_are_each_well_formed() {
+    let mut travelled = false;
+    let mut previous_end = 0.0;
+    for step in 0..=200 {
+        let phase = step as f32 / 200.0;
+        for (start, end) in phase_segments(phase) {
+            assert!(
+                start <= end + f32::EPSILON,
+                "相位 {phase:.3}：段起点 {start} 大于终点 {end}（前缘/后缘写反就会这样）"
+            );
+            assert!(
+                (0.0..=1.0).contains(&start) && (0.0..=1.0).contains(&end),
+                "相位 {phase:.3}：段越出轨道 {start}..{end}"
+            );
+        }
+        let first = phase_segments(phase)[0].1;
+        if phase > 0.0 && phase < 0.5 && first > previous_end {
+            travelled = true;
+        }
+        previous_end = first;
+    }
+    assert!(travelled, "段前沿必须随相位右移（否则就是一根不动的条）");
+    assert_eq!(phase_segments(0.0), [(0.0, 0.0), (0.0, 0.0)]);
+    let (_, head) = phase_segments(1000.0 / 1750.0)[0];
+    assert!((head - 1.0).abs() < 1.0e-5, "第一线前沿应在 1000ms 到 1.0");
+}
+
+/// **复审 P1-A 的回归测试**：`phase_segments` 的原始输出**不有序**（第一线的前缘在右、第二线在左），
+/// 所以铺布局前必须排序 + 合并；排序后的两段位置要与 A1 keyframes 对得上。
+#[test]
+fn raw_segments_are_unordered_and_layout_sorts_them() {
+    // 原始顺序：第一线（右，0.355..0.87）在前，第二线（左，0.003..0.079）在后
+    let raw = phase_segments(0.55);
+    assert!(
+        raw[0].0 > raw[1].0,
+        "phase 0.55 的原始两段应当是「右段在前、左段在后」，实际 {raw:?}"
+    );
+
+    let laid = layout_spans(&raw);
+    // 期望：间隙 / 左段 / 间隙 / 右段 / 间隙（5 项，总长 1.0）
+    assert_eq!(laid.len(), 5, "两段应摊成 5 项：{laid:?}");
+    assert!(!laid[0].0 && laid[1].0 && !laid[2].0 && laid[3].0 && !laid[4].0);
+    let left = laid[1].1;
+    let right = laid[3].1;
+    let left_start: f32 = laid[0].1;
+    let right_start: f32 = laid[0].1 + left + laid[2].1;
+    // 期望值来自 `geometry::PHASE_055`——与渲染层探针**共用**（复审 B：早先两边差 0.011）
+    let [(a0, a1), (b0, b1)] = PHASE_055;
+    assert!(
+        (left_start - a0).abs() < 0.01,
+        "左段起点 {left_start} vs {a0}"
+    );
+    assert!(
+        (left - (a1 - a0)).abs() < 0.01,
+        "左段宽 {left} vs {}",
+        a1 - a0
+    );
+    assert!(
+        (right_start - b0).abs() < 0.01,
+        "右段起点 {right_start} vs {b0}"
+    );
+    assert!(
+        (right - (b1 - b0)).abs() < 0.01,
+        "右段宽 {right} vs {}",
+        b1 - b0
+    );
+
+    let total: f32 = laid.iter().map(|(_, fraction)| fraction).sum();
+    assert!(
+        (total - 1.0).abs() < 1.0e-5,
+        "铺开的占比之和必须 = 1.0，实测 {total}"
+    );
+}
+
+/// 任意相位下 `FillPortion` 份额之和**恒为 1000**（iced 按总和归一 ⇒ 不等于 1000 就会压扁）。
+///
+/// 复审 P1-A 的实测反例：旧实现 **34/100 个相位**总和 >1（最大 1.99）。
+#[test]
+fn portion_shares_always_sum_to_the_full_track() {
+    for step in 0..=200 {
+        let phase = step as f32 / 200.0;
+        let items = layout_spans(&phase_segments(phase));
+        let shares = portion_shares(&items);
+        let total: u32 = shares.iter().map(|(_, share)| u32::from(*share)).sum();
+        assert_eq!(total, 1000, "相位 {phase:.3} 的份额之和是 {total}");
+        assert!(
+            shares.iter().filter(|(is_bar, _)| *is_bar).count() <= 2,
+            "最多两段指示条，相位 {phase:.3}"
+        );
+        // 指示条之间必须留间隙（除非两段相接，那时会被合并成一段）
+        let mut previous_bar = false;
+        for (is_bar, share) in &shares {
+            if *is_bar && previous_bar && *share > 0 {
+                panic!("相位 {phase:.3}：两段指示条相邻但没合并");
+            }
+            previous_bar = *is_bar;
+        }
+    }
+}
+
+/// 环形不定态：弧长在 0.1..0.87 之间（A1 min/max），旋转走满一圈。
+#[test]
+fn circular_indeterminate_sweeps_the_official_range() {
+    let geometry = CircularGeometry::of(&ui(SchemeFlavor::Light));
+    let mut min = f32::MAX;
+    let mut max = f32::MIN;
+    let mut rotation = f32::MIN;
+    for step in 0..=600 {
+        let (sweep, spin) = geometry.indeterminate(step as f32 / 600.0);
+        min = min.min(sweep);
+        max = max.max(sweep);
+        rotation = rotation.max(spin);
+    }
+    assert!(
+        (min - 0.1).abs() < 1.0e-3,
+        "弧长下限 0.1（CircularIndeterminateMinProgress），实测 {min}"
+    );
+    assert!((max - 0.87).abs() < 1.0e-3, "弧长上限 0.87，实测 {max}");
+    // P1-B：每周期 4 圈（1080° 全局 + 360° 关键帧），不是 1 圈
+    assert!(
+        (rotation - 4.0).abs() < 0.01,
+        "旋转应走满 4 圈，实测 {rotation}"
+    );
+}
+
+/// **复审 P1-B 的回归测试**：环形不定态每周期 4 圈（官方 1440°），且跨周期**不跳变**。
+///
+/// 修之前：`ROTATION` 首点在 300ms/90°，且没有全局旋转 ⇒
+/// `turns(0.9999) = 1.0`、`turns(0.0) = 0.25`，跨周期差 0.75 圈 = **270° 瞬时倒跳**。
+#[test]
+fn circular_indeterminate_rotation_is_four_turns_and_continuous() {
+    let geometry = CircularGeometry::of(&ui(SchemeFlavor::Light));
+
+    // 每周期 4 圈 = 1440°（1080° 全局 + 360° 关键帧）
+    let start = geometry.indeterminate(0.0).1;
+    let end = geometry.indeterminate(1.0 - 1.0e-6).1;
+    assert!(
+        ((end - start) - 4.0).abs() < 1.0e-3,
+        "每周期应为 4 圈（1440°），实测 {} 圈",
+        end - start
+    );
+
+    // 跨周期连续性：按「圈」取最短距离，必须 ≤ 一帧的位移（60fps ⇒ 4/60 ≈ 0.067 圈）
+    let before = geometry.indeterminate(1.0 - 1.0e-4).1;
+    let after = geometry.indeterminate(0.0).1;
+    let mut jump = (before - after).rem_euclid(1.0);
+    if jump > 0.5 {
+        jump = 1.0 - jump;
+    }
+    assert!(
+        jump <= 4.0 / 60.0,
+        "跨周期旋转跳变 {jump} 圈（应 ≤ 4/60；修之前是 0.75 圈 = 270°）"
+    );
+    // 给报告用的一行实测数值（`--nocapture` 可见）：跨周期跳变 + 每周期圈数
+    eprintln!(
+        "[rotation] turns(0.9999)={before:.6} turns(0.0)={after:.6} 跳变={jump:.6} 圈（{:.2}°）·          每周期 {:.4} 圈 = {:.1}°",
+        jump * 360.0,
+        end - start,
+        (end - start) * 360.0
+    );
+
+    // 旋转必须单调（相位 0 → 1 逐帧不回退，按圈算）
+    // 只扫 [0, 1) 的相位：phase == 1.0 就是下一周期的 0，回绕是**正常的**（mod 1 等价）。
+    let mut previous = geometry.indeterminate(0.0).1;
+    for step in 1..600 {
+        let phase = step as f32 / 600.0;
+        let current = geometry.indeterminate(phase).1;
+        assert!(
+            current >= previous - 1.0e-6,
+            "相位 {phase:.3}：旋转从 {previous} 回退到 {current}"
+        );
+        previous = current;
+    }
+}
+
+/// 确定态：越界值夹到 0..1（0% 只画轨道，100% 画满）。
+#[test]
+fn determinate_values_are_clamped() {
+    assert_eq!(
+        Progress::determinate(1.5).amount(),
+        Amount::Determinate(1.0)
+    );
+    assert_eq!(
+        Progress::determinate(-2.0).amount(),
+        Amount::Determinate(0.0)
+    );
+    assert_eq!(Progress::determinate(0.5).spans(), vec![(0.0, 0.5)]);
+    assert_eq!(Progress::determinate(0.0).spans(), vec![(0.0, 0.0)]);
+}
+
+/// keyframes 求值器：端点保持、相位循环、越界相位按周期取模。
+#[test]
+fn keyframes_hold_ends_and_wrap() {
+    const LINE: Keyframes = Keyframes {
+        cycle_ms: 1000,
+        points: &[
+            KeyPoint {
+                ms: 250,
+                value: 0.0,
+                easing: unlucky_design::motion::Easing::Linear,
+            },
+            KeyPoint {
+                ms: 750,
+                value: 1.0,
+                easing: unlucky_design::motion::Easing::Linear,
+            },
+        ],
+    };
+    assert_eq!(LINE.sample(0.0), 0.0, "第一点之前保持首值");
+    assert_eq!(LINE.sample(0.25), 0.0, "正好在第一点");
+    assert!((LINE.sample(0.5) - 0.5).abs() < 1.0e-5, "中点线性插值");
+    assert_eq!(LINE.sample(0.75), 1.0);
+    assert_eq!(LINE.sample(0.9), 1.0, "最后一点之后保持末值");
+    assert_eq!(LINE.sample(1.25), 0.0, "相位 1.25 = 0.25（循环）");
+    assert_eq!(
+        LINE.sample(-0.75),
+        0.0,
+        "负相位按周期折返：-0.75 → 0.25 相位 = 250ms = 首点"
+    );
+    assert!(
+        (LINE.sample(-0.6) - 0.3).abs() < 1.0e-5,
+        "-0.6 → 0.4 相位 = 400ms = 30%"
+    );
+    assert_eq!(LINE.sample(f32::NAN), 0.0, "NaN 不 panic，给首值");
+}
diff --git a/crates/app-iced/src/components/gallery/buttons.rs b/crates/app-iced/src/components/gallery/buttons.rs
new file mode 100644
index 0000000..b6b1451
--- /dev/null
+++ b/crates/app-iced/src/components/gallery/buttons.rs
@@ -0,0 +1,173 @@
+//! 按钮家族的状态矩阵（D30：浅/深 × 五态）。
+//!
+//! ## 矩阵形状
+//!
+//! ```text
+//!                        | enabled | hovered | pressed | focused | disabled |
+//!   filled               |  [btn]  |  [btn]  |  [btn]  |  [btn]  |  [btn]   |
+//!   tonal                |   ...   （下同）
+//!   elevated             |
+//!   outlined             |
+//!   text                 |
+//!   icon·standard        |  [ico]  |   ...
+//!   icon·filled          |
+//!   icon·tonal           |
+//! ```
+//!
+//! 40 个单元格共 5 列 × 8 行，一屏（1180×760）装不下，靠 `gallery/mod.rs` 的 scrollable 滚动；
+//! 截图取的是**整窗**，所以首屏能看到按钮家族的全部 5 行（图标行可能需要滚动，报告里会说明）。
+//!
+//! ## 为什么每格都强制状态
+//!
+//! iced 的 `button::Status` 只由**真实鼠标**驱动，截图时没法让 40 个按钮同时 hover。
+//! 组件层的 `Button::state(...)` 就是为这件事开的取证开关（`--force-state` 只能给整屏一种态）。
+//! 强制值**只影响画什么**，不动任何状态机——所以矩阵图里的五态与运行期五态逐像素同源。
+
+use iced::widget::{column, row};
+use iced::{Element, Length};
+
+use unlucky_design::color::Role;
+use unlucky_design::icons::IconKind;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use crate::theme::Ui;
+
+use super::super::buttons::{self, Button, IconVariant, Variant};
+use super::super::interaction::Interaction;
+use super::{cell_width, heading, row_label, state_cells, DemoMessage};
+
+/// 按钮家族整段（标题 + 列头 + 5 行文字按钮 + 3 行图标按钮 + 一条图例说明）。
+pub(super) fn section<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> {
+    let legend = ui.style(TypeRole::BodySmall);
+
+    let mut rows = column![header_row(ui)].spacing(ui.space(Space::X2));
+
+    for variant in Variant::ALL {
+        let cells = Interaction::ALL
+            .iter()
+            .map(|state| cell(ui, text_button(ui, variant, *state)))
+            .collect::<Vec<_>>();
+
+        rows = rows.push(
+            row![
+                row_label(ui, variant.name()),
+                row(cells).spacing(ui.space(Space::X2))
+            ]
+            .spacing(ui.space(Space::X2)),
+        );
+    }
+
+    for variant in IconVariant::ALL {
+        let cells = Interaction::ALL
+            .iter()
+            .map(|state| cell(ui, icon_button(ui, variant, *state)))
+            .collect::<Vec<_>>();
+
+        rows = rows.push(
+            row![
+                row_label(ui, variant.name()),
+                row(cells).spacing(ui.space(Space::X2))
+            ]
+            .spacing(ui.space(Space::X2)),
+        );
+    }
+
+    column![
+        heading(
+            ui,
+            "buttons · filled / tonal / elevated / outlined / text + icon",
+            "12b §1/§2：高 40 · 圆角 full(20) · 内边距 24（带图标 16/24）· 图标 18 间距 8 · \
+             hover 8% / focus 10% / pressed 10% / disabled 容器 10% 内容 38%"
+        ),
+        rows,
+        iced::widget::text(
+            "图例：列 = 五态（focus 与 pressed 同 α 10%，看起来一样是规范要求）；\
+             行 = 变体。虚线不表示任何东西，只是矩阵栅格。"
+        )
+        .size(legend.size_px)
+        .font(ui.font_of(legend))
+        .color(ui.color(Role::OnSurfaceVariant)),
+    ]
+    .spacing(ui.space(Space::X2))
+    .into()
+}
+
+/// 列头（五态名）。
+fn header_row<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> {
+    let style = ui.style(TypeRole::LabelSmall);
+    let mut head = row![row_label(ui, "")].spacing(ui.space(Space::X2));
+
+    for (name, width) in state_cells(ui) {
+        head = head.push(
+            iced::widget::container(
+                iced::widget::text(name)
+                    .size(style.size_px)
+                    .font(ui.font_of(style))
+                    .color(ui.color(Role::OnSurfaceVariant)),
+            )
+            .width(Length::Fixed(width)),
+        );
+    }
+
+    head.into()
+}
+
+/// 一个矩阵单元格（固定宽，内容左对齐；高度只由按钮自己决定）。
+fn cell<'a>(ui: &'a Ui, content: Element<'a, DemoMessage>) -> Element<'a, DemoMessage> {
+    iced::widget::container(content)
+        .width(Length::Fixed(cell_width(ui)))
+        .into()
+}
+
+/// 文字按钮的一格（强制成 `state`）。
+fn text_button<'a>(ui: &'a Ui, variant: Variant, state: Interaction) -> Element<'a, DemoMessage> {
+    // 标签用变体名 + 首字母大写：图上要能一眼对上左栏，且不引入 i18n 依赖（gallery 不是产品页）
+    let label = match variant {
+        Variant::Filled => "Filled",
+        Variant::Tonal => "Tonal",
+        Variant::Elevated => "Elevated",
+        Variant::Outlined => "Outlined",
+        Variant::Text => "Text",
+    };
+
+    // 五态共用**同一套**装配，只有「有没有消息」随禁用变：
+    // 早先禁用格单独走 `Button::disabled(label)`，把前后图标一起丢了，于是 disabled 列看起来
+    // 像另一个组件（视觉 reviewer P2-3）。
+    let mut spec = if state.is_disabled() {
+        Button::disabled(label)
+    } else {
+        Button::new(label, DemoMessage::Pressed(label))
+    }
+    .state(state);
+    if variant != Variant::Text {
+        // 两个样例都必须是**描边**字形：`Play` 是填充字形，和 `ChevronRight` 混在一颗按钮里
+        // 会显得线宽不一致（视觉 reviewer P2-3）。主操作允许实心，但只能单独出现。
+        spec = spec
+            .leading(IconKind::Download)
+            .trailing(IconKind::ChevronRight);
+    }
+
+    match variant {
+        Variant::Filled => buttons::filled(ui, spec),
+        Variant::Tonal => buttons::tonal(ui, spec),
+        Variant::Elevated => buttons::elevated(ui, spec),
+        Variant::Outlined => buttons::outlined(ui, spec),
+        Variant::Text => buttons::text(ui, spec),
+    }
+}
+
+/// 图标按钮的一格（强制成 `state`）。
+fn icon_button<'a>(
+    ui: &'a Ui,
+    variant: IconVariant,
+    state: Interaction,
+) -> Element<'a, DemoMessage> {
+    let press = if state.is_disabled() {
+        None
+    } else {
+        Some(DemoMessage::Pressed(variant.name()))
+    };
+
+    buttons::icon(ui, variant, IconKind::Settings, press, Some(state))
+}
diff --git a/crates/app-iced/src/components/gallery/feedback.rs b/crates/app-iced/src/components/gallery/feedback.rs
new file mode 100644
index 0000000..7da2d75
--- /dev/null
+++ b/crates/app-iced/src/components/gallery/feedback.rs
@@ -0,0 +1,365 @@
+//! gallery 里的反馈类小节：把状态矩阵摆进 harness（**断言不在这里**，在
+//! [`crate::app::components::feedback::probe`]）。
+//!
+//! ## 段落切分：`ULL_FEEDBACK_PART`（本文件自己的开关）
+//!
+//! `ULL_GALLERY_SECTION=feedback` 只能把**整个家族**拎出来，而四件的高度超过 1180×760 首屏，
+//! 所以再加一层**家族内**切分（契约 §9.2 的口径：环境变量 + 默认向后兼容 + 未识别的值回落
+//! 默认并打 stderr；区别只是它住在**本家族自己的文件**里，不动 `gallery/mod.rs`）：
+//!
+//! ```text
+//! ULL_FEEDBACK_PART=all       # 默认：四件全渲染（progress → snackbar → empty → dialog）
+//! ULL_FEEDBACK_PART=progress  # Linear 0/50/100 + 三相位 · Circular 0/25/50/75/100 + 不定态
+//! ULL_FEEDBACK_PART=snackbar  # 四格：贴顶·上限宽 / 双行 / 宿主 300 / 宿主 344
+//! ULL_FEEDBACK_PART=dialog    # 两形态并排 + 双动作 + 一屏 scrim
+//! ULL_FEEDBACK_PART=empty     # 空态（带 CTA）
+//! ```
+//!
+//! ## 宿主尺寸为什么写死
+//!
+//! 量宽度必须有确定的宿主宽：`Snackbar` 的 600 是「宿主给 800 时的夹取值」、344 与 300 是
+//! 「宿主给多少就是多少」的反证（组件没有 min-width，G17-d）。`Linear` 轨道统一 320（一行 3 格 = 960 < 1128）。
+//!
+//! 复现（worktree 根目录）：
+//!
+//! ```text
+//! ULL_GALLERY_SECTION=feedback ULL_FEEDBACK_PART=progress ./target/debug/unlucky-launcher-iced \
+//!   --software-renderer --screen=gallery \
+//!   --screenshot target/m78/progress-light.png --screenshot-theme=light
+//! ULL_GALLERY_SHOT=target/m78/progress-light.png cargo test -p app-iced feedback::probe
+//! ```
+
+use iced::widget::{column, container, row, text};
+use iced::{Element, Length};
+
+use unlucky_design::color::Role;
+use unlucky_design::icons::IconKind;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use crate::theme::Ui;
+
+use super::super::feedback::gallery_parts::{Part, DIALOG, EMPTY, PROGRESS, SNACKBAR};
+use super::super::feedback::{self, Dialog, EmptyState, Placement, Progress, Snackbar};
+use super::super::interaction::Interaction;
+use super::{heading, DemoMessage};
+
+/// 线性进度的宿主宽（格宽，不是组件尺寸）。
+const TRACK_HOST: f32 = 320.0;
+/// `Snackbar` 的宿主宽：**条宽 + 2×12 外边距**（12 是官方外边距，组件的定位层会扣掉）。
+///
+/// 800（条夹到上限 600）/ 368（条 344）/ 324（条 300，用来证明**没有**下限，G17-d）。
+const HOST_WIDE: f32 = 800.0;
+const HOST_MIN: f32 = 368.0;
+const HOST_NARROW: f32 = 324.0;
+/// `Snackbar` 宿主高（比 68 + 2×12 略高，留出贴顶/贴底的判定余量）。
+const HOST_TALL: f32 = 96.0;
+/// 窄宿主：给 `Dialog::width` 递 360，量「窄宿主不再被裁」的那一格（复审 E）。
+const NARROW_HOST: f32 = 360.0;
+
+/// 单行提示条的宿主高。
+///
+/// **96 而不是 72**（复审 D）：72 = 48 + 2×12 时上下外边距相等，像素上分不出「贴底」还是
+/// 「居中」；96 让贴底那格的上留白 = 36、下留白 = 12，探针能量到「条底距宿主底 = 12」。
+const HOST_SHORT: f32 = 96.0;
+/// 空态宿主高：内容本征高 ≈96+16+32+8+16+24+40 ≈ 232，留出上下各 40 的余量。
+const HOST_EMPTY: f32 = 320.0;
+
+/// 反馈类家族的小节。
+pub(super) fn section<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> {
+    let part = Part::from_env();
+    part.log_once();
+
+    let mut body = column![heading(
+        ui,
+        "feedback · progress / snackbar / dialog / empty state",
+        "12b §7/§12/§14/§15：Linear 厚 4 圆角 full · Circular 40/4 · Snackbar 48/68 上限宽 600 · \
+         Dialog R28 pad24 宽 480 · EmptyState 项目自定[估]（官方无此组件）"
+    )]
+    .spacing(ui.space(Space::X3));
+
+    if part.has(PROGRESS) {
+        body = body.push(progress_block(ui));
+    }
+    if part.has(SNACKBAR) {
+        body = body.push(snackbar_block(ui));
+    }
+    if part.has(EMPTY) {
+        body = body.push(empty_block(ui));
+    }
+    if part.has(DIALOG) {
+        // 只有这一屏不画进度/提示条时，才把三形态与 scrim 都摆开（高度够）。
+        let roomy = !part.has(PROGRESS) && !part.has(SNACKBAR);
+        body = body.push(dialog_block(ui, roomy));
+    }
+
+    body.into()
+}
+
+/// 一行判据说明（`LabelSmall`，与矩阵的正文档分开）。
+fn caption<'a>(ui: &'a Ui, value: &'a str) -> Element<'a, DemoMessage> {
+    let style = ui.style(TypeRole::LabelSmall);
+    text(value)
+        .size(style.size_px)
+        .font(ui.font_of(style))
+        .color(ui.color(Role::OnSurfaceVariant))
+        .into()
+}
+
+/// 带 1px 取景框的宿主：`Snackbar` 的贴底/贴顶需要一条**可见的宿主边界**才量得出来
+/// （描边画在盒内但**不参与布局**：内容区仍是整盒宽，实测条宽不受影响）。
+/// （透明宿主的底边在图上不存在，`Placement::Bottom` 就不可证）。
+fn framed_host<'a>(
+    ui: &'a Ui,
+    width: f32,
+    height: f32,
+    content: impl Into<Element<'a, DemoMessage>>,
+) -> Element<'a, DemoMessage> {
+    let line = ui.color(Role::OutlineVariant);
+    container(content)
+        .width(Length::Fixed(width))
+        .height(Length::Fixed(height))
+        .style(move |_theme| container::Style {
+            border: iced::Border {
+                color: line,
+                width: crate::theme::STROKE_PX,
+                radius: iced::border::Radius::default(),
+            },
+            ..container::Style::default()
+        })
+        .into()
+}
+
+/// 固定宽宿主（量宽度用：宿主宽写死，组件内部的占比/夹取才有确定值）。
+fn host<'a>(
+    width: f32,
+    height: Option<f32>,
+    content: impl Into<Element<'a, DemoMessage>>,
+) -> Element<'a, DemoMessage> {
+    let mut box_ = container(content).width(Length::Fixed(width));
+    if let Some(height) = height {
+        box_ = box_.height(Length::Fixed(height));
+    }
+    box_.into()
+}
+
+/// 一列：[进度条, 说明]。
+fn track<'a>(ui: &'a Ui, label: &'a str, progress: Progress) -> Element<'a, DemoMessage> {
+    column![
+        host(TRACK_HOST, None, feedback::linear(ui, progress)),
+        caption(ui, label)
+    ]
+    .spacing(ui.space(Space::X2))
+    .into()
+}
+
+/// 一列：[环, 说明]。
+fn ring<'a>(ui: &'a Ui, label: &'a str, progress: Progress) -> Element<'a, DemoMessage> {
+    column![feedback::circular(ui, progress), caption(ui, label)]
+        .spacing(ui.space(Space::X2))
+        .into()
+}
+
+/// §12：Linear 0/50/100 + 四个相位；Circular 0/25/50/75/100 + 三个相位。
+fn progress_block<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> {
+    let determinate = row![
+        track(ui, "0%", Progress::determinate(0.0)),
+        track(ui, "50%", Progress::determinate(0.5)),
+        track(ui, "100%", Progress::determinate(1.0)),
+    ]
+    .spacing(ui.space(Space::X3));
+
+    let indeterminate = row![
+        track(ui, "phase 0.15", Progress::indeterminate(0.15)),
+        track(ui, "phase 0.35", Progress::indeterminate(0.35)),
+        track(ui, "phase 0.55", Progress::indeterminate(0.55)),
+    ]
+    .spacing(ui.space(Space::X3));
+
+    let rings = row![
+        ring(ui, "0%", Progress::determinate(0.0)),
+        ring(ui, "25%", Progress::determinate(0.25)),
+        ring(ui, "50%", Progress::determinate(0.5)),
+        ring(ui, "75%", Progress::determinate(0.75)),
+        ring(ui, "100%", Progress::determinate(1.0)),
+        ring(ui, "ind 0.30", Progress::indeterminate(0.30)),
+    ]
+    .spacing(ui.space(Space::X4))
+    .align_y(iced::Alignment::Start);
+
+    column![
+        caption(
+            ui,
+            "Linear · determinate 0% / 50% / 100%（轨道 SecondaryContainer · 指示条 Primary）"
+        ),
+        determinate,
+        caption(
+            ui,
+            "Linear · indeterminate（官方 1750ms 双段追逐；下面是同一周期的三个相位）"
+        ),
+        indeterminate,
+        caption(
+            ui,
+            "Circular · 直径 40 · 线宽 4 · 弧长 = 数值 × 360°（第六格 = 不定态 phase 0.30）"
+        ),
+        rings,
+    ]
+    .spacing(ui.space(Space::X2))
+    .into()
+}
+
+/// 提示条的宿主：固定宽 + 提示条宿主高（比 68 + 2×12 略高，贴顶/贴底都量得到）。
+fn bar_host<'a>(
+    width: f32,
+    content: impl Into<Element<'a, DemoMessage>>,
+) -> Element<'a, DemoMessage> {
+    host(width, Some(HOST_TALL), content)
+}
+
+/// §14：四格 —— 贴顶·上限宽 / 双行 + action + 关闭 / 宿主 300 / 宿主 344。
+fn snackbar_block<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> {
+    let press = |id| DemoMessage::Pressed(id);
+
+    let wide = bar_host(
+        HOST_WIDE,
+        feedback::snackbar(
+            ui,
+            Snackbar::new("版本清单已刷新")
+                .placement(Placement::Top)
+                .dismiss(press("snackbar/wide")),
+        ),
+    );
+    let two_lines = host(
+        HOST_WIDE,
+        Some(HOST_TALL * 2.0),
+        feedback::snackbar(
+            ui,
+            Snackbar::new(
+                "启动失败：找不到 Java 21。请在「设置 · Java」里指定运行时路径，或让启动器自动下载一个 21 的运行时。",
+            )
+                .two_lines()
+                .placement(Placement::Top)
+                .action("去设置", press("snackbar/settings"))
+                .dismiss(press("snackbar/close"))
+                .state(Interaction::Hovered),
+        ),
+    );
+    let mid = framed_host(
+        ui,
+        HOST_MIN,
+        HOST_SHORT,
+        feedback::snackbar(
+            ui,
+            Snackbar::new("已删除实例")
+                .placement(Placement::Bottom)
+                .action("撤销", press("snackbar/undo")),
+        ),
+    );
+    let narrow = framed_host(
+        ui,
+        HOST_NARROW,
+        HOST_SHORT,
+        feedback::snackbar(ui, Snackbar::new("宿主 324").placement(Placement::Bottom)),
+    );
+
+    column![
+        caption(
+            ui,
+            "Snackbar · 贴顶 + 上限宽（宿主 800 → 夹到 600）· 关闭键 InverseOnSurface"
+        ),
+        wide,
+        caption(
+            ui,
+            "Snackbar · 双行 68 + action InversePrimary + 关闭键（动作强制 hover 态）"
+        ),
+        two_lines,
+        caption(
+            ui,
+            "宿主 324（取景框）⇒ 条 300：组件没有 min-width，宿主给多少就是多少（G17-d）；贴底 = 条底距框底 12"
+        ),
+        narrow,
+        caption(ui, "宿主 368 ⇒ 条 344：最小宽的取值口径（[估]）"),
+        mid,
+    ]
+    .spacing(ui.space(Space::X2))
+    .into()
+}
+
+/// §15：空态（项目自定；浅/深两种主题各出一张图，主题来自 `--screenshot-theme`）。
+fn empty_block<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> {
+    let press = |id| DemoMessage::Pressed(id);
+    host(
+        HOST_WIDE,
+        Some(HOST_EMPTY),
+        feedback::empty_state(
+            ui,
+            EmptyState::new(
+                IconKind::Instances,
+                "还没有任何实例",
+                "建一个实例，或者从整合包导入。[项目自定 · 估]",
+            )
+            .action("新建实例", press("empty/create")),
+        ),
+    )
+}
+
+/// §7：三形态（无动作 / 单动作 / 双动作）+ 一屏 scrim。
+///
+/// `full = true` 表示**这一屏只渲染 dialog 段**（`ULL_FEEDBACK_PART=dialog` 或 `=empty` 之类
+/// 单独出图）：此时多摆一屏 scrim，并把三形态都摆开；全家族同屏时留高度给别的段。
+fn dialog_block<'a>(ui: &'a Ui, full: bool) -> Element<'a, DemoMessage> {
+    let press = |id| DemoMessage::Pressed(id);
+
+    // 页面把自己的**可用宽**递给对话框（组件取 `min(可用宽, 480)`）——窄窗口时靠这一手，
+    // 组件自己无法从宿主推（iced 的 Length 没有 min-width，见 `Dialog::width` 的说明）。
+    let plain = feedback::dialog(
+        ui,
+        Dialog::new("已是最新版本", "当前没有可用更新。").width(HOST_WIDE),
+    );
+    let single = feedback::dialog(
+        ui,
+        Dialog::new("已导入整合包", "共 42 个模组，缺失 0 个。")
+            .confirm("知道了", press("dialog/ok")),
+    );
+    // 窄宿主那格：可用宽 360 ⇒ `min(480, 360) = 360`，且不得低于官方下限 280。
+    let narrow = feedback::dialog(
+        ui,
+        Dialog::new("窄宿主 360", "可用宽 360 时取 min(480, 360)。").width(NARROW_HOST),
+    );
+    // 强制 hover：动作件的状态层必须来自 `interaction`（不是组件里自己乘 8%）。
+    let double = feedback::dialog(
+        ui,
+        Dialog::new("删除实例「1.20.1 生存」？", "存档与模组会一起删除。")
+            .double(
+                ("取消", press("dialog/cancel")),
+                ("删除", press("dialog/delete")),
+            )
+            .state(Interaction::Hovered),
+    );
+
+    let mut body = column![caption(
+        ui,
+        "Dialog · R28 · SurfaceContainerHigh + L3（**本项目不画阴影，见 D-1**）· pad 24（标题下 16 / 正文下 24）· 动作 Primary 间距 8",
+    )]
+    .spacing(ui.space(Space::X2));
+
+    body = body.push(row![plain, single].spacing(ui.space(Space::X6)));
+    // 双动作 + 窄宿主并排：探针要同时量到 480 与 360 两种宽
+    body = body.push(row![double, narrow].spacing(ui.space(Space::X6)));
+    if full {
+        body = body.push(caption(
+            ui,
+            "Dialog · scrim = 黑@0.32 叠 canvas 的实色（D27 预合成；详见 dialog.rs 模块文档）",
+        ));
+        body = body.push(host(
+            HOST_WIDE,
+            Some(HOST_EMPTY),
+            feedback::scrimmed(
+                ui,
+                feedback::dialog(ui, Dialog::new("已是最新版本", "当前没有可用更新。")),
+            ),
+        ));
+    }
+
+    body.into()
+}
diff --git a/crates/app-iced/src/components/gallery/inputs.rs b/crates/app-iced/src/components/gallery/inputs.rs
new file mode 100644
index 0000000..04f8e20
--- /dev/null
+++ b/crates/app-iced/src/components/gallery/inputs.rs
@@ -0,0 +1,341 @@
+//! gallery 里的输入类小节（D30 的状态矩阵登记）：TextField / Search / Slider / Menu。
+//!
+//! ## 为什么分成四个 `part`
+//!
+//! 一整段（四组件 × 五态 × 两式）比 760 高的窗口还高，`--screen=gallery` 的截图只能看到顶部。
+//! 所以本文件把证据拆成四个自足的 `part`（[`text_field_part`] / [`search_part`] /
+//! [`slider_part`] / [`menu_part`]），[`section`] 按 D30 的顺序把它们竖排——
+//! 出图时用副本工程把 `section()` 换成单个 `part`（只调段序、不改组件代码，报告里有 diff 与说明）。
+//!
+//! ## 矩阵形状
+//!
+//! ```text
+//! TextField（两行 × 五态）            列 = enabled / hovered / pressed / focused / disabled
+//!   filled    | [字段] | ...
+//!   outlined  | [字段] | ...
+//!   另加三格：空 / 有值 / 错误（9.7 的判据要单独一眼）
+//!
+//! Search  （五行 + 一个展开面板）
+//! Slider  （五态一行 + 0% / 50% / 100% 三行 + 离散 4 段一行）
+//! Menu    （五态各一项的一只菜单 + 一只「展开态」菜单：选中 / 分隔线 / 禁用）
+//! ```
+//!
+//! ## 每个格子都强制状态
+//!
+//! 与按钮家族同一个理由：截图时没法让 20 个控件同时 hover。`state(..)` 只是取证开关，
+//! 不动任何状态机——图上的五态与运行期五态同源。
+
+use iced::widget::{column, container, row, text};
+use iced::{Element, Length};
+
+use unlucky_design::color::Role;
+use unlucky_design::icons::IconKind;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use crate::theme::Ui;
+
+use super::super::inputs::{
+    self, Field, FieldVariant, Menu, MenuItem, SearchBar, SearchView, Slider,
+};
+use super::super::interaction::Interaction;
+use super::{cell_width, heading, row_label, state_cells, DemoMessage};
+
+/// 演示消息（组件只认泛型，gallery 的映射在这里落地）。
+fn pressed(id: &'static str) -> DemoMessage {
+    DemoMessage::Pressed(id)
+}
+
+/// 输入类家族整段（四个 part 竖排；见模块文档的「为什么分成四个 part」）。
+pub(super) fn section<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> {
+    column![
+        heading(
+            ui,
+            "inputs · text field / search / slider / menu",
+            "12b §9/§11/§8 + 15 §20：TextField 高 56（无标签 40）· Search 条 56 药丸 + 图标可视边 16 \
+             （= pad 12 + offset 4）· Slider 轨 16 + 竖条 4×44 · Menu 项 48 + L2 阴影"
+        ),
+        text_field_part(ui),
+        search_part(ui),
+        slider_part(ui),
+        menu_part(ui),
+    ]
+    .spacing(ui.space(Space::X8))
+    .into()
+}
+
+/// 一行小字（图例/说明）。
+fn note<'a>(ui: &'a Ui, value: &'a str) -> Element<'a, DemoMessage> {
+    let style = ui.style(TypeRole::BodySmall);
+    text(value)
+        .size(style.size_px)
+        .font(ui.font_of(style))
+        .color(ui.color(Role::OnSurfaceVariant))
+        .into()
+}
+
+/// 固定宽的矩阵格。
+fn cell<'a>(ui: &'a Ui, content: impl Into<Element<'a, DemoMessage>>) -> Element<'a, DemoMessage> {
+    container(content)
+        .width(Length::Fixed(cell_width(ui)))
+        .into()
+}
+
+/// 五态列头。
+fn state_header<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> {
+    let style = ui.style(TypeRole::LabelSmall);
+    let mut head = row![row_label(ui, "")].spacing(ui.space(Space::X2));
+    for (name, width) in state_cells(ui) {
+        head = head.push(
+            container(
+                text(name)
+                    .size(style.size_px)
+                    .font(ui.font_of(style))
+                    .color(ui.color(Role::OnSurfaceVariant)),
+            )
+            .width(Length::Fixed(width)),
+        );
+    }
+    head.into()
+}
+
+/// 一行矩阵（左侧标签 + 五格）。
+fn state_row<'a>(
+    ui: &'a Ui,
+    label: &'a str,
+    cells: Vec<Element<'a, DemoMessage>>,
+) -> Element<'a, DemoMessage> {
+    row![
+        row_label(ui, label),
+        row(cells).spacing(ui.space(Space::X2))
+    ]
+    .spacing(ui.space(Space::X2))
+    .into()
+}
+
+/// TextField：两式 × 五态 + 空 / 有值 / 错误 三格。
+fn text_field_part<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> {
+    let mut matrix = column![state_header(ui)].spacing(ui.space(Space::X2));
+
+    for variant in FieldVariant::ALL {
+        let cells = Interaction::ALL
+            .iter()
+            .map(|state| {
+                cell(
+                    ui,
+                    inputs::text_field(
+                        ui,
+                        Field::new("实例一")
+                            .variant(variant)
+                            .label("名称")
+                            .state(*state),
+                        |_| pressed("field"),
+                    ),
+                )
+            })
+            .collect::<Vec<_>>();
+        matrix = matrix.push(state_row(ui, variant.name(), cells));
+    }
+
+    // 三格用 **320** 宽（= 2 个矩阵格）：9.2 的最小宽 280 只在这里可验（矩阵格 160 更窄）
+    let wide = Length::Fixed(cell_width(ui) * 2.0);
+    let extras = row![
+        inputs::text_field(
+            ui,
+            Field::new("")
+                .label("名称")
+                .placeholder("请输入名称")
+                .width(wide),
+            |_| pressed("field"),
+        ),
+        inputs::text_field(
+            ui,
+            Field::new("1.21.4")
+                .label("名称")
+                .leading(IconKind::Folder)
+                .width(wide),
+            |_| pressed("field"),
+        ),
+        inputs::text_field(
+            ui,
+            Field::new("")
+                .variant(FieldVariant::Outlined)
+                .label("名称")
+                .placeholder("必填")
+                .trailing(IconKind::Error)
+                .supporting("该名称已被占用")
+                .error()
+                .width(wide),
+            |_| pressed("field"),
+        ),
+    ]
+    .spacing(ui.space(Space::X2));
+
+    column![
+        note(
+            ui,
+            "列 = 五态 · 行 = 两式。静息指示线/描边 1px、聚焦与错误 2px（A1 FocusOutlineWidth）；\
+             错误态线/标签/辅助文本全 Error"
+        ),
+        matrix,
+        note(
+            ui,
+            "另加：空（占位 OnSurfaceVariant）/ 有值（带前置图标 24）/ 错误（2px + 辅助文本）"
+        ),
+        extras,
+    ]
+    .spacing(ui.space(Space::X2))
+    .into()
+}
+
+/// Search：五态 bar 竖排 + 一个展开的 docked 面板。
+fn search_part<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> {
+    let bar_width = ui.space(Space::X8) * 12.0;
+    let mut bars = column![].spacing(ui.space(Space::X2));
+    for state in Interaction::ALL {
+        let bar = inputs::search_bar(
+            ui,
+            SearchBar::new("")
+                .placeholder("搜索实例 / 版本 / mod")
+                .state(state)
+                .width(Length::Fixed(bar_width)),
+            |_| pressed("search"),
+        );
+        bars = bars.push(
+            row![row_label(ui, state.name()), bar]
+                .spacing(ui.space(Space::X2))
+                .align_y(iced::Alignment::Center),
+        );
+    }
+
+    let results: &[&str] = &[
+        "实例：原版 1.21.4",
+        "版本：Fabric 0.16.9",
+        "mod：Sodium 0.6.5",
+    ];
+    let view = inputs::search_view(
+        ui,
+        SearchView::new("1.21", results, "没有匹配的实例").placeholder("搜索实例 / 版本 / mod"),
+        |_| pressed("search"),
+    );
+
+    column![
+        note(
+            ui,
+            "bar：高 56 · 圆角 full(28) · SurfaceContainerHigh · 图标可视边 16 = pad 12 + offset 4（M69 不变量）· \
+             聚焦 1px Secondary；view：docked，头部 56 + 1px Outline 分隔 + 结果区最小高 240"
+        ),
+        row![bars, view].spacing(ui.space(Space::X6)),
+    ]
+    .spacing(ui.space(Space::X2))
+    .into()
+}
+
+/// Slider：五态一行 + 0%/50%/100% 三行 + 离散 4 段一行。
+fn slider_part<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> {
+    let cells = Interaction::ALL
+        .iter()
+        .map(|state| {
+            let enabled = !state.is_disabled();
+            let mut spec = Slider::new(ui, 0.5).state(*state);
+            if enabled {
+                spec = spec.on_change(|_| pressed("slider"));
+            }
+            cell(ui, inputs::slider(spec))
+        })
+        .collect::<Vec<_>>();
+
+    let track_width = ui.space(Space::X8) * 14.0;
+    let mut values = column![].spacing(ui.space(Space::X2));
+    for (label, fraction) in [("0%", 0.0), ("50%", 0.5), ("100%", 1.0)] {
+        let spec = Slider::new(ui, fraction)
+            .on_change(|_| pressed("slider"))
+            .state(Interaction::Enabled);
+        values = values.push(
+            row![
+                row_label(ui, label),
+                container(inputs::slider(spec)).width(Length::Fixed(track_width)),
+            ]
+            .spacing(ui.space(Space::X2))
+            .align_y(iced::Alignment::Center),
+        );
+    }
+
+    // 离散：4 段 = 3 个内部停靠点（25 / 50 / 75%），当前 25% ⇒ 能看到 50% 与 75% 两个点
+    let discrete = row![
+        row_label(ui, "离散 4"),
+        container(inputs::slider(
+            Slider::new(ui, 0.25)
+                .steps(4)
+                .on_change(|_| pressed("slider"))
+                .state(Interaction::Enabled)
+        ))
+        .width(Length::Fixed(track_width)),
+    ]
+    .spacing(ui.space(Space::X2))
+    .align_y(iced::Alignment::Center);
+
+    column![
+        note(
+            ui,
+            "轨 16 full（Primary / SecondaryContainer）· 竖条 4×44 full（overflow 上下各 14）· \
+             focus/pressed 收窄到 2 · 命中 48 · 离散停靠点 4"
+        ),
+        state_row(ui, "五态", cells),
+        note(ui, "0% / 50% / 100%：竖条在两端贴边但不越界（左缘 = 轨道左缘，右缘 = 轨道右缘）"),
+        values,
+        note(
+            ui,
+            "离散：steps(4) ⇒ 3 个内部停靠点（25/50/75%），未激活轨在停靠点两侧留 6 空隙，\n             激活段只画到竖条中心",
+        ),
+        discrete,
+    ]
+    .spacing(ui.space(Space::X2))
+    .into()
+}
+
+/// Menu：一只五态菜单 + 一只展开态菜单（选中 / 分组线 / 禁用）。
+fn menu_part<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> {
+    let width = ui.space(Space::X8) * 8.0;
+
+    let mut states = Menu::new().width(Length::Fixed(width));
+    for state in Interaction::ALL {
+        let mut item = MenuItem::new("重命名", pressed("menu")).state(state);
+        if state.is_disabled() {
+            item = MenuItem::disabled("重命名").state(state);
+        }
+        states = states.item(item.leading(IconKind::Folder));
+    }
+
+    let open = Menu::new()
+        .width(Length::Fixed(width))
+        .item(MenuItem::new("重命名", pressed("menu")).leading(IconKind::Folder))
+        .item(
+            MenuItem::new("复制实例", pressed("menu"))
+                .leading(IconKind::Download)
+                .trailing(IconKind::Check)
+                .selected(),
+        )
+        .divider()
+        .item(MenuItem::disabled("删除").leading(IconKind::Trash));
+
+    column![
+        note(
+            ui,
+            "容器 SurfaceContainer + L2 阴影（blur 6 / offset 2 / Shadow 角色）· 圆角 4（令牌表）· \
+             项高 48 · 水平 12 · 上下留白 8 · 选中项 SecondaryContainer 指示器内缩 4、圆角 8"
+        ),
+        row![
+            column![note(ui, "五态（每项强制一态）"), inputs::menu(ui, states)]
+                .spacing(ui.space(Space::X2)),
+            column![
+                note(ui, "展开：含选中项 / 分组分隔线（复用 divider）/ 不可点项"),
+                inputs::menu(ui, open)
+            ]
+            .spacing(ui.space(Space::X2)),
+        ]
+        .spacing(ui.space(Space::X6)),
+    ]
+    .spacing(ui.space(Space::X2))
+    .into()
+}
diff --git a/crates/app-iced/src/components/gallery/mod.rs b/crates/app-iced/src/components/gallery/mod.rs
new file mode 100644
index 0000000..f83897a
--- /dev/null
+++ b/crates/app-iced/src/components/gallery/mod.rs
@@ -0,0 +1,375 @@
+//! `--screen=gallery` 的壳：**视觉验收 harness**（D30 / D39 §5），不是产品页面。
+//!
+//! ## 它是什么、不是什么
+//!
+//! - 是：**状态矩阵的取景框**。每个家族在自己的 `gallery/<family>.rs` 里摆出
+//!   「五变体 × 五态」的矩阵，一张截图就能判完该家族（浅/深各一张 = 10 张证据）。
+//! - 不是：页面。gallery 允许堆叠、不分页、不做空态，**难看不算问题**；
+//!   但**每个组件本身**必须按官方口径做到位。
+//!
+//! ## 并行地基（后续四条线怎么加东西）
+//!
+//! 五个家族文件在下面 `mod` 里**全部预先声明**了，每个都有自己的 `section()`：
+//!
+//! ```text
+//! gallery/buttons.rs     ← COMPBASE（本 mission）
+//! gallery/selection.rs   ← 后续 mission（只改这个文件）
+//! gallery/inputs.rs      ← 同上
+//! gallery/feedback.rs    ← 同上
+//! gallery/navigation.rs  ← 同上
+//! ```
+//!
+//! 加组件 = 只改自己那个文件里的 `section()`，**不用碰本文件**（这是「五条线并行不冲突」的
+//! 具体保证，也是 tower 会亲手验的一条）。
+//!
+//! ## DemoMessage 为什么独立
+//!
+//! 契约 §2：组件不 import `crate::app::Message`。gallery 用自己定义的消息枚举，
+//! 正好当「组件能脱离业务验收」的示范——`app.rs` 只做一次 `.map(Message::Demo)` 就接上了。
+//!
+//! ## 截图命令（D30）
+//!
+//! ```text
+//! unlucky-launcher-iced --software-renderer --screen=gallery \
+//!     --screenshot out.png --screenshot-theme=light
+//! ```
+//!
+//! `--screenshot` 不带主题时**默认 Light**（可复现；见 `cli::Options::capture_flavor`）。
+//!
+//! ## 段落过滤：环境变量 `ULL_GALLERY_SECTION`（M76 起）
+//!
+//! 五段拼成一列、外面套 `scrollable`，而截图只截**首屏** `1180×760`。段数一多，后面的家族
+//! 就落到折叠线以下（实测：selection 段从 y≈735 起，只剩标题一行）——那条线的
+//! 「渲染层像素断言」就没有一个像素可量。所以这里加一个**段落选择器**：
+//!
+//! ```text
+//! ULL_GALLERY_SECTION=all        # 默认：五段全渲染（行为与加开关之前逐像素一致）
+//! ULL_GALLERY_SECTION=buttons    # 只渲染 buttons 段
+//! ULL_GALLERY_SECTION=selection  # 只渲染 selection 段（本 mission 的取证与 probe 用它）
+//! ```
+//!
+//! 取值：`all` / `buttons` / `divider` / `selection` / `inputs` / `feedback` / `navigation`。
+//! 语义是「**不构建**没被选中的段」（不是构建后隐藏）：`column` 里根本不 push 它，
+//! 于是该家族的 `view` 一行都不跑。未识别的值**回落 `all`** 并在 stderr 打一行提示
+//! （静默回落会让人拿错图还以为拍的是那一段）。
+//!
+//! 为什么用环境变量而不是 `--screen=gallery:<family>`：`cli.rs` 不归组件线（M82 在改它），
+//! 而环境变量既能被测试（`cargo test` 里 `std::env::set_var`）又不用跟别人的 CLI 解析抢文件。
+//! 各家族的 `demo()` 签名**不因此改变**——本文件只决定「push 哪几段」。
+//!
+//! 实际渲染了哪几段会打一行 `[gallery] section=... → 渲染 ...`（首帧一次），
+//! 拿它当出图日志的证据。
+
+use std::sync::atomic::{AtomicBool, Ordering};
+
+use iced::widget::{column, container, scrollable, text};
+use iced::{Alignment, Background, Element, Length};
+
+use unlucky_design::color::Role;
+use unlucky_design::elevation::MaterialLayer;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use crate::shot::flavor_slug;
+use crate::theme::Ui;
+
+use super::divider;
+use super::interaction::Interaction;
+use super::layout;
+
+mod buttons;
+mod feedback;
+mod inputs;
+mod navigation;
+#[cfg(test)]
+mod probe;
+#[cfg(test)]
+mod scan;
+mod selection;
+
+/// 段落过滤的环境变量名（语义见模块文档「段落过滤」）。
+pub const SECTION_ENV: &str = "ULL_GALLERY_SECTION";
+
+/// 段落开关：**构建**哪几段（`false` = 这一段连 `view` 都不跑）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+struct Sections {
+    buttons: bool,
+    divider: bool,
+    selection: bool,
+    inputs: bool,
+    feedback: bool,
+    navigation: bool,
+}
+
+impl Sections {
+    /// 五段全渲染（默认）。
+    const ALL: Self = Self {
+        buttons: true,
+        divider: true,
+        selection: true,
+        inputs: true,
+        feedback: true,
+        navigation: true,
+    };
+
+    /// 只有一段。
+    fn only(name: &str) -> Option<Self> {
+        let mut sections = Self {
+            buttons: false,
+            divider: false,
+            selection: false,
+            inputs: false,
+            feedback: false,
+            navigation: false,
+        };
+        match name {
+            "buttons" => sections.buttons = true,
+            "divider" => sections.divider = true,
+            "selection" => sections.selection = true,
+            "inputs" => sections.inputs = true,
+            "feedback" => sections.feedback = true,
+            "navigation" => sections.navigation = true,
+            _ => return None,
+        }
+        Some(sections)
+    }
+
+    /// 读 `ULL_GALLERY_SECTION`。
+    ///
+    /// 未设置 / 空 / `all`（大小写不敏感）→ 全渲染；**未识别的值 → 回落全渲染 + stderr 一行**。
+    fn from_env() -> Self {
+        let Ok(raw) = std::env::var(SECTION_ENV) else {
+            return Self::ALL;
+        };
+        let name = raw.trim().to_ascii_lowercase();
+        if name.is_empty() || name == "all" {
+            return Self::ALL;
+        }
+        if let Some(sections) = Self::only(&name) {
+            return sections;
+        }
+        eprintln!(
+            "[gallery] {SECTION_ENV}={raw:?} 不是已知段（all|buttons|divider|selection|inputs|feedback|navigation），已回落 all"
+        );
+        Self::ALL
+    }
+
+    /// 本次渲染的段名（stderr 日志 / 测试断言用）。
+    fn names(self) -> Vec<&'static str> {
+        let mut names = Vec::new();
+        for (on, name) in [
+            (self.buttons, "buttons"),
+            (self.divider, "divider"),
+            (self.selection, "selection"),
+            (self.inputs, "inputs"),
+            (self.feedback, "feedback"),
+            (self.navigation, "navigation"),
+        ] {
+            if on {
+                names.push(name);
+            }
+        }
+        names
+    }
+}
+
+/// `[gallery] ... 渲染 ...` 只打一次（`view` 每帧都会跑）。
+static SECTION_LOGGED: AtomicBool = AtomicBool::new(false);
+
+fn log_sections(sections: Sections) {
+    if SECTION_LOGGED.swap(true, Ordering::Relaxed) {
+        return;
+    }
+    let raw = std::env::var(SECTION_ENV).unwrap_or_else(|_| "all".to_owned());
+    eprintln!(
+        "[gallery] section={raw} → 渲染 {} 段：{}",
+        sections.names().len(),
+        sections.names().join(", ")
+    );
+}
+
+/// gallery 自己的消息（与业务 `Message` 解耦，契约 §2）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum DemoMessage {
+    /// 某个演示按钮被按下（`&'static str` = 演示 id，只用于日志）。
+    Pressed(&'static str),
+}
+
+impl DemoMessage {
+    /// 演示 id（日志用；将来加变体时这里跟着改，`app.rs` 不用动）。
+    pub fn id(&self) -> &'static str {
+        match self {
+            DemoMessage::Pressed(id) => id,
+        }
+    }
+}
+
+/// gallery 根视图（整窗：不带标题栏与导航轨，验收图上只有组件）。
+pub fn view<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> {
+    let page = ui.style(TypeRole::BodySmall);
+
+    let header = column![
+        text("Component gallery")
+            .size(ui.emphasized(TypeRole::TitleLarge).size_px)
+            .font(ui.emphasized_font(TypeRole::TitleLarge))
+            .color(ui.color(Role::OnSurface)),
+        text(format!(
+            "M3 Expressive component base · flavor={} · 1180×760 @100% DPI · \
+             focus 与 pressed 同为 10%（令牌口径，图上一样是对的）",
+            flavor_slug(ui)
+        ))
+        .size(page.size_px)
+        .font(ui.font_of(page))
+        .color(ui.color(Role::OnSurfaceVariant)),
+    ]
+    .spacing(ui.space(Space::X1));
+
+    // 小节之间**不画分隔线**：rubric（15 §22.4）要求同屏同类线 ≤3，
+    // 而验收图里要给分隔线自己留证据（见 `divider_proof`）。分组靠 32px 留白 + 标题。
+    //
+    // 段落过滤（`ULL_GALLERY_SECTION`）：**没被选中的段根本不 push**，于是该家族的
+    // `view` 一行都不跑——不是「构建后隐藏」。默认 `all` 与加开关之前逐像素一致。
+    let picked = Sections::from_env();
+    log_sections(picked);
+    let mut sections = column![].spacing(ui.space(Space::X8)).width(Length::Fill);
+    if picked.buttons {
+        sections = sections.push(buttons::section(ui));
+    }
+    if picked.divider {
+        sections = sections.push(divider_proof(ui));
+    }
+    if picked.selection {
+        sections = sections.push(selection::section(ui));
+    }
+    if picked.inputs {
+        sections = sections.push(inputs::section(ui));
+    }
+    if picked.feedback {
+        sections = sections.push(feedback::section(ui));
+    }
+    if picked.navigation {
+        sections = sections.push(navigation::section(ui));
+    }
+
+    // 滚动条：默认是主题给的 10px 深灰 thumb，压过组件本体（视觉 reviewer P2-4）。
+    // 这里把它改成 **透明轨 + OutlineVariant thumb**；宽度 10px 是 `scrollable` 的内部常量
+    // （该控件不暴露 Scrollbar 配置），所以只做了「低对比」这一半，已登记为偏离 D7。
+    let body = scrollable(sections)
+        .height(Length::Fill)
+        .width(Length::Fill)
+        .style(move |theme, status| {
+            // `scrollable::Style` 没有 `Default`：底色/间隙从主题默认值出发，只覆盖竖轨
+            let base = scrollable::default(theme, status);
+            scrollable::Style {
+                vertical_rail: scrollable::Rail {
+                    background: None,
+                    border: iced::Border::default(),
+                    scroller: scrollable::Scroller {
+                        background: Background::Color(ui.color(Role::OutlineVariant)),
+                        border: iced::Border {
+                            radius: ui.radius(ShapeScale::Full, ui.space(Space::X2)),
+                            ..iced::Border::default()
+                        },
+                    },
+                },
+                ..base
+            }
+        });
+
+    // 页面留白走 `layout::inset`（左右/上下各 24）：这是 Q8/Q9 那两个 helper 的第三个兄弟，
+    // 存在意义是「只改内边距、不改尺寸」，也顺手避免把 Padding 的上右下左写反。
+    let page_padding = ui.space(Space::X6);
+    container(layout::inset(
+        page_padding,
+        page_padding,
+        column![header, body].spacing(ui.space(Space::X4)),
+    ))
+    .width(Length::Fill)
+    .height(Length::Fill)
+    .style(|_theme| container::Style {
+        background: Some(Background::Color(ui.layer(MaterialLayer::Canvas))),
+        ..container::Style::default()
+    })
+    .into()
+}
+
+/// 分隔线的视觉证据（§22）：一条通栏 + 一条列表内缩进，各自带说明。
+///
+/// 单独一节而不是散落各处：`15 §22.4` 说「同屏同类线 ≤3」，这两条是**唯一**计入的两条。
+fn divider_proof<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> {
+    let caption = ui.style(TypeRole::LabelSmall);
+    let label = |text_value: &'a str| {
+        text(text_value)
+            .size(caption.size_px)
+            .font(ui.font_of(caption))
+            .color(ui.color(Role::OnSurfaceVariant))
+    };
+
+    column![
+        heading(
+            ui,
+            "divider · full / list-inset",
+            "15 §22：厚度 1px（stroke::HAIRLINE）· 颜色 OutlineVariant · 列表内左缩进 16 · 同屏 ≤3 条"
+        ),
+        label("full (通栏，区块分隔)"),
+        divider::full::<DemoMessage>(ui),
+        label("list (左缩进 16)"),
+        divider::list::<DemoMessage>(ui),
+    ]
+    .spacing(ui.space(Space::X2))
+    .into()
+}
+
+/// 一个家族小节的标题（`index.title`）+ 一行判据说明。
+///
+/// 五个家族文件共用（`pub(super)`），保证五段的节奏一致——这也是 rubric D4
+/// 「一屏字号档 ≤4」的落点：小节只有 `TitleMedium` + `BodySmall` 两档。
+pub(crate) fn heading<'a>(ui: &'a Ui, title: &'a str, note: &'a str) -> Element<'a, DemoMessage> {
+    let note_style = ui.style(TypeRole::BodySmall);
+    column![
+        text(title)
+            .size(ui.emphasized(TypeRole::TitleMedium).size_px)
+            .font(ui.emphasized_font(TypeRole::TitleMedium))
+            .color(ui.color(Role::OnSurface)),
+        text(note)
+            .size(note_style.size_px)
+            .font(ui.font_of(note_style))
+            .color(ui.color(Role::OnSurfaceVariant)),
+    ]
+    .spacing(ui.space(Space::X1))
+    .into()
+}
+
+/// 状态矩阵的列头：五态的固定次序（`Interaction::ALL` 的口径）。
+///
+/// 列宽 = [`cell_width`]（**160** = `Space::X8 × 5`，是矩阵栅格，不是组件尺寸）。
+pub(crate) fn state_cells(ui: &Ui) -> Vec<(&'static str, f32)> {
+    Interaction::ALL
+        .iter()
+        .map(|state| (state.name(), cell_width(ui)))
+        .collect()
+}
+
+/// 矩阵单元格宽度（只影响 harness 的取景，不是组件尺寸）。
+///
+/// 160 = `Space::X8 × 5`：5 列 + 1 个标签列 + 4 个列间距 + 页左右各 24
+/// = 6×160 + 4×8 + 48 = **1040 < 1180**，所以第 5 列（disabled）不再被窗口右缘裁掉。
+/// 早先是 192（×6），总宽 1232 撑破窗口，disabled 列被裁掉一半（视觉 reviewer P2-3）。
+pub(crate) fn cell_width(ui: &Ui) -> f32 {
+    ui.space(Space::X8) * 5.0
+}
+
+/// 一个矩阵行的左侧标签（变体名）。
+pub(crate) fn row_label<'a>(ui: &'a Ui, name: &'a str) -> Element<'a, DemoMessage> {
+    let style = ui.style(TypeRole::BodySmall);
+    container(
+        text(name)
+            .size(style.size_px)
+            .font(ui.font_of(style))
+            .color(ui.color(Role::OnSurfaceVariant)),
+    )
+    .width(Length::Fixed(cell_width(ui)))
+    .align_y(Alignment::Center)
+    .into()
+}
diff --git a/crates/app-iced/src/components/gallery/navigation.rs b/crates/app-iced/src/components/gallery/navigation.rs
new file mode 100644
index 0000000..1ca5830
--- /dev/null
+++ b/crates/app-iced/src/components/gallery/navigation.rs
@@ -0,0 +1,352 @@
+//! gallery 里的导航类小节：四块状态矩阵 + 一块长文案块（**断言在 `navigation::probe`**）。
+//!
+//! ## 块选择器 `ULL_NAV_PART`
+//!
+//! `ULL_GALLERY_SECTION=navigation` 只隔离家族；本家族自己就有四块矩阵 + 长文案块，竖排比 760 高，
+//! 一屏只拍得到第一块。所以按契约 §9.2 的同一套规则再切一层（环境变量 + 默认兼容 + 未知值回落并打
+//! stderr）：`ULL_NAV_PART=list|tabs|drawer|appbar|long|all`（默认 `all`）。
+//!
+//! ```text
+//! ULL_GALLERY_SECTION=navigation ULL_NAV_PART=list ./target/debug/unlucky-launcher-iced.exe //!   --software-renderer --screen=gallery --screenshot target/m79/list-light.png --screenshot-theme=light
+//! ULL_NAV_DIR=target/m79 cargo test -p unlucky-app-iced navigation::probe
+//! ```
+//!
+//! ## 矩阵形状
+//!
+//! ```text
+//! ListItem   行 = 一 / 两 / 三行（44 / 60 / 76）   列 = 选中 / 未选中 / 禁用（三列槽位完全相同）
+//! Tabs       三行 Primary（选中第 1/2/3 个）+ 一行 Secondary + 一行五态
+//! Drawer     rail 88 与 drawer 240 **同尺度并排**（D33），各 3 项、第 2 项 hover、第 3 项禁用
+//! AppBar     静息 / 滚动两态（56 高；滚动只换容器色 + L2）
+//! long       长文案：页头 + 三行 ListItem + drawer（单行约束 D-M79-5 的取证）
+//! ```
+//!
+//! 取景板（`SurfaceContainerLow`）不是装饰：`Surface` 的页头/导航与页面底色同色，不垫一层板子，
+//! 截图里量不到边界（probe 就是靠板量 88 / 240 的）。
+
+use iced::widget::{column, container, row, text};
+use iced::{Background, Element, Length};
+
+use unlucky_design::color::Role;
+use unlucky_design::icons::IconKind;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use crate::theme::Ui;
+
+use super::super::interaction::Interaction;
+use super::super::navigation::{
+    self, app_bar, list_item, navigation, tabs, AppBar, AppBarAction, ListItem, NavGroup, NavItem,
+    NavLayout, Navigation, Tab, Tabs, TabsVariant,
+};
+use super::{heading, DemoMessage};
+
+/// 块选择器的环境变量名（语义见模块文档）。
+pub const PART_ENV: &str = "ULL_NAV_PART";
+
+/// 本次渲染哪一块（`all` = 四块都渲染，默认）。
+fn part() -> String {
+    let Ok(raw) = std::env::var(PART_ENV) else {
+        return "all".to_owned();
+    };
+    let name = raw.trim().to_ascii_lowercase();
+    match name.as_str() {
+        "" | "all" | "list" | "tabs" | "drawer" | "appbar" | "long" => name,
+        _ => {
+            eprintln!(
+                "[gallery] {PART_ENV}={raw:?} 不是已知块（all|list|tabs|drawer|appbar|long），已回落 all"
+            );
+            "all".to_owned()
+        }
+    }
+}
+
+/// 演示消息（组件只认泛型，映射在 gallery 侧落地）。
+fn pressed() -> DemoMessage {
+    DemoMessage::Pressed("navigation")
+}
+
+fn icon(name: &str) -> IconKind {
+    match name {
+        "download" => IconKind::Download,
+        "logs" => IconKind::Logs,
+        "settings" => IconKind::Settings,
+        _ => IconKind::Instances,
+    }
+}
+
+/// 取景板：`SurfaceContainerLow` 底（`Surface` 的页头/导航要靠它才有边界）。
+fn plate<'a>(
+    ui: &'a Ui,
+    pad: f32,
+    content: impl Into<Element<'a, DemoMessage>>,
+) -> Element<'a, DemoMessage> {
+    container(content)
+        .padding(pad)
+        .style(move |_theme| container::Style {
+            background: Some(Background::Color(ui.color(Role::SurfaceContainerLow))),
+            ..container::Style::default()
+        })
+        .into()
+}
+
+/// 一行小字图例。
+fn note<'a>(ui: &'a Ui, value: &'a str) -> Element<'a, DemoMessage> {
+    let style = ui.style(TypeRole::BodySmall);
+    text(value)
+        .size(style.size_px)
+        .font(ui.font_of(style))
+        .color(ui.color(Role::OnSurfaceVariant))
+        .into()
+}
+
+/// 导航类家族的小节。
+pub(super) fn section<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> {
+    let picked = part();
+    let mut body = column![heading(
+        ui,
+        "navigation · list item / tabs / drawer / app bar",
+        "12b §4/§6/§16 + 15 §21：ListItem 44/60/76 · Tabs 48 + 指示条 3 · \
+         Drawer = rail 88 ⇄ drawer 240（同一容器）· AppBar 56 + 滚动换色"
+    )]
+    .spacing(ui.space(Space::X8));
+
+    if picked == "all" || picked == "list" {
+        body = body.push(list_part(ui));
+    }
+    if picked == "all" || picked == "tabs" {
+        body = body.push(tabs_part(ui));
+    }
+    if picked == "all" || picked == "drawer" {
+        body = body.push(drawer_part(ui));
+    }
+    if picked == "all" || picked == "appbar" {
+        body = body.push(app_bar_part(ui));
+    }
+    if picked == "long" {
+        body = body.push(navigation::matrix::long_part(ui, pressed));
+    }
+    body.into()
+}
+
+/// 一个列表格（宽 = `nav_drawer_width` 240：够放下 icon + 两行文本，且与 drawer 药丸 216 可区分）。
+fn list_cell<'a>(ui: &'a Ui, item: ListItem<'a, DemoMessage>) -> Element<'a, DemoMessage> {
+    container(list_item(ui, item))
+        .width(Length::Fixed(ui.metrics().nav_drawer_width))
+        .into()
+}
+
+/// ListItem：三行高 × {选中 / 未选中 / 禁用}。
+fn list_part<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> {
+    let states = ["selected", "enabled", "disabled"];
+
+    let mut grid = column![].spacing(ui.space(Space::X4));
+    let header = states
+        .iter()
+        .map(|name| {
+            container(note(ui, name))
+                .width(Length::Fixed(ui.metrics().nav_drawer_width))
+                .into()
+        })
+        .collect::<Vec<Element<'a, DemoMessage>>>();
+    grid = grid.push(
+        row![
+            note(ui, "rows +16 each · 44 / 60 / 76"),
+            row(header).spacing(ui.space(Space::X2))
+        ]
+        .spacing(ui.space(Space::X2)),
+    );
+
+    for (index, lines) in ["one line", "two lines", "three lines"].iter().enumerate() {
+        let mut cells = row![].spacing(ui.space(Space::X2));
+        for state in states {
+            // 三列的**内容完全相同**（同样的槽位），只有态不同——否则「选中 trailing = Primary」
+            // 这条结论没有可比对象（视觉 r1 P2-2 点名）
+            let mut item = ListItem::new(lines, pressed())
+                .leading(icon("instances"))
+                .trailing(icon("settings"));
+            if index >= 1 {
+                item = item.supporting("3 versions · 1.21.4");
+            }
+            if index >= 2 {
+                item = item.overline("RECENT");
+            }
+            item = match state {
+                "selected" => item.selected(),
+                // 禁用是修饰器：这里只清消息，槽位全部保留
+                "disabled" => item.disabled(),
+                _ => item.state(Interaction::Enabled),
+            };
+            cells = cells.push(list_cell(ui, item));
+        }
+        grid = grid.push(cells);
+    }
+
+    column![
+        note(
+            ui,
+            "ListItem · 选中 = SecondaryContainer（偏离 D-M79-1：A1 的 ListItem 不换底色）· \
+             禁用 = OnSurface@38%（A1 ListTokens）"
+        ),
+        grid,
+    ]
+    .spacing(ui.space(Space::X2))
+    .into()
+}
+
+/// Tabs：两行 Primary（短 / 长文案各选中一次 → 指示条宽度必须不同）+ Secondary + 五态。
+fn tabs_part<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> {
+    let primary_row = |selected: usize| {
+        let mut builder = Tabs::primary();
+        for (index, label) in ["Logs", "Instance details", "Settings"].iter().enumerate() {
+            let mut tab = Tab::new(label, pressed());
+            if index == 2 {
+                // 6.1：带图标的 Tabs 容器高 64（纯文字 48）
+                tab = tab.icon(icon("settings"));
+            }
+            if index == selected {
+                tab = tab.selected();
+            }
+            builder = builder.tab(tab);
+        }
+        tabs(ui, builder)
+    };
+
+    let state_row = {
+        let mut builder = Tabs::primary();
+        for (index, state) in [
+            Interaction::Enabled,
+            Interaction::Hovered,
+            Interaction::Focused,
+            Interaction::Pressed,
+            Interaction::Disabled,
+        ]
+        .iter()
+        .enumerate()
+        {
+            let mut tab = Tab::new("Tab", pressed()).state(*state);
+            if index == 0 {
+                tab = tab.selected();
+            }
+            builder = builder.tab(tab);
+        }
+        tabs(ui, builder)
+    };
+
+    let secondary = tabs(
+        ui,
+        Tabs::secondary()
+            .tab(Tab::new("Release", pressed()).selected())
+            .tab(Tab::new("Snapshot", pressed()))
+            .tab(Tab::new("Legacy", pressed()).disabled()),
+    );
+
+    // 两式的名字进图例（同时把 `TabsVariant::ALL` 变成可点检的常量，而不是死代码）
+    let legend = TabsVariant::ALL
+        .iter()
+        .map(|variant| note(ui, variant.name()))
+        .collect::<Vec<_>>();
+
+    column![
+        note(
+            ui,
+            "Tabs · Primary 三行 = 选中第 1 / 2 / 3 个（指示条跟着走且宽度跟随该项）；Secondary：1px SurfaceVariant"
+        ),
+        row(legend).spacing(ui.space(Space::X4)),
+        primary_row(0),
+        primary_row(1),
+        primary_row(2),
+        secondary,
+        note(ui, "Primary 五态（第 1 项选中；未选项 hover/focus/pressed 提到 OnSurface）"),
+        state_row,
+    ]
+    .spacing(ui.space(Space::X2))
+    .into()
+}
+
+/// 导航容器：rail 88 与 drawer 240 **同尺度并排**（D33 的可验收形式）。
+fn drawer_part<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> {
+    // 取景板高 288（= Space::X8 × 9）：装得下 drawer 的「两个分组 + 三项 + 两次标题」，否则末行被裁
+    let plate_height = ui.space(Space::X8) * 9.0;
+    let mut panes = row![].spacing(ui.space(Space::X6));
+
+    for layout in NavLayout::ALL {
+        let builder = match layout {
+            NavLayout::Rail => Navigation::rail(),
+            NavLayout::Drawer => Navigation::drawer(),
+        };
+        let pane = builder
+            .group(
+                NavGroup::titled("LIBRARY")
+                    .item(NavItem::new("Instances", icon("instances"), pressed()).selected())
+                    .item(
+                        NavItem::new("Download", icon("download"), pressed())
+                            .state(Interaction::Hovered),
+                    ),
+            )
+            .group(
+                NavGroup::titled("SYSTEM")
+                    .item(NavItem::new("Settings", icon("settings"), pressed()).disabled()),
+            );
+        let width = match layout {
+            NavLayout::Rail => ui.metrics().nav_rail_width,
+            NavLayout::Drawer => ui.metrics().nav_drawer_width,
+        };
+        // 取景板比容器大一圈（pad 8）：`Surface` 的导航与页面底色同色，板要露边才量得到
+        let pad = ui.space(Space::X2);
+        panes = panes.push(
+            container(container(navigation(ui, pane)).height(Length::Fixed(plate_height)))
+                .width(Length::Fixed(width + pad * 2.0))
+                .height(Length::Fixed(plate_height + pad * 2.0))
+                .padding(pad)
+                .style(move |_theme| container::Style {
+                    background: Some(Background::Color(ui.color(Role::SurfaceContainerLow))),
+                    ..container::Style::default()
+                }),
+        );
+    }
+
+    column![
+        note(
+            ui,
+            "D33：同一个容器两个宽度 —— rail（药丸 56×32）｜drawer（药丸 216×56，左右各缩 12）；             第 2 项 hover、第 3 项禁用"
+        ),
+        panes,
+        row![
+            note(ui, "左→右："),
+            note(ui, NavLayout::Rail.name()),
+            note(ui, NavLayout::Drawer.name()),
+        ]
+        .spacing(ui.space(Space::X2)),
+    ]
+    .spacing(ui.space(Space::X2))
+    .into()
+}
+
+/// AppBar small：静息 / 滚动两态（56 高；滚动换容器色 + L2）。
+fn app_bar_part<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> {
+    let bar = |scrolled: bool| {
+        app_bar(
+            ui,
+            AppBar::new("Instances")
+                .subtitle(if scrolled {
+                    "scrolled · SurfaceContainer + L2"
+                } else {
+                    "resting · Surface + L0"
+                })
+                .leading(AppBarAction::inert(icon("instances")))
+                .trailing(AppBarAction::new(icon("settings"), pressed()))
+                .scrolled(scrolled),
+        )
+    };
+
+    column![
+        note(
+            ui,
+            "AppBar small · 56 高（A1 64，偏离 D-M79-2）· 滚动只换容器色与高程，不改高度（A1 无 OnScroll…Height）"
+        ),
+        plate(ui, ui.space(Space::X2), column![bar(false), bar(true)].spacing(ui.space(Space::X2))),
+    ]
+    .spacing(ui.space(Space::X2))
+    .into()
+}
diff --git a/crates/app-iced/src/components/gallery/probe.rs b/crates/app-iced/src/components/gallery/probe.rs
new file mode 100644
index 0000000..73f927f
--- /dev/null
+++ b/crates/app-iced/src/components/gallery/probe.rs
@@ -0,0 +1,368 @@
+//! 渲染层几何断言：**对着真截图量像素**（M68 的教训：纯函数返回对，图可能是错的）。
+//!
+//! `buttons::tests` 只能证明「几何结构体里的数字是 40/20/24」——M68 的药丸正是这样：单测全绿、
+//! 图上是 88×32（容器被 `center_x(Length::Fill)` 覆盖）。唯一能抓住这类错误的是**真渲染的像素**。
+//! CI 没有桌面，所以这里不自己开窗：先用 `--screen=gallery --screenshot` 出真窗截图，本测试读
+//! 那张 PNG 量几何、与令牌逐项比对。**没给图就跳过并大声说出来**（不静默通过）。
+//!
+//! 复现命令（在 worktree 根目录）：
+//!
+//! ```text
+//! cargo build -p unlucky-app-iced --bin unlucky-launcher-iced
+//! ./target/debug/unlucky-launcher-iced --software-renderer --screen=gallery \
+//!   --screenshot target/m75/gallery-light.png --screenshot-theme=light
+//! ULL_GALLERY_SHOT=target/m75/gallery-light.png cargo test -p unlucky-app-iced gallery::probe
+//! ```
+//!
+//! 量什么（每条对一个已发生过的错误）：实心块高 **40**（12b 1.1）· 药丸顶行**左内缩 ≈14** ⇒ 圆角 full=20
+//! （12b 1.2，8 圆角会接近通栏）· IconButton **40×40**（12b 2.1）· 字形墨迹 **16~26**
+//! （Q9：24 盒被填满会到 40）· 分隔线 **1px**（22.1）· 禁用容器 **on-surface@10%**（按钮族）存在（12b 1.8）。
+
+use unlucky_design::color::{Role, SchemeFlavor};
+use unlucky_design::typography::Platform;
+
+use crate::theme::{Families, Ui};
+
+use crate::app::components::interaction;
+
+use super::scan::{matches, nearer, rgb, Shot};
+
+const FAMILIES: Families = Families {
+    text: "Segoe UI",
+    display: "Segoe UI",
+    mono: "Consolas",
+};
+
+fn ui(flavor: SchemeFlavor) -> Ui {
+    Ui::with_platform(flavor, Platform::Windows, FAMILIES)
+}
+
+/// 一条 1dp 细线在竖直方向的「墨量覆盖率」：各行相对底色的不透明度之和（1dp ⇒ ≈1.0）。
+///
+/// **只统计「长横线行」**（连续非底色像素 > 900）：标题/正文那些行也有几百个零散墨迹像素，
+/// 按「任意非底色像素数」筛会把文字算进墨量（首版实测 57.9，明显是文字被算进去了）。
+fn line_coverage(shot: &Shot, surface: [u8; 3], line: [u8; 3]) -> f32 {
+    let mut total = 0.0;
+    for y in 0..shot.height {
+        let mut longest = 0;
+        let mut current = 0;
+        let mut sum = 0.0f32;
+        let mut run_sum = 0.0f32;
+        for x in 0..shot.width {
+            let pixel = shot.at(x, y);
+            if !matches(pixel, surface) {
+                current += 1;
+                run_sum += delta_ratio(pixel, surface, line);
+                if current > longest {
+                    longest = current;
+                    sum = run_sum;
+                }
+            } else {
+                current = 0;
+                run_sum = 0.0;
+            }
+        }
+        if longest > 900 {
+            total += sum / longest as f32;
+        }
+    }
+    total
+}
+
+/// `pixel` 相对 `surface` 的偏移占「满档 line 色偏移」的比例（0..=1）。
+fn delta_ratio(pixel: [u8; 3], surface: [u8; 3], line: [u8; 3]) -> f32 {
+    let channel = |i: usize| {
+        let full = f32::from(line[i]) - f32::from(surface[i]);
+        if full.abs() < 1.0 {
+            return 0.0;
+        }
+        ((f32::from(pixel[i]) - f32::from(surface[i])) / full).clamp(0.0, 1.0)
+    };
+    let (dr, dg, db) = (channel(0), channel(1), channel(2));
+    (dr + dg + db) / 3.0
+}
+
+/// `ULL_GALLERY_SHOT` → 截图路径（相对路径按**工作区根**解释：`cargo test` 的 cwd 是 crate 目录）。
+fn shot_path() -> Option<std::path::PathBuf> {
+    let raw = std::env::var_os("ULL_GALLERY_SHOT")?;
+    let path = std::path::PathBuf::from(raw);
+    if path.is_absolute() || path.exists() {
+        return Some(path);
+    }
+    let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../..");
+    Some(root.join(path))
+}
+
+/// 一条测试覆盖全部几何断言（每张图各跑一次）。
+#[test]
+fn gallery_geometry_matches_the_tokens() {
+    let Some(path) = shot_path() else {
+        eprintln!(
+            "[probe] SKIPPED：未设置 ULL_GALLERY_SHOT。这是**渲染层**几何断言，\
+             需要先出一张真窗截图（命令见本文件模块文档）。"
+        );
+        return;
+    };
+
+    let shot = Shot::load(&path).expect("读 gallery 截图");
+    assert_eq!(
+        (shot.width, shot.height),
+        (1180, 760),
+        "验收图必须是 D30 的 1180×760 @100% DPI"
+    );
+
+    // 用左上角背景色判定深浅（页面 padding 区就是 `Surface`）
+    let corner = shot.at(2, 2);
+    let flavor = if matches(corner, rgb(ui(SchemeFlavor::Light).color(Role::Surface))) {
+        SchemeFlavor::Light
+    } else {
+        SchemeFlavor::Dark
+    };
+    let ui = ui(flavor);
+
+    // ---- 12b 1.1 / 1.2：实心按钮 40 高、药丸圆角 20 ------------------------------
+    let primary = shot.bbox_of(rgb(ui.color(Role::Primary)));
+    assert!(
+        primary.len() >= 2,
+        "至少该找到 Filled 按钮与 Filled IconButton 两块实心（实际 {}）",
+        primary.len()
+    );
+
+    let mut label_button = None;
+    for bbox in &primary {
+        // 字形（OnPrimary）会把实心块割出小碎片，只判「成块的」（40×40 = 1600）
+        if bbox.area() < 800 {
+            continue;
+        }
+        assert!(
+            (39..=41).contains(&bbox.height()),
+            "实心块高 {}（参考 40，12b 1.1）@ {:?}",
+            bbox.height(),
+            (bbox.left, bbox.top)
+        );
+        if bbox.width() > 60 {
+            label_button = Some(*bbox);
+        }
+        // 12b 2.1：IconButton 容器精确 40×40（别再用区间——reviewer 已证 +2px 抓不住）
+        if bbox.width() < 60 {
+            // 宽 = 40（最宽那行是实色，量得准）；高会把底部抗锯齿行排除掉，所以是 39 或 40。
+            // 区间收到 39..=40 仍能抓 ±2px 的回归（42 → 41、38 → 37 都会落区间外）。
+            assert_eq!(bbox.width(), 40, "IconButton 容器宽必须 40（12b 2.1）");
+            assert!(
+                (39..=40).contains(&bbox.height()),
+                "IconButton 容器高应 40（实色 39 + 抗锯齿行），实测 {}",
+                bbox.height()
+            );
+        }
+    }
+
+    let label_button = label_button.expect("没找到文字按钮的实心块");
+    assert!(
+        label_button.width() >= 58,
+        "12b 1.7：最小宽 58，实测 {}",
+        label_button.width()
+    );
+
+    // 含抗锯齿的真实外框：中心列上「更接近填充色而不是底色」的连续行
+    let fill = rgb(ui.color(Role::Primary));
+    let surface = rgb(ui.color(Role::Surface));
+    let center = (label_button.left + label_button.right) / 2;
+    let mut true_top = label_button.top;
+    while true_top > 0 && nearer(shot.at(center, true_top - 1), fill, surface) {
+        true_top -= 1;
+    }
+    let mut true_bottom = label_button.bottom;
+    while true_bottom + 1 < shot.height && nearer(shot.at(center, true_bottom + 1), fill, surface) {
+        true_bottom += 1;
+    }
+    let true_height = true_bottom - true_top + 1;
+
+    // **精确 40**：变异成 42 必须红。上一版写的是 `(39..=41).contains(..)`，
+    // reviewer 把高度改成 42 重新出图后断言照样绿 —— 那就是「渲层断言等于没有」。
+    assert_eq!(
+        true_height, 40,
+        "可见高必须精确 40（12b 1.1）；变异成 42 这里就会红"
+    );
+
+    // 圆角档位：量**顶部那一行的左内缩**。按像素中心口径，第 k 行（k 从 0 起）的闭式是
+    // inset(k) = r − √(r² − (r − k − 0.5)²)；r=20、k=1 给 **12.40**（实测 12~14），
+    // r=8 只有 ≈3.6，直角为 0。比「数圆角行数」抗锯齿得多。
+    let top_row_left = (label_button.left..=label_button.right)
+        .find(|x| matches(shot.at(*x, label_button.top), fill))
+        .expect("顶部行应至少有一个填充像素");
+    let top_inset = top_row_left - label_button.left;
+    assert!(
+        (11..=17).contains(&top_inset),
+        "药丸圆角应 = 20（12b 1.2）：顶部行左内缩应 ≈14，实测 {top_inset}（8 圆角 ≈4，直角 0）"
+    );
+
+    // ---- 12b 1.4：带前置图标的左内边距 = 16（用 Filled 格量，避开圆角只扫中间带）----
+    // 判「墨迹」的方式：比容器色更接近 OnPrimary。不要用字面量白——浅色页面底色 (246,250,255)
+    // 与白在容差内，会把圆角外的底色当成墨迹（首次实现就踩了，量出 3）。
+    let on_primary = rgb(ui.color(Role::OnPrimary));
+    let mut left_ink: Option<usize> = None;
+    for y in (label_button.top + 12)..=(label_button.bottom - 12) {
+        for x in (label_button.left + 4)..=label_button.right {
+            if nearer(shot.at(x, y), on_primary, fill) {
+                left_ink = Some(left_ink.map_or(x, |best: usize| best.min(x)));
+            }
+        }
+    }
+    let icon_pad = left_ink.expect("Filled 格应带前置图标（量内边距用）") - label_button.left;
+    // 图标盒左缘 = 16；字形在 24 viewBox 里自带 ≈5.3 左边距 ⇒ 墨迹落在 21 附近
+    // （16 → 21；24 → 29；8 → 13，三档互不重叠）
+    assert!(
+        (18..=24).contains(&icon_pad),
+        "12b 1.4：带图标左内边距应 16（墨迹 ≈21），实测 {icon_pad}"
+    );
+
+    // ---- Q9：IconButton 的字形不许撑满 40 盒 -----------------------------------
+    let tonal = rgb(ui.color(Role::SecondaryContainer));
+    let tonal_boxes = shot.bbox_of(tonal);
+    let icon_states = tonal_boxes
+        .iter()
+        .filter(|bbox| (39..=41).contains(&bbox.width()) && (39..=41).contains(&bbox.height()))
+        .count();
+    // 只有 **enabled** 列是精确的 SecondaryContainer（hover/pressed/focus 列叠了状态层，颜色不同），
+    // 所以这里只要求 ≥1：量几何一只就够，五态的可见性由图本身给。
+    assert!(
+        icon_states >= 1,
+        "tonal IconButton 至少 1 个（实际 {icon_states}）"
+    );
+
+    let gear = rgb(ui.color(Role::OnSecondaryContainer));
+    let mut measured_glyph = false;
+    let mut glyph_width = 0;
+    for bbox in tonal_boxes
+        .iter()
+        .filter(|bbox| (39..=41).contains(&bbox.width()))
+    {
+        if let Some(ink) = shot.ink_inside(bbox, gear) {
+            let width = ink.width();
+            if width > glyph_width {
+                glyph_width = width;
+            }
+            assert!(
+                (16..=26).contains(&width),
+                "图标盒 24 的字形墨迹应 16~26 宽，实测 {width}（Q9 回归时会接近 40）"
+            );
+            measured_glyph = true;
+        }
+    }
+    assert!(measured_glyph, "没量到 IconButton 的字形");
+
+    // ---- 22.1：分隔线 1px（按「非底色的长横线」判，不按精确色：线被抗锯齿摊到两行）----
+    let surface = rgb(ui.color(Role::Surface));
+    let mut runs = 0;
+    for y in 0..shot.height {
+        let mut longest = 0;
+        let mut current = 0;
+        for x in 0..shot.width {
+            if !matches(shot.at(x, y), surface) {
+                current += 1;
+                longest = longest.max(current);
+            } else {
+                current = 0;
+            }
+        }
+        if longest > 300 {
+            runs += 1;
+        }
+    }
+    // 两条线 × 各摊 1~2 行 ⇒ 2..=4 行
+    assert!(
+        (2..=4).contains(&runs),
+        "分隔线应 2 条（每条 1px，抗锯齿最多摊 2 行）⇒ 2..=4 行，实测 {runs} 行"
+    );
+    // **墨量覆盖率**：一条 1dp 的线，其各行相对底色的不透明覆盖率之和应 ≈1.0。
+    // 1.5dp 的线会到 ≈1.5，2dp 会到 ≈2.0 —— 这是「容忍 1.5 倍粗」的补丁。
+    let full = rgb(ui.color(Role::OutlineVariant));
+    // 屏上正好 2 条线（通栏 + 列表内缩），所以把总墨量除以 2 得到「单条线的覆盖率」
+    let coverage = line_coverage(&shot, surface, full) / 2.0;
+    assert!(
+        (0.8..=1.3).contains(&coverage),
+        "单条分隔线墨量覆盖率应 ≈1.0（= 1dp），实测 {coverage:.2}（1.5dp 会到 ~1.5）"
+    );
+
+    // ---- 12b 1.8 禁用态：容器 + **每一行**的内容色（A1 逐变体不同）----------------
+    //
+    // 上一版把两个 reviewer 都指出的重复块留在这里（`disabled_colors` 被调两次、
+    // `disabled_container` 被绑定两次），且只有一条「全图数墨迹」的护栏 —— 深色下阈值失效、
+    // 单行回退也抓不住。现在按矩阵的行逐条断言。
+    //
+    // **按钮族**：容器 10%（官方 `*ButtonTokens.DisabledContainerOpacity = 0.1f`）、内容 38%。
+    // M86 之前这里和 chip 共用同一个 12% 常量，所以断言与实现「一起错」、永远同源——拆族后才对得上。
+    let (disabled_container, _) = interaction::disabled_button_colors(&ui, Role::Surface);
+    assert!(
+        shot.bbox_of(rgb(disabled_container))
+            .iter()
+            .any(|b| b.width() > 60),
+        "没找到禁用态实心按钮（12b 1.8：容器 = on-surface@10%）"
+    );
+
+    // 矩阵行序（gallery/buttons.rs 的 Variant::ALL + IconVariant::ALL），行距 48 = 40 + 8
+    let row_step = 48usize;
+    let rows: [(usize, Role, bool, &str); 8] = [
+        (0, Role::OnSurfaceVariant, true, "filled"),
+        (1, Role::OnSurface, true, "tonal"), // A1：FilledTonal 是例外
+        (2, Role::OnSurfaceVariant, true, "elevated"),
+        (3, Role::OnSurfaceVariant, false, "outlined"),
+        (4, Role::OnSurfaceVariant, false, "text"),
+        (5, Role::OnSurface, false, "icon·standard"), // A1：IconButton 全是 OnSurface
+        (6, Role::OnSurface, false, "icon·filled"),
+        // 第 7 行（矩阵最后一行的 tonal IconButton）上一版漏了 —— reviewer 把它的禁用墨迹涂回
+        // 满档色时 probe 全绿。A1 同样是 OnSurface（`FilledTonalIconButtonTokens`）。
+        (7, Role::OnSurface, true, "icon·tonal"),
+    ];
+    let column_from = shot.width * 2 / 3; // 矩阵最右列 = disabled 列
+    for (index, role, on_container, name) in rows {
+        let y0 = label_button.top + index * row_step;
+        let y1 = y0 + 44;
+        // **与实现同源**：按钮族的内容色一律走 `disabled_button_content`（38% 叠在 10% 底上）。
+        // 这里若用面状控件族的 `disabled_content_over_role`（12% 底），断言的底就比实现宽一档，
+        // 差的 1/255 会让「容器对了内容错了」这类错逃过门控——M86 明确要防这个。
+        let ink = interaction::disabled_button_content(&ui, role, on_container);
+        let count = shot.count_in(rgb(ink), column_from, shot.width, y0, y1);
+        assert!(
+            count > 40,
+            "{name} 行的禁用内容（{role:?}@38%）在 disabled 列里只有 {count} px ——              说明这一行没走 A1 的禁用角色"
+        );
+    }
+
+    // filled 禁用容器里不许出现满档 OnPrimary（旧实现是白字压在容器上 = 1.23:1）
+    let full_content = rgb(ui.color(Role::OnPrimary));
+    for bbox in shot.bbox_of(rgb(disabled_container)) {
+        if bbox.width() < 60 {
+            continue;
+        }
+        // 只扫**内带**：圆角外的页面底色与 OnPrimary 在容差内，贴边扫描会误报。
+        for y in (bbox.top + 12)..=(bbox.bottom - 12) {
+            for x in (bbox.left + 12)..=(bbox.right - 12) {
+                assert!(
+                    !matches(shot.at(x, y), full_content),
+                    "禁用容器内出现满档 OnPrimary @({x},{y})：禁用标签没降到 38%"
+                );
+            }
+        }
+    }
+
+    eprintln!(
+        "[probe] OK flavor={:?}：
+  Filled 药丸 {}×{}（参考 高 40 / 宽 ≥58）
+  顶行左内缩 {}（r=20 应 ≈14；8 圆角 ≈4；直角 0）
+  实心块 {} 个（含 40×40 IconButton）
+  分隔线长行 {} 行（每条 1px）
+  禁用容器 (on-surface@10%，按钮族) 命中 · 逐行禁用内容断言 {} 行通过
+  分隔线墨量覆盖率 {:.2}（1dp 应 ≈1.0）
+  字形墨迹 {}px（24 盒应 16~26）",
+        flavor,
+        label_button.width(),
+        true_height,
+        top_inset,
+        primary.len(),
+        runs,
+        rows.len(),
+        coverage,
+        glyph_width
+    );
+}
diff --git a/crates/app-iced/src/components/gallery/scan.rs b/crates/app-iced/src/components/gallery/scan.rs
new file mode 100644
index 0000000..b33f933
--- /dev/null
+++ b/crates/app-iced/src/components/gallery/scan.rs
@@ -0,0 +1,183 @@
+//! 截图像素扫描工具（`gallery::probe` 的底层，四个后续家族的 probe 也能复用）。
+//!
+//! 只做「按颜色找连通块 / 量外接框 / 量某行的连续长度」三件事，不含任何判据——
+//! 判据在同级 `probe.rs` 里，这样每条家族线可以自带 probe 而不用重写扫描逻辑。
+
+use std::path::Path;
+
+use iced::Color;
+
+/// 颜色比对的通道容差（抗锯齿/取整）。
+const TOLERANCE: u8 = 10;
+
+/// iced 颜色 → 8bit RGB（截图里的原值）。
+pub(super) fn rgb(color: Color) -> [u8; 3] {
+    [
+        (color.r * 255.0).round() as u8,
+        (color.g * 255.0).round() as u8,
+        (color.b * 255.0).round() as u8,
+    ]
+}
+
+/// 颜色是否落在容差内。
+pub(super) fn matches(pixel: [u8; 3], expected: [u8; 3]) -> bool {
+    pixel
+        .iter()
+        .zip(expected)
+        .all(|(a, b)| a.abs_diff(b) <= TOLERANCE)
+}
+
+/// 一张图的像素访问器。
+pub(super) struct Shot {
+    pub(super) width: usize,
+    pub(super) height: usize,
+    pixels: Vec<[u8; 3]>,
+}
+
+impl Shot {
+    pub(super) fn load(path: &Path) -> Result<Self, String> {
+        let bytes = std::fs::read(path).map_err(|error| format!("读不动 {path:?}：{error}"))?;
+        let image = image::load_from_memory(&bytes)
+            .map_err(|error| format!("解 PNG 失败：{error}"))?
+            .to_rgb8();
+        let (width, height) = (image.width() as usize, image.height() as usize);
+        Ok(Self {
+            width,
+            height,
+            pixels: image.pixels().map(|p| p.0).collect(),
+        })
+    }
+
+    pub(super) fn at(&self, x: usize, y: usize) -> [u8; 3] {
+        self.pixels[y * self.width + x]
+    }
+
+    /// 某种颜色的全部像素的外接框（连通块）。
+    pub(super) fn bbox_of(&self, color: [u8; 3]) -> Vec<BBox> {
+        let mut seen = vec![false; self.width * self.height];
+        let mut boxes = Vec::new();
+
+        for y in 0..self.height {
+            for x in 0..self.width {
+                if seen[y * self.width + x] || !matches(self.at(x, y), color) {
+                    continue;
+                }
+
+                let mut stack = vec![(x, y)];
+                seen[y * self.width + x] = true;
+                let mut bbox = BBox::new(x, y);
+
+                while let Some((cx, cy)) = stack.pop() {
+                    bbox.include(cx, cy);
+                    for (nx, ny) in [
+                        (cx + 1, cy),
+                        (cx.saturating_sub(1), cy),
+                        (cx, cy + 1),
+                        (cx, cy.saturating_sub(1)),
+                    ] {
+                        let inside = nx < self.width && ny < self.height;
+                        if inside && !seen[ny * self.width + nx] && matches(self.at(nx, ny), color)
+                        {
+                            seen[ny * self.width + nx] = true;
+                            stack.push((nx, ny));
+                        }
+                    }
+                }
+
+                if bbox.area() > 200 {
+                    boxes.push(bbox);
+                }
+            }
+        }
+
+        boxes
+    }
+
+    /// 在矩形 `[x0,x1) × [y0,y1)` 内数某颜色的像素（按行/列取证用）。
+    pub(super) fn count_in(
+        &self,
+        color: [u8; 3],
+        x0: usize,
+        x1: usize,
+        y0: usize,
+        y1: usize,
+    ) -> usize {
+        (y0..y1.min(self.height))
+            .map(|y| {
+                (x0..x1.min(self.width))
+                    .filter(|x| matches(self.at(*x, y), color))
+                    .count()
+            })
+            .sum()
+    }
+
+    /// `bbox` 内某颜色的墨迹外接框（量字形用）。
+    ///
+    /// 内缩 3px：不内缩会把按钮自身的抗锯齿边算成墨迹（实测把 24 盒字形量成 40）。
+    pub(super) fn ink_inside(&self, bbox: &BBox, color: [u8; 3]) -> Option<BBox> {
+        const MARGIN: usize = 3;
+        let mut ink: Option<BBox> = None;
+        for y in (bbox.top + MARGIN)..=(bbox.bottom - MARGIN) {
+            for x in (bbox.left + MARGIN)..=(bbox.right - MARGIN) {
+                if matches(self.at(x, y), color) {
+                    match &mut ink {
+                        Some(found) => found.include(x, y),
+                        None => ink = Some(BBox::new(x, y)),
+                    }
+                }
+            }
+        }
+        ink
+    }
+}
+
+/// 一个外接框（闭区间）。
+#[derive(Debug, Clone, Copy)]
+#[allow(clippy::struct_field_names)]
+pub(super) struct BBox {
+    pub(super) left: usize,
+    pub(super) right: usize,
+    pub(super) top: usize,
+    pub(super) bottom: usize,
+}
+
+impl BBox {
+    pub(super) fn new(x: usize, y: usize) -> Self {
+        Self {
+            left: x,
+            right: x,
+            top: y,
+            bottom: y,
+        }
+    }
+
+    pub(super) fn include(&mut self, x: usize, y: usize) {
+        self.left = self.left.min(x);
+        self.right = self.right.max(x);
+        self.top = self.top.min(y);
+        self.bottom = self.bottom.max(y);
+    }
+
+    pub(super) fn width(&self) -> usize {
+        self.right - self.left + 1
+    }
+
+    pub(super) fn height(&self) -> usize {
+        self.bottom - self.top + 1
+    }
+
+    pub(super) fn area(&self) -> usize {
+        self.width() * self.height()
+    }
+}
+
+/// `pixel` 更接近 `fill` 还是 `surface`。
+pub(super) fn nearer(pixel: [u8; 3], fill: [u8; 3], surface: [u8; 3]) -> bool {
+    let dist = |a: [u8; 3], b: [u8; 3]| -> u32 {
+        a.iter()
+            .zip(b)
+            .map(|(x, y)| (i32::from(*x) - i32::from(y)).unsigned_abs())
+            .sum()
+    };
+    dist(pixel, fill) < dist(pixel, surface)
+}
diff --git a/crates/app-iced/src/components/gallery/selection.rs b/crates/app-iced/src/components/gallery/selection.rs
new file mode 100644
index 0000000..2efe01a
--- /dev/null
+++ b/crates/app-iced/src/components/gallery/selection.rs
@@ -0,0 +1,37 @@
+//! gallery 里的选择类小节：把状态矩阵摆进 harness（**断言不在这里**）。
+//!
+//! 矩阵本体的构造在 [`selection::matrix`]（12 行 × 5 列：checkbox 四态 / radio / switch /
+//! chip 三类），消息用 `()`（矩阵只供视觉验收），这里一次 `.map(..)` 接成 `DemoMessage`。
+//!
+//! ## 渲染层几何断言去哪了
+//!
+//! 在 [`crate::app::components::selection::probe`]（`selection/probe.rs`）。挪出去的原因是
+//! 400 行红线（复审 P2-5 同一类问题）：断言 + 像素扫描会把这个文件顶到 458 行。
+//!
+//! 跑法（worktree 根目录）：
+//!
+//! ```text
+//! ULL_GALLERY_SECTION=selection ./target/debug/unlucky-launcher-iced --software-renderer \
+//!   --screen=gallery --screenshot target/m76/selection-light.png --screenshot-theme=light
+//! ULL_GALLERY_SHOT=target/m76/selection-light.png cargo test -p unlucky-app-iced selection::probe
+//! ```
+
+use iced::widget::column;
+use iced::Element;
+
+use super::super::selection;
+use crate::theme::Ui;
+
+use super::DemoMessage;
+
+/// 选择类家族的小节：标题 + 矩阵 + 图例。
+pub(super) fn section<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> {
+    let pressed = |()| DemoMessage::Pressed("selection");
+    column![
+        selection::matrix::heading_and_note(ui).map(pressed),
+        selection::matrix::matrix(ui).map(pressed),
+        selection::matrix::legend(ui).map(pressed),
+    ]
+    .spacing(ui.space(unlucky_design::spacing::Space::X2))
+    .into()
+}
diff --git a/crates/app-iced/src/components/gate.rs b/crates/app-iced/src/components/gate.rs
new file mode 100644
index 0000000..1a023f5
--- /dev/null
+++ b/crates/app-iced/src/components/gate.rs
@@ -0,0 +1,310 @@
+//! 组件目录的自检门禁（`src/components/**`）。
+//!
+//! 为什么要有这份：`tests/no_hardcoded_tokens.rs` 只扫**色值**和 `shell/` 的尺寸字面量，
+//! 组件库目录是后来才开的——如果不管，五条并行线会各自写回 `.width(24.0)` 与
+//! `center_x(Length::Fill)`，M68 那两个形态级错误就会被复制五份。
+//!
+//! 四条判据（每条对应一个已发生过的错误）：
+//!
+//! | 判据 | 抓的是什么 | 历史 |
+//! |---|---|---|
+//! | Q8：禁 `center_x(` / `center_y(` / `.center(` | 容器尺寸被 `Fill` 静默覆盖 | 药丸 56×32 → 88×32 |
+//! | Q9：图标必须经 `layout::fixed` / `centered_fixed` | 字形被 Button 的 Fill 撑满 | 24 的字形渲染成 46px |
+//! | T2：禁尺寸字面量 | 组件里重复定义令牌值 | rubric T2 |
+//! | 400 行 | 单文件上限（AGENTS.md §3-1） | `guards.yml` 的 file-size job |
+//!
+//! 扫描对象是**源码文本**而不是布局结果——这不是偷懒：布局结果要真窗口（CI 无桌面），
+//! 而「把尺寸交给 `center_*`」这个错误 100% 出现在源码形态里（M68 就是这样被抓的）。
+//! 像素级几何另有 `gallery::probe` 对着真截图量。
+
+use std::path::{Path, PathBuf};
+
+/// 单文件行数上限（AGENTS.md §3-1）。
+const MAX_LINES: usize = 400;
+
+fn src_dir() -> PathBuf {
+    PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("src")
+}
+
+fn components_dir() -> PathBuf {
+    PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+        .join("src")
+        .join("components")
+}
+
+fn rust_files(dir: &Path, collected: &mut Vec<PathBuf>) {
+    let entries =
+        std::fs::read_dir(dir).unwrap_or_else(|error| panic!("读不动 {}：{error}", dir.display()));
+
+    for entry in entries {
+        let path = entry.expect("目录项读失败").path();
+        if path.is_dir() {
+            rust_files(&path, collected);
+        } else if path.extension().is_some_and(|ext| ext == "rs") {
+            collected.push(path);
+        }
+    }
+}
+
+/// 全部组件源文件（`mod.rs` 也要扫：它是共享地基，最容易混进字面量）。
+fn sources() -> Vec<(PathBuf, String)> {
+    let mut files = Vec::new();
+    rust_files(&components_dir(), &mut files);
+    files.sort();
+
+    assert!(
+        files.len() >= 15,
+        "只扫到 {} 个组件源文件：扫描逻辑坏了，门禁等于没跑",
+        files.len()
+    );
+
+    files
+        .into_iter()
+        .map(|path| {
+            let text = std::fs::read_to_string(&path)
+                .unwrap_or_else(|error| panic!("读不动 {}：{error}", path.display()));
+            (path, text)
+        })
+        .collect()
+}
+
+/// 去掉 `#[cfg(test)]` 之后的全部内容：测试里写参考值是**应该的**（12b 的 40/24/20
+/// 必须在测试里以字面量出现，否则测不出偏离）。
+fn product_part(text: &str) -> &str {
+    match text.find("#[cfg(test)]") {
+        Some(at) => &text[..at],
+        None => text,
+    }
+}
+
+/// 代码行（跳过注释行：文档里写 `.center_x(` 是在解释坑，不该判违规）。
+fn code_lines(text: &str) -> impl Iterator<Item = (usize, &str)> {
+    text.lines().enumerate().filter_map(|(index, line)| {
+        let trimmed = line.trim_start();
+        if trimmed.starts_with("//") {
+            None
+        } else {
+            Some((index + 1, line))
+        }
+    })
+}
+
+#[test]
+fn q8_no_center_shortcuts_that_swallow_fixed_sizes() {
+    let mut offenders = Vec::new();
+
+    for (path, text) in sources() {
+        for (line_no, line) in code_lines(product_part(&text)) {
+            for pattern in ["center_x(", "center_y(", ".center("] {
+                if line.contains(pattern) {
+                    offenders.push(format!(
+                        "{}:{line_no} {line}\n    → {pattern} 会把容器尺寸改成 Fill（Q8），\
+                         居中请用父级 align_x 或 layout::centered_fixed",
+                        path.display()
+                    ));
+                }
+            }
+        }
+    }
+
+    assert!(offenders.is_empty(), "Q8 违规：\n{}", offenders.join("\n"));
+}
+
+#[test]
+fn q9_icons_never_reach_a_button_unwrapped() {
+    let mut offenders = Vec::new();
+
+    for (path, text) in sources() {
+        let product = product_part(&text);
+        // 允许两种写法：同一行里已经包在 layout:: 里；或它是 `layout::fixed(` 多行调用的实参
+        // （图标常作为第 3 个参数出现在后两行，所以往回看 4 行）。
+        let mut window: Vec<&str> = Vec::new();
+        for (line_no, line) in code_lines(product) {
+            if line.contains("icons::view") {
+                let wrapped =
+                    line.contains("layout::fixed") || line.contains("layout::centered_fixed");
+                let continued = window.iter().rev().any(|prev| {
+                    prev.contains("layout::fixed") || prev.contains("layout::centered_fixed")
+                });
+                if !wrapped && !continued {
+                    offenders.push(format!(
+                        "{}:{line_no} {line}\n    → 图标必须经 layout::fixed / centered_fixed 包一层（Q9）",
+                        path.display()
+                    ));
+                }
+            }
+            if !line.trim().is_empty() {
+                window.push(line);
+                if window.len() > 4 {
+                    window.remove(0);
+                }
+            }
+        }
+    }
+
+    assert!(offenders.is_empty(), "Q9 违规：\n{}", offenders.join("\n"));
+}
+
+/// 布局调用后面直接跟数字 → 判违规（`0` 与 `0.0` 放行：0 = 无内边距/无描边）。
+fn size_literal(argument: &str) -> Option<String> {
+    let mut rest = argument.trim_start();
+    for wrapper in ["Length::Fixed(", "Padding::from(", "Size::new("] {
+        if let Some(after) = rest.strip_prefix(wrapper) {
+            rest = after.trim_start().trim_start_matches(['[', '(']);
+            break;
+        }
+    }
+
+    let number: String = rest
+        .trim_start()
+        .chars()
+        .take_while(|ch| ch.is_ascii_digit() || *ch == '.')
+        .collect();
+
+    if number.is_empty() || number.trim_end_matches('.').parse::<f64>() == Ok(0.0) {
+        return None;
+    }
+    Some(number)
+}
+
+#[test]
+fn t2_no_size_literals_in_components() {
+    let mut offenders = Vec::new();
+
+    for (path, text) in sources() {
+        for (line_no, line) in code_lines(product_part(&text)) {
+            for pattern in [".width(", ".height(", ".size(", ".spacing(", ".padding("] {
+                let mut from = 0;
+                while let Some(found) = line[from..].find(pattern) {
+                    let after = from + found + pattern.len();
+                    if let Some(number) = size_literal(&line[after..]) {
+                        offenders.push(format!(
+                            "{}:{line_no} {line} -> {pattern} 后面写了数字 {number}",
+                            path.display()
+                        ));
+                    }
+                    from = after;
+                }
+            }
+        }
+    }
+
+    assert!(
+        offenders.is_empty(),
+        "组件里不许有尺寸字面量（走 LayoutMetrics / Space / ComponentMetrics）：\n{}",
+        offenders.join("\n")
+    );
+}
+
+/// 单文件 ≤400 行：**扫整个 `src/`**，不只 components。
+///
+/// M90 r2（P1-2）的教训：这条守门原来只遍历 `components/`，于是 `pages/harness.rs` 悄悄长到
+/// 402 行没人拦，直到 `guards.yml` 的 file-size job 在 CI 上判红才发现。`guards.yml` 的口径是
+/// **全仓**（`git ls-files '*.rs' '*.md' …`），这里至少把本 crate 的 `src/**` 对齐：
+/// 谁在 `app/` / `pages/` / `shell/` 把文件推过线，`cargo test` 就先红，不用等 CI。
+#[test]
+fn every_source_file_stays_under_the_line_limit() {
+    let mut files = Vec::new();
+    rust_files(&src_dir(), &mut files);
+    assert!(
+        files.len() >= 40,
+        "src/ 至少 40 个 .rs，实际 {}：扫描逻辑坏了，这条门禁等于没跑",
+        files.len()
+    );
+
+    let mut offenders = Vec::new();
+    for path in files {
+        let text = std::fs::read_to_string(&path).expect("读源文件");
+        let lines = text.lines().count();
+        if lines > MAX_LINES {
+            offenders.push(format!(
+                "{}: {lines} 行（上限 {MAX_LINES}）",
+                path.display()
+            ));
+        }
+    }
+    assert!(
+        offenders.is_empty(),
+        "单文件 ≤400 行（AGENTS.md §3-1，guards.yml 按全仓判红）：\n{}",
+        offenders.join("\n")
+    );
+}
+
+/// 四个家族目录必须存在且结构完整。
+///
+/// **这里刻意不再限制「pub fn 有几个」**：M76 往 `selection/` 里加 Checkbox/Radio 是它的本职工作，
+/// 而家族线被明确要求不许改 `gate.rs`——把「桩还在不在」写成 pub fn 计数，等于给 M76 埋一个
+/// 它无权拆的地雷（reviewer P1-C）。越界与否由 merge gate 的 scope 判定（各家族目录只归对应
+/// mission），门禁只管「地基还在」：
+///
+/// - 四个家族目录各有 `mod.rs`；
+/// - `components/mod.rs` 仍声明这五个家族 + gallery（谁把声明删了，这里先红）。
+#[test]
+fn the_five_families_are_declared_and_present() {
+    let declared =
+        std::fs::read_to_string(components_dir().join("mod.rs")).expect("读 components/mod.rs");
+
+    for family in ["selection", "inputs", "feedback", "navigation"] {
+        let dir = components_dir().join(family);
+        let file = dir.join("mod.rs");
+        assert!(file.is_file(), "家族目录 {} 缺 mod.rs", dir.display());
+        assert!(
+            declared.contains(&format!("pub mod {family};")),
+            "components/mod.rs 少了 `pub mod {family};` 声明"
+        );
+    }
+    assert!(
+        declared.contains("pub mod gallery;") && declared.contains("pub mod buttons;"),
+        "components/mod.rs 的声明被动了"
+    );
+}
+
+/// gallery 的五个家族文件必须都在（`mod.rs` 声明了它们，缺一个就编译不过——
+/// 这条在并行线删文件/改名时给出人话，而不是一堆 `unresolved module`）。
+#[test]
+fn gallery_keeps_one_file_per_family() {
+    for family in ["buttons", "selection", "inputs", "feedback", "navigation"] {
+        let path = components_dir()
+            .join("gallery")
+            .join(format!("{family}.rs"));
+        assert!(
+            path.is_file(),
+            "gallery 缺 {}（本文件结构是并行地基）",
+            path.display()
+        );
+
+        let text = std::fs::read_to_string(&path).expect("读 gallery 家族文件");
+        assert!(
+            text.contains("fn section"),
+            "{} 必须提供 section()（gallery/mod.rs 调它）",
+            path.display()
+        );
+    }
+}
+
+/// 门禁自身不能空转：造几个违规样本喂给判据。
+#[test]
+fn the_gate_catches_planted_violations() {
+    assert_eq!(
+        size_literal("Length::Fixed(40.0))").as_deref(),
+        Some("40.0")
+    );
+    assert_eq!(size_literal("0)").as_deref(), None);
+    assert_eq!(
+        size_literal("ui.metrics().control_height)").as_deref(),
+        None
+    );
+    assert!(product_part("a\n#[cfg(test)]\n.width(40.0)\n")
+        .find(".width(40.0)")
+        .is_none());
+    assert!(product_part("a\n.width(40.0)\n")
+        .find(".width(40.0)")
+        .is_some());
+    // Q8 判据本身
+    for code in ["x.center_x(Length::Fill)", "x.center(Length::Fill)"] {
+        assert!(
+            code.contains("center_x(") || code.contains(".center("),
+            "判据写坏了"
+        );
+    }
+}
diff --git a/crates/app-iced/src/components/inputs/field.rs b/crates/app-iced/src/components/inputs/field.rs
new file mode 100644
index 0000000..32a0bad
--- /dev/null
+++ b/crates/app-iced/src/components/inputs/field.rs
@@ -0,0 +1,398 @@
+//! 文本框（`research/12b` §9）：Filled / Outlined 两式，**受控组件**。
+//!
+//! ## 参考值（`[源]` = A1，本机 `material3-android:1.4.0` 的 `*TextFieldTokens` + `TextFieldDefaults`）
+//!
+//! | # | 检查项 | 参考值 | 落点 |
+//! |---|---|---|---|
+//! | 9.1 | 高度 | min **56**（带标签）；无标签单行本项目 **40** | `FIELD_HEIGHT`（G16）/ `LM.control_height` |
+//! | 9.2 | 最小宽 | **280** → **G21 未施加**（iced 的 `Length` 无 min-width，同按钮 G15） | 文档 |
+//! | 9.3 | 形状 | Outlined **4**；Filled 顶圆角 4、底直角 | `Component::TextField.spec().shape` |
+//! | 9.4 | 描边 / 指示线 | Outlined 静息 1dp `Outline` → hover 1dp `OnSurface` → 聚焦 **2dp `Primary`**；Filled 底指示线静息 `OnSurfaceVariant` | [`Filled`] / [`Palette`] |
+//! | 9.5 | 字级 | 输入/标签 `BodyLarge 16/24`；辅助/错误 `BodySmall 12/16` | `TypeRole` |
+//! | 9.6 | 图标 | 前后 **24**、`OnSurfaceVariant`；图标可视边 **12**、文本从 **48** 起 | `FieldGeometry` |
+//! | 9.7 | 错误态 | 线/标签/辅助文本全 **`Error`**、线宽 **2dp** | [`Field::error`] |
+//! | 9.8 | 禁用态 | Filled 容器 `OnSurface`@**4%**（→ 令牌只有 12%，**登记偏离 D10**）；Outlined 描边 `OnSurface`@**12%**；内容 @**38%** | `interaction::*` |
+//!
+//! ## 三处口径说明
+//!
+//! 1. **状态差异落在指示线/描边/标签上，容器底色不叠状态层**（A1 的口径，与按钮家族的 8%/10% 状态层不同）；press 无独立 token，按 hover 处理（D11）。
+//! 2. 标签是「**常浮起**」的两段式（占上面 16px，不做上浮动画，登记 D12）；缺省宽度 `Fill`（最小宽 280 无法在 iced 表达，G21）。
+
+use iced::widget::text::LineHeight;
+use iced::widget::{column, container, row, text, text_input};
+use iced::{Alignment, Background, Border, Color, Element, Length, Padding, Pixels};
+
+use unlucky_design::color::Role;
+use unlucky_design::icons::IconKind;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use crate::icons;
+use crate::theme::Ui;
+
+use super::super::interaction::{self, Interaction};
+use super::super::layout;
+use super::geometry::FieldGeometry;
+
+/// 两式容器（12b 9.3 / 9.4 的差别：Filled 有容器色 + 底部指示线；Outlined 只有描边）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum FieldVariant {
+    /// 实心：`SurfaceContainerHighest` + 底部指示线，顶圆角 4 底直角。
+    Filled,
+    /// 描边：透明容器 + 1dp `Outline`，四角 4。
+    Outlined,
+}
+
+impl FieldVariant {
+    /// 两式全序（gallery 的行序）。
+    pub const ALL: [FieldVariant; 2] = [FieldVariant::Filled, FieldVariant::Outlined];
+
+    /// 稳定名字（图例 / 测试信息）。
+    pub const fn name(self) -> &'static str {
+        match self {
+            FieldVariant::Filled => "filled",
+            FieldVariant::Outlined => "outlined",
+        }
+    }
+}
+
+/// 一个文本框的装配描述（不持有 `String`：受控组件只借值，契约 §2）。
+#[derive(Debug, Clone)]
+pub struct Field<'a> {
+    variant: FieldVariant,
+    value: &'a str,
+    label: Option<&'a str>,
+    placeholder: &'a str,
+    supporting: Option<&'a str>,
+    leading: Option<IconKind>,
+    trailing: Option<IconKind>,
+    error: bool,
+    state: Option<Interaction>,
+    width: Length,
+    secure: bool,
+}
+
+impl<'a> Field<'a> {
+    /// 一个 Filled 文本框。
+    pub fn new(value: &'a str) -> Self {
+        Self {
+            variant: FieldVariant::Filled,
+            value,
+            label: None,
+            placeholder: "",
+            supporting: None,
+            leading: None,
+            trailing: None,
+            error: false,
+            state: None,
+            width: Length::Fill,
+            secure: false,
+        }
+    }
+
+    /// 选式（Filled / Outlined）。
+    pub fn variant(mut self, variant: FieldVariant) -> Self {
+        self.variant = variant;
+        self
+    }
+
+    /// 浮动标签（`BodySmall`，常浮起，见模块文档第 2 条）。
+    pub fn label(mut self, label: &'a str) -> Self {
+        self.label = Some(label);
+        self
+    }
+
+    /// 占位文案（只在值为空时可见，`OnSurfaceVariant`）。
+    pub fn placeholder(mut self, placeholder: &'a str) -> Self {
+        self.placeholder = placeholder;
+        self
+    }
+
+    /// 辅助/错误说明（字段下方 `BodySmall`）。
+    pub fn supporting(mut self, supporting: &'a str) -> Self {
+        self.supporting = Some(supporting);
+        self
+    }
+
+    /// 前置图标（24，图标可视边 12）。
+    pub fn leading(mut self, kind: IconKind) -> Self {
+        self.leading = Some(kind);
+        self
+    }
+
+    /// 后置图标（24，右侧内边距 16）。
+    pub fn trailing(mut self, kind: IconKind) -> Self {
+        self.trailing = Some(kind);
+        self
+    }
+
+    /// 错误态：线 / 标签 / 辅助文本转 `Error`，线宽 2dp（9.7）。
+    pub fn error(mut self) -> Self {
+        self.error = true;
+        self
+    }
+
+    /// 强制视觉态（gallery 状态矩阵取证；运行期不要调）。
+    pub fn state(mut self, state: Interaction) -> Self {
+        self.state = Some(state);
+        self
+    }
+
+    /// 定宽（默认 `Fill`；gallery 的矩阵格用它钉宽度）。
+    pub fn width(mut self, width: Length) -> Self {
+        self.width = width;
+        self
+    }
+
+    /// 密码式输入（M114）：上屏是掩码（明文上屏＝UI 侧凭据泄漏）。
+    pub fn secure(mut self, secure: bool) -> Self {
+        self.secure = secure;
+        self
+    }
+}
+
+/// 一个字段在某一态下的全套颜色（9.4 / 9.7 / 9.8 的落点）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+struct Palette {
+    /// 容器底色；`None` = 透明（Outlined）。
+    fill: Option<Color>,
+    /// 描边/指示线色。
+    line: Color,
+    /// 描边/指示线宽（1 或 2）。
+    stroke: f32,
+    /// 标签（`BodySmall`）。
+    label: Color,
+    /// 输入文本。
+    input: Color,
+    /// 前后图标。
+    icon: Color,
+    /// 辅助文本。
+    supporting: Color,
+    /// 占位文本。
+    placeholder: Color,
+}
+
+/// 解析某一态的颜色（**唯一**做角色映射的地方）。
+fn palette(ui: &Ui, variant: FieldVariant, state: Interaction, error: bool) -> Palette {
+    let geometry = FieldGeometry::of(ui, true, None);
+
+    if state.is_disabled() {
+        // 9.8：内容一律 OnSurface@38%；Filled 容器叠 12%（官方 4%，令牌无 4% 档 → D10）；
+        // Outlined 描边正好是官方 12%。
+        let container = interaction::disabled_colors(ui, Role::Surface).0;
+        let ink = interaction::disabled_content_over_role(
+            ui,
+            Role::OnSurface,
+            matches!(variant, FieldVariant::Filled),
+        );
+        return Palette {
+            fill: match variant {
+                FieldVariant::Filled => Some(container),
+                FieldVariant::Outlined => None,
+            },
+            line: match variant {
+                FieldVariant::Filled => ink,
+                FieldVariant::Outlined => container,
+            },
+            stroke: geometry.stroke,
+            label: ink,
+            input: ink,
+            icon: ink,
+            supporting: ink,
+            placeholder: ink,
+        };
+    }
+
+    let focused = matches!(state, Interaction::Focused);
+    let hovered = matches!(state, Interaction::Hovered | Interaction::Pressed);
+
+    let (line, stroke) = if error {
+        (ui.color(Role::Error), geometry.focus_stroke)
+    } else if focused {
+        (ui.color(Role::Primary), geometry.focus_stroke)
+    } else if hovered {
+        (ui.color(Role::OnSurface), geometry.stroke)
+    } else {
+        (
+            match variant {
+                FieldVariant::Filled => ui.color(Role::OnSurfaceVariant),
+                FieldVariant::Outlined => ui.color(Role::Outline),
+            },
+            geometry.stroke,
+        )
+    };
+
+    Palette {
+        fill: match variant {
+            FieldVariant::Filled => Some(ui.color(Role::SurfaceContainerHighest)),
+            FieldVariant::Outlined => None,
+        },
+        line,
+        stroke,
+        label: if error {
+            ui.color(Role::Error)
+        } else if focused {
+            ui.color(Role::Primary)
+        } else {
+            ui.color(Role::OnSurfaceVariant)
+        },
+        input: ui.color(Role::OnSurface),
+        icon: if error {
+            ui.color(Role::Error)
+        } else {
+            ui.color(Role::OnSurfaceVariant)
+        },
+        supporting: if error {
+            ui.color(Role::Error)
+        } else {
+            ui.color(Role::OnSurfaceVariant)
+        },
+        placeholder: ui.color(Role::OnSurfaceVariant),
+    }
+}
+
+/// 一个文本框（Filled / Outlined 由 [`Field::variant`] 选）。
+///
+/// 受控：值由外部持有，输入经 `on_input` 回传；`state` 强制成 `Disabled` 时输入被摘掉
+/// （`on_input_maybe(None)`），所以禁用字段真的点不动，不只是变灰。
+pub fn text_field<'a, M: Clone + 'a>(
+    ui: &'a Ui,
+    field: Field<'a>,
+    on_input: impl Fn(String) -> M + 'a,
+) -> Element<'a, M> {
+    let geometry = FieldGeometry::of(ui, field.label.is_some(), field.leading);
+    let state = field.state.unwrap_or(Interaction::Enabled);
+    let colors = palette(ui, field.variant, state, field.error);
+
+    let input_style = ui.style(TypeRole::BodyLarge);
+    let label_style = ui.style(TypeRole::BodySmall);
+
+    let text_input = text_input(field.placeholder, field.value)
+        .on_input_maybe(if state.is_disabled() {
+            None
+        } else {
+            Some(on_input)
+        })
+        .secure(field.secure)
+        .size(input_style.size_px)
+        .line_height(LineHeight::Absolute(Pixels(input_style.line_height_px)))
+        .font(ui.font_of(input_style))
+        .padding(Padding::default())
+        .width(Length::Fill)
+        .style(move |_theme, _status| text_input::Style {
+            background: Background::Color(Color::TRANSPARENT),
+            border: Border::default(),
+            icon: colors.icon,
+            placeholder: colors.placeholder,
+            value: colors.input,
+            selection: colors.line,
+        });
+
+    let mut content = row![].align_y(Alignment::Center).spacing(geometry.icon_gap);
+    if let Some(kind) = field.leading {
+        // Q9：图标必须经固定尺寸容器，否则会被 Fill 约束撑满（M68 的 46px 字形）
+        content = content.push(layout::fixed(
+            geometry.icon,
+            geometry.icon,
+            icons::view::<M>(kind, colors.icon),
+        ));
+    }
+    content = content.push(text_input);
+    if let Some(kind) = field.trailing {
+        content = content.push(layout::fixed(
+            geometry.icon,
+            geometry.icon,
+            icons::view::<M>(kind, colors.icon),
+        ));
+    }
+
+    let label = field.label.map(|label| {
+        text(label)
+            .size(label_style.size_px)
+            .line_height(LineHeight::Absolute(Pixels(label_style.line_height_px)))
+            .font(ui.font_of(label_style))
+            .color(colors.label)
+    });
+
+    // 内容块：带标签 = [标签 16 + 输入 24] 共 40，居中在内容区里；无标签 = 单行 24 居中。
+    // **垂直居中交给容器**（Q8 的教训：不要指望子元素自己贴边）。
+    let inner: Element<'a, M> = match label {
+        Some(label) => column![label, content].width(Length::Fill).into(),
+        None => content.into(),
+    };
+    let content_area = container(inner)
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .align_y(Alignment::Center)
+        .padding(Padding {
+            top: 0.0,
+            right: geometry.padding.right,
+            bottom: 0.0,
+            left: geometry.padding.left,
+        });
+
+    // Filled：容器色 + **底部指示线**（静息 1dp / 聚焦与错误 2dp）；Outlined：透明 + 描边。
+    // 指示线占容器底边那 1~2px（内容区因此少 1~2px，官方也是画在 padding-box 底边上的）。
+    let body: Element<'a, M> = match field.variant {
+        FieldVariant::Filled => {
+            let indicator = container(iced::widget::space::horizontal())
+                .width(Length::Fill)
+                .height(Length::Fixed(colors.stroke))
+                .style(move |_theme| container::Style {
+                    background: Some(Background::Color(colors.line)),
+                    ..container::Style::default()
+                });
+            column![content_area, indicator].into()
+        }
+        FieldVariant::Outlined => content_area.into(),
+    };
+
+    let border = Border {
+        color: if matches!(field.variant, FieldVariant::Outlined) {
+            colors.line
+        } else {
+            Color::TRANSPARENT
+        },
+        width: if matches!(field.variant, FieldVariant::Outlined) {
+            colors.stroke
+        } else {
+            0.0
+        },
+        // Filled 是「顶圆角 4、底直角」= CornerExtraSmallTop；ShapeScale 没有「部分角」，
+        // 这里按官方语义手工指定上下角（登记 D13）。
+        radius: match field.variant {
+            FieldVariant::Filled => iced::border::Radius {
+                top_left: ui.radius_dp(geometry.shape).top_left,
+                top_right: ui.radius_dp(geometry.shape).top_right,
+                bottom_left: 0.0,
+                bottom_right: 0.0,
+            },
+            FieldVariant::Outlined => ui.radius_dp(geometry.shape),
+        },
+    };
+
+    let field_el: Element<'a, M> = container(body)
+        .width(field.width)
+        .height(Length::Fixed(geometry.height))
+        .style(move |_theme| container::Style {
+            background: colors.fill.map(Background::Color),
+            border,
+            ..container::Style::default()
+        })
+        .into();
+
+    match field.supporting {
+        Some(supporting) => {
+            let note = text(supporting)
+                .size(label_style.size_px)
+                .line_height(LineHeight::Absolute(Pixels(label_style.line_height_px)))
+                .font(ui.font_of(label_style))
+                .color(colors.supporting);
+            column![field_el, layout::inset(0.0, ui.space(Space::X1), note)].into()
+        }
+        None => field_el,
+    }
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/app-iced/src/components/inputs/field/tests.rs b/crates/app-iced/src/components/inputs/field/tests.rs
new file mode 100644
index 0000000..f24e9ff
--- /dev/null
+++ b/crates/app-iced/src/components/inputs/field/tests.rs
@@ -0,0 +1,115 @@
+//! field 的单测（从 `field.rs` 拆出：单文件 ≤400 行，AGENTS.md §3-1）。
+
+use super::*;
+use unlucky_design::color::SchemeFlavor;
+use unlucky_design::typography::Platform;
+
+use crate::theme::Families;
+
+const FAMILIES: Families = Families {
+    text: "Segoe UI",
+    display: "Segoe UI",
+    mono: "Consolas",
+};
+
+fn ui(flavor: SchemeFlavor) -> Ui {
+    Ui::with_platform(flavor, Platform::Windows, FAMILIES)
+}
+
+fn build(field: Field<'_>, flavor: SchemeFlavor) -> Element<'_, u8> {
+    let ui = Box::leak(Box::new(ui(flavor)));
+    text_field(ui, field, |_| 0_u8)
+}
+
+#[test]
+fn every_variant_and_state_builds() {
+    for variant in FieldVariant::ALL {
+        for state in Interaction::ALL {
+            for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+                let field = Field::new("实例一")
+                    .variant(variant)
+                    .label("名称")
+                    .placeholder("请输入")
+                    .supporting("辅助说明")
+                    .leading(IconKind::Folder)
+                    .trailing(IconKind::Close)
+                    .state(state);
+                let _: Element<'_, u8> = build(field, flavor);
+            }
+        }
+    }
+}
+
+/// 9.4：聚焦 2dp `Primary`、hover 1dp `OnSurface`、静息 Outlined 1dp `Outline`（Filled 用 OnSurfaceVariant）。
+#[test]
+fn outline_colors_and_widths_follow_the_state() {
+    let ui = ui(SchemeFlavor::Light);
+    let rest = palette(&ui, FieldVariant::Outlined, Interaction::Enabled, false);
+    assert_eq!(rest.line, ui.color(Role::Outline));
+    assert_eq!(rest.stroke, 1.0);
+    assert_eq!(rest.fill, None, "Outlined 无容器色");
+
+    let hover = palette(&ui, FieldVariant::Outlined, Interaction::Hovered, false);
+    assert_eq!(hover.line, ui.color(Role::OnSurface));
+    assert_eq!(hover.stroke, 1.0);
+
+    let focus = palette(&ui, FieldVariant::Outlined, Interaction::Focused, false);
+    assert_eq!(focus.line, ui.color(Role::Primary));
+    assert_eq!(focus.stroke, 2.0, "FocusOutlineWidth = 2dp");
+    assert_eq!(focus.label, ui.color(Role::Primary), "FocusLabelColor");
+
+    // A1 没有 Pressed token：按 hover 处理（D11），不是漏做
+    assert_eq!(
+        palette(&ui, FieldVariant::Outlined, Interaction::Pressed, false),
+        hover
+    );
+}
+
+/// 9.7：错误态线/标签/辅助全 `Error`，线宽 2dp；错误优先于聚焦。
+#[test]
+fn error_beats_focus_and_paints_everything_error() {
+    let ui = ui(SchemeFlavor::Light);
+    let error = palette(&ui, FieldVariant::Outlined, Interaction::Focused, true);
+    assert_eq!(error.line, ui.color(Role::Error));
+    assert_eq!(error.label, ui.color(Role::Error));
+    assert_eq!(error.supporting, ui.color(Role::Error));
+    assert_eq!(error.stroke, 2.0, "错误线宽 2dp");
+    assert_eq!(error.input, ui.color(Role::OnSurface), "ErrorInputColor");
+}
+
+/// 9.8：禁用内容 38%、Outlined 描边 12%、Filled 容器 12%（官方 4%，令牌缺口 → D10）。
+#[test]
+fn disabled_uses_the_token_alphas() {
+    for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+        let ui = ui(flavor);
+        let container = interaction::disabled_colors(&ui, Role::Surface).0;
+
+        let filled = palette(&ui, FieldVariant::Filled, Interaction::Disabled, false);
+        assert_eq!(filled.fill, Some(container));
+        assert_eq!(
+            filled.input,
+            interaction::disabled_content_over_role(&ui, Role::OnSurface, true)
+        );
+
+        let outlined = palette(&ui, FieldVariant::Outlined, Interaction::Disabled, false);
+        assert_eq!(outlined.fill, None);
+        assert_eq!(outlined.line, container, "DisabledOutlineOpacity = 0.12");
+        assert_eq!(
+            outlined.input,
+            interaction::disabled_content_over_role(&ui, Role::OnSurface, false)
+        );
+        assert_ne!(outlined.input, ui.color(Role::OnSurface), "禁用不许满档");
+    }
+}
+
+/// Filled 有容器色、Outlined 没有；两者圆角都取 `Component::TextField`（4）。
+#[test]
+fn filled_carries_the_container_role() {
+    let ui = ui(SchemeFlavor::Light);
+    assert_eq!(
+        palette(&ui, FieldVariant::Filled, Interaction::Enabled, false).fill,
+        Some(ui.color(Role::SurfaceContainerHighest)),
+        "FilledTextFieldTokens.ContainerColor"
+    );
+    assert_eq!(FieldGeometry::of(&ui, true, None).shape.dp(), 4.0);
+}
diff --git a/crates/app-iced/src/components/inputs/geometry.rs b/crates/app-iced/src/components/inputs/geometry.rs
new file mode 100644
index 0000000..fc7995d
--- /dev/null
+++ b/crates/app-iced/src/components/inputs/geometry.rs
@@ -0,0 +1,309 @@
+//! 输入类家族的**内部几何**：能取令牌的一律取令牌，取不到的登记 G 编号后集中在这里。
+//!
+//! ## 为什么这个文件存在
+//!
+//! `components::gate` 的 `t2_no_size_literals_in_components` 扫 `.width(40.0)` 这类**调用点字面量**；
+//! 但「TextField 高 56」这种 A 级参考值在 `LayoutMetrics` / `ComponentMetrics` 里确实没有落点
+//! （令牌层是另一条 mission 的 scope，不许我改）。所以按契约 §6.2：**登记 G 编号 + 只在这个文件里
+//! 定义一次**，组件实现一个数字都不写。
+//!
+//! ## 参考值表（`[源]` = A1，本机 `material3-android:1.4.0` 的 token 源码；`[估]` = 团队口径）
+//!
+//! | G | 名称 | 参考值 | 出处 | 本文件落点 |
+//! |---|---|---|---|---|
+//! | G16 | TextField 可见高（带标签） | **56** | `TextFieldDefaults.MinHeight` / `OutlinedTextFieldTokens.ContainerHeight` | [`FIELD_HEIGHT`] |
+//! | G17 | 聚焦/错误描边 | **2** | `OutlinedTextFieldTokens.FocusOutlineWidth`、`FilledTextFieldTokens.FocusActiveIndicatorHeight` | [`FOCUS_STROKE`] |
+//! | G18 | Slider 轨道 / 竖条 / 停靠点 | **16 / 4×44 / 4** | `SliderTokens.ActiveTrackHeight` / `HandleWidth`+`HandleHeight` / `StopIndicatorSize` | [`TRACK_HEIGHT`] 等 |
+//! | G19 | 菜单项高 | **48** | `Menu.kt:524 MenuListItemContainerHeight` | [`MENU_ITEM_HEIGHT`] |
+//! | G20 | Search 宽高 | **min 360 / max 720 / 面板最小 240** | `SearchBar.kt:2712-2713`、`DockedExpandedTableMinHeight` | [`SEARCH_MIN_WIDTH`] 等 |
+//!
+//! **已经能取令牌、不许在这里重复定义的**（同一数值只许一份，见 `ComponentMetrics` 模块文档）：
+//! 搜索条高 56 = `LayoutMetrics::search_bar_height`；无标签单行 40 = `LayoutMetrics::control_height`；
+//! 命中区 48 = `LayoutMetrics::touch_target`；水平/上下内边距与图标间距 = `Space::{X2,X3,X4}`；
+//! 图标 24 = `IconSize::Toolbar`；圆角 = `ComponentSpec::shape`（TextField/Menu = 4，Search = Full，
+//! SearchView = ExtraLarge 28）；一像素线 = `stroke::HAIRLINE`。
+//!
+//! ## 与文档的两处口径冲突（按「代码优先」处理，报告里有偏离登记）
+//!
+//! 1. `12b §8.1` 说菜单圆角「本项目 12（偏离官方 4）」；令牌表 `Component::Menu.spec().shape`
+//!    是 `ExtraSmall`（**4**）。令牌层是 M69 定案的真源，本实现取 **4**，不取 12。
+//! 2. `12b §9.1` 说「无标签单行 40」是登记偏离——40 正好是 `LM.control_height`，
+//!    所以那条偏离在实现上是「用骨架令牌」而不是「用字面量」。
+
+use iced::Padding;
+
+use unlucky_design::component_map::Component;
+use unlucky_design::icons::{IconKind, IconSize};
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::Space;
+
+use crate::theme::{Ui, STROKE_PX};
+
+/// G16：文本字段可见高（带浮动标签）。
+pub const FIELD_HEIGHT: f32 = 56.0;
+
+/// G17：聚焦/错误态的描边与指示线宽（官方 2dp；令牌层的 `stroke::HAIRLINE` 只有 1dp）。
+pub const FOCUS_STROKE: f32 = 2.0;
+
+/// G18：Slider 轨道高（激活/未激活同值）。
+pub const TRACK_HEIGHT: f32 = 16.0;
+
+/// G18：Slider 竖条 handle 宽（静息 / hover）。
+pub const HANDLE_WIDTH: f32 = 4.0;
+
+/// G18：Slider 竖条 handle 宽（focus / pressed）——A1 在这两态收窄到 2。
+pub const HANDLE_WIDTH_ACTIVE: f32 = 2.0;
+
+/// G18：Slider 竖条 handle 高（纵向溢出轨道，上下各 14）。
+pub const HANDLE_HEIGHT: f32 = 44.0;
+
+/// G18：离散停靠点直径。
+pub const STOP_SIZE: f32 = 4.0;
+
+/// G18：停靠点与轨道段之间的空隙（官方 `StopIndicatorTrailingSpace = 6`；6 不在 4px 栅格上）。
+pub const STOP_GAP: f32 = 6.0;
+
+/// G19：菜单项高。
+pub const MENU_ITEM_HEIGHT: f32 = 48.0;
+
+/// G20：搜索条最小宽（列宽不足时**不许压窄**，降级为 40 高 TextField 或 icon 入口）。
+pub const SEARCH_MIN_WIDTH: f32 = 360.0;
+
+/// G20：搜索条最大宽。
+pub const SEARCH_MAX_WIDTH: f32 = 720.0;
+
+/// G20：展开面板最小高（空结果也不许矮于它）。
+pub const SEARCH_VIEW_MIN_HEIGHT: f32 = 240.0;
+
+/// 文本字段的几何（Filled / Outlined 共用；差别只在颜色与形状）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct FieldGeometry {
+    /// 可见高：带标签 [`FIELD_HEIGHT`]，无标签 `LM.control_height`。
+    pub height: f32,
+    /// 内容内边距（无图标 16/16；有前置图标 12/16，图标与文本间距另算）。
+    pub padding: Padding,
+    /// 前置图标可视左边距（无偏移，就是内边距 12）。
+    pub icon_inset: f32,
+    /// 图标 ↔ 文本间距（12：12 + 24 + 12 = 48 起文本，与官方 48 的图标槽一致）。
+    pub icon_gap: f32,
+    /// 图标边长（24）。
+    pub icon: f32,
+    /// 静息描边（一像素线）。
+    pub stroke: f32,
+    /// 聚焦/错误描边（2）。
+    pub focus_stroke: f32,
+    /// 圆角档位（`Component::TextField` = ExtraSmall）。
+    pub shape: ShapeScale,
+}
+
+impl FieldGeometry {
+    /// 求值；`labeled` = 带浮动标签（56），否则单行 40；`leading` = 有没有前置图标。
+    pub fn of(ui: &Ui, labeled: bool, leading: Option<IconKind>) -> Self {
+        let icon_inset = ui.space(Space::X3);
+        let pad_end = ui.space(Space::X4);
+        let padding = if leading.is_some() {
+            Padding {
+                top: 0.0,
+                right: pad_end,
+                bottom: 0.0,
+                left: icon_inset,
+            }
+        } else {
+            Padding {
+                top: 0.0,
+                right: pad_end,
+                bottom: 0.0,
+                left: pad_end,
+            }
+        };
+
+        Self {
+            height: if labeled {
+                FIELD_HEIGHT
+            } else {
+                ui.metrics().control_height
+            },
+            padding,
+            icon_inset,
+            icon_gap: ui.space(Space::X3),
+            icon: IconSize::Toolbar.px(),
+            stroke: STROKE_PX,
+            focus_stroke: FOCUS_STROKE,
+            shape: Component::TextField.spec().shape,
+        }
+    }
+}
+
+/// Slider 的几何（轨道 / 竖条 / 停靠点 / 命中区）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct SliderGeometry {
+    /// 轨道高（16）。
+    pub track: f32,
+    /// 竖条宽（静息 4 / focus·pressed 2）。
+    pub handle: f32,
+    /// 竖条高（44）。
+    pub handle_tall: f32,
+    /// 停靠点直径（4）。
+    pub stop: f32,
+    /// 控件高 = 命中区（`LM.touch_target` 48：竖条 44 + 上下各 2）。
+    pub height: f32,
+}
+
+impl SliderGeometry {
+    /// 从令牌求值。
+    pub fn of(ui: &Ui) -> Self {
+        Self {
+            track: TRACK_HEIGHT,
+            handle: HANDLE_WIDTH,
+            handle_tall: HANDLE_HEIGHT,
+            stop: STOP_SIZE,
+            height: ui.metrics().touch_target,
+        }
+    }
+}
+
+/// 菜单（Menu / DropdownMenuItem）的几何。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct MenuGeometry {
+    /// 项高（48）。
+    pub item_height: f32,
+    /// 水平内边距（12，来自 `Space::X3`）。
+    pub pad_h: f32,
+    /// 上下留白（8，来自 `Space::X2`）。
+    pub pad_v: f32,
+    /// 槽位图标边长（24）。
+    pub icon: f32,
+    /// 图标 ↔ 文本间距（12）。
+    pub gap: f32,
+    /// 容器圆角档位（`Component::Menu` = ExtraSmall 4）。
+    pub shape: ShapeScale,
+}
+
+impl MenuGeometry {
+    /// 从令牌求值。
+    pub fn of(ui: &Ui) -> Self {
+        Self {
+            item_height: MENU_ITEM_HEIGHT,
+            pad_h: ui.space(Space::X3),
+            pad_v: ui.space(Space::X2),
+            icon: IconSize::Toolbar.px(),
+            gap: ui.space(Space::X3),
+            shape: Component::Menu.spec().shape,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use unlucky_design::color::SchemeFlavor;
+    use unlucky_design::typography::Platform;
+
+    use crate::theme::Families;
+
+    const FAMILIES: Families = Families {
+        text: "Segoe UI",
+        display: "Segoe UI",
+        mono: "Consolas",
+    };
+
+    fn ui() -> Ui {
+        Ui::with_platform(SchemeFlavor::Light, Platform::Windows, FAMILIES)
+    }
+
+    /// G16 / G17：两个 2dp 与 56dp 的参考值钉在这里（改参考表会让这条红）。
+    #[test]
+    fn field_geometry_matches_the_reference_table() {
+        let ui = ui();
+        let labeled = FieldGeometry::of(&ui, true, None);
+        assert_eq!(labeled.height, 56.0, "G16 TextFieldDefaults.MinHeight");
+        assert_eq!(labeled.stroke, 1.0, "静息一像素线");
+        assert_eq!(labeled.focus_stroke, 2.0, "G17 FocusOutlineWidth");
+        assert_eq!(labeled.shape.dp(), 4.0, "CornerExtraSmall");
+
+        // 无标签单行 40 = 骨架令牌，不是字面量
+        let compact = FieldGeometry::of(&ui, false, None);
+        assert_eq!(compact.height, ui.metrics().control_height);
+        assert_eq!(compact.height, 40.0);
+
+        // 内边距：无图标 16/16
+        assert_eq!(compact.padding.left, 16.0);
+        assert_eq!(compact.padding.right, 16.0);
+        assert_eq!(compact.padding.left, compact.padding.right);
+    }
+
+    /// 前置图标：图标可视边 12、文本从 48 起（= 12 + 24 + 12，官方 48 的图标槽）。
+    #[test]
+    fn field_icon_slot_matches_the_official_48() {
+        let ui = ui();
+        let leading = FieldGeometry::of(&ui, true, Some(IconKind::Search));
+        assert_eq!(leading.icon, 24.0, "LeadingIconSize");
+        assert_eq!(leading.icon_inset, 12.0, "textFieldHorizontalIconPadding");
+        // 文本起点 = 图标可视边 12 + 图标 24 + 间距 12 = 48（官方图标槽）
+        assert_eq!(leading.icon_inset + leading.icon + leading.icon_gap, 48.0);
+        // 右侧仍是 16（官方内边距不因图标变）
+        assert_eq!(leading.padding.right, 16.0);
+    }
+
+    /// G18：轨道 16 / 竖条 4×44 / 停靠点 4 / 命中 48；竖条比轨道高 28 ⇒ 上下各溢出 14。
+    #[test]
+    fn slider_geometry_matches_the_reference_table() {
+        let ui = ui();
+        let slider = SliderGeometry::of(&ui);
+        assert_eq!(slider.track, 16.0, "ActiveTrackHeight");
+        assert_eq!(slider.handle, 4.0, "HandleWidth");
+        assert_eq!(slider.handle_tall, 44.0, "HandleHeight");
+        assert_eq!(slider.stop, 4.0, "StopIndicatorSize");
+        assert_eq!(
+            (slider.handle_tall - slider.track) / 2.0,
+            14.0,
+            "上下各溢出"
+        );
+        assert_eq!(slider.height, 48.0, "命中下限 LM.touch_target");
+        assert!(slider.height >= slider.handle_tall, "命中区必须容得下竖条");
+        // focus / pressed 收窄到 2（A1 FocusHandleWidth / PressedHandleWidth）
+        assert_eq!(HANDLE_WIDTH_ACTIVE, 2.0);
+        assert!(HANDLE_WIDTH_ACTIVE < slider.handle);
+    }
+
+    /// G19：项高 48、水平 12、上下 8、图标 24、圆角按令牌表（4，**不是** 12b 说的 12）。
+    #[test]
+    fn menu_geometry_matches_the_reference_table() {
+        let ui = ui();
+        let menu = MenuGeometry::of(&ui);
+        assert_eq!(menu.item_height, 48.0, "MenuListItemContainerHeight");
+        assert_eq!(menu.pad_h, 12.0, "DropdownMenuItemHorizontalPadding");
+        assert_eq!(menu.pad_v, 8.0, "DropdownMenuVerticalPadding");
+        assert_eq!(menu.icon, 24.0);
+        assert_eq!(
+            menu.shape.dp(),
+            4.0,
+            "MenuTokens.ContainerShape = CornerExtraSmall"
+        );
+        assert_eq!(
+            menu.shape,
+            Component::Menu.spec().shape,
+            "圆角只能来自令牌表"
+        );
+        assert_eq!(menu.gap, ui.space(Space::X3), "图标 ↔ 文本 12 走栅格令牌");
+    }
+
+    /// G20：搜索条 min 360 / max 720；面板最小高 240；条高取骨架令牌 56（**不在这里重复定义**）。
+    #[test]
+    fn search_constants_do_not_duplicate_layout_metrics() {
+        let ui = ui();
+        assert_eq!(SEARCH_MIN_WIDTH, 360.0);
+        assert_eq!(SEARCH_MAX_WIDTH, 720.0);
+        assert_eq!(SEARCH_VIEW_MIN_HEIGHT, 240.0);
+        assert_eq!(ui.metrics().search_bar_height, 56.0, "条高来自 LM");
+        assert_eq!(
+            ShapeScale::Full.radius_px(ui.metrics().search_bar_height),
+            28.0
+        );
+        assert_eq!(Component::Search.spec().shape, ShapeScale::Full);
+        // 图标可视边 = pad + offset（M69 的 SEARCH_BAR 不变量，本文件不重复定义 12/4）
+        let bar = Component::Search.metrics().expect("Search 有组件级度量");
+        assert_eq!(bar.pad_start + bar.icon_offset, 16.0);
+        assert_eq!(bar.icon, 24.0);
+    }
+}
diff --git a/crates/app-iced/src/components/inputs/menu.rs b/crates/app-iced/src/components/inputs/menu.rs
new file mode 100644
index 0000000..9dc7050
--- /dev/null
+++ b/crates/app-iced/src/components/inputs/menu.rs
@@ -0,0 +1,354 @@
+//! 菜单（`research/12b` §8）：`Menu` 弹出层 + `DropdownMenuItem`。
+//!
+//! ## 参考值（`[源]` = A1，`MenuTokens` / `Menu.kt` 1.4.0）
+//!
+//! | # | 检查项 | 参考值 | 落点 |
+//! |---|---|---|---|
+//! | 8.1 | 容器圆角 | 官方 **4**（`ContainerShape = CornerExtraSmall`）；`12b` 说「本项目 12」——**取令牌表的 4**（报告偏离 D18） | `Component::Menu.spec().shape` |
+//! | 8.2 | 容器色 / 高程 | `SurfaceContainer` + **L2** | `Role::SurfaceContainer` + `Elevation::Level2` |
+//! | 8.3 | 项高 | **48** | `MENU_ITEM_HEIGHT`（G19） |
+//! | 8.4 | 项内边距 | 水平 **12**、菜单上下留白 **8** | `Space::X3` / `Space::X2` |
+//! | 8.5 | 字级 / 图标 | 文本 `BodyMedium 14/20`；图标 **24** | `TypeRole` + `IconSize::Toolbar` |
+//! | 8.6 | 选中项 | 容器 `SecondaryContainer` + 文本 `OnSecondaryContainer`；指示器水平内缩 **4**、圆角 **8** | [`MenuItem::selected`] |
+//! | 8.7 | 宽度 | 不窄于触发元素、长文本不换行（`ellipsis` 本轮不做，登记 D19） | [`Menu::width`] |
+//!
+//! ## 弹出层阴影
+//!
+//! 高程取 `Component::Menu.spec().elevation`（= L2），阴影参数取 `Elevation::shadow()`
+//! （`ShadowSpec`：blur 6 / offset 2 / alpha 0.14，令牌层给的值），阴影色取 `Role::Shadow`。
+//! **容器色不取 `MaterialLayer::Overlay`**：那是 `SurfaceContainerHigh`，比 A1 的 `SurfaceContainer`
+//! 高一档；`MaterialLayer` 只用来确认「弹出层属于 Overlay 语义」，颜色以 A1 为准。
+//!
+//! ## 分组分隔线
+//!
+//! 复用 [`crate::app::components::divider::full`]（一像素线 + `OutlineVariant`），**不自己画线**。
+//! 菜单水平内边距 12 由容器给，所以分隔线自然落在 12 内缩后的宽度上。
+
+use iced::widget::text::LineHeight;
+use iced::widget::{button, column, container, text};
+use iced::{
+    Alignment, Background, Border, Color, Element, Length, Padding, Pixels, Shadow, Vector,
+};
+
+use unlucky_design::color::Role;
+use unlucky_design::component_map::Component;
+use unlucky_design::elevation::Elevation;
+use unlucky_design::icons::IconKind;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use crate::icons;
+use crate::theme::Ui;
+
+use super::super::divider;
+use super::super::interaction::{self, Interaction};
+use super::super::layout;
+use super::geometry::MenuGeometry;
+
+/// 菜单里的一项。
+#[derive(Debug, Clone)]
+pub struct MenuItem<'a, M> {
+    label: &'a str,
+    leading: Option<IconKind>,
+    trailing: Option<IconKind>,
+    on_press: Option<M>,
+    selected: bool,
+    state: Option<Interaction>,
+}
+
+impl<'a, M> MenuItem<'a, M> {
+    /// 一个可点的项。
+    pub fn new(label: &'a str, on_press: M) -> Self {
+        Self {
+            label,
+            leading: None,
+            trailing: None,
+            on_press: Some(on_press),
+            selected: false,
+            state: None,
+        }
+    }
+
+    /// 一个禁用的项（无消息 = 点不动，与按钮家族同一口径）。
+    pub fn disabled(label: &'a str) -> Self {
+        Self {
+            label,
+            leading: None,
+            trailing: None,
+            on_press: None,
+            selected: false,
+            state: None,
+        }
+    }
+
+    /// 前置槽位（24）。
+    pub fn leading(mut self, kind: IconKind) -> Self {
+        self.leading = Some(kind);
+        self
+    }
+
+    /// 后置槽位（24；勾选/快捷键提示用）。
+    pub fn trailing(mut self, kind: IconKind) -> Self {
+        self.trailing = Some(kind);
+        self
+    }
+
+    /// 选中项（`SecondaryContainer` + `OnSecondaryContainer`）。
+    pub fn selected(mut self) -> Self {
+        self.selected = true;
+        self
+    }
+
+    /// 强制视觉态（gallery 状态矩阵取证）。
+    pub fn state(mut self, state: Interaction) -> Self {
+        self.state = Some(state);
+        self
+    }
+}
+
+/// 菜单里的一行：普通项或分组分隔线。
+#[derive(Debug, Clone)]
+pub enum Entry<'a, M> {
+    /// 一个可点/禁用的项。
+    Item(MenuItem<'a, M>),
+    /// 分组分隔线（复用 `components::divider`）。
+    Divider,
+}
+
+/// 菜单弹出层。
+#[derive(Debug, Clone)]
+pub struct Menu<'a, M> {
+    entries: Vec<Entry<'a, M>>,
+    width: Length,
+}
+
+impl<'a, M> Default for Menu<'a, M> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl<'a, M> Menu<'a, M> {
+    /// 空菜单（默认按容器宽度伸展，宽度由调用方定）。
+    pub fn new() -> Self {
+        Self {
+            entries: Vec::new(),
+            width: Length::Fill,
+        }
+    }
+
+    /// 追加一项。
+    pub fn item(mut self, item: MenuItem<'a, M>) -> Self {
+        self.entries.push(Entry::Item(item));
+        self
+    }
+
+    /// 追加一条分组分隔线。
+    pub fn divider(mut self) -> Self {
+        self.entries.push(Entry::Divider);
+        self
+    }
+
+    /// 菜单宽度（8.7：不窄于触发元素由调用方保证）。
+    pub fn width(mut self, width: Length) -> Self {
+        self.width = width;
+        self
+    }
+}
+
+/// 一项的颜色（8.5 / 8.6 / 禁用）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+struct ItemPalette {
+    /// 项底色；`None` = 透明（不画状态层）。
+    fill: Option<Color>,
+    /// 文本色。
+    ink: Color,
+    /// 图标色（前置槽位；A1 是 `OnSecondaryContainer`）。
+    icon: Color,
+    /// 圆角档位（选中指示器 8）。
+    shape: ShapeScale,
+}
+
+/// 解析一项的颜色：选中优先，其余按五态叠状态层（`interaction::overlay_color`）。
+fn item_palette(ui: &Ui, state: Interaction, selected: bool) -> ItemPalette {
+    if state.is_disabled() {
+        // 禁用：内容 38%（无容器时叠在表面色上；菜单项本身透明）
+        let ink = interaction::disabled_content_over_role(ui, Role::OnSurface, false);
+        return ItemPalette {
+            fill: None,
+            ink,
+            icon: ink,
+            shape: ShapeScale::Small,
+        };
+    }
+
+    if selected {
+        // 选中项也要跟态走：状态层叠在 SecondaryContainer 上（不透明结果，D27）
+        let fill = interaction::overlay_color(
+            ui,
+            state,
+            Role::OnSecondaryContainer,
+            Role::SecondaryContainer,
+        )
+        .unwrap_or_else(|| ui.color(Role::SecondaryContainer));
+        return ItemPalette {
+            fill: Some(fill),
+            ink: ui.color(Role::OnSecondaryContainer),
+            icon: ui.color(Role::OnSecondaryContainer),
+            shape: ShapeScale::Small,
+        };
+    }
+
+    ItemPalette {
+        // 状态层叠在**菜单容器色**上（SurfaceContainer），得到不透明结果（D27）
+        fill: interaction::overlay_color(ui, state, Role::OnSurface, Role::SurfaceContainer),
+        ink: ui.color(Role::OnSurface),
+        icon: ui.color(Role::OnSecondaryContainer),
+        shape: ShapeScale::Small,
+    }
+}
+
+/// 菜单弹出层（`SurfaceContainer` + L2 阴影）。
+pub fn menu<'a, M: Clone + 'a>(ui: &'a Ui, menu: Menu<'a, M>) -> Element<'a, M> {
+    let geometry = MenuGeometry::of(ui);
+    let spec = Component::Menu.spec();
+    let elevation = spec.elevation;
+    debug_assert_eq!(
+        elevation,
+        Elevation::Level2,
+        "MenuTokens.ContainerElevation"
+    );
+    let shadow_spec = elevation.shadow();
+    let panel = ui.color(Role::SurfaceContainer);
+    let shape = geometry.shape;
+
+    let mut rows = column![].width(Length::Fill);
+    for entry in menu.entries {
+        rows = rows.push(match entry {
+            Entry::Item(item) => item_row(ui, item, geometry),
+            // 分组分隔线：复用 `divider::full`（一像素线 + OutlineVariant），不自己画
+            Entry::Divider => divider::full::<M>(ui),
+        });
+    }
+
+    container(layout::inset(0.0, geometry.pad_v, rows))
+        .width(menu.width)
+        .style(move |_theme| container::Style {
+            background: Some(Background::Color(panel)),
+            border: Border {
+                radius: ui.radius_dp(shape),
+                ..Border::default()
+            },
+            shadow: Shadow {
+                color: Color {
+                    a: shadow_spec.alpha,
+                    ..ui.color(Role::Shadow)
+                },
+                offset: Vector::new(0.0, shadow_spec.offset_y_px),
+                blur_radius: shadow_spec.blur_px,
+            },
+            ..container::Style::default()
+        })
+        .into()
+}
+
+/// 一行菜单项（用 `button` 承载命中与四态，几何与颜色自绘）。
+fn item_row<'a, M: Clone + 'a>(
+    ui: &'a Ui,
+    item: MenuItem<'a, M>,
+    geometry: MenuGeometry,
+) -> Element<'a, M> {
+    let forced = item.state.or(if item.on_press.is_none() {
+        Some(Interaction::Disabled)
+    } else {
+        None
+    });
+    // 选中项的背景也要跟态走：禁用时不许留满档 SecondaryContainer
+    let colors = item_palette(ui, forced.unwrap_or(Interaction::Enabled), item.selected);
+    let body = ui.style(TypeRole::BodyMedium);
+
+    let label = text(item.label)
+        .size(body.size_px)
+        .line_height(LineHeight::Absolute(Pixels(body.line_height_px)))
+        .font(ui.font_of(body))
+        .color(colors.ink);
+
+    let mut row = iced::widget::Row::new()
+        .align_y(Alignment::Center)
+        .spacing(geometry.gap);
+    if let Some(kind) = item.leading {
+        // Q9：图标必须经固定尺寸容器
+        row = row.push(layout::fixed(
+            geometry.icon,
+            geometry.icon,
+            icons::view::<M>(kind, colors.icon),
+        ));
+    }
+    row = row.push(label);
+    if let Some(kind) = item.trailing {
+        // **撑开**：label 与 trailing 之间插一个水平 Fill，trailing 才会被推到行右内边距上
+        // （M3 里 trailing 是「快捷键 / 子菜单箭头 / 勾」，必须在一列菜单里成一条竖线）。
+        // 没有 trailing 时**不插**：label 仍在左边，不会被居中或右对齐。
+        row = row.push(iced::widget::space::horizontal());
+        row = row.push(layout::fixed(
+            geometry.icon,
+            geometry.icon,
+            icons::view::<M>(kind, colors.icon),
+        ));
+    }
+
+    // 行必须撑满 item 宽度：上面的 Fill 空间要有宽度可撑（Q8 的教训：撑开靠容器，不靠子元素）。
+    // 顺带把内容垂直居中——`button` 只把内容放在 padding-box 的左上角。
+    let content = iced::widget::container(row)
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .align_y(Alignment::Center);
+
+    let selected = item.selected;
+    let style = move |_theme: &iced::Theme, status: button::Status| {
+        let state = forced.unwrap_or_else(|| Interaction::from_status(status));
+        let colors = item_palette(ui, state, selected);
+        button::Style {
+            background: colors.fill.map(Background::Color),
+            text_color: colors.ink,
+            border: Border {
+                radius: ui.radius_dp(colors.shape),
+                ..Border::default()
+            },
+            shadow: Shadow::default(),
+            snap: true,
+        }
+    };
+
+    let inset = ui.space(Space::X1);
+    let button = button(content)
+        .width(Length::Fill)
+        .height(Length::Fixed(geometry.item_height))
+        .padding(Padding {
+            top: 0.0,
+            // 选中指示器水平内缩 4（8.6 / 参考图纸），内容仍落在 12 上：12 = 4 + 8
+            right: geometry.pad_h - inset,
+            bottom: 0.0,
+            left: geometry.pad_h - inset,
+        })
+        .style(style);
+
+    let element: Element<'a, M> = match item.on_press {
+        Some(message) => button.on_press(message).into(),
+        None => button.into(),
+    };
+
+    container(element)
+        .width(Length::Fill)
+        .padding(Padding {
+            top: 0.0,
+            right: inset,
+            bottom: 0.0,
+            left: inset,
+        })
+        .into()
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/app-iced/src/components/inputs/menu/tests.rs b/crates/app-iced/src/components/inputs/menu/tests.rs
new file mode 100644
index 0000000..19f041b
--- /dev/null
+++ b/crates/app-iced/src/components/inputs/menu/tests.rs
@@ -0,0 +1,123 @@
+//! menu 的单测（从 `menu.rs` 拆出：单文件 ≤400 行，AGENTS.md §3-1）。
+
+use super::*;
+use unlucky_design::color::SchemeFlavor;
+use unlucky_design::typography::Platform;
+
+use crate::theme::Families;
+
+const FAMILIES: Families = Families {
+    text: "Segoe UI",
+    display: "Segoe UI",
+    mono: "Consolas",
+};
+
+fn ui(flavor: SchemeFlavor) -> Ui {
+    Ui::with_platform(flavor, Platform::Windows, FAMILIES)
+}
+
+fn sample(flavor: SchemeFlavor) -> Element<'static, u8> {
+    let ui = Box::leak(Box::new(ui(flavor)));
+    let spec = Menu::new()
+        .item(MenuItem::new("重命名", 1_u8).leading(IconKind::Folder))
+        .item(
+            MenuItem::new("复制实例", 2_u8)
+                .selected()
+                .trailing(IconKind::Check),
+        )
+        .divider()
+        .item(MenuItem::disabled("删除").leading(IconKind::Trash));
+    menu(ui, spec)
+}
+
+/// 8.2：容器 `SurfaceContainer` + L2；阴影参数来自高程令牌。
+#[test]
+fn container_uses_surface_container_and_level2_shadow() {
+    let ui = ui(SchemeFlavor::Light);
+    assert_eq!(Component::Menu.spec().elevation, Elevation::Level2);
+    assert_eq!(
+        Component::Menu.spec().elevation.surface_role(),
+        Role::SurfaceContainer,
+        "L2 的容器角色与 MenuTokens.ContainerColor 一致"
+    );
+    let shadow = Elevation::Level2.shadow();
+    assert!(shadow.is_visible(), "菜单是浮层，必须有可见阴影");
+    assert_eq!(shadow.blur_px, 6.0);
+    assert_eq!(shadow.offset_y_px, 2.0);
+    // 容器色**不是** MaterialLayer::Overlay（那会高一档）
+    assert_ne!(
+        ui.layer(unlucky_design::elevation::MaterialLayer::Overlay),
+        ui.color(Role::SurfaceContainer)
+    );
+}
+
+/// 8.6：选中 = SecondaryContainer + OnSecondaryContainer；禁用内容 38%。
+#[test]
+fn selected_and_disabled_items_use_the_right_roles() {
+    let ui = ui(SchemeFlavor::Light);
+    let selected = item_palette(&ui, Interaction::Enabled, true);
+    assert_eq!(selected.fill, Some(ui.color(Role::SecondaryContainer)));
+    assert_eq!(selected.ink, ui.color(Role::OnSecondaryContainer));
+    assert_eq!(selected.icon, ui.color(Role::OnSecondaryContainer));
+
+    // 选中 + hover：状态层叠在 SecondaryContainer 上（不是满档底色）
+    let hovered = item_palette(&ui, Interaction::Hovered, true);
+    assert_ne!(hovered.fill, selected.fill);
+    assert_eq!(
+        hovered.fill,
+        interaction::overlay_color(
+            &ui,
+            Interaction::Hovered,
+            Role::OnSecondaryContainer,
+            Role::SecondaryContainer
+        )
+    );
+
+    let disabled = item_palette(&ui, Interaction::Disabled, true);
+    assert_eq!(disabled.fill, None, "禁用项不留满档选中底色");
+    assert_eq!(
+        disabled.ink,
+        interaction::disabled_content_over_role(&ui, Role::OnSurface, false)
+    );
+    assert_ne!(disabled.ink, ui.color(Role::OnSurface));
+}
+
+/// 五态：hover 8% / pressed 10% / focus 10% 都叠在 SurfaceContainer 上（不透明）。
+#[test]
+fn item_states_blend_on_the_menu_container() {
+    let ui = ui(SchemeFlavor::Light);
+    let rest = item_palette(&ui, Interaction::Enabled, false);
+    assert_eq!(rest.fill, None, "静息不叠色（菜单底色透出来）");
+    for state in [
+        Interaction::Hovered,
+        Interaction::Pressed,
+        Interaction::Focused,
+    ] {
+        let fill = item_palette(&ui, state, false)
+            .fill
+            .expect("可交互态必须给底色");
+        assert_eq!(fill.a, 1.0, "结果必须不透明（D27）");
+        assert_ne!(Some(fill), rest.fill);
+    }
+}
+
+/// 8.3 / 8.4：项高 48、水平 12（内容）、选中指示器内缩 4 ⇒ 内容仍在 12。
+#[test]
+fn item_geometry_matches_the_reference_table() {
+    let ui = ui(SchemeFlavor::Light);
+    let geometry = MenuGeometry::of(&ui);
+    assert_eq!(geometry.item_height, 48.0);
+    assert_eq!(geometry.pad_h, 12.0);
+    assert_eq!(geometry.pad_v, 8.0);
+    let inset = ui.space(Space::X1);
+    assert_eq!(inset, 4.0);
+    assert_eq!((geometry.pad_h - inset) + inset, 12.0, "内容落在 12 上");
+}
+
+/// 三种形态（带槽位 / 选中 / 禁用 / 分组线）都能构建。
+#[test]
+fn menu_shapes_build() {
+    for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+        let _: Element<'static, u8> = sample(flavor);
+    }
+}
diff --git a/crates/app-iced/src/components/inputs/mod.rs b/crates/app-iced/src/components/inputs/mod.rs
new file mode 100644
index 0000000..5e880ba
--- /dev/null
+++ b/crates/app-iced/src/components/inputs/mod.rs
@@ -0,0 +1,42 @@
+//! **输入类家族**（D39 §1 的 `inputs/`）：§9 TextField / §20 Search / §11 Slider / §8 Menu。
+//!
+//! 四个组件的共同纪律（与本目录外的契约一一对应）：
+//!
+//! - **对消息类型泛型**（`M: Clone`，不 import `crate::app::Message`）——组件库要能脱离业务验收；
+//! - **`&'a Ui` 传入**，组件内部不 `Ui::new`（深浅热切靠外部重建整树）；
+//! - **不持有 `String`**：文本框与搜索条是受控组件（借值 + `on_input`/`on_change` 回传），
+//!   滑块也只借一个比例；
+//! - **hover/pressed/focus/disabled 一律走 [`super::interaction`]**（α 只有一处定义）；
+//! - **精确尺寸走 [`super::layout`]**（Q8/Q9 的两个固定解法），图标一律 `layout::fixed`；
+//! - **零尺寸字面量**：能取令牌的取令牌，取不到的集中登记在 [`geometry`] 的 G16~G20。
+//!
+//! ## 文件分工
+//!
+//! | 文件 | 内容 |
+//! |---|---|
+//! | [`geometry`] | 内部几何 + G 编号常量（`FieldGeometry` / `SliderGeometry` / `MenuGeometry`） |
+//! | [`field`] | [`text_field`]（Filled / Outlined） |
+//! | [`search`] | [`search_bar`]（收起）+ [`search_view`]（展开 docked） |
+//! | [`slider`] | [`slider`]（自绘 `Widget`：轨道 16 + 竖条 4×44） |
+//! | [`menu`] | [`menu`]（`Menu` + `MenuItem` + 分组分隔线） |
+//!
+//! ## 与契约 §2 示例签名的关系
+//!
+//! 契约示例是 `filled(ui, label, on_press)`；本家族的四个组件都比三个参数多（变体 × 五态 ×
+//! 前后槽位 × 错误/辅助文本），所以照按钮家族的先例把「部件参数」收进构造器结构体：
+//! `text_field(ui, Field::new(value).label("名称"), on_input)`。**泛型纪律一字不改**，
+//! 差别只是位置参数变命名参数（按钮家族已登记同一决定，见 `buttons` 模块文档）。
+
+pub mod geometry;
+
+mod field;
+mod menu;
+#[cfg(test)]
+mod probe;
+mod search;
+mod slider;
+
+pub use field::{text_field, Field, FieldVariant};
+pub use menu::{menu, Menu, MenuItem};
+pub use search::{search_bar, search_view, SearchBar, SearchView};
+pub use slider::{slider, Slider};
diff --git a/crates/app-iced/src/components/inputs/probe.rs b/crates/app-iced/src/components/inputs/probe.rs
new file mode 100644
index 0000000..8a1086e
--- /dev/null
+++ b/crates/app-iced/src/components/inputs/probe.rs
@@ -0,0 +1,347 @@
+//! 渲染层几何断言（D30 / M68 的教训：**纯函数对 ≠ 图画对**）。
+//!
+//! ## 为什么这个文件在 `inputs/` 而不是 `gallery/probe.rs`
+//!
+//! 像素工具 `gallery::scan` 是 `mod scan;`（**私有**于 `gallery`），我的 probe 拿不到它，
+//! 而 `gallery/mod.rs` 不在本 mission 的 scope 里。所以这里自带一份最小的读图器
+//! （约 40 行：读 PNG / 取点 / 连通块 / 行覆盖），判据全在本文件——已作为 finding 报给 tower
+//! （建议把 `gallery::scan` 提升为 `pub(crate)`，四个家族就能共用一份）。
+//!
+//! ## 怎么跑（worktree 根目录）
+//!
+//! ```text
+//! # ① 出图：副本工程只把 inputs 段提到首位（组件代码逐字节相同），见 target/m77/sync.py
+//! python target/m77/sync.py && (cd /d/tmp/m77-shot && cargo build --no-default-features ...)
+//! M77_PART=text ./target/debug/unlucky-launcher-iced.exe --software-renderer --screen=gallery \
+//!     --screenshot target/m77/text-light.png --screenshot-theme=light
+//! # ② 量图
+//! ULL_INPUTS_DIR=target/m77 cargo test -p unlucky-app-iced inputs::probe
+//! ```
+//!
+//! 没给 `ULL_INPUTS_DIR` 就**大声跳过**（不静默通过），与 `gallery::probe` 的口径一致。
+//!
+//! ## 量什么（每条都对着一个「已经可能画错」的形态）
+//!
+//! | 断言 | 抓的错误 |
+//! |---|---|
+//! | 文本框高 **56**、宽 **320** | 高度被内容/内边距吃掉（不是 56 的 A 级值） |
+//! | Filled 底部指示线 静息 **1.0** / 聚焦 **2.0** 墨量 | 把 2dp 画成 1dp（或反过来） |
+//! | Outlined 描边 静息 **1.0** / 聚焦 **2.0** 墨量 | 同上 |
+//! | 错误态：标签 / 线 / 辅助文本全 `Error` | 只把线染红、忘了标签与辅助文本 |
+//! | 搜索条高 **56**、图标墨迹偏移 **20**（= 16 + viewBox 4） | 手抄 16/20 当图标边、或 pad 与 offset 少加一段 |
+//! | docked 面板 宽 **360** / 头 **56** / 分隔线 **1.0 `Outline`** / 体 **240** | 用 `OutlineVariant`、或头部高度与 bar 不一致 |
+//! | Slider 0%（竖条贴左）、50%（分界在中央）、100%（无未激活段） | 位移区间取错（0..W 而不是 handle/2..W−handle/2） |
+//! | Slider 竖条 **4×44** | 画成圆点或撑满命中区 |
+//! | 菜单项 pitch **48**、选中指示器内缩 **4**、容器高 **161** | 项高/内边距抄错 |
+//! | 分组分隔线 **1.0** 墨量 | 分隔线变成 2px |
+
+use std::path::{Path, PathBuf};
+
+use unlucky_design::color::{Role, SchemeFlavor};
+use unlucky_design::typography::Platform;
+
+use crate::theme::{Families, Ui};
+
+const FAMILIES: Families = Families {
+    text: "Segoe UI",
+    display: "Segoe UI",
+    mono: "Consolas",
+};
+
+/// 颜色比对容差（抗锯齿/取整）。
+const TOLERANCE: u8 = 10;
+
+type Rgb = [u8; 3];
+
+fn ui(flavor: SchemeFlavor) -> Ui {
+    Ui::with_platform(flavor, Platform::Windows, FAMILIES)
+}
+
+fn rgb(color: iced::Color) -> Rgb {
+    [
+        (color.r * 255.0).round() as u8,
+        (color.g * 255.0).round() as u8,
+        (color.b * 255.0).round() as u8,
+    ]
+}
+
+fn matches(pixel: Rgb, expected: Rgb) -> bool {
+    matches_within(pixel, expected, TOLERANCE)
+}
+
+/// 指定容差的同色判断（量**阴影边**时要用更严的容差：阴影叠上去会落在 10 的容差内）。
+fn matches_within(pixel: Rgb, expected: Rgb, tolerance: u8) -> bool {
+    pixel
+        .iter()
+        .zip(expected)
+        .all(|(a, b)| a.abs_diff(b) <= tolerance)
+}
+
+/// 一张图的最小访问器（读 PNG / 取点 / 连通块）。
+struct Shot {
+    width: usize,
+    height: usize,
+    pixels: Vec<Rgb>,
+}
+
+/// 一张图里某颜色的连通块外接框（闭区间）。
+#[derive(Debug, Clone, Copy)]
+struct BBox {
+    left: usize,
+    right: usize,
+    top: usize,
+    bottom: usize,
+}
+
+impl BBox {
+    fn width(&self) -> usize {
+        self.right - self.left + 1
+    }
+
+    fn height(&self) -> usize {
+        self.bottom - self.top + 1
+    }
+}
+
+impl Shot {
+    fn load(path: &Path) -> Result<Self, String> {
+        let bytes = std::fs::read(path).map_err(|error| format!("读不动 {path:?}：{error}"))?;
+        let image = image::load_from_memory(&bytes)
+            .map_err(|error| format!("解 PNG 失败：{error}"))?
+            .to_rgb8();
+        let (width, height) = (image.width() as usize, image.height() as usize);
+        Ok(Self {
+            width,
+            height,
+            pixels: image.pixels().map(|p| p.0).collect(),
+        })
+    }
+
+    fn at(&self, x: usize, y: usize) -> Rgb {
+        self.pixels[y * self.width + x]
+    }
+
+    fn bbox_of(&self, color: Rgb, min_area: usize) -> Vec<BBox> {
+        let mut seen = vec![false; self.width * self.height];
+        let mut boxes = Vec::new();
+        for y in 0..self.height {
+            for x in 0..self.width {
+                if seen[y * self.width + x] || !matches(self.at(x, y), color) {
+                    continue;
+                }
+                let mut stack = vec![(x, y)];
+                seen[y * self.width + x] = true;
+                let mut bbox = BBox {
+                    left: x,
+                    right: x,
+                    top: y,
+                    bottom: y,
+                };
+                while let Some((cx, cy)) = stack.pop() {
+                    bbox.left = bbox.left.min(cx);
+                    bbox.right = bbox.right.max(cx);
+                    bbox.top = bbox.top.min(cy);
+                    bbox.bottom = bbox.bottom.max(cy);
+                    for (nx, ny) in [
+                        (cx + 1, cy),
+                        (cx.saturating_sub(1), cy),
+                        (cx, cy + 1),
+                        (cx, cy.saturating_sub(1)),
+                    ] {
+                        if nx < self.width
+                            && ny < self.height
+                            && !seen[ny * self.width + nx]
+                            && matches(self.at(nx, ny), color)
+                        {
+                            seen[ny * self.width + nx] = true;
+                            stack.push((nx, ny));
+                        }
+                    }
+                }
+                if bbox.width() * bbox.height() >= min_area {
+                    boxes.push(bbox);
+                }
+            }
+        }
+        boxes
+    }
+
+    fn count_in(&self, color: Rgb, x0: usize, x1: usize, y0: usize, y1: usize) -> usize {
+        let mut total = 0;
+        for y in y0..y1.min(self.height) {
+            for x in x0..x1.min(self.width) {
+                if matches(self.at(x, y), color) {
+                    total += 1;
+                }
+            }
+        }
+        total
+    }
+}
+
+/// 一行像素相对底色向 `line` 靠拢的比例（0..=1）——1dp 的线在各行上摊开时总和 ≈ 1.0。
+fn coverage(pixel: Rgb, surface: Rgb, line: Rgb) -> f32 {
+    let channel = |i: usize| {
+        let full = f32::from(line[i]) - f32::from(surface[i]);
+        if full.abs() < 1.0 {
+            return 0.0;
+        }
+        ((f32::from(pixel[i]) - f32::from(surface[i])) / full).clamp(0.0, 1.0)
+    };
+    (channel(0) + channel(1) + channel(2)) / 3.0
+}
+
+/// 竖直方向上的**线墨量**：`y0..y1` 每行在 x 区间上的平均覆盖之和（1dp ⇒ ≈1.0）。
+fn line_ink(
+    shot: &Shot,
+    x0: usize,
+    x1: usize,
+    y0: usize,
+    y1: usize,
+    surface: Rgb,
+    line: Rgb,
+) -> f32 {
+    let mut total = 0.0;
+    for y in y0..y1.min(shot.height) {
+        let mut sum = 0.0;
+        for x in x0..x1.min(shot.width) {
+            sum += coverage(shot.at(x, y), surface, line);
+        }
+        total += sum / (x1 - x0) as f32;
+    }
+    total
+}
+
+/// 某一行里「两色之一」的最长连续段 `(start, end)`，允许 ≤`max_gap` 的空隙。
+///
+/// 用它而不是「本行最左/最右」：深色档的说明文字里有零星像素落在令牌色容差内，
+/// 取 min/max 会把轨道量成从 x=24 起（实测）。
+fn longest_run(shot: &Shot, y: usize, a: Rgb, b: Rgb, max_gap: usize) -> Option<(usize, usize)> {
+    let mut best: Option<(usize, usize)> = None;
+    let mut start: Option<usize> = None;
+    let mut last: Option<usize> = None;
+    for x in 0..shot.width {
+        if matches(shot.at(x, y), a) || matches(shot.at(x, y), b) {
+            if start.is_none() {
+                start = Some(x);
+            }
+            last = Some(x);
+        } else if let (Some(from), Some(to)) = (start, last) {
+            if x - to > max_gap {
+                if best.is_none_or(|(p, q)| to - from > q - p) {
+                    best = Some((from, to));
+                }
+                start = None;
+                last = None;
+            }
+        }
+    }
+    if let (Some(from), Some(to)) = (start, last) {
+        if best.is_none_or(|(p, q)| to - from > q - p) {
+            best = Some((from, to));
+        }
+    }
+    best
+}
+
+/// `bbox` 范围内「整行至少 `min_pixels` 个同色像素」的行区间（闭区间）。
+///
+/// 菜单的阴影会把 bbox 外扩 ~5px，而阴影行绝不会有 100 个容器色像素——用它把阴影滤掉。
+fn row_extent(shot: &Shot, bbox: &BBox, color: Rgb, min_pixels: usize) -> (usize, usize) {
+    let mut first = None;
+    let mut last = None;
+    for y in bbox.top..=bbox.bottom {
+        let mut count = 0;
+        for x in bbox.left..=bbox.right {
+            // 容差收到 2：**阴影边**会落在默认容差 10 内，会把容器量高 ~5px
+            if matches_within(shot.at(x, y), color, 2) {
+                count += 1;
+            }
+        }
+        if count >= min_pixels {
+            first.get_or_insert(y);
+            last = Some(y);
+        }
+    }
+    (
+        first.expect("行内没有足够的同色像素"),
+        last.expect("行内没有足够的同色像素"),
+    )
+}
+
+/// `pixel` 更接近 `fill` 还是 `surface`（含平局都算 `fill`）。
+fn nearer(pixel: Rgb, fill: Rgb, surface: Rgb) -> bool {
+    let dist = |a: Rgb, b: Rgb| -> u32 {
+        a.iter()
+            .zip(b)
+            .map(|(x, y)| (i32::from(*x) - i32::from(y)).unsigned_abs())
+            .sum()
+    };
+    dist(pixel, fill) <= dist(pixel, surface)
+}
+
+/// 截图目录（`ULL_INPUTS_DIR`）；没给就返回 `None`（调用方大声跳过）。
+fn shot_dir() -> Option<PathBuf> {
+    let raw = std::env::var_os("ULL_INPUTS_DIR")?;
+    let path = PathBuf::from(raw);
+    if path.is_absolute() || path.is_dir() {
+        return Some(path);
+    }
+    let root = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../..");
+    Some(root.join(path))
+}
+
+/// 取一张图；缺图直接 panic（给了目录就说明这轮要认真量）。
+fn shot(dir: &Path, part: &str, flavor: SchemeFlavor) -> Shot {
+    let slug = match flavor {
+        SchemeFlavor::Light => "light",
+        SchemeFlavor::Dark => "dark",
+    };
+    let path = dir.join(format!("{part}-{slug}.png"));
+    let shot = Shot::load(&path).unwrap_or_else(|error| panic!("{error}"));
+    assert_eq!(
+        (shot.width, shot.height),
+        (1180, 760),
+        "验收图必须是 D30 的 1180×760 @100% DPI"
+    );
+    shot
+}
+
+/// 一个矩阵格在某列的竖直「实色高度」：从 `bbox.top-4` 往上/下走到不再接近 `fill` 为止。
+fn vertical_extent(
+    shot: &Shot,
+    bbox: &BBox,
+    fill: Rgb,
+    surface: Rgb,
+    column: usize,
+) -> (usize, usize) {
+    let mut top = bbox.top;
+    while top > 0 && nearer(shot.at(column, top - 1), fill, surface) {
+        top -= 1;
+    }
+    let mut bottom = bbox.bottom;
+    while bottom + 1 < shot.height && nearer(shot.at(column, bottom + 1), fill, surface) {
+        bottom += 1;
+    }
+    (top, bottom)
+}
+
+macro_rules! require_dir {
+    () => {
+        match shot_dir() {
+            Some(dir) => dir,
+            None => {
+                eprintln!(
+                    "[inputs::probe] SKIPPED：未设置 ULL_INPUTS_DIR。这是**渲染层**断言，\
+                     需要先按本文件模块文档出 8 张图（target/m77/*.png）。"
+                );
+                return;
+            }
+        }
+    };
+}
+
+mod menu;
+mod search;
+mod slider;
+mod text;
diff --git a/crates/app-iced/src/components/inputs/probe/menu.rs b/crates/app-iced/src/components/inputs/probe/menu.rs
new file mode 100644
index 0000000..b6ccdd0
--- /dev/null
+++ b/crates/app-iced/src/components/inputs/probe/menu.rs
@@ -0,0 +1,102 @@
+//! M77 probe · menu（从 `probe.rs` 拆出：单文件 ≤400 行，AGENTS.md §3-1）。
+
+use super::*;
+
+/// 8.3 / 8.4 / 8.6：菜单容器高 161、项 pitch 48、选中指示器内缩 4、分组分隔线 1dp。
+#[test]
+fn menu_container_items_and_divider() {
+    let dir = require_dir!();
+    for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+        let shot = shot(&dir, "menu", flavor);
+        let ui = ui(flavor);
+        let container = rgb(ui.color(Role::SurfaceContainer));
+        let selected = rgb(ui.color(Role::SecondaryContainer));
+        let divider = rgb(ui.color(Role::OutlineVariant));
+
+        // 右侧那只 = 「展开态」菜单。容器色块可能被**分组分隔线 / 选中项**切成多块，
+        // 所以先把 x>290 的块并成一个外接框，再逐行量容器色（容差 2，滤掉阴影外扩的 ~5px）。
+        let menus = shot.bbox_of(container, 2000);
+        let right: Vec<BBox> = menus.iter().filter(|b| b.left > 290).copied().collect();
+        assert!(!right.is_empty(), "找不到右侧的「展开态」菜单");
+        let mut open = right[0];
+        for b in right.iter().skip(1) {
+            open.left = open.left.min(b.left);
+            open.top = open.top.min(b.top);
+            open.right = open.right.max(b.right);
+            open.bottom = open.bottom.max(b.bottom);
+        }
+        let (top, bottom) = row_extent(&shot, &open, container, 1);
+        open.top = top;
+        open.bottom = bottom;
+
+        // 布局高 **161** = 8 + 48×3 + 1 + 8；抗锯齿会吃掉上下各 1 行 ⇒ 实测 160
+        assert!(
+            (159..=162).contains(&open.height()),
+            "8.3/8.4 菜单高应 161（= 8 + 48×3 + 1 + 8）：实测 {}",
+            open.height()
+        );
+
+        // 选中项：SecondaryContainer，高 48、左右各内缩 4
+        let selected_box = shot
+            .bbox_of(selected, 2000)
+            .into_iter()
+            .filter(|b| b.height() >= 44 && b.height() <= 50)
+            .max_by_key(|b| b.width())
+            .expect("找不到选中项的 SecondaryContainer");
+        assert!(
+            (46..=48).contains(&selected_box.height()),
+            "8.3 项高应 48：实测 {}",
+            selected_box.height()
+        );
+        // 容器左右缘：在第一项那一行按严格同色扫（bbox 会被阴影外扩 ~2px，不能用）
+        let scan_y = open.top + 10;
+        let row: Vec<usize> = (open.left..=open.right)
+            .filter(|x| matches_within(shot.at(*x, scan_y), container, 2))
+            .collect();
+        let (menu_left, menu_right) = (*row.first().unwrap(), *row.last().unwrap());
+        assert_eq!(selected_box.left - menu_left, 4, "8.6 选中指示器左内缩应 4");
+        assert_eq!(
+            menu_right - selected_box.right,
+            4,
+            "8.6 选中指示器右内缩应 4"
+        );
+
+        // 分组分隔线：1dp OutlineVariant 墨量 ≈1.0（位置在选中项与最后一项之间）
+        let ink = line_ink(
+            &shot,
+            open.left + 20,
+            open.right - 20,
+            selected_box.bottom + 1,
+            selected_box.bottom + 6,
+            container,
+            divider,
+        );
+        assert!(
+            (0.6..=1.4).contains(&ink),
+            "8.x 分组分隔线应 1dp `OutlineVariant`：实测墨量 {ink:.2}"
+        );
+
+        // trailing 槽位必须靠到**行右内边距**上（视觉 r5 P1：早先它紧贴 label 右边）。
+        //
+        // 位置公式：item 右缘 = menu_right − 4（选中指示器内缩）；button 内容右缘 = item 右缘 −
+        // (pad_h − inset) = menu_right − 12；trailing 图标盒 24 的**墨迹**再内缩 k（`Check` 字形
+        // 在 24 viewBox 里右边界 ≈ 5，与 leading 图标「可视边 12、墨迹 16」同一口径）。
+        // 所以墨迹右缘 ≈ menu_right − 17。变异（去掉撑开的 Fill）会让它贴着 label ⇒ 差 ~120。
+        let trailing_ink_color = rgb(ui.color(Role::OnSecondaryContainer));
+        let mut trailing_right = 0usize;
+        for y in selected_box.top..=selected_box.bottom {
+            for x in selected_box.left..=selected_box.right {
+                if matches(shot.at(x, y), trailing_ink_color) {
+                    trailing_right = trailing_right.max(x);
+                }
+            }
+        }
+        let trailing_offset = menu_right - trailing_right;
+        assert!(
+            (16..=18).contains(&trailing_offset),
+            "8.6/trailing：带 trailing 的项，其 trailing 墨迹右缘应在 item 右内边距上\
+             （menu_right − 17，允许 ±1）：实测 menu_right={menu_right}、墨迹右缘={trailing_right}\
+             ⇒ 偏 {trailing_offset}（贴 label 时会是 ~120）"
+        );
+    }
+}
diff --git a/crates/app-iced/src/components/inputs/probe/search.rs b/crates/app-iced/src/components/inputs/probe/search.rs
new file mode 100644
index 0000000..40dc2c3
--- /dev/null
+++ b/crates/app-iced/src/components/inputs/probe/search.rs
@@ -0,0 +1,80 @@
+//! M77 probe · search（从 `probe.rs` 拆出：单文件 ≤400 行，AGENTS.md §3-1）。
+
+use super::*;
+
+/// 20.1 / 20.4 / 20.6 / 20.8 / 20.9：条 56、图标墨迹偏移 20（= 16 + viewBox 4）、
+/// docked 面板 360 / 头 56 / 分隔线 1.0 `Outline` / 体 240。
+#[test]
+fn search_bar_and_docked_panel_geometry() {
+    let dir = require_dir!();
+    for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+        let shot = shot(&dir, "search", flavor);
+        let ui = ui(flavor);
+        let bar_color = rgb(ui.color(Role::SurfaceContainerHigh));
+        let ink = rgb(ui.color(Role::OnSurface));
+
+        let bars = shot.bbox_of(bar_color, 2000);
+        let bar = bars
+            .iter()
+            .filter(|b| b.height() <= 60 && b.width() >= 360)
+            .min_by_key(|b| b.top)
+            .copied()
+            .expect("找不到搜索条（高 ≤60、宽 ≥360）");
+        assert_eq!(bar.height(), 56, "20.1 搜索条高必须 56");
+        assert!(bar.width() >= 360, "20.2 搜索条宽 ≥ 360");
+
+        // 20.4：图标墨迹左缘 = pad 12 + offset 4 + viewBox 内 ≈4 = 20（±1）
+        let inner = (bar.top + 12)..(bar.bottom - 12);
+        let mut left_ink = usize::MAX;
+        for y in inner.clone() {
+            for x in bar.left..bar.right {
+                if matches(shot.at(x, y), ink) {
+                    left_ink = left_ink.min(x);
+                }
+            }
+        }
+        let offset = left_ink - bar.left;
+        assert!(
+            (19..=21).contains(&offset),
+            "20.4 前置图标墨迹偏移应 20（= 12 + 4 + viewBox 4）：实测 {offset}"
+        );
+
+        // 20.6 / 20.9：docked 面板 360 宽，头 56 + 1px 分隔线 + 体 240
+        // （头与体被那条线切成**两个同色块**，所以按 top 排序取前两块）
+        let mut parts = bars
+            .iter()
+            .filter(|b| b.width() == 360)
+            .copied()
+            .collect::<Vec<_>>();
+        parts.sort_by_key(|b| b.top);
+        assert_eq!(parts.len(), 2, "docked 面板 = 头部 + 结果区两块");
+        let (header, body) = (parts[0], parts[1]);
+        assert!(
+            (55..=56).contains(&header.height()),
+            "20.6 面板头部高 56（与 bar 同高；顶部圆角会吃掉 1 行抗锯齿，实测 {}）",
+            header.height()
+        );
+        assert_eq!(body.height(), 240, "20.9 结果区最小高 240");
+        assert!(
+            (2..=3).contains(&(body.top - header.bottom)),
+            "20.8 头与体之间正好 1dp（CPU 档摊成 2 行 ⇒ 隔 2~3 行）：实测 {}",
+            body.top - header.bottom
+        );
+        let panel = header;
+
+        // 20.8：分隔线是 `Outline`（不是 OutlineVariant），1dp 墨量 ≈1.0
+        let divider_ink = line_ink(
+            &shot,
+            panel.left + 40,
+            panel.right - 40,
+            panel.top + 50,
+            panel.top + 62,
+            bar_color,
+            rgb(ui.color(Role::Outline)),
+        );
+        assert!(
+            (0.7..=1.3).contains(&divider_ink),
+            "20.8 头部分隔线应 1dp `Outline`：实测墨量 {divider_ink:.2}"
+        );
+    }
+}
diff --git a/crates/app-iced/src/components/inputs/probe/slider.rs b/crates/app-iced/src/components/inputs/probe/slider.rs
new file mode 100644
index 0000000..5473a9c
--- /dev/null
+++ b/crates/app-iced/src/components/inputs/probe/slider.rs
@@ -0,0 +1,96 @@
+//! M77 probe · slider（从 `probe.rs` 拆出：单文件 ≤400 行，AGENTS.md §3-1）。
+
+use super::*;
+
+/// 11.1~11.6：竖条 4×44、0% 贴左、50% 分界在中央、100% 无未激活段（thumb 永不越界）。
+#[test]
+fn slider_thumb_positions_at_zero_half_and_full() {
+    let dir = require_dir!();
+    for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+        let shot = shot(&dir, "slider", flavor);
+        let ui = ui(flavor);
+        let active = rgb(ui.color(Role::Primary));
+        let inactive = rgb(ui.color(Role::SecondaryContainer));
+
+        // 三条「值行」= 宽 ≥400 的轨道（0% / 50% / 100%），按 y 排序
+        let mut rows: Vec<(usize, usize, usize)> = Vec::new();
+        for y in 0..shot.height {
+            if let Some((left, right)) = longest_run(&shot, y, active, inactive, 20) {
+                // 先按「跨度 ≥300」收行（把抗锯齿行也纳进来），band 建好后再按宽度筛。
+                if right - left + 1 >= 300 {
+                    rows.push((y, left, right));
+                }
+            }
+        }
+        // 合并相邻的 y（同一条轨道占 16 行），并把每行的端点累积成 min/max——
+        // 首行/末行都是抗锯齿行，只取它们会把轨道量窄 2~3px。
+        let mut bands: Vec<(usize, usize, usize, usize)> = Vec::new();
+        for (y, left, right) in rows {
+            match bands.last_mut() {
+                Some(last) if y - last.1 <= 3 => {
+                    last.1 = y;
+                    last.2 = last.2.min(left);
+                    last.3 = last.3.max(right);
+                }
+                _ => bands.push((y, y, left, right)),
+            }
+        }
+        // 值行是 448 宽（`Space::X8 × 14`）；五态行 5 条轨道会被并成 ~663 的带，按宽度筛掉
+        let bands: Vec<(usize, usize, usize, usize)> = bands
+            .into_iter()
+            .filter(|(_, _, left, right)| (440..=470).contains(&(right - left + 1)))
+            .collect();
+        assert_eq!(
+            bands.len(),
+            4,
+            "值行应有 4 条（0% / 50% / 100% / 离散）：实测 {}",
+            bands.len()
+        );
+
+        for (label, band) in ["0%", "50%", "100%"].iter().zip(bands.iter()) {
+            let (top, bottom, band_left, band_right) = *band;
+            let mid = (top + bottom) / 2; // 轨道中心行
+            let (left, right) = (band_left, band_right);
+            let width = right - left + 1;
+            let handle_centre = left + 2 + (width - 4) / 2; // 位移区间 = handle/2 .. W-handle/2
+            let boundary = (left..=right)
+                .find(|x| matches(shot.at(*x, mid), inactive))
+                .unwrap_or(right + 1);
+            match *label {
+                "0%" => assert!(
+                    boundary <= left + 4,
+                    "11.x 0% 时未激活轨必须从竖条（4 宽）之后立刻开始：实测分界 {}",
+                    boundary - left
+                ),
+                "50%" => assert!(
+                    boundary.abs_diff(handle_centre) <= 2,
+                    "11.x 50% 的轨道分界应在正中（{handle_centre}）：实测 {boundary}"
+                ),
+                _ => {
+                    let tail = shot.count_in(inactive, left, right + 1, mid, mid + 1);
+                    assert_eq!(tail, 0, "11.x 100% 时不该有未激活段：实测 {tail}px");
+                }
+            }
+
+            // 竖条必须落在轨道内（0% / 100% 的最狠情形）
+            let handles: Vec<BBox> = shot
+                .bbox_of(active, 100)
+                .into_iter()
+                .filter(|b| b.width() == 4 && b.height() >= 40)
+                .collect();
+            assert!(!handles.is_empty(), "11.2 找不到 4×44 的竖条");
+            for handle in handles {
+                assert!(
+                    handle.left >= left && handle.right <= right,
+                    "11.4 竖条越界：{handle:?} 不在轨道 {left}..{right} 内"
+                );
+                assert!(
+                    (43..=44).contains(&handle.height()),
+                    "11.2 竖条高必须 44（抗锯齿会吃掉 1 行，实测 {}）",
+                    handle.height()
+                );
+                assert_eq!(handle.width(), 4, "11.2 竖条宽必须 4");
+            }
+        }
+    }
+}
diff --git a/crates/app-iced/src/components/inputs/probe/text.rs b/crates/app-iced/src/components/inputs/probe/text.rs
new file mode 100644
index 0000000..32eb2ca
--- /dev/null
+++ b/crates/app-iced/src/components/inputs/probe/text.rs
@@ -0,0 +1,205 @@
+//! M77 probe · text（从 `probe.rs` 拆出：单文件 ≤400 行，AGENTS.md §3-1）。
+
+use super::*;
+
+/// 9.1 / 9.2：Filled 高 56、宽 320；Filled 指示线 静息 1.0 / 聚焦 2.0 墨量。
+#[test]
+fn text_field_height_width_and_indicator_thickness() {
+    let dir = require_dir!();
+    for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+        let shot = shot(&dir, "text", flavor);
+        let ui = ui(flavor);
+        let surface = rgb(ui.color(Role::Surface));
+        let fill = rgb(ui.color(Role::SurfaceContainerHighest));
+        let line = rgb(ui.color(Role::OnSurfaceVariant));
+        let primary = rgb(ui.color(Role::Primary));
+
+        let mut boxes = shot.bbox_of(fill, 400);
+        boxes.sort_by_key(|b| (b.top, b.left));
+        let wide: Vec<&BBox> = boxes.iter().filter(|b| b.width() >= 280).collect();
+        // 320 宽的有两个 Filled（空 / 有值）；第三格是 Outlined 错误态——它没有容器色，
+        // 所以这里只要求 ≥2，错误态由 `outlined_stroke_and_error_paint` 单独验。
+        assert!(
+            wide.len() >= 2,
+            "{flavor:?}: 至少要有 2 个 320 宽的 Filled 文本字段（实测 {}）",
+            wide.len()
+        );
+
+        // 320 宽那三个 = 「空 / 有值 / 错误」三格；高度必须精确 56
+        for bbox in wide.iter().take(2) {
+            assert!(
+                (280..=320).contains(&bbox.width()),
+                "9.2 最小宽 280：实测 {}（320 宽格）",
+                bbox.width()
+            );
+            let column = bbox.right - 20;
+            let (top, bottom) = vertical_extent(&shot, bbox, fill, surface, column);
+            assert_eq!(
+                bottom - top + 1,
+                56,
+                "9.1 高度必须精确 56（带浮动标签）：实测 {flavor:?} @x={column}"
+            );
+        }
+
+        // 矩阵第一行（Filled 五态）＝最靠上的 5 个 160 宽格：列序 = Interaction::ALL
+        // 五态里 disabled 的容器是 `OnSurface@12%`（另一种颜色），所以这里只有 4 块：
+        // enabled / hovered / pressed / focused —— 列序与 `Interaction::ALL` 一致。
+        let row: Vec<&BBox> = boxes
+            .iter()
+            .filter(|b| (140..=170).contains(&b.width()))
+            .take(4)
+            .collect();
+        assert_eq!(row.len(), 4, "{flavor:?}: Filled 矩阵应有 4 个同色格");
+        let enabled = row[0];
+        let focused = row[3];
+
+        // 静息指示线 1dp：墨量 ≈ 1.0
+        let enabled_ink = line_ink(
+            &shot,
+            enabled.left + 8,
+            enabled.right - 8,
+            enabled.bottom,
+            enabled.bottom + 4,
+            fill,
+            line,
+        );
+        assert!(
+            (0.6..=1.4).contains(&enabled_ink),
+            "9.4 静息指示线应 1dp：实测墨量 {enabled_ink:.2}"
+        );
+
+        // 聚焦指示线 2dp：墨量 ≈ 2.0（画成 1dp 会掉到 ~1.0）
+        let focused_ink = line_ink(
+            &shot,
+            focused.left + 8,
+            focused.right - 8,
+            focused.bottom,
+            focused.bottom + 5,
+            fill,
+            primary,
+        );
+        assert!(
+            (1.5..=2.5).contains(&focused_ink),
+            "9.4 聚焦指示线应 2dp：实测墨量 {focused_ink:.2}（1dp 会掉到 ≈1.0）"
+        );
+        assert!(
+            focused_ink > enabled_ink + 0.5,
+            "聚焦必须比静息粗一档（{focused_ink:.2} vs {enabled_ink:.2}）"
+        );
+    }
+}
+
+/// 9.4 / 9.7：Outlined 描边 静息 1dp / 聚焦 2dp；错误态线/标签/辅助文本全 `Error`。
+///
+/// 量法：**在某一列的竖线上扫**（不是找同色块）——深色档里 hover 描边的抗锯齿像素也会落进
+/// `Outline` 的容差里，按「最上面的同色块」取会取错行（实测 dark 取到了 hover 那一行）。
+#[test]
+fn outlined_stroke_and_error_paint() {
+    let dir = require_dir!();
+    for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+        let shot = shot(&dir, "text", flavor);
+        let ui = ui(flavor);
+        let surface = rgb(ui.color(Role::Surface));
+        let fill = rgb(ui.color(Role::SurfaceContainerHighest));
+        let outline = rgb(ui.color(Role::Outline));
+        let primary = rgb(ui.color(Role::Primary));
+        let error = rgb(ui.color(Role::Error));
+
+        // 矩阵第一列（enabled）的左缘与行距：列宽 160 + 间距 8 = 168
+        let left = shot
+            .bbox_of(fill, 400)
+            .into_iter()
+            .filter(|b| (140..=170).contains(&b.width()))
+            .min_by_key(|b| (b.top, b.left))
+            .expect("找不到 Filled 矩阵格")
+            .left;
+        let filled_bottom = shot
+            .bbox_of(fill, 400)
+            .into_iter()
+            .filter(|b| (140..=170).contains(&b.width()))
+            .min_by_key(|b| (b.top, b.left))
+            .expect("找不到 Filled 矩阵格")
+            .bottom;
+
+        let column = |index: usize| left + index * 168 + 120;
+
+        // 静息（第 1 列）描边 1dp：在竖线上找第一处比底色更接近 `Outline` 的像素
+        let rest_y = ((filled_bottom + 8)..shot.height)
+            .find(|y| nearer(shot.at(column(0), *y), outline, surface))
+            .expect("竖线上找不到 Outlined 静息描边");
+        let rest_ink = line_ink(
+            &shot,
+            column(0) - 40,
+            column(0) + 40,
+            rest_y.saturating_sub(2),
+            rest_y + 3,
+            surface,
+            outline,
+        );
+        // 描边的墨量随**亚像素相位**在 1.0~1.67 之间浮动（同一 1dp：整行对齐 = 1.0，
+        // 落在半像素上 = 1 行满 + 1 行 0.67）。所以静息只做宽松下限，**宽度差异由比值判**。
+        assert!(
+            (0.8..=1.9).contains(&rest_ink),
+            "9.4 Outlined 静息描边应 1dp（实测墨量 {rest_ink:.2}；2dp 会到 2.0）"
+        );
+
+        // 聚焦（第 4 列）描边 2dp
+        let focus_y = ((filled_bottom + 8)..shot.height)
+            .find(|y| nearer(shot.at(column(3), *y), primary, surface))
+            .expect("竖线上找不到 Outlined 聚焦描边");
+        let focus_ink = line_ink(
+            &shot,
+            column(3) - 40,
+            column(3) + 40,
+            focus_y.saturating_sub(2),
+            focus_y + 4,
+            surface,
+            primary,
+        );
+        assert!(
+            (1.8..=2.3).contains(&focus_ink),
+            "9.4 Outlined 聚焦描边应 2dp（实测墨量 {focus_ink:.2}；1dp 会掉到 1.67）"
+        );
+        let ratio = focus_ink / rest_ink;
+        assert!(
+            (1.6..=2.5).contains(&ratio),
+            "聚焦必须正好粗一倍（2dp/1dp）：实测比值 {ratio:.2}（{focus_ink:.2} vs {rest_ink:.2}）"
+        );
+
+        // 9.7：错误格——描边 2dp + 标签（框内上带）+ 辅助文本（框下）全 `Error`
+        let error_box = shot
+            .bbox_of(error, 2000)
+            .into_iter()
+            .filter(|b| b.width() >= 280)
+            .max_by_key(|b| b.width())
+            .expect("找不到错误态字段");
+        assert!(
+            error_box.height() >= 50,
+            "错误格应是一整个 320 宽的字段（实测 {}×{}）",
+            error_box.width(),
+            error_box.height()
+        );
+        let label_ink = shot.count_in(
+            error,
+            error_box.left,
+            error_box.right + 1,
+            error_box.top + 2,
+            error_box.top + 22,
+        );
+        let supporting_ink = shot.count_in(
+            error,
+            error_box.left,
+            error_box.right + 1,
+            error_box.bottom + 1,
+            error_box.bottom + 30,
+        );
+        assert!(
+            label_ink > 20,
+            "9.7 错误标签没变成 Error（框内上带墨迹 {label_ink}px）"
+        );
+        assert!(
+            supporting_ink > 20,
+            "9.7 错误辅助文本没变成 Error（框下墨迹 {supporting_ink}px）"
+        );
+    }
+}
diff --git a/crates/app-iced/src/components/inputs/search.rs b/crates/app-iced/src/components/inputs/search.rs
new file mode 100644
index 0000000..3d99951
--- /dev/null
+++ b/crates/app-iced/src/components/inputs/search.rs
@@ -0,0 +1,353 @@
+//! 搜索（`research/15` §20）：官方是**两个组件**——[`search_bar`]（收起）+ [`search_view`]（展开）。
+//!
+//! ## 参考值（`[源]` = A1；本机 `material3-android:1.4.0` 的 `SearchBarTokens` / `SearchBar.kt`）
+//!
+//! | # | 检查项 | 参考值 | 落点 |
+//! |---|---|---|---|
+//! | 20.1 | 高 + 圆角 | 高 **56**、圆角 **full = 28**（药丸，不是圆角矩形） | `LM.search_bar_height` + `Component::Search.spec().shape` |
+//! | 20.2 | 宽 | min **360** / max **720**（G20：iced 无 min-width，只施加 max） | [`SEARCH_MAX_WIDTH`](super::geometry::SEARCH_MAX_WIDTH) |
+//! | 20.3 | 容器色 / 高程 | `SurfaceContainerHigh` + **L0**（token 写 L3，默认值是 L0，按观感取 L0） | `Role::SurfaceContainerHigh` |
+//! | 20.4 | 图标位 | leading 24/`OnSurface`、trailing 24/`OnSurfaceVariant`；**可视边 16 = pad 12 + offset 4** | `ComponentMetrics::SEARCH_BAR` |
+//! | 20.5 | 文本 / 占位 / 聚焦 | 输入 `BodyLarge`+`OnSurface`；占位 `OnSurfaceVariant`；聚焦 `Secondary` 1px 指示 | `TypeRole` / `Role::Secondary` |
+//! | 20.6 | docked 面板 | 头部 **56**、形状 `CornerExtraLarge` = **28** | `ShapeScale::ExtraLarge` |
+//! | 20.8 | 头部 / 结果区分隔 | **1px `Outline`**（**不是** `OutlineVariant`！） | 见下 |
+//! | 20.9 | 面板尺寸 | 顶距 8、最小高 **240**、docked 宽 **360** | §20B |
+//!
+//! ## 三处实现口径
+//!
+//! 1. **图标可视边一律 `pad + icon_offset` 求和**（`SEARCH_BAR.pad_start = 12` + `icon_offset = 4` = 16）。
+//!    M69 把这两个值钉成不变量，本文件**不写 16、也不写 12/4**——只做加法。
+//! 2. `20.8` 的分隔线用 `Role::Outline`，而 `components::divider` 给的是 `OutlineVariant`
+//!    （那是正文分隔线的角色）。两个角色在 A1 里明确不同，所以这里**不复用** `divider`，
+//!    只按一像素线（`stroke::HAIRLINE`）画一条 —— 复用会把 20.8 判成「报 OutlineVariant 即错」。
+//! 3. bar 的 hover / pressed / disabled 在 `SearchBarTokens` 里**没有** token。
+//!    hover/pressed 按通用状态层（`interaction::overlay_color`，8%/10%），disabled 按令牌的
+//!    12%/38%，都登记为 [估]（D14 / D15）；焦点指示用 A1 的 `FocusIndicatorColor = Secondary`。
+
+use iced::widget::text::LineHeight;
+use iced::widget::{column, container, row, text, text_input};
+use iced::{Alignment, Background, Border, Color, Element, Length, Padding, Pixels};
+
+use unlucky_design::color::Role;
+use unlucky_design::component_map::{Component, ComponentMetrics};
+use unlucky_design::icons::IconKind;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use crate::icons;
+use crate::theme::{Ui, STROKE_PX};
+
+use super::super::interaction::{self, Interaction};
+use super::super::layout;
+use super::geometry::{SEARCH_MAX_WIDTH, SEARCH_MIN_WIDTH, SEARCH_VIEW_MIN_HEIGHT};
+
+/// 搜索条（收起形态）。
+///
+/// 状态矩阵用 [`SearchBar::state`] 强制；运行期五态由 `Tracker`/`text_input` 的真实事件驱动。
+#[derive(Debug, Clone)]
+pub struct SearchBar<'a> {
+    value: &'a str,
+    placeholder: &'a str,
+    trailing: Option<IconKind>,
+    state: Option<Interaction>,
+    width: Length,
+}
+
+impl<'a> SearchBar<'a> {
+    /// 一条收起态搜索条（默认占位文案由页面给，组件内不拼中文）。
+    pub fn new(value: &'a str) -> Self {
+        Self {
+            value,
+            placeholder: "",
+            trailing: Some(IconKind::Filter),
+            state: None,
+            width: Length::Fill,
+        }
+    }
+
+    /// 占位文案。
+    pub fn placeholder(mut self, placeholder: &'a str) -> Self {
+        self.placeholder = placeholder;
+        self
+    }
+
+    /// 强制视觉态（gallery 取证）。
+    pub fn state(mut self, state: Interaction) -> Self {
+        self.state = Some(state);
+        self
+    }
+
+    /// 定宽（默认 `Fill`）。
+    pub fn width(mut self, width: Length) -> Self {
+        self.width = width;
+        self
+    }
+}
+
+/// 搜索条内的一行内容（bar 与 view 头部共用，保证「展开时头部不跳」——20.6）。
+#[allow(clippy::too_many_arguments)]
+fn bar_content<'a, M: Clone + 'a>(
+    ui: &'a Ui,
+    value: &'a str,
+    placeholder: &'a str,
+    trailing: Option<IconKind>,
+    state: Interaction,
+    on_input: impl Fn(String) -> M + 'a,
+) -> Element<'a, M> {
+    // 20.4：可视边 = pad + offset（**求和**，不抄 16）
+    let bar: ComponentMetrics = Component::Search.metrics().expect("Search 有组件级度量");
+    // 20.4：图标**可视边** = pad + offset（M69 不变量）。这里反解出偏移，两侧共用同一个量。
+    let icon_edge = bar.pad_start + bar.icon_offset;
+    let icon_offset = icon_edge - bar.pad_start;
+
+    let ink = if state.is_disabled() {
+        interaction::disabled_content_over_role(ui, Role::OnSurface, true)
+    } else {
+        ui.color(Role::OnSurface)
+    };
+    let subtle = if state.is_disabled() {
+        ink
+    } else {
+        ui.color(Role::OnSurfaceVariant)
+    };
+
+    let body_style = ui.style(TypeRole::BodyLarge);
+    let input = text_input(placeholder, value)
+        .on_input_maybe(if state.is_disabled() {
+            None
+        } else {
+            Some(on_input)
+        })
+        .size(body_style.size_px)
+        .line_height(LineHeight::Absolute(Pixels(body_style.line_height_px)))
+        .font(ui.font_of(body_style))
+        .padding(Padding::default())
+        .width(Length::Fill)
+        .style(move |_theme, _status| text_input::Style {
+            background: Background::Color(Color::TRANSPARENT),
+            border: Border::default(),
+            icon: subtle,
+            placeholder: subtle,
+            value: ink,
+            selection: ink,
+        });
+
+    // 前置图标：左边 = pad（容器内边距 12）+ offset（4）= 16。两层分别来自令牌的两个字段。
+    let leading = container(layout::fixed(
+        bar.icon,
+        bar.icon,
+        icons::view::<M>(IconKind::Search, ink),
+    ))
+    .padding(Padding {
+        top: 0.0,
+        right: 0.0,
+        bottom: 0.0,
+        left: icon_offset,
+    });
+
+    let mut contents = row![leading, input]
+        .align_y(Alignment::Center)
+        .spacing(bar.gap);
+
+    if let Some(kind) = trailing {
+        // 尾随图标：右边 = pad_end + offset（镜像同式），所以右缘也在 16 上
+        let trailing = container(layout::fixed(
+            bar.icon,
+            bar.icon,
+            icons::view::<M>(kind, subtle),
+        ))
+        .padding(Padding {
+            top: 0.0,
+            right: icon_offset,
+            bottom: 0.0,
+            left: 0.0,
+        });
+        contents = contents.push(trailing);
+    }
+
+    container(contents)
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .align_y(Alignment::Center)
+        .padding(Padding {
+            top: 0.0,
+            right: bar.pad_end,
+            bottom: 0.0,
+            left: bar.pad_start,
+        })
+        .into()
+}
+
+/// 收起态搜索条（56 高、药丸、`SurfaceContainerHigh`、无可见阴影）。
+pub fn search_bar<'a, M: Clone + 'a>(
+    ui: &'a Ui,
+    bar: SearchBar<'a>,
+    on_input: impl Fn(String) -> M + 'a,
+) -> Element<'a, M> {
+    let state = bar.state.unwrap_or(Interaction::Enabled);
+    let component = Component::Search.spec();
+    let height = ui.metrics().search_bar_height;
+
+    let background = if state.is_disabled() {
+        interaction::disabled_colors(ui, Role::Surface).0
+    } else {
+        let role = Role::SurfaceContainerHigh;
+        interaction::overlay_color(ui, state, Role::OnSurface, role).unwrap_or(ui.color(role))
+    };
+
+    // 20.5：聚焦指示 = 1px `Secondary`（A1 的 token 存在但 Compose 未消费 → 标 [规格]）
+    let focus_ring = matches!(state, Interaction::Focused);
+    let border = Border {
+        color: if focus_ring {
+            ui.color(Role::Secondary)
+        } else {
+            Color::TRANSPARENT
+        },
+        width: if focus_ring { STROKE_PX } else { 0.0 },
+        radius: ui.radius(component.shape, height),
+    };
+
+    container(bar_content(
+        ui,
+        bar.value,
+        bar.placeholder,
+        bar.trailing,
+        state,
+        on_input,
+    ))
+    .width(bar.width)
+    // 20.2：max **720**（`SearchBarMaxWidth`）。min 360 无法在 iced 表达（G20），由页面保证列宽。
+    .max_width(SEARCH_MAX_WIDTH)
+    .height(Length::Fixed(height))
+    .style(move |_theme| container::Style {
+        background: Some(Background::Color(background)),
+        border,
+        ..container::Style::default()
+    })
+    .into()
+}
+
+/// 展开态搜索面板（docked 形态：桌面 1180 窗口永远用它，`20C` 的结论）。
+///
+/// 形状：头部 56（半径 28）+ 1px `Outline` 分隔 + 结果区（最小 240）。
+#[derive(Debug, Clone)]
+pub struct SearchView<'a> {
+    value: &'a str,
+    placeholder: &'a str,
+    empty: &'a str,
+    results: &'a [&'a str],
+    width: f32,
+}
+
+impl<'a> SearchView<'a> {
+    /// 一个展开面板（`empty` = 空结果文案，由页面给 i18n 文本）。
+    pub fn new(value: &'a str, results: &'a [&'a str], empty: &'a str) -> Self {
+        Self {
+            value,
+            placeholder: "",
+            empty,
+            results,
+            width: SEARCH_MIN_WIDTH,
+        }
+    }
+
+    /// 占位文案。
+    pub fn placeholder(mut self, placeholder: &'a str) -> Self {
+        self.placeholder = placeholder;
+        self
+    }
+}
+
+/// 展开态搜索面板。
+pub fn search_view<'a, M: Clone + 'a>(
+    ui: &'a Ui,
+    view: SearchView<'a>,
+    on_input: impl Fn(String) -> M + 'a,
+) -> Element<'a, M> {
+    let panel = ui.color(Role::SurfaceContainerHigh);
+    let header_height = ui.metrics().search_bar_height;
+    let body_style = ui.style(TypeRole::BodyMedium);
+
+    // 20.8：头部/结果区分隔是 **`Outline`**（正文分隔线才是 OutlineVariant）
+    let divider = container(iced::widget::space::horizontal())
+        .width(Length::Fill)
+        .height(Length::Fixed(STROKE_PX))
+        .style(move |_theme| container::Style {
+            background: Some(Background::Color(ui.color(Role::Outline))),
+            ..container::Style::default()
+        });
+
+    let mut rows = column![].width(Length::Fill).spacing(0);
+    for result in view.results {
+        rows = rows.push(
+            container(
+                text(*result)
+                    .size(body_style.size_px)
+                    .font(ui.font_of(body_style))
+                    .color(ui.color(Role::OnSurface)),
+            )
+            .width(Length::Fill)
+            .padding(Padding {
+                top: ui.space(Space::X2),
+                right: ui.space(Space::X4),
+                bottom: ui.space(Space::X2),
+                left: ui.space(Space::X4),
+            }),
+        );
+    }
+    if view.results.is_empty() {
+        let small = ui.style(TypeRole::BodySmall);
+        rows = rows.push(
+            container(
+                text(view.empty)
+                    .size(small.size_px)
+                    .font(ui.font_of(small))
+                    .color(ui.color(Role::OnSurfaceVariant)),
+            )
+            .width(Length::Fill)
+            .padding(Padding {
+                top: ui.space(Space::X4),
+                right: ui.space(Space::X4),
+                bottom: ui.space(Space::X4),
+                left: ui.space(Space::X4),
+            }),
+        );
+    }
+
+    let body = container(rows)
+        .width(Length::Fill)
+        .height(Length::Fixed(SEARCH_VIEW_MIN_HEIGHT))
+        .align_y(Alignment::Start);
+
+    let panel_content = column![
+        container(bar_content(
+            ui,
+            view.value,
+            view.placeholder,
+            Some(IconKind::Close),
+            Interaction::Enabled,
+            on_input,
+        ))
+        .width(Length::Fill)
+        .height(Length::Fixed(header_height)),
+        divider,
+        body,
+    ];
+
+    container(panel_content)
+        .width(Length::Fixed(view.width))
+        .style(move |_theme| container::Style {
+            background: Some(Background::Color(panel)),
+            // 20.6：docked 面板 = CornerExtraLarge（28）；bar ⇄ view 半径不变（§20C）
+            border: Border {
+                radius: ui.radius_dp(ShapeScale::ExtraLarge),
+                ..Border::default()
+            },
+            ..container::Style::default()
+        })
+        .into()
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/app-iced/src/components/inputs/search/tests.rs b/crates/app-iced/src/components/inputs/search/tests.rs
new file mode 100644
index 0000000..b635884
--- /dev/null
+++ b/crates/app-iced/src/components/inputs/search/tests.rs
@@ -0,0 +1,93 @@
+//! search 的单测（从 `search.rs` 拆出：单文件 ≤400 行，AGENTS.md §3-1）。
+
+use super::*;
+use unlucky_design::color::SchemeFlavor;
+use unlucky_design::typography::Platform;
+
+use crate::theme::Families;
+
+const FAMILIES: Families = Families {
+    text: "Segoe UI",
+    display: "Segoe UI",
+    mono: "Consolas",
+};
+
+fn ui(flavor: SchemeFlavor) -> Ui {
+    Ui::with_platform(flavor, Platform::Windows, FAMILIES)
+}
+
+fn leaked(flavor: SchemeFlavor) -> &'static Ui {
+    Box::leak(Box::new(ui(flavor)))
+}
+
+/// **M69 不变量**：图标可视边 = pad + offset（12 + 4 = 16），且本实现只做加法。
+#[test]
+fn icon_edge_is_pad_plus_offset_not_a_literal() {
+    let bar = Component::Search.metrics().expect("Search 有组件级度量");
+    assert_eq!(bar.pad_start, 12.0, "M69 钉住的 pad_start");
+    assert_eq!(bar.icon_offset, 4.0, "M69 钉住的 icon_offset");
+    assert_eq!(bar.pad_start + bar.icon_offset, 16.0);
+    assert_eq!(bar.icon, 24.0, "SearchBarTokens 图标 24");
+    // 文本从 pad（12）起：图标（16..40）+ gap 8 → 48 是文字的实际起点
+    assert_eq!(
+        bar.pad_start + bar.icon_offset + bar.icon + bar.gap,
+        48.0,
+        "图标槽 + 间距后文字起点 48"
+    );
+}
+
+/// 20.1：高 56、圆角 full = 28（药丸）；条高来自 LM，不重复定义。
+#[test]
+fn bar_height_and_radius_come_from_tokens() {
+    let ui = ui(SchemeFlavor::Light);
+    assert_eq!(ui.metrics().search_bar_height, 56.0);
+    assert_eq!(
+        ShapeScale::Full.radius_px(ui.metrics().search_bar_height),
+        28.0,
+        "SearchBarCornerRadius = InputFieldHeight / 2"
+    );
+    assert_eq!(Component::Search.spec().shape, ShapeScale::Full);
+    // 高程按观感取 L0（无可见阴影）
+    assert_eq!(
+        Component::Search.spec().elevation,
+        unlucky_design::elevation::Elevation::Level0
+    );
+}
+
+/// 20.6 / 20.9：面板头部 56、形状 ExtraLarge(28)、最小高 240、docked 宽 360。
+#[test]
+fn docked_panel_geometry() {
+    let ui = ui(SchemeFlavor::Light);
+    assert_eq!(ShapeScale::ExtraLarge.dp(), 28.0, "DockedContainerShape");
+    assert_eq!(
+        SEARCH_VIEW_MIN_HEIGHT, 240.0,
+        "DockedExpandedTableMinHeight"
+    );
+    assert_eq!(SEARCH_MIN_WIDTH, 360.0, "SearchBarMinWidth = docked 面板宽");
+    assert_eq!(ui.metrics().search_bar_height, 56.0, "头部与 bar 同高");
+}
+
+/// bar 与 view 都能构建（含禁用态：输入被摘掉）。
+#[test]
+fn both_forms_build() {
+    for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+        for state in Interaction::ALL {
+            let ui = leaked(flavor);
+            let bar = SearchBar::new("").placeholder("搜索").state(state);
+            let _: Element<'_, u8> = search_bar(ui, bar, |_| 0_u8);
+
+            let results: &[&str] = &["实例一", "1.21.4"];
+            let view = SearchView::new("实例", results, "没有结果").placeholder("搜索");
+            let _: Element<'_, u8> = search_view(ui, view, |_| 0_u8);
+        }
+    }
+}
+
+/// 空结果也必须给面板内容（20C：不许收回到 bar）。
+#[test]
+fn empty_results_still_render_a_panel() {
+    let ui = leaked(SchemeFlavor::Light);
+    let empty: &[&str] = &[];
+    let view = SearchView::new("xyz", empty, "没有结果");
+    let _: Element<'_, u8> = search_view(ui, view, |_| 0_u8);
+}
diff --git a/crates/app-iced/src/components/inputs/slider.rs b/crates/app-iced/src/components/inputs/slider.rs
new file mode 100644
index 0000000..91449a2
--- /dev/null
+++ b/crates/app-iced/src/components/inputs/slider.rs
@@ -0,0 +1,396 @@
+//! 滑块（`research/12b` §11，A1）：**自绘 `Widget`**——M3 Expressive 的滑块是「竖条」，不是圆点。
+//!
+//! ## 参考值（`[源]` = A1，`SliderTokens`）
+//!
+//! | # | 检查项 | 参考值 | 落点 |
+//! |---|---|---|---|
+//! | 11.1 | 轨道高 | **16**，圆角 full（= 8） | `TRACK_HEIGHT`（G18） |
+//! | 11.2 | handle 形态 | **4 宽 × 44 高**，圆角 full；focus / pressed 收窄到 **2** | `HANDLE_WIDTH` / `HANDLE_HEIGHT` |
+//! | 11.3 | 颜色 | 激活轨 `Primary`、未激活轨 `SecondaryContainer`、handle `Primary` | `Role::*` |
+//! | 11.4 | handle 与轨道 | 纵向溢出：上下各 **14**（(44−16)/2） | 推导 |
+//! | 11.5 | 命中高度 | **48**（`LM.touch_target`；竖条 44 + 上下各 2） | `SliderGeometry::height` |
+//! | 11.6 | 禁用 | 激活轨 `OnSurface`@**38%**、未激活 @**12%**、handle @**38%** | `interaction::*` |
+//! | — | 离散停靠点 | **4** 圆点 `SecondaryContainer`（`StopIndicatorSize`）；尾随间距 6 | [`Slider::steps`] |
+//!
+//! ## 为什么必须自绘
+//!
+//! iced 内置 `slider` 只能画「轨道 + 圆形/矩形 handle（高度 = 控件高）」，
+//! **没有停靠点、没有禁用态、无法强制取证态**；而 §11.2 的 4×44 竖条要求 handle 高（44）
+//! 与轨道高（16）分离。所以这里用 `advanced::Widget` 自绘：布局只有「宽 × 48」一个原子，
+//! 轨道/激活段/停靠点/竖条全部用 `fill_quad` 画进同一个 bounds——几何因此在像素级可断言。
+//!
+//! ## 状态层（[估]，登记 D16）
+//!
+//! `SliderTokens` **没有**状态层直径（M3 Expressive 去掉了旧版的水滴 halo），hover/pressed 只体现为
+//! handle 宽度与颜色。为了让五态在验收图上可辨且 α 只认令牌，这里把**通用状态层**
+//! （`interaction::overlay_color`：hover 8% / focus 10% / pressed 10%）叠在 handle 上，
+//! 宽度仍按 A1 收窄——两件事都来自令牌，没有新数值。
+//!
+//! ## 拖动
+//!
+//! `on_change` 有值就启用拖动与点击跳转；`None` = 禁用（也不吃事件）。
+//! 值由外部持有（受控组件），拖动只 `publish` 新比例：组件不持有业务状态（契约 §2）。
+
+use iced::advanced::layout::{self, Layout};
+use iced::advanced::renderer::Quad;
+use iced::advanced::widget::{tree, Tree};
+use iced::advanced::{mouse, Clipboard, Shell, Widget};
+use iced::{Background, Border, Color, Element, Event, Length, Rectangle, Size};
+
+use unlucky_design::color::Role;
+
+use crate::theme::Ui;
+
+use super::super::interaction::{self, Interaction, Tracker};
+use super::geometry::{SliderGeometry, HANDLE_HEIGHT, HANDLE_WIDTH_ACTIVE, STOP_GAP, STOP_SIZE};
+
+mod track;
+
+pub use track::TrackGeometry;
+
+use track::{fraction_at, quantize, EPSILON};
+
+/// 一个滑块（受控：`fraction` 由外部给，变化经 `on_change` 回传）。
+pub struct Slider<'a, M> {
+    ui: &'a Ui,
+    fraction: f32,
+    steps: Option<u32>,
+    on_change: Option<Box<dyn Fn(f32) -> M + 'a>>,
+    forced: Option<Interaction>,
+}
+
+impl<'a, M> Slider<'a, M> {
+    /// 连续值滑块（0.0 ~= 1.0）。
+    pub fn new(ui: &'a Ui, fraction: f32) -> Self {
+        Self {
+            ui,
+            fraction: fraction.clamp(0.0, 1.0),
+            steps: None,
+            on_change: None,
+            forced: None,
+        }
+    }
+
+    /// 离散值：`steps` = 分段数（4 → 5 个停靠点 0 / 25 / 50 / 75 / 100%）。
+    pub fn steps(mut self, steps: u32) -> Self {
+        self.steps = Some(steps.max(1));
+        self.fraction = quantize(self.fraction, self.steps);
+        self
+    }
+
+    /// 值变化回调；不给 = 禁用。
+    pub fn on_change(mut self, on_change: impl Fn(f32) -> M + 'a) -> Self {
+        self.on_change = Some(Box::new(on_change));
+        self
+    }
+
+    /// 强制视觉态（gallery 状态矩阵取证）。
+    pub fn state(mut self, state: Interaction) -> Self {
+        self.forced = Some(state);
+        self
+    }
+
+    /// 当前比例（量化后）。
+    fn value(&self) -> f32 {
+        quantize(self.fraction, self.steps)
+    }
+
+    /// 禁用与否：没有回调就是禁用（与按钮 `on_press: Option<M>` 同一口径）。
+    fn enabled(&self) -> bool {
+        self.on_change.is_some() && !matches!(self.forced, Some(Interaction::Disabled))
+    }
+}
+
+/// `Widget` 的状态：五态状态机（[`Tracker`]）+ 是否正在拖动。
+#[derive(Debug, Default)]
+struct State {
+    tracker: Tracker,
+    dragging: bool,
+}
+
+/// 一个圆角实心块（轨道的所有部件都是它）。
+fn quad(bounds: Rectangle, radius: f32, color: Color) -> (Quad, Background) {
+    (
+        Quad {
+            bounds,
+            border: Border {
+                radius: radius.into(),
+                ..Border::default()
+            },
+            ..Quad::default()
+        },
+        Background::Color(color),
+    )
+}
+
+impl<'a, M, Theme, Renderer> Widget<M, Theme, Renderer> for Slider<'a, M>
+where
+    M: Clone,
+    Renderer: iced::advanced::Renderer,
+{
+    fn size(&self) -> Size<Length> {
+        Size {
+            width: Length::Fill,
+            height: Length::Fixed(SliderGeometry::of(self.ui).height),
+        }
+    }
+
+    fn tag(&self) -> tree::Tag {
+        tree::Tag::of::<State>()
+    }
+
+    fn state(&self) -> tree::State {
+        tree::State::new(State {
+            tracker: Tracker::new(self.enabled()),
+            dragging: false,
+        })
+    }
+
+    fn layout(
+        &mut self,
+        _tree: &mut Tree,
+        _renderer: &Renderer,
+        limits: &layout::Limits,
+    ) -> layout::Node {
+        layout::atomic(
+            limits,
+            Length::Fill,
+            Length::Fixed(SliderGeometry::of(self.ui).height),
+        )
+    }
+
+    fn update(
+        &mut self,
+        tree: &mut Tree,
+        event: &Event,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        _renderer: &Renderer,
+        _clipboard: &mut dyn Clipboard,
+        shell: &mut Shell<'_, M>,
+        _viewport: &Rectangle,
+    ) {
+        if self.forced.is_some() {
+            return;
+        }
+
+        let enabled = self.enabled();
+        let geometry = SliderGeometry::of(self.ui);
+        let bounds = layout.bounds();
+        let state = tree.state.downcast_mut::<State>();
+        if state.tracker.set_enabled(enabled) {
+            shell.request_redraw();
+        }
+
+        let mut target: Option<f32> = None;
+        match event {
+            Event::Mouse(mouse::Event::ButtonPressed(mouse::Button::Left))
+                if enabled && cursor.is_over(bounds) =>
+            {
+                if let Some(position) = cursor.position() {
+                    state.dragging = true;
+                    target = Some(fraction_at(bounds, position.x, geometry.handle));
+                    shell.capture_event();
+                }
+            }
+            Event::Mouse(mouse::Event::CursorMoved { .. }) if state.dragging => {
+                if let Some(position) = cursor.position() {
+                    target = Some(fraction_at(bounds, position.x, geometry.handle));
+                    shell.capture_event();
+                }
+            }
+            Event::Mouse(mouse::Event::ButtonReleased(mouse::Button::Left)) => {
+                state.dragging = false;
+            }
+            _ => {}
+        }
+
+        if let Some(fraction) = target {
+            let next = quantize(fraction, self.steps);
+            if (next - self.value()).abs() >= EPSILON {
+                if let Some(on_change) = &self.on_change {
+                    self.fraction = next;
+                    shell.publish(on_change(next));
+                }
+            }
+        }
+
+        if state.tracker.event(event, cursor.is_over(bounds)) {
+            shell.request_redraw();
+        }
+    }
+
+    fn draw(
+        &self,
+        tree: &Tree,
+        renderer: &mut Renderer,
+        _theme: &Theme,
+        _style: &iced::advanced::renderer::Style,
+        layout: Layout<'_>,
+        _cursor: mouse::Cursor,
+        _viewport: &Rectangle,
+    ) {
+        let ui = self.ui;
+        let geometry = SliderGeometry::of(ui);
+        let bounds = layout.bounds();
+        let state = self
+            .forced
+            .unwrap_or_else(|| tree.state.downcast_ref::<State>().tracker.state());
+        let disabled = state.is_disabled();
+
+        let (active_color, inactive_color, handle_color, handle_width) = if disabled {
+            (
+                interaction::disabled_content_over_role(ui, Role::OnSurface, false),
+                interaction::disabled_colors(ui, Role::Surface).0,
+                interaction::disabled_content_over_role(ui, Role::OnSurface, false),
+                geometry.handle,
+            )
+        } else {
+            // 状态层只叠在 handle 上（D16）：α 全部来自 interaction（hover 8 / focus 10 / pressed 10）
+            let handle_color =
+                interaction::overlay_color(ui, state, Role::OnSurface, Role::Primary)
+                    .unwrap_or_else(|| ui.color(Role::Primary));
+            let handle_width = match state {
+                Interaction::Focused | Interaction::Pressed => HANDLE_WIDTH_ACTIVE,
+                _ => geometry.handle,
+            };
+            (
+                ui.color(Role::Primary),
+                ui.color(Role::SecondaryContainer),
+                handle_color,
+                handle_width,
+            )
+        };
+
+        let centre_y = bounds.y + bounds.height / 2.0;
+        let track_x = bounds.x;
+        let track_w = bounds.width;
+        let track = TrackGeometry::of(bounds, self.value());
+        let centre_x = track.handle_centre();
+        let track_rect = |x: f32, width: f32| Rectangle {
+            x,
+            y: centre_y - geometry.track / 2.0,
+            width: width.max(0.0),
+            height: geometry.track,
+        };
+
+        // 离散停靠点：A1 的 `StopIndicatorColor = SecondaryContainer` 与未激活轨**同色**，
+        // 所以停靠点只有在「未激活轨在它两侧留出空隙」时才读得出来（官方也是这么画的：
+        // `StopIndicatorSize = 4` + `StopIndicatorTrailingSpace = 6`）。空隙两侧各留半个点 + 6。
+        // **不含两端**：0% 与 100% 上不画停靠点（那是轨道自己的圆角端，官方也不画）
+        let stops: Vec<f32> = match self.steps {
+            Some(steps) if steps >= 2 => (1..steps)
+                .map(|index| TrackGeometry::of(bounds, index as f32 / steps as f32).handle_centre())
+                .collect(),
+            _ => Vec::new(),
+        };
+        let gap = STOP_SIZE / 2.0 + STOP_GAP;
+
+        // 未激活轨：从**竖条中心**到右端，按停靠点切成段（每段自己圆角，端点读数更清楚）
+        let mut cursor = centre_x;
+        let mut segments: Vec<(f32, f32)> = Vec::new();
+        for anchor in stops.iter().copied() {
+            if anchor <= cursor {
+                continue;
+            }
+            segments.push((cursor, anchor - gap - cursor));
+            cursor = anchor + gap;
+        }
+        if track_x + track_w > cursor {
+            segments.push((cursor, track_x + track_w - cursor));
+        }
+        for (x, width) in segments {
+            if width <= 0.0 {
+                continue;
+            }
+            let (inactive, inactive_bg) =
+                quad(track_rect(x, width), geometry.track / 2.0, inactive_color);
+            renderer.fill_quad(inactive, inactive_bg);
+        }
+
+        // 激活轨：从容器左缘到**竖条中心**（与官方一致：激活段托在竖条下面）
+        let active_w = track.active_width;
+        if active_w > 0.0 {
+            let (active, active_bg) = quad(
+                track_rect(track_x, active_w),
+                geometry.track / 2.0,
+                active_color,
+            );
+            renderer.fill_quad(active, active_bg);
+        }
+
+        // 停靠点本体：4dp 圆点，只画在**未激活侧**（激活段已经走过的不重复画）
+        if !disabled {
+            for anchor in stops
+                .iter()
+                .copied()
+                .filter(|anchor| *anchor > centre_x + EPSILON)
+            {
+                let (stop, stop_bg) = quad(
+                    Rectangle {
+                        x: anchor - STOP_SIZE / 2.0,
+                        y: centre_y - STOP_SIZE / 2.0,
+                        width: STOP_SIZE,
+                        height: STOP_SIZE,
+                    },
+                    STOP_SIZE / 2.0,
+                    inactive_color,
+                );
+                renderer.fill_quad(stop, stop_bg);
+            }
+        }
+
+        // 竖条：4×44（focus / pressed 收窄到 2），圆角 full
+        let (bar, bar_bg) = quad(
+            Rectangle {
+                x: track.handle_centre() - handle_width / 2.0,
+                y: centre_y - HANDLE_HEIGHT / 2.0,
+                width: handle_width,
+                height: HANDLE_HEIGHT,
+            },
+            handle_width / 2.0,
+            handle_color,
+        );
+        renderer.fill_quad(bar, bar_bg);
+    }
+
+    fn mouse_interaction(
+        &self,
+        tree: &Tree,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        _viewport: &Rectangle,
+        _renderer: &Renderer,
+    ) -> mouse::Interaction {
+        if !self.enabled() {
+            return mouse::Interaction::None;
+        }
+        if tree.state.downcast_ref::<State>().dragging {
+            return mouse::Interaction::Grabbing;
+        }
+        if cursor.is_over(layout.bounds()) {
+            mouse::Interaction::Grab
+        } else {
+            mouse::Interaction::None
+        }
+    }
+}
+
+impl<'a, M, Theme, Renderer> From<Slider<'a, M>> for Element<'a, M, Theme, Renderer>
+where
+    M: Clone + 'a,
+    Theme: 'a,
+    Renderer: iced::advanced::Renderer + 'a,
+{
+    fn from(slider: Slider<'a, M>) -> Self {
+        Element::new(slider)
+    }
+}
+
+/// 便捷入口：把 [`Slider`] 直接变成 `Element`（与其它组件的函数式签名一致）。
+pub fn slider<'a, M: Clone + 'a>(spec: Slider<'a, M>) -> Element<'a, M> {
+    Element::new(spec)
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/app-iced/src/components/inputs/slider/tests.rs b/crates/app-iced/src/components/inputs/slider/tests.rs
new file mode 100644
index 0000000..482868d
--- /dev/null
+++ b/crates/app-iced/src/components/inputs/slider/tests.rs
@@ -0,0 +1,122 @@
+//! slider 的单测（从 `slider.rs` 拆出：单文件 ≤400 行，AGENTS.md §3-1）。
+
+use super::*;
+use unlucky_design::color::SchemeFlavor;
+use unlucky_design::typography::Platform;
+
+use crate::theme::Families;
+
+const FAMILIES: Families = Families {
+    text: "Segoe UI",
+    display: "Segoe UI",
+    mono: "Consolas",
+};
+
+fn ui() -> Ui {
+    Ui::with_platform(SchemeFlavor::Light, Platform::Windows, FAMILIES)
+}
+
+fn track() -> Rectangle {
+    Rectangle {
+        x: 100.0,
+        y: 200.0,
+        width: 300.0,
+        height: 48.0,
+    }
+}
+
+/// 11.1 / 11.2 / 11.4：轨道 16、竖条 4×44、上下各溢出 14。
+#[test]
+fn track_and_handle_are_the_m3_expressive_shapes() {
+    let g = SliderGeometry::of(&ui());
+    assert_eq!(g.track, 16.0);
+    assert_eq!((g.handle, g.handle_tall), (4.0, 44.0));
+    assert_eq!((g.handle_tall - g.track) / 2.0, 14.0);
+    assert_eq!(g.stop, 4.0);
+    assert_eq!(g.height, 48.0, "命中区 = LM.touch_target");
+}
+
+/// 0% / 50% / 100% 三档的位置：竖条**永不越界**，激活段与轨道分界一致。
+#[test]
+fn thumb_stays_inside_the_track_at_both_ends() {
+    let bounds = track();
+    let zero = TrackGeometry::of(bounds, 0.0);
+    assert_eq!(zero.handle_left, bounds.x, "0% 时竖条左缘 = 轨道左缘");
+    assert!(zero.handle_left >= bounds.x);
+    assert_eq!(zero.active_width, 2.0, "0% 时激活段只剩竖条半宽");
+
+    let half = TrackGeometry::of(bounds, 0.5);
+    assert!((half.handle_left - (bounds.x + bounds.width / 2.0 - 2.0)).abs() < 0.01);
+
+    let full = TrackGeometry::of(bounds, 1.0);
+    assert_eq!(
+        full.handle_right,
+        bounds.x + bounds.width,
+        "100% 时右缘贴轨道右缘"
+    );
+    assert!(full.handle_right <= bounds.x + bounds.width);
+    // 激活段画到**竖条中心**为止（= 右缘 − 2），不是画到右缘：100% 时也被竖条自己盖住
+    assert_eq!(full.active_width, bounds.width - 2.0);
+}
+
+/// 越界的比例（<0 或 >1）被 clamp，不会把竖条推到轨道外。
+#[test]
+fn out_of_range_fractions_are_clamped() {
+    let bounds = track();
+    for fraction in [-3.0, -0.01, 0.0, 1.0, 1.5, 9.0] {
+        let geometry = TrackGeometry::of(bounds, fraction);
+        assert!(
+            geometry.handle_left >= bounds.x,
+            "{fraction} 的竖条左缘越界：{}",
+            geometry.handle_left
+        );
+        assert!(
+            geometry.handle_right <= bounds.x + bounds.width,
+            "{fraction} 的竖条右缘越界：{}",
+            geometry.handle_right
+        );
+    }
+}
+
+/// 离散值：4 段 → 1/4 步进；连续值原样。
+#[test]
+fn discrete_sliders_quantize_to_the_stops() {
+    assert_eq!(quantize(0.3, Some(4)), 0.25);
+    assert_eq!(quantize(0.4, Some(4)), 0.5);
+    assert_eq!(quantize(1.4, Some(4)), 1.0);
+    assert_eq!(quantize(0.3, None), 0.3);
+    // 停靠点位置 = 五等分，且都落在轨道内
+    let bounds = track();
+    for index in 0..=4 {
+        let geometry = TrackGeometry::of(bounds, index as f32 / 4.0);
+        assert!(geometry.handle_left >= bounds.x);
+        assert!(geometry.handle_right <= bounds.x + bounds.width);
+    }
+}
+
+/// 拖动换算：指针在轨道左缘 → 0、右缘 → 1，中间线性。
+#[test]
+fn fraction_at_is_the_inverse_of_handle_center() {
+    let bounds = track();
+    for fraction in [0.0, 0.25, 0.5, 0.75, 1.0] {
+        let centre = TrackGeometry::of(bounds, fraction).handle_centre();
+        let back = fraction_at(bounds, centre, 4.0);
+        assert!((back - fraction).abs() < 1e-4, "{fraction} → {back}");
+    }
+    assert_eq!(fraction_at(bounds, bounds.x, 4.0), 0.0);
+    assert_eq!(fraction_at(bounds, bounds.x + bounds.width, 4.0), 1.0);
+}
+
+/// 没有回调 = 禁用：不吃拖动，也不响应状态机。
+#[test]
+fn slider_without_a_callback_is_disabled() {
+    let ui = ui();
+    let slider: Slider<'_, u8> = Slider::new(&ui, 0.5);
+    assert!(!slider.enabled());
+    let enabled: Slider<'_, u8> = Slider::new(&ui, 0.5).on_change(|_| 0_u8);
+    assert!(enabled.enabled());
+    let forced: Slider<'_, u8> = Slider::new(&ui, 0.5)
+        .on_change(|_| 0_u8)
+        .state(Interaction::Disabled);
+    assert!(!forced.enabled(), "强制禁用时不吃事件");
+}
diff --git a/crates/app-iced/src/components/inputs/slider/track.rs b/crates/app-iced/src/components/inputs/slider/track.rs
new file mode 100644
index 0000000..d160746
--- /dev/null
+++ b/crates/app-iced/src/components/inputs/slider/track.rs
@@ -0,0 +1,66 @@
+//! Slider 的**纯几何**（无 iced 画布依赖）：比例 ⇄ 像素，`draw` 与单测共用同一条公式。
+//!
+//! 单独成文件的原因：`slider.rs` 已到 400 行红线，而这几条公式是「0% / 100% 竖条不越界」的
+//! 唯一实现点——独立出来才好被人一眼审完。`draw` 与 `#[cfg(test)] mod tests` 都调这里。
+
+use iced::Rectangle;
+
+use super::super::geometry::HANDLE_WIDTH;
+
+/// 比例比较的容差（浮点拖动会产生 1e-7 级抖动，别让它每帧发一条消息）。
+pub(super) const EPSILON: f32 = 1e-4;
+
+/// 量化到停靠点（连续值时原样返回）。
+pub(super) fn quantize(fraction: f32, steps: Option<u32>) -> f32 {
+    match steps {
+        Some(steps) => {
+            let steps = steps as f32;
+            (fraction.clamp(0.0, 1.0) * steps).round() / steps
+        }
+        None => fraction.clamp(0.0, 1.0),
+    }
+}
+
+/// 一条竖条的横坐标（**位移区间是 `handle/2 .. width - handle/2`**，所以 0%/100% 都不越界）。
+fn handle_center(bounds: Rectangle, fraction: f32, handle: f32) -> f32 {
+    let travel = (bounds.width - handle).max(0.0);
+    bounds.x + handle / 2.0 + travel * fraction.clamp(0.0, 1.0)
+}
+
+/// 指针横坐标 → 比例（`handle_center` 的逆函数，同样不越界）。
+pub(super) fn fraction_at(bounds: Rectangle, x: f32, handle: f32) -> f32 {
+    let travel = (bounds.width - handle).max(1.0);
+    ((x - bounds.x - handle / 2.0) / travel).clamp(0.0, 1.0)
+}
+
+/// 轨道 / 停靠点 / 竖条的纯几何（像素级断言用；`Widget::draw` 与测试共用同一条公式）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct TrackGeometry {
+    /// 激活段的左缘。
+    pub active_left: f32,
+    /// 激活段的宽。
+    pub active_width: f32,
+    /// 竖条左缘（`f = 0` 时应 = 轨道左缘）。
+    pub handle_left: f32,
+    /// 竖条右缘（`f = 1` 时应 = 轨道右缘）。
+    pub handle_right: f32,
+}
+
+impl TrackGeometry {
+    /// 按轨道矩形与比例求值（`f` 会被 clamp 到 0..=1）。
+    pub fn of(track: Rectangle, fraction: f32) -> Self {
+        let centre = handle_center(track, fraction, HANDLE_WIDTH);
+        let handle_left = centre - HANDLE_WIDTH / 2.0;
+        Self {
+            active_left: track.x,
+            active_width: centre - track.x,
+            handle_left,
+            handle_right: handle_left + HANDLE_WIDTH,
+        }
+    }
+
+    /// 竖条中心（= 激活段与未激活段的分界）。
+    pub fn handle_centre(&self) -> f32 {
+        self.handle_left + HANDLE_WIDTH / 2.0
+    }
+}
diff --git a/crates/app-iced/src/components/interaction/disabled.rs b/crates/app-iced/src/components/interaction/disabled.rs
new file mode 100644
index 0000000..4e033c5
--- /dev/null
+++ b/crates/app-iced/src/components/interaction/disabled.rs
@@ -0,0 +1,305 @@
+//! 禁用态的颜色口径：**两个族、两套 α**（M86 收口）。
+//!
+//! ## 为什么不是「一个 12%」
+//!
+//! 官方禁用 α 分两类（A 级：`material3-android-1.4.0.aar` 的字节码 `<clinit>`）：
+//!
+//! | 族 | α | 官方 token | 消费者 |
+//! |---|---|---|---|
+//! | **按钮容器** | **0.10** | `*ButtonTokens.DisabledContainerOpacity`（`Filled` / `Outlined` / `Text` / `Elevated` / `Tonal` / `Baseline`） | `buttons::assemble` |
+//! | **面状控件**容器与描边 | **0.12** | `AssistChipTokens.FlatDisabledOutlineOpacity`、`FilterChipTokens.FlatDisabled(SelectedContainer/UnselectedOutline)Opacity`、`SliderTokens.DisabledInactiveTrackOpacity`、`SwitchTokens.DisabledTrackOpacity` | chip / switch / slider / TextField 描边 |
+//! | 内容（两族共用） | 0.38 | `Disabled{Icon,LabelText,Input}Opacity` | 全部 |
+//!
+//! 历史上这里只有一个 12% 常量供两族共用：**按钮那半边一直错、chip/slider/switch 那半边一直对**。
+//! 现在按族分开两个入口——取错入口的后果是「差 1/255」，肉眼看不见，只有像素 probe 会红，
+//! 所以入口**必须按名字就能选对**。
+//!
+//! ⚠️ TextField 的 **Filled 容器**不在这两族里：官方
+//! `FilledTextFieldTokens.FieldDisabledContainerOpacity = 0.04f`，我们仍在用面状族的值
+//! （既有 D10 偏离，未在本轮收口）。`inputs::field` 走 [`disabled_colors`] 的口径，行为未变。
+//!
+//! ⚠️ **filled-tonal 是另一条已知偏离**：官方
+//! `FilledTonalButtonTokens.DisabledContainerOpacity = 0.12f`（`javap -p -constants` 可见它是个
+//! **编译期常量**，被内联进 `getDefaultFilledTonalButtonColors` 的 `ldc_w 0.12f`，所以调用点是常量、
+//! `getDisabledContainerOpacity()` 不会被调用）；而本模块的 `disabled_button_*` **不区分变体**，
+//! tonal 与 filled 共用 0.10 ⇒ tonal 实际画 10%。这不是对齐、是登记过的偏离；要修得让入口知道变体，
+//! 本轮（M86）不做。
+
+use iced::Color;
+
+use unlucky_design::color::state::{
+    DISABLED_CONTAINER_ALPHA, DISABLED_CONTENT_ALPHA, DISABLED_SURFACE_ALPHA,
+};
+use unlucky_design::color::{Role, Scheme};
+
+use crate::theme::{to_iced, Ui};
+
+/// 禁用态内容色（**按角色、按有没有容器**求值）——A1 口径的入口（**面状控件族**的底）。
+///
+/// - `role`：由变体决定（Filled/Outlined/Text/Elevated = `OnSurfaceVariant`；
+///   FilledTonal 与三式 IconButton = `OnSurface`，见 `Variant::disabled_content`）；
+/// - `on_container = true`：叠在**面状控件族的 12% 容器**（[`DISABLED_SURFACE_ALPHA`]）上
+///   （Filled TextField / 有容器控件在 12% 底上求内容时）；
+///   `false`：直接叠在 **surface** 上（Text / Outlined / standard IconButton / 描边类控件的内容）。
+///
+/// **按钮家族不要用这个函数**（按钮容器是 10%）：走 [`disabled_button_content`]。
+///
+/// 之前这里写死 `OnSurfaceVariant` 且只有一个「底」，导致 FilledTonal 与 IconButton 两族偏浅
+/// 15/255（视觉 r3 用像素量的）。
+pub fn disabled_content_over_role(ui: &Ui, role: Role, on_container: bool) -> Color {
+    let scheme = Scheme::baseline(ui.flavor());
+    disabled_content_with_alpha(&scheme, role, on_container, DISABLED_SURFACE_ALPHA)
+}
+
+/// 禁用态内容色——**按钮家族**（`on_container`：是否叠在本族 10% 容器上）。
+///
+/// 与 [`disabled_content_over_role`] 的差别只有「底」的 α：按钮 10%、面状控件 12%。
+/// 两个入口分开是 M86 的结论：合成一个数会让一族永远差 1/255，肉眼看不见、只有 probe 会红。
+pub fn disabled_button_content(ui: &Ui, role: Role, on_container: bool) -> Color {
+    let scheme = Scheme::baseline(ui.flavor());
+    disabled_content_with_alpha(&scheme, role, on_container, DISABLED_CONTAINER_ALPHA)
+}
+
+/// 两个族共用的内容色求值（「底」的 α 由调用方给）。
+fn disabled_content_with_alpha(
+    scheme: &Scheme,
+    role: Role,
+    on_container: bool,
+    container_alpha: f32,
+) -> Color {
+    let base = if on_container {
+        scheme
+            .get(Role::OnSurface)
+            .with_alpha(container_alpha)
+            .over(scheme.get(Role::Surface))
+    } else {
+        scheme.get(Role::Surface)
+    };
+
+    to_iced(
+        scheme
+            .get(role)
+            .with_alpha(DISABLED_CONTENT_ALPHA)
+            .over(base),
+    )
+}
+
+/// 禁用态的一对颜色 `(容器, 内容)`——**面状控件族**（12% 容器/描边）。
+///
+/// ⚠️ 这个名字是历史遗留（当年只有它一个），**语义是「面状控件族」**：
+/// - chip 容器与描边（`AssistChipTokens.FlatDisabledOutlineOpacity = 0.12f` 等）
+/// - switch 轨道（`SwitchTokens.DisabledTrackOpacity = 0.12f`）
+/// - slider 未激活轨（`SliderTokens.DisabledInactiveTrackOpacity = 0.12f`）
+/// - TextField 禁用描边（Filled 容器的 4% 是另一条 D10 偏离，不在这里收口）
+///
+/// **按钮家族用 [`disabled_button_colors`]**（0.10，`*ButtonTokens.DisabledContainerOpacity = 0.1f`）。
+///
+/// `ui` 不暴露 [`Scheme`]，这里按同一个 flavor 求一次基线方案——调的是
+/// `unlucky_design` 的**同一个**函数与同一套角色，不是第二份令牌。
+///
+/// 顺序必须「先容器后内容」：Compose 也是这么画的，先叠容器再叠 label，
+/// 所以内容叠的角色是容器实色而不是底下的 surface。
+pub fn disabled_colors(ui: &Ui, surface: Role) -> (Color, Color) {
+    disabled_colors_with_alpha(ui, surface, DISABLED_SURFACE_ALPHA)
+}
+
+/// 禁用态的一对颜色 `(容器, 内容)`——**按钮家族**（10% 容器）。
+///
+/// - 容器 = `OnSurface` @ 10%（[`DISABLED_CONTAINER_ALPHA`]）叠在 `surface` 上；
+/// - 内容 = **默认** `OnSurfaceVariant` @ 38%；按变体的取值走 [`disabled_button_content`]。
+///
+/// 除了按钮家族，**没有别的消费者**：面状控件（chip / slider 轨道 / switch 轨道 / 描边）走
+/// [`disabled_colors`] 的 12%。
+pub fn disabled_button_colors(ui: &Ui, surface: Role) -> (Color, Color) {
+    disabled_colors_with_alpha(ui, surface, DISABLED_CONTAINER_ALPHA)
+}
+
+/// 两个族共用的求值：容器 = `OnSurface` @ `container_alpha` 叠在 `surface` 上，内容 = 38% 叠在容器上。
+fn disabled_colors_with_alpha(ui: &Ui, surface: Role, container_alpha: f32) -> (Color, Color) {
+    let scheme = Scheme::baseline(ui.flavor());
+    let base = scheme.get(surface);
+    let container = scheme
+        .get(Role::OnSurface)
+        .with_alpha(container_alpha)
+        .over(base);
+    // 这里是**默认口径**（OnSurfaceVariant）；按变体取值请走 [`disabled_content_over_role`]
+    // ——FilledTonal 与三式 IconButton 的禁用内容是 `OnSurface`（A1）。
+    let content = scheme
+        .get(Role::OnSurfaceVariant)
+        .with_alpha(DISABLED_CONTENT_ALPHA)
+        .over(container);
+
+    (to_iced(container), to_iced(content))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use unlucky_design::color::SchemeFlavor;
+    use unlucky_design::typography::Platform;
+
+    use crate::theme::Families;
+
+    const FAMILIES: Families = Families {
+        text: "Segoe UI",
+        display: "Segoe UI",
+        mono: "Consolas",
+    };
+
+    fn ui(flavor: SchemeFlavor) -> Ui {
+        Ui::with_platform(flavor, Platform::Windows, FAMILIES)
+    }
+
+    /// 两族的 α 必须都钉住（只钉一条，另一族被合并时会静默错 1/255）。
+    #[test]
+    fn both_disabled_alpha_classes_are_pinned_to_the_tokens() {
+        // 绑定成局部变量再过断言：直接比两个常量会被 clippy 判成「常量断言」。
+        let button_alpha = DISABLED_CONTAINER_ALPHA;
+        let surface_alpha = DISABLED_SURFACE_ALPHA;
+        let content_alpha = DISABLED_CONTENT_ALPHA;
+        // 按钮容器：官方 *ButtonTokens.DisabledContainerOpacity = 0.1f
+        assert!(
+            (button_alpha - 0.10).abs() < f32::EPSILON,
+            "按钮禁用容器 α 必须是 0.10（官方 DisabledContainerOpacity）；\
+             0.12 是面状控件那一类，别混用"
+        );
+        // 面状控件：chip 描边 / slider 未激活轨 / switch 轨道 = 0.12f
+        assert!(
+            (surface_alpha - 0.12).abs() < f32::EPSILON,
+            "面状控件禁用 α 必须是 0.12（官方 FlatDisabledOutlineOpacity / \
+             DisabledInactiveTrackOpacity / DisabledTrackOpacity）"
+        );
+        assert!((content_alpha - 0.38).abs() < f32::EPSILON);
+        assert!(
+            surface_alpha > button_alpha,
+            "两族必须可区分：面状控件比按钮容器更实（{surface_alpha} > {button_alpha}）"
+        );
+    }
+
+    /// **面状控件族**的那一对颜色 = 0.12 预混合（chip / switch / slider / TextField 描边）。
+    ///
+    /// ⚠️ 期望值**写死 0.12 / 0.38**，不从 `DISABLED_SURFACE_ALPHA` 取：
+    /// 从被测常量求期望是**自指断言**——常量一改，expected 跟着改，永远相等（复审 r1 P2-1 实测：
+    /// 把 `DISABLED_SURFACE_ALPHA` 改成 0.10，旧版这条照样绿）。现在常量改坏必红。
+    #[test]
+    fn surface_family_disabled_colors_are_the_12_percent_class() {
+        const EXPECTED_SURFACE_ALPHA: f32 = 0.12;
+        const EXPECTED_CONTENT_ALPHA: f32 = 0.38;
+        let actual_alpha = DISABLED_SURFACE_ALPHA;
+        assert_eq!(
+            actual_alpha, EXPECTED_SURFACE_ALPHA,
+            "面状控件族 α 必须是官方 0.12f；改常量会让下面每一条合成色断言同时红"
+        );
+
+        for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+            let ui = ui(flavor);
+            let scheme = Scheme::baseline(flavor);
+            let base = scheme.get(Role::Surface);
+            let expected_container = scheme
+                .get(Role::OnSurface)
+                .with_alpha(EXPECTED_SURFACE_ALPHA)
+                .over(base);
+
+            let (surface, surface_content) = disabled_colors(&ui, Role::Surface);
+            assert_eq!(
+                surface,
+                to_iced(expected_container),
+                "{flavor:?}：面状控件容器 = on-surface@12% 叠表面（期望值硬编码，不取自常量）"
+            );
+            assert_eq!(
+                surface_content,
+                to_iced(
+                    scheme
+                        .get(Role::OnSurfaceVariant)
+                        .with_alpha(EXPECTED_CONTENT_ALPHA)
+                        .over(expected_container)
+                ),
+                "{flavor:?}：面状控件内容仍是 38%，只是叠的底不同"
+            );
+            assert_ne!(surface, ui.color(Role::Surface), "12% 叠上去必须能看出来");
+            assert_eq!(surface.a, 1.0, "禁用容器也是实色（CPU/GPU 一致）");
+            assert_eq!(surface_content.a, 1.0, "禁用内容也是实色");
+            // 内容叠在容器上 vs 叠在表面上，是两回事（probe 量的是前者）
+            assert_ne!(
+                surface_content,
+                to_iced(
+                    scheme
+                        .get(Role::OnSurfaceVariant)
+                        .with_alpha(EXPECTED_CONTENT_ALPHA)
+                        .over(base)
+                ),
+                "{flavor:?}：内容必须叠在容器上"
+            );
+            // 跨族对照：面状族的合成色必须与按钮族不同（两族一旦合流，这条红）
+            let (button, _) = disabled_button_colors(&ui, Role::Surface);
+            assert_ne!(
+                surface, button,
+                "{flavor:?}：面状族 12% 与按钮族 10% 必须落在不同像素值上"
+            );
+        }
+    }
+
+    /// **按钮家族**的那一对颜色 = 0.10 预混合，且与面状控件族**必须落在不同像素值上**。
+    ///
+    /// 期望值同样写死（0.10 / 0.38），理由见上一条：自指断言抓不住常量被改坏。
+    #[test]
+    fn button_family_disabled_colors_are_the_10_percent_class() {
+        const EXPECTED_BUTTON_ALPHA: f32 = 0.10;
+        const EXPECTED_CONTENT_ALPHA: f32 = 0.38;
+        let actual_alpha = DISABLED_CONTAINER_ALPHA;
+        assert_eq!(
+            actual_alpha, EXPECTED_BUTTON_ALPHA,
+            "按钮族 α 必须是官方 0.1f（*ButtonTokens.DisabledContainerOpacity）"
+        );
+
+        for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+            let ui = ui(flavor);
+            let scheme = Scheme::baseline(flavor);
+            let base = scheme.get(Role::Surface);
+            let expected_container = scheme
+                .get(Role::OnSurface)
+                .with_alpha(EXPECTED_BUTTON_ALPHA)
+                .over(base);
+
+            let (button, button_content) = disabled_button_colors(&ui, Role::Surface);
+            assert_eq!(
+                button,
+                to_iced(expected_container),
+                "{flavor:?}：按钮容器 = on-surface@10% 叠表面（官方 DisabledContainerOpacity = 0.1f）"
+            );
+            assert_eq!(
+                button_content,
+                to_iced(
+                    scheme
+                        .get(Role::OnSurfaceVariant)
+                        .with_alpha(EXPECTED_CONTENT_ALPHA)
+                        .over(expected_container)
+                ),
+            );
+
+            let (surface, _) = disabled_colors(&ui, Role::Surface);
+            assert_ne!(
+                button, surface,
+                "{flavor:?}：10% 与 12% 必须落在不同像素值上（合成一个数就是这次要防的回归）"
+            );
+
+            // 内容色同理：按钮 38% 叠 10% 底 ≠ 面状 38% 叠 12% 底
+            assert_ne!(
+                button_content,
+                disabled_content_over_role(&ui, Role::OnSurfaceVariant, true),
+                "{flavor:?}：两族的「有容器」内容色不能同源"
+            );
+            assert_eq!(
+                disabled_button_content(&ui, Role::OnSurfaceVariant, true),
+                button_content,
+                "{flavor:?}：按钮内容入口必须与按钮颜色入口同源"
+            );
+            // 无容器时两族完全一致（都叠 surface）——差异只在「有容器」那一支
+            assert_eq!(
+                disabled_button_content(&ui, Role::OnSurfaceVariant, false),
+                disabled_content_over_role(&ui, Role::OnSurfaceVariant, false),
+                "{flavor:?}：没有容器时不该有族差异"
+            );
+        }
+    }
+}
diff --git a/crates/app-iced/src/components/interaction/mod.rs b/crates/app-iced/src/components/interaction/mod.rs
new file mode 100644
index 0000000..8fd640a
--- /dev/null
+++ b/crates/app-iced/src/components/interaction/mod.rs
@@ -0,0 +1,239 @@
+//! 交互状态层：hover / focus / pressed / disabled 的**唯一实现点**（D39 §3）。
+//!
+//! ## 为什么必须只有一处
+//!
+//! M3 的状态层不是「另一种灰」，而是**内容色自身 + 固定 alpha** 叠在容器色上
+//! （`unlucky_design::color::state` 的文档）。五个家族各写一遍
+//! `if hovered { 0.08 }`，第一周就会出现 0.08 / 0.1 / 0.12 三种 hover——
+//! 这一层存在的意义就是让「组件里出现 α 字面量」变成不可能：
+//!
+//! | 态 | α | 令牌来源 |
+//! |---|---|---|
+//! | hover | 0.08 | [`StateLayer::Hover`] |
+//! | focus | 0.10 | [`StateLayer::Focus`] |
+//! | pressed | 0.10 | [`StateLayer::Pressed`] |
+//! | dragged | 0.16 | [`StateLayer::Dragged`]（按钮家族不用，列表拖拽用） |
+//! | disabled 容器（**按钮家族**） | 0.10 | [`DISABLED_CONTAINER_ALPHA`]（按钮 `*ButtonTokens.DisabledContainerOpacity`） |
+//! | disabled 容器/描边（**面状控件族**） | 0.12 | [`DISABLED_SURFACE_ALPHA`]（chip / slider 轨道 / switch 轨道 / TextField 禁用描边） |
+//! | disabled 内容 | 0.38 | [`DISABLED_CONTENT_ALPHA`] |
+//!
+//! ## ⚠️ 禁用 α 有**两类**（M86 收口，别再合成一个数）
+//!
+//! 官方禁用 α 从来不是「一个 12%」：
+//!
+//! - **按钮容器 0.10**：`BaselineButtonTokens` / `FilledButtonTokens` / `OutlinedButtonTokens` /
+//!   `TextButtonTokens` / `ElevatedButtonTokens` / `TonalButtonTokens` 的 `DisabledContainerOpacity`
+//!   = `0.1f`（AAR 字节码 `<clinit>` 里的 `ldc 0.1f`）；
+//! - **面状控件 0.12**：`AssistChipTokens.FlatDisabledOutlineOpacity` / `FilterChipTokens.
+//!   FlatDisabledSelectedContainerOpacity` / `SliderTokens.DisabledInactiveTrackOpacity` /
+//!   `SwitchTokens.DisabledTrackOpacity` 都是 `0.12f`。
+//!
+//! 本模块过去只有一个 12% 常量供两条线共用：**按钮那半边一直错、chip/slider/switch 那半边一直对**。
+//! 现在按族分两个入口，谁也别再拿一个数服务两族：
+//!
+//! | 入口 | α | 谁用 |
+//! |---|---|---|
+//! | [`disabled_button_colors`] / [`disabled_button_content`] | 0.10 | **只有按钮家族**（`buttons::assemble`） |
+//! | [`disabled_colors`] / [`disabled_content_over_role`] | 0.12 | **面状控件族**：chip 容器与描边、switch 轨道、slider 未激活轨、TextField 禁用描边（`disabled_colors` 这个名字是历史遗留，**语义是面状控件族**） |
+//!
+//! 上表右列是**唯一**允许的取值口；左列只是给人看的，代码里一个数字都不许出现
+//! （`components::gate` 会扫）。
+//!
+//! ## 两个消费形态
+//!
+//! 1. **iced `button` 系**（本 mission 的按钮家族）：拿 [`Interaction`] 直接配 [`overlay_color`]；
+//! 2. **自定义 `Widget`**（后续若需要自绘轨道/滑块）：用 [`Tracker`] 把事件折成五态，
+//!    `update()` 的返回值告诉你「要不要重绘」，`state()` 给出当前态。
+//!
+//! ## 与 `Ui::state_over` 的关系
+//!
+//! 颜色一律经 [`crate::theme::Ui::state_over`] 求值（它返回**不透明**结果，所以 GPU/CPU 两档
+//! 逐像素一致，D27）。本模块只做「哪一态叠哪一层」的映射，不做任何颜色算术。
+
+use iced::widget::button;
+use iced::Color;
+
+use unlucky_design::color::{Role, StateLayer};
+
+use crate::theme::Ui;
+
+mod tracker;
+
+// 本 mission 没有自绘控件，所以这条再导出在 crate 内暂时无人使用；
+// 它是给四条家族线（Slider / Switch 轨道要自绘）的公共入口，路径与拆分前一致。
+#[allow(unused_imports)]
+pub use tracker::Tracker;
+
+// 本模块会被四条家族线各扩一次：加东西前先看行数余额（单文件 ≤400，AGENTS.md §3-1）。
+// `mod.rs` 只装「五态 + 颜色映射」这类纯函数；事件 → 态的**状态机在 [`tracker`]**，
+// 需要新的状态机就加到那边，别把本文件再撑到红线上。
+
+/// 一个控件的视觉态（五态，M3 的完整集合）。
+///
+/// `Enabled` 是**静息态**（不叠状态层）；`Focused` / `Pressed` 在 M3 里 α 相同（都 10%），
+/// 所以两者在图上会一模一样——这是规范，不是漏画（12b §1.8 判据只要求 α 对得上）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Interaction {
+    /// 静息：可交互，不叠状态层。
+    Enabled,
+    /// 悬停：叠 8%。
+    Hovered,
+    /// 键盘焦点：叠 10%。
+    Focused,
+    /// 按下：叠 10%。
+    Pressed,
+    /// 禁用：按钮容器 10% / 面状控件 12% / 内容 38%，**不叠状态层**。
+    Disabled,
+}
+
+impl Interaction {
+    /// 五态全序（gallery 的状态矩阵按这个次序出图）。
+    pub const ALL: [Interaction; 5] = [
+        Interaction::Enabled,
+        Interaction::Hovered,
+        Interaction::Pressed,
+        Interaction::Focused,
+        Interaction::Disabled,
+    ];
+
+    /// 稳定名字（截图文件名 / 图例 / 测试失败信息用）。
+    pub const fn name(self) -> &'static str {
+        match self {
+            Interaction::Enabled => "enabled",
+            Interaction::Hovered => "hovered",
+            Interaction::Focused => "focused",
+            Interaction::Pressed => "pressed",
+            Interaction::Disabled => "disabled",
+        }
+    }
+
+    /// 是否禁用（禁用不是「第六态」，它要不要画容器由组件决定）。
+    pub const fn is_disabled(self) -> bool {
+        matches!(self, Interaction::Disabled)
+    }
+
+    /// 该态要叠的状态层；`None` = 不叠（静息与禁用）。
+    pub const fn layer(self) -> Option<StateLayer> {
+        match self {
+            Interaction::Enabled | Interaction::Disabled => None,
+            Interaction::Hovered => Some(StateLayer::Hover),
+            Interaction::Focused => Some(StateLayer::Focus),
+            Interaction::Pressed => Some(StateLayer::Pressed),
+        }
+    }
+
+    /// 从 iced 的 [`button::Status`] 推导（`button` 只有四态，没有 focus）。
+    ///
+    /// 用 `button` 做组件的家族一律经这里，**不许自己 match status 再各写一遍颜色**。
+    pub const fn from_status(status: button::Status) -> Self {
+        match status {
+            button::Status::Active => Interaction::Enabled,
+            button::Status::Hovered => Interaction::Hovered,
+            button::Status::Pressed => Interaction::Pressed,
+            button::Status::Disabled => Interaction::Disabled,
+        }
+    }
+}
+
+/// 当前态叠在 `container` 上的**不透明**颜色；`None` = 该态不叠。
+///
+/// `content` 是容器上的前景角色（Filled 按钮用 `OnPrimary`；中性表面上的控件用 `OnSurfaceVariant`）。
+pub fn overlay_color(ui: &Ui, state: Interaction, content: Role, container: Role) -> Option<Color> {
+    state
+        .layer()
+        .map(|layer| ui.state_over(layer, content, container))
+}
+
+mod disabled;
+
+pub use disabled::{
+    disabled_button_colors, disabled_button_content, disabled_colors, disabled_content_over_role,
+};
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use unlucky_design::color::SchemeFlavor;
+    use unlucky_design::typography::Platform;
+
+    use crate::theme::Families;
+
+    const FAMILIES: Families = Families {
+        text: "Segoe UI",
+        display: "Segoe UI",
+        mono: "Consolas",
+    };
+
+    fn ui(flavor: SchemeFlavor) -> Ui {
+        Ui::with_platform(flavor, Platform::Windows, FAMILIES)
+    }
+
+    /// 契约 §3 的状态层 α 全表：**钉住令牌值**（改令牌会让这条红，改组件抓不到）。
+    ///
+    /// 禁用态的两族 α（按钮 0.10 / 面状控件 0.12）在 [`super::disabled`] 的测试里，
+    /// 那边还负责「两族不能同源」的判据。
+    #[test]
+    fn state_layer_alphas_are_the_contract_values() {
+        assert!((StateLayer::Hover.alpha() - 0.08).abs() < f32::EPSILON);
+        assert!((StateLayer::Focus.alpha() - 0.10).abs() < f32::EPSILON);
+        assert!((StateLayer::Pressed.alpha() - 0.10).abs() < f32::EPSILON);
+        assert!((StateLayer::Dragged.alpha() - 0.16).abs() < f32::EPSILON);
+    }
+
+    #[test]
+    fn five_states_map_onto_four_layers() {
+        assert_eq!(Interaction::ALL.len(), 5);
+        assert_eq!(Interaction::Enabled.layer(), None);
+        assert_eq!(Interaction::Disabled.layer(), None);
+        assert_eq!(Interaction::Hovered.layer(), Some(StateLayer::Hover));
+        assert_eq!(Interaction::Focused.layer(), Some(StateLayer::Focus));
+        assert_eq!(Interaction::Pressed.layer(), Some(StateLayer::Pressed));
+        // focus 与 pressed 同 α（M3 口径）——图上一样是**对的**
+        assert_eq!(
+            Interaction::Focused.layer().map(StateLayer::alpha),
+            Interaction::Pressed.layer().map(StateLayer::alpha)
+        );
+    }
+
+    #[test]
+    fn overlay_color_is_the_token_blend_not_local_math() {
+        for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+            let ui = ui(flavor);
+            for (state, layer) in [
+                (Interaction::Hovered, StateLayer::Hover),
+                (Interaction::Focused, StateLayer::Focus),
+                (Interaction::Pressed, StateLayer::Pressed),
+            ] {
+                assert_eq!(
+                    overlay_color(&ui, state, Role::OnPrimary, Role::Primary),
+                    Some(ui.state_over(layer, Role::OnPrimary, Role::Primary)),
+                    "{flavor:?}/{state:?} 必须逐位等于令牌求值结果"
+                );
+                assert!(
+                    overlay_color(&ui, state, Role::OnSurface, Role::Surface).is_some(),
+                    "可交互态必须给颜色"
+                );
+            }
+            assert_eq!(
+                overlay_color(&ui, Interaction::Enabled, Role::OnSurface, Role::Surface),
+                None
+            );
+            assert_eq!(
+                overlay_color(&ui, Interaction::Disabled, Role::OnSurface, Role::Surface),
+                None,
+                "禁用态不叠状态层（它换的是容器/内容色）"
+            );
+        }
+    }
+
+    #[test]
+    fn hover_is_weaker_than_pressed_on_the_same_container() {
+        let ui = ui(SchemeFlavor::Light);
+        let hover = overlay_color(&ui, Interaction::Hovered, Role::OnSurface, Role::Surface)
+            .expect("hover 有颜色");
+        let pressed = overlay_color(&ui, Interaction::Pressed, Role::OnSurface, Role::Surface)
+            .expect("pressed 有颜色");
+        assert_ne!(hover, pressed, "8% 与 10% 必须能区分");
+        assert_eq!(hover.a, 1.0, "结果必须不透明（GPU/CPU 逐像素一致）");
+    }
+}
diff --git a/crates/app-iced/src/components/interaction/tracker.rs b/crates/app-iced/src/components/interaction/tracker.rs
new file mode 100644
index 0000000..8139171
--- /dev/null
+++ b/crates/app-iced/src/components/interaction/tracker.rs
@@ -0,0 +1,155 @@
+//! 自定义 `Widget` 的状态机（[`Tracker`]）：把 iced 事件折成 [`Interaction`] 五态。
+//!
+//! 与 [`super`] 的分工：`super` 只有「态 → 颜色」的纯映射；**事件 → 态**在这里。
+//! 本 mission 的按钮家族全走 iced 的 `button`（自带四态），所以 `Tracker` 目前只有单测在用——
+//! 它给四个后续家族里**要自绘**的控件（Slider 轨道 / Switch 轨道 / 进度条）准备。
+//!
+//! 加东西前先看行数余额（单文件 ≤400，AGENTS.md §3-1）。
+
+use iced::Event;
+
+use super::Interaction;
+
+/// 自定义 `Widget` 的状态机：把 iced 事件折成 [`Interaction`]。
+///
+/// 这是 D39 §3 说的「状态机的公共部分」。用法（自定义 Widget 的 `update` 里）：
+///
+/// ```ignore
+/// if self.tracker.event(event, cursor.is_over(layout.bounds())) {
+///     shell.request_redraw();       // 只有真变了才重绘
+/// }
+/// let style = style_of(self.tracker.state());
+/// ```
+#[allow(dead_code)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub struct Tracker {
+    enabled: bool,
+    hovered: bool,
+    focused: bool,
+    pressed: bool,
+}
+
+#[allow(dead_code)]
+impl Tracker {
+    /// 新建；`enabled` 由组件自己决定（例如 `on_press.is_some()`）。
+    pub fn new(enabled: bool) -> Self {
+        Self {
+            enabled,
+            ..Self::default()
+        }
+    }
+
+    /// 启用/禁用热切换（禁用时清掉悬停与按下：禁用元素不该留着 hover 高亮）。
+    pub fn set_enabled(&mut self, enabled: bool) -> bool {
+        let changed = self.enabled != enabled;
+        self.enabled = enabled;
+        if !enabled {
+            self.hovered = false;
+            self.pressed = false;
+            self.focused = false;
+        }
+        changed
+    }
+
+    /// 键盘焦点（由 `operation`/`shell` 侧的聚焦消息驱动）。
+    pub fn set_focused(&mut self, focused: bool) -> bool {
+        let next = focused && self.enabled;
+        let changed = self.focused != next;
+        self.focused = next;
+        changed
+    }
+
+    /// 折进一个事件；返回「视觉态变了，要重绘吗」。
+    ///
+    /// `over` = 指针是否在控件 bounds 内（`Cursor::is_over(bounds)` 的结果，由调用方算——
+    /// 这样本函数不依赖 `Layout`，可以在单测里直接喂）。
+    pub fn event(&mut self, event: &Event, over: bool) -> bool {
+        if !self.enabled {
+            return false;
+        }
+
+        let before = self.state();
+        match event {
+            Event::Mouse(iced::mouse::Event::CursorMoved { .. }) => self.hovered = over,
+            Event::Mouse(iced::mouse::Event::CursorLeft) => {
+                self.hovered = false;
+                self.pressed = false;
+            }
+            Event::Mouse(iced::mouse::Event::ButtonPressed(iced::mouse::Button::Left)) => {
+                self.pressed = over;
+            }
+            Event::Mouse(iced::mouse::Event::ButtonReleased(iced::mouse::Button::Left)) => {
+                self.pressed = false;
+            }
+            _ => {}
+        }
+        self.state() != before
+    }
+
+    /// 当前态（优先级：按下 > 焦点 > 悬停 > 静息；禁用最高）。
+    pub const fn state(&self) -> Interaction {
+        if !self.enabled {
+            Interaction::Disabled
+        } else if self.pressed {
+            Interaction::Pressed
+        } else if self.focused {
+            Interaction::Focused
+        } else if self.hovered {
+            Interaction::Hovered
+        } else {
+            Interaction::Enabled
+        }
+    }
+}
+
+/// `Tracker` 的行为用例（自绘控件用，与颜色无关）。
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use iced::Event;
+
+    fn moved() -> Event {
+        Event::Mouse(iced::mouse::Event::CursorMoved {
+            position: iced::Point::ORIGIN,
+        })
+    }
+
+    #[test]
+    fn tracker_folds_events_into_the_five_states() {
+        let mut tracker = Tracker::new(true);
+        assert_eq!(tracker.state(), Interaction::Enabled);
+
+        assert!(tracker.event(&moved(), true), "首次悬停要报变化");
+        assert_eq!(tracker.state(), Interaction::Hovered);
+        assert!(!tracker.event(&moved(), true), "重复悬停不该再报变化");
+
+        let press = Event::Mouse(iced::mouse::Event::ButtonPressed(iced::mouse::Button::Left));
+        assert!(tracker.event(&press, true));
+        assert_eq!(tracker.state(), Interaction::Pressed);
+
+        let release = Event::Mouse(iced::mouse::Event::ButtonReleased(
+            iced::mouse::Button::Left,
+        ));
+        assert!(tracker.event(&release, true));
+        assert_eq!(tracker.state(), Interaction::Hovered);
+
+        assert!(tracker.set_focused(true));
+        assert_eq!(tracker.state(), Interaction::Focused, "焦点态优先于悬停");
+
+        let left = Event::Mouse(iced::mouse::Event::CursorLeft);
+        tracker.event(&left, false);
+        assert_eq!(tracker.state(), Interaction::Focused, "鼠标离开不影响焦点");
+    }
+
+    #[test]
+    fn disabled_tracker_swallows_everything() {
+        let mut tracker = Tracker::new(true);
+        assert!(tracker.set_enabled(false));
+        assert_eq!(tracker.state(), Interaction::Disabled);
+
+        let press = Event::Mouse(iced::mouse::Event::ButtonPressed(iced::mouse::Button::Left));
+        assert!(!tracker.event(&press, true), "禁用态不响应事件");
+        assert_eq!(tracker.state(), Interaction::Disabled);
+        assert!(!tracker.set_focused(true), "禁用态拿不到焦点");
+    }
+}
diff --git a/crates/app-iced/src/components/layout.rs b/crates/app-iced/src/components/layout.rs
new file mode 100644
index 0000000..998a838
--- /dev/null
+++ b/crates/app-iced/src/components/layout.rs
@@ -0,0 +1,129 @@
+//! 布局陷阱的两个固定解法（D39 §4）：**要精确尺寸就调这里，别手写**。
+//!
+//! ## 陷阱 Q8：`center_x(Length::Fill)` 会把已设的 `.width()` 覆盖成 Fill
+//!
+//! iced 的 `container::center_x/center_y/center` 不只是「对齐」——它们**同时**把容器该轴的
+//! `Length` 改成 `Fill`（源码里 `self.width = Length::Fill`）。于是
+//! `.width(56).center_x(Length::Fill)` 最终是 `Fill`，56 被父级宽度吃掉：
+//! M68 的导航药丸因此从 **56×32 变成 88×32**（父级是 88 宽的轨），图上看着「横贯全轨」，
+//! 而单元测试测的 `indicator_size()` 返回值一直是 56×32 —— **函数对、图错**。
+//!
+//! 正确写法是二选一：
+//!
+//! - 尺寸留在**自己**身上，居中交给**父级**（`row/column` 的 `align_x`）——`shell/nav.rs` 的做法；
+//! - 或者用 [`centered_fixed`]：容器写死宽高，**用 `align_x/align_y` 居中**（它们只改对齐，
+//!   不改 `Length`）。
+//!
+//! ## 陷阱 Q9：`Button` 给内容 Fill 约束，`svg().width(24)` 会被忽略
+//!
+//! `button` 在 layout 里把「内容可用区」作为约束交给子元素，`svg` 拿到的是 Fill，
+//! usvg 于是按 `Contain` 撑满内区：**字形渲染成 46px、线宽从 1.5 变 2.9**（M68 视觉复审 P2-2），
+//! 比导航图标重一倍。反过来「把 `.width(24)` 设在 button 上」也不行——那会缩掉点击区。
+//!
+//! 正确写法：**在中间插一层固定尺寸容器**——[`fixed`]：
+//!
+//! ```text
+//! let icon = layout::fixed(24.0, 24.0, icons::view(kind, color));   // 字形 24×24
+//! button(icon).width(46).height(48)                                 // 命中区仍是 46×48
+//! ```
+//!
+//! ## 为什么还要 [`inset`]
+//!
+//! 「左右缩进 16 的一条线」「内容四周留 24」这类**只改内边距、不改尺寸**的语义，
+//! 写 `.padding(Padding::from([...]))` 时数组顺序（上右下左）极易写反；封装一次，
+//! 全组件线只写一次顺序。
+//!
+//! ## 自检
+//!
+//! `components::gate` 会扫 `src/components/**`：出现 `center_x(` / `center_y(` / `.center(`
+//! 即判红（这条门禁就是 Q8 的回归测试）；图标一律经 [`fixed`] / [`centered_fixed`] 包一层。
+
+use iced::widget::container;
+use iced::{Alignment, Element, Length, Padding};
+
+/// 固定尺寸的盒子：宽高**只由参数决定**，子元素贴左上（对齐交给子元素自己或父级）。
+///
+/// Q9 的解法：`svg` 放进 24×24 的盒子，它拿到的约束就是 24，`Contain` 无从撑满。
+pub fn fixed<'a, M: 'a>(
+    width: f32,
+    height: f32,
+    content: impl Into<Element<'a, M>>,
+) -> Element<'a, M> {
+    container(content)
+        .width(Length::Fixed(width))
+        .height(Length::Fixed(height))
+        .into()
+}
+
+/// 固定尺寸 + 内容居中（Q8 的解法）。
+///
+/// 用 `align_x/align_y` 而不是 `center_x/center_y`：前者只改对齐，后者会把本容器的
+/// `Length` 改成 `Fill`，把参数里的宽高**静默丢掉**。
+///
+/// 典型用法：导航轨的选中指示器 [`centered_fixed(56.0, 32.0, icon)`](centered_fixed)。
+pub fn centered_fixed<'a, M: 'a>(
+    width: f32,
+    height: f32,
+    content: impl Into<Element<'a, M>>,
+) -> Element<'a, M> {
+    container(content)
+        .width(Length::Fixed(width))
+        .height(Length::Fixed(height))
+        .align_x(Alignment::Center)
+        .align_y(Alignment::Center)
+        .into()
+}
+
+/// 只加内边距、不碰尺寸（`horizontal` = 左右，`vertical` = 上下）。
+///
+/// 语义等价于 `.padding(Padding { top: vertical, right: horizontal, bottom: vertical,
+/// left: horizontal })`，但只暴露两个参数——避免把「上右下左」写反。
+pub fn inset<'a, M: 'a>(
+    horizontal: f32,
+    vertical: f32,
+    content: impl Into<Element<'a, M>>,
+) -> Element<'a, M> {
+    container(content)
+        .padding(Padding {
+            top: vertical,
+            right: horizontal,
+            bottom: vertical,
+            left: horizontal,
+        })
+        .into()
+}
+
+/// 单侧缩进（只缩左侧；分隔线的「列表内左缩进 16」用这个）。
+pub fn inset_start<'a, M: 'a>(start: f32, content: impl Into<Element<'a, M>>) -> Element<'a, M> {
+    container(content)
+        .width(Length::Fill)
+        .padding(Padding {
+            left: start,
+            ..Padding::default()
+        })
+        .into()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Q8 的**形态级**钉法：这三个 API 一旦内部改用 `center_*`，这条测试之外的门禁
+    /// （`components::gate`）也会红；这里再钉一次「参数就是参数」，防止签名被悄悄改成
+    /// `impl Into<Length>` 之类。
+    #[test]
+    fn helpers_take_pixel_sizes_not_lengths() {
+        let _: fn(f32, f32, Element<'static, ()>) -> Element<'static, ()> = fixed;
+        let _: fn(f32, f32, Element<'static, ()>) -> Element<'static, ()> = centered_fixed;
+        let _: fn(f32, f32, Element<'static, ()>) -> Element<'static, ()> = inset;
+        let _: fn(f32, Element<'static, ()>) -> Element<'static, ()> = inset_start;
+    }
+
+    #[test]
+    fn helpers_build_a_tree_without_panicking() {
+        let _: Element<'_, ()> = fixed(24.0, 24.0, iced::widget::text("x"));
+        let _: Element<'_, ()> = centered_fixed(56.0, 32.0, iced::widget::text("x"));
+        let _: Element<'_, ()> = inset(16.0, 8.0, iced::widget::text("x"));
+        let _: Element<'_, ()> = inset_start(16.0, iced::widget::text("x"));
+    }
+}
diff --git a/crates/app-iced/src/components/mod.rs b/crates/app-iced/src/components/mod.rs
new file mode 100644
index 0000000..ac7d52c
--- /dev/null
+++ b/crates/app-iced/src/components/mod.rs
@@ -0,0 +1,58 @@
+//! 组件库（D39 定案）：五家族并行，**目录所有权切分**，接口见
+//! `DevDocs/SubAgentsTalk/app-iced-组件库契约.md`。
+//!
+//! ## 模块地图与归属（谁能写哪里）
+//!
+//! ```text
+//! components/
+//!   mod.rs          ← 本文件（COMPBASE 独占）：只声明子模块，不含实现
+//!   interaction.rs  ← COMPBASE 独占：hover/focus/pressed/disabled 的唯一实现
+//!   layout.rs       ← COMPBASE 独占：Q8/Q9 两个布局陷阱的固定解法
+//!   buttons/        ← COMPBASE（12b §1 按钮家族 + §2 IconButton）
+//!   divider.rs      ← COMPBASE（15 §22）
+//!   selection/      ← 本文件只放桩；后续 mission 在自己的目录里填（§18/§19/§10/§13）
+//!   inputs/         ← 同上（§9/§20/§11/§8）
+//!   feedback/       ← 同上（§12/§14/§7/§15）
+//!   navigation/     ← 同上（§4/§6/§21/§16）
+//!   gallery/        ← 视觉验收 harness（`--screen=gallery`）
+//! ```
+//!
+//! **后续 mission 只写自己目录内的文件，不改本文件**：四个家族桩已经在这里声明好，
+//! 每个家族文件自带一个 `demo()`（占位 → 真组件），gallery 侧对应文件也在
+//! `gallery/` 里预置了同构的桩。加组件 = 只改自家目录里的文件。
+//!
+//! ## 组件签名纪律（契约 §2）
+//!
+//! 组件**对消息类型泛型**，不 import `crate::app::Message`：
+//!
+//! ```text
+//! pub fn filled<'a, M: Clone + 'a>(ui: &'a Ui, ...) -> Element<'a, M>
+//! ```
+//!
+//! `Ui` 一律 `&'a Ui` 传入，组件内部**不许** `Ui::new`；深浅热切靠外部重建整树。
+//!
+//! ## 令牌纪律
+//!
+//! 组件里**零**色值 / 字号 / 半径 / 间距 / α 字面量：颜色走 [`crate::theme::Ui`]，
+//! 状态层走 [`interaction`]，尺寸走 `unlucky_design` 的 `LayoutMetrics` / `Space` /
+//! `IconSize` / `ShapeScale`。缺令牌 → 登记 G 编号（续 15 §25 的 G13），**不发明**。
+//! [`gate`] 里的测试会扫本目录源码执行这条纪律。
+//!
+//! ## 为什么 `components` 由 `app.rs` 声明
+//!
+//! `src/lib.rs` 是五条组件线共用的文件（并行线改它必然冲突）。本模块挂在
+//! `app.rs` 的 `#[path]` 声明下，路径仍是 `src/components/`，这样 COMPBASE 的
+//! 全部改动都落在自己 scope 内。
+
+pub mod buttons;
+pub mod divider;
+pub mod feedback;
+pub mod gallery;
+pub mod inputs;
+pub mod interaction;
+pub mod layout;
+pub mod navigation;
+pub mod selection;
+
+#[cfg(test)]
+mod gate;
diff --git a/crates/app-iced/src/components/navigation/app_bar.rs b/crates/app-iced/src/components/navigation/app_bar.rs
new file mode 100644
index 0000000..0f6e5a6
--- /dev/null
+++ b/crates/app-iced/src/components/navigation/app_bar.rs
@@ -0,0 +1,353 @@
+//! AppBar（small）（`research/12b` §16）：页头 56、标题 + 副标题、leading / trailing 槽位、滚动换色。
+//!
+//! ## 参考值（`[源]` = A1，本轮 `javap` 实读本机 AAR）
+//!
+//! | # | 检查项 | 参考值 | 本项目 |
+//! |---|---|---|---|
+//! | 16.1 | 页头高 | `AppBarSmallTokens.ContainerHeight` = **64** | **56** = `LM.page_header_height`（登记偏离 −8） |
+//! | 16.3 | 容器 | `AppBarTokens.ContainerColor = Surface` + L0；**滚动后** `OnScrollContainerColor = SurfaceContainer` + `OnScrollContainerElevation`（L2） | 同 |
+//! | 16.4 | 字级 | `TitleFont = TitleLarge`（emphasized w500）· `SubtitleFont = LabelMedium` + `SubtitleColor = OnSurfaceVariant` | 同 |
+//! | 16.5 | 图标 | `IconSize = 24`；leading `OnSurface`、trailing `OnSurfaceVariant` | 同 |
+//! | 16.6 | 左右内边距 | `LeadingSpace = 4` / `TrailingSpace = 4`（+ IconButton 自带 40 宽 → 视觉起手 20） | 同 |
+//!
+//! ## 「滚动时的高度变化」——**规范上不存在**（不是我们没做）
+//!
+//! A1 的 `AppBarTokens` 全字段实读（`javap -p -c androidx.compose.material3.tokens.AppBarTokens`）：
+//!
+//! ```text
+//! AvatarSize 32 · ContainerColor Surface · ContainerElevation · ContainerShape CornerNone
+//! IconButtonSpace · IconSize 24 · LeadingIconColor · LeadingSpace 4
+//! OnScrollContainerColor SurfaceContainer · OnScrollContainerElevation   ← 滚动只改这两项
+//! SubtitleColor/SubtitleFont · TitleColor/TitleFont · TrailingIconColor · TrailingSpace 4
+//! ```
+//!
+//! **整个 tokens 包里 `OnScroll*` 只有两个字段**（颜色与高程，见 `grep` 全量核对的报告），
+//! 没有任何 `OnScroll…Height`；高度只在**尺寸档**（`AppBarSmallTokens.ContainerHeight = 64`）里，
+//! 而那是 `small` / `medium` / `large` 三个**不同组件**的分档，不是滚动驱动的形变。
+//! 所以滚动时**高度不变**、只换容器色 + 升到 L2 阴影——这是规范，不是偏离。
+//!
+//! 我们与规范的两处差异各登记一条：
+//!
+//! - **D-M79-2** 高度 56 而不是 64（项目骨架口径 `LM.page_header_height`，已有页面按 56 排版）；
+//! - 不做 `Medium` / `Large` 的**折叠（collapsing）**形态——那是另外两个组件（`AppBarMediumTokens`
+//!   / `AppBarLargeTokens`），本 mission 的 §16 只要求 small。
+
+use iced::widget::text::{LineHeight, Wrapping};
+use iced::widget::{button, container, text};
+use iced::{
+    Alignment, Background, Border, Color, Element, Length, Padding, Pixels, Shadow, Vector,
+};
+
+use unlucky_design::color::Role;
+use unlucky_design::elevation::Elevation;
+use unlucky_design::icons::IconKind;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::typography::TypeRole;
+
+use crate::icons;
+use crate::theme::Ui;
+
+use super::super::interaction::{self, Interaction};
+use super::super::layout;
+use super::geometry::AppBarGeometry;
+
+/// 页头里的一个图标动作。
+#[derive(Debug, Clone)]
+pub struct AppBarAction<M> {
+    icon: IconKind,
+    on_press: Option<M>,
+}
+
+impl<M> AppBarAction<M> {
+    /// 一个可点的图标动作。
+    pub fn new(icon: IconKind, on_press: M) -> Self {
+        Self {
+            icon,
+            on_press: Some(on_press),
+        }
+    }
+
+    /// 一个装饰性图标（无消息）。
+    pub fn inert(icon: IconKind) -> Self {
+        Self {
+            icon,
+            on_press: None,
+        }
+    }
+}
+
+/// 一条 AppBar small。
+#[derive(Debug, Clone)]
+pub struct AppBar<'a, M> {
+    title: &'a str,
+    subtitle: Option<&'a str>,
+    leading: Option<AppBarAction<M>>,
+    trailing: Vec<AppBarAction<M>>,
+    scrolled: bool,
+}
+
+impl<'a, M> AppBar<'a, M> {
+    /// 标题（`TitleLarge`，emphasized）。
+    pub fn new(title: &'a str) -> Self {
+        Self {
+            title,
+            subtitle: None,
+            leading: None,
+            trailing: Vec::new(),
+            scrolled: false,
+        }
+    }
+
+    /// 副标题（`LabelMedium` + `OnSurfaceVariant`）。
+    pub fn subtitle(mut self, subtitle: &'a str) -> Self {
+        self.subtitle = Some(subtitle);
+        self
+    }
+
+    /// 前置动作（导航返回 / 汉堡；`OnSurface`）。
+    pub fn leading(mut self, action: AppBarAction<M>) -> Self {
+        self.leading = Some(action);
+        self
+    }
+
+    /// 追加一个后置动作（`OnSurfaceVariant`）。
+    pub fn trailing(mut self, action: AppBarAction<M>) -> Self {
+        self.trailing.push(action);
+        self
+    }
+
+    /// 滚动状态：`true` = 容器色 `SurfaceContainer` + L2 阴影（A1 `OnScroll*`）。
+    pub fn scrolled(mut self, scrolled: bool) -> Self {
+        self.scrolled = scrolled;
+        self
+    }
+}
+
+/// 一个图标动作按钮（40×40 命中区、图标 24 经 `layout::fixed`——Q9）。
+fn action<'a, M: Clone + 'a>(
+    ui: &'a Ui,
+    action: AppBarAction<M>,
+    geometry: AppBarGeometry,
+    color: Color,
+) -> Element<'a, M> {
+    let hovered =
+        interaction::overlay_color(ui, Interaction::Hovered, Role::OnSurface, Role::Surface);
+    let icon = layout::fixed(
+        geometry.icon,
+        geometry.icon,
+        icons::view::<M>(action.icon, color),
+    );
+    let hit = ui.metrics().control_height;
+    // 图标要落在 40×40 命中区的**正中**：`Container` 默认 `horizontal_alignment: Left`
+    // （`iced_widget-0.14.2/src/container.rs`），只给 `align_y` 会让 24px 图标贴左缘——
+    // 视觉 r1 实测前导墨迹 `38..58`（应 `44..68`）。所以**两轴都显式给**（规则 Q21）。
+    let button = button(
+        container(icon)
+            .width(Length::Fill)
+            .height(Length::Fill)
+            .align_x(Alignment::Center)
+            .align_y(Alignment::Center),
+    )
+    .width(Length::Fixed(hit))
+    .height(Length::Fixed(hit))
+    .padding(0)
+    .style(move |_theme, status| button::Style {
+        background: some_if_hovered(status, hovered),
+        text_color: color,
+        border: Border {
+            // IconButton 的圆角是 full：按命中区边长折算（`radius_dp` 不接受 Full）
+            radius: ui.radius(ShapeScale::Full, hit),
+            ..Border::default()
+        },
+        shadow: Shadow::default(),
+        snap: true,
+    });
+    match action.on_press {
+        Some(message) => button.on_press(message).into(),
+        None => button.into(),
+    }
+}
+
+/// hover 时给背景（`None` 的其他态不叠状态层）。
+fn some_if_hovered(status: button::Status, hovered: Option<Color>) -> Option<Background> {
+    match status {
+        button::Status::Hovered => hovered.map(Background::Color),
+        _ => None,
+    }
+}
+
+/// AppBar small（页头 56 / Surface / 滚动换色）。
+pub fn app_bar<'a, M: Clone + 'a>(ui: &'a Ui, bar: AppBar<'a, M>) -> Element<'a, M> {
+    let geometry = AppBarGeometry::of(ui);
+
+    let title_style = ui.emphasized(TypeRole::TitleLarge);
+    let mut texts = iced::widget::Column::new().spacing(0);
+    texts = texts.push(
+        text(bar.title)
+            .size(title_style.size_px)
+            .line_height(LineHeight::Absolute(Pixels(title_style.line_height_px)))
+            // 单行：页头高固定 56，长标题折行会顶穿页头并与 trailing 动作重叠（偏离 D-M79-5）
+            .wrapping(Wrapping::None)
+            .font(ui.font_of(title_style))
+            .color(ui.color(Role::OnSurface)),
+    );
+    if let Some(subtitle) = bar.subtitle {
+        let style = ui.style(TypeRole::LabelMedium);
+        texts = texts.push(
+            text(subtitle)
+                .size(style.size_px)
+                .line_height(LineHeight::Absolute(Pixels(style.line_height_px)))
+                .wrapping(Wrapping::None)
+                .font(ui.font_of(style))
+                .color(ui.color(Role::OnSurfaceVariant)),
+        );
+    }
+
+    let mut row = iced::widget::Row::new()
+        .align_y(Alignment::Center)
+        .spacing(ui.space(unlucky_design::spacing::Space::X2));
+    if let Some(leading) = bar.leading {
+        // 16.5：leading 图标 `OnSurface`
+        row = row.push(action(ui, leading, geometry, ui.color(Role::OnSurface)));
+    }
+    // 文本块吃掉剩余宽度并**裁切**：这一条同时解决两件事——
+    // ① 标题与 trailing 之间必须有 Fill（M77 Q8 同款），② 单行超长标题切在动作按钮之前，
+    //    不会重叠（`clip(true)` 是 iced 里唯一能裁子元素越界的方式；没有 ellipsis，见 D-M79-5）。
+    row = row.push(container(texts).width(Length::Fill).clip(true));
+    for action_item in bar.trailing {
+        // 16.5：trailing 图标 `OnSurfaceVariant`
+        row = row.push(action(
+            ui,
+            action_item,
+            geometry,
+            ui.color(Role::OnSurfaceVariant),
+        ));
+    }
+
+    let background = if bar.scrolled {
+        ui.color(Role::SurfaceContainer)
+    } else {
+        ui.color(Role::Surface)
+    };
+    let elevation = scroll_elevation(bar.scrolled);
+    let shadow = if matches!(elevation, Elevation::Level0) {
+        Shadow::default()
+    } else {
+        let spec = elevation.shadow();
+        Shadow {
+            color: Color {
+                a: spec.alpha,
+                ..ui.color(Role::Shadow)
+            },
+            offset: Vector::new(0.0, spec.offset_y_px),
+            blur_radius: spec.blur_px,
+        }
+    };
+
+    container(row)
+        .width(Length::Fill)
+        .height(Length::Fixed(geometry.height))
+        // 内容行（40 高的动作按钮 + 文本块）必须落在 56 页头的**垂直中线**上：
+        // `Container` 的 vertical_alignment 默认 Top，只给 `width` 会让整行贴顶
+        // （视觉 r1 实测前导图标墨迹 y=204..223，居中应是 209..227）。
+        .align_y(Alignment::Center)
+        .padding(Padding {
+            top: 0.0,
+            right: geometry.edge,
+            bottom: 0.0,
+            left: geometry.edge,
+        })
+        .style(move |_theme| container::Style {
+            background: Some(Background::Color(background)),
+            border: Border {
+                // 16.3：ContainerShape = CornerNone
+                radius: ui.radius_dp(ShapeScale::None),
+                ..Border::default()
+            },
+            shadow,
+            ..container::Style::default()
+        })
+        .into()
+}
+
+/// 滚动态的高程档（A1 `AppBarTokens.OnScrollContainerElevation`；静息 L0 = `ContainerElevation`）。
+fn scroll_elevation(scrolled: bool) -> Elevation {
+    if scrolled {
+        Elevation::Level2
+    } else {
+        Elevation::Level0
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    use unlucky_design::color::SchemeFlavor;
+    use unlucky_design::typography::Platform;
+
+    use crate::theme::Families;
+
+    fn ui() -> Ui {
+        Ui::with_platform(
+            SchemeFlavor::Light,
+            Platform::Windows,
+            Families {
+                text: "Segoe UI",
+                display: "Segoe UI",
+                mono: "Consolas",
+            },
+        )
+    }
+
+    /// 16.1：页头高 = `LM.page_header_height`（56），并**钉死**它与 A1 的 64 不同。
+    #[test]
+    fn height_is_pinned_to_the_page_header_token() {
+        let ui = ui();
+        let geometry = AppBarGeometry::of(&ui);
+        assert_eq!(geometry.height, ui.metrics().page_header_height);
+        assert_eq!(geometry.height, 56.0);
+        assert_ne!(
+            geometry.height, 64.0,
+            "64 是 A1 AppBarSmallTokens.ContainerHeight；本项目按骨架令牌取 56（D-M79-2）"
+        );
+    }
+
+    /// 16.5 / 16.6：图标 24、左右内边距 4、头像 32。
+    #[test]
+    fn icon_and_edges_come_from_tokens() {
+        let geometry = AppBarGeometry::of(&ui());
+        assert_eq!(geometry.icon, 24.0);
+        assert_eq!(geometry.edge, 4.0);
+        assert_eq!(geometry.avatar, 32.0);
+    }
+
+    /// 「滚动只换色 + 升 L2」：这条把 `OnScroll*` 的两个字段钉住（高度**不在**这里面）。
+    #[test]
+    fn scroll_switches_color_and_elevation_only() {
+        let ui = ui();
+        assert_eq!(scroll_elevation(false), Elevation::Level0);
+        assert_eq!(scroll_elevation(true), Elevation::Level2);
+        // 高度与滚动无关：同一个几何（这条是「滚动不改高度」的可执行声明）
+        assert_eq!(
+            AppBarGeometry::of(&ui).height,
+            ui.metrics().page_header_height,
+            "高度只由骨架令牌决定，没有 OnScroll…Height"
+        );
+    }
+
+    /// 树能建出来（leading + 副标题 + 两个 trailing + 滚动态）。
+    #[test]
+    fn view_builds_a_tree() {
+        let ui = ui();
+        let _: Element<'_, ()> = app_bar(
+            &ui,
+            AppBar::new("Instances")
+                .subtitle("4 instances")
+                .leading(AppBarAction::new(IconKind::Instances, ()))
+                .trailing(AppBarAction::new(IconKind::Settings, ()))
+                .trailing(AppBarAction::inert(IconKind::Logs))
+                .scrolled(true),
+        );
+    }
+}
diff --git a/crates/app-iced/src/components/navigation/drawer.rs b/crates/app-iced/src/components/navigation/drawer.rs
new file mode 100644
index 0000000..2a8a690
--- /dev/null
+++ b/crates/app-iced/src/components/navigation/drawer.rs
@@ -0,0 +1,140 @@
+//! NavigationDrawer / NavigationRail（`research/15` §21 + 12b §5）：**同一个容器的两个宽度**（D33）。
+//!
+//! 本文件只装「容器」：宽度（88 ⇄ 240）、`CornerLargeEnd` 圆角、分组标题、组间分隔线。
+//! 一项长什么样（`NavItem` / `NavGroup` / 颜色求值 / 药丸排布）在 `drawer/item.rs`。
+//!
+//! ## 参考值与 D33（详见 `geometry.rs` 的表）
+//!
+//! ```text
+//! 折叠 = Rail   88  = LayoutMetrics::nav_rail_width    项高 52 = 药丸 32 + 4 + 标签 16
+//! 展开 = Drawer 240 = LayoutMetrics::nav_drawer_width  项高 56 = A1 ActiveIndicatorHeight（G24）
+//! 药丸：rail 88 − 2×16 = 56（M68 的 56×32）；drawer 240 − 2×12 = 216（= A1 的 360 − 2×12）
+//! ```
+//!
+//! 两者共用 [`navigation`] 一个入口、一套颜色角色、一套 full 圆角药丸；切换时圆角语言不变，
+//! 一屏导航容器数恒为 1（§21.9）。**不是两套组件**——D33 的可验收形式就是「同一函数两个宽度」。
+//!
+//! ## Q8 的现场
+//!
+//! M68 的药丸写 56 宽后用 `center_x(Length::Fill)` 居中，容器尺寸被 Fill 覆盖成 88 宽（图上横贯全轨）。
+//! 这里药丸宽由 [`NavPaneGeometry::pill_width`] 给出，居中一律交给父级 `align_x`。
+//!
+//! ## 分组标题（只 drawer 侧，§21.8）
+//!
+//! `TitleSmall` + `OnSurfaceVariant`，**不可点**；组与组之间 1px `OutlineVariant`
+//! （复用 [`crate::app::components::divider`]），不用背景色块分区。
+
+use iced::widget::container;
+use iced::{Background, Border, Element, Length, Padding};
+
+use unlucky_design::color::Role;
+use unlucky_design::elevation::MaterialLayer;
+use unlucky_design::typography::TypeRole;
+
+use crate::theme::Ui;
+
+use super::super::divider;
+use super::geometry::{NavLayout, NavPaneGeometry};
+
+mod item;
+use item::{line, nav_row};
+pub use item::{NavGroup, NavItem};
+
+/// 导航容器（D33：`layout` 决定 88 还是 240，其余全同）。
+#[derive(Debug, Clone)]
+pub struct Navigation<'a, M> {
+    layout: NavLayout,
+    groups: Vec<NavGroup<'a, M>>,
+}
+
+impl<'a, M> Navigation<'a, M> {
+    /// 折叠态：rail（88）。
+    pub fn rail() -> Self {
+        Self {
+            layout: NavLayout::Rail,
+            groups: Vec::new(),
+        }
+    }
+
+    /// 展开态：标准常驻 drawer（240）。
+    pub fn drawer() -> Self {
+        Self {
+            layout: NavLayout::Drawer,
+            groups: Vec::new(),
+        }
+    }
+
+    /// 追加分组（组间自动画 1px `OutlineVariant`）。
+    pub fn group(mut self, group: NavGroup<'a, M>) -> Self {
+        self.groups.push(group);
+        self
+    }
+}
+
+/// 导航容器（rail ⇄ drawer 的唯一入口）。
+pub fn navigation<'a, M: Clone + 'a>(ui: &'a Ui, nav: Navigation<'a, M>) -> Element<'a, M> {
+    let geometry = NavPaneGeometry::of(ui, nav.layout);
+    let gap = match nav.layout {
+        NavLayout::Rail => ui.metrics().nav_item_gap,
+        // drawer 的项是紧贴的（56 已经含了内部留白，§21.4）
+        NavLayout::Drawer => 0.0,
+    };
+
+    let mut body = iced::widget::Column::new().spacing(gap).width(Length::Fill);
+    for (index, group) in nav.groups.into_iter().enumerate() {
+        // 组间分隔线只属于 drawer：rail 88 宽里一条通栏线只会切碎药丸的节奏（§21.8 的分区是 drawer 语义）
+        if index > 0 && matches!(nav.layout, NavLayout::Drawer) {
+            body = body.push(container(divider::full::<M>(ui)).padding(Padding {
+                top: ui.space(unlucky_design::spacing::Space::X2),
+                bottom: ui.space(unlucky_design::spacing::Space::X2),
+                left: 0.0,
+                right: 0.0,
+            }));
+        }
+        // 标题只在 drawer 侧出现（rail 88 宽放不下文字，§21.8 的分区是 drawer 语义）
+        if let (NavLayout::Drawer, Some(title)) = (nav.layout, group.title) {
+            body = body.push(
+                container(line::<M>(
+                    ui,
+                    title,
+                    TypeRole::TitleSmall,
+                    ui.color(Role::OnSurfaceVariant),
+                ))
+                .width(Length::Fill)
+                .padding(Padding {
+                    top: ui.space(unlucky_design::spacing::Space::X2),
+                    right: geometry.pad_start,
+                    bottom: ui.space(unlucky_design::spacing::Space::X1),
+                    left: geometry.pill_inset + geometry.pad_start,
+                }),
+            );
+        }
+        for item in group.items {
+            body = body.push(nav_row(ui, item, geometry));
+        }
+    }
+
+    container(body)
+        .width(Length::Fixed(geometry.width))
+        .height(Length::Fill)
+        // 轨顶留白走 padding（不是 spacer 元素：会被 column 的 spacing 再加一档，M68 P3-5）
+        .padding(Padding {
+            top: ui.space(unlucky_design::spacing::Space::X6),
+            right: 0.0,
+            bottom: 0.0,
+            left: 0.0,
+        })
+        .style(move |_theme| container::Style {
+            // §21.3 标准（常驻）= Surface + L0；形状 CornerLargeEnd（内侧两角 16）
+            background: Some(Background::Color(ui.layer(MaterialLayer::Canvas))),
+            border: Border {
+                radius: geometry.radius,
+                ..Border::default()
+            },
+            ..container::Style::default()
+        })
+        .into()
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/app-iced/src/components/navigation/drawer/item.rs b/crates/app-iced/src/components/navigation/drawer/item.rs
new file mode 100644
index 0000000..4b4a667
--- /dev/null
+++ b/crates/app-iced/src/components/navigation/drawer/item.rs
@@ -0,0 +1,296 @@
+//! 导航项的公共类型与一行渲染（`drawer.rs` 的私有子模块：单文件 ≤400 行，AGENTS.md §3-1）。
+//!
+//! 拆出去的是「一项长什么样」（`NavItem` / `NavGroup` + 颜色求值 + 一行布局），
+//! `drawer.rs` 只留「容器长什么样」（宽度、圆角、分组标题、分隔线）。
+
+use iced::widget::text::{LineHeight, Wrapping};
+use iced::widget::{button, container, text};
+use iced::{Alignment, Background, Border, Color, Element, Length, Padding, Pixels, Shadow};
+
+use unlucky_design::color::Role;
+use unlucky_design::icons::IconKind;
+use unlucky_design::typography::TypeRole;
+
+use crate::icons;
+use crate::theme::Ui;
+
+use super::super::super::interaction::{self, Interaction};
+use super::super::super::layout;
+use super::super::geometry::{NavLayout, NavPaneGeometry};
+
+/// 一条导航项。
+#[derive(Debug, Clone)]
+pub struct NavItem<'a, M> {
+    pub(super) label: &'a str,
+    pub(super) icon: IconKind,
+    pub(super) selected: bool,
+    pub(super) on_press: Option<M>,
+    pub(super) state: Option<Interaction>,
+}
+
+impl<'a, M> NavItem<'a, M> {
+    /// 一个可点的导航项（图标 + 文案）。
+    pub fn new(label: &'a str, icon: IconKind, on_press: M) -> Self {
+        Self {
+            label,
+            icon,
+            selected: false,
+            on_press: Some(on_press),
+            state: None,
+        }
+    }
+
+    /// 当前项（药丸 + `OnSecondaryContainer`）。
+    pub fn selected(mut self) -> Self {
+        self.selected = true;
+        self
+    }
+
+    /// 强制视觉态（gallery 取证；不动状态机）。
+    pub fn state(mut self, state: Interaction) -> Self {
+        self.state = Some(state);
+        self
+    }
+
+    /// 转禁用：**只清消息**（修饰器；图标 / 选中态 / 槽位全部保留）。
+    pub fn disabled(mut self) -> Self {
+        self.on_press = None;
+        self
+    }
+}
+
+/// 一个分组（drawer 侧可带标题；rail 侧标题会被忽略——rail 只有图标）。
+#[derive(Debug, Clone)]
+pub struct NavGroup<'a, M> {
+    pub(super) title: Option<&'a str>,
+    pub(super) items: Vec<NavItem<'a, M>>,
+}
+
+impl<'a, M> NavGroup<'a, M> {
+    /// 无标题分组。
+    pub fn new() -> Self {
+        Self {
+            title: None,
+            items: Vec::new(),
+        }
+    }
+
+    /// 带标题分组（§21.8：`TitleSmall` + `OnSurfaceVariant`，不可点）。
+    pub fn titled(title: &'a str) -> Self {
+        Self {
+            title: Some(title),
+            items: Vec::new(),
+        }
+    }
+
+    /// 追加一项。
+    pub fn item(mut self, item: NavItem<'a, M>) -> Self {
+        self.items.push(item);
+        self
+    }
+}
+
+impl<'a, M> Default for NavGroup<'a, M> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+/// 一项的颜色（按态 + 选中求值）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub(super) struct ItemPalette {
+    /// 药丸底色（`None` = 不画药丸 / 不叠状态层）。
+    pub(super) pill: Option<Color>,
+    /// 图标色。
+    pub(super) icon: Color,
+    /// 标签色。
+    pub(super) label: Color,
+}
+
+pub(super) fn palette(
+    ui: &Ui,
+    layout: NavLayout,
+    state: Interaction,
+    selected: bool,
+) -> ItemPalette {
+    if state.is_disabled() {
+        let ink = interaction::disabled_content_over_role(ui, Role::OnSurface, false);
+        return ItemPalette {
+            pill: None,
+            icon: ink,
+            label: ink,
+        };
+    }
+
+    if selected {
+        let pill = interaction::overlay_color(
+            ui,
+            state,
+            Role::OnSecondaryContainer,
+            Role::SecondaryContainer,
+        )
+        .unwrap_or_else(|| ui.color(Role::SecondaryContainer));
+        return ItemPalette {
+            pill: Some(pill),
+            icon: ui.color(Role::OnSecondaryContainer),
+            // rail 的选中标签是 `Secondary`（12b 5.6）；drawer 是 `OnSecondaryContainer`（§21.7）
+            label: match layout {
+                NavLayout::Rail => ui.color(Role::Secondary),
+                NavLayout::Drawer => ui.color(Role::OnSecondaryContainer),
+            },
+        };
+    }
+
+    // 未选中：静息 `OnSurfaceVariant`，hover/focus/pressed 提到 `OnSurface`
+    let ink = match state {
+        Interaction::Enabled => ui.color(Role::OnSurfaceVariant),
+        _ => ui.color(Role::OnSurface),
+    };
+    ItemPalette {
+        pill: interaction::overlay_color(ui, state, Role::OnSurface, Role::Surface),
+        icon: ink,
+        label: ink,
+    }
+}
+
+/// 一块文字（显式行高，让项高与行高对得上）。
+pub(super) fn line<'a, M: 'a>(
+    ui: &'a Ui,
+    value: &'a str,
+    role: TypeRole,
+    color: Color,
+) -> Element<'a, M> {
+    let style = ui.style(role);
+    text(value)
+        .size(style.size_px)
+        .line_height(LineHeight::Absolute(Pixels(style.line_height_px)))
+        // 单行（项高固定 52/56）：长分组名/实例名不许折行（偏离 D-M79-5）
+        .wrapping(Wrapping::None)
+        .font(ui.font_of(style))
+        .color(color)
+        .into()
+}
+
+/// 一项（rail：图标在上、标签在下；drawer：图标在左、标签在右）。
+pub(super) fn nav_row<'a, M: Clone + 'a>(
+    ui: &'a Ui,
+    item: NavItem<'a, M>,
+    geometry: NavPaneGeometry,
+) -> Element<'a, M> {
+    let forced = item.state.or(if item.on_press.is_none() {
+        Some(Interaction::Disabled)
+    } else {
+        None
+    });
+    let state = forced.unwrap_or(Interaction::Enabled);
+    let colors = palette(ui, geometry.layout, state, item.selected);
+    let radius = iced::border::Radius::new(geometry.pill_height / 2.0);
+
+    let icon = layout::fixed(
+        geometry.icon,
+        geometry.icon,
+        icons::view::<M>(item.icon, colors.icon),
+    );
+
+    // 药丸本体：宽高都来自几何（rail 56×32 / drawer 216×56），居中交给父级 align_x
+    let pill = move |content: Element<'a, M>| -> Element<'a, M> {
+        let fill = colors.pill;
+        container(content)
+            .width(Length::Fixed(geometry.pill_width))
+            .height(Length::Fixed(geometry.pill_height))
+            .align_x(Alignment::Center)
+            .align_y(Alignment::Center)
+            .style(move |_theme| container::Style {
+                background: fill.map(Background::Color),
+                border: Border {
+                    radius,
+                    ..Border::default()
+                },
+                ..container::Style::default()
+            })
+            .into()
+    };
+
+    let body: Element<'a, M> = match geometry.layout {
+        NavLayout::Rail => {
+            // rail：药丸（56×32，图标居中）+ 4 + 标签（LabelMedium）
+            let mut stack = iced::widget::Column::new()
+                .spacing(geometry.gap)
+                .width(Length::Fixed(geometry.width))
+                .align_x(Alignment::Center);
+            stack = stack.push(pill(icon));
+            // 标签要裁到轨宽：单行超长时切在 88 内，不会溢出到内容区（D-M79-5）
+            stack = stack.push(
+                container(line::<M>(
+                    ui,
+                    item.label,
+                    TypeRole::LabelMedium,
+                    colors.label,
+                ))
+                .width(Length::Fixed(geometry.width))
+                .align_x(Alignment::Center)
+                .clip(true),
+            );
+            stack.into()
+        }
+        NavLayout::Drawer => {
+            // drawer：药丸就是一整行（216×56），内容从 pad_start 16 起、图标↔label 12
+            let row = iced::widget::Row::new()
+                .align_y(Alignment::Center)
+                .spacing(geometry.gap)
+                .padding(Padding {
+                    top: 0.0,
+                    right: geometry.pad_end,
+                    bottom: 0.0,
+                    left: geometry.pad_start,
+                });
+            // label 吃掉剩余宽度并裁切（单行 + 不压到药丸右内边距，D-M79-5）
+            pill(Element::from(
+                row.push(icon)
+                    .push(
+                        container(line::<M>(
+                            ui,
+                            item.label,
+                            TypeRole::LabelLarge,
+                            colors.label,
+                        ))
+                        .width(Length::Fill)
+                        .clip(true),
+                    )
+                    .width(Length::Fill),
+            ))
+        }
+    };
+
+    let height = geometry.item_height;
+    let clickable = button(body)
+        .width(Length::Fill)
+        .height(Length::Fixed(height))
+        .padding(0)
+        .style(move |_theme, _status| button::Style {
+            // 底色由药丸给（rail 的 hover 层也画在药丸上，与 drawer 同口径）
+            background: None,
+            text_color: colors.label,
+            border: Border::default(),
+            shadow: Shadow::default(),
+            snap: true,
+        });
+    let element: Element<'a, M> = match item.on_press {
+        Some(message) => clickable.on_press(message).into(),
+        None => clickable.into(),
+    };
+
+    // drawer 的项外距 12（`ItemPadding`）：药丸两侧由内缩给出，所以整行再包一层水平内边距
+    match geometry.layout {
+        NavLayout::Drawer => container(element)
+            .width(Length::Fill)
+            .padding(Padding {
+                top: 0.0,
+                right: geometry.pill_inset,
+                bottom: 0.0,
+                left: geometry.pill_inset,
+            })
+            .into(),
+        NavLayout::Rail => element,
+    }
+}
diff --git a/crates/app-iced/src/components/navigation/drawer/tests.rs b/crates/app-iced/src/components/navigation/drawer/tests.rs
new file mode 100644
index 0000000..c160951
--- /dev/null
+++ b/crates/app-iced/src/components/navigation/drawer/tests.rs
@@ -0,0 +1,115 @@
+//! `drawer` 的单元测试（单文件 ≤400 行，AGENTS.md §3-1 拆出来）。
+
+use super::super::super::interaction::{self, Interaction};
+use super::item::palette;
+use super::*;
+
+use unlucky_design::color::SchemeFlavor;
+use unlucky_design::icons::IconKind;
+use unlucky_design::typography::Platform;
+
+use crate::theme::Families;
+
+fn ui() -> Ui {
+    Ui::with_platform(
+        SchemeFlavor::Light,
+        Platform::Windows,
+        Families {
+            text: "Segoe UI",
+            display: "Segoe UI",
+            mono: "Consolas",
+        },
+    )
+}
+
+/// §21.7：选中项图标/标签都是 `OnSecondaryContainer`，药丸 `SecondaryContainer`。
+#[test]
+fn drawer_selected_uses_secondary_container() {
+    let ui = ui();
+    let palette = palette(&ui, NavLayout::Drawer, Interaction::Enabled, true);
+    assert_eq!(palette.pill, Some(ui.color(Role::SecondaryContainer)));
+    assert_eq!(palette.icon, ui.color(Role::OnSecondaryContainer));
+    assert_eq!(palette.label, ui.color(Role::OnSecondaryContainer));
+}
+
+/// 12b §5.6：**rail** 的选中标签是 `Secondary`（与 drawer 不同，别串线）。
+#[test]
+fn rail_selected_label_is_secondary() {
+    let ui = ui();
+    let rail = palette(&ui, NavLayout::Rail, Interaction::Enabled, true);
+    let drawer = palette(&ui, NavLayout::Drawer, Interaction::Enabled, true);
+    assert_eq!(rail.label, ui.color(Role::Secondary));
+    assert_ne!(rail.label, drawer.label, "两条线的选中标签角色不同");
+    // 但图标与药丸相同（同一套语言）
+    assert_eq!(rail.icon, drawer.icon);
+    assert_eq!(rail.pill, drawer.pill);
+}
+
+/// 未选中：静息 `OnSurfaceVariant`；hover/focus/pressed 提到 `OnSurface` 且叠状态层。
+#[test]
+fn inactive_lifts_to_on_surface() {
+    let ui = ui();
+    let resting = palette(&ui, NavLayout::Drawer, Interaction::Enabled, false);
+    assert_eq!(resting.label, ui.color(Role::OnSurfaceVariant));
+    assert_eq!(resting.pill, None);
+    for state in [
+        Interaction::Hovered,
+        Interaction::Focused,
+        Interaction::Pressed,
+    ] {
+        let active = palette(&ui, NavLayout::Drawer, state, false);
+        assert_eq!(active.label, ui.color(Role::OnSurface), "{state:?}");
+        assert_eq!(active.icon, ui.color(Role::OnSurface), "{state:?}");
+        assert!(active.pill.is_some(), "{state:?} 必须叠状态层");
+    }
+}
+
+/// 禁用：`OnSurface`@38%，不画药丸，不叠状态层。
+#[test]
+fn disabled_draws_no_pill() {
+    let ui = ui();
+    let palette = palette(&ui, NavLayout::Drawer, Interaction::Disabled, true);
+    assert_eq!(
+        palette.icon,
+        interaction::disabled_content_over_role(&ui, Role::OnSurface, false)
+    );
+    assert_eq!(palette.label, palette.icon);
+    assert_eq!(palette.pill, None);
+}
+
+/// 禁用是**修饰器**：只清消息，图标 / 选中态全部保留。
+#[test]
+fn disabled_only_clears_the_message() {
+    let item = NavItem::new("Settings", IconKind::Settings, ())
+        .selected()
+        .disabled();
+    assert!(item.on_press.is_none());
+    assert!(item.selected);
+    assert_eq!(item.icon, IconKind::Settings);
+    assert_eq!(item.label, "Settings");
+}
+
+/// D33：两种宽度都能建出树（同一个 `navigation` 入口）。
+#[test]
+fn both_layouts_build_a_tree() {
+    let ui = ui();
+    for layout in NavLayout::ALL {
+        let base = match layout {
+            NavLayout::Rail => Navigation::rail(),
+            NavLayout::Drawer => Navigation::drawer(),
+        };
+        let _: Element<'_, ()> = navigation(
+            &ui,
+            base.group(
+                NavGroup::titled("LIBRARY")
+                    .item(NavItem::new("Instances", IconKind::Instances, ()).selected())
+                    .item(NavItem::new("Download", IconKind::Download, ())),
+            )
+            .group(NavGroup::titled("SYSTEM").item(NavItem::new(
+                "Settings",
+                IconKind::Settings,
+                (),
+            ))),
+        );
+    }
+}
diff --git a/crates/app-iced/src/components/navigation/geometry.rs b/crates/app-iced/src/components/navigation/geometry.rs
new file mode 100644
index 0000000..1e1b88e
--- /dev/null
+++ b/crates/app-iced/src/components/navigation/geometry.rs
@@ -0,0 +1,333 @@
+//! 导航类家族的**几何**：能取令牌的取令牌，取不到的在此登记 G 编号（不散落在组件里）。
+//!
+//! ## 参考值 → 落点（`[源]` = A1，`material3-android:1.4.0`；本轮逐条用 `javap` 读本机 AAR 复核）
+//!
+//! ```text
+//! javap -p -c androidx.compose.material3.tokens.ListTokens          → 56/72/88、16/16、图标 24
+//! javap -p -c androidx.compose.material3.tokens.NavigationDrawerTokens
+//!      → ActiveIndicatorHeight 56、ActiveIndicatorWidth 336、ContainerWidth 360、CornerLargeEnd
+//! javap -p -c androidx.compose.material3.NavigationDrawerItemDefaults
+//!      → ItemPadding = 12（bipush 12 → PaddingValues(12f, 0f)）
+//! javap -p -c androidx.compose.material3.tokens.PrimaryNavigationTabTokens
+//!      → ContainerHeight 48、IconAndLabelTextContainerHeight 64、ActiveIndicatorHeight 3、图标 24
+//! javap -p -c androidx.compose.material3.tokens.SecondaryNavigationTabTokens → ContainerHeight 48
+//! javap -p -c androidx.compose.material3.tokens.AppBarSmallTokens   → ContainerHeight 64
+//! ```
+//!
+//! | # | 量 | 参考值（A1） | 本项目 | 来源 | 落点 |
+//! |---|---|---|---|---|---|
+//! | 4.1 | ListItem 一行高 | **56** | **44** = `LM.row_height`（登记偏离 −12） | `[源]` `ListItemOneLineContainerHeight` | [`ListItemGeometry::heights`] |
+//! | 4.2 | ListItem 两/三行高 | **72 / 88** | **60 / 76**（每多一行 +16，与官方同 delta） | `[源]` | 同上 |
+//! | 4.3 | ListItem 左右内边距 | **16 / 16** | 同 | `[源]` `ListItemLeading/TrailingSpace` | `pad_start` / `pad_end` |
+//! | 4.4 | ListItem leading 图标 | **24** | 同 | `[源]` `ListItemLeadingIconSize` | `icon`（`IconSize::Toolbar`） |
+//! | 4.4b | 图标 ↔ 文本间距 | 无 token | **16** | `[估]`（Compose 由 ListItem 内部排版决定） | `gap`（`Space::X4`） |
+//! | 6.1 | Tabs 容器高 | **48**（带图标 **64**） | 同 | `[源]` | [`TABS_HEIGHT`]（**G22**：`LM` 无此档） |
+//! | 6.2 | 指示条 | 高 **3**、圆角 **3**、`Primary` | 同 | `[源]` `ActiveIndicatorHeight` + `RoundedCornerShape(3dp)` | [`TABS_INDICATOR`]（**G23**） |
+//! | 6.6 | Secondary 分隔线 | **1dp `SurfaceVariant`** | 同 | `[源]` `DividerHeight` / `DividerColor` | [`TabsGeometry::secondary_bar`] |
+//! | 21.4 | drawer 项高 | **56**（`heightIn(min = ActiveIndicatorHeight)`） | **56**（`LM.nav_item_height` 是 44，登记偏离 +12） | `[源]` | [`DRAWER_ITEM_HEIGHT`]（**G24**） |
+//! | 21.5 | drawer 指示器 | 宽 = 容器宽 − **24**（360 → 336）；高 = 项高；圆角 full | 240 − 24 = **216** | `[源]` `ItemPadding = 12` | [`NavPaneGeometry::pill_width`] |
+//! | 21.6 | drawer 项内 | 项外 **12**；内 start **16** / end **24**；图标 24；图标↔label **12**；label `LabelLarge` | 同 | `[源]` `ItemPadding` + `navigation/15 §21.6` | [`ComponentMetrics::NAVIGATION_DRAWER`] |
+//! | 21.2 | drawer 形状 | **`CornerLargeEnd`**（只有靠内容那侧两角 16，贴边侧直角） | 同（右两角 16） | `[源]` `ContainerShape` | [`NavPaneGeometry::radius`] |
+//! | 16.1 | AppBar small 高 | **64** | **56** = `LM.page_header_height`（登记偏离 −8） | `[源]` `AppBarSmallTokens.ContainerHeight` | [`AppBarGeometry::height`] |
+//! | 16.5/16.6 | AppBar 图标 / 左右内边距 | **24** / **4** | 同 | `[源]` `AppBarTokens.IconSize/LeadingSpace/TrailingSpace` | [`AppBarGeometry`] |
+//!
+//! **G 编号**（续 `research/15` §25 的 G13；G16~G20 已被 selection/inputs 用掉）：
+//!
+//! - **G22** Tabs 容器高 48 / 带图标 64：`LayoutMetrics` 无此档，收在本文件的 [`TABS_HEIGHT`]；
+//! - **G23** Tabs 指示条高 3 / 最小项宽 90：同上，收在本文件 [`TABS_INDICATOR`]，
+//!   而**最小项宽 90（`TabMinWidth`）本轮不施加**——iced 无 min-width，tab 按内容 hug，
+//!   指示条因此严格等于「该 tab 的内容宽 + 2×16」，见 [`TabsGeometry::pad`] 的说明；
+//! - **G24** drawer 项高 56：令牌 `LM.nav_item_height = 44` 是**列表行**的密集档，drawer 项按 A1 取 56。
+//!
+//! ## 两个「同一个容器两个宽度」（D33）
+//!
+//! [`NavPaneGeometry::of`] 是**唯一**一处同时知道 88 与 240 的地方：宽 → 药丸宽、项高、内边距
+//! 全部由 `layout` 派生。Q8 的历史事故（药丸 56×32 被 `center_x(Fill)` 撑成 88×32）就出在
+//! 「药丸宽度不是从容器宽派生」——这里把派生写成函数，组件层拿不到手写数字。
+
+use iced::border::Radius;
+
+use unlucky_design::component_map::{Component, ComponentMetrics};
+use unlucky_design::icons::IconSize;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::Space;
+
+use crate::theme::Ui;
+
+/// Tabs 容器高（A1 `PrimaryNavigationTabTokens.ContainerHeight`，**G22**）。
+pub const TABS_HEIGHT: f32 = 48.0;
+/// 带图标的 Tabs 容器高（A1 `IconAndLabelTextContainerHeight`，**G22**；本轮只做文字档）。
+pub const TABS_ICON_HEIGHT: f32 = 64.0;
+/// Tabs 指示条高（A1 `PrimaryNavigationTabTokens.ActiveIndicatorHeight`，**G23**）。
+pub const TABS_INDICATOR: f32 = 3.0;
+/// drawer 项高（A1 `NavigationDrawerItemDefaults` 的 `heightIn(min = ActiveIndicatorHeight)`，**G24**）。
+pub const DRAWER_ITEM_HEIGHT: f32 = 56.0;
+
+/// 导航容器的两种宽度（D33：**同一个容器**的折叠 / 展开，不是两套组件）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum NavLayout {
+    /// 折叠：宽 **88**（`LayoutMetrics::nav_rail_width`），项内「药丸在上、标签在下」。
+    Rail,
+    /// 展开：宽 **240**（`LayoutMetrics::nav_drawer_width`），项内「图标在左、标签在右」。
+    Drawer,
+}
+
+impl NavLayout {
+    /// 两种宽度（gallery）与测试用。
+    pub const ALL: [NavLayout; 2] = [NavLayout::Rail, NavLayout::Drawer];
+
+    /// 稳定名字（截图文件名 / 图例用）。
+    pub const fn name(self) -> &'static str {
+        match self {
+            NavLayout::Rail => "rail",
+            NavLayout::Drawer => "drawer",
+        }
+    }
+}
+
+/// ListItem 的几何（`research/12b` §4）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct ListItemGeometry {
+    /// 一 / 两 / 三行行高（44 / 60 / 76；A1 是 56 / 72 / 88，本项目登记偏离 −12）。
+    pub heights: [f32; 3],
+    /// 内容起始侧内边距（16，A1 `ListItemLeadingSpace`）。
+    pub pad_start: f32,
+    /// 内容结束侧内边距（16，A1 `ListItemTrailingSpace`）。
+    pub pad_end: f32,
+    /// leading / trailing 图标边长（24，A1 `ListItemLeading/TrailingIconSize`）。
+    pub icon: f32,
+    /// 图标 ↔ 文本间距（16，`[估]`）。
+    pub gap: f32,
+}
+
+impl ListItemGeometry {
+    /// 从令牌求值。
+    pub fn of(ui: &Ui) -> Self {
+        let one = ui.metrics().row_height;
+        let step = ui.space(Space::X4);
+        Self {
+            // 每多一行 +16：与官方 56→72→88 的 delta 一致，差的只是基准值（−12）。
+            heights: [one, one + step, one + step * 2.0],
+            pad_start: ui.space(Space::X4),
+            pad_end: ui.space(Space::X4),
+            icon: IconSize::Toolbar.px(),
+            gap: ui.space(Space::X4),
+        }
+    }
+
+    /// `lines` 行的行高（1/2/3 之外按就近夹取，不 panic——调用方传入的是枚举值）。
+    pub fn height(&self, lines: usize) -> f32 {
+        self.heights[lines.clamp(1, 3) - 1]
+    }
+
+    /// `lines` 行的文本块高（行高 − 文本块 = 上下各一半的内边距）。
+    pub fn text_block(&self, ui: &Ui, lines: usize) -> f32 {
+        let headline = ui.style(typography_headline()).line_height_px;
+        match lines.clamp(1, 3) {
+            // 一行：主文本（BodyLarge 24）
+            1 => headline,
+            // 两行：主 + 辅助（BodyLarge 24 + BodyMedium 20）
+            2 => headline + ui.style(typography_supporting()).line_height_px,
+            // 三行：overline（LabelSmall 16）+ 主 + 辅助
+            _ => {
+                ui.style(typography_overline()).line_height_px
+                    + headline
+                    + ui.style(typography_supporting()).line_height_px
+            }
+        }
+    }
+
+    /// 垂直内边距 = (行高 − 文本块) / 2（一行 44 → 10，两行 60 → 8，三行 76 → 8）。
+    pub fn pad_y(&self, ui: &Ui, lines: usize) -> f32 {
+        (self.height(lines) - self.text_block(ui, lines)) / 2.0
+    }
+}
+
+/// ListItem 主文本字级（12b 4.5：`BodyLarge 16/24` `[源] ListTokens.ListItemLabelTextFont`）。
+pub const fn typography_headline() -> unlucky_design::typography::TypeRole {
+    unlucky_design::typography::TypeRole::BodyLarge
+}
+
+/// ListItem 辅助文本字级（12b 4.5：`BodyMedium 14/20`）。
+pub const fn typography_supporting() -> unlucky_design::typography::TypeRole {
+    unlucky_design::typography::TypeRole::BodyMedium
+}
+
+/// ListItem overline 字级（12b 4.5：`LabelSmall 11/16`）。
+pub const fn typography_overline() -> unlucky_design::typography::TypeRole {
+    unlucky_design::typography::TypeRole::LabelSmall
+}
+
+/// Tabs 的几何（`research/12b` §6）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct TabsGeometry {
+    /// 容器高（48，**G22**）。
+    pub height: f32,
+    /// 图标边长（24，A1 `Primary/SecondaryNavigationTabTokens.IconSize`）。
+    pub icon: f32,
+    /// 标签左右内边距（16，`[估]`：Compose `TabRow` 的 `HorizontalTextPadding`）。
+    ///
+    /// 这条同时决定「指示条跟随选中项宽度」的**可测形态**：指示条宽 = 标签墨迹宽 + 2×16，
+    /// 所以两段文案长度不同的 tab，其指示条宽度必然不同（渲染层断言用它）。
+    pub pad: f32,
+    /// Primary 指示条高（3，**G23**）。
+    pub primary_bar: f32,
+    /// Secondary 分隔线厚度（1 = `LM.divider_thickness`）。
+    pub secondary_bar: f32,
+}
+
+impl TabsGeometry {
+    /// 从令牌求值。
+    pub fn of(ui: &Ui) -> Self {
+        Self {
+            height: TABS_HEIGHT,
+            icon: IconSize::Toolbar.px(),
+            pad: ui.space(Space::X4),
+            primary_bar: TABS_INDICATOR,
+            secondary_bar: ui.metrics().divider_thickness,
+        }
+    }
+
+    /// 指示条 / 分隔线高度：Primary 取 3px，Secondary 取 1px。
+    pub fn bar(&self, primary: bool) -> f32 {
+        if primary {
+            self.primary_bar
+        } else {
+            self.secondary_bar
+        }
+    }
+
+    /// Primary 指示条圆角：`RoundedCornerShape(3dp)` 落在 3px 高的条上，与 `Full`（=1.5 半径）渲染结果相同。
+    ///
+    /// Secondary 的 1px 分隔线**没有圆角**：A1 是一条直线；早先给 0.5 圆角，相邻 tab 的分段之间
+    /// 因此留下 1px 亮缝（视觉 r1 P2-2 实测 `25..101 | 103..191 | 193..265`）。
+    pub fn indicator_radius(&self) -> Radius {
+        Radius::new(self.primary_bar / 2.0)
+    }
+}
+
+/// 导航容器（rail ⇄ drawer）的几何（`research/15` §21 + D33）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct NavPaneGeometry {
+    /// 哪种宽度（88 / 240）。
+    pub layout: NavLayout,
+    /// 容器宽（88 / 240）。
+    pub width: f32,
+    /// 项高（rail 52 = 药丸 32 + 4 + 标签 16；drawer 56，**G24**）。
+    pub item_height: f32,
+    /// 选中药丸宽（rail 56 = 88 − 2×16；drawer 216 = 240 − 2×12）。
+    pub pill_width: f32,
+    /// 选中药丸高（rail 32；drawer 56 = 项高）。
+    pub pill_height: f32,
+    /// 药丸离容器左右各缩多少（rail 16；drawer 12 = `ItemPadding`）。
+    pub pill_inset: f32,
+    /// 内容起始侧内边距（drawer 16；rail 由药丸居中决定）。
+    pub pad_start: f32,
+    /// 内容结束侧内边距（drawer 24）。
+    pub pad_end: f32,
+    /// 图标边长（24）。
+    pub icon: f32,
+    /// 图标 ↔ 标签间距（rail 是纵向 4；drawer 是横向 12）。
+    pub gap: f32,
+    /// 容器圆角（`CornerLargeEnd`：贴边侧直角、靠内容侧 16）。
+    pub radius: Radius,
+}
+
+impl NavPaneGeometry {
+    /// 从令牌求值：**88 与 240 只在这里分叉**，其余全部由宽度派生。
+    pub fn of(ui: &Ui, layout: NavLayout) -> Self {
+        let metrics = ui.metrics();
+        let item = drawer_metrics();
+        // CornerLargeEnd：只有靠内容那一侧（右侧）两角 16，贴边侧直角。
+        let corner = shape_radius();
+        let radius = Radius {
+            top_left: 0.0,
+            top_right: corner,
+            bottom_right: corner,
+            bottom_left: 0.0,
+        };
+
+        match layout {
+            NavLayout::Rail => {
+                let width = metrics.nav_rail_width;
+                let pill_inset = ui.space(Space::X4);
+                let pill_height = metrics.control_height - ui.space(Space::X2);
+                Self {
+                    layout,
+                    width,
+                    // 52 = 药丸 32 + 4 + 标签行高 16（与 `shell/nav.rs` 的项高同源）
+                    item_height: pill_height
+                        + ui.space(Space::X1)
+                        + ui.style(unlucky_design::typography::TypeRole::LabelMedium)
+                            .line_height_px,
+                    pill_width: width - pill_inset * 2.0,
+                    pill_height,
+                    pill_inset,
+                    pad_start: pill_inset,
+                    pad_end: pill_inset,
+                    icon: IconSize::Toolbar.px(),
+                    gap: ui.space(Space::X1),
+                    radius,
+                }
+            }
+            NavLayout::Drawer => {
+                let width = metrics.nav_drawer_width;
+                Self {
+                    layout,
+                    width,
+                    item_height: DRAWER_ITEM_HEIGHT,
+                    pill_width: item.indicator_width(width),
+                    pill_height: DRAWER_ITEM_HEIGHT,
+                    pill_inset: item.inset,
+                    pad_start: item.pad_start,
+                    pad_end: item.pad_end,
+                    icon: item.icon,
+                    gap: item.gap,
+                    radius,
+                }
+            }
+        }
+    }
+}
+
+/// 导航容器的组件级微度量（`ComponentMetrics::NAVIGATION_DRAWER`；缺令牌会直接炸，不静默回退）。
+fn drawer_metrics() -> ComponentMetrics {
+    Component::NavigationDrawer
+        .metrics()
+        .expect("NavigationDrawer 的 ComponentMetrics 是 G10 的落点")
+}
+
+/// 容器圆角（`Component::NavigationDrawer.spec().shape = ShapeScale::Large` → 16）。
+fn shape_radius() -> f32 {
+    let shape = Component::NavigationDrawer.spec().shape;
+    debug_assert_eq!(shape, ShapeScale::Large, "ContainerShape=CornerLargeEnd");
+    shape.dp()
+}
+
+/// AppBar（small）的几何（`research/12b` §16）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct AppBarGeometry {
+    /// 页头高（56 = `LM.page_header_height`；A1 是 64，登记偏离 −8）。
+    pub height: f32,
+    /// 图标边长（24，A1 `AppBarTokens.IconSize`）。
+    pub icon: f32,
+    /// 左右内边距（4，A1 `AppBarTokens.Leading/TrailingSpace`）。
+    pub edge: f32,
+    /// 头像边长（32，A1 `AppBarTokens.AvatarSize`）。
+    pub avatar: f32,
+}
+
+impl AppBarGeometry {
+    /// 从令牌求值。
+    pub fn of(ui: &Ui) -> Self {
+        Self {
+            height: ui.metrics().page_header_height,
+            icon: IconSize::Toolbar.px(),
+            edge: ui.space(Space::X1),
+            avatar: IconSize::Empty.px(),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/app-iced/src/components/navigation/geometry/tests.rs b/crates/app-iced/src/components/navigation/geometry/tests.rs
new file mode 100644
index 0000000..263832b
--- /dev/null
+++ b/crates/app-iced/src/components/navigation/geometry/tests.rs
@@ -0,0 +1,131 @@
+//! `geometry` 的单元测试（split 拆出来的：单文件 ≤400 行，AGENTS.md §3-1）。
+
+use super::*;
+use unlucky_design::color::SchemeFlavor;
+use unlucky_design::typography::Platform;
+
+use crate::theme::Families;
+
+fn ui() -> Ui {
+    Ui::with_platform(
+        SchemeFlavor::Light,
+        Platform::Windows,
+        Families {
+            text: "Segoe UI",
+            display: "Segoe UI",
+            mono: "Consolas",
+        },
+    )
+}
+
+/// 4.1 / 4.2：三种行高 44 / 60 / 76（A1 56/72/88 的登记偏离 −12）。
+#[test]
+fn list_item_heights_are_44_60_76() {
+    let geometry = ListItemGeometry::of(&ui());
+    assert_eq!(geometry.heights, [44.0, 60.0, 76.0]);
+    for lines in 1..=3 {
+        assert_eq!(geometry.height(lines), geometry.heights[lines - 1]);
+    }
+    // 官方 delta 也是每行 +16
+    assert_eq!(geometry.heights[1] - geometry.heights[0], 16.0);
+    assert_eq!(geometry.heights[2] - geometry.heights[1], 16.0);
+}
+
+/// 行高必须**装得下**文本块（否则文字会被裁）：三行文本块 16+24+20 = 60 ≤ 76。
+#[test]
+fn list_item_rows_fit_their_text_block() {
+    let ui = ui();
+    let geometry = ListItemGeometry::of(&ui);
+    for lines in 1..=3 {
+        let block = geometry.text_block(&ui, lines);
+        let pad = geometry.pad_y(&ui, lines);
+        assert!(pad >= 0.0, "{lines} 行的垂直内边距是负数（行高装不下文本）");
+        assert!(
+            (block + pad * 2.0 - geometry.height(lines)).abs() < f32::EPSILON,
+            "{lines} 行：文本块 {block} + 2×{pad} ≠ 行高 {}",
+            geometry.height(lines)
+        );
+    }
+    assert_eq!(geometry.text_block(&ui, 1), 24.0, "BodyLarge 24/24");
+    assert_eq!(geometry.text_block(&ui, 2), 44.0, "24 + BodyMedium 20");
+    assert_eq!(geometry.text_block(&ui, 3), 60.0, "LabelSmall 16 + 24 + 20");
+    assert_eq!(geometry.pad_y(&ui, 1), 10.0, "(44 − 24) / 2");
+    assert_eq!(geometry.pad_y(&ui, 3), 8.0, "(76 − 60) / 2");
+}
+
+/// 21.1 / 21.5 / 21.6：drawer 240、药丸 216（左右各缩 12）、项高 56、内边距 16/24。
+#[test]
+fn drawer_pane_is_240_wide_with_a_216_pill() {
+    let geometry = NavPaneGeometry::of(&ui(), NavLayout::Drawer);
+    assert_eq!(geometry.width, 240.0, "D33 的展开宽度");
+    assert_eq!(geometry.pill_inset, 12.0, "ItemPadding");
+    assert_eq!(
+        geometry.pill_width, 216.0,
+        "240 − 2×12（A1: 360 − 2×12 = 336）"
+    );
+    assert_eq!(geometry.item_height, 56.0, "G24：A1 ActiveIndicatorHeight");
+    assert_eq!(geometry.pill_height, 56.0, "指示器高 = 项高");
+    assert_eq!((geometry.pad_start, geometry.pad_end), (16.0, 24.0));
+    assert_eq!(geometry.gap, 12.0, "图标 ↔ label");
+    assert_eq!(geometry.icon, 24.0);
+    // 药丸 + 两侧内缩 = 容器宽（这条是「药丸从容器宽派生」的等式，Q8 的回归点）
+    assert!((geometry.pill_width + geometry.pill_inset * 2.0 - geometry.width).abs() < 0.01);
+}
+
+/// D33：rail 与 drawer 是**同一个容器**的两个宽度（88 ⇄ 240），不是两套组件。
+#[test]
+fn rail_and_drawer_share_one_container() {
+    let ui = ui();
+    let rail = NavPaneGeometry::of(&ui, NavLayout::Rail);
+    let drawer = NavPaneGeometry::of(&ui, NavLayout::Drawer);
+
+    assert_eq!(rail.width, 88.0);
+    assert_eq!(drawer.width, 240.0);
+    assert!(rail.width < drawer.width);
+
+    // 同一个「药丸 = 容器宽 − 2×内缩」公式
+    for pane in [rail, drawer] {
+        assert!(
+            (pane.pill_width + pane.pill_inset * 2.0 - pane.width).abs() < 0.01,
+            "{:?} 的药丸宽不是从容器宽派生的",
+            pane.layout
+        );
+        // 圆角语言不变：都是 CornerLargeEnd（外侧直角、内侧 16）
+        assert_eq!((pane.radius.top_left, pane.radius.bottom_left), (0.0, 0.0));
+        assert_eq!(
+            (pane.radius.top_right, pane.radius.bottom_right),
+            (16.0, 16.0)
+        );
+        assert_eq!(pane.icon, 24.0);
+    }
+
+    // rail 的药丸是 56×32（M68 已修正的结论），不是 drawer 的 216×56
+    assert_eq!((rail.pill_width, rail.pill_height), (56.0, 32.0));
+    assert_eq!((drawer.pill_width, drawer.pill_height), (216.0, 56.0));
+}
+
+/// 6.1 / 6.2 / 6.6：Tabs 48 高、指示条 3、Secondary 线 1。
+#[test]
+fn tabs_geometry_matches_the_reference() {
+    let ui = ui();
+    let geometry = TabsGeometry::of(&ui);
+    assert_eq!(geometry.height, 48.0, "G22");
+    assert_eq!(geometry.icon, 24.0);
+    assert_eq!(geometry.pad, 16.0);
+    assert_eq!(geometry.bar(true), 3.0, "ActiveIndicatorHeight");
+    assert_eq!(geometry.bar(false), 1.0, "DividerHeight");
+    // RoundedCornerShape(3dp) 落在 3px 高的条上 = 半径 1.5（与 Full 同渲染）
+    assert_eq!(geometry.indicator_radius().top_left, 1.5);
+}
+
+/// 16.1 / 16.5：AppBar 56（LM）、图标 24、左右 4、头像 32。
+#[test]
+fn app_bar_geometry_matches_the_skeleton() {
+    let geometry = AppBarGeometry::of(&ui());
+    assert_eq!(
+        geometry.height, 56.0,
+        "LM.page_header_height（A1 64，登记偏离）"
+    );
+    assert_eq!((geometry.icon, geometry.edge), (24.0, 4.0));
+    assert_eq!(geometry.avatar, 32.0);
+}
diff --git a/crates/app-iced/src/components/navigation/list_item.rs b/crates/app-iced/src/components/navigation/list_item.rs
new file mode 100644
index 0000000..3f44d0a
--- /dev/null
+++ b/crates/app-iced/src/components/navigation/list_item.rs
@@ -0,0 +1,306 @@
+//! ListItem（`research/12b` §4）：一行 / 两行 / 三行，leading / trailing 槽位，选中态，五态状态层。
+//!
+//! ## 参考值（`[源]` = A1，本轮 `javap` 实读本机 AAR 的 `ListTokens` / `ListItemColors`）
+//!
+//! | # | 检查项 | 参考值 | 落点 |
+//! |---|---|---|---|
+//! | 4.1 | 一行高 | A1 **56** → 本项目 **44**（`LM.row_height`，登记偏离 −12） | [`ListItemGeometry::heights`] |
+//! | 4.2 | 两 / 三行高 | A1 **72 / 88** → 本项目 **60 / 76**（每多一行 +16，与官方同 delta） | 同上 |
+//! | 4.3 | 左右内边距 | **16 / 16** | `pad_start` / `pad_end` |
+//! | 4.4 | leading | 图标 **24** `OnSurfaceVariant` | `IconSize::Toolbar` |
+//! | 4.5 | 字级 | 主 `BodyLarge 16/24`、辅助 `BodyMedium 14/20`、overline `LabelSmall 11/16` | `TypeRole` |
+//! | 4.7 | 状态 | hover/focus/pressed **文本与图标色不变**，只叠状态层（8/10/10%） | [`interaction`] |
+//! | 4.8 | 选中 trailing | 图标 → **`Primary`** | `Role::Primary` |
+//!
+//! ## 禁用是**修饰器**，不是构造函数（照 `selection/chip.rs` 复审 P2-1 的结论）
+//!
+//! [`ListItem::disabled`] **只清消息**：图标、选中态、状态层全部保留。早期 chip 的
+//! `Chip::disabled(label)` 构造函数把图标和选中态一起丢了，图上是「另一行」，不是「这一行禁用」。
+//!
+//! ## 禁用内容角色是 **`OnSurface`**，不是默认的 `OnSurfaceVariant`
+//!
+//! A1 实读（`javap -p -c androidx.compose.material3.tokens.ListTokens`）：
+//!
+//! ```text
+//! ListItemDisabledLabelTextColor       = OnSurface   （+ ListItemDisabledLabelTextOpacity = 0.38f）
+//! ListItemDisabledLeadingIconColor     = OnSurface   （+ 0.38f）
+//! ListItemDisabledTrailingIconColor    = OnSurface   （+ 0.38f）
+//! ```
+//!
+//! 所以这里必须走 `interaction::disabled_content_over_role(ui, OnSurface, false)`；
+//! 用默认的 `disabled_colors()`（写死 `OnSurfaceVariant`）会偏浅一档。
+//!
+//! ## 选中态：本项目口径（**偏离登记 D-M79-1**）
+//!
+//! A1 的 `ListItemColors` **没有** selected 容器色（实读字段：containerColor / headline / leadingIcon /
+//! overline / supporting / trailingIcon + 三个 disabled），选中只把 trailing 图标换成 `Primary`。
+//! mission 要求「选中态（SecondaryContainer）」，且本项目的菜单项（M77）与 drawer 项都用
+//! `SecondaryContainer` 表示「当前项」——三处保持同一语言，故 ListItem 也填 `SecondaryContainer`
+//! + `OnSecondaryContainer`。**这是实质偏离**：A1 的 ListItem 选中行不换底色。
+
+use iced::widget::text::{LineHeight, Wrapping};
+use iced::widget::{button, container, text};
+use iced::{Alignment, Background, Border, Color, Element, Length, Padding, Pixels, Shadow};
+
+use unlucky_design::color::Role;
+use unlucky_design::icons::IconKind;
+use unlucky_design::shape::ShapeScale;
+
+use crate::icons;
+use crate::theme::Ui;
+
+use super::super::interaction::{self, Interaction};
+use super::super::layout;
+use super::geometry::{
+    typography_headline, typography_overline, typography_supporting, ListItemGeometry,
+};
+
+/// 一个列表项（一行 / 两行 / 三行由槽位决定）。
+#[derive(Debug, Clone)]
+pub struct ListItem<'a, M> {
+    overline: Option<&'a str>,
+    headline: &'a str,
+    supporting: Option<&'a str>,
+    leading: Option<IconKind>,
+    trailing: Option<IconKind>,
+    on_press: Option<M>,
+    selected: bool,
+    state: Option<Interaction>,
+}
+
+impl<'a, M> ListItem<'a, M> {
+    /// 一行项（主文本 + 可点消息）。
+    pub fn new(headline: &'a str, on_press: M) -> Self {
+        Self {
+            overline: None,
+            headline,
+            supporting: None,
+            leading: None,
+            trailing: None,
+            on_press: Some(on_press),
+            selected: false,
+            state: None,
+        }
+    }
+
+    /// 加一行辅助文本 → **两行**项（4.5：辅助 `BodyMedium`）。
+    pub fn supporting(mut self, supporting: &'a str) -> Self {
+        self.supporting = Some(supporting);
+        self
+    }
+
+    /// 加上方 overline → **三行**项（4.5：overline `LabelSmall`，`OnSurfaceVariant`）。
+    pub fn overline(mut self, overline: &'a str) -> Self {
+        self.overline = Some(overline);
+        self
+    }
+
+    /// 前置槽位（图标 24，`OnSurfaceVariant`）。
+    pub fn leading(mut self, kind: IconKind) -> Self {
+        self.leading = Some(kind);
+        self
+    }
+
+    /// 后置槽位（未选中 `OnSurface`，选中 `Primary`，见 4.8）。
+    pub fn trailing(mut self, kind: IconKind) -> Self {
+        self.trailing = Some(kind);
+        self
+    }
+
+    /// 选中态（`SecondaryContainer` + `OnSecondaryContainer`；偏离 D-M79-1 见模块文档）。
+    pub fn selected(mut self) -> Self {
+        self.selected = true;
+        self
+    }
+
+    /// 强制视觉态（gallery 状态矩阵取证；不动状态机）。
+    pub fn state(mut self, state: Interaction) -> Self {
+        self.state = Some(state);
+        self
+    }
+
+    /// 转禁用：**只清消息**，槽位与选中态一律保留。
+    pub fn disabled(mut self) -> Self {
+        self.on_press = None;
+        self
+    }
+
+    /// 行数（1 + 有 overline + 有 supporting）。
+    pub fn lines(&self) -> usize {
+        usize::from(self.overline.is_some()) + 1 + usize::from(self.supporting.is_some())
+    }
+}
+
+/// 一项的颜色（按态 + 选中求值；禁用按 A1 的 `OnSurface`@38%）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+struct ItemPalette {
+    fill: Option<Color>,
+    headline: Color,
+    supporting: Color,
+    leading: Color,
+    trailing: Color,
+}
+
+fn palette(ui: &Ui, state: Interaction, selected: bool) -> ItemPalette {
+    if state.is_disabled() {
+        // A1：ListItemDisabled*Color = OnSurface × 0.38（无容器时叠在 surface 上）
+        let ink = interaction::disabled_content_over_role(ui, Role::OnSurface, false);
+        return ItemPalette {
+            fill: None,
+            headline: ink,
+            supporting: ink,
+            leading: ink,
+            trailing: ink,
+        };
+    }
+
+    if selected {
+        let fill = interaction::overlay_color(
+            ui,
+            state,
+            Role::OnSecondaryContainer,
+            Role::SecondaryContainer,
+        )
+        .unwrap_or_else(|| ui.color(Role::SecondaryContainer));
+        return ItemPalette {
+            fill: Some(fill),
+            headline: ui.color(Role::OnSecondaryContainer),
+            supporting: ui.color(Role::OnSecondaryContainer),
+            leading: ui.color(Role::OnSecondaryContainer),
+            // 4.8：选中时 trailing 图标是 `Primary`（A1 ListItemSelectedTrailingIconColor）
+            trailing: ui.color(Role::Primary),
+        };
+    }
+
+    ItemPalette {
+        // 状态层叠在**行自己的底**（Surface）上，得到不透明结果（D27）
+        fill: interaction::overlay_color(ui, state, Role::OnSurface, Role::Surface),
+        headline: ui.color(Role::OnSurface),
+        supporting: ui.color(Role::OnSurfaceVariant),
+        leading: ui.color(Role::OnSurfaceVariant),
+        trailing: ui.color(Role::OnSurface),
+    }
+}
+
+/// 一行文本（显式行高：三行块的 16+24+20 必须能精确等于 60，靠的就是它）。
+fn line<'a, M: 'a>(
+    ui: &'a Ui,
+    value: &'a str,
+    role: unlucky_design::typography::TypeRole,
+    color: Color,
+) -> Element<'a, M> {
+    let style = ui.style(role);
+    text(value)
+        .size(style.size_px)
+        .line_height(LineHeight::Absolute(Pixels(style.line_height_px)))
+        // **单行**：行高是固定值（44/60/76），`Text` 默认 `Wrapping::Word` 会把长实例名
+        // 折成两行、把三行块顶穿。官方要的是单行 ellipsis，iced 没有 ellipsis（D19 先例）
+        // → 单行 + 超长由外层 `clip(true)` 直接切（偏离 D-M79-5）。
+        .wrapping(Wrapping::None)
+        .font(ui.font_of(style))
+        .color(color)
+        .into()
+}
+
+/// 列表项（`research/12b` §4）。
+pub fn list_item<'a, M: Clone + 'a>(ui: &'a Ui, item: ListItem<'a, M>) -> Element<'a, M> {
+    let geometry = ListItemGeometry::of(ui);
+    let lines = item.lines();
+    let height = geometry.height(lines);
+    // 禁用 = 「没有消息」；`state` 是取证强制值，优先级更高（矩阵里画 hover 的禁用项也成立）
+    let forced = item.state.or(if item.on_press.is_none() {
+        Some(Interaction::Disabled)
+    } else {
+        None
+    });
+    let colors = palette(ui, forced.unwrap_or(Interaction::Enabled), item.selected);
+
+    let mut body = iced::widget::Column::new().spacing(0);
+    if let Some(overline) = item.overline {
+        body = body.push(line::<M>(
+            ui,
+            overline,
+            typography_overline(),
+            colors.supporting,
+        ));
+    }
+    body = body.push(line::<M>(
+        ui,
+        item.headline,
+        typography_headline(),
+        colors.headline,
+    ));
+    if let Some(supporting) = item.supporting {
+        body = body.push(line::<M>(
+            ui,
+            supporting,
+            typography_supporting(),
+            colors.supporting,
+        ));
+    }
+
+    let mut content = iced::widget::Row::new()
+        .align_y(Alignment::Center)
+        .spacing(geometry.gap);
+    if let Some(kind) = item.leading {
+        // Q9：图标必须经固定尺寸容器（否则会被按钮的 Fill 约束撑满）
+        content = content.push(layout::fixed(
+            geometry.icon,
+            geometry.icon,
+            icons::view::<M>(kind, colors.leading),
+        ));
+    }
+    // 文本块吃掉剩余宽度并**裁切**：单行超长时切在行内边距上，不会压到 trailing
+    content = content.push(container(body).width(Length::Fill).clip(true));
+    if let Some(kind) = item.trailing {
+        content = content.push(layout::fixed(
+            geometry.icon,
+            geometry.icon,
+            icons::view::<M>(kind, colors.trailing),
+        ));
+    }
+
+    let pad_y = geometry.pad_y(ui, lines);
+    // 行必须撑满 item 宽度（Fill 空间要有宽度可撑），垂直靠 align_y 居中（`button` 默认贴左上）
+    let body = container(content)
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .align_y(Alignment::Center);
+
+    let selected = item.selected;
+    let style = move |_theme: &iced::Theme, status: button::Status| {
+        let state = forced.unwrap_or_else(|| Interaction::from_status(status));
+        let colors = palette(ui, state, selected);
+        button::Style {
+            background: colors.fill.map(Background::Color),
+            text_color: colors.headline,
+            // 4.x：ListItem 的形状是 `CornerNone`（直角），没有圆角档
+            border: Border {
+                radius: ui.radius_dp(ShapeScale::None),
+                ..Border::default()
+            },
+            shadow: Shadow::default(),
+            snap: true,
+        }
+    };
+
+    let button = button(body)
+        .width(Length::Fill)
+        .height(Length::Fixed(height))
+        .padding(Padding {
+            top: pad_y,
+            right: geometry.pad_end,
+            bottom: pad_y,
+            left: geometry.pad_start,
+        })
+        .style(style);
+
+    let element: Element<'a, M> = match item.on_press {
+        Some(message) => button.on_press(message).into(),
+        None => button.into(),
+    };
+    element
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/app-iced/src/components/navigation/list_item/tests.rs b/crates/app-iced/src/components/navigation/list_item/tests.rs
new file mode 100644
index 0000000..b1be068
--- /dev/null
+++ b/crates/app-iced/src/components/navigation/list_item/tests.rs
@@ -0,0 +1,127 @@
+//! `list_item` 的单元测试（split 拆出来的：单文件 ≤400 行，AGENTS.md §3-1）。
+
+use super::*;
+
+use unlucky_design::color::SchemeFlavor;
+use unlucky_design::typography::Platform;
+
+use crate::theme::Families;
+
+fn ui() -> Ui {
+    Ui::with_platform(
+        SchemeFlavor::Light,
+        Platform::Windows,
+        Families {
+            text: "Segoe UI",
+            display: "Segoe UI",
+            mono: "Consolas",
+        },
+    )
+}
+
+/// 槽位决定行数：1 / 2 / 3（三行是 overline + headline + supporting）。
+#[test]
+fn line_count_follows_the_slots() {
+    let one = ListItem::<()>::new("Instances", ());
+    assert_eq!(one.lines(), 1);
+    let two = ListItem::<()>::new("Instances", ()).supporting("3 versions");
+    assert_eq!(two.lines(), 2);
+    let three = ListItem::<()>::new("Instances", ())
+        .overline("RECENT")
+        .supporting("3 versions");
+    assert_eq!(three.lines(), 3);
+    // overline 单独存在也是两行（overline + headline）
+    let overline_only = ListItem::<()>::new("Instances", ()).overline("RECENT");
+    assert_eq!(overline_only.lines(), 2);
+}
+
+/// **禁用是修饰器**：只清消息，槽位与选中态全部保留（复审 P2-1 那条）。
+#[test]
+fn disabled_only_clears_the_message() {
+    let item = ListItem::new("Instances", ())
+        .leading(unlucky_design::icons::IconKind::Instances)
+        .trailing(unlucky_design::icons::IconKind::Settings)
+        .supporting("3 versions")
+        .selected()
+        .disabled();
+    assert!(item.on_press.is_none(), "禁用必须清消息");
+    assert!(item.leading.is_some(), "禁用不许删前置图标");
+    assert!(item.trailing.is_some(), "禁用不许删后置图标");
+    assert!(item.selected, "禁用不许删选中态");
+    assert!(item.supporting.is_some(), "禁用不许删槽位");
+    assert_eq!(item.lines(), 2);
+}
+
+/// 禁用内容角色是 **`OnSurface`**@38%（A1 ListTokens），不是默认的 `OnSurfaceVariant`。
+#[test]
+fn disabled_content_uses_on_surface() {
+    let ui = ui();
+    let palette = palette(&ui, Interaction::Disabled, false);
+    let expected = interaction::disabled_content_over_role(&ui, Role::OnSurface, false);
+    assert_eq!(palette.headline, expected);
+    assert_eq!(palette.leading, expected);
+    assert_eq!(palette.trailing, expected);
+    assert_ne!(
+        palette.headline,
+        interaction::disabled_content_over_role(&ui, Role::OnSurfaceVariant, false),
+        "走默认的 OnSurfaceVariant 就会偏浅一档（这条钉住 A1 的角色）"
+    );
+    assert!(palette.fill.is_none(), "禁用不叠状态层容器");
+}
+
+/// 选中态：`SecondaryContainer` + `OnSecondaryContainer`，trailing 是 `Primary`（4.8）。
+#[test]
+fn selected_row_is_secondary_container() {
+    let ui = ui();
+    let palette = palette(&ui, Interaction::Enabled, true);
+    assert_eq!(palette.fill, Some(ui.color(Role::SecondaryContainer)));
+    assert_eq!(palette.headline, ui.color(Role::OnSecondaryContainer));
+    assert_eq!(palette.trailing, ui.color(Role::Primary), "4.8");
+}
+
+/// 4.7：hover / pressed 只叠状态层，**内容色不变**。
+#[test]
+fn interaction_states_keep_the_content_colors() {
+    let ui = ui();
+    let resting = palette(&ui, Interaction::Enabled, false);
+    for state in [
+        Interaction::Hovered,
+        Interaction::Focused,
+        Interaction::Pressed,
+    ] {
+        let active = palette(&ui, state, false);
+        assert_eq!(active.headline, resting.headline, "{state:?} 不许改文本色");
+        assert_eq!(active.leading, resting.leading, "{state:?} 不许改图标色");
+        assert!(active.fill.is_some(), "{state:?} 必须叠状态层");
+    }
+    assert_eq!(resting.fill, None, "静息态不叠状态层");
+}
+
+/// 三档行高与 `LM.row_height` 的关系**钉死**（有人按 A1 改回 56 时这里会红）。
+#[test]
+fn heights_are_pinned_to_the_row_height_token() {
+    let ui = ui();
+    let geometry = ListItemGeometry::of(&ui);
+    assert_eq!(geometry.heights[0], ui.metrics().row_height);
+    assert_eq!(geometry.heights, [44.0, 60.0, 76.0]);
+    assert_ne!(
+        geometry.heights[0], 56.0,
+        "56 是 A1 的值；本项目按 12b §4.1 取 44（改回去会破坏页面排版）"
+    );
+}
+
+/// 元素构造不 panic（`Element` 树的形状也一并过一遍）。
+#[test]
+fn view_builds_a_tree() {
+    let ui = ui();
+    let _: Element<'_, ()> = list_item(
+        &ui,
+        ListItem::new("Instances", ())
+            .overline("RECENT")
+            .supporting("3 versions")
+            .leading(unlucky_design::icons::IconKind::Instances)
+            .trailing(unlucky_design::icons::IconKind::Settings)
+            .selected(),
+    );
+    let _: Element<'_, ()> = list_item(&ui, ListItem::new("Logs", ()).disabled());
+}
diff --git a/crates/app-iced/src/components/navigation/matrix.rs b/crates/app-iced/src/components/navigation/matrix.rs
new file mode 100644
index 0000000..9efd37f
--- /dev/null
+++ b/crates/app-iced/src/components/navigation/matrix.rs
@@ -0,0 +1,110 @@
+//! 导航家族的长文案取证块（D-M79-5）：**单行 + 裁切**，页面真接长实例名时不许折行。
+//!
+//! 为什么不放在 `gallery/navigation.rs`：那个文件已经贴到 400 行红线（AGENTS.md §3-1），
+//! 而它属于 harness 单文件、scope 只授权一个路径。按 `selection::matrix` 的先例，把**取证块**
+//! 收进组件目录、对消息类型泛型（`pressed: impl Fn() -> M`），gallery 只做一次 `.map`。
+
+use iced::widget::{column, container, text};
+use iced::{Background, Element, Length};
+
+use unlucky_design::color::Role;
+use unlucky_design::icons::IconKind;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use crate::theme::Ui;
+
+use super::{
+    app_bar, list_item, navigation, tabs, AppBar, AppBarAction, ListItem, NavGroup, NavItem,
+    Navigation, Tab, Tabs,
+};
+
+/// 一行小字图例。
+fn note<'a, M: 'a>(ui: &'a Ui, value: &'a str) -> Element<'a, M> {
+    let style = ui.style(TypeRole::BodySmall);
+    text(value)
+        .size(style.size_px)
+        .font(ui.font_of(style))
+        .color(ui.color(Role::OnSurfaceVariant))
+        .into()
+}
+
+/// 取景板（`SurfaceContainerLow`）：`Surface` 的页头与页面底色同色，要垫一层才量得到边界。
+fn plate<'a, M: 'a>(ui: &'a Ui, pad: f32, content: impl Into<Element<'a, M>>) -> Element<'a, M> {
+    container(content)
+        .padding(pad)
+        .style(move |_theme| container::Style {
+            background: Some(Background::Color(ui.color(Role::SurfaceContainerLow))),
+            ..container::Style::default()
+        })
+        .into()
+}
+
+fn icon(name: &str) -> IconKind {
+    match name {
+        "download" => IconKind::Download,
+        "logs" => IconKind::Logs,
+        "settings" => IconKind::Settings,
+        _ => IconKind::Instances,
+    }
+}
+
+/// 长文案块（D-M79-5 的取证）：单行 + 裁切——不折行、不顶穿 56 的页头、不压 trailing。
+/// 矩阵图全用短文案看不出这个坑，真实实例名（`All the Mods 10 - ATM10 …`）一接就中招。
+pub fn long_part<'a, M: Clone + 'a>(ui: &'a Ui, pressed: impl Fn() -> M) -> Element<'a, M> {
+    const LONG: &str = "All the Mods 10 - ATM10 - 1.21.1 - NeoForge";
+
+    let bar = app_bar(
+        ui,
+        AppBar::new(LONG)
+            .subtitle(LONG)
+            .leading(AppBarAction::inert(icon("instances")))
+            .trailing(AppBarAction::new(icon("settings"), pressed()))
+            .trailing(AppBarAction::new(icon("logs"), pressed())),
+    );
+
+    let row = |lines: usize| {
+        let mut item = ListItem::new(LONG, pressed())
+            .leading(icon("instances"))
+            .trailing(icon("settings"));
+        if lines >= 2 {
+            item = item.supporting(LONG);
+        }
+        if lines >= 3 {
+            item = item.overline(LONG);
+        }
+        container(list_item(ui, item.selected()))
+            .width(Length::Fixed(ui.metrics().nav_drawer_width))
+    };
+
+    let pane = navigation(
+        ui,
+        Navigation::drawer().group(
+            NavGroup::titled(LONG)
+                .item(NavItem::new(LONG, icon("instances"), pressed()).selected())
+                .item(NavItem::new("Settings", icon("settings"), pressed())),
+        ),
+    );
+
+    // Tabs：长标签不折行，tab 自己变宽（横向滚动兜住溢出）
+    let tabs_row = tabs(
+        ui,
+        Tabs::primary()
+            .tab(Tab::new(LONG, pressed()).selected())
+            .tab(Tab::new("Settings", pressed())),
+    );
+
+    column![
+        note(
+            ui,
+            "长文案（D-M79-5）：单行 + 裁切 —— 不折行、页头仍 56、不压 trailing"
+        ),
+        plate(ui, ui.space(Space::X2), bar),
+        column![row(1), row(2), row(3)].spacing(ui.space(Space::X4)),
+        tabs_row,
+        container(container(pane).height(Length::Fixed(ui.space(Space::X8) * 6.0)))
+            .width(Length::Fixed(ui.metrics().nav_drawer_width)),
+    ]
+    .spacing(ui.space(Space::X2))
+    .into()
+}
diff --git a/crates/app-iced/src/components/navigation/mod.rs b/crates/app-iced/src/components/navigation/mod.rs
new file mode 100644
index 0000000..de7d65c
--- /dev/null
+++ b/crates/app-iced/src/components/navigation/mod.rs
@@ -0,0 +1,80 @@
+//! **导航类家族**（`research/12b` §4/§6/§16 + `research/15` §21）：四件组件，一个容器。
+//!
+//! | 组件 | 入口 | 参考章节 | 关键几何 |
+//! |---|---|---|---|
+//! | ListItem | [`list_item::list_item`] | 12b §4 | 行高 44 / 60 / 76（A1 56/72/88，登记偏离） |
+//! | Tabs | [`tabs::tabs`] | 12b §6 | 容器 48、Primary 指示条 3、Secondary 线 1 |
+//! | NavigationDrawer | [`drawer::navigation`] | 15 §21 + D33 | **同一个容器**：rail 88 ⇄ drawer 240 |
+//! | AppBar small | [`app_bar::app_bar`] | 12b §16 | 页头 56、标题 TitleLarge、滚动换色 + L2 |
+//!
+//! ## 三条纪律（与另外四个家族同源）
+//!
+//! 1. **对消息类型泛型**，不 import `crate::app::Message`（契约 §2）；`Ui` 一律 `&'a Ui` 传入。
+//! 2. **状态层只走** [`crate::app::components::interaction`]：α 与禁用色一处求值；
+//!    禁用是**修饰器**（`.disabled()` 只清消息，见 `selection/chip.rs` 复审 P2-1）。
+//! 3. **精确尺寸只走** [`crate::app::components::layout`]：图标一律 `layout::fixed`（Q9），
+//!    居中交给父级 `align_x`（Q8：`center_x(Fill)` 会把 56 宽药丸撑成 88）。
+//!
+//! ## 禁用内容角色**按变体**（不许抄默认值）
+//!
+//! | 组件 | 禁用内容角色 | 出处 |
+//! |---|---|---|
+//! | ListItem | **`OnSurface`**@38%（不是 `OnSurfaceVariant`） | `[源]` `ListTokens.ListItemDisabledLabel/LeadingIcon/TrailingIconColor = OnSurface` + `…Opacity = 0.38f` |
+//! | Drawer / Rail 项 | `OnSurface`@38% | `[估]`（A1 无 disabled token，与 ListItem 同表面语境） |
+//! | Tabs | `OnSurface`@38% | `[估]`（同上；A1 的 Tabs 两套 token 只有 Active/Inactive） |
+//! | AppBar | — （本轮页头不带禁用动作） | — |
+//!
+//! ## Q21：要给居中就**两轴都显式给**（第三轮 review 的规则化）
+//!
+//! `Container` 的 `horizontal_alignment` 默认 `Left`、`vertical_alignment` 默认 `Top`
+//! （`iced_widget-0.14.2/src/container.rs`）。只给 `align_y` 会让内容贴左缘——AppBar 的 40×40
+//! 动作按钮里 24px 图标曾因此左内缩 4 / 右内缩 20（视觉 r1 实测前导墨迹 `38..58`，应 `44..68`），
+//! 而且 hover 的圆形状态层会露在图标一侧。
+//!
+//! 本目录的复查结论（逐处）：
+//!
+//! | 位置 | 需要 | 写法 |
+//! |---|---|---|
+//! | `app_bar::action` 命中区里的图标 | 两轴居中 | `align_x` + `align_y` |
+//! | `app_bar` 页头内容行 | 垂直居中（水平由 `Fill` 决定） | `.align_y(Center)` |
+//! | `tabs::tab_cell` 的内容 | 两轴居中 | `align_x` + `align_y` |
+//! | `drawer/item` 的药丸 | 两轴居中 | `align_x` + `align_y` |
+//! | `list_item` 的文本块 / `drawer` 的分组标题 | **左上起排**（`Start` 是对的，不需要居中） | 不设对齐，靠 `padding` 定起点 |
+//!
+//! 回归钉子：`navigation::probe` 的 appbar 断言量「左内缩 == 右内缩 ±2」——`align_x` 再漏一次就红。
+//!
+//! ## 单行约束（偏离 D-M79-5）
+//!
+//! 四件的文本一律 `Wrapping::None` + 外层 `clip(true)`：容器高度都是固定值（44/60/76、48/64、56），
+//! `Text` 默认 `Wrapping::Word` 会把长实例名折成 2~3 行，顶穿页头、压住 trailing。官方要的是
+//! **单行 ellipsis**，iced 没有 ellipsis（`inputs/menu.rs` 的 D19 先例）→ 我们单行 + 超长直接切。
+//! 取证：`ULL_NAV_PART=long` 出图 + `navigation::probe::long` 量「行高不变 / 页头仍 56 / 标题不压动作」。
+//!
+//! ## 令牌缺口（G 编号，续 `research/15` §25 的 G13；G16~G20 已被其他家族占用）
+//!
+//! - **G22** Tabs 容器高 48（带图标 64）——`LayoutMetrics` 无此档；
+//! - **G23** Tabs 指示条高 3 / `TabMinWidth` 90（后者 iced 无法表达，登记为限制）；
+//! - **G24** drawer 项高 56——与 `LM.nav_item_height`(44) 的差异按 A1 取 56，见 [`geometry`]；
+//! - **G25** ListItem 两/三行高（60 / 76）——`G4` 要求的 `row_height_1/2/3` 仍缺，本文件按
+//!   `LM.row_height` + 每行 16 派生（A1 delta 相同）。
+//!
+//! ## 视觉证据（D30）
+//!
+//! `gallery/navigation.rs` 把四个组件摆成状态矩阵；`ULL_GALLERY_SECTION=navigation` 只渲染本段，
+//! `ULL_NAV_PART=<list|tabs|drawer|appbar|all>` 再切成单块出图（1180×760 一屏装不下四块矩阵）。
+//! 渲染层断言在 [`probe`]（读 `ULL_NAV_DIR` 下的真截图量像素），纯函数断言在各组件文件的 `tests`。
+
+pub mod app_bar;
+pub mod drawer;
+pub mod geometry;
+pub mod list_item;
+pub mod matrix;
+#[cfg(test)]
+mod probe;
+pub mod tabs;
+
+pub use app_bar::{app_bar, AppBar, AppBarAction};
+pub use drawer::{navigation, NavGroup, NavItem, Navigation};
+pub use geometry::NavLayout;
+pub use list_item::{list_item, ListItem};
+pub use tabs::{tabs, Tab, Tabs, TabsVariant};
diff --git a/crates/app-iced/src/components/navigation/probe.rs b/crates/app-iced/src/components/navigation/probe.rs
new file mode 100644
index 0000000..68d2730
--- /dev/null
+++ b/crates/app-iced/src/components/navigation/probe.rs
@@ -0,0 +1,393 @@
+//! 渲染层几何断言：**对着真截图量像素**（M68 的教训——纯函数返回对，图可能是错的）。
+//!
+//! ## 为什么自带一份最小读图器
+//!
+//! `gallery::scan` 是 `pub(super)`（私有于 `gallery`），而 `gallery/mod.rs` 不在本 mission 的 scope 里，
+//! 所以这里自带 ~60 行读图器（读 PNG / 取点 / 连通块 / 横带墨迹范围），判据全在本文件。
+//! 与 `inputs/probe.rs` 同一个处置（已作为 finding 报给 tower：建议把 `gallery::scan` 提升为 `pub(crate)`）。
+//!
+//! ## 怎么跑（worktree 根目录）
+//!
+//! ```text
+//! # ① 出 4 张图（每块一条命令，块选择器见 gallery/navigation.rs 的模块文档）
+//! ULL_GALLERY_SECTION=navigation ULL_NAV_PART=list ./target/debug/unlucky-launcher-iced.exe \
+//!   --software-renderer --screen=gallery --screenshot target/m79/list-light.png --screenshot-theme=light
+//! # ② 量图
+//! ULL_NAV_DIR=target/m79 cargo test -p unlucky-app-iced navigation::probe
+//! ```
+//!
+//! 没给 `ULL_NAV_DIR` 就**大声跳过**（不静默通过），与 `gallery::probe` 的口径一致。
+//!
+//! ## 量什么（每条都对着一个「已经画错过」的形态）
+//!
+//! | 断言 | 抓的错误 |
+//! |---|---|
+//! | ListItem 三行高 **44 / 60 / 76** | 抄 A1 的 56/72/88、或用内容撑高（行高被文本吃掉） |
+//! | ListItem 禁用内容 = `OnSurface`@38% | 走 `disabled_colors()` 的默认 `OnSurfaceVariant` |
+//! | Primary 指示条宽 = 选中项文本宽 + 2×16 | 条写成 `Fill`（= 整行宽，Q8 的另一面）或写死 |
+//! | drawer **240** / rail **88**，药丸内缩 **12** / **16** | 药丸不贴边（Q8）、或两套组件各写死一个宽度 |
+//! | AppBar **56** 高（静息 + 滚动） | 页头被内容撑高、或按 A1 改回 64 |
+
+use std::path::{Path, PathBuf};
+
+use unlucky_design::color::{Role, SchemeFlavor};
+use unlucky_design::spacing::Space;
+
+use crate::app::components::interaction;
+
+mod divider;
+mod long;
+mod scan;
+use scan::{rgb, ui as ui_of, BBox, Rgb, Shot};
+
+/// 有这张图就读，没有就 `None`（深色档的可选覆盖用）。
+fn shot_opt(dir: &Path, part: &str, flavor: SchemeFlavor) -> Option<Shot> {
+    let slug = match flavor {
+        SchemeFlavor::Light => "light",
+        SchemeFlavor::Dark => "dark",
+    };
+    let path = dir.join(format!("{part}-{slug}.png"));
+    path.exists().then(|| Shot::load(&path))
+}
+
+/// `ULL_NAV_DIR` → 截图目录（相对路径按**工作区根**解释：`cargo test` 的 cwd 是 crate 目录）。
+fn shot_dir() -> Option<PathBuf> {
+    let raw = std::env::var_os("ULL_NAV_DIR")?;
+    let path = PathBuf::from(raw);
+    if path.is_absolute() || path.exists() {
+        return Some(path);
+    }
+    let root = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../..");
+    Some(root.join(path))
+}
+
+macro_rules! require_dir {
+    () => {
+        match shot_dir() {
+            Some(dir) => dir,
+            None => {
+                eprintln!(
+                    "[navigation::probe] SKIPPED：未设置 ULL_NAV_DIR。这是**渲染层**断言，\
+                     需要先按本文件模块文档出 4 张图（target/m79/*.png）。"
+                );
+                return;
+            }
+        }
+    };
+}
+
+fn shot(dir: &Path, part: &str, flavor: SchemeFlavor) -> Shot {
+    let slug = match flavor {
+        SchemeFlavor::Light => "light",
+        SchemeFlavor::Dark => "dark",
+    };
+    Shot::load(&dir.join(format!("{part}-{slug}.png")))
+}
+
+/// ListItem：三行高 **44 / 60 / 76**（选中行的 `SecondaryContainer` 底就是行高）。
+#[test]
+fn list_item_rows_are_44_60_76() {
+    let dir = require_dir!();
+    let ui = ui_of(SchemeFlavor::Light);
+    let shot = shot(&dir, "list", SchemeFlavor::Light);
+
+    // 矩阵格宽 240（`nav_drawer_width`）：选中列的三块填充就是三条行
+    let selected = rgb(ui.color(Role::SecondaryContainer));
+    let mut rows: Vec<BBox> = shot
+        .blocks(selected)
+        .into_iter()
+        .filter(|b| (238..=242).contains(&b.width()) && b.height() > 30)
+        .collect();
+    rows.sort_by_key(|b| b.top);
+    assert_eq!(
+        rows.len(),
+        3,
+        "选中列应有 3 条（一 / 两 / 三行），实际 {} —— 图里格子宽度或选中底丢了",
+        rows.len()
+    );
+    let heights: Vec<usize> = rows.iter().map(BBox::height).collect();
+    // 边缘那一行是抗锯齿（半覆盖）→ 实测常常少 1px；判 43..=44 / 59..=60 / 75..=76，
+    // 而 A1 的 56/72/88 仍然落区间外（这条照样能被打红）。
+    for (measured, expected) in heights.iter().zip([44usize, 60, 76]) {
+        assert!(
+            (expected - 1..=expected).contains(measured),
+            "12b §4.1/4.2 的项目口径是 44/60/76（A1 是 56/72/88）；实测 {heights:?}"
+        );
+    }
+
+    // 禁用内容角色 = `OnSurface`@38%（A1 ListTokens），不是默认的 `OnSurfaceVariant`@38%。
+    // 判据：禁用格里**最深**的像素就是核心笔画，它必须精确等于 A1 的那个混合色。
+    let cell = rows[0].width() + 8; // 格宽 240 + 列间距 8
+    let disabled = BBox {
+        left: rows[0].left + cell * 2,
+        right: (rows[0].left + cell * 2 + rows[0].width() - 1).min(shot.width - 1),
+        top: rows[0].top,
+        bottom: rows[2].bottom,
+    };
+    let darkest = shot.darkest(&disabled).expect("禁用格里应有墨迹");
+    let right = rgb(interaction::disabled_content_over_role(
+        &ui,
+        Role::OnSurface,
+        false,
+    ));
+    let wrong = rgb(interaction::disabled_content_over_role(
+        &ui,
+        Role::OnSurfaceVariant,
+        false,
+    ));
+    let near = |a: Rgb, b: Rgb| {
+        a.iter()
+            .zip(b)
+            .all(|(x, y)| x.abs_diff(y) <= scan::TOLERANCE)
+    };
+    assert!(
+        near(darkest, right),
+        "禁用内容最深像素是 {darkest:?}，A1 的 OnSurface@38% 是 {right:?}（用 OnSurfaceVariant 会得到 {wrong:?}）"
+    );
+    assert!(
+        !near(darkest, wrong),
+        "禁用内容用了 OnSurfaceVariant@38%（{wrong:?}）而不是 A1 的 OnSurface@38%（{right:?}）"
+    );
+
+    eprintln!(
+        "[navigation::probe] list: 行高 {heights:?}，禁用最深像素 {darkest:?}（A1 = {right:?}）"
+    );
+}
+
+/// Tabs：Primary 指示条宽 = **选中项**文本宽 + 2×16（短/长文案各选中一次 → 两条宽度必须不同）。
+#[test]
+fn tabs_indicator_tracks_the_selected_tab() {
+    let dir = require_dir!();
+    let ui = ui_of(SchemeFlavor::Light);
+    let shot = shot(&dir, "tabs", SchemeFlavor::Light);
+
+    let primary = rgb(ui.color(Role::Primary));
+    let surface = rgb(ui.color(Role::Surface));
+    // 指示条：3px 高、宽 ≥ 40 的 `Primary` 块（选中项的标签是同色，但笔画块远小于 40 宽）
+    let mut bars: Vec<BBox> = shot
+        .blocks(primary)
+        .into_iter()
+        .filter(|b| b.height() <= 4 && b.width() >= 40)
+        .collect();
+    bars.sort_by_key(|b| b.top);
+    assert!(
+        bars.len() >= 2,
+        "至少应有 2 条 Primary 指示条（短文案选中一行 + 长文案选中一行），实际 {}",
+        bars.len()
+    );
+    // 前两条 = 两行 Primary（后面还有「五态」那一行的选中条，不参与「跟随宽度」的判定）
+    bars.truncate(2);
+
+    let mut measured = Vec::new();
+    for bar in &bars {
+        // 该行的标签墨迹：指示条上方 2..32 像素、**指示条自身跨度内**与底色不同的像素范围
+        let span = shot
+            .band_ink(
+                surface,
+                bar.left,
+                bar.right,
+                bar.top.saturating_sub(32),
+                bar.top.saturating_sub(2),
+            )
+            .expect("指示条上方应能找到选中标签的墨迹");
+        let ink = span.1 - span.0 + 1;
+        let expected = ink + 32; // 2 × pad(16)
+        assert!(
+            bar.width() >= ink,
+            "指示条 {} 比标签墨迹 {ink} 还窄",
+            bar.width()
+        );
+        assert!(
+            bar.width() <= expected + 12,
+            "指示条宽 {} 远大于「标签墨迹 {ink} + 2×16 = {expected}」——条被写成了整行宽（Q8）",
+            bar.width()
+        );
+        assert!(
+            bar.width() + 12 >= expected,
+            "指示条宽 {} 小于「标签墨迹 {ink} + 2×16 = {expected}」——条没有覆盖内边距",
+            bar.width()
+        );
+        measured.push((bar.width(), ink));
+    }
+    // 6.6：Secondary 的分隔线必须是**一条连续直线**（逐 tab 分段画会在相邻段之间留缝）。
+    // 判据与锚定规则全在 `probe/divider.rs`（含「无论红绿都打印锚定行」）。
+    divider::check(&shot, &ui, "light");
+    if let Some(dark) = shot_opt(&dir, "tabs", SchemeFlavor::Dark) {
+        divider::check(&dark, &ui_of(SchemeFlavor::Dark), "dark");
+    }
+
+    let (short_bar, long_bar) = (measured[0].0, measured[1].0);
+    assert!(
+        long_bar > short_bar + 20,
+        "两行的指示条宽度必须随选中项变化（短文案 {short_bar} / 长文案 {long_bar}）——\
+         写死或 Fill 的条会一样宽"
+    );
+
+    eprintln!("[navigation::probe] tabs: 指示条 {measured:?}（宽, 标签墨迹宽）");
+}
+
+/// Drawer：**同一个容器两个宽度** —— rail 88 / drawer 240，药丸 56×32 / 216×56，内缩 16 / 12（D33）。
+#[test]
+fn drawer_is_240_and_rail_is_88_with_inset_pills() {
+    let dir = require_dir!();
+    let ui = ui_of(SchemeFlavor::Light);
+    let shot = shot(&dir, "drawer", SchemeFlavor::Light);
+
+    let pad = Space::X2.dp();
+    let plate = rgb(ui.color(Role::SurfaceContainerLow));
+    let mut plates: Vec<BBox> = shot
+        .blocks(plate)
+        .into_iter()
+        .filter(|b| b.height() > 150)
+        .collect();
+    plates.sort_by_key(|b| b.left);
+    assert_eq!(
+        plates.len(),
+        2,
+        "应有 2 块取景板（rail 与 drawer），实际 {}",
+        plates.len()
+    );
+    let (rail_plate, drawer_plate) = (plates[0], plates[1]);
+    // 取景板比导航容器大一圈（左右各 pad）：板宽 − 2×pad 才是容器宽
+    let rail = rail_plate.width() as f32 - pad * 2.0;
+    let drawer = drawer_plate.width() as f32 - pad * 2.0;
+    assert_eq!(rail, 88.0, "LayoutMetrics::nav_rail_width");
+    assert_eq!(drawer, 240.0, "LayoutMetrics::nav_drawer_width");
+
+    let pill = rgb(ui.color(Role::SecondaryContainer));
+    let mut pills: Vec<BBox> = shot
+        .blocks(pill)
+        .into_iter()
+        .filter(|b| b.width() > 40 && b.height() > 20)
+        .collect();
+    pills.sort_by_key(|b| b.left);
+    assert_eq!(
+        pills.len(),
+        2,
+        "rail 与 drawer 各一个选中药丸，实际 {}",
+        pills.len()
+    );
+    let (rail_pill, drawer_pill) = (pills[0], pills[1]);
+
+    // rail：药丸 56×32，左右各缩 16（88 − 2×16 = 56，M68 的结论）
+    // 边缘抗锯齿可能少 1px（32 → 31）；判 ±1 区间，216/56 的 drawer 药丸同理
+    assert!(
+        (55..=56).contains(&rail_pill.width()) && (31..=32).contains(&rail_pill.height()),
+        "12b §5.4：rail 药丸应是 56×32，实测 {}×{}",
+        rail_pill.width(),
+        rail_pill.height()
+    );
+    assert_eq!(
+        rail_pill.left - (rail_plate.left + pad as usize),
+        16,
+        "rail 药丸左内缩必须是 16（Q8 回归时这里是 0，药丸会贴边）"
+    );
+    // drawer：药丸 216×56，左右各缩 12（A1 `NavigationDrawerItemDefaults.ItemPadding = 12`）
+    assert!(
+        (215..=216).contains(&drawer_pill.width()) && (55..=56).contains(&drawer_pill.height()),
+        "21.5：drawer 药丸应是 216×56（240 − 2×12），实测 {}×{}",
+        drawer_pill.width(),
+        drawer_pill.height()
+    );
+    assert_eq!(
+        drawer_plate.width() - drawer_pill.width(),
+        24 + pad as usize * 2,
+        "药丸两侧内缩之和必须是 24（12 + 12），再加取景板的两圈 pad"
+    );
+    assert_eq!(
+        drawer_pill.left - (drawer_plate.left + pad as usize),
+        12,
+        "ItemPadding"
+    );
+    // 圆角语言不变：两条药丸都居中（左右内缩相等）
+    assert_eq!(
+        rail_plate.right - pad as usize - rail_pill.right,
+        rail_pill.left - (rail_plate.left + pad as usize),
+        "rail 药丸必须水平居中（两侧内缩相等）"
+    );
+
+    eprintln!(
+        "[navigation::probe] drawer: rail {rail} / drawer {drawer}，药丸 {}×{} / {}×{}，内缩 {} / {}",
+        rail_pill.width(),
+        rail_pill.height(),
+        drawer_pill.width(),
+        drawer_pill.height(),
+        rail_pill.left - (rail_plate.left + pad as usize),
+        drawer_pill.left - (drawer_plate.left + pad as usize)
+    );
+}
+
+/// AppBar：静息 56 高（`Surface`）、滚动 56 高（`SurfaceContainer`）——高度不随滚动变化。
+#[test]
+fn app_bar_is_56_high_in_both_states() {
+    let dir = require_dir!();
+    let ui = ui_of(SchemeFlavor::Light);
+    let shot = shot(&dir, "appbar", SchemeFlavor::Light);
+
+    let resting = rgb(ui.color(Role::Surface));
+    let scrolled = rgb(ui.color(Role::SurfaceContainer));
+    let mut measured = Vec::new();
+    for (name, color) in [("静息", resting), ("滚动", scrolled)] {
+        let bars: Vec<BBox> = shot
+            .blocks(color)
+            .into_iter()
+            .filter(|b| b.width() > 300 && (54..=58).contains(&b.height()))
+            .collect();
+        assert_eq!(
+            bars.len(),
+            1,
+            "{name} AppBar 应恰好一条（56 高、>300 宽），实际 {} 条",
+            bars.len()
+        );
+        measured.push((name, bars[0].height()));
+    }
+    // 两条同高：滚动只换容器色与高程，不改高度（A1 只有 `OnScrollContainerColor` / `OnScrollContainerElevation`）
+    // 滚动态带 L2 阴影，阴影会把边缘那一行染成接近容器的颜色 → 允许差 1px
+    assert!(
+        (measured[0].1 as i32 - measured[1].1 as i32).abs() <= 1,
+        "静息与滚动必须同高（滚动不改高度），实测 {measured:?}"
+    );
+    // 抗锯齿让边缘行可能差 1px：判 55..=57；A1 的 64 必须落区间外
+    assert!(
+        (55..=57).contains(&measured[0].1),
+        "AppBar 高度应是 56（LM.page_header_height），实测 {measured:?}"
+    );
+    assert!(
+        !(63..=65).contains(&measured[0].1),
+        "64 是 A1 AppBarSmallTokens.ContainerHeight；本项目按骨架令牌取 56（D-M79-2）"
+    );
+
+    // Q21：动作图标必须在 40×40 命中区正中出现（`Container` 默认 Left/Top，
+    // 只给 `align_y` 会贴左缘——视觉 r1 实测前导墨迹 `38..58`，应 `44..68`）。
+    // 判据：左内缩（bar.left → 前导墨迹左缘）== 右内缩（尾随墨迹右缘 → bar.right），±2px。
+    let bars = shot
+        .blocks(resting)
+        .into_iter()
+        .filter(|b| b.width() > 300 && (54..=58).contains(&b.height()))
+        .collect::<Vec<_>>();
+    let bar = bars[0];
+    let leading_ink = rgb(ui.color(Role::OnSurface));
+    let trailing_ink = rgb(ui.color(Role::OnSurfaceVariant));
+    let leading = shot
+        .band_extent(leading_ink, bar.top, bar.bottom, bar.left, bar.left + 48)
+        .expect("页头左侧应有前导图标墨迹");
+    let trailing = shot
+        .band_extent(
+            trailing_ink,
+            bar.top,
+            bar.bottom,
+            bar.right.saturating_sub(48),
+            bar.right,
+        )
+        .expect("页头右侧应有尾随图标墨迹");
+    let left_inset = leading.0 as i32 - bar.left as i32;
+    let right_inset = bar.right as i32 - trailing.1 as i32;
+    assert!(
+        (left_inset - right_inset).abs() <= 2,
+        "动作图标不在命中区正中：左内缩 {left_inset} / 右内缩 {right_inset}（Q21：`align_x` 漏给会差 8px）"
+    );
+
+    eprintln!(
+        "[navigation::probe] appbar: 高度 {measured:?}，图标内缩 左 {left_inset} / 右 {right_inset}"
+    );
+}
diff --git a/crates/app-iced/src/components/navigation/probe/divider.rs b/crates/app-iced/src/components/navigation/probe/divider.rs
new file mode 100644
index 0000000..966ae49
--- /dev/null
+++ b/crates/app-iced/src/components/navigation/probe/divider.rs
@@ -0,0 +1,49 @@
+//! 分隔线守卫（6.6）：**Secondary 的分隔线必须是一条连续直线**。
+//!
+//! 逐 tab 分段画会在相邻段之间留缝（视觉 r1 P2-2 实测 `25..101 | 103..191 | 193..265`，
+//! 交界像素偏亮）。这条守卫被复审三轮打过三次，每次都是「假绿」，所以下面把**每个判据
+//! 挡的是哪一次假通过**写清楚——改之前先读一遍：
+//!
+//! | 判据 | 挡的假通过 |
+//! |---|---|
+//! | ① 锚定「细 + 近乎实心 + 薄 + 低对比 + 跨度 ≥200」的一行（见 `scan::Shot::find_thin_line`） | 五态行的 40px 高底色带、`Primary` 指示条顶替分隔线 |
+//! | ② 线色必须是 `Surface → SurfaceVariant` 的插值（覆盖率 30%~105%） | 更靠上的同类细线顶替：`OutlineVariant` 组间线（t 出界）、hover 8% 带（三通道 t 散开） |
+//! | ③ 参考色取**该行墨迹众数色**（见 `scan::Shot::line_segments`） | 缺口恰落在跨度中点时，参考色退化成页面底色 → 恒 1 段 |
+//! | ④ 在该行**整段墨迹跨度**上数段（不是某次 run 的窗口） | 缺口在窗口外看不见、在窗口内被「跳过去重新起跑」滑过 |
+//!
+//! ## 锚定行**无条件打印**
+//!
+//! 不管红绿都往 stderr 打一行 `[probe] divider anchored at y=… span=x..x color=(r,g,b) segments=N`。
+//! 之前绿的时候什么都不说，于是「锚错行」是静默的——不看断言在量什么，等于没有断言。
+//!
+//! ## 深浅两档
+//!
+//! 浅色图必跑；深色图（`tabs-dark.png`）**存在就跑**（深色的 divider 对比更低，更值得测）。
+//! 没有深色图时不算失败，但会在输出里留一行 `dark 档跳过`。
+
+use unlucky_design::color::Role;
+
+use crate::theme::Ui;
+
+use super::scan::{rgb, Shot};
+
+/// 在 `shot` 上验证分隔线是一条直线；`label` 只用于日志（`light` / `dark`）。
+pub(super) fn check(shot: &Shot, ui: &Ui, label: &str) {
+    let surface = rgb(ui.color(Role::Surface));
+    let variant = rgb(ui.color(Role::SurfaceVariant));
+    let (y, x0, x1, color) = shot
+        .find_thin_line(surface, variant, 200, 120)
+        .unwrap_or_else(|| panic!("[{label}] 找不到 Secondary 那一行细线（锚定失败）"));
+    let segments = shot.line_segments(y, x0, x1);
+    eprintln!(
+        "[probe] divider anchored at y={y} span=x{x0}..{x1} color={color:?} segments={segments} \
+         ({label}, {shot_width}x{shot_height})",
+        shot_width = shot.width,
+        shot_height = shot.height,
+    );
+    assert_eq!(
+        segments, 1,
+        "[{label}] Secondary 分隔线应是一条直线，实测 {segments} 段（量到 y={y}, x{x0}..{x1}）——\
+         分段画会在交界处留缝"
+    );
+}
diff --git a/crates/app-iced/src/components/navigation/probe/long.rs b/crates/app-iced/src/components/navigation/probe/long.rs
new file mode 100644
index 0000000..aa1295a
--- /dev/null
+++ b/crates/app-iced/src/components/navigation/probe/long.rs
@@ -0,0 +1,98 @@
+//! 长文案的渲染层断言（**D-M79-5**：我们的单行约束是否真的成立）。
+//!
+//! 矩阵图全用短文案（"Instances" / "Instance details"），`Text` 默认 `Wrapping::Word` 的坑
+//! 在图上根本看不出来——页面一接真实实例名（`All the Mods 10 - ATM10 - 1.21.1 - NeoForge`）
+//! 就会折成 2~3 行、顶穿 56 的页头、压住 trailing 动作。所以这里用 `ULL_NAV_PART=long`
+//! 那张图单独量三件事：
+//!
+//! | 断言 | 抓的错误 |
+//! |---|---|
+//! | ListItem 三行高仍 44/60/76 | 长文本折行把行撑高 / 被固定行高裁掉 |
+//! | AppBar 仍 56 高 | 标题折行顶穿页头 |
+//! | 标题墨迹右缘 < trailing 图标左缘 | 长标题覆盖到动作按钮上 |
+//!
+//! 跑法见 `navigation/probe.rs` 的模块文档（`ULL_NAV_DIR=target/m79`，图名 `long-light.png`）。
+
+use unlucky_design::color::{Role, SchemeFlavor};
+
+use super::scan::{rgb, ui};
+use super::{shot, shot_dir};
+
+#[test]
+fn long_text_stays_single_line() {
+    let Some(dir) = shot_dir() else {
+        eprintln!(
+            "[navigation::probe::long] SKIPPED：未设置 ULL_NAV_DIR（需要先出 long-light.png）"
+        );
+        return;
+    };
+    let shot = shot(&dir, "long", SchemeFlavor::Light);
+    let ui = ui(SchemeFlavor::Light);
+
+    // ---- ① ListItem：长实例名不折行 → 行高仍是 44 / 60 / 76 ----
+    let selected = rgb(ui.color(Role::SecondaryContainer));
+    let mut rows = shot
+        .blocks(selected)
+        .into_iter()
+        .filter(|b| (238..=242).contains(&b.width()) && b.height() > 30)
+        .collect::<Vec<_>>();
+    rows.sort_by_key(|b| b.top);
+    assert_eq!(
+        rows.len(),
+        3,
+        "长文案块应有 3 条 ListItem（实 {}）",
+        rows.len()
+    );
+    let heights = rows.iter().map(|b| b.height()).collect::<Vec<_>>();
+    for (measured, expected) in heights.iter().zip([44usize, 60, 76]) {
+        assert!(
+            (expected - 1..=expected).contains(measured),
+            "长文案把行高撑成 {heights:?}（应为 44/60/76 ±1）——说明折行了"
+        );
+    }
+
+    // ---- ② AppBar：长标题不顶穿页头（仍 56 高）----
+    let bar = shot
+        .blocks(rgb(ui.color(Role::Surface)))
+        .into_iter()
+        .find(|b| b.width() > 300 && (54..=58).contains(&b.height()))
+        .expect("长文案块应有一条 56 高的页头");
+    assert!(
+        (55..=57).contains(&bar.height()),
+        "长标题把页头撑成 {} 高（应 56）——说明折行了",
+        bar.height()
+    );
+
+    // ---- ③ 标题不许压到 trailing 动作上 ----
+    let title_ink = shot
+        .band_extent(
+            rgb(ui.color(Role::OnSurface)),
+            bar.top,
+            bar.bottom,
+            bar.left + 40,
+            bar.right.saturating_sub(90),
+        )
+        .expect("页头里应有标题墨迹");
+    let trailing = shot
+        .band_extent(
+            rgb(ui.color(Role::OnSurfaceVariant)),
+            bar.top,
+            bar.bottom,
+            bar.right.saturating_sub(90),
+            bar.right,
+        )
+        .expect("页头右侧应有 trailing 图标墨迹");
+    assert!(
+        title_ink.1 + 2 < trailing.0,
+        "长标题墨迹右缘 {} 压到 trailing 图标左缘 {} 上了（应被裁在文本区里）",
+        title_ink.1,
+        trailing.0
+    );
+
+    eprintln!(
+        "[navigation::probe] long: 行高 {heights:?}，页头 {} 高，标题右缘 {} < trailing {}",
+        bar.height(),
+        title_ink.1,
+        trailing.0
+    );
+}
diff --git a/crates/app-iced/src/components/navigation/probe/scan.rs b/crates/app-iced/src/components/navigation/probe/scan.rs
new file mode 100644
index 0000000..1299db9
--- /dev/null
+++ b/crates/app-iced/src/components/navigation/probe/scan.rs
@@ -0,0 +1,379 @@
+//! `probe` 的读图器（`probe.rs` 拆出来的：单文件 ≤400 行，AGENTS.md §3-1）。
+//!
+//! 只做三件事：读 PNG、找同色的连通块（`BBox`）、量一条横带里某颜色的墨迹范围
+//! 与「一条细线」。判据在 `probe.rs` / `probe/divider.rs` / `probe/long.rs`。
+//!
+//! ## 已知边界（分隔线守卫，写在这里供以后改的人查）
+//!
+//! 1. **≤25% 覆盖的淡线找不到** → 表现是 **loud red**（`find_thin_line` 返回 `None`，
+//!    `divider::check` 直接 panic「锚定失败」），**不是假绿**。原因：`find_thin_line` 的
+//!    `TOL=6` 是单通道可辨差下限，40% 覆盖行实测 `(9,6,4)` 刚好在线上，25% 覆盖行只有
+//!    `(6,4,2)`，会落到判据外——但相邻那行是满覆盖（`(25,17,10)`），所以真实渲染的画法下
+//!    行锚定不会丢；只有「整条线都画在半像素上」才会既找不到又看起来像没画。
+//! 2. **身份校验绑定了 `SurfaceVariant`**：`divider::check` 用
+//!    `Surface → SurfaceVariant` 的插值做身份校验。若哪天 Secondary 分隔线换了角色色
+//!    （比如改回 `OutlineVariant`），这里会 loud red——届时改 `divider.rs` 里那一行 `Role`。
+//! 3. **只认「一条横线」**：竖向分隔线（本项目不用）与圆角/虚线画法不在判据内。
+//! 4. **深浅两档**：浅色图必跑；深色图存在就跑（`tabs-dark.png`），深色 divider 对比更低
+//!    （实测线色 `(46,60,70)`，与深色 Surface 的差比浅色档小），更值得测。
+
+use std::path::Path;
+
+use unlucky_design::color::SchemeFlavor;
+use unlucky_design::typography::Platform;
+
+use crate::theme::{Families, Ui};
+
+/// 字体族（与 `gallery::probe` 同一套）。
+pub(super) const FAMILIES: Families = Families {
+    text: "Segoe UI",
+    display: "Segoe UI",
+    mono: "Consolas",
+};
+
+/// 颜色比对容差。
+///
+/// **3 而不是 10**：本家族要区分的几个容器色本身很接近（light 下
+/// `SurfaceContainerLow (235,245,255)` vs `SurfaceContainer (227,239,251)` 只差 8/6/4），
+/// 容差 10 会把「取景板」和「滚动后的 AppBar」连成一块，量出来的高度就不对了。
+/// 实色区域是精确值，3 足够吸收抗锯齿的取整误差。
+pub(super) const TOLERANCE: u8 = 3;
+
+pub(super) type Rgb = [u8; 3];
+
+pub(super) fn ui(flavor: SchemeFlavor) -> Ui {
+    Ui::with_platform(flavor, Platform::Windows, FAMILIES)
+}
+
+pub(super) fn rgb(color: iced::Color) -> Rgb {
+    [
+        (color.r * 255.0).round() as u8,
+        (color.g * 255.0).round() as u8,
+        (color.b * 255.0).round() as u8,
+    ]
+}
+
+pub(super) fn matches(pixel: Rgb, expected: Rgb) -> bool {
+    // **每个通道**都在容差内；`differs` 是它的否定（任一通道超差即「不同」）
+    !differs(pixel, expected, TOLERANCE)
+}
+
+/// 两个颜色在**每个通道**上都不超过 `tol`。
+pub(super) fn differs(pixel: Rgb, expected: Rgb, tol: u8) -> bool {
+    pixel.iter().zip(expected).any(|(a, b)| a.abs_diff(b) > tol)
+}
+
+/// 一个外接框（闭区间）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(super) struct BBox {
+    pub(super) left: usize,
+    pub(super) right: usize,
+    pub(super) top: usize,
+    pub(super) bottom: usize,
+}
+
+impl BBox {
+    pub(super) fn width(&self) -> usize {
+        self.right - self.left + 1
+    }
+
+    pub(super) fn height(&self) -> usize {
+        self.bottom - self.top + 1
+    }
+}
+
+/// 一张图的像素访问器。
+pub(super) struct Shot {
+    pub(super) width: usize,
+    pub(super) height: usize,
+    pixels: Vec<Rgb>,
+}
+
+impl Shot {
+    pub(super) fn load(path: &Path) -> Self {
+        let bytes = std::fs::read(path).unwrap_or_else(|e| panic!("读不动 {path:?}：{e}"));
+        let image = image::load_from_memory(&bytes)
+            .unwrap_or_else(|e| panic!("解 PNG 失败 {path:?}：{e}"))
+            .to_rgb8();
+        assert_eq!(
+            (image.width() as usize, image.height() as usize),
+            (1180, 760),
+            "验收图必须是 D30 的 1180×760 @100% DPI"
+        );
+        Self {
+            width: image.width() as usize,
+            height: image.height() as usize,
+            pixels: image.pixels().map(|p| p.0).collect(),
+        }
+    }
+
+    pub(super) fn at(&self, x: usize, y: usize) -> Rgb {
+        self.pixels[y * self.width + x]
+    }
+
+    /// 某种颜色的**全部**连通块（面积 ≥ 24；文字笔画太碎的块直接丢掉）。
+    pub(super) fn blocks(&self, color: Rgb) -> Vec<BBox> {
+        let mut seen = vec![false; self.width * self.height];
+        let mut found = Vec::new();
+        for y in 0..self.height {
+            for x in 0..self.width {
+                if seen[y * self.width + x] || !matches(self.at(x, y), color) {
+                    continue;
+                }
+                let mut stack = vec![(x, y)];
+                seen[y * self.width + x] = true;
+                let mut bbox = BBox {
+                    left: x,
+                    right: x,
+                    top: y,
+                    bottom: y,
+                };
+                while let Some((cx, cy)) = stack.pop() {
+                    bbox.left = bbox.left.min(cx);
+                    bbox.right = bbox.right.max(cx);
+                    bbox.top = bbox.top.min(cy);
+                    bbox.bottom = bbox.bottom.max(cy);
+                    for (nx, ny) in [
+                        (cx + 1, cy),
+                        (cx.saturating_sub(1), cy),
+                        (cx, cy + 1),
+                        (cx, cy.saturating_sub(1)),
+                    ] {
+                        if nx < self.width
+                            && ny < self.height
+                            && !seen[ny * self.width + nx]
+                            && matches(self.at(nx, ny), color)
+                        {
+                            seen[ny * self.width + nx] = true;
+                            stack.push((nx, ny));
+                        }
+                    }
+                }
+                if bbox.width() * bbox.height() >= 24 {
+                    found.push(bbox);
+                }
+            }
+        }
+        found
+    }
+
+    /// 矩形内**最深**的像素（禁用的核心笔画就是精确的混合色，用它判角色最稳）。
+    pub(super) fn darkest(&self, bbox: &BBox) -> Option<Rgb> {
+        let mut best: Option<(u32, Rgb)> = None;
+        for y in bbox.top..=bbox.bottom.min(self.height - 1) {
+            for x in bbox.left..=bbox.right.min(self.width - 1) {
+                let pixel = self.at(x, y);
+                let sum: u32 = pixel.iter().map(|c| u32::from(*c)).sum();
+                if best.is_none_or(|(current, _)| sum < current) {
+                    best = Some((sum, pixel));
+                }
+            }
+        }
+        best.map(|(_, pixel)| pixel)
+    }
+
+    /// 矩形里某颜色墨迹的左右范围（量图标/文字位置用）。
+    pub(super) fn band_extent(
+        &self,
+        color: Rgb,
+        y0: usize,
+        y1: usize,
+        x0: usize,
+        x1: usize,
+    ) -> Option<(usize, usize)> {
+        let mut span: Option<(usize, usize)> = None;
+        for y in y0..=y1.min(self.height - 1) {
+            for x in x0..=x1.min(self.width - 1) {
+                if matches(self.at(x, y), color) {
+                    span = Some(match span {
+                        Some((l, r)) => (l.min(x), r.max(x)),
+                        None => (x, x),
+                    });
+                }
+            }
+        }
+        span
+    }
+
+    /// 找「一条**细、低对比、近乎实心**的长横线」，返回 `(y, x0, x1)`：
+    /// `y` 是线最实的那一行，`x0..x1` 是**该行整段墨迹的跨度**（不是某一次连续 run 的窗口）。
+    ///
+    /// 四条判据，每条都对应一次真实的假通过（视觉 r1 P2-2 复核时被点出来的）：
+    ///
+    /// 1. **跨度 ≥ `min_len`**（200）：`Secondary` 分隔线整行 242px；标题/标签行凑不满，能跳过它们。
+    /// 2. **近乎实心**（墨迹数 ≥ 跨度 × 4/5）：逐 tab 分段时中间是真缺口，但只有 1~2px，仍算实心
+    ///    ——**必须先能找到这一行**，再由 [`Shot::line_segments`] 把缺口数成多段。
+    ///    （早先「凑满 150px 就 return，然后在窗口里数段」的写法会滑过缺口，永远数到 1。）
+    /// 3. **薄**（跨中点纵向墨迹 ≤ 3 行）：五态行里的 hover 底色是 40px 高的带，被这条排除
+    ///    （早先的写法会把那条 224px 的带选中，量到完全不同的元素）。
+    /// 4. **低对比**（线色与底色的单通道最大差 ≤ `max_contrast`）：`Primary` 指示条是高饱和色，被排除。
+    ///
+    /// `TOL` 的口径：**单通道**最大可辨差，取 6。40% 覆盖的抗锯齿行实测单通道差 `(9,6,4)`，
+    /// 6 能看见它、又挡住 ±3 的渲染噪声；覆盖再低的行会落到判据外，但**相邻那行是满覆盖**
+    /// （实测线色差 25/17/10），所以行的锚定不会丢。
+    pub(super) fn find_thin_line(
+        &self,
+        background: Rgb,
+        expected: Rgb,
+        min_len: usize,
+        max_contrast: u8,
+    ) -> Option<(usize, usize, usize, Rgb)> {
+        const TOL: u8 = 6;
+        let is_ink = |pixel: Rgb| differs(pixel, background, TOL);
+        let contrast = |pixel: Rgb| {
+            pixel
+                .iter()
+                .zip(background)
+                .map(|(p, q)| p.abs_diff(q))
+                .max()
+                .unwrap_or(0)
+        };
+
+        for y in 0..self.height {
+            let ink: Vec<usize> = (0..self.width).filter(|x| is_ink(self.at(*x, y))).collect();
+            let (Some(&first), Some(&last)) = (ink.first(), ink.last()) else {
+                continue;
+            };
+            let len = last - first + 1;
+            if len < min_len || ink.len() * 5 < len * 4 {
+                continue;
+            }
+            // 薄：跨中点纵向墨迹 ≤ 3 行
+            let mid = (first + last) / 2;
+            let mut top = y;
+            while top > 0 && is_ink(self.at(mid, top - 1)) {
+                top -= 1;
+            }
+            let mut bottom = y;
+            while bottom + 1 < self.height && is_ink(self.at(mid, bottom + 1)) {
+                bottom += 1;
+            }
+            if bottom - top + 1 > 3 {
+                continue;
+            }
+            // 低对比：取这条细带里最实的一行（满覆盖），跨段与线色都按那一行算
+            let best = (top..=bottom)
+                .max_by_key(|candidate| {
+                    (first..=last)
+                        .filter(|x| is_ink(self.at(*x, *candidate)))
+                        .count()
+                })
+                .unwrap_or(y);
+            let line = self.modal_color(best, first, last);
+            let c = contrast(line);
+            if c > max_contrast || c <= TOL {
+                continue;
+            }
+            // **身份校验**：线色必须落在 `底色 → 预期角色色` 的插值线上（覆盖率 30%~105%）。
+            // 只靠「跨度/薄/低对比」挡不住「更靠上的另一条同类细线」（复审 r3 的
+            // `decoy_outline_gap` / `decoy_hover_gap` 两个反例都因此锚错行）。
+            let Some(coverage) = Self::blend_coverage(line, background, expected) else {
+                eprintln!(
+                    "[probe] divider skip y={best} color={line:?}（不是预期角色色的插值，拒绝）"
+                );
+                continue;
+            };
+            if !(0.30..=1.05).contains(&coverage) {
+                eprintln!(
+                    "[probe] divider skip y={best} color={line:?}（覆盖率 {coverage:.2} 出界，拒绝）"
+                );
+                continue;
+            }
+            return Some((best, first, last, line));
+        }
+        None
+    }
+
+    /// `y` 行 `[x0, x1]` 上「按该行**墨迹众数色**」数的连通段数（分隔线断没断）。
+    ///
+    /// 参考色为什么不能取「跨度中点那一个像素」：缺口恰落在中点时，参考色变成页面底色，
+    /// 数出来的是「底色有几段」→ 恒为 1 → **假绿**（复审 r3 的 `gap_at_mid` 反例）。
+    /// 众数色在整段跨度里天然是线自己的颜色（242px 的线 vs ≤4px 的缺口）。
+    pub(super) fn line_segments(&self, y: usize, x0: usize, x1: usize) -> usize {
+        let line = self.modal_color(y, x0, x1);
+        let mut segments = 0;
+        let mut in_run = false;
+        for x in x0..=x1 {
+            let on = matches(self.at(x, y), line);
+            if on && !in_run {
+                segments += 1;
+                in_run = true;
+            } else if !on {
+                in_run = false;
+            }
+        }
+        segments
+    }
+
+    /// `y` 行 `[x0, x1]` 里出现次数最多的颜色（分隔线的线色）。
+    pub(super) fn modal_color(&self, y: usize, x0: usize, x1: usize) -> Rgb {
+        let mut counts: std::collections::HashMap<Rgb, usize> = std::collections::HashMap::new();
+        for x in x0..=x1.min(self.width - 1) {
+            *counts.entry(self.at(x, y)).or_insert(0) += 1;
+        }
+        counts
+            .into_iter()
+            .max_by_key(|(_, n)| *n)
+            .map(|(c, _)| c)
+            .unwrap_or(self.at(x0.min(self.width - 1), y))
+    }
+
+    /// `pixel` 是否落在 `from → to` 的插值线上（覆盖率 t），返回三个通道一致时的平均 t。
+    ///
+    /// 用来给「这条线是不是某个角色色」做**身份校验**：比「单通道差 ≤N」稳得多——
+    /// 实测 `OutlineVariant (200,212,224)` → t=(1.84,2.24,3.1) 出界；
+    /// hover 8% `(228,233,238)` → t=(0.72,1.0,1.7) 三通道散开 0.98；两者都被拒。
+    /// 而真分隔线满覆盖 `(221,233,245)` → t=(1,1,1)；40% 覆盖的抗锯齿行 → t≈(0.36,0.35,0.40) 被接受。
+    ///
+    /// 只统计 `|to - from| > 4` 的通道（差太小的通道不携带信息，噪声会把 t 带偏）。
+    pub(super) fn blend_coverage(pixel: Rgb, from: Rgb, to: Rgb) -> Option<f32> {
+        let mut ts = Vec::new();
+        for ((p, f), t) in pixel.iter().zip(from).zip(to) {
+            let delta = f32::from(t) - f32::from(f);
+            if delta.abs() <= 4.0 {
+                continue;
+            }
+            ts.push((f32::from(*p) - f32::from(f)) / delta);
+        }
+        if ts.is_empty() {
+            return None;
+        }
+        let max = ts.iter().cloned().fold(f32::MIN, f32::max);
+        let min = ts.iter().cloned().fold(f32::MAX, f32::min);
+        if max - min > 0.25 {
+            return None;
+        }
+        Some(ts.iter().sum::<f32>() / ts.len() as f32)
+    }
+
+    /// 矩形内「与底色不同」的像素的左右范围（量文本墨迹用）。
+    ///
+    /// 为什么不按精确文字色找：小字号抗锯齿后几乎没有像素落在**精确**色上（容差 3 时实测
+    /// 「Logs」只剩 12px）。改成「与底色不同即墨迹」，既与字色无关，也不会被状态层带偏。
+    pub(super) fn band_ink(
+        &self,
+        background: Rgb,
+        x0: usize,
+        x1: usize,
+        y0: usize,
+        y1: usize,
+    ) -> Option<(usize, usize)> {
+        let mut span: Option<(usize, usize)> = None;
+        for y in y0..=y1.min(self.height - 1) {
+            for x in x0..=x1.min(self.width - 1) {
+                let pixel = self.at(x, y);
+                let differs = pixel
+                    .iter()
+                    .zip(background)
+                    .any(|(a, b)| a.abs_diff(b) > 12);
+                if differs {
+                    span = Some(match span {
+                        Some((l, r)) => (l.min(x), r.max(x)),
+                        None => (x, x),
+                    });
+                }
+            }
+        }
+        span
+    }
+}
diff --git a/crates/app-iced/src/components/navigation/tabs.rs b/crates/app-iced/src/components/navigation/tabs.rs
new file mode 100644
index 0000000..a89d683
--- /dev/null
+++ b/crates/app-iced/src/components/navigation/tabs.rs
@@ -0,0 +1,359 @@
+//! Tabs（`research/12b` §6）：**Primary**（下方 3px 指示条）与 **Secondary**（1px 分隔线）。
+//!
+//! ## 参考值（`[源]` = A1，本轮 `javap` 实读本机 AAR）
+//!
+//! ```text
+//! PrimaryNavigationTabTokens:   ContainerHeight 48、IconAndLabelTextContainerHeight 64、
+//!                               ActiveIndicatorHeight 3、ActiveIndicatorShape RoundedCornerShape(3dp)、
+//!                               IconSize 24、ContainerShape CornerNone、LabelTextFont TitleSmall
+//!                               ActiveIndicatorColor=Primary；Active*/Inactive* 各态内容色（见下表）
+//! SecondaryNavigationTabTokens: ContainerHeight 48、DividerHeight、DividerColor=SurfaceVariant、
+//!                               ActiveLabelTextColor=OnSurface、InactiveLabelTextColor=OnSurfaceVariant
+//! ```
+//!
+//! | 项 | Primary | Secondary |
+//! |---|---|---|
+//! | 选中内容色 | **`Primary`** | **`OnSurface`**（不是 Primary——6.5 明写） |
+//! | 未选内容色 | `OnSurfaceVariant` | `OnSurfaceVariant` |
+//! | hover / focus / pressed | 未选项提到 **`OnSurface`**，选中项保持不变 | 同左 |
+//! | 底部条 | 仅选中项：**3px `Primary`**，宽度**跟随该 tab** | 所有项：**1px `SurfaceVariant`**（连成一条线） |
+//!
+//! 尺寸/圆角/线厚全部来自 [`TabsGeometry`]（**G22/G23**：`LayoutMetrics` 没有 Tabs 档）。
+//!
+//! ## 指示条怎么做到「宽度跟随选中项」
+//!
+//! iced 没有「取到渲染后文本宽度」的公开 API，所以这里用 [`stack`] 的**分层语义**：
+//!
+//! 1. `Stack` 的**底层**是 tab 自己的内容容器（`Length::Shrink` → 宽度 = 文本实测宽 + 2×16）；
+//! 2. `Stack` 的**上层**是 `Length::Fill` 的指示条。`Stack::layout` 先按**底层**定尺寸，再用
+//!    「已知尺寸」的 `Limits` 布局其余层（`iced_widget-0.14.2/src/stack.rs` 的
+//!    `size = limits.resolve(self.width, self.height, base.size())`）——于是 Fill 的指示条
+//!    拿到的正好是「这个 tab 的宽」，**不是**整行宽。
+//!
+//! 这也顺带避开 Q8 的另一面：把条写成 `center_x(Fill)` 会把它撑成整行。
+//!
+//! ## 横向滚动
+//!
+//! 整行外面套 `scrollable`（`Direction::Horizontal`，滚动条 `Scrollbar::hidden()`）：
+//! tab 宽度因此是**内容宽**而不是「行宽 ÷ n」——官方 `ScrollableTabRow` 的口径。
+//! `TabMinWidth = 90` **本轮不施加**（iced 无 min-width，登记在 G23）。
+
+use iced::widget::text::{LineHeight, Wrapping};
+use iced::widget::{button, container, scrollable, space, text, Row, Stack};
+use iced::{Alignment, Background, Border, Color, Element, Length, Padding, Pixels, Shadow};
+
+use unlucky_design::color::Role;
+use unlucky_design::icons::IconKind;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::typography::TypeRole;
+
+use crate::icons;
+use crate::theme::Ui;
+
+use super::super::interaction::{self, Interaction};
+use super::super::layout;
+use super::geometry::{TabsGeometry, TABS_ICON_HEIGHT};
+
+/// 两种 Tabs（`research/12b` §6；M3 的 `PrimaryTabRow` / `SecondaryTabRow`）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum TabsVariant {
+    /// 主标签页：选中项下方 3px `Primary` 指示条。
+    Primary,
+    /// 次标签页：1px `SurfaceVariant` 分隔线 + 选中项 `OnSurface` 文字。
+    Secondary,
+}
+
+impl TabsVariant {
+    /// 两种变体（gallery 状态矩阵按这个次序出图）。
+    pub const ALL: [TabsVariant; 2] = [TabsVariant::Primary, TabsVariant::Secondary];
+
+    /// 稳定名字（截图文件名 / 图例用）。
+    pub const fn name(self) -> &'static str {
+        match self {
+            TabsVariant::Primary => "primary",
+            TabsVariant::Secondary => "secondary",
+        }
+    }
+
+    /// 是否是 Primary（指示条 3px）。
+    pub const fn is_primary(self) -> bool {
+        matches!(self, TabsVariant::Primary)
+    }
+}
+
+/// 一个标签页。
+#[derive(Debug, Clone)]
+pub struct Tab<'a, M> {
+    label: &'a str,
+    icon: Option<IconKind>,
+    selected: bool,
+    on_press: Option<M>,
+    state: Option<Interaction>,
+}
+
+impl<'a, M> Tab<'a, M> {
+    /// 一个未选中的 tab。
+    pub fn new(label: &'a str, on_press: M) -> Self {
+        Self {
+            label,
+            icon: None,
+            selected: false,
+            on_press: Some(on_press),
+            state: None,
+        }
+    }
+
+    /// 选中（内容色换成激活档 + 画指示条）。
+    pub fn selected(mut self) -> Self {
+        self.selected = true;
+        self
+    }
+
+    /// 前置图标（24，`IconSize::Toolbar`；带图标的容器高官方是 64，本轮只做文字档）。
+    pub fn icon(mut self, kind: IconKind) -> Self {
+        self.icon = Some(kind);
+        self
+    }
+
+    /// 强制视觉态（gallery 取证；不动状态机）。
+    pub fn state(mut self, state: Interaction) -> Self {
+        self.state = Some(state);
+        self
+    }
+
+    /// 转禁用：**只清消息**（修饰器，不是构造函数）。
+    pub fn disabled(mut self) -> Self {
+        self.on_press = None;
+        self
+    }
+}
+
+/// 一行标签页。
+#[derive(Debug, Clone)]
+pub struct Tabs<'a, M> {
+    variant: TabsVariant,
+    tabs: Vec<Tab<'a, M>>,
+}
+
+impl<'a, M> Tabs<'a, M> {
+    /// Primary tabs（3px 指示条）。
+    pub fn primary() -> Self {
+        Self {
+            variant: TabsVariant::Primary,
+            tabs: Vec::new(),
+        }
+    }
+
+    /// Secondary tabs（1px 分隔线）。
+    pub fn secondary() -> Self {
+        Self {
+            variant: TabsVariant::Secondary,
+            tabs: Vec::new(),
+        }
+    }
+
+    /// 追加一个 tab。
+    pub fn tab(mut self, tab: Tab<'a, M>) -> Self {
+        self.tabs.push(tab);
+        self
+    }
+}
+
+/// 一个 tab 的内容色（A1 的 `Active*` / `Inactive*` / 各态表，见模块文档）。
+fn content_color(ui: &Ui, primary: bool, state: Interaction, selected: bool) -> Color {
+    if state.is_disabled() {
+        // A1 的 Tabs 没有 Disabled* token（实读：Primary/Secondary 两套都只有 Active/Inactive × 四态），
+        // 按 ListItem 的 38% 口径处理 —— 登记 `[估]`。
+        return interaction::disabled_content_over_role(ui, Role::OnSurface, false);
+    }
+    if selected {
+        // 6.5：Primary 选中 `Primary`；Secondary 选中 `OnSurface`
+        return if primary {
+            ui.color(Role::Primary)
+        } else {
+            ui.color(Role::OnSurface)
+        };
+    }
+    match state {
+        // 未选中静息 `OnSurfaceVariant`；hover/focus/pressed 提到 `OnSurface`（A1 的 Inactive* 四态）
+        Interaction::Enabled => ui.color(Role::OnSurfaceVariant),
+        _ => ui.color(Role::OnSurface),
+    }
+}
+
+/// Primary 指示条的颜色（只有选中项有；禁用项降档，否则「点不动却亮着」）。
+fn bar_color(ui: &Ui, state: Interaction, selected: bool) -> Option<Color> {
+    if !selected {
+        return None;
+    }
+    if state.is_disabled() {
+        return Some(interaction::disabled_content_over_role(
+            ui,
+            Role::OnSurface,
+            false,
+        ));
+    }
+    Some(ui.color(Role::Primary))
+}
+
+/// 6.6：Secondary 的分隔线色 = **`SurfaceVariant`**（不是 `OutlineVariant`——那是 §22 的分隔线）。
+///
+/// 色值只在这里出现一次：整行那条线与逐 tab 的实现都从这里取。
+fn secondary_line_color(ui: &Ui) -> Color {
+    ui.color(Role::SurfaceVariant)
+}
+
+/// 一行标签页（自带横向滚动）。
+pub fn tabs<'a, M: Clone + 'a>(ui: &'a Ui, tabs: Tabs<'a, M>) -> Element<'a, M> {
+    let geometry = TabsGeometry::of(ui);
+    let primary = tabs.variant.is_primary();
+    // 6.1：带图标时容器高 **64**（`IconAndLabelTextContainerHeight`），纯文字 48
+    let height = if tabs.tabs.iter().any(|tab| tab.icon.is_some()) {
+        TABS_ICON_HEIGHT
+    } else {
+        geometry.height
+    };
+
+    let mut row = Row::new()
+        .height(Length::Fixed(height))
+        .align_y(Alignment::Center);
+    for tab in tabs.tabs {
+        row = row.push(tab_cell(ui, tab, geometry, primary, height));
+    }
+
+    let body: Element<'a, M> = if primary {
+        row.into()
+    } else {
+        // A1 的 Secondary 分隔线是**整行一条直线**，不是每个 tab 一段：
+        // 逐段画会在相邻段之间留缝（视觉 r1 P2-2）。这里用 `Stack` 把一条 Fill 线压在整行底下，
+        // 底座是 tab 行本身（Shrink → 内容宽），所以线长 = tab 行总宽，横向滚动时跟着走。
+        let line = container(space::vertical())
+            .width(Length::Fill)
+            .height(Length::Fixed(geometry.secondary_bar))
+            .style(move |_theme| container::Style {
+                background: Some(Background::Color(secondary_line_color(ui))),
+                ..container::Style::default()
+            });
+        Stack::new()
+            .push(container(row))
+            .push(
+                container(line)
+                    .width(Length::Fill)
+                    .height(Length::Fill)
+                    .align_y(Alignment::End),
+            )
+            .into()
+    };
+
+    scrollable(body)
+        .direction(scrollable::Direction::Horizontal(
+            scrollable::Scrollbar::hidden(),
+        ))
+        .height(Length::Fixed(height))
+        .into()
+}
+
+/// 一个 tab 单元（内容 + 底部条）。
+fn tab_cell<'a, M: Clone + 'a>(
+    ui: &'a Ui,
+    tab: Tab<'a, M>,
+    geometry: TabsGeometry,
+    primary: bool,
+    height: f32,
+) -> Element<'a, M> {
+    let forced = tab.state.or(if tab.on_press.is_none() {
+        Some(Interaction::Disabled)
+    } else {
+        None
+    });
+    let state = forced.unwrap_or(Interaction::Enabled);
+    let selected = tab.selected;
+    let color = content_color(ui, primary, state, selected);
+    let style = ui.style(TypeRole::TitleSmall);
+
+    let label = text(tab.label)
+        .size(style.size_px)
+        .line_height(LineHeight::Absolute(Pixels(style.line_height_px)))
+        // 单行（容器高固定 48/64）：长标签让 tab 变宽 + 横向滚动，不折行（偏离 D-M79-5）
+        .wrapping(Wrapping::None)
+        .font(ui.font_of(style))
+        .color(color);
+
+    let mut content = Row::new().align_y(Alignment::Center).spacing(geometry.pad);
+    if let Some(kind) = tab.icon {
+        content = content.push(layout::fixed(
+            geometry.icon,
+            geometry.icon,
+            icons::view::<M>(kind, color),
+        ));
+    }
+    content = content.push(label);
+
+    let bar_height = geometry.bar(primary);
+    // 底层：内容自己决定宽度（Shrink），底部留出条的高度 —— 未选中的 Primary tab 也占同样的高
+    let base = container(content)
+        .height(Length::Fixed(height))
+        // Q21：要给居中就两轴都显式给（`Container` 默认 Left/Top）
+        .align_x(Alignment::Center)
+        .align_y(Alignment::Center)
+        .padding(Padding {
+            top: 0.0,
+            right: geometry.pad,
+            bottom: bar_height,
+            left: geometry.pad,
+        });
+
+    // Primary：逐 tab 画条（要跟随该 tab 的宽度）；Secondary：整行一条，在 `tabs()` 里画
+    let bar = if primary {
+        bar_color(ui, state, selected)
+    } else {
+        None
+    };
+    let radius = geometry.indicator_radius();
+    let mut stack = Stack::new().push(base);
+    if let Some(color) = bar {
+        // 上层：Fill —— `Stack` 先按底层定尺寸，所以这里的 Fill = 这个 tab 的宽（不是整行）
+        stack = stack.push(
+            container(
+                container(space::vertical())
+                    .width(Length::Fill)
+                    .height(Length::Fixed(bar_height))
+                    .style(move |_theme| container::Style {
+                        background: Some(Background::Color(color)),
+                        border: Border {
+                            radius,
+                            ..Border::default()
+                        },
+                        ..container::Style::default()
+                    }),
+            )
+            .width(Length::Fill)
+            .height(Length::Fill)
+            .align_y(Alignment::End),
+        );
+    }
+
+    let fill = interaction::overlay_color(ui, state, Role::OnSurface, Role::Surface);
+    let button = button(stack)
+        .height(Length::Fixed(height))
+        .padding(0)
+        .style(move |_theme, _status| button::Style {
+            background: fill.map(Background::Color),
+            text_color: color,
+            // ContainerShape = CornerNone（tab 本身是直角；圆角只在指示条上）
+            border: Border {
+                radius: ui.radius_dp(ShapeScale::None),
+                ..Border::default()
+            },
+            shadow: Shadow::default(),
+            snap: true,
+        });
+
+    match tab.on_press {
+        Some(message) => button.on_press(message).into(),
+        None => button.into(),
+    }
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/app-iced/src/components/navigation/tabs/tests.rs b/crates/app-iced/src/components/navigation/tabs/tests.rs
new file mode 100644
index 0000000..0446961
--- /dev/null
+++ b/crates/app-iced/src/components/navigation/tabs/tests.rs
@@ -0,0 +1,150 @@
+//! `tabs` 的单元测试（split 拆出来的：单文件 ≤400 行，AGENTS.md §3-1）。
+
+use super::*;
+
+use unlucky_design::color::SchemeFlavor;
+use unlucky_design::typography::Platform;
+
+use crate::theme::Families;
+
+use super::super::super::interaction;
+
+fn ui() -> Ui {
+    Ui::with_platform(
+        SchemeFlavor::Light,
+        Platform::Windows,
+        Families {
+            text: "Segoe UI",
+            display: "Segoe UI",
+            mono: "Consolas",
+        },
+    )
+}
+
+/// 6.5：选中色 Primary 用 `Primary`，Secondary 用 `OnSurface`（**不是** Primary）。
+#[test]
+fn active_colors_follow_the_variant() {
+    let ui = ui();
+    assert_eq!(
+        content_color(&ui, true, Interaction::Enabled, true),
+        ui.color(Role::Primary)
+    );
+    assert_eq!(
+        content_color(&ui, false, Interaction::Enabled, true),
+        ui.color(Role::OnSurface),
+        "6.5：Secondary 的选中项是 OnSurface"
+    );
+    assert_ne!(
+        content_color(&ui, false, Interaction::Enabled, true),
+        ui.color(Role::Primary),
+        "把 Secondary 的选中色写成 Primary 是最常见的串线"
+    );
+}
+
+/// 未选中静息 `OnSurfaceVariant`；hover / focus / pressed 提到 `OnSurface`。
+#[test]
+fn inactive_states_lift_to_on_surface() {
+    let ui = ui();
+    for primary in [true, false] {
+        assert_eq!(
+            content_color(&ui, primary, Interaction::Enabled, false),
+            ui.color(Role::OnSurfaceVariant)
+        );
+        for state in [
+            Interaction::Hovered,
+            Interaction::Focused,
+            Interaction::Pressed,
+        ] {
+            assert_eq!(
+                content_color(&ui, primary, state, false),
+                ui.color(Role::OnSurface),
+                "{state:?} 必须提到 OnSurface"
+            );
+        }
+    }
+}
+
+/// 6.2：Primary 只有选中项有 3px `Primary` 条；禁用项降档。
+#[test]
+fn primary_bar_only_on_the_selected_tab() {
+    let ui = ui();
+    assert_eq!(bar_color(&ui, Interaction::Enabled, false), None);
+    assert_eq!(
+        bar_color(&ui, Interaction::Enabled, true),
+        Some(ui.color(Role::Primary))
+    );
+    assert_eq!(
+        bar_color(&ui, Interaction::Disabled, true),
+        Some(interaction::disabled_content_over_role(
+            &ui,
+            Role::OnSurface,
+            false
+        )),
+        "禁用项「点不动却亮着」是错的"
+    );
+}
+
+/// 6.6：Secondary 的分隔线整行一条，颜色 `SurfaceVariant`（不是 §22 的 `OutlineVariant`）。
+#[test]
+fn secondary_line_is_surface_variant() {
+    let ui = ui();
+    assert_eq!(secondary_line_color(&ui), ui.color(Role::SurfaceVariant));
+    assert_ne!(
+        secondary_line_color(&ui),
+        ui.color(Role::OutlineVariant),
+        "OutlineVariant 是 §22 分隔线的角色，Tabs 不用它"
+    );
+}
+
+/// 禁用是**修饰器**：只清消息，label / 选中态 / 图标全部保留。
+#[test]
+fn disabled_only_clears_the_message() {
+    let tab = Tab::new("Mods", ())
+        .icon(unlucky_design::icons::IconKind::Settings)
+        .selected()
+        .disabled();
+    assert!(tab.on_press.is_none());
+    assert!(tab.icon.is_some());
+    assert!(tab.selected);
+    assert_eq!(tab.label, "Mods");
+}
+
+/// 指示条宽度 = tab 宽 = 文本宽 + 2×16（这条是「跟随选中项宽度」的公式面）。
+#[test]
+fn indicator_width_is_the_tab_width() {
+    let geometry = TabsGeometry::of(&ui());
+    let tab_width = |text_width: f32| text_width + geometry.pad * 2.0;
+    assert_eq!(tab_width(0.0), 32.0, "空文本 = 2×16");
+    // 两段不同长度的文案 ⇒ 指示条宽度必然不同（渲染层断言用它打红）
+    let short = tab_width(40.0);
+    let long = tab_width(120.0);
+    assert_eq!(long - short, 80.0);
+    assert!(long > short);
+}
+
+/// 6.1：带图标的 Tabs 容器高 64（`IconAndLabelTextContainerHeight`），纯文字 48。
+#[test]
+fn icon_tabs_use_the_taller_container() {
+    let ui = ui();
+    assert_eq!(TABS_ICON_HEIGHT, 64.0);
+    assert!(TABS_ICON_HEIGHT > TabsGeometry::of(&ui).height);
+}
+
+/// 3 个 tab 的树能建出来（含选中 / 禁用 / 带图标三条路径）。
+#[test]
+fn view_builds_a_tree() {
+    let ui = ui();
+    let _: Element<'_, ()> = tabs(
+        &ui,
+        Tabs::primary()
+            .tab(Tab::new("General", ()).selected())
+            .tab(Tab::new("Mods", ()).icon(unlucky_design::icons::IconKind::Settings))
+            .tab(Tab::new("Logs", ()).disabled()),
+    );
+    let _: Element<'_, ()> = tabs(
+        &ui,
+        Tabs::secondary()
+            .tab(Tab::new("Release", ()).selected())
+            .tab(Tab::new("Snapshot", ())),
+    );
+}
diff --git a/crates/app-iced/src/components/selection/checkbox.rs b/crates/app-iced/src/components/selection/checkbox.rs
new file mode 100644
index 0000000..41a7d69
--- /dev/null
+++ b/crates/app-iced/src/components/selection/checkbox.rs
@@ -0,0 +1,186 @@
+//! Checkbox（`research/15` §18）：20×20 / 圆角 2 / 描边向内收的 2px 框 / 勾形 12dp 方头 /
+//! indeterminate 形变为居中短横 / Ø40 状态层 / 48 命中区。
+//!
+//! ## 三条容易画错的（每条都有对应的像素断言或单测）
+//!
+//! 1. **描边向内**：外缘恒 20（§18.3）。iced 的 quad 渲染器把描边路径**向内缩半个线宽**
+//!    （`iced_tiny_skia::engine::draw_quad`：`border_bounds + border_width / 2`），与 Compose
+//!    `drawBox` 的 `topLeft = stroke/2, size = 20 − stroke` 同一口径，所以选中/未选中外缘同尺寸。
+//! 2. **勾不是图标**：勾形按路径比例画（`shell::glyph`），代码里**没有第二个 `IconKind`**（§18.6）。
+//! 3. **状态层是 Ø40 的圆**、命中区是 48：两者不同尺寸，所以外壳是透明的 48 按钮，
+//!    里面套一个 40 的圆容器，再套 20 的方框（见 `shell` 的模块文档）。
+
+use iced::widget::{container, row, text};
+use iced::{Alignment, Element, Length, Padding};
+
+use unlucky_design::typography::TypeRole;
+
+use crate::theme::Ui;
+
+use super::super::interaction::Interaction;
+use super::geometry::ControlGeometry;
+use super::paint::{self, Frame};
+use super::shell::{self, StateSource};
+
+/// 复选框的三种取值（§18.6：indeterminate 不是第四种「选中」，是「部分选中」）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CheckValue {
+    /// 未选中：透明内部 + 2px `OnSurfaceVariant` 描边。
+    Unchecked,
+    /// 选中：`Primary` 实心 + 勾。
+    Checked,
+    /// 部分选中：**同样是实心**，勾形变成一条居中短横（不换图标）。
+    Indeterminate,
+}
+
+impl CheckValue {
+    /// 框是否**填充**（选中与 indeterminate 都填，后者只是把勾换成短横）。
+    pub const fn filled(self) -> bool {
+        !matches!(self, CheckValue::Unchecked)
+    }
+
+    /// 是否要画短横而不是勾。
+    pub const fn indeterminate(self) -> bool {
+        matches!(self, CheckValue::Indeterminate)
+    }
+}
+
+/// 一个复选框（框 + 可选标签；`on_toggle` 为 `None` = 禁用）。
+#[derive(Debug, Clone)]
+pub struct Checkbox<'a, M> {
+    label: &'a str,
+    value: CheckValue,
+    on_toggle: Option<M>,
+    error: bool,
+    state: Option<Interaction>,
+}
+
+impl<'a, M> Checkbox<'a, M> {
+    /// 一个二态复选框。
+    pub fn new(label: &'a str, selected: bool, on_toggle: M) -> Self {
+        Self::tri(
+            label,
+            if selected {
+                CheckValue::Checked
+            } else {
+                CheckValue::Unchecked
+            },
+            on_toggle,
+        )
+    }
+
+    /// 三态复选框（`indeterminate` 由调用方给值）。
+    pub fn tri(label: &'a str, value: CheckValue, on_toggle: M) -> Self {
+        Self {
+            label,
+            value,
+            on_toggle: Some(on_toggle),
+            error: false,
+            state: None,
+        }
+    }
+
+    /// 禁用的复选框（无消息；禁用不是「另一种颜色」，见 `paint::checkbox` 的禁用分支）。
+    pub fn disabled(label: &'a str, value: CheckValue) -> Self {
+        Self {
+            label,
+            value,
+            on_toggle: None,
+            error: false,
+            state: None,
+        }
+    }
+
+    /// 校验失败态（§18.7：未选中描边 `Error`，选中填 `Error` + 勾 `OnError`）。
+    pub fn error(mut self) -> Self {
+        self.error = true;
+        self
+    }
+
+    /// 强制视觉态（`--screen=gallery` 取证用；运行期不要调）。
+    pub fn state(mut self, state: Interaction) -> Self {
+        self.state = Some(state);
+        self
+    }
+}
+
+/// 画一个复选框（框 + 标签）。
+pub fn checkbox<'a, M: Clone + 'a>(ui: &'a Ui, spec: Checkbox<'a, M>) -> Element<'a, M> {
+    let geometry = ControlGeometry::checkbox(ui);
+    let filled = spec.value.filled();
+    let indeterminate = spec.value.indeterminate();
+    let error = spec.error;
+    let radius = geometry.radius;
+    let stroke = geometry.stroke;
+    let source = StateSource::new(spec.state, spec.on_toggle.is_some());
+
+    // 勾的颜色与 hover/pressed 无关（A1：`SelectedHover/Focus/PressedIconColor` 都是 `OnPrimary`），
+    // 只随「选中 + 禁用」变 —— 所以这里用**静态**态求值（SVG 的颜色在构建期就要定）。
+    let at_rest = paint::checkbox(ui, filled, error, source.get(), radius, stroke);
+    let glyph: Element<'a, M> = if filled {
+        shell::square(
+            geometry.side,
+            shell::glyph(geometry, indeterminate, at_rest.glyph),
+        )
+    } else {
+        iced::widget::Space::new().into()
+    };
+
+    // 20 方框：填/描边（跟态走）+ 勾
+    let boxed = container(glyph)
+        .width(Length::Fixed(geometry.side))
+        .height(Length::Fixed(geometry.side))
+        .style(source.container_style(move |state| {
+            paint::checkbox(ui, filled, error, state, radius, stroke)
+                .frame
+                .container_style()
+        }));
+
+    // Ø40 状态层：圆（半径 = 直径/2，`ShapeScale::Full` 的等价写法）
+    let layer_side = geometry.state_layer;
+    let layer = container(boxed)
+        .width(Length::Fixed(layer_side))
+        .height(Length::Fixed(layer_side))
+        .align_x(Alignment::Center)
+        .align_y(Alignment::Center)
+        .style(source.container_style(move |state| {
+            Frame {
+                fill: paint::state_layer(ui, state, paint::checkbox_layer_role(filled, error)),
+                outline: None,
+                stroke: 0.0,
+                radius: layer_side / 2.0,
+            }
+            .container_style()
+        }));
+
+    let mut content = row![layer].align_y(Alignment::Center).spacing(geometry.gap);
+    if !spec.label.is_empty() {
+        let style = ui.style(TypeRole::BodyLarge);
+        content = content.push(
+            text(spec.label)
+                .size(style.size_px)
+                .font(ui.font_of(style))
+                .color(paint::label(ui, source.get())),
+        );
+    }
+
+    // 命中区 48：方框 20 + 状态层 40 都在里面垂直居中；
+    // 左右各留 `hit_padding` 透明内边距，无标签时命中区也是 48×48（复审 P2-2）
+    let pad = geometry.hit_padding();
+    let body = container(content)
+        .height(Length::Fill)
+        .align_y(Alignment::Center)
+        .padding(Padding {
+            left: pad,
+            right: pad,
+            ..Padding::default()
+        });
+
+    shell::shell(
+        &source,
+        Length::Shrink,
+        Length::Fixed(geometry.hit),
+        spec.on_toggle,
+        body.into(),
+    )
+}
diff --git a/crates/app-iced/src/components/selection/chip.rs b/crates/app-iced/src/components/selection/chip.rs
new file mode 100644
index 0000000..e84353d
--- /dev/null
+++ b/crates/app-iced/src/components/selection/chip.rs
@@ -0,0 +1,187 @@
+//! Chip（`research/12b` §13）：高 **32** / 圆角 **8** / 水平内边距 **8** / 元素间距 **8** /
+//! 图标 **18**（`IconSize::Button` = 官方 `AssistChipTokens.IconSize`）/ 描边 1px `OutlineVariant`。
+//!
+//! ## 三类（§13 的 Assist / Filter / Input）
+//!
+//! | 类 | 选中态 | 容器 | 文字 | 前置图标 |
+//! |---|---|---|---|---|
+//! | Assist | **无**（一次动作，不是开关） | 透明 + 1px 描边 | `OnSurface` | `Primary` |
+//! | Filter | 有 | 未选透明+描边；选中 `SecondaryContainer` **无描边** | `OnSurfaceVariant` / `OnSecondaryContainer` | 选中态才给勾 |
+//! | Input | 有 | 同 Filter | 同 Filter | 可给 + 后置关闭图标 |
+//!
+//! ## 为什么 Chip 不用 `selection::shell` 那条透明外壳
+//!
+//! M3 的 chip **没有圆形状态层**：hover / pressed 就是把状态层叠在**自己的容器**上，
+//! 而容器尺寸 = 命中区尺寸。所以 chip 直接走 `button` 的样式闭包（与按钮家族同一条产线），
+//! 不需要「48 外壳 + 40 圆」那套。
+
+use iced::widget::{button, container, row, text};
+use iced::{Alignment, Background, Border, Element, Length, Padding, Shadow};
+
+use unlucky_design::icons::IconKind;
+use unlucky_design::typography::TypeRole;
+
+use crate::icons;
+use crate::theme::Ui;
+
+use super::super::interaction::Interaction;
+use super::geometry::ChipGeometry;
+use super::paint::{self, ChipVariant};
+
+/// 一个 chip（可带前后图标；`on_press` 为 `None` = 禁用）。
+#[derive(Debug, Clone)]
+pub struct Chip<'a, M> {
+    label: &'a str,
+    variant: ChipVariant,
+    selected: bool,
+    leading: Option<IconKind>,
+    trailing: Option<IconKind>,
+    on_press: Option<M>,
+    state: Option<Interaction>,
+}
+
+impl<'a, M> Chip<'a, M> {
+    /// Assist chip：辅助动作，**没有**选中态。
+    pub fn assist(label: &'a str, on_press: M) -> Self {
+        Self::new(label, ChipVariant::Assist, false, on_press)
+    }
+
+    /// Filter chip：筛选开关（`selected` 决定容器是否 `SecondaryContainer`）。
+    pub fn filter(label: &'a str, selected: bool, on_press: M) -> Self {
+        Self::new(label, ChipVariant::Filter, selected, on_press)
+    }
+
+    /// Input chip：用户输入的实体（可选中 + 可带关闭图标）。
+    pub fn input(label: &'a str, on_press: M) -> Self {
+        Self::new(label, ChipVariant::Input, false, on_press)
+    }
+
+    /// 转成禁用：**只清消息**，图标 / 选中态 / 状态层全部保留（复审 P2-1）。
+    ///
+    /// 官方禁用态是「容器/描边 12%、文字与**图标** 38%」——只降**不删**。早先的
+    /// `Chip::disabled(label, variant)` 把 leading / trailing / selected 一起丢掉，实测
+    /// assist 78→54、filter·on 74→50（连填充和勾都没了），禁用列里 `filter·on` 与 `filter`
+    /// 逐像素同形，看不出选中与否。
+    pub fn disabled(mut self) -> Self {
+        self.on_press = None;
+        self
+    }
+
+    fn new(label: &'a str, variant: ChipVariant, selected: bool, on_press: M) -> Self {
+        Self {
+            label,
+            variant,
+            selected,
+            leading: None,
+            trailing: None,
+            on_press: Some(on_press),
+            state: None,
+        }
+    }
+
+    /// 前置图标（Assist / Filter 用）。
+    pub fn leading(mut self, kind: IconKind) -> Self {
+        self.leading = Some(kind);
+        self
+    }
+
+    /// 后置图标（Input chip 的关闭键）。
+    pub fn trailing(mut self, kind: IconKind) -> Self {
+        self.trailing = Some(kind);
+        self
+    }
+
+    /// 强制视觉态（gallery 取证用；运行期不要调）。
+    pub fn state(mut self, state: Interaction) -> Self {
+        self.state = Some(state);
+        self
+    }
+}
+
+/// 画一个 chip。
+pub fn chip<'a, M: Clone + 'a>(ui: &'a Ui, spec: Chip<'a, M>) -> Element<'a, M> {
+    let geometry = ChipGeometry::of(ui);
+    let variant = spec.variant;
+    let selected = spec.selected;
+    let disabled = spec.on_press.is_none();
+    let forced = spec.state;
+
+    // 文字/图标色只看「选中 + 禁用」（A1：Filter/Input 的 label 色在 hover/focus/pressed 不变），
+    // 所以这里静态求值；容器（含状态层）在样式闭包里跟态走。
+    let at_rest = paint::chip(
+        ui,
+        variant,
+        selected,
+        if disabled {
+            Interaction::Disabled
+        } else {
+            forced.unwrap_or(Interaction::Enabled)
+        },
+        geometry.radius,
+    );
+
+    let mut content = row![].align_y(Alignment::Center).spacing(geometry.gap);
+    if let Some(kind) = spec.leading {
+        // Q9：图标一律经固定尺寸容器；盒 18 ≠ RENDER_PX(24)，所以必须走 `view_at` 按 18 烘焙，
+        // 否则线宽会被布局缩水（复审 r1 P2-2）。
+        content = content.push(super::super::layout::centered_fixed(
+            geometry.icon,
+            geometry.icon,
+            icons::view_at::<M>(kind, at_rest.icon, geometry.icon),
+        ));
+    }
+
+    let style = ui.style(TypeRole::LabelLarge);
+    content = content.push(
+        text(spec.label)
+            .size(style.size_px)
+            .font(ui.font_of(ui.emphasized(TypeRole::LabelLarge)))
+            .color(at_rest.label),
+    );
+
+    if let Some(kind) = spec.trailing {
+        content = content.push(super::super::layout::centered_fixed(
+            geometry.icon,
+            geometry.icon,
+            icons::view_at::<M>(kind, at_rest.icon, geometry.icon),
+        ));
+    }
+
+    // 垂直居中必须在内容侧做（`button` 把内容放左上角）
+    let body = container(content)
+        .height(Length::Fill)
+        .align_y(Alignment::Center);
+
+    let element = button(body)
+        .height(Length::Fixed(geometry.height))
+        .padding(Padding {
+            top: 0.0,
+            right: geometry.pad,
+            bottom: 0.0,
+            left: geometry.pad,
+        })
+        .style(move |_theme, status| {
+            let state = forced.unwrap_or_else(|| Interaction::from_status(status));
+            let paint = paint::chip(ui, variant, selected, state, geometry.radius);
+            button::Style {
+                background: paint.frame.fill.map(Background::Color),
+                text_color: paint.label,
+                border: Border {
+                    color: paint.frame.outline.unwrap_or(iced::Color::TRANSPARENT),
+                    width: if paint.frame.outline.is_some() {
+                        paint.frame.stroke
+                    } else {
+                        0.0
+                    },
+                    radius: iced::border::Radius::new(paint.frame.radius),
+                },
+                shadow: Shadow::default(),
+                snap: true,
+            }
+        });
+
+    match spec.on_press {
+        Some(message) => element.on_press(message).into(),
+        None => element.into(),
+    }
+}
diff --git a/crates/app-iced/src/components/selection/geometry.rs b/crates/app-iced/src/components/selection/geometry.rs
new file mode 100644
index 0000000..3a6656e
--- /dev/null
+++ b/crates/app-iced/src/components/selection/geometry.rs
@@ -0,0 +1,259 @@
+//! 选择类家族的**几何**：值要么来自令牌，要么在此登记 G 编号（不散落在组件里）。
+//!
+//! ## 参考值 → 落点
+//!
+//! | # | 量 | 参考值 | 来源 | 落点 |
+//! |---|---|---|---|---|
+//! | 18.1 | Checkbox 外框 / 圆角 | **20×20** / **2** | `[源]` `Checkbox.kt:737-738`（`COMPONENT_WIDTH/HEIGHT=18` 是死值，见 §26.2） | `Component::Checkbox.metrics()` + `ComponentRadius::Micro` |
+//! | 18.2 | Checkbox 描边 | **2**（选中时 0） | `[源]` `UnselectedOutlineWidth` | `ComponentMetrics::CHECKBOX.stroke` |
+//! | 18.5 | Checkbox 状态层 | **Ø40** | `[源]` `StateLayerSize` | `ComponentMetrics::CHECKBOX.state_layer` |
+//! | 18.9 | 命中区 / 标签间距 | **48** / **8** | `[源]` `minimumInteractiveComponentSize` / 间距 `[估]` | `LayoutMetrics::touch_target` / `metrics.gap` |
+//! | 19.1 | Radio 外圈 / 环线 | **20** / **2** | `[源]` `IconSize` / `RadioStrokeWidth` | `Component::Radio.metrics()` |
+//! | 19.2 | Radio 内点 | **10**（不是 12） | `[源]` `DotSize=12`，绘制半径 12/2−2/2=5 | `ComponentMetrics::RADIO.inner_dot` |
+//! | 10.1 | Switch 轨道 | **52×32**，圆角 full(16) | `[源]` `TrackWidth/TrackHeight/TrackShape` | [`SwitchGeometry`]（**G16**） |
+//! | 10.2 | Switch 滑块 | 选中 **24** / 未选 **16** / 按下 **28** | `[源]` `Selected/Unselected/PressedHandleWidth` | [`SwitchGeometry`]（**G16**） |
+//! | 13.1 | Chip 高 / 圆角 | **32** / **8** | `[源]` `ContainerHeight` / `ContainerShape=CornerSmall` | `Space::X8` + `Component::Chip.spec().shape` |
+//!
+//! **G16 登记**（续 `research/15` §25 的 G13）：`ComponentMetrics` 只有
+//! `CHECKBOX/RADIO/SEARCH_BAR/NAVIGATION_DRAWER` 四组，**Switch 与 Chip 没有落点**。
+//! 本文件把它们的量收成命名常量（每个都带 A1 出处），等令牌层补
+//! `ComponentMetrics::SWITCH/CHIP` 后整段删除、改走 `Component::Switch.metrics()`。
+//!
+//! **G14 已收口（M86）**：Chip 图标取 `IconSize::Button` = **18**（AAR `AssistChipTokens.IconSize =
+//! 18.0d`，与 12b 13.4 同值），不再是偏离。Switch 滑块内的图标是**另一个值 16**
+//! （`SwitchTokens.SelectedIconSize / UnselectedIconSize = 16.0d`），所以走 `IconSize::SwitchThumb`：
+//! 两者在官方就是两个 token，别为了省一个档位把它们合成一个。
+
+use unlucky_design::component_map::{Component, ComponentMetrics};
+use unlucky_design::icons::IconSize;
+use unlucky_design::spacing::Space;
+
+use crate::theme::Ui;
+
+/// Switch 轨道宽（`SwitchTokens.TrackWidth = 52.0`，**G16**：令牌层无此档）。
+const SWITCH_TRACK_WIDTH: f32 = 52.0;
+/// Switch 轨道描边（`SwitchTokens.TrackOutlineWidth = 2.0`，**G16**）。
+const SWITCH_TRACK_STROKE: f32 = 2.0;
+/// Switch 选中态滑块（`SwitchTokens.SelectedHandleWidth = 24.0`，**G16**）。
+const SWITCH_THUMB_SELECTED: f32 = 24.0;
+/// Switch 未选中态滑块（`SwitchTokens.UnselectedHandleWidth = 16.0`，**G16**）。
+const SWITCH_THUMB_UNSELECTED: f32 = 16.0;
+/// Switch 按下态滑块（`SwitchTokens.PressedHandleWidth = 28.0`，**G16**）。
+const SWITCH_THUMB_PRESSED: f32 = 28.0;
+/// Switch 状态层（`SwitchTokens.StateLayerSize = 40.0`，**G16**；与 Checkbox 同值）。
+const SWITCH_STATE_LAYER: f32 = 40.0;
+
+/// Checkbox / Radio 共用的方框几何（两控件同尺寸、不同形状语言，§18 / §19）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct ControlGeometry {
+    /// 可见外框边长（20）。
+    pub side: f32,
+    /// 描边 / 环线宽度（2；**禁用态不变细**，§18.8）。
+    pub stroke: f32,
+    /// 状态层圆的直径（40）。
+    pub state_layer: f32,
+    /// 最小命中区（48，`LayoutMetrics::touch_target`）。
+    pub hit: f32,
+    /// 框 ↔ 标签间距（8，团队口径 `[估]`）。
+    pub gap: f32,
+    /// 圆角半径：Checkbox = 2（`ComponentRadius::Micro`），Radio = 10（`ShapeScale::Full` 的真圆）。
+    pub radius: f32,
+    /// Radio 内点直径（10）；Checkbox 为 0（没有内点）。
+    pub inner_dot: f32,
+}
+
+impl ControlGeometry {
+    /// Checkbox：20×20 / 圆角 2 / 描边 2 / 状态层 Ø40（全部 `[源]`，见模块表）。
+    pub fn checkbox(ui: &Ui) -> Self {
+        let metrics = metrics(Component::Checkbox);
+        Self {
+            side: metrics.width,
+            stroke: metrics.stroke,
+            state_layer: metrics.state_layer,
+            hit: ui.metrics().touch_target,
+            gap: metrics.gap,
+            // 微控件层（D32）：2dp 不在 `ShapeScale` 刻度里，只能走 `ComponentRadius`。
+            // 传 20 拿不到值说明有人把它挪到容器层了——那是 D32 违规，`unwrap_or` 会悄悄
+            // 变成直角，所以这里用 `expect` 直接炸（比图画错好查）。
+            radius: metrics
+                .radius
+                .expect("Checkbox 的圆角必须在微控件层（ComponentSpec::micro_radius）")
+                .radius_px(metrics.width)
+                .expect("Checkbox 20dp ≤ 微控件上限 24dp"),
+            // Checkbox 没有内点（内点是 radio 的语言，§19.6 明令两者不许混用）
+            inner_dot: metrics.inner_dot,
+        }
+    }
+
+    /// Radio：20 / 环线 2 / 内点 10 / 状态层 Ø40；圆角是**真圆**（`ShapeScale::Full`）。
+    pub fn radio(ui: &Ui) -> Self {
+        let metrics = metrics(Component::Radio);
+        Self {
+            side: metrics.width,
+            stroke: metrics.stroke,
+            state_layer: metrics.state_layer,
+            hit: ui.metrics().touch_target,
+            gap: metrics.gap,
+            radius: Component::Radio.spec().shape.radius_px(metrics.width),
+            // 内点 **10 不是 12**（§19.2：12 是含描边前的名义值，绘制半径 = 12/2 − 2/2 = 5）
+            inner_dot: metrics.inner_dot,
+        }
+    }
+
+    /// 命中区比可见状态层宽出来的部分（左右**各一份**）：`(48 − 40) / 2 = 4`。
+    ///
+    /// 无标签时行宽只有状态层的 40dp，命中区就少 8dp；A1 的
+    /// `minimumInteractiveComponentSize` 是 **48**，所以 view 侧左右各留这段透明内边距
+    /// （复审 P2-2）。有标签时行宽本来 ≥48，这段内边距不改变结论，只是保持两处口径一致。
+    pub fn hit_padding(&self) -> f32 {
+        (self.hit - self.state_layer) / 2.0
+    }
+
+    /// 勾形横向端点跨度（20 画布内 0.2→0.8）：`[源]` `Checkbox.kt:496-514` 的路径比例。
+    ///
+    /// 这是 research/15 §25 明确允许的「组件级常量」（路径比例 0.2/0.4/0.5/0.7/0.8 不进令牌层）。
+    /// 只在取证/测试里用（生产路径由 `shell::glyph` 直接按比例构路径）。
+    #[cfg(test)]
+    pub fn check_span(&self) -> f32 {
+        self.side * (0.8 - 0.2)
+    }
+
+    /// 方头（`StrokeCap.Square`）渲染后墨迹相对端点跨度的**外扩量**：两侧各 `1/√2 × 线宽`。
+    ///
+    /// 只用于把「参考值 12 是端点跨度、实测是墨迹跨度」这件事写进断言：勾的两端是 45° 斜线，
+    /// 方头沿斜向外扩，投影到 x 轴正好是 `stroke / √2`（每端）。`#[cfg(test)]`：同 `check_span`。
+    #[cfg(test)]
+    pub fn square_cap_bleed(&self) -> f32 {
+        self.stroke * std::f32::consts::FRAC_1_SQRT_2
+    }
+}
+
+/// Switch 的几何（`research/12b` §10；数值标 **G16** 的部分令牌层暂无档位）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct SwitchGeometry {
+    /// 轨道宽（52）。
+    pub track_width: f32,
+    /// 轨道高（32 = `Space::X8`）。
+    pub track_height: f32,
+    /// 轨道描边（2，仅未选中态画）。
+    pub track_stroke: f32,
+    /// 滑块：选中 / 未选中 / 按下三档（24 / 16 / 28）。
+    pub thumb_selected: f32,
+    /// 未选中滑块（16）。
+    pub thumb_unselected: f32,
+    /// 按下滑块（28）。
+    pub thumb_pressed: f32,
+    /// 滑块内图标（16 = `IconSize::SwitchThumb`；AAR `SwitchTokens.SelectedIconSize /
+    /// UnselectedIconSize = 16.0d`。**不是按钮的 18**）。
+    pub icon: f32,
+    /// 状态层直径（40）。
+    pub state_layer: f32,
+    /// 最小命中区（48）。
+    pub hit: f32,
+}
+
+impl SwitchGeometry {
+    /// 从令牌 + G16 常量求值。
+    pub fn of(ui: &Ui) -> Self {
+        Self {
+            track_width: SWITCH_TRACK_WIDTH,
+            track_height: ui.space(Space::X8),
+            track_stroke: SWITCH_TRACK_STROKE,
+            thumb_selected: SWITCH_THUMB_SELECTED,
+            thumb_unselected: SWITCH_THUMB_UNSELECTED,
+            thumb_pressed: SWITCH_THUMB_PRESSED,
+            icon: IconSize::SwitchThumb.px(),
+            state_layer: SWITCH_STATE_LAYER,
+            hit: ui.metrics().touch_target,
+        }
+    }
+
+    /// 滑块直径：按下态胀到 28，其余按选中与否取 24 / 16（§10.2）。
+    pub fn thumb(&self, selected: bool, pressed: bool) -> f32 {
+        if pressed {
+            self.thumb_pressed
+        } else if selected {
+            self.thumb_selected
+        } else {
+            self.thumb_unselected
+        }
+    }
+
+    /// 滑块离轨道边的内距 = `(轨道高 − 滑块) / 2`（三个档位都成立：32−24=8→4，32−16=16→8，32−28=4→2）。
+    pub fn thumb_inset(&self, thumb: f32) -> f32 {
+        (self.track_height - thumb) / 2.0
+    }
+
+    /// 状态层相对轨道的横向外扩：状态层比轨道高，未选中时滑块又靠左，
+    /// 所以状态层会**超出轨道左侧**——绘制区因此要多留这一段（见 [`Self::layer_offset`]）。
+    pub fn bleed(&self) -> f32 {
+        (self.state_layer - self.track_height) / 2.0
+    }
+
+    /// 滑块圆心到状态层左缘的距离（= 状态层半径）。
+    pub fn layer_radius(&self) -> f32 {
+        self.state_layer / 2.0
+    }
+
+    /// 滑块圆心离轨道左缘的距离：未选中 = 内距 + 半滑块；选中 = 轨道宽 − 内距 − 半滑块。
+    pub fn thumb_center(&self, selected: bool, thumb: f32) -> f32 {
+        let inset = self.thumb_inset(thumb);
+        if selected {
+            self.track_width - inset - thumb / 2.0
+        } else {
+            inset + thumb / 2.0
+        }
+    }
+
+    /// 状态层左缘相对**绘制区**的位置：绘制区左缘 = 轨道左缘 − [`Self::bleed`]。
+    pub fn layer_offset(&self, selected: bool, thumb: f32) -> f32 {
+        self.thumb_center(selected, thumb) + self.bleed() - self.layer_radius()
+    }
+
+    /// 绘制区宽（轨道 + 两侧各一段状态层外扩）。
+    pub fn draw_width(&self) -> f32 {
+        self.track_width + self.bleed() * 2.0
+    }
+
+    /// 绘制区高（= 状态层直径，轨道在中间垂直居中）。
+    pub fn draw_height(&self) -> f32 {
+        self.state_layer
+    }
+}
+
+/// Chip 的几何（`research/12b` §13）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct ChipGeometry {
+    /// 容器高（32 = `Space::X8`，`AssistChipTokens.ContainerHeight`）。
+    pub height: f32,
+    /// 圆角（8 = `Component::Chip.spec().shape = ShapeScale::Small`）。
+    pub radius: f32,
+    /// 水平内边距（8 = `Space::X2`，`Chip.kt HorizontalElementsPadding`）。
+    pub pad: f32,
+    /// 元素间距（8，同上）。
+    pub gap: f32,
+    /// 图标边长（18 = `IconSize::Button`；AAR `AssistChipTokens.IconSize = 18.0d`，12b 13.4 同值）。
+    pub icon: f32,
+}
+
+impl ChipGeometry {
+    /// 从令牌求值（`shape` 档位来自组件表，半径按边长折算）。
+    pub fn of(ui: &Ui) -> Self {
+        let height = ui.space(Space::X8);
+        let shape = Component::Chip.spec().shape;
+        Self {
+            height,
+            radius: shape.radius_px(height),
+            pad: ui.space(Space::X2),
+            gap: ui.space(Space::X2),
+            icon: IconSize::Button.px(),
+        }
+    }
+}
+
+/// 组件表里的微度量；缺组 = 令牌层还没建这一档（G16 的判据）。
+fn metrics(component: Component) -> ComponentMetrics {
+    component
+        .metrics()
+        .unwrap_or_else(|| panic!("{component:?} 缺 ComponentMetrics（G10 的消费入口）"))
+}
diff --git a/crates/app-iced/src/components/selection/matrix.rs b/crates/app-iced/src/components/selection/matrix.rs
new file mode 100644
index 0000000..5f44807
--- /dev/null
+++ b/crates/app-iced/src/components/selection/matrix.rs
@@ -0,0 +1,211 @@
+//! 选择类家族的**状态矩阵**（D30：浅/深 × 五态）：12 行 × 5 列。
+//!
+//! ```text
+//!                        | enabled | hovered | pressed | focused | disabled |
+//!   checkbox·off/on/indet/error · radio·off/on · switch·off/on
+//!   chip·assist / chip·filter / chip·filter·on / chip·input
+//! ```
+//!
+//! 每格都**强制**成该态（`Checkbox::state(..)` 等取证开关）：截图时不能让 60 个控件同时 hover，
+//! 而强制值只影响「画什么」，不动任何状态机——所以矩阵图里的五态与运行期五态逐像素同源。
+//!
+//! 为什么住在 `selection/` 而不是 `gallery/`：`gallery/<family>.rs` 只负责「怎么摆」，本文件负责
+//! 「摆什么」，混在一起会顶到 400 行红线（像素断言在 `gallery/selection.rs`）。消息类型是 `()`
+//! （矩阵只供视觉验收，点击不产生业务效果），由 gallery 侧一次 `.map(..)` 接成 `DemoMessage`。
+
+use iced::widget::{column, container, row, text};
+use iced::{Element, Length};
+
+use unlucky_design::color::Role;
+use unlucky_design::icons::IconKind;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use crate::theme::Ui;
+
+use super::super::gallery::{cell_width, heading, row_label, state_cells};
+use super::super::interaction::Interaction;
+use super::{self as selection, CheckValue, Checkbox, Chip, ChipVariant, Radio, Switch};
+
+/// 整段矩阵（列头 + 12 行）；消息类型是 `()`。
+pub fn matrix<'a>(ui: &'a Ui) -> Element<'a, ()> {
+    let mut rows = column![header_row(ui)].spacing(ui.space(Space::X1));
+    for spec in Row::ALL {
+        let cells = Interaction::ALL
+            .iter()
+            .map(|state| cell(ui, draw(ui, spec, *state)))
+            .collect::<Vec<_>>();
+
+        rows = rows.push(
+            row![
+                row_label(ui, spec.name()).map(|_| ()),
+                row(cells).spacing(ui.space(Space::X2))
+            ]
+            .spacing(ui.space(Space::X2)),
+        );
+    }
+
+    rows.into()
+}
+
+/// 家族小节的标题 + 判据说明（与矩阵分开，好让 gallery 侧决定顺序）。
+pub fn heading_and_note<'a>(ui: &'a Ui) -> Element<'a, ()> {
+    heading(
+        ui,
+        "selection · checkbox / radio / switch / chip",
+        "15 §18/§19 + 12b §10/§13：checkbox 20×20 圆角 2 描边 2（向内收）勾 12 方头 · \
+         radio 外圈 20 环线 2 内点 10 · switch 轨道 52×32 滑块 24/16 · chip 高 32 圆角 8 · \
+         Ø40 状态层 · 命中 48",
+    )
+    .map(|_| ())
+}
+
+/// 图例（一行说明五态口径）。
+pub fn legend<'a>(ui: &'a Ui) -> Element<'a, ()> {
+    let style = ui.style(TypeRole::BodySmall);
+    text(
+        "图例：列 = 五态（focus 与 pressed 同 α 10%，看起来一样是规范要求）；行 = 组件×取值。\
+         复选框第三行是 indeterminate（勾形变成居中短横，不换图标）；第四行是错误态。",
+    )
+    .size(style.size_px)
+    .font(ui.font_of(style))
+    .color(ui.color(Role::OnSurfaceVariant))
+    .into()
+}
+
+/// 矩阵的一行（组件 × 取值）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum Row {
+    /// 三态复选框；布尔位 = 错误态。
+    Checkbox(CheckValue, bool),
+    /// 单选框；布尔位 = 选中。
+    Radio(bool),
+    /// 开关；布尔位 = 打开。
+    Switch(bool),
+    /// Chip；`(类, 选中)`。
+    Chip(ChipVariant, bool),
+}
+
+impl Row {
+    /// 行序（矩阵自上而下）。
+    const ALL: [Row; 12] = [
+        Row::Checkbox(CheckValue::Unchecked, false),
+        Row::Checkbox(CheckValue::Checked, false),
+        Row::Checkbox(CheckValue::Indeterminate, false),
+        Row::Checkbox(CheckValue::Unchecked, true),
+        Row::Radio(false),
+        Row::Radio(true),
+        Row::Switch(false),
+        Row::Switch(true),
+        Row::Chip(ChipVariant::Assist, false),
+        Row::Chip(ChipVariant::Filter, false),
+        Row::Chip(ChipVariant::Filter, true),
+        Row::Chip(ChipVariant::Input, false),
+    ];
+
+    /// 左栏标签。
+    fn name(self) -> &'static str {
+        match self {
+            Row::Checkbox(CheckValue::Unchecked, false) => "checkbox·off",
+            Row::Checkbox(CheckValue::Checked, false) => "checkbox·on",
+            Row::Checkbox(CheckValue::Indeterminate, false) => "checkbox·indet",
+            Row::Checkbox(..) => "checkbox·error",
+            Row::Radio(false) => "radio·off",
+            Row::Radio(true) => "radio·on",
+            Row::Switch(false) => "switch·off",
+            Row::Switch(true) => "switch·on",
+            Row::Chip(ChipVariant::Assist, _) => "chip·assist",
+            Row::Chip(ChipVariant::Filter, false) => "chip·filter",
+            Row::Chip(ChipVariant::Filter, true) => "chip·filter·on",
+            Row::Chip(..) => "chip·input",
+        }
+    }
+}
+
+/// 一格的组件（强制成 `state`）。
+fn draw(ui: &Ui, spec: Row, state: Interaction) -> Element<'_, ()> {
+    let disabled = state.is_disabled();
+
+    match spec {
+        // 五态共用同一套装配：只有「有没有消息」随禁用变（语义上的禁用，不是画成禁用）
+        Row::Checkbox(value, error) => {
+            let mut checkbox = match (disabled, value) {
+                (true, value) => Checkbox::disabled("", value),
+                (false, CheckValue::Indeterminate) => Checkbox::tri("", value, ()),
+                (false, CheckValue::Checked) => Checkbox::new("", true, ()),
+                (false, CheckValue::Unchecked) => Checkbox::new("", false, ()),
+            }
+            .state(state);
+            if error {
+                checkbox = checkbox.error();
+            }
+            selection::checkbox(ui, checkbox)
+        }
+        Row::Radio(selected) => {
+            let radio = if disabled {
+                Radio::disabled("", selected)
+            } else {
+                Radio::new("", selected, ())
+            };
+            selection::radio(ui, radio.state(state))
+        }
+        Row::Switch(value) => {
+            let switch = if disabled {
+                Switch::disabled("", value)
+            } else {
+                Switch::new("", value, ())
+            };
+            selection::switch(ui, switch.state(state))
+        }
+        Row::Chip(variant, selected) => {
+            let label = match variant {
+                ChipVariant::Assist => "Assist",
+                ChipVariant::Filter => "Filter",
+                ChipVariant::Input => "Input",
+            };
+            // 禁用**只清消息**（`Chip::disabled()` 是修饰器）：图标与选中态必须保留，
+            // 否则禁用列里 `filter·on` 与 `filter` 会逐像素同形（复审 P2-1）。
+            let chip = match variant {
+                ChipVariant::Assist => Chip::assist(label, ()).leading(IconKind::Download),
+                // Filter 的勾只在**选中**时给（选中态才需要「已筛选」的强提示）
+                ChipVariant::Filter if selected => {
+                    Chip::filter(label, true, ()).leading(IconKind::Check)
+                }
+                ChipVariant::Filter => Chip::filter(label, false, ()).leading(IconKind::Filter),
+                // Input chip：前置图标 + 后置关闭键（avatar 位用图标代替）
+                ChipVariant::Input => Chip::input(label, ())
+                    .leading(IconKind::Folder)
+                    .trailing(IconKind::Close),
+            };
+            let chip = if disabled { chip.disabled() } else { chip };
+            selection::chip(ui, chip.state(state))
+        }
+    }
+}
+
+/// 列头（五态名）。
+fn header_row(ui: &Ui) -> Element<'_, ()> {
+    let style = ui.style(TypeRole::LabelSmall);
+    let mut head = row![row_label(ui, "").map(|_| ())].spacing(ui.space(Space::X2));
+
+    for (name, width) in state_cells(ui) {
+        head = head.push(
+            container(
+                text(name)
+                    .size(style.size_px)
+                    .font(ui.font_of(style))
+                    .color(ui.color(Role::OnSurfaceVariant)),
+            )
+            .width(Length::Fixed(width)),
+        );
+    }
+
+    head.into()
+}
+
+/// 一个矩阵单元格（固定宽，内容左对齐）。
+fn cell<'a>(ui: &Ui, content: Element<'a, ()>) -> Element<'a, ()> {
+    container(content)
+        .width(Length::Fixed(cell_width(ui)))
+        .into()
+}
diff --git a/crates/app-iced/src/components/selection/mod.rs b/crates/app-iced/src/components/selection/mod.rs
new file mode 100644
index 0000000..c6c15cc
--- /dev/null
+++ b/crates/app-iced/src/components/selection/mod.rs
@@ -0,0 +1,50 @@
+//! **选择类家族**（D39 §1 的 ownership 切片）：Checkbox / Radio / Switch / Chip。
+//!
+//! | 组件 | 参考章节 | 尺寸一句话 |
+//! |---|---|---|
+//! | [`Checkbox`] | `research/15` §18 | 20×20 / 圆角 2 / 描边 2（向内收）/ 勾 12dp 方头 / Ø40 状态层 / 命中 48 |
+//! | [`Radio`] | `research/15` §19 | 外圈 20 / 环线 2 / 内点 **10**（不是 12）/ Ø40 状态层 |
+//! | [`Switch`] | `research/12b` §10 | 轨道 52×32 / 滑块 24·16 / Ø40 状态层 |
+//! | [`Chip`] | `research/12b` §13 | 高 32 / 圆角 8 / 内边距 8 / Assist·Filter·Input |
+//!
+//! ## 分层（照抄按钮家族，审起来只需看四处）
+//!
+//! ```text
+//! geometry.rs  令牌 → 像素（唯一把 ComponentMetrics / Space / ShapeScale 读成数字的地方）
+//! paint.rs     Interaction × 选中 × 错误 → 角色 → 颜色（唯一写角色名的地方）
+//! shell.rs     button 四态 → 内部自绘样式的帧内通道 + 勾形 SVG
+//! <component>.rs  布局与装配（一行一个 Element）
+//! ```
+//!
+//! ## 纪律（D39 契约 §2 / §3）
+//!
+//! - 全部组件**对消息类型泛型**（`M: Clone`），不 import `crate::app::Message`；
+//! - hover / pressed / focus / disabled 的 α 只从 [`super::interaction`] 取（本目录零 α 字面量）；
+//! - 精确尺寸只从 [`super::layout`]（`centered_fixed` / `fixed`）与 `geometry` 取，不许手写；
+//! - 图标一律 `icons::view_at(kind, color, geometry.icon)` + 固定尺寸容器（Q9）：本目录的盒是
+//!   **18（chip）与 16（switch 滑块）**，都不是 `icons::RENDER_PX`(24)，所以必须按盒烘焙——用
+//!   `icons::view`（24 烘焙）会被布局缩到 1.1px 视觉线宽（复审 r1 P2-2）。圆角按 D32 分层
+//!   （微控件 2 / 容器刻度 / full）。
+
+mod checkbox;
+mod chip;
+mod radio;
+mod shell;
+mod switch;
+
+pub mod geometry;
+pub mod matrix;
+pub mod paint;
+
+#[cfg(test)]
+mod pixel;
+#[cfg(test)]
+mod probe;
+#[cfg(test)]
+mod tests;
+
+pub use checkbox::{checkbox, CheckValue, Checkbox};
+pub use chip::{chip, Chip};
+pub use paint::ChipVariant;
+pub use radio::{radio, Radio};
+pub use switch::{switch, Switch};
diff --git a/crates/app-iced/src/components/selection/paint/check.rs b/crates/app-iced/src/components/selection/paint/check.rs
new file mode 100644
index 0000000..6fdab48
--- /dev/null
+++ b/crates/app-iced/src/components/selection/paint/check.rs
@@ -0,0 +1,88 @@
+//! Checkbox 的角色映射（`research/15` §18.2 / §18.7 / §18.8）。
+
+use unlucky_design::color::Role;
+
+use crate::theme::Ui;
+
+use super::super::super::interaction::Interaction;
+use super::{disabled_ink, lifted, CheckboxPaint, Frame};
+
+/// Checkbox 的外观。
+///
+/// **描边宽度恒 2**（禁用态也是 2，§18.8：禁用不是「变淡变细」）；
+/// 选中态没有描边（`SelectedOutlineWidth = 0`，走填充分支）。
+pub fn checkbox(
+    ui: &Ui,
+    selected: bool,
+    error: bool,
+    state: Interaction,
+    radius: f32,
+    stroke: f32,
+) -> CheckboxPaint {
+    if state.is_disabled() {
+        return CheckboxPaint {
+            frame: Frame {
+                // A1：`SelectedDisabledContainerColor = OnSurface` +
+                // `SelectedDisabledContainerOpacity = 0.38` —— **不是** 12%（复审 P2-3）。
+                // 与未选中禁用的描边是同一个 38% 叠色，两格看起来才成对。
+                fill: selected.then(|| disabled_ink(ui, Role::OnSurface)),
+                outline: (!selected).then(|| disabled_ink(ui, Role::OnSurface)),
+                stroke,
+                radius,
+            },
+            // `SelectedDisabledIconColor = Surface`：勾是「透出底色」的浅色
+            glyph: ui.color(Role::Surface),
+        };
+    }
+
+    match (selected, error) {
+        (true, false) => CheckboxPaint {
+            frame: Frame {
+                fill: Some(ui.color(Role::Primary)),
+                outline: None,
+                stroke: 0.0,
+                radius,
+            },
+            glyph: ui.color(Role::OnPrimary),
+        },
+        (true, true) => CheckboxPaint {
+            frame: Frame {
+                fill: Some(ui.color(Role::Error)),
+                outline: None,
+                stroke: 0.0,
+                radius,
+            },
+            glyph: ui.color(Role::OnError),
+        },
+        (false, error) => {
+            let role = if error {
+                Role::Error
+            } else if lifted(state) {
+                // `UnselectedHover/Focus/PressedOutlineColor = OnSurface`（A1；不是 OnSurfaceVariant）
+                Role::OnSurface
+            } else {
+                Role::OnSurfaceVariant
+            };
+            CheckboxPaint {
+                frame: Frame {
+                    fill: None,
+                    outline: Some(ui.color(role)),
+                    stroke,
+                    radius,
+                },
+                glyph: ui.color(role),
+            }
+        }
+    }
+}
+
+/// Checkbox 状态层的 content 角色（选中/部分选中 = `Primary`，错误 = `Error`，否则 `OnSurfaceVariant`）。
+///
+/// 出处：Compose 的 ripple 色就是 `selectedContainerColor` / `unselectedOutlineColor`。
+pub fn checkbox_layer_role(filled: bool, error: bool) -> Role {
+    match (filled, error) {
+        (true, false) => Role::Primary,
+        (true, true) | (false, true) => Role::Error,
+        (false, false) => Role::OnSurfaceVariant,
+    }
+}
diff --git a/crates/app-iced/src/components/selection/paint/chip.rs b/crates/app-iced/src/components/selection/paint/chip.rs
new file mode 100644
index 0000000..3277f33
--- /dev/null
+++ b/crates/app-iced/src/components/selection/paint/chip.rs
@@ -0,0 +1,79 @@
+//! Chip 的角色映射（`research/12b` §13.5 / §13.6 / §13.7）。
+
+use unlucky_design::color::Role;
+
+use crate::theme::{Ui, STROKE_PX};
+
+use super::super::super::interaction::Interaction;
+use super::{disabled_container, disabled_ink, state_layer, ChipPaint, Frame};
+
+/// Chip 的三种（§13.6 / §13.7）：Assist / Filter / Input。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ChipVariant {
+    /// Assist：**永远未选中**，前置图标 `Primary`（`AssistChipTokens.IconColor`）。
+    Assist,
+    /// Filter：可选中（`SecondaryContainer`），选中态无描边。
+    Filter,
+    /// Input：可选中 + 后置关闭图标。
+    Input,
+}
+
+/// Chip 的外观。
+///
+/// 与 Checkbox/Radio 的区别：Chip 的**状态层就是它自己的容器**（M3 的 chip 没有圆形状态层），
+/// 所以未选中 + hover 的 fill 是「状态层叠在 surface 上」的实色。
+pub fn chip(
+    ui: &Ui,
+    variant: ChipVariant,
+    selected: bool,
+    state: Interaction,
+    radius: f32,
+) -> ChipPaint {
+    let selected = selected && !matches!(variant, ChipVariant::Assist);
+    let label_role = if selected {
+        Role::OnSecondaryContainer
+    } else if matches!(variant, ChipVariant::Assist) {
+        Role::OnSurface
+    } else {
+        Role::OnSurfaceVariant
+    };
+
+    if state.is_disabled() {
+        let ink = disabled_ink(ui, Role::OnSurface);
+        return ChipPaint {
+            frame: Frame {
+                fill: selected.then(|| disabled_container(ui)),
+                outline: (!selected).then(|| disabled_container(ui)),
+                stroke: STROKE_PX,
+                radius,
+            },
+            label: ink,
+            icon: ink,
+        };
+    }
+
+    let outline = (!selected).then(|| ui.color(Role::OutlineVariant));
+    let fill = if selected {
+        Some(ui.color(Role::SecondaryContainer))
+    } else {
+        state_layer(ui, state, label_role)
+    };
+    // Assist / 选中态的前置图标是 `Primary`（`AssistChipTokens.IconColor` /
+    // `InputChipTokens.SelectedLeadingIconColor`）；其余跟文字同色。
+    let icon_role = if matches!(variant, ChipVariant::Assist) || selected {
+        Role::Primary
+    } else {
+        label_role
+    };
+
+    ChipPaint {
+        frame: Frame {
+            fill,
+            outline,
+            stroke: STROKE_PX,
+            radius,
+        },
+        label: ui.color(label_role),
+        icon: ui.color(icon_role),
+    }
+}
diff --git a/crates/app-iced/src/components/selection/paint/mod.rs b/crates/app-iced/src/components/selection/paint/mod.rs
new file mode 100644
index 0000000..b52e4ee
--- /dev/null
+++ b/crates/app-iced/src/components/selection/paint/mod.rs
@@ -0,0 +1,149 @@
+//! 选择类家族的**角色映射**：`Interaction × 选中 × 错误 → 颜色`（公共件 + 各组件分文件）。
+//!
+//! ## 出处（全部 A1：`material3-android:1.4.0` 的 token 类，本机 AAR `javap` 复核，见报告）
+//!
+//! | 组件 | 静息 | hover / focus / pressed | 禁用 |
+//! |---|---|---|---|
+//! | Checkbox 未选中 | 描边 `OnSurfaceVariant` 2px | 描边提到 **`OnSurface`**（宽度仍 2） | 描边 `OnSurface`@38% |
+//! | Checkbox 选中 | 填 `Primary` + 勾 `OnPrimary` | 填 `Primary`（不变） | 填 `OnSurface`@38% + 勾 `Surface` |
+//! | Radio | 环 `OnSurfaceVariant` / 选中环+点 `Primary` | 未选中环提到 **`OnSurface`**；**选中态仍是 `Primary`** | 环+点 `OnSurface`@38% |
+//! | Switch | 轨 `Primary`（选中）/`SurfaceContainerHighest`+2px `Outline`；滑块 `OnPrimary`/`Outline` | 滑块 `PrimaryContainer`/`OnSurfaceVariant` | 轨 `OnSurface`@12%；滑块 `Surface`/@38% |
+//! | Chip | 未选中：透明+1px `OutlineVariant`，文字 `OnSurfaceVariant`；选中：`SecondaryContainer` **无描边** | 描边不变，状态层成为底色 | 描边 `OnSurface`@12%；文字/图标 @38% |
+//!
+//! **A1 改过参考表的三处**：`UnselectedHover/Focus/PressedOutlineColor` 与 Radio 的
+//! `UnselectedHover/Focus/PressedIconColor` 都是 `OnSurface`（不是 `OnSurfaceVariant`）；
+//! `SelectedDisabledIconColor` 是 `Surface`。α 一律从 [`interaction`] 取。
+//!
+//! ## 为什么拆成目录（复审 P2-5）
+//!
+//! 原来一个文件正好 400 行、零余量：再加一个态就得动它。按组件拆成
+//! `check.rs` / `radio.rs` / `switch.rs` / `chip.rs`，公共件（[`Frame`]、状态层、禁用色）留在本文件，
+//! **对外 API 一字不改**（`selection::paint::*` 的路径全部保持）。
+
+use iced::widget::container;
+use iced::{Background, Border, Color};
+
+use unlucky_design::color::Role;
+
+use crate::theme::Ui;
+
+use super::super::interaction::{self, Interaction};
+
+mod check;
+mod chip;
+mod radio;
+mod switch;
+
+pub use check::{checkbox, checkbox_layer_role};
+pub use chip::{chip, ChipVariant};
+pub use radio::{radio, radio_layer_role};
+pub use switch::{switch, switch_layer};
+
+/// 一个「方框」的外观：填色 / 描边 / 线宽 / 半径。
+///
+/// Checkbox 的框、Radio 的环、Switch 的轨道、Chip 的容器都用它——差别只在颜色与线宽。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Frame {
+    /// 填充色；`None` = 透明（未选中的 Checkbox / Radio 外圈、Chip 的 flat 底）。
+    pub fill: Option<Color>,
+    /// 描边色；`None` = 不画描边。
+    pub outline: Option<Color>,
+    /// 描边宽度（Checkbox/Radio 2，Chip 1，Switch 未选中 2）。
+    pub stroke: f32,
+    /// 圆角半径（Checkbox 2 / Radio 10 / Switch 16 / Chip 8）。
+    pub radius: f32,
+}
+
+impl Frame {
+    /// 翻成 iced 的 `container::Style`（唯一把 Frame 变成像素的地方）。
+    pub fn container_style(self) -> container::Style {
+        container::Style {
+            background: self.fill.map(Background::Color),
+            border: Border {
+                color: self.outline.unwrap_or(Color::TRANSPARENT),
+                width: self.outline.map_or(0.0, |_| self.stroke),
+                radius: iced::border::Radius::new(self.radius),
+            },
+            ..container::Style::default()
+        }
+    }
+}
+
+/// Checkbox 的外观：框 + 勾的颜色。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct CheckboxPaint {
+    /// 框（20×20）。
+    pub frame: Frame,
+    /// 勾 / 短横。
+    pub glyph: Color,
+}
+
+/// Radio 的外观：环 + 内点。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct RadioPaint {
+    /// 外圈（20×20，环线向内收 → 外缘恒 20）。
+    pub ring: Frame,
+    /// 内点（Ø10）；`None` = 未选中（不画点）。
+    pub dot: Option<Color>,
+}
+
+/// Switch 的外观：轨道 + 滑块 + 滑块内图标。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct SwitchPaint {
+    /// 轨道（52×32）。
+    pub track: Frame,
+    /// 滑块。
+    pub thumb: Color,
+    /// 滑块内图标（16）；`None` = 不画（未选中时官方色与轨道同色，画了也看不见）。
+    pub icon: Option<Color>,
+}
+
+/// Chip 的外观：容器 + 文字/图标。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct ChipPaint {
+    /// 容器。
+    pub frame: Frame,
+    /// 文字。
+    pub label: Color,
+    /// 前/后置图标。
+    pub icon: Color,
+}
+
+/// 状态层颜色：`content` 角色 @ 该态的 α 叠在 `surface` 上（不透明；α 的唯一实现点是
+/// [`interaction::overlay_color`]，本目录零 α 字面量）。
+pub fn state_layer(ui: &Ui, state: Interaction, content: Role) -> Option<Color> {
+    interaction::overlay_color(ui, state, content, Role::Surface)
+}
+
+/// `OnSurface`@12% 叠 surface（**容器**禁用色：Switch 轨道、Chip 未选中描边）。
+///
+/// 注意：Checkbox「选中且禁用」的**填充**不是这个 12%，A1 的
+/// `SelectedDisabledContainerOpacity = 0.38` → 见 [`disabled_ink`]（复审 P2-3）。
+pub(super) fn disabled_container(ui: &Ui) -> Color {
+    interaction::disabled_colors(ui, Role::Surface).0
+}
+
+/// 内容禁用色：`role` @38% 叠在 surface 上（`on_container = false`）。
+pub(super) fn disabled_ink(ui: &Ui, role: Role) -> Color {
+    interaction::disabled_content_over_role(ui, role, false)
+}
+
+/// hover / focus / pressed（「抬起来」的三态）。
+pub(super) fn lifted(state: Interaction) -> bool {
+    matches!(
+        state,
+        Interaction::Hovered | Interaction::Focused | Interaction::Pressed
+    )
+}
+
+/// 控件旁的标签色：`OnSurface`；禁用 → `OnSurface`@38%。
+///
+/// A1 里 checkbox/radio 都没有「标签色随 hover 变」的字段（标签不属于控件本体），
+/// 所以这里只看禁用与否。
+pub fn label(ui: &Ui, state: Interaction) -> Color {
+    if state.is_disabled() {
+        disabled_ink(ui, Role::OnSurface)
+    } else {
+        ui.color(Role::OnSurface)
+    }
+}
diff --git a/crates/app-iced/src/components/selection/paint/radio.rs b/crates/app-iced/src/components/selection/paint/radio.rs
new file mode 100644
index 0000000..7d09072
--- /dev/null
+++ b/crates/app-iced/src/components/selection/paint/radio.rs
@@ -0,0 +1,42 @@
+//! Radio 的角色映射（`research/15` §19.3 / §19.4 / §19.5）。
+
+use unlucky_design::color::Role;
+
+use crate::theme::Ui;
+
+use super::super::super::interaction::Interaction;
+use super::{disabled_ink, lifted, Frame, RadioPaint};
+
+/// Radio 的外观。
+///
+/// **选中态 hover 不换色**：环与点在四态里都是 `Primary`（只有状态层变）。
+pub fn radio(ui: &Ui, selected: bool, state: Interaction, radius: f32, stroke: f32) -> RadioPaint {
+    let ink = if state.is_disabled() {
+        disabled_ink(ui, Role::OnSurface)
+    } else if selected {
+        ui.color(Role::Primary)
+    } else if lifted(state) {
+        ui.color(Role::OnSurface)
+    } else {
+        ui.color(Role::OnSurfaceVariant)
+    };
+
+    RadioPaint {
+        ring: Frame {
+            fill: None,
+            outline: Some(ink),
+            stroke,
+            radius,
+        },
+        dot: selected.then_some(ink),
+    }
+}
+
+/// Radio 状态层的 content 角色（选中 = `Primary`，未选中 = `OnSurfaceVariant`）。
+pub fn radio_layer_role(selected: bool) -> Role {
+    if selected {
+        Role::Primary
+    } else {
+        Role::OnSurfaceVariant
+    }
+}
diff --git a/crates/app-iced/src/components/selection/paint/switch.rs b/crates/app-iced/src/components/selection/paint/switch.rs
new file mode 100644
index 0000000..d4b2520
--- /dev/null
+++ b/crates/app-iced/src/components/selection/paint/switch.rs
@@ -0,0 +1,102 @@
+//! Switch 的角色映射（`research/12b` §10.3 / §10.4 / §10.6 / §10.7）。
+
+use iced::Color;
+
+use unlucky_design::color::Role;
+use unlucky_design::shape::ShapeScale;
+
+use crate::theme::Ui;
+
+use super::super::super::interaction::{self, Interaction};
+use super::super::geometry::SwitchGeometry;
+use super::{disabled_container, disabled_ink, lifted, Frame, SwitchPaint};
+
+/// Switch 的外观。
+pub fn switch(ui: &Ui, selected: bool, state: Interaction) -> SwitchPaint {
+    let geometry = SwitchGeometry::of(ui);
+    let radius = ShapeScale::Full.radius_px(geometry.track_height);
+
+    if state.is_disabled() {
+        let container = disabled_container(ui);
+        return if selected {
+            SwitchPaint {
+                track: Frame {
+                    fill: Some(container),
+                    outline: None,
+                    stroke: 0.0,
+                    radius,
+                },
+                // `DisabledSelectedHandleColor = Surface` 且不透明度 1（A1 的 fconst_1）
+                thumb: ui.color(Role::Surface),
+                icon: Some(disabled_ink(ui, Role::OnSurface)),
+            }
+        } else {
+            SwitchPaint {
+                track: Frame {
+                    fill: Some(ui.color(Role::SurfaceContainerHighest)),
+                    outline: Some(container),
+                    stroke: geometry.track_stroke,
+                    radius,
+                },
+                thumb: disabled_ink(ui, Role::OnSurface),
+                icon: None,
+            }
+        };
+    }
+
+    if selected {
+        SwitchPaint {
+            track: Frame {
+                fill: Some(ui.color(Role::Primary)),
+                outline: None,
+                stroke: 0.0,
+                radius,
+            },
+            // `SelectedHover/Focus/PressedHandleColor = PrimaryContainer`（A1，1.4.0 起）
+            thumb: if lifted(state) {
+                ui.color(Role::PrimaryContainer)
+            } else {
+                ui.color(Role::OnPrimary)
+            },
+            icon: Some(ui.color(Role::OnPrimaryContainer)),
+        }
+    } else {
+        SwitchPaint {
+            track: Frame {
+                fill: Some(ui.color(Role::SurfaceContainerHighest)),
+                outline: Some(ui.color(Role::Outline)),
+                stroke: geometry.track_stroke,
+                radius,
+            },
+            // `UnselectedHover/Focus/PressedHandleColor = OnSurfaceVariant`（A1）
+            thumb: if lifted(state) {
+                ui.color(Role::OnSurfaceVariant)
+            } else {
+                ui.color(Role::Outline)
+            },
+            icon: None,
+        }
+    }
+}
+
+/// 状态层的 content 角色（选中 = 滑块色 `OnPrimary`，未选中 = `Outline`）。
+pub fn switch_layer_role(selected: bool) -> Role {
+    if selected {
+        Role::OnPrimary
+    } else {
+        Role::Outline
+    }
+}
+
+/// Switch 状态层的颜色：**叠在轨道色上**，不是叠在 surface 上。
+///
+/// switch 的状态层圆（Ø40）有一大半压在轨道（52×32）上：若照别的控件那样叠 surface，
+/// 圆会在轨道里画出一块「更亮的补丁」（实测第一版就是这个样子，轨道像被啃掉一块）。
+pub fn switch_layer(ui: &Ui, state: Interaction, selected: bool) -> Option<Color> {
+    let track = if selected {
+        Role::Primary
+    } else {
+        Role::SurfaceContainerHighest
+    };
+    interaction::overlay_color(ui, state, switch_layer_role(selected), track)
+}
diff --git a/crates/app-iced/src/components/selection/pixel.rs b/crates/app-iced/src/components/selection/pixel.rs
new file mode 100644
index 0000000..d5528ab
--- /dev/null
+++ b/crates/app-iced/src/components/selection/pixel.rs
@@ -0,0 +1,205 @@
+//! 像素取证的小工具（**仅测试**）：读 PNG、按「底色→墨色混色线」找连通块、量内缩墨迹。
+//!
+//! 为什么不去用 `gallery/scan.rs`：它的可见性是 `pub(in crate::app::components::gallery)`，
+//! 跨目录拿不到；这里只重写 4 个纯函数（`rgb` / `matches` / 像素访问 / 外接框），其余判据
+//! （[`on_ramp`] / [`ink_boxes`] / [`inner_ink`]）是一次性的测量逻辑，本来就只服务本家族。
+
+use std::path::PathBuf;
+
+use iced::Color;
+
+/// 8bit RGB。
+pub(super) fn rgb(color: Color) -> [u8; 3] {
+    [
+        (color.r * 255.0).round() as u8,
+        (color.g * 255.0).round() as u8,
+        (color.b * 255.0).round() as u8,
+    ]
+}
+
+/// 容差比较（抗锯齿/取整）。
+pub(super) fn matches(pixel: [u8; 3], expected: [u8; 3]) -> bool {
+    pixel.iter().zip(expected).all(|(a, b)| a.abs_diff(b) <= 10)
+}
+
+/// `ULL_GALLERY_SHOT` → 截图路径（相对路径按工作区根解释）。
+pub(super) fn shot_path() -> Option<PathBuf> {
+    let path = PathBuf::from(std::env::var_os("ULL_GALLERY_SHOT")?);
+    if path.is_absolute() || path.exists() {
+        return Some(path);
+    }
+    let root = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../..");
+    Some(root.join(path))
+}
+
+/// 一张图的像素访问器（只做本家族需要的事）。
+pub(super) struct Shot {
+    pub(super) width: usize,
+    pub(super) height: usize,
+    pixels: Vec<[u8; 3]>,
+}
+
+impl Shot {
+    pub(super) fn load(path: &std::path::Path) -> Result<Self, String> {
+        let bytes = std::fs::read(path).map_err(|error| format!("读不动 {path:?}：{error}"))?;
+        let image = image::load_from_memory(&bytes)
+            .map_err(|error| format!("解 PNG 失败：{error}"))?
+            .to_rgb8();
+        let (width, height) = (image.width() as usize, image.height() as usize);
+        Ok(Self {
+            width,
+            height,
+            pixels: image.pixels().map(|p| p.0).collect(),
+        })
+    }
+
+    pub(super) fn at(&self, x: usize, y: usize) -> [u8; 3] {
+        self.pixels[y * self.width + x]
+    }
+}
+
+/// 外接框（闭区间）。
+#[derive(Debug, Clone, Copy)]
+pub(super) struct BBox {
+    pub(super) left: usize,
+    pub(super) right: usize,
+    pub(super) top: usize,
+    pub(super) bottom: usize,
+}
+
+impl BBox {
+    pub(super) fn new(x: usize, y: usize) -> Self {
+        Self {
+            left: x,
+            right: x,
+            top: y,
+            bottom: y,
+        }
+    }
+
+    pub(super) fn include(&mut self, x: usize, y: usize) {
+        self.left = self.left.min(x);
+        self.right = self.right.max(x);
+        self.top = self.top.min(y);
+        self.bottom = self.bottom.max(y);
+    }
+
+    pub(super) fn width(&self) -> usize {
+        self.right - self.left + 1
+    }
+
+    pub(super) fn height(&self) -> usize {
+        self.bottom - self.top + 1
+    }
+}
+
+pub(super) fn center(bbox: &BBox) -> (usize, usize) {
+    ((bbox.left + bbox.right) / 2, (bbox.top + bbox.bottom) / 2)
+}
+
+/// 尺寸容差 ±1（rubric §6 的默认容差）：控件常落在半像素上，实测会多一行抗锯齿。
+pub(super) fn near(value: usize, expected: usize) -> bool {
+    value.abs_diff(expected) <= 1
+}
+
+pub(super) fn dims(boxes: &[BBox]) -> String {
+    boxes
+        .iter()
+        .map(|bbox| format!("{}×{}", bbox.width(), bbox.height()))
+        .collect::<Vec<_>>()
+        .join(", ")
+}
+
+/// `pixel` 是否落在 `under → fill` 这条混色线上（覆盖率 ≥50%、偏离线 ≤14）。
+///
+/// 覆盖率 ≥50% 取几何边界（30% 会把半格抗锯齿也算进去，Ø10 量成 12）；
+/// 偏离线 ≤14 把「另一种深色墨」排除（它不在线上，见 [`ink_boxes`] 的坑 2）。
+fn on_ramp(pixel: [u8; 3], fill: [u8; 3], under: [u8; 3]) -> bool {
+    let axis = [0, 1, 2].map(|i| f32::from(fill[i]) - f32::from(under[i]));
+    let offset = [0, 1, 2].map(|i| f32::from(pixel[i]) - f32::from(under[i]));
+    let square: f32 = axis.iter().map(|a| a * a).sum();
+    if square <= f32::EPSILON {
+        return false;
+    }
+    let t: f32 = (0..3).map(|i| axis[i] * offset[i]).sum::<f32>() / square;
+    (0.5..=1.0).contains(&t)
+        && (0..3)
+            .map(|i| (offset[i] - t * axis[i]).powi(2))
+            .sum::<f32>()
+            .sqrt()
+            <= 14.0
+}
+
+/// 「墨迹块」：`fill` 与「底色→fill 的混色」都算墨，按外接框尺寸筛。
+///
+/// 踩过的两个坑：① 按「精确色」连通会把圆形的环切成碎片（每片面积很小，量不到内点）；
+/// ② 按「更接近 fill 还是底色」判会让**另一种深色墨**混进来（`OnSurfaceVariant` 比 `Primary`
+/// 更接近深色，于是未选中的框被当成 20×20 的 Primary 块）。所以判据是「落在混色线上」。
+pub(super) fn ink_boxes(
+    shot: &Shot,
+    color: Color,
+    under: Color,
+    min: usize,
+    max: usize,
+) -> Vec<BBox> {
+    let (fill, base) = (rgb(color), rgb(under));
+    let mut seen = vec![false; shot.width * shot.height];
+    let mut boxes = Vec::new();
+
+    for y in 0..shot.height {
+        for x in 0..shot.width {
+            if seen[y * shot.width + x] || !on_ramp(shot.at(x, y), fill, base) {
+                continue;
+            }
+            let mut stack = vec![(x, y)];
+            seen[y * shot.width + x] = true;
+            let mut bbox = BBox::new(x, y);
+            while let Some((cx, cy)) = stack.pop() {
+                bbox.include(cx, cy);
+                for (nx, ny) in [
+                    (cx + 1, cy),
+                    (cx.saturating_sub(1), cy),
+                    (cx, cy + 1),
+                    (cx, cy.saturating_sub(1)),
+                ] {
+                    let inside = nx < shot.width && ny < shot.height;
+                    if inside && !seen[ny * shot.width + nx] && on_ramp(shot.at(nx, ny), fill, base)
+                    {
+                        seen[ny * shot.width + nx] = true;
+                        stack.push((nx, ny));
+                    }
+                }
+            }
+            if (min..=max).contains(&bbox.width()) && (min..=max).contains(&bbox.height()) {
+                boxes.push(bbox);
+            }
+        }
+    }
+
+    boxes
+}
+
+/// `bbox` 内缩 `inset` 后、落在 **`under → color` 混色线上**的墨迹框（量内点 / 勾形用）。
+///
+/// 内缩 4 而不是 3（描边内缘 AA 正好压在 3 上，会把 Ø10 量成 14）；用混色线而不是精确色
+/// （Ø10 的圆只有 ~8×8 是精确色，边缘 1px 全是抗锯齿）。
+pub(super) fn inner_ink(
+    shot: &Shot,
+    bbox: &BBox,
+    color: Color,
+    under: Color,
+    inset: usize,
+) -> Option<BBox> {
+    let mut ink: Option<BBox> = None;
+    for y in (bbox.top + inset)..=(bbox.bottom - inset) {
+        for x in (bbox.left + inset)..=(bbox.right - inset) {
+            if on_ramp(shot.at(x, y), rgb(color), rgb(under)) {
+                match &mut ink {
+                    Some(found) => found.include(x, y),
+                    None => ink = Some(BBox::new(x, y)),
+                }
+            }
+        }
+    }
+    ink
+}
diff --git a/crates/app-iced/src/components/selection/probe.rs b/crates/app-iced/src/components/selection/probe.rs
new file mode 100644
index 0000000..7a7e697
--- /dev/null
+++ b/crates/app-iced/src/components/selection/probe.rs
@@ -0,0 +1,326 @@
+//! 选择类家族的**渲染层**几何断言：对着真截图量像素（M68 的教训：纯函数对、图可能是错的）。
+//!
+//! 为什么住在 `selection/` 而不是 `gallery/`：`gallery/selection.rs` 只负责「把矩阵摆进 harness」，
+//! 断言加上去会把它顶到 400 行红线。像素扫描的 4 个纯函数在 [`super::pixel`]（同一目录、`cfg(test)`）。
+//!
+//! 量什么（每条对一个具体错误，容差 ±1）：
+//!
+//! - **Checkbox 外缘 20，且选中/未选中同尺寸**（§18.3：描边向内收；向外画会变 22）——逐块断言；
+//! - **Radio 内点 10 不是 12**（§19.2）· 环是真圆、不是圆角方（§19.6）；
+//! - **状态层直径 40 且四角无墨**（§18.5 / §19.7）——**每一块**都查；
+//! - 勾形墨迹 ≈14.8（端点 12 + 方头外扩）· **indeterminate 是短横**（§18.4/§18.6）；
+//! - Switch 轨道**恰好一块** 52×32（§10.1）· Chip **恰好一块** 32 高（§13.1）；
+//! - 禁用：chip 只降不删（P2-1）· 选中禁用的 Checkbox 容器是 38% 不是 12%（P2-3）。
+//!
+//! 复现（worktree 根目录）：
+//!
+//! ```text
+//! cargo build -p unlucky-app-iced --bin unlucky-launcher-iced
+//! ULL_GALLERY_SECTION=selection ./target/debug/unlucky-launcher-iced \
+//!   --software-renderer --screen=gallery \
+//!   --screenshot target/m76/selection-light.png --screenshot-theme=light
+//! ULL_GALLERY_SHOT=target/m76/selection-light.png cargo test -p unlucky-app-iced selection::probe
+//! ```
+
+use unlucky_design::color::{Role, SchemeFlavor};
+use unlucky_design::typography::Platform;
+
+use super::super::interaction::{self, Interaction};
+use super::pixel::{center, dims, ink_boxes, inner_ink, matches, near, rgb, shot_path, Shot};
+use crate::theme::{Families, Ui};
+
+const FAMILIES: Families = Families {
+    text: "Segoe UI",
+    display: "Segoe UI",
+    mono: "Consolas",
+};
+
+fn ui(flavor: SchemeFlavor) -> Ui {
+    Ui::with_platform(flavor, Platform::Windows, FAMILIES)
+}
+
+/// 一条测试覆盖全部几何断言（浅/深各跑一次）。
+#[test]
+fn selection_geometry_matches_the_reference() {
+    let Some(path) = shot_path() else {
+        eprintln!(
+            "[selection-probe] SKIPPED：未设置 ULL_GALLERY_SHOT。这是**渲染层**几何断言，\
+             需要先出图（见本文件模块文档，注意 ULL_GALLERY_SECTION=selection）。"
+        );
+        return;
+    };
+    let shot = Shot::load(&path).expect("读 selection 截图");
+    assert_eq!(
+        (shot.width, shot.height),
+        (1180, 760),
+        "验收图必须 1180×760 @100% DPI"
+    );
+    let light = matches(
+        shot.at(2, 2),
+        rgb(ui(SchemeFlavor::Light).color(Role::Surface)),
+    );
+    let flavor = if light {
+        SchemeFlavor::Light
+    } else {
+        SchemeFlavor::Dark
+    };
+    let ui = ui(flavor);
+    let surface = ui.color(Role::Surface);
+    let primary = ui.color(Role::Primary);
+    let on_primary = ui.color(Role::OnPrimary);
+    let unselected = ui.color(Role::OnSurfaceVariant);
+
+    // ---- §18.1 / §18.3 / §19.1：20 的外缘，选中与未选中**同尺寸** -----------------
+    // 逐块断言（复审 P2-4）：**每一块** Primary 都必须是 20(±1)——任何一块到 22 就说明描边
+    // 画到了框外。只数「20×20 有几块」的时候，「把其中一格放大成 22」照样绿。
+    let filled = ink_boxes(&shot, primary, surface, 15, 24);
+    for bbox in &filled {
+        assert!(
+            bbox.width() <= 21 && bbox.height() <= 21,
+            "18.3：Primary 块不得超过 21（22 = 描边画到框外），实测 {}×{} @ {:?}",
+            bbox.width(),
+            bbox.height(),
+            (bbox.left, bbox.top)
+        );
+    }
+    let twenty: Vec<_> = filled
+        .iter()
+        .copied()
+        .filter(|bbox| near(bbox.width(), 20) && near(bbox.height(), 20))
+        .collect();
+    assert_eq!(
+        twenty.len(),
+        12,
+        "18.1：应**恰好** 12 块 20(±1) 的 Primary（checkbox 选中 4 + 部分选中 4 + radio 环 4），\
+         实际 {}：{}",
+        twenty.len(),
+        dims(&filled)
+    );
+
+    // 未选中（OnSurfaceVariant 描边）：逐块都必须 20(±1)，且内部透底
+    let candidates = ink_boxes(&shot, unselected, surface, 17, 24);
+    let rings: Vec<_> = candidates
+        .iter()
+        .copied()
+        .filter(|bbox| !matches(shot.at(center(bbox).0, bbox.top + 3), rgb(unselected)))
+        .collect();
+    assert!(
+        !rings.is_empty(),
+        "18.2：没找到未选中的复选框；候选：{}",
+        dims(&candidates)
+    );
+    for bbox in &rings {
+        assert!(
+            near(bbox.width(), 20) && near(bbox.height(), 20),
+            "18.3：未选中外缘必须与选中同尺寸 20（描边向内收），实测 {}×{} @ {:?}",
+            bbox.width(),
+            bbox.height(),
+            (bbox.left, bbox.top)
+        );
+        assert!(
+            !matches(shot.at(center(bbox).0, center(bbox).1), rgb(unselected)),
+            "18.2：未选中框内部必须透出底色"
+        );
+    }
+    // A1：hover/pressed/focused 三列的未选中描边提到 `OnSurface`
+    let on_surface = ui.color(Role::OnSurface);
+    let lifted: Vec<_> = ink_boxes(&shot, on_surface, surface, 17, 24)
+        .into_iter()
+        .filter(|bbox| !matches(shot.at(center(bbox).0, bbox.top + 3), rgb(on_surface)))
+        .collect();
+    assert!(
+        lifted.len() >= 3,
+        "A1：未选中复选框在 hover/pressed/focused 的描边应是 OnSurface（3 个），实际 {}",
+        lifted.len()
+    );
+    for bbox in &lifted {
+        assert!(
+            near(bbox.width(), 20) && near(bbox.height(), 20),
+            "18.3：提到 OnSurface 之后外缘仍是 20，实测 {}×{}",
+            bbox.width(),
+            bbox.height()
+        );
+    }
+
+    // ---- §19.2：Radio 内点 **10 不是 12**；§19.6：环是真圆 ------------------------
+    // 环/实心看**上沿内缩 3px 的点**（环在那里是内孔）；不看正中心——短横正好压中心。
+    let mut dots = 0;
+    for bbox in &twenty {
+        if matches(shot.at(center(bbox).0, bbox.top + 3), rgb(primary)) {
+            continue;
+        }
+        assert!(
+            !matches(shot.at(bbox.left + 1, bbox.top + 1), rgb(primary)),
+            "19.6：Radio 外圈必须是真圆（不是圆角方）@ {:?}",
+            (bbox.left, bbox.top)
+        );
+        let dot = inner_ink(&shot, bbox, primary, surface, 4).expect("选中的 radio 必须有内点");
+        assert!(
+            near(dot.width(), 10) && near(dot.height(), 10),
+            "19.2：Radio 内点可视直径 10（12 是含描边前的名义值），实测 {}×{}",
+            dot.width(),
+            dot.height()
+        );
+        assert_ne!(dot.width(), 12, "19.2：照名义值抄 12 会明显偏大");
+        dots += 1;
+    }
+    assert_eq!(
+        dots, 4,
+        "19.2：应恰好 4 个选中的 radio（四态），实际 {dots}"
+    );
+
+    // ---- §18.4 / §18.6：勾形墨迹跨度；indeterminate 是**短横**不是勾 --------------
+    let mut bars = 0;
+    let mut checks = 0;
+    for bbox in &twenty {
+        let Some(glyph) = inner_ink(&shot, bbox, on_primary, primary, 3) else {
+            continue;
+        };
+        if glyph.height() <= 4 {
+            bars += 1;
+            assert!(
+                glyph.width() >= 12,
+                "18.6：indeterminate 必须是居中短横，实测 {}×{}",
+                glyph.width(),
+                glyph.height()
+            );
+        } else {
+            checks += 1;
+            // 端点 12 + 方头两侧各 2/√2 ≈ 1.41 → 墨迹 ≈14.8（见 `ControlGeometry`）
+            assert!(
+                (13..=16).contains(&glyph.width()),
+                "18.4：勾形墨迹横向应 ≈14.8（端点 12 + 方头外扩），实测 {}",
+                glyph.width()
+            );
+            assert!(
+                glyph.height() >= 6,
+                "18.4：勾形有折点，实测高 {}",
+                glyph.height()
+            );
+        }
+    }
+    assert!(
+        bars >= 4 && checks >= 4,
+        "18.4/18.6：勾 {checks} 个、短横 {bars} 个（各应 ≥4）"
+    );
+
+    // ---- §18.5 / §19.7：状态层直径 40，且**每一块**都是圆（四角无墨）----------------
+    // hover 是 8%、pressed/focus 是 10%：**两种颜色都要查**。只查 8% 会漏掉「按下那一列被画成
+    // 方块」——代码 reviewer 的第二次变异正好落在这个盲点上（实测它当时是绿的）。
+    let mut circles = 0;
+    for state in [Interaction::Hovered, Interaction::Pressed] {
+        let layer = interaction::overlay_color(&ui, state, Role::OnSurfaceVariant, Role::Surface)
+            .expect("可交互态有状态层");
+        let found: Vec<_> = ink_boxes(&shot, layer, surface, 37, 43)
+            .into_iter()
+            .filter(|bbox| near(bbox.width(), 40) && near(bbox.height(), 40))
+            .collect();
+        assert!(
+            found.len() >= 2,
+            "18.5：{state:?} 的 Ø40 状态层应 ≥2 块（checkbox×3 + radio + switch），实测 {}：{}",
+            found.len(),
+            dims(&found)
+        );
+        for circle in &found {
+            for (x, y) in [
+                (circle.left, circle.top),
+                (circle.right, circle.top),
+                (circle.left, circle.bottom),
+                (circle.right, circle.bottom),
+            ] {
+                assert!(
+                    !matches(shot.at(x, y), rgb(layer)),
+                    "18.5：{state:?} 状态层必须是圆（外接框四角不该有墨）@ ({x},{y})"
+                );
+            }
+        }
+        circles += found.len();
+    }
+
+    // ---- §10.1 Switch 轨道 52×32 · §13.1 Chip 高 32 -------------------------------
+    let on_tracks: Vec<_> = ink_boxes(&shot, primary, surface, 28, 57)
+        .into_iter()
+        .filter(|bbox| near(bbox.width(), 52) && near(bbox.height(), 32))
+        .collect();
+    assert_eq!(
+        on_tracks.len(),
+        1,
+        "10.1：选中的 switch 轨道应**恰好一块** 52×32，实测 {}：{}",
+        on_tracks.len(),
+        dims(&on_tracks)
+    );
+    let chips: Vec<_> = ink_boxes(&shot, ui.color(Role::SecondaryContainer), surface, 20, 140)
+        .into_iter()
+        .filter(|bbox| near(bbox.height(), 32))
+        .collect();
+    // 选中的 chip 在**四态**里容器都是 `SecondaryContainer`（状态层只叠在未选中的透明底上），
+    // 所以这里应恰好 4 块——多于 4 说明别的组件的容器也是这个角色、且高 32。
+    assert_eq!(
+        chips.len(),
+        4,
+        "13.1：选中的 filter chip 应**恰好四块**（enabled/hover/pressed/focused 各一，32 高），\
+         实测 {}：{}",
+        chips.len(),
+        dims(&chips)
+    );
+    assert!(
+        chips[0].width() >= 58,
+        "13.1：chip 宽应 ≥58（图标 18 + 两侧各 8 + 文字），实测 {}",
+        chips[0].width()
+    );
+
+    // ---- 复审 P2-1：禁用的 chip **只降不删**（选中态与图标都要在）------------------
+    // 判据：禁用列里必须**恰好有一块** 12% 填充的 chip（= filter·on）。旧 API 把 selected
+    // 一起删掉，这一块根本不存在（实测 0 块）；能查到它、且宽度 ≥58，说明选中态与图标都还在。
+    // （未选中的那三个禁用 chip 只有 1px 描边，落在半像素上时覆盖率不足 50%，量不稳，故不在此断言。）
+    let disabled_container = interaction::disabled_colors(&ui, Role::Surface).0;
+    let disabled_chips: Vec<_> = ink_boxes(&shot, disabled_container, surface, 28, 140)
+        .into_iter()
+        .filter(|bbox| near(bbox.height(), 32) && bbox.width() >= 58)
+        .collect();
+    assert_eq!(
+        disabled_chips.len(),
+        1,
+        "P2-1：禁用列应**恰好一块**填充 chip（filter·on 的选中态不能被删掉），实测 {}：{}",
+        disabled_chips.len(),
+        dims(&disabled_chips)
+    );
+    assert!(
+        disabled_chips[0].width() >= 58,
+        "P2-1：禁用 chip 宽度应 ≥58（图标还在），实测 {}",
+        disabled_chips[0].width()
+    );
+
+    // ---- 复审 P2-3：**选中且禁用**的 Checkbox 容器是 38%，不是 12% -----------------
+    let disabled_ink = interaction::disabled_content_over_role(&ui, Role::OnSurface, false);
+    let ink38: Vec<_> = ink_boxes(&shot, disabled_ink, surface, 17, 24)
+        .into_iter()
+        .filter(|bbox| near(bbox.width(), 20) && near(bbox.height(), 20))
+        .collect();
+    assert!(
+        ink38.len() >= 3,
+        "18.8：禁用列应有 ≥3 块 20(±1) 的 38% 叠色（选中禁用填充 + 未选中禁用描边 + radio 环），\
+         实测 {}：{}",
+        ink38.len(),
+        dims(&ink38)
+    );
+    let container_20: Vec<_> = ink_boxes(&shot, disabled_container, surface, 19, 21)
+        .into_iter()
+        .filter(|bbox| near(bbox.width(), 20) && near(bbox.height(), 20))
+        .collect();
+    assert!(
+        container_20.is_empty(),
+        "P2-3：20×20 的禁用块不许是 12% 容器色（那是普通禁用容器，选中禁用是 38%），实测 {}",
+        dims(&container_20)
+    );
+
+    eprintln!(
+        "[selection-probe] OK flavor={flavor:?}：20(±1) Primary 块 {} · 未选中环 {} · 内点 {dots} · \
+         勾 {checks} / 短横 {bars} · 状态层 {} · 禁用 38% {} · 禁用 chip {}",
+        twenty.len(),
+        rings.len(),
+        circles,
+        ink38.len(),
+        disabled_chips.len()
+    );
+}
diff --git a/crates/app-iced/src/components/selection/radio.rs b/crates/app-iced/src/components/selection/radio.rs
new file mode 100644
index 0000000..64680cd
--- /dev/null
+++ b/crates/app-iced/src/components/selection/radio.rs
@@ -0,0 +1,155 @@
+//! Radio button（`research/15` §19）：外圈 **20** / 环线 **2** / 内点 **10**（不是 12）/
+//! 选中环+点 `Primary` / 未选中环 `OnSurfaceVariant`（hover 提到 `OnSurface`）/ Ø40 状态层。
+//!
+//! ## 为什么它不是「基于 Checkbox 画的」
+//!
+//! §19.6 明令：Radio **只能**是「2px 环 + 实心内点」，Checkbox **只能**是「2px 方框 + 勾/横」；
+//! 两者尺寸相同（20）但形状语言不同，禁止混用。所以本文件是独立实现，**没有** import
+//! `super::checkbox`（gallery 的 probe 另有一条断言：radio 的墨迹里不得出现方角像素）。
+//!
+//! ## 几何怎么落到像素
+//!
+//! 环：20×20 容器 + `Border { width: 2, radius: 10 }`。iced 的 quad 渲染器把描边路径向内缩
+//! 半个线宽（半径 10−1=9、路径外接 18），再以 2 描边 → 外缘正好 20、内缘 16。这与 Compose
+//! `RadioButton.kt` 的「环半径 = 10 − 1 = 9 且描边居中 → 外缘正好 20」逐像素同源。
+//! 内点：独立 10×10 圆容器居中在环里（绘制半径 12/2 − 2/2 = 5，即**直径 10**，§19.2）。
+
+use iced::widget::{container, row, text};
+use iced::{Alignment, Element, Length, Padding};
+
+use unlucky_design::typography::TypeRole;
+
+use crate::theme::Ui;
+
+use super::super::interaction::Interaction;
+use super::geometry::ControlGeometry;
+use super::paint::{self, Frame};
+use super::shell::{self, StateSource};
+
+/// 一个单选框（环 + 可选标签；`on_select` 为 `None` = 禁用）。
+#[derive(Debug, Clone)]
+pub struct Radio<'a, M> {
+    label: &'a str,
+    selected: bool,
+    on_select: Option<M>,
+    state: Option<Interaction>,
+}
+
+impl<'a, M> Radio<'a, M> {
+    /// 一个可选的单选框。
+    pub fn new(label: &'a str, selected: bool, on_select: M) -> Self {
+        Self {
+            label,
+            selected,
+            on_select: Some(on_select),
+            state: None,
+        }
+    }
+
+    /// 禁用的单选框（无消息）。
+    pub fn disabled(label: &'a str, selected: bool) -> Self {
+        Self {
+            label,
+            selected,
+            on_select: None,
+            state: None,
+        }
+    }
+
+    /// 强制视觉态（gallery 取证用；运行期不要调）。
+    pub fn state(mut self, state: Interaction) -> Self {
+        self.state = Some(state);
+        self
+    }
+}
+
+/// 画一个单选框（环 + 内点 + 标签）。
+pub fn radio<'a, M: Clone + 'a>(ui: &'a Ui, spec: Radio<'a, M>) -> Element<'a, M> {
+    let geometry = ControlGeometry::radio(ui);
+    let selected = spec.selected;
+    let radius = geometry.radius;
+    let stroke = geometry.stroke;
+    let dot_side = geometry.inner_dot;
+    let source = StateSource::new(spec.state, spec.on_select.is_some());
+
+    // 内点与环的颜色与 hover/pressed 无关（A1：选中态四态都是 `Primary`），
+    // 只随「选中 + 禁用」变 —— 所以点的颜色在这里静态求值即可。
+    let at_rest = paint::radio(ui, selected, source.get(), radius, stroke);
+
+    // Ø10 内点（半径 = 直径/2）
+    let dot: Element<'a, M> = match at_rest.dot {
+        Some(ink) => container(iced::widget::Space::new())
+            .width(Length::Fixed(dot_side))
+            .height(Length::Fixed(dot_side))
+            .style(move |_theme| {
+                Frame {
+                    fill: Some(ink),
+                    outline: None,
+                    stroke: 0.0,
+                    radius: dot_side / 2.0,
+                }
+                .container_style()
+            })
+            .into(),
+        None => iced::widget::Space::new().into(),
+    };
+
+    // 20 外圈：环（未选中时环就是唯一的墨迹；选中时环 + 点同色）
+    let ring = container(dot)
+        .width(Length::Fixed(geometry.side))
+        .height(Length::Fixed(geometry.side))
+        .align_x(Alignment::Center)
+        .align_y(Alignment::Center)
+        .style(source.container_style(move |state| {
+            paint::radio(ui, selected, state, radius, stroke)
+                .ring
+                .container_style()
+        }));
+
+    // Ø40 状态层
+    let layer_side = geometry.state_layer;
+    let layer = container(ring)
+        .width(Length::Fixed(layer_side))
+        .height(Length::Fixed(layer_side))
+        .align_x(Alignment::Center)
+        .align_y(Alignment::Center)
+        .style(source.container_style(move |state| {
+            Frame {
+                fill: paint::state_layer(ui, state, paint::radio_layer_role(selected)),
+                outline: None,
+                stroke: 0.0,
+                radius: layer_side / 2.0,
+            }
+            .container_style()
+        }));
+
+    let mut content = row![layer].align_y(Alignment::Center).spacing(geometry.gap);
+    if !spec.label.is_empty() {
+        let style = ui.style(TypeRole::BodyLarge);
+        content = content.push(
+            text(spec.label)
+                .size(style.size_px)
+                .font(ui.font_of(style))
+                .color(paint::label(ui, source.get())),
+        );
+    }
+
+    // 命中区 48×48：左右各留 `hit_padding` 透明内边距（无标签时行宽才不是 40；复审 P2-2）
+    let pad = geometry.hit_padding();
+    let body = container(content)
+        .height(Length::Fill)
+        .align_y(Alignment::Center)
+        .padding(Padding {
+            left: pad,
+            right: pad,
+            ..Padding::default()
+        });
+
+    shell::shell(
+        &source,
+        Length::Shrink,
+        Length::Fixed(geometry.hit),
+        spec.on_select,
+        body.into(),
+    )
+}
diff --git a/crates/app-iced/src/components/selection/shell.rs b/crates/app-iced/src/components/selection/shell.rs
new file mode 100644
index 0000000..0034cdf
--- /dev/null
+++ b/crates/app-iced/src/components/selection/shell.rs
@@ -0,0 +1,156 @@
+//! 交互外壳：`button` 的四态 → 内部自绘容器的样式；以及勾形的 SVG。
+//!
+//! ## 为什么需要 [`StateSource`] 这条「帧内通道」
+//!
+//! M3 的 Checkbox / Radio / Switch 状态层是**Ø40 的圆**，而命中区是 **48**
+//! （`research/15` §18.5 / §18.9）——两者尺寸不同，所以状态层不可能就是 `button` 自己的
+//! 矩形四角（`button` 只能给自己的 bounds 上色）。正确画法是「48 的透明按钮里放一个 40 的圆」，
+//! 但这个圆的颜色要跟着**按钮的状态**走，而 iced 的 `container` 样式闭包只有 `&Theme`、拿不到
+//! `button::Status`。
+//!
+//! 所以这里留一个帧内通道：`button` 的样式闭包先跑（父先于子绘制，`iced_widget::button::draw`
+//! 第 382 行 `fill_quad` 在 `content.draw` 之前），把状态写进 [`StateSource`]；子容器的样式闭包
+//! 随后读到**本帧**的状态。α 仍然只从 [`super::super::interaction`] 取，这里不做任何颜色算术。
+//!
+//! 取证（gallery 状态矩阵）时用 [`StateSource::forced`] 直接钉住某态，通道根本不参与。
+
+use std::cell::Cell;
+use std::rc::Rc;
+
+use iced::widget::{button, svg};
+use iced::{Color, Element, Length, Padding};
+
+use super::super::interaction::Interaction;
+use super::geometry::ControlGeometry;
+
+/// 当前视觉态的取值口：**外部钉住**（取证）或**跟随 `button` 的实况**（运行期）。
+#[derive(Debug, Clone)]
+pub struct StateSource {
+    forced: Option<Interaction>,
+    live: Option<Rc<Cell<Interaction>>>,
+    enabled: bool,
+}
+
+impl StateSource {
+    /// `forced = Some(..)`：钉住某态（gallery 用）；`None`：跟随 `button`。
+    ///
+    /// `enabled = false`（没有消息 = 禁用）时直接返回 [`Interaction::Disabled`]：iced 的
+    /// `Button::status` 在**首帧**还是 `None`（→ 按 `Disabled` 画），靠它判断禁用会让首帧
+    /// 画错色，所以禁用这件事由调用方给定，通道只管 hover/pressed。
+    pub fn new(forced: Option<Interaction>, enabled: bool) -> Self {
+        Self {
+            forced,
+            live: (forced.is_none() && enabled).then(|| Rc::new(Cell::new(Interaction::Enabled))),
+            enabled,
+        }
+    }
+
+    /// 本帧要画的态。
+    pub fn get(&self) -> Interaction {
+        if let Some(forced) = self.forced {
+            return forced;
+        }
+        if !self.enabled {
+            return Interaction::Disabled;
+        }
+        self.live
+            .as_ref()
+            .map_or(Interaction::Enabled, |live| live.get())
+    }
+
+    /// `button` 的样式闭包里调（把实况写进通道）。
+    fn record(&self, status: button::Status) {
+        if let (Some(live), true) = (&self.live, self.enabled) {
+            live.set(Interaction::from_status(status));
+        }
+    }
+
+    /// 一个 `container::Style` 闭包：每次绘制按「本帧的态」求值。
+    pub fn container_style<'a, F>(
+        &self,
+        build: F,
+    ) -> impl Fn(&iced::Theme) -> iced::widget::container::Style + 'a
+    where
+        F: Fn(Interaction) -> iced::widget::container::Style + 'a,
+    {
+        let source = self.clone();
+        move |_theme| build(source.get())
+    }
+}
+
+/// 透明的交互外壳：尺寸由调用方给定，视觉**全部**由内部容器负责。
+///
+/// 交互外壳自己不画任何东西——它有且只有一个职责：把 48 的命中区交出去，并把
+/// `button` 的状态写进 [`StateSource`]。
+pub(super) fn shell<'a, M: Clone + 'a>(
+    source: &StateSource,
+    width: Length,
+    height: Length,
+    on_press: Option<M>,
+    content: Element<'a, M>,
+) -> Element<'a, M> {
+    let recorder = source.clone();
+    let element = button(content)
+        .width(width)
+        .height(height)
+        .padding(Padding::default())
+        .style(move |_theme, status| {
+            recorder.record(status);
+            button::Style {
+                background: None,
+                text_color: Color::TRANSPARENT,
+                ..button::Style::default()
+            }
+        });
+
+    match on_press {
+        Some(message) => element.on_press(message).into(),
+        None => element.into(),
+    }
+}
+
+/// 勾形 / 短横的 SVG（`research/15` §18.4 / §18.6）。
+///
+/// 为什么用 SVG 而不是自绘：勾形是**斜线**，iced 的 `fill_quad` 只能画轴对齐矩形，而
+/// `canvas` feature 没开（`crates/app-iced/Cargo.toml` 不在本 mission 的 scope）。
+/// `stroke-linecap="square"` 与 Compose 的 `StrokeCap.Square` 同义；路径比例
+/// （0.2 / 0.4 / 0.5 / 0.7 / 0.8）是 `research/15` §25 明确允许的组件级常量。
+///
+/// `indeterminate` = 三点共线于 `y = 0.5`（`crossCenterGravitation = 1`）→ **形变**成一条居中短横，
+/// **不新增图标**（§18.6）。
+pub(super) fn glyph<'a, M: 'a>(
+    geometry: ControlGeometry,
+    indeterminate: bool,
+    ink: Color,
+) -> Element<'a, M> {
+    let side = geometry.side;
+    let point = |x: f32, y: f32| (side * x, side * y);
+    let path = if indeterminate {
+        // 三个控制点被拉到同一条水平线（勾形消失，只剩短横）
+        let (x0, y0) = point(0.2, 0.5);
+        let (x1, y1) = point(0.8, 0.5);
+        format!("M {x0:.2} {y0:.2} L {x1:.2} {y1:.2}")
+    } else {
+        let (x0, y0) = point(0.2, 0.5);
+        let (x1, y1) = point(0.4, 0.7);
+        let (x2, y2) = point(0.8, 0.3);
+        format!("M {x0:.2} {y0:.2} L {x1:.2} {y1:.2} L {x2:.2} {y2:.2}")
+    };
+    let source = format!(
+        "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"{side}\" height=\"{side}\" \
+         viewBox=\"0 0 {side} {side}\"><path d=\"{path}\" fill=\"none\" stroke=\"currentColor\" \
+         stroke-width=\"{}\" stroke-linecap=\"square\" stroke-linejoin=\"miter\"/></svg>",
+        geometry.stroke
+    );
+
+    svg(svg::Handle::from_memory(source.into_bytes()))
+        .width(Length::Fixed(side))
+        .height(Length::Fixed(side))
+        .style(move |_theme, _status| svg::Style { color: Some(ink) })
+        .into()
+}
+
+/// 一个固定边长的正方形（内部再居中）：Q9 的纪律，字形一律锁在盒子里。
+pub(super) fn square<'a, M: 'a>(side: f32, content: impl Into<Element<'a, M>>) -> Element<'a, M> {
+    super::super::layout::centered_fixed(side, side, content)
+}
diff --git a/crates/app-iced/src/components/selection/switch.rs b/crates/app-iced/src/components/selection/switch.rs
new file mode 100644
index 0000000..b097cda
--- /dev/null
+++ b/crates/app-iced/src/components/selection/switch.rs
@@ -0,0 +1,177 @@
+//! Switch（`research/12b` §10）：轨道 **52×32** / 圆角 full(16) / 未选中 2px `Outline` 描边 /
+//! 滑块 **24·16**（按下 28，见偏离 D-SW1）/ 滑块内图标 16 / **Ø40 状态层**。
+//!
+//! ## 状态层为什么跟滑块走
+//!
+//! M3 的 switch 状态层是围着**滑块**的 Ø40 圆（`StateLayerSize = 40`），而轨道只有 32 高、
+//! 52 宽、滑块最小 16——圆会同时超出轨道的上下与左右。所以绘制区比轨道大一圈：
+//! 宽 = 52 + 2×4（[`SwitchGeometry::draw_width`]）、高 = 40，轨道在中间，滑块与状态层浮在上面。
+//!
+//! ## 偏离 D-SW1（登记在报告里）
+//!
+//! `PressedHandleWidth = 28` 的「按下胀开」**未做**：iced 的 `button` 只在事件时重绘，
+//! 不会重建视图，而滑块尺寸是**布局量**（不是颜色）。要做它必须写自定义 `Widget`
+//! （`interaction::Tracker` 那条路），本 mission 的时间盒留给四条线的像素断言与视觉证据。
+//! 按下的可判定反馈仍在：状态层 α 从 8% 升到 10%（`StateLayer::Pressed`）。
+
+use iced::widget::{container, row, text, Space as Spacer};
+use iced::{Alignment, Element, Length, Padding};
+
+use unlucky_design::icons::IconKind;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use crate::icons;
+use crate::theme::Ui;
+
+use super::super::interaction::Interaction;
+use super::geometry::SwitchGeometry;
+use super::paint::{self, Frame};
+use super::shell::{self, StateSource};
+
+/// 一个开关（轨道 + 滑块 + 可选标签；`on_toggle` 为 `None` = 禁用）。
+#[derive(Debug, Clone)]
+pub struct Switch<'a, M> {
+    label: &'a str,
+    value: bool,
+    on_toggle: Option<M>,
+    state: Option<Interaction>,
+}
+
+impl<'a, M> Switch<'a, M> {
+    /// 一个可切换的开关。
+    pub fn new(label: &'a str, value: bool, on_toggle: M) -> Self {
+        Self {
+            label,
+            value,
+            on_toggle: Some(on_toggle),
+            state: None,
+        }
+    }
+
+    /// 禁用的开关（无消息）。
+    pub fn disabled(label: &'a str, value: bool) -> Self {
+        Self {
+            label,
+            value,
+            on_toggle: None,
+            state: None,
+        }
+    }
+
+    /// 强制视觉态（gallery 取证用；运行期不要调）。
+    pub fn state(mut self, state: Interaction) -> Self {
+        self.state = Some(state);
+        self
+    }
+}
+
+/// 画一个开关（轨道 + 滑块 + 标签）。
+pub fn switch<'a, M: Clone + 'a>(ui: &'a Ui, spec: Switch<'a, M>) -> Element<'a, M> {
+    let geometry = SwitchGeometry::of(ui);
+    let selected = spec.value;
+    let thumb_side = geometry.thumb(selected, false);
+    let source = StateSource::new(spec.state, spec.on_toggle.is_some());
+
+    // 滑块内的勾：颜色只随选中/禁用变（A1 的 `Selected*IconColor` 都是 `OnPrimaryContainer`），
+    // 所以静态求值；未选中态官方图标色 = 轨道色（画了也看不见），因此不画。
+    let at_rest = paint::switch(ui, selected, source.get());
+    let glyph: Element<'a, M> = match at_rest.icon {
+        Some(ink) => super::super::layout::centered_fixed(
+            geometry.icon,
+            geometry.icon,
+            // 盒 16 ≠ RENDER_PX(24)：必须按 16 烘焙，否则线宽被布局压细（复审 r1 P2-2）。
+            icons::view_at::<M>(IconKind::Check, ink, geometry.icon),
+        ),
+        None => Spacer::new().into(),
+    };
+
+    // 滑块（颜色跟态走：hover/pressed 是 `PrimaryContainer`）
+    let thumb = container(glyph)
+        .width(Length::Fixed(thumb_side))
+        .height(Length::Fixed(thumb_side))
+        .align_x(Alignment::Center)
+        .align_y(Alignment::Center)
+        .style(source.container_style(move |state| {
+            Frame {
+                fill: Some(paint::switch(ui, selected, state).thumb),
+                outline: None,
+                stroke: 0.0,
+                radius: thumb_side / 2.0,
+            }
+            .container_style()
+        }));
+
+    // Ø40 状态层（围着滑块，圆心与滑块同心）
+    let layer_side = geometry.state_layer;
+    let layer = container(thumb)
+        .width(Length::Fixed(layer_side))
+        .height(Length::Fixed(layer_side))
+        .align_x(Alignment::Center)
+        .align_y(Alignment::Center)
+        .style(source.container_style(move |state| {
+            Frame {
+                fill: paint::switch_layer(ui, state, selected),
+                outline: None,
+                stroke: 0.0,
+                radius: layer_side / 2.0,
+            }
+            .container_style()
+        }));
+
+    // 轨道（52×32；未选中态有 2px `Outline` 描边）
+    let track = container(Spacer::new())
+        .width(Length::Fixed(geometry.track_width))
+        .height(Length::Fixed(geometry.track_height))
+        .style(source.container_style(move |state| {
+            paint::switch(ui, selected, state).track.container_style()
+        }));
+
+    // 绘制区 = 轨道 + 状态层外扩；两层叠放（层序：轨道在下，滑块与状态层在上）
+    let draw_width = geometry.draw_width();
+    let draw_height = geometry.draw_height();
+    let area = iced::widget::stack![
+        container(track)
+            .width(Length::Fixed(draw_width))
+            .height(Length::Fixed(draw_height))
+            .padding(Padding {
+                left: geometry.bleed(),
+                ..Padding::default()
+            })
+            .align_y(Alignment::Center),
+        container(layer)
+            .width(Length::Fixed(draw_width))
+            .height(Length::Fixed(draw_height))
+            .padding(Padding {
+                left: geometry.layer_offset(selected, thumb_side),
+                ..Padding::default()
+            }),
+    ]
+    .width(Length::Fixed(draw_width))
+    .height(Length::Fixed(draw_height));
+
+    let mut content = row![area]
+        .align_y(Alignment::Center)
+        .spacing(ui.space(Space::X3));
+    if !spec.label.is_empty() {
+        let style = ui.style(TypeRole::BodyMedium);
+        content = content.push(
+            text(spec.label)
+                .size(style.size_px)
+                .font(ui.font_of(style))
+                .color(paint::label(ui, source.get())),
+        );
+    }
+
+    let body = container(content)
+        .height(Length::Fill)
+        .align_y(Alignment::Center);
+
+    shell::shell(
+        &source,
+        Length::Shrink,
+        Length::Fixed(geometry.hit),
+        spec.on_toggle,
+        body.into(),
+    )
+}
diff --git a/crates/app-iced/src/components/selection/tests.rs b/crates/app-iced/src/components/selection/tests.rs
new file mode 100644
index 0000000..3bb995b
--- /dev/null
+++ b/crates/app-iced/src/components/selection/tests.rs
@@ -0,0 +1,358 @@
+//! 选择类家族的单测：几何取自令牌、角色取自 A1（`#[cfg(test)]` 下的纯值断言）。
+//!
+//! **这些测试测的是「值与映射」**——它们抓不住「函数对、图错」（M68 的教训），
+//! 像素级几何在 `components/gallery/selection.rs` 的 `probe` 里对着真截图量。
+
+use unlucky_design::color::{Role, SchemeFlavor};
+use unlucky_design::typography::Platform;
+
+use super::super::interaction::{self, Interaction};
+use super::geometry::{ChipGeometry, ControlGeometry, SwitchGeometry};
+use super::paint::{self, ChipVariant};
+use crate::theme::{Families, Ui};
+
+const FAMILIES: Families = Families {
+    text: "Segoe UI",
+    display: "Segoe UI",
+    mono: "Consolas",
+};
+
+fn ui() -> Ui {
+    Ui::with_platform(SchemeFlavor::Light, Platform::Windows, FAMILIES)
+}
+
+/// 复审 P2-2：命中区恒 **48×48**——Ø40 状态层之外左右各 4dp 透明内边距（无标签时行宽才不是 40）。
+#[test]
+fn hit_area_is_48_square_even_without_a_label() {
+    let ui = ui();
+    for (name, geometry) in [
+        ("checkbox", ControlGeometry::checkbox(&ui)),
+        ("radio", ControlGeometry::radio(&ui)),
+    ] {
+        assert_eq!(geometry.hit, 48.0, "{name} 命中区必须是 48");
+        assert_eq!(geometry.state_layer, 40.0, "{name} 状态层 Ø40");
+        assert_eq!(geometry.hit_padding(), 4.0, "{name} 左右各留 4dp");
+        assert_eq!(
+            geometry.state_layer + geometry.hit_padding() * 2.0,
+            geometry.hit,
+            "{name}：可见 40 + 左右各 4 = 命中 48"
+        );
+    }
+}
+
+/// §18.1 / §18.5 / §18.9：Checkbox 的四个参考值全部来自令牌层。
+#[test]
+fn checkbox_geometry_comes_from_the_token_layer() {
+    let ui = ui();
+    let g = ControlGeometry::checkbox(&ui);
+    assert_eq!(g.side, 20.0, "18.1：容器 20×20（ContainerWidth=18 是死值）");
+    assert_eq!(g.radius, 2.0, "18.1：圆角 2（ComponentRadius::Micro）");
+    assert_eq!(g.stroke, 2.0, "18.2：未选中描边 2px");
+    assert_eq!(g.state_layer, 40.0, "18.5：状态层 Ø40");
+    assert_eq!(g.hit, 48.0, "18.9：命中区 48");
+    assert_eq!(g.gap, 8.0, "18.9：框↔标签 8（[估] 团队口径）");
+    assert_eq!(g.inner_dot, 0.0, "Checkbox 没有内点");
+    // 18.4：勾形横向端点跨度 = 0.8−0.2 = 0.6 × 20 = 12
+    assert!((g.check_span() - 12.0).abs() < 0.001, "18.4：勾横向 12dp");
+    // 方头外扩：每端 2/√2 ≈ 1.41 → 墨迹跨度 ≈ 14.8（参考值 12 是端点跨度，不是墨迹）
+    let bleed = g.square_cap_bleed();
+    assert!(
+        (bleed - std::f32::consts::SQRT_2).abs() < 0.001,
+        "方头外扩 1/√2×线宽"
+    );
+    assert!(
+        (g.check_span() + bleed * 2.0 - 14.83).abs() < 0.05,
+        "墨迹跨度 ≈14.83"
+    );
+}
+
+/// §19.1 / §19.2：Radio 外圈 20、环线 2、**内点 10 不是 12**、真圆。
+#[test]
+fn radio_inner_dot_is_ten_not_twelve() {
+    let ui = ui();
+    let g = ControlGeometry::radio(&ui);
+    assert_eq!(g.side, 20.0, "19.1：外圈直径 20");
+    assert_eq!(g.stroke, 2.0, "19.1：环线 2px");
+    assert_eq!(g.radius, 10.0, "19.1：真圆（半径 = 边长/2）");
+    assert_eq!(g.inner_dot, 10.0, "19.2：内点可视直径 10");
+    assert_ne!(
+        g.inner_dot, 12.0,
+        "19.2：12 是含描边前的名义值，抄 12 会明显偏大"
+    );
+    assert_eq!(g.state_layer, 40.0, "19.7：状态层 Ø40");
+    assert_eq!(g.hit, 48.0, "19.7：命中区 48");
+}
+
+/// §10.1 / §10.2 / §10.6：Switch 的三档滑块与状态层，以及「状态层必然溢出轨道」这条布局不变量。
+#[test]
+fn switch_geometry_matches_the_tokens() {
+    let ui = ui();
+    let g = SwitchGeometry::of(&ui);
+    assert_eq!(g.track_width, 52.0, "10.1：轨道宽 52");
+    assert_eq!(g.track_height, 32.0, "10.1：轨道高 32");
+    assert_eq!(g.track_stroke, 2.0, "10.3：未选中态 2px Outline");
+    assert_eq!(g.thumb(false, false), 16.0, "10.2：未选中滑块 16");
+    assert_eq!(g.thumb(true, false), 24.0, "10.2：选中滑块 24");
+    assert_eq!(g.thumb(false, true), 28.0, "10.2：按下滑块 28");
+    assert_eq!(g.thumb(true, true), 28.0, "10.2：按下档与选中无关");
+    assert_eq!(
+        g.icon, 16.0,
+        "10.5：滑块内图标 16（官方 SwitchTokens.SelectedIconSize，令牌 IconSize::SwitchThumb）"
+    );
+    assert_eq!(
+        g.icon,
+        unlucky_design::icons::IconSize::SwitchThumb.px(),
+        "滑块图标必须走 SwitchThumb 档，不许借按钮的 18"
+    );
+    assert_eq!(g.state_layer, 40.0, "10.6：状态层 Ø40");
+    assert_eq!(g.hit, 48.0, "命中区 48");
+
+    // 内距公式在三个档位都成立（32−24=8→4、32−16=16→8、32−28=4→2）
+    for thumb in [24.0, 16.0, 28.0] {
+        assert!((g.thumb_inset(thumb) * 2.0 + thumb - g.track_height).abs() < 0.001);
+    }
+    // 状态层必然溢出轨道左右：未选中时滑块靠左、选中时靠右
+    assert_eq!(g.bleed(), 4.0, "状态层比轨道高 → 上下各溢出 4");
+    assert_eq!(g.draw_width(), 60.0, "绘制区宽 = 52 + 2×4");
+    for (selected, thumb) in [(false, 16.0), (true, 24.0), (false, 28.0), (true, 28.0)] {
+        let offset = g.layer_offset(selected, thumb);
+        assert!(
+            offset >= 0.0,
+            "状态层左缘不得为负（selected={selected} thumb={thumb} → {offset}）"
+        );
+        // 圆心与滑块同心：offset + 半径 = 滑块圆心 + 外扩
+        let center = offset + g.layer_radius();
+        assert!((center - (g.thumb_center(selected, thumb) + g.bleed())).abs() < 0.001);
+    }
+}
+
+/// §13.1 / §13.3 / §13.4：Chip 高 32、圆角 8、内边距 8、图标 18（官方 `AssistChipTokens.IconSize`，G14 已收口）。
+#[test]
+fn chip_geometry_matches_the_tokens() {
+    let ui = ui();
+    let g = ChipGeometry::of(&ui);
+    assert_eq!(g.height, 32.0, "13.1：容器高 32");
+    assert_eq!(g.radius, 8.0, "13.1：圆角 8（ContainerShape=CornerSmall）");
+    assert_eq!(g.pad, 8.0, "13.3：水平内边距 8");
+    assert_eq!(g.gap, 8.0, "13.3：元素间距 8");
+    // 旧期望 16 记的是 G14 偏离（令牌层当时没有 18 档）；令牌补齐后官方值 18 才是对的
+    // ——AAR `AssistChipTokens.IconSize = 18.0d`，12b 13.4 也写 18。这不是「把期望改成实现」，
+    // 是偏离被取消。
+    assert_eq!(
+        g.icon, 18.0,
+        "13.4：图标 18（官方 AssistChipTokens.IconSize）"
+    );
+    assert_eq!(
+        g.icon,
+        unlucky_design::icons::IconSize::Button.px(),
+        "chip 图标与按钮图标同源（令牌 IconSize::Button）"
+    );
+}
+
+/// §18.2 / A1：未选中 Checkbox 在 hover/focus/pressed 下描边提到 `OnSurface`（不是 `OnSurfaceVariant`）。
+#[test]
+fn checkbox_unselected_lifts_the_outline_to_on_surface() {
+    let ui = ui();
+    let g = ControlGeometry::checkbox(&ui);
+    let at_rest = paint::checkbox(&ui, false, false, Interaction::Enabled, g.radius, g.stroke);
+    assert_eq!(
+        at_rest.frame.outline,
+        Some(ui.color(Role::OnSurfaceVariant))
+    );
+    for state in [
+        Interaction::Hovered,
+        Interaction::Focused,
+        Interaction::Pressed,
+    ] {
+        let lifted = paint::checkbox(&ui, false, false, state, g.radius, g.stroke);
+        assert_eq!(
+            lifted.frame.outline,
+            Some(ui.color(Role::OnSurface)),
+            "A1：{state:?} 的 UnselectedOutlineColor = OnSurface"
+        );
+        assert_eq!(lifted.frame.stroke, 2.0, "18.8：描边宽度不随态变");
+    }
+    // 错误态优先于 hover
+    let error = paint::checkbox(&ui, false, true, Interaction::Hovered, g.radius, g.stroke);
+    assert_eq!(error.frame.outline, Some(ui.color(Role::Error)));
+}
+
+/// §18.8：禁用不是「变淡变细」——描边仍 2；选中禁用是 `OnSurface`@38% 容器 + `Surface` 勾。
+#[test]
+fn checkbox_disabled_keeps_the_stroke_and_uses_the_a1_roles() {
+    let ui = ui();
+    let g = ControlGeometry::checkbox(&ui);
+    let unchecked = paint::checkbox(&ui, false, false, Interaction::Disabled, g.radius, g.stroke);
+    assert_eq!(unchecked.frame.stroke, 2.0, "18.8：禁用描边仍 2px");
+    assert_eq!(unchecked.frame.fill, None, "18.8：未选中禁用内部仍透明");
+    assert!(
+        unchecked
+            .frame
+            .outline
+            .is_some_and(|color| color != ui.color(Role::OnSurfaceVariant)),
+        "18.8：禁用描边是 OnSurface@38%，不是满档角色色"
+    );
+
+    let checked = paint::checkbox(&ui, true, false, Interaction::Disabled, g.radius, g.stroke);
+    assert_eq!(
+        checked.glyph,
+        ui.color(Role::Surface),
+        "A1：SelectedDisabledIconColor = Surface"
+    );
+    // 复审 P2-3：**选中且禁用**的填充是 OnSurface@38%（`SelectedDisabledContainerOpacity`），
+    // 不是普通禁用容器的 12%。两格差一眼就能看出来，所以逐字钉住。
+    let ink38 = interaction::disabled_content_over_role(&ui, Role::OnSurface, false);
+    let container12 = interaction::disabled_colors(&ui, Role::Surface).0;
+    assert_eq!(
+        checked.frame.fill,
+        Some(ink38),
+        "A1：SelectedDisabledContainerOpacity = 0.38"
+    );
+    assert_ne!(
+        checked.frame.fill,
+        Some(container12),
+        "选中禁用不是 12% 容器色"
+    );
+    assert_eq!(
+        unchecked.frame.outline,
+        Some(ink38),
+        "同一行里未选中禁用描边与选中禁用填充是同一个 38% 叠色"
+    );
+}
+
+/// §19.4：**选中态 hover/pressed 不换环色**（只有状态层变）。
+#[test]
+fn radio_keeps_primary_on_hover_when_selected() {
+    let ui = ui();
+    let g = ControlGeometry::radio(&ui);
+    let primary = Some(ui.color(Role::Primary));
+    for state in Interaction::ALL {
+        if state.is_disabled() {
+            continue;
+        }
+        let paint = paint::radio(&ui, true, state, g.radius, g.stroke);
+        assert_eq!(
+            paint.ring.outline, primary,
+            "19.4：{state:?} 环仍是 Primary"
+        );
+        assert_eq!(paint.dot, primary, "19.4：{state:?} 点仍是 Primary");
+    }
+    // 未选中：静息 OnSurfaceVariant → hover/focus/pressed 提到 OnSurface
+    let at_rest = paint::radio(&ui, false, Interaction::Enabled, g.radius, g.stroke);
+    assert_eq!(at_rest.dot, None, "未选中不画内点");
+    assert_eq!(at_rest.ring.outline, Some(ui.color(Role::OnSurfaceVariant)));
+    let lifted = paint::radio(&ui, false, Interaction::Hovered, g.radius, g.stroke);
+    assert_eq!(lifted.ring.outline, Some(ui.color(Role::OnSurface)));
+}
+
+/// §10.4 + A1：选中态 hover 的滑块是 `PrimaryContainer`；禁用选中滑块是 `Surface`（不透明度 1）。
+#[test]
+fn switch_handle_roles_follow_the_tokens() {
+    let ui = ui();
+    let at_rest = paint::switch(&ui, true, Interaction::Enabled);
+    assert_eq!(at_rest.track.fill, Some(ui.color(Role::Primary)));
+    assert_eq!(at_rest.thumb, ui.color(Role::OnPrimary));
+    assert_eq!(at_rest.icon, Some(ui.color(Role::OnPrimaryContainer)));
+
+    let hovered = paint::switch(&ui, true, Interaction::Hovered);
+    assert_eq!(
+        hovered.thumb,
+        ui.color(Role::PrimaryContainer),
+        "A1：选中 hover 滑块 PrimaryContainer"
+    );
+    assert_eq!(
+        hovered.track.fill,
+        Some(ui.color(Role::Primary)),
+        "轨道不随 hover 变"
+    );
+
+    let off = paint::switch(&ui, false, Interaction::Enabled);
+    assert_eq!(
+        off.track.outline,
+        Some(ui.color(Role::Outline)),
+        "10.3：未选中 2px Outline"
+    );
+    assert_eq!(off.track.stroke, 2.0);
+    assert_eq!(
+        off.thumb,
+        ui.color(Role::Outline),
+        "10.4：未选中滑块 Outline"
+    );
+    assert_eq!(off.icon, None, "未选中态图标与轨道同色（不画）");
+
+    let disabled = paint::switch(&ui, true, Interaction::Disabled);
+    assert_eq!(
+        disabled.thumb,
+        ui.color(Role::Surface),
+        "A1：DisabledSelectedHandleColor=Surface"
+    );
+}
+
+/// §13.5 / §13.6 / §13.7：选中态**无描边**、Assist 不可选中、禁用文字 @38%。
+#[test]
+fn chip_roles_follow_the_tokens() {
+    let ui = ui();
+    let radius = ChipGeometry::of(&ui).radius;
+
+    let selected = paint::chip(&ui, ChipVariant::Filter, true, Interaction::Enabled, radius);
+    assert_eq!(
+        selected.frame.fill,
+        Some(ui.color(Role::SecondaryContainer))
+    );
+    assert_eq!(selected.frame.outline, None, "13.5：选中描边 0dp");
+    assert_eq!(selected.label, ui.color(Role::OnSecondaryContainer));
+
+    let unselected = paint::chip(
+        &ui,
+        ChipVariant::Filter,
+        false,
+        Interaction::Enabled,
+        radius,
+    );
+    assert_eq!(
+        unselected.frame.outline,
+        Some(ui.color(Role::OutlineVariant))
+    );
+    assert_eq!(unselected.label, ui.color(Role::OnSurfaceVariant));
+
+    // Assist 没有选中态：即使传 selected = true 也不会变 SecondaryContainer
+    let assist = paint::chip(&ui, ChipVariant::Assist, true, Interaction::Enabled, radius);
+    assert_ne!(assist.frame.fill, Some(ui.color(Role::SecondaryContainer)));
+    assert_eq!(
+        assist.icon,
+        ui.color(Role::Primary),
+        "13.4：Assist 前置图标 Primary"
+    );
+
+    let disabled = paint::chip(
+        &ui,
+        ChipVariant::Filter,
+        false,
+        Interaction::Disabled,
+        radius,
+    );
+    assert_ne!(disabled.label, unselected.label, "13.7：禁用文字降到 38%");
+}
+
+/// 状态层只在三态存在，且**不是**满档角色色（α 由 `interaction` 给）。
+#[test]
+fn state_layer_only_exists_on_lifted_states() {
+    let ui = ui();
+    for (state, expected) in [
+        (Interaction::Enabled, false),
+        (Interaction::Hovered, true),
+        (Interaction::Focused, true),
+        (Interaction::Pressed, true),
+        (Interaction::Disabled, false),
+    ] {
+        let layer = paint::state_layer(&ui, state, Role::OnSurfaceVariant);
+        assert_eq!(layer.is_some(), expected, "{state:?} 的状态层有无");
+        if let Some(color) = layer {
+            assert_eq!(color.a, 1.0, "状态层必须是实色（D27：CPU/GPU 一致）");
+        }
+    }
+    // 同态下 hover 比 pressed 浅（8% < 10%）
+    let hover = paint::state_layer(&ui, Interaction::Hovered, Role::OnSurface).unwrap();
+    let pressed = paint::state_layer(&ui, Interaction::Pressed, Role::OnSurface).unwrap();
+    assert_ne!(hover, pressed);
+}
diff --git a/crates/app-iced/src/fonts.rs b/crates/app-iced/src/fonts.rs
new file mode 100644
index 0000000..74c5b5e
--- /dev/null
+++ b/crates/app-iced/src/fonts.rs
@@ -0,0 +1,302 @@
+//! 字体基座（D28 前半）：把令牌的字体栈求值成「本机真的有的族名」，并打一行启动日志。
+//!
+//! ## 做什么
+//!
+//! 1. 取 `Platform::current()` 的三条栈（Display / Text / Mono，见 `unlucky_design::typography`）；
+//! 2. 用 iced 的**全局字体系统**（`iced_graphics::text::font_system()`，即 cosmic-text 的
+//!    `FontSystem`，首次调用会扫系统字体）核对每个族名是否装机 → 取栈里第一个装机可用的族；
+//! 3. 给出 400/500/700 三档字重的落点（原生 / 最近档 / 合成加粗）：
+//!    **先查系统里这个族真实提供的字面（fontdb 的 `FaceInfo.weight`）**，查不到才回落到令牌的
+//!    纯函数 `Platform::resolve_weight`。缺档按降级记录。
+//!
+//! ## 为什么要真查系统
+//!
+//! 令牌栈写的是「Win11 有 Segoe UI Variable Text」，但 Win10 / Server 只有 `Segoe UI`（静态
+//! 300/400/600/700，**没有 500**），干净安装的 Linux 可能一个都没有。只按栈头写死族名会把
+//! 「实际使用哪个族、哪一档字重」变成猜测——本 mission 的开发机就是 Windows Server 2025，
+//! 实测就回退到了经典 `Segoe UI`（见交接文档的启动日志）。
+
+//! ## 不做什么
+//!
+//! **中文字体 CDN 下载不在这里**（后续 mission）。本模块只做「系统字体优先」这一半，
+//! 也没有能力判断 CJK 字形覆盖（那是 `ttf-parser` 查 cmap 的活，M60 Q3 的 spike 做过）。
+//!
+//! ## 中文那一半（M92 / D28 后半）
+//!
+//! 语言探测 + 「中文环境有没有中文字体」的判据在 [`cjk`]（判据本体在零依赖的 `unlucky_i18n::font`），
+//! 语言的真值源是 [`crate::platform::locale`]（Windows 上 `reg.exe` 读注册表，零 FFI），
+//! 结论作为 [`Resolved::cjk`] 进同一行启动日志。**英文环境结论恒为 `NotNeeded`**：不要求中文字体、
+//! 不下载任何字体（系统里已有的 CJK 族照旧躺在 iced 的字体库里，我们既不注册新的也删不掉——那是
+//! cosmic-text 的全局状态，不是本模块能管的事）。
+
+mod cjk;
+
+use cjk::CjkReport;
+use unlucky_design::typography::{FontFamily, Platform, Weight, WeightMatch};
+
+use crate::theme::Families;
+
+/// 一条栈的求值结果。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct FamilyReport {
+    /// 栈的用途（`text` / `display` / `mono`）。
+    pub stack: &'static str,
+    /// 实际选中的族名（栈里第一个装机可用的；都没装就是栈头）。
+    pub family: &'static str,
+    /// 选中的族是否真的在系统字体库里。
+    pub installed: bool,
+}
+
+/// 一档字重的求值结果。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct WeightReport {
+    /// 请求的字重（400/500/700）。
+    pub requested: u16,
+    /// 实际可用的字重（降级后）。
+    pub available: u16,
+    /// 匹配质量（原生 / 最近档 / 合成加粗）。
+    pub quality: WeightMatch,
+}
+
+/// 字体求值的全部结论（启动日志与测试都用它）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Resolved {
+    /// 平台（决定栈与字重覆盖表）。
+    pub platform: Platform,
+    /// 三条栈的落点。
+    pub families: [FamilyReport; 3],
+    /// 三档字重的落点（对**正文**栈求值）。
+    pub weights: [WeightReport; 3],
+    /// 语言 + 中文环境的中文字体策略（D28；英文环境恒为 `NotNeeded`）。
+    pub cjk: CjkReport,
+}
+
+impl Resolved {
+    /// 把结论塞回主题适配层要的形状。
+    pub fn families(&self) -> Families {
+        Families {
+            text: self.families[0].family,
+            display: self.families[1].family,
+            mono: self.families[2].family,
+        }
+    }
+
+    /// 是否有任何一档走了「合成加粗」（= 观感降级，要记日志）。
+    pub fn has_synthetic(&self) -> bool {
+        self.weights
+            .iter()
+            .any(|weight| weight.quality == WeightMatch::Synthetic)
+    }
+
+    /// 启动日志（**一行**：族 / 字重 / 语言与中文字体策略）。
+    pub fn describe(&self) -> String {
+        let families = self
+            .families
+            .iter()
+            .map(|report| {
+                format!(
+                    "{}={:?}{}",
+                    report.stack,
+                    report.family,
+                    if report.installed {
+                        ""
+                    } else {
+                        "(未装机→回落)"
+                    }
+                )
+            })
+            .collect::<Vec<_>>()
+            .join(" ");
+
+        let weights = self
+            .weights
+            .iter()
+            .map(|report| {
+                let quality = match report.quality {
+                    WeightMatch::Native => "native",
+                    WeightMatch::Nearest => "nearest",
+                    WeightMatch::Synthetic => "synthetic",
+                };
+                format!("w{}={}({quality})", report.requested, report.available)
+            })
+            .collect::<Vec<_>>()
+            .join(" ");
+
+        format!(
+            "[font] platform={} {families} | weights {weights} | {}",
+            self.platform.name(),
+            self.cjk.describe()
+        )
+    }
+}
+
+/// 求值本机字体（会触发 iced 全局字体系统的首次初始化，约 0.1~0.8s）。
+///
+/// 中文那一级按**系统 locale** 判：启动编排（`app/boot.rs`）这一拍还没有配置读取点。真正的
+/// `ui.language` 在 [`crate::app::state`] 构造 `App` 时读到，随后用 [`cjk_for`] 重算一次并打
+/// 日志——所以「英文系统上手动切中文」不会停在 `NotNeeded`（见 [`cjk_for`]）。
+pub fn resolve() -> Resolved {
+    resolve_with(None)
+}
+
+/// 同 [`resolve`]，但把配置里 `ui.language` 的显式值喂给中文策略（D28 的第一级）。
+pub fn resolve_with(setting: Option<&str>) -> Resolved {
+    let platform = Platform::current();
+    let faces = system_faces();
+
+    let is_installed = |family: &str| -> bool {
+        faces
+            .as_ref()
+            .is_none_or(|faces: &Vec<Face>| faces.iter().any(|face| face.family == family))
+    };
+
+    let families = [
+        FamilyReport {
+            stack: "text",
+            family: pick(platform, FontFamily::Text, &is_installed),
+            installed: is_installed(pick(platform, FontFamily::Text, &is_installed)),
+        },
+        FamilyReport {
+            stack: "display",
+            family: pick(platform, FontFamily::Display, &is_installed),
+            installed: is_installed(pick(platform, FontFamily::Display, &is_installed)),
+        },
+        FamilyReport {
+            stack: "mono",
+            family: pick(platform, FontFamily::Mono, &is_installed),
+            installed: is_installed(pick(platform, FontFamily::Mono, &is_installed)),
+        },
+    ];
+
+    // 字重：**优先用系统里这个族真实提供的档位**（令牌表的 `WeightCoverage` 是「这个族通常有哪几档」，
+    // 装机版可能是静态子集：Win Server / 精简版只有经典 Segoe UI，没有 500）。查不到才回落到令牌纯函数。
+    let weights = [Weight::Regular, Weight::Medium, Weight::Bold]
+        .map(|weight| weight_report(platform, families[0].family, weight, faces.as_deref()));
+
+    // D28 后半：语言 + 中文环境的中文字体策略。`faces` 的 `None` 在这里是「字体库读不出来」，
+    // 适配层会把它翻成 `Unprobeable` 而不是「缺字体」（否则会误触发一次 CDN 下载）。
+    let cjk_report = cjk::probe_with(setting, faces.as_deref());
+
+    Resolved {
+        platform,
+        families,
+        weights,
+        cjk: cjk_report,
+    }
+}
+
+/// 语言切换后的中文策略重算（M106）：`setting` 是配置里 `ui.language` 的**显式值**
+/// （`None` = 跟随系统，由 [`crate::platform::locale::SystemLocale`] 决定）。
+///
+/// 为什么需要它：启动那一轮（[`resolve`]）拿不到配置，只按系统 locale 判。用户在英文系统上
+/// 手选「简体中文」时，若不复算，策略会停在 `NotNeeded`——界面文字是中文、字体却没有中文字形，
+/// 那就是白块。复算出的 `NeedsDownload` 是 D28 的**信号**（下载器仍是 `Source::PendingPin`，
+/// 见 `unlucky_i18n::font`），本 crate 只负责把它打进日志、不让它静默。
+pub fn cjk_for(setting: Option<&str>) -> CjkReport {
+    cjk::probe_with(setting, system_faces().as_deref())
+}
+
+/// 一条系统字面（族名 + 字重）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct Face {
+    family: String,
+    weight: u16,
+}
+
+/// 某档字重的落点：先问系统，再问令牌。
+fn weight_report(
+    platform: Platform,
+    family: &str,
+    weight: Weight,
+    faces: Option<&[Face]>,
+) -> WeightReport {
+    let requested = weight.value();
+
+    let available = faces.and_then(|faces| {
+        let mut weights = faces
+            .iter()
+            .filter(|face| face.family == family)
+            .map(|face| face.weight)
+            .collect::<Vec<_>>();
+        weights.sort_unstable();
+        weights.dedup();
+        if weights.is_empty() {
+            return None;
+        }
+
+        Some(
+            weights
+                .iter()
+                .copied()
+                .min_by_key(|candidate| candidate.abs_diff(requested))
+                .unwrap_or(requested),
+        )
+    });
+
+    match available {
+        Some(available) => WeightReport {
+            requested,
+            available,
+            quality: quality_of(requested, available),
+        },
+        None => {
+            let choice = platform.resolve_weight(FontFamily::Text, weight);
+            WeightReport {
+                requested: choice.requested,
+                available: choice.available,
+                quality: choice.quality,
+            }
+        }
+    }
+}
+
+/// 与令牌层同一判据：原生 / 最近档（差 <200）/ 合成加粗（差 ≥200）。
+fn quality_of(requested: u16, available: u16) -> WeightMatch {
+    match available.abs_diff(requested) {
+        0 => WeightMatch::Native,
+        delta if delta >= 200 => WeightMatch::Synthetic,
+        _ => WeightMatch::Nearest,
+    }
+}
+
+/// 在栈里选第一个**装机可用**的族（跳过 `sans-serif` 这类通用族名）。
+///
+/// 一个都没装上时返回栈头：让 cosmic-text 自己去回退，比我们猜一个更靠谱。
+pub fn pick(
+    platform: Platform,
+    stack: FontFamily,
+    is_installed: &dyn Fn(&str) -> bool,
+) -> &'static str {
+    let faces = platform.font_stack(stack);
+
+    faces
+        .iter()
+        .find(|face| !is_generic(face.family) && is_installed(face.family))
+        .map_or(faces[0].family, |face| face.family)
+}
+
+/// 通用族名（CSS 关键字，不是真族名）。
+fn is_generic(family: &str) -> bool {
+    matches!(family, "sans-serif" | "serif" | "monospace" | "cursive")
+}
+
+/// 系统字体库里的全部字面（`None` = 拿不到，视为「不知道」，全部当装机）。
+fn system_faces() -> Option<Vec<Face>> {
+    let lock = iced::advanced::graphics::text::font_system();
+    let mut font_system = lock.write().ok()?;
+
+    let mut faces = Vec::new();
+    for face in font_system.raw().db().faces() {
+        for (family, _) in &face.families {
+            faces.push(Face {
+                family: family.clone(),
+                weight: face.weight.0,
+            });
+        }
+    }
+
+    Some(faces)
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/app-iced/src/fonts/cjk.rs b/crates/app-iced/src/fonts/cjk.rs
new file mode 100644
index 0000000..346f6f4
--- /dev/null
+++ b/crates/app-iced/src/fonts/cjk.rs
@@ -0,0 +1,188 @@
+//! 中文环境的 CJK 字体探测（D28 后半）：把 iced 系统字体库里的族名喂给 `unlucky_i18n::font::decide`。
+//!
+//! ## 分工
+//!
+//! - **判据**（要不要中文字体、哪些族算候选、缺了要不要下载）全在 `unlucky_i18n::font`，是纯函数，
+//!   零 UI 依赖、脱机可测；
+//! - **语言**从 [`unlucky_i18n::lang::resolve`] 拿：`ui.language` 显式值 > [`SystemLocale`]
+//!   （Windows 读注册表，零 FFI）> 环境变量 > 英文；
+//! - **本模块只做适配**：把 [`super::Face`] 列表变成一个「某族装没装」的查询，并处理
+//!   **读不到字体库**这种情况。
+//!
+//! ## 为什么「读不到」不等于「需下载」
+//!
+//! `system_faces()` 拿不到字体库时返回 `None`。把它当成「没有中文字体」会直接触发一次 CDN 下载
+//! （D28 的自动下载路径），而真相是**我们不知道**。所以这一路走 [`Strategy::Unprobeable`]：
+//! 日志里留痕，不下载、不弹提示。
+//!
+//! ## 诚实边界（抓得住什么 / 抓不住什么）
+//!
+//! - **抓得住**：语言 + 字体库族名 → 策略（含 `Unprobeable` 这一支）；优先级顺序（注入的假源可测）；
+//! - **抓不住**：①族名存在 ≠ 字形覆盖（`SimSun` 也可能是个残缺子集）。真判据要开 `ttf-parser`
+//!   查 cmap，本 mission 不引依赖（M60 Q3 spike 做过，结论见 `DevDocs`）；
+//!   ②下载与注册（`Strategy::NeedsDownload` 只是信号，`Source::PendingPin` 还没钉 URL/哈希）。
+//!
+//! ## `ui.language` 的接线（M106）
+//!
+//! 启动编排（`app/boot.rs`）那一拍只按系统 locale 判（`fonts::resolve` → `probe_with(None, ..)`）；真正的
+//! `ui.language` 在 `App` 构造/切语言时读到，随后走 `fonts::cjk_for(setting)` 复算一次并打日志。
+//! 所以「英文系统上手动切中文」也会得到 `needs-download` 而不是 `not-needed`——白块那条路被堵住了。
+
+use unlucky_i18n::font::{self, Strategy};
+use unlucky_i18n::lang::{self, Detection, EnvLocale};
+
+use super::Face;
+use crate::platform::locale::SystemLocale;
+
+/// 一次中文探测的结论（启动日志的第二段）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CjkReport {
+    /// 语言探测（含原始 locale 与来源，便于解释「为什么是英文」）。
+    pub detection: Detection,
+    /// 字体策略结论。
+    pub strategy: Strategy,
+}
+
+impl CjkReport {
+    /// 一行日志片段（`lang=zh-CN locale=zh-CN source=registry cjk=system:"Microsoft YaHei"`）。
+    pub fn describe(&self) -> String {
+        format!("{} {}", self.detection.describe(), self.strategy.describe())
+    }
+}
+
+/// 用给定语言 + 字体库内容做判定。
+///
+/// `faces` 为 `None` = 字体库读不出来（→ [`Strategy::Unprobeable`]，**不是**「需下载」）。
+pub fn report(detection: Detection, faces: Option<&[Face]>) -> CjkReport {
+    let strategy = faces.map_or(Strategy::Unprobeable, |faces| {
+        let is_installed = |family: &str| faces.iter().any(|face| face.family == family);
+        font::decide(detection.lang, &is_installed)
+    });
+
+    CjkReport {
+        detection,
+        strategy,
+    }
+}
+
+/// 探测本机：优先级见 [`unlucky_i18n::lang::resolve`]。
+///
+/// `setting` 是配置里 `ui.language` 的原文（`zh_cn` / `en_us`）；`None` = **配置里没写过这个键**
+/// （= 跟随系统，不是「没读」）。注意 `None` 与 `Some("不认识的值")` 效果相同：都不当显式选择，
+/// 继续往下走。
+pub fn probe_with(setting: Option<&str>, faces: Option<&[Face]>) -> CjkReport {
+    report(lang::resolve(setting, &SystemLocale, &EnvLocale), faces)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn faces(families: &[&str]) -> Vec<Face> {
+        families
+            .iter()
+            .map(|family| Face {
+                family: (*family).to_owned(),
+                weight: 400,
+            })
+            .collect()
+    }
+
+    fn zh() -> Detection {
+        Detection {
+            lang: unlucky_i18n::Lang::ZhCn,
+            raw: Some("zh-CN".to_owned()),
+            origin: "injected",
+        }
+    }
+
+    fn en() -> Detection {
+        Detection {
+            lang: unlucky_i18n::Lang::En,
+            raw: Some("en-US".to_owned()),
+            origin: "injected",
+        }
+    }
+
+    #[test]
+    fn chinese_host_with_a_cjk_font_uses_the_system_one() {
+        // 抓得住：适配层把字体库查反/查漏（例如只按第一个族判断、或把 `Segoe UI` 当候选）。
+        // 抓不住：这台机器实测有没有这个族（测试用的是注入的假字面表）。
+        let installed = faces(&["Segoe UI", "Microsoft YaHei", "Cascadia Mono"]);
+        let report = report(zh(), Some(&installed));
+        assert_eq!(
+            report.strategy,
+            Strategy::System {
+                family: "Microsoft YaHei"
+            }
+        );
+        assert_eq!(
+            report.describe(),
+            "lang=zh-CN locale=zh-CN source=injected cjk=system:\"Microsoft YaHei\""
+        );
+    }
+
+    #[test]
+    fn chinese_host_without_cjk_fonts_gets_the_download_signal() {
+        // 抓得住：D28 的「中文环境扫不到 → 要下载」这条路（信号必须能被日志看出来）。
+        // 抓不住：信号之后的下载与提示（本 mission 不联网，页面也没接）。
+        let latin_only = faces(&["Segoe UI", "Roboto"]);
+        let report = report(zh(), Some(&latin_only));
+        assert_eq!(
+            report.strategy,
+            Strategy::NeedsDownload(&unlucky_i18n::font::NOTO_SANS_SC)
+        );
+        assert!(report
+            .describe()
+            .contains("cjk=needs-download(Noto Sans SC)"));
+    }
+
+    #[test]
+    fn english_host_never_asks_for_a_chinese_font() {
+        // 抓得住：英文环境的「零字体负担」（D28）——系统里有没有中文字体都不影响结论。
+        // 抓不住：程序真的没去读那些字体文件（那是 iced/cosmic-text 的加载行为）。
+        assert_eq!(report(en(), Some(&[])).strategy, Strategy::NotNeeded);
+        assert_eq!(
+            report(en(), Some(&faces(&["Microsoft YaHei"]))).strategy,
+            Strategy::NotNeeded
+        );
+    }
+
+    #[test]
+    fn unreadable_font_database_is_unknown_not_missing() {
+        // 抓得住：把「读不到字体库」错判成「缺字体」——那会在探测失败时触发一次多余的 CDN 下载。
+        // 抓不住：真的读不到字体库时的运行行为（那条路径要 poisoned lock，测试造不出来）。
+        let report = report(zh(), None);
+        assert_eq!(report.strategy, Strategy::Unprobeable);
+        assert!(
+            report.describe().ends_with("cjk=unprobeable"),
+            "{}",
+            report.describe()
+        );
+    }
+
+    #[test]
+    fn explicit_setting_overrides_the_platform_source() {
+        // 抓得住：`ui.language` 显式值被平台源盖掉（用户手选中文/英文必须赢过系统语言）；
+        // 也让「平台源真的接在链路上」有个不依赖本机语言的证据。
+        // 抓不住：`ui.language` 在真机上读到什么（那一级由 `App` 读配置后经 `fonts::cjk_for` 喂进来）。
+        let installed = faces(&["Microsoft YaHei"]);
+
+        let forced_english = probe_with(Some("en_us"), Some(&installed));
+        assert_eq!(forced_english.detection.lang, unlucky_i18n::Lang::En);
+        assert_eq!(
+            forced_english.detection.origin,
+            unlucky_i18n::lang::ORIGIN_SETTING
+        );
+        assert_eq!(forced_english.strategy, Strategy::NotNeeded);
+
+        let forced_chinese = probe_with(Some("zh_cn"), Some(&installed));
+        assert_eq!(
+            forced_chinese.strategy,
+            Strategy::System {
+                family: "Microsoft YaHei"
+            }
+        );
+        assert!(forced_chinese.describe().contains("source=setting"));
+    }
+}
diff --git a/crates/app-iced/src/fonts/tests.rs b/crates/app-iced/src/fonts/tests.rs
new file mode 100644
index 0000000..5616c58
--- /dev/null
+++ b/crates/app-iced/src/fonts/tests.rs
@@ -0,0 +1,175 @@
+//! `fonts` 的单元测试（拆出来只为「src 文件 ≤400 行」的门禁）。
+
+use super::cjk::CjkReport;
+use super::*;
+use unlucky_design::typography::WeightCoverage;
+use unlucky_i18n::font::Strategy;
+use unlucky_i18n::lang::Detection;
+
+fn only(installed: &'static [&'static str]) -> impl Fn(&str) -> bool {
+    move |family| installed.contains(&family)
+}
+
+#[test]
+fn windows_stack_falls_back_to_classic_segoe_when_variable_is_absent() {
+    // Win10 没有 Segoe UI Variable Text
+    let family = pick(
+        Platform::Windows,
+        FontFamily::Text,
+        &only(&["Segoe UI", "Microsoft YaHei UI"]),
+    );
+    assert_eq!(family, "Segoe UI");
+}
+
+#[test]
+fn windows_stack_prefers_the_variable_face_on_win11() {
+    let family = pick(
+        Platform::Windows,
+        FontFamily::Text,
+        &only(&["Segoe UI Variable Text", "Segoe UI"]),
+    );
+    assert_eq!(family, "Segoe UI Variable Text");
+}
+
+#[test]
+fn generic_family_names_are_never_reported_as_the_resolved_family() {
+    // 一个都没装：返回栈头，且栈头不是通用族名
+    let family = pick(Platform::Linux, FontFamily::Text, &only(&[]));
+    assert_eq!(family, "Roboto");
+    assert!(!is_generic(family));
+}
+
+#[test]
+fn missing_cjk_fonts_do_not_change_the_latin_pick() {
+    // 装了苹方但没装 SF：macOS 栈应该选 Helvetica Neue 而不是中文族
+    let family = pick(
+        Platform::MacOs,
+        FontFamily::Text,
+        &only(&["PingFang SC", "Helvetica Neue"]),
+    );
+    assert_eq!(family, "Helvetica Neue");
+}
+
+#[test]
+fn weight_reports_use_the_token_degradation_path() {
+    // 没有系统字面表时回落到令牌纯函数：Windows 栈里 Segoe UI Variable Text 是可变 300..700
+    let medium = weight_report(
+        Platform::Windows,
+        "Segoe UI Variable Text",
+        Weight::Medium,
+        None,
+    );
+    assert_eq!(medium.requested, 500);
+    assert_eq!(medium.quality, WeightMatch::Native);
+
+    // 手工构造一个「只有 400/700」的族（= 经典 Segoe UI），500 应该落到最近档
+    let faces = [
+        Face {
+            family: "Segoe UI".to_owned(),
+            weight: 400,
+        },
+        Face {
+            family: "Segoe UI".to_owned(),
+            weight: 700,
+        },
+    ];
+    let medium = weight_report(Platform::Windows, "Segoe UI", Weight::Medium, Some(&faces));
+    assert_eq!(medium.available, 400, "400 比 700 更近");
+    assert_eq!(medium.quality, WeightMatch::Nearest);
+
+    // 只有 400 却要 700 → 合成加粗
+    let only_regular = [Face {
+        family: "Narrow".to_owned(),
+        weight: 400,
+    }];
+    let bold = weight_report(
+        Platform::Windows,
+        "Narrow",
+        Weight::Bold,
+        Some(&only_regular),
+    );
+    assert_eq!(bold.quality, WeightMatch::Synthetic);
+
+    // 原生有 500 就用 500
+    let has_medium = [Face {
+        family: "Noto".to_owned(),
+        weight: 500,
+    }];
+    assert_eq!(
+        weight_report(Platform::Linux, "Noto", Weight::Medium, Some(&has_medium)).quality,
+        WeightMatch::Native
+    );
+
+    let narrow = WeightCoverage::Static(&[400]);
+    assert_eq!(narrow.nearest(700), 400);
+}
+
+#[test]
+fn describe_is_one_line_and_mentions_all_three_stacks() {
+    let resolved = Resolved {
+        platform: Platform::Windows,
+        families: [
+            FamilyReport {
+                stack: "text",
+                family: "Segoe UI",
+                installed: true,
+            },
+            FamilyReport {
+                stack: "display",
+                family: "Segoe UI Variable Display",
+                installed: false,
+            },
+            FamilyReport {
+                stack: "mono",
+                family: "Cascadia Mono",
+                installed: true,
+            },
+        ],
+        weights: [
+            WeightReport {
+                requested: 400,
+                available: 400,
+                quality: WeightMatch::Native,
+            },
+            WeightReport {
+                requested: 500,
+                available: 400,
+                quality: WeightMatch::Nearest,
+            },
+            WeightReport {
+                requested: 700,
+                available: 400,
+                quality: WeightMatch::Synthetic,
+            },
+        ],
+        cjk: CjkReport {
+            detection: Detection {
+                lang: unlucky_i18n::Lang::En,
+                raw: None,
+                origin: unlucky_i18n::lang::ORIGIN_DEFAULT,
+            },
+            strategy: Strategy::NotNeeded,
+        },
+    };
+
+    let line = resolved.describe();
+    assert_eq!(line.lines().count(), 1);
+    assert!(line.contains("text=\"Segoe UI\""), "{line}");
+    assert!(line.contains("未装机"), "{line}");
+    assert!(line.contains("w700=400(synthetic)"), "{line}");
+    assert!(line.contains("cjk=not-needed"), "英文环境要进日志：{line}");
+    assert!(resolved.has_synthetic());
+    assert_eq!(resolved.families().text, "Segoe UI");
+}
+
+#[test]
+fn type_roles_pick_the_display_stack_for_big_text() {
+    use unlucky_design::typography::TypeRole;
+
+    assert_eq!(
+        TypeRole::TitleLarge.style().family,
+        FontFamily::Display,
+        "22px 标题走 Display 栈"
+    );
+    assert_eq!(TypeRole::BodyMedium.style().family, FontFamily::Text);
+}
diff --git a/crates/app-iced/src/icons.rs b/crates/app-iced/src/icons.rs
new file mode 100644
index 0000000..b431060
--- /dev/null
+++ b/crates/app-iced/src/icons.rs
@@ -0,0 +1,400 @@
+//! 令牌图标（`unlucky_design::icons` 的 24 网格 SVG path）→ iced `svg` 控件。
+//!
+//! ## 为什么走 SVG 而不是自绘 canvas
+//!
+//! 令牌里存的是 **SVG path 字符串**（含 `A` 弧线命令），自绘要自己写 path parser + 弧线细分，
+//! 那是一份将来只有自己在维护的代码；iced 的 `svg` 控件已经带 usvg 解析与按 id 缓存的位图。
+//! 代价是二进制多一份 resvg/usvg（体积基线里会单列出来）。
+//!
+//! ## 描边语义（`design-令牌约定.md` §4）
+//!
+//! 令牌的 `Icon::stroke_width(render_px)` 已经把「视觉 1.5px」折算成 **viewBox 单位**
+//! （`1.5 × 24 / render_px`），本模块**不重算也不手抄常数**。
+//!
+//! ## ⚠️ 渲染尺寸**不是**一个全局值（M86 收口）
+//!
+//! **盒子多宽就按多宽烘焙**，规则只有两条：
+//!
+//! | 盒尺寸 | 用哪个入口 |
+//! |---|---|
+//! | **等于** [`RENDER_PX`]（24） | [`view`]（导航、卡片头、表单、IconButton…） |
+//! | **不等于** 24（按钮 18 / chip 18 / switch 滑块 16 / 标题栏 caption 20） | **[`view_at`]（必须）** |
+//!
+//! 尺寸只有一个来源：`unlucky_design::icons` 的令牌（[`IconSize`] /
+//! [`unlucky_design::icons::TITLEBAR_CAPTION_ICON_PX`]）——本文件里不许出现 `18.0` / `20.0` / `24.0`
+//! 这类字面量，也不许把某个组件的尺寸「凑」进 [`RENDER_PX`]。
+//!
+//! **为什么必须按盒烘焙**：`stroke-width` 是 viewBox 单位，同一个 viewBox 线宽在更小的盒子里
+//! 视觉更细。把 24px 烘焙的位图塞进 18px 盒子，视觉线宽会从 1.5px 掉到 **1.125px**
+//! （复审 r1 实测 1.04~1.25px，而同屏 caption 的 20px 走 [`view_at`] 实测正好 1.50px）。
+//! 所以：**每个用到的尺寸各缓存一份**，缓存键是 `(图标种类, 渲染尺寸)`——但「缓存支持多尺寸」
+//! 不等于「调用点都用上了」，**不等于 24 的盒子一律走 [`view_at`]** 才是这条的落点。
+
+use std::collections::HashMap;
+use std::sync::{Mutex, OnceLock};
+
+use iced::widget::svg;
+use iced::Color;
+
+use unlucky_design::icons::{IconKind, IconPaint, IconSize};
+
+/// 图标缓存键里的尺寸精度（px × 100 取整），避免拿 f32 做哈希键。
+const PX_KEY_SCALE: f32 = 100.0;
+
+/// 骨架期图标的默认渲染尺寸（12b：标题栏与导航轨都是 24；`SmallIconButtonTokens.IconSize = 24`）。
+pub const RENDER_PX: f32 = IconSize::Toolbar.px();
+
+/// 标题栏 caption 三键（最小化 / 最大化 / 关闭）的图标边长。
+///
+/// **项目偏离**（用户点名）：官方 `SmallIconButtonTokens.IconSize = 24`，这里 20；容器 46×48 不动。
+/// 值只在令牌层定义一次（`unlucky_design::icons::TITLEBAR_CAPTION_ICON_PX`），本文件只是转口。
+pub const CAPTION_PX: f32 = unlucky_design::icons::TITLEBAR_CAPTION_ICON_PX;
+
+/// 生成一个图标的 SVG 源码（`viewBox` 24×24，颜色用 `currentColor` 交给 iced 的色滤镜）。
+///
+/// 之所以用 `currentColor` 而不是把令牌色写进 SVG：色滤镜（`svg::Style::color`）会按
+/// **alpha 蒙版**重涂 RGB，这样一份 SVG 位图能被浅/深两套主题复用，缓存不会翻倍。
+///
+/// `render_px` 决定两件事：SVG 的 `width`/`height` 属性与 `stroke-width` 的 viewBox 折算，
+/// 两者必须同源，否则线宽会被二次缩放（见模块文档最后一段）。
+pub fn source(kind: IconKind, render_px: f32) -> String {
+    let icon = kind.icon();
+    let paint = match icon.paint {
+        IconPaint::Stroke => format!(
+            "fill=\"none\" stroke=\"currentColor\" stroke-width=\"{}\" \
+             stroke-linecap=\"round\" stroke-linejoin=\"round\"",
+            icon.stroke_width(render_px)
+        ),
+        IconPaint::Fill => "fill=\"currentColor\" stroke=\"none\"".to_owned(),
+    };
+
+    format!(
+        "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"{0}\" height=\"{0}\" \
+         viewBox=\"0 0 24 24\"><path d=\"{1}\" {paint}/></svg>",
+        render_px, icon.path
+    )
+}
+
+/// 图标的 SVG 句柄（按 `(种类, 渲染尺寸)` 缓存；句柄 id 是内容哈希，所以 iced 侧也能命中缓存）。
+fn handle(kind: IconKind, render_px: f32) -> svg::Handle {
+    static HANDLES: OnceLock<Mutex<HashMap<(IconKind, u32), svg::Handle>>> = OnceLock::new();
+
+    // 依赖「枚举下标 == IconKind::ALL 下标」（令牌层用 `GLYPHS[self as usize]` 同一约定）。
+    // 这条断言把约定钉在测试与 debug 构建里，`IconKind` 一旦乱序插入就会立刻炸。
+    debug_assert_eq!(
+        IconKind::ALL[kind as usize],
+        kind,
+        "IconKind::ALL 必须与枚举声明顺序一致"
+    );
+
+    let key = (kind, (render_px * PX_KEY_SCALE).round() as u32);
+    let cache = HANDLES.get_or_init(|| Mutex::new(HashMap::new()));
+    let mut cache = cache
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner());
+    cache
+        .entry(key)
+        .or_insert_with(|| svg::Handle::from_memory(source(kind, render_px).into_bytes()))
+        .clone()
+}
+
+/// 一个图标控件：按**令牌默认尺寸**（[`RENDER_PX`]）渲染，颜色走令牌角色。
+pub fn view<'a, Message: 'a>(kind: IconKind, color: Color) -> iced::Element<'a, Message> {
+    view_at(kind, color, RENDER_PX)
+}
+
+/// 一个图标控件：按调用方给的**令牌尺寸**渲染（`render_px` 必须来自 `unlucky_design::icons`）。
+///
+/// 只有需要「组件自己的图标尺寸不同」时才用这个入口（目前只有标题栏 caption 三键）。
+/// 别为了摆一个位置而拿它调字面量：位置交给布局（`layout::fixed` / `centered_fixed`）。
+pub fn view_at<'a, Message: 'a>(
+    kind: IconKind,
+    color: Color,
+    render_px: f32,
+) -> iced::Element<'a, Message> {
+    svg(handle(kind, render_px))
+        .width(render_px)
+        .height(render_px)
+        .style(move |_theme, _status| svg::Style { color: Some(color) })
+        .into()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn every_icon_produces_wellformed_svg() {
+        for kind in IconKind::ALL {
+            let source = source(kind, RENDER_PX);
+            assert!(source.starts_with("<svg"), "{} 的 SVG 头不对", kind.name());
+            assert!(source.ends_with("</svg>"), "{} 的 SVG 尾不对", kind.name());
+            assert!(source.contains("viewBox=\"0 0 24 24\""), "{}", kind.name());
+            assert!(
+                source.contains(kind.icon().path),
+                "{} 的 path 没写进去",
+                kind.name()
+            );
+            assert!(!source.contains('#'), "{} 里出现了色值字面量", kind.name());
+        }
+    }
+
+    #[test]
+    fn stroke_icons_carry_the_token_stroke_width() {
+        let stroke = source(IconKind::Settings, RENDER_PX);
+        let expected = IconKind::Settings.icon().stroke_width(RENDER_PX);
+        assert!(
+            stroke.contains(&format!("stroke-width=\"{expected}\"")),
+            "{stroke}"
+        );
+        assert!(stroke.contains("stroke-linecap=\"round\""));
+        // 24px 渲染时的视觉线宽必须是 1.5（M54 结论）
+        assert!((expected - 1.5).abs() < f32::EPSILON);
+    }
+
+    /// 默认尺寸**只从令牌取**：谁把 `RENDER_PX` 改成字面量或改成别的档，这条会红。
+    #[test]
+    fn default_render_size_comes_from_the_token() {
+        assert_eq!(
+            RENDER_PX,
+            IconSize::Toolbar.px(),
+            "默认 24 来自 IconSize::Toolbar"
+        );
+        assert_eq!(RENDER_PX, 24.0);
+        assert!(
+            source(IconKind::Close, RENDER_PX).contains("width=\"24\""),
+            "默认渲染尺寸必须是 24"
+        );
+    }
+
+    /// `view_at` 必须**按请求尺寸烘焙**（复审 r1 P1-2/P2-2 的守门断言）。两条路径的差别就是全部意义：
+    /// - **烘焙路径**：`source(kind, 盒)` → SVG `width=盒` + 线宽 `1.5×24/盒` ⇒ 视觉恒 **1.5px**；
+    /// - **缩放路径**（错的那条）：24 烘焙（`stroke-width="1.5"`）塞进 18 盒 ⇒ 视觉 **1.125px**。
+    #[test]
+    fn view_at_bakes_the_requested_size() {
+        // (盒, 该盒应有的 viewBox 线宽, 盒子来源)——caption 20 / 按钮 18 / switch 滑块 16。
+        let cases = [
+            (CAPTION_PX, 1.8, "caption"),
+            (IconSize::Button.px(), 2.0, "按钮"),
+            (IconSize::SwitchThumb.px(), 2.25, "switch 滑块"),
+        ];
+        for (px, stroke, what) in cases {
+            let svg = source(IconKind::Close, px);
+            // `stroke-width` 由 `format!("{}", f32)` 渲染：2.0 会打印成 `2`，所以先比数值再比字符串。
+            let baked = unlucky_design::icons::stroke_width_for(px, 1.5);
+            assert!(
+                (baked - stroke).abs() < 1.0e-6,
+                "{what}：{px}px 盒的 viewBox 线宽应为 {stroke}，实际 {baked}"
+            );
+            assert!(
+                svg.contains(&format!("width=\"{px}\""))
+                    && svg.contains(&format!("stroke-width=\"{baked}\"")),
+                "{what}：svg 必须按 {px} 烘焙：{svg}"
+            );
+            let visual = unlucky_design::icons::visual_stroke_px(px, baked);
+            assert!(
+                (visual - 1.5).abs() < 1.0e-6,
+                "{what}：烘焙路径视觉线宽应为 1.5，实际 {visual}"
+            );
+        }
+
+        // 反证：拿 24 烘焙的那份去填 18 盒（= 用 `view` 装进小盒），视觉只剩 1.125px。
+        let scaled = source(IconKind::Check, RENDER_PX);
+        assert!(scaled.contains("width=\"24\""));
+        let scaled_visual = unlucky_design::icons::visual_stroke_px(IconSize::Button.px(), 1.5);
+        assert!(
+            (scaled_visual - 1.125).abs() < 1.0e-6,
+            "缩放路径只该得到 1.125px（这就是为什么盒 ≠ 24 必须走 view_at）"
+        );
+    }
+
+    #[test]
+    fn filled_icons_do_not_get_a_stroke() {
+        // `more` 是三个填充圆点
+        let filled = source(IconKind::More, RENDER_PX);
+        assert!(filled.contains("fill=\"currentColor\""));
+        assert!(filled.contains("stroke=\"none\""));
+    }
+
+    #[test]
+    fn handles_are_cached_per_kind_and_size() {
+        let first = handle(IconKind::Close, RENDER_PX);
+        let second = handle(IconKind::Close, RENDER_PX);
+        assert_eq!(first.id(), second.id(), "同尺寸同图标必须复用句柄");
+        assert_ne!(first.id(), handle(IconKind::Minimize, RENDER_PX).id());
+        // 同一图标、不同渲染尺寸 = 不同位图（线宽不同），不能共用。
+        assert_ne!(first.id(), handle(IconKind::Close, CAPTION_PX).id());
+    }
+
+    /// **盒 ≠ `RENDER_PX`(24) 的调用点必须走 `view_at`**（复审 r1 P1-1）。判据 = 调用形状匹配 +
+    /// **逐调用点计数**（不做「文件里出现过 view_at 就整文件放行」的短路）：先剥注释，再认
+    /// `icons::view(` / `icons::view::<` / `crate::`·`super::` 前缀 / `use …view as v` 的 `v(`。
+    /// 每个文件的计数必须**等于**白名单期望（未列出 = 0），所以「同文件改对 3 处、漏掉 1 处」也会红。
+    #[test]
+    fn sub_24_boxes_go_through_view_at() {
+        const VIEW: &[(&str, usize)] = &[
+            ("shell/nav.rs", 1),
+            ("shell/nav/account.rs", 1), // M114：轨底头像位
+            ("components/inputs/field.rs", 2),
+            ("components/inputs/menu.rs", 2),
+            ("components/inputs/search.rs", 2),
+            ("components/buttons/mod.rs", 1), // 24 图标 + 40 外壳
+            // 导航族（M79）全是 `IconSize::Toolbar = 24`，`view` 正确；本白名单写于 M79 之前，
+            // 「未列出 = 0」会误判它们。补进来后这几族再出现多余 `view` 仍会红。
+            ("components/navigation/app_bar.rs", 1),
+            ("components/navigation/drawer/item.rs", 1),
+            ("components/navigation/list_item.rs", 2),
+            ("components/navigation/tabs.rs", 1),
+        ];
+        let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src");
+        let mut views = 0usize;
+        let mut bad: Vec<String> = Vec::new();
+        for path in walk_rs(&root) {
+            let rel = path.strip_prefix(&root).expect("strip_prefix");
+            let rel = rel.to_string_lossy().replace('\\', "/");
+            if rel == "icons.rs" {
+                continue; // 实现自身
+            }
+            let code = strip_comments(&std::fs::read_to_string(&path).expect("读组件源码"));
+            let view_alias = icon_view_aliases(&code);
+            let view = count_calls(&code, "view", &view_alias);
+            views += view;
+            let want_view = sites(VIEW, &rel);
+            if view != want_view {
+                bad.push(format!(
+                    "{rel}: {view} 处 `icons::view`，期望 {want_view} —— 盒 ≠ 24 必须 \
+                     `icons::view_at(kind, color, 盒尺寸)`（24 烘焙再缩放只有 ~1.1px 线宽）"
+                ));
+            }
+        }
+        assert!(bad.is_empty(), "图标入口用法违规：\n{}", bad.join("\n"));
+        assert_eq!(views, 14, "`icons::view` 调用点总数变了");
+
+        fn sites(list: &[(&str, usize)], rel: &str) -> usize {
+            list.iter().find(|(p, _)| *p == rel).map_or(0, |(_, n)| *n)
+        }
+        fn walk_rs(dir: &std::path::Path) -> Vec<std::path::PathBuf> {
+            let mut out = Vec::new();
+            for entry in std::fs::read_dir(dir).expect("读目录") {
+                let path = entry.expect("目录项").path();
+                if path.is_dir() {
+                    out.extend(walk_rs(&path));
+                } else if path.extension().is_some_and(|ext| ext == "rs") {
+                    out.push(path);
+                }
+            }
+            out
+        }
+        /// 剥掉 `//` 行注释与 `/* */` 块注释；字符串里的 `//`（URL）不算注释。
+        fn strip_comments(text: &str) -> String {
+            let mut out = String::with_capacity(text.len());
+            let mut it = text.chars().peekable();
+            let (mut line, mut block, mut string) = (false, false, false);
+            while let Some(c) = it.next() {
+                if line {
+                    line = c != '\n';
+                    if c == '\n' {
+                        out.push(c);
+                    }
+                } else if block {
+                    if c == '*' && it.peek() == Some(&'/') {
+                        it.next();
+                        block = false;
+                    }
+                } else if string {
+                    out.push(c);
+                    if c == '\\' {
+                        if let Some(esc) = it.next() {
+                            out.push(esc);
+                        }
+                    } else if c == '"' {
+                        string = false;
+                    }
+                } else if c == '"' {
+                    string = true;
+                    out.push(c);
+                } else if c == '/' && it.peek() == Some(&'/') {
+                    it.next();
+                    line = true;
+                } else if c == '/' && it.peek() == Some(&'*') {
+                    it.next();
+                    block = true;
+                } else {
+                    out.push(c);
+                }
+            }
+            out
+        }
+        /// `use …icons…view …` 里 `view` 的本地名（含 `as` 别名与花括号列表）。
+        fn icon_view_aliases(code: &str) -> Vec<String> {
+            let mut names = Vec::new();
+            for line in code.lines() {
+                let t = line.trim_start();
+                if !t.starts_with("use ") || !t.contains("icons") {
+                    continue;
+                }
+                for (idx, _) in t.match_indices("view") {
+                    let end = idx + 4;
+                    if !word_start(t, idx) || !word_end(t, end) {
+                        continue;
+                    }
+                    let alias = alias_after(t, end).unwrap_or_else(|| "view".to_owned());
+                    if !names.contains(&alias) {
+                        names.push(alias);
+                    }
+                }
+            }
+            names
+        }
+        /// `use …::view as v;` 里的 `v`。
+        fn alias_after(line: &str, from: usize) -> Option<String> {
+            let rest = line[from..].trim_start().strip_prefix("as")?.trim_start();
+            let name: String = rest
+                .chars()
+                .take_while(|c| c.is_alphanumeric() || *c == '_')
+                .collect();
+            (!name.is_empty()).then_some(name)
+        }
+        /// 数调用点：路径形状（`icons::<name>`，含 `crate::`/`super::` 前缀）与别名形状，
+        /// 后面必须紧跟 `(` 或 `::<`。
+        fn count_calls(code: &str, name: &str, aliases: &[String]) -> usize {
+            let mut count = 0;
+            let path = format!("icons::{name}");
+            for (idx, _) in code.match_indices(&path) {
+                if word_start(code, idx) && follows_call(code, idx + path.len()) {
+                    count += 1;
+                }
+            }
+            for alias in aliases {
+                for (idx, _) in code.match_indices(alias.as_str()) {
+                    let end = idx + alias.len();
+                    // `icons::view(` 里的 `view` 已由路径形状数过，别再数一次。
+                    if !(idx >= 7 && code[..idx].ends_with("icons::"))
+                        && word_start(code, idx)
+                        && word_end(code, end)
+                        && follows_call(code, end)
+                    {
+                        count += 1;
+                    }
+                }
+            }
+            count
+        }
+        fn follows_call(code: &str, from: usize) -> bool {
+            let rest = code[from..].trim_start_matches([' ', '\t']);
+            rest.starts_with('(') || rest.starts_with("::<")
+        }
+        fn word_start(code: &str, idx: usize) -> bool {
+            code[..idx]
+                .chars()
+                .next_back()
+                .is_none_or(|c| !(c.is_alphanumeric() || c == '_'))
+        }
+        fn word_end(code: &str, idx: usize) -> bool {
+            code[idx..]
+                .chars()
+                .next()
+                .is_none_or(|c| !(c.is_alphanumeric() || c == '_'))
+        }
+    }
+}
diff --git a/crates/app-iced/src/lib.rs b/crates/app-iced/src/lib.rs
new file mode 100644
index 0000000..2638a5a
--- /dev/null
+++ b/crates/app-iced/src/lib.rs
@@ -0,0 +1,62 @@
+//! # unlucky-app-iced · iced 版桌面壳（P4 / D26）
+//!
+//! 本 crate 是「UI 从头写」的第一步：**只做骨架**（能开窗、颜色/字体对、层级在），
+//! 业务页面、组件库、i18n 全文案、玻璃 shader 都是后续 mission。
+//!
+//! | 模块 | 职责 | 不负责 |
+//! |---|---|---|
+//! | [`theme`] | 令牌（`unlucky-design`）→ iced 类型：`Color` / `Font` / `Radius` / `Theme` | 发明令牌值 |
+//! | `cli` | `--renderer` / `--software-renderer` / `--theme` / `--screenshot*` 参数 | 业务开关 |
+//! | `probe` | 渲染后端探测（D27）+ 写 `ICED_BACKEND`，失败自动降级 CPU | 绘制 |
+//! | `fonts` | 字体栈求值（D28 前半）：平台族名 → 系统字体库校验 → 启动日志 | 中文字体下载 |
+//! | `renderer` | **渲染后端判据表**（M97）+ wgpu 预检 + `log` 桥：什么条件选 wgpu / 什么时候降级 CPU / 日志该长什么样 | 实际绘帧 |
+//! | `app` / `shell` | Elm 三件套 + 自绘标题栏 / 导航轨 / 内容骨架 | 业务逻辑 |
+//! | `shot` | `window::screenshot` → PNG（验收通道） | 图像比对 |
+//! | `icons` | 令牌里的 SVG path → iced `svg` 控件 | 画新图标 |
+//! | [`ui`] | 界面语言的入口层（M106）：`LangState` = 用户档位 + 探测结论，目录由它选 | 翻译（那是 `unlucky-i18n`） |
+//! | `platform` | 平台窗口能力（D36）：整窗 α 的纯判据 + win32 FFI（补分层样式 + 下发 α）—— **全仓唯一** `unsafe` 落点 | 窗口创建 / 业务开关 |
+//!
+//! ## 消费纪律
+//!
+//! **组件层零硬编码色值/字号/半径/间距**：一律走 [`theme::Ui`]。守门测试在
+//! `tests/no_hardcoded_tokens.rs`（扫 `src/**`，出现 `#RRGGBB` / `Color::from_rgb(` 即红）。
+//!
+//! ## 与 Slint 版的关系
+//!
+//! 并存期：`crates/app` 仍出 `unlucky-launcher`，本 crate 出 `unlucky-launcher-iced`。
+//! 等价验收后翻牌（bin 改名 + 旧 crate 降级），步骤写在
+//! `DevDocs/SubAgentsTalk/app-iced-骨架与翻牌.md`。
+
+pub mod pages;
+pub mod platform;
+pub mod renderer;
+pub mod shot;
+pub mod theme;
+
+mod app;
+mod cli;
+mod fonts;
+mod icons;
+mod probe;
+mod shell;
+mod ui;
+
+pub use cli::{Backend, Options};
+pub use probe::Probe;
+
+/// 启动 UI（阻塞到窗口关闭）。渲染后端由 `probe` 在 `run()` 之前写进 `ICED_BACKEND`。
+pub fn run(options: Options) -> iced::Result {
+    app::run(options)
+}
+
+/// 与 [`run`] 同义，但把命令行做成最终结论：`Options::from_env()` + 启动日志。
+///
+/// 二进制入口用 [`Options::from_env`] + [`run`] 自己拼（要额外处理 `--diff`），这个函数留给
+/// 集成测试与将来的 CLI 复用。
+///
+/// # Errors
+/// 参数不合法时返回人话（不 panic、不 `exit`）。
+pub fn run_from_env() -> Result<iced::Result, String> {
+    let options = Options::from_env()?;
+    Ok(run(options))
+}
diff --git a/crates/app-iced/src/main.rs b/crates/app-iced/src/main.rs
new file mode 100644
index 0000000..f3dad9c
--- /dev/null
+++ b/crates/app-iced/src/main.rs
@@ -0,0 +1,103 @@
+//! 入口。所有实际逻辑在 lib（`unlucky_app_iced`）里：
+//!
+//! 一个二进制两种用法（M82），分发在进 UI 之前完成：
+//!
+//! - 被子命令命中（`instances` / `install` / `launch` / `accounts` / `sessions` / `logs` /
+//!   `diag` / `config` / `java` / `agent`，或 `--help` / `--version`）→ 直接转给
+//!   `unlucky_cli::run`，**不初始化任何 UI**（不 probe 后端、不扫字体、不碰图形库）。
+//!   子命令表不在这里抄一份：唯一真相源是 `crates/cli` 的解析器
+//!   （`unlucky_cli::cli::looks_like_cli`，本文件只调用）。
+//! - 其余参数（`--software-renderer` / `--renderer` / `--theme` / `--screenshot*` /
+//!   `--diff` …）：开窗跑骨架，`--screenshot` 出图后退出；`--diff <a> <b>` 只读两张 PNG
+//!   做逐像素对比（D30 的 GPU/CPU 几何一致性检查），不开窗。
+//!
+//! 零 UI 依赖的 `ull` 仍然保留（D18）：它是唯一连 fontconfig 都不需要的产物，
+//! 给服务器 / CI / Termux 这类没有图形库的机器用。
+//!
+//! 退出码：`0` 成功 / `1` 截图有差异（diff 模式）或 CLI 用户错误 / `2` 参数或运行错误。
+
+use std::process::ExitCode;
+
+use unlucky_app_iced::shot;
+use unlucky_app_iced::Options;
+
+fn main() -> ExitCode {
+    let args: Vec<String> = std::env::args().skip(1).collect();
+    if let Some(code) = run_cli_if_requested(&args) {
+        return code;
+    }
+
+    // M97：把 iced_wgpu / wgpu 的 `log` 输出接到 stderr。`Selected: AdapterInfo{…}` 那行
+    // 是「GPU 真生效」的实证——没有它，日志只能证明我们**请求过** GPU。
+    // CLI 子命令在上面就返回了；`--diff` 虽然也装，但它不碰 wgpu，不会多出任何一行。
+    unlucky_app_iced::renderer::log_bridge::install();
+
+    match run_gui() {
+        Ok(code) => code,
+        Err(message) => {
+            eprintln!("[cli] {message}");
+            eprintln!(
+                "用法：unlucky-launcher-iced [--renderer=auto|gpu|cpu] [--software-renderer] \
+                 [--theme=light|dark] [--screenshot <png>] [--screenshot-theme=light|dark] \
+                 [--scale-factor <f32>] [--diff <a.png> <b.png>]"
+            );
+            // M98：验收开关写在用法里，不然「日志怎么变详细了」只能靠翻文档。
+            eprintln!(
+                "验收诊断：ULL_ACCEPTANCE=1（[env]/[backend]/[window]/[font]/[theme]/[perf]/[i18n]/[caps]）\
+                 ，ULL_WINDOW_SIZE=1520x900 覆盖窗口尺寸"
+            );
+            ExitCode::from(2)
+        }
+    }
+}
+
+/// 子命令命中 CLI 就跑 CLI 并以它的退出码收尾；返回 `None` 表示「这不是 CLI 调用，去开窗」。
+///
+/// 这条路径上**不构造窗口、不探后端、不扫字体、不依赖任何图形库**（这些库缺失时同一条命令照样
+/// 跑完，实测见 packaging/README.md §7.4）。`unlucky-launcher-iced launch …` 的耗时因此与首帧无关——
+/// 这句是结构性判断，**没有重量**（原因见 §10-8）。
+///
+/// 「这条命令行算不算 CLI 调用」的判据不在这里重复：`unlucky_cli::cli::looks_like_cli` 是唯一
+/// 一处（M82 复审去重），两个 GUI 二进制都只调它，改语义不会漂。
+fn run_cli_if_requested(args: &[String]) -> Option<ExitCode> {
+    if !unlucky_cli::cli::looks_like_cli(args) {
+        return None;
+    }
+    let mut stdout = std::io::stdout();
+    let mut stderr = std::io::stderr();
+    let code = unlucky_cli::run(args, &mut stdout, &mut stderr);
+    let _ = std::io::Write::flush(&mut stdout);
+    let _ = std::io::Write::flush(&mut stderr);
+    Some(ExitCode::from(u8::try_from(code).unwrap_or(2)))
+}
+
+/// 开窗路径：解析 GUI 参数 → （`--diff` 走比对）→ 起 UI。
+fn run_gui() -> Result<ExitCode, String> {
+    let options = Options::from_env()?;
+
+    if let Some((left, right)) = options.diff.clone() {
+        let scan = i32::try_from(options.diff_scan).unwrap_or(i32::MAX);
+        return match shot::diff_files_with_scan(&left, &right, scan) {
+            Ok(diff) => {
+                eprintln!("{}", diff.describe());
+                if diff.is_identical() {
+                    Ok(ExitCode::SUCCESS)
+                } else {
+                    Ok(ExitCode::from(1))
+                }
+            }
+            Err(message) => {
+                eprintln!("[diff] {message}");
+                Ok(ExitCode::from(2))
+            }
+        };
+    }
+
+    match unlucky_app_iced::run(options) {
+        Ok(()) => Ok(ExitCode::SUCCESS),
+        Err(error) => {
+            eprintln!("[run] {error}");
+            Ok(ExitCode::FAILURE)
+        }
+    }
+}
diff --git a/crates/app-iced/src/pages/account.rs b/crates/app-iced/src/pages/account.rs
new file mode 100644
index 0000000..a7ef912
--- /dev/null
+++ b/crates/app-iced/src/pages/account.rs
@@ -0,0 +1,175 @@
+//! 账户页（M114）：**三轨**登录（微软正版 / 第三方皮肤站 / 本地档案）+ 账户列表 + 皮肤区。
+//!
+//! ## 这一页回答什么
+//!
+//! 用户的原话是「用户管理页面还没做吗？包括不限于正版登录 离线登录 第三方皮肤站登录」。
+//! Slint 版曾有这个页面（`DevDocs/ops/screens-m43/account-data.png`），换 iced 时没搬过来，
+//! 于是 iced 版**一个账户入口都没有**——本页就是把它补回来，并按 M114 的口径做成三轨。
+//!
+//! ## 四条红线（都在本页的断言里）
+//!
+//! | 红线 | 落点 |
+//! |---|---|
+//! | 页面不得出现任何 token / refresh_token | 上屏文案只来自 [`model`] 的公开字段；`tests` 里有「把 JWT 塞进事件、断言模型干净」的用例 |
+//! | 离线档案的说明必须带「仅本地/隔离网络测试用，无法连接启用正版验证的服务器」 | `Key::AccountTrackOfflineBody` / `Key::AccountOfflineWarning` 两处都写全 |
+//! | 设备码不得只转圈 | [`login`]：用户码 + 链接 + 倒计时 + 「已过期，重试」 |
+//! | 没有皮肤不给假皮肤 | 头像位 = 首字母块（`profile_id` 稳定取色）；第三方轨才可能出真图 |
+//!
+//! ## 模块
+//!
+//! | 文件 | 职责 |
+//! |---|---|
+//! | [`model`] | 状态 → 视图模型（列表行 / 当前账户 / 三条轨道的面板态） |
+//! | [`avatar`] | 首字母块 + 皮肤图（解码/裁剪缓存；失败一律退回首字母块，**绝不白块**） |
+//! | [`widgets`] | 本页的小件（头像块 / 章节标题 / 徽标），样式全部走令牌 |
+//! | [`rows`] | 当前账户卡片 + 账户列表行 |
+//! | [`forms`] | 三条轨道的入口卡 + 本地档案/第三方站表单 |
+//! | [`login`] | 微软登录面板（设备码倒计时 / 浏览器授权 / 失败态） |
+//! | `tests` | 视图模型的判据（凭据红线、空态、倒计时、皮肤回落） |
+
+pub mod avatar;
+pub mod forms;
+pub mod login;
+pub mod model;
+pub mod panels;
+pub mod rows;
+pub mod widgets;
+
+#[cfg(test)]
+mod tests;
+#[cfg(test)]
+#[path = "account/tests_text.rs"]
+mod tests_text;
+
+pub use model::{Form, Hint, Notice, Page, Panel, Track};
+
+use iced::widget::{column, container, scrollable};
+use iced::{Element, Length, Padding};
+
+use unlucky_design::spacing::Space;
+use unlucky_i18n::{Key, Lang};
+
+use crate::app::components::buttons::{self, Button};
+use crate::pages::frame::{self, Header};
+use crate::pages::layout::FrameMetrics;
+use crate::theme::Ui;
+
+use super::Message as PageMessage;
+
+/// 账户页的页面消息（app 层把它翻成 `AppCommand` / 状态写入）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Message {
+    /// 打开某条轨道的表单
+    Open(Track),
+    /// 关掉表单/登录面板
+    Close,
+    /// 第三方站地址输入
+    Server(String),
+    /// 登录名输入
+    Login(String),
+    /// 密码输入（只存在内存里，随请求交给 host，用完即弃）
+    Password(String),
+    /// 本地档案名输入
+    OfflineName(String),
+    /// 校验服务器地址（服务发现）
+    Probe,
+    /// 表单提交（本地档案 → 建档案；第三方站 → 登录）
+    Submit,
+    /// 微软：设备码流
+    StartDevice,
+    /// 微软：授权码流（拉起系统浏览器）
+    StartBrowser,
+    /// 取消/关掉登录面板
+    Cancel,
+    /// 复制一段文本（用户码 / 链接）
+    Copy(String),
+    /// 切换当前启动账户
+    Switch(String),
+    /// 删除账户
+    Remove(String),
+    /// 重新登录（按账户类型分派：微软 → 授权码流；第三方 → 预填表单；离线 → 明确说明）
+    Relogin(String),
+    /// 展开/收起「Add an account」的三张轨道卡（复审 r1 P2-4）
+    ToggleAdd,
+    /// 关掉横幅
+    DismissNotice,
+}
+
+impl Message {
+    /// 包成页面的消息（本模块内部与 app 层都用它，保证只有一处包装点）。
+    pub fn into_page(self) -> PageMessage {
+        PageMessage::Account(self)
+    }
+}
+
+/// 整页。
+pub fn view<'a>(
+    ui: &'a Ui,
+    metrics: FrameMetrics,
+    page: &'a Page,
+    lang: Lang,
+) -> Element<'a, PageMessage> {
+    let text = lang.catalog();
+    let subtitle = text.text(Key::AccountSubtitle);
+    let add = text.text(Key::AccountEmptyAction);
+    let header = Header::new(text.text(Key::AccountTitle))
+        .subtitle(subtitle)
+        .action(buttons::tonal(
+            ui,
+            Button::new(add, Message::ToggleAdd.into_page()),
+        ));
+
+    let top = if page.rows.is_empty() {
+        forms::empty(ui, text, lang)
+    } else {
+        column![
+            rows::active_card(ui, page, text, lang),
+            rows::list(ui, page, text, lang),
+        ]
+        .spacing(ui.space(Space::X6))
+        .into()
+    };
+
+    // 三条轨道入口 + 表单/登录面板：面板存在时**只画面板**，且**置顶**——
+    // 否则在 1180×760 下设备码的「复制用户码 / 取消」会掉到折线以下（D30 复审实测）。
+    let flows = match page.panel {
+        Panel::None => forms::tracks(ui, text, lang),
+        _ => forms::panel(ui, page, text, lang),
+    };
+
+    let mut content = column![].spacing(ui.space(Space::X6)).width(Length::Fill);
+    if let Some(notice) = &page.notice {
+        content = content.push(widgets::banner(ui, notice, text));
+    }
+    if let Some(hint) = page.hint {
+        content = content.push(widgets::hint(ui, hint, page, text));
+    }
+    // 三张轨道卡：空态**总是**画（那就是空态的入口）；有账号时收在「Add an account」后面
+    let show_tracks = page.panel == Panel::None && (page.rows.is_empty() || page.form.section_open);
+    content = if page.panel == Panel::None {
+        if show_tracks {
+            content.push(top).push(flows)
+        } else {
+            content.push(top)
+        }
+    } else {
+        content.push(flows).push(top)
+    };
+
+    // 右缘留 8px gutter：全局 `frame::scroll_style` 的滚动条是 6px + 2px 内缩，
+    // 满宽卡片会被它压住（tower 看图意见 ②）。页面级留白是这条的最小修法。
+    let padded = container(content).width(Length::Fill).padding(Padding {
+        right: ui.space(Space::X2),
+        ..Padding::default()
+    });
+
+    frame::page(
+        ui,
+        metrics,
+        header,
+        scrollable(padded)
+            .style(frame::scroll_style(ui))
+            .width(Length::Fill)
+            .height(Length::Fill),
+    )
+}
diff --git a/crates/app-iced/src/pages/account/avatar.rs b/crates/app-iced/src/pages/account/avatar.rs
new file mode 100644
index 0000000..d180dbe
--- /dev/null
+++ b/crates/app-iced/src/pages/account/avatar.rs
@@ -0,0 +1,229 @@
+//! 头像位与皮肤区：**首字母块**（无皮肤时）与**真图**（第三方轨抓到皮肤时）。
+//!
+//! ## 为什么头像可以「真有图」
+//!
+//! presenter 只把皮肤的 **PNG 原图**送到 UI（它不引入图片解码依赖），裁剪/缩放全部在这里做：
+//! Minecraft 皮肤的头部在 `(8,8)` 的 8×8 方块（64×64 皮肤），帽子层在 `(40,8)`，
+//! 两层贴起来再放大到 64×64 就是一张真正的头像。**解码失败一律退回首字母块**——
+//! 头像位不允许出现白块（M114 明文要求）。
+//!
+//! ## 依赖口径
+//!
+//! 用的是 `crates/app-iced/Cargo.toml` **既有**的 `image`（png feature，M93 背景图那一条），
+//! 本 mission 没有改任何依赖表。
+
+use std::collections::BTreeMap;
+
+use iced::widget::image;
+
+use unlucky_presenter::dto::SkinImage;
+
+/// 头像边长（像素）：列表行 40、当前账户卡片 56 共用同一张 64 的图（缩下来仍然清晰）。
+const HEAD_PX: u32 = 64;
+/// 皮肤原图的头部坐标（64×64 皮肤的标准布局）。
+const FACE: (u32, u32) = (8, 8);
+/// 帽子/头发层的坐标（叠在脸上一层）。
+const HAT: (u32, u32) = (40, 8);
+/// 头部方块边长（8×8）。
+const FACE_EDGE: u32 = 8;
+
+/// 一个账户的解码结果（失败就是两个 `None`，UI 画首字母块）。
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct Avatar {
+    /// 裁好的头像（64×64 RGBA）
+    pub head: Option<image::Handle>,
+    /// 皮肤原图（皮肤预览区用）
+    pub skin: Option<image::Handle>,
+}
+
+/// 解码缓存：同一个账户的同一张皮肤只解码一次。
+///
+/// 键 = 账户 id，值 = (皮肤来源串, 解码结果)。来源串变了（重新登录换了皮肤）就重解。
+#[derive(Debug, Default)]
+pub struct Cache {
+    entries: BTreeMap<String, (String, Avatar)>,
+}
+
+impl Cache {
+    /// 取某个账户的头像（必要时解码）。
+    pub fn resolve(&mut self, id: &str, skin: Option<&SkinImage>) -> Avatar {
+        let source = skin.map(|skin| skin.source.clone()).unwrap_or_default();
+        let empty = skin.is_none_or(SkinImage::is_empty);
+        if empty {
+            // 没有皮肤 = 没有图（离线轨永远走这条；**不给假皮肤**）
+            self.entries.remove(id);
+            return Avatar::default();
+        }
+        if let Some((cached_source, avatar)) = self.entries.get(id) {
+            if cached_source == &source {
+                return avatar.clone();
+            }
+        }
+        let decoded = skin.map(decode).unwrap_or_default();
+        self.entries
+            .insert(id.to_string(), (source, decoded.clone()));
+        decoded
+    }
+
+    /// 当前缓存条目数（单测与诊断用）。
+    #[must_use]
+    pub fn len(&self) -> usize {
+        self.entries.len()
+    }
+
+    /// 缓存是否为空。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.entries.is_empty()
+    }
+}
+
+/// PNG 皮肤 → 头像（裁 + 叠帽子层 + 放大）。
+fn decode(skin: &SkinImage) -> Avatar {
+    let Some(decoded) = decode_png(&skin.png) else {
+        return Avatar::default();
+    };
+    let Some(scaled) = compose_head(&decoded) else {
+        return Avatar::default();
+    };
+    Avatar {
+        head: Some(image::Handle::from_rgba(
+            HEAD_PX,
+            HEAD_PX,
+            scaled.into_raw(),
+        )),
+        // 皮肤预览用**原图**（64×64）：tower 口径是「原图直接展示，不为好看伪造皮肤」
+        skin: Some(image::Handle::from_bytes(skin.png.clone())),
+    }
+}
+
+/// 裁 8×8 脸 + 叠 (40,8) 的帽子层 + 放大到 64×64（纯函数，单测直接验像素）。
+///
+/// 旧版 64×32 皮肤没有帽子层（只有脸），所以尺寸不够时只裁脸。
+fn compose_head(decoded: &::image::RgbaImage) -> Option<::image::RgbaImage> {
+    let (width, height) = (decoded.width(), decoded.height());
+    if width < FACE.0 + FACE_EDGE || height < FACE.1 + FACE_EDGE {
+        return None;
+    }
+    let mut face =
+        ::image::imageops::crop_imm(decoded, FACE.0, FACE.1, FACE_EDGE, FACE_EDGE).to_image();
+    if width >= HAT.0 + FACE_EDGE && height >= HAT.1 + FACE_EDGE {
+        let hat =
+            ::image::imageops::crop_imm(decoded, HAT.0, HAT.1, FACE_EDGE, FACE_EDGE).to_image();
+        ::image::imageops::overlay(&mut face, &hat, 0, 0);
+    }
+    Some(::image::imageops::resize(
+        &face,
+        HEAD_PX,
+        HEAD_PX,
+        ::image::imageops::FilterType::Nearest,
+    ))
+}
+
+/// 解 PNG（尺寸上限与背景图那条守门同源：皮肤不该有超大图）。
+fn decode_png(bytes: &[u8]) -> Option<::image::RgbaImage> {
+    const MAX_EDGE: u32 = 512;
+    let reader = ::image::ImageReader::new(std::io::Cursor::new(bytes))
+        .with_guessed_format()
+        .ok()?;
+    let (width, height) = reader.into_dimensions().ok()?;
+    if width == 0 || height == 0 || width > MAX_EDGE || height > MAX_EDGE {
+        return None;
+    }
+    let reader = ::image::ImageReader::new(std::io::Cursor::new(bytes))
+        .with_guessed_format()
+        .ok()?;
+    Some(reader.decode().ok()?.to_rgba8())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use ::image::ImageEncoder;
+    use ::image::{Rgba, RgbaImage};
+
+    fn png_of(image: &RgbaImage) -> Vec<u8> {
+        let mut bytes = Vec::new();
+        let encoder = ::image::codecs::png::PngEncoder::new(&mut bytes);
+        encoder
+            .write_image(
+                image.as_raw(),
+                image.width(),
+                image.height(),
+                ::image::ExtendedColorType::Rgba8,
+            )
+            .expect("编码 PNG");
+        bytes
+    }
+
+    /// 造一张 64×64 的皮肤：脸是红色，帽子层是半透明蓝。
+    fn skin_bytes() -> Vec<u8> {
+        let mut skin = RgbaImage::from_pixel(64, 64, Rgba([0, 0, 0, 0]));
+        for x in 8..16 {
+            for y in 8..16 {
+                skin.put_pixel(x, y, Rgba([200, 10, 10, 255]));
+            }
+        }
+        for x in 40..48 {
+            for y in 8..16 {
+                skin.put_pixel(x, y, Rgba([10, 10, 200, 120]));
+            }
+        }
+        png_of(&skin)
+    }
+
+    /// **帽子层真的叠进头像了**（复审 r1 P3-4：原用例只断言 `head.is_some()`，
+    /// 把 overlay 删掉也不会红）。
+    ///
+    /// 夹具：脸是纯红 (200,10,10,255)，帽子层是半透明蓝 (10,10,200,120)。
+    /// 叠上去之后头像像素必须**既不等于纯红、也不等于纯蓝**——那就是混合的结果。
+    #[test]
+    fn a_real_skin_becomes_a_head_with_the_hat_layer() {
+        let avatar = decode(&SkinImage {
+            png: skin_bytes(),
+            source: "test".to_string(),
+        });
+        assert!(avatar.head.is_some(), "64×64 皮肤必须裁出头像");
+        assert!(avatar.skin.is_some(), "皮肤预览要有原图");
+
+        let decoded = decode_png(&skin_bytes()).expect("解码夹具");
+        let head = compose_head(&decoded).expect("裁头");
+        let pixel = head.get_pixel(0, 0).0;
+        assert_ne!(pixel, [200, 10, 10, 255], "帽子层没叠上去（还是纯红）");
+        assert_ne!(
+            pixel,
+            [10, 10, 200, 120],
+            "帽子层把脸整个盖掉了（不是 blend）"
+        );
+        assert!(pixel[2] > 10, "蓝色分量必须被帽子层抬高：{pixel:?}");
+    }
+
+    #[test]
+    fn a_broken_payload_falls_back_instead_of_panicking() {
+        let avatar = decode(&SkinImage {
+            png: b"not a png".to_vec(),
+            source: "test".to_string(),
+        });
+        assert!(avatar.head.is_none(), "解不开就退回首字母块");
+        assert!(avatar.skin.is_none());
+    }
+
+    #[test]
+    fn the_cache_keeps_one_entry_per_account_and_drops_it_without_a_skin() {
+        let mut cache = Cache::default();
+        let skin = SkinImage {
+            png: skin_bytes(),
+            source: "a".to_string(),
+        };
+        let first = cache.resolve("account:a", Some(&skin));
+        assert!(first.head.is_some());
+        assert_eq!(cache.len(), 1);
+        // 同一来源：命中缓存
+        let again = cache.resolve("account:a", Some(&skin));
+        assert!(again.head.is_some());
+        // 没有皮肤：条目被删掉（不留「上次的图」冒充真皮肤）
+        let none = cache.resolve("account:a", None);
+        assert!(none.head.is_none());
+        assert!(cache.is_empty());
+    }
+}
diff --git a/crates/app-iced/src/pages/account/forms.rs b/crates/app-iced/src/pages/account/forms.rs
new file mode 100644
index 0000000..378ba68
--- /dev/null
+++ b/crates/app-iced/src/pages/account/forms.rs
@@ -0,0 +1,322 @@
+//! 三条轨道的入口卡与两张表单（本地档案 / 第三方皮肤站）。
+//!
+//! ## 为什么是「三条轨道」而不是「一个添加按钮 + 一个类型下拉」
+//!
+//! 三条轨道的**字段完全不同**（微软没有密码输入框、本地档案没有服务器、第三方站两样都有），
+//! 而且失败原因也不同（403 / 白名单未批 / 服务器不可达）。把它们压进一个表单只会让每种情况
+//! 都要解释自己不属于另外两种——所以入口就是三张卡，各自展开自己的面板。
+
+use iced::widget::{column, container, row};
+use iced::{Alignment, Element, Length};
+
+use unlucky_design::color::Role;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+use unlucky_i18n::{Catalog, Key, Lang};
+
+use crate::app::components::buttons::{self, Button};
+use crate::app::components::feedback::empty_state::{empty_state, EmptyState};
+use crate::app::components::inputs::{text_field, Field, FieldVariant};
+use crate::pages::frame;
+use crate::theme::Ui;
+
+use crate::pages::account::model::{AuthlibPanel, Page, Track};
+use crate::pages::Message as PageMessage;
+
+use super::{login, widgets, Message as Account};
+
+/// 空态：不是一张白页——图标块 + 标题 + 说明，下面紧跟**三张轨道卡**（真正的入口）。
+///
+/// 复审 r1 的 P2-4：空态原先有**三套**同一件事的入口（右上按钮 / 三个 chip / 三张卡），
+/// chip 还被当成操作按钮用。现在只剩「右上 Add an account（展开/收起）+ 三张卡」这一套：
+/// 空态时卡片本来就可见，有账号时收在按钮后面。
+pub fn empty<'a>(ui: &'a Ui, catalog: Catalog, lang: Lang) -> Element<'a, PageMessage> {
+    let _ = lang;
+    let state = empty_state(
+        ui,
+        EmptyState::new(
+            unlucky_design::icons::IconKind::User,
+            catalog.text(Key::AccountEmptyTitle),
+            catalog.text(Key::AccountEmptyBody),
+        ),
+    );
+    container(state)
+        .height(Length::Fixed(ui.space(Space::X8) * 8.0))
+        .width(Length::Fill)
+        .into()
+}
+
+/// 三条轨道的入口卡（面板没打开时画这一排）。
+pub fn tracks<'a>(ui: &'a Ui, catalog: Catalog, lang: Lang) -> Element<'a, PageMessage> {
+    let _ = lang;
+    let mut row = iced::widget::Row::new().spacing(ui.space(Space::X4));
+    for track in Track::ALL {
+        row = row.push(track_card(ui, track, catalog));
+    }
+    row.width(Length::Fill).into()
+}
+
+fn track_card<'a>(ui: &'a Ui, track: Track, catalog: Catalog) -> Element<'a, PageMessage> {
+    let body = column![
+        frame::text_role(
+            ui,
+            TypeRole::TitleSmall,
+            true,
+            catalog.text(track.title_key()),
+            ui.color(Role::OnSurface),
+        ),
+        frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            catalog.text(track.body_key()),
+            ui.color(Role::OnSurfaceVariant),
+        ),
+        buttons::outlined(
+            ui,
+            Button::new(
+                catalog.text(track.action_key()),
+                Account::Open(track).into_page(),
+            ),
+        ),
+    ]
+    .spacing(ui.space(Space::X3));
+    container(frame::card(ui, body))
+        .width(Length::FillPortion(1))
+        .into()
+}
+
+/// 当前打开的面板。
+pub fn panel<'a>(
+    ui: &'a Ui,
+    page: &'a Page,
+    catalog: Catalog,
+    lang: Lang,
+) -> Element<'a, PageMessage> {
+    let _ = lang;
+    match page.panel {
+        crate::pages::account::model::Panel::None => tracks(ui, catalog, Lang::En),
+        crate::pages::account::model::Panel::Microsoft => login::panel(ui, &page.device, catalog),
+        crate::pages::account::model::Panel::Authlib => authlib_form(ui, page, catalog),
+        crate::pages::account::model::Panel::Offline => offline_form(ui, page, catalog),
+    }
+}
+
+/// 本地档案表单（**说明里带「仅本地/隔离网络测试用」这条限定**）。
+fn offline_form<'a>(ui: &'a Ui, page: &'a Page, catalog: Catalog) -> Element<'a, PageMessage> {
+    let ready = page.form.offline_ready();
+    let submit = if ready {
+        buttons::filled(
+            ui,
+            Button::new(
+                catalog.text(Key::AccountOfflineSubmit),
+                Account::Submit.into_page(),
+            ),
+        )
+    } else {
+        buttons::filled(
+            ui,
+            Button::disabled(catalog.text(Key::AccountOfflineSubmit)),
+        )
+    };
+
+    let body = column![
+        // 标题下**不再复读**同一句限定：下面那条 `ErrorContainer` 警告条就是它
+        // （两处一模一样的句子在 1180×760 下看着像重复渲染）。
+        widgets::section(ui, catalog.text(Key::AccountTrackOfflineTitle), None),
+        warning(ui, catalog.text(Key::AccountOfflineWarning)),
+        text_field(
+            ui,
+            Field::new(&page.form.offline_name)
+                .variant(FieldVariant::Outlined)
+                .label(catalog.text(Key::AccountOfflineNameLabel))
+                .placeholder(catalog.text(Key::AccountOfflineNameHint))
+                .supporting(catalog.text(Key::AccountOfflineNameHint)),
+            |value| Account::OfflineName(value).into_page(),
+        ),
+        row![
+            submit,
+            buttons::text(
+                ui,
+                Button::new(
+                    catalog.text(Key::AccountDialogClose),
+                    Account::Close.into_page()
+                )
+            ),
+        ]
+        .spacing(ui.space(Space::X2))
+        .align_y(Alignment::Center),
+    ]
+    .spacing(ui.space(Space::X3));
+    frame::card(ui, body)
+}
+
+/// 第三方站表单：地址（可单独校验）+ 登录名 + 密码 + 登录。
+fn authlib_form<'a>(ui: &'a Ui, page: &'a Page, catalog: Catalog) -> Element<'a, PageMessage> {
+    let busy = page.authlib.busy();
+    let ready = page.form.authlib_ready() && !busy;
+
+    let submit = if ready {
+        buttons::filled(
+            ui,
+            Button::new(
+                catalog.text(Key::AccountAuthlibSubmit),
+                Account::Submit.into_page(),
+            ),
+        )
+    } else {
+        buttons::filled(
+            ui,
+            Button::disabled(catalog.text(Key::AccountAuthlibSubmit)),
+        )
+    };
+
+    let mut body = column![
+        widgets::section(
+            ui,
+            catalog.text(Key::AccountTrackAuthlibTitle),
+            Some(catalog.text(Key::AccountTrackAuthlibBody)),
+        ),
+        text_field(
+            ui,
+            Field::new(&page.form.server)
+                .variant(FieldVariant::Outlined)
+                .label(catalog.text(Key::AccountServerLabel))
+                .placeholder(catalog.text(Key::AccountServerHint))
+                .supporting(if page.checked_server.is_empty() {
+                    catalog.text(Key::AccountServerHint)
+                } else {
+                    page.checked_server.as_str()
+                }),
+            |value| Account::Server(value).into_page(),
+        ),
+        text_field(
+            ui,
+            Field::new(&page.form.login)
+                .variant(FieldVariant::Outlined)
+                .label(catalog.text(Key::AccountLoginNameLabel))
+                .placeholder(""),
+            |value| Account::Login(value).into_page(),
+        ),
+        text_field(
+            ui,
+            Field::new(&page.form.password)
+                .variant(FieldVariant::Outlined)
+                .label(catalog.text(Key::AccountPasswordLabel))
+                .supporting(catalog.text(Key::AccountPasswordHint))
+                // 密码**掩码**显示：明文只在内存里，不上屏
+                .secure(true),
+            |value| Account::Password(value).into_page(),
+        ),
+        status_line(ui, page, catalog),
+        row![
+            buttons::outlined(
+                ui,
+                Button::new(
+                    catalog.text(Key::AccountServerProbe),
+                    Account::Probe.into_page()
+                )
+            ),
+            submit,
+            buttons::text(
+                ui,
+                Button::new(
+                    catalog.text(Key::AccountDialogClose),
+                    Account::Close.into_page()
+                )
+            ),
+        ]
+        .spacing(ui.space(Space::X2))
+        .align_y(Alignment::Center),
+    ]
+    .spacing(ui.space(Space::X3));
+
+    if !ready && !busy {
+        body = body.push(frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            catalog.text(Key::AccountAuthlibIdleHint),
+            ui.color(Role::OnSurfaceVariant),
+        ));
+    }
+    frame::card(ui, body)
+}
+
+/// 第三方轨的状态行（校验通过 / 进行中 / 失败原文）。
+///
+/// 进行中与通过都走 **i18n**：presenter 给的 `message` 是后端诊断串（中文），
+/// 直接上屏会让英文界面里混一段中文；失败态才用它（那是要人读的错误原因）。
+fn status_line<'a>(ui: &'a Ui, page: &'a Page, catalog: Catalog) -> Element<'a, PageMessage> {
+    match &page.authlib {
+        AuthlibPanel::Idle => frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            "",
+            ui.color(Role::OnSurfaceVariant),
+        ),
+        AuthlibPanel::Running => frame::text_role(
+            ui,
+            TypeRole::LabelMedium,
+            false,
+            catalog.text(Key::AccountServerChecking),
+            ui.color(Role::OnSurfaceVariant),
+        ),
+        AuthlibPanel::Ready { server_name, .. } => frame::text_role_owned(
+            ui,
+            TypeRole::LabelMedium,
+            true,
+            catalog.render(Key::AccountServerOk, &[("server", server_name.as_str())]),
+            ui.color(Role::Primary),
+        ),
+        // 失败只画**原因码对应的 i18n** + 一行 Code（原文是中文诊断串，上屏就是语言泄漏）
+        AuthlibPanel::Failed { failure } => column![
+            frame::text_role(
+                ui,
+                TypeRole::LabelMedium,
+                false,
+                catalog.text(super::login::failure_body_key(*failure)),
+                ui.color(Role::Error),
+            ),
+            frame::text_role_owned(
+                ui,
+                TypeRole::LabelSmall,
+                false,
+                catalog.render(Key::AccountFailureCode, &[("code", failure.code())]),
+                ui.color(Role::Error),
+            ),
+        ]
+        .spacing(ui.space(Space::X1))
+        .into(),
+        AuthlibPanel::Succeeded { name } => frame::text_role(
+            ui,
+            TypeRole::LabelMedium,
+            true,
+            name,
+            ui.color(Role::Primary),
+        ),
+    }
+}
+
+/// 「仅本地/隔离网络测试用」这条限定：**带色块**，不是一句灰字（用户要点得明白）。
+fn warning<'a>(ui: &'a Ui, text: &'a str) -> Element<'a, PageMessage> {
+    container(frame::text_role(
+        ui,
+        TypeRole::BodySmall,
+        false,
+        text,
+        ui.color(Role::OnErrorContainer),
+    ))
+    .width(Length::Fill)
+    .padding(ui.space(Space::X2))
+    .style(move |_theme| container::Style {
+        background: Some(iced::Background::Color(ui.color(Role::ErrorContainer))),
+        border: iced::Border {
+            radius: ui.radius_dp(unlucky_design::shape::ShapeScale::Small),
+            ..iced::Border::default()
+        },
+        ..container::Style::default()
+    })
+    .into()
+}
diff --git a/crates/app-iced/src/pages/account/login.rs b/crates/app-iced/src/pages/account/login.rs
new file mode 100644
index 0000000..17a9455
--- /dev/null
+++ b/crates/app-iced/src/pages/account/login.rs
@@ -0,0 +1,352 @@
+//! 微软登录面板：设备码（用户码 + 链接 + **倒计时** + 过期重试）与授权码（浏览器 + 可复制链接 + 取消）。
+//!
+//! ## 为什么不是「一个转圈」
+//!
+//! 设备码流的等待期可以长到 15 分钟。只画转圈的话，用户既不知道要做什么、也不知道还剩多久，
+//! 更不知道已经过期了——M114 把这三件事都做成可见状态：用户码（可复制）、链接（可复制/打开）、
+//! 倒计时（`{secs}s left`）与过期后的「已过期，重试」。授权码流同理，另外必须能**取消**。
+
+use iced::widget::{column, row};
+use iced::{Alignment, Element};
+
+use unlucky_design::color::Role;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+use unlucky_i18n::{Catalog, Key};
+use unlucky_presenter::dto::LoginFailure;
+
+use crate::app::components::buttons::{self, Button};
+use crate::pages::frame;
+use crate::theme::Ui;
+
+use crate::pages::account::model::DevicePanel;
+use crate::pages::Message as PageMessage;
+
+use super::Message as Account;
+
+/// 微软登录面板。
+pub fn panel<'a>(
+    ui: &'a Ui,
+    device: &'a DevicePanel,
+    catalog: Catalog,
+) -> Element<'a, PageMessage> {
+    match device {
+        DevicePanel::Hidden => idle(ui, catalog),
+        DevicePanel::Requesting => requesting(ui, catalog),
+        DevicePanel::Code {
+            code,
+            link,
+            remaining,
+            expired,
+        } => device_code(ui, code, link, *remaining, *expired, catalog),
+        DevicePanel::Browser {
+            link,
+            remaining,
+            expired,
+        } => browser(ui, link, *remaining, *expired, catalog),
+        DevicePanel::Failed { failure } => failed(ui, *failure, catalog),
+        DevicePanel::Succeeded { name } => succeeded(ui, name, catalog),
+    }
+}
+
+/// 空闲：给出两条流的入口（GUI 默认授权码流，设备码是备选）。
+fn idle<'a>(ui: &'a Ui, catalog: Catalog) -> Element<'a, PageMessage> {
+    let body = column![row![
+        buttons::filled(
+            ui,
+            Button::new(
+                catalog.text(Key::AccountDeviceBrowser),
+                Account::StartBrowser.into_page(),
+            )
+        ),
+        buttons::outlined(
+            ui,
+            Button::new(
+                catalog.text(Key::AccountDeviceUseCode),
+                Account::StartDevice.into_page(),
+            )
+        ),
+        buttons::text(
+            ui,
+            Button::new(
+                catalog.text(Key::AccountDeviceCancel),
+                Account::Close.into_page()
+            )
+        ),
+    ]
+    .spacing(ui.space(Space::X2))
+    .align_y(Alignment::Center),]
+    .spacing(ui.space(Space::X3));
+    frame::card(ui, body)
+}
+
+/// 「正在申请」：一句 i18n 状态 + 取消。
+///
+/// presenter 那边的进度串是中文诊断（只进日志），面板态里**根本没有**这个字段可画。
+fn requesting<'a>(ui: &'a Ui, catalog: Catalog) -> Element<'a, PageMessage> {
+    let body = column![
+        frame::text_role(
+            ui,
+            TypeRole::BodyMedium,
+            false,
+            catalog.text(Key::AccountDeviceRequesting),
+            ui.color(Role::OnSurfaceVariant),
+        ),
+        row![buttons::text(
+            ui,
+            Button::new(
+                catalog.text(Key::AccountDeviceCancel),
+                Account::Cancel.into_page()
+            )
+        )]
+        .align_y(Alignment::Center),
+    ]
+    .spacing(ui.space(Space::X3));
+    frame::card(ui, body)
+}
+
+/// 设备码等待态：**码 + 链接 + 倒计时**。
+fn device_code<'a>(
+    ui: &'a Ui,
+    code: &'a str,
+    link: &'a str,
+    remaining: Option<u64>,
+    expired: bool,
+    catalog: Catalog,
+) -> Element<'a, PageMessage> {
+    let mut actions = row![
+        buttons::tonal(
+            ui,
+            Button::new(
+                catalog.text(Key::AccountDeviceCodeCopy),
+                Account::Copy(code.to_string()).into_page(),
+            )
+        ),
+        buttons::outlined(
+            ui,
+            Button::new(
+                catalog.text(Key::AccountDeviceLinkCopy),
+                Account::Copy(link.to_string()).into_page(),
+            )
+        ),
+    ]
+    .spacing(ui.space(Space::X2))
+    .align_y(Alignment::Center);
+
+    if expired {
+        actions = actions.push(buttons::filled(
+            ui,
+            Button::new(
+                catalog.text(Key::AccountDeviceRetry),
+                Account::StartDevice.into_page(),
+            ),
+        ));
+    }
+    actions = actions.push(buttons::text(
+        ui,
+        Button::new(
+            catalog.text(Key::AccountDeviceCancel),
+            Account::Cancel.into_page(),
+        ),
+    ));
+
+    let countdown = countdown_line(ui, remaining, expired, catalog);
+
+    let body = column![
+        frame::text_role(
+            ui,
+            TypeRole::LabelMedium,
+            false,
+            catalog.text(Key::AccountDeviceCodeLabel),
+            ui.color(Role::OnSurfaceVariant),
+        ),
+        frame::text_role(
+            ui,
+            TypeRole::HeadlineSmall,
+            true,
+            code,
+            ui.color(Role::OnSurface),
+        ),
+        frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            link,
+            ui.color(Role::OnSurfaceVariant),
+        ),
+        countdown,
+        frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            catalog.text(Key::AccountDeviceHint),
+            ui.color(Role::OnSurfaceVariant),
+        ),
+        actions,
+    ]
+    .spacing(ui.space(Space::X3));
+    frame::card(ui, body)
+}
+
+/// 授权码等待态：浏览器已拉起，链接可复制；过期可重试。
+fn browser<'a>(
+    ui: &'a Ui,
+    link: &'a str,
+    remaining: Option<u64>,
+    expired: bool,
+    catalog: Catalog,
+) -> Element<'a, PageMessage> {
+    let mut actions = row![buttons::outlined(
+        ui,
+        Button::new(
+            catalog.text(Key::AccountDeviceLinkCopy),
+            Account::Copy(link.to_string()).into_page(),
+        )
+    )]
+    .spacing(ui.space(Space::X2))
+    .align_y(Alignment::Center);
+    if expired {
+        actions = actions.push(buttons::filled(
+            ui,
+            Button::new(
+                catalog.text(Key::AccountDeviceRetry),
+                Account::StartBrowser.into_page(),
+            ),
+        ));
+    }
+    actions = actions.push(buttons::text(
+        ui,
+        Button::new(
+            catalog.text(Key::AccountDeviceCancel),
+            Account::Cancel.into_page(),
+        ),
+    ));
+
+    let body = column![
+        frame::text_role(
+            ui,
+            TypeRole::BodyMedium,
+            false,
+            catalog.text(Key::AccountDeviceBrowserHint),
+            ui.color(Role::OnSurface),
+        ),
+        frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            link,
+            ui.color(Role::OnSurfaceVariant),
+        ),
+        countdown_line(ui, remaining, expired, catalog),
+        actions,
+    ]
+    .spacing(ui.space(Space::X3));
+    frame::card(ui, body)
+}
+
+/// 倒计时 / 过期提示（**这一行是「不得只转圈」的落点**）。
+fn countdown_line<'a>(
+    ui: &'a Ui,
+    remaining: Option<u64>,
+    expired: bool,
+    catalog: Catalog,
+) -> Element<'a, PageMessage> {
+    if expired {
+        return frame::text_role(
+            ui,
+            TypeRole::LabelMedium,
+            true,
+            catalog.text(Key::AccountDeviceExpired),
+            ui.color(Role::Error),
+        );
+    }
+    let text = remaining.map_or_else(String::new, |secs| {
+        // mm:ss（`15:00 left`）而不是 `900s left`：人读的是分秒，而且不随语言换格式
+        // （数字与冒号在两种语言里同形，只有 `left`/`剩` 走 catalog）。
+        let clock = format!("{:02}:{:02}", secs / 60, secs % 60);
+        catalog.render(Key::AccountDeviceCountdown, &[("time", &clock)])
+    });
+    // 运行时格式化的串走 `text_role_owned`（`text_role` 只借 `&'a str`）
+    frame::text_role_owned(
+        ui,
+        TypeRole::LabelMedium,
+        false,
+        text,
+        ui.color(Role::OnSurfaceVariant),
+    )
+}
+
+/// 失败态：**M3 内联 alert**（左侧 `ErrorContainer` 图标块 + 标题/正文/Code + 重试/关闭）。
+///
+/// 两条修订叠在这里：
+/// - **语言泄漏（r1 p1）**：只画原因码对应的 i18n + 一行 `Code: …`，后端中文原文不上屏；
+/// - **不许通栏实心红（tower r2）**：面板底走 `SurfaceContainerHigh` + 描边，
+///   `ErrorContainer`/`OnErrorContainer` 只作左侧图标块的强调（角色不变，面积收小）。
+fn failed<'a>(ui: &'a Ui, failure: LoginFailure, catalog: Catalog) -> Element<'a, PageMessage> {
+    let body = catalog.text(failure_body_key(failure)).to_string();
+    let code = catalog.render(Key::AccountFailureCode, &[("code", failure.code())]);
+    let actions = vec![
+        buttons::tonal(
+            ui,
+            Button::new(
+                catalog.text(Key::AccountDeviceRetry),
+                Account::StartDevice.into_page(),
+            ),
+        ),
+        buttons::text(
+            ui,
+            Button::new(
+                catalog.text(Key::AccountDialogClose),
+                Account::Close.into_page(),
+            ),
+        ),
+    ];
+    super::widgets::alert(
+        ui,
+        super::widgets::Tone::Error,
+        catalog.text(Key::AccountLoginFailed),
+        body,
+        Some(code),
+        actions,
+    )
+}
+
+/// 成功态。
+fn succeeded<'a>(ui: &'a Ui, name: &'a str, catalog: Catalog) -> Element<'a, PageMessage> {
+    // 成功也走 key + 参数（名字是 `{name}` 参数）——presenter 不再拼任何人类可读句子
+    // （复审 r1 P1-1 那条「报告与代码不符」的收口：`已登录：{name}` 这类拼接全部消失）。
+    let text = catalog.render(Key::AccountLoginSucceeded, &[("name", name)]);
+    let body = column![
+        frame::text_role_owned(
+            ui,
+            TypeRole::BodyMedium,
+            true,
+            text,
+            ui.color(Role::OnSurface),
+        ),
+        row![buttons::text(
+            ui,
+            Button::new(
+                catalog.text(Key::AccountDialogClose),
+                Account::Close.into_page()
+            )
+        )]
+        .align_y(Alignment::Center),
+    ]
+    .spacing(ui.space(Space::X3));
+    frame::card(ui, body)
+}
+
+/// 原因码 → i18n 正文 key（页面里唯一的「码→文案」映射点）。
+pub(super) fn failure_body_key(failure: LoginFailure) -> Key {
+    match failure {
+        LoginFailure::Denied => Key::AccountFailureDenied,
+        LoginFailure::NotWhitelisted => Key::AccountFailureWhitelist,
+        LoginFailure::Unreachable => Key::AccountFailureUnreachable,
+        LoginFailure::NotAuthlibServer => Key::AccountFailureNotAuthlib,
+        LoginFailure::BadCredentials => Key::AccountFailureBadCredentials,
+        LoginFailure::NoProfile => Key::AccountFailureNoProfile,
+        LoginFailure::StoreFailed => Key::AccountFailureStore,
+        LoginFailure::Other => Key::AccountFailureOther,
+    }
+}
diff --git a/crates/app-iced/src/pages/account/model.rs b/crates/app-iced/src/pages/account/model.rs
new file mode 100644
index 0000000..03d6eea
--- /dev/null
+++ b/crates/app-iced/src/pages/account/model.rs
@@ -0,0 +1,337 @@
+//! 状态 → 账户页视图模型（页面层不认识 presenter 的其它类型，只认这里）。
+//!
+//! 三条轨道在 UI 上只有三种「面板」：微软登录面板 / 第三方站表单 / 本地档案表单。
+//! 表单里那些**输入串**是纯 UI 状态，归 [`Form`]（app 层持有）；从 presenter 来的只有
+//! 账户列表、登录进度与倒计时。
+
+use iced::widget::image;
+
+use unlucky_i18n::{Key, Lang};
+use unlucky_presenter::dto::{AccountKind, AccountNotice, AccountNoticeCode, AccountView};
+use unlucky_presenter::state::AppState;
+
+use super::avatar::{Avatar, Cache};
+use super::panels::{authlib_panel, device_panel};
+
+pub use super::panels::{AuthlibPanel, DevicePanel};
+
+/// 三条轨道。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Track {
+    /// 微软正版（设备码 / 授权码两条流）
+    Microsoft,
+    /// 第三方皮肤站（authlib-injector）
+    Authlib,
+    /// 本地档案（离线）
+    Offline,
+}
+
+impl Track {
+    /// 卡片标题的 key。
+    #[must_use]
+    pub const fn title_key(self) -> Key {
+        match self {
+            Self::Microsoft => Key::AccountTrackMicrosoftTitle,
+            Self::Authlib => Key::AccountTrackAuthlibTitle,
+            Self::Offline => Key::AccountTrackOfflineTitle,
+        }
+    }
+
+    /// 卡片说明的 key。
+    #[must_use]
+    pub const fn body_key(self) -> Key {
+        match self {
+            Self::Microsoft => Key::AccountTrackMicrosoftBody,
+            Self::Authlib => Key::AccountTrackAuthlibBody,
+            Self::Offline => Key::AccountTrackOfflineBody,
+        }
+    }
+
+    /// 卡片主按钮的 key（微软/第三方是「登录」，本地是「创建档案」）。
+    #[must_use]
+    pub const fn action_key(self) -> Key {
+        match self {
+            Self::Microsoft => Key::AccountTrackOpen,
+            Self::Authlib => Key::AccountTrackOpen,
+            Self::Offline => Key::AccountTrackCreate,
+        }
+    }
+
+    /// 三条轨道（卡片顺序）。
+    pub const ALL: [Track; 3] = [Track::Microsoft, Track::Authlib, Track::Offline];
+}
+
+/// 当前打开的面板。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum Panel {
+    /// 只画三条轨道入口
+    #[default]
+    None,
+    /// 微软登录面板
+    Microsoft,
+    /// 第三方站表单
+    Authlib,
+    /// 本地档案表单
+    Offline,
+}
+
+/// 表单的**纯 UI 状态**（app 层持有，随消息改动）。
+///
+/// 密码只存在这里和「一次 `AppCommand::AddAuthlibAccount` 的载荷」里：不进日志、不进快照、
+/// 不进任何回程 DTO（M114 凭据红线）。
+/// **手写 `Debug`**：`Form` 里持着一次性密码，任何 `{:?}` 都不许带出明文（凭据红线）。
+impl std::fmt::Debug for Form {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("Form")
+            .field("panel", &self.panel)
+            .field("server", &self.server)
+            .field("login", &self.login)
+            .field("password", &"⟪redacted⟫")
+            .field("offline_name", &self.offline_name)
+            .field("section_open", &self.section_open)
+            .field("hint", &self.hint)
+            .finish()
+    }
+}
+
+/// 三条轨道的表单输入（纯 UI 状态；密码是**一次性请求值**）。
+#[derive(Clone, Default, PartialEq, Eq)]
+pub struct Form {
+    /// 当前面板
+    pub panel: Panel,
+    /// 第三方站地址
+    pub server: String,
+    /// 登录名
+    pub login: String,
+    /// 密码（一次性的请求值）
+    pub password: String,
+    /// 本地档案名
+    pub offline_name: String,
+    /// 「Add an account」展开态（有账号时三张轨道卡默认收起，复审 r1 P2-4）
+    pub section_open: bool,
+    /// 一次性引导（重新登录时告诉用户下一步；`None` = 没有引导）
+    pub hint: Option<Hint>,
+}
+
+/// 一次性引导（由 app 层在「重新登录」时设置，页面画一行 i18n）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Hint {
+    /// 第三方轨重登：重新输入密码
+    AuthlibReauth,
+    /// 本地档案没有可重登的服务器账户
+    OfflineNoRelogin,
+}
+
+impl Form {
+    /// 空表单（只画三条轨道）。
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// 打开某条轨道的面板（已开着同一个就用原值，避免输入被清掉）。
+    pub fn open(&mut self, track: Track) {
+        self.panel = match track {
+            Track::Microsoft => Panel::Microsoft,
+            Track::Authlib => Panel::Authlib,
+            Track::Offline => Panel::Offline,
+        };
+    }
+
+    /// 关掉面板（**密码一起清掉**：留着没有意义，只是多留一份凭据在内存里）。
+    pub fn close(&mut self) {
+        self.password.clear();
+        self.hint = None;
+        self.panel = Panel::None;
+    }
+
+    /// 提交之后清掉一次性凭据（成功与否都清：重试用新输入）。
+    pub fn clear_secret(&mut self) {
+        self.password.clear();
+    }
+
+    /// 本地档案名是否已填（`trim` 后非空才算）。
+    #[must_use]
+    pub fn offline_ready(&self) -> bool {
+        // 与 host 写盘前用的是**同一份判据**（`unlucky_presenter::dto::valid_offline_name`）：
+        // 按钮亮着却必然失败，比按钮灰着更糟（复审 r1 P2-2 的另一半）。
+        unlucky_presenter::dto::valid_offline_name(self.offline_name.trim())
+    }
+
+    /// 第三方站表单是否已填（三项都非空；地址的语法问题由 host 的规范化兜）。
+    #[must_use]
+    pub fn authlib_ready(&self) -> bool {
+        !self.server.trim().is_empty() && !self.login.trim().is_empty() && !self.password.is_empty()
+    }
+}
+
+/// 列表行 / 当前账户卡片用的数据。
+#[derive(Debug, Clone, PartialEq)]
+pub struct Row {
+    /// 稳定 id（切/删/重登都按它派命令）
+    pub id: String,
+    /// 展示名
+    pub name: String,
+    /// 首字母块的字
+    pub monogram: String,
+    /// 首字母块色号（0..6，`profile_id` 稳定推导）
+    pub tone: u8,
+    /// 轨道
+    pub kind: AccountKind,
+    /// 轨道文案（i18n）
+    pub kind_label: String,
+    /// 「添加于 {date}」
+    pub added: String,
+    /// 副行：服务器 / 登录名（没有就空）
+    pub detail: String,
+    /// 是否是当前启动账户
+    pub active: bool,
+    /// 裁好的头像（`None` = 画首字母块）
+    pub head: Option<image::Handle>,
+    /// 皮肤原图（皮肤预览区）
+    pub skin: Option<image::Handle>,
+}
+
+/// 整页视图模型。
+#[derive(Debug, Clone, PartialEq)]
+pub struct Page {
+    /// 账户行
+    pub rows: Vec<Row>,
+    /// 当前启动账户在 `rows` 里的下标
+    pub active: Option<usize>,
+    /// 打开的面板
+    pub panel: Panel,
+    /// 表单值（渲染要读）
+    pub form: Form,
+    /// 微软登录面板
+    pub device: DevicePanel,
+    /// 第三方轨面板
+    pub authlib: AuthlibPanel,
+    /// 校验通过的服务器名（表单上显示）
+    pub checked_server: String,
+    /// 版面宽度（**中栏可用宽**，M104 的 `AgentUi::content_width`；账户页自己的
+    /// `layout::frame_metrics` 拿它算列宽，与其它页同源）
+    pub width: f32,
+    /// 账户页横幅（添加/删除/切换的结果；`None` = 不画）
+    pub notice: Option<Notice>,
+    /// 一次性引导（重新登录的下一步）
+    pub hint: Option<Hint>,
+}
+
+/// 横幅的渲染数据（文案在视图层按 `code` 查 i18n）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Notice {
+    /// 结果码
+    pub code: AccountNoticeCode,
+    /// 主题（账户名/服务器地址）
+    pub subject: String,
+    /// 是否失败（决定配色）
+    pub failure: bool,
+}
+
+impl Notice {
+    fn of(notice: &AccountNotice) -> Self {
+        Self {
+            code: notice.code,
+            subject: notice.subject.clone(),
+            failure: notice.code.is_failure(),
+        }
+    }
+}
+
+impl Page {
+    /// 从状态与表单构造（`avatars` 是解码缓存，见 [`Cache`]；`width` 是中栏可用宽）。
+    pub fn build(
+        state: &AppState,
+        form: &Form,
+        avatars: &mut Cache,
+        lang: Lang,
+        width: f32,
+    ) -> Self {
+        let rows: Vec<Row> = state
+            .accounts
+            .iter()
+            .map(|account| row_of(account, avatars, lang))
+            .collect();
+        let active = rows.iter().position(|row| row.active);
+        let device = device_panel(&state.device_login, state.device_code_remaining());
+        // 登录在进行（或刚失败/刚成功）时，面板**必须**是微软那条轨：否则用户点了登录、
+        // 后台已经在等设备码，页面上却只剩三张入口卡——那正是「只转圈」的另一种坏法。
+        let panel = if matches!(device, DevicePanel::Hidden) {
+            form.panel
+        } else {
+            Panel::Microsoft
+        };
+        let (authlib, checked_server) = authlib_panel(&state.authlib_login);
+        // 「校验通过」的服务器名只在该面板打开且地址一致时显示（换了地址就不再是它）
+        let checked_server = if form.server.trim().is_empty()
+            || state.authlib_login.server.trim().is_empty()
+            || form.server.trim() != state.authlib_login.server.trim()
+        {
+            String::new()
+        } else {
+            checked_server
+        };
+        Page {
+            rows,
+            active,
+            panel,
+            form: form.clone(),
+            device,
+            authlib,
+            checked_server,
+            notice: state.account_notice.as_ref().map(Notice::of),
+            hint: form.hint,
+            width,
+        }
+    }
+
+    /// 当前账户行。
+    #[must_use]
+    pub fn active_row(&self) -> Option<&Row> {
+        self.active.and_then(|index| self.rows.get(index))
+    }
+
+    /// 有没有账户（空态判据）。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.rows.is_empty()
+    }
+
+    /// 皮肤预览区要画的那张图（当前账户有皮肤才画）。
+    #[must_use]
+    pub fn active_skin(&self) -> Option<&image::Handle> {
+        self.active_row().and_then(|row| row.skin.as_ref())
+    }
+}
+
+/// 单行。
+fn row_of(account: &AccountView, avatars: &mut Cache, lang: Lang) -> Row {
+    let text = lang.catalog();
+    let avatar: Avatar = avatars.resolve(&account.id, account.skin.as_ref());
+    let kind_label = match account.kind {
+        AccountKind::Microsoft => text.text(Key::AccountKindMicrosoft),
+        AccountKind::Authlib => text.text(Key::AccountKindAuthlib),
+        AccountKind::Offline => text.text(Key::AccountKindOffline),
+    };
+    let detail = if !account.server_url.is_empty() {
+        text.render(
+            Key::AccountServer,
+            &[("server", account.server_url.as_str())],
+        )
+    } else {
+        account.login_name.clone()
+    };
+    Row {
+        id: account.id.clone(),
+        name: account.name.clone(),
+        monogram: account.monogram(),
+        tone: account.monogram_tone(),
+        kind: account.kind,
+        kind_label: kind_label.to_string(),
+        added: text.render(Key::AccountAddedOn, &[("date", account.created.as_str())]),
+        detail,
+        active: account.active,
+        head: avatar.head,
+        skin: avatar.skin,
+    }
+}
diff --git a/crates/app-iced/src/pages/account/panels.rs b/crates/app-iced/src/pages/account/panels.rs
new file mode 100644
index 0000000..5feb6b9
--- /dev/null
+++ b/crates/app-iced/src/pages/account/panels.rs
@@ -0,0 +1,141 @@
+//! 两条登录流的面板态（微软设备码/授权码 + 第三方站校验/登录）。
+//!
+//! 从 `model.rs` 拆出来守 400 行硬线：这些类型是「UI 要画什么」的枚举，
+//! 判定逻辑（倒计时 → 已过期、服务发现 → 可用）也在这里，页面与表单只消费结果。
+//!
+//! ## 为什么这里**没有** `message` / `detail` 字段（M114 r3 / 复审 r2 P2-2）
+//!
+//! 后端的原始诊断串是中文人话，只该进日志。r2 时它们还以 `message`/`detail` 存在于此，
+//! 「页面把它们画上屏」只能靠一条**平行实现**的取样断言去拦（复审用变异证明那条断言是哑的）。
+//! 现在直接把字段删掉：视图**没有材料可画**，想画原文是编译错误——比任何测试都硬。
+//! 原文仍在 presenter 的 `DeviceLoginView/AuthlibLoginView::message` 里（只进 `eprintln!`）。
+
+use unlucky_presenter::dto::{AuthlibLoginView, DeviceLoginPhase, DeviceLoginView, LoginFailure};
+
+/// 微软登录面板要画什么（每态都不同，**不允许只有一个转圈**）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum DevicePanel {
+    /// 没有登录在跑
+    Hidden,
+    /// 正在申请设备码（进度文案由页面按 i18n 出）
+    Requesting,
+    /// 设备码等待用户操作
+    Code {
+        /// 用户码
+        code: String,
+        /// 验证链接
+        link: String,
+        /// 剩余秒数
+        remaining: Option<u64>,
+        /// 是否已过期
+        expired: bool,
+    },
+    /// 授权码流：等浏览器回调
+    Browser {
+        /// 授权链接（可复制）
+        link: String,
+        /// 剩余秒数
+        remaining: Option<u64>,
+        /// 是否已过期
+        expired: bool,
+    },
+    /// 失败（**只有原因码**；原文在 presenter 的日志里）
+    Failed {
+        /// 原因码（页面据此选 i18n）
+        failure: LoginFailure,
+    },
+    /// 成功
+    Succeeded {
+        /// 账户名
+        name: String,
+    },
+}
+
+/// 第三方轨面板的可见状态。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum AuthlibPanel {
+    /// 没在跑
+    Idle,
+    /// 正在校验/登录
+    Running,
+    /// 地址校验通过（服务发现拿到服务器名）
+    Ready {
+        /// 服务器名
+        server_name: String,
+    },
+    /// 失败（**只有原因码**；原文在 presenter 的日志里）
+    Failed {
+        /// 原因码（页面据此选 i18n）
+        failure: LoginFailure,
+    },
+    /// 成功
+    Succeeded {
+        /// 账户名
+        name: String,
+    },
+}
+
+/// 微软登录状态 → 面板态（倒计时与「已过期」都在这里定性，UI 只画）。
+pub(super) fn device_panel(view: &DeviceLoginView, remaining: Option<u64>) -> DevicePanel {
+    let expired = remaining == Some(0);
+    match view.phase {
+        DeviceLoginPhase::Idle => DevicePanel::Hidden,
+        DeviceLoginPhase::Requesting => DevicePanel::Requesting,
+        DeviceLoginPhase::Waiting => {
+            if view.user_code.trim().is_empty() {
+                DevicePanel::Browser {
+                    link: view.verification_uri.clone(),
+                    remaining,
+                    expired,
+                }
+            } else {
+                DevicePanel::Code {
+                    code: view.user_code.clone(),
+                    link: view.qr_link.clone(),
+                    remaining,
+                    expired,
+                }
+            }
+        }
+        DeviceLoginPhase::Failed => DevicePanel::Failed {
+            failure: view.failure.unwrap_or(LoginFailure::Other),
+        },
+        DeviceLoginPhase::Succeeded => DevicePanel::Succeeded {
+            name: view.account_name.clone(),
+        },
+    }
+}
+
+/// 第三方轨状态 → 面板态（顺带取出「校验通过的服务器名」）。
+pub(super) fn authlib_panel(view: &AuthlibLoginView) -> (AuthlibPanel, String) {
+    match view.phase {
+        DeviceLoginPhase::Idle => (AuthlibPanel::Idle, String::new()),
+        DeviceLoginPhase::Requesting => (AuthlibPanel::Running, String::new()),
+        DeviceLoginPhase::Waiting => (
+            AuthlibPanel::Ready {
+                server_name: view.server_name.clone(),
+            },
+            view.server_name.clone(),
+        ),
+        DeviceLoginPhase::Succeeded => (
+            AuthlibPanel::Succeeded {
+                name: view.account_name.clone(),
+            },
+            view.server_name.clone(),
+        ),
+        DeviceLoginPhase::Failed => (
+            AuthlibPanel::Failed {
+                failure: view.failure.unwrap_or(LoginFailure::Other),
+            },
+            String::new(),
+        ),
+    }
+}
+
+impl AuthlibPanel {
+    /// 是否正在跑（此时表单字段禁用，避免改了一半的地址被提交）。
+    #[must_use]
+    pub fn busy(&self) -> bool {
+        matches!(self, Self::Running { .. })
+    }
+}
diff --git a/crates/app-iced/src/pages/account/rows.rs b/crates/app-iced/src/pages/account/rows.rs
new file mode 100644
index 0000000..9e29ede
--- /dev/null
+++ b/crates/app-iced/src/pages/account/rows.rs
@@ -0,0 +1,274 @@
+//! 账户列表：当前账户卡片 + 全部账户行 + 皮肤预览区。
+
+use iced::widget::{column, container, image, row, space};
+use iced::{Alignment, ContentFit, Element, Length};
+
+use unlucky_design::color::Role;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+use unlucky_i18n::{Catalog, Key, Lang};
+
+use crate::app::components::buttons::{self, Button};
+use crate::pages::frame;
+use crate::theme::Ui;
+
+use crate::pages::account::{model::Page as Model, widgets};
+use crate::pages::Message as PageMessage;
+
+use super::Message as Account;
+
+/// 当前账户卡片（含皮肤预览区）。
+pub fn active_card<'a>(
+    ui: &'a Ui,
+    page: &'a Model,
+    catalog: Catalog,
+    lang: Lang,
+) -> Element<'a, PageMessage> {
+    let Some(current) = page.active_row() else {
+        return container(space::vertical()).into();
+    };
+    let _ = lang;
+
+    let mut actions = row![]
+        .spacing(ui.space(Space::X2))
+        .align_y(Alignment::Center);
+    actions = actions.push(buttons::text(
+        ui,
+        Button::new(
+            catalog.text(Key::AccountRelogin),
+            Account::Relogin(current.id.clone()).into_page(),
+        ),
+    ));
+    actions = actions.push(buttons::text(
+        ui,
+        Button::new(
+            catalog.text(Key::AccountRemove),
+            Account::Remove(current.id.clone()).into_page(),
+        ),
+    ));
+
+    let mut name_line = row![
+        frame::text_role(
+            ui,
+            TypeRole::TitleMedium,
+            true,
+            &current.name,
+            ui.color(Role::OnSurface),
+        ),
+        widgets::badge(ui, &current.kind_label, false),
+    ]
+    .spacing(ui.space(Space::X2))
+    .align_y(Alignment::Center);
+    if current.active {
+        name_line = name_line.push(widgets::badge(
+            ui,
+            catalog.text(Key::AccountActiveChip),
+            true,
+        ));
+    }
+
+    let mut identity = column![
+        name_line,
+        frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            &current.added,
+            ui.color(Role::OnSurfaceVariant),
+        ),
+    ]
+    .spacing(ui.space(Space::X1));
+    // 与列表行同源：服务器地址 / 登录名这一行两边都要有（tower 看图意见 ①）
+    if !current.detail.is_empty() {
+        identity = identity.push(frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            &current.detail,
+            ui.color(Role::OnSurfaceVariant),
+        ));
+    }
+
+    let left = row![
+        widgets::avatar(ui, current, widgets::AVATAR_ACTIVE),
+        container(identity).width(Length::Fill),
+        actions,
+    ]
+    .spacing(ui.space(Space::X4))
+    .align_y(Alignment::Center);
+
+    let mut body = column![
+        widgets::section(ui, catalog.text(Key::AccountCurrentTitle), None),
+        left,
+    ]
+    .spacing(ui.space(Space::X4));
+
+    match page.active_skin() {
+        Some(skin) => body = body.push(skin_preview(ui, skin.clone(), catalog)),
+        // 没有皮肤就**说出来**（离线轨永远没有；第三方轨没抓到也是这句），别让用户猜
+        None => body = body.push(skin_absent(ui, catalog)),
+    }
+
+    frame::card(ui, body)
+}
+
+/// 无皮肤时的皮肤区：一句话说清「没有可用皮肤」，与皮肤预览区同一位置、同一节奏。
+fn skin_absent<'a>(ui: &'a Ui, catalog: Catalog) -> Element<'a, PageMessage> {
+    column![
+        frame::text_role(
+            ui,
+            TypeRole::LabelMedium,
+            true,
+            catalog.text(Key::AccountSkinTitle),
+            ui.color(Role::OnSurface),
+        ),
+        frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            catalog.text(Key::AccountSkinNone),
+            ui.color(Role::OnSurfaceVariant),
+        ),
+        frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            catalog.text(Key::AccountSkinHint),
+            ui.color(Role::OnSurfaceVariant),
+        ),
+    ]
+    .spacing(ui.space(Space::X1))
+    .into()
+}
+
+/// 皮肤预览区：**原图直出**（64×64），旁边一句话说清「皮肤从哪来」。
+fn skin_preview<'a>(
+    ui: &'a Ui,
+    skin: iced::widget::image::Handle,
+    catalog: Catalog,
+) -> Element<'a, PageMessage> {
+    let size = ui.space(Space::X8) * 2.0;
+    row![
+        container(
+            image(skin)
+                .width(Length::Fixed(size))
+                .height(Length::Fixed(size))
+                .content_fit(ContentFit::Contain),
+        )
+        .width(Length::Fixed(size))
+        .height(Length::Fixed(size)),
+        column![
+            frame::text_role(
+                ui,
+                TypeRole::LabelMedium,
+                true,
+                catalog.text(Key::AccountSkinTitle),
+                ui.color(Role::OnSurface),
+            ),
+            frame::text_role(
+                ui,
+                TypeRole::BodySmall,
+                false,
+                catalog.text(Key::AccountSkinHint),
+                ui.color(Role::OnSurfaceVariant),
+            ),
+        ]
+        .spacing(ui.space(Space::X1)),
+    ]
+    .spacing(ui.space(Space::X4))
+    .align_y(Alignment::Center)
+    .into()
+}
+
+/// 「全部账户」列表。
+pub fn list<'a>(
+    ui: &'a Ui,
+    page: &'a Model,
+    catalog: Catalog,
+    lang: Lang,
+) -> Element<'a, PageMessage> {
+    let _ = lang;
+    let mut items = column![widgets::section(
+        ui,
+        catalog.text(Key::AccountListTitle),
+        None
+    )]
+    .spacing(ui.space(Space::X3));
+
+    for row in &page.rows {
+        items = items.push(item(ui, row, catalog));
+    }
+    frame::card(ui, items)
+}
+
+/// 一行账户。
+fn item<'a>(
+    ui: &'a Ui,
+    row: &'a crate::pages::account::model::Row,
+    catalog: Catalog,
+) -> Element<'a, PageMessage> {
+    let mut detail = column![
+        frame::text_role(
+            ui,
+            TypeRole::LabelMedium,
+            false,
+            &row.name,
+            ui.color(Role::OnSurface),
+        ),
+        frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            &row.added,
+            ui.color(Role::OnSurfaceVariant),
+        ),
+    ]
+    .spacing(ui.space(Space::X1));
+
+    if !row.detail.is_empty() {
+        detail = detail.push(frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            &row.detail,
+            ui.color(Role::OnSurfaceVariant),
+        ));
+    }
+
+    let mut trailing = row![widgets::badge(ui, &row.kind_label, false),]
+        .spacing(ui.space(Space::X2))
+        .align_y(Alignment::Center);
+
+    if row.active {
+        trailing = trailing.push(widgets::badge(
+            ui,
+            catalog.text(Key::AccountActiveChip),
+            true,
+        ));
+    } else {
+        trailing = trailing.push(buttons::text(
+            ui,
+            Button::new(
+                catalog.text(Key::AccountSwitch),
+                Account::Switch(row.id.clone()).into_page(),
+            ),
+        ));
+    }
+    trailing = trailing.push(buttons::text(
+        ui,
+        Button::new(
+            catalog.text(Key::AccountRemove),
+            Account::Remove(row.id.clone()).into_page(),
+        ),
+    ));
+
+    row![
+        widgets::avatar(ui, row, widgets::AVATAR_LIST),
+        container(detail).width(Length::Fill),
+        trailing,
+    ]
+    .spacing(ui.space(Space::X3))
+    .align_y(Alignment::Center)
+    .padding(iced::Padding::from([0.0, ui.space(Space::X2)]))
+    .into()
+}
diff --git a/crates/app-iced/src/pages/account/tests.rs b/crates/app-iced/src/pages/account/tests.rs
new file mode 100644
index 0000000..debfc41
--- /dev/null
+++ b/crates/app-iced/src/pages/account/tests.rs
@@ -0,0 +1,330 @@
+//! 账户页视图模型的判据（M114 的核心断言都在这里）。
+//!
+//! | 用例 | 抓得住什么 |
+//! |---|---|
+//! | `a_jwt_injected_into_events_never_reaches_the_page` | **凭据红线**：DTO → 状态 → 视图模型这一路漏了脱敏 |
+//! | `a_failure_with_a_provider_code_renders_english_and_the_code` | **语言泄漏（r1 p1）**：模型 + i18n 查表这一路又出现中文（视图层由类型禁画原文，见 `tests_text` 的边界说明） |
+//! | `the_device_code_panel_shows_a_countdown_and_expires` | 设备码「只转圈」/ 倒计时不是人话格式 |
+
+use unlucky_i18n::{Key, Lang};
+use unlucky_presenter::dto::{
+    AccountKind, AccountNotice, AccountNoticeCode, AccountView, AppEvent, AuthlibLoginView,
+    CoreEvent, DeviceLoginPhase, DeviceLoginView, LoginFailure, SkinImage,
+};
+use unlucky_presenter::state::AppState;
+
+use super::avatar::Cache;
+use super::model::{DevicePanel, Form, Page, Panel, Track};
+use super::tests_text::{has_cjk, on_screen};
+
+fn account(name: &str, kind: AccountKind, active: bool) -> AccountView {
+    AccountView {
+        id: format!("account:{name}"),
+        name: name.to_string(),
+        kind,
+        profile_id: "0f8f1d3c4b5a69788796a5b4c3d2e1f0".to_string(),
+        login_name: String::new(),
+        created: "2026-10-31 20:12".to_string(),
+        active,
+        server_url: String::new(),
+        skin: None,
+    }
+}
+
+fn build(state: &AppState, form: &Form) -> Page {
+    // 断言口径是英文界面（app 钉死 `Lang::En`）：英文目录下「视图里有中文」=「后端原文上屏了」。
+    // 宽度取验收窗口 1180（r2 起 `Page` 记中栏可用宽）。
+    Page::build(state, form, &mut Cache::default(), Lang::En, 1180.0)
+}
+
+const JWT: &str =
+    "eyJhbGciOiJSUzI1NiIsIng1dCI6IkFCQyJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.c2lnbmF0dXJlLXZhbHVl";
+
+/// **凭据红线（审核项）**：把 JWT 形状串注入事件 → 状态与视图模型里都不许出现。
+///
+/// 抓得住：presenter 状态层的脱敏被删（`AppState::apply_device_login` / `apply_authlib_login`）。
+/// 视图层不在此列：面板态里已无 `message`/`detail` 字段，想画原文是编译错误。
+#[test]
+fn a_jwt_injected_into_events_never_reaches_the_page() {
+    let mut state = AppState::new();
+    state.accounts = vec![account("Steve", AccountKind::Microsoft, true)];
+    // **绕过构造器**直接摆一个带 JWT 的 DTO：模拟「将来某个新构造器忘了脱敏」/「后端把原文塞进来」。
+    state.apply(AppEvent::Core(CoreEvent::DeviceLoginChanged(
+        DeviceLoginView {
+            phase: DeviceLoginPhase::Failed,
+            message: format!("微软返回错误：accessToken={JWT} refresh_token={JWT}"),
+            failure: Some(LoginFailure::Denied),
+            ..DeviceLoginView::new()
+        },
+    )));
+    state.apply(AppEvent::Core(CoreEvent::AuthlibLoginChanged(
+        AuthlibLoginView {
+            phase: DeviceLoginPhase::Failed,
+            server: "https://littleskin.cn/api/yggdrasil/".to_string(),
+            server_name: String::new(),
+            message: format!("服务器回包异常 {JWT}"),
+            failure: Some(LoginFailure::Denied),
+            account_name: String::new(),
+        },
+    )));
+
+    // ① 状态层已经脱敏（这一条抓得住「摘掉 state 层 redact」的变异）
+    assert!(
+        !state.device_login.message.contains("eyJ"),
+        "{}",
+        state.device_login.message
+    );
+    assert!(
+        !state.authlib_login.message.contains("eyJ"),
+        "{}",
+        state.authlib_login.message
+    );
+
+    // ② 上屏文案更不可能有它（页面根本不画原文）
+    let text = on_screen(&build(&state, &Form::new()));
+    assert!(!text.contains("eyJ"), "视图里出现了 JWT：{text}");
+    assert!(!text.contains("⟪redacted⟫"), "脱敏占位符也不该上屏：{text}");
+}
+
+/// **语言泄漏（复审 r1 p1）**：带 AADSTS 码的失败事件 → 英文取样里不许有中文，且要带 code。
+///
+/// 抓得住：`failure_body_key` 的码→key 映射被摘/接错；DTO 或状态层把中文混进模型字段。
+/// 抓不住（复审 r2 P2-2 实测过）：视图层把原文画上屏——这条断言是**平行实现**。
+/// 那道回归改由**类型**拦：`DevicePanel`/`AuthlibPanel` 已无 `message`/`detail` 字段。
+/// 也抓不住：catalog 里某条英文译文本身写得差（那只能人工审图）。
+#[test]
+fn a_failure_with_a_provider_code_renders_english_and_the_code() {
+    let mut state = AppState::new();
+    state.apply(AppEvent::Core(CoreEvent::DeviceLoginChanged(
+        DeviceLoginView {
+            phase: DeviceLoginPhase::Failed,
+            message:
+                "微软拒绝了这次登录：AADSTS7000218（HTTP 403）—— 应用白名单还没批准，或网络被拦截"
+                    .to_string(),
+            failure: Some(LoginFailure::NotWhitelisted),
+            ..DeviceLoginView::new()
+        },
+    )));
+    let page = build(&state, &Form::new());
+    let text = on_screen(&page);
+    assert!(!has_cjk(&text), "英文界面里出现了中文：{text}");
+    assert!(
+        text.contains("whitelist_pending"),
+        "面板要给稳定 code：{text}"
+    );
+    assert!(
+        text.to_lowercase().contains("approved"),
+        "要给出可读的英文原因：{text}"
+    );
+
+    // 第三方轨的失败同样只有 i18n + code
+    state.apply(AppEvent::Core(CoreEvent::AuthlibLoginChanged(
+        AuthlibLoginView {
+            phase: DeviceLoginPhase::Failed,
+            server: "https://example.invalid/".to_string(),
+            server_name: String::new(),
+            message: "服务器不可达：dns error".to_string(),
+            failure: Some(LoginFailure::Unreachable),
+            account_name: String::new(),
+        },
+    )));
+    let text = on_screen(&build(&state, &Form::new()));
+    assert!(!has_cjk(&text), "{text}");
+    assert!(text.contains("unreachable"), "{text}");
+}
+
+/// 空态：**三条轨道都有入口**，不是一张白页；且三张卡的标题各不相同。
+#[test]
+fn an_empty_account_list_offers_all_three_tracks() {
+    let state = AppState::new();
+    let page = build(&state, &Form::new());
+    assert!(page.is_empty());
+    assert_eq!(page.panel, Panel::None);
+    assert!(page.active_row().is_none());
+    let mut keys: Vec<&str> = Track::ALL
+        .iter()
+        .map(|track| track.title_key().name())
+        .collect();
+    keys.sort_unstable();
+    keys.dedup();
+    assert_eq!(keys.len(), 3);
+}
+
+/// 设备码：**倒计时是人话格式（mm:ss）**，过期后是「已过期」而不是继续转圈。
+#[test]
+fn the_device_code_panel_shows_a_countdown_and_expires() {
+    let mut state = AppState::new();
+    state.apply(AppEvent::Core(CoreEvent::DeviceLoginChanged(
+        DeviceLoginView::waiting("ABCD-EFGH", "https://www.microsoft.com/link", 900, ""),
+    )));
+    let page = build(&state, &Form::new());
+    match &page.device {
+        DevicePanel::Code {
+            code,
+            remaining,
+            expired,
+            ..
+        } => {
+            assert_eq!(code, "ABCD-EFGH");
+            assert_eq!(*remaining, Some(900));
+            assert!(!expired);
+        }
+        other => panic!("等待态应该是设备码面板，实际 {other:?}"),
+    }
+    let text = on_screen(&page);
+    assert!(text.contains("15:00"), "倒计时要画成 mm:ss：{text}");
+    assert!(!text.contains("900s"), "不再是 `900s left`：{text}");
+
+    // 起点往前挪 20 分钟 ⇒ 过期
+    state.device_login_started =
+        Some(std::time::Instant::now() - std::time::Duration::from_secs(1_200));
+    let page = build(&state, &Form::new());
+    match &page.device {
+        DevicePanel::Code {
+            remaining, expired, ..
+        } => {
+            assert_eq!(*remaining, Some(0));
+            assert!(*expired, "过期必须被标出来（面板要画「已过期，重试」）");
+        }
+        other => panic!("过期态仍是设备码面板，实际 {other:?}"),
+    }
+
+    // 授权码流也走同一条倒计时（没有用户码时是 Browser 面板）
+    state.apply(AppEvent::Core(CoreEvent::DeviceLoginChanged(
+        DeviceLoginView::browser_waiting("https://login.microsoftonline.com/x", 300, None),
+    )));
+    let page = build(&state, &Form::new());
+    assert!(matches!(page.device, DevicePanel::Browser { .. }));
+}
+
+/// 没有皮肤 = 首字母块（不是白块、不是假皮肤）；坏图也必须回落；无皮肤时**明说**。
+#[test]
+fn a_third_party_account_falls_back_to_the_monogram() {
+    let mut state = AppState::new();
+    state.accounts = vec![
+        account("Alex", AccountKind::Authlib, true),
+        account("Steve", AccountKind::Microsoft, false),
+    ];
+    let page = build(&state, &Form::new());
+    assert!(
+        page.rows.iter().all(|row| row.head.is_none()),
+        "没有皮肤就不许有图"
+    );
+    assert!(page.rows.iter().all(|row| !row.monogram.is_empty()));
+    assert!(page.active_skin().is_none(), "皮肤预览区没有图就不画图");
+    let text = on_screen(&page);
+    assert!(!has_cjk(&text));
+
+    // 塞一张坏图：解码失败 → 仍然回落到首字母块（不 panic、不白块）
+    state.accounts[0].skin = Some(SkinImage {
+        png: b"not a png".to_vec(),
+        source: "test".to_string(),
+    });
+    let page = build(&state, &Form::new());
+    assert!(page.rows[0].head.is_none());
+}
+
+/// 离线档案的说明**必须**带「无法连接启用正版验证的服务器」这条限定（中英都要）。
+#[test]
+fn the_offline_track_keeps_the_agreed_wording() {
+    for lang in Lang::ALL {
+        let catalog = lang.catalog();
+        for key in [Key::AccountTrackOfflineBody, Key::AccountOfflineWarning] {
+            let text = catalog.text(key);
+            assert!(
+                text.contains("cannot join servers that require a genuine Minecraft account")
+                    || text.contains("无法连接启用正版验证的服务器"),
+                "{} 的 {key:?} 丢了「仅本地/隔离网络测试用」口径：{text}",
+                lang.tag()
+            );
+            assert!(
+                !text.contains("migration") && !text.contains("迁移"),
+                "不许改写成「兼容旧启动器迁移」：{text}"
+            );
+        }
+    }
+}
+
+/// **离线轨的失败必须可见**（复审 r1 P2-2）：横幅进模型、文案走 i18n、原文不上屏。
+#[test]
+fn a_failed_offline_add_is_visible() {
+    let mut state = AppState::new();
+    state.apply(AppEvent::Core(CoreEvent::AccountNoticeChanged(Some(
+        AccountNotice::new(
+            AccountNoticeCode::OfflineNameInvalid,
+            "ab",
+            "离线名字必须是 3–16 位字母/数字/下划线，收到 \"ab\"",
+        ),
+    ))));
+    let page = build(&state, &Form::new());
+    let notice = page.notice.as_ref().expect("失败要有横幅");
+    assert_eq!(notice.code, AccountNoticeCode::OfflineNameInvalid);
+    assert!(notice.failure, "失败横幅要用 error 配色");
+    let text = on_screen(&page);
+    assert!(text.contains("3–16"), "要说清规则：{text}");
+    assert!(!has_cjk(&text), "英文界面不许出现中文：{text}");
+}
+
+/// 表单状态：三条轨道各开各的，密码关面板即清，三卡默认收起。
+#[test]
+fn the_form_tracks_are_independent() {
+    let mut form = Form::new();
+    assert!(!form.section_open, "有账号时三卡默认收起（P2-4）");
+    form.open(Track::Offline);
+    assert_eq!(form.panel, Panel::Offline);
+    assert!(!form.offline_ready(), "空名字不能提交");
+    form.offline_name = "ab".to_string();
+    assert!(
+        !form.offline_ready(),
+        "太短也不许提交（与 host 同一条规则）"
+    );
+    assert!(
+        !unlucky_presenter::dto::valid_offline_name("ab"),
+        "UI 判据 = host 那份规则"
+    );
+    form.offline_name = "Alex".to_string();
+    assert!(form.offline_ready());
+
+    form.open(Track::Authlib);
+    assert!(!form.authlib_ready(), "地址/登录名/密码缺一不可");
+    form.server = "https://littleskin.cn/api/yggdrasil/".to_string();
+    form.login = "alex".to_string();
+    form.password = "hunter2".to_string();
+    assert!(form.authlib_ready());
+    form.clear_secret();
+    assert!(form.password.is_empty());
+    assert!(!form.authlib_ready());
+}
+
+/// 登录阶段的可判据性：Requesting / Waiting / Failed 各自映射到不同面板。
+#[test]
+fn login_phases_map_to_distinct_panels() {
+    let mut state = AppState::new();
+    state.apply(AppEvent::Core(CoreEvent::DeviceLoginChanged(
+        DeviceLoginView {
+            phase: DeviceLoginPhase::Requesting,
+            message: "正在向微软申请设备码…".to_string(),
+            ..DeviceLoginView::new()
+        },
+    )));
+    let page = build(&state, &Form::new());
+    assert!(matches!(page.device, DevicePanel::Requesting));
+    // 进行中也只有 i18n（不再复读 presenter 的中文状态串）
+    assert!(!has_cjk(&on_screen(&page)));
+
+    state.apply(AppEvent::Core(CoreEvent::DeviceLoginChanged(
+        DeviceLoginView::failed("HTTP 403"),
+    )));
+    assert!(matches!(
+        build(&state, &Form::new()).device,
+        DevicePanel::Failed { .. }
+    ));
+
+    state.apply(AppEvent::Core(CoreEvent::DeviceLoginChanged(
+        DeviceLoginView::new(),
+    )));
+    assert!(matches!(
+        build(&state, &Form::new()).device,
+        DevicePanel::Hidden
+    ));
+}
diff --git a/crates/app-iced/src/pages/account/tests_text.rs b/crates/app-iced/src/pages/account/tests_text.rs
new file mode 100644
index 0000000..a10299b
--- /dev/null
+++ b/crates/app-iced/src/pages/account/tests_text.rs
@@ -0,0 +1,97 @@
+//! 「**模型这一层会给出什么**」的取样器：视图模型字段 + **按码做的 i18n 查表**，拼成一串。
+//!
+//! ## 边界（复审 r2 P2-2 订正，别把这条读成「视图覆盖」）
+//!
+//! 这是**平行实现**：它自己调 `catalog` 查表，**不调用** `login::panel` / `forms::status_line`，
+//! 也不遍历 iced 的元素树。所以它证明的是「模型 + i18n 表里没有中文」，**不证明**「视图真的照它画」。
+//!
+//! 视图层靠两道别的闸：
+//! 1. **类型**：`DevicePanel` / `AuthlibPanel` 里**没有** `message`/`detail` 字段（r3 删掉了），
+//!    想画后端原文是编译错误，不是测试问题；
+//! 2. **出图**：`DevDocs/artifacts/m114/after/*` 由人（tower/复审）逐张看。
+//!
+//! 为什么单独一个文件：`pages/account/tests.rs` 贴着 400 行硬线，而这段是**纯取样**
+//! （不给任何断言）——断言都在 `tests.rs` 里。
+
+use unlucky_i18n::{Key, Lang};
+use unlucky_presenter::dto::AccountNoticeCode;
+
+use super::login::failure_body_key;
+use super::model::{AuthlibPanel, DevicePanel, Hint, Page};
+
+/// 页面**会画什么**：模型里的数据 + 视图层对码的 i18n 查表结果。
+pub(super) fn on_screen(page: &Page) -> String {
+    let catalog = Lang::En.catalog();
+    let mut out = String::new();
+    for row in &page.rows {
+        out.push_str(&row.name);
+        out.push_str(&row.monogram);
+        out.push_str(&row.kind_label);
+        out.push_str(&row.added);
+        out.push_str(&row.detail);
+    }
+    out.push_str(&page.form.offline_name);
+    out.push_str(&page.form.server);
+    if let Some(notice) = &page.notice {
+        // 与 `widgets::banner` 同源：码 → i18n（主题名拼进去）
+        out.push_str(match notice.code {
+            AccountNoticeCode::OfflineNameInvalid => {
+                catalog.text(Key::AccountNoticeOfflineNameInvalid)
+            }
+            AccountNoticeCode::AccountExists => catalog.text(Key::AccountNoticeAccountExists),
+            AccountNoticeCode::StoreFailed => catalog.text(Key::AccountNoticeStoreFailed),
+            AccountNoticeCode::NotFound => catalog.text(Key::AccountNoticeNotFound),
+            AccountNoticeCode::Other => catalog.text(Key::AccountNoticeOther),
+            AccountNoticeCode::Added => catalog.text(Key::AccountNoticeAdded),
+            AccountNoticeCode::Removed => catalog.text(Key::AccountNoticeRemoved),
+            AccountNoticeCode::Switched => catalog.text(Key::AccountNoticeSwitched),
+        });
+        out.push_str(&notice.subject);
+    }
+    if let Some(hint) = page.hint {
+        out.push_str(match hint {
+            Hint::AuthlibReauth => catalog.text(Key::AccountHintAuthlibReauth),
+            Hint::OfflineNoRelogin => catalog.text(Key::AccountHintOfflineNoRelogin),
+        });
+    }
+    match &page.device {
+        DevicePanel::Hidden => {}
+        DevicePanel::Requesting => out.push_str(catalog.text(Key::AccountDeviceRequesting)),
+        DevicePanel::Code {
+            code,
+            link,
+            remaining,
+            expired,
+        } => {
+            out.push_str(code);
+            out.push_str(link);
+            if *expired {
+                out.push_str(catalog.text(Key::AccountDeviceExpired));
+            } else if let Some(secs) = remaining {
+                let clock = format!("{:02}:{:02}", secs / 60, secs % 60);
+                out.push_str(&catalog.render(Key::AccountDeviceCountdown, &[("time", &clock)]));
+            }
+        }
+        DevicePanel::Browser { link, .. } => out.push_str(link),
+        DevicePanel::Failed { failure } => {
+            out.push_str(catalog.text(failure_body_key(*failure)));
+            out.push_str(&catalog.render(Key::AccountFailureCode, &[("code", failure.code())]));
+        }
+        DevicePanel::Succeeded { name } => {
+            out.push_str(&catalog.render(Key::AccountLoginSucceeded, &[("name", name)]));
+        }
+    }
+    match &page.authlib {
+        AuthlibPanel::Idle => {}
+        AuthlibPanel::Running => out.push_str(catalog.text(Key::AccountServerChecking)),
+        AuthlibPanel::Ready { server_name } => out.push_str(server_name),
+        AuthlibPanel::Failed { failure } => out.push_str(failure.code()),
+        AuthlibPanel::Succeeded { name } => out.push_str(name),
+    }
+    out
+}
+
+/// 有没有中日韩统一表意文字（语言泄漏的最直接判据）。
+pub(super) fn has_cjk(text: &str) -> bool {
+    text.chars().any(|c| matches!(c, '\u{3400}'..='\u{4DBF}' | '\u{4E00}'..='\u{9FFF}' | '\u{3000}'..='\u{303F}' | '\u{FF00}'..='\u{FFEF}'))
+}
diff --git a/crates/app-iced/src/pages/account/widgets.rs b/crates/app-iced/src/pages/account/widgets.rs
new file mode 100644
index 0000000..d378036
--- /dev/null
+++ b/crates/app-iced/src/pages/account/widgets.rs
@@ -0,0 +1,386 @@
+//! 本页小件：头像块（首字母块 / 真图）、章节标题、轨道徽标。
+//!
+//! ## 令牌纪律
+//!
+//! 本文件**零**色值 / 字号 / 半径字面量：颜色一律 [`Ui::color`]，尺寸走 `Space` /
+//! `LayoutMetrics` / `ui.style(..)`。首字母块的「色号」也只是**挑哪一个角色**，
+//! 不是一个具体颜色——深浅两套主题各自成立。
+
+use iced::widget::text::LineHeight;
+use iced::widget::{container, image, row, text};
+use iced::{Alignment, Background, Border, ContentFit, Element, Length, Pixels};
+
+use unlucky_design::color::Role;
+use unlucky_design::component_map::Component;
+use unlucky_design::elevation::MaterialLayer;
+use unlucky_design::icons::IconKind;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+use unlucky_i18n::{Catalog, Key};
+use unlucky_presenter::dto::AccountNoticeCode;
+
+use crate::pages::frame;
+use crate::pages::frame::ICON_PX;
+use crate::theme::Ui;
+
+use crate::app::components::buttons::{self, Button};
+
+use crate::pages::Message as PageMessage;
+use crate::pages::Message;
+
+use super::model::{Hint, Notice, Row};
+use super::Message as Account;
+
+/// 头像块的可选尺寸（列表 40 / 当前账户 56）。
+pub const AVATAR_LIST: f32 = 40.0;
+/// 当前账户卡片上的头像边长。
+pub const AVATAR_ACTIVE: f32 = 56.0;
+
+/// 色号 → (底色, 字色) 角色对。
+///
+/// 只有「挑角色」这一步是硬的：六个色号对应六个容器角色，深浅主题各有一套值，
+/// 所以同一个账户在两种主题下都成立，也不会撞出低对比。
+fn tone(ui: &Ui, tone: u8) -> (iced::Color, iced::Color) {
+    match tone % 6 {
+        0 => (
+            ui.color(Role::PrimaryContainer),
+            ui.color(Role::OnPrimaryContainer),
+        ),
+        1 => (
+            ui.color(Role::SecondaryContainer),
+            ui.color(Role::OnSecondaryContainer),
+        ),
+        2 => (
+            ui.color(Role::TertiaryContainer),
+            ui.color(Role::OnTertiaryContainer),
+        ),
+        3 => (
+            ui.color(Role::SurfaceContainerHighest),
+            ui.color(Role::OnSurface),
+        ),
+        4 => (ui.color(Role::PrimaryFixed), ui.color(Role::OnPrimaryFixed)),
+        _ => (
+            ui.color(Role::SurfaceVariant),
+            ui.color(Role::OnSurfaceVariant),
+        ),
+    }
+}
+
+/// 提示条的语义档（决定图标块与图标字形用哪一对角色）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Tone {
+    /// 失败（`ErrorContainer` / `OnErrorContainer` 图标块 + `Error` 图形）
+    Error,
+    /// 成功/信息（`SecondaryContainer` / `OnSecondaryContainer` 图标块 + `Check` 图形）
+    Info,
+}
+
+/// **M3 内联提示条**（账户页横幅与登录失败面板共用）。
+///
+/// ## 为什么不是通栏实心色块（tower r2 意见）
+///
+/// r1 的失败面板把 `errorContainer` 铺满整条内容宽——角色本身是对的（复审按像素采样反证过：
+/// 暗色取到容器角色 30 档、浅色取到 90 档，与设计层逐值一致），但**面积**让它像一条通栏告警带。
+/// 现在改成 M3 的 alert 形态：面板底走 `SurfaceContainerHigh` + 1dp 描边，
+/// `ErrorContainer` / `OnErrorContainer` 只作左侧**图标块**的强调（成功档换成 Secondary 容器），
+/// 标题用 `OnSurface`、正文与 code 行用 `OnSurfaceVariant`。语义仍由角色表达，视觉不再是红条。
+pub fn alert<'a>(
+    ui: &'a Ui,
+    tone: Tone,
+    title: &'a str,
+    body: String,
+    code: Option<String>,
+    actions: Vec<Element<'a, PageMessage>>,
+) -> Element<'a, PageMessage> {
+    let (chip_bg, chip_fg, glyph, glyph_color) = match tone {
+        Tone::Error => (
+            ui.color(Role::ErrorContainer),
+            ui.color(Role::OnErrorContainer),
+            IconKind::Error,
+            ui.color(Role::Error),
+        ),
+        Tone::Info => (
+            ui.color(Role::SecondaryContainer),
+            ui.color(Role::OnSecondaryContainer),
+            IconKind::Check,
+            ui.color(Role::OnSecondaryContainer),
+        ),
+    };
+    let _ = chip_fg;
+
+    let chip = container(frame::glyph_box(glyph, glyph_color, ICON_PX))
+        .width(Length::Fixed(ui.space(Space::X8)))
+        .height(Length::Fixed(ui.space(Space::X8)))
+        .align_x(Alignment::Center)
+        .align_y(Alignment::Center)
+        .style(move |_theme| container::Style {
+            background: Some(Background::Color(chip_bg)),
+            border: Border {
+                radius: ui.radius(ShapeScale::Full, ui.space(Space::X8)),
+                ..Border::default()
+            },
+            ..container::Style::default()
+        });
+
+    // 标题与 `Code: …` 同**一行**：`Code` 只是取证用的稳定 id，不值得占一整行高度
+    // （1180×760 下多一行就把「All accounts」第三行挤到折线下）。
+    let mut title_row = iced::widget::Row::new()
+        .spacing(ui.space(Space::X2))
+        .align_y(Alignment::Center)
+        .push(frame::text_role(
+            ui,
+            TypeRole::TitleSmall,
+            true,
+            title,
+            ui.color(Role::OnSurface),
+        ));
+    if let Some(code) = code {
+        title_row = title_row.push(frame::text_role_owned(
+            ui,
+            TypeRole::LabelSmall,
+            false,
+            code,
+            ui.color(Role::OnSurfaceVariant),
+        ));
+    }
+
+    let mut lines = iced::widget::Column::new().spacing(ui.space(Space::X1));
+    lines = lines.push(title_row);
+    lines = lines.push(frame::text_role_owned(
+        ui,
+        TypeRole::BodySmall,
+        false,
+        body,
+        ui.color(Role::OnSurfaceVariant),
+    ));
+
+    container(
+        row![
+            chip,
+            container(lines).width(Length::Fill),
+            row(actions)
+                .spacing(ui.space(Space::X2))
+                .align_y(Alignment::Center),
+        ]
+        .spacing(ui.space(Space::X3))
+        .align_y(Alignment::Center)
+        .width(Length::Fill),
+    )
+    .width(Length::Fill)
+    .padding(ui.metrics().card_padding)
+    .style(move |_theme| container::Style {
+        background: Some(Background::Color(ui.layer(MaterialLayer::Card))),
+        border: ui.outlined(Component::OutlinedCard.spec().shape),
+        ..container::Style::default()
+    })
+    .into()
+}
+
+/// 账户页横幅：添加/删除/切换的结果（**页面上真实可见的控件**，不是 toast）。
+///
+/// 为什么必须有它：app-iced 不渲染 toast（复审 r1 P2-2），离线名字不合法/重名/落盘失败时
+/// 用户原本什么都看不到。文案按 `AccountNoticeCode` 查 i18n，后端原文不进 UI。
+pub fn banner<'a>(ui: &'a Ui, notice: &'a Notice, catalog: Catalog) -> Element<'a, PageMessage> {
+    let tone = if notice.failure {
+        Tone::Error
+    } else {
+        Tone::Info
+    };
+    let title = if notice.failure {
+        catalog.text(Key::AccountNoticeTitleFailed)
+    } else {
+        catalog.text(Key::AccountNoticeTitleDone)
+    };
+    let message = notice_text(notice, catalog);
+    let dismiss = buttons::text(
+        ui,
+        Button::new(
+            catalog.text(Key::AccountNoticeDismiss),
+            Account::DismissNotice.into_page(),
+        ),
+    );
+    // 只有失败才显示稳定 code（成功态列一串 `added` 是噪音）
+    let code = notice
+        .failure
+        .then(|| catalog.render(Key::AccountFailureCode, &[("code", notice.code.code())]));
+    alert(ui, tone, title, message, code, vec![dismiss])
+}
+
+/// 横幅文案（码 → i18n；主题名拼进带占位符的几句）。
+fn notice_text(notice: &Notice, catalog: Catalog) -> String {
+    let name = notice.subject.as_str();
+    match notice.code {
+        AccountNoticeCode::Added => catalog.render(Key::AccountNoticeAdded, &[("name", name)]),
+        AccountNoticeCode::Removed => catalog.render(Key::AccountNoticeRemoved, &[("name", name)]),
+        AccountNoticeCode::Switched => {
+            catalog.render(Key::AccountNoticeSwitched, &[("name", name)])
+        }
+        AccountNoticeCode::OfflineNameInvalid => catalog
+            .text(Key::AccountNoticeOfflineNameInvalid)
+            .to_string(),
+        AccountNoticeCode::AccountExists => {
+            catalog.text(Key::AccountNoticeAccountExists).to_string()
+        }
+        AccountNoticeCode::StoreFailed => catalog.text(Key::AccountNoticeStoreFailed).to_string(),
+        AccountNoticeCode::NotFound => catalog.text(Key::AccountNoticeNotFound).to_string(),
+        AccountNoticeCode::Other => catalog.text(Key::AccountNoticeOther).to_string(),
+    }
+}
+
+/// 一次性引导（重新登录时告诉用户下一步）。
+pub fn hint<'a>(
+    ui: &'a Ui,
+    hint: Hint,
+    page: &'a super::Page,
+    catalog: Catalog,
+) -> Element<'a, PageMessage> {
+    let message = match hint {
+        Hint::AuthlibReauth => catalog.render(
+            Key::AccountHintAuthlibReauth,
+            &[("server", page.form.server.as_str())],
+        ),
+        Hint::OfflineNoRelogin => catalog.text(Key::AccountHintOfflineNoRelogin).to_string(),
+    };
+    container(frame::text_role_owned(
+        ui,
+        TypeRole::BodySmall,
+        false,
+        message,
+        ui.color(Role::OnSurfaceVariant),
+    ))
+    .width(Length::Fill)
+    .into()
+}
+
+/// 头像块：有真图就画图（圆角裁切），没有就画**首字母块**。
+///
+/// 三条铁律：① 图解码失败一定回到首字母块（不白块）；② 首字母块的字来自 `AccountView::monogram`，
+/// 永不空串；③ 两者尺寸完全一致，切换时不跳版。
+pub fn avatar<'a>(ui: &'a Ui, row: &Row, size: f32) -> Element<'a, Message> {
+    if let Some(handle) = &row.head {
+        return container(
+            image(handle.clone())
+                .width(Length::Fixed(size))
+                .height(Length::Fixed(size))
+                .content_fit(ContentFit::Cover),
+        )
+        .width(Length::Fixed(size))
+        .height(Length::Fixed(size))
+        .style(move |_theme| container::Style {
+            border: Border {
+                radius: ui.radius(ShapeScale::Full, size),
+                ..Border::default()
+            },
+            ..container::Style::default()
+        })
+        .into();
+    }
+    monogram(ui, &row.monogram, row.tone, size)
+}
+
+/// 首字母块（没有皮肤时的头像位）。
+pub fn monogram<'a>(ui: &'a Ui, letter: &str, tone_index: u8, size: f32) -> Element<'a, Message> {
+    let (background, foreground) = tone(ui, tone_index);
+    let style = ui.emphasized(TypeRole::TitleMedium);
+    container(
+        text(letter.to_string())
+            .size(style.size_px)
+            .line_height(LineHeight::Absolute(Pixels(style.line_height_px)))
+            .font(ui.font_of(style))
+            .color(foreground),
+    )
+    .width(Length::Fixed(size))
+    .height(Length::Fixed(size))
+    .align_x(Alignment::Center)
+    .align_y(Alignment::Center)
+    .style(move |_theme| container::Style {
+        background: Some(Background::Color(background)),
+        border: Border {
+            radius: ui.radius(ShapeScale::Full, size),
+            ..Border::default()
+        },
+        ..container::Style::default()
+    })
+    .into()
+}
+
+/// 章节标题（`TitleMedium` + 可选副文案）。
+pub fn section<'a>(ui: &'a Ui, title: &'a str, support: Option<&'a str>) -> Element<'a, Message> {
+    let mut column = iced::widget::column![frame::text_role(
+        ui,
+        TypeRole::TitleMedium,
+        true,
+        title,
+        ui.color(Role::OnSurface),
+    )]
+    .spacing(ui.space(Space::X1));
+    if let Some(support) = support {
+        column = column.push(frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            support,
+            ui.color(Role::OnSurfaceVariant),
+        ));
+    }
+    column.into()
+}
+
+/// 轨道徽标（小药丸：`LabelMedium` + `SecondaryContainer`）。
+pub fn badge<'a>(ui: &'a Ui, label: &'a str, active: bool) -> Element<'a, Message> {
+    let (background, foreground) = if active {
+        (
+            ui.color(Role::SecondaryContainer),
+            ui.color(Role::OnSecondaryContainer),
+        )
+    } else {
+        (
+            ui.color(Role::SurfaceContainerHighest),
+            ui.color(Role::OnSurfaceVariant),
+        )
+    };
+    let style = ui.style(TypeRole::LabelMedium);
+    container(
+        text(label.to_string())
+            .size(style.size_px)
+            .line_height(LineHeight::Absolute(Pixels(style.line_height_px)))
+            .font(ui.font_of(style))
+            .color(foreground),
+    )
+    .padding(iced::Padding::from([0.0, ui.space(Space::X2)]))
+    .height(ui.metrics().control_height - ui.space(Space::X2) * 2.0)
+    .align_y(Alignment::Center)
+    .style(move |_theme| container::Style {
+        background: Some(Background::Color(background)),
+        border: Border {
+            radius: ui.radius(ShapeScale::Full, ui.metrics().control_height),
+            ..Border::default()
+        },
+        ..container::Style::default()
+    })
+    .into()
+}
+
+/// 一条「标签 + 值」的元信息行（列表行副文案之外的结构化信息）。
+pub fn meta_line<'a>(ui: &'a Ui, label: &'a str, value: &'a str) -> Element<'a, Message> {
+    row![
+        frame::text_role(
+            ui,
+            TypeRole::LabelSmall,
+            false,
+            label,
+            ui.color(Role::OnSurfaceVariant),
+        ),
+        frame::text_role(
+            ui,
+            TypeRole::LabelMedium,
+            false,
+            value,
+            ui.color(Role::OnSurface)
+        ),
+    ]
+    .spacing(ui.space(Space::X2))
+    .align_y(Alignment::Center)
+    .into()
+}
diff --git a/crates/app-iced/src/pages/agent/conversation.rs b/crates/app-iced/src/pages/agent/conversation.rs
new file mode 100644
index 0000000..84980b6
--- /dev/null
+++ b/crates/app-iced/src/pages/agent/conversation.rs
@@ -0,0 +1,338 @@
+//! **会话视图组件**：右栗面板与 `Route::Agent` 独立页的**同一份**对话 UI。
+//!
+//! ## 输入契约（纯数据入、消息出）
+//!
+//! ```text
+//! Conversation { messages, busy, unread, confirm, failure, draft, blank, rail, host, focus }
+//!        ──view()──▶  Element<Message>
+//! ```
+//!
+//! - **入**：全部是**借用**的纯数据。会话三件（`messages` / `busy` / `unread` / `confirm`）
+//!   直接从 presenter 的 `AgentRail` 借来（M119），组件自己不持有会话状态；`failure` 是 app 层
+//!   备好的**展示输入**（标题是 catalog 键、正文是已脱敏串），见 `super::Failure`。
+//! - **出**：控件树只发 [`super::Message`]（`Collapse` / `Detach` / `Dock` / `Submit` / `Stop` /
+//!   `Confirm` / `Edit` / `Expand`），app 层再包一层 `Message::Agent(..)`。于是同一份视图可以被
+//!   两个宿主摆在不同宽度里，而「点了发生什么」只有一处实现（`app/update/agent.rs`）。
+//!
+//! ## 两个宿主只差「外壳」
+//!
+//! | 宿主 | 谁调用 | 给的宽度 | 差别 |
+//! |---|---|---|---|
+//! | [`Host::Rail`] | [`super::docked`]（右栗面板） | 280~360（本组件吃 Fill） | 头部动作是 `⌄` 收起 + `⇥` 拆出 |
+//! | [`Host::Page`] | [`super::page`]（独立页） | 行宽上限 424 | 头部动作是 `⇤` 收回；标题是页级标题 |
+//!
+//! **判据不是「长得像」而是「同一个函数」**：`tests::both_hosts_render_the_same_conversation`
+//! 用源码扫描钉住「两个宿主都只通过 [`view`] 画对话」，`super::mod` 里不许出现第二份气泡/输入框装配。
+//!
+//! ## 控件与可达性（任务第 4 条逐项）
+//!
+//! | 要求 | 落点 |
+//! |---|---|
+//! | 输入框多行 | `text_editor`（真多行，不是 `text_input` 的单行） |
+//! | Enter 发送 / Shift+Enter 换行 | [`composer`] 的 `key_binding`：`Binding::Custom(Submit)` vs `Binding::Enter`，用 `modifiers.shift()` 分流（**只有输入框聚焦时生效**，不会抢别处的 Enter） |
+//! | 发送禁用态 | 草稿空白或流式中 → `Button::disabled`（M3 的 10% 容器 / 38% 内容，不是自创灰色） |
+//! | 流式中断 | 只在 `busy` 时出现 `Stop`（`IconKind::Close` + 文字标签） |
+//! | 未读点 | 折叠条上的圆点（[`super::strip`]）+ 面板头部的「N unread」胶囊 |
+//! | 失败态 | [`banners::failure`]：具名标题（catalog）+ 已脱敏正文（M119） |
+//! | 写操作确认 | [`banners::confirm`]：请求摘要 + Allow / Deny 两个文字按钮（M119） |
+//! | `⌄` / `⇥` / `⇤` | 头部两个文字按钮，图标只是**前导**，标签一律可读 |
+//! | 键盘 | `Esc` 收栗 / `Tab` 走焦点环 / `Enter` 激活焦点键（订阅在 `app/subscription.rs`） |
+
+use iced::widget::text_editor;
+use iced::widget::{column, container, row, rule, space, text};
+use iced::{Background, Border, Element, Length, Padding, Theme};
+
+use unlucky_design::color::Role;
+use unlucky_design::icons::IconKind;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+use unlucky_i18n::{Catalog, Key};
+
+use unlucky_presenter::dto::{ChatMessage, ConfirmRequest};
+
+use crate::app::components::buttons::{self, Button};
+use crate::app::components::interaction::Interaction;
+use crate::theme::Ui;
+
+use super::state::{Focus, RailState};
+use super::{Disclaimer, Failure, Message};
+
+mod banners;
+mod composer;
+mod transcript;
+
+pub(super) use composer::{text_role, text_role_owned};
+
+/// 会话视图落在哪种外壳里（只影响头部动作与标题密度，**不影响**对话本体）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Host {
+    /// 右侧栏（280~360）。
+    Rail,
+    /// 独立页（列宽 ≤424）。
+    Page,
+}
+
+/// 会话视图的**输入契约**（见模块文档；全部是借用的纯数据）。
+#[derive(Clone, Copy)]
+pub struct Conversation<'a> {
+    /// 会话内容（presenter 的 `AgentRail::messages`，零条 = 空会话，画引导空态）。
+    pub messages: &'a [ChatMessage],
+    /// 输入框内容（iced 的 `text_editor` 自己持有编辑状态）。
+    pub draft: &'a text_editor::Content,
+    /// 是否在流式回复 / 有待确认写操作（来自 rail 的 `busy`：决定 `Stop` 出现与 `Send` 禁用）。
+    pub busy: bool,
+    /// 未读数（>0 时头部画胶囊；来自 rail 的 `unread`）。
+    pub unread: usize,
+    /// 草稿是否空白（发送键的禁用判据，由 `AgentUi::draft_is_blank` 给）。
+    pub blank: bool,
+    /// 待确认的写操作（`Some` = 画确认条）。
+    pub confirm: Option<&'a ConfirmRequest>,
+    /// 失败横幅（`Some` = 画具名错误；见 [`Failure`]）。
+    pub failure: Option<Failure<'a>>,
+    /// 「这是模拟助手」的**四处文案**（副标题 / 占位符 / 空态正文 / 标题胶囊），
+    /// 全部由 [`Disclaimer::of`] 一次算好——视图里没有第二种取词路径。
+    ///
+    /// M119 r1 / r2 复审 P2-1：生产默认后端是脚本化 rig，界面上曾**没有任何模拟标识**；
+    /// 上一轮又只有标题胶囊认这个开关，另外三处会反方向地留在「没接真实模型」上。
+    pub note: Disclaimer<'a>,
+    /// 三档状态（决定头部画哪组动作）。
+    pub rail: RailState,
+    /// 宿主。
+    pub host: Host,
+    /// 键盘软焦点（`None` = 用户在用鼠标，**不画焦点环**）。
+    ///
+    /// 为什么不直接给 `Focus`：焦点环是键盘巡航的可视证据，鼠标操作时还挂着 10% 状态层会让人
+    /// 以为那是一个 tonal 按钮（r1 出图实测）。`AgentUi::keyboard_mode` 就是这道闸。
+    pub focus: Option<Focus>,
+}
+
+/// 画会话视图（**右栗与独立页的唯一实现**）。
+pub fn view<'a>(ui: &'a Ui, spec: Conversation<'a>, catalog: Catalog) -> Element<'a, Message> {
+    let mut body = column![header(ui, spec, catalog), divider(ui)]
+        .spacing(ui.space(Space::X2))
+        .width(Length::Fill)
+        .height(Length::Fill);
+
+    // 失败横幅放在会话**上方**：错误是这一轮的结果，比历史更需要先看见（M119）。
+    if let Some(failure) = spec.failure {
+        body = body.push(banners::failure(ui, failure, catalog));
+    }
+
+    body = body.push(if spec.messages.is_empty() {
+        transcript::empty(ui, catalog, spec.note.empty_body)
+    } else {
+        transcript::list(ui, spec, catalog)
+    });
+
+    // 确认条贴着输入区（动作在下面，读完就能按）。
+    if let Some(request) = spec.confirm {
+        body = body.push(banners::confirm(ui, request, catalog, spec.focus));
+    }
+
+    body.push(divider(ui))
+        .push(composer::composer(ui, spec, catalog))
+        .into()
+}
+
+// ---------------------------------------------------------------- 头部
+
+fn header<'a>(ui: &'a Ui, spec: Conversation<'a>, catalog: Catalog) -> Element<'a, Message> {
+    let mut title = row![text_role(
+        ui,
+        TypeRole::TitleLarge,
+        true,
+        catalog.text(Key::AgentTitle),
+        ui.color(Role::OnSurface),
+        Length::Shrink,
+    )]
+    .spacing(ui.space(Space::X2))
+    .align_y(iced::Alignment::Center);
+    // 常驻标记：与标题同一行，不点开、不 hover、不藏在设置里（P2-1 的判据）
+    if spec.note.simulated {
+        title = title.push(simulated_chip(ui, catalog));
+    }
+    title = title.push(unread_badge(ui, spec.unread, catalog));
+
+    let titles = column![
+        title,
+        text_role(
+            ui,
+            TypeRole::LabelMedium,
+            false,
+            spec.note.subtitle,
+            ui.color(Role::OnSurfaceVariant),
+            Length::Fill,
+        ),
+    ]
+    .spacing(ui.space(Space::X1))
+    .width(Length::Fill);
+
+    // 独立页的头部与页面同一套（标题在左、动作在右）；右栗太窄，动作单独一行，免得挤成两截。
+    match spec.host {
+        Host::Rail => column![
+            titles,
+            row![actions(ui, spec, catalog)]
+                .width(Length::Fill)
+                .spacing(ui.space(Space::X2)),
+        ]
+        .spacing(ui.space(Space::X2))
+        .width(Length::Fill)
+        .into(),
+        Host::Page => row![
+            titles,
+            row![actions(ui, spec, catalog)]
+                .spacing(ui.space(Space::X2))
+                .align_y(iced::Alignment::Center),
+        ]
+        .width(Length::Fill)
+        .align_y(iced::Alignment::Center)
+        .into(),
+    }
+}
+
+/// 头部动作：`⌄` 收起 / `⇥` 拆出（停靠时）或 `⇤` 收回（独立页）。
+///
+/// 每个按钮都带**文字标签**（图标只做前导）：任务要求「不得只有图标」。焦点环用
+/// `Interaction::Focused`（组件的 10% 状态层），键序见 [`Focus`]。
+fn actions<'a>(ui: &'a Ui, spec: Conversation<'a>, catalog: Catalog) -> Element<'a, Message> {
+    let mut items: Vec<Element<'a, Message>> = Vec::new();
+
+    // 页宿主只有一个正确动作：收回右栗。这里先按**宿主**分流（而不是先按档位）是结构性兜底：
+    // 就算哪天档位同步漏了，独立页也不会再出现「Open assistant / Collapse / Pop out」这种
+    // 右栗才该有的按钮（复审 r1 P2-1 的可见症状）。
+    if spec.host == Host::Page {
+        return row![label_button(
+            ui,
+            catalog.text(Key::AgentDock),
+            IconKind::ChevronLeft,
+            Some(Message::Dock),
+            spec.focus == Some(Focus::Detach),
+        )]
+        .spacing(ui.space(Space::X2))
+        .align_y(iced::Alignment::Center)
+        .into();
+    }
+
+    match spec.rail {
+        RailState::Collapsed => items.push(label_button(
+            ui,
+            catalog.text(Key::AgentOpen),
+            IconKind::ChevronRight,
+            Some(Message::Expand),
+            spec.focus == Some(Focus::Collapse),
+        )),
+        RailState::Expanded => {
+            items.push(label_button(
+                ui,
+                catalog.text(Key::AgentCollapse),
+                IconKind::ChevronDown,
+                Some(Message::Collapse),
+                spec.focus == Some(Focus::Collapse),
+            ));
+            items.push(label_button(
+                ui,
+                catalog.text(Key::AgentDetach),
+                IconKind::Expand,
+                Some(Message::Detach),
+                spec.focus == Some(Focus::Detach),
+            ));
+        }
+        RailState::Detached => items.push(label_button(
+            ui,
+            catalog.text(Key::AgentDock),
+            IconKind::ChevronLeft,
+            Some(Message::Dock),
+            spec.focus == Some(Focus::Detach),
+        )),
+    }
+
+    row(items)
+        .spacing(ui.space(Space::X2))
+        .align_y(iced::Alignment::Center)
+        .into()
+}
+
+fn label_button<'a>(
+    ui: &'a Ui,
+    label: &'a str,
+    icon: IconKind,
+    on_press: Option<Message>,
+    focused: bool,
+) -> Element<'a, Message> {
+    let button = match on_press {
+        Some(message) => Button::new(label, message).leading(icon),
+        None => Button::disabled(label).leading(icon),
+    };
+    buttons::text(ui, focused_state(button, focused))
+}
+
+/// 焦点环：键盘走到这一格时叠 10% 的 `Focused` 状态层（组件库的取证状态也是它）。
+pub(super) fn focused_state<'a>(button: Button<'a, Message>, focused: bool) -> Button<'a, Message> {
+    if focused {
+        button.state(Interaction::Focused)
+    } else {
+        button
+    }
+}
+
+/// 「模拟」标记：`SurfaceVariant` / `OnSurfaceVariant` 的 tonal 小胶囊（中性信息，不是告警）。
+fn simulated_chip<'a>(ui: &'a Ui, catalog: Catalog) -> Element<'a, Message> {
+    let style = ui.style(TypeRole::LabelMedium);
+
+    container(
+        text(catalog.text(Key::AgentSimulated))
+            .size(style.size_px)
+            .font(ui.font_of(style))
+            .color(ui.color(Role::OnSurfaceVariant)),
+    )
+    .padding(Padding::from([ui.space(Space::X1), ui.space(Space::X2)]))
+    .style(move |_theme| container::Style {
+        background: Some(Background::Color(ui.color(Role::SurfaceVariant))),
+        border: Border {
+            radius: ui.radius(ShapeScale::Full, ui.metrics().control_height / 2.0),
+            ..Border::default()
+        },
+        ..container::Style::default()
+    })
+    .into()
+}
+
+fn unread_badge<'a>(ui: &'a Ui, unread: usize, catalog: Catalog) -> Element<'a, Message> {
+    if unread == 0 {
+        return space::horizontal().into();
+    }
+
+    let count = unread.to_string();
+    let label = catalog.render(Key::AgentUnread, &[("count", count.as_str())]);
+    let style = ui.style(TypeRole::LabelMedium);
+
+    container(
+        text(label)
+            .size(style.size_px)
+            .font(ui.font_of(style))
+            .color(ui.color(Role::OnSecondaryContainer)),
+    )
+    .padding(Padding::from([ui.space(Space::X1), ui.space(Space::X2)]))
+    .style(move |_theme| container::Style {
+        background: Some(Background::Color(ui.color(Role::SecondaryContainer))),
+        border: Border {
+            radius: ui.radius(ShapeScale::Full, ui.metrics().control_height / 2.0),
+            ..Border::default()
+        },
+        ..container::Style::default()
+    })
+    .into()
+}
+
+/// 一像素分隔线（`pages::frame::divider` 绑在 `pages::Message` 上，这里要自己的消息类型）。
+fn divider<'a>(ui: &'a Ui) -> Element<'a, Message> {
+    rule::horizontal::<Theme>(ui.metrics().divider_thickness)
+        .style(move |_theme| rule::Style {
+            color: ui.color(Role::OutlineVariant),
+            radius: ui.radius_dp(ShapeScale::None),
+            fill_mode: rule::FillMode::Full,
+            snap: true,
+        })
+        .into()
+}
diff --git a/crates/app-iced/src/pages/agent/conversation/banners.rs b/crates/app-iced/src/pages/agent/conversation/banners.rs
new file mode 100644
index 0000000..b6d0861
--- /dev/null
+++ b/crates/app-iced/src/pages/agent/conversation/banners.rs
@@ -0,0 +1,212 @@
+//! 会话里的两条**横幅**（M119 从 `conversation.rs` 拆出来守 400 行硬线）：
+//! 失败态（具名错误）与写操作确认。
+//!
+//! ## 为什么必须存在
+//!
+//! 任务书第 4 条：「presenter 返回错误时 UI 必须显示**具名**错误而不是静默无语」。M104 的壳没有
+//! 任何错误位——`Submit` 只在本地数组追加一句「没发给模型」的提示。现在两条来源都有了落点：
+//!
+//! | 来源 | 触发 | 画什么 |
+//! |---|---|---|
+//! | `AgentHost::last_failure` | `agent_submit` 返回 `Err`（端点不可达 / 路由未实现） | 标题 = [`Key::AgentErrorTitle`]，正文 = 原因码对应的 catalog 译文 |
+//! | `AgentRail::error` | 后端发 `AgentEvent::Failed`（这一轮回复中止） | 标题同上，正文 = presenter 已脱敏的那句原因 |
+//!
+//! 两者都不把后端诊断原文直接上屏：诊断串只进日志（M114 复审 r1 立的口径）。
+//!
+//! ## 确认条
+//!
+//! `rail.confirm` 非空 ⇒ 一轮写操作在等用户裁决，而 `busy` 会一直锁着输入（presenter 的
+//! `sync_busy` 语义：`busy = streaming || confirm.is_some()`）。所以这段 UI 不是装饰：
+//! **不按就不动**。两个按钮都带文字标签（M104 的「不得只有图标」同一条规矩）。
+
+use iced::widget::{column, container, row, Row};
+use iced::{Alignment, Background, Element, Length};
+
+use unlucky_design::color::Role;
+use unlucky_design::elevation::MaterialLayer;
+use unlucky_design::icons::IconKind;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+use unlucky_i18n::{Catalog, Key};
+
+use unlucky_presenter::dto::ConfirmRequest;
+
+use crate::app::components::buttons::{self, Button};
+use crate::theme::Ui;
+
+use super::super::state::Focus;
+use super::super::{Failure, Message};
+use super::focused_state;
+use super::text_role_owned;
+
+/// 失败横幅：`ErrorContainer` 图标块 + 标题/正文（M3 内联 alert 的形状，与账户页横幅同源）。
+pub(super) fn failure<'a>(
+    ui: &'a Ui,
+    failure: Failure<'a>,
+    catalog: Catalog,
+) -> Element<'a, Message> {
+    banner(
+        ui,
+        catalog.text(failure.title).to_string(),
+        failure.body.to_string(),
+        Vec::new(),
+    )
+}
+
+/// 写操作确认条：一行请求摘要 + Allow / Deny。
+pub(super) fn confirm<'a>(
+    ui: &'a Ui,
+    request: &'a ConfirmRequest,
+    catalog: Catalog,
+    focus: Option<Focus>,
+) -> Element<'a, Message> {
+    // 摘要来自 presenter（已过 `scrub_text`）：它是「要改什么」的唯一描述，必须显示，
+    // 否则用户是在盲签。句框走 catalog，摘要本身是正文。
+    let title = catalog.render(
+        Key::AgentConfirmRequest,
+        &[("summary", request.summary.as_str())],
+    );
+    // 两个按钮都在 Tab 环上（`Focus::ConfirmAllow` / `Focus::ConfirmDeny`）：键盘用户
+    // 用 Enter/Space 就能裁决，不必去找鼠标（P2-2 的那条死路）
+    let deny = focus == Some(Focus::ConfirmDeny);
+    let allow = focus == Some(Focus::ConfirmAllow);
+    let actions: Vec<Element<'a, Message>> = vec![
+        ring(
+            ui,
+            buttons::outlined(
+                ui,
+                focused_state(
+                    Button::new(catalog.text(Key::AgentConfirmDeny), Message::Confirm(false))
+                        .leading(IconKind::Close),
+                    deny,
+                ),
+            ),
+            deny,
+        ),
+        ring(
+            ui,
+            buttons::filled(
+                ui,
+                focused_state(
+                    Button::new(catalog.text(Key::AgentConfirmAllow), Message::Confirm(true))
+                        .leading(IconKind::Check),
+                    allow,
+                ),
+            ),
+            allow,
+        ),
+    ];
+    banner(ui, title, String::new(), actions)
+}
+
+/// 焦点环：`Primary` 的 2dp 描边（与输入框聚焦同一套语言）。
+///
+/// 为什么不能只用 `Interaction::Focused`（10% 状态层）：在**实心主色**按钮上那层几乎看不出来
+/// ——M119 r1 复审要求「焦点确实落在可操作元素上」且要能出图证明，10% 层在浅色图里等于没有。
+/// 所以键盘焦点在这两个按钮上额外加一圈描边（鼠标用户的界面不受影响：只有 `focused` 才画）。
+fn ring<'a>(ui: &'a Ui, button: Element<'a, Message>, focused: bool) -> Element<'a, Message> {
+    // 外圈留 3px 空气：环与按钮之间不贴边，才看得成「一圈」而不是「两条重合的描边」。
+    // 两个按钮**都**加这层 padding（`focused` 与否一样），所以焦点变化不移动布局。
+    let gap = ui.space(Space::X1) * 0.75;
+    let outer = ui.metrics().control_height + gap * 2.0;
+    container(button)
+        .padding(gap)
+        .style(move |_theme| container::Style {
+            border: if focused {
+                iced::Border {
+                    color: ui.color(Role::Primary),
+                    width: crate::theme::STROKE_PX * 2.0,
+                    // 与按钮同一种「药丸」：`Full` 的半径 = 边长 / 2（这里用加过 padding 的边长）
+                    radius: ui.radius(ShapeScale::Full, outer),
+                }
+            } else {
+                iced::Border::default()
+            },
+            ..container::Style::default()
+        })
+        .into()
+}
+
+/// 横幅本体：图标块 + 标题/正文 + 右侧动作。
+///
+/// 形状与 `pages::account::widgets::alert` 同源（面板底走卡片层 + 1dp 描边，
+/// `ErrorContainer` / `OnErrorContainer` 只作左侧图标块的强调，不是通栏红条）。
+fn banner<'a>(
+    ui: &'a Ui,
+    title: String,
+    body: String,
+    actions: Vec<Element<'a, Message>>,
+) -> Element<'a, Message> {
+    let side = ui.space(Space::X8);
+    let glyph_px = ui.space(Space::X6);
+    let chip = container(crate::icons::view_at(
+        IconKind::Error,
+        ui.color(Role::Error),
+        glyph_px,
+    ))
+    .width(Length::Fixed(side))
+    .height(Length::Fixed(side))
+    .align_x(Alignment::Center)
+    .align_y(Alignment::Center)
+    .style(move |_theme| container::Style {
+        background: Some(Background::Color(ui.color(Role::ErrorContainer))),
+        border: iced::Border {
+            radius: ui.radius(ShapeScale::Full, side),
+            ..iced::Border::default()
+        },
+        ..container::Style::default()
+    });
+
+    let mut lines = column![text_role_owned(
+        ui,
+        TypeRole::TitleSmall,
+        true,
+        title,
+        ui.color(Role::OnSurface),
+        Length::Fill,
+    )]
+    .spacing(ui.space(Space::X1));
+    if !body.is_empty() {
+        lines = lines.push(text_role_owned(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            body,
+            ui.color(Role::OnSurfaceVariant),
+            Length::Fill,
+        ));
+    }
+
+    // 文字行与动作**分行**：右栗只有 280~360，chip + 两个按钮已占掉大半宽，
+    // 把文字挤在同一条 Row 里会被压成一条竖缝（M119 实测：320 宽下标题整段看不见）。
+    let head = Row::new()
+        .spacing(ui.space(Space::X3))
+        .align_y(Alignment::Center)
+        .width(Length::Fill)
+        .push(chip)
+        .push(container(lines).width(Length::Fill));
+
+    let mut content = column![Element::from(head)].spacing(ui.space(Space::X2));
+    if !actions.is_empty() {
+        content = content.push(
+            container(
+                row(actions)
+                    .spacing(ui.space(Space::X2))
+                    .align_y(Alignment::Center),
+            )
+            .width(Length::Fill)
+            .align_x(Alignment::End),
+        );
+    }
+
+    container(content)
+        .width(Length::Fill)
+        .padding(ui.metrics().card_padding)
+        .style(move |_theme| container::Style {
+            background: Some(Background::Color(ui.layer(MaterialLayer::Card))),
+            border: ui.outlined(ShapeScale::Medium),
+            ..container::Style::default()
+        })
+        .into()
+}
diff --git a/crates/app-iced/src/pages/agent/conversation/composer.rs b/crates/app-iced/src/pages/agent/conversation/composer.rs
new file mode 100644
index 0000000..a642c2c
--- /dev/null
+++ b/crates/app-iced/src/pages/agent/conversation/composer.rs
@@ -0,0 +1,234 @@
+//! 输入区（多行输入框 + 发送/中断）：会话视图的**下半截**。
+//!
+//! 从 `conversation.rs` 拆出来的理由只有一条：那边贴着 400 行硬上限（AGENTS.md §3-1）。
+//! 拆的位置是「输入区」这一整块 + 一个排版小工具，语义边界与文件边界一致。
+//!
+//! ## Enter / Shift+Enter 的分流（任务第 4 条）
+//!
+//! `text_editor` 的默认绑定把两种 Enter 都折成 `Binding::Enter`，所以必须自己接管
+//! （见 [`composer`] 里的 `key_binding`）：`modifiers.shift()` 决定「换行」还是「发送」。
+//! **只在输入框聚焦时生效**——`KeyPress.status` 不是 `Focused` 时原样交回默认绑定，
+//! 于是别处的 Enter 不会被助手栏抢走。
+
+use iced::widget::text_editor::{self, Binding, KeyPress};
+use iced::widget::{column, row, text, text_editor as editor};
+use iced::{keyboard, Background, Border, Element, Length, Pixels, Theme};
+
+use unlucky_design::color::Role;
+use unlucky_design::elevation::MaterialLayer;
+use unlucky_design::icons::IconKind;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+use unlucky_i18n::{Catalog, Key};
+
+use crate::app::components::buttons::{self, Button};
+use crate::theme::{Ui, STROKE_PX};
+
+use super::super::state::Focus;
+use super::super::Message;
+use super::{focused_state, Conversation};
+
+pub(super) fn composer<'a>(
+    ui: &'a Ui,
+    spec: Conversation<'a>,
+    catalog: Catalog,
+) -> Element<'a, Message> {
+    let style = ui.style(TypeRole::BodyMedium);
+
+    let field = editor(spec.draft)
+        .placeholder(spec.note.placeholder)
+        .on_action(Message::Edit)
+        .key_binding(binding_for)
+        .size(style.size_px)
+        .font(ui.font_of(style))
+        .height(Length::Fixed(
+            ui.space(Space::X8) + ui.space(Space::X8) + ui.space(Space::X1),
+        ))
+        .padding(ui.space(Space::X2))
+        .style(move |_theme: &Theme, status| {
+            let focused = matches!(status, text_editor::Status::Focused { .. });
+            text_editor::Style {
+                background: Background::Color(ui.layer(MaterialLayer::Card)),
+                border: if focused {
+                    Border {
+                        color: ui.color(Role::Primary),
+                        width: STROKE_PX * 2.0,
+                        radius: ui.radius_dp(ShapeScale::Small),
+                    }
+                } else {
+                    ui.outlined(ShapeScale::Small)
+                },
+                placeholder: ui.color(Role::OnSurfaceVariant),
+                value: ui.color(Role::OnSurface),
+                selection: ui.color(Role::PrimaryContainer),
+            }
+        });
+
+    let send_label = catalog.text(Key::AgentSend);
+    let send = if spec.blank || spec.busy {
+        Button::disabled(send_label)
+    } else {
+        Button::new(send_label, Message::Submit)
+    };
+    // 键盘焦点在「发送」上时用 `Interaction::Focused`（10% 状态层），与头部动作同一套焦点语言。
+    let send = focused_state(
+        send.leading(IconKind::Send),
+        spec.focus == Some(Focus::Send),
+    );
+
+    let mut actions = row![]
+        .spacing(ui.space(Space::X2))
+        .align_y(iced::Alignment::Center);
+    if spec.busy {
+        actions = actions.push(buttons::outlined(
+            ui,
+            focused_state(
+                Button::new(catalog.text(Key::AgentStop), Message::Stop).leading(IconKind::Close),
+                spec.focus == Some(Focus::Stop),
+            ),
+        ));
+    }
+    actions = actions.push(buttons::filled(ui, send));
+
+    column![field, actions]
+        .spacing(ui.space(Space::X2))
+        .width(Length::Fill)
+        .into()
+}
+
+/// Enter = 发送 / Shift+Enter = 换行（任务第 4 条）。
+///
+/// 为什么走 `key_binding` 而不是全局键盘订阅：`KeyPress` 直接带 `modifiers`，而 iced 的默认绑定
+/// 把两种 Enter 都折成 `Binding::Enter`（`text_editor.rs:1210`），所以**必须**在这里分流。
+/// 未聚焦时一律交回默认绑定（`from_key_press` 对非聚焦返回 `None`），于是别处的 Enter 不会被
+/// 助手栏抢走。
+///
+/// 抽成**纯函数**是为了能被单测钉住（复审 P3-2：之前一个测试都没覆盖这条分流）。
+pub(super) fn binding_for(press: KeyPress) -> Option<Binding<Message>> {
+    let enter = matches!(
+        press.modified_key.as_ref(),
+        keyboard::Key::Named(keyboard::key::Named::Enter)
+    );
+    if !enter || !matches!(press.status, text_editor::Status::Focused { .. }) {
+        return Binding::from_key_press(press);
+    }
+    if press.modifiers.shift() {
+        Some(Binding::Enter)
+    } else {
+        Some(Binding::Custom(Message::Submit))
+    }
+}
+
+/// 一档文字（**借来的**正文）。
+///
+/// 与 `pages::frame::text_role` 同源，但那边返回的是 `Element<pages::Message>`，助手栏要自己的
+/// 消息类型——这是 M104 起就有的分工，不是重复实现。
+/// 一档文字（**拼出来的**正文：工具条目 `name · summary`、横幅文案都走它）。
+///
+/// 为什么不能直接用借用版：正文是 `String`，而 `Element` 不允许借用局部变量。
+pub(crate) fn text_role_owned<'a>(
+    ui: &'a Ui,
+    role: TypeRole,
+    emphasized: bool,
+    content: String,
+    color: iced::Color,
+    width: Length,
+) -> Element<'a, Message> {
+    let style = if emphasized {
+        ui.emphasized(role)
+    } else {
+        ui.style(role)
+    };
+
+    text(content)
+        .size(style.size_px)
+        .line_height(iced::widget::text::LineHeight::Absolute(Pixels(
+            style.line_height_px,
+        )))
+        .font(ui.font_of(style))
+        .color(color)
+        .width(width)
+        .into()
+}
+
+pub(crate) fn text_role<'a>(
+    ui: &'a Ui,
+    role: TypeRole,
+    emphasized: bool,
+    content: &'a str,
+    color: iced::Color,
+    width: Length,
+) -> Element<'a, Message> {
+    let style = if emphasized {
+        ui.emphasized(role)
+    } else {
+        ui.style(role)
+    };
+
+    text(content)
+        .size(style.size_px)
+        .line_height(iced::widget::text::LineHeight::Absolute(Pixels(
+            style.line_height_px,
+        )))
+        .font(ui.font_of(style))
+        .color(color)
+        .width(width)
+        .into()
+}
+
+#[cfg(test)]
+mod tests {
+    use iced::keyboard::key::{Code, Named, Physical};
+    use iced::keyboard::{Key, Modifiers};
+
+    use super::super::super::Message;
+    use super::*;
+
+    fn press(key: Key, modifiers: Modifiers, focused: bool) -> KeyPress {
+        let status = if focused {
+            text_editor::Status::Focused { is_hovered: false }
+        } else {
+            text_editor::Status::Active
+        };
+        KeyPress {
+            key: key.clone(),
+            modified_key: key,
+            physical_key: Physical::Code(Code::Enter),
+            modifiers,
+            text: None,
+            status,
+        }
+    }
+
+    fn enter() -> Key {
+        Key::Named(Named::Enter)
+    }
+
+    /// **Enter 发送 / Shift+Enter 换行**（复审 P3-2 点名缺的那条）：
+    /// 抓得住两条分支各自选对了 `Binding`（非 shift 只发消息、不插换行；shift 才插换行）。
+    /// 抓不住真实按键（`KeyPress` 是这里手搓的，不是 winit 送上来的）。
+    #[test]
+    fn enter_sends_and_shift_enter_breaks_the_line() {
+        // 非 shift + 聚焦 ⇒ 发消息（**不**插换行）
+        let plain = binding_for(press(enter(), Modifiers::default(), true));
+        assert!(
+            matches!(plain, Some(Binding::Custom(Message::Submit))),
+            "Enter 应当发 Submit，实际 {plain:?}"
+        );
+
+        // shift + 聚焦 ⇒ 插换行
+        let shifted = binding_for(press(enter(), Modifiers::SHIFT, true));
+        assert!(
+            matches!(shifted, Some(Binding::Enter)),
+            "Shift+Enter 应当插换行，实际 {shifted:?}"
+        );
+
+        // 未聚焦 ⇒ 原样交回默认绑定（它自己对非聚焦返回 None），别处的 Enter 不受影响
+        assert!(binding_for(press(enter(), Modifiers::default(), false)).is_none());
+
+        // 其它键 ⇒ 交回默认绑定（这里用 Tab：默认绑定里没有它）
+        let tab = press(Key::Named(Named::Tab), Modifiers::default(), true);
+        assert!(binding_for(tab).is_none());
+    }
+}
diff --git a/crates/app-iced/src/pages/agent/conversation/transcript.rs b/crates/app-iced/src/pages/agent/conversation/transcript.rs
new file mode 100644
index 0000000..8e7e911
--- /dev/null
+++ b/crates/app-iced/src/pages/agent/conversation/transcript.rs
@@ -0,0 +1,122 @@
+//! 对话本体：空态 + 消息气泡（M119 从 `conversation.rs` 拆出来守 400 行硬线）。
+//!
+//! ## 数据从哪来
+//!
+//! 直接画 presenter 的 `AgentRail::messages`（`ChatMessage`）：`role` 决定角色小标与气泡容器，
+//! `text` 是正文（**已经过 presenter 的第二道脱敏闸门** `scrub_text`），`tool` 是工具调用条目
+//! （D4：工具调用会话可见）。壳里不再有 `Speaker`/`Turn` 那种自己的会话类型——那是一份要跟
+//! presenter 对齐的镜像，M119 已经删掉。
+
+use iced::widget::{column, container, scrollable};
+use iced::{Alignment, Background, Border, Element, Length, Padding};
+
+use unlucky_design::color::Role;
+use unlucky_design::elevation::MaterialLayer;
+use unlucky_design::icons::IconKind;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+use unlucky_i18n::{Catalog, Key};
+
+use unlucky_presenter::dto::{ChatMessage, ChatRole};
+
+use crate::app::components::feedback::empty_state::{empty_state, EmptyState};
+use crate::pages::frame;
+use crate::theme::Ui;
+
+use super::super::Message;
+use super::{text_role, text_role_owned, Conversation};
+
+/// 空会话：引导空态（零条消息时替代气泡列表）。
+///
+/// `body` 由调用方从 [`super::super::Disclaimer`] 取（模拟态/真实态两句话），这里不再自己取词。
+pub(super) fn empty<'a>(ui: &'a Ui, catalog: Catalog, body: &'a str) -> Element<'a, Message> {
+    container(empty_state(
+        ui,
+        EmptyState::new(IconKind::Ai, catalog.text(Key::AgentEmptyTitle), body),
+    ))
+    .width(Length::Fill)
+    .height(Length::Fill)
+    .into()
+}
+
+/// 气泡列表（可滚动）。
+pub(super) fn list<'a>(
+    ui: &'a Ui,
+    spec: Conversation<'a>,
+    catalog: Catalog,
+) -> Element<'a, Message> {
+    let mut items = column![].spacing(ui.space(Space::X3)).width(Length::Fill);
+
+    for message in spec.messages {
+        items = items.push(bubble(ui, message, catalog));
+    }
+
+    scrollable(container(items).padding(Padding::from([ui.space(Space::X1), 0.0])))
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .style(frame::scroll_style(ui))
+        .into()
+}
+
+/// 一条消息：角色小标 + 正文。三种容器（用户 = `SecondaryContainer`、助手/工具 = 卡片层、
+/// 系统提示 = 无容器只留文字），气泡整体右/左对齐。
+fn bubble<'a>(ui: &'a Ui, message: &'a ChatMessage, catalog: Catalog) -> Element<'a, Message> {
+    let (role, fill, ink, align) = match message.role {
+        ChatRole::User => (
+            Key::AgentRoleYou,
+            Some(ui.color(Role::SecondaryContainer)),
+            ui.color(Role::OnSecondaryContainer),
+            Alignment::End,
+        ),
+        // 工具条目也挂在助手名下：它是助手这一轮做的事，不是第三方说话人
+        ChatRole::Assistant | ChatRole::Tool => (
+            Key::AgentRoleAssistant,
+            Some(ui.layer(MaterialLayer::Card)),
+            ui.color(Role::OnSurface),
+            Alignment::Start,
+        ),
+        ChatRole::System => (
+            Key::AgentRoleNotice,
+            None,
+            ui.color(Role::OnSurfaceVariant),
+            Alignment::Start,
+        ),
+    };
+
+    // 工具条目：正文是结果摘要，名字前缀一行（`tool.name`，与 ToolSpec 注册表同名）。
+    // 两者都来自 presenter 的事件，已过脱敏；这里只拼展示串。
+    let body = match &message.tool {
+        Some(tool) => format!("{} · {}", tool.name, tool.summary),
+        None => message.text.clone(),
+    };
+
+    let inner = column![
+        text_role(
+            ui,
+            TypeRole::LabelMedium,
+            false,
+            catalog.text(role),
+            ui.color(Role::OnSurfaceVariant),
+            Length::Fill,
+        ),
+        text_role_owned(ui, TypeRole::BodyMedium, false, body, ink, Length::Fill),
+    ]
+    .spacing(ui.space(Space::X1))
+    .width(Length::Fill);
+
+    let card = container(inner)
+        .width(Length::Fill)
+        .padding(Padding::from([ui.space(Space::X2), ui.space(Space::X3)]))
+        .style(move |_theme| container::Style {
+            background: fill.map(Background::Color),
+            border: if fill.is_some() {
+                ui.outlined(ShapeScale::Medium)
+            } else {
+                Border::default()
+            },
+            ..container::Style::default()
+        });
+
+    container(card).width(Length::Fill).align_x(align).into()
+}
diff --git a/crates/app-iced/src/pages/agent/demo.rs b/crates/app-iced/src/pages/agent/demo.rs
new file mode 100644
index 0000000..65b213c
--- /dev/null
+++ b/crates/app-iced/src/pages/agent/demo.rs
@@ -0,0 +1,130 @@
+//! 取证开关（`ULL_AGENT_*`）：三档档位 / 展开宽度 / 会话夹具。
+//!
+//! ## 与 M104 的区别：这里不再有「样本会话」
+//!
+//! M104 的 `demo::transcript()` 是**内置会话样本**，右栗出厂就画着四条假对话——那是「壳先搭好、
+//! 等 M103 接」的过渡态。M119 接线之后会话的唯一来源是 presenter，于是样本只能以**真链路**的
+//! 方式进来：夹具不造消息，而是**走一次真的提交**（`agent_submit` → transport → 事件队列 →
+//! `Message::Agent(Events)` → `apply`）。跑什么脚本由 `ULL_AGENT_SCRIPT`（见
+//! [`crate::app::state::presenter`]）决定，夹具只决定「要不要在启动时跑这一轮」。
+//!
+//! 于是出厂态是**空会话**（空态引导卡）——这才是没有模型的启动器该有的样子。
+//!
+//! ## 取值表
+//!
+//! | 变量 | 取值 | 作用 |
+//! |---|---|---|
+//! | [`RAIL_ENV`] | `collapsed` / `expanded` / `detached` | 启动时直接落到某一档（三态矩阵） |
+//! | [`FIXTURE_ENV`] | `turn` / `unread` / `focused` / `empty` | 启动时跑一轮真提交 / 折叠态跑（留未读）/ 键盘焦点环 / 什么都不做 |
+//! | [`WIDTH_ENV`] | `280` / `320` / `360` | 展开档宽度（磁铁档位的对照图） |
+//!
+//! 解析失败一律**忽略**（取证开关不该让进程起不来），并在 stderr 留一行，方便对照日志读图。
+
+use super::metrics::PRESETS;
+use super::state::{AgentUi, RailState};
+
+/// 启动档位。
+pub const RAIL_ENV: &str = "ULL_AGENT_RAIL";
+/// 会话夹具（`turn` / `unread` / `focused` / `empty`）。
+pub const FIXTURE_ENV: &str = "ULL_AGENT_FIXTURE";
+/// 展开档宽度（只接受三档预设值）。
+pub const WIDTH_ENV: &str = "ULL_AGENT_WIDTH";
+
+/// 夹具：启动时对**真 presenter** 做什么。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Fixture {
+    /// 什么都不做（出厂态：空会话）。`ULL_AGENT_FIXTURE=empty` 显式写出来也一样。
+    None,
+    /// 跑一轮真提交（脚本由 `ULL_AGENT_SCRIPT` 决定：问答 / 断流 / 写操作 / 两种失败）。
+    Turn,
+    /// 折叠态跑一轮真提交：于是未读会真的被 presenter 累加（不是硬编码的数字）。
+    Unread,
+    /// 键盘巡航一次的样子（焦点环 = 10% 状态层）。
+    Focused,
+    /// 跑一轮真提交，然后**按一次 `Tab`**（M119 r2 出图用）。
+    ///
+    /// 复现的是键盘用户走到确认条的路径：待确认出现 ⇒ 焦点已落在「允许」但**键盘闸没开**
+    /// （图 `05`，看不到环）；按一次 `Tab` 才算表态（图 `09`，环亮出来且焦点不动）。
+    Armed,
+}
+
+/// 夹具里的那句用户消息（**演示数据**，不是界面文案：它跟实例名一样属于样本内容，
+/// 不进 i18n 词表——接上真模型之后它就不存在了）。
+pub const DEMO_QUESTION: &str = "Which instance should I start for a 1.20.4 test?";
+
+/// 按环境变量构造一份 UI 状态 + 夹具（没设任何变量 = `None`，调用方用出厂态）。
+pub fn from_env() -> Option<(AgentUi, Fixture)> {
+    let rail = std::env::var(RAIL_ENV).ok();
+    let fixture = std::env::var(FIXTURE_ENV).ok();
+    let width = std::env::var(WIDTH_ENV).ok();
+
+    if rail.is_none() && fixture.is_none() && width.is_none() {
+        return None;
+    }
+
+    let mut ui = AgentUi::new();
+
+    if let Some(raw) = width.as_deref().map(str::trim) {
+        match raw.parse::<f32>() {
+            Ok(value) if PRESETS.contains(&value) => ui.set_expanded(value),
+            _ => eprintln!("[agent] {WIDTH_ENV}={raw:?} 不是预设档位 {PRESETS:?} 之一，忽略"),
+        }
+    }
+
+    // 档位走**真迁移**（`expand` / `detach` / `collapse`）而不是直接写字段：这样未读的语义
+    // （展开即读）在取证图里也成立，不会出现「展开着还挂着 2 条未读」这种自相矛盾的画面。
+    // 唯一要单独看徽标的情形用 `ULL_AGENT_FIXTURE=unread` 显式造（折叠态跑一轮）。
+    match rail.as_deref().map(str::trim) {
+        None => ui.expand(),
+        Some(name) => match RailState::from_name(name) {
+            Some(RailState::Collapsed) => ui.collapse(),
+            Some(RailState::Detached) => ui.detach(),
+            Some(RailState::Expanded) => ui.expand(),
+            None => eprintln!(
+                "[agent] {RAIL_ENV}={name:?} 不是三档之一（{}），忽略",
+                RailState::ALL.map(RailState::name).join("/")
+            ),
+        },
+    }
+
+    let fixture = match fixture.as_deref().map(str::trim) {
+        Some("turn") => Fixture::Turn,
+        Some("unread") => Fixture::Unread,
+        Some("focused") => Fixture::Focused,
+        Some("armed") => Fixture::Armed,
+        Some("empty") | None => Fixture::None,
+        Some(other) => {
+            eprintln!("[agent] {FIXTURE_ENV}={other:?} 不是夹具之一，按 empty 处理");
+            Fixture::None
+        }
+    };
+
+    eprintln!(
+        "[agent] rail={} width={} fixture={fixture:?}",
+        ui.rail.name(),
+        ui.expanded(),
+    );
+
+    Some((ui, fixture))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn the_demo_question_is_plain_ascii_so_a_clean_ci_has_the_glyphs() {
+        assert!(
+            DEMO_QUESTION.is_ascii(),
+            "夹具正文不带非 ascii（干净 CI 无中文字体）"
+        );
+    }
+
+    #[test]
+    fn every_rail_state_name_round_trips_through_the_env_parser() {
+        for state in RailState::ALL {
+            assert_eq!(RailState::from_name(state.name()), Some(state));
+        }
+        assert_eq!(RailState::from_name("nope"), None);
+    }
+}
diff --git a/crates/app-iced/src/pages/agent/metrics.rs b/crates/app-iced/src/pages/agent/metrics.rs
new file mode 100644
index 0000000..8c09f34
--- /dev/null
+++ b/crates/app-iced/src/pages/agent/metrics.rs
@@ -0,0 +1,176 @@
+//! 右侧助手栏的**布局数学**：三档宽度、磁铁吸附、中栗下限。纯函数 + 常量，不碰 iced 控件树。
+//!
+//! ## 一屏的横向预算
+//!
+//! ```text
+//! 窗口宽 = 左轨 88 + [中栗] + [拖拽缝 8（仅展开档）] + [右栗]
+//! ```
+//!
+//! - 右栗宽度 = [`rail_width`]：折叠 48 / 展开 280~360（吸附值）/ 拆出 0；
+//! - 中栗宽度 = 窗口 − 右栗 − 拖拽缝（[`content_width`]，页面层再扣左轨与页边距）；
+//! - **中栗下限** [`min_content_width`] = 行宽上限 424 + 两侧页边距 48 = **472**：
+//!   再窄正文列就装不下一行满宽文，所以拖拽被夹在这里（不是「拖到 0 再说」）。
+//!
+//! 「展开时中栗**收缩而不是溢出**」这句话的落点就是 [`content_width`]：页面布局系统仍以
+//! 「一个窗口宽」为输入（它内部扣 rail 与页边距），所以右栗占掉的那一段必须在这里先减掉。
+//! 四个对照宽度的实际数值由 `metrics/tests.rs` 的表钉住（报告里贴的是同一张表）。
+//!
+//! ## 三档预设的取值理由（tower 要求写明，不许默默定）
+//!
+//! | 档位 | 值 | 依据 |
+//! |---|---|---|
+//! | 折叠 | **48** | `LayoutMetrics::touch_target`：M3 无障碍下限，图标按钮 40 + 未读点要放得下 |
+//! | 展开（锚） | **320** | 令牌 `ai_panel_width`：M69 起这个令牌就叫「AI 面板宽度」，改锚等于改令牌语义 |
+//! | 展开 ±1 档 | **280 / 360** | 在 4px 栅格上、离锚正好 40（`Space::X8 + Space::X2`）；280 = 官方 supporting-pane 侧列下限 240 + 两份 20 内边距，仍能排 40 字符/行 |
+//!
+//! **不取 420**：900 宽窗上右栗上限只有 340（[`max_rail_width`]），420 这个预设永远点不到 = 假档位。
+//! **不取 240**：减去两侧 16 内边距只剩 208，一行不到 35 字符，会话气泡会碎成柱状。
+
+use unlucky_design::spacing::{snap_to_grid, LayoutMetrics, Space};
+
+use crate::pages::layout;
+
+/// 折叠态图标条宽 = M3 触控目标 **48**（`LayoutMetrics::touch_target`，不是新字面量）。
+pub const COLLAPSED_WIDTH: f32 = LayoutMetrics::DESKTOP.touch_target;
+
+/// 展开态面板宽 = 令牌 `ai_panel_width` = **320**。
+pub const DEFAULT_EXPANDED_WIDTH: f32 = LayoutMetrics::DESKTOP.ai_panel_width;
+
+/// 磁铁档位间距 = 一个页级留白（32）+ 一个小留白（8）= **40**。
+pub const PRESET_STEP: f32 = Space::X8.dp() + Space::X2.dp();
+
+/// 三个预设档位：**280 / 320 / 360**（理由见模块文档）。
+pub const PRESETS: [f32; 3] = [
+    DEFAULT_EXPANDED_WIDTH - PRESET_STEP,
+    DEFAULT_EXPANDED_WIDTH,
+    DEFAULT_EXPANDED_WIDTH + PRESET_STEP,
+];
+
+/// 磁铁半径（`Space::X6` = 24）：离预设档位 24px 以内就吸过去，否则按 4px 栅格落地。
+///
+/// 24 > 档位间距的一半（20），所以 280~360 之间**任何**位置都会被吸到某一档；360 以上到上限
+/// 之间不再有档位，那段才走 4px 栅格（用户想要 500 宽的面板也给）。
+pub const MAGNET_RADIUS: f32 = Space::X6.dp();
+
+/// 面板与中栗之间的可拖拽缝隙宽（`Space::X2` = 8）。
+///
+/// 它既是分隔线（1px `OutlineVariant` 居中）也是命中区：不是「看起来细就抓不到」。
+pub const RESIZE_GUTTER: f32 = Space::X2.dp();
+
+/// 中栗的最小可用宽度 = 行宽上限 424 + 两侧页边距 24×2 = **472**。
+///
+/// 依据是布局系统自己的判据（[`layout::measure_cap_px`]）：1180 展开 320 后中栗 **852**，
+/// 880（进程最小窗宽）展开 320 后中栗 **552** —— 都还在 472 之上。
+pub fn min_content_width() -> f32 {
+    layout::measure_cap_px() + 2.0 * Space::X6.dp()
+}
+
+/// 右栗能占的最大宽度：中栗不许低于 [`min_content_width`]（拖拽缝也算右栗的开销）。
+///
+/// 下限取 [`COLLAPSED_WIDTH`]（窗口再窄也不把右栗夹成负数）。
+pub fn max_rail_width(window_width: f32) -> f32 {
+    (window_width - layout::rail_width() - min_content_width() - RESIZE_GUTTER).max(COLLAPSED_WIDTH)
+}
+
+/// 展开宽度的合法化：夹到可用范围。低于 280 就吸到 280（不是变细）。
+///
+/// 窗口窄到连 280 都不成立时返回 [`COLLAPSED_WIDTH`]——那时「展开」这件事本身不成立，
+/// 画一条 280 的栏会把中栗压到 472 以下。
+pub fn clamp_width(window_width: f32, requested: f32) -> f32 {
+    let ceiling = max_rail_width(window_width);
+    if ceiling < PRESETS[0] {
+        return COLLAPSED_WIDTH;
+    }
+    requested.clamp(PRESETS[0], ceiling)
+}
+
+/// 拖拽落点 → 吸附后的右栗宽度（磁铁 → 4px 栅格 → 夹紧）。
+pub fn magnet_width(window_width: f32, raw: f32) -> f32 {
+    let nearest = PRESETS
+        .iter()
+        .copied()
+        .min_by(|left, right| (left - raw).abs().total_cmp(&(right - raw).abs()))
+        .unwrap_or(DEFAULT_EXPANDED_WIDTH);
+
+    let settled = if (nearest - raw).abs() <= MAGNET_RADIUS {
+        nearest
+    } else {
+        snap_to_grid(raw)
+    };
+
+    clamp_width(window_width, settled)
+}
+
+/// 窗口窄到连最小展开档都放不下时，`Expanded` **事实上**就是折叠档。
+///
+/// 不是「自动帮用户收起」的一时兴起：`clamp_width` 在这种情况下返回的就是 [`COLLAPSED_WIDTH`]，
+/// 若仍报 `Expanded`，宿主会画一条 48 宽的面板、还白扣 8px 拖拽缝。
+pub fn effective_state(
+    window_width: f32,
+    state: crate::shell::agent::RailState,
+    expanded: f32,
+) -> crate::shell::agent::RailState {
+    use crate::shell::agent::RailState;
+    match state {
+        RailState::Expanded if clamp_width(window_width, expanded) <= COLLAPSED_WIDTH => {
+            RailState::Collapsed
+        }
+        other => other,
+    }
+}
+
+/// 一屏的横向预算（窗口 → 左轨 / 中栗 / 右栗）。纯数据，供单测与日志用。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct RailLayout {
+    /// 窗口宽度（输入）。
+    pub window: f32,
+    /// 左侧导航轨宽度（令牌 `nav_rail_width` = 88）。
+    pub left: f32,
+    /// 右栗面板宽度（0 / 48 / 280~360）。
+    pub rail: f32,
+    /// 右栗前面的拖拽缝宽度（只有展开档有，其余 0）。
+    pub gutter: f32,
+    /// 中栗宽度 = 窗口 − 右栗 − 拖拽缝（页面层再扣左轨与页边距）。
+    pub content: f32,
+}
+
+/// 算一屏的横向预算（档位先经 [`effective_state`] 归一）。
+pub fn layout_for(
+    window_width: f32,
+    state: crate::shell::agent::RailState,
+    expanded: f32,
+) -> RailLayout {
+    use crate::shell::agent::RailState;
+
+    let (rail, gutter) = match effective_state(window_width, state, expanded) {
+        RailState::Collapsed => (COLLAPSED_WIDTH, 0.0),
+        RailState::Expanded => (clamp_width(window_width, expanded), RESIZE_GUTTER),
+        RailState::Detached => (0.0, 0.0),
+    };
+
+    RailLayout {
+        window: window_width,
+        left: layout::rail_width(),
+        rail,
+        gutter,
+        content: (window_width - rail - gutter).max(0.0),
+    }
+}
+
+/// 右栗面板宽度（`App::view` 与 shell 都用这一个入口，避免两处各算一套）。
+pub fn rail_width(window_width: f32, state: crate::shell::agent::RailState, expanded: f32) -> f32 {
+    layout_for(window_width, state, expanded).rail
+}
+
+/// **交给页面布局系统的宽度** = 窗口 − 右栗 − 拖拽缝。
+pub fn content_width(
+    window_width: f32,
+    state: crate::shell::agent::RailState,
+    expanded: f32,
+) -> f32 {
+    layout_for(window_width, state, expanded).content
+}
+
+#[cfg(test)]
+#[path = "metrics/tests.rs"]
+mod tests;
diff --git a/crates/app-iced/src/pages/agent/metrics/tests.rs b/crates/app-iced/src/pages/agent/metrics/tests.rs
new file mode 100644
index 0000000..444b226
--- /dev/null
+++ b/crates/app-iced/src/pages/agent/metrics/tests.rs
@@ -0,0 +1,189 @@
+//! 布局数学的数值判据（M104 任务第 2 条那张表就长在这里）。
+//!
+//! 每条断言都写清「抓得住什么 / 抓不住什么」——纯函数能钉住算式，**钉不住**像素与手感。
+
+use crate::pages::layout::{self, PaneKit};
+
+use crate::shell::agent::RailState;
+
+use super::{
+    clamp_width, content_width, effective_state, layout_for, magnet_width, max_rail_width,
+    min_content_width, COLLAPSED_WIDTH, DEFAULT_EXPANDED_WIDTH, MAGNET_RADIUS, PRESETS,
+    RESIZE_GUTTER,
+};
+
+/// **布局数学的核心表**（1180 / 1024 / 900 / 700，任务第 2 条点名要的四个宽度）。
+///
+/// 抓得住：右栗占宽之后中栗是**收缩**的（`content = window − rail − gutter`），以及页面布局系统
+/// 拿到的列宽确实跟着变（1180 展开时实例页详情列 424 → 356）。
+/// 抓不住：真实的像素宽度（那要量图），也抓不住「右栗和外框之间有没有缝」这种观感问题。
+#[test]
+fn the_column_table_matches_the_mission_widths() {
+    // (窗口, 档位, 右栗面板, 拖拽缝, 中栗, 实例详情列, 单列页列宽)
+    //
+    // 第三列是**面板宽度**，前两列的「展开档」用默认锚 320；360 那一行显式给值（见 `set_expanded`）。
+    let expect = [
+        (1180.0, RailState::Detached, 0.0, 0.0, 1180.0, 424.0, 424.0),
+        (
+            1180.0,
+            RailState::Collapsed,
+            48.0,
+            0.0,
+            1132.0,
+            424.0,
+            424.0,
+        ),
+        (1180.0, RailState::Expanded, 320.0, 8.0, 852.0, 356.0, 424.0),
+        // 360 档：中栗 812 掉到 medium 档 ⇒ 实例页退化单列（不再有两列硬挤）
+        (1180.0, RailState::Expanded, 360.0, 8.0, 812.0, 424.0, 424.0),
+        (1024.0, RailState::Detached, 0.0, 0.0, 1024.0, 424.0, 424.0),
+        (1024.0, RailState::Collapsed, 48.0, 0.0, 976.0, 424.0, 424.0),
+        // 1024 展开：中栗 696 掉到 medium 档 ⇒ 实例页退化成单列（不再两列硬挤）
+        (1024.0, RailState::Expanded, 320.0, 8.0, 696.0, 424.0, 424.0),
+        // 900 收起：中栗 852 仍够 list-detail（几何门槛 816），详情列 356
+        (900.0, RailState::Detached, 0.0, 0.0, 900.0, 404.0, 424.0),
+        (900.0, RailState::Collapsed, 48.0, 0.0, 852.0, 356.0, 424.0),
+        (900.0, RailState::Expanded, 320.0, 8.0, 572.0, 424.0, 424.0),
+        // 700 < 进程最小窗宽 880：展开档不成立（中栗会被压到 472 以下），退回收起档
+        (700.0, RailState::Expanded, 48.0, 0.0, 652.0, 424.0, 424.0),
+    ];
+
+    for (window, rail, width, gutter, content, detail, single) in expect {
+        // 展开档用「锚 320」或表里显式给的更宽档（360）——收起/拆出的行也给 320，不影响结果
+        let expanded = if width > DEFAULT_EXPANDED_WIDTH {
+            width
+        } else {
+            DEFAULT_EXPANDED_WIDTH
+        };
+        let laid_out = layout_for(window, rail, expanded);
+        assert_eq!(
+            (laid_out.rail, laid_out.gutter, laid_out.content),
+            (width, gutter, content),
+            "{window} / {} 的横向预算不对",
+            rail.name()
+        );
+        assert_eq!(laid_out.left, layout::rail_width(), "左轨宽度只有一个真源");
+
+        // 页面布局系统吃的就是这个 content 宽：实例页（list-detail）与单列页各算一次
+        let instances = layout::frame_metrics(PaneKit::ListDetail, content);
+        assert_eq!(
+            instances.column,
+            detail,
+            "{window} / {} 的实例详情列宽不对",
+            rail.name()
+        );
+        let page = layout::frame_metrics(PaneKit::Single, content);
+        assert_eq!(
+            page.column,
+            single,
+            "{window} / {} 的单列页列宽不对",
+            rail.name()
+        );
+    }
+}
+
+/// **不溢出**的硬判据：窗口 ≥ 最小窗宽时，任何档位、任何预设，中栗都不低于 472。
+///
+/// 抓得住：有人把 [`min_content_width`] 调小、或让 [`content_width`] 忘了扣右栗/拖拽缝。
+/// 抓不住：`row!` 的兄弟顺序写错（那要出图看）。
+#[test]
+fn the_middle_column_never_drops_below_the_usable_width() {
+    assert_eq!(
+        min_content_width(),
+        472.0,
+        "472 = 行宽上限 424 + 两侧页边距 48"
+    );
+
+    for window in [880.0, 900.0, 1024.0, 1180.0, 1440.0, 2560.0] {
+        for rail in RailState::ALL {
+            for preset in PRESETS {
+                let width = content_width(window, rail, preset);
+                assert!(
+                    width >= 472.0,
+                    "{window} / {} / 预设 {preset} 把中栗压到 {width}",
+                    rail.name()
+                );
+            }
+        }
+    }
+
+    // 边界：最小窗宽 880 上，展开档被夹到上限 312（880 − 88 − 472 − 8），中栗留 560
+    assert_eq!(max_rail_width(880.0), 312.0);
+    assert_eq!(content_width(880.0, RailState::Expanded, 320.0), 560.0);
+}
+
+/// 拖拽：磁铁吸附 + 夹紧。
+///
+/// 抓得住：①拖动结果落在预设档或 4px 栅格上（不会一像素一像素抖）；②离预设 24px 内被吸住；
+/// ③往左拖过头会被夹在 [`max_rail_width`]，而不是把中栗压扁。
+/// 抓不住：真实指针手感（`mouse_area::on_move` 在真窗口里的采样率只能人试）。
+#[test]
+fn the_drag_magnetises_and_refuses_to_squeeze_the_middle() {
+    // 1180 窗口：上限 = 1180 − 88（左轨）− 472（中栗下限）− 8（拖拽缝）= 612
+    assert_eq!(max_rail_width(1180.0), 612.0);
+
+    // 离 320 只有 6px ⇒ 吸到 320
+    assert_eq!(magnet_width(1180.0, 326.0), 320.0);
+    // 两档之间（310）：离 320 只有 10px ⇒ 还是吸住
+    assert_eq!(magnet_width(1180.0, 310.0), 320.0);
+    // 360 之上再没有档位 ⇒ 走 4px 栅格
+    assert_eq!(magnet_width(1180.0, 500.0), 500.0);
+    assert_eq!(magnet_width(1180.0, 497.0), 496.0);
+    // 低于最小档 ⇒ 吸到 280（不是变细）
+    assert_eq!(magnet_width(1180.0, 120.0), 280.0);
+    // 超过上限 ⇒ 夹在 612（中栗正好 472）
+    assert_eq!(magnet_width(1180.0, 900.0), 612.0);
+    assert_eq!(
+        content_width(1180.0, RailState::Expanded, 612.0),
+        1180.0 - 612.0 - 8.0
+    );
+
+    // 900 窗口：上限 = 900 − 88 − 472 − 8 = 332 ⇒ 360 档被夹到 332
+    assert_eq!(max_rail_width(900.0), 332.0);
+    assert_eq!(magnet_width(900.0, 360.0), 332.0);
+    // 窄到连 280 都放不下（700）：展开档不成立，返回折叠宽
+    assert_eq!(clamp_width(700.0, 320.0), COLLAPSED_WIDTH);
+    assert_eq!(
+        effective_state(700.0, RailState::Expanded, 320.0),
+        RailState::Collapsed
+    );
+    assert_eq!(
+        effective_state(1180.0, RailState::Expanded, 320.0),
+        RailState::Expanded
+    );
+}
+
+/// 三段常量必须互相自洽（改一个忘一个，图上就是「面板 320 但内容按 280 排」）。
+#[test]
+fn the_rail_constants_stay_consistent() {
+    assert_eq!(COLLAPSED_WIDTH, 48.0, "折叠条 = M3 触控目标");
+    assert_eq!(
+        DEFAULT_EXPANDED_WIDTH, 320.0,
+        "展开档 = 令牌 ai_panel_width"
+    );
+    assert_eq!(PRESETS, [280.0, 320.0, 360.0]);
+    assert_eq!(RESIZE_GUTTER, 8.0);
+    assert_eq!(MAGNET_RADIUS, 24.0);
+
+    assert!(
+        PRESETS.contains(&DEFAULT_EXPANDED_WIDTH),
+        "锚档必须在预设里"
+    );
+
+    // 下面两条用**变量**而不是常量表达式：clippy 的 `assertions_on_constants` 会把
+    // 「拿常量断言常量」判成无用断言，而这里断的正是两个常量之间的关系。
+    let shortest_rail = COLLAPSED_WIDTH;
+    let narrowest_panel = PRESETS[0];
+    assert!(shortest_rail < narrowest_panel, "折叠比最小展开还窄");
+
+    // 磁铁半径 > 档位间距的一半 ⇒ 280~360 之间没有「吸不住」的空档
+    let magnet = MAGNET_RADIUS;
+    let half_step = (PRESETS[1] - PRESETS[0]) / 2.0;
+    assert!(magnet > half_step);
+
+    // 三档名字是取证开关的取值，改名等于改命令行契约
+    for rail in RailState::ALL {
+        assert_eq!(RailState::from_name(rail.name()), Some(rail));
+    }
+    assert_eq!(RailState::from_name("open"), None);
+}
diff --git a/crates/app-iced/src/pages/agent/mod.rs b/crates/app-iced/src/pages/agent/mod.rs
new file mode 100644
index 0000000..e370868
--- /dev/null
+++ b/crates/app-iced/src/pages/agent/mod.rs
@@ -0,0 +1,371 @@
+//! # AI 助手（右栗三档 + `Route::Agent` 独立页）
+//!
+//! 用户定案（D16）：「右侧常驻可折叠，允许拆分成独立页」+「中栗宽度可调（磁铁吸附）」。
+//! 本模块交付**壳**：三档状态、布局数学、两个宿主共用的一份会话视图。
+//!
+//! **会话数据来自 presenter**（M119）：唯一来源是 `app/state.rs` 里的 `agent_host` →
+//! `AgentRail`。壳里不再有样本会话、也不再自己数未读——M104 当时的 `demo::transcript()`
+//! 只剩「截图取证要不要自动跑一轮」这一件事（见 [`demo`]）。
+//!
+//! ## 文件与职责
+//!
+//! | 文件 | 职责 |
+//! |---|---|
+//! | [`state`] | 三档状态机 + **布局数学**（纯函数，可脱机单测）+ [`AgentUi`]（挂在 `App` 上的纯 UI 态） |
+//! | `conversation` | **会话视图组件**：右栗与独立页唯一的对话 UI（输入契约见该文件） |
+//! | [`demo`] | `ULL_AGENT_*` 取证开关（自动跑一轮 / 三档 / 宽度 / 焦点环） |
+//! | 本文件 | 两个**宿主**（[`docked`] 右栗 / [`page`] 独立页）+ 消息枚举 + 拖拽层 |
+//! | `tests.rs` / `metrics/tests.rs` | 三档迁移 / 单实现判据 / a11y 文案；数值表与磁铁在后者 |
+//!
+//! ## 为什么物理路径在 `pages/agent/`、逻辑路径却是 `crate::shell::agent`
+//!
+//! M104 的 scope 给了 `pages/agent/**`，但**没给** `pages/mod.rs`（那是四条页面线共用的声明文件）。
+//! 于是 `shell/mod.rs` 用 `#[path = "../pages/agent/mod.rs"]` 挂载它——与 `app/mod.rs` 挂
+//! `../components/mod.rs` 是同一个先例。**没有第二份实现**：物理目录只有这一处。
+//!
+//! ## 三档状态（[`RailState`]）
+//!
+//! | 档位 | 右栗 | 会话在哪 | 切法 |
+//! |---|---|---|---|
+//! | `Collapsed` | 48 图标条 + 未读点 | 不画 | 点条上的 AI 图标 / `Esc` |
+//! | `Expanded` | 280~360（默认 320）+ 8 拖拽缝 | 面板内 | 条上图标 / `⌄` 收起 / 拆出后收回 |
+//! | `Detached` | 0 | `Route::Agent` 独立页 | `⇥` 拆出 / 导航第五项 `Assistant` |
+//!
+//! ## 为什么消息不走 `pages::Message`
+//!
+//! 助手栏是**外壳级视图**（挂在任何页面右边），不是某一页的消息：塞进 `pages::Message` 要动
+//! `app/update/page_messages.rs` 的穷尽 match，语义也不对。所以是一等公民 [`Message`] +
+//! `app::Message::Agent(..)` 一次映射，落点 `app/update/agent.rs`。
+
+pub(crate) mod demo;
+mod metrics;
+mod state;
+
+mod conversation;
+mod strip;
+
+#[cfg(test)]
+mod tests;
+
+pub use state::{AgentUi, Focus, RailState};
+
+use iced::widget::{column, container, mouse_area, row, rule, space, text, tooltip};
+use iced::{mouse, Alignment, Background, Border, Element, Length, Padding, Theme as IcedTheme};
+
+use unlucky_design::color::Role;
+use unlucky_design::elevation::MaterialLayer;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+use unlucky_i18n::{Catalog, Key};
+
+use unlucky_presenter::agent::AgentRail;
+use unlucky_presenter::dto::AppEvent;
+
+use crate::pages::{self, layout};
+use crate::theme::Ui;
+
+use conversation::{Conversation, Host};
+use metrics::RESIZE_GUTTER;
+
+/// 助手栏消息（**唯一**的消息类型；`app/view.rs` 用 `Message::Agent(..)` 包一层）。
+#[derive(Debug, Clone)]
+pub enum Message {
+    /// 折叠条 → 展开。
+    Expand,
+    /// `⌄` 收起 / 独立页上 `Esc`。
+    Collapse,
+    /// `⇥` 拆成独立页（同时压一层 `Route::Agent`）。
+    Detach,
+    /// `⇤` 收回右栗（离开 `Route::Agent`）。
+    Dock,
+    /// 输入框的编辑动作（由 `text_editor::on_action` 来）。
+    Edit(iced::widget::text_editor::Action),
+    /// 发送（`Send` 键 / 输入框里按 Enter）。
+    Submit,
+    /// 中断流式回复（`AppCommand::StopAgent`；收敛靠后端事件）。
+    Stop,
+    /// 允许 / 拒绝当前待确认的写操作（`rails.confirm` 非空时才有按钮）。
+    Confirm(bool),
+    /// **事件回流**（M119）：presenter 侧产生的 `AppEvent` 整批回到 `update` 的那条通道。
+    ///
+    /// 为什么是消息而不是直接改状态：异步后端在后台线程里产事件，UI 只能在节拍里抽；
+    /// 抽出来的这一批必须和「用户点击」走同一条漏斗（`on_agent`），否则两处各改一次状态，
+    /// 未读/流式标记会打架。落点见 `app/update/agent.rs` 的 `Events` 分支。
+    Events(Vec<AppEvent>),
+    /// 按下拖拽缝。
+    DragStart,
+    /// 拖拽中：窗口坐标里的指针 x。
+    DragTo(f32),
+    /// 松手。
+    DragEnd,
+    /// 键盘：`Esc`（收栗 / 独立页收回）。
+    Escape,
+    /// 键盘：`Tab`（走焦点环；`shift` = 反向）。
+    Tab { shift: bool },
+    /// 键盘：`Enter`（激活软焦点上的按钮）。
+    Activate,
+    /// 原始键盘事件（`app/subscription.rs` 的 `keyboard::listen()` 搬过来的）。
+    ///
+    /// 订阅层只负责搬运，**解释权**在 `app/update/agent.rs` 的 `on_agent_key`：
+    /// `Esc` / `Tab` / `Enter` 各自在什么状态下做什么，集中在一个函数里一眼看完。
+    Key(iced::keyboard::Event),
+}
+
+/// 错误横幅的**展示输入**（M119「失败态可见」的唯一落点）。
+///
+/// 为什么要包一层而不是把 `String` 传进来：标题必须是 catalog 键（`lang` 说哪种语言就哪种），
+/// 正文则有两种合法来源——具名原因码对应的 catalog 译文（端不可达 / 未实现），或 presenter
+/// 已经脱敏过的这一轮错误原文（`AgentRail::error`）。两者都是「已 sanitize 的展示串」，
+/// 页面不再加工（UI 层不复制脱敏逻辑）。
+#[derive(Debug, Clone, Copy)]
+pub struct Failure<'a> {
+    /// 横幅标题的 catalog 键。
+    pub title: Key,
+    /// 横幅正文（已脱敏 / 已是译文）。
+    pub body: &'a str,
+}
+
+/// 「这是模拟助手」的**四处文案**（M119 r2 / 复审 P2-1）。
+///
+/// ## 为什么是一个结构体而不是四个 `if`
+///
+/// 上一轮只有标题胶囊由 `simulated` 驱动，另外三处（副标题 / 输入框占位符 / 空态正文）是
+/// **无条件取词**，而它们的译文里写着「模拟 / 没接真实模型」——接上真 transport 之后，这三句会
+/// 反方向地留着（`simulated == false` 时界面上还在说「没接真实模型」）。复审把这条列为 P2。
+///
+/// 现在四处**只认这一个开关**：`Disclaimer::of(catalog, simulated)` 一次算好，视图没有第二种
+/// 取词路径。`pages/agent/tests/disclaimer.rs` 钉住「四处一起出现 / 一起消失」。
+#[derive(Debug, Clone, Copy)]
+pub struct Disclaimer<'a> {
+    /// 这套后端是不是模拟的（标题旁的胶囊只在 `true` 时画）。
+    pub simulated: bool,
+    /// 标题下的副标题。
+    pub subtitle: &'a str,
+    /// 输入框占位符。
+    pub placeholder: &'a str,
+    /// 空会话正文。
+    pub empty_body: &'a str,
+}
+
+impl<'a> Disclaimer<'a> {
+    /// 按 `simulated` 选模拟态或真实态那一套文案。
+    #[must_use]
+    pub fn of(catalog: Catalog, simulated: bool) -> Self {
+        Self {
+            simulated,
+            subtitle: if simulated {
+                catalog.text(Key::AgentSubtitle)
+            } else {
+                catalog.text(Key::AgentSubtitleReal)
+            },
+            placeholder: if simulated {
+                catalog.text(Key::AgentPlaceholder)
+            } else {
+                catalog.text(Key::AgentPlaceholderReal)
+            },
+            empty_body: if simulated {
+                catalog.text(Key::AgentEmptyBody)
+            } else {
+                catalog.text(Key::AgentEmptyBodyReal)
+            },
+        }
+    }
+}
+
+/// 两个宿主共用的**会话入参**（`Session` = 从 presenter 借来的那一份 + 两个展示事实）。
+///
+/// 为什么是一个结构体而不是继续加形参：`docked`/`page` 已经收到 6 个形参，这一轮还要加
+/// 「是不是模拟后端」——那会变成 7 个，正是塔台登记过的可维护性观察项。收成结构体之后两个宿主
+/// 各 3 个形参，且以后再加展示事实只改这个结构体。
+#[derive(Clone, Copy)]
+pub struct Session<'a> {
+    /// 三档/草稿/焦点（纯 UI 态）。
+    pub agent: &'a AgentUi,
+    /// 会话内容 / 未读 / busy / 待确认（presenter 的唯一真相）。
+    pub rail: &'a AgentRail,
+    /// 失败横幅的展示输入。
+    pub failure: Option<Failure<'a>>,
+    /// 这套后端是不是模拟的（M119 r1 / 复审 P2-1）。`true` ⇒ 头部常驻「模拟」标记，
+    /// 且三处文案走模拟态（见 [`Disclaimer`]：**四处一起变**，只认这一个开关）。
+    pub simulated: bool,
+}
+
+/// 停靠档的右栗（`None` = 已拆成独立页，右栗不占地）。
+///
+/// 两档共用同一条 `Element` 通道交给外壳的 `row!`：折叠是 48 的条，展开是「8 拖拽缝 + 面板」。
+pub fn docked<'a>(
+    ui: &'a Ui,
+    session: Session<'a>,
+    catalog: Catalog,
+    window_width: f32,
+) -> Option<Element<'a, Message>> {
+    // 判档用**这一窗宽下实际生效**的档位：窗窄到放不下 280 时，`Expanded` 事实上就是折叠条
+    // （否则会画一条 48 宽、还白扣 8px 拖拽缝的「面板」）。
+    match session.agent.effective_rail(window_width) {
+        RailState::Detached => None,
+        RailState::Collapsed => Some(strip::strip(ui, session.rail, catalog)),
+        RailState::Expanded => Some(panel(ui, session, catalog, window_width)),
+    }
+}
+
+/// `Route::Agent` 独立页（与右栗**同一个** `conversation::view`）。
+///
+/// 页级骨架（页边距 + 正文列宽）与其它页面同源：列宽取 [`layout::frame_metrics`]，单列 ≤424。
+pub fn page<'a>(
+    ui: &'a Ui,
+    session: Session<'a>,
+    catalog: Catalog,
+    window_width: f32,
+) -> Element<'a, Message> {
+    let metrics = layout::frame_metrics(pages::PaneKit::Single, window_width);
+
+    let body = conversation::view(ui, spec(session, catalog, Host::Page), catalog);
+
+    container(
+        container(body)
+            .width(Length::Fixed(metrics.column))
+            .height(Length::Fill),
+    )
+    .width(Length::Fill)
+    .height(Length::Fill)
+    .padding(metrics.gutter)
+    .align_x(Alignment::Center)
+    .align_y(Alignment::Start)
+    .into()
+}
+
+/// 拖拽层：拖拽期间铺满窗口，把指针 x 变成 [`Message::DragTo`]。
+///
+/// 为什么铺满整窗：`mouse_area::on_move` 只在**它自己的边界内**回报坐标，而拖拽时指针一定会离开
+/// 那 8px 的缝隙。铺满整窗后 `Point.x` 就是窗口坐标 ⇒ `目标宽 = 窗口宽 − x`。
+///
+/// **三条收尾路径**（复审 P3-7：`mouse_area` 在 `!cursor.is_over` 时直接 return，窗**外**松手
+/// 的 `on_release` 永远不来，于是叠层会留在最上层、右栗继续跟着指针缩放）：
+///
+/// | 路径 | 触发 | 语义 |
+/// |---|---|---|
+/// | `on_release` | 窗内松手 | 正常结束 |
+/// | `on_exit` | 指针离开窗口 | 「拖到窗外」= 收在当前值（不是把指针丢掉继续跟） |
+/// | `on_press` | 拖拽中再按一次 | 兜底清态（万一上两条都没来，一次点击就能恢复） |
+pub fn drag_overlay<'a>(agent: &AgentUi) -> Option<Element<'a, Message>> {
+    if !agent.is_dragging() {
+        return None;
+    }
+
+    Some(
+        mouse_area(
+            container(space::horizontal())
+                .width(Length::Fill)
+                .height(Length::Fill),
+        )
+        .interaction(mouse::Interaction::ResizingHorizontally)
+        .on_move(|point| Message::DragTo(point.x))
+        .on_release(Message::DragEnd)
+        .on_press(Message::DragEnd)
+        .on_exit(Message::DragEnd)
+        .into(),
+    )
+}
+
+// ---------------------------------------------------------------- 展开档：拖拽缝 + 面板
+
+fn panel<'a>(
+    ui: &'a Ui,
+    session: Session<'a>,
+    catalog: Catalog,
+    window_width: f32,
+) -> Element<'a, Message> {
+    let width = session.agent.rail_width(window_width);
+
+    let body = container(conversation::view(
+        ui,
+        spec(session, catalog, Host::Rail),
+        catalog,
+    ))
+    .width(Length::Fixed(width))
+    .height(Length::Fill)
+    .padding(Padding {
+        top: ui.space(Space::X6),
+        right: ui.space(Space::X4),
+        bottom: ui.space(Space::X4),
+        left: ui.space(Space::X4),
+    })
+    .style(move |_theme| container::Style {
+        background: Some(Background::Color(ui.layer(MaterialLayer::Canvas))),
+        ..container::Style::default()
+    });
+
+    row![splitter(ui, width, catalog), body]
+        .width(Length::Shrink)
+        .height(Length::Fill)
+        .into()
+}
+
+/// 8px 拖拽缝：1px 分隔线居中 + 水平缩放光标 + 按下即开拖 + **可读标签**（tooltip）。
+///
+/// 复审 P3-5：这条 8px 的缝此前没有任何可读文字，而 `AgentResize` / `AgentWidthLabel` 两条 key
+/// 在视图里一次没用（只在测试里被断言「不空」）——那是空头支票。现在 tooltip 同时给出
+/// 「拖它做什么」（`AgentResize`）与「当前多宽」（`AgentWidthLabel`），两个 key 都真用上了。
+fn splitter<'a>(ui: &'a Ui, width: f32, catalog: Catalog) -> Element<'a, Message> {
+    let line = container(
+        rule::vertical::<IcedTheme>(ui.metrics().divider_thickness).style(move |_theme| {
+            rule::Style {
+                color: ui.color(Role::OutlineVariant),
+                radius: ui.radius_dp(ShapeScale::None),
+                fill_mode: rule::FillMode::Full,
+                snap: true,
+            }
+        }),
+    )
+    .width(Length::Fixed(RESIZE_GUTTER))
+    .height(Length::Fill)
+    .align_x(Alignment::Center);
+
+    let grab = mouse_area(line)
+        .interaction(mouse::Interaction::ResizingHorizontally)
+        .on_press(Message::DragStart);
+
+    let tip_style = ui.style(TypeRole::BodySmall);
+    let pixels = format!("{width:.0}");
+    let tip = container(column![
+        text(catalog.text(Key::AgentResize))
+            .size(tip_style.size_px)
+            .font(ui.font_of(tip_style))
+            .color(ui.color(Role::OnSurface)),
+        text(catalog.render(Key::AgentWidthLabel, &[("width", pixels.as_str())]))
+            .size(tip_style.size_px)
+            .font(ui.font_of(tip_style))
+            .color(ui.color(Role::OnSurfaceVariant)),
+    ])
+    .padding(Padding::from([ui.space(Space::X1), ui.space(Space::X2)]))
+    .style(move |_theme| container::Style {
+        background: Some(Background::Color(ui.layer(MaterialLayer::Overlay))),
+        border: Border {
+            radius: ui.radius_dp(ShapeScale::Small),
+            ..Border::default()
+        },
+        ..container::Style::default()
+    });
+
+    tooltip(grab, tip, tooltip::Position::Left).into()
+}
+
+/// 会话视图的入参（**唯一**的组装点：两个宿主都走这里，不许各拼一份）。
+fn spec<'a>(session: Session<'a>, catalog: Catalog, host: Host) -> Conversation<'a> {
+    Conversation {
+        // 会话内容、未读、busy、待确认：**全部**来自 presenter（M119）
+        messages: &session.rail.messages,
+        busy: session.rail.busy,
+        unread: session.rail.unread,
+        confirm: session.rail.confirm.as_ref(),
+        failure: session.failure,
+        note: Disclaimer::of(catalog, session.simulated),
+        draft: &session.agent.draft,
+        blank: session.agent.draft_is_blank(),
+        rail: session.agent.rail,
+        host,
+        // 只有键盘巡航过才画焦点环（鼠标操作时那是噪音，而且会被误读成 tonal 按钮）
+        focus: session.agent.keyboard_mode.then_some(session.agent.focus),
+    }
+}
diff --git a/crates/app-iced/src/pages/agent/state.rs b/crates/app-iced/src/pages/agent/state.rs
new file mode 100644
index 0000000..651a8d9
--- /dev/null
+++ b/crates/app-iced/src/pages/agent/state.rs
@@ -0,0 +1,324 @@
+//! 右栗的**纯 UI 状态**：三档状态机 + 展开宽度 + 草稿 + 键盘焦点环 + [`AgentUi`]。
+//!
+//! 布局数学（宽度 / 磁铁吸附 / 中栗下限）在 [`super::metrics`]；这里只管「UI 状态怎么变」。
+//!
+//! ## 会话内容为什么不在这个文件里（M119）
+//!
+//! M104 的 `AgentUi` 自带 `transcript` / `busy` / `unread` 三个字段，数据来自内置样本
+//! （[`super::demo`]）——那是「壳先搭好、等 M103 接」的过渡态。M119 把这三个字段**删掉**：
+//! 会话的唯一来源是 presenter 的 `AgentRail`（`app/state.rs` 的 `agent_host`），右栗与独立页
+//! 直接读它。于是在这个文件里再放一份就是第二份真相，而两份真相必然漂。
+//!
+//! ## 三档状态（用户定案 D16）
+//!
+//! | 档位 | 右栗宽度 | 会话视图在哪 | 切法 |
+//! |---|---|---|---|
+//! | [`RailState::Collapsed`] | 48（图标条 + 未读点） | 不画 | `⌄` 收起 / `Esc` |
+//! | [`RailState::Expanded`] | 280~360（默认 320） | 右栗面板内 | 点图标条 / 收回 |
+//! | [`RailState::Detached`] | 0 | `Route::Agent` 独立页 | `⇥` 拆出 |
+//!
+//! 三档是**同一个会话**的三种呈现：切档只改 [`RailState`] 与路由栈，草稿与焦点一条都不丢
+//! （会话本身在 presenter 上，三档共享得比原来更彻底）。
+//!
+//! ## 未读 / busy 从哪来
+//!
+//! 都在 `AgentRail` 上：未读由 presenter 按「栏可见吗」累加、`agent_mark_read()` 清零；
+//! `busy` 由「有流式消息 || 有写操作待确认」算出来。壳里**不再自己数**未读。
+
+use iced::widget::text_editor;
+
+use super::metrics::{
+    content_width, effective_state, magnet_width, rail_width, DEFAULT_EXPANDED_WIDTH,
+};
+
+/// 三档状态（顺序 = 展开程度，测试与文件名按它遍历）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RailState {
+    /// 48px 图标条。
+    Collapsed,
+    /// 280~360 的会话面板。
+    Expanded,
+    /// 收进 `Route::Agent` 独立页（右栗消失）。
+    Detached,
+}
+
+impl RailState {
+    /// 三档全序（截图矩阵按它铺）。
+    pub const ALL: [RailState; 3] = [
+        RailState::Collapsed,
+        RailState::Expanded,
+        RailState::Detached,
+    ];
+
+    /// 稳定名字（文件名 / `ULL_AGENT_RAIL` 的取值 / 失败信息）。
+    pub const fn name(self) -> &'static str {
+        match self {
+            RailState::Collapsed => "collapsed",
+            RailState::Expanded => "expanded",
+            RailState::Detached => "detached",
+        }
+    }
+
+    /// 反向解析（取证开关用）。
+    pub fn from_name(name: &str) -> Option<Self> {
+        Self::ALL.into_iter().find(|state| state.name() == name)
+    }
+}
+
+/// 键盘软焦点顺序（Tab 环）。顺序 = 屏幕上的阅读顺序：头部动作 → 输入区动作 → 输入框。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Focus {
+    /// `⌄` 收起。
+    Collapse,
+    /// `⇥` 拆出（独立页上则是 `⇤` 收回，同一个焦点位）。
+    Detach,
+    /// 确认条的「允许」（只在有待确认写操作时存在于环上）。
+    ///
+    /// M119 r1 / 复审 P2-2：确认条原本只有鼠标路径——键盘用户在写操作确认这一步**卡死**
+    /// （`busy` 锁住发送，`Stop` 走的是主后端、清不掉 presenter 的待确认）。这两格就是那条键盘通路。
+    ConfirmAllow,
+    /// 确认条的「拒绝」。
+    ConfirmDeny,
+    /// 发送。
+    Send,
+    /// 中断（只在流式中出现）。
+    Stop,
+    /// 输入框（真实焦点由 iced 的 `text_editor` 持有，这里只记「轮到它了」）。
+    Composer,
+}
+
+impl Focus {
+    /// 稳定名字（日志 / 测试）。
+    pub const fn name(self) -> &'static str {
+        match self {
+            Focus::Collapse => "collapse",
+            Focus::Detach => "detach",
+            Focus::ConfirmAllow => "confirm-allow",
+            Focus::ConfirmDeny => "confirm-deny",
+            Focus::Send => "send",
+            Focus::Stop => "stop",
+            Focus::Composer => "composer",
+        }
+    }
+
+    /// Tab 环上「这一档真正存在的控件」。
+    ///
+    /// `confirm_pending` = 有待确认的写操作（那时条上多两格：允许 / 拒绝）。`busy` 在等确认时
+    /// 也是真（presenter 的 `busy = streaming || confirm.is_some()`），所以环上还会多一格中断。
+    fn order(state: RailState, busy: bool, confirm_pending: bool) -> Vec<Focus> {
+        let mut order = Vec::new();
+        match state {
+            RailState::Collapsed => order.push(Focus::Collapse),
+            RailState::Expanded => {
+                order.push(Focus::Collapse);
+                order.push(Focus::Detach);
+            }
+            RailState::Detached => order.push(Focus::Detach),
+        }
+        if confirm_pending {
+            order.push(Focus::ConfirmAllow);
+            order.push(Focus::ConfirmDeny);
+        }
+        if state != RailState::Collapsed {
+            order.push(Focus::Send);
+            if busy {
+                order.push(Focus::Stop);
+            }
+            order.push(Focus::Composer);
+        }
+        order
+    }
+
+    /// 下一个焦点（`shift` = 反向）。当前焦点不在环上时从头/尾进。
+    ///
+    /// `busy` 由 presenter 的 rail 给（壳里不自己数）：流式中环上多一格 `Stop`。
+    pub fn step(self, shift: bool, state: RailState, busy: bool, confirm_pending: bool) -> Focus {
+        let order = Self::order(state, busy, confirm_pending);
+        let Some(at) = order.iter().position(|focus| *focus == self) else {
+            return if shift { order.last() } else { order.first() }
+                .copied()
+                .unwrap_or(Focus::Collapse);
+        };
+        let next = if shift {
+            (at + order.len() - 1) % order.len()
+        } else {
+            (at + 1) % order.len()
+        };
+        order[next]
+    }
+}
+
+/// 助手栏的 UI 状态（挂在 `App` 上；**唯一**的写入口是 `app/update/agent.rs`）。
+pub struct AgentUi {
+    /// 三档状态。
+    pub rail: RailState,
+    /// 展开档的吸附宽度（三档共享一个值：收起再展开回到同一宽度）。
+    expanded: f32,
+    /// 输入框（多行；iced 的 `text_editor` 自己持有编辑状态，这里只放内容）。
+    pub draft: text_editor::Content,
+    /// 键盘软焦点。
+    pub focus: Focus,
+    /// 焦点环是否「被键盘走过」（`Tab` 置 true，鼠标点输入框 / 换档置 false）。
+    ///
+    /// 为什么需要它：`Enter` 全局订阅与输入框自己的 `key_binding` 共用同一个键。若不加这道闸，
+    /// 用户在**别的页面**用鼠标点过发送键之后，随手按 Enter 也会把草稿发出去。只有真的按过
+    /// `Tab`（= 用户在用键盘巡航助手栏）才让 `Activate` 生效。
+    pub keyboard_mode: bool,
+    /// 拖拽中的指针 x（`Some` = 正在拖）。
+    pointer: Option<f32>,
+}
+
+impl AgentUi {
+    /// 出厂态：**折叠** + 空草稿 + 无未读（未读由 presenter 按事件累加，M119）。
+    ///
+    /// 为什么默认折叠：1180 下展开 320 会把实例页挤成单列（中栗 852 < 816 的两列门槛之外还够，
+    /// 但 1024 就掉档了），用户第一次打开启动器不该先被一个助手栏改掉主页面版面。
+    pub fn new() -> Self {
+        Self {
+            rail: RailState::Collapsed,
+            expanded: DEFAULT_EXPANDED_WIDTH,
+            draft: text_editor::Content::new(),
+            focus: Focus::Composer,
+            keyboard_mode: false,
+            pointer: None,
+        }
+    }
+
+    /// 当前展开宽度（吸附后的值）。
+    pub fn expanded(&self) -> f32 {
+        self.expanded
+    }
+
+    /// 直接指定展开宽度（只给取证开关用：三档预设值之一）。
+    pub fn set_expanded(&mut self, width: f32) {
+        self.expanded = width;
+    }
+
+    /// 是否正在拖拽（shell 据此铺一层取指针的透明层）。
+    pub fn is_dragging(&self) -> bool {
+        self.pointer.is_some()
+    }
+
+    /// 这一窗宽下**实际**生效的档位（窄窗里 `Expanded` 会退化成 `Collapsed`）。
+    pub fn effective_rail(&self, window_width: f32) -> RailState {
+        effective_state(window_width, self.rail, self.expanded)
+    }
+
+    /// 右栗当前宽度（窗口宽度是判据之一：窗口变窄时展开档会被夹住）。
+    ///
+    /// 名字故意不叫 `width`：`tests/no_hardcoded_tokens.rs` 会把任何 `.width(数字)` 当成
+    /// 「布局尺寸写死」拦下来，而测试里 `agent.width(1180.0)` 会被误判（那条门禁扫的是控件调用点，
+    /// 分不清是谁的方法）。
+    pub fn rail_width(&self, window_width: f32) -> f32 {
+        rail_width(window_width, self.rail, self.expanded)
+    }
+
+    /// **交给页面布局系统的宽度**（窗口 − 右栗 − 拖拽缝）。
+    ///
+    /// `refresh_view` 用它算视图模型：面板展开后页面按更窄的宽度排版，内容才会「收缩」而不是
+    /// 顶到面板底下。
+    pub fn content_width(&self, window_width: f32) -> f32 {
+        content_width(window_width, self.rail, self.expanded)
+    }
+
+    /// 收起（`⌄` / `Esc`）。未读**不**清零：收起后新消息仍要能显示成点（清零由 app 层在
+    /// 「打开栏」时调 `agent_mark_read` 做——那是 presenter 的语义，不是 UI 的）。
+    pub fn collapse(&mut self) {
+        self.keyboard_mode = false;
+        if self.rail == RailState::Expanded {
+            self.rail = RailState::Collapsed;
+            self.focus = Focus::Collapse;
+        } else if self.rail == RailState::Detached {
+            self.dock();
+        }
+    }
+
+    /// 展开（点图标条）。展开即视为读过——**清零动作在 app 层**（`mark_read`），这里只改档位。
+    pub fn expand(&mut self) {
+        self.keyboard_mode = false;
+        self.rail = RailState::Expanded;
+        self.focus = Focus::Collapse;
+    }
+
+    /// 拆成独立页（`⇥`）。UI 状态一条不动（会话在 presenter 上，本来就不归这里管）。
+    pub fn detach(&mut self) {
+        self.keyboard_mode = false;
+        self.rail = RailState::Detached;
+        self.focus = Focus::Detach;
+    }
+
+    /// 收回右栗（`⇤` / 独立页上的 `Esc`）。
+    pub fn dock(&mut self) {
+        self.keyboard_mode = false;
+        self.rail = RailState::Expanded;
+        self.focus = Focus::Collapse;
+    }
+
+    /// 输入框内容变化（`text_editor::Action` 由 app 层转过来）。
+    ///
+    /// 这里**不**分 Enter / Shift+Enter：分流在 `conversation::composer::binding_for`（非 shift 的
+    /// Enter 根本不会变成 `Action`，它直接发 `Message::Submit`）。所以走到这里的 `Edit(Enter)`
+    /// 一定是「Shift+Enter 换行」那一支，`perform` 就够。
+    pub fn edit(&mut self, action: text_editor::Action) {
+        use iced::widget::text_editor::Action;
+
+        if matches!(action, Action::Click(_)) {
+            // 鼠标点了输入框 = 用户切回鼠标，键盘巡航结束（见 `keyboard_mode` 的理由）
+            self.focus = Focus::Composer;
+            self.keyboard_mode = false;
+        }
+        self.draft.perform(action);
+    }
+
+    /// 清空输入框（发送成功之后调：草稿已经交给 presenter 了）。
+    pub fn clear_draft(&mut self) {
+        self.draft = text_editor::Content::new();
+    }
+
+    /// 输入框是否为空（发送键的禁用判据）。
+    pub fn draft_is_blank(&self) -> bool {
+        self.draft.text().trim().is_empty()
+    }
+
+    /// 拖拽开始（按下分隔条）。`0.0` 只是占位：第一次 `drag_to` 就会换成真实指针位置。
+    pub fn drag_start(&mut self) {
+        self.pointer = Some(0.0);
+    }
+
+    /// 拖拽中：`x` = 指针在**窗口**里的横坐标（0 = 窗口左缘）。
+    pub fn drag_to(&mut self, window_width: f32, x: f32) {
+        if self.pointer.is_none() {
+            return;
+        }
+        self.pointer = Some(x);
+        self.expanded = magnet_width(window_width, window_width - x);
+    }
+
+    /// 拖拽结束（松手）。
+    pub fn drag_end(&mut self) {
+        self.pointer = None;
+    }
+
+    /// Tab 走一格（走一次就把键盘巡航打开）。`busy` / `confirm_pending` 都由 presenter 的 rail 给。
+    ///
+    /// **待确认的那一次 Tab 只点亮焦点环、不移动焦点**：待确认出现时 app 层已经把焦点放到
+    /// 「允许」上（阻塞态，见 `App::sync_confirm_focus`），但**不会**替用户把键盘巡航打开
+    /// （M119 r2 / 复审 P2-2：自动 arm 会让用户随手敲的空格变成「批准」）。所以第一次 `Tab`
+    /// 是「我要用键盘」的显式表态，此时焦点原地不动——否则第一次 Tab 会把「允许」挪到「拒绝」，
+    /// 用户按 `Enter` 就是反着裁决。
+    pub fn step_focus(&mut self, shift: bool, busy: bool, confirm_pending: bool) {
+        let arming = !self.keyboard_mode
+            && confirm_pending
+            && matches!(self.focus, Focus::ConfirmAllow | Focus::ConfirmDeny);
+        self.keyboard_mode = true;
+        if !arming {
+            self.focus = self.focus.step(shift, self.rail, busy, confirm_pending);
+        }
+    }
+}
+
+impl Default for AgentUi {
+    fn default() -> Self {
+        Self::new()
+    }
+}
diff --git a/crates/app-iced/src/pages/agent/strip.rs b/crates/app-iced/src/pages/agent/strip.rs
new file mode 100644
index 0000000..d9d335b
--- /dev/null
+++ b/crates/app-iced/src/pages/agent/strip.rs
@@ -0,0 +1,133 @@
+//! 折叠档：48px 图标条（M119 从 `mod.rs` 拆出来守 400 行硬线）。
+//!
+//! 条上三行：AI 图标（带未读点）+ 小字标签 + 未读计数。为什么未读既有点又有数字：48px 宽
+//! 装不下 `2 unread` 那 8 个字符（实测贴到窗角被裁），所以条上只放「有几条」，完整那句
+//! （`{count} unread`）在面板头部的胶囊里。零未读时给一个等高留白，免得条上元素上下跳。
+//!
+//! 未读数来自 presenter 的 `AgentRail::unread`（M119 起壳里不再自己数）。
+
+use iced::widget::{column, container, space, stack, text, tooltip};
+use iced::{Alignment, Background, Border, Element, Length, Padding};
+
+use unlucky_design::color::Role;
+use unlucky_design::elevation::MaterialLayer;
+use unlucky_design::icons::IconKind;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+use unlucky_i18n::{Catalog, Key};
+
+use unlucky_presenter::agent::AgentRail;
+
+use crate::app::components::buttons::{self, IconVariant};
+use crate::theme::Ui;
+
+use super::metrics::COLLAPSED_WIDTH;
+use super::{conversation, Message};
+
+/// 折叠条。
+pub(super) fn strip<'a>(ui: &'a Ui, rail: &'a AgentRail, catalog: Catalog) -> Element<'a, Message> {
+    let side = ui.metrics().control_height;
+
+    // 图标按钮 40×40（M3 icon button），未读点叠在右上角；下面两行小字保证「不得只有图标」：
+    // 条上每个可点元素都有可读文字（完整名字在 tooltip 里）。
+    let icon: Element<'a, Message> = buttons::icon(
+        ui,
+        IconVariant::Standard,
+        IconKind::Ai,
+        Some(Message::Expand),
+        None,
+    );
+
+    let glyph: Element<'a, Message> = if rail.unread > 0 {
+        stack![
+            icon,
+            container(dot(ui))
+                .width(Length::Fixed(side))
+                .height(Length::Fixed(side))
+                .align_x(Alignment::End)
+                .align_y(Alignment::Start)
+                .padding(Padding::from([0.0, ui.space(Space::X1)])),
+        ]
+        .into()
+    } else {
+        icon
+    };
+
+    let labelled = container(column![
+        glyph,
+        conversation::text_role(
+            ui,
+            TypeRole::LabelMedium,
+            false,
+            catalog.text(Key::AgentStripLabel),
+            ui.color(Role::OnSurfaceVariant),
+            // `Shrink` 而不是 `Fill`：48 宽的条上 Fill 会让文字贴左缘，"2 unread" 会被窗角裁掉
+            Length::Shrink,
+        ),
+        unread_text(ui, rail.unread),
+    ])
+    .width(Length::Fixed(COLLAPSED_WIDTH))
+    .align_x(Alignment::Center)
+    .padding(Padding::from([ui.space(Space::X6), 0.0]));
+
+    let tip_style = ui.style(TypeRole::BodySmall);
+    let tip = container(
+        text(catalog.text(Key::AgentOpen))
+            .size(tip_style.size_px)
+            .font(ui.font_of(tip_style))
+            .color(ui.color(Role::OnSurface)),
+    )
+    .padding(Padding::from([ui.space(Space::X1), ui.space(Space::X2)]))
+    .style(move |_theme| container::Style {
+        background: Some(Background::Color(ui.layer(MaterialLayer::Overlay))),
+        border: Border {
+            radius: ui.radius_dp(ShapeScale::Small),
+            ..Border::default()
+        },
+        ..container::Style::default()
+    });
+
+    container(tooltip(labelled, tip, tooltip::Position::Left))
+        .width(Length::Fixed(COLLAPSED_WIDTH))
+        .height(Length::Fill)
+        .style(move |_theme| container::Style {
+            background: Some(Background::Color(ui.layer(MaterialLayer::Canvas))),
+            ..container::Style::default()
+        })
+        .into()
+}
+
+/// 未读点（8×8，`Primary`）。
+fn dot<'a>(ui: &'a Ui) -> Element<'a, Message> {
+    let side = ui.space(Space::X2);
+
+    container(space::horizontal())
+        .width(Length::Fixed(side))
+        .height(Length::Fixed(side))
+        .style(move |_theme| container::Style {
+            background: Some(Background::Color(ui.color(Role::Primary))),
+            border: Border {
+                radius: ui.radius(ShapeScale::Full, side),
+                ..Border::default()
+            },
+            ..container::Style::default()
+        })
+        .into()
+}
+
+/// 未读计数（零 = 等高留白，免得条上元素上下跳）。
+fn unread_text<'a>(ui: &'a Ui, unread: usize) -> Element<'a, Message> {
+    let style = ui.style(TypeRole::LabelMedium);
+
+    if unread == 0 {
+        return space::vertical().height(style.line_height_px).into();
+    }
+
+    text(unread.to_string())
+        .size(style.size_px)
+        .font(ui.font_of(style))
+        .color(ui.color(Role::Primary))
+        .width(Length::Shrink)
+        .into()
+}
diff --git a/crates/app-iced/src/pages/agent/tests.rs b/crates/app-iced/src/pages/agent/tests.rs
new file mode 100644
index 0000000..b01d3c7
--- /dev/null
+++ b/crates/app-iced/src/pages/agent/tests.rs
@@ -0,0 +1,398 @@
+//! 三档状态机、两个宿主、a11y 文案的判据（数值表与磁铁在 `metrics/tests.rs`）。
+//!
+//! 每条断言都写清「抓得住什么 / 抓不住什么」——纯函数与源码扫描能钉住语义，**钉不住**像素。
+//!
+//! M119 起这里的重心变了：会话内容不再由本模块持有，所以「提交会怎样」这类端到端断言搬到了
+//! `app/update/agent/tests.rs`（那里能拿到 presenter 句柄）。这里留的是**纯 UI 态**与**视图契约**。
+
+use unlucky_design::color::SchemeFlavor;
+use unlucky_design::typography::Platform;
+use unlucky_i18n::{Catalog, Key, Lang};
+
+use unlucky_presenter::agent::AgentRail;
+use unlucky_presenter::dto::{ChatMessage, ChatRole, ConfirmRequest, Sensitivity};
+
+use crate::theme::{Families, Ui};
+
+mod disclaimer;
+mod drag;
+
+use super::conversation::{Conversation, Host};
+use super::state::{AgentUi, Focus, RailState};
+use super::*;
+
+const FAMILIES: Families = Families {
+    text: "Segoe UI",
+    display: "Segoe UI",
+    mono: "Consolas",
+};
+
+pub(super) fn ui() -> Ui {
+    Ui::with_platform(SchemeFlavor::Light, Platform::Windows, FAMILIES)
+}
+
+/// 一条只给视图用的 rail（会话内容由 presenter 生产，这里只造**渲染输入**）。
+fn rail(messages: Vec<ChatMessage>, unread: usize, busy: bool) -> AgentRail {
+    AgentRail {
+        messages,
+        unread,
+        busy,
+        ..AgentRail::new()
+    }
+}
+
+fn conversation_rail() -> AgentRail {
+    rail(
+        vec![
+            ChatMessage::user("Which instance should I start?"),
+            ChatMessage {
+                role: ChatRole::Assistant,
+                text: "Survival is on 1.20.4.".to_string(),
+                tool: None,
+                streaming: false,
+            },
+        ],
+        2,
+        false,
+    )
+}
+
+/// 三档迁移：**草稿与焦点**跟着走（会话在 presenter 上，本来就不归这里管）。
+///
+/// 抓得住：`expand()/detach()/dock()` 把档位改对且不清草稿；`collapse()` 对 Detached 等价于 `dock()`。
+/// 抓不住：切换时有没有一次「闪一下」的重排（那要出图看）。
+#[test]
+fn the_three_states_share_one_draft() {
+    let mut agent = AgentUi::new();
+    assert_eq!(agent.rail, RailState::Collapsed, "出厂是折叠档");
+
+    agent.expand();
+    assert_eq!(agent.rail, RailState::Expanded);
+
+    // 走 `AgentUi::edit`（= app 层真正的落点），而不是直接操作 iced 的 `Content`：
+    // 走到这里的 `Edit(Enter)` 只可能是 Shift+Enter（非 shift 的 Enter 在 composer 的
+    // `key_binding` 里就变成 `Message::Submit` 了）。
+    agent.draft = iced::widget::text_editor::Content::with_text("kick off Survival");
+    agent.edit(iced::widget::text_editor::Action::Edit(
+        iced::widget::text_editor::Edit::Enter,
+    ));
+    assert_eq!(
+        agent.draft.line_count(),
+        2,
+        "多行：一条 Edit(Enter) 之后成两行"
+    );
+
+    let draft = agent.draft.text();
+    agent.detach();
+    assert_eq!(agent.rail, RailState::Detached);
+    assert_eq!(agent.draft.text(), draft, "拆出去不丢草稿");
+
+    agent.dock();
+    assert_eq!(agent.rail, RailState::Expanded);
+    assert_eq!(agent.draft.text(), draft);
+
+    // 收起 / Esc：只改档位
+    agent.collapse();
+    assert_eq!(agent.rail, RailState::Collapsed);
+    // 独立页上的 Esc = 收回（`collapse` 对 Detached 等价于 dock）
+    agent.rail = RailState::Detached;
+    agent.collapse();
+    assert_eq!(agent.rail, RailState::Expanded);
+}
+
+/// 草稿只有两个写口：`edit`（打字）与 `clear_draft`（发送成功之后）。
+#[test]
+fn sending_clears_the_draft_and_blank_is_trimmed() {
+    let mut agent = AgentUi::new();
+    assert!(agent.draft_is_blank());
+    agent.draft = iced::widget::text_editor::Content::with_text("   ");
+    assert!(agent.draft_is_blank(), "只有空白也算空（发送键是禁用态）");
+    agent.draft = iced::widget::text_editor::Content::with_text("  hello  ");
+    assert!(!agent.draft_is_blank());
+    agent.clear_draft();
+    assert!(agent.draft_is_blank(), "发出去后草稿清空");
+}
+
+/// 空会话：零消息 + 一句引导文案（任务第 7 条）。
+#[test]
+fn the_empty_session_has_a_guidance_line() {
+    let catalog = Catalog::of(Lang::En);
+    assert!(!catalog.text(Key::AgentEmptyTitle).is_empty());
+    assert!(
+        catalog.text(Key::AgentEmptyBody).split_whitespace().count() >= 5,
+        "空态要有一句能读懂下一步的引导，而不是一个词"
+    );
+    // 中文也得有且不同（D28：两套目录一行一个 key，缺译会红）
+    let zh = Catalog::of(Lang::ZhCn);
+    assert_ne!(
+        zh.text(Key::AgentEmptyBody),
+        catalog.text(Key::AgentEmptyBody)
+    );
+}
+
+/// **单实现判据**：右栗与独立页都只通过 `conversation::view` 画对话。
+///
+/// 抓得住：有人把「独立页要更宽」当成理由另写一份气泡/输入框装配（复制粘贴是这类任务最常见的坏法）。
+/// 抓不住：`conversation::view` **内部**再分叉成两套（那要人读那个文件）。
+#[test]
+fn both_hosts_render_the_same_conversation() {
+    let hosts = include_str!("mod.rs");
+    let conversation = include_str!("conversation.rs");
+    let composer = include_str!("conversation/composer.rs");
+
+    assert_eq!(
+        conversation.matches("pub fn view<").count(),
+        1,
+        "会话视图只能有一个 `view`"
+    );
+    assert_eq!(
+        hosts.matches("conversation::view(").count(),
+        2,
+        "右栗与独立页各调用一次同一个 `conversation::view`（不多不少）"
+    );
+    assert!(
+        !hosts.contains("text_editor("),
+        "输入框的装配只许在 conversation/composer.rs 里（宿主不许自己拼一份）"
+    );
+    assert!(
+        !hosts.contains("scrollable("),
+        "滚动区的装配只许在 conversation/transcript.rs 里"
+    );
+    assert!(
+        composer.contains("text_editor(") || composer.contains("editor(spec.draft)"),
+        "输入框就在 composer 里"
+    );
+    // M119：会话内容的唯一来源是 presenter 的 rail ⇒ 宿主把 rail 借进来，而不是自己造
+    assert!(
+        !hosts.contains("Vec<ChatMessage>") && !hosts.contains("Vec<Turn>"),
+        "宿主里不许出现自持的会话容器"
+    );
+}
+
+/// a11y：所有动作按钮的标签都来自词表，折叠条也不是「只有图标」。
+///
+/// 抓得住：有人写死一句英文/中文在视图里（"Cancel"/"发送"），或给折叠条只留一个图标按钮。
+/// 抓不住：译文本身好不好读（那要人看）。
+#[test]
+fn every_action_has_a_readable_label() {
+    let catalog = Catalog::of(Lang::En);
+    for key in [
+        Key::AgentCollapse,
+        Key::AgentDetach,
+        Key::AgentDock,
+        Key::AgentOpen,
+        Key::AgentSend,
+        Key::AgentStop,
+        Key::AgentStripLabel,
+        Key::AgentResize,
+        Key::AgentWidthLabel,
+        // M119 新增：确认条的两个动作 + 失败横幅的标题
+        Key::AgentConfirmAllow,
+        Key::AgentConfirmDeny,
+        Key::AgentConfirmRequest,
+        Key::AgentErrorTitle,
+        Key::AgentErrorUnavailable,
+        Key::AgentErrorNotImplemented,
+        // M119 r1 / P2-1：「这是模拟」的常驻标记也必须有词（用户不点就要能看到）
+        Key::AgentSimulated,
+        Key::AgentSubtitle,
+    ] {
+        assert!(
+            !catalog.text(key).trim().is_empty(),
+            "{} 没有可读标签",
+            key.name()
+        );
+    }
+
+    for source in [
+        include_str!("conversation.rs"),
+        include_str!("conversation/composer.rs"),
+        include_str!("conversation/banners.rs"),
+        include_str!("conversation/transcript.rs"),
+        include_str!("strip.rs"),
+        include_str!("mod.rs"),
+    ] {
+        for literal in ["Button::new(\"", "Button::disabled(\""] {
+            assert!(
+                !source.contains(literal),
+                "按钮标签不许写死在视图里：{literal}"
+            );
+        }
+        assert!(
+            !source.contains("text(\"Assistant\""),
+            "文案不许写死在视图里（走 i18n 的 Key）"
+        );
+    }
+
+    // 折叠条的 48px 条上，图标下面必须有文字标签（否则就是「只有图标」）
+    assert!(
+        include_str!("strip.rs").contains("Key::AgentStripLabel"),
+        "折叠条必须有可读的条上标签"
+    );
+}
+
+/// Tab 环：只在**真正存在**的控件之间走，且顺序自左向右可预期。
+#[test]
+fn the_focus_ring_walks_the_controls_that_exist() {
+    // 展开且空闲：收起 → 拆出 → 发送 → 输入框（没有中断键）
+    let mut focus = Focus::Collapse;
+    let mut walked = vec![focus];
+    for _ in 0..4 {
+        focus = focus.step(false, RailState::Expanded, false, false);
+        walked.push(focus);
+    }
+    assert_eq!(
+        walked,
+        vec![
+            Focus::Collapse,
+            Focus::Detach,
+            Focus::Send,
+            Focus::Composer,
+            Focus::Collapse,
+        ]
+    );
+
+    // 反向：Collapse 往回走是 Composer
+    assert_eq!(
+        Focus::Collapse.step(true, RailState::Expanded, false, false),
+        Focus::Composer
+    );
+
+    // 流式中多一档中断键（`busy` 由 presenter 的 rail 给）
+    assert_eq!(
+        Focus::Send.step(false, RailState::Expanded, true, false),
+        Focus::Stop
+    );
+
+    // 独立页只有「收回 + 输入区」
+    assert_eq!(
+        Focus::Detach.step(false, RailState::Detached, false, false),
+        Focus::Send
+    );
+
+    // 折叠档没有会话动作：环上只有「展开」一格
+    assert_eq!(
+        Focus::Collapse.step(false, RailState::Collapsed, false, false),
+        Focus::Collapse
+    );
+
+    // `Tab` 真的把键盘巡航打开（`Enter` 的闸门）
+    let mut agent = AgentUi::new();
+    assert!(!agent.keyboard_mode);
+    agent.step_focus(false, false, false);
+    assert!(agent.keyboard_mode);
+
+    // M119 r1 / P2-2：有待确认写操作时，环上多两格（允许 / 拒绝），且**排在发送之前**——
+    // 阻塞态该先被看见。这也是键盘用户唯一能推进这一轮的路径。
+    assert_eq!(
+        Focus::Detach.step(false, RailState::Expanded, true, true),
+        Focus::ConfirmAllow
+    );
+    assert_eq!(
+        Focus::ConfirmAllow.step(false, RailState::Expanded, true, true),
+        Focus::ConfirmDeny
+    );
+    assert_eq!(
+        Focus::ConfirmDeny.step(false, RailState::Expanded, true, true),
+        Focus::Send
+    );
+    // 没有待确认时这两格不在环上（鼠标用户不该 Tab 到不存在的按钮）
+    assert_eq!(
+        Focus::Detach.step(false, RailState::Expanded, false, false),
+        Focus::Send
+    );
+}
+
+/// 视图契约：`spec()` 把 presenter 的三件事**原样借**给视图（零拷贝、不复制）。
+///
+/// 抓得住：有人在 `spec()` 里换掉/派生一份会话（那就会有两份真相）。
+/// 抓不住：`Conversation` 字段在视图里怎么用（那要人读 conversation.rs）。
+#[test]
+fn the_spec_borrows_the_presenter_rail_verbatim() {
+    let mut agent = AgentUi::new();
+    agent.expand();
+    let rail = conversation_rail();
+    let session = Session {
+        agent: &agent,
+        rail: &rail,
+        failure: None,
+        simulated: true,
+    };
+    let spec = super::spec(session, Catalog::of(Lang::En), Host::Rail);
+    assert_eq!(spec.messages.len(), rail.messages.len());
+    assert_eq!(spec.messages[0].text, rail.messages[0].text, "同一条消息");
+    assert_eq!(spec.unread, rail.unread);
+    assert_eq!(spec.busy, rail.busy);
+    assert!(spec.failure.is_none());
+    assert!(
+        spec.note.simulated,
+        "模拟事实要原样传给视图（标记不是硬编码）"
+    );
+    assert!(
+        spec.note.subtitle.to_lowercase().contains("simulated"),
+        "副标题也归这个开关管：{}",
+        spec.note.subtitle
+    );
+}
+
+/// 两个宿主都能构图（含空会话 / 有会话 / 流式中 / 待确认 / 失败横幅），且吃 880~2560 的宽度。
+///
+/// 抓得住：某档位下 `view` 的某条分支 panic（例如空消息 + 非零未读、确认条 + 失败横幅同时出现）。
+/// 抓不住：像素级观感（出图另算）。
+#[test]
+fn every_state_builds_in_both_hosts() {
+    let ui = ui();
+    let catalog = Catalog::of(Lang::En);
+    let empty = AgentRail::new();
+    let full = conversation_rail();
+    let busy = rail(conversation_rail().messages, 0, true);
+    let failed = AgentRail {
+        error: Some("provider 断流：read timeout".to_string()),
+        ..conversation_rail()
+    };
+    let mut confirm_rail = conversation_rail();
+    confirm_rail.confirm = Some(ConfirmRequest {
+        id: "req-1".to_string(),
+        tool: "set_config".to_string(),
+        summary: "把下载并发 64 → 16".to_string(),
+        details: Default::default(),
+        sensitivity: Sensitivity::High,
+    });
+    let failure = Failure {
+        title: Key::AgentErrorTitle,
+        body: "The assistant backend is unreachable.",
+    };
+
+    for window in [880.0, 900.0, 1180.0, 2560.0] {
+        for rail in [&empty, &full, &busy, &failed, &confirm_rail] {
+            for state in RailState::ALL {
+                let mut agent = AgentUi::new();
+                agent.rail = state;
+                for shown in [None, Some(failure)] {
+                    let session = Session {
+                        agent: &agent,
+                        rail,
+                        failure: shown,
+                        simulated: true,
+                    };
+                    let _: iced::Element<'_, Message> = page(&ui, session, catalog, window);
+                    let _ = docked(&ui, session, catalog, window);
+                    let spec = Conversation {
+                        messages: &rail.messages,
+                        draft: &agent.draft,
+                        busy: rail.busy,
+                        unread: rail.unread,
+                        blank: agent.draft_is_blank(),
+                        confirm: rail.confirm.as_ref(),
+                        failure: shown,
+                        note: Disclaimer::of(catalog, true),
+                        rail: agent.rail,
+                        host: Host::Rail,
+                        focus: agent.keyboard_mode.then_some(agent.focus),
+                    };
+                    let _: iced::Element<'_, Message> = conversation::view(&ui, spec, catalog);
+                }
+            }
+        }
+    }
+}
diff --git a/crates/app-iced/src/pages/agent/tests/disclaimer.rs b/crates/app-iced/src/pages/agent/tests/disclaimer.rs
new file mode 100644
index 0000000..fcb637f
--- /dev/null
+++ b/crates/app-iced/src/pages/agent/tests/disclaimer.rs
@@ -0,0 +1,96 @@
+//! 「这是模拟助手」的四处文案必须**一起**变（M119 r2 / 复审 P2-1 的验收标准）。
+//!
+//! ## 为什么这个文件存在
+//!
+//! 复审 r2 的 P2-1 抓得很准：`simulated` 是真字段，但 r1 只有**标题胶囊**一个消费者，另外三处
+//! （副标题 / 输入框占位符 / 空态正文）是**无条件取词**，而它们的译文里写着「模拟 / 没接真实模型」。
+//! 于是「接上真 transport 之后四处一起消失」只是一句声明——没有测试钉住它。
+//!
+//! 现在四处都从 [`Disclaimer`] 取词（`Disclaimer::of(catalog, simulated)`），本文件就是那句声明的
+//! 证据：`simulated == true` 四处都提模拟；`simulated == false` 四处**都不提**。
+//!
+//! 抓得住：谁把某一处改回无条件取词（那就会出现「字段说真、界面说模拟」的反向假话）。
+//! 抓不住：文案本身翻得好不好读（那要人看），也不管视图有没有真的用这几个字段
+//! （那是 `tests.rs::the_spec_borrows_the_presenter_rail_verbatim` 与出图的活）。
+
+use unlucky_i18n::{Catalog, Key, Lang};
+
+use super::super::Disclaimer;
+
+/// 这句话里有没有「模拟 / 没接真实模型」的意思（中英各一套写法）。
+fn mentions_simulated(text: &str) -> bool {
+    let lower = text.to_lowercase();
+    lower.contains("simulated") || lower.contains("no real model") || text.contains("模拟")
+}
+
+/// **四处一起出现**（`simulated == true`）：副标题 / 占位符 / 空态正文 / 标题胶囊。
+#[test]
+fn all_four_disclaimers_appear_when_the_backend_is_simulated() {
+    for lang in [Lang::En, Lang::ZhCn] {
+        let catalog = Catalog::of(lang);
+        let note = Disclaimer::of(catalog, true);
+        assert!(note.simulated, "{}：开关要传下去", lang.tag());
+        for (place, text) in [
+            ("副标题", note.subtitle),
+            ("输入框占位符", note.placeholder),
+            ("空态正文", note.empty_body),
+            // 第四处是标题胶囊：只在 `simulated` 时渲染，文案来自这条 key
+            ("标题胶囊", catalog.text(Key::AgentSimulated)),
+        ] {
+            assert!(
+                mentions_simulated(text),
+                "{} 的{place}没有说清「这是模拟」：{text:?}",
+                lang.tag()
+            );
+        }
+    }
+}
+
+/// **四处一起消失**（`simulated == false`）：三处文案都不许再提模拟，胶囊也不该被画。
+///
+/// 这条就是复审要的那一句验收：接上真 transport 那天，界面不会再反向地声明「没接真实模型」。
+#[test]
+fn no_disclaimer_survives_when_a_real_backend_is_wired() {
+    for lang in [Lang::En, Lang::ZhCn] {
+        let catalog = Catalog::of(lang);
+        let note = Disclaimer::of(catalog, false);
+        assert!(!note.simulated, "{}：开关要传下去", lang.tag());
+        for (place, text) in [
+            ("副标题", note.subtitle),
+            ("输入框占位符", note.placeholder),
+            ("空态正文", note.empty_body),
+        ] {
+            assert!(
+                !mentions_simulated(text),
+                "{} 的{place}在真实态还在说模拟：{text:?}",
+                lang.tag()
+            );
+        }
+        // 真实态的三句也得是**有内容的话**，不能靠空串糊过去
+        for (place, text) in [
+            ("副标题", note.subtitle),
+            ("输入框占位符", note.placeholder),
+            ("空态正文", note.empty_body),
+        ] {
+            assert!(!text.trim().is_empty(), "{} 的{place}是空的", lang.tag());
+        }
+    }
+}
+
+/// 两态必须是**两套不同的文案**（同一个 key 两边都用就退化成「永远说模拟」或「永远不说」）。
+#[test]
+fn the_two_states_use_different_keys() {
+    let catalog = Catalog::of(Lang::En);
+    assert_ne!(
+        catalog.text(Key::AgentSubtitle),
+        catalog.text(Key::AgentSubtitleReal)
+    );
+    assert_ne!(
+        catalog.text(Key::AgentPlaceholder),
+        catalog.text(Key::AgentPlaceholderReal)
+    );
+    assert_ne!(
+        catalog.text(Key::AgentEmptyBody),
+        catalog.text(Key::AgentEmptyBodyReal)
+    );
+}
diff --git a/crates/app-iced/src/pages/agent/tests/drag.rs b/crates/app-iced/src/pages/agent/tests/drag.rs
new file mode 100644
index 0000000..5dbbeb5
--- /dev/null
+++ b/crates/app-iced/src/pages/agent/tests/drag.rs
@@ -0,0 +1,150 @@
+//! 拖拽与「缝」的判据（从 `tests.rs` 拆出来：那边加完复审 r1 的断言后顶到 436 行，
+//! 而 AGENTS.md §3-1 是 400 行硬线）。
+//!
+//! 拆的位置是「指针/几何」这一族：拖拽三条收尾路径、吸附宽度写回、缝的预算、缝与折叠条的标签。
+
+use unlucky_presenter::agent::AgentRail;
+
+use super::super::metrics::{layout_for, PRESETS, RESIZE_GUTTER};
+use super::super::state::{AgentUi, RailState};
+
+use super::super::{docked, drag_overlay};
+use super::ui;
+
+/// 拖拽层只在拖拽期间存在（否则它会吃掉整窗的点击）。
+#[test]
+fn the_drag_overlay_only_exists_while_dragging() {
+    let mut agent = AgentUi::new();
+    agent.expand();
+    assert!(drag_overlay(&agent).is_none());
+
+    agent.drag_start();
+    assert!(agent.is_dragging());
+    assert!(drag_overlay(&agent).is_some());
+
+    agent.drag_end();
+    assert!(drag_overlay(&agent).is_none());
+}
+
+/// 拆出档右栗必须**不占地**（否则会话会在两个地方各画一份）。
+#[test]
+fn the_detached_state_frees_the_rail_slot() {
+    let ui = ui();
+    let mut agent = AgentUi::new();
+    agent.detach();
+    let session = super::super::Session {
+        agent: &agent,
+        rail: &AgentRail::new(),
+        failure: None,
+        simulated: true,
+    };
+    assert!(docked(
+        &ui,
+        session,
+        unlucky_i18n::Catalog::of(unlucky_i18n::Lang::En),
+        1180.0
+    )
+    .is_none());
+    assert_eq!(agent.rail_width(1180.0), 0.0);
+    assert_eq!(agent.content_width(1180.0), 1180.0);
+}
+
+/// 拖拽把「展开宽度」写进状态（松手后保有该宽度）。
+#[test]
+fn the_drag_writes_back_the_snapped_width() {
+    let mut agent = AgentUi::new();
+    agent.expand();
+    agent.drag_start();
+    agent.drag_to(1180.0, 1180.0 - 280.0);
+    agent.drag_end();
+    assert_eq!(agent.expanded(), 280.0);
+    assert!(!agent.is_dragging());
+
+    // 没按下就收到的 DragTo（例如上一步松手后的残留）不该改宽度
+    let before = agent.expanded();
+    agent.drag_to(1180.0, 100.0);
+    assert_eq!(agent.expanded(), before);
+
+    // 三档预设都能被拖到（1180 下上限 612 > 360）
+    for preset in PRESETS {
+        agent.drag_start();
+        agent.drag_to(1180.0, 1180.0 - preset);
+        agent.drag_end();
+        assert_eq!(agent.expanded(), preset);
+    }
+}
+
+/// 面板与中栗之间的缝在布局里被真的留出来了。
+///
+/// **全用字面量**（复审 P3-4：早先写成 `rail + GUTTER == window − content`，两边同一组常量，
+/// 把 `RESIZE_GUTTER` 改成 0 照样绿 = 自证）。现在的算式是写死的：
+/// `320（面板）+ 8（缝）+ 852（中栗）= 1180`。
+#[test]
+fn the_resize_gutter_is_part_of_the_budget() {
+    let mut agent = AgentUi::new();
+    agent.expand();
+
+    assert_eq!(agent.rail_width(1180.0), 320.0, "1180 下展开档 = 令牌 320");
+    assert_eq!(agent.content_width(1180.0), 852.0, "中栗 = 1180 − 320 − 8");
+    assert_eq!(320.0 + 8.0 + 852.0, 1180.0, "三段之和必须回到窗口宽");
+    assert_eq!(RESIZE_GUTTER, 8.0, "缝宽就是 8（`Space::X2`）");
+
+    // 折叠档 48 / 拆出档 0：这两档**没有**缝（中栗 = 1180 − 48 / 1180 − 0）
+    let collapsed = layout_for(1180.0, RailState::Collapsed, 320.0);
+    assert_eq!(
+        (collapsed.rail, collapsed.gutter, collapsed.content),
+        (48.0, 0.0, 1132.0)
+    );
+    let detached = layout_for(1180.0, RailState::Detached, 320.0);
+    assert_eq!(
+        (detached.rail, detached.gutter, detached.content),
+        (0.0, 0.0, 1180.0)
+    );
+}
+
+/// 拖拽的三条收尾路径里，**能测的两条**（复审 P3-7）。
+///
+/// 真实鼠标在窗口外松手无法注入（这台机器连 `SetCursorPos` 都失败），所以这里只钉状态机：
+/// ①松手（`DragEnd`）之后指针再动不改宽度；②拖拽中「再按一次」（叠层的 `on_press`）能清态，
+/// 也就是上一条事件丢了的兜底。叠层本身挂了 `on_exit`（指针离窗 = 收在当前值），那条只能真窗口验。
+#[test]
+fn the_drag_recovers_when_a_release_is_missed() {
+    let mut agent = AgentUi::new();
+    agent.expand();
+
+    // ① 正常松手
+    agent.drag_start();
+    agent.drag_to(1180.0, 1180.0 - 360.0);
+    agent.drag_end();
+    assert_eq!(agent.expanded(), 360.0);
+    agent.drag_to(1180.0, 900.0);
+    assert_eq!(agent.expanded(), 360.0, "松手后指针再动不该改宽度");
+
+    // ② 拖拽中「再按一次」= 叠层的 on_press 兜底：清态，后续 DragTo 不再改宽度
+    agent.drag_start();
+    agent.drag_to(1180.0, 1180.0 - 280.0);
+    assert_eq!(agent.expanded(), 280.0);
+    agent.drag_end(); // ← 叠层 on_press → DragEnd
+    assert!(
+        !agent.is_dragging(),
+        "再按一次必须能清态（窗内松手丢失时的兜底）"
+    );
+    agent.drag_to(1180.0, 100.0);
+    assert_eq!(agent.expanded(), 280.0);
+    assert!(drag_overlay(&agent).is_none(), "清态后叠层必须消失");
+}
+
+/// 折叠条与拖拽缝都有可读文字（复审 P3-5：两条 key 以前在视图里一次没用）。
+///
+/// 抓得住：谁把 `AgentResize` / `AgentWidthLabel` 从视图里删掉（那样它们又变回空头支票）。
+/// 抓不住：tooltip 真弹出来长什么样（那要 hover 出图）。
+#[test]
+fn the_gutter_and_strip_are_labelled() {
+    let hosts = include_str!("../mod.rs");
+    let strip = include_str!("../strip.rs");
+    for key in ["Key::AgentResize", "Key::AgentWidthLabel"] {
+        assert!(hosts.contains(key), "视图里没用上 {key}");
+    }
+    // M119：折叠条整段搬去了 `strip.rs`（`mod.rs` 顶到 400 行）
+    assert!(strip.contains("Key::AgentStripLabel"), "折叠条上没画标签");
+}
diff --git a/crates/app-iced/src/pages/appearance/alpha.rs b/crates/app-iced/src/pages/appearance/alpha.rs
new file mode 100644
index 0000000..1e5dec3
--- /dev/null
+++ b/crates/app-iced/src/pages/appearance/alpha.rs
@@ -0,0 +1,235 @@
+//! 两层透明度的**判据层**：整窗 α / 面板 α 的钳位链、CPU 档降级、滑块映射。纯函数、零 iced。
+//!
+//! ## 为什么要分成「两层」
+//!
+//! 用户定案（D34 / D36）：
+//!
+//! - **整窗 α**：整扇窗口（含自绘标题栏、导航轨、所有卡片）作为一个整体乘上 α。Windows 上唯一
+//!   实现是 `SetLayeredWindowAttributes(LWA_ALPHA)`，DWM 常数乘法、成本≈0，所以**CPU 档也允许**；
+//! - **面板 α**：只有面板/卡片这一层半透明，让背景图透出来。CPU 档**强制 1.0**（D36 对 D27 的
+//!   修订：CPU 档被限制的是「多层半透明的合成成本」，不是窗口级常数乘法）。
+//!
+//! ## 真值表（三层 × 三个后端；`x` = 用户设置值）
+//!
+//! | 项 | GPU | CPU | auto | 下限 | 上限 | 钳位还是拒绝 |
+//! |---|---|---|---|---|---|---|
+//! | 整窗 α | `clamp(x, 0.08, 1.0)` | **同左**（D36 修订：CPU 也允许） | 同左 | 0.08 | 1.0 | 钳位；`x ≤ 0` 或非有限值 → **拒绝**（整窗穿透） |
+//! | 面板 α | `clamp(x, 0.4, 1.0)` | **恒 1.0** | `clamp(x, 0.4, 1.0)`（auto 是探测后的择优档） | 0.4 | 1.0 | 钳位 |
+//! | 玻璃 | `x` | **恒 false** | `x` | — | — | 无（布尔） |
+//!
+//! 「auto」按**请求值**判（`Backend::Auto` 是用户没指定、让探测决定）：它不走 CPU 的强制分支，
+//! 因为「强制 1.0」是 CPU 渲染档的降级规则，而探测结果可能是 GPU。真落到 tiny-skia 时
+//! `probe` 会写 `ICED_BACKEND=tiny-skia`，但那时 `Options::backend` 仍是 `Auto`——这条已知
+//! 张力登记在 [`crate::pages::appearance`] 的偏离表里（要收口得让探测结果回灌 `Backend`）。
+//!
+//! ## 两条链为什么都在本文件
+//!
+//! 它们共用一个**滑块映射**与一套钳位纪律，分开写迟早会出现「滑块给 0.0、钳位给 0.08、
+//! 日志又打 0.0」这种三处各说一套的事故。整窗 α 的**执行**（FFI）在
+//! `crate::platform::win32::transparency`，本文件只给「该下发什么」与「下发成什么字节」。
+
+use unlucky_presenter::prefs::WINDOW_ALPHA_MIN;
+
+use crate::platform::effective_window_alpha;
+use crate::platform::win32::transparency::alpha_byte;
+use crate::Backend;
+
+/// 整窗 α 下限的 `f32` 形态（唯一真源仍是 `unlucky_presenter::prefs::WINDOW_ALPHA_MIN`）。
+pub const WINDOW_ALPHA_FLOOR: f32 = WINDOW_ALPHA_MIN as f32;
+
+/// 面板 α 下限（core 的 `PANEL_ALPHA_MIN` = 0.4，经 `unlucky_presenter::prefs` 重导出）。
+pub const PANEL_ALPHA_FLOOR: f32 = unlucky_presenter::prefs::PANEL_ALPHA_MIN as f32;
+
+/// 整窗 α 滑块位置（0..=1）→ 请求值（0.08..=1.0）。
+#[must_use]
+pub fn window_alpha_from_fraction(fraction: f32) -> f32 {
+    let fraction = sanitize_fraction(fraction);
+    WINDOW_ALPHA_FLOOR + fraction * (1.0 - WINDOW_ALPHA_FLOOR)
+}
+
+/// 请求值 → 滑块位置（[`window_alpha_from_fraction`] 的逆；钳位后落在 0..=1）。
+#[must_use]
+pub fn window_fraction(alpha: f32) -> f32 {
+    let alpha = clamp(alpha, WINDOW_ALPHA_FLOOR, 1.0);
+    (alpha - WINDOW_ALPHA_FLOOR) / (1.0 - WINDOW_ALPHA_FLOOR)
+}
+
+/// 面板 α 滑块位置（0..=1）→ 请求值（0.4..=1.0）。
+#[must_use]
+pub fn panel_alpha_from_fraction(fraction: f32) -> f32 {
+    let fraction = sanitize_fraction(fraction);
+    PANEL_ALPHA_FLOOR + fraction * (1.0 - PANEL_ALPHA_FLOOR)
+}
+
+/// 请求值 → 滑块位置。
+#[must_use]
+pub fn panel_fraction(alpha: f32) -> f32 {
+    let alpha = clamp(alpha, PANEL_ALPHA_FLOOR, 1.0);
+    (alpha - PANEL_ALPHA_FLOOR) / (1.0 - PANEL_ALPHA_FLOOR)
+}
+
+/// 该后端是否**强制**面板不透明（D36：CPU 档面板 α / 玻璃 / 模糊一律 1.0）。
+#[must_use]
+pub fn panel_is_forced_opaque(backend: Backend) -> bool {
+    matches!(backend, Backend::Cpu)
+}
+
+/// 面板 α 的生效值：CPU 档恒 1.0，其余钳到 `0.4..=1.0`。
+#[must_use]
+pub fn effective_panel_alpha(backend: Backend, requested: f32) -> f32 {
+    if panel_is_forced_opaque(backend) {
+        return 1.0;
+    }
+    clamp(requested, PANEL_ALPHA_FLOOR, 1.0)
+}
+
+/// 玻璃拟态卡片的生效值：CPU 档恒关（它要的是多层半透明 + 模糊底，那是 D27 的动机）。
+#[must_use]
+pub fn effective_glass(backend: Backend, requested: bool) -> bool {
+    requested && !panel_is_forced_opaque(backend)
+}
+
+/// 整窗 α 最终**下发到 Win32 的字节**（`None` = 不该下发：`α ≥ 1` 或整窗穿透被拒绝）。
+///
+/// 这条链是「配置值 → 判据 → 量化字节」的唯一定义点：
+/// `effective_window_alpha`（钳位/拒绝）→ [`alpha_byte`]（**向上取整**，永不低于下限）。
+#[must_use]
+pub fn window_alpha_byte(backend: Backend, requested: f32) -> Option<u8> {
+    effective_window_alpha(backend, f64::from(requested))
+        .filter(|alpha| *alpha < 1.0)
+        .map(alpha_byte)
+}
+
+fn sanitize_fraction(fraction: f32) -> f32 {
+    clamp(fraction, 0.0, 1.0)
+}
+
+fn clamp(value: f32, min: f32, max: f32) -> f32 {
+    if value.is_nan() {
+        min
+    } else {
+        value.clamp(min, max)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{
+        effective_glass, effective_panel_alpha, panel_alpha_from_fraction, panel_fraction,
+        panel_is_forced_opaque, window_alpha_byte, window_alpha_from_fraction, window_fraction,
+        PANEL_ALPHA_FLOOR, WINDOW_ALPHA_FLOOR,
+    };
+    use crate::Backend;
+
+    const BACKENDS: [Backend; 3] = [Backend::Gpu, Backend::Cpu, Backend::Auto];
+
+    #[test]
+    fn floor_values_are_the_ones_the_user_decided() {
+        // 抓得住：有人把下限改回 0（= 整窗穿透）或把面板下限降到「前景压不住背景图」。
+        // 两个下限都来自 `unlucky_presenter::prefs` 的重导出（M93 r2 起不再有本地字面量），
+        // 所以这条同时钉住「presenter 的重导出没被改坏」。
+        assert_eq!(WINDOW_ALPHA_FLOOR, 0.08);
+        assert_eq!(PANEL_ALPHA_FLOOR, 0.4);
+    }
+
+    /// 任务要求的**钳位链**：配置写 0.8 → 判据放行 0.8 → 下发字节 205。
+    ///
+    /// 抓得住：①`effective_window_alpha` 把 0.8 原样放行（CPU 档也放行，D36 修订）；
+    /// ②**向上取整**这条纪律（`f32` 的 0.8 扩到 `f64` 是 0.8000000119…，×255 = 204.000003，
+    /// ceil = **205**；若谁改成 `round` 就会变 204 并在这里红——那正是「实际下发可能低于下限」
+    /// 的同一个坑）；③`α ≥ 1` 时**不下发**（`None`，而不是 255）。
+    /// 抓不住：这 205 个字节真的被 Win32 收下（FFI 成败由 `transparency` 的单测与本机日志举证）。
+    #[test]
+    fn the_clamp_chain_reports_the_byte_that_would_be_sent() {
+        for backend in BACKENDS {
+            assert_eq!(
+                window_alpha_byte(backend, 0.8),
+                Some(205),
+                "{backend:?}：0.8 → 205（f32→f64 略大于 0.8，ceil 上去）"
+            );
+            assert_eq!(
+                window_alpha_byte(backend, 0.5),
+                Some(128),
+                "{backend:?}：0.5×255=127.5 → 128"
+            );
+            assert_eq!(
+                window_alpha_byte(backend, 1.0),
+                None,
+                "{backend:?}：不透明不下发"
+            );
+            assert_eq!(
+                window_alpha_byte(backend, 0.001),
+                Some(21),
+                "{backend:?}：低于下限先夹到 0.08，再向上取整 21（0.0824 ≥ 0.08）"
+            );
+            assert_eq!(
+                window_alpha_byte(backend, -1.0),
+                None,
+                "{backend:?}：整窗穿透被拒绝，不给字节"
+            );
+            assert_eq!(window_alpha_byte(backend, f32::NAN), None);
+        }
+    }
+
+    /// D36 的核心分界：**CPU 档允许整窗 α，强制面板 1.0**。
+    ///
+    /// 抓得住：谁把这条写反（CPU 档整窗 α 也强制 1.0，或 CPU 档面板 α 跟着用户值走）。
+    /// 抓不住：真实 CPU 档下窗口是否真的半透明（观感未验，见报告「没验的部分」）。
+    #[test]
+    fn cpu_tier_allows_the_window_alpha_but_forces_the_panel_opaque() {
+        assert!(
+            window_alpha_byte(Backend::Cpu, 0.5).is_some(),
+            "CPU 档允许整窗 α"
+        );
+        assert!(panel_is_forced_opaque(Backend::Cpu));
+        assert_eq!(
+            effective_panel_alpha(Backend::Cpu, 0.5),
+            1.0,
+            "CPU 档面板强制 1.0"
+        );
+        assert!(!effective_glass(Backend::Cpu, true), "CPU 档玻璃强制关");
+        // 另外两档不做这个降级（否则「强制」就失去了意义）。
+        for backend in [Backend::Gpu, Backend::Auto] {
+            assert!(!panel_is_forced_opaque(backend), "{backend:?} 不强制");
+            assert_eq!(effective_panel_alpha(backend, 0.5), 0.5);
+            assert!(effective_glass(backend, true));
+        }
+    }
+
+    #[test]
+    fn panel_alpha_is_clamped_into_range() {
+        for backend in [Backend::Gpu, Backend::Auto] {
+            assert_eq!(effective_panel_alpha(backend, 0.0), PANEL_ALPHA_FLOOR);
+            assert_eq!(effective_panel_alpha(backend, 0.2), PANEL_ALPHA_FLOOR);
+            assert_eq!(effective_panel_alpha(backend, 3.0), 1.0);
+            assert_eq!(effective_panel_alpha(backend, f32::NAN), PANEL_ALPHA_FLOOR);
+        }
+    }
+
+    #[test]
+    fn slider_fractions_round_trip_without_leaving_the_range() {
+        for fraction in [0.0, 0.25, 0.5, 0.75, 1.0] {
+            let alpha = window_alpha_from_fraction(fraction);
+            assert!(
+                (WINDOW_ALPHA_FLOOR..=1.0).contains(&alpha),
+                "{fraction} → {alpha}"
+            );
+            assert!((window_fraction(alpha) - fraction).abs() < 1e-6);
+        }
+        // 越界输入（滑块自己不会给，但别让下游吃 NaN）
+        assert_eq!(window_alpha_from_fraction(-1.0), WINDOW_ALPHA_FLOOR);
+        assert_eq!(window_alpha_from_fraction(9.0), 1.0);
+        assert_eq!(window_alpha_from_fraction(f32::NAN), WINDOW_ALPHA_FLOOR);
+
+        for fraction in [0.0, 0.5, 1.0] {
+            let alpha = panel_alpha_from_fraction(fraction);
+            assert!((PANEL_ALPHA_FLOOR..=1.0).contains(&alpha));
+            assert!((panel_fraction(alpha) - fraction).abs() < 1e-6);
+        }
+        // 0.4 与 1.0 是滑块两端：端点必须精确（否则「拖到头还不是 1.0」）
+        assert_eq!(panel_alpha_from_fraction(1.0), 1.0);
+        assert_eq!(panel_fraction(1.0), 1.0);
+        assert_eq!(window_alpha_from_fraction(1.0), 1.0);
+        assert_eq!(window_fraction(WINDOW_ALPHA_FLOOR), 0.0);
+    }
+}
diff --git a/crates/app-iced/src/pages/appearance/background.rs b/crates/app-iced/src/pages/appearance/background.rs
new file mode 100644
index 0000000..d706029
--- /dev/null
+++ b/crates/app-iced/src/pages/appearance/background.rs
@@ -0,0 +1,294 @@
+//! 背景图：**读盘解码（png / jpeg / bmp）→ 三种填充 → 暗化系数 → 可读诊断**。
+//!
+//! ## 真图（M93 r2 起）
+//!
+//! 渲染走 iced 的 `image`（`crates/app-iced/Cargo.toml` 的 `image-without-codecs`）：`Cover` /
+//! `Contain` 交给 `ContentFit`，`Tile` 用本模块的 [`tiles`] 算网格后由 `picture` 真铺图块。
+//! 本模块只负责「解码一次（取色 + 诊断 + 尺寸）」与「网格/暗化的纯数学」。
+//!
+//! | 档 | 渲染 | 露底色 |
+//! |---|---|---|
+//! | `cover` | `ContentFit::Cover`（铺满、裁掉溢出） | 否 |
+//! | `contain` | `ContentFit::Contain`（完整显示、等比） | **是**（上下或左右） |
+//! | `tile` | 原图尺寸平铺（[`tiles`] 给行列数，上限 [`MAX_TILES`]） | 否（图比视口大时=裁切） |
+//!
+//! ## 解码只在这里（一次）
+//!
+//! 一张图会被两处用到：①渲染器（`image::Handle::from_path`，由 iced 自己解码；r2 实测
+//! `from_bytes` 的异步纹理分配赶不上截图第 3 帧，画面会是空的）；②取色（`unlucky_design` 要 RGBA
+//! 像素，本模块把解码结果缩到 [`MAX_EDGE`] 内交给它）。本模块的解码只为「取色 + 诊断 + 尺寸」。
+//!
+//! ## 暗化（`appearance.bg_dim`）
+//!
+//! 语义是「让背景往面板底色退」，即把版面底色（`Role::Surface`）以 α = `dim` 叠在图上——
+//! 与 `rgb + (toward − rgb) × dim` **在数学上等价**（图不透明时），所以这里只给一个钳位函数
+//! [`dim_alpha`]，真正的合成交给渲染器（CPU/GPU 两档都支持普通 alpha 混合）。
+//! 为什么向底色退而不是「叠黑」：浅色主题下叠黑会把亮图压成暗块，深色正文反而更读不清
+//! （偏离登记在 [`super`] 的偏离表 #7）。
+
+use unlucky_presenter::prefs::BgFill;
+
+/// 暗化上限（core 的 `BG_DIM_MAX` = 0.95，经 `unlucky_presenter::prefs` 重导出；这里只给 f32 形态）。
+pub const BG_DIM_MAX: f32 = unlucky_presenter::prefs::BG_DIM_MAX as f32;
+
+/// 解码后保留给取色的最大边长：取色只需要色彩分布，4K 图缩到 256 边后内存从 33MB 掉到 147KB。
+pub const MAX_EDGE: u32 = 256;
+
+/// 解码**之前**允许的原始边长上限。
+///
+/// 复审 r1 P2-4：原来写 16_384，等于允许一张 16384×16384 的 PNG 被**整幅解成 RGBA**
+/// （≈1.07 GB）再缩到 256——那是解压炸弹。现在按「真实会遇到的壁纸尺寸」定：8K（7680×4320）
+/// 留一倍余量 ⇒ **8192**。再大的图直接 [`LoadError::TooLarge`] + 可读提示（不静默）。
+pub const MAX_SOURCE_EDGE: u32 = 8_192;
+
+/// 解码时允许的最大内存占用（`image::Limits::max_alloc`）。
+///
+/// 8192×8192 的 RGBA 是 256 MB；给到 320 MB 足够正常图，同时把「边长合法但通道数/位深
+/// 变态」的图挡在分配之前（第二道闸，第一道是 [`MAX_SOURCE_EDGE`]）。
+pub const MAX_DECODE_BYTES: u64 = 320 * 1024 * 1024;
+
+/// 平铺档「小图」的判据（dp）：短边低于它就一定会被放大铺，值得给一句提示。
+pub const SMALL_TILE_EDGE: f32 = 200.0;
+
+/// 平铺档一次最多铺多少个图块（列 × 行）。超了**放大图块**而不是少铺——见 [`tiles`] 的不变量。
+pub const MAX_TILES: u32 = 64;
+
+/// 图块放大步长（每次乘这个数，直到块数落进预算）。
+pub const TILE_SCALE_STEP: f32 = 1.15;
+
+/// 图块缩放上限（**只是安全阀**，正常情况下远达不到）。
+///
+/// 取 1024 而不是 64：`cols·rows ≤ MAX_TILES` 与「覆盖 ≥ 视口」在**极小图**上要求很大的缩放
+/// （1×1 的图在 1180×760 上要 ~118 倍才能用 64 块盖满）。取小了就等于两者不可兼得——那一侧
+/// 会退化成「留缝」，正是 r1 的 P2-1。真实图片不会走到这个上限。
+pub const MAX_TILE_SCALE: f32 = 1024.0;
+
+/// 解码失败的原因（人话在 [`LoadError::describe`]）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum LoadError {
+    /// 读文件失败：不存在 / 没权限 / 被占用。
+    Io(String),
+    /// 解码失败：格式不认识（webp/tiff 等没开编码器）/ 文件截断 / 不是图片。
+    Undecodable(String),
+    /// 图片头里的尺寸超限。
+    TooLarge {
+        /// 宽。
+        width: u32,
+        /// 高。
+        height: u32,
+    },
+}
+
+impl LoadError {
+    /// 可读诊断（设置页提示行与日志共用同一句）。
+    #[must_use]
+    pub fn describe(&self) -> String {
+        match self {
+            Self::Io(reason) => format!("Background image could not be read: {reason}"),
+            Self::Undecodable(reason) => format!(
+                "Background image could not be decoded ({reason}; this build decodes PNG, JPEG and BMP)"
+            ),
+            Self::TooLarge { width, height } => format!(
+                "Background image is too large to decode: {width}×{height} (limit {MAX_SOURCE_EDGE} px per edge)"
+            ),
+        }
+    }
+}
+
+/// 一张解码好的背景图。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Image {
+    /// **原图**尺寸（像素）：填充几何按它算（`tile` = 原始尺寸平铺）。
+    pub source: (u32, u32),
+    /// 缩略图宽（≤ [`MAX_EDGE`]）。
+    pub width: u32,
+    /// 缩略图高（≤ [`MAX_EDGE`]）。
+    pub height: u32,
+    /// 缩略图 RGBA8（取色用；`width × height × 4`）。
+    pub rgba: Vec<u8>,
+}
+
+impl Image {
+    /// 从已解码的数据构造（测试也走这里，避免测试依赖磁盘）。
+    #[must_use]
+    pub fn from_rgba(source: (u32, u32), width: u32, height: u32, rgba: Vec<u8>) -> Self {
+        Self {
+            source,
+            width,
+            height,
+            rgba,
+        }
+    }
+}
+
+/// 读盘 + 解码 + 缩到 [`MAX_EDGE`] 内。
+///
+/// # Errors
+/// 见 [`LoadError`]：读不到 / 解不开 / 头部尺寸超限。**不 return 默认色**——回落的决定在
+/// [`super::palette`]（它会往 `Provenance` 里留原因），这一层只管如实报告失败。
+pub fn load(path: &str) -> Result<Image, LoadError> {
+    let trimmed = path.trim();
+    if trimmed.is_empty() {
+        return Err(LoadError::Io("no path configured".to_owned()));
+    }
+    let bytes = std::fs::read(trimmed).map_err(|error| LoadError::Io(error.to_string()))?;
+
+    // 第一趟只读图头：先按尺寸拒掉压缩炸弹，再真解码。
+    let (source_w, source_h) = header_size(&bytes)?;
+    if source_w > MAX_SOURCE_EDGE || source_h > MAX_SOURCE_EDGE {
+        return Err(LoadError::TooLarge {
+            width: source_w,
+            height: source_h,
+        });
+    }
+
+    // 第二道闸（复审 r1 P2-4）：把解码器也关进同样的上限里，别只靠自己先读图头。
+    let mut reader = image::ImageReader::new(std::io::Cursor::new(&bytes))
+        .with_guessed_format()
+        .map_err(|error| LoadError::Undecodable(error.to_string()))?;
+    let mut limits = image::Limits::default();
+    limits.max_image_width = Some(MAX_SOURCE_EDGE);
+    limits.max_image_height = Some(MAX_SOURCE_EDGE);
+    limits.max_alloc = Some(MAX_DECODE_BYTES);
+    reader.limits(limits);
+    let decoded = reader
+        .decode()
+        .map_err(|error| LoadError::Undecodable(error.to_string()))?;
+    let (width, height) = (decoded.width().max(1), decoded.height().max(1));
+    let scale = (f64::from(MAX_EDGE) / f64::from(width.max(height))).min(1.0);
+    let target_w = ((f64::from(width) * scale).round() as u32).max(1);
+    let target_h = ((f64::from(height) * scale).round() as u32).max(1);
+    let thumb = image::imageops::resize(
+        &decoded,
+        target_w,
+        target_h,
+        image::imageops::FilterType::Triangle,
+    );
+
+    Ok(Image {
+        source: (source_w, source_h),
+        width: target_w,
+        height: target_h,
+        rgba: thumb.into_raw(),
+    })
+}
+
+/// 原图尺寸（只读图头，不解像素）。
+fn header_size(bytes: &[u8]) -> Result<(u32, u32), LoadError> {
+    let reader = image::ImageReader::new(std::io::Cursor::new(bytes))
+        .with_guessed_format()
+        .map_err(|error| LoadError::Undecodable(error.to_string()))?;
+    if reader.format().is_none() {
+        return Err(LoadError::Undecodable(
+            "unknown image format (magic bytes not recognised)".to_owned(),
+        ));
+    }
+    reader
+        .into_dimensions()
+        .map_err(|error| LoadError::Undecodable(error.to_string()))
+}
+
+/// 平铺档的**诊断**（复审 r1 P2-1）：小图会被放大图块，必须说出来而不是静默。
+///
+/// 判据只看图片本身（短边 < [`SMALL_TILE_EDGE`]）——视口尺寸在渲染层才知道，而这里要的是
+/// 「这张图小到要放大」这个与视口无关的事实。`scale` 条数上限由 [`tiles`] 保证覆盖 ≥ 视口。
+#[must_use]
+pub fn small_tile_note(image: &Image, fill: BgFill) -> Option<String> {
+    if !matches!(fill, BgFill::Tile) {
+        return None;
+    }
+    let (width, height) = (image.source.0 as f32, image.source.1 as f32);
+    if width.min(height) >= SMALL_TILE_EDGE {
+        return None;
+    }
+    Some(format!(
+        "Small image ({}×{}): tiles are scaled up so the window stays covered (max {MAX_TILES} tiles, no gaps).",
+        image.source.0, image.source.1
+    ))
+}
+
+/// 暗化系数（叠在图上那层底色的 α）：`0` = 不暗化，上限 [`BG_DIM_MAX`]。
+#[must_use]
+pub fn dim_alpha(dim: f32) -> f32 {
+    if dim.is_nan() {
+        0.0
+    } else {
+        dim.clamp(0.0, BG_DIM_MAX)
+    }
+}
+
+/// 平铺档的网格（列 × 行 × 图块缩放）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Tiles {
+    /// 列数。
+    pub cols: u32,
+    /// 行数。
+    pub rows: u32,
+    /// 单块图相对原尺寸的缩放（`1.0` = 原尺寸；超预算时**只放大图块**，不减少覆盖）。
+    pub scale: f32,
+}
+
+impl Tiles {
+    /// 总块数。
+    #[must_use]
+    pub fn count(self) -> u32 {
+        self.cols * self.rows
+    }
+
+    /// 一块图的实际边长（dp）：`源尺寸 × scale`。
+    #[must_use]
+    pub fn tile_size(self, source: (u32, u32)) -> (f32, f32) {
+        (
+            source.0.max(1) as f32 * self.scale,
+            source.1.max(1) as f32 * self.scale,
+        )
+    }
+
+    /// 铺满后覆盖的宽高（dp）：**恒 ≥ 视口**（[`tiles`] 的硬不变量，单测钉住）。
+    #[must_use]
+    pub fn covered(self, source: (u32, u32)) -> (f32, f32) {
+        let (w, h) = self.tile_size(source);
+        (self.cols as f32 * w, self.rows as f32 * h)
+    }
+}
+
+/// 平铺档的网格（原图 1 像素 = 1 dp）。
+///
+/// **硬不变量：`covered >= viewport`**——任何情况都不许留缝（复审 r1 P2-1 的返工点）。
+///
+/// r1 的写法是「超预算就减列/减行」，于是 120×120 的图需要 10×7=70 块 > [`MAX_TILES`]，
+/// 列数被砍到 9 ⇒ 覆盖宽 1080 < 1180，右缘 100px 裸白。现在的做法是**放大图块步长**：
+/// `scale` 从 1.0 起按 [`TILE_SCALE_STEP`] 逐级变大，直到 `ceil(视口/图块) 的乘积 ≤ 预算`。
+/// 图块按同一比例放大 ⇒ 图不变形；`ceil` 保证每行/每列都盖过视口边界（多出来的部分由渲染器裁掉）。
+///
+/// 图比视口大时是 `1×1, scale=1.0`（= 以原尺寸裁切），与小图平铺是同一套算式。
+#[must_use]
+pub fn tiles(source: (u32, u32), viewport: (f32, f32)) -> Tiles {
+    let mut tiles = Tiles {
+        cols: 1,
+        rows: 1,
+        scale: 1.0,
+    };
+
+    loop {
+        let (width, height) = tiles.tile_size(source);
+        tiles.cols = ceil_div(viewport.0.max(1.0), width);
+        tiles.rows = ceil_div(viewport.1.max(1.0), height);
+        if tiles.count() <= MAX_TILES || tiles.scale >= MAX_TILE_SCALE {
+            return tiles;
+        }
+        tiles.scale = (tiles.scale * TILE_SCALE_STEP).min(MAX_TILE_SCALE);
+    }
+}
+
+fn ceil_div(value: f32, step: f32) -> u32 {
+    let count = (value / step).ceil();
+    if count.is_finite() && count >= 1.0 {
+        count as u32
+    } else {
+        1
+    }
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/app-iced/src/pages/appearance/background/tests.rs b/crates/app-iced/src/pages/appearance/background/tests.rs
new file mode 100644
index 0000000..4e69b88
--- /dev/null
+++ b/crates/app-iced/src/pages/appearance/background/tests.rs
@@ -0,0 +1,200 @@
+//! `background` 的单测：解码（png + jpeg）、失败分类、暗化钳位、平铺网格。
+//!
+//! 每条测试的「抓得住 / 抓不住」写在注释里——这是本 mission 的验收纪律：能断言的不许只靠肉眼。
+
+use super::{dim_alpha, load, small_tile_note, tiles, LoadError, BG_DIM_MAX, MAX_TILES};
+use std::path::{Path, PathBuf};
+use unlucky_presenter::prefs::BgFill;
+
+fn temp_file(label: &str, name: &str) -> PathBuf {
+    let dir =
+        std::env::temp_dir().join(format!("ull-bg-{label}-{}-{}", std::process::id(), line!()));
+    std::fs::create_dir_all(&dir).expect("临时目录");
+    dir.join(name)
+}
+
+fn cleanup(path: &Path) {
+    if let Some(dir) = path.parent() {
+        std::fs::remove_dir_all(dir).ok();
+    }
+}
+
+#[test]
+fn a_real_png_decodes_with_its_original_size_and_raw_bytes() {
+    // 抓得住：真磁盘 PNG 能读、原图尺寸按图头、缩略图不超预算、原始字节留着给渲染器。
+    // 抓不住：渲染器用这些字节画出来的颜色（那要看截图）。
+    let path = temp_file("png", "bg.png");
+    let source: image::RgbImage = image::RgbImage::from_pixel(300, 20, image::Rgb([12, 200, 90]));
+    source.save(&path).expect("写 png");
+
+    let image = load(path.to_str().unwrap()).expect("真 PNG 必须能读");
+    assert_eq!(image.source, (300, 20));
+    assert!(
+        image.width <= super::MAX_EDGE && image.height <= super::MAX_EDGE,
+        "缩略图 {}×{} 超预算",
+        image.width,
+        image.height
+    );
+    assert_eq!(image.rgba.len(), (image.width * image.height * 4) as usize);
+    assert_eq!(image.rgba.len(), (image.width * image.height * 4) as usize);
+    cleanup(&path);
+}
+
+/// M93 r2 的硬要求：`.jpg` 必须能加载（用户挑的背景图/壁纸多半是 jpeg）。
+///
+/// 抓得住：`image` 的 jpeg 编码器真的开了（没开时 `load` 会返回 `Undecodable`）。
+/// 抓不住：渲染器那边（`iced/image`）解码 jpeg 的能力——那条由截图矩阵里那张 jpg 出图举证。
+#[test]
+fn a_real_jpeg_decodes_too() {
+    let path = temp_file("jpeg", "bg.jpg");
+    let source =
+        image::RgbImage::from_fn(64, 32, |x, y| image::Rgb([x as u8 * 4, y as u8 * 8, 90]));
+    source
+        .save_with_format(&path, image::ImageFormat::Jpeg)
+        .expect("写 jpeg");
+
+    let image = load(path.to_str().unwrap()).expect("jpeg 必须能读（M93 r2）");
+    assert_eq!(image.source, (64, 32));
+    assert_eq!(
+        image.rgba.len(),
+        (image.width * image.height * 4) as usize,
+        "像素解出来了"
+    );
+    cleanup(&path);
+}
+
+#[test]
+fn a_missing_or_broken_file_reports_a_readable_reason() {
+    // 抓得住：①路径不存在 → Io；②文件存在但不是图片 → Undecodable；③空路径 → Io。
+    // 都必须是 Err（不许静默回默认色），且 describe() 是人话。
+    // 抓不住：webp/tiff 这类没开编码器的格式具体报什么字符串（只钉分类，不钉解码库原文）。
+    let missing = temp_file("missing", "bg.png");
+    let error = load(missing.to_str().unwrap()).expect_err("不存在的路径必须报错");
+    assert!(matches!(error, LoadError::Io(_)), "实际 {error:?}");
+    assert!(error
+        .describe()
+        .starts_with("Background image could not be read"));
+
+    let broken = temp_file("broken", "bg.png");
+    std::fs::write(&broken, b"this is not an image").expect("写坏文件");
+    let error = load(broken.to_str().unwrap()).expect_err("非图片必须报错");
+    assert!(matches!(error, LoadError::Undecodable(_)), "实际 {error:?}");
+    cleanup(&broken);
+
+    let empty = load("   ").expect_err("空路径必须报错");
+    assert!(matches!(empty, LoadError::Io(_)));
+}
+
+#[test]
+fn dim_is_clamped_to_the_supported_range() {
+    // 抓得住：暗化系数夹在 0..=0.95（下限允许 0 = 不暗化，上限防「背景看不见」），NaN 取 0。
+    // 抓不住：0.35 这个默认值在真实壁纸上的观感（视觉判断）。
+    assert_eq!(dim_alpha(0.0), 0.0);
+    assert_eq!(dim_alpha(0.35), 0.35);
+    assert_eq!(dim_alpha(-1.0), 0.0);
+    assert_eq!(dim_alpha(f32::NAN), 0.0);
+    assert_eq!(dim_alpha(9.0), BG_DIM_MAX);
+    assert_eq!(BG_DIM_MAX, 0.95, "与 core 同源（presenter 重导出）");
+}
+
+/// **P2-1 的守门**：任何尺寸/视口组合下，平铺网格铺出来的覆盖宽高都必须 ≥ 视口（不许留缝），
+/// 同时块数不超预算（不留缝的代价只能是「放大图块」，不能是「少铺」）。
+///
+/// 抓得住：谁把 `tiles()` 改回「超预算就减列」——120×120 @ 1180×760 那条会立刻红
+/// （r1 实测右缘裸白 100px）。
+/// 抓不住：渲染器把单块图铺进格子时的实际像素对齐（有没有半像素缝由截图看）。
+#[test]
+fn tile_grid_always_covers_the_viewport_within_budget() {
+    let cases = [
+        ((120, 120), (1180.0, 760.0)),
+        ((300, 200), (1180.0, 760.0)),
+        ((16, 16), (1920.0, 1080.0)),
+        ((8, 8), (3840.0, 2160.0)),
+        ((1600, 900), (1180.0, 760.0)),
+        ((1, 1), (1180.0, 760.0)),
+    ];
+    for (source, viewport) in cases {
+        let grid = tiles(source, viewport);
+        let (covered_w, covered_h) = grid.covered(source);
+        assert!(
+            covered_w >= viewport.0 - 0.01 && covered_h >= viewport.1 - 0.01,
+            "{source:?} @ {viewport:?} 覆盖 {covered_w}×{covered_h} 小于视口（会留缝）：{grid:?}"
+        );
+        assert!(
+            grid.count() <= MAX_TILES,
+            "{source:?} @ {viewport:?} 块数 {} 超预算",
+            grid.count()
+        );
+        assert!(grid.scale >= 1.0, "图块只许放大，不许缩小：{grid:?}");
+    }
+
+    // 图比视口大 ⇒ 1×1 原尺寸裁切（scale 必须还是 1.0，否则等于缩小了原图）。
+    let big = tiles((1600, 900), (1180.0, 760.0));
+    assert_eq!((big.cols, big.rows, big.scale), (1, 1, 1.0));
+
+    // 小图按原尺寸铺够（不放大时）。
+    let small = tiles((300, 200), (1180.0, 760.0));
+    assert_eq!((small.cols, small.rows, small.scale), (4, 4, 1.0));
+}
+
+/// 编译期钉住：填充档解析走 core 的词表（`cover`/`contain`/`tile`）。
+#[test]
+fn fill_keys_are_the_schema_vocabulary() {
+    // 抓得住：有人改了落盘词表却没改这里（截图矩阵的 env 也按这三个词传）。
+    assert_eq!(BgFill::from_key_value("cover"), BgFill::Cover);
+    assert_eq!(BgFill::from_key_value("contain"), BgFill::Contain);
+    assert_eq!(BgFill::from_key_value("tile"), BgFill::Tile);
+}
+
+/// **复审 r1 P2-4**：解压炸弹的第二道闸——图头就超上限时要走 `TooLarge`，而且这条分支
+/// 以前**没有任何测试**（三态诊断里唯一没被钉住的一态）。
+///
+/// 抓得住：`header_size` 的尺寸判据（构造一张 9000×4 的真 PNG，只花 ~100 KB 就能造出来）。
+/// 抓不住：内存分配真的被 `image::Limits` 挡住（那要真喂一张巨图跑到 OOM，本机不做）。
+#[test]
+fn an_over_sized_image_reports_too_large_instead_of_trying_to_decode() {
+    let path = temp_file("huge", "huge.png");
+    let source = image::RgbImage::new(9_000, 4);
+    source.save(&path).expect("写大尺寸图");
+
+    let error = load(path.to_str().unwrap()).expect_err("超过 MAX_SOURCE_EDGE 必须报错");
+    assert!(
+        matches!(
+            error,
+            LoadError::TooLarge {
+                width: 9_000,
+                height: 4
+            }
+        ),
+        "实际 {error:?}"
+    );
+    assert!(
+        error.describe().contains("too large"),
+        "提示要人话：{}",
+        error.describe()
+    );
+    // 上限不许再放宽（r1 的 16384 等于允许 1 GB 的中间缓冲）：常量级约束放在测试里钉。
+    const _: () = assert!(super::MAX_SOURCE_EDGE <= 8_192);
+    cleanup(&path);
+}
+
+/// **复审 r1 P2-1 的诊断面**：小图平铺会被放大（图块步长放大，见 `tiles`），必须说出来。
+///
+/// 抓得住：短边 < `SMALL_TILE_EDGE` 的图在 tile 档下一定有提示；cover/contain 档不提示；
+/// 大图不提示。
+/// 抓不住：提示文案在真实界面上的位置（由截图看）。
+#[test]
+fn small_images_get_a_tile_diagnostic_instead_of_silently_degrading() {
+    let small = super::Image::from_rgba((32, 32), 4, 4, vec![0; 64]);
+    let note = small_tile_note(&small, BgFill::Tile).expect("小图 tile 必须有提示");
+    assert!(note.contains("32×32"), "{note}");
+    assert!(note.contains("scaled up"), "{note}");
+
+    // 非 tile 档不提示（cover/contain 会等比铺满，不存在「小图被放大铺」这件事）。
+    assert!(small_tile_note(&small, BgFill::Cover).is_none());
+    assert!(small_tile_note(&small, BgFill::Contain).is_none());
+
+    // 大图不提示。
+    let big = super::Image::from_rgba((1200, 800), 4, 4, vec![0; 64]);
+    assert!(small_tile_note(&big, BgFill::Tile).is_none());
+}
diff --git a/crates/app-iced/src/pages/appearance/mod.rs b/crates/app-iced/src/pages/appearance/mod.rs
new file mode 100644
index 0000000..1cbda1c
--- /dev/null
+++ b/crates/app-iced/src/pages/appearance/mod.rs
@@ -0,0 +1,219 @@
+//! # 外观接线（M93 / APPEARWIRE）：**键 → 像素**
+//!
+//! 本模块把 `appearance.*` 那批键接到真正的窗口与真正的像素上，并把「哪里是判据、哪里是观感」
+//! 分开写清楚。底座（M91）已经给了键、钳位判据与唯一的不安全落点；这里补的是**调用方**。
+//!
+//! ## 两层透明度（D34 / D36）
+//!
+//! | 层 | 作用范围 | 实现 | CPU 档 | 下限 |
+//! |---|---|---|---|---|
+//! | 整窗 α | 整扇窗口（标题栏 + 导航轨 + 内容 + 卡片） | `SetLayeredWindowAttributes(LWA_ALPHA)`，DWM 常数乘法 | **允许** | 0.08（α=0 = 整窗穿透，拒绝） |
+//! | 面板 α | 只有面板/卡片表面这一层（背景图能透出来） | 容器色的 alpha（[`section`] / `shell`） | **强制 1.0** | 0.4 |
+//!
+//! 真值表在 [`alpha`] 的模块文档里（三层 × 三个后端，含「钳位还是拒绝」）。
+//!
+//! ## 模块分工
+//!
+//! | 文件 | 是什么 | 有没有 IO |
+//! |---|---|---|
+//! | [`alpha`] | 两层 α 的钳位链、CPU 档降级、滑块映射、下发字节 | 无（纯函数） |
+//! | [`background`] | 背景图解码（png/jpeg/bmp）、平铺网格、暗化系数、可读诊断 | 读盘一次（`load`） |
+//! | `palette` | D38 三级优先序的调用侧 + 提示文案 | 无（像素由 `background` 给） |
+//! | `state` | 运行期状态：把上面三件的输入输出连起来 | 只在 `refresh_background` |
+//! | `section` | 设置页「外观」分组（真控件） | 无 |
+//! | `picture` | 背景层 Element：真图直出（Cover/Contain/Tile）+ 暗化叠层 | 无 |
+//!
+//! ## 偏离登记（D30 要求逐条写清）
+//!
+//! | # | 偏离 | 为什么 | 什么时候收口 |
+//! |---|---|---|---|
+//! | 1 | ~~背景图按 36dp 马赛克画~~ → **r2 已销**：iced 的 `image-without-codecs` 打开，真图直出（`ContentFit` + 平铺网格） | r1 时 `Cargo.toml` 不在 scope；M93 r2 由 tower 扩 scope 解决 | ✅ |
+//! | 2 | ~~面板 α 只覆盖外壳层~~ → **r2 已销**：α 收敛到 `Ui::layer`（唯一施加点），`frame::card` / 页头带 / 外壳 / 外观卡片自动同源 | M93 r2 扩了 `pages/frame.rs` + `theme.rs` 的 scope | ✅ |
+//! | 3 | 桌面壁纸取色（第二级）永远 `Absent` | 壁纸探测（M73）还没落地；优先序本身仍按 design 的三级走，测试里用合成像素证明第二级会被用到 | M73 |
+//! | 4 | 色卡档**不换** `Ui` 的 scheme | `resolve_source` 的色卡档返回 `DEFAULT_CARD`（天蓝卡）的方案，与令牌 baseline 逐色不同；应用它会把全部既有验收图的像素改掉。取色档（①②）才换 | 色卡选择 UI 落地时一并决议 |
+//! | 5 | `Backend::Auto` 不触发 CPU 档降级 | 「强制 1.0」是 CPU 渲染档的规则，而 `Auto` 是「探测前的请求值」；探测结果没有回灌 `Backend` | 让 `probe` 把结果回灌 `Options::backend` |
+//! | 6 | ~~背景图只支持 png~~ → **r2 已销**：`image` 补了 `jpeg`/`bmp`，单测与截图都用 `.jpg` 举证 | 同上 | ✅ |
+//! | 7 | `bg_dim` 是「往**面板底色**退」，不是「叠黑」 | 浅色主题下叠黑会把亮图压成暗块，深色正文反而更读不清；向底色退在两种主题下都单调变好（见 [`background::dim_alpha`]） | 若将来为了「夜间压暗」需要真叠黑，加一档独立键（不要复用这个） |
+//! | 8 | ~~页头文字压在画布上~~ → **r2 已销**：`frame::header_bar` 加了面板底色 | M93 r2 扩了 `pages/frame.rs` 的 scope | ✅ |
+//!
+//! ## 取证
+//!
+//! 每一处改动都打一行 [`state::State::log_line`]：`[appearance] window_alpha=… panel_alpha=…
+//! byte=… corner=…`；圆角另有一条独立管线，行形如
+//! `[corner] <ctx> corner=policy=system source=dwm os=10.0.26100 excluded_reason=none
+//! radius=system pref=2 readback=? read_hr=0x80070057 frame=overlapped layered=on
+//! suppressed_by=window_alpha`（真进程实跑的两条见 `DevDocs/artifacts/m116/README.md`；
+//! `frame=` 恒为 `overlapped`/`other`，**不会是 `popup`**）
+//! （见 `app::update::appearance` 与 `platform::win32::corner::format_line`）。数值是**下发前**的
+//! 字节/属性值（不是观感），因为在 RDP + 虚拟显示适配器上「看上去多透明 / 圆不圆」不可信。
+//! 截图矩阵用 `ULL_APPEARANCE_*` 环境变量灌值（见 [`state`] 的常量）。
+
+use iced::widget::container;
+use iced::{Background, Border, Element, Length, Padding};
+
+use unlucky_design::color::Role;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use crate::pages::frame;
+use crate::pages::Message;
+use crate::theme::Ui;
+
+pub mod alpha;
+pub mod background;
+
+mod palette;
+mod picture;
+mod section;
+mod state;
+
+/// 状态提示的 **tonal notice**（`section.rs` 的 400 行硬顶把它放在模块根）。
+///
+/// `SurfaceContainerHighest` 底 + `ShapeScale::Small` 圆角 + 两侧 `X2` 内边距，文字 `OnSurfaceVariant`。
+/// 用它而不是「换色的正文」：容器才是 M3 表达「当前状态」的形态，也和说明段在**形态**上分开
+/// （不靠色相、不新增令牌）。调用点见 [`section::section`] 的圆角一节。
+fn notice<'a>(ui: &'a Ui, text: &str) -> Element<'a, Message> {
+    let background = ui.color(Role::SurfaceContainerHighest);
+    let tone = ui.color(Role::OnSurfaceVariant);
+    let body = frame::text_role_owned(ui, TypeRole::BodySmall, true, text.to_owned(), tone);
+    let pad = ui.space(Space::X2);
+    let radius = ui.radius_dp(ShapeScale::Small);
+    container(body)
+        .width(Length::Fill)
+        .padding(Padding::from([ui.space(Space::X1), pad]))
+        .style(move |_theme| container::Style {
+            background: Some(Background::Color(background)),
+            border: Border {
+                radius,
+                ..Border::default()
+            },
+            ..container::Style::default()
+        })
+        .into()
+}
+
+pub use picture::layer;
+pub use section::section;
+pub use state::State;
+
+/// 设置页「外观」分组在左列里的下标（0 = General，1 = Appearance …）。
+pub const APPEARANCE_GROUP: usize = 1;
+
+/// 设置页「外观」分组的显示名。
+pub const GROUP_LABEL: &str = "Appearance";
+
+/// 一次外观改动（设置页 → `App`）。
+///
+/// 值都是**用户请求值**（未钳位）：钳位与降级只发生在 [`alpha`]，这样「用户设了 0.5、CPU 档实际
+/// 1.0」这种差别在状态里能看出来，日志也就不会把请求值写成生效值。
+#[derive(Debug, Clone, PartialEq)]
+pub enum Change {
+    /// 整窗透明度（请求值，0.08~1.0）。
+    WindowOpacity(f32),
+    /// 面板透明度（请求值，0.4~1.0）。
+    PanelAlpha(f32),
+    /// 背景图开关。
+    BgEnabled(bool),
+    /// 背景图路径（空串 = 清掉）。
+    BgImage(String),
+    /// 填充档。
+    BgFill(unlucky_presenter::prefs::BgFill),
+    /// 暗化强度（0~0.95）。
+    BgDim(f32),
+    /// 配色来源档。
+    PaletteSource(unlucky_presenter::prefs::PaletteSource),
+    /// 窗口圆角档位（M116：跟随系统 / 直角）。
+    Corner(unlucky_presenter::prefs::WindowCorner),
+    /// 设置页切分组（左列点选）。
+    SelectGroup(usize),
+}
+
+impl Change {
+    /// 这条改动对应哪个 schema 键（写回配置用；`SelectGroup` 不落盘）。
+    #[must_use]
+    pub fn key(&self) -> Option<&'static str> {
+        Some(match self {
+            Self::WindowOpacity(_) => unlucky_presenter::prefs::keys::WINDOW_OPACITY,
+            Self::PanelAlpha(_) => unlucky_presenter::prefs::keys::PANEL_ALPHA,
+            Self::BgEnabled(_) => unlucky_presenter::prefs::keys::BG_IMAGE_ENABLED,
+            Self::BgImage(_) => unlucky_presenter::prefs::keys::BG_IMAGE,
+            Self::BgFill(_) => unlucky_presenter::prefs::keys::BG_FILL,
+            Self::BgDim(_) => unlucky_presenter::prefs::keys::BG_DIM,
+            Self::PaletteSource(_) => unlucky_presenter::prefs::keys::PALETTE_SOURCE,
+            Self::Corner(_) => unlucky_presenter::prefs::keys::WINDOW_CORNER,
+            Self::SelectGroup(_) => return None,
+        })
+    }
+
+    /// 这条改动的落盘字符串形态（与 `schema` 的取值词表逐字一致）。
+    ///
+    /// `None` = 不落盘（分组选择）。数字一律给 `f64` 的十进制字面量（`store.set` 按 schema 类型转）。
+    #[must_use]
+    pub fn value(&self) -> Option<String> {
+        Some(match self {
+            Self::WindowOpacity(alpha) => format!("{alpha}"),
+            Self::PanelAlpha(alpha) => format!("{alpha}"),
+            Self::BgEnabled(enabled) => enabled.to_string(),
+            Self::BgImage(path) => path.clone(),
+            Self::BgFill(fill) => fill.as_str().to_owned(),
+            Self::BgDim(dim) => format!("{dim}"),
+            Self::PaletteSource(source) => source.as_str().to_owned(),
+            Self::Corner(corner) => corner.as_str().to_owned(),
+            Self::SelectGroup(_) => return None,
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{Change, APPEARANCE_GROUP};
+    use unlucky_presenter::prefs::{keys, BgFill, PaletteSource};
+
+    /// 抓得住：每条改动都点名到自己那个 schema 键（写错键 = 静默写到别的配置项上）。
+    /// 抓不住：这些键是否真的在 core 的 schema 白名单里（那由 presenter/core 的测试守）。
+    #[test]
+    fn every_change_names_its_own_schema_key() {
+        assert_eq!(APPEARANCE_GROUP, 1, "左列第 1 项是 Appearance");
+        let cases = [
+            (Change::WindowOpacity(0.8), keys::WINDOW_OPACITY),
+            (Change::PanelAlpha(0.6), keys::PANEL_ALPHA),
+            (Change::BgEnabled(true), keys::BG_IMAGE_ENABLED),
+            (Change::BgImage("D:/x.png".to_owned()), keys::BG_IMAGE),
+            (Change::BgFill(BgFill::Tile), keys::BG_FILL),
+            (Change::BgDim(0.5), keys::BG_DIM),
+            (
+                Change::PaletteSource(PaletteSource::Wallpaper),
+                keys::PALETTE_SOURCE,
+            ),
+            (
+                Change::Corner(unlucky_presenter::prefs::WindowCorner::Square),
+                keys::WINDOW_CORNER,
+            ),
+        ];
+        for (change, key) in cases {
+            assert_eq!(change.key(), Some(key), "{change:?}");
+            assert!(change.value().is_some());
+        }
+        assert_eq!(Change::SelectGroup(2).key(), None, "切分组不落盘");
+        assert_eq!(Change::SelectGroup(2).value(), None);
+    }
+
+    /// 抓得住：落盘字符串必须是 schema 认识的词表（枚举档写错就整条配置读回默认值）。
+    /// 抓不住：数值是否在范围内（钳位在 core 侧，越界写入会被 schema 拒绝）。
+    #[test]
+    fn persisted_values_use_the_schema_vocabulary() {
+        assert_eq!(
+            Change::BgFill(BgFill::Contain).value().as_deref(),
+            Some("contain")
+        );
+        assert_eq!(
+            Change::PaletteSource(PaletteSource::BackgroundImage)
+                .value()
+                .as_deref(),
+            Some("background-image")
+        );
+        assert_eq!(Change::BgEnabled(false).value().as_deref(), Some("false"));
+        assert_eq!(Change::WindowOpacity(0.8).value().as_deref(), Some("0.8"));
+    }
+}
diff --git a/crates/app-iced/src/pages/appearance/palette.rs b/crates/app-iced/src/pages/appearance/palette.rs
new file mode 100644
index 0000000..b611027
--- /dev/null
+++ b/crates/app-iced/src/pages/appearance/palette.rs
@@ -0,0 +1,279 @@
+//! D38 三级配色来源的**调用侧**：用户选的档 → `unlucky_design::palette::resolve_source`。
+//!
+//! ## 档位与优先序
+//!
+//! `appearance.palette_source` 的取值是「**从哪一级起**试」：① `background-image` ② `wallpaper`
+//! ③ `preset`。起点的级别以下的级别**不参与**（在 `Provenance` 里记为 `Absent` = 用户没让它们
+//! 参与），起点以上的每一级只要「有输入但不合格」就自动往下一级落——回落链本身由 design 实现
+//! （`crates/design/src/palette/resolve/`），本文件只做两件事：
+//!
+//! 1. 把「没设」与「设了但坏了」**分开传**（[`Source::Absent`] vs [`Source::Undecodable`]）——
+//!    混成一个 `None` 会让设置页说错话（「没设背景图」 vs 「你那张图读不出来」）；
+//! 2. 把 `Provenance::hint_key()` 翻成一句可读提示（键 → 文案是 UI 层的活，i18n 之后再统一）。
+//!
+//! ## 为什么不在这里做对比度
+//!
+//! WCAG 收敛在 `unlucky_design` 里（`converge` + `check`，任何来源的方案都跑同一套）。本文件
+//! 只负责「选哪一级」，越俎代庖会让两条路径各有一套门禁。测试里仍然断言「任何一级的结果都
+//! `is_clean()`」，那是**验收**，不是实现。
+
+use unlucky_design::color::{Scheme, SchemeFlavor};
+use unlucky_design::palette::{resolve_source, ImageInput, Level, Provenance};
+use unlucky_presenter::prefs::PaletteSource;
+
+use super::background::Image;
+
+/// 某一级的输入（三态：没设 / 设了但坏了 / 解码好了）。
+#[derive(Debug, Clone, Copy)]
+pub enum Source<'a> {
+    /// 用户没设这一级（没开关 / 路径空）。
+    Absent,
+    /// 设了，但读盘或解码失败（原因在调用侧记着，这里只用来说「坏」）。
+    Undecodable,
+    /// 解码好的像素。
+    Pixels(&'a Image),
+}
+
+impl<'a> Source<'a> {
+    /// 翻成 design 的输入形态。
+    #[must_use]
+    pub fn input(self) -> Option<ImageInput<'a>> {
+        match self {
+            Self::Absent => None,
+            Self::Undecodable => Some(ImageInput::Undecodable),
+            Self::Pixels(image) => Some(ImageInput::pixels(&image.rgba, image.width, image.height)),
+        }
+    }
+}
+
+/// 一次解析的结果。
+#[derive(Debug, Clone, PartialEq)]
+pub struct Resolved {
+    /// 最终生效的方案（49 个角色）。
+    pub scheme: Scheme,
+    /// 用哪一级、前几级为什么没用。
+    pub provenance: Provenance,
+}
+
+impl Resolved {
+    /// 生效的层级（日志与设置页展示用）。
+    #[must_use]
+    pub fn level(&self) -> Level {
+        self.provenance.level
+    }
+
+    /// 可读提示（`None` = 一级成功、没什么可解释的）。
+    #[must_use]
+    pub fn note(&self) -> Option<&'static str> {
+        note(&self.provenance)
+    }
+}
+
+/// 按档位解析一套方案。
+///
+/// `preset` 固定传 `None`：本仓库的「用户选中的色卡」还没有 UI（M91 只落了档位），
+/// 所以 design 用它自己的出厂卡（`DEFAULT_CARD` = 天蓝）。色卡选择接上后从 `state` 传进来即可。
+#[must_use]
+pub fn resolve(
+    source: PaletteSource,
+    background: Source<'_>,
+    wallpaper: Source<'_>,
+    flavor: SchemeFlavor,
+) -> Resolved {
+    // 档位 = 起点：起点以下的级别不参与（传 `Source::Absent`）。
+    let background = if source == PaletteSource::BackgroundImage {
+        background
+    } else {
+        Source::Absent
+    };
+    let wallpaper =
+        if source == PaletteSource::BackgroundImage || source == PaletteSource::Wallpaper {
+            wallpaper
+        } else {
+            Source::Absent
+        };
+
+    let (scheme, provenance) = resolve_source(background.input(), wallpaper.input(), None, flavor);
+    Resolved { scheme, provenance }
+}
+
+/// `Provenance::hint_key()` → 一句可读提示（英文基线；i18n mission 之后走词表）。
+///
+/// 键的完整表在 `unlucky_design::palette::resolve::Provenance::hint_key` 的文档里；
+/// 这里只翻「本 mission 真会产生的那几个」，未识别键返回 `None` 而不是编一句话。
+#[must_use]
+pub fn note(provenance: &Provenance) -> Option<&'static str> {
+    Some(match provenance.hint_key()? {
+        "palette.hint.background.undecodable" => {
+            "Background image could not be read; colours fall back."
+        }
+        "palette.hint.background.too-small" => {
+            "Background image is too small to sample; colours fall back."
+        }
+        "palette.hint.background.bad-dimensions" => {
+            "Background image data looks inconsistent; colours fall back."
+        }
+        "palette.hint.background.no-opaque-pixels" => {
+            "Background image is almost fully transparent; colours fall back."
+        }
+        "palette.hint.background.low-chroma" => {
+            "Background image is too monochrome to tint from; colours fall back."
+        }
+        "palette.hint.background.contrast" => {
+            "Background image colours would be unreadable; colours fall back."
+        }
+        "palette.hint.wallpaper.undecodable" => "Desktop wallpaper could not be read.",
+        "palette.hint.wallpaper.low-chroma" => "Desktop wallpaper is too monochrome to tint from.",
+        "palette.hint.wallpaper.too-small" => "Desktop wallpaper is too small to sample.",
+        "palette.hint.wallpaper.bad-dimensions" => "Desktop wallpaper data looks inconsistent.",
+        "palette.hint.wallpaper.no-opaque-pixels" => {
+            "Desktop wallpaper is almost fully transparent."
+        }
+        "palette.hint.wallpaper.contrast" => {
+            "Desktop wallpaper colours would be unreadable; colours fall back."
+        }
+        "palette.hint.preset.contrast" => "The built-in card needed a small contrast correction.",
+        "palette.hint.adjusted" => "A few colours were nudged for readability.",
+        _ => return None,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{note, resolve, Source};
+    use crate::pages::appearance::background::Image;
+    use unlucky_design::color::SchemeFlavor;
+    use unlucky_design::palette::wcag::check;
+    use unlucky_design::palette::{Level, Outcome, Skip};
+    use unlucky_presenter::prefs::PaletteSource;
+
+    /// 高彩度的图（纯红）：取色一定成功。
+    fn vivid() -> Image {
+        let rgba = [0xC0, 0x20, 0x20, 0xFF].repeat(64);
+        Image::from_rgba((8, 8), 8, 8, rgba)
+    }
+
+    /// 极低彩度的图（近灰）：D40 的彩度门槛会拒绝它（`< 8`）。
+    fn grey() -> Image {
+        let rgba = [0x80, 0x80, 0x82, 0xFF].repeat(64);
+        Image::from_rgba((8, 8), 8, 8, rgba)
+    }
+
+    #[test]
+    fn background_tier_wins_when_the_image_is_usable() {
+        // 抓得住：档位 ① 有合格输入时就用它，且不回落、没有提示。
+        let image = vivid();
+        let resolved = resolve(
+            PaletteSource::BackgroundImage,
+            Source::Pixels(&image),
+            Source::Absent,
+            SchemeFlavor::Light,
+        );
+        assert_eq!(resolved.level(), Level::BackgroundImage);
+        assert!(!resolved.provenance.did_fall_back());
+        assert_eq!(resolved.note(), None, "一级成功时不该有提示");
+        assert!(check(&resolved.scheme).is_clean(), "取色结果也必须过 WCAG");
+    }
+
+    #[test]
+    fn a_broken_background_falls_back_and_says_why() {
+        // 抓得住：「设了但坏了」（Undecodable）与「没设」（Absent）在 Provenance 里分得开，
+        // 且提示文案对应的是前者；结果仍然过 WCAG（回落不静默变黑白）。
+        let resolved = resolve(
+            PaletteSource::BackgroundImage,
+            Source::Undecodable,
+            Source::Absent,
+            SchemeFlavor::Dark,
+        );
+        assert_eq!(resolved.level(), Level::Preset, "解码失败 → 落到色卡");
+        assert_eq!(
+            resolved.provenance.background(),
+            Outcome::Failed(Skip::Undecodable)
+        );
+        assert!(resolved.provenance.did_fall_back());
+        assert_eq!(
+            resolved.note(),
+            Some("Background image could not be read; colours fall back.")
+        );
+        assert!(check(&resolved.scheme).is_clean());
+    }
+
+    #[test]
+    fn a_monochrome_background_falls_back_instead_of_turning_grey() {
+        // 抓得住：彩度不足**不是**「压成灰方案」，而是回落到色卡（D40 的纪律），并留下 low-chroma。
+        let image = grey();
+        let resolved = resolve(
+            PaletteSource::BackgroundImage,
+            Source::Pixels(&image),
+            Source::Absent,
+            SchemeFlavor::Light,
+        );
+        assert_eq!(resolved.level(), Level::Preset);
+        match resolved.provenance.background() {
+            Outcome::Failed(skip) => {
+                assert!(matches!(skip, Skip::LowChroma { .. }), "实际 {skip:?}")
+            }
+            other => panic!("灰图必须被判不合格，实际 {other:?}"),
+        }
+        assert!(resolved.note().unwrap().contains("monochrome"));
+    }
+
+    #[test]
+    fn the_three_tiers_are_tried_in_order_and_never_out_of_order() {
+        // 抓得住：① 档位=wallpaper 时背景图**不参与**（即使手里有像素）；② 档位=preset 时前两级
+        // 都不参与。这两条是「优先序」的唯一可断言形态（顺序本身在 design 里）。
+        let background = vivid();
+        let wallpaper = vivid();
+
+        let wallpaper_tier = resolve(
+            PaletteSource::Wallpaper,
+            Source::Pixels(&background),
+            Source::Pixels(&wallpaper),
+            SchemeFlavor::Light,
+        );
+        assert_eq!(wallpaper_tier.level(), Level::Wallpaper);
+        assert_eq!(
+            wallpaper_tier.provenance.background(),
+            Outcome::Absent,
+            "档位是壁纸 → 背景图那一级没参与"
+        );
+
+        let preset_tier = resolve(
+            PaletteSource::Preset,
+            Source::Pixels(&background),
+            Source::Pixels(&wallpaper),
+            SchemeFlavor::Light,
+        );
+        assert_eq!(preset_tier.level(), Level::Preset);
+        assert_eq!(preset_tier.provenance.background(), Outcome::Absent);
+        assert_eq!(preset_tier.provenance.wallpaper(), Outcome::Absent);
+        assert!(check(&preset_tier.scheme).is_clean());
+
+        // 而档位=background-image 且壁纸也在时：一级成功 ⇒ 壁纸是 NotReached（不是 Absent）。
+        let background_tier = resolve(
+            PaletteSource::BackgroundImage,
+            Source::Pixels(&background),
+            Source::Pixels(&wallpaper),
+            SchemeFlavor::Light,
+        );
+        assert_eq!(background_tier.level(), Level::BackgroundImage);
+        assert_eq!(background_tier.provenance.wallpaper(), Outcome::NotReached);
+    }
+
+    #[test]
+    fn hints_are_only_produced_for_keys_we_ship_a_sentence_for() {
+        // 抓得住：note() 不会为未知键编文案（返回 None 而不是 Some("")）。
+        assert_eq!(
+            note(
+                &resolve(
+                    PaletteSource::Preset,
+                    Source::Absent,
+                    Source::Absent,
+                    SchemeFlavor::Light,
+                )
+                .provenance
+            ),
+            None
+        );
+    }
+}
diff --git a/crates/app-iced/src/pages/appearance/picture.rs b/crates/app-iced/src/pages/appearance/picture.rs
new file mode 100644
index 0000000..f4280fa
--- /dev/null
+++ b/crates/app-iced/src/pages/appearance/picture.rs
@@ -0,0 +1,113 @@
+//! 背景层的**像素**：真图直出（`Cover` / `Contain` / `Tile`）+ 暗化叠层。
+//!
+//! 与 [`super::section`] 拆开只为单文件 ≤400 行的纪律；对外入口仍是
+//! `pages::appearance::layer`（本文件 [`layer`] 的再导出）。
+//!
+//! ## 三种填充
+//!
+//! `Cover`/`Contain` 交给渲染器的 `ContentFit`（等比缩放 + 裁切/留白由它做）；`Tile` 用
+//! [`background::tiles`] 算行列后铺 N 个图块（单块尺寸 = 原尺寸 × `tiles.scale`）。
+//!
+//! 暗化不是逐像素改色，而是**盖一层「版面底色 @ α=dim」**：图不透明时它与「向底色插值」
+//! 数学等价（[`background::dim_alpha`] 有推导），而普通 alpha 混合 CPU/GPU 两档都支持。
+
+use iced::widget::image;
+use iced::widget::{column, container, image as image_widget, space};
+use iced::{ContentFit, Element, Length};
+
+use unlucky_design::color::Role;
+use unlucky_presenter::prefs::BgFill;
+
+use crate::pages::{frame, Message};
+use crate::theme::Ui;
+
+use super::background;
+use super::state::State;
+
+/// 背景层（铺满整窗、垫在最下层）。`None` = 没有可用的背景图（调用方就不叠这一层）。
+///
+/// 真图直出（M93 r2）：`Cover` / `Contain` 交给 iced 的 `ContentFit`，`Tile` 用
+/// [`background::tiles`] 算网格铺 N 个图块。暗化 = 一层「版面底色 @ α=dim」盖在图上
+/// （见 [`background::dim_alpha`] 的等价性说明）。
+#[must_use]
+pub fn layer(ui: &Ui, state: &State, viewport: (f32, f32)) -> Option<Element<'static, Message>> {
+    let picture = state.image()?;
+    if !state.bg_enabled {
+        return None;
+    }
+
+    let handle = image_handle(state.bg_path.trim());
+    let art: Element<'static, Message> = match state.bg_fill {
+        BgFill::Cover => fitted(handle, ContentFit::Cover),
+        BgFill::Contain => fitted(handle, ContentFit::Contain),
+        BgFill::Tile => tiled(handle, picture.source, viewport),
+    };
+
+    // 暗化：底色 @ α=dim 盖在图上（等价于逐像素向底色插值，见 `background::dim_alpha`）。
+    let scrim_color = ui
+        .color(Role::Surface)
+        .scale_alpha(background::dim_alpha(state.bg_dim));
+    let scrim: Element<'static, Message> = container(space::horizontal())
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .style(move |_theme| frame::filled(scrim_color))
+        .into();
+
+    Some(
+        iced::widget::stack![art, scrim]
+            .width(Length::Fill)
+            .height(Length::Fill)
+            .into(),
+    )
+}
+
+/// 文件字节 → iced 的图片句柄（渲染器自己解复用，不再读盘）。
+fn image_handle(path: &str) -> image::Handle {
+    image::Handle::from_path(path)
+}
+
+/// `Cover` / `Contain`：交给渲染器的等比缩放档。
+fn fitted(handle: image::Handle, fit: ContentFit) -> Element<'static, Message> {
+    image_widget(handle)
+        .content_fit(fit)
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .into()
+}
+
+/// `Tile`：按 [`background::tiles`] 的网格平铺。
+///
+/// 三个细节都是为了「不留缝」（复审 r1 P2-1）：
+/// 1. 单块边长 = `源尺寸 × tiles.scale`——超预算时图块**等比例放大**（不是少铺），
+///    所以 `cols × 边长 >= 视口宽`、`rows × 边长 >= 视口高` 由 [`background::tiles`] 保证；
+/// 2. `ContentFit::Fill`：`None` 会按**图片原生尺寸**画，比格子小就留空——那道缝正是它造成的；
+///    这里格子尺寸恰好等于「等比放大后的尺寸」，`Fill` 就是等比缩放本身（不变形）；
+/// 3. 行高显式写死（`Fixed`），列整体 `Fill`：不靠子控件撑，布局结果与算式一致。
+fn tiled(
+    handle: image::Handle,
+    source: (u32, u32),
+    viewport: (f32, f32),
+) -> Element<'static, Message> {
+    let tiles = background::tiles(source, viewport);
+    let (width, height) = tiles.tile_size(source);
+
+    let rows = (0..tiles.rows)
+        .map(|_| {
+            let cells = (0..tiles.cols)
+                .map(|_| -> Element<'static, Message> {
+                    image_widget(handle.clone())
+                        .content_fit(ContentFit::Fill)
+                        .width(Length::Fixed(width))
+                        .height(Length::Fixed(height))
+                        .into()
+                })
+                .collect::<Vec<_>>();
+            iced::widget::row(cells)
+                .width(Length::Fill)
+                .height(Length::Fixed(height))
+                .into()
+        })
+        .collect::<Vec<_>>();
+
+    column(rows).width(Length::Fill).height(Length::Fill).into()
+}
diff --git a/crates/app-iced/src/pages/appearance/section.rs b/crates/app-iced/src/pages/appearance/section.rs
new file mode 100644
index 0000000..04e3ada
--- /dev/null
+++ b/crates/app-iced/src/pages/appearance/section.rs
@@ -0,0 +1,395 @@
+//! 设置页「外观」分组（**真控件**）+ 背景层 Element + 面板层配色。
+//!
+//! ## 控件与键的对应
+//!
+//! | 控件 | 键 | 改动消息 |
+//! |---|---|---|
+//! | 整窗透明度滑块（下限 0.08） | `appearance.window_opacity` | [`Change::WindowOpacity`] |
+//! | 窗口圆角（跟随系统 / 直角，M116） | `appearance.window_corner` | [`Change::Corner`] |
+//! | 面板透明度滑块（下限 0.4，CPU 档禁用） | `appearance.panel_alpha` | [`Change::PanelAlpha`] |
+//! | 背景图开关 | `appearance.bg_image_enabled` | [`Change::BgEnabled`] |
+//! | 背景图路径（文本框） | `appearance.bg_image` | [`Change::BgImage`] |
+//! | 填充（封面 / 拉伸 / 平铺） | `appearance.bg_fill` | [`Change::BgFill`] |
+//! | 暗化强度（0~0.95） | `appearance.bg_dim` | [`Change::BgDim`] |
+//! | 配色来源（三档） | `appearance.palette_source` | [`Change::PaletteSource`] |
+//!
+//! 文案一律英文基线（i18n 是别的 mission；本文件不拼中文、不 import 尚不存在的 crate）。
+//!
+//! ## 为什么「值」与「生效值」分开显示
+//!
+//! CPU 档下面板 α 被强制 1.0（D36），而用户请求值可能是 0.5。滑块位置按**生效值**画、旁边写
+//! 「requested 0.50 → forced 1.00」，这样「为什么拖了没反应」在界面上就有答案，而不是只躺在日志里。
+
+use iced::widget::{button, column, container, row, space};
+use iced::{
+    Alignment, Background, Border, Color, Element, Length, Padding, Shadow, Theme as IcedTheme,
+};
+
+use unlucky_design::color::Role;
+use unlucky_design::component_map::Component;
+use unlucky_design::elevation::MaterialLayer;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+use unlucky_i18n::catalog::Key;
+use unlucky_presenter::prefs::{BgFill, PaletteSource, WindowCorner};
+
+use crate::app::components::inputs::{slider, text_field, Field, Slider};
+use crate::pages::{frame, Message};
+use crate::theme::Ui;
+
+use super::alpha::{
+    panel_alpha_from_fraction, panel_fraction, window_alpha_from_fraction, window_fraction,
+    WINDOW_ALPHA_FLOOR,
+};
+use super::background::{self, BG_DIM_MAX};
+use super::state::State;
+use super::Change;
+
+/// 「外观」分组整块（一张卡）。
+pub fn section<'a>(ui: &'a Ui, state: &'a State) -> Element<'a, Message> {
+    let mut rows = column![].spacing(ui.space(Space::X1)).width(Length::Fill);
+
+    // ① 整窗透明度
+    let window_percent = format!("{:.0}%", state.window_opacity * 100.0);
+    rows = rows.push(slider_row(
+        ui,
+        "Window transparency",
+        window_percent,
+        format!(
+            "Applies to the whole window. Floor {:.2}; 1.00 = fully opaque.",
+            WINDOW_ALPHA_FLOOR
+        ),
+        state.window_opacity < 1.0,
+        slider(
+            Slider::new(ui, window_fraction(state.window_opacity)).on_change(|fraction| {
+                Message::Appearance(Change::WindowOpacity(window_alpha_from_fraction(fraction)))
+            }),
+        ),
+    ));
+
+    // ② 窗口圆角（M116）：只有两档 + 一句按平台说明；不做 8/12/16 档（系统不暴露半径）。
+    let corner = state.window_corner();
+    rows = rows.push(choice_row(
+        ui,
+        t(Key::SettingsAppearanceCorner),
+        vec![
+            choice(
+                ui,
+                t(Key::SettingsAppearanceCornerSystem),
+                corner == WindowCorner::System,
+                Change::Corner(WindowCorner::System),
+            ),
+            choice(
+                ui,
+                t(Key::SettingsAppearanceCornerSquare),
+                corner == WindowCorner::Square,
+                Change::Corner(WindowCorner::Square),
+            ),
+        ],
+    ));
+    // **tonal notice**（r5 视觉终稿）：M3 里表达「当前状态」的惯用形态是**容器**，不是改字色。
+    // 只在「跟随系统 + α<1」出现；与下面的说明段之间再留 `Space::X1`（列间距 X1 + 这里 X1 = X2）。
+    if corner == WindowCorner::System && state.window_opacity < 1.0 {
+        rows = rows.push(super::notice(ui, t(Key::SettingsAppearanceCornerSuspended)));
+        let gap: Element<'a, Message> = space::vertical().height(ui.space(Space::X1)).into();
+        rows = rows.push(gap);
+    }
+    let tone = ui.color(Role::OnSurfaceVariant);
+    rows = rows.push(note_line(ui, t(Key::SettingsAppearanceCornerHint), tone));
+
+    // ③ 面板透明度（CPU 档强制 1.0）
+    let forced = state.panel_is_forced();
+    let panel_percent = if forced {
+        format!("100% (forced from {:.2})", state.panel_alpha)
+    } else {
+        format!("{:.0}%", state.effective_panel_alpha() * 100.0)
+    };
+    let panel_hint = if forced {
+        "Software renderer: panels stay fully opaque (window transparency still works)."
+    } else {
+        "Only the panel/card layer. Floor 0.40; independent of window transparency."
+    };
+    let panel_control = if forced {
+        slider(Slider::new(ui, panel_fraction(1.0)))
+    } else {
+        slider(
+            Slider::new(ui, panel_fraction(state.panel_alpha)).on_change(|fraction| {
+                Message::Appearance(Change::PanelAlpha(panel_alpha_from_fraction(fraction)))
+            }),
+        )
+    };
+    rows = rows.push(slider_row(
+        ui,
+        "Panel transparency",
+        panel_percent,
+        panel_hint.to_owned(),
+        !forced,
+        panel_control,
+    ));
+
+    // ④ 背景图开关
+    rows = rows.push(choice_row(
+        ui,
+        "Background image",
+        vec![
+            choice(ui, "Off", !state.bg_enabled, Change::BgEnabled(false)),
+            choice(ui, "On", state.bg_enabled, Change::BgEnabled(true)),
+        ],
+    ));
+
+    // ⑤ 路径（文本框：受控，输入即生效）
+    let path_field: Element<'a, Message> = text_field(
+        ui,
+        Field::new(&state.bg_path)
+            .label("Image path")
+            .placeholder("D:/Pictures/background.png"),
+        |value| Message::Appearance(Change::BgImage(value)),
+    );
+    rows = rows.push(
+        column![label(ui, "Image path"), path_field]
+            .spacing(ui.space(Space::X1))
+            .width(Length::Fill),
+    );
+
+    // ⑥ 诊断（读盘失败 / CPU 降级 / 配色回落）——**不许静默**，且必须在**首屏可见处**
+    // （复审 r1 P2-3：文案落在折叠线以下等于没提示）。位置就在背景图那两行的紧下方。
+    for note in state.diagnostics() {
+        rows = rows.push(note_line(ui, note, ui.color(Role::Error)));
+    }
+    if let Some(note) = state.backend_note() {
+        rows = rows.push(note_line(ui, note, ui.color(Role::OnSurfaceVariant)));
+    }
+    if let Some(note) = state
+        .image()
+        .and_then(|image| background::small_tile_note(image, state.bg_fill))
+    {
+        rows = rows.push(note_line(ui, &note, ui.color(Role::OnSurfaceVariant)));
+    }
+    if let Some(note) = state.palette_note() {
+        rows = rows.push(note_line(ui, note, ui.color(Role::OnSurfaceVariant)));
+    }
+    let resolved = format!("Colours: {}", state.palette_level());
+    rows = rows.push(note_line(ui, &resolved, ui.color(Role::OnSurfaceVariant)));
+
+    // ⑦ 填充
+    rows = rows.push(choice_row(
+        ui,
+        "Fill",
+        vec![
+            choice(
+                ui,
+                "Cover",
+                state.bg_fill == BgFill::Cover,
+                Change::BgFill(BgFill::Cover),
+            ),
+            choice(
+                ui,
+                "Contain",
+                state.bg_fill == BgFill::Contain,
+                Change::BgFill(BgFill::Contain),
+            ),
+            choice(
+                ui,
+                "Tile",
+                state.bg_fill == BgFill::Tile,
+                Change::BgFill(BgFill::Tile),
+            ),
+        ],
+    ));
+
+    // ⑧ 暗化
+    rows = rows.push(slider_row(
+        ui,
+        "Dim",
+        format!("{:.0}%", state.bg_dim * 100.0),
+        format!(
+            "Blends the image toward the panel colour so text stays readable. Max {BG_DIM_MAX:.2}."
+        ),
+        state.bg_dim > 0.0,
+        slider(
+            Slider::new(ui, state.bg_dim / BG_DIM_MAX)
+                .on_change(|fraction| Message::Appearance(Change::BgDim(fraction * BG_DIM_MAX))),
+        ),
+    ));
+
+    // ⑨ 配色来源
+    rows = rows.push(choice_row(
+        ui,
+        "Colour source",
+        vec![
+            choice(
+                ui,
+                "Background",
+                state.palette_source == PaletteSource::BackgroundImage,
+                Change::PaletteSource(PaletteSource::BackgroundImage),
+            ),
+            choice(
+                ui,
+                "Wallpaper",
+                state.palette_source == PaletteSource::Wallpaper,
+                Change::PaletteSource(PaletteSource::Wallpaper),
+            ),
+            choice(
+                ui,
+                "Preset",
+                state.palette_source == PaletteSource::Preset,
+                Change::PaletteSource(PaletteSource::Preset),
+            ),
+        ],
+    ));
+
+    card(ui, rows)
+}
+
+/// 外观卡片：底色走 `ui.layer`（面板 α 的唯一来源），与其它页的卡片同源。
+fn card<'a>(ui: &'a Ui, content: impl Into<Element<'a, Message>>) -> Element<'a, Message> {
+    let spec = Component::OutlinedCard.spec();
+    let background = ui.layer(MaterialLayer::Card);
+
+    container(content)
+        .width(Length::Fill)
+        .padding(ui.metrics().card_padding)
+        .style(move |_theme| container::Style {
+            background: Some(Background::Color(background)),
+            border: ui.outlined(spec.shape),
+            ..container::Style::default()
+        })
+        .into()
+}
+
+// --------------------------------------------------------------- 行与控件
+
+fn label<'a>(ui: &'a Ui, content: &'a str) -> Element<'a, Message> {
+    frame::text_role(
+        ui,
+        TypeRole::BodyMedium,
+        false,
+        content,
+        ui.color(Role::OnSurface),
+    )
+}
+
+/// 设置页文案的 i18n 取词口（M116 起新条目一律走词表，不再写字面量）。
+///
+/// 为什么是 [`Lang::En`]：本文件的既有文案是英文基线（i18n 接线是另一条 mission，
+/// 见本文件头部「文案一律英文基线」）。走词表的意义是**新增条目已经有中英两套**，
+/// 接线时只换这一行，不用回来重写控件。
+fn t(key: Key) -> &'static str {
+    unlucky_i18n::Lang::En.catalog().text(key)
+}
+
+fn note_line<'a>(ui: &'a Ui, content: &str, color: Color) -> Element<'a, Message> {
+    // 诊断文案是**运行时拼出来的**（路径、错误原因），只能走 owned 版本。
+    frame::text_role_owned(ui, TypeRole::BodySmall, false, content.to_owned(), color)
+}
+
+/// 一行「标签 + 值 + 滑块 + 说明」。
+fn slider_row<'a>(
+    ui: &'a Ui,
+    title: &'a str,
+    value: String,
+    hint: String,
+    enabled: bool,
+    control: Element<'a, Message>,
+) -> Element<'a, Message> {
+    let value_color = if enabled {
+        ui.color(Role::OnSurface)
+    } else {
+        ui.color(Role::OnSurfaceVariant)
+    };
+
+    let head = row![
+        container(label(ui, title))
+            .width(Length::Fill)
+            .align_y(Alignment::Center),
+        frame::text_role_owned(ui, TypeRole::LabelLarge, true, value, value_color),
+    ]
+    .width(Length::Fill)
+    .align_y(Alignment::Center);
+
+    column![
+        head,
+        control,
+        frame::text_role_owned(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            hint,
+            ui.color(Role::OnSurfaceVariant),
+        ),
+    ]
+    .spacing(ui.space(Space::X1))
+    .width(Length::Fill)
+    .padding(Padding::from([ui.space(Space::X2), 0.0]))
+    .into()
+}
+
+/// 一行「标签 + 一排互斥按钮」。
+fn choice_row<'a>(
+    ui: &'a Ui,
+    title: &'a str,
+    choices: Vec<Element<'a, Message>>,
+) -> Element<'a, Message> {
+    row![
+        container(label(ui, title))
+            .width(Length::Fill)
+            .align_y(Alignment::Center),
+        row(choices)
+            .spacing(ui.space(Space::X1))
+            .align_y(Alignment::Center),
+    ]
+    .width(Length::Fill)
+    .align_y(Alignment::Center)
+    .padding(Padding::from([ui.space(Space::X2), 0.0]))
+    .into()
+}
+
+/// 一个互斥按钮（选中态用 `SecondaryContainer`，未选中用透明 + `OnSurfaceVariant`）。
+fn choice<'a>(ui: &'a Ui, text: &'a str, selected: bool, change: Change) -> Element<'a, Message> {
+    let height = ui.metrics().control_height;
+    let content_color = if selected {
+        ui.color(Role::OnSecondaryContainer)
+    } else {
+        ui.color(Role::OnSurfaceVariant)
+    };
+
+    button(
+        container(frame::text_role(
+            ui,
+            TypeRole::LabelLarge,
+            selected,
+            text,
+            content_color,
+        ))
+        .align_y(Alignment::Center),
+    )
+    .height(height)
+    .padding(Padding::from([0.0, ui.space(Space::X3)]))
+    .style(move |_theme: &IcedTheme, status| {
+        let background = if selected {
+            Some(Background::Color(ui.color(Role::SecondaryContainer)))
+        } else if matches!(status, button::Status::Hovered | button::Status::Pressed) {
+            Some(Background::Color(ui.state_over(
+                unlucky_design::color::StateLayer::Hover,
+                Role::OnSurface,
+                Role::Surface,
+            )))
+        } else {
+            None
+        };
+
+        button::Style {
+            background,
+            text_color: content_color,
+            border: Border {
+                radius: ui.radius(ShapeScale::Full, height),
+                ..Border::default()
+            },
+            shadow: Shadow::default(),
+            snap: true,
+        }
+    })
+    .on_press(Message::Appearance(change))
+    .into()
+}
diff --git a/crates/app-iced/src/pages/appearance/state.rs b/crates/app-iced/src/pages/appearance/state.rs
new file mode 100644
index 0000000..e1868bf
--- /dev/null
+++ b/crates/app-iced/src/pages/appearance/state.rs
@@ -0,0 +1,390 @@
+//! 外观的**运行期状态**：配置值 → 生效值（钳位 / CPU 档降级）→ 要下发的字节与要画的格子。
+//!
+//! 这一层是「键 → 像素」的中间站，App 持有一份（`crate::app::state::App::appearance`）：
+//!
+//! ```text
+//! launcher.json ──SettingsBridge::load/load_base──┐
+//!                                                ▼
+//!                                          State（本文件）
+//!                                   ┌────────────┴────────────┐
+//!                     整窗 α → 字节 │                         │ 面板 α / 背景图 → Element
+//!                                   ▼                         ▼
+//!                        app::window_alpha（FFI）      shell / 设置页（像素）
+//! ```
+//!
+//! **纯的与不纯的**分界刻意写在这里：钳位链（[`super::alpha`]）、几何（[`super::background`]）、
+//! 优先序（[`super::palette`]）都是纯函数；本文件只把它们的输入输出连起来，并把「读盘失败」
+//! 变成一条**可读诊断**而不是一个 `unwrap`。
+
+use unlucky_design::color::{Scheme, SchemeFlavor};
+use unlucky_presenter::prefs::{
+    AppearanceBase, AppearancePrefs, BgFill, PaletteSource, WindowCorner,
+};
+
+use crate::Backend;
+
+use super::alpha::{self, effective_glass, effective_panel_alpha, panel_is_forced_opaque};
+use super::background::{self, Image};
+use super::palette::{self, Resolved, Source};
+
+/// 取证开关的环境变量名（截图矩阵与真机日志用；生产默认全部不设）。
+pub const ENV_WINDOW_ALPHA: &str = "ULL_APPEARANCE_WINDOW_ALPHA";
+/// 面板 α。
+pub const ENV_PANEL_ALPHA: &str = "ULL_APPEARANCE_PANEL_ALPHA";
+/// 背景图路径。
+pub const ENV_BG_IMAGE: &str = "ULL_APPEARANCE_BG_IMAGE";
+/// 填充档（`cover` / `contain` / `tile`）。
+pub const ENV_BG_FILL: &str = "ULL_APPEARANCE_BG_FILL";
+/// 暗化强度。
+pub const ENV_BG_DIM: &str = "ULL_APPEARANCE_BG_DIM";
+/// 配色来源档（`background-image` / `wallpaper` / `preset`）。
+pub const ENV_PALETTE: &str = "ULL_APPEARANCE_PALETTE";
+
+/// 外观的运行期状态。
+#[derive(Debug, Clone, PartialEq)]
+pub struct State {
+    /// 用户请求的整窗 α（未钳位原值；下发前过 [`super::alpha`]）。
+    pub window_opacity: f32,
+    /// 用户请求的面板 α（CPU 档会被强制成 1.0，见 [`State::effective_panel_alpha`]）。
+    pub panel_alpha: f32,
+    /// 背景图总开关。
+    pub bg_enabled: bool,
+    /// 背景图路径（空 = 未设置）。
+    pub bg_path: String,
+    /// 填充档。
+    pub bg_fill: BgFill,
+    /// 暗化强度。
+    pub bg_dim: f32,
+    /// 配色来源档。
+    pub palette_source: PaletteSource,
+    /// 玻璃拟态开关（CPU 档强制关）。
+    pub glass: bool,
+    /// 窗口圆角策略（M116：`system` / `square`；真能不能圆由平台判，见 `platform::plan_corner`）。
+    pub window_corner: WindowCorner,
+    /// 渲染后端（决定 CPU 档的两条降级）。
+    pub backend: Backend,
+    /// 设置页当前分组（0 = General … 1 = Appearance；见 [`super::APPEARANCE_GROUP`]）。
+    pub selected_group: usize,
+    /// 已解码的背景图（`None` = 没设 / 读失败）。
+    image: Option<Image>,
+    /// 读盘/解码失败的**可读诊断**（按发生顺序追加）。
+    diagnostics: Vec<String>,
+    /// 上一次的配色解析结果。
+    resolved: Option<Resolved>,
+    /// 当前深浅（配色解析的输入）。
+    flavor: SchemeFlavor,
+}
+
+impl State {
+    /// 从配置读一份（启动时调一次）。
+    #[must_use]
+    pub fn new(
+        prefs: &AppearancePrefs,
+        base: &AppearanceBase,
+        backend: Backend,
+        flavor: SchemeFlavor,
+    ) -> Self {
+        let mut state = Self {
+            window_opacity: base.window_opacity,
+            panel_alpha: prefs.panel_alpha,
+            bg_enabled: prefs.bg_image_enabled,
+            bg_path: prefs.bg_image.clone(),
+            bg_fill: prefs.bg_fill,
+            bg_dim: prefs.bg_dim,
+            palette_source: base.palette_source,
+            window_corner: base.window_corner,
+            glass: prefs.glass,
+            backend,
+            selected_group: super::APPEARANCE_GROUP,
+            image: None,
+            diagnostics: Vec::new(),
+            resolved: None,
+            flavor,
+        };
+        state.refresh_background();
+        state.refresh_palette();
+        state
+    }
+
+    /// 截图/真机取证用：把 `ULL_APPEARANCE_*` 灌进来（不设 = 不动）。
+    ///
+    /// 为什么用环境变量而不是 CLI 参数：`crates/app-iced/src/cli.rs` 不在本 mission 的 scope。
+    /// 语义与既有取证开关（`ULL_TICK_TRACE`）一致：**只影响这次进程**，不落盘。
+    pub fn apply_env(&mut self) {
+        if let Some(value) = env_f32(ENV_WINDOW_ALPHA) {
+            self.window_opacity = value;
+        }
+        if let Some(value) = env_f32(ENV_PANEL_ALPHA) {
+            self.panel_alpha = value;
+        }
+        if let Some(value) = std::env::var_os(ENV_BG_IMAGE) {
+            let path = value.to_string_lossy().to_string();
+            self.bg_enabled = !path.trim().is_empty();
+            self.bg_path = path;
+        }
+        if let Some(value) = std::env::var_os(ENV_BG_FILL) {
+            self.bg_fill = BgFill::from_key_value(&value.to_string_lossy());
+        }
+        if let Some(value) = env_f32(ENV_BG_DIM) {
+            self.bg_dim = value;
+        }
+        if let Some(value) = std::env::var_os(ENV_PALETTE) {
+            self.palette_source = PaletteSource::from_key_value(&value.to_string_lossy());
+        }
+        self.refresh_background();
+        self.refresh_palette();
+    }
+
+    /// 面板 α 的**生效值**（CPU 档恒 1.0）。
+    #[must_use]
+    pub fn effective_panel_alpha(&self) -> f32 {
+        effective_panel_alpha(self.backend, self.panel_alpha)
+    }
+
+    /// 面板 α 是否被后端强制（设置页据此禁用滑块并给说明）。
+    #[must_use]
+    pub fn panel_is_forced(&self) -> bool {
+        panel_is_forced_opaque(self.backend)
+    }
+
+    /// 当前圆角策略（设置页显示选中项、日志与下发都用它）。
+    #[must_use]
+    pub fn window_corner(&self) -> WindowCorner {
+        self.window_corner
+    }
+
+    /// 改圆角策略（消息落点见 `app::update::appearance`；这里只管状态，不碰窗口）。
+    pub fn set_window_corner(&mut self, policy: WindowCorner) {
+        self.window_corner = policy;
+    }
+
+    /// 玻璃是否生效（CPU 档恒关）。
+    #[must_use]
+    pub fn effective_glass(&self) -> bool {
+        effective_glass(self.backend, self.glass)
+    }
+
+    /// 整窗 α 要下发的字节（`None` = 不调 FFI）。
+    #[must_use]
+    pub fn window_alpha_byte(&self) -> Option<u8> {
+        alpha::window_alpha_byte(self.backend, self.window_opacity)
+    }
+
+    /// 背景图是否真的会画（开关开 + 路径非空 + 解码成功）。
+    #[must_use]
+    pub fn background_active(&self) -> bool {
+        self.bg_enabled && self.image.is_some()
+    }
+
+    /// 已解码的背景图。
+    #[must_use]
+    pub fn image(&self) -> Option<&Image> {
+        self.image.as_ref()
+    }
+
+    /// 取色得到的方案（`None` = 色卡档，继续用令牌 baseline）。
+    ///
+    /// 为什么色卡档不换 scheme：`resolve_source` 的色卡档走的是 `DEFAULT_CARD`（天蓝卡），
+    /// 与令牌 baseline 逐色不同；直接应用会把**全部既有验收图的像素**改掉。色卡档的视觉基线
+    /// 归令牌层（`Scheme::baseline`），这里只接管「取色真的成功」的那两档。
+    #[must_use]
+    pub fn derived_scheme(&self) -> Option<&Scheme> {
+        let resolved = self.resolved.as_ref()?;
+        if resolved.level() == unlucky_design::palette::Level::Preset {
+            return None;
+        }
+        Some(&resolved.scheme)
+    }
+
+    /// 读盘/解码失败的诊断（设置页逐条显示）。
+    #[must_use]
+    pub fn diagnostics(&self) -> &[String] {
+        &self.diagnostics
+    }
+
+    /// CPU 档降级的说明（`None` = 没有降级）。
+    #[must_use]
+    pub fn backend_note(&self) -> Option<&'static str> {
+        self.panel_is_forced().then_some(
+            "Software renderer: panel transparency and glass stay fully opaque (window \
+             transparency still works).",
+        )
+    }
+
+    /// 配色来源的提示（`None` = 一级成功）。
+    #[must_use]
+    pub fn palette_note(&self) -> Option<&'static str> {
+        self.resolved.as_ref()?.note()
+    }
+
+    /// 生效的配色层级码（日志用）。
+    #[must_use]
+    pub fn palette_level(&self) -> &'static str {
+        match &self.resolved {
+            Some(resolved) => resolved.level().code(),
+            None => self.palette_source.as_str(),
+        }
+    }
+
+    /// 深浅切换后重算配色（`Ui` 换主题时调）。
+    pub fn set_flavor(&mut self, flavor: SchemeFlavor) {
+        if self.flavor == flavor {
+            return;
+        }
+        self.flavor = flavor;
+        self.refresh_palette();
+    }
+
+    /// 当前深浅。
+    #[must_use]
+    pub fn flavor(&self) -> SchemeFlavor {
+        self.flavor
+    }
+
+    /// 应用一条改动（设置页 → 状态）。返回**是否需要立刻下发整窗 α**。
+    pub fn apply(&mut self, change: super::Change) -> bool {
+        use super::Change;
+        match change {
+            Change::WindowOpacity(alpha) => {
+                self.window_opacity = alpha;
+                true
+            }
+            Change::PanelAlpha(alpha) => {
+                self.panel_alpha = alpha;
+                false
+            }
+            Change::BgEnabled(enabled) => {
+                self.bg_enabled = enabled;
+                self.refresh_background();
+                self.refresh_palette();
+                false
+            }
+            Change::BgImage(path) => {
+                self.bg_path = path;
+                self.bg_enabled = !self.bg_path.trim().is_empty();
+                self.refresh_background();
+                self.refresh_palette();
+                false
+            }
+            Change::BgFill(fill) => {
+                self.bg_fill = fill;
+                false
+            }
+            Change::BgDim(dim) => {
+                self.bg_dim = dim;
+                false
+            }
+            Change::PaletteSource(source) => {
+                self.palette_source = source;
+                self.refresh_palette();
+                false
+            }
+            Change::Corner(policy) => {
+                self.window_corner = policy;
+                false
+            }
+            Change::SelectGroup(index) => {
+                self.selected_group = index;
+                false
+            }
+        }
+    }
+
+    /// 写回配置用的快照（`SettingsBridge::persist` 覆盖的那 8 个字段）。
+    ///
+    /// 注意：**强调色 / 玻璃不在本 mission 的管辖内**，调用方（`app::appearance`）会拿配置里
+    /// 已有的快照做基底、只覆盖本 mission 真改了的字段，所以这里不产出完整快照。
+    /// 这个函数只给「当前值是什么」一个只读视图（日志与测试用）。
+    #[must_use]
+    pub fn current_values(&self) -> AppearancePrefs {
+        AppearancePrefs {
+            bg_image_enabled: self.bg_enabled,
+            bg_image: self.bg_path.clone(),
+            bg_fill: self.bg_fill,
+            bg_dim: self.bg_dim,
+            panel_alpha: self.panel_alpha,
+            glass: self.glass,
+            accent_color: String::new(),
+        }
+    }
+
+    /// 取证日志（**一行**，数值而不是观感）：`[appearance] window_alpha=… panel_alpha=… byte=…`。
+    #[must_use]
+    pub fn log_line(&self, context: &str) -> String {
+        let byte = self
+            .window_alpha_byte()
+            .map_or_else(|| "none".to_owned(), |byte| byte.to_string());
+        format!(
+            "[appearance] {context} window_alpha={:.3} panel_alpha={:.3} (requested {:.3}) \
+             byte={byte} corner={} backend={} bg={} fill={} dim={:.2} palette={} group={}",
+            self.window_opacity,
+            self.effective_panel_alpha(),
+            self.panel_alpha,
+            self.window_corner.as_str(),
+            self.backend.name(),
+            if self.background_active() {
+                self.bg_path.as_str()
+            } else {
+                "none"
+            },
+            self.bg_fill.as_str(),
+            self.bg_dim,
+            self.palette_level(),
+            self.selected_group
+        )
+    }
+
+    /// 重读配置后同步（热切）。
+    pub fn reload(&mut self, prefs: &AppearancePrefs, base: &AppearanceBase) {
+        self.window_opacity = base.window_opacity;
+        self.palette_source = base.palette_source;
+        self.window_corner = base.window_corner;
+        self.panel_alpha = prefs.panel_alpha;
+        self.bg_enabled = prefs.bg_image_enabled;
+        self.bg_fill = prefs.bg_fill;
+        self.bg_dim = prefs.bg_dim;
+        self.glass = prefs.glass;
+        if self.bg_path != prefs.bg_image {
+            self.bg_path = prefs.bg_image.clone();
+        }
+        self.refresh_background();
+        self.refresh_palette();
+    }
+
+    // ------------------------------------------------------------ 内部
+
+    fn refresh_background(&mut self) {
+        self.image = None;
+        self.diagnostics.clear();
+        let trimmed = self.bg_path.trim();
+        if !self.bg_enabled || trimmed.is_empty() {
+            return;
+        }
+        match background::load(trimmed) {
+            Ok(image) => self.image = Some(image),
+            Err(error) => self.diagnostics.push(error.describe()),
+        }
+    }
+
+    fn refresh_palette(&mut self) {
+        let background = match (&self.image, self.bg_enabled) {
+            (Some(image), true) => Source::Pixels(image),
+            (None, true) if !self.bg_path.trim().is_empty() => Source::Undecodable,
+            _ => Source::Absent,
+        };
+        // 桌面壁纸探测（M73）尚未落地：这一级永远 `Absent`，回落链仍按 design 的规则走。
+        self.resolved = Some(palette::resolve(
+            self.palette_source,
+            background,
+            Source::Absent,
+            self.flavor,
+        ));
+    }
+}
+
+fn env_f32(key: &str) -> Option<f32> {
+    std::env::var(key)
+        .ok()
+        .and_then(|value| value.trim().parse::<f32>().ok())
+        .filter(|value| value.is_finite())
+}
diff --git a/crates/app-iced/src/pages/content.rs b/crates/app-iced/src/pages/content.rs
new file mode 100644
index 0000000..736ee55
--- /dev/null
+++ b/crates/app-iced/src/pages/content.rs
@@ -0,0 +1,99 @@
+//! # 内容库页（M109 `CONTENTDL`）：整合包 / Mod / 资源包 / 光影
+//!
+//! 用户令：「下载页只负责下载整合包和Mod/光影」。于是版本管理页（M107/M108 改名）只做版本，
+//! **这一页**做内容：四条内容类型（页内一级侧栏）+ 关键词/来源/版本/加载器/排序筛选 +
+//! 结果列表与详情面板 + **一键装入指定实例**。
+//!
+//! ## 入口（B1 裁定：不新增导航项）
+//!
+//! `Route::Content` 是新顶层路由，但 `Route::nav()` 返回 `NavSection::Download`：导航轨仍是
+//! 五项，页头右上是「版本管理 | 内容库」一级切换（[`parts::section_switcher`]）。
+//! 为什么不是第六个图标：轨宽 88 塞六项会挤，且用户要的是「同一入口下两块内容」。
+//!
+//! ## 分页 vs 无限滚动：**选分页**
+//!
+//! 三条理由，都是这一页的实际约束：
+//!
+//! 1. **快照只有一个槽**（`AppState::content.results`）：无限滚动要求「滚到底就自动续」，而
+//!    自动续在没有虚拟化列表的 iced 里会一次挂上几百个控件；
+//! 2. **翻页要有明确出口**：站点限流 / 失败重试都发生在「下一批」上，用户得能看见自己正在
+//!    等第 3 页，而不是画面莫名一卡；
+//! 3. **可截图复现**：分页的每一次状态都是一份确定的快照，D30 的矩阵能钉住「还有更多 / 没有更多了」。
+//!
+//! 所以尾部是一个「加载更多」按钮 + 一句「没有更多了」（[`parts::more`]），追加逻辑在
+//! presenter 的 `AppState::apply_content`（同条件换页 ⇒ 追加；换条件 ⇒ 整批替换；迟到 ⇒ 丢掉）。
+//!
+//! ## 四态（都必须能画出来）
+//!
+//! | 态 | 判据 | 画什么 |
+//! |---|---|---|
+//! | 加载 | `pending` 或还没有结果 | 一句「正在加载」+ 说明 + 重试 |
+//! | 空 | 拉到了、零命中 | 真 `EmptyState` + 重试 CTA |
+//! | 失败 | `failed` 有原因 | `Error` 图标 + 原因原文 + 重试（实心） |
+//! | 有数据 | 有命中项 | 计数头 + 列表 +（还有更多 ⇒ 加载更多 / 否则 ⇒ 没有更多了） |
+//!
+//! ## 不在这里做的事
+//!
+//! - **不发 HTTP**：检索与装入都在 presenter 的 `host/addon`（任务书第 4 条）。
+//! - **不做乐观回显**：点「装入」不改本地状态，进度只由 `InstallProgress` 事件回流。
+//! - **不自己画安装面板**：复用 `pages::download::install_panel`（同一个函数、同一套文案）。
+//!
+//! ## 偏离登记
+//!
+//! | # | 偏离 | 为什么 | 何时收口 |
+//! |---|---|---|---|
+//! | 1 | 四种内容类型借用现有字形（`Folder` / `Plus` / `Restore` / `Expand`，见 `parts::kind_icon`） | 设计令牌的 28 枚图标里没有这四类内容，且**不许**借用导航那五枚（同屏撞形）、不许用填充字形（门禁） | 图标集补「整合包 / Mod / 资源包 / 光影」时 |
+//! | 2 | 本页自带一份栏几何（`content/layout.rs`） | M107 的 `pages/layout/rails.rs` 未并入本分支的 base | M107 合并后改为复用、删掉本文件 |
+//! | 3 | 整合包的「装入」是禁用态 | core 没有远程整合包的安装管线 | 导入管线落地后接同一入口 |
+//! | 5 | CurseForge 的「装入」同样是禁用态（`Blocker::SourceNotWired`） | 检索通了，**文件端点**还没接（CF 的文件列表要带 key） | 接上 CF 文件端点后删掉这条原因 |
+//! | 4 | 安装进度只有阶段级（无字节条） | presenter 依赖表里没有 tokio/futures，拿不到 `ProgressEmitter` 的接收端 | presenter 补依赖后换成字节级 |
+
+mod demo;
+mod layout;
+mod message;
+mod model;
+// M113: import/export —— 导入/导出区的界面（新代码全在 `packui*`）
+mod packui;
+mod parts;
+mod view;
+
+#[cfg(test)]
+mod tests;
+
+pub use message::Message;
+pub use model::{loader_name, Blocker, Content, ContentQueryView, Hit, PageState, Status, Target};
+// M113: import/export
+pub use packui::{request_export, Pack, PackMessage, PackPageState};
+
+use iced::Element;
+
+use unlucky_i18n::Lang;
+
+pub use unlucky_presenter::dto::ContentKind;
+
+use crate::pages::layout::FrameMetrics;
+use crate::pages::Message as PageMessage;
+use crate::theme::Ui;
+
+/// 整页入口（`pages/mod.rs` 的 `render` 调它；页面层不认识 presenter 的 DTO）。
+pub fn view<'a>(
+    ui: &'a Ui,
+    metrics: FrameMetrics,
+    model: &'a Content,
+    lang: Lang,
+) -> Element<'a, PageMessage> {
+    view::view(ui, metrics, model, lang)
+}
+
+/// 演示数据（`pages_demo` 出图与单测用；产品路径走 `Content::from_snapshot`）。
+pub fn demo(kind: ContentKind, lang: Lang) -> Content {
+    demo::demo(kind, lang)
+}
+
+/// 页头那条一级切换（版本管理页也要用同一个函数：两页共用一个入口才不会各画一套）。
+pub(crate) fn section_switcher<'a>(
+    ui: &'a Ui,
+    catalog: unlucky_i18n::Catalog,
+) -> Element<'a, PageMessage> {
+    parts::section_switcher(ui, catalog, true)
+}
diff --git a/crates/app-iced/src/pages/content/demo.rs b/crates/app-iced/src/pages/content/demo.rs
new file mode 100644
index 0000000..9259019
--- /dev/null
+++ b/crates/app-iced/src/pages/content/demo.rs
@@ -0,0 +1,221 @@
+//! 内容库的演示数据（`pages_demo` 出图与单测用；产品路径永远走 `Content::from_snapshot`）。
+//!
+//! ## 为什么要环境变量选「哪一屏」
+//!
+//! D30 的验收矩阵要求「四类内容 × 浅/深」加「搜索无结果」「加载器不兼容禁用」两种状态，
+//! 共 10 张。`pages_demo` 的 `--screen=` 只够选到**哪一页**，选不到「同一页的哪一态」；
+//! 而 `pages/harness.rs` 与 `cli.rs` 不在本 mission 的 scope。
+//!
+//! 所以沿用本仓既有的取证开关范式（`ULL_START_ROUTE` / `ULL_APPEARANCE_*` / `ULL_TICK_TRACE`）：
+//!
+//! | 变量 | 取值 | 作用 |
+//! |---|---|---|
+//! | `ULL_CONTENT_KIND` | `modpack` / `mod` / `resourcepack` / `shader` | 选内容类型（默认 `mod`） |
+//! | `ULL_CONTENT_STATE` | `ok` / `empty` / `incompatible` | 选状态（默认 `ok`） |
+//!
+//! 只影响本来就用演示数据的 harness 路径；产品二进制里 `demo()` 根本不会被调用。
+
+use unlucky_i18n::{Catalog, Lang};
+use unlucky_presenter::dto::{ContentHit, ContentKind, ContentSort, ContentSource, LoaderKind};
+
+use super::model::{blockers_of, Content, ContentQueryView, Hit, HitFacts, Status, Target};
+use crate::pages::download::Download;
+
+/// 一个固定的演示环境：两个实例（一个 Fabric / 一个 Forge）。
+fn targets() -> Vec<Target> {
+    vec![
+        Target {
+            id: "survival".to_string(),
+            name: "Survival".to_string(),
+            mc_version: "1.20.1".to_string(),
+            loader: LoaderKind::Fabric,
+        },
+        Target {
+            id: "modded".to_string(),
+            name: "Modded".to_string(),
+            mc_version: "1.21.1".to_string(),
+            loader: LoaderKind::Forge,
+        },
+    ]
+}
+
+/// 四条命中项：**先造 `ContentHit` 再走 `Hit::of`**，保证演示数据与产品路径逐字段同源
+/// （自己拼 `Hit` 的那一版会把「1,200,000 下载量」「Fabric 首字母大写」这类格式化漂开）。
+fn hits(kind: ContentKind, catalog: Catalog, compatible_only: bool) -> Vec<Hit> {
+    let rows: &[(&str, &str, &str)] = match kind {
+        ContentKind::Modpack => &[
+            (
+                "Fabulously Optimized",
+                "robotkoer",
+                "Performance-focused vanilla+ pack",
+            ),
+            ("Adrenaline", "Someone", "Lightweight kitchen-sink pack"),
+            ("Better MC", "Luna", "Adventure pack with quests"),
+            ("All the Mods 9", "ATMTeam", "Kitchen sink, 400+ mods"),
+        ],
+        ContentKind::Mod => &[
+            ("Sodium", "jellysquid3", "Modern rendering engine"),
+            ("Lithium", "jellysquid3", "Game logic optimizations"),
+            ("Iris Shaders", "coderbot", "Shader support for Fabric"),
+            ("JEI", "mezz", "Item and recipe viewer"),
+        ],
+        ContentKind::Resourcepack => &[
+            (
+                "Faithful 32x",
+                "Faithful",
+                "Double resolution vanilla textures",
+            ),
+            ("Stay True", "Fred", "Warm, hand-drawn look"),
+            ("Classic 3D", "Someone", "3D blocks and items"),
+            ("Bare Bones", "Someone", "Flat, minimalist textures"),
+        ],
+        ContentKind::Shader => &[
+            ("Complementary Reimagined", "Emin", "Balanced, high quality"),
+            ("BSL Shaders", "capttatsu", "Soft colors, strong weather"),
+            ("Photon", "SixthSurge", "Path-traced look"),
+            ("MakeUp Ultra Fast", "Someone", "Lightweight shader"),
+        ],
+    };
+
+    rows.iter()
+        .enumerate()
+        .map(|(index, (title, author, summary))| {
+            // 前两条只支持 1.20.1 + Fabric（能装进 Survival）；后两条是 1.21.1 + Forge
+            let compatible = compatible_only || index < 2;
+            Hit::of(
+                &ContentHit {
+                    id: format!("{}-{index}", kind.slug()),
+                    slug: format!("{}-{index}", kind.slug()),
+                    title: (*title).to_string(),
+                    summary: (*summary).to_string(),
+                    author: (*author).to_string(),
+                    downloads: 1_200_000u64.saturating_sub(index as u64 * 111_111),
+                    updated: format!("2026-0{}-1{index}", index + 1),
+                    source: if index % 2 == 0 {
+                        ContentSource::Modrinth
+                    } else {
+                        ContentSource::Curseforge
+                    },
+                    game_versions: if compatible {
+                        vec!["1.20.1".to_string()]
+                    } else {
+                        vec!["1.21.1".to_string()]
+                    },
+                    loaders: if compatible {
+                        vec!["fabric".to_string()]
+                    } else {
+                        vec!["forge".to_string()]
+                    },
+                    icon: None,
+                },
+                catalog,
+            )
+        })
+        .collect()
+}
+
+/// 装入中的面板（**复用下载页那块**：`pages::download::install_panel_model` + `install_panel`）。
+fn install_panel(catalog: Catalog) -> Download {
+    use unlucky_presenter::dto::{InstallProgressView, InstallStage};
+    let progress = InstallProgressView {
+        version: "Sodium".to_string(),
+        instance: "survival".to_string(),
+        loader: "Fabric".to_string(),
+        stage: InstallStage::Downloading,
+        files_done: 0,
+        files_total: 1,
+        message: "sodium-fabric-0.6.0.jar".to_string(),
+        ..InstallProgressView::new()
+    };
+    crate::pages::download::install_panel_model(&progress, catalog)
+        .expect("演示数据的进度是「下载中」，面板必然存在")
+}
+
+/// 内建模型（默认 `ok` + 从环境变量读类型/状态）。
+pub(super) fn demo(fallback_kind: ContentKind, lang: Lang) -> Content {
+    let catalog = lang.catalog();
+    let kind = std::env::var("ULL_CONTENT_KIND")
+        .ok()
+        .and_then(|value| {
+            ContentKind::ALL
+                .into_iter()
+                .find(|item| item.slug() == value.trim())
+        })
+        .unwrap_or(fallback_kind);
+    let state = std::env::var("ULL_CONTENT_STATE").unwrap_or_else(|_| "ok".to_string());
+
+    let targets = targets();
+    let target = Some("survival".to_string());
+    let empty = state == "empty";
+    // 「装入中」那一屏：面板就是下载页那块（同一个函数），用来证明它在内容库语义下也可读
+    let installing = state == "install";
+    let list = if empty {
+        Vec::new()
+    } else {
+        hits(kind, catalog, state != "incompatible")
+    };
+    // 「不兼容」那一屏：选中的那条是 1.21.1 + Forge 的项目，而目标是 1.20.1 + Fabric
+    // 「CF 未接通」那一屏：选中的那条来自 CurseForge（文件端点还没接，按钮必须禁用）
+    let selected_index = match state.as_str() {
+        "incompatible" => 2,
+        "cf" => 1,
+        _ => 0,
+    };
+    let selected = list.get(selected_index).map(|hit| hit.id.clone());
+    let blockers = blockers_of(
+        list.get(selected_index).map(|hit| HitFacts {
+            versions: hit.versions.as_slice(),
+            loaders: hit.loaders.as_slice(),
+            source: hit.source,
+        }),
+        kind,
+        &targets,
+        target.as_deref(),
+    );
+    let target_label = targets
+        .iter()
+        .find(|item| Some(&item.id) == target.as_ref())
+        .map(|item| item.label());
+
+    // M113: import/export —— 导入导出区自己那一态由 `ULL_CONTENT_PACK` 选
+    // （`importing` / `partial` / `conflict` / `export`；不设 = 只有入口）
+    let pack = super::packui::demo_pack(lang).0;
+
+    Content {
+        kind,
+        query: ContentQueryView {
+            source: ContentSource::Modrinth,
+            sort: ContentSort::Relevance,
+            version: Some("1.20.1".to_string()),
+            loader: Some(LoaderKind::Fabric),
+            text: if empty {
+                "quarkonium".to_string()
+            } else {
+                String::new()
+            },
+        },
+        hits: list,
+        selected,
+        status: if empty { Status::Empty } else { Status::Ready },
+        total: if empty { 0 } else { 1_284 },
+        // 演示数据故意把 `has_more` 置真（真实判据是「本页装满」）：出图要能看到「加载更多」
+        has_more: !empty,
+        curseforge: false,
+        targets,
+        target: target.clone(),
+        target_label,
+        blockers,
+        panel: if installing {
+            Some(install_panel(catalog))
+        } else {
+            None
+        },
+        versions: vec!["1.20.1".to_string(), "1.21.1".to_string()],
+        draft: if empty {
+            "quarkonium".to_string()
+        } else {
+            String::new()
+        },
+        pack,
+    }
+}
diff --git a/crates/app-iced/src/pages/content/layout.rs b/crates/app-iced/src/pages/content/layout.rs
new file mode 100644
index 0000000..b2a253a
--- /dev/null
+++ b/crates/app-iced/src/pages/content/layout.rs
@@ -0,0 +1,194 @@
+//! 内容库页的栏几何（纯函数 + 数值表）。
+//!
+//! ## 为什么这一页自带一份几何
+//!
+//! 任务书要求「与 M107 同一套视觉语言」：类型栏 140 / 图标栏 64、间距 24、列表列下限 424
+//! （行宽红线）、详情 320。M107 的那份几何在 `pages/layout/rails.rs`（M107 分支，尚未并入 main），
+//! 本 mission 的分支基于 main，所以这里按**同一组数值**先落一份，并在报告里登记
+//! 「M107 合并后应改为复用 `pages/layout/rails.rs`，删掉本文件」。
+//!
+//! ## 四档的判据是**算出来的**，不是拍的
+//!
+//! | 档 | 条件（可用宽，已扣导航轨与页边距） | 版面 |
+//! |---|---|---|
+//! | `Wide` | ≥ 140 + 24 + 424 + 24 + 320 = **932** | 标签栏 + 列表 + 详情 |
+//! | `Narrow` | ≥ 64 + 24 + 424 + 24 + 320 = **856**（类型栏收成图标栏） | 图标栏 + 列表 + 详情 |
+//! | `Compact` | ≥ 140 + 24 + 424 = **588** | 标签栏 + 单列（详情整页替换列表） |
+//! | `Tight` | 其余 | 类型条变成顶部一行 chip + 单列 |
+//!
+//! 三个门槛都是「Σ栏宽 + 间距」算出来的，改动任何一档都会让数值表用例红。
+
+use unlucky_design::spacing::Space;
+
+use crate::pages::layout;
+
+/// 类型栏宽（标签形态）。
+///
+/// M107 的版本类型栏是 140；这里取 200：四个**内容类型**的名字（`Resource packs`）比
+/// 版本类型（`Release` / `Snapshot`）长，140 会把标签切掉。登记在 `pages/content.rs` 的偏离表。
+pub const RAIL_LABEL: f32 = 200.0;
+/// 类型栏宽（图标形态）。
+pub const RAIL_ICON: f32 = 64.0;
+/// 详情面板宽。
+pub const DETAIL: f32 = 320.0;
+/// 栏间距（`Space::X6` = 24，与 `pages::layout::PANES_GAP` 同源）。
+pub const GAP: f32 = Space::X6.dp();
+
+/// 一屏三栏各自多宽。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Rails {
+    /// 档位
+    pub tier: Tier,
+    /// 类型栏宽（`Tight` 档是 0：类型条在顶部）
+    pub rail: f32,
+    /// 列表列宽
+    pub list: f32,
+    /// 详情面板宽（0 = 这一档没有独立详情列）
+    pub detail: f32,
+    /// 栏间距
+    pub gap: f32,
+}
+
+/// 版面档位。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Tier {
+    /// 标签栏 + 列表 + 详情
+    Wide,
+    /// 图标栏 + 列表 + 详情
+    Narrow,
+    /// 标签栏 + 单列
+    Compact,
+    /// 顶部 chip 条 + 单列
+    Tight,
+}
+
+impl Tier {
+    /// 这一档有独立详情列吗。
+    pub const fn has_detail(self) -> bool {
+        matches!(self, Self::Wide | Self::Narrow)
+    }
+
+    /// 这一档的类型栏是标签形态吗（`Tight` 没有栏）。
+    pub const fn rail_has_labels(self) -> bool {
+        matches!(self, Self::Wide | Self::Compact)
+    }
+}
+
+/// `Wide` 的门槛：标签栏 + 间距 + 列表下限 + 间距 + 详情。
+pub fn wide_min() -> f32 {
+    RAIL_LABEL + GAP + layout::LINE_SAFE_WIDTH_PX + GAP + DETAIL
+}
+
+/// `Narrow` 的门槛：图标栏 + 间距 + 列表下限 + 间距 + 详情。
+pub fn narrow_min() -> f32 {
+    RAIL_ICON + GAP + layout::LINE_SAFE_WIDTH_PX + GAP + DETAIL
+}
+
+/// `Compact` 的门槛：标签栏 + 间距 + 列表下限。
+pub fn compact_min() -> f32 {
+    RAIL_LABEL + GAP + layout::LINE_SAFE_WIDTH_PX
+}
+
+/// 可用宽 → 三栏几何。
+pub fn resolve(available: f32) -> Rails {
+    let cap = layout::measure_cap_px();
+
+    if available >= wide_min() {
+        let rail = RAIL_LABEL;
+        return Rails {
+            tier: Tier::Wide,
+            rail,
+            gap: GAP,
+            detail: DETAIL,
+            list: (available - rail - GAP - DETAIL - GAP).max(layout::LINE_SAFE_WIDTH_PX),
+        };
+    }
+    if available >= narrow_min() {
+        let rail = RAIL_ICON;
+        return Rails {
+            tier: Tier::Narrow,
+            rail,
+            gap: GAP,
+            detail: DETAIL,
+            list: (available - rail - GAP - DETAIL - GAP).max(layout::LINE_SAFE_WIDTH_PX),
+        };
+    }
+    if available >= compact_min() {
+        let rail = RAIL_LABEL;
+        return Rails {
+            tier: Tier::Compact,
+            rail,
+            gap: GAP,
+            detail: 0.0,
+            list: (available - rail - GAP).min(cap.max(layout::LINE_SAFE_WIDTH_PX)),
+        };
+    }
+    Rails {
+        tier: Tier::Tight,
+        rail: 0.0,
+        gap: GAP,
+        detail: 0.0,
+        list: available.min(cap.max(layout::LINE_SAFE_WIDTH_PX)),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// 门槛必须由「Σ栏宽 + 间距」算出来（抓得住：谁把 932 抄成 900 这种拍值）。
+    #[test]
+    fn the_three_thresholds_are_sums_not_magic_numbers() {
+        assert_eq!(wide_min(), 200.0 + 24.0 + 424.0 + 24.0 + 320.0);
+        assert_eq!(narrow_min(), 64.0 + 24.0 + 424.0 + 24.0 + 320.0);
+        assert_eq!(compact_min(), 200.0 + 24.0 + 424.0);
+        assert_eq!(wide_min(), 992.0);
+        assert_eq!(narrow_min(), 856.0);
+        assert_eq!(compact_min(), 648.0);
+    }
+
+    #[test]
+    fn each_tier_takes_effect_at_its_own_threshold() {
+        assert_eq!(resolve(wide_min()).tier, Tier::Wide);
+        assert_eq!(resolve(wide_min() - 0.5).tier, Tier::Narrow);
+        assert_eq!(resolve(narrow_min()).tier, Tier::Narrow);
+        assert_eq!(resolve(narrow_min() - 0.5).tier, Tier::Compact);
+        assert_eq!(resolve(compact_min()).tier, Tier::Compact);
+        assert_eq!(resolve(compact_min() - 0.5).tier, Tier::Tight);
+    }
+
+    #[test]
+    fn a_wide_page_never_gives_the_list_less_than_the_row_width_red_line() {
+        // 1180 窗宽（右栗收起）：1044 可用 → Wide，列表 536
+        let rails = resolve(1044.0);
+        assert_eq!(rails.tier, Tier::Wide);
+        assert!(rails.list >= layout::LINE_SAFE_WIDTH_PX, "{}", rails.list);
+        // 逐档扫一遍：只要还有独立列表列，就不许低于 424（行宽红线）
+        for available in 500..=1600 {
+            let rails = resolve(available as f32);
+            if rails.rail > 0.0 {
+                assert!(
+                    rails.list >= layout::LINE_SAFE_WIDTH_PX,
+                    "available={available} 时列表只剩 {}",
+                    rails.list
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn the_detail_column_only_exists_in_the_two_wide_tiers() {
+        assert!(Tier::Wide.has_detail());
+        assert!(Tier::Narrow.has_detail());
+        assert!(!Tier::Compact.has_detail());
+        assert!(!Tier::Tight.has_detail());
+        assert_eq!(resolve(1200.0).detail, DETAIL);
+        assert_eq!(resolve(700.0).detail, 0.0);
+        // 图标形态只在这两档出现，且窄档的标签栏不存在
+        assert_eq!(resolve(900.0).rail, RAIL_ICON);
+        assert_eq!(resolve(700.0).rail, RAIL_LABEL);
+        assert_eq!(resolve(400.0).rail, 0.0);
+        assert!(Tier::Wide.rail_has_labels());
+        assert!(!Tier::Narrow.rail_has_labels());
+    }
+}
diff --git a/crates/app-iced/src/pages/content/message.rs b/crates/app-iced/src/pages/content/message.rs
new file mode 100644
index 0000000..a5e9286
--- /dev/null
+++ b/crates/app-iced/src/pages/content/message.rs
@@ -0,0 +1,42 @@
+//! 内容库页的**自有**消息（M109）。
+//!
+//! 与设置页同一个范式（`pages/settings/message.rs` + `pages::Message::Settings`）：页面自己的一套
+//! 意图在这个文件里声明，`pages::Message` 只留一个 `Content(..)` 投递口，于是「加一条内容库消息」
+//! 不碰共享枚举的正文，也不碰 `app/update/page_messages.rs` 那条不许 `_ =>` 的 match。
+//!
+//! **一条纪律**：这里的每个变体都是**意图**，不是状态变更。改了条件 ≠ 已经发请求
+//! （`QueryChanged` 只改输入框里的字，`Search` 才发指令）；点了「装入」≠ 已装上
+//! （装上的证据是 `InstallProgress` 事件回流到面板）。
+
+use unlucky_presenter::dto::{ContentKind, ContentSort, ContentSource, LoaderKind};
+
+/// 内容库页的消息。
+#[derive(Debug, Clone)]
+pub enum Message {
+    /// 换内容类型（左侧四条一级侧栏）
+    SetKind(ContentKind),
+    /// 关键词输入框变了（**只改草稿**，不 dispatch）
+    QueryChanged(String),
+    /// 提交搜索（零偏移重来）
+    Search,
+    /// 换来源（Modrinth / CurseForge）
+    SetSource(ContentSource),
+    /// 换排序
+    SetSort(ContentSort),
+    /// 换游戏版本过滤（`None` = 不限）
+    SetVersion(Option<String>),
+    /// 换加载器过滤（`None` = 不限）
+    SetLoader(Option<LoaderKind>),
+    /// 选中一个项目（**页面内选中**，不 dispatch）
+    Select(String),
+    /// 选目标实例（一键装入的对象）
+    SetTarget(String),
+    /// 加载下一页
+    LoadMore,
+    /// 同条件重试（失败态的出口）
+    Retry,
+    /// 装进目标实例
+    Install,
+    /// 导入/导出区（M113：整合包导入与导出；一切细节在 `packui::Message`）
+    Pack(super::packui::PackMessage),
+}
diff --git a/crates/app-iced/src/pages/content/model.rs b/crates/app-iced/src/pages/content/model.rs
new file mode 100644
index 0000000..f9f9199
--- /dev/null
+++ b/crates/app-iced/src/pages/content/model.rs
@@ -0,0 +1,301 @@
+//! 内容库页的视图模型：**presenter 快照 + 页面选中项 → 要画的东西**。
+//!
+//! ## 分层（与实例页 / 下载页同一条）
+//!
+//! | 数据源 | 谁转 | 用途 |
+//! |---|---|---|
+//! | `AppState::content`（检索条件 + 结果 + 请求态） | [`Content::from_snapshot`] | 产品运行时的真页面 |
+//! | [`super::demo`] 的固定夹具 | 同上 | `pages_demo` 出图与单测 |
+//!
+//! ## 「点之前就知道装不装得上」（任务书第 3 条）
+//!
+//! 兼容性判定在 [`Content::blockers`]：**纯函数**，输入是「选中的项目 + 目标实例」，
+//! 输出是 [`Blocker`] 列表。视图拿它决定按钮 `disabled` 与旁边那几句原因——于是「点完才报错」
+//! 在结构上不可能发生（按钮根本发不出消息）。
+//!
+//! 两条判据各自独立、**都能同时成立**（版本对不上 + 加载器也不对）：把两条合成一条会在
+//! 「都不兼容」时只说一半原因。
+//!
+//! ## 为什么要 `PageState`（页面自留的那点状态）
+//!
+//! `kind` / `selected` / `target` / `draft` 都是**页面内**的选择：检索条件与结果在 presenter
+//! （`AppState::content`），这四样是「用户在这一屏上点了什么」，重建快照不该把它们冲掉。
+//! 它们的所有者是 `app/state.rs` 的 `App::content`，本文件只借用。
+
+use unlucky_presenter::dto::{
+    loader_facet, ContentKind, ContentSort, ContentSource, ContentState, LoaderKind,
+};
+use unlucky_presenter::state::AppState;
+
+use unlucky_i18n::Catalog;
+
+use crate::pages::download::Download;
+
+mod items;
+
+pub(crate) use items::HitFacts;
+pub(crate) use items::{capitalize, thousands};
+pub use items::{loader_name, Blocker, Hit, PageState, Status, Target};
+
+/// 内容库页要画的东西。
+#[derive(Debug, Clone, PartialEq)]
+pub struct Content {
+    /// 当前内容类型（左栏四条侧栏的选中项）
+    pub kind: ContentKind,
+    /// 当前检索条件（筛选条 + 分页游标）
+    pub query: ContentQueryView,
+    /// 命中项
+    pub hits: Vec<Hit>,
+    /// 选中项
+    pub selected: Option<String>,
+    /// 当前状态
+    pub status: Status,
+    /// 命中总数（`0` = 站点没给）
+    pub total: u32,
+    /// 还有下一页
+    pub has_more: bool,
+    /// CurseForge 源可用（缺 key 时筛选条里那条禁用并说明）
+    pub curseforge: bool,
+    /// 目标实例候选
+    pub targets: Vec<Target>,
+    /// 选中的目标实例
+    pub target: Option<String>,
+    /// 选中目标实例的可读标签（详情面板「装入到 …」）
+    pub target_label: Option<String>,
+    /// 装入不上的原因（空 = 可以装）
+    pub blockers: Vec<Blocker>,
+    /// 安装面板的视图模型（**复用下载页那块**：`pages::download::install_panel`）
+    ///
+    /// 存整个 `Download` 而不是只存一帧视图：面板的入参就是 `&Download`，而 iced 的控件树
+    /// 借用它 ⇒ 被借的东西必须活得比这一帧长（局部临时值不行）。
+    pub panel: Option<Download>,
+    /// 游戏版本筛选的候选（来自实例；去重、保持实例顺序）
+    pub versions: Vec<String>,
+    /// 关键词草稿
+    pub draft: String,
+    /// 导入/导出区（M113）：入口 + 进度 + 结果 + 导出预检
+    pub pack: super::packui::Pack,
+}
+
+/// 筛选条的展示态（数字/枚举都在这里，页面不再从 `ContentQuery` 里挖字段）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ContentQueryView {
+    /// 来源
+    pub source: ContentSource,
+    /// 排序
+    pub sort: ContentSort,
+    /// 游戏版本过滤
+    pub version: Option<String>,
+    /// 加载器过滤
+    pub loader: Option<LoaderKind>,
+    /// 已提交的关键词（输入框显示的是 `draft`）
+    pub text: String,
+}
+
+impl Content {
+    /// presenter 快照 + 页面选中项 → 视图模型（**唯一的真数据入口**）。
+    pub fn from_snapshot(state: &AppState, page: &PageState, catalog: Catalog) -> Self {
+        let content: &ContentState = &state.content;
+        let hits: Vec<Hit> = content
+            .results
+            .as_ref()
+            .map(|results| {
+                results
+                    .hits
+                    .iter()
+                    .map(|hit| Hit::of(hit, catalog))
+                    .collect()
+            })
+            .unwrap_or_default();
+
+        let status = status_of(content, &hits);
+        let targets: Vec<Target> = state.instances.iter().map(Target::of).collect();
+        let target = page
+            .target
+            .clone()
+            .filter(|id| targets.iter().any(|target| &target.id == id))
+            .or_else(|| targets.first().map(|target| target.id.clone()));
+        let target_label = target
+            .as_deref()
+            .and_then(|id| targets.iter().find(|item| item.id == id))
+            .map(Target::label);
+
+        let mut versions: Vec<String> = Vec::new();
+        for instance in &targets {
+            if !versions.iter().any(|item| item == &instance.mc_version) {
+                versions.push(instance.mc_version.clone());
+            }
+        }
+
+        let selected_hit = page.selected.as_deref().and_then(|id| {
+            content
+                .results
+                .as_ref()?
+                .hits
+                .iter()
+                .find(|hit| hit.id == id)
+        });
+        let blockers = blockers_of(
+            selected_hit.map(|hit| HitFacts {
+                versions: hit.game_versions.as_slice(),
+                loaders: hit.loaders.as_slice(),
+                source: hit.source,
+            }),
+            page.kind,
+            &targets,
+            target.as_deref(),
+        );
+
+        // M113: import/export —— 进度/报告/预检在 presenter（`AppState.pack`），
+        // 页内选择在 `page.pack`。`targets` 下面会被移动进结构体，所以这里先借用它建视图模型。
+        let pack = super::packui::Pack::of(
+            &state.pack.import,
+            &state.pack.export,
+            &page.pack,
+            &targets,
+            catalog,
+        );
+
+        Self {
+            kind: page.kind,
+            query: ContentQueryView {
+                source: content.query.source,
+                sort: content.query.sort,
+                version: content.query.game_version.clone(),
+                loader: content.query.loader,
+                text: content.query.text.clone(),
+            },
+            hits,
+            selected: page.selected.clone(),
+            status,
+            total: content.results.as_ref().map_or(0, |results| results.total),
+            // 读「最近一页是否装满」（不是累计条数）：见 `ContentState::last_page_filled` 的文档
+            has_more: content.last_page_filled && !content.pending,
+            curseforge: content
+                .results
+                .as_ref()
+                .is_some_and(|results| results.curseforge),
+            targets,
+            target: target.clone(),
+            target_label,
+            blockers,
+            panel: content_install(state, catalog),
+            versions,
+            draft: page.draft.clone(),
+            pack,
+        }
+    }
+
+    /// 选中项在命中列表里的那一行（详情面板读它）。
+    pub fn selected_hit(&self) -> Option<&Hit> {
+        let id = self.selected.as_deref()?;
+        self.hits.iter().find(|hit| hit.id == id)
+    }
+
+    /// 「装入」按钮此刻能不能按（`false` 时按钮禁用，`blockers()` 给原因）。
+    pub fn can_install(&self) -> bool {
+        self.selected_hit().is_some() && self.blockers.is_empty()
+    }
+
+    /// 原因的人读文案（顺序 = 判定顺序；空 = 没有原因）。
+    pub fn blocker_reasons(&self, catalog: Catalog) -> Vec<String> {
+        self.blockers
+            .iter()
+            .map(|blocker| blocker.reason(catalog))
+            .collect()
+    }
+
+    /// 加载中（首屏 / 换条件）。
+    pub const fn is_loading(&self) -> bool {
+        matches!(self.status, Status::Loading)
+    }
+}
+
+/// 快照 → 四态。判据只有三个字段（请求在飞 / 失败原因 / 命中项），没有第四份真相。
+fn status_of(content: &ContentState, hits: &[Hit]) -> Status {
+    if let Some(reason) = &content.failed {
+        return Status::Failed(reason.clone());
+    }
+    if content.pending || content.results.is_none() {
+        return Status::Loading;
+    }
+    if hits.is_empty() {
+        Status::Empty
+    } else {
+        Status::Ready
+    }
+}
+
+/// 安装面板（**只借用下载页那块面板**，不另写一套画法）。
+///
+/// 转换与「成功/取消这类终态不占面板」的判断都在 `pages::download::install_panel_model` 里
+/// （M105 起 `InstallView` 不再从那个模块导出）：内容库只拿 `Option<Download>`。
+fn content_install(state: &AppState, catalog: Catalog) -> Option<Download> {
+    state
+        .install
+        .as_ref()
+        .and_then(|progress| crate::pages::download::install_panel_model(progress, catalog))
+}
+
+/// 兼容性判定（**纯函数**，单测直接钉它；见模块文档第 2 节）。
+///
+/// `hit` 是「选中项的两个支持列表」：`None` = 没选中，`Some((版本, 加载器))` = 选中了。
+/// **空列表 ≠ 不兼容**：站点没给数据时按「未知」处理，不许把「不知道」画成「不支持」。
+pub(super) fn blockers_of(
+    hit: Option<HitFacts<'_>>,
+    kind: ContentKind,
+    targets: &[Target],
+    target: Option<&str>,
+) -> Vec<Blocker> {
+    if targets.is_empty() {
+        return vec![Blocker::NoTarget];
+    }
+    let Some(target) = target.and_then(|id| targets.iter().find(|item| item.id == id)) else {
+        return vec![Blocker::NoTarget];
+    };
+    let mut blockers = Vec::new();
+    // 整合包：不是「兼容不兼容」的问题，是这条路根本没有（导入管线未落地）
+    if kind.dir().is_none() {
+        blockers.push(Blocker::NeedsPipeline);
+    }
+    let Some(facts) = hit else {
+        return blockers;
+    };
+    let (versions, loaders) = (facts.versions, facts.loaders);
+    // 来源的文件端点没通：**必须在点之前**说清楚。放行等于「点完必然失败」（复审 P1-1）。
+    if facts.source == ContentSource::Curseforge {
+        blockers.push(Blocker::SourceNotWired);
+    }
+    if !versions.is_empty() && !versions.iter().any(|item| item == &target.mc_version) {
+        blockers.push(Blocker::Version {
+            needs: join_or_unknown(versions),
+            actual: target.mc_version.clone(),
+        });
+    }
+    let facet = loader_facet(target.loader);
+    if let Some(facet) = facet {
+        if !loaders.is_empty() && !loaders.iter().any(|item| item == facet) {
+            blockers.push(Blocker::Loader {
+                loader: target.loader,
+            });
+        }
+    }
+    blockers
+}
+
+/// 版本列表 → 一行人读串（最多三个，其余用 `…`；空 = 「未知」）。
+fn join_or_unknown(versions: &[String]) -> String {
+    if versions.is_empty() {
+        return "?".to_string();
+    }
+    let shown = versions.iter().take(3).cloned().collect::<Vec<_>>();
+    if versions.len() > shown.len() {
+        format!("{}…", shown.join(", "))
+    } else {
+        shown.join(", ")
+    }
+}
+
+#[cfg(test)]
+#[path = "model/tests.rs"]
+mod tests;
diff --git a/crates/app-iced/src/pages/content/model/items.rs b/crates/app-iced/src/pages/content/model/items.rs
new file mode 100644
index 0000000..7e4be4e
--- /dev/null
+++ b/crates/app-iced/src/pages/content/model/items.rs
@@ -0,0 +1,238 @@
+//! 内容库页的类型：页面自留状态 / 四态 / 展示行 / 目标实例 / 装不上的原因。
+//!
+//! 从 `pages/content/model.rs` 拆出（那个文件已贴 400 行硬上限）。纯数据类型与纯函数，
+//! 不认识 iced：`model/tests.rs` 直接钉它们的判定。
+
+use unlucky_presenter::dto::{ContentHit, ContentKind, ContentSource, InstanceSummary, LoaderKind};
+
+use unlucky_i18n::{Catalog, Key};
+
+/// 页面自留的选择（检索条件与结果在 presenter 的 `AppState::content`）。
+#[derive(Debug, Clone, PartialEq)]
+pub struct PageState {
+    /// 当前内容类型
+    pub kind: ContentKind,
+    /// 选中的项目 id（`None` = 没选 → 详情面板空态）
+    pub selected: Option<String>,
+    /// 目标实例 id（`None` = 没选 → 装入按钮禁用并说明）
+    pub target: Option<String>,
+    /// 关键词输入框里的草稿（**未提交**；提交后才进 `AppState::content.query`）
+    pub draft: String,
+    /// 导入/导出区的页内选择（M113：路径草稿 / 目标实例 / 格式 / 展开的那条冲突）
+    pub pack: super::super::packui::PackPageState,
+}
+
+impl Default for PageState {
+    fn default() -> Self {
+        Self {
+            kind: ContentKind::Mod,
+            selected: None,
+            target: None,
+            draft: String::new(),
+            pack: super::super::packui::PackPageState::default(),
+        }
+    }
+}
+
+/// 页面此刻画哪一态（四态 + 分页尾）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Status {
+    /// 加载中（首屏 / 换条件 / 换页）
+    Loading,
+    /// 有命中项
+    Ready,
+    /// 拉到了但一条都没有
+    Empty,
+    /// 失败（带一句人读原因）
+    Failed(String),
+}
+
+impl Status {
+    /// 失败了吗（视图用它决定画错误面板还是列表）。
+    pub const fn failed(&self) -> bool {
+        matches!(self, Self::Failed(_))
+    }
+}
+
+/// 一条命中项的展示态（文案在这一层求好：iced 的文本控件借用内容）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Hit {
+    /// 项目 id（选中 / 装入指令的载荷）
+    pub id: String,
+    /// 标题
+    pub title: String,
+    /// 一行说明
+    pub summary: String,
+    /// 来源 + 作者（`Modrinth · jelly`）
+    pub supporting: String,
+    /// 下载量（已加千分位）
+    pub downloads: String,
+    /// 更新日期的人读串
+    pub updated: String,
+    /// 支持的游戏版本（详情面板用；空 = 站点没给）
+    pub versions: Vec<String>,
+    /// 支持的加载器（**站点原样的小写 facet**：兼容性判定要用它跟 `loader_facet` 比）
+    pub loaders: Vec<String>,
+    /// 来源（行上标来源徽标）
+    pub source: ContentSource,
+}
+
+impl Hit {
+    /// 命中项 DTO → 展示态（**演示数据也走这条**，于是 fixture 与产品路径逐字段同源）。
+    pub(crate) fn of(hit: &ContentHit, catalog: Catalog) -> Self {
+        let source = match hit.source {
+            ContentSource::Modrinth => catalog.text(Key::ContentSourceModrinth),
+            ContentSource::Curseforge => catalog.text(Key::ContentSourceCurseforge),
+        };
+        let supporting = if hit.author.is_empty() {
+            source.to_string()
+        } else {
+            format!("{source} · {}", hit.author)
+        };
+        Self {
+            id: hit.id.clone(),
+            title: hit.title.clone(),
+            summary: hit.summary.clone(),
+            supporting,
+            downloads: catalog.render(
+                Key::ContentDetailDownloads,
+                &[("count", &thousands(hit.downloads))],
+            ),
+            updated: catalog.render(Key::ContentDetailUpdated, &[("date", &hit.updated)]),
+            versions: hit.game_versions.clone(),
+            loaders: hit.loaders.clone(),
+            source: hit.source,
+        }
+    }
+}
+
+/// 目标实例（一键装入的对象）的展示态。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Target {
+    /// 实例 id
+    pub id: String,
+    /// 显示名
+    pub name: String,
+    /// 游戏版本
+    pub mc_version: String,
+    /// 加载器
+    pub loader: LoaderKind,
+}
+
+impl Target {
+    pub(super) fn of(instance: &InstanceSummary) -> Self {
+        Self {
+            id: instance.id.clone(),
+            name: instance.name.clone(),
+            mc_version: instance.mc_version.clone(),
+            loader: instance.loader.kind,
+        }
+    }
+
+    /// 详情里那一行（`Survival · 1.20.4 · Fabric`）。
+    pub(crate) fn label(&self) -> String {
+        format!(
+            "{} · {} · {}",
+            self.name,
+            self.mc_version,
+            loader_name(self.loader)
+        )
+    }
+}
+
+/// 下载量加千分位（`1200000` → `1,200,000`）：raw 数字在详情面板上读不出量级。
+pub(crate) fn thousands(value: u64) -> String {
+    let digits = value.to_string();
+    let mut out = String::with_capacity(digits.len() + digits.len() / 3);
+    for (index, ch) in digits.chars().enumerate() {
+        if index > 0 && (digits.len() - index).is_multiple_of(3) {
+            out.push(',');
+        }
+        out.push(ch);
+    }
+    out
+}
+
+/// 首字母大写（`fabric` → `Fabric`；空串原样）。
+///
+/// **只在画的时候用**：`Hit::loaders` 与兼容性判定都保持站点原样的小写 facet，
+/// 否则「Fabric」与 facet「fabric」一比就成了不兼容（本轮踩过）。
+pub(crate) fn capitalize(raw: &str) -> String {
+    let mut chars = raw.chars();
+    match chars.next() {
+        Some(first) => first.to_uppercase().collect::<String>() + chars.as_str(),
+        None => String::new(),
+    }
+}
+
+/// 加载器的**界面名**（ASCII）。
+///
+/// 不复用 `LoaderKind::label()`：它对原版返回「原版」——中文业务串，而本仓的界面文案在 i18n
+/// 之前是英文基线（干净 CI 上没有中文字体，见 `pages/instances/data.rs` 的同一条理由）。
+pub const fn loader_name(loader: LoaderKind) -> &'static str {
+    match loader {
+        LoaderKind::Vanilla => "Vanilla",
+        LoaderKind::Fabric => "Fabric",
+        LoaderKind::Quilt => "Quilt",
+        LoaderKind::Forge => "Forge",
+        LoaderKind::NeoForge => "NeoForge",
+        LoaderKind::OptiFine => "OptiFine",
+        LoaderKind::LiteLoader => "LiteLoader",
+    }
+}
+
+/// 选中项的**判定事实**（版本 / 加载器 / 来源）。
+///
+/// 为什么另起一个结构：兼容性判据随着「宿主接通了什么」在长（M109 加了来源），
+/// 每次加一条都改一次 `blockers_of` 的形参列表，而调用点有两处（产品路径与演示数据）。
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct HitFacts<'a> {
+    /// 支持的游戏版本（空 = 站点没给）
+    pub versions: &'a [String],
+    /// 支持的加载器（空 = 站点没给；**站点原样的小写 facet**）
+    pub loaders: &'a [String],
+    /// 来源（决定「文件端点通没通」）
+    pub source: ContentSource,
+}
+
+/// 装不上的原因（**一条一个原因**，可以有多条同时成立）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Blocker {
+    /// 整包类内容不走「单文件进目录」这条路（导入管线还没落地）
+    NeedsPipeline,
+    /// 这个来源的**文件端点**还没接通（检索通了、拿到下载地址那一跳没通）
+    SourceNotWired,
+    /// 项目不支持目标实例的游戏版本
+    Version {
+        /// 项目支持的游戏版本（人读，最多取三个）
+        needs: String,
+        /// 目标实例的版本
+        actual: String,
+    },
+    /// 项目不支持目标实例的加载器
+    Loader {
+        /// 目标实例的加载器
+        loader: LoaderKind,
+    },
+    /// 没有目标实例
+    NoTarget,
+}
+
+impl Blocker {
+    /// 一句话原因（i18n）。
+    pub(super) fn reason(&self, catalog: Catalog) -> String {
+        match self {
+            Self::NeedsPipeline => catalog.text(Key::ContentModpackNotReady).to_string(),
+            Self::Version { needs, actual } => catalog.render(
+                Key::ContentIncompatibleVersion,
+                &[("version", needs), ("actual", actual)],
+            ),
+            Self::Loader { loader } => catalog.render(
+                Key::ContentIncompatibleLoader,
+                &[("loader", loader_name(*loader))],
+            ),
+            Self::SourceNotWired => catalog.text(Key::ContentSourceNotWired).to_string(),
+            Self::NoTarget => catalog.text(Key::ContentNoInstances).to_string(),
+        }
+    }
+}
diff --git a/crates/app-iced/src/pages/content/model/tests.rs b/crates/app-iced/src/pages/content/model/tests.rs
new file mode 100644
index 0000000..b20074b
--- /dev/null
+++ b/crates/app-iced/src/pages/content/model/tests.rs
@@ -0,0 +1,294 @@
+//! 内容库视图模型的守门测试（M109）：四态判定、兼容性判定、装入闸门。
+//!
+//! 全部是纯函数级断言（不开图形环境）：`status_of` / `blockers_of` / `Content::can_install`
+//! 是页面「该画什么、按钮能不能按」的唯一判据，钉住它们比截图更早期。
+
+use super::*;
+use unlucky_i18n::Lang;
+use unlucky_presenter::dto::{
+    ContentHit, ContentKind, ContentQuery, ContentResults, ContentSource, InstanceRuntime,
+    LoaderKind,
+};
+
+fn hit(versions: &[&str], loaders: &[&str]) -> ContentHit {
+    ContentHit {
+        id: "p1".to_string(),
+        slug: "p".to_string(),
+        title: "Sodium".to_string(),
+        summary: "fast".to_string(),
+        author: "jelly".to_string(),
+        downloads: 10,
+        updated: "2026-01-01".to_string(),
+        source: ContentSource::Modrinth,
+        game_versions: versions.iter().map(|item| (*item).to_string()).collect(),
+        loaders: loaders.iter().map(|item| (*item).to_string()).collect(),
+        icon: None,
+    }
+}
+
+fn targets() -> Vec<Target> {
+    vec![
+        Target {
+            id: "fabric-1.20.1".to_string(),
+            name: "Survival".to_string(),
+            mc_version: "1.20.1".to_string(),
+            loader: LoaderKind::Fabric,
+        },
+        Target {
+            id: "forge-1.21.1".to_string(),
+            name: "Modded".to_string(),
+            mc_version: "1.21.1".to_string(),
+            loader: LoaderKind::Forge,
+        },
+    ]
+}
+
+fn blockers_of_hit(hit: &ContentHit, kind: ContentKind, target: Option<&str>) -> Vec<Blocker> {
+    blockers_of(
+        Some(HitFacts {
+            versions: hit.game_versions.as_slice(),
+            loaders: hit.loaders.as_slice(),
+            source: hit.source,
+        }),
+        kind,
+        &targets(),
+        target,
+    )
+}
+
+#[test]
+fn a_matching_project_has_no_blockers() {
+    let hit = hit(&["1.20.1"], &["fabric"]);
+    assert!(blockers_of_hit(&hit, ContentKind::Mod, Some("fabric-1.20.1")).is_empty());
+}
+
+#[test]
+fn a_version_mismatch_is_reported_before_the_user_clicks() {
+    // 抓得住：把「版本对不上」留到点了才报错（任务书第 3 条禁止的正是这个）。
+    let hit = hit(&["1.20.1"], &["fabric"]);
+    let blockers = blockers_of_hit(&hit, ContentKind::Mod, Some("forge-1.21.1"));
+    assert!(blockers.contains(&Blocker::Version {
+        needs: "1.20.1".to_string(),
+        actual: "1.21.1".to_string()
+    }));
+    assert!(blockers.contains(&Blocker::Loader {
+        loader: LoaderKind::Forge
+    }));
+}
+
+#[test]
+fn both_mismatches_are_reported_separately() {
+    // 合成一条会在「都不兼容」时只说一半原因
+    let hit = hit(&["1.20.1"], &["fabric"]);
+    assert_eq!(
+        blockers_of_hit(&hit, ContentKind::Mod, Some("forge-1.21.1")).len(),
+        2
+    );
+}
+
+#[test]
+fn site_data_that_is_missing_never_blocks() {
+    // 站点没给版本/加载器 = 未知，不是「不支持」
+    let hit = hit(&[], &[]);
+    assert!(blockers_of_hit(&hit, ContentKind::Mod, Some("forge-1.21.1")).is_empty());
+}
+
+#[test]
+fn a_curseforge_project_is_blocked_because_its_file_endpoint_is_not_wired() {
+    // 复审 P1-1：检索通了、文件端点没通 ⇒ 必须在**点之前**禁用并说明，
+    // 否则「切到 CF 源后每条都必然失败，UI 一点提示都没有」。
+    let mut cf = hit(&["1.20.1"], &["fabric"]);
+    cf.source = ContentSource::Curseforge;
+    assert_eq!(
+        blockers_of_hit(&cf, ContentKind::Mod, Some("fabric-1.20.1")),
+        vec![Blocker::SourceNotWired]
+    );
+    // 同样的版本/加载器，Modrinth 那条就没有这条原因（否则等于把整页禁死）
+    let modrinth = hit(&["1.20.1"], &["fabric"]);
+    assert!(blockers_of_hit(&modrinth, ContentKind::Mod, Some("fabric-1.20.1")).is_empty());
+}
+
+#[test]
+fn modpacks_are_blocked_by_the_missing_pipeline_not_by_compatibility() {
+    let hit = hit(&["1.20.1"], &["fabric"]);
+    assert_eq!(
+        blockers_of_hit(&hit, ContentKind::Modpack, Some("fabric-1.20.1")),
+        vec![Blocker::NeedsPipeline]
+    );
+    // 资源包 / 光影 / Mod 都没有这一条
+    for kind in [
+        ContentKind::Mod,
+        ContentKind::Resourcepack,
+        ContentKind::Shader,
+    ] {
+        assert!(blockers_of_hit(&hit, kind, Some("fabric-1.20.1")).is_empty());
+    }
+}
+
+#[test]
+fn no_target_instance_disables_the_button_with_a_reason() {
+    assert_eq!(
+        blockers_of(None, ContentKind::Mod, &[], None),
+        vec![Blocker::NoTarget]
+    );
+    // 有实例但选中项不在名单里（被删了）：同样不许静默通过
+    assert_eq!(
+        blockers_of(None, ContentKind::Mod, &targets(), Some("gone")),
+        vec![Blocker::NoTarget]
+    );
+    // 没选中项目：只剩「目标」与「整包」这两类先天原因
+    assert!(blockers_of(None, ContentKind::Mod, &targets(), Some("fabric-1.20.1")).is_empty());
+}
+
+fn state_with(results: Option<ContentResults>, pending: bool) -> AppState {
+    let mut state = AppState::new();
+    state.instances = Vec::new();
+    state.content.pending = pending;
+    state.content.results = results;
+    state
+}
+
+fn results(hits: Vec<ContentHit>, offset: u32) -> ContentResults {
+    let mut query = ContentQuery::first(ContentKind::Mod);
+    query.offset = offset;
+    ContentResults {
+        query,
+        hits,
+        total: 100,
+        curseforge: false,
+    }
+}
+
+#[test]
+fn the_four_states_are_derived_from_three_fields() {
+    let page = PageState::default();
+    let catalog = Lang::En.catalog();
+
+    // 还没有结果 ⇒ 加载
+    let loading = Content::from_snapshot(&state_with(None, false), &page, catalog);
+    assert!(loading.is_loading());
+    assert_eq!(loading.status, Status::Loading);
+
+    // 请求在飞 ⇒ 加载（即使手里还有上一批）
+    let pending = Content::from_snapshot(
+        &state_with(Some(results(vec![hit(&["1.20.1"], &["fabric"])], 0)), true),
+        &page,
+        catalog,
+    );
+    assert_eq!(pending.status, Status::Loading);
+
+    // 拉到了但零命中 ⇒ 空
+    let empty = Content::from_snapshot(
+        &state_with(Some(results(Vec::new(), 0)), false),
+        &page,
+        catalog,
+    );
+    assert_eq!(empty.status, Status::Empty);
+
+    // 有命中 ⇒ 有数据
+    let ready = Content::from_snapshot(
+        &state_with(Some(results(vec![hit(&["1.20.1"], &["fabric"])], 0)), false),
+        &page,
+        catalog,
+    );
+    assert_eq!(ready.status, Status::Ready);
+    assert_eq!(ready.hits.len(), 1);
+    assert_eq!(ready.hits[0].title, "Sodium");
+    assert!(!ready.has_more, "只有 1 条、不够一页 ⇒ 没有下一页");
+}
+
+#[test]
+fn a_failure_outranks_the_loading_state() {
+    let mut state = state_with(None, true);
+    state.content.failed = Some("网络不通".to_string());
+    let model = Content::from_snapshot(&state, &PageState::default(), Lang::En.catalog());
+    assert_eq!(model.status, Status::Failed("网络不通".to_string()));
+    assert!(model.status.failed());
+}
+
+#[test]
+fn can_install_needs_a_selection_and_no_blockers() {
+    let mut state = state_with(Some(results(vec![hit(&["1.20.1"], &["fabric"])], 0)), false);
+    state.instances = vec![unlucky_presenter::dto::InstanceSummary {
+        id: "fabric-1.20.1".to_string(),
+        name: "Survival".to_string(),
+        mc_version: "1.20.1".to_string(),
+        loader: unlucky_presenter::dto::LoaderInfo {
+            kind: LoaderKind::Fabric,
+            version: "0.16.5".to_string(),
+        },
+        last_played: None,
+        runtime: InstanceRuntime::Idle,
+        icon: None,
+        isolation: "isolated".to_string(),
+        version_id: "1.20.1".to_string(),
+        version_present: true,
+    }];
+    let catalog = Lang::En.catalog();
+    let page = PageState {
+        kind: ContentKind::Mod,
+        selected: None,
+        target: None,
+        draft: String::new(),
+        pack: super::super::packui::PackPageState::default(),
+    };
+
+    // 没选中项目 ⇒ 不能装（也不该说「成功」）
+    let no_selection = Content::from_snapshot(&state, &page, catalog);
+    assert!(!no_selection.can_install());
+    assert_eq!(
+        no_selection.target.as_deref(),
+        Some("fabric-1.20.1"),
+        "只有一个实例就默认选它"
+    );
+
+    // 选中兼容项 ⇒ 能装
+    let page = PageState {
+        selected: Some("p1".to_string()),
+        ..page
+    };
+    let compatible = Content::from_snapshot(&state, &page, catalog);
+    assert!(compatible.can_install());
+    assert!(compatible.blocker_reasons(catalog).is_empty());
+    assert!(compatible.target_label.is_some());
+}
+
+#[test]
+fn the_panel_only_shows_while_an_install_is_unfinished() {
+    use unlucky_presenter::dto::{InstallProgressView, InstallStage};
+
+    let mut state = state_with(None, false);
+    state.install = Some(InstallProgressView {
+        version: "Sodium".to_string(),
+        stage: InstallStage::Downloading,
+        files_total: 1,
+        ..InstallProgressView::new()
+    });
+    let running = Content::from_snapshot(&state, &PageState::default(), Lang::En.catalog());
+    assert!(running.panel.is_some(), "下载中要有面板");
+
+    state.install = Some(InstallProgressView {
+        stage: InstallStage::Done,
+        ..InstallProgressView::new()
+    });
+    let done = Content::from_snapshot(&state, &PageState::default(), Lang::En.catalog());
+    assert!(done.panel.is_none(), "装完的面板不该钉在页面上");
+}
+
+#[test]
+fn loader_names_are_ascii_so_the_english_baseline_stays_english() {
+    for loader in [
+        LoaderKind::Vanilla,
+        LoaderKind::Fabric,
+        LoaderKind::Forge,
+        LoaderKind::NeoForge,
+        LoaderKind::Quilt,
+    ] {
+        assert!(loader_name(loader).is_ascii(), "{loader:?}");
+    }
+    assert_eq!(
+        loader_name(LoaderKind::Vanilla),
+        "Vanilla",
+        "不能画「原版」"
+    );
+}
diff --git a/crates/app-iced/src/pages/content/packui.rs b/crates/app-iced/src/pages/content/packui.rs
new file mode 100644
index 0000000..c734909
--- /dev/null
+++ b/crates/app-iced/src/pages/content/packui.rs
@@ -0,0 +1,57 @@
+//! 整合包**导入 / 导出**区（M113 `PACKUI`）：内容库页里「把我的包装进来」与「把我的实例打出去」。
+//!
+//! ## 为什么长在内容库页上
+//!
+//! 用户令：「下载页只负责下载整合包和Mod/光影」+「支持当前主流的整合包格式导入导出的功能」。
+//! 下载页（+内容库）是「拿内容进来」的地方，所以：
+//!
+//! - **导入**（本地包 → 实例）：入口在这里，和「从站点拿整合包」摆在同一页；
+//! - **导出**（实例 → 包）：同一块，选目标实例 + 格式，预检之后再写盘。
+//!
+//! ## 三种格式都是 core 的既有能力，本模块只做界面
+//!
+//! | 格式 | 导入 | 导出 | 界面上的如实说明 |
+//! |---|---|---|---|
+//! | CurseForge `manifest.json` | 是（`files[]` 远程补全**未接通**） | 是 | 缺 CF 客户端 ⇒ 那些条目只能记成「没搞到」，逐条列出，**绝不猜 URL** |
+//! | Modrinth `.mrpack` | 是 | 是 | —— |
+//! | MultiMC / Prism 实例目录 | 是 | **否**（core 有意省略） | 文案明写「只能导入、不能导出」 |
+//!
+//! `.disabled` 是**路径后缀**（不是 `env.client=optional`）——这条在导出预检的逐条原因里出现，
+//! 界面上不解释「可选依赖」，因为那不是同一件事。
+//!
+//! ## 文件分工
+//!
+//! | 文件 | 职责 |
+//! |---|---|
+//! | [`message`] | 本区的意图（挂在 `content::Message::Pack` 下） |
+//! | [`model`] | 视图模型（快照 → 要画的东西；纯决策可单测） |
+//! | [`view`] | 画法（进度**整块**复用下载页的安装面板） |
+//! | `demo` | 出图夹具（`ULL_CONTENT_PACK` 选态） |
+//!
+//! ## 本版明确的边界（报告里同样登记）
+//!
+//! - **没有系统文件选择框**：依赖树里没有 `rfd` 一类的对话框依赖，加它要动根 `Cargo.toml`、
+//!   过许可门禁、还要给 Linux 选后端（GTK / xdg-portal），直接影响「单文件产物」。所以入口是
+//!   **拖拽（真能用）+ 路径输入框**，并且把原因写在界面上（[`model::Pack::no_dialog_note`]）。
+//! - **冲突没有逐文件决策**：core 的 `ConflictPolicy` 是整次导入一个全局档（`KeepUser` 默认 /
+//!   `Overwrite`），`ConflictFile` 是**事后账**。所以这一块给的是「逐文件看 + 整体翻档」，
+//!   文案如实写「两者都留（改名）暂不支持」。逐文件策略已登记为后续 core mission。
+
+mod demo;
+mod message;
+mod model;
+mod view;
+
+#[cfg(test)]
+mod tests;
+
+pub use message::Message as PackMessage;
+pub use model::{request_export, Pack, PackPageState};
+
+/// 区入口（内容库页的正列调它）。
+pub(crate) use view::section;
+
+/// 出图夹具：按 `ULL_CONTENT_PACK` 选态（`importing` / `partial` / `conflict` / `export`）。
+pub(crate) fn demo_pack(lang: unlucky_i18n::Lang) -> (Pack, PackPageState) {
+    demo::pack(lang)
+}
diff --git a/crates/app-iced/src/pages/content/packui/demo.rs b/crates/app-iced/src/pages/content/packui/demo.rs
new file mode 100644
index 0000000..47ad0ea
--- /dev/null
+++ b/crates/app-iced/src/pages/content/packui/demo.rs
@@ -0,0 +1,245 @@
+//! 出图夹具（D30）：`ULL_CONTENT_PACK` 选「同一页的哪一态」。
+//!
+//! ## 为什么是环境变量
+//!
+//! `pages_demo` 的 `--screen=` 只够选到**哪一页**，选不到「同一页的哪一态」；而
+//! `pages/harness.rs` 与 `cli.rs` 不在本 mission 的 scope。所以沿用本仓既有的取证开关范式
+//! （`ULL_START_ROUTE` / `ULL_CONTENT_KIND` / `ULL_CONTENT_STATE`）：
+//!
+//! | 变量 | 取值 | 作用 |
+//! |---|---|---|
+//! | `ULL_CONTENT_PACK` | `importing` / `partial` / `conflict` / `failed` / `export` | 选导入导出区的哪一态（不设 = 只有入口） |
+//!
+//! 夹具**不直接造视图模型**，而是造 presenter 侧的快照（`ImportState` / `ExportState`），
+//! 再走产品路径同一个 [`Pack::of`]。这样截图里看到的每一行字都是产品路径会画的那一行，
+//! 而不是「为了出图另写一套」。
+
+use std::path::PathBuf;
+
+use unlucky_i18n::Lang;
+use unlucky_presenter::dto::{
+    ConflictChoiceView, ConflictFileView, ConflictReasonView, ExportClassView, ExportFileView,
+    ExportPreviewView, ExportReasonView, ExportState, FileActionView, ImportErrorView,
+    ImportProgressView, ImportReportView, ImportStageView, ImportState, ImportStatusView,
+    InstanceId, LoaderKind, MissingFileView, MissingReasonView, PackFormatView,
+};
+
+use crate::pages::content::Target;
+
+use super::model::{Pack, PackPageState};
+
+/// 取证开关名。
+const ENV_PACK: &str = "ULL_CONTENT_PACK";
+
+/// 两个实例（与内容库页的演示环境同一批，避免同一张图上出现两套实例名）。
+fn targets() -> Vec<Target> {
+    vec![
+        Target {
+            id: "survival".to_string(),
+            name: "Survival".to_string(),
+            mc_version: "1.20.1".to_string(),
+            loader: LoaderKind::Fabric,
+        },
+        Target {
+            id: "modded".to_string(),
+            name: "Modded".to_string(),
+            mc_version: "1.21.1".to_string(),
+            loader: LoaderKind::Forge,
+        },
+    ]
+}
+
+/// 按环境变量造一态（不设 = 只有入口，没有进度也没有报告）。
+pub(super) fn pack(lang: Lang) -> (Pack, PackPageState) {
+    let state = std::env::var(ENV_PACK).unwrap_or_default();
+    pack_in(&state, lang)
+}
+
+/// 按名字造一态（单测直接调它，不碰环境变量：并行测试里改 env 是竞态）。
+pub(super) fn pack_in(state: &str, lang: Lang) -> (Pack, PackPageState) {
+    let catalog = lang.catalog();
+    let instance: Option<InstanceId> = Some("survival".to_string());
+    let mut page = PackPageState {
+        instance,
+        ..PackPageState::default()
+    };
+    let mut import = ImportState::default();
+    let mut export = ExportState::default();
+
+    match state {
+        "importing" => import.progress = Some(progress()),
+        "partial" => import.report = Some(report(ImportStatusView::Partial, false)),
+        "conflict" => {
+            import.report = Some(report(ImportStatusView::Partial, true));
+            page.expanded = Some("config/sodium-options.json".to_string());
+        }
+        // 致命态：整包回滚 + 容忍域仍在（展示两类失败的视觉分野）
+        "failed" => {
+            let mut fatal = report(ImportStatusView::Failed, false);
+            fatal.error = Some(ImportErrorView {
+                code: "pack_traversal".to_string(),
+                label: "Path traversal".to_string(),
+                message: "overrides/../../etc/passwd".to_string(),
+                hint: Some("Re-download the pack from its source".to_string()),
+            });
+            fatal.files.clear();
+            fatal.bytes_written = 0;
+            import.report = Some(fatal);
+        }
+        // 取消态：面板收回了，但「后台还在跑」这句话要留在屏上
+        "cancelled" => import.cancelled = true,
+        "export" => {
+            page.export_open = true;
+            page.export_name = "Survival 1.20.1".to_string();
+            export.preview = Some(preview());
+        }
+        _ => {}
+    }
+
+    let model = Pack::of(&import, &export, &page, &targets(), catalog);
+    (model, page)
+}
+
+/// 导入中：第 2 阶段（解包覆盖内容），计数已知。
+fn progress() -> ImportProgressView {
+    ImportProgressView {
+        stage: ImportStageView::Extract,
+        done: 418,
+        total: 640,
+        current: Some("overrides/config/sodium-options.json".to_string()),
+        pack: "Better MC 1.2.0".to_string(),
+    }
+}
+
+/// 一条落地文件。
+fn file(
+    path: &str,
+    action: FileActionView,
+    bytes: u64,
+) -> unlucky_presenter::dto::ImportedFileView {
+    unlucky_presenter::dto::ImportedFileView {
+        path: path.to_string(),
+        action,
+        bytes,
+    }
+}
+
+/// 报告（`conflicts` 决定造不造冲突那一块）。
+fn report(status: ImportStatusView, conflicts: bool) -> ImportReportView {
+    let mut report = ImportReportView {
+        status,
+        format: Some(PackFormatView::Curseforge),
+        pack_name: Some("Better MC".to_string()),
+        pack_version: Some("1.2.0".to_string()),
+        game_version: Some("1.20.1".to_string()),
+        loader: Some("fabric-loader 0.15.11".to_string()),
+        version_id: Some("1.20.1-fabric0.15.11".to_string()),
+        target: PathBuf::from("C:/ULL/instances/survival/.minecraft"),
+        files: vec![
+            file("mods/sodium.jar", FileActionView::Installed, 812_000),
+            file("mods/lithium.jar", FileActionView::Installed, 640_000),
+            file("config/xaeroplus.cfg", FileActionView::KeptUser, 4_200),
+        ],
+        conflicts: Vec::new(),
+        missing: vec![
+            MissingFileView {
+                path: Some("mods/create-1.2.3.jar".to_string()),
+                display: "mods/create-1.2.3.jar".to_string(),
+                reason: MissingReasonView::FetchFailed,
+                detail: "HTTP 404".to_string(),
+            },
+            MissingFileView {
+                path: None,
+                display: "123456:789012".to_string(),
+                reason: MissingReasonView::NoSource,
+                detail: "CurseForge 文件端点未接通".to_string(),
+            },
+            MissingFileView {
+                path: Some("mods/jei-1.20.1.jar".to_string()),
+                display: "mods/jei-1.20.1.jar".to_string(),
+                reason: MissingReasonView::Offline,
+                detail: String::new(),
+            },
+        ],
+        rejected: vec!["org.lwjgl3:3.3.1".to_string()],
+        warnings: vec!["`server-overrides/` was not unpacked (client import)".to_string()],
+        error: None,
+        registered: Some("Survival".to_string()),
+        bytes_written: 3_400_000,
+        rolled_back: true,
+    };
+    if conflicts {
+        report.conflicts = vec![
+            conflict(
+                "config/sodium-options.json",
+                ConflictReasonView::UserModified,
+            ),
+            conflict("mods/xaeroplus.jar", ConflictReasonView::UserDeleted),
+            conflict("options.txt", ConflictReasonView::PreExisting),
+        ];
+    }
+    report
+}
+
+fn conflict(path: &str, reason: ConflictReasonView) -> ConflictFileView {
+    ConflictFileView {
+        path: path.to_string(),
+        reason,
+        // 默认档永远是「保留我的」——夹具也一样，截图不许示范成默认覆盖
+        choice: ConflictChoiceView::KeepUser,
+        pack_sha1: "9f2c41ab77de3350aa1b8c0d5e6f708192a3b4c5".to_string(),
+        base_sha1: Some("3a7d90ff11bc22445566ef7788990011aabbccdd".to_string()),
+        disk_sha1: Some("c1d2e3f4050617283940a5b6c7d8e9f0a1b2c3d4".to_string()),
+        pack_size: 4_200,
+    }
+}
+
+/// 导出预检：12 内联 / 1 跳过（包不完整）。
+fn preview() -> ExportPreviewView {
+    let mut files = vec![ExportFileView {
+        path: "mods/create-1.2.3.jar".to_string(),
+        class: ExportClassView::Inline,
+        reason: ExportReasonView::NoRemoteMatch,
+        bytes: 2_100_000,
+        disabled: false,
+    }];
+    for index in 0..11 {
+        files.push(ExportFileView {
+            path: format!("mods/generated-{index:02}.jar"),
+            class: ExportClassView::Inline,
+            reason: ExportReasonView::NoRemoteMatch,
+            bytes: 512_000,
+            disabled: false,
+        });
+    }
+    // 13 条「没进包」是真实形态：预检那块必须自己做有界滚动，否则把「确认写盘」顶出屏幕
+    for index in 0..12 {
+        files.push(ExportFileView {
+            path: format!("mods/.cache/backup-{index:02}.jar"),
+            class: ExportClassView::Skipped,
+            reason: ExportReasonView::SymbolicLink,
+            bytes: 0,
+            disabled: false,
+        });
+    }
+    files.push(ExportFileView {
+        path: "mods/bad:name.jar".to_string(),
+        class: ExportClassView::Skipped,
+        reason: ExportReasonView::UnsafePath,
+        bytes: 0,
+        disabled: false,
+    });
+
+    ExportPreviewView {
+        format: PackFormatView::Modrinth,
+        instance: "survival".to_string(),
+        name: "Survival 1.20.1".to_string(),
+        version: "1.0.0".to_string(),
+        target: PathBuf::from("C:/ULL/downloads/Survival-1.0.0.mrpack"),
+        files,
+        notes: vec![
+            "CF 表达不了禁用位：`.disabled` 文件已内联".to_string(),
+            "离线目录：所有文件都证明不了可被远程替代，全部内联".to_string(),
+        ],
+    }
+}
diff --git a/crates/app-iced/src/pages/content/packui/message.rs b/crates/app-iced/src/pages/content/packui/message.rs
new file mode 100644
index 0000000..62b8983
--- /dev/null
+++ b/crates/app-iced/src/pages/content/packui/message.rs
@@ -0,0 +1,57 @@
+//! 整合包导入/导出区的**自有**消息（M113 `PACKUI`）。
+//!
+//! 与内容库页同一个范式（`pages/content/message.rs`）：这一支挂在
+//! [`super::Message::Pack`] 下面，`pages::Message` 只留 `Content(..)` 一个投递口，
+//! 于是「加一条导入/导出消息」不碰共享枚举的正文，也不碰 `app/update/page_messages.rs`
+//! 那条**不许 `_ =>`** 的 match。
+//!
+//! **一条纪律**（与内容库页同一句）：这里的每个变体都是**意图**，不是状态变更。
+//! 拖入文件 ≠ 已经导入（证据是 `ImportProgress` / `ImportReport` 事件回流）；
+//! 点「导出」≠ 已经写了盘（证据是预检与 `ExportDone` 事件）。
+
+use std::path::PathBuf;
+
+use unlucky_presenter::dto::{InstanceId, PackFormatView};
+
+/// 导入/导出区的消息。
+#[derive(Debug, Clone)]
+pub enum Message {
+    /// 拖入了一个文件或目录（由 `app/update.rs` 的窗口事件转发）
+    ///
+    /// 只**落成草稿并立刻探测**，不直接开跑：用户要能看到「这个包看起来像 X」再决定。
+    Dropped(PathBuf),
+    /// 拖拽悬停状态变了（`true` = 有文件在窗口上方）
+    Hover(bool),
+    /// 路径输入框变了（**只改草稿**，不派指令）
+    PathChanged(String),
+    /// 提交导入（用当前草稿路径）
+    Import,
+    /// 取消正在跑的导入（阶段边界生效）
+    Cancel,
+    /// 关掉结果面板（报告 / 致命错误都走这一条）
+    Dismiss,
+    /// 以包为准重新导入（对应 `overwrite = true`；**只在用户显式点过之后**）
+    Overwrite,
+    /// 展开/收起某一条冲突的三方明细
+    ToggleConflict(String),
+    /// 换目标实例（`None` = 按包名新建）
+    SetInstance(Option<InstanceId>),
+    /// 换新实例名（`None` 语义由 `SetInstance` 承担，这里只改名字）
+    SetInstanceName(String),
+    /// 换导出格式
+    SetFormat(PackFormatView),
+    /// 换导出包名
+    SetExportName(String),
+    /// 换导出包版本
+    SetExportVersion(String),
+    /// 换落盘路径（留空 = 让 host 给缺省）
+    SetOutput(String),
+    /// 跑预检（**不写盘**）
+    Precheck,
+    /// 确认写盘（预检已经有结果才可达）
+    Confirm,
+    /// 放弃这次导出（关掉预检面板，不写盘）
+    AbortExport,
+    /// 打开导出面板
+    OpenExport,
+}
diff --git a/crates/app-iced/src/pages/content/packui/model.rs b/crates/app-iced/src/pages/content/packui/model.rs
new file mode 100644
index 0000000..46bfa9d
--- /dev/null
+++ b/crates/app-iced/src/pages/content/packui/model.rs
@@ -0,0 +1,227 @@
+//! 导入/导出区的视图模型：**presenter 快照 + 页面选择 → 要画的东西**。
+//!
+//! ## 分层（与内容库页、下载页同一条）
+//!
+//! | 数据源 | 谁转 | 用途 |
+//! |---|---|---|
+//! | `AppState::import` / `AppState::export` | [`Pack::of`] | 产品运行时的真页面 |
+//! | [`super::demo`] 的固定夹具 | 同上 | `pages_demo` 出图与单测 |
+//!
+//! 页面自己**不留**业务状态：进度、报告、预检都在 presenter（`ImportState` / `ExportState`）。
+//! [`PackPageState`] 里只有「用户在这一屏上点了什么」——路径草稿、目标实例、格式、包名、
+//! 展开的那条冲突。
+//!
+//! ## 文件分工（守 400 行）
+//!
+//! | 文件 | 职责 |
+//! |---|---|
+//! | 本文件 | 整块 [`Pack`] + 页内选择 [`PackPageState`] + 探测诊断 [`Probe`] |
+//! | [`progress`] | 阶段 / 进度 → 下载页面板的入参（**唯一**的进度形状来源） |
+//! | [`report`] | 导入结果：三态 + 容忍域逐条 + 致命块 |
+//! | [`export`] | 导出：格式选择 + 预检（不写盘） |
+//!
+//! ## 容忍 / 致命在模型层就分开
+//!
+//! [`report::Report::missing`] 是「搞不到某个文件」（实例可用），[`report::Report::fatal`]
+//! 是「已整包回滚」。两者字段类型不同、画的时候颜色与图标也不同，不可能混成一个列表。
+
+mod export;
+mod progress;
+mod report;
+
+pub use export::{format_label, request_of as request_export, Export, Preview};
+pub use progress::Running;
+pub use report::{ConflictRow, Report, Row};
+
+use unlucky_i18n::{Catalog, Key};
+use unlucky_presenter::dto::{ExportState, ImportState, InstanceId, PackFormatView, ProbeView};
+
+use crate::pages::content::Target;
+
+/// 页面自留的选择（所有者在 `App::pack`，重建快照不该把它们冲掉）。
+#[derive(Debug, Clone, PartialEq)]
+pub struct PackPageState {
+    /// 路径草稿（拖入或手输；提交后才进请求）
+    pub draft: String,
+    /// 有文件悬在窗口上方（拖拽高亮）
+    pub hover: bool,
+    /// 目标实例（`None` = 按包名新建）
+    pub instance: Option<InstanceId>,
+    /// 新实例名
+    pub instance_name: String,
+    /// 导出格式
+    pub format: PackFormatView,
+    /// 导出包名
+    pub export_name: String,
+    /// 导出包版本
+    pub export_version: String,
+    /// 落盘路径草稿（空 = 让 host 给缺省）
+    pub output: String,
+    /// 导出面板开着吗
+    pub export_open: bool,
+    /// 展开的那条冲突路径
+    pub expanded: Option<String>,
+}
+
+impl Default for PackPageState {
+    fn default() -> Self {
+        Self {
+            draft: String::new(),
+            hover: false,
+            instance: None,
+            instance_name: String::new(),
+            // 导出的首选是 Modrinth：CF 的 `files[]` 只能写能证明 `projectID`/`fileID` 的项，
+            // 而离线目录证明不了任何一条 ⇒ 全内联 + 一堆「表达不了」的注记。mrpack 才是主路。
+            format: PackFormatView::Modrinth,
+            export_name: String::new(),
+            export_version: "1.0.0".to_string(),
+            output: String::new(),
+            export_open: false,
+            expanded: None,
+        }
+    }
+}
+
+/// 一个实例候选（导入目标与导出源共用）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PackTarget {
+    /// 实例 id
+    pub id: InstanceId,
+    /// 一行显示名（`Survival · 1.20.1 · Fabric`）
+    pub label: String,
+}
+
+/// 探测失败时的具名诊断块。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Probe {
+    /// 最像哪个格式（`None` = 三个都不像）
+    pub looks_like: Option<PackFormatView>,
+    /// 「看起来像 X，但缺 Y」（或「没有任何已知格式认领」）
+    pub lead: String,
+    /// 包里实际看到的标记（host 已截断，只给代表性几条）
+    pub saw: Vec<String>,
+    /// 兜底说明（core 原文：试过哪些格式）
+    pub detail: String,
+}
+
+/// 整块导入/导出区要画的东西。
+#[derive(Debug, Clone, PartialEq)]
+pub struct Pack {
+    /// 拖拽高亮
+    pub hover: bool,
+    /// 路径草稿
+    pub draft: String,
+    /// 入口说明（拖什么）
+    pub drop_hint: &'static str,
+    /// 没有系统文件框的原因（如实说，不许装作有）
+    pub no_dialog_note: &'static str,
+    /// 目标实例候选
+    pub targets: Vec<PackTarget>,
+    /// 选中的目标实例
+    pub instance: Option<InstanceId>,
+    /// 新实例名
+    pub instance_name: String,
+    /// 正在导入（有它就画那块面板）
+    pub running: Option<Running>,
+    /// 探测失败诊断
+    pub probe: Option<Probe>,
+    /// 用户取消过这次导入：面板收回但**后台还在跑**（core 没有取消令牌），
+    /// 所以要把这句话留在界面上，别让用户以为「没建成」（复审 r1 P1-2）。
+    pub cancelled: bool,
+    /// 取消提示的正文
+    pub cancelled_note: &'static str,
+    /// 导入结果
+    pub report: Option<Report>,
+    /// 导出块
+    pub export: Export,
+}
+
+impl Pack {
+    /// presenter 快照 + 页面选择 → 视图模型（**唯一的真数据入口**）。
+    pub fn of(
+        import: &ImportState,
+        export: &ExportState,
+        page: &PackPageState,
+        targets: &[Target],
+        catalog: Catalog,
+    ) -> Self {
+        let candidates: Vec<PackTarget> = targets
+            .iter()
+            .map(|target| PackTarget {
+                id: target.id.clone(),
+                label: format!(
+                    "{} · {} · {}",
+                    target.name,
+                    target.mc_version,
+                    crate::pages::content::loader_name(target.loader)
+                ),
+            })
+            .collect();
+        let instance = page
+            .instance
+            .clone()
+            .or_else(|| candidates.first().map(|target| target.id.clone()));
+
+        Self {
+            hover: page.hover,
+            draft: page.draft.clone(),
+            drop_hint: catalog.text(Key::PackDropHint),
+            no_dialog_note: catalog.text(Key::PackNoDialog),
+            targets: candidates.clone(),
+            instance: instance.clone(),
+            instance_name: page.instance_name.clone(),
+            running: import
+                .progress
+                .as_ref()
+                .map(|progress| progress::running_of(progress, catalog)),
+            probe: import.probe.as_ref().map(|probe| probe_of(probe, catalog)),
+            cancelled: import.cancelled,
+            cancelled_note: catalog.text(Key::PackCancelled),
+            report: import
+                .report
+                .as_ref()
+                .map(|report| report::report_of(report, page, catalog)),
+            export: export::export_of(export, page, candidates, catalog),
+        }
+    }
+
+    /// 有没有东西可画（没有就整块收起来，不占版面）。
+    pub fn is_idle(&self) -> bool {
+        self.running.is_none()
+            && self.probe.is_none()
+            && self.report.is_none()
+            && !self.cancelled
+            && !self.export.open
+            && self.draft.is_empty()
+    }
+}
+
+/// 探测诊断：把「缺哪个标记」摊开。
+///
+/// `saw` 为空时补一句「没有可识别的东西」——空列表直接画出来是一行空白，用户会以为是渲染坏了。
+fn probe_of(probe: &ProbeView, catalog: Catalog) -> Probe {
+    let lead = match probe.looks_like {
+        Some(format) => catalog.render(
+            Key::PackProbeLooksLike,
+            &[
+                ("format", export::format_label(format, catalog)),
+                ("missing", &probe.missing.join(" · ")),
+            ],
+        ),
+        None => catalog.text(Key::PackProbeUnknown).to_owned(),
+    };
+    let saw = if probe.saw.is_empty() {
+        vec![catalog.text(Key::PackProbeNothing).to_owned()]
+    } else {
+        probe.saw.clone()
+    };
+    Probe {
+        looks_like: probe.looks_like,
+        lead,
+        saw,
+        detail: probe.detail.clone(),
+    }
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/app-iced/src/pages/content/packui/model/export.rs b/crates/app-iced/src/pages/content/packui/model/export.rs
new file mode 100644
index 0000000..d4e3f37
--- /dev/null
+++ b/crates/app-iced/src/pages/content/packui/model/export.rs
@@ -0,0 +1,254 @@
+//! 导出：格式选择 + **预检**（不写盘）。
+//!
+//! ## 预检与写盘是两次调用，同一套判据
+//!
+//! [`Preview`] 只扫描分类、不写盘；确认之后才是真导出。任务书要的
+//! 「将内联 N 个文件 / 无法导出 M 项」正是 [`Preview::head`]。
+//!
+//! 三分类的口径（与 core 一致，**没有第四类**）：
+//!
+//! | 类 | 含义 | 预检里怎么呈现 |
+//! |---|---|---|
+//! | `Remote` | 能证明可被远程替代 | 一行计数 |
+//! | `Inline` | 证明不了 ⇒ 原字节进 `overrides/` | 计数 + 字节 + 前几条样例 |
+//! | `Skipped` | 压根没进包 | **逐条列出**（包不完整，不许合并成一句「已导出」） |
+//!
+//! `Skipped` 非零时 [`Preview::complete`] 为假，界面上会明确写「有文件不会进包」——
+//! 这是 M112 那句「不认识的 mod 不能丢、不能编」的用户侧落点：丢了就要看见丢在哪。
+
+use unlucky_i18n::{Catalog, Key};
+use unlucky_presenter::dto::{
+    human_bytes, ExportClassView, ExportFileView, ExportPreviewView, ExportReasonView,
+    ExportRequestView, ExportState, PackFormatView,
+};
+
+use super::{PackPageState, PackTarget, Row};
+
+/// 页内选择 → 导出请求（预检与写盘**共用同一份**）。
+///
+/// `target` 必须从这里进去（复审 r1 P1-1）：之前全仓唯一构造点硬编码 `target: None`，
+/// 于是用户敲的「Save to」永远不进请求 —— 输入框是死的。
+#[must_use]
+pub fn request_of(page: &PackPageState, instance: &str) -> ExportRequestView {
+    let name = page.export_name.trim();
+    let version = page.export_version.trim();
+    let output = page.output.trim();
+    ExportRequestView {
+        instance: instance.to_string(),
+        format: page.format,
+        name: if name.is_empty() {
+            instance.to_string()
+        } else {
+            name.to_string()
+        },
+        version: if version.is_empty() {
+            "1.0.0".to_string()
+        } else {
+            version.to_string()
+        },
+        target: (!output.is_empty()).then(|| std::path::PathBuf::from(output)),
+    }
+}
+
+/// 预检里「内联文件样例」最多列几条（其余用一句「还有 N 个」收口）。
+const INLINE_SAMPLE: usize = 6;
+
+/// 预检块（**还没写盘**）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Preview {
+    /// 一句话主结论：`将内联 12 个文件 · 无法导出 0 项`
+    pub head: String,
+    /// 远程引用行
+    pub remote_line: String,
+    /// 内联字节行
+    pub inline_line: String,
+    /// 落盘路径行
+    pub target_line: String,
+    /// 包会完整吗（`false` = 有文件压根没进包）
+    pub complete: bool,
+    /// 完整性那句话
+    pub complete_line: String,
+    /// 无法导出的项（逐条）
+    pub skipped: Vec<Row>,
+    /// 内联文件样例
+    pub inline_sample: Vec<String>,
+    /// `还有 N 个文件…`
+    pub more_line: Option<String>,
+    /// core 的 `notes`（已知损失）
+    pub notes: Vec<String>,
+}
+
+/// 导出块。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Export {
+    /// 面板开着吗
+    pub open: bool,
+    /// 当前格式
+    pub format: PackFormatView,
+    /// 格式人读名
+    pub format_label: &'static str,
+    /// 可选的格式（只有两个：mrpack / CF）
+    pub formats: Vec<(PackFormatView, &'static str)>,
+    /// 目标实例候选
+    pub targets: Vec<PackTarget>,
+    /// 选中的实例
+    pub instance: Option<unlucky_presenter::dto::InstanceId>,
+    /// 包名
+    pub name: String,
+    /// 版本
+    pub version: String,
+    /// 落盘路径草稿（空 = 缺省）
+    pub output: String,
+    /// MultiMC/Prism 只导入不导出（如实写）
+    pub format_note: &'static str,
+    /// 预检在飞
+    pub pending: bool,
+    /// 预检的进行中说明
+    pub pending_line: &'static str,
+    /// 预检结果
+    pub preview: Option<Preview>,
+    /// 写盘完成行
+    pub done: Option<String>,
+    /// 失败原因
+    pub failed: Option<String>,
+}
+
+/// 导出一块。
+pub(super) fn export_of(
+    state: &ExportState,
+    page: &PackPageState,
+    targets: Vec<PackTarget>,
+    catalog: Catalog,
+) -> Export {
+    let instance = page
+        .instance
+        .clone()
+        .or_else(|| targets.first().map(|target| target.id.clone()));
+    let formats = PackFormatView::EXPORTABLE
+        .iter()
+        .map(|format| (*format, format_label(*format, catalog)))
+        .collect();
+
+    Export {
+        open: page.export_open,
+        format: page.format,
+        format_label: format_label(page.format, catalog),
+        formats,
+        targets,
+        instance,
+        name: page.export_name.clone(),
+        version: page.export_version.clone(),
+        output: page.output.clone(),
+        format_note: catalog.text(Key::PackExportMultimcNote),
+        pending: state.pending,
+        pending_line: catalog.text(Key::PackExportPending),
+        preview: state
+            .preview
+            .as_ref()
+            .map(|preview| preview_of(preview, catalog)),
+        done: state.done.as_ref().map(|done| {
+            catalog.render(
+                Key::PackExportDone,
+                &[
+                    ("path", &done.path.display().to_string()),
+                    ("bytes", &human_bytes(done.bytes)),
+                ],
+            )
+        }),
+        failed: state.failed.clone(),
+    }
+}
+
+pub(super) fn preview_of(preview: &ExportPreviewView, catalog: Catalog) -> Preview {
+    let skipped: Vec<Row> = preview
+        .files
+        .iter()
+        .filter(|file| file.class == ExportClassView::Skipped)
+        .map(|file| skipped_row(file, catalog))
+        .collect();
+    let inline: Vec<&ExportFileView> = preview
+        .files
+        .iter()
+        .filter(|file| file.class == ExportClassView::Inline)
+        .collect();
+    let inline_sample = inline
+        .iter()
+        .take(INLINE_SAMPLE)
+        .map(|file| file.path.clone())
+        .collect::<Vec<_>>();
+    let more_line = (inline.len() > inline_sample.len()).then(|| {
+        catalog.render(
+            Key::PackPreviewMore,
+            &[("count", &(inline.len() - inline_sample.len()).to_string())],
+        )
+    });
+
+    Preview {
+        head: catalog.render(
+            Key::PackPreviewHead,
+            &[
+                ("inline", &preview.inline_count().to_string()),
+                ("skipped", &preview.skipped_count().to_string()),
+            ],
+        ),
+        remote_line: catalog.render(
+            Key::PackPreviewRemote,
+            &[("count", &preview.remote_count().to_string())],
+        ),
+        inline_line: catalog.render(
+            Key::PackPreviewInlineBytes,
+            &[("bytes", &human_bytes(preview.inline_bytes()))],
+        ),
+        target_line: catalog.render(
+            Key::PackPreviewTarget,
+            &[("path", &preview.target.display().to_string())],
+        ),
+        complete: preview.is_complete(),
+        complete_line: catalog
+            .text(if preview.is_complete() {
+                Key::PackPreviewComplete
+            } else {
+                Key::PackPreviewIncomplete
+            })
+            .to_owned(),
+        skipped,
+        inline_sample,
+        more_line,
+        notes: preview.notes.clone(),
+    }
+}
+
+fn skipped_row(file: &ExportFileView, catalog: Catalog) -> Row {
+    Row {
+        path: file.path.clone(),
+        note: reason_label(file.reason, catalog).to_owned(),
+    }
+}
+
+/// 导出归类原因 → 人读（每条都写得能自己解释，不靠图标猜）。
+#[must_use]
+pub fn reason_label(reason: ExportReasonView, catalog: Catalog) -> &'static str {
+    match reason {
+        ExportReasonView::ModrinthSha1 => catalog.text(Key::PackReasonModrinthSha1),
+        ExportReasonView::CurseForgeFingerprint => catalog.text(Key::PackReasonCurseFingerprint),
+        ExportReasonView::NoRemoteMatch => catalog.text(Key::PackReasonNoRemoteMatch),
+        ExportReasonView::CurseOnlyMatch => catalog.text(Key::PackReasonCurseOnly),
+        ExportReasonView::ModrinthOnlyMatch => catalog.text(Key::PackReasonModrinthOnly),
+        ExportReasonView::MissingSha512 => catalog.text(Key::PackReasonMissingSha512),
+        ExportReasonView::MissingCurseIds => catalog.text(Key::PackReasonMissingCurseIds),
+        ExportReasonView::DisabledNotExpressible => catalog.text(Key::PackReasonDisabled),
+        ExportReasonView::SymbolicLink => catalog.text(Key::PackReasonSymlink),
+        ExportReasonView::UnsafePath => catalog.text(Key::PackReasonUnsafePath),
+        ExportReasonView::Unreadable => catalog.text(Key::PackReasonUnreadable),
+    }
+}
+
+/// 格式人读名。
+#[must_use]
+pub fn format_label(format: PackFormatView, catalog: Catalog) -> &'static str {
+    match format {
+        PackFormatView::Curseforge => catalog.text(Key::PackFormatCurseforge),
+        PackFormatView::Modrinth => catalog.text(Key::PackFormatModrinth),
+        PackFormatView::Multimc => catalog.text(Key::PackFormatMultimc),
+    }
+}
diff --git a/crates/app-iced/src/pages/content/packui/model/progress.rs b/crates/app-iced/src/pages/content/packui/model/progress.rs
new file mode 100644
index 0000000..646056f
--- /dev/null
+++ b/crates/app-iced/src/pages/content/packui/model/progress.rs
@@ -0,0 +1,121 @@
+//! 阶段与进度：**把导入进度映射成下载页那块面板的入参**（不另画一套进度 UI）。
+//!
+//! ## 任务书第 5 条怎么落
+//!
+//! 「沿用既有安装面板组件与状态机，禁止再写第二套进度 UI」——
+//!
+//! 1. 导入的 `ImportStageView` / 计数先映射成面板的入参形状（[`panel_progress`] →
+//!    `InstallProgressView` → [`InstallView`]）；
+//! 2. 画法交给 `pages::download::install_panel`（同一个函数、同一套几何，进度条 / 计数 /
+//!    取消按钮都归它）；
+//! 3. 任务书要的「解包 / overrides / 补文件」三档由**一行步骤说明**（[`stage_line`]）承载。
+//!
+//! **已知重叠（如实写，别再说成修好了）**：面板自带的阶段词是**安装**语义
+//! （`Resolving version` / `Downloading files` / `Building the version` / `Registering instance`），
+//! 而 `install_panel_model` 永远会填它（M109 合流 M105 后 `InstallView` 不再对外导出，
+//! 没法从外面塞一个自定义标签或清空）。所以屏幕上同时出现「Step 2/5 · Unpacking overrides」
+//! 与「Building the version」：**粗/细两层，不是两句矛盾的话**，但 `Extract`/`Commit` 都映射到
+//! `Installing`，那一档的用词偏「安装」。
+//!
+//! 要彻底解决得让面板接受调用方给的阶段词（已报 finding：把安装面板提成共享组件）。
+
+use unlucky_i18n::{Catalog, Key};
+use unlucky_presenter::dto::{
+    ImportProgressView, ImportStageView, InstallProgressView, InstallStage,
+};
+
+use crate::pages::download::Download;
+
+/// 抛进面板的进度行。
+#[derive(Debug, Clone, PartialEq)]
+pub struct Running {
+    /// 包名（面板标题那一行）
+    pub pack: String,
+    /// 细档位说明（`步骤 2/5 · 解包覆盖内容`）
+    pub stage_line: String,
+    /// 交给下载页那块面板的进度（**唯一**的进度形状来源；`None` = 面板无话可说）
+    pub panel: Option<Download>,
+}
+
+/// 细档位说明（`步骤 2/5 · 解包覆盖内容`）。
+#[must_use]
+pub fn stage_line(stage: ImportStageView, catalog: Catalog) -> String {
+    let total = ImportStageView::ALL.len();
+    let index = ImportStageView::ALL
+        .iter()
+        .position(|item| *item == stage)
+        .map_or(1, |at| at + 1);
+    catalog.render(
+        Key::PackStageLine,
+        &[
+            ("index", &index.to_string()),
+            ("total", &total.to_string()),
+            ("stage", catalog.text(stage_key(stage))),
+        ],
+    )
+}
+
+/// 阶段 → 文案 key。
+#[must_use]
+pub const fn stage_key(stage: ImportStageView) -> Key {
+    match stage {
+        ImportStageView::Probe => Key::PackStageProbe,
+        ImportStageView::Extract => Key::PackStageExtract,
+        ImportStageView::Fetch => Key::PackStageFetch,
+        ImportStageView::Commit => Key::PackStageCommit,
+        ImportStageView::Register => Key::PackStageRegister,
+    }
+}
+
+/// 导入阶段 → 安装面板的粗阶段（**唯一映射处**）。
+///
+/// `Extract` / `Commit` 都落到 `Installing`：对那块面板而言它们都是「在写盘」，区别由
+/// [`stage_line`] 说给用户。
+#[must_use]
+pub const fn panel_stage(stage: ImportStageView) -> InstallStage {
+    match stage {
+        ImportStageView::Probe => InstallStage::Planning,
+        ImportStageView::Extract | ImportStageView::Commit => InstallStage::Installing,
+        ImportStageView::Fetch => InstallStage::Downloading,
+        ImportStageView::Register => InstallStage::Registering,
+    }
+}
+
+/// 导入进度 → 下载页面板的入参。
+///
+/// `version` / `instance` 都填包名：面板第一行显示的就是「这次在装什么」，
+/// 而导入的对象是包，不是某个版本 id。
+#[must_use]
+pub fn panel_progress(progress: &ImportProgressView) -> InstallProgressView {
+    InstallProgressView {
+        version: progress.pack.clone(),
+        instance: progress.pack.clone(),
+        loader: String::new(),
+        stage: panel_stage(progress.stage),
+        files_done: u64::from(progress.done),
+        files_total: u64::from(progress.total),
+        bytes_done: 0,
+        bytes_total: 0,
+        speed_bps: 0,
+        eta_secs: 0,
+        message: progress.current.clone().unwrap_or_default(),
+    }
+}
+
+/// 进度事件 → 面板要的视图模型。
+///
+/// 面板入参走 `pages::download::install_panel_model`（M109 合流 M105 后提供的**唯一**入口）：
+/// 它把 `InstallProgressView` 转成面板要的 `Download`，终态（完成/取消）返回 `None`。
+/// 导入的五个阶段都不是终态，所以正常路径下一定是 `Some`；`None` 只做防御（面板没了就只留步骤行）。
+///
+/// 面板自带那个粗阶段词是**安装**语义（`Resolving version` / `Downloading files` /
+/// `Building the version` / `Registering instance`），所以细档位由 [`stage_line`] 说，
+/// 二者是「粗/细」关系而不是两套说法——[`panel_stage`] 只挑语义最近的那一档。
+pub(super) fn running_of(progress: &ImportProgressView, catalog: Catalog) -> Running {
+    let panel = panel_progress(progress);
+    Running {
+        pack: progress.pack.clone(),
+        stage_line: stage_line(progress.stage, catalog),
+        panel: crate::pages::download::install_panel_model(&panel, catalog),
+    }
+}
diff --git a/crates/app-iced/src/pages/content/packui/model/report.rs b/crates/app-iced/src/pages/content/packui/model/report.rs
new file mode 100644
index 0000000..c056317
--- /dev/null
+++ b/crates/app-iced/src/pages/content/packui/model/report.rs
@@ -0,0 +1,255 @@
+//! 导入结果的视图模型：**三态 + 容忍域逐条 + 致命块**。
+//!
+//! ## 为什么容忍域与致命域连字段类型都不同
+//!
+//! 任务书：「失败原因逐条展示（能容忍的缺文件与致命错误必须视觉可区分）」。
+//! 只在颜色上区分不够——颜色一关掉（截图/高对比/色弱）就没了。所以：
+//!
+//! | 域 | 类型 | 画法 |
+//! |---|---|---|
+//! | 容忍（缺文件 / 被拒 component / 注记） | [`Row`]（路径 + 原因） | 中性容器 + `Info` 图标 + 逐条列表 |
+//! | 致命（已回滚） | [`Fatal`]（大类 + 原文 + 建议 + 稳定码） | `ErrorContainer` + `Error` 图标 + 标题换措辞 |
+//!
+//! 一个 `Option<Fatal>` 与一个 `Vec<Row>` 之间没有「误合并」的写法，这比任何样式约定都硬。
+
+use unlucky_i18n::{Catalog, Key};
+use unlucky_presenter::dto::{
+    ConflictChoiceView, ConflictFileView, ConflictReasonView, ImportErrorView, ImportReportView,
+    ImportStatusView, MissingFileView, MissingReasonView,
+};
+
+use super::PackPageState;
+
+/// 报告里的一行（容忍域：缺文件 / 被拒 component）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Row {
+    /// 左列（路径 / 组件名）
+    pub path: String,
+    /// 右列（原因的人读文案）
+    pub note: String,
+}
+
+/// 一条冲突（三方哈希 + 本次处置）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ConflictRow {
+    /// 实例内路径
+    pub path: String,
+    /// 成因（`你改过` / `你删过` / `本来就在`）
+    pub reason: String,
+    /// 本次实际处置（`保留我的` / `用包里的`）
+    pub choice: String,
+    /// 包内 SHA-1（截短）
+    pub pack_sha1: String,
+    /// 基线 SHA-1（`None` = 没有基线）
+    pub base_sha1: Option<String>,
+    /// 磁盘 SHA-1（`None` = 文件不在）
+    pub disk_sha1: Option<String>,
+    /// 展开中（展开才画三方哈希那行）
+    pub expanded: bool,
+}
+
+/// 致命失败块（**已整包回滚**）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Fatal {
+    /// 「已回滚 —— 目标目录零残留」
+    pub title: String,
+    /// 大类名（`路径穿越` / `清单损坏` …）
+    pub label: String,
+    /// 具体是什么
+    pub message: String,
+    /// 稳定码
+    pub code: String,
+    /// 补救建议
+    pub hint: Option<String>,
+}
+
+/// 导入结果块。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Report {
+    /// 三态
+    pub status: ImportStatusView,
+    /// 标题（已导入 / 有缺口 / 已回滚）
+    pub title: String,
+    /// 副标题（`包名 · 格式 · 游戏版本 · 加载器`）
+    pub subtitle: String,
+    /// 写盘行（`12 个文件已写盘 · 3.4 MB`）
+    pub written_line: String,
+    /// 致命失败（有它就**没有**下面的缺口区块）
+    pub fatal: Option<Fatal>,
+    /// 缺文件标题
+    pub missing_title: Option<String>,
+    /// 缺文件逐条（容忍域）
+    pub missing: Vec<Row>,
+    /// 冲突标题
+    pub conflicts_title: Option<String>,
+    /// 冲突逐条
+    pub conflicts: Vec<ConflictRow>,
+    /// 被拒 component 的标题（带计数，与下面逐条行数一致）
+    pub rejected_title: Option<String>,
+    /// 被拒 component 逐条
+    pub rejected: Vec<Row>,
+    /// 注记逐条
+    pub warnings: Vec<String>,
+    /// 能不能给「以包为准重新导入」（有冲突、且实例可用时才有意义）
+    pub can_overwrite: bool,
+    /// 「两者都留改名」为何不支持（有冲突时如实写）
+    pub overwrite_note: Option<String>,
+}
+
+impl Report {
+    /// 实例可用吗（`Success` / `Partial` 都是装上了）。
+    pub const fn installed(&self) -> bool {
+        self.status.installed()
+    }
+}
+
+/// 一次导入结果 → 视图模型。
+pub(super) fn report_of(
+    report: &ImportReportView,
+    page: &PackPageState,
+    catalog: Catalog,
+) -> Report {
+    let missing_title = (!report.missing.is_empty()).then(|| {
+        catalog.render(
+            Key::PackReportMissing,
+            &[("count", &report.missing.len().to_string())],
+        )
+    });
+    let conflicts_title = (!report.conflicts.is_empty()).then(|| {
+        catalog.render(
+            Key::PackReportConflicts,
+            &[("count", &report.conflicts.len().to_string())],
+        )
+    });
+
+    Report {
+        status: report.status,
+        title: status_title(report.status, catalog).to_owned(),
+        subtitle: subtitle(report, catalog),
+        written_line: catalog.render(
+            Key::PackReportWritten,
+            &[
+                ("count", &report.written().to_string()),
+                ("bytes", &human(report)),
+            ],
+        ),
+        fatal: report.error.as_ref().map(|error| fatal_of(error, catalog)),
+        missing_title,
+        missing: report
+            .missing
+            .iter()
+            .map(|file| missing_row(file, catalog))
+            .collect(),
+        conflicts_title,
+        conflicts: report
+            .conflicts
+            .iter()
+            .map(|file| conflict_row(file, page.expanded.as_deref(), catalog))
+            .collect(),
+        rejected_title: (!report.rejected.is_empty()).then(|| {
+            catalog.render(
+                Key::PackReportRejected,
+                &[("count", &report.rejected.len().to_string())],
+            )
+        }),
+        rejected: report
+            .rejected
+            .iter()
+            .map(|component| Row {
+                path: component.clone(),
+                note: catalog.text(Key::PackReportRejectedNote).to_owned(),
+            })
+            .collect(),
+        warnings: report.warnings.clone(),
+        // 「以包为准重新导入」只在**导入到已有实例**时有意义（复审 r1 P2-2）：新建实例那条路上
+        // 目标目录已经建好，再点一次必然撞「directory already exists」——一个必然失败的按钮
+        // 等于死按钮，所以那种流程下不显示。
+        can_overwrite: !report.conflicts.is_empty()
+            && report.status == ImportStatusView::Partial
+            && page.instance.is_some(),
+        overwrite_note: (!report.conflicts.is_empty())
+            .then(|| catalog.text(Key::PackOverwriteNote).to_owned()),
+    }
+}
+
+/// 字节数的人读串。
+fn human(report: &ImportReportView) -> String {
+    unlucky_presenter::dto::human_bytes(report.bytes_written)
+}
+
+fn status_title(status: ImportStatusView, catalog: Catalog) -> &'static str {
+    match status {
+        ImportStatusView::Success => catalog.text(Key::PackStatusSuccess),
+        ImportStatusView::Partial => catalog.text(Key::PackStatusPartial),
+        ImportStatusView::Failed => catalog.text(Key::PackStatusFailed),
+    }
+}
+
+/// 副标题：包名 · 格式 · 游戏版本 · 加载器（缺哪个就不写哪个，不拼「未知」）。
+fn subtitle(report: &ImportReportView, catalog: Catalog) -> String {
+    let mut parts: Vec<String> = Vec::new();
+    if let Some(format) = report.format {
+        parts.push(super::format_label(format, catalog).to_owned());
+    }
+    if let Some(version) = &report.game_version {
+        parts.push(version.clone());
+    }
+    if let Some(loader) = &report.loader {
+        parts.push(loader.clone());
+    }
+    if let Some(name) = &report.pack_name {
+        parts.insert(0, name.clone());
+    }
+    parts.join(" · ")
+}
+
+fn fatal_of(error: &ImportErrorView, catalog: Catalog) -> Fatal {
+    Fatal {
+        title: catalog.text(Key::PackFatalTitle).to_owned(),
+        label: error.label.clone(),
+        message: error.message.clone(),
+        code: error.code.clone(),
+        hint: error.hint.clone(),
+    }
+}
+
+fn missing_row(file: &MissingFileView, catalog: Catalog) -> Row {
+    Row {
+        path: file.path.clone().unwrap_or_else(|| file.display.clone()),
+        note: match file.reason {
+            MissingReasonView::Offline => catalog.text(Key::PackMissingOffline).to_owned(),
+            MissingReasonView::NoSource => catalog.text(Key::PackMissingNoSource).to_owned(),
+            MissingReasonView::FetchFailed => catalog.render(
+                Key::PackMissingFetchFailed,
+                &[("detail", file.detail.as_str())],
+            ),
+        },
+    }
+}
+
+fn conflict_row(file: &ConflictFileView, expanded: Option<&str>, catalog: Catalog) -> ConflictRow {
+    ConflictRow {
+        path: file.path.clone(),
+        reason: match file.reason {
+            ConflictReasonView::UserModified => catalog.text(Key::PackConflictUserModified),
+            ConflictReasonView::UserDeleted => catalog.text(Key::PackConflictUserDeleted),
+            ConflictReasonView::PreExisting => catalog.text(Key::PackConflictPreExisting),
+        }
+        .to_owned(),
+        choice: match file.choice {
+            ConflictChoiceView::KeepUser => catalog.text(Key::PackChoiceKeepUser),
+            ConflictChoiceView::Overwrite => catalog.text(Key::PackChoiceOverwrite),
+        }
+        .to_owned(),
+        pack_sha1: short_sha(&file.pack_sha1),
+        base_sha1: file.base_sha1.as_deref().map(short_sha),
+        disk_sha1: file.disk_sha1.as_deref().map(short_sha),
+        expanded: expanded == Some(file.path.as_str()),
+    }
+}
+
+/// SHA-1 截短（前 8 位够人眼区分；全 40 位会把一行撑爆）。
+#[must_use]
+pub fn short_sha(sha: &str) -> String {
+    sha.chars().take(8).collect()
+}
diff --git a/crates/app-iced/src/pages/content/packui/model/tests.rs b/crates/app-iced/src/pages/content/packui/model/tests.rs
new file mode 100644
index 0000000..991fcbd
--- /dev/null
+++ b/crates/app-iced/src/pages/content/packui/model/tests.rs
@@ -0,0 +1,394 @@
+//! 导入/导出区视图模型的守门（M113）：阶段映射、预检计数、三方哈希、容忍/致命分野。
+//!
+//! 这里**不测画法**（画法靠出图），测的是「决策」：哪些数字进了哪一行、哪些字段被截短、
+//! 哪一态该出现哪一块。所有断言都能在没有图形环境的情况下跑。
+
+use std::path::PathBuf;
+
+use unlucky_i18n::Lang;
+use unlucky_presenter::dto::{
+    ConflictChoiceView, ConflictFileView, ConflictReasonView, ExportClassView, ExportFileView,
+    ExportPreviewView, ImportErrorView, ImportProgressView, ImportReportView, ImportStageView,
+    ImportStatusView, InstallStage, MissingFileView, MissingReasonView, PackFormatView,
+};
+
+use super::progress::{panel_progress, panel_stage, stage_line};
+use super::report::report_of;
+use super::report::short_sha;
+use super::{Pack, PackPageState};
+
+fn catalog() -> unlucky_i18n::Catalog {
+    Lang::En.catalog()
+}
+
+#[test]
+fn stage_line_counts_the_five_steps_in_order() {
+    let expected = [
+        (ImportStageView::Probe, "1/5"),
+        (ImportStageView::Extract, "2/5"),
+        (ImportStageView::Fetch, "3/5"),
+        (ImportStageView::Commit, "4/5"),
+        (ImportStageView::Register, "5/5"),
+    ];
+    for (stage, position) in expected {
+        let line = stage_line(stage, catalog());
+        assert!(line.contains(position), "{stage:?} 的步号不对：{line}");
+    }
+    // 阶段名要真的是「那一档」，不能五个阶段都显示同一句
+    let lines: Vec<String> = ImportStageView::ALL
+        .iter()
+        .map(|stage| stage_line(*stage, catalog()))
+        .collect();
+    for (index, line) in lines.iter().enumerate() {
+        for other in lines.iter().skip(index + 1) {
+            assert_ne!(line, other, "两个阶段的说明撞了：{line}");
+        }
+    }
+}
+
+#[test]
+fn no_progress_stage_maps_to_a_terminal_install_stage() {
+    // 进度面板只该画「在跑」的形态：映射到 Done/Failed/Cancelled 会让面板提前画成收尾/失败
+    for stage in ImportStageView::ALL {
+        let mapped = panel_stage(stage);
+        assert!(
+            !mapped.is_terminal(),
+            "{stage:?} 落到了终态 {mapped:?}（面板会画成收尾）"
+        );
+    }
+}
+
+#[test]
+fn panel_progress_carries_the_counts_and_the_pack_name() {
+    let progress = ImportProgressView {
+        stage: ImportStageView::Fetch,
+        done: 41,
+        total: 90,
+        current: Some("mods/sodium.jar".to_string()),
+        pack: "Better MC".to_string(),
+    };
+    let panel = panel_progress(&progress);
+    assert_eq!(panel.files_done, 41);
+    assert_eq!(panel.files_total, 90);
+    assert_eq!(panel.stage, InstallStage::Downloading);
+    // 面板第一行显示的就是包名（导入的对象是包，不是某个版本 id）
+    assert_eq!(panel.version, "Better MC");
+}
+
+#[test]
+fn unknown_counts_keep_the_bar_unknown() {
+    // total == 0 时不允许画确定态进度条（那是「静止的假进度」的来源）
+    let progress = ImportProgressView {
+        stage: ImportStageView::Probe,
+        done: 0,
+        total: 0,
+        current: None,
+        pack: "Pack".to_string(),
+    };
+    let panel = panel_progress(&progress);
+    assert_eq!(panel.files_total, 0);
+    assert_eq!(panel.speed_bps, 0, "导入没有字节速率，不许编");
+}
+
+#[test]
+fn sha_is_shortened_to_eight_chars() {
+    assert_eq!(
+        short_sha("9f2c41ab77de3350aa1b8c0d5e6f708192a3b4c5"),
+        "9f2c41ab"
+    );
+    assert_eq!(short_sha("abc"), "abc");
+    assert_eq!(short_sha(""), "");
+}
+
+fn preview(files: Vec<ExportFileView>) -> ExportPreviewView {
+    ExportPreviewView {
+        format: PackFormatView::Modrinth,
+        instance: "survival".to_string(),
+        name: "Survival".to_string(),
+        version: "1.0.0".to_string(),
+        target: PathBuf::from("C:/tmp/out.mrpack"),
+        files,
+        notes: Vec::new(),
+    }
+}
+
+fn export_file(
+    path: &str,
+    class: ExportClassView,
+    reason: unlucky_presenter::dto::ExportReasonView,
+) -> ExportFileView {
+    ExportFileView {
+        path: path.to_string(),
+        class,
+        reason,
+        bytes: 1000,
+        disabled: false,
+    }
+}
+
+#[test]
+fn preview_counts_match_the_three_classes() {
+    use unlucky_presenter::dto::ExportReasonView;
+    let view = preview(vec![
+        export_file(
+            "a.jar",
+            ExportClassView::Remote,
+            ExportReasonView::ModrinthSha1,
+        ),
+        export_file(
+            "b.jar",
+            ExportClassView::Inline,
+            ExportReasonView::NoRemoteMatch,
+        ),
+        export_file(
+            "c.jar",
+            ExportClassView::Inline,
+            ExportReasonView::MissingSha512,
+        ),
+        export_file(
+            "d.jar",
+            ExportClassView::Skipped,
+            ExportReasonView::SymbolicLink,
+        ),
+    ]);
+    assert_eq!(view.remote_count(), 1);
+    assert_eq!(view.inline_count(), 2);
+    assert_eq!(view.skipped_count(), 1);
+    assert_eq!(view.inline_bytes(), 2000);
+    assert!(!view.is_complete(), "有跳过项 ⇒ 包不完整");
+}
+
+#[test]
+fn the_head_line_carries_the_two_numbers_the_task_asks_for() {
+    use unlucky_presenter::dto::ExportReasonView;
+    let view = preview(vec![
+        export_file(
+            "b.jar",
+            ExportClassView::Inline,
+            ExportReasonView::NoRemoteMatch,
+        ),
+        export_file(
+            "c.jar",
+            ExportClassView::Inline,
+            ExportReasonView::MissingSha512,
+        ),
+        export_file(
+            "d.jar",
+            ExportClassView::Skipped,
+            ExportReasonView::UnsafePath,
+        ),
+    ]);
+    let block = super::export::preview_of(&view, catalog());
+    // 「将内联 N 个文件 · 无法导出 M 项」两个数字必须来自同一份 files，不许另算
+    assert!(
+        block.head.contains('2'),
+        "内联数没进 headline：{}",
+        block.head
+    );
+    assert!(
+        block.head.contains('1'),
+        "跳过数没进 headline：{}",
+        block.head
+    );
+    assert_eq!(block.skipped.len(), 1);
+    assert!(!block.complete);
+}
+
+#[test]
+fn report_keeps_tolerable_and_fatal_apart() {
+    let report = ImportReportView {
+        status: ImportStatusView::Failed,
+        format: Some(PackFormatView::Curseforge),
+        pack_name: Some("Broken".to_string()),
+        pack_version: None,
+        game_version: None,
+        loader: None,
+        version_id: None,
+        target: PathBuf::from("C:/tmp"),
+        files: Vec::new(),
+        conflicts: Vec::new(),
+        missing: vec![MissingFileView {
+            path: Some("mods/a.jar".to_string()),
+            display: "mods/a.jar".to_string(),
+            reason: MissingReasonView::Offline,
+            detail: String::new(),
+        }],
+        rejected: Vec::new(),
+        warnings: Vec::new(),
+        error: Some(ImportErrorView {
+            code: "pack_traversal".to_string(),
+            label: "路径穿越".to_string(),
+            message: "../etc/passwd".to_string(),
+            hint: Some("换一个来源".to_string()),
+        }),
+        registered: None,
+        bytes_written: 0,
+        rolled_back: true,
+    };
+    let block = report_of(&report, &PackPageState::default(), catalog());
+    assert!(block.fatal.is_some(), "致命块必须单独存在");
+    assert_eq!(block.missing.len(), 1, "容忍域仍要逐条列出");
+    assert!(!block.installed(), "Failed 不是「装上了」");
+    assert!(!block.can_overwrite, "没有冲突时不给翻档动作");
+}
+
+#[test]
+fn conflicts_default_to_keeping_the_user_copy() {
+    let report = ImportReportView {
+        status: ImportStatusView::Partial,
+        format: Some(PackFormatView::Modrinth),
+        pack_name: Some("Pack".to_string()),
+        pack_version: None,
+        game_version: None,
+        loader: None,
+        version_id: None,
+        target: PathBuf::from("C:/tmp"),
+        files: Vec::new(),
+        conflicts: vec![ConflictFileView {
+            path: "config/x.json".to_string(),
+            reason: ConflictReasonView::UserModified,
+            choice: ConflictChoiceView::KeepUser,
+            pack_sha1: "fixture".to_string(),
+            base_sha1: None,
+            disk_sha1: Some("disk".to_string()),
+            pack_size: 12,
+        }],
+        missing: Vec::new(),
+        rejected: Vec::new(),
+        warnings: Vec::new(),
+        error: None,
+        registered: None,
+        bytes_written: 0,
+        rolled_back: true,
+    };
+    // 「以包为准」只在导入到**已有实例**时给（复审 r1 P2-2），所以这里选一个实例
+    let page = PackPageState {
+        instance: Some("survival".to_string()),
+        ..PackPageState::default()
+    };
+    let block = report_of(&report, &page, catalog());
+    assert_eq!(block.conflicts.len(), 1);
+    assert!(!block.conflicts[0].expanded, "默认收起");
+    assert_eq!(
+        block.conflicts[0].choice,
+        catalog().text(unlucky_i18n::Key::PackChoiceKeepUser),
+        "默认档必须是「保留我的」"
+    );
+    assert!(block.can_overwrite, "有冲突要能整体翻档");
+    assert!(block.overwrite_note.is_some(), "不支持「两者都留」要如实写");
+
+    // 展开的那一条才画三方哈希
+    let expanded = PackPageState {
+        expanded: Some("config/x.json".to_string()),
+        ..page.clone()
+    };
+    let block = report_of(&report, &expanded, catalog());
+    assert!(block.conflicts[0].expanded);
+}
+
+#[test]
+fn an_idle_pack_has_nothing_to_draw_but_the_entry() {
+    let import = unlucky_presenter::dto::ImportState::default();
+    let export = unlucky_presenter::dto::ExportState::default();
+    let model = Pack::of(&import, &export, &PackPageState::default(), &[], catalog());
+    assert!(model.is_idle());
+    assert!(model.running.is_none());
+    assert!(model.report.is_none());
+    // 入口说明永远在（用户得知道可以拖什么、为什么没有「选择文件」按钮）
+    assert!(!model.drop_hint.is_empty());
+    assert!(!model.no_dialog_note.is_empty());
+}
+
+#[test]
+fn the_save_to_field_really_reaches_the_request() {
+    // 复审 r1 P1-1：这个字段以前是死的（构造点硬编码 target: None）
+    let page = PackPageState {
+        output: "  D:/packs/my.mrpack  ".to_string(),
+        ..PackPageState::default()
+    };
+    let request = super::export::request_of(&page, "survival");
+    assert_eq!(
+        request.target.as_deref(),
+        Some(std::path::Path::new("D:/packs/my.mrpack")),
+        "用户敲的路径必须真的进请求（去首尾空白）"
+    );
+
+    // 留空 ⇒ None（由 host 给缺省路径），不是空串路径
+    let blank = PackPageState {
+        output: "   ".to_string(),
+        ..PackPageState::default()
+    };
+    assert!(super::export::request_of(&blank, "survival")
+        .target
+        .is_none());
+
+    // 包名/版本留空时的缺省值也钉一下（预检与写盘共用同一份请求，不能各算一套）
+    let request = super::export::request_of(&blank, "survival");
+    assert_eq!(request.name, "survival");
+    assert_eq!(request.version, "1.0.0");
+}
+
+#[test]
+fn overwrite_is_offered_only_when_importing_into_an_existing_instance() {
+    // 复审 r1 P2-2：新建实例那条路上再点「以包为准」必然撞「directory already exists」
+    let report = unlucky_presenter::dto::ImportReportView {
+        status: ImportStatusView::Partial,
+        format: Some(PackFormatView::Modrinth),
+        pack_name: Some("Pack".to_string()),
+        pack_version: None,
+        game_version: None,
+        loader: None,
+        version_id: None,
+        target: std::path::PathBuf::from("C:/tmp"),
+        files: Vec::new(),
+        conflicts: vec![ConflictFileView {
+            path: "config/x.json".to_string(),
+            reason: ConflictReasonView::UserModified,
+            choice: ConflictChoiceView::KeepUser,
+            pack_sha1: "abc".to_string(),
+            base_sha1: None,
+            disk_sha1: None,
+            pack_size: 1,
+        }],
+        missing: Vec::new(),
+        rejected: Vec::new(),
+        warnings: Vec::new(),
+        error: None,
+        registered: None,
+        bytes_written: 0,
+        rolled_back: true,
+    };
+
+    let new_instance = PackPageState::default();
+    assert!(
+        !super::report::report_of(&report, &new_instance, catalog()).can_overwrite,
+        "新建实例流程下不该出现「以包为准」（那按钮必然失败）"
+    );
+
+    let existing = PackPageState {
+        instance: Some("survival".to_string()),
+        ..PackPageState::default()
+    };
+    assert!(
+        super::report::report_of(&report, &existing, catalog()).can_overwrite,
+        "导入到已有实例时才给翻档动作"
+    );
+}
+
+#[test]
+fn cancelled_state_is_visible_and_says_the_import_keeps_running() {
+    // 复审 r1 P1-2：面板收回之后，界面上必须留一句「后台还在跑」
+    let import = unlucky_presenter::dto::ImportState {
+        cancelled: true,
+        ..unlucky_presenter::dto::ImportState::default()
+    };
+    let export = unlucky_presenter::dto::ExportState::default();
+    let model = Pack::of(&import, &export, &PackPageState::default(), &[], catalog());
+    assert!(model.cancelled);
+    assert!(
+        model.cancelled_note.to_lowercase().contains("background"),
+        "取消提示必须说清后台还在跑：{}",
+        model.cancelled_note
+    );
+    assert!(!model.is_idle(), "取消态不能被当成「什么都没有」");
+}
diff --git a/crates/app-iced/src/pages/content/packui/tests.rs b/crates/app-iced/src/pages/content/packui/tests.rs
new file mode 100644
index 0000000..f0d0d5a
--- /dev/null
+++ b/crates/app-iced/src/pages/content/packui/tests.rs
@@ -0,0 +1,107 @@
+//! 导入/导出区的守门（M113）：四种出图态都装得满、入口文案都在。
+//!
+//! 出图（D30）靠这几条夹具：任何一态装不满，截图就会是一块空容器，而不是「有话说」的界面。
+//! 视图模型的判定在 `model/tests.rs`，这里只管**夹具本身**。
+
+use unlucky_i18n::Lang;
+
+use super::demo::pack_in;
+use super::model::Pack;
+
+/// D30 要求的四态（导入中 / 部分成功 / 冲突选择 / 导出预检）。
+const STATES: [&str; 4] = ["importing", "partial", "conflict", "export"];
+
+#[test]
+fn every_screenshot_state_fills_something() {
+    for state in STATES {
+        let (model, _page) = pack_in(state, Lang::En);
+        assert!(
+            !model.is_idle(),
+            "{state} 这一态什么都没画（截图会是一块空容器）"
+        );
+        assert_eq!(model.targets.len(), 2, "{state} 的实例候选不足");
+        assert!(!model.drop_hint.is_empty());
+        assert!(
+            !model.no_dialog_note.is_empty(),
+            "没有系统文件框这件事必须写在界面上"
+        );
+    }
+}
+
+#[test]
+fn importing_shows_the_shared_install_panel() {
+    let (model, _page) = pack_in("importing", Lang::En);
+    let running = model.running.expect("导入中要有进度");
+    // 进度形状来自下载页那块面板（`Download.install`），不是本区另造的
+    assert!(
+        running
+            .panel
+            .as_ref()
+            .is_some_and(|panel| panel.install.is_some()),
+        "进度必须走下载页的安装面板视图模型"
+    );
+    assert!(
+        running.stage_line.contains("2/5"),
+        "解包阶段是第 2/5 步：{}",
+        running.stage_line
+    );
+    assert!(model.report.is_none(), "导入中不该同时有结果");
+}
+
+#[test]
+fn partial_keeps_the_tolerable_rows_one_by_one() {
+    let (model, _page) = pack_in("partial", Lang::En);
+    let report = model.report.expect("部分成功要有报告");
+    assert!(report.installed(), "Partial 仍是「装上了」");
+    assert!(report.fatal.is_none(), "部分成功不是致命失败");
+    assert_eq!(report.missing.len(), 3, "缺文件要逐条列出");
+    assert!(report.missing_title.is_some());
+    assert!(!report.rejected.is_empty(), "被拒 component 也要逐条");
+}
+
+#[test]
+fn conflict_state_defaults_to_keeping_the_user_copy_and_expands_one_row() {
+    let (model, page) = pack_in("conflict", Lang::En);
+    let report = model.report.expect("冲突态要有报告");
+    assert_eq!(report.conflicts.len(), 3);
+    assert!(
+        report.conflicts.iter().all(|row| !row.expanded)
+            || report.conflicts.iter().filter(|row| row.expanded).count() == 1,
+        "只展开用户点过的那一条"
+    );
+    assert_eq!(
+        report.conflicts.iter().filter(|row| row.expanded).count(),
+        1,
+        "夹具要展开一条，截图才看得见三方哈希"
+    );
+    assert!(page.expanded.is_some());
+    assert!(report.can_overwrite);
+    assert!(report.overwrite_note.is_some());
+}
+
+#[test]
+fn export_state_has_a_preview_but_has_not_written_anything() {
+    let (model, _page) = pack_in("export", Lang::En);
+    assert!(model.export.open);
+    let preview = model.export.preview.expect("预检要有结果");
+    assert!(
+        preview.head.contains('2'),
+        "内联数要进主结论：{}",
+        preview.head
+    );
+    assert!(!preview.skipped.is_empty(), "无法导出的项要逐条");
+    assert!(!preview.complete, "有跳过项 ⇒ 包不完整");
+    assert!(!preview.notes.is_empty(), "已知损失要列出来");
+    assert!(
+        model.export.done.is_none(),
+        "预检阶段不许出现「已写出」（那是写盘之后的事）"
+    );
+}
+
+#[test]
+fn default_state_offers_the_entry_with_nothing_else() {
+    let (model, page): (Pack, _) = pack_in("", Lang::En);
+    assert!(model.is_idle());
+    assert!(!model.export.open);
+    assert!(page.draft.is_empty());
+}
diff --git a/crates/app-iced/src/pages/content/packui/view.rs b/crates/app-iced/src/pages/content/packui/view.rs
new file mode 100644
index 0000000..7e41d0a
--- /dev/null
+++ b/crates/app-iced/src/pages/content/packui/view.rs
@@ -0,0 +1,257 @@
+//! 导入/导出区的画法：入口（拖拽 + 路径）→ 进度（**下载页那块面板**）→ 结果 → 导出预检。
+//!
+//! ## 版面
+//!
+//! ```text
+//! ┌ 导入整合包 ──────────────────────────────────┐
+//! │ ┌ 拖拽区（hover 时变主色描边） ─────────────┐ │
+//! │ └ 路径输入框 ──────────┘ [导入]             │ │
+//! │ [装到实例：chips] [实例名]                   │ │
+//! ├ 进度：步骤 2/5 · 解包覆盖内容                 │
+//! │   <下载页的安装面板：进度条 + 计数 + 取消>      │
+//! ├ 探测失败：看起来像 X，但缺 Y                  │
+//! ├ 结果：三态标题 + 缺文件逐条 + 冲突逐条 + 致命块  │
+//! └ 导出：格式 chips + 预检（将内联 N / 无法导出 M）│
+//! ```
+//!
+//! ## 三处「视觉可区分」不是靠颜色一种通道
+//!
+//! | 域 | 图标 | 颜色角色 | 容器 | 措辞 |
+//! |---|---|---|---|---|
+//! | 容忍（缺文件 / 被拒 component） | `Warn` | `Tertiary` | 无底色 | 「可容忍」 |
+//! | 致命（已回滚） | `Error` | `Error` | `ErrorContainer` | 「已回滚 —— 零残留」 |
+//! | 成功 | `Check` | `Primary` | 无底色 | 「已导入」 |
+//!
+//! 关掉颜色也还认得出（图标 + 措辞），这是任务书「必须视觉可区分」的落点。
+//!
+//! ## 进度只有一份
+//!
+//! 进行中的进度**整块交给** `pages::download::install_panel`（同一个函数、同一套几何与文案）；
+//! 本区只额外画一行 [`Running::stage_line`] 补足「解包 / overrides / 补文件」三档的粒度。
+//!
+//! ## 文件分工（守 400 行）
+//!
+//! | 文件 | 职责 |
+//! |---|---|
+//! | 本文件 | 区入口 + 拖拽区 + 路径输入 + 目标实例 |
+//! | [`parts`] | 三个共用小件（底色容器 / 容忍标题 / 逐条列表） |
+//! | [`progress`] | 进度块（复用面板）与探测失败块 |
+//! | [`report`] | 结果块：三态 + 冲突 + 致命 |
+//! | [`export`] | 导出块与预检块 |
+
+mod export;
+mod parts;
+mod progress;
+mod report;
+
+use iced::widget::{column, container, row};
+use iced::{Alignment, Background, Border, Element, Length};
+
+use unlucky_design::color::Role;
+use unlucky_design::icons::IconKind;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use unlucky_i18n::{Catalog, Key};
+
+use crate::app::components::buttons::{self, Button};
+use crate::app::components::divider;
+use crate::app::components::inputs::{text_field, Field};
+use crate::app::components::selection::{chip, Chip};
+use crate::pages::frame;
+use crate::pages::Message as PageMessage;
+use crate::theme::Ui;
+
+use self::export::export_block;
+use self::progress::{probe_block, running_block};
+use self::report::report_block;
+use super::model::Pack;
+use super::PackMessage;
+
+/// 内容库意图 → 页面消息（唯一的一层包装）。
+pub(super) fn intent(message: PackMessage) -> PageMessage {
+    PageMessage::Content(super::super::Message::Pack(message))
+}
+
+/// 整块（导入入口 + 进度 + 结果 + 导出）。
+pub(crate) fn section<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    model: &'a Pack,
+) -> Element<'a, PageMessage> {
+    let mut block = column![].spacing(ui.space(Space::X3)).width(Length::Fill);
+
+    // **一次只摊开一件事**：入口（拖什么/装到哪）、进度、结果、导出预检各占一态。
+    // 全都堆在一起时，内容库页正列没有整页滚动 ⇒ 动作按钮被顶出屏幕（出图实测：冲突态与
+    // 导出预检态的「确认写盘 / 关闭」都落在 900px 以下）。收起的入口不会丢功能：拖拽是窗口级
+    // 事件，任何时候把文件拖进来都算数。
+    if model.export.open {
+        block = block.push(export_block(ui, catalog, &model.export));
+    } else if let Some(running) = &model.running {
+        block = block.push(running_block(ui, catalog, running));
+    } else if let Some(report) = &model.report {
+        block = block.push(report_block(ui, catalog, report));
+    } else if model.cancelled {
+        // 取消过、还没有新结果：把「后台还在跑」这句话留在屏上（复审 r1 P1-2）
+        block = block.push(
+            column![
+                frame::text_role(
+                    ui,
+                    TypeRole::BodySmall,
+                    false,
+                    model.cancelled_note,
+                    ui.color(Role::Tertiary),
+                ),
+                buttons::text(
+                    ui,
+                    Button::new(catalog.text(Key::PackDismiss), intent(PackMessage::Dismiss)),
+                ),
+            ]
+            .spacing(ui.space(Space::X1))
+            .width(Length::Fill),
+        );
+    } else {
+        block = block.push(entry(ui, catalog, model));
+        if let Some(probe) = &model.probe {
+            // 探测失败要和路径输入框在一起：用户下一步就是改路径
+            block = block.push(probe_block(ui, catalog, probe));
+        }
+        block = block.push(divider::full(ui));
+        block = block.push(export_block(ui, catalog, &model.export));
+    }
+
+    container(block).width(Length::Fill).into()
+}
+
+/// 入口：拖拽区 + 路径输入 + 目标实例。
+fn entry<'a>(ui: &'a Ui, catalog: Catalog, model: &'a Pack) -> Element<'a, PageMessage> {
+    let zone = container(
+        column![
+            frame::text_role(
+                ui,
+                TypeRole::BodyMedium,
+                false,
+                if model.hover {
+                    catalog.text(Key::PackDropActive)
+                } else {
+                    model.drop_hint
+                },
+                ui.color(if model.hover {
+                    Role::Primary
+                } else {
+                    Role::OnSurface
+                }),
+            ),
+            // 没有系统文件框这件事**写在界面上**：不能让用户点了半天「选择文件」找不到按钮
+            frame::text_role(
+                ui,
+                TypeRole::BodySmall,
+                false,
+                model.no_dialog_note,
+                ui.color(Role::OnSurfaceVariant),
+            ),
+        ]
+        .spacing(ui.space(Space::X1))
+        .width(Length::Fill),
+    )
+    .width(Length::Fill)
+    .padding(ui.space(Space::X4))
+    .style(move |_theme| container::Style {
+        border: Border {
+            color: ui.color(if model.hover {
+                Role::Primary
+            } else {
+                Role::Outline
+            }),
+            width: 1.0,
+            radius: ui.radius_dp(ShapeScale::Large),
+        },
+        background: model
+            .hover
+            .then(|| Background::Color(ui.color(Role::PrimaryContainer))),
+        ..container::Style::default()
+    });
+
+    let field = text_field(
+        ui,
+        Field::new(model.draft.as_str())
+            .label(catalog.text(Key::PackPathLabel))
+            .placeholder(catalog.text(Key::PackPathPlaceholder))
+            .leading(IconKind::Folder),
+        move |text| intent(PackMessage::PathChanged(text)),
+    );
+    let submit = buttons::filled(
+        ui,
+        Button::new(
+            catalog.text(Key::PackImportAction),
+            intent(PackMessage::Import),
+        )
+        .leading(IconKind::Folder),
+    );
+
+    let mut block = column![
+        frame::text_role(
+            ui,
+            TypeRole::TitleSmall,
+            true,
+            catalog.text(Key::PackImportTitle),
+            ui.color(Role::OnSurface),
+        ),
+        zone,
+        row![field, submit]
+            .spacing(ui.space(Space::X2))
+            .align_y(Alignment::End)
+            .width(Length::Fill),
+        targets(ui, catalog, model),
+    ]
+    .spacing(ui.space(Space::X2))
+    .width(Length::Fill);
+
+    if model.instance.is_none() {
+        block = block.push(text_field(
+            ui,
+            Field::new(model.instance_name.as_str()).label(catalog.text(Key::PackInstanceName)),
+            move |text| intent(PackMessage::SetInstanceName(text)),
+        ));
+    }
+
+    block.into()
+}
+
+/// 目标实例那一行（chips + 「新建实例」）。
+fn targets<'a>(ui: &'a Ui, catalog: Catalog, model: &'a Pack) -> Element<'a, PageMessage> {
+    let mut chips: Vec<Element<'a, PageMessage>> = Vec::new();
+    for target in &model.targets {
+        chips.push(chip(
+            ui,
+            Chip::filter(
+                target.label.as_str(),
+                model.instance.as_deref() == Some(target.id.as_str()),
+                intent(PackMessage::SetInstance(Some(target.id.clone()))),
+            ),
+        ));
+    }
+    chips.push(chip(
+        ui,
+        Chip::filter(
+            catalog.text(Key::PackTargetNew),
+            model.instance.is_none(),
+            intent(PackMessage::SetInstance(None)),
+        ),
+    ));
+
+    column![
+        frame::text_role(
+            ui,
+            TypeRole::LabelMedium,
+            false,
+            catalog.text(Key::PackTargetLabel),
+            ui.color(Role::OnSurfaceVariant),
+        ),
+        row(chips).spacing(ui.space(Space::X2)).wrap(),
+    ]
+    .spacing(ui.space(Space::X1))
+    .width(Length::Fill)
+    .into()
+}
diff --git a/crates/app-iced/src/pages/content/packui/view/export.rs b/crates/app-iced/src/pages/content/packui/view/export.rs
new file mode 100644
index 0000000..563c1e6
--- /dev/null
+++ b/crates/app-iced/src/pages/content/packui/view/export.rs
@@ -0,0 +1,323 @@
+//! 导出块与预检块：格式选择 → **预检**（不写盘）→ 确认写盘。
+
+use iced::widget::{column, row};
+use iced::{Alignment, Element, Length};
+
+use unlucky_design::color::Role;
+use unlucky_design::icons::IconKind;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use unlucky_i18n::{Catalog, Key};
+
+use crate::app::components::buttons::{self, Button};
+use crate::app::components::inputs::{text_field, Field};
+use crate::app::components::selection::{chip, Chip};
+use crate::pages::frame;
+use crate::pages::Message as PageMessage;
+use crate::theme::Ui;
+
+use super::super::model::{Export, Preview};
+use super::super::PackMessage;
+use super::intent;
+use super::parts::{bounded, rows_block, tolerable_title};
+
+/// 导出块。
+pub(super) fn export_block<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    export: &'a Export,
+) -> Element<'a, PageMessage> {
+    let mut block = column![].spacing(ui.space(Space::X2)).width(Length::Fill);
+
+    if !export.open {
+        block = block.push(
+            row![
+                buttons::outlined(
+                    ui,
+                    Button::new(
+                        catalog.text(Key::PackExportOpen),
+                        intent(PackMessage::OpenExport)
+                    )
+                    .leading(IconKind::Folder),
+                ),
+                frame::text_role(
+                    ui,
+                    TypeRole::BodySmall,
+                    false,
+                    export.format_note,
+                    ui.color(Role::OnSurfaceVariant),
+                ),
+            ]
+            .spacing(ui.space(Space::X2))
+            .align_y(Alignment::Center),
+        );
+    } else {
+        block = block.push(frame::text_role(
+            ui,
+            TypeRole::TitleSmall,
+            true,
+            catalog.text(Key::PackExportTitle),
+            ui.color(Role::OnSurface),
+        ));
+        block = block.push(frame::text_role(
+            ui,
+            TypeRole::LabelMedium,
+            false,
+            catalog.text(Key::PackExportFormat),
+            ui.color(Role::OnSurfaceVariant),
+        ));
+        block = block.push(
+            row(export
+                .formats
+                .iter()
+                .map(|(format, label)| {
+                    chip(
+                        ui,
+                        Chip::filter(
+                            label,
+                            export.format == *format,
+                            intent(PackMessage::SetFormat(*format)),
+                        ),
+                    )
+                })
+                .collect::<Vec<_>>())
+            .spacing(ui.space(Space::X2)),
+        );
+        block = block.push(frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            export.format_note,
+            ui.color(Role::OnSurfaceVariant),
+        ));
+        block = block.push(text_field(
+            ui,
+            Field::new(export.name.as_str()).label(catalog.text(Key::PackExportName)),
+            move |text| intent(PackMessage::SetExportName(text)),
+        ));
+        block = block.push(text_field(
+            ui,
+            Field::new(export.version.as_str()).label(catalog.text(Key::PackExportVersion)),
+            move |text| intent(PackMessage::SetExportVersion(text)),
+        ));
+        // 标签在上、占位在下：**别让占位文字看起来像已填的值**（复审提过这张图的观感）
+        block = block.push(text_field(
+            ui,
+            Field::new(export.output.as_str())
+                .label(catalog.text(Key::PackExportOutput))
+                .placeholder(catalog.text(Key::PackExportOutputPlaceholder)),
+            move |text| intent(PackMessage::SetOutput(text)),
+        ));
+        // 有预检结果时这里只留「预检」（`Back` 交给预览块那一个）——复审 r2 P3-1：
+        // 搬确认按钮进来时把 `Back` 带出了两份，同屏两个一样的按钮
+        let mut actions = row![buttons::filled(
+            ui,
+            Button::new(
+                catalog.text(Key::PackExportPrecheck),
+                intent(PackMessage::Precheck),
+            )
+            .leading(IconKind::Search),
+        )]
+        .spacing(ui.space(Space::X2));
+        if export.preview.is_none() {
+            actions = actions.push(buttons::text(
+                ui,
+                Button::new(
+                    catalog.text(Key::PackExportAbort),
+                    intent(PackMessage::AbortExport),
+                ),
+            ));
+        }
+        block = block.push(actions);
+        if export.pending {
+            block = block.push(frame::text_role(
+                ui,
+                TypeRole::BodySmall,
+                false,
+                export.pending_line,
+                ui.color(Role::OnSurfaceVariant),
+            ));
+        }
+        if let Some(preview) = &export.preview {
+            // 动作在 `preview_block` 里紧跟摘要（明细再长也不会把「确认写盘」顶出屏幕）
+            block = block.push(preview_block(ui, catalog, preview));
+        }
+    }
+
+    if let Some(done) = &export.done {
+        block = block.push(frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            done.as_str(),
+            ui.color(Role::Primary),
+        ));
+    }
+    if let Some(failed) = &export.failed {
+        block = block.push(frame::text_role_owned(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            catalog.render(Key::PackExportFailed, &[("reason", failed)]),
+            ui.color(Role::Error),
+        ));
+    }
+
+    block.into()
+}
+
+/// 预检块：`将内联 N / 无法导出 M` + 逐条跳过项 + 已知损失。
+pub(super) fn preview_block<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    preview: &'a Preview,
+) -> Element<'a, PageMessage> {
+    let mut block = column![
+        frame::text_role(
+            ui,
+            TypeRole::TitleSmall,
+            true,
+            preview.head.as_str(),
+            ui.color(if preview.complete {
+                Role::Primary
+            } else {
+                Role::Tertiary
+            }),
+        ),
+        frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            preview.complete_line.as_str(),
+            ui.color(if preview.complete {
+                Role::OnSurfaceVariant
+            } else {
+                Role::Tertiary
+            }),
+        ),
+        frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            preview.remote_line.as_str(),
+            ui.color(Role::OnSurfaceVariant),
+        ),
+        frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            preview.inline_line.as_str(),
+            ui.color(Role::OnSurfaceVariant),
+        ),
+        frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            preview.target_line.as_str(),
+            ui.color(Role::OnSurfaceVariant),
+        ),
+    ]
+    .spacing(ui.space(Space::X1))
+    .width(Length::Fill);
+
+    // **动作紧跟摘要**：明细（13 条 skipped + 样例 + 已知损失）再长，也不会把
+    // 「Write the pack」顶出 900px（复审 r1 P2-3 的正解：先给结论与动作，明细往下滚）
+    block = block.push(
+        row![
+            buttons::filled(
+                ui,
+                Button::new(
+                    catalog.text(Key::PackExportConfirm),
+                    intent(PackMessage::Confirm),
+                ),
+            ),
+            buttons::text(
+                ui,
+                Button::new(
+                    catalog.text(Key::PackExportAbort),
+                    intent(PackMessage::AbortExport)
+                ),
+            ),
+        ]
+        .spacing(ui.space(Space::X2))
+        .align_y(Alignment::Center),
+    );
+
+    if !preview.skipped.is_empty() {
+        // 标题写成「Not in the pack: 13」而不是「逐条列出」：13 条**确实**全列出来了，
+        // 但下面那个「…还有 N 个（这里不展开）」说的是**内联样例**，两句挨着容易被读成矛盾
+        block = block.push(tolerable_title(
+            ui,
+            catalog.render(
+                Key::PackPreviewSkippedTitle,
+                &[("count", &preview.skipped.len().to_string())],
+            ),
+        ));
+        // 13 条是真实形态：摊开会把「Write the pack」顶出 900px（复审 r1 P2-3）
+        block = block.push(bounded(
+            ui,
+            rows_block(ui, catalog, &preview.skipped),
+            preview.skipped.len(),
+            3,
+            110.0,
+        ));
+    }
+
+    // 样例 + 已知损失一起套有界滚动：预检是「摊开给你看」的块，条目多时它会把
+    // 「确认写盘」顶出屏幕（出图时实测到了）
+    let mut extras = column![].spacing(ui.space(Space::X1)).width(Length::Fill);
+    if !preview.inline_sample.is_empty() {
+        // 给样例一句自己的标题 + 说明只列前几条（截断要说出来）
+        extras = extras.push(frame::text_role_owned(
+            ui,
+            TypeRole::LabelMedium,
+            false,
+            catalog.render(
+                Key::PackPreviewInlineTitle,
+                &[("shown", &preview.inline_sample.len().to_string())],
+            ),
+            ui.color(Role::OnSurfaceVariant),
+        ));
+    }
+    for path in &preview.inline_sample {
+        extras = extras.push(frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            path.as_str(),
+            ui.color(Role::OnSurfaceVariant),
+        ));
+    }
+    if let Some(more) = &preview.more_line {
+        extras = extras.push(frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            more.as_str(),
+            ui.color(Role::OnSurfaceVariant),
+        ));
+    }
+    if !preview.notes.is_empty() {
+        extras = extras.push(frame::text_role(
+            ui,
+            TypeRole::LabelMedium,
+            false,
+            catalog.text(Key::PackPreviewNotes),
+            ui.color(Role::OnSurfaceVariant),
+        ));
+        for note in &preview.notes {
+            extras = extras.push(frame::text_role(
+                ui,
+                TypeRole::BodySmall,
+                false,
+                note.as_str(),
+                ui.color(Role::OnSurfaceVariant),
+            ));
+        }
+    }
+    let extras_rows = preview.inline_sample.len() + preview.notes.len();
+    block = block.push(bounded(ui, extras, extras_rows, 3, 120.0));
+
+    block.into()
+}
diff --git a/crates/app-iced/src/pages/content/packui/view/parts.rs b/crates/app-iced/src/pages/content/packui/view/parts.rs
new file mode 100644
index 0000000..a0e5156
--- /dev/null
+++ b/crates/app-iced/src/pages/content/packui/view/parts.rs
@@ -0,0 +1,128 @@
+//! 共用小件：带底色的容器、容忍域的标题、逐条列表。
+//!
+//! 三个都在两个以上地方用到，所以单独一个文件——不是为了行数好看，是因为
+//! 「容忍域长什么样」只有一处定义，改颜色/图标才不用找第二个副本。
+
+use iced::widget::{column, container, row};
+use iced::{Alignment, Background, Border, Element, Length};
+
+use unlucky_design::color::Role;
+use unlucky_design::icons::IconKind;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use unlucky_i18n::Catalog;
+
+use crate::pages::frame;
+use crate::pages::Message as PageMessage;
+use crate::theme::Ui;
+
+use super::super::model::Row;
+
+/// 带底色的容器（探测块与致命块共用；颜色由调用方给）。
+pub(super) fn marker_box<'a>(
+    ui: &'a Ui,
+    role: Role,
+    content: impl Into<Element<'a, PageMessage>>,
+) -> Element<'a, PageMessage> {
+    let role = ui.color(role);
+    container(content.into())
+        .width(Length::Fill)
+        .padding(ui.space(Space::X3))
+        .style(move |_theme| container::Style {
+            background: Some(Background::Color(role)),
+            border: Border {
+                radius: ui.radius_dp(ShapeScale::Large),
+                ..Border::default()
+            },
+            ..container::Style::default()
+        })
+        .into()
+}
+
+/// 容忍域的标题（`Warn` 图标 + 三级色）。
+///
+/// 收 `String` 而不是 `&str`：标题要带计数（`Not in the pack: 13`），而计数是运行时 `format!`
+/// 出来的，借用不出去。
+pub(super) fn tolerable_title(ui: &Ui, title: String) -> Element<'_, PageMessage> {
+    row![
+        frame::glyph(IconKind::Warn, ui.color(Role::Tertiary), frame::ICON_PX),
+        frame::text_role_owned(
+            ui,
+            TypeRole::LabelLarge,
+            true,
+            title,
+            ui.color(Role::Tertiary),
+        ),
+    ]
+    .spacing(ui.space(Space::X2))
+    .align_y(Alignment::Center)
+    .into()
+}
+
+pub(super) fn rows_block<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    rows: &'a [Row],
+) -> Element<'a, PageMessage> {
+    let _ = catalog;
+    column(
+        rows.iter()
+            .map(|row| {
+                row![
+                    frame::text_role(
+                        ui,
+                        TypeRole::BodySmall,
+                        false,
+                        row.path.as_str(),
+                        ui.color(Role::OnSurface),
+                    ),
+                    frame::text_role(
+                        ui,
+                        TypeRole::BodySmall,
+                        false,
+                        row.note.as_str(),
+                        ui.color(Role::OnSurfaceVariant),
+                    ),
+                ]
+                .spacing(ui.space(Space::X2))
+                .width(Length::Fill)
+                .into()
+            })
+            .collect::<Vec<_>>(),
+    )
+    .spacing(ui.space(Space::X1))
+    .width(Length::Fill)
+    .into()
+}
+
+/// 逐条列表的**有界**容器：条目多时给一个固定高度的滚动区。
+///
+/// 为什么必须要有界：这一块长在内容库页正列的上方，而整页没有滚动（只有结果列表自己滚）⇒
+/// 报告一长，「关闭 / 以包为准重新导入 / 确认写盘」这些动作就被顶出屏幕。出图时实测到了这一点
+/// （冲突态与导出预检态的动作按钮落在 900px 以下）。
+///
+/// 少于 `rows_threshold` 条时直接铺开：给两行内容套一个 120px 的空框，比溢出更难看。
+pub(super) fn bounded<'a>(
+    ui: &'a Ui,
+    content: impl Into<Element<'a, PageMessage>>,
+    rows: usize,
+    rows_threshold: usize,
+    height: f32,
+) -> Element<'a, PageMessage> {
+    let content = content.into();
+    if rows <= rows_threshold {
+        return content;
+    }
+    iced::widget::scrollable(content)
+        .height(Length::Fixed(height))
+        .direction(iced::widget::scrollable::Direction::Vertical(
+            iced::widget::scrollable::Scrollbar::new()
+                .width(frame::SCROLLBAR_WIDTH)
+                .scroller_width(frame::SCROLLBAR_WIDTH)
+                .margin(frame::SCROLLBAR_MARGIN),
+        ))
+        .style(frame::scroll_style(ui))
+        .into()
+}
diff --git a/crates/app-iced/src/pages/content/packui/view/progress.rs b/crates/app-iced/src/pages/content/packui/view/progress.rs
new file mode 100644
index 0000000..2afb9cf
--- /dev/null
+++ b/crates/app-iced/src/pages/content/packui/view/progress.rs
@@ -0,0 +1,97 @@
+//! 进度块（**整块复用下载页的安装面板**）与探测失败块。
+
+use iced::widget::{column, row};
+use iced::{Alignment, Element, Length};
+
+use unlucky_design::color::Role;
+use unlucky_design::icons::IconKind;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use unlucky_i18n::{Catalog, Key};
+
+use crate::app::components::buttons::{self, Button};
+use crate::pages::download;
+use crate::pages::frame;
+use crate::pages::Message as PageMessage;
+use crate::theme::Ui;
+
+use super::super::model::{Probe, Running};
+use super::super::PackMessage;
+use super::intent;
+use super::parts::marker_box;
+
+/// 进行中：一行步骤说明 + **下载页那块面板**。
+pub(super) fn running_block<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    running: &'a Running,
+) -> Element<'a, PageMessage> {
+    let mut block = column![frame::text_role(
+        ui,
+        TypeRole::LabelMedium,
+        false,
+        running.stage_line.as_str(),
+        ui.color(Role::OnSurfaceVariant),
+    )]
+    .spacing(ui.space(Space::X1))
+    .width(Length::Fill);
+
+    // 同一块面板：进度条、计数行、取消按钮都归它，这里不另画一条。
+    // `None` 只会在「阶段已收尾」时出现（导入的五个阶段都不是终态），那时只剩步骤行。
+    if let Some(panel) = &running.panel {
+        block = block.push(download::install_panel(ui, catalog, panel));
+    }
+    block.into()
+}
+
+/// 探测失败：把「缺哪个标记」摊开。
+pub(super) fn probe_block<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    probe: &'a Probe,
+) -> Element<'a, PageMessage> {
+    let mut block = column![
+        row![
+            frame::glyph(IconKind::Warn, ui.color(Role::Tertiary), frame::ICON_PX),
+            frame::text_role(
+                ui,
+                TypeRole::TitleSmall,
+                true,
+                catalog.text(Key::PackProbeTitle),
+                ui.color(Role::Tertiary),
+            ),
+        ]
+        .spacing(ui.space(Space::X2))
+        .align_y(Alignment::Center),
+        frame::text_role(
+            ui,
+            TypeRole::BodyMedium,
+            false,
+            probe.lead.as_str(),
+            ui.color(Role::OnSurface),
+        ),
+        frame::text_role_owned(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            catalog.render(Key::PackProbeSaw, &[("saw", &probe.saw.join(" · "))]),
+            ui.color(Role::OnSurfaceVariant),
+        ),
+        frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            probe.detail.as_str(),
+            ui.color(Role::OnSurfaceVariant),
+        ),
+    ]
+    .spacing(ui.space(Space::X1))
+    .width(Length::Fill);
+
+    block = block.push(buttons::text(
+        ui,
+        Button::new(catalog.text(Key::PackDismiss), intent(PackMessage::Dismiss)),
+    ));
+    marker_box(ui, Role::TertiaryContainer, block)
+}
diff --git a/crates/app-iced/src/pages/content/packui/view/report.rs b/crates/app-iced/src/pages/content/packui/view/report.rs
new file mode 100644
index 0000000..8cc8f1d
--- /dev/null
+++ b/crates/app-iced/src/pages/content/packui/view/report.rs
@@ -0,0 +1,296 @@
+//! 结果块：三态标题 + 容忍域逐条 + 冲突逐条 + 致命块。
+
+use iced::widget::{column, row};
+use iced::{Alignment, Element, Length};
+
+use unlucky_design::color::Role;
+use unlucky_design::icons::IconKind;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use unlucky_i18n::{Catalog, Key};
+
+use crate::app::components::buttons::{self, Button};
+use crate::pages::frame;
+use crate::pages::Message as PageMessage;
+use crate::theme::Ui;
+
+use super::super::model::{ConflictRow, Report};
+use super::super::PackMessage;
+use super::intent;
+use super::parts::{bounded, marker_box, rows_block, tolerable_title};
+
+/// 结果块。
+pub(super) fn report_block<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    report: &'a Report,
+) -> Element<'a, PageMessage> {
+    let mut block = column![
+        row![
+            frame::glyph(
+                status_icon(report),
+                ui.color(status_role(report)),
+                frame::ICON_PX
+            ),
+            frame::text_role(
+                ui,
+                TypeRole::TitleSmall,
+                true,
+                report.title.as_str(),
+                ui.color(status_role(report)),
+            ),
+        ]
+        .spacing(ui.space(Space::X2))
+        .align_y(Alignment::Center),
+        frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            report.subtitle.as_str(),
+            ui.color(Role::OnSurfaceVariant),
+        ),
+        frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            report.written_line.as_str(),
+            ui.color(Role::OnSurfaceVariant),
+        ),
+    ]
+    .spacing(ui.space(Space::X1))
+    .width(Length::Fill);
+
+    if let Some(fatal) = &report.fatal {
+        block = block.push(marker_box(
+            ui,
+            Role::ErrorContainer,
+            column![
+                frame::text_role(
+                    ui,
+                    TypeRole::LabelLarge,
+                    true,
+                    fatal.title.as_str(),
+                    ui.color(Role::OnErrorContainer),
+                ),
+                frame::text_role_owned(
+                    ui,
+                    TypeRole::BodyMedium,
+                    false,
+                    format!("{} · {}", fatal.label, fatal.code),
+                    ui.color(Role::OnErrorContainer),
+                ),
+                frame::text_role(
+                    ui,
+                    TypeRole::BodySmall,
+                    false,
+                    fatal.message.as_str(),
+                    ui.color(Role::OnErrorContainer),
+                ),
+            ]
+            .spacing(ui.space(Space::X1))
+            .width(Length::Fill),
+        ));
+        if let Some(hint) = &fatal.hint {
+            block = block.push(
+                row![
+                    frame::text_role(
+                        ui,
+                        TypeRole::LabelMedium,
+                        false,
+                        catalog.text(Key::PackFatalHint),
+                        ui.color(Role::OnSurfaceVariant),
+                    ),
+                    frame::text_role(
+                        ui,
+                        TypeRole::BodySmall,
+                        false,
+                        hint.as_str(),
+                        ui.color(Role::OnSurfaceVariant),
+                    ),
+                ]
+                .spacing(ui.space(Space::X2)),
+            );
+        }
+    }
+
+    // 容忍域（缺文件 / 被拒 component）：中性容器 + `Warn` 图标 + 逐条
+    if let Some(title) = &report.missing_title {
+        block = block.push(
+            column![
+                tolerable_title(ui, title.clone()),
+                bounded(
+                    ui,
+                    rows_block(ui, catalog, &report.missing),
+                    report.missing.len(),
+                    3,
+                    120.0,
+                ),
+            ]
+            .spacing(ui.space(Space::X1))
+            .width(Length::Fill),
+        );
+    }
+    if let Some(title) = &report.rejected_title {
+        // 没有这句的话，「Could not fetch (tolerated): 3」下面会多出一行没有归属的
+        // 「not supported by the client」（复审 r1 P2-4）
+        block = block.push(
+            column![
+                tolerable_title(ui, title.clone()),
+                // 与 missing / conflicts 同一条口径：条目多时框起来滚，别把动作顶出屏幕
+                bounded(
+                    ui,
+                    rows_block(ui, catalog, &report.rejected),
+                    report.rejected.len(),
+                    3,
+                    110.0,
+                ),
+            ]
+            .spacing(ui.space(Space::X1))
+            .width(Length::Fill),
+        );
+    }
+
+    if let Some(title) = &report.conflicts_title {
+        block = block.push(
+            column![
+                tolerable_title(ui, title.clone()),
+                bounded(
+                    ui,
+                    column(
+                        report
+                            .conflicts
+                            .iter()
+                            .map(|conflict| conflict_row(ui, catalog, conflict))
+                            .collect::<Vec<_>>()
+                    )
+                    .spacing(ui.space(Space::X1))
+                    .width(Length::Fill),
+                    report.conflicts.len(),
+                    2,
+                    160.0,
+                ),
+            ]
+            .spacing(ui.space(Space::X1))
+            .width(Length::Fill),
+        );
+    }
+
+    for warning in &report.warnings {
+        block = block.push(frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            warning.as_str(),
+            ui.color(Role::OnSurfaceVariant),
+        ));
+    }
+
+    if let Some(note) = &report.overwrite_note {
+        block = block.push(frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            note.as_str(),
+            ui.color(Role::OnSurfaceVariant),
+        ));
+    }
+
+    let mut actions = row![]
+        .spacing(ui.space(Space::X2))
+        .align_y(Alignment::Center);
+    if report.can_overwrite {
+        actions = actions.push(buttons::outlined(
+            ui,
+            Button::new(
+                catalog.text(Key::PackOverwriteAction),
+                intent(PackMessage::Overwrite),
+            )
+            .leading(IconKind::Refresh),
+        ));
+    }
+    actions = actions.push(buttons::text(
+        ui,
+        Button::new(catalog.text(Key::PackDismiss), intent(PackMessage::Dismiss)),
+    ));
+    block = block.push(actions);
+
+    block.into()
+}
+
+/// 一条冲突：路径 + 成因 + 本次处置（点一行展开三方哈希）。
+pub(super) fn conflict_row<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    conflict: &'a ConflictRow,
+) -> Element<'a, PageMessage> {
+    let head = row![
+        frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            conflict.path.as_str(),
+            ui.color(Role::OnSurface),
+        ),
+        frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            conflict.reason.as_str(),
+            ui.color(Role::OnSurfaceVariant),
+        ),
+        frame::text_role(
+            ui,
+            TypeRole::LabelMedium,
+            false,
+            conflict.choice.as_str(),
+            ui.color(Role::Tertiary),
+        ),
+        buttons::text(
+            ui,
+            Button::new(
+                catalog.text(Key::PackConflictDetail),
+                intent(PackMessage::ToggleConflict(conflict.path.clone())),
+            )
+            .leading(IconKind::ChevronDown),
+        ),
+    ]
+    .spacing(ui.space(Space::X2))
+    .align_y(Alignment::Center)
+    .width(Length::Fill);
+
+    let mut block = column![head].width(Length::Fill);
+    if conflict.expanded {
+        block = block.push(frame::text_role_owned(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            catalog.render(
+                Key::PackConflictHashes,
+                &[
+                    ("pack", conflict.pack_sha1.as_str()),
+                    ("base", conflict.base_sha1.as_deref().unwrap_or("—")),
+                    ("disk", conflict.disk_sha1.as_deref().unwrap_or("—")),
+                ],
+            ),
+            ui.color(Role::OnSurfaceVariant),
+        ));
+    }
+    block.into()
+}
+
+pub(super) fn status_icon(report: &Report) -> IconKind {
+    match report.status {
+        unlucky_presenter::dto::ImportStatusView::Success => IconKind::Check,
+        unlucky_presenter::dto::ImportStatusView::Partial => IconKind::Warn,
+        unlucky_presenter::dto::ImportStatusView::Failed => IconKind::Error,
+    }
+}
+
+pub(super) fn status_role(report: &Report) -> Role {
+    match report.status {
+        unlucky_presenter::dto::ImportStatusView::Success => Role::Primary,
+        unlucky_presenter::dto::ImportStatusView::Partial => Role::Tertiary,
+        unlucky_presenter::dto::ImportStatusView::Failed => Role::Error,
+    }
+}
diff --git a/crates/app-iced/src/pages/content/parts.rs b/crates/app-iced/src/pages/content/parts.rs
new file mode 100644
index 0000000..45bebfb
--- /dev/null
+++ b/crates/app-iced/src/pages/content/parts.rs
@@ -0,0 +1,338 @@
+//! 内容库页的零件：筛选条 / 结果列表 / 详情面板 / 四态（加载 / 空 / 失败 / 无更多）/ 一级切换。
+//!
+//! 全是既有真组件（`chip` / `list_item` / `buttons` / `empty_state`），页面不自己画状态层。
+//!
+//! ## 消息口径
+//!
+//! 本文件的每个控件都直接发 [`crate::pages::Message`]：内容库自己的意图包一层
+//! `PageMessage::Content(..)`（[`intent`]），而「取消安装 / 打开日志」用的是**下载页就有的**
+//! 那两个变体——因为对用户来说它们是同一件事（同一个 `AppCommand::CancelInstall`）。
+
+use iced::widget::{column, container, row, scrollable};
+use iced::{Alignment, Element, Length, Padding};
+
+use unlucky_design::color::Role;
+use unlucky_design::icons::IconKind;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use unlucky_i18n::{Catalog, Key};
+use unlucky_presenter::dto::ContentSort;
+use unlucky_presenter::router::Route;
+
+use crate::app::components::buttons::{self, Button};
+use crate::app::components::feedback::{empty_state, EmptyState};
+use crate::app::components::navigation::list_item::{list_item, ListItem};
+use crate::app::components::selection::{chip, Chip};
+use crate::theme::Ui;
+
+use super::layout::Rails;
+use super::model::{Content, Hit, Status};
+
+mod detail;
+mod filters;
+
+pub(crate) use detail::detail;
+pub(crate) use filters::{filters, labelled};
+
+use super::Message as ContentMessage;
+use crate::pages::frame;
+use crate::pages::Message as PageMessage;
+
+/// 内容库意图 → 页面消息（唯一的一层包装）。
+pub(super) fn intent(message: ContentMessage) -> PageMessage {
+    PageMessage::Content(message)
+}
+
+/// 结果行与行之间的间距（与下载页同值）。
+const ROW_GAP: Space = Space::X1;
+
+/// 一级切换：版本管理 | 内容库（M109 按 B1 裁定：共用同一条导航轨项，页内切换）。
+pub(super) fn section_switcher<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    on_content: bool,
+) -> Element<'a, PageMessage> {
+    let versions = Chip::filter(
+        catalog.text(Key::ContentSectionVersions),
+        !on_content,
+        PageMessage::Navigate(Route::Download),
+    );
+    let content = Chip::filter(
+        catalog.text(Key::ContentSectionContent),
+        on_content,
+        PageMessage::Navigate(Route::Content),
+    );
+    row![chip(ui, versions), chip(ui, content)]
+        .spacing(ui.space(Space::X2))
+        .align_y(Alignment::Center)
+        .into()
+}
+
+/// 关键词搜索条（输入只改草稿；回车/按钮才发检索指令）。
+pub(super) fn search<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    model: &'a Content,
+) -> Element<'a, PageMessage> {
+    // 输入只改草稿，**提交**才发检索（每敲一个字就打一次网络既没必要也会被限流）。
+    // 搜索条自身没有提交回调，所以旁边给一个显式的「搜索」按钮——这也是键盘外的唯一出口。
+    let bar = crate::app::components::inputs::search_bar(
+        ui,
+        crate::app::components::inputs::SearchBar::new(model.draft.as_str())
+            .placeholder(catalog.text(Key::ContentSearchPlaceholder)),
+        move |text| intent(ContentMessage::QueryChanged(text)),
+    );
+    let submit = crate::app::components::buttons::text(
+        ui,
+        crate::app::components::buttons::Button::new(
+            catalog.text(Key::ContentSearch),
+            intent(ContentMessage::Search),
+        )
+        .leading(IconKind::Search),
+    );
+    row![bar, submit]
+        .spacing(ui.space(Space::X2))
+        .align_y(Alignment::Center)
+        .width(Length::Fill)
+        .into()
+}
+
+/// 结果列表（独立滚动；底部「加载更多」钉在列表之外，见 [`more`]）。
+pub(super) fn list<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    model: &'a Content,
+    rails: Rails,
+) -> Element<'a, PageMessage> {
+    let rows = column(
+        model
+            .hits
+            .iter()
+            .map(|hit| hit_row(ui, model, hit))
+            .collect::<Vec<_>>(),
+    )
+    .spacing(ui.space(ROW_GAP))
+    .padding(Padding::from([0.0, ui.space(Space::X2)]))
+    .width(Length::Fill);
+
+    let _ = catalog;
+    container(
+        scrollable(rows)
+            .direction(scrollable::Direction::Vertical(
+                scrollable::Scrollbar::new()
+                    .width(frame::SCROLLBAR_WIDTH)
+                    .scroller_width(frame::SCROLLBAR_WIDTH)
+                    .margin(frame::SCROLLBAR_MARGIN),
+            ))
+            .height(Length::Fill)
+            .style(frame::scroll_style(ui)),
+    )
+    .width(Length::Fixed(rails.list))
+    .height(Length::Fill)
+    .into()
+}
+
+fn hit_row<'a>(ui: &'a Ui, model: &Content, hit: &'a Hit) -> Element<'a, PageMessage> {
+    let mut item = ListItem::new(
+        hit.title.as_str(),
+        intent(ContentMessage::Select(hit.id.clone())),
+    )
+    .overline(hit.supporting.as_str())
+    .supporting(hit.summary.as_str())
+    .leading(kind_icon(model.kind));
+    if model.selected.as_deref() == Some(hit.id.as_str()) {
+        item = item.selected();
+    }
+    list_item(ui, item)
+}
+
+/// 计数头 + 翻页尾（分页而非无限滚动：见 `pages/content.rs` 的模块文档）。
+pub(super) fn count_head<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    model: &Content,
+) -> Element<'a, PageMessage> {
+    let count = if model.total > 0 {
+        model.total
+    } else {
+        u32::try_from(model.hits.len()).unwrap_or(u32::MAX)
+    };
+    frame::text_role_owned(
+        ui,
+        TypeRole::LabelMedium,
+        false,
+        catalog.render(
+            Key::ContentCount,
+            &[("count", &super::model::thousands(u64::from(count)))],
+        ),
+        ui.color(Role::OnSurfaceVariant),
+    )
+}
+
+/// 列表尾部：还有更多 ⇒「加载更多」；没有了 ⇒ 一句「没有更多了」。
+pub(super) fn more<'a>(ui: &'a Ui, catalog: Catalog, model: &Content) -> Element<'a, PageMessage> {
+    if model.has_more {
+        return buttons::text(
+            ui,
+            Button::new(
+                catalog.text(Key::ContentLoadMore),
+                intent(ContentMessage::LoadMore),
+            )
+            .leading(IconKind::ChevronDown),
+        );
+    }
+    frame::text_role(
+        ui,
+        TypeRole::BodySmall,
+        false,
+        catalog.text(Key::ContentNoMore),
+        ui.color(Role::OnSurfaceVariant),
+    )
+}
+
+pub(super) fn loading<'a>(ui: &'a Ui, catalog: Catalog) -> Element<'a, PageMessage> {
+    centered(
+        column![
+            frame::text_role_centered(
+                ui,
+                TypeRole::TitleMedium,
+                true,
+                catalog.text(Key::ContentLoading),
+                ui.color(Role::OnSurface)
+            ),
+            frame::text_role_centered(
+                ui,
+                TypeRole::BodySmall,
+                false,
+                catalog.text(Key::ContentLoadingHint),
+                ui.color(Role::OnSurfaceVariant)
+            ),
+            buttons::text(
+                ui,
+                Button::new(
+                    catalog.text(Key::ContentRetry),
+                    intent(ContentMessage::Retry)
+                )
+            ),
+        ]
+        .spacing(ui.space(Space::X3))
+        .width(Length::Fill)
+        .align_x(Alignment::Center),
+    )
+}
+
+/// 空态（真 `EmptyState`：CTA 是标准 Filled 按钮）。
+pub(super) fn empty<'a>(ui: &'a Ui, catalog: Catalog) -> Element<'a, PageMessage> {
+    centered(empty_state(
+        ui,
+        EmptyState::new(
+            IconKind::Search,
+            catalog.text(Key::ContentEmptyTitle),
+            catalog.text(Key::ContentEmptyBody),
+        )
+        .action(
+            catalog.text(Key::ContentRetry),
+            intent(ContentMessage::Retry),
+        ),
+    ))
+}
+
+/// 失败态（带原因与重试出口；原因来自 host，不打码不打折）。
+pub(super) fn failed<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    reason: &'a str,
+) -> Element<'a, PageMessage> {
+    centered(
+        column![
+            row![
+                frame::glyph(IconKind::Error, ui.color(Role::Error), frame::ICON_PX),
+                frame::text_role(
+                    ui,
+                    TypeRole::TitleSmall,
+                    true,
+                    catalog.text(Key::ContentFailedTitle),
+                    ui.color(Role::Error)
+                ),
+            ]
+            .spacing(ui.space(Space::X2))
+            .align_y(Alignment::Center),
+            frame::text_role(
+                ui,
+                TypeRole::BodySmall,
+                false,
+                reason,
+                ui.color(Role::OnSurfaceVariant)
+            ),
+            frame::text_role(
+                ui,
+                TypeRole::BodySmall,
+                false,
+                catalog.text(Key::ContentFailedBody),
+                ui.color(Role::OnSurfaceVariant)
+            ),
+            buttons::filled(
+                ui,
+                Button::new(
+                    catalog.text(Key::ContentRetry),
+                    intent(ContentMessage::Retry)
+                )
+                .leading(IconKind::Refresh)
+            ),
+        ]
+        .spacing(ui.space(Space::X3))
+        .width(Length::Fill)
+        .align_x(Alignment::Center),
+    )
+}
+
+fn centered<'a>(content: impl Into<Element<'a, PageMessage>>) -> Element<'a, PageMessage> {
+    container(content)
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .align_x(Alignment::Center)
+        .align_y(Alignment::Center)
+        .into()
+}
+
+/// 内容类型 → 图标（**借用**现有字形：图标集里还没有「整合包/Mod/资源包/光影」四枚专用图标，
+/// 已在报告里登记为偏离）。
+pub(super) const fn kind_icon(kind: unlucky_presenter::dto::ContentKind) -> IconKind {
+    // 两条硬约束（都来自门禁与复审）：
+    // ① `Play`/`Stop`/`More` 是**填充**字形，pages 里禁用（`tests/no_hardcoded_tokens`）；
+    // ② **不许与全局导航撞形**：`Instances`/`Download`/`Logs`/`Settings`/`Ai` 五枚在同一个屏上
+    //    就在左边那条轨里，页内四类再借用它们会让「同形不同义」（复审 P2-3）。
+    //
+    // 剩下的描边字形里挑语义最近的：
+    // `Folder`（包=文件夹）/ `Plus`（加装内容=加号）/ `Restore`（双层方框≈贴图分层）/ `Expand`（四散光线）。
+    match kind {
+        unlucky_presenter::dto::ContentKind::Modpack => IconKind::Folder,
+        unlucky_presenter::dto::ContentKind::Mod => IconKind::Plus,
+        unlucky_presenter::dto::ContentKind::Resourcepack => IconKind::Restore,
+        unlucky_presenter::dto::ContentKind::Shader => IconKind::Expand,
+    }
+}
+
+pub(super) fn sort_label(sort: ContentSort, catalog: Catalog) -> &'static str {
+    match sort {
+        ContentSort::Relevance => catalog.text(Key::ContentSortRelevance),
+        ContentSort::Downloads => catalog.text(Key::ContentSortDownloads),
+        ContentSort::Newest => catalog.text(Key::ContentSortNewest),
+        ContentSort::Updated => catalog.text(Key::ContentSortUpdated),
+    }
+}
+
+/// 状态分派（四态各一支；`Ready` 由调用方画列表 + 详情）。
+pub(super) fn status_body<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    model: &'a Content,
+) -> Option<Element<'a, PageMessage>> {
+    match &model.status {
+        Status::Loading => Some(loading(ui, catalog)),
+        Status::Empty => Some(empty(ui, catalog)),
+        Status::Failed(reason) => Some(failed(ui, catalog, reason.as_str())),
+        Status::Ready => None,
+    }
+}
diff --git a/crates/app-iced/src/pages/content/parts/detail.rs b/crates/app-iced/src/pages/content/parts/detail.rs
new file mode 100644
index 0000000..5d616a1
--- /dev/null
+++ b/crates/app-iced/src/pages/content/parts/detail.rs
@@ -0,0 +1,179 @@
+//! 详情面板：选中项的支持范围 + 目标实例 + 装入（不兼容时**禁用并逐条给原因**）。
+//!
+//! 从 `pages/content/parts.rs` 拆出（那个文件已贴 400 行硬上限）。
+//!
+//! 这块是「一键装入指定实例」的**唯一**入口：按钮能不能按由 [`Content::can_install`] 决定，
+//! 按不动时旁边逐条列出原因——判定与画法分开，`model/tests.rs` 才能不开图形环境就钉住它。
+
+use iced::widget::{column, container};
+use iced::{Element, Length};
+
+use unlucky_design::color::Role;
+use unlucky_design::icons::IconKind;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use unlucky_i18n::{Catalog, Key};
+
+use crate::app::components::buttons::{self, Button};
+use crate::app::components::divider;
+use crate::app::components::selection::{chip, Chip};
+use crate::theme::Ui;
+
+use super::super::model::{capitalize, Content};
+use super::super::Message as ContentMessage;
+use super::{intent, labelled};
+use crate::pages::frame;
+use crate::pages::Message as PageMessage;
+
+/// 详情面板：选中项的支持范围 + 目标实例 + 装入（不兼容时**禁用并给原因**）。
+pub(crate) fn detail<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    model: &'a Content,
+) -> Element<'a, PageMessage> {
+    let Some(hit) = model.selected_hit() else {
+        return container(frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            catalog.text(Key::ContentDetailEmpty),
+            ui.color(Role::OnSurfaceVariant),
+        ))
+        .width(Length::Fill)
+        .into();
+    };
+
+    let head = column![
+        frame::text_role(
+            ui,
+            TypeRole::TitleMedium,
+            true,
+            hit.title.as_str(),
+            ui.color(Role::OnSurface)
+        ),
+        frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            hit.supporting.as_str(),
+            ui.color(Role::OnSurfaceVariant),
+        ),
+        frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            hit.summary.as_str(),
+            ui.color(Role::OnSurfaceVariant),
+        ),
+    ]
+    .spacing(ui.space(Space::X1))
+    .width(Length::Fill);
+
+    let meta = column![
+        frame::text_role(
+            ui,
+            TypeRole::LabelMedium,
+            false,
+            hit.downloads.as_str(),
+            ui.color(Role::OnSurfaceVariant)
+        ),
+        frame::text_role(
+            ui,
+            TypeRole::LabelMedium,
+            false,
+            hit.updated.as_str(),
+            ui.color(Role::OnSurfaceVariant)
+        ),
+        support_line(ui, catalog, Key::ContentDetailVersions, &hit.versions),
+        support_line(ui, catalog, Key::ContentDetailLoaders, &hit.loaders),
+    ]
+    .spacing(ui.space(Space::X1))
+    .width(Length::Fill);
+
+    let mut body = column![head, divider::full(ui), meta].spacing(ui.space(Space::X3));
+
+    // 目标实例：一行 chip（选中的那个高亮）
+    if model.targets.is_empty() {
+        body = body.push(frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            catalog.text(Key::ContentNoInstances),
+            ui.color(Role::OnSurfaceVariant),
+        ));
+    } else {
+        let mut targets = Vec::new();
+        for target in &model.targets {
+            targets.push(chip(
+                ui,
+                Chip::filter(
+                    target.name.as_str(),
+                    model.target.as_deref() == Some(target.id.as_str()),
+                    intent(ContentMessage::SetTarget(target.id.clone())),
+                ),
+            ));
+        }
+        body = body.push(labelled(
+            ui,
+            catalog.text(Key::ContentTargetInstance),
+            targets,
+        ));
+    }
+
+    // 装入：能装 ⇒ 实心按钮；不能 ⇒ 禁用 + 逐条原因（**点之前**就说清楚）
+    if model.can_install() {
+        body = body.push(buttons::filled(
+            ui,
+            Button::new(
+                catalog.text(Key::ContentInstall),
+                intent(ContentMessage::Install),
+            )
+            .leading(IconKind::Download),
+        ));
+    } else {
+        body = body.push(buttons::outlined(
+            ui,
+            Button::disabled(catalog.text(Key::ContentInstall)),
+        ));
+        for reason in model.blocker_reasons(catalog) {
+            body = body.push(frame::text_role_owned(
+                ui,
+                TypeRole::BodySmall,
+                false,
+                reason,
+                ui.color(Role::OnSurfaceVariant),
+            ));
+        }
+    }
+
+    container(body.spacing(ui.space(Space::X3)))
+        .width(Length::Fill)
+        .into()
+}
+
+/// 「游戏版本：1.20.1, 1.20.4」一行（空列表给 `—`，不编造）。
+fn support_line<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    key: Key,
+    values: &[String],
+) -> Element<'a, PageMessage> {
+    let list = if values.is_empty() {
+        "—".to_string()
+    } else {
+        // 加载器是站点给的小写 facet（`fabric`）：这一层只管怎么显示
+        values
+            .iter()
+            .map(|value| capitalize(value))
+            .collect::<Vec<_>>()
+            .join(", ")
+    };
+    frame::text_role_owned(
+        ui,
+        TypeRole::BodySmall,
+        false,
+        catalog.render(key, &[("list", &list)]),
+        ui.color(Role::OnSurfaceVariant),
+    )
+}
diff --git a/crates/app-iced/src/pages/content/parts/filters.rs b/crates/app-iced/src/pages/content/parts/filters.rs
new file mode 100644
index 0000000..6e1a9f7
--- /dev/null
+++ b/crates/app-iced/src/pages/content/parts/filters.rs
@@ -0,0 +1,163 @@
+//! 筛选条：来源 / 排序 / 游戏版本 / 加载器四组 chip，外加分组标签与换行容器。
+//!
+//! 从 `pages/content/parts.rs` 拆出（那个文件已贴 400 行硬上限）。
+//!
+//! 缺 key 的源（CurseForge）画成**禁用**而不是消失：筛选条要能被发现，也要能解释自己。
+
+use iced::widget::{column, container, row};
+use iced::{Alignment, Element, Length};
+
+use unlucky_design::color::Role;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use unlucky_i18n::{Catalog, Key};
+use unlucky_presenter::dto::{loader_facet, ContentSort, ContentSource, LoaderKind};
+
+use crate::app::components::selection::{chip, Chip};
+use crate::theme::Ui;
+
+use super::super::model::{loader_name, Content};
+use super::super::Message as ContentMessage;
+use super::{intent, sort_label};
+use crate::pages::frame;
+use crate::pages::Message as PageMessage;
+
+/// 来源 + 排序 + 版本 + 加载器四组 chip（一行放不下就换行，`row` 变 `column`）。
+pub(crate) fn filters<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    model: &'a Content,
+) -> Element<'a, PageMessage> {
+    let mut source = Vec::new();
+    for item in ContentSource::ALL {
+        let available = match item {
+            ContentSource::Modrinth => true,
+            ContentSource::Curseforge => model.curseforge,
+        };
+        let label = match item {
+            ContentSource::Modrinth => catalog.text(Key::ContentSourceModrinth),
+            ContentSource::Curseforge => catalog.text(Key::ContentSourceCurseforge),
+        };
+        let mut spec = Chip::filter(
+            label,
+            model.query.source == item,
+            intent(ContentMessage::SetSource(item)),
+        );
+        if !available {
+            // 缺 key 的源：**禁用并说明**，不是静默消失（否则用户找不到它）
+            spec = spec.disabled();
+        }
+        source.push(chip(ui, spec));
+    }
+
+    let mut sort = Vec::new();
+    for item in ContentSort::ALL {
+        sort.push(chip(
+            ui,
+            Chip::filter(
+                sort_label(item, catalog),
+                model.query.sort == item,
+                intent(ContentMessage::SetSort(item)),
+            ),
+        ));
+    }
+
+    let mut versions = vec![chip(
+        ui,
+        Chip::filter(
+            catalog.text(Key::ContentFilterAny),
+            model.query.version.is_none(),
+            intent(ContentMessage::SetVersion(None)),
+        ),
+    )];
+    for version in &model.versions {
+        versions.push(chip(
+            ui,
+            Chip::filter(
+                version.as_str(),
+                model.query.version.as_deref() == Some(version.as_str()),
+                intent(ContentMessage::SetVersion(Some(version.clone()))),
+            ),
+        ));
+    }
+
+    let mut loaders = vec![chip(
+        ui,
+        Chip::filter(
+            catalog.text(Key::ContentFilterAny),
+            model.query.loader.is_none(),
+            intent(ContentMessage::SetLoader(None)),
+        ),
+    )];
+    for loader in [
+        LoaderKind::Fabric,
+        LoaderKind::Forge,
+        LoaderKind::NeoForge,
+        LoaderKind::Quilt,
+    ] {
+        let usable = loader_facet(loader).is_some();
+        let mut spec = Chip::filter(
+            loader_name(loader),
+            model.query.loader == Some(loader),
+            intent(ContentMessage::SetLoader(Some(loader))),
+        );
+        if !usable {
+            spec = spec.disabled();
+        }
+        loaders.push(chip(ui, spec));
+    }
+
+    let mut column = column![
+        labelled(ui, catalog.text(Key::ContentFilterVersion), versions),
+        labelled(ui, catalog.text(Key::ContentFilterLoader), loaders),
+        wrapped_row(ui, source),
+        wrapped_row(ui, sort),
+    ]
+    .spacing(ui.space(Space::X2))
+    .width(Length::Fill);
+
+    if !model.curseforge {
+        column = column.push(frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            catalog.text(Key::ContentSourceUnavailable),
+            ui.color(Role::OnSurfaceVariant),
+        ));
+    }
+    column.into()
+}
+
+/// 分组标签 + 一行 chip（标签左、chip 右，纵向居中对齐）。
+pub(crate) fn labelled<'a>(
+    ui: &'a Ui,
+    label: &'a str,
+    chips: Vec<Element<'a, PageMessage>>,
+) -> Element<'a, PageMessage> {
+    row![
+        container(frame::text_role(
+            ui,
+            TypeRole::LabelMedium,
+            false,
+            label,
+            ui.color(Role::OnSurfaceVariant),
+        )),
+        wrapped_row(ui, chips),
+    ]
+    .spacing(ui.space(Space::X2))
+    .align_y(Alignment::Center)
+    .width(Length::Fill)
+    .into()
+}
+
+/// `Vec<Element>` → 一行（顺序就是声明顺序）。
+pub(crate) fn wrapped_row<'a>(
+    ui: &'a Ui,
+    chips: Vec<Element<'a, PageMessage>>,
+) -> Element<'a, PageMessage> {
+    row(chips)
+        .spacing(ui.space(Space::X1))
+        .align_y(Alignment::Center)
+        .into()
+}
diff --git a/crates/app-iced/src/pages/content/tests.rs b/crates/app-iced/src/pages/content/tests.rs
new file mode 100644
index 0000000..e4dcb08
--- /dev/null
+++ b/crates/app-iced/src/pages/content/tests.rs
@@ -0,0 +1,87 @@
+//! 内容库页的守门（M109）：演示数据、四类内容、页面自留状态的默认值。
+//!
+//! 视图模型的判定在 `model/tests.rs`，栏几何在 `layout.rs`，这里只管「演示数据真的装得满」——
+//! 出图靠它，装不满就说明 `demo()` 与 `Content` 的字段对不上。
+
+use unlucky_i18n::Lang;
+use unlucky_presenter::dto::ContentKind;
+
+use super::model::{PageState, Status};
+use super::{demo, Content};
+
+#[test]
+fn the_page_state_starts_on_mods_with_nothing_selected() {
+    let page = PageState::default();
+    assert_eq!(page.kind, ContentKind::Mod);
+    assert!(page.selected.is_none());
+    assert!(page.target.is_none());
+    assert!(page.draft.is_empty());
+}
+
+#[test]
+fn every_kind_gets_a_full_demo_screen() {
+    // 四种内容各出一屏（状态矩阵的前 8 张靠这一条）
+    for kind in ContentKind::ALL {
+        let model: Content = demo(kind, Lang::En);
+        assert_eq!(model.kind, kind, "{} 的演示数据换了类型", kind.slug());
+        assert_eq!(model.status, Status::Ready, "{}", kind.slug());
+        assert_eq!(model.hits.len(), 4, "{} 的命中项不足", kind.slug());
+        assert!(
+            model.selected.is_some(),
+            "演示数据要选中一条（详情面板才有内容）"
+        );
+        assert!(model.total > 0);
+        assert!(model.has_more, "演示数据要能画「加载更多」");
+        // 整合包**不**在这一条里断（它天生不可装：`ContentKind::Modpack.dir()` 是 `None`），
+        // 由下一条用例专钉。
+        if kind != ContentKind::Modpack {
+            assert!(
+                model.can_install(),
+                "默认那一屏应当是「能装」的（{}）",
+                kind.slug()
+            );
+        }
+    }
+}
+
+#[test]
+fn the_modpack_screen_is_browsable_but_never_installable() {
+    // 整合包：检索能看，装入一律禁用（M111 未落地）——演示图上必须看得到原因
+    let model = demo(ContentKind::Modpack, Lang::En);
+    assert!(model.selected.is_some());
+    assert!(!model.can_install());
+    assert_eq!(
+        model.blocker_reasons(Lang::En.catalog()).len(),
+        1,
+        "整合包只有一条原因（导入管线未落地）"
+    );
+}
+
+#[test]
+fn the_installable_kinds_block_only_when_the_target_disagrees() {
+    for kind in [
+        ContentKind::Mod,
+        ContentKind::Resourcepack,
+        ContentKind::Shader,
+    ] {
+        let model = demo(kind, Lang::En);
+        assert!(
+            model.blocker_reasons(Lang::En.catalog()).is_empty(),
+            "{} 的默认演示项应当可装",
+            kind.slug()
+        );
+    }
+}
+
+#[test]
+fn the_demo_selection_is_always_one_of_the_hits() {
+    for kind in ContentKind::ALL {
+        let model = demo(kind, Lang::En);
+        let selected = model.selected.clone().expect("有选中项");
+        assert!(
+            model.hits.iter().any(|hit| hit.id == selected),
+            "{} 的选中项不在命中列表里（详情面板会是空的）",
+            kind.slug()
+        );
+    }
+}
diff --git a/crates/app-iced/src/pages/content/view.rs b/crates/app-iced/src/pages/content/view.rs
new file mode 100644
index 0000000..bf9d9fd
--- /dev/null
+++ b/crates/app-iced/src/pages/content/view.rs
@@ -0,0 +1,232 @@
+//! 内容库页的整页装配：页头（含一级切换）+ 左侧类型栏 + 主列（筛选/结果）+ 详情 + 安装面板。
+//!
+//! ## 版面（几何在 [`super::layout`]，这里只消费结果）
+//!
+//! ```text
+//! ┌─ 页头：Content            [版本管理 | 内容库] ─┐
+//! ├──────┬────────────────────────┬──────────────┤
+//! │ 类型 │ 搜索 + 四组 chip        │ 详情 / 装入   │
+//! │ 四条 │ 计数头                  │ 原因逐条列出   │
+//! │ 侧栏 │ 结果列表（独立滚动）      │              │
+//! │      │ 加载更多 / 没有更多了    │              │
+//! ├──────┴────────────────────────┴──────────────┤
+//! │ 安装面板（**下载页那块**，只在有安装时出现）    │
+//! └──────────────────────────────────────────────┘
+//! ```
+//!
+//! ## 为什么类型栏用 `list_item`（与 M107 的版本类型栏同一套）
+//!
+//! 四条内容类型是**一级侧栏**（页面内导航），几何与状态层必须与版本管理页一致：`list_item`
+//! 自带 60 高两行档与选中态，页面不自己写 hover/pressed。窄档（`Tight`）退成一行 chip——
+//! 栏宽没了就不该硬塞一条 140px 的栏。
+
+use iced::widget::{column, container, row};
+use iced::{Element, Length};
+
+use unlucky_design::spacing::Space;
+
+use unlucky_i18n::{Catalog, Key};
+use unlucky_presenter::dto::ContentKind;
+
+use crate::app::components::divider;
+use crate::app::components::navigation::list_item::{list_item, ListItem};
+use crate::app::components::selection::{chip, Chip};
+use crate::theme::Ui;
+
+use crate::pages::download;
+use crate::pages::frame::{self, Header};
+use crate::pages::layout::FrameMetrics;
+use crate::pages::Message as PageMessage;
+
+use super::layout::{self as content_layout, Rails, Tier};
+use super::model::{Content, Status};
+use super::parts;
+use super::Message as ContentMessage;
+
+/// 整页入口（由 `pages/mod.rs` 的 `render` 调；页面层不认识 presenter 类型）。
+pub(super) fn view<'a>(
+    ui: &'a Ui,
+    metrics: FrameMetrics,
+    model: &'a Content,
+    lang: unlucky_i18n::Lang,
+) -> Element<'a, PageMessage> {
+    let catalog = lang.catalog();
+    let header = Header::new(catalog.text(Key::ContentTitle))
+        .subtitle(catalog.text(Key::ContentSubtitle))
+        .action(parts::section_switcher(ui, catalog, true));
+    frame::page(ui, metrics, header, body(ui, metrics, catalog, model))
+}
+
+fn body<'a>(
+    ui: &'a Ui,
+    metrics: FrameMetrics,
+    catalog: Catalog,
+    model: &'a Content,
+) -> Element<'a, PageMessage> {
+    let rails = content_layout::resolve(metrics.available);
+
+    let mut columns = row![kind_rail(ui, catalog, model, rails)]
+        .spacing(rails.gap)
+        .width(Length::Fill)
+        .height(Length::Fill);
+
+    if rails.tier == Tier::Tight {
+        // 窄到放不下侧栏：类型条跑到主列上方（同一个 `kind_rail`，chip 形态）
+        let main = column![
+            kind_rail(ui, catalog, model, rails),
+            divider::full(ui),
+            main_column(ui, catalog, model, rails)
+        ]
+        .spacing(ui.space(Space::X2))
+        .width(Length::Fill)
+        .height(Length::Fill);
+        columns = row![main].width(Length::Fill).height(Length::Fill);
+    } else {
+        columns = columns.push(main_column(ui, catalog, model, rails));
+        if rails.tier.has_detail() {
+            columns = columns.push(detail_column(ui, catalog, model, rails));
+        }
+    }
+
+    let mut stack = column![columns]
+        .spacing(ui.space(Space::X3))
+        .width(Length::Fill)
+        .height(Length::Fill);
+    if let Some(panel) = &model.panel {
+        // **同一块安装面板**（下载页那个函数）：内容库不另画一套进度/失败/取消。
+        stack = stack
+            .push(divider::full(ui))
+            .push(download::install_panel(ui, catalog, panel));
+    }
+    stack.into()
+}
+
+/// 左侧四条内容类型（`Wide`/`Compact` 是列表项，`Narrow` 是图标项，`Tight` 是一行 chip）。
+fn kind_rail<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    model: &'a Content,
+    rails: Rails,
+) -> Element<'a, PageMessage> {
+    if rails.tier == Tier::Tight {
+        let mut chips = Vec::new();
+        for kind in ContentKind::ALL {
+            chips.push(chip(
+                ui,
+                Chip::filter(
+                    kind_label(kind, catalog),
+                    model.kind == kind,
+                    PageMessage::Content(ContentMessage::SetKind(kind)),
+                ),
+            ));
+        }
+        return row(chips)
+            .spacing(ui.space(Space::X2))
+            .width(Length::Fill)
+            .into();
+    }
+
+    let labels = rails.tier.rail_has_labels();
+    let mut items = column(Vec::new())
+        .spacing(ui.space(Space::X1))
+        .width(Length::Fill);
+    for kind in ContentKind::ALL {
+        let label = kind_label(kind, catalog);
+        // 图标档没有文字位：标签仍传（无障碍/日志用），宽度由几何裁掉
+        let mut item = ListItem::new(
+            if labels { label } else { " " },
+            PageMessage::Content(ContentMessage::SetKind(kind)),
+        )
+        .leading(parts::kind_icon(kind));
+        if model.kind == kind {
+            item = item.selected();
+        }
+        items = items.push(list_item(ui, item));
+    }
+
+    container(items)
+        .width(Length::Fixed(rails.rail))
+        .height(Length::Fill)
+        .into()
+}
+
+/// 主列：搜索条 + 筛选 + 计数 + 结果（或四态之一）。
+fn main_column<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    model: &'a Content,
+    rails: Rails,
+) -> Element<'a, PageMessage> {
+    // 主列的横向内边距不在这里加：`rails.list` 已经把可用宽算干了，再加 2×X2 会让整排
+    // 溢出 32px（详情列被切掉一半，复审截图上正是这条）
+    let mut head = column![parts::search(ui, catalog, model)]
+        .spacing(ui.space(Space::X2))
+        .width(Length::Fill);
+
+    // 筛选条**永远在**：它是控制面，不是数据。加载中把筛选条藏起来，用户就没法在慢网络下
+    // 换条件或换类型（只能干等），这是「加载态顺手把入口收走」的经典坑。
+    head = head.push(parts::filters(ui, catalog, model));
+    head = head.push(divider::full(ui));
+    if model.status == Status::Ready {
+        // 计数头只在有数据时出现：0 条的「0 results」和空态说的是同一件事，画两遍是噪音
+        head = head.push(parts::count_head(ui, catalog, model));
+    }
+
+    let body: Element<'a, PageMessage> = if let Some(state) = parts::status_body(ui, catalog, model)
+    {
+        state
+    } else {
+        // **必须给间距**（复审 P2-1）：这一列原先漏了 `.spacing(..)`，而列表自身的纵向内边距是 0，
+        // 于是「列表视口底边」与「加载更多」贴在一起，末行正好被切在半行上。
+        let mut list = column![parts::list(ui, catalog, model, rails)]
+            .spacing(ui.space(Space::X2))
+            .width(Length::Fill)
+            .height(Length::Fill);
+        // 紧凑档没有独立详情列：详情压在列表下面（整页替换的成本比「多一块」高）
+        if !rails.tier.has_detail() {
+            list = list
+                .push(divider::full(ui))
+                .push(parts::detail(ui, catalog, model));
+        }
+        list.push(parts::more(ui, catalog, model)).into()
+    };
+
+    let mut column = column![]
+        .spacing(ui.space(Space::X2))
+        .width(Length::Fixed(rails.list))
+        .height(Length::Fill);
+
+    // M113: import/export —— 只有整合包这一类才有「把本地的包装进来 / 把实例打出去」。
+    // 其它三类（Mod / 资源包 / 光影）的导入就是把文件拖进目录，不属于本条任务。
+    if model.kind == ContentKind::Modpack {
+        column = column
+            .push(super::packui::section(ui, catalog, &model.pack))
+            .push(divider::full(ui));
+    }
+
+    column.push(head).push(body).into()
+}
+
+/// 详情列（只在 `Wide` / `Narrow` 存在）。
+fn detail_column<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    model: &'a Content,
+    rails: Rails,
+) -> Element<'a, PageMessage> {
+    container(parts::detail(ui, catalog, model))
+        .width(Length::Fixed(rails.detail))
+        .height(Length::Fill)
+        .style(move |_theme| container::Style::default())
+        .into()
+}
+
+/// 四种内容类型的界面名。
+fn kind_label(kind: ContentKind, catalog: Catalog) -> &'static str {
+    match kind {
+        ContentKind::Modpack => catalog.text(Key::ContentKindModpack),
+        ContentKind::Mod => catalog.text(Key::ContentKindMod),
+        ContentKind::Resourcepack => catalog.text(Key::ContentKindResourcepack),
+        ContentKind::Shader => catalog.text(Key::ContentKindShader),
+    }
+}
diff --git a/crates/app-iced/src/pages/download.rs b/crates/app-iced/src/pages/download.rs
new file mode 100644
index 0000000..d0e85dd
--- /dev/null
+++ b/crates/app-iced/src/pages/download.rs
@@ -0,0 +1,241 @@
+//! **版本管理页**（原下载页）：三栏版面 —— 版本类型 / 主版本 / 列表 + 安装面板。
+//!
+//! 用户令（信息架构调整）把这一页从「下载」改称「版本管理」：下载页只负责整合包与 Mod/光影，
+//! 而这一页管的是**游戏版本与加载器安装**。本文件是那次改版后的页面装配点。
+//! **标识符不改**（用户令 2026-11-04 的「只改显示层」边界）：`Route::Download` /
+//! `Screen::Download` / 文件名 / 类型名一律保留，全仓重命名另开 finding 后置——所以本文件里
+//! 「下载页」三个字到处都是，那是标识符的叫法，不是界面上出现的词。
+//! **M102 版面订正**：旧版把整页块压到 424 并水平居中（1180 宽下左缘 422、页头标题在 112，
+//! 左右各空 ~300px，视觉复审判为「内容缩在中间一条窄栏」）。现在页面块走 [`frame::body`]
+//! ——左缘与页头标题同一条线（= 页边距 24），宽 = 块宽 `frame::body_width`（1180 下 1044，
+//! 极宽窗封顶 **1440**）。424 只约束**成段散文**（本页没有），三栏的每一栏都吃块宽。
+//!
+//! ## 版面：三栏，宽度由布局系统裁决
+//!
+//! ```text
+//! ┌─────────┬─────────┬──────────────────────────────┐
+//! │ 版本类型 │ 主版本  │ 搜索条 · 命中数 · 计数头      │
+//! │ 140/64  │ 140/64  │ 版本行（单行四项）            │
+//! │         │         │ …                            │
+//! │         │         │ 安装面板（M105 的选项区在这里）│
+//! └─────────┴─────────┴──────────────────────────────┘
+//! ```
+//!
+//! 三个数字**没有一个是在本文件里拍的**：它们来自
+//! [`VersionRails`](super::layout::VersionRails)（宽档裁决 + 数值表在 `pages/layout/rails.rs`）。
+//! 页面只做一件事：把裁决结果交给 [`rails`] 画出来。
+//!
+//! ## 原顶部 4 个 tab 的去处（不是新造分类）
+//!
+//! 四个 chip（全部 / 正式版 / 预览版 / 远古版）**语义一字不改**，只是从顶部横排搬到第一栏竖排；
+//! 窄到三栏不成立时（可用宽 < 600）它们**原样回到顶部**（[`rails::stacked_chips`]）——同一条
+//! [`Category`] 谓词、同一条 `AppCommand::ListVersions`。
+//!
+//! ## 意图 → 消息 → 指令（页面只发意图，不做乐观回显）
+//!
+//! | 用户动作 | 页面消息 | app 层落点 |
+//! |---|---|---|
+//! | 点分类 tab | [`Message::SetCategory`] | `AppCommand::ListVersions(category)`（`All` 不派：画现有快照） |
+//! | 点一行 | [`Message::SelectVersion`] | **只改视图模型**（选中不是业务命令） |
+//! | 点「安装」 | [`Message::InstallVersion`] | `AppCommand::CreateInstance(草稿)`（M105：带加载器与实例名） |
+//! | 点「取消安装」 | [`Message::CancelInstall`] | `AppCommand::CancelInstall` |
+//! | 点「刷新」/「打开日志」 | `Message::Action(RefreshSources)` / `Message::Navigate(Logs)` | `ListVersions` / `AppState::navigate` |
+//!
+//! ## M105：安装选项（加载器维度）
+//!
+//! 选中版本**不再直接开工**。面板下半块变成「安装选项」区：五家加载器（原版 / Forge /
+//! NeoForge / Fabric / Quilt）的 chip、该加载器的官方版本列表、实例名，点「安装」才派
+//! `CreateInstance`。选项的决策与画法在 [`options`]（子模块），本文件只负责把模型交给它。
+//! 加载器版本列表来自 core 的 `LoaderSource::loader_versions`（经
+//! `AppCommand::ListLoaderVersions` 回流到快照）；取不到时页面给具名原因并**禁掉确认**——
+//! 不许「选完才失败」。
+//!
+//! 进度条只读 `model.install`：它由 presenter 的 `InstallProgress` 事件经 `apply` 灌进来。
+//! 于是「点了没变」只有一种解释——后端还没回事件，这正是要的（P3-2 的纪律）。
+//!
+//! ## M107：两级侧栏从哪来（第一级 = 版本类型，第二级 = 主版本桶）
+//!
+//! 第一级 = 版本类型（4 项，固定）；第二级 = 主版本桶（由快照里的版本 id 按 [`group`] 的规则归纳，
+//! 远古版这类「没有主版本概念」的只有「全部版本」一项）。
+//!
+//! ## 搜索（三层口径）
+//!
+//! | 情形 | 画面 |
+//! |---|---|
+//! | 有命中 | 列表照常；侧栏**位置不动**；搜索条右侧给「N 个匹配」（跨类型读数） |
+//! | 一个都不命中 | [`states::no_match`]：没有匹配 + 换短片段 + 清空 |
+//! | 有命中但不在当前类型 | [`states::elsewhere`]：N 个在别的类型 + 「看全部类型」 |
+//! | 搜索中点第二级桶 | **退出搜索 + 按那个桶过滤**（点桶 = 「我就是要看这个桶」，见 `on_download`） |
+//!
+//! 查询词写在 presenter 快照的 `download_query` 里（页面无状态，见 [`model::Download::from_snapshot`]），
+//! 所以「搜索 → 任何事件回来之后仍然在搜」这条不需要页面持有任何字段。
+//!
+//! ## 状态矩阵（加载 / 空 / 有数据 / 安装中 / 失败）
+//!
+//! 与 M94 时一致，唯一的改动是**空态与搜索态都留在三栏骨架里**：侧栏与搜索框照旧在，
+//! 只有列表区换成占位内容——白屏会让人以为列表坏了。
+//!
+//! ## 两个纯视图态的字段（快照里没有，重建会丢）
+//!
+//! `selected_major`（第二级侧栏选中）与 `type_rail_folded`（类型栏手动折叠）**不在 presenter 快照里**
+//! （`AppState` 没有这两个字段，加字段要动 `pages/mod.rs` 的偏离表与 presenter，见 M107 报告）。
+//! 所以它们与既有的 `selected` 同一档处理：`on_download` 直接改视图模型，**不重建**；
+//! 唯一会重建的路径是搜索（`rebuild_after_query`），那里把两个字段在重建前后各搬一次。
+//! 其余事件（安装进度、版本列表刷新）回来时这两个字段会回到默认值——与 `selected` 的既有缺口同源，
+//! 长期要靠 presenter 加字段，已登记在报告里。
+//!
+//! ## 版面判据（M102 口径：页面块 vs 散文列）
+//!
+//! 页面仍是 `PaneKit::Single`（页内自己切三栏）。整页内容走 [`frame::body`]：块左缘 =
+//! 页头标题左缘 = `rail 88 + gutter 24 = 112`，块宽 = [`frame::body_width`]（pane 宽封顶
+//! **1440**）——视觉复审 ①（内容缩在中间一条窄栏、与页头错位）因此收口。
+//! **三栏的列宽从「块宽」算**（[`VersionRails::of_metrics`] 读 `frame::body_width`，不是
+//! `metrics.available`）：否则 1576+ 的超宽窗上三列之和会超出 1440 的块、右侧被裁。
+//! 424（[`super::layout::measure_cap_px`]）在本页只对**成段散文**有效——这一页没有散文。
+
+mod demo;
+mod group;
+mod install;
+mod model;
+mod options;
+mod rails;
+mod rows;
+mod states;
+
+#[cfg(test)]
+mod tests;
+
+pub use demo::demo;
+pub use model::{cancelled_toast, Category, Download};
+pub use options::{InstallDraft, Loader};
+
+// M109：内容库页复用**同一块**安装面板（同一个函数、同一套文案与几何），不另写一套。
+//
+// 两个薄包装为什么必须在**这个文件**里：①`install::panel` 是 `pub(super)`（只在 `pages::download`
+// 可见），再导出到 crate 会撞 `E0364`；②面板的入参是 `&Download`，而 `InstallView` 是页面私有
+// 类型（M105 起不再从本模块导出），所以「快照 → 面板形状」的转换也留在这里——内容库只拿到
+// `Option<Download>`，它不需要也不该认识 `InstallView`。
+pub(crate) fn install_panel<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    model: &'a Download,
+) -> Element<'a, Message> {
+    install::panel(ui, catalog, model)
+}
+
+/// 快照 → 面板要的 `Download` 形状（**只填 `install`**）。
+///
+/// 「装完 / 已取消」这类没有动作可给的终态返回 `None`（与下载页同一个判断
+/// `InstallView::finished`）：留着只会让面板停在一个点不动的状态上。
+pub(crate) fn install_panel_model(
+    progress: &unlucky_presenter::dto::InstallProgressView,
+    catalog: Catalog,
+) -> Option<Download> {
+    let view = model::InstallView::of(progress, catalog);
+    if view.finished() {
+        return None;
+    }
+    Some(Download {
+        install: Some(view),
+        ..Download::loading()
+    })
+}
+
+use iced::widget::column;
+use iced::{Element, Length};
+
+use unlucky_design::spacing::Space;
+
+use unlucky_i18n::{Catalog, Key, Lang};
+
+use crate::app::components::buttons::{self, Button};
+use crate::app::components::divider;
+use crate::theme::Ui;
+
+use super::content;
+use super::frame::{self, Header};
+use super::layout::{FrameMetrics, VersionRails};
+use super::{Action, Message};
+
+/// 整页（**唯一**的真数据入口：`model` 由 `app/view.rs` 从 presenter 快照建）。
+///
+/// `lang` 是 i18n 的入参，调用点传的是 `pages::Model.lang`（M106 起 = `App` 的生效语言，
+/// 见 `ui::lang::LangState`）；页面自己不读全局、不猜语言。
+pub fn view<'a>(
+    ui: &'a Ui,
+    metrics: FrameMetrics,
+    model: &'a Download,
+    lang: Lang,
+) -> Element<'a, Message> {
+    let catalog = lang.catalog();
+
+    let header = Header::new(catalog.text(Key::DownloadTitle))
+        .subtitle(catalog.text(Key::DownloadSubtitle))
+        // M109：一级切换「版本管理 | 内容库」。两页共用同一条导航轨项（`NavSection::Download`），
+        // 所以这个切换是进内容库的唯一产品入口——少了它，内容库只能靠 `ULL_START_ROUTE` 到达。
+        .action(content::section_switcher(ui, catalog))
+        .action(buttons::text(
+            ui,
+            Button::new(
+                catalog.text(Key::DownloadRefresh),
+                Message::Action(Action::RefreshSources),
+            ),
+        ));
+
+    frame::page(ui, metrics, header, body(ui, metrics, catalog, model))
+}
+
+/// 正文：加载态仍是居中占位；其余状态都长在三栏骨架上。
+fn body<'a>(
+    ui: &'a Ui,
+    metrics: FrameMetrics,
+    catalog: Catalog,
+    model: &'a Download,
+) -> Element<'a, Message> {
+    if model.is_loading() {
+        // 还没拉到版本列表：三栏没有内容可填，给占位（安装面板照旧带着，见 M94 复审 p3）
+        let content: Element<'a, Message> = if model.install.is_some() {
+            column![
+                states::loading(ui, catalog),
+                divider::full(ui),
+                install::panel(ui, catalog, model)
+            ]
+            .spacing(ui.space(Space::X3))
+            .width(Length::Fill)
+            .height(Length::Fill)
+            .into()
+        } else {
+            states::loading(ui, catalog)
+        };
+        return frame::body(metrics, content);
+    }
+
+    // 宽度裁决：档位来自布局系统，「用户手动折叠了类型栏」这一条覆盖叠在上面。
+    let rails = {
+        let rails = VersionRails::of_metrics(metrics);
+        if model.type_rail_folded {
+            rails.with_type_folded()
+        } else {
+            rails
+        }
+    };
+
+    let content: Element<'a, Message> = if rails.tier.is_three_column() {
+        rails::three_column(ui, catalog, model, rails)
+    } else {
+        // 三栏不成立（可用宽 < 600）：类型与主版本原样退回顶部 chips，列表吃掉整条可用宽
+        column![
+            rails::stacked_chips(ui, catalog, model),
+            divider::full(ui),
+            rows::content(ui, catalog, model),
+        ]
+        .spacing(ui.space(Space::X2))
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .into()
+    };
+
+    // M102：整页块走 `frame::body`（贴左、块宽封顶 1440），与页头标题同一条左缘。
+    // 三栏都在这个块里切，所以 `VersionRails` 读的是块宽而不是 `metrics.available`。
+    frame::body(metrics, content)
+}
diff --git a/crates/app-iced/src/pages/download/demo.rs b/crates/app-iced/src/pages/download/demo.rs
new file mode 100644
index 0000000..63d9b38
--- /dev/null
+++ b/crates/app-iced/src/pages/download/demo.rs
@@ -0,0 +1,301 @@
+//! 下载页的**演示数据**（截图 harness 与单测的输入，产品路径不读）。
+//!
+//! 与 `pages/instances/data.rs` 同一条纪律：演示条目是**页面侧常量**，不是业务 DTO——
+//! 于是核心 DTO 每改一次字段，基线图不会跟着漂。真页面的数据只走
+//! [`Download::from_snapshot`](super::model::Download::from_snapshot)。
+//!
+//! 演示条目本身也是一步「DTO → 视图模型」的真转换（[`VersionRow::of`](super::model::VersionRow)、
+//! [`InstallView::of`](super::model::InstallView)）：图上看到的副文案 / 进度行就是产品路径
+//! 那条转换的产物，不是另写一套拼串。
+//!
+//! ## 为什么要一个环境变量
+//!
+//! 状态矩阵（加载 / 空 / 有数据 / 安装中 / 安装失败）都要出图，而 harness 的
+//! `--screen` 只选页面、选不了页面状态：
+//!
+//! ```text
+//! ULL_DL_DEMO=empty cargo run -p unlucky-app-iced --example pages_demo -- \
+//!   --screen=download --screenshot=out.png --screenshot-theme=light --software-renderer
+//! ```
+//!
+//! 取值：`ready`（缺省）/ `loading` / `empty` / `selected` / `category-release` / `installing` /
+//! `installing-late` / `installing-empty` / `failed` / `done` / `done-next` /
+//! **`options` / `options-fabric` / `options-incompat`**（M105 的安装选项区三态）/
+//! **`category-ancient` / `search` / `search-major` / `search-empty` / `search-elsewhere`**
+//! （M107 的两级侧栏与搜索取样点）。
+//!
+//! M107 那几个取样点**都走产品那条真转换**（`Download::from_snapshot`，查询词写在快照的
+//! `download_query` 里）：图证明的是产品路径的行为，不是演示的特权。
+//!
+//! `category-release` / `done` / `done-next` 都**不手搓结果**，而是拿一份 `AppState` 跑
+//! [`Download::from_snapshot`]：图证明的是产品路径的行为（分类本地过滤、装完后面板让回列表），
+//! 不是演示的特权。
+//!
+//! `done` / `done-next` 是「**刚装完**」的两个采样点：它们不手搓模型，而是拿一份
+//! `AppState`（版本列表 + `InstallStage::Done`）跑 [`Download::from_snapshot`]，所以图上看到的是
+//! 产品路径的真行为（复审 p2：`Done` 之后面板必须让回列表，否则第二个版本装不了）。
+//! **只有 harness 与演示走这里**：产品路径由 `app/view.rs` 从 presenter 快照建模型。
+
+use unlucky_presenter::dto::{
+    AncientKind, InstallProgressView, InstallStage, VersionKind, VersionSummary,
+};
+
+use unlucky_presenter::dto::{AppEvent, CoreEvent};
+use unlucky_presenter::state::AppState;
+
+use unlucky_i18n::Catalog;
+
+use super::model::{Category, Download, InstallView, VersionRow};
+use super::options::{InstallDraft, Loader};
+
+/// 取证开关的名字（[`demo`] 读它）。
+pub const DEMO_STATE_ENV: &str = "ULL_DL_DEMO";
+
+/// 演示模型：按 [`DEMO_STATE_ENV`] 选状态，缺省是「有数据」。
+pub fn demo(catalog: Catalog) -> Download {
+    match std::env::var(DEMO_STATE_ENV).ok().as_deref() {
+        Some("loading") => Download::loading(),
+        Some("empty") => Download {
+            loaded: true,
+            ..Download::loading()
+        },
+        Some("installing") => Download {
+            install: Some(install(InstallStage::Downloading, 0.42, catalog)),
+            selected: Some("1.21.9".to_string()),
+            ..ready(catalog)
+        },
+        // 同一状态的第二个采样点：进度条随**事件**推进（不是动画），出图时两帧对照
+        Some("installing-late") => Download {
+            install: Some(install(InstallStage::Downloading, 0.8, catalog)),
+            selected: Some("1.21.9".to_string()),
+            ..ready(catalog)
+        },
+        // M105：安装选项区三态（未选加载器 / 已选 Fabric / 不兼容组合）。
+        // 三条都走**产品那条真转换**（`from_snapshot` + 草稿），图里看到的是页面真会画的东西。
+        Some("options") => options(catalog, "1.21.9", Loader::Vanilla, None),
+        Some("options-fabric") => options(
+            catalog,
+            "1.21.9",
+            Loader::Fabric,
+            Some(vec!["0.16.5", "0.16.4", "0.15.11"]),
+        ),
+        // NeoForge 最早只到 1.20.1，远古版（列表里的 `rd-132211`）根本没有构建 ⇒ 选中即报原因
+        Some("options-incompat") => options(catalog, "rd-132211", Loader::NeoForge, None),
+        Some("selected") => Download {
+            selected: Some("1.21.9".to_string()),
+            ..ready(catalog)
+        },
+        Some("failed") => Download {
+            install: Some(install(InstallStage::Failed, 0.0, catalog)),
+            selected: Some("1.21.9".to_string()),
+            ..ready(catalog)
+        },
+        // 装完之后：走**产品那条真转换**（见 `finished`），图里看到的就是页面真会画的东西
+        Some("done") => finished(catalog, None),
+        // 装完之后再点下一个版本：面板必须重新给出实心「安装」
+        Some("done-next") => finished(catalog, Some("1.21.9-pre3")),
+        // 安装进行中、但列表被过滤空：面板要跟着占位态一起在（复审 p3 的边角）
+        // 分类筛选（本页本地过滤：真 host 丢弃 ListVersions 的分类参数）——混合清单里只留正式版
+        Some("category-release") => category(catalog, Category::Release),
+        // M107 的两级侧栏 + 搜索：这三种状态**都走产品那条真转换**（from_snapshot），
+        // 图里看到的是页面真会画的东西，不是演示的特权。
+        Some("category-ancient") => searched(catalog, Category::Ancient, ""),
+        Some("search") => searched(catalog, Category::All, "1.20"),
+        Some("search-major") => majored(searched(catalog, Category::All, ""), "1.21"),
+        Some("search-empty") => searched(catalog, Category::All, "zzz"),
+        Some("search-elsewhere") => searched(catalog, Category::Release, "24w"),
+        // 复审 P2-1 的取样点：**选中 1.21 桶的同时搜 1.20**。修好之后列表里是 2 行命中、
+        // 侧栏点亮「全部版本」（第二级在搜索期间放宽），不会出现「2 个匹配 + 没有版本」。
+        Some("search-over-bucket") => majored(searched(catalog, Category::All, "1.20"), "1.21"),
+        // 复审 P2-2 的取样点：**22 个主版本桶**（MOJANG 清单里 `Release` 就是这个量级）。
+        // chips 档一行放不下 ⇒ 主版本行必须能横向滚，否则后面的桶永远点不到。
+        Some("many-buckets") => many(catalog),
+        Some("installing-empty") => Download {
+            install: Some(install(InstallStage::Downloading, 0.42, catalog)),
+            ..Download::loading()
+        },
+        _ => ready(catalog),
+    }
+}
+
+/// 有数据：八行（四条正式、两条预览、两条远古），覆盖四种版本形态与三个主版本桶。
+///
+/// 不复用 `mock_data::mock_versions()`：演示数据是**出图的基线**，得比 mock 稳定
+/// （mock 随 P3 的假数据一起漂）。
+fn ready(catalog: Catalog) -> Download {
+    let versions = demo_versions();
+    let rows: Vec<VersionRow> = versions
+        .iter()
+        .map(|version| VersionRow::of(version, catalog))
+        .collect();
+
+    Download {
+        // 混合分类 → 没有单个 chip 该亮（这正是 `Category::of` 的反推结果）
+        category: Category::of(&versions),
+        buckets: super::group::buckets(&rows),
+        hits: rows.len(),
+        rows,
+        selected: None,
+        options: None,
+        install: None,
+        loaded: true,
+        query: String::new(),
+        selected_major: None,
+        type_rail_folded: false,
+    }
+}
+
+/// 「用户选了版本、正在填安装选项」的演示（M105）。
+///
+/// 走真转换：`AppState`（版本列表 + 可选的加载器版本缓存）+ 草稿 → [`Download::from_snapshot`]。
+/// 于是图上「默认取最新加载器版本」「不兼容给具名原因」「确认键禁用」都是产品行为，不是演示特权。
+fn options(catalog: Catalog, version: &str, loader: Loader, cached: Option<Vec<&str>>) -> Download {
+    let mut state = AppState::new();
+    state.apply(AppEvent::Core(CoreEvent::VersionListChanged(
+        demo_versions(),
+    )));
+    if let Some(items) = cached {
+        state.apply(AppEvent::Core(CoreEvent::LoaderVersions {
+            kind: loader.kind(),
+            mc_version: version.to_string(),
+            result: Ok(items.into_iter().map(str::to_string).collect()),
+        }));
+    }
+    let draft = InstallDraft {
+        selected: Some(version.to_string()),
+        loader,
+        ..InstallDraft::default()
+    };
+    Download::from_snapshot(&state, Category::All, &draft, catalog)
+}
+
+/// 22 个主版本桶（`1.21 … 1.0`）的清单：chips 档的横向滚动取证用。
+fn many(catalog: Catalog) -> Download {
+    let versions = (0..=21)
+        .rev()
+        .map(|minor| VersionSummary {
+            id: format!("1.{minor}.4"),
+            kind: VersionKind::Release,
+            released: "2026-09-20".to_string(),
+            installed: false,
+        })
+        .collect();
+
+    let mut state = AppState::new();
+    state.apply(AppEvent::Core(CoreEvent::VersionListChanged(versions)));
+    Download::from_snapshot(&state, Category::All, &InstallDraft::default(), catalog)
+}
+
+/// 演示用的版本表（`ready` 与 `finished` 共用；与 presenter 的 `mock_versions` 同形）。
+///
+/// 四种形态各有样本：`1.21.9`（正式）、`1.21.9-pre3`（预发布）、`24w14a`（周更）、
+/// `rd-132211` / `a1.2.6`（远古，没有主版本）。
+fn demo_versions() -> Vec<VersionSummary> {
+    fn summary(id: &str, kind: VersionKind, released: &str, installed: bool) -> VersionSummary {
+        VersionSummary {
+            id: id.to_string(),
+            kind,
+            released: released.to_string(),
+            installed,
+        }
+    }
+
+    vec![
+        summary("1.21.9", VersionKind::Release, "2026-09-20", false),
+        summary("1.21.8", VersionKind::Release, "2026-07-11", true),
+        summary("1.20.4", VersionKind::Release, "2023-12-07", true),
+        summary("1.20.1", VersionKind::Release, "2023-06-12", false),
+        summary("1.21.9-pre3", VersionKind::Snapshot, "2026-09-01", false),
+        summary("24w14a", VersionKind::Snapshot, "2024-04-03", false),
+        summary(
+            "rd-132211",
+            VersionKind::Ancient(AncientKind::Classic),
+            "2009-05-13",
+            false,
+        ),
+        summary(
+            "a1.2.6",
+            VersionKind::Ancient(AncientKind::OldAlpha),
+            "2010-08-11",
+            false,
+        ),
+    ]
+}
+
+/// 「刚装完一个版本」的演示：**走产品那条真转换**（`AppState` → `Download::from_snapshot`）。
+///
+/// 为什么不用手搓模型：本轮复审的 bug 正是「`Done` 之后 `install` 从不清」——手搓一个
+/// `install: None` 的模型会让图**假绿**（图上好看，真路径照样卡死）。这里真的走一遍快照转换，
+/// 于是图能证明「装完之后面板让回列表」是产品路径的行为，不是演示的特权。
+///
+/// `select_next`：演「用户接着点了下一个版本」，面板应当重新给出实心「安装」。
+fn finished(catalog: Catalog, select_next: Option<&str>) -> Download {
+    let mut state = AppState::new();
+    state.apply(AppEvent::Core(CoreEvent::VersionListChanged(
+        demo_versions(),
+    )));
+    state.apply(AppEvent::Core(CoreEvent::InstallProgress(Some(
+        InstallProgressView {
+            version: "1.21.8".to_string(),
+            stage: InstallStage::Done,
+            files_done: 512,
+            files_total: 512,
+            ..InstallProgressView::new()
+        },
+    ))));
+
+    let mut model =
+        Download::from_snapshot(&state, Category::All, &InstallDraft::default(), catalog);
+    model.selected = select_next.map(str::to_string);
+    model
+}
+
+/// 「用户点了某个分类」的演示：走真转换（`from_snapshot` 的分类过滤），不手搓过滤结果。
+fn category(catalog: Catalog, wanted: Category) -> Download {
+    let mut state = AppState::new();
+    state.apply(AppEvent::Core(CoreEvent::VersionListChanged(
+        demo_versions(),
+    )));
+    Download::from_snapshot(&state, wanted, &InstallDraft::default(), catalog)
+}
+
+/// 「用户在搜索框里敲了几个字符」的演示：查询词写进**快照字段**（产品路径就是这么活的）。
+fn searched(catalog: Catalog, wanted: Category, query: &str) -> Download {
+    let mut state = AppState::new();
+    state.apply(AppEvent::Core(CoreEvent::VersionListChanged(
+        demo_versions(),
+    )));
+    state.download_query = query.to_string();
+    Download::from_snapshot(&state, wanted, &InstallDraft::default(), catalog)
+}
+
+/// 「用户点了第二级侧栏里的一个主版本桶」的演示（纯视图态，与 `on_download` 的落点一致）。
+fn majored(mut model: Download, key: &str) -> Download {
+    model.selected_major = Some(key.to_string());
+    model
+}
+
+/// 一次安装的演示快照（文件计数 / 字节 / 速度 / 剩余时间都给真值，进度条画得出来）。
+fn install(stage: InstallStage, ratio: f32, catalog: Catalog) -> InstallView {
+    let total = 512;
+    let done = (f64::from(ratio) * total as f64) as u64;
+    let failed = matches!(stage, InstallStage::Failed);
+
+    InstallView::of(
+        &InstallProgressView {
+            version: "1.21.9".to_string(),
+            instance: "1.21.9".to_string(),
+            // 演示也**不**搬 core 的中文串：`loader` 字段这里给的是结构化徽标的英文名
+            loader: "Vanilla".to_string(),
+            stage,
+            files_done: if failed { 137 } else { done },
+            files_total: total,
+            bytes_done: 0,
+            bytes_total: 0,
+            speed_bps: if failed { 0 } else { 1_258_291 },
+            eta_secs: if failed { 0 } else { 75 },
+            message: String::new(),
+        },
+        catalog,
+    )
+}
diff --git a/crates/app-iced/src/pages/download/group.rs b/crates/app-iced/src/pages/download/group.rs
new file mode 100644
index 0000000..51ff5e0
--- /dev/null
+++ b/crates/app-iced/src/pages/download/group.rs
@@ -0,0 +1,169 @@
+//! 主版本分组：把一串版本 id 归成「大版本」桶（第二级侧栏的数据源）。
+//!
+//! ## 为什么不能按第一个 `.` 切
+//!
+//! 真实的版本清单里同时存在**四种形态**（拿真样本说，不用「第几个点」这种相对说法）：
+//!
+//! | 样本 | 是什么 | `split('.')` 会得到什么 | 正确的主版本 |
+//! |---|---|---|---|
+//! | `1.21.4` | 正式版 | `["1", "21", "4"]` | `1.21` |
+//! | `1.21.9-pre3` | 预发布（正式版的兄弟） | `["1", "21", "9-pre3"]` | `1.21` |
+//! | `24w14a` | 周更快照 | `["24w14a"]`（一个都没有） | `24w`（周更的年桶） |
+//! | `rd-132211` / `a1.2.6` | 远古版（Classic / Alpha） | `["rd-132211"]` / `["a1", "2", "6"]` | **没有主版本** |
+//!
+//! 「按第一个 `.` 切」在 `1.21.4` 上给出 `1`，把 1.7 到 1.21 的全部正式版塞进一个桶；
+//! 在 `a1.2.6` 上给出 `a1`，凭空造出一个「主版本」——远古版根本没有 major.minor 这层概念。
+//!
+//! ## 规则（三条，按顺序命中即返回）
+//!
+//! 1. **带点的数值前缀**（正式版 / 预发布）：id 在第一个 `-` 之前的部分，前两段都是纯数字
+//!    ⇒ 主版本 = `第一段.第二段`。`1.21.9-pre3` 先切掉 `-pre3` 再取 `1.21`。
+//! 2. **周更快照**：id 形如 `24w14a`（两位年 + `w` + 两位周 + 一个修订字母）⇒ 主版本 = `24w`。
+//!    周更版本每年几十个，年桶是它的「大版本」等价物；不按周切是因为一周通常只有 1 个版本，
+//!    按周分组等于每个桶一个版本（侧栏退化成重复的列表）。
+//! 3. **其余**：返回 [`None`]（没有主版本概念）。远古版（`rd-132211` / `a1.2.6` / `c0.30_01c`）
+//!    走这一条 ⇒ 第二级侧栏只有一个「全部」项。
+//!
+//! 判据是**形态**（有没有 `-` 后缀、前两段是不是纯数字、有没有 `NNwNNx` 的形状），
+//! 不是「版本号大小」，所以新增一个 `1.22.0` 或 `25w01a` 不需要改规则。
+
+use unlucky_presenter::dto::VersionKind;
+
+/// 主版本桶的一个标签（`1.21` / `24w`）；没有主版本概念时是 [`None`]。
+pub type MajorKey = String;
+
+/// 这个版本属于哪个主版本桶（规则见模块文档）。
+///
+/// 远古版**直接**返回 [`None`]：它们的 id 形态（`a1.2.6`）与正式版同族，靠形态规则会误判，
+/// 所以先按 `kind` 分流——「有没有主版本」是**版本类型**的属性，不是 id 字符串的属性。
+#[must_use]
+pub fn key(id: &str, kind: VersionKind) -> Option<MajorKey> {
+    if kind.is_ancient() {
+        return None;
+    }
+
+    // 规则 1：切掉 `-pre3` / `-rc1` 这类后缀，再取前两段数值
+    let head = id.split('-').next().unwrap_or(id);
+    let mut parts = head.split('.');
+    if let (Some(major), Some(minor)) = (parts.next(), parts.next()) {
+        if is_number(major) && is_number(minor) {
+            return Some(format!("{major}.{minor}"));
+        }
+    }
+
+    // 规则 2：周更快照 `24w14a` → `24w`
+    if let Some((year, tail)) = head.split_once('w') {
+        let week_like = tail.chars().next().is_some_and(|ch| ch.is_ascii_digit());
+        if year.len() == 2 && is_number(year) && week_like {
+            return Some(format!("{year}w"));
+        }
+    }
+
+    // 规则 3：没有主版本概念
+    None
+}
+
+/// 纯数字（空串不算）。
+fn is_number(text: &str) -> bool {
+    !text.is_empty() && text.bytes().all(|byte| byte.is_ascii_digit())
+}
+
+/// 两条主版本标签的**版本序**（降序用）：`1.21 > 1.9`、`24w > 14w`，数字按数值比、字母按字节比。
+///
+/// 为什么不是字符串序：`"1.9" > "1.21"` 在字典序里成立（`9 > 2`），而版本序里 1.21 更新。
+/// 逐段比：连续数字读成整数、其余字符逐字节比。
+#[must_use]
+pub fn compare(left: &str, right: &str) -> std::cmp::Ordering {
+    let mut left_rest = left;
+    let mut right_rest = right;
+
+    loop {
+        match (left_rest.chars().next(), right_rest.chars().next()) {
+            (None, None) => return std::cmp::Ordering::Equal,
+            (None, Some(_)) => return std::cmp::Ordering::Less,
+            (Some(_), None) => return std::cmp::Ordering::Greater,
+            (Some(left_char), Some(right_char)) => {
+                if left_char.is_ascii_digit() && right_char.is_ascii_digit() {
+                    let (left_number, left_tail) = take_number(left_rest);
+                    let (right_number, right_tail) = take_number(right_rest);
+                    match left_number.cmp(&right_number) {
+                        std::cmp::Ordering::Equal => {
+                            left_rest = left_tail;
+                            right_rest = right_tail;
+                        }
+                        other => return other,
+                    }
+                } else if left_char == right_char {
+                    left_rest = &left_rest[left_char.len_utf8()..];
+                    right_rest = &right_rest[right_char.len_utf8()..];
+                } else {
+                    return left_char.cmp(&right_char);
+                }
+            }
+        }
+    }
+}
+
+/// 取出开头的连续数字（返回数值与剩余部分）。
+fn take_number(text: &str) -> (u64, &str) {
+    let end = text
+        .find(|ch: char| !ch.is_ascii_digit())
+        .unwrap_or(text.len());
+    (text[..end].parse().unwrap_or(0), &text[end..])
+}
+
+/// 一个主版本桶（第二级侧栏的一行）：桶标签 + 桶里有多少个版本。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Bucket {
+    /// 桶标签（`1.21` / `24w`）；[`None`] = 这一组版本没有主版本概念（远古版）。
+    pub key: Option<MajorKey>,
+    /// 桶里的版本数（列表列与命中数都读它）。
+    pub count: usize,
+}
+
+/// 把版本行归成桶：**按版本序降序**（`1.21` 在 `1.20` 前面），无主版本概念的桶排最后。
+///
+/// 只做聚合与排序，不决定「当前选中哪个桶」——那是页面状态，住在 `pages/Download` 里。
+#[must_use]
+pub fn buckets(rows: &[super::model::VersionRow]) -> Vec<Bucket> {
+    let mut grouped: Vec<Bucket> = Vec::new();
+    for row in rows {
+        let key = row.major();
+        match grouped.iter_mut().find(|bucket| bucket.key == key) {
+            Some(bucket) => bucket.count += 1,
+            None => grouped.push(Bucket { key, count: 1 }),
+        }
+    }
+
+    grouped.sort_by(|left, right| match (&left.key, &right.key) {
+        (Some(a), Some(b)) => compare(b, a),
+        (Some(_), None) => std::cmp::Ordering::Less,
+        (None, Some(_)) => std::cmp::Ordering::Greater,
+        (None, None) => std::cmp::Ordering::Equal,
+    });
+    grouped
+}
+
+/// 第二级侧栏此刻**真正生效**的桶（P2-1 的口径）。
+///
+/// 搜索时一律放宽到「全部」（[`None`]）：命中数 `hits` 是**跨桶**读数，若列表还按桶过滤，
+/// 就会出现「N matches + 0 versions + 没有版本」的自相矛盾一屏（复审 P2-1）。
+/// 放宽之后「列表行数 = 当前分类里的命中数」，侧栏也不会有「选中项不在桶列表里」的幽灵态。
+/// `selected_major` 一直留在模型里，只是搜索期间不生效——清空搜索后原来的桶自动回来。
+#[must_use]
+pub fn active_bucket(model: &super::model::Download) -> Option<&str> {
+    if model.has_query() {
+        None
+    } else {
+        model.selected_major.as_deref()
+    }
+}
+
+/// 第二级侧栏里这一项该不该点亮（`None` = 「全部版本」那一项）。
+#[must_use]
+pub fn bucket_selected(model: &super::model::Download, key: Option<&str>) -> bool {
+    active_bucket(model) == key
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/app-iced/src/pages/download/group/tests.rs b/crates/app-iced/src/pages/download/group/tests.rs
new file mode 100644
index 0000000..6a714f9
--- /dev/null
+++ b/crates/app-iced/src/pages/download/group/tests.rs
@@ -0,0 +1,104 @@
+//! 分组规则的判据：**用真实版本样本**钉住（不用「第几个点」这种相对说法，踩坑 T1）。
+//!
+//! 每条都写清抓得住什么 / 抓不住什么。
+
+use super::*;
+use unlucky_presenter::dto::{AncientKind, VersionKind};
+
+const RELEASE: VersionKind = VersionKind::Release;
+const SNAPSHOT: VersionKind = VersionKind::Snapshot;
+
+fn ancient(kind: AncientKind) -> VersionKind {
+    VersionKind::Ancient(kind)
+}
+
+/// 四种形态**同时存在**时各自归到哪个桶（这是模块文档那张表的产品化版本）。
+///
+/// 抓得住：有人改回「按第一个 `.` 切」——`1.21.4` 会变成 `1`、`a1.2.6` 会变成一个假主版本。
+/// 抓不住：真实清单里还没出现的形态（比如将来的 `1.22.0`，它走同一条数值规则所以不会红）。
+#[test]
+fn the_four_shapes_land_in_the_documented_buckets() {
+    // 1. 正式版
+    assert_eq!(key("1.21.4", RELEASE).as_deref(), Some("1.21"));
+    assert_eq!(key("1.9.4", RELEASE).as_deref(), Some("1.9"));
+    assert_eq!(key("1.7.10", RELEASE).as_deref(), Some("1.7"));
+    // 2. 预发布：切掉 `-pre3` 之后与它的正式版同一个桶
+    assert_eq!(key("1.21.9-pre3", SNAPSHOT).as_deref(), Some("1.21"));
+    assert_eq!(key("1.21-rc1", SNAPSHOT).as_deref(), Some("1.21"));
+    assert_eq!(
+        key("1.21.9-pre3", SNAPSHOT),
+        key("1.21.4", RELEASE),
+        "预发布必须和它的正式版同桶"
+    );
+    // 3. 周更快照：年桶
+    assert_eq!(key("24w14a", SNAPSHOT).as_deref(), Some("24w"));
+    assert_eq!(key("14w02a", SNAPSHOT).as_deref(), Some("14w"));
+    // 4. 远古版：没有主版本
+    assert_eq!(key("rd-132211", ancient(AncientKind::Classic)), None);
+    assert_eq!(key("a1.2.6", ancient(AncientKind::OldAlpha)), None);
+    assert_eq!(key("c0.30_01c", ancient(AncientKind::Classic)), None);
+    assert_eq!(key("b1.7.3", ancient(AncientKind::OldBeta)), None);
+}
+
+/// 「按第一个 `.` 切」的坏法要留下痕迹：同一族的版本不许被拆成两个桶。
+#[test]
+fn splitting_on_the_first_dot_would_break_these_samples() {
+    // 1.7 / 1.9 / 1.21 是三个不同的桶（按第一个点切会全归到 "1"）
+    let buckets = ["1.7.10", "1.9.4", "1.21.4", "1.21.1"]
+        .map(|id| key(id, RELEASE).expect("正式版都有主版本"))
+        .to_vec();
+    assert_eq!(buckets, vec!["1.7", "1.9", "1.21", "1.21"]);
+    assert_ne!(buckets[0], buckets[2]);
+}
+
+/// 版本序：`1.21 > 1.9`（字典序会说反），周更年桶同理。
+#[test]
+fn the_version_order_is_numeric_not_lexicographic() {
+    use std::cmp::Ordering;
+    assert_eq!(compare("1.21", "1.9"), Ordering::Greater);
+    assert_eq!(compare("1.9", "1.21"), Ordering::Less);
+    assert_eq!(compare("24w", "14w"), Ordering::Greater);
+    assert_eq!(compare("1.21", "1.21"), Ordering::Equal);
+
+    let mut labels = vec!["1.9", "1.21", "24w", "1.7"];
+    labels.sort_by(|left, right| compare(right, left));
+    assert_eq!(labels, vec!["24w", "1.21", "1.9", "1.7"]);
+}
+
+/// 桶聚合：数量正确、按版本序降序、无主版本的桶排在最后。
+#[test]
+fn buckets_are_counted_and_sorted() {
+    use unlucky_i18n::Lang;
+
+    let catalog = Lang::En.catalog();
+    let rows: Vec<super::super::model::VersionRow> = [
+        ("1.21.9", RELEASE),
+        ("1.21.8", RELEASE),
+        ("1.20.4", RELEASE),
+        ("24w14a", SNAPSHOT),
+        ("rd-132211", ancient(AncientKind::Classic)),
+    ]
+    .into_iter()
+    .map(|(id, kind)| {
+        super::super::model::VersionRow::of(
+            &unlucky_presenter::dto::VersionSummary {
+                id: id.to_string(),
+                kind,
+                released: "2026-09-20".to_string(),
+                installed: false,
+            },
+            catalog,
+        )
+    })
+    .collect();
+
+    let buckets = buckets(&rows);
+    let keys: Vec<Option<&str>> = buckets.iter().map(|bucket| bucket.key.as_deref()).collect();
+    assert_eq!(
+        keys,
+        vec![Some("24w"), Some("1.21"), Some("1.20"), None],
+        "24w > 1.21 > 1.20 > 无主版本"
+    );
+    assert_eq!(buckets[1].count, 2, "1.21 桶里两个版本");
+    assert_eq!(buckets[3].count, 1, "远古版落在 None 桶");
+}
diff --git a/crates/app-iced/src/pages/download/install.rs b/crates/app-iced/src/pages/download/install.rs
new file mode 100644
index 0000000..93d34c2
--- /dev/null
+++ b/crates/app-iced/src/pages/download/install.rs
@@ -0,0 +1,252 @@
+//! 安装面板（页面底部）：选中版本 → **安装选项** → 「安装」/ 进度 + 「取消」/ 失败 → 「打开日志」。
+//!
+//! M105 之前这里是「选中版本 → 直接『安装』」：点下去就开工，加载器维度整个不存在
+//! （用户实跑的原话：「没是否有选择有前置加载器(版本选择)选项」）。选项区在 `options/`，
+//! 本文件只管**面板形态的决策**（纯函数 [`panel_state`]）与「安装中 / 失败」两种形态。
+//!
+//! ## 这一块为什么钉在底部而不是跟着列表滚
+//!
+//! 列表装的是几十行版本；底部按钮如果跟着滚，用户在列表中间永远看不到「安装」在哪。
+//! 所以列表独立滚动（`rows::list`），面板固定占尾部一块高度。
+//!
+//! ## 只有意图，没有乐观回显
+//!
+//! | 控件 | 消息 | app 层落点 |
+//! |---|---|---|
+//! | 「安装」 | [`Message::InstallVersion`] | `AppCommand::CreateInstance(草稿)`（带加载器与实例名） |
+//! | 「取消安装」 | [`Message::CancelInstall`] | `AppCommand::CancelInstall` |
+//! | 「打开日志」 | [`Message::Navigate`]（`Route::Logs`） | `AppState::navigate`（不派指令） |
+//!
+//! 按钮按下**不改任何本地状态**：进度条读的是 `model.install`，它只由 presenter 的
+//! `InstallProgress` 事件灌进来（`apply` → 视图模型重建）。于是「点了没变」= 后端还没回事件。
+//!
+//! ## 三种面板形态刻意不同构（M94 r1 / P2-3 + P2-4）
+//!
+//! | 状态 | 形态 | 为什么 |
+//! |---|---|---|
+//! | 选好了 | 版本 id + 实心「安装」 | 本页唯一的实心按钮（rubric K2） |
+//! | 安装中 | 版本 id + 阶段 + **进度条**（仅当进度已知）+ 计数 + 文本「取消安装」 | 有进度才有条 |
+//! | 失败 | **整块 `ErrorContainer` 面板**：`Error` 图标 + `Error` 色标题 + 停在哪 + 实心「打开日志」 | **不画进度条**——进度条正是「看起来还在跑」的来源；颜色/图标/措辞/按钮四样一起变，才一眼可辨 |
+//!
+//! 进度未知（刚派发、后端还没给文件计数）时**不画条**：页面没有帧订阅，`Progress::indeterminate`
+//! 只会得到一个静止的假进度（复审 P2-3 的「17% 卡住」），不如只写「等第一个文件…」。
+
+use iced::widget::{column, container, row};
+use iced::{Alignment, Background, Border, Element, Length, Padding};
+
+use unlucky_design::color::Role;
+use unlucky_design::icons::IconKind;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use unlucky_presenter::router::Route;
+
+use unlucky_i18n::{Catalog, Key};
+
+use crate::app::components::buttons::{self, Button};
+use crate::app::components::feedback::{linear, Progress};
+use crate::theme::Ui;
+
+use super::super::frame;
+use super::super::Message;
+use super::model::{Download, InstallView};
+use super::options::OptionsView;
+
+/// 面板要画哪一种形态（**决策与画法分开**：决策是纯函数，单测直接钉它）。
+///
+/// 分开的理由就是本轮复审那件事：「装完之后面板还占着、用户再也装不了第二个版本」——
+/// 这是**决策**错了，画法本身没错；把决策抽出来，测试才能在不开图形环境的情况下断言它。
+#[derive(Debug, Clone, PartialEq)]
+pub(super) enum PanelState<'a> {
+    /// 没有安装、也没选中：一句「选一个版本再安装」
+    Hint,
+    /// 选中了一个版本：给出**安装选项区**（M105；加载器 / 加载器版本 / 实例名 + 「安装」）
+    Options(&'a OptionsView),
+    /// 有安装（进行中 / 失败）：进度或错误面板
+    Install(&'a InstallView),
+}
+
+/// 面板此刻该画哪一种（纯函数，无 iced）。
+///
+/// 顺序是**安装优先**：有安装时面板讲安装，讲不了列表；安装结束后 `model.install` 由
+/// [`Download::from_snapshot`](super::model::Download::from_snapshot) 清掉，于是这里自然回到
+/// [`PanelState::Options`] / [`PanelState::Hint`]，用户能接着选下一个版本。
+pub(super) fn panel_state(model: &Download) -> PanelState<'_> {
+    match &model.install {
+        Some(install) => PanelState::Install(install),
+        None => match &model.options {
+            Some(options) => PanelState::Options(options),
+            None => PanelState::Hint,
+        },
+    }
+}
+
+/// 底部的安装面板。
+pub(super) fn panel<'a>(ui: &'a Ui, catalog: Catalog, model: &'a Download) -> Element<'a, Message> {
+    let content = match panel_state(model) {
+        PanelState::Install(install) => installing(ui, catalog, install),
+        // 选中版本之后**先给选项，再点「安装」**（M105：以前是选中就直接开工，等于没有加载器维度）
+        PanelState::Options(options) => super::options::section(ui, catalog, options),
+        PanelState::Hint => hint(ui, catalog),
+    };
+
+    container(content)
+        .width(Length::Fill)
+        .padding(Padding::from([ui.space(Space::X3), 0.0]))
+        .into()
+}
+
+/// 没选中任何版本：给一句「选一个版本再安装」（不静默禁用，也不画一个点不动的按钮）。
+fn hint<'a>(ui: &'a Ui, catalog: Catalog) -> Element<'a, Message> {
+    frame::text_role(
+        ui,
+        TypeRole::BodySmall,
+        false,
+        catalog.text(Key::DownloadSelectHint),
+        ui.color(Role::OnSurfaceVariant),
+    )
+}
+
+/// 安装中 / 已收尾（失败另走 [`failed`]）。
+fn installing<'a>(ui: &'a Ui, catalog: Catalog, install: &'a InstallView) -> Element<'a, Message> {
+    if install.failed() {
+        return failed(ui, catalog, install);
+    }
+
+    let head = row![
+        container(frame::text_role(
+            ui,
+            TypeRole::BodyMedium,
+            false,
+            install.version.as_str(),
+            ui.color(Role::OnSurface),
+        ))
+        .width(Length::Fill),
+        frame::text_role(
+            ui,
+            TypeRole::LabelMedium,
+            false,
+            install.stage_label.as_str(),
+            ui.color(Role::OnSurfaceVariant),
+        ),
+    ]
+    .width(Length::Fill)
+    .align_y(Alignment::Center);
+
+    let mut body = column![head];
+    // 进度已知才画条：未知时画 indeterminate 会得到一个静止的假进度（见模块文档）。
+    if install.known {
+        body = body.push(linear(ui, Progress::determinate(install.ratio)));
+    }
+    body = body.push(frame::text_role(
+        ui,
+        TypeRole::BodySmall,
+        false,
+        install.detail.as_str(),
+        ui.color(Role::OnSurfaceVariant),
+    ));
+    if let Some(rate) = &install.rate {
+        body = body.push(frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            rate.as_str(),
+            ui.color(Role::OnSurfaceVariant),
+        ));
+    }
+
+    let action = if install.running() {
+        buttons::text(
+            ui,
+            Button::new(catalog.text(Key::DownloadCancel), Message::CancelInstall),
+        )
+    } else {
+        frame::gap(0.0)
+    };
+
+    column![
+        body.spacing(ui.space(Space::X2)).width(Length::Fill),
+        action
+    ]
+    .spacing(ui.space(Space::X2))
+    .width(Length::Fill)
+    .into()
+}
+
+/// 失败态：一整块 `ErrorContainer` 面板（**没有进度条**）。
+///
+/// 四样一起变，保证与「正在下载」一眼可辨：容器色（`ErrorContainer`）/ 图标（`Error`）/
+/// 措辞（`Install failed` 用 `Error` 色标题）/ 主按钮（实心「打开日志」，不是文本按钮）。
+fn failed<'a>(ui: &'a Ui, catalog: Catalog, install: &'a InstallView) -> Element<'a, Message> {
+    let head = row![
+        frame::glyph(IconKind::Error, ui.color(Role::Error), frame::ICON_PX),
+        frame::text_role(
+            ui,
+            TypeRole::TitleSmall,
+            true,
+            catalog.text(Key::DownloadStageFailed),
+            ui.color(Role::Error),
+        ),
+    ]
+    .spacing(ui.space(Space::X2))
+    .align_y(Alignment::Center);
+
+    let stopped = frame::text_role_owned(
+        ui,
+        TypeRole::BodySmall,
+        false,
+        format!("{} · {}", install.version, install.detail),
+        ui.color(Role::OnErrorContainer),
+    );
+
+    let actions = row![
+        buttons::filled(
+            ui,
+            Button::new(
+                catalog.text(Key::DownloadOpenLogs),
+                Message::Navigate(Route::Logs),
+            )
+            .leading(IconKind::Logs),
+        ),
+        // 失败把面板钉住了：不给出口的话用户既重试不了、也装不了别的版本（只能重启）。
+        // `CancelInstall` 在 host 侧就是「清 install + 发 InstallProgress(None)」，对没在跑的任务是安全 no-op。
+        buttons::text(
+            ui,
+            Button::new(catalog.text(Key::DownloadDismiss), Message::CancelInstall),
+        ),
+    ]
+    .spacing(ui.space(Space::X2))
+    .align_y(Alignment::Center);
+
+    container(
+        column![
+            head,
+            stopped,
+            frame::text_role(
+                ui,
+                TypeRole::BodySmall,
+                false,
+                catalog.text(Key::DownloadFailedHint),
+                ui.color(Role::OnErrorContainer),
+            ),
+            actions,
+        ]
+        .spacing(ui.space(Space::X2))
+        .width(Length::Fill),
+    )
+    .width(Length::Fill)
+    .padding(ui.space(Space::X4))
+    .style(move |_theme| container::Style {
+        background: Some(Background::Color(ui.color(Role::ErrorContainer))),
+        border: Border {
+            radius: ui.radius_dp(ShapeScale::Large),
+            ..Border::default()
+        },
+        ..container::Style::default()
+    })
+    .into()
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/app-iced/src/pages/download/install/tests.rs b/crates/app-iced/src/pages/download/install/tests.rs
new file mode 100644
index 0000000..e960bb5
--- /dev/null
+++ b/crates/app-iced/src/pages/download/install/tests.rs
@@ -0,0 +1,136 @@
+//! 安装面板的决策测试（M94 r2）。
+//!
+//! 从 `install.rs` 外置（那边加上本轮修复会顶到 400 行）。`use super::*` 仍指向
+//! `crate::pages::download::install`，`PanelState` / `panel_state` 是那里的 `pub(super)`。
+//!
+//! **不走 `MockBackend`**：`MockBackend::script_install` 只发 Dialog + Toast、从不发
+//! `InstallProgress`（复审 r1 的取证），所以 mock 下 `install` 恒为 `None`，终态分支永远跑不到——
+//! 用 mock 写的测试会**假绿**。这里直接构造 `AppState` 并 `apply(CoreEvent::InstallProgress(..))`。
+
+use unlucky_presenter::dto::{
+    AppEvent, CoreEvent, InstallProgressView, InstallStage, VersionKind, VersionSummary,
+};
+use unlucky_presenter::state::AppState;
+
+use unlucky_i18n::Lang;
+
+use super::super::model::{Category, Download};
+use super::super::options::InstallDraft;
+use super::{panel_state, PanelState};
+
+fn version(id: &str) -> VersionSummary {
+    VersionSummary {
+        id: id.to_string(),
+        kind: VersionKind::Release,
+        released: "2026-09-20".to_string(),
+        installed: false,
+    }
+}
+
+fn progress(stage: InstallStage) -> InstallProgressView {
+    InstallProgressView {
+        version: "1.21.9".to_string(),
+        stage,
+        files_done: 512,
+        files_total: 512,
+        ..InstallProgressView::new()
+    }
+}
+
+fn snapshot(stage: InstallStage) -> AppState {
+    let mut state = AppState::new();
+    state.apply(AppEvent::Core(CoreEvent::VersionListChanged(vec![
+        version("1.21.9"),
+        version("1.21.8"),
+    ])));
+    state.apply(AppEvent::Core(CoreEvent::InstallProgress(Some(progress(
+        stage,
+    )))));
+    state
+}
+
+/// **装完之后页面必须回到「能再装下一个」**（复审 p2 的修复验收）。
+///
+/// 复审现象：`InstallDone` 从不清 `AppState.install`（presenter 只在取消时清），而面板**优先**
+/// 用 `install`，终态又没有可执行动作 ⇒ 装完第一个版本后按钮永久消失，只能重启进程。
+///
+/// 抓得住：`Done` 之后面板还被 `install` 占着（= 装不了第二个版本的根因）、列表没回来、
+/// 面板不再给「安装」。测试直接钉 [`panel_state`]——那是 `panel()` 唯一的决策入口，两者不会漂。
+/// 抓不住：presenter 侧 `AppState.install` 仍是 `Some(Done)`（proper fix 不在本 mission，已报 finding）；
+/// 也抓不住「装完后已装标记不刷新」（同一个 finding）。
+#[test]
+fn a_finished_install_gives_the_page_back_to_the_list() {
+    let running = Download::from_snapshot(
+        &snapshot(InstallStage::Downloading),
+        Category::All,
+        &InstallDraft::default(),
+        Lang::En.catalog(),
+    );
+    assert!(running.install.is_some(), "跑着的时候面板要在");
+    assert!(matches!(panel_state(&running), PanelState::Install(_)));
+
+    let state = snapshot(InstallStage::Done);
+    assert_eq!(
+        state.install.as_ref().map(|view| view.stage),
+        Some(InstallStage::Done),
+        "现实如此：快照里仍留着终态（presenter 不清），页面必须自己让位"
+    );
+
+    let model = Download::from_snapshot(
+        &state,
+        Category::All,
+        &InstallDraft::default(),
+        Lang::En.catalog(),
+    );
+    assert!(model.install.is_none(), "Done 之后不许再占着安装面板");
+    assert!(model.selected.is_none(), "装完不替用户选中任何行");
+    assert_eq!(model.rows.len(), 2, "列表要回来");
+    assert_eq!(
+        panel_state(&model),
+        PanelState::Hint,
+        "回到「选一个版本再安装」"
+    );
+
+    // 再装一次：选中下一个版本 → 面板重新给出**安装选项区**（M105 起「安装」在选项区里）
+    let next = Download::from_snapshot(
+        &state,
+        Category::All,
+        &InstallDraft {
+            selected: Some("1.21.9".to_string()),
+            ..InstallDraft::default()
+        },
+        Lang::En.catalog(),
+    );
+    let options = match panel_state(&next) {
+        PanelState::Options(options) => options,
+        other => panic!("装完之后必须能接着装下一个版本，实际 {other:?}"),
+    };
+    assert_eq!(options.version, "1.21.9");
+    assert!(options.can_confirm, "原版 + 列表里的版本 = 可以装");
+}
+
+/// 取消与失败**不许**一起被清：失败态是 P2-4 的错误出口，取消是「已经没事了」。
+///
+/// 抓得住：把 `finished()` 写成「terminated()」（那会把失败态的日志入口一起清掉，用户失去原因）。
+/// 抓不住：presenter 在取消后是否补发 `InstallProgress(None)`（那是 presenter 的行为）。
+#[test]
+fn only_done_and_cancelled_release_the_panel() {
+    let failed = Download::from_snapshot(
+        &snapshot(InstallStage::Failed),
+        Category::All,
+        &InstallDraft::default(),
+        Lang::En.catalog(),
+    );
+    assert!(failed.install.is_some(), "失败态要留在屏幕上");
+    assert!(matches!(panel_state(&failed), PanelState::Install(_)));
+
+    for stage in [InstallStage::Done, InstallStage::Cancelled] {
+        let model = Download::from_snapshot(
+            &snapshot(stage),
+            Category::All,
+            &InstallDraft::default(),
+            Lang::En.catalog(),
+        );
+        assert!(model.install.is_none(), "{stage:?} 之后面板要让位");
+    }
+}
diff --git a/crates/app-iced/src/pages/download/model.rs b/crates/app-iced/src/pages/download/model.rs
new file mode 100644
index 0000000..b2756f2
--- /dev/null
+++ b/crates/app-iced/src/pages/download/model.rs
@@ -0,0 +1,367 @@
+//! 下载页视图模型：**presenter 快照 → 页面要画的东西**（与 [`super::super::model`] 同一套分层）。
+//!
+//! ## 为什么这一页也要中间层
+//!
+//! 页面层不认识 presenter 的 DTO（同实例页的理由）：真页面吃 `AppState` 的快照，
+//! 演示数据与单测吃 [`super::demo`]，两边都转成这里的纯展示字段。
+//!
+//! 文案在这一层就按 [`Catalog`] 求好值（`supporting` / `detail` / `rate` 都是 `String`）：
+//! iced 的文字控件**借用**内容，行内文案又是 `format!` 出来的，不先落成字段就没法进控件树
+//! （`pages/frame` 的 `text_role_owned` 是同一个理由的单行版）。
+//!
+//! ## 快照里**没有**的东西（都登记在 `pages/mod.rs` 的偏离表里）
+//!
+//! | 缺什么 | 后果 | 兜法 |
+//! |---|---|---|
+//! | 「版本列表已加载完成」标志 | 空列表既可能是「还没拉到」也可能是「真的没有」 | [`Download::loaded`] 按「快照里有没有版本」判：没有 = 加载中 |
+//! | 版本列表**失败**事件 | 拉取失败会停在加载态（不静默：页面上有说明与刷新入口） | 错误态借安装阶段的 `Failed`（结构化、可翻译） |
+//! | 「当前选中」字段 | 选中态存在模型里，任何快照重建都会回到「正在安装的那个版本」 | 见 `pages/mod.rs` 偏离登记；长期要靠 presenter 加字段 |
+//!
+//! ## 中文串一个都不许画
+//!
+//! `InstallProgressView::message` / `InstallStage::label()` 都是**中文业务串**（`i18n::bridge`
+//! 的规矩 2：core 的中文串只给日志和 CLI）。所以这里只搬**结构化字段**（阶段枚举、计数、字节），
+//! 文案按 `Key` 现求——中文环境自然出中文，英文环境不需要任何中文字体。
+
+use unlucky_presenter::dto::{
+    human_bytes, InstallProgressView, InstallStage, VersionKind, VersionSummary,
+};
+use unlucky_presenter::state::AppState;
+
+use unlucky_i18n::{Catalog, Key, Lang};
+
+use super::options::{InstallDraft, OptionsView};
+
+/// 取消安装之后那一句提示（M105）。
+///
+/// 为什么文案在页面层而不是 presenter：取消的**信号**由 host 发（`CoreEvent::InstallCancelled`），
+/// 但 presenter 不依赖 `unlucky-i18n`，写死的中文会和页面语言打架（复审 P2-2 抓的就是这个：
+/// 选项区是英文、取消弹窗是中文）。所以文本按 `Key` 现求，语言跟着页面走。
+#[must_use]
+pub fn cancelled_toast(lang: Lang) -> String {
+    lang.catalog().text(Key::DownloadCancelled).to_owned()
+}
+
+mod category;
+
+pub use category::Category;
+
+/// 版本列表的一行（`ListItem` 的两行档：headline = 版本 id，supporting = `正式版 · 发布于 …`）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct VersionRow {
+    /// 版本 id（`1.21.9` / `rd-132211`）——也是「安装」指令的载荷
+    pub id: String,
+    /// 发布日期（ISO-8601 日期部分，快照原样）
+    pub released: String,
+    /// 版本类型
+    pub kind: VersionKind,
+    /// 本地是否已安装（行上给勾 / overline `Installed`）
+    pub installed: bool,
+    /// 副文案（`正式版 · 发布于 2026-09-20`；一行 = 一个 key，不拼片段）
+    pub supporting: String,
+}
+
+impl VersionRow {
+    pub(super) fn of(version: &VersionSummary, catalog: Catalog) -> Self {
+        Self {
+            id: version.id.clone(),
+            released: version.released.clone(),
+            kind: version.kind,
+            installed: version.installed,
+            supporting: catalog.render(
+                Key::DownloadRowSupporting,
+                &[
+                    ("kind", catalog.text(kind_label_key(version.kind))),
+                    ("date", version.released.as_str()),
+                ],
+            ),
+        }
+    }
+
+    /// 这个版本属于哪个主版本桶（规则见 [`super::group`]）。
+    pub fn major(&self) -> Option<super::group::MajorKey> {
+        super::group::key(&self.id, self.kind)
+    }
+}
+
+/// 版本类型 → 文案 key（远古版不分子类：chip 只有一档，行上再分子类等于两套语言）。
+pub(super) const fn kind_label_key(kind: VersionKind) -> Key {
+    match kind {
+        VersionKind::Release => Key::DownloadCategoryRelease,
+        VersionKind::Snapshot => Key::DownloadCategorySnapshot,
+        VersionKind::Ancient(_) => Key::DownloadCategoryAncient,
+    }
+}
+
+/// 一次安装的展示态（结构化字段 + 已求好的文案）。
+#[derive(Debug, Clone, PartialEq)]
+pub struct InstallView {
+    /// 目标版本（= 选中的那一行）
+    pub version: String,
+    /// 阶段
+    pub stage: InstallStage,
+    /// 阶段词（`下载文件`）
+    pub stage_label: String,
+    /// 计数行（`128/512 文件`；未知时是「等第一个文件…」）
+    pub detail: String,
+    /// 速率 + 剩余时间（`1.2 MB/s · 剩 1m15s`；未知时 `None`）
+    pub rate: Option<String>,
+    /// 整体进度 0.0~1.0
+    pub ratio: f32,
+    /// 进度是否已知（`false` = 进度条画不确定态）
+    pub known: bool,
+}
+
+impl InstallView {
+    /// 快照 → 展示态。
+    pub(super) fn of(progress: &InstallProgressView, catalog: Catalog) -> Self {
+        let known = progress.is_known();
+        let detail = if known {
+            catalog.render(
+                Key::DownloadProgress,
+                &[
+                    ("done", &progress.files_done.to_string()),
+                    ("total", &progress.files_total.to_string()),
+                ],
+            )
+        } else {
+            catalog.text(Key::DownloadProgressUnknown).to_owned()
+        };
+        let rate = if progress.speed_bps == 0 || progress.eta_secs == 0 {
+            None
+        } else {
+            let eta = if progress.eta_secs >= 60 {
+                catalog.render(
+                    Key::DownloadEtaMins,
+                    &[
+                        ("mins", &(progress.eta_secs / 60).to_string()),
+                        ("secs", &format!("{:02}", progress.eta_secs % 60)),
+                    ],
+                )
+            } else {
+                catalog.render(
+                    Key::DownloadEtaSecs,
+                    &[("secs", &progress.eta_secs.to_string())],
+                )
+            };
+            Some(catalog.render(
+                Key::DownloadRate,
+                &[
+                    ("speed", &format!("{}/s", human_bytes(progress.speed_bps))),
+                    ("eta", eta.as_str()),
+                ],
+            ))
+        };
+
+        Self {
+            version: progress.version.clone(),
+            stage: progress.stage,
+            stage_label: catalog.text(stage_key(progress.stage)).to_owned(),
+            detail,
+            rate,
+            ratio: progress.ratio(),
+            known,
+        }
+    }
+
+    /// 失败了（错误态要出可读文案 + 出口，不许静默）。
+    pub const fn failed(&self) -> bool {
+        matches!(self.stage, InstallStage::Failed)
+    }
+
+    /// 收尾了（`Done` / `Failed` / `Cancelled`）。
+    pub fn terminal(&self) -> bool {
+        self.stage.is_terminal()
+    }
+
+    /// **结束且没什么可说**的收尾：成功（`Done`）与取消（`Cancelled`）。
+    ///
+    /// 这两种终态页面没有动作可给，留着只会让安装面板停在一个点不动的状态上（复审 p2 的根因）。
+    /// 失败**不在其中**：它还要给原因出口。
+    pub fn finished(&self) -> bool {
+        matches!(self.stage, InstallStage::Done | InstallStage::Cancelled)
+    }
+
+    /// 还在跑（「取消安装」只在这时给）。
+    pub fn running(&self) -> bool {
+        !self.stage.is_terminal()
+    }
+}
+
+/// 阶段 → 文案 key（**不**用 `InstallStage::label()`：那是中文业务串）。
+const fn stage_key(stage: InstallStage) -> Key {
+    match stage {
+        InstallStage::Planning => Key::DownloadStagePlanning,
+        InstallStage::Downloading => Key::DownloadStageDownloading,
+        InstallStage::Installing => Key::DownloadStageInstalling,
+        InstallStage::Registering => Key::DownloadStageRegistering,
+        InstallStage::Done => Key::DownloadStageDone,
+        InstallStage::Failed => Key::DownloadStageFailed,
+        InstallStage::Cancelled => Key::DownloadStageCancelled,
+    }
+}
+
+/// 下载页要画的东西（**全部字段都能从快照推出来**，页面自己不留状态）。
+#[derive(Debug, Clone, PartialEq, Default)]
+pub struct Download {
+    /// 版本列表（顺序 = 快照顺序）
+    pub rows: Vec<VersionRow>,
+    /// 当前分类（从快照反推）
+    pub category: Category,
+    /// 选中的版本 id（`None` = 没选中 → 面板只给一句提示）
+    pub selected: Option<String>,
+    /// 安装选项区（M105）：选中了版本、又没在装的时候才有
+    pub options: Option<OptionsView>,
+    /// 正在跑（或刚跑完）的安装
+    pub install: Option<InstallView>,
+    /// 快照里有没有版本列表（`false` = 还没拉到 → 加载态）
+    pub loaded: bool,
+    /// 搜索词（presenter 的 `download_query` 原样；空串 = 不过滤）
+    pub query: String,
+    /// **跨分类**命中数：搜索时侧栏显示它，所以它不随当前分类变化
+    pub hits: usize,
+    /// 选中的主版本桶（`None` = 全部；第二级侧栏的选中态，纯视图态）
+    pub selected_major: Option<String>,
+    /// 类型栏被用户手动折叠（`true` = 64 图标条；宽度档自己也会折叠，两者取更窄的）
+    pub type_rail_folded: bool,
+    /// 主版本桶（第二级侧栏的数据源；由 [`Self::rows`] 聚合，所以只含**当前分类**的桶）
+    pub buckets: Vec<super::group::Bucket>,
+}
+
+impl Download {
+    /// 空模型 = 加载态（首帧，以及 `pages::Model::new` 的默认值）。
+    pub fn loading() -> Self {
+        Self::default()
+    }
+
+    /// presenter 快照 → 下载页模型（**唯一的真数据入口**）。
+    ///
+    /// 三个过滤条件都是「过滤」，不是「乐观回显」：
+    /// - `installed_only` / `download_query` 是 presenter 自己的状态，页面不该另存一份；
+    /// - `category` 是**本页的过滤条件**（参数传进来，调用方持有它）：真 host 的
+    ///   `AppCommand::ListVersions(_)` 会丢掉分类参数、回全量清单（见 `host/dispatch.rs`），
+    ///   所以分类**必须在页面这一侧过滤**，否则 chip 只是点亮一下、列表照旧是全量（复审 P2-1）。
+    ///   过滤谓词与 chip 的选中判断是同一个 [`Category::matches`]，于是「chip 说的」与「列表画的」
+    ///   永远是同一份真相，事件回来重建也不会跳回「全部」。
+    ///
+    /// 过滤后为空就是「空态」（`loaded` 仍为 `true`）。
+    ///
+    /// `draft` 是**用户还没确认的安装输入**（选中版本 + 加载器 + 加载器版本 + 实例名）。
+    /// 它住在 `App`（照分类筛选的既有做法），因为 `refresh_view` 每次事件都会把整棵模型重建，
+    /// 页面自己存不住任何东西。选中项还要**在当前列表里**才算数：切分类后那一行不在了，
+    /// 就不该还留着一个点不动的「安装」。
+    ///
+    /// M107：`query` / `hits` / `buckets` 也走这条路——查询词来自快照的 `download_query`，
+    /// 桶由过滤后的行聚合（第二级侧栏的数据源）。
+    pub fn from_snapshot(
+        state: &AppState,
+        category: Category,
+        draft: &InstallDraft,
+        catalog: Catalog,
+    ) -> Self {
+        let query = state.download_query.trim().to_ascii_lowercase();
+        // 过滤谓词写一次、两处用：`hits` 是**跨分类**命中数（搜索框旁边的「N 个结果」不能
+        // 随当前分类变，否则用户在「正式版」里搜一个只有快照才有的串会看到 0）。
+        let matches = |version: &VersionSummary| {
+            (!state.installed_only || version.installed)
+                && (query.is_empty() || version.id.to_ascii_lowercase().contains(&query))
+        };
+
+        let hits = state
+            .versions
+            .iter()
+            .filter(|version| matches(version))
+            .count();
+        let rows = state
+            .versions
+            .iter()
+            .filter(|version| matches(version) && category.matches(version.kind))
+            .map(|version| VersionRow::of(version, catalog))
+            .collect::<Vec<_>>();
+
+        let install = state
+            .install
+            .as_ref()
+            .map(|view| InstallView::of(view, catalog))
+            // 安装**已经成功结束/被取消**就不再占用面板（复审 p2，本轮的修复点）：
+            // presenter 只在 `InstallProgress(None)`（取消指令）时清 `AppState.install`，`Done`
+            // 会一直留在快照里 ⇒ 面板被一个**没有动作**的终态钉死，用户装完第一个版本就再也发不出
+            // 第二次安装（只能重启进程）。界面这里把「结束」当结束：面板让回列表。
+            //
+            // 为什么不连 `Failed` 一起清：失败态带着用户要的东西（停在哪个文件 + 去日志页），
+            // 那正是 P2-4 要它一眼可辨的理由。
+            .filter(|view| !view.finished());
+        // 选中项：安装中就是正在装的那个；否则是用户点的那个（草稿），且必须还在当前列表里。
+        let selected = install
+            .as_ref()
+            .map(|view| view.version.clone())
+            .or_else(|| draft.selected.clone())
+            .filter(|id| rows.iter().any(|row| &row.id == id));
+        // 选项区与安装面板**互斥**：在装的时候面板讲进度，讲不了选项。
+        let options = match &install {
+            Some(_) => None,
+            None => selected.as_ref().and_then(|id| {
+                rows.iter()
+                    .find(|row| &row.id == id)
+                    .map(|row| OptionsView::of(row, state, draft, catalog))
+            }),
+        };
+
+        Self {
+            // 桶由**过滤后的行**聚合：第二级侧栏只列当前分类里真实出现的版本族。
+            buckets: super::group::buckets(&rows),
+            rows,
+            // 分类不再从列表反推（那正是「chip 跳回全部」的来源）：谁选的就是谁。
+            // [`Category::of`] 只留给「不经过用户选择」的入口（演示数据的首帧）。
+            category,
+            selected,
+            options,
+            install,
+            loaded: !state.versions.is_empty(),
+            // 搜索词与命中数都来自快照：页面不持有查询（见模块文档「为什么搜索也走快照」）。
+            query: state.download_query.trim().to_owned(),
+            hits,
+            // 主版本桶的选中是**纯视图态**（同 `selected`）：快照重建会回到「全部」。
+            selected_major: None,
+            // 折叠也是纯视图态；搜索重建时由 `rebuild_after_query` 前后各搬一次。
+            type_rail_folded: false,
+        }
+    }
+
+    /// 选中的那一行（安装面板上的版本名）。
+    pub fn selected_row(&self) -> Option<&VersionRow> {
+        let id = self.selected.as_deref()?;
+        self.rows.iter().find(|row| row.id == id)
+    }
+
+    /// 加载态：快照里还没有版本列表。
+    pub const fn is_loading(&self) -> bool {
+        !self.loaded
+    }
+
+    /// 空态：列表拉到了，但过滤之后一行都不剩。
+    pub fn is_empty(&self) -> bool {
+        self.loaded && self.rows.is_empty()
+    }
+
+    /// 有搜索词（空串不算：用户在框里敲了空格不该触发「没有匹配」）。
+    pub fn has_query(&self) -> bool {
+        !self.query.is_empty()
+    }
+
+    /// **整份清单**里一个都不匹配（跨分类也没有）⇒ 画「没有匹配」而不是白屏。
+    pub fn no_match(&self) -> bool {
+        self.loaded && self.has_query() && self.hits == 0
+    }
+
+    /// 有命中、但**不在当前分类**里 ⇒ 画「N 个版本在别的类型下」，并给一个「看全部」的出口。
+    ///
+    /// 这条与 [`Self::no_match`] 分开，是因为两者该说的话完全不同：一个是「真的没有」，
+    /// 一个是「有，但你站错了分类」——后者让用户多点一次 tab 就白跑一趟。
+    pub fn only_elsewhere(&self) -> bool {
+        self.loaded && self.rows.is_empty() && self.hits > 0
+    }
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/app-iced/src/pages/download/model/category.rs b/crates/app-iced/src/pages/download/model/category.rs
new file mode 100644
index 0000000..eab9afa
--- /dev/null
+++ b/crates/app-iced/src/pages/download/model/category.rs
@@ -0,0 +1,85 @@
+//! 分类筛选（原顶部四个 chip / 现在是第一级侧栏的四个固定项）。
+//!
+//! 从 `model.rs` 搬出来：M105/M107 合流后那边到 441 行（超 400 硬线）。
+//! **纯搬移**：枚举、`matches` 谓词、`command()` 与 `of()` 一字未改，
+//! 路径仍由 `model.rs` 的 `pub use` 保持 `pages::download::Category`。
+
+use unlucky_i18n::Key;
+use unlucky_presenter::dto::{AncientKind, VersionCategory, VersionKind, VersionSummary};
+
+/// 分类筛选（页面上的四个 filter chip）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum Category {
+    /// 不过滤：画快照里有什么就是什么（首帧与 `RefreshAll` 的落点）
+    #[default]
+    All,
+    /// 正式版
+    Release,
+    /// 预览版
+    Snapshot,
+    /// 远古版（快照里按 `AncientKind` 分四类，页面先只认一个 chip）
+    Ancient,
+}
+
+impl Category {
+    /// 四个 chip 的声明顺序（= 画出来的顺序）。
+    pub const ALL: [Category; 4] = [
+        Category::All,
+        Category::Release,
+        Category::Snapshot,
+        Category::Ancient,
+    ];
+
+    /// chip 文案的 key。
+    pub const fn label_key(self) -> Key {
+        match self {
+            Category::All => Key::DownloadCategoryAll,
+            Category::Release => Key::DownloadCategoryRelease,
+            Category::Snapshot => Key::DownloadCategorySnapshot,
+            Category::Ancient => Key::DownloadCategoryAncient,
+        }
+    }
+
+    /// 点这个 chip 要派的指令（`None` = 不派：`All` 就是「把当前快照全画出来」）。
+    ///
+    /// 远古版在 `VersionCategory` 里是**带子类的**（`Ancient(AncientKind)`），一个 chip 拉不全四类；
+    /// 这里先拉 `Classic`，四子类同屏要靠 presenter 侧支持（已登记 finding）。
+    pub const fn command(self) -> Option<VersionCategory> {
+        match self {
+            Category::All => None,
+            Category::Release => Some(VersionCategory::Release),
+            Category::Snapshot => Some(VersionCategory::Snapshot),
+            Category::Ancient => Some(VersionCategory::Ancient(AncientKind::Classic)),
+        }
+    }
+
+    /// 这个版本属于这个分类吗。
+    pub fn matches(self, kind: VersionKind) -> bool {
+        match self {
+            Category::All => true,
+            Category::Release => kind == VersionKind::Release,
+            Category::Snapshot => kind == VersionKind::Snapshot,
+            Category::Ancient => kind.is_ancient(),
+        }
+    }
+
+    /// 从快照里**反推**当前分类：整份列表只有一类 → 那一类；混合或为空 → [`Category::All`]。
+    ///
+    /// 快照没有「我上次按哪个分类拉的」这种字段，所以分类靠列表内容反推
+    /// （`ListVersions` 的结果是单一分类，`RefreshAll` 的结果是混合）。
+    pub fn of(versions: &[VersionSummary]) -> Self {
+        let mut kinds = versions.iter().map(|version| version.kind);
+        let Some(first) = kinds.next() else {
+            return Category::All;
+        };
+        if kinds.all(|kind| kind == first) {
+            match first {
+                VersionKind::Release => Category::Release,
+                VersionKind::Snapshot => Category::Snapshot,
+                VersionKind::Ancient(_) => Category::Ancient,
+            }
+        } else {
+            Category::All
+        }
+    }
+}
diff --git a/crates/app-iced/src/pages/download/model/tests.rs b/crates/app-iced/src/pages/download/model/tests.rs
new file mode 100644
index 0000000..678adc4
--- /dev/null
+++ b/crates/app-iced/src/pages/download/model/tests.rs
@@ -0,0 +1,78 @@
+//! 视图模型的判据（从 `model.rs` 外置：那边加上本轮的分类过滤会顶到 400 行）。
+
+use unlucky_presenter::dto::{AncientKind, AppEvent, CoreEvent, VersionKind, VersionSummary};
+use unlucky_presenter::state::AppState;
+
+use unlucky_i18n::Lang;
+
+use super::super::options::InstallDraft;
+use super::{Category, Download};
+
+fn version(id: &str, kind: VersionKind) -> VersionSummary {
+    VersionSummary {
+        id: id.to_string(),
+        kind,
+        released: "2026-09-20".to_string(),
+        installed: false,
+    }
+}
+
+fn state_with(versions: Vec<VersionSummary>) -> AppState {
+    let mut state = AppState::new();
+    state.apply(AppEvent::Core(CoreEvent::VersionListChanged(versions)));
+    state
+}
+
+/// 分类筛选是**本页的过滤**（复审 P2-1：真 host 的 `ListVersions(_)` 丢掉分类参数、回全量清单）。
+///
+/// 抓得住：`from_snapshot` 忘了按分类过滤——那正是「chip 点亮一下、列表照旧全量、事件回来 chip
+/// 跳回『全部』」的根因；也抓得住「分类被列表反推覆盖」（`Category::of` 回到 `All`）。
+/// 抓不住：真 host 是否按分类拉清单（`host/dispatch.rs:30` 丢参数，已报 finding）。
+#[test]
+fn the_category_filters_the_list_locally() {
+    let state = state_with(vec![
+        version("1.21.9", VersionKind::Release),
+        version("1.21.9-pre3", VersionKind::Snapshot),
+        version("rd-132211", VersionKind::Ancient(AncientKind::Classic)),
+    ]);
+
+    let release = Download::from_snapshot(
+        &state,
+        Category::Release,
+        &InstallDraft::default(),
+        Lang::En.catalog(),
+    );
+    assert_eq!(
+        release.category,
+        Category::Release,
+        "谁选的就是谁：不从列表反推（反推会把混合列表打回 All）"
+    );
+    assert_eq!(release.rows.len(), 1, "只剩正式版");
+    assert_eq!(release.rows[0].id, "1.21.9");
+
+    let all = Download::from_snapshot(
+        &state,
+        Category::All,
+        &InstallDraft::default(),
+        Lang::En.catalog(),
+    );
+    assert_eq!(all.rows.len(), 3, "「全部」不过滤");
+}
+
+/// 分类把行全滤掉时是**空态**，不是加载态（两态文案与位置不同，别混）。
+///
+/// 抓得住：把「筛出来是空」当成「还没拉到」。
+/// 抓不住：用户看到空态之后会怎么操作（那是 UI 层）。
+#[test]
+fn a_category_that_hides_everything_is_the_empty_state() {
+    let state = state_with(vec![version("1.21.9", VersionKind::Release)]);
+    let ancient = Download::from_snapshot(
+        &state,
+        Category::Ancient,
+        &InstallDraft::default(),
+        Lang::En.catalog(),
+    );
+    assert!(ancient.rows.is_empty());
+    assert!(!ancient.is_loading(), "快照里有版本 ⇒ 不是加载中");
+    assert!(ancient.is_empty(), "筛掉所有行 ⇒ 空态");
+}
diff --git a/crates/app-iced/src/pages/download/options.rs b/crates/app-iced/src/pages/download/options.rs
new file mode 100644
index 0000000..27a8ed1
--- /dev/null
+++ b/crates/app-iced/src/pages/download/options.rs
@@ -0,0 +1,36 @@
+//! 安装选项区（M105）：**选中版本之后先给选项，点「安装」才开工**。
+//!
+//! ## 为什么要有这一步
+//!
+//! 用户实跑反馈的原话是「点击下载之后它就直接下载了，没有选择前置加载器(版本选择)选项」。
+//! 这不是画得不好，是**功能没做**：`Message::InstallVersion` 直接派 `InstallVersion`，
+//! 而 core 早就会装四家加载器（M32/M35/M45 已合）。于是「能装什么」与「UI 让你装什么」
+//! 之间差着一整个加载器维度。
+//!
+//! ## 文件分工
+//!
+//! | 文件 | 内容 |
+//! |---|---|
+//! | [`model`] | **决策**（无 iced）：加载器词表、兼容性静态规则、选项视图、确认键判据 |
+//! | [`view`] | 控件树：加载器 chip ×2 行 + 加载器版本列表 + 实例名 + 不兼容提示 |
+//! | `tests`（`options/tests.rs`） | 兼容性真值表 + 确认键门（纯函数，不开图形环境） |
+//!
+//! ## 一条纪律：页面只发意图
+//!
+//! | 控件 | 消息 | app 层落点 |
+//! |---|---|---|
+//! | 加载器 chip | [`Message::SetLoader`](super::Message::SetLoader) | 改草稿 + 按需派 `ListLoaderVersions` |
+//! | 加载器版本一行 | [`Message::SetLoaderVersion`](super::Message::SetLoaderVersion) | 改草稿 |
+//! | 实例名输入 | [`Message::SetInstanceName`](super::Message::SetInstanceName) | 改草稿 |
+//! | 「安装」 | [`Message::InstallVersion`](super::Message::InstallVersion) | `AppCommand::CreateInstance(草稿)` |
+//!
+//! 草稿（选中版本 + 三个选项）住在 `App`，由 `refresh_view` 带进页面模型——与分类筛选同一个做法，
+//! 因为 `refresh_view` 每次事件都会把整棵模型重建，页面自己存不住任何东西。
+
+mod model;
+#[cfg(test)]
+mod tests;
+mod view;
+
+pub use model::{InstallDraft, Loader, OptionsView};
+pub(crate) use view::section;
diff --git a/crates/app-iced/src/pages/download/options/model.rs b/crates/app-iced/src/pages/download/options/model.rs
new file mode 100644
index 0000000..3db89f3
--- /dev/null
+++ b/crates/app-iced/src/pages/download/options/model.rs
@@ -0,0 +1,286 @@
+//! 安装选项的**决策**（无 iced）：选哪个加载器、它配不配这个原版版本、确认键能不能按。
+//!
+//! ## 为什么选项要有自己的模型层
+//!
+//! M105 之前「点安装」直接开工，于是用户装不了带加载器的版本（core 早就会装四家加载器，
+//! 只是 UI 没接）。补上这一步之后，页面要回答的问题从一个变成四个：
+//!
+//! | 问题 | 判据 |
+//! |---|---|
+//! | 这个加载器配这个原版版本吗 | [`Loader::supports`]（静态规则，**不联网**） |
+//! | 加载器版本有哪些 | presenter 的 `LoaderVersions` 快照（`state.loader_versions_for`） |
+//! | 用哪个加载器版本 | 用户选的；没选就取列表里最新的一条（core 的 `resolve(kind, mc, None)` 也是这个口径） |
+//! | 现在能不能点「安装」 | [`OptionsView::can_confirm`]（不兼容 / 列表没到位 / 已装 都按不下去） |
+//!
+//! ## 兼容性为什么是静态规则而不是问网络
+//!
+//! 「选完才失败」是用户最讨厌的一种交互。凡是**官方根本没有**的组合（NeoForge × 1.12.2、
+//! 远古版 × 任何加载器），必须在选中那一刻就说清，不能等点了安装再回一个 404。
+//! 反过来说：**能**装但列表拉不到（网络问题）属于「取不到」，由 [`LoaderVersionsView::Failed`]
+//! 显示具名原因并禁掉确认——两条都不会让用户「选完才失败」。
+//!
+//! 规则来源（不猜：都是 core 安装管线自己的判据）：
+//! - Fabric/Quilt 的 loader 列表从 `1.14` 起才有（core 走 fabric meta，1.13 及以前没有）；
+//! - NeoForge 的第一个版本是 `1.20.1`（`maven::NEOFORGE_FORGE_LAYOUT_MC`）；
+//! - Forge 从 `1.1` 起有正式构建；远古版（`rd-*` / `a*` / `b*`）与预览版在 maven 表里没有条目。
+
+use unlucky_i18n::{Catalog, Key};
+use unlucky_presenter::dto::{LoaderKind, VersionKind};
+use unlucky_presenter::state::AppState;
+
+use super::super::model::VersionRow;
+
+/// 加载器版本下拉此刻的内容。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum LoaderVersionsView {
+    /// 还没查过 / 正在查（页面显示「正在获取…」，确认键按下不去）
+    Loading,
+    /// 查到了（**最新在前**，与 core 的 `loader_versions` 同序）
+    Ready(Vec<String>),
+    /// 查不到：人读原因（页面显示它并禁掉确认，不静默显示成空列表）
+    Failed(String),
+}
+
+/// 页面侧的加载器词表：只列 GUI 真能装的五家（与 `dto::LoaderKind::wizard_choices` 同集）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum Loader {
+    /// 原版（不装加载器）
+    #[default]
+    Vanilla,
+    /// Forge
+    Forge,
+    /// NeoForge
+    NeoForge,
+    /// Fabric
+    Fabric,
+    /// Quilt
+    Quilt,
+}
+
+impl Loader {
+    /// 展示顺序（任务书的口径：原版 / Forge / NeoForge / Fabric / Quilt）。
+    pub const ALL: [Loader; 5] = [
+        Loader::Vanilla,
+        Loader::Forge,
+        Loader::NeoForge,
+        Loader::Fabric,
+        Loader::Quilt,
+    ];
+
+    /// 对应的 presenter 词表（派 `AppCommand` 时用）。
+    pub const fn kind(self) -> LoaderKind {
+        match self {
+            Loader::Vanilla => LoaderKind::Vanilla,
+            Loader::Forge => LoaderKind::Forge,
+            Loader::NeoForge => LoaderKind::NeoForge,
+            Loader::Fabric => LoaderKind::Fabric,
+            Loader::Quilt => LoaderKind::Quilt,
+        }
+    }
+
+    /// 从 presenter 词表回来（`OptiFine` / `LiteLoader` 不是本页选项）。
+    pub const fn of(kind: LoaderKind) -> Option<Self> {
+        match kind {
+            LoaderKind::Vanilla => Some(Loader::Vanilla),
+            LoaderKind::Forge => Some(Loader::Forge),
+            LoaderKind::NeoForge => Some(Loader::NeoForge),
+            LoaderKind::Fabric => Some(Loader::Fabric),
+            LoaderKind::Quilt => Some(Loader::Quilt),
+            LoaderKind::OptiFine | LoaderKind::LiteLoader => None,
+        }
+    }
+
+    /// chip 文案。
+    ///
+    /// 四家加载器的名字是**专有名词**（Fabric/Forge/NeoForge/Quilt 官方各语言都写原样），
+    /// 所以只有「原版」走 i18n；硬给品牌名建一条 en==zh 的 key 会被
+    /// `catalog::tests::chinese_catalog_is_actually_chinese` 判为「未翻译」。
+    pub fn label(self, catalog: Catalog) -> &'static str {
+        match self {
+            Loader::Vanilla => catalog.text(Key::LoaderVanilla),
+            Loader::Forge => "Forge",
+            Loader::NeoForge => "NeoForge",
+            Loader::Fabric => "Fabric",
+            Loader::Quilt => "Quilt",
+        }
+    }
+
+    /// 这个加载器配不配这个原版版本（静态规则，见模块文档的判据表）。
+    ///
+    /// 参数是 `(版本 id, 版本类型)` 而不是一整行：app 层在**派查询之前**也要问同一个问题
+    /// （静态就不支持的组合不该去联网问，否则会白白换来一条「取不到」的 Toast）。
+    pub fn supports(self, id: &str, kind: VersionKind) -> Result<(), Incompat> {
+        if self == Loader::Vanilla {
+            return Ok(());
+        }
+        // 远古版：四家都没有构建（maven 表 / fabric meta 都没有这些版本）。
+        if kind.is_ancient() {
+            return Err(Incompat::Unsupported);
+        }
+        let rank = release_rank(id);
+        match self {
+            Loader::Vanilla => Ok(()),
+            // 预览版：Fabric 系的确会为快照发 loader，交给列表回答（拉不到就显示原因）；
+            // maven 系（Forge/NeoForge）没有快照条目，直接拒。
+            Loader::Fabric | Loader::Quilt => match rank {
+                Some(version) if version >= (1, 14, 0) => Ok(()),
+                Some(_) => Err(Incompat::NeedsAtLeast("1.14")),
+                None if kind == VersionKind::Snapshot => Ok(()),
+                None => Err(Incompat::Unsupported),
+            },
+            Loader::Forge => match rank {
+                Some(_) => Ok(()),
+                None => Err(Incompat::Unsupported),
+            },
+            Loader::NeoForge => match rank {
+                Some(version) if version >= (1, 20, 1) => Ok(()),
+                Some(_) => Err(Incompat::NeedsAtLeast("1.20.1")),
+                None => Err(Incompat::Unsupported),
+            },
+        }
+    }
+}
+
+/// 不支持的原因（两种，页面各一句文案）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Incompat {
+    /// 官方没有这个组合的构建
+    Unsupported,
+    /// 需要某个最低原版版本
+    NeedsAtLeast(&'static str),
+}
+
+/// `1.20.1` → `(1, 20, 1)`；预览版 / 远古版 / 乱七八糟的串 → `None`。
+///
+/// 只要有一段落不是纯数字就给 `None`：宁可保守地拒绝一个自定义版本号，也不把
+/// `1.20.1-pre3` 当成 `1.20.1` 放过去（那会装出加载器找不到父版本）。
+pub fn release_rank(id: &str) -> Option<(u64, u64, u64)> {
+    let mut pieces = id.trim().split('.');
+    let major: u64 = pieces.next()?.parse().ok()?;
+    let minor: u64 = pieces.next()?.parse().ok()?;
+    let patch: u64 = match pieces.next() {
+        Some(patch) => patch.parse().ok()?,
+        None => 0,
+    };
+    if pieces.next().is_some() {
+        return None;
+    }
+    Some((major, minor, patch))
+}
+
+/// 用户还没确认的安装输入（**app 持有**，不是 presenter 快照的一部分）。
+///
+/// 为什么住在 app 而不是 presenter：这是「用户正在填、还没提交」的草稿，
+/// 和下载页的分类筛选（`App::view.download.category` 的来源）是同一层的东西；
+/// 塞进 presenter 快照会让后端视图模型混进 UI 草稿。
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct InstallDraft {
+    /// 选中的版本 id（点行得到；点别的版本会清掉加载器版本，见 `app/update/download.rs`）
+    pub selected: Option<String>,
+    /// 选中的加载器
+    pub loader: Loader,
+    /// 用户指定的加载器版本（空 = 用列表里最新的那条）
+    pub loader_version: String,
+    /// 实例名（空 = 用版本 id）
+    pub instance_name: String,
+}
+
+/// 选项区要画的东西（文案都已按 `Catalog` 求好值）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct OptionsView {
+    /// 目标版本 id
+    pub version: String,
+    /// 当前选中的加载器
+    pub loader: Loader,
+    /// 加载器版本下拉的内容（原版恒为 [`LoaderVersionsView::Ready`] 空表）
+    pub versions: LoaderVersionsView,
+    /// **实际会用**的加载器版本（空 = 原版）
+    pub loader_version: String,
+    /// 实例名输入框的现值
+    pub instance_name: String,
+    /// 不兼容 / 取不到的原因（`Some` ⇒ 确认键按下不去）
+    pub problem: Option<String>,
+    /// 本地已装（确认键给「已安装」禁用态）
+    pub installed: bool,
+    /// 现在能不能点「安装」
+    pub can_confirm: bool,
+}
+
+impl OptionsView {
+    /// 选中行 + 快照 + 草稿 → 选项区的样子。
+    pub fn of(row: &VersionRow, state: &AppState, draft: &InstallDraft, catalog: Catalog) -> Self {
+        let loader = draft.loader;
+        let incompat = loader.supports(&row.id, row.kind);
+        // 静态就不支持的组合**不去查列表**（查了也只会换来一条「取不到」的假原因）：
+        // 空表 + 上面那条「没有适配构建」就是说清这件事的那一句话。
+        let versions = if loader == Loader::Vanilla || incompat.is_err() {
+            LoaderVersionsView::Ready(Vec::new())
+        } else {
+            match state.loader_versions_for(loader.kind(), &row.id) {
+                None => LoaderVersionsView::Loading,
+                Some(Ok(items)) => LoaderVersionsView::Ready(items.clone()),
+                Some(Err(reason)) => LoaderVersionsView::Failed(reason.clone()),
+            }
+        };
+        // 用户选过就用它；没选过取列表里最新的一条（core 的默认口径也是「最新」）。
+        let loader_version = if loader == Loader::Vanilla {
+            String::new()
+        } else if !draft.loader_version.trim().is_empty() {
+            draft.loader_version.clone()
+        } else {
+            match &versions {
+                LoaderVersionsView::Ready(items) => items.first().cloned().unwrap_or_default(),
+                _ => String::new(),
+            }
+        };
+
+        let problem = match (incompat, &versions) {
+            (Err(Incompat::Unsupported), _) => Some(catalog.render(
+                Key::DownloadOptionsIncompatible,
+                &[
+                    ("loader", loader.label(catalog)),
+                    ("version", row.id.as_str()),
+                ],
+            )),
+            (Err(Incompat::NeedsAtLeast(min)), _) => Some(catalog.render(
+                Key::DownloadOptionsNeedsAtLeast,
+                &[("loader", loader.label(catalog)), ("min", min)],
+            )),
+            (Ok(()), LoaderVersionsView::Failed(reason)) => Some(catalog.render(
+                Key::DownloadOptionsLoaderVersionsFailed,
+                &[("reason", reason.as_str())],
+            )),
+            (Ok(()), LoaderVersionsView::Ready(items))
+                if loader != Loader::Vanilla && items.is_empty() =>
+            {
+                Some(catalog.render(
+                    Key::DownloadOptionsLoaderVersionsEmpty,
+                    &[("version", row.id.as_str())],
+                ))
+            }
+            (Ok(()), _) => None,
+        };
+
+        // 四条同时成立才按得下去：不兼容没有、列表真的就位（原版不需要列表）、没装过。
+        // 「列表没到位」既包括 `Loading` 也包括 `Failed` 与空表——它们都已经在 `problem` 里说了原因。
+        let ready = loader == Loader::Vanilla
+            || matches!(&versions, LoaderVersionsView::Ready(items) if !items.is_empty());
+        let can_confirm = problem.is_none() && ready && !row.installed;
+
+        Self {
+            version: row.id.clone(),
+            loader,
+            versions,
+            loader_version,
+            instance_name: draft.instance_name.clone(),
+            problem,
+            installed: row.installed,
+            can_confirm,
+        }
+    }
+
+    /// 确认安装要提交的加载器版本（`None` = 让 core 用官方默认，只在原版路径出现）。
+    pub fn loader_version_arg(&self) -> Option<&str> {
+        (!self.loader_version.is_empty()).then_some(self.loader_version.as_str())
+    }
+}
diff --git a/crates/app-iced/src/pages/download/options/tests.rs b/crates/app-iced/src/pages/download/options/tests.rs
new file mode 100644
index 0000000..aa81251
--- /dev/null
+++ b/crates/app-iced/src/pages/download/options/tests.rs
@@ -0,0 +1,254 @@
+//! 安装选项的决策单测（M105）：兼容性真值表 + 确认键门 + 默认加载器版本。
+//!
+//! 全部是**纯函数**（`OptionsView::of` 吃 `AppState` 与 `VersionRow`，不碰 iced），
+//! 所以不开图形环境也能钉住「什么组合能装、什么组合按下不去」。
+//!
+//! **为什么用 `AppState` 而不是 mock 后端**：加载器版本列表是快照字段
+//! （`state.loader_versions`），灌一条 `CoreEvent::LoaderVersions` 就能造出三种状态
+//! （没查过 / 查到了 / 取不到），比 mock 更直接，也不依赖 `MockBackend` 的脚本。
+
+use unlucky_i18n::Lang;
+use unlucky_presenter::dto::{
+    AncientKind, AppEvent, CoreEvent, LoaderKind, VersionKind, VersionSummary,
+};
+use unlucky_presenter::state::AppState;
+
+use super::model::{release_rank, Incompat, InstallDraft, Loader, LoaderVersionsView, OptionsView};
+use crate::pages::download::model::VersionRow;
+
+fn row(id: &str, kind: VersionKind) -> VersionRow {
+    VersionRow::of(
+        &VersionSummary {
+            id: id.to_string(),
+            kind,
+            released: "2026-09-20".to_string(),
+            installed: false,
+        },
+        Lang::En.catalog(),
+    )
+}
+
+fn state_with(kind: LoaderKind, mc: &str, items: Result<Vec<&str>, &str>) -> AppState {
+    let mut state = AppState::new();
+    state.apply(AppEvent::Core(CoreEvent::LoaderVersions {
+        kind,
+        mc_version: mc.to_string(),
+        result: items
+            .map(|list| {
+                list.into_iter()
+                    .map(str::to_string)
+                    .collect::<Vec<String>>()
+            })
+            .map_err(str::to_string),
+    }));
+    state
+}
+
+fn draft(loader: Loader) -> InstallDraft {
+    InstallDraft {
+        selected: Some("1.20.1".to_string()),
+        loader,
+        loader_version: String::new(),
+        instance_name: String::new(),
+    }
+}
+
+/// 版本号解析：只有纯数字三段（或缺末段）才算正式版。
+#[test]
+fn release_rank_only_accepts_plain_release_ids() {
+    assert_eq!(release_rank("1.20.1"), Some((1, 20, 1)));
+    assert_eq!(release_rank("1.20"), Some((1, 20, 0)), "缺末段按 0 算");
+    assert_eq!(release_rank("24w14a"), None, "快照不是正式版号");
+    assert_eq!(release_rank("rd-132211"), None);
+    assert_eq!(
+        release_rank("1.20.1-pre3"),
+        None,
+        "预发布不许当正式版放过去"
+    );
+    assert_eq!(release_rank("1.20.1.2"), None, "多一段不认");
+}
+
+/// 兼容性真值表（任务书点名的「老版本 × NeoForge」在这条里）。
+#[test]
+fn loader_support_matrix_is_explicit() {
+    // 原版永远可以
+    for id in ["1.21.9", "1.12.2", "rd-132211"] {
+        let kind = if id.starts_with("rd") {
+            VersionKind::Ancient(AncientKind::Classic)
+        } else {
+            VersionKind::Release
+        };
+        assert_eq!(Loader::Vanilla.supports(id, kind), Ok(()));
+    }
+    // NeoForge 要 1.20.1+
+    assert_eq!(
+        Loader::NeoForge.supports("1.20.1", VersionKind::Release),
+        Ok(())
+    );
+    assert_eq!(
+        Loader::NeoForge.supports("1.12.2", VersionKind::Release),
+        Err(Incompat::NeedsAtLeast("1.20.1")),
+        "老版本 × NeoForge 必须在选中那一刻就说清，而不是点安装才失败"
+    );
+    // Fabric/Quilt 要 1.14+
+    assert_eq!(
+        Loader::Fabric.supports("1.20.1", VersionKind::Release),
+        Ok(())
+    );
+    assert_eq!(
+        Loader::Fabric.supports("1.12.2", VersionKind::Release),
+        Err(Incompat::NeedsAtLeast("1.14"))
+    );
+    // Forge 任何正式版都行，但预览版/远古版没有 maven 条目
+    assert_eq!(
+        Loader::Forge.supports("1.12.2", VersionKind::Release),
+        Ok(())
+    );
+    assert_eq!(
+        Loader::Forge.supports("24w14a", VersionKind::Snapshot),
+        Err(Incompat::Unsupported)
+    );
+    // 远古版：四家全都不支持
+    let ancient = ("a1.2.6", VersionKind::Ancient(AncientKind::OldAlpha));
+    for loader in [
+        Loader::Fabric,
+        Loader::Quilt,
+        Loader::Forge,
+        Loader::NeoForge,
+    ] {
+        assert_eq!(
+            loader.supports(ancient.0, ancient.1),
+            Err(Incompat::Unsupported)
+        );
+    }
+}
+
+/// 不兼容的组合：给具名提示，并且**确认键按下不去**。
+#[test]
+fn incompatible_combination_disables_confirm_with_a_named_reason() {
+    let state = AppState::new();
+    let options = OptionsView::of(
+        &row("1.12.2", VersionKind::Release),
+        &state,
+        &draft(Loader::NeoForge),
+        Lang::En.catalog(),
+    );
+    assert!(!options.can_confirm, "不兼容就不许按下确认");
+    let problem = options.problem.expect("要给出具名原因");
+    assert!(problem.contains("NeoForge"), "{problem}");
+    assert!(problem.contains("1.20.1"), "{problem}");
+}
+
+/// 默认加载器版本 = 列表里最新的一条（core 的默认口径）；用户选过就用用户的。
+#[test]
+fn loader_version_defaults_to_the_newest_and_honours_the_choice() {
+    let state = state_with(LoaderKind::Fabric, "1.20.1", Ok(vec!["0.16.5", "0.16.4"]));
+    let options = OptionsView::of(
+        &row("1.20.1", VersionKind::Release),
+        &state,
+        &draft(Loader::Fabric),
+        Lang::En.catalog(),
+    );
+    assert!(options.can_confirm);
+    assert_eq!(options.loader_version, "0.16.5", "没选过就用最新");
+    assert_eq!(options.loader_version_arg(), Some("0.16.5"));
+
+    let mut chosen = draft(Loader::Fabric);
+    chosen.loader_version = "0.16.4".to_string();
+    let options = OptionsView::of(
+        &row("1.20.1", VersionKind::Release),
+        &state,
+        &chosen,
+        Lang::En.catalog(),
+    );
+    assert_eq!(options.loader_version, "0.16.4", "用户选的就是用户选的");
+}
+
+/// 三条「列表还没到位」的状态都不许按下确认，且各自说清是哪种。
+#[test]
+fn versions_pending_or_failed_blocks_confirm() {
+    let bare = AppState::new();
+    let loading = OptionsView::of(
+        &row("1.20.1", VersionKind::Release),
+        &bare,
+        &draft(Loader::Fabric),
+        Lang::En.catalog(),
+    );
+    assert_eq!(loading.versions, LoaderVersionsView::Loading);
+    assert!(!loading.can_confirm, "还没查过就不许装");
+
+    let failed = state_with(LoaderKind::Fabric, "1.20.1", Err("network down"));
+    let options = OptionsView::of(
+        &row("1.20.1", VersionKind::Release),
+        &failed,
+        &draft(Loader::Fabric),
+        Lang::En.catalog(),
+    );
+    assert!(!options.can_confirm);
+    assert!(
+        options
+            .problem
+            .as_deref()
+            .is_some_and(|p| p.contains("network down")),
+        "取不到要给具名原因（不是空下拉）"
+    );
+
+    let empty = state_with(LoaderKind::Fabric, "1.20.1", Ok(vec![]));
+    let options = OptionsView::of(
+        &row("1.20.1", VersionKind::Release),
+        &empty,
+        &draft(Loader::Fabric),
+        Lang::En.catalog(),
+    );
+    assert!(!options.can_confirm, "官方没有版本就不许装");
+    assert!(options.problem.is_some());
+}
+
+/// 缓存键带原版版本：A 版本的列表不会挂到 B 版本下面。
+#[test]
+fn cached_versions_are_keyed_by_minecraft_version() {
+    let state = state_with(LoaderKind::Fabric, "1.20.1", Ok(vec!["0.16.5"]));
+    let other = OptionsView::of(
+        &row("1.21.9", VersionKind::Release),
+        &state,
+        &draft(Loader::Fabric),
+        Lang::En.catalog(),
+    );
+    assert_eq!(
+        other.versions,
+        LoaderVersionsView::Loading,
+        "换原版版本就得重新查，不许复用上一版的结果"
+    );
+}
+
+/// 原版：不查列表、不需要加载器版本，确认键直接可用。
+#[test]
+fn vanilla_needs_no_loader_version_at_all() {
+    let state = AppState::new();
+    let options = OptionsView::of(
+        &row("1.20.1", VersionKind::Release),
+        &state,
+        &draft(Loader::Vanilla),
+        Lang::En.catalog(),
+    );
+    assert!(options.can_confirm);
+    assert_eq!(options.versions, LoaderVersionsView::Ready(Vec::new()));
+    assert_eq!(options.loader_version, "");
+    assert_eq!(options.loader_version_arg(), None);
+}
+
+/// 已装的版本：确认键给「已安装」禁用态（列表行上也有勾，按钮再点一次不会更清楚）。
+#[test]
+fn installed_versions_cannot_be_confirmed_again() {
+    let state = AppState::new();
+    let mut installed = row("1.20.1", VersionKind::Release);
+    installed.installed = true;
+    let options = OptionsView::of(
+        &installed,
+        &state,
+        &draft(Loader::Vanilla),
+        Lang::En.catalog(),
+    );
+    assert!(options.installed);
+    assert!(!options.can_confirm);
+}
diff --git a/crates/app-iced/src/pages/download/options/view.rs b/crates/app-iced/src/pages/download/options/view.rs
new file mode 100644
index 0000000..54fb428
--- /dev/null
+++ b/crates/app-iced/src/pages/download/options/view.rs
@@ -0,0 +1,213 @@
+//! 选项区的控件树（M105）。
+//!
+//! ## 版面（424 正文列里的四段）
+//!
+//! ```text
+//! 1.21.9                                          [安装]
+//! 安装选项
+//! [原版][Forge][NeoForge]
+//! [Fabric][Quilt]
+//! 加载器版本            ← 只在选了加载器时出现
+//! ┌ 0.16.5            ┐  ← 官方那份列表（menu + 滚动，最多看两行）
+//! │ 0.16.4            │
+//! └───────────────────┘
+//! [实例名                ]
+//! NeoForge 需要 Minecraft 1.20.1 或更新      ← 不兼容时（Error 色）
+//! ```
+//!
+//! ## 为什么加载器分成两行
+//!
+//! 五家一起排在 424 宽里最宽的那组（`原版 + Forge + NeoForge + Fabric + Quilt`）实测会溢出，
+//! 而 chip 的几何是组件自己的真源（`ChipGeometry`），页面不许压它 ⇒ 折成两行。
+//! 顺序仍是任务书的口径（原版 / Forge / NeoForge / Fabric / Quilt），只是换行。
+//!
+//! ## 为什么「不兼容」不禁用 chip、而是禁用确认键
+//!
+//! 禁用的 chip 点不动，用户就**看不到原因**（那正是「选完才失败」的另一种形态）。
+//! 现在的做法：五家永远都能点，选中不兼容的那家时下面出现一行具名原因，同时「安装」变成禁用态。
+//! 于是「为什么不能装」和「怎么才能装」永远同屏。
+
+use iced::widget::{column, container, row, scrollable};
+use iced::{Alignment, Element, Length};
+
+use unlucky_design::color::Role;
+use unlucky_design::icons::IconKind;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use unlucky_i18n::{Catalog, Key};
+
+use crate::app::components::buttons::{self, Button};
+use crate::app::components::inputs::{menu, Menu, MenuItem};
+use crate::app::components::inputs::{text_field, Field, FieldVariant};
+use crate::app::components::selection::{chip, Chip};
+use crate::theme::Ui;
+
+use super::super::frame;
+use super::super::Message;
+use super::model::{Loader, LoaderVersionsView, OptionsView};
+
+/// 五家加载器（一行放得下：实测五枚 chip 合计约 311 dp，正文列 424）。
+const LOADERS: [Loader; 5] = [
+    Loader::Vanilla,
+    Loader::Forge,
+    Loader::NeoForge,
+    Loader::Fabric,
+    Loader::Quilt,
+];
+
+/// 菜单项高度 = 48（`MenuGeometry` 的项高）×2 行 + 上下留白 8×2 = 112。
+/// 这么算是为了避免「列表被截掉半行」——滚动区高度必须覆盖整行。
+const VERSION_ROWS: f32 = 7.0;
+
+/// 选项区（面板的下半块）。
+pub(crate) fn section<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    options: &'a OptionsView,
+) -> Element<'a, Message> {
+    let head = row![
+        container(frame::text_role(
+            ui,
+            TypeRole::BodyMedium,
+            false,
+            options.version.as_str(),
+            ui.color(Role::OnSurface),
+        ))
+        .width(Length::Fill),
+        confirm(ui, catalog, options),
+    ]
+    .width(Length::Fill)
+    .align_y(Alignment::Center);
+
+    let mut body = column![
+        head,
+        frame::text_role(
+            ui,
+            TypeRole::LabelMedium,
+            false,
+            catalog.text(Key::DownloadOptionsTitle),
+            ui.color(Role::OnSurfaceVariant),
+        ),
+        loader_row(ui, catalog, options),
+    ]
+    .spacing(ui.space(Space::X2))
+    .width(Length::Fill);
+
+    // 「加载器版本」这一段只在**真该有列表**时出现：原版没有、静态不兼容没有（原因在下面那行）、
+    // 取不到也没有（同样在原因行）。留一个空标题只会让人以为界面缺了一块。
+    if show_versions(options) {
+        body = body.push(frame::text_role(
+            ui,
+            TypeRole::LabelMedium,
+            false,
+            catalog.text(Key::DownloadOptionsLoaderVersion),
+            ui.color(Role::OnSurfaceVariant),
+        ));
+        body = body.push(version_list(ui, catalog, options));
+    }
+
+    body = body.push(text_field(
+        ui,
+        Field::new(options.instance_name.as_str())
+            .variant(FieldVariant::Outlined)
+            .label(catalog.text(Key::DownloadOptionsInstanceName))
+            .placeholder(catalog.text(Key::DownloadOptionsInstanceNameHint)),
+        Message::SetInstanceName,
+    ));
+
+    if let Some(problem) = &options.problem {
+        body = body.push(frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            problem.as_str(),
+            ui.color(Role::Error),
+        ));
+    }
+
+    body.into()
+}
+
+/// 加载器版本这一段要不要画（见 `section` 的注释）。
+fn show_versions(options: &OptionsView) -> bool {
+    if options.loader == Loader::Vanilla || options.problem.is_some() {
+        return false;
+    }
+    match &options.versions {
+        LoaderVersionsView::Loading => true,
+        LoaderVersionsView::Ready(items) => !items.is_empty(),
+        LoaderVersionsView::Failed(_) => false,
+    }
+}
+
+/// 一行加载器 chip（Filter 档：选中 = `SecondaryContainer`）。
+fn loader_row<'a>(ui: &'a Ui, catalog: Catalog, options: &'a OptionsView) -> Element<'a, Message> {
+    let mut line = row![]
+        .spacing(ui.space(Space::X1))
+        .align_y(Alignment::Center);
+    for loader in LOADERS.iter() {
+        line = line.push(chip(
+            ui,
+            Chip::filter(
+                loader.label(catalog),
+                options.loader == *loader,
+                Message::SetLoader(*loader),
+            ),
+        ));
+    }
+    line.into()
+}
+
+/// 官方那份加载器版本列表（`menu` + 滚动：Fabric 有上百条，不做下拉也不铺满屏）。
+fn version_list<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    options: &'a OptionsView,
+) -> Element<'a, Message> {
+    match &options.versions {
+        LoaderVersionsView::Loading => frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            catalog.text(Key::DownloadOptionsLoaderVersionsLoading),
+            ui.color(Role::OnSurfaceVariant),
+        ),
+        // 取不到 / 一条都没有：原因已经在上面那行 `problem` 里说清，这里不再重复。
+        LoaderVersionsView::Failed(_) => frame::gap(0.0),
+        LoaderVersionsView::Ready(items) if items.is_empty() => frame::gap(0.0),
+        LoaderVersionsView::Ready(items) => {
+            let mut list = Menu::new().width(Length::Fill);
+            for item in items {
+                let mut entry =
+                    MenuItem::new(item.as_str(), Message::SetLoaderVersion(item.clone()));
+                if *item == options.loader_version {
+                    entry = entry.selected();
+                }
+                list = list.item(entry);
+            }
+            scrollable(menu(ui, list))
+                .height(Length::Fixed(ui.space(Space::X4) * VERSION_ROWS))
+                .style(frame::scroll_style(ui))
+                .into()
+        }
+    }
+}
+
+/// 「安装」：不兼容 / 列表没到位 / 已装 都按下不去（禁用态保留几何，只清消息）。
+fn confirm<'a>(ui: &'a Ui, catalog: Catalog, options: &'a OptionsView) -> Element<'a, Message> {
+    if options.installed {
+        return buttons::outlined(ui, Button::disabled(catalog.text(Key::DownloadInstalled)));
+    }
+    if !options.can_confirm {
+        return buttons::outlined(ui, Button::disabled(catalog.text(Key::DownloadInstall)));
+    }
+    buttons::filled(
+        ui,
+        Button::new(
+            catalog.text(Key::DownloadInstall),
+            Message::InstallVersion(options.version.clone()),
+        )
+        .leading(IconKind::Download),
+    )
+}
diff --git a/crates/app-iced/src/pages/download/rails.rs b/crates/app-iced/src/pages/download/rails.rs
new file mode 100644
index 0000000..0aa3b8d
--- /dev/null
+++ b/crates/app-iced/src/pages/download/rails.rs
@@ -0,0 +1,375 @@
+//! 版本管理页的**三栏装配**：类型栏 + 主版本栏 + 列表列（宽档不够时退回顶部 chips）。
+//!
+//! ## 三栏各自的内容
+//!
+//! | 栏 | 画什么 | 交互 |
+//! |---|---|---|
+//! | 版本类型（第一栏） | 折叠开关 + 四个类型项（原顶部 tabs 的四个 chip，语义一字不改） | [`Message::SetCategory`]（真指令：`AppCommand::ListVersions`） |
+//! | 主版本（第二栏） | 「全部版本」+ 快照里出现的每个主版本桶（[`super::group`]） | [`Message::SelectMajor`]（纯视图态） |
+//! | 列表 / 内容（第三栏） | 搜索条 + 命中数 + 计数头 + 版本行 + 底部安装面板 | [`Message::SetVersionQuery`] / 选版本 / 安装 |
+//!
+//! ## 宽度不在这里拍
+//!
+//! 两条栏的宽度来自 [`VersionRails`]（宽档裁决，见 `pages/layout/rails.rs` 的数值表）。
+//! 本文件只做两件事：把裁决出来的数字用上、把「用户手动折叠类型栏」这条覆盖叠上去。
+//!
+//! ## 为什么搜索条在第三栏而不是横跨三栏
+//!
+//! 搜索过滤的对象是**第三栏的列表**；横跨三栏会让人以为它也在搜侧栏里的类型。放进列表列顶部，
+//! 「输入 → 下面的行变少」这条因果在视觉上就是同一条竖线；命中数是这条因果的读数，紧贴右侧。
+//!
+//! ## 键盘可达
+//!
+//! 两层侧栏的每一项都是真组件按钮（`navigation::list_item` / `navigation::tabs` /
+//! `buttons::icon`）：焦点由 iced 的焦点系统给，Tab 依次走「类型栏 → 主版本栏 → 搜索框 → 版本行 →
+//! 安装」，Enter 激活。页面不自己写焦点环（那是组件的状态层）。
+
+use iced::widget::tooltip::Position;
+use iced::widget::{column, container, row, scrollable, tooltip};
+use iced::{Alignment, Element, Length, Padding};
+
+use unlucky_design::color::Role;
+use unlucky_design::elevation::MaterialLayer;
+use unlucky_design::icons::IconKind;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use unlucky_i18n::{Catalog, Key};
+
+use crate::app::components::buttons::{self, IconVariant};
+use crate::app::components::navigation::list_item::{list_item, ListItem};
+use crate::app::components::navigation::tabs::{tabs, Tab, Tabs};
+use crate::app::components::selection::{chip, Chip};
+use crate::theme::Ui;
+
+use super::super::frame;
+use super::super::layout::{VersionRails, RAIL_ICON_WIDTH};
+use super::super::Message;
+use super::model::{Category, Download};
+use super::{group, rows};
+
+/// 类型栏里一项的图标。
+///
+/// 图标语汇只有 28 个描边字形（没有 `History` / `Camera`），所以借用：
+/// **全部 = 网格、正式版 = 勾、预览版 = 刷新、远古版 = 档案袋**。已登记为偏离。
+pub(super) const fn category_icon(category: Category) -> IconKind {
+    match category {
+        Category::All => IconKind::Instances,
+        Category::Release => IconKind::Check,
+        Category::Snapshot => IconKind::Refresh,
+        Category::Ancient => IconKind::Folder,
+    }
+}
+
+/// 三栏装配（`Wide` / `Narrow` / `Compact` 三档共用）。
+pub(super) fn three_column<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    model: &'a Download,
+    rails: VersionRails,
+) -> Element<'a, Message> {
+    row![
+        panel(
+            ui,
+            rails.type_rail,
+            type_rail(ui, catalog, model, rails.type_rail)
+        ),
+        panel(
+            ui,
+            rails.major_rail,
+            major_rail(ui, catalog, model, rails.major_rail)
+        ),
+        container(rows::content(ui, catalog, model))
+            .width(Length::Fixed(rails.list))
+            .height(Length::Fill),
+    ]
+    .spacing(super::super::layout::rails::RAIL_GAP)
+    .width(Length::Fill)
+    .height(Length::Fill)
+    .into()
+}
+
+/// 一条侧栏的外壳：固定宽 + 面板底色 + 独立滚动（栏内内容不横向挤）。
+fn panel<'a>(
+    ui: &'a Ui,
+    width: f32,
+    content: impl Into<Element<'a, Message>>,
+) -> Element<'a, Message> {
+    container(scrollable(content).height(Length::Fill).style(frame::scroll_style(ui)))
+        .width(Length::Fixed(width))
+        .height(Length::Fill)
+        // 水平不留内边距：140 宽里 `ListItem` 自己的 16+16 已经够，再多 8 会把 `Snapshot` 切掉
+        // （首轮出图实测「Snapsh」）。垂直留 8 让第一项不贴顶。
+        //
+        // 底色取 `Card` 层（`SurfaceContainerLow`，比页面 Canvas 高一档）：首轮出图用的是 Canvas，
+        // 两条栏和页面底色一模一样 ⇒ 读起来像「一堆文字浮在左边」，不像两条侧栏。
+        .padding(Padding::from([ui.space(Space::X2), 0.0]))
+        .style(move |_theme| frame::filled(ui.layer(MaterialLayer::Card)))
+        .into()
+}
+
+/// 第一栏：版本类型（`140` 展开 / `64` 图标条）。
+fn type_rail<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    model: &'a Download,
+    width: f32,
+) -> Element<'a, Message> {
+    // 宽度 ≤ 图标条宽 ⇒ 只画图标。用户手动折叠与窄档折叠走同一条判据（不另设开关）。
+    let icon_only = width <= RAIL_ICON_WIDTH;
+
+    let mut body = column![].spacing(ui.space(Space::X1)).width(Length::Fill);
+    let fold = fold_action(ui, model, icon_only);
+    if icon_only {
+        body = body.push(
+            container(fold)
+                .width(Length::Fill)
+                .align_x(Alignment::Center),
+        );
+    } else {
+        body = body.push(rail_title(ui, catalog.text(Key::VersionRailTitle), fold));
+    }
+
+    for category in Category::ALL {
+        let selected = category == model.category;
+        let label = catalog.text(category.label_key());
+        let press = Message::SetCategory(category);
+
+        body = body.push(if icon_only {
+            // 图标条：40×40 图标按钮（命中区 48 由栏内留白补足），选中 = `Tonal`。
+            // 64 宽放不下标签，所以每一项都挂 tooltip（复审建议）：四个图标既不说话也没有标题时，
+            // 用户只能靠猜。tooltip 的容器色/圆角走令牌，不新造样式。
+            container(labeled(ui, label, category_icon(category), selected, press))
+                .width(Length::Fill)
+                .align_x(Alignment::Center)
+                .into()
+        } else {
+            let mut item = ListItem::new(label, press).leading(category_icon(category));
+            if selected {
+                item = item.selected();
+            }
+            list_item(ui, item)
+        });
+    }
+
+    body.into()
+}
+
+/// 带 tooltip 的图标项（图标条用）。tooltip 位置在右侧——它是竖栏，右边就是内容区，
+/// 弹在下面会盖住下一项。
+fn labeled<'a>(
+    ui: &'a Ui,
+    label: &'a str,
+    kind: IconKind,
+    selected: bool,
+    press: Message,
+) -> Element<'a, Message> {
+    let button = buttons::icon(ui, select_variant(selected), kind, Some(press), None);
+    tooltip(
+        button,
+        container(frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            label,
+            ui.color(Role::OnSurface),
+        ))
+        .padding(ui.space(Space::X2))
+        .style(move |_theme| frame::filled(ui.layer(MaterialLayer::Overlay))),
+        Position::Right,
+    )
+    .into()
+}
+
+/// 选中态 → 图标按钮的三式（`Tonal` = 当前项，与 ListItem 的 `SecondaryContainer` 同色系）。
+fn select_variant(selected: bool) -> IconVariant {
+    if selected {
+        IconVariant::Tonal
+    } else {
+        IconVariant::Standard
+    }
+}
+
+/// 折叠 / 展开类型栏的图标按钮（`Sidebar` 字形；折叠中 = `Tonal`）。
+fn fold_action<'a>(ui: &'a Ui, model: &Download, icon_only: bool) -> Element<'a, Message> {
+    // 已经被宽度压成图标条时不再给开关：那时点它也不会变宽（档位说了算），
+    // 一个按了没反应的按钮正是 D30 判 p1 的那种假控件。
+    if icon_only && !model.type_rail_folded {
+        return frame::gap(ui.metrics().nav_item_gap);
+    }
+    buttons::icon(
+        ui,
+        select_variant(model.type_rail_folded),
+        IconKind::Sidebar,
+        Some(Message::ToggleTypeRail),
+        None,
+    )
+}
+
+/// 栏标题（`LabelMedium` + `OnSurfaceVariant`，与列表计数头同一档字级）。
+///
+/// 高度固定成 `control_height`（40 = 图标按钮的边长）：两条栏的标题必须**横向对齐**，
+/// 而第一栏标题右侧有个 40 高的折叠按钮、第二栏没有。不固定高度的话两行标题会差 12px。
+fn rail_title<'a>(
+    ui: &'a Ui,
+    title: &'a str,
+    action: Element<'a, Message>,
+) -> Element<'a, Message> {
+    container(
+        row![
+            container(frame::text_role(
+                ui,
+                TypeRole::LabelMedium,
+                false,
+                title,
+                ui.color(Role::OnSurfaceVariant),
+            ))
+            .width(Length::Fill),
+            action,
+        ]
+        .width(Length::Fill)
+        .align_y(Alignment::Center)
+        .padding(Padding::from([0.0, ui.space(Space::X2)])),
+    )
+    .height(Length::Fixed(ui.metrics().control_height))
+    .align_y(Alignment::Center)
+    .into()
+}
+
+/// 第二栏：主版本桶（第一项永远是「全部版本」；没有主版本概念的版本不单独占一项）。
+fn major_rail<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    model: &'a Download,
+    width: f32,
+) -> Element<'a, Message> {
+    let icon_only = width <= RAIL_ICON_WIDTH;
+
+    let mut body = column![].spacing(ui.space(Space::X1)).width(Length::Fill);
+    if !icon_only {
+        body = body.push(rail_title(
+            ui,
+            catalog.text(Key::VersionMajorTitle),
+            frame::gap(ui.metrics().nav_item_gap),
+        ));
+    }
+
+    for entry in major_entries(catalog, model) {
+        body = body.push(major_item(ui, entry.label, entry.key, entry.selected));
+    }
+
+    body.into()
+}
+
+/// 第二级侧栏的一项（「全部版本」与每个主版本桶共用一套结构，好让**两条渲染路径**
+/// ——竖栏与 chips 行 —— 都用同一份数据，测试也只钉这一份）。
+///
+/// 字段全部**借**模型里的桶标签与目录里的静态串：这两条渲染路径都要把标签塞进 iced 控件树，
+/// 借本地的 `String` 会让整棵树的生命周期塌到函数作用域里（E0515）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(super) struct MajorEntry<'a> {
+    /// 选中它要发的键（`None` = 「全部版本」）
+    pub key: Option<&'a str>,
+    /// 画出来的标签
+    pub label: &'a str,
+    /// 此刻是否选中（**按生效值算**：搜索期间恒为「全部」，见 `group::bucket_selected`）
+    pub selected: bool,
+}
+
+/// 第二级侧栏要画的全部项：`[全部版本, 1.21, 1.20, …]`，顺序 = 桶的版本序。
+///
+/// 抽成纯函数是为了让「最后一个桶可点」这件事**可断言**（复审 P2-2 的要求）：
+/// 竖栏与 chips 行都从这一份数据画，chips 行外面还套了横向滚动，所以「画得出来」= 「够得着」。
+/// 返回 `Vec` 而不是迭代器：调用方两处都要 len（chips 的宽度预算）与随机访问。
+pub(super) fn major_entries<'a>(catalog: Catalog, model: &'a Download) -> Vec<MajorEntry<'a>> {
+    let mut entries = vec![MajorEntry {
+        key: None,
+        label: catalog.text(Key::VersionMajorAll),
+        selected: group::bucket_selected(model, None),
+    }];
+
+    for bucket in &model.buckets {
+        // `None` 桶 = 远古版那类没有主版本的版本：第二级只有一个「全部」，不画空桶
+        let Some(key) = bucket.key.as_deref() else {
+            continue;
+        };
+        entries.push(MajorEntry {
+            key: Some(key),
+            label: key,
+            selected: group::bucket_selected(model, Some(key)),
+        });
+    }
+
+    entries
+}
+
+/// 主版本的一项：`ListItem` 单行（64 宽里 `1.21` 仍完整——`BodyLarge` 4 字符 ≈ 32px ≤ 64−32 内边距）。
+fn major_item<'a>(
+    ui: &'a Ui,
+    label: &'a str,
+    key: Option<&str>,
+    selected: bool,
+) -> Element<'a, Message> {
+    let mut item = ListItem::new(label, Message::SelectMajor(key.map(str::to_string)));
+    if selected {
+        item = item.selected();
+    }
+    list_item(ui, item)
+}
+
+/// 顶部 chips（可用宽 < 600 时三栏不成立：类型退回 Primary tabs，主版本变成 Secondary chips 行）。
+///
+/// 与三栏档**同源**：同一批 [`Category`] / 同一批主版本桶 / 同两条消息，不是另造一套筛选状态。
+pub(super) fn stacked_chips<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    model: &'a Download,
+) -> Element<'a, Message> {
+    let mut types = Tabs::primary();
+    for category in Category::ALL {
+        let mut tab = Tab::new(
+            catalog.text(category.label_key()),
+            Message::SetCategory(category),
+        );
+        if category == model.category {
+            tab = tab.selected();
+        }
+        types = types.tab(tab);
+    }
+
+    // 主版本 chips：**从同一份 `major_entries` 画**，并且整行套横向滚动（复审 P2-2）。
+    //
+    // 为什么必须能滚：真实清单里 `Release` 就有 ~20 个桶（1.21…1.7），chips 档的可用宽不到 600、
+    // 一行只放得下 5~6 个。没有横向滚动时后面的桶**永远点不到**——而这正是「主版本下拉」要解决的
+    // 那件事（设计系统里没有 dropdown 组件，所以用可横向滚动的 chips 行承担同一职责）。
+    let mut majors = row![]
+        .spacing(ui.space(Space::X2))
+        .align_y(Alignment::Center);
+    for entry in major_entries(catalog, model) {
+        majors = majors.push(chip(
+            ui,
+            Chip::filter(
+                entry.label,
+                entry.selected,
+                Message::SelectMajor(entry.key.map(str::to_string)),
+            ),
+        ));
+    }
+
+    let strip = scrollable(majors)
+        .direction(scrollable::Direction::Horizontal(
+            scrollable::Scrollbar::new()
+                .width(frame::SCROLLBAR_WIDTH)
+                .scroller_width(frame::SCROLLBAR_WIDTH)
+                .margin(frame::SCROLLBAR_MARGIN),
+        ))
+        .height(Length::Fixed(
+            ui.metrics().control_height + ui.space(Space::X2),
+        ))
+        .style(frame::scroll_style(ui));
+
+    column![tabs(ui, types), strip]
+        .spacing(ui.space(Space::X2))
+        .width(Length::Fill)
+        .into()
+}
diff --git a/crates/app-iced/src/pages/download/rows.rs b/crates/app-iced/src/pages/download/rows.rs
new file mode 100644
index 0000000..31f6bc2
--- /dev/null
+++ b/crates/app-iced/src/pages/download/rows.rs
@@ -0,0 +1,291 @@
+//! 列表列：搜索条 + 计数头 + **单行**版本行 + 底部安装面板。
+//!
+//! ## 这一列的职责边界
+//!
+//! | 位置 | 画什么 | 消息 |
+//! |---|---|---|
+//! | 搜索条 | 真实控件的 `search_bar`（56 高、药丸）+ 清空按钮 + 命中数 | [`Message::SetVersionQuery`] / [`Message::ClearVersionQuery`] |
+//! | 计数头 | `{count} versions`（`LabelMedium` + `OnSurfaceVariant`，与实例页列表头同一个语言） | 无 |
+//! | 列表 | `ListItem` + 三列短文本 + 尾随图标按钮 | [`Message::SelectVersion`] / [`Message::InstallVersion`] |
+//! | 面板 | 见 [`super::install`]（M105 的安装选项区**不在这里**） | — |
+//!
+//! ## 版本行为什么必须是**单行**
+//!
+//! 任务硬约束：列表列最窄 424（行宽下限），此时「版本号 + 类型 + 日期 + 安装按钮」四样仍要在
+//! 一行里。所以：版本号那一格是 `ListItem`（它自己的 `Wrapping::None` 保证不折行，超长由外层
+//! clip 切掉），类型 / 日期 / 安装按钮三格是**定宽**（[`super::super::layout::rails`] 的音阶）。
+//! 折行的唯一可能来源是定宽格子挤爆容器——那条由列表列下限 424 挡住（`layout/rails/tests.rs`
+//! 的扫描断言）。
+//!
+//! ## 搜索的三条口径
+//!
+//! | 情形 | 画什么 | 为什么 |
+//! |---|---|---|
+//! | 有命中 | 列表照常，侧栏**位置不动**，搜索条右侧显示「N 个匹配」 | 命中数是「我搜的词有货」的读数，不是分页读数 |
+//! | 一个都不命中（跨类型也没有） | [`super::states::no_match`]：一句「没有匹配」+ 一句「换短一点的片段」 | 白屏会让人以为列表坏了 |
+//! | 有命中但都不在当前类型 | [`super::states::elsewhere`]：说清「有 N 个在别的类型里」+ 一个「看全部类型」按钮 | 否则用户会以为自己搜错了 |
+//!
+//! ## 行距归零（M102，与本页的单行版本行同时成立）
+//!
+//! M102 把列表行距归零：原先页面在 `ListItem` 的可视高度之外又加了 `Space::X1`（4），行节奏
+//! 与可视高度除不尽，实例页复现成「末行被卡片底边切半行」（视觉复审 ②）。规则：行距只由
+//! 组件自己的几何决定，`Space` 里也没有 0 这一档 ⇒ `list()` 里**不写** `.spacing(…)`。
+//! 本页的行是 44 的单行档，同样不加行距；[`ROW_GAP`] 只用在**行内**那三个格子的间距上。
+
+use iced::widget::{column, container, row, scrollable};
+use iced::{Alignment, Element, Length, Padding};
+
+use unlucky_design::color::Role;
+use unlucky_design::icons::IconKind;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use unlucky_i18n::{Catalog, Key};
+
+use crate::app::components::buttons::{self, IconVariant};
+use crate::app::components::divider;
+use crate::app::components::inputs::{search_bar, SearchBar};
+use crate::app::components::navigation::list_item::{list_item, ListItem};
+use crate::theme::Ui;
+
+use super::super::frame;
+use super::super::layout::rails::{LIST_DATE_WIDTH, LIST_KIND_WIDTH, ROW_GAP, ROW_ICON_BUTTON};
+use super::super::Message;
+use super::model::{Download, VersionRow};
+use super::{install, states};
+
+/// 列表列（三栏档与 chips 档共用一份）。
+pub(super) fn content<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    model: &'a Download,
+) -> Element<'a, Message> {
+    let visible = visible(model);
+
+    let body: Element<'a, Message> = if model.no_match() {
+        states::no_match(ui, catalog)
+    } else if model.only_elsewhere() {
+        states::elsewhere(ui, catalog, model.hits)
+    } else if visible.is_empty() {
+        states::empty(ui, catalog)
+    } else {
+        list(ui, catalog, model, &visible)
+    };
+
+    let tail: Element<'a, Message> = if model.install.is_some() {
+        column![divider::full(ui), install::panel(ui, catalog, model)]
+            .spacing(ui.space(Space::X3))
+            .width(Length::Fill)
+            .into()
+    } else {
+        install::panel(ui, catalog, model)
+    };
+
+    column![
+        search_row(ui, catalog, model),
+        divider::full(ui),
+        head(ui, catalog, visible.len()),
+        body,
+        tail,
+    ]
+    .spacing(ui.space(Space::X2))
+    .width(Length::Fill)
+    .height(Length::Fill)
+    .into()
+}
+
+/// 搜索条 + 清空按钮 + 命中数（三者一行；命中数只在有查询词时出现）。
+pub(super) fn search_row<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    model: &'a Download,
+) -> Element<'a, Message> {
+    let bar = search_bar(
+        ui,
+        SearchBar::new(model.query.as_str())
+            .placeholder(catalog.text(Key::VersionSearchPlaceholder)),
+        Message::SetVersionQuery,
+    );
+
+    let mut line = row![container(bar).width(Length::Fill)]
+        .spacing(ui.space(Space::X2))
+        .align_y(Alignment::Center)
+        .width(Length::Fill);
+
+    if model.has_query() {
+        // 命中数是**跨类型**的读数（`Download::hits`），所以它在「当前分类没命中」时也照画
+        line = line.push(frame::text_role_owned(
+            ui,
+            TypeRole::LabelMedium,
+            false,
+            hits_text(catalog, model.hits),
+            ui.color(Role::OnSurfaceVariant),
+        ));
+        line = line.push(buttons::icon(
+            ui,
+            IconVariant::Standard,
+            IconKind::Close,
+            Some(Message::ClearVersionQuery),
+            None,
+        ));
+    }
+
+    line.into()
+}
+
+/// 命中数的文案：`1` 与 `>1` 是两条 key（英文的 `1 matches` 是错的，复审 P2-4）。
+///
+/// 中文两侧都是「个匹配」，但**不能**因此只留一条 key：英文的复数规则要在目录里可读，
+/// 而且将来加第三种语言时这条分支已经在那儿了。
+pub(super) fn hits_text(catalog: Catalog, count: usize) -> String {
+    let key = if count == 1 {
+        Key::VersionSearchHitsOne
+    } else {
+        Key::VersionSearchHits
+    };
+    catalog.render(key, &[("count", &count.to_string())])
+}
+
+/// 「命中在别的类型里」的正文（同样单复数两条 key）。
+pub(super) fn elsewhere_text(catalog: Catalog, count: usize) -> String {
+    let key = if count == 1 {
+        Key::VersionSearchElsewhereOne
+    } else {
+        Key::VersionSearchElsewhere
+    };
+    catalog.render(key, &[("count", &count.to_string())])
+}
+
+/// 计数头（`LabelMedium`）：一行 = 一个 key，数字走占位符，不拼片段。
+pub(super) fn head<'a>(ui: &'a Ui, catalog: Catalog, count: usize) -> Element<'a, Message> {
+    frame::text_role_owned(
+        ui,
+        TypeRole::LabelMedium,
+        false,
+        catalog.render(Key::DownloadCount, &[("count", &count.to_string())]),
+        ui.color(Role::OnSurfaceVariant),
+    )
+}
+
+/// 当前可见的行：先按分类（模型已过滤），再按第二级侧栏**此刻生效**的主版本桶。
+///
+/// 桶的生效值来自 [`super::group::active_bucket`]：搜索期间它恒为「全部」，于是
+/// 「命中数说 N 个、列表却 0 行」这种自相矛盾在结构上不可能出现（复审 P2-1）。
+pub(super) fn visible(model: &Download) -> Vec<&VersionRow> {
+    match super::group::active_bucket(model) {
+        None => model.rows.iter().collect(),
+        Some(key) => model
+            .rows
+            .iter()
+            .filter(|entry| entry.major().as_deref() == Some(key))
+            .collect(),
+    }
+}
+
+/// 版本行列表（**独立滚动**：只有列表滚，安装面板钉在底部不跟着滚）。
+fn list<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    model: &'a Download,
+    visible: &[&'a VersionRow],
+) -> Element<'a, Message> {
+    let entries = column(
+        visible
+            .iter()
+            .map(|entry| version_row(ui, catalog, model, entry))
+            .collect::<Vec<_>>(),
+    )
+    // M102：行距归零（见模块文档），只留横向留白
+    .padding(Padding::from([0.0, ui.space(Space::X2)]))
+    .width(Length::Fill);
+
+    scrollable(entries)
+        .direction(scrollable::Direction::Vertical(
+            scrollable::Scrollbar::new()
+                .width(frame::SCROLLBAR_WIDTH)
+                .scroller_width(frame::SCROLLBAR_WIDTH)
+                .margin(frame::SCROLLBAR_MARGIN),
+        ))
+        .height(Length::Fill)
+        .style(frame::scroll_style(ui))
+        .into()
+}
+
+/// 一行：`ListItem`（版本号，可点选）+ 类型 + 日期 + 安装图标按钮（**四样同一行**）。
+///
+/// 点版本号 = [`Message::SelectVersion`]（页面内选中，不 dispatch）；点尾随按钮 =
+/// [`Message::InstallVersion`]。已装的版本给勾 + 禁用按钮（不重复安装）。
+fn version_row<'a>(
+    ui: &'a Ui,
+    catalog: Catalog,
+    model: &Download,
+    entry: &'a VersionRow,
+) -> Element<'a, Message> {
+    let mut item = ListItem::new(entry.id.as_str(), Message::SelectVersion(entry.id.clone()))
+        .leading(IconKind::Download);
+
+    if entry.installed {
+        item = item.trailing(IconKind::Check);
+    }
+    if model.selected.as_deref() == Some(entry.id.as_str()) {
+        item = item.selected();
+    }
+
+    // 版本号那一格吃掉剩下的宽（`ListItem` 自己是 `Wrapping::None`：再长也**不折行**，
+    // 由外层 clip 切掉）。定宽的三格因此永远落在右边，行宽下限 424 保证它们不会被挤出容器。
+    row![
+        container(list_item(ui, item)).width(Length::Fill),
+        cell(
+            ui,
+            catalog.text(super::model::kind_label_key(entry.kind)),
+            LIST_KIND_WIDTH
+        ),
+        cell(ui, entry.released.as_str(), LIST_DATE_WIDTH),
+        install_action(ui, entry),
+    ]
+    .spacing(ui.space(ROW_GAP))
+    .align_y(Alignment::Center)
+    .width(Length::Fill)
+    .into()
+}
+
+/// 一格定宽文本（`LabelMedium` + `OnSurfaceVariant`；单行，超长由外层 clip）。
+fn cell<'a>(ui: &'a Ui, text: &'a str, width: f32) -> Element<'a, Message> {
+    container(frame::text_role(
+        ui,
+        TypeRole::LabelMedium,
+        false,
+        text,
+        ui.color(Role::OnSurfaceVariant),
+    ))
+    .width(Length::Fixed(width))
+    .into()
+}
+
+/// 行尾的安装按钮：已装 → `Check`（`Primary`）；未装 → `Download` 图标按钮（命中区 40/48）。
+///
+/// 「本页唯一实心 accent」留在底部面板那个带文字的「安装」按钮上（rubric K2），行内用标准图标按钮：
+/// 一行一个实心药丸会让列表变成一排强调色。
+fn install_action<'a>(ui: &'a Ui, entry: &'a VersionRow) -> Element<'a, Message> {
+    if entry.installed {
+        return container(frame::glyph(
+            IconKind::Check,
+            ui.color(Role::Primary),
+            frame::ICON_PX,
+        ))
+        .width(Length::Fixed(ROW_ICON_BUTTON))
+        .align_x(Alignment::Center)
+        .into();
+    }
+
+    container(buttons::icon(
+        ui,
+        IconVariant::Standard,
+        IconKind::Download,
+        Some(Message::InstallVersion(entry.id.clone())),
+        None,
+    ))
+    .width(Length::Fixed(ROW_ICON_BUTTON))
+    .align_x(Alignment::Center)
+    .into()
+}
diff --git a/crates/app-iced/src/pages/download/rows/tests.rs b/crates/app-iced/src/pages/download/rows/tests.rs
new file mode 100644
index 0000000..e05ab31
--- /dev/null
+++ b/crates/app-iced/src/pages/download/rows/tests.rs
@@ -0,0 +1,41 @@
+//! 列表列的两条判据：**单行**（四样挤得下）与**搜索框真的在**（不是摆样子）。
+
+use crate::pages::layout::rails::{
+    version_list_min_width, version_row_min_width, LIST_DATE_WIDTH, LIST_KIND_WIDTH, ROW_GAP,
+    ROW_ICON_BUTTON,
+};
+
+/// 行宽下限 424 之下，四样东西仍在一行里（并留出够放 `1.21.9-pre3` 的版本号格）。
+///
+/// 抓得住：有人把类型 / 日期 / 按钮的格子改宽（改到 424 放不下时这条红），或者把行宽下限调小。
+/// 抓不住：真的渲染出来会不会折行（`ListItem` 的 `Wrapping::None` 是组件层的事，成图在报告里）。
+#[test]
+fn the_version_row_still_fits_on_one_line_at_the_floor() {
+    let floor = version_list_min_width();
+    assert_eq!(floor, 424.0, "行宽下限就是既有的 424");
+
+    let needed = version_row_min_width();
+    assert!(
+        needed <= floor,
+        "四样固定格加起来要 {needed}，超过行宽下限 {floor} 就得折行"
+    );
+
+    // 版本号那一格在最窄情况下还剩多少
+    let label_room = floor - LIST_KIND_WIDTH - LIST_DATE_WIDTH - ROW_ICON_BUTTON - 3.0 * ROW_GAP.dp();
+    assert!(
+        label_room >= 176.0,
+        "版本号那一格只剩 {label_room}，`1.21.9-pre3`（11 字符）会被切"
+    );
+}
+
+/// 搜索条出现在列表列里（源码层面钉住：「有搜索框」这件事不能悄悄被删掉）。
+///
+/// 抓得住：有人把搜索条从列表列里拿掉（那一整块需求就没了）。
+/// 抓不住：搜索条是否**生效**（效果由 `download/tests.rs` 的跨类型命中数断言与出图负责）。
+#[test]
+fn the_search_bar_is_actually_mounted() {
+    let source = include_str!("../rows.rs");
+    assert!(source.contains("search_bar("), "搜索条没装");
+    assert!(source.contains("Message::SetVersionQuery"), "搜索条不产生查询消息");
+    assert!(source.contains("Message::ClearVersionQuery"), "搜索条没有清空入口");
+}
diff --git a/crates/app-iced/src/pages/download/states.rs b/crates/app-iced/src/pages/download/states.rs
new file mode 100644
index 0000000..42215b3
--- /dev/null
+++ b/crates/app-iced/src/pages/download/states.rs
@@ -0,0 +1,164 @@
+//! 占位状态（加载 / 空）：**同一套占位规则——内容在可用区居中**（M94 r1 / P2-1）。
+//!
+//! | 状态 | 条件（都能从快照推出来） | 画什么 |
+//! |---|---|---|
+//! | 加载 | `model.is_loading()`：快照里还没有版本列表 | 标题 + 一句说明（**没有任何进度形状**） |
+//! | 空 | `model.is_empty()`：列表拉到了，但过滤后一行不剩 | 真 [`empty_state`]（图标块 96 + 24 标题 + 说明 + 刷新 CTA） |
+//!
+//! ## 为什么是「都居中」（P2-1）
+//!
+//! `components::feedback::empty_state` 的既有口径（`12b §15.4`）就是「内容在可用区居中」；
+//! 加载态原先贴顶，等于同一个页面里两套占位规则，两态互切时内容会纵向跳一次。所以本轮把加载态
+//! 也放进同一条规则里。**有数据时列表仍然贴顶**——那是有内容的状态，不属于占位规则。
+//!
+//! ## 为什么加载态没有进度条（P2-3）
+//!
+//! 页面**没有帧订阅**（`app/subscription.rs` 的 `needs_frames` 归 app 层），所以
+//! `Progress::indeterminate(phase)` 拿到的是一个**静止的**相位——用户看到的是「17% 卡住」。
+//! 与其留一个「看起来有进度但不动」的控件，不如给一句明确的「正在加载」文字；等 app 层真有了
+//! 帧订阅再来带动画（那时这里换回 indeterminate 才有意义）。
+//!
+//! ## 文案口径（P2-2）
+//!
+//! 只说页面真能做到的动作：说明里那句「点右上角的刷新」对应页头那个真的 Refresh 按钮
+//! （`Message::Action(Action::RefreshSources)`）；没有写「稍后会自动重试」这种 UI 做不到的承诺。
+
+use iced::widget::{column, container};
+use iced::{Alignment, Element, Length};
+
+use unlucky_design::color::Role;
+use unlucky_design::icons::IconKind;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use unlucky_i18n::{Catalog, Key};
+
+use crate::app::components::buttons::{self, Button};
+use crate::app::components::feedback::{empty_state, EmptyState};
+use crate::theme::Ui;
+
+use super::super::frame;
+use super::super::{Action, Message};
+use super::model::Category;
+
+/// 空态图标块边长（12b §15.1：**96×96**，与 `components::feedback::EmptyState` 内部同一个项目值；
+/// 那里是 `frame::pieces::EMPTY_ICON_BLOCK`（`pub(super)`，本模块取不到，只能同值声明一次）。
+const EMPTY_ICON_BLOCK: f32 = 96.0;
+
+/// 两个占位状态共用的外壳：水平 + 垂直都居中（见模块文档的两条理由）。
+fn centered<'a>(content: impl Into<Element<'a, Message>>) -> Element<'a, Message> {
+    container(content)
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .align_x(Alignment::Center)
+        .align_y(Alignment::Center)
+        .into()
+}
+
+/// 加载态：一句「正在加载」+ 一句这个页面真能做的事（点刷新）。
+pub(super) fn loading<'a>(ui: &'a Ui, catalog: Catalog) -> Element<'a, Message> {
+    centered(
+        column![
+            frame::text_role_centered(
+                ui,
+                TypeRole::TitleMedium,
+                true,
+                catalog.text(Key::DownloadLoading),
+                ui.color(Role::OnSurface),
+            ),
+            frame::text_role_centered(
+                ui,
+                TypeRole::BodySmall,
+                false,
+                catalog.text(Key::DownloadLoadingHint),
+                ui.color(Role::OnSurfaceVariant),
+            ),
+        ]
+        .spacing(ui.space(Space::X3))
+        .width(Length::Fill)
+        .align_x(Alignment::Center),
+    )
+}
+
+/// 空态（真 `EmptyState`：CTA 就是标准 Filled 按钮，走按钮家族）。
+pub(super) fn empty<'a>(ui: &'a Ui, catalog: Catalog) -> Element<'a, Message> {
+    centered(empty_state(
+        ui,
+        EmptyState::new(
+            IconKind::Download,
+            catalog.text(Key::DownloadEmptyTitle),
+            catalog.text(Key::DownloadEmptyBody),
+        )
+        .action(
+            catalog.text(Key::DownloadRefresh),
+            Message::Action(Action::RefreshSources),
+        ),
+    ))
+}
+
+/// 搜索**一个都不命中**（跨类型也没有）：说「没有匹配」+ 一句「换短一点的片段」+ 清空入口。
+///
+/// 与 [`empty`] 分开的理由：那个是「这个分类里没有版本」，这个是「这个词没有任何版本」——
+/// 两种情况该给的下一步动作不同（前者换分类/刷新，后者改搜索词）。
+pub(super) fn no_match<'a>(ui: &'a Ui, catalog: Catalog) -> Element<'a, Message> {
+    centered(empty_state(
+        ui,
+        EmptyState::new(
+            IconKind::Search,
+            catalog.text(Key::VersionSearchEmptyTitle),
+            catalog.text(Key::VersionSearchEmptyBody),
+        )
+        .action(
+            catalog.text(Key::VersionSearchClear),
+            Message::ClearVersionQuery,
+        ),
+    ))
+}
+
+/// **有命中但不在当前分类**：说清「N 个在别的类型里」+ 一个「看全部类型」的出口。
+///
+/// 不给出口的话，用户只能自己猜「是不是要切到快照 tab」——这正是本条的验收口径。
+///
+/// 标题**不再复用命中数那条 key**（复审 P2-4）：原来同一个数在同屏报三遍
+/// （右上角「1 matches」+ 标题「1 matches」+ 正文「1 versions match」），而且单数时英文是错的。
+/// 现在标题是一条固定文案，正文的单复数由 [`super::rows::elsewhere_text`] 选 key。
+pub(super) fn elsewhere<'a>(ui: &'a Ui, catalog: Catalog, hits: usize) -> Element<'a, Message> {
+    let title = catalog.text(Key::VersionSearchElsewhereTitle).to_owned();
+    let body = super::rows::elsewhere_text(catalog, hits);
+
+    // 手搭而不是用 `EmptyState`：它的标题/正文借 `&'a str`，而这里的句子是 `render()` 出来的
+    // `String`（带命中数），借不到 `'a`。字形、字级、按钮全走同一套令牌，视觉上仍是空态。
+    centered(
+        column![
+            frame::glyph_box(
+                IconKind::Search,
+                ui.color(Role::OnSurfaceVariant),
+                EMPTY_ICON_BLOCK
+            ),
+            frame::text_role_owned(
+                ui,
+                TypeRole::HeadlineSmall,
+                false,
+                title,
+                ui.color(Role::OnSurface),
+            ),
+            frame::text_role_owned(
+                ui,
+                TypeRole::BodySmall,
+                false,
+                body,
+                ui.color(Role::OnSurfaceVariant),
+            ),
+            buttons::filled(
+                ui,
+                Button::new(
+                    catalog.text(Key::VersionSearchElsewhereAction),
+                    Message::SetCategory(Category::All),
+                ),
+            ),
+        ]
+        .spacing(ui.space(Space::X3))
+        .width(Length::Fill)
+        .align_x(Alignment::Center),
+    )
+}
diff --git a/crates/app-iced/src/pages/download/tests.rs b/crates/app-iced/src/pages/download/tests.rs
new file mode 100644
index 0000000..a1b3e56
--- /dev/null
+++ b/crates/app-iced/src/pages/download/tests.rs
@@ -0,0 +1,302 @@
+//! 版本管理页的判据：**快照 → 模型 → 控件树**三段各自的断言。
+//!
+//! 每条都写清「抓得住什么 / 抓不住什么」——这里只测纯转换与树能构建，**像素**由
+//! `DevDocs/artifacts/m107/` 的十张图与报告的量测表负责（同 `pages/tests.rs` 的口径）。
+
+use unlucky_design::color::SchemeFlavor;
+use unlucky_design::typography::Platform;
+use unlucky_i18n::Lang;
+use unlucky_presenter::dto::{
+    AncientKind, AppEvent, CoreEvent, InstallProgressView, InstallStage, VersionCategory,
+    VersionKind, VersionSummary,
+};
+use unlucky_presenter::state::AppState;
+
+use crate::theme::{Families, Ui};
+
+use super::super::layout::{frame_metrics, PaneKit};
+use super::model::{Category, Download};
+use super::options::InstallDraft;
+
+mod i18n;
+
+const FAMILIES: Families = Families {
+    text: "Segoe UI",
+    display: "Segoe UI",
+    mono: "Consolas",
+};
+
+fn ui() -> Ui {
+    Ui::with_platform(SchemeFlavor::Light, Platform::Windows, FAMILIES)
+}
+
+fn version(id: &str, kind: VersionKind, installed: bool) -> VersionSummary {
+    VersionSummary {
+        id: id.to_string(),
+        kind,
+        released: "2026-09-20".to_string(),
+        installed,
+    }
+}
+
+fn state_with(versions: Vec<VersionSummary>) -> AppState {
+    let mut state = AppState::new();
+    state.apply(AppEvent::Core(CoreEvent::VersionListChanged(versions)));
+    state
+}
+
+/// 一份覆盖四种版本形态的清单（`1.21.x` / `24w14a` / `rd-132211` / `a1.2.6`）。
+fn mixed() -> Vec<VersionSummary> {
+    vec![
+        version("1.21.9", VersionKind::Release, false),
+        version("1.21.8", VersionKind::Release, true),
+        version("1.20.4", VersionKind::Release, true),
+        version("24w14a", VersionKind::Snapshot, false),
+        version(
+            "rd-132211",
+            VersionKind::Ancient(AncientKind::Classic),
+            false,
+        ),
+    ]
+}
+
+// --------------------------------------------------------------- 版面
+
+/// 页面仍是单列页（页内三栏是**页内**的事，不改 `PaneKit`）：任何宽度都不出现「页面级第二列」。
+///
+/// 抓得住：有人把 `Screen::Download` 的 `kit()` 改成 `ListDetail`（那会让页头与页边距跟着变）。
+/// 抓不住：页内三栏的宽度（那由 `layout/rails/tests.rs` 的数值表钉住）。
+#[test]
+fn the_page_kit_is_still_single() {
+    for width in [700.0, 900.0, 1024.0, 1180.0, 2400.0] {
+        let metrics = frame_metrics(PaneKit::Single, width);
+        assert!(metrics.secondary.is_none(), "{width} 出现了页面级第二列");
+    }
+}
+
+// --------------------------------------------------------------- 两层侧栏（见 `tests/rails.rs`）
+
+mod rails;
+
+// --------------------------------------------------------------- 搜索一致性 / 复数（见 `tests/search.rs`）
+
+mod search;
+
+// --------------------------------------------------------------- 文案（i18n）
+
+// --------------------------------------------------------------- 快照 → 模型
+
+/// 真快照进得来：行数、分类、选中项、已装标记、主版本桶全部来自 `AppState`。
+#[test]
+fn the_snapshot_becomes_the_page_model() {
+    let mut state = state_with(vec![
+        version("1.21.9", VersionKind::Release, false),
+        version("1.21.8", VersionKind::Release, true),
+    ]);
+    state.apply(AppEvent::Core(CoreEvent::InstallProgress(Some(
+        InstallProgressView {
+            version: "1.21.9".to_string(),
+            loader: "Vanilla".to_string(),
+            stage: InstallStage::Downloading,
+            files_done: 128,
+            files_total: 512,
+            speed_bps: 1_258_291,
+            eta_secs: 75,
+            ..InstallProgressView::new()
+        },
+    ))));
+
+    let model = Download::from_snapshot(
+        &state,
+        Category::All,
+        &InstallDraft::default(),
+        Lang::En.catalog(),
+    );
+
+    assert_eq!(model.rows.len(), 2);
+    assert_eq!(model.rows[0].id, "1.21.9");
+    assert!(model.rows[1].installed, "快照说装了就是装了");
+    assert_eq!(model.category, Category::All);
+    assert_eq!(
+        model.selected.as_deref(),
+        Some("1.21.9"),
+        "正在安装的版本 = 选中行"
+    );
+    assert!(model.loaded, "有版本 = 已加载");
+    assert_eq!(model.buckets.len(), 1, "两个版本同一个主版本桶");
+    assert_eq!(model.buckets[0].key.as_deref(), Some("1.21"));
+    assert_eq!(model.hits, 2, "没有搜索词时命中数 = 行数");
+
+    let install = model.install.expect("安装进度要转进来");
+    assert!(install.running());
+    assert_eq!(install.detail, "128/512 files");
+}
+
+/// 快照里的两个过滤条件（`installed_only` / `download_query`）原样照用。
+#[test]
+fn presenter_filters_still_apply() {
+    let mut state = state_with(vec![
+        version("1.21.9", VersionKind::Release, false),
+        version("1.21.8", VersionKind::Release, true),
+        version("1.20.4", VersionKind::Release, true),
+    ]);
+
+    let installed_only = {
+        state.installed_only = true;
+        Download::from_snapshot(
+            &state,
+            Category::All,
+            &InstallDraft::default(),
+            Lang::En.catalog(),
+        )
+    };
+    assert_eq!(installed_only.rows.len(), 2, "仅已装");
+
+    let queried = {
+        state.installed_only = false;
+        state.download_query = " 1.21 ".to_string();
+        Download::from_snapshot(
+            &state,
+            Category::All,
+            &InstallDraft::default(),
+            Lang::En.catalog(),
+        )
+    };
+    assert_eq!(queried.rows.len(), 2, "版本号片段匹配两个");
+    assert_eq!(queried.query, "1.21", "查询词去掉首尾空格后进模型");
+    assert_eq!(queried.hits, 2);
+}
+
+/// 空快照 = 加载态；过滤掉所有行 = 空态。
+#[test]
+fn loading_and_empty_are_different_states() {
+    let loading = Download::from_snapshot(
+        &AppState::new(),
+        Category::All,
+        &InstallDraft::default(),
+        Lang::En.catalog(),
+    );
+    assert!(loading.is_loading() && !loading.is_empty());
+
+    let mut state = state_with(vec![version("1.21.9", VersionKind::Release, false)]);
+    state.download_query = "no-such-version".to_string();
+    let empty = Download::from_snapshot(
+        &state,
+        Category::All,
+        &InstallDraft::default(),
+        Lang::En.catalog(),
+    );
+    assert!(!empty.is_loading(), "列表拉到了，不是加载中");
+    assert!(empty.is_empty(), "过滤后没有行 = 空态");
+    assert!(empty.no_match(), "跨类型也没有 ⇒ 没有匹配");
+    assert!(!empty.only_elsewhere());
+}
+
+/// **搜索跨类型**：命中数与当前分类无关，行数相关。
+///
+/// 抓得住：有人把 `hits` 也算成「当前分类的命中」（那会让「正式版里搜 24w」显示 0 个匹配，
+/// 用户以为没有这个版本）。
+/// 抓不住：大小写之外的搜索口径（模糊匹配 / 分词属 presenter）。
+#[test]
+fn search_hits_are_cross_category() {
+    let mut state = state_with(mixed());
+    state.download_query = "1.20".to_string();
+
+    let all = Download::from_snapshot(
+        &state,
+        Category::All,
+        &InstallDraft::default(),
+        Lang::En.catalog(),
+    );
+    assert_eq!(all.rows.len(), 1);
+    assert_eq!(all.hits, 1);
+
+    // 同一个词，站在「预览版」分类里：行数 0，命中数仍是 1
+    let snapshot = Download::from_snapshot(
+        &state,
+        Category::Snapshot,
+        &InstallDraft::default(),
+        Lang::En.catalog(),
+    );
+    assert_eq!(snapshot.rows.len(), 0);
+    assert_eq!(snapshot.hits, 1, "命中数是跨类型读数");
+    assert!(snapshot.only_elsewhere(), "有命中但不在当前分类");
+    assert!(!snapshot.no_match(), "不是「没有匹配」");
+}
+
+/// 「搜不到」与「在当前分类搜不到」是两种画面（文案与出口都不同）。
+#[test]
+fn the_two_search_misses_are_distinguishable() {
+    let mut state = state_with(mixed());
+
+    state.download_query = "zzz".to_string();
+    let nothing = Download::from_snapshot(
+        &state,
+        Category::All,
+        &InstallDraft::default(),
+        Lang::En.catalog(),
+    );
+    assert!(nothing.no_match() && !nothing.only_elsewhere());
+
+    state.download_query = "rd-".to_string();
+    let elsewhere = Download::from_snapshot(
+        &state,
+        Category::Release,
+        &InstallDraft::default(),
+        Lang::En.catalog(),
+    );
+    assert!(elsewhere.only_elsewhere() && !elsewhere.no_match());
+
+    let home = Download::from_snapshot(
+        &state,
+        Category::Ancient,
+        &InstallDraft::default(),
+        Lang::En.catalog(),
+    );
+    assert_eq!(home.rows.len(), 1, "切到远古版就看见了");
+    assert!(!home.no_match() && !home.only_elsewhere());
+}
+
+/// 分类反推：混合 = 全部，远古 = 远古（不看子类）。
+#[test]
+fn the_category_is_derived_from_the_list() {
+    let mixed = vec![
+        version("1.21.9", VersionKind::Release, false),
+        version("1.21.9-pre3", VersionKind::Snapshot, false),
+    ];
+    assert_eq!(Category::of(&mixed), Category::All);
+    assert_eq!(
+        Category::of(&[version("x", VersionKind::Snapshot, false)]),
+        Category::Snapshot
+    );
+    assert_eq!(
+        Category::of(&[version(
+            "rd-132211",
+            VersionKind::Ancient(AncientKind::OldBeta),
+            false
+        )]),
+        Category::Ancient
+    );
+    assert_eq!(Category::of(&[]), Category::All);
+}
+
+/// 分类 chip 派的是**真指令**。
+#[test]
+fn category_commands_are_real() {
+    assert_eq!(Category::All.command(), None, "全部 = 画现有快照，不派指令");
+    assert_eq!(Category::Release.command(), Some(VersionCategory::Release));
+    assert_eq!(
+        Category::Snapshot.command(),
+        Some(VersionCategory::Snapshot)
+    );
+    assert_eq!(
+        Category::Ancient.command(),
+        Some(VersionCategory::Ancient(AncientKind::Classic))
+    );
+    assert!(Category::Ancient.matches(VersionKind::Ancient(AncientKind::Unlisted)));
+    assert!(!Category::Release.matches(VersionKind::Snapshot));
+}
+
+// --------------------------------------------------------------- 控件树（见 `tests/view.rs`）
+
+mod view;
diff --git a/crates/app-iced/src/pages/download/tests/i18n.rs b/crates/app-iced/src/pages/download/tests/i18n.rs
new file mode 100644
index 0000000..b5fa3ab
--- /dev/null
+++ b/crates/app-iced/src/pages/download/tests/i18n.rs
@@ -0,0 +1,106 @@
+//! 下载页的**文案守门**（M105 从 `download/tests.rs` 搬出：那边加了安装选项的用例之后顶破 400 行）。
+//!
+//! 两条各守一件事：死 key（目录里有、页面没用）与「模型说的是目录的语言」。
+
+use unlucky_i18n::{Key, Lang};
+use unlucky_presenter::dto::VersionKind;
+
+use super::*;
+
+// --------------------------------------------------------------- 文案（i18n）
+
+/// 每个 `Download*` key 都**真的被页面引用**（死 key 守门，M94 r1 / P2-6）。
+///
+/// 复审抓到的 `DownloadSelected` 就是这条要拦的东西：目录里定义了、页面没人用。所以这里把页面
+/// 源码用 `include_str!` 编进来扫一遍。**抓不住什么也说清**：反向（引用了不存在的 key）是编译错误，
+/// 不需要测试；译文对不对、两套语言都填了没由 `i18n` 自己的 `built_in_catalogs_have_every_key` 守；
+/// 它只看字面出现，用宏拼 key 名能骗过它。
+#[test]
+fn every_download_key_is_referenced_by_the_page() {
+    const SOURCES: [&str; 11] = [
+        include_str!("../../download.rs"),
+        include_str!("../model.rs"),
+        // M107：分类枚举搬进 `model/category.rs`（`Category::label_key` 在那儿，漏扫会误判死 key）
+        include_str!("../model/category.rs"),
+        include_str!("../rows.rs"),
+        // M107：两级侧栏与分组规则（`VersionRailTitle` / `VersionMajorAll` 的落点）
+        include_str!("../rails.rs"),
+        include_str!("../group.rs"),
+        include_str!("../install.rs"),
+        include_str!("../states.rs"),
+        include_str!("../demo.rs"),
+        // M105：安装选项区的两条填页线（漏扫的话新 key 会被判成死 key）
+        include_str!("../options/model.rs"),
+        include_str!("../options/view.rs"),
+    ];
+
+    let mut checked = 0;
+    for key in Key::ALL
+        .iter()
+        .filter(|key| key.name().starts_with("Download") || key.name().starts_with("Version"))
+    {
+        let needle = format!("Key::{}", key.name());
+        assert!(
+            SOURCES.iter().any(|source| source.contains(&needle)),
+            "{needle} 在目录里定义了，但下载页没有任何地方用它（死 key，删掉或接上）"
+        );
+        checked += 1;
+    }
+    assert!(
+        checked > 20,
+        "下载页的 key 不该被成批删掉（只查到 {checked} 条）"
+    );
+    assert!(
+        checked > 50,
+        "M107 之后这一页的 key（Download* + Version*）不该少于 50 条，只查到 {checked}"
+    );
+}
+
+/// 页面级的文案全部按 `Catalog` 走：中文目录出中文，英文目录出英文，**且不含 core 的中文业务串**。
+///
+/// 抓得住：页面里又出现硬编码英文/中文字面量、或把 `InstallStage::label()` / `progress.message`
+/// （core 的中文串）画到界面上。
+/// 抓不住：目录里那条译文本身写错了。
+#[test]
+fn the_model_speaks_the_catalog_language() {
+    let versions = vec![version("1.21.9", VersionKind::Release, false)];
+    let state = state_with(versions);
+
+    let en = Download::from_snapshot(
+        &state,
+        Category::All,
+        &InstallDraft::default(),
+        Lang::En.catalog(),
+    );
+    let zh = Download::from_snapshot(
+        &state,
+        Category::All,
+        &InstallDraft::default(),
+        Lang::ZhCn.catalog(),
+    );
+
+    assert_eq!(en.rows[0].supporting, "Release · released 2026-09-20");
+    assert_eq!(zh.rows[0].supporting, "正式版 · 发布于 2026-09-20");
+
+    let progress = InstallProgressView {
+        version: "1.21.9".to_string(),
+        stage: InstallStage::Planning,
+        message: "正在解析版本清单…".to_string(),
+        ..InstallProgressView::new()
+    };
+    let install_en = crate::pages::download::model::InstallView::of(&progress, Lang::En.catalog());
+    assert_eq!(install_en.stage_label, "Planning");
+    assert_eq!(install_en.detail, "Waiting for the first file…");
+    assert!(
+        !install_en.stage_label.contains('解'),
+        "core 的中文阶段串不许直接上屏"
+    );
+    assert!(
+        !install_en.detail.contains('正'),
+        "`InstallProgressView::message` 是中文业务串，页面不许画它"
+    );
+
+    let install_zh =
+        crate::pages::download::model::InstallView::of(&progress, Lang::ZhCn.catalog());
+    assert_eq!(install_zh.stage_label, "解析版本");
+}
diff --git a/crates/app-iced/src/pages/download/tests/rails.rs b/crates/app-iced/src/pages/download/tests/rails.rs
new file mode 100644
index 0000000..b575d76
--- /dev/null
+++ b/crates/app-iced/src/pages/download/tests/rails.rs
@@ -0,0 +1,177 @@
+//! 两层侧栏的护栏（**变异可证**）+ 三栏宽度账。
+//!
+//! 从 `download/tests.rs` 拆出来：那边已经贴着 400 行硬线。
+
+use unlucky_i18n::Lang;
+use unlucky_presenter::dto::{AppEvent, CoreEvent, VersionKind, VersionSummary};
+use unlucky_presenter::state::AppState;
+
+use crate::pages::download::options::InstallDraft;
+use crate::pages::download::rails::major_entries;
+use crate::pages::download::{Category, Download};
+use crate::pages::layout::{
+    available_width, frame_metrics, measure_cap_px, PaneKit, VersionRailTier, VersionRails,
+    RAIL_GAP,
+};
+
+/// 三栏要吃掉整条可用宽（不是 424 的居中正文列）——三个宽度档各取一个采样点。
+///
+/// 抓得住：有人把第三栏写成 `Length::Fill`（那会让三列宽度之和**超过**可用宽、右侧被挤出屏）。
+/// 抓不住：像素级对齐（出图在报告里）。
+#[test]
+fn the_three_columns_spend_the_whole_available_width() {
+    for (window, tier) in [
+        (1180.0, VersionRailTier::Wide),
+        (900.0, VersionRailTier::Narrow),
+        (700.0, VersionRailTier::Chips),
+    ] {
+        let rails = VersionRails::of(available_width(window));
+        assert_eq!(rails.tier, tier, "{window} 的档位");
+        if tier.is_three_column() {
+            let spent = rails.type_rail + rails.major_rail + rails.list + 2.0 * RAIL_GAP;
+            assert!(
+                (spent - available_width(window)).abs() < f32::EPSILON,
+                "{window}：三列 + 两处间距应正好等于可用宽（{spent} vs {}）",
+                available_width(window)
+            );
+        }
+    }
+}
+
+/// **两层侧栏都存在、且选中态真的传给列表**——M107 的护栏，改坏要红。
+///
+/// 四件事一起钉：
+/// 1. 页面装配点仍调 `rails::three_column`（三栏装配是唯一入口）；
+/// 2. 装配点里**两个**侧栏函数都被调用（删掉 `major_rail(` → 只剩一级侧栏 ⇒ 红）；
+/// 3. 两级各自都有可点的消息（`SetCategory` / `SelectMajor`）；
+/// 4. 列表的行确实按第二级选中态过滤（`rows::visible` + `selected_major`）。
+///
+/// 抓得住：删掉一层侧栏、或者让列表无视 `selected_major`（第二级点了没反应）。
+/// 抓不住：两层是否**看起来**是两层（那要出图，见报告）。
+#[test]
+fn both_rail_levels_exist_and_the_selection_reaches_the_list() {
+    let rails_source = include_str!("../rails.rs");
+    let download_source = include_str!("../../download.rs");
+    let rows_source = include_str!("../rows.rs");
+
+    assert!(
+        download_source.contains("rails::three_column"),
+        "页面装配点不再调三栏装配"
+    );
+    for required in ["type_rail(ui", "major_rail(ui"] {
+        assert!(
+            rails_source.contains(required),
+            "两层侧栏缺了一级：找不到 {required}"
+        );
+    }
+    assert!(
+        rails_source.contains("Message::SelectMajor"),
+        "第二级（主版本）没有可点的消息"
+    );
+    assert!(
+        rails_source.contains("Message::SetCategory"),
+        "第一级（版本类型）没有可点的消息"
+    );
+    // 列表按第二级的**生效值**过滤（搜索期间放宽到「全部」，见 `group::active_bucket`）：
+    // 这两样只要有一样不在，第二级点了就等于没反应。
+    assert!(
+        rows_source.contains("fn visible") && rows_source.contains("group::active_bucket"),
+        "列表没有按第二级选中态过滤"
+    );
+    assert_eq!(Category::ALL.len(), 4, "第一级还是原来那四类，不许新造分类");
+}
+
+/// `< 600` 可用宽时两栏都退场、列表吃掉可用宽（chips 档的账）。
+#[test]
+fn the_chips_tier_gives_the_whole_width_to_the_list() {
+    let rails = VersionRails::of(564.0);
+    assert_eq!(rails.tier, VersionRailTier::Chips);
+    assert_eq!(rails.type_rail, 0.0);
+    assert_eq!(rails.major_rail, 0.0);
+    assert_eq!(rails.list, 564.0);
+}
+
+/// **Chips 档的最后一个桶也要够得着**（复审 P2-2）。
+///
+/// 夹具按真实清单的量级造：`1.21 … 1.0` 共 **22 个桶**（`Release` 在 MOJANG 清单里就是这个量级）。
+/// 三条一起钉：
+/// 1. `major_entries` 把**每一个桶**都吐出来（含最后一个 `1.0`）——渲染两条路径都吃这一份数据；
+/// 2. chips 行外面套了 `Direction::Horizontal` 的滚动（源码层，删掉那一层就够不着后面的桶）；
+/// 3. 选中态按**生效值**算：搜索期间「全部版本」点亮（P2-1 的放宽）。
+///
+/// 抓得住：把 chips 行的横向滚动拿掉（第 2 条红）；或让 `major_entries` 在某个桶处截断（第 1 条红）。
+/// 抓不住：滚动条在真机上好不好拖（那要出图 + 手感，报告里登记为未验）。
+#[test]
+fn every_bucket_is_reachable_in_the_chips_tier() {
+    let versions: Vec<VersionSummary> = (0..=21)
+        .rev()
+        .map(|minor| VersionSummary {
+            id: format!("1.{minor}.4"),
+            kind: VersionKind::Release,
+            released: "2026-09-20".to_string(),
+            installed: false,
+        })
+        .collect();
+
+    let mut state = AppState::new();
+    state.apply(AppEvent::Core(CoreEvent::VersionListChanged(versions)));
+
+    let catalog = Lang::En.catalog();
+    let mut model =
+        Download::from_snapshot(&state, Category::All, &InstallDraft::default(), catalog);
+    assert_eq!(model.buckets.len(), 22, "夹具应有 22 个主版本桶");
+
+    let entries = major_entries(catalog, &model);
+    assert_eq!(entries.len(), 23, "「全部版本」+ 22 个桶");
+    assert_eq!(
+        entries.last().and_then(|entry| entry.key),
+        Some("1.0"),
+        "最后一个桶（版本序最老的那个）必须在列表里，否则它永远点不到"
+    );
+    assert_eq!(entries[1].label, "1.21", "第一条桶是版本序最新的");
+
+    // 选中态按生效值：选中 1.0 时那一项点亮；搜索期间整体放宽到「全部」
+    model.selected_major = Some("1.0".to_string());
+    let entries = major_entries(catalog, &model);
+    assert!(entries.last().expect("有最后一项").selected);
+    state.download_query = "1.0".to_string();
+    let mut searching =
+        Download::from_snapshot(&state, Category::All, &InstallDraft::default(), catalog);
+    searching.selected_major = Some("1.0".to_string());
+    let entries = major_entries(catalog, &searching);
+    assert!(entries[0].selected, "搜索期间「全部版本」点亮（P2-1）");
+    assert!(
+        entries.iter().skip(1).all(|entry| !entry.selected),
+        "搜索期间不许留下幽灵选中"
+    );
+
+    // chips 行的横向滚动是「够得着」的实现手段
+    let source = include_str!("../rails.rs");
+    assert!(
+        source.contains("Direction::Horizontal"),
+        "chips 档的主版本行必须可横向滚动（否则 22 个桶里大部分点不到）"
+    );
+    assert!(
+        source.contains("major_entries(catalog, model)"),
+        "竖栏与 chips 行必须吃同一份 entries"
+    );
+}
+
+/// 宽窗下多出来的宽度归**页面块**，不归散文列（M102 订正；旧口径是「留白」）。
+///
+/// 抓得住：谁把整页块又压回 424（视觉复审 ① 的原样：块宽 = `column`，1180 下左右各留 ~300px）；
+/// 抓不住：真实像素（报告里的量测表负责）。
+#[test]
+fn extra_width_goes_to_the_page_block_not_to_the_prose_column() {
+    let metrics = frame_metrics(PaneKit::Single, 1180.0);
+    assert_eq!(metrics.column, measure_cap_px(), "散文列仍是行宽上限 424");
+    assert_eq!(
+        crate::pages::frame::body_width(metrics),
+        metrics.available,
+        "页面块必须吃满可用宽度（1044），不是被居中压成 424"
+    );
+    assert!(
+        metrics.available - metrics.column >= 400.0,
+        "两个量要分得开：块宽 1044 比散文列 424 宽出 620"
+    );
+}
diff --git a/crates/app-iced/src/pages/download/tests/search.rs b/crates/app-iced/src/pages/download/tests/search.rs
new file mode 100644
index 0000000..b6b1a78
--- /dev/null
+++ b/crates/app-iced/src/pages/download/tests/search.rs
@@ -0,0 +1,217 @@
+//! 搜索 × 主版本桶的一致性判据（复审 P2-1）+ 复数口径（P2-4）。
+//!
+//! 这两条都是「一屏之内两句话打架」那类问题：命中数说 N 个、列表却 0 行；或者英文写 `1 matches`。
+//! 所以断言都写成**不变式**（对一张输入矩阵扫），而不是挑一个例子。
+
+use unlucky_i18n::Lang;
+use unlucky_presenter::dto::{AppEvent, CoreEvent, VersionKind, VersionSummary};
+use unlucky_presenter::state::AppState;
+
+use super::super::group;
+use super::super::model::{Category, Download};
+use super::super::options::InstallDraft;
+use super::super::rows;
+use super::version;
+
+fn state_with(versions: Vec<VersionSummary>, query: &str) -> AppState {
+    let mut state = AppState::new();
+    state.apply(AppEvent::Core(CoreEvent::VersionListChanged(versions)));
+    state.download_query = query.to_string();
+    state
+}
+
+/// 一份带三个主版本桶的清单（`1.21` / `1.20` / `24w`）。
+fn three_buckets() -> Vec<VersionSummary> {
+    vec![
+        version("1.21.9", VersionKind::Release, false),
+        version("1.21.8", VersionKind::Release, true),
+        version("1.20.4", VersionKind::Release, true),
+        version("1.20.1", VersionKind::Release, false),
+        version("24w14a", VersionKind::Snapshot, false),
+    ]
+}
+
+/// **P2-1 的核心不变式**：搜索有命中时，列表要么有行，要么落到「命中在别的类型里」那条口径。
+///
+/// 扫「四个分类 × 五个桶值 × 四个查询词」：任何一格出现「hits > 0 且可见行为空 **且**
+/// `only_elsewhere()` 为假」就是自相矛盾的一屏——那正是复审复现的形态：选中 `1.21` 后搜 `1.20`，
+/// `rows` 非空所以 `only_elsewhere()` 也是假，于是页面落到「没有版本」的空态，而同屏写着「2 matches」。
+///
+/// （分类这一层本来就有 `only_elsewhere()`：站在「正式版」搜 `24w` 时列表空是**对的**，
+/// 页面会说「N 个命中在别的类型里」并给出口——那不是矛盾，所以判据里要把它排除。）
+///
+/// 抓得住：把 `group::active_bucket` 的搜索放宽去掉（那一行删掉，这一格立刻红）。
+/// 抓不住：像素上这两句话是否真的没同屏（那要出图，见 `DevDocs/artifacts/m107/`）。
+#[test]
+fn a_search_hit_never_lands_on_an_empty_list() {
+    // A 组：**有搜索词**。桶可以是任意值（包括「桶列表里不存在」的过期值），分类也随便切——
+    //    只要 hits > 0，可见行就不许为空。这一组是 P2-1 的正面判据。
+    for category in Category::ALL {
+        for bucket in [None, Some("1.21"), Some("1.20"), Some("24w"), Some("9.99")] {
+            for query in ["1.20", "1.21", "24w", "zzz"] {
+                let state = state_with(three_buckets(), query);
+                let mut model = Download::from_snapshot(
+                    &state,
+                    category,
+                    &InstallDraft::default(),
+                    Lang::En.catalog(),
+                );
+                model.selected_major = bucket.map(str::to_string);
+
+                let visible = rows::visible(&model);
+                let contradiction = model.hits > 0 && visible.is_empty() && !model.only_elsewhere();
+                assert!(
+                    !contradiction,
+                    "分类 {category:?} / 桶 {bucket:?} / 查询 {query:?}：命中数 {} 但可见行 0                      且没有「命中在别的类型」的口径 ⇒ 同屏自相矛盾",
+                    model.hits
+                );
+            }
+        }
+    }
+
+    // B 组：**没有搜索词**。只有「桶真的在当前分类里」时才有这条承诺；桶是过期值时列表空是
+    // 正确行为（真正要防的是「选中项不在桶列表里」的幽灵态，那由 `rebuild_after_query` 的校验
+    // 与 `a_stale_bucket_choice_cannot_hide_the_hits` 两条一起管）。
+    for category in Category::ALL {
+        let state = state_with(three_buckets(), "");
+        let model = Download::from_snapshot(
+            &state,
+            category,
+            &InstallDraft::default(),
+            Lang::En.catalog(),
+        );
+        for bucket in model
+            .buckets
+            .iter()
+            .filter_map(|bucket| bucket.key.as_deref())
+        {
+            let mut filtered = Download::from_snapshot(
+                &state,
+                category,
+                &InstallDraft::default(),
+                Lang::En.catalog(),
+            );
+            filtered.selected_major = Some(bucket.to_string());
+            assert!(
+                !rows::visible(&filtered).is_empty(),
+                "分类 {category:?} / 真实桶 {bucket:?}：画出来的桶点下去居然是空列表"
+            );
+        }
+    }
+}
+
+/// 一个**过期的桶选择**（模型里有个桶列表里不存在的 key）也挡不住搜索命中。
+///
+/// 这种 key 正常路径上不会出现（`rebuild_after_query` 会校验、点选只可能点到真实桶），但它是
+/// 「幽灵选中」的极端形态：搜索结果必须仍然可见，否则用户会看着「N 个命中 + 空列表」。
+#[test]
+fn a_stale_bucket_choice_cannot_hide_the_hits() {
+    let state = state_with(three_buckets(), "1.20");
+    let mut model = Download::from_snapshot(
+        &state,
+        Category::All,
+        &InstallDraft::default(),
+        Lang::En.catalog(),
+    );
+    model.selected_major = Some("9.99".to_string());
+
+    assert_eq!(model.hits, 2);
+    assert_eq!(rows::visible(&model).len(), 2, "搜索期间过期桶不生效");
+    assert_ne!(
+        group::active_bucket(&model),
+        Some("9.99"),
+        "过期桶不许成为生效值"
+    );
+}
+
+/// 搜索期间第二级桶**放宽到「全部」**（`active_bucket` = None），清空后原来的桶回来。
+///
+/// 抓得住：有人「修好」一致性的办法是把 `selected_major` 一起清掉（那会让用户的桶选择丢失，
+/// 清空搜索后回不到原位）。
+#[test]
+fn searching_relaxes_the_bucket_without_losing_the_choice() {
+    let state = state_with(three_buckets(), "1.20");
+    let mut model = Download::from_snapshot(
+        &state,
+        Category::All,
+        &InstallDraft::default(),
+        Lang::En.catalog(),
+    );
+    model.selected_major = Some("1.21".to_string());
+
+    assert!(model.has_query());
+    assert_eq!(
+        model.selected_major.as_deref(),
+        Some("1.21"),
+        "选择本身留着"
+    );
+    assert_eq!(
+        group::active_bucket(&model),
+        None,
+        "搜索期间生效值是「全部」"
+    );
+    assert_eq!(rows::visible(&model).len(), 2, "两个 1.20 的行都看得见");
+    assert!(group::bucket_selected(&model, None), "侧栏点亮「全部版本」");
+
+    // 清空搜索：生效值回到用户原来选的那个桶，而它还在（buckets 由全量行聚合）
+    let state = state_with(three_buckets(), "");
+    let mut model = Download::from_snapshot(
+        &state,
+        Category::All,
+        &InstallDraft::default(),
+        Lang::En.catalog(),
+    );
+    model.selected_major = Some("1.21".to_string());
+    assert_eq!(group::active_bucket(&model), Some("1.21"));
+    assert_eq!(rows::visible(&model).len(), 2, "1.21 桶里两个正式版");
+}
+
+/// 没有搜索词时第二级桶照常过滤（这条不许被「放宽」误伤）。
+#[test]
+fn without_a_query_the_bucket_still_filters() {
+    let state = state_with(three_buckets(), "");
+    let mut model = Download::from_snapshot(
+        &state,
+        Category::All,
+        &InstallDraft::default(),
+        Lang::En.catalog(),
+    );
+    model.selected_major = Some("1.20".to_string());
+
+    assert_eq!(rows::visible(&model).len(), 2);
+    assert!(!group::bucket_selected(&model, None), "「全部」不点亮");
+    assert!(group::bucket_selected(&model, Some("1.20")));
+}
+
+/// 复数口径：`1` 走单数 key，`>1` 走复数 key（复审 P2-4）。
+///
+/// 抓得住：把 `hits_text` 的 `count == 1` 分支删掉（英文重新变成「1 matches」）。
+/// 抓不住：中文的「个」是否自然（中文两边同形，由译审看）。
+#[test]
+fn the_search_counts_are_pluralised() {
+    let en = Lang::En.catalog();
+    let zh = Lang::ZhCn.catalog();
+
+    assert_eq!(rows::hits_text(en, 1), "1 match");
+    assert_eq!(rows::hits_text(en, 2), "2 matches");
+    assert_eq!(rows::hits_text(en, 0), "0 matches");
+    assert_eq!(rows::hits_text(zh, 1), "1 个匹配");
+
+    assert_eq!(
+        rows::elsewhere_text(en, 1),
+        "1 version matches, but it is in another type."
+    );
+    assert_eq!(
+        rows::elsewhere_text(en, 3),
+        "3 versions match, but they are in another type."
+    );
+    assert_eq!(
+        rows::elsewhere_text(zh, 1),
+        "有 1 个版本匹配，但它在别的类型里。"
+    );
+    assert_ne!(
+        rows::elsewhere_text(zh, 1),
+        rows::elsewhere_text(zh, 3),
+        "中文也在两套 key 之间切换（不是硬编码同一个串）"
+    );
+}
diff --git a/crates/app-iced/src/pages/download/tests/view.rs b/crates/app-iced/src/pages/download/tests/view.rs
new file mode 100644
index 0000000..e0e5c3e
--- /dev/null
+++ b/crates/app-iced/src/pages/download/tests/view.rs
@@ -0,0 +1,147 @@
+//! 控件树那一节：九个状态 × 四档宽度都要能构图（M105/M107 合流后 `tests.rs` 到 433 行，
+//! 按 AGENTS.md §3-1 拆出来）。
+//!
+//! 只测「能构建出树」——**抓不住**画出来长什么样（像素由 `DevDocs/artifacts/m107/` 的图负责）。
+
+use unlucky_i18n::Lang;
+use unlucky_presenter::dto::{InstallProgressView, InstallStage, VersionKind};
+
+use crate::pages::download::model::{Download, InstallView, VersionRow};
+use crate::pages::download::{view, Category, Message};
+use crate::pages::layout::{frame_metrics, PaneKit};
+
+use super::{ui, version};
+
+/// 九个状态都能构建出控件树，且四档宽度都能构建（不 panic、消息类型对得上）。
+///
+/// 抓得住：某个状态分支漏了返回值、或消息类型接错（编译期就红）；空态/加载态忘了给内容。
+/// 抓不住：**画出来长什么样**——像素由 `DevDocs/artifacts/m107/` 的图负责。
+#[test]
+fn every_state_builds_a_tree_at_every_width() {
+    let ui = ui();
+    let catalog = Lang::En.catalog();
+
+    let loading = Download::loading();
+    let empty = Download {
+        loaded: true,
+        ..Download::loading()
+    };
+    let ready = Download {
+        options: None,
+        rows: vec![VersionRow::of(
+            &version("1.21.9", VersionKind::Release, false),
+            catalog,
+        )],
+        category: Category::Release,
+        selected: Some("1.21.9".to_string()),
+        install: None,
+        loaded: true,
+        // M107 的五个新字段：桶 / 查询 / 命中数 / 第二级选中 / 折叠态
+        ..Download::default()
+    };
+
+    let installing = Download {
+        install: Some(InstallView::of(
+            &InstallProgressView {
+                version: "1.21.9".to_string(),
+                stage: InstallStage::Downloading,
+                files_done: 128,
+                files_total: 512,
+                ..InstallProgressView::new()
+            },
+            catalog,
+        )),
+        ..ready.clone()
+    };
+
+    let failed = Download {
+        install: Some(InstallView::of(
+            &InstallProgressView {
+                version: "1.21.9".to_string(),
+                stage: InstallStage::Failed,
+                ..InstallProgressView::new()
+            },
+            catalog,
+        )),
+        ..ready.clone()
+    };
+
+    // M107：搜索 / 第二级选中 / 搜不到 / 手动折叠四个新增状态的取样
+    let searching = Download {
+        query: "1.21".to_string(),
+        hits: 1,
+        ..ready.clone()
+    };
+    let majored = Download {
+        selected_major: Some("1.21".to_string()),
+        ..ready.clone()
+    };
+    let no_match = Download {
+        query: "zzz".to_string(),
+        hits: 0,
+        ..ready.clone()
+    };
+    let folded = Download {
+        type_rail_folded: true,
+        ..ready.clone()
+    };
+
+    // 四档宽度：1180 / 1024（Wide 门槛）/ 900（Narrow）/ 700（Chips）
+    for width in [1180.0, 1024.0, 900.0, 700.0] {
+        let metrics = frame_metrics(PaneKit::Single, width);
+        for model in [
+            loading.clone(),
+            empty.clone(),
+            ready.clone(),
+            installing.clone(),
+            failed.clone(),
+            searching.clone(),
+            majored.clone(),
+            no_match.clone(),
+            folded.clone(),
+        ] {
+            let _: iced::Element<'_, Message> = view(&ui, metrics, &model, Lang::En);
+        }
+    }
+}
+
+/// 安装失败的模型：可读文案 + 出口都有（不静默）。
+#[test]
+fn a_failed_install_stays_visible() {
+    let model = InstallView::of(
+        &InstallProgressView {
+            version: "1.21.9".to_string(),
+            stage: InstallStage::Failed,
+            ..InstallProgressView::new()
+        },
+        Lang::En.catalog(),
+    );
+    assert!(model.failed());
+    assert!(model.terminal());
+    assert!(!model.running(), "失败之后不再给「取消安装」");
+    assert_eq!(model.stage_label, "Install failed");
+}
+
+/// 演示数据自己也得守规矩（它是出图的基线）：八行、四个主版本桶、英文目录下不出现中文类型词。
+#[test]
+fn the_demo_data_is_sane() {
+    let catalog = Lang::En.catalog();
+    let demo = crate::pages::download::demo(catalog);
+    assert!(demo.loaded);
+    assert_eq!(demo.rows.len(), 8);
+    assert_eq!(demo.category, Category::All, "混合列表没有单个分类该亮");
+    assert!(demo.query.is_empty(), "缺省演示没有搜索词");
+    assert_eq!(
+        demo.buckets
+            .iter()
+            .map(|bucket| bucket.key.as_deref())
+            .collect::<Vec<_>>(),
+        vec![Some("24w"), Some("1.21"), Some("1.20"), None],
+        "第二级侧栏的桶顺序与内容"
+    );
+    assert!(demo
+        .rows
+        .iter()
+        .all(|row| row.supporting.contains("released")));
+    assert!(demo.rows.iter().all(|row| !row.supporting.contains('版')));
+}
diff --git a/crates/app-iced/src/pages/frame.rs b/crates/app-iced/src/pages/frame.rs
new file mode 100644
index 0000000..e78c3c2
--- /dev/null
+++ b/crates/app-iced/src/pages/frame.rs
@@ -0,0 +1,252 @@
+//! 页面骨架：**页头**（标题 + 副标题 + 可选操作区）+ **内容区**（列宽由 [`super::layout`] 决定）
+//! + **空态位**。
+//!
+//! ## 边界
+//!
+//! 这里只放「页面级」的东西：页头、页边距、内容块、两列骨架、空态位的摆放。
+//! 具体控件（卡片 / 分隔线 / 文本按钮 / 图标）在 [`pieces`]，它们是**占位实现**
+//! （同一份令牌，没有完整状态机），等 M75 的 `components/` 家族合入后由另一条 mission 换掉。
+//!
+//! ## 对齐口径（M102）：页头标题左缘 = 正文块左缘
+//!
+//! 页头带与内容区共用同一个 `gutter`（`Padding::from([0.0, metrics.gutter])` / `padding(gutter)`），
+//! 所以页头标题的左缘 = `rail 88 + gutter 24 = 112`。正文块必须从**同一条线**起：
+//!
+//! - 单列页用 [`body`]（贴左 + 宽 `layout::block::body_width` = pane 宽，封顶 1440）；
+//! - 成段散文再套一层 [`prose`]（宽 `layout::block::prose_width` ≤424，保证一行 ≤72 字符）；
+//! - 两列页的正文在 [`panes`] 的主列里，左缘 = `112 + 列表列 336 + 间隙 24 = 472`（有据的分栏，不是错位）。
+//!
+//! 旧 [`single_column`] 把 424 的块**居中**摆进 1044，于是左缘 422、标题 112——视觉复审的 ① 就是这个。
+//! 它保留给设置页（`pages/settings/**`，几何归设置页线）。
+//!
+//! **这三个量都在 [`super::layout::block`]（纯函数 + 单测）**；[`body`] / [`prose`] 只是把
+//! 「从哪个数建盒」写死在一处，`pages/tests.rs` 有两条**源码结构断言**盯着这两个盒子
+//! （iced 的 Element 没有几何内省，量不到摆法，只能断言「照哪个数建的」）。
+//!
+//! ## 判据落点（`research/12b`）
+//!
+//! | 部件 | 参考 | 落点 |
+//! |---|---|---|
+//! | 页头 | 16.1 AppBar 高 56（登记偏离官方 64）/ 两行 84 | `LayoutMetrics::header_height` |
+//! | 页头标题 | 16.4 `TitleLarge 22/28` | `Component::TopAppBar.spec().text` |
+//! | 页头副标题 | 16.4 `LabelMedium 12/16` `OnSurfaceVariant` | 同上 `.support` |
+//! | 空态 | 15.1 图标块 96×96 / `Large(16)`；15.2 标题 `HeadlineSmall 24`；15.3 副文案 `BodySmall 12` | `Component::EmptyState` |
+
+mod pieces;
+
+#[cfg(test)]
+mod tests;
+
+pub use pieces::{
+    card, divider, empty_state, filled, gap, glyph, glyph_box, scroll_style, text_action,
+    text_role, text_role_centered, text_role_owned, ICON_PX, ICON_SMALL_PX, SCROLLBAR_MARGIN,
+    SCROLLBAR_WIDTH,
+};
+
+use iced::widget::{column, container, row};
+use iced::{Alignment, Element, Length, Padding};
+
+use unlucky_design::color::Role;
+use unlucky_design::component_map::Component;
+use unlucky_design::elevation::MaterialLayer;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use crate::theme::Ui;
+
+use super::layout::{self, block, FrameMetrics};
+use super::Message;
+
+/// 页头操作区之间的间隔（`Space::X2`）。
+const HEADER_ACTION_GAP: f32 = Space::X2.dp();
+
+/// 页头内容。
+pub struct Header<'a> {
+    /// 标题（`TitleLarge`）。
+    pub title: &'a str,
+    /// 副标题（`LabelMedium`，给了页头就是两行高）。
+    pub subtitle: Option<&'a str>,
+    /// 右侧操作区（text button 占位，数量 ≤3）。
+    pub actions: Vec<Element<'a, Message>>,
+}
+
+impl<'a> Header<'a> {
+    /// 单行页头。
+    pub fn new(title: &'a str) -> Self {
+        Self {
+            title,
+            subtitle: None,
+            actions: Vec::new(),
+        }
+    }
+
+    /// 加副标题（页头自动变两行高）。
+    #[must_use]
+    pub fn subtitle(mut self, subtitle: &'a str) -> Self {
+        self.subtitle = Some(subtitle);
+        self
+    }
+
+    /// 追加一个右侧操作。
+    #[must_use]
+    pub fn action(mut self, action: Element<'a, Message>) -> Self {
+        self.actions.push(action);
+        self
+    }
+}
+
+/// 一整页：页头 + 内容区（页边距已由布局系统决定）。
+pub fn page<'a>(
+    ui: &'a Ui,
+    metrics: FrameMetrics,
+    header: Header<'a>,
+    body: impl Into<Element<'a, Message>>,
+) -> Element<'a, Message> {
+    let bar = header_bar(ui, metrics, header);
+    let content = container(body)
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .padding(metrics.gutter);
+
+    column![bar, content]
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .into()
+}
+
+fn header_bar<'a>(ui: &'a Ui, metrics: FrameMetrics, header: Header<'a>) -> Element<'a, Message> {
+    let spec = Component::TopAppBar.spec();
+    // 16.4：标题 TitleLarge（emphasized w500），副标题 LabelMedium + OnSurfaceVariant
+    let mut titles = column![text_role(
+        ui,
+        spec.text,
+        true,
+        header.title,
+        ui.color(Role::OnSurface)
+    )]
+    .spacing(ui.space(Space::X1));
+    if let Some(subtitle) = header.subtitle {
+        titles = titles.push(text_role(
+            ui,
+            spec.support.unwrap_or(TypeRole::LabelMedium),
+            false,
+            subtitle,
+            ui.color(Role::OnSurfaceVariant),
+        ));
+    }
+
+    let actions = row(header.actions)
+        .spacing(HEADER_ACTION_GAP)
+        .align_y(Alignment::Center);
+
+    // 页头带也要有面板底色（M93）：否则「开背景图 + 面板 α<1」时标题/副标题直接压在图上，
+    // 浅色主题的副标题（OnSurfaceVariant）对比度掉得厉害。底色同源于 `Ui::layer`（含面板 α）。
+    container(
+        row![titles.width(Length::Fill), actions]
+            .width(Length::Fill)
+            .align_y(Alignment::Center),
+    )
+    .width(Length::Fill)
+    .height(ui.metrics().header_height(header.subtitle.is_some()))
+    .align_y(Alignment::Center)
+    .padding(Padding::from([0.0, metrics.gutter]))
+    .style(move |_theme| filled(ui.layer(MaterialLayer::Canvas)))
+    .into()
+}
+
+/// 单列版面的正文列：宽 = 行宽上限内的实际列宽，**水平居中**。
+///
+/// > **M102 起产品页不再用它**：居中会把 424 摆到 1044 的正中（左缘 422 对页头标题 112），
+/// > 视觉复审判为「内容缩在中间一条窄栏」。设置页（`pages/settings/**`）仍走这条，
+/// > 它的几何归设置页线，本 mission 不动；下载 / 日志 / 窄窗实例改用 [`body`]。
+pub fn single_column<'a>(
+    metrics: FrameMetrics,
+    content: impl Into<Element<'a, Message>>,
+) -> Element<'a, Message> {
+    centered(metrics.column, content)
+}
+
+/// **页面块宽度**：pane 宽（单列 = 可用宽度 / 两列 = 主列 pane）封顶 1440。
+///
+/// 真源在 [`super::layout::block::body_width`]（纯量 + 单测）；这里只是转发，**不另算一份**。
+/// 与 [`FrameMetrics::column`]（一句话多宽，≤424）是两个量。
+pub use super::layout::block::body_width;
+
+/// **正文块**：从页边距起（= 页头标题那条左缘）、宽 [`body_width`]、左内边距 [`body_offset`]。
+///
+/// 盒子**从纯量建**：宽度取 [`body_width`]、左内边距取 [`super::layout::block::body_offset`]
+/// （恒 0）、对齐 `Start`。这三件事的顺序就是契约，`pages/tests.rs` 的
+/// `frame_body_is_built_from_the_block_quantities` 逐条扫这段源码（iced 的 Element 没有几何
+/// 内省，量不到「摆在哪」，只能断言「照哪个数建的」）。
+pub fn body<'a>(
+    metrics: FrameMetrics,
+    content: impl Into<Element<'a, Message>>,
+) -> Element<'a, Message> {
+    container(content)
+        .width(Length::Fixed(body_width(metrics)))
+        .height(Length::Fill)
+        .align_x(Alignment::Start)
+        .align_y(Alignment::Start)
+        .padding(Padding::default().left(block::body_offset(metrics)))
+        .into()
+}
+
+/// **散文块**：宽度锁在 [`super::layout::block::prose_width`]（= `metrics.column`，≤424 ⇒ 一行 ≤72 字符）。
+///
+/// 只包「成段读的文字」（实例详情正文那样的 prose）；卡片、列表、Tabs 吃的是 [`body_width`]，
+/// 它们的宽度不承担行宽承诺（列宽只影响每行放几个字段，不影响读一句话的舒适度）。
+pub fn prose<'a>(
+    metrics: FrameMetrics,
+    content: impl Into<Element<'a, Message>>,
+) -> Element<'a, Message> {
+    container(content)
+        .width(Length::Fixed(block::prose_width(metrics)))
+        .into()
+}
+
+/// 两列版面：左列 `secondary`（独立滚动区由调用方自己加 `scrollable`）+ 右列 `main`。
+///
+/// 两列都**显式**取布局系统给的宽度，不吃 Fill：列表列必须固定 336，
+/// 详情列必须窄于可用宽度，否则又回到「全宽单卡」。
+pub fn panes<'a>(
+    metrics: FrameMetrics,
+    secondary: impl Into<Element<'a, Message>>,
+    main: impl Into<Element<'a, Message>>,
+) -> Element<'a, Message> {
+    let width = metrics.secondary.unwrap_or(0.0);
+    row![
+        container(secondary)
+            .width(Length::Fixed(width))
+            .height(Length::Fill),
+        container(main)
+            .width(Length::Fixed(metrics.main_pane))
+            .height(Length::Fill),
+    ]
+    .spacing(layout::PANES_GAP)
+    .width(Length::Fill)
+    .height(Length::Fill)
+    .into()
+}
+
+/// 把内容塞进固定宽度并水平居中（`align_x` 不会覆盖子元素的宽度，见 Q8）。
+pub fn centered<'a>(width: f32, content: impl Into<Element<'a, Message>>) -> Element<'a, Message> {
+    container(container(content).width(Length::Fixed(width)))
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .align_x(Alignment::Center)
+        .align_y(Alignment::Start)
+        .into()
+}
+
+/// 与 [`centered`] 同宽，但**贴左**：列表右侧的详情列要贴着自己的 pane 左边，不再二次居中。
+pub fn left_aligned<'a>(
+    width: f32,
+    content: impl Into<Element<'a, Message>>,
+) -> Element<'a, Message> {
+    container(container(content).width(Length::Fixed(width)))
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .align_x(Alignment::Start)
+        .align_y(Alignment::Start)
+        .into()
+}
diff --git a/crates/app-iced/src/pages/frame/pieces.rs b/crates/app-iced/src/pages/frame/pieces.rs
new file mode 100644
index 0000000..1a6b0f0
--- /dev/null
+++ b/crates/app-iced/src/pages/frame/pieces.rs
@@ -0,0 +1,333 @@
+//! 页面用的**占位控件**：卡片 / 分隔线 / 空态 / 文本按钮 / 图标 / 容器样式。
+//!
+//! 全部走令牌（颜色、圆角、排版、间距、一像素线），但**没有完整状态机**——
+//! 这些是给页面骨架站稳版式用的临时件，M74/M75 的 `components/` 家族合入后由另一条 mission 替换。
+//! 每个函数都在文档里点明它对应哪个组件的档位（12b 的参考值）。
+
+use iced::widget::text::LineHeight;
+use iced::widget::{button, column, container, row, rule, scrollable, space, svg};
+use iced::Theme as IcedTheme;
+use iced::{Alignment, Background, Border, Color, Element, Length, Padding, Pixels, Shadow};
+
+use unlucky_design::color::{Role, StateLayer};
+use unlucky_design::component_map::Component;
+use unlucky_design::elevation::MaterialLayer;
+use unlucky_design::icons::{IconKind, IconPaint};
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::{TypeRole, TypeStyle};
+
+use crate::icons;
+use crate::pages::{Action, Message};
+use crate::theme::Ui;
+
+/// 空态图标块边长（12b 15.1：96×96，圆角 `Large`）。
+pub(super) const EMPTY_ICON_BLOCK: f32 = 96.0;
+/// 空态字形渲染尺寸（12b 15.1：图标 32~48 `[估]`，取 40）。
+pub(super) const EMPTY_ICON_GLYPH: f32 = 40.0;
+/// 滚动条轨宽（视觉复审 P2-2：原来用 iced 默认的 10px，压过了列表内容）。
+///
+/// 取 6：细到不抢视线，又还在命中/可见的下限之上；滑块做成 full 圆角药丸（半径 3）。
+pub const SCROLLBAR_WIDTH: f32 = 6.0;
+/// 滑块离卡片内边的留白（2px，避免贴边）。
+pub const SCROLLBAR_MARGIN: f32 = 2.0;
+
+/// 描边卡片（占位：M75 的 `components` 会提供真正的 `OutlinedCard`）。
+pub fn card<'a>(ui: &'a Ui, content: impl Into<Element<'a, Message>>) -> Element<'a, Message> {
+    let spec = Component::OutlinedCard.spec();
+    container(content)
+        .width(Length::Fill)
+        .padding(ui.metrics().card_padding)
+        .style(move |_theme| container::Style {
+            background: Some(Background::Color(ui.layer(MaterialLayer::Card))),
+            border: ui.outlined(spec.shape),
+            ..container::Style::default()
+        })
+        .into()
+}
+
+/// 一像素分隔线（`OutlineVariant`，厚度取令牌）。
+pub fn divider<'a>(ui: &'a Ui) -> Element<'a, Message> {
+    rule::horizontal::<IcedTheme>(ui.metrics().divider_thickness)
+        .style(move |_theme| rule::Style {
+            color: ui.color(Role::OutlineVariant),
+            radius: ui.radius_dp(ShapeScale::None),
+            fill_mode: rule::FillMode::Full,
+            snap: true,
+        })
+        .into()
+}
+
+/// 空态（12b §15）：图标块 96 + 24 标题 + 12 副文案 + ≤3 个快捷入口，**整块垂直居中**。
+pub fn empty_state<'a>(
+    ui: &'a Ui,
+    icon: IconKind,
+    title: &'a str,
+    body: &'a str,
+    actions: Vec<Element<'a, Message>>,
+) -> Element<'a, Message> {
+    let spec = Component::EmptyState.spec();
+
+    let block = container(glyph(
+        icon,
+        ui.color(Role::OnSurfaceVariant),
+        EMPTY_ICON_GLYPH,
+    ))
+    .width(EMPTY_ICON_BLOCK)
+    .height(EMPTY_ICON_BLOCK)
+    .align_x(Alignment::Center)
+    .align_y(Alignment::Center)
+    .style(move |_theme| container::Style {
+        background: Some(Background::Color(ui.layer(MaterialLayer::Overlay))),
+        border: Border {
+            radius: ui.radius_dp(spec.shape),
+            ..Border::default()
+        },
+        ..container::Style::default()
+    });
+
+    let mut stack = column![
+        block,
+        text_role_centered(ui, spec.text, false, title, ui.color(Role::OnSurface)),
+        text_role_centered(
+            ui,
+            spec.support.unwrap_or(TypeRole::BodySmall),
+            false,
+            body,
+            ui.color(Role::OnSurfaceVariant),
+        ),
+    ]
+    .spacing(ui.space(Space::X3))
+    .align_x(Alignment::Center);
+
+    if !actions.is_empty() {
+        stack = stack.push(
+            row(actions)
+                .spacing(ui.space(Space::X2))
+                .align_y(Alignment::Center),
+        );
+    }
+
+    container(stack)
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .align_x(Alignment::Center)
+        .align_y(Alignment::Center)
+        .into()
+}
+
+/// 文本按钮占位（TextButton 档：透明底、`OnSurfaceVariant`、40 高、full 圆角）。
+///
+/// 只画静息、hover、pressed 三态（focus/disabled 归 M75 的 `interaction.rs`）；
+/// 消息是页面自己的 [`Message::Action`]，与 app 的 `Message` 完全解耦。
+pub fn text_action<'a>(ui: &'a Ui, label: &'a str, action: Action) -> Element<'a, Message> {
+    let spec = Component::TextButton.spec();
+    let height = ui.metrics().control_height;
+
+    let content = text_role(
+        ui,
+        spec.text,
+        false,
+        label,
+        ui.color(Role::OnSurfaceVariant),
+    );
+
+    button(container(content).align_y(Alignment::Center))
+        .height(height)
+        .padding(Padding::from([0.0, ui.space(Space::X4)]))
+        .style(move |_theme: &IcedTheme, status| {
+            let background = match status {
+                button::Status::Hovered => Some(Background::Color(ui.state_over(
+                    StateLayer::Hover,
+                    Role::OnSurface,
+                    Role::Surface,
+                ))),
+                button::Status::Pressed => Some(Background::Color(ui.state_over(
+                    StateLayer::Pressed,
+                    Role::OnSurface,
+                    Role::Surface,
+                ))),
+                button::Status::Active | button::Status::Disabled => None,
+            };
+
+            button::Style {
+                background,
+                text_color: ui.color(Role::OnSurfaceVariant),
+                border: Border {
+                    radius: ui.radius(ShapeScale::Full, height),
+                    ..Border::default()
+                },
+                shadow: Shadow::default(),
+                snap: true,
+            }
+        })
+        .on_press(Message::Action(action))
+        .into()
+}
+
+/// 令牌排版档 → 文字元素（字号 / 行高 / 字重全来自令牌，不写字面量）。
+pub fn text_role<'a>(
+    ui: &'a Ui,
+    role: TypeRole,
+    emphasized: bool,
+    content: &'a str,
+    color: Color,
+) -> Element<'a, Message> {
+    text_widget(ui, role, emphasized, content, color).into()
+}
+
+/// 同 [`text_role`]，但文案是**拥有的**字符串（计数、时间戳这类运行时格式化出来的短串）。
+///
+/// 为什么需要它：文字控件**借用**它的内容（`&'a str`），所以 `format!` 出来的临时串不能直接进树；
+/// iced 的 `text()` 接受 `String`（`IntoFragment` 为 `String` 实现了 owned 分支），这里把
+/// 「令牌化 + owned 内容」两件事合成一处，页面就不必为了一个计数往视图模型里塞字段。
+pub fn text_role_owned<'a>(
+    ui: &Ui,
+    role: TypeRole,
+    emphasized: bool,
+    content: String,
+    color: Color,
+) -> Element<'a, Message> {
+    let style: TypeStyle = if emphasized {
+        ui.emphasized(role)
+    } else {
+        ui.style(role)
+    };
+
+    iced::widget::text(content)
+        .size(style.size_px)
+        .line_height(LineHeight::Absolute(Pixels(style.line_height_px)))
+        .font(ui.font_of(style))
+        .color(color)
+        .into()
+}
+
+/// 同 [`text_role`]，但**文字自身居中**（空态的标题与副文案：图标块是居中锚点）。
+pub fn text_role_centered<'a>(
+    ui: &'a Ui,
+    role: TypeRole,
+    emphasized: bool,
+    content: &'a str,
+    color: Color,
+) -> Element<'a, Message> {
+    text_widget(ui, role, emphasized, content, color)
+        .align_x(iced::widget::text::Alignment::Center)
+        .into()
+}
+
+fn text_widget<'a>(
+    ui: &'a Ui,
+    role: TypeRole,
+    emphasized: bool,
+    content: &'a str,
+    color: Color,
+) -> iced::widget::Text<'a> {
+    let style: TypeStyle = if emphasized {
+        ui.emphasized(role)
+    } else {
+        ui.style(role)
+    };
+
+    iced::widget::text(content)
+        .size(style.size_px)
+        .line_height(LineHeight::Absolute(Pixels(style.line_height_px)))
+        .font(ui.font_of(style))
+        .color(color)
+}
+
+/// 任意尺寸的令牌图标（`icons::RENDER_PX` 只有 24 一档；空态图标要 40）。
+///
+/// ## 图标语汇（视觉复审 P2-3）
+///
+/// 令牌里 **`Play` / `Stop` / `More` 是填充字形**，其余全是描边。页面骨架里**只用描边图标**：
+/// 同屏把填充字形和描边字形混在一起，线宽语汇会打架（复审的原话是「Play 是填充字形，
+/// 同屏其它图标是描边」）。真要做「主操作允许实心图标」这条例外，应当由组件线在
+/// `components/` 里统一定义并只保留一处，而不是散落在页面里——所以这里干脆一个都不放。
+/// 守门：`tests/no_hardcoded_tokens.rs` 的 `pages_use_only_stroked_icons`。
+///
+/// 描边宽度仍按令牌的 `Icon::stroke_width(render_px)` 折算，所以视觉线宽在任何尺寸下都是 1.5。
+pub fn glyph(kind: IconKind, color: Color, render_px: f32) -> Element<'static, Message> {
+    let icon = kind.icon();
+    let paint = match icon.paint {
+        IconPaint::Stroke => format!(
+            "fill=\"none\" stroke=\"currentColor\" stroke-width=\"{}\" \
+             stroke-linecap=\"round\" stroke-linejoin=\"round\"",
+            icon.stroke_width(render_px)
+        ),
+        IconPaint::Fill => "fill=\"currentColor\" stroke=\"none\"".to_owned(),
+    };
+
+    let source = format!(
+        "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"{0}\" height=\"{0}\" \
+         viewBox=\"0 0 24 24\"><path d=\"{1}\" {paint}/></svg>",
+        render_px, icon.path
+    );
+
+    svg(svg::Handle::from_memory(source.into_bytes()))
+        .width(render_px)
+        .height(render_px)
+        .style(move |_theme, _status| svg::Style { color: Some(color) })
+        .into()
+}
+
+/// 固定宽 × 固定高的图标容器（Q9：按钮给的 Fill 约束会撑大字形，必须中间夹一层）。
+pub fn glyph_box(kind: IconKind, color: Color, px: f32) -> Element<'static, Message> {
+    container(glyph(kind, color, px))
+        .width(px)
+        .height(px)
+        .align_x(Alignment::Center)
+        .align_y(Alignment::Center)
+        .into()
+}
+
+/// 竖直留白（布局拼装用；值来自令牌栅格）。
+pub fn gap<'a>(px: f32) -> Element<'a, Message> {
+    space::vertical().height(px).into()
+}
+
+/// 纯色容器样式（页面底色 / 留白带）。
+pub fn filled(color: Color) -> container::Style {
+    container::Style {
+        background: Some(Background::Color(color)),
+        ..container::Style::default()
+    }
+}
+
+/// 滚动条配色（令牌角色）：轨道透明、滑块 `OutlineVariant`（低对比，弱于正文），
+/// 轨宽 `SCROLLBAR_WIDTH`（6px）+ `SCROLLBAR_MARGIN`（2px 内缩）——视觉 r1 P2-2 的修法。
+///
+/// 只在**独立滚动区**上挂（实例页列表列），不许挂到整页上——整页滚动会把页头一起滚走。
+pub fn scroll_style(ui: &Ui) -> impl Fn(&IcedTheme, scrollable::Status) -> scrollable::Style + '_ {
+    let rail = scrollable::Rail {
+        background: None,
+        border: Border::default(),
+        scroller: scrollable::Scroller {
+            // 低对比：用 `OutlineVariant`（比 `Outline` 弱一档的容器描边角色）而不是 `Outline`，
+            // 让滑块明显弱于正文；纯色不透明，CPU/GPU 两档一致。
+            background: Background::Color(ui.color(Role::OutlineVariant)),
+            border: Border {
+                radius: ui.radius(ShapeScale::Full, SCROLLBAR_WIDTH),
+                ..Border::default()
+            },
+        },
+    };
+
+    move |_theme, _status| scrollable::Style {
+        container: container::Style::default(),
+        vertical_rail: rail,
+        horizontal_rail: rail,
+        gap: None,
+        auto_scroll: scrollable::AutoScroll {
+            background: Background::Color(ui.color(Role::SurfaceContainerHigh)),
+            border: Border::default(),
+            shadow: Shadow::default(),
+            icon: ui.color(Role::OnSurfaceVariant),
+        },
+    }
+}
+
+/// `crate::icons::RENDER_PX` 的再导出（页面里 24px 图标走这个常量，不写字面量）。
+pub const ICON_PX: f32 = icons::RENDER_PX;
+
+/// 小号图标（行尾 chevron 之类的辅助指示，16px）。
+pub const ICON_SMALL_PX: f32 = 16.0;
diff --git a/crates/app-iced/src/pages/frame/tests.rs b/crates/app-iced/src/pages/frame/tests.rs
new file mode 100644
index 0000000..4f9689e
--- /dev/null
+++ b/crates/app-iced/src/pages/frame/tests.rs
@@ -0,0 +1,101 @@
+//! `frame` 的断言：空态 / 卡片 / 页头规格与一屏字号档。
+use super::pieces::{EMPTY_ICON_BLOCK, EMPTY_ICON_GLYPH};
+use super::*;
+
+use unlucky_design::color::SchemeFlavor;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::typography::Platform;
+
+use crate::pages::layout::{frame_metrics, PaneKit};
+use crate::theme::Families;
+
+fn ui() -> Ui {
+    Ui::with_platform(
+        SchemeFlavor::Light,
+        Platform::Windows,
+        Families {
+            text: "Segoe UI",
+            display: "Segoe UI",
+            mono: "Consolas",
+        },
+    )
+}
+
+#[test]
+fn empty_state_follows_the_12b_reference() {
+    // 15.1 图标块 96×96、圆角 Large(16)；15.2 标题 HeadlineSmall；15.3 副文案 BodySmall
+    let spec = Component::EmptyState.spec();
+    assert_eq!(EMPTY_ICON_BLOCK, 96.0);
+    assert_eq!(spec.shape, ShapeScale::Large);
+    assert_eq!(spec.text, TypeRole::HeadlineSmall);
+    assert_eq!(ui().style(spec.text).size_px, 24.0);
+    assert_eq!(spec.support, Some(TypeRole::BodySmall));
+    assert_eq!(ui().style(TypeRole::BodySmall).size_px, 12.0);
+    // 字形 32~48（[估]）
+    assert!((32.0..=48.0).contains(&EMPTY_ICON_GLYPH));
+    const { assert!(EMPTY_ICON_GLYPH < EMPTY_ICON_BLOCK) };
+}
+
+#[test]
+fn card_uses_the_outlined_card_spec() {
+    let spec = Component::OutlinedCard.spec();
+    assert_eq!(spec.shape, ShapeScale::Medium);
+    assert_eq!(ui().radius_dp(spec.shape).top_left, 12.0);
+    assert_eq!(spec.text, TypeRole::TitleMedium);
+    assert_eq!(spec.support, Some(TypeRole::BodySmall));
+}
+
+#[test]
+fn page_header_uses_the_two_documented_heights() {
+    let ui = ui();
+    assert_eq!(ui.metrics().header_height(false), 56.0);
+    assert_eq!(ui.metrics().header_height(true), 84.0);
+}
+
+/// 一屏字号 ≤4 档（rubric D4）。规格表来源：12b §16.4 / §15 / 3.x OutlinedCard。
+#[test]
+fn every_screen_keeps_at_most_four_text_sizes() {
+    let ui = ui();
+
+    let header = ui.emphasized(Component::TopAppBar.spec().text).size_px;
+    let row_title = ui.style(Component::ListItem.spec().text).size_px;
+    let row_support = ui
+        .style(Component::ListItem.spec().support.unwrap())
+        .size_px;
+    let action = ui.style(Component::TextButton.spec().text).size_px;
+    let body = ui.style(TypeRole::BodyMedium).size_px;
+    let empty_title = ui.style(Component::EmptyState.spec().text).size_px;
+
+    let screens: [(&str, &[f32]); 3] = [
+        // 实例页（list-detail 与窄窗单列）：页头 + 行标题 + 行副文案 + 操作/正文
+        ("instances", &[header, row_title, row_support, action, body]),
+        // 设置页：页头 + 分组项/操作 + 行标签 + 行值 + 空态标题
+        (
+            "settings",
+            &[header, action, row_support, body, empty_title],
+        ),
+        // 下载 / 日志：页头 + 空态标题 + 空态副文案 + 操作
+        ("empty-pages", &[header, empty_title, row_support, action]),
+    ];
+
+    for (name, sizes) in screens {
+        let mut unique = sizes.to_vec();
+        unique.sort_by(f32::total_cmp);
+        unique.dedup();
+        assert!(
+            unique.len() <= 4,
+            "{name} 一屏用了 {} 档字号 {unique:?}，超过 rubric D4 的 4 档",
+            unique.len()
+        );
+        assert!(unique[0] >= 12.0, "{name} 出现小于 12px 的字号");
+        assert!(unique[unique.len() - 1] <= 24.0, "{name} 字号过大");
+    }
+}
+
+/// 版面几何是页面唯一宽度来源：两列版面的正文列必须窄于可用宽度。
+#[test]
+fn two_pane_body_is_narrower_than_the_available_width() {
+    let wide = frame_metrics(PaneKit::ListDetail, 1180.0);
+    assert!(wide.column < wide.available);
+    assert!(wide.secondary.is_some());
+}
diff --git a/crates/app-iced/src/pages/harness.rs b/crates/app-iced/src/pages/harness.rs
new file mode 100644
index 0000000..b97a376
--- /dev/null
+++ b/crates/app-iced/src/pages/harness.rs
@@ -0,0 +1,317 @@
+//! 截图 harness：把**一页**按给定窗口宽度 / 主题单独渲染并出图（`examples/pages_demo.rs` 的入口）。
+//!
+//! **刻意不接 `cli.rs`**：等 `cli.rs` 具备 `--screen` / `--window-width` 之后，这个 harness 应当
+//! 删掉，改由正式启动参数出图。参数：`--screen=instances|download|settings|logs`、`--width`、
+//! `--height`、`--theme` / `--screenshot-theme`（后者优先）、`--screenshot`、`--renderer`、
+//! `--software-renderer`、`--scale-factor`、`--appearance=real|demo`、`--passthrough=on|off`。
+//! 解析与默认值在 [`request`]（M100 拆出去：本文件当时正好 400 行、零余量）；没给 `--screenshot`
+//! 就只是开窗看。
+//!
+//! ## 取证密闭（M100）：取证图不许跟着系统指针变
+//!
+//! M99 复审实测过：同一个 exe 连跑 8 次，第 6 次给出**第三个 hash**，差异区是某个按钮被画成 Hovered
+//! ——根因是 harness 开真窗口，`button::Status` 由**系统光标位置**决定。
+//!
+//! 于是 `--screenshot` 有一条**通道级**钉死：开窗那一刻调 `window::enable_mouse_passthrough`
+//! （winit 的 `set_cursor_hittest(false)`）⇒ 窗口从此收不到指针事件 ⇒ 全树控件恒为 `Active`。
+//!
+//! ⚠️ **限定**：上句的因果链在**有指针输入的会话**里才被实测过。本机（RDP 断开）连
+//! `SetCursorPos` 都失败，所以「`指针事件=0`」在本环境里**既可能是穿透生效，也可能是根本没输入**。
+//! 要让 `指针事件=N` 变成密闭证据，必须同一 argv 再跑一次 `--passthrough=off` 做对照：
+//! 那一跑该给出 `N>0`（复审注入后实测 12）**并且** hash 与开穿透时不同。没有这个对照，
+//! `指针事件=0` 就退回成「没观测到输入」，而不能读成「输入被挡住了」。
+//!
+//! ### 证据怎么读（M100 r1 复审订正，优先级从高到低）
+//!
+//! 1. **`[caps] passthrough_ext=on|off|unknown`** ← 主证据。winit 0.30 在 Windows 把
+//!    `set_cursor_hittest(false)` 落成 `WS_EX_TRANSPARENT | WS_EX_LAYERED`，这一位可以从
+//!    `GWL_EXSTYLE` 读回来（[`caps`] → `platform::win32::transparency::click_through`）。
+//!    复审探针实测：`--screenshot` 默认 176/214 次采样命中、`--passthrough=off` **0/320**、
+//!    产品 bin **0/535**。三态里的 `unknown` 是「没读到」，**不许**读成 `off`。
+//! 2. `指针事件=N`：**辅助**指标。它证明「鼠标消息到没到」，**不**证明「像素会不会变」
+//!    （复审实测：注入 12 个事件而像素不变）。别拿它当密闭证据。
+//! 3. ~~hash 连跑几次都一样~~：**不是证据**。同 argv 加 `--passthrough=off` 出来的 hash 与
+//!    开穿透时完全相同 ⇒ 它只能说明「那几帧恰好静止」。
+//!
+//! ### 同一族的另一个坑：一次一采样（P2-1）
+//!
+//! 以前第 3 帧之后**每一帧**都请求一次采样、每次都覆盖同一文件才 `exit()`，而已派发的采样不会
+//! 因为 exit 撤回 ⇒ **最后写入者说了算**（复审实测 12 次里 7 次写了两次；把窗口在两次采样之间
+//! 改成 900×600，落盘的就是 900×600 那张）。现在闸门在 [`should_request_capture`]，日志里的
+//! `落盘次数=` 必须恒为 1。
+//!
+//! **为什么不是给每个控件灌 forced**：设置页「外观」区的滑块 / 文本框 / 裸 `iced::button` 都不
+//! 消费 forced，那样做要改十几个组件文件——为取证去动产品组件，代价与风险都不对，而且新产品
+//! 组件随时会漏。
+//!
+//! ```text
+//! cargo run -p unlucky-app-iced --example pages_demo -- --screen=instances --width=1180 \
+//!   --height=760 --screenshot=out.png --screenshot-theme=light --software-renderer
+//! ```
+//!
+//! 等 3 帧再截图与 `app.rs` 同一口径（M60 坑 #5）：第一帧可能是启动时的旧尺寸，字体首次上屏会抖动。
+
+use std::sync::atomic::{AtomicU32, Ordering};
+use std::sync::Arc;
+use std::time::Instant;
+
+use iced::{window, Element, Point, Subscription, Task};
+
+use crate::pages::appearance;
+use crate::renderer;
+use crate::shot;
+use crate::theme::Ui;
+
+use super::{app_with_appearance, demo_model, Model};
+
+mod app;
+mod caps;
+mod request;
+
+pub use app::run;
+pub use request::{Request, CAPTURE_POSITION};
+
+/// 截图落盘的帧号（见模块文档）。
+const CAPTURE_AT_FRAME: u32 = 3;
+
+/// 这一帧要不要请求采样？
+///
+/// **M100 r1 P2-1 的核心判据**：`dispatched` 一旦置位就永不再次请求。以前这里是
+/// `frames >= CAPTURE_AT_FRAME`，于是第 3 帧之后**每一帧**都发一次 `window::screenshot`，
+/// 而 `Captured` 每次都覆盖同一文件才 `exit()`——已派发的采样不会因为 exit 被撤回，
+/// 落盘内容变成调度结果（复审实测 12 次里 7 次写了两次）。
+///
+/// 单独拎成自由函数是为了让它可被断言（`Harness::update` 要 iced 运行时才能跑）。
+fn should_request_capture(frames: u32, dispatched: bool, capture_mode: bool) -> bool {
+    capture_mode && !dispatched && frames >= CAPTURE_AT_FRAME
+}
+
+/// 采样「派发了却回不来」的宽限帧数（M100 r2 p3-b）。
+///
+/// 为什么需要它：一次性闸门（上面那条）把「每帧重试」换成了「只试一次」，于是若
+/// `window::screenshot` 的 Task 回不来，harness 既不再采样也不 `exit()` ⇒ CI 上表现成**超时**，
+/// 而不是红灯。超时会被当成基础设施抖动重跑过去，红才会被人看。
+///
+/// ⚠️ **这条兜底只覆盖「还有帧」的情形**（M100 r3 P2-1 订正，我原来在这里写反了）：
+/// `window::frames()` 只在 `Event::Window(RedrawRequested)` 时产消息，**窗口消失 ⇒ 不再有帧
+/// ⇒ 这里的判据根本求值不到**。那一路由 `run()` 里的**终态不变量**兜住（跑完没图 ⇒ 红着退出）；
+/// 而后端报错是另一回事：`run()` 直接返回 `Err`，本来就是非 0。
+///
+/// 30 帧**不换算成秒**（M100 r4 P3-1）：帧间隔在不同机器/负载下量级差异极大——复审实测 2~3ms/帧，
+/// 而本机 `[perf]` 日志里是 `frames=4 elapsed=1133ms` / `frames=5 elapsed=1605ms`（≈200~300ms/帧）。
+/// 所以这里只承诺「若干帧的宽限」，不写时间预算；要调就按「正常路径是第 3 帧派发、第 4~5 帧落盘」
+/// 这个结构关系调，别按秒。
+const CAPTURE_GIVE_UP_FRAMES: u32 = 30;
+
+/// 采样是不是**卡住了**：过了宽限帧数，一次都没落盘。
+///
+/// 不区分「一直没派发」（窗口始终没就绪）与「派发了没回来」——两者对使用者的表现都是
+/// 「没有图」，都该红着退出而不是挂死。
+fn capture_stalled(frames: u32, written: u32) -> bool {
+    written == 0 && frames > CAPTURE_AT_FRAME + CAPTURE_GIVE_UP_FRAMES
+}
+
+struct Harness {
+    request: Request,
+    ui: Ui,
+    /// 视图模型（演示数据；harness 不接 presenter，只出**单页**图）
+    model: Model,
+    /// 外观运行期状态（`--appearance=real`）；`None` = 设置页画演示行。
+    appearance: Option<appearance::State>,
+    window: Option<window::Id>,
+    /// 窗口原生句柄（`window::raw_id` 的回值）。OS 侧密闭指标要在**真句柄**上读，
+    /// 拿不到就留 `None` ⇒ 日志记 `unknown`（不是 `off`）。
+    hwnd: Option<isize>,
+    /// 窗口落点（`window::position` 的**返回值**，不是请求值）。
+    placed: Option<Point>,
+    frames: u32,
+    /// 采样**已派发**（M100 r1 P2-1）：置位后不再请求第二张，避免「最后写入者说了算」。
+    dispatched: bool,
+    /// **成功落盘**的次数（共享给 [`run`]，终态不变量读它）。
+    ///
+    /// 只在 `shot::save` 返回 `Ok` 之后自增：这是「真的写出去了」，不是「我们打算写」（U1）。
+    /// 正常必须恰好 1；打进日志让复审能数。
+    written: Arc<AtomicU32>,
+    /// 本张图收到过几个鼠标事件（`Message::Pointer` 的计数）。
+    ///
+    /// ⚠️ 它只证明「鼠标消息到没到」，**不**证明「像素会不会变」（复审实测：注入 12 个事件而像素
+    /// 不变）。密闭的**主证据**是 `[caps] passthrough_ext=`，见 [`caps`]。
+    pointer: u32,
+    /// 进程起点（`run()` 的开头）——`[perf]` 的首帧口径与产品路径一致：从进 `run()` 算。
+    started: Instant,
+    /// 第一帧到达的时刻（相对 `started`）。`None` = 一帧都没到过。
+    first_frame: Option<std::time::Duration>,
+    /// 出这张图的后端（`wgpu` / `tiny-skia`）。图要能**自证来源**——以前它证不了（M97）。
+    backend: &'static str,
+}
+
+#[derive(Debug, Clone)]
+enum Message {
+    Boot,
+    WindowReady(Option<window::Id>),
+    /// `window::raw_id` 的回值（原生句柄，OS 侧密闭指标要它）。
+    RawId(u64),
+    /// `window::position` 的回值。
+    Placed(Option<Point>),
+    /// `window::size` 的回值。
+    Sized(iced::Size),
+    Frame,
+    Captured(window::Screenshot),
+    /// 收到一个指针事件（只计数，不画；见 [`Harness::subscription`]）。
+    Pointer,
+    /// 页面里的动作（骨架期只打印，接线后由 app 层处理）。
+    Page(super::Message),
+}
+
+impl Harness {
+    fn update(&mut self, message: Message) -> Task<Message> {
+        match message {
+            Message::Boot => window::latest().map(Message::WindowReady),
+            Message::WindowReady(id) => {
+                self.window = id;
+                // 取证窗口按住**那一刻**就断开指针输入（M100 模块文档「取证密闭」）。
+                // 交互模式走不到这里：`request.passthrough` 在没有 `--screenshot` 时恒为 false
+                // （`Request::parse` 里显式给值会直接报错，不给值就是 false）。
+                let Some(id) = id else {
+                    return Task::none();
+                };
+                let mut tasks: Vec<Task<Message>> = Vec::new();
+                if self.request.passthrough {
+                    eprintln!("[harness] 指针穿透已开：本窗口不再接收鼠标事件（取证专用）");
+                    tasks.push(window::enable_mouse_passthrough(id));
+                }
+                tasks.push(window::raw_id::<Message>(id).map(Message::RawId));
+                tasks.push(window::position(id).map(Message::Placed));
+                Task::batch(tasks)
+            }
+            Message::RawId(raw) => {
+                self.hwnd = isize::try_from(raw).ok();
+                Task::none()
+            }
+            Message::Placed(position) => {
+                self.placed = position;
+                match self.window {
+                    Some(id) => window::size(id).map(Message::Sized),
+                    None => Task::none(),
+                }
+            }
+            Message::Sized(size) => {
+                match self.placed {
+                    Some(Point { x, y }) => eprintln!(
+                        "[harness] 窗口实测矩形：({x:.0}, {y:.0}) {:.0}×{:.0}（window::position/size 的回值）",
+                        size.width, size.height
+                    ),
+                    None => eprintln!("[harness] 窗口落点取不到（window::position 回 None）"),
+                }
+                Task::none()
+            }
+            Message::Frame => {
+                if self.frames == 0 {
+                    self.first_frame = Some(self.started.elapsed());
+                }
+                self.frames += 1;
+                // 兜底（M100 r2 p3-b）：采样派发了却回不来时，不许挂死也不许 exit 0。
+                // 这里用 `std::process::exit(1)` 而不是 `iced::exit()`：iced 0.14 没有「带退出码
+                // 结束」的入口，`exit()` 恒 0 —— 而这条的全部意义就是让 CI 看到**红**而不是超时。
+                if capture_stalled(self.frames, self.written.load(Ordering::Relaxed)) {
+                    eprintln!(
+                        "[harness] 采样超时：已过 CAPTURE_AT_FRAME+{CAPTURE_GIVE_UP_FRAMES} 帧\
+                         （当前 {} 帧）仍未收到 Captured，放弃并红着退出",
+                        self.frames
+                    );
+                    std::process::exit(1);
+                }
+                // **一次一采样**（M100 r1 P2-1）：以前这里是 `frames >= CAPTURE_AT_FRAME`，于是第 3 帧
+                // 之后**每一帧**都发一次 `window::screenshot`，而 `Captured` 每次都覆盖同一文件才
+                // `exit()`——已派发的采样不会因为 exit 被撤回 ⇒ **最后写入者说了算**。复审实测 12 次里
+                // 7 次真的写了两次；把窗口在两次采样之间改成 900×600，落盘的就是 900×600 那张。
+                // 现在 `dispatched` 一置位就不再请求（`window` 还没就绪时不置位，保留重试，不会挂死）。
+                if !should_request_capture(
+                    self.frames,
+                    self.dispatched,
+                    self.request.screenshot.is_some(),
+                ) {
+                    return Task::none();
+                }
+                match self.window {
+                    Some(id) => {
+                        self.dispatched = true;
+                        window::screenshot(id).map(Message::Captured)
+                    }
+                    None => Task::none(),
+                }
+            }
+            Message::Pointer => {
+                self.pointer += 1;
+                Task::none()
+            }
+            Message::Captured(screenshot) => {
+                let Some(path) = self.request.screenshot.clone() else {
+                    return Task::none();
+                };
+                // 只在真的写成功时计数（U1）：这个计数器（旧字段名叫 `writes`）若在 save **之前**
+                // 自增，一次落盘失败也会被记成「有图了」，而 `run()` 的终态不变量正是拿它判「有没有证据」。
+                match shot::save(&screenshot, &path) {
+                    Ok(summary) => {
+                        eprintln!("{}", summary.describe());
+                        self.written.fetch_add(1, Ordering::Relaxed);
+                    }
+                    Err(error) => eprintln!("[harness] 截图失败：{error}"),
+                }
+                eprintln!(
+                    "[harness] slug={} backend={} 落盘次数={} 指针事件={}",
+                    self.request.slug(),
+                    self.backend,
+                    self.written.load(Ordering::Relaxed),
+                    self.pointer
+                );
+                // OS 侧密闭指标（M100 r1 P2-2）：`WS_EX_TRANSPARENT` 在不在。三态，`unknown` 不许
+                // 写成 `off`。这一行是「窗口真的把命中测试关掉了」的主证据；`指针事件=` 只是辅助。
+                eprintln!(
+                    "[caps] passthrough_ext={}（GWL_EXSTYLE 的 WS_EX_TRANSPARENT；unknown = 没读到）",
+                    caps::passthrough_label(self.hwnd)
+                );
+                // `[perf]` 两格都是实测：`first_frame` = 首帧事件的时间戳，`fps` = 帧数 / 时长
+                // （**取证窗口**的吞吐，不是长跑稳态帧率——那个看产品路径的 `[tick]`）。
+                renderer::acceptance::report_perf_scene(
+                    &self.request.slug(),
+                    self.frames,
+                    self.first_frame,
+                    self.started.elapsed(),
+                );
+                iced::exit()
+            }
+            Message::Page(message) => {
+                eprintln!("[harness] 页面动作：{message:?}（骨架期不做业务）");
+                Task::none()
+            }
+        }
+    }
+
+    fn subscription(&self) -> Subscription<Message> {
+        if self.request.screenshot.is_none() {
+            return Subscription::none();
+        }
+        // 帧节拍 + **指针事件计数**两样都订阅。后者是 M100 加的：以前「取证密闭」靠
+        // 「同一场景连跑几次 hash 一样」证明，而进程压根收不到鼠标时那条恒真（U5 的同族假绿）。
+        Subscription::batch([
+            window::frames().map(|_| Message::Frame),
+            iced::event::listen_with(|event, _status, _window| match event {
+                iced::Event::Mouse(_) => Some(Message::Pointer),
+                _ => None,
+            }),
+        ])
+    }
+
+    fn theme(&self) -> iced::Theme {
+        self.ui.theme()
+    }
+
+    fn view(&self) -> Element<'_, Message> {
+        app_with_appearance(&self.ui, &self.model, self.appearance.as_ref()).map(Message::Page)
+    }
+}
+
+#[cfg(test)]
+#[path = "harness/tests.rs"]
+mod tests;
diff --git a/crates/app-iced/src/pages/harness/app.rs b/crates/app-iced/src/pages/harness/app.rs
new file mode 100644
index 0000000..2e2dea1
--- /dev/null
+++ b/crates/app-iced/src/pages/harness/app.rs
@@ -0,0 +1,241 @@
+//! 截图 harness 的**运行部分**（M100 r1：`harness.rs` 撞 400 行后从那里搬出来）。
+//!
+//! 这里只有 [`run`]：探后端 → 造外观真状态 → 起 iced → 出图 → 按验收口径打日志。
+//! 参数解析在 [`super::request`]，窗口状态机与采样闸门在 [`super`]，OS 侧密闭指标在
+//! [`super::caps`]。搬出来没有改行为（同一 argv 的 PNG sha256 不变）。
+
+use std::sync::atomic::{AtomicU32, Ordering};
+use std::sync::Arc;
+use std::time::Instant;
+
+use iced::{window, Point, Task};
+
+use unlucky_presenter::prefs::{AppearanceBase, AppearancePrefs};
+
+use crate::app::components::interaction::Interaction;
+use crate::cli::Backend;
+use crate::fonts;
+use crate::pages::appearance;
+use crate::probe::{self, Probe};
+use crate::renderer;
+use crate::theme::Ui;
+
+use super::{demo_model, Harness, Message, Request, CAPTURE_POSITION};
+
+/// **终态判据**：取证运行跑完了却一张图都没落盘 ⇒ 失败。
+///
+/// 单独拎成纯函数是为了让它能被断言（`run()` 要真窗口才能跑）。它守的是 M100 r3 P2-1 那个
+/// 真实缺陷：窗口在第 3 帧消失时，`window::frames()` 不再产消息 ⇒ 帧超时兜底**求值不到**，
+/// 而 iced_winit 对「最后一个窗口 Destroyed」直接退出 ⇒ 曾经是 **exit 0 + 没有 PNG**。
+///
+/// ## 为什么必须有 `capture_mode` 前提（M100 r4 P2-1）
+///
+/// 不给 `--screenshot` 是文档明确支持的**交互预览模式**（「没给 `--screenshot` 就只是开窗看」）：
+/// 该模式 `subscription()` 直接 `Subscription::none()`，**永远不会有 `Captured`** ⇒ `written` 恒 0。
+/// 没有这个前提，用户**正常关掉预览窗**会拿到 exit 1 和一句「取证结束但没有任何图落盘」的
+/// 假消息——那是把"从未要求出图"判成"取证失败"，通道的退出码就此失去区分力
+/// （真崩溃 / 真取证失败 / 正常关个预览窗全是 1）。
+///
+/// ## 为什么用计数器而不是 `path.exists()`
+///
+/// `written` 是**本进程**成功落盘的次数，不会被执行前就存在的旧 PNG 骗过；换成「目标文件存在」
+/// 会在脏路径下给出「exit 0 + 上一次的旧图」。这一点写在这里，免得后来人「顺手改成 exists」。
+pub(super) fn no_evidence(capture_mode: bool, written: u32) -> bool {
+    capture_mode && written == 0
+}
+
+/// 启动（阻塞到出图或关窗）。
+///
+/// **取证通道的硬规则（M97）**：宁可红着退出，也不能悄悄换一种后端继续出图（以前 wgpu 挂掉时
+/// 会静默降级 tiny-skia 照样落 PNG，而报告上写着「GPU 渲染截图」）。所以这里 ① 决策被
+/// [`renderer::strict`] 剥掉兜底、② 起不来带**具名**错误返回、③ 每张图日志都带 `backend=`。
+///
+/// # Errors
+/// 后端探测/字体求值失败、**渲染后端起不来（含 iced 的具名图形错误）**、截图落盘失败时返回人话。
+pub fn run(request: Request) -> Result<(), String> {
+    let started = Instant::now();
+
+    let needs_probe = request.backend == Backend::Auto || renderer::acceptance::enabled();
+    let probe = if needs_probe {
+        Probe::run()
+    } else {
+        Probe::default()
+    };
+    // 剥掉兜底：gallery 没有「偷偷换 CPU」这个选项。
+    let decision = renderer::strict(probe::apply(request.backend, &probe));
+    eprintln!(
+        "[shot] 出图后端 = {} reason={}（取证通道无回退：起不来就红着退出，绝不换 CPU 出图）",
+        decision.primary.name(),
+        decision.reason
+    );
+    renderer::acceptance::report_backend_plan(&decision, request.backend);
+
+    let resolved = fonts::resolve();
+    eprintln!("{}", resolved.describe());
+    let families = resolved.families();
+
+    // 这一份就是喂给 iced 的真值：`[window]` 那行从它取字段（M98 r1 p2-1 的同一个教训）
+    let settings = window::Settings {
+        size: iced::Size::new(request.width, request.height),
+        decorations: false,
+        resizable: true,
+        // 取证窗口钉在固定落点：这样「把指针放进窗口某个位置」是可复算的（真实矩形由
+        // `Harness` 用 `window::position` / `window::size` 的返回值打日志报出，见 `Message::Sized`）
+        position: match request.screenshot {
+            Some(_) => {
+                window::Position::Specific(Point::new(CAPTURE_POSITION.0, CAPTURE_POSITION.1))
+            }
+            None => window::Position::default(),
+        },
+        ..window::Settings::default()
+    };
+    renderer::acceptance::report_window(
+        &renderer::acceptance::WindowFacts::from_settings(&settings),
+        request.scale_factor,
+        "pages_demo",
+        None,
+    );
+
+    // 外观**真状态**（`--appearance=real`）：工厂态 + `ULL_APPEARANCE_*` 覆盖。
+    // 这不是给设置页塞常量：状态从 `State::new` / `apply_env` 来，打日志的是它算出来的生效值。
+    let appearance = request.real_appearance.then(|| {
+        let mut state = appearance::State::new(
+            &AppearancePrefs::factory(),
+            &AppearanceBase::factory(),
+            request.backend,
+            request.flavor,
+        );
+        state.apply_env();
+        eprintln!(
+            "[harness] 外观真状态：window={:.2} panel={:.2}（生效 {:.2}）bg={} fill={:?} dim={:.2} \
+             配色来源={:?} 选中分组={}",
+            state.window_opacity,
+            state.panel_alpha,
+            state.effective_panel_alpha(),
+            state.bg_enabled,
+            state.bg_fill,
+            state.bg_dim,
+            state.palette_source,
+            state.selected_group,
+        );
+        state
+    });
+
+    // 落盘计数器（终态不变量 + 日志共用）：只在 `shot::save` 成功后自增。
+    let written = Arc::new(AtomicU32::new(0));
+
+    let application = |backend: renderer::Kind| {
+        let boot = request.clone();
+        let appearance = appearance.clone();
+        // 落盘次数要能被 `run()` 读到（终态不变量用它），所以走共享计数器而不是 `Harness` 的私有字段：
+        // 值只在 `shot::save` **成功**之后自增，是「真的写出去了」而不是「我们打算写」（U1）。
+        let written = Arc::clone(&written);
+        iced::application(
+            move || {
+                let mut model = demo_model(boot.screen, boot.width);
+                // 截图通道把**消费 forced 的那批控件**（实例页）钉成常态，与产品 `--screenshot`
+                // 的 `ForcedState::Rest` 同一条纪律。它管不到设置页 / 外观区（那边不读 forced），
+                // 那两屏的密闭靠窗口级 passthrough——别把这条当成万能的。
+                if boot.screenshot.is_some() {
+                    model.forced = Some(Interaction::Enabled);
+                }
+                (
+                    Harness {
+                        ui: Ui::new(boot.flavor, families),
+                        model,
+                        appearance: appearance.clone(),
+                        request: boot.clone(),
+                        window: None,
+                        hwnd: None,
+                        placed: None,
+                        frames: 0,
+                        dispatched: false,
+                        written: Arc::clone(&written),
+                        pointer: 0,
+                        started,
+                        first_frame: None,
+                        backend: backend.name(),
+                    },
+                    Task::done(Message::Boot),
+                )
+            },
+            Harness::update,
+            Harness::view,
+        )
+        .theme(Harness::theme)
+        .subscription(Harness::subscription)
+        .default_font(iced::Font {
+            family: iced::font::Family::Name(families.text),
+            ..iced::Font::DEFAULT
+        })
+        .window(settings)
+    };
+
+    eprintln!(
+        "[harness] screen={} width={} height={} slug={}（布局档位 {}）",
+        request.screen.slug(),
+        request.width,
+        request.height,
+        request.slug(),
+        crate::pages::layout::WidthClass::of(request.width).name()
+    );
+
+    // 兜底已被 `strict` 剥掉，所以这条最多跑一次；具名错误的口径与 App 启动一致，
+    // 但**取证通道不许降级**：出不了图就红着退出，不换后端（那是另一处 iced 行为）。
+    let session_started = Instant::now();
+    let result = renderer::run_once(decision, |backend| {
+        std::env::set_var("ICED_BACKEND", backend.env_value());
+        let application = application(backend);
+        match request.scale_factor {
+            Some(scale) => application.scale_factor(move |_| scale).run(),
+            None => application.run(),
+        }
+    });
+    let session = session_started.elapsed();
+
+    let outcome = result.map_err(|error| match renderer::named_graphics_error(&error) {
+        Some(named) => format!(
+            "渲染后端 {} 初始化失败（取证通道无回退，未出图）：{named}",
+            decision.primary.name()
+        ),
+        None => format!("iced 启动失败：{error}"),
+    });
+
+    // 取证通道恒为 evidence 启动 ⇒ 有兜底时 via=refuse、没兜底时 none（不再写死，M98 r1 p3-4）
+    renderer::acceptance::report_outcome(
+        &decision,
+        outcome.as_ref().err().map(String::as_str),
+        renderer::acceptance::failure_via(decision.fallback.is_some(), true),
+        "screenshot",
+        session,
+    );
+
+    outcome?;
+
+    // **终态不变量（M100 r3 P2-1）**：取证跑完了却一张图都没落盘 = 失败。
+    //
+    // 为什么要有这一条（复审变异实测）：兜底原来只有「帧数超时」，而 `window::frames()` 只在
+    // `Event::Window(RedrawRequested)` 时产消息 —— 窗口一旦消失就不再 redraw ⇒ `Message::Frame`
+    // 不再产生 ⇒ `capture_stalled` **永远求值不到**；同时 iced_winit 对「最后一个窗口 Destroyed」
+    // 直接 `Control::Exit`，`run()` 返回 `Ok(())`。表现是 **exit 0 + 没有 PNG**，与成功跑同一形状
+    // 只少了出图那几行 —— 只看退出码的脚本会读到「成功 + 零证据」。
+    //
+    // 所以判据从「超时」升级成「终态」：**跑完了没有图就是失败**。它比超时强，因为覆盖
+    // 「帧不再产生」这一类；帧超时那条保留，管「有帧但采样回不来」。
+    //
+    // **前提是这次真的是取证运行**（M100 r4 P2-1）：不给 `--screenshot` 的交互预览模式本来
+    // 就不出图，判成失败会打出假消息、并让退出码失去区分力。前提写在判据里，不写在这里。
+    if no_evidence(
+        request.screenshot.is_some(),
+        written.load(Ordering::Relaxed),
+    ) {
+        eprintln!("[harness] 取证结束但没有任何图落盘（窗口提前消失 / 落盘失败），按失败退出");
+        std::process::exit(1);
+    }
+
+    eprintln!(
+        "[harness] 用时 {:.0} ms",
+        started.elapsed().as_secs_f64() * 1000.0
+    );
+    Ok(())
+}
diff --git a/crates/app-iced/src/pages/harness/caps.rs b/crates/app-iced/src/pages/harness/caps.rs
new file mode 100644
index 0000000..4dcbff8
--- /dev/null
+++ b/crates/app-iced/src/pages/harness/caps.rs
@@ -0,0 +1,53 @@
+//! 取证窗口的**OS 侧密闭指标**（M100 r1 P2-2）：`WS_EX_TRANSPARENT` 在不在。
+//!
+//! 为什么单独一个文件：① `harness.rs` 正卡在 400 行硬线上；② 「三态映射」这件事本身值得有断言
+//! （把 `unknown` 掉成 `off` 是这类日志最典型的假绿）。
+//!
+//! 判据来自 winit 0.30 的 Windows 实现：`set_cursor_hittest(false)` ⇒
+//! `WS_EX_TRANSPARENT | WS_EX_LAYERED`。读位的手在
+//! [`crate::platform::win32::transparency::click_through`]（全仓唯一 unsafe 落点）。
+
+use crate::platform::win32::transparency;
+
+/// 窗口是不是点击穿透 → 日志里的三态字面量。
+///
+/// - `on` = 读到了，且有 `WS_EX_TRANSPARENT`（winit 已把命中测试关掉）；
+/// - `off` = 读到了，没有这一位；
+/// - `unknown` = **没读到**（非 Windows / 句柄无效 / 还没拿到句柄）。
+///
+/// `unknown` 绝不许写成 `off`：「拿不到」和「没有」是两件事（U1 同族）。
+#[must_use]
+pub fn passthrough_label(hwnd: Option<isize>) -> &'static str {
+    match hwnd.and_then(transparency::click_through) {
+        Some(true) => "on",
+        Some(false) => "off",
+        None => "unknown",
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::passthrough_label;
+
+    /// **抓得住**：谁把「没读到」掉成 `off`（那样一次失败的读数就变成了「密闭没开」的假证据，
+    /// 或者反过来——在一台读不到扩展样式的机器上永远看不出密闭是否生效）。
+    /// **抓不住**：真实窗口上的位到底置没置（那要出图日志里看 `on`）。
+    #[test]
+    fn a_missing_handle_is_unknown_not_off() {
+        assert_eq!(
+            passthrough_label(None),
+            "unknown",
+            "没句柄 = 没读到 ⇒ unknown"
+        );
+        assert_eq!(
+            passthrough_label(Some(0)),
+            "unknown",
+            "句柄 0 = 拿不到 ⇒ unknown（不是 off）"
+        );
+        assert_eq!(
+            passthrough_label(Some(1)),
+            "unknown",
+            "无效句柄 ⇒ unknown（不是 off）"
+        );
+    }
+}
diff --git a/crates/app-iced/src/pages/harness/request.rs b/crates/app-iced/src/pages/harness/request.rs
new file mode 100644
index 0000000..569271e
--- /dev/null
+++ b/crates/app-iced/src/pages/harness/request.rs
@@ -0,0 +1,233 @@
+//! harness 的**参数解析**（M100 从 `harness.rs` 搬出来：那边正好 400 行、零余量）。
+//!
+//! 搬移**不改行为**：同一份 argv 方言、同一份 slug、同一句报错。等价性判据是「同一 argv 出的 PNG
+//! sha256 与拆分前一致」（M100 报告里有实测）。
+//!
+//! 参数方言与 `crates/app-iced/src/cli.rs` 同源（`--key value` 与 `--key=value` 都认），但**刻意不共用
+//! 那个 parser**：harness 是取证通道，默认值与产品启动不同（`--screenshot` 默认开**指针穿透**，见
+//! [`Request::passthrough`]）。产品 bin 的密闭手段是另一套（`cli::ForcedState::Rest`）——两条通道的
+//! 证据分开算，别互相冒充。
+
+use std::path::PathBuf;
+
+use unlucky_design::color::SchemeFlavor;
+
+use crate::cli::Backend;
+use crate::pages::{layout::WidthClass, Screen};
+
+/// 验收窗口尺寸（D30：1180×760、100% DPI）。
+const DEFAULT_SIZE: (f32, f32) = (1180.0, 760.0);
+
+/// 取证窗口的落点请求值（`--screenshot` 时才用）。
+///
+/// 为什么要固定：密闭验证要把系统指针放进窗口里某个点（**故意压在控件上**），窗口位置每次都飘的话，
+/// 「指针到底在不在窗口里」就变成了猜——那正是 U1 的形状。真实矩形由 harness 用
+/// `window::position` / `window::size` 的**返回值**打日志报出，脚本按日志放指针，不以这个常量为准
+/// （它只是请求值）。
+pub const CAPTURE_POSITION: (f32, f32) = (80.0, 80.0);
+
+/// 一次渲染请求。
+#[derive(Debug, Clone, PartialEq)]
+pub struct Request {
+    /// 渲染哪一页。
+    pub screen: Screen,
+    /// 窗口宽度（**含外壳**：布局档位就是按它判的）。
+    pub width: f32,
+    /// 窗口高度。
+    pub height: f32,
+    /// 主题（`--screenshot-theme` > `--theme` > 浅色）。
+    pub flavor: SchemeFlavor,
+    /// 出图路径（`None` = 只开窗）。
+    pub screenshot: Option<PathBuf>,
+    /// 渲染后端请求。
+    pub backend: Backend,
+    /// 强制缩放因子（截图要 100% DPI）。
+    pub scale_factor: Option<f32>,
+    /// 设置页正文画**真控件**（`appearance: Some(..)`）还是演示行（`--appearance=real|demo`）。
+    ///
+    /// 只对 `--screen=settings` 有意义：别的页没有外观分组，静默接受会造出「以为接了线」的假图（U1）。
+    pub real_appearance: bool,
+    /// 截图窗口开**指针穿透**（`window::enable_mouse_passthrough` ⇒ winit `set_cursor_hittest(false)`）。
+    ///
+    /// 默认：给了 `--screenshot` 就开；**交互模式（没有截图）一律关**——交互窗口收不到鼠标是产品事故，
+    /// 所以 `--passthrough` 在交互模式下直接报错，不留「配一下就行」的口子。
+    ///
+    /// `--passthrough=off` 只服务一件事：对照实验——证明「不开穿透时，同一指针位置会把 hover 漏进图」。
+    /// 没有这个反向证据的话，「穿透开着时 hash 不变」既可能是真密闭，也可能只是指针压根没进窗口。
+    pub passthrough: bool,
+}
+
+impl Default for Request {
+    fn default() -> Self {
+        Self {
+            screen: Screen::Instances,
+            width: DEFAULT_SIZE.0,
+            height: DEFAULT_SIZE.1,
+            flavor: SchemeFlavor::Light,
+            screenshot: None,
+            backend: Backend::Auto,
+            scale_factor: None,
+            real_appearance: false,
+            passthrough: false,
+        }
+    }
+}
+
+impl Request {
+    /// 从进程参数解析（`argv[1..]`）。未知参数 / 缺值 / 数字非法时返回人话。
+    pub fn parse(args: impl IntoIterator<Item = String>) -> Result<Self, String> {
+        let mut request = Self::default();
+        let mut theme: Option<SchemeFlavor> = None;
+        let mut shot_theme: Option<SchemeFlavor> = None;
+        let mut passthrough: Option<bool> = None;
+        let mut args = args.into_iter();
+
+        while let Some(arg) = args.next() {
+            let (key, inline) = match arg.split_once('=') {
+                Some((key, value)) => (key.to_owned(), Some(value.to_owned())),
+                None => (arg.clone(), None),
+            };
+
+            match key.as_str() {
+                "--screen" => {
+                    let raw = take(&mut args, inline, "--screen")?;
+                    request.screen = Screen::from_slug(&raw).ok_or_else(|| {
+                        format!("--screen 只认 instances|download|settings|logs，收到 {raw:?}")
+                    })?;
+                }
+                "--width" => {
+                    request.width = number(&take(&mut args, inline, "--width")?, "--width")?
+                }
+                "--height" => {
+                    request.height = number(&take(&mut args, inline, "--height")?, "--height")?;
+                }
+                "--theme" => theme = Some(flavor(&take(&mut args, inline, "--theme")?)?),
+                "--screenshot-theme" => {
+                    shot_theme = Some(flavor(&take(&mut args, inline, "--screenshot-theme")?)?);
+                }
+                "--screenshot" => {
+                    request.screenshot =
+                        Some(PathBuf::from(take(&mut args, inline, "--screenshot")?));
+                }
+                "--software-renderer" => request.backend = Backend::Cpu,
+                "--renderer" => {
+                    request.backend = match take(&mut args, inline, "--renderer")?.as_str() {
+                        "auto" => Backend::Auto,
+                        "gpu" => Backend::Gpu,
+                        "cpu" => Backend::Cpu,
+                        other => {
+                            return Err(format!("--renderer 只认 auto|gpu|cpu，收到 {other:?}"))
+                        }
+                    };
+                }
+                "--scale-factor" => {
+                    let raw = take(&mut args, inline, "--scale-factor")?;
+                    let value = number(&raw, "--scale-factor")?;
+                    if value <= 0.0 {
+                        return Err(format!("--scale-factor 必须 > 0，收到 {raw:?}"));
+                    }
+                    request.scale_factor = Some(value);
+                }
+                "--appearance" => {
+                    request.real_appearance =
+                        match take(&mut args, inline, "--appearance")?.as_str() {
+                            "real" => true,
+                            "demo" => false,
+                            other => {
+                                return Err(format!("--appearance 只认 real|demo，收到 {other:?}"))
+                            }
+                        };
+                }
+                "--passthrough" => {
+                    passthrough = Some(match take(&mut args, inline, "--passthrough")?.as_str() {
+                        "on" => true,
+                        "off" => false,
+                        other => return Err(format!("--passthrough 只认 on|off，收到 {other:?}")),
+                    });
+                }
+                other => return Err(format!("未知参数 {other:?}")),
+            }
+        }
+
+        request.flavor = shot_theme.or(theme).unwrap_or(SchemeFlavor::Light);
+
+        // 指针穿透**只服务取证通道**：没有 `--screenshot` 时显式给值就是配置错误，不是「忽略」——
+        // 静默忽略会让人以为交互窗口也「密闭」了，而它其实照常收鼠标。
+        if passthrough.is_some() && request.screenshot.is_none() {
+            return Err(
+                "--passthrough 只服务 --screenshot 取证通道：交互模式的窗口必须收得到鼠标"
+                    .to_owned(),
+            );
+        }
+        request.passthrough = match request.screenshot {
+            // 取证默认密闭：开窗口的那一刻就断开指针输入（见 `Harness::update` 的 `WindowReady`）
+            Some(_) => passthrough.unwrap_or(true),
+            None => false,
+        };
+
+        if request.real_appearance && request.screen != Screen::Settings {
+            return Err(format!(
+                "--appearance=real 只对 --screen=settings 生效（当前 --screen={}），别的页没有外观分组，\
+                 静默接受会出一张假装接了线的图",
+                request.screen.slug()
+            ));
+        }
+
+        if request.width < 320.0 || request.height < 320.0 {
+            return Err(format!(
+                "窗口太小：{}×{}（至少 320×320）",
+                request.width, request.height
+            ));
+        }
+
+        Ok(request)
+    }
+
+    /// 出图文件名片段（`<screen>[-real]-<class>-<flavor>-w<宽>`，归档用）。
+    pub fn slug(&self) -> String {
+        let class = WidthClass::of(self.width);
+        let flavor = if self.flavor.is_dark() {
+            "dark"
+        } else {
+            "light"
+        };
+        let width = self.width as u32;
+        // 「演示行版」与「真控件版」必须能靠文件名分开，否则归档里两张图分不清谁是谁
+        let screen = if self.real_appearance {
+            format!("{}-real", self.screen.slug())
+        } else {
+            self.screen.slug().to_owned()
+        };
+        format!("{screen}-{}-{flavor}-w{width}", class.name())
+    }
+}
+
+fn take(
+    args: &mut impl Iterator<Item = String>,
+    inline: Option<String>,
+    flag: &str,
+) -> Result<String, String> {
+    inline
+        .or_else(|| args.next())
+        .ok_or_else(|| format!("{flag} 需要一个值"))
+}
+
+fn number(raw: &str, flag: &str) -> Result<f32, String> {
+    raw.parse::<f32>()
+        .map_err(|_| format!("{flag} 需要数字，收到 {raw:?}"))
+        .and_then(|value| {
+            if value.is_finite() && value > 0.0 {
+                Ok(value)
+            } else {
+                Err(format!("{flag} 必须是正数，收到 {raw:?}"))
+            }
+        })
+}
+
+fn flavor(raw: &str) -> Result<SchemeFlavor, String> {
+    match raw {
+        "light" => Ok(SchemeFlavor::Light),
+        "dark" => Ok(SchemeFlavor::Dark),
+        other => Err(format!("主题只认 light|dark，收到 {other:?}")),
+    }
+}
diff --git a/crates/app-iced/src/pages/harness/tests.rs b/crates/app-iced/src/pages/harness/tests.rs
new file mode 100644
index 0000000..730952c
--- /dev/null
+++ b/crates/app-iced/src/pages/harness/tests.rs
@@ -0,0 +1,247 @@
+//! `pages::harness` 的断言（M90 r2 从 `harness.rs` 外置：那边曾 402 行，guards 的 file-size 会判红）。
+//!
+//! 只测**参数解析 / slug / 采样闸门 / 三态标签**，不碰 iced 运行时。所以「穿透在真实窗口上真的
+//! 关掉了命中测试」这条这里证明不了——它要看出图日志里的 `[caps] passthrough_ext=`（三态，
+//! 来自 `GWL_EXSTYLE` 的 `WS_EX_TRANSPARENT`）；`指针事件=N` 只是辅助指标（它只证明消息到没到）。
+
+use super::request::Request;
+use super::{capture_stalled, should_request_capture, CAPTURE_AT_FRAME, CAPTURE_GIVE_UP_FRAMES};
+use crate::cli::Backend;
+use crate::pages::Screen;
+
+use unlucky_design::color::SchemeFlavor;
+
+fn parse(args: &[&str]) -> Result<Request, String> {
+    Request::parse(args.iter().map(|arg| (*arg).to_owned()))
+}
+
+#[test]
+fn defaults_are_the_acceptance_frame() {
+    let request = parse(&[]).expect("空参数要能解析");
+    assert_eq!(request.screen, Screen::Instances);
+    assert_eq!((request.width, request.height), (1180.0, 760.0));
+    assert_eq!(request.flavor, SchemeFlavor::Light);
+    assert!(request.screenshot.is_none());
+    assert!(!request.real_appearance, "默认画演示行");
+}
+
+#[test]
+fn screen_and_width_parse_in_both_argv_forms() {
+    let spaced = parse(&["--screen", "settings", "--width", "900"]).unwrap();
+    let inline = parse(&["--screen=settings", "--width=900"]).unwrap();
+    assert_eq!(spaced, inline);
+    assert_eq!(spaced.screen, Screen::Settings);
+    assert_eq!(spaced.width, 900.0);
+    assert!(parse(&["--screen=gallery"]).is_err());
+    assert!(parse(&["--width=abc"]).is_err());
+}
+
+#[test]
+fn screenshot_theme_wins_over_theme() {
+    let request = parse(&["--theme=dark", "--screenshot-theme=light"]).unwrap();
+    assert_eq!(request.flavor, SchemeFlavor::Light);
+    assert_eq!(parse(&["--theme=dark"]).unwrap().flavor, SchemeFlavor::Dark);
+}
+
+#[test]
+fn software_renderer_is_an_alias_of_cpu() {
+    assert_eq!(
+        parse(&["--software-renderer"]).unwrap().backend,
+        Backend::Cpu
+    );
+    assert_eq!(parse(&["--renderer=cpu"]).unwrap().backend, Backend::Cpu);
+    assert_eq!(parse(&["--renderer=gpu"]).unwrap().backend, Backend::Gpu);
+}
+
+#[test]
+fn slug_carries_screen_class_and_flavor() {
+    let request = parse(&[
+        "--screen=instances",
+        "--width=700",
+        "--screenshot-theme=dark",
+    ])
+    .unwrap();
+    assert_eq!(request.slug(), "instances-medium-dark-w700");
+}
+
+#[test]
+fn tiny_windows_are_rejected() {
+    assert!(parse(&["--width=200"]).is_err());
+    assert!(parse(&["--height=100"]).is_err());
+}
+
+/// **密闭不变量（M100）**：截图通道默认开指针穿透；交互模式（没有 `--screenshot`）一律关。
+///
+/// 抓得住：① 谁把取证默认值改成关（那会让取证图重新受系统指针影响）；
+/// ② 谁让交互模式也开穿透（用户窗口收不到鼠标 = 产品事故）。
+/// 抓不住：穿透**真的**生效了没有——那要看出图日志的 `指针事件=N`，测试替不了。
+#[test]
+fn capture_is_sealed_by_default_and_interactive_never_is() {
+    assert!(
+        parse(&["--screenshot", "o.png"]).unwrap().passthrough,
+        "截图通道默认必须开指针穿透"
+    );
+    assert!(!parse(&[]).unwrap().passthrough, "交互模式不许开指针穿透");
+    assert!(
+        !parse(&["--screen=settings"]).unwrap().passthrough,
+        "交互模式（带页名）同样不许开"
+    );
+    // 显式给值在交互模式下是**配置错误**，不是「忽略」：静默忽略会让人以为交互窗口也密闭了
+    for flags in [
+        &["--passthrough=on"][..],
+        &["--passthrough", "off"],
+        &["--screen=settings", "--passthrough=on"],
+    ] {
+        assert!(parse(flags).is_err(), "{flags:?} 应该报错");
+    }
+}
+
+/// 对照实验的口子（`--passthrough=off`）：只服务「不开穿透时 hover 会不会漏进图」这一条。
+#[test]
+fn the_control_run_can_turn_the_passthrough_off() {
+    let shot = parse(&["--screenshot", "o.png", "--passthrough=off"]).unwrap();
+    assert!(!shot.passthrough, "显式 off 必须尊重");
+    assert!(shot.screenshot.is_some(), "off 只对截图通道有意义");
+}
+
+/// **外观真状态那一屏（M100）**：`--appearance=real` 只在设置页成立，且 slug 要与演示行版分开。///
+/// 抓得住：① 谁把 real 接到别的页（那会出一张「假装接了线」的图）；
+/// ② 两张图落成同名文件（归档后无法区分哪张是真控件版）。
+/// 抓不住：那张图里到底有没有控件——那是像素的事，由两张图的 sha256 不同 + tower 亲自看图判。
+#[test]
+fn the_real_control_screen_is_settings_only_and_says_so_in_the_slug() {
+    let real = parse(&["--screen=settings", "--appearance=real"]).unwrap();
+    assert!(real.real_appearance);
+    assert_eq!(real.slug(), "settings-real-expanded-light-w1180");
+    assert_eq!(
+        parse(&["--screen=settings"]).unwrap().slug(),
+        "settings-expanded-light-w1180",
+        "演示行版的 slug 不许变（既有归档脚本按它找图）"
+    );
+    assert!(
+        parse(&["--screen=instances", "--appearance=real"]).is_err(),
+        "别的页没有外观分组，静默接受会出一张假图"
+    );
+    assert!(parse(&["--screen=settings", "--appearance=x"]).is_err());
+}
+
+/// **一次一采样（M100 r1 P2-1）**：采样请求最多发一次，且最早在 `CAPTURE_AT_FRAME`。
+///
+/// 抓得住：谁把闸门改回 `frames >= CAPTURE_AT_FRAME`（那样第 3 帧之后每帧都发一次采样，
+/// `Captured` 每次都覆盖同一文件 ⇒ **最后写入者说了算**；复审实测 12 次里 7 次写了两次，
+/// 并把窗口在两次采样之间改成 900×600 之后落盘的就是 900×600 那张）。
+/// 抓不住：「落盘次数真的是 1」——那要看真实运行的日志 `落盘次数=1`（本测试只测闸门逻辑）。
+#[test]
+fn the_capture_gate_opens_once_and_never_again() {
+    // 窗口到第 4 帧才就绪也要恰好请求一次（`window` 未就绪时不置位，保留重试，不会挂死）
+    let mut dispatched = false;
+    let mut requests = 0;
+    for frames in 1..=10u32 {
+        let window_ready = frames >= 4;
+        if should_request_capture(frames, dispatched, true) && window_ready {
+            dispatched = true;
+            requests += 1;
+        }
+    }
+    assert_eq!(requests, 1, "整个进程只许请求一次采样");
+
+    assert!(!should_request_capture(1, false, true), "第 3 帧前不许采样");
+    assert!(should_request_capture(3, false, true), "第 3 帧取第一张");
+    assert!(
+        !should_request_capture(99, true, true),
+        "已派发过就不再请求（这条就是 P2-1 的修复本身）"
+    );
+    assert!(
+        !should_request_capture(99, false, false),
+        "交互模式（没有 --screenshot）不采样"
+    );
+}
+
+/// **密闭日志三态（M100 r1 P2-2）**：拿不到句柄必须记 `unknown`，不许记 `off`。
+///
+/// 抓得住：谁把 `None` 掉成 `off`（那会把「没读到」说成「读到了、没开」——这台机器上从此永远
+/// 看不出密闭到底生效没有）。
+/// 抓不住：真实窗口上的位（那要看运行日志里的 `passthrough_ext=on`）。
+#[test]
+fn the_passthrough_capability_is_three_states() {
+    assert_eq!(super::caps::passthrough_label(None), "unknown");
+    assert_eq!(
+        super::caps::passthrough_label(Some(0)),
+        "unknown",
+        "句柄 0 = 还没拿到窗口"
+    );
+}
+
+/// **兜底不许在正常路径误触发**（M100 r2 p3-b）。
+///
+/// 抓得住：宽限帧数被改小到「采样还在飞行中就判死」（例如把它写成 0）——那时第 4 帧
+/// （第 3 帧派发、第 5 帧才落盘）就会误触发，CI 上表现为「正常出图却红」。
+/// 抓不住：真实 `window::screenshot` 卡死的时序（那要注入一个不回的采样，测试替不了）。
+#[test]
+fn the_stall_guard_never_fires_on_the_normal_path() {
+    // 实测时序：第 3 帧派发，第 4~5 帧才收到 Captured（采样在飞行中 writes 还是 0）
+    let mut first_bad: Option<(u32, bool, u32)> = None;
+    for frames in 1..=200u32 {
+        let dispatched = frames >= CAPTURE_AT_FRAME;
+        let writes = u32::from(dispatched && frames >= CAPTURE_AT_FRAME + 2);
+        if capture_stalled(frames, writes) {
+            first_bad.get_or_insert((frames, dispatched, writes));
+        }
+    }
+    assert!(
+        first_bad.is_none(),
+        "正常路径误触发兜底（帧, dispatched, writes）={first_bad:?}"
+    );
+}
+
+/// **兜底只在「有帧但没采样」时触发**，且必须过了宽限窗口才触发。
+///
+/// 抓得住：① 判据写成 `frames >= CAPTURE_AT_FRAME`（宽限为 0）——正常路径会立刻误触发；
+/// ② 判据漏掉 `writes == 0`（已经落过盘还报超时）；
+/// ③ 宽限窗口被写成 `>=` 边界错位（差一帧）。
+/// 抓不住：`exit(1)` 到底有没有被操作系统收到（那要跑真二进制，见报告里的变异实测）。
+#[test]
+fn the_stall_guard_fires_only_after_the_grace_window() {
+    let threshold = CAPTURE_AT_FRAME + CAPTURE_GIVE_UP_FRAMES;
+    assert!(
+        !capture_stalled(threshold, 0),
+        "刚好到阈值还不算超时（要给最后一帧留余量）"
+    );
+    assert!(
+        capture_stalled(threshold + 1, 0),
+        "越过阈值且一次都没落盘 ⇒ 必须放弃（红着退出，不许挂死）"
+    );
+    assert!(
+        !capture_stalled(u32::MAX, 1),
+        "已经落过盘就不算卡住（正常路径由 exit() 结束）"
+    );
+    assert!(!capture_stalled(1, 0), "前几帧本来就没有图，不算卡住");
+    // 宽限必须明显大于「派发→落盘」的实测间隔（约 2 帧），否则正常路径会误触发。
+    // 用局部绑定而不是直接比较常量：`assert!(CONST >= 10)` 会被 clippy 判成常量断言。
+    let grace = CAPTURE_GIVE_UP_FRAMES;
+    assert!(grace >= 10, "宽限帧数 {grace} 太小，正常路径会误触发");
+}
+
+/// **终态不变量：跑完了没有图就是失败 —— 但只在取证运行里这么判**（r3 P2-1 → r4 P2-1）。
+///
+/// 抓得住：① 判据被改成恒 false（终态检查成摆设）；② **判据丢掉 `capture_mode` 前提**
+/// （r4 实测到的真缺陷：不给 `--screenshot` 的交互预览模式本来就不出图，却会被判失败 ⇒
+/// exit 1 + 一句「取证结束但没有任何图落盘」的假消息，退出码因此失去区分力）。
+/// 抓不住：`run()` 里那个**调用点**被删掉（判据还在、本测试照绿）——那一层只能靠变异实测
+/// （M3：第 3 帧改关窗 ⇒ 期望 exit 1），测试替不了。
+#[test]
+fn finishing_without_a_single_write_is_a_failure_only_while_capturing() {
+    use super::app::no_evidence;
+
+    // 红线（r4 P2-1）：交互预览模式关窗**不是**失败
+    assert!(
+        !no_evidence(false, 0),
+        "交互预览模式（没给 --screenshot）从未要求出图，关窗必须 exit 0"
+    );
+    assert!(
+        no_evidence(true, 0),
+        "取证运行一张图都没落盘 ⇒ 必须判失败（不许 exit 0）"
+    );
+    assert!(!no_evidence(true, 1), "落过盘就算有证据");
+    assert!(!no_evidence(false, 1), "预览模式更不该报错");
+}
diff --git a/crates/app-iced/src/pages/instances.rs b/crates/app-iced/src/pages/instances.rs
new file mode 100644
index 0000000..43b9ac6
--- /dev/null
+++ b/crates/app-iced/src/pages/instances.rs
@@ -0,0 +1,267 @@
+//! 实例页：**list-detail** 的唯一用例，也是 M90 唯一打通到「真组件 + 真数据 + 真命令」的页。
+//!
+//! ## 版式（由 [`super::layout`] 决议，页面不自己算宽度）
+//!
+//! | 版面 | 结构 | 退化行为 |
+//! |---|---|---|
+//! | `ListDetail`（窗口 ≥840） | 左列 336 固定、**独立滚动**；右列详情，散文 ≤424 | — |
+//! | `SingleColumn`（<840） | 列表与详情**整页切换**：本页只渲染详情列（块贴左吃满页宽，散文 ≤424） | 顶部给「Back to instances」，列表退成上一屏 |
+//!
+//! 为什么窄窗不是「上下堆」：官方 compact 下 list-detail 的口径是一次只显示一个 pane（列表 → 详情，
+//! 整页切换）。上下堆会把详情挤到折叠线以下，等于详情不存在。
+//!
+//! ## M90：占位控件 → 真组件（逐项对照）
+//!
+//! | 位置 | M84（占位） | M90（真组件） |
+//! |---|---|---|
+//! | 列表行 | 手搓 `container` + `text_role`（行高 56） | `navigation::list_item`（一/两/三行 44/60/76，五态状态层） |
+//! | 页头动作 | `frame::text_action`（纯 `text` + 手搓 hover） | `buttons::text`（`Button` 五式 + 状态层） |
+//! | 「Play」 | `frame::text_action` | `buttons::filled`（**全屏唯一实心 accent**，rubric K2） |
+//! | 分隔线 | `frame::divider` | `divider::full` |
+//! | 数据 | `DEMO` 常量 | [`super::model::Instances`]（真页面由 presenter 快照转，演示由 `DEMO` 转） |
+//!
+//! 判据没有因此放松：列宽仍由 [`super::layout`] 给（见 `pages/tests.rs` 的 424 断言）。
+//!
+//! ## 行高为什么从 56 变成 60（M90 登记）
+//!
+//! M84 的行高是「`row_height` 44 + `Space::X3` 12 = 56」的手工值；真 `ListItem` 的两行档是
+//! **60**（令牌 `row_height` 44 + 每多一行 16，A1 是 72）。差异来自组件自己的几何真源，
+//! 页面不许覆盖——这正是「接真组件」的应有结果。列表仍高于可视区，独立滚动条照样可见。
+//!
+//! ## 行距归零 + 底部内缩（M102，视觉复审 ②）
+//!
+//! 视觉复审在 1180×760 的截图里抓到「末行 Redstone Lab 被卡片底边切掉半行（副标题消失）」。
+//! 根因是**两道页级附加量**：`Space::X1` 的行距让行节奏变成 64，与可视高度除不尽；
+//! 列表滚动区贴到卡片的 1px 圆角描边上，切点正好落在描边线上。修法两件：
+//!
+//! | 改什么 | 值 | 结果 |
+//! |---|---|---|
+//! | 页级行距 | 4 → **0**（真源 [`ROW_SPACING`] = `None`） | 行节奏回到组件的 60 |
+//! | 滚动区底部内缩 | 0 → **`Space::X2` 8**（真源 [`LIST_BOTTOM_INSET`]） | 切点落在卡片的内边距带里，不压描边 |
+//!
+//! 于是可视区 = 580 − 列头 32 − 内缩 8 = **540 = 9 × 60**，正好 9 整行：末行完整可见，
+//! 第 10 行整体落在裁切线之外。两个数都**只有一个真源**，页面与护栏都从它取
+//! （`instances/tests.rs` 引 [`LIST_BOTTOM_INSET`].`dp()` 与 [`ROW_SPACING`] 算 pitch，
+//! 另有一条源码结构断言盯着 `list_column()` 不许再叠字面量间距）。
+//! 列表内容 12×60 = 720 仍高过可视区，独立滚动条照样可见。
+
+mod data;
+mod demo;
+mod detail;
+mod text;
+
+#[cfg(test)]
+mod tests;
+
+#[cfg(test)]
+pub(crate) use data::{DEMO, NOTE, SELECTED};
+pub(super) use demo::demo;
+pub(super) use text::Texts;
+
+use iced::widget::{column, container, row, scrollable};
+use iced::{Alignment, Background, Border, Element, Length, Padding};
+
+use unlucky_design::color::Role;
+use unlucky_design::elevation::MaterialLayer;
+use unlucky_design::icons::IconKind;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use crate::app::components::buttons::{self, Button};
+use crate::app::components::interaction::Interaction;
+use crate::app::components::navigation::list_item::{list_item, ListItem};
+use crate::theme::Ui;
+use unlucky_presenter::router::Route;
+
+use super::frame::{self, Header};
+use super::layout::{FrameMetrics, PageLayout};
+use super::model::{Instances, Model, Row};
+use super::{Action, Message};
+
+/// 列表行距：**`None` = 这一层不加间距**（页面与护栏**共用这一个真源**）。
+///
+/// M102 的 ② 就是页级附加量：`ListItem` 自己的 60 高已含上下 8px 内边距，页面再叠一道
+/// `Space::X1`(4) 就把行节奏变成 64、与可视高度除不尽（1180×760 下末行被切半行）。
+/// 所以行距不写成字面量、也不散落在 `list_column` 里，而是这个常量——
+/// 页面 `match` 它，`instances/tests.rs` 也从它算 pitch（改这里，测试立刻红）。
+pub(super) const ROW_SPACING: Option<Space> = None;
+
+/// 列表滚动区的**底部内缩**：让裁切线落在卡片的内边距带里，而不是压在 1px 描边上。
+///
+/// 与 [`ROW_SPACING`] 是一对（行距管「切在哪」、内缩管「切在什么底色上」），
+/// 两个数都由 `instances/tests.rs` 的几何断言直接引用。
+pub(super) const LIST_BOTTOM_INSET: Space = Space::X2;
+
+/// 整页（`block.detail = None` 时详情区显示空态）。
+///
+/// 文案全部走 [`Texts`]（`model.lang` 的语言）：这个函数是实例页唯一的取词入口，
+/// 页面里不留任何可见英文字面量（守门见 `instances/tests/i18n.rs`）。
+pub fn view<'a>(ui: &'a Ui, metrics: FrameMetrics, model: &'a Model) -> Element<'a, Message> {
+    let block = &model.instances;
+    let forced = model.forced;
+    let texts = Texts::of(model.lang.catalog());
+    let header = Header::new(texts.title())
+        .subtitle(texts.subtitle())
+        .action(buttons::text(
+            ui,
+            forced_state(
+                Button::new(texts.new_instance(), Message::Action(Action::NewInstance)),
+                forced,
+            ),
+        ))
+        .action(buttons::text(
+            ui,
+            forced_state(
+                Button::new(texts.import(), Message::Action(Action::Import)),
+                forced,
+            ),
+        ));
+
+    let body = match metrics.layout {
+        PageLayout::ListDetail => frame::panes(
+            metrics,
+            list_column(ui, block, forced, texts),
+            match &block.detail {
+                Some(detail) => detail::detail_column(ui, metrics, detail, forced, texts),
+                None => detail::detail_empty(ui, texts),
+            },
+        ),
+        _ => match &block.detail {
+            Some(detail) => detail::narrow_detail(ui, metrics, detail, forced, texts),
+            None => frame::body(metrics, detail::detail_empty(ui, texts)),
+        },
+    };
+
+    frame::page(ui, metrics, header, body)
+}
+
+// --------------------------------------------------------------- 列表列
+
+fn list_column<'a>(
+    ui: &'a Ui,
+    block: &'a Instances,
+    forced: Option<Interaction>,
+    texts: Texts,
+) -> Element<'a, Message> {
+    let head = container(
+        row![
+            container(frame::text_role(
+                ui,
+                TypeRole::LabelMedium,
+                false,
+                texts.all_title(),
+                ui.color(Role::OnSurfaceVariant),
+            ))
+            .width(Length::Fill)
+            .align_y(Alignment::Center),
+            frame::text_role_owned(
+                ui,
+                TypeRole::LabelMedium,
+                false,
+                block.rows.len().to_string(),
+                ui.color(Role::OnSurfaceVariant),
+            ),
+        ]
+        .width(Length::Fill)
+        .align_y(Alignment::Center),
+    )
+    .width(Length::Fill)
+    .padding(Padding {
+        top: ui.space(Space::X3),
+        right: ui.space(Space::X3),
+        bottom: ui.space(Space::X1),
+        left: ui.space(Space::X3),
+    });
+
+    let mut rows = column(
+        block
+            .rows
+            .iter()
+            .map(|entry| list_row(ui, entry, is_selected(block, entry), forced))
+            .collect::<Vec<_>>(),
+    )
+    .padding(Padding::from([0.0, ui.space(Space::X2)]))
+    .width(Length::Fill);
+
+    // 行距只从 `ROW_SPACING` 来（当前是 None = 不加间距）。别在这里写字面量 `.spacing(…)`：
+    // 那正是视觉复审 ② 的那道页级附加量（`pages/tests.rs` 有一条源码结构断言盯着这段）。
+    if let Some(spacing) = ROW_SPACING {
+        rows = rows.spacing(ui.space(spacing));
+    }
+
+    // **独立滚动**：只有列表列这一条 scrollable，详情列不跟着滚。
+    let scroller = scrollable(rows)
+        .direction(scrollable::Direction::Vertical(
+            scrollable::Scrollbar::new()
+                .width(frame::SCROLLBAR_WIDTH)
+                .scroller_width(frame::SCROLLBAR_WIDTH)
+                .margin(frame::SCROLLBAR_MARGIN),
+        ))
+        .height(Length::Fill)
+        .style(frame::scroll_style(ui));
+
+    // 底部内缩：裁切线落在卡片的内边距带里，而不是压在圆角描边上（M102 / 视觉复审 ②）。
+    container(column![head, scroller].height(Length::Fill))
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .padding(Padding::default().bottom(ui.space(LIST_BOTTOM_INSET)))
+        .style(move |_theme| container::Style {
+            background: Some(Background::Color(ui.layer(MaterialLayer::Card))),
+            border: Border {
+                radius: ui.radius_dp(ShapeScale::Large),
+                ..Border::default()
+            },
+            ..container::Style::default()
+        })
+        .into()
+}
+
+fn is_selected(block: &Instances, entry: &Row) -> bool {
+    block
+        .detail
+        .as_ref()
+        .is_some_and(|detail| detail.id == entry.id)
+}
+
+/// `--force-state` 的落点：只改**画出来的**状态，不动任何状态机（cli `ForcedState` 的同一条纪律）。
+pub(super) fn forced_state<'a, M>(
+    button: Button<'a, M>,
+    forced: Option<Interaction>,
+) -> Button<'a, M> {
+    match forced {
+        Some(state) => button.state(state),
+        None => button,
+    }
+}
+
+/// 一行（`ListItem` 的两/三行档：overline = 运行状态，headline = 名字，supporting = 版本 + 加载器）。
+///
+/// 点一行 = **压一层路由栈**（`Route::Detail(id)`），页面自己不留「选中项」副本——
+/// 于是「当前选中」与「返回栈」永远是同一份真相（`presenter::router`）。
+fn list_row<'a>(
+    ui: &'a Ui,
+    entry: &'a Row,
+    selected: bool,
+    forced: Option<Interaction>,
+) -> Element<'a, Message> {
+    let mut item = ListItem::new(
+        entry.name.as_str(),
+        Message::Navigate(Route::Detail(entry.id.clone())),
+    )
+    .supporting(entry.supporting.as_str())
+    .leading(IconKind::Instances)
+    .trailing(IconKind::ChevronRight);
+
+    if let Some(status) = &entry.status {
+        item = item.overline(status.as_str());
+    }
+    if selected {
+        item = item.selected();
+    }
+    if let Some(state) = forced {
+        item = item.state(state);
+    }
+
+    list_item(ui, item)
+}
diff --git a/crates/app-iced/src/pages/instances/data.rs b/crates/app-iced/src/pages/instances/data.rs
new file mode 100644
index 0000000..df9899e
--- /dev/null
+++ b/crates/app-iced/src/pages/instances/data.rs
@@ -0,0 +1,143 @@
+//! 实例页的**演示数据**（骨架期没有业务状态机，也没有业务数据）。
+//!
+//! 12 条，**故意比可视区高**：列表列的独立滚动条要能在截图里看见（单测钉住这条）。
+//!
+//! **这里的数据是夹具（用户数据），不是界面文案**：`1.20.4` / `Fabric 0.15.7` / `4 GiB` /
+//! `2 hours ago` 这些是「实例清单里会长成什么样」的样本，M120 没有把它们搬进词表——它们不是
+//! 界面说的那句话。界面文案（标题 / 按钮 / 元信息标签 / 空态 / 阶段）走 `catalog/instances.rs`，
+//! 见 `text.rs` 与 `app/view/instances.rs`。
+//!
+//! 这条路径（`pages_demo` harness / 单测）**恒英文**：`pages::demo_model` 走 `Model::new`，
+//! `lang` 是 `Lang::En`。产品路径不读这份数据，它画的是 presenter 快照。
+
+/// 演示条目（骨架期没有业务数据；夹具文案，见模块文档）。
+pub(crate) struct Entry {
+    pub(crate) name: &'static str,
+    pub(crate) version: &'static str,
+    pub(crate) loader: &'static str,
+    pub(crate) memory: &'static str,
+    pub(crate) java: &'static str,
+    pub(crate) mods: &'static str,
+    pub(crate) last_played: &'static str,
+}
+
+/// 12 条演示数据：**比可视区高**，这样列表列的独立滚动条在截图里能看见。
+pub(crate) const DEMO: [Entry; 12] = [
+    Entry {
+        name: "Fabulous World",
+        version: "1.20.4",
+        loader: "Fabric 0.15.7",
+        memory: "4 GiB",
+        java: "Temurin 21",
+        mods: "148 mods",
+        last_played: "2 hours ago",
+    },
+    Entry {
+        name: "Skyblock Origins",
+        version: "1.21.1",
+        loader: "NeoForge 21.1.72",
+        memory: "6 GiB",
+        java: "Temurin 21",
+        mods: "86 mods",
+        last_played: "yesterday",
+    },
+    Entry {
+        name: "Vanilla Survival",
+        version: "1.21.4",
+        loader: "Vanilla",
+        memory: "2 GiB",
+        java: "Temurin 21",
+        mods: "0 mods",
+        last_played: "3 days ago",
+    },
+    Entry {
+        name: "Create: Above and Beyond",
+        version: "1.18.2",
+        loader: "Forge 40.2.0",
+        memory: "8 GiB",
+        java: "Temurin 17",
+        mods: "312 mods",
+        last_played: "last week",
+    },
+    Entry {
+        name: "All the Mods 9",
+        version: "1.20.1",
+        loader: "NeoForge 20.4.237",
+        memory: "8 GiB",
+        java: "Temurin 17",
+        mods: "412 mods",
+        last_played: "2 weeks ago",
+    },
+    Entry {
+        name: "Better MC",
+        version: "1.20.1",
+        loader: "Fabric 0.14.24",
+        memory: "6 GiB",
+        java: "Temurin 17",
+        mods: "264 mods",
+        last_played: "last month",
+    },
+    Entry {
+        name: "RLCraft",
+        version: "1.12.2",
+        loader: "Forge 14.23.5",
+        memory: "4 GiB",
+        java: "Zulu 8",
+        mods: "184 mods",
+        last_played: "2 months ago",
+    },
+    Entry {
+        name: "Origins SMP",
+        version: "1.20.4",
+        loader: "Quilt 0.24.0",
+        memory: "4 GiB",
+        java: "Temurin 21",
+        mods: "57 mods",
+        last_played: "3 months ago",
+    },
+    Entry {
+        name: "Redstone Lab",
+        version: "1.19.4",
+        loader: "Fabric 0.15.2",
+        memory: "3 GiB",
+        java: "Temurin 17",
+        mods: "34 mods",
+        last_played: "April 12",
+    },
+    Entry {
+        name: "Pixelmon Reforged",
+        version: "1.16.5",
+        loader: "Forge 36.2.34",
+        memory: "6 GiB",
+        java: "Temurin 8",
+        mods: "121 mods",
+        last_played: "March 3",
+    },
+    Entry {
+        name: "Techopolis 2",
+        version: "1.20.1",
+        loader: "Forge 47.2.20",
+        memory: "8 GiB",
+        java: "Temurin 17",
+        mods: "198 mods",
+        last_played: "January 28",
+    },
+    Entry {
+        name: "Cobblemon",
+        version: "1.21.1",
+        loader: "Fabric 0.16.9",
+        memory: "5 GiB",
+        java: "Temurin 21",
+        mods: "74 mods",
+        last_played: "January 9",
+    },
+];
+
+/// 演示选中的条目（第一条）。
+pub(crate) const SELECTED: usize = 0;
+
+/// 详情正文（**故意写长**：这是行宽上限的视觉证据——1180 宽窗口下也只断在 ~72 字符）。
+pub(crate) const NOTE: &str = "This instance keeps its own mods, configs and saves. The launcher resolves the version chain \
+     (instance → mod loader → vanilla) at launch time, verifies every jar it downloaded against the mirror \
+     manifest, and streams progress back as structured events so the UI never has to guess. Nothing on this \
+     page is wired to real data yet: the layout is, the numbers are.";
diff --git a/crates/app-iced/src/pages/instances/demo.rs b/crates/app-iced/src/pages/instances/demo.rs
new file mode 100644
index 0000000..64443c9
--- /dev/null
+++ b/crates/app-iced/src/pages/instances/demo.rs
@@ -0,0 +1,67 @@
+//! 实例页的**演示数据 → 视图模型**转换（M84 的出图基线靠这份数据）。
+//!
+//! 只被 [`crate::pages::demo_model`] 用：产品路径的转换在 `app/view.rs`（presenter 快照 → 模型）。
+//! 两份数据源喂同一个渲染函数，这是 [`crate::pages::model`] 存在的理由。
+
+use unlucky_i18n::{Catalog, Key, Lang};
+
+use super::super::model::{Detail, Instances, Meta, Row};
+use super::data::{DEMO, NOTE, SELECTED};
+
+/// 演示路径的目录：**恒英文**。
+///
+/// 为什么不是 `model.lang`：本函数只被 `pages::demo_model` 调用，而那条路（`pages_demo` harness /
+/// 单测）走 `Model::new`，`lang` 恒为 `Lang::En`（harness 没有换语言的开关）。产品路径不读这里
+/// ——它走 `app/view.rs` 的快照转换。等 harness 有 `--lang` 时把这一行换成参数即可。
+fn catalog() -> Catalog {
+    Lang::En.catalog()
+}
+
+/// 元信息卡的标签（与 `app/view/instances.rs` 的 `detail_of` 同一批 key，只是这里恒英文）。
+fn label(key: Key) -> &'static str {
+    catalog().text(key)
+}
+
+/// 把 M84 的演示条目 [`DEMO`] 转成视图模型（真页面走 `app/view.rs` 的 `AppState` 转换）。
+pub(crate) fn demo() -> Instances {
+    let rows = DEMO
+        .iter()
+        .map(|entry| Row {
+            id: entry.name.to_string(),
+            name: entry.name.to_string(),
+            supporting: format!("{} · {}", entry.version, entry.loader),
+            status: None,
+        })
+        .collect();
+
+    let entry = &DEMO[SELECTED];
+    let detail = Detail {
+        id: entry.name.to_string(),
+        name: entry.name.to_string(),
+        subtitle: format!("{} · {}", entry.version, entry.loader),
+        meta: vec![
+            meta(label(Key::InstancesMetaVersion), entry.version),
+            meta(label(Key::InstancesMetaLoader), entry.loader),
+            meta(label(Key::InstancesMetaMemory), entry.memory),
+            meta(label(Key::InstancesMetaJava), entry.java),
+            meta(label(Key::InstancesMetaMods), entry.mods),
+            meta(label(Key::InstancesMetaLastPlayed), entry.last_played),
+        ],
+        note: Some(NOTE.to_string()),
+        status: None,
+        can_launch: true,
+        can_stop: false,
+    };
+
+    Instances {
+        rows,
+        detail: Some(detail),
+    }
+}
+
+fn meta(label: &str, value: &str) -> Meta {
+    Meta {
+        label: label.to_string(),
+        value: value.to_string(),
+    }
+}
diff --git a/crates/app-iced/src/pages/instances/detail.rs b/crates/app-iced/src/pages/instances/detail.rs
new file mode 100644
index 0000000..4d6d41c
--- /dev/null
+++ b/crates/app-iced/src/pages/instances/detail.rs
@@ -0,0 +1,256 @@
+//! 实例页的**详情列**（M90 r2 从 `instances.rs` 拆出来：那边超过 400 行会被 guards 的 file-size 判红）。
+//!
+//! 结构：标题行（名字 + 版本 + Play/Stop）→ 元信息网格（列数由 `layout::meta_columns` 决定）
+//! → 一条分隔线 → 正文段 / 运行状态行 → 动作行（Duplicate / Open folder / Delete）。
+//! 窄窗（<840）时列表退成上一屏，本文件只画详情 + 一个「返回」按钮。
+
+use iced::widget::{column, container, row};
+use iced::{Alignment, Element, Length};
+
+use unlucky_design::color::Role;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+use unlucky_presenter::router::Route;
+
+use crate::app::components::buttons::{self, Button};
+use crate::app::components::divider;
+use crate::app::components::interaction::Interaction;
+use crate::theme::Ui;
+use unlucky_design::icons::IconKind;
+
+use super::super::frame;
+use super::super::layout::{self, FrameMetrics};
+use super::super::model::Detail;
+use super::super::{Action, Message};
+use super::forced_state;
+use super::Texts;
+
+// --------------------------------------------------------------- 详情列
+
+pub(super) fn detail_column<'a>(
+    ui: &'a Ui,
+    metrics: FrameMetrics,
+    detail: &'a Detail,
+    forced: Option<Interaction>,
+    texts: Texts,
+) -> Element<'a, Message> {
+    let mut body = column![
+        detail_head(ui, detail, forced, texts),
+        meta_grid(ui, metrics, detail),
+        divider::full(ui),
+    ]
+    .spacing(ui.space(Space::X4))
+    .width(Length::Fill);
+
+    body = push_text(ui, metrics, body, detail);
+
+    // 页头 + 元信息网格 + **一条**分隔线以下才是正文与操作区（M84 那两条线是占位时期的排版残留）
+    frame::left_aligned(metrics.column, body.push(action_row(ui, forced, texts)))
+}
+
+pub(super) fn narrow_detail<'a>(
+    ui: &'a Ui,
+    metrics: FrameMetrics,
+    detail: &'a Detail,
+    forced: Option<Interaction>,
+    texts: Texts,
+) -> Element<'a, Message> {
+    // 窄窗：列表退成上一屏，本屏只放详情（官方 compact 的 list-detail 口径）。
+    let mut body = column![
+        row![buttons::text(
+            ui,
+            forced_state(
+                Button::new(texts.back(), Message::Navigate(Route::Instances)),
+                forced,
+            ),
+        )]
+        .width(Length::Fill)
+        .align_y(Alignment::Center),
+        detail_head(ui, detail, forced, texts),
+        meta_grid(ui, metrics, detail),
+        divider::full(ui),
+    ]
+    .spacing(ui.space(Space::X4))
+    .width(Length::Fill);
+
+    body = push_text(ui, metrics, body, detail);
+
+    body = body.push(frame::text_role(
+        ui,
+        TypeRole::BodySmall,
+        false,
+        texts.narrow_note(),
+        ui.color(Role::OnSurfaceVariant),
+    ));
+
+    frame::body(metrics, body.push(action_row(ui, forced, texts)))
+}
+
+/// 正文段（演示数据才有）与运行状态行（真数据才有）——两者都是可选的，顺序固定。
+///
+/// 散文段套 [`frame::prose`]：M102 起页面块吃满页宽，但「一行 ≤72 字符」的承诺仍然只由
+/// 散文承担（`frame::body_width` 管块、`metrics.column` 管一句话）。
+fn push_text<'a>(
+    ui: &'a Ui,
+    metrics: FrameMetrics,
+    mut body: iced::widget::Column<'a, Message>,
+    detail: &'a Detail,
+) -> iced::widget::Column<'a, Message> {
+    if let Some(note) = &detail.note {
+        body = body.push(frame::prose(
+            metrics,
+            frame::text_role(
+                ui,
+                TypeRole::BodyMedium,
+                false,
+                note.as_str(),
+                ui.color(Role::OnSurfaceVariant),
+            ),
+        ));
+    }
+    if let Some(status) = &detail.status {
+        body = body.push(frame::text_role(
+            ui,
+            TypeRole::BodyMedium,
+            false,
+            status.as_str(),
+            ui.color(Role::OnSurface),
+        ));
+    }
+    body
+}
+
+fn detail_head<'a>(
+    ui: &'a Ui,
+    detail: &'a Detail,
+    forced: Option<Interaction>,
+    texts: Texts,
+) -> Element<'a, Message> {
+    let titles = column![
+        frame::text_role(
+            ui,
+            TypeRole::TitleLarge,
+            true,
+            detail.name.as_str(),
+            ui.color(Role::OnSurface)
+        ),
+        frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            detail.subtitle.as_str(),
+            ui.color(Role::OnSurfaceVariant),
+        ),
+    ]
+    .spacing(ui.space(Space::X1))
+    .width(Length::Fill);
+
+    // 主操作：**全屏唯一**实心 accent（rubric K2）。不可用时退化成禁用态（只清消息，不改身份）。
+    let launch = if detail.can_launch {
+        buttons::filled(
+            ui,
+            forced_state(
+                Button::new(texts.play(), Message::Launch(detail.id.clone())),
+                forced,
+            ),
+        )
+    } else {
+        buttons::filled(ui, Button::disabled(texts.play()))
+    };
+    let stop = if detail.can_stop {
+        buttons::text(
+            ui,
+            forced_state(
+                Button::new(texts.stop(), Message::Stop(detail.id.clone())),
+                forced,
+            ),
+        )
+    } else {
+        buttons::text(ui, Button::disabled(texts.stop()))
+    };
+
+    row![titles, launch, stop]
+        .spacing(ui.space(Space::X2))
+        .width(Length::Fill)
+        .align_y(Alignment::Center)
+        .into()
+}
+
+/// 元信息网格：列数由 [`layout::meta_columns`]（按正文列宽）决定 —— **1180 与 900 都是 2 列**。
+///
+/// 3 列需要 `3 × META_CARD_MIN_WIDTH + 2 × META_GAP` = 504px，而行宽上限是 424，**数学上不可行**；
+/// 硬塞回 3 列会让 `NeoForge 20.4.237`（118px）这类值按词折行、同排卡底不齐。
+fn meta_grid<'a>(ui: &'a Ui, metrics: FrameMetrics, detail: &'a Detail) -> Element<'a, Message> {
+    let mut grid = column![].spacing(layout::META_GAP).width(Length::Fill);
+    let columns = metrics.meta_columns.clamp(1, detail.meta.len().max(1));
+
+    for chunk in detail.meta.chunks(columns) {
+        let mut cells_row = row![].spacing(layout::META_GAP).width(Length::Fill);
+        for cell in chunk {
+            let card = frame::card(
+                ui,
+                column![
+                    frame::text_role(
+                        ui,
+                        TypeRole::LabelMedium,
+                        false,
+                        cell.label.as_str(),
+                        ui.color(Role::OnSurfaceVariant),
+                    ),
+                    frame::text_role(
+                        ui,
+                        TypeRole::BodyMedium,
+                        false,
+                        cell.value.as_str(),
+                        ui.color(Role::OnSurface)
+                    ),
+                ]
+                .spacing(ui.space(Space::X1))
+                .width(Length::Fill),
+            );
+            cells_row = cells_row.push(container(card).width(Length::Fill));
+        }
+        grid = grid.push(cells_row);
+    }
+
+    grid.into()
+}
+
+fn action_row<'a>(ui: &'a Ui, forced: Option<Interaction>, texts: Texts) -> Element<'a, Message> {
+    row![
+        buttons::text(
+            ui,
+            forced_state(
+                Button::new(texts.duplicate(), Message::Action(Action::Duplicate)),
+                forced,
+            )
+        ),
+        buttons::text(
+            ui,
+            forced_state(
+                Button::new(texts.open_folder(), Message::Action(Action::OpenFolder)),
+                forced,
+            )
+        ),
+        buttons::text(
+            ui,
+            forced_state(
+                Button::new(texts.delete(), Message::Action(Action::Delete)),
+                forced
+            ),
+        ),
+    ]
+    .spacing(ui.space(Space::X2))
+    .align_y(Alignment::Center)
+    .into()
+}
+
+pub(super) fn detail_empty<'a>(ui: &'a Ui, texts: Texts) -> Element<'a, Message> {
+    frame::empty_state(
+        ui,
+        IconKind::Instances,
+        texts.empty_title(),
+        texts.empty_body(),
+        Vec::new(),
+    )
+}
diff --git a/crates/app-iced/src/pages/instances/tests.rs b/crates/app-iced/src/pages/instances/tests.rs
new file mode 100644
index 0000000..0385462
--- /dev/null
+++ b/crates/app-iced/src/pages/instances/tests.rs
@@ -0,0 +1,224 @@
+//! `instances` 的断言：演示数据、窄窗退化，以及**页面摆法**（源码结构断言）。
+use super::*;
+
+/// M120 的文案守门（中文无英文词 / 切语言真的变 / 页面里不许写死英文案·白名单）。
+mod i18n;
+
+use super::super::layout::source;
+use super::super::layout::{frame_metrics, measure_cap_px, PaneKit, WidthClass};
+
+/// **M102 几何判据**：列表可视区正好放下整数行——末行不会被卡片底边切半行。
+///
+/// 算式里的三个页面真源**直接引用**（不写字面量），所以改页面常量会让这条立刻红：
+/// [`LIST_BOTTOM_INSET`]（滚动区底部内缩）、[`ROW_SPACING`]（页级行距，`None` = 0）。
+///
+/// ```text
+/// 卡片高 = 760 − 标题栏 48 − 两行页头 84 − 2×gutter 24      = 580
+/// 列头   = 上 12 + LabelMedium 16 + 下 4                     = 32
+/// 内缩   = LIST_BOTTOM_INSET = Space::X2                     = 8
+/// 可视区 = 580 − 32 − 8                                      = 540
+/// 行高   = ListItem 两行档 44 + 16                           = 60
+/// pitch  = 行高 + ROW_SPACING（None ⇒ 0）                    = 60
+/// 整行数 = 540 / 60                                          = 9 行整
+/// ```
+///
+/// **抓得住**：页面把内缩换档（`LIST_BOTTOM_INSET` → `X1` 立刻除不尽）、行距真源被改、
+/// 列头算错、演示数据被缩到不够滚（独立滚动条消失）；
+/// **抓不住**：`list_column()` 里被另写一层 `.spacing(…)`（那一条由
+/// `list_column_spaces_rows_only_from_the_shared_constant` 扫源码守）。
+#[test]
+fn list_viewport_fits_whole_rows_and_still_overflow() {
+    use unlucky_design::spacing::LayoutMetrics;
+    use unlucky_design::typography::TypeRole;
+
+    let lm = LayoutMetrics::DESKTOP;
+    let gutter = WidthClass::Expanded.gutter();
+
+    let card = 760.0 - lm.titlebar_height - lm.header_height(true) - 2.0 * gutter;
+    assert_eq!(card, 580.0, "1180×760 下列表卡片的内部高度");
+
+    let head = Space::X3.dp() + TypeRole::LabelMedium.style().line_height_px + Space::X1.dp();
+    let viewport = card - head - LIST_BOTTOM_INSET.dp();
+    assert_eq!(viewport, 540.0, "列表滚动区高度必须以页面的内缩真源算");
+
+    // 页级行距的**唯一真源**：None = 这一层不加间距
+    let gap = ROW_SPACING.map_or(0.0, Space::dp);
+    let row = lm.row_height + Space::X4.dp();
+    let pitch = row + gap;
+    assert_eq!(pitch, 60.0, "行节奏 = ListItem 两行档 60（不留页级行距）");
+    assert_eq!(
+        viewport % pitch,
+        0.0,
+        "可视区 {viewport} 不是 {pitch} 的整数倍 ⇒ 末行会被切半行（ROW_SPACING={ROW_SPACING:?}）"
+    );
+
+    // 同时必须还能滚：12 行内容高过可视区，截图里才看得到独立滚动条
+    let content = DEMO.len() as f32 * pitch;
+    assert!(
+        content > viewport,
+        "列表内容 {content} 不比可视区 {viewport} 高，截图里看不到独立滚动条"
+    );
+}
+
+/// **源码结构**：`list_column()` 里对行容器的间距**只能**来自 [`ROW_SPACING`]。
+///
+/// 为什么读源码：变异实测（M102 r1）把 `.spacing(ui.space(Space::X1))` 加回行容器后，
+/// 几何断言照样绿——它算的是常量，看不见页面又叠了一层。iced 的 Element 又没有内省接口，
+/// 所以只能断言这段代码的形状。
+///
+/// ## 两层判据（r4 复审的 M4 订正）
+///
+/// | 层 | 判据 | 抓的是 |
+/// |---|---|---|
+/// | ① 构建链 | `let mut rows = column(…);` 这条语句链上不许有 `.spacing(` | 直接写在链上的间距（变异 D） |
+/// | ② 语句序列 | `list_column()` 里**每一处** `rows.spacing(…)` 的实参都要**顺绑定追回 `ROW_SPACING`** | **另起一条语句**再叠间距（变异 M4，含「先把令牌挪进一条 `let`」的写法） |
+///
+/// 为什么②要追绑定而不是比字面：合法写法有几种形状——`rows = rows.spacing(ui.space(spacing))`
+/// 直接取自 `if let Some(spacing) = ROW_SPACING`，或先 `let spacing = ROW_SPACING;` 再中转
+/// （变异 H3）。`layout/source.rs::derived_from` 顺 `let` / `Some(…) =` 两种绑定往回追最多三跳，
+/// 于是「真源」放行、「中转了一层 `Space::X1`」判否。
+///
+/// **抓得住**：构建链上的字面量间距（D）、另起语句的行距（M4）、`ROW_SPACING` / `LIST_BOTTOM_INSET`
+/// 两个真源被摘掉；`column![head, scroller]` 上的合法间距不受影响（变异 J，绿）；
+/// **抓不住**：把间距算进别处再以非令牌形式传进 `list_row()`（那要改组件几何，代码评审能看出来）、
+/// 以及绕过 `rows.spacing(…)` 这个调用形状的写法。
+#[test]
+fn list_column_spaces_rows_only_from_the_shared_constant() {
+    let file = include_str!("../instances.rs");
+    let body = source::function_region(file, "fn list_column");
+    let rows_chain = source::statement(file, "let mut rows = column(");
+
+    assert!(
+        body.contains("ROW_SPACING"),
+        "列表行距必须从 ROW_SPACING 取，不许另写：\n{body}"
+    );
+    assert!(
+        body.contains("LIST_BOTTOM_INSET"),
+        "底部内缩必须从 LIST_BOTTOM_INSET 取：\n{body}"
+    );
+
+    // ① 行容器的构建链上不许叠间距（`column![head, scroller]` 上的合法间距不在这条链里）
+    assert!(
+        !rows_chain.contains(".spacing("),
+        "行容器的构建链上又出现了间距（M102 ② 的页级附加量）：\n{rows_chain}"
+    );
+
+    // ② 语句序列：每一处 `rows.spacing(…)` 的实参都必须**顺绑定追回 `ROW_SPACING`**
+    //    （直接用它、或 `let spacing = ROW_SPACING` 再中转都算；先 `let extra = Space::X1;`
+    //     再 `rows.spacing(ui.space(extra))` 则红——r4 复审的变异 M4）
+    let applied = source::call_arguments(&body, "rows.spacing(");
+    assert!(
+        !applied.is_empty(),
+        "`list_column()` 里没有把 ROW_SPACING 应用到行容器的调用：\n{body}"
+    );
+    for argument in &applied {
+        let ident = argument
+            .split_once("ui.space(")
+            .map(|(_, rest)| rest)
+            .unwrap_or(argument);
+        let ident: String = ident
+            .chars()
+            .take_while(|ch| ch.is_alphanumeric() || *ch == '_')
+            .collect();
+
+        assert!(
+            argument.contains("ui.space("),
+            "行容器的间距实参必须走令牌栅格（`ui.space(…)`），收到 {argument:?}"
+        );
+        assert!(
+            !argument.contains("Space::"),
+            "行容器的间距实参里直接写了令牌档位：{argument:?}\n{body}"
+        );
+        assert!(
+            source::derived_from(&body, &ident, "ROW_SPACING"),
+            "行容器的间距不是从 ROW_SPACING 来的（`{ident}` 追不到 ROW_SPACING）——\
+             M102 ② 的页级附加量不许另起一条语句塞回来：{argument:?}\n{body}"
+        );
+    }
+}
+
+/// **散文接线**：详情页的正文段必须进 `frame::prose`（424），不许直接塞进 `frame::body`（1044）。
+///
+/// M102 把「块宽」与「散文列宽」拆成两个量之后，接错一行代码就会让 361 字符的正文在 1180 窗宽下
+/// 排成 170 字符一行，而不红任何测试。这条断言把接线本身钉住。
+#[test]
+fn the_detail_note_goes_through_the_prose_box() {
+    let body = source::function_body(include_str!("../instances/detail.rs"), "fn push_text");
+
+    assert!(
+        body.contains("frame::prose("),
+        "正文段没有走 frame::prose：\n{body}"
+    );
+    assert!(
+        !body.contains("frame::body("),
+        "正文段被塞进了整页块（会失去 72 字符行宽承诺）：\n{body}"
+    );
+}
+
+/// 元信息卡必须装得下**卡内最长的那条值**（视觉 r2：136 漏算 padding，版本串折行让卡底不齐）。
+#[test]
+fn meta_card_is_wide_enough_for_the_longest_value() {
+    use super::super::layout::{measure_cap_px, META_CARD_MIN_WIDTH, META_GAP};
+    use unlucky_design::spacing::LayoutMetrics;
+
+    // 实测（Segoe UI 14px）：demo 数据里最宽的元信息值是加载器版本串
+    const LONGEST_VALUE: &str = "NeoForge 20.4.237";
+    const LONGEST_VALUE_PX: f32 = 118.0;
+
+    let padding = LayoutMetrics::DESKTOP.card_padding;
+    assert_eq!(padding, 20.0, "卡内边距来自令牌");
+
+    // 夹具与 demo 数据不许脱节：这个值必须真在 DEMO 里
+    assert!(
+        DEMO.iter().any(|entry| entry.loader == LONGEST_VALUE),
+        "夹具 {LONGEST_VALUE:?} 已经不在 DEMO 里了，请重新量最长值"
+    );
+
+    // ① 单卡外框减掉两侧内边距，必须放得下这条值（否则 text 会按词折行 → 卡底不齐）
+    let inner = META_CARD_MIN_WIDTH - 2.0 * padding;
+    assert!(
+        inner >= LONGEST_VALUE_PX,
+        "卡内可用 {inner}px 装不下 {LONGEST_VALUE_PX}px 的 {LONGEST_VALUE:?}（外框 {META_CARD_MIN_WIDTH} − 2×{padding}）"
+    );
+
+    // ② 实际版面里每张卡的内宽（2 列时）也要够
+    let two_columns = (measure_cap_px() - META_GAP) / 2.0;
+    assert!(
+        two_columns - 2.0 * padding >= LONGEST_VALUE_PX,
+        "两列布局下卡内可用 {}px 装不下 {LONGEST_VALUE_PX}px",
+        two_columns - 2.0 * padding
+    );
+}
+
+#[test]
+fn every_demo_entry_has_name_version_and_loader() {
+    for entry in &DEMO {
+        assert!(!entry.name.is_empty());
+        assert!(!entry.version.is_empty());
+        assert!(!entry.loader.is_empty());
+    }
+    assert!(SELECTED < DEMO.len());
+}
+
+#[test]
+fn detail_paragraph_is_long_enough_to_wrap() {
+    // 行宽上限 ≈ 72 字符/行；写够几行才看得出断行位置
+    assert!(NOTE.len() > 200, "正文档太短，看不出行宽上限");
+}
+
+#[test]
+fn narrow_widths_switch_the_page_to_one_column() {
+    // 1180 / 900 → 两列；700 → 单列（整页切换）
+    assert_eq!(
+        frame_metrics(PaneKit::ListDetail, 1180.0).layout,
+        PageLayout::ListDetail
+    );
+    assert_eq!(
+        frame_metrics(PaneKit::ListDetail, 700.0).layout,
+        PageLayout::SingleColumn
+    );
+    // 窄窗下详情不吃满窗口：正文列仍 ≤ 行宽上限
+    let narrow = frame_metrics(PaneKit::ListDetail, 700.0);
+    assert!(narrow.column <= measure_cap_px() + f32::EPSILON);
+    assert!(narrow.secondary.is_none());
+}
diff --git a/crates/app-iced/src/pages/instances/tests/i18n.rs b/crates/app-iced/src/pages/instances/tests/i18n.rs
new file mode 100644
index 0000000..4e96787
--- /dev/null
+++ b/crates/app-iced/src/pages/instances/tests/i18n.rs
@@ -0,0 +1,271 @@
+//! 实例页的**文案守门**（M120）：中文态不许漏英文、切语言必须真的变、运行状态的数字不许变形。
+//!
+//! | 用例 | 抓得住什么 |
+//! |---|---|
+//! | [`the_chinese_page_has_no_english_words`] | 目录里某条中文忘了翻（或翻完还留着英文词） |
+//! | [`every_instances_text_changes_with_the_language`] | 两套语言写成一样（= 切换语言时那一处不动，看着像「已 i18n」其实是死文案） |
+//! | [`the_running_line_keeps_its_number_and_separator`] | `Running · pid 1234` 的数字 / `pid` / `·` 被翻译走样 |
+//! | [`every_english_literal_in_the_page_sources_is_whitelisted`] | 页面里写死**任何**英文（旧串或新写的，白名单判定；r1 之前是黑名单，对新写的英文是哑的） |
+//! | [`every_instances_key_is_referenced_by_the_page`] | 目录里加了 key、页面没人用（死 key，M117 那七条就是这么来的） |
+//!
+//! ## 边界（别把这张表读成「视图覆盖」）
+//!
+//! iced 0.14 的 `Element` **没有内省接口**（`instances/tests.rs` 里那条「为什么读源码」写的就是它），
+//! 所以「上屏文本」取样只能从页面取词的那**一个入口** [`Texts`] 拿：页面用它画、测试用同一个
+//! `Texts` 断言，不是另写一份平行实现。「页面又冒出一条**新**硬编码英文字面量」由
+//! [`every_english_literal_in_the_page_sources_is_whitelisted`] 兜（白名单）；**中文**写死的
+//! 字面量它看不见，那只能靠 `Texts::of(` 的反向锚与出图人工看。
+//! 「模型这一层（快照 → 状态行 / 元信息）跟着 `Lang` 变」由 `app/view/tests.rs` 守。
+
+use unlucky_i18n::catalog::MISSING;
+use unlucky_i18n::{Catalog, Key, Lang};
+
+use super::super::Texts;
+
+/// 中文界面里允许出现的 ASCII 词：**品牌名与技术标识**。
+///
+/// 每一条都要说清为什么：
+///
+/// - `Java`：运行时品牌名（`JAVA` 那格的值域里也全是 `Temurin 21` 这类品牌串），翻成「爪哇」是错的；
+/// - `pid`：进程号的技术标识。用户拿它去任务管理器里搜进程，翻成「进程」就丢了这条可操作性。
+const ALLOWED: &[&str] = &["Java", "pid"];
+
+/// 页面取词的五个源码文件（死 key 扫描与旧串扫描共用）。
+const PAGE_SOURCES: [(&str, &str); 5] = [
+    ("instances.rs", include_str!("../../instances.rs")),
+    ("instances/detail.rs", include_str!("../detail.rs")),
+    ("instances/demo.rs", include_str!("../demo.rs")),
+    ("instances/text.rs", include_str!("../text.rs")),
+    (
+        "app/view/instances.rs",
+        include_str!("../../../app/view/instances.rs"),
+    ),
+];
+
+/// 页面五件套里**允许出现的字符串字面量**（凡是带 ASCII 单词的都必须在这张表里）。
+///
+/// M120 r1 复审实测出黑名单的哑点：只兜「已知的 29 条旧串」时，往页面里**新写一句英文**
+/// 照样 612/612 + 12/12 全绿。判据现在反过来——**白名单**：页面源码里每个带 ASCII 单词的
+/// 字面量都要在这里找到归宿，新写一句英文立刻红。
+///
+/// 全部 6 条都写了理由（剩下一批 `"{} · {}"` / `"{} · {:.0}%"` / `"{} {}"` 这类格式化模板
+/// **连一个词都没有**，所以不需要条目）：
+///
+/// | 字面量 | 为什么它可以是英文 |
+/// |---|---|
+/// | `{date} {time} UTC` | `UTC` 是时区缩写，不是界面文案（本地时区换算属时间格式 mission） |
+/// | `isolated` / `shared` | core 的隔离档位**稳定 id**（`IsolationMode::as_str`），`isolation()` 只认这两档，其余原样上屏 |
+/// | `pid` / `reason` | `Catalog::render` 的**占位符名**（与 catalog 里的 `{pid}` / `{reason}` 对应） |
+/// | `Instances` | `Texts::keys()` 的**族名前缀**（`Key::ALL` 的过滤条件，不是文案） |
+const ALLOWED_LITERALS: [&str; 6] = [
+    "{date} {time} UTC",
+    "isolated",
+    "shared",
+    "pid",
+    "reason",
+    "Instances",
+];
+
+/// 抽出源码里的字符串字面量（够用的实现：本仓这五个文件没有 `\"` 转义、没有多行字符串）。
+///
+/// 按 `"` 切开取**奇数段**即可：`a"b"c"d"e` → 段 1 = `b`、段 3 = `d`。
+fn string_literals(source: &str) -> Vec<&str> {
+    source.split('"').skip(1).step_by(2).collect()
+}
+
+/// 把 `{占位符}` 抹掉再切 ASCII 词：占位符是**运行时数据**（pid / 原因 / 时间），不是文案。
+fn ascii_words(text: &str) -> Vec<String> {
+    let mut stripped = String::new();
+    let mut depth = 0usize;
+    for ch in text.chars() {
+        match ch {
+            '{' => depth += 1,
+            '}' if depth > 0 => depth -= 1,
+            _ if depth > 0 => {}
+            _ => stripped.push(ch),
+        }
+    }
+
+    let mut words = Vec::new();
+    let mut current = String::new();
+    for ch in stripped.chars() {
+        if ch.is_ascii_alphabetic() {
+            current.push(ch);
+        } else if !current.is_empty() {
+            words.push(std::mem::take(&mut current));
+        }
+    }
+    if !current.is_empty() {
+        words.push(current);
+    }
+    words
+}
+
+/// 有没有中日韩统一表意文字（「这条文案真的翻成中文了吗」的最直接判据）。
+fn has_cjk(text: &str) -> bool {
+    text.chars().any(|c| {
+        matches!(c, '\u{3400}'..='\u{4DBF}' | '\u{4E00}'..='\u{9FFF}' | '\u{3000}'..='\u{303F}')
+    })
+}
+
+/// **中文界面无英文词**：实例页这一族的每一条中文译文，除了 [`ALLOWED`] 之外不许出现 ASCII 单词。
+///
+/// 抓得住：漏翻（中英写成一样）、翻了一半（`Present on disk` → `已在磁盘上 Present`）、
+/// 新加 key 时中文那栏顺手抄了英文。
+/// 抓不住：译文本身读着别扭；也抓不住「页面另写了一条字面量」（见模块文档的边界一节）。
+///
+/// **变异实测**（M120 交付时跑过）：把 `InstancesPresentOnDisk` 的中文改回 `Present on disk`，
+/// 这条立刻红并指出 key 名。
+#[test]
+fn the_chinese_page_has_no_english_words() {
+    let zh = Lang::ZhCn.catalog();
+    let mut offenders = Vec::new();
+    let mut checked = 0;
+
+    for key in Texts::keys() {
+        let text = zh.text(key);
+        assert_ne!(text, MISSING, "{} 没有中文译文", key.name());
+        checked += 1;
+        for word in ascii_words(text) {
+            if !ALLOWED.contains(&word.as_str()) {
+                offenders.push(format!("{} · 出现 {word:?} ← 「{text}」", key.name()));
+            }
+        }
+    }
+
+    assert!(
+        offenders.is_empty(),
+        "中文界面上这些英文词会漏出来（品牌名 / 技术标识请加进 ALLOWED 并写明理由）：\n{}",
+        offenders.join("\n")
+    );
+    assert!(
+        checked >= 30,
+        "实例页的 key 不该被成批删掉（只查到 {checked} 条）"
+    );
+}
+
+/// **切换语言，文本真的变**：这一族的每一条中英译文都必须不同。
+///
+/// 抓得住：翻完没改（两栏抄同一句）——那种 key 在切语言时**一个字都不动**，界面上看起来
+/// 「已经国际化」，其实那一处永远是英文。今夜反复出现的「测试绿着但什么都没守住」就是这一类。
+/// 抓不住：某条译文翻错了词。
+#[test]
+fn every_instances_text_changes_with_the_language() {
+    let en = Lang::En.catalog();
+    let zh = Lang::ZhCn.catalog();
+
+    for key in Texts::keys() {
+        let (a, b) = (en.text(key), zh.text(key));
+        assert_ne!(a, MISSING, "{} 没有英文译文", key.name());
+        assert_ne!(b, MISSING, "{} 没有中文译文", key.name());
+        assert_ne!(
+            a,
+            b,
+            "{} 的两套语言写成了一样（{a:?}）——切语言时这一处不会变",
+            key.name()
+        );
+        // 中文那栏必须真的有汉字——**整句只有品牌名时例外**（`InstancesMetaJava` = "Java"：
+        // 那一格的值域是 `Temurin 21` 这种品牌串，翻成「爪哇」是错的）。
+        let brand_only = {
+            let words = ascii_words(b);
+            !words.is_empty() && words.iter().all(|word| ALLOWED.contains(&word.as_str()))
+        };
+        assert!(
+            has_cjk(b) || brand_only,
+            "{} 的中文译文里一个汉字都没有：{b:?}",
+            key.name()
+        );
+    }
+}
+
+/// **数字与分隔符不随语言变形**：`Running · pid 1234` 的两套语言只换前半句。
+///
+/// 抓得住：把 `pid` 翻成「进程」、把 `·` 换成 `-`、把 `{pid}` 写成固定文字、少一个空格。
+/// 抓不住：真实 pid 的取值（那是 core 的事，出图那台机器上也没真跑过）。
+#[test]
+fn the_running_line_keeps_its_number_and_separator() {
+    let en = Catalog::of(Lang::En).render(Key::InstancesRunning, &[("pid", "1234")]);
+    let zh = Catalog::of(Lang::ZhCn).render(Key::InstancesRunning, &[("pid", "1234")]);
+
+    assert_eq!(en, "Running · pid 1234");
+    assert_eq!(zh, "运行中 · pid 1234");
+    assert_ne!(en, zh, "切换语言时这一行要变（只换标签本体）");
+    for text in [en, zh] {
+        assert!(text.contains("1234"), "数字丢了：{text}");
+        assert!(text.contains(" · pid "), "分隔符或 pid 变形了：{text}");
+    }
+
+    // 失败那一行同理：core 给的原因原文原样保留，只翻前半句
+    let failed_en = Catalog::of(Lang::En).render(Key::InstancesFailed, &[("reason", "exit 1")]);
+    let failed_zh = Catalog::of(Lang::ZhCn).render(Key::InstancesFailed, &[("reason", "exit 1")]);
+    assert_eq!(failed_en, "Launch failed · exit 1");
+    assert_eq!(failed_zh, "启动失败 · exit 1");
+}
+
+/// **页面里不许再写死界面文案**（白名单）：带 ASCII 单词的字面量必须在 [`ALLOWED_LITERALS`] 里。
+///
+/// 抓得住：①M120 之前那 29 条旧串被抄回页面（它们都带英文词 ⇒ 不在白名单 ⇒ 红）；
+/// ②**任何新写的英文字面量**（r1 复审抓到的哑点：黑名单版本把 `"Ready"` 写进页面是全绿的）。
+/// 抓不住：中文写死的字面量（`"实例"` 没有 ASCII 词）——那要靠 `Texts::of(` 的反向锚与出图；
+/// 也抓不住夹具数据（`pages/instances/data.rs` 故意不在扫描范围：那是**用户数据**的样子，
+/// 不是界面文案，见该文件的模块文档）。
+///
+/// **变异实测（M120 r1 交付时跑过三条）**：写回 `"ALL INSTANCES"` ⇒ 红；写进一条全新的
+/// `"Ready"` ⇒ 红；把 `Texts::of(` 从实例页删掉 ⇒ 反向锚红。
+#[test]
+fn every_english_literal_in_the_page_sources_is_whitelisted() {
+    let mut checked = 0;
+    for (name, source) in PAGE_SOURCES {
+        for literal in string_literals(source) {
+            if ascii_words(literal).is_empty() {
+                continue;
+            }
+            checked += 1;
+            assert!(
+                ALLOWED_LITERALS.contains(&literal),
+                "{name} 里的字面量 {literal:?} 带 ASCII 单词但不在白名单里：界面文案要走 Texts / 目录；确属专有名词的话加进 ALLOWED_LITERALS 并写明理由"
+            );
+        }
+    }
+
+    // 反向锚①：扫描器真的扫到了东西（否则上面那个循环是空转）
+    assert!(
+        checked >= 6,
+        "只扫到 {checked} 条带英文的字面量，扫描器可能失效了"
+    );
+
+    // 反向锚②：这些来源**必须**真的在用 Texts / 目录
+    assert!(
+        PAGE_SOURCES[0].1.contains("Texts::of("),
+        "实例页没有从 Texts 取词"
+    );
+    assert!(
+        PAGE_SOURCES[0].1.contains("Header::new(texts.title())"),
+        "页头标题必须是词表里的那条（`Header::new` 里写死字符串 = 中文界面上顶着英文标题）"
+    );
+    assert!(
+        PAGE_SOURCES[3].1.contains("Key::Instances"),
+        "text.rs 没有引用本族的 key"
+    );
+    assert!(
+        PAGE_SOURCES[4].1.contains("Key::InstancesStage"),
+        "阶段标签没有走目录"
+    );
+}
+
+/// **死 key 守门**：目录里每一条 `Instances*` 都必须被页面（或产品快照转换）真的引用。
+///
+/// M117 加的那七条就是这么沉的：目录里写着，页面上一个都没用。扫描是字面出现的
+/// `Key::<名字>`，所以用宏拼 key 名能骗过它——这个局限写在这里，不假装它更强。
+#[test]
+fn every_instances_key_is_referenced_by_the_page() {
+    for key in Texts::keys() {
+        let needle = format!("Key::{}", key.name());
+        assert!(
+            PAGE_SOURCES
+                .iter()
+                .any(|(_, source)| source.contains(&needle)),
+            "{needle} 在目录里定义了，但实例页没有任何地方用它（死 key，删掉或接上）"
+        );
+    }
+}
diff --git a/crates/app-iced/src/pages/instances/text.rs b/crates/app-iced/src/pages/instances/text.rs
new file mode 100644
index 0000000..b792445
--- /dev/null
+++ b/crates/app-iced/src/pages/instances/text.rs
@@ -0,0 +1,103 @@
+//! 实例页的**文案入口**：页面上一处可见英文字面量都不留，全部从目录取。
+//!
+//! ## 为什么要有这一层（而不是在控件树里直接 `catalog.text(..)`）
+//!
+//! 页面要的文案有 20 多条，直接写的话每个调用点都是「key 名 + 这一处画什么」的重复劳动，
+//! 而且**守门测试没法取样**：iced 0.14 的 `Element` 没有内省接口（`instances/tests.rs` 里
+//! 「读源码」那条注释解释过同一件事），所以「上屏文本」只能从**页面取词的那一个入口**拿。
+//! 于是所有取词收进 [`Texts`]，页面用 `texts.xxx()` 画，测试用同一个 `Texts` 断言——
+//! 一处定义、两处消费，不存在「测试抄了一份平行实现」。
+//!
+//! ## 它抓得住什么 / 抓不住什么
+//!
+//! - **抓得住**：目录里某条中文忘了翻（「无 ASCII 英文单词」）、某条中英写成一样（「切换语言文本真的变」）、
+//!   `Running · pid {pid}` 的数字与分隔符被翻译走样、页面里写死**英文**字面量
+//!   （`every_english_literal_in_the_page_sources_is_whitelisted`，白名单判定）；
+//! - **抓不住**：页面里写死的**中文**字面量（没有 ASCII 词，扫不到）、`PAGE_SOURCES` 五个文件
+//!   之外的东西（如 `data.rs` 夹具数据）、译文翻得顺不顺——这些只能靠出图人工看
+//!   （`DevDocs/artifacts/m120/`）。
+//!
+//! ## 口径
+//!
+//! 品牌名不翻译（`Java` / `Fabric` / `Forge` 原样）；`pid` 是进程号的技术标识，两套语言都写
+//! `pid`（改成「进程」会丢掉「拿它去任务管理器里搜」这条可操作性）。
+//!
+//! **启动阶段（下载中 / 校验中 / …）不在这张表里**：它在 `app/view/instances.rs` 拼进
+//! `Row.status`（「阶段 · 百分比」是一整句），与元信息卡同一层——页面只画模型给的字符串。
+
+use unlucky_i18n::{Catalog, Key};
+
+/// 实例页 + 详情列的文案（一个 `Catalog` 的薄包装，`Copy`）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) struct Texts(Catalog);
+
+impl Texts {
+    /// 从目录取一套（调用方给 `model.lang.catalog()`）。
+    pub(super) fn of(catalog: Catalog) -> Self {
+        Self(catalog)
+    }
+
+    // ------------------------------------------------------------- 页头
+    pub(super) fn title(self) -> &'static str {
+        self.text(Key::InstancesTitle)
+    }
+    pub(super) fn subtitle(self) -> &'static str {
+        self.text(Key::InstancesSubtitle)
+    }
+    pub(super) fn new_instance(self) -> &'static str {
+        self.text(Key::InstancesNew)
+    }
+    pub(super) fn import(self) -> &'static str {
+        self.text(Key::InstancesImport)
+    }
+
+    // --------------------------------------------------------------- 列表列
+    pub(super) fn all_title(self) -> &'static str {
+        self.text(Key::InstancesAllTitle)
+    }
+
+    // --------------------------------------------------------------- 详情列
+    pub(super) fn back(self) -> &'static str {
+        self.text(Key::InstancesBack)
+    }
+    pub(super) fn play(self) -> &'static str {
+        self.text(Key::InstancesPlay)
+    }
+    pub(super) fn stop(self) -> &'static str {
+        self.text(Key::InstancesStop)
+    }
+    pub(super) fn duplicate(self) -> &'static str {
+        self.text(Key::InstancesDuplicate)
+    }
+    pub(super) fn open_folder(self) -> &'static str {
+        self.text(Key::InstancesOpenFolder)
+    }
+    pub(super) fn delete(self) -> &'static str {
+        self.text(Key::InstancesDelete)
+    }
+    pub(super) fn empty_title(self) -> &'static str {
+        self.text(Key::InstancesEmptyTitle)
+    }
+    pub(super) fn empty_body(self) -> &'static str {
+        self.text(Key::InstancesEmptyBody)
+    }
+    pub(super) fn narrow_note(self) -> &'static str {
+        self.text(Key::InstancesNarrowNote)
+    }
+
+    fn text(self, key: Key) -> &'static str {
+        self.0.text(key)
+    }
+
+    /// 这一页的全部 key（守门测试的取样口：**从 `Key::ALL` 过滤出来**，不是手抄一份清单）。
+    ///
+    /// 域判据是前缀 `Instances`——本族的 key 名是契约（`catalog/instances.rs` 里一条一条写着），
+    /// 新加的 key 只要还在这个族里就自动进守门范围，不需要有人记得来登记。
+    #[cfg(test)]
+    pub(super) fn keys() -> impl Iterator<Item = Key> {
+        Key::ALL
+            .iter()
+            .copied()
+            .filter(|key| key.name().starts_with("Instances"))
+    }
+}
diff --git a/crates/app-iced/src/pages/layout.rs b/crates/app-iced/src/pages/layout.rs
new file mode 100644
index 0000000..4c55fed
--- /dev/null
+++ b/crates/app-iced/src/pages/layout.rs
@@ -0,0 +1,399 @@
+//! 页面布局系统：**窗口宽度档位 → 版面 → 列宽**。纯函数，不碰 iced 控件树。
+//!
+//! 这是本 mission 的核心交付物，四个页面只是它的用例。`layout.rs` 是页面级几何的
+//! **唯一定义点**：页面文件里不许再出现列宽字面量。
+//!
+//! ## 1. 宽度档位（官方响应式断点 600 / 840）
+//!
+//! 档位定义照官方 M3「Window size classes」（A 级：m3.material.io 的 app-quality/window-size-classes，
+//! Compose `WindowSizeClass` 的同一组硬值）：**600dp 与 840dp** 是两个分界。
+//!
+//! | 档位 | 窗口宽度（逻辑 px @100% DPI） | 页边距（gutter） |
+//! |---|---|---|
+//! | `Compact` | `< 600` | 16（`Space::X4`） |
+//! | `Medium` | `600 ≤ w < 840` | 24（`Space::X6`） |
+//! | `Expanded` | `≥ 840` | 24（`Space::X6`） |
+//!
+//! 页边距取 16/24 而不是 16/24/32：官方 expanded 页边距也是 24，写 32 会白白多一条偏离登记。
+//!
+//! > 本 crate 的真实窗口下限是 880（`app.rs` 的 `MIN_SIZE`），所以日常只有 `Expanded`；
+//! > 600 以下的档位是给「将来允许更窄窗口 / 内嵌面板」准备的，也让布局规则**可测**。
+//!
+//! ## 2. 三种版面与「什么宽度用哪种」
+//!
+//! | 版面 | 含义 | 页面上用它 | 成立条件 | 退化到 |
+//! |---|---|---|---|---|
+//! | `SingleColumn` | 单列，列宽 ≤ 行宽上限 | 下载 / 日志（全部档位）；实例 / 设置（窄窗） | 总是成立 | — |
+//! | `SupportingPane` | 主列 + 窄侧列（侧列是辅助，主列是阅读对象） | 设置（分组导航 240 + 表单列） | `w ≥ 600` 且 `w ≥ 720` | `SingleColumn` |
+//! | `ListDetail` | 固定列表列（320~360，**独立滚动**）+ 详情列 | 实例 | `w ≥ 840` 且 `w ≥ 816` | `SingleColumn` |
+//!
+//! 两个门槛都是**算出来的**，不是拍的（见 [`panes_min_window`]）：
+//!
+//! - 设置：`240（drawer）+ 24（间隙）+ 320（表单列下限）+ 2×24（gutter）+ 88（rail）= 720`；
+//! - 实例：`336（列表列）+ 24（间隙）+ 320（详情列下限）+ 2×24（gutter）+ 88（rail）= 816`。
+//!
+//! 实例的几何门槛 816 低于官方 expanded 断点 840 —— 所以**档位是更严的那一条**，
+//! 单测 `expanded_is_wide_enough_for_list_detail` 把这条「余量 24px」钉死。
+//!
+//! ## 3. 行宽约束（历史事故：M68 的全宽单卡）
+//!
+//! M68 骨架的内容区是**一张全宽卡**：卡片横跨 x=112..1156（**1044px**），卡片内文本区 **1004px**
+//! （边距 24 + 卡片内边距 20）。那张卡里的正文是 `BodySmall` 12px：步进 = 14px 实测值
+//! 6.0526 × 12/14 = **5.19px/字符**，所以 137 字符 × 5.19 ≈ **711px** —— 与
+//! `DevDocs/ops/screens-m68/shell-light-cpu.png` 里那一行**实测 ink 712px**（x=133..845）吻合。
+//! 视觉复审的判词因此是「**不能把全宽单卡当页面模板**，官方桌面口径是 supporting-pane / list-detail」。
+//!
+//! > **两个订正记录**（P2 复审抓出）：① **712 是那行的墨迹宽，不是列宽**（列宽 1004；旧文档的减法得 1044）；
+//! > ② 那行是 **137 字符**（12px × 0.4323em = 5.19px/字符），早期拿 `0.5em` 估算既高估步进、也错了字号。
+//! > 现在事故描述一律用**实测步进 × 实际字号**——这也是 `line_length_is_capped_at_72_characters`
+//! > 里那条「旧口径 504px 能放 83 字符」护栏的由来。
+//!
+//! ### 逐行口径：72 字符是**最长一行**的上界，不是平均（r2 复审的教训）
+//!
+//! 「平均步进 × 72」只能保证**平均**一行 72 字符：r2 复审在交付图里抓到一行 **73 字符**
+//! （`guess. Nothing on this page is wired to real data yet: the layout is, the`，ink 428px）。
+//! 所以上限**不是算术结果，而是逐行折行模拟的结果**——用 FreeType 量宽 + 贪心词折行，
+//! 对实例页那段正文（361 字符）扫不同列宽：
+//!
+//! | 列宽 | 最长一行 | 该行 ink | 结论 |
+//! |---|---|---|---|
+//! | 435（= 平均口径上界） | 73 字符 | 428px | ✗ 破了 72 |
+//! | 428 | 73 字符 | 428px | ✗ |
+//! | 426 | 71 字符 | 426px | ✓ 但只剩 1 字符余量 |
+//! | **424**（4px 栅格） | **67 字符** | **402px** | ✓ 取这个：满足上界 + 留 5 字符余量 |
+//!
+//! 于是 [`measure_cap_px`] = **424**（= `min(逐行安全宽 424, 平均口径上界 435)`），由
+//! [`content_column_width`] 与 [`frame_metrics`] 无条件施加：任何窗口宽度、任何版面，
+//! 正文列都不会超过它。1180 宽窗口下正文列是 **424**（不是 712）。
+//!
+//! **作用域**：这条承诺只覆盖 `BodyMedium` 14px 的正文。`BodySmall` 12px 的辅助文案
+//! （空态副文案、窄窗提示）在同一列宽下每行可到 ~82 字符——它们都是 1~2 行的短句，不做逐行承诺；
+//! 中文（全角 1em）另算，等 i18n mission 定。
+//!
+//! ### M102 订正：`column` 是**正文（prose）列宽**，不是页面块宽
+//!
+//! 视觉复审抓到「正文列左缘 423 对标题 110」，根因是**把 424 当成整页块宽再居中**。
+//! 现在三个量分开，口径与常量全在 [`block`]（本文件只留指针，免得文档把 file-size 门禁顶到红线）。
+//!
+//! ### 步进是怎么量的（口径 + 可复现）
+//!
+//! - **测的是哪组字形**：`BodyMedium` 的字体栈（本机解析到 Segoe UI **Regular**，14px），
+//!   **无 letter-spacing**——令牌的 0.5px 字距 iced 0.14 不支持（已登记的令牌丢失），渲染里没有；
+//! - **样本**：实例页详情那段正文（`pages/instances/data.rs` 的 `NOTE`，**361 字符**，
+//!   大小写 / 标点 / 空格 / `→` 混排，是我们自己的真实正文，不是造出来的 `mmmm`）；
+//! - **量法**：FreeType `getlength`（PIL `ImageFont.truetype(segoeui.ttf, 14)`）求整段排版宽，
+//!   再除以字符数 → **2185.00px / 361 = 6.0526 px/字符 = 0.43233em**；× 72 = 435.79（这是**平均**口径上界，逐行口径见下）；
+//! - **交叉验证**：同一段的首行（78 字符）渲染实测墨迹 **484px**，FreeType 对同一串给 479px
+//!   （差 ~1%，抗锯齿外扩），说明「步进」这个口径在 iced 渲染器与 FreeType 之间是一致的；
+//! - **CJK 不适用**：全角字形是 1em（14px），中文的 72 字符是 1008px。页面文案走 i18n 之后
+//!   要按语言分别定上限，这条留给 i18n mission；本模块只保证英文基线。
+
+use unlucky_design::spacing::{LayoutMetrics, Space};
+use unlucky_design::typography::TypeRole;
+
+pub mod block;
+pub mod wrap;
+
+#[cfg(test)]
+pub(crate) mod source;
+
+/// 官方 M3 窗口档的 medium 断点（600dp）。
+pub const BREAKPOINT_MEDIUM: f32 = 600.0;
+/// 官方 M3 窗口档的 expanded 断点（840dp）。
+pub const BREAKPOINT_EXPANDED: f32 = 840.0;
+
+/// 列表列宽（list-detail 左列）。任务区间 320~360，取 4px 栅格内的 **336**：
+/// 落在区间中段，既放得下「名字 + 版本 + 尾随图标」，又给详情列多留 16px。
+pub const LIST_COLUMN_WIDTH: f32 = 336.0;
+
+/// 详情列下限：再窄就不再分栏。
+///
+/// 按实测步进算：45 字符 × 6.05px ≈ 272，取 4px 栅格并留余量 → **320**
+/// （320 / 6.05 = 53 字符，仍在行宽下限之上）。
+pub const DETAIL_MIN_WIDTH: f32 = 320.0;
+
+/// 侧列宽（设置页分组导航）= D33 的 drawer 宽 240。
+///
+/// 复用 rail 的**尺寸语义**（88 ⇄ 240 同一容器的两种形态），但**不复制 rail 的实现**：
+/// 分组导航是页内元素，没有 hover 药丸、没有二级标签。
+pub const SIDE_NAV_WIDTH: f32 = LayoutMetrics::DESKTOP.nav_drawer_width;
+
+/// 表单列下限（supporting-pane 主列）：与详情列下限同源（320 ≈ 45 字符）。
+pub const FORM_MIN_WIDTH: f32 = DETAIL_MIN_WIDTH;
+
+/// 两列之间的间隙（`Space::X6` = 24）。
+pub const PANES_GAP: f32 = Space::X6.dp();
+
+/// 详情里元信息网格的**单卡最小宽度 = 由卡内最长内容反推**：**160**。
+///
+/// 推导（不是凑出来的）：
+/// - 卡内最长值是 demo 里的 `NeoForge 20.4.237`，Segoe UI 14px 实测 **118px**；
+/// - 卡两侧内边距 `LayoutMetrics::card_padding` = 20，故最小外框 = 118 + 2×20 = **158**；
+/// - 取 4px 栅格的 **160**（等价于旧值，但这次是**内容推出来的**，不是凑上限凑出来的）。
+///
+/// r2 复审抓到的回归：上一轮为了塞三列把这里收到 136，忘了算 padding ——
+/// 卡内只剩 96px，`NeoForge 20.4.237`（118px）与 `NeoForge 21.1.72`（110px）都会折成两行，
+/// 同排另两张卡仍一行 → **卡底不齐**。160 之下 3 列要 3×160 + 2×12 = 504，超出行宽上限，
+/// 所以元信息网格在 1180 宽是 **2 列**（2×160 + 12 = 332，卡内可排 166px，装得下 118）。
+/// 这也是有意的：mod 加载器版本串只会更长，2 列宽卡比 3 列挤卡更抗将来。
+pub const META_CARD_MIN_WIDTH: f32 = 160.0;
+/// 元信息网格卡片间距（`Space::X3` = 12）。
+pub const META_GAP: f32 = Space::X3.dp();
+
+/// 正文平均字符步进（em）——**实测值**，口径见模块文档 §3。
+///
+/// `BodyMedium` 14px / Segoe UI Regular / 361 字符英文混排正文，FreeType 实测
+/// **6.0526px/字符 = 0.43233em**。
+///
+/// 旧的 `0.5`（`[估]`）把 72 字符的列宽算成 504px，而实测 504px 能塞 **83 字符**——
+/// 「72 字符」这个名字和数字对不上的根因就在这里。换字体栈要重新量（这不是令牌）。
+pub const CHAR_ADVANCE_EM: f32 = 0.43233;
+/// 舒适行宽的字符数上限（任务建议 60~72，取上界 72）。
+pub const MAX_MEASURE_CHARS: f32 = 72.0;
+/// 行宽下限的字符数（再窄正文就碎成短行，45 是最低可读长度）。
+pub const MIN_MEASURE_CHARS: f32 = 45.0;
+
+/// 导航轨宽度（与 `shell::nav` 同一令牌值；布局系统只读它，不重定义）。
+pub const fn rail_width() -> f32 {
+    LayoutMetrics::DESKTOP.nav_rail_width
+}
+
+/// **逐行**安全宽度（px）：折行模拟下「最长一行 ≤72 字符」的最大 4px 栅格列宽 = **424**。
+///
+/// 见模块文档 §3 的模拟表：428 会出现 73 字符行，426 起降到 71，424 给到 67（留 5 字符余量）。
+/// 这个数是**量出来的**，不是 `advance × 72` 算出来的——后者只保证平均。
+pub const LINE_SAFE_WIDTH_PX: f32 = 424.0;
+
+/// 平均口径上界（px）：`floor(14px × 0.43233em × 72)` = **435**。
+///
+/// 只能保证**平均**一行 72 字符（实测 435 下会冒出 73 字符行），所以它是上界而不是取值。
+pub fn measure_average_bound_px() -> f32 {
+    (TypeRole::BodyMedium.style().size_px * CHAR_ADVANCE_EM * MAX_MEASURE_CHARS).floor()
+}
+
+/// 正文列宽上限（px）= `min(逐行安全宽 424, 平均口径上界 435)` = **424**。
+///
+/// 硬上限，任何版面 / 任何窗口宽度都不许超；`1180` 窗宽下正文列就是它（而非 M68 的 712）。
+pub fn measure_cap_px() -> f32 {
+    LINE_SAFE_WIDTH_PX.min(measure_average_bound_px())
+}
+
+/// 正文列宽下限（px）：`floor(14 × 0.43233 × 45)` = **272**。
+pub fn measure_floor_px() -> f32 {
+    (TypeRole::BodyMedium.style().size_px * CHAR_ADVANCE_EM * MIN_MEASURE_CHARS).floor()
+}
+
+/// 窗口宽度档位（官方 600 / 840 两个断点）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum WidthClass {
+    /// `< 600`
+    Compact,
+    /// `600 ≤ w < 840`
+    Medium,
+    /// `≥ 840`
+    Expanded,
+}
+
+impl WidthClass {
+    /// 按**窗口宽度**（含导航轨，逻辑 px）判档。
+    pub fn of(window_width: f32) -> Self {
+        if window_width < BREAKPOINT_MEDIUM {
+            Self::Compact
+        } else if window_width < BREAKPOINT_EXPANDED {
+            Self::Medium
+        } else {
+            Self::Expanded
+        }
+    }
+
+    /// 稳定名字（日志/测试/文件名用）。
+    pub const fn name(self) -> &'static str {
+        match self {
+            Self::Compact => "compact",
+            Self::Medium => "medium",
+            Self::Expanded => "expanded",
+        }
+    }
+
+    /// 页边距：compact 16 / medium 24 / expanded 24（官方 expanded 也是 24）。
+    pub const fn gutter(self) -> f32 {
+        match self {
+            Self::Compact => Space::X4.dp(),
+            Self::Medium | Self::Expanded => Space::X6.dp(),
+        }
+    }
+}
+
+/// 三种版面。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PageLayout {
+    /// 单列（列宽 ≤ 行宽上限，水平居中）。
+    SingleColumn,
+    /// 主列 + 辅助侧列。
+    SupportingPane,
+    /// 固定列表列 + 详情列。
+    ListDetail,
+}
+
+impl PageLayout {
+    /// 稳定名字。
+    pub const fn name(self) -> &'static str {
+        match self {
+            Self::SingleColumn => "single-column",
+            Self::SupportingPane => "supporting-pane",
+            Self::ListDetail => "list-detail",
+        }
+    }
+
+    /// 是否有两个列（侧列 + 主列）。
+    pub const fn is_two_pane(self) -> bool {
+        !matches!(self, Self::SingleColumn)
+    }
+}
+
+/// 页面声明的「最宽版面」——布局系统按窗口宽度降级。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PaneKit {
+    /// 单列页（下载 / 日志）。
+    Single,
+    /// 主列 + 侧列（设置）。
+    Supporting,
+    /// 列表 + 详情（实例）。
+    ListDetail,
+}
+
+/// 两列版面成立所需的最小窗口宽度（**公式**，不是拍值）：
+/// `Σ列宽 + 间隙 + 2×gutter + rail`。
+pub fn panes_min_window(first: f32, second: f32) -> f32 {
+    first + second + PANES_GAP + 2.0 * WidthClass::Expanded.gutter() + rail_width()
+}
+
+/// `ListDetail` 的几何门槛：336 + 320 + 24 + 48 + 88 = **816**。
+pub fn list_detail_min_window() -> f32 {
+    panes_min_window(LIST_COLUMN_WIDTH, DETAIL_MIN_WIDTH)
+}
+
+/// `SupportingPane` 的几何门槛：240 + 320 + 24 + 48 + 88 = **720**。
+pub fn supporting_pane_min_window() -> f32 {
+    panes_min_window(SIDE_NAV_WIDTH, FORM_MIN_WIDTH)
+}
+
+/// 版面决议：档位与几何门槛**同时**满足才升到两列，否则退化单列。
+pub fn resolve(kit: PaneKit, window_width: f32) -> PageLayout {
+    let class = WidthClass::of(window_width);
+    let wide_enough = match kit {
+        PaneKit::Single => false,
+        PaneKit::Supporting => {
+            class != WidthClass::Compact && window_width >= supporting_pane_min_window()
+        }
+        PaneKit::ListDetail => {
+            class == WidthClass::Expanded && window_width >= list_detail_min_window()
+        }
+    };
+
+    match (kit, wide_enough) {
+        (PaneKit::Single, _) | (_, false) => PageLayout::SingleColumn,
+        (PaneKit::Supporting, true) => PageLayout::SupportingPane,
+        (PaneKit::ListDetail, true) => PageLayout::ListDetail,
+    }
+}
+
+/// 页面可用宽度：窗口 − 导航轨 − 两侧页边距（下限 0）。
+pub fn available_width(window_width: f32) -> f32 {
+    let class = WidthClass::of(window_width);
+    (window_width - rail_width() - 2.0 * class.gutter()).max(0.0)
+}
+
+/// **给定窗口宽度 → 内容（正文）列宽**。本 mission 的「行宽约束」入口。
+///
+/// - 单列页：就是正文列宽（水平居中摆放）；
+/// - 两列页：这是**主列**的正文列宽；实际值还要看 [`frame_metrics`]（详情列会被列表列挤窄）。
+///
+/// 返回值永远 ≤ [`measure_cap_px`]：1180 窗宽下是 424（逐行 67 字符，≤72），不是 M68 的 712。
+pub fn content_column_width(window_width: f32) -> f32 {
+    available_width(window_width).min(measure_cap_px())
+}
+
+/// 元信息网格的列数：3 列需要 504（超出行宽上限，1180 下用不到），2 列需要 332，否则 1 列。
+pub fn meta_columns(width: f32) -> usize {
+    for columns in [3usize, 2] {
+        let needed = columns as f32 * META_CARD_MIN_WIDTH + (columns - 1) as f32 * META_GAP;
+        if width >= needed {
+            return columns;
+        }
+    }
+    1
+}
+
+/// 一屏的版面几何（页面直接消费，不再自己算列宽）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct FrameMetrics {
+    /// 窗口宽度（输入）。
+    pub window_width: f32,
+    /// 宽度档位。
+    pub class: WidthClass,
+    /// 决议出来的版面。
+    pub layout: PageLayout,
+    /// 页边距。
+    pub gutter: f32,
+    /// 页面可用宽度（已扣导航轨与页边距）。
+    pub available: f32,
+    /// 正文列宽（≤ 行宽上限）。两列版面时是**主列**的正文列宽。
+    pub column: f32,
+    /// 第二列（list-detail 的列表列 / supporting-pane 的侧列）。
+    pub secondary: Option<f32>,
+    /// 主列所在 pane 的宽度（单列 = 正文列宽）。
+    pub main_pane: f32,
+    /// 详情元信息网格列数。
+    pub meta_columns: usize,
+}
+
+/// 一次算齐版面几何。
+pub fn frame_metrics(kit: PaneKit, window_width: f32) -> FrameMetrics {
+    let class = WidthClass::of(window_width);
+    let gutter = class.gutter();
+    let available = available_width(window_width);
+    let layout = resolve(kit, window_width);
+
+    let (column, secondary, main_pane) = match layout {
+        PageLayout::SingleColumn => {
+            let column = available.min(measure_cap_px());
+            (column, None, column)
+        }
+        PageLayout::ListDetail => {
+            let list = LIST_COLUMN_WIDTH.min(available);
+            let pane = (available - list - PANES_GAP).max(0.0);
+            (pane.min(measure_cap_px()), Some(list), pane)
+        }
+        PageLayout::SupportingPane => {
+            let side = SIDE_NAV_WIDTH.min(available);
+            let pane = (available - side - PANES_GAP).max(0.0);
+            (pane.min(measure_cap_px()), Some(side), pane)
+        }
+    };
+
+    FrameMetrics {
+        window_width,
+        class,
+        layout,
+        gutter,
+        available,
+        column,
+        secondary,
+        main_pane,
+        meta_columns: meta_columns(column),
+    }
+}
+
+/// 版本管理页的**页内**三栏几何（版本类型栏 / 主版本栏 / 列表列）。
+///
+/// 页面级版面只有三种（[`PageLayout`]），而版本管理页要在单列里再切三栏——那次裁决住在这里，
+/// 与 `PaneKit` 分开：`PaneKit` 决定「页面占多宽」，[`rails`] 决定「这宽度怎么切成三栏」。
+pub mod rails;
+
+pub use rails::{
+    VersionRailTier, VersionRails, MAJOR_RAIL_WIDTH, RAIL_GAP, RAIL_ICON_WIDTH, TYPE_RAIL_WIDTH,
+};
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/app-iced/src/pages/layout/block.rs b/crates/app-iced/src/pages/layout/block.rs
new file mode 100644
index 0000000..7b4fae6
--- /dev/null
+++ b/crates/app-iced/src/pages/layout/block.rs
@@ -0,0 +1,83 @@
+//! 页面块几何：**块宽 / 块偏移 / 散文列宽**（纯函数，不碰 iced 控件树）。
+//!
+//! ## 为什么这三个量单独住一个文件（M102 r2）
+//!
+//! M102 把「一句话多宽」和「整页块多宽」拆成两个量，那段口径原本写在 `layout.rs` 的模块文档里，
+//! 连同 1440 上限一起把主文件顶到 **399 行**（CI 的 file-size 门禁是 `wc -l`，只剩 1 行余量）。
+//! 挪到本文件：主文件回到安全线以下，**口径与常量同处一室**——谁改上限都得读同一段话。
+//!
+//! ## 三个量（页面只许从这里取，不许自己算）
+//!
+//! | 量 | 值 | 用在哪 |
+//! |---|---|---|
+//! | [`body_width`] | `min(pane, 1440)`；pane = `available`（单列）/ `main_pane`（两列） | 页面块：Tabs / 列表 / 卡片 / 分隔线 |
+//! | [`body_offset`] | **0**（贴左） | 块的左缘相对页边距的偏移 —— 0 就是「与页头标题同一条线」 |
+//! | [`prose_width`] | [`FrameMetrics::column`]（≤424） | 成段散文（`frame::prose`），保证一行 ≤72 字符 |
+//!
+//! ## 为什么 1440 是上限（tower 拍板，M102 r2）
+//!
+//! 块宽**没有上限**时，2560 窗宽下单列页的块会一路长到 2424px：一行 80 个英文字符的列表行
+//! 空得发慌，中文正文同一行更能排到 170 字。取 **1440**（落在 4px 栅格上，= 360 × 4）：
+//! 在 1180（可用 1044）与 900（764）上**都不生效**，只拦极宽窗。
+//!
+//! 与 [`super::measure_cap_px`]（424，用 FreeType 实测步进 × 逐行折行模拟推出来的）不同，
+//! 1440 是**决策值**不是量出来的：它没有排版学推导，只有「别让列表行排成一条高速路」这一条理由。
+//! 所以它只该在这一处出现——谁想改，改这里并同时改 `block/tests.rs` 的断言。
+//!
+//! 贴左不变：块左缘仍是 `rail 88 + gutter 24 = 112`，封顶后**右侧留白**（不是居中）。
+//! 这是有意的：页头标题在左，正文块跟着左缘；把块居中又会回到视觉复审 ① 的「内容缩在中间」。
+//!
+//! ## 这一层唯一的行为变化，以及它从哪一版开始
+//!
+//! 封顶是 M102 r2 引入的**有意行为变化**：`≥ 1576` 窗宽（`112 + 1440 + 24`）下块宽不再跟随可用宽度。
+//! 在 1180 / 900 上它**不生效**——那两张验收图与 r1 逐字节相同（9/9 `cmp`）。所以对外口径是
+//! 「**≤1440 窗宽零像素变化；更宽的窗口按本上限有意改变**」，不是笼统的「零变化」。
+//! （`frame::body` 那行 `padding(left(body_offset))` 在同一轮加进来，值恒 0 ⇒ 像素中性。）
+//!
+//! ## 偏移为什么是个常量函数而不是 `align_x`
+//!
+//! iced 的 `Element` **没有几何内省接口**，「块摆在哪」在单测里量不到。所以把「贴左」写成一个
+//! 可断言的纯量 [`body_offset`]（= 0），让 `frame::body` 从它建盒，再配一条**源码结构**断言
+//! （`pages/tests.rs::frame_body_is_built_from_the_block_quantities`）钉住「盒子的左内边距来自它」。
+//! 变异实测：把 `frame::body` 换回 `centered(metrics.column, …)`（视觉复审 ① 的原样）⇒ 该断言红。
+
+use super::{FrameMetrics, PageLayout};
+
+/// 页面块宽度上限（逻辑像素，4px 栅格的 1440 = 360dp × 4）。
+///
+/// 只拦极宽窗：1180 窗宽下可用 1044、900 下 764，都够不到它。
+pub const BODY_MAX_WIDTH: f32 = 1440.0;
+
+/// 页面块宽度（px）：pane 宽封顶 1440。
+///
+/// 单列 = 整条可用宽度；两列 = 主列 pane（列表列 / 侧列已被扣掉）。
+pub fn body_width(metrics: FrameMetrics) -> f32 {
+    let pane = match metrics.layout {
+        PageLayout::SingleColumn => metrics.available,
+        PageLayout::SupportingPane | PageLayout::ListDetail => metrics.main_pane,
+    };
+
+    if pane < BODY_MAX_WIDTH {
+        pane
+    } else {
+        BODY_MAX_WIDTH
+    }
+}
+
+/// 页面块相对页边距的**左偏移**（px）：恒为 **0**（贴左）。
+///
+/// 「贴左」是 M102 的头号交付（视觉复审 ① 是「424 居中 ⇒ 左缘 422 对标题 112」），
+/// 所以它必须是一个能被断言的数，而不是一处 `align_x` 的写法。
+pub const fn body_offset(_metrics: FrameMetrics) -> f32 {
+    0.0
+}
+
+/// 散文块宽度（px）= [`FrameMetrics::column`]（≤424 ⇒ 逐行 ≤72 字符）。
+///
+/// 与 [`body_width`] 是两个量：块可以是 1044，一句话仍然只排 424。
+pub const fn prose_width(metrics: FrameMetrics) -> f32 {
+    metrics.column
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/app-iced/src/pages/layout/block/tests.rs b/crates/app-iced/src/pages/layout/block/tests.rs
new file mode 100644
index 0000000..6c2a652
--- /dev/null
+++ b/crates/app-iced/src/pages/layout/block/tests.rs
@@ -0,0 +1,89 @@
+//! `block` 的断言：三个纯量的数值口径。
+//!
+//! 「块摆在哪」量不到（iced 无 Element 内省），所以这里只钉**数**；
+//! 「盒子是不是照这个数摆的」由 `pages/tests.rs` 的源码结构断言负责
+//! （`frame_body_is_built_from_the_block_quantities`）。
+
+use super::*;
+use crate::pages::layout::{frame_metrics, measure_cap_px, rail_width, PaneKit};
+
+/// 贴左：**任何**版面、任何窗宽，块偏移都是 0。
+///
+/// 抓得住：有人把偏移改成居中/右对齐（那它就不再是 0）；
+/// 抓不住：`frame::body` 有没有真的用这个数（源码结构断言负责）。
+#[test]
+fn the_block_is_always_left_aligned() {
+    for kit in [PaneKit::Single, PaneKit::Supporting, PaneKit::ListDetail] {
+        for width in [320.0, 600.0, 720.0, 840.0, 900.0, 1180.0, 1440.0, 2560.0] {
+            assert_eq!(
+                body_offset(frame_metrics(kit, width)),
+                0.0,
+                "{kit:?} @{width} 的块偏移必须贴左"
+            );
+        }
+    }
+}
+
+/// 块宽 = pane 宽（单列 = 可用宽度，两列 = 主列 pane），未到上限时不缩水。
+#[test]
+fn body_width_is_the_pane_until_the_cap() {
+    for width in [320.0, 600.0, 840.0, 1180.0] {
+        let single = frame_metrics(PaneKit::Single, width);
+        assert_eq!(body_width(single), single.available, "单列 @{width}");
+        assert_eq!(body_offset(single), 0.0, "@{width}");
+    }
+
+    // 两列版面：块宽 = 主列 pane（低于门槛时 list-detail 会退化成单列，那时块宽回到可用宽度）
+    let two = frame_metrics(PaneKit::ListDetail, 1180.0);
+    assert_eq!(body_width(two), two.main_pane);
+    assert!(two.main_pane < two.available);
+    let degraded = frame_metrics(PaneKit::ListDetail, 700.0);
+    assert_eq!(body_width(degraded), degraded.available);
+
+    // 1440 上限只拦极宽窗：1180 可用 1044、2560 可用 2424
+    assert_eq!(frame_metrics(PaneKit::Single, 1180.0).available, 1044.0);
+    assert_eq!(frame_metrics(PaneKit::Single, 2560.0).available, 2424.0);
+    assert_eq!(
+        body_width(frame_metrics(PaneKit::Single, 2560.0)),
+        BODY_MAX_WIDTH
+    );
+    // 两列版面同样封顶（2560 下主列 pane 是 2064）
+    let wide_two = frame_metrics(PaneKit::ListDetail, 2560.0);
+    assert!(wide_two.main_pane > BODY_MAX_WIDTH);
+    assert_eq!(body_width(wide_two), BODY_MAX_WIDTH);
+
+    // 封顶之后左缘不变、右侧留白（不是居中）
+    let huge = frame_metrics(PaneKit::Single, 2560.0);
+    let left = rail_width() + huge.gutter;
+    assert_eq!(left, 112.0);
+    let right_gap = 2560.0 - (left + body_width(huge)) - huge.gutter;
+    assert_eq!(right_gap, 984.0, "2560 宽下封顶后右侧留白");
+    assert!(right_gap > 900.0);
+}
+
+/// 散文列宽 = `FrameMetrics::column`，永远 ≤ 行宽上限（与块宽脱钩）。
+#[test]
+fn prose_width_stays_at_the_measure_cap() {
+    for width in [600.0, 840.0, 900.0, 1180.0, 2560.0] {
+        let metrics = frame_metrics(PaneKit::Single, width);
+        assert_eq!(prose_width(metrics), metrics.column, "@{width}");
+        assert!(prose_width(metrics) <= measure_cap_px());
+    }
+
+    // 块已经封顶的地方，散文列仍是 424 —— 两个量确实分开了
+    let huge = frame_metrics(PaneKit::Single, 2560.0);
+    assert_eq!(body_width(huge), BODY_MAX_WIDTH);
+    assert_eq!(prose_width(huge), measure_cap_px());
+    assert_eq!(prose_width(huge), 424.0);
+}
+
+/// 上限本身：在 4px 栅格上，且远宽于散文列（否则「把两个量拆开」这件事是白做的）。
+#[test]
+fn the_cap_is_on_the_grid_and_far_wider_than_the_measure() {
+    assert_eq!(BODY_MAX_WIDTH % 4.0, 0.0, "块宽上限必须在 4px 栅格上");
+    assert!(
+        BODY_MAX_WIDTH >= measure_cap_px() * 3.0,
+        "块宽上限 {BODY_MAX_WIDTH} 必须远宽于散文列 {}",
+        measure_cap_px()
+    );
+}
diff --git a/crates/app-iced/src/pages/layout/rails.rs b/crates/app-iced/src/pages/layout/rails.rs
new file mode 100644
index 0000000..951f1a2
--- /dev/null
+++ b/crates/app-iced/src/pages/layout/rails.rs
@@ -0,0 +1,227 @@
+//! 版本管理页的**三栏几何**：版本类型栏 + 主版本栏 + 列表列。纯函数，不碰 iced 控件树。
+//!
+//! 这一页是 `PaneKit::Single` 之外的第二种「页内分栏」：外层仍是单列（页头铺满页宽），
+//! 正文自己切成三栏。所以它不能复用 [`super::PaneKit`]（那是**页面级**版面决议），
+//! 而是在可用宽上再做一次**页内**裁决 —— 本文件就是那次裁决的唯一真源。
+//!
+//! ## 1. 两个侧栏的宽度
+//!
+//! | 栏 | 展开 | 收成图标条 | 依据 |
+//! |---|---|---|---|
+//! | 版本类型栏 | **140** | **64** | 140 = `12b §7` drawer 项「图标 24 + 间距 12 + 8 字符标签」；`Snapshot` 是最长标签（8 字符 ≈ 62px），24+12+62+2×16 内边距 = 130，取 4px 栅格 **140** |
+//! | 主版本栏 | **140** | **64** | 同一档宽度：主版本是 `1.21` 这种 3~5 字符的短串，140 里放得下「主版本 + 该组版本数」两行；64 里只放得下版本号本身（40 可用宽够 4 字符 `LabelMedium`） |
+//!
+//! 64 = `LayoutMetrics::nav_rail_width` 的一半再对齐栅格？**不是**：64 是 4px 栅格上的
+//! 「图标 24 + 两侧内边距 2×16 + 余量 8」，比导航轨 88 窄一档（导航轨要放 56 宽的选中药丸，
+//! 页内侧栏只要 40 宽的选中条）。
+//!
+//! ## 2. 四档与各自的门槛（门槛都是**算出来的**）
+//!
+//! 记 `A` = **页面块宽**（[`super::block::body_width`](super::block::body_width) = 可用宽
+//! 封顶 1440，M102 的口径；≤1440 时它就是可用宽，所以下面这张表在 1180/1024/900/700 上不变）。
+//!
+//! | 档 | 门槛 | 类型栏 | 主版本栏 | 列表列 |
+//! |---|---|---|---|---|
+//! | `Wide` | `A ≥ 888` | 140 | 140 | `A − 328` |
+//! | `Narrow` | `676 ≤ A < 888` | **64** | 140 | `A − 252` |
+//! | `Compact` | `600 ≤ A < 676` | 64 | **64** | `A − 176` |
+//! | `Chips` | `A < 600` | 0 | 0 | `A` |
+//!
+//! 三个门槛的来源（`L` = 列表列下限 [`version_list_min_width`] = 行宽上限 **424**）：
+//!
+//! - `888` = `available_width(1024)`：任务给的产品口径「≫1024 两栏都展开」，换成可用宽就是它；
+//! - `676` = `64 + 24 + 140 + 24 + 424`：**类型栏收成图标条之后**三栏仍能让列表停在 424；
+//! - `600` = `64 + 24 + 64 + 24 + 424`：两条栏都收成 64 也救不回来时，三栏这件事就不成立了。
+//!
+//! ## 3. 列表列下限为什么是 424（这条是硬的）
+//!
+//! 版本行要**单行不折**地放「版本号 + 类型 + 日期 + 安装按钮」。424 是 [`super::measure_cap_px`]
+//! ——正文行宽上限（逐行实测 67 字符 ≤72），比这一行真正需要的宽得多：
+//! `1.21.9-pre3`（11 字符 `BodyMedium` 14px ≈ 67）+ `Snapshot`（`LabelMedium` 12px ≈ 50）
+//! + `2026-09-20`（10 字符 ≈ 52）+ 安装按钮（`control_height` 40 高的 text 按钮 ≈ 76）
+//! + 两侧内边距 2×16 + 三处间距 3×12 = **293**。取 424 不是「凑」：它是本仓既有的
+//! 行宽红线，列表列比它还窄就等于在 424 的正文列旁边又开了一条更窄的正文列。
+//!
+//! ## 4. 数值表（报告里贴的是同一张）
+//!
+//! 页面拿到的宽度 → 可用宽 `A`（扣 rail 88 与 2×24 页边距）→ 档位 → 三列。
+//! 「右栏收起 / 展开」列按 M104 的 `content_width`（窗口 − 右栗 − 拖拽缝）计算：
+//!
+//! | 窗口 | 右栏 | 页面拿到 | `A` | 档 | 类型 | 主版本 | 列表 |
+//! |---|---|---|---|---|---|---|---|
+//! | 1180 | 无（本分支） | 1180 | 1044 | Wide | 140 | 140 | **716** |
+//! | 1180 | 收起 48 | 1132 | 996 | Wide | 140 | 140 | **668** |
+//! | 1180 | 展开 320 | 852 | 716 | Narrow | 64 | 140 | **464** |
+//! | 1024 | 无 | 1024 | 888 | Wide | 140 | 140 | **560** |
+//! | 900 | 无 | 900 | 764 | Narrow | 64 | 140 | **512** |
+//! | 880 | 无 | 880 | 744 | Narrow | 64 | 140 | **492** |
+//! | 700 | 无 | 700 | 564 | Chips | — | — | **564** |
+//!
+//! **任务书那句「1180−88−320−140−140 = 492」算错了**：它漏掉 2×24 页边距与 2×24 栏间距
+//! （共 96）。按真实链路，1180 展开右栏后页面拿到 **852**，可用宽 **716**，
+//! 两条 140 栏 + 两处间距要 328 ⇒ 列表只剩 **388 < 424**，**那正是「一条栏必须收成 64」的
+//! 触发条件**；收到 64 之后列表是 **464**（不是 492）。492 这个数在 **880 窗宽**上成立
+//! （744 − 252 = 492），两者差 28 就是 1180−852−88−48 里被漏掉的那部分。
+//!
+//! ## 5. 为什么 Narrow 档收的是**类型栏**而不是主版本栏
+//!
+//! 两栏都放 3~5 个字符的短串，但可辨性不同：类型栏是**四个固定项**（有图标可认：列表 / 星 /
+//! 相机 / 历史），主版本栏放的是**用户正在找的那串版本号**——同一屏里两种 64 栏，先收有图标的那个。
+//! `Compact` 档才把主版本栏也收成 64（`1.21` 在 40 可用宽里仍是完整串，不会被截断）。
+
+use unlucky_design::spacing::Space;
+
+use super::{available_width, measure_cap_px, FrameMetrics};
+
+/// 版本类型栏（第一栏）展开宽。
+pub const TYPE_RAIL_WIDTH: f32 = 140.0;
+/// 主版本栏（第二栏）展开宽。
+pub const MAJOR_RAIL_WIDTH: f32 = 140.0;
+/// 两条侧栏收成图标条时的宽度。
+pub const RAIL_ICON_WIDTH: f32 = 64.0;
+/// 栏与栏之间的间距（与两列版面的 `PANES_GAP` 同值：同一屏里不出现两种分栏节奏）。
+pub const RAIL_GAP: f32 = Space::X6.dp();
+
+/// 列表列下限 = 行宽上限 **424**（见模块文档 §3）。
+pub fn version_list_min_width() -> f32 {
+    measure_cap_px()
+}
+
+/// `Wide` 档门槛：`available_width(1024)` = **888**（产品口径「≫1024 两栏都展开」）。
+pub fn wide_min_available() -> f32 {
+    available_width(1024.0)
+}
+
+/// `Narrow` 档门槛：类型栏 64 + 间距 + 主版本栏 140 + 间距 + 列表下限 = **676**。
+pub fn narrow_min_available() -> f32 {
+    RAIL_ICON_WIDTH + RAIL_GAP + MAJOR_RAIL_WIDTH + RAIL_GAP + version_list_min_width()
+}
+
+/// `Compact` 档门槛：两条 64 栏 + 两处间距 + 列表下限 = **600**。
+pub fn compact_min_available() -> f32 {
+    RAIL_ICON_WIDTH + RAIL_GAP + RAIL_ICON_WIDTH + RAIL_GAP + version_list_min_width()
+}
+
+/// 版本行里「类型」一格的宽度：最长标签 `Snapshot`（8 字符 × `LabelMedium` 12px ≈ 50）+
+/// 一格间距余量，取 4px 栅格 **84**。
+pub const LIST_KIND_WIDTH: f32 = 84.0;
+
+/// 版本行里「日期」一格的宽度：ISO 日期 `2026-09-20`（10 字符 ≈ 52）+ 余量，取 **88**。
+pub const LIST_DATE_WIDTH: f32 = 88.0;
+
+/// 版本行尾的安装图标按钮格子宽 = 图标按钮边长 **40**（`IconGeometry::side`；命中区 48 由行高 44 补）。
+pub const ROW_ICON_BUTTON: f32 = 40.0;
+
+/// 版本行内三处间距（`Space::X2` = 8）：比栏间距小一档，行内节奏不与分栏节奏打架。
+pub const ROW_GAP: Space = Space::X2;
+
+/// 版本行的最小内容宽（报告里的推导用它当校验）：
+/// `Listitem 最小格 176 + 84 + 88 + 40 + 3×8 = 412 < 424`。
+///
+/// 412 略小于行宽下限 424，说明「424 下四样仍在同一行」不是估计而是有 12px 余量的结论；
+/// 版本号那一格最窄拿到 `424 − 84 − 88 − 40 − 24 = 188`（比推导里取的 176 还宽 12）。
+pub fn version_row_min_width() -> f32 {
+    176.0 + LIST_KIND_WIDTH + LIST_DATE_WIDTH + ROW_ICON_BUTTON + 3.0 * ROW_GAP.dp()
+}
+
+/// 版本管理页此刻用哪一档（四档，见模块文档 §2）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum VersionRailTier {
+    /// 两栏都展开（`A ≥ 888`）。
+    Wide,
+    /// 类型栏收成图标条（`676 ≤ A < 888`）。
+    Narrow,
+    /// 两条栏都收成图标条（`600 ≤ A < 676`）。
+    Compact,
+    /// 三栏不成立：退回顶部 chips（`A < 600`）。
+    Chips,
+}
+
+impl VersionRailTier {
+    /// 稳定名字（日志 / 测试 / 出图文件名用）。
+    pub const fn name(self) -> &'static str {
+        match self {
+            Self::Wide => "wide",
+            Self::Narrow => "narrow",
+            Self::Compact => "compact",
+            Self::Chips => "chips",
+        }
+    }
+
+    /// 这一档还画不画页内侧栏。
+    pub const fn is_three_column(self) -> bool {
+        !matches!(self, Self::Chips)
+    }
+}
+
+/// 三栏的宽度裁决结果（页面直接消费，不再自己算）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct VersionRails {
+    /// 档位。
+    pub tier: VersionRailTier,
+    /// 版本类型栏宽（`Chips` 档为 0）。
+    pub type_rail: f32,
+    /// 主版本栏宽（`Chips` 档为 0）。
+    pub major_rail: f32,
+    /// 列表 / 内容列宽。
+    pub list: f32,
+}
+
+impl VersionRails {
+    /// 按可用宽裁决（门槛见模块文档 §2）。
+    ///
+    /// 降级是**逐档下沉**的，不做「挤一挤」：每一档都保证 `list ≥ `[`version_list_min_width`]，
+    /// 除非已经沉到 `Chips`（那时列表就是整条可用宽）。
+    pub fn of(available: f32) -> Self {
+        let (tier, type_rail, major_rail) = if available >= wide_min_available() {
+            (VersionRailTier::Wide, TYPE_RAIL_WIDTH, MAJOR_RAIL_WIDTH)
+        } else if available >= narrow_min_available() {
+            (VersionRailTier::Narrow, RAIL_ICON_WIDTH, MAJOR_RAIL_WIDTH)
+        } else if available >= compact_min_available() {
+            (VersionRailTier::Compact, RAIL_ICON_WIDTH, RAIL_ICON_WIDTH)
+        } else {
+            (VersionRailTier::Chips, 0.0, 0.0)
+        };
+
+        let list = if tier.is_three_column() {
+            (available - type_rail - RAIL_GAP - major_rail - RAIL_GAP).max(0.0)
+        } else {
+            available.max(0.0)
+        };
+
+        Self {
+            tier,
+            type_rail,
+            major_rail,
+            list,
+        }
+    }
+
+    /// 一屏的版本管理页几何（`metrics` 来自 [`super::frame_metrics`]）。
+    ///
+    /// **读的是块宽**（[`super::block::body_width`] = pane 宽封顶 1440，M102 的口径），
+    /// 不是 `metrics.available`：三栏都长在 `frame::body` 那个块里，超宽窗（≥1576）上
+    /// 可用宽 2424 > 块宽 1440，按 available 切会让三列之和超出块、右侧被裁。
+    pub fn of_metrics(metrics: FrameMetrics) -> Self {
+        Self::of(super::block::body_width(metrics))
+    }
+
+    /// 叠上「用户手动折叠了类型栏」这条覆盖。
+    ///
+    /// 只动第一栏：收窄到 [`RAIL_ICON_WIDTH`]，省下来的宽**原样进列表列**（折叠只会让列表更宽，
+    /// 所以不需要再校验一次 424 下限）。`Chips` 档没有第一栏，返回原值。
+    #[must_use]
+    pub fn with_type_folded(self) -> Self {
+        if !self.tier.is_three_column() || self.type_rail <= RAIL_ICON_WIDTH {
+            return self;
+        }
+        Self {
+            type_rail: RAIL_ICON_WIDTH,
+            list: self.list + (self.type_rail - RAIL_ICON_WIDTH),
+            ..self
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/app-iced/src/pages/layout/rails/tests.rs b/crates/app-iced/src/pages/layout/rails/tests.rs
new file mode 100644
index 0000000..5c650f7
--- /dev/null
+++ b/crates/app-iced/src/pages/layout/rails/tests.rs
@@ -0,0 +1,139 @@
+//! 三栏几何的判据：**报告里的数值表就是这张表**，改任何一个门槛或栏宽都会在这里红。
+//!
+//! 每条都写清「抓得住什么 / 抓不住什么」——这里只测纯函数，**像素**由 `DevDocs/artifacts/m107/`
+//! 的图与报告的量测表负责。
+
+use super::*;
+use crate::pages::layout::available_width;
+
+/// 报告里那张数值表的**逐行快照**（窗口 → 页面拿到多宽 → 可用宽 → 档 → 三列）。
+///
+/// 抓得住：任何一处门槛 / 栏宽 / 间距被改动（表里 7 行的档位或列宽立刻对不上）。
+/// 抓不住：改完之后画面**看起来**是否还行（那要出图，见报告）。
+#[test]
+fn the_numeric_table_matches_the_report() {
+    // (页面拿到的宽, 期望档, 类型栏, 主版本栏, 列表)
+    let table: [(f32, VersionRailTier, f32, f32, f32); 7] = [
+        (1180.0, VersionRailTier::Wide, 140.0, 140.0, 716.0),
+        (1132.0, VersionRailTier::Wide, 140.0, 140.0, 668.0),
+        (852.0, VersionRailTier::Narrow, 64.0, 140.0, 464.0),
+        (1024.0, VersionRailTier::Wide, 140.0, 140.0, 560.0),
+        (900.0, VersionRailTier::Narrow, 64.0, 140.0, 512.0),
+        (880.0, VersionRailTier::Narrow, 64.0, 140.0, 492.0),
+        (700.0, VersionRailTier::Chips, 0.0, 0.0, 564.0),
+    ];
+
+    for (page_width, tier, type_rail, major_rail, list) in table {
+        let rails = VersionRails::of(available_width(page_width));
+        assert_eq!(rails.tier, tier, "{page_width} 的档位");
+        assert_eq!(rails.type_rail, type_rail, "{page_width} 的类型栏");
+        assert_eq!(rails.major_rail, major_rail, "{page_width} 的主版本栏");
+        assert_eq!(rails.list, list, "{page_width} 的列表列");
+    }
+}
+
+/// 三栏档里，列表列**永远**不低于行宽下限 424（任务里那条硬约束：版本行不许折行）。
+///
+/// 抓得住：有人把门槛算小了（比如把 `Compact` 档门槛写成 560，列表会掉到 384 以下，
+/// `1.21.9-pre3 · Snapshot · 2026-09-20 · Install` 这一行就得折）。
+/// 抓不住：折行到底发生在第几个字符（那要 FreeType 量宽 + 出图）。
+#[test]
+fn every_three_column_tier_keeps_the_list_at_the_reading_floor() {
+    let floor = version_list_min_width();
+    let mut sweep = 0;
+    // 4px 栅格扫一遍：从 480 到 2400 的可用宽
+    let mut available = 480.0_f32;
+    while available <= 2400.0 {
+        let rails = VersionRails::of(available);
+        if rails.tier.is_three_column() {
+            assert!(
+                rails.list + f32::EPSILON >= floor,
+                "可用宽 {available}（{} 档）的列表列 {} 低于行宽下限 {floor}",
+                rails.tier.name(),
+                rails.list
+            );
+            sweep += 1;
+        }
+        available += 4.0;
+    }
+    assert!(sweep > 100, "扫描没跑到（只命中 {sweep} 档）");
+}
+
+/// 档位随可用宽**单调**下沉：变窄只可能降档，不会「窄一点反而三栏都展开」。
+#[test]
+fn the_tiers_only_ever_step_down_as_the_width_shrinks() {
+    let order = |tier: VersionRailTier| match tier {
+        VersionRailTier::Wide => 0,
+        VersionRailTier::Narrow => 1,
+        VersionRailTier::Compact => 2,
+        VersionRailTier::Chips => 3,
+    };
+
+    let mut previous = VersionRails::of(4096.0);
+    let mut available = 4092.0_f32;
+    while available >= 200.0 {
+        let rails = VersionRails::of(available);
+        assert!(
+            order(rails.tier) >= order(previous.tier),
+            "{available} 反而比更宽时更「展开」：{:?} → {:?}",
+            previous.tier,
+            rails.tier
+        );
+        previous = rails;
+        available -= 4.0;
+    }
+}
+
+/// 三个门槛都是**算出来的**，不是拍的：把它们与文档里的公式对上。
+#[test]
+fn the_three_thresholds_are_derived() {
+    assert_eq!(wide_min_available(), 888.0, "1024 窗宽换算的可用宽");
+    assert_eq!(
+        narrow_min_available(),
+        64.0 + 24.0 + 140.0 + 24.0 + 424.0,
+        "类型栏收成图标条后三栏仍成立的最小可用宽"
+    );
+    assert_eq!(
+        compact_min_available(),
+        64.0 + 24.0 + 64.0 + 24.0 + 424.0,
+        "两条栏都收成 64 时的最小可用宽"
+    );
+    assert!(compact_min_available() < narrow_min_available());
+    assert!(narrow_min_available() < wide_min_available());
+
+    // 门槛上的两个采样点：刚好到就进这一档，差 4px 就退一档
+    assert_eq!(
+        VersionRails::of(narrow_min_available()).tier,
+        VersionRailTier::Narrow
+    );
+    assert_eq!(
+        VersionRails::of(narrow_min_available() - 4.0).tier,
+        VersionRailTier::Compact
+    );
+    assert_eq!(
+        VersionRails::of(compact_min_available()).tier,
+        VersionRailTier::Compact
+    );
+    assert_eq!(
+        VersionRails::of(compact_min_available() - 4.0).tier,
+        VersionRailTier::Chips
+    );
+}
+
+/// 右栏展开（M104 的 `content_width`：窗口 − 320 − 拖拽缝 8）之后**仍是三栏**，且列表够宽。
+///
+/// 这条钉的是任务里那个场景：1180 窗宽开右栏，用户还能看见两条侧栏 + 一个不折行的版本列表。
+/// 抓得住：有人把 `Narrow` 门槛抬到 716 以上（那会让右栏一展开就掉进 chips）。
+/// 抓不住：`content_width` 自己算错（那是 M104 的测试）。
+#[test]
+fn the_agent_rail_open_at_1180_keeps_three_columns() {
+    // M104 `content_width` = 窗口 − 右栗 320 − 拖拽缝 8
+    let page_width = 1180.0 - 320.0 - 8.0;
+    let rails = VersionRails::of(available_width(page_width));
+
+    assert_eq!(page_width, 852.0);
+    assert_eq!(rails.tier, VersionRailTier::Narrow);
+    assert!(rails.tier.is_three_column(), "右栏展开不许把侧栏收掉");
+    assert_eq!(rails.list, 464.0, "列表列 464（任务书写的 492 漏扣了 96）");
+    assert!(rails.list >= version_list_min_width());
+}
diff --git a/crates/app-iced/src/pages/layout/source.rs b/crates/app-iced/src/pages/layout/source.rs
new file mode 100644
index 0000000..28e74f7
--- /dev/null
+++ b/crates/app-iced/src/pages/layout/source.rs
@@ -0,0 +1,235 @@
+//! **源码结构断言**的小工具：把某个函数的实现文本切出来（只给测试用）。
+//!
+//! ## 为什么要读源码（而不是量 Element）
+//!
+//! iced 的 `Element` 没有几何内省接口（`size()` 只是 `Size<Length>`，取不到布局结果），
+//! 所以「页面把块摆在哪 / 有没有在行之间叠间距」在单测里**量不到**。M102 r1 的教训正是这个：
+//! 护栏只喂 `frame_metrics()` 与常量重算，把 `frame::body` 换回「居中 424」的实现，
+//! 测试照样全绿——钉住的是公式，不是摆法。
+//!
+//! 本仓已有同一条纪律的先例：`tests/no_hardcoded_tokens.rs` 直接扫 `src/**`，
+//! `pages/download/tests.rs::every_download_key_is_referenced_by_the_page` 用 `include_str!`
+//! 扫页面源码找 key 引用。这里只是把「切出某个函数」这件小事做成一个共用工具，
+//! 让护栏能断言「盒子是不是照那个数建的」。
+//!
+//! ## 边界（它抓不住什么）
+//!
+//! 它读的是**文本**：换个写法（先赋值给局部变量再 `.width(...)`）就可能绕过。
+//! 所以它只配一条**明确的契约**用：`frame::body` / `frame::prose` / `list_column` 这几处的
+//! 写法本身就是契约的一部分（它们各自只有 5~10 行），不是为了抠实现细节。
+//! 真要守像素，还是得靠软件渲染金图（`shot::diff`，绑 Windows + 字体栈，属另一个决定）。
+
+/// 把 `source` 里第一个 `signature` 起始、到该函数**顶层**右花括号为止的文本切出来。
+///
+/// 「顶层」= 行首的 `}`（本仓函数都是顶格收尾，内层块都是缩进收尾），所以不会在内层 `}` 提前断。
+///
+/// # Panics
+/// 签名不存在时 panic（护栏自己的前置条件坏了要立刻红，不能静默放行）。
+pub(crate) fn function_body<'a>(source: &'a str, signature: &str) -> &'a str {
+    let start = source
+        .find(signature)
+        .unwrap_or_else(|| panic!("源码里找不到签名 {signature:?}"));
+
+    let rest = &source[start..];
+    let end = rest.find("\n}").map_or(rest.len(), |index| index + 2);
+    &rest[..end]
+}
+
+/// 从 `start` 起到**第一个 `;`** 为止的一条语句（构建链断言用）。
+///
+/// 例如 `statement(instances.rs, "let mut rows = column(")` 拿到的是
+/// `let mut rows = column(...).padding(...).width(Length::Fill);` 这一整条链——
+/// 于是「这条链上不许叠间距」可以精确到**这一个**容器，不会连带禁掉旁边 `column![head, scroller]`
+/// 上的合法间距。
+///
+/// # Panics
+/// `start` 不存在时 panic（守卫的前置条件坏了要立刻红）。
+pub(crate) fn statement<'a>(source: &'a str, start: &str) -> &'a str {
+    let from = source
+        .find(start)
+        .unwrap_or_else(|| panic!("源码里找不到语句起点 {start:?}"));
+
+    let rest = &source[from..];
+    let end = rest.find(';').map_or(rest.len(), |index| index + 1);
+    &rest[..end]
+}
+
+/// `signature` 的函数体 **+ 它内部转调的函数体**（同文件，最多两层）。
+///
+/// 为什么不只切一个函数：**等价重构不该假红**。把 `frame::body` 拆成
+/// `body` → `body_impl` 两层再转调，盒子一个像素都没变，`function_body` 却会拿到三行转调桩、
+/// needle 全缺（r2 复审的变异 H1 就是这样假红的）。这里把「被它调用的函数」也算进契约，
+/// 于是「拆一层再转调」放行，「换成居中盒子」照样红。
+///
+/// 跨文件转调用 [`region_across`]。两者都不跟「先赋局部变量再建盒」的写法。
+pub(crate) fn function_region(source: &str, signature: &str) -> String {
+    region_across(&[source], signature)
+}
+
+/// 多文件版的 [`function_region`]：[`expand`] 会在给定的**所有**文件里按名字找转调目标。
+///
+/// 存在的理由（r4 复审的变异 M6）：把盒子原样搬进 `layout/block.rs::body_box` 再由
+/// `frame::body` 转调，是**等价重构**，单文件版会把 needle 全丢掉并假红。
+/// 现在把 `frame.rs` 与 `layout/block.rs` 一起交进来，搬运不再被惩罚。
+///
+/// # Panics
+/// `signature` 在任何一个文件里都找不到时 panic（护栏前置条件坏了要立刻红）。
+pub(crate) fn region_across(sources: &[&str], signature: &str) -> String {
+    let mut region = sources
+        .iter()
+        .find(|source| source.contains(signature))
+        .map(|source| function_body(source, signature).to_owned())
+        .unwrap_or_else(|| panic!("这几个文件里都找不到签名 {signature:?}"));
+
+    for _ in 0..2 {
+        if !expand(&mut region, sources) {
+            break;
+        }
+    }
+
+    region
+}
+
+/// 把 `region` 里出现、且定义在 `sources` 某处的函数体补进来。返回是否有增长。
+fn expand(region: &mut String, sources: &[&str]) -> bool {
+    let mut grew = false;
+
+    for source in sources {
+        let mut cursor = 0;
+
+        while let Some(found) = source[cursor..].find("fn ") {
+            let at = cursor + found + "fn ".len();
+            cursor = at;
+
+            let name: String = source[at..]
+                .chars()
+                .take_while(|ch| ch.is_alphanumeric() || *ch == '_')
+                .collect();
+            if name.is_empty() {
+                continue;
+            }
+
+            // `defined` 不带 `(`：签名可能带泛型（`fn body_impl<'a>(`），
+            // 带括号的 needle 会找不到定义、直接把护栏自己搞 panic。
+            let defined = format!("fn {name}");
+            if region.contains(&format!("{name}("))
+                && !region.contains(&defined)
+                && source.contains(&defined)
+            {
+                region.push('\n');
+                region.push_str(function_body(source, &defined));
+                grew = true;
+            }
+        }
+    }
+
+    grew
+}
+
+/// `haystack` 里每一处 `callee(…)` 调用的**实参文本**（不含括号本身）。
+///
+/// 括号按深度配对，所以 `ui.space(Space::X1)` 这种嵌套实参会完整取到 `ui.space(Space::X1)`；
+/// 找不到闭合括号时取到文本末尾（宁可让断言看见多余文本，也不静默返回空）。
+pub(crate) fn call_arguments<'a>(haystack: &'a str, callee: &str) -> Vec<&'a str> {
+    let mut found = Vec::new();
+    let mut from = 0;
+
+    while let Some(index) = haystack[from..].find(callee) {
+        let start = from + index + callee.len();
+        let mut depth = 1usize;
+        let mut end = haystack.len();
+
+        for (offset, ch) in haystack[start..].char_indices() {
+            match ch {
+                '(' => depth += 1,
+                ')' => {
+                    depth -= 1;
+                    if depth == 0 {
+                        end = start + offset;
+                        break;
+                    }
+                }
+                _ => {}
+            }
+        }
+
+        found.push(&haystack[start..end]);
+        from = end.max(start);
+    }
+
+    found
+}
+
+/// 顺绑定链往回追：`ident` 是否（直接或经至多 3 跳中转）来自 `root`。
+///
+/// 认两种绑定形状（本仓就这两种）：
+///
+/// - `let <ident> = <expr>;`
+/// - `if let Some(<ident>) = <expr> {`（`while let` 同理，形状一样）
+///
+/// 为什么需要它（r4 复审的变异 M4）：把写死的令牌先挪到一条 `let extra = Space::X1;`，
+/// 再 `rows = rows.spacing(ui.space(extra));` —— 只看实参文本「有没有 `Space::`」会漏掉它。
+/// 顺着绑定追回源头就能区分「真的来自 `ROW_SPACING`（含 `let spacing = ROW_SPACING` 再中转，
+/// 变异 H3）」与「中转了一层写死令牌」。
+pub(crate) fn derived_from(body: &str, ident: &str, root: &str) -> bool {
+    let mut frontier = vec![ident.to_owned()];
+
+    for _ in 0..3 {
+        let mut next = Vec::new();
+
+        for name in &frontier {
+            for rhs in binding_rhs(body, name) {
+                if rhs.contains(root) {
+                    return true;
+                }
+
+                next.extend(
+                    rhs.split(|ch: char| !(ch.is_alphanumeric() || ch == '_'))
+                        .filter(|token| {
+                            token
+                                .chars()
+                                .next()
+                                .is_some_and(|first| first.is_alphabetic())
+                        })
+                        .map(str::to_owned),
+                );
+            }
+        }
+
+        if next.is_empty() {
+            return false;
+        }
+        frontier = next;
+    }
+
+    false
+}
+
+/// `ident` 在 `body` 里的绑定表达式（`let` 与 `Some(ident) =` 两种形状）。
+fn binding_rhs<'a>(body: &'a str, ident: &str) -> Vec<&'a str> {
+    let mut rhs = Vec::new();
+
+    for pattern in [format!("let {ident} = "), format!("let mut {ident} = ")] {
+        let mut from = 0;
+        while let Some(index) = body[from..].find(&pattern) {
+            let start = from + index + pattern.len();
+            let end = body[start..].find(';').map_or(body.len(), |at| start + at);
+            rhs.push(&body[start..end]);
+            from = end;
+        }
+    }
+
+    let pattern = format!("Some({ident}) = ");
+    let mut from = 0;
+    while let Some(index) = body[from..].find(&pattern) {
+        let start = from + index + pattern.len();
+        let end = body[start..].find('{').map_or(body.len(), |at| start + at);
+        rhs.push(&body[start..end]);
+        from = end;
+    }
+
+    rhs
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/app-iced/src/pages/layout/source/tests.rs b/crates/app-iced/src/pages/layout/source/tests.rs
new file mode 100644
index 0000000..007d71b
--- /dev/null
+++ b/crates/app-iced/src/pages/layout/source/tests.rs
@@ -0,0 +1,178 @@
+//! `source` 自己的断言：切得准、切得住（门禁的门禁）。
+//!
+//! 口径与 `tests/no_hardcoded_tokens.rs::the_gate_itself_catches_a_planted_violation` 一致：
+//! 护栏工具自己先被一条断言钉住，否则它退化时没人发现。
+
+use super::*;
+
+const SAMPLE: &str = "\
+/// doc
+pub fn alpha() -> u8 {
+    let inner = |x: u8| {
+        x
+    };
+    inner(1)
+}
+
+pub fn beta<'a>(value: &'a str) -> &'a str {
+    value
+}
+";
+
+#[test]
+fn it_stops_at_the_top_level_closing_brace() {
+    let alpha = function_body(SAMPLE, "pub fn alpha");
+    assert!(alpha.starts_with("pub fn alpha"));
+    assert!(alpha.trim_end().ends_with('}'), "{alpha}");
+    // 内层闭包的花括号不会提前截断：`inner(1)` 与它的 `};` 都在
+    assert!(alpha.contains("inner(1)"), "{alpha}");
+    assert!(!alpha.contains("pub fn beta"), "切到了下一个函数：{alpha}");
+
+    let beta = function_body(SAMPLE, "pub fn beta<'a>(");
+    assert!(beta.contains("value"), "{beta}");
+    assert!(!beta.contains("inner("), "{beta}");
+}
+
+#[test]
+fn the_helper_also_works_on_signatures_with_generics_and_multiline_params() {
+    let source = "pub fn gamma<'a>(\n    metrics: FrameMetrics,\n    content: u8,\n) -> u8 {\n    content\n}\n";
+    let gamma = function_body(source, "pub fn gamma");
+    assert!(gamma.contains("metrics: FrameMetrics"), "{gamma}");
+    assert!(gamma.trim_end().ends_with('}'), "{gamma}");
+}
+
+/// `statement` 停在第一个 `;`：构建链断言靠它精确到一个容器。
+#[test]
+fn a_statement_stops_at_the_first_semicolon() {
+    let source = "\
+let mut rows = column(entries)
+    .padding(Padding::from([0.0, ui.space(Space::X2)]))
+    .width(Length::Fill);
+let other = 1;
+";
+    let chain = statement(source, "let mut rows = column(");
+    assert!(chain.starts_with("let mut rows"), "{chain}");
+    assert!(chain.ends_with(".width(Length::Fill);"), "{chain}");
+    assert!(!chain.contains("let other"), "越过语句边界：{chain}");
+}
+
+/// `function_region` 把**本文件内被调用的函数**也算进契约（等价重构不假红）。
+#[test]
+fn the_region_follows_one_level_of_delegation() {
+    let source = "\
+pub fn outer(a: u8) -> u8 {
+    inner(a) + 1
+}
+
+fn inner(a: u8) -> u8 {
+    a * 2
+}
+
+fn unrelated(a: u8) -> u8 {
+    a - 9
+}
+";
+    let region = function_region(source, "pub fn outer(");
+    assert!(region.contains("inner(a) + 1"), "{region}");
+    assert!(region.contains("a * 2"), "转调目标没进来：{region}");
+    assert!(!region.contains("a - 9"), "把无关函数也扫进来了：{region}");
+}
+
+/// 转调目标带**泛型签名**时也要跟进去（`frame::body` → `body_impl<'a>` 就是这种形状）。
+///
+/// 这条是变异 H1 抓出来的：早先的实现拿 `fn {name}(` 当定义 needle，遇到
+/// `fn body_impl<'a>(` 找不到 ⇒ 护栏自己 panic ⇒ 对等价重构**假红**。
+#[test]
+fn the_region_follows_delegation_into_a_generic_function() {
+    let source = "\
+pub fn wrapper(v: u8) -> u8 {
+    helper(v) + 1
+}
+
+fn helper<'a>(v: u8) -> u8 {
+    v * 3
+}
+";
+    let region = function_region(source, "pub fn wrapper(");
+    assert!(region.contains("v * 3"), "泛型签名没跟进去：{region}");
+}
+
+#[test]
+#[should_panic(expected = "找不到签名")]
+fn a_missing_signature_fails_loudly() {
+    let _ = function_body(SAMPLE, "pub fn nope");
+}
+
+/// 跨文件转调也要跟进去（`frame::body` → `layout::block::body_box` 就是这种形状）。
+///
+/// 变异 M6（把盒子原样搬进 `layout/block.rs`）在单文件版下假红；多文件版应当放行。
+#[test]
+fn the_region_follows_delegation_across_files() {
+    let frame = "\
+pub fn body(a: u8) -> u8 {
+    block::body_box(a) + 1
+}
+";
+    let block = "\
+pub fn body_box(a: u8) -> u8 {
+    a * 7
+}
+";
+    let region = region_across(&[frame, block], "pub fn body(");
+    assert!(region.contains("body_box(a) + 1"), "{region}");
+    assert!(region.contains("a * 7"), "跨文件转调没跟进去：{region}");
+}
+
+/// `call_arguments` 取到的是**实参原文**（嵌套括号完整），这是 M4 那条护栏的判据基础。
+#[test]
+fn call_arguments_returns_the_nested_argument_text() {
+    let source = "\
+rows = rows.spacing(ui.space(Space::X1));
+rows = rows.spacing(ui.space(step));
+column![head, scroller].spacing(ui.space(Space::X2));
+";
+    let args = call_arguments(source, "rows.spacing(");
+    assert_eq!(args, vec!["ui.space(Space::X1)", "ui.space(step)"]);
+    assert!(
+        args[0].contains("Space::") && !args[1].contains("Space::"),
+        "实参文本要能区分「写死令牌」与「经变量中转」：{args:?}"
+    );
+}
+
+/// `derived_from` 顺绑定链追源头：真源放行、中转一层写死令牌判否（变异 M4 的判据）。
+#[test]
+fn binding_tracing_separates_the_truth_source_from_a_smuggled_token() {
+    let honest = "\
+    if let Some(spacing) = ROW_SPACING {
+        rows = rows.spacing(ui.space(spacing));
+    }
+";
+    assert!(derived_from(honest, "spacing", "ROW_SPACING"));
+
+    // 经局部变量中转一次（变异 H3 的等价重构形状）：仍要追到 ROW_SPACING
+    let via_local = "\
+    let spacing = ROW_SPACING;
+    if let Some(step) = spacing {
+        rows = rows.spacing(ui.space(step));
+    }
+";
+    assert!(derived_from(via_local, "step", "ROW_SPACING"));
+
+    // 把写死令牌挪到另一条 let 再传（变异 M4）：追不到 ROW_SPACING
+    let smuggled = "\
+    if let Some(spacing) = ROW_SPACING {
+        rows = rows.spacing(ui.space(spacing));
+    }
+
+    let extra = Space::X1;
+    rows = rows.spacing(ui.space(extra));
+";
+    assert!(!derived_from(smuggled, "extra", "ROW_SPACING"));
+    assert!(derived_from(smuggled, "spacing", "ROW_SPACING"));
+}
+
+#[test]
+#[should_panic(expected = "找不到语句起点")]
+fn a_missing_statement_start_fails_loudly() {
+    let _ = statement(SAMPLE, "let nope = 1");
+}
diff --git a/crates/app-iced/src/pages/layout/tests.rs b/crates/app-iced/src/pages/layout/tests.rs
new file mode 100644
index 0000000..c795876
--- /dev/null
+++ b/crates/app-iced/src/pages/layout/tests.rs
@@ -0,0 +1,367 @@
+//! `layout` 的断言：断点表、版面决议、行宽上限、列宽几何。
+//!
+//! 这些是**门禁级**断言：阈值改错必须立刻红（tower 会故意改错来验）。
+use super::*;
+
+/// 断点表：官方 600 / 840 两个硬值，边界闭开区间逐点钉死。
+#[test]
+fn breakpoints_are_the_official_600_and_840() {
+    assert_eq!(BREAKPOINT_MEDIUM, 600.0, "官方 medium 断点");
+    assert_eq!(BREAKPOINT_EXPANDED, 840.0, "官方 expanded 断点");
+
+    for (width, expected) in [
+        (320.0, WidthClass::Compact),
+        (599.0, WidthClass::Compact),
+        (599.9, WidthClass::Compact),
+        (600.0, WidthClass::Medium),
+        (720.0, WidthClass::Medium),
+        (839.0, WidthClass::Medium),
+        (839.9, WidthClass::Medium),
+        (840.0, WidthClass::Expanded),
+        (900.0, WidthClass::Expanded),
+        (1180.0, WidthClass::Expanded),
+        (2560.0, WidthClass::Expanded),
+    ] {
+        assert_eq!(
+            WidthClass::of(width),
+            expected,
+            "{width} 宽应该判为 {expected:?}"
+        );
+    }
+}
+
+/// 版面决议表（tower 会照这张表对文档）：一列写死「宽度 → 版面」。
+#[test]
+fn layout_table_matches_the_documented_thresholds() {
+    // (窗口宽度, 实例页, 设置页, 下载/日志页)
+    let table = [
+        (
+            320.0,
+            PageLayout::SingleColumn,
+            PageLayout::SingleColumn,
+            PageLayout::SingleColumn,
+        ),
+        (
+            599.0,
+            PageLayout::SingleColumn,
+            PageLayout::SingleColumn,
+            PageLayout::SingleColumn,
+        ),
+        (
+            700.0,
+            PageLayout::SingleColumn,
+            PageLayout::SingleColumn,
+            PageLayout::SingleColumn,
+        ),
+        (
+            720.0,
+            PageLayout::SingleColumn,
+            PageLayout::SupportingPane,
+            PageLayout::SingleColumn,
+        ),
+        (
+            800.0,
+            PageLayout::SingleColumn,
+            PageLayout::SupportingPane,
+            PageLayout::SingleColumn,
+        ),
+        (
+            839.0,
+            PageLayout::SingleColumn,
+            PageLayout::SupportingPane,
+            PageLayout::SingleColumn,
+        ),
+        (
+            840.0,
+            PageLayout::ListDetail,
+            PageLayout::SupportingPane,
+            PageLayout::SingleColumn,
+        ),
+        (
+            900.0,
+            PageLayout::ListDetail,
+            PageLayout::SupportingPane,
+            PageLayout::SingleColumn,
+        ),
+        (
+            1180.0,
+            PageLayout::ListDetail,
+            PageLayout::SupportingPane,
+            PageLayout::SingleColumn,
+        ),
+        (
+            1920.0,
+            PageLayout::ListDetail,
+            PageLayout::SupportingPane,
+            PageLayout::SingleColumn,
+        ),
+    ];
+
+    for (width, instances, settings, single) in table {
+        assert_eq!(
+            resolve(PaneKit::ListDetail, width),
+            instances,
+            "{width} 宽实例页版面不对"
+        );
+        assert_eq!(
+            resolve(PaneKit::Supporting, width),
+            settings,
+            "{width} 宽设置页版面不对"
+        );
+        assert_eq!(
+            resolve(PaneKit::Single, width),
+            single,
+            "{width} 宽单列页版面对不"
+        );
+    }
+}
+
+#[test]
+fn pane_thresholds_are_the_sum_of_their_columns() {
+    // 336 + 320 + 24 + 2×24 + 88 = 816
+    assert_eq!(list_detail_min_window(), 816.0);
+    // 240 + 320 + 24 + 2×24 + 88 = 720
+    assert_eq!(supporting_pane_min_window(), 720.0);
+    // 官方 expanded 断点必须**宽于** list-detail 的几何门槛，否则「840 起用 list-detail」是空话
+    assert!(
+        BREAKPOINT_EXPANDED >= list_detail_min_window(),
+        "840 档必须放得下 336 + 24 + 320 的三列和"
+    );
+    // 设置页在 medium 档里就有能用的窗口宽度（720 < 840）
+    assert!(supporting_pane_min_window() < BREAKPOINT_EXPANDED);
+    assert!(WidthClass::of(supporting_pane_min_window()) == WidthClass::Medium);
+}
+
+/// 实测样本：**实例页详情那段正文**（`pages/instances/data.rs` 的 `NOTE`）。
+///
+/// 口径（`layout` 模块文档 §3）：Segoe UI Regular @14px、无 letter-spacing、
+/// FreeType `getlength` 求整段排版宽。**这是外部实测数据，不是从常量推出来的**——
+/// 下面的断言拿它反算「一行能放几个字符」，所以把 `CHAR_ADVANCE_EM` 改回估算值会立刻红。
+const MEASURE_SAMPLE_CHARS: f32 = 361.0;
+const MEASURE_SAMPLE_WIDTH_PX: f32 = 2185.0;
+
+/// 样本的实测平均步进（px/字符）。
+fn measured_advance_px() -> f32 {
+    MEASURE_SAMPLE_WIDTH_PX / MEASURE_SAMPLE_CHARS
+}
+
+/// 给定列宽，按**实测步进**能放多少字符。
+fn chars_per_line(width: f32) -> f32 {
+    width / measured_advance_px()
+}
+
+/// **逐行**折行模拟结果（FreeType `getlength` 量宽 + 贪心词折行，脚本见模块文档 §3）。
+///
+/// 四个数都是外部实测，口径要分清（视觉 r3 提醒过这里容易写糊）：
+/// - `SAFE_MAX_CHARS` / `SAFE_MAX_CHARS_INK`：cap=424 时**字符最多**的那一行 —— 67 字符，ink **402px**；
+/// - `SAFE_WIDEST_INK`：cap=424 时**墨迹最宽**的那一行 —— **411px**（不是同一行！402 那行字符多但字形窄）；
+/// - `BREAK_INK` / `BREAK_CHARS`：第一档会冒出 73 字符行的宽度 428px（那行 ink 428px）。
+///
+/// 有了它，Rust 侧不用字体引擎也能把「上限必须夹在这些数之间」写成断言。
+const SIM_SAFE_MAX_CHARS: f32 = 67.0;
+const SIM_SAFE_MAX_CHARS_INK: f32 = 402.0;
+const SIM_SAFE_WIDEST_INK: f32 = 411.0;
+const SIM_BREAK_INK: f32 = 428.0;
+const SIM_BREAK_CHARS: f32 = 73.0;
+
+/// 行宽上限必须真的停在 72 字符：名字、常量、**逐行模拟**三者一致。
+#[test]
+fn line_length_is_capped_at_72_characters() {
+    // ① 常量对得上实测步进（14px 下的平均步进）
+    let body_size = TypeRole::BodyMedium.style().size_px;
+    assert_eq!(body_size, 14.0);
+    assert!(
+        (measured_advance_px() - body_size * CHAR_ADVANCE_EM).abs() < 0.02,
+        "CHAR_ADVANCE_EM = {CHAR_ADVANCE_EM} 与实测步进 {:.4}px/字符对不上",
+        measured_advance_px()
+    );
+    assert_eq!(measure_floor_px(), 272.0, "floor(14 × 0.43233 × 45)");
+
+    // ② 上限是**逐行**模拟出来的 424，不是「平均步进 × 72」的算术值 435
+    assert_eq!(measure_cap_px(), 424.0, "逐行安全宽（4px 栅格）");
+    assert_eq!(
+        measure_average_bound_px(),
+        435.0,
+        "floor(14 × 0.43233 × 72)"
+    );
+    assert!(
+        measure_cap_px() < measure_average_bound_px(),
+        "平均口径上界必须比逐行安全宽**更宽**——这说明 cap 不是拿平均算出来的"
+    );
+
+    // ③ 交付宽度下两条实测线都装得下：字符最多那行（402px）与墨迹最宽那行（411px）
+    assert!(
+        SIM_SAFE_MAX_CHARS_INK <= measure_cap_px(),
+        "字符最多那行 {}px 超过上限 {}px",
+        SIM_SAFE_MAX_CHARS_INK,
+        measure_cap_px()
+    );
+    assert!(
+        SIM_SAFE_WIDEST_INK <= measure_cap_px(),
+        "墨迹最宽那行 {}px 超过上限 {}px（余量只有 {}px）",
+        SIM_SAFE_WIDEST_INK,
+        measure_cap_px(),
+        measure_cap_px() - SIM_SAFE_WIDEST_INK
+    );
+    const { assert!(SIM_SAFE_MAX_CHARS <= MAX_MEASURE_CHARS) };
+
+    // ④ **两侧夹逼**：这是本条真正的护栏。
+    //    放大到 SIM_BREAK_INK（428）逐行模拟就会重新出现 73 字符行；
+    //    压到 SAFE 以下则纯属白丢宽度。两个方向都会红。
+    assert!(
+        measure_cap_px() < SIM_BREAK_INK,
+        "上限 ≥{SIM_BREAK_INK}px 时逐行模拟会再次出现 {SIM_BREAK_CHARS} 字符行——请重跑折行模拟"
+    );
+    assert!(
+        measure_cap_px() >= SIM_SAFE_WIDEST_INK,
+        "上限 {}px 比模拟出来的最宽行 {}px 还窄，白丢宽度",
+        measure_cap_px(),
+        SIM_SAFE_WIDEST_INK
+    );
+
+    // ⑤ 平均口径的回归护栏：旧 0.5em 的 504px 在实测步进下能放 83 字符
+    assert!(
+        chars_per_line(504.0) > MAX_MEASURE_CHARS + 10.0,
+        "504px 在实测步进下应能放 >82 字符（旧口径的破绽），现在算出来 {:.1}",
+        chars_per_line(504.0)
+    );
+
+    for width in [600.0, 840.0, 900.0, 1180.0, 1440.0, 2560.0] {
+        let column = content_column_width(width);
+        // 平均口径只是次要护栏（逐行口径见上面的模拟常数）
+        assert!(
+            chars_per_line(column) <= MAX_MEASURE_CHARS,
+            "{width} 宽窗口的平均行宽 {:.1} 字符，超过 {MAX_MEASURE_CHARS}",
+            chars_per_line(column)
+        );
+        assert!(column <= measure_cap_px() + f32::EPSILON);
+    }
+
+    // 1180 —— M68 就是在这条上翻的车（712px），现在必须是 424（= measure_cap_px()）
+    let wide = content_column_width(1180.0);
+    assert_eq!(wide, measure_cap_px());
+    assert!(wide < 712.0, "不许回到 M68 的全宽单卡（712px）");
+}
+
+#[test]
+fn line_length_tracks_width_until_it_hits_the_cap() {
+    // 窄窗：正文列跟着可用宽度走（480 宽还在上限以内），撞上上限就锁死
+    let narrow = content_column_width(480.0);
+    assert!(narrow < measure_cap_px(), "480 宽时正文列应窄于上限");
+    assert_eq!(narrow, available_width(480.0));
+
+    // 单调不减：窗口变宽，正文列不变窄
+    let mut previous = 0.0;
+    for width in [320.0, 480.0, 600.0, 720.0, 840.0, 1024.0, 1180.0, 1600.0] {
+        let column = content_column_width(width);
+        assert!(column >= previous, "{width} 宽的正文列比更窄时还小");
+        previous = column;
+    }
+
+    // 一旦撞上上限就锁死（宽窗不会继续变宽）
+    assert_eq!(content_column_width(1180.0), measure_cap_px());
+    assert_eq!(content_column_width(1920.0), measure_cap_px());
+}
+
+#[test]
+fn list_detail_geometry_keeps_the_list_column_in_range() {
+    let metrics = frame_metrics(PaneKit::ListDetail, 1180.0);
+    assert_eq!(metrics.layout, PageLayout::ListDetail);
+
+    let list = metrics.secondary.expect("list-detail 必须有列表列");
+    assert!(
+        (320.0..=360.0).contains(&list),
+        "列表列 {list} 不在 320~360 参考区间"
+    );
+    assert_eq!(list, LIST_COLUMN_WIDTH);
+
+    // 详情正文列：≤ 行宽上限，且明显窄于「窗口全宽」
+    assert!(metrics.column <= measure_cap_px() + f32::EPSILON);
+    assert!(metrics.column < metrics.available, "详情列必须窄于可用宽度");
+
+    // 列表列 + 间隙 + 详情 pane = 可用宽度（不留缝）
+    assert_eq!(
+        list + PANES_GAP + metrics.main_pane,
+        metrics.available,
+        "两列几何必须铺满可用宽度"
+    );
+}
+
+#[test]
+fn list_detail_degrades_to_one_column_below_the_threshold() {
+    for width in [320.0, 599.0, 700.0, 816.0, 839.0] {
+        assert_eq!(
+            frame_metrics(PaneKit::ListDetail, width).layout,
+            PageLayout::SingleColumn,
+            "{width} 宽应该退化成单列"
+        );
+        assert!(frame_metrics(PaneKit::ListDetail, width)
+            .secondary
+            .is_none());
+    }
+
+    // 840 = 官方 expanded 断点，list-detail 从这里成立
+    assert_eq!(
+        frame_metrics(PaneKit::ListDetail, 840.0).layout,
+        PageLayout::ListDetail
+    );
+    // 840 宽下详情正文列仍要够宽（≥ 下限），否则等于假分栏
+    let at_breakpoint = frame_metrics(PaneKit::ListDetail, 840.0);
+    assert!(
+        at_breakpoint.column >= measure_floor_px(),
+        "840 宽下详情列 {:?} 低于行宽下限",
+        at_breakpoint.column
+    );
+}
+
+#[test]
+fn settings_pane_keeps_the_drawer_width_and_a_readable_form_column() {
+    let metrics = frame_metrics(PaneKit::Supporting, 1180.0);
+    assert_eq!(metrics.layout, PageLayout::SupportingPane);
+    assert_eq!(metrics.secondary, Some(SIDE_NAV_WIDTH));
+    assert_eq!(SIDE_NAV_WIDTH, 240.0, "D33：展开态是 240 的 drawer");
+    assert_eq!(metrics.column, measure_cap_px(), "表单列吃满行宽上限");
+    assert_eq!(measure_cap_px(), 424.0);
+
+    let narrow = frame_metrics(PaneKit::Supporting, 700.0);
+    assert_eq!(narrow.layout, PageLayout::SingleColumn);
+    assert!(narrow.secondary.is_none());
+}
+
+#[test]
+fn meta_grid_drops_columns_as_the_detail_narrows() {
+    // 160 宽卡：3 列要 3×160 + 2×12 = 504（超出行宽上限），所以上限处就是 2 列；2 列要 332
+    assert_eq!(meta_columns(measure_cap_px()), 2, "2×160 + 12 = 332");
+    assert_eq!(meta_columns(340.0), 2);
+    assert_eq!(meta_columns(330.0), 1);
+
+    // 1180 与 900 都是 2 列（160 宽卡三列塞不进行宽上限），差别落在详情列宽
+    let wide = frame_metrics(PaneKit::ListDetail, 1180.0);
+    let mid = frame_metrics(PaneKit::ListDetail, 900.0);
+    assert_eq!(wide.meta_columns, 2);
+    assert_eq!(mid.meta_columns, 2);
+    assert!(mid.column < wide.column, "900 宽下详情列必须真的变窄");
+}
+
+#[test]
+fn gutters_follow_the_class_and_are_on_the_grid() {
+    assert_eq!(WidthClass::Compact.gutter(), 16.0);
+    assert_eq!(WidthClass::Medium.gutter(), 24.0);
+    assert_eq!(WidthClass::Expanded.gutter(), 24.0);
+    for class in [
+        WidthClass::Compact,
+        WidthClass::Medium,
+        WidthClass::Expanded,
+    ] {
+        assert_eq!(class.gutter() % 4.0, 0.0, "{class:?} 的页边距不在 4px 栅格");
+    }
+}
+
+#[test]
+fn page_layout_names_are_stable() {
+    assert_eq!(PageLayout::SingleColumn.name(), "single-column");
+    assert_eq!(PageLayout::SupportingPane.name(), "supporting-pane");
+    assert_eq!(PageLayout::ListDetail.name(), "list-detail");
+    assert!(!PageLayout::SingleColumn.is_two_pane());
+    assert!(PageLayout::ListDetail.is_two_pane());
+}
diff --git a/crates/app-iced/src/pages/layout/wrap.rs b/crates/app-iced/src/pages/layout/wrap.rs
new file mode 100644
index 0000000..6ba1183
--- /dev/null
+++ b/crates/app-iced/src/pages/layout/wrap.rs
@@ -0,0 +1,84 @@
+//! **断行工具**：给没有空格的长标识符补上「软断点」。
+//!
+//! ## 为什么在这里而不是日志页里
+//!
+//! 这是**排版度量**问题，不是日志页的私事：`layout.rs` 已经是页面级几何的唯一真源
+//! （档位 / 版面 / 列宽 / 行宽上限），「一行在哪儿能断」属于同一类判据的第二半——
+//! 列宽决定**能放多宽**，断点决定**放不下时从哪儿折**。放在 `layout/` 下面：
+//!
+//! - 日志页（`pages/logs/**`）与以后任何要排长串的页都能用，不产生第二份实现；
+//! - 它是纯函数（`&str → String`），不碰 iced 控件树，能在单测里逐字符钉死。
+//!
+//! ## 修的是什么（M102 视觉复审的 ③）
+//!
+//! 崩溃日志的一行摘要与堆栈里有 `graphics.gl_operation_failure:medium(70)` 这种
+//! **完全没有空格**的长串：iced 的 `Wrapping::Word` 找不到断点，只能退化成按字形硬断，
+//! 于是图里出现了 `graphics.gl_o` / `peration_failure`——单词被从中间劈开。
+//!
+//! 修法不是改字号也不是截断（截断会让用户拿不回原始堆栈），而是往
+//! `.` `_` `:` `/` `\` 这些**标识符/路径分隔符后面**插一个**零宽空格**（U+200B）：
+//!
+//! - U+200B 是 Unicode 的**软断点**（UAX #14 `ZW`）：排版时可以在这里折行，但不占宽度、
+//!   不产生字形，`Wrapping::WordOrGlyph` 会优先在它那里折；
+//! - 它只进**显示**用的字符串，不进数据：`Logs::summary()`（剪贴板）与 `Line::text`
+//!   （视图模型）仍是原文，`strip` 一下就能还原（见单测）。
+//!
+//! ## 边界（没做什么）
+//!
+//! - 只在**分隔符之后**插，不在之前：「`a.b`」断成「`a.` / `b`」比「`a` / `.b`」好读；
+//! - 分隔符后面紧跟空白、或结尾，就不插（`Wrapping` 本来就能在空白处折）；
+//! - 连续分隔符（`a..b`、`a/_b`）只在最后那个后面插一个，不制造一串空断点；
+//! - `-` **不插**：时间戳 `2026-11-02 19:40` 断在日期中间比不断更难看，
+//!   而 `-` 两侧几乎都有空白/标点兜底。
+
+/// 零宽空格（U+200B）：可断行、不占宽度的软断点。
+pub const SOFT_BREAK: char = '\u{200b}';
+
+/// 软断点允许落在哪些字符**之后**。
+///
+/// 取标识符 / 路径 / 规则 id 的分隔符：`integrity.unsatisfied_link`、
+/// `graphics.gl_operation_failure:medium(70)`、`logs/2026-11-02/client.txt`、
+/// `AppData\Roaming\.unlucky\instances\dev-test\natives`（Windows 路径，反斜杠也断）。
+pub const BREAK_AFTER: [char; 5] = ['.', '_', ':', '/', '\\'];
+
+/// 给 `text` 补上软断点（返回**显示用**的新串；数据侧原文不动）。
+///
+/// 幂等：对已经补过断点的串再跑一遍不会插更多（U+200B 不是分隔符，也不是空白以外的可断字符）。
+pub fn breakable(text: &str) -> String {
+    let mut out = String::with_capacity(text.len() + text.len() / 8);
+    let mut chars = text.chars().peekable();
+
+    while let Some(ch) = chars.next() {
+        out.push(ch);
+
+        if !BREAK_AFTER.contains(&ch) {
+            continue;
+        }
+
+        // 只在「分隔符 + 真内容」之间插：结尾、空白、连续分隔符、已有软断点都不插。
+        let worth_breaking = chars.peek().is_some_and(|next| {
+            !next.is_whitespace() && *next != SOFT_BREAK && !BREAK_AFTER.contains(next)
+        });
+
+        if worth_breaking {
+            out.push(SOFT_BREAK);
+        }
+    }
+
+    out
+}
+
+/// 去掉 [`breakable`] 插进去的软断点（还原成数据原文）。
+///
+/// 只给测试与调试用：页面渲染时不需要还原（原文从未被改写）。
+///
+/// **限界（r1 复审指出）**：它删的是**所有** U+200B，所以原文自带的零宽空格也会被一并删掉
+/// （`strip(breakable(x)) == x` 只在「x 本身不含 U+200B」时成立；实测样例里没有这种串）。
+/// 这个函数因此只配「与 [`breakable`] 成对使用」的场景，不能当通用的原文还原器用——
+/// 产品侧从不调用它，剪贴板/视图模型拿的本来就是没动过的原文。
+pub fn strip(text: &str) -> String {
+    text.chars().filter(|ch| *ch != SOFT_BREAK).collect()
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/app-iced/src/pages/layout/wrap/tests.rs b/crates/app-iced/src/pages/layout/wrap/tests.rs
new file mode 100644
index 0000000..fac9d82
--- /dev/null
+++ b/crates/app-iced/src/pages/layout/wrap/tests.rs
@@ -0,0 +1,102 @@
+//! `wrap` 的断言：软断点插在哪、插完还能不能还原。
+//!
+//! 口径与 `layout/tests.rs` 一致：只钉**纯函数**（断点位置 / 原文可还原），
+//! 「渲染器是不是真在那里折」由截图与报告里的前后对照图负责。
+
+use super::*;
+
+/// 视觉复审 ③ 的原话样本：这两个被劈开的词必须重新可断。
+#[test]
+fn identifiers_break_after_their_separators() {
+    let summary =
+        "findings=integrity.unsatisfied_link:high(85),graphics.gl_operation_failure:medium(70)";
+    let broken = breakable(summary);
+
+    // 抓得住：断点漏掉 `_` / `.` / `:`（那就退化成按字形硬断，`graphics.gl_o` + `peration_failure` 复现）；
+    // 抓不住：渲染器最终在哪一列折行（那要量图，见报告）。
+    for seam in [
+        "integrity.\u{200b}",
+        "unsatisfied_\u{200b}",
+        "link:\u{200b}",
+        "graphics.\u{200b}",
+        "gl_\u{200b}",
+        "operation_\u{200b}",
+        "failure:\u{200b}",
+    ] {
+        assert!(broken.contains(seam), "缺断点 {seam:?}：{broken}");
+    }
+}
+
+/// 路径样本：`logs/2026-11-02/client.txt` 在 `/` 与 `.` 后能断，日期里的 `-` 不许断。
+#[test]
+fn paths_break_after_slashes_but_not_inside_dates() {
+    let broken = breakable("logs/2026-11-02/client.txt");
+    assert!(broken.contains("logs/\u{200b}"), "{broken}");
+    assert!(broken.contains("client.\u{200b}txt"), "{broken}");
+    // 日期整体不拆：`-` 不在断点表里，视觉复审没要求、拆开反而难读。
+    assert!(broken.contains("2026-11-02"), "{broken}");
+
+    // Windows 路径：反斜杠同样是断点（日志里 `AppData\Roaming\...\dev-test\natives\...`）
+    let win =
+        breakable("C:\\Users\\Player\\AppData\\Roaming\\.unlucky\\instances\\dev-test\\natives");
+    assert!(win.contains("Player\\\u{200b}"), "{win}");
+    assert!(win.contains("natives"), "{win}");
+}
+
+/// 不该插的地方一个都不插：结尾、空白之后、连续分隔符。
+#[test]
+fn no_dangling_or_doubled_breaks() {
+    assert_eq!(breakable(""), "");
+    assert_eq!(breakable("plain text"), "plain text");
+    assert_eq!(breakable("trailing."), "trailing.", "结尾不插");
+    assert_eq!(
+        breakable("a. b"),
+        "a. b",
+        "分隔符后面是空白：Wrapping 本来就能在空白处折"
+    );
+    assert_eq!(
+        breakable("a..b"),
+        "a..\u{200b}b",
+        "连续分隔符只在最后一处断"
+    );
+    assert_eq!(breakable("a:/b"), "a:/\u{200b}b");
+
+    // 抓得住：有人在每个字符后面都插（那就等于按字形断，本 mission 的修法失效）。
+    assert!(
+        !breakable("abcdef").contains(SOFT_BREAK),
+        "没有任何分隔符的串不该出现断点"
+    );
+}
+
+/// 只改显示：`strip` 还原后与原文逐字符相同（剪贴板/日志原文不许被污染）。
+#[test]
+fn breaking_is_reversible_and_idempotent() {
+    for text in [
+        "graphics.gl_operation_failure:medium(70)",
+        "[19:40:12] [main/ERROR] 启动失败: exit code 1",
+        "at com.mojang.blaze3d.platform.GLX._initGlfw(GLX.java:64)",
+    ] {
+        let broken = breakable(text);
+        assert_eq!(strip(&broken), text, "还原失败：{broken}");
+        assert_eq!(breakable(&broken), broken, "幂等：再跑一遍不许再插");
+    }
+}
+
+/// **已知限界**（r1 复审 P2）：`strip` 删的是**所有** U+200B，原文自带的也会被删。
+///
+/// 这条不修（产品侧从不调用 `strip`，剪贴板/模型拿的是未改写的原文），但要把行为钉住：
+/// 将来谁想拿 `strip` 当通用还原器，这里会告诉他为什么不行。
+#[test]
+fn strip_is_not_a_general_unbreaker() {
+    let original_with_zwsp = "a\u{200b}b";
+    assert_eq!(
+        breakable(original_with_zwsp),
+        original_with_zwsp,
+        "没有分隔符就不插"
+    );
+    assert_eq!(
+        strip(original_with_zwsp),
+        "ab",
+        "strip 会连同原文自带的 U+200B 一起删（已知限界，不是 bug 修复点）"
+    );
+}
diff --git a/crates/app-iced/src/pages/logs.rs b/crates/app-iced/src/pages/logs.rs
new file mode 100644
index 0000000..eca01ab
--- /dev/null
+++ b/crates/app-iced/src/pages/logs.rs
@@ -0,0 +1,159 @@
+//! 日志页（M95）：**单列**版面的第二个用例，也是本项目卖点（崩溃日志诊断）的落地页。
+//!
+//! ## 一屏由三块组成
+//!
+//! ```text
+//! ┌ 页头（两行 84：标题 + 运行状态；右侧 Open folder / Clear）──────────┐
+//! ├ 诊断卡片（只在有结论时出现，**按置信度档分组**：HIGH / MEDIUM / LOW）──┤
+//! │   DIAGNOSIS 3        CRITICAL 1 / WARNING 2                        │
+//! │   integrity.unsatisfied_link（规则 id，等宽）                       │
+//! │   结论（规则表原文） / 说明 / Suggested fix / Confidence 85%        │
+//! │   ─ One-line summary ─ (等宽可复制的一行) [Copy summary]            │
+//! ├ 日志行列表（等宽 + 折行 + **独立滚动**，吃满剩余高度）──────────────┤
+//! └──────────────────────────────────────────────────────────────────┘
+//! ```
+//!
+//! 数据源只有两个（页面**不读盘**，路径从不进过页面）：
+//!
+//! | 来源 | 谁造 | 用途 |
+//! |---|---|---|
+//! | presenter 快照（`log_lines` / `diagnosis` / `log_sessions`） | `app/view.rs::logs_model` | 产品运行时 |
+//! | [`demo`] 内嵌的崩溃日志片段 | `pages::demo_model`（`ULL_LOGS_FIXTURE=empty\|live\|crash`） | 出图 |
+//!
+//! ## M95 的取舍（逐条）
+//!
+//! | # | 取舍 | 为什么 |
+//! |---|---|---|
+//! | 1 | **折行**而不是横向滚动 | 见 [`lines`] 模块文档：一行 200+ 字符的现实下，横滚与外壳竖向滚动打架，且等宽族的 CJK 回退会毁掉「按列对齐」这个横滚唯一的好处 |
+//! | 2 | 诊断卡片在日志列表**之上** | 崩溃时用户先要结论；把结论放在 14 行日志下面等于让人先翻页 |
+//! | 3 | 规则原文（中文）当**数据**直接画 | 界面文案全走 i18n key；规则表的 `cause.summary` 是诊断结论本身，翻译要等 `rules.d` 带 `cause.key` 进 DTO（已报 finding） |
+//! | 4 | 分组用**置信度档**（High/Medium/Low），不借 core 的严重度词汇 | `dto::Diagnosis` 没带 core 的 `severity`；拿置信度凑严重度会让 64 条规则里 12 条进错组（两个方向都有，复审实测）。档位由 `Confidence::of` 定，DTO 补齐后应换回真严重度（已报 finding） |
+//! | 5 | 页头保持**两行 84** | M84 定的版式（运行状态在副标题上）；计数留在两张卡片自己的标题行，避免为了拼计数把 i18n 字符串漏进页头生命期 |
+//!
+//! ## 指令（只有真业务命令才 dispatch）
+//!
+//! | 控件 | 消息 | 落到哪 |
+//! |---|---|---|
+//! | Copy summary | [`Message::CopySummary`] | `app/update.rs` → `iced::clipboard::write` |
+//! | Open folder | `Action::OpenLogs` | **还没有 `AppCommand`**（报 finding，现在是占位分支） |
+//! | Clear | `Action::ClearLogs` | `app/update.rs` → 清空 presenter 的 `log_lines` |
+//! | 空态的 CTA | [`Message::Navigate`] | 压一层路由栈回实例页（真导航，不是占位动作） |
+//!
+//! 截图的强弱边界写在 `logs/tests.rs` 每条断言下面。
+//!
+//! ## M102：页面块吃满页宽 + 单词不再被劈开
+//!
+//! - 正文块走 [`frame::body`]（左缘 = 页头标题左缘 = 112，宽 = 可用宽度 1044 @1180），
+//!   旧版把整页块压成 424 居中，视觉复审 ① 就是它；
+//! - 日志行与一行摘要先过 [`super::layout::wrap::breakable`]：在 `.` `_` `:` `/` `\` 后面插零宽空格，
+//!   于是 `graphics.gl_operation_failure` 断在 `_` 后面，而不是被按字形劈成 `gl_o` / `peration`。
+//!   零宽空格只进显示串，`Line::text` 与 `Logs::summary()`（剪贴板）仍是原文。
+
+mod demo;
+mod diagnostic;
+mod lines;
+mod model;
+mod panel;
+
+#[cfg(test)]
+mod tests;
+
+/// 诊断卡在正文里的高度份额（见 [`panel`] 的模块文档：两块必须都是定高 + 内部滚动）。
+///
+/// r2 是 3:2 —— 1180×760 下诊断卡的滚动视口只剩 141px，而一条完整结论（分组标题 → 建议动作 →
+/// 置信度）要 177px，于是**首屏看不到任何一条完整结论**（视觉复审 r2 的 P2-A：任务要求的
+/// 「建议动作」在验收尺寸下不可见）。改成 4:2：视口 ~184px，一条结论整块可见。
+const DIAGNOSIS_SHARE: u16 = 4;
+/// 日志卡的高度份额。
+const LOGS_SHARE: u16 = 2;
+
+pub use demo::demo;
+pub use model::{Confidence, Finding, Level, Line, Logs, Outcome};
+
+use iced::widget::column;
+use iced::{Element, Length};
+
+use unlucky_design::icons::IconKind;
+use unlucky_design::spacing::Space;
+use unlucky_i18n::catalog::{Catalog, Key};
+use unlucky_i18n::Lang;
+use unlucky_presenter::router::Route;
+
+use crate::app::components::buttons::{self, Button};
+use crate::app::components::feedback::empty_state::{empty_state, EmptyState};
+use crate::theme::Ui;
+
+use super::frame::{self, Header};
+use super::layout::FrameMetrics;
+use super::{Action, Message};
+
+/// 整页。
+pub fn view<'a>(
+    ui: &'a Ui,
+    metrics: FrameMetrics,
+    logs: &'a Logs,
+    lang: Lang,
+) -> Element<'a, Message> {
+    let catalog = Catalog::of(lang);
+
+    let header = Header::new(catalog.text(Key::NavLogs))
+        .subtitle(subtitle(&catalog, logs))
+        .action(buttons::text(
+            ui,
+            Button::new(
+                catalog.text(Key::LogsOpenFolder),
+                Message::Action(Action::OpenLogs),
+            ),
+        ))
+        .action(buttons::text(
+            ui,
+            Button::new(
+                catalog.text(Key::LogsClear),
+                Message::Action(Action::ClearLogs),
+            ),
+        ));
+
+    let body = if logs.is_empty() {
+        frame::body(metrics, empty(ui, &catalog))
+    } else if logs.findings.is_empty() {
+        // 没有结论：日志卡片独吞整页（这样「正常运行的一场」不会留一块空卡片）。
+        frame::body(metrics, lines::card(ui, logs, lang, Length::Fill))
+    } else {
+        // 有结论：两块**都定高**、各自独立滚动（诊断 4 : 日志 2）。
+        // 定高不是偷懒：第一版让诊断卡按内容撑开，三条结论就把日志卡压成 0 高度（截图见报告）。
+        let stack = column![
+            diagnostic::card(ui, logs, lang, Length::FillPortion(DIAGNOSIS_SHARE)),
+            lines::card(ui, logs, lang, Length::FillPortion(LOGS_SHARE)),
+        ]
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .spacing(ui.space(Space::X4));
+
+        frame::body(metrics, stack)
+    };
+
+    frame::page(ui, metrics, header, body)
+}
+
+/// 页头副标题：有会话身份（实例 · 时间 · 结局）就显示它，否则退回静态文案。
+fn subtitle<'a>(catalog: &Catalog, logs: &'a Logs) -> &'a str {
+    logs.status
+        .as_deref()
+        .unwrap_or_else(|| catalog.text(Key::LogsSubtitleIdle))
+}
+
+/// 空态（`feedback::EmptyState` 真组件：图标块 + 标题 + 说明 + 一个 CTA）。
+fn empty<'a>(ui: &'a Ui, catalog: &Catalog) -> Element<'a, Message> {
+    empty_state(
+        ui,
+        EmptyState::new(
+            IconKind::Logs,
+            catalog.text(Key::LogsEmptyTitle),
+            catalog.text(Key::LogsEmptyBody),
+        )
+        .action(
+            catalog.text(Key::LogsEmptyAction),
+            Message::Navigate(Route::Instances),
+        ),
+    )
+}
diff --git a/crates/app-iced/src/pages/logs/demo.rs b/crates/app-iced/src/pages/logs/demo.rs
new file mode 100644
index 0000000..97b2cd6
--- /dev/null
+++ b/crates/app-iced/src/pages/logs/demo.rs
@@ -0,0 +1,182 @@
+//! 日志页演示数据：**只给 `pages_demo` 出图与单测**，产品运行时的数据来自 presenter 快照
+//! （`app/view.rs::logs_model`）。页面任何路径都不读盘：日志文本要么来自快照，要么来自
+//! 本文件 `include_str!` 内嵌的 [`SAMPLE`]（编译期进二进制，运行时零 I/O）。
+//!
+//! ## 为什么用环境变量挑状态
+//!
+//! 三种状态（空态 / 有日志 / 有诊断）要分别出图，而 `pages_demo` 的 `--screen` 只有一个
+//! `logs`。环境变量是这个 crate 已有的 harness 口径（`ULL_GALLERY_SHOT` / `ULL_FEEDBACK_PART`
+//! 都是这么挑的，见 `components/gallery/mod.rs` 的说明）：既能被测试直接调纯函数覆盖，
+//! 又不用跟别人的 CLI 解析抢同一个文件。
+//!
+//! ```text
+//! ULL_LOGS_FIXTURE=empty pages_demo --screen=logs --screenshot=logs-empty-light.png
+//! ```
+//!
+//! 取值：`empty`（空态）/ `live`（有日志、无诊断）/ 其它或未设 = `crash`（日志 + 三条诊断）。
+//! 默认取 `crash`：一屏就能看见页面的全部结构，reviewer 不必先猜环境变量。
+//!
+//! ## 样例内容的出处
+//!
+//! [`SAMPLE`] 是按 `core/diagnose/rules.d/samples/graphics/graphics_driver.log` 与
+//! `integrity/unsatisfied_link.log` 的形状写的（含中文 + 堆栈 + 200 字符以上的长行），
+//! 诊断结论的 `rule` / `title` / `hint` 抄自规则表 `rules.d/integrity.yaml` 与 `graphics.yaml`。
+//! **中文在这里是「规则表的输出（数据）」，不是界面文案**：界面文案（标题 / 按钮 / 分组名 /
+//! 空态）全部走 `unlucky_i18n` 的 key，见 `logs.rs`。
+
+use unlucky_i18n::Lang;
+
+use super::model::{Confidence, Finding, Level, Line, Logs, Outcome};
+
+/// 挑演示状态的环境变量。
+pub const STATE_ENV: &str = "ULL_LOGS_FIXTURE";
+
+/// 内嵌的崩溃日志片段（见模块文档的出处）。
+const SAMPLE: &str = include_str!("sample_crash.log");
+
+/// 内嵌的**正常跑完**一场的日志片段（`live` 状态用；见 `sample_live.log` 的文件头）。
+const LIVE_SAMPLE: &str = include_str!("sample_live.log");
+
+/// 演示状态。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum State {
+    /// 空态：没有输出，也没有诊断。
+    Empty,
+    /// 有日志、无诊断（正常跑着的一场）。
+    Live,
+    /// 崩溃现场：日志 + 诊断结论。
+    Crash,
+    /// **正在跑**的一场（页头走「正在运行」那条文案；session 索引里还没有它）。
+    Running,
+}
+
+impl State {
+    /// 从环境变量取值解析（未设 / 不认识一律 `Crash`）。
+    ///
+    /// 取值：`empty`（空态）/ `live`（正常跑完的一场）/ `running`（**正在跑**：页头走「正在运行」）
+    /// / 其余 = `crash`。
+    #[must_use]
+    pub fn of_env_value(raw: Option<&str>) -> Self {
+        match raw {
+            Some("empty") => Self::Empty,
+            Some("live") => Self::Live,
+            Some("running") => Self::Running,
+            _ => Self::Crash,
+        }
+    }
+
+    /// 造出这个状态的视图模型（`lang` 用于页头副标题的 i18n）。
+    #[must_use]
+    pub fn build(self, lang: Lang) -> Logs {
+        match self {
+            Self::Empty => Logs::default().with_status(lang),
+            // 正常跑完的一场用**自己的**日志样例：页头写「正常结束」却配崩溃日志尾行是自己打自己
+            // （视觉复审 r2 的 p3）。
+            Self::Live => Logs {
+                instance: Some("开发测试".to_owned()),
+                when: Some("11-02 19:22".to_owned()),
+                outcome: Some(Outcome::Ok),
+                lines: parse(LIVE_SAMPLE),
+                ..Logs::default()
+            }
+            .with_status(lang),
+            // 运行中：还没有结局、也不在 session 索引里（`host::logs::sessions` 只在结束时追加），
+            // 所以既没有实例名也没有 outcome —— 页头只能走「正在运行」那条中性文案。
+            Self::Running => Logs {
+                live: true,
+                lines: parse(LIVE_SAMPLE),
+                ..Logs::default()
+            }
+            .with_status(lang),
+            Self::Crash => crash().with_status(lang),
+        }
+    }
+}
+
+/// harness 入口：按 [`STATE_ENV`] 挑状态。
+#[must_use]
+pub fn demo(lang: Lang) -> Logs {
+    State::of_env_value(std::env::var(STATE_ENV).ok().as_deref()).build(lang)
+}
+
+/// 崩溃现场（日志 + 三条诊断，覆盖 critical / warning 两个分组）。
+///
+/// 不带 `status`（副标题要 i18n，见 [`Logs::with_status`]）：[`State::build`] 会补上。
+#[must_use]
+pub fn crash() -> Logs {
+    Logs {
+        instance: Some("开发测试".to_owned()),
+        when: Some("11-02 19:40".to_owned()),
+        outcome: Some(Outcome::Crashed),
+        lines: parse(SAMPLE),
+        findings: findings(),
+        ..Logs::default()
+    }
+}
+
+/// 解析内嵌样例：`#` 注释与空行跳过，首字符是等级前缀。
+pub(super) fn parse(text: &str) -> Vec<Line> {
+    text.lines()
+        .filter_map(|raw| {
+            let raw = raw.trim_end();
+            if raw.is_empty() || raw.starts_with('#') {
+                return None;
+            }
+
+            // 按**字符**取等级前缀，不 `split_at(1)`：后者在非 ASCII 首字符上会切到
+            // 多字节序列中间直接 panic（视觉复审 r2 的 p3）。
+            let mut chars = raw.chars();
+            let level = match chars.next() {
+                Some('D') => Level::Debug,
+                Some('I') => Level::Info,
+                Some('W') => Level::Warn,
+                Some('E') => Level::Error,
+                _ => return None,
+            };
+
+            Some(Line {
+                text: chars.as_str().trim_start().to_owned(),
+                level,
+            })
+        })
+        .collect()
+}
+
+/// 三条诊断（`rule` / `title` / `hint` 抄自规则表；置信度档走 [`Confidence::of`]，
+/// 也就是 DTO 缺 `severity` 时产品路径用的同一条档位定义）。
+fn findings() -> Vec<Finding> {
+    vec![
+        finding(
+            "integrity.unsatisfied_link",
+            85,
+            "找不到原生库（natives）：lwjgl_opengl.dll 没解压出来或被杀软删了",
+            "重装组件（重新解压 natives）；Windows 上检查杀软隔离区",
+            Some("reinstall natives"),
+        ),
+        finding(
+            "graphics.gl_operation_failure",
+            70,
+            "某个 mod/光影包做了非法的 OpenGL 操作（GL_INVALID_OPERATION）",
+            "换掉最近装的光影/资源包，或把资源包分辨率降下来",
+            Some("change_graphics.renderer = OpenGL 兼容模式"),
+        ),
+        finding(
+            "integrity.no_class_def_found",
+            60,
+            "NoClassDefFoundError：缺少类文件（库没下全 / jar 被解压 / mod 不配套）",
+            "先检查 libraries 是否完整，再排查 mods 里的解压目录",
+            Some("reinstall libraries"),
+        ),
+    ]
+}
+
+fn finding(rule: &str, confidence: u8, title: &str, hint: &str, action: Option<&str>) -> Finding {
+    Finding {
+        rule: rule.to_owned(),
+        confidence_band: Confidence::of(confidence),
+        title: title.to_owned(),
+        hint: hint.to_owned(),
+        confidence,
+        action: action.map(str::to_owned),
+    }
+}
diff --git a/crates/app-iced/src/pages/logs/diagnostic.rs b/crates/app-iced/src/pages/logs/diagnostic.rs
new file mode 100644
index 0000000..ba3143c
--- /dev/null
+++ b/crates/app-iced/src/pages/logs/diagnostic.rs
@@ -0,0 +1,218 @@
+//! 诊断结果区：**按置信度档分组**的结论卡片 + 可直接粘进 issue 的一行摘要。
+//!
+//! ## 一条结论要能看出什么（tower 的三问）
+//!
+//! | 问题 | 落点 | 数据来源 |
+//! |---|---|---|
+//! | 哪条规则命中 | 规则 id（等宽、`LabelMedium`） | `Finding::rule` |
+//! | 置信度（不是严重度） | 分组标题 + 分组顺序（`HIGH` → `MEDIUM` → `LOW`） | `Finding::confidence_band` |
+//! | 建议动作 | `Suggested fix` 一行（规则表的 `fix_action`，技术标识原样） | `Finding::action` |
+//!
+//! ## 用户真的要拿去用的两样东西
+//!
+//! 1. **结论原文**（`title` / `hint`）：规则表 `rules.d/*.yaml` 写的 `cause.summary` / `detail`。
+//!    它是**数据**（诊断结论），页面不翻译也不改写——改写会让「规则命中」与「用户读到的」
+//!    变成两套说法。界面文案（分组名 / 标签 / 按钮）仍然全部走 i18n key。
+//! 2. **一行摘要**（[`Logs::summary`]）：等宽显示 + 「Copy summary」按钮；按钮把字符串塞进
+//!    剪贴板（`Message::CopySummary` → `iced::app/update.rs` → `iced::clipboard::write`）。
+//!    崩溃日志换 issue 时粘这一行就够：实例 / 时间 / 结局 / 行数 / 命中的规则与置信度都在里面。
+
+use iced::widget::text::{LineHeight, Wrapping};
+use iced::widget::{column, row, text};
+use iced::{Alignment, Color, Element, Length, Pixels};
+
+use unlucky_design::color::Role;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::{TypeRole, TypeStyle};
+use unlucky_i18n::catalog::{Catalog, Key};
+use unlucky_i18n::Lang;
+
+use crate::app::components::buttons::{self, Button};
+use crate::theme::Ui;
+
+use super::super::frame;
+use super::super::layout::wrap;
+use super::super::Message;
+use super::lines::{mono, mono_owned};
+use super::model::{Confidence, Finding, Logs, GROUPS};
+use super::panel;
+
+/// 诊断卡片（只在有结论时画）。高度由调用方定（见 [`panel`]）。
+///
+/// 结构 = 头（`DIAGNOSIS` + 条数）/ **可滚动的分组区** / **固定的摘要页脚**。
+/// 摘要钉在页脚而不是跟着滚（视觉复审 P2-3）：三条结论就足以把它顶到折叠线以下，
+/// 而「Copy」复制的是用户必须看得见的东西——看不见的字符串不该能被复制。
+pub fn card<'a>(ui: &'a Ui, logs: &'a Logs, lang: Lang, height: Length) -> Element<'a, Message> {
+    let catalog = Catalog::of(lang);
+
+    let mut group = column![].spacing(ui.space(Space::X2)).width(Length::Fill);
+
+    for band in GROUPS {
+        let findings = logs.group(band);
+        if findings.is_empty() {
+            continue;
+        }
+
+        group = group.push(frame::divider(ui));
+        group = group.push(title_row(ui, catalog.text(key_of(band)), findings.len()));
+        for finding in findings {
+            group = group.push(finding_block(ui, &catalog, finding));
+        }
+    }
+
+    panel::card(
+        ui,
+        height,
+        column![
+            title_row(
+                ui,
+                catalog.text(Key::LogsDiagnosisTitle),
+                logs.findings.len(),
+            ),
+            panel::scroll(ui, group),
+            frame::divider(ui),
+            summary_block(ui, &catalog, logs),
+        ]
+        .spacing(ui.space(Space::X2))
+        .width(Length::Fill),
+    )
+}
+
+/// 标题行：左边标签（大写字距靠令牌档），右边条数。
+fn title_row<'a>(ui: &'a Ui, label: &'a str, count: usize) -> Element<'a, Message> {
+    row![
+        frame::text_role(
+            ui,
+            TypeRole::LabelMedium,
+            true,
+            label,
+            ui.color(Role::OnSurfaceVariant),
+        ),
+        iced::widget::Space::new().width(Length::Fill),
+        frame::text_role_owned(
+            ui,
+            TypeRole::LabelMedium,
+            false,
+            count.to_string(),
+            ui.color(Role::OnSurfaceVariant),
+        ),
+    ]
+    .width(Length::Fill)
+    .align_y(Alignment::Center)
+    .into()
+}
+
+/// 一条结论：规则 id / 结论 / 说明 / 建议动作 / 置信度。
+fn finding_block<'a>(ui: &'a Ui, catalog: &Catalog, finding: &'a Finding) -> Element<'a, Message> {
+    let mut block = column![
+        mono(ui, &finding.rule, ui.color(Role::OnSurfaceVariant)),
+        wrapped(
+            ui,
+            TypeRole::BodyMedium,
+            &finding.title,
+            ui.color(Role::OnSurface)
+        ),
+        wrapped(
+            ui,
+            TypeRole::BodySmall,
+            &finding.hint,
+            ui.color(Role::OnSurfaceVariant)
+        ),
+    ]
+    .spacing(ui.space(Space::X1))
+    .width(Length::Fill);
+
+    if let Some(action) = &finding.action {
+        block = block.push(
+            column![
+                frame::text_role(
+                    ui,
+                    TypeRole::LabelMedium,
+                    false,
+                    catalog.text(Key::LogsSuggestedFix),
+                    ui.color(Role::OnSurfaceVariant),
+                ),
+                mono(ui, action, ui.color(Role::OnSurface)),
+            ]
+            .spacing(0.0)
+            .width(Length::Fill),
+        );
+    }
+
+    block = block.push(frame::text_role_owned(
+        ui,
+        TypeRole::LabelMedium,
+        false,
+        catalog.render(
+            Key::LogsConfidence,
+            &[("percent", &finding.confidence.to_string())],
+        ),
+        ui.color(Role::OnSurfaceVariant),
+    ));
+
+    block.into()
+}
+
+/// **固定的摘要页脚**：标签 +「Copy summary」+ 等宽摘要（可整段带走）。
+///
+/// 页脚不滚动（见 [`card`] 的文档）：按钮紧邻它要复制的那段文字，用户复制的一定是看得见的串。
+fn summary_block<'a>(ui: &'a Ui, catalog: &Catalog, logs: &Logs) -> Element<'a, Message> {
+    column![
+        row![
+            frame::text_role(
+                ui,
+                TypeRole::LabelMedium,
+                false,
+                catalog.text(Key::LogsSummaryLabel),
+                ui.color(Role::OnSurfaceVariant),
+            ),
+            iced::widget::Space::new().width(Length::Fill),
+            buttons::text(
+                ui,
+                Button::new(
+                    catalog.text(Key::LogsCopySummary),
+                    Message::CopySummary(logs.summary()),
+                ),
+            ),
+        ]
+        .width(Length::Fill)
+        .align_y(Alignment::Center),
+        mono_owned(
+            ui,
+            wrap::breakable(&logs.summary()),
+            ui.color(Role::OnSurface)
+        )
+        .width(Length::Fill)
+        .wrapping(Wrapping::WordOrGlyph),
+    ]
+    .spacing(ui.space(Space::X1))
+    .width(Length::Fill)
+    .into()
+}
+
+/// 置信度档 → 分组标题的 key。
+///
+/// 刻意**不叫严重度**（`CRITICAL` / `WARNING` / `NOTICE`）：DTO 没带 core 的 severity，
+/// 拿置信度去凑严重度会让 64 条规则里的 12 条进错组（`mod.mixin_failure` critical/0.70 沉底、
+/// `other.debug_crash` info/0.95 冒顶）。标题只说它对「这条结论有多确定」。
+fn key_of(band: Confidence) -> Key {
+    match band {
+        Confidence::High => Key::LogsConfidenceHigh,
+        Confidence::Medium => Key::LogsConfidenceMedium,
+        Confidence::Low => Key::LogsConfidenceLow,
+    }
+}
+
+/// 令牌排版档 + **按词或字形折行**（长堆栈里的点分标识符没有空格，只按词会溢出）。
+fn wrapped<'a>(ui: &'a Ui, role: TypeRole, content: &'a str, color: Color) -> Element<'a, Message> {
+    let style: TypeStyle = ui.style(role);
+
+    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(Wrapping::WordOrGlyph)
+        .into()
+}
diff --git a/crates/app-iced/src/pages/logs/lines.rs b/crates/app-iced/src/pages/logs/lines.rs
new file mode 100644
index 0000000..2e10e8b
--- /dev/null
+++ b/crates/app-iced/src/pages/logs/lines.rs
@@ -0,0 +1,221 @@
+//! 日志行列表：**等宽 + 折行 + 独立滚动**。
+//!
+//! ## 为什么折行而不是横向滚动（tower 要求二选一，这里选折行）
+//!
+//! 一行崩溃堆栈动辄 200+ 字符（样例里最长的一行 214 字符）。M102 起卡片吃满页宽
+//! （1180 窗宽 → 卡内约 1004px），但 214 字符 × 等宽 12px ≈ 1412px 仍要折一次。两条路：
+//!
+//! | 方案 | 代价 |
+//! |---|---|
+//! | 横向滚动 | 一条日志要横甩两屏；外壳已经是竖向滚动，横竖两向嵌套后滚轮归属会打架 |
+//! | **折行（本页选）** | 一条日志可能占 2~3 行，行号/等级栏必须能标明「这是同一条」 |
+//!
+//! 选折行的决定性理由：**折行让等宽族只承担「视觉密度」，不承担「列对齐」**。等宽栈在
+//! Windows 上是 `Cascadia Mono` / `Consolas`，它们没有 CJK 字形——中文日志要靠 cosmic-text
+//! 逐字回退到系统 CJK 族（本机实测回退到 `Microsoft YaHei UI`），回退字形的 advance 不是 1ch。
+//! 横向滚动方案里「第 40 列对齐」是有意义的（堆栈缩进、`at a.b.C(File.java:12)` 的括号列），
+//! 一旦 CJK 回退把列宽带偏，对齐就废了；折行版面不承诺任何列对齐，回退只影响同一行内的观感。
+//! ## 悬挂缩进（M95 r2 落地，视觉复审 P2-1）
+//!
+//! r1 的 `entry()` 只有 `row![等级条, 单个 Text]`：折行的续行回到文本自己的左边距，
+//! 于是 `at com.mojang…(GLX.java:64)` 被拆成「`at` 独占一行 + 帧名一行」，和「下一条日志」
+//! 视觉上无法区分（一屏白花 ~5 行）。**现在的落地方式**是把一行拆成**前缀 + 正文两个文本控件**：
+//!
+//! ```text
+//! │ [19:40:14] [Render thread/ERROR] 显卡驱动不支持 OpenGL 3.2，初始化窗口失败
+//! │        ↑ 前缀（第一个空格及其之前，含空格）   ↑ 正文从它右边开始，带着 Fill 宽度自己折行
+//! │ java.lang.IllegalStateException: GLFW error before init: [0x10008] Failed to create window…
+//! │ ↑ 无前缀（第一个「词」超过 20 字符）⇒ 整行一个文本块
+//! ```
+//!
+//! 为什么不是「NBSP 绑定前缀 + 单个 Text」：NBSP 只阻止断行，**改不了续行的起点**——续行依旧
+//! 回到文本左边距，`at` 还是独占一行（除非整行按字形硬断，那会把时间戳也断掉）。两段布局是
+//! iced 里唯一能同时做到「`at` 与帧名同行」+「续行比行首缩进」的写法。
+//!
+//! 代价与边界：续行缩进量 = **该行前缀宽度**（时间戳行 ≈ 10 字符、栈帧 `at` 行 ≈ 3 字符），
+//! 所以不同行的续行缩进不一样——这是悬挂缩进的正常形态（按行首标签缩进），不是 bug。
+//!
+//! ## 软断点（M102，视觉复审 ③）
+//!
+//! 没有空格的长串（`graphics.gl_operation_failure:medium(70)`）在原版里只能按字形硬断，
+//! 图里出现 `gl_o` / `peration_failure`。现在正文先过
+//! [`super::super::layout::wrap::breakable`]：在 `.` `_` `:` `/` `\` 后插零宽空格，折行落回
+//! 词边界；悬挂缩进不受影响（前缀仍是独立文本控件），`Line::text` 仍是原文。
+//!
+//! ## 贴底（M95 r2，视觉复审 P2-4）
+//!
+//! 崩溃排查看的是**最后几行**，所以行列表用 `panel::scroll_tail`（`Anchor::End`）：偏移按
+//! 「距底多远」记，内容增长时视图保持距底同一位置 ⇒ 天然跟随尾部。用户上滚后的行为与
+//! 「是否冻结」的边界写在 [`panel::scroll_tail`] 的文档里（结论：**没有**冻结，需要 app 层
+//! 回灌滚动状态才做得到）。
+//!
+//! ## 等宽族的实际落点
+//!
+//! `ui.families().mono` 是启动时用系统字体库核对过的族名（[`crate::fonts`] 求值，启动日志里
+//! 有一行 `mono=…`），本页只通过 [`mono_style`] 用它，不写死族名。字号/行高走
+//! `TypeRole::BodySmall`（12/16），与报告里的数值表对得上（见 `logs/tests.rs`）。
+
+use iced::widget::text::LineHeight;
+use iced::widget::{column, container, row, space};
+use iced::{Alignment, Background, Border, Color, Element, Length, Padding, Pixels};
+
+use unlucky_design::color::Role;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::{FontFamily, TypeRole, TypeStyle};
+use unlucky_i18n::catalog::{Catalog, Key};
+use unlucky_i18n::Lang;
+
+use crate::theme::Ui;
+
+use super::super::frame;
+use super::super::layout::wrap;
+use super::super::Message;
+use super::model::{Level, Line, Logs};
+use super::panel;
+
+/// 前缀上限（字符）：超过就不拆（见 [`split_prefix`]）。
+const PREFIX_MAX_CHARS: usize = 20;
+
+/// 等级条宽度（2px：够看见，又不抢日志正文的起始列）。
+const BAR_WIDTH: f32 = 2.0;
+
+/// 日志卡片：标题行（`OUTPUT` + 行数）+ 独立滚动的行列表。高度由调用方定（见 [`panel`]）。
+pub fn card<'a>(ui: &'a Ui, logs: &'a Logs, lang: Lang, height: Length) -> Element<'a, Message> {
+    let catalog = Catalog::of(lang);
+
+    let head = row![
+        container(frame::text_role(
+            ui,
+            TypeRole::LabelMedium,
+            false,
+            catalog.text(Key::LogsOutputTitle),
+            ui.color(Role::OnSurfaceVariant),
+        ))
+        .width(Length::Fill)
+        .align_y(Alignment::Center),
+        frame::text_role_owned(
+            ui,
+            TypeRole::LabelMedium,
+            false,
+            logs.lines.len().to_string(),
+            ui.color(Role::OnSurfaceVariant),
+        ),
+    ]
+    .width(Length::Fill)
+    .align_y(Alignment::Center)
+    .padding(Padding::default().bottom(ui.space(Space::X2)));
+
+    let rows = column(
+        logs.lines
+            .iter()
+            .map(|line| entry(ui, line))
+            .collect::<Vec<_>>(),
+    )
+    .spacing(ui.space(Space::X1))
+    .width(Length::Fill);
+
+    panel::card(ui, height, column![head, panel::scroll_tail(ui, rows)])
+}
+
+/// 一行：等级条（跨行）+ **前缀 / 正文两段**（正文折行后落在前缀右边 = 悬挂缩进）。
+fn entry<'a>(ui: &'a Ui, line: &'a Line) -> Element<'a, Message> {
+    let color = color_of(ui, line.level);
+    let (prefix, body) = split_prefix(&line.text);
+
+    let bar = container(space::horizontal())
+        .width(BAR_WIDTH)
+        .height(Length::Fill)
+        .style(move |_theme| container::Style {
+            background: Some(Background::Color(color)),
+            border: Border {
+                radius: ui.radius(ShapeScale::Full, BAR_WIDTH),
+                ..Border::default()
+            },
+            ..container::Style::default()
+        });
+
+    // 「前缀 + 正文」拆两个文本控件是悬挂缩进的**唯一**落地方式（iced 的单个 `Text` 折行后
+    // 续行一定回到自己的左边距，没有 `text-indent` 之类的排版钩子）：
+    // 前缀占第一行开头，正文从它右边开始、带着 `Fill` 宽度自己折行 ⇒ 续行自然落在
+    // `前缀宽度` 之后，与下一条日志的起点（x = 等级条右边）分开。
+    //
+    // M102：正文先过 `wrap::breakable`——`graphics.gl_operation_failure:medium(70)` 这种没有空格的
+    // 长串在原版里只能按字形硬断（`gl_o` / `peration`），补上软断点后才断在 `.` `_` `:` 后面。
+    let text = row![
+        mono(ui, prefix, color),
+        mono_owned(ui, wrap::breakable(body), color)
+            .width(Length::Fill)
+            .wrapping(iced::widget::text::Wrapping::WordOrGlyph),
+    ]
+    .spacing(0.0)
+    .width(Length::Fill)
+    .align_y(Alignment::Start);
+
+    row![bar, text]
+        .spacing(ui.space(Space::X2))
+        .width(Length::Fill)
+        .align_y(Alignment::Start)
+        .into()
+}
+
+/// 拆「前缀」与「正文」：前缀 = 第一个空格及其之前的部分（**含**那个空格，所以接缝处不用再加
+/// 间距），正文 = 其余。
+///
+/// 拆的条件：空格在 1..=[`PREFIX_MAX_CHARS`] 个字符之内。超长（一整行没有空格、或第一个
+/// 「词」本身就比 20 字符长，例如以 URL 开头的行）就**不拆**，整行当一个文本块折行——否则
+/// 前缀会把正文挤成一条 1 字符宽的缝。
+pub(super) fn split_prefix(text: &str) -> (&str, &str) {
+    match text.find(' ') {
+        Some(index) if index > 0 && index < PREFIX_MAX_CHARS => text.split_at(index + 1),
+        _ => ("", text),
+    }
+}
+
+/// 等级 → 颜色（错误用 `Error`，警告用 `Tertiary`：与主题的 warning 槽位同源）。
+fn color_of(ui: &Ui, level: Level) -> Color {
+    match level {
+        Level::Error => ui.color(Role::Error),
+        Level::Warn => ui.color(Role::Tertiary),
+        Level::Info => ui.color(Role::OnSurface),
+        Level::Debug => ui.color(Role::OnSurfaceVariant),
+    }
+}
+
+/// 等宽排版档：**同一个 `BodySmall` 档，只把字体族换成 mono 栈**。
+///
+/// 不新造字号（12/16 与辅助说明同档），所以「等宽」这件事只改字体族这一个维度，
+/// 行高仍是令牌值——CJK 回退只换字形，行高不会跳（这也是折行方案的前提之一）。
+#[must_use]
+pub fn mono_style(ui: &Ui) -> TypeStyle {
+    TypeStyle {
+        family: FontFamily::Mono,
+        ..ui.style(TypeRole::BodySmall)
+    }
+}
+
+/// 等宽文本（字号 / 行高 / 字重 / 族全来自 [`mono_style`]）。
+#[must_use]
+pub fn mono<'a>(ui: &Ui, content: &'a str, color: Color) -> iced::widget::Text<'a> {
+    mono_styled(ui, content, color)
+}
+
+/// 同 [`mono`]，但文案是**拥有的**字符串（摘要行这类运行时拼出来的短串）。
+#[must_use]
+pub fn mono_owned<'a>(ui: &Ui, content: String, color: Color) -> iced::widget::Text<'a> {
+    mono_styled(ui, content, color)
+}
+
+fn mono_styled<'a>(
+    ui: &Ui,
+    content: impl iced::widget::text::IntoFragment<'a>,
+    color: Color,
+) -> iced::widget::Text<'a> {
+    let style = mono_style(ui);
+
+    iced::widget::text(content)
+        .size(style.size_px)
+        .line_height(LineHeight::Absolute(Pixels(style.line_height_px)))
+        .font(ui.font_of(style))
+        .color(color)
+}
diff --git a/crates/app-iced/src/pages/logs/model.rs b/crates/app-iced/src/pages/logs/model.rs
new file mode 100644
index 0000000..49d8762
--- /dev/null
+++ b/crates/app-iced/src/pages/logs/model.rs
@@ -0,0 +1,299 @@
+//! 日志页的视图模型：**纯展示字段**（沿用 `pages::model` 的分层——不含 iced 类型，也不认识 presenter）。
+//!
+//! ## 为什么单独一层
+//!
+//! 渲染函数只吃 [`Logs`]，于是同一棵树能被三份数据喂：
+//!
+//! | 数据源 | 谁造 | 用途 |
+//! |---|---|---|
+//! | presenter 快照（`AppState`） | `app/view.rs::logs_model` | 产品运行时 |
+//! | [`super::demo`] 的内嵌崩溃日志片段 | `pages::demo_model` | `pages_demo --screen=logs` 出图 |
+//! | [`Logs::default`] | 空态 | 真的没有输出（未接线时也是这个兜底） |
+//!
+//! 页面**不读盘**：日志文本只有两条来路——presenter 快照里的 `LogLine`，或 `demo` 里
+//! `include_str!` 内嵌的样例。日志文件的路径从头到尾没进过页面。
+//!
+//! ## 缺口（M95 登记，已报 finding）
+//!
+//! presenter 的 `dto::Diagnosis` 只有 `rule` / `title` / `hint` / `confidence` / `fix`：
+//!
+//! 1. **core 的 `Severity`（info / warning / critical）在半路丢了**——`core::diagnose::rules`
+//!    里每条规则都带它，`presenter::dto::Diagnosis` 没有。拿严重度当分组名就只能拿置信度硬凑，
+//!    实测 **64 条规则里 12 条会被凑错档、两个方向都有**（`mod.mixin_failure` critical/0.70 沉到
+//!    第二档、`other.debug_crash` info/0.95 冒到第一档）。
+//!
+//!    所以 M95 r4 起页面**不再借 core 的词汇**：分组改用**置信度档**
+//!    [`Confidence::High`] / [`Confidence::Medium`] / [`Confidence::Low`]，标题直接写「高/中/低
+//!    置信度」——它描述的是「规则引擎有多确定」，不是「这毛病有多严重」。DTO 补上 `severity`
+//!    之后这里应该换回真严重度（finding 已记给 presenter）。
+//! 2. `title` / `hint` 只有中文单语，而且规则表里其实已经有结构化出口
+//!    （`rules.d/*.yaml` 的 `cause.key: diagnose.cause.…`）。DTO 没带 `key`，页面就把规则原文
+//!    当**数据**画出来，页面的界面文案（标题 / 按钮 / 分组名 / 空态）仍然全部走 i18n key。
+
+use unlucky_i18n::catalog::{Catalog, Key};
+use unlucky_i18n::Lang;
+
+/// 一行日志的等级（presenter `LogLevel` 的展示投影）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Level {
+    /// 调试噪音。
+    Debug,
+    /// 正常流水。
+    Info,
+    /// 可疑。
+    Warn,
+    /// 错误行（崩溃现场）。
+    Error,
+}
+
+impl Level {
+    /// 稳定 slug（摘要行与测试用；不是文案）。
+    #[must_use]
+    pub const fn slug(self) -> &'static str {
+        match self {
+            Self::Debug => "debug",
+            Self::Info => "info",
+            Self::Warn => "warn",
+            Self::Error => "error",
+        }
+    }
+}
+
+/// 诊断结论的**置信度档**（规则引擎有多确定，不是「这毛病有多严重」）。
+///
+/// 为什么不是 `Severity`：`presenter::dto::Diagnosis` 没带 core 规则表的 `severity`，
+/// 页面自己按置信度折算严重度会凑错档（64 条规则里 12 条，两个方向都有）。宁可**如实**
+/// 说「这条结论置信度多高」，也不要编一个「严重度」（视觉复审 r3 的 P2-2 + 塔裁决）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub enum Confidence {
+    /// 低：规则只是「有点像」。
+    Low,
+    /// 中：可疑。
+    Medium,
+    /// 高：基本可以确定。
+    High,
+}
+
+/// 分区顺序（**高置信度在上**：崩溃日志换 issue 时第一段就是最该看的）。
+pub const GROUPS: [Confidence; 3] = [Confidence::High, Confidence::Medium, Confidence::Low];
+
+impl Confidence {
+    /// 稳定 slug（摘要行用；不是文案——分组标题走 i18n key）。
+    #[must_use]
+    pub const fn slug(self) -> &'static str {
+        match self {
+            Self::Low => "low",
+            Self::Medium => "medium",
+            Self::High => "high",
+        }
+    }
+
+    /// 0~100 置信度 → 档位（阈值 `≥80` 高 / `≥50` 中 / 其余低）。
+    ///
+    /// 阈值是**档位定义**，不是从严重度反推的代理：标题与文案都说的是「置信度」。
+    #[must_use]
+    pub const fn of(confidence: u8) -> Self {
+        if confidence >= 80 {
+            Self::High
+        } else if confidence >= 50 {
+            Self::Medium
+        } else {
+            Self::Low
+        }
+    }
+}
+
+/// 一行日志。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Line {
+    /// 原始文本（**不截断**：折行是渲染的事，数据要留全，否则用户永远拿不回堆栈）。
+    pub text: String,
+    /// 等级。
+    pub level: Level,
+}
+
+/// 一条诊断结论。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Finding {
+    /// 命中的规则 id（`graphics.opengl_not_supported`）：技术标识，原样显示。
+    pub rule: String,
+    /// 置信度档（DTO 没有 core 的 severity，见 [`Confidence`]）。
+    pub confidence_band: Confidence,
+    /// 结论标题（规则表的 `cause.summary`，**数据不是文案**）。
+    pub title: String,
+    /// 建议说明（规则表的 `cause.detail`）。
+    pub hint: String,
+    /// 0~100 置信度。
+    pub confidence: u8,
+    /// 建议动作（规则表的 `fix_action`，技术标识 / 设置项名）。
+    pub action: Option<String>,
+}
+
+/// 一次运行的结局（`presenter::dto::LogOutcome` 的展示投影；文案走 `LaunchOutcome*` key）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Outcome {
+    /// 正常退出。
+    Ok,
+    /// 崩溃。
+    Crashed,
+    /// exit 0 但游戏没起来。
+    SilentFail,
+}
+
+impl Outcome {
+    /// 稳定 slug（摘要行用）。
+    #[must_use]
+    pub const fn slug(self) -> &'static str {
+        match self {
+            Self::Ok => "ok",
+            Self::Crashed => "crashed",
+            Self::SilentFail => "silent-fail",
+        }
+    }
+}
+
+/// 日志页要画的东西。
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct Logs {
+    /// 会话所属实例名（`None` = 不知道，页头副标题退成通用文案）。
+    pub instance: Option<String>,
+    /// 会话时间（展示用短串 `10-29 18:40`，presenter 已经格式化好）。
+    pub when: Option<String>,
+    /// 结局。
+    pub outcome: Option<Outcome>,
+    /// 页头副标题（`实例 · 时间 · 结局`）：**构造时**拼好（见 [`Logs::with_status`]），
+    /// 页面只负责显示——i18n 的「一句话 = 一个 key」不许在渲染里拼句子。
+    pub status: Option<String>,
+    /// 有没有正在跑的会话（`live_session` 非空）。
+    ///
+    /// 为什么需要它：session 索引只在会话**结束**时追加（`host::logs::sessions`），所以运行中的
+    /// 那一场根本不在 `log_sessions` 里 ⇒ 拿不到实例名与结局。r3 之前这里直接退回
+    /// 「当前没有运行中的实例」，于是**每次实时运行页头都在说反话**（视觉复审 r3 的 P2-3）。
+    pub live: bool,
+    /// 日志行（顺序 = 文件顺序）。
+    pub lines: Vec<Line>,
+    /// 诊断结论（顺序 = presenter 给的顺序，页面不重排）。
+    pub findings: Vec<Finding>,
+}
+
+impl Logs {
+    /// 补上页头副标题（M95 r2，视觉复审 P2-2；r4 补「运行中」这一档，P2-3）。
+    ///
+    /// 为什么在这里做而不是在页面里：`Header::subtitle` 要 `&'a str`，而拼出来的是 `String`；
+    /// 让模型持有它，页面就永远只借不拼。
+    ///
+    /// 三级回退：**有实例 + 结局** → `实例 · 时间 · 结局`；**正在跑但还没有结局**（session 索引
+    /// 里没有它） → 中性的「正在运行」；都没有 → `None`（页面退回 [`Key::LogsSubtitleIdle`]）。
+    #[must_use]
+    pub fn with_status(mut self, lang: Lang) -> Self {
+        let catalog = Catalog::of(lang);
+
+        self.status = status_line(
+            self.instance.as_deref(),
+            self.when.as_deref(),
+            self.outcome,
+            lang,
+        )
+        .or_else(|| {
+            self.live
+                .then(|| catalog.text(Key::LogsSubtitleLive).to_owned())
+        });
+
+        self
+    }
+
+    /// 没有任何可显示的东西（空态判据：行与诊断都空）。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.lines.is_empty() && self.findings.is_empty()
+    }
+
+    /// 某一置信度档下的结论（顺序不变；空组返回空 `Vec`）。
+    #[must_use]
+    pub fn group(&self, band: Confidence) -> Vec<&Finding> {
+        self.findings
+            .iter()
+            .filter(|finding| finding.confidence_band == band)
+            .collect()
+    }
+
+    /// **可复制的一行摘要**（崩溃日志换 issue 时直接粘）。
+    ///
+    /// 格式是刻意的：ASCII 骨架 + 稳定字段序 + ` | ` 分隔，人读与机器读都行；
+    /// 不含任何界面文案（所以不随语言变），只带数据与控制面的技术标识。
+    ///
+    /// ```text
+    /// ULL-LOGS v1 | instance=开发测试 | when=10-29 18:40 | outcome=crashed | lines=6 \
+    ///   | findings=graphics.opengl_not_supported:critical(85)
+    /// ```
+    #[must_use]
+    pub fn summary(&self) -> String {
+        let mut parts = vec![SUMMARY_HEADER.to_owned()];
+
+        if let Some(instance) = &self.instance {
+            parts.push(format!("instance={instance}"));
+        }
+        if let Some(when) = &self.when {
+            parts.push(format!("when={when}"));
+        }
+        if let Some(outcome) = self.outcome {
+            parts.push(format!("outcome={}", outcome.slug()));
+        }
+        parts.push(format!("lines={}", self.lines.len()));
+
+        if !self.findings.is_empty() {
+            let hits: Vec<String> = self
+                .findings
+                .iter()
+                .map(|finding| {
+                    format!(
+                        "{}:{}({})",
+                        finding.rule,
+                        finding.confidence_band.slug(),
+                        finding.confidence
+                    )
+                })
+                .collect();
+            parts.push(format!("findings={}", hits.join(",")));
+        }
+
+        parts.join(" | ")
+    }
+}
+
+/// 摘要行的版本头（改了格式就换代，别让旧 issue 里的摘要含义漂移）。
+pub const SUMMARY_HEADER: &str = "ULL-LOGS v1";
+
+/// 页头副标题：`{instance} · {when} · {outcome}`。
+///
+/// 结局文案走 [`Key::LaunchOutcomeNormal`] / [`Key::LaunchOutcomeCrash`] /
+/// [`Key::LaunchOutcomeSilent`] —— 就是 `unlucky_i18n::bridge` 文档里写了很久的那条
+/// 「`LogOutcome` 三态 → 三 key 结构化出口」，M95 r2 之前它们在 UI 侧**零调用点**（视觉复审 P2-2）。
+///
+/// 没有实例名或结局时返回 `None`（不知道是哪一场就别编），页头退回静态副标题。
+#[must_use]
+pub fn status_line(
+    instance: Option<&str>,
+    when: Option<&str>,
+    outcome: Option<Outcome>,
+    lang: Lang,
+) -> Option<String> {
+    let instance = instance?;
+    let outcome = outcome?;
+    let catalog = Catalog::of(lang);
+
+    let outcome_key = match outcome {
+        Outcome::Ok => Key::LaunchOutcomeNormal,
+        Outcome::Crashed => Key::LaunchOutcomeCrash,
+        Outcome::SilentFail => Key::LaunchOutcomeSilent,
+    };
+
+    Some(catalog.render(
+        Key::LogsStatus,
+        &[
+            ("instance", instance),
+            ("when", when.unwrap_or("—")),
+            ("outcome", catalog.text(outcome_key)),
+        ],
+    ))
+}
diff --git a/crates/app-iced/src/pages/logs/panel.rs b/crates/app-iced/src/pages/logs/panel.rs
new file mode 100644
index 0000000..64c401d
--- /dev/null
+++ b/crates/app-iced/src/pages/logs/panel.rs
@@ -0,0 +1,89 @@
+//! 两块的共用外壳：**定高的卡片 + 内部独立滚动**。
+//!
+//! ## 为什么必须定高（M95 r1 的实拍 bug）
+//!
+//! 第一版把诊断卡按内容自然高度画、日志卡吃剩余高度。三条结论在 424×540 的正文里就要
+//! ~500px，结果：诊断卡被裁掉尾部（一行摘要整块消失）、日志卡拿到 **0** 高度（整块不见）。
+//! 截图见报告里的「r1 崩了」。
+//!
+//! 所以两块都**由调用方给定高**（`FillPortion`），各自内部滚动：
+//!
+//! | 块 | 高度 | 为什么 |
+//! |---|---|---|
+//! | 诊断 | `FillPortion(4)` | 崩溃时先读结论；份额要够 177px 的滚动视口，才放得下**一条完整结论**（含建议动作与置信度） |
+//! | 日志 | `FillPortion(2)` | 日志是长流水，滚就是了 |
+//!
+//! 两者都是**兄弟**滚动区（不是嵌套）：滚轮归属清楚，不存在「滚动条套滚动条」。
+
+use iced::widget::{container, scrollable};
+use iced::{Background, Element, Length};
+
+use unlucky_design::component_map::Component;
+use unlucky_design::elevation::MaterialLayer;
+
+use crate::theme::Ui;
+
+use super::super::frame;
+use super::super::Message;
+
+/// 定高卡片（`Card` 材质层 + `OutlinedCard` 形状与 **1px 描边**，与 `frame::card` 同一套令牌：
+/// 实例页 / 下载页的卡都带这条描边，日志页的两张主卡不能例外）。
+pub fn card<'a>(
+    ui: &'a Ui,
+    height: Length,
+    content: impl Into<Element<'a, Message>>,
+) -> Element<'a, Message> {
+    let shape = Component::OutlinedCard.spec().shape;
+
+    container(content)
+        .width(Length::Fill)
+        .height(height)
+        .padding(ui.metrics().card_padding)
+        .style(move |_theme| container::Style {
+            background: Some(Background::Color(ui.layer(MaterialLayer::Card))),
+            border: ui.outlined(shape),
+            ..container::Style::default()
+        })
+        .into()
+}
+
+/// 卡片内的竖向滚动区（贴顶：诊断卡从头读）。
+pub fn scroll<'a>(ui: &'a Ui, content: impl Into<Element<'a, Message>>) -> Element<'a, Message> {
+    scroller(ui, content, false)
+}
+
+/// 卡片内的竖向滚动区（**贴底**：日志卡看最后几行）。
+///
+/// `anchor_bottom` = `Anchor::End`：滚动偏移按「距底多远」记，所以**内容增长时视图保持在
+/// 距底同一位置 ⇒ 天然跟随尾部**。用户上滚后偏移 = 距底 N 像素，新内容到达时仍按「距底 N」
+/// 呈现（视图跟着内容下移），也就是说**这里没有「上滚即冻结」**——那需要页面自己持有滚动
+/// 状态 + `on_scroll` 消息 + app 层回灌，属于另一件事（已登记在报告里）。
+pub fn scroll_tail<'a>(
+    ui: &'a Ui,
+    content: impl Into<Element<'a, Message>>,
+) -> Element<'a, Message> {
+    scroller(ui, content, true)
+}
+
+fn scroller<'a>(
+    ui: &'a Ui,
+    content: impl Into<Element<'a, Message>>,
+    tail: bool,
+) -> Element<'a, Message> {
+    let view = scrollable(content)
+        .direction(scrollable::Direction::Vertical(
+            scrollable::Scrollbar::new()
+                .width(frame::SCROLLBAR_WIDTH)
+                .scroller_width(frame::SCROLLBAR_WIDTH)
+                .margin(frame::SCROLLBAR_MARGIN),
+        ))
+        .height(Length::Fill)
+        .width(Length::Fill)
+        .style(frame::scroll_style(ui));
+
+    if tail {
+        view.anchor_bottom().into()
+    } else {
+        view.into()
+    }
+}
diff --git a/crates/app-iced/src/pages/logs/sample_crash.log b/crates/app-iced/src/pages/logs/sample_crash.log
new file mode 100644
index 0000000..bc2671c
--- /dev/null
+++ b/crates/app-iced/src/pages/logs/sample_crash.log
@@ -0,0 +1,23 @@
+# M95 演示数据：一段真实崩溃日志的片段（页面用 include_str! 编译期内嵌，运行时不读盘）。
+#
+# 每行格式：`<等级> <原文>`，等级 = D(debug) / I(info) / W(warn) / E(error)；`#` 开头是注释。
+#
+# 这份样例是故意挑的（tower 要求的两条真风险都压在这里）：
+#   1. 中文 + 堆栈混排 —— mono 族（Windows 上是 Consolas / Cascadia Mono）没有 CJK 字形，
+#      中文要靠 cosmic-text 逐字回退到系统 CJK 族，字宽与 Latin 1ch 不等；页面选的是折行，
+#      所以「列对齐」不参与版面，回退只影响同一行内的视觉密度；
+#   2. 超长行 —— 第 9/10/11 行都在 200 字符以上（真实 Java 堆栈的长度），正文列上限 424px，
+#      折行策略见 `logs.rs` 模块文档。
+I [19:40:12] [main/INFO] 正在启动 1.20.4，实例「开发测试」，加载器 NeoForge 21.1.72
+I [19:40:12] [main/INFO] Java 21.0.5 (Microsoft build 21.0.5+11-LTS), 内存 4096 MiB, JVM 参数 -Xmx4G -XX:+UseG1GC -Dfile.encoding=UTF-8 -Djava.library.path=C:\Users\Player\AppData\Roaming\.unlucky\instances\dev-test\natives
+W [19:40:13] [Render thread/WARN] GLFW 报告 OpenGL 2.1，低于所需的 3.2；显卡驱动可能是 Microsoft Basic Display Adapter
+E [19:40:14] [Render thread/ERROR] 显卡驱动不支持 OpenGL 3.2，初始化窗口失败
+E java.lang.IllegalStateException: GLFW error before init: [0x10008] Failed to create window: WGL: The driver does not appear to support OpenGL
+E 	at com.mojang.blaze3d.platform.GLX._initGlfw(GLX.java:64)
+E 	at net.minecraft.client.MainWindow.<init>(MainWindow.java:261)
+E 	at net.minecraft.client.Minecraft.<init>(Minecraft.java:472)
+E 	at net.neoforged.fml.loading.targets.CommonLaunchHandler.clientService(CommonLaunchHandler.java:98)
+E Caused by: java.lang.UnsatisfiedLinkError: C:\Users\Player\AppData\Roaming\.unlucky\instances\dev-test\natives\lwjgl_opengl.dll: 找不到指定的模块。 (error code 126, 依赖的 d3dcompiler_47.dll 或 vcruntime140.dll 缺失时也会报同一条)
+W [19:40:15] [main/WARN] 正在生成本地崩溃报告 crash-2026-11-02_19.40.15-client.txt，请勿关闭窗口
+I [19:40:16] [main/INFO] 已加载 148 个模组，其中 3 个标记为客户端专用：iris-1.7.4, sodium-0.5.11, indium-1.0.32
+E [19:40:16] [main/ERROR] 启动失败：exit code 1（进程存活 4 秒）
diff --git a/crates/app-iced/src/pages/logs/sample_live.log b/crates/app-iced/src/pages/logs/sample_live.log
new file mode 100644
index 0000000..8daf728
--- /dev/null
+++ b/crates/app-iced/src/pages/logs/sample_live.log
@@ -0,0 +1,19 @@
+# M95 演示数据：一场**正常跑完**的会话（与 sample_crash.log 成对）。
+#
+# 为什么单独一份（视觉复审 r2 的 p3）：`live` 状态的页头写着「Finished normally」，
+# 却配着崩溃日志的尾行（`启动失败：exit code 1`），演示数据自相矛盾。
+#
+# 每行格式：`<等级> D|I|W|E <原文>`；`#` 开头是注释。
+
+I [19:22:01] [main/INFO] 正在启动 1.20.4，实例「开发测试」，加载器 NeoForge 21.1.72
+I [19:22:02] [main/INFO] Java 21.0.5 (Microsoft build 21.0.5+11-LTS), 内存 4096 MiB, JVM 参数 -Xmx4G -XX:+UseG1GC -Dfile.encoding=UTF-8 -Djava.library.path=C:\Users\Player\AppData\Roaming\.unlucky\instances\dev-test\natives
+W [19:22:03] [Render thread/WARN] GLFW 报告 OpenGL 3.2，低于推荐值 4.5；部分光影可能不可用
+I [19:22:05] [Render thread/INFO] OpenGL 3.2.0 NVIDIA 552.44，渲染器 NVIDIA GeForce GTX 1060 6GB
+I [19:22:08] [modloading-worker-0/INFO] 已加载 148 个模组，其中 3 个标记为客户端专用：iris-1.7.4, sodium-0.5.11, indium-1.0.32
+I [19:22:14] [Worker-Main-2/INFO] 正在准备生成区域，种子 20261102，生物群系 47 种，结构与地物共 113 项已注册
+I [19:22:19] [main/INFO] 世界「生存世界」已加载，游玩时间 3 小时 12 分
+I [19:22:20] [main/INFO] 本地服务器已启动，端口 25565
+I [19:22:41] [Render thread/INFO] 区块渲染完成，平均帧率 61 fps（垂直同步开）
+W [19:31:07] [Render thread/WARN] 一个资源包（Soartex Fanver 1.20）缺少 pack.png，已跳过图标
+I [19:40:12] [main/INFO] 正在停止服务器，保存世界数据
+I [19:40:13] [main/INFO] Stopping!
diff --git a/crates/app-iced/src/pages/logs/tests.rs b/crates/app-iced/src/pages/logs/tests.rs
new file mode 100644
index 0000000..7cf4793
--- /dev/null
+++ b/crates/app-iced/src/pages/logs/tests.rs
@@ -0,0 +1,370 @@
+//! 日志页的守门测试。每条断言下面写清「抓得住什么 / 抓不住什么」（这个仓的硬要求）。
+//!
+//! 这里**没有截图断言**：像素级验收靠 `pages_demo --screen=logs` 的六张图（浅/深 × 空态/有日志/崩溃），
+//! 单测只钉住「图上看不出来的那部分」——数值令牌、分组顺序、摘要格式、悬挂缩进的拆分规则、
+//! 页头会话身份的拼法。
+
+use unlucky_design::color::SchemeFlavor;
+use unlucky_design::typography::{FontFamily, Platform};
+use unlucky_i18n::catalog::{Catalog, Key};
+use unlucky_i18n::Lang;
+
+use crate::theme::Families;
+
+use super::super::layout::{frame_metrics, measure_cap_px, source, wrap, PaneKit};
+use super::model::{self, GROUPS, SUMMARY_HEADER};
+use super::{demo, lines, *};
+
+fn ui() -> Ui {
+    Ui::with_platform(
+        SchemeFlavor::Dark,
+        Platform::Windows,
+        Families {
+            text: "Segoe UI",
+            display: "Segoe UI",
+            mono: "Consolas",
+        },
+    )
+}
+
+#[test]
+fn page_is_single_column_and_never_wider_than_the_measure_cap() {
+    for width in [700.0, 1180.0, 1600.0] {
+        let metrics = frame_metrics(PaneKit::Single, width);
+        // 抓得住：谁把日志页改成两列（`secondary` 出现就会把正文列挤窄）；
+        //          谁绕开 `layout` 自己算列宽（`column` 会超 424）。
+        // 抓不住：列内文本是否真在这 424 里折行（那要量字形，单测量不到）。
+        assert!(metrics.secondary.is_none(), "w={width}");
+        assert!(
+            metrics.column <= measure_cap_px() + f32::EPSILON,
+            "w={width} 正文列 {} > 上限 {}",
+            metrics.column,
+            measure_cap_px()
+        );
+    }
+}
+
+/// **M102 ③**：`wrap::breakable` 这张表本身是好的，且**只改显示**（原文能还原）。
+///
+/// **抓得住**：断点表被掏空（`BREAK_AFTER` 少了一档 ⇒ 长标识符又没有断点）、
+/// `breakable` 开始污染原文（`strip` 还不了原）；
+/// **抓不住**：页面到底有没有把 `breakable` 接在渲染路径上——那条由
+/// [`the_page_wires_the_soft_breaks_into_both_rendering_paths`] 扫调用点守
+/// （r2 复审的变异 I：两处接线去掉后这条仍全绿，所以 docstring 不能替它吹牛）。
+#[test]
+fn log_text_carries_soft_breaks_but_keeps_the_original() {
+    let logs = demo::crash();
+    let summary = wrap::breakable(&logs.summary());
+
+    assert!(
+        !summary.contains("gl_operation_failure"),
+        "摘要里没有软断点，长标识符会被按字形劈开：{summary}"
+    );
+    assert_eq!(
+        wrap::strip(&summary),
+        logs.summary(),
+        "剪贴板拿到的仍是原文"
+    );
+
+    // 每条日志行的正文（拆前缀后的那一半）都要过同一件事：至少最长的那几行里有断点。
+    let broken = logs
+        .lines
+        .iter()
+        .filter(|line| {
+            !wrap::breakable(lines::split_prefix(&line.text).1).contains(wrap::SOFT_BREAK)
+        })
+        .count();
+    assert!(
+        broken * 2 < logs.lines.len(),
+        "{} / {} 行日志没有任何软断点（断点表可能被掏空了）",
+        broken,
+        logs.lines.len()
+    );
+}
+
+/// **源码结构（调用点）**：日志页必须把 `wrap::breakable` 接在**两条渲染路径**上。
+///
+/// r2 复审的变异 I：把 `lines::entry()` 的 `mono_owned(ui, wrap::breakable(body), …)` 改回
+/// `mono(ui, body, …)`、把 `diagnostic::summary_block()` 的 `wrap::breakable(&logs.summary())`
+/// 改回原文 ⇒ 420 条全绿，而视觉复审 ③（`graphics.gl_o` / `peration_failure`）原样回来。
+/// 断点表那侧已经 [`log_text_carries_soft_breaks_but_keeps_the_original`] 守着了，
+/// 这里守的是**接线**：页面真把显示串过了一遍它。
+///
+/// **抓得住**：任一处接线被摘掉（日志行 / 一行摘要）；
+/// **抓不住**：接线写得对但断点表被掏空（那是上一条的事）。
+///
+/// 用 [`source::function_region`] 而不是 `function_body`（r4 复审的变异 M3）：把
+/// `wrap::breakable` 外面套一层同义包装（`fn soft(…) { wrap::breakable(…) }`）再调用，是
+/// **等价重构**，不该假红；而「整条链路都没碰 `wrap::breakable`」照样红。
+#[test]
+fn the_page_wires_the_soft_breaks_into_both_rendering_paths() {
+    let entry = source::function_region(include_str!("lines.rs"), "fn entry");
+    assert!(
+        entry.contains("wrap::breakable("),
+        "日志行没接软断点（`graphics.gl_operation_failure` 会被按字形劈开）：\n{entry}"
+    );
+
+    let summary = source::function_region(include_str!("diagnostic.rs"), "fn summary_block");
+    assert!(
+        summary.contains("wrap::breakable("),
+        "一行摘要没接软断点：\n{summary}"
+    );
+}
+
+#[test]
+fn mono_lines_use_the_mono_stack_with_the_body_small_metrics() {
+    let ui = ui();
+    let style = lines::mono_style(&ui);
+
+    // 抓得住：把等宽行换成正文栈（`family` 会变 `Text`）——那是「等宽」失真的唯一入口；
+    //          顺手改字号/行高（数值表要写 12/16，漂了就红）。
+    // 抓不住：CJK 字形到底有没有被回退到别的族（要查字体 cmap，本 crate 不做）。
+    assert_eq!(style.family, FontFamily::Mono);
+    assert_eq!(style.size_px, 12.0);
+    assert_eq!(style.line_height_px, 16.0);
+    assert_eq!(
+        ui.font_of(style).family,
+        iced::font::Family::Name("Consolas")
+    );
+}
+
+#[test]
+fn findings_are_grouped_critical_first_and_empty_groups_do_not_exist() {
+    let findings = demo::crash().findings;
+    let logs = Logs {
+        findings,
+        ..Logs::default()
+    };
+    let counts: Vec<usize> = GROUPS.iter().map(|band| logs.group(*band).len()).collect();
+
+    // 抓得住：分组顺序被改成低置信度在前（最像主因的沉底）；空组也被画出一个标题。
+    // 抓不住：组内顺序（页面刻意不重排 presenter 给的顺序）。
+    assert_eq!(GROUPS[0], Confidence::High);
+    assert_eq!(
+        counts.iter().sum::<usize>(),
+        logs.findings.len(),
+        "每条结论必须落进恰好一个分组"
+    );
+    assert!(counts[0] >= 1, "样例至少有高置信度结论");
+    assert!(logs.group(Confidence::Low).is_empty());
+}
+
+#[test]
+fn summary_is_a_single_deterministic_line_carrying_rule_and_confidence() {
+    let logs = demo::crash();
+    let summary = logs.summary();
+
+    // 抓得住：摘要里丢了规则 id / 置信度档 / 置信度百分比（换 issue 时最关键的三个字段）；
+    //          有人把换行塞进摘要（"一行"就不成立了）。
+    // 抓不住：粘贴到 issue 后的可读性（那是人判断的），也不守文案语言（摘要刻意不含界面文案）。
+    assert!(!summary.contains('\n'), "{summary}");
+    assert!(summary.starts_with(SUMMARY_HEADER), "{summary}");
+    assert!(
+        summary.contains("integrity.unsatisfied_link:high(85)"),
+        "{summary}"
+    );
+    assert!(summary.contains("lines="), "{summary}");
+    assert_eq!(summary, logs.summary(), "同一份模型两次摘要必须一致");
+
+    let empty = Logs::default();
+    assert_eq!(empty.summary(), "ULL-LOGS v1 | lines=0");
+}
+
+#[test]
+fn the_band_is_the_documented_confidence_band_not_a_severity_impostor() {
+    // 抓得住：阈值边界写成 `>` / `>=` 的 off-by-one（80 / 50 是档位的定义点）；
+    //          以及有人把档位名字改回 `critical/warning/notice` 那种**严重度词汇**
+    //          （那会让 64 条规则里 12 条进错组，两个方向都有——视觉复审 r3 的 P2-2）。
+    // 抓不住：档位划分本身对不对（那是产品口径；DTO 补上 `severity` 后应换回真严重度，已报 finding）。
+    assert_eq!(Confidence::of(100), Confidence::High);
+    assert_eq!(Confidence::of(80), Confidence::High);
+    assert_eq!(Confidence::of(79), Confidence::Medium);
+    assert_eq!(Confidence::of(50), Confidence::Medium);
+    assert_eq!(Confidence::of(49), Confidence::Low);
+    assert_eq!(Confidence::of(0), Confidence::Low);
+
+    assert_eq!(Confidence::High.slug(), "high");
+    assert_eq!(Confidence::Medium.slug(), "medium");
+    assert_eq!(Confidence::Low.slug(), "low");
+}
+
+#[test]
+fn the_longest_stack_line_reaches_the_view_model_untruncated() {
+    let logs = demo::crash();
+    let longest = logs
+        .lines
+        .iter()
+        .map(|line| line.text.chars().count())
+        .max()
+        .unwrap_or(0);
+
+    // 抓得住：为了排版把行截断 / 加省略号（用户就再也拿不回原始堆栈）。
+    // 抓不住：折行后的视觉行数（渲染期的事）。
+    assert!(
+        longest >= 200,
+        "样例里应有一条 ≥200 字符的堆栈行，实际 {longest}"
+    );
+    assert!(!logs.lines.iter().any(|line| line.text.ends_with('…')));
+}
+
+#[test]
+fn a_line_is_split_into_prefix_and_body_for_the_hanging_indent() {
+    // 抓得住：悬挂缩进被改回「整行一个文本块」（`at` 会重新独占一行、续行回到行首）。
+    // 抓不住：缩进到底落在第几像素（那要量字形/截图，见报告的前后对比图）。
+    assert_eq!(
+        lines::split_prefix("[19:40:12] [main/INFO] hi"),
+        ("[19:40:12] ", "[main/INFO] hi")
+    );
+    assert_eq!(
+        lines::split_prefix("at com.mojang.blaze3d.platform.GLX._initGlfw(GLX.java:64)"),
+        (
+            "at ",
+            "com.mojang.blaze3d.platform.GLX._initGlfw(GLX.java:64)"
+        )
+    );
+
+    // 没有空格 / 第一个「词」过长 ⇒ 不拆（否则正文被挤成一条 1 字符宽的缝）。
+    assert_eq!(
+        lines::split_prefix("java.lang.RuntimeException"),
+        ("", "java.lang.RuntimeException")
+    );
+    assert_eq!(
+        lines::split_prefix("https://example.invalid/aaaaaaaaaaaaaaaaaaaaaaaa va"),
+        ("", "https://example.invalid/aaaaaaaaaaaaaaaaaaaaaaaa va")
+    );
+    // CJK 行：第一个空格若落在 20 字符以内就正常拆（时间戳 + 中文正文）。
+    assert_eq!(
+        lines::split_prefix("[19:40:12] 正在启动 1.20.4"),
+        ("[19:40:12] ", "正在启动 1.20.4")
+    );
+}
+
+#[test]
+fn status_line_names_the_session_with_the_launch_outcome_keys() {
+    // 抓得住：页头副标题不再说「这是哪个实例、哪一场、什么结局」（视觉复审 P2-2），
+    //          以及 `LaunchOutcome*` 三 key 又回到「定义了但零调用点」。
+    // 抓不住：副标题在 1180 下会不会撞上右侧动作区（那要看截图）。
+    let en = model::status_line(
+        Some("开发测试"),
+        Some("11-02 19:40"),
+        Some(Outcome::Crashed),
+        Lang::En,
+    )
+    .expect("有实例名与结局就该有副标题");
+    assert_eq!(en, "开发测试 · 11-02 19:40 · The game crashed");
+
+    let zh = model::status_line(
+        Some("开发测试"),
+        Some("11-02 19:40"),
+        Some(Outcome::SilentFail),
+        Lang::ZhCn,
+    )
+    .expect("静默失败也有副标题");
+    assert!(zh.contains("疑似静默失败"), "{zh}");
+
+    // 不知道是哪一场就别编：没有实例名 / 没有结局时退回静态副标题。
+    assert!(model::status_line(None, Some("11-02 19:40"), Some(Outcome::Ok), Lang::En).is_none());
+    assert!(model::status_line(Some("x"), None, None, Lang::En).is_none());
+
+    // demo 的三种状态里，有会话身份的那两种必须带副标题（页面才有东西可显示）。
+    assert!(demo::State::Crash.build(Lang::En).status.is_some());
+    assert!(demo::State::Live.build(Lang::En).status.is_some());
+}
+
+#[test]
+fn empty_state_is_driven_by_both_lists_being_empty() {
+    let mut logs = Logs::default();
+    assert!(logs.is_empty());
+
+    logs.findings = demo::crash().findings;
+    // 抓得住：把「没有日志行」当成空态（有诊断时那样会藏掉最该看的东西）。
+    assert!(!logs.is_empty(), "只有诊断也不算空态");
+
+    let live = demo::State::Live.build(Lang::En);
+    assert!(!live.is_empty());
+    assert!(live.findings.is_empty(), "live 状态没有诊断");
+}
+
+#[test]
+fn the_fixture_parser_survives_a_non_ascii_first_char() {
+    // 抓得住：`parse` 用 `split_at(1)` 切多字节序列会直接 panic（视觉复审 r2 的 p3 实测过）。
+    // 抓不住：样例文件本身写坏（比如等级前缀写成小写 `e`）——那会被静默跳过，只体现为行数变少。
+    assert!(!demo::parse("日本語の行")
+        .iter()
+        .any(|line| line.level == Level::Info));
+
+    let parsed = demo::parse(
+        "I 正常一行
+W 警告一行
+# 注释
+
+E 错误一行",
+    );
+    assert_eq!(parsed.len(), 3);
+    assert_eq!(parsed[0].text, "正常一行");
+    assert_eq!(parsed[1].level, Level::Warn);
+    assert_eq!(parsed[2].level, Level::Error);
+}
+
+#[test]
+fn demo_state_comes_from_the_fixture_variable() {
+    // 抓得住：环境变量取值拼错（截图会静默退成 crash，出图的人以为拍到了空态）。
+    assert_eq!(demo::State::of_env_value(Some("empty")), demo::State::Empty);
+    assert_eq!(demo::State::of_env_value(Some("live")), demo::State::Live);
+    assert_eq!(demo::State::of_env_value(Some("crash")), demo::State::Crash);
+    assert_eq!(demo::State::of_env_value(None), demo::State::Crash);
+}
+
+#[test]
+fn every_key_the_page_uses_is_translated_in_both_languages() {
+    let keys = [
+        Key::NavLogs,
+        Key::LogsSubtitleIdle,
+        Key::LogsStatus,
+        Key::LogsOpenFolder,
+        Key::LogsClear,
+        Key::LogsOutputTitle,
+        Key::LogsDiagnosisTitle,
+        Key::LogsConfidenceHigh,
+        Key::LogsConfidenceMedium,
+        Key::LogsConfidenceLow,
+        Key::LogsSubtitleLive,
+        Key::LogsConfidence,
+        Key::LogsSuggestedFix,
+        Key::LogsSummaryLabel,
+        Key::LogsCopySummary,
+        Key::LogsEmptyTitle,
+        Key::LogsEmptyBody,
+        Key::LogsEmptyAction,
+        // 结局文案由页头副标题间接用到（见 `status_line`）
+        Key::LaunchOutcomeNormal,
+        Key::LaunchOutcomeCrash,
+        Key::LaunchOutcomeSilent,
+    ];
+
+    // 抓得住：页面用到的 key 被改名/删掉，或只进了其中一套目录（缺译会返回 `⟪missing⟫`）。
+    // 抓不住：译文的语气与长度（人读的事）。
+    for lang in [Lang::En, Lang::ZhCn] {
+        let catalog = Catalog::of(lang);
+        for key in keys {
+            assert!(
+                catalog.get(key).is_some(),
+                "{} 缺 {}",
+                lang.setting_value(),
+                key.name()
+            );
+        }
+    }
+
+    // 占位符名写错时 `render` 会把 `{percent}` 原样留在文案里——这条钉住它。
+    let rendered = Catalog::of(Lang::En).render(Key::LogsConfidence, &[("percent", "85")]);
+    assert_eq!(rendered, "Confidence 85%");
+}
+
+#[test]
+fn header_stays_two_lines_because_of_the_status_subtitle() {
+    let ui = ui();
+    // 抓得住：有人把副标题去掉，页头从 84 掉回 56（版式台账上会露出来）。
+    assert_eq!(ui.metrics().header_height(true), 84.0);
+    assert!(ui.metrics().header_height(true) > ui.metrics().header_height(false));
+}
diff --git a/crates/app-iced/src/pages/message.rs b/crates/app-iced/src/pages/message.rs
new file mode 100644
index 0000000..baa530d
--- /dev/null
+++ b/crates/app-iced/src/pages/message.rs
@@ -0,0 +1,140 @@
+//! 页面消息与动作表（M101 r2 从 `pages/mod.rs` **原样搬出**）。
+//!
+//! 为什么拆：合并 M100/M101 之后 `pages/mod.rs` 是 397 行，只剩 3 行余量，下一条线往枚举里加
+//! 一个变体（含文档）就顶破 400 硬线。拆法与 M99 的 `pages/nav.rs` 同一种范式：**纯搬移**、
+//! 一行不改、路径靠 `pages/mod.rs` 的 `pub use` 再导出保持不变（`pages::Message` / `pages::Action`）。
+//!
+//! `pages::Message` 是页面层的自有消息类型（**不** import `crate::app::Message`，组件契约 §2 的
+//! 同一条纪律）；app 层只做一次 `.map`。
+
+use unlucky_i18n::LangChoice;
+use unlucky_presenter::router::Route;
+
+use super::appearance;
+use super::content;
+use super::download::{Category, Loader};
+use super::settings;
+
+/// 页面消息。
+///
+/// **故意不用 `crate::app::Message`**（组件库契约 §2 的同一条理由）：页面不绑 app 的状态层，
+/// 接线时由 app 层把这里的三类意图翻成 presenter 的 `AppCommand` / `Route`。
+#[derive(Debug, Clone)]
+pub enum Message {
+    /// 骨架期动作（三页的占位按钮 + 实例页上还没接后端的两个页头动作）。
+    Action(Action),
+    /// 路由跳转：导航轨、列表行、窄窗「返回」都走这一条（栈语义归 `presenter::router`）。
+    Navigate(Route),
+    /// 启动某实例（app 层翻成 `AppCommand::LaunchInstance`）。
+    Launch(String),
+    /// 停止某实例（app 层翻成 `AppCommand::StopInstance`）。
+    Stop(String),
+    /// 外观项改动（设置页「外观」分组 → `App` 的状态与落盘）。
+    ///
+    /// 载荷是**用户请求值**（未钳位）：钳位与 CPU 档降级在 `appearance::alpha` 里做，
+    /// 页面只表达意图（与组件库「不持有业务状态」同一条纪律）。
+    Appearance(appearance::Change),
+    /// 选中下载页的一个版本（M94）：**页面内选中**，app 层只改视图模型，不 dispatch。
+    SelectVersion(String),
+    /// **确认安装**选中的版本（用当前安装选项）。
+    ///
+    /// M105 起语义变了：以前是「立刻装原版」（`AppCommand::InstallVersion`），现在是
+    /// 「用选项区里选好的加载器 / 加载器版本 / 实例名开工」（`AppCommand::CreateInstance`）。
+    /// 载荷仍是版本 id，app 层拿它去草稿里取其余三项。
+    InstallVersion(String),
+    /// 改安装选项的加载器（M105；app 层改草稿，必要时派 `AppCommand::ListLoaderVersions`）。
+    SetLoader(Loader),
+    /// 改加载器版本（M105；空串 = 用官方最新）。
+    SetLoaderVersion(String),
+    /// 改实例名（M105；空串 = 用版本号）。
+    SetInstanceName(String),
+    /// 取消正在跑的安装（M94；`AppCommand::CancelInstall`）。
+    CancelInstall,
+    /// 切换下载页分类（M94；app 层翻成 `AppCommand::ListVersions`，`All` 只画现有快照）。
+    SetCategory(Category),
+    /// 搜索版本号（**M107**）：查询词写进 `AppState.download_query`，页面走同一条重建路径过滤。
+    ///
+    /// 为什么不是「页面自己存一份查询」：下载页是**无状态视图**（每帧由快照重建），页面持有的
+    /// 字段活不过下一次事件；查询词只有落在 presenter 的快照里才能跨帧存活，而
+    /// `Download::from_snapshot` 本来就读 `download_query` —— 复用这条路，过滤只有一份真相。
+    SetVersionQuery(String),
+    /// 清空搜索框（**M107**）。与 [`Self::SetVersionQuery`] 同一支的 `""` 特例，
+    /// 单独一个变体是为了让「清空」这个意图在日志与测试里一眼可辨。
+    ClearVersionQuery,
+    /// 选中第二级侧栏的一个主版本桶（**M107**；`None` = 全部版本）。
+    ///
+    /// **纯视图态**（与 [`Self::SelectVersion`] 同一类）：不派业务命令，app 层只改视图模型。
+    SelectMajor(Option<String>),
+    /// 折叠 / 展开第一级（版本类型）侧栏（**M107**）。纯视图态。
+    ToggleTypeRail,
+    /// 把现成文本塞进剪贴板（**M95**：诊断卡片的一行摘要，文本由页面造，app 只搬）。
+    CopySummary(String),
+    /// 设置页的一组消息（**M101 `SETTINGSMSG`**）：设置页的**唯一**投递口。
+    ///
+    /// 四条填页线（java / download / language+appearance / ai+about）各自在自己的文件里定义
+    /// 消息枚举，本枚举**不再**为设置页增加第二个变体——「加一支设置页消息」从此不碰本文件，
+    /// 也不碰 `app/update/page_messages.rs` 那条不许 `_ =>` 的 match。加变体与落点见
+    /// `pages/settings/message.rs`（`app/update/settings.rs` 对它做穷尽分发，漏接线报 E0004）。
+    Settings(settings::GroupMessage),
+    /// 换界面语言（**M106**：设置页 General 分组的语言行 → `App::set_language`）。
+    ///
+    /// 载荷是**用户意图**（跟随系统 / 手选某一门语言），不是「生效语言」：生效语言由
+    /// `LangChoice::resolve` 按 D28 的顺序算出来，页面不参与计算。
+    ///
+    /// 为什么不折进 [`Message::Settings`] 那个投递口：语言档位不是「某一组的状态」——它要**落盘**
+    /// 到 `ui.language` 并**重建整棵视图模型**（目录是 `pages::Model` 的一部分），而那条落点
+    /// （`app/update/settings/language_appearance.rs`）是 language+appearance 线的文件。
+    /// 代价是本文件多一个变体；收口方向写在 `settings/general.rs` 的文档里。
+    Language(LangChoice),
+    /// 内容库页的一组消息（**M109**）：与设置页同一个范式（页面自己的枚举 + 一个投递口）。
+    ///
+    /// 加一条内容库消息只动 `pages/content/message.rs`，不动本枚举的正文，也不动
+    /// `app/update/page_messages.rs` 那条不许 `_ =>` 的 match。
+    Content(content::Message),
+    /// 账户页消息（**M114**：三轨登录 / 列表动作 / 表单输入；app 层翻成 `AppCommand`）。
+    ///
+    /// 与 `Settings` 同一种做法：账户页自己的消息枚举在 `pages/account.rs`，这里只加一支入口。
+    Account(crate::pages::account::Message),
+}
+
+/// 页面动作清单（骨架期够用就行；接线时按业务语义重命名/扩充）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Action {
+    /// 新建实例（**还没有后端**，见模块文档偏离 #8）。
+    NewInstance,
+    /// 导入（同上）。
+    Import,
+    /// 返回实例列表（窄窗整页切换）。**已由 `Message::Navigate(Route::Instances)` 取代**，
+    /// 这里保留枚举项是为了别把「返回」这件意图从动作表里抹掉（外壳回退路径仍可能用到）。
+    Back,
+    /// 启动（占位动作表里的「启动」；真启动走 `Message::Launch`）。
+    Play,
+    /// 更多。
+    More,
+    /// 复制实例。
+    Duplicate,
+    /// 打开实例目录。
+    OpenFolder,
+    /// 删除实例。
+    Delete,
+    /// 重新探测下载源。
+    RefreshSources,
+    /// 浏览版本列表。
+    BrowseVersions,
+    /// 导入整合包。
+    ImportModpack,
+    /// 检查下载源。
+    CheckSources,
+    /// 打开日志目录。
+    OpenLogs,
+    /// 复制诊断信息。
+    CopyDiagnostics,
+    /// 清空日志。
+    ClearLogs,
+    /// 重置当前设置分组。
+    ResetSection,
+    /// 保存设置。
+    SaveSettings,
+    /// 新增逐实例覆盖。
+    AddOverride,
+}
diff --git a/crates/app-iced/src/pages/mod.rs b/crates/app-iced/src/pages/mod.rs
new file mode 100644
index 0000000..18fb0f8
--- /dev/null
+++ b/crates/app-iced/src/pages/mod.rs
@@ -0,0 +1,296 @@
+//! # 页面层（P4）：布局系统 + 四页 + **路由/真组件的接入口**（M84 `PAGEFRAME` → M90 `APPSKEL`）
+//!
+//! ## 这一层交了什么
+//!
+//! | 阶段 | 交付 | 判据 |
+//! |---|---|---|
+//! | M84 | **布局系统**（档位/版面/列宽）+ 四页占位视觉 | 下面的版面阈值表 |
+//! | **M90（本文件当前状态）** | ①视图模型 [`model`] ②导航项接上 `presenter::router::Route` ③**实例页整页接真组件 + 真数据** | 「接真组件后版面约束一条没破」（见 `pages/tests.rs` 的数值断言） |
+//! | M99 `SETTINGSFRAME` | **纯搬移**：导航表搬到 [`nav`]，设置页拆成目录（`pages/settings/**`），i18n 目录按域拆开 | 截图逐字节相同 + `catalog` 金表（`key -> 译文` 全量不变） |
+//!
+//! **导航轨归属（M90 r3 订正，复审 P2-1）**：产品路径（`app/view.rs`）走
+//! `shell::view_with_content`，导航轨由 **`shell/nav.rs` 的手搓实现**画——它与 M78 组件几何同值
+//! （宽 88、药丸 56×32），复审逐像素量过「r1 产品图（真组件 rail）vs r2 产品图（shell rail）
+//! 在 y≥48 区域差异为 0」；组件版的 `nav::rail` 现在只服务 `pages::app`（`pages_demo` 出口图、
+//! harness）与单测。为什么不是「把 rail 挪进内容槽位」：那需要把 `shell` 的消息类型泛型化/映射，
+//! 成本远大于收益（见偏离表 #10）。
+//!
+//! 实例页之外的三页**仍是 M84 的占位视觉**（下载/日志/设置），但它们已经：
+//! 走同一个 `Message` → `update` → `Route` 通道，导航轨点得动、路由栈按 `presenter::router` 的语义走。
+//! 页面美化是后续 mission 的事，本 mission 只保证「地基是通的」。
+//!
+//! ## 版面规矩（M84 立的三条，M90 一条没动）
+//!
+//! 1. **宽度档位**：官方响应式断点 **600 / 840**（[`layout::WidthClass`]）；
+//! 2. **版面**：单列 / supporting-pane / list-detail，各自的成立条件与退化阈值写在 [`layout`]；
+//! 3. **行宽上限**：正文列硬上限 **424px（逐行实测 67 字符 ≤72）**（[`layout::measure_cap_px`]），
+//!    由 [`layout::content_column_width`] / [`layout::frame_metrics`] **无条件施加**，
+//!    页面拿不到「更宽」的选项。
+//!
+//! ## 版面阈值表（`layout` 模块文档是全文，这里给速查）
+//!
+//! | 版面 | 用它的页面 | 成立条件 | 退化 |
+//! |---|---|---|---|
+//! | `SingleColumn` | 下载 / 日志（永远）；实例 / 设置（窄窗） | 总是 | — |
+//! | `SupportingPane` | 设置 | `w ≥ 600` 且 `w ≥ 720`（240 + 24 + 320 + 2×24 + 88） | 单列（分组按组堆叠） |
+//! | `ListDetail` | 实例 | `w ≥ 840`（官方 expanded）且 `w ≥ 816` | 单列（列表 ↔ 详情整页切换） |
+//!
+//! ## 模块
+//!
+//! | 文件 | 职责 |
+//! |---|---|
+//! | [`layout`] | **布局系统**：档位 / 版面 / 列宽 / 阈值，纯函数 + 单测（无 iced 控件树） |
+//! | [`model`] | **视图模型**：presenter 快照 → 页面要画的东西（页面层不认识 presenter 类型） |
+//! | [`frame`] | 页头 / 内容列 / 两列骨架 / 空态 / 卡片 / 分隔线 |
+//! | [`nav`] | 导航轨的 `NAV` 表 + 部件版 `rail()`（harness / 单测；产品走 `shell/nav.rs`） |
+//! | [`message`] / [`screen`] | `pages::Message` / `Action` / `Screen`（M101 r2 从本文件原样搬出） |
+//! | `instances` | 实例页（list-detail）——**M90 唯一打通到真组件 + 真数据真命令的页** |
+//! | `settings` | 设置页（supporting-pane，占位视觉）：分组注册表 + 每个分组一个文件 |
+//! | `download` / `logs` | 下载 / 日志页（单列，占位视觉） |
+//! | [`harness`] | 截图 harness（`examples/pages_demo.rs` 的入口，**不是** `cli.rs` 的一部分） |
+//!
+//! ## 消息与路由（M90 新增）
+//!
+//! 页面**不 import `crate::app::Message`**（组件契约 §2 的同一条纪律）：它有自己的
+//! [`Message`]，app 层只做一次 `.map`。路由跳转的载荷是 `presenter::router::Route` 本身，
+//! 于是「页面里点一行」= 「压一层栈」，语义与 presenter 的 `Router` 天然一致，
+//! 中间不再有一层「页面自定义的选中项」需要同步。
+//!
+//! ### 设置页只有一个投递口（M101 `SETTINGSMSG`）
+//!
+//! 设置页的四条填页线各自在自己的文件里定义消息与状态，本文件的 [`Message`] 只留一个
+//! [`Message::Settings`]（详见 `pages/settings/mod.rs` 的「消息 / 状态」两节）；`Message` 与
+//! `Screen` 本身也在 M101 r2 搬到 [`message`] / [`screen`]（`pages/mod.rs` 合并后 397 行，只剩
+//! 3 行余量），这里的 `pub use` 保证了 `pages::Message` / `pages::Action` / `pages::Screen`
+//! 三条路径一字未变。
+//!
+//! ## 偏离登记（D30 要求逐条写清；M84 六条 + M90 三条）
+//!
+//! | # | 偏离 | 为什么 | 什么时候收口 |
+//! |---|---|---|---|
+//! | 1 | 页头按 M3 口径**铺满页面宽度**（贴页边距），不与正文列对齐 | AppBar 本来就该满宽；1180 下页头右缘 **1156** 与详情列右缘 **896** 有 **260px 分歧** | 真 top bar 落地时按 M3 定语（页头右侧是操作区，不跟随列宽） |
+//! | 2 | 空态标题 `HeadlineSmall 24` 比页标题 `TitleLarge 22` 大 | 12b §15.2 明确「空态是唯一允许 Headline 级的场景」，与 §16.4 的页标题档有 spec 张力 | 有意保留，不修 |
+//! | 3 | 单列页（下载 / 日志）在 1180 下只用掉 **40.6%** 内容宽（424/1044） | 行宽上限的必然结果；空态居中不显空 | 版本浏览真正接数据后重新决议 `PaneKit` |
+//! | 4 | 空态图标字形 **40px**（12b 15.1 是 `[估]` 32~48） | 令牌 `IconSize` 只有 24 一档，`frame::glyph` 按尺寸重算 stroke | 组件库的 `EmptyState`（M77）落地时 |
+//! | 5 | 窄窗「Back to instances」没有前导箭头 | 占位文本按钮没有图标位 | 真 top bar / M78 的导航件落地时 |
+//! | 6 | 实例页「未选中详情」空态**没有出图** | 演示数据固定选中第 1 条；空态代码路径在（`detail_empty`） | D30 状态矩阵补齐时补一张，不必重跑全套 |
+//! | 7 | ~~标题栏仍是 48px 留白带~~ → **已于 M90 r2 修**：产品页现在走 `shell::view_with_content`，标题栏 / 拖动热区 / 两条缩放热区 / 三个 caption 键全在 | r1 的实质问题是**交互面缺失**（无边框窗口 + 产品页没有任何窗口装饰 ⇒ 拖不动、缩不了、点不到关闭），不是「少画了一条栏」 | ✅ 已收口（见下） |
+//! | 8 | 实例页的「New instance / Import」仍是**没有后端的按钮**（M90） | presenter 没有「打开新建向导」的指令（`wizard` 只有状态机，`AppCommand` 里无对应项），已报 finding | 向导 mission 补 `AppCommand::OpenWizard` 之后 |
+//! | 10 | **两套 rail 各测各的**（M90 r3）：产品走 `shell/nav.rs`，组件版只给 harness/单测 | r2 把产品页接进真外壳后，rail 自然落到 `shell/nav.rs`（像素等价，见上）。但两边的守门是分开的：`shell/nav.rs` 自带 indicator 56×32 的单测，`pages/tests.rs` 守的是组件 rail 的 88 ⇒ **将来哪边先漂没人拦**。统一要泛型化 shell 的消息类型，成本大于收益 | 谁做「rail 单一实现」的 mission（已在报告登记）；在那之前任何改 rail 几何的改动都要两处一起改并各自跑守门 |
+//! | 9 | 实例页的正文段落只在**演示数据**里出现（M90） | 真快照里没有「正文描述」这种字段；M84 那段 361 字符的 `NOTE` 是给行宽测量当样本的，不能凭空造到真页面里 | i18n / 实例详情 mission 补真实描述字段 |
+//!
+//! ### 偏离 #7 的收口记录（M90 r2 / P1-1）
+//!
+//! r1 的产品页渲染的是 `pages::app`：一条**只有高度、没有任何控件**的标题栏留白带。而
+//! `DragWindow` / `ResizeStart` / `Minimize` / `ToggleMaximize` / `Close` 五种消息的**构造点只有
+//! `shell/mod.rs`**，窗口又是 `decorations: false` ⇒ 交互模式下拖不动、缩不了、点不到关闭。
+//!
+//! 修法：`shell::view_with_content(ui, nav, title, content, forced)` 把外壳（标题栏 + 三条热区 +
+//! 导航轨）与内容区拆开，产品页把 [`page`] 的树塞进内容槽位；`shell::view`（M68 骨架卡）保留给
+//! `Route::Agent` 回落 —— 删了会让私有模块里的 `view` / `shell::nav::rail` 变死代码，`-D warnings` 会红。
+//!
+//! `pages::app`（本文件）现在**只服务 harness**（`pages_demo` example 与单测）：它的标题栏仍是留白带，
+//! 因为 `shell` 的回调类型是 `crate::app::Message`，套不进 `pages::Message` 的树里。
+//!
+//! ## 截图通道
+//!
+//! ```text
+//! cargo run -p unlucky-app-iced --example pages_demo -- \
+//!   --screen=instances --width=1180 --height=760 \
+//!   --screenshot=out.png --screenshot-theme=light --software-renderer
+//! ```
+//!
+//! 产品二进制的截图走 `--screenshot`（页面树由 app 层按路由装配），本 harness 只出**单页**图，
+//! 用于页面级回归与宽度对照。
+
+pub mod appearance;
+pub mod frame;
+pub mod harness;
+pub mod layout;
+pub mod model;
+
+pub mod account;
+pub mod content;
+mod download;
+mod instances;
+mod logs;
+mod message;
+mod nav;
+mod screen;
+// M101：设置页的两条漏斗（消息 / 状态）都从这个模块树里出——app 层要构造
+// `settings::GroupMessage`、借用 `settings::Groups`，所以最小暴露面是 `pub(crate)`。
+// **不是** `pub`：`private_interfaces` 按**类型自身的声明可见性**判（四个 `Message` 枚举与
+// `GroupMessage` 声明成 `pub` 就够），把整个设置页模块树暴露成 crate 公开 API 没有回报。
+pub(crate) mod settings;
+
+#[cfg(test)]
+mod tests;
+pub use download::{cancelled_toast, Category, Download, InstallDraft, Loader};
+pub use layout::{FrameMetrics, PageLayout, PaneKit, WidthClass};
+pub use logs::{Confidence, Finding, Level, Line, Logs, Outcome};
+pub use message::{Action, Message};
+pub use model::{Detail, Instances, Meta, Model, Row};
+pub use screen::Screen;
+pub use settings::Language;
+
+use iced::widget::{column, container, row, space};
+use iced::{Element, Length};
+
+use unlucky_design::elevation::MaterialLayer;
+
+use crate::theme::Ui;
+
+use frame::filled;
+
+/// **单页内容**（不含外壳）：交给 `shell::view_with_content` 塞进真标题栏与导航轨之间。
+///
+/// 产品路径（`app/view.rs`）走 [`page_with_settings`]：外壳由 `shell` 画（拖动/缩放/三个
+/// caption 键、rail 88），这里只画「页头 + 内容列」。列宽仍按**整个窗口宽**算
+/// （`layout::frame_metrics` 内部会扣掉 rail 88 与页边距），所以外壳换了不影响版面判据。
+///
+/// 视图模型由**调用方持有**（`App` 在状态变化时重建一次 `Model`），这里只借用：
+/// `view(&self)` 不能返回一棵借用局部变量的树。
+pub fn page<'a>(ui: &'a Ui, model: &'a Model) -> Element<'a, Message> {
+    render(
+        ui,
+        model,
+        settings::States {
+            appearance: None,
+            groups: settings::demo_groups(),
+        },
+        Language::default(),
+    )
+}
+
+/// 同 [`page`]，但带上**外观状态**（设置页的「外观」分组要读当前值与诊断）。
+///
+/// 为什么另开一个入口而不是给 `Model` 加字段：`pages/model.rs` 是页面与 presenter 之间的展示
+/// 契约（`Model` 只装「要画什么」），外观是**运行时状态**（滑块请求值、已解码的背景图、诊断），
+/// 塞进去会让演示数据（`pages::demo`）也得伪造一份外观状态。
+///
+/// 这条入口拿的是**演示组状态**（[`settings::demo_groups`]）：页面层没有真组状态可用，
+/// 产品路径走 [`page_with_settings`]。
+pub fn page_with_appearance<'a>(
+    ui: &'a Ui,
+    model: &'a Model,
+    appearance: &'a appearance::State,
+) -> Element<'a, Message> {
+    render(
+        ui,
+        model,
+        settings::States {
+            appearance: Some(appearance),
+            groups: settings::demo_groups(),
+        },
+        Language::default(),
+    )
+}
+
+/// 产品路径：带上**设置页那份只读状态**（外观运行期状态 + 各组自己的状态）。
+///
+/// 为什么要单独一个入口：组状态的所有者是 `App`（`app/state.rs` 的 `settings` 字段），页面层
+/// 只借用一帧。加/改某一组的字段不改变这条签名（`States` 里只有 `&Groups`），所以四条填页线
+/// 都不必来这里动一行。
+/// `language` 是 M106 加的：「当前档位 + 生效语言」只有 `App` 知道（`App::language()`），而设置页
+/// 的 General 组要画它。唯一调用点是 `app/view.rs`；harness 那三条入口（[`page`] /
+/// [`page_with_appearance`] / [`app_with_appearance`]）仍用 [`Language::default`]。
+pub fn page_with_settings<'a>(
+    ui: &'a Ui,
+    model: &'a Model,
+    states: settings::States<'a>,
+    language: Language,
+) -> Element<'a, Message> {
+    render(ui, model, states, language)
+}
+
+fn render<'a>(
+    ui: &'a Ui,
+    model: &'a Model,
+    states: settings::States<'a>,
+    language: Language,
+) -> Element<'a, Message> {
+    let metrics = layout::frame_metrics(model.screen.kit(), model.window_width);
+
+    match model.screen {
+        Screen::Instances => instances::view(ui, metrics, model),
+        // M106：下载页此前写死成 `Lang::En`，现在跟 `model.lang`（页面文案跟着界面语言走）。
+        Screen::Download => download::view(ui, metrics, &model.download, model.lang),
+        // M109：内容库页同样跟 `model.lang`
+        Screen::Content => content::view(ui, metrics, &model.content, model.lang),
+        Screen::Settings => settings::view(ui, metrics, states, language),
+        Screen::Logs => logs::view(ui, metrics, &model.logs, model.lang),
+    }
+}
+
+/// 整窗（**harness 专用**）：标题栏留白带 + 导航轨 + 当前路由的页面。
+///
+/// 产品路径**不走这里**（它走 [`page`] + `shell::view_with_content`，用真标题栏）。这个入口留给
+/// `pages_demo` example 与单测：它们要一张「只有页面、不接 app 消息」的独立图，而 `shell` 的
+/// 回调类型是 `crate::app::Message`，套不进 `pages::Message` 的树里。
+pub fn app<'a>(ui: &'a Ui, model: &'a Model) -> Element<'a, Message> {
+    app_with_appearance(ui, model, None)
+}
+
+/// 同 [`app`]，但可以带上**外观运行期状态**。
+///
+/// `Some(state)` ⇒ 设置页「外观」分组画**真控件**（`pages/appearance/section.rs`）；
+/// `None` ⇒ 画演示行，与 [`app`] 逐像素等价。harness 的 `--appearance=real` 走的就是这一支：
+/// M100 之前 harness 恒传 `None`，于是 D30 要的「带真实外观控件」那一屏**根本不存在**——
+/// 报告上写着「设置页已接真控件」，图里却只有演示行（U1 的形状）。
+pub fn app_with_appearance<'a>(
+    ui: &'a Ui,
+    model: &'a Model,
+    appearance: Option<&'a appearance::State>,
+) -> Element<'a, Message> {
+    // harness 路径没有真组状态：用演示状态（[`settings::demo_groups`]），外观状态照传。
+    let body = render(
+        ui,
+        model,
+        settings::States {
+            appearance,
+            groups: settings::demo_groups(),
+        },
+        Language::default(),
+    );
+
+    let shell = row![nav::rail(ui, model.active), body]
+        .width(Length::Fill)
+        .height(Length::Fill);
+
+    let titled = column![titlebar_placeholder(ui), shell]
+        .width(Length::Fill)
+        .height(Length::Fill);
+
+    container(titled)
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .style(move |_theme| filled(ui.layer(MaterialLayer::Canvas)))
+        .into()
+}
+
+/// 演示模型（`pages_demo` example 与单测用；真页面走 `app/view.rs` 的 `AppState` 转换）。
+///
+/// 实例 / 下载 / 日志三页带演示数据，设置页仍是占位视觉。
+pub fn demo_model(screen: Screen, window_width: f32) -> Model {
+    let mut model = Model::new(screen, window_width, Some(screen.nav()));
+    match screen {
+        Screen::Instances => model.instances = instances::demo(),
+        Screen::Download => model.download = download::demo(unlucky_i18n::Lang::En.catalog()),
+        Screen::Content => model.content = content::demo(content::ContentKind::Mod, model.lang),
+        Screen::Logs => model.logs = logs::demo(model.lang),
+        Screen::Settings => {}
+    }
+    model
+}
+
+/// 标题栏留白带（高 = `LayoutMetrics::titlebar_height`）——**只给 [`app`] 的 harness 路径用**。
+///
+/// 产品路径的标题栏是 `shell::view_with_content` 画的那个真的（三个 caption 键 + 拖动热区），
+/// 见模块文档偏离 #7（M90 r2 已修）。
+fn titlebar_placeholder<'a>(ui: &'a Ui) -> Element<'a, Message> {
+    container(space::horizontal())
+        .width(Length::Fill)
+        .height(ui.metrics().titlebar_height)
+        .style(move |_theme| filled(ui.layer(MaterialLayer::Canvas)))
+        .into()
+}
diff --git a/crates/app-iced/src/pages/model.rs b/crates/app-iced/src/pages/model.rs
new file mode 100644
index 0000000..fdde68d
--- /dev/null
+++ b/crates/app-iced/src/pages/model.rs
@@ -0,0 +1,124 @@
+//! 视图模型：**presenter 快照 → 页面要画的东西**的唯一转换产物。
+//!
+//! ## 为什么页面不直接吃 presenter 的快照
+//!
+//! 页面层（`pages/*`）要能用**两套数据源**喂同一个渲染函数：
+//!
+//! | 数据源 | 谁转 | 用途 |
+//! |---|---|---|
+//! | presenter 的 `AppState` 快照 | `app/view.rs` 的自由函数 `model(&AppState, width, forced)` | 产品运行时的真页面 |
+//! | `pages/instances/data.rs` 的演示条目 | [`crate::pages::demo`] | M84 骨架图的可复现基线、`pages_demo` example |
+//!
+//! 如果页面直接读 `InstanceSummary`，演示数据就得先伪造成 `InstanceSummary`（含 core 语义字段），
+//! 基线图会跟着业务 DTO 的每次改动漂。所以中间加一层**纯展示字段**的模型：它只含「要画什么」。
+//!
+//! 文本都是 `String`/`&'static str`，没有框架类型——这一层可以纯单测（见 `pages/tests.rs`）。
+
+use unlucky_i18n::Lang;
+use unlucky_presenter::router::NavSection;
+
+use crate::app::components::interaction::Interaction;
+
+use super::content::Content;
+use super::logs::Logs;
+use super::{Download, Screen};
+
+/// 实例列表的一行（`ListItem` 的槽位：overline = 运行状态，headline = 名字，supporting = 版本）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Row {
+    /// 实例 id（点行 → `Route::Detail(id)`）
+    pub id: String,
+    /// 显示名
+    pub name: String,
+    /// 副文案（`1.20.4 · Fabric 0.16.5`）
+    pub supporting: String,
+    /// 运行状态（`None` = 空闲，不占 overline 槽位）
+    pub status: Option<String>,
+}
+
+/// 元信息卡：标签 + 值（`VERSION` / `Fabric 0.16.5`）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Meta {
+    /// 卡片上排的标签（`LabelMedium`）
+    pub label: String,
+    /// 卡片下排的值（`BodyMedium`）
+    pub value: String,
+}
+
+/// 详情列要画的东西。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Detail {
+    /// 实例 id（启动/停止命令要用它）
+    pub id: String,
+    /// 标题（`TitleLarge`）
+    pub name: String,
+    /// 标题下的一行（`BodySmall`）
+    pub subtitle: String,
+    /// 元信息网格（顺序 = 展示顺序；列数仍由 `layout::meta_columns` 决定）
+    pub meta: Vec<Meta>,
+    /// 正文档（演示数据有；真实快照没有对应字段时为 `None`）
+    pub note: Option<String>,
+    /// 运行状态行（`None` = 空闲，不占版面）
+    pub status: Option<String>,
+    /// 「Play」可用
+    pub can_launch: bool,
+    /// 「Stop」可用
+    pub can_stop: bool,
+}
+
+/// 实例页要画的东西。
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct Instances {
+    /// 列表列（顺序稳定 = 实例列表顺序）
+    pub rows: Vec<Row>,
+    /// 当前选中的实例详情（`None` = 没选中 → 空态）
+    pub detail: Option<Detail>,
+}
+
+/// 一屏的视图模型。
+#[derive(Debug, Clone, PartialEq)]
+pub struct Model {
+    /// 当前路由落在哪个页面上
+    pub screen: Screen,
+    /// 窗口宽度（**含外壳**：布局档位判据就是它）
+    pub window_width: f32,
+    /// 导航轨高亮项（`None` = 没有高亮，如 AI 独立页）
+    pub active: Option<NavSection>,
+    /// 实例页的数据（其它三页还是占位视觉，不读）
+    pub instances: Instances,
+    /// 下载页的数据（M94：版本列表 / 选中 / 安装进度，全部来自 presenter 快照）
+    pub download: Download,
+    /// 日志页的数据（M95：presenter 快照 → 日志行 + 诊断结论，见 [`super::logs`]）。
+    pub logs: Logs,
+    /// 内容库页的数据（M109：检索条件 / 命中项 / 装入闸门，见 [`super::content`]）。
+    pub content: Content,
+    /// 界面语言（M106）：页面文案走 i18n key，语言由 app 层决定后灌进来。
+    ///
+    /// 谁填：`app/state.rs` 的 `App::refresh_view`（`LangState::lang()` → `view::model(..)`），
+    /// 即「用户档位 / 系统 locale → 生效语言」这条链的结论。**不是**基线值：M95 以前这里是
+    /// `Lang::En` 占位，M106 之后中文系统上灌进来的是 `Lang::ZhCn`。
+    pub lang: Lang,
+    /// 取证用的强制交互态（`--force-state`）：`Some` 时页面里的控件按该态画。
+    ///
+    /// M90 r2（P3-1）之前这个开关只作用到 `shell` 回退路径，产品页是**静默失效**的；
+    /// 现在由 `app/view.rs` 把 `cli::ForcedState` 翻成 `Interaction` 灌进模型。
+    pub forced: Option<Interaction>,
+}
+
+impl Model {
+    /// 空模型（只有外壳参数，页面数据全空）——窄窗退化与空态的构造入口。
+    pub fn new(screen: Screen, window_width: f32, active: Option<NavSection>) -> Self {
+        Self {
+            screen,
+            window_width,
+            active,
+            instances: Instances::default(),
+            download: Download::loading(),
+            logs: Logs::default(),
+            // 演示模型也从这个空壳起步（`demo_model` 再按页面填数据）
+            content: super::content::demo(unlucky_presenter::dto::ContentKind::Mod, Lang::En),
+            lang: Lang::En,
+            forced: None,
+        }
+    }
+}
diff --git a/crates/app-iced/src/pages/nav.rs b/crates/app-iced/src/pages/nav.rs
new file mode 100644
index 0000000..f9dddd1
--- /dev/null
+++ b/crates/app-iced/src/pages/nav.rs
@@ -0,0 +1,204 @@
+//! 导航轨的**部件版**实现：`NAV` 表 + [`rail`]（宽 = 令牌 `nav_rail_width` = 88）。
+//!
+//! ## 两套 rail 的关系（M90 r3 订正，复审 P2-1；M99 把这张表从 `pages/mod.rs` 搬到这里）
+//!
+//! 产品路径（`app/view.rs`）走 `shell::view_with_content`，导航轨由 **`shell/nav.rs` 的手搓实现**画
+//! ——它与 M78 组件几何同值（宽 88、药丸 56×32），复审逐像素量过「r1 产品图（真组件 rail）vs r2
+//! 产品图（shell rail）在 y≥48 区域差异为 0」。组件版的 [`rail`] 只服务 `pages::app`
+//! （`pages_demo` 出口图、harness）与单测。
+//!
+//! 两边的守门是分开的：`shell/nav.rs` 自带 indicator 56×32 的单测，`pages/tests.rs` 守的是下面
+//! 这张表（表长 5 / 每一项都指向能高亮它的路由 / 第 5 项没有 section）。**将来哪边先漂没人拦**
+//! ——统一要泛型化 shell 的消息类型，成本大于收益；在那之前任何改 rail 几何的改动都要两处一起改
+//! 并各自跑守门（`pages/mod.rs` 偏离登记 #10）。
+
+use iced::Element;
+
+use unlucky_design::icons::IconKind;
+use unlucky_i18n::{Key, Lang};
+use unlucky_presenter::router::{NavSection, Route};
+
+use crate::app::components::navigation::drawer::{self, Navigation};
+use crate::app::components::navigation::navigation;
+use crate::theme::Ui;
+
+use super::Message;
+
+/// 导航轨的固定项：图标 + 文案 key + 目标路由（顺序 = 自上而下）。
+///
+/// 顺序与 `presenter::router::NavSection` 的声明顺序一致，改这里等于改导航栏。
+///
+/// 第 3 列是 [`Key`] 而不是字面量（M108）：导航文案归目录管，`pages_demo` 出的图与将来的中文
+/// 界面读的是同一份表，不会出现「页面翻译了、导航还是硬编码英文」。
+///
+/// **显示名 ≠ 标识符**：`Key::NavDownload` 这条说的是「版本管理 / Versions」，而它指向的仍是
+/// `Route::Download`（用户令只改显示层，标识符改名后置）。
+///
+/// 表里存的是**收起态（88）的 key**；展开态（240）要对 [`label_key`] 过一道才换全名。
+/// 可见性是 `pub(crate)`：`pages/tests.rs` 的三条断言读它（M99 从 `pages/mod.rs` 搬出来时，
+/// 它从「模块私有」变成「crate 内可见」，断言一条没动、强度也没降）。
+pub(crate) const NAV: [(Option<NavSection>, IconKind, Key, Route); 5] = [
+    (
+        Some(NavSection::Instances),
+        IconKind::Instances,
+        Key::NavInstances,
+        Route::Instances,
+    ),
+    (
+        Some(NavSection::Download),
+        IconKind::Download,
+        Key::NavDownload,
+        Route::Download,
+    ),
+    (
+        Some(NavSection::Logs),
+        IconKind::Logs,
+        Key::NavLogs,
+        Route::Logs,
+    ),
+    (
+        Some(NavSection::Settings),
+        IconKind::Settings,
+        Key::NavSettings,
+        Route::Settings,
+    ),
+    // AI 独立页没有导航高亮项（`Route::nav()` 对它返回 `None`）；文案用 M106 给导航项新开的
+    // `Key::NavAi`（与产品路径的 `shell/nav.rs` 同一条 key，两条 rail 不许各借一个词）。
+    (None, IconKind::Ai, Key::NavAi, Route::Agent),
+];
+
+/// 这一项在当前宽度态下的文案 key。
+///
+/// `expanded` = D33 的 240 展开抽屉（用全名），`false` = 88 收起轨（用短名）。产品路径**当前只有
+/// 88 收起态**，所以调用点只出现 `false`。
+///
+/// **为什么是 bool 参数而不是 `enum NavWidth { Rail, Drawer }`**：D33 的抽屉还没有渲染路径，
+/// 枚举里那个 `Drawer` 变体在产品代码里永远构造不到，`-D warnings` 会按 `dead_code` 把它拦下来
+/// （M108 第一版就是这么红的）。参数化之后没有「构造不到的状态」，切换点仍只有这一处。
+pub(crate) const fn label_key(label: Key, expanded: bool) -> Key {
+    if expanded && matches!(label, Key::NavDownload) {
+        Key::NavDownloadExpanded
+    } else {
+        label
+    }
+}
+
+/// 导航轨：**真组件**（`components::navigation` 的 rail 形态，宽 = 令牌 `nav_rail_width` = 88）。
+///
+/// M84 这里是一条留白带；M90 换成 M78 的 `NavigationRail`，于是「导航项 → 路由」是真的可点。
+///
+/// 语言暂时固定 [`Lang::En`]：组件版 rail 的调用点只有 `pages/mod.rs` 的 `nav::rail(ui, model.active)`，
+/// 那里还没把 `Model.lang` 传进来（`pages/mod.rs` 不在 M108 的 scope 内）。文案本身已经走 [`Key`]，
+/// 接线时只改这一行——产品路径那边同一笔欠账归 M106（它给 `shell/nav.rs` 接 i18n）。
+pub(super) fn rail<'a>(ui: &'a Ui, active: Option<NavSection>) -> Element<'a, Message> {
+    let catalog = Lang::En.catalog();
+    let mut group = drawer::NavGroup::new();
+
+    for (section, icon, label, route) in NAV {
+        // 88 收起轨 = 短名（240 展开抽屉才用全名，见 [`label_key`]）
+        let label = label_key(label, false);
+        let mut item = drawer::NavItem::new(catalog.text(label), icon, Message::Navigate(route));
+        if section.is_some() && active == section {
+            item = item.selected();
+        }
+        group = group.item(item);
+    }
+
+    navigation(ui, Navigation::rail().group(group))
+}
+
+#[cfg(test)]
+mod tests {
+    //! 导航表与文案的守门（M108）。
+    //!
+    //! 这条断言原先挂在 `pages/tests.rs`，但那份文件在 M102 合并后是 464 行、撞了「单文件 ≤400 行」
+    //! 的硬门禁（`components/gate.rs` 按全仓判红），于是按「谁的数据谁守」挪到本文件——`NAV` 表在
+    //! 这里，守门也在这里，强度一条没降。
+
+    use super::*;
+
+    /// **M108**：这一页对外叫「版本管理」，代码里仍是 `Route::Download`。
+    ///
+    /// 用户令（2026-11-04）只要**显示层**改名：全仓重命名标识符会与在途的多条线全面撞车，
+    /// 所以 `Route::Download` / `NavSection::Download` / `Screen::Download` / 文件名一个都不动。
+    ///
+    /// 英文有两个不同长度的名字，**是刻意的**（见 `catalog/nav.rs` 的「两条 key」一节）：
+    /// 88px 收起轨放不下 `Version management`（≈101px），用短名 `Versions`；页标题与 240 展开抽屉
+    /// 用全名。中文两处都是「版本管理」（≈48px，放得下就不缩）。
+    ///
+    /// **抓得住**：① 导航项或页标题又写回「下载」「Download」；② 88 轨上误用全名（会截断/换行）；
+    /// ③ 副标题退回「只说下载」；④ 中文被「为了对称」砍短。**抓不住**：产品路径的导航轨
+    /// （`shell/nav.rs` 是另一套手搓实现，它自己有一条同样的断言）、真画出来会不会截断（那要出图）、
+    /// 中文目录在真机上的字体（截图通道固定 En，见 M108 报告与 finding）。
+    #[test]
+    fn the_download_route_is_presented_as_version_management() {
+        let en = Lang::En.catalog();
+        let zh = Lang::ZhCn.catalog();
+
+        let entry = NAV
+            .iter()
+            .find(|entry| entry.3 == Route::Download)
+            .expect("导航表里有版本管理页那一项");
+        assert_eq!(entry.2, Key::NavDownload, "导航文案走目录，不写字面量");
+
+        // 88 收起轨 = 短名；240 展开与页标题 = 全名（中文两处同值）
+        assert_eq!(en.text(Key::NavDownload), "Versions");
+        assert_eq!(en.text(Key::NavDownloadExpanded), "Version management");
+        assert_eq!(en.text(Key::DownloadTitle), "Version management");
+        assert_eq!(zh.text(Key::NavDownload), "版本管理");
+        assert_eq!(zh.text(Key::NavDownloadExpanded), "版本管理");
+        assert_eq!(zh.text(Key::DownloadTitle), "版本管理");
+        assert_eq!(
+            label_key(Key::NavDownload, false),
+            Key::NavDownload,
+            "88 收起态必须用短名"
+        );
+        assert_eq!(
+            label_key(Key::NavDownload, true),
+            Key::NavDownloadExpanded,
+            "240 展开态换全名"
+        );
+        assert_eq!(
+            label_key(Key::NavLogs, true),
+            Key::NavLogs,
+            "其余四项两态同一条 key"
+        );
+
+        // 目录里凡是指向这一页的文案都不许再说「下载」。唯一豁免是 `Downloading files`：
+        // 那是安装流程里真在传文件的那一步，说的是当时的动作、不是页面身份。
+        let page_keys = Key::ALL.iter().filter(|key| {
+            (key.name().starts_with("Download") && **key != Key::DownloadStageDownloading)
+                || **key == Key::NavDownload
+                || **key == Key::NavDownloadExpanded
+        });
+        let mut checked = 0;
+        for key in page_keys {
+            assert!(
+                !en.text(*key).to_ascii_lowercase().contains("download"),
+                "{} 的英文文案还在说「下载」：{}",
+                key.name(),
+                en.text(*key)
+            );
+            assert!(
+                !zh.text(*key).contains("下载"),
+                "{} 的中文文案还在说「下载」：{}",
+                key.name(),
+                zh.text(*key)
+            );
+            checked += 1;
+        }
+        assert!(checked > 20, "只扫到 {checked} 条，守门形同虚设");
+
+        // 副标题要讲这个页面「管什么」（版本 + 加载器），不是「能下载什么」
+        let subtitle_en = en.text(Key::DownloadSubtitle);
+        let subtitle_zh = zh.text(Key::DownloadSubtitle);
+        assert!(
+            subtitle_en.contains("versions") && subtitle_en.contains("loaders"),
+            "副标题要提到版本与加载器：{subtitle_en}"
+        );
+        assert!(
+            subtitle_zh.contains("版本") && subtitle_zh.contains("加载器"),
+            "副标题要提到版本与加载器：{subtitle_zh}"
+        );
+    }
+}
diff --git a/crates/app-iced/src/pages/screen.rs b/crates/app-iced/src/pages/screen.rs
new file mode 100644
index 0000000..02a724a
--- /dev/null
+++ b/crates/app-iced/src/pages/screen.rs
@@ -0,0 +1,89 @@
+//! 页面枚举 `Screen` 与它的三张对照表（版面 / 导航项 / 路由；M101 r2 从 `pages/mod.rs` **原样搬出**）。
+//!
+//! 为什么拆：合并 M100/M101 之后 `pages/mod.rs` 是 397 行，只剩 3 行余量。纯搬移，路径靠
+//! `pages/mod.rs` 的 `pub use screen::Screen;` 保持不变（`pages::Screen`）。
+
+use unlucky_presenter::router::{NavSection, Route};
+
+use super::layout::PaneKit;
+
+/// 四个页面。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Screen {
+    /// 实例（list-detail）。
+    Instances,
+    /// **版本管理**（原下载页；单列页，但正文自己切三栏：类型 / 主版本 / 列表）。
+    Download,
+    /// 内容库（M109）：整合包 / Mod / 资源包 / 光影。
+    Content,
+    /// 设置（supporting-pane）。
+    Settings,
+    /// 日志（单列，两行页头）。
+    Logs,
+}
+
+impl Screen {
+    /// 全部页面（截图矩阵按这个顺序铺）。
+    pub const ALL: [Screen; 5] = [
+        Screen::Instances,
+        Screen::Download,
+        Screen::Content,
+        Screen::Settings,
+        Screen::Logs,
+    ];
+
+    /// 稳定 slug（命令行参数与文件名用）。
+    pub const fn slug(self) -> &'static str {
+        match self {
+            Screen::Instances => "instances",
+            Screen::Download => "download",
+            Screen::Content => "content",
+            Screen::Settings => "settings",
+            Screen::Logs => "logs",
+        }
+    }
+
+    /// 反向解析（`--screen=instances`）。
+    pub fn from_slug(slug: &str) -> Option<Self> {
+        Self::ALL.into_iter().find(|screen| screen.slug() == slug)
+    }
+
+    /// 页面声明的**最宽**版面；实际用哪个由 [`layout::resolve`](super::layout) 按窗口宽度决定。
+    pub const fn kit(self) -> PaneKit {
+        match self {
+            Screen::Instances => PaneKit::ListDetail,
+            Screen::Settings => PaneKit::Supporting,
+            // 内容库自带三栏（`pages/content/layout.rs`），版面基座仍是单列：
+            // 它的三栏是「页内栏」而不是 layout 模块那三种整页版面。
+            Screen::Download | Screen::Content | Screen::Logs => PaneKit::Single,
+        }
+    }
+
+    /// 路由落在哪一页上（`None` = 这一页还没有实现，由 app 层决定回退）。
+    ///
+    /// `Route::Detail(_)` 仍属实例页（窄窗时是「整页切换」的那一屏）。
+    pub fn of(route: &Route) -> Option<Self> {
+        Some(match route {
+            Route::Instances | Route::Detail(_) => Screen::Instances,
+            Route::Download => Screen::Download,
+            Route::Content => Screen::Content,
+            Route::Logs => Screen::Logs,
+            Route::Settings => Screen::Settings,
+            // 账户页（M114）不是本枚举四页之一：它由 `pages::account` 自己的树画
+            // （路由在 `app/view.rs` 里先被拦下），harness 的单页矩阵也不含它。
+            Route::Accounts => return None,
+            Route::Agent => return None,
+        })
+    }
+
+    /// 该页高亮的导航项（与 `Route::nav` 同源，但这里是「按页问」的口径）。
+    pub const fn nav(self) -> NavSection {
+        match self {
+            Screen::Instances => NavSection::Instances,
+            // M109（B1 裁定）：内容库与版本管理共用同一条导航轨项
+            Screen::Download | Screen::Content => NavSection::Download,
+            Screen::Logs => NavSection::Logs,
+            Screen::Settings => NavSection::Settings,
+        }
+    }
+}
diff --git a/crates/app-iced/src/pages/settings/ai_about.rs b/crates/app-iced/src/pages/settings/ai_about.rs
new file mode 100644
index 0000000..6d5aa62
--- /dev/null
+++ b/crates/app-iced/src/pages/settings/ai_about.rs
@@ -0,0 +1,39 @@
+//! 设置页「AI / About」分组：**预留**（页面上还没有这个分组，左列 4 项里没有它）。
+//!
+//! 为什么先留一个空文件：设置页正文接下来由四条线并行接（java / download / language+appearance /
+//! ai+about）。文件位置先占好，四条线就不会在同一天抢同一个新文件名；本文件现在是**只有文档**的
+//! 空模块（不产生任何代码，`-D warnings` 不会红）。
+//!
+//! ## 接线步骤（ai+about 线照做）
+//!
+//! 1. 在本文件写 `pub(super) const GROUP: Group = Group { … }`，形状抄 `java.rs`；
+//! 2. 到 `settings/mod.rs` 的 `GROUPS` 里加一行 `ai_about::GROUP,`，并把数组长度 `4` 改成 `5`；
+//! 3. 文案 key 写进 `crates/i18n/src/catalog/settings/ai.rs`（那边已经接进装配链，同样只改一个文件）。
+//!
+//! 界面上「多了一组」这件事本身是行为变化，所以**只在真有那一组内容时才做**，不要为占位先加。
+//!
+//! ## M101 起本文件还装本线的状态与消息口
+//!
+//! - 状态：[`State`]（`Groups.ai_about` 的载荷，加字段只改本文件）；
+//! - 消息：[`Message`]（落点 `app/update/settings/ai_about.rs`）。
+//!
+//! 上第 5 组时**额外**要动的共享文件（按上面的步骤 2 + 测试装配）：
+//! - `settings/mod.rs` 的 `GROUPS`（加一行，长度 +1）；
+//! - `settings/tests/mod.rs` 顶部加一行 `mod ai_section;`（新测试文件不挂 `mod` 就不编译），
+//!   并且左列顺序那条字面量断言会红——那是刻意的（页面上多一组就是观感变了，要人确认）。
+//!
+//! 注意 i18n 那边是按**分组**命名的，文案文件叫 `ai.rs` 而不是 `ai_about.rs`。
+
+/// AI / About 分组的运行期状态（M101 r2：**只归 ai+about 线**）。
+///
+/// 加字段只改本文件：`Groups` 只认 `Groups.ai_about` 这一个字段。
+#[derive(Debug, Default)]
+pub struct State {}
+
+/// AI / About 线的消息（**只归本线**）。
+///
+/// 首版是空枚举：这一条线的分组还没上页面。空枚举的好处是
+/// `app/update/settings/ai_about.rs` 里的 `match message {}` 天然穷尽——加了变体不接线就报
+/// E0004，不会静默。
+#[derive(Debug, Clone)]
+pub enum Message {}
diff --git a/crates/app-iced/src/pages/settings/appearance.rs b/crates/app-iced/src/pages/settings/appearance.rs
new file mode 100644
index 0000000..6d98023
--- /dev/null
+++ b/crates/app-iced/src/pages/settings/appearance.rs
@@ -0,0 +1,40 @@
+//! 设置页「Appearance」分组：演示行 + **真控件的接线**（M93 / APPEARWIRE）。
+//!
+//! 这一组是设置页唯一接了真控件的：`body = Some(body)`，`body` 直接调
+//! `crate::pages::appearance::section`。`settings/mod.rs` 只按 `group.body` 分发，**不认识
+//! 「Appearance」这个名字**；分组在左列的下标仍由 `crate::pages::appearance::APPEARANCE_GROUP`
+//! 声明，`settings/tests/mod.rs` 拿它和本文件比对（顺序被调换会红）。
+//!
+//! **这一组归 language+appearance 线**：真控件的实现全在 `pages/appearance/section.rs`（本文件只负责
+//! 把它挂进注册表），所以改控件时不用碰设置页目录。
+//!
+//! M101 r2：本组的渲染器签名改成收 [`States`]（组状态 + 外观状态），于是「这一组要读哪些状态」
+//! 由本文件决定——`settings/mod.rs` 不再认识 `appearance::State`。
+
+use iced::Element;
+use unlucky_design::icons::IconKind;
+
+use crate::theme::Ui;
+
+use super::{Group, Message, States};
+
+/// Appearance 分组。`body` 指着 [`body`]（它再转给 `pages/appearance/section.rs` 的真控件）；
+/// 没有外观运行期状态时（harness / `pages_demo`）返回 `None`，由 `form` 退回下面的演示行。
+pub(super) const GROUP: Group = Group {
+    name: "Appearance",
+    icon: IconKind::Sidebar,
+    rows: &[
+        ("Density", "Comfortable"),
+        ("Corner style", "Follow system"),
+        ("Motion", "Full"),
+        ("Text scale", "100%"),
+    ],
+    body: Some(body),
+};
+
+/// 本组的真控件渲染器：有外观状态就画真控件（M93），没有（harness）返回 `None`。
+fn body<'a>(ui: &'a Ui, states: States<'a>) -> Option<Element<'a, Message>> {
+    states
+        .appearance
+        .map(|state| crate::pages::appearance::section(ui, state))
+}
diff --git a/crates/app-iced/src/pages/settings/download.rs b/crates/app-iced/src/pages/settings/download.rs
new file mode 100644
index 0000000..b3d8a09
--- /dev/null
+++ b/crates/app-iced/src/pages/settings/download.rs
@@ -0,0 +1,36 @@
+//! 设置页「Downloads」分组：首选源 / 并发数 / 校验（演示行）。
+//!
+//! **这一组归 download 线**：接真控件时在本文件把 `body` 换成 `Some(download::body)`（渲染器也写在本文件），
+//! `settings/mod.rs` 的注册表不用动。
+//!
+//! 注意与下载页（`pages/download*`）的区别：那是「装哪个版本」，这里是「怎么下」的默认值。
+
+use unlucky_design::icons::IconKind;
+
+use super::Group;
+
+/// Downloads 分组。
+pub(super) const GROUP: Group = Group {
+    name: "Downloads",
+    icon: IconKind::Download,
+    rows: &[
+        ("Preferred source", "Automatic (region)"),
+        ("Concurrency", "8 threads"),
+        ("Verify checksums", "On"),
+    ],
+    body: None,
+};
+
+/// Downloads 分组的运行期状态（M101 r2：**只归 download 线**）。
+///
+/// 加字段只改本文件：`Groups` 只认 `Groups.download` 这一个字段。
+#[derive(Debug, Default)]
+pub struct State {}
+
+/// Downloads 分组的消息（M101：**只归 download 线**，加变体只改本文件）。
+///
+/// 落点是 `app/update/settings/download.rs`；`pages/mod.rs` 与 `page_messages.rs` 都不用动（它们只认
+/// [`GroupMessage`](super::GroupMessage)）。异步结果（例如「测这个源可用」）在自己那条落点里构造
+/// `Message::Page(pages::Message::Settings(GroupMessage::Download(…)))` 回来即可。
+#[derive(Debug, Clone)]
+pub enum Message {}
diff --git a/crates/app-iced/src/pages/settings/frame.rs b/crates/app-iced/src/pages/settings/frame.rs
new file mode 100644
index 0000000..438744d
--- /dev/null
+++ b/crates/app-iced/src/pages/settings/frame.rs
@@ -0,0 +1,219 @@
+//! 设置页骨架：页头、左列分组导航、表单列的滚动区、演示卡片、空态位。
+//!
+//! ## 为什么这里还再导出一批 `pages::frame` 的名字
+//!
+//! M99 拆目录时立的硬要求是**纯搬移**：调用点一字不改。设置页原来的代码从 `super::frame` 取词
+//! （`frame::text_role` / `frame::card` / `frame::ICON_PX` …）；拆成目录后 `frame` 这个名字落到了
+//! 本文件上，于是把用到的那几件**再导出**一次，`mod.rs` / `tests.rs` 的调用点就能原样保留。
+//! 这不是新 API，只是一条转发（新增控件仍归 [`crate::pages::frame`]）。
+
+pub(super) use super::super::frame::{
+    card, divider, empty_state, glyph_box, left_aligned, page, panes, scroll_style, single_column,
+    text_action, text_role, Header, ICON_PX, SCROLLBAR_MARGIN, SCROLLBAR_WIDTH,
+};
+
+use iced::widget::{column, container, mouse_area, row, scrollable};
+use iced::{Alignment, Background, Border, Element, Length, Padding};
+
+use unlucky_design::color::Role;
+use unlucky_design::component_map::Component;
+use unlucky_design::elevation::MaterialLayer;
+use unlucky_design::icons::IconKind;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+use unlucky_i18n::{Key, Lang};
+
+use crate::pages::appearance::Change;
+use crate::pages::{Action, Message};
+use crate::theme::Ui;
+
+use super::Group;
+
+/// 空态位高度：给图标块 96 + 标题 + 副文案 + 按钮留够空间（`[估]`，按 12b §15 的元素最小高度累加）。
+const EMPTY_SLOT_HEIGHT: f32 = 320.0;
+
+/// 页头：标题 + 副标题 + 两个占位动作。
+///
+/// M106：三条文案走 catalog（`lang` 由 `settings::view` 传下来）。页标题复用 `NavSettings`——
+/// 左列与页头说的是同一件事，不该有第二条译文。
+pub(super) fn header<'a>(ui: &'a Ui, lang: Lang) -> Header<'a> {
+    let catalog = lang.catalog();
+    Header::new(catalog.text(Key::NavSettings))
+        .subtitle(catalog.text(Key::SettingsSubtitle))
+        .action(text_action(
+            ui,
+            catalog.text(Key::SettingsResetSection),
+            Action::ResetSection,
+        ))
+        .action(text_action(
+            ui,
+            catalog.text(Key::SettingsSave),
+            Action::SaveSettings,
+        ))
+}
+
+// --------------------------------------------------------------- 侧列
+
+/// 左列分组导航（supporting-pane 的辅助列，宽 = 令牌 `nav_drawer_width` = 240）。
+pub(super) fn group_nav<'a>(ui: &'a Ui, selected: usize, lang: Lang) -> Element<'a, Message> {
+    let catalog = lang.catalog();
+    let items = column(
+        super::GROUPS
+            .iter()
+            .enumerate()
+            .map(|(index, group)| {
+                let label = super::GROUP_LABELS
+                    .get(index)
+                    .map_or(group.name, |key| catalog.text(*key));
+                group_item(ui, group, label, index, index == selected)
+            })
+            .collect::<Vec<_>>(),
+    )
+    .spacing(ui.space(Space::X1))
+    .padding(Padding::from([ui.space(Space::X2), ui.space(Space::X2)]))
+    .width(Length::Fill);
+
+    container(items)
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .style(move |_theme| container::Style {
+            background: Some(Background::Color(ui.layer(MaterialLayer::Card))),
+            border: Border {
+                radius: ui.radius_dp(ShapeScale::Large),
+                ..Border::default()
+            },
+            ..container::Style::default()
+        })
+        .into()
+}
+
+fn group_item<'a>(
+    ui: &'a Ui,
+    group: &'a Group,
+    label: &'a str,
+    index: usize,
+    selected: bool,
+) -> Element<'a, Message> {
+    let spec = Component::NavigationItem.spec();
+    let height = ui.metrics().row_height;
+
+    let content_color = if selected {
+        ui.color(Role::OnSecondaryContainer)
+    } else {
+        ui.color(Role::OnSurfaceVariant)
+    };
+
+    let inner = row![
+        glyph_box(group.icon, content_color, ICON_PX),
+        text_role(ui, spec.text, false, label, content_color),
+    ]
+    .spacing(ui.space(Space::X3))
+    .width(Length::Fill)
+    .align_y(Alignment::Center);
+
+    let pill = container(inner)
+        .width(Length::Fill)
+        .height(height)
+        .padding(Padding::from([0.0, ui.space(Space::X3)]))
+        .align_y(Alignment::Center)
+        .style(move |_theme| container::Style {
+            background: selected.then(|| Background::Color(ui.color(Role::SecondaryContainer))),
+            border: Border {
+                radius: ui.radius(ShapeScale::Full, height),
+                ..Border::default()
+            },
+            ..container::Style::default()
+        });
+
+    // 点选切分组：走页面自己的 `Message::Appearance(SelectGroup)`（只改视图状态，不落盘）。
+    mouse_area(pill)
+        .on_press(Message::Appearance(Change::SelectGroup(index)))
+        .into()
+}
+
+// --------------------------------------------------------------- 表单列
+
+/// 表单列的滚动区：只有正文滚，页头不动（与实例页列表列同一套口径）。
+///
+/// 「外观」分组有 7 个控件 + 最多 3 行诊断，1180×760 下会超出可视区，所以这一层是必需的。
+pub(super) fn scroll<'a>(
+    ui: &'a Ui,
+    content: impl Into<Element<'a, Message>>,
+) -> Element<'a, Message> {
+    scrollable(content)
+        .direction(scrollable::Direction::Vertical(
+            scrollable::Scrollbar::new()
+                .width(SCROLLBAR_WIDTH)
+                .scroller_width(SCROLLBAR_WIDTH)
+                .margin(SCROLLBAR_MARGIN),
+        ))
+        .height(Length::Fill)
+        .style(scroll_style(ui))
+        .into()
+}
+
+/// 演示行构成的一组设置 = 一张卡，行间 1px 分隔线（M3 设置列表的常规做法）。
+///
+/// 已经接了真控件的分组（`GROUP.body` 是 `Some`）不走这里。
+pub(super) fn demo_card<'a>(
+    ui: &'a Ui,
+    rows: &'a [(&'static str, &'static str)],
+) -> Element<'a, Message> {
+    let mut stacked = column![].spacing(0.0).width(Length::Fill);
+
+    for (index, (label, value)) in rows.iter().enumerate() {
+        if index > 0 {
+            stacked = stacked.push(divider(ui));
+        }
+        stacked = stacked.push(setting_row(ui, label, value));
+    }
+
+    card(ui, stacked)
+}
+
+fn setting_row<'a>(ui: &'a Ui, label: &'a str, value: &'a str) -> Element<'a, Message> {
+    let height = ui.metrics().control_height + Space::X2.dp();
+
+    row![
+        container(text_role(
+            ui,
+            TypeRole::BodyMedium,
+            false,
+            label,
+            ui.color(Role::OnSurface),
+        ))
+        .width(Length::Fill)
+        .align_y(Alignment::Center),
+        text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            value,
+            ui.color(Role::OnSurfaceVariant),
+        ),
+    ]
+    .height(height)
+    .width(Length::Fill)
+    .align_y(Alignment::Center)
+    .into()
+}
+
+/// 空态位：没有逐实例覆盖时的样子（12b §15 的口径）。
+pub(super) fn overrides_empty<'a>(ui: &'a Ui, lang: Lang) -> Element<'a, Message> {
+    let catalog = lang.catalog();
+    container(empty_state(
+        ui,
+        IconKind::Instances,
+        catalog.text(Key::SettingsOverridesEmptyTitle),
+        catalog.text(Key::SettingsOverridesEmptyBody),
+        vec![text_action(
+            ui,
+            catalog.text(Key::SettingsOverridesAdd),
+            Action::AddOverride,
+        )],
+    ))
+    .width(Length::Fill)
+    .height(Length::Fixed(EMPTY_SLOT_HEIGHT))
+    .into()
+}
diff --git a/crates/app-iced/src/pages/settings/general.rs b/crates/app-iced/src/pages/settings/general.rs
new file mode 100644
index 0000000..9ece9c3
--- /dev/null
+++ b/crates/app-iced/src/pages/settings/general.rs
@@ -0,0 +1,225 @@
+//! 设置页「General」分组：语言选择器 + 主题 / 启动页 / 关闭按钮（M106 接真控件）。
+//!
+//! **这一组归 language+appearance 线**（M101 的分线口径）。
+//!
+//! ## 这一组为什么特殊
+//!
+//! 它**不走** `Group::body`：那个渲染器的签名是 `fn(&Ui, States) -> Option<Element>`，`States` 只有
+//! `appearance` + `groups` 两格，装不下「当前语言档位 + 生效语言」。语言行要的两件在
+//! `pages::Language` 里，由 `pages::settings::view` 的 `language` 形参一路递进来、`form` 按下标
+//! 转交 [`body`]；所以 `GROUP.body` 仍是 `None`，`tests/mod.rs` 那条「只有外观组带真控件」照样成立。
+//!
+//! ## 语言切换**没有**走 M101 的 `GroupMessage` 投递口（偏离，已登记）
+//!
+//! `settings/mod.rs` 的文档说本线要加消息就加到 `settings/language_appearance.rs` 的 `Message` 上。
+//! M106 走的是 `pages::Message::Language(choice)` 这条独立增量，理由：语言档位不是「某一组的状态」，
+//! 它要**落盘**（`ui.language`）+ **重建整棵视图模型**（目录是 `pages::Model` 的一部分），而落点
+//! `app/update/settings/language_appearance.rs` 与消息口 `language_appearance.rs` 都不在本 mission 的
+//! scope 内。代价：`page_messages.rs` 多一支（那是 M101 想收掉的共享锚点）。**收口方向**：等本线
+//! 再动设置页时，把 `Message::Language` 折进 `GroupMessage::LanguageAppearance(SetChoice)`，并把
+//! `pages/mod.rs` 的这支删掉——finding 已登记。
+//!
+//! ## 语言行的三个事实
+//!
+//! 1. **选中态显示的是档位**（跟随系统 / 简体中文 / 英文），不是「猜出来的语言」——用户点过什么
+//!    就得画回什么，否则「我明明选了跟随系统」这件事在界面上无从确认；
+//! 2. **旁边回显生效语言**（`界面当前使用：简体中文`）：中文系统 + 跟随系统时，这一行是「界面
+//!    真的用了中文」的唯一可见证据（用户报的 bug 正是「识别到了但没用上」）；
+//! 3. **文案全部走 catalog**（[`Key`]），三档选项名跟着界面语言走（见 `catalog/general.rs`
+//!    的头注释：为什么不写语言自称）。
+//!
+//! ## 其余三行仍只读
+//!
+//! 主题 / 启动页 / 关闭按钮还没有后端（`pages::Action` 里是占位动作），所以它们是**只读行**；
+//! 但标签与取值已经进 catalog，中文界面下不会再冒出英文。
+//!
+//! 分组元数据只有一份（这里的 [`GROUP`]）：`settings/mod.rs` 的 `GROUPS` 直接引用它。
+
+use iced::widget::{button, column, container, row};
+use iced::{Alignment, Background, Border, Element, Length, Padding, Shadow, Theme as IcedTheme};
+
+use unlucky_design::color::{Role, StateLayer};
+use unlucky_design::icons::IconKind;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+use unlucky_i18n::catalog::Key;
+use unlucky_i18n::LangChoice;
+
+use crate::pages::{frame, Language, Message};
+use crate::theme::Ui;
+
+use super::frame::{card, divider};
+use super::Group;
+
+/// General 分组（左列名固定英文：左列是**导航**，与导航轨同源，不进 catalog）。
+pub(super) const GROUP: Group = Group {
+    name: "General",
+    icon: IconKind::Settings,
+    // 只给 harness（`pages_demo` 走 `appearance: None` 时）用的演示行：产品路径走 [`body`]。
+    // 语言那一行**不在**这里——它的值是要跟着语言变的，写死在静态表里就是用户看到的那条假值。
+    rows: &[
+        ("Theme", "Follow system"),
+        ("Startup page", "Instances"),
+        ("Close button", "Exit to tray"),
+    ],
+    body: None,
+};
+
+/// 这一组的正文（**产品路径**）。
+pub(super) fn body<'a>(ui: &'a Ui, language: Language) -> Element<'a, Message> {
+    let catalog = language.effective.catalog();
+    let mut stacked = column![].spacing(0.0).width(Length::Fill);
+    stacked = stacked.push(language_row(ui, language));
+
+    // 主题 / 启动页 / 关闭按钮：还没有后端，只读；文案已经进 catalog。
+    for (label, value) in [
+        (Key::SettingsTheme, Key::SettingsThemeFollowSystem),
+        (Key::SettingsStartupPage, Key::SettingsStartupInstances),
+        (Key::SettingsCloseButton, Key::SettingsCloseToTray),
+    ] {
+        stacked = stacked.push(divider(ui));
+        stacked = stacked.push(setting_row(ui, catalog.text(label), catalog.text(value)));
+    }
+
+    card(ui, stacked)
+}
+
+/// 语言行：标题 + 生效语言回显 + 三档互斥按钮 + 一句说明。
+fn language_row<'a>(ui: &'a Ui, language: Language) -> Element<'a, Message> {
+    let catalog = language.effective.catalog();
+    let effective = LangChoice::Fixed(language.effective).label_key();
+
+    let head = row![
+        container(frame::text_role(
+            ui,
+            TypeRole::BodyMedium,
+            false,
+            catalog.text(Key::SettingsLanguage),
+            ui.color(Role::OnSurface),
+        ))
+        .width(Length::Fill)
+        .align_y(Alignment::Center),
+        frame::text_role_owned(
+            ui,
+            TypeRole::LabelLarge,
+            true,
+            catalog.render(
+                Key::SettingsLanguageEffective,
+                &[("language", catalog.text(effective))],
+            ),
+            ui.color(Role::OnPrimaryFixedVariant),
+        ),
+    ]
+    .width(Length::Fill)
+    .align_y(Alignment::Center);
+
+    let chips = row(LangChoice::ALL
+        .iter()
+        .map(|choice| {
+            chip(
+                ui,
+                catalog.text(choice.label_key()),
+                *choice == language.choice,
+                *choice,
+            )
+        })
+        .collect::<Vec<_>>())
+    .spacing(ui.space(Space::X1))
+    .align_y(Alignment::Center);
+
+    column![
+        head,
+        chips,
+        frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            catalog.text(Key::SettingsLanguageHint),
+            ui.color(Role::OnSurfaceVariant),
+        ),
+    ]
+    .spacing(ui.space(Space::X1))
+    .width(Length::Fill)
+    .padding(Padding::from([ui.space(Space::X2), 0.0]))
+    .into()
+}
+
+/// 一个只读的「标签 + 取值」行（与 `frame::demo_card` 的一行同高同排版）。
+fn setting_row<'a>(ui: &'a Ui, label: &'a str, value: &'a str) -> Element<'a, Message> {
+    let height = ui.metrics().control_height + Space::X2.dp();
+
+    row![
+        container(frame::text_role(
+            ui,
+            TypeRole::BodyMedium,
+            false,
+            label,
+            ui.color(Role::OnSurface),
+        ))
+        .width(Length::Fill)
+        .align_y(Alignment::Center),
+        frame::text_role(
+            ui,
+            TypeRole::BodySmall,
+            false,
+            value,
+            ui.color(Role::OnSurfaceVariant),
+        ),
+    ]
+    .height(height)
+    .width(Length::Fill)
+    .align_y(Alignment::Center)
+    .into()
+}
+
+/// 一个互斥按钮（选中态 `SecondaryContainer`，未选中透明 + `OnSurfaceVariant`）。
+///
+/// 与 `pages/appearance/section.rs` 的 `choice` 同款，但文案来自 catalog（那份是英文基线）。
+fn chip<'a>(ui: &'a Ui, text: &'a str, selected: bool, choice: LangChoice) -> Element<'a, Message> {
+    let height = ui.metrics().control_height;
+    let content_color = if selected {
+        ui.color(Role::OnSecondaryContainer)
+    } else {
+        ui.color(Role::OnSurfaceVariant)
+    };
+
+    button(
+        container(frame::text_role(
+            ui,
+            TypeRole::LabelLarge,
+            selected,
+            text,
+            content_color,
+        ))
+        .align_y(Alignment::Center),
+    )
+    .height(height)
+    .padding(Padding::from([0.0, ui.space(Space::X3)]))
+    .style(move |_theme: &IcedTheme, status| {
+        let background = if selected {
+            Some(Background::Color(ui.color(Role::SecondaryContainer)))
+        } else if matches!(status, button::Status::Hovered | button::Status::Pressed) {
+            Some(Background::Color(ui.state_over(
+                StateLayer::Hover,
+                Role::OnSurface,
+                Role::Surface,
+            )))
+        } else {
+            None
+        };
+
+        button::Style {
+            background,
+            text_color: content_color,
+            border: Border {
+                radius: ui.radius(ShapeScale::Full, height),
+                ..Border::default()
+            },
+            shadow: Shadow::default(),
+            snap: true,
+        }
+    })
+    .on_press(Message::Language(choice))
+    .into()
+}
diff --git a/crates/app-iced/src/pages/settings/java.rs b/crates/app-iced/src/pages/settings/java.rs
new file mode 100644
index 0000000..dac13c9
--- /dev/null
+++ b/crates/app-iced/src/pages/settings/java.rs
@@ -0,0 +1,44 @@
+//! 设置页「Java」分组：运行时 / 默认内存 / JVM 参数（演示行）。
+//!
+//! **这一组归 java 线**：接真控件时在本文件把 `body` 换成 `Some(java::body)`（渲染器也写在本文件），
+//! 再把 `rows` 换成真数据源给的文本；`settings/mod.rs` 的注册表不用动。
+//!
+//! 图标说明（视觉复审 P2-3）：令牌里 `Play` 是填充字形，和同屏其它描边图标语汇打架；
+//! Java 分组讲的是运行时安装位置，用目录图标语义也对得上。
+
+use unlucky_design::icons::IconKind;
+
+use super::Group;
+
+/// Java 分组。
+pub(super) const GROUP: Group = Group {
+    name: "Java",
+    icon: IconKind::Folder,
+    rows: &[
+        ("Runtime", "Temurin 21.0.4"),
+        ("Default memory", "4 GiB"),
+        ("JVM arguments", "Automatic"),
+    ],
+    body: None,
+};
+
+/// Java 分组的运行期状态（M101 r2：**只归 java 线**）。
+///
+/// 加字段只改本文件：`Groups` 只认 `Groups.java`（一个字段），不认这个类型里的任何字段，
+/// 所以 `settings/mod.rs` / `app/state.rs` / `app/view.rs` 都不用动。
+#[derive(Debug, Default)]
+pub struct State {}
+
+/// Java 分组的消息（M101：**只归 java 线**，加变体只改本文件）。
+///
+/// 落点是 `app/update/settings/java.rs`；`pages/mod.rs` 与 `page_messages.rs` 都不用动（它们只认
+/// [`GroupMessage`](super::GroupMessage)）。
+#[derive(Debug, Clone)]
+pub enum Message {
+    /// **只有测试构造它**：M101 r2 留的「活的端到端证据」——外壳消息 →
+    /// `on_page` → `on_settings` → `on_settings_java` 这条路在运行时真的跑通，不是只靠编译期穷尽。
+    /// java 线接第一个真控件时把这一支换成真变体：`tests/java_section.rs` 的
+    /// `the_java_group_is_still_demo_rows` 就是那条会提醒你的绊线（它断言 `body.is_none()`）。
+    #[cfg(test)]
+    Ping,
+}
diff --git a/crates/app-iced/src/pages/settings/language_appearance.rs b/crates/app-iced/src/pages/settings/language_appearance.rs
new file mode 100644
index 0000000..f167c03
--- /dev/null
+++ b/crates/app-iced/src/pages/settings/language_appearance.rs
@@ -0,0 +1,35 @@
+//! 设置页 language+appearance 线的**消息口 + 状态口**（M101 `SETTINGSMSG`）。
+//!
+//! 为什么另开一个文件而不是塞进 `general.rs`：这一条线管**两个分组**（General 的语言 / 主题 /
+//! 启动页 / 关闭按钮，Appearance 的密度 / 圆角 / 动效 / 文字缩放）。两个分组各有自己的正文文件
+//! （`settings/general.rs`、`settings/appearance.rs`），消息与状态却只能有一个类型挂到
+//! [`GroupMessage::LanguageAppearance`](super::GroupMessage::LanguageAppearance) /
+//! [`Groups::language_appearance`](super::Groups) 上——否则 `GroupMessage` 与 `Groups` 会多出第五个
+//! 槽位，本线就要改 `settings/message.rs` / `settings/state.rs`（共享文件）。
+//!
+//! ## 本线的文件集合（只归本线，四条线两两不相交）
+//!
+//! | 文件 | 作用 |
+//! |---|---|
+//! | 本文件 | 消息枚举 + 状态结构（加一支消息 / 一个字段只改这里） |
+//! | `settings/general.rs` / `settings/appearance.rs` | 两个分组各自的 `GROUP`（名字 / 图标 / 行 / body） |
+//! | `settings/tests/general_section.rs` / `settings/tests/appearance_section.rs` | 两组的独立断言 |
+//! | `crates/i18n/src/catalog/settings/general.rs` / `appearance.rs` | 两组的文案 key |
+//! | `crates/app-iced/src/app/update/settings/language_appearance.rs` | 消息的落点 |
+//!
+//! 真控件那半边在 `pages/appearance/section.rs`（`appearance.rs` 只负责把 `body` 挂上去）。
+
+/// 语言 + 外观线的状态（**只归本线**）。
+///
+/// 首版是空结构：这一条线还没有自己的运行期状态（外观那份状态是 `pages::appearance::State`，
+/// 归 M93，走 `States::appearance` 那条既有通道，不在这里）。加字段只改本文件。
+#[derive(Debug, Default)]
+pub struct State {}
+
+/// 语言 + 外观线的消息（**只归本线**）。
+///
+/// 首版是空枚举：这一条线还没有接真下拉 / 真控件之前，没有可点的东西。空枚举的好处是
+/// `app/update/settings/language_appearance.rs` 里的 `match message {}` 天然穷尽——加了变体
+/// 不接线就报 E0004，不会静默。
+#[derive(Debug, Clone)]
+pub enum Message {}
diff --git a/crates/app-iced/src/pages/settings/message.rs b/crates/app-iced/src/pages/settings/message.rs
new file mode 100644
index 0000000..be4fcdd
--- /dev/null
+++ b/crates/app-iced/src/pages/settings/message.rs
@@ -0,0 +1,106 @@
+//! 设置页的**分组消息投递口**（M101 `SETTINGSMSG`）：四条填页线各写各的变体，不再抢
+//! `pages/mod.rs` 的枚举尾部与 `app/update/page_messages.rs` 那条不许兜底的 match。
+//!
+//! ## 这一层为什么存在
+//!
+//! M100 把设置页的**文件**按分区拆开了，但四条线真正的交汇处仍是同一处追加锚点：
+//! `pages::Message` 的枚举尾部 + `page_messages.rs` 的 match 臂（该 match 有
+//! `the_page_match_has_no_wildcard_fallback` 守门，不许 `_ =>`）。四个变体、四条线、两个共享
+//! 文件 ⇒ 四路并行必然四路冲突。M101 只做一件事：把「加消息」从共享文件搬进各组自己的文件——
+//! `pages::Message` 从此只有**这一个**设置页变体。
+//!
+//! ```text
+//! pages::Message::Settings(GroupMessage)
+//!   ├─ Java(java::Message)                       → settings/java.rs
+//!   ├─ Download(download::Message)               → settings/download.rs
+//!   ├─ LanguageAppearance(language_appearance::Message) → settings/language_appearance.rs
+//!   └─ AiAbout(ai_about::Message)                → settings/ai_about.rs
+//! ```
+//!
+//! 四个载荷**必须**是四个不同类型、分别定义在四个文件里；否则「两条线往同一个枚举里加变体」的
+//! 冲突只是从 `pages/mod.rs` 搬到了这里。`each_group_owns_its_own_message_type` 用 `type_name`
+//! 里的模块路径守这一条。
+//!
+//! ## 加一支设置页消息要改几个文件（M101 r2 之后）
+//!
+//! **2 个**：你自己那条线的消息口文件（`settings/<线>.rs`）加一个变体，加上你那条落点
+//! （`app/update/settings/<线>.rs`）接一条臂——两处都只归你。`pages/mod.rs`、
+//! `page_messages.rs`、`settings/message.rs`、`settings/state.rs`、`app/update/settings.rs` 都不用动。
+//!
+//! ## 穷尽性：抓得住什么 / 抓不住什么
+//!
+//! - **抓得住**：某条线加了变体却忘了接线 → 编译器在 `app/update/settings.rs` 的 match 上报
+//!   **E0004**（那里对 [`GroupMessage`] 做穷尽匹配，没有 `_ =>`）。注意 `page_messages.rs`
+//!   那条守卫只认 `pages::Message`，**它抓不住组内变体**——把守卫下放到 `settings.rs` 正是本层
+//!   的第二个目的，两个 dispatch 各守一层。
+//! - **抓不住**：handler 忽略消息（`let _ = message; Task::none()`）或两个 handler 的**身体**被
+//!   写成一样——类型对得上就编得过。那要人读，或者等真接业务后由「点了没反应」的用例抓。
+//!
+//! 类型还顺手挡掉了另一种错：把 `Java(m)` 转给 `on_settings_download` 编不过（载荷类型不同），
+//! 所以「接错组」这一半是编译期兜住的，「接了个空壳」那一半不是。
+//!
+//! ## 测试
+//!
+//! 本文件的 [`tests::each_group_owns_its_own_message_type`]；dispatch 侧的
+//! `the_group_dispatch_has_no_catch_all_arm` 在 `app/update/settings/tests.rs`（`app/update/settings.rs`
+//! 只是 `#[cfg(test)] mod tests;` 的声明点，别去那里找）。
+
+use super::{ai_about, download, java, language_appearance};
+
+/// 设置页分组消息：**唯一**一个进 `pages::Message` 的投递口。
+///
+/// 每个变体只归一条线，载荷类型定义在那条线自己的文件里（见模块文档的四个箭头）。
+/// 加变体 = 改自己那个文件 + 改 `app/update/settings/<线>.rs`，两处都只归你。
+#[derive(Debug, Clone)]
+pub enum GroupMessage {
+    /// Java 分组（`settings/java.rs`）。
+    Java(java::Message),
+    /// Downloads 分组（`settings/download.rs`）。
+    Download(download::Message),
+    /// 语言 + 外观两组的共同消息口（`settings/language_appearance.rs`）。
+    LanguageAppearance(language_appearance::Message),
+    /// AI / About 分组（`settings/ai_about.rs`）。
+    AiAbout(ai_about::Message),
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// 四条线的载荷**必须**住在四个不同文件里。
+    ///
+    /// 抓得住：① 为了少建一个文件，把两个组的 `Message` 塞进同一个文件（四条线又会撞同一个
+    /// 追加锚点，本 mission 的目的当场作废）；② 谁把某个分组文件改名后忘了同步（`type_name`
+    /// 里带模块路径，改名就红）。
+    /// 抓不住：变体装得对不对（那是 `app/update/settings.rs` 的 E0004 与其守卫的事），也抓不住
+    /// handler 身体写空/写反（类型对得上就编得过）。
+    #[test]
+    fn each_group_owns_its_own_message_type() {
+        let homes = [
+            (
+                std::any::type_name::<java::Message>(),
+                "settings::java::Message",
+            ),
+            (
+                std::any::type_name::<download::Message>(),
+                "settings::download::Message",
+            ),
+            (
+                std::any::type_name::<language_appearance::Message>(),
+                "settings::language_appearance::Message",
+            ),
+            (
+                std::any::type_name::<ai_about::Message>(),
+                "settings::ai_about::Message",
+            ),
+        ];
+
+        for (actual, expected) in homes {
+            assert!(
+                actual.ends_with(expected),
+                "载荷类型 {actual} 不在它自己的文件里（应为 {expected}）：\
+                 两个组共用一个消息类型，四条线又会撞同一个追加锚点"
+            );
+        }
+    }
+}
diff --git a/crates/app-iced/src/pages/settings/mod.rs b/crates/app-iced/src/pages/settings/mod.rs
new file mode 100644
index 0000000..d06d737
--- /dev/null
+++ b/crates/app-iced/src/pages/settings/mod.rs
@@ -0,0 +1,326 @@
+//! 设置页：**supporting-pane** 的用例（左侧分组导航 240 + 右侧表单列 ≤424）。
+//!
+//! ## 为什么是 supporting-pane 而不是 list-detail
+//!
+//! 分组导航是**辅助**（它不承载数据，只切换右侧表单的内容），右侧表单才是阅读对象；
+//! 官方把这种「主列 + 窄侧列」叫 supporting pane。list-detail 的前提是左列本身是一份可浏览的数据集
+//! （实例列表就是），设置页不满足。
+//!
+//! ## 侧列与 rail 的关系（D33）
+//!
+//! 宽度 240 直接取 `LayoutMetrics::nav_drawer_width`（D33：同一容器 rail 88 ⇄ drawer 240 的展开态），
+//! 但**不复制 rail 的实现**：这里没有 hover 药丸、没有二级标签、没有 `Message::Select`。
+//! 将来真正的 `NavigationDrawer` 由 M78 提供，本页换掉 [`frame::group_nav`] 即可。
+//!
+//! ## 退化（窗口 <720 或 compact 档）
+//!
+//! 侧列消失，分组导航退化成「按组堆叠」：同一列里每组一张卡 + 一段 12pt 组名。整页仍居中、正文列仍 ≤424。
+//!
+//! ## 文件地图（M99 `SETTINGSFRAME`：**纯搬移**，行为与视觉零变化）
+//!
+//! 本文件只做三件事：**分组注册表**（[`GROUPS`]）、**内容分发**（[`form`] 按分组挑渲染器）、
+//! 以及 M101 加的两条漏斗的**转发**（消息 → [`message`]，状态 → [`state`]）。
+//! 一组的正文、文案、演示行、状态、消息都在它自己的文件里：
+//!
+//! | 分组 | 文件（正文 / 状态 / 消息） | 谁会动它 |
+//! |---|---|---|
+//! | General | [`general`] | language+appearance 线（语言下拉 + 主题 / 启动页） |
+//! | Appearance | [`appearance`] | language+appearance 线（真控件已在 `pages/appearance/section.rs`） |
+//! | Java | [`java`] | java 线 |
+//! | Downloads | [`download`] | download 线 |
+//! | （页面上还没有这个分组） | [`ai_about`] | ai+about 线：先建分组再接线 |
+//! | 页头 / 侧列 / 滚动区 / 演示卡片 / 空态位 | [`frame`] | 谁都不该改（改了就是改版面） |
+//!
+//! ## 测试也按 section 分（M100）
+//!
+//! 断言跟着它守的东西走，于是四条 section 线**各改各的测试**：
+//!
+//! | 测试文件 | 守什么 | 谁会动它 |
+//! |---|---|---|
+//! | `tests/general_section.rs` | General 自己的行 / 图标 / body 现状 | language+appearance 线 |
+//! | `tests/appearance_section.rs` | Appearance 自己的行 / 图标 / body 现状 | language+appearance 线 |
+//! | `tests/java_section.rs` | Java 自己的行 / 图标 / body 现状 | java 线 |
+//! | `tests/download_section.rs` | Downloads 自己的行 / 图标 / body 现状 | download 线 |
+//! | `tests/mod.rs` | **跨 section**：版面契约、行宽上限、窄窗退化、注册表顺序 / 分组下标 / 每条线的漏斗安装情况 | 谁都别随手改（每条都写了为什么不能下放） |
+//!
+//! 判据：**给某一组加一条新断言 = 只改它自己那个测试文件**。
+//!
+//! **加一个分组要动哪里**：① 在它自己的文件里写一个 `pub(super) const GROUP`（名字 / 图标 / 演示行 /
+//! 可选的真控件渲染器 `body`）；② 本文件的 [`GROUPS`] 加一行、数组长度 +1；③ [`state::Groups`] 加一个
+//! 字段、[`message::GroupMessage`] 加一个变体、`app/update/settings.rs` 加一条臂。**不需要**动 `frame.rs`、
+//! 别的分组文件或 `pages/mod.rs`。
+//!
+//! ## 消息：一个投递口，四条线各写各的（M101 `SETTINGSMSG`）
+//!
+//! 四条填页线都要往 `pages::Message` 里加变体，而那是**一个**枚举加上
+//! `app/update/page_messages.rs` 里一条不许 `_ =>` 的 match —— 四路并行必然四路冲突。
+//! M101 把这件事收成一个投递口：
+//!
+//! ```text
+//! pages::Message::Settings(GroupMessage)   ← 全 crate 只有这一个设置页变体
+//!   ├─ Java(java::Message)                             → settings/java.rs
+//!   ├─ Download(download::Message)                     → settings/download.rs
+//!   ├─ LanguageAppearance(language_appearance::Message) → settings/language_appearance.rs
+//!   └─ AiAbout(ai_about::Message)                      → settings/ai_about.rs
+//! ```
+//!
+//! 加一支消息 = 改自己那个消息口文件 + 自己那条落点（`app/update/settings/<线>.rs`），2 个文件、
+//! 0 个共享文件。四个消息口枚举声明成 `pub` 是为了过 `private_interfaces`：那条 lint 按**类型自身
+//! 的声明可见性**判，所以模块用最小的 `pub(crate)`（`pages/mod.rs` 的 `pub(crate) mod settings;`）
+//! 就够，不必把整个设置页模块树暴露成 crate 公开 API。
+//!
+//! ## 状态：与消息同构的状态漏斗（M101 r2，r1 复审 P1）
+//!
+//! ```text
+//! App.settings: state::Groups  ← app/state.rs 一行（M101 加一次，四条线都不碰）
+//!   ├─ java / download / language_appearance / ai_about：各自的 State 在各自文件里
+//! States { appearance, groups } ← 只读视图，按值传给 view；每组的 GROUP.body 自己取自己要的那份
+//! ```
+//!
+//! **加/改某一组的字段**只改 `pages/settings/<组>.rs`；**异步结果**在自己那条落点里构造
+//! `Message::Page(pages::Message::Settings(GroupMessage::<线>(…)))` 回来——`Page` 这条既有通道就是
+//! 异步结果的入口，`app::Message` / `app/update.rs` 都不用动。
+//!
+//! ### 仍然共享的点（四条线都可能碰到，只能靠 tower 串行合并，或者由专人一次性做掉）
+//!
+//! 1. `crates/i18n/src/catalog/golden.rs` —— 每加一条文案 key 都要按声明顺序往金表里插一行
+//!    （`split_keeps_every_translation` 逐条比 key + 英/中译文）。**注意**：`catalog.rs` 的 `Key`
+//!    枚举由 `catalog!` 宏从各域文件累积生成，加 key **不用**改 `catalog.rs`，也不用改
+//!    `catalog/settings/mod.rs`（五个域已全部接进装配链）。
+//! 2. 本文件的 [`GROUPS`] —— 只有 ai+about 线**上第 5 组**时加一行（页面上多一组本来就是整页的变化）。
+//! 3. `tests/mod.rs` —— ai+about 线新建 `tests/ai_section.rs` 时要加一行 `mod ai_section;`
+//!    （测试文件不挂 `mod` 就不编译），以及「左列顺序」那条字面量断言会连带红，需要人确认。
+//! 4. **读页外真值**（r2 复审 P1 补的）—— [`States`] 只有 `appearance` + `groups` 两格，组正文读不到
+//!    `pages::Model`（「当前语言」的值在 `Model.lang`，`pages/model.rs`），也读不到 presenter 的设置
+//!    快照。两条路的**真实成本**（`States` 没有 `Default`，加字段必然 E0063，已实测）：
+//!    - 把 `model` **塞进 [`States`]** ⇒ struct literal 有 **4 处**（`pages/mod.rs:154/177/232` 与
+//!      `app/view.rs:70`），四处都要补字段 ⇒ **3 个共享文件**：`settings/state.rs`、`pages/mod.rs`、
+//!      **`app/view.rs`**（最后这个正是 M104 的落点，本 mission 反复设锚点要避开的就是它）；
+//!    - 给 `settings::view` **加一个 `model: &Model` 形参**（`pages/mod.rs` 的 `render` 本来就拿着
+//!      `model`，直接往下传）⇒ **2 个共享文件**（`settings/mod.rs` + `pages/mod.rs`），
+//!      `app/view.rs` 不用动 —— **推荐这个形状**。
+//!
+//!    顺带订正 r3 之前那句「在 `app/state.rs` 用真值初始化 `Groups.language_appearance`（1 个文件）」：
+//!    **M106 起语言已经有真值源**——`App::lang: LangState`（`crates/app-iced/src/ui/lang.rs`，用户档位
+//!    `LangChoice` + 探测结论 `Detection`），由 `App::refresh_view` 经 `view::model(…, lang)` 灌进
+//!    `pages::Model.lang`，设置页再从 `settings::view` 的 `language` 形参拿到它。所以下一条线要给某一组
+//!    读「当前语言」时，**不需要**再造一层状态：要么走 `Model.lang`（给 `settings::view` 加形参，
+//!    与 M106 同形状），要么读 `Groups` 里本线的字段。两种形状都是「谁先撞谁付一次钱」的一次性代价，
+//!    不是永久性四路撞车。
+//! 5. **首帧取数 / 异步发起**（同上，r2 复审 P1 补）—— [`Body`] 是
+//!    `fn(&Ui, States) -> Option<Element>`，返回不了 `Task`；而且 `settings::view` → `pages::render`
+//!    → `App::view` **一路都返回 `Element`**（iced 0.14 的 `view` 也只返回 `Element`，`view(&self)`
+//!    又改不了状态），**view 期间产出的 `Task` 没有出口**。所以只有一条路：在 `app/update.rs` 的
+//!    `Message::Boot` 分支补一次首帧派发（**1 个共享文件**——`on_boot` 本来就在派
+//!    `AppCommand::RefreshAll`）。想让「组自己」发起首帧探测，得先在 app 侧另造一条旁路
+//!    （`settings/mod.rs` + `pages/mod.rs` + `app/view.rs` 三处都要动），**不建议**。不改的代价：
+//!    首屏显示演示值、等用户点一次才变真值——四条线都能接受就不必动。
+//! 6. **隐性代价：`Groups` 必须是 `Sync + Default`**（r2 复审 P3 指出）——
+//!    [`demo_groups`] 用 `static LazyLock<Groups>` 撑着 harness 路径，所以某个组的 `State` 里一旦
+//!    放了 `Rc` 这类非 `Sync` 字段，编译会在**本模块**（`settings/state.rs`）红。选择 `LazyLock`
+//!    是为了让 `page()` / `page_with_appearance()` 的返回 `Element<'a>` 借得到一个 `'static` 的默认
+//!    状态；如果哪天必须放非 `Sync` 状态，改法是把默认状态改成「每个调用点自己造一个 `Groups`」
+//!    ——`pages/mod.rs` 的**三个**调用点都要改（`page` / `page_with_appearance` /
+//!    `app_with_appearance`，行 156 / 179 / 234），同样是**一次性**代价。
+
+// 四条填页线的文件要能被**各自那条落点**（`app/update/settings/<线>.rs`）与状态架子
+// （`state::Groups`）命名，所以是 `pub(crate)`：最小面，不是 crate 公开 API。
+// 分组正文文件 `appearance` / `frame` / `general` 只在设置页内部用，保持私有。
+pub(crate) mod ai_about;
+mod appearance;
+pub(crate) mod download;
+mod frame;
+mod general;
+pub(crate) mod java;
+pub(crate) mod language_appearance;
+mod message;
+mod state;
+
+#[cfg(test)]
+mod tests;
+
+pub use message::GroupMessage;
+pub use state::{demo_groups, Groups, States};
+
+use iced::widget::column;
+use iced::{Element, Length};
+
+use unlucky_design::color::Role;
+use unlucky_design::icons::IconKind;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+use unlucky_i18n::{Lang, LangChoice};
+
+use crate::theme::Ui;
+
+use super::layout::{FrameMetrics, PageLayout};
+use super::Message;
+
+/// 设置页 General 分组要的两件（M106）：用户选的档位 + 这一次生效的语言。
+///
+/// 为什么不塞进 `pages::Model`：那是页面与 presenter 之间的**展示契约**（由快照派生），而档位是
+/// **用户意图**（`App` 的字段）；塞进去会让 `pages::demo_model` 也得伪造一个档位。
+/// 为什么不是单个 `Lang`：语言行要画**选中态**——「我明明选了跟随系统」得在界面上看得出来。
+/// 为什么不塞进 [`States`]：那条路要改 `settings/state.rs` 并补齐 4 处 struct literal
+/// （`settings/mod.rs` 文档「仍然共享」第 4 条已算过账），而 `view` 多一个形参只动 2 个文件。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Language {
+    /// 用户选的那一档（跟随系统 / 手选）。
+    pub choice: LangChoice,
+    /// 这一次真正生效的语言（目录选的就是它）。
+    pub effective: Lang,
+}
+
+impl Default for Language {
+    /// harness / 演示路径的默认值：跟随系统 + 英文基线（与 M84 起的截图基线一致）。
+    fn default() -> Self {
+        Self {
+            choice: LangChoice::System,
+            effective: Lang::En,
+        }
+    }
+}
+
+/// 一个分组正文的**真控件渲染器**：入参是「画一帧时那份只读状态」（组状态 + 外观状态），
+/// 返回 `None` = 这一组现在没东西可画（例如外观分组在 harness 路径下没有外观状态），
+/// 由 [`form`] 退回演示行。
+///
+/// 各组自己的渲染器**定义在自己文件里**，签名是这一条：于是「这一组要读哪些状态」由它自己决定，
+/// 本文件不需要认识任何一组的字段（r1 复审 P1 要的正是这一点）。
+type Body = for<'a> fn(&'a Ui, States<'a>) -> Option<Element<'a, Message>>;
+
+/// 一个设置分组：名字、图标、演示行、（可选）把这一组正文画成真控件的渲染器。
+///
+/// 除 `name`/`icon`/`rows`/`body` 外没有别的字段：**分组自己的状态归分组自己**（见 [`state`]），
+/// 这里只装「怎么画」。
+struct Group {
+    /// 左列显示名（也是表单列的分组标题）。
+    name: &'static str,
+    /// 左列图标。
+    icon: IconKind,
+    /// 演示行（`body` 为 `None` 时画这些；harness 出图也靠它们）。
+    rows: &'static [(&'static str, &'static str)],
+    /// 真控件渲染器；`None` = 这一组还没接真控件，画 `rows`。
+    body: Option<Body>,
+}
+
+/// 分组注册表：**顺序 = 左列自上而下**，也是 `crate::pages::appearance::APPEARANCE_GROUP` 的下标来源。
+///
+/// 每一项都指向它自己文件里的 `GROUP`（M99 之前是四份字面量挤在本文件里）。
+const GROUPS: [Group; 4] = [
+    general::GROUP,
+    appearance::GROUP,
+    java::GROUP,
+    download::GROUP,
+];
+
+/// 演示选中的分组（没有真实外观状态时——`pages_demo` harness——用它）。
+const SELECTED: usize = 0;
+
+/// General 分组在 [`GROUPS`] 里的下标（0）。它与 [`SELECTED`] 同值**是巧合，不是依赖**。
+///
+/// 为什么需要它：语言行要的是「当前档位 + 生效语言」（[`Language`]），而 `Group.body` 的签名只带
+/// [`States`]（外观 + 组状态）——给 `States` 加字段要动 `settings/state.rs` 与 4 处 struct literal
+/// （见本文件文档「仍然共享」第 4 条），给 `Body` 加形参会令另外三组各自的 `body` 函数编译不过。
+/// 所以这里做一次**按下标的分发**：代价是一行 `if`，换来 `general::GROUP.body` 仍是 `None`
+/// （`tests/mod.rs` 的「只有外观组带真控件 body」照样成立）。
+const GENERAL_GROUP: usize = 0;
+
+/// 左列分组的**显示名** key（下标与 [`GROUPS`] 一一对应，M106）。
+///
+/// 为什么不放进 [`Group`]：那会让另外三组的 `GROUP` 字面量（各自文件、各自填页线）编译不过——
+/// 与 [`GENERAL_GROUP`] 同一条理由。`Group.name` 因此退化为**id**（测试按它认组；显示走这张表）。
+pub(super) const GROUP_LABELS: [unlucky_i18n::Key; 4] = [
+    unlucky_i18n::Key::SettingsGroupGeneral,
+    unlucky_i18n::Key::SettingsGroupAppearance,
+    unlucky_i18n::Key::SettingsGroupJava,
+    unlucky_i18n::Key::SettingsGroupDownloads,
+];
+
+/// 整页。
+///
+/// `states` 是「画一帧时那份只读状态」：[`States::appearance`] 是 M93 接进来的外观运行期状态
+/// （`None` = harness / 演示路径，设置页仍画占位行），[`States::groups`] 是各组自己的状态。
+pub fn view<'a>(
+    ui: &'a Ui,
+    metrics: FrameMetrics,
+    states: States<'a>,
+    language: Language,
+) -> Element<'a, Message> {
+    // 选中分组：有真实外观状态时看状态（点左列可切），否则退回演示值 0。
+    let selected = states
+        .appearance
+        .map_or(SELECTED, |state| state.selected_group);
+
+    let body = match metrics.layout {
+        PageLayout::SupportingPane => frame::panes(
+            metrics,
+            frame::group_nav(ui, selected, language.effective),
+            frame::left_aligned(metrics.column, form(ui, Some(selected), states, language)),
+        ),
+        _ => frame::single_column(metrics, form(ui, None, states, language)),
+    };
+
+    frame::page(ui, metrics, frame::header(ui, language.effective), body)
+}
+
+// --------------------------------------------------------------- 内容分发
+
+/// 表单列（正文列宽 ≤424）。`only = Some(i)` 只渲染一组（supporting-pane），
+/// `None` 渲染全部（窄窗：分组导航退化成按组堆叠）。
+///
+/// **分发点**：一组的正文由它自己文件里的 `GROUP.body` 决定——`Some(f)` 让 `f` 自己去
+/// [`States`] 里取它要的数据（`None` 返回值 ⇒ 退回演示行），`None` 直接画演示行
+/// （[`frame::demo_card`]）。这里不出现任何一个分组名，也不比较下标，更不认识任何一组的字段。
+fn form<'a>(
+    ui: &'a Ui,
+    only: Option<usize>,
+    states: States<'a>,
+    language: Language,
+) -> Element<'a, Message> {
+    let catalog = language.effective.catalog();
+    let mut stack = column![].spacing(ui.space(Space::X6)).width(Length::Fill);
+
+    for (index, group) in GROUPS.iter().enumerate() {
+        if only.is_some_and(|selected| selected != index) {
+            continue;
+        }
+
+        // 「外观」分组：有真实外观状态时画真控件（M93），否则退回演示行（harness）。
+        // 这两条的差别由 `GROUP.body` 的返回值表达，而不是「下标 == APPEARANCE_GROUP」的硬比较。
+        //
+        // M106：General 是**唯一一处按下标分发**的例外（理由见 [`GENERAL_GROUP`]）——语言行的
+        // 档位与生效语言不在 [`States`] 里，只能从 `pages::Language` 进来；它与 `appearance` 在不在场
+        // 无关（harness 那条路径也画得出真控件）。
+        let card = if index == GENERAL_GROUP {
+            general::body(ui, language)
+        } else {
+            group
+                .body
+                .and_then(|body| body(ui, states))
+                .unwrap_or_else(|| frame::demo_card(ui, group.rows))
+        };
+
+        stack = stack.push(
+            column![
+                frame::text_role(
+                    ui,
+                    TypeRole::LabelMedium,
+                    false,
+                    // 卡片标题与左列同一个词源（`GROUP_LABELS`）：`Group.name` 只是 id。
+                    GROUP_LABELS
+                        .get(index)
+                        .map_or(group.name, |key| catalog.text(*key)),
+                    ui.color(Role::OnSurfaceVariant),
+                ),
+                card,
+            ]
+            .spacing(ui.space(Space::X2))
+            .width(Length::Fill),
+        );
+    }
+
+    stack = stack.push(frame::overrides_empty(ui, language.effective));
+
+    frame::scroll(ui, stack)
+}
diff --git a/crates/app-iced/src/pages/settings/state.rs b/crates/app-iced/src/pages/settings/state.rs
new file mode 100644
index 0000000..44113a8
--- /dev/null
+++ b/crates/app-iced/src/pages/settings/state.rs
@@ -0,0 +1,85 @@
+//! 设置页的**状态漏斗**（M101 r2）：与 [`super::message`] 的消息漏斗同构——一个组的状态归它自己的
+//! 文件，[`Groups`] 只是一个按组排开的架子。
+//!
+//! ## 为什么要这一层（r1 复审的 P1）
+//!
+//! 消息漏斗解决了「加一支消息要改哪些文件」，但一组要画**真值**就得有数据进渲染器：r1 之前
+//! `settings::view` 只收 `Option<&appearance::State>`，于是 java / download / language+appearance
+//! 三条线要显示「当前运行时 / 当前并发数 / 当前语言」时，**都得改 `settings/mod.rs`**；带运行期状态
+//! 的还要改 `pages/mod.rs` / `app/view.rs` / `app/state.rs`。四条线一铺开就是第二处四路撞车。
+//!
+//! 现在的形状：
+//!
+//! ```text
+//! App.settings: pages::settings::Groups        ← 唯一的所有者（app/state.rs 一行）
+//!   ├─ java: java::State                        → pages/settings/java.rs
+//!   ├─ download: download::State                → pages/settings/download.rs
+//!   ├─ language_appearance: language_appearance::State → pages/settings/language_appearance.rs
+//!   └─ ai_about: ai_about::State                → pages/settings/ai_about.rs
+//!
+//! settings::view(ui, metrics, States { appearance, groups })   ← 只读视图，按值传
+//!   └─ 每组的 GROUP.body(ui, states) 自己从 states 里取自己要的那份
+//! ```
+//!
+//! **加/改某一组的字段** = 只改 `pages/settings/<组>.rs`（状态类型在它自己文件里）+ 用它自己的
+//! handler 更新（`app/update/settings/<线>.rs`）。本文件、`pages/mod.rs`、`app/state.rs`、
+//! `app/view.rs` **都不用动**——本 mission 的这半边判据就是这么验的（见报告「变异证据」）。
+//!
+//! **加一整条新线**（多一个组）才需要：本文件加一个字段、`message.rs` 加一个变体、
+//! `app/update/settings.rs` 加一条臂。那是「加一条线」，不是「加一个字段」。
+//!
+//! ## 外观那条真控件路径（M93）没有被挤掉
+//!
+//! `appearance::State` 仍是 `App` 的字段（不复用、不搬走），[`States::appearance`] 原样借用它；
+//! 「没有外观状态（harness）⇒ 画演示行」这条判据现在由 `appearance` 组自己的 `GROUP.body`
+//! 表达（返回 `None` ⇒ [`super::frame::demo_card`]），与 r1 之前逐像素等价。
+
+use std::sync::LazyLock;
+
+use crate::pages::appearance;
+
+use super::{ai_about, download, java, language_appearance};
+
+/// 各组自己拥有的运行期状态：**一个组一个字段**，字段类型定义在那条线自己的文件里。
+///
+/// 字段的**内部**结构归各组（加字段只改它自己的文件）；架子（有哪几个组）归这里。
+#[derive(Debug, Default)]
+pub struct Groups {
+    /// Java 分组的状态（`pages/settings/java.rs`）。
+    pub java: java::State,
+    /// Downloads 分组的状态（`pages/settings/download.rs`）。
+    pub download: download::State,
+    /// 语言 + 外观两组的状态（`pages/settings/language_appearance.rs`）。
+    pub language_appearance: language_appearance::State,
+    /// AI / About 分组的状态（`pages/settings/ai_about.rs`）。
+    pub ai_about: ai_about::State,
+}
+
+/// 画一帧时**按值**递给各组渲染器的只读视图：组状态 + 外观运行期状态（两个引用，`Copy`）。
+///
+/// 为什么按值而不是按引用：`Settings::view` 返回的 `Element<'a>` 会借走它，按引用传会逼着
+/// harness 那条路径（[`super::demo_groups`] 撑着的 `page()` / `page_with_appearance()`）为一份
+/// **临时构造**的 `States` 造 `'static`，或者把默认状态塞进 `Model`（两份真相）。按值传没有
+/// 这层借用纠缠，调用方写一行就够。
+#[derive(Debug, Clone, Copy)]
+pub struct States<'a> {
+    /// 外观运行期状态（M93）：`None` = harness / 演示路径（设置页画演示行）。
+    pub appearance: Option<&'a appearance::State>,
+    /// 各组自己的状态（见 [`Groups`]）。
+    pub groups: &'a Groups,
+}
+
+/// 演示 / harness 路径的默认组状态（`pages::page` 与 `pages::page_with_appearance` 用它）。
+///
+/// `'static` 是有意的：那两条入口不持有任何组状态，而返回的 `Element<'a>` 会借走这份 `Groups`；
+/// 让它活得比调用方长，借用就不会把返回值钉在函数栈上。
+///
+/// **隐性代价（r2 复审 P3）**：`static` 要求 `Groups: Sync + Default`，于是某个组的 `State` 里一旦
+/// 放了 `Rc` 这类非 `Sync` 字段，编译会红在**本文件**（共享）而不是那一组自己的文件。真需要
+/// 非 `Sync` 状态时的改法：去掉这个 `static`，改成每个调用点自己造一份 `Groups`——`pages/mod.rs` 的
+/// **三个**调用点都要改（`page` / `page_with_appearance` / `app_with_appearance`，行 156 / 179 / 234），
+/// 一次性代价，见 [`super`] 文档「仍然共享」第 6 条。
+pub fn demo_groups() -> &'static Groups {
+    static DEMO: LazyLock<Groups> = LazyLock::new(Groups::default);
+    &DEMO
+}
diff --git a/crates/app-iced/src/pages/settings/tests/appearance_section.rs b/crates/app-iced/src/pages/settings/tests/appearance_section.rs
new file mode 100644
index 0000000..e318042
--- /dev/null
+++ b/crates/app-iced/src/pages/settings/tests/appearance_section.rs
@@ -0,0 +1,52 @@
+//! 「Appearance」分组自己的断言（M100 **新增**：`settings/tests.rs` 那 7 条全是跨 section 的，
+//! 一条 section 断言都没有；这 3 条是新增，不是搬移）。
+//!
+//! **归 language+appearance 线**：这是设置页唯一接了真控件的一组，真控件实现全在
+//! `pages/appearance/section.rs`；本文件只守「注册表这一侧的接线」。
+//! 本组已经把 `body` 接上了；`tests/mod.rs` 那条「只有一组有真控件」的**聚合绊线已在 M101 r2 删除**
+//! （被四条 per-group 断言完全蕴含——代价是「唯一性」从此没人守，那段说明写在 `tests/mod.rs` 同处）。
+
+use super::super::appearance;
+use unlucky_design::icons::IconKind;
+
+/// 这一组的**演示行**（没有外观运行期状态时才画）。
+///
+/// 抓得住：四条线并行合并时把别人的行粘到本文件（四份 `GROUP` 长得几乎一样）；
+/// 漏掉/多一条行；标签与值错位。
+/// 抓不住：真控件那一屏（那是 `pages/appearance` 的事，靠出图判）。
+#[test]
+fn the_appearance_group_shows_density_corner_motion_and_text_scale() {
+    let rows: Vec<(&str, &str)> = appearance::GROUP.rows.to_vec();
+    assert_eq!(
+        rows,
+        vec![
+            ("Density", "Comfortable"),
+            ("Corner style", "Follow system"),
+            ("Motion", "Full"),
+            ("Text scale", "100%"),
+        ]
+    );
+}
+
+/// 左列图标（`IconKind::Sidebar`）。
+#[test]
+fn the_appearance_group_keeps_its_icon() {
+    assert_eq!(appearance::GROUP.icon, IconKind::Sidebar);
+}
+
+/// **本组的绊线**：外观分组必须一直是「挂了真控件」的那一组。
+///
+/// 抓得住：language+appearance 线把 `body` 换回 `None`（真控件消失、退回演示行，而截图对这种
+/// 「只在有外观状态时出现」的差别不一定抓得住）。
+/// 抓不住：`body` 到底指向哪个渲染器——**函数指针相等性断言不了**（rustc
+/// `unpredictable_function_pointer_comparisons`：fn 地址不保证唯一，比出来的结果没有意义），
+/// 所以「指向 `pages::appearance::section`」这件事只能由
+/// `settings/appearance.rs` 那一行源码 + 两张图的 sha256 不同来担保。
+#[test]
+fn the_appearance_group_keeps_a_real_control_body() {
+    assert!(
+        appearance::GROUP.body.is_some(),
+        "外观分组必须是挂了真控件的那一组（`settings/appearance.rs` 里是 `body: Some(body)`，\
+         `body` 是本文件那个本地 fn；具体渲染器由那一行源码 + 截图担保，函数指针相等性断言不了）"
+    );
+}
diff --git a/crates/app-iced/src/pages/settings/tests/download_section.rs b/crates/app-iced/src/pages/settings/tests/download_section.rs
new file mode 100644
index 0000000..f3ca8bc
--- /dev/null
+++ b/crates/app-iced/src/pages/settings/tests/download_section.rs
@@ -0,0 +1,49 @@
+//! 「Downloads」分组自己的断言（M100 **新增**：`settings/tests.rs` 那 7 条全是跨 section 的，
+//! 一条 section 断言都没有；这 3 条是新增，不是搬移）。
+//!
+//! **归 download 线**。接真控件那天要改**两个**文件（M101 r2 删掉了原先的第 3 处跨 section 绊线）：
+//! `settings/download.rs` + 本文件 `the_downloads_group_is_still_demo_rows`。
+//!
+//! 别把它和下载页（`pages/download*`）搞混：那是「装哪个版本」，这一组是「怎么下」的默认值。
+
+use super::super::download;
+use unlucky_design::icons::IconKind;
+
+/// 这一组的行集合（标签 + 值）。
+///
+/// 抓得住：① 四条线并行合并时把别人的行粘到本文件（四份 `GROUP` 长得几乎一样，最容易整块贴错）；
+/// ② 漏掉/多出一条行；③ 标签与值错位（`("Concurrency", "8 threads")` 被写成 `"Off"`）。
+/// 抓不住：值对不对（`Automatic (region)` 是不是本机真选中的源）——那是接线后真数据源的事。
+#[test]
+fn the_downloads_group_shows_source_concurrency_and_checksums() {
+    let rows: Vec<(&str, &str)> = download::GROUP.rows.to_vec();
+    assert_eq!(
+        rows,
+        vec![
+            ("Preferred source", "Automatic (region)"),
+            ("Concurrency", "8 threads"),
+            ("Verify checksums", "On"),
+        ]
+    );
+}
+
+/// 左列图标（`IconKind::Download`）。与导航轨的「下载」同族，换掉就与 rail 语汇不一致。
+#[test]
+fn the_downloads_group_keeps_its_icon() {
+    assert_eq!(download::GROUP.icon, IconKind::Download);
+}
+
+/// **绊线**：这一组还没接真控件，画的是演示行。
+///
+/// 抓得住：download 线接上了 `body` 却没更新这里的期望（那会让本文件静默变成假绿）。
+/// 抓不住：界面上真控件长什么样。
+///
+/// 接真控件时：把 `is_none()` 改成 `is_some()`，**只改这一行**（M101 r2 起不必再去
+/// `tests/mod.rs` 报到：那条跨 section 聚合绊线已删）。
+#[test]
+fn the_downloads_group_is_still_demo_rows() {
+    assert!(
+        download::GROUP.body.is_none(),
+        "Downloads 还没接真控件：接了就改本断言"
+    );
+}
diff --git a/crates/app-iced/src/pages/settings/tests/general_section.rs b/crates/app-iced/src/pages/settings/tests/general_section.rs
new file mode 100644
index 0000000..8825de1
--- /dev/null
+++ b/crates/app-iced/src/pages/settings/tests/general_section.rs
@@ -0,0 +1,122 @@
+//! 「General」分组自己的断言（M106 `I18NFOLLOW` 重写：语言行换成真控件）。
+//!
+//! **归 language+appearance 线**。接真控件那天要改**两个**文件（M101 r2 删掉了原先的第 3 处跨
+//! section 绊线）：`settings/general.rs` + 本文件 `the_general_group_is_still_demo_rows`。
+//!
+//! M106（`I18NFOLLOW`）已经接了这一组的语言行。用户报的 bug 有两半：**界面全英文**（探测对了
+//! 但没人用）与**设置页写着 `English (System)`**（一行硬编码假值）。本文件的断言守后半：那行
+//! 假值不许回来，语言行的三档必须真的能在两套目录里取到词。
+//!
+//! 接线形状：语言行的正文由 [`general::body`] 画（入口是 `pages::settings` 的 `GENERAL_GROUP`
+//! 按下标分发），`GROUP.body` 仍是 `None`——那个槽位的签名是 `fn(&Ui, States) -> Option<Element>`，
+//! `States` 只有 `appearance` + `groups` 两格，装不下「当前语言档位」。所以 M101 r2 的
+//! 「本组接真控件只需改两个文件」这条口径，在语言行上**仍然是两个文件**。
+
+use super::super::general;
+use unlucky_design::icons::IconKind;
+use unlucky_i18n::LangChoice;
+use unlucky_i18n::{Key, Lang};
+
+/// 这一组的**静态演示行**：语言那一行已经换真控件，所以只剩三行。
+///
+/// 抓得住：①四条线并行合并时把别人的行粘到本文件；②语言行被「顺手」加回静态表——
+/// 那等于把用户看到的假值又写回去（它的值必须跟着语言变，静态表做不到）。
+/// 抓不住：真控件画出来长什么样（那是截图验收的事，见 `DevDocs/artifacts/m106/`）。
+#[test]
+fn the_general_group_keeps_theme_startup_and_close_as_static_rows() {
+    let rows: Vec<(&str, &str)> = general::GROUP.rows.to_vec();
+    assert_eq!(
+        rows,
+        vec![
+            ("Theme", "Follow system"),
+            ("Startup page", "Instances"),
+            ("Close button", "Exit to tray"),
+        ]
+    );
+}
+
+/// 左列图标（`IconKind::Settings`）。分组图标是左列的语义标签，换掉就是换观感。
+#[test]
+fn the_general_group_keeps_its_icon() {
+    assert_eq!(general::GROUP.icon, IconKind::Settings);
+}
+
+/// **回归绊线（用户原话）**：`"English (System)"` 那条硬编码字面量不许回来。
+///
+/// 抓得住：①原来那条「这一组还没接真控件」在接上之后没更新（静默变假绿）；
+///         ②语言行**退回静态演示行**（哪怕换个说法，只要还写着「English」就是同一个 bug 的复盘）。
+/// 抓不住：界面上真控件长什么样、三档选项名对不对（下一条与截图各管一段）。
+///
+/// 现状（M106）：`body` 仍是 `None`（语言行走 `GENERAL_GROUP` 的按下标分发），但这一组**已经**
+/// 有真控件了——所以这里断言的**不再是「还没接」**，而是「不许回到静态行」。
+#[test]
+fn the_language_row_is_not_a_static_string() {
+    for (label, value) in general::GROUP.rows {
+        assert_ne!(
+            *label, "Language",
+            "语言行必须走真控件（pages::Language），不许回到静态演示行"
+        );
+        assert!(
+            !value.contains("English"),
+            "静态行里不许再出现写死的语言名：{value}"
+        );
+    }
+}
+
+/// 语言行**三档**，且在**两套目录**里都有词（中文界面不该出现 `⟪missing⟫`）。
+///
+/// 抓得住：①少一档（用户就没法切回去了）；②标签 key 只加进了中文表（英文界面上一档变成
+/// `⟪missing⟫`）；③回显那句的占位符名字与调用点对不上（会原样印出 `{language}`）。
+/// 抓不住：译文翻得对不对（金表 + `chinese_catalog_is_actually_chinese` 管那一层）。
+#[test]
+fn the_language_row_offers_three_choices_in_both_languages() {
+    assert_eq!(
+        LangChoice::ALL.len(),
+        3,
+        "跟随系统 / 简体中文 / 英文，少一档就切不回来"
+    );
+
+    for lang in Lang::ALL {
+        let catalog = lang.catalog();
+        for choice in LangChoice::ALL {
+            assert!(
+                catalog.get(choice.label_key()).is_some(),
+                "{} 在 {} 目录里没词",
+                choice.label_key().name(),
+                lang.tag()
+            );
+        }
+
+        // 「界面当前使用：⟨语言名⟩」——中文系统下这句必须真的出现「简体中文」。
+        let effective = catalog.text(LangChoice::Fixed(*lang).label_key());
+        let line = catalog.render(Key::SettingsLanguageEffective, &[("language", effective)]);
+        assert!(line.contains(effective), "回显没带上语言名：{line}");
+        assert!(!line.contains('{'), "占位符没被替换：{line}");
+    }
+
+    // 中文系统 + 跟随系统 ⇒ 回显是「简体中文」（用户报的 bug 的直接判据）。
+    let zh = Lang::ZhCn.catalog();
+    assert_eq!(
+        zh.render(
+            Key::SettingsLanguageEffective,
+            &[(
+                "language",
+                zh.text(LangChoice::Fixed(Lang::ZhCn).label_key())
+            )]
+        ),
+        "界面当前使用：简体中文"
+    );
+}
+
+/// **绊线**：这一组仍不走 `Group.body`。
+///
+/// 为什么不是「接了真控件」：语言行的入口是 `pages::Language`（`GENERAL_GROUP` 那条分发），
+/// 而 `Group.body` 那个槽位的签名是 `fn(&Ui, &pages::appearance::State)`——装不下「当前语言档位」。
+/// 谁把语言行塞进 `body`，就得先给它换签名（那会改到另外三组的文件），这条断言逼他先想一遍。
+#[test]
+fn the_general_group_does_not_use_the_appearance_body_slot() {
+    assert!(
+        general::GROUP.body.is_none(),
+        "General 的真控件走 pages::Language 入口（见 settings/mod.rs 的 GENERAL_GROUP），不是 body"
+    );
+}
diff --git a/crates/app-iced/src/pages/settings/tests/java_section.rs b/crates/app-iced/src/pages/settings/tests/java_section.rs
new file mode 100644
index 0000000..0dbcef4
--- /dev/null
+++ b/crates/app-iced/src/pages/settings/tests/java_section.rs
@@ -0,0 +1,57 @@
+//! 「Java」分组自己的断言（M100 **新增**：`settings/tests.rs` 里一条 section 断言都没有，
+//! 那 7 条全是跨 section 的；所以这 3 条是新增，不是搬移）。
+//!
+//! **归 java 线**。接真控件那天要改**两个**文件（M101 r2 删掉了原先的第 3 处跨 section 绊线，
+//! 见 `tests/mod.rs` 的 `every_line_can_be_wired_alone` 说明）：
+//! 1. `settings/java.rs`（`body = Some(java::body)` + 渲染器）；
+//! 2. 本文件 `the_java_group_is_still_demo_rows`（把 `is_none()` 改成 `is_some()`）。
+//!
+//! download / general 同型。
+//!
+//! 判据（M100 交付里正面回答的那条）：给 java 加一条**新断言** = **只改本文件**。
+
+use super::super::java;
+use unlucky_design::icons::IconKind;
+
+/// 这一组的行集合（标签 + 值）。改文案就是改观感，所以逐条钉住，而不是「非空就行」。
+///
+/// 抓得住：① 四条线并行合并时把别人的行粘到本文件（四份 `GROUP` 长得几乎一样，最容易整块贴错）；
+/// ② 漏掉/多出一条行；③ 标签与值错位（`("Default memory", "4 GiB")` 被写成 `"8 threads"`）。
+/// 抓不住：值对不对（`Temurin 21.0.4` 是不是本机真检测到的运行时）——那是接线后真数据源的事。
+#[test]
+fn the_java_group_shows_runtime_memory_and_jvm_arguments() {
+    let rows: Vec<(&str, &str)> = java::GROUP.rows.to_vec();
+    assert_eq!(
+        rows,
+        vec![
+            ("Runtime", "Temurin 21.0.4"),
+            ("Default memory", "4 GiB"),
+            ("JVM arguments", "Automatic"),
+        ]
+    );
+}
+
+/// 左列图标必须是 `IconKind::Folder`。
+///
+/// 抓得住：谁把它换回 `IconKind::Play`——那是视觉复审 P2-3 判过的（`Play` 是填充字形，
+/// 和同屏其它描边图标语汇打架；Java 组讲的是运行时安装位置，目录图标语义才对得上）。
+/// 抓不住：图标画出来的大小/线宽（那是 tokens 层的事）。
+#[test]
+fn the_java_group_keeps_the_folder_icon_from_the_visual_review() {
+    assert_eq!(java::GROUP.icon, IconKind::Folder);
+}
+
+/// **绊线**：这一组还没接真控件，画的是演示行。
+///
+/// 抓得住：java 线接上了 `body` 却没更新这里的期望（那会让本文件静默变成假绿）。
+/// 抓不住：界面上真控件长什么样。
+///
+/// 接真控件时：把 `is_none()` 改成 `is_some()`，**只改这一行**（M101 r2 起不必再去
+/// `tests/mod.rs` 报到：那条跨 section 聚合绊线已删，见那里的 `every_line_can_be_wired_alone`）。
+#[test]
+fn the_java_group_is_still_demo_rows() {
+    assert!(
+        java::GROUP.body.is_none(),
+        "Java 还没接真控件：接了就改本断言"
+    );
+}
diff --git a/crates/app-iced/src/pages/settings/tests/mod.rs b/crates/app-iced/src/pages/settings/tests/mod.rs
new file mode 100644
index 0000000..3159dfc
--- /dev/null
+++ b/crates/app-iced/src/pages/settings/tests/mod.rs
@@ -0,0 +1,198 @@
+//! 设置页的**跨 section** 守门测试（M100：跨 section 的留在这里，section 自己的断言**新增**在
+//! `tests/<section>_section.rs`）。
+//!
+//! ## 为什么这里只剩「跨 section」的断言
+//!
+//! 设置页正文接下来由四条线并行接（java / download / language+appearance / ai+about）。每条线要能
+//! **只改自己的测试**就跑通，所以「某一组自己的行文案 / 图标 / body 现状」一律放在
+//! `tests/<section>_section.rs`（M100 **新增**的 12 条，不是从本文件搬过去的——本文件在 `main`
+//! 上就只有下面这 7 条跨 section 断言，一条 section 断言都没有）；本文件只留**必须四组一起看**的
+//! 断言——下放到任何单组文件里，都会变成「某组替其它三组说话」，四条线并行时必然互相踩。
+//!
+//! 判据（M100 报告里正面回答的那条）：**给 java 加一条新断言，改几个文件？** —— 1 个
+//! （`tests/java_section.rs`）。本文件不动。
+//!
+//! 但「java 线**接真控件**那天改几个文件」是另一回事，答案是 **2 个**（M101 r2 订正：
+//! M100 之后曾是 3 个，第 3 处就是本文件末尾那条聚合绊线
+//! `only_the_appearance_group_carries_a_real_control_body`，它被四条 per-group 断言完全蕴含、
+//! 已在 M101 r2 删除）：`settings/java.rs`（写 body）+ `tests/java_section.rs` 的
+//! `the_java_group_is_still_demo_rows`（它断言 `body.is_none()`，接上就红）。download / general 同型。
+//!
+//! ## ai+about 线要额外改本文件的两处（M100 r1 复审 p3-4）
+//!
+//! 它加第 5 组时，除了 `settings/mod.rs` 的 `GROUPS`，**本文件还有两处必改**：
+//! 1. 顶部 `mod ai_section;`（新测试文件要挂进来，否则永远不编译、永远不跑）；
+//! 2. [`the_split_kept_the_left_column_order`] 断言的是**字面量** `["General","Appearance",
+//!    "Java","Downloads"]`，加第 5 组必红——这是刻意的：左列顺序变了就是观感变了，要人确认。
+//!    另外 `the_appearance_group_is_where_the_module_says_it_is` 依赖 `APPEARANCE_GROUP == 1`，
+//!    **把新组插在 Appearance 前面会连带红**（所以新组应该排最后）。
+//!
+//! ## 站位
+//!
+//! 本文件是 `pages::settings::tests`：`super` = `pages::settings`，`super::super` = `pages`。
+//!
+//! ## 命名
+//!
+//! 子模块带 `_section` 后缀，是为了不和 `use super::*` 带进来的分组模块（`settings::java` 等）
+//! 撞名——撞名时显式 `mod` 会静默盖掉 glob，读代码的人会以为 `java` 指的是分组的那个。
+
+mod appearance_section;
+mod download_section;
+mod general_section;
+mod java_section;
+
+use super::super::layout::{self, frame_metrics, measure_cap_px, PaneKit, SIDE_NAV_WIDTH};
+use super::*;
+use crate::pages::appearance::{APPEARANCE_GROUP, GROUP_LABEL};
+
+// --------------------------------------------------------------- 版面（不属于任何一组）
+
+/// 守的是**版面契约**：分组导航走 drawer 240（D33），不是 rail 的 88。
+///
+/// 不能下放到分组：它不是「某一组」的属性，而是整个 supporting-pane 的几何。
+#[test]
+fn side_nav_reuses_the_drawer_width() {
+    assert_eq!(SIDE_NAV_WIDTH, 240.0);
+    let metrics = frame_metrics(PaneKit::Supporting, 1180.0);
+    assert_eq!(metrics.secondary, Some(240.0));
+    assert_ne!(metrics.secondary, Some(layout::rail_width()));
+}
+
+/// 守的是**行宽上限**（逐行 67 字符 ≤72）在所有宽度档下都成立。
+///
+/// 不能下放：它是四个分组共用的正文列，任何一组把列撑宽都会连带别人。
+#[test]
+fn form_column_never_exceeds_the_measure_cap() {
+    for width in [720.0, 840.0, 1180.0, 1920.0] {
+        let metrics = frame_metrics(PaneKit::Supporting, width);
+        assert!(
+            metrics.column <= measure_cap_px() + f32::EPSILON,
+            "{width} 宽下表单列 {:?} 超过行宽上限",
+            metrics.column
+        );
+        assert!(metrics.column >= layout::measure_floor_px());
+    }
+}
+
+/// 守的是**窄窗退化**：<720 时侧列消失、分组改为按组堆叠。
+///
+/// 不能下放：退化是整页行为，四组一起变（单组文件里没法验证「侧列没了」）。
+#[test]
+fn narrow_window_stacks_the_groups_instead_of_the_side_nav() {
+    let narrow = frame_metrics(PaneKit::Supporting, 700.0);
+    assert_eq!(narrow.layout, PageLayout::SingleColumn);
+    assert!(narrow.secondary.is_none(), "窄窗不许留侧列");
+}
+
+// --------------------------------------------------------------- 注册表（四组一起看）
+
+/// 守的是**注册表的结构不变量**：每组都有名字、图标、演示行，且演示下标在范围内。
+///
+/// 下放不了：它遍历的是 `GROUPS`（四组拼出来的数组），单组文件拿不到其它三组，
+/// 而「新增一组忘了填 rows」正是这条要抓的。
+#[test]
+fn every_group_has_a_name_icon_and_rows() {
+    assert!(GROUPS.len() >= 3);
+    assert!(SELECTED < GROUPS.len());
+    for group in &GROUPS {
+        assert!(!group.name.is_empty());
+        assert!(!group.icon.icon().path.is_empty(), "{} 缺图标", group.name);
+        assert!(!group.rows.is_empty(), "{} 没有设置行", group.name);
+        for (label, value) in group.rows {
+            assert!(!label.is_empty() && !value.is_empty());
+        }
+    }
+}
+
+/// M93：设置页「外观」分组的下标与 `pages::appearance` 声明的常量必须一致。
+///
+/// 抓得住：谁把 `GROUPS` 的顺序调了却忘了改 `APPEARANCE_GROUP`（那样真控件会画到别的分组上，
+/// 而支持列显示的分组名也对不上）。
+/// 抓不住：控件本身画得对不对（那由截图与 app 侧测试管）。
+///
+/// 下放不了：它同时读 `GROUPS`（注册表）与 `pages::appearance` 的常量，横跨两处；
+/// 放进 `appearance_section.rs` 会让「外观那条线」替注册表顺序作证。
+#[test]
+fn the_appearance_group_is_where_the_module_says_it_is() {
+    assert_eq!(GROUPS[APPEARANCE_GROUP].name, GROUP_LABEL);
+    assert!(SELECTED < GROUPS.len(), "演示下标仍在范围内");
+}
+
+/// M99：拆分后**左列顺序**必须还是拆分前那四项（顺序变了就是观感变了，不是「纯搬移」）。
+///
+/// 抓得住：① 注册表顺序被调换（`GROUPS` 是四条线各自文件拼出来的，最容易在合并时错位）；
+/// ② 某组被误删/误加（长度不等）。
+/// 抓不住：组内那些行还在不在、译文对不对（各组自己的文件与 `catalog` 金表各管一段）。
+///
+/// 下放不了：它是一句「四组顺序 = 这四个名字」的断言，任何单组文件都只能看到自己那一个名字。
+#[test]
+fn the_split_kept_the_left_column_order() {
+    let names: Vec<&str> = GROUPS.iter().map(|group| group.name).collect();
+    assert_eq!(names, vec!["General", "Appearance", "Java", "Downloads"]);
+}
+
+/// M101 r2：`settings/mod.rs` 里**不许出现任何一组的 `State` 类型**（r1 复审 P1 的判据钉在这里）。
+///
+/// 抓得住：谁把状态漏斗拆回去——让 `view` / `form` 直接收 `appearance::State` 或某一组的 `State`
+/// （那正是四条线「加一个字段就要改本文件」的形状，本次复审要求修掉的就是它）。
+/// 抓不住：各组的**字段**（那些活在各组自己的文件里，本文件本来就不该知道，也就没有可断言的东西）。
+///
+/// **M106 的例外要读清楚**：General 已经接了真控件（语言行），但它**不走 `Group.body`**——
+/// 那个槽位的签名是 `fn(&Ui, States) -> Option<Element>`，`States` 只有 `appearance` + `groups`
+/// 两格，装不下「当前语言档位 + 生效语言」。它走 `settings::view` 的 `language` 形参 +
+/// `GENERAL_GROUP` 那条按下标分发，`body` 仍是 `None`，所以本断言不动。
+/// 判据没变：**`body: Some(..)` 仍然只有外观组**。
+#[test]
+fn the_settings_module_does_not_name_any_group_state() {
+    let source = include_str!("../mod.rs");
+    let forbidden = [
+        "appearance::State",
+        "java::State",
+        "download::State",
+        "language_appearance::State",
+        "ai_about::State",
+    ];
+
+    let hits: Vec<&str> = forbidden
+        .into_iter()
+        .filter(|needle| source.contains(needle))
+        .collect();
+
+    assert!(
+        hits.is_empty(),
+        "`settings/mod.rs` 里出现了具体的组状态类型 {hits:?}：状态漏斗被打回去了——\
+         四条填页线又要改本文件。状态应该只在 `settings/state.rs` 的 `Groups` 与各组自己的\
+         `State` 定义里出现，本文件只转发 `States`"
+    );
+}
+
+///
+/// 为什么能删：`tests/appearance_section.rs` 断言外观组 `body.is_some()`，
+/// `tests/{general,java,download}_section.rs` 各自断言本组 `body.is_none()`——四条合起来与
+/// 原来那条聚合断言等价（成员与顺序另有 [`the_split_kept_the_left_column_order`] 钉住）。
+/// 删掉之后每条线「接真控件」只需改自己那 2 个文件，不必来本文件报到。
+///
+/// ## 删掉之后**抓不住什么**（tower 要求写明）
+///
+/// 那四条都只看**本组**，没有任何一条再断言「唯一性」——「四组里恰好一组挂了真控件」这件事
+/// **现在没有守卫**。具体漏法：
+///
+/// | 情形 | 还红吗 |
+/// |---|---|
+/// | 某条线接上 `body` 却忘了翻自己那条 `is_none()` | **红**（本组断言还在） |
+/// | 两条线的断言被同时改成 `is_some()`，页面上两组同时长真控件 | **绿着过去**（没人指认「唯一」） |
+/// | 谁把 `body: Some(..)` 挂到一个不该有的组、又顺手改了它那条断言 | **绿着过去** |
+///
+/// 接受这个损失的理由：接真控件是**每组各自的一次性动作**，谁做谁翻自己那一条；而「唯一」在
+/// 四条线并行的阶段是最容易假红的约束（一条线接上就替另外三条红）。想要回这条守卫，等四条线
+/// 都落地后在这里加一条**计数**断言（`GROUPS.iter().filter(|g| g.body.is_some()).count()`），
+/// 而不是现在钉死某个下标。
+///
+/// 这条 `#[test]` 本体已删；保留这段文档是为了让后来的人知道「这里原本有一条绊线」。
+#[test]
+fn every_line_can_be_wired_alone() {
+    // 判据是「每条线只改自己的文件」，不是任何一条具体断言：这里只钉住架子本身的两件事——
+    // ① 每组都有 `GROUP`（成员齐）；② 演示下标合法。真正的 per-group 断言在各自文件里。
+    assert_eq!(GROUPS.len(), 4, "四条线各一个分组");
+    assert!(SELECTED < GROUPS.len(), "演示下标仍在范围内");
+}
diff --git a/crates/app-iced/src/pages/tests.rs b/crates/app-iced/src/pages/tests.rs
new file mode 100644
index 0000000..469b772
--- /dev/null
+++ b/crates/app-iced/src/pages/tests.rs
@@ -0,0 +1,385 @@
+//! 页面层的**数值判据**：M90 接真组件后，「M84 的版面约束一条没破」这件事在这里钉死。
+//!
+//! 每条断言都注明了「抓得住什么 / 抓不住什么」——只测到纯函数，渲染真像素另见报告里的图与量测。
+
+use super::layout::{self, frame_metrics, measure_cap_px, PaneKit, WidthClass};
+use super::nav::NAV;
+use super::*;
+use unlucky_design::color::SchemeFlavor;
+use unlucky_design::typography::Platform;
+use unlucky_i18n::Lang;
+use unlucky_presenter::router::{NavSection, Route};
+
+use crate::theme::Families;
+
+const FAMILIES: Families = Families {
+    text: "Segoe UI",
+    display: "Segoe UI",
+    mono: "Consolas",
+};
+
+fn ui() -> Ui {
+    Ui::with_platform(SchemeFlavor::Light, Platform::Windows, FAMILIES)
+}
+
+#[test]
+fn five_screens_answer_the_mission_list() {
+    // M109：内容库是第五页（`download` 与 `content` 共用导航轨的「下载」项）
+    assert_eq!(Screen::ALL.len(), 5);
+    let slugs: Vec<&str> = Screen::ALL.iter().map(|screen| screen.slug()).collect();
+    assert_eq!(
+        slugs,
+        vec!["instances", "download", "content", "settings", "logs"]
+    );
+    for screen in Screen::ALL {
+        assert_eq!(Screen::from_slug(screen.slug()), Some(screen));
+    }
+    assert_eq!(Screen::from_slug("gallery"), None);
+}
+
+#[test]
+fn screens_declare_the_layout_their_page_needs() {
+    assert_eq!(Screen::Instances.kit(), PaneKit::ListDetail);
+    assert_eq!(Screen::Settings.kit(), PaneKit::Supporting);
+    assert_eq!(Screen::Download.kit(), PaneKit::Single);
+    // 内容库自带页内三栏，版面基座仍是单列（见 `pages/content/layout.rs`）
+    assert_eq!(Screen::Content.kit(), PaneKit::Single);
+    assert_eq!(Screen::Logs.kit(), PaneKit::Single);
+}
+
+/// 四个页面 × 三个对照宽度都能构图（不 panic、不依赖运行时）。
+///
+/// **抓得住**：`view` 的每条分支都能产出一棵树（含真空列表、无选中详情）。
+/// **抓不住**：像素级观感（那要出图，见报告）。
+#[test]
+fn every_screen_builds_at_the_three_comparison_widths() {
+    let ui = ui();
+    for width in [1180.0, 900.0, 700.0] {
+        for screen in Screen::ALL {
+            let model = demo_model(screen, width);
+            let _element: Element<'_, Message> = app(&ui, &model);
+        }
+    }
+}
+
+/// 空数据也要能构图（真实后端的「还没扫到实例」是常态，不能 panic）。
+#[test]
+fn an_empty_snapshot_still_builds() {
+    let ui = ui();
+    for screen in Screen::ALL {
+        let model = Model::new(screen, 1180.0, Some(screen.nav()));
+        let _element: Element<'_, Message> = app(&ui, &model);
+    }
+}
+
+/// 版面对照：同一页在 1180 / 900 / 700 三个宽度上必须**真的换版面**。
+#[test]
+fn the_width_comparison_really_changes_the_layout() {
+    let wide = frame_metrics(PaneKit::ListDetail, 1180.0);
+    let mid = frame_metrics(PaneKit::ListDetail, 900.0);
+    let narrow = frame_metrics(PaneKit::ListDetail, 700.0);
+
+    assert_eq!(wide.layout, PageLayout::ListDetail);
+    assert_eq!(mid.layout, PageLayout::ListDetail);
+    assert_eq!(narrow.layout, PageLayout::SingleColumn);
+
+    // 900 与 1180 同为 list-detail，但详情列必须真的变窄（不是硬编码 1180 的宽度）
+    assert!(mid.column < wide.column, "900 的详情列应窄于 1180");
+    assert!(narrow.secondary.is_none(), "700 不许再有列表列");
+}
+
+/// **M102 的对齐判据**：正文块左缘 = 页头标题左缘（`body_offset == 0`），块宽 = pane 宽（封顶 1440）。
+///
+/// 页头标题的左缘 = `rail + gutter`（`frame::header_bar` 的 padding 与 `frame::page` 的内容
+/// padding 是同一个 `metrics.gutter`）；正文块宽 = `frame::body_width`。
+///
+/// **抓得住**：块宽被改回 424（视觉复审 ①：左缘 422 对标题 112）、偏移不再是 0（居中/右对齐）、
+/// 上限被挪动；
+/// **抓不住**：`frame::body` 到底有没有照这两个数建盒子（那由
+/// [`frame_body_is_built_from_the_block_quantities`] 扫源码守）。
+#[test]
+fn body_block_starts_at_the_header_title_and_fills_the_page() {
+    for width in [600.0, 840.0, 900.0, 1180.0] {
+        let metrics = frame_metrics(PaneKit::Single, width);
+        let title_x = layout::rail_width() + metrics.gutter;
+        let block = frame::body_width(metrics);
+
+        assert_eq!(
+            block, metrics.available,
+            "{width}: 单列页块宽必须是可用宽度"
+        );
+        assert_eq!(
+            layout::block::body_offset(metrics),
+            0.0,
+            "{width}: 块必须贴左"
+        );
+        assert!(
+            (title_x + block + metrics.gutter - width).abs() < f32::EPSILON,
+            "{width}: 块从 {title_x} 起、宽 {block}，没铺到右页边距"
+        );
+        // 块变宽不等于一句话变宽：散文列仍 ≤424
+        assert!(metrics.column <= measure_cap_px() + f32::EPSILON);
+    }
+
+    // 验收尺寸 1180：标题左缘 112、块宽 1044（旧版居中时正文左缘是 422）
+    let wide = frame_metrics(PaneKit::Single, 1180.0);
+    assert_eq!(layout::rail_width() + wide.gutter, 112.0, "页头标题左缘");
+    assert_eq!(frame::body_width(wide), 1044.0, "正文块宽度");
+
+    // 极宽窗：块宽封顶 1440（tower 拍板），仍然贴左 ⇒ 右侧留白而不是居中
+    let huge = frame_metrics(PaneKit::Single, 2560.0);
+    assert_eq!(frame::body_width(huge), layout::block::BODY_MAX_WIDTH);
+    assert_eq!(frame::body_width(huge), 1440.0);
+    assert_eq!(layout::block::body_offset(huge), 0.0);
+    assert!(112.0 + frame::body_width(huge) < 2560.0);
+
+    // 两列版面的块宽 = 主列 pane（实例页正文在 panes 的主列里，不铺整页）
+    let two = frame_metrics(PaneKit::ListDetail, 1180.0);
+    assert_eq!(frame::body_width(two), two.main_pane);
+    assert_eq!(two.main_pane, 1180.0 - 88.0 - 48.0 - 336.0 - 24.0);
+}
+
+/// **源码结构**：`frame::body` 的盒子必须从「块宽 + 块偏移 + 贴左」这三个数建。
+///
+/// 为什么读源码：iced 的 `Element` 没有几何内省接口，`frame::body` 换成
+/// `centered(metrics.column, content)`（**就是视觉复审 ① 的改前写法**）不会红任何数值断言 ——
+/// M102 r1 的变异实测就是这样漏掉的（`pages/tests.rs` 那条只喂 `frame_metrics()` 与
+/// `body_width()`）。所以这条盯的是**摆法**：宽度来自 `body_width(metrics)`、左内边距来自
+/// `body_offset(metrics)`、`align_x` 只许是 `Start`（不写 = container 默认 Start，等价），
+/// 且不出现居中/散文列宽。
+///
+/// 扫的是 [`layout::source::region_across`]：`frame.rs` **加上** `layout/block.rs`，
+/// 于是「拆成 `body` → `body_impl`」（变异 H1）与「把盒子原样搬进 `block::body_box`」（变异 M6）
+/// 这两种**等价重构都不假红**，而「换成居中 424 盒子」照样红（变异 A）。
+///
+/// **抓得住**：盒子的**语义**变了（居中 / 用散文列宽 / 用 `centered`）；
+/// **抓不住**：`frame::centered(metrics.column, …)` 这种**与 `frame::body` 逐像素等价**的另写
+/// （r4 复审的 M1/M2 —— 按塔的裁定那是等价重构，护栏不该为此红），也不抓「先赋局部变量再建盒」。
+#[test]
+fn frame_body_is_built_from_the_block_quantities() {
+    let body = layout::source::region_across(
+        &[include_str!("frame.rs"), include_str!("layout/block.rs")],
+        "pub fn body<'a>(",
+    );
+
+    for needle in ["body_width(metrics)", "body_offset(metrics)"] {
+        assert!(
+            body.contains(needle),
+            "`frame::body` 必须从 {needle} 建盒（贴左 + 块宽 + 零偏移）：\n{body}"
+        );
+    }
+
+    // `align_x` 出现就必须是 Start：`.align_y(Alignment::Start)` 单独存在不算数（r2 复审 P2-3），
+    // 而「干脆不写 align_x」（container 默认 Start）视为等价重构，放行。
+    // 判的是**实参**而不是整段文本，所以 `Alignment::Start` 与 `iced::Alignment::Start` 同等放行
+    // （把盒子搬进别的模块后路径要写全，那是等价重构，不该假红 —— r4 复审的变异 M6）。
+    for argument in layout::source::call_arguments(&body, ".align_x(") {
+        assert!(
+            argument.trim().ends_with("Alignment::Start"),
+            "`frame::body` 的 align_x 只许是 Start，收到 {argument:?}：\n{body}"
+        );
+    }
+
+    for forbidden in [
+        "centered(",
+        "single_column(",
+        "metrics.column",
+        "Alignment::Center",
+    ] {
+        assert!(
+            !body.contains(forbidden),
+            "`frame::body` 里出现了 {forbidden:?} —— 那是居中 / 散文列宽的老写法：\n{body}"
+        );
+    }
+}
+
+/// **源码结构**：`frame::prose` 的宽度必须来自 `prose_width`（= `metrics.column`），不来自块宽。
+///
+/// M102 把两个量拆开后，「把散文塞进 1044 的块」不会红任何数值断言；这条盯接线。
+/// 与 `frame::body` 那条一样用 [`layout::source::region_across`]（`frame.rs` + `layout/block.rs`），
+/// 所以把盒子搬进 `layout/block.rs` 的等价重构不假红；抓的是**语义**（用块宽/可用宽度就红）。
+#[test]
+fn frame_prose_is_built_from_the_prose_width() {
+    let prose = layout::source::region_across(
+        &[include_str!("frame.rs"), include_str!("layout/block.rs")],
+        "pub fn prose<'a>(",
+    );
+
+    assert!(
+        prose.contains("prose_width(metrics)"),
+        "`frame::prose` 必须从 prose_width 取宽：\n{prose}"
+    );
+    for forbidden in ["body_width(", "metrics.available", "metrics.main_pane"] {
+        assert!(
+            !prose.contains(forbidden),
+            "`frame::prose` 里出现了 {forbidden:?} —— 散文会失去 72 字符行宽承诺：\n{prose}"
+        );
+    }
+}
+
+/// **源码结构（调用点）**：单列页必须调 `frame::body`，不许退回 `frame::single_column`。
+///
+/// r2 复审的变异 G：把四个页面文件里的 7 个调用点（`download.rs` 2 / `logs.rs` 3 /
+/// `instances.rs` 1 / `instances/detail.rs` 1）一键改回 `frame::single_column` ⇒ 420 条全绿，
+/// 而视觉复审 ① 原样回来。r2 的护栏只盯 `frame::body` **内部**，`single_column` 又是为设置页
+/// 合法保留的，所以「哪个页面用它」必须单独守。
+///
+/// 逐文件断言（而不是只数一条调用）：**同一个文件里退一个调用点**也会让
+/// `frame::single_column(` 出现，立刻红。
+///
+/// **抓得住**：页面退回居中的老写法（视觉复审 ① 原样）；
+/// **抓不住**：新增的页面文件（它不在这个清单里——新页要自己登记）。
+#[test]
+fn single_column_pages_call_the_body_box_not_the_centred_one() {
+    for (name, source) in [
+        ("download.rs", include_str!("download.rs")),
+        ("logs.rs", include_str!("logs.rs")),
+        ("instances.rs", include_str!("instances.rs")),
+        ("instances/detail.rs", include_str!("instances/detail.rs")),
+    ] {
+        assert!(
+            source.contains("frame::body("),
+            "{name} 没有调用 frame::body —— 正文块不再从块宽/块偏移建盒"
+        );
+        assert!(
+            !source.contains("frame::single_column("),
+            "{name} 退回了 frame::single_column（= 424 居中，视觉复审 ① 的原样）"
+        );
+    }
+
+    // 实例页窄窗那一屏的唯一入口也得走 body
+    let narrow =
+        layout::source::function_body(include_str!("instances/detail.rs"), "fn narrow_detail");
+    assert!(
+        narrow.contains("frame::body("),
+        "narrow_detail 没走 frame::body：\n{narrow}"
+    );
+}
+
+/// **M84 的行宽红线**：任何页、任何窗口宽度、任何版面，正文列都不许超过 424px。
+///
+/// **抓得住**：`frame_metrics` 的 `column`（页面唯一的列宽来源）不会越界；
+/// **抓不住**：页面自己绕过 metrics 写死宽度（那条由 `tests/no_hardcoded_tokens.rs` 的
+/// 「`.width(` 后面不许跟数字字面量」守门——它扫的是 `src/shell` + `src/pages` + `src/app`
+/// （M90 r2/P3-3 把 `app` 加进去了）。
+#[test]
+fn every_page_any_width_stays_under_the_measure_cap() {
+    let cap = measure_cap_px();
+    assert!((cap - 424.0).abs() < f32::EPSILON, "行宽上限必须是 424");
+
+    for screen in Screen::ALL {
+        for width in [416.0, 600.0, 700.0, 840.0, 900.0, 1180.0, 1600.0, 2560.0] {
+            let metrics = frame_metrics(screen.kit(), width);
+            assert!(
+                metrics.column <= cap + f32::EPSILON,
+                "{} @{width} 的正文列 {} 超过 424",
+                screen.slug(),
+                metrics.column
+            );
+        }
+    }
+}
+
+/// 断点 600 / 840 与 rail 88：M84 的三条硬值，接真组件后不许漂。
+///
+/// **抓得住**：布局系统的常量与 `WidthClass::of` 的分档；
+/// **抓不住**：导航轨真画出来是不是 88（那条要量像素；组件自己声明 88 见下一个断言）。
+#[test]
+fn the_three_frozen_numbers_are_unchanged() {
+    assert!((layout::BREAKPOINT_MEDIUM - 600.0).abs() < f32::EPSILON);
+    assert!((layout::BREAKPOINT_EXPANDED - 840.0).abs() < f32::EPSILON);
+    assert!((layout::rail_width() - 88.0).abs() < f32::EPSILON);
+
+    assert_eq!(WidthClass::of(599.9), WidthClass::Compact);
+    assert_eq!(WidthClass::of(600.0), WidthClass::Medium);
+    assert_eq!(WidthClass::of(839.9), WidthClass::Medium);
+    assert_eq!(WidthClass::of(840.0), WidthClass::Expanded);
+}
+
+/// **组件版**导航轨（M78 的 `NavigationRail`）声明的宽度必须与布局系统同值。
+///
+/// 注意这不是产品路径的实现（M90 r3 订正）：产品页的 rail 由 `shell/nav.rs` 画，组件版只服务
+/// `pages::app`（harness 出口图）与单测。这条守的是「组件与布局系统没分叉」，**不是**「产品 rail
+/// 没问题」——两套实现的漂移风险见 `pages/mod.rs` 偏离表 #10。
+///
+/// **抓得住**：`NavPaneGeometry::rail().width` == `layout::rail_width()` == 88；
+/// **抓不住**：容器圆角/药丸摆放的像素级正确性（组件自己的 probe 管），也抓不住 `shell/nav.rs`。
+#[test]
+fn the_real_rail_agrees_with_the_layout_system() {
+    let ui = ui();
+    let geometry = crate::app::components::navigation::geometry::NavPaneGeometry::of(
+        &ui,
+        crate::app::components::navigation::NavLayout::Rail,
+    );
+    assert!(
+        (geometry.width - layout::rail_width()).abs() < f32::EPSILON,
+        "真组件 rail 宽 {} 与布局系统的 {} 分叉了",
+        geometry.width,
+        layout::rail_width()
+    );
+}
+
+/// 路由 → 页面：四个一级页各自落到自己那页，`Detail` 落在实例页，`Agent` 没有页面（app 层回退）。
+#[test]
+fn routes_map_onto_pages() {
+    assert_eq!(Screen::of(&Route::Instances), Some(Screen::Instances));
+    assert_eq!(
+        Screen::of(&Route::Detail("survival".to_string())),
+        Some(Screen::Instances),
+        "详情页仍是实例页的那一屏"
+    );
+    assert_eq!(Screen::of(&Route::Download), Some(Screen::Download));
+    assert_eq!(Screen::of(&Route::Logs), Some(Screen::Logs));
+    assert_eq!(Screen::of(&Route::Settings), Some(Screen::Settings));
+    assert_eq!(Screen::of(&Route::Agent), None, "AI 独立页还没有页面实现");
+}
+
+/// 导航轨的每一项都指向一个**它能高亮的**路由（点完不会出现「没有任何项高亮」的悬空态）。
+///
+/// **抓得住**：`NAV` 表的 5 项与 `Screen::nav` / `Route::nav` 三者没有错位；
+/// **抓不住**：点下去真的换页（那是 `app/update.rs` 的 `Navigate` 分支 + 集成图）。
+#[test]
+fn every_rail_item_points_at_a_route_that_highlights_it() {
+    assert_eq!(NAV.len(), 5, "导航轨 5 项（4 个一级页 + AI）");
+    let catalog = Lang::En.catalog();
+
+    for (section, _icon, label, route) in NAV {
+        assert!(!catalog.text(label).is_empty(), "{} 没有文案", label.name());
+        assert_eq!(
+            route.nav(),
+            section,
+            "{} 指向的 {route:?} 高亮的是 {:?}",
+            label.name(),
+            route.nav()
+        );
+    }
+    assert_eq!(
+        NAV[4].0, None,
+        "AI 项没有导航高亮（Route::Agent.nav() 是 None）"
+    );
+
+    // 四个一级页的 page-nav 与 route-nav 同源
+    assert_eq!(Screen::Instances.nav(), NavSection::Instances);
+    assert_eq!(Screen::Settings.nav(), NavSection::Settings);
+}
+
+/// 演示模型：12 行 + 1 条选中详情（M84 的出图基线就靠这份数据）。
+#[test]
+fn the_demo_model_carries_the_m84_baseline() {
+    let model = demo_model(Screen::Instances, 1180.0);
+    assert_eq!(model.instances.rows.len(), 12);
+    let detail = model.instances.detail.as_ref().expect("演示数据有选中项");
+    assert_eq!(detail.meta.len(), 6, "元信息 6 格");
+    assert!(detail.note.is_some(), "演示数据带正文段");
+    assert_eq!(model.active, Some(NavSection::Instances));
+
+    // 其余三页不带实例数据（占位视觉不读它）
+    for screen in [Screen::Download, Screen::Settings, Screen::Logs] {
+        let model = demo_model(screen, 1180.0);
+        assert!(
+            model.instances.rows.is_empty(),
+            "{} 不该带实例数据",
+            screen.slug()
+        );
+    }
+}
diff --git a/crates/app-iced/src/platform/locale.rs b/crates/app-iced/src/platform/locale.rs
new file mode 100644
index 0000000..bd28142
--- /dev/null
+++ b/crates/app-iced/src/platform/locale.rs
@@ -0,0 +1,301 @@
+//! 系统语言的**真值源**（D28）：Windows 走 `reg.exe` 读注册表——**零 `unsafe`、零 FFI、零新依赖**。
+//!
+//! ## 为什么是子进程而不是 FFI
+//!
+//! 先例是 M73 的壁纸探测（`crates/core/src/platform/wallpaper/windows.rs`）：同样是「Windows 上
+//! 只有注册表知道答案」的问题，它用 `reg.exe query` 解决，`unsafe` 一个没加。本 crate 的 `unsafe`
+//! 只允许出现在 [`crate::platform::win32`]（D36 的纪律），所以这里照抄那条路。
+//!
+//! 为什么不 `GetUserDefaultLocaleName`：它要 FFI，而它对**本用途**并不比注册表准——Windows 的
+//! 「区域格式」与「显示语言」本来就是两个设置，两者都有各自的说法（见下面的诚实边界）。
+//!
+//! ## 读什么、按什么顺序
+//!
+//! 1. `HKCU\Control Panel\International` 的 `LocaleName`——Win7+ 都有，值就是 `zh-CN` 这种标签，
+//!    [`unlucky_i18n::Lang::from_locale`] 直接吃得下；
+//! 2. 读不到 `LocaleName` 时退到同一个键的 `Locale`（8 位十六进制 LCID，如 `00000804`），
+//!    用一张**很短的**表翻成标签；表里没有的返回 `None`（宁可英文，也不猜错语种）。
+//!
+//! 优先级链在 [`unlucky_i18n::lang::resolve`]：**`ui.language` 显式值 > 本模块 > 环境变量 > 英文**。
+//!
+//! ## 诚实边界（抓得住什么 / 抓不住什么）
+//!
+//! - **抓得住**：`reg query` 输出的解析（含 CRLF、空值、值名大小写）、`LocaleName` 缺失时退 LCID
+//!   的分支、命令失败/缺失时的 `None`；
+//! - **抓不住**：①`LocaleName` 是**区域格式**，用户完全可能在设置里把「显示语言」改成英文而区域
+//!   仍是 `zh-CN`（或反过来）——真要读显示语言得 `GetUserDefaultUILanguage`（FFI）或多语言
+//!   用户界面注册表（`...\Control Panel\Desktop` 的 `PreferredUILanguages`，本 mission 未做）；
+//!   ②策略禁用 `reg.exe` / Wine 环境 → `None` → 落到环境变量 → 英文；
+//!   ③代码页（`chcp`）与这里无关，注册表值不受它影响。
+
+use unlucky_i18n::lang::LocaleSource;
+
+/// 语言相关的注册表键。
+const INTERNATIONAL_KEY: &str = r"HKCU\Control Panel\International";
+
+/// 首选值名：值是 BCP-47 风格标签（`zh-CN`）。
+const LOCALE_NAME_VALUE: &str = "LocaleName";
+
+/// 兜底值名：值是 8 位十六进制 LCID（`00000804`）。
+const LOCALE_VALUE: &str = "Locale";
+
+/// 常见 LCID → 语言的短表（**故意短**：不认识的返回 `None`，让链路落到英文）。
+///
+/// 覆盖面：中文四地 + 英语三地 + 几个大语种。这张表只在 `LocaleName` 缺失时用到，
+/// 而 `LocaleName` 从 Win7 起就有，所以它实际上是「老系统 / 被裁剪的系统」专用。
+const LCID_TAGS: &[(&str, &str)] = &[
+    ("00000804", "zh-CN"),
+    ("00000404", "zh-TW"),
+    ("00000c04", "zh-HK"),
+    ("00001004", "zh-SG"),
+    ("00000409", "en-US"),
+    ("00000809", "en-GB"),
+    ("00000c09", "en-AU"),
+    ("00000411", "ja-JP"),
+    ("00000412", "ko-KR"),
+    ("00000407", "de-DE"),
+    ("0000040c", "fr-FR"),
+    ("00000410", "it-IT"),
+    ("00000c0a", "es-ES"),
+    ("00000416", "pt-BR"),
+    ("00000419", "ru-RU"),
+    ("00000415", "pl-PL"),
+    ("0000041f", "tr-TR"),
+    ("00000406", "da-DK"),
+    ("0000040b", "fi-FI"),
+    ("00000413", "nl-NL"),
+];
+
+/// 跑外部命令的接口（注入点：单测不 spawn 进程）。
+pub trait RegIo {
+    /// 跑一条命令取 stdout；命令缺失 / 非零退出 / 空输出都返回 `None`。
+    fn run(&self, program: &str, args: &[&str]) -> Option<String>;
+}
+
+/// 真实实现：`reg.exe` 子进程（非 Windows 上恒 `None`）。
+#[derive(Debug, Clone, Copy, Default)]
+pub struct HostReg;
+
+impl RegIo for HostReg {
+    fn run(&self, program: &str, args: &[&str]) -> Option<String> {
+        if !cfg!(windows) {
+            // 其它平台的「系统语言」真值源不是注册表；`resolve` 会继续往环境变量走。
+            return None;
+        }
+
+        let output = std::process::Command::new(program)
+            .args(args)
+            .output()
+            .ok()?;
+        // `Command::output` 对非零退出同样返回 `Ok`，退出码要单独判（`reg.exe` 查不到值就是非零）。
+        if !output.status.success() || output.stdout.is_empty() {
+            return None;
+        }
+        Some(String::from_utf8_lossy(&output.stdout).into_owned())
+    }
+}
+
+/// 系统语言源（实现 [`LocaleSource`]，日志里自称 `registry`）。
+#[derive(Debug, Clone, Copy, Default)]
+pub struct SystemLocale;
+
+impl LocaleSource for SystemLocale {
+    fn locale(&self) -> Option<String> {
+        detect_with(&HostReg)
+    }
+
+    fn label(&self) -> &'static str {
+        "registry"
+    }
+}
+
+/// 用给定 IO 读一次系统语言（`LocaleName` 优先，退 `Locale` 的 LCID）。
+pub fn detect_with(io: &dyn RegIo) -> Option<String> {
+    let by_name = io
+        .run(
+            "reg.exe",
+            &["query", INTERNATIONAL_KEY, "/v", LOCALE_NAME_VALUE],
+        )
+        .and_then(|text| parse_reg_sz(&text, LOCALE_NAME_VALUE))
+        .filter(|value| looks_like_tag(value));
+    if by_name.is_some() {
+        return by_name;
+    }
+
+    io.run("reg.exe", &["query", INTERNATIONAL_KEY, "/v", LOCALE_VALUE])
+        .and_then(|text| parse_reg_sz(&text, LOCALE_VALUE))
+        .and_then(|lcid| lcid_tag(&lcid))
+        .map(str::to_owned)
+}
+
+/// 取 `reg query <键> /v <值名>` 输出里某个 `REG_SZ` 值的原文。
+///
+/// 真机输出形如（本机 Windows 11 24H2 实测，CRLF）：
+///
+/// ```text
+/// HKEY_CURRENT_USER\Control Panel\International
+///     LocaleName    REG_SZ    zh-CN
+/// ```
+///
+/// 值名大小写不敏感（`reg.exe` 原样回显查询时给的名字）；值可能含空格，所以「值名 + 类型」
+/// 之后整段取原文，不 `split_whitespace` 再拼（会吃掉连续空格）。
+pub fn parse_reg_sz(text: &str, value_name: &str) -> Option<String> {
+    text.lines().find_map(|line| {
+        let trimmed = line.trim_start();
+        let name_end = trimmed.find(char::is_whitespace)?;
+        if !trimmed[..name_end].eq_ignore_ascii_case(value_name) {
+            return None;
+        }
+        let after_name = trimmed[name_end..].trim_start();
+        let kind_end = after_name.find(char::is_whitespace)?;
+        let value = after_name[kind_end..].trim();
+        (!value.is_empty()).then(|| value.to_owned())
+    })
+}
+
+/// LCID（十六进制原文，如 `00000804`）→ 标签（大小写不敏感）。
+pub fn lcid_tag(lcid: &str) -> Option<&'static str> {
+    LCID_TAGS
+        .iter()
+        .find(|(key, _)| key.eq_ignore_ascii_case(lcid.trim()))
+        .map(|(_, tag)| *tag)
+}
+
+/// 像不像一个语言标签（`zh-CN` / `en` / `zh-Hans-CN`）。
+///
+/// 只拦明显不是标签的东西（空值、带空格、带路径分隔符）——`reg.exe` 在某些策略下会回
+/// `REG_SZ` 空串或一长串本地化文本，那些不该被当成语言喂给 `from_locale`。
+fn looks_like_tag(value: &str) -> bool {
+    !value.is_empty()
+        && value.len() <= 35
+        && value
+            .chars()
+            .all(|ch| ch.is_ascii_alphanumeric() || ch == '-')
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// 本机 Windows 11 24H2 实测抓下来的两段原文（含 `\r\n`）。
+    const REAL_LOCALE_NAME: &str = "\r\nHKEY_CURRENT_USER\\Control Panel\\International\r\n    LocaleName    REG_SZ    zh-CN\r\n\r\n";
+    const REAL_LOCALE: &str = "\r\nHKEY_CURRENT_USER\\Control Panel\\International\r\n    Locale    REG_SZ    00000804\r\n\r\n";
+
+    struct FakeReg {
+        name: Option<&'static str>,
+        locale: Option<&'static str>,
+        fail: bool,
+    }
+
+    impl FakeReg {
+        fn both(name: Option<&'static str>, locale: Option<&'static str>) -> Self {
+            FakeReg {
+                name,
+                locale,
+                fail: false,
+            }
+        }
+    }
+
+    impl RegIo for FakeReg {
+        fn run(&self, program: &str, args: &[&str]) -> Option<String> {
+            assert_eq!(program, "reg.exe", "程序名写错就不是注册表读了");
+            assert_eq!(args[0], "query");
+            assert_eq!(args[1], INTERNATIONAL_KEY);
+            assert_eq!(args[2], "/v");
+            if self.fail {
+                return None;
+            }
+
+            let raw = match args[3] {
+                LOCALE_NAME_VALUE => self.name?,
+                LOCALE_VALUE => self.locale?,
+                other => panic!("没料到的值名：{other}"),
+            };
+            Some(format!(
+                "\r\nHKEY_CURRENT_USER\\Control Panel\\International\r\n    {}    REG_SZ    {raw}\r\n\r\n",
+                args[3]
+            ))
+        }
+    }
+
+    #[test]
+    fn real_registry_output_parses_to_the_locale_tag() {
+        // 抓得住：解析器与真机 `reg query` 输出格式之间的契约（CRLF、前导空白、值名与类型之间的
+        //         多个空格）。这两段夹具是真机抓的原文，不是我编的。
+        // 抓不住：这台机器的值本身会变（用户改区域设置）——测试只钉格式，不钉具体语言。
+        assert_eq!(
+            parse_reg_sz(REAL_LOCALE_NAME, LOCALE_NAME_VALUE).as_deref(),
+            Some("zh-CN")
+        );
+        assert_eq!(
+            parse_reg_sz(REAL_LOCALE, LOCALE_VALUE).as_deref(),
+            Some("00000804")
+        );
+        // 值名大小写不敏感（reg.exe 会原样回显查询里给的名字）
+        assert_eq!(
+            parse_reg_sz(REAL_LOCALE_NAME, "localename").as_deref(),
+            Some("zh-CN")
+        );
+        // 空值 = 没设（不是空串语言）
+        let empty = "    LocaleName    REG_SZ    \r\n";
+        assert_eq!(parse_reg_sz(empty, LOCALE_NAME_VALUE), None);
+        // 别的值名不该被误取
+        assert_eq!(parse_reg_sz(REAL_LOCALE_NAME, "Locale"), None);
+    }
+
+    #[test]
+    fn lcid_fallback_covers_chinese_and_english() {
+        // 抓得住：LCID 兜底表的关键格子（中文四地 + 英语三地）被改动或删掉；
+        //         以及「不认识就 None」这条（不许猜成某个语言）。
+        // 抓不住：这 20 条之外的语言——没有 `LocaleName` 的老系统上它们会落到英文。
+        assert_eq!(lcid_tag("00000804"), Some("zh-CN"));
+        assert_eq!(lcid_tag("00000804\r"), Some("zh-CN"), "要去空白");
+        assert_eq!(lcid_tag("00000404"), Some("zh-TW"));
+        assert_eq!(lcid_tag("00000C04"), Some("zh-HK"), "大小写不敏感");
+        assert_eq!(lcid_tag("00001004"), Some("zh-SG"));
+        assert_eq!(lcid_tag("00000409"), Some("en-US"));
+        assert_eq!(lcid_tag("00000411"), Some("ja-JP"));
+        assert_eq!(lcid_tag("00000437"), None, "表外语言必须 None");
+        assert_eq!(lcid_tag(""), None);
+    }
+
+    #[test]
+    fn detect_prefers_locale_name_and_falls_back_to_lcid() {
+        // 抓得住：两条取值路径的顺序（有 LocaleName 就不该再看 LCID），以及命令失败时的 None。
+        // 抓不住：真机注册表里到底有什么（下面的 windows_live 测试才碰真机）。
+        assert_eq!(
+            detect_with(&FakeReg::both(Some("zh-CN"), Some("00000409"))).as_deref(),
+            Some("zh-CN"),
+            "LocaleName 优先"
+        );
+        assert_eq!(
+            detect_with(&FakeReg::both(None, Some("00000804"))).as_deref(),
+            Some("zh-CN"),
+            "没有 LocaleName 才退 LCID"
+        );
+        assert_eq!(detect_with(&FakeReg::both(None, None)), None);
+        assert_eq!(
+            detect_with(&FakeReg {
+                name: Some("zh-CN"),
+                locale: Some("00000804"),
+                fail: true,
+            }),
+            None,
+            "命令失败就是 None，不许猜"
+        );
+        // 值名对但值不像标签（策略回了一串本地化文本）→ 不许当成语言
+        assert_eq!(detect_with(&FakeReg::both(Some("中文(简体)"), None)), None);
+    }
+
+    #[test]
+    #[cfg(windows)]
+    fn windows_live_registry_query_returns_a_tag() {
+        // 抓得住：`reg.exe` 这条路在本机真的通（spawn 成功、退出码为 0、输出能被解析）。
+        // 抓不住：它读到的「区域格式」是否等于用户想用的**界面语言**（见模块文档的诚实边界）。
+        let tag = SystemLocale.locale().expect("本机应当读得到 LocaleName");
+        assert!(!tag.is_empty());
+        assert!(looks_like_tag(&tag), "解析出来的不是语言标签：{tag:?}");
+        assert_eq!(SystemLocale.label(), "registry");
+    }
+}
diff --git a/crates/app-iced/src/platform/mod.rs b/crates/app-iced/src/platform/mod.rs
new file mode 100644
index 0000000..e4e1e3f
--- /dev/null
+++ b/crates/app-iced/src/platform/mod.rs
@@ -0,0 +1,170 @@
+//! 平台相关的窗口能力（P4 / D36 / M116）：整窗透明度与窗口圆角的**判据**、唯一 `unsafe` 落点，
+//! 以及系统语言真值源，三件事分居三处。
+//!
+//! - 本文件 = 整窗 α 的纯判据 [`effective_window_alpha`]：不读环境变量、不调 FFI、不碰窗口句柄，
+//!   只回答「按这个渲染后端和用户要的 α，最终该给窗口什么值」；
+//! - [`win32::corner`] = 圆角的纯判据 [`plan_corner`]（M116）：用户策略 × 系统版本 × 渲染档 →
+//!   来源与原因码。两个判据都**不碰** FFI，因此都能被断言证明；
+//! - [`win32::transparency`] = 唯一允许 `unsafe` 的文件（补 `WS_EX_LAYERED` +
+//!   `SetLayeredWindowAttributes`，以及 M116 的 `DwmSetWindowAttribute`）；
+//! - [`locale`] = 系统语言真值源（D28）：`reg.exe` 子进程读注册表，**零 `unsafe` / 零 FFI**。
+//!
+//! 为什么判据要单独拎出来：D36 的降级规则（α 下限 0.08 / `≤0` 一律拒绝 / CPU 档也允许
+//! 窗口级 α）**可以**被断言证明；而 FFI 的**视觉**结果在本仓库的验证环境（RDP + 虚拟显示
+//! 适配器）上没有参考价值。把可测的那一半独立出来，才有「有测试的判据 + 没测试的观感」这条
+//! 诚实的分界。
+
+use unlucky_presenter::prefs::WINDOW_ALPHA_MIN;
+
+use crate::Backend;
+
+pub mod locale;
+pub mod win32;
+
+/// 窗口圆角的**判定**（M116）住在 `win32::corner`：判据是 Windows 版本与 DWM 能力，
+/// 非 Windows 平台在这里恒得「直角」（平台没有可承诺的系统圆角）。
+pub use win32::corner::{plan_corner, CornerExclusion, CornerPlan, CornerSource};
+
+/// 本机 Windows 版本（`None` = 非 Windows / 读不到）。**进程内只探测一次**。
+///
+/// 为什么缓存：底层是 `reg.exe` 子进程（`unlucky_core::platform::windows_version`，实测约 50 ms），
+/// 而圆角判定会在启动、切档、热重载时各问一次。探测结果在进程生命周期内不会变。
+///
+/// 为什么走 `unlucky_presenter::prefs` 的重导出而不是 `unlucky_core` 直连：
+/// `unlucky-app-iced` 不直接依赖 core（分层：UI → presenter → core），这是既有的唯一通道。
+#[must_use]
+pub fn current_windows_version() -> Option<unlucky_presenter::prefs::WindowsVersion> {
+    static CACHED: std::sync::OnceLock<Option<unlucky_presenter::prefs::WindowsVersion>> =
+        std::sync::OnceLock::new();
+    *CACHED.get_or_init(unlucky_presenter::prefs::probe_windows_version)
+}
+
+/// 用户请求的整窗 α → 真正写进窗口的值（纯函数）。
+///
+/// - `requested <= 0.0`（含 `-0.0`）→ `None`：**拒绝整窗穿透**。α = 0 表示窗口内容全透明，
+///   用户会以为程序消失/卡死，所以这不是「合法的最小值」而是「不给设」（D36）。
+///   非有限值（`NaN` / `±∞`）同样 `None`——它们没有合法落点，也不该被 `clamp` 悄悄吞掉。
+/// - 其余一律夹到 [`WINDOW_ALPHA_MIN`]`..=1.0`。
+/// - 后端**不**参与「能不能用窗口级 α」的判断：D36 **修订**了 D27 的旧结论——
+///   CPU 渲染档同样允许整窗 α（CPU 档被限制的是面板 α / 玻璃 / 模糊，不是窗口 α）。
+///   因此三个后端分支给出同一个值；写成 `match` 是为了让「将来真分档」只改这一处，
+///   而不是让读代码的人以为这里漏了一个分支。
+#[must_use]
+pub fn effective_window_alpha(backend: Backend, requested: f64) -> Option<f64> {
+    if !requested.is_finite() || requested <= 0.0 {
+        return None;
+    }
+    match backend {
+        Backend::Gpu | Backend::Cpu | Backend::Auto => Some(requested.clamp(WINDOW_ALPHA_MIN, 1.0)),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::effective_window_alpha;
+    use crate::Backend;
+    use unlucky_presenter::prefs::WINDOW_ALPHA_MIN;
+
+    const BACKENDS: [Backend; 3] = [Backend::Gpu, Backend::Cpu, Backend::Auto];
+
+    #[test]
+    fn truth_table_valid_alpha_passes_through_every_backend() {
+        // GPU / CPU × 合法值：四个格子都要 Some（CPU 档不再强制不透明）。
+        for backend in BACKENDS {
+            assert_eq!(
+                effective_window_alpha(backend, 0.5),
+                Some(0.5),
+                "{backend:?}：合法 α 原样返回"
+            );
+            assert_eq!(effective_window_alpha(backend, 1.0), Some(1.0));
+            assert_eq!(
+                effective_window_alpha(backend, WINDOW_ALPHA_MIN),
+                Some(WINDOW_ALPHA_MIN)
+            );
+        }
+    }
+
+    #[test]
+    fn truth_table_out_of_range_is_clamped_not_refused() {
+        for backend in BACKENDS {
+            assert_eq!(
+                effective_window_alpha(backend, 0.001),
+                Some(WINDOW_ALPHA_MIN),
+                "{backend:?}：正数低于下限 → 夹到 0.08（钳位，不拒绝）"
+            );
+            assert_eq!(
+                effective_window_alpha(backend, 9.0),
+                Some(1.0),
+                "{backend:?}：高于 1.0 → 夹到 1.0"
+            );
+        }
+    }
+
+    #[test]
+    fn truth_table_non_positive_is_refused_on_every_backend() {
+        for backend in BACKENDS {
+            for requested in [0.0, -0.0, -0.01, -1.0] {
+                assert_eq!(
+                    effective_window_alpha(backend, requested),
+                    None,
+                    "{backend:?}：requested={requested} → 拒绝整窗穿透"
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn truth_table_non_finite_is_refused() {
+        // NaN 用 `<= 0.0` 判不出来（比较恒 false），所以必须先 `is_finite()`；
+        // 否则 NaN 会穿到 `clamp` 里再原样返回，变成「给窗口一个 NaN」。
+        for backend in BACKENDS {
+            for requested in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY] {
+                assert_eq!(
+                    effective_window_alpha(backend, requested),
+                    None,
+                    "{backend:?}：requested={requested} 不是有限值"
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn cpu_tier_is_not_forced_opaque() {
+        // D36 对 D27 的**修订**：旧文档写「CPU 档一律不透明」，这条测试钉住修订后的行为，
+        // 防止谁照着旧文档把 CPU 分支改回 `None`。
+        assert_eq!(effective_window_alpha(Backend::Cpu, 0.5), Some(0.5));
+        assert_eq!(effective_window_alpha(Backend::Gpu, 0.5), Some(0.5));
+    }
+
+    /// `appearance.palette_source` 的码值必须与 `design` 的 `Level::code()` 逐字一致。
+    ///
+    /// 为什么这条断言住在这里：`unlucky-core` 按分层纪律不依赖 `unlucky-design`，
+    /// 它的测试**看不到** design，所以 core 自己只能钉字面量。本 crate 同时依赖
+    /// `unlucky-design`（`Level`）与 `unlucky-presenter`（重导出 `PaletteSource`），
+    /// 是全仓唯一能真做这次对照的地方。
+    ///
+    /// 抓得住：design 侧改任一档的稳定码（例如把 `wallpaper` 改成 `desktop`）、或有人改了
+    /// core 的字符串表——两个方向都红（下面往返那条覆盖「只改一侧」）。
+    /// 抓不住：档位的**语义**是否仍对齐（只保证字符串一致），以及 UI 是否真按这个码值取色。
+    #[test]
+    fn palette_source_codes_match_design_level_codes() {
+        use unlucky_design::palette::Level;
+        use unlucky_presenter::prefs::PaletteSource;
+
+        for (source, level) in [
+            (PaletteSource::BackgroundImage, Level::BackgroundImage),
+            (PaletteSource::Wallpaper, Level::Wallpaper),
+            (PaletteSource::Preset, Level::Preset),
+        ] {
+            assert_eq!(
+                source.as_str(),
+                level.code(),
+                "core 的 {source:?} 码值与 design 的 {level:?} 不一致"
+            );
+            // 反方向：design 的码值喂回 core 必须还原成同一档（防「两个字符串互换了」）。
+            assert_eq!(PaletteSource::from_key_value(level.code()), source);
+            // 且必须真的在 core 的允许值表里（否则 schema 会拒绝写这个值）。
+            assert!(unlucky_presenter::prefs::PALETTE_SOURCES.contains(&level.code()));
+        }
+    }
+}
diff --git a/crates/app-iced/src/platform/win32/corner.rs b/crates/app-iced/src/platform/win32/corner.rs
new file mode 100644
index 0000000..b4a8c87
--- /dev/null
+++ b/crates/app-iced/src/platform/win32/corner.rs
@@ -0,0 +1,293 @@
+//! M116：窗口外框圆角的**判据**（纯函数，零 `unsafe`、零 FFI、零环境读取）。
+//!
+//! ## 判据为什么单独拎出来
+//!
+//! 「能不能圆」= 用户策略 × 系统版本 × 渲染档，这三件事**可以被断言证明**；而 DWM 的**视觉**
+//! 结果在本仓库的验证环境（RDP 断连、抓屏失效）上没有参考价值。把可测的那一半独立出来，
+//! 才有「有测试的判据 + 没测试的观感」这条诚实的分界（与 [`super::super::effective_window_alpha`]
+//! 同一套分法）。
+//!
+//! 真正下发给窗口的动作在 [`super::transparency`]（全仓唯一 `unsafe` 落点）。
+//!
+//! ## 平台矩阵（哪些是实测、哪些是推断）
+//!
+//! | 平台 | 我们做什么 | 依据级别 |
+//! |---|---|---|
+//! | Win11 / Server 2025（build ≥ 22000） | 下发 `DWMWCP_ROUND`（**请求**系统圆角） | 写入被接受 = **本机 API 实测**；「圆没圆 / 边缘什么样」= **未验**（无像素、回读不可用） |
+//! | Win10 及更早（build < 22000） | 直角；不做 `SetWindowRgn` 毛边默认 | 「该属性不存在」= **外部文档证据**；本机没有 Win10 |
+//! | macOS | 不主动加，交给系统 | **推断**（未真机验） |
+//! | Linux X11 / Wayland | 不承诺，直角即如实结果 | **推断**（未真机验） |
+//!
+//! ⚠️ **「Win11 上我们的窗口一定有圆角、边缘平滑」这句话本分支的证据不支持**，别写回去。
+//! 本机（Server 2025 build 26100、RDP 会话断开）测到的是：
+//! ① `DwmSetWindowAttribute(DWMWA_WINDOW_CORNER_PREFERENCE)` 被接受（三种窗口样式都接受）；
+//! ② `DwmGetWindowAttribute` 同一属性返回 `E_INVALIDARG`（本会话不支持回读，与窗口形状无关）；
+//! ③ DWM 的调整带只给**有 `WS_CAPTION|WS_THICKFRAME` 的窗口**：`EXTENDED_FRAME_BOUNDS −
+//!    GetWindowRect` 在有边框窗口上是 `+0,−7`，在**裸 `WS_POPUP` 假形状**上是 `+0,+0`。
+//!
+//! ⚠️ **第 ③ 条不能拿裸 popup 的读数去解释产品窗口**（M116 r4 复审订正）：产品窗口
+//! **不是** `WS_POPUP`（winit 只在带 owner 的弹出窗才加它；无边框观感来自 `WM_NCCALCSIZE`），
+//! 它带 `WS_CAPTION|WS_THICKFRAME` ⇒ 按同一张表应得 `+0,−7`，与 `decorated` 同族。
+//! 探针里 `product` / `product+alpha` 两行量的就是这个真实形状。
+//!
+//! ④ **整窗 α 会关掉圆角**（tower 裁定 A / D47：整窗透明度优先于 DWM 圆角）：α < 1 时我们补
+//! `WS_EX_LAYERED`，此时系统会忽略圆角请求——请求照样发出（日志里 `pref=` 有值），
+//! 只是不生效；α 回到 1.0 就恢复。日志用 `suppressed_by=window_alpha` 记这一条**观测事实**。
+//!
+//! 「圆角长什么样」归真机验收，证据目录见 `DevDocs/artifacts/m116/`。
+//!
+//! 后两行在本 crate 里落到同一格：探测不到 Windows 版本 ⇒ `UnknownOs` ⇒ 直角。
+//! 这是「不承诺」，不是「做不到」——两者的区别写在日志的原因码里。
+
+use unlucky_presenter::prefs::{WindowCorner, WindowsVersion, WIN11_MIN_BUILD};
+
+use crate::Backend;
+
+/// 一次「圆角该从哪来」的判定结果（M116）。
+///
+/// 只有两种来源，且**互相排斥**：
+///
+/// | 来源 | 谁画圆角 | 我们做什么 |
+/// |---|---|---|
+/// | [`CornerSource::Dwm`] | 系统合成器（是否真画、半径多少都不由我们定，也读不到） | 只下发 `DWMWA_WINDOW_CORNER_PREFERENCE` |
+/// | [`CornerSource::Square`] | 没人 | 明确下发 `DWMWCP_DONOTROUND`，把「方」也变成可观测的选择 |
+///
+/// **没有 `Self`（自绘圆角）这一档**，这是刻意的（用户定案 2026-11-03 + tower 裁定）：
+/// 窗口是 `decorations=false` + 自绘标题栏 + 整窗 `LWA_ALPHA`，自绘圆角意味着把内容层裁成圆角，
+/// 那会把标题栏三键与边缘缩放热区一起裁掉；系统也不暴露圆角半径（无 API 可读），
+/// 「固定 8/12/16」只是凭空维护一个数字。所以非 DWM 平台**就是直角**，并且日志里说明原因。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CornerSource {
+    /// DWM 系统圆角（Win11 / Server 2025 内核，build ≥ [`WIN11_MIN_BUILD`]）。
+    Dwm,
+    /// 直角（用户选择、系统不支持、或该平台不承诺）。
+    Square,
+}
+
+impl CornerSource {
+    /// 日志取值（`corner=… source=dwm|square`）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Dwm => "dwm",
+            Self::Square => "square",
+        }
+    }
+
+    /// 是否要求 DWM 真去画圆角。
+    #[must_use]
+    pub const fn is_dwm(self) -> bool {
+        matches!(self, Self::Dwm)
+    }
+}
+
+/// 为什么**不是** DWM 圆角（`None` = 就是 DWM 圆角）。日志里逐字打出来。
+///
+/// 为什么要这个枚举而不是一个 `bool`：用户报的现象是「别的窗口都有圆角，只有我们的没有」，
+/// 于是「没圆角」至少有四种完全不同的原因，混成一个 `square` 以后没人能分辨
+/// 「没生效」与「生效了但看不见」（M116 任务书原话）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CornerExclusion {
+    /// 用户在设置里选了「直角」。
+    UserSquare,
+    /// 系统太老：Win10 及更早（build < [`WIN11_MIN_BUILD`]）——DWM 没有这个偏好属性。
+    OsBuild,
+    /// 版本探测不出来（非 Windows / 注册表读不到 / 有东西在骗版本号）。
+    UnknownOs,
+    /// 非 DWM 平台上的软件渲染档：圆角只能靠自绘/`SetWindowRgn` 毛边路，D36 的
+    /// 「CPU 档不碰合成技巧」优先，所以退回直角。
+    CpuTier,
+}
+
+impl CornerExclusion {
+    /// 日志取值（`excluded_reason=…`）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::UserSquare => "user",
+            Self::OsBuild => "os-build",
+            Self::UnknownOs => "unknown-os",
+            Self::CpuTier => "cpu-tier",
+        }
+    }
+}
+
+/// 判定结果：来源 + 排除原因 + 平台版本（日志与测试共用）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct CornerPlan {
+    /// 圆角从哪来。
+    pub source: CornerSource,
+    /// `None` = 走 DWM；`Some(..)` = 走直角，并说明为什么。
+    pub excluded: Option<CornerExclusion>,
+    /// 探测到的 Windows 版本（`None` = 不是 Windows / 读不到）。
+    pub os: Option<WindowsVersion>,
+}
+
+impl CornerPlan {
+    /// 日志行：`corner=policy=system source=dwm os=10.0.26100 excluded_reason=none radius=system`。
+    ///
+    /// **`radius=system` 是刻意的**：系统不暴露 DWM 的圆角半径，我们也不自己定一个数字
+    /// （用户定案取消了 8/12/16 档），所以这一栏永远只说「系统决定」。
+    #[must_use]
+    pub fn log_line(&self, policy: WindowCorner) -> String {
+        let os = self
+            .os
+            .map_or_else(|| "unknown".to_owned(), |os| os.version_string());
+        format!(
+            "corner=policy={} source={} os={os} excluded_reason={} radius=system",
+            policy.as_str(),
+            self.source.as_str(),
+            self.excluded.map_or("none", CornerExclusion::as_str),
+        )
+    }
+}
+
+/// 判定「这一次窗口该不该有系统圆角」（纯函数，不调 FFI、不读环境）。
+///
+/// 真值表（`backend` 只影响**非 DWM** 平台，见下）：
+///
+/// | `policy` | `os.build` | backend | `source` | `excluded` |
+/// |---|---|---|---|---|
+/// | `Square` | 任意 | 任意 | `Square` | `UserSquare` |
+/// | `System` | `None` | 任意 | `Square` | `UnknownOs` |
+/// | `System` | `< 22000` | GPU/Auto | `Square` | `OsBuild` |
+/// | `System` | `< 22000` | CPU | `Square` | `CpuTier` |
+/// | `System` | `>= 22000` | 任意 | `Dwm` | `None` |
+///
+/// 为什么 CPU 档在 Win11 上**照样**用 DWM 圆角（**tower 2026-11-03 裁定，按此执行**）：
+/// D36 的 CPU 档约束针对的是**我们自己的渲染路径**（面板 α / 玻璃 / 模糊要关、不许拿透明叠加
+/// 去换效果），而 DWM 圆角是**合成器侧**的效果，不增加我们的 GPU/CPU 绘制负担。所以
+/// 「CPU 档关掉 Win11 圆角」不是 D36 的要求，而是凭空造一个没人要的降级。
+///
+/// 反过来在非 DWM 平台上，圆角只剩「自绘裁切 / `SetWindowRgn` 毛边」这两条**我们自己的**
+/// 合成技巧，那才是 D36 要拦的东西 ⇒ 那一格落 `cpu-tier` 而不是 `os-build`
+/// （同一个直角，**原因不同**，日志里可分辨）。
+#[must_use]
+pub fn plan_corner(
+    policy: WindowCorner,
+    os: Option<WindowsVersion>,
+    backend: Backend,
+) -> CornerPlan {
+    let square = |excluded| CornerPlan {
+        source: CornerSource::Square,
+        excluded: Some(excluded),
+        os,
+    };
+
+    if policy == WindowCorner::Square {
+        return square(CornerExclusion::UserSquare);
+    }
+    match os {
+        None => square(CornerExclusion::UnknownOs),
+        Some(os) if os.build < WIN11_MIN_BUILD => match backend {
+            Backend::Cpu => square(CornerExclusion::CpuTier),
+            Backend::Gpu | Backend::Auto => square(CornerExclusion::OsBuild),
+        },
+        Some(_) => CornerPlan {
+            source: CornerSource::Dwm,
+            excluded: None,
+            os,
+        },
+    }
+}
+
+/// 产品日志行的**唯一格式化落点**（纯函数：把四段文本拼成一个固定形状）。
+///
+/// ```text
+/// [corner] <context> corner=policy=system source=dwm os=10.0.26100 excluded_reason=none \
+///          radius=system pref=2 readback=? read_hr=0x80070057 frame=overlapped layered=on \
+///          suppressed_by=window_alpha
+/// ```
+///
+/// 为什么单独拎出来：`App::apply_window_corner` 要真句柄、真 DWM 才能跑，而**这一行的形状**
+/// 恰恰是「以后分辨没生效 / 生效了看不见」的唯一依据（M116 任务书原话）。形状必须在没有窗口的
+/// 环境里也能被断言——tower 2026-11-03 明确要求：不为了这行日志去构建 bin。
+///
+/// 参数里 `outcome` / `style` 由调用方给（`CornerOutcome::describe()` / `style_summary(hwnd)`），
+/// 本文件不依赖 FFI 层，因此可以在非 Windows 目标上编、也能被单测覆盖。
+///
+/// `suppressed_by` 是**观测事实**（tower 裁定 A / D47 要求的那一栏）：整窗 α < 1 时我们补了
+/// `WS_EX_LAYERED`，此时系统忽略圆角请求。配合同一行里的 `pref=`（请求确实发出去了）与
+/// `layered=`（分层位确实在），读者能自己推出「不是我们没发请求」——本函数不写结论性措辞。
+#[must_use]
+pub fn format_line(
+    context: &str,
+    plan: &CornerPlan,
+    policy: WindowCorner,
+    outcome: &str,
+    style: &str,
+    suppressed_by: Option<&'static str>,
+) -> String {
+    let mut line = format!(
+        "[corner] {context} {} {outcome} {style}",
+        plan.log_line(policy)
+    );
+    if let Some(reason) = suppressed_by {
+        line.push(' ');
+        line.push_str("suppressed_by=");
+        line.push_str(reason);
+    }
+    line
+}
+
+/// 一次「已经下发过」的**指纹**：只由判定本身与「当时有没有窗口」组成，不含读数。
+///
+/// 为什么需要它：设置页的滑条（整窗 α / 面板 α / 暗化）每动一下就触发一次外部外观变更，
+/// 而圆角与那些键**无关**。没有去重时，拖一次滑条就会刷出一串
+/// `[corner] change …`，把「分辨有没有生效」的那条日志淹掉（M116 r1 复审 P2-4）。
+///
+/// 指纹**刻意不含 `pref=` / `readback=` 这类读数**：那些只有真下发才知道，拿它们参与比较
+/// 会变成「自己比较自己」。判定没变就不重下、也不重记——这也是「同一策略 N 次只记 1 行」的判据。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct CornerApplied {
+    /// 当时的策略（`system` / `square`）。
+    pub policy: WindowCorner,
+    /// 判定出来的来源。
+    pub source: CornerSource,
+    /// 直角时的原因码（`None` = 走 DWM）。
+    pub excluded: Option<CornerExclusion>,
+    /// 下发时**有没有窗口句柄**：`false → true` 必须重下（首次拿到 HWND 时才真能设属性）。
+    pub has_window: bool,
+    /// 整窗 α 是否 < 1（= 我们补了 `WS_EX_LAYERED`，系统会忽略圆角请求）。
+    ///
+    /// 进指纹是为了让「α 从 1.0 拉低 / 拉回 1.0」各触发一次重下与一行日志——那两次的
+    /// 系统行为确实不同，不重记就看不出来。
+    pub suppressed_by_window_alpha: bool,
+}
+
+impl CornerApplied {
+    /// 由判定 + 「有没有句柄」+ 「整窗 α 是否补了分层」构造指纹。
+    #[must_use]
+    pub const fn new(
+        policy: WindowCorner,
+        plan: &CornerPlan,
+        has_window: bool,
+        suppressed_by_window_alpha: bool,
+    ) -> Self {
+        Self {
+            policy,
+            source: plan.source,
+            excluded: plan.excluded,
+            has_window,
+            suppressed_by_window_alpha,
+        }
+    }
+}
+
+/// 这一次要不要真的下发 / 记日志（纯函数）。
+///
+/// `false` = 判定与上次完全一致（策略、来源、原因码、有没有句柄都没变）⇒ **不动窗口、不打日志**。
+/// `true` 的四种情形：首次、换档、系统版本变化导致判定变化、首次拿到句柄。
+///
+/// 注意：判定不变而上次**下发失败**时这里也返回 `false`——失败原因（`pref=none hresult=…`）
+/// 已经在那一行日志里了，重复重试只会刷屏；真要重试应该由「换档 / 重启」触发，不是每帧。
+#[must_use]
+pub fn needs_redispatch(previous: Option<&CornerApplied>, next: &CornerApplied) -> bool {
+    match previous {
+        None => true,
+        Some(previous) => previous != next,
+    }
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/app-iced/src/platform/win32/corner/tests.rs b/crates/app-iced/src/platform/win32/corner/tests.rs
new file mode 100644
index 0000000..796db2d
--- /dev/null
+++ b/crates/app-iced/src/platform/win32/corner/tests.rs
@@ -0,0 +1,289 @@
+//! `win32::corner` 的单测（M116 从 `corner.rs` 搬出来：那个文件要守 400 行上限，
+//! 而日志行的形状断言本身就有几十行）。
+//!
+//! 判据与真实读数的出处：`DevDocs/artifacts/m116/probe-table.md`。
+
+use super::{format_line, plan_corner, CornerExclusion, CornerPlan, CornerSource};
+use crate::Backend;
+use unlucky_presenter::prefs::{WindowCorner, WindowsVersion, WIN11_MIN_BUILD};
+
+/// 本机实测版本（Server 2025 / build 26100）。
+fn win11() -> WindowsVersion {
+    WindowsVersion::new(10, 0, 26_100)
+}
+
+/// Win10 22H2（build 19045）：DWM 没有圆角偏好属性。
+fn win10() -> WindowsVersion {
+    WindowsVersion::new(10, 0, 19_045)
+}
+
+/// **抓得住**：判定链的顺序与每一格的原因码（把 `policy`/`os`/`backend` 任一条判反都会红）。
+/// **抓不住**：DWM 到底有没有真画圆角（那要像素，见 `platform/win32` 的探针输出）。
+#[test]
+fn truth_table_policy_os_backend() {
+    let cases = [
+        // policy=Square：任何系统/后端都直角，原因是用户选的。
+        (
+            WindowCorner::Square,
+            Some(win11()),
+            Backend::Gpu,
+            CornerSource::Square,
+            Some(CornerExclusion::UserSquare),
+        ),
+        (
+            WindowCorner::Square,
+            Some(win10()),
+            Backend::Cpu,
+            CornerSource::Square,
+            Some(CornerExclusion::UserSquare),
+        ),
+        (
+            WindowCorner::Square,
+            None,
+            Backend::Auto,
+            CornerSource::Square,
+            Some(CornerExclusion::UserSquare),
+        ),
+        // policy=System + 探测不出系统：不许猜「Win11」。
+        (
+            WindowCorner::System,
+            None,
+            Backend::Gpu,
+            CornerSource::Square,
+            Some(CornerExclusion::UnknownOs),
+        ),
+        // Win10：直角，GPU 档原因是版本、CPU 档原因是渲染档（同一个直角，原因不同）。
+        (
+            WindowCorner::System,
+            Some(win10()),
+            Backend::Gpu,
+            CornerSource::Square,
+            Some(CornerExclusion::OsBuild),
+        ),
+        (
+            WindowCorner::System,
+            Some(win10()),
+            Backend::Auto,
+            CornerSource::Square,
+            Some(CornerExclusion::OsBuild),
+        ),
+        (
+            WindowCorner::System,
+            Some(win10()),
+            Backend::Cpu,
+            CornerSource::Square,
+            Some(CornerExclusion::CpuTier),
+        ),
+        // Win11 / Server 2025：三个后端都用 DWM（D36 只管我们自己的合成技巧）。
+        (
+            WindowCorner::System,
+            Some(win11()),
+            Backend::Gpu,
+            CornerSource::Dwm,
+            None,
+        ),
+        (
+            WindowCorner::System,
+            Some(win11()),
+            Backend::Cpu,
+            CornerSource::Dwm,
+            None,
+        ),
+        (
+            WindowCorner::System,
+            Some(win11()),
+            Backend::Auto,
+            CornerSource::Dwm,
+            None,
+        ),
+    ];
+
+    for (policy, os, backend, want_source, want_excluded) in cases {
+        let plan = plan_corner(policy, os, backend);
+        assert_eq!(
+            plan.source, want_source,
+            "policy={policy:?} os={os:?} backend={backend:?}"
+        );
+        assert_eq!(
+            plan.excluded, want_excluded,
+            "policy={policy:?} os={os:?} backend={backend:?} 的原因码"
+        );
+    }
+}
+
+/// 边界：`WIN11_MIN_BUILD` **本身**算 Win11（`>=`，不是 `>`）。
+///
+/// 抓得住：把 `build < WIN11_MIN_BUILD` 写成 `<=`——Win11 21H2（build 22000）会静默掉成直角，
+/// 而那正好是第一台 Win11 机器。
+#[test]
+fn the_win11_boundary_is_inclusive() {
+    let at = WindowsVersion::new(10, 0, WIN11_MIN_BUILD);
+    assert_eq!(
+        plan_corner(WindowCorner::System, Some(at), Backend::Gpu).source,
+        CornerSource::Dwm
+    );
+    let below = WindowsVersion::new(10, 0, WIN11_MIN_BUILD - 1);
+    assert_eq!(
+        plan_corner(WindowCorner::System, Some(below), Backend::Gpu).source,
+        CornerSource::Square,
+        "build 21999 = Win10 22H2 家族末尾，不能算 Win11"
+    );
+}
+
+/// 日志行的形状：四个字段都在，且 `excluded_reason=none` 与 `reason=user` 不许混。
+///
+/// 为什么要钉这一条：这行是「后来的人分辨没生效 / 生效了看不见」的唯一依据（任务书原话），
+/// 少一栏就等于把这条线索丢掉。
+#[test]
+fn the_log_line_carries_every_field() {
+    let dwm = plan_corner(WindowCorner::System, Some(win11()), Backend::Gpu)
+        .log_line(WindowCorner::System);
+    assert!(dwm.starts_with("corner=policy=system"), "{dwm}");
+    assert!(dwm.contains("source=dwm"), "{dwm}");
+    assert!(dwm.contains("os=10.0.26100"), "{dwm}");
+    assert!(dwm.contains("excluded_reason=none"), "{dwm}");
+    assert!(dwm.contains("radius=system"), "{dwm}");
+
+    let square = plan_corner(WindowCorner::Square, Some(win11()), Backend::Gpu)
+        .log_line(WindowCorner::Square);
+    assert!(square.contains("source=square"), "{square}");
+    assert!(square.contains("excluded_reason=user"), "{square}");
+
+    let unknown: CornerPlan = plan_corner(WindowCorner::System, None, Backend::Gpu);
+    assert!(unknown
+        .log_line(WindowCorner::System)
+        .contains("os=unknown"));
+}
+
+/// **日志行的形状**，用 M116 探针窗口的**真实读数**构造（`DevDocs/artifacts/m116/probe-table.md`）。
+///
+/// 抓得住：字段被删/改名/顺序错乱（`excluded_reason` 少一栏、`radius=system` 丢了、
+/// `frame` / `layered` 被挪出这一行）——这些都会让「没生效 vs 生效了看不见」的区分重新变成猜谜。
+/// 抓不住：**产品进程**里那一行（本测试只钉格式）。真值已有：2026-11-04 两次真跑产品 bin
+/// （α=1.0 / α=0.85）的 `[corner] boot …` 两行，见 `DevDocs/artifacts/m116/README.md`。
+#[test]
+fn the_log_line_shape_is_pinned_with_the_measured_readings() {
+    // 本机实测：Server 2025 / build 26100；读回 `E_INVALIDARG`；产品形状是 `overlapped`，
+    // 而 `layered=on` 只可能来自整窗 α（我们的 `WS_EX_LAYERED`） ⇒ 带 `suppressed_by=`。
+    let os = WindowsVersion::new(10, 0, 26_100);
+    let plan: CornerPlan = plan_corner(WindowCorner::System, Some(os), Backend::Gpu);
+    let line = format_line(
+        "boot",
+        &plan,
+        WindowCorner::System,
+        "pref=2 readback=? read_hr=0x80070057",
+        "frame=overlapped layered=on",
+        Some("window_alpha"),
+    );
+    assert_eq!(
+        line,
+        concat!(
+            "[corner] boot corner=policy=system source=dwm os=10.0.26100 ",
+            "excluded_reason=none radius=system pref=2 readback=? ",
+            "read_hr=0x80070057 frame=overlapped layered=on ",
+            "suppressed_by=window_alpha"
+        )
+    );
+
+    // 设置里选「直角」：原因码必须从 `none` 变成 `user`，其余字段不动。
+    let square = format_line(
+        "change",
+        &plan_corner(WindowCorner::Square, Some(os), Backend::Gpu),
+        WindowCorner::Square,
+        "pref=1 readback=? read_hr=0x80070057",
+        "frame=overlapped layered=off",
+        None,
+    );
+    assert!(
+        square.contains("corner=policy=square source=square"),
+        "{square}"
+    );
+    assert!(square.contains("excluded_reason=user"), "{square}");
+    assert!(square.contains("frame=overlapped layered=off"), "{square}");
+    // α = 1（不补分层）时**不许**出现 `suppressed_by=`：那一栏只在整窗 α 打开时才有意义。
+    assert!(!square.contains("suppressed_by"), "{square}");
+
+    // Win10：原因码是 `os-build`（GPU 档）/ `cpu-tier`（CPU 档），来源仍是 square。
+    let win10 = WindowsVersion::new(10, 0, 19_045);
+    let os_build =
+        plan_corner(WindowCorner::System, Some(win10), Backend::Gpu).log_line(WindowCorner::System);
+    assert!(
+        os_build.contains("source=square") && os_build.contains("excluded_reason=os-build"),
+        "{os_build}"
+    );
+    let cpu =
+        plan_corner(WindowCorner::System, Some(win10), Backend::Cpu).log_line(WindowCorner::System);
+    assert!(cpu.contains("excluded_reason=cpu-tier"), "{cpu}");
+
+    // 探测不到版本（macOS / X11 / Wayland 落到同一格）：`unknown-os`，不许猜 Win11。
+    let unknown =
+        plan_corner(WindowCorner::System, None, Backend::Gpu).log_line(WindowCorner::System);
+    assert!(
+        unknown.contains("os=unknown") && unknown.contains("excluded_reason=unknown-os"),
+        "{unknown}"
+    );
+}
+
+/// **同一策略 N 次只下发 / 只记 1 行**（M116 r1 复审 P2-4 的判据）。
+///
+/// 为什么要有这条：设置页的整窗 α / 面板 α / 暗化滑条每动一下都会触发一次外观变更，
+/// 而圆角与它们无关。没有去重时拖一次滑条会刷出一串 `[corner] change …`，
+/// 把「分辨有没有生效」的那唯一一行日志淹掉。
+///
+/// 抓得住：把去重删掉（`needs_redispatch` 恒 `true` 时这里会数到 N）、或指纹里漏掉某一维
+/// （换档 / 首次拿到句柄就不重下了）。
+/// 抓不住：真进程里到底打了几行（`eprintln!` 在 `App` 里，本测试只钉判定）。
+#[test]
+fn the_same_policy_is_dispatched_only_once() {
+    use super::{needs_redispatch, plan_corner, CornerApplied};
+    use crate::Backend;
+    use unlucky_presenter::prefs::{WindowCorner, WindowsVersion};
+
+    let os = WindowsVersion::new(10, 0, 26_100);
+    let plan = plan_corner(WindowCorner::System, Some(os), Backend::Gpu);
+
+    // 模拟「滑条被拖动 20 次」：每次都是同一个策略、同一个系统、句柄一直在。
+    let mut last: Option<CornerApplied> = None;
+    let mut dispatches = 0;
+    for _ in 0..20 {
+        let next = CornerApplied::new(WindowCorner::System, &plan, true, false);
+        if needs_redispatch(last.as_ref(), &next) {
+            dispatches += 1;
+            last = Some(next);
+        }
+    }
+    assert_eq!(dispatches, 1, "同一策略连按 20 次只该下发/记 1 次");
+
+    // 换档必须重下。
+    let square = plan_corner(WindowCorner::Square, Some(os), Backend::Gpu);
+    assert!(needs_redispatch(
+        last.as_ref(),
+        &CornerApplied::new(WindowCorner::Square, &square, true, false)
+    ));
+
+    // 句柄从无到有必须重下（首次拿到 HWND 时才真能设属性）。
+    let mut no_window: Option<CornerApplied> = None;
+    let first = CornerApplied::new(WindowCorner::System, &plan, false, false);
+    assert!(needs_redispatch(no_window.as_ref(), &first));
+    no_window = Some(first);
+    assert!(needs_redispatch(
+        no_window.as_ref(),
+        &CornerApplied::new(WindowCorner::System, &plan, true, false)
+    ));
+
+    // 整窗 α 拉低（补分层）与拉回 1.0 都必须各重下/各记一行：系统行为在这两次确实不同。
+    let opaque = CornerApplied::new(WindowCorner::System, &plan, true, false);
+    let translucent = CornerApplied::new(WindowCorner::System, &plan, true, true);
+    assert!(
+        needs_redispatch(Some(&opaque), &translucent),
+        "α 从 1.0 拉低必须重下（那一行才会出现 suppressed_by=window_alpha）"
+    );
+    assert!(
+        needs_redispatch(Some(&translucent), &opaque),
+        "α 拉回 1.0 也必须重下（圆角请求重新生效）"
+    );
+    assert!(
+        !needs_redispatch(Some(&translucent), &translucent),
+        "α 一直在 <1 时重复触发不该刷屏"
+    );
+}
diff --git a/crates/app-iced/src/platform/win32/mod.rs b/crates/app-iced/src/platform/win32/mod.rs
new file mode 100644
index 0000000..85239d3
--- /dev/null
+++ b/crates/app-iced/src/platform/win32/mod.rs
@@ -0,0 +1,16 @@
+//! Win32 专属的窗口能力。
+//!
+//! | 子模块 | 是什么 | 有没有 `unsafe` |
+//! |---|---|---|
+//! | [`transparency`] | D36 定案的整窗 α 唯一实现落点（也是 M116 的 DWM 圆角落点） | **有**（全仓唯一） |
+//! | [`corner`] | M116 的圆角**判据**：策略 × 系统版本 × 渲染档 → 来源与原因码 | 没有（纯函数） |
+//!
+//! 目录形态（而非 `win32.rs` 单文件）是为了让「每个平台一份实现」在路径上一眼可见：
+//! 将来 macOS / Wayland 的对应能力各自成目录，互不干扰。
+//!
+//! **非 Windows 平台也在编译**：`transparency` 里的公开函数有同签名的空实现，
+//! `corner` 的判据在探测不到系统版本时给出「直角 + `unknown-os`」，所以调用点不需要 `#[cfg]`，
+//! 行为（返回「本平台不支持」）可被测试断言。
+
+pub mod corner;
+pub mod transparency;
diff --git a/crates/app-iced/src/platform/win32/transparency.rs b/crates/app-iced/src/platform/win32/transparency.rs
new file mode 100644
index 0000000..4458a5f
--- /dev/null
+++ b/crates/app-iced/src/platform/win32/transparency.rs
@@ -0,0 +1,398 @@
+//! 整窗透明度（D36）：**全仓唯一**允许 `unsafe` 的文件。
+//!
+//! ## 为什么只有这里有 unsafe
+//!
+//! 窗口级 α 没有任何「安全」的 Rust API 可达：`SetLayeredWindowAttributes` 是 Win32 的
+//! 唯一路径（D36 逐路核实过 wgpu / iced / winit 都没有代理入口）。所以把**整个仓库**的
+//! FFI 面收在这一处，其余一层（[`super::super::effective_window_alpha`]）保持纯函数。
+//! 守门在 `.github/workflows/guards.yml` 的 `unsafe-scope` job：全仓带这个 allow 的文件集合
+//! 必须**恰好等于**本文件的路径（集合相等，不是黑名单命中）。
+//!
+//! ## 只做 LWA_ALPHA
+//!
+//! `LWA_COLORKEY` / `DwmEnableBlurBehindWindow` 一律不用：色键会把某个颜色整块变透明（视觉
+//! 事故），模糊是另一条路线（D36 已排除）。
+//!
+//! `WS_EX_LAYERED`（`SetLayeredWindowAttributes` 的调用前提）**也归本文件**：加扩展位只有
+//! `Get/SetWindowLongPtrW` 能走，必须 `unsafe`，而全仓放行 unsafe 的文件集合恰好只有本文件。
+//! 所以窗口创建侧（`app::boot`）不碰扩展样式，它只负责拿到句柄后先调 [`ensure_layered`]
+//! 再调 [`apply_window_alpha`]——两件事都在同一个 unsafe 落点里，门禁仍是「集合相等」。
+//!
+//! ## 为什么它不影响命中测试与自绘标题栏拖动（D36 任务书要求写清）
+//!
+//! `LWA_ALPHA` 只改**合成**（DWM 把整窗乘一个常数），不动窗口的命中测试：
+//!
+//! | 机制 | 会不会让鼠标穿透 | 本项目用不用 |
+//! |---|---|---|
+//! | `WS_EX_TRANSPARENT`（分层窗口的「点击穿透」位） | **会**（鼠标事件直接发给下层的窗口） | 不用 |
+//! | `LWA_COLORKEY`（色键：某种颜色整块变透明） | **会**（命中测试按颜色挖洞） | 不用 |
+//! | `WS_EX_LAYERED` + `LWA_ALPHA` | **不会**（只是合成时乘 α，整个矩形仍然接收命中） | 用这一条 |
+//!
+//! 所以自绘标题栏的拖动照旧：`Message::DragWindow` → `window::drag(id)` 走 winit 的
+//! `WM_NCLBUTTONDOWN(HTCAPTION)`，它依赖的是**窗口矩形内的鼠标事件**，与 α 无关。
+//! 唯一会「点不动」的情形是 α = 0（整窗不可见，用户以为程序消失）——这就是
+//! [`unlucky_presenter::prefs::WINDOW_ALPHA_MIN`]（0.08）作为硬底、且 `α ≤ 0` 直接拒绝的原因。
+//!
+//! D36 已在真机上实测「α ≥ 1 时分层样式不破坏命中测试与拖动」；本仓库的 RDP 环境无法复核
+//! 观感，所以这条结论的**行为**部分归真机验收（见 M93 报告「没验的部分」）。
+//!
+//! ## 非 Windows
+//!
+//! 同签名的空实现返回 [`AlphaOutcome::Unsupported`]：调用点不需要 `#[cfg]`，
+//! 而「这个平台不支持」这件事本身可以被断言。
+
+// D36：这是全仓唯一的 unsafe 落点，CI 的 `unsafe-scope` job 会比对文件集合。
+#![allow(unsafe_code)]
+
+mod alpha;
+mod dwm;
+mod exstyle;
+mod probe;
+
+pub use dwm::{apply_corner, style_summary, CornerOutcome};
+pub use exstyle::{click_through, is_click_through_style, WS_EX_TRANSPARENT};
+pub use probe::{controlled_experiment, TABLE_HEADER};
+
+pub use alpha::{
+    alpha_byte, apply_window_alpha, ensure_layered, AlphaOutcome, AlphaRejection, GWL_EXSTYLE,
+    LWA_ALPHA, WS_EX_LAYERED,
+};
+
+/// 读扩展样式（跨位宽的唯一落点：64 位走 `GetWindowLongPtrW`，32 位走 `GetWindowLongW`）。
+#[cfg(all(target_os = "windows", target_pointer_width = "64"))]
+pub(super) fn raw_ex_style(hwnd: isize) -> isize {
+    // SAFETY: 只读一个窗口属性，按值传参、不持有指针、无所有权转移；无效句柄只会返回 0。
+    unsafe { GetWindowLongPtrW(hwnd, GWL_EXSTYLE) }
+}
+
+/// 32 位目标：符号是 `GetWindowLongW`（`link_name` 已映射），返回 `i32`，扩到 `isize`。
+#[cfg(all(target_os = "windows", target_pointer_width = "32"))]
+pub(super) fn raw_ex_style(hwnd: isize) -> isize {
+    // SAFETY: 同 64 位分支。
+    unsafe { isize::from(GetWindowLongPtrW(hwnd, GWL_EXSTYLE)) }
+}
+
+/// 非 Windows：没有扩展样式这个概念，读 0（`ensure_layered` 因此恒 `false`）。
+#[cfg(not(target_os = "windows"))]
+pub(super) fn raw_ex_style(_hwnd: isize) -> isize {
+    0
+}
+
+/// 写扩展样式（位宽分档同上）。
+#[cfg(all(target_os = "windows", target_pointer_width = "64"))]
+pub(super) fn raw_set_ex_style(hwnd: isize, style: isize) {
+    // SAFETY: 同 `raw_ex_style`：按值传参、不持有指针；返回值刻意不用（改完靠回读取证）。
+    unsafe {
+        SetWindowLongPtrW(hwnd, GWL_EXSTYLE, style);
+    }
+}
+
+/// 32 位目标：符号是 `SetWindowLongW`；扩展样式本身就是 32 位量，收窄无损。
+#[cfg(all(target_os = "windows", target_pointer_width = "32"))]
+pub(super) fn raw_set_ex_style(hwnd: isize, style: isize) {
+    let style = i32::try_from(style).unwrap_or(i32::MAX);
+    // SAFETY: 同 64 位分支。
+    unsafe {
+        SetWindowLongPtrW(hwnd, GWL_EXSTYLE, style);
+    }
+}
+
+/// 非 Windows：空实现。
+#[cfg(not(target_os = "windows"))]
+pub(super) fn raw_set_ex_style(_hwnd: isize, _style: isize) {}
+
+/// 回读判据：这一位在不在扩展样式里。
+pub(super) fn has_layered(hwnd: isize) -> bool {
+    raw_ex_style(hwnd) & WS_EX_LAYERED != 0
+}
+
+/// 句柄是否指向一个**存在**的窗口（全仓唯一 `unsafe` 落点的一部分）。
+///
+/// 为什么在这里而不是在取证探针那个文件里：`transparency.rs` 是全仓**唯一**允许 `unsafe` 的
+/// 文件（`unsafe-scope` 判据 = 「带 `#![allow(unsafe_code)]` 的文件集合恰好等于本文件」）。
+/// 探针用到 FFI 时就只能**把 FFI 搬进来**，不能让 `unsafe` 溜到没有标记的文件里——
+/// 那会让门禁照样绿、而「唯一落点」这个性质已经破了（M100 r1 复审实测抓到的形状）。
+///
+/// `0` / 无效句柄 → `false`（Win32 的 `IsWindow` 对无效句柄返回 0）。
+#[cfg(target_os = "windows")]
+pub(super) fn window_exists(hwnd: isize) -> bool {
+    // SAFETY: `IsWindow` 只按值接受句柄，不持有指针、无所有权转移；无效句柄返回 0。
+    (unsafe { IsWindow(hwnd) }) != 0
+}
+
+#[cfg(target_os = "windows")]
+#[link(name = "user32")]
+extern "system" {
+    /// `IsWindow`：句柄是否指向一个存在的窗口。
+    ///
+    /// 为什么需要它（M100 r1）：`GetWindowLongPtrW` 对**无效句柄**返回 0，与「扩展样式全 0」
+    /// 不可区分。取证探针要分「拿不到」与「读到了没有这一位」，所以先验一次句柄。
+    fn IsWindow(hwnd: isize) -> i32;
+
+    /// `SetLayeredWindowAttributes`：窗口必须已带 `WS_EX_LAYERED`，α 才生效。
+    ///
+    /// 签名照 Win32 头文件：`BOOL SetLayeredWindowAttributes(HWND, COLORREF, BYTE, DWORD)`。
+    fn SetLayeredWindowAttributes(hwnd: isize, color_key: u32, alpha: u8, flags: u32) -> i32;
+
+    /// `GetWindowLongPtrW`：读窗口属性（`GWL_EXSTYLE` = `-20`）。
+    ///
+    /// 头文件里 `GetWindowLongPtrW` 是宏：64 位映射到 `GetWindowLongPtrW`、32 位映射到
+    /// `GetWindowLongW`。user32 在 32 位导出里**没有** `...PtrW`，所以这里按指针宽度分档声明，
+    /// 否则 i686 目标会在链接期失败（本仓的 Win7 冒烟是 x64，但编译不该只在一个位宽上成立）。
+    #[cfg(target_pointer_width = "64")]
+    fn GetWindowLongPtrW(hwnd: isize, index: i32) -> isize;
+    /// `SetWindowLongPtrW`：写窗口属性（同上，32 位映射到 `SetWindowLongW`）。
+    #[cfg(target_pointer_width = "64")]
+    fn SetWindowLongPtrW(hwnd: isize, index: i32, new_value: isize) -> isize;
+
+    /// 32 位目标的实际符号（见上）。
+    #[cfg(target_pointer_width = "32")]
+    #[link_name = "GetWindowLongW"]
+    fn GetWindowLongPtrW(hwnd: isize, index: i32) -> i32;
+    /// 32 位目标的实际符号（见上）。
+    #[cfg(target_pointer_width = "32")]
+    #[link_name = "SetWindowLongW"]
+    fn SetWindowLongPtrW(hwnd: isize, index: i32, new_value: i32) -> i32;
+
+    /// `GetWindowRect`：窗口矩形的屏幕坐标（**含** DWM 加出来的不可见边框）。
+    ///
+    /// 与 `DWMWA_EXTENDED_FRAME_BOUNDS` 对照，是 M116 探针里「DWM 到底给这个窗口加了多宽的
+    /// 边框」这条差值的来源：差值 ≈ 系统认为的边框带宽度。
+    fn GetWindowRect(hwnd: isize, rect: *mut WinRect) -> i32;
+
+    /// `CreateWindowExW`：M116 的**受控对照实验**要用它造三种样式的窗口（同进程）。
+    ///
+    /// 只用系统自带类 `STATIC`（不需要 `RegisterClassW`，也就没有窗口过程要写）。
+    fn CreateWindowExW(
+        ex_style: u32,
+        class: *const u16,
+        name: *const u16,
+        style: u32,
+        x: i32,
+        y: i32,
+        width: i32,
+        height: i32,
+        parent: isize,
+        menu: isize,
+        instance: isize,
+        param: *mut core::ffi::c_void,
+    ) -> isize;
+
+    /// `DestroyWindow`：探针窗口用完即毁（不泄漏 HWND）。
+    fn DestroyWindow(hwnd: isize) -> i32;
+
+    /// `ShowWindow`：DWM 只管理**可见**窗口，所以探针窗口必须真显示一次才有读数。
+    fn ShowWindow(hwnd: isize, command: i32) -> i32;
+}
+
+/// `RECT`（`GetWindowRect` 的 out 参数）。字段顺序照 Win32 头文件，`repr(C)` 保证布局。
+#[cfg(target_os = "windows")]
+#[repr(C)]
+#[derive(Debug, Clone, Copy, Default)]
+pub(super) struct WinRect {
+    /// 左
+    pub left: i32,
+    /// 上
+    pub top: i32,
+    /// 右
+    pub right: i32,
+    /// 下
+    pub bottom: i32,
+}
+
+#[cfg(target_os = "windows")]
+#[link(name = "dwmapi")]
+extern "system" {
+    /// `DwmSetWindowAttribute`：M116 圆角的唯一落点（`DWMWA_WINDOW_CORNER_PREFERENCE`）。
+    ///
+    /// 返回 `HRESULT`：`S_OK`(0) = 成功；属性不被这个 Windows 版本认识时是 `E_INVALIDARG`
+    /// （`0x8007_0057`）——Win10 上就是这个返回值，**不是**「设了但没效果」。
+    fn DwmSetWindowAttribute(
+        hwnd: isize,
+        attribute: u32,
+        value: *const core::ffi::c_void,
+        size: u32,
+    ) -> i32;
+
+    /// `DwmGetWindowAttribute`：读回 DWM 侧的属性（探针与日志的证据来源）。
+    fn DwmGetWindowAttribute(
+        hwnd: isize,
+        attribute: u32,
+        value: *mut core::ffi::c_void,
+        size: u32,
+    ) -> i32;
+}
+
+/// 写一个 `u32` 的 DWM 属性，返回 `HRESULT`（0 = `S_OK`）。
+#[cfg(target_os = "windows")]
+pub(super) fn dwm_set_u32(hwnd: isize, attribute: u32, value: u32) -> i32 {
+    // SAFETY: `value` 是栈上的 POD，指针只在调用期间有效，`size` 与它逐字节一致；
+    // DWM 只按值读取，不保留指针。
+    unsafe {
+        DwmSetWindowAttribute(
+            hwnd,
+            attribute,
+            (&raw const value).cast::<core::ffi::c_void>(),
+            u32::try_from(std::mem::size_of::<u32>()).unwrap_or(4),
+        )
+    }
+}
+
+/// `HRESULT` 的成功判据：**看严重性位**（bit 31），不是「等于 0」。
+///
+/// Win32 里成功码不只有 `S_OK`(0)：`S_FALSE`(1) 与各种 `S_*` / 信息级码都是成功，所以判据必须
+/// 是 `hr >= 0`。这条判据与 M116 探针的具体读数无关——它只是 `HRESULT` 的通用语义。
+///
+/// ⚠️ **别把 `0x7FF8FFA9` 当成 DWM 的返回值**（本分支一度这么写过，已订正）：本机
+/// `DwmGetWindowAttribute(DWMWA_WINDOW_CORNER_PREFERENCE)` 三种窗口样式实测**全部**返回
+/// `E_INVALIDARG`（`0x8007_0057`，负数）；`0x7FF8FFA9` 是我早期用 `i32::unsigned_abs()` 打印
+/// HRESULT 时的产物（把负数的补码取了绝对值），它既不是 `S_OK` 也不是任何 DWM 信息码。
+#[must_use]
+pub const fn hresult_ok(hr: i32) -> bool {
+    hr >= 0
+}
+
+/// 读一个 `u32` 的 DWM 属性**并保留 `HRESULT`**（M116 探针要它：读不回来时得知道为什么）。
+#[cfg(target_os = "windows")]
+pub(super) fn dwm_get_u32_hr(hwnd: isize, attribute: u32) -> (Option<u32>, u32) {
+    let mut value: u32 = 0;
+    // SAFETY: out 指针指向本栈帧里的 `u32`，`size` 与之一致；失败时 DWM 不写。
+    let hr = unsafe {
+        DwmGetWindowAttribute(
+            hwnd,
+            attribute,
+            (&raw mut value).cast::<core::ffi::c_void>(),
+            u32::try_from(std::mem::size_of::<u32>()).unwrap_or(4),
+        )
+    };
+    // 判据是**严重性位**（bit 31），不是「等于 0」：`S_FALSE` / 信息级码也是成功。
+    // ⚠️ 报错时给的是 `hr as u32`（原始位），**不是** `unsigned_abs()`——后者会把
+    // `E_INVALIDARG`（`0x8007_0057`）印成 `0x7FF8_FFA9`（M116 实测踩过：负数取绝对值
+    // 得到的是「补码的绝对值」，不是 HRESULT）。`hresult_ok` 与这条打印规则一起被测试钉住。
+    (hresult_ok(hr).then_some(value), hr as u32)
+}
+
+/// 读一个 `u32` 的 DWM 属性；`HRESULT` 非 0 返回 `None`（**不许**把失败读成 0）。
+#[cfg(target_os = "windows")]
+pub(super) fn dwm_get_u32(hwnd: isize, attribute: u32) -> Option<u32> {
+    dwm_get_u32_hr(hwnd, attribute).0
+}
+
+/// 读 `DWMWA_EXTENDED_FRAME_BOUNDS` 这类 `RECT` 属性；失败返回 `None`。
+#[cfg(target_os = "windows")]
+pub(super) fn dwm_get_rect(hwnd: isize, attribute: u32) -> Option<WinRect> {
+    let mut rect = WinRect::default();
+    // SAFETY: 同 `dwm_get_u32`，只是 out 类型换成 `RECT`。
+    let hr = unsafe {
+        DwmGetWindowAttribute(
+            hwnd,
+            attribute,
+            (&raw mut rect).cast::<core::ffi::c_void>(),
+            u32::try_from(std::mem::size_of::<WinRect>()).unwrap_or(16),
+        )
+    };
+    // 与 `dwm_get_u32_hr` 同一条判据：`HRESULT` 看严重性位，不是「等于 0」（judgment 只留一处）。
+    hresult_ok(hr).then_some(rect)
+}
+
+/// `GetWindowRect`：窗口矩形（屏幕坐标）。失败返回 `None`。
+#[cfg(target_os = "windows")]
+pub(super) fn window_rect(hwnd: isize) -> Option<WinRect> {
+    let mut rect = WinRect::default();
+    // SAFETY: out 指针指向本栈帧的 `RECT`；`GetWindowRect` 只在成功时写它。
+    let ok = unsafe { GetWindowRect(hwnd, &raw mut rect) };
+    (ok != 0).then_some(rect)
+}
+
+/// 造一个探针窗口（受控对照实验用）。`0` = 创建失败。
+///
+/// 类名用系统自带的 `STATIC`：不需要 `RegisterClassW`，也就不必在这个文件里再写一个窗口过程。
+#[cfg(target_os = "windows")]
+pub(super) fn create_probe_window(style: u32, ex_style: u32) -> isize {
+    let class: Vec<u16> = "STATIC\0".encode_utf16().collect();
+    let title: Vec<u16> = "ULL M116 corner probe\0".encode_utf16().collect();
+    // SAFETY: 两个指针都指向本帧里以 NUL 结尾的 UTF-16 缓冲；其余参数全是按值 POD。
+    // 失败返回 0，调用方按「拿不到句柄」处理，不会产生未定义行为。
+    unsafe {
+        CreateWindowExW(
+            ex_style,
+            class.as_ptr(),
+            title.as_ptr(),
+            style,
+            40,
+            40,
+            420,
+            260,
+            0,
+            0,
+            0,
+            core::ptr::null_mut(),
+        )
+    }
+}
+
+/// 让探针窗口可见（DWM 只管理可见窗口），`SW_SHOWNA` = 显示但不激活。
+#[cfg(target_os = "windows")]
+pub(super) fn show_probe_window(hwnd: isize) {
+    const SW_SHOWNA: i32 = 8;
+    // SAFETY: 按值传句柄；无效句柄只会让 Win32 返回 0。
+    unsafe {
+        ShowWindow(hwnd, SW_SHOWNA);
+    }
+}
+
+/// 销毁探针窗口（成对使用，避免 HWND 泄漏）。
+#[cfg(target_os = "windows")]
+pub(super) fn destroy_probe_window(hwnd: isize) {
+    if hwnd == 0 {
+        return;
+    }
+    // SAFETY: 只对本模块 `create_probe_window` 造出来的句柄调用；销毁后不再使用它。
+    unsafe {
+        DestroyWindow(hwnd);
+    }
+}
+
+/// 读窗口样式位（`GWL_STYLE` = `-16`）。探针用它取 `frame=` 那一栏（产品的真实样式见
+/// `probe::PRODUCT_STYLE`，**不是** `WS_POPUP`）。
+#[cfg(target_os = "windows")]
+pub(super) fn window_style(hwnd: isize) -> isize {
+    const GWL_STYLE: i32 = -16;
+    // SAFETY: 同 `raw_ex_style`：只读一个窗口属性，按值传参、不持有指针。
+    unsafe { GetWindowLongPtrW(hwnd, GWL_STYLE) }
+}
+
+#[cfg(target_os = "windows")]
+pub(super) fn set_layered(hwnd: isize, byte: u8) -> AlphaOutcome {
+    // SAFETY: 四个参数都是按值传入的 POD；`flags` 只带 LWA_ALPHA，于是系统忽略 `color_key`
+    // （传 0 与之无关）。句柄由调用方给出：无效句柄只会让 Win32 返回 0（走下面的 Failed 分支），
+    // 不会造成未定义行为——本调用不持有指针，也没有释放语义。
+    let ok = unsafe { SetLayeredWindowAttributes(hwnd, 0, byte, LWA_ALPHA) };
+    if ok == 0 {
+        // ⚠️ **这里的 `unsigned_abs()` 是有意的，别跟 DWM 那几处「统一」**（tower 裁定 2026-11-03）：
+        //
+        // - 这里取的是 `GetLastError()` 的 **DWORD**（`raw_os_error()` 给的是被塞进 `i32` 的 DWORD，
+        //   例如 `87` / `1400`），它不是 HRESULT，没有严重性位；`unsigned_abs` 只是把
+        //   「高位被当符号」的那点噪声抹掉，语义仍是「错误号」。
+        // - `DwmGet/SetWindowAttribute` 返回的是 **HRESULT**：判成功看 bit 31（`hresult_ok`），
+        //   打印必须用 `hr as u32` 的原始位——用 `unsigned_abs()` 会把 `E_INVALIDARG`
+        //   （`0x8007_0057`）印成 `0x7FF8_FFA9`（M116 实测踩过，见 `dwm_get_u32_hr` 的注释）。
+        //
+        // 两种「错误号」不同源，所以打印方式也不该相同。这条由
+        // `tests::dword_error_codes_and_hresults_are_printed_differently` 钉住。
+        let code = std::io::Error::last_os_error()
+            .raw_os_error()
+            .unwrap_or(0)
+            .unsigned_abs();
+        return AlphaOutcome::Failed { code };
+    }
+    AlphaOutcome::Applied { byte }
+}
+
+#[cfg(not(target_os = "windows"))]
+pub(super) fn set_layered(_hwnd: isize, _byte: u8) -> AlphaOutcome {
+    AlphaOutcome::Unsupported
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/app-iced/src/platform/win32/transparency/alpha.rs b/crates/app-iced/src/platform/win32/transparency/alpha.rs
new file mode 100644
index 0000000..0dcf596
--- /dev/null
+++ b/crates/app-iced/src/platform/win32/transparency/alpha.rs
@@ -0,0 +1,128 @@
+//! 整窗 α 的**判据与执行**（D36）——从 `transparency.rs` 搬出来，那里要留行数给 DWM 的 FFI。
+//!
+//! ## 本文件零 `unsafe`、零 `extern`
+//!
+//! 全仓 `unsafe` 只允许出现在 [`super`]（`transparency.rs`）一个文件里，判据是「**带放行属性的
+//! 文件集合恰好等于它**」。本文件要的 FFI 全部由 `super` 提供安全包装
+//! （`raw_ex_style` / `raw_set_ex_style` / `has_layered` / `set_layered`），这里只做钳位、量化与三态映射。
+//!
+//! ⚠️ **别把 FFI 写回来**（`exstyle.rs` 的模块文档里有同一句，M100 r1 复审实测抓过一次）：
+//! lint 级别沿模块树继承，在这里写 `unsafe` 块也**编得过**、门禁也照样绿，但「唯一落点」就破了。
+
+use unlucky_presenter::prefs::WINDOW_ALPHA_MIN;
+
+use super::{has_layered, raw_ex_style, raw_set_ex_style, set_layered};
+
+/// Win32 的 `LWA_ALPHA` 标志位：只改整窗 α（`0x2`）。
+///
+/// 单独立成常量是为了让「写错成 `LWA_COLORKEY`（`0x1`）等于什么都没做」这件事有断言盯着。
+pub const LWA_ALPHA: u32 = 0x0000_0002;
+
+/// `WS_EX_LAYERED`：分层窗口扩展样式（`0x0008_0000`）。**整窗 α 的调用前提**。
+pub const WS_EX_LAYERED: isize = 0x0008_0000;
+
+/// `GWL_EXSTYLE`：扩展样式在 `Get/SetWindowLongPtrW` 里的槽位号（`-20`）。
+pub const GWL_EXSTYLE: i32 = -20;
+
+/// 一次整窗 α 应用的结果。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AlphaOutcome {
+    /// α ≥ 1.0：完全不透明，**不调 FFI**（也就不需要分层窗口）。
+    Opaque,
+    /// 已下发，`byte` 是 Win32 收到的 `0..=255`。
+    Applied {
+        /// 量化后的字节值。
+        byte: u8,
+    },
+    /// 拒绝执行。
+    Rejected(AlphaRejection),
+    /// 非 Windows 平台：空实现，什么都没做。
+    Unsupported,
+    /// FFI 自己失败（如句柄无效），`code` 来自 `GetLastError`。
+    Failed {
+        /// Win32 错误码（`1400` = `ERROR_INVALID_WINDOW_HANDLE`）。
+        code: u32,
+    },
+}
+
+/// [`AlphaOutcome::Rejected`] 的原因。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AlphaRejection {
+    /// 没有可用的 α（`None` / 非正 / 非有限）——整窗穿透的拒绝在这里拦住。
+    NoAlpha,
+    /// 句柄为 0：还没拿到窗口，或窗口已销毁。
+    NoWindow,
+}
+
+/// α → Win32 的 `bAlpha`（`0..=255`）。
+///
+/// 输入先夹到 [`WINDOW_ALPHA_MIN`]`..=1.0`（NaN 取下限）：调用方即使漏了
+/// [`super::super::effective_window_alpha`] 的过滤，也不会把窗口写成穿透。
+///
+/// **向上取整**（`ceil`）是刻意的：`bAlpha/255` 才是实际下发的 α，用 `round` 会让
+/// `0.08×255 = 20.4 → 20`，实际下发 `20/255 = 0.0784`，反而**低于** D36 的下限。
+/// 因此下发值可能比请求值略高（最多 1/255 ≈ 0.004），但绝不会低于下限。
+#[must_use]
+pub fn alpha_byte(alpha: f64) -> u8 {
+    let clamped = if alpha.is_nan() {
+        WINDOW_ALPHA_MIN
+    } else {
+        alpha.clamp(WINDOW_ALPHA_MIN, 1.0)
+    };
+    (clamped * 255.0).ceil() as u8
+}
+
+/// 给窗口补上 `WS_EX_LAYERED`（幂等）。
+///
+/// ## 为什么这件事必须在这里（而不是「窗口创建侧」）
+///
+/// 加扩展样式只有 `GetWindowLongPtrW` / `SetWindowLongPtrW` 一条路，都是 `unsafe`；而
+/// [`super::super`] 的 CI 门禁（`.github/workflows/guards.yml` 的 `unsafe-scope`）要求
+/// 全仓显式放行 `unsafe_code` 的文件集合**恰好等于本文件**。所以窗口创建侧的
+/// `app/boot.rs` 只负责「拿句柄 → 调本函数 → 调 [`apply_window_alpha`]」，
+/// 不新增第二个放行文件。
+///
+/// ## 为什么创建侧无法预先带上这一位
+///
+/// iced 0.14 的 `window::Settings` 没有扩展样式入口；winit 0.30 只在
+/// `IGNORE_CURSOR_EVENT`（鼠标穿透，`WS_EX_TRANSPARENT | WS_EX_LAYERED`）时置位，
+/// `transparent: true` 走的是 DWM 那条路（`window.rs` 的 `ENABLE BLUR BEHIND WINDOW`），
+/// 与 `LWA_ALPHA` 无关。所以只能拿到句柄后补。
+///
+/// ## 返回值
+///
+/// `true` = 这一位**已就位**（原本就有，或本次加上了）。判据是**再加读一次**验证，
+/// 而不是信 `SetWindowLongPtrW` 的返回值：Win32 的它「失败返回 0 且成功也可能返回 0」
+/// （前值就是 0 时），只能靠回读取证。句柄为 0 / 无效 → `false`（`GetWindowLongPtrW`
+/// 也读不到这一位）。
+pub fn ensure_layered(hwnd: isize) -> bool {
+    if hwnd == 0 {
+        return false;
+    }
+    if has_layered(hwnd) {
+        return true;
+    }
+    raw_set_ex_style(hwnd, raw_ex_style(hwnd) | WS_EX_LAYERED);
+    has_layered(hwnd)
+}
+
+/// 把整窗 α 下发到窗口。
+///
+/// `alpha` 一般直接来自 [`super::super::effective_window_alpha`]（`None` = 拒绝整窗穿透）。
+/// 本函数是**执行层**：不再看渲染后端、不读环境变量，只认「有没有一个合法的值」+
+/// 「有没有句柄」，然后（仅 Windows）调一次 `SetLayeredWindowAttributes`。
+///
+/// 调用前提是窗口已带 `WS_EX_LAYERED`（见 [`ensure_layered`]）：没有它 `SetLayeredWindowAttributes`
+/// 一定失败（Win32 返回 0，本机实测 `GetLastError` 常见 87 / `ERROR_INVALID_PARAMETER`）。
+pub fn apply_window_alpha(hwnd: isize, alpha: Option<f64>) -> AlphaOutcome {
+    let Some(alpha) = alpha.filter(|value| value.is_finite() && *value > 0.0) else {
+        return AlphaOutcome::Rejected(AlphaRejection::NoAlpha);
+    };
+    if alpha >= 1.0 {
+        return AlphaOutcome::Opaque;
+    }
+    if hwnd == 0 {
+        return AlphaOutcome::Rejected(AlphaRejection::NoWindow);
+    }
+    set_layered(hwnd, alpha_byte(alpha))
+}
diff --git a/crates/app-iced/src/platform/win32/transparency/dwm.rs b/crates/app-iced/src/platform/win32/transparency/dwm.rs
new file mode 100644
index 0000000..3990bae
--- /dev/null
+++ b/crates/app-iced/src/platform/win32/transparency/dwm.rs
@@ -0,0 +1,394 @@
+//! DWM 圆角（M116）：把 [`CornerPlan`](super::super::corner::CornerPlan) 落成一次属性下发。
+//!
+//! ## 本文件零 `unsafe`、零 `extern`
+//!
+//! `DwmSetWindowAttribute` / `DwmGetWindowAttribute` 的声明与调用点在 [`super`]
+//! （全仓唯一 `unsafe` 落点）；这里只做「哪一档 → 哪个属性值」的映射、`HRESULT` 解释与回读。
+//!
+//! ## 为什么「直角」也要真的下发一次
+//!
+//! `DWMWCP_DONOTROUND` 是**显式**的直角请求。不下发也能得到直角（Win10 就没有这个属性），
+//! 但那样日志里「方」与「没生效」长得一模一样。下发 + 回读之后，
+//! `corner=… source=square excluded_reason=user` 与 `excluded_reason=os-build` 是两条
+//! 可区分的事实，而不是一句猜测。
+//!
+//! ## 回读为什么是证据而不是自证
+//!
+//! `DwmSetWindowAttribute` 返回 `S_OK` 只说明「参数被接受了」。属性值由 DWM 保存，
+//! 回读拿到的是 **DWM 侧的当前值**——它能抓住「设了 A 属性、读回还是旧值」这类事
+//! （比如把 `DWMWA_WINDOW_CORNER_PREFERENCE` 写成别的号，回读会给出 `None` 或旧值）。
+
+/// `DWMWA_WINDOW_CORNER_PREFERENCE`：窗口圆角偏好的属性号（Win11 / Server 2025，build ≥ 22000）。
+pub const DWMWA_WINDOW_CORNER_PREFERENCE: u32 = 34;
+/// `DWMWCP_DONOTROUND`：显式直角。
+pub const DWMWCP_DONOTROUND: u32 = 1;
+/// `DWMWCP_ROUND`：显式圆角（半径由系统决定，**不暴露**给应用）。
+pub const DWMWCP_ROUND: u32 = 2;
+/// `DWMWA_VISIBLE_FRAME_BORDER_THICKNESS`：可见边框厚度（像素，Win11 起）。
+///
+/// ⚠️ **本机实测它不能当「圆不圆」的判据**（我最初以为能，被探针否掉了）：
+/// 三种窗口样式 × 三种状态（默认 / `DWMWCP_ROUND` / `DWMWCP_DONOTROUND`）读出来**全是 `1`**，
+/// 没有任何区分度。保留它只作诊断读数（万一将来在别的机器上有变化），不参与判定。
+/// 证据：`DevDocs/artifacts/m116/probe-table.md` 的 `bdef` / `brnd` / `bsq` 三列。
+pub const DWMWA_VISIBLE_FRAME_BORDER_THICKNESS: u32 = 37;
+/// `DWMWA_EXTENDED_FRAME_BOUNDS`：DWM 认为的窗口边界（**含**不可见的调整带）。
+pub const DWMWA_EXTENDED_FRAME_BOUNDS: u32 = 9;
+
+/// 一次圆角下发的结局（日志与测试共用）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CornerOutcome {
+    /// 非 Windows：空实现，什么都没做。
+    UnsupportedPlatform,
+    /// 句柄为 0：还没拿到窗口，或窗口已销毁。
+    NoWindow,
+    /// 已下发且回读一致。`readback == None` 表示**这一版 DWM 不接受回读**
+    /// （属性不被认识时 `DwmGetWindowAttribute` 返回 `E_INVALIDARG`），此时只有 `S_OK` 作证。
+    Applied {
+        /// 下发下去的偏好值（[`DWMWCP_ROUND`] / [`DWMWCP_DONOTROUND`]）。
+        preference: u32,
+        /// DWM 侧回读到的值（`None` = 读不回来）。
+        readback: Option<u32>,
+        /// 回读那一次的 `HRESULT`（`0` = `S_OK`）。
+        read_hresult: u32,
+    },
+    /// 属性不被这个 Windows 版本认识（`E_INVALIDARG`）：Win10 就是这个结局。
+    Unsupported {
+        /// `DwmSetWindowAttribute` 的原始 `HRESULT`。
+        hresult: u32,
+    },
+    /// 其他失败（句柄无效等），`hresult` 来自 DWM。
+    Failed {
+        /// `DwmSetWindowAttribute` 的原始 `HRESULT`。
+        hresult: u32,
+    },
+}
+
+impl CornerOutcome {
+    /// 一行日志尾巴：`corner=source=dwm pref=2 readback=2`。
+    ///
+    /// `readback=?` 与 `pref=none`（平台不支持）是不同的坏消息：前者是「设了但读不回来」，
+    /// 后者是「这里根本没有这个能力」。
+    #[must_use]
+    pub fn describe(&self) -> String {
+        match self {
+            Self::UnsupportedPlatform => "pref=none readback=n/a platform=unsupported".to_owned(),
+            Self::NoWindow => "pref=none readback=n/a window=none".to_owned(),
+            Self::Applied {
+                preference,
+                readback,
+                read_hresult,
+            } => format!(
+                "pref={preference} readback={} read_hr=0x{read_hresult:08X}",
+                readback.map_or_else(|| "?".to_owned(), |value| value.to_string())
+            ),
+            Self::Unsupported { hresult } => {
+                format!("pref=none readback=n/a hresult=0x{hresult:08X} (attribute unsupported)")
+            }
+            Self::Failed { hresult } => format!("pref=none readback=n/a hresult=0x{hresult:08X}"),
+        }
+    }
+}
+
+/// `HRESULT` 是不是 `E_INVALIDARG`（`0x8007_0057`）：Win10 上设这个属性就是这个返回值。
+#[cfg(target_os = "windows")]
+const E_INVALIDARG: u32 = 0x8007_0057;
+
+/// 把「来源」映射成要下发的偏好值（纯函数，测试直接钉它）。
+///
+/// `Dwm` → [`DWMWCP_ROUND`]；`Square` → [`DWMWCP_DONOTROUND`]。
+/// 刻意**不用**默认值（`0`）：那在 Win11 上等于「请 DWM 自己决定」，而无边框窗口
+/// 到底算不算「有框」由 DWM 的启发式决定——那正是我们要么拿到、要么明确放弃的东西。
+#[must_use]
+pub const fn preference_for(source: super::super::corner::CornerSource) -> u32 {
+    use super::super::corner::CornerSource;
+    match source {
+        CornerSource::Dwm => DWMWCP_ROUND,
+        CornerSource::Square => DWMWCP_DONOTROUND,
+    }
+}
+
+/// 下发一次圆角偏好（幂等：重复调用结果相同）。
+pub fn apply_corner(hwnd: isize, plan: &super::super::corner::CornerPlan) -> CornerOutcome {
+    if hwnd == 0 {
+        return CornerOutcome::NoWindow;
+    }
+    set_preference(hwnd, preference_for(plan.source))
+}
+
+/// 下发一个具体的偏好值并回读（拆开是为了让探针能逐格遍历）。
+pub fn set_preference(hwnd: isize, preference: u32) -> CornerOutcome {
+    #[cfg(not(target_os = "windows"))]
+    {
+        let _ = (hwnd, preference);
+        return CornerOutcome::UnsupportedPlatform;
+    }
+    #[cfg(target_os = "windows")]
+    {
+        if hwnd == 0 {
+            return CornerOutcome::NoWindow;
+        }
+        let hresult = super::dwm_set_u32(hwnd, DWMWA_WINDOW_CORNER_PREFERENCE, preference);
+        if !super::hresult_ok(hresult) {
+            // 原始位，不是 `unsigned_abs()`（见 `dwm_get_u32_hr` 的注释：后者印不出 HRESULT）。
+            let code = hresult as u32;
+            return if code == E_INVALIDARG {
+                CornerOutcome::Unsupported { hresult: code }
+            } else {
+                CornerOutcome::Failed { hresult: code }
+            };
+        }
+        let (readback, read_hresult) = corner_preference_hr(hwnd);
+        CornerOutcome::Applied {
+            preference,
+            readback,
+            read_hresult,
+        }
+    }
+}
+
+/// 读圆角偏好**以及它的 `HRESULT`**（`(None, code)` = 读不回来，`code` 是 DWM 给的原因）。
+///
+/// 为什么要暴露 `HRESULT`：M116 本机实测——**写成功、读回 `E_INVALIDARG`**。只报 `?`
+/// 会让「设上了吗」变成猜谜；有了码就能说清是「属性不支持读」而不是「没设上」。
+#[must_use]
+pub fn corner_preference_hr(hwnd: isize) -> (Option<u32>, u32) {
+    #[cfg(target_os = "windows")]
+    {
+        super::dwm_get_u32_hr(hwnd, DWMWA_WINDOW_CORNER_PREFERENCE)
+    }
+    #[cfg(not(target_os = "windows"))]
+    {
+        let _ = hwnd;
+        (None, 0)
+    }
+}
+
+/// 读可见边框厚度（像素）。**诊断用，不可作判据**（本机三样式三态实测全是 1，见常量文档）。
+#[must_use]
+pub fn visible_border_thickness(hwnd: isize) -> Option<u32> {
+    #[cfg(target_os = "windows")]
+    {
+        super::dwm_get_u32(hwnd, DWMWA_VISIBLE_FRAME_BORDER_THICKNESS)
+    }
+    #[cfg(not(target_os = "windows"))]
+    {
+        let _ = hwnd;
+        None
+    }
+}
+
+/// 读 DWM 的窗口边界（`left, top, right, bottom`，屏幕坐标）。
+#[must_use]
+pub fn extended_frame_bounds(hwnd: isize) -> Option<(i32, i32, i32, i32)> {
+    #[cfg(target_os = "windows")]
+    {
+        super::dwm_get_rect(hwnd, DWMWA_EXTENDED_FRAME_BOUNDS)
+            .map(|rect| (rect.left, rect.top, rect.right, rect.bottom))
+    }
+    #[cfg(not(target_os = "windows"))]
+    {
+        let _ = hwnd;
+        None
+    }
+}
+
+/// 读 `GetWindowRect`（含 DWM 加出来的不可见边框），用于和 [`extended_frame_bounds`] 求差。
+#[must_use]
+pub fn window_rect(hwnd: isize) -> Option<(i32, i32, i32, i32)> {
+    #[cfg(target_os = "windows")]
+    {
+        super::window_rect(hwnd).map(|rect| (rect.left, rect.top, rect.right, rect.bottom))
+    }
+    #[cfg(not(target_os = "windows"))]
+    {
+        let _ = hwnd;
+        None
+    }
+}
+
+/// 读窗口样式位（`GWL_STYLE` = `-16`）：日志里 `frame=` 那一栏的取值来源。
+///
+/// ⚠️ 产品窗口**不是** `WS_POPUP`（M116 r4 复审订正）：winit 在 `decorations = false` 下给的是
+/// `WS_CAPTION|WS_BORDER|...`（见 `probe::PRODUCT_STYLE`），真进程的 `frame=` 应为 `overlapped`
+/// （关掉 min/max 则 `other`）。「无边框」是 `WM_NCCALCSIZE` 的效果，不是样式位。
+#[must_use]
+pub fn window_style(hwnd: isize) -> Option<isize> {
+    #[cfg(target_os = "windows")]
+    {
+        (hwnd != 0).then(|| super::window_style(hwnd))
+    }
+    #[cfg(not(target_os = "windows"))]
+    {
+        let _ = hwnd;
+        None
+    }
+}
+
+/// 读窗口扩展样式位（`GWL_EXSTYLE`）：配合 [`window_style`] 回答「我们是不是 `WS_EX_LAYERED`」。
+#[must_use]
+pub fn window_ex_style(hwnd: isize) -> Option<isize> {
+    #[cfg(target_os = "windows")]
+    {
+        (hwnd != 0).then(|| super::raw_ex_style(hwnd))
+    }
+    #[cfg(not(target_os = "windows"))]
+    {
+        let _ = hwnd;
+        None
+    }
+}
+
+/// `WS_POPUP` 位（`0x8000_0000`）：**带 owner 的弹出窗**才置它；产品主窗口不用这一位。
+pub const WS_POPUP: isize = 0x8000_0000_u32 as isize;
+
+/// 帧样式的一句话标签（纯函数，日志用）：`popup` / `overlapped` / `other`。
+///
+/// 为什么要它：用户的现象是「别的窗口有圆角，我们的没有」。把它打进日志，才能一眼看出
+/// 窗口形状这一项**不是**变量（产品恒为 `overlapped`）——真正让系统忽略圆角请求的是整窗 α
+/// 引入的 `WS_EX_LAYERED`（见 `layered=` 与 `suppressed_by=window_alpha`），不是 `popup` 形状。
+#[must_use]
+pub const fn frame_label(style: isize) -> &'static str {
+    const WS_OVERLAPPEDWINDOW_MASK: isize = 0x00CF_0000;
+    if style & WS_POPUP != 0 {
+        "popup"
+    } else if style & WS_OVERLAPPEDWINDOW_MASK == WS_OVERLAPPEDWINDOW_MASK {
+        "overlapped"
+    } else {
+        "other"
+    }
+}
+
+/// 分层位的一句话标签（纯函数，日志用）：`on` / `off`。
+#[must_use]
+pub const fn layered_label(ex_style: isize) -> &'static str {
+    if ex_style & super::WS_EX_LAYERED != 0 {
+        "on"
+    } else {
+        "off"
+    }
+}
+
+/// 一个窗口的样式摘要（`frame=overlapped layered=off`，产品真进程实测值）；读不到时如实写
+/// `frame=? layered=?`。「`frame=popup`」只会出现在**带 owner 的弹出窗**上，产品不会。
+#[must_use]
+pub fn style_summary(hwnd: isize) -> String {
+    let frame = window_style(hwnd).map_or("?", frame_label);
+    let layered = window_ex_style(hwnd).map_or("?", layered_label);
+    format!("frame={frame} layered={layered}")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{
+        apply_corner, corner_preference_hr, preference_for, CornerOutcome,
+        DWMWA_VISIBLE_FRAME_BORDER_THICKNESS, DWMWA_WINDOW_CORNER_PREFERENCE, DWMWCP_DONOTROUND,
+        DWMWCP_ROUND,
+    };
+    use crate::platform::win32::corner::{CornerPlan, CornerSource};
+    use unlucky_presenter::prefs::WindowsVersion;
+
+    /// **抓得住**：属性号写错（34 写成 33 / 37 写成 36 —— 这两个都在 Win11 上存在，改错不会崩，
+    /// 只会静默读出别的东西）、两个偏好值互换。
+    /// **抓不住**：这些值在真窗口上是否真的生效（那要探针读数，见 `probe` 与报告）。
+    #[test]
+    fn attribute_numbers_follow_the_win32_header() {
+        assert_eq!(DWMWA_WINDOW_CORNER_PREFERENCE, 34);
+        assert_eq!(DWMWA_VISIBLE_FRAME_BORDER_THICKNESS, 37);
+        assert_eq!(DWMWCP_ROUND, 2);
+        assert_eq!(DWMWCP_DONOTROUND, 1);
+    }
+
+    /// **抓得住**：`preference_for` 把圆角/直角映射反了（这一格反了就是「设置里选直角反而更圆」）。
+    #[test]
+    fn the_preference_mapping_cannot_be_swapped() {
+        assert_eq!(preference_for(CornerSource::Dwm), DWMWCP_ROUND);
+        assert_eq!(preference_for(CornerSource::Square), DWMWCP_DONOTROUND);
+    }
+
+    /// 无效句柄：**不下发**、也不 panic。句柄 0 走 `NoWindow`（还没拿到窗口 ≠ 平台不支持）。
+    #[test]
+    fn a_missing_window_is_reported_not_guessed() {
+        let plan = CornerPlan {
+            source: CornerSource::Dwm,
+            excluded: None,
+            os: Some(WindowsVersion::new(10, 0, 26_100)),
+        };
+        assert_eq!(apply_corner(0, &plan), CornerOutcome::NoWindow);
+        assert_eq!(corner_preference_hr(0).0, None);
+        // 1 号句柄永远无效：非 Windows 上是「平台不支持」，Windows 上是 DWM 的失败码，
+        // 两种都不许表现成「成功」。
+        let outcome = apply_corner(1, &plan);
+        assert!(
+            matches!(
+                outcome,
+                CornerOutcome::Failed { .. }
+                    | CornerOutcome::Unsupported { .. }
+                    | CornerOutcome::UnsupportedPlatform
+            ),
+            "无效句柄应报失败，实际 {outcome:?}"
+        );
+    }
+
+    /// 日志尾巴三态可区分：设了 / 设了但读不回 / 属性不支持。
+    #[test]
+    fn the_log_tail_separates_applied_from_unsupported() {
+        let applied = CornerOutcome::Applied {
+            preference: DWMWCP_ROUND,
+            readback: Some(DWMWCP_ROUND),
+            read_hresult: 0,
+        };
+        assert!(
+            applied.describe().starts_with("pref=2 readback=2"),
+            "{applied:?}"
+        );
+
+        let blind = CornerOutcome::Applied {
+            preference: DWMWCP_ROUND,
+            readback: None,
+            read_hresult: 0x8000_4005,
+        };
+        assert!(
+            blind.describe().contains("readback=?"),
+            "{}",
+            blind.describe()
+        );
+
+        let old = CornerOutcome::Unsupported {
+            hresult: 0x8007_0057,
+        };
+        assert!(
+            old.describe().contains("attribute unsupported"),
+            "{}",
+            old.describe()
+        );
+        assert!(CornerOutcome::UnsupportedPlatform
+            .describe()
+            .contains("platform=unsupported"));
+    }
+}
+
+/// **抓得住**：`frame_label` 把 `WS_POPUP` 与 `WS_OVERLAPPEDWINDOW` 判反（那会让日志把
+/// 「我们自己的窗口」写成「普通窗口」，这行日志的全部价值就是分辨这个）。
+/// **抓不住**：真窗口上到底置了哪一位（那属于运行时读数）。
+#[test]
+fn the_frame_label_separates_popup_from_a_decorated_window() {
+    assert_eq!(WS_POPUP, 0x8000_0000_u32 as isize);
+    assert_eq!(frame_label(WS_POPUP | 0x1000_0000), "popup");
+    assert_eq!(frame_label(0x00CF_0000), "overlapped");
+    assert_eq!(frame_label(0), "other");
+}
+
+/// 分层位标签：只认 `WS_EX_LAYERED`，别把 `WS_EX_TRANSPARENT` 之类的邻居混进来。
+#[test]
+fn the_layered_label_reads_the_right_bit() {
+    let layered = crate::platform::win32::transparency::WS_EX_LAYERED;
+    assert_eq!(layered_label(layered), "on");
+    assert_eq!(layered_label(WS_POPUP), "off");
+    assert_eq!(layered_label(0), "off");
+}
+
+/// 读不到句柄时摘要不许编：`frame=? layered=?`（「不知道」与「没有」是两件事）。
+#[test]
+fn the_style_summary_never_guesses() {
+    assert_eq!(style_summary(0), "frame=? layered=?");
+}
diff --git a/crates/app-iced/src/platform/win32/transparency/exstyle.rs b/crates/app-iced/src/platform/win32/transparency/exstyle.rs
new file mode 100644
index 0000000..82c8ab4
--- /dev/null
+++ b/crates/app-iced/src/platform/win32/transparency/exstyle.rs
@@ -0,0 +1,107 @@
+//! 取证用的**扩展样式探针**（M100 r1 P2-2）：这个窗口是不是「点击穿透」。
+//!
+//! ## 本文件零 `unsafe`、零 `extern`
+//!
+//! 全仓 `unsafe` 只允许出现在 [`super`]（`transparency.rs`）一个文件里，判据是
+//! 「**带放行属性**的文件集合恰好等于它」。所以探针需要的 FFI 一律由 `transparency.rs` 提供
+//! **安全包装**（[`super::window_exists`] / [`super::raw_ex_style`]），本文件只做纯判断、
+//! 三态映射与测试。
+//!
+//! ⚠️ **别把 FFI 写回来**（M100 r1 复审实测抓过一次）：lint 级别沿模块树继承，所以在这里写
+//! 一个 `unsafe` 块 + `extern` 声明也**编得过**，`unsafe-scope` 门禁也照样绿（它只数「带放行
+//! 属性的文件」）——但「全仓唯一允许 unsafe 的文件」这个性质就破了。
+//! 属性的作用是可审计性，不是给 CI 看的。
+//!
+//! ## 判据来源
+//!
+//! winit 0.30 在 Windows 把 `set_cursor_hittest(false)` 落成
+//! `WS_EX_TRANSPARENT | WS_EX_LAYERED`（`window_state.rs`）。所以读回这一位，就是
+//! 「取证窗口真的把命中测试关掉了」的 OS 侧证据——比「出图 hash 不变」有判别力得多
+//! （实测：同 argv 开/关穿透，hash 完全相同）。
+
+use super::raw_ex_style;
+
+/// `WS_EX_TRANSPARENT`：**点击穿透**位（`0x0000_0020`）。
+pub const WS_EX_TRANSPARENT: isize = 0x0000_0020;
+
+/// 纯判据：扩展样式里 [`WS_EX_TRANSPARENT`] 在不在。
+///
+/// 单独拎成 `const fn` 是为了让「位判断写反」有断言盯着——`& WS_EX_TRANSPARENT != 0` 写成
+/// `== 0` 是这类 getter 最经典的错，而且只会在「开/关恰好反向」时暴露（两边都"有输出"）。
+#[must_use]
+pub const fn is_click_through_style(ex_style: isize) -> bool {
+    ex_style & WS_EX_TRANSPARENT != 0
+}
+
+/// 取证用：窗口**现在**是否点击穿透（`WS_EX_TRANSPARENT` 在扩展样式里）。
+///
+/// ## 为什么是三态而不是 `bool`
+///
+/// `None` = **没读到**（非 Windows / 句柄无效 / 句柄还没拿到）。这时调用方必须记 `unknown`，
+/// **不许记成 `off`**——「拿不到」和「没有」是两件事，混为一谈就是假绿（本项目在别处栽过：
+/// 扫描读不全时报「没有」）。所以这里宁可 `None`，也不用「读失败的 0」冒充「没这一位」。
+///
+/// ## 为什么本文件零 `unsafe`、零 `extern`
+///
+/// `unsafe` 全仓只在 [`super`]（`transparency.rs`）那一个文件里。探针需要的 FFI
+/// （`IsWindow` / `GetWindowLongPtrW`）都由 `super` 提供安全包装
+/// （[`super::window_exists`] / [`super::raw_ex_style`]），本文件只做**纯判断**。
+///
+/// ## 用途
+///
+/// 出图时把它打进日志（`pages::harness` 的 `[caps] passthrough_ext=…`），于是「取证窗口到底
+/// 有没有把指针输入关掉」每次运行都能自证，不依赖外部探针。
+#[cfg(target_os = "windows")]
+#[must_use]
+pub fn click_through(hwnd: isize) -> Option<bool> {
+    if hwnd == 0 || !super::window_exists(hwnd) {
+        return None;
+    }
+    Some(is_click_through_style(raw_ex_style(hwnd)))
+}
+
+/// 非 Windows：**恒 `None`**。空实现不许冒充「没开穿透」（那就是把「不知道」写成「没有」）。
+#[cfg(not(target_os = "windows"))]
+#[must_use]
+pub fn click_through(_hwnd: isize) -> Option<bool> {
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{click_through, is_click_through_style, WS_EX_TRANSPARENT};
+    use crate::platform::win32::transparency::WS_EX_LAYERED;
+
+    /// **抓得住**：`& WS_EX_TRANSPARENT != 0` 被写成 `== 0`（位判断反向）——这是这类 getter 最经典
+    /// 的错，而且只会在「开/关恰好互换」时暴露：日志里永远有值，只是意思反了。
+    /// **抓不住**：真实窗口上 winit 到底置没置这一位（那要出图日志里看 `passthrough_ext=on`）。
+    #[test]
+    fn the_click_through_bit_cannot_be_read_backwards() {
+        assert_eq!(WS_EX_TRANSPARENT, 0x0000_0020, "位值照 Win32 头文件");
+        assert!(is_click_through_style(WS_EX_TRANSPARENT));
+        assert!(
+            is_click_through_style(WS_EX_TRANSPARENT | WS_EX_LAYERED),
+            "winit 的鼠标穿透是两位一起置的，这种组合必须是 true"
+        );
+        assert!(
+            !is_click_through_style(WS_EX_LAYERED),
+            "只有分层位不算穿透——LWA_ALPHA 也加这一位，反向了会把正常窗口误判成穿透"
+        );
+        assert!(!is_click_through_style(0));
+    }
+
+    /// **抓得住**：「拿不到」被记成「没有」。句柄 0 / 无效句柄 / 非 Windows 必须是 `None`
+    /// （调用方据此写 `unknown`），不许用「读失败的 0」冒充「这一位没开」。
+    /// **抓不住**：一个**有效**窗口上的读数（那要真窗口，见 harness 的出图日志）。
+    #[test]
+    fn click_through_reports_unknown_instead_of_off_when_it_cannot_read() {
+        assert_eq!(click_through(0), None, "句柄 0 = 还没拿到窗口 ⇒ unknown");
+        assert_eq!(click_through(1), None, "无效句柄 ⇒ unknown（不许掉成 off）");
+        #[cfg(not(target_os = "windows"))]
+        assert_eq!(
+            click_through(0x1234),
+            None,
+            "非 Windows 的空实现必须恒 None，不许冒充 off"
+        );
+    }
+}
diff --git a/crates/app-iced/src/platform/win32/transparency/probe.rs b/crates/app-iced/src/platform/win32/transparency/probe.rs
new file mode 100644
index 0000000..2a307ac
--- /dev/null
+++ b/crates/app-iced/src/platform/win32/transparency/probe.rs
@@ -0,0 +1,342 @@
+//! M116 的**受控对照实验**：同进程里造几种窗口样式，逐个读 DWM 属性。
+//!
+//! ## 为什么需要它
+//!
+//! 用户的观察是「同一台机器上别的窗口都有圆角，只有我们的没有」。于是「没圆角」至少有三种
+//! 可能：①这是 DWM 的默认行为（我们没申请）；②某个**样式位**把它 opt-out 了；③属性根本设不上。
+//!
+//! 只在自己的窗口上读一次，分不清 ①②③。所以这里**同一进程**里造几个窗口，除「样式」外
+//! 条件全相同：
+//!
+//! | 标签 | 样式 | 它代表什么 |
+//! |---|---|---|
+//! | `decorated` | `WS_OVERLAPPEDWINDOW` | 用户说的「别的窗口」（对照） |
+//! | `probe:popup` | 裸 `WS_POPUP` | **对照，不是产品形状**：带 owner 的弹出窗才用这一位 |
+//! | `probe:popup+layered` | `WS_POPUP` + `WS_EX_LAYERED`(α) | **对照**：把两个嫌疑同时打开 |
+//! | `product` | [`PRODUCT_STYLE`]（α = 1，不补分层） | 产品的**真实**样式（出厂态） |
+//! | `product+alpha` | [`PRODUCT_STYLE`] + `WS_EX_LAYERED`(α) | 产品真实样式 + 用户把整窗 α 拉低 |
+//!
+//! ## ⚠️ 产品窗口**不是** `WS_POPUP`（M116 r4 复审订正）
+//!
+//! iced/winit 在 `decorations = false` 下**不会**用 `WS_POPUP`：winit 的
+//! `window_state.rs::to_window_styles` 起点是 `WS_CAPTION|WS_BORDER|WS_CLIPSIBLINGS|WS_SYSMENU`，
+//! 可缩放/可最大化时再加 `WS_THICKFRAME|WS_MINIMIZEBOX|WS_MAXIMIZEBOX`；`WS_POPUP` 只在
+//! `WindowFlags::POPUP`（**带 owner** 的弹出窗）时才加。产品的「无边框观感」来自
+//! `WM_NCCALCSIZE` 把客户区铺满，**不是**样式位。
+//!
+//! 所以本文件早期那句「`popup+layered` = 本产品窗口的完整形状」是**错的**：那一行的读数
+//! （尤其 `Δframe = +0,+0`）只属于假形状，不能拿去解释产品窗口。要解释产品，看 `product`
+//! 与 `product+alpha` 两行。
+//!
+//! ## 这个实验能证明什么、不能证明什么
+//!
+//! **能**：属性层能不能开（`DwmSetWindowAttribute` 的 `HRESULT`）、开完 DWM 侧回读是多少、
+//! 各样式之间 `DWMWA_VISIBLE_FRAME_BORDER_THICKNESS` 与
+//! `DWMWA_EXTENDED_FRAME_BOUNDS - GetWindowRect` 的数值差是否随样式变化。
+//!
+//! **不能**：角上到底是不是透明的（那要合成输出像素，本机 RDP 断连拿不到）。所以本文件
+//! 的读数只回答「属性层」，观感归真机验收——报告里逐条标注。
+
+#[cfg(target_os = "windows")]
+use super::alpha::{apply_window_alpha, ensure_layered};
+use super::dwm::{
+    corner_preference_hr, extended_frame_bounds, set_preference, visible_border_thickness,
+    window_rect, window_style, CornerOutcome, DWMWCP_DONOTROUND, DWMWCP_ROUND,
+};
+
+/// `WS_POPUP`（`0x8000_0000`）：**带 owner 的弹出窗**才用它；产品主窗口没有 owner，不用。
+pub const WS_POPUP: u32 = 0x8000_0000;
+/// `WS_OVERLAPPEDWINDOW`：普通有边框窗口（对照组的「别的窗口」）。
+pub const WS_OVERLAPPEDWINDOW: u32 = 0x00CF_0000;
+
+/// `WS_CAPTION`（`WS_BORDER | WS_DLGFRAME`）。
+const WS_CAPTION: u32 = 0x00C0_0000;
+/// `WS_BORDER`（= `WS_THICKFRAME` 的低位别名，`0x0080_0000`）。
+const WS_BORDER: u32 = 0x0080_0000;
+/// `WS_CLIPSIBLINGS`：子窗口层叠顺序位（DWM 不看它，winit 的起点里有）。
+const WS_CLIPSIBLINGS: u32 = 0x0400_0000;
+/// `WS_SYSMENU`。
+const WS_SYSMENU: u32 = 0x0008_0000;
+/// `WS_THICKFRAME`（可缩放边框）。
+const WS_THICKFRAME: u32 = 0x0004_0000;
+/// `WS_MINIMIZEBOX`。
+const WS_MINIMIZEBOX: u32 = 0x0002_0000;
+/// `WS_MAXIMIZEBOX`。
+const WS_MAXIMIZEBOX: u32 = 0x0001_0000;
+
+/// **产品窗口的真实样式位**（iced/winit，`decorations = false`，可缩放、可最大化、可最小化）。
+///
+/// 出处（可复核）：winit `window_state.rs::to_window_styles` 从
+/// `WS_CAPTION|WS_BORDER|WS_CLIPSIBLINGS|WS_SYSMENU` 起手，`RESIZABLE` / `MAXIMIZABLE` /
+/// `MINIMIZABLE` 分别加 `WS_THICKFRAME` / `WS_MAXIMIZEBOX` / `WS_MINIMIZEBOX`；`WS_POPUP`
+/// 只在 `WindowFlags::POPUP`（带 owner）时才加——产品主窗口不带。
+///
+/// 这些**位**是输入（照抄 winit 的产物，带出处）；表里那一行 `product` 的**读数**是跑出来的，
+/// 不是我写死的。
+pub const PRODUCT_STYLE: u32 = WS_CAPTION
+    | WS_BORDER
+    | WS_CLIPSIBLINGS
+    | WS_SYSMENU
+    | WS_THICKFRAME
+    | WS_MINIMIZEBOX
+    | WS_MAXIMIZEBOX;
+
+/// `WS_EX_LAYERED` 的 `u32` 形态（`create_probe_window` 的参数类型）。
+const WS_EX_LAYERED_U32: u32 = 0x0008_0000;
+
+/// 实验里的一行（一个窗口样式）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProbeRow {
+    /// 这一行是什么样式（见模块文档的表）。
+    pub label: &'static str,
+    /// 创建时请求的样式位。
+    pub style: u32,
+    /// 创建时请求的扩展样式位。
+    pub ex_style: u32,
+    /// 读回的 `GWL_STYLE`（证明请求的样式真的生效了）。
+    pub style_readback: Option<isize>,
+    /// 什么都没设时 DWM 侧的偏好值（`0` = `DWMWCP_DEFAULT`）。
+    pub preference_default: Option<u32>,
+    /// 读上面那一格时的 `HRESULT`（`0` = `S_OK`；非 0 说明这个会话读不出 DWM 属性）。
+    pub preference_read_hresult: u32,
+    /// 设为 [`DWMWCP_ROUND`] 的结局（含回读）。
+    pub set_round: CornerOutcome,
+    /// 设为 [`DWMWCP_DONOTROUND`] 的结局（含回读）。
+    pub set_square: CornerOutcome,
+    /// 默认状态下的可见边框厚度（像素）。
+    pub border_default: Option<u32>,
+    /// 圆角状态下的可见边框厚度（像素）。
+    pub border_round: Option<u32>,
+    /// 直角状态下的可见边框厚度（像素）。
+    pub border_square: Option<u32>,
+    /// `extended_frame_bounds - GetWindowRect` = `(dx, dy)`（各边差值之和）；
+    /// `None` = 任一侧读不到。
+    pub frame_delta: Option<(i32, i32)>,
+    /// 窗口是否真的造出来了（`false` = 本机造不出窗口，整行无效）。
+    pub created: bool,
+}
+
+impl ProbeRow {
+    /// 表格里的一行（对齐成文本，报告直接贴）。
+    ///
+    /// **一格一格拼**而不是一条长 `format!`：位置参数一多，「多了/少了一个占位符」在编译期报、
+    /// 在报告里却表现为整张表错位；这里列数由 [`TABLE_HEADER`] 与 [`Self::cells`] 同时决定，
+    /// 单测比对竖线数。
+    #[must_use]
+    pub fn describe(&self) -> String {
+        format!("| {} |", self.cells().join(" | "))
+    }
+
+    /// 各列的原始文本（与 [`TABLE_HEADER`] 同序）。
+    #[must_use]
+    pub fn cells(&self) -> Vec<String> {
+        let show = |value: Option<u32>| value.map_or_else(|| "?".to_owned(), |v| v.to_string());
+        let delta = self
+            .frame_delta
+            .map_or_else(|| "?".to_owned(), |(dx, dy)| format!("{dx:+},{dy:+}"));
+        vec![
+            format!("{:<14}", self.label),
+            format!("0x{:08X}", self.style),
+            format!("0x{:08X}", self.ex_style),
+            self.style_readback
+                .map_or_else(|| "?".to_owned(), |style| format!("0x{:08X}", style as u32)),
+            show(self.preference_default),
+            format!("0x{:08X}", self.preference_read_hresult),
+            show(self.border_default),
+            show(self.border_round),
+            show(self.border_square),
+            delta,
+            self.set_round.describe(),
+            self.set_square.describe(),
+            if self.created { "ok" } else { "FAILED" }.to_owned(),
+        ]
+    }
+}
+
+/// 表头（与 [`ProbeRow::describe`] 的列一一对应）。
+pub const TABLE_HEADER: &str = "| style | requested | exstyle | readback | pref | read_hr | bdef | brnd | bsq | Δframe | set ROUND | set SQUARE | created |";
+
+/// 跑一遍受控对照实验（非 Windows 返回空表）。
+///
+/// 前两行是对照（**不是产品形状**），后两行才是产品：`product` = 出厂态（α = 1，不补分层），
+/// `product+alpha` = 用户把整窗 α 拉低之后的真实形状。
+///
+/// 每个窗口用完立刻销毁：这是诊断路径，不许留 HWND。
+#[must_use]
+pub fn controlled_experiment() -> Vec<ProbeRow> {
+    let mut rows = Vec::new();
+    for (label, style, ex_style) in [
+        ("decorated", WS_OVERLAPPEDWINDOW, 0u32),
+        ("probe:popup", WS_POPUP, 0u32),
+        ("probe:popup+layered", WS_POPUP, WS_EX_LAYERED_U32),
+        ("product", PRODUCT_STYLE, 0u32),
+        ("product+alpha", PRODUCT_STYLE, WS_EX_LAYERED_U32),
+    ] {
+        rows.push(run_one(label, style, ex_style));
+    }
+    rows
+}
+
+/// 一个样式的完整读数。`created = false` 时其余字段全 `None`（**不许**拿 0 冒充读数）。
+#[cfg(target_os = "windows")]
+fn run_one(label: &'static str, style: u32, ex_style: u32) -> ProbeRow {
+    use super::{create_probe_window, destroy_probe_window, show_probe_window};
+
+    let hwnd = create_probe_window(style, ex_style);
+    if hwnd == 0 {
+        return empty_row(label, style, ex_style);
+    }
+    show_probe_window(hwnd);
+    // D36 的整窗 α：只有 layered 那一行才有意义（`apply_window_alpha` 对 α=1 不下发）。
+    if ex_style & WS_EX_LAYERED_U32 != 0 {
+        ensure_layered(hwnd);
+        let _ = apply_window_alpha(hwnd, Some(0.8));
+    }
+
+    let (preference_default, preference_read_hresult) = corner_preference_hr(hwnd);
+    let border_default = visible_border_thickness(hwnd);
+    let set_round = set_preference(hwnd, DWMWCP_ROUND);
+    let border_round = visible_border_thickness(hwnd);
+    let set_square = set_preference(hwnd, DWMWCP_DONOTROUND);
+    let border_square = visible_border_thickness(hwnd);
+
+    let frame_delta =
+        window_rect(hwnd)
+            .zip(extended_frame_bounds(hwnd))
+            .map(|(plain, extended)| {
+                (
+                    (extended.0 - plain.0) + (extended.2 - plain.2),
+                    (extended.1 - plain.1) + (extended.3 - plain.3),
+                )
+            });
+
+    let row = ProbeRow {
+        label,
+        style,
+        ex_style,
+        style_readback: window_style(hwnd),
+        preference_default,
+        preference_read_hresult,
+        set_round,
+        set_square,
+        border_default,
+        border_round,
+        border_square,
+        frame_delta,
+        created: true,
+    };
+    destroy_probe_window(hwnd);
+    row
+}
+
+/// 非 Windows：造不出 Win32 窗口，整行标记 `created = false`（不许编读数）。
+#[cfg(not(target_os = "windows"))]
+fn run_one(label: &'static str, style: u32, ex_style: u32) -> ProbeRow {
+    empty_row(label, style, ex_style)
+}
+
+fn empty_row(label: &'static str, style: u32, ex_style: u32) -> ProbeRow {
+    ProbeRow {
+        label,
+        style,
+        ex_style,
+        style_readback: None,
+        preference_default: None,
+        preference_read_hresult: 0,
+        set_round: CornerOutcome::UnsupportedPlatform,
+        set_square: CornerOutcome::UnsupportedPlatform,
+        border_default: None,
+        border_round: None,
+        border_square: None,
+        frame_delta: None,
+        created: false,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::dwm::frame_label;
+    use super::{
+        controlled_experiment, ProbeRow, PRODUCT_STYLE, TABLE_HEADER, WS_OVERLAPPEDWINDOW, WS_POPUP,
+    };
+
+    /// **抓得住**：样式常量写错（`WS_POPUP` 少一个 0 就变成别的位，对照实验的前提就没了）。
+    #[test]
+    fn the_style_constants_match_the_win32_header() {
+        assert_eq!(WS_POPUP, 0x8000_0000);
+        assert_eq!(WS_OVERLAPPEDWINDOW, 0x00CF_0000);
+    }
+
+    /// **产品窗口不是 popup**（M116 r4 复审的核心事实，钉住它，别再写回去）。
+    ///
+    /// 抓得住：有人把 `PRODUCT_STYLE` 改回 `WS_POPUP`（那会让「产品形状」整条证据链回到错的假设上）；
+    /// 也抓得住 `PRODUCT_STYLE` 丢掉 `WS_CAPTION`/`WS_THICKFRAME`（那会让 `Δframe` 从 `+0,−7`
+    /// 掉成 `+0,+0`，把「产品没有边框带」这个错结论复活）。
+    /// 抓不住：真进程上 winit 到底置了哪些位（那看 `[corner] … frame=` 的运行时读数）。
+    #[test]
+    fn the_product_window_is_overlapped_not_popup() {
+        assert_eq!(
+            PRODUCT_STYLE & WS_POPUP,
+            0,
+            "产品主窗口没有 owner ⇒ 不带 WS_POPUP"
+        );
+        assert_ne!(
+            PRODUCT_STYLE & 0x00C0_0000,
+            0,
+            "WS_CAPTION 在（winit 起点）"
+        );
+        assert_ne!(PRODUCT_STYLE & 0x0004_0000, 0, "WS_THICKFRAME 在（可缩放）");
+        assert_eq!(frame_label(PRODUCT_STYLE as isize), "overlapped");
+        assert_eq!(frame_label(WS_POPUP as isize), "popup");
+    }
+
+    /// 实验固定五行，顺序固定：两行对照 + 两行产品 + `decorated` 参照。
+    ///
+    /// 抓得住：有人把分层那一行或产品行删了/调换——那样「layered 会不会让 DWM 忽略圆角请求」
+    /// 与「产品真实形状有没有边框带」这两条对照就都没了。
+    /// 抓不住：读数本身（那要么真机跑，要么看报告里的表）。
+    #[test]
+    fn the_experiment_always_covers_the_same_five_rows_in_order() {
+        let rows = controlled_experiment();
+        assert_eq!(rows.len(), 5);
+        let labels: Vec<_> = rows.iter().map(|row| row.label).collect();
+        assert_eq!(
+            labels,
+            [
+                "decorated",
+                "probe:popup",
+                "probe:popup+layered",
+                "product",
+                "product+alpha"
+            ]
+        );
+        assert_eq!(rows[0].style, WS_OVERLAPPEDWINDOW);
+        assert_eq!(rows[1].style, WS_POPUP);
+        assert_eq!(rows[2].ex_style & 0x0008_0000, 0x0008_0000);
+        // 产品两行：样式位相同（都是真实样式），只有 layered 一位不同。
+        assert_eq!(rows[3].style, PRODUCT_STYLE);
+        assert_eq!(rows[4].style, PRODUCT_STYLE);
+        assert_eq!(rows[3].ex_style & 0x0008_0000, 0, "出厂态 α=1 ⇒ 不补分层");
+        assert_eq!(rows[4].ex_style & 0x0008_0000, 0x0008_0000, "α<1 ⇒ 补分层");
+    }
+
+    /// 表头与每行的竖线数一致（`format!` 里多/少一列会让表格在报告里错位）。
+    #[test]
+    fn the_table_columns_line_up() {
+        let header_pipes = TABLE_HEADER.matches('|').count();
+        for row in controlled_experiment() {
+            let line = row.describe();
+            assert_eq!(
+                line.matches('|').count(),
+                header_pipes,
+                "列数不一致：{line}"
+            );
+        }
+        // 没造出窗口的行必须**没有**读数（不许用 0 冒充）。
+        let failed = ProbeRow {
+            created: false,
+            ..controlled_experiment().into_iter().next().expect("五行")
+        };
+        assert!(failed.describe().contains("FAILED"));
+    }
+}
diff --git a/crates/app-iced/src/platform/win32/transparency/tests.rs b/crates/app-iced/src/platform/win32/transparency/tests.rs
new file mode 100644
index 0000000..4f55898
--- /dev/null
+++ b/crates/app-iced/src/platform/win32/transparency/tests.rs
@@ -0,0 +1,233 @@
+//! `transparency` 的测试（M116 从 `transparency.rs` 搬出来：那个文件要留行数给 DWM 的 FFI）。
+//!
+//! **本文件零 `unsafe`、零 `extern`**：只调父模块的安全包装。别把 FFI 写进来——
+//! 「全仓唯一允许 unsafe 的文件」是 `transparency.rs`，不是它下面的每个文件。
+
+use super::{
+    alpha_byte, apply_window_alpha, ensure_layered, AlphaOutcome, AlphaRejection, GWL_EXSTYLE,
+    LWA_ALPHA, WS_EX_LAYERED,
+};
+use unlucky_presenter::prefs::WINDOW_ALPHA_MIN;
+
+#[test]
+fn layered_constants_match_the_win32_header() {
+    // 抓得住：常量写错（例如把 GWL_EXSTYLE 写成 -16 = GWL_STYLE，或 WS_EX_LAYERED 少写一个 0）。
+    // 抓不住：这些值在真实窗口上是否真的生效（那要靠真机日志，见 app 侧）。
+    assert_eq!(WS_EX_LAYERED, 0x0008_0000);
+    assert_eq!(GWL_EXSTYLE, -20);
+}
+
+#[test]
+fn ensure_layered_refuses_a_missing_or_invalid_window() {
+    // 句柄 0 = 还没拿到窗口：不许「假设成功」。
+    assert!(!ensure_layered(0), "句柄 0 必须返回 false");
+    // 1 号句柄永远无效：读不到扩展样式，也就加不上这一位。
+    assert!(!ensure_layered(1), "无效句柄必须返回 false（不 panic）");
+}
+
+#[test]
+fn alpha_byte_quantizes_upward_never_below_the_floor() {
+    assert_eq!(alpha_byte(1.0), 255);
+    assert_eq!(alpha_byte(0.5), 128, "0.5×255=127.5 → 向上取整 128");
+    assert_eq!(
+        alpha_byte(WINDOW_ALPHA_MIN),
+        21,
+        "0.08×255=20.4 → 向上取整 21；用 round 会得到 20，实际下发 20/255=0.0784 低于 D36 下限"
+    );
+    // 漏过预处理的坏值也不会变成「穿透」：一律落到下限字节。
+    for bad in [0.0, -3.0, f64::NAN] {
+        assert_eq!(
+            alpha_byte(bad),
+            alpha_byte(WINDOW_ALPHA_MIN),
+            "{bad} 应取下限"
+        );
+    }
+    assert_eq!(
+        LWA_ALPHA, 0x2,
+        "0x2 就是 LWA_ALPHA；写成 0x1 会变成色键、等于没设 α"
+    );
+}
+
+#[test]
+fn applied_alpha_is_never_below_the_floor() {
+    // 真正生效的 α 是 `bAlpha / 255`，不是传进来的 f64。这条把「改用 round」的行为钉死：
+    // round 下 0.08 → 20 → 20/255 = 0.0784 < 0.08 → 这里红。
+    for requested in [WINDOW_ALPHA_MIN, 0.081, 0.1, 0.33, 0.5, 0.77, 0.999, 1.0] {
+        let byte = alpha_byte(requested);
+        let applied = f64::from(byte) / 255.0;
+        assert!(
+            applied >= WINDOW_ALPHA_MIN - 1e-12,
+            "requested={requested} → byte={byte} → 实际 α={applied}，低于下限 {WINDOW_ALPHA_MIN}"
+        );
+        assert!(
+            applied <= 1.0,
+            "requested={requested} → 实际 α={applied} 超过 1.0"
+        );
+    }
+}
+
+#[test]
+fn missing_or_opaque_alpha_never_touches_the_window() {
+    for none in [None, Some(0.0), Some(-0.5), Some(f64::NAN)] {
+        assert_eq!(
+            apply_window_alpha(1234, none),
+            AlphaOutcome::Rejected(AlphaRejection::NoAlpha),
+            "{none:?} 应被拒绝（整窗穿透不许发生）"
+        );
+    }
+    // α = 1.0：两个平台都返回 Opaque —— 正好证明「不调 FFI」不是靠 Unsupported 混过去的。
+    assert_eq!(apply_window_alpha(1234, Some(1.0)), AlphaOutcome::Opaque);
+    // 合法 α 但没有句柄：拒绝，绝不下发。
+    assert_eq!(
+        apply_window_alpha(0, Some(0.5)),
+        AlphaOutcome::Rejected(AlphaRejection::NoWindow)
+    );
+}
+
+#[cfg(target_os = "windows")]
+#[test]
+fn invalid_handle_reports_a_win32_failure_instead_of_panicking() {
+    // 用 1 号句柄（永远无效）真调一次 API：验的是**返回值语义**，不是观感。
+    match apply_window_alpha(1, Some(0.5)) {
+        AlphaOutcome::Failed { code } => {
+            assert_eq!(code, 1400, "ERROR_INVALID_WINDOW_HANDLE")
+        }
+        other => panic!("无效句柄应报 Failed，实际 {other:?}"),
+    }
+}
+
+#[cfg(not(target_os = "windows"))]
+#[test]
+fn non_windows_stub_reports_unsupported() {
+    assert_eq!(apply_window_alpha(1, Some(0.5)), AlphaOutcome::Unsupported);
+}
+
+/// **受控对照实验**（M116）：同进程造三种窗口样式，逐行读 DWM 属性。
+///
+/// 为什么是 `#[ignore]`：它要真造窗口（CI 的无桌面环境里跑不出读数），所以只在需要出证据时
+/// 手动跑：
+///
+/// ```text
+/// cargo test -p unlucky-app-iced --lib m116 -- --ignored --nocapture
+/// ```
+///
+/// 输出就是报告里那张表（`| style | requested | exstyle | readback | … |`）。
+/// **抓不住**：角上到底是透明还是方块（那要合成输出像素，本机 RDP 断连拿不到）。
+#[cfg(target_os = "windows")]
+#[test]
+#[ignore = "要真窗口：手动跑 cargo test -p unlucky-app-iced --lib m116 -- --ignored --nocapture"]
+fn m116_corner_controlled_experiment() {
+    println!("{}", super::probe::TABLE_HEADER);
+    for row in super::controlled_experiment() {
+        println!("{}", row.describe());
+    }
+}
+
+/// **成功判据的语义**：`HRESULT` 看严重性位（bit 31），不是「等于 0」——`S_FALSE`(1) 也算成功。
+///
+/// ⚠️ 这条测试**不是**「本机 DWM 会返回某个正数」的证据：本机
+/// `DwmGetWindowAttribute` 三种窗口样式实测全 `E_INVALIDARG (0x80070057)`（失败）。
+/// 下面那个 `0x7FF8_FFA9` 是**合成值**，只用来钉住「非零但严重性位为 0 ⇒ 成功」这条规则，
+/// 以及钉住「`unsigned_abs()` 不能用来打印 HRESULT」这个打印坑。
+///
+/// 抓得住：把成功判据写回 `hr == 0`；把打印改回 `unsigned_abs()`。
+/// 抓不住：DWM 在别的机器上返回什么（那是运行期读数）。
+#[test]
+fn hresult_success_follows_the_severity_bit_not_equality_with_zero() {
+    use super::hresult_ok;
+    assert!(hresult_ok(0), "S_OK");
+    assert!(hresult_ok(1), "S_FALSE 也是成功");
+    assert!(
+        hresult_ok(0x7FF8_FFA9),
+        "合成值：非零但严重性位为 0 ⇒ 按 HRESULT 语义是成功（不是 DWM 的实测返回值）"
+    );
+    // 失败码：严重性位为 1（i32 负数）。**本机探针实际拿到的就是这个**。
+    assert!(!hresult_ok(0x8007_0057_u32 as i32), "E_INVALIDARG");
+    assert!(!hresult_ok(-1));
+    // **打印规则**：失败码必须印成 `hr as u32` 的原始位。
+    // `unsigned_abs()` 会把 `0x8007_0057` 印成 `0x7FF8_FFA9`（M116 踩过，一次误读的源头），
+    // 于是「E_INVALIDARG」读起来像「一个信息级成功码」，整个证据链就毁了。
+    let e_invalidarg = 0x8007_0057_u32 as i32;
+    assert_eq!(e_invalidarg as u32, 0x8007_0057);
+    assert_ne!(e_invalidarg.unsigned_abs(), 0x8007_0057);
+}
+
+/// **两种「错误号」不同源，打印方式也不同**（tower 裁定 2026-11-03：不许统一）。
+///
+/// - `GetLastError()` 是 **DWORD**：`87`（`ERROR_INVALID_PARAMETER`）/ `1400`
+///   （`ERROR_INVALID_WINDOW_HANDLE`）这类小整数，没有严重性位，`set_layered` 用
+///   `raw_os_error().unsigned_abs()` 取的就是它；
+/// - `Dwm*WindowAttribute` 返回 **HRESULT**：成功看 bit 31，打印用 `as u32` 原始位。
+///
+/// 抓得住：有人把 `set_layered` 也改成 `as u32`（或把 DWM 那侧改成 `unsigned_abs`）——
+/// 前者对 `87` 无害但对高位被置的错误号会印出负数，后者会把 `E_INVALIDARG` 印成
+/// `0x7FF8FFA9`（M116 实测踩过的那个坑）。
+#[test]
+fn dword_error_codes_and_hresults_are_printed_differently() {
+    use super::hresult_ok;
+
+    // DWORD 侧：典型值是小的正数，两种打印结果一致（所以错误只会在高位情形暴露）。
+    for dword in [87_i32, 1400] {
+        assert_eq!(dword.unsigned_abs(), dword as u32);
+        assert!(
+            hresult_ok(dword),
+            "DWORD 不是 HRESULT，不该拿这个判据去读它"
+        );
+    }
+
+    // HRESULT 侧：失败码的原始位与 `unsigned_abs()` 必须不同。
+    let e_invalidarg = 0x8007_0057_u32 as i32;
+    assert!(!hresult_ok(e_invalidarg));
+    assert_eq!(e_invalidarg as u32, 0x8007_0057);
+    assert_ne!(e_invalidarg.unsigned_abs(), e_invalidarg as u32);
+}
+
+/// **产品日志行 `[corner] …` 的真实取值**（同一套判据 + 同一套格式化，句柄换成探针窗口）。
+///
+/// `excluded_reason=` / `frame=` / `layered=` 三栏是「为什么我们的窗口没有圆角」的唯一现场线索；
+/// 报告里要贴真实取值，不是模板。跑法同 `m116`：
+///
+/// ```text
+/// cargo test -p unlucky-app-iced --lib m116 -- --ignored --nocapture
+/// ```
+#[cfg(target_os = "windows")]
+#[test]
+#[ignore = "要真窗口：手动跑 cargo test -p unlucky-app-iced --lib m116 -- --ignored --nocapture"]
+fn m116_corner_log_line_on_real_windows() {
+    use crate::platform::win32::corner::plan_corner;
+    use unlucky_presenter::prefs::WindowCorner;
+
+    let os = crate::platform::current_windows_version();
+    let plan = plan_corner(WindowCorner::System, os, crate::Backend::Gpu);
+    // 直接遍历 `controlled_experiment` 的**同一份**行定义（含 `product` / `product+alpha`），
+    // 免得这里另抄一份样式表、跟探针悄悄分叉。
+    for row in super::controlled_experiment() {
+        let hwnd = super::create_probe_window(row.style, row.ex_style);
+        if hwnd == 0 {
+            println!("[corner] {} window=none", row.label);
+            continue;
+        }
+        super::show_probe_window(hwnd);
+        // layered=on 的那几行（产品的 α<1 档与裸 popup 对照）按裁定 A 带 `suppressed_by=`。
+        let layered = row.ex_style & 0x0008_0000 != 0;
+        println!(
+            "{}",
+            crate::platform::win32::corner::format_line(
+                row.label,
+                &plan,
+                WindowCorner::System,
+                &super::apply_corner(hwnd, &plan).describe(),
+                &super::dwm::style_summary(hwnd),
+                layered.then_some("window_alpha"),
+            )
+        );
+        super::destroy_probe_window(hwnd);
+    }
+
+    // 设置里选「直角」时的取值（`excluded_reason` 必须变成 `user`）。
+    let square = plan_corner(WindowCorner::Square, os, crate::Backend::Gpu);
+    println!(
+        "[corner] policy=square {}",
+        square.log_line(WindowCorner::Square)
+    );
+}
diff --git a/crates/app-iced/src/presenter/agent.rs b/crates/app-iced/src/presenter/agent.rs
new file mode 100644
index 0000000..f6dd375
--- /dev/null
+++ b/crates/app-iced/src/presenter/agent.rs
@@ -0,0 +1,279 @@
+//! AI 助手栏的 presenter 句柄（M119）：四个契约 + 事件队列 + 具名错误。
+//!
+//! ## 它替掉的是什么
+//!
+//! M104 交付的壳是**自带样本会话**的（`pages/agent/demo.rs` 的 `transcript()`，`Submit` 只往
+//! 本地数组里追加一条「没发给模型」的提示）。M119 把这些全部删掉：会话内容的唯一来源是
+//! [`Presenter::agent_rail`]，壳里的 `Submit` / `Stop` / `Confirm` / 标记已读**全部**翻成
+//! presenter 的那四个签名——**壳里一行会话状态都不留**。
+//!
+//! | 壳里的动作 | 落到哪 |
+//! |---|---|
+//! | 输入框打字 | [`AgentHost::set_draft`] → `Presenter::agent_set_draft`（切形态不丢） |
+//! | 发送 | [`AgentHost::submit`] → `Presenter::agent_submit` |
+//! | 打开栏 / 停在独立页 | [`AgentHost::mark_read`] → `Presenter::agent_mark_read` |
+//! | 允许/拒绝写操作 | [`AgentHost::confirm`] → `Presenter::agent_confirm` |
+//! | 事件回流 | [`AgentHost::apply`] → `Presenter::apply`（唯一状态写入口） |
+//! | 栏可见性 | [`AgentHost::sync_visibility`] → `Presenter::navigate` + `prefs_mut` |
+//!
+//! ## 为什么句柄里还要持一份队列与失败槽
+//!
+//! presenter 不持有定时器，也不认识 iced（crate 文档 §4）。异步后端的事件只能落在**进程内队列**
+//! 里由 UI 抽；失败原因同理（`AgentTransport::submit` 只回一个 `String`，而 UI 要按**原因码**
+//! 选 i18n 文案，不能去匹配错误串）。两个 `Arc<Mutex<..>>` 就这两件东西，和
+//! [`super::transport::RigTransport`] 共享，**transport 只写、UI 只读**。
+//!
+//! ## 未读口径为什么依赖两行同步
+//!
+//! presenter 判「栏在用户眼前」用的是它自己那份 `router` + `prefs.ai_collapsed`
+//! （`AppState::agent_rail_visible`），而路由与档位的真源在 `App`。所以每次 `refresh_view`
+//! 都把这两个事实按**窄入口**（`navigate` / `prefs_mut`）写回去——这是 presenter 目前对
+//! 「栏可见吗」唯一开放的接口。更好的形状是给 presenter 加一个 `agent_set_visible(bool)`
+//! 窄入口（已按 finding 报给塔台），那样这两行同步就可以删。
+
+use unlucky_i18n::Key;
+use unlucky_presenter::agent::{AgentRail, Presenter};
+use unlucky_presenter::dto::AppEvent;
+use unlucky_presenter::router::{AiPanelMode, Route};
+
+use super::transport::{EventQueue, FailureSlot, RigTransport, Script};
+
+/// 一个**具名**的失败原因（UI 据码选 catalog 文案；后端诊断原文只进日志）。
+///
+/// 为什么不是 `String`：M114 复审 r1 的 p1 就是这么来的——后端诊断是中文人话，直接上屏会让
+/// 英文界面里出现整句中文。原因码是 ascii 且不随语言变（日志 / 测试 / 用户报障都靠它对齐）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum AgentFailure {
+    /// 端点不可达（连接失败 / 超时）。
+    Unreachable,
+    /// 这条请求的路由还没接线（真实 LLM 后端未装配）。
+    NotImplemented,
+}
+
+impl AgentFailure {
+    /// 稳定 ascii 码（日志与测试断言用）。
+    pub(crate) const fn code(self) -> &'static str {
+        match self {
+            Self::Unreachable => "unreachable",
+            Self::NotImplemented => "not_implemented",
+        }
+    }
+
+    /// 横幅正文的 catalog 键。
+    pub(crate) const fn body_key(self) -> Key {
+        match self {
+            Self::Unreachable => Key::AgentErrorUnavailable,
+            Self::NotImplemented => Key::AgentErrorNotImplemented,
+        }
+    }
+}
+
+/// 一次提交的结局。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum SubmitOutcome {
+    /// 交给后端了（事件稍后从队列里回来）。
+    Sent,
+    /// 后端明确失败：UI 要显示具名错误。
+    Failed(AgentFailure),
+    /// presenter 拒收（空文本 / 上一轮还在跑 / 有写操作待确认）。
+    ///
+    /// 不进横幅：这三种情形正常情况下**够不着**（发送键在空白/忙碌时是禁用的，确认框没关时
+    /// 输入区也不该能发），走到这里说明某处闸门漏了 ⇒ 留一行日志，别拿一句话糊在界面上。
+    Rejected,
+}
+
+/// AI 助手栏的 presenter 句柄。
+pub(crate) struct AgentHost {
+    presenter: Presenter,
+    /// 这套后端是不是**模拟**的（M119 r1 / 复审 P2-1）。
+    ///
+    /// 今天恒 `true`：transport 只有 `RigTransport` 一种（脚本化，没有真模型）。接真 `AgentTransport`
+    /// 的那一天，这里传 `false`——**四处「模拟」措辞会一起消失**（标题胶囊 / 副标题 / 输入框占位符 /
+    /// 空态正文，全部出自 `pages::agent::Disclaimer::of(catalog, simulated)`）。
+    /// 标记不是硬编码在视图里的，它是这个事实字段的渲染；「四处一起变」由
+    /// `pages/agent/tests/disclaimer.rs` 钉住（r1 时只有一处认它，那句声明是空的）。
+    simulated: bool,
+    queue: EventQueue,
+    failure: FailureSlot,
+    /// 最近一次提交失败（具名；下一次成功提交或重试用尽时清掉）。
+    last_failure: Option<AgentFailure>,
+    /// 上一次写回 presenter 的「栏可见性」(独立页?, 折叠?)，相同就不重复写（`navigate` 有副作用）。
+    synced: Option<(bool, bool)>,
+}
+
+impl AgentHost {
+    /// 指定脚本（单测与取证开关都走它）。
+    pub(crate) fn with_script(script: Script) -> Self {
+        let transport = RigTransport::new(script);
+        let queue = transport.queue();
+        let failure = transport.failure();
+        Self {
+            presenter: Presenter::new(Box::new(transport)),
+            // 脚本化 rig ⇒ 一定是模拟的（见字段文档）
+            simulated: true,
+            queue,
+            failure,
+            last_failure: None,
+            synced: None,
+        }
+    }
+
+    /// 按 `ULL_AGENT_SCRIPT` 选脚本（没设 = `qa`）。
+    pub(crate) fn from_env() -> Self {
+        Self::with_script(Script::from_env())
+    }
+
+    /// 当前会话视图模型（**唯一**读入口；两形态共享同一份）。
+    pub(crate) fn rail(&self) -> &AgentRail {
+        self.presenter.agent_rail()
+    }
+
+    /// 这套后端是不是模拟的（界面据此常驻「模拟」标记；见字段文档）。
+    pub(crate) fn is_simulated(&self) -> bool {
+        self.simulated
+    }
+
+    /// 最近一次提交失败的具名原因。
+    pub(crate) fn last_failure(&self) -> Option<AgentFailure> {
+        self.last_failure
+    }
+
+    /// 抽干事件队列（UI 在心跳里调；返回的事件**只**经 `Message::Agent(Events)` 回流）。
+    pub(crate) fn drain(&mut self) -> Vec<AppEvent> {
+        let mut drained = Vec::new();
+        if let Ok(mut queue) = self.queue.lock() {
+            drained.extend(queue.drain(..));
+        }
+        drained
+    }
+
+    /// 喂一条事件（纯转发给 `AppState::apply`）。
+    pub(crate) fn apply(&mut self, event: AppEvent) {
+        self.presenter.apply(event);
+    }
+
+    /// 提交一句话。
+    pub(crate) fn submit(&mut self, text: String) -> SubmitOutcome {
+        match self.presenter.agent_submit(text) {
+            Ok(()) => {
+                self.last_failure = None;
+                SubmitOutcome::Sent
+            }
+            Err(detail) => {
+                // presenter 已经把错误串脱敏（`agent/tests_red_line.rs` 钉住），这里只进日志。
+                eprintln!("[agent] submit 失败：{detail}");
+                match self.failure.lock().ok().and_then(|mut slot| slot.take()) {
+                    Some(failure) => {
+                        self.last_failure = Some(failure);
+                        SubmitOutcome::Failed(failure)
+                    }
+                    None => SubmitOutcome::Rejected,
+                }
+            }
+        }
+    }
+
+    /// 未读清零（用户打开栏 / 停在独立页）。
+    pub(crate) fn mark_read(&mut self) {
+        self.presenter.agent_mark_read();
+    }
+
+    /// 对当前待确认的写操作做决定。
+    pub(crate) fn confirm(&mut self, accept: bool) {
+        self.presenter.agent_confirm(accept);
+    }
+
+    /// 输入框草稿（用户打字时同步进来，切形态不丢）。
+    pub(crate) fn set_draft(&mut self, text: String) {
+        self.presenter.agent_set_draft(text);
+    }
+
+    /// 把「用户此刻看得见这段会话吗」写回 presenter（未读口径的输入）。
+    ///
+    /// 只在两个事实变化时写：`Presenter::navigate(Route::Agent)` 会顺手展开栏偏好并清未读，
+    /// 每次 `refresh_view` 都写一遍会把用户攒的未读吃掉。
+    pub(crate) fn sync_visibility(&mut self, on_agent_page: bool, collapsed: bool) {
+        if self.synced == Some((on_agent_page, collapsed)) {
+            return;
+        }
+        self.synced = Some((on_agent_page, collapsed));
+        match (on_agent_page, self.presenter.state().ai_mode()) {
+            (true, AiPanelMode::Docked) => self.presenter.navigate(Route::Agent),
+            (false, AiPanelMode::Page) => self.presenter.navigate(Route::Instances),
+            _ => {}
+        }
+        // 顺序不能反：`navigate(Route::Agent)` 内部会把 `ai_collapsed` 置 false。
+        self.presenter.prefs_mut().ai_collapsed = collapsed;
+    }
+
+    /// 本进程内的裁决记录条数（取证/测试用；权威审计在 agent 侧）。
+    #[cfg(test)]
+    pub(crate) fn audit_len(&self) -> usize {
+        self.presenter.audit().len()
+    }
+}
+
+impl std::fmt::Debug for AgentHost {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("AgentHost")
+            .field("rail", self.rail())
+            .field("last_failure", &self.last_failure)
+            .finish_non_exhaustive()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn each_failure_code_is_stable_ascii_and_has_its_own_body_key() {
+        assert_eq!(AgentFailure::Unreachable.code(), "unreachable");
+        assert_eq!(AgentFailure::NotImplemented.code(), "not_implemented");
+        assert_ne!(
+            AgentFailure::Unreachable.body_key(),
+            AgentFailure::NotImplemented.body_key(),
+            "两种失败要两句话，不能都糊成一句"
+        );
+    }
+
+    #[test]
+    fn a_submit_only_reaches_the_backend_once_per_turn_while_busy() {
+        let mut host = AgentHost::with_script(Script::Streaming);
+        assert_eq!(host.rail().messages.len(), 0);
+        assert_eq!(host.submit("hello".to_string()), SubmitOutcome::Sent);
+        // 队列里的这一批要经 `apply` 才进 rail（app 层由 `Message::Agent(Events)` 做同一件事）
+        for event in host.drain() {
+            host.apply(event);
+        }
+        assert!(host.rail().busy, "流式没收敛前输入要禁用");
+        // 第二轮被 presenter 拒收（不是服务器错误，所以不进横幅）
+        assert_eq!(host.submit("again".to_string()), SubmitOutcome::Rejected);
+        assert_eq!(host.last_failure(), None);
+    }
+
+    #[test]
+    fn an_unreachable_endpoint_is_named_not_stringified() {
+        let mut host = AgentHost::with_script(Script::Unreachable);
+        assert_eq!(
+            host.submit("hello".to_string()),
+            SubmitOutcome::Failed(AgentFailure::Unreachable)
+        );
+        assert_eq!(host.last_failure(), Some(AgentFailure::Unreachable));
+        assert!(host.drain().is_empty());
+    }
+
+    #[test]
+    fn visibility_is_written_back_once_per_change() {
+        let mut host = AgentHost::with_script(Script::Qa);
+        host.sync_visibility(false, true);
+        host.sync_visibility(false, true);
+        assert!(host.presenter.state().prefs.ai_collapsed);
+        host.sync_visibility(true, false);
+        assert_eq!(host.presenter.state().ai_mode(), AiPanelMode::Page);
+        assert!(!host.presenter.state().prefs.ai_collapsed);
+        host.sync_visibility(false, false);
+        assert_eq!(host.presenter.state().ai_mode(), AiPanelMode::Docked);
+    }
+}
diff --git a/crates/app-iced/src/presenter/mod.rs b/crates/app-iced/src/presenter/mod.rs
new file mode 100644
index 0000000..7bb925b
--- /dev/null
+++ b/crates/app-iced/src/presenter/mod.rs
@@ -0,0 +1,41 @@
+//! iced 侧的 presenter 接线层（M119）。
+//!
+//! ## 为什么单独一个目录
+//!
+//! presenter 已经把「AI 会话怎么攒、未读怎么算、YOLO 怎么裁决」做完了（M103），壳层只该
+//! **读视图模型 + 把点击翻成四个方法**。这份「只做翻译」的胶水需要地方放，而且要能和 presenter
+//! 自己的契约分开审：所以是独立目录，不塞进 `app/` 的 update 分支里。
+//!
+//! | 文件 | 职责 | 不负责 |
+//! |---|---|---|
+//! | [`agent`] | [`AgentHost`]：presenter 句柄（四契约）+ 事件队列 + 具名错误 | 画、算脱敏 |
+//! | [`transport`] | [`AgentTransport`](unlucky_presenter::agent::AgentTransport) 的 iced 侧实现（脚本化 rig + 三种失败注入） | 真实模型调用 |
+//! | `rig`（仅测试） | 账户轨的 `Backend` 实现：`AppCommand` → host 形状的 `CoreEvent` | 真 AccountStore 落盘 |
+//!
+//! ## 逻辑路径与物理路径
+//!
+//! 物理目录是 `crates/app-iced/src/presenter/`，逻辑名字是 `crate::app::state::presenter`——由
+//! `app/state.rs` 用 `#[path = "../presenter/mod.rs"]` 挂载。理由与 `shell::agent`
+//! （`crates/app-iced/src/pages/agent/` → `crate::shell::agent`）完全相同：本 mission 的 scope
+//! 不含 `lib.rs` 与 `app/mod.rs`，用 `#[path]` 挂载既不碰共用声明文件，也不产生第二份实现。
+//!
+//! ## 线程/通道边界（本轮只验同步形状，异步未验）
+//!
+//! ```text
+//! on_agent(Submit) ──► AgentHost::submit ──► Presenter::agent_submit ──► Transport::submit
+//!                                                                          │ 事件进队列
+//!   右栏（读 rag.agent_rail()）◄── AgentHost::apply ◄── Message::Agent(Events) ◄── App::drain_agent
+//! ```
+//!
+//! 队列是 `Arc<Mutex<VecDeque<..>>>`：**transport 侧只入队、UI 侧只出队**，中间不共享状态。
+//! 真实异步后端落地时换掉的是「谁往队列里 push」，这条形状不动。本轮 transport 是同步实现
+//! （`submit` 当场把整批事件入队），所以「跨线程时序 / 乱序 / 并发提交」**没有验过**。
+
+pub(crate) mod agent;
+// 账户轨的 UI 侧 rig（`AppCommand` → host 形状的 `CoreEvent`）。只在测试里存在：截图通道的
+// 账户矩阵仍走 presenter 自带的 `MockBackend`（`ULL_ACCOUNT_STATE`）。
+#[cfg(test)]
+pub(crate) mod rig;
+pub(crate) mod transport;
+
+pub(crate) use agent::{AgentFailure, AgentHost};
diff --git a/crates/app-iced/src/presenter/rig.rs b/crates/app-iced/src/presenter/rig.rs
new file mode 100644
index 0000000..52d64ae
--- /dev/null
+++ b/crates/app-iced/src/presenter/rig.rs
@@ -0,0 +1,211 @@
+//! 账户轨的 UI 侧 rig（**只在测试里存在**）：把 `AppCommand` 翻成 host 形状的 `CoreEvent`。
+//!
+//! ## 它替的是谁、替到什么程度
+//!
+//! 真 host 的账户分支在 `presenter/host/dispatch.rs`：`AddOfflineAccount` → `accounts::add_offline`
+//! （`core::auth::AccountStore` 落盘）→ `AccountsChanged`；`SwitchAccount` → 只改内存里的
+//! `active_account` → `AccountsChanged`；失败一律走 `AccountNoticeChanged(结构化码)`。
+//!
+//! 这里**照同一条形状**回事件，但不碰磁盘、不起线程：
+//!
+//! | 真 host | 本 rig | 差在哪 |
+//! |---|---|---|
+//! | `AccountStore` 落盘 + 读回 | 内存 `Vec<AccountView>` | 落盘/读回由 presenter 自己的
+//!   `host::accounts::offline_add_list_remove_round_trips` 覆盖，本轮**没有**跨 crate 复跑 |
+//! | `notice_failure` 带原因码 | 同名三个码（`OfflineNameInvalid` / `NotFound` / `Added`…） | 一致 |
+//! | 设备码：起后台线程等用户 | 直接给 Waiting 态 | 「进行中可见 + 可取消」验得到，**真实网络不验** |
+//!
+//! 为什么不能直接用 `CoreHost`：`host::accounts` 是**私有**模块（outside 本 mission 的 scope），
+//! 而 `CoreHost::new` 会 `refresh_all`（版本清单网络线程 + Java 探测）。测试要的是确定性。
+
+use std::collections::VecDeque;
+
+use unlucky_presenter::dto::{
+    valid_offline_name, AccountKind, AccountNotice, AccountNoticeCode, AccountView, AppCommand,
+    AppEvent, Backend, CoreEvent, DeviceLoginView,
+};
+
+/// 账户轨的假后端（形状与真 host 一致，数据在内存里）。
+#[derive(Debug)]
+pub(crate) struct AccountRig {
+    events: VecDeque<AppEvent>,
+    accounts: Vec<AccountView>,
+    next_id: u32,
+    active: Option<String>,
+}
+
+impl Default for AccountRig {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl AccountRig {
+    /// 空账户表。
+    pub(crate) fn new() -> Self {
+        Self {
+            events: VecDeque::new(),
+            accounts: Vec::new(),
+            next_id: 0,
+            active: None,
+        }
+    }
+
+    fn emit(&mut self, event: CoreEvent) {
+        self.events.push_back(AppEvent::Core(event));
+    }
+
+    /// 当前列表（`active` 标记按内存里的当前账户算）。
+    fn snapshot(&mut self) {
+        self.emit(CoreEvent::AccountsChanged(self.accounts.clone()));
+    }
+
+    fn notice(&mut self, code: AccountNoticeCode, subject: &str, detail: &str) {
+        self.emit(CoreEvent::AccountNoticeChanged(Some(AccountNotice::new(
+            code, subject, detail,
+        ))));
+    }
+
+    fn add_offline(&mut self, name: &str) {
+        let name = name.trim();
+        if !valid_offline_name(name) {
+            // 与 host 同码：名字不合法是**结构化**失败，不是静默
+            self.notice(
+                AccountNoticeCode::OfflineNameInvalid,
+                name,
+                "长度/字符集不符",
+            );
+            return;
+        }
+        if self.accounts.iter().any(|account| account.name == name) {
+            self.notice(AccountNoticeCode::AccountExists, name, "同名账户已存在");
+            return;
+        }
+        self.next_id += 1;
+        let id = format!("account:rig-{}", self.next_id);
+        self.accounts.push(AccountView {
+            id,
+            name: name.to_string(),
+            kind: AccountKind::Offline,
+            profile_id: format!("{:08x}", self.next_id),
+            login_name: String::new(),
+            created: "2026-11-05 00:00".to_string(),
+            active: false,
+            server_url: String::new(),
+            skin: None,
+        });
+        self.notice(AccountNoticeCode::Added, name, "");
+        self.snapshot();
+    }
+
+    fn remove(&mut self, key: &str) {
+        let Some(index) = self
+            .accounts
+            .iter()
+            .position(|account| account.id == key || account.name == key)
+        else {
+            self.notice(AccountNoticeCode::NotFound, key, "找不到这个账户");
+            return;
+        };
+        let removed = self.accounts.remove(index);
+        if self.active.as_deref() == Some(removed.id.as_str()) {
+            self.active = None;
+        }
+        self.notice(AccountNoticeCode::Removed, &removed.name, "");
+        self.snapshot();
+    }
+
+    fn switch(&mut self, id: &str) {
+        if !self.accounts.iter().any(|account| account.id == id) {
+            self.notice(AccountNoticeCode::NotFound, id, "找不到这个账户");
+            return;
+        }
+        let name = self
+            .accounts
+            .iter()
+            .find(|account| account.id == id)
+            .map(|account| account.name.clone())
+            .unwrap_or_default();
+        self.active = Some(id.to_string());
+        for account in &mut self.accounts {
+            account.active = account.id == id;
+        }
+        self.notice(AccountNoticeCode::Switched, &name, "");
+        self.snapshot();
+    }
+}
+
+impl Backend for AccountRig {
+    fn drain_events(&mut self) -> Vec<AppEvent> {
+        self.events.drain(..).collect()
+    }
+
+    fn dispatch(&mut self, command: AppCommand) {
+        match command {
+            AppCommand::RefreshAll => self.snapshot(),
+            AppCommand::AddOfflineAccount(name) => self.add_offline(&name),
+            AppCommand::RemoveAccount(key) => self.remove(&key),
+            AppCommand::SwitchAccount(id) => self.switch(&id),
+            AppCommand::DismissAccountNotice => self.emit(CoreEvent::AccountNoticeChanged(None)),
+            // 两条登录流：都给「等用户」态（真 host 在这里起后台线程 + 浏览器）
+            AppCommand::StartDeviceLogin | AppCommand::StartBrowserLogin => {
+                self.emit(CoreEvent::DeviceLoginChanged(DeviceLoginView::waiting(
+                    "ABCD-EFGH",
+                    "https://www.microsoft.com/link",
+                    900,
+                    "",
+                )));
+            }
+            // 取消：两条轨都收回 Idle（真 host 的 `CancelDeviceLogin` 就是这么做的）
+            AppCommand::CancelDeviceLogin => {
+                self.emit(CoreEvent::DeviceLoginChanged(DeviceLoginView::new()));
+            }
+            _ => {}
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn the_rig_answers_add_switch_remove_with_host_shaped_events() {
+        let mut rig = AccountRig::new();
+        rig.dispatch(AppCommand::AddOfflineAccount("Steve".to_string()));
+        let events = rig.drain_events();
+        assert!(events.iter().any(|event| matches!(
+            event,
+            AppEvent::Core(CoreEvent::AccountsChanged(rows)) if rows.len() == 1
+        )));
+
+        let id = match &events[1] {
+            AppEvent::Core(CoreEvent::AccountsChanged(rows)) => rows[0].id.clone(),
+            _ => unreachable!(),
+        };
+        rig.dispatch(AppCommand::SwitchAccount(id.clone()));
+        assert!(matches!(
+            rig.drain_events().first(),
+            Some(AppEvent::Core(CoreEvent::AccountNoticeChanged(Some(notice))))
+                if notice.code == AccountNoticeCode::Switched
+        ));
+
+        rig.dispatch(AppCommand::RemoveAccount(id));
+        let events = rig.drain_events();
+        assert!(events.iter().any(|event| matches!(
+            event,
+            AppEvent::Core(CoreEvent::AccountsChanged(rows)) if rows.is_empty()
+        )));
+    }
+
+    #[test]
+    fn an_invalid_offline_name_is_a_structured_failure_not_silence() {
+        let mut rig = AccountRig::new();
+        rig.dispatch(AppCommand::AddOfflineAccount("ab".to_string()));
+        assert!(matches!(
+            rig.drain_events().first(),
+            Some(AppEvent::Core(CoreEvent::AccountNoticeChanged(Some(notice))))
+                if notice.code == AccountNoticeCode::OfflineNameInvalid
+        ));
+    }
+}
diff --git a/crates/app-iced/src/presenter/transport.rs b/crates/app-iced/src/presenter/transport.rs
new file mode 100644
index 0000000..947d3d9
--- /dev/null
+++ b/crates/app-iced/src/presenter/transport.rs
@@ -0,0 +1,339 @@
+//! [`AgentTransport`] 的 iced 侧实现：脚本化 rig + 三类失败注入（M119）。
+//!
+//! ## 它是什么、不是什么
+//!
+//! 它是 M103 契约 [`AgentTransport`] 的一个**实现**，不是契约的改写：`submit` / `confirm` 的
+//! 签名一行没动。真实的 rig 后端（`crates/agent` + rig）还没装配进 host（M103 报告 §4 登记过），
+//! 所以本轮用它跑端到端。
+//!
+//! **事件走队列，不当场返回**：`submit` 把整批事件 push 进 [`EventQueue`] 后返回 `Ok(vec![])`，
+//! UI 在心跳里抽。这条形状才是异步后端落地时**不会变**的那部分——换掉的只有「谁往队列里 push」
+//! （真实后端在后台线程里逐帧推流）。抓得住：事件经 Message 通道回流的整条链路；
+//! 抓不住：跨线程时序、乱序、并发提交（本轮 transport 是同步的，见报告「没验的部分」）。
+//!
+//! ## 失败注入（任务「失败态可见」的那两条 AI 侧）
+//!
+//! | `ULL_AGENT_SCRIPT` | `submit` 行为 |
+//! |---|---|
+//! | `qa`（默认） | 一轮正常问答：用户气泡 + 流式助手消息（三条增量）+ 收敛 |
+//! | `streaming` | 同上但**永不收敛**（`busy` 一直亮着：中断键与禁用态的可视图） |
+//! | `fails` | 流到一半断流：已到的增量保留，整轮以 `Failed` 收尾 |
+//! | `write` | 需确认的写操作（High 级 `ConfirmRequested`） |
+//! | `unreachable` | **端点不可达**：`Err`，一个事件也不产生 |
+//! | `unimplemented` | **未实现路由**：`Err`，同上 |
+//!
+//! 两种 `Err` 都先把**具名原因**写进 [`FailureSlot`] 再返回错误串——UI 据原因码选 catalog 文案，
+//! 错误串本身（后端诊断）只进日志，不上屏（M114 立的口径）。
+
+use std::collections::VecDeque;
+use std::sync::{Arc, Mutex};
+
+use unlucky_presenter::agent::{AgentRail, AgentTransport};
+use unlucky_presenter::dto::{
+    AgentEvent, AppEvent, ChatMessage, ChatRole, ConfirmRequest, Sensitivity,
+};
+
+use super::AgentFailure;
+
+/// 事件队列（transport 侧 push、UI 侧 drain）。
+pub(crate) type EventQueue = Arc<Mutex<VecDeque<AppEvent>>>;
+
+/// 失败原因槽（transport 侧写、UI 侧读后清）。
+pub(crate) type FailureSlot = Arc<Mutex<Option<AgentFailure>>>;
+
+/// 脚本（一轮输入会产生哪种剧情）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum Script {
+    /// 正常问答。
+    Qa,
+    /// 流式永不收敛。
+    Streaming,
+    /// 流式中途断流。
+    FailsMidStream,
+    /// 需确认的写操作。
+    WriteOp,
+    /// 端点不可达（`Err`）。
+    Unreachable,
+    /// 未实现路由（`Err`）。
+    NotImplemented,
+}
+
+/// 脚本环境变量（取证开关，与 `ULL_AGENT_RAIL` / `ULL_APPEARANCE_*` 同一口径）。
+pub(crate) const SCRIPT_ENV: &str = "ULL_AGENT_SCRIPT";
+
+impl Script {
+    /// 全部脚本（`from_name` 的遍历表）。
+    pub(crate) const ALL: [Script; 6] = [
+        Script::Qa,
+        Script::Streaming,
+        Script::FailsMidStream,
+        Script::WriteOp,
+        Script::Unreachable,
+        Script::NotImplemented,
+    ];
+
+    /// 稳定名字（`ULL_AGENT_SCRIPT` 的取值 / 日志）。
+    pub(crate) const fn name(self) -> &'static str {
+        match self {
+            Script::Qa => "qa",
+            Script::Streaming => "streaming",
+            Script::FailsMidStream => "fails",
+            Script::WriteOp => "write",
+            Script::Unreachable => "unreachable",
+            Script::NotImplemented => "unimplemented",
+        }
+    }
+
+    /// 反向解析（取证开关用；未知值忽略）。
+    pub(crate) fn from_name(name: &str) -> Option<Self> {
+        Self::ALL.into_iter().find(|script| script.name() == name)
+    }
+
+    /// 读 `ULL_AGENT_SCRIPT`；没设 / 解析不出来 = [`Script::Qa`]。
+    pub(crate) fn from_env() -> Self {
+        match std::env::var(SCRIPT_ENV) {
+            Ok(raw) => match Self::from_name(raw.trim()) {
+                Some(script) => script,
+                None => {
+                    eprintln!(
+                        "[agent] {SCRIPT_ENV}={raw:?} 不是脚本之一，按 qa 处理（可选：{}）",
+                        Self::ALL.map(Self::name).join("/")
+                    );
+                    Script::Qa
+                }
+            },
+            Err(_) => Script::Qa,
+        }
+    }
+}
+
+/// 脚本化 transport：事件入队、失败入槽。
+pub(crate) struct RigTransport {
+    script: Script,
+    /// 已发起过几轮（用来算消息下标 / 确认请求 id）。
+    turns: usize,
+    /// 当前待确认的写操作。
+    pending: Option<ConfirmRequest>,
+    queue: EventQueue,
+    failure: FailureSlot,
+}
+
+impl RigTransport {
+    /// 新 transport + 它与 UI 共享的两个句柄。
+    pub(crate) fn new(script: Script) -> Self {
+        Self {
+            script,
+            turns: 0,
+            pending: None,
+            queue: EventQueue::default(),
+            failure: FailureSlot::default(),
+        }
+    }
+
+    /// 与 UI 共享的事件队列（克隆一个给 [`super::AgentHost`]）。
+    pub(crate) fn queue(&self) -> EventQueue {
+        Arc::clone(&self.queue)
+    }
+
+    /// 与 UI 共享的失败原因槽。
+    pub(crate) fn failure(&self) -> FailureSlot {
+        Arc::clone(&self.failure)
+    }
+
+    /// 入队一批事件（transport 唯一的输出方向）。
+    fn emit(&self, events: Vec<AppEvent>) {
+        if events.is_empty() {
+            return;
+        }
+        if let Ok(mut queue) = self.queue.lock() {
+            queue.extend(events);
+        }
+    }
+
+    /// 注入一次失败：原因入槽（UI 据它选 catalog 文案）、错误串回给 presenter（只进日志）。
+    fn fail(&self, failure: AgentFailure, detail: &str) -> Result<Vec<AppEvent>, String> {
+        if let Ok(mut slot) = self.failure.lock() {
+            *slot = Some(failure);
+        }
+        Err(format!("{}：{detail}", failure.code()))
+    }
+}
+
+impl AgentTransport for RigTransport {
+    fn submit(&mut self, text: &str, history: &AgentRail) -> Result<Vec<AppEvent>, String> {
+        match self.script {
+            Script::Unreachable => {
+                return self.fail(
+                    AgentFailure::Unreachable,
+                    "assistant endpoint http://127.0.0.1:8080 连不上（connection refused）",
+                );
+            }
+            Script::NotImplemented => {
+                return self.fail(
+                    AgentFailure::NotImplemented,
+                    "真实 LLM 路由还没装配进 host（M103 §4 的欠账）",
+                );
+            }
+            _ => {}
+        }
+
+        self.turns += 1;
+        // 后端自己算下标：用户气泡先到，助手流式占位紧随其后。
+        let assistant = history.messages.len() + 1;
+        let mut events = vec![
+            agent_event(AgentEvent::MessageAppended(ChatMessage::user(text))),
+            agent_event(AgentEvent::MessageAppended(ChatMessage::assistant_stream())),
+        ];
+        match self.script {
+            Script::Qa | Script::Streaming => {
+                for delta in ["先确认版本：", "装完再加 Fabric。"] {
+                    events.push(agent_event(AgentEvent::MessageDelta {
+                        index: assistant,
+                        delta: delta.to_string(),
+                    }));
+                }
+                if self.script == Script::Qa {
+                    events.push(agent_event(AgentEvent::MessageFinished {
+                        index: assistant,
+                    }));
+                }
+            }
+            Script::FailsMidStream => {
+                events.push(agent_event(AgentEvent::MessageDelta {
+                    index: assistant,
+                    delta: "我先读一下最近的日志".to_string(),
+                }));
+                events.push(agent_event(AgentEvent::Failed {
+                    message: "provider 断流：read timeout".to_string(),
+                }));
+            }
+            Script::WriteOp => {
+                events.push(agent_event(AgentEvent::MessageDelta {
+                    index: assistant,
+                    delta: "我准备把下载并发从 64 改成 16，改之前先问一句。".to_string(),
+                }));
+                events.push(agent_event(AgentEvent::MessageFinished {
+                    index: assistant,
+                }));
+                events.push(agent_event(AgentEvent::ToolCallStarted {
+                    name: "set_config".to_string(),
+                    summary: "修改 download.concurrency".to_string(),
+                }));
+                let request = ConfirmRequest {
+                    id: format!("req-{}", self.turns),
+                    tool: "set_config".to_string(),
+                    summary: "把下载并发 64 → 16".to_string(),
+                    // 不引 serde_json（app-iced 没有这个依赖）：`Value::default()` = Null，
+                    // 确认框只画 `summary`，`details` 的结构化 diff 留给后续 mission。
+                    details: Default::default(),
+                    sensitivity: Sensitivity::High,
+                };
+                self.pending = Some(request.clone());
+                events.push(agent_event(AgentEvent::ConfirmRequested { request }));
+            }
+            // 三支失败脚本在上面的 `match` 里已经 `return`，这里只为穷尽
+            Script::Unreachable | Script::NotImplemented => {}
+        }
+        self.emit(events);
+        // 契约允许「事件分片由 presenter 顺序 apply」，也允许走事件通道——本实现走通道（见模块文档）。
+        Ok(Vec::new())
+    }
+
+    fn confirm(&mut self, request_id: &str, accept: bool) -> Vec<AppEvent> {
+        self.pending = None;
+        let (ok, summary, reply) = if accept {
+            (true, "已写入 download.concurrency = 16", "改好了。")
+        } else {
+            (false, "用户拒绝，未写入", "那就不改了。")
+        };
+        let events = vec![
+            agent_event(AgentEvent::ToolCallFinished {
+                name: "set_config".to_string(),
+                ok,
+                summary: summary.to_string(),
+            }),
+            agent_event(AgentEvent::ConfirmResolved {
+                id: request_id.to_string(),
+            }),
+            agent_event(AgentEvent::MessageAppended(ChatMessage {
+                role: ChatRole::Assistant,
+                text: reply.to_string(),
+                tool: None,
+                streaming: false,
+            })),
+        ];
+        self.emit(events.clone());
+        // 与 `submit` 同一条口径：事件走队列，这里返回空（避免同一批事件被 apply 两遍）。
+        Vec::new()
+    }
+}
+
+/// 包一层 [`AppEvent::Agent`]（事件队列只认顶层事件）。
+fn agent_event(event: AgentEvent) -> AppEvent {
+    AppEvent::Agent(event)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn every_script_name_round_trips_and_the_env_default_is_qa() {
+        for script in Script::ALL {
+            assert_eq!(Script::from_name(script.name()), Some(script));
+        }
+        assert_eq!(Script::from_name("nope"), None);
+        // 环境变量在这条测试里不可靠地存在（并行测试共享进程），只验默认分支的返回值
+        assert_eq!(Script::from_name("qa"), Some(Script::Qa));
+    }
+
+    #[test]
+    fn a_normal_turn_queues_the_whole_batch_and_returns_no_inline_events() {
+        let mut transport = RigTransport::new(Script::Qa);
+        let queue = transport.queue();
+        let inline = transport
+            .submit("hello", &AgentRail::new())
+            .expect("qa 不会失败");
+        assert!(inline.is_empty(), "本实现走队列，不走进内联分片");
+        assert_eq!(
+            queue.lock().expect("queue").len(),
+            5,
+            "user + 流式占位 + 两片增量 + 收敛"
+        );
+    }
+
+    #[test]
+    fn the_two_failing_scripts_return_a_named_reason_and_queue_nothing() {
+        for (script, expected) in [
+            (Script::Unreachable, AgentFailure::Unreachable),
+            (Script::NotImplemented, AgentFailure::NotImplemented),
+        ] {
+            let mut transport = RigTransport::new(script);
+            let queue = transport.queue();
+            let failure = transport.failure();
+            let error = transport
+                .submit("hello", &AgentRail::new())
+                .expect_err("这两支必失败");
+            assert!(error.contains(expected.code()), "错误串要带原因码：{error}");
+            assert_eq!(*failure.lock().expect("slot"), Some(expected));
+            assert!(queue.lock().expect("queue").is_empty(), "失败不产生事件");
+        }
+    }
+
+    #[test]
+    fn confirm_queues_the_tool_result_and_the_reply() {
+        let mut transport = RigTransport::new(Script::WriteOp);
+        let queue = transport.queue();
+        transport
+            .submit("改并发", &AgentRail::new())
+            .expect("写操作");
+        queue.lock().expect("queue").clear();
+        let inline = transport.confirm("req-1", true);
+        assert!(inline.is_empty());
+        assert_eq!(
+            queue.lock().expect("queue").len(),
+            3,
+            "工具收尾 + 确认收敛 + 回复"
+        );
+    }
+}
diff --git a/crates/app-iced/src/probe.rs b/crates/app-iced/src/probe.rs
new file mode 100644
index 0000000..3b53de0
--- /dev/null
+++ b/crates/app-iced/src/probe.rs
@@ -0,0 +1,226 @@
+//! 渲染后端探测 + 自动降级（D27）。
+//!
+//! ## 为什么需要探测
+//!
+//! iced 0.14 的 `Renderer` 本身就是「wgpu → tiny-skia」的运行时回退枚举（M60 Q1）：
+//! **不设** `ICED_BACKEND` 时，拿不到 GPU 适配器会自动降级到 CPU，零代码。
+//! 需要自研的只有**判据**：
+//!
+//! - 本机会枚举出 `Microsoft Basic Render Driver [Cpu]`（= WARP 软光栅），
+//!   所以「有没有适配器」不能当「有没有 GPU」（M60 实测），必须看 `device_type`。
+//! - 没有硬件 GPU 时要**主动**把 CPU 放到候选首位，否则 wgpu 会先花时间尝试 WARP，
+//!   观感与行为都难料。
+//!
+//! ## M97 订正：判据在 [`crate::renderer::decide`]，日志不再说谎
+//!
+//! 本模块只负责**探测**（`Probe::run`）和**落地**（[`apply`]）；决策表、兜底、日志格式
+//! 全部搬到了 [`crate::renderer`] 的模块文档里（那张判据表就是验收标准）。
+//!
+//! 三条被删掉/改掉的东西，别再加回来：
+//!
+//! 1. **`ICED_BACKEND` 不再写候选列表**（`wgpu,tiny-skia` / `tiny-skia,wgpu` 这种）。
+//!    列表语义让 iced 自己回退，而它的回退是静默的：`iced_renderer-0.14.0/src/fallback.rs`
+//!    把 wgpu 的错误装进 `errors` 向量，tiny-skia 一成功就整体丢弃。现在只写**一项**，
+//!    起不来就必然是具名错误，由 `app::boot` 打印并重开降级。
+//! 2. **`auto` + 有硬件不再「不设变量」**。那等于把决策权交给一条我们看不见的路径。
+//! 3. **`renderer = auto (wgpu -> tiny-skia)` 这行删了**。它是按「变量未设」打出来的常量，
+//!    跟实际后端无关——M97 的 macOS 报告就是被它误导的。
+
+use crate::renderer::{self, Decision};
+use crate::Backend;
+
+/// 单个适配器的摘要（只留日志要用的字段）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AdapterSummary {
+    /// 适配器名（如 `AMD Radeon RX 6600 XT`）。
+    pub name: String,
+    /// `device_type` 的字符串形式（`DiscreteGpu` / `IntegratedGpu` / `Cpu` / …）。
+    pub device_type: &'static str,
+}
+
+/// 探测结论。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct Probe {
+    /// 枚举到的全部适配器（含 WARP 这类软光栅）。
+    pub adapters: Vec<AdapterSummary>,
+    /// 是否存在**真**硬件适配器（`device_type` 既不是 `Cpu` 也不是 `Other`）。
+    pub hardware: bool,
+}
+
+impl Probe {
+    /// 探测本机渲染能力（编入 `wgpu` 时真的枚举适配器）。
+    #[cfg(feature = "gpu")]
+    pub fn run() -> Self {
+        run_wgpu()
+    }
+
+    /// 探测本机渲染能力（`--no-default-features` 的纯 CPU 构建：没有 wgpu，直接判定无硬件）。
+    #[cfg(not(feature = "gpu"))]
+    pub fn run() -> Self {
+        Self::default()
+    }
+
+    /// 一行日志：适配器清单 + 判定。
+    pub fn describe(&self) -> String {
+        if self.adapters.is_empty() {
+            return format!("adapters=0 hardware={}", self.hardware);
+        }
+
+        let list = self
+            .adapters
+            .iter()
+            .map(|adapter| format!("{} [{}]", adapter.name, adapter.device_type))
+            .collect::<Vec<_>>()
+            .join(" | ");
+
+        format!(
+            "adapters={} [{list}] hardware={}",
+            self.adapters.len(),
+            self.hardware
+        )
+    }
+}
+
+/// 把 [`renderer::decide`] 的结论落到进程环境变量，并把**判据**打进日志（不带预检）。
+///
+/// 这个入口给「没有重试能力」的调用方（组件库 harness，`--screen=gallery`）用：它写完变量就
+/// 直接 `iced::application(..).run()`，拿不到 `app/boot.rs` 的「换进程降级」。
+pub fn apply(request: Backend, probe: &Probe) -> Decision {
+    apply_with_preflight(request, probe, None)
+}
+
+/// 同上，但接受 [`renderer::preflight`] 的结果（`ULL_PREFLIGHT=1` 时才有值）。
+///
+/// 注意这里是「判据」不是「结果」：日志里不会出现「实际用了哪个后端」这种我们观测不到的话。
+/// 实际后端的取证有两条，都在 [`crate::renderer`] 的判据表里：
+/// ① `[gpu] iced_wgpu: …Selected: AdapterInfo…`（iced 自己在创建设备时打的）；
+/// ② 起不来时的具名错误 + `app/boot.rs` 的重开降级。
+///
+/// 预检失败就把 wgpu 降下来（判据表第 7 行），免得为了拿一条错误去闪一次窗。
+pub fn apply_with_preflight(
+    request: Backend,
+    probe: &Probe,
+    preflight: Option<&Result<renderer::preflight::Verdict, renderer::preflight::Failure>>,
+) -> Decision {
+    let gpu_compiled = cfg!(feature = "gpu");
+    let mut decision = renderer::decide(request, probe, gpu_compiled);
+
+    if matches!(preflight, Some(Err(_))) {
+        decision = renderer::demote_after_preflight(decision);
+    }
+
+    // ICED_BACKEND 是进程级环境变量，必须在 `iced::application(..).run()` 之前写。
+    // 仓库是 edition 2021 → `set_var` 仍是安全 API（升 2024 后要改成子进程 exec 自身）。
+    std::env::set_var("ICED_BACKEND", decision.primary.env_value());
+
+    let note = if !gpu_compiled && request != Backend::Cpu {
+        "；本构建未编入 wgpu（--no-default-features），只能 CPU"
+    } else {
+        ""
+    };
+
+    eprintln!(
+        "[probe] {} :: request={} -> ICED_BACKEND={}{note}",
+        probe.describe(),
+        request.name(),
+        decision.primary.env_value()
+    );
+    eprintln!("[probe] {}", decision.describe());
+    if decision.primary == renderer::Kind::Wgpu {
+        eprintln!(
+            "[probe] 取证：出现 `[gpu] iced_wgpu: …Selected: AdapterInfo…` ⇒ GPU 真生效；\
+             出现 `[gpu] wgpu 初始化失败` ⇒ 已降级 CPU"
+        );
+    }
+
+    decision
+}
+
+#[cfg(feature = "gpu")]
+fn run_wgpu() -> Probe {
+    // `iced::wgpu` 就是 wgpu crate 本身（`pub use iced_renderer::wgpu::wgpu` 再导出），
+    // 所以不需要单独依赖 wgpu，版本也不会和 iced 打架。
+    use iced::wgpu::{Backends, Instance, InstanceDescriptor};
+
+    let instance = Instance::new(&InstanceDescriptor {
+        backends: Backends::all(),
+        ..Default::default()
+    });
+
+    let adapters = instance
+        .enumerate_adapters(Backends::all())
+        .into_iter()
+        .map(|adapter| {
+            let info = adapter.get_info();
+            AdapterSummary {
+                name: info.name,
+                device_type: renderer::preflight::device_type_name(info.device_type),
+            }
+        })
+        .collect::<Vec<_>>();
+
+    let hardware = adapters
+        .iter()
+        .any(|adapter| !matches!(adapter.device_type, "Cpu" | "Other"));
+
+    Probe { adapters, hardware }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn probe(types: &[&'static str]) -> Probe {
+        let adapters = types
+            .iter()
+            .map(|device_type| AdapterSummary {
+                name: "adapter".to_owned(),
+                device_type,
+            })
+            .collect::<Vec<_>>();
+        Probe {
+            adapters,
+            hardware: types
+                .iter()
+                .any(|device_type| !matches!(*device_type, "Cpu" | "Other")),
+        }
+    }
+
+    #[test]
+    fn warp_only_machine_counts_as_no_gpu() {
+        // 本机实测会枚举出 WARP：`Microsoft Basic Render Driver [Cpu]`
+        let warp = probe(&["Cpu"]);
+        assert!(!warp.hardware, "只有 WARP 不能当「有 GPU」");
+        assert_ne!(
+            renderer::decide(Backend::Auto, &warp, true).primary,
+            renderer::Kind::Wgpu
+        );
+    }
+
+    #[test]
+    fn describe_lists_every_adapter() {
+        let text = probe(&["DiscreteGpu", "Cpu"]).describe();
+        assert!(text.contains("DiscreteGpu"), "{text}");
+        assert!(text.contains("Cpu"), "{text}");
+        assert!(text.contains("hardware=true"), "{text}");
+    }
+
+    /// 判据矩阵本身在 [`crate::renderer::decide`] 的测试里逐行钉死（表驱动 + 兜底守门）。
+    /// 这里只守 `apply` 这一层的**落地**契约：写进环境变量的永远是**单项**。
+    ///
+    /// 抓得住：谁把候选列表（`wgpu,tiny-skia`）加回来——那会让 iced 的静默回退复活。
+    /// 抓不住：iced 运行期真的选了谁（那是判据表第 8 行的事）。
+    #[test]
+    fn apply_writes_exactly_one_backend() {
+        let gpu = probe(&["IntegratedGpu"]);
+        for request in [Backend::Auto, Backend::Gpu, Backend::Cpu] {
+            let decision = renderer::decide(request, &gpu, true);
+            let value = decision.primary.env_value();
+            assert!(
+                !value.contains(','),
+                "ICED_BACKEND 只许单项，收到 {value:?}"
+            );
+            assert!(matches!(value, "wgpu" | "tiny-skia"), "{value}");
+        }
+    }
+}
diff --git a/crates/app-iced/src/renderer/acceptance/locale.rs b/crates/app-iced/src/renderer/acceptance/locale.rs
new file mode 100644
index 0000000..64c73b5
--- /dev/null
+++ b/crates/app-iced/src/renderer/acceptance/locale.rs
@@ -0,0 +1,294 @@
+//! `[env]` 与 `[i18n]`：**本机是什么**（系统 / arch / 核数 / GPU / 时区）与**为什么是这个语言**。
+//!
+//! ## 语言链为什么在这里而不是 `platform/`
+//!
+//! `platform::locale::SystemLocale` 是 **Windows 注册表**那一路（`reg.exe`，零 FFI）。macOS 的
+//! 真值源是 `defaults read -g AppleLanguages`，而 M98 的 scope 没有 `platform/**`，所以
+//! [`AppleLanguages`] 先落在这里。**它该搬去 `platform/locale.rs`**——两处并存会漂（见交接报告）。
+
+use unlucky_i18n::lang::{self, Detection, LocaleSource};
+use unlucky_presenter::settings_bridge::SettingsBridge;
+
+use crate::Probe;
+
+// ---------------------------------------------------------------- [env]
+
+/// `[env]`：系统 / arch / 核数 / 语言 / 时区 / 缩放请求 / GPU。
+///
+/// `gpu` 与 `hardware` **来自真实适配器枚举**（[`Probe`]），不是请求值；枚举不到就写
+/// `<无适配器>` 并把 `hardware=false` 一起打出来——「没有适配器」与「没枚举」是两件事。
+///
+/// `display=` 恒为 `needs-window`：显示器尺寸只有拿到窗口句柄才问得到，而这一行在开窗之前就打了。
+/// 真值由验收脚本用 `system_profiler SPDisplaysDataType` 采进 `logs/00-env.txt`——**写个猜的值
+/// 比留白更坏**（那会让「Monitor 4K / 无外接」这种结论变成猜测）。
+#[must_use]
+pub fn env_line(probe: &Probe, language: &str, scale: Option<f32>, tz: Option<&str>) -> String {
+    format!(
+        "[env] os={} arch={} cores={} language={language} tz={} scale_requested={} display=needs-window \
+         adapters={} hardware={} gpu=\"{}\"",
+        std::env::consts::OS,
+        std::env::consts::ARCH,
+        std::thread::available_parallelism().map_or(0, std::num::NonZeroUsize::get),
+        tz.unwrap_or("<未设置>"),
+        scale.map_or_else(|| "system".to_owned(), |value| value.to_string()),
+        probe.adapters.len(),
+        probe.hardware,
+        gpu_summary(probe),
+    )
+}
+
+/// 枚举结果里**最该被当成 GPU** 的那个适配器的摘要：`DiscreteGpu > IntegratedGpu > 其它`。
+///
+/// 为什么不是「第一个非 Cpu/Other」（M98 r1 p3-2）：本机枚举顺序是核显在前，于是 `[env] gpu=`
+/// 报的是 `AMD Radeon(TM) Graphics [IntegratedGpu]`，而 iced 实际选的是
+/// `AMD Radeon RX 6600 XT [DiscreteGpu]`。一行「机器有什么显卡」的日志报错型号，比不报更坏。
+/// 判据仍然只管**型号名称**：真正的「iced 选了谁」只有 `[gpu] …Selected: AdapterInfo` 那行有。
+#[must_use]
+pub fn gpu_summary(probe: &Probe) -> String {
+    probe
+        .adapters
+        .iter()
+        .max_by_key(|adapter| gpu_rank(adapter.device_type))
+        .map_or_else(
+            || "<无适配器>".to_owned(),
+            |adapter| format!("{} [{}]", adapter.name, adapter.device_type),
+        )
+}
+
+/// 适配器的「该不该被当成这台机器的显卡」排序权重（越大越该）。
+fn gpu_rank(device_type: &str) -> u8 {
+    match device_type {
+        "DiscreteGpu" => 3,
+        "IntegratedGpu" => 2,
+        "VirtualGpu" => 1,
+        "Cpu" | "Other" => 0,
+        _ => 1,
+    }
+}
+
+/// 时区（`TZ` 环境变量）。`std` 拿不到系统时区，所以这里**只报环境变量**，没有就写未设置。
+///
+/// macOS 上的真值时区由脚本用 `date +%Z%z` 采（那份是观测值，这个只是进程视角）。
+#[must_use]
+pub fn tz() -> Option<String> {
+    std::env::var("TZ")
+        .ok()
+        .filter(|value| !value.trim().is_empty())
+}
+
+// ---------------------------------------------------------------- [i18n]
+
+/// 语言决策链的四级（顺序即优先级：显式值 > 平台源 > 环境变量 > 英文）。
+///
+/// 每一级的**原始值**都留着，日志才能解释「为什么是英文」——只打结论的话，macOS 上「英文」
+/// 到底是「用户就是英文」还是「一个源都没取到」根本分不出来。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Chain {
+    /// `ULL_LANG` 的显式覆盖（截图矩阵的注入值）；`None` = 没设。
+    ///
+    /// 它与 [`Chain::setting`] 是**两个不同的源**：一个是我们为了出图钉的值，一个是用户配置里存的。
+    /// 判定顺序里前者压后者（见 [`Chain::read`]），日志里分开打，读的人不用猜。
+    pub forced: Option<String>,
+    /// `ui.language` 的显式值（`None` = 文件里**没写过** = 跟随系统）。
+    ///
+    /// 与 `App` 启动判定同一个读法（`SettingsBridge::load_ui_language`：只认显式值，不走 schema
+    /// 默认值），所以「没写过」在这里与 `ui::lang` 里是同一个意思。
+    pub setting: Option<String>,
+    /// (源自称的名字, 原始 locale)。
+    pub platform: (&'static str, Option<String>),
+    /// (源自称的名字, 原始 locale)。
+    pub env: (&'static str, Option<String>),
+    /// 只按**平台源 + 环境变量**算出来的「这台机器说什么语言」（**不看** `ui.language`）。
+    ///
+    /// `[env] language=` 用的是它：那一行回答的是「本机是什么」，用户手选英文不该改写机器的事实。
+    pub machine: Detection,
+    /// 最终结论：**与 `App` 启动日志的 `[i18n] choice=…` 用同一个判据函数**
+    /// （`ui::lang::choose_choice` + `LangChoice::resolve`），所以两行不可能说的是两种语言。
+    pub detection: Detection,
+    /// 这一次是不是**截图通道**（D30）：`true` 时配置那一级按设计被忽略，日志里打出来，
+    /// 否则「配置写了英文、结论是中文」看起来像 bug。
+    pub screenshot: bool,
+}
+
+impl Chain {
+    /// 用全部四个源探测一次。**每个源只读一次**（`defaults` / `reg.exe` 都是子进程）。
+    ///
+    /// 优先级**不在这里重写**：档位由 [`crate::ui::lang::choose_choice`] 出（与 `App` 启动判定
+    /// 同一个函数），结论由 `LangChoice::resolve` 出（与 `App` 同一个 `resolve`）。
+    /// 顺序即 **`ULL_LANG` > 配置（`screenshot == false` 才算） > 平台源 > 环境变量 > 英文**。
+    #[must_use]
+    pub fn read(
+        forced: Option<&str>,
+        setting: Option<&str>,
+        screenshot: bool,
+        platform: &dyn LocaleSource,
+        env: &dyn LocaleSource,
+    ) -> Self {
+        let platform = Captured {
+            label: platform.label(),
+            raw: platform.locale(),
+        };
+        let env = Captured {
+            label: env.label(),
+            raw: env.locale(),
+        };
+        // 「机器说什么语言」：与 `ui.language` 无关，`[env] language=` 用它。
+        let machine = lang::resolve(None, &platform, &env);
+        // 「这一次界面用什么语言」：**调产品路径那个函数**，不在这里复制一遍优先级表。
+        let detection =
+            crate::ui::lang::choose_choice(forced, setting, screenshot).resolve(&platform, &env);
+        Self {
+            forced: forced.map(str::to_owned),
+            setting: setting.map(str::to_owned),
+            platform: (platform.label, platform.raw),
+            env: (env.label, env.raw),
+            machine,
+            detection,
+            screenshot,
+        }
+    }
+
+    /// 本机链路（`ULL_LANG` + 配置 + 平台源 + 环境变量）。
+    ///
+    /// `screenshot` 由调用方从 `Options` 递进来（`report_boot` 手上有）：**截图通道按 D30 忽略配置**，
+    /// 这一级判断必须与产品路径同源，否则又会出现「一行说 zh-CN、下一行说 effective=en」。
+    ///
+    /// 诚实边界：这里 `SettingsBridge::open()` 走**默认数据根**；同一次运行若带了 `--data-dir`，
+    /// 配置可能来自另一份文件（此时以 `App` 那行 `[i18n] choice=…` 为准，它用的是 App 自己的桥）。
+    #[must_use]
+    pub fn host(screenshot: bool) -> Self {
+        let forced = std::env::var(crate::ui::lang::LANG_ENV)
+            .ok()
+            .filter(|value| !value.trim().is_empty());
+        let setting = SettingsBridge::open().load_ui_language();
+        Self::read(
+            forced.as_deref(),
+            setting.as_deref(),
+            screenshot,
+            platform_locale_source(),
+            &lang::EnvLocale,
+        )
+    }
+
+    /// **机器的**语言标签（`zh-CN` / `en`）——不含 `ui.language` 的手选。
+    #[must_use]
+    pub fn language(&self) -> &'static str {
+        self.machine.lang.tag()
+    }
+
+    /// `[i18n]` 一行：四个源 + 结论。
+    ///
+    /// 顺序即 `ULL_LANG` > 配置（`shot=false` 才参与） > 平台源 > 环境变量 > 英文；`->` 后面那一段
+    /// 就是**最终生效语言 + 它来自哪一级**，与 `App` 的 `[i18n] choice=…` **用同一个判据函数**算出来。
+    ///
+    /// 为什么把 `forced=` 与 `shot=` 也打出来：`shot=true` 时配置按 D30 被忽略，不写这一格的话
+    /// 「配置里明明写了 en_us，结论却是 zh-CN」看起来像 bug（r4 复审 p2-1 的两组复现就是这两种）。
+    ///
+    /// 曾经这里钉着 `ui_text=pinned-en`（那会儿 `pages/mod.rs::render` 真的把下载页写死成英文）。
+    #[must_use]
+    pub fn line(&self) -> String {
+        format!(
+            "[i18n] forced={} setting={} platform={}:{} env={}:{} shot={} -> {}",
+            self.forced.as_deref().unwrap_or("<未设置>"),
+            self.setting.as_deref().unwrap_or("<未设置=跟随系统>"),
+            self.platform.0,
+            show(self.platform.1.as_deref()),
+            self.env.0,
+            show(self.env.1.as_deref()),
+            self.screenshot,
+            self.detection.describe()
+        )
+    }
+}
+
+fn show(value: Option<&str>) -> String {
+    value.map_or_else(|| "<未设置>".to_owned(), |raw| raw.to_owned())
+}
+
+/// 把值钉住的源（为了「读一次、按真优先级算」）。
+struct Captured {
+    label: &'static str,
+    raw: Option<String>,
+}
+
+impl LocaleSource for Captured {
+    fn locale(&self) -> Option<String> {
+        self.raw.clone()
+    }
+
+    fn label(&self) -> &'static str {
+        self.label
+    }
+}
+
+/// 本平台的「系统语言」真值源。
+///
+/// - Windows：`reg.exe` 读注册表（[`crate::platform::locale::SystemLocale`]）；
+/// - macOS：[`AppleLanguages`]（`defaults read -g AppleLanguages`）；
+/// - 其它：没有平台源（`resolve` 会继续往环境变量走）。
+///
+/// 为什么 macOS 不复用 `SystemLocale`：它 `cfg!(windows)` 之外恒返回 `None`，在 Mac 上等于
+/// 「没有平台源」——于是语言只剩环境变量一级，而 GUI 程序从 Finder 启动时 `LANG` 通常是空的。
+#[must_use]
+pub fn platform_locale_source() -> &'static dyn LocaleSource {
+    #[cfg(target_os = "macos")]
+    {
+        &AppleLanguages
+    }
+    #[cfg(not(target_os = "macos"))]
+    {
+        &crate::platform::locale::SystemLocale
+    }
+}
+
+/// macOS 的系统语言源：`defaults read -g AppleLanguages` 的第一项。
+#[derive(Debug, Clone, Copy, Default)]
+pub struct AppleLanguages;
+
+impl LocaleSource for AppleLanguages {
+    fn locale(&self) -> Option<String> {
+        #[cfg(target_os = "macos")]
+        {
+            let output = std::process::Command::new("defaults")
+                .args(["read", "-g", "AppleLanguages"])
+                .output()
+                .ok()?;
+            if !output.status.success() {
+                return None;
+            }
+            parse_apple_languages(&String::from_utf8_lossy(&output.stdout))
+        }
+        #[cfg(not(target_os = "macos"))]
+        {
+            None
+        }
+    }
+
+    fn label(&self) -> &'static str {
+        "applelanguages"
+    }
+}
+
+/// 解析 `defaults` 的输出，取**第一条**语言（真机格式见测试夹具）。
+///
+/// ```text
+/// (
+///     "zh-Hans-CN",
+///     "en-US"
+/// )
+/// ```
+///
+/// 首项是用户的**首选语言**；后面几项是「语言与地区」里的备选，与本 crate「只看主语言子标签」
+/// 的口径无关。
+#[must_use]
+pub fn parse_apple_languages(text: &str) -> Option<String> {
+    let start = text.find('"')?;
+    let rest = &text[start + 1..];
+    let end = rest.find('"')?;
+    let value = rest[..end].trim();
+    (!value.is_empty()).then(|| value.to_owned())
+}
+
+#[cfg(test)]
+#[path = "locale_tests.rs"]
+mod tests;
diff --git a/crates/app-iced/src/renderer/acceptance/locale_tests.rs b/crates/app-iced/src/renderer/acceptance/locale_tests.rs
new file mode 100644
index 0000000..3e9cbb7
--- /dev/null
+++ b/crates/app-iced/src/renderer/acceptance/locale_tests.rs
@@ -0,0 +1,247 @@
+//! `[env]` / `[i18n]` 的钉死测试（从 `tests.rs` 拆出来：那边撞到 400 行上限）。
+//!
+//! 这两类都靠「把真实输入喂进纯函数再逐字断言」，抓得住的是本项目的头号事故类型：
+//! **在需要结果的地方打印请求或常量**。
+
+use super::*;
+use crate::probe::AdapterSummary;
+use crate::Probe;
+use unlucky_i18n::lang::LocaleSource;
+
+fn probe_of(adapters: &[(&str, &'static str)]) -> Probe {
+    let adapters: Vec<AdapterSummary> = adapters
+        .iter()
+        .map(|(name, device_type)| AdapterSummary {
+            name: (*name).to_owned(),
+            device_type,
+        })
+        .collect();
+    let hardware = adapters
+        .iter()
+        .any(|adapter| !matches!(adapter.device_type, "Cpu" | "Other"));
+    Probe { adapters, hardware }
+}
+
+/// 抓得住：`[env]` 的 `gpu=` 取的是**硬件**适配器而不是枚举里的第一个（WARP 排在第一是本机实测
+/// 的形状：`Microsoft Basic Render Driver [Cpu]`）。改回 `adapters.first()` 这条就红。
+#[test]
+fn env_line_prefers_the_hardware_adapter() {
+    let probe = probe_of(&[
+        ("Microsoft Basic Render Driver", "Cpu"),
+        ("AMD Radeon RX 6600 XT", "DiscreteGpu"),
+    ]);
+    let line = env_line(&probe, "zh-CN", Some(1.0), Some("Asia/Shanghai"));
+    assert!(
+        line.contains("gpu=\"AMD Radeon RX 6600 XT [DiscreteGpu]\""),
+        "{line}"
+    );
+    assert!(line.contains("adapters=2"), "{line}");
+    assert!(line.contains("hardware=true"), "{line}");
+    assert!(line.contains("language=zh-CN"), "{line}");
+    assert!(line.contains("tz=Asia/Shanghai"), "{line}");
+    assert!(line.contains("scale_requested=1"), "{line}");
+    // 显示器只有开窗后才知道：这里必须留白并**自证**留白（写个猜的值比留白更坏）
+    assert!(line.contains("display=needs-window"), "{line}");
+    assert!(line.starts_with("[env] os="), "{line}");
+}
+
+/// 抓得住：「一个适配器都没枚举到」不许写成 `gpu=""` 或者省略（那会让人以为枚举到了）。
+#[test]
+fn env_line_says_so_when_there_is_no_adapter() {
+    let line = env_line(&Probe::default(), "en", None, None);
+    assert!(line.contains("gpu=\"<无适配器>\""), "{line}");
+    assert!(line.contains("adapters=0 hardware=false"), "{line}");
+    assert!(line.contains("scale_requested=system"), "{line}");
+    assert!(line.contains("tz=<未设置>"), "{line}");
+}
+
+/// 抓得住：`[i18n]` 必须把**每一级的原始值**打出来，且结论跟着真优先级走。
+/// 抓不住：这台机器的 `defaults` / `reg.exe` 真的返回什么（那是真机验收）。
+#[test]
+fn i18n_line_shows_every_rung_and_the_resolved_language() {
+    struct Fixed(Option<&'static str>, Option<&'static str>);
+    impl LocaleSource for Fixed {
+        fn locale(&self) -> Option<String> {
+            self.0.map(str::to_owned)
+        }
+        fn label(&self) -> &'static str {
+            self.1.unwrap_or("injected")
+        }
+    }
+
+    let chain = Chain::read(
+        None,
+        None,
+        false,
+        &Fixed(Some("zh-Hans-CN"), Some("applelanguages")),
+        &Fixed(None, Some("env")),
+    );
+    assert_eq!(chain.language(), "zh-CN");
+    let line = chain.line();
+    assert!(
+        line.contains("platform=applelanguages:zh-Hans-CN"),
+        "平台源原始值必须打出来：{line}"
+    );
+    assert!(line.contains("env=env:<未设置>"), "{line}");
+    assert!(line.contains("forced=<未设置>"), "{line}");
+    assert!(line.contains("setting=<未设置=跟随系统>"), "{line}");
+    assert!(line.contains("shot=false"), "{line}");
+    assert!(
+        line.contains("-> lang=zh-CN locale=zh-Hans-CN source=applelanguages"),
+        "{line}"
+    );
+    // **回归绊线（M106 r1 p2-1）**：这行曾经钉着 `ui_text=pinned-en`，在文案真的接了
+    // `model.lang` 之后变成一句假话（「界面钉在英文」）。它不许回来。
+    assert!(
+        !line.contains("pinned-en"),
+        "`ui_text=pinned-en` 是 M106 之前的旧事实，现在会与 App 的 [i18n] 行自相矛盾：{line}"
+    );
+}
+
+/// 配置的手选必须**同时**体现在结论与 `[env]` 的分工上（M106 r1 p2-1 的修法证据）。
+///
+/// 抓得住：①`ui.language` 这一级被丢掉（那行 `->` 的结论会退回系统语言，与 `App` 的
+/// `[i18n] choice=…` 矛盾）；②把「机器语言」也改成手选值（`[env] language=` 答的是「本机是什么」，
+/// 用户手选英文不该改写机器的事实）。
+#[test]
+fn i18n_line_honours_the_explicit_setting_without_rewriting_the_machine_language() {
+    struct Fixed(Option<&'static str>);
+    impl LocaleSource for Fixed {
+        fn locale(&self) -> Option<String> {
+            self.0.map(str::to_owned)
+        }
+        fn label(&self) -> &'static str {
+            "registry"
+        }
+    }
+
+    let chain = Chain::read(
+        None,
+        Some("en_us"),
+        false,
+        &Fixed(Some("zh-CN")),
+        &Fixed(None),
+    );
+    assert_eq!(chain.language(), "zh-CN", "[env] 报的是机器语言");
+    assert_eq!(chain.detection.lang, unlucky_i18n::Lang::En, "手选压过系统");
+    let line = chain.line();
+    assert!(line.contains("setting=en_us"), "{line}");
+    assert!(line.contains("source=setting"), "{line}");
+    assert!(line.contains("lang=en"), "{line}");
+}
+
+/// **两个 `[i18n]` 行不许打架**（r4 复审 p2-1 的回归绊线）。
+///
+/// 复审实测的两组复现，现在必须是同一个结论：
+/// - ① 只设 `ULL_LANG=en_us`、配置干净 ⇒ 结论 = en（`forced` 压过系统中文）；
+/// - ② 配置 `ui.language=en_us` + **截图通道** ⇒ 结论 = zh-CN（D30：截图不读用户配置）；
+/// - ③ 配置 `ui.language=en_us` + 交互通道 ⇒ 结论 = en（配置这一级只在非截图时参与）。
+///
+/// 抓得住：①`ULL_LANG` 这一级被丢掉；②截图通道又去读配置（「一行说 zh-CN、下一行说 effective=en」
+/// 就是这么来的）；③acceptance 侧自己复制了一份优先级表 —— 每条都用
+/// `crate::ui::lang::choose_choice`（产品路径那张表）算出**期望结论**再与 `Chain` 比，谁复制谁红。
+/// 抓不住：真机上 `reg.exe` / `defaults` 读到什么（那是真机验收），以及 `App` 那行日志本身
+/// （它由 `ui/lang.rs` 的单测守）。
+#[test]
+fn i18n_line_and_the_app_agree_on_every_channel_and_override() {
+    use unlucky_i18n::Lang;
+
+    struct Fixed(Option<&'static str>);
+    impl LocaleSource for Fixed {
+        fn locale(&self) -> Option<String> {
+            self.0.map(str::to_owned)
+        }
+        fn label(&self) -> &'static str {
+            "registry"
+        }
+    }
+
+    let registry_zh = Fixed(Some("zh-CN"));
+    let no_env = Fixed(None);
+
+    /// 一行真值表：`(ULL_LANG, 配置, 截图通道) -> (期望语言, 期望来源)`。
+    type Case<'a> = (Option<&'a str>, Option<&'a str>, bool, Lang, &'a str);
+    let table: &[Case<'_>] = &[
+        (Some("en_us"), None, false, Lang::En, "setting"),
+        // 复审组合 ①：`ULL_LANG` 在截图通道里同样压过系统中文
+        (Some("en_us"), None, true, Lang::En, "setting"),
+        // 复审组合 ②：截图通道**忽略配置**，于是退回系统语言
+        (None, Some("en_us"), true, Lang::ZhCn, "registry"),
+        // 组合 ③：非截图通道，配置这一级生效
+        (None, Some("en_us"), false, Lang::En, "setting"),
+        (None, None, false, Lang::ZhCn, "registry"),
+    ];
+
+    for (forced, setting, screenshot, lang, origin) in table {
+        let chain = Chain::read(*forced, *setting, *screenshot, &registry_zh, &no_env);
+        let line = chain.line();
+        assert_eq!(
+            (chain.detection.lang, chain.detection.origin),
+            (*lang, *origin),
+            "forced={forced:?} setting={setting:?} shot={screenshot} 结论不对：{line}"
+        );
+        // `[env] language=` 只报机器语言，任何手选/覆盖都不该改写它。
+        assert_eq!(chain.language(), "zh-CN", "{line}");
+
+        // **同一张表**的结构性钉子：期望结论取自产品路径那个函数，谁在 acceptance 侧另写一份就红。
+        let expected = crate::ui::lang::choose_choice(*forced, *setting, *screenshot)
+            .resolve(&registry_zh, &no_env);
+        assert_eq!(chain.detection, expected, "两侧的判据表漂了：{line}");
+        assert!(
+            line.contains(&format!("shot={screenshot}")),
+            "截图通道必须在行里写出来：{line}"
+        );
+    }
+}
+
+/// 抓得住 macOS 最典型的失败形态：**一个源都没有**（Finder 启动的 GUI 进程既没有 `LANG`
+/// 也没有注册表）。这时必须是 `lang=en source=default`，而不是「假装读到了英文」。
+#[test]
+fn i18n_line_distinguishes_no_source_from_english_source() {
+    struct Nothing;
+    impl LocaleSource for Nothing {
+        fn locale(&self) -> Option<String> {
+            None
+        }
+        fn label(&self) -> &'static str {
+            "applelanguages"
+        }
+    }
+
+    let empty = Chain::read(None, None, false, &Nothing, &Nothing);
+    assert_eq!(empty.language(), "en");
+    assert!(empty.line().contains("source=default"), "{}", empty.line());
+
+    struct EnvEnglish;
+    impl LocaleSource for EnvEnglish {
+        fn locale(&self) -> Option<String> {
+            Some("en_US.UTF-8".to_owned())
+        }
+        fn label(&self) -> &'static str {
+            "env"
+        }
+    }
+
+    let env = Chain::read(None, None, false, &Nothing, &EnvEnglish);
+    assert!(env.line().contains("source=env"), "{}", env.line());
+    assert!(
+        env.line().contains("locale=en_US.UTF-8"),
+        "两种「英文」必须能从日志上分开：{}",
+        env.line()
+    );
+}
+
+/// 真机 `defaults read -g AppleLanguages` 的输出形状（多行、带引号、逗号）。
+#[test]
+fn apple_languages_takes_the_first_entry() {
+    let real = "(\n    \"zh-Hans-CN\",\n    \"en-US\"\n)\n";
+    assert_eq!(parse_apple_languages(real).as_deref(), Some("zh-Hans-CN"));
+    assert_eq!(
+        parse_apple_languages("(\n    \"en-US\"\n)\n").as_deref(),
+        Some("en-US")
+    );
+    assert_eq!(parse_apple_languages("()"), None);
+    assert_eq!(parse_apple_languages(""), None);
+    // 空串（某些机器上 `defaults` 会回 `(\n)`）不许被当成语言
+    assert_eq!(parse_apple_languages("(\n    \"\"\n)"), None);
+}
diff --git a/crates/app-iced/src/renderer/acceptance/mod.rs b/crates/app-iced/src/renderer/acceptance/mod.rs
new file mode 100644
index 0000000..0ad2048
--- /dev/null
+++ b/crates/app-iced/src/renderer/acceptance/mod.rs
@@ -0,0 +1,323 @@
+//! 验收诊断（M98）：把「借朋友一台 Mac、反复问 7 个问题」压成「一次运行、日志自己回答」。
+//!
+//! ## 八类日志的分工（M98 任务表）
+//!
+//! | 类 | 谁打 | 是不是真实结果 |
+//! |---|---|---|
+//! | `[env]` | [`locale`] | 是（`os/arch/cores` 来自编译目标；`gpu` 来自真适配器枚举；`language` 来自下面的语言链） |
+//! | `[backend]` | 本模块（`app::boot` / `pages::harness` 调用） | 是（单项 `ICED_BACKEND` ⇒ 起步成功就是它；失败带具名错误） |
+//! | `[window]` | 本模块 | **请求值**（`requested=`）。实际值由脚本从 `[shot] …scale=` 与 PNG 像素尺寸换算 |
+//! | `[font]` | `fonts`（已有）+ [`visual`]（`chain`） | 是：`platform=` 是实际落点，`chain=` 是令牌声明的回退链 |
+//! | `[theme]` | 本模块 | 是（来源 = 哪个参数/系统决定；系统真值更晚，由已有 `[theme] 系统主题 = …` 打） |
+//! | `[perf]` | 本模块 | 是（`Instant` 实测） |
+//! | `[i18n]` | [`locale`] | 是（四级链的**每一级原始值**都打出来，结论由 `unlucky_i18n::lang::resolve` 给） |
+//! | `[caps]` | [`visual`] | 半观测（`bundle` / `menu_bar_name` 从可执行文件路径读）、半**请求值**（`transparent` / `decorations`） |
+//!
+//! **反模式警告（本项目反复踩的那一类）**：在需要「结果」的地方打「请求」。所以本模块凡是请求值
+//! 都给字段加后缀（`requested` / `…_requested`），凡是推断出来的都给 `_source`，拿不到就写
+//! `<未设置>` / `pending` / `none`，**不猜**。
+//!
+//! ## 开关
+//!
+//! [`ACCEPTANCE_ENV`]（`ULL_ACCEPTANCE=1`）打开「贵的那部分」：`[env]` 里的适配器枚举（本机
+//! 0.65~1.2 s）在 `--renderer=gpu|cpu` 时本来会被跳过，验收要它 ⇒ 这个开关强制枚举一次。
+//! 关掉它对产品行为没有任何影响：本模块只打日志，不改决策。
+//!
+//! 便宜的行（`[backend]` / `[window] requested` / `[theme]`）**没有开关**：报 bug 的人随手截的
+//! 日志里就该有「实际用哪个后端」这件事。
+
+use std::time::Duration;
+
+use crate::renderer::{Decision, Kind};
+use crate::{Backend, Probe};
+
+pub mod locale;
+pub mod visual;
+pub mod window;
+
+pub use locale::{env_line, tz, Chain};
+pub use visual::{caps_line, font_chain_line, report_caps, report_font_chain};
+pub use window::{
+    parse_window_size, report_window, resolve_window_size, window_size, window_text, WindowFacts,
+    WINDOW_SIZE_ENV,
+};
+
+/// 打开「贵的诊断」的开关（见模块文档 §开关）。
+pub const ACCEPTANCE_ENV: &str = "ULL_ACCEPTANCE";
+
+/// `ULL_ACCEPTANCE` 是否打开（缺省关；`0` / `off` / `false` / `no` 也算关）。
+#[must_use]
+pub fn enabled() -> bool {
+    match std::env::var(ACCEPTANCE_ENV) {
+        Ok(value) => !matches!(
+            value.trim().to_ascii_lowercase().as_str(),
+            "0" | "off" | "false" | "no"
+        ),
+        Err(_) => false,
+    }
+}
+
+/// 第一行：告诉读日志的人「后面这些类是刻意打开的，不是噪声」。
+pub fn announce() {
+    eprintln!(
+        "[acceptance] on（{ACCEPTANCE_ENV}）八类诊断已开：[env] [backend] [window] [font] [theme] \
+         [perf] [i18n] [caps]。关掉：{ACCEPTANCE_ENV}=0"
+    );
+}
+
+/// 启动那一段（只在不贵的时候由调用方决定打不打）：`[env]` + `[i18n]`。
+///
+/// 两行都吃**同一次**适配器枚举与**同一次**语言链（`defaults` / `reg.exe` 是子进程，读两次就是
+/// 两次开销，而且两次之间值可能变）。
+pub fn report_startup(probe: &Probe, scale: Option<f32>, screenshot: bool) {
+    // `screenshot` 一路递到 `Chain`：截图通道按 D30 忽略配置，判定必须与产品路径同源
+    // （两行日志用的都是 `ui::lang::choose_choice` 那一张表，见 `locale::Chain::read`）。
+    let chain = Chain::host(screenshot);
+    eprintln!(
+        "{}",
+        env_line(probe, chain.language(), scale, tz().as_deref())
+    );
+    eprintln!("{}", chain.line());
+}
+
+// ---------------------------------------------------------------- [theme]
+
+/// `[theme]`：本次主题**由谁决定**（来源）+ 语义值。
+///
+/// `follows_system=true` 时 `flavor=pending`：系统主题是异步到达的（`iced::system::theme()`），
+/// 启动这一刻还没有值。真值随后由 `app/update.rs` 的 `[theme] 系统主题 = Dark` 给出——
+/// **两行合起来才是完整答案**，缺一行就分不清「跟了系统」和「没跟」。
+pub fn report_theme(source: &str, flavor: Option<&str>, follows_system: bool) {
+    eprintln!("{}", theme_text(source, flavor, follows_system));
+}
+
+/// 主题**由谁决定**（纯判据，好测）：`(来源, 是否跟随系统)`。
+///
+/// 顺序与 `Options::capture_flavor` 一致：`--screenshot-theme` > `--theme` > 截图默认 Light >
+/// 系统。**取值口只有一个**（`capture_flavor`），这里只回答「为什么是它」。
+#[must_use]
+pub fn theme_source(screenshot_theme: bool, theme: bool, screenshot: bool) -> (&'static str, bool) {
+    match (screenshot_theme, theme, screenshot) {
+        (true, _, _) => ("screenshot-theme", false),
+        (_, true, _) => ("theme", false),
+        (_, _, true) => ("default-light", false),
+        _ => ("system", true),
+    }
+}
+
+/// 见 [`report_theme`]（单独返回字符串是为了让测试能逐字断言）。
+#[must_use]
+pub fn theme_text(source: &str, flavor: Option<&str>, follows_system: bool) -> String {
+    format!(
+        "[theme] source={source} flavor={} follows_system={follows_system}",
+        flavor.unwrap_or("pending")
+    )
+}
+
+// ---------------------------------------------------------------- [backend]
+
+/// `[backend] plan`：这一次准备试**哪些**后端（单项 + 本 crate 的兜底，不是 iced 的候选回退）。
+pub fn report_backend_plan(decision: &Decision, request: Backend) {
+    eprintln!("{}", backend_plan_text(decision, request));
+}
+
+/// 见 [`report_backend_plan`]。
+#[must_use]
+pub fn backend_plan_text(decision: &Decision, request: Backend) -> String {
+    format!(
+        "[backend] plan request={} primary={} fallback={} candidates=1 reason={}",
+        request.name(),
+        decision.primary.name(),
+        decision.fallback.map_or("none", Kind::name),
+        decision.reason,
+    )
+}
+
+/// `[backend] final`：起步的**结果**。
+///
+/// 判据是 M97 的「单项 `ICED_BACKEND`」：候选只有一项 ⇒ `run()` 能正常起来就必定是它
+/// （没有静默回退的空间）。`evidence=probe-single-item` 就是这条推理的名字，别把它读成
+/// 「我们查了渲染器内部」——那件事只有 `[gpu] iced_wgpu: …Selected: AdapterInfo…` 那行能做。
+pub fn report_backend_started(primary: Kind, elapsed: Duration) {
+    eprintln!("{}", backend_started_text(primary, elapsed));
+}
+
+/// 见 [`report_backend_started`]。
+#[must_use]
+pub fn backend_started_text(primary: Kind, elapsed: Duration) -> String {
+    format!(
+        "[backend] final={} result=started elapsed={}ms evidence=probe-single-item",
+        primary.name(),
+        elapsed.as_millis()
+    )
+}
+
+/// `[backend] final`：起步失败（具名错误原样带在 `error=` 里，一行可 grep）。
+///
+/// `via` = 失败之后去了哪：
+/// - `respawn`：交互启动换了进程用兜底后端重开（子进程自己再打一遍 plan/final）；
+/// - `refuse`：取证启动（`--screenshot`）拒绝降级出图，**没有图**；
+/// - `none`：没有兜底（`--renderer=cpu` / 没编 wgpu），原样失败。
+///
+/// `final` 是**终态**：`refuse` / `none` 两条路什么都没跑起来 ⇒ `final=none`（不是兜底名）。
+/// 第一版让 `final=` 与 `fallback=` 装同一个值，于是 `[backend] final=tiny-skia result=failed`
+/// 会被 REPORT 的「后端实际选中」照抄成「这次跑的是 tiny-skia」——报告说谎（M98 r1 p3-4）。
+pub fn report_backend_failed(
+    primary: Kind,
+    fallback: Option<Kind>,
+    final_kind: Option<Kind>,
+    via: &str,
+    error: &str,
+) {
+    eprintln!(
+        "{}",
+        backend_failed_text(primary, fallback, final_kind, via, error)
+    );
+}
+
+/// 见 [`report_backend_failed`]。
+#[must_use]
+pub fn backend_failed_text(
+    primary: Kind,
+    fallback: Option<Kind>,
+    final_kind: Option<Kind>,
+    via: &str,
+    error: &str,
+) -> String {
+    let fallback_name = fallback.map_or("none", Kind::name);
+    let final_name = final_kind.map_or("none", Kind::name);
+    // `error="…"` 必须是**格式良好的单个字段**：具名错误里常自带双引号（wgpu 的 Debug 输出），
+    // 原样塞进去会把这一行撕成两半，脚本按 `error="` 取值就只能取到前半截。
+    let error = error.replace('"', "'").replace(['\n', '\r'], " ");
+    format!(
+        "[backend] final={final_name} result=failed primary={} fallback={fallback_name} \
+         via={via} error=\"{error}\"",
+        primary.name(),
+    )
+}
+
+/// 起步失败后去了哪（日志字段 `via=`；与 `app::boot::fallback::OnFailure` 同一套取值）。
+///
+/// 放在这里而不是 `app/boot/fallback.rs`：`mod boot` 在 `app/mod.rs` 里是私有的（那份文件不在
+/// M98 的 scope），`pages::harness` 够不到它，而两个调用点必须用**同一个**判据。
+#[must_use]
+pub fn failure_via(has_fallback: bool, evidence: bool) -> &'static str {
+    match (has_fallback, evidence) {
+        (false, _) => "none",
+        (true, true) => "refuse",
+        (true, false) => "respawn",
+    }
+}
+
+/// 起步结果 → `[backend] final` 一行 +（验收模式）`[perf] session` 一行。
+///
+/// `final_kind` 的口径：`respawn` 时是**兜底**（进程即将带着它重开），`refuse` / `none` 时是
+/// `None`（什么都没跑起来）——见 [`backend_failed_text`]。成功时恒为 `primary`。
+pub fn report_outcome(
+    decision: &Decision,
+    error: Option<&str>,
+    via: &str,
+    mode: &str,
+    elapsed: Duration,
+) {
+    let final_kind = match via {
+        "respawn" => decision.fallback,
+        _ => None,
+    };
+    match error {
+        None => report_backend_started(decision.primary, elapsed),
+        Some(message) => report_backend_failed(
+            decision.primary,
+            decision.fallback,
+            final_kind,
+            via,
+            message,
+        ),
+    }
+    if enabled() {
+        report_perf_session(mode, elapsed, error.is_none());
+    }
+}
+
+/// `[perf] boot`：启动三段（探测 / 字体 / 到 `run()` 之前）的实测毫秒数。
+///
+/// `probe = None` ⇒ 打 `probe=skipped`。**不许拿 `0ms` 冒充一次实测**（M98 r1 p3-1：降级重开那一轮
+/// 没计时却报了 0，而报告说「[perf] 全是 Instant 实测」）。
+pub fn report_perf_boot(probe: Option<Duration>, font: Duration, to_run: Duration) {
+    eprintln!("{}", perf_boot_text(probe, font, to_run));
+}
+
+/// 见 [`report_perf_boot`]。
+#[must_use]
+pub fn perf_boot_text(probe: Option<Duration>, font: Duration, to_run: Duration) -> String {
+    format!(
+        "[perf] boot probe={} font={}ms to_run={}ms",
+        probe.map_or_else(
+            || "skipped".to_owned(),
+            |value| format!("{}ms", value.as_millis())
+        ),
+        font.as_millis(),
+        to_run.as_millis()
+    )
+}
+
+/// `[perf] session`：`iced::application().run()` 从进到出（或到出图）的总时长。
+///
+/// 取证启动（`--screenshot`）的出图在第 3 帧，所以这条约等于「进程启动 → 出图」——验收里它就是
+/// 「这个场景要多久」。交互启动那次是「窗口开了多久」，所以带 `mode=` 区分，别混着读。
+pub fn report_perf_session(mode: &str, elapsed: Duration, ok: bool) {
+    eprintln!("{}", perf_session_text(mode, elapsed, ok));
+}
+
+/// 见 [`report_perf_session`]。
+#[must_use]
+pub fn perf_session_text(mode: &str, elapsed: Duration, ok: bool) -> String {
+    format!(
+        "[perf] session mode={mode} elapsed={}ms result={}",
+        elapsed.as_millis(),
+        if ok { "ok" } else { "failed" }
+    )
+}
+
+/// `[perf] scene`：**取证场景**（`pages_demo` 通道）的帧数据。
+///
+/// `fps` 由 `frames / elapsed` 算——注意它是**取证窗口**（第 1 帧到第 N 帧）的吞吐，不是长时间
+/// 稳态帧率：产品路径的长跑帧率看 `[tick]` 那串（`ULL_TICK_TRACE=1`，每秒一行、带累计帧数）。
+/// 两个来源刻意不合并：一个是「出这张图花了多久」，一个是「放着不动烧不烧风扇」。
+pub fn report_perf_scene(
+    scene: &str,
+    frames: u32,
+    first_frame: Option<Duration>,
+    elapsed: Duration,
+) {
+    eprintln!("{}", perf_scene_text(scene, frames, first_frame, elapsed));
+}
+
+/// 见 [`report_perf_scene`]。
+#[must_use]
+pub fn perf_scene_text(
+    scene: &str,
+    frames: u32,
+    first_frame: Option<Duration>,
+    elapsed: Duration,
+) -> String {
+    // fps 只从**首帧之后**的帧间隔算：整段起点到首帧那段是启动成本（字体扫描、适配器枚举），
+    // 把它算进帧率会让「8 fps」这种结论完全是启动慢的假象。少于 2 帧就没有间隔可测 ⇒ unknown。
+    let fps = first_frame.and_then(|first| {
+        let window = elapsed.checked_sub(first)?;
+        (frames >= 2 && !window.is_zero()).then(|| f64::from(frames - 1) / window.as_secs_f64())
+    });
+    format!(
+        "[perf] scene={scene} frames={frames} first_frame={}ms elapsed={}ms fps={}",
+        first_frame.map_or_else(
+            || "unknown".to_owned(),
+            |value| value.as_millis().to_string()
+        ),
+        elapsed.as_millis(),
+        fps.map_or_else(|| "unknown".to_owned(), |value| format!("{value:.1}")),
+    )
+}
+
+#[cfg(test)]
+#[path = "tests.rs"]
+mod tests;
diff --git a/crates/app-iced/src/renderer/acceptance/tests.rs b/crates/app-iced/src/renderer/acceptance/tests.rs
new file mode 100644
index 0000000..360fadb
--- /dev/null
+++ b/crates/app-iced/src/renderer/acceptance/tests.rs
@@ -0,0 +1,395 @@
+//! `[env]` / `[i18n]` / `[window]` / `[caps]` / `[backend]` / `[perf]` 六类行的钉死测试。
+//!
+//! **这些测试只钉「给定真实输入 → 打出什么」**：格式化函数是纯的，所以能断言逐字字符串。
+//! 它们抓不住「输入本身是不是真的」（那要靠验收脚本在真机上 grep），抓得住的是这一整类事故：
+//! **在需要结果的地方打印请求 / 常量**——每一格都有一个能改坏的断言。
+
+use std::path::Path;
+use std::time::Duration;
+
+use super::*;
+use crate::probe::AdapterSummary;
+use crate::renderer::decision::{decide, Kind};
+use crate::Probe;
+use unlucky_design::typography::Platform as FontPlatform;
+
+fn probe_of(adapters: &[(&str, &'static str)]) -> Probe {
+    let adapters: Vec<AdapterSummary> = adapters
+        .iter()
+        .map(|(name, device_type)| AdapterSummary {
+            name: (*name).to_owned(),
+            device_type,
+        })
+        .collect();
+    let hardware = adapters
+        .iter()
+        .any(|adapter| !matches!(adapter.device_type, "Cpu" | "Other"));
+    Probe { adapters, hardware }
+}
+
+/// 抓得住：`[window]` 打的是**请求**，字段名必须自证（`requested` / `scale_requested`）。
+/// 抓不住：窗口真的开成了多大（由验收脚本从 `[shot] … scale=` 与 PNG 像素换算）。
+#[test]
+fn window_line_is_labelled_as_a_request() {
+    let facts = WindowFacts {
+        size: (1180.0, 760.0),
+        min: Some((880.0, 560.0)),
+        resizable: true,
+        decorations: false,
+        transparent: false,
+    };
+    let line = window_text(&facts, None, "default", Some("Unlucky Launcher"));
+    assert!(
+        line.starts_with("[window] requested size=1180x760"),
+        "{line}"
+    );
+    assert!(line.contains("min=880x560"), "{line}");
+    assert!(line.contains("resizable=true"), "{line}");
+    assert!(line.contains("decorations=false"), "{line}");
+    assert!(line.contains("transparent=false"), "{line}");
+    assert!(line.contains("scale_requested=system"), "{line}");
+    assert!(line.contains("size_source=default"), "{line}");
+    assert!(line.contains("title=\"Unlucky Launcher\""), "{line}");
+
+    // `pages_demo` 那条通道没有最小尺寸 / 自定标题：必须写 none / <默认>，不许编 0x0
+    let harness = window_text(
+        &WindowFacts { min: None, ..facts },
+        Some(1.0),
+        "pages_demo",
+        None,
+    );
+    assert!(harness.contains("min=none"), "{harness}");
+    assert!(harness.contains("title=<默认>"), "{harness}");
+    assert!(harness.contains("scale_requested=1"), "{harness}");
+}
+
+/// `ULL_WINDOW_SIZE` 的三种分隔符都要认；非法值必须返回 `None`（调用方打警告，不许静默吞）。
+#[test]
+fn window_size_override_accepts_the_three_separators() {
+    for raw in ["1520x900", "1520X900", "1520×900", " 1180 x 760 "] {
+        assert!(parse_window_size(raw).is_some(), "{raw:?}");
+    }
+    assert_eq!(parse_window_size("1520x900"), Some((1520.0, 900.0)));
+    for raw in [
+        "",
+        "1520",
+        "1520x",
+        "x900",
+        "0x900",
+        "-1x900",
+        "axb",
+        "1520x900x1",
+    ] {
+        assert_eq!(parse_window_size(raw), None, "{raw:?}");
+    }
+}
+
+/// 抓得住：`size_source=` 必须能区分「默认」「覆盖生效」「覆盖被夹到最小」「覆盖是垃圾」——
+/// 四种情况打出一样的两张图，是最典型的假绿（脚本以为在测宽屏，其实测的是默认）。
+#[test]
+fn window_size_source_distinguishes_the_four_cases() {
+    let default = (1180.0, 760.0);
+    let min = (880.0, 560.0);
+
+    assert_eq!(
+        resolve_window_size(None, default, min),
+        (default, "default")
+    );
+    assert_eq!(
+        resolve_window_size(Some("1520x900"), default, min),
+        ((1520.0, 900.0), "ULL_WINDOW_SIZE")
+    );
+    // 最小尺寸档：正好等于 min，不该被标成 clamped
+    assert_eq!(
+        resolve_window_size(Some("880x560"), default, min),
+        ((880.0, 560.0), "ULL_WINDOW_SIZE")
+    );
+    assert_eq!(
+        resolve_window_size(Some("640x480"), default, min),
+        (min, "ULL_WINDOW_SIZE:clamped-to-min")
+    );
+    assert_eq!(
+        resolve_window_size(Some("wide-ish"), default, min),
+        (default, "ULL_WINDOW_SIZE:invalid")
+    );
+}
+
+/// 抓得住：macOS 上「菜单栏显示什么名字」从可执行文件路径就能读出来——bundle 与非 bundle
+/// 是两条不同的答案，且 `controls=self-drawn` 由 `decorations=false` 推出来。
+#[test]
+fn caps_line_reads_the_menu_bar_name_from_the_executable_path() {
+    let plain = caps_line(
+        Some(Path::new(
+            "/Users/x/ull/target/release/unlucky-launcher-iced",
+        )),
+        false,
+        true,
+        false,
+    );
+    assert!(plain.contains("bundle=no"), "{plain}");
+    assert!(
+        plain.contains("menu_bar_name=\"unlucky-launcher-iced\""),
+        "{plain}"
+    );
+    assert!(plain.contains("menu_bar_source=exe-stem"), "{plain}");
+    assert!(plain.contains("controls=self-drawn"), "{plain}");
+
+    let bundled = caps_line(
+        Some(Path::new(
+            "/Applications/Unlucky Launcher.app/Contents/MacOS/unlucky-launcher-iced",
+        )),
+        false,
+        true,
+        false,
+    );
+    assert!(bundled.contains("bundle=yes"), "{bundled}");
+    assert!(
+        bundled.contains("menu_bar_name=\"Unlucky Launcher\""),
+        "{bundled}"
+    );
+    assert!(bundled.contains("menu_bar_source=bundle"), "{bundled}");
+
+    let native = caps_line(Some(Path::new("/tmp/ull")), false, true, true);
+    assert!(native.contains("controls=native"), "{native}");
+}
+
+/// 抓得住：`bundle=` 与 `menu_bar_name=` 拿不到路径时不猜（`<未知>`）。
+#[test]
+fn caps_line_does_not_guess_without_a_path() {
+    let line = caps_line(None, false, true, false);
+    assert!(line.contains("bundle=no"), "{line}");
+    assert!(line.contains("menu_bar_name=\"<未知>\""), "{line}");
+}
+
+/// 抓得住：`[backend] plan` 打的是**判据产物**（primary / fallback / reason），不是请求。
+/// 改回 `request=` 当 primary 用、或把兜底写成候选列表，这条就红。
+#[test]
+fn backend_plan_prints_the_decision_not_the_request() {
+    let probe = probe_of(&[("Apple M1", "IntegratedGpu")]);
+    let decision = decide(crate::Backend::Auto, &probe, true);
+    let line = backend_plan_text(&decision, crate::Backend::Auto);
+    assert!(line.contains("request=auto"), "{line}");
+    assert!(line.contains("primary=wgpu"), "{line}");
+    assert!(line.contains("fallback=tiny-skia"), "{line}");
+    assert!(line.contains("candidates=1"), "{line}");
+    assert!(line.contains("reason=auto-hardware-adapter"), "{line}");
+}
+
+/// 抓得住：`[backend] final` 的两条路都要能一眼读出「到底跑起来的是谁」。
+#[test]
+fn backend_final_lines_separate_started_from_failed() {
+    let started = backend_started_text(Kind::Wgpu, Duration::from_millis(37));
+    assert!(
+        started.contains("final=wgpu result=started elapsed=37ms"),
+        "{started}"
+    );
+    assert!(started.contains("evidence=probe-single-item"), "{started}");
+
+    // refuse：**什么都没跑起来** ⇒ final=none（不是兜底名，否则报告会把「这次用的是 tiny-skia」当真）
+    let refused = backend_failed_text(
+        Kind::Wgpu,
+        Some(Kind::TinySkia),
+        None,
+        "refuse",
+        "metal support not compiled in",
+    );
+    assert!(refused.contains("final=none result=failed"), "{refused}");
+    assert!(refused.contains("fallback=tiny-skia"), "{refused}");
+    assert!(refused.contains("primary=wgpu"), "{refused}");
+    assert!(refused.contains("via=refuse"), "{refused}");
+    assert!(
+        refused.contains("error=\"metal support not compiled in\""),
+        "具名错误必须原样出现在同一行里：{refused}"
+    );
+
+    let none = backend_failed_text(Kind::TinySkia, None, None, "none", "boom");
+    assert!(none.contains("final=none result=failed"), "{none}");
+
+    // respawn：进程即将带着兜底重开 ⇒ final=<兜底>
+    let respawned = backend_failed_text(
+        Kind::Wgpu,
+        Some(Kind::TinySkia),
+        Some(Kind::TinySkia),
+        "respawn",
+        "x",
+    );
+    assert!(respawned.contains("final=tiny-skia"), "{respawned}");
+    assert!(respawned.contains("via=respawn"), "{respawned}");
+
+    // 具名错误自带双引号时，`error="…"` 仍必须是**格式良好的单个字段**（否则脚本只能取到前半截）
+    let quoted = backend_failed_text(
+        Kind::Wgpu,
+        Some(Kind::TinySkia),
+        None,
+        "refuse",
+        "GraphicsAdapterNotFound { backend: \"wgpu\" }",
+    );
+    assert!(
+        quoted.contains("error=\"GraphicsAdapterNotFound { backend: 'wgpu' }\""),
+        "{quoted}"
+    );
+    assert_eq!(
+        quoted.matches('"').count(),
+        2,
+        "整行只该有 error= 那一对引号：{quoted}"
+    );
+}
+
+/// 抓得住：`[perf]` 打的是实测毫秒数，不是「预计」；场景行的 fps 由帧数/时长算。
+#[test]
+fn perf_lines_carry_measured_millis() {
+    let boot = perf_boot_text(
+        Some(Duration::from_millis(650)),
+        Duration::from_millis(120),
+        Duration::from_millis(780),
+    );
+    assert_eq!(boot, "[perf] boot probe=650ms font=120ms to_run=780ms");
+    // 没探测 ⇒ skipped，不是 0ms（M98 r1 p3-1：拿 0 冒充实测）
+    let skipped = perf_boot_text(None, Duration::from_millis(120), Duration::from_millis(780));
+    assert!(skipped.contains("probe=skipped"), "{skipped}");
+
+    let session = perf_session_text("screenshot", Duration::from_millis(1234), true);
+    assert!(session.contains("mode=screenshot elapsed=1234ms result=ok"));
+
+    let scene = perf_scene_text(
+        "instances-minimal-w880",
+        3,
+        Some(Duration::from_millis(210)),
+        Duration::from_millis(300),
+    );
+    assert!(
+        scene.contains("frames=3 first_frame=210ms elapsed=300ms"),
+        "{scene}"
+    );
+    // 只算首帧之后的帧间隔：(3-1) 帧 / (0.30-0.21) s ≈ 22.2 fps（启动那段不算进帧率）
+    assert!(scene.contains("fps=22.2"), "{scene}");
+    // 少于 2 帧 / 没有首帧时间 ⇒ 没有间隔可测，必须是 unknown 而不是编一个数
+    let one = perf_scene_text(
+        "x",
+        1,
+        Some(Duration::from_millis(5)),
+        Duration::from_millis(9),
+    );
+    assert!(one.contains("fps=unknown"), "{one}");
+    let no_first = perf_scene_text("x", 5, None, Duration::from_millis(9));
+    assert!(no_first.contains("fps=unknown"), "{no_first}");
+}
+
+/// 抓得住：`[font] chain` 来自令牌的三条栈（顺序 = 首选 → 兜底），不是某个常量字符串。
+#[test]
+fn font_chain_lists_the_token_stacks_in_order() {
+    let line = font_chain_line(FontPlatform::MacOs);
+    assert!(line.starts_with("[font] chain platform=macos"), "{line}");
+    // macOS 的中文兜底族必须在链里（M98 要验的就是它有没有被用上）
+    assert!(line.contains("PingFang SC"), "{line}");
+    assert!(line.contains("mono="), "{line}");
+    // 顺序：首选族在前，通用族名在最后
+    let text = line.split("text=").nth(1).expect("text 栈");
+    let first = text.split('>').next().unwrap_or_default();
+    assert!(!first.contains("sans-serif"), "栈头不该是通用族名：{line}");
+}
+
+/// 抓得住：`[theme]` 的来源判定（哪个参数赢）与「跟随系统 = pending」这条不变量。
+#[test]
+fn theme_source_follows_the_capture_flavor_order() {
+    // --screenshot-theme 压过 --theme，也压过「这是截图模式」的默认值
+    assert_eq!(theme_source(true, true, true), ("screenshot-theme", false));
+    assert_eq!(theme_source(false, true, true), ("theme", false));
+    // 截图模式没给主题 ⇒ 默认 Light（不是「等系统」）
+    assert_eq!(theme_source(false, false, true), ("default-light", false));
+    // 交互模式没给主题 ⇒ 跟随系统（异步，真值晚到）
+    assert_eq!(theme_source(false, false, false), ("system", true));
+
+    let system = theme_text("system", None, true);
+    assert!(system.contains("flavor=pending"), "{system}");
+}
+
+/// 抓得住：`[theme]` 的 `follows_system=true` 必须同时是 `flavor=pending`
+/// （系统主题异步到达；写死一个值就是猜）。
+#[test]
+fn theme_line_marks_the_async_system_case_as_pending() {
+    let system = theme_text("system", None, true);
+    assert!(system.contains("source=system"), "{system}");
+    assert!(system.contains("flavor=pending"), "{system}");
+    assert!(system.contains("follows_system=true"), "{system}");
+
+    let pinned = theme_text("screenshot-theme", Some("dark"), false);
+    assert!(pinned.contains("flavor=dark"), "{pinned}");
+    assert!(pinned.contains("follows_system=false"), "{pinned}");
+}
+
+/// 抓得住：开关默认关（产品启动不该多花 1 s 去枚举适配器），`0/off/false/no` 也算关。
+#[test]
+fn acceptance_switch_is_off_by_default() {
+    // 这个测试不读进程环境（会与其它测试抢 `set_var`），只钉常量名：
+    // 名字改了验收脚本就失效，所以它必须是测试锁住的东西。
+    assert_eq!(ACCEPTANCE_ENV, "ULL_ACCEPTANCE");
+    assert_eq!(WINDOW_SIZE_ENV, "ULL_WINDOW_SIZE");
+}
+
+/// 抓得住：`theme_source()`（日志用）与 `Options::capture_flavor()`（真取值口）**两处优先级漂了**——
+/// 漂了就会打出错的 `source=`，而图上的主题才是真的（M98 r1 p3-5：两份实现，没有交叉测试）。
+/// 抓不住：系统主题异步到达之后的值（那要 `[theme] 系统主题 = …` 那一行）。
+#[test]
+fn theme_source_agrees_with_the_only_flavor_gate() {
+    use crate::cli::Options;
+
+    let cases: [&[&str]; 5] = [
+        &[],
+        &["--screenshot", "out.png"],
+        &["--screenshot", "out.png", "--theme=dark"],
+        &[
+            "--screenshot",
+            "out.png",
+            "--theme=dark",
+            "--screenshot-theme=light",
+        ],
+        &["--theme=dark"],
+    ];
+
+    for args in cases {
+        let options = Options::parse(args.iter().map(|arg| (*arg).to_owned())).expect("参数合法");
+        let (source, follows) = theme_source(
+            options.screenshot_theme.is_some(),
+            options.theme.is_some(),
+            options.screenshot.is_some(),
+        );
+        let flavor = options.capture_flavor();
+
+        assert_eq!(
+            follows,
+            flavor.is_none(),
+            "{}：follows_system 与 capture_flavor().is_none() 必须一致",
+            args.join(" ")
+        );
+        // 非「跟随系统」时，来源标签必须能解释 capture_flavor 给出的那个值
+        match source {
+            "screenshot-theme" => assert_eq!(flavor, options.screenshot_theme),
+            "theme" => assert_eq!(flavor, options.theme),
+            "default-light" => assert_eq!(flavor, Some(unlucky_design::color::SchemeFlavor::Light)),
+            "system" => assert_eq!(flavor, None),
+            other => panic!("没料到的来源 {other}"),
+        }
+    }
+}
+
+/// 抓得住：`via` 的三档与判据表第 8/9 行一致（有兜底 + 取证启动 ⇒ `refuse`，**不是** `respawn`）。
+#[test]
+fn failure_via_matches_the_two_paths_of_the_criteria_table() {
+    assert_eq!(
+        failure_via(true, false),
+        "respawn",
+        "交互启动 + 有兜底 ⇒ 换进程重开"
+    );
+    assert_eq!(
+        failure_via(true, true),
+        "refuse",
+        "取证启动 + 有兜底 ⇒ 拒绝出图"
+    );
+    assert_eq!(failure_via(false, false), "none", "没兜底 ⇒ 原样失败");
+    assert_eq!(
+        failure_via(false, true),
+        "none",
+        "没兜底时也不该冒出 refuse 的提示"
+    );
+}
diff --git a/crates/app-iced/src/renderer/acceptance/visual.rs b/crates/app-iced/src/renderer/acceptance/visual.rs
new file mode 100644
index 0000000..010da81
--- /dev/null
+++ b/crates/app-iced/src/renderer/acceptance/visual.rs
@@ -0,0 +1,103 @@
+//! `[font]` 的回退链与 `[caps]` 的平台能力——两件「看一眼就知道对不对」的事。
+//!
+//! 这里的两个函数都是**纯格式化**（除了 `[caps]` 读一次 `current_exe()`，那是调用方传进来的）：
+
+use std::path::Path;
+
+use unlucky_design::typography::{FontFamily, Platform as FontPlatform};
+
+// ---------------------------------------------------------------- [font]
+
+/// `[font] chain`：令牌里三条栈的**声明**顺序（首选 → 兜底 → 通用族名）。
+///
+/// 与 `fonts` 打的 `[font] platform=…` 互补：那行是「实际落到哪个族」，这行是「本来想落哪些」。
+/// 缺字体（方块字）时要看的是**两者的差**：链里有 `"PingFang SC"` 但 `text=` 落到别的族，
+/// 就是这台机器没有苹方。
+#[must_use]
+pub fn font_chain_line(platform: FontPlatform) -> String {
+    let stacks = [
+        ("display", FontFamily::Display),
+        ("text", FontFamily::Text),
+        ("mono", FontFamily::Mono),
+    ]
+    .map(|(name, family)| {
+        let chain = platform
+            .font_stack(family)
+            .iter()
+            .map(|face| format!("\"{}\"", face.family))
+            .collect::<Vec<_>>()
+            .join(">");
+        format!("{name}={chain}")
+    })
+    .join(" ");
+
+    format!(
+        "[font] chain platform={} {stacks}（令牌声明的回退链；实际落点见上面 [font] platform=…）",
+        platform.name()
+    )
+}
+
+/// 打一行 [`font_chain_line`]（调用点只留一句）。
+pub fn report_font_chain(platform: FontPlatform) {
+    eprintln!("{}", font_chain_line(platform));
+}
+
+// ---------------------------------------------------------------- [caps]
+
+/// `[caps]`：平台能力里**本进程能自己回答**的那几条。
+///
+/// 半观测半请求，字段名照实说：
+/// - `bundle` / `menu_bar_name`：观测（从可执行文件路径读）；
+/// - `transparent` / `decorations` / `resizable`：本进程给窗口的设置（**请求值**，即终端用户
+///   实际跑的那个形态；`decorations=false` ⇒ 三键是自绘的）；
+/// - `controls=self-drawn`：由 `decorations=false` 推出来的结论（自绘三键在**右上角**，
+///   与 macOS 惯例的左上相反——这条正是「三键位置怪不怪」的机器答案，位置本身由脚本在截图上
+///   做像素定位）。
+#[must_use]
+pub fn caps_line(
+    exe: Option<&Path>,
+    transparent: bool,
+    resizable: bool,
+    decorations: bool,
+) -> String {
+    let (is_bundle, name) = bundle_of(exe);
+    format!(
+        "[caps] bundle={} menu_bar_name=\"{name}\" menu_bar_source={} controls={} \
+         transparent={transparent} resizable={resizable} decorations={decorations}",
+        if is_bundle { "yes" } else { "no" },
+        if is_bundle { "bundle" } else { "exe-stem" },
+        if decorations { "native" } else { "self-drawn" },
+    )
+}
+
+/// 可执行文件 → (是不是 `.app` 包, 菜单栏会显示的名字)。
+///
+/// macOS 上非 bundle 的二进制，菜单栏 App 名就是**可执行文件名**；打成 `.app` 时是
+/// `Foo.app` 里的 `Foo`。这条从路径读得出来，所以「菜单栏名字对不对」**不需要问人**。
+#[must_use]
+pub fn bundle_of(exe: Option<&Path>) -> (bool, String) {
+    let Some(exe) = exe else {
+        return (false, "<未知>".to_owned());
+    };
+
+    // `Foo.app/Contents/MacOS/foo` 里的 `Foo`：路径里出现以 `.app` 结尾的一段就是 bundle。
+    for component in exe
+        .components()
+        .filter_map(|part| part.as_os_str().to_str())
+    {
+        if let Some(name) = component.strip_suffix(".app") {
+            return (true, name.to_owned());
+        }
+    }
+
+    let stem = exe
+        .file_stem()
+        .and_then(|stem| stem.to_str())
+        .unwrap_or("<未知>");
+    (false, stem.to_owned())
+}
+
+/// 打一行 [`caps_line`]（调用点只留一句）。
+pub fn report_caps(exe: Option<&Path>, transparent: bool, resizable: bool, decorations: bool) {
+    eprintln!("{}", caps_line(exe, transparent, resizable, decorations));
+}
diff --git a/crates/app-iced/src/renderer/acceptance/window.rs b/crates/app-iced/src/renderer/acceptance/window.rs
new file mode 100644
index 0000000..51b2ed2
--- /dev/null
+++ b/crates/app-iced/src/renderer/acceptance/window.rs
@@ -0,0 +1,142 @@
+//! `[window]`：**本进程给窗口的那些设置**（不是我们从别处猜的）。
+//!
+//! 唯一产地是 `app/boot/diagnostics.rs::window_settings`（`pages_demo` 通道自己也有一份，
+//! 它没有最小尺寸与自定标题）。这里只做「从 `window::Settings` 抽字段 → 排版」。
+//!
+//! **别再把这些字段写进格式化串**：M98 r1 p2-1 就是这么错的——日志说 `decorations=false`，
+//! 而真实 `settings` 可以改成 `true` 而不惊动任何断言（踩坑记录 U1）。
+
+/// 窗口尺寸覆盖（`ULL_WINDOW_SIZE=1520x900`）。
+///
+/// 为什么是环境变量而不是 `--width`：`cli.rs` 不在 M98 的 scope，而验收矩阵必须有「最小尺寸 /
+/// 宽屏」两档，且必须是**真外壳**（自绘三键 + 标题栏）——`pages_demo` example 的标题栏是留白带，
+/// 出不了「三键位置」那张图。语义与 `ULL_START_ROUTE` 一致：只影响这一次进程。
+pub const WINDOW_SIZE_ENV: &str = "ULL_WINDOW_SIZE";
+
+// ---------------------------------------------------------------- [window]
+
+/// 窗口事实：**从真实的 `window::Settings` 抽出来**的那几个字段（唯一产地见
+/// `app/boot/diagnostics.rs` 的 `window_settings`）。
+///
+/// 为什么要有这个结构：M98 r1 p2-1 —— 第一版把 `resizable=true decorations=false transparent=false`
+/// 写在格式化串里，与真实 `settings` 无绑定；定向变异把 `settings.decorations` 改成 `true`，
+/// 371 个测试全绿，而日志会与 `[caps]` 互相矛盾（踩坑记录 U1）。现在这些字段只能从
+/// [`WindowFacts::from_settings`] 来，没有手抄的入口。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct WindowFacts {
+    /// 窗口尺寸（逻辑像素）。
+    pub size: (f32, f32),
+    /// 最小尺寸（`None` = 没设）。
+    pub min: Option<(f32, f32)>,
+    /// 可缩放。
+    pub resizable: bool,
+    /// 系统装饰（`false` ⇒ 自绘三键）。
+    pub decorations: bool,
+    /// 整窗透明。
+    pub transparent: bool,
+}
+
+impl WindowFacts {
+    /// 从**真正交给 iced/winit 的那个** `window::Settings` 抽字段。
+    #[must_use]
+    pub fn from_settings(settings: &iced::window::Settings) -> Self {
+        Self {
+            size: (settings.size.width, settings.size.height),
+            min: settings.min_size.map(|size| (size.width, size.height)),
+            resizable: settings.resizable,
+            decorations: settings.decorations,
+            transparent: settings.transparent,
+        }
+    }
+}
+
+/// `[window]` 的**请求值**一行（实际值见模块文档的表：脚本从 `[shot] … scale=` 与 PNG 换算）。
+///
+/// `title` 是 `Option`：`pages_demo` 那条通道没有自定标题，打 `<默认>` —— 编一个空串会让
+/// 「标题是什么」变成猜的。
+pub fn report_window(
+    facts: &WindowFacts,
+    scale: Option<f32>,
+    size_source: &str,
+    title: Option<&str>,
+) {
+    eprintln!("{}", window_text(facts, scale, size_source, title));
+}
+
+/// 见 [`report_window`]。
+#[must_use]
+pub fn window_text(
+    facts: &WindowFacts,
+    scale: Option<f32>,
+    size_source: &str,
+    title: Option<&str>,
+) -> String {
+    let min = facts
+        .min
+        .map_or_else(|| "none".to_owned(), |(w, h)| format!("{w}x{h}"));
+    let title = title.map_or_else(|| "<默认>".to_owned(), |text| format!("\"{text}\""));
+    format!(
+        "[window] requested size={}x{} min={min} resizable={} decorations={} transparent={} scale_requested={} size_source={size_source} title={title}",
+        facts.size.0,
+        facts.size.1,
+        facts.resizable,
+        facts.decorations,
+        facts.transparent,
+        scale.map_or_else(|| "system".to_owned(), |value| value.to_string()),
+    )
+}
+
+/// 解析 `ULL_WINDOW_SIZE`（`1520x900` / `1520X900` / `1520×900`）。
+///
+/// 返回 `None` = 不是这个格式（调用方保留默认尺寸并打一行警告，**不**静默忽略）。
+#[must_use]
+pub fn parse_window_size(raw: &str) -> Option<(f32, f32)> {
+    let trimmed = raw.trim();
+    let (width, height) = trimmed
+        .split_once(['x', 'X', '×', '*'])
+        .map(|(w, h)| (w.trim(), h.trim()))?;
+    let width: f32 = width.parse().ok()?;
+    let height: f32 = height.parse().ok()?;
+    (width.is_finite() && height.is_finite() && width > 0.0 && height > 0.0)
+        .then_some((width, height))
+}
+
+/// 尺寸覆盖 → 实际要开多大 + **尺寸来源**（进 `[window] … size_source=`）。
+///
+/// 三种来源：`default`（没设 / 设了但解析不了）与 `ULL_WINDOW_SIZE`（生效）。
+/// 小于最小尺寸时夹到最小并标 `:clamped-to-min`——iced 的 `min_size` 本来也会拦住，
+/// 但那样日志会说「要求 640x480」而实际是 880x560，是典型的「日志说请求、报告当结果」。
+#[must_use]
+pub fn resolve_window_size(
+    raw: Option<&str>,
+    default: (f32, f32),
+    min: (f32, f32),
+) -> ((f32, f32), &'static str) {
+    let Some(raw) = raw else {
+        return (default, "default");
+    };
+    let Some((width, height)) = parse_window_size(raw) else {
+        return (default, "ULL_WINDOW_SIZE:invalid");
+    };
+
+    let clamped = (width.max(min.0), height.max(min.1));
+    if clamped == (width, height) {
+        (clamped, "ULL_WINDOW_SIZE")
+    } else {
+        (clamped, "ULL_WINDOW_SIZE:clamped-to-min")
+    }
+}
+
+/// 窗尺寸（含来源）从进程环境取一遍——`app::boot` 与测试共用同一条路径。
+#[must_use]
+pub fn window_size(default: (f32, f32), min: (f32, f32)) -> ((f32, f32), &'static str) {
+    let raw = std::env::var(WINDOW_SIZE_ENV).ok();
+    let resolved = resolve_window_size(raw.as_deref(), default, min);
+    if resolved.1.ends_with("invalid") {
+        eprintln!(
+            "[window] {WINDOW_SIZE_ENV}={:?} 解析不了（要 1520x900 这种），按默认尺寸跑",
+            raw.unwrap_or_default()
+        );
+    }
+    resolved
+}
diff --git a/crates/app-iced/src/renderer/decision.rs b/crates/app-iced/src/renderer/decision.rs
new file mode 100644
index 0000000..4e71e52
--- /dev/null
+++ b/crates/app-iced/src/renderer/decision.rs
@@ -0,0 +1,331 @@
+//! 判据的**纯函数**部分：`请求 × 探测 × 是否编入 wgpu` → 起步后端 + 兜底后端。
+//!
+//! 表本身（什么条件选什么、日志该打什么、谁能验证）在 [`super`] 的模块文档顶部。
+//! 这里只放可测的东西：判据一旦掺进运行期副作用（写环境变量、看日志、开窗），
+//! 「降级矩阵」就再也写不成表驱动测试了——M97 的教训。
+
+use crate::{Backend, Probe};
+
+/// 一个具体渲染后端（`ICED_BACKEND` 的单项取值）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Kind {
+    /// `ICED_BACKEND=wgpu`。
+    Wgpu,
+    /// `ICED_BACKEND=tiny-skia`。
+    TinySkia,
+}
+
+impl Kind {
+    /// 写进 `ICED_BACKEND` 的取值（也是 `iced_renderer` 认的名字）。
+    #[must_use]
+    pub fn env_value(self) -> &'static str {
+        match self {
+            Kind::Wgpu => "wgpu",
+            Kind::TinySkia => "tiny-skia",
+        }
+    }
+
+    /// 日志里的名字。
+    #[must_use]
+    pub fn name(self) -> &'static str {
+        self.env_value()
+    }
+
+    /// 对应的「档位」（D36 的 CPU 档 / GPU 档判据用）。
+    #[must_use]
+    pub fn tier(self) -> Backend {
+        match self {
+            Kind::Wgpu => Backend::Gpu,
+            Kind::TinySkia => Backend::Cpu,
+        }
+    }
+}
+
+/// 判据产物：起步后端 + **本 crate 自己**的兜底（不是 iced 的候选回退）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Decision {
+    /// 写进 `ICED_BACKEND` 的唯一一项。
+    pub primary: Kind,
+    /// 起步失败后重开的后端；`None` = 没有兜底（强制 CPU / 没编 wgpu）。
+    pub fallback: Option<Kind>,
+    /// 为什么这么判（进日志，验收就靠它）。
+    pub reason: &'static str,
+}
+
+impl Decision {
+    /// 一行给人看的决策描述。
+    #[must_use]
+    pub fn describe(&self) -> String {
+        match self.fallback {
+            Some(fallback) => format!(
+                "renderer = {} reason={} 兜底={}（失败会先打印具名错误）",
+                self.primary.name(),
+                self.reason,
+                fallback.name()
+            ),
+            None => format!(
+                "renderer = {} reason={} 兜底=none（候选表唯一项）",
+                self.primary.name(),
+                self.reason
+            ),
+        }
+    }
+}
+
+/// 判据纯函数：请求 × 探测 × 是否编入 wgpu → 决策。
+///
+/// **必须是纯函数**：M97 的教训是判据一旦掺了运行期副作用（写环境变量、看日志），
+/// 就再也写不出「降级矩阵」的表驱动测试了。
+#[must_use]
+pub fn decide(request: Backend, probe: &Probe, gpu_compiled: bool) -> Decision {
+    match (request, gpu_compiled) {
+        // 1. 用户点名 CPU：只有 CPU，且**不给兜底**（强制就是强制）。
+        (Backend::Cpu, _) => Decision {
+            primary: Kind::TinySkia,
+            fallback: None,
+            reason: "forced-cpu",
+        },
+        // 2. 点名 GPU 但没编 wgpu：只能 CPU，没得兜。
+        (Backend::Gpu, false) => Decision {
+            primary: Kind::TinySkia,
+            fallback: None,
+            reason: "gpu-not-compiled",
+        },
+        // 3. 点名 GPU 且编了：GPU 起步，CPU 兜底（绝不硬失败）。
+        (Backend::Gpu, true) => Decision {
+            primary: Kind::Wgpu,
+            fallback: Some(Kind::TinySkia),
+            reason: "forced-gpu",
+        },
+        // 4. auto + 没编 wgpu。
+        (Backend::Auto, false) => Decision {
+            primary: Kind::TinySkia,
+            fallback: None,
+            reason: "auto-gpu-not-compiled",
+        },
+        // 5. auto + 只有 WARP/llvmpipe 这类软光栅：CPU 起步，wgpu 留作最后兜底。
+        (Backend::Auto, true) if !probe.hardware => Decision {
+            primary: Kind::TinySkia,
+            fallback: Some(Kind::Wgpu),
+            reason: "auto-no-hardware-adapter",
+        },
+        // 6. auto + 有硬件适配器：GPU 起步，CPU 兜底。
+        (Backend::Auto, true) => Decision {
+            primary: Kind::Wgpu,
+            fallback: Some(Kind::TinySkia),
+            reason: "auto-hardware-adapter",
+        },
+    }
+}
+
+/// 预检失败时把 wgpu 降下来（判据表第 7 行）。
+///
+/// 只在 `ULL_PREFLIGHT=1` 且预检真的失败时调用：这时候**别去开那个窗**——重试一次要闪两下窗，
+/// 而且原因已经拿在手里了。
+#[must_use]
+pub fn demote_after_preflight(decision: Decision) -> Decision {
+    if decision.primary != Kind::Wgpu {
+        return decision;
+    }
+    Decision {
+        primary: Kind::TinySkia,
+        fallback: Some(Kind::Wgpu),
+        reason: "preflight-failed",
+    }
+}
+
+/// 降级重开那一次的决策（判据表第 8 行的**子进程侧**，`boot_probe` 的第一分支用它）。
+///
+/// **`fallback` 必须是 `None`**：这一步的兜底就是「不再兜底」。若它非空，子进程再失败时
+/// 还会 respawn ⇒ **无限递归重开**（每次重开都像「刚刚启动」，这种自杀式循环极难诊断）。
+/// 所以这条不变量只在这里定义一次，并由 `decision::tests` 钉住，别在调用点另拼一个 `Decision`。
+#[must_use]
+pub fn fallback_round(kind: Kind) -> Decision {
+    Decision {
+        primary: kind,
+        fallback: None,
+        reason: "fallback-after-failure",
+    }
+}
+
+/// 取证通道（`--screen=gallery`）用：**剥掉兜底**。
+///
+/// 硬规则（M97 定）：**取证工具宁可红着退出，也不能悄悄换一种后端继续出图**。
+/// 以前 gallery 在 wgpu 挂掉时会静默出 CPU 截图，而报告上写的是「GPU 渲染截图」——
+/// 所有视觉结论的可信度都被这一条悄悄打折，而且从输出上看不出来。
+#[must_use]
+pub fn strict(decision: Decision) -> Decision {
+    Decision {
+        fallback: None,
+        reason: "gallery-strict",
+        ..decision
+    }
+}
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn probe(types: &[&'static str]) -> Probe {
+        Probe {
+            adapters: types
+                .iter()
+                .map(|device_type| crate::probe::AdapterSummary {
+                    name: "adapter".to_owned(),
+                    device_type,
+                })
+                .collect(),
+            hardware: types
+                .iter()
+                .any(|device_type| !matches!(*device_type, "Cpu" | "Other")),
+        }
+    }
+
+    /// 判据表的一行：`请求, 探测结论, 是否编入 wgpu, 期望起步, 期望兜底, 期望 reason`。
+    type Case = (Backend, Probe, bool, Kind, Option<Kind>, &'static str);
+
+    /// 判据表第 1~6 行逐行钉死（表驱动）。谁动了 `decide` 的矩阵，这条先红。
+    #[test]
+    fn criterion_table_rows_1_to_6() {
+        let hardware = || probe(&["IntegratedGpu"]);
+        let software = || probe(&["Cpu"]);
+        let cases: &[Case] = &[
+            // 1 强制 CPU：不给兜底
+            (
+                Backend::Cpu,
+                hardware(),
+                true,
+                Kind::TinySkia,
+                None,
+                "forced-cpu",
+            ),
+            (
+                Backend::Cpu,
+                software(),
+                false,
+                Kind::TinySkia,
+                None,
+                "forced-cpu",
+            ),
+            // 2 点名 GPU 但没编
+            (
+                Backend::Gpu,
+                hardware(),
+                false,
+                Kind::TinySkia,
+                None,
+                "gpu-not-compiled",
+            ),
+            // 3 点名 GPU 且编了
+            (
+                Backend::Gpu,
+                hardware(),
+                true,
+                Kind::Wgpu,
+                Some(Kind::TinySkia),
+                "forced-gpu",
+            ),
+            (
+                Backend::Gpu,
+                software(),
+                true,
+                Kind::Wgpu,
+                Some(Kind::TinySkia),
+                "forced-gpu",
+            ),
+            // 4 auto + 没编
+            (
+                Backend::Auto,
+                hardware(),
+                false,
+                Kind::TinySkia,
+                None,
+                "auto-gpu-not-compiled",
+            ),
+            // 5 auto + 只有软光栅
+            (
+                Backend::Auto,
+                software(),
+                true,
+                Kind::TinySkia,
+                Some(Kind::Wgpu),
+                "auto-no-hardware-adapter",
+            ),
+            // 6 auto + 有硬件（macOS M1 走这条）
+            (
+                Backend::Auto,
+                hardware(),
+                true,
+                Kind::Wgpu,
+                Some(Kind::TinySkia),
+                "auto-hardware-adapter",
+            ),
+        ];
+
+        for (request, probe, gpu_compiled, primary, fallback, reason) in cases {
+            let got = decide(*request, probe, *gpu_compiled);
+            assert_eq!(got.primary, *primary, "request={request:?} reason={reason}");
+            assert_eq!(
+                got.fallback, *fallback,
+                "request={request:?} reason={reason}"
+            );
+            assert_eq!(got.reason, *reason);
+        }
+    }
+
+    /// **安全网守门**：除了「强制 CPU」和「没编 wgpu」，任何一条判据都必须留兜底。
+    ///
+    /// 抓不住：兜底那次重开本身失败（那是 iced 的事，见判据表第 8 行）。
+    #[test]
+    fn every_decision_keeps_an_exit() {
+        for request in [Backend::Auto, Backend::Gpu, Backend::Cpu] {
+            for gpu_compiled in [true, false] {
+                for types in [&[][..], &["Cpu"][..], &["IntegratedGpu"][..]] {
+                    let decision = decide(request, &probe(types), gpu_compiled);
+                    let forced = request == Backend::Cpu || !gpu_compiled;
+                    assert_eq!(
+                        decision.fallback.is_none(),
+                        forced,
+                        "{decision:?} 必须留兜底（request={request:?} gpu_compiled={gpu_compiled}）"
+                    );
+                    // 兜底不能和起步项相同，否则重试等于原地打转。
+                    assert_ne!(decision.fallback, Some(decision.primary), "{decision:?}");
+                }
+            }
+        }
+    }
+
+    /// 预检失败只降 wgpu 起步的那些行；`--renderer=cpu` 一行都不许动。
+    #[test]
+    fn preflight_demotes_only_wgpu_decisions() {
+        let hardware = probe(&["IntegratedGpu"]);
+        let auto = decide(Backend::Auto, &hardware, true);
+        let demoted = demote_after_preflight(auto);
+        assert_eq!(demoted.primary, Kind::TinySkia);
+        assert_eq!(demoted.reason, "preflight-failed");
+        assert_eq!(demoted.fallback, Some(Kind::Wgpu), "wgpu 还能当最后兜底");
+
+        let cpu = decide(Backend::Cpu, &hardware, true);
+        assert_eq!(demote_after_preflight(cpu), cpu, "强制 CPU 不许被预检改写");
+    }
+
+    /// 取证通道的决策必须**剥掉兜底**（判据表第 9 行）：`strict` 若忘了清 `fallback`，
+    /// gallery 就能在 wgpu 挂掉时悄悄出 CPU 图——那是 M97 要杀的第九种「假绿」。
+    #[test]
+    fn strict_strips_the_fallback() {
+        let gpu = decide(Backend::Gpu, &Probe::default(), true);
+        assert_eq!(gpu.fallback, Some(Kind::TinySkia), "前提：普通决策有兜底");
+        let strict = strict(gpu);
+        assert_eq!(strict.fallback, None, "取证通道不许有兜底");
+        assert_eq!(strict.primary, Kind::Wgpu, "剥的是兜底，不是起步项");
+        assert_eq!(strict.reason, "gallery-strict");
+    }
+
+    #[test]
+    fn describe_names_the_backend_and_the_reason() {
+        let hardware = probe(&["DiscreteGpu"]);
+        let text = decide(Backend::Auto, &hardware, true).describe();
+        assert!(text.contains("renderer = wgpu"), "{text}");
+        assert!(text.contains("reason=auto-hardware-adapter"), "{text}");
+        assert!(text.contains("兜底=tiny-skia"), "{text}");
+    }
+}
diff --git a/crates/app-iced/src/renderer/log_bridge.rs b/crates/app-iced/src/renderer/log_bridge.rs
new file mode 100644
index 0000000..d45f9a6
--- /dev/null
+++ b/crates/app-iced/src/renderer/log_bridge.rs
@@ -0,0 +1,151 @@
+//! 把 `iced_wgpu` / `wgpu` 的 `log` 输出转到 stderr（判据表第 8 行的取证通道）。
+//!
+//! ## 为什么需要它
+//!
+//! `iced_wgpu` 在**真的**创建设备时会自己打一行：
+//!
+//! ```text
+//! Selected: AdapterInfo { name: "Apple M1", backend: Metal, device_type: IntegratedGpu, … }
+//! ```
+//!
+//! 这行只有「wgpu 走到适配器那一步」才会出现，所以它是**GPU 真生效的实证**——不是我们的推断。
+//! 但它走 `log` crate，而本进程从来没装过 logger，于是 M1 那份报告里这行根本不存在：
+//! 「看不到」被当成了「没有」。装一个只放行 GPU 相关 target 的 logger，成本 60 行，
+//! 换来的是以后每次验收都能直接看见 wgpu 说了什么。
+//!
+//! ## 过滤
+//!
+//! 按 **target 分级**，不是一刀切：`wgpu_hal` / `wgpu_core` 在 Info 级别会刷出上百行 Vulkan
+//! loader 噪声（M97 实测：启动时 90 行 registry 扫描），把真正有用的
+//! `iced_wgpu: Selected: AdapterInfo{…}` 埋掉。
+//!
+//! | `ULL_GPU_LOG` | `iced_wgpu*` | `wgpu*`（hal / core） | 用途 |
+//! |---|---|---|---|
+//! | 未设 / `info` | Info | **Warn** | 默认：看得见选中的适配器/格式 + wgpu 的告警 |
+//! | `warn` | Warn | Warn | 只留告警（启动日志最干净） |
+//! | `debug` | Debug | Debug | 全量（诊断用；含 Vulkan loader 噪声） |
+//! | `off` | — | — | 不装 logger（回到 M97 之前，仅用于对照实验） |
+//!
+//! 其它 target（`winit`、`iced_winit` …）一律不放行：它们只会把启动日志淹掉。
+
+use std::sync::Once;
+
+/// 装 logger（进程内只生效一次；重复调用无害）。
+pub fn install() {
+    static ONCE: Once = Once::new();
+    ONCE.call_once(|| {
+        let Some(level) = level_from_env() else {
+            return;
+        };
+        // `set_boxed_logger` 只能成功一次；已被别人装过就安静让位，不 panic。
+        if log::set_boxed_logger(Box::new(Bridge { level })).is_ok() {
+            log::set_max_level(level);
+        }
+    });
+}
+
+/// `ULL_GPU_LOG` → 过滤级别；`None` = 别装（`off`）。
+fn level_from_env() -> Option<log::LevelFilter> {
+    parse_level(&std::env::var("ULL_GPU_LOG").unwrap_or_default())
+}
+
+/// 取值解释（纯函数，测试直接喂字符串，不碰进程环境）。
+fn parse_level(value: &str) -> Option<log::LevelFilter> {
+    match value.trim().to_ascii_lowercase().as_str() {
+        "off" | "0" | "no" | "false" => None,
+        "warn" | "warning" => Some(log::LevelFilter::Warn),
+        "debug" => Some(log::LevelFilter::Debug),
+        "trace" => Some(log::LevelFilter::Trace),
+        _ => Some(log::LevelFilter::Info),
+    }
+}
+
+/// 某个 target 在这个总级别下实际放行到哪一级。
+///
+/// `wgpu_hal`/`wgpu_core` 在 `info` 档被压到 `warn`：它们的 info 是 Vulkan loader 的原文，
+/// 对「到底用了哪个后端」没有信息量，只有噪声。
+fn target_level(level: log::LevelFilter, target: &str) -> log::LevelFilter {
+    if level == log::LevelFilter::Info && !target.starts_with("iced_wgpu") {
+        return log::LevelFilter::Warn;
+    }
+    level
+}
+
+/// 只放行渲染后端相关 target 的 logger。
+struct Bridge {
+    level: log::LevelFilter,
+}
+
+impl log::Log for Bridge {
+    fn enabled(&self, metadata: &log::Metadata<'_>) -> bool {
+        let target = metadata.target();
+        is_gpu_target(target) && metadata.level() <= target_level(self.level, target)
+    }
+
+    fn log(&self, record: &log::Record<'_>) {
+        if !self.enabled(record.metadata()) {
+            return;
+        }
+        // iced_wgpu 用 `{:#?}` 打多行结构体；压成一行才好 grep / 贴验收报告。
+        let message = record.args().to_string().replace('\n', " ");
+        eprintln!("[gpu] {}: {}", record.target(), message.trim_end());
+    }
+
+    fn flush(&self) {}
+}
+
+/// `iced_wgpu::window::compositor` / `wgpu_core::…` / `wgpu_hal::…` 都算。
+fn is_gpu_target(target: &str) -> bool {
+    ["iced_wgpu", "wgpu"]
+        .iter()
+        .any(|prefix| target.starts_with(prefix))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn only_gpu_targets_pass() {
+        assert!(is_gpu_target("iced_wgpu::window::compositor"));
+        assert!(is_gpu_target("wgpu_core::instance"));
+        assert!(is_gpu_target("wgpu_hal::metal"));
+        assert!(!is_gpu_target("iced_winit::lib"));
+        assert!(!is_gpu_target("winit::event_loop"));
+    }
+
+    #[test]
+    fn level_env_values_are_interpreted() {
+        assert_eq!(parse_level(""), Some(log::LevelFilter::Info));
+        assert_eq!(parse_level("info"), Some(log::LevelFilter::Info));
+        assert_eq!(parse_level(" WARN "), Some(log::LevelFilter::Warn));
+        assert_eq!(parse_level("off"), None);
+        assert_eq!(parse_level("0"), None);
+    }
+
+    /// 默认档（`info`）下 `wgpu_hal`/`wgpu_core` 被压到 Warn：它们是 Vulkan loader 原文，
+    /// M97 实测一屏 90 行噪声，会把 `Selected: AdapterInfo` 埋掉。
+    #[test]
+    fn default_level_mutes_wgpu_noise_but_keeps_adapter_line() {
+        use log::LevelFilter;
+        assert_eq!(
+            target_level(LevelFilter::Info, "iced_wgpu::window::compositor"),
+            LevelFilter::Info,
+            "选中适配器那行必须留"
+        );
+        assert_eq!(
+            target_level(LevelFilter::Info, "wgpu_hal::vulkan::instance"),
+            LevelFilter::Warn,
+            "Vulkan loader 噪声必须压掉"
+        );
+        assert_eq!(
+            target_level(LevelFilter::Info, "wgpu_core::instance"),
+            LevelFilter::Warn
+        );
+        // 显式要 debug 时全放行（诊断用）。
+        assert_eq!(
+            target_level(LevelFilter::Debug, "wgpu_hal::vulkan::instance"),
+            LevelFilter::Debug
+        );
+    }
+}
diff --git a/crates/app-iced/src/renderer/mod.rs b/crates/app-iced/src/renderer/mod.rs
new file mode 100644
index 0000000..90ea616
--- /dev/null
+++ b/crates/app-iced/src/renderer/mod.rs
@@ -0,0 +1,249 @@
+//! 渲染后端的**判据表**（M97）+ 三段可观测性基建。
+//!
+//! 本模块回答一个问题：**这个进程到底跑在哪个渲染器上，凭什么这么断定。**
+//!
+//! ## 判据表（验收直接对照这张表）
+//!
+//! `ICED_BACKEND` **永远是单项**（不是候选列表）。理由见下节「为什么不再用候选列表」：
+//! 单项 ⇒ 「跑起来了 ⇒ 就是它」，不存在需要事后猜的空间。`兜底` 列是**本 crate 自己的重试**，
+//! 不是 iced 的回退，所以它一定伴随一行具名错误日志。
+//!
+//! | # | 条件 | 选哪个 | 日志该打印什么 | 谁能验证 |
+//! |---|---|---|---|---|
+//! | 1 | `--renderer=cpu` / `--software-renderer` | `tiny-skia` | `renderer = tiny-skia reason=forced-cpu` | 三平台（CI 只用这条） |
+//! | 2 | `--renderer=gpu` 但本构建没编 wgpu | `tiny-skia` | `reason=gpu-not-compiled` + `；本构建未编入 wgpu` | 三平台（`--no-default-features`） |
+//! | 3 | `--renderer=gpu` 且编了 wgpu | `wgpu`，兜底 `tiny-skia` | `renderer = wgpu reason=forced-gpu 兜底=tiny-skia` | Windows / Linux 本机；macOS 需真机 |
+//! | 4 | `--renderer=auto` 但没编 wgpu | `tiny-skia` | `reason=auto-gpu-not-compiled` | 三平台（`--no-default-features`） |
+//! | 5 | `auto` + 枚举不到硬件适配器（只有 WARP / llvmpipe） | `tiny-skia`，兜底 `wgpu` | `reason=auto-no-hardware-adapter` | Windows 本机（软渲染 VM） |
+//! | 6 | `auto` + 有硬件适配器 | `wgpu`，兜底 `tiny-skia` | `reason=auto-hardware-adapter` | Windows 本机 **√**；macOS 需真机 |
+//! | 7 | 同上但 `ULL_PREFLIGHT=1` 预检失败 | `tiny-skia`，兜底 `wgpu` | `[gpu-preflight] FAILED stage=… error=…` + `reason=preflight-failed` | 三平台（可用 `WGPU_BACKEND=gl` 造） |
+//! | 8 | 任何一行选了 wgpu，但 iced 真初始化失败，且**交互启动**（无 `--screenshot`） | 具名错误 → **换一个进程**重开 `tiny-skia` | `[gpu] wgpu 初始化失败（具名）：…` → `[gpu] 降级 → tiny-skia（…换一个进程重开…）` → 子进程 `[probe] 本次是降级重开（ULL_GPU_FALLBACK=tiny-skia）` | **Windows 已验**（`WGPU_BACKEND=metal` 造）；macOS 需真机 |
+//! | 9 | 同上行，但**取证启动**（带 `--screenshot`，含 `--screen=gallery`） | 具名错误 → **不出图**，退出码 1 | `[gpu] wgpu 初始化失败（具名）：…` → `[gpu] 拒绝降级出图：本次是取证启动（--screenshot …）` | **Windows 已验**（同造法）；macOS 需真机 |
+//!
+//! **第 8/9 行的硬规则（M97 定）**：
+//!
+//! - 取证工具（`--screenshot`）宁可红着退出，也不能悄悄换一种后端继续出图。以前 gallery 在
+//!   wgpu 挂掉时会静默降级到 tiny-skia 照样落 PNG，而报告上写的是「GPU 渲染截图」——所有视觉
+//!   结论的可信度都被悄悄打折，而且从输出上看不出来。现在每张图的日志里都带
+//!   **实际**后端名（`[shot] … renderer=wgpu`），图能自证来源。
+//! - 交互启动保留安全网：真无 GPU / wgpu 起不来时降级到 tiny-skia，不崩。
+//!
+//! **降级为什么是换进程**：第一版写的是「打印错误 → 在本进程里再 `run()` 一次」，Windows 实测
+//! 直接 panic（`iced_winit-0.14.1/src/lib.rs:81` → `Create event loop: RecreationAttempt`）——
+//! winit 不允许一个进程建两次事件循环。所以安全网是 `respawn`：起一个子进程、只换
+//! `ICED_BACKEND` + `ULL_GPU_FALLBACK`，然后带着子进程的退出码退出。子进程看到
+//! `ULL_GPU_FALLBACK` 就跳过探测（否则会得到同一个结论、无限重开）。
+//!
+//! `ULL_PREFLIGHT` 开关的代价（**实测**，不是估计）：Windows RX 6600 XT / Vulkan 上
+//! `took=717ms`（首次要扫一遍 Vulkan loader），不可用时 `took=0ms`。打开它等于启动多 ~0.7 s，
+//! 所以默认关。它测不了 `create_surface`（那时还没有窗口），代替不了真跑一次，只用来「开窗前拿原因」。
+//! 注意：`ULL_PREFLIGHT=1` + 预检失败 + `--screenshot` 时**仍会**降级出图（`reason=preflight-failed`，
+//! 图上是 `renderer=tiny-skia`）——那条路径不是静默的，但图确实是 CPU 的，读图前先读日志。
+//!
+//! ## 怎么从日志判断「有没有静默降级」
+//!
+//! | 你看到 | 结论 |
+//! |---|---|
+//! | `[probe] renderer = wgpu` 且之后有 `[gpu] iced_wgpu: …Selected: AdapterInfo…` | **真在走 GPU**（这行是 iced_wgpu 自己在创建设备时打的，不是我们的猜测） |
+//! | `[gpu] wgpu 初始化失败（具名）：…` | wgpu 起不来，**原因就在这行里**；交互启动已换进程降级 CPU，取证启动已拒绝出图 |
+//! | `[gpu] 拒绝降级出图：…` | 这张图**没有**产出（取证启动 + wgpu 起不来）。想用 CPU 出图请显式 `--renderer=cpu` |
+//! | `[gpu] 降级 → tiny-skia（…换一个进程重开…）` | 交互启动降级了；后面必然跟一行 `[probe] 本次是降级重开` |
+//! | `[probe] renderer = tiny-skia reason=…`（`reason` 不是 `forced-cpu`） | 探测判定不该上 GPU，**原因在 `reason`** |
+//! | `[shot] … renderer=wgpu` / `renderer=tiny-skia` | 这张图**实际**由哪个后端产出（M97 之前这里打的是请求值 `auto`，等于没打） |
+//! | 只有 `[probe] renderer = …` 一行、没有 `[gpu] iced_wgpu:` 也没有取证行 | 那是 M97 之前的旧日志——**它从来没观测过实际后端**，不可采信 |
+//!
+//! ## 为什么不再用候选列表（M97 的根因订正）
+//!
+//! M97 之前：`auto` + 有硬件 → **不设** `ICED_BACKEND`，把决策交给 iced 的
+//! `fallback::Compositor`；那条路径里 wgpu 的失败被 `errors` 向量装起来、tiny-skia 一成功就整体丢弃
+//! （`iced_renderer-0.14.0/src/fallback.rs`，我们改不了）。日志只剩 `renderer = auto (wgpu -> tiny-skia)`
+//! ——而这行是 `probe.rs` 里按 `env == None` 打出来的**常量字符串**，跟实际后端无关。
+//! 于是 macOS M1 上「枚举到 Apple M1」与「最终是不是真在用 GPU」彻底脱钩：**看起来正常但可能在跑 CPU**。
+//!
+//! 现在的唯一判据：`ICED_BACKEND` 只写一项 ⇒ 能跑起来就必定是它；起不来就必然是
+//! `iced::Error::GraphicsCreationFailed` 里那串具名错误（哪个 backend、reason 是什么），
+//! 由 `app/boot.rs` 打印后决定「换进程降级」还是「拒绝出图」。
+//!
+//! ## 四段基建
+//!
+//! | 模块 | 作用 | 默认 |
+//! |---|---|---|
+//! | [`preflight`] | 在 iced 之前自己跑一遍 wgpu 的「实例→适配器→设备」，把失败原因拿在手里 | **关**（`ULL_PREFLIGHT=1` 打开；会重复创建实例/设备，别放默认路径） |
+//! | [`log_bridge`] | 把 `iced_wgpu` / `wgpu` 的 `log` 输出转到 stderr（`Selected: AdapterInfo{…}` 这行就是 GPU 生效的实证） | 开（`ULL_GPU_LOG=off` 可关） |
+//! | [`acceptance`] | **验收诊断（M98）**：`[env]` `[backend]` `[window]` `[font] chain` `[theme]` `[perf]` `[i18n]` `[caps]` 八类里本 crate 能观测的那部分，固定前缀、单行可 grep | 便宜的行恒开；贵的（适配器枚举）由 `ULL_ACCEPTANCE=1` 打开 |
+//!
+//! ### 「单项 ⇒ 没有静默回退」这条推理的依据（M98 r1 复审挖到源码层）
+//!
+//! `iced_renderer` 的 `fallback::Compositor` 拿到 `ICED_BACKEND` 后**仍会把每个候选依次拿去试
+//! wgpu 和 tiny-skia**，两个子渲染器收同一个 backend 字符串，所以「单项」本身并不阻止它去试
+//! tiny-skia。真正挡住它的是 `iced_tiny_skia` 的 `with_backend`：它只接受
+//! `None | "tiny-skia" | "tiny_skia"`，`Some("wgpu")` 直接返回 `GraphicsAdapterNotFound`。
+//! 于是 `ICED_BACKEND=wgpu` 这条路**不可能**落到 tiny-skia：起不来就两项都失败、返回
+//! `GraphicsCreationFailed`（判据表第 8/9 行接住它）。
+//!
+//! 这条依赖 iced 的实现细节，所以：① `iced = "=0.14.0"` 精确钉版本；② 验收脚本另有
+//! `[gpu] …Selected: AdapterInfo` 这条**不依赖本 crate 推理**的实证断言。升级 iced 时这两条都要重看。
+//!
+//! **本模块自己只回答「判据」**；「结果」由三处分别取证，别混：① `[backend] final=`（本 crate 的
+//! 起步结果，判据是单项 `ICED_BACKEND`）；② `[gpu] iced_wgpu: …Selected:`（iced 自己打的，
+//! GPU 真生效的实证）；③ `[shot] … renderer=`（这张图是哪个后端出的）。
+//!
+//! ## 真机验收（macOS Metal 路径 —— **需真机复核**，Windows 验不了这一段）
+//!
+//! 判据表第 3/6/8/9 行的 macOS 分支只能真机验。下面每段都可直接粘贴；`# 期望` 后面是**必须能在
+//! stderr 里 grep 到的原文**（M98 的验收包会直接把这些字符串编成断言）。
+//!
+//! ```bash
+//! # 0) 一次
+//! cargo build -p unlucky-app-iced
+//!
+//! # 1) 交互启动：这才是判「M1 到底有没有在用 GPU」的那次。看完关窗即可。
+//! ./target/debug/unlucky-launcher-iced --renderer=auto
+//! # 期望（这两行同一次运行里都要有）：
+//! #   [probe] renderer = wgpu reason=auto-hardware-adapter 兜底=tiny-skia
+//! #   [gpu] iced_wgpu::window::compositor: Selected: AdapterInfo {     name: "Apple M1",
+//! # 上面第二行里的 backend 必须是 Metal（同一行靠后）。
+//! # 若出现下面任一行 ⇒ 这次**不是** GPU，把那段原文（含上一行）发回来：
+//! #   [gpu] wgpu 初始化失败（具名）：
+//! #   [gpu] 降级 → tiny-skia
+//! #   [probe] 本次是降级重开（ULL_GPU_FALLBACK=tiny-skia）
+//!
+//! # 2) 开窗前拿原因（不建窗；多花 ~0.7 s）
+//! ULL_PREFLIGHT=1 ./target/debug/unlucky-launcher-iced --renderer=auto
+//! # 期望：[gpu-preflight] ok adapter="Apple M1" type=IntegratedGpu backend=Metal took=
+//!
+//! # 3) 取证出图（D30 通道；这一张图自证来源）
+//! ./target/debug/unlucky-launcher-iced --screen=gallery --screenshot /tmp/gallery.png
+//! # 期望（三行都该有）：
+//! #   [gpu] iced_wgpu::window::compositor: Selected: AdapterInfo {     name: "Apple M1",
+//! #   [shot] 1180x760 scale=1 -> /tmp/gallery.png
+//! #   [shot] screen=gallery theme=light renderer=wgpu
+//! # 若 wgpu 起不来 ⇒ 没有 /tmp/gallery.png、退出码 1、且打印 [gpu] 拒绝降级出图：
+//!
+//! # 4) 强制 CPU 对照（必须与 M97 之前逐字一致）
+//! ./target/debug/unlucky-launcher-iced --renderer=cpu --screenshot /tmp/cpu.png
+//! # 期望：
+//! #   [probe] adapters=0 hardware=false :: request=cpu -> ICED_BACKEND=tiny-skia
+//! #   [probe] renderer = tiny-skia reason=forced-cpu 兜底=none（候选表唯一项）
+//! #   [shot] screen=shell theme=light renderer=tiny-skia
+//!
+//! # 5) 负例：取证启动遇到 wgpu 不可用时必须红着退出（Mac 上用一个不存在的后端来造）
+//! WGPU_BACKEND=dx12 ./target/debug/unlucky-launcher-iced --screen=gallery --screenshot /tmp/bad.png
+//! # 期望：**没有** /tmp/bad.png、退出码 1、并且打印：
+//! #   [gpu] wgpu 初始化失败（具名）：multiple errors occurred: [GraphicsAdapterNotFound { backend: "wgpu", reason: RequestFailed("no adapter was found for the options requested:
+//! #   [gpu] 拒绝降级出图：本次是取证启动（--screenshot /tmp/bad.png），换后端出的图会撒谎。
+//! ```
+//!
+//! 第 5 段在 Windows 上已用同构的 `WGPU_BACKEND=metal` 验过（`metal support not compiled in`
+//! → 具名错误 → 拒绝出图 → exit 1）；macOS 上要确认打印的是 `dx12 support not compiled in` 那类
+//! wgpu 原话，而不是我们自己的话。
+
+pub mod acceptance;
+pub mod decision;
+pub mod log_bridge;
+pub mod preflight;
+
+pub use decision::{decide, demote_after_preflight, fallback_round, strict, Decision, Kind};
+
+/// 把 `iced::Error` 里的**具名**图形错误掏出来（`Display` 那句笼统的话不算原因）。
+///
+/// `iced::Error::GraphicsCreationFailed(inner)` 的 `Display` 只有
+/// 「the application graphics context could not be created」，**没有** `{0}`；
+/// 真正的 backend 名与 `Reason` 在内层 `graphics::Error` 里。所以这里同时给 Display 与 Debug。
+#[must_use]
+pub fn named_graphics_error(error: &iced::Error) -> Option<String> {
+    match error {
+        iced::Error::GraphicsCreationFailed(inner) => Some(format!("{inner}｜详情 {inner:?}")),
+        _ => None,
+    }
+}
+
+/// 跑一次 iced；起步后端起不来时把**具名**原因交给调用方（不在这里重试）。
+///
+/// ## 为什么不能在本进程里重试（M97 实测）
+///
+/// 第一版这里是「打印错误 + 再 `run()` 一次」。Windows 实测直接 panic：
+///
+/// ```text
+/// thread 'main' panicked at iced_winit-0.14.1/src/lib.rs:81:
+/// Create event loop: RecreationAttempt
+/// ```
+///
+/// winit 不允许一个进程建两次事件循环，所以**进程内重试在架构上就不成立**。
+/// 安全网因此改成**换一个进程重开**（`app/boot.rs` 的 `respawn`），
+/// 猜测的写法别再加回来。
+pub fn run_once(decision: Decision, attempt: impl FnOnce(Kind) -> iced::Result) -> iced::Result {
+    attempt(decision.primary)
+}
+
+/// 降级重开用的环境变量：子进程看到它就跳过探测、直接用它指向的后端（见 `app::boot::boot_probe`）。
+///
+/// ⚠️ 这是**防无限重开**的唯一闸门：子进程若不跳过探测，会算出同一个结论（auto + 有硬件 → wgpu）、
+/// 再失败、再 respawn，变成自杀式递归。子进程侧的判据在 `boot_probe` 的第一个分支。
+///
+/// 它也是**进程间**的交接约定，不是给用户设的开关（用户入口仍是 `--renderer`）。
+pub const FALLBACK_ENV: &str = "ULL_GPU_FALLBACK";
+
+/// 读 [`FALLBACK_ENV`]：本进程是不是「上一步失败后重开」的那一次。
+#[must_use]
+pub fn forced_fallback() -> Option<Kind> {
+    match std::env::var(FALLBACK_ENV).ok()?.trim() {
+        "tiny-skia" => Some(Kind::TinySkia),
+        "wgpu" => Some(Kind::Wgpu),
+        _ => None,
+    }
+}
+
+/// 打印**具名**失败原因（三行以内，`stage`/`backend`/`reason` 都可 grep）。
+///
+/// `iced::Error::GraphicsCreationFailed` 的 `Display` **不包含**内部错误
+/// （`#[error("the application graphics context could not be created")]`，没有 `{0}`），
+/// 所以这里必须显式把内层错误打出来，否则又变回「只知道失败，不知道为什么」。
+pub fn report_failure(backend: Kind, error: &(impl std::fmt::Display + std::fmt::Debug)) {
+    eprintln!("[gpu] {} 初始化失败（具名）：{error}", backend.name());
+    eprintln!("[gpu] 失败详情（具名）：{error:?}");
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::{Backend, Probe};
+
+    /// `run_once` **必须**把决策里的起步后端传下去。
+    ///
+    /// 抓得住：`run_once` 被改成传死值（例如恒 `Kind::Wgpu`）——那会让「强制 CPU」也去试 GPU。
+    /// 抓不住：真 iced 启动成功/失败（那条只能真跑，见判据表第 6/8/9 行的实测记录）。
+    #[test]
+    fn run_once_passes_the_decision_primary() {
+        for request in [Backend::Cpu, Backend::Gpu] {
+            let decision = decide(request, &Probe::default(), true);
+            let mut seen = None;
+            let result = run_once(decision, |kind| {
+                seen = Some(kind);
+                Ok(())
+            });
+            assert!(result.is_ok(), "闭包返回 Ok 时 run_once 必须原样返回");
+            assert_eq!(
+                seen,
+                Some(decision.primary),
+                "run_once 传给 iced 的后端必须是决策里的起步项"
+            );
+        }
+    }
+
+    /// `run_once` 只跑一次：失败也**不**在进程内重试（winit 只允许建一次事件循环）。
+    ///
+    /// 抓得住：谁把「进程内重试」加回 `run_once`（会 panic：`RecreationAttempt`）。
+    /// 抓不住：`respawn` 那条换进程的路（见 `app::boot::tests`）。
+    #[test]
+    fn run_once_never_retries_in_process() {
+        let mut calls = 0;
+        let _ = run_once(decide(Backend::Gpu, &Probe::default(), true), |_| {
+            calls += 1;
+            Err(iced::Error::WindowCreationFailed(Box::new(
+                std::io::Error::other("测试用"),
+            )))
+        });
+        assert_eq!(calls, 1, "进程内只许跑一次；重试只能换进程");
+    }
+}
diff --git a/crates/app-iced/src/renderer/preflight.rs b/crates/app-iced/src/renderer/preflight.rs
new file mode 100644
index 0000000..ff6b101
--- /dev/null
+++ b/crates/app-iced/src/renderer/preflight.rs
@@ -0,0 +1,244 @@
+//! wgpu 自检（判据表第 7 行）：在把控制权交给 iced **之前**自己跑一遍
+//! 「实例 → 适配器 → 设备」，把 wgpu 的具名错误拿在手里。
+//!
+//! ## 为什么默认关
+//!
+//! 它会**重复** iced 马上要做的活（再建一个实例、再要一个设备），macOS 上一个 Metal 设备
+//! 不是免费的；而且它测不了 `create_surface`（那时还没有窗口），所以它**代替不了**真跑一次。
+//! 它的价值只有一个：让「不上 GPU」这个结论在**开窗之前**就有原因，验收时不用盯着一个闪窗猜。
+//!
+//! 开关：`ULL_PREFLIGHT=1`（判据表里登记过，不是隐藏口子）。
+//!
+//! ## 它镜像的是谁
+//!
+//! 逐字对着 `iced_wgpu-0.14.0/src/window/compositor.rs` 的 `Compositor::request()` 抄的：
+//! `Backends::from_env().unwrap_or(all)`、`PowerPreference::from_env().unwrap_or(HighPerformance)`、
+//! `Limits { max_bind_groups: 2, max_non_sampler_bindings: 2048, ..default }`。
+//! 差一处都会让预检和真实路径说不同的话，那时预检就不是证据而是噪声了。
+
+/// 预检开关的环境变量名（`1` / `true` 打开）。
+pub const ENV_SWITCH: &str = "ULL_PREFLIGHT";
+
+/// 预检成功：拿到的适配器摘要。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Verdict {
+    /// 适配器名（`Apple M1` / `AMD Radeon RX 6600 XT` / `Microsoft Basic Render Driver`）。
+    pub adapter: String,
+    /// `device_type` 的字符串形式。
+    pub device_type: &'static str,
+    /// 命中哪个 wgpu 后端（`Metal` / `Vulkan` / `Dx12` / `Gl`）。
+    pub backend: String,
+}
+
+impl Verdict {
+    /// 一行日志。
+    #[must_use]
+    pub fn describe(&self) -> String {
+        format!(
+            "ok adapter={:?} type={} backend={}",
+            self.adapter, self.device_type, self.backend
+        )
+    }
+}
+
+/// 预检失败：卡在哪一步 + wgpu 自己的错误文本。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Failure {
+    /// 失败阶段（日志里 `stage=` 的取值）。
+    pub stage: &'static str,
+    /// wgpu 具名错误（`Display`，原样保留，不翻译成「失败」）。
+    pub detail: String,
+}
+
+impl Failure {
+    /// 一行日志（`stage=` 可直接 grep）。
+    #[must_use]
+    pub fn describe(&self) -> String {
+        format!("FAILED stage={} error={}", self.stage, self.detail)
+    }
+}
+
+/// 用户是否要求预检。
+#[must_use]
+pub fn requested() -> bool {
+    std::env::var(ENV_SWITCH).is_ok_and(|value| matches!(value.trim(), "1" | "true" | "yes" | "on"))
+}
+
+/// 按 `ULL_PREFLIGHT` 决定跑不跑；跑了就顺手把结论打进 stderr（带耗时，别让开关成本变成传说）。
+///
+/// 返回 `None` = 没要求预检（调用方按判据表 1~6 行原样走）。
+#[must_use]
+pub fn run_if_requested() -> Option<Result<Verdict, Failure>> {
+    if !requested() {
+        return None;
+    }
+
+    let started = std::time::Instant::now();
+    let verdict = run();
+    let took = started.elapsed().as_secs_f64() * 1000.0;
+    match &verdict {
+        Ok(ok) => eprintln!("[gpu-preflight] {} took={took:.0}ms", ok.describe()),
+        Err(failure) => {
+            eprintln!("[gpu-preflight] {} took={took:.0}ms", failure.describe());
+        }
+    }
+    Some(verdict)
+}
+
+#[cfg(feature = "gpu")]
+/// 真跑一遍 wgpu 初始化（不开窗、不建 surface）。
+///
+/// # Errors
+/// 无适配器 / 设备请求被拒时返回 [`Failure`]，`detail` 是 wgpu 的原话。
+pub fn run() -> Result<Verdict, Failure> {
+    use iced::wgpu::{
+        Backends, ExperimentalFeatures, Features, Instance, InstanceDescriptor, Limits,
+        MemoryHints, PowerPreference, RequestAdapterOptions, Trace,
+    };
+
+    let backends = Backends::from_env().unwrap_or_else(Backends::all);
+    let instance = Instance::new(&InstanceDescriptor {
+        backends,
+        ..Default::default()
+    });
+
+    let options = RequestAdapterOptions {
+        power_preference: PowerPreference::from_env().unwrap_or(PowerPreference::HighPerformance),
+        // 没有窗口，测不了 surface 兼容性——这一条只能靠真跑一次（判据表第 8 行）。
+        compatible_surface: None,
+        force_fallback_adapter: false,
+    };
+
+    let adapter = block_on(instance.request_adapter(&options)).map_err(|error| Failure {
+        stage: "request-adapter",
+        detail: format!("{options:?}: {error}"),
+    })?;
+
+    let info = adapter.get_info();
+    let device_type = device_type_name(info.device_type);
+
+    // iced 的 `request_device` 失败时不打日志、只把错误塞进 `RequestDeviceFailed`，
+    // 所以我们在这里先请求一次，把它的话原样抄下来。
+    let _ = block_on(adapter.request_device(&iced::wgpu::DeviceDescriptor {
+        label: Some("unlucky-launcher gpu preflight"),
+        required_features: Features::empty(),
+        required_limits: Limits {
+            max_bind_groups: 2,
+            max_non_sampler_bindings: 2048,
+            ..Limits::default()
+        },
+        memory_hints: MemoryHints::MemoryUsage,
+        trace: Trace::Off,
+        experimental_features: ExperimentalFeatures::disabled(),
+    }))
+    .map_err(|error| Failure {
+        stage: "request-device",
+        detail: error.to_string(),
+    })?;
+
+    Ok(Verdict {
+        adapter: info.name,
+        device_type,
+        backend: format!("{:?}", info.backend),
+    })
+}
+
+#[cfg(not(feature = "gpu"))]
+/// 本构建没编 wgpu：预检必然是「不可用」，但这不是错误——判据表第 4 行已经说明原因。
+///
+/// # Errors
+/// 恒返回 [`Failure`]（`stage=not-compiled`）。
+pub fn run() -> Result<Verdict, Failure> {
+    Err(Failure {
+        stage: "not-compiled",
+        detail: "本构建未编入 wgpu（--no-default-features）".to_owned(),
+    })
+}
+
+#[cfg(feature = "gpu")]
+/// `DeviceType` → 日志里的字符串（探测与预检**共用**这一处，别各写一份 `match`）。
+#[must_use]
+pub fn device_type_name(device_type: iced::wgpu::DeviceType) -> &'static str {
+    use iced::wgpu::DeviceType;
+    match device_type {
+        DeviceType::DiscreteGpu => "DiscreteGpu",
+        DeviceType::IntegratedGpu => "IntegratedGpu",
+        DeviceType::VirtualGpu => "VirtualGpu",
+        DeviceType::Cpu => "Cpu",
+        DeviceType::Other => "Other",
+    }
+}
+
+/// 把 wgpu 的 future 跑到底。
+///
+/// 只用 `std`：`Waker` 由 `std::task::Wake` 提供（安全 API），运行期负责 `park`。
+/// 不引入 futures 执行器——这里只有一个 future，而且它在 wgpu 的回调线程上唤醒。
+#[cfg(feature = "gpu")]
+fn block_on<F: std::future::Future>(future: F) -> F::Output {
+    use std::sync::Arc;
+    use std::task::{Context, Poll, Wake, Waker};
+
+    struct Unpark(std::thread::Thread);
+
+    impl Wake for Unpark {
+        fn wake(self: Arc<Self>) {
+            self.0.unpark();
+        }
+
+        fn wake_by_ref(self: &Arc<Self>) {
+            self.0.unpark();
+        }
+    }
+
+    let waker = Waker::from(Arc::new(Unpark(std::thread::current())));
+    let mut context = Context::from_waker(&waker);
+    let mut future = std::pin::pin!(future);
+
+    loop {
+        match future.as_mut().poll(&mut context) {
+            Poll::Ready(output) => return output,
+            Poll::Pending => std::thread::park(),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn failure_line_is_greppable() {
+        let failure = Failure {
+            stage: "request-device",
+            detail: "no device request succeeded".to_owned(),
+        };
+        let text = failure.describe();
+        assert!(
+            text.starts_with("FAILED stage=request-device error="),
+            "{text}"
+        );
+        assert!(text.contains("no device request succeeded"), "{text}");
+    }
+
+    #[test]
+    fn verdict_line_lists_the_three_facts() {
+        let verdict = Verdict {
+            adapter: "Apple M1".to_owned(),
+            device_type: "IntegratedGpu",
+            backend: "Metal".to_owned(),
+        };
+        let text = verdict.describe();
+        assert!(text.contains("adapter=\"Apple M1\""), "{text}");
+        assert!(text.contains("type=IntegratedGpu"), "{text}");
+        assert!(text.contains("backend=Metal"), "{text}");
+    }
+
+    /// 没编 wgpu 的构建：预检必须说清原因，而不是一句「失败」。
+    #[cfg(not(feature = "gpu"))]
+    #[test]
+    fn unbuilt_gpu_names_the_reason() {
+        let failure = run().unwrap_err();
+        assert_eq!(failure.stage, "not-compiled");
+        assert!(failure.detail.contains("wgpu"), "{}", failure.detail);
+    }
+}
diff --git a/crates/app-iced/src/shell/mod.rs b/crates/app-iced/src/shell/mod.rs
new file mode 100644
index 0000000..e726fc0
--- /dev/null
+++ b/crates/app-iced/src/shell/mod.rs
@@ -0,0 +1,357 @@
+//! 首屏骨架（**不做业务**）：自绘标题栏 + 左侧导航轨 + 内容区 + **右侧 AI 助手栏**（M104）。
+//!
+//! ## 与参考判据的对应（`research/12b-component-fidelity.md`）
+//!
+//! | 部件 | 参考 | 令牌落点 |
+//! |---|---|---|
+//! | 标题栏高度 | 16.2 桌面标题栏 **40**（登记偏离） | `LM.titlebar_height = 48`（M63 §1.4/R13 桌面档，令牌优先） |
+//! | 标题栏按钮 | 16.5 官方图标 **24** → 本项目 **20**（M86 项目偏离，用户点名「图标稍大」） | `icons::CAPTION_PX`（令牌 `TITLEBAR_CAPTION_ICON_PX`）+ `LM.titlebar_button_width = 46` |
+//! | 页头 | 16.1 官方 AppBar **64**；本项目 **56** | `LM.page_header_height = 56`（已有偏离登记） |
+//! | 卡片 | 3.x Outlined：**Medium(12)**、L0、`OutlineVariant` 1px、`SurfaceContainerLow` | `Component::OutlinedCard.spec()` + `STROKE_PX` |
+//! | 字级 | 16.4 标题 `TitleLarge`；卡片 `TitleMedium` / `BodySmall` | `Ui::style` / `Ui::emphasized` |
+//!
+//! 导航轨在 [`nav`] 子模块里（12b §5 的判据表也在那边）。
+//!
+//! 一屏只出现 4 档字号（22 / 16 / 14 / 12），且**没有实心 accent**（rubric K2：一屏最多一个实心
+//! Primary，骨架期一个都不要）。阴影只给浮层，骨架里没有浮层，所以**全屏零阴影**（rubric K3）。
+
+mod nav;
+
+/// AI 助手栏与 AI 独立页（M104）：**物理目录是 `crates/app-iced/src/pages/agent/`**，
+/// 用 `#[path]` 挂到外壳的命名空间。
+///
+/// 为什么是 `#[path]` 而不是在 `pages/mod.rs` 加一行 `mod agent;`：`pages/mod.rs` 是四条页面线
+/// 共用的声明文件（M104 的 scope 没给它），而右栏是**外壳的一部分**（它挂在任何页面右边）。
+/// 先例是 `app/mod.rs` 挂 `../components/mod.rs`。物理路径只有一份，逻辑名字有两个用途：
+/// 宿主（右栏）归外壳，视图（会话组件）归页面目录。
+#[path = "../pages/agent/mod.rs"]
+pub(crate) mod agent;
+
+// M114：轨底账户头像位的状态也归外壳（`NavItem` + `RailAccount` 一起导出）。
+pub use nav::{NavItem, RailAccount};
+
+use iced::widget::text::LineHeight;
+use iced::widget::{button, column, container, mouse_area, row, space, stack, text};
+use iced::{mouse, Alignment, Background, Border, Color, Element, Length, Padding, Pixels, Shadow};
+use iced::{window::Direction, Theme as IcedTheme};
+
+use unlucky_design::color::{Role, StateLayer};
+use unlucky_design::elevation::MaterialLayer;
+use unlucky_design::icons::IconKind;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use unlucky_i18n::Lang;
+
+use crate::app::Message;
+use crate::cli::ForcedState;
+use crate::icons;
+use crate::theme::Ui;
+
+/// 导航轨的一帧状态（M114）：主序列高亮项 + 轨底账户头像位。
+///
+/// 绑成一个结构体是为了让 [`view_with_account`] 的参数停在 8 个以内（clippy `too_many_arguments`），
+/// 也把「这两个值永远一起传」这件事写进类型：谁加导航项都绕不开轨底那一格。
+pub struct NavRail {
+    /// 高亮哪个主序列项（账户页是 `NavItem::Account`）
+    pub selected: NavItem,
+    /// 轨底头像位的状态（**按值持有**：它是每帧现算的，引用会让整棵树的生存期挂到临时值上）
+    pub account: nav::RailAccount,
+}
+
+/// 整棵树（**内容槽位版**）：外壳画标题栏 / 缩放热区 / 导航轨 / 右栏，中间那块交给调用方。
+///
+/// 产品页的唯一入口（M90 r2 / P1-1；M104 起多两样东西：右侧助手栏与拖拽取指针层；
+/// M114 起导航轨还会画轨底的账户头像位）。
+///
+/// 分工写死：
+///
+/// - 本模块负责：标题栏（拖动面 = **整条 48px 栏里从窗口左缘到第一个 caption** 的 `mouse_area`，
+///   没有单独的 8px 热区；三个 caption 键各 46×48）、东/南两条缩放热区（各 `Space::X1` = 4px）、
+///   导航轨、右栏、根容器底色；
+/// - 调用方负责：`content`（页面内容区）。它拿到的可用宽度是 `窗口宽 − rail 88 − 右栏`，
+///   而页面自己的 `layout::frame_metrics` 仍以**中栏可用宽**为输入（M104 的 `content_width`）。
+///
+/// 面板 α（D36 / M93）不从这里传：它是**表面色**的属性，唯一施加点是 `Ui::layer`
+/// （`crate::theme`）。外壳的根容器 / 标题栏 / 导航轨都走 `ui.layer(..)`，因此自动同源。
+///
+/// 产品页入口：**内容槽位 + 背景层 + 右栏 + 拖拽层 + 轨底账户头像位**。
+///
+/// `background` 由 `pages::appearance::layer` 产出（已与 `Message::Page` 映射过）；垫在 `stack!`
+/// 最底层，于是「面板 α < 1」时能真的看见它——这就是 D34 在像素上的落点。
+// 9 个形参：M104 的 `right`/`overlay`、M106 的 `lang`（导航轨标签按语言取词），
+// 加上 M114 把「高亮项 + 轨底账户态」捆成的 `NavRail`（捆它是为了少一个形参）。
+// 再拆就得动 `app/view.rs` / `account_page.rs` 的调用点，而那正是 M104/M105/M109 反复设锚点的
+// 地方——先就地 `allow`（主线原本也在这条上 `allow`），等下次合流再结构体化。
+#[allow(clippy::too_many_arguments)]
+pub fn view_with_account<'a>(
+    ui: &'a Ui,
+    nav_state: NavRail,
+    app_title: &'a str,
+    background: Option<Element<'a, Message>>,
+    content: Element<'a, Message>,
+    right: Option<Element<'a, Message>>,
+    overlay: Option<Element<'a, Message>>,
+    forced: Option<ForcedState>,
+    lang: Lang,
+) -> Element<'a, Message> {
+    // 右栏（M104）是 `row` 的**第三个兄弟**而不是叠层：它是布局宽度的一部分，压在上面会让
+    // 中栏以为自己还有那么宽（那就是任务里禁止的「溢出」）。它的宽度由 `agent::docked` 自己声明。
+    // M106：导航轨标签按当前界面语言取词（`lang` 一路从 `App::lang()` 递进来）。
+    // M114：`nav_state` 只影响轨底那一格，`right`/`overlay` 的语义一字未动。
+    let mut work = row![
+        nav::rail(ui, nav_state.selected, &nav_state.account, forced, lang),
+        content
+    ]
+    .width(Length::Fill)
+    .height(Length::Fill);
+    if let Some(right) = right {
+        work = work.push(right);
+    }
+
+    let work_area = column![titlebar(ui, app_title, forced), work]
+        .width(Length::Fill)
+        .height(Length::Fill);
+
+    window_frame(ui, background, work_area.into(), overlay)
+}
+
+/// 无边框窗口的「外壳壳子」：背景层 + 工作区 + 两条缩放热区 + 根容器底色。
+///
+/// ## 圆角生效时**不**内缩热区（M116）
+///
+/// Win11 / Server 2025 的 DWM 圆角是**合成层**的裁切：它只改「画出来的像素」，**不改窗口矩形**，
+/// 也不改命中测试（`WM_NCHITTEST` / 我们的 `mouse_area` 走的仍是整窗矩形）。所以：
+///
+/// - 标题栏拖动面、三个 caption 键（46×48）、东/南两条 4px 缩放热区**都不动**；
+/// - 角上那一小块（圆角弧以外的像素）在屏幕上看不见，但仍会响应——落在南侧热区里就是缩放、
+///   落在标题栏里就是拖动。两者都是无害的常规操作，比「内缩后角上出现 4px 死区」更好；
+/// - 反过来**不能**把根容器改成圆角容器来「配合」外框：那只会在四角露出底色方块
+///   （背景图/画布被裁成圆弧而外框仍然方），是自绘圆角的经典失败形态。
+///
+/// ⚠️ 上一条是本机**读不到**的部分：RDP 断连导致抓屏失效（见 `DevDocs/artifacts/m116/README.md`），
+/// 「角上那块到底响不响应」没有任何像素证据，只有「DWM 不改窗口矩形」这条 API 事实。
+/// 真机验收时请按 M116 报告里的清单补一条「在圆角窗口上拖边缩放仍命中」的手测。
+fn window_frame<'a>(
+    ui: &'a Ui,
+    background: Option<Element<'a, Message>>,
+    work_area: Element<'a, Message>,
+    overlay: Option<Element<'a, Message>>,
+) -> Element<'a, Message> {
+    // 无边框窗口没有系统缩放边框 → 自己给两条热区（东/南）。
+    // **必须叠层而不是兄弟列**：当兄弟列会吃掉 4px 布局宽（右留白变 28、caption 按钮离窗角 4px，
+    // 视觉复审 P3-1）。叠层容器自己铺满，再用 align 把 4px 热区贴到边上，布局宽保持 1180。
+    // 东侧热区从标题栏下方开始，避免吃掉三个 caption 按钮最右 4px 的点击区。
+    let thickness = ui.space(Space::X1);
+
+    let east = container(
+        column![
+            space::vertical().height(ui.metrics().titlebar_height),
+            resize_edge(
+                Direction::East,
+                (Length::Fixed(thickness), Length::Fill),
+                mouse::Interaction::ResizingHorizontally,
+            ),
+        ]
+        .height(Length::Fill),
+    )
+    .width(Length::Fill)
+    .height(Length::Fill)
+    .align_x(Alignment::End);
+
+    let south = container(resize_edge(
+        Direction::South,
+        (Length::Fill, Length::Fixed(thickness)),
+        mouse::Interaction::ResizingVertically,
+    ))
+    .width(Length::Fill)
+    .height(Length::Fill)
+    .align_y(Alignment::End);
+
+    // 背景在最底层（M93 / D34）。有背景层时**根容器不再盖实色画布**：否则那张不透明的
+    // `Canvas` 会把背景图整块挡住（r2 实测：panel α=1 时背景完全看不见）。
+    // 各面板（标题栏 / 导航轨 / 卡片 / 页头带）自己画底色，空隙里露出的就是背景图。
+    // 拖拽层（M104）压在最上面：它只在「按下右栗分隔条」期间存在，作用是把指针 x 变成拖拽消息
+    // （`mouse_area::on_move` 只在自己的边界内回报坐标，所以这一层必须铺满整窗）。
+    let has_background = background.is_some();
+    let shell = match (background, overlay) {
+        (Some(layer), Some(overlay)) => stack![layer, work_area, east, south, overlay],
+        (Some(layer), None) => stack![layer, work_area, east, south],
+        (None, Some(overlay)) => stack![work_area, east, south, overlay],
+        (None, None) => stack![work_area, east, south],
+    };
+
+    container(shell)
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .style(move |_theme| {
+            if has_background {
+                container::Style::default()
+            } else {
+                filled(ui.layer(MaterialLayer::Canvas))
+            }
+        })
+        .into()
+}
+
+/// 窗口缩放热区（透明；玻璃/底色由根容器提供）。
+///
+/// 拖动时调 `window::drag_resize(id, direction)`——Windows/X11 走 winit 原生实现，
+/// **macOS 返回 `NotSupported`**（M60 Q4），如实登记在交接文档里。
+fn resize_edge<'a>(
+    direction: Direction,
+    size: (Length, Length),
+    interaction: mouse::Interaction,
+) -> Element<'a, Message> {
+    let (width, height) = size;
+
+    mouse_area(container(space::horizontal()).width(width).height(height))
+        .interaction(interaction)
+        .on_press(Message::ResizeStart(direction))
+        .into()
+}
+
+// ---------------------------------------------------------------- 标题栏
+
+fn titlebar<'a>(ui: &'a Ui, title: &'a str, forced: Option<ForcedState>) -> Element<'a, Message> {
+    let metrics = ui.metrics();
+
+    // 拖动热区：从窗口左缘到第一个按钮（按钮自己不能被拖区吞掉，所以只包左侧一段）
+    let drag_area = mouse_area(
+        container(label(
+            ui,
+            TypeRole::LabelLarge,
+            true,
+            title,
+            ui.color(Role::OnSurface),
+        ))
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .align_y(Alignment::Center)
+        .padding(Padding::from([0.0, ui.space(Space::X4)])),
+    )
+    .on_press(Message::DragWindow);
+
+    let bar = row![
+        drag_area,
+        caption(ui, IconKind::Minimize, Message::Minimize, forced),
+        caption(ui, IconKind::Maximize, Message::ToggleMaximize, forced),
+        caption(ui, IconKind::Close, Message::Close, forced),
+    ]
+    .width(Length::Fill)
+    .height(metrics.titlebar_height)
+    .align_y(Alignment::Center);
+
+    container(bar)
+        .width(Length::Fill)
+        .height(metrics.titlebar_height)
+        .style(move |_theme| filled(ui.layer(MaterialLayer::Canvas)))
+        .into()
+}
+
+/// 标题栏按钮（自绘最小化/最大化/关闭）。
+///
+/// 图标必须**再包一层固定尺寸的容器**：iced 的 `button` 在 layout 里给内容 Fill 约束，
+/// 直接把 `svg(...).width(24)` 塞进 button，usvg 会按 Contain 撑满内区（实测渲染盒 46 → 视觉线宽
+/// 从 1.5 变 2.9，视觉复审 P2-2）。Container 尊重子元素的 Length，所以这层是「锁尺寸」用的。
+///
+/// **图标尺寸 = [`icons::CAPTION_PX`]（20，项目偏离；官方 24），容器 46×48 不动**（M86）：
+/// 用户原话是「保持其容器尺寸不变的前提下把图标改小些」，所以缩放只落在图标盒与 SVG 位图上，
+/// `metrics.titlebar_button_width` / `titlebar_height` 一个都不许跟着改。
+fn caption<'a>(
+    ui: &'a Ui,
+    kind: IconKind,
+    message: Message,
+    forced: Option<ForcedState>,
+) -> Element<'a, Message> {
+    let metrics = ui.metrics();
+    // 用 `center(Length::Fill)` 而不是只设 `width(20).height(20)`：后者会让容器缩到 20×20 并贴到
+    // button 内容的左上角（button 不居中「收缩后」的内容，r1 实测图标跑到 cell 左上 (left+11.5, 11.5)）；
+    // `center(Fill)` = 撑满按钮内容区 + **两轴**居中，字形仍是 20 盒、命中区仍是 46×48（Q21：
+    // 只设 `align_y` 不设 `align_x` 会让图标贴左）。
+    let icon = container(icons::view_at::<Message>(
+        kind,
+        ui.color(Role::OnSurfaceVariant),
+        icons::CAPTION_PX,
+    ))
+    .width(icons::CAPTION_PX)
+    .height(icons::CAPTION_PX)
+    .center(Length::Fill);
+
+    button(icon)
+        .width(metrics.titlebar_button_width)
+        .height(metrics.titlebar_height)
+        .padding(0)
+        .style(move |_theme: &IcedTheme, status| {
+            let background = match overridden(forced, status) {
+                button::Status::Hovered => Some(Background::Color(ui.state_over(
+                    StateLayer::Hover,
+                    Role::OnSurface,
+                    Role::Surface,
+                ))),
+                button::Status::Pressed => Some(Background::Color(ui.state_over(
+                    StateLayer::Pressed,
+                    Role::OnSurface,
+                    Role::Surface,
+                ))),
+                button::Status::Active | button::Status::Disabled => None,
+            };
+
+            button::Style {
+                background,
+                text_color: ui.color(Role::OnSurfaceVariant),
+                border: Border::default(),
+                shadow: Shadow::default(),
+                snap: true,
+            }
+        })
+        .on_press(message)
+        .into()
+}
+
+// ---------------------------------------------------------------- 小工具
+
+/// 一个文字元素：字号/行高/字重全部来自令牌排版档。
+pub(super) fn label<'a>(
+    ui: &'a Ui,
+    role: TypeRole,
+    emphasized: bool,
+    content: &'a str,
+    color: Color,
+) -> Element<'a, Message> {
+    let style = if emphasized {
+        ui.emphasized(role)
+    } else {
+        ui.style(role)
+    };
+
+    text(content)
+        .size(style.size_px)
+        .line_height(LineHeight::Absolute(Pixels(style.line_height_px)))
+        .font(ui.font_of(style))
+        .color(color)
+        .into()
+}
+
+/// 取证用的状态覆盖（`--force-state`）：只改画出来的状态，不动任何状态机。
+pub(super) fn overridden(forced: Option<ForcedState>, status: button::Status) -> button::Status {
+    match forced {
+        // `Rest` = 取证图的常态：**明确**画成 Active，把系统光标带来的 hover/pressed 压掉。
+        // 截图通道默认就是它（见 `cli::Options::parse` 的尾部），否则同一份代码会因指针位置出不同的图。
+        Some(ForcedState::Rest) => button::Status::Active,
+        Some(ForcedState::Hover) => button::Status::Hovered,
+        Some(ForcedState::Pressed) => button::Status::Pressed,
+        None => status,
+    }
+}
+
+pub(super) fn filled(color: Color) -> container::Style {
+    container::Style {
+        background: Some(Background::Color(color)),
+        ..container::Style::default()
+    }
+}
+
+#[cfg(test)]
+#[path = "tests.rs"]
+mod tests;
diff --git a/crates/app-iced/src/shell/nav.rs b/crates/app-iced/src/shell/nav.rs
new file mode 100644
index 0000000..3705950
--- /dev/null
+++ b/crates/app-iced/src/shell/nav.rs
@@ -0,0 +1,335 @@
+//! 左侧导航轨（M3 `NavigationRail`）。
+//!
+//! 判据来源 `research/12b-component-fidelity.md` §5：
+//!
+//! | 项 | 参考值 | 令牌落点 |
+//! |---|---|---|
+//! | 轨宽 | 5.1 官方 96（narrow 80）；本项目 **88** | [`nav_rail_width`]（`LayoutMetrics` 骨架值，详见该函数文档的 M69 迁移说明） |
+//! | 轨容器 | 5.3 形状 None / L0 / `Surface` | `MaterialLayer::Canvas` |
+//! | 选中指示器 | 5.4 **56×32**、圆角 full、`SecondaryContainer` | [`indicator_size`]（令牌推导） |
+//! | 图标 | 5.5 24px | `IconSize::Toolbar` |
+//! | 标签 | 5.5 `LabelMedium 12/16` | `TypeRole::LabelMedium` |
+//! | 颜色 | 5.6 选中图标 `OnSecondaryContainer` / 选中标签 `Secondary` / 未选中 `OnSurfaceVariant` | `Ui::color` |
+//! | 项间距 | 5.7 **4** | `LayoutMetrics::nav_item_gap` |
+
+use iced::widget::{button, column, container};
+use iced::{Alignment, Background, Border, Element, Length, Padding, Shadow, Theme as IcedTheme};
+
+use unlucky_design::color::{Role, StateLayer};
+use unlucky_design::elevation::MaterialLayer;
+use unlucky_design::icons::IconKind;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::{LayoutMetrics, Space};
+use unlucky_design::typography::TypeRole;
+use unlucky_i18n::{Key, Lang};
+
+mod account;
+
+pub use account::RailAccount;
+
+use account::account_item;
+
+use crate::app::Message;
+use crate::cli::ForcedState;
+use crate::icons;
+use crate::shell::{filled, label, overridden};
+use crate::theme::Ui;
+
+/// 导航占位项（任务要求 4~6 个；真正的页面由后续 mission 接管）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum NavItem {
+    /// 实例列表。
+    Instances,
+    /// 版本管理（显示名；变体名按用户令「只改显示层」不改，标识符改名后置）。
+    Download,
+    /// 日志。
+    Logs,
+    /// 设置。
+    Settings,
+    /// AI 助手。
+    Ai,
+    /// 账户页（**不进主序列**：入口是轨底的头像位，见 [`RailAccount`]）。
+    Account,
+}
+
+impl NavItem {
+    /// 全部**主序列**项（顺序 = 导航栏自上而下）。账户不在其中：它固定贴在轨底。
+    pub const ALL: [NavItem; 5] = [
+        NavItem::Instances,
+        NavItem::Download,
+        NavItem::Logs,
+        NavItem::Settings,
+        NavItem::Ai,
+    ];
+
+    /// 显示名的 key（M106 起走 catalog；两套目录都有词由 `catalog` 的完整性测试守）。
+    pub const fn label_key(self) -> Key {
+        match self {
+            NavItem::Instances => Key::NavInstances,
+            NavItem::Download => Key::NavDownload,
+            NavItem::Logs => Key::NavLogs,
+            NavItem::Settings => Key::NavSettings,
+            NavItem::Ai => Key::NavAi,
+            // M114：轨底头像位的可访问名（不在主序列里，但 `router` 的 `nav()` 会问到它）。
+            NavItem::Account => Key::AccountTitle,
+        }
+    }
+
+    /// 显示名（按当前界面语言）。
+    ///
+    /// 为什么带 `lang` 而不是读全局：这个函数要被单测与 harness 调，全局状态会让「同一份代码在
+    /// 不同语言下画什么」不可断言。
+    pub fn label(self, lang: Lang) -> &'static str {
+        lang.catalog().text(self.label_key())
+    }
+
+    /// 令牌图标。
+    pub const fn icon(self) -> IconKind {
+        match self {
+            NavItem::Instances => IconKind::Instances,
+            NavItem::Download => IconKind::Download,
+            NavItem::Logs => IconKind::Logs,
+            NavItem::Settings => IconKind::Settings,
+            NavItem::Ai => IconKind::Ai,
+            NavItem::Account => IconKind::User,
+        }
+    }
+}
+
+/// 整条导航轨。
+pub(super) fn rail<'a>(
+    ui: &'a Ui,
+    selected: NavItem,
+    account: &RailAccount,
+    forced: Option<ForcedState>,
+    lang: Lang,
+) -> Element<'a, Message> {
+    let metrics = ui.metrics();
+    let indicator = indicator_size(metrics);
+    let compact = account.compact;
+
+    let items = NavItem::ALL
+        .iter()
+        // `ALL` 本来就不含 `Account`（它固定在轨底），filter 只是把这条意图写明。
+        .filter(|item| **item != NavItem::Account)
+        .map(|item| rail_item(ui, *item, *item == selected, indicator, compact, forced, lang))
+        .collect::<Vec<_>>();
+
+    // 轨顶留白走 container padding，而不是「先塞一个 spacer 元素」：后者会被 column 的
+    // spacing（4）再加一档，实测变 28（视觉复审 P3-5）。
+    //
+    // 轨底色与其它面板同源（M93）：`ui.layer` 已含面板 α，导航轨是面板层的一部分。
+    //
+    // 账户头像位**固定贴在轨底**（M114）：主序列四项在上，中间一段 Fill 把头像顶到底部——
+    // 于是「账户」不是第 6 个导航项，轨的长度也不会随页数增长。
+    container(
+        column![
+            column(items).spacing(metrics.nav_item_gap),
+            iced::widget::space::vertical(),
+            account_item(ui, selected, account, indicator, forced),
+        ]
+        .height(Length::Fill),
+    )
+    .width(nav_rail_width(metrics))
+    .height(Length::Fill)
+    .padding(Padding::from([ui.space(Space::X6), 0.0]))
+    .style(move |_theme| filled(ui.layer(MaterialLayer::Canvas)))
+    .into()
+}
+
+fn rail_item<'a>(
+    ui: &'a Ui,
+    item: NavItem,
+    selected: bool,
+    indicator: (f32, f32),
+    compact: bool,
+    forced: Option<ForcedState>,
+    lang: Lang,
+) -> Element<'a, Message> {
+    let (indicator_width, indicator_height) = indicator;
+
+    let icon_color = if selected {
+        ui.color(Role::OnSecondaryContainer)
+    } else {
+        ui.color(Role::OnSurfaceVariant)
+    };
+    // 12b 5.6：选中标签用 `Secondary`，未选中 `OnSurfaceVariant`
+    let label_color = if selected {
+        ui.color(Role::Secondary)
+    } else {
+        ui.color(Role::OnSurfaceVariant)
+    };
+
+    // **不要用 `center_x/center_y(Fill)`**：那会把容器自己的 width/height 改成 Fill，
+    // 于是 56 被父级（button 宽 88）覆盖成 88、32 靠布局凑巧（视觉复审 P2-1）。
+    // 尺寸只认令牌推导值，居中交给父 column 的 `align_x`。
+    let pill = container(icons::view::<Message>(item.icon(), icon_color))
+        .width(indicator_width)
+        .height(indicator_height)
+        .align_x(Alignment::Center)
+        .align_y(Alignment::Center)
+        .style(move |_theme| container::Style {
+            background: selected.then(|| Background::Color(ui.color(Role::SecondaryContainer))),
+            border: Border {
+                radius: ui.radius(ShapeScale::Full, indicator_height),
+                ..Border::default()
+            },
+            ..container::Style::default()
+        });
+
+    let item_height = nav_item_height(ui, indicator_height);
+    let height = if compact {
+        indicator_height
+    } else {
+        item_height
+    };
+    // 列必须显式占满轨宽，否则它会 shrink 到 56，`align_x(Center)` 就变成空操作，
+    // 药丸会贴左缘（x=0..55 而不是 16..71）——r1 实测踩到的第二个坑。
+    let mut stack = column![pill]
+        .width(nav_rail_width(ui.metrics()))
+        .align_x(Alignment::Center)
+        .height(height);
+    if !compact {
+        // M114 的「窄高收成图标条」+ M106 的「按语言取词」并存。
+        stack = stack.push(label(
+            ui,
+            TypeRole::LabelMedium,
+            false,
+            item.label(lang),
+            label_color,
+        ));
+    }
+    stack = stack.spacing(ui.space(Space::X1));
+
+    button(stack)
+        .width(nav_rail_width(ui.metrics()))
+        .height(height)
+        .padding(0)
+        .style(move |_theme: &IcedTheme, status| {
+            let background = match overridden(forced, status) {
+                button::Status::Hovered if !selected => Some(Background::Color(ui.state_over(
+                    StateLayer::Hover,
+                    Role::OnSurface,
+                    Role::Surface,
+                ))),
+                button::Status::Pressed if !selected => Some(Background::Color(ui.state_over(
+                    StateLayer::Pressed,
+                    Role::OnSurface,
+                    Role::Surface,
+                ))),
+                _ => None,
+            };
+
+            button::Style {
+                background,
+                text_color: label_color,
+                border: Border::default(),
+                shadow: Shadow::default(),
+                snap: true,
+            }
+        })
+        .on_press(Message::Select(item))
+        .into()
+}
+
+/// 导航轨宽度（M69 起是令牌层的 `nav_rail_width`）。
+///
+/// M69（`141e9b1`）把 `LayoutMetrics` 的 nav 字段做了语义纠正：
+///
+/// | 旧 | 新 |
+/// |---|---|
+/// | `nav_expanded_width = 88` | **`nav_rail_width = 88`**（值不变，名字从「展开」改成「轨」） |
+/// | `nav_collapsed_width = 48` | 删除（48 连 56 宽的选中指示器都放不下） |
+/// | —（缺） | `nav_drawer_width = 240`（D33 的展开态抽屉，本 crate 未用） |
+///
+/// 三处调用点都走这里：将来令牌再改名，仍然只改这一行。
+fn nav_rail_width(metrics: LayoutMetrics) -> f32 {
+    metrics.nav_rail_width
+}
+
+/// 选中指示器尺寸（12b 5.4 参考 56×32），全部由令牌推导、不写死：
+///
+/// - 宽 = [`nav_rail_width`] − 2 × `Space::X4` = 88 − 32 = **56**（轨的左右内边距 16）
+/// - 高 = `control_height − Space::X2` = 40 − 8 = **32**（可见高度上下各让 4）
+pub fn indicator_size(metrics: LayoutMetrics) -> (f32, f32) {
+    (
+        nav_rail_width(metrics) - Space::X4.dp() * 2.0,
+        metrics.control_height - Space::X2.dp(),
+    )
+}
+
+/// 导航项高度 = 指示器 + 4 + 标签行高 = 32 + 4 + 16 = 52（`LM.nav_item_height` 是列表行节奏，
+/// 药丸 + 标签的轨项放不进 44，偏差登记在交接文档里）。
+pub fn nav_item_height(ui: &Ui, indicator_height: f32) -> f32 {
+    indicator_height + ui.space(Space::X1) + ui.style(TypeRole::LabelMedium).line_height_px
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use unlucky_design::color::SchemeFlavor;
+    use unlucky_design::typography::Platform;
+
+    use crate::theme::Families;
+
+    fn ui() -> Ui {
+        Ui::with_platform(
+            SchemeFlavor::Light,
+            Platform::Windows,
+            Families {
+                text: "Segoe UI",
+                display: "Segoe UI",
+                mono: "Consolas",
+            },
+        )
+    }
+
+    #[test]
+    fn indicator_matches_the_reference_56x32() {
+        let (width, height) = indicator_size(LayoutMetrics::DESKTOP);
+        assert_eq!((width, height), (56.0, 32.0), "12b 5.4 的参考值");
+    }
+
+    #[test]
+    fn nav_item_height_is_indicator_plus_gap_plus_label() {
+        let ui = ui();
+        let (_, indicator_height) = indicator_size(ui.metrics());
+        // 32 + 4 + 16
+        assert_eq!(nav_item_height(&ui, indicator_height), 52.0);
+    }
+
+    #[test]
+    fn every_nav_item_has_a_label_and_an_icon() {
+        assert!((4..=6).contains(&NavItem::ALL.len()));
+        for item in NavItem::ALL {
+            assert!(!item.label(Lang::En).is_empty(), "{item:?} 没有文案");
+            assert!(!item.icon().icon().path.is_empty(), "{item:?} 没有图标");
+        }
+    }
+
+    /// **M108**：导航栏上这一项叫 `Versions`（88px 轨放不下全名 `Version management`）。
+    ///
+    /// 文案本身走目录（M106 的 `label_key()` + `label(lang)`），这条只守**取值**与**宽度余量**：
+    ///
+    /// - **抓得住**：① 有人把 `Key::NavDownload` 的英文改回「下载」或塞回 18 字符的全名
+    ///   （88px 轨上会截断/换行，实测全名 ≈101px）；② 中文被「为了对称」砍成两个字。
+    /// - **抓不住**：真画出来的截断（那要出图，见 M108 报告里的产品通道与 pages_demo 图）；
+    ///   也抓不住 240 展开抽屉（那一档在产品里还不可达）。
+    #[test]
+    fn the_download_item_is_labelled_version_management() {
+        // 88px 轨的余量：中文 4 字 ≈48px、英文短名 ≈45px，都该有明显的余量
+        assert_eq!(NavItem::Download.label(Lang::En), "Versions");
+        assert_eq!(NavItem::Download.label(Lang::ZhCn), "版本管理");
+        for item in NavItem::ALL {
+            let label = item.label(Lang::En);
+            assert!(
+                !label.to_ascii_lowercase().contains("download"),
+                "{item:?} 的英文标签还在说下载：{label}"
+            );
+            assert!(
+                label.chars().count() <= 12,
+                "{item:?} 的标签太长，88px 的轨放不下：{label}"
+            );
+        }
+    }
+}
diff --git a/crates/app-iced/src/shell/nav/account.rs b/crates/app-iced/src/shell/nav/account.rs
new file mode 100644
index 0000000..f3fa2df
--- /dev/null
+++ b/crates/app-iced/src/shell/nav/account.rs
@@ -0,0 +1,220 @@
+//! 导航轨**底部账户头像位**（M114）：状态结构体 + 那个按钮。
+//!
+//! 为什么单独一个文件：`shell/nav.rs` 贴着 400 行硬线，而这块是 M114 新增的一整块
+//! （未登录/已登录两态、窄高收成图标条的判据、点击跳账户页）。
+
+use iced::widget::{button, column, container, text};
+use iced::{Alignment, Background, Border, Element, Length, Shadow, Theme as IcedTheme};
+
+use unlucky_design::color::{Role, StateLayer};
+use unlucky_design::icons::IconKind;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use crate::app::Message;
+use crate::cli::ForcedState;
+use crate::icons;
+use crate::shell::overridden;
+use crate::theme::Ui;
+
+use super::{nav_item_height, nav_rail_width, NavItem};
+
+/// 导航轨底部的**账户头像位**状态（M114）。
+///
+/// 为什么单独传而不是塞进 `NavItem`：它不是主序列里的第 6 项（那会让轨道越堆越长），
+/// 而是固定在**底部**的一个头像位；未登录/已登录两态要在**形状上**就不同（描边剪影 vs 首字母块）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RailAccount {
+    /// 是否已登录（至少有一个账户）
+    pub signed_in: bool,
+    /// 首字母块的字（已登录时有意义）
+    pub initial: String,
+    /// 账户名（已登录时作为标签；未登录时是 i18n 的「未登录」）
+    pub label: String,
+    /// 窄高度/窄宽下的图标条形态（隐藏文字标签，只留头像位）
+    pub compact: bool,
+}
+
+impl RailAccount {
+    /// 未登录态。
+    pub fn signed_out(label: impl Into<String>) -> Self {
+        Self {
+            signed_in: false,
+            initial: String::new(),
+            label: label.into(),
+            compact: false,
+        }
+    }
+
+    /// 已登录态。
+    pub fn signed_in(initial: impl Into<String>, label: impl Into<String>) -> Self {
+        Self {
+            signed_in: true,
+            initial: initial.into(),
+            label: label.into(),
+            compact: false,
+        }
+    }
+
+    /// 图标条形态（导航项太多/太窄时收起文字标签）。
+    #[must_use]
+    pub fn compact(mut self, compact: bool) -> Self {
+        self.compact = compact;
+        self
+    }
+}
+
+/// 轨底的账户头像位：未登录 = 描边剪影，已登录 = 首字母块（两态在**形状**上就不同）。
+pub(super) fn account_item<'a>(
+    ui: &'a Ui,
+    selected: NavItem,
+    account: &RailAccount,
+    indicator: (f32, f32),
+    forced: Option<ForcedState>,
+) -> Element<'a, Message> {
+    let (indicator_width, indicator_height) = indicator;
+    let active = selected == NavItem::Account;
+    let label_color = if active {
+        ui.color(Role::Secondary)
+    } else {
+        ui.color(Role::OnSurfaceVariant)
+    };
+
+    let avatar: Element<'a, Message> = if account.signed_in {
+        let style = ui.emphasized(TypeRole::TitleMedium);
+        container(
+            text(account.initial.clone())
+                .size(style.size_px)
+                .line_height(iced::widget::text::LineHeight::Absolute(iced::Pixels(
+                    style.line_height_px,
+                )))
+                .font(ui.font_of(style))
+                .color(ui.color(Role::OnSecondaryContainer)),
+        )
+        .width(Length::Fixed(avatar_size(ui, indicator_width)))
+        .height(Length::Fixed(avatar_size(ui, indicator_width)))
+        .align_x(Alignment::Center)
+        .align_y(Alignment::Center)
+        .style(move |_theme| container::Style {
+            background: Some(Background::Color(ui.color(Role::SecondaryContainer))),
+            border: Border {
+                radius: ui.radius(ShapeScale::Full, avatar_size(ui, indicator_width)),
+                ..Border::default()
+            },
+            ..container::Style::default()
+        })
+        .into()
+    } else {
+        container(icons::view::<Message>(
+            IconKind::User,
+            ui.color(Role::OnSurfaceVariant),
+        ))
+        .width(Length::Fixed(avatar_size(ui, indicator_width)))
+        .height(Length::Fixed(avatar_size(ui, indicator_width)))
+        .align_x(Alignment::Center)
+        .align_y(Alignment::Center)
+        .style(move |_theme| container::Style {
+            border: Border {
+                color: ui.color(Role::Outline),
+                width: 1.0,
+                radius: ui.radius(ShapeScale::Full, avatar_size(ui, indicator_width)),
+            },
+            ..container::Style::default()
+        })
+        .into()
+    };
+
+    let height = nav_item_height(ui, indicator_height);
+    let mut stack = column![avatar]
+        .spacing(ui.space(Space::X1))
+        .width(nav_rail_width(ui.metrics()))
+        .align_x(Alignment::Center);
+    if !account.compact {
+        // 用**拥有的**字符串画标签：`RailAccount` 是调用方临时算出来的状态，
+        // 借它的 `&str` 会让整棵树跟着那个临时值一起活（E0515）。
+        let style = ui.style(TypeRole::LabelSmall);
+        stack = stack.push(
+            text(account.label.clone())
+                .size(style.size_px)
+                .line_height(iced::widget::text::LineHeight::Absolute(iced::Pixels(
+                    style.line_height_px,
+                )))
+                .font(ui.font_of(style))
+                .color(label_color),
+        );
+    }
+
+    button(stack)
+        .width(nav_rail_width(ui.metrics()))
+        .height(height)
+        .padding(0)
+        .style(move |_theme: &IcedTheme, status| button::Style {
+            background: match overridden(forced, status) {
+                button::Status::Hovered if !active => Some(Background::Color(ui.state_over(
+                    StateLayer::Hover,
+                    Role::OnSurface,
+                    Role::Surface,
+                ))),
+                button::Status::Pressed if !active => Some(Background::Color(ui.state_over(
+                    StateLayer::Pressed,
+                    Role::OnSurface,
+                    Role::Surface,
+                ))),
+                _ => None,
+            },
+            text_color: label_color,
+            border: Border::default(),
+            shadow: Shadow::default(),
+            snap: true,
+        })
+        .on_press(Message::Select(NavItem::Account))
+        .into()
+}
+
+/// 头像位边长 = 指示器宽 − 16，但不超过 48（12b 里没有这个控件，按令牌栅格取整）。
+fn avatar_size(ui: &Ui, indicator_width: f32) -> f32 {
+    (indicator_width - Space::X4.dp()).min(ui.space(Space::X8) + Space::X2.dp())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn the_two_states_are_distinguishable() {
+        let out = RailAccount::signed_out("Not signed in");
+        assert!(!out.signed_in);
+        let on = RailAccount::signed_in("S", "Steve");
+        assert!(on.signed_in);
+        assert_eq!(on.initial, "S");
+        let compacted = on.clone().compact(true);
+        assert!(compacted.compact, "compact(true) 必须收成图标条");
+    }
+
+    #[test]
+    fn the_avatar_slot_fits_the_rail() {
+        use unlucky_design::color::SchemeFlavor;
+        use unlucky_design::typography::Platform;
+
+        use crate::theme::Families;
+
+        let ui = Ui::with_platform(
+            SchemeFlavor::Light,
+            Platform::Windows,
+            Families {
+                text: "Segoe UI",
+                display: "Segoe UI",
+                mono: "Consolas",
+            },
+        );
+        let width = super::super::indicator_size(ui.metrics()).0;
+        let size = avatar_size(&ui, width);
+        assert!(size > 0.0);
+        assert!(
+            size <= nav_rail_width(ui.metrics()),
+            "头像位不能比导航轨还宽（{size} > {}）",
+            nav_rail_width(ui.metrics())
+        );
+    }
+}
diff --git a/crates/app-iced/src/shell/tests.rs b/crates/app-iced/src/shell/tests.rs
new file mode 100644
index 0000000..0aa7b6d
--- /dev/null
+++ b/crates/app-iced/src/shell/tests.rs
@@ -0,0 +1,131 @@
+//! `shell` 的断言（M100 从 `shell/mod.rs` 搬出来：那边在 HEAD 上已经 **399 行**，
+//! 加一个 `ForcedState::Rest` 分支就必破 400 行硬线）。
+//!
+//! 搬移**不改一行断言**：只去掉了 `mod tests { }` 那一层缩进，外加 M100 新增的两条
+//! 取证不变量（见文件末尾）。
+//!
+//! 站位：本文件是 `crate::shell::tests`，`use super::*;` 就够。
+use super::*;
+use unlucky_design::color::SchemeFlavor;
+use unlucky_design::component_map::Component;
+use unlucky_design::typography::Platform;
+
+use crate::theme::Families;
+
+fn ui(flavor: SchemeFlavor) -> Ui {
+    Ui::with_platform(
+        flavor,
+        Platform::Windows,
+        Families {
+            text: "Segoe UI",
+            display: "Segoe UI",
+            mono: "Consolas",
+        },
+    )
+}
+
+#[test]
+fn a_screen_only_uses_four_text_sizes_at_most() {
+    let ui = ui(SchemeFlavor::Dark);
+    let card = Component::OutlinedCard.spec();
+    let sizes = [
+        ui.emphasized(TypeRole::TitleLarge).size_px,
+        ui.emphasized(TypeRole::LabelLarge).size_px,
+        ui.emphasized(card.text).size_px,
+        ui.style(card.support.unwrap_or(card.text)).size_px,
+        ui.style(TypeRole::LabelMedium).size_px,
+    ];
+    let mut unique = sizes.to_vec();
+    unique.sort_by(f32::total_cmp);
+    unique.dedup();
+    assert!(
+        unique.len() <= 4,
+        "rubric D4：一屏字号档 ≤4（实际 {} 档 {unique:?}）",
+        unique.len()
+    );
+    assert!(unique[0] >= 12.0, "最小档不下 12px（caption ≥11）");
+    assert!(unique[unique.len() - 1] <= 28.0, "列表页标题不得 >28px");
+}
+
+#[test]
+fn flavor_slug_is_stable_for_filenames() {
+    assert_eq!(crate::shot::flavor_slug(&ui(SchemeFlavor::Light)), "light");
+    assert_eq!(crate::shot::flavor_slug(&ui(SchemeFlavor::Dark)), "dark");
+}
+
+/// **交互模式不许被取证开关污染**（M100 的头号不变量）。
+///
+/// 抓得住：`overridden` 的 `None` 分支被改坏——例如把「跟控件自己的状态走」写成了固定
+/// `Active`/`Hovered`（那会让**用户窗口里所有按钮**不再反映 hover/pressed，是产品事故）。
+/// 抓不住：**默认值被顺手设成 `Some(Rest)`** 这类错误——`overridden(None, …)` 根本不会被调用，
+/// 本条照样绿；那一条由 `cli::tests::screenshots_default_to_the_rest_state` 抓（它断言
+/// 交互模式 `force_state == None`）。两条各守一半，别拿一条当另一条的证据。
+#[test]
+fn interactive_mode_still_hovers() {
+    use iced::widget::button::Status;
+
+    for status in [Status::Hovered, Status::Pressed, Status::Active] {
+        assert_eq!(
+            overridden(None, status),
+            status,
+            "交互模式（None）必须跟控件自己的状态走，不许替用户钉死"
+        );
+    }
+}
+
+/// **取证图的常态钉死**：`Rest` 把控件压成 `Active`，不管它自己的运行期状态是什么。
+///
+/// 抓得住：谁把 `Rest` 接成「保留现状」（那等于没钉：系统指针 hover 照样漏进图——M99 复审实测
+/// 连跑 8 次翻盘 1 次就是这里没钉住）。
+/// 抓不住：① 不经过 `overridden` 的控件（标题栏以外的裸 `iced::button`，例如设置页「外观」区）；
+/// ② 窗口到底还收不收鼠标事件（那是 harness 的 passthrough，看 `[caps] passthrough_ext=`）；
+/// ③ **`Rest` 与「真 Disabled」撞语义**：`components::buttons::assemble()` 把「无 `on_press`」的
+/// 按钮默认画成 Disabled，而 `Rest => Enabled` 会把它画成可用。当前零影响（8 处 `forced_state(`
+/// 调用点与 shell 的 caption / nav 全带消息），但将来若有人加一个**无消息**的按钮又被 `Rest` 罩住，
+/// 那张取证图会画出「一个本应禁用的按钮」而这条断言照绿。
+#[test]
+fn rest_suppresses_cursor_hover() {
+    use iced::widget::button::Status;
+
+    for status in [Status::Hovered, Status::Pressed, Status::Active] {
+        assert_eq!(
+            overridden(Some(ForcedState::Rest), status),
+            Status::Active,
+            "Rest 必须压掉 {status:?}"
+        );
+    }
+    // 明细态照旧（D30 的状态矩阵图靠它们）
+    assert_eq!(
+        overridden(Some(ForcedState::Hover), Status::Active),
+        Status::Hovered
+    );
+    assert_eq!(
+        overridden(Some(ForcedState::Pressed), Status::Active),
+        Status::Pressed
+    );
+}
+
+/// M86：标题栏 caption 图标缩到 20 后，**容器一个数都没动**（46×48），图标也还在框里。
+#[test]
+fn caption_icon_shrinks_without_touching_the_container() {
+    let ui = ui(SchemeFlavor::Light);
+    let metrics = ui.metrics();
+    let caption = icons::CAPTION_PX;
+    assert_eq!(metrics.titlebar_button_width, 46.0, "容器宽不许跟着图标改");
+    assert_eq!(metrics.titlebar_height, 48.0, "容器高不许跟着图标改");
+    assert!(
+        caption < metrics.titlebar_button_width,
+        "图标 {caption} 必须小于按钮宽 {}",
+        metrics.titlebar_button_width
+    );
+    assert!(
+        caption < metrics.titlebar_height,
+        "图标 {caption} 必须小于按钮高 {}",
+        metrics.titlebar_height
+    );
+    // 官方口径 24 仍在令牌里（`IconSize::Toolbar`），偏离只发生在 caption 这一个入口。
+    assert!(
+        caption < unlucky_design::icons::IconSize::Toolbar.px(),
+        "caption 图标必须小于官方 24（缩小是用户点名的）"
+    );
+}
diff --git a/crates/app-iced/src/shot/diff.rs b/crates/app-iced/src/shot/diff.rs
new file mode 100644
index 0000000..1136891
--- /dev/null
+++ b/crates/app-iced/src/shot/diff.rs
@@ -0,0 +1,352 @@
+//! 两图逐像素对比（GPU/CPU 几何一致性）与 ±N px 平移扫描。
+//!
+//! 拆成子模块只为「src 文件 ≤400 行」的门禁；对外通过 `shot::{compare, diff_files, Diff, Image}`
+//! 使用，调用方不用感知这层。
+
+use std::path::Path;
+
+/// 一张已解码的 RGBA 图。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Image {
+    /// RGBA8 字节（逐像素 4 字节）。
+    pub rgba: Vec<u8>,
+    /// 宽（px）。
+    pub width: u32,
+    /// 高（px）。
+    pub height: u32,
+}
+
+impl Image {
+    /// 读 PNG（只支持 PNG：本 crate 的 `image` 只开了 png 编码/解码）。
+    ///
+    /// # Errors
+    /// 读文件失败或解码失败时返回人话。
+    pub fn load(path: &Path) -> Result<Self, String> {
+        let reader = image::ImageReader::open(path)
+            .map_err(|error| format!("读图 {} 失败：{error}", path.display()))?
+            .with_guessed_format()
+            .map_err(|error| format!("判定 {} 的格式失败：{error}", path.display()))?;
+
+        let decoded = reader
+            .decode()
+            .map_err(|error| format!("解码 {} 失败：{error}", path.display()))?
+            .to_rgba8();
+
+        Ok(Self {
+            width: decoded.width(),
+            height: decoded.height(),
+            rgba: decoded.into_raw(),
+        })
+    }
+}
+
+/// 两图对比结果（GPU/CPU 一致性靠它给数字，不靠肉眼）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Diff {
+    /// 宽（px）。
+    pub width: u32,
+    /// 高（px）。
+    pub height: u32,
+    /// 有差异的像素数。
+    pub differing_pixels: usize,
+    /// 单通道最大差（0~255）。
+    pub max_channel_delta: u8,
+    /// 单通道平均差（0~255）。
+    pub mean_channel_delta: f64,
+    /// 平移扫描的最佳对齐（dx, dy）；不扫描时为 (0, 0)。
+    pub best_shift: (i32, i32),
+    /// 最佳对齐下的差异像素数（不扫描时等于 `differing_pixels`）。
+    pub best_differing_pixels: usize,
+}
+
+/// 逐像素对比两张尺寸相同的图。
+///
+/// # Errors
+/// 尺寸不同直接报错——**几何不一致不许静默通过**。
+pub fn compare(left: &Image, right: &Image) -> Result<Diff, String> {
+    if (left.width, left.height) != (right.width, right.height) {
+        return Err(format!(
+            "尺寸不同：{}x{} vs {}x{}",
+            left.width, left.height, right.width, right.height
+        ));
+    }
+
+    let pixel_count = left.rgba.len() / 4;
+    let mut differing = 0_usize;
+    let mut max_delta = 0_u8;
+    let mut sum_delta = 0_u64;
+
+    for index in 0..pixel_count {
+        let offset = index * 4;
+        let mut pixel_differs = false;
+
+        for channel in 0..4 {
+            let delta = left.rgba[offset + channel].abs_diff(right.rgba[offset + channel]);
+            if delta > 0 {
+                pixel_differs = true;
+                max_delta = max_delta.max(delta);
+                sum_delta += u64::from(delta);
+            }
+        }
+
+        if pixel_differs {
+            differing += 1;
+        }
+    }
+
+    Ok(Diff {
+        width: left.width,
+        height: left.height,
+        differing_pixels: differing,
+        max_channel_delta: max_delta,
+        mean_channel_delta: if pixel_count == 0 {
+            0.0
+        } else {
+            sum_delta as f64 / (pixel_count * 4) as f64
+        },
+        best_shift: (0, 0),
+        best_differing_pixels: differing,
+    })
+}
+
+/// ±`max_shift` px 的平移扫描：把 `right` 平移后再比，返回差异像素数最小的那一档。
+///
+/// 用途：D30 的「几何逐像素一致」除了看差异占比，还要证明**没有整体错位**——
+/// 如果 (0,0) 就是最优，说明差异只来自抗锯齿而不是位移/缩放。CI 不必再依赖 numpy。
+///
+/// 平移后越界的像素按「无法比较」处理，不计入差异（否则边缘会造成假阳性）。
+pub fn shift_scan(left: &Image, right: &Image, max_shift: i32) -> Result<Diff, String> {
+    let mut best = compare(left, right)?;
+    let max_shift = max_shift.unsigned_abs();
+
+    if (left.width, left.height) != (right.width, right.height) {
+        return Err("尺寸不同，无法做平移扫描".to_owned());
+    }
+
+    for dy in -(max_shift as i32)..=(max_shift as i32) {
+        for dx in -(max_shift as i32)..=(max_shift as i32) {
+            if (dx, dy) == (0, 0) {
+                continue;
+            }
+
+            let count = shifted_differing_pixels(left, right, dx, dy);
+            if count < best.best_differing_pixels {
+                best.best_differing_pixels = count;
+                best.best_shift = (dx, dy);
+            }
+        }
+    }
+
+    Ok(best)
+}
+
+/// 把 `right` 平移 `(dx, dy)` 后与 `left` 比较，返回差异像素数（越界不算）。
+fn shifted_differing_pixels(left: &Image, right: &Image, dx: i32, dy: i32) -> usize {
+    let width = left.width as i32;
+    let height = left.height as i32;
+    let mut differing = 0;
+
+    for y in 0..height {
+        let source_y = y - dy;
+        if !(0..height).contains(&source_y) {
+            continue;
+        }
+
+        for x in 0..width {
+            let source_x = x - dx;
+            if !(0..width).contains(&source_x) {
+                continue;
+            }
+
+            let left_offset = ((y * width + x) * 4) as usize;
+            let right_offset = ((source_y * width + source_x) * 4) as usize;
+
+            if left.rgba[left_offset..left_offset + 4] != right.rgba[right_offset..right_offset + 4]
+            {
+                differing += 1;
+            }
+        }
+    }
+
+    differing
+}
+
+impl Diff {
+    /// 完全一致（几何 + 颜色都一致）。
+    pub fn is_identical(&self) -> bool {
+        self.differing_pixels == 0
+    }
+
+    /// 一行日志。
+    pub fn describe(&self) -> String {
+        let total = (self.width as usize) * (self.height as usize);
+        let percent = if total == 0 {
+            0.0
+        } else {
+            self.differing_pixels as f64 * 100.0 / total as f64
+        };
+
+        format!(
+            "[diff] {}x{} differing={}/{} ({percent:.2}%) max_delta={} mean_delta={:.4} best_shift=({},{}) best_differing={}",
+            self.width,
+            self.height,
+            self.differing_pixels,
+            total,
+            self.max_channel_delta,
+            self.mean_channel_delta,
+            self.best_shift.0,
+            self.best_shift.1,
+            self.best_differing_pixels,
+        )
+    }
+}
+
+/// `--diff <left> <right>` 的实现：读两张 PNG、对比、打日志。
+///
+/// # Errors
+/// 任一图读不出来，或尺寸不同。
+pub fn diff_files(left: &Path, right: &Path) -> Result<Diff, String> {
+    diff_files_with_scan(left, right, 0)
+}
+
+/// 同 [`diff_files`]，但额外做 ±`max_shift` px 的平移扫描（`--diff-scan`）。
+///
+/// # Errors
+/// 任一图读不出来，或尺寸不同。
+pub fn diff_files_with_scan(left: &Path, right: &Path, max_shift: i32) -> Result<Diff, String> {
+    let left = Image::load(left)?;
+    let right = Image::load(right)?;
+
+    if max_shift == 0 {
+        compare(&left, &right)
+    } else {
+        shift_scan(&left, &right, max_shift)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::path::PathBuf;
+
+    use iced::window;
+
+    use super::*;
+    use crate::shot::{save, write_rgba};
+
+    fn temp_dir() -> PathBuf {
+        let dir = std::env::temp_dir().join("ull-app-iced-shot-tests");
+        std::fs::create_dir_all(&dir).expect("建临时目录");
+        dir
+    }
+
+    #[test]
+    fn identical_images_have_zero_diff() {
+        let image = Image {
+            rgba: vec![7_u8; 4 * 4],
+            width: 2,
+            height: 2,
+        };
+        let diff = compare(&image, &image).unwrap();
+        assert!(diff.is_identical());
+        assert_eq!(diff.max_channel_delta, 0);
+    }
+
+    #[test]
+    fn geometry_mismatch_is_an_error_not_a_silent_pass() {
+        let square = Image {
+            rgba: vec![0; 16],
+            width: 2,
+            height: 2,
+        };
+        let strip = Image {
+            rgba: vec![0; 16],
+            width: 4,
+            height: 1,
+        };
+        assert!(compare(&square, &strip).is_err());
+    }
+
+    #[test]
+    fn color_only_differences_are_counted_per_pixel() {
+        let left = Image {
+            rgba: vec![0, 0, 0, 255, 0, 0, 0, 255],
+            width: 2,
+            height: 1,
+        };
+        let right = Image {
+            rgba: vec![10, 0, 0, 255, 0, 0, 0, 255],
+            width: 2,
+            height: 1,
+        };
+        let diff = compare(&left, &right).unwrap();
+        assert_eq!(diff.differing_pixels, 1);
+        assert_eq!(diff.max_channel_delta, 10);
+        assert!(diff.describe().contains("differing=1/2"));
+    }
+
+    #[test]
+    fn png_roundtrip_through_disk() {
+        let path = temp_dir().join("roundtrip.png");
+        let bytes = vec![200_u8; 4 * 3 * 2];
+        write_rgba(&bytes, 3, 2, &path).unwrap();
+
+        let loaded = Image::load(&path).unwrap();
+        assert_eq!((loaded.width, loaded.height), (3, 2));
+        assert_eq!(loaded.rgba, bytes);
+
+        let diff = diff_files(&path, &path).unwrap();
+        assert!(diff.is_identical());
+    }
+
+    #[test]
+    fn shift_scan_finds_the_best_alignment() {
+        // 5x5 图，R 通道存唯一值；构造 right[y][x] = left[y+1][x+1]（即把左图向左上挪 1px），
+        // 于是「left 与 right 在 dy=1,dx=1 时逐像素相等」——扫描应该把 (1,1) 找出来。
+        let side = 5_i32;
+        let mut rgba = Vec::new();
+        for y in 0..side {
+            for x in 0..side {
+                rgba.extend([(y * side + x) as u8, 0, 0, 255]);
+            }
+        }
+        let left = Image {
+            rgba,
+            width: side as u32,
+            height: side as u32,
+        };
+
+        let mut moved = vec![255_u8; (side * side * 4) as usize];
+        for y in 0..side - 1 {
+            for x in 0..side - 1 {
+                let source = ((y + 1) * side + (x + 1)) as usize * 4;
+                let target = (y * side + x) as usize * 4;
+                moved[target..target + 4].copy_from_slice(&left.rgba[source..source + 4]);
+            }
+        }
+        let right = Image {
+            rgba: moved,
+            width: side as u32,
+            height: side as u32,
+        };
+
+        let diff = shift_scan(&left, &right, 2).unwrap();
+        assert_eq!(diff.best_shift, (1, 1), "应扫出 1px 的位移");
+        assert_eq!(diff.best_differing_pixels, 0, "对齐后应逐像素相等");
+        assert!(
+            diff.differing_pixels > 0,
+            "不对齐时应该有差异（否则这条测试没有信息量）"
+        );
+
+        // 同一张图：最佳对齐就是 (0,0)
+        let same = shift_scan(&left, &left, 2).unwrap();
+        assert_eq!(same.best_shift, (0, 0));
+        assert_eq!(same.best_differing_pixels, 0);
+    }
+
+    #[test]
+    fn wrong_byte_count_is_reported() {
+        let screenshot = window::Screenshot::new(vec![0_u8; 3], iced::Size::new(1, 1), 1.0);
+        let error = save(&screenshot, &temp_dir().join("unused.png")).unwrap_err();
+        assert!(error.contains("字节数对不上"), "{error}");
+    }
+}
diff --git a/crates/app-iced/src/shot/mod.rs b/crates/app-iced/src/shot/mod.rs
new file mode 100644
index 0000000..1e2bb32
--- /dev/null
+++ b/crates/app-iced/src/shot/mod.rs
@@ -0,0 +1,100 @@
+//! 截图通道（D30 验收用）：`iced::window::screenshot` 的真窗口出图 → PNG，以及两图逐像素对比。
+//!
+//! ## 为什么用真窗口而不是 `iced_test::Emulator`
+//!
+//! 任务书首选路径①：真开窗截图覆盖了标题栏/DPI/窗口管理的真实行为，离屏通道不覆盖
+//! （M60 §Q6 的边界说明）。本机与 Windows CI 都有交互会话，所以走路径①。
+//!
+//! ## 关键事实（M60 踩坑 Q3）
+//!
+//! `Screenshot` 的字节字段在 0.14 叫 **`rgba`**（0.13 是 `bytes`），`size` 是**物理像素**，
+//! 另带 `scale_factor`（换算逻辑坐标用）。落盘用 `image::save_buffer` + `ExtendedColorType::Rgba8`。
+//!
+//! ## 为什么自己带一个 diff
+//!
+//! D30 的硬项是「GPU 档与 CPU 档**几何逐像素一致**，只有颜色/材质不同」。CI 里不该假设有
+//! Python/PIL/ImageMagick，所以把「读两张 PNG → 数差异像素 → 给最大/平均通道差」做进本程序
+//! （`--diff a.png b.png`），复用同一个二进制。
+
+use std::path::{Path, PathBuf};
+
+use iced::window;
+
+use crate::theme;
+
+/// 把一帧截图写到 `path`（自动建父目录）。
+///
+/// # Errors
+/// 目录建不出来、PNG 编码失败、字节数与尺寸对不上时返回人话（截图通道要能一眼看出哪一步断）。
+pub fn save(screenshot: &window::Screenshot, path: &Path) -> Result<Summary, String> {
+    let width = screenshot.size.width;
+    let height = screenshot.size.height;
+    let bytes = screenshot.rgba.as_ref();
+
+    let expected = width as usize * height as usize * 4;
+    if bytes.len() != expected {
+        return Err(format!(
+            "截图字节数对不上：{width}x{height} 应该 {expected} B，实际 {} B",
+            bytes.len()
+        ));
+    }
+
+    write_rgba(bytes, width, height, path)?;
+
+    Ok(Summary {
+        width,
+        height,
+        scale_factor: screenshot.scale_factor,
+        path: path.to_path_buf(),
+    })
+}
+
+fn write_rgba(bytes: &[u8], width: u32, height: u32, path: &Path) -> Result<(), String> {
+    if let Some(parent) = path.parent() {
+        if !parent.as_os_str().is_empty() {
+            std::fs::create_dir_all(parent)
+                .map_err(|error| format!("建目录 {} 失败：{error}", parent.display()))?;
+        }
+    }
+
+    image::save_buffer(path, bytes, width, height, image::ExtendedColorType::Rgba8)
+        .map_err(|error| format!("写 PNG {} 失败：{error}", path.display()))
+}
+
+/// 一次截图的结果摘要（打日志与报告用）。
+#[derive(Debug, Clone, PartialEq)]
+pub struct Summary {
+    /// 物理宽（px）。
+    pub width: u32,
+    /// 物理高（px）。
+    pub height: u32,
+    /// 窗口缩放因子（100% DPI = 1.0）。
+    pub scale_factor: f32,
+    /// 落盘路径。
+    pub path: PathBuf,
+}
+
+impl Summary {
+    /// 一行日志。
+    pub fn describe(&self) -> String {
+        format!(
+            "[shot] {}x{} scale={} -> {}",
+            self.width,
+            self.height,
+            self.scale_factor,
+            self.path.display()
+        )
+    }
+}
+
+mod diff;
+
+pub use diff::{compare, diff_files, diff_files_with_scan, shift_scan, Diff, Image};
+
+/// 主题名 → 归档文件名片段（`visual-acceptance-protocol.md` §7 的命名）。
+pub fn flavor_slug(ui: &theme::Ui) -> &'static str {
+    match ui.flavor() {
+        unlucky_design::color::SchemeFlavor::Light => "light",
+        unlucky_design::color::SchemeFlavor::Dark => "dark",
+    }
+}
diff --git a/crates/app-iced/src/theme.rs b/crates/app-iced/src/theme.rs
new file mode 100644
index 0000000..4d512db
--- /dev/null
+++ b/crates/app-iced/src/theme.rs
@@ -0,0 +1,400 @@
+//! 令牌 → iced 类型（`Color` / `Font` / `Border` / `Radius` / `Theme`）。
+//!
+//! 本模块是**唯一**允许把 `unlucky-design` 的值翻成 iced 类型的地方（M61 §0）：组件层只调
+//! [`Ui`]，绝不出现色值/字号/半径/间距字面量（`tests/no_hardcoded_tokens.rs` 扫 `src/**`）。
+//!
+//! ## 为什么不用 `iced::theme::Base` 承载 49 个角色
+//!
+//! iced 的 `Palette` 只有 6 色，M3 有 49 个角色（M60 Q5）：真源是本模块的 [`Scheme`]，`Theme`
+//! 只用来「换名字」（名字变了 iced 才重算缓存），控件外观由各自的 `Style` 注入。
+//! `success`/`warning` 没有对应角色，按邻近语义映射（→ `Secondary` / `Tertiary`），不许读。
+
+use iced::border::Radius;
+use iced::theme::Palette;
+use iced::{Border, Color, Font, Theme};
+
+use unlucky_design::color::{Role, Scheme, SchemeFlavor, StateLayer};
+use unlucky_design::elevation::MaterialLayer;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::{LayoutMetrics, Space};
+use unlucky_design::typography::{FontFamily, Platform, TypeRole, TypeStyle, Weight};
+
+/// 全站描边宽度（rubric G7：1px）。令牌层的 `stroke::HAIRLINE` 是唯一定义点，这里只再导出。
+pub use unlucky_design::stroke::HAIRLINE as STROKE_PX;
+
+/// 已经解析到系统的字体族名（`&'static str` 才能塞进 `iced::Font`）。
+///
+/// 由 `fonts` 模块按令牌栈 + 系统字体库求值，本模块只消费。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Families {
+    /// 正文族（`FontFamily::Text` 栈里第一个装机可用的）。
+    pub text: &'static str,
+    /// 展示族（`FontFamily::Display`）。
+    pub display: &'static str,
+    /// 等宽族（`FontFamily::Mono`，日志/版本号用）。
+    pub mono: &'static str,
+}
+
+/// 令牌求值器：一个 `Ui` 对应一套主题（浅或深）。热切 = 重建 `Ui` 并整树重绘，
+/// 控件里不要缓存颜色。
+#[derive(Debug, Clone)]
+pub struct Ui {
+    scheme: Scheme,
+    platform: Platform,
+    metrics: LayoutMetrics,
+    families: Families,
+    /// 面板层不透明度（D36 / M93）：**唯一的 α 来源**，由 [`Ui::layer`] 统一施加。
+    panel_alpha: f32,
+}
+
+impl Ui {
+    /// 按平台（由 `cfg!` 决定）与令牌基线方案求值。
+    pub fn new(flavor: SchemeFlavor, families: Families) -> Self {
+        Self::with_platform(flavor, Platform::current(), families)
+    }
+
+    /// 显式指定平台（跨平台核对与测试用）。
+    pub fn with_platform(flavor: SchemeFlavor, platform: Platform, families: Families) -> Self {
+        Self {
+            scheme: Scheme::baseline(flavor),
+            platform,
+            metrics: LayoutMetrics::DESKTOP,
+            families,
+            panel_alpha: 1.0,
+        }
+    }
+
+    /// 当前深浅。
+    pub fn flavor(&self) -> SchemeFlavor {
+        self.scheme.flavor()
+    }
+
+    /// 用**已解析的方案**构造求值器（D38：背景图 / 壁纸取色 → 49 个角色换掉 baseline）。
+    ///
+    /// 追加式入口：`new` / `with_platform` 的行为一字未动（默认仍是 [`Scheme::baseline`]）；
+    /// 平台与骨架尺寸仍按当前环境求值——方案只带颜色。
+    pub fn from_scheme(scheme: Scheme, families: Families) -> Self {
+        Self {
+            scheme,
+            platform: Platform::current(),
+            metrics: LayoutMetrics::DESKTOP,
+            families,
+            panel_alpha: 1.0,
+        }
+    }
+
+    /// 当前平台（决定字体族与字重降级）。
+    pub fn platform(&self) -> Platform {
+        self.platform
+    }
+
+    /// 骨架尺寸（标题栏/导航/行高…）。
+    pub fn metrics(&self) -> LayoutMetrics {
+        self.metrics
+    }
+
+    /// 已解析的字体族名。
+    pub fn families(&self) -> Families {
+        self.families
+    }
+
+    /// 间距档位（4px 栅格）。
+    pub fn space(&self, space: Space) -> f32 {
+        space.dp()
+    }
+
+    /// M3 角色 → iced 颜色。
+    pub fn color(&self, role: Role) -> Color {
+        to_iced(self.scheme.get(role))
+    }
+
+    /// 材质层（Canvas/Card/Overlay）→ 容器色；**只有令牌允许半透明的层才乘面板 α**（M93 唯一来源）。
+    ///
+    /// α 乘在这里而不是调用点：所有表面色都从这里出去（根容器/标题栏/导航轨/页头带/卡片），
+    /// 一次同源、调用点无从「各自自乘」。Canvas 层恒不透明（r1 P2-2）：令牌
+    /// [`MaterialLayer::allows_translucency`] 写死 `Canvas => false`（窗口底），而三个窗口键与
+    /// 导航轨、页头带都取 Canvas——给它们乘 α 会让文字直接压在背景照片上（α=0.55 实测不可读）。
+    pub fn layer(&self, layer: MaterialLayer) -> Color {
+        let base = self.color(layer.surface_role());
+        if layer.allows_translucency() {
+            base.scale_alpha(self.panel_alpha)
+        } else {
+            base
+        }
+    }
+
+    /// 当前面板 α（CPU 档由 `app` 侧强制成 1.0）。
+    pub fn panel_alpha(&self) -> f32 {
+        self.panel_alpha
+    }
+
+    /// 换一个面板 α（只影响 `layer()` 出的表面色，不动角色色 `color()`；默认 `1.0`）。
+    #[must_use]
+    pub fn with_panel_alpha(mut self, alpha: f32) -> Self {
+        self.panel_alpha = if alpha.is_finite() {
+            alpha.clamp(0.0, 1.0)
+        } else {
+            1.0
+        };
+        self
+    }
+
+    /// 状态层叠在容器色上，返回**不透明**结果（D27：GPU/CPU 两档状态色逐像素一致；
+    /// 只有材质/面板才允许两档不同）。
+    pub fn state_over(&self, state: StateLayer, content: Role, container: Role) -> Color {
+        to_iced(state.over(self.scheme.get(content), self.scheme.get(container)))
+    }
+
+    /// 圆角（`side` = 控件在该轴上的边长，`Full` 要按它折算）。
+    pub fn radius(&self, shape: ShapeScale, side: f32) -> Radius {
+        Radius::new(shape.radius_px(side))
+    }
+
+    /// 固定档圆角。`ShapeScale::Full` 必须走 [`Ui::radius`]（它没有绝对值）。
+    pub fn radius_dp(&self, shape: ShapeScale) -> Radius {
+        debug_assert!(
+            !matches!(shape, ShapeScale::Full),
+            "Full 需要边长，请用 Ui::radius(shape, side)"
+        );
+        Radius::new(if matches!(shape, ShapeScale::Full) {
+            0.0
+        } else {
+            shape.dp()
+        })
+    }
+
+    /// 描边：`OutlineVariant` + [`STROKE_PX`]，圆角走刻度（固定档）。
+    pub fn outlined(&self, shape: ShapeScale) -> Border {
+        Border {
+            color: self.color(Role::OutlineVariant),
+            width: STROKE_PX,
+            radius: self.radius_dp(shape),
+        }
+    }
+
+    /// baseline 排版档。
+    pub fn style(&self, role: TypeRole) -> TypeStyle {
+        role.style()
+    }
+
+    /// Expressive 强调档（官方值：字重升到 500/700）。
+    pub fn emphasized(&self, role: TypeRole) -> TypeStyle {
+        role.emphasized()
+    }
+
+    /// 排版档 → iced 字体（族 + 字重）。
+    pub fn font_of(&self, style: TypeStyle) -> Font {
+        let family = match style.family {
+            FontFamily::Display => self.families.display,
+            FontFamily::Text => self.families.text,
+            FontFamily::Mono => self.families.mono,
+        };
+
+        Font {
+            family: iced::font::Family::Name(family),
+            weight: weight_of(style.weight),
+            ..Font::DEFAULT
+        }
+    }
+
+    /// baseline 档的字体。
+    pub fn font(&self, role: TypeRole) -> Font {
+        self.font_of(self.style(role))
+    }
+
+    /// 强调档的字体。
+    pub fn emphasized_font(&self, role: TypeRole) -> Font {
+        self.font_of(self.emphasized(role))
+    }
+
+    /// iced 的 6 色 `Palette`（只给 devtools；M3 的 49 角色在 [`Ui::color`]）。
+    pub fn palette(&self) -> Palette {
+        Palette {
+            background: self.color(Role::Surface),
+            text: self.color(Role::OnSurface),
+            primary: self.color(Role::Primary),
+            success: self.color(Role::Secondary),
+            warning: self.color(Role::Tertiary),
+            danger: self.color(Role::Error),
+        }
+    }
+
+    /// iced 主题对象：**名字带深浅**，切主题时 `Theme::name()` 变化会触发重算。
+    pub fn theme(&self) -> Theme {
+        Theme::custom(self.name(), self.palette())
+    }
+
+    /// `Theme::name()` 的取值（稳定字符串，改名要先在协作文档登记）。
+    pub fn name(&self) -> &'static str {
+        match self.flavor() {
+            SchemeFlavor::Light => "ull-m3-light",
+            SchemeFlavor::Dark => "ull-m3-dark",
+        }
+    }
+}
+
+/// 令牌色（8 bit sRGB）→ iced 的 sRGB 分量。
+pub fn to_iced(color: unlucky_design::color::Color) -> Color {
+    Color::from_rgba8(
+        color.r,
+        color.g,
+        color.b,
+        f32::from(color.a) / f32::from(u8::MAX),
+    )
+}
+
+/// 令牌字重 → iced 字重。
+pub fn weight_of(weight: Weight) -> iced::font::Weight {
+    match weight {
+        Weight::Regular => iced::font::Weight::Normal,
+        Weight::Medium => iced::font::Weight::Medium,
+        Weight::SemiBold => iced::font::Weight::Semibold,
+        Weight::Bold => iced::font::Weight::Bold,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const FAMILIES: Families = Families {
+        text: "Segoe UI Variable Text",
+        display: "Segoe UI Variable Display",
+        mono: "Cascadia Mono",
+    };
+
+    fn ui(flavor: SchemeFlavor) -> Ui {
+        Ui::with_platform(flavor, Platform::Windows, FAMILIES)
+    }
+
+    #[test]
+    fn theme_name_tracks_the_flavor() {
+        assert_eq!(ui(SchemeFlavor::Light).name(), "ull-m3-light");
+        assert_eq!(ui(SchemeFlavor::Dark).name(), "ull-m3-dark");
+        assert_ne!(
+            ui(SchemeFlavor::Light).theme().to_string(),
+            ui(SchemeFlavor::Dark).theme().to_string()
+        );
+    }
+
+    #[test]
+    fn canvas_card_overlay_follow_surface_containers() {
+        let ui = ui(SchemeFlavor::Light);
+        assert_eq!(ui.layer(MaterialLayer::Canvas), ui.color(Role::Surface));
+        assert_eq!(
+            ui.layer(MaterialLayer::Card),
+            ui.color(Role::SurfaceContainerLow)
+        );
+        assert_eq!(
+            ui.layer(MaterialLayer::Overlay),
+            ui.color(Role::SurfaceContainerHigh)
+        );
+    }
+
+    #[test]
+    fn radii_only_come_from_the_scale() {
+        let ui = ui(SchemeFlavor::Light);
+        // 卡片 Medium(12)：边长够大时就是 12
+        assert_eq!(ui.radius_dp(ShapeScale::Medium).top_left, 12.0);
+        assert_eq!(ui.radius_dp(ShapeScale::ExtraSmall).top_left, 4.0);
+        // 药丸 Full：按边长一半折算
+        assert_eq!(ui.radius(ShapeScale::Full, 32.0).top_left, 16.0);
+        // 不许超过边长一半
+        assert_eq!(ui.radius(ShapeScale::ExtraLarge, 20.0).top_left, 10.0);
+    }
+
+    #[test]
+    fn outlines_are_one_pixel_and_use_outline_variant() {
+        let ui = ui(SchemeFlavor::Light);
+        let border = ui.outlined(ShapeScale::Medium);
+        assert_eq!(border.width, STROKE_PX);
+        assert_eq!(border.width, 1.0, "rubric G7：全站 1px");
+        assert_eq!(border.color, ui.color(Role::OutlineVariant));
+        assert_eq!(border.radius.top_left, 12.0);
+    }
+
+    #[test]
+    fn emphasized_weights_are_the_official_ones() {
+        let ui = ui(SchemeFlavor::Light);
+        // title-small 的强调档是 700（官方 Emphasized）
+        assert_eq!(
+            ui.emphasized_font(TypeRole::TitleSmall).weight,
+            iced::font::Weight::Bold
+        );
+        // baseline 正文是 400
+        assert_eq!(
+            ui.font(TypeRole::BodyMedium).weight,
+            iced::font::Weight::Normal
+        );
+    }
+
+    #[test]
+    fn body_text_keeps_wcag_contrast_in_both_flavors() {
+        for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+            let scheme = Scheme::baseline(flavor);
+            assert!(
+                scheme.contrast(Role::OnSurface, Role::Surface) >= 4.5,
+                "{flavor:?} 的正文对比度不够"
+            );
+            assert!(
+                scheme.contrast(Role::OnSecondaryContainer, Role::SecondaryContainer) >= 4.5,
+                "{flavor:?} 的选中态药丸对比度不够"
+            );
+        }
+    }
+
+    #[test]
+    fn every_role_maps_to_an_iced_color() {
+        for role in Role::ALL {
+            let color = ui(SchemeFlavor::Dark).color(role);
+            assert!((0.0..=1.0).contains(&color.a), "{role:?} 的 alpha 越界");
+        }
+    }
+
+    #[test]
+    fn state_layers_are_opaque_so_cpu_and_gpu_match() {
+        let ui = ui(SchemeFlavor::Light);
+        let hovered = ui.state_over(StateLayer::Hover, Role::OnSurface, Role::Surface);
+        assert_eq!(hovered.a, 1.0, "状态层必须给出不透明结果");
+        assert_ne!(hovered, ui.color(Role::Surface));
+    }
+
+    /// D38：配色方案必须真的换色；默认构造逐字段等于 baseline（防回流的那一半）。
+    /// 抓不住：取色好不好看、设置页是否真切过去（后者由 app 侧日志举证）。
+    #[test]
+    fn a_resolved_scheme_replaces_the_baseline_colours() {
+        use unlucky_design::palette::{resolve_source, CardKey, ImageInput};
+
+        // 4×4 的纯红图：种子彩度远高于门槛，必然走到「背景图取色」这一级。
+        let pixels = [0xC0_u8, 0x20, 0x20, 0xFF].repeat(16);
+        let input = ImageInput::pixels(&pixels, 4, 4);
+        let (scheme, provenance) =
+            resolve_source(Some(input), None, Some(CardKey::Sky), SchemeFlavor::Light);
+        assert_eq!(
+            provenance.level,
+            unlucky_design::palette::Level::BackgroundImage,
+            "纯红图必须取色成功（否则本测试的输入不合格）"
+        );
+
+        let tinted = Ui::from_scheme(scheme, FAMILIES);
+        let baseline = ui(SchemeFlavor::Light);
+        assert_ne!(
+            tinted.color(Role::Primary),
+            baseline.color(Role::Primary),
+            "取色方案必须换掉 primary"
+        );
+        // 深浅仍跟着方案走（方案自带 flavor），不会把 Light 变成 Dark。
+        assert_eq!(tinted.flavor(), SchemeFlavor::Light);
+        assert_eq!(tinted.name(), baseline.name());
+
+        // 默认构造不变：`with_platform` 与 baseline 逐块相等。
+        let explicit = Ui::from_scheme(Scheme::baseline(SchemeFlavor::Light), FAMILIES);
+        for role in Role::ALL {
+            assert_eq!(
+                explicit.color(role),
+                baseline.color(role),
+                "{role:?}：不传 scheme 时默认行为必须与改动前一致"
+            );
+        }
+    }
+}
diff --git a/crates/app-iced/src/ui.rs b/crates/app-iced/src/ui.rs
new file mode 100644
index 0000000..8fbbf70
--- /dev/null
+++ b/crates/app-iced/src/ui.rs
@@ -0,0 +1,17 @@
+//! # 界面语言入口（M106 `I18NFOLLOW`）
+//!
+//! 用户报的原话：「我系统语言是中文 为什么打开软件是英文 并且设置页里面显示的是 English (System)」。
+//! 前半是**探测对了但没人用**（`app/view.rs` 里 `Lang::En` 写死），后半是一行硬编码假值。
+//!
+//! 这个模块就是那条缺失的入口：把「用户选的档位 + M92 的探测结论」变成一个值，交给
+//! `pages::Model.lang`（目录）与设置页语言行（档位回显）。
+//!
+//! | 文件 | 是什么 |
+//! |---|---|
+//! | [`lang`] | [`lang::LangState`]：启动判定（`ULL_LANG` > 配置 > 系统 locale > 英文）、切档、两行日志 |
+//!
+//! 为什么不叫 `theme::Ui` 的字段：`theme.rs` 是令牌求值器（颜色/字号/间距），语言不是令牌——
+//! 它是**运行期状态**，随设置变化，还要落盘。混进 `Ui` 会让「切主题」与「切语言」共享一条重建路径，
+//! 而它们该重建的东西根本不是同一批（一个重建 Style，一个重建视图模型）。
+
+pub mod lang;
diff --git a/crates/app-iced/src/ui/lang.rs b/crates/app-iced/src/ui/lang.rs
new file mode 100644
index 0000000..1ef28d5
--- /dev/null
+++ b/crates/app-iced/src/ui/lang.rs
@@ -0,0 +1,283 @@
+//! 界面语言的**入口层**（M106 `I18NFOLLOW`）：`Ui` 缺的那条语言入口就是这里。
+//!
+//! ## 它解决的是什么
+//!
+//! M92 把探测链做对了（启动日志里 `lang=zh-CN locale=zh-CN source=registry` 一直是对的），但
+//! **没人消费它**：`app/view.rs` 的 `model()` 里 `Lang::En` 是写死的，于是中文系统上开出来的是
+//! 全英文界面，设置页还写着 `English (System)`。本模块把「用户档位 + 探测结论」变成一个**值**
+//! （[`LangState`]），`App` 持有它、`view::model` 只认它，页面侧 `pages::Model.lang` 决定目录。
+//!
+//! ## 判定的四级优先级（[`LangState::boot`]）
+//!
+//! | 级 | 来源 | 什么时候用 |
+//! |---|---|---|
+//! | 1 | `ULL_LANG`（`zh_cn` / `en_us`） | 截图矩阵要**可复现地**换语言（D30） |
+//! | 2 | 配置里的 `ui.language` | 用户手选（设置页写入） |
+//! | 3 | 系统 locale（注册表 / 环境变量） | 跟随系统 |
+//! | 4 | 英文 | 一个源都没有 |
+//!
+//! **截图通道不读用户配置**（与 `appearance_prefs` 同一条 D30 纪律）：同一份代码在两台机器上出
+//! 不了同一张图，除非语言也由 `ULL_LANG` 显式给。
+//!
+//! ## 日志（两个下一个人要问的问题）
+//!
+//! 「探测错了吗」与「探测对了但没用上吗」在日志里必须分得开：
+//!
+//! ```text
+//! [i18n] choice=system lang=zh-CN locale=zh-CN source=registry effective=zh-CN
+//! [i18n] lang=zh-CN locale=zh-CN source=registry cjk=system:"Microsoft YaHei UI"
+//! ```
+//!
+//! 第一行是**档位 + 探测结论 + 最终生效语言**（[`LangState::log`]），第二行是中文策略（D28：
+//! 缺字体是信号，不许静默；[`LangState::log_cjk`]）。
+//!
+//! ## 诚实边界
+//!
+//! - **抓得住**：档位的选择顺序、坏值不猜、截图通道忽略配置、切档后生效语言跟着换；
+//! - **抓不住**：系统 locale 的真机行为（那在 [`crate::platform::locale::SystemLocale`]，Windows 上
+//!   真的去跑 `reg.exe`）；中文字体到底装没装（`fonts::cjk_for` 查 iced 的字体库）。
+
+use unlucky_i18n::lang::{Detection, EnvLocale};
+use unlucky_i18n::{Lang, LangChoice};
+use unlucky_presenter::settings_bridge::SettingsBridge;
+
+use crate::pages;
+use crate::platform::locale::SystemLocale;
+
+/// 截图通道的语言覆盖（D30 可复现）：`ULL_LANG=zh_cn` / `ULL_LANG=en_us`。
+///
+/// 为什么走环境变量而不是 `--lang`：`cli.rs` 不在本 mission 的 scope 里，而截图矩阵要能**只**改
+/// 一个环境变量就换语言（与 `ULL_APPEARANCE_*` 那批同一条做法）。
+pub(crate) const LANG_ENV: &str = "ULL_LANG";
+
+/// 设置页左侧分组的取证开关：`ULL_SETTINGS_GROUP=0` 直达 General（语言行在那里）。
+///
+/// 只影响 `--screenshot` 那一次进程（设置页出厂停在「外观」，而用户抱怨的语言行在 General 组；
+/// 出图必须能直达）。交互模式一律按用户点的那一组，所以这里拿 `screenshot` 当闸门。
+/// 为什么住在 `ui/lang.rs`：它与 [`LANG_ENV`] 是同一族「出图取证开关」，一起放在语言入口层，
+/// `App` 那边只留一行调用（`app/state.rs` 贴着 400 行硬线）。
+pub(crate) fn screenshot_settings_group(screenshot: bool) -> Option<usize> {
+    if !screenshot {
+        return None;
+    }
+    std::env::var("ULL_SETTINGS_GROUP")
+        .ok()
+        .and_then(|raw| raw.trim().parse::<usize>().ok())
+}
+
+/// 这一次进程的界面语言：用户选的档 + 探测出来的结论。
+///
+/// 不是 `Copy`：结论里带着探测到的原始 locale 字符串（`Detection.raw`），而它只在切档/启动时
+/// 构造一次——每帧问的是 [`LangState::lang`]（一个 `Copy` 的枚举），不是整份状态。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct LangState {
+    /// 用户意图（决定设置页画哪个按钮、落盘写不写 `ui.language`）。
+    choice: LangChoice,
+    /// 生效结论（决定用哪套目录；`describe()` 就是日志那一段）。
+    detection: Detection,
+}
+
+impl LangState {
+    /// 启动判定：`ULL_LANG` > 配置 `ui.language` > 系统 locale > 英文。
+    pub(crate) fn boot(bridge: &SettingsBridge, screenshot: bool) -> Self {
+        let forced = std::env::var(LANG_ENV)
+            .ok()
+            .filter(|value| !value.trim().is_empty());
+        let setting = bridge.load_ui_language();
+        Self::of(choose_choice(
+            forced.as_deref(),
+            setting.as_deref(),
+            screenshot,
+        ))
+    }
+
+    /// 换了档位之后的状态（重新走一遍 `resolve`，不保留旧结论）。
+    pub(crate) fn of(choice: LangChoice) -> Self {
+        Self {
+            choice,
+            detection: choice.resolve(&SystemLocale, &EnvLocale),
+        }
+    }
+
+    /// 当前档位。
+    pub(crate) fn choice(&self) -> LangChoice {
+        self.choice
+    }
+
+    /// 当前生效的语言（目录选择）。
+    pub(crate) fn lang(&self) -> Lang {
+        self.detection.lang
+    }
+
+    /// 设置页语言行要的两件（档位 + 生效语言）。
+    pub(crate) fn for_settings(&self) -> pages::Language {
+        pages::Language {
+            choice: self.choice,
+            effective: self.lang(),
+        }
+    }
+
+    /// 主日志行：档位 + 探测结论 + 最终生效语言。
+    pub(crate) fn log(&self) {
+        eprintln!(
+            "[i18n] choice={} {} effective={}",
+            self.choice.setting_value().unwrap_or("system"),
+            self.detection.describe(),
+            self.lang().tag()
+        );
+    }
+
+    /// 中文策略日志（D28）：缺字体是**信号**，不许静默。
+    ///
+    /// 为什么要单独一次（启动编排里已经打过一行 `[font]`）：那一拍按**系统 locale** 判，不知道用户
+    /// 手选了什么。英文系统上手动切中文时，只有这一行会变成 `cjk=needs-download(...)`——白块那条路
+    /// 就是靠它被看见的。
+    pub(crate) fn log_cjk(&self) {
+        let report = crate::fonts::cjk_for(self.choice.setting_value());
+        eprintln!("[i18n] {}", report.describe());
+        if matches!(
+            report.strategy,
+            unlucky_i18n::font::Strategy::NeedsDownload(_)
+        ) {
+            eprintln!(
+                "[i18n] 缺中文字体：界面会是中文但字形可能缺失（D28 的下载通道还是 PendingPin）"
+            );
+        }
+    }
+}
+
+/// 档位选择的**纯判据**（单测直接打这张表）。
+///
+/// **产品路径与验收路径共用它**：`LangState::boot` 用它决定目录，`renderer::acceptance::locale`
+/// 的 `[i18n]` 行也用它算结论——两行日志因此不可能再说出不同的语言（r4 复审 p2-1 就是
+/// 「两处各算一遍」造成的）。
+///
+/// | 输入 | 结果 |
+/// |---|---|
+/// | `ULL_LANG` 给了合法值 | 那一档（压过配置） |
+/// | 没给 + 配置写了 `zh_cn` / `en_us` | 那一档 |
+/// | 没给 + 配置没写（或写了坏值） | 跟随系统 |
+/// | **截图通道** + 配置写了值 | 跟随系统（除非 `ULL_LANG` 另给） |
+pub(crate) fn choose_choice(
+    forced: Option<&str>,
+    setting: Option<&str>,
+    screenshot: bool,
+) -> LangChoice {
+    let configured = if screenshot { None } else { setting };
+    LangChoice::from_setting(forced.or(configured))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// 档位判据的真值表（D28 第一级 + D30 的截图可复现）。
+    ///
+    /// 抓得住：①`ULL_LANG` 没压过配置（截图矩阵就换不了语言）；②截图通道读了用户配置（同一份代码
+    /// 在两台机器上出不同的图）；③坏值被猜成某种语言。
+    /// 抓不住：系统 locale 真探测成什么（那是 `SystemLocale` + `i18n::lang::resolve` 的事）。
+    #[test]
+    fn the_language_choice_is_ull_lang_then_config_then_system() {
+        let en = Some("en_us");
+        let zh = Some("zh_cn");
+
+        assert_eq!(choose_choice(None, None, false), LangChoice::System);
+        assert_eq!(
+            choose_choice(None, zh, false),
+            LangChoice::Fixed(Lang::ZhCn),
+            "配置里的手选要生效"
+        );
+        assert_eq!(
+            choose_choice(en, zh, false),
+            LangChoice::Fixed(Lang::En),
+            "ULL_LANG 压过配置（截图矩阵靠它换语言）"
+        );
+        assert_eq!(
+            choose_choice(zh, None, false),
+            LangChoice::Fixed(Lang::ZhCn)
+        );
+
+        assert_eq!(
+            choose_choice(None, zh, true),
+            LangChoice::System,
+            "截图通道必须忽略配置文件里的语言，否则同一份代码出不了同一张图"
+        );
+        assert_eq!(choose_choice(en, zh, true), LangChoice::Fixed(Lang::En));
+
+        for bogus in ["zh-CN", "system", "", "fr_fr"] {
+            assert_eq!(
+                choose_choice(Some(bogus), None, false),
+                LangChoice::System,
+                "{bogus}"
+            );
+        }
+    }
+
+    /// 「重启后保持所选语言」的**闭环证据**：真的落一个临时 `launcher.json`，再用**新开的** bridge
+    /// 读回来（等价于重启）。
+    ///
+    /// 抓得住：①「跟随系统」被读成 schema 默认值 `zh_cn`（英文机器一启动就是中文）；
+    /// ②「跟随系统」写了哨兵值（下次启动撒谎）；③删键时把别的键一起删了。
+    /// 抓不住：数据根解析（`SettingsBridge::open` 那条路）——这里用的是显式路径。
+    #[test]
+    fn the_choice_round_trips_through_the_config_file() {
+        use unlucky_presenter::settings_bridge::SettingsBridge;
+
+        let dir = std::env::temp_dir().join(format!("ull-m106-lang-{}", std::process::id()));
+        std::fs::create_dir_all(dir.join("config")).expect("临时目录");
+        let path = dir.join("config/launcher.json");
+        std::fs::write(
+            &path,
+            r#"{"appearance":{"theme_mode":"dark"},"custom":{"keep":true}}"#,
+        )
+        .expect("写配置");
+
+        // ① 没写过 = 跟随系统（不是默认值 zh_cn）
+        let bridge = SettingsBridge::with_path(&path);
+        assert_eq!(
+            bridge.load_ui_language(),
+            None,
+            "没写过这个键 = 跟随系统，不许回落成 schema 默认值"
+        );
+
+        // ② 手选落盘 → 新开的 bridge（= 重启）读回来
+        let mut bridge = SettingsBridge::with_path(&path);
+        assert!(bridge.persist_ui_language(Some("zh_cn")));
+        assert_eq!(
+            SettingsBridge::with_path(&path)
+                .load_ui_language()
+                .as_deref(),
+            Some("zh_cn"),
+            "重启后要保持所选语言"
+        );
+
+        // ③ 切回跟随系统 = 删键，且不许顺手删别的键
+        let mut bridge = SettingsBridge::with_path(&path);
+        assert!(bridge.persist_ui_language(None));
+        assert_eq!(SettingsBridge::with_path(&path).load_ui_language(), None);
+        let text = std::fs::read_to_string(&path).expect("读配置");
+        assert!(text.contains("theme_mode"), "外观键被删了：{text}");
+        assert!(text.contains("custom"), "用户手写的未知键被删了：{text}");
+
+        // ④ 已经是跟随系统时再点一次是幂等的
+        let mut bridge = SettingsBridge::with_path(&path);
+        assert!(!bridge.persist_ui_language(None), "没有键可删 = 没有落盘");
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    /// 手选档会赢过系统源，且 `raw`/`origin` 看得出来是手选的（日志可分诊）。
+    ///
+    /// 抓得住：`of()` 忘了重算（切档后结论还停在旧语言）、手选被系统源盖掉。
+    /// 抓不住：真机上系统源读到什么（`SystemLocale` 跑 `reg.exe`）。
+    #[test]
+    fn a_fixed_choice_wins_over_the_system_locale() {
+        let zh = LangState::of(LangChoice::Fixed(Lang::ZhCn));
+        assert_eq!(zh.lang(), Lang::ZhCn);
+        assert_eq!(zh.for_settings().effective, Lang::ZhCn);
+        assert_eq!(zh.for_settings().choice, LangChoice::Fixed(Lang::ZhCn));
+
+        let en = LangState::of(LangChoice::Fixed(Lang::En));
+        assert_eq!(en.lang(), Lang::En, "手选英文压过任何中文系统源");
+        assert_eq!(en.detection.origin, "setting");
+    }
+}
diff --git a/crates/app-iced/tests/no_hardcoded_tokens.rs b/crates/app-iced/tests/no_hardcoded_tokens.rs
new file mode 100644
index 0000000..1645758
--- /dev/null
+++ b/crates/app-iced/tests/no_hardcoded_tokens.rs
@@ -0,0 +1,400 @@
+//! 门禁：**组件层零硬编码**（色值 / 尺寸）与「不依赖 slint」。
+//!
+//! 这三条测试会扫本 crate 的 `src/**` 与 `Cargo.toml`，故意写得「宁可错杀」：
+//! 将来 reviewer 复跑 `cargo test -p unlucky-app-iced` 就能挡住「顺手写个 #RRGGBB」的提交。
+//!
+//! 判定口径（与 `component-fidelity-rubric.md` T1/T2、`visual-acceptance-protocol.md` §1 对齐）：
+//!
+//! - **色值字面量**：`#` + 6 位十六进制（且**至少含一个数字**，这样文档里的 `#RRGGBB` 占位不会被误杀）
+//!   或 `Color::from_rgb(0.1, …)` / `color!(0x…)` 这类带数值参数的构造。
+//! - **令牌优先**：唯一允许的是 `theme.rs`（适配层），且它也只做 `token → iced` 的搬运。
+//! - **尺寸字面量**：`shell.rs` 里 `.width(12.0)` / `.height(34)` / `.size(22)` 一律不许出现
+//!   （必须走 `LayoutMetrics` / `TypeStyle` / `Space`）。
+
+use std::path::{Path, PathBuf};
+
+/// 本 crate 根目录（编译期注入，换机器也成立）。
+fn manifest_dir() -> PathBuf {
+    PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+}
+
+/// 递归收集 `dir` 下的 `.rs` 文件。
+fn rust_files(dir: &Path, collected: &mut Vec<PathBuf>) {
+    let entries =
+        std::fs::read_dir(dir).unwrap_or_else(|error| panic!("读不动 {}：{error}", dir.display()));
+
+    for entry in entries {
+        let path = entry.expect("目录项读失败").path();
+        if path.is_dir() {
+            rust_files(&path, collected);
+        } else if path.extension().is_some_and(|ext| ext == "rs") {
+            collected.push(path);
+        }
+    }
+}
+
+fn sources() -> Vec<(PathBuf, String)> {
+    let mut files = Vec::new();
+    rust_files(&manifest_dir().join("src"), &mut files);
+
+    assert!(
+        files.len() >= 8,
+        "只扫到 {} 个源文件：扫描逻辑坏了，这条门禁等于没跑",
+        files.len()
+    );
+
+    files
+        .into_iter()
+        .map(|path| {
+            let text = std::fs::read_to_string(&path)
+                .unwrap_or_else(|error| panic!("读不动 {}：{error}", path.display()));
+            (path, text)
+        })
+        .collect()
+}
+
+/// `#RRGGBB` / `#AARRGGBB` 形式的色值字面量（至少含一个数字，避开 `#RRGGBB` 这种占位写法）。
+fn hex_color_at(bytes: &[u8], start: usize) -> Option<&str> {
+    let digits = bytes.get(start + 1..start + 7)?;
+    let all_hex = digits
+        .iter()
+        .all(|byte| byte.is_ascii_hexdigit() && !byte.is_ascii_whitespace());
+    let has_number = digits.iter().any(u8::is_ascii_digit);
+
+    if all_hex && has_number {
+        // 后面不能再跟着十六进制字符（否则是更长的 token，不是 6 位色值）
+        let next = bytes.get(start + 7).copied();
+        if next.is_none_or(|byte| !byte.is_ascii_hexdigit()) {
+            return Some("hex 色值字面量（#RRGGBB）");
+        }
+    }
+
+    None
+}
+
+/// 带数值参数的取色构造（`Color::from_rgb(0.1, …)`、`Color::from_rgb8(103, 80, 164)`、`color!(0x12, …)`）。
+///
+/// **子串匹配要注意前后缀**：`from_rgb(` 匹配不到 `from_rgb8(`，所以 8 bit 那个必须单独列出来
+/// （reviewer 造样就是这么绕过去的）。
+const NUMERIC_COLOR_CALLS: [&str; 8] = [
+    "Color::from_rgb(",
+    "Color::from_rgb8(",
+    "Color::from_rgba(",
+    "Color::from_rgba8(",
+    "Color::from_hex(",
+    "Color::rgba(",
+    "Color::rgb8(",
+    "color!(",
+];
+
+/// 取色构造后面是不是跟着数值字面量（允许 `Color::from_rgba8(color.r, …)` 这类搬运）。
+fn numeric_color_call(text: &str) -> Option<&'static str> {
+    for pattern in NUMERIC_COLOR_CALLS {
+        let mut from = 0;
+        while let Some(found) = text[from..].find(pattern) {
+            let after = from + found + pattern.len();
+            let next = text[after..].trim_start().chars().next();
+
+            // 参数以数字或 `0x`/`#` 开头才算字面量；`Color::from_rgba8(color.r, …)` 是搬运，放行。
+            if next.is_some_and(|ch| ch.is_ascii_digit() || ch == '#') {
+                return Some(pattern);
+            }
+
+            from = after;
+        }
+    }
+
+    None
+}
+
+/// 结构体字面量取色：`Color { r: 0.4, g: 0.3, b: 0.6, a: 1.0 }`。
+///
+/// 判据：`Color {` 之后 64 个字符内同时出现 `r:` 与 `g:` 且有数字（`Color { a: 0.0, .. }` 这种
+/// 只改 alpha 的写法不会命中，因为它没有 `r:`）。
+fn color_struct_literal(text: &str) -> bool {
+    let mut from = 0;
+    while let Some(found) = text[from..].find("Color {") {
+        let after = from + found + "Color {".len();
+        let window: String = text[after..].chars().take(64).collect();
+        let has_channels = window.contains("r:") && window.contains("g:");
+        let has_number = window.chars().any(|ch| ch.is_ascii_digit());
+
+        if has_channels && has_number {
+            return true;
+        }
+
+        from = after;
+    }
+
+    false
+}
+
+#[test]
+fn no_hardcoded_colors_in_sources() {
+    let mut offenders = Vec::new();
+
+    for (path, text) in sources() {
+        for (index, line) in text.lines().enumerate() {
+            let bytes = line.as_bytes();
+            let mut position = 0;
+
+            while let Some(found) = line[position..].find('#') {
+                let at = position + found;
+                if let Some(kind) = hex_color_at(bytes, at) {
+                    offenders.push(format!(
+                        "{}:{} {line:?} -> {kind}",
+                        path.display(),
+                        index + 1
+                    ));
+                }
+                position = at + 1;
+            }
+
+            if let Some(pattern) = numeric_color_call(line) {
+                offenders.push(format!(
+                    "{}:{} {line:?} -> {pattern}",
+                    path.display(),
+                    index + 1
+                ));
+            }
+
+            if color_struct_literal(line) {
+                offenders.push(format!(
+                    "{}:{} {line:?} -> Color {{ r: … }} 结构体字面量",
+                    path.display(),
+                    index + 1
+                ));
+            }
+        }
+    }
+
+    assert!(
+        offenders.is_empty(),
+        "组件层不许出现色值字面量（一律走 unlucky_design 的 Role）：\n{}",
+        offenders.join("\n")
+    );
+}
+
+/// 判断某个布局调用后面是不是直接跟了尺寸字面量；`0`（= 无内边距）放行。
+///
+/// iced 里尺寸经常被包一层：`.width(Length::Fixed(123.0))`、`.padding(Padding::from([12.0, 8.0]))`、
+/// `.size(Size::new(10.0, 10.0))` —— 所以遇到这些包装要**往里剥一层**再判。
+fn size_literal(argument: &str) -> Option<String> {
+    let mut rest = argument.trim_start();
+
+    for wrapper in ["Length::Fixed(", "Padding::from(", "Size::new("] {
+        if let Some(after) = rest.strip_prefix(wrapper) {
+            rest = after.trim_start().trim_start_matches(['[', '(']);
+            break;
+        }
+    }
+
+    let number: String = rest
+        .trim_start()
+        .chars()
+        .take_while(|ch| ch.is_ascii_digit() || *ch == '.')
+        .collect();
+
+    if number.is_empty() || number.trim_end_matches('.').parse::<f64>() == Ok(0.0) {
+        return None;
+    }
+
+    Some(number)
+}
+
+/// 尺寸字面量守门：`src/shell` + `src/pages` 都扫。
+///
+/// P2-3（M84 复审）：原先只扫 `shell`，新增的 `pages/` **没被覆盖**（页面里写 `.width(24)` 没人发现）。
+/// `pages/layout.rs` 允许有布局常量（它是布局系统的定义点），控件调用点上不许再出现字面量。
+#[test]
+fn layout_sources_take_every_size_from_tokens() {
+    let mut files = Vec::new();
+    // P3-3（M90 r2）：`app` 是 M90 新拆出来的模块，也是唯一没被这条守门看过的控件树。
+    for dir in ["shell", "pages", "app"] {
+        rust_files(&manifest_dir().join("src").join(dir), &mut files);
+    }
+    assert!(
+        files.len() >= 20,
+        "shell + pages + app 至少 20 个文件，实际扫到 {}：扫描逻辑坏了，这条门禁等于没跑",
+        files.len()
+    );
+
+    let mut offenders = Vec::new();
+
+    for path in files {
+        let text = std::fs::read_to_string(&path).expect("读布局源文件");
+
+        for (index, line) in text.lines().enumerate() {
+            // 文档注释是散文不是代码：里面写 `.width(24)` 是在解释坑，不该判违规
+            if line.trim_start().starts_with("//") {
+                continue;
+            }
+
+            for pattern in [".width(", ".height(", ".size(", ".spacing(", ".padding("] {
+                let mut from = 0;
+                while let Some(found) = line[from..].find(pattern) {
+                    let after = from + found + pattern.len();
+                    if let Some(number) = size_literal(&line[after..]) {
+                        offenders.push(format!(
+                            "{}:{} {line:?} -> {pattern} 后面直接写了数字 {number}",
+                            path.display(),
+                            index + 1
+                        ));
+                    }
+                    from = after;
+                }
+            }
+        }
+    }
+
+    assert!(
+        offenders.is_empty(),
+        "骨架尺寸必须来自 LayoutMetrics / TypeStyle / Space：\n{}",
+        offenders.join("\n")
+    );
+}
+
+/// 图标语汇守门（视觉复审 P2-3）：`pages/` 里只用**描边**字形。
+///
+/// 令牌层把 `Play` / `Stop` / `More` 定义成填充字形，其余是描边；页面骨架里混用会让同屏线宽
+/// 语汇打架。将来要支持「主操作允许实心图标」，应由 `components/` 统一定义并只留一处。
+#[test]
+fn pages_use_only_stroked_icons() {
+    const FILLED: [&str; 3] = ["IconKind::Play", "IconKind::Stop", "IconKind::More"];
+
+    let mut files = Vec::new();
+    rust_files(&manifest_dir().join("src").join("pages"), &mut files);
+    assert!(
+        files.len() >= 8,
+        "pages 至少 8 个文件，实扫 {}",
+        files.len()
+    );
+
+    let mut offenders = Vec::new();
+    for path in files {
+        let text = std::fs::read_to_string(&path).expect("读 pages 源文件");
+        for (index, line) in text.lines().enumerate() {
+            if line.trim_start().starts_with("//") {
+                continue;
+            }
+            for kind in FILLED {
+                if line.contains(kind) {
+                    offenders.push(format!("{}:{} {line:?}", path.display(), index + 1));
+                }
+            }
+        }
+    }
+
+    assert!(
+        offenders.is_empty(),
+        "pages 里出现了填充字形图标（令牌层 Play/Stop/More），与同屏描边语汇冲突：
+{}",
+        offenders.join(
+            "
+"
+        )
+    );
+}
+
+/// 依赖行里出现 `slint` 就算违规（注释行放过：说明并存期要提到 slint）。
+fn manifest_has_slint_dependency(manifest: &str) -> Vec<String> {
+    manifest
+        .lines()
+        .enumerate()
+        .filter(|(_, line)| {
+            let trimmed = line.trim_start();
+            !trimmed.starts_with('#') && trimmed.contains("slint")
+        })
+        .map(|(index, line)| format!("Cargo.toml:{} {line}", index + 1))
+        .collect()
+}
+
+#[test]
+fn this_crate_never_depends_on_slint() {
+    let manifest =
+        std::fs::read_to_string(manifest_dir().join("Cargo.toml")).expect("读 Cargo.toml");
+
+    let offenders = manifest_has_slint_dependency(&manifest);
+    assert!(
+        offenders.is_empty(),
+        "P4 的 iced 版 crate 不许依赖 slint（D26）：\n{}",
+        offenders.join("\n")
+    );
+
+    for (path, text) in sources() {
+        for (index, line) in text.lines().enumerate() {
+            // 只查真代码里的 use/路径，文档里提 slint 是允许的（要解释并存期）
+            let code = line.trim_start();
+            let is_import = code.starts_with("use ") || code.starts_with("extern crate");
+            if is_import && code.contains("slint") {
+                panic!("{}:{} 引入了 slint：{line}", path.display(), index + 1);
+            }
+        }
+    }
+}
+
+#[test]
+fn the_gate_itself_catches_a_planted_violation() {
+    // 自检：把违规样本喂给同一套判定，必须被抓住（否则门禁是空转）。
+    // **reviewer r1 造样验证过的 5 个漏网样本逐条钉在这里**，退化成「放行」立刻红。
+
+    // 1. `Color::from_rgb8(103, 80, 164)` —— 8bit 版曾因 `from_rgb(` 匹配不到而漏
+    assert!(numeric_color_call("Color::from_rgb8(103, 80, 164)").is_some());
+    // 2. `iced::Color::from_rgb8(...)` —— 带路径前缀的写法同样要拦
+    assert!(numeric_color_call("iced::Color::from_rgb8(103, 80, 164)").is_some());
+    // 3. `Color { r: 0.4, g: 0.3, b: 0.6, a: 1.0 }` —— 结构体字面量
+    assert!(color_struct_literal(
+        "Color { r: 0.4, g: 0.3, b: 0.6, a: 1.0 }"
+    ));
+    // 4. `.width(Length::Fixed(123.0))` —— 尺寸被 iced 包装一层
+    assert_eq!(
+        size_literal("Length::Fixed(123.0))").as_deref(),
+        Some("123.0")
+    );
+    // 5. `.padding(Padding::from([12.0, 8.0]))` —— 数组字面量
+    assert_eq!(
+        size_literal("Padding::from([12.0, 8.0]))").as_deref(),
+        Some("12.0")
+    );
+
+    // 原有规则不能退化
+    assert!(hex_color_at(b"    color: #6750A4,", 11).is_some());
+    assert!(hex_color_at(b"// placeholder #RRGGBB here", 15).is_none());
+    assert!(numeric_color_call("Color::from_rgb(0.1, 0.2, 0.3)").is_some());
+    assert!(numeric_color_call("Color::from_rgba8(color.r, color.g, color.b, color.a)").is_none());
+    assert!(numeric_color_call("color!(0x5865F2)").is_some());
+    assert!(size_literal("40.0)").is_some());
+    assert!(size_literal("0)").is_none());
+    assert!(size_literal("metrics.titlebar_height)").is_none());
+    assert!(size_literal("Length::Fixed(thickness))").is_none());
+    assert!(size_literal("Padding::from([0.0, ui.space(Space::X4)]))").is_none());
+    assert!(!color_struct_literal(
+        "Color::from_rgba8(color.r, color.g, color.b, 1.0)"
+    ));
+    assert!(!color_struct_literal("let color = Color { a: 0.5 };"));
+    assert!(!manifest_has_slint_dependency("slint = \"1.18\"").is_empty());
+    assert!(manifest_has_slint_dependency("# 不得依赖 slint").is_empty());
+}
+
+/// 渲染层回归守门（视觉复审 P2-1 的教训）：`indicator_matches_the_reference_56x32` 只测纯函数，
+/// 门禁全绿但图上的药丸实际是 88×32 —— 因为 `.center_x(Length::Fill)` 会把容器 width 覆盖成 Fill。
+/// 这里直接扫 `nav.rs`：药丸容器**不许**出现 `center_x(` / `center_y(`。
+#[test]
+fn pill_never_overrides_its_size_with_fill() {
+    let nav = manifest_dir().join("src").join("shell").join("nav.rs");
+    let text = std::fs::read_to_string(&nav).expect("读 nav.rs");
+
+    for (index, line) in text.lines().enumerate() {
+        let code = line.trim_start();
+        if code.starts_with("//") {
+            continue;
+        }
+        for pattern in ["center_x(", "center_y("] {
+            assert!(
+                !code.contains(pattern),
+                "nav.rs:{} 用了 {pattern}——`center_*(Length::Fill)` 会把容器尺寸改成 Fill，                 药丸会被父级宽度覆盖（视觉复审 P2-1）。居中请用父级 `align_x`：{line}",
+                index + 1
+            );
+        }
+    }
+}
diff --git a/crates/app/Cargo.toml b/crates/app/Cargo.toml
new file mode 100644
index 0000000..7bcdaa9
--- /dev/null
+++ b/crates/app/Cargo.toml
@@ -0,0 +1,50 @@
+[package]
+name = "unlucky-app"
+description = "Unlucky-Launcher 桌面壳：Slint + Metro 视觉（唯一允许依赖 UI 框架的 crate）"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+publish.workspace = true
+
+[[bin]]
+name = "unlucky-launcher"
+path = "src/main.rs"
+
+[dependencies]
+slint.workspace = true
+# 跨界 DTO 必须可序列化（AGENTS §6 / 01c §5）：事件与快照是 IPC 契约，
+# 序列化能力由 derive 钉住，测试里做 round-trip 断言。
+serde.workspace = true
+# host 层要读 core 设置/事件里的 JSON 值（serde_json 是 workspace 既有依赖）
+serde_json.workspace = true
+
+# M85：UI 框架无关的宿主层（DTO / 状态 reducer / host / 设置桥 / 偏好 / 路由 / 对话框 / 提示 /
+# 向导 / 假后端）。Slint 版与 iced 版共用这一层，所以 `crates/app` 只是它的**消费者**：
+# 本 crate 里剩下的 `crate::` 引用都换成了 `unlucky_presenter::`。
+#
+# presenter 的零 UI 依赖守门（原文与实测输出就在这里，放不进 present 的自家文档——自指）：
+#   grep -rn slint crates/presenter                 # 期望：无输出
+#   cargo tree -p unlucky-presenter --edges normal   # 期望：只有 serde/serde_json/unlucky-core
+unlucky-presenter = { path = "../presenter", version = "0.2" }
+
+# 边界（01c §5 / D3）：app 只经 DTO 消费 core/agent，**不 import 内部类型**。
+# 迁移到 presenter 之后，app 侧只剩视图模型转换（`conv/ui.rs` 的 BgFill/强调色映射）与
+# 系统主题探测需要 core；业务装配（读盘/起进程/写设置）全部在 presenter 的 host 里。
+unlucky-core = { path = "../core", version = "0.2" }
+unlucky-agent = { path = "../agent", version = "0.2" }
+# M82：同一个二进制也带 CLI 子命令（`unlucky-launcher instances list` …）。
+# 依赖方向 app → cli → core/agent 不违反 core 零 UI 铁律（guards.yml 的 core-no-ui 只查
+# `cargo tree -p unlucky-core`，core 不依赖 cli）。零 UI 依赖的 `ull` 仍在 `crates/cli`，
+# 给没有图形库的机器用——两者不是重复品。
+unlucky-cli = { path = "../cli", version = "0.2" }
+
+[build-dependencies]
+slint-build.workspace = true
+
+[dev-dependencies]
+
+[lints]
+workspace = true
diff --git a/crates/app/build.rs b/crates/app/build.rs
new file mode 100644
index 0000000..a67a158
--- /dev/null
+++ b/crates/app/build.rs
@@ -0,0 +1,7 @@
+//! Slint 编译入口：把 ui/main.slint 编译成 Rust 代码，供 src/main.rs 的 `slint::include_modules!()` 引入。
+//! 保持极简——UI 结构演进（多文件拆分、主题文件）在 M17 阶段 B 里扩展本脚本。
+
+/// 编译 `ui/main.slint`；失败时让构建直接报错（UI 语法错误不该被静默忽略）。
+fn main() {
+    slint_build::compile("ui/main.slint").expect("Slint UI 编译失败（ui/main.slint）");
+}
diff --git a/crates/app/src/appearance_bind.rs b/crates/app/src/appearance_bind.rs
new file mode 100644
index 0000000..1e47787
--- /dev/null
+++ b/crates/app/src/appearance_bind.rs
@@ -0,0 +1,124 @@
+//! 「外观（高级）」四件的回调接线（从 `callbacks.rs` 拆出，守住单文件 ≤400 行）。
+//!
+//! 与 `wire_settings` 的分工：这个文件只负责 09 §101-104 的四个高级特性
+//! （背景图 / 面板半透明度 / 玻璃拟态 / 强调色）＋ 主题三态。
+//! 每个回调都是同一套动作：改 `state.prefs` → 下发到 Slint（`apply_*`）→ 落盘（`persist_settings`）→
+//! `sync()`。出厂全部关闭，所以「不碰设置页」时这里一次都不会触发。
+
+use std::rc::Weak;
+
+use crate::conv;
+use crate::ui_bind::Inner;
+
+/// 接主题三态与外观四件的回调。
+pub(crate) fn wire(ui: &crate::MainWindow, weak: &Weak<Inner>) {
+    {
+        let weak = weak.clone();
+        ui.on_theme_changed(move |mode| {
+            let Some(this) = weak.upgrade() else { return };
+            this.state.borrow_mut().prefs.theme = conv::theme_mode_from(mode);
+            this.apply_theme();
+            this.persist_settings();
+            this.sync();
+        });
+    }
+    // ── 09 §101-104「外观（高级）」四件（出厂全关，改动即刻落盘）────────
+    {
+        let weak = weak.clone();
+        ui.on_bg_image_enabled_changed(move |enabled| {
+            let Some(this) = weak.upgrade() else { return };
+            this.state.borrow_mut().prefs.appearance.bg_image_enabled = enabled;
+            this.apply_appearance();
+            this.persist_settings();
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        ui.on_bg_image_changed(move |path| {
+            let Some(this) = weak.upgrade() else { return };
+            this.state.borrow_mut().prefs.appearance.bg_image = path.to_string();
+            this.apply_appearance();
+            this.persist_settings();
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        ui.on_bg_fill_changed(move |fill| {
+            let Some(this) = weak.upgrade() else { return };
+            this.state.borrow_mut().prefs.appearance.bg_fill = conv::bg_fill_from(fill);
+            this.apply_appearance();
+            this.persist_settings();
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        ui.on_bg_dim_changed(move |value| {
+            let Some(this) = weak.upgrade() else { return };
+            this.state.borrow_mut().prefs.appearance.bg_dim = value;
+            this.apply_appearance();
+            this.persist_settings();
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        ui.on_panel_alpha_changed(move |value| {
+            let Some(this) = weak.upgrade() else { return };
+            this.state.borrow_mut().prefs.appearance.panel_alpha = value;
+            this.apply_appearance();
+            this.persist_settings();
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        ui.on_glass_changed(move |enabled| {
+            let Some(this) = weak.upgrade() else { return };
+            this.state.borrow_mut().prefs.appearance.glass = enabled;
+            this.apply_appearance();
+            this.persist_settings();
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        ui.on_accent_color_changed(move |text| {
+            let Some(this) = weak.upgrade() else { return };
+            let accepted = this.state.borrow_mut().prefs.appearance.set_accent(&text);
+            // 非法输入：只亮设置页的 warn 行，不改现状、不落盘
+            this.ui.set_accent_invalid(!accepted);
+            if accepted {
+                this.apply_appearance();
+                this.persist_settings();
+            }
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        ui.on_accent_swatch_picked(move |index| {
+            let Some(this) = weak.upgrade() else { return };
+            let Ok(index) = usize::try_from(index) else {
+                return;
+            };
+            let accepted = this
+                .state
+                .borrow_mut()
+                .prefs
+                .appearance
+                .set_accent_preset(index);
+            if !accepted {
+                return;
+            }
+            let hex = this.state.borrow().prefs.appearance.accent_color.clone();
+            this.ui.set_accent_color(conv::accent_color(&hex));
+            this.ui.set_accent_invalid(false);
+            this.apply_appearance();
+            this.persist_settings();
+            this.sync();
+        });
+    }
+}
diff --git a/crates/app/src/bg_image.rs b/crates/app/src/bg_image.rs
new file mode 100644
index 0000000..a47004e
--- /dev/null
+++ b/crates/app/src/bg_image.rs
@@ -0,0 +1,370 @@
+//! 背景图与玻璃拟态模糊层的准备（09 §101/§103 的「预生成」手法，纯 Rust、无新依赖）。
+//!
+//! 为什么要自己算：Slint 没有 `backdrop-filter`，也无法在渲染管线里做高斯模糊。可用的只有
+//! `Image::load_from_path` + 像素缓冲（`to_rgba8` / `from_rgba8`）。于是：
+//!
+//! - **模糊层** = 把原图按面积平均降到极小的尺寸（默认宽 48px），渲染时被平滑放大 → 天然模糊
+//!   （面积平均本身就是低通滤波，比在满分辨率上跑 box blur 快几个数量级，且一次只在设置变更时算）；
+//! - **tile 模式** = Slint 的 `image-fit` 没有 `repeat`，所以在 Rust 侧按窗口尺寸平铺成一张画布，
+//!   交给 `image-fit: cover`（画布与窗口同尺寸，等价于 1:1 铺设）。
+//!
+//! 解码格式：Slint 默认只编译 PNG 解码器（`image-default-formats` 特性未开），因此这里只保证 PNG；
+//! 其它格式 `load_from_path` 直接失败，UI 侧给出提示而不是静默无效果。
+
+use slint::{Image, Rgba8Pixel, SharedPixelBuffer};
+
+use unlucky_presenter::prefs::BgFill;
+
+/// 模糊层目标宽度（像素）。越小越糊；96 在 1180px 宽窗口上 ≈ 24px 半径高斯的效果。
+const BLUR_WIDTH: u32 = 96;
+/// 小图上再跑几轮 box blur（3×3）：把降采样的块状边缘抹平。
+const BLUR_PASSES: usize = 3;
+/// tile 画布上限（防超大窗口吃爆内存：4096×2560×4 ≈ 40MB）。
+const TILE_MAX_WIDTH: u32 = 4096;
+const TILE_MAX_HEIGHT: u32 = 2560;
+
+/// 一次准备出来的两张图：原图（按填充模式处理）+ 模糊层。
+#[derive(Debug, Clone, Default)]
+pub struct BackgroundLayers {
+    /// 铺在窗口底的图（tile 模式下已平铺成整窗画布）
+    pub image: Image,
+    /// 玻璃拟态用的模糊层
+    pub blur: Image,
+}
+
+/// 载入并加工背景图。
+///
+/// `viewport` 是窗口的**物理像素**尺寸（tile 模式平铺用；拿不到时传 `(0, 0)` 退回只载入）。
+/// 返回 `None` 表示路径无效 / 解码失败 / 读了像素但为空——调用方据此提示用户。
+#[must_use]
+pub fn prepare(path: &str, fill: BgFill, viewport: (u32, u32)) -> Option<BackgroundLayers> {
+    let path = path.trim();
+    if path.is_empty() {
+        return None;
+    }
+    let loaded = Image::load_from_path(std::path::Path::new(path)).ok()?;
+    let source = loaded.to_rgba8()?;
+    if source.width() == 0 || source.height() == 0 {
+        return None;
+    }
+
+    let image = match fill {
+        BgFill::Tile => {
+            let (width, height) = tile_canvas_size(source.width(), source.height(), viewport);
+            Image::from_rgba8(tile(&source, width, height))
+        }
+        // cover / contain 交给 Slint 的 image-fit，这里保留原图
+        BgFill::Cover | BgFill::Contain => loaded,
+    };
+
+    let blurred = box_blur(&downscale(&source, BLUR_WIDTH), BLUR_PASSES);
+    // 放大回窗口物理尺寸再做 1:1 贴图：软件渲染器对图片缩放不做平滑插值（最近邻），
+    // 直接把 96px 的小图丢给它会出现明显方块；这里自己双线性放大，观感才是「磨砂」。
+    let blur = match viewport {
+        (0, 0) => Image::from_rgba8(blurred),
+        (width, height) => Image::from_rgba8(upscale(&blurred, width, height)),
+    };
+
+    Some(BackgroundLayers { image, blur })
+}
+
+/// 3×3 均值模糊，`passes` 轮（小图上跑，代价可忽略）。
+fn box_blur(
+    source: &SharedPixelBuffer<Rgba8Pixel>,
+    passes: usize,
+) -> SharedPixelBuffer<Rgba8Pixel> {
+    let width = source.width() as usize;
+    let height = source.height() as usize;
+    if width < 3 || height < 3 || passes == 0 {
+        return source.clone();
+    }
+    let mut current: Vec<Rgba8Pixel> = source.as_slice().to_vec();
+    let mut next = current.clone();
+    for _ in 0..passes {
+        for y in 0..height {
+            for x in 0..width {
+                let mut sum = [0u32; 4];
+                let mut count = 0u32;
+                for dy in -1i32..=1 {
+                    for dx in -1i32..=1 {
+                        let sy = (y as i32 + dy).clamp(0, height as i32 - 1) as usize;
+                        let sx = (x as i32 + dx).clamp(0, width as i32 - 1) as usize;
+                        let pixel = current[sy * width + sx];
+                        sum[0] += u32::from(pixel.r);
+                        sum[1] += u32::from(pixel.g);
+                        sum[2] += u32::from(pixel.b);
+                        sum[3] += u32::from(pixel.a);
+                        count += 1;
+                    }
+                }
+                next[y * width + x] = Rgba8Pixel {
+                    r: (sum[0] / count) as u8,
+                    g: (sum[1] / count) as u8,
+                    b: (sum[2] / count) as u8,
+                    a: (sum[3] / count) as u8,
+                };
+            }
+        }
+        std::mem::swap(&mut current, &mut next);
+    }
+    let mut out = SharedPixelBuffer::<Rgba8Pixel>::new(source.width(), source.height());
+    out.make_mut_slice().copy_from_slice(&current);
+    out
+}
+
+/// 双线性放大到目标尺寸。
+fn upscale(
+    source: &SharedPixelBuffer<Rgba8Pixel>,
+    width: u32,
+    height: u32,
+) -> SharedPixelBuffer<Rgba8Pixel> {
+    let src_w = source.width();
+    let src_h = source.height();
+    if src_w == 0 || src_h == 0 || width == 0 || height == 0 {
+        return SharedPixelBuffer::new(width.max(1), height.max(1));
+    }
+    let pixels = source.as_slice();
+    let mut out = SharedPixelBuffer::<Rgba8Pixel>::new(width, height);
+    let dst = out.make_mut_slice();
+    let sample = |fx: f32, fy: f32| -> Rgba8Pixel {
+        let x = (fx * (src_w - 1) as f32).clamp(0.0, (src_w - 1) as f32);
+        let y = (fy * (src_h - 1) as f32).clamp(0.0, (src_h - 1) as f32);
+        let x0 = x.floor() as usize;
+        let y0 = y.floor() as usize;
+        let x1 = (x0 + 1).min(src_w as usize - 1);
+        let y1 = (y0 + 1).min(src_h as usize - 1);
+        let tx = x - x0 as f32;
+        let ty = y - y0 as f32;
+        let at = |px: usize, py: usize| pixels[py * src_w as usize + px];
+        let blend = |a: u8, b: u8, c: u8, d: u8| -> u8 {
+            let top = f32::from(a) * (1.0 - tx) + f32::from(b) * tx;
+            let bottom = f32::from(c) * (1.0 - tx) + f32::from(d) * tx;
+            (top * (1.0 - ty) + bottom * ty).round().clamp(0.0, 255.0) as u8
+        };
+        let (p00, p10, p01, p11) = (at(x0, y0), at(x1, y0), at(x0, y1), at(x1, y1));
+        Rgba8Pixel {
+            r: blend(p00.r, p10.r, p01.r, p11.r),
+            g: blend(p00.g, p10.g, p01.g, p11.g),
+            b: blend(p00.b, p10.b, p01.b, p11.b),
+            a: blend(p00.a, p10.a, p01.a, p11.a),
+        }
+    };
+    for y in 0..height as usize {
+        let fy = y as f32 / height as f32;
+        for x in 0..width as usize {
+            dst[y * width as usize + x] = sample(x as f32 / width as f32, fy);
+        }
+    }
+    out
+}
+
+/// 平铺画布尺寸：覆盖整个视口、且是原图尺寸的整数倍（超上限就截断）。
+fn tile_canvas_size(source_width: u32, source_height: u32, viewport: (u32, u32)) -> (u32, u32) {
+    if viewport.0 == 0 || viewport.1 == 0 {
+        return (source_width, source_height);
+    }
+    let repeat_x = viewport.0.div_ceil(source_width).max(1);
+    let repeat_y = viewport.1.div_ceil(source_height).max(1);
+    let width = (repeat_x * source_width).min(TILE_MAX_WIDTH);
+    let height = (repeat_y * source_height).min(TILE_MAX_HEIGHT);
+    (width.max(source_width), height.max(source_height))
+}
+
+/// 按整数格平铺（源图超出画布的部分裁掉）。
+fn tile(
+    source: &SharedPixelBuffer<Rgba8Pixel>,
+    width: u32,
+    height: u32,
+) -> SharedPixelBuffer<Rgba8Pixel> {
+    let mut canvas = SharedPixelBuffer::<Rgba8Pixel>::new(width, height);
+    let src_w = source.width() as usize;
+    let src_h = source.height() as usize;
+    let src = source.as_slice();
+    let dst = canvas.make_mut_slice();
+    for y in 0..height as usize {
+        let src_row = (y % src_h) * src_w;
+        let dst_row = y * width as usize;
+        for x in 0..width as usize {
+            dst[dst_row + x] = src[src_row + (x % src_w)];
+        }
+    }
+    canvas
+}
+
+/// 面积平均降采样（保留宽高比，最窄 1px）。
+fn downscale(
+    source: &SharedPixelBuffer<Rgba8Pixel>,
+    target_width: u32,
+) -> SharedPixelBuffer<Rgba8Pixel> {
+    let src_w = source.width();
+    let src_h = source.height();
+    let target_width = target_width.clamp(1, src_w);
+    let target_height = ((src_h as u64 * target_width as u64) / src_w as u64).max(1) as u32;
+
+    let mut out = SharedPixelBuffer::<Rgba8Pixel>::new(target_width, target_height);
+    let src = source.as_slice();
+    let dst = out.make_mut_slice();
+
+    for ty in 0..target_height as usize {
+        // 每个目标像素覆盖的源矩形（按比例分块，块内取平均）
+        let y0 = ty * src_h as usize / target_height as usize;
+        let y1 = ((ty + 1) * src_h as usize / target_height as usize).max(y0 + 1);
+        for tx in 0..target_width as usize {
+            let x0 = tx * src_w as usize / target_width as usize;
+            let x1 = ((tx + 1) * src_w as usize / target_width as usize).max(x0 + 1);
+            let mut sum = [0u32; 4];
+            let mut count = 0u32;
+            for y in y0..y1.min(src_h as usize) {
+                for x in x0..x1.min(src_w as usize) {
+                    let pixel = src[y * src_w as usize + x];
+                    sum[0] += u32::from(pixel.r);
+                    sum[1] += u32::from(pixel.g);
+                    sum[2] += u32::from(pixel.b);
+                    sum[3] += u32::from(pixel.a);
+                    count += 1;
+                }
+            }
+            let count = count.max(1);
+            dst[ty * target_width as usize + tx] = Rgba8Pixel {
+                r: (sum[0] / count) as u8,
+                g: (sum[1] / count) as u8,
+                b: (sum[2] / count) as u8,
+                a: (sum[3] / count) as u8,
+            };
+        }
+    }
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn solid(width: u32, height: u32, pixel: Rgba8Pixel) -> SharedPixelBuffer<Rgba8Pixel> {
+        let mut buffer = SharedPixelBuffer::<Rgba8Pixel>::new(width, height);
+        buffer.make_mut_slice().fill(pixel);
+        buffer
+    }
+
+    #[test]
+    fn downscale_keeps_aspect_and_averages_area() {
+        let mut source = SharedPixelBuffer::<Rgba8Pixel>::new(96, 48);
+        // 左半黑、右半白：降采样后左右两侧应各自保持纯色
+        for y in 0..48 {
+            for x in 0..96 {
+                let value = if x < 48 { 0 } else { 255 };
+                source.make_mut_slice()[y * 96 + x] = Rgba8Pixel {
+                    r: value,
+                    g: value,
+                    b: value,
+                    a: 255,
+                };
+            }
+        }
+        let small = downscale(&source, 24);
+        assert_eq!(small.width(), 24);
+        assert_eq!(small.height(), 12, "宽高比保持 2:1");
+        let pixels = small.as_slice();
+        assert_eq!(pixels[0].r, 0, "左侧仍是黑");
+        assert_eq!(pixels[23].r, 255, "右侧仍是白");
+    }
+
+    #[test]
+    fn downscale_never_produces_zero_height() {
+        let source = solid(
+            400,
+            3,
+            Rgba8Pixel {
+                r: 1,
+                g: 2,
+                b: 3,
+                a: 255,
+            },
+        );
+        let small = downscale(&source, 2);
+        assert_eq!(small.width(), 2);
+        assert!(small.height() >= 1);
+    }
+
+    #[test]
+    fn tile_canvas_covers_viewport_in_whole_repeats() {
+        assert_eq!(tile_canvas_size(120, 100, (1180, 760)), (1200, 800));
+        // 视口未知（取不到窗口尺寸）时退回单块
+        assert_eq!(tile_canvas_size(120, 100, (0, 0)), (120, 100));
+        // 超大视口被上限截断
+        let (width, height) = tile_canvas_size(64, 64, (9000, 9000));
+        assert!(width <= TILE_MAX_WIDTH && height <= TILE_MAX_HEIGHT);
+    }
+
+    #[test]
+    fn tile_repeats_source_pixels() {
+        let source = solid(
+            2,
+            2,
+            Rgba8Pixel {
+                r: 9,
+                g: 9,
+                b: 9,
+                a: 255,
+            },
+        );
+        let canvas = tile(&source, 5, 3);
+        assert_eq!(canvas.width(), 5);
+        assert_eq!(canvas.height(), 3);
+        assert!(canvas.as_slice().iter().all(|pixel| pixel.r == 9));
+    }
+
+    #[test]
+    fn prepare_rejects_bad_input() {
+        assert!(prepare("", BgFill::Cover, (100, 100)).is_none());
+        assert!(prepare("D:/definitely/not/here.png", BgFill::Cover, (100, 100)).is_none());
+    }
+
+    #[test]
+    fn box_blur_smooths_a_hard_edge() {
+        // 左黑右白：模糊后交界处应出现中间灰（硬边被抹平）
+        let mut source = SharedPixelBuffer::<Rgba8Pixel>::new(9, 3);
+        for y in 0..3 {
+            for x in 0..9 {
+                let value = if x < 4 { 0 } else { 255 };
+                source.make_mut_slice()[y * 9 + x] = Rgba8Pixel {
+                    r: value,
+                    g: value,
+                    b: value,
+                    a: 255,
+                };
+            }
+        }
+        let blurred = box_blur(&source, 2);
+        let middle = blurred.as_slice()[9 + 4]; // 第 1 行（共 9 列）的第 4 个像素
+        assert!(
+            middle.r > 20 && middle.r < 235,
+            "交界处应被抹成中间灰，实际 {}",
+            middle.r
+        );
+    }
+
+    #[test]
+    fn upscale_matches_requested_size_and_interpolates() {
+        let mut source = SharedPixelBuffer::<Rgba8Pixel>::new(2, 1);
+        let pixels = source.make_mut_slice();
+        pixels[0] = Rgba8Pixel {
+            r: 0,
+            g: 0,
+            b: 0,
+            a: 255,
+        };
+        pixels[1] = Rgba8Pixel {
+            r: 255,
+            g: 255,
+            b: 255,
+            a: 255,
+        };
+        let big = upscale(&source, 8, 2);
+        assert_eq!(big.width(), 8);
+        assert_eq!(big.height(), 2);
+        let row = big.as_slice();
+        // 双线性：中间像素应是灰阶过渡而不是 0/255 二值
+        assert!(row[3].r > 60 && row[3].r < 200, "实际 {}", row[3].r);
+    }
+}
diff --git a/crates/app/src/callbacks.rs b/crates/app/src/callbacks.rs
new file mode 100644
index 0000000..eab031a
--- /dev/null
+++ b/crates/app/src/callbacks.rs
@@ -0,0 +1,352 @@
+//! 回调接线：把 `ui/main.slint` 暴露的每个回调翻译成「状态变更 + AppCommand + 同步」。
+//!
+//! 逐条列出而不做通用转发，是为了让「用户能做的每一件事」在这里一目了然；
+//! 新增交互时只改这一处 + `.slint` 的 callback 声明。
+
+use std::rc::Weak;
+
+use slint::ComponentHandle;
+
+use crate::conv;
+use crate::ui_bind::Inner;
+use unlucky_presenter::dto::AppCommand;
+use unlucky_presenter::router::Route;
+use unlucky_presenter::toast::ToastKind;
+
+/// 接全部回调；闭包持弱引用，避免 `MainWindow` 与闭包互相持有导致窗口永不释放。
+pub(crate) fn wire(weak: Weak<Inner>) {
+    let Some(inner) = weak.upgrade() else { return };
+    // 只在注册期间持有强引用；闭包内一律持弱引用（否则窗口与闭包互相持有、永不释放）。
+    let ui = &inner.ui;
+
+    wire_window(ui, &weak);
+    wire_navigation(ui, &weak);
+    wire_instances(ui, &weak);
+    wire_download(ui, &weak);
+    wire_logs(ui, &weak);
+    wire_settings(ui, &weak);
+    wire_overlays(ui, &weak);
+}
+
+fn wire_window(ui: &crate::MainWindow, weak: &Weak<Inner>) {
+    {
+        let weak = weak.clone();
+        ui.on_toggle_maximize(move || {
+            let Some(this) = weak.upgrade() else { return };
+            let window = this.ui.window();
+            window.set_maximized(!window.is_maximized());
+        });
+    }
+    {
+        let weak = weak.clone();
+        ui.on_minimize(move || {
+            if let Some(this) = weak.upgrade() {
+                this.ui.window().set_minimized(true);
+            }
+        });
+    }
+    {
+        let weak = weak.clone();
+        ui.on_request_close(move || {
+            if let Some(this) = weak.upgrade() {
+                let _ = this.ui.hide();
+            }
+            let _ = slint::quit_event_loop();
+        });
+    }
+}
+
+fn wire_navigation(ui: &crate::MainWindow, weak: &Weak<Inner>) {
+    {
+        let weak = weak.clone();
+        ui.on_navigate(move |route| {
+            let Some(this) = weak.upgrade() else { return };
+            if let Some(route) = conv::route_from(route) {
+                this.state.borrow_mut().navigate(route);
+                this.sync();
+            }
+        });
+    }
+    {
+        let weak = weak.clone();
+        ui.on_toggle_nav(move || {
+            let Some(this) = weak.upgrade() else { return };
+            this.state.borrow_mut().toggle_nav();
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        ui.on_toggle_ai(move || {
+            let Some(this) = weak.upgrade() else { return };
+            this.state.borrow_mut().toggle_ai();
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        ui.on_expand_ai(move || {
+            let Some(this) = weak.upgrade() else { return };
+            this.state.borrow_mut().navigate(Route::Agent);
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        ui.on_dock_ai(move || {
+            let Some(this) = weak.upgrade() else { return };
+            this.state.borrow_mut().back();
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        ui.on_toggle_yolo(move || {
+            let Some(this) = weak.upgrade() else { return };
+            let enabled = {
+                let mut state = this.state.borrow_mut();
+                state.ai.yolo = !state.ai.yolo;
+                state.ai.yolo
+            };
+            this.dispatch(AppCommand::SetYolo(enabled));
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        ui.on_ai_send(move |text| {
+            let Some(this) = weak.upgrade() else { return };
+            let text = text.to_string();
+            if text.trim().is_empty() {
+                return;
+            }
+            // 不做本地回显：user 消息由 host 的 MessageAppended 事件带回（契约 §3）
+            this.state.borrow_mut().ai.draft.clear();
+            this.ui.set_ai_draft("".into());
+            this.ask_agent(&text);
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        ui.on_ai_stop(move || {
+            let Some(this) = weak.upgrade() else { return };
+            this.state.borrow_mut().ai.finish_stream();
+            this.dispatch(AppCommand::StopAgent);
+            this.sync();
+        });
+    }
+}
+
+fn wire_instances(ui: &crate::MainWindow, weak: &Weak<Inner>) {
+    {
+        let weak = weak.clone();
+        ui.on_instance_launch(move |id| {
+            let Some(this) = weak.upgrade() else { return };
+            this.dispatch(AppCommand::LaunchInstance(id.to_string()));
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        ui.on_instance_configure(move |id| {
+            let Some(this) = weak.upgrade() else { return };
+            // 齿轮键进实例详情（G4 占位页），实例级设置后续挂在该页 tab 上
+            this.state
+                .borrow_mut()
+                .navigate(Route::Detail(id.to_string()));
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        ui.on_instance_stop(move |id| {
+            let Some(this) = weak.upgrade() else { return };
+            this.dispatch(AppCommand::StopInstance(id.to_string()));
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        ui.on_instance_open(move |id| {
+            let Some(this) = weak.upgrade() else { return };
+            this.state
+                .borrow_mut()
+                .navigate(Route::Detail(id.to_string()));
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        ui.on_new_instance(move || {
+            let Some(this) = weak.upgrade() else { return };
+            // G5：打开向导（版本 → 加载器 → 名字 → 确认 → 安装进度）
+            this.state.borrow_mut().wizard = unlucky_presenter::wizard::WizardState::open();
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        ui.on_instance_view_changed(move |view| {
+            let Some(this) = weak.upgrade() else { return };
+            this.state.borrow_mut().prefs.instance_view = conv::instance_view_from(view);
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        ui.on_tile_size_changed(move |size| {
+            let Some(this) = weak.upgrade() else { return };
+            this.state.borrow_mut().prefs.tile_size = conv::tile_size_from(size);
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        ui.on_instance_query_changed(move |query| {
+            let Some(this) = weak.upgrade() else { return };
+            this.state.borrow_mut().instance_query = query.to_string();
+            this.sync();
+        });
+    }
+}
+
+fn wire_download(ui: &crate::MainWindow, weak: &Weak<Inner>) {
+    {
+        let weak = weak.clone();
+        ui.on_download_category_changed(move |category| {
+            let Some(this) = weak.upgrade() else { return };
+            let category = conv::version_category(category);
+            this.state.borrow_mut().prefs.download_category = category;
+            this.dispatch(AppCommand::ListVersions(category));
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        ui.on_download_install(move |id| {
+            let Some(this) = weak.upgrade() else { return };
+            this.dispatch(AppCommand::InstallVersion(id.to_string()));
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        ui.on_installed_only_changed(move |only| {
+            let Some(this) = weak.upgrade() else { return };
+            this.state.borrow_mut().installed_only = only;
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        ui.on_download_query_changed(move |query| {
+            let Some(this) = weak.upgrade() else { return };
+            this.state.borrow_mut().download_query = query.to_string();
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        ui.on_ancient_help(move || {
+            let Some(this) = weak.upgrade() else { return };
+            this.state.borrow_mut().toasts.push(
+                ToastKind::Info,
+                "远古版（classic/alpha/beta）需旧版 Java 与旧启动参数；完整说明页 P1 接入",
+            );
+            this.sync();
+        });
+    }
+}
+
+fn wire_logs(ui: &crate::MainWindow, weak: &Weak<Inner>) {
+    {
+        let weak = weak.clone();
+        ui.on_log_select(move |id| {
+            let Some(this) = weak.upgrade() else { return };
+            this.state.borrow_mut().selected_session = Some(id.to_string());
+            this.dispatch(AppCommand::OpenLogSession(id.to_string()));
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        ui.on_log_ask_ai(move |id| {
+            let Some(this) = weak.upgrade() else { return };
+            let question = format!("帮我看下会话 {id} 为什么崩溃");
+            this.state.borrow_mut().navigate(Route::Agent);
+            this.ask_agent(&question);
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        ui.on_log_apply_fix(move || {
+            let Some(this) = weak.upgrade() else { return };
+            this.state
+                .borrow_mut()
+                .toasts
+                .push(ToastKind::Warn, "一键修复在 P1 接 diagnose 的 fix_action");
+            this.sync();
+        });
+    }
+}
+
+fn wire_settings(ui: &crate::MainWindow, weak: &Weak<Inner>) {
+    // 主题三态 + 外观四件在 appearance_bind.rs（拆文件守 400 行）
+    crate::appearance_bind::wire(ui, weak);
+    {
+        let weak = weak.clone();
+        ui.on_yolo_changed(move |enabled| {
+            let Some(this) = weak.upgrade() else { return };
+            this.state.borrow_mut().ai.yolo = enabled;
+            this.dispatch(AppCommand::SetYolo(enabled));
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        ui.on_mcp_changed(move |_enabled| {
+            let Some(this) = weak.upgrade() else { return };
+            this.state
+                .borrow_mut()
+                .toasts
+                .push(ToastKind::Info, "MCP server 开关在 P1 接 agent");
+            this.sync();
+        });
+    }
+    // P0 只保留入口：设置分组与 AI 端点暂不落状态（P1 接 setting schema）。
+    ui.on_settings_section_changed(|_section| {});
+    ui.on_ai_endpoint_changed(|_index| {});
+}
+
+fn wire_overlays(ui: &crate::MainWindow, weak: &Weak<Inner>) {
+    {
+        let weak = weak.clone();
+        ui.on_dialog_primary(move || close_current_dialog(&weak));
+    }
+    {
+        let weak = weak.clone();
+        ui.on_dialog_secondary(move || close_current_dialog(&weak));
+    }
+    {
+        let weak = weak.clone();
+        ui.on_dialog_dismissed(move || close_current_dialog(&weak));
+    }
+    {
+        let weak = weak.clone();
+        ui.on_toast_dismissed(move |id| {
+            let Some(this) = weak.upgrade() else { return };
+            if let Ok(id) = id.parse::<u64>() {
+                this.state.borrow_mut().toasts.dismiss(id);
+                this.sync();
+            }
+        });
+    }
+}
+
+fn close_current_dialog(weak: &Weak<Inner>) {
+    let Some(this) = weak.upgrade() else { return };
+    this.state.borrow_mut().dialogs.close_current();
+    this.sync();
+}
diff --git a/crates/app/src/callbacks_pages.rs b/crates/app/src/callbacks_pages.rs
new file mode 100644
index 0000000..19623f9
--- /dev/null
+++ b/crates/app/src/callbacks_pages.rs
@@ -0,0 +1,264 @@
+//! `PageState` global 的回调接线：账户 / Java / 设置 / 通知 / 向导 / 崩溃导入 / 日志刷新。
+//!
+//! 与 `callbacks.rs` 同一纪律：每个回调 = 「改状态 + 发 AppCommand + 同步 UI」，一处看全。
+//! 用 global 而不是逐层转发属性（见 `ui/page_state.slint` 顶部的取舍说明）。
+
+use std::rc::Weak;
+
+use slint::ComponentHandle;
+
+use crate::conv;
+use crate::ui_bind::Inner;
+use unlucky_presenter::dto::{AppCommand, CreateRequest, LoaderKind};
+
+/// 接全部页面状态回调。
+pub(crate) fn wire_pages(weak: Weak<Inner>) {
+    let Some(inner) = weak.upgrade() else { return };
+    let page = inner.ui.global::<crate::PageState<'_>>();
+
+    // ── 账户 ──────────────────────────────────────────────────
+    {
+        let weak = weak.clone();
+        page.on_account_add_offline(move |name| {
+            let name = name.to_string();
+            if name.trim().is_empty() {
+                return;
+            }
+            let Some(this) = weak.upgrade() else { return };
+            this.dispatch(AppCommand::AddOfflineAccount(name));
+            this.ui
+                .global::<crate::PageState<'_>>()
+                .set_offline_name("".into());
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        page.on_account_remove(move |id| {
+            let Some(this) = weak.upgrade() else { return };
+            this.dispatch(AppCommand::RemoveAccount(id.to_string()));
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        page.on_account_switch(move |id| {
+            let Some(this) = weak.upgrade() else { return };
+            this.dispatch(AppCommand::SwitchAccount(id.to_string()));
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        page.on_msa_begin(move || {
+            let Some(this) = weak.upgrade() else { return };
+            this.dispatch(AppCommand::StartDeviceLogin);
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        page.on_msa_browser_begin(move || {
+            let Some(this) = weak.upgrade() else { return };
+            this.dispatch(AppCommand::StartBrowserLogin);
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        page.on_msa_cancel(move || {
+            let Some(this) = weak.upgrade() else { return };
+            this.dispatch(AppCommand::CancelDeviceLogin);
+            this.sync();
+        });
+    }
+
+    // ── Java ──────────────────────────────────────────────────
+    {
+        let weak = weak.clone();
+        page.on_java_install(move |vendor| {
+            let Some(this) = weak.upgrade() else { return };
+            this.dispatch(AppCommand::InstallJava(vendor.to_string()));
+            this.sync();
+        });
+    }
+
+    // ── 设置 ──────────────────────────────────────────────────
+    {
+        let weak = weak.clone();
+        page.on_setting_changed(move |key, value| {
+            let Some(this) = weak.upgrade() else { return };
+            this.dispatch(AppCommand::SetSetting {
+                key: key.to_string(),
+                value: value.to_string(),
+            });
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        page.on_setting_action(move |action| {
+            let Some(this) = weak.upgrade() else { return };
+            let action = action.to_string();
+            match action.as_str() {
+                // 清 24h 地区缓存 → 下次下载重新判定
+                "detect_region" => this.dispatch(AppCommand::SetSetting {
+                    key: "download.action.detect_region".to_string(),
+                    value: String::new(),
+                }),
+                // Java 分组的「安装/管理」→ 按回退链装一个托管 JDK
+                "install_java" => this.dispatch(AppCommand::InstallJava(String::new())),
+                _ => {}
+            }
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        page.on_settings_tab_changed(move |tab| {
+            let Some(this) = weak.upgrade() else { return };
+            this.state.borrow_mut().settings_tab = tab.to_string();
+            this.sync();
+        });
+    }
+
+    // ── 通知 ──────────────────────────────────────────────────
+    {
+        let weak = weak.clone();
+        page.on_notice_dismiss(move |id| {
+            let Some(this) = weak.upgrade() else { return };
+            this.dispatch(AppCommand::DismissNotice(id.to_string()));
+            this.sync();
+        });
+    }
+
+    // ── 向导 ──────────────────────────────────────────────────
+    {
+        let weak = weak.clone();
+        page.on_wizard_open(move || {
+            let Some(this) = weak.upgrade() else { return };
+            this.state.borrow_mut().wizard = unlucky_presenter::wizard::WizardState::open();
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        page.on_wizard_close(move || {
+            let Some(this) = weak.upgrade() else { return };
+            this.state.borrow_mut().wizard.open = false;
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        page.on_wizard_select_version(move |version| {
+            let Some(this) = weak.upgrade() else { return };
+            this.state
+                .borrow_mut()
+                .wizard
+                .select_version(version.as_ref());
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        page.on_wizard_select_loader(move |index| {
+            let Some(this) = weak.upgrade() else { return };
+            let loader = match index {
+                1 => LoaderKind::Fabric,
+                2 => LoaderKind::Quilt,
+                3 => LoaderKind::Forge,
+                4 => LoaderKind::NeoForge,
+                _ => LoaderKind::Vanilla,
+            };
+            this.state.borrow_mut().wizard.select_loader(loader);
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        page.on_wizard_name_changed(move |name| {
+            let Some(this) = weak.upgrade() else { return };
+            let mut state = this.state.borrow_mut();
+            state.wizard.name = name.to_string();
+            state.wizard.error.clear();
+            drop(state);
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        page.on_wizard_next(move || {
+            let Some(this) = weak.upgrade() else { return };
+            this.state.borrow_mut().wizard.advance();
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        page.on_wizard_back(move || {
+            let Some(this) = weak.upgrade() else { return };
+            this.state.borrow_mut().wizard.step_back();
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        page.on_wizard_confirm(move || {
+            let Some(this) = weak.upgrade() else { return };
+            let request = {
+                let state = this.state.borrow();
+                let wizard = &state.wizard;
+                wizard.ready_to_submit().map(|()| CreateRequest {
+                    version: wizard.version.trim().to_string(),
+                    loader: wizard.loader,
+                    loader_version: wizard.loader_version.trim().to_string(),
+                    name: wizard.name.trim().to_string(),
+                })
+            };
+            match request {
+                Ok(request) => {
+                    this.dispatch(AppCommand::CreateInstance(request));
+                    this.state.borrow_mut().wizard.submitted();
+                }
+                Err(error) => {
+                    this.state.borrow_mut().wizard.error = error;
+                }
+            }
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        page.on_install_cancel(move || {
+            let Some(this) = weak.upgrade() else { return };
+            this.dispatch(AppCommand::CancelInstall);
+            this.sync();
+        });
+    }
+
+    // ── 日志页 ────────────────────────────────────────────────
+    {
+        let weak = weak.clone();
+        page.on_crash_import(move |path| {
+            let Some(this) = weak.upgrade() else { return };
+            let path = path.to_string();
+            if path.trim().is_empty() {
+                return;
+            }
+            this.dispatch(AppCommand::ImportCrashLog(path));
+            this.sync();
+        });
+    }
+    {
+        let weak = weak.clone();
+        page.on_logs_refresh(move || {
+            let Some(this) = weak.upgrade() else { return };
+            this.dispatch(AppCommand::RefreshLogSessions);
+            this.sync();
+        });
+    }
+
+    // 设置页分组切换同时刷新一遍分组快照（外部改配置后手点分组即最新）
+    let _ = conv::setting_groups;
+}
diff --git a/crates/app/src/conv/agent.rs b/crates/app/src/conv/agent.rs
new file mode 100644
index 0000000..9e32255
--- /dev/null
+++ b/crates/app/src/conv/agent.rs
@@ -0,0 +1,103 @@
+//! AI 页与覆盖层：会话消息、对话框（一次一条）、Toast。
+
+use crate::{ChatRole, DialogKind, UiChatMessage, UiDialog, UiToast};
+use unlucky_presenter::dialogs as dlg;
+use unlucky_presenter::dto::ChatRole as DtoChatRole;
+use unlucky_presenter::state::AppState;
+use unlucky_presenter::toast as toast_mod;
+
+/// AI 会话消息。
+pub fn chat(state: &AppState) -> Vec<UiChatMessage> {
+    state
+        .ai
+        .messages
+        .iter()
+        .map(|message| UiChatMessage {
+            role: match message.role {
+                DtoChatRole::User => ChatRole::User,
+                DtoChatRole::Assistant => ChatRole::Assistant,
+                DtoChatRole::Tool => ChatRole::Tool,
+                DtoChatRole::System => ChatRole::System,
+            },
+            text: message.text.clone().into(),
+            tool_name: message
+                .tool
+                .as_ref()
+                .map(|tool| tool.name.clone())
+                .unwrap_or_default()
+                .into(),
+            tool_ok: message.tool.as_ref().is_none_or(|tool| tool.ok),
+            streaming: message.streaming,
+        })
+        .collect()
+}
+
+/// 当前对话框（一次一条）+ 是否显示 + 队列剩余条数。
+pub fn dialog(state: &AppState) -> (UiDialog, bool, i32) {
+    let queued = i32::try_from(state.dialogs.pending_len()).unwrap_or(0);
+    match state.dialogs.current() {
+        None => (UiDialog::default(), false, queued),
+        Some(request) => {
+            let (kind, primary, secondary) = match &request.kind {
+                dlg::DialogKind::Confirm { primary, secondary } => {
+                    (DialogKind::Confirm, primary.clone(), secondary.clone())
+                }
+                dlg::DialogKind::Input { primary, .. } => {
+                    (DialogKind::Input, primary.clone(), String::new())
+                }
+                dlg::DialogKind::Progress { .. } => {
+                    (DialogKind::Progress, "取消".to_string(), String::new())
+                }
+                dlg::DialogKind::Error { primary, .. } => {
+                    (DialogKind::Error, primary.clone(), "忽略".to_string())
+                }
+            };
+            let progress = match &request.kind {
+                dlg::DialogKind::Progress { progress, .. } => *progress,
+                _ => 0.0,
+            };
+            let input_label = match &request.kind {
+                dlg::DialogKind::Input { label, .. } => label.clone(),
+                _ => String::new(),
+            };
+            let input_value = match &request.kind {
+                dlg::DialogKind::Input { value, .. } => value.clone(),
+                _ => String::new(),
+            };
+            (
+                UiDialog {
+                    id: request.id.to_string().into(),
+                    kind,
+                    title: request.title.clone().into(),
+                    body: request.body.clone().into(),
+                    primary: primary.into(),
+                    secondary: secondary.into(),
+                    progress,
+                    input_label: input_label.into(),
+                    input_value: input_value.into(),
+                },
+                true,
+                queued,
+            )
+        }
+    }
+}
+
+/// Toast 列表。
+pub fn toasts(state: &AppState) -> Vec<UiToast> {
+    state
+        .toasts
+        .items()
+        .iter()
+        .map(|toast| UiToast {
+            id: toast.id.to_string().into(),
+            kind: match toast.kind {
+                toast_mod::ToastKind::Info => crate::ToastKind::Info,
+                toast_mod::ToastKind::Success => crate::ToastKind::Success,
+                toast_mod::ToastKind::Warn => crate::ToastKind::Warn,
+                toast_mod::ToastKind::Error => crate::ToastKind::Error,
+            },
+            text: toast.text.clone().into(),
+        })
+        .collect()
+}
diff --git a/crates/app/src/conv/instances.rs b/crates/app/src/conv/instances.rs
new file mode 100644
index 0000000..ddf60fb
--- /dev/null
+++ b/crates/app/src/conv/instances.rs
@@ -0,0 +1,163 @@
+//! 实例相关：磁贴外观（相位/进度/徽标/占位色）、运行中列表。
+
+use slint::Color;
+
+use crate::{LoaderKind, RuntimePhase, UiTile};
+use unlucky_presenter::dto::{self, InstanceRuntime};
+use unlucky_presenter::state::{AppState, TileCell};
+
+/// 头像/图标占位的底色池（Metro 强调色系，按 id 哈希稳定取色）。
+const HUES: [u32; 8] = [
+    0x0078D4, 0x8764B0, 0xD13438, 0xCA5010, 0x498205, 0x038387, 0x5C2D91, 0x0050EF,
+];
+
+/// 加载器枚举。
+pub fn loader(kind: dto::LoaderKind) -> LoaderKind {
+    match kind {
+        dto::LoaderKind::Vanilla => LoaderKind::Vanilla,
+        dto::LoaderKind::Fabric => LoaderKind::Fabric,
+        dto::LoaderKind::Quilt => LoaderKind::Quilt,
+        dto::LoaderKind::Forge => LoaderKind::Forge,
+        dto::LoaderKind::NeoForge => LoaderKind::Neoforge,
+        dto::LoaderKind::OptiFine => LoaderKind::Optifine,
+        dto::LoaderKind::LiteLoader => LoaderKind::Liteloader,
+    }
+}
+
+/// 运行时状态 → (磁贴外观相位, 进度 0~1, 阶段文案)。
+pub fn phase(runtime: &InstanceRuntime) -> (RuntimePhase, f32, String) {
+    match runtime {
+        InstanceRuntime::Idle => (RuntimePhase::Idle, 0.0, String::new()),
+        InstanceRuntime::Busy { stage, progress } => {
+            let phase = match stage {
+                dto::LaunchStage::Download => RuntimePhase::Downloading,
+                dto::LaunchStage::Verify => RuntimePhase::Verifying,
+                dto::LaunchStage::Launch => RuntimePhase::Launching,
+                dto::LaunchStage::Window => RuntimePhase::Running,
+            };
+            (phase, progress.ratio(), stage.label().to_string())
+        }
+        InstanceRuntime::Running { .. } => (RuntimePhase::Running, 1.0, "运行中".to_string()),
+        InstanceRuntime::Failed { reason } => (RuntimePhase::Failed, 0.0, reason.clone()),
+    }
+}
+
+/// 名字首字（无图标时的占位字母）。
+pub fn initial_of(name: &str) -> String {
+    name.chars()
+        .next()
+        .map(|c| c.to_string())
+        .unwrap_or_else(|| "?".to_string())
+}
+
+/// id → 稳定底色（同一实例每次启动同色）。
+pub fn hue_of(id: &str) -> Color {
+    let hash = id.bytes().fold(0u32, |acc, byte| {
+        acc.wrapping_mul(31).wrapping_add(u32::from(byte))
+    });
+    Color::from_argb_encoded(0xFF00_0000 | HUES[(hash as usize) % HUES.len()])
+}
+
+/// ISO-8601 UTC → 逗号少的本地展示串（`2026-10-29 19:22`）；None/空 → 从未启动。
+pub fn last_played(raw: &Option<String>) -> String {
+    match raw {
+        None => "从未启动".to_string(),
+        Some(value) if value.is_empty() => "从未启动".to_string(),
+        Some(value) => {
+            let trimmed = value.trim_end_matches('Z');
+            let mut out = String::with_capacity(trimmed.len());
+            let mut seen_time = false;
+            for ch in trimmed.chars() {
+                match ch {
+                    'T' => {
+                        seen_time = true;
+                        out.push(' ');
+                    }
+                    ':' if seen_time && out.ends_with(|c: char| c.is_ascii_digit()) => {
+                        // 只保留到分钟：秒（第三段冒号之后）直接截断
+                        if out.matches(':').count() >= 1 {
+                            break;
+                        }
+                        out.push(ch);
+                    }
+                    _ => out.push(ch),
+                }
+            }
+            out
+        }
+    }
+}
+
+/// 单个磁贴。
+pub fn tile(cell: &TileCell<'_>) -> UiTile {
+    let instance = cell.instance;
+    let (phase, progress, label) = phase(&instance.runtime);
+    UiTile {
+        id: instance.id.clone().into(),
+        name: instance.name.clone().into(),
+        mc_version: instance.mc_version.clone().into(),
+        loader: loader(instance.loader.kind),
+        loader_version: instance.loader.version.clone().into(),
+        loader_label: instance.loader.badge().into(),
+        last_played: last_played(&instance.last_played).into(),
+        phase,
+        phase_label: label.into(),
+        progress,
+        icon: slint::Image::default(),
+        hue: hue_of(&instance.id),
+        initial: initial_of(&instance.name).into(),
+        row: i32::try_from(cell.row).unwrap_or(0),
+        col: i32::try_from(cell.col).unwrap_or(0),
+    }
+}
+
+/// 磁贴网格（已按当前尺寸算好 row/col）。
+pub fn tiles(state: &AppState) -> Vec<UiTile> {
+    state.tiles().iter().map(tile).collect()
+}
+
+/// 运行中实例（顶部迷你状态条）。
+pub fn running_tiles(state: &AppState) -> Vec<UiTile> {
+    state
+        .running()
+        .iter()
+        .enumerate()
+        .map(|(index, instance)| {
+            let cell = TileCell {
+                instance,
+                row: 0,
+                col: index,
+            };
+            tile(&cell)
+        })
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{hue_of, initial_of, last_played};
+
+    #[test]
+    fn initial_is_first_grapheme_or_question_mark() {
+        assert_eq!(initial_of("生存整合包"), "生");
+        assert_eq!(initial_of("Vanilla"), "V");
+        assert_eq!(initial_of(""), "?");
+    }
+
+    #[test]
+    fn hue_is_stable_per_id() {
+        assert_eq!(hue_of("survival"), hue_of("survival"));
+        // 不同 id 大体不同色（哈希池 8 色，这里只验证确定性 + 不 panic）
+        let _ = hue_of("another-instance");
+    }
+
+    #[test]
+    fn last_played_formats_iso_to_minutes() {
+        assert_eq!(
+            last_played(&Some("2026-10-29T19:22:45Z".to_string())),
+            "2026-10-29 19:22"
+        );
+        assert_eq!(last_played(&None), "从未启动");
+        assert_eq!(last_played(&Some(String::new())), "从未启动");
+    }
+}
diff --git a/crates/app/src/conv/logs.rs b/crates/app/src/conv/logs.rs
new file mode 100644
index 0000000..b678621
--- /dev/null
+++ b/crates/app/src/conv/logs.rs
@@ -0,0 +1,84 @@
+//! 日志页：会话列表、日志行、D8 诊断卡片。
+
+use crate::{LogLevel, LogOutcome, UiDiagnosis, UiLogLine, UiLogSession};
+use unlucky_presenter::dto::{LogLevel as DtoLogLevel, LogOutcome as DtoLogOutcome};
+use unlucky_presenter::state::AppState;
+
+/// 日志会话列表。
+pub fn log_sessions(state: &AppState) -> Vec<UiLogSession> {
+    state
+        .log_sessions
+        .iter()
+        .map(|session| UiLogSession {
+            id: session.id.clone().into(),
+            when: session.when.clone().into(),
+            instance: session.instance.clone().into(),
+            outcome: match session.outcome {
+                DtoLogOutcome::Ok => LogOutcome::Ok,
+                DtoLogOutcome::Crashed => LogOutcome::Crashed,
+                DtoLogOutcome::SilentFail => LogOutcome::SilentFail,
+            },
+            duration: duration(session.duration_secs).into(),
+        })
+        .collect()
+}
+
+/// 秒 → `1h03m` / `62s`。
+pub fn duration(secs: u64) -> String {
+    if secs >= 3_600 {
+        format!("{}h{:02}m", secs / 3_600, (secs % 3_600) / 60)
+    } else if secs >= 60 {
+        format!("{}m{:02}s", secs / 60, secs % 60)
+    } else {
+        format!("{secs}s")
+    }
+}
+
+/// 当前会话日志行。
+pub fn log_lines(state: &AppState) -> Vec<UiLogLine> {
+    state
+        .log_lines
+        .iter()
+        .map(|line| UiLogLine {
+            text: line.text.clone().into(),
+            level: match line.level {
+                DtoLogLevel::Debug => LogLevel::Debug,
+                DtoLogLevel::Info => LogLevel::Info,
+                DtoLogLevel::Warn => LogLevel::Warn,
+                DtoLogLevel::Error => LogLevel::Error,
+            },
+        })
+        .collect()
+}
+
+/// 诊断卡片内容（无结论时返回默认值 + has=false）。
+pub fn diagnosis(state: &AppState) -> (UiDiagnosis, bool) {
+    match &state.diagnosis {
+        None => (UiDiagnosis::default(), false),
+        Some(report) => {
+            let diagnosis = &report.diagnosis;
+            (
+                UiDiagnosis {
+                    rule: diagnosis.rule.clone().into(),
+                    title: diagnosis.title.clone().into(),
+                    confidence: i32::from(diagnosis.confidence),
+                    hint: diagnosis.hint.clone().into(),
+                    has_fix: diagnosis.fix.is_some(),
+                },
+                true,
+            )
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::duration;
+
+    #[test]
+    fn duration_is_human_readable() {
+        assert_eq!(duration(8), "8s");
+        assert_eq!(duration(62), "1m02s");
+        assert_eq!(duration(3_780), "1h03m");
+    }
+}
diff --git a/crates/app/src/conv/mod.rs b/crates/app/src/conv/mod.rs
new file mode 100644
index 0000000..dd50cf3
--- /dev/null
+++ b/crates/app/src/conv/mod.rs
@@ -0,0 +1,26 @@
+//! 状态层 → Slint 视图模型的单向转换（DTO 值 → `models.slint` 结构体）。
+//!
+//! 只做「领域值 → 展示值」的搬运与格式化，不含业务判断；
+//! 这样 `ui_bind.rs` 里的同步逻辑就是纯粹的「状态灌进属性」。
+//! 按领域拆子模块：instances / versions / logs / agent / ui，全量 `pub use`，
+//! 调用方统一写 `crate::conv::tiles(...)` 这类路径。
+
+mod agent;
+mod instances;
+mod logs;
+mod pages;
+mod ui;
+mod versions;
+
+pub use agent::{chat, dialog, toasts};
+pub use instances::{running_tiles, tiles};
+pub use logs::{diagnosis, log_lines, log_sessions};
+pub use pages::{
+    accounts, active_account_name, device, install, java_chain, java_runtimes, java_vendors,
+    notices, setting_groups, wizard, wizard_versions,
+};
+pub use ui::{
+    accent_color, bg_fill, bg_fill_from, category_from, instance_view, instance_view_from, route,
+    route_from, theme_mode, theme_mode_from, tile_size, tile_size_from, version_category,
+};
+pub use versions::versions;
diff --git a/crates/app/src/conv/pages.rs b/crates/app/src/conv/pages.rs
new file mode 100644
index 0000000..b375c1e
--- /dev/null
+++ b/crates/app/src/conv/pages.rs
@@ -0,0 +1,301 @@
+//! 状态 → `page_state.slint` 的视图模型（账户 / Java / 安装 / 设置分组 / 通知 / 向导）。
+//!
+//! 与 `conv/{instances,versions,logs,agent}.rs` 同一套路：只做「领域值 → 展示值」的搬运，
+//! 不含业务判断。`ui_bind::sync` 把这些灌进 `PageState` global。
+
+use slint::{ModelRc, SharedString, VecModel};
+
+use crate::{
+    AccountKind, InstallStage, JavaStepOutcome, NoticeKind, SettingControl as UiControl, UiAccount,
+    UiDeviceCode, UiInstallProgress, UiJavaRuntime, UiJavaStep, UiJavaVendor, UiNotice,
+    UiSettingGroup, UiSettingRow, UiVersion, UiWizard,
+};
+use unlucky_presenter::dto::{
+    AccountKind as DtoAccountKind, DeviceLoginPhase, InstallStage as DtoInstallStage,
+    JavaChainOutcome, NoticeLevel, SettingControl, VersionKind as DtoVersionKind,
+};
+use unlucky_presenter::state::AppState;
+use unlucky_presenter::wizard::WizardStep;
+
+fn strings(items: &[String]) -> ModelRc<SharedString> {
+    ModelRc::new(VecModel::from(
+        items
+            .iter()
+            .map(|item| SharedString::from(item.as_str()))
+            .collect::<Vec<_>>(),
+    ))
+}
+
+/// 账户行。
+pub fn accounts(state: &AppState) -> Vec<UiAccount> {
+    state
+        .accounts
+        .iter()
+        .map(|account| UiAccount {
+            id: account.id.as_str().into(),
+            name: account.name.as_str().into(),
+            kind: match account.kind {
+                DtoAccountKind::Offline => AccountKind::Offline,
+                DtoAccountKind::Microsoft => AccountKind::Microsoft,
+                DtoAccountKind::Authlib => AccountKind::Authlib,
+            },
+            kind_label: account.kind.label().into(),
+            profile_id: account.profile_id.as_str().into(),
+            login_name: account.login_name.as_str().into(),
+            created: account.created.as_str().into(),
+            active: account.active,
+        })
+        .collect()
+}
+
+/// 当前启动账户的展示名（导航底部头像）。
+pub fn active_account_name(state: &AppState) -> String {
+    state
+        .accounts
+        .iter()
+        .find(|account| account.active)
+        .map(|account| account.name.clone())
+        .unwrap_or_else(|| "未登录".to_string())
+}
+
+/// 微软登录面板。
+pub fn device(state: &AppState) -> UiDeviceCode {
+    let view = &state.device_login;
+    UiDeviceCode {
+        visible: view.phase.visible(),
+        busy: view.phase.busy(),
+        user_code: view.user_code.as_str().into(),
+        verification_uri: view.verification_uri.as_str().into(),
+        qr_link: view.qr_link.as_str().into(),
+        expires: i32::try_from(view.expires_in).unwrap_or(i32::MAX),
+        message: view.message.as_str().into(),
+        phase_label: match view.phase {
+            DeviceLoginPhase::Idle => "空闲",
+            DeviceLoginPhase::Requesting => "申请中",
+            DeviceLoginPhase::Waiting => "等待确认",
+            DeviceLoginPhase::Succeeded => "成功",
+            DeviceLoginPhase::Failed => "失败",
+        }
+        .into(),
+    }
+}
+
+/// Java 发行版行。
+pub fn java_vendors(state: &AppState) -> Vec<UiJavaVendor> {
+    state
+        .java
+        .vendors
+        .iter()
+        .map(|vendor| UiJavaVendor {
+            id: vendor.id.as_str().into(),
+            display: vendor.display.as_str().into(),
+            rank: i32::try_from(vendor.rank).unwrap_or(0),
+            majors: vendor.majors.as_str().into(),
+            sources: vendor.sources.join(" · ").into(),
+            installed: vendor.installed,
+        })
+        .collect()
+}
+
+/// Java 回退链。
+pub fn java_chain(state: &AppState) -> Vec<UiJavaStep> {
+    state
+        .java
+        .chain
+        .iter()
+        .map(|step| UiJavaStep {
+            vendor: step.vendor.as_str().into(),
+            outcome: match step.outcome {
+                JavaChainOutcome::Pending => JavaStepOutcome::Pending,
+                JavaChainOutcome::Skip => JavaStepOutcome::Skip,
+                JavaChainOutcome::Failed => JavaStepOutcome::Failed,
+                JavaChainOutcome::Hit => JavaStepOutcome::Hit,
+            },
+            outcome_label: step.outcome.label().into(),
+            detail: step.detail.as_str().into(),
+        })
+        .collect()
+}
+
+/// Java 本地运行时。
+pub fn java_runtimes(state: &AppState) -> Vec<UiJavaRuntime> {
+    state
+        .java
+        .runtimes
+        .iter()
+        .map(|runtime| UiJavaRuntime {
+            binary: runtime.binary.as_str().into(),
+            version: runtime.version.as_str().into(),
+            vendor: runtime.vendor.as_str().into(),
+            origin: runtime.origin.as_str().into(),
+        })
+        .collect()
+}
+
+/// 安装进度卡片。
+pub fn install(state: &AppState) -> UiInstallProgress {
+    let Some(progress) = &state.install else {
+        return UiInstallProgress {
+            visible: false,
+            stage: InstallStage::Planning,
+            ..UiInstallProgress::default()
+        };
+    };
+    UiInstallProgress {
+        visible: true,
+        version: progress.version.as_str().into(),
+        instance: progress.instance.as_str().into(),
+        loader: progress.loader.as_str().into(),
+        stage: match progress.stage {
+            DtoInstallStage::Planning => InstallStage::Planning,
+            DtoInstallStage::Downloading => InstallStage::Downloading,
+            DtoInstallStage::Installing => InstallStage::Installing,
+            DtoInstallStage::Registering => InstallStage::Registering,
+            DtoInstallStage::Done => InstallStage::Done,
+            DtoInstallStage::Failed => InstallStage::Failed,
+            DtoInstallStage::Cancelled => InstallStage::Cancelled,
+        },
+        stage_label: progress.stage.label().into(),
+        ratio: progress.ratio(),
+        known: progress.is_known(),
+        files_label: progress.files_label().into(),
+        bytes_label: if progress.bytes_total > 0 {
+            format!(
+                "{}/{}",
+                unlucky_presenter::dto::human_bytes(progress.bytes_done),
+                unlucky_presenter::dto::human_bytes(progress.bytes_total)
+            )
+        } else {
+            String::new()
+        }
+        .into(),
+        speed: progress.speed_label().into(),
+        eta: progress.eta_label().into(),
+        message: progress.message.as_str().into(),
+        terminal: progress.stage.is_terminal(),
+        failed: progress.stage == DtoInstallStage::Failed,
+    }
+}
+
+/// 设置分组（行 + 控件）。
+pub fn setting_groups(state: &AppState) -> Vec<UiSettingGroup> {
+    state
+        .settings_groups
+        .iter()
+        .map(|group| UiSettingGroup {
+            id: group.id.as_str().into(),
+            title: group.title.as_str().into(),
+            rows: ModelRc::new(VecModel::from(
+                group
+                    .rows
+                    .iter()
+                    .map(|row| UiSettingRow {
+                        key: row.key.as_str().into(),
+                        label: row.label.as_str().into(),
+                        description: row.description.as_str().into(),
+                        control: match row.control {
+                            SettingControl::Toggle => UiControl::Toggle,
+                            SettingControl::Choice => UiControl::Choice,
+                            SettingControl::Text => UiControl::Text,
+                            SettingControl::ReadOnly => UiControl::Readonly,
+                            SettingControl::Action => UiControl::Action,
+                        },
+                        flag: row.flag,
+                        selected: row.selected,
+                        options: strings(&row.options),
+                        value_text: row.value_text.as_str().into(),
+                        action: row.action.as_str().into(),
+                    })
+                    .collect::<Vec<_>>(),
+            )),
+        })
+        .collect()
+}
+
+/// 横幅通知。
+pub fn notices(state: &AppState) -> Vec<UiNotice> {
+    state
+        .notices
+        .iter()
+        .map(|notice| UiNotice {
+            id: notice.id.as_str().into(),
+            kind: match notice.level {
+                NoticeLevel::Info => NoticeKind::Info,
+                NoticeLevel::Warn => NoticeKind::Warn,
+                NoticeLevel::Error => NoticeKind::Error,
+            },
+            title: notice.title.as_str().into(),
+            body: notice.body.as_str().into(),
+        })
+        .collect()
+}
+
+/// 向导状态。
+pub fn wizard(state: &AppState) -> UiWizard {
+    let wizard = &state.wizard;
+    let step = wizard.step;
+    let can_next = match step {
+        WizardStep::Version => !wizard.version.trim().is_empty(),
+        WizardStep::Name => unlucky_presenter::wizard::validate_name(&wizard.name).is_ok(),
+        WizardStep::Loader | WizardStep::Confirm => true,
+        WizardStep::Progress => false,
+    };
+    UiWizard {
+        open: wizard.open,
+        step: i32::try_from(step.index()).unwrap_or(0),
+        step_label: step.title().into(),
+        step_index: i32::try_from(step.index()).unwrap_or(0),
+        step_total: 5,
+        version: wizard.version.as_str().into(),
+        loader: loader_index(wizard.loader),
+        loader_label: if wizard.loader == unlucky_presenter::dto::LoaderKind::Vanilla {
+            "原版".to_string()
+        } else {
+            format!("{} {}", wizard.loader.label(), wizard.loader_version.trim())
+                .trim()
+                .to_string()
+        }
+        .into(),
+        loader_version: wizard.loader_version.as_str().into(),
+        name: wizard.name.as_str().into(),
+        error: wizard.error.as_str().into(),
+        busy: wizard.submitting,
+        can_next,
+    }
+}
+
+/// 加载器在向导里的单选序号（与 `wizard.slint` 的 LoaderChoice 顺序一致）。
+pub fn loader_index(loader: unlucky_presenter::dto::LoaderKind) -> i32 {
+    match loader {
+        unlucky_presenter::dto::LoaderKind::Vanilla => 0,
+        unlucky_presenter::dto::LoaderKind::Fabric => 1,
+        unlucky_presenter::dto::LoaderKind::Quilt => 2,
+        unlucky_presenter::dto::LoaderKind::Forge => 3,
+        unlucky_presenter::dto::LoaderKind::NeoForge => 4,
+        unlucky_presenter::dto::LoaderKind::OptiFine
+        | unlucky_presenter::dto::LoaderKind::LiteLoader => 0,
+    }
+}
+
+/// 向导里的版本列表（正式版 + 快照；远古版走下载页的显式入口）。
+pub fn wizard_versions(state: &AppState) -> Vec<UiVersion> {
+    state
+        .versions
+        .iter()
+        .filter(|version| !version.kind.is_ancient())
+        .map(|version| UiVersion {
+            id: version.id.as_str().into(),
+            kind: match version.kind {
+                DtoVersionKind::Release => crate::VersionKind::Release,
+                _ => crate::VersionKind::Snapshot,
+            },
+            released: version.released.as_str().into(),
+            installed: version.installed,
+            ancient: false,
+        })
+        .collect()
+}
+
+#[cfg(test)]
+#[path = "pages_tests.rs"]
+mod tests;
diff --git a/crates/app/src/conv/pages_tests.rs b/crates/app/src/conv/pages_tests.rs
new file mode 100644
index 0000000..e6e6d09
--- /dev/null
+++ b/crates/app/src/conv/pages_tests.rs
@@ -0,0 +1,172 @@
+//! conv/pages.rs 的单测（拆文件守 400 行上限）。
+
+use super::*;
+use slint::Model;
+use unlucky_presenter::dto::{
+    AccountView, DeviceLoginView, InstallProgressView, JavaPageView, JavaVendorView, NoticeView,
+    SettingGroupView, SettingRowView, VersionSummary,
+};
+use unlucky_presenter::wizard::WizardState;
+
+#[test]
+fn accounts_and_device_login_render() {
+    let mut state = AppState::new();
+    state.accounts = vec![AccountView {
+        id: "account:1".to_string(),
+        name: "Steve".to_string(),
+        kind: DtoAccountKind::Offline,
+        profile_id: "0f8f".to_string(),
+        login_name: String::new(),
+        created: "2026-10-31 20:12".to_string(),
+        active: true,
+    }];
+    state.device_login =
+        DeviceLoginView::waiting("ABCD-EFGH", "https://www.microsoft.com/link", 900, "");
+
+    let rows = accounts(&state);
+    assert_eq!(rows.len(), 1);
+    assert!(rows[0].active);
+    assert_eq!(rows[0].kind_label, "离线");
+    assert_eq!(active_account_name(&state), "Steve");
+
+    let device = device(&state);
+    assert!(device.visible && device.busy);
+    assert_eq!(device.user_code, "ABCD-EFGH");
+    assert_eq!(device.phase_label, "等待确认");
+}
+
+#[test]
+fn browser_login_panel_renders_the_authorization_link() {
+    let mut state = AppState::new();
+    state.device_login = DeviceLoginView::browser_waiting(
+        "https://login.microsoftonline.com/consumers/oauth2/v2.0/authorize?client_id=x",
+        300,
+        None,
+    );
+    let device = device(&state);
+    assert!(device.visible && device.busy);
+    assert_eq!(device.user_code, "", "授权码流没有用户码");
+    assert!(device.verification_uri.contains("/authorize?client_id=x"));
+    assert_eq!(device.qr_link, device.verification_uri);
+    assert_eq!(device.expires, 300);
+}
+
+#[test]
+fn install_progress_renders_labels_and_terminal_flags() {
+    let mut state = AppState::new();
+    state.install = Some(InstallProgressView {
+        version: "1.20.4".to_string(),
+        instance: "生存".to_string(),
+        loader: "Fabric 0.16.5".to_string(),
+        stage: DtoInstallStage::Downloading,
+        files_done: 3,
+        files_total: 6,
+        bytes_done: 1024,
+        bytes_total: 4096,
+        speed_bps: 2048,
+        eta_secs: 2,
+        message: "下载中".to_string(),
+    });
+    let ui = install(&state);
+    assert!(ui.visible && !ui.terminal && !ui.failed);
+    assert!((ui.ratio - 0.5).abs() < f32::EPSILON);
+    assert_eq!(ui.files_label, "3/6 文件");
+    assert_eq!(ui.speed, "2.0 KB/s");
+    assert_eq!(ui.eta, "剩 2s");
+
+    state.install = None;
+    assert!(!install(&state).visible);
+}
+
+#[test]
+fn java_chain_and_vendors_map_outcomes() {
+    let mut state = AppState::new();
+    state.java = JavaPageView {
+        vendors: vec![JavaVendorView {
+            id: "temurin".to_string(),
+            display: "Eclipse Temurin".to_string(),
+            rank: 1,
+            majors: "17/21".to_string(),
+            sources: vec!["BMCLAPI".to_string(), "GitHub".to_string()],
+            installed: true,
+        }],
+        chain: vec![unlucky_presenter::dto::JavaChainStep {
+            vendor: "temurin".to_string(),
+            outcome: JavaChainOutcome::Hit,
+            detail: "21".to_string(),
+        }],
+        ..JavaPageView::new()
+    };
+    let vendors = java_vendors(&state);
+    assert_eq!(vendors.len(), 1);
+    assert_eq!(vendors[0].sources, "BMCLAPI · GitHub");
+    let chain = java_chain(&state);
+    assert!(matches!(chain[0].outcome, JavaStepOutcome::Hit));
+    assert_eq!(chain[0].outcome_label, "命中");
+}
+
+#[test]
+fn settings_groups_map_controls() {
+    let mut state = AppState::new();
+    state.settings_groups = vec![SettingGroupView::new("download", "下载")
+        .with(SettingRowView::toggle("agent.mcp.enabled", "MCP", "", true))
+        .with(SettingRowView::choice(
+            "download.region",
+            "地区",
+            "",
+            &["auto", "cn"],
+            1,
+        ))];
+    let groups = setting_groups(&state);
+    assert_eq!(groups.len(), 1);
+    let rows = groups[0].rows.clone();
+    assert_eq!(rows.row_count(), 2);
+    let first = rows.row_data(0).expect("第一行");
+    let second = rows.row_data(1).expect("第二行");
+    assert!(first.flag);
+    assert!(matches!(second.control, UiControl::Choice));
+    assert_eq!(second.selected, 1);
+}
+
+#[test]
+fn notices_and_wizard_render() {
+    let mut state = AppState::new();
+    state.notices = vec![NoticeView::new(
+        "isolation:x",
+        NoticeLevel::Warn,
+        "隔离档位已切换",
+        "两侧都有内容",
+    )];
+    let notices = notices(&state);
+    assert!(matches!(notices[0].kind, NoticeKind::Warn));
+
+    state.wizard = WizardState::open();
+    state.wizard.select_version("1.20.4");
+    let wizard = wizard(&state);
+    assert!(wizard.open);
+    assert_eq!(wizard.step_label, "选择版本");
+    assert!(wizard.can_next);
+    assert_eq!(wizard.loader, 0);
+}
+
+#[test]
+fn wizard_versions_skip_ancient_ones() {
+    let mut state = AppState::new();
+    state.versions = vec![
+        VersionSummary {
+            id: "1.20.4".to_string(),
+            kind: DtoVersionKind::Release,
+            released: "2023-12-07".to_string(),
+            installed: false,
+        },
+        VersionSummary {
+            id: "rd-132211".to_string(),
+            kind: DtoVersionKind::Ancient(unlucky_presenter::dto::AncientKind::Classic),
+            released: "2009-05-13".to_string(),
+            installed: false,
+        },
+    ];
+    let rows = wizard_versions(&state);
+    assert_eq!(rows.len(), 1);
+    assert_eq!(rows[0].id, "1.20.4");
+}
diff --git a/crates/app/src/conv/ui.rs b/crates/app/src/conv/ui.rs
new file mode 100644
index 0000000..d9fb094
--- /dev/null
+++ b/crates/app/src/conv/ui.rs
@@ -0,0 +1,136 @@
+//! UI 偏好/路由枚举的双向映射（Slint 枚举 ↔ 状态层枚举）。
+
+use crate::{BgFillKind, DownloadCategory, InstanceView, RouteKind, ThemeMode, TileSize};
+use unlucky_presenter::dto::{self, VersionCategory};
+use unlucky_presenter::prefs;
+use unlucky_presenter::router;
+
+/// 路由 → 导航高亮/页面选择。
+pub fn route(route: &router::Route) -> RouteKind {
+    match route {
+        router::Route::Instances => RouteKind::Instances,
+        router::Route::Download => RouteKind::Download,
+        router::Route::Logs => RouteKind::Logs,
+        router::Route::Settings => RouteKind::Settings,
+        router::Route::Detail(_) => RouteKind::Detail,
+        router::Route::Agent => RouteKind::Agent,
+    }
+}
+
+/// Slint 侧导航点击 → 路由（详情页保持当前实例，不在导航里触发）。
+pub fn route_from(kind: RouteKind) -> Option<router::Route> {
+    match kind {
+        RouteKind::Instances => Some(router::Route::Instances),
+        RouteKind::Download => Some(router::Route::Download),
+        RouteKind::Logs => Some(router::Route::Logs),
+        RouteKind::Settings => Some(router::Route::Settings),
+        RouteKind::Agent => Some(router::Route::Agent),
+        RouteKind::Detail => None,
+    }
+}
+
+/// 磁贴尺寸。
+pub fn tile_size(size: prefs::TileSize) -> TileSize {
+    match size {
+        prefs::TileSize::Small => TileSize::Small,
+        prefs::TileSize::Medium => TileSize::Medium,
+        prefs::TileSize::Large => TileSize::Large,
+    }
+}
+
+/// 视图模式。
+pub fn instance_view(view: prefs::InstanceView) -> InstanceView {
+    match view {
+        prefs::InstanceView::Tiles => InstanceView::Tiles,
+        prefs::InstanceView::List => InstanceView::List,
+    }
+}
+
+/// 主题三态。
+pub fn theme_mode(mode: prefs::ThemeMode) -> ThemeMode {
+    match mode {
+        prefs::ThemeMode::Auto => ThemeMode::Auto,
+        prefs::ThemeMode::Light => ThemeMode::Light,
+        prefs::ThemeMode::Dark => ThemeMode::Dark,
+    }
+}
+
+/// Slint 主题三态 → 偏好枚举。
+pub fn theme_mode_from(mode: ThemeMode) -> prefs::ThemeMode {
+    match mode {
+        ThemeMode::Auto => prefs::ThemeMode::Auto,
+        ThemeMode::Light => prefs::ThemeMode::Light,
+        ThemeMode::Dark => prefs::ThemeMode::Dark,
+    }
+}
+
+/// Slint 磁贴尺寸 → 偏好枚举。
+pub fn tile_size_from(size: TileSize) -> prefs::TileSize {
+    match size {
+        TileSize::Small => prefs::TileSize::Small,
+        TileSize::Medium => prefs::TileSize::Medium,
+        TileSize::Large => prefs::TileSize::Large,
+    }
+}
+
+/// Slint 视图模式 → 偏好枚举。
+pub fn instance_view_from(view: InstanceView) -> prefs::InstanceView {
+    match view {
+        InstanceView::Tiles => prefs::InstanceView::Tiles,
+        InstanceView::List => prefs::InstanceView::List,
+    }
+}
+
+/// 下载分类 → core 侧分类枚举。
+pub fn version_category(category: DownloadCategory) -> VersionCategory {
+    match category {
+        DownloadCategory::Release => VersionCategory::Release,
+        DownloadCategory::Snapshot => VersionCategory::Snapshot,
+        DownloadCategory::AncientClassic => VersionCategory::Ancient(dto::AncientKind::Classic),
+        DownloadCategory::AncientAlpha => VersionCategory::Ancient(dto::AncientKind::OldAlpha),
+        DownloadCategory::AncientBeta => VersionCategory::Ancient(dto::AncientKind::OldBeta),
+        DownloadCategory::AncientUnlisted => VersionCategory::Ancient(dto::AncientKind::Unlisted),
+        DownloadCategory::Modpack => VersionCategory::Modpack,
+        DownloadCategory::Mod => VersionCategory::Mod,
+    }
+}
+
+/// 下载分类（偏好 → Slint）——供启动时回填。
+pub fn category_from(category: VersionCategory) -> DownloadCategory {
+    match category {
+        VersionCategory::Release => DownloadCategory::Release,
+        VersionCategory::Snapshot => DownloadCategory::Snapshot,
+        VersionCategory::Ancient(dto::AncientKind::Classic) => DownloadCategory::AncientClassic,
+        VersionCategory::Ancient(dto::AncientKind::OldAlpha) => DownloadCategory::AncientAlpha,
+        VersionCategory::Ancient(dto::AncientKind::OldBeta) => DownloadCategory::AncientBeta,
+        VersionCategory::Ancient(dto::AncientKind::Unlisted) => DownloadCategory::AncientUnlisted,
+        VersionCategory::Modpack => DownloadCategory::Modpack,
+        VersionCategory::Mod => DownloadCategory::Mod,
+    }
+}
+
+/// 背景图填充模式（core 侧枚举 → Slint）。
+pub fn bg_fill(fill: unlucky_core::setting::appearance::BgFill) -> BgFillKind {
+    match fill {
+        unlucky_core::setting::appearance::BgFill::Cover => BgFillKind::Cover,
+        unlucky_core::setting::appearance::BgFill::Contain => BgFillKind::Contain,
+        unlucky_core::setting::appearance::BgFill::Tile => BgFillKind::Tile,
+    }
+}
+
+/// Slint 填充模式 → core 侧枚举。
+pub fn bg_fill_from(fill: BgFillKind) -> unlucky_core::setting::appearance::BgFill {
+    match fill {
+        BgFillKind::Cover => unlucky_core::setting::appearance::BgFill::Cover,
+        BgFillKind::Contain => unlucky_core::setting::appearance::BgFill::Contain,
+        BgFillKind::Tile => unlucky_core::setting::appearance::BgFill::Tile,
+    }
+}
+
+/// 强调色十六进制串 → Slint 颜色；空串/非法值给透明（= 用出厂 accent）。
+pub fn accent_color(hex: &str) -> slint::Color {
+    match unlucky_core::setting::appearance::hex_to_rgb(hex) {
+        Some((r, g, b)) => slint::Color::from_rgb_u8(r, g, b),
+        None => slint::Color::from_argb_u8(0, 0, 0, 0),
+    }
+}
diff --git a/crates/app/src/conv/versions.rs b/crates/app/src/conv/versions.rs
new file mode 100644
index 0000000..7105742
--- /dev/null
+++ b/crates/app/src/conv/versions.rs
@@ -0,0 +1,105 @@
+//! 版本列表与下载分类映射（下载页）。
+
+use crate::{UiVersion, VersionKind};
+use unlucky_presenter::dto::{
+    AncientKind, VersionCategory, VersionKind as DtoVersionKind, VersionSummary,
+};
+use unlucky_presenter::state::AppState;
+
+/// 分类侧栏 → 该分类下的版本（远古版按子类细分）。
+pub fn in_category(category: VersionCategory, kind: DtoVersionKind) -> bool {
+    match (category, kind) {
+        (VersionCategory::Release, DtoVersionKind::Release) => true,
+        (VersionCategory::Snapshot, DtoVersionKind::Snapshot) => true,
+        (VersionCategory::Ancient(expected), DtoVersionKind::Ancient(actual)) => expected == actual,
+        // 未接线的分类（整合包 / Mod）不显示任何版本，而不是把全部版本倒进去
+        (VersionCategory::Modpack | VersionCategory::Mod, _) => false,
+        _ => false,
+    }
+}
+
+/// 版本行（下载页与新建向导共用）。
+pub fn version_rows(versions: &[VersionSummary]) -> Vec<UiVersion> {
+    versions
+        .iter()
+        .map(|version| UiVersion {
+            id: version.id.clone().into(),
+            kind: version_kind(version.kind),
+            released: version.released.clone().into(),
+            installed: version.installed,
+            ancient: version.kind.is_ancient(),
+        })
+        .collect()
+}
+
+/// 下载页版本行（按当前分类 + 「仅已装」+ 版本号筛选词过滤）。
+pub fn versions(state: &AppState) -> Vec<UiVersion> {
+    let query = state.download_query.trim().to_lowercase();
+    let filtered: Vec<VersionSummary> = state
+        .versions
+        .iter()
+        .filter(|version| in_category(state.prefs.download_category, version.kind))
+        .filter(|version| !state.installed_only || version.installed)
+        .filter(|version| query.is_empty() || version.id.to_lowercase().contains(&query))
+        .cloned()
+        .collect();
+    version_rows(&filtered)
+}
+
+fn version_kind(kind: DtoVersionKind) -> VersionKind {
+    match kind {
+        DtoVersionKind::Release => VersionKind::Release,
+        DtoVersionKind::Snapshot => VersionKind::Snapshot,
+        DtoVersionKind::Ancient(AncientKind::Classic) => VersionKind::AncientClassic,
+        DtoVersionKind::Ancient(AncientKind::OldAlpha) => VersionKind::AncientAlpha,
+        DtoVersionKind::Ancient(AncientKind::OldBeta) => VersionKind::AncientBeta,
+        DtoVersionKind::Ancient(AncientKind::Unlisted) => VersionKind::AncientUnlisted,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::versions;
+    use unlucky_presenter::dto::{VersionKind, VersionSummary};
+    use unlucky_presenter::state::AppState;
+
+    fn state_with_versions() -> AppState {
+        let mut state = AppState::new();
+        let row = |id: &str, installed: bool| VersionSummary {
+            id: id.to_string(),
+            kind: VersionKind::Release,
+            released: "2026-01-01".to_string(),
+            installed,
+        };
+        state.versions = vec![
+            row("1.21.9", false),
+            row("1.20.4", true),
+            row("1.20.1", true),
+        ];
+        state
+    }
+
+    #[test]
+    fn installed_only_filter_hides_uninstalled_versions() {
+        let mut state = state_with_versions();
+        assert_eq!(versions(&state).len(), 3);
+
+        state.installed_only = true;
+        let filtered = versions(&state);
+        assert_eq!(filtered.len(), 2);
+        assert!(filtered.iter().all(|version| version.installed));
+    }
+
+    #[test]
+    fn query_filters_by_version_id_substring() {
+        let mut state = state_with_versions();
+        state.download_query = "1.20".to_string();
+        let filtered = versions(&state);
+        assert_eq!(filtered.len(), 2);
+
+        state.download_query = "1.21".to_string();
+        state.installed_only = true;
+        // 「仅已装」优先：1.21.9 未安装 → 空列表
+        assert!(versions(&state).is_empty());
+    }
+}
diff --git a/crates/app/src/main.rs b/crates/app/src/main.rs
new file mode 100644
index 0000000..13e23d9
--- /dev/null
+++ b/crates/app/src/main.rs
@@ -0,0 +1,116 @@
+//! Unlucky-Launcher 桌面壳（`unlucky_app`）：Slint UI + Metro 视觉。
+//!
+//! 边界（决策 D3 / D16）：本 crate 是**唯一**允许依赖 UI 框架的 crate；
+//! 它只经「快照 + 事件流 + 注入的显示服务」消费 core/agent，不直接触碰其内部类型
+//! （P0 的 host 是 `mock` 假后端，`unlucky_presenter::dto` 是唯一跨界类型集合）。
+//!
+//! 渲染策略（`DevDocs/PlanDoc/01c-native-gui-options.md` §6）：
+//! GL 优先（femtovg），启动参数 `--software-renderer` 或 Win7 老机探测失败时切 CPU 软渲染。
+//!
+//! 主题与外观（D17 / 09 §101-113）：
+//! - 主题三态 `appearance.theme_mode ∈ {auto, light, dark}`（出厂 auto）；
+//! - 「外观（高级）」四件（背景图 / 面板半透明度 / 玻璃拟态 / 强调色）出厂全关；
+//! - 全部走 `core::setting` 的 schema（`unlucky_presenter::settings_bridge`），AI 可写并且**热切**
+//!   （tick 里 1s 一次 mtime 比对）；系统主题由 `core::platform::theme_probe` 对齐 + 兜底轮询。
+//!
+//! 一个二进制两种用法（M82）：`unlucky-launcher` 不带子命令时起 GUI；带子命令
+//! （`instances` / `install` / `launch` / `accounts` / `sessions` / `logs` / `diag` /
+//! `config` / `java` / `agent`）时直接转给 `unlucky_cli::run`，**不初始化任何 UI**。
+//! 子命令表不在这里抄一份——唯一真相源是 `crates/cli` 的解析器（见
+//! `unlucky_cli::cli::looks_like_cli`）。
+//! 零 UI 依赖的 `ull` 仍然保留：它连 fontconfig 都不需要，给服务器 / CI / Termux 用。
+//!
+//! 架构分层（本文件只有一个职责：分发 + 把窗口拉起来）：
+//! - `state.rs` / `prefs.rs` / `router.rs` / `dialogs.rs` / `toast.rs`：纯 Rust 状态（可单测，无 Slint）
+//! - `dto/`：跨边界 DTO 与事件/指令
+//! - `conv.rs`：状态 → Slint 视图模型
+//! - `ui_bind.rs` + `callbacks.rs`：窗口/状态/后端缝合 + 回调接线
+//! - `settings_bridge.rs`：`config/launcher.json` 的读写与热切（core::setting 的 schema API）
+//! - `bg_image.rs` + `png.rs`：背景图/模糊层加工与截图编码（09 §101/§103 的预生成手法）
+//! - `mock.rs` + `mock_data.rs`：P0 假后端（脚本化事件）
+//!
+//! 关于 unsafe：本 crate 不写 unsafe，workspace lint 已设 `unsafe_code = "deny"`。
+//! 这里不能升级成 `#![forbid(unsafe_code)]`——Slint 生成的代码自带 `#[allow(unsafe_code)]`，
+//! 而 forbid 无法被内层 allow 覆盖（会直接编译失败）。同理 Slint 生成类型不带文档注释，
+//! 只能在 crate 级放开 `missing_docs`（库 crate 仍由 workspace lint 保持 warn）。
+// 关于 dead_code：P0 骨架里有一批「已定义、等接线」的公共 API——事件通道 / 偏好键登记 /
+// 诊断文案 / mock 数据构造器等，它们被单测覆盖但业务侧要 P1 才用到。逐条 `#[allow]`
+// 会把噪音藏进实现细节，这里统一放开并在 P1 接线时逐个转正（届时删掉本行即可暴露真死码）。
+#![allow(missing_docs, dead_code)]
+
+use std::process::ExitCode;
+
+mod appearance_bind;
+mod bg_image;
+mod callbacks;
+mod callbacks_pages;
+mod conv;
+mod page_sync;
+mod png;
+mod screenshot;
+mod theme_runtime;
+mod ui_bind;
+
+slint::include_modules!();
+
+fn main() -> ExitCode {
+    let args: Vec<String> = std::env::args().skip(1).collect();
+    if let Some(code) = run_cli_if_requested(&args) {
+        return code;
+    }
+    match run_gui() {
+        Ok(()) => ExitCode::SUCCESS,
+        Err(error) => {
+            eprintln!("[run] {error}");
+            ExitCode::FAILURE
+        }
+    }
+}
+
+/// 把窗口拉起来（分发之后的唯一路径）。
+fn run_gui() -> Result<(), slint::PlatformError> {
+    apply_renderer_flag();
+
+    let app = ui_bind::AppUi::with_options(MainWindow::new()?, screenshot::app_options());
+
+    // 截图验收通道（M41 视觉验收；无交互桌面/无 GPU 环境下的唯一可靠取图方式：
+    // 不截屏幕，而是让 Slint 把当前场景渲染进内存像素缓冲再自己编码 PNG）。
+    // P3 追加页面选择与中间态（安装进度 / 启动事件流），见 `crate::screenshot`。
+    if let Some(options) = screenshot::shot_options() {
+        screenshot::capture(&app, &options)?;
+        return Ok(());
+    }
+
+    app.start_timer();
+    app.run()
+}
+
+/// 子命令命中 CLI 就跑 CLI 并以它的退出码收尾；返回 `None` 表示「这不是 CLI 调用，去开窗」。
+///
+/// 这条路径上**不构造窗口、不探后端、不扫字体、不依赖任何图形库**（这些库缺失时同一条命令照样
+/// 跑完，实测见 packaging/README.md §7.4）。`unlucky-launcher launch …` 的耗时因此与首帧无关——
+/// 这句是结构性判断，**没有重量**（原因见 §10-8）。
+///
+/// 「这条命令行算不算 CLI 调用」的判据不在这里重复：`unlucky_cli::cli::looks_like_cli` 是唯一
+/// 一处（M82 复审去重），两个 GUI 二进制都只调它，改语义不会漂。
+fn run_cli_if_requested(args: &[String]) -> Option<ExitCode> {
+    if !unlucky_cli::cli::looks_like_cli(args) {
+        return None;
+    }
+    let mut stdout = std::io::stdout();
+    let mut stderr = std::io::stderr();
+    let code = unlucky_cli::run(args, &mut stdout, &mut stderr);
+    let _ = std::io::Write::flush(&mut stdout);
+    let _ = std::io::Write::flush(&mut stderr);
+    Some(ExitCode::from(u8::try_from(code).unwrap_or(2)))
+}
+
+/// Win7 老机 / 无可用 OpenGL 驱动时的软渲染兜底开关（01c §6 的 Slint 核心卖点）。
+fn apply_renderer_flag() {
+    let software = std::env::args()
+        .skip(1)
+        .any(|arg| arg == "--software-renderer");
+    if software {
+        std::env::set_var("SLINT_BACKEND", "winit-software");
+    }
+}
diff --git a/crates/app/src/page_sync.rs b/crates/app/src/page_sync.rs
new file mode 100644
index 0000000..578e0c8
--- /dev/null
+++ b/crates/app/src/page_sync.rs
@@ -0,0 +1,36 @@
+//! `PageState` global 的状态灌入（从 `ui_bind` 拆出，守 400 行上限）。
+//!
+//! 一个函数只做「AppState → Slint global 属性」的搬运，同步发生在每一拍末尾
+//! （`ui_bind::Inner::sync`）。分文件而不是砍内容：这些字段每一行都对应一个页面元素。
+
+use crate::conv;
+use crate::ui_bind::model;
+use crate::{MainWindow, PageState};
+use slint::ComponentHandle;
+use unlucky_presenter::state::AppState;
+
+/// 把页面状态灌进 `PageState`。
+pub(crate) fn apply(ui: &MainWindow, state: &AppState) {
+    // 导航底部账户 + PageState 全量页面状态（账户/Java/安装/设置/通知/向导）
+    ui.set_account_name(conv::active_account_name(state).into());
+    let page = ui.global::<PageState<'_>>();
+    page.set_accounts(model(conv::accounts(state)));
+    page.set_active_account(conv::active_account_name(state).into());
+    page.set_device(conv::device(state));
+    page.set_java_vendors(model(conv::java_vendors(state)));
+    page.set_java_chain(model(conv::java_chain(state)));
+    page.set_java_runtimes(model(conv::java_runtimes(state)));
+    page.set_java_order(state.java.order_text.clone().into());
+    page.set_java_region(state.java.region.clone().into());
+    page.set_java_priority_source(state.java.priority_source.clone().into());
+    page.set_java_message(state.java.message.clone().into());
+    page.set_java_busy(state.java.busy);
+    let major = state.java.majors().last().copied().unwrap_or(17);
+    page.set_java_target_major(i32::try_from(major).unwrap_or(17));
+    page.set_install(conv::install(state));
+    page.set_setting_groups(model(conv::setting_groups(state)));
+    page.set_setting_tab(state.settings_tab.clone().into());
+    page.set_notices(model(conv::notices(state)));
+    page.set_wizard(conv::wizard(state));
+    page.set_wizard_versions(model(conv::wizard_versions(state)));
+}
diff --git a/crates/app/src/png.rs b/crates/app/src/png.rs
new file mode 100644
index 0000000..94aff5b
--- /dev/null
+++ b/crates/app/src/png.rs
@@ -0,0 +1,140 @@
+//! 极简 PNG 编码器（只做「无压缩 stored deflate」），给截图验收用。
+//!
+//! 为什么不引 `image` / `png` crate：截屏只是开发期验收工具（`--screenshot`），
+//! 为它加一个依赖违反「新依赖过 deny.toml 白名单」的成本收益。PNG 规范里 zlib 流允许
+//! **stored（未压缩）块**，于是我们只需要 CRC32 + Adler32 两个校验和就能产出合法 PNG——
+//! 文件大一些，但任何看图工具都认。
+//!
+//! 输出：8bit RGBA（color type 6），逐行 filter=0（None）。
+
+use slint::{Rgba8Pixel, SharedPixelBuffer};
+
+/// 把 RGBA8 像素缓冲写成 PNG 字节流。
+#[must_use]
+pub fn encode_rgba8(buffer: &SharedPixelBuffer<Rgba8Pixel>) -> Vec<u8> {
+    let width = buffer.width();
+    let height = buffer.height();
+    let pixels = buffer.as_slice();
+
+    // 原始扫描线：每行前面加一个 filter 字节 0
+    let stride = width as usize * 4;
+    let mut raw = Vec::with_capacity((stride + 1) * height as usize);
+    for y in 0..height as usize {
+        raw.push(0u8);
+        for x in 0..width as usize {
+            let pixel = pixels[y * width as usize + x];
+            raw.extend_from_slice(&[pixel.r, pixel.g, pixel.b, pixel.a]);
+        }
+    }
+
+    let mut out = Vec::new();
+    out.extend_from_slice(&[0x89, b'P', b'N', b'G', 0x0d, 0x0a, 0x1a, 0x0a]);
+
+    let mut ihdr = Vec::with_capacity(13);
+    ihdr.extend_from_slice(&width.to_be_bytes());
+    ihdr.extend_from_slice(&height.to_be_bytes());
+    ihdr.extend_from_slice(&[8, 6, 0, 0, 0]); // 位深 8、RGBA、deflate、无交错
+    push_chunk(&mut out, b"IHDR", &ihdr);
+    push_chunk(&mut out, b"IDAT", &zlib_stored(&raw));
+    push_chunk(&mut out, b"IEND", &[]);
+    out
+}
+
+fn push_chunk(out: &mut Vec<u8>, kind: &[u8; 4], data: &[u8]) {
+    out.extend_from_slice(&(data.len() as u32).to_be_bytes());
+    out.extend_from_slice(kind);
+    out.extend_from_slice(data);
+    let mut crc_input = Vec::with_capacity(4 + data.len());
+    crc_input.extend_from_slice(kind);
+    crc_input.extend_from_slice(data);
+    out.extend_from_slice(&crc32(&crc_input).to_be_bytes());
+}
+
+/// zlib 容器 + 全 stored deflate 块（每块上限 65535 字节）。
+fn zlib_stored(raw: &[u8]) -> Vec<u8> {
+    let mut out = Vec::with_capacity(raw.len() + raw.len() / 65_535 * 5 + 16);
+    out.extend_from_slice(&[0x78, 0x01]); // CMF/FLG：deflate、32K 窗口、无字典、最快
+    let mut offset = 0usize;
+    while offset < raw.len() {
+        let len = (raw.len() - offset).min(65_535);
+        let last = offset + len >= raw.len();
+        out.push(u8::from(last)); // BFINAL + BTYPE=00
+        let len_u16 = len as u16;
+        out.extend_from_slice(&len_u16.to_le_bytes());
+        out.extend_from_slice(&(!len_u16).to_le_bytes());
+        out.extend_from_slice(&raw[offset..offset + len]);
+        offset += len;
+    }
+    if raw.is_empty() {
+        out.push(1);
+        out.extend_from_slice(&[0, 0, 0xff, 0xff]);
+    }
+    out.extend_from_slice(&adler32(raw).to_be_bytes());
+    out
+}
+
+fn crc32(data: &[u8]) -> u32 {
+    let mut crc = 0xffff_ffffu32;
+    for byte in data {
+        crc ^= u32::from(*byte);
+        for _ in 0..8 {
+            let mask = (crc & 1).wrapping_neg();
+            crc = (crc >> 1) ^ (0xedb8_8320 & mask);
+        }
+    }
+    !crc
+}
+
+fn adler32(data: &[u8]) -> u32 {
+    let mut a: u32 = 1;
+    let mut b: u32 = 0;
+    for byte in data {
+        a = (a + u32::from(*byte)) % 65_521;
+        b = (b + a) % 65_521;
+    }
+    (b << 16) | a
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn pixel(r: u8, g: u8, b: u8) -> Rgba8Pixel {
+        Rgba8Pixel { r, g, b, a: 255 }
+    }
+
+    #[test]
+    fn header_and_chunks_are_well_formed() {
+        let mut buffer = SharedPixelBuffer::<Rgba8Pixel>::new(3, 2);
+        buffer.make_mut_slice().fill(pixel(1, 2, 3));
+        let bytes = encode_rgba8(&buffer);
+        assert_eq!(
+            &bytes[..8],
+            &[0x89, b'P', b'N', b'G', 0x0d, 0x0a, 0x1a, 0x0a]
+        );
+        // IHDR：宽 3 高 2、8bit、RGBA(6)
+        assert_eq!(&bytes[8..12], &13u32.to_be_bytes());
+        assert_eq!(&bytes[12..16], b"IHDR");
+        assert_eq!(&bytes[16..20], &3u32.to_be_bytes());
+        assert_eq!(&bytes[20..24], &2u32.to_be_bytes());
+        assert_eq!(bytes[24], 8);
+        assert_eq!(bytes[25], 6);
+        // 结尾是 IEND 块
+        assert_eq!(&bytes[bytes.len() - 8..bytes.len() - 4], b"IEND");
+    }
+
+    #[test]
+    fn checksums_match_known_vectors() {
+        // CRC32("IEND") 是公认值 0xAE426082（写进 IEND 块尾）
+        assert_eq!(crc32(b"IEND"), 0xae42_6082);
+        // Adler32("Wikipedia") = 0x11E60398
+        assert_eq!(adler32(b"Wikipedia"), 0x11e6_0398);
+    }
+
+    #[test]
+    fn empty_buffer_still_produces_valid_stream() {
+        let buffer = SharedPixelBuffer::<Rgba8Pixel>::new(0, 0);
+        let bytes = encode_rgba8(&buffer);
+        assert!(bytes.windows(4).any(|window| window == b"IDAT"));
+    }
+}
diff --git a/crates/app/src/screenshot.rs b/crates/app/src/screenshot.rs
new file mode 100644
index 0000000..7c761f0
--- /dev/null
+++ b/crates/app/src/screenshot.rs
@@ -0,0 +1,177 @@
+//! 截图验收通道的参数解析与流程（`--screenshot*` / `--data-dir` / `--mock`）。
+//!
+//! 为什么用进程内渲染而不是截屏：验收机没有交互桌面（`CopyFromScreen` 直接失败），
+//! 而 Slint 的软件渲染器能把场景渲进内存像素缓冲（`Window::take_snapshot`），
+//! 结果与屏幕上逐像素一致且不需要 GPU（M41 落地的通道，这里只加页面/中间态参数）。
+//!
+//! 中间态（安装进度 / 启动事件流）走真实后端：`--screenshot-install <版本>` 会真的发起
+//! 一次安装并停若干毫秒后取图，`--screenshot-launch <实例>` 同理。
+
+use std::path::PathBuf;
+
+use crate::ui_bind::AppUi;
+use unlucky_presenter::backend::AppOptions;
+use unlucky_presenter::dto::AppCommand;
+
+/// 一次截图请求。
+#[derive(Debug, Clone, Default)]
+pub struct ShotOptions {
+    /// 输出 PNG 路径
+    pub path: String,
+    /// 页面名（instances / download / java / logs / settings / account / appearance / agent）
+    pub page: Option<String>,
+    /// 打开新建实例向导
+    pub wizard: bool,
+    /// 发起一次真实安装并停 `dwell_ms` 后取图（中间态）
+    pub install: Option<String>,
+    /// 安装走哪个加载器（`--screenshot-loader forge`；缺省 = 原版）
+    pub loader: Option<String>,
+    /// 发起一次真实启动并停 `dwell_ms` 后取图（中间态）
+    pub launch: Option<String>,
+    /// 打开一个日志会话（日志页有数据态：日志行 + 诊断卡片）
+    pub session: Option<String>,
+    /// 中间态停留毫秒（默认 2500）
+    pub dwell_ms: u64,
+}
+
+impl ShotOptions {
+    /// 中间态默认停留时长。
+    pub const DEFAULT_DWELL_MS: u64 = 2_500;
+}
+
+/// 从命令行读启动选项（数据根 / mock）。
+pub fn app_options() -> AppOptions {
+    AppOptions {
+        data_root: value_of("--data-dir").map(PathBuf::from),
+        mock: flag("--mock"),
+    }
+}
+
+/// 从命令行读截图请求；没有 `--screenshot` 时返回 `None`。
+pub fn shot_options() -> Option<ShotOptions> {
+    let path = value_of("--screenshot")?;
+    let page = value_of("--screenshot-page");
+    let mut options = ShotOptions {
+        path,
+        page: if flag("--screenshot-settings") {
+            Some("appearance".to_string())
+        } else {
+            page
+        },
+        wizard: flag("--screenshot-wizard"),
+        install: value_of("--screenshot-install"),
+        loader: value_of("--screenshot-loader"),
+        launch: value_of("--screenshot-launch"),
+        session: value_of("--screenshot-session"),
+        dwell_ms: value_of("--screenshot-dwell")
+            .and_then(|value| value.parse().ok())
+            .unwrap_or(ShotOptions::DEFAULT_DWELL_MS),
+    };
+    if options.dwell_ms < 500 {
+        options.dwell_ms = 500;
+    }
+    options.page = options.page.filter(|page| !page.trim().is_empty());
+    Some(options)
+}
+
+/// 执行截图流程：切页 → （可选）中间态 → 渲染 PNG。
+///
+/// # Errors
+/// 窗口显示/快照/写文件失败时返回错误。
+pub fn capture(app: &AppUi, options: &ShotOptions) -> Result<(), slint::PlatformError> {
+    if let Some(page) = &options.page {
+        app.open_page(page);
+        // 先给后端一次全量刷新：版本清单要在后台线程里拉（12h 缓存），
+        // 下载页/Java 页/向导需要它才有「有数据态」。
+        let warmup = if matches!(page.as_str(), "download" | "java") {
+            4_000
+        } else {
+            1_200
+        };
+        app.dispatch_and_run(AppCommand::RefreshAll, warmup);
+    }
+    if options.wizard {
+        app.open_wizard();
+    }
+    if let Some(version) = &options.install {
+        app.dispatch_and_run(
+            install_command(version, options.loader.as_deref()),
+            options.dwell_ms,
+        );
+    }
+    if let Some(session) = &options.session {
+        app.open_session(session);
+        app.dispatch_and_run(AppCommand::RefreshLogSessions, options.dwell_ms.min(1_000));
+    }
+    if let Some(instance) = &options.launch {
+        app.dispatch_and_run(
+            AppCommand::LaunchInstance(instance.clone()),
+            options.dwell_ms,
+        );
+    }
+    app.render_screenshot(&options.path)?;
+    // 启动中间态截完就把进程收掉：截图进程退出后子进程会变孤儿，
+    // 所以在取图之后显式 stop（kill_tree），不留给系统。
+    if let Some(instance) = &options.launch {
+        app.dispatch_and_run(AppCommand::StopInstance(instance.clone()), 1_500);
+    }
+    Ok(())
+}
+
+/// 截图通道的安装指令：缺省原版，给了 `--screenshot-loader` 就走向导同一条路
+/// （`CreateInstance`），因此 Forge/NeoForge 的中间态也能取图。
+fn install_command(version: &str, loader: Option<&str>) -> AppCommand {
+    match loader.map(unlucky_presenter::dto::LoaderKind::parse) {
+        Some(Some(kind)) => AppCommand::CreateInstance(unlucky_presenter::dto::CreateRequest {
+            version: version.to_string(),
+            loader: kind,
+            loader_version: String::new(),
+            name: version.to_string(),
+        }),
+        _ => AppCommand::InstallVersion(version.to_string()),
+    }
+}
+
+/// `--flag` 是否存在。
+pub fn flag(name: &str) -> bool {
+    std::env::args().skip(1).any(|arg| arg == name)
+}
+
+/// `--key value` / `--key=value` 的取值。
+pub fn value_of(name: &str) -> Option<String> {
+    let mut args = std::env::args().skip(1);
+    while let Some(arg) = args.next() {
+        if let Some(value) = arg.strip_prefix(&format!("{name}=")) {
+            return Some(value.to_string());
+        }
+        if arg == name {
+            return args.next();
+        }
+    }
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn default_dwell_is_a_visible_mid_state() {
+        const DEFAULT: u64 = ShotOptions::DEFAULT_DWELL_MS;
+        let dwell = DEFAULT;
+        assert!(dwell >= 1_000, "中间态至少要停 1 秒才看得见进度");
+    }
+
+    #[test]
+    fn options_without_screenshot_are_none() {
+        // 测试进程没有 --screenshot 参数
+        assert!(
+            shot_options().is_none() || std::env::args().any(|arg| arg.contains("--screenshot"))
+        );
+    }
+
+    #[test]
+    fn value_of_ignores_absent_flags() {
+        assert!(value_of("--definitely-not-a-real-flag").is_none());
+    }
+}
diff --git a/crates/app/src/theme_runtime.rs b/crates/app/src/theme_runtime.rs
new file mode 100644
index 0000000..b8fccab
--- /dev/null
+++ b/crates/app/src/theme_runtime.rs
@@ -0,0 +1,152 @@
+//! 主题与外观的运行期逻辑（从 `ui_bind.rs` 拆出，守住单文件 ≤400 行）。
+//!
+//! 全是 `impl Inner` 的方法：配置热切轮询、系统主题对齐、外观令牌下发、背景图/模糊层重建。
+//! 拆出来的边界是「时间驱动的状态维护」——`ui_bind.rs` 只留「建窗口 + 每拍驱动 + 灌属性」。
+
+use slint::ComponentHandle;
+
+use crate::bg_image::{self, BackgroundLayers};
+use crate::conv;
+use crate::ui_bind::Inner;
+use unlucky_presenter::prefs::{AppearancePrefs, BgFill, ThemeMode};
+use unlucky_presenter::theme::{
+    config_poll_due, system_theme_poll_due, system_theme_value, BackgroundKey,
+};
+use unlucky_presenter::toast::ToastKind;
+
+impl Inner {
+    pub(crate) fn poll_settings(&self) {
+        if !config_poll_due(self.ticks.get()) {
+            return;
+        }
+        let Some((appearance, theme)) = self.bridge.borrow_mut().reload_if_changed() else {
+            return;
+        };
+        {
+            let mut state = self.state.borrow_mut();
+            state.prefs.appearance = appearance;
+            state.prefs.theme = theme;
+        }
+        self.apply_theme();
+        self.apply_appearance();
+    }
+
+    /// 系统主题对齐：启动时先读一次真实系统主题（避免 auto 首帧按浅色画再翻黑）；
+    /// 之后仅在「auto + 后端不认识系统主题」（`Theme.system-theme-known == false`）时兜底轮询。
+    pub(crate) fn poll_system_theme(&self) {
+        let auto = matches!(self.state.borrow().prefs.theme, ThemeMode::Auto);
+        let backend_known = self.ui.get_system_theme_known();
+        let due = system_theme_poll_due(
+            self.system_theme_probed.get(),
+            auto,
+            backend_known,
+            self.ticks.get(),
+        );
+        if !due {
+            return;
+        }
+        self.system_theme_probed.set(true);
+        let value = system_theme_value();
+        if self.ui.get_system_theme() != value {
+            self.ui.set_system_theme(value);
+        }
+    }
+
+    /// 启动时的系统主题对齐（首帧前调用一次）。
+    pub(crate) fn align_system_theme(&self) {
+        self.poll_system_theme();
+    }
+
+    /// 主题三态 → 根组件属性；`ui/main.slint` 里的 changed 处理器再赋给 `Theme` 全局
+    /// （auto 时 Theme 内部读系统的 `Palette.color-scheme` 与本进程探测到的系统主题）。
+    pub(crate) fn apply_theme(&self) {
+        let mode = self.state.borrow().prefs.theme;
+        self.ui.set_theme_mode(conv::theme_mode(mode));
+    }
+
+    /// 外观（高级）四件 → 根组件属性（进而写进 `Theme` 全局）。
+    ///
+    /// 背景图只在「开关打开 + 路径非空 + 换了输入」时才重新解码/生成模糊层。
+    pub(crate) fn apply_appearance(&self) {
+        let appearance = self.state.borrow().prefs.appearance.clone();
+        self.ui.set_bg_fill(conv::bg_fill(appearance.bg_fill));
+        self.ui.set_bg_dim(appearance.bg_dim.clamp(0.0, 0.9));
+        self.ui
+            .set_panel_alpha(appearance.panel_alpha.clamp(0.4, 1.0));
+        self.ui.set_glass(appearance.glass);
+        self.ui
+            .set_accent_color(conv::accent_color(&appearance.accent_color));
+        self.ui
+            .set_accent_hex(appearance.accent_color.clone().into());
+        self.refresh_background(&appearance);
+    }
+
+    /// 按需重建背景图 + 模糊层。
+    fn refresh_background(&self, appearance: &AppearancePrefs) {
+        if !appearance.bg_active() {
+            let had = self.background_key.borrow_mut().take().is_some();
+            if had {
+                self.background.replace(BackgroundLayers::default());
+                self.ui.set_background_image(slint::Image::default());
+                self.ui.set_background_blur(slint::Image::default());
+            }
+            return;
+        }
+
+        let key = BackgroundKey {
+            path: appearance.bg_image.clone(),
+            fill: appearance.bg_fill,
+            viewport: self.tile_viewport(appearance.bg_fill),
+        };
+        if self.background_key.borrow().as_ref() == Some(&key) {
+            return;
+        }
+        self.background_key.replace(Some(key.clone()));
+
+        // 模糊层按窗口物理尺寸放大（软件渲染器不做图片缩放插值，见 bg_image::prepare）；
+        // tile 之外的模式窗口缩放不重建画布，模糊层被拉伸也无感。
+        let real_viewport = self.window_physical_size();
+        match bg_image::prepare(&key.path, key.fill, real_viewport) {
+            Some(layers) => {
+                self.ui.set_background_image(layers.image.clone());
+                self.ui.set_background_blur(layers.blur.clone());
+                self.background.replace(layers);
+            }
+            None => {
+                // 载入失败（路径不存在 / 不是 PNG）：清空图层并提示一次，别留上一张图的残影
+                self.background.replace(BackgroundLayers::default());
+                self.ui.set_background_image(slint::Image::default());
+                self.ui.set_background_blur(slint::Image::default());
+                self.state.borrow_mut().toasts.push(
+                    ToastKind::Warn,
+                    "背景图载入失败（当前只支持 PNG，且路径需存在）",
+                );
+            }
+        }
+    }
+
+    /// tile 画布的窗口尺寸（量化到 `TILE_REGENERATE_STEP`，避免拖动窗口时反复重算）。
+    ///
+    /// 判据在 [`unlucky_presenter::theme::tile_viewport`]（两侧 UI 共用一份）；这里只负责
+    /// 提供窗口物理尺寸。
+    fn tile_viewport(&self, fill: BgFill) -> (u32, u32) {
+        if fill != BgFill::Tile {
+            return (0, 0);
+        }
+        unlucky_presenter::theme::tile_viewport(fill, self.window_physical_size())
+    }
+
+    /// 窗口物理像素尺寸（取不到时 (0, 0)，tile 退化为单块）。
+    fn window_physical_size(&self) -> (u32, u32) {
+        let size = self.ui.window().size();
+        (size.width, size.height)
+    }
+
+    /// 落盘当前偏好（主题 + 外观四件）。
+    pub(crate) fn persist_settings(&self) {
+        let state = self.state.borrow();
+        self.bridge
+            .borrow_mut()
+            .persist(&state.prefs.appearance, state.prefs.theme);
+    }
+}
diff --git a/crates/app/src/ui_bind.rs b/crates/app/src/ui_bind.rs
new file mode 100644
index 0000000..6b5d07e
--- /dev/null
+++ b/crates/app/src/ui_bind.rs
@@ -0,0 +1,314 @@
+//! 绑定层（核心）：窗口/状态/后端的持有与同步；回调接线在 [`crate::callbacks`]。
+//!
+//! P0 的“后端”是 [`MockBackend`]（脚本化假数据）；把 `Box<dyn Backend>` 换成真实的 core/agent
+//! host 时，除本文件、`conv.rs`、`callbacks.rs` 外都不需要改
+//! （通道语义见 `DevDocs/SubAgentsTalk/app-DTO通道约定.md`）。
+//!
+//! 主题与外观（D17 / 09 §101-113）：落盘配置由 [`SettingsBridge`] 读写（`config/launcher.json`，
+//! 与 `ull config set` 同一份），tick 里 1s 一次 `mtime` 热切；系统主题由
+//! `core::platform::theme_probe` 做启动对齐 + 后端不支持时的兜底轮询。
+
+use std::cell::{Cell, RefCell};
+use std::rc::Rc;
+use std::time::Duration;
+
+use slint::{ComponentHandle, ModelRc, VecModel};
+
+use crate::bg_image::BackgroundLayers;
+use crate::conv;
+use crate::{MainWindow, PageState, SettingSection};
+use unlucky_presenter::backend::{build_backend, config_path, AppOptions};
+use unlucky_presenter::dto::{AppCommand, Backend};
+use unlucky_presenter::settings_bridge::SettingsBridge;
+use unlucky_presenter::state::AppState;
+use unlucky_presenter::theme::BackgroundKey;
+
+/// 定时器节拍：33ms ≈ 30fps（磁贴进度环 / 流式文本 / Toast TTL 的刷新下限）。
+const TICK_MS: u64 = 33;
+
+/// 应用外壳：持有窗口、状态与后端，把三者缝在一起。
+pub struct AppUi {
+    inner: Rc<Inner>,
+    timer: slint::Timer,
+}
+
+pub(crate) struct Inner {
+    pub(crate) ui: MainWindow,
+    pub(crate) state: RefCell<AppState>,
+    pub(crate) backend: RefCell<Box<dyn Backend>>,
+    /// `config/launcher.json` 读写桥（app 不自己写盘：一律走 core::setting 的 schema API）
+    pub(crate) bridge: RefCell<SettingsBridge>,
+    /// 当前背景图 / 模糊层（避免每次同步都重新解码）
+    pub(crate) background: RefCell<BackgroundLayers>,
+    /// 生成 `background` 时的输入（路径 / 填充模式 / 窗口粒度尺寸）
+    pub(crate) background_key: RefCell<Option<BackgroundKey>>,
+    /// 拍数（轮询节拍）
+    pub(crate) ticks: Cell<u64>,
+    /// 是否已经做过启动时的系统主题对齐
+    pub(crate) system_theme_probed: Cell<bool>,
+}
+
+impl AppUi {
+    /// 建状态 + 真实后端、读配置、接全部回调、灌初始事件并做第一次同步。
+    pub fn new(ui: MainWindow) -> Self {
+        Self::with_options(ui, AppOptions::default())
+    }
+
+    /// 带启动选项装配（数据根覆盖 / 强制 mock）。
+    pub fn with_options(ui: MainWindow, options: AppOptions) -> Self {
+        // 先读一次落盘配置：主题三态 + 外观四件必须在首帧前就位（否则会闪一下出厂外观）
+        let bridge = match &options.data_root {
+            Some(root) => SettingsBridge::with_path(config_path(root)),
+            None => SettingsBridge::open(),
+        };
+        let (appearance, theme) = bridge.load();
+        let mut state = AppState::new();
+        state.prefs.appearance = appearance;
+        state.prefs.theme = theme;
+
+        let backend = build_backend(&options);
+        let inner = Rc::new(Inner {
+            ui,
+            state: RefCell::new(state),
+            backend: RefCell::new(backend),
+            bridge: RefCell::new(bridge),
+            background: RefCell::new(BackgroundLayers::default()),
+            background_key: RefCell::new(None),
+            ticks: Cell::new(0),
+            system_theme_probed: Cell::new(false),
+        });
+
+        crate::callbacks::wire(Rc::downgrade(&inner));
+        crate::callbacks_pages::wire_pages(Rc::downgrade(&inner));
+        inner.drain_events();
+        inner.align_system_theme();
+        inner.apply_theme();
+        inner.apply_appearance();
+        inner.sync();
+
+        Self {
+            inner,
+            timer: slint::Timer::default(),
+        }
+    }
+
+    /// 进入 Slint 事件循环（窗口句柄由本结构持有，直到循环退出）。
+    pub fn run(&self) -> Result<(), slint::PlatformError> {
+        self.inner.ui.run()
+    }
+
+    /// 启动 33ms 节拍（后端 tick → 事件 → 状态 → UI）。
+    pub fn start_timer(&self) {
+        let inner = Rc::clone(&self.inner);
+        self.timer.start(
+            slint::TimerMode::Repeated,
+            Duration::from_millis(TICK_MS),
+            move || inner.tick(),
+        );
+    }
+
+    /// 推进一拍（截图通道用：没有事件循环时手动把 tick 走起来，让 mock 事件灌进状态）。
+    pub fn tick_once(&self) {
+        self.inner.tick();
+        slint::platform::update_timers_and_animations();
+    }
+
+    /// 直接跳到「设置 → 外观」页（截图验收用：证明外观分组的四组控件真的接线了）。
+    pub fn open_settings_appearance(&self) {
+        self.inner
+            .state
+            .borrow_mut()
+            .navigate(unlucky_presenter::router::Route::Settings);
+        self.inner.sync();
+        self.inner
+            .ui
+            .set_settings_section(SettingSection::Appearance);
+        slint::platform::update_timers_and_animations();
+    }
+
+    /// 直接跳到一个页面（截图验收用：每页一张）。
+    pub fn open_page(&self, page: &str) {
+        let route = match page {
+            "download" | "java" => unlucky_presenter::router::Route::Download,
+            "logs" => unlucky_presenter::router::Route::Logs,
+            "settings" | "account" | "appearance" => unlucky_presenter::router::Route::Settings,
+            "agent" => unlucky_presenter::router::Route::Agent,
+            _ => unlucky_presenter::router::Route::Instances,
+        };
+        {
+            let mut state = self.inner.state.borrow_mut();
+            state.navigate(route);
+            match page {
+                "account" => state.settings_tab = "account".to_string(),
+                "java" => state.settings_tab = "java".to_string(),
+                "settings" => state.settings_tab = "download".to_string(),
+                _ => {}
+            }
+            let download_tab = i32::from(page == "java");
+            self.inner
+                .ui
+                .global::<PageState<'_>>()
+                .set_download_tab(download_tab);
+        }
+        match page {
+            "account" => self.inner.ui.set_settings_section(SettingSection::Account),
+            "java" => self.inner.ui.set_settings_section(SettingSection::Java),
+            "appearance" => self
+                .inner
+                .ui
+                .set_settings_section(SettingSection::Appearance),
+            "settings" => self.inner.ui.set_settings_section(SettingSection::Download),
+            _ => {}
+        }
+        self.inner.sync();
+        slint::platform::update_timers_and_animations();
+    }
+
+    /// 打开新建实例向导（截图验收用）。
+    pub fn open_wizard(&self) {
+        self.inner.state.borrow_mut().wizard = unlucky_presenter::wizard::WizardState::open();
+        self.inner.sync();
+        slint::platform::update_timers_and_animations();
+    }
+
+    /// 打开一个日志会话（截图验收：日志行 + 诊断卡片 + 头部标题都要有值）。
+    pub fn open_session(&self, id: &str) {
+        self.inner.state.borrow_mut().selected_session = Some(id.to_string());
+        self.inner
+            .dispatch(AppCommand::OpenLogSession(id.to_string()));
+        self.inner.sync();
+        slint::platform::update_timers_and_animations();
+    }
+
+    /// 派发一条指令并跑若干毫秒（截图中间态：安装进度 / 启动事件流）。
+    pub fn dispatch_and_run(&self, command: AppCommand, millis: u64) {
+        self.inner.dispatch(command);
+        let steps = (millis / TICK_MS).max(1);
+        for _ in 0..steps {
+            self.inner.tick();
+            slint::platform::update_timers_and_animations();
+            std::thread::sleep(Duration::from_millis(TICK_MS));
+        }
+    }
+
+    /// 渲染当前场景并存成 PNG（`--screenshot` 通道；见 `crate::png`）。
+    ///
+    /// 为什么要这条通道：验收环境可能没有交互桌面（`CopyFromScreen` 直接失败），
+    /// 而 Slint 的软件渲染器可以把场景渲染进内存像素缓冲（`Window::take_snapshot`），
+    /// 结果与屏幕上看到的逐像素一致，且不需要 GPU。
+    ///
+    /// # Errors
+    /// 窗口显示失败、快照失败或写文件失败时返回错误。
+    pub fn render_screenshot(&self, path: &str) -> Result<(), slint::PlatformError> {
+        let ui = &self.inner.ui;
+        ui.show()?;
+        // 固定逻辑尺寸 = main.slint 的默认窗口口径，保证验收图可比
+        ui.window()
+            .set_size(slint::WindowSize::Logical(slint::LogicalSize::new(
+                1180.0, 760.0,
+            )));
+        // 先走几拍：把后端事件（实例/版本/日志/账户/设置）与 33ms 节拍的效果灌进去
+        for _ in 0..8 {
+            self.tick_once();
+            std::thread::sleep(Duration::from_millis(TICK_MS));
+        }
+        let buffer = ui.window().take_snapshot()?;
+        let bytes = crate::png::encode_rgba8(&buffer);
+        std::fs::write(path, bytes)
+            .map_err(|error| slint::PlatformError::Other(format!("写截图失败 {path}: {error}")))?;
+        Ok(())
+    }
+}
+
+/// 发送一条 AI 提问：**只发指令 + 回流事件**，绝不做本地乐观回显。
+///
+/// 契约 §3 规定 host 先发 `MessageAppended(user)`：本地再 push 一次用户消息就会重复；
+/// 且流式气泡的收敛依赖事件里的 `MessageFinished{index}`，本地多建的占位会变成
+/// 永不收敛的「幽灵气泡」（review P1-1）。callbacks 与单测都走这一个入口。
+pub(crate) fn send_agent_message(state: &mut AppState, backend: &mut dyn Backend, text: &str) {
+    backend.dispatch(AppCommand::AskAgent(text.to_string()));
+    for event in backend.drain_events() {
+        state.apply(event);
+    }
+}
+
+impl Inner {
+    /// 走一次完整的「提问 → 事件回流」。
+    pub(crate) fn ask_agent(&self, text: &str) {
+        let mut state = self.state.borrow_mut();
+        let mut backend = self.backend.borrow_mut();
+        send_agent_message(&mut state, backend.as_mut(), text);
+    }
+
+    pub(crate) fn dispatch(&self, command: AppCommand) {
+        self.backend.borrow_mut().dispatch(command);
+        self.drain_events();
+    }
+
+    pub(crate) fn drain_events(&self) {
+        let events = self.backend.borrow_mut().drain_events();
+        if events.is_empty() {
+            return;
+        }
+        let mut state = self.state.borrow_mut();
+        for event in events {
+            state.apply(event);
+        }
+    }
+
+    fn tick(&self) {
+        self.backend
+            .borrow_mut()
+            .tick(Duration::from_millis(TICK_MS));
+        self.drain_events();
+        self.state.borrow_mut().toasts.expire(TICK_MS);
+        self.ticks.set(self.ticks.get() + 1);
+        self.poll_settings();
+        self.poll_system_theme();
+        self.sync();
+    }
+
+    pub(crate) fn sync(&self) {
+        let state = self.state.borrow();
+        let ui = &self.ui;
+
+        ui.set_route(conv::route(state.route()));
+        ui.set_nav_collapsed(state.prefs.nav_collapsed);
+        ui.set_ai_collapsed(state.prefs.ai_collapsed);
+        ui.set_tile_size(conv::tile_size(state.prefs.tile_size));
+        ui.set_instance_view(conv::instance_view(state.prefs.instance_view));
+        ui.set_download_category(conv::category_from(state.prefs.download_category));
+        ui.set_download_installed_only(state.installed_only);
+        ui.set_theme_mode(conv::theme_mode(state.prefs.theme));
+
+        ui.set_tiles(model(conv::tiles(&state)));
+        ui.set_running_tiles(model(conv::running_tiles(&state)));
+        ui.set_versions(model(conv::versions(&state)));
+        ui.set_log_sessions(model(conv::log_sessions(&state)));
+        ui.set_log_lines(model(conv::log_lines(&state)));
+        ui.set_toasts(model(conv::toasts(&state)));
+
+        let (diagnosis, has_diagnosis) = conv::diagnosis(&state);
+        ui.set_diagnosis(diagnosis);
+        ui.set_has_diagnosis(has_diagnosis);
+        ui.set_selected_session(state.selected_session.clone().unwrap_or_default().into());
+
+        ui.set_ai_messages(model(conv::chat(&state)));
+        ui.set_ai_streaming(state.ai.streaming);
+        ui.set_yolo(state.ai.yolo);
+        ui.set_ai_endpoint_label(state.ai.endpoint_label.clone().into());
+
+        let (dialog, open, queued) = conv::dialog(&state);
+        ui.set_dialog(dialog);
+        ui.set_dialog_open(open);
+        ui.set_dialog_queued(queued);
+
+        // PageState（账户/Java/安装/设置/通知/向导）在独立模块里灌，守 400 行
+        crate::page_sync::apply(ui, &state);
+    }
+}
+
+/// Slint 列表模型（VecModel → ModelRc）。
+pub(crate) fn model<T: Clone + 'static>(items: Vec<T>) -> ModelRc<T> {
+    ModelRc::new(VecModel::from(items))
+}
diff --git a/crates/app/ui/components/ai-panel.slint b/crates/app/ui/components/ai-panel.slint
new file mode 100644
index 0000000..a9982f1
--- /dev/null
+++ b/crates/app/ui/components/ai-panel.slint
@@ -0,0 +1,283 @@
+// 右侧 AI 常驻栏（D16 §1）：默认 320px 可折叠；可「展开为页面」变成全宽独立页，
+// 两形态共享同一份会话模型（由 Rust 侧 AiSession 持有，这里只渲染，切换不丢状态）。
+// 栏顶承载 YOLO 快捷开关（D4 补充）与端点标签。
+import { Theme } from "../theme/tokens.slint";
+import { Metrics } from "../theme/metrics.slint";
+import { UiChatMessage, ChatRole } from "../models.slint";
+import { UiText, TextRole } from "label.slint";
+import { AppIcon, IconKind } from "icons.slint";
+import { MetroButton, ButtonKind } from "../widgets/button.slint";
+import { PlainInput } from "../widgets/inputs.slint";
+import { GlassBase } from "glass.slint";
+import { ListView } from "std-widgets.slint";
+
+// 一条会话消息：user 靠右（accent-soft 块）/ assistant 靠左 / tool 用状态边框 / system 居中弱化
+component ChatBubble inherits Rectangle {
+    in property <UiChatMessage> message;
+
+    property <bool> is-tool: message.role == ChatRole.tool;
+    property <bool> is-system: message.role == ChatRole.system;
+    property <length> text-width: root.width - 2 * Metrics.gap-2;
+    property <length> tool-row: is-tool ? 16px : 0px;
+
+    height: text-node.preferred-height + 2 * Metrics.gap-2 + tool-row;
+    background: message.role == ChatRole.user
+            ? Theme.accent-soft
+        : is-tool ? Theme.bg-canvas
+        : is-system ? transparent
+        : Theme.bg-elevated;
+    border-radius: Metrics.radius-md;
+    border-width: is-tool ? 1px : 0px;
+    border-color: message.tool_ok ? Theme.state-success : Theme.state-danger;
+
+    // 工具调用可视化（D4 要求：工具执行在会话里可见）
+    if is-tool : AppIcon {
+        x: Metrics.gap-2;
+        y: Metrics.gap-2 + 1px;
+        icon-size: 12px;
+        kind: message.tool_ok ? IconKind.check : IconKind.error;
+        tint: message.tool_ok ? Theme.state-success : Theme.state-danger;
+    }
+    if is-tool : UiText {
+        x: Metrics.gap-2 + 16px;
+        y: Metrics.gap-2;
+        width: text-width - 16px;
+        height: 14px;
+        role: TextRole.caption;
+        text: "工具 · " + message.tool_name;
+        color: message.tool_ok ? Theme.state-success : Theme.state-danger;
+    }
+
+    text-node := UiText {
+        x: Metrics.gap-2;
+        y: Metrics.gap-2 + tool-row;
+        width: text-width;
+        height: text-node.preferred-height;
+        role: TextRole.body;
+        text: message.text;
+        wrap: word-wrap;
+        overflow: elide;
+        vertical-alignment: top;
+        horizontal-alignment: message.role == ChatRole.user ? right : left;
+        color: is-system ? Theme.fg-secondary : Theme.fg-primary;
+    }
+
+    // 流式未收敛：末尾的 accent 光标块
+    if message.streaming : Rectangle {
+        x: 0;
+        y: root.height - 10px;
+        width: 8px;
+        height: 10px;
+        background: Theme.accent;
+    }
+}
+
+export component AiPanel inherits Rectangle {
+    in property <[UiChatMessage]> messages;
+    in-out property <bool> collapsed: false;
+    /// true = 停在右侧栏形态；false = 已拆成独立全宽页
+    in property <bool> docked: true;
+    in property <bool> yolo: false;
+    in property <bool> streaming: false;
+    in property <string> endpoint-label: "llama.cpp · 本地";
+    in-out property <string> draft: "";
+
+    callback toggle-collapsed();
+    callback expand();
+    callback dock();
+    callback toggle-yolo();
+    callback send(string);
+    callback stop();
+
+    // 栏形态用 min/max 钉死宽度（布局里等价于固定宽度），页形态交给父容器铺满
+    min-width: docked ? (collapsed ? Metrics.ai-rail-width : Metrics.ai-panel-width) : 0px;
+    max-width: docked ? (collapsed ? Metrics.ai-rail-width : Metrics.ai-panel-width) : 100000px;
+    horizontal-stretch: docked ? 0 : 1;
+    height: 100%;
+    background: Theme.bg-surface;
+
+    // 玻璃拟态底（D17 高级特性；关闭态不画东西）——排在内容之前，压在最底层
+    GlassBase { card-radius: 0px; }
+
+    // 左边界线
+    Rectangle {
+        x: 0;
+        y: 0;
+        width: 1px;
+        height: root.height;
+        background: Theme.stroke;
+    }
+
+    // ── 折叠态：icon 轨 ─────────────────────────────────────────
+    if docked && collapsed : VerticalLayout {
+        x: 1px;
+        width: root.width - 1px;
+        height: root.height;
+        padding-top: Metrics.gap-2;
+        padding-bottom: Metrics.gap-2;
+        spacing: Metrics.gap-2;
+
+        AppIcon {
+            kind: IconKind.ai;
+            icon-size: 18px;
+            tint: Theme.accent;
+
+            TouchArea {
+                mouse-cursor: pointer;
+                clicked => { root.toggle-collapsed(); }
+            }
+        }
+
+        AppIcon {
+            kind: IconKind.expand;
+            icon-size: 14px;
+            tint: Theme.fg-secondary;
+
+            TouchArea {
+                mouse-cursor: pointer;
+                clicked => { root.expand(); }
+            }
+        }
+
+        Rectangle { vertical-stretch: 1; background: transparent; }
+
+        // YOLO 指示点：开启时实心 accent
+        Rectangle {
+            width: 6px;
+            height: 6px;
+            border-radius: 3px;
+            background: root.yolo ? Theme.accent : Theme.stroke-strong;
+        }
+    }
+
+    // ── 展开态：栏内 / 独立页共用 ────────────────────────────────
+    if !(docked && collapsed) : VerticalLayout {
+        x: 1px;
+        width: root.width - 1px;
+        height: root.height;
+
+        // 头部
+        Rectangle {
+            height: 52px;
+            background: transparent;
+
+            HorizontalLayout {
+                padding-left: Metrics.gap-3;
+                padding-right: Metrics.gap-2;
+                spacing: Metrics.gap-2;
+
+                AppIcon { kind: IconKind.ai; icon-size: 16px; tint: Theme.accent; }
+
+                VerticalLayout {
+                    spacing: 0px;
+                    vertical-stretch: 1;
+
+                    UiText {
+                        role: TextRole.bodyStrong;
+                        text: "AI 助手";
+                        horizontal-stretch: 1;
+                    }
+                    UiText {
+                        role: TextRole.caption;
+                        text: root.endpoint-label;
+                        horizontal-stretch: 1;
+                    }
+                }
+
+                MetroButton {
+                    kind: root.yolo ? ButtonKind.accent : ButtonKind.subtle;
+                    text: "YOLO";
+                    button-height: 24px;
+                    clicked => { root.toggle-yolo(); }
+                }
+
+                if root.docked : MetroButton {
+                    kind: ButtonKind.subtle;
+                    icon: IconKind.expand;
+                    icon-only: true;
+                    button-height: 24px;
+                    clicked => { root.expand(); }
+                }
+                if !root.docked : MetroButton {
+                    kind: ButtonKind.subtle;
+                    icon: IconKind.sidebar;
+                    icon-only: true;
+                    button-height: 24px;
+                    clicked => { root.dock(); }
+                }
+                if root.docked : MetroButton {
+                    kind: ButtonKind.subtle;
+                    icon: IconKind.chevronRight;
+                    icon-only: true;
+                    button-height: 24px;
+                    clicked => { root.toggle-collapsed(); }
+                }
+            }
+        }
+
+        Rectangle { height: 1px; background: Theme.stroke; }
+
+        // 对话流（ListView 行虚拟化，research/01 已确认）
+        ListView {
+            vertical-stretch: 1;
+
+            for m in root.messages : ChatBubble {
+                message: m;
+                width: root.width - 2 * Metrics.gap-3;
+            }
+        }
+
+        if root.messages.length == 0 : UiText {
+            role: TextRole.caption;
+            text: "问点什么：装哪个版本、崩溃怎么修、帮我改设置…";
+            horizontal-alignment: center;
+            height: 40px;
+        }
+
+        Rectangle { height: 1px; background: Theme.stroke; }
+
+        // 输入区
+        Rectangle {
+            height: 56px;
+            background: transparent;
+
+            HorizontalLayout {
+                padding: Metrics.gap-2;
+                spacing: Metrics.gap-2;
+
+                input-box := Rectangle {
+                    horizontal-stretch: 1;
+                    vertical-stretch: 1;
+                    background: Theme.bg-input;
+                    border-radius: Metrics.radius-sm;
+                    border-width: 1px;
+                    border-color: input-field.focused ? Theme.accent : Theme.stroke;
+
+                    input-field := PlainInput {
+                        text-padding: Metrics.gap-2;
+                        placeholder: "输入消息，Enter 发送";
+                        text <=> root.draft;
+                        accepted(t) => {
+                            if (t != "") {
+                                root.send(t);
+                            }
+                        }
+                    }
+                }
+
+                MetroButton {
+                    kind: ButtonKind.accent;
+                    icon: root.streaming ? IconKind.stop : IconKind.send;
+                    icon-only: true;
+                    clicked => {
+                        if (root.streaming) {
+                            root.stop();
+                        } else if (root.draft != "") {
+                            root.send(root.draft);
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
diff --git a/crates/app/ui/components/badge.slint b/crates/app/ui/components/badge.slint
new file mode 100644
index 0000000..4d68f57
--- /dev/null
+++ b/crates/app/ui/components/badge.slint
@@ -0,0 +1,27 @@
+// 徽标：MC 版本 / 加载器 / 已装 / 远古版 等短标记。Metro 做法是细边框小方块，不用药丸圆角。
+import { Theme } from "../theme/tokens.slint";
+import { Metrics } from "../theme/metrics.slint";
+import { UiText, TextRole } from "../components/label.slint";
+
+export component Badge inherits Rectangle {
+    in property <string> text: "";
+    in property <color> tint: Theme.fg-secondary;
+    in property <color> fill: transparent;
+
+    height: 18px;
+    width: label.preferred-width + 2 * Metrics.gap-1 + 2px;
+    background: fill;
+    border-width: 1px;
+    border-color: tint;
+    border-radius: Metrics.radius-sm;
+
+    label := UiText {
+        role: TextRole.caption;
+        text: root.text;
+        color: root.tint;
+        font-size: 11px;
+        horizontal-alignment: center;
+        x: Metrics.gap-1 + 1px;
+        width: label.preferred-width;
+    }
+}
diff --git a/crates/app/ui/components/glass.slint b/crates/app/ui/components/glass.slint
new file mode 100644
index 0000000..79fc043
--- /dev/null
+++ b/crates/app/ui/components/glass.slint
@@ -0,0 +1,59 @@
+// 玻璃拟态卡片的公共底座（09 §103：Slint 没有 backdrop-filter，用「预生成模糊背景层」替代）。
+//
+// 手法：Rust 侧把背景图降采样成一张极小的图（`Theme.bg-blur`），渲染时被平滑放大 → 天然模糊。
+// 卡片里把它按 `absolute-position` **反向偏移**画出来，于是卡片显示的是「自己这一块屏幕区域的
+// 模糊影像」，视觉上就是毛玻璃；再叠一层半透明面板色保证文字可读（对比度优先）。
+//
+// 关闭态（`Theme.glass == false` 或无背景图）不画任何东西：卡片保持 Metro 纯色观感。
+import { Theme } from "../theme/tokens.slint";
+import { Metrics } from "../theme/metrics.slint";
+
+export component GlassBase inherits Rectangle {
+    /// 卡片圆角（跟随宿主卡片）
+    in property <length> card-radius: Metrics.radius-md;
+    /// 叠在模糊层上的半透明面板色（保证前景对比度）
+    in property <color> tint: Theme.surface-solid;
+
+    out property <bool> active: Theme.glass && Theme.bg-blur.width > 0 && Theme.bg-image.width > 0;
+
+    x: 0;
+    y: 0;
+    width: 100%;
+    height: 100%;
+    border-radius: root.card-radius;
+    clip: true;
+    background: transparent;
+
+    if root.active : Image {
+        // 整窗模糊层 + 反向偏移 = 只露出「卡片所在那一块」。
+        // 必须用 `parent`（本组件自身）的绝对位置：用 `self` 会与自身 x 形成绑定环
+        // （absolute-position 依赖 x，x 又依赖 absolute-position）。
+        source: Theme.bg-blur;
+        x: -parent.absolute-position.x;
+        y: -parent.absolute-position.y;
+        width: Theme.window-width;
+        height: Theme.window-height;
+        image-fit: cover;
+    }
+
+    if root.active : Rectangle {
+        // 暗化层要**重画一次**：模糊层在卡片内部、盖在窗口的暗化层之上，
+        // 不补这一层的话玻璃卡片会比周围亮一大截（05 截图验收时的真实问题）。
+        background: rgba(0, 0, 0, Theme.bg-dim);
+        border-radius: root.card-radius;
+    }
+
+    if root.active : Rectangle {
+        // 玻璃染色：面板底色 55% 不透明，字压得住背景（对比度优先于「更透」）
+        background: root.tint.with-alpha(0.55);
+        border-radius: root.card-radius;
+    }
+
+    if root.active : Rectangle {
+        // 上缘一道细高光，玻璃的「厚度感」
+        y: 0;
+        height: 1px;
+        width: root.width;
+        background: Theme.stroke.with-alpha(0.35);
+    }
+}
diff --git a/crates/app/ui/components/icons.slint b/crates/app/ui/components/icons.slint
new file mode 100644
index 0000000..c1a6e61
--- /dev/null
+++ b/crates/app/ui/components/icons.slint
@@ -0,0 +1,192 @@
+// 图标：18×18 viewbox 的矢量绘制（Metro 要求线性几何图标，不用 emoji/位图）。
+// 只用 M/L/Q/Z 命令 + 直线，避免依赖字体字形；描边图标 stroke，实心图标 fill。
+import { Theme } from "../theme/tokens.slint";
+
+export enum IconKind {
+    instances,
+    download,
+    logs,
+    settings,
+    ai,
+    play,
+    stop,
+    search,
+    plus,
+    close,
+    minimize,
+    maximize,
+    chevronLeft,
+    chevronRight,
+    chevronDown,
+    expand,
+    send,
+    check,
+    warn,
+    error,
+    more,
+    sidebar,
+    restore,
+}
+
+export component AppIcon inherits Rectangle {
+    in property <IconKind> kind: IconKind.instances;
+    in property <color> tint: Theme.fg-secondary;
+    in property <length> icon-size: 18px;
+
+    width: icon-size;
+    height: icon-size;
+    background: transparent;
+
+    if kind == IconKind.instances : Path {
+        width: root.width; height: root.height;
+        viewbox-width: 18; viewbox-height: 18;
+        commands: "M 2 2 L 8 2 L 8 8 L 2 8 Z M 10 2 L 16 2 L 16 8 L 10 8 Z M 2 10 L 8 10 L 8 16 L 2 16 Z M 10 10 L 16 10 L 16 16 L 10 16 Z";
+        fill: transparent; stroke: root.tint; stroke-width: 1.4px;
+    }
+    if kind == IconKind.download : Path {
+        width: root.width; height: root.height;
+        viewbox-width: 18; viewbox-height: 18;
+        commands: "M 9 2 L 9 11 M 4 7 L 9 12 L 14 7 M 3 15 L 15 15";
+        fill: transparent; stroke: root.tint; stroke-width: 1.6px;
+    }
+    if kind == IconKind.logs : Path {
+        width: root.width; height: root.height;
+        viewbox-width: 18; viewbox-height: 18;
+        commands: "M 3 4 L 15 4 M 3 9 L 15 9 M 3 14 L 11 14";
+        fill: transparent; stroke: root.tint; stroke-width: 1.6px;
+    }
+    if kind == IconKind.settings : Path {
+        width: root.width; height: root.height;
+        viewbox-width: 18; viewbox-height: 18;
+        commands: "M 3 5 L 15 5 M 3 9 L 15 9 M 3 13 L 15 13";
+        fill: transparent; stroke: root.tint; stroke-width: 1.4px;
+    }
+    if kind == IconKind.settings : Rectangle {
+        x: 5px;
+        width: 5px; height: 5px; y: 3px;
+        border-radius: 2.5px; background: root.tint;
+    }
+    if kind == IconKind.settings : Rectangle {
+        x: 10px; y: 7px; width: 5px; height: 5px;
+        border-radius: 2.5px; background: root.tint;
+    }
+    if kind == IconKind.settings : Rectangle {
+        x: 3px; y: 11px; width: 5px; height: 5px;
+        border-radius: 2.5px; background: root.tint;
+    }
+    if kind == IconKind.ai : Path {
+        width: root.width; height: root.height;
+        viewbox-width: 18; viewbox-height: 18;
+        commands: "M 9 1.5 L 10.7 7.3 L 16.5 9 L 10.7 10.7 L 9 16.5 L 7.3 10.7 L 1.5 9 L 7.3 7.3 Z";
+        fill: root.tint; stroke: transparent; stroke-width: 1px;
+    }
+    if kind == IconKind.play : Path {
+        width: root.width; height: root.height;
+        viewbox-width: 18; viewbox-height: 18;
+        commands: "M 5 3 L 15 9 L 5 15 Z";
+        fill: root.tint; stroke: transparent; stroke-width: 1px;
+    }
+    if kind == IconKind.stop : Path {
+        width: root.width; height: root.height;
+        viewbox-width: 18; viewbox-height: 18;
+        commands: "M 5 5 L 13 5 L 13 13 L 5 13 Z";
+        fill: root.tint; stroke: transparent; stroke-width: 1px;
+    }
+    if kind == IconKind.search : Path {
+        width: root.width; height: root.height;
+        viewbox-width: 18; viewbox-height: 18;
+        commands: "M 8 3 Q 13 3 13 8 Q 13 13 8 13 Q 3 13 3 8 Q 3 3 8 3 Z M 11.5 11.5 L 16 16";
+        fill: transparent; stroke: root.tint; stroke-width: 1.5px;
+    }
+    if kind == IconKind.plus : Path {
+        width: root.width; height: root.height;
+        viewbox-width: 18; viewbox-height: 18;
+        commands: "M 9 3 L 9 15 M 3 9 L 15 9";
+        fill: transparent; stroke: root.tint; stroke-width: 1.8px;
+    }
+    if kind == IconKind.close : Path {
+        width: root.width; height: root.height;
+        viewbox-width: 18; viewbox-height: 18;
+        commands: "M 4 4 L 14 14 M 14 4 L 4 14";
+        fill: transparent; stroke: root.tint; stroke-width: 1.4px;
+    }
+    if kind == IconKind.minimize : Path {
+        width: root.width; height: root.height;
+        viewbox-width: 18; viewbox-height: 18;
+        commands: "M 4 9 L 14 9";
+        fill: transparent; stroke: root.tint; stroke-width: 1.4px;
+    }
+    if kind == IconKind.maximize : Path {
+        width: root.width; height: root.height;
+        viewbox-width: 18; viewbox-height: 18;
+        commands: "M 4.5 4.5 L 13.5 4.5 L 13.5 13.5 L 4.5 13.5 Z";
+        fill: transparent; stroke: root.tint; stroke-width: 1.2px;
+    }
+    if kind == IconKind.chevronLeft : Path {
+        width: root.width; height: root.height;
+        viewbox-width: 18; viewbox-height: 18;
+        commands: "M 11 3 L 6 9 L 11 15";
+        fill: transparent; stroke: root.tint; stroke-width: 1.6px;
+    }
+    if kind == IconKind.chevronRight : Path {
+        width: root.width; height: root.height;
+        viewbox-width: 18; viewbox-height: 18;
+        commands: "M 7 3 L 12 9 L 7 15";
+        fill: transparent; stroke: root.tint; stroke-width: 1.6px;
+    }
+    if kind == IconKind.chevronDown : Path {
+        width: root.width; height: root.height;
+        viewbox-width: 18; viewbox-height: 18;
+        commands: "M 3 7 L 9 13 L 15 7";
+        fill: transparent; stroke: root.tint; stroke-width: 1.6px;
+    }
+    if kind == IconKind.expand : Path {
+        width: root.width; height: root.height;
+        viewbox-width: 18; viewbox-height: 18;
+        commands: "M 3 7 L 3 3 L 7 3 M 11 3 L 15 3 L 15 7 M 15 11 L 15 15 L 11 15 M 7 15 L 3 15 L 3 11";
+        fill: transparent; stroke: root.tint; stroke-width: 1.4px;
+    }
+    if kind == IconKind.send : Path {
+        width: root.width; height: root.height;
+        viewbox-width: 18; viewbox-height: 18;
+        commands: "M 2 9 L 16 9 M 11 4 L 16 9 L 11 14";
+        fill: transparent; stroke: root.tint; stroke-width: 1.6px;
+    }
+    if kind == IconKind.check : Path {
+        width: root.width; height: root.height;
+        viewbox-width: 18; viewbox-height: 18;
+        commands: "M 3 9 L 7 13 L 15 4";
+        fill: transparent; stroke: root.tint; stroke-width: 1.8px;
+    }
+    if kind == IconKind.warn : Path {
+        width: root.width; height: root.height;
+        viewbox-width: 18; viewbox-height: 18;
+        commands: "M 9 2 L 16 15 L 2 15 Z M 9 6.5 L 9 10.5";
+        fill: transparent; stroke: root.tint; stroke-width: 1.4px;
+    }
+    if kind == IconKind.error : Path {
+        width: root.width; height: root.height;
+        viewbox-width: 18; viewbox-height: 18;
+        commands: "M 9 2 Q 16 2 16 9 Q 16 16 9 16 Q 2 16 2 9 Q 2 2 9 2 Z M 9 5 L 9 10";
+        fill: transparent; stroke: root.tint; stroke-width: 1.5px;
+    }
+    if kind == IconKind.more : Path {
+        width: root.width; height: root.height;
+        viewbox-width: 18; viewbox-height: 18;
+        commands: "M 4 7 L 6 7 L 6 9 L 4 9 Z M 8 7 L 10 7 L 10 9 L 8 9 Z M 12 7 L 14 7 L 14 9 L 12 9 Z";
+        fill: root.tint; stroke: transparent; stroke-width: 1px;
+    }
+    if kind == IconKind.sidebar : Path {
+        width: root.width; height: root.height;
+        viewbox-width: 18; viewbox-height: 18;
+        commands: "M 3 4 L 15 4 L 15 14 L 3 14 Z M 7 4 L 7 14";
+        fill: transparent; stroke: root.tint; stroke-width: 1.4px;
+    }
+    // 还原（已最大化时的标题栏按钮）：两层叠放方框
+    if kind == IconKind.restore : Path {
+        width: root.width; height: root.height;
+        viewbox-width: 18; viewbox-height: 18;
+        commands: "M 6 3 L 15 3 L 15 12 M 3 6 L 12 6 L 12 15 L 3 15 Z";
+        fill: transparent; stroke: root.tint; stroke-width: 1.2px;
+    }
+}
diff --git a/crates/app/ui/components/install-panel.slint b/crates/app/ui/components/install-panel.slint
new file mode 100644
index 0000000..73e0e53
--- /dev/null
+++ b/crates/app/ui/components/install-panel.slint
@@ -0,0 +1,73 @@
+// 安装进度卡片（下载页底部 / 向导进度步共用）：阶段 + 进度条 + 文件/字节/速度/剩余 + 取消。
+import { Theme } from "../theme/tokens.slint";
+import { Metrics } from "../theme/metrics.slint";
+import { UiInstallProgress, InstallStage } from "../models.slint";
+import { UiText, TextRole } from "../components/label.slint";
+import { ProgressBar } from "../components/progress-bar.slint";
+import { AppIcon, IconKind } from "../components/icons.slint";
+import { MetroButton, ButtonKind } from "../widgets/button.slint";
+
+export component InstallPanel inherits Rectangle {
+    in property <UiInstallProgress> data;
+    callback cancel();
+
+    height: 96px;
+    visible: root.data.visible;
+    background: Theme.bg-surface;
+    border-width: 1px;
+    border-color: Theme.stroke;
+
+    VerticalLayout {
+        padding: Metrics.gap-3;
+        spacing: Metrics.gap-1;
+
+        HorizontalLayout {
+            spacing: Metrics.gap-2;
+
+            AppIcon {
+                icon-size: 16px;
+                kind: root.data.failed ? IconKind.error
+                    : root.data.terminal ? IconKind.check
+                    : IconKind.download;
+                tint: root.data.failed ? Theme.state-danger
+                    : root.data.terminal ? Theme.state-success
+                    : Theme.accent;
+            }
+            UiText {
+                role: TextRole.bodyStrong;
+                text: root.data.instance + " · " + root.data.loader;
+                horizontal-stretch: 1;
+            }
+            UiText {
+                role: TextRole.caption;
+                text: root.data.stage_label;
+                color: root.data.failed ? Theme.state-danger : Theme.fg-secondary;
+            }
+            if !root.data.terminal : MetroButton {
+                kind: ButtonKind.subtle;
+                text: "取消";
+                button-height: 24px;
+                clicked => { root.cancel(); }
+            }
+        }
+
+        ProgressBar {
+            ratio: root.data.ratio;
+            known: root.data.known;
+        }
+
+        HorizontalLayout {
+            spacing: Metrics.gap-3;
+            UiText {
+                role: TextRole.caption;
+                text: root.data.message;
+                horizontal-stretch: 1;
+                overflow: elide;
+            }
+            UiText { role: TextRole.caption; text: root.data.files_label; }
+            UiText { role: TextRole.caption; text: root.data.bytes_label; }
+            UiText { role: TextRole.caption; text: root.data.speed; color: Theme.accent; }
+            UiText { role: TextRole.caption; text: root.data.eta; }
+        }
+    }
+}
diff --git a/crates/app/ui/components/label.slint b/crates/app/ui/components/label.slint
new file mode 100644
index 0000000..0dd42ae
--- /dev/null
+++ b/crates/app/ui/components/label.slint
@@ -0,0 +1,34 @@
+// 排版角色封装：所有文字都走 UiText，不在页面里散落 font-size/font-family 字面量。
+// 角色 → 字号/字重/默认前景色由 tokens.slint 的 ramp 决定；外部赋值可覆盖（例如强调色标题）。
+import { Theme } from "../theme/tokens.slint";
+
+export enum TextRole {
+    display,
+    title,
+    subtitle,
+    body,
+    bodyStrong,
+    caption,
+    mono,
+    monoSmall,
+}
+
+export component UiText inherits Text {
+    in property <TextRole> role: TextRole.body;
+
+    color: role == TextRole.caption ? Theme.fg-secondary : Theme.fg-primary;
+    font-family: (role == TextRole.mono || role == TextRole.monoSmall)
+        ? Theme.font-family-mono
+        : Theme.font-family;
+    font-size: (role == TextRole.display) ? Theme.font-size-display
+        : (role == TextRole.title) ? Theme.font-size-title
+        : (role == TextRole.subtitle) ? Theme.font-size-subtitle
+        : (role == TextRole.caption || role == TextRole.monoSmall) ? Theme.font-size-caption
+        : Theme.font-size-body;
+    font-weight: (role == TextRole.bodyStrong || role == TextRole.title || role == TextRole.display)
+        ? 600
+        : 400;
+    vertical-alignment: center;
+    wrap: no-wrap;
+    overflow: elide;
+}
diff --git a/crates/app/ui/components/nav.slint b/crates/app/ui/components/nav.slint
new file mode 100644
index 0000000..739f308
--- /dev/null
+++ b/crates/app/ui/components/nav.slint
@@ -0,0 +1,182 @@
+// 左侧主导航（D16 §1）：图标+文字，选中项 accent 色块；可折叠成纯图标窄条（偏好记忆）。
+// 折叠宽度/展开宽度取 Metrics，动画时长取 Theme.motion-normal。
+import { Theme } from "../theme/tokens.slint";
+import { Metrics } from "../theme/metrics.slint";
+import { RouteKind } from "../models.slint";
+import { UiText, TextRole } from "label.slint";
+import { AppIcon, IconKind } from "icons.slint";
+
+component NavItem inherits Rectangle {
+    in property <IconKind> icon: IconKind.instances;
+    in property <string> label: "";
+    in property <bool> active: false;
+    in property <bool> collapsed: false;
+    callback clicked();
+
+    height: root.collapsed ? 48px : 64px;
+    background: root.active
+        ? Theme.accent-soft
+        : touch.has-hover ? Theme.bg-hover : transparent;
+    animate background { duration: Theme.motion-fast; }
+
+    // 选中态：左侧 accent 竖条（Metro 侧栏语义）
+    Rectangle {
+        visible: root.active;
+        x: 0;
+        y: 0;
+        width: 3px;
+        height: root.height;
+        background: Theme.accent;
+    }
+
+    AppIcon {
+        kind: root.icon;
+        icon-size: 20px;
+        x: (root.width - self.width) / 2;
+        y: root.collapsed ? (root.height - self.height) / 2 : 12px;
+        tint: root.active ? Theme.accent : Theme.fg-secondary;
+    }
+
+    UiText {
+        visible: !root.collapsed;
+        role: TextRole.caption;
+        text: root.label;
+        color: root.active ? Theme.accent : Theme.fg-secondary;
+        horizontal-alignment: center;
+        x: 0;
+        y: 38px;
+        width: root.width;
+    }
+
+    touch := TouchArea {
+        mouse-cursor: pointer;
+        clicked => { root.clicked(); }
+    }
+
+    accessible-role: button;
+    accessible-label: root.label;
+}
+
+export component Nav inherits Rectangle {
+    in property <RouteKind> active: RouteKind.instances;
+    in-out property <bool> collapsed: false;
+    in property <string> account-name: "未登录";
+    in property <color> account-hue: #5C2D91;
+    in property <string> account-initial: "?";
+    callback navigate(RouteKind);
+    callback toggle-collapsed();
+    callback account-clicked();
+
+    width: collapsed ? Metrics.nav-collapsed-width : Metrics.nav-expanded-width;
+    height: 100%;
+    background: Theme.bg-surface;
+    animate width { duration: Theme.motion-normal; easing: ease-in-out; }
+
+    // 右边界线
+    Rectangle {
+        x: root.width - 1px;
+        y: 0;
+        width: 1px;
+        height: root.height;
+        background: Theme.stroke;
+    }
+
+    VerticalLayout {
+        x: 0;
+        y: Metrics.gap-2;
+        width: root.width;
+        height: root.height - Metrics.gap-2 - Metrics.gap-2;
+
+        NavItem {
+            icon: IconKind.instances;
+            label: "实例";
+            active: root.active == RouteKind.instances || root.active == RouteKind.detail;
+            collapsed: root.collapsed;
+            clicked => { root.navigate(RouteKind.instances); }
+        }
+        NavItem {
+            icon: IconKind.download;
+            label: "下载";
+            active: root.active == RouteKind.download;
+            collapsed: root.collapsed;
+            clicked => { root.navigate(RouteKind.download); }
+        }
+        NavItem {
+            icon: IconKind.logs;
+            label: "日志";
+            active: root.active == RouteKind.logs;
+            collapsed: root.collapsed;
+            clicked => { root.navigate(RouteKind.logs); }
+        }
+        NavItem {
+            icon: IconKind.settings;
+            label: "设置";
+            active: root.active == RouteKind.settings;
+            collapsed: root.collapsed;
+            clicked => { root.navigate(RouteKind.settings); }
+        }
+
+        Rectangle { vertical-stretch: 1; background: transparent; }
+
+        // 底部：账户头像（点击进设置·账户）
+        Rectangle {
+            height: 56px;
+            background: account-touch.has-hover ? Theme.bg-hover : transparent;
+
+            Rectangle {
+                width: 28px;
+                height: 28px;
+                border-radius: 14px;
+                background: root.account-hue;
+                x: (root.width - self.width) / 2;
+                y: 8px;
+
+                UiText {
+                    text: root.account-initial;
+                    font-size: 12px;
+                    font-weight: 600;
+                    color: Theme.fg-on-accent;
+                    horizontal-alignment: center;
+                    vertical-alignment: center;
+                }
+            }
+
+            UiText {
+                visible: !root.collapsed;
+                role: TextRole.caption;
+                text: root.account-name;
+                horizontal-alignment: center;
+                x: 0;
+                y: 38px;
+                width: root.width;
+            }
+
+            account-touch := TouchArea {
+                mouse-cursor: pointer;
+                clicked => { root.account-clicked(); }
+            }
+        }
+
+        // 折叠开关（偏好由 Rust 侧持久化到 ui.nav.collapsed）
+        Rectangle {
+            height: 40px;
+            background: toggle-touch.has-hover ? Theme.bg-hover : transparent;
+
+            AppIcon {
+                kind: root.collapsed ? IconKind.chevronRight : IconKind.chevronLeft;
+                icon-size: 16px;
+                x: (root.width - self.width) / 2;
+                y: (root.height - self.height) / 2;
+                tint: Theme.fg-secondary;
+            }
+
+            toggle-touch := TouchArea {
+                mouse-cursor: pointer;
+                clicked => { root.toggle-collapsed(); }
+            }
+
+            accessible-role: button;
+            accessible-label: root.collapsed ? "展开导航栏" : "折叠导航栏";
+        }
+    }
+}
diff --git a/crates/app/ui/components/notice-bar.slint b/crates/app/ui/components/notice-bar.slint
new file mode 100644
index 0000000..895d432
--- /dev/null
+++ b/crates/app/ui/components/notice-bar.slint
@@ -0,0 +1,57 @@
+// 横幅通知条：隔离档位切换提示（M30 ModeChangeWarning）/ 启动失败 / 启动告警。
+// 与 Toast 的分工：Toast 是「刚发生了什么」，通知条是「现在需要你处理」（用户点了才收）。
+import { Theme } from "../theme/tokens.slint";
+import { Metrics } from "../theme/metrics.slint";
+import { UiNotice, NoticeKind } from "../models.slint";
+import { PageState } from "../page_state.slint";
+import { UiText, TextRole } from "../components/label.slint";
+import { AppIcon, IconKind } from "../components/icons.slint";
+import { MetroButton, ButtonKind } from "../widgets/button.slint";
+
+// 横幅通知：隔离档位切换提示（M30 ModeChangeWarning）/ 启动失败 / 启动告警。
+// 与 Toast 的分工：Toast 是「刚发生了什么」，通知条是「现在需要你处理」。
+export component NoticeBar inherits Rectangle {
+    in property <[UiNotice]> notices;
+
+    visible: root.notices.length > 0;
+    height: root.notices.length > 0 ? 48px : 0px;
+    background: Theme.state-warn-soft;
+
+    HorizontalLayout {
+        padding-left: Metrics.gap-4;
+        padding-right: Metrics.gap-3;
+        spacing: Metrics.gap-2;
+
+        for notice in root.notices : Rectangle {
+            horizontal-stretch: 1;
+            background: transparent;
+            HorizontalLayout {
+                spacing: Metrics.gap-2;
+                AppIcon {
+                    icon-size: 16px;
+                    kind: notice.kind == NoticeKind.error ? IconKind.error : IconKind.warn;
+                    tint: notice.kind == NoticeKind.error ? Theme.state-danger : Theme.state-warn;
+                }
+                VerticalLayout {
+                    vertical-stretch: 1;
+                    spacing: 0px;
+                    UiText { role: TextRole.caption; text: notice.title; horizontal-stretch: 1; }
+                    UiText {
+                        role: TextRole.caption;
+                        text: notice.body;
+                        horizontal-stretch: 1;
+                        overflow: elide;
+                        color: Theme.fg-secondary;
+                    }
+                }
+                MetroButton {
+                    kind: ButtonKind.subtle;
+                    text: "知道了";
+                    button-height: 22px;
+                    clicked => { PageState.notice-dismiss(notice.id); }
+                }
+            }
+        }
+    }
+}
+
diff --git a/crates/app/ui/components/progress-bar.slint b/crates/app/ui/components/progress-bar.slint
new file mode 100644
index 0000000..c9adcfa
--- /dev/null
+++ b/crates/app/ui/components/progress-bar.slint
@@ -0,0 +1,34 @@
+// 细进度条（0.0~1.0）：安装进度 / 下载页顶部 / 向导进度共用。
+// 未知总量（known = false）时画一条不确定态的弱色轨道，而不是假装 0%。
+import { Theme } from "../theme/tokens.slint";
+import { Metrics } from "../theme/metrics.slint";
+
+export component ProgressBar inherits Rectangle {
+    in property <float> ratio: 0.0;
+    in property <bool> known: true;
+    in property <length> bar-height: 6px;
+
+    height: root.bar-height;
+    border-radius: root.bar-height / 2;
+    background: Theme.bg-hover;
+    clip: true;
+
+    Rectangle {
+        x: 0;
+        y: 0;
+        width: root.known ? max(0px, root.width * clamp(root.ratio, 0.0, 1.0)) : 0px;
+        height: root.height;
+        border-radius: root.bar-height / 2;
+        background: Theme.accent;
+        animate width { duration: 180ms; easing: ease-out; }
+    }
+
+    if !root.known : Rectangle {
+        x: 0;
+        y: 0;
+        width: root.width / 3;
+        height: root.height;
+        border-radius: root.bar-height / 2;
+        background: Theme.accent-soft;
+    }
+}
diff --git a/crates/app/ui/components/progress-ring.slint b/crates/app/ui/components/progress-ring.slint
new file mode 100644
index 0000000..4bb82d4
--- /dev/null
+++ b/crates/app/ui/components/progress-ring.slint
@@ -0,0 +1,22 @@
+// 启动进度环：磁贴「启动中」状态用（下载/校验/启动三个阶段共用一个环）。
+// 用 std-widgets 的 ProgressIndicator：progress <= 0 时转为不确定态（转圈）。
+// P1 若要完全贴合 Metro 强调色，需自绘弧线（Slint 无 arc 命令，得用旋转遮罩法）。
+import { Theme } from "../theme/tokens.slint";
+import { ProgressIndicator } from "std-widgets.slint";
+
+export component ProgressRing inherits Rectangle {
+    /// 0.0~1.0；<= 0 表示未知进度
+    in property <float> progress: 0;
+    in property <length> ring-size: 28px;
+
+    width: ring-size;
+    height: ring-size;
+    background: transparent;
+
+    ProgressIndicator {
+        width: root.ring-size;
+        height: root.ring-size;
+        progress: root.progress;
+        indeterminate: root.progress <= 0;
+    }
+}
diff --git a/crates/app/ui/components/tile.slint b/crates/app/ui/components/tile.slint
new file mode 100644
index 0000000..16e455c
--- /dev/null
+++ b/crates/app/ui/components/tile.slint
@@ -0,0 +1,198 @@
+// 实例磁贴（G1）：图标 / 名字 / MC 版本徽标 / 加载器徽标 / 最后游玩 / 大启动键 + 设置键。
+// 三档尺寸由 Metrics.tile-* 决定（小磁贴藏徽标与时间，只留名字+启动）；
+// 启动中把底部按钮行替换成「进度环 + 阶段文案 + 停止」。
+import { Theme } from "../theme/tokens.slint";
+import { Metrics } from "../theme/metrics.slint";
+import { UiTile, RuntimePhase, LoaderKind } from "../models.slint";
+import { UiText, TextRole } from "label.slint";
+import { AppIcon, IconKind } from "icons.slint";
+import { Badge } from "badge.slint";
+import { ProgressRing } from "progress-ring.slint";
+import { GlassBase } from "glass.slint";
+import { MetroButton, ButtonKind } from "../widgets/button.slint";
+
+component TileIcon inherits Rectangle {
+    in property <UiTile> data;
+    in property <length> box-size: 44px;
+
+    width: box-size;
+    height: box-size;
+    border-radius: Metrics.radius-md;
+    background: root.data.hue;
+
+    if root.data.icon.width > 0 : Image {
+        x: 0;
+        y: 0;
+        width: root.width;
+        height: root.height;
+        source: root.data.icon;
+        image-fit: cover;
+    }
+    if root.data.icon.width <= 0 : UiText {
+        text: root.data.initial;
+        font-size: 18px;
+        font-weight: 600;
+        color: Theme.fg-on-accent;
+        horizontal-alignment: center;
+        vertical-alignment: center;
+    }
+}
+
+export component InstanceTile inherits Rectangle {
+    in property <UiTile> data;
+    in property <bool> compact: false;
+    callback open();
+    callback launch();
+    callback configure();
+    /// 启动中/运行中的停止键（dispatch StopInstance）
+    callback stop();
+
+    height: Metrics.tile-height;
+    background: touch.has-hover ? Theme.bg-elevated : Theme.bg-surface;
+    border-radius: Metrics.radius-md;
+    border-width: 1px;
+    border-color: root.data.phase == RuntimePhase.running ? Theme.accent : Theme.stroke;
+    drop-shadow-blur: touch.has-hover ? 12px : 0px;
+    drop-shadow-color: Theme.shadow;
+    drop-shadow-offset-y: 2px;
+    animate background { duration: Theme.motion-fast; }
+    animate drop-shadow-blur { duration: Theme.motion-normal; }
+
+    // 玻璃拟态底（关闭态什么都不画，卡片就是 Metro 纯色）；必须排在最前，否则盖住 accent 细线
+    GlassBase {
+        card-radius: root.border-radius;
+    }
+
+    // 运行中：顶部 accent 细线（Metro 色块语义）
+    Rectangle {
+        visible: root.data.phase == RuntimePhase.running;
+        x: 0;
+        y: 0;
+        width: root.width;
+        height: 2px;
+        background: Theme.accent;
+    }
+
+    // 磁贴主体点击 → 实例详情（G4）；按钮的 TouchArea 后声明，命中优先
+    touch := TouchArea {
+        mouse-cursor: pointer;
+        clicked => { root.open(); }
+    }
+
+    VerticalLayout {
+        padding: Metrics.gap-3;
+        spacing: Metrics.gap-2;
+
+        HorizontalLayout {
+            spacing: Metrics.gap-2;
+
+            TileIcon {
+                data: root.data;
+                box-size: Metrics.tile-icon-size;
+            }
+
+            VerticalLayout {
+                spacing: 2px;
+                vertical-stretch: 1;
+
+                UiText {
+                    role: TextRole.bodyStrong;
+                    text: root.data.name;
+                    horizontal-stretch: 1;
+                }
+
+                UiText {
+                    role: TextRole.caption;
+                    text: root.data.last_played;
+                    visible: !root.compact;
+                }
+            }
+        }
+
+        HorizontalLayout {
+            visible: !root.compact;
+            spacing: Metrics.gap-1;
+
+            Badge {
+                text: root.data.mc_version;
+                tint: Theme.fg-secondary;
+            }
+            Badge {
+                text: root.data.loader_label;
+                tint: root.data.loader == LoaderKind.vanilla ? Theme.fg-secondary : Theme.accent;
+            }
+        }
+
+        Rectangle { vertical-stretch: 1; background: transparent; }
+
+        // 空闲/失败：大启动键 + 设置键
+        HorizontalLayout {
+            visible: root.data.phase == RuntimePhase.idle || root.data.phase == RuntimePhase.failed;
+            spacing: Metrics.gap-2;
+
+            MetroButton {
+                kind: ButtonKind.accent;
+                text: root.data.phase == RuntimePhase.failed ? "重试" : "启动";
+                show-icon: true;
+                icon: IconKind.play;
+                grow: true;
+                clicked => { root.launch(); }
+            }
+            MetroButton {
+                kind: ButtonKind.subtle;
+                icon: IconKind.settings;
+                icon-only: true;
+                clicked => { root.configure(); }
+            }
+        }
+
+        // 启动中：进度环 + 阶段文案 + 停止
+        HorizontalLayout {
+            visible: root.data.phase == RuntimePhase.downloading
+                || root.data.phase == RuntimePhase.verifying
+                || root.data.phase == RuntimePhase.launching;
+            spacing: Metrics.gap-2;
+
+            ProgressRing {
+                progress: root.data.progress;
+                ring-size: 22px;
+            }
+            UiText {
+                role: TextRole.caption;
+                text: root.data.phase_label;
+                horizontal-stretch: 1;
+            }
+            MetroButton {
+                kind: ButtonKind.subtle;
+                icon: IconKind.stop;
+                icon-only: true;
+                clicked => { root.stop(); }
+            }
+        }
+
+        // 运行中：状态点 + 停止
+        HorizontalLayout {
+            visible: root.data.phase == RuntimePhase.running;
+            spacing: Metrics.gap-2;
+
+            Rectangle {
+                width: 8px;
+                height: 8px;
+                border-radius: 4px;
+                background: Theme.state-success;
+            }
+            UiText {
+                role: TextRole.caption;
+                text: "运行中";
+                color: Theme.state-success;
+                horizontal-stretch: 1;
+            }
+            MetroButton {
+                kind: ButtonKind.subtle;
+                icon: IconKind.stop;
+                icon-only: true;
+                clicked => { root.stop(); }
+            }
+        }
+    }
+}
diff --git a/crates/app/ui/components/titlebar.slint b/crates/app/ui/components/titlebar.slint
new file mode 100644
index 0000000..6fc46e2
--- /dev/null
+++ b/crates/app/ui/components/titlebar.slint
@@ -0,0 +1,126 @@
+// 自绘无边框标题栏（D16 §1）：Metro 一体感 + accent 顶线。
+// 拖拽/最大化/最小化/关闭只发回调，原生窗口操作由 main.rs 接到 Slint Window 平台上
+// （Slint DSL 内无法移动原生窗口）。
+import { Theme } from "../theme/tokens.slint";
+import { Metrics } from "../theme/metrics.slint";
+import { UiText, TextRole } from "label.slint";
+import { AppIcon, IconKind } from "icons.slint";
+
+component WindowButton inherits Rectangle {
+    in property <IconKind> icon: IconKind.minimize;
+    /// 关闭键：hover 用 Metro 红底白字
+    in property <bool> danger: false;
+    callback clicked();
+
+    width: Metrics.titlebar-button-width;
+    height: Metrics.titlebar-height;
+    background: touch.pressed
+        ? (danger ? Theme.state-danger-hover : Theme.bg-pressed)
+        : touch.has-hover ? (danger ? Theme.state-danger : Theme.bg-hover) : transparent;
+    animate background { duration: Theme.motion-fast; }
+
+    AppIcon {
+        kind: root.icon;
+        icon-size: 12px;
+        x: (root.width - self.width) / 2;
+        y: (root.height - self.height) / 2;
+        tint: root.danger && touch.has-hover ? Theme.fg-on-accent : Theme.fg-primary;
+    }
+
+    touch := TouchArea {
+        mouse-cursor: pointer;
+        clicked => { root.clicked(); }
+    }
+}
+
+export component TitleBar inherits Rectangle {
+    in property <string> title: "Unlucky Launcher";
+    in property <string> subtitle: "";
+    in property <bool> maximized: false;
+
+    callback toggle-maximize();
+    callback minimize();
+    callback request-close();
+
+    height: Metrics.titlebar-height;
+    background: Theme.bg-titlebar;
+
+    // accent 顶线（Metro 强调色贯穿）
+    Rectangle {
+        x: 0;
+        y: 0;
+        width: root.width;
+        height: Metrics.accent-line;
+        background: Theme.accent;
+    }
+
+    // 拖拽区：交给原生 `WindowMoveArea`（Slint 1.18 内置，拖过阈值才移动窗口，
+    // 并保持子元素可交互）。只覆盖左侧，右侧三个窗口按钮留出来。
+    // 平台不支持「系统级窗口移动」时该元素退化为无操作（Qt/部分 Wayland 组合），
+    // winit on Windows/macOS/X11 可用——Win7 落在这条路上。
+    WindowMoveArea {
+        x: 0;
+        y: Metrics.accent-line;
+        width: root.width - 3 * Metrics.titlebar-button-width;
+        height: root.height - Metrics.accent-line;
+    }
+
+    // 应用标记 + 标题
+    HorizontalLayout {
+        x: Metrics.gap-3;
+        y: Metrics.accent-line;
+        width: root.width - 3 * Metrics.titlebar-button-width - 2 * Metrics.gap-3;
+        height: root.height - Metrics.accent-line;
+        spacing: Metrics.gap-2;
+
+        Rectangle {
+            width: 14px;
+            height: 14px;
+            border-radius: Metrics.radius-sm;
+            background: Theme.accent;
+            UiText {
+                text: "U";
+                font-size: 10px;
+                font-weight: 700;
+                color: Theme.fg-on-accent;
+                horizontal-alignment: center;
+                vertical-alignment: center;
+            }
+        }
+
+        UiText {
+            role: TextRole.caption;
+            text: root.title;
+            font-weight: 600;
+            horizontal-stretch: 1;
+        }
+
+        UiText {
+            role: TextRole.caption;
+            text: root.subtitle;
+            color: Theme.fg-secondary;
+        }
+    }
+
+    HorizontalLayout {
+        x: root.width - 3 * Metrics.titlebar-button-width;
+        y: Metrics.accent-line;
+        width: 3 * Metrics.titlebar-button-width;
+        height: root.height - Metrics.accent-line;
+        spacing: 0px;
+
+        WindowButton {
+            icon: IconKind.minimize;
+            clicked => { root.minimize(); }
+        }
+        WindowButton {
+            icon: root.maximized ? IconKind.restore : IconKind.maximize;
+            clicked => { root.toggle-maximize(); }
+        }
+        WindowButton {
+            icon: IconKind.close;
+            danger: true;
+            clicked => { root.request-close(); }
+        }
+    }
+}
diff --git a/crates/app/ui/main.slint b/crates/app/ui/main.slint
new file mode 100644
index 0000000..2423fe9
--- /dev/null
+++ b/crates/app/ui/main.slint
@@ -0,0 +1,305 @@
+// Unlucky-Launcher · 主入口窗口（P0 阶段 B 接线）
+//
+// 布局真相源：DevDocs/PlanDoc/09-ui-layout.md（D16：左侧固定导航 + 右侧 AI 常驻栏 + 磁贴实例页）。
+// 本文件只做三件事：①无边框窗口与字体/缩放口径 ②实例化 `AppShell` ③把 AppShell 的全部
+// 属性/回调原样上抛给 src/main.rs（Slint 只能从根组件访问属性与回调，所以这层转发是必需的）。
+//
+// 与 M11 骨架的关系：M11 的 `Metro` palette global（accent/surface/sidebar/tile/text/muted/pad/gap）
+// 已由 `theme/tokens.slint` 的 `Theme` 继承并扩展——同一「palette global 令牌化」思路，但多了
+// 亮/暗双套色板（LightPalette/DarkPalette）、主题三态解析、排版 ramp 与字体栈；M11 的占位
+// NavItem/Tile 组件由 `components/nav.slint` 与 `components/tile.slint` 取代，占位内核不再保留。
+
+// P3：页面状态 global 从根文件再导出一遍，Rust 侧才能拿到 `PageState` 类型。
+export { PageState } from "page_state.slint";
+import { AppShell } from "shell.slint";
+import { Theme } from "theme/tokens.slint";
+import { Metrics } from "theme/metrics.slint";
+import {
+    RouteKind, TileSize, InstanceView, SettingSection, DownloadCategory, ThemeMode, BgFillKind,
+    UiTile, UiVersion, UiLogSession, UiLogLine, UiDiagnosis, UiChatMessage, UiDialog, UiToast,
+} from "models.slint";
+
+export component MainWindow inherits Window {
+    title: root.app-title;
+    // 默认尺寸取 D16 线框口径；最小尺寸保证 5 列磁贴 + 导航 + AI 栏不挤压
+    width: 1180px;
+    height: 760px;
+    // Metro 一体感：自绘标题栏（components/titlebar.slint）
+    no-frame: true;
+    // 无边框窗口必须显式给边缘缩放热区，否则用户无法拖拽改窗口大小
+    resize-border-width: 4px;
+    default-font-family: Theme.font-family;
+    default-font-size: Theme.font-size-body;
+    // 窗口自身底色必须**不透明**：面板半透明度（panel-alpha）只该透出背景图，不该透到桌面
+    background: Theme.canvas-solid;
+
+    // ── 从 main.rs 灌入的状态 ───────────────────────────────────
+    in-out property <string> app-title: "Unlucky Launcher";
+    in property <RouteKind> route: RouteKind.instances;
+
+    in property <bool> nav-collapsed: false;
+    in property <string> account-name: "未登录";
+    in property <string> account-initial: "?";
+    in property <color> account-hue: #5C2D91;
+
+    in-out property <bool> ai-collapsed: false;
+    in property <[UiChatMessage]> ai-messages;
+    in property <bool> ai-streaming: false;
+    in-out property <bool> yolo: false;
+    in property <string> ai-endpoint-label: "llama.cpp · 本地";
+    in-out property <string> ai-draft: "";
+
+    in property <[UiTile]> tiles;
+    in property <[UiTile]> running-tiles;
+    in property <[UiVersion]> versions;
+    in property <[UiLogSession]> log-sessions;
+    in property <[UiLogLine]> log-lines;
+    in property <UiDiagnosis> diagnosis;
+    in property <bool> has-diagnosis: false;
+    in property <string> selected-session: "";
+
+    in-out property <TileSize> tile-size: TileSize.medium;
+    in-out property <InstanceView> instance-view: InstanceView.tiles;
+    in-out property <string> instance-query: "";
+    in-out property <SettingSection> settings-section: SettingSection.general;
+    in-out property <ThemeMode> theme-mode: ThemeMode.auto;
+    // 系统主题（M41）：0 = 未知（回落 Slint 后端），1 = 浅色，2 = 深色
+    in property <int> system-theme: 0;
+    /// 后端是否认得系统主题（`false` 时 Rust 侧才需要轮询探测兜底）
+    out property <bool> system-theme-known: Theme.system-theme-known;
+
+    // ── 外观（高级）P1 四件（09 §101-104，出厂全部关闭）──────────────
+    // 图片由 Rust 灌入（`in`）；其余是 in-out：设置页控件会写回，回调里再原样上抛给 Rust。
+    in property <image> background-image;
+    in property <image> background-blur;
+    in-out property <bool> bg-image-enabled: false;
+    in-out property <string> bg-image: "";
+    in-out property <BgFillKind> bg-fill: BgFillKind.cover;
+    in-out property <float> bg-dim: 0.35;
+    in-out property <float> panel-alpha: 1.0;
+    in-out property <bool> glass: false;
+    in-out property <color> accent-color: transparent;
+    /// 设置页「强调色（十六进制）」输入框的内容（Rust 写入规范化后的值）
+    in-out property <string> accent-hex: "";
+    /// 强调色输入是否非法（设置页亮 warn 行）
+    in-out property <bool> accent-invalid: false;
+    in-out property <DownloadCategory> download-category: DownloadCategory.release;
+    in-out property <bool> download-installed-only: false;
+    in-out property <string> download-query: "";
+
+    in property <UiDialog> dialog;
+    in property <bool> dialog-open: false;
+    in property <int> dialog-queued: 0;
+    in property <[UiToast]> toasts;
+
+    // 主题/外观：handler 里整体赋值给 `Theme` 全局（Slint 不允许在组件体内给全局属性做绑定，
+    // 但允许在回调/init 里赋值）。auto 分支由 Theme 自己读系统的 Palette.color-scheme。
+    init => {
+        Theme.theme-mode = root.theme-mode;
+        Theme.system-theme = root.system-theme;
+        Theme.bg-image = root.background-image;
+        Theme.bg-blur = root.background-blur;
+        Theme.bg-dim = root.bg-dim;
+        Theme.panel-alpha = root.panel-alpha;
+        Theme.glass = root.glass;
+        Theme.accent-override = root.accent-color;
+    }
+    changed theme-mode => { Theme.theme-mode = root.theme-mode; }
+    changed system-theme => { Theme.system-theme = root.system-theme; }
+    changed background-image => { Theme.bg-image = root.background-image; }
+    changed background-blur => { Theme.bg-blur = root.background-blur; }
+    changed bg-dim => { Theme.bg-dim = root.bg-dim; }
+    changed panel-alpha => { Theme.panel-alpha = root.panel-alpha; }
+    changed glass => { Theme.glass = root.glass; }
+    changed accent-color => { Theme.accent-override = root.accent-color; }
+
+    // ── 用户操作（main.rs 转成 AppCommand 或纯 UI 偏好）──────────────
+    callback toggle-maximize();
+    callback minimize();
+    callback request-close();
+
+    callback navigate(RouteKind);
+    callback toggle-nav();
+    callback toggle-ai();
+    callback expand-ai();
+    callback dock-ai();
+    callback toggle-yolo();
+    callback ai-send(string);
+    callback ai-stop();
+
+    callback instance-launch(string);
+    callback instance-configure(string);
+    callback instance-stop(string);
+    callback instance-open(string);
+    callback new-instance();
+    callback instance-view-changed(InstanceView);
+    callback tile-size-changed(TileSize);
+    callback instance-query-changed(string);
+
+    callback download-category-changed(DownloadCategory);
+    callback download-install(string);
+    callback installed-only-changed(bool);
+    callback download-query-changed(string);
+    callback ancient-help();
+
+    callback log-select(string);
+    callback log-ask-ai(string);
+    callback log-apply-fix();
+
+    callback settings-section-changed(SettingSection);
+    callback theme-changed(ThemeMode);
+    callback bg-image-enabled-changed(bool);
+    callback bg-image-changed(string);
+    callback bg-fill-changed(BgFillKind);
+    callback bg-dim-changed(float);
+    callback panel-alpha-changed(float);
+    callback glass-changed(bool);
+    callback accent-color-changed(string);
+    callback accent-swatch-picked(int);
+    callback yolo-changed(bool);
+    callback mcp-changed(bool);
+    callback ai-endpoint-changed(int);
+
+    callback dialog-primary();
+    callback dialog-secondary();
+    callback dialog-dismissed();
+    callback toast-dismissed(string);
+
+    AppShell {
+        app-title: root.app-title;
+        // 直接复用 Window 的内建 `maximized`（后端随窗口状态更新，无需自建属性）
+        maximized: root.maximized;
+        route: root.route;
+        nav-collapsed: root.nav-collapsed;
+        account-name: root.account-name;
+        account-initial: root.account-initial;
+        account-hue: root.account-hue;
+        ai-collapsed: root.ai-collapsed;
+        ai-messages: root.ai-messages;
+        ai-streaming: root.ai-streaming;
+        yolo: root.yolo;
+        ai-endpoint-label: root.ai-endpoint-label;
+        ai-draft: root.ai-draft;
+        tiles: root.tiles;
+        running-tiles: root.running-tiles;
+        versions: root.versions;
+        log-sessions: root.log-sessions;
+        log-lines: root.log-lines;
+        diagnosis: root.diagnosis;
+        has-diagnosis: root.has-diagnosis;
+        selected-session: root.selected-session;
+        tile-size: root.tile-size;
+        instance-view: root.instance-view;
+        instance-query: root.instance-query;
+        settings-section: root.settings-section;
+        theme-mode: root.theme-mode;
+        bg-image-enabled: root.bg-image-enabled;
+        bg-image: root.bg-image;
+        bg-fill: root.bg-fill;
+        bg-dim: root.bg-dim;
+        panel-alpha: root.panel-alpha;
+        glass: root.glass;
+        accent-hex: root.accent-hex;
+        accent-invalid: root.accent-invalid;
+        download-category: root.download-category;
+        download-installed-only: root.download-installed-only;
+        download-query: root.download-query;
+        dialog: root.dialog;
+        dialog-open: root.dialog-open;
+        dialog-queued: root.dialog-queued;
+        toasts: root.toasts;
+
+        toggle-maximize => { root.toggle-maximize(); }
+        minimize => { root.minimize(); }
+        request-close => { root.request-close(); }
+
+        navigate(r) => { root.navigate(r); }
+        toggle-nav => { root.toggle-nav(); }
+        toggle-ai => { root.toggle-ai(); }
+        expand-ai => { root.expand-ai(); }
+        dock-ai => { root.dock-ai(); }
+        toggle-yolo => { root.toggle-yolo(); }
+        ai-send(text) => { root.ai-send(text); }
+        ai-stop => { root.ai-stop(); }
+
+        instance-launch(id) => { root.instance-launch(id); }
+        instance-configure(id) => { root.instance-configure(id); }
+        instance-stop(id) => { root.instance-stop(id); }
+        instance-open(id) => { root.instance-open(id); }
+        new-instance => { root.new-instance(); }
+        instance-view-changed(view) => {
+            root.instance-view = view;
+            root.instance-view-changed(view);
+        }
+        tile-size-changed(size) => {
+            root.tile-size = size;
+            root.tile-size-changed(size);
+        }
+        instance-query-changed(query) => { root.instance-query-changed(query); }
+
+        download-category-changed(category) => {
+            root.download-category = category;
+            root.download-category-changed(category);
+        }
+        download-install(id) => { root.download-install(id); }
+        download-query-changed(query) => {
+            root.download-query = query;
+            root.download-query-changed(query);
+        }
+        ancient-help => { root.ancient-help(); }
+        installed-only-changed(only) => {
+            root.download-installed-only = only;
+            root.installed-only-changed(only);
+        }
+
+        log-select(id) => { root.log-select(id); }
+        log-ask-ai(id) => { root.log-ask-ai(id); }
+        log-apply-fix => { root.log-apply-fix(); }
+
+        settings-section-changed(section) => {
+            root.settings-section = section;
+            root.settings-section-changed(section);
+        }
+        theme-changed(mode) => {
+            root.theme-mode = mode;
+            root.theme-changed(mode);
+        }
+        bg-image-enabled-changed(v) => {
+            root.bg-image-enabled = v;
+            root.bg-image-enabled-changed(v);
+        }
+        bg-image-changed(path) => {
+            root.bg-image = path;
+            root.bg-image-changed(path);
+        }
+        bg-fill-changed(fill) => {
+            root.bg-fill = fill;
+            root.bg-fill-changed(fill);
+        }
+        bg-dim-changed(v) => {
+            root.bg-dim = v;
+            root.bg-dim-changed(v);
+        }
+        panel-alpha-changed(v) => {
+            root.panel-alpha = v;
+            root.panel-alpha-changed(v);
+        }
+        glass-changed(v) => {
+            root.glass = v;
+            root.glass-changed(v);
+        }
+        accent-color-changed(text) => {
+            root.accent-hex = text;
+            root.accent-color-changed(text);
+        }
+        accent-swatch-picked(index) => { root.accent-swatch-picked(index); }
+        yolo-changed(enabled) => { root.yolo-changed(enabled); }
+        mcp-changed(enabled) => { root.mcp-changed(enabled); }
+        ai-endpoint-changed(index) => { root.ai-endpoint-changed(index); }
+
+        dialog-primary => { root.dialog-primary(); }
+        dialog-secondary => { root.dialog-secondary(); }
+        dialog-dismissed => { root.dialog-dismissed(); }
+        toast-dismissed(id) => { root.toast-dismissed(id); }
+    }
+}
diff --git a/crates/app/ui/models.slint b/crates/app/ui/models.slint
new file mode 100644
index 0000000..b1e7dc3
--- /dev/null
+++ b/crates/app/ui/models.slint
@@ -0,0 +1,364 @@
+// UI 视图模型：Rust 的 dto.rs 做单向转换后喂给 Slint（app 不 import core 内部类型，01c §5）。
+// 命名一律 kebab-case，Rust 侧 slint-build 会生成 snake_case 字段。
+// 约定：这里只放「界面要显示什么」，不放领域语义（版本继承链、下载源健康度等留在 core）。
+
+// ── 共享枚举 ─────────────────────────────────────────────────────
+export enum RouteKind {
+    instances,
+    download,
+    logs,
+    settings,
+    detail,
+    agent,
+}
+
+export enum TileSize {
+    small,
+    medium,
+    large,
+}
+
+export enum InstanceView {
+    tiles,
+    list,
+}
+
+/// D17 主题三态：auto 跟随系统（Slint Palette.color-scheme 热更），light/dark 钉死。
+/// 键值 `appearance.theme_mode ∈ {light, dark, auto}`，出厂 auto。
+export enum ThemeMode {
+    auto,
+    light,
+    dark,
+}
+
+/// 背景图填充模式（09 §101：cover / contain / tile）。与 `core::setting::appearance::BgFill` 同序。
+export enum BgFillKind {
+    cover,
+    contain,
+    tile,
+}
+
+export enum LoaderKind {
+    vanilla,
+    fabric,
+    quilt,
+    forge,
+    neoforge,
+    optifine,
+    liteloader,
+}
+
+export enum RuntimePhase {
+    idle,
+    downloading,
+    verifying,
+    launching,
+    running,
+    failed,
+}
+
+export enum ChatRole {
+    user,
+    assistant,
+    tool,
+    system,
+}
+
+export enum DialogKind {
+    confirm,
+    input,
+    progress,
+    error,
+}
+
+export enum ToastKind {
+    info,
+    success,
+    warn,
+    error,
+}
+
+export enum VersionKind {
+    release,
+    snapshot,
+    ancientClassic,
+    ancientAlpha,
+    ancientBeta,
+    ancientUnlisted,
+    modpack,
+    mod,
+}
+
+// 下载页分类侧栏的选中项（远古版把四个子类提升为平级枚值，便于单选高亮）
+export enum DownloadCategory {
+    release,
+    snapshot,
+    ancientClassic,
+    ancientAlpha,
+    ancientBeta,
+    ancientUnlisted,
+    modpack,
+    mod,
+}
+
+export enum LogOutcome {
+    ok,
+    crashed,
+    silentFail,
+}
+
+export enum LogLevel {
+    debug,
+    info,
+    warn,
+    error,
+}
+
+export enum SettingSection {
+    general,
+    /// D17「外观（高级）」：主题三态 / 背景图 / 半透明度 / 玻璃拟态 / 强调色 / 动画强度
+    appearance,
+    data,
+    download,
+    java,
+    account,
+    ai,
+    proxy,
+    about,
+}
+
+// ── 磁贴 ────────────────────────────────────────────────────────
+// row/col 由 Rust state.rs 的 tile_grid() 按当前磁贴尺寸算好（小 6 / 中 4 / 大 3 列），
+// 这样 Slint 侧 GridLayout 只消费整数位置，不必在 DSL 里做除法。
+export struct UiTile {
+    id: string,
+    name: string,
+    mc_version: string,
+    loader: LoaderKind,
+    loader_version: string,
+    /// 加载器徽标文字（「原版」/「Fabric 0.16.5」）：由 Rust 侧用 `LoaderInfo::badge()` 拼好，
+    /// DSL 不做枚举→字符串映射（少一处双份真相）。
+    loader_label: string,
+    last_played: string,
+    phase: RuntimePhase,
+    /// 启动中阶段文案（「下载资源」/「校验文件」/「启动中」），idle 时为空。
+    phase_label: string,
+    /// 0.0~1.0；<= 0 表示进度未知（进度环转为不确定态）。
+    progress: float,
+    /// 实例图标；空 image 时退回「名字首字 + hue 底色」占位。
+    icon: image,
+    hue: color,
+    /// 名字首字，无图标时的占位字母（Rust 侧取首个字素）。
+    initial: string,
+    row: int,
+    col: int,
+}
+
+// ── 下载页 ──────────────────────────────────────────────────────
+export struct UiVersion {
+    id: string,
+    kind: VersionKind,
+    released: string,
+    installed: bool,
+    /// 远古版（classic/alpha/beta/unlisted）——列表行带徽标 + 页顶兼容性提示。
+    ancient: bool,
+}
+
+// ── 日志页 ──────────────────────────────────────────────────────
+export struct UiLogSession {
+    id: string,
+    when: string,
+    instance: string,
+    outcome: LogOutcome,
+    duration: string,
+}
+
+export struct UiLogLine {
+    text: string,
+    level: LogLevel,
+}
+
+/// D8 规则引擎结论（core::diagnose 的 DTO，app 只负责展示）。
+export struct UiDiagnosis {
+    rule: string,
+    title: string,
+    confidence: int,
+    hint: string,
+    has_fix: bool,
+}
+
+// ── AI 栏 ───────────────────────────────────────────────────────
+export struct UiChatMessage {
+    role: ChatRole,
+    text: string,
+    /// role == tool 时的工具名。
+    tool_name: string,
+    tool_ok: bool,
+    /// 流式未完成时 true（末尾显示光标块）。
+    streaming: bool,
+}
+
+// ── 对话框 / Toast ──────────────────────────────────────────────
+export struct UiDialog {
+    id: string,
+    kind: DialogKind,
+    title: string,
+    body: string,
+    primary: string,
+    secondary: string,
+    progress: float,
+    input_label: string,
+    input_value: string,
+}
+
+export struct UiToast {
+    id: string,
+    kind: ToastKind,
+    text: string,
+}
+
+// ── P3 全量接线的视图模型（账户 / Java / 安装 / 设置分组 / 通知 / 向导）──────────
+// 这些类型由 Rust 的 dto 单向转换（`conv/pages.rs`），Slint 只读不写业务真相。
+// 全部经 `page_state.slint` 的 `PageState` global 下发（避免 main/shell 的属性转发膨胀）。
+
+export enum AccountKind {
+    offline,
+    microsoft,
+    authlib,
+}
+
+export struct UiAccount {
+    id: string,
+    name: string,
+    kind: AccountKind,
+    kind_label: string,
+    profile_id: string,
+    login_name: string,
+    created: string,
+    active: bool,
+}
+
+/// 微软登录面板（用户码 / 授权链接都不是凭据，可直接展示）。
+export struct UiDeviceCode {
+    visible: bool,
+    busy: bool,
+    user_code: string,
+    verification_uri: string,
+    qr_link: string,
+    expires: int,
+    message: string,
+    phase_label: string,
+}
+
+export enum JavaStepOutcome {
+    pending,
+    skip,
+    failed,
+    hit,
+}
+
+export struct UiJavaStep {
+    vendor: string,
+    outcome: JavaStepOutcome,
+    outcome_label: string,
+    detail: string,
+}
+
+export struct UiJavaVendor {
+    id: string,
+    display: string,
+    rank: int,
+    majors: string,
+    sources: string,
+    installed: bool,
+}
+
+export struct UiJavaRuntime {
+    binary: string,
+    version: string,
+    vendor: string,
+    origin: string,
+}
+
+export enum InstallStage {
+    planning,
+    downloading,
+    installing,
+    registering,
+    done,
+    failed,
+    cancelled,
+}
+
+export struct UiInstallProgress {
+    visible: bool,
+    version: string,
+    instance: string,
+    loader: string,
+    stage: InstallStage,
+    stage_label: string,
+    ratio: float,
+    known: bool,
+    files_label: string,
+    bytes_label: string,
+    speed: string,
+    eta: string,
+    message: string,
+    terminal: bool,
+    failed: bool,
+}
+
+export enum SettingControl {
+    toggle,
+    choice,
+    text,
+    readonly,
+    action,
+}
+
+export struct UiSettingRow {
+    key: string,
+    label: string,
+    description: string,
+    control: SettingControl,
+    flag: bool,
+    selected: int,
+    options: [string],
+    value_text: string,
+    action: string,
+}
+
+export struct UiSettingGroup {
+    id: string,
+    title: string,
+    rows: [UiSettingRow],
+}
+
+export enum NoticeKind {
+    info,
+    warn,
+    error,
+}
+
+export struct UiNotice {
+    id: string,
+    kind: NoticeKind,
+    title: string,
+    body: string,
+}
+
+export struct UiWizard {
+    open: bool,
+    step: int,
+    step_label: string,
+    step_index: int,
+    step_total: int,
+    version: string,
+    loader: int,
+    loader_label: string,
+    loader_version: string,
+    name: string,
+    error: string,
+    busy: bool,
+    can-next: bool,
+}
diff --git a/crates/app/ui/page_state.slint b/crates/app/ui/page_state.slint
new file mode 100644
index 0000000..a20cb12
--- /dev/null
+++ b/crates/app/ui/page_state.slint
@@ -0,0 +1,77 @@
+// P3 全量接线的页面状态：一个导出的 global，Slint 任何页面都能直接读/回推。
+//
+// 为什么用 global 而不是继续经 main.slint → shell.slint 逐层转发：属性表已经 100+ 条，
+// 再加五页的数据会把 main.slint 顶破 400 行上限（AGENTS §3）。global 在同一个 Slint
+// 编译单元内是单例，Rust 侧用 `ui.global::<PageState>()` 读写，语义与 property 相同。
+//
+// 纪律：这里只放「页面要显示什么」与「用户点了什么」，业务真相在 Rust 的 state.rs。
+import { UiAccount, UiDeviceCode, UiJavaVendor, UiJavaStep, UiJavaRuntime, UiInstallProgress, UiSettingGroup, UiNotice, UiWizard, UiVersion } from "models.slint";
+
+export global PageState {
+    // ── 账户页 ────────────────────────────────────────────────
+    in-out property <[UiAccount]> accounts;
+    in property <string> active-account: "";
+    in property <UiDeviceCode> device;
+    /// 离线添加表单的输入（不落盘，点「添加」才提交）
+    in-out property <string> offline-name: "";
+
+    // ── Java（下载页 Java 分组 / 设置页 Java 分组）──────────────
+    in property <[UiJavaVendor]> java-vendors;
+    in property <[UiJavaStep]> java-chain;
+    in property <[UiJavaRuntime]> java-runtimes;
+    in property <string> java-order: "";
+    in property <string> java-region: "";
+    in property <string> java-priority-source: "";
+    in property <string> java-message: "";
+    in property <bool> java-busy: false;
+    in property <int> java-target-major: 17;
+
+    // ── 安装进度（下载页 + 向导共用）────────────────────────────
+    in property <UiInstallProgress> install;
+    /// 下载页右侧视图：0 = 版本列表，1 = Java 运行时（截图通道也从这里切）
+    in-out property <int> download-tab: 0;
+
+    // ── 设置分组（settings_bridge 同源 launcher.json）──────────
+    in property <[UiSettingGroup]> setting-groups;
+    in-out property <string> setting-tab: "download";
+
+    // ── 通知条 / 向导 ─────────────────────────────────────────
+    in property <[UiNotice]> notices;
+    in property <UiWizard> wizard;
+    in property <[UiVersion]> wizard-versions;
+
+    // ── 账户 ──────────────────────────────────────────────────
+    callback account-add-offline(string);
+    callback account-remove(string);
+    callback account-switch(string);
+    callback msa-begin();
+    callback msa-browser-begin();
+    callback msa-cancel();
+
+    // ── Java ──────────────────────────────────────────────────
+    callback java-install(string);
+
+    // ── 设置 ──────────────────────────────────────────────────
+    callback setting-changed(string, string);
+    callback setting-action(string);
+    callback settings-tab-changed(string);
+
+    // ── 通知 ──────────────────────────────────────────────────
+    callback notice-dismiss(string);
+
+    // ── 向导 ──────────────────────────────────────────────────
+    callback wizard-open();
+    callback wizard-close();
+    callback wizard-select-version(string);
+    callback wizard-select-loader(int);
+    callback wizard-name-changed(string);
+    callback wizard-next();
+    callback wizard-back();
+    callback wizard-confirm();
+    callback install-cancel();
+
+    // ── 日志页：崩溃日志导入 / 手动刷新 ──────────────────────────
+    in-out property <string> crash-path: "";
+    callback crash-import(string);
+    callback logs-refresh();
+}
diff --git a/crates/app/ui/pages/download-java.slint b/crates/app/ui/pages/download-java.slint
new file mode 100644
index 0000000..358cd64
--- /dev/null
+++ b/crates/app/ui/pages/download-java.slint
@@ -0,0 +1,204 @@
+// 下载页 · Java 分组（G2 的第二个分类）：四家发行版 + 回退链可视化 + 本地运行时。
+//
+// 回退链是「可观测性」核心：安装失败时用户要能看见 Temurin 跳过 → Oracle 失败 →
+// Microsoft 命中的每一步原因（D23），而不是只看到一句「下载失败」。
+import { Theme } from "../theme/tokens.slint";
+import { Metrics } from "../theme/metrics.slint";
+import { UiJavaVendor, UiJavaStep, UiJavaRuntime, JavaStepOutcome } from "../models.slint";
+import { PageState } from "../page_state.slint";
+import { UiText, TextRole } from "../components/label.slint";
+import { Badge } from "../components/badge.slint";
+import { AppIcon, IconKind } from "../components/icons.slint";
+import { MetroButton, ButtonKind } from "../widgets/button.slint";
+import { ScrollView } from "std-widgets.slint";
+
+component ChainStep inherits Rectangle {
+    in property <UiJavaStep> step;
+
+    height: 26px;
+    background: transparent;
+
+    HorizontalLayout {
+        spacing: Metrics.gap-1;
+
+        AppIcon {
+            icon-size: 12px;
+            kind: root.step.outcome == JavaStepOutcome.hit ? IconKind.check
+                : root.step.outcome == JavaStepOutcome.failed ? IconKind.error
+                : root.step.outcome == JavaStepOutcome.skip ? IconKind.warn
+                : IconKind.more;
+            tint: root.step.outcome == JavaStepOutcome.hit ? Theme.state-success
+                : root.step.outcome == JavaStepOutcome.failed ? Theme.state-danger
+                : Theme.fg-secondary;
+        }
+        UiText {
+            role: TextRole.caption;
+            text: root.step.vendor;
+            width: 72px;
+            color: root.step.outcome == JavaStepOutcome.hit ? Theme.state-success : Theme.fg-primary;
+        }
+        Badge {
+            text: root.step.outcome_label;
+            tint: root.step.outcome == JavaStepOutcome.hit ? Theme.state-success
+                : root.step.outcome == JavaStepOutcome.failed ? Theme.state-danger
+                : Theme.fg-secondary;
+        }
+        UiText {
+            role: TextRole.caption;
+            text: root.step.detail;
+            horizontal-stretch: 1;
+            overflow: elide;
+        }
+    }
+}
+
+component VendorRow inherits Rectangle {
+    in property <UiJavaVendor> data;
+    callback install();
+
+    height: 56px;
+    background: vendor-touch.has-hover ? Theme.bg-hover : transparent;
+
+    HorizontalLayout {
+        padding-left: Metrics.gap-3;
+        padding-right: Metrics.gap-3;
+        spacing: Metrics.gap-2;
+
+        UiText {
+            role: TextRole.bodyStrong;
+            text: root.data.rank + ". " + root.data.display;
+            width: 170px;
+        }
+        if root.data.installed : Badge { text: "已装"; tint: Theme.state-success; }
+        UiText {
+            role: TextRole.caption;
+            text: "Java " + root.data.majors;
+            width: 96px;
+        }
+        UiText {
+            role: TextRole.caption;
+            text: root.data.sources;
+            horizontal-stretch: 1;
+            overflow: elide;
+        }
+        MetroButton {
+            kind: ButtonKind.standard;
+            text: "安装此家";
+            button-height: 26px;
+            enabled: !PageState.java-busy;
+            clicked => { root.install(); }
+        }
+    }
+
+    vendor-touch := TouchArea {
+        mouse-cursor: pointer;
+        clicked => { root.install(); }
+    }
+}
+
+export component JavaPanel inherits Rectangle {
+    background: Theme.bg-canvas;
+
+    VerticalLayout {
+        // 顶栏：地区 / 优先级来源 / 目标大版本 / 一键按回退链安装
+        Rectangle {
+            height: 56px;
+            background: Theme.bg-canvas;
+
+            HorizontalLayout {
+                padding-left: Metrics.gap-4;
+                padding-right: Metrics.gap-4;
+                spacing: Metrics.gap-3;
+
+                UiText {
+                    role: TextRole.subtitle;
+                    text: "Java 运行时";
+                    width: 110px;
+                }
+                UiText {
+                    role: TextRole.caption;
+                    text: "地区 " + PageState.java-region + " · 优先级 " + PageState.java-priority-source
+                        + " · 目标 Java " + PageState.java-target-major;
+                    horizontal-stretch: 1;
+                    overflow: elide;
+                }
+                MetroButton {
+                    kind: ButtonKind.accent;
+                    text: PageState.java-busy ? "安装中…" : "按回退链安装";
+                    button-height: 28px;
+                    enabled: !PageState.java-busy;
+                    clicked => { PageState.java-install(""); }
+                }
+            }
+        }
+
+        UiText {
+            x: Metrics.gap-4;
+            role: TextRole.caption;
+            text: PageState.java-order;
+            horizontal-stretch: 1;
+            overflow: elide;
+        }
+
+        if PageState.java-message != "" : Rectangle {
+            height: 30px;
+            background: Theme.accent-soft;
+            UiText {
+                x: Metrics.gap-4;
+                role: TextRole.caption;
+                text: PageState.java-message;
+                overflow: elide;
+            }
+        }
+
+        Rectangle { height: 1px; background: Theme.stroke; }
+
+        ScrollView {
+            vertical-stretch: 1;
+
+            VerticalLayout {
+                padding-bottom: Metrics.gap-4;
+
+                // 回退链
+                UiText {
+                    x: Metrics.gap-4;
+                    role: TextRole.bodyStrong;
+                    text: "回退链";
+                }
+                for step in PageState.java-chain : ChainStep { step: step; }
+
+                UiText {
+                    x: Metrics.gap-4;
+                    role: TextRole.bodyStrong;
+                    text: "四家发行版";
+                }
+                for vendor in PageState.java-vendors : VendorRow {
+                    data: vendor;
+                    install => { PageState.java-install(vendor.id); }
+                }
+
+                UiText {
+                    x: Metrics.gap-4;
+                    role: TextRole.bodyStrong;
+                    text: "本地已发现";
+                }
+                if PageState.java-runtimes.length == 0 : UiText {
+                    x: Metrics.gap-4;
+                    role: TextRole.caption;
+                    text: "还没有探测到 Java：点上面的「按回退链安装」装一个托管 JDK。";
+                }
+                for runtime in PageState.java-runtimes : Rectangle {
+                    height: 24px;
+                    HorizontalLayout {
+                        padding-left: Metrics.gap-4;
+                        spacing: Metrics.gap-2;
+                        UiText { role: TextRole.caption; text: "Java " + runtime.version; width: 120px; }
+                        UiText { role: TextRole.caption; text: runtime.vendor; width: 96px; }
+                        UiText { role: TextRole.caption; text: runtime.origin; width: 80px; }
+                        UiText { role: TextRole.caption; text: runtime.binary; horizontal-stretch: 1; overflow: elide; }
+                    }
+                }
+            }
+        }
+    }
+}
diff --git a/crates/app/ui/pages/download.slint b/crates/app/ui/pages/download.slint
new file mode 100644
index 0000000..d7d14e3
--- /dev/null
+++ b/crates/app/ui/pages/download.slint
@@ -0,0 +1,320 @@
+// G2 下载页（09 §2 P0·G2 / Q24-4 定案）：页内独立左侧分类栏（常驻，非 tab）+ 右侧版本列表。
+// 远古版入口显式可达（ULL 对 HMCL「隐藏」行为的纠偏），下挂 classic/alpha/beta/unlisted 子类树，
+// 进入远古版分类时顶部提示兼容性 + 每行带「远古版」徽标（防误装）。
+//
+// P3 接线：右侧多一个「Java 运行时」视图（四家发行版 + 回退链），页面底部常驻安装进度条。
+import { Theme } from "../theme/tokens.slint";
+import { Metrics } from "../theme/metrics.slint";
+import { UiVersion, VersionKind, DownloadCategory } from "../models.slint";
+import { PageState } from "../page_state.slint";
+import { UiText, TextRole } from "../components/label.slint";
+import { AppIcon, IconKind } from "../components/icons.slint";
+import { Badge } from "../components/badge.slint";
+import { MetroButton, ButtonKind } from "../widgets/button.slint";
+import { SearchField, CheckBox } from "../widgets/inputs.slint";
+import { InstallPanel } from "../components/install-panel.slint";
+import { JavaPanel } from "download-java.slint";
+import { ListView } from "std-widgets.slint";
+
+component CategoryRow inherits Rectangle {
+    in property <string> label: "";
+    in property <bool> active: false;
+    in property <bool> sub: false;
+    in property <bool> disabled: false;
+    callback clicked();
+
+    height: 34px;
+    background: root.active ? Theme.accent-soft : (row-touch.has-hover ? Theme.bg-hover : transparent);
+
+    if root.active : Rectangle {
+        x: 0;
+        y: 0;
+        width: 3px;
+        height: root.height;
+        background: Theme.accent;
+    }
+
+    UiText {
+        x: root.sub ? Metrics.gap-5 : Metrics.gap-3;
+        width: root.width - (root.sub ? Metrics.gap-5 : Metrics.gap-3) - Metrics.gap-2;
+        height: root.height;
+        role: TextRole.body;
+        text: root.label;
+        color: root.disabled ? Theme.fg-disabled
+            : root.active ? Theme.accent
+            : Theme.fg-primary;
+    }
+
+    row-touch := TouchArea {
+        mouse-cursor: root.disabled ? default : pointer;
+        clicked => {
+            if (!root.disabled) {
+                root.clicked();
+            }
+        }
+    }
+}
+
+component VersionRow inherits Rectangle {
+    in property <UiVersion> data;
+    callback install();
+
+    height: Metrics.row-height + 8px;
+    background: row-touch.has-hover ? Theme.bg-hover : transparent;
+
+    HorizontalLayout {
+        padding-left: Metrics.gap-4;
+        padding-right: Metrics.gap-4;
+        spacing: Metrics.gap-2;
+
+        UiText {
+            role: TextRole.bodyStrong;
+            text: root.data.id;
+            width: 160px;
+        }
+
+        Badge {
+            text: root.data.kind == VersionKind.release ? "正式版"
+                : root.data.kind == VersionKind.snapshot ? "预览版"
+                : "远古版";
+            tint: root.data.ancient ? Theme.state-warn : Theme.fg-secondary;
+        }
+
+        UiText {
+            role: TextRole.caption;
+            text: root.data.released;
+            horizontal-stretch: 1;
+        }
+
+        if root.data.installed : HorizontalLayout {
+            spacing: Metrics.gap-1;
+            AppIcon { kind: IconKind.check; icon-size: 12px; tint: Theme.state-success; }
+            UiText {
+                role: TextRole.caption;
+                text: "已装";
+                color: Theme.state-success;
+            }
+        }
+
+        MetroButton {
+            kind: ButtonKind.standard;
+            text: root.data.installed ? "重装" : "安装";
+            button-height: 26px;
+            clicked => { root.install(); }
+        }
+    }
+
+    row-touch := TouchArea {
+        mouse-cursor: pointer;
+        clicked => { root.install(); }
+    }
+}
+
+export component DownloadPage inherits Rectangle {
+    in property <[UiVersion]> versions;
+    in-out property <DownloadCategory> category: DownloadCategory.release;
+    in-out property <bool> installed-only: false;
+    in-out property <string> query: "";
+    /// 远古版子类树是否展开（默认展开，显式可达）
+    in-out property <bool> ancient-expanded: true;
+    /// 右侧视图：0 = 版本列表，1 = Java 运行时
+    in-out property <int> view-tab <=> PageState.download-tab;
+
+    callback category-changed(DownloadCategory);
+    callback install(string);
+    callback installed-only-changed(bool);
+    callback query-changed(string);
+    callback toggle-ancient();
+    /// 远古版兼容性说明（P1 出说明页；当前由 Rust 侧弹 Toast 占位）
+    callback ancient-help();
+
+    background: Theme.bg-canvas;
+
+    VerticalLayout {
+        // 视图切换（版本 / Java）
+        Rectangle {
+            height: 40px;
+            background: Theme.bg-surface;
+            HorizontalLayout {
+                padding-left: Metrics.gap-4;
+                spacing: Metrics.gap-2;
+                UiText {
+                    role: TextRole.subtitle;
+                    text: "版本获取";
+                    width: 96px;
+                }
+                MetroButton {
+                    kind: root.view-tab == 0 ? ButtonKind.accent : ButtonKind.subtle;
+                    text: "版本列表";
+                    button-height: 26px;
+                    clicked => { root.view-tab = 0; }
+                }
+                MetroButton {
+                    kind: root.view-tab == 1 ? ButtonKind.accent : ButtonKind.subtle;
+                    text: "Java 运行时";
+                    button-height: 26px;
+                    clicked => { root.view-tab = 1; }
+                }
+                Rectangle { horizontal-stretch: 1; background: transparent; }
+                if PageState.java-busy : UiText {
+                    role: TextRole.caption;
+                    text: "Java 安装中…";
+                    color: Theme.accent;
+                }
+            }
+        }
+        Rectangle { height: 1px; background: Theme.stroke; }
+
+        if root.view-tab == 0 : HorizontalLayout {
+            vertical-stretch: 1;
+
+            // ── 页内分类侧栏（常驻）───────────────────────────────────
+            Rectangle {
+                width: 200px;
+                background: Theme.bg-surface;
+                border-width: 1px;
+                border-color: Theme.stroke;
+
+                VerticalLayout {
+                    padding-top: Metrics.gap-2;
+
+                    CategoryRow {
+                        label: "正式版 release";
+                        active: root.category == DownloadCategory.release;
+                        clicked => { root.category-changed(DownloadCategory.release); }
+                    }
+                    CategoryRow {
+                        label: "预览版 snapshot";
+                        active: root.category == DownloadCategory.snapshot;
+                        clicked => { root.category-changed(DownloadCategory.snapshot); }
+                    }
+
+                    // 远古版：可展开的父节点 + 子类树
+                    CategoryRow {
+                        label: root.ancient-expanded ? "远古版 ▾" : "远古版 ▸";
+                        active: root.category == DownloadCategory.ancientClassic
+                            || root.category == DownloadCategory.ancientAlpha
+                            || root.category == DownloadCategory.ancientBeta
+                            || root.category == DownloadCategory.ancientUnlisted;
+                        clicked => { root.toggle-ancient(); }
+                    }
+                    if root.ancient-expanded : CategoryRow {
+                        label: "classic（rd-*）";
+                        sub: true;
+                        active: root.category == DownloadCategory.ancientClassic;
+                        clicked => { root.category-changed(DownloadCategory.ancientClassic); }
+                    }
+                    if root.ancient-expanded : CategoryRow {
+                        label: "old_alpha（a1.*）";
+                        sub: true;
+                        active: root.category == DownloadCategory.ancientAlpha;
+                        clicked => { root.category-changed(DownloadCategory.ancientAlpha); }
+                    }
+                    if root.ancient-expanded : CategoryRow {
+                        label: "old_beta（b1.*）";
+                        sub: true;
+                        active: root.category == DownloadCategory.ancientBeta;
+                        clicked => { root.category-changed(DownloadCategory.ancientBeta); }
+                    }
+                    if root.ancient-expanded : CategoryRow {
+                        label: "unlisted 汇总";
+                        sub: true;
+                        active: root.category == DownloadCategory.ancientUnlisted;
+                        clicked => { root.category-changed(DownloadCategory.ancientUnlisted); }
+                    }
+
+                    CategoryRow {
+                        label: "整合包（P1）";
+                        disabled: true;
+                    }
+                    CategoryRow {
+                        label: "Mod（P1）";
+                        disabled: true;
+                    }
+
+                    Rectangle { vertical-stretch: 1; background: transparent; }
+                }
+            }
+
+            // ── 右侧版本列表 ──────────────────────────────────────────
+            VerticalLayout {
+                vertical-stretch: 1;
+
+                Rectangle {
+                    height: Metrics.page-header-height;
+                    background: Theme.bg-canvas;
+
+                    HorizontalLayout {
+                        padding-left: Metrics.gap-4;
+                        padding-right: Metrics.gap-4;
+                        spacing: Metrics.gap-3;
+
+                        SearchField {
+                            width: 220px;
+                            placeholder: "筛选版本号";
+                            text <=> root.query;
+                            edited(t) => { root.query-changed(t); }
+                        }
+                        CheckBox {
+                            text: "仅已装";
+                            checked: root.installed-only;
+                            toggled(v) => { root.installed-only-changed(v); }
+                        }
+                        Rectangle { horizontal-stretch: 1; background: transparent; }
+                    }
+                }
+
+                // 远古版兼容性提示条（首次进入显示，显式可达的代价告知）
+                Rectangle {
+                    height: 44px;
+                    visible: root.category == DownloadCategory.ancientClassic
+                        || root.category == DownloadCategory.ancientAlpha
+                        || root.category == DownloadCategory.ancientBeta
+                        || root.category == DownloadCategory.ancientUnlisted;
+                    background: Theme.state-warn-soft;
+
+                    HorizontalLayout {
+                        padding-left: Metrics.gap-4;
+                        padding-right: Metrics.gap-4;
+                        spacing: Metrics.gap-2;
+
+                        AppIcon { kind: IconKind.warn; icon-size: 16px; tint: Theme.state-warn; }
+                        UiText {
+                            role: TextRole.caption;
+                            text: "远古版（classic/alpha/beta）需要旧版 Java 与旧启动参数，装完请先看兼容性说明。";
+                            wrap: word-wrap;
+                            horizontal-stretch: 1;
+                        }
+                        MetroButton {
+                            kind: ButtonKind.subtle;
+                            text: "说明";
+                            button-height: 26px;
+                            clicked => { root.ancient-help(); }
+                        }
+                    }
+                }
+
+                Rectangle { height: 1px; background: Theme.stroke; }
+
+                ListView {
+                    vertical-stretch: 1;
+
+                    for v in root.versions : VersionRow {
+                        data: v;
+                        install => { root.install(v.id); }
+                    }
+                }
+            }
+        }
+
+        if root.view-tab == 1 : JavaPanel {
+            vertical-stretch: 1;
+        }
+
+        // 安装进度（下载页行内安装 / 向导共用同一份进度）
+        InstallPanel {
+            data: PageState.install;
+            cancel => { PageState.install-cancel(); }
+        }
+    }
+}
diff --git a/crates/app/ui/pages/instances.slint b/crates/app/ui/pages/instances.slint
new file mode 100644
index 0000000..3495bd5
--- /dev/null
+++ b/crates/app/ui/pages/instances.slint
@@ -0,0 +1,260 @@
+// G1 实例页（09 §2 P0·G1）：顶栏（搜索/新建/视图切换/磁贴尺寸）+ 磁贴网格 + 运行中迷你状态条。
+// 网格用 GridLayout：列数由 Rust 按磁贴尺寸算好（小 6 / 中 4 / 大 3），row/col 随 UiTile 一起给。
+import { Theme } from "../theme/tokens.slint";
+import { Metrics } from "../theme/metrics.slint";
+import { UiTile, InstanceView, TileSize, RuntimePhase } from "../models.slint";
+import { UiText, TextRole } from "../components/label.slint";
+import { AppIcon, IconKind } from "../components/icons.slint";
+import { MetroButton, ButtonKind } from "../widgets/button.slint";
+import { SearchField, SegmentedControl } from "../widgets/inputs.slint";
+import { InstanceTile } from "../components/tile.slint";
+import { ListView } from "std-widgets.slint";
+
+// 列表视图的一行（与磁贴共用同一份 UiTile 数据）
+component InstanceRow inherits Rectangle {
+    in property <UiTile> data;
+    callback open();
+    callback launch();
+
+    height: Metrics.row-height + 8px;
+    background: row-touch.has-hover ? Theme.bg-hover : transparent;
+
+    // 行点击区先声明，按钮后声明 → 按钮命中优先
+    row-touch := TouchArea {
+        mouse-cursor: pointer;
+        clicked => { root.open(); }
+    }
+
+    HorizontalLayout {
+        padding-left: Metrics.gap-3;
+        padding-right: Metrics.gap-3;
+        spacing: Metrics.gap-3;
+
+        Rectangle {
+            width: 28px;
+            height: 28px;
+            border-radius: Metrics.radius-sm;
+            background: root.data.hue;
+
+            UiText {
+                text: root.data.initial;
+                font-size: 13px;
+                font-weight: 600;
+                color: Theme.fg-on-accent;
+                horizontal-alignment: center;
+                vertical-alignment: center;
+            }
+        }
+
+        UiText {
+            role: TextRole.body;
+            text: root.data.name;
+            horizontal-stretch: 1;
+        }
+        UiText {
+            role: TextRole.caption;
+            text: root.data.mc_version;
+            width: 88px;
+        }
+        UiText {
+            role: TextRole.caption;
+            text: root.data.loader_label;
+            width: 88px;
+        }
+        UiText {
+            role: TextRole.caption;
+            text: root.data.last_played;
+            width: 120px;
+        }
+
+        MetroButton {
+            kind: ButtonKind.subtle;
+            icon: IconKind.play;
+            icon-only: true;
+            enabled: root.data.phase == RuntimePhase.idle
+                || root.data.phase == RuntimePhase.failed;
+            clicked => { root.launch(); }
+        }
+    }
+}
+
+export component InstancesPage inherits Rectangle {
+    in property <[UiTile]> tiles;
+    in property <[UiTile]> running;
+    in property <InstanceView> view: InstanceView.tiles;
+    in-out property <TileSize> tile-size: TileSize.medium;
+    in-out property <string> query: "";
+
+    callback launch(string);
+    callback configure(string);
+    callback stop(string);
+    callback open(string);
+    callback new-instance();
+    callback view-changed(InstanceView);
+    callback tile-size-changed(TileSize);
+    callback query-changed(string);
+
+    background: Theme.bg-canvas;
+
+    VerticalLayout {
+        // ── 顶栏 ────────────────────────────────────────────────
+        Rectangle {
+            height: Metrics.page-header-height;
+            background: Theme.bg-surface;
+
+            HorizontalLayout {
+                padding-left: Metrics.gap-4;
+                padding-right: Metrics.gap-4;
+                spacing: Metrics.gap-2;
+
+                UiText {
+                    role: TextRole.subtitle;
+                    text: "实例";
+                    width: 72px;
+                }
+
+                SearchField {
+                    width: 240px;
+                    placeholder: "搜索实例";
+                    text <=> root.query;
+                    edited(t) => { root.query-changed(t); }
+                }
+
+                Rectangle { horizontal-stretch: 1; background: transparent; }
+
+                SegmentedControl {
+                    width: 120px;
+                    options: ["磁贴", "列表"];
+                    selected: root.view == InstanceView.tiles ? 0 : 1;
+                    changed(i) => {
+                        root.view-changed(i == 0 ? InstanceView.tiles : InstanceView.list);
+                    }
+                }
+
+                SegmentedControl {
+                    width: 132px;
+                    visible: root.view == InstanceView.tiles;
+                    options: ["小", "中", "大"];
+                    selected: root.tile-size == TileSize.small ? 0
+                        : root.tile-size == TileSize.large ? 2 : 1;
+                    changed(i) => {
+                        root.tile-size-changed(
+                            i == 0 ? TileSize.small : i == 2 ? TileSize.large : TileSize.medium);
+                    }
+                }
+
+                MetroButton {
+                    kind: ButtonKind.accent;
+                    text: "新建实例";
+                    show-icon: true;
+                    icon: IconKind.plus;
+                    clicked => { root.new-instance(); }
+                }
+            }
+        }
+
+        Rectangle { height: 1px; background: Theme.stroke; }
+
+        // ── 运行中迷你状态条 ──────────────────────────────────────
+        Rectangle {
+            height: Metrics.running-strip-height;
+            visible: root.running.length > 0;
+            background: Theme.state-info-soft;
+
+            HorizontalLayout {
+                padding-left: Metrics.gap-4;
+                padding-right: Metrics.gap-4;
+                spacing: Metrics.gap-2;
+
+                Rectangle {
+                    width: 8px;
+                    height: 8px;
+                    border-radius: 4px;
+                    background: Theme.state-success;
+                }
+                UiText {
+                    role: TextRole.caption;
+                    text: root.running.length + " 个实例运行中";
+                    color: Theme.state-success;
+                    horizontal-stretch: 1;
+                }
+                for r in root.running : UiText {
+                    role: TextRole.caption;
+                    text: r.name;
+                }
+            }
+        }
+
+        // ── 磁贴网格 ─────────────────────────────────────────────
+        body := Flickable {
+            vertical-stretch: 1;
+            visible: root.view == InstanceView.tiles && root.tiles.length > 0;
+            content-width: self.width;
+            content-height: grid-content.height;
+
+            grid-content := Rectangle {
+                width: body.width;
+                height: grid.preferred-height;
+                background: transparent;
+
+                grid := GridLayout {
+                    padding: Metrics.gap-4;
+                    spacing: Metrics.gap-3;
+
+                    for t in root.tiles : InstanceTile {
+                        row: t.row;
+                        col: t.col;
+                        data: t;
+                        compact: root.tile-size == TileSize.small;
+                        open => { root.open(t.id); }
+                        launch => { root.launch(t.id); }
+                        configure => { root.configure(t.id); }
+                        stop => { root.stop(t.id); }
+                    }
+                }
+            }
+        }
+
+        // ── 列表视图 ─────────────────────────────────────────────
+        ListView {
+            vertical-stretch: 1;
+            visible: root.view == InstanceView.list && root.tiles.length > 0;
+
+            for t in root.tiles : InstanceRow {
+                data: t;
+                open => { root.open(t.id); }
+                launch => { root.launch(t.id); }
+            }
+        }
+
+        // ── 空态 ────────────────────────────────────────────────
+        VerticalLayout {
+            vertical-stretch: 1;
+            visible: root.tiles.length == 0;
+            alignment: center;
+            spacing: Metrics.gap-3;
+
+            UiText {
+                role: TextRole.title;
+                text: "还没有实例";
+                horizontal-alignment: center;
+                color: Theme.fg-secondary;
+            }
+            UiText {
+                role: TextRole.caption;
+                text: "新建一个实例，或者先去下载页装个版本";
+                horizontal-alignment: center;
+            }
+            HorizontalLayout {
+                alignment: center;
+                MetroButton {
+                    kind: ButtonKind.accent;
+                    text: "新建实例";
+                    show-icon: true;
+                    icon: IconKind.plus;
+                    clicked => { root.new-instance(); }
+                }
+            }
+        }
+    }
+}
diff --git a/crates/app/ui/pages/logs.slint b/crates/app/ui/pages/logs.slint
new file mode 100644
index 0000000..a7699ea
--- /dev/null
+++ b/crates/app/ui/pages/logs.slint
@@ -0,0 +1,289 @@
+// G3 日志页（09 §2 P0·G3）：左侧会话列表（✓正常 / ✗崩溃 / ⚠静默失败）+ 右侧日志流 + 崩溃诊断卡片。
+// 诊断卡片 = D8 规则引擎结论（命中规则 + 置信度 + 修复动作 + 跳 AI 栏带上下文）。
+import { Theme } from "../theme/tokens.slint";
+import { Metrics } from "../theme/metrics.slint";
+import { UiLogSession, UiLogLine, UiDiagnosis, LogOutcome, LogLevel } from "../models.slint";
+import { UiText, TextRole } from "../components/label.slint";
+import { AppIcon, IconKind } from "../components/icons.slint";
+import { Badge } from "../components/badge.slint";
+import { MetroButton, ButtonKind } from "../widgets/button.slint";
+import { SearchField } from "../widgets/inputs.slint";
+import { PageState } from "../page_state.slint";
+import { ListView } from "std-widgets.slint";
+
+component SessionRow inherits Rectangle {
+    in property <UiLogSession> data;
+    in property <bool> active: false;
+    callback clicked();
+
+    height: 52px;
+    background: root.active ? Theme.accent-soft : (row-touch.has-hover ? Theme.bg-hover : transparent);
+
+    if root.active : Rectangle {
+        x: 0;
+        y: 0;
+        width: 3px;
+        height: root.height;
+        background: Theme.accent;
+    }
+
+    HorizontalLayout {
+        padding-left: Metrics.gap-3;
+        padding-right: Metrics.gap-2;
+        spacing: Metrics.gap-2;
+
+        AppIcon {
+            icon-size: 14px;
+            kind: root.data.outcome == LogOutcome.ok ? IconKind.check
+                : root.data.outcome == LogOutcome.crashed ? IconKind.error
+                : IconKind.warn;
+            tint: root.data.outcome == LogOutcome.ok ? Theme.state-success
+                : root.data.outcome == LogOutcome.crashed ? Theme.state-danger
+                : Theme.state-warn;
+        }
+
+        VerticalLayout {
+            spacing: 0px;
+            vertical-stretch: 1;
+
+            UiText {
+                role: TextRole.body;
+                text: root.data.instance;
+                horizontal-stretch: 1;
+            }
+            UiText {
+                role: TextRole.caption;
+                text: root.data.when;
+                horizontal-stretch: 1;
+            }
+        }
+
+        UiText {
+            role: TextRole.caption;
+            text: root.data.duration;
+            width: 56px;
+            horizontal-alignment: right;
+        }
+    }
+
+    row-touch := TouchArea {
+        mouse-cursor: pointer;
+        clicked => { root.clicked(); }
+    }
+}
+
+component LogRow inherits Rectangle {
+    in property <UiLogLine> line;
+
+    height: 18px;
+    background: root.line.level == LogLevel.error
+        ? Theme.state-danger-soft
+        : transparent;
+
+    UiText {
+        x: Metrics.gap-2;
+        y: 0;
+        width: root.width - 2 * Metrics.gap-2;
+        height: root.height;
+        role: TextRole.monoSmall;
+        text: root.line.text;
+        color: root.line.level == LogLevel.error ? Theme.state-danger
+            : root.line.level == LogLevel.warn ? Theme.state-warn
+            : root.line.level == LogLevel.debug ? Theme.fg-disabled
+            : Theme.fg-primary;
+    }
+}
+
+export component LogsPage inherits Rectangle {
+    in property <[UiLogSession]> sessions;
+    in property <[UiLogLine]> lines;
+    in property <UiDiagnosis> diagnosis;
+    in property <bool> has-diagnosis: false;
+    in property <bool> live: false;
+    in-out property <string> selected: "";
+    in-out property <string> query: "";
+
+    callback select(string);
+    callback ask-ai(string);
+    callback apply-fix();
+    callback query-changed(string);
+    /// 重新扫会话索引（手动刷新）
+    callback refresh();
+
+    background: Theme.bg-canvas;
+
+    HorizontalLayout {
+        // ── 左侧会话列表 ─────────────────────────────────────────
+        Rectangle {
+            width: 248px;
+            background: Theme.bg-surface;
+
+            VerticalLayout {
+                Rectangle {
+                    height: 44px;
+                    background: transparent;
+
+                    HorizontalLayout {
+                        padding-left: Metrics.gap-3;
+                        padding-right: Metrics.gap-2;
+                        spacing: Metrics.gap-2;
+
+                        UiText {
+                            role: TextRole.bodyStrong;
+                            text: "会话";
+                            horizontal-stretch: 1;
+                        }
+                        if root.live : Rectangle {
+                            width: 6px;
+                            height: 6px;
+                            border-radius: 3px;
+                            background: Theme.state-success;
+                        }
+                    }
+                }
+
+                ListView {
+                    vertical-stretch: 1;
+
+                    for s in root.sessions : SessionRow {
+                        data: s;
+                        active: root.selected == s.id;
+                        clicked => { root.select(s.id); }
+                    }
+                }
+            }
+        }
+
+        Rectangle { width: 1px; background: Theme.stroke; }
+
+        // ── 右侧日志流 + 诊断卡片 ────────────────────────────────
+        VerticalLayout {
+            vertical-stretch: 1;
+
+            // 会话头：标题 + 实时标记 + 筛选 + 刷新（第一行），崩溃日志导入（第二行）
+            Rectangle {
+                height: 84px;
+                background: Theme.bg-surface;
+
+                VerticalLayout {
+                    HorizontalLayout {
+                        height: 44px;
+                        padding-left: Metrics.gap-3;
+                        padding-right: Metrics.gap-3;
+                        spacing: Metrics.gap-2;
+
+                        UiText {
+                            role: TextRole.bodyStrong;
+                            text: root.selected == "" ? "未选择会话" : root.selected;
+                            horizontal-stretch: 1;
+                            overflow: elide;
+                        }
+                        if root.live : Badge { text: "实时"; tint: Theme.state-success; }
+                        SearchField {
+                            width: 140px;
+                            placeholder: "筛选日志行";
+                            text <=> root.query;
+                            edited(t) => { root.query-changed(t); }
+                        }
+                        MetroButton {
+                            kind: ButtonKind.subtle;
+                            text: "刷新";
+                            button-height: 26px;
+                            clicked => { root.refresh(); }
+                        }
+                    }
+
+                    // 崩溃日志导入分析（hs_err_pid*.log / crash-*.txt / latest.log）
+                    HorizontalLayout {
+                        height: 40px;
+                        padding-left: Metrics.gap-3;
+                        padding-right: Metrics.gap-3;
+                        spacing: Metrics.gap-2;
+                        SearchField {
+                            horizontal-stretch: 1;
+                            placeholder: "崩溃日志路径（如 .minecraft/crash-reports/crash-*.txt）";
+                            text <=> PageState.crash-path;
+                        }
+                        MetroButton {
+                            kind: ButtonKind.standard;
+                            text: "导入分析";
+                            button-height: 26px;
+                            enabled: PageState.crash-path != "";
+                            clicked => { PageState.crash-import(PageState.crash-path); }
+                        }
+                    }
+                }
+            }
+
+            Rectangle { height: 1px; background: Theme.stroke; }
+
+            // 崩溃诊断卡片（D8）
+            Rectangle {
+                height: root.has-diagnosis ? 76px : 0px;
+                visible: root.has-diagnosis;
+                background: Theme.state-danger-soft;
+
+                HorizontalLayout {
+                    padding: Metrics.gap-3;
+                    spacing: Metrics.gap-3;
+
+                    AppIcon { kind: IconKind.error; icon-size: 20px; tint: Theme.state-danger; }
+
+                    VerticalLayout {
+                        spacing: 2px;
+                        vertical-stretch: 1;
+
+                        HorizontalLayout {
+                            spacing: Metrics.gap-2;
+                            UiText {
+                                role: TextRole.bodyStrong;
+                                text: root.diagnosis.title;
+                                horizontal-stretch: 1;
+                            }
+                            Badge {
+                                text: "置信度 " + root.diagnosis.confidence + "%";
+                                tint: Theme.state-danger;
+                            }
+                        }
+                        UiText {
+                            role: TextRole.caption;
+                            text: root.diagnosis.hint;
+                            horizontal-stretch: 1;
+                        }
+                    }
+
+                    VerticalLayout {
+                        spacing: Metrics.gap-1;
+                        alignment: center;
+
+                        if root.diagnosis.has_fix : MetroButton {
+                            kind: ButtonKind.standard;
+                            text: "修复建议";
+                            button-height: 26px;
+                            clicked => { root.apply-fix(); }
+                        }
+                        MetroButton {
+                            kind: ButtonKind.subtle;
+                            text: "让 AI 详解";
+                            button-height: 26px;
+                            clicked => { root.ask-ai(root.selected); }
+                        }
+                    }
+                }
+            }
+
+            // 日志流（行虚拟化）
+            Rectangle {
+                vertical-stretch: 1;
+                background: Theme.bg-canvas;
+
+                ListView {
+                    for l in root.lines : LogRow {
+                        line: l;
+                        width: root.width;
+                    }
+                }
+            }
+        }
+    }
+}
diff --git a/crates/app/ui/pages/settings-account.slint b/crates/app/ui/pages/settings-account.slint
new file mode 100644
index 0000000..8e704c7
--- /dev/null
+++ b/crates/app/ui/pages/settings-account.slint
@@ -0,0 +1,201 @@
+// 设置 → 账户（D9 / G6）：三轨账户列表 + 离线添加 + 微软登录（授权码浏览器 / 设备码）+ 删除/切换。
+//
+// 凭据红线：这里能看到的只有「名字 / 轨道 / 公开 UUID / 登录名 / 创建时间」——
+// token 与密码永远不进 UI（Rust 侧的 AccountView 不含这些字段）。
+import { Theme } from "../theme/tokens.slint";
+import { Metrics } from "../theme/metrics.slint";
+import { AccountKind, UiAccount } from "../models.slint";
+import { PageState } from "../page_state.slint";
+import { UiText, TextRole } from "../components/label.slint";
+import { Badge } from "../components/badge.slint";
+import { AppIcon, IconKind } from "../components/icons.slint";
+import { MetroButton, ButtonKind } from "../widgets/button.slint";
+import { SearchField } from "../widgets/inputs.slint";
+import { SettingGroup } from "../widgets/setting-item.slint";
+
+component AccountRow inherits Rectangle {
+    in property <UiAccount> data;
+    callback activate();
+    callback remove();
+
+    height: 56px;
+    background: root.data.active ? Theme.accent-soft : transparent;
+
+    if root.data.active : Rectangle {
+        x: 0;
+        y: 0;
+        width: 3px;
+        height: root.height;
+        background: Theme.accent;
+    }
+
+    HorizontalLayout {
+        padding-left: Metrics.gap-3;
+        padding-right: Metrics.gap-3;
+        spacing: Metrics.gap-2;
+
+        AppIcon {
+            icon-size: 16px;
+            kind: root.data.kind == AccountKind.offline ? IconKind.instances : IconKind.ai;
+            tint: root.data.active ? Theme.accent : Theme.fg-secondary;
+        }
+        VerticalLayout {
+            spacing: 0px;
+            vertical-stretch: 1;
+            UiText { role: TextRole.bodyStrong; text: root.data.name; horizontal-stretch: 1; }
+            UiText {
+                role: TextRole.caption;
+                text: root.data.profile_id + (root.data.login_name == "" ? "" : " · " + root.data.login_name);
+                horizontal-stretch: 1;
+                overflow: elide;
+            }
+        }
+        Badge { text: root.data.kind_label; tint: Theme.fg-secondary; }
+        UiText { role: TextRole.caption; text: root.data.created; width: 108px; }
+        if !root.data.active : MetroButton {
+            kind: ButtonKind.standard;
+            text: "用这个";
+            button-height: 24px;
+            clicked => { root.activate(); }
+        }
+        if root.data.active : Badge { text: "启动中"; tint: Theme.accent; }
+        MetroButton {
+            kind: ButtonKind.subtle;
+            text: "删除";
+            button-height: 24px;
+            clicked => { root.remove(); }
+        }
+    }
+}
+
+export component AccountSection inherits Rectangle {
+    background: transparent;
+
+    VerticalLayout {
+        // 微软登录面板（设备码显示用户码；授权码显示可复制的授权链接；失败显示原因）
+        if PageState.device.visible : Rectangle {
+            height: PageState.device.busy ? 96px : 84px;
+            background: PageState.device.phase_label == "失败" ? Theme.state-danger-soft : Theme.accent-soft;
+
+            VerticalLayout {
+                padding: Metrics.gap-3;
+                spacing: Metrics.gap-1;
+
+                HorizontalLayout {
+                    spacing: Metrics.gap-2;
+                    AppIcon {
+                        icon-size: 16px;
+                        kind: PageState.device.phase_label == "失败" ? IconKind.error : IconKind.ai;
+                        tint: PageState.device.phase_label == "失败" ? Theme.state-danger : Theme.accent;
+                    }
+                    UiText {
+                        role: TextRole.bodyStrong;
+                        text: "微软登录 · " + PageState.device.phase_label;
+                        horizontal-stretch: 1;
+                    }
+                    if PageState.device.busy : MetroButton {
+                        kind: ButtonKind.subtle;
+                        text: "取消";
+                        button-height: 24px;
+                        clicked => { PageState.msa-cancel(); }
+                    }
+                    if !PageState.device.busy : MetroButton {
+                        kind: ButtonKind.subtle;
+                        text: "关闭";
+                        button-height: 24px;
+                        clicked => { PageState.msa-cancel(); }
+                    }
+                }
+
+                if PageState.device.user_code != "" : HorizontalLayout {
+                    spacing: Metrics.gap-3;
+                    UiText {
+                        role: TextRole.title;
+                        text: PageState.device.user_code;
+                        color: Theme.accent;
+                    }
+                    UiText {
+                        role: TextRole.caption;
+                        text: "在浏览器打开 " + PageState.device.verification_uri + " 输入上面的用户码";
+                        horizontal-stretch: 1;
+                        overflow: elide;
+                    }
+                }
+                UiText {
+                    role: TextRole.caption;
+                    text: PageState.device.message;
+                    horizontal-stretch: 1;
+                    wrap: word-wrap;
+                }
+                if PageState.device.qr_link != "" : UiText {
+                    role: TextRole.monoSmall;
+                    text: PageState.device.qr_link;
+                    horizontal-stretch: 1;
+                    overflow: elide;
+                }
+            }
+        }
+
+        // 离线添加表单
+        SettingGroup { title: "添加离线账户"; }
+        HorizontalLayout {
+            padding-left: Metrics.gap-4;
+            padding-right: Metrics.gap-4;
+            spacing: Metrics.gap-2;
+            SearchField {
+                width: 220px;
+                text <=> PageState.offline-name;
+                placeholder: "玩家名（离线 UUID 自动生成）";
+            }
+            MetroButton {
+                kind: ButtonKind.standard;
+                text: "添加离线";
+                button-height: 28px;
+                enabled: PageState.offline-name != "";
+                clicked => { PageState.account-add-offline(PageState.offline-name); }
+            }
+            MetroButton {
+                kind: ButtonKind.accent;
+                text: "微软登录";
+                button-height: 28px;
+                enabled: !PageState.device.busy;
+                clicked => { PageState.msa-browser-begin(); }
+            }
+            MetroButton {
+                kind: ButtonKind.subtle;
+                text: "设备码登录";
+                button-height: 28px;
+                enabled: !PageState.device.busy;
+                clicked => { PageState.msa-begin(); }
+            }
+        }
+
+        // 账户列表
+        SettingGroup { title: "账户（" + PageState.accounts.length + "）"; }
+        if PageState.accounts.length == 0 : Rectangle {
+            height: 72px;
+            VerticalLayout {
+                alignment: center;
+                spacing: 2px;
+                UiText {
+                    role: TextRole.caption;
+                    text: "还没有账户：启动时会用「Player」离线占位。";
+                    horizontal-alignment: center;
+                }
+            }
+        }
+        for account in PageState.accounts : AccountRow {
+            data: account;
+            activate => { PageState.account-switch(account.id); }
+            remove => { PageState.account-remove(account.id); }
+        }
+
+        UiText {
+            role: TextRole.caption;
+            x: Metrics.gap-4;
+            text: "凭据只存在 <数据根>/data/auth/（账号文件与凭据文件分离），界面与 AI 都拿不到 token。";
+            horizontal-stretch: 1;
+            wrap: word-wrap;
+        }
+    }
+}
diff --git a/crates/app/ui/pages/settings-appearance.slint b/crates/app/ui/pages/settings-appearance.slint
new file mode 100644
index 0000000..a7ef123
--- /dev/null
+++ b/crates/app/ui/pages/settings-appearance.slint
@@ -0,0 +1,146 @@
+// 设置页「外观」分组（09 §2 G6 + §113 D17 定案）：主题三态 + 「外观（高级）」P1 四件。
+//
+// 从 pages/settings.slint 拆出来只为守住 400 行门槛；控件语义与设置键一一对应：
+// theme-mode → appearance.theme_mode / bg-* → appearance.bg_image* / panel-alpha →
+// appearance.panel_alpha / glass → appearance.glass / accent-color → appearance.accent_color。
+// 09 §111 硬约束：高级特性全部默认关闭，开启背景图时这里会给出对比度提示（warn 行）。
+import { Theme } from "../theme/tokens.slint";
+import { ThemeMode, BgFillKind } from "../models.slint";
+import { SettingItem, SettingGroup, ControlKind } from "../widgets/setting-item.slint";
+
+export component AppearanceSection inherits VerticalLayout {
+    in-out property <ThemeMode> theme-mode: ThemeMode.auto;
+    in-out property <bool> bg-image-enabled: false;
+    in-out property <string> bg-image: "";
+    in-out property <BgFillKind> bg-fill: BgFillKind.cover;
+    in-out property <float> bg-dim: 0.35;
+    in-out property <float> panel-alpha: 1.0;
+    in-out property <bool> glass: false;
+    in-out property <string> accent-color: "";
+    in property <bool> accent-invalid: false;
+
+    callback theme-changed(ThemeMode);
+    callback bg-image-enabled-changed(bool);
+    callback bg-image-changed(string);
+    callback bg-fill-changed(BgFillKind);
+    callback bg-dim-changed(float);
+    callback panel-alpha-changed(float);
+    callback glass-changed(bool);
+    callback accent-color-changed(string);
+    callback accent-swatch-picked(int);
+
+// ── 外观（D17：主题三态 + 09 §101-104 高级四件）──────
+SettingGroup { title: "主题"; }
+SettingItem {
+    label: "主题模式";
+    description: "跟随系统（Auto，随 OS 热切）/ 浅色 / 深色";
+    kind: ControlKind.segmented;
+    options: ["跟随系统", "浅色", "深色"];
+    selected: root.theme-mode == ThemeMode.auto ? 0
+        : root.theme-mode == ThemeMode.light ? 1 : 2;
+    changed(i) => {
+        root.theme-mode = i == 0 ? ThemeMode.auto
+            : i == 1 ? ThemeMode.light : ThemeMode.dark;
+        root.theme-changed(root.theme-mode);
+    }
+}
+
+SettingGroup {
+    title: "高级特性（出厂全部关闭，开启后请确认前景可读）";
+}
+// ① 自定义窗口背景图（09 §101）
+SettingItem {
+    label: "自定义窗口背景图";
+    description: "PNG 图片铺满窗口；开启后所有面板半透明处都会透出它";
+    kind: ControlKind.toggle;
+    checked: root.bg-image-enabled;
+    toggled(v) => {
+        root.bg-image-enabled = v;
+        root.bg-image-enabled-changed(v);
+    }
+}
+SettingItem {
+    label: "背景图路径";
+    description: root.bg-image == "" ? "尚未选择（绝对路径，例：D:/wall/p.png）" : root.bg-image;
+    kind: ControlKind.text;
+    button-text: "D:/wall/p.png";
+    value <=> root.bg-image;
+    edited(t) => { root.bg-image-changed(t); }
+}
+SettingItem {
+    label: "填充模式";
+    description: "铺满（裁切）/ 完整（留底色）/ 平铺";
+    kind: ControlKind.segmented;
+    options: ["铺满", "完整", "平铺"];
+    selected: root.bg-fill == BgFillKind.cover ? 0
+        : root.bg-fill == BgFillKind.contain ? 1 : 2;
+    changed(i) => {
+        root.bg-fill = i == 0 ? BgFillKind.cover
+            : i == 1 ? BgFillKind.contain : BgFillKind.tile;
+        root.bg-fill-changed(root.bg-fill);
+    }
+}
+SettingItem {
+    label: "暗化层强度";
+    // 09 §111：开启背景图时自动给对比度提示——暗化太低 + 面板太透会伤可读性
+    description: (root.bg-image-enabled && (root.bg-dim < 0.25 || root.panel-alpha < 0.8))
+        ? "⚠ 对比度偏低：建议暗化 ≥ 25% 或面板不透明度 ≥ 80%"
+        : "越大背景越暗、前景越清晰（0% = 不压暗）";
+    warn: root.bg-image-enabled && (root.bg-dim < 0.25 || root.panel-alpha < 0.8);
+    kind: ControlKind.slider;
+    min-value: 0.0;
+    max-value: 0.9;
+    slider-value: root.bg-dim;
+    slid(v) => {
+        root.bg-dim = v;
+        root.bg-dim-changed(v);
+    }
+}
+// ② 全局面板半透明度（09 §102）
+SettingItem {
+    label: "全局面板半透明度";
+    description: "卡片 / 导航 / AI 栏统一透明度（100% = 出厂 Metro 纯色）";
+    kind: ControlKind.slider;
+    min-value: 0.4;
+    max-value: 1.0;
+    slider-value: root.panel-alpha;
+    slid(v) => {
+        root.panel-alpha = v;
+        root.panel-alpha-changed(v);
+    }
+}
+// ③ 玻璃拟态卡片（09 §103）
+SettingItem {
+    label: "玻璃拟态卡片";
+    description: "卡片底铺背景图的预生成模糊层（需先开启背景图）";
+    kind: ControlKind.toggle;
+    checked: root.glass;
+    toggled(v) => {
+        root.glass = v;
+        root.glass-changed(v);
+    }
+}
+// ④ 自定义强调色（09 §104）
+SettingItem {
+    label: "预设强调色";
+    description: root.accent-color == "" ? "当前：出厂 Metro 蓝" : "当前：" + root.accent-color;
+    kind: ControlKind.swatches;
+    swatch-colors: [
+        #0078D4, #0F6CBD, #107C10, #9D5D00,
+        #C42B1C, #8764B8, #C239B3, #00B7C3,
+    ];
+    swatch-current: root.accent-color == "" ? #0078D4 : Theme.accent;
+    swatch-picked(i) => { root.accent-swatch-picked(i); }
+}
+SettingItem {
+    label: "强调色（十六进制）";
+    description: root.accent-invalid
+        ? "⚠ 需要 #RRGGBB 形式，留空恢复出厂蓝"
+        : "留空 = 出厂 #0078D4；影响顶线 / 选中态 / 按钮 / 徽标";
+    warn: root.accent-invalid;
+    kind: ControlKind.text;
+    button-text: "#0078D4";
+    value <=> root.accent-color;
+    edited(t) => { root.accent-color-changed(t); }
+}
+}
diff --git a/crates/app/ui/pages/settings-groups.slint b/crates/app/ui/pages/settings-groups.slint
new file mode 100644
index 0000000..a8f1c25
--- /dev/null
+++ b/crates/app/ui/pages/settings-groups.slint
@@ -0,0 +1,117 @@
+// 设置页右栏的「schema 分组」渲染器：下载 / Java / 数据 / AI / MCP 五组。
+//
+// 行来自 Rust 侧的 `SettingGroupView`（core::setting schema 的键），这里只按控件类型画：
+// 开关 → toggle；分段 → segmented；文本 → text；只读 → 纯文案；动作 → 按钮。
+// 写回一律 `PageState.setting-changed(key, value)` / `setting-action(action)`，
+// 由 host 走 `SettingStore::set`（同源 launcher.json）。
+import { Theme } from "../theme/tokens.slint";
+import { Metrics } from "../theme/metrics.slint";
+import { UiSettingGroup, UiSettingRow, SettingControl } from "../models.slint";
+import { PageState } from "../page_state.slint";
+import { UiText, TextRole } from "../components/label.slint";
+import { SettingItem, SettingGroup, ControlKind } from "../widgets/setting-item.slint";
+
+component RowView inherits Rectangle {
+    in property <UiSettingRow> item;
+    /// 文本编辑的本地缓冲（编辑中不回写模型，失焦/回车才提交）
+    in-out property <string> draft;
+
+    height: root.item.control == SettingControl.readonly ? 48px
+        : root.item.description == "" ? 44px : 58px;
+    background: transparent;
+
+    init => { self.draft = root.item.value_text; }
+    changed item => { self.draft = root.item.value_text; }
+
+    if root.item.control == SettingControl.toggle : SettingItem {
+        label: root.item.label;
+        description: root.item.description;
+        kind: ControlKind.toggle;
+        checked: root.item.flag;
+        toggled(v) => { PageState.setting-changed(root.item.key, v ? "true" : "false"); }
+    }
+
+    if root.item.control == SettingControl.choice : SettingItem {
+        label: root.item.label;
+        description: root.item.description;
+        kind: ControlKind.segmented;
+        options: root.item.options;
+        selected: root.item.selected;
+        changed(i) => {
+            if (i >= 0 && i < root.item.options.length) {
+                PageState.setting-changed(root.item.key, root.item.options[i]);
+            }
+        }
+    }
+
+    if root.item.control == SettingControl.text : SettingItem {
+        label: root.item.label;
+        description: root.item.description;
+        kind: ControlKind.text;
+        value: root.draft;
+        edited(t) => {
+            root.draft = t;
+            PageState.setting-changed(root.item.key, t);
+        }
+    }
+
+    if root.item.control == SettingControl.action : SettingItem {
+        label: root.item.label;
+        description: root.item.description;
+        kind: ControlKind.button;
+        button-text: "执行";
+        clicked => { PageState.setting-action(root.item.action); }
+    }
+
+    if root.item.control == SettingControl.readonly : HorizontalLayout {
+        padding-left: Metrics.gap-4;
+        padding-right: Metrics.gap-4;
+        spacing: Metrics.gap-3;
+
+        UiText {
+            role: TextRole.body;
+            text: root.item.label;
+            width: 200px;
+        }
+        UiText {
+            role: TextRole.caption;
+            text: root.item.description;
+            horizontal-stretch: 1;
+            wrap: word-wrap;
+        }
+    }
+}
+
+export component SettingsGroups inherits Rectangle {
+    in property <string> tab: "";
+
+    background: transparent;
+
+    VerticalLayout {
+        padding-bottom: Metrics.gap-5;
+
+        if PageState.setting-groups.length == 0 : Rectangle {
+            height: 120px;
+            VerticalLayout {
+                alignment: center;
+                spacing: 2px;
+                UiText {
+                    role: TextRole.caption;
+                    text: "设置还没加载出来（host 未就绪或数据根不可写）";
+                    horizontal-alignment: center;
+                }
+            }
+        }
+
+        for group in PageState.setting-groups : Rectangle {
+            visible: group.id == root.tab;
+            height: group.rows.length * 58px + 40px;
+            background: transparent;
+
+            VerticalLayout {
+                SettingGroup { title: group.title; }
+                for setting-row in group.rows : RowView { item: setting-row; }
+            }
+        }
+    }
+}
diff --git a/crates/app/ui/pages/settings.slint b/crates/app/ui/pages/settings.slint
new file mode 100644
index 0000000..d810995
--- /dev/null
+++ b/crates/app/ui/pages/settings.slint
@@ -0,0 +1,280 @@
+// G6 设置页（09 §2 P0·G6）：左子导航 + 右表单 + 搜索框（设置项多，防迷路）。
+// 「通用 / 外观（D17 三态 + 09 §101-104 高级四件，实现在 settings-appearance.slint）/ 数据 / AI /
+// 关于」是真实控件，Java / 账户 / 代理分组仍是入口按钮（等各自 mission 接实现）。
+// 关于页内嵌 AboutSlint —— Slint RF 2.0 许可义务（01c §8：关于页放官方部件）。
+import { Theme } from "../theme/tokens.slint";
+import { Metrics } from "../theme/metrics.slint";
+import { SettingSection, TileSize, ThemeMode, BgFillKind } from "../models.slint";
+import { UiText, TextRole } from "../components/label.slint";
+import { SettingItem, SettingGroup, ControlKind } from "../widgets/setting-item.slint";
+import { AppearanceSection } from "settings-appearance.slint";
+import { AccountSection } from "settings-account.slint";
+import { SettingsGroups } from "settings-groups.slint";
+import { PageState } from "../page_state.slint";
+import { SearchField } from "../widgets/inputs.slint";
+import { AboutSlint, ScrollView } from "std-widgets.slint";
+
+component SectionRow inherits Rectangle {
+    in property <string> label: "";
+    in property <SettingSection> section: SettingSection.general;
+    in property <bool> active: false;
+    callback clicked();
+
+    height: 36px;
+    background: root.active ? Theme.accent-soft : (row-touch.has-hover ? Theme.bg-hover : transparent);
+
+    if root.active : Rectangle {
+        x: 0;
+        y: 0;
+        width: 3px;
+        height: root.height;
+        background: Theme.accent;
+    }
+
+    UiText {
+        x: Metrics.gap-3;
+        y: 0;
+        width: root.width - Metrics.gap-3 - Metrics.gap-2;
+        height: root.height;
+        role: TextRole.body;
+        text: root.label;
+        color: root.active ? Theme.accent : Theme.fg-primary;
+    }
+
+    row-touch := TouchArea {
+        mouse-cursor: pointer;
+        clicked => { root.clicked(); }
+    }
+}
+
+export component SettingsPage inherits Rectangle {
+    in-out property <SettingSection> section: SettingSection.general;
+    in-out property <string> query: "";
+
+    // 外观（D17：主题三态 + 09 §101-104 高级特性四件）
+    in-out property <ThemeMode> theme-mode: ThemeMode.auto;
+    in-out property <bool> bg-image-enabled: false;
+    in-out property <string> bg-image: "";
+    in-out property <BgFillKind> bg-fill: BgFillKind.cover;
+    in-out property <float> bg-dim: 0.35;
+    in-out property <float> panel-alpha: 1.0;
+    in-out property <bool> glass: false;
+    in-out property <string> accent-color: "";
+    in property <bool> accent-invalid: false;
+    // 通用
+    in-out property <TileSize> tile-size: TileSize.medium;
+    in-out property <bool> close-to-tray: true;
+
+    // 数据
+    in-out property <int> data-mode: 0;
+    in property <string> data-path: "";
+    // 下载
+    in-out property <int> download-concurrency: 1;
+    in property <string> region-label: "未知";
+    // 账户
+    in property <string> account-label: "未登录";
+    // AI
+    in-out property <int> ai-endpoint: 0;
+    in-out property <bool> yolo: false;
+    in-out property <bool> mcp-enabled: false;
+    // 代理
+    in-out property <string> proxy: "";
+    // 关于
+    in property <string> version: "";
+
+    callback section-changed(SettingSection);
+    callback query-changed(string);
+    callback theme-changed(ThemeMode);
+    callback bg-image-enabled-changed(bool);
+    callback bg-image-changed(string);
+    callback bg-fill-changed(BgFillKind);
+    callback bg-dim-changed(float);
+    callback panel-alpha-changed(float);
+    callback glass-changed(bool);
+    callback accent-color-changed(string);
+    callback accent-swatch-picked(int);
+    callback tile-size-changed(TileSize);
+    callback close-to-tray-changed(bool);
+    callback data-mode-changed(int);
+    callback download-concurrency-changed(int);
+    callback ai-endpoint-changed(int);
+    callback yolo-changed(bool);
+    callback mcp-changed(bool);
+    callback proxy-changed(string);
+    callback migrate-data();
+    callback login();
+    callback manage-java();
+    callback open-audit-log();
+    callback detect-region();
+
+    background: Theme.bg-canvas;
+
+    HorizontalLayout {
+        // ── 左子导航 ──────────────────────────────────────────────
+        Rectangle {
+            width: 200px;
+            background: Theme.bg-surface;
+
+            VerticalLayout {
+                padding-top: Metrics.gap-2;
+
+                SectionRow { label: "通用"; section: SettingSection.general; active: root.section == SettingSection.general; clicked => { root.section-changed(SettingSection.general); } }
+                SectionRow { label: "外观"; section: SettingSection.appearance; active: root.section == SettingSection.appearance; clicked => { root.section-changed(SettingSection.appearance); } }
+                SectionRow { label: "数据"; section: SettingSection.data; active: root.section == SettingSection.data; clicked => { root.section-changed(SettingSection.data); } }
+                SectionRow { label: "下载"; section: SettingSection.download; active: root.section == SettingSection.download; clicked => { root.section-changed(SettingSection.download); } }
+                SectionRow { label: "Java"; section: SettingSection.java; active: root.section == SettingSection.java; clicked => { root.section-changed(SettingSection.java); } }
+                SectionRow { label: "账户"; section: SettingSection.account; active: root.section == SettingSection.account; clicked => { root.section-changed(SettingSection.account); } }
+                SectionRow { label: "AI"; section: SettingSection.ai; active: root.section == SettingSection.ai; clicked => { root.section-changed(SettingSection.ai); } }
+                SectionRow { label: "代理"; section: SettingSection.proxy; active: root.section == SettingSection.proxy; clicked => { root.section-changed(SettingSection.proxy); } }
+                SectionRow { label: "关于"; section: SettingSection.about; active: root.section == SettingSection.about; clicked => { root.section-changed(SettingSection.about); } }
+
+                Rectangle { vertical-stretch: 1; background: transparent; }
+            }
+        }
+
+        Rectangle { width: 1px; background: Theme.stroke; }
+
+        // ── 右表单 ────────────────────────────────────────────────
+        VerticalLayout {
+            vertical-stretch: 1;
+
+            Rectangle {
+                height: Metrics.page-header-height;
+                background: Theme.bg-surface;
+
+                HorizontalLayout {
+                    padding-left: Metrics.gap-4;
+                    padding-right: Metrics.gap-4;
+                    spacing: Metrics.gap-3;
+
+                    UiText {
+                        role: TextRole.subtitle;
+                        text: "设置";
+                        width: 72px;
+                    }
+                    SearchField {
+                        width: 240px;
+                        placeholder: "搜索设置项";
+                        text <=> root.query;
+                        edited(t) => { root.query-changed(t); }
+                    }
+                    Rectangle { horizontal-stretch: 1; background: transparent; }
+                }
+            }
+
+            Rectangle { height: 1px; background: Theme.stroke; }
+
+            ScrollView {
+                vertical-stretch: 1;
+
+                VerticalLayout {
+                    padding-bottom: Metrics.gap-5;
+
+                    // 外观（D17：主题三态 + 09 §101-104 高级四件；实现在 settings-appearance.slint）
+                    if root.section == SettingSection.appearance : AppearanceSection {
+                        theme-mode: root.theme-mode;
+                        bg-image-enabled: root.bg-image-enabled;
+                        bg-image: root.bg-image;
+                        bg-fill: root.bg-fill;
+                        bg-dim: root.bg-dim;
+                        panel-alpha: root.panel-alpha;
+                        glass: root.glass;
+                        accent-color: root.accent-color;
+                        accent-invalid: root.accent-invalid;
+                        theme-changed(m) => {
+                            root.theme-mode = m;
+                            root.theme-changed(m);
+                        }
+                        bg-image-enabled-changed(v) => {
+                            root.bg-image-enabled = v;
+                            root.bg-image-enabled-changed(v);
+                        }
+                        bg-image-changed(t) => {
+                            root.bg-image = t;
+                            root.bg-image-changed(t);
+                        }
+                        bg-fill-changed(f) => {
+                            root.bg-fill = f;
+                            root.bg-fill-changed(f);
+                        }
+                        bg-dim-changed(v) => {
+                            root.bg-dim = v;
+                            root.bg-dim-changed(v);
+                        }
+                        panel-alpha-changed(v) => {
+                            root.panel-alpha = v;
+                            root.panel-alpha-changed(v);
+                        }
+                        glass-changed(v) => {
+                            root.glass = v;
+                            root.glass-changed(v);
+                        }
+                        accent-color-changed(t) => {
+                            root.accent-color = t;
+                            root.accent-color-changed(t);
+                        }
+                        accent-swatch-picked(i) => { root.accent-swatch-picked(i); }
+                    }
+
+                    // ── 通用 ────────────────────────────────────────
+                    if root.section == SettingSection.general : SettingGroup { title: "外观"; }
+                    if root.section == SettingSection.general : SettingItem {
+                        label: "磁贴尺寸";
+                        description: "小 6 列 / 中 4 列（默认）/ 大 3 列";
+                        kind: ControlKind.segmented;
+                        options: ["小", "中", "大"];
+                        selected: root.tile-size == TileSize.small ? 0
+                            : root.tile-size == TileSize.large ? 2 : 1;
+                        changed(i) => {
+                            root.tile-size-changed(
+                                i == 0 ? TileSize.small : i == 2 ? TileSize.large : TileSize.medium);
+                        }
+                    }
+                    if root.section == SettingSection.general : SettingItem {
+                        label: "关闭窗口时最小化到托盘";
+                        description: "避免误关正在运行的游戏";
+                        kind: ControlKind.toggle;
+                        checked: root.close-to-tray;
+                        toggled(v) => { root.close-to-tray-changed(v); }
+                    }
+
+                    // ── 数据 / 下载 / Java / 账户 / AI / MCP ────────────
+                    // 行来自 core::setting schema（`PageState.setting-groups`），写回走
+                    // `SettingStore::set`——与 `ull config set` / AI `set_config` 同一份 launcher.json。
+                    if root.section == SettingSection.data : SettingsGroups { tab: "data"; }
+                    if root.section == SettingSection.download : SettingsGroups { tab: "download"; }
+                    if root.section == SettingSection.java : SettingsGroups { tab: "java"; }
+                    if root.section == SettingSection.ai : SettingsGroups { tab: "ai"; }
+                    if root.section == SettingSection.ai : SettingsGroups { tab: "mcp"; }
+                    if root.section == SettingSection.account : AccountSection { }
+
+                    // ── 代理 ────────────────────────────────────────
+                    if root.section == SettingSection.proxy : SettingGroup { title: "代理"; }
+                    if root.section == SettingSection.proxy : SettingItem {
+                        label: "HTTP 代理";
+                        description: "留空则使用系统代理";
+                        kind: ControlKind.text;
+                        button-text: "http://127.0.0.1:7890";
+                        value <=> root.proxy;
+                        edited(t) => { root.proxy-changed(t); }
+                    }
+
+                    // ── 关于 ────────────────────────────────────────
+                    if root.section == SettingSection.about : SettingGroup { title: "关于"; }
+                    if root.section == SettingSection.about : SettingItem {
+                        label: "版本";
+                        description: root.version;
+                    }
+                    if root.section == SettingSection.about : SettingItem {
+                        label: "许可";
+                        description: "Apache-2.0（Slint 走 RF 2.0 轨道）";
+                    }
+                    if root.section == SettingSection.about : Rectangle {
+                        height: 120px;
+                        AboutSlint { }
+                    }
+                }
+            }
+        }
+    }
+}
diff --git a/crates/app/ui/shell.slint b/crates/app/ui/shell.slint
new file mode 100644
index 0000000..65770b7
--- /dev/null
+++ b/crates/app/ui/shell.slint
@@ -0,0 +1,387 @@
+// 主窗口框架（D16 §1）：无边框标题栏 + 左侧可折叠导航 + 内容区路由 + 右侧 AI 常驻栏 + 对话框/Toast 覆盖层。
+// 这里只做「组装 + 路由转发」，状态全在 Rust 侧（state.rs），Slint 不持有业务真相。
+// main.slint（阶段 B 接线）只负责实例化 AppShell 并把 Window 的窗口事件接上。
+import { Theme } from "theme/tokens.slint";
+import { Metrics } from "theme/metrics.slint";
+import {
+    RouteKind, TileSize, InstanceView, SettingSection, DownloadCategory, ThemeMode, BgFillKind,
+    UiTile, UiVersion, UiLogSession, UiLogLine, UiDiagnosis, UiChatMessage, UiDialog, UiToast,
+} from "models.slint";
+import { PageState } from "page_state.slint";
+import { NewInstanceWizard } from "widgets/wizard.slint";
+import { TitleBar } from "components/titlebar.slint";
+import { Nav } from "components/nav.slint";
+import { AiPanel } from "components/ai-panel.slint";
+import { UiText, TextRole } from "components/label.slint";
+import { MetroButton, ButtonKind } from "widgets/button.slint";
+import { DialogHost } from "widgets/dialog.slint";
+import { ToastHost } from "widgets/toast.slint";
+import { NoticeBar } from "components/notice-bar.slint";
+import { InstancesPage } from "pages/instances.slint";
+import { DownloadPage } from "pages/download.slint";
+import { LogsPage } from "pages/logs.slint";
+import { SettingsPage } from "pages/settings.slint";
+
+
+export component AppShell inherits Rectangle {
+    // ── 窗口 ────────────────────────────────────────────────────
+    in property <string> app-title: "Unlucky Launcher";
+    in property <bool> maximized: false;
+
+    // ── 路由 ────────────────────────────────────────────────────
+    in property <RouteKind> route: RouteKind.instances;
+
+    // ── 导航 / 账户 ──────────────────────────────────────────────
+    in property <bool> nav-collapsed: false;
+    in property <string> account-name: "未登录";
+    in property <string> account-initial: "?";
+    in property <color> account-hue: #5C2D91;
+
+    // ── AI 栏（双形态共享同一份会话）──────────────────────────────
+    in property <bool> ai-collapsed: false;
+    in property <[UiChatMessage]> ai-messages;
+    in property <bool> ai-streaming: false;
+    in property <bool> yolo: false;
+    in property <string> ai-endpoint-label: "llama.cpp · 本地";
+    in-out property <string> ai-draft: "";
+
+    // ── 页面数据 ────────────────────────────────────────────────
+    in property <[UiTile]> tiles;
+    in property <[UiTile]> running-tiles;
+    in property <[UiVersion]> versions;
+    in property <[UiLogSession]> log-sessions;
+    in property <[UiLogLine]> log-lines;
+    in property <UiDiagnosis> diagnosis;
+    in property <bool> has-diagnosis: false;
+    in property <string> selected-session: "";
+
+    // ── 偏好（持久化键见 SubAgentsTalk/app-DTO通道约定.md）──────────
+    in-out property <TileSize> tile-size: TileSize.medium;
+    in-out property <InstanceView> instance-view: InstanceView.tiles;
+    in-out property <string> instance-query: "";
+    in-out property <SettingSection> settings-section: SettingSection.general;
+    /// D17 主题三态（auto 跟随系统；light/dark 钉死）。Rust 侧同时写 Theme 全局。
+    in-out property <ThemeMode> theme-mode: ThemeMode.auto;
+    /// 外观（高级）四件的 in-out 通道：MainWindow ↔ SettingsPage（图片本身走 `Theme.bg-image`）
+    in-out property <bool> bg-image-enabled: false;
+    in-out property <string> bg-image: "";
+    in-out property <BgFillKind> bg-fill: BgFillKind.cover;
+    in-out property <float> bg-dim: 0.35;
+    in-out property <float> panel-alpha: 1.0;
+    in-out property <bool> glass: false;
+    /// 设置页编辑的十六进制串（`accent-color` 是解析后的颜色，只给 Theme 用）
+    in-out property <string> accent-hex: "";
+    /// 强调色输入是否非法（设置页亮 warn 行）
+    in-out property <bool> accent-invalid: false;
+    in-out property <DownloadCategory> download-category: DownloadCategory.release;
+    in-out property <bool> download-installed-only: false;
+    /// 下载页版本号筛选词（输入由页面写回，state.download_query 参与过滤）
+    in-out property <string> download-query: "";
+
+    // ── 对话框队列 / Toast ───────────────────────────────────────
+    in property <UiDialog> dialog;
+    in property <bool> dialog-open: false;
+    in property <int> dialog-queued: 0;
+    in property <[UiToast]> toasts;
+
+    // ── 窗口控制（拖拽走 WindowMoveArea，不需要 Rust 参与）────────
+    callback toggle-maximize();
+    callback minimize();
+    callback request-close();
+
+    // ── 导航 / AI ───────────────────────────────────────────────
+    callback navigate(RouteKind);
+    callback toggle-nav();
+    callback toggle-ai();
+    callback expand-ai();
+    callback dock-ai();
+    callback toggle-yolo();
+    callback ai-send(string);
+    callback ai-stop();
+
+    // ── 实例页 ──────────────────────────────────────────────────
+    callback instance-launch(string);
+    callback instance-configure(string);
+    callback instance-stop(string);
+    callback instance-open(string);
+    callback new-instance();
+    callback instance-view-changed(InstanceView);
+    callback tile-size-changed(TileSize);
+    callback instance-query-changed(string);
+
+    // ── 下载页 ──────────────────────────────────────────────────
+    callback download-category-changed(DownloadCategory);
+    callback download-install(string);
+    callback installed-only-changed(bool);
+    callback download-query-changed(string);
+    callback ancient-help();
+
+    // ── 日志页 ──────────────────────────────────────────────────
+    callback log-select(string);
+    callback log-ask-ai(string);
+    callback log-apply-fix();
+
+    // ── 设置页 ──────────────────────────────────────────────────
+    callback settings-section-changed(SettingSection);
+    callback theme-changed(ThemeMode);
+    callback bg-image-enabled-changed(bool);
+    callback bg-image-changed(string);
+    callback bg-fill-changed(BgFillKind);
+    callback bg-dim-changed(float);
+    callback panel-alpha-changed(float);
+    callback glass-changed(bool);
+    callback accent-color-changed(string);
+    callback accent-swatch-picked(int);
+    callback yolo-changed(bool);
+    callback mcp-changed(bool);
+    callback ai-endpoint-changed(int);
+
+    // ── 对话框 / Toast ──────────────────────────────────────────
+    callback dialog-primary();
+    callback dialog-secondary();
+    callback dialog-dismissed();
+    callback toast-dismissed(string);
+
+    // 窗口底色交给 main.slint 的 Window（不透明 `canvas-solid`），这里只铺背景图层
+    background: transparent;
+
+    // 玻璃拟态的对齐基准：整窗逻辑尺寸（components/glass.slint 反向偏移用）
+    init => {
+        Theme.window-width = root.width;
+        Theme.window-height = root.height;
+    }
+    changed width => { Theme.window-width = root.width; }
+    changed height => { Theme.window-height = root.height; }
+
+    // ── ① 自定义窗口背景图（09 §101）────────────────────────────
+    // 只在「开关打开且图片已加载」时才画：空 image 的 width 为 0，出厂态零开销。
+    if Theme.bg-image.width > 0 : Rectangle {
+        x: 0;
+        y: 0;
+        width: root.width;
+        height: root.height;
+        clip: true;
+        background: Theme.canvas-solid;
+
+        Image {
+            source: Theme.bg-image;
+            x: 0;
+            y: 0;
+            width: parent.width;
+            height: parent.height;
+            // tile 模式由 Rust 预平铺成整窗画布，故这里等同 cover
+            image-fit: root.bg-fill == BgFillKind.contain ? contain : cover;
+        }
+    }
+
+    // ── ② 暗化层（09 §111：保证前景可读；0 = 不压暗）─────────────
+    if Theme.bg-image.width > 0 && Theme.bg-dim > 0 : Rectangle {
+        x: 0;
+        y: 0;
+        width: root.width;
+        height: root.height;
+        background: rgba(0, 0, 0, Theme.bg-dim);
+    }
+
+    VerticalLayout {
+        TitleBar {
+            title: root.app-title;
+            subtitle: "P0 骨架 · Metro";
+            maximized: root.maximized;
+            toggle-maximize => { root.toggle-maximize(); }
+            minimize => { root.minimize(); }
+            request-close => { root.request-close(); }
+        }
+
+        NoticeBar {
+            notices: PageState.notices;
+        }
+
+        HorizontalLayout {
+            // 左侧主导航
+            Nav {
+                active: root.route;
+                collapsed: root.nav-collapsed;
+                account-name: root.account-name;
+                account-initial: root.account-initial;
+                account-hue: root.account-hue;
+                navigate(r) => { root.navigate(r); }
+                toggle-collapsed => { root.toggle-nav(); }
+                account-clicked => { root.navigate(RouteKind.settings); root.settings-section-changed(SettingSection.account); }
+            }
+
+            // 内容区（每页独立滚动，路由切换栈语义在 Rust Router）
+            Rectangle {
+                horizontal-stretch: 1;
+                background: Theme.bg-canvas;
+
+                if root.route == RouteKind.instances : InstancesPage {
+                    tiles: root.tiles;
+                    running: root.running-tiles;
+                    view: root.instance-view;
+                    tile-size: root.tile-size;
+                    query: root.instance-query;
+                    launch(id) => { root.instance-launch(id); }
+                    configure(id) => { root.instance-configure(id); }
+                    stop(id) => { root.instance-stop(id); }
+                    open(id) => { root.instance-open(id); }
+                    new-instance => { root.new-instance(); }
+                    view-changed(v) => {
+                        root.instance-view = v;
+                        root.instance-view-changed(v);
+                    }
+                    tile-size-changed(s) => {
+                        root.tile-size = s;
+                        root.tile-size-changed(s);
+                    }
+                    query-changed(q) => { root.instance-query-changed(q); }
+                }
+
+                if root.route == RouteKind.download : DownloadPage {
+                    versions: root.versions;
+                    category: root.download-category;
+                    installed-only: root.download-installed-only;
+                    query: root.download-query;
+                    install(id) => { root.download-install(id); }
+                    query-changed(q) => {
+                        root.download-query = q;
+                        root.download-query-changed(q);
+                    }
+                    ancient-help => { root.ancient-help(); }
+                    category-changed(c) => {
+                        root.download-category = c;
+                        root.download-category-changed(c);
+                    }
+                    installed-only-changed(v) => {
+                        root.download-installed-only = v;
+                        root.installed-only-changed(v);
+                    }
+                }
+
+                if root.route == RouteKind.logs : LogsPage {
+                    sessions: root.log-sessions;
+                    lines: root.log-lines;
+                    diagnosis: root.diagnosis;
+                    has-diagnosis: root.has-diagnosis;
+                    selected: root.selected-session;
+                    select(id) => { root.log-select(id); }
+                    ask-ai(id) => { root.log-ask-ai(id); }
+                    apply-fix => { root.log-apply-fix(); }
+                    refresh => { PageState.logs-refresh(); }
+                }
+
+                if root.route == RouteKind.settings : SettingsPage {
+                    section: root.settings-section;
+                    theme-mode: root.theme-mode;
+                    bg-image-enabled: root.bg-image-enabled;
+                    bg-image: root.bg-image;
+                    bg-fill: root.bg-fill;
+                    bg-dim: root.bg-dim;
+                    panel-alpha: root.panel-alpha;
+                    glass: root.glass;
+                    accent-color: root.accent-hex;
+                    accent-invalid: root.accent-invalid;
+                    section-changed(s) => {
+                        root.settings-section = s;
+                        root.settings-section-changed(s);
+                    }
+                    theme-changed(mode) => {
+                        root.theme-mode = mode;
+                        root.theme-changed(mode);
+                    }
+                    bg-image-enabled-changed(v) => { root.bg-image-enabled-changed(v); }
+                    bg-image-changed(path) => { root.bg-image-changed(path); }
+                    bg-fill-changed(fill) => { root.bg-fill-changed(fill); }
+                    bg-dim-changed(v) => { root.bg-dim-changed(v); }
+                    panel-alpha-changed(v) => { root.panel-alpha-changed(v); }
+                    glass-changed(v) => { root.glass-changed(v); }
+                    accent-color-changed(text) => {
+                        root.accent-hex = text;
+                        root.accent-color-changed(text);
+                    }
+                    accent-swatch-picked(index) => { root.accent-swatch-picked(index); }
+                    yolo-changed(v) => { root.yolo-changed(v); }
+                    mcp-changed(v) => { root.mcp-changed(v); }
+                    ai-endpoint-changed(i) => { root.ai-endpoint-changed(i); }
+                }
+
+                // AI 拆成独立全宽页：与右侧栏共用同一份 ai-messages（切换无损）
+                if root.route == RouteKind.agent : AiPanel {
+                    docked: false;
+                    messages: root.ai-messages;
+                    collapsed: false;
+                    yolo: root.yolo;
+                    streaming: root.ai-streaming;
+                    endpoint-label: root.ai-endpoint-label;
+                    draft <=> root.ai-draft;
+                    dock => { root.dock-ai(); }
+                    toggle-yolo => { root.toggle-yolo(); }
+                    send(t) => { root.ai-send(t); }
+                    stop => { root.ai-stop(); }
+                }
+
+                // 实例详情 G4：P0 只留占位（点击磁贴进入）
+                if root.route == RouteKind.detail : VerticalLayout {
+                    alignment: center;
+                    spacing: Metrics.gap-3;
+
+                    UiText {
+                        role: TextRole.title;
+                        text: "实例详情（G4）";
+                        horizontal-alignment: center;
+                    }
+                    UiText {
+                        role: TextRole.caption;
+                        text: "P0 骨架未实现：概要与设置 tab 在 G4 补齐";
+                        horizontal-alignment: center;
+                    }
+                    HorizontalLayout {
+                        alignment: center;
+                        MetroButton {
+                            kind: ButtonKind.standard;
+                            text: "返回实例页";
+                            clicked => { root.navigate(RouteKind.instances); }
+                        }
+                    }
+                }
+            }
+
+            // 右侧 AI 常驻栏（拆成独立页时让位给内容区）
+            AiPanel {
+                visible: root.route != RouteKind.agent;
+                docked: true;
+                collapsed: root.ai-collapsed;
+                messages: root.ai-messages;
+                yolo: root.yolo;
+                streaming: root.ai-streaming;
+                endpoint-label: root.ai-endpoint-label;
+                draft <=> root.ai-draft;
+                toggle-collapsed => { root.toggle-ai(); }
+                expand => { root.expand-ai(); }
+                toggle-yolo => { root.toggle-yolo(); }
+                send(t) => { root.ai-send(t); }
+                stop => { root.ai-stop(); }
+            }
+        }
+    }
+
+    // 新建实例向导（全屏模态；数据来自 PageState）
+    NewInstanceWizard {
+        versions: root.versions;
+    }
+
+    // 覆盖层：模态队列（一次一条）+ 右下 Toast
+    DialogHost {
+        current: root.dialog;
+        open: root.dialog-open;
+        queued: root.dialog-queued;
+        primary => { root.dialog-primary(); }
+        secondary => { root.dialog-secondary(); }
+        dismissed => { root.dialog-dismissed(); }
+    }
+
+    ToastHost {
+        toasts: root.toasts;
+        dismissed(id) => { root.toast-dismissed(id); }
+    }
+}
diff --git a/crates/app/ui/theme/metrics.slint b/crates/app/ui/theme/metrics.slint
new file mode 100644
index 0000000..c0483fa
--- /dev/null
+++ b/crates/app/ui/theme/metrics.slint
@@ -0,0 +1,48 @@
+// 布局度量令牌（D16 定稿的尺寸口径集中在此）：
+// 导航栏折叠宽度、AI 栏宽度、标题栏高度、磁贴三档尺寸与列数。
+import { TileSize } from "../models.slint";
+
+export global Metrics {
+    // 间距刻度（4 的倍数，Metro 栅格）
+    out property <length> gap-1: 4px;
+    out property <length> gap-2: 8px;
+    out property <length> gap-3: 12px;
+    out property <length> gap-4: 16px;
+    out property <length> gap-5: 24px;
+    out property <length> gap-6: 32px;
+
+    out property <length> radius-sm: 2px;
+    out property <length> radius-md: 4px;
+    out property <length> radius-lg: 8px;
+
+    // 主窗口骨架
+    out property <length> titlebar-height: 40px;
+    out property <length> titlebar-button-width: 46px;
+    out property <length> accent-line: 2px;
+    out property <length> nav-expanded-width: 88px;
+    out property <length> nav-collapsed-width: 48px;
+    out property <length> ai-panel-width: 320px;
+    out property <length> ai-rail-width: 44px;
+    out property <length> page-header-height: 56px;
+    out property <length> running-strip-height: 32px;
+    out property <length> row-height: 44px;
+    out property <length> control-height: 32px;
+    out property <length> touch-target: 32px;
+
+    // 磁贴三档（Q24-3：默认中磁贴 4 列，设置可调小 6 / 大 3）
+    in-out property <TileSize> tile-size: TileSize.medium;
+    out property <int> tile-columns:
+        tile-size == TileSize.small ? 6
+        : tile-size == TileSize.large ? 3
+        : 4;
+    out property <length> tile-height:
+        tile-size == TileSize.small ? 104px
+        : tile-size == TileSize.large ? 176px
+        : 136px;
+    out property <length> tile-icon-size:
+        tile-size == TileSize.small ? 32px
+        : tile-size == TileSize.large ? 56px
+        : 44px;
+    // 小磁贴只留图标+名字+启动键，藏起徽标与最后游玩时间（空间不足）
+    out property <bool> tile-compact: tile-size == TileSize.small;
+}
diff --git a/crates/app/ui/theme/tokens.slint b/crates/app/ui/theme/tokens.slint
new file mode 100644
index 0000000..1314af1
--- /dev/null
+++ b/crates/app/ui/theme/tokens.slint
@@ -0,0 +1,208 @@
+// Metro 主题令牌（D14 + D17 主题三态 + 09 §101-104「外观（高级）」）：palette + 排版层级 + 字体栈 +
+// 动效时长 + 外观令牌（背景图 / 面板半透明度 / 玻璃拟态 / 强调色）。
+//
+// 结构约定：
+// - `LightPalette` / `DarkPalette` = 两套完整色板（**不是**一套加条件），换肤只改这两处。
+// - `Theme` = 解析器：按主题三态（auto/light/dark）挑一套，并持有**共享**的 accent 与字体/排版。
+// - auto 跟随系统：`Theme.system-theme` 由 Rust 的 `core::platform::theme_probe` 灌入（启动对齐 +
+//   未知时兜底轮询），后端支持时另有 `Palette.color-scheme` 实时热切；两者都不认识就按浅色。
+// - 「外观（高级）」四件全部默认关闭：`panel-alpha` 1.0 / `glass` false / `bg-image` 空 /
+//   `accent-override` 透明——出厂观感与 M17 骨架逐像素一致（09 §111 硬约束）。
+// - 组件只准用 `Theme.*`，不得出现裸色字面量（背景图暗化层是唯一例外，它是「遮罩」而非配色）。
+
+import { ThemeMode } from "../models.slint";
+import { Palette } from "std-widgets.slint";
+
+// ── 亮色色板 ────────────────────────────────────────────────────
+export global LightPalette {
+    out property <color> bg-canvas: #F3F3F3;
+    out property <color> bg-surface: #FFFFFF;
+    out property <color> bg-elevated: #FFFFFF;
+    out property <color> bg-titlebar: #EDEDED;
+    out property <color> bg-hover: #E9E9E9;
+    out property <color> bg-pressed: #DEDEDE;
+    out property <color> bg-input: #FFFFFF;
+
+    out property <color> fg-primary: #1A1A1A;
+    out property <color> fg-secondary: #5F5F5F;
+    out property <color> fg-disabled: #9A9A9A;
+
+    out property <color> stroke: #E1E1E1;
+    out property <color> stroke-strong: #C8C8C8;
+    out property <color> shadow: #00000026;
+    out property <color> scrim: #00000099;
+
+    out property <color> accent-soft: #E5F1FB;
+    out property <color> accent-hover: #106EBE;
+    out property <color> accent-pressed: #005A9E;
+
+    out property <color> state-success: #107C10;
+    out property <color> state-success-soft: #DFF6DD;
+    out property <color> state-warn: #9D5D00;
+    out property <color> state-warn-soft: #FFF4CE;
+    out property <color> state-danger: #C42B1C;
+    out property <color> state-danger-hover: #A82214;
+    out property <color> state-danger-soft: #FDE7E9;
+    out property <color> state-info-soft: #E7F1FA;
+}
+
+// ── 暗色色板 ────────────────────────────────────────────────────
+export global DarkPalette {
+    out property <color> bg-canvas: #1B1B1B;
+    out property <color> bg-surface: #232323;
+    out property <color> bg-elevated: #2B2B2B;
+    out property <color> bg-titlebar: #161616;
+    out property <color> bg-hover: #2F2F2F;
+    out property <color> bg-pressed: #383838;
+    out property <color> bg-input: #1E1E1E;
+
+    out property <color> fg-primary: #F2F2F2;
+    out property <color> fg-secondary: #A6A6A6;
+    out property <color> fg-disabled: #6B6B6B;
+
+    out property <color> stroke: #3A3A3A;
+    out property <color> stroke-strong: #4A4A4A;
+    out property <color> shadow: #000000CC;
+    out property <color> scrim: #00000099;
+
+    out property <color> accent-soft: #0F2A3F;
+    out property <color> accent-hover: #2B8FE0;
+    out property <color> accent-pressed: #005A9E;
+
+    out property <color> state-success: #4CCB4C;
+    out property <color> state-success-soft: #16321A;
+    out property <color> state-warn: #FFD24C;
+    out property <color> state-warn-soft: #3A2E0F;
+    out property <color> state-danger: #FF6B6B;
+    out property <color> state-danger-hover: #FF8A8A;
+    out property <color> state-danger-soft: #3A1A1A;
+    out property <color> state-info-soft: #10263A;
+}
+
+// ── 解析器 ──────────────────────────────────────────────────────
+export global Theme {
+    // ── 主题三态（D17 设置页「外观」分组，出厂 auto）──────────────────
+    // D17 主题三态（设置页「外观」分组，出厂 auto）
+    in-out property <ThemeMode> theme-mode: ThemeMode.auto;
+    // 系统主题来源（M41）：0 = 未知（此时回落到 Slint 后端 `Palette.color-scheme`），
+    // 1 = 浅色 / 2 = 深色。由 Rust 的 `core::platform::theme_probe` 探测后灌入：
+    // 启动时给首帧对齐，之后按需轮询兜底（后端不支持系统主题时 auto 仍可用）。
+    in-out property <int> system-theme: 0;
+    // 后端是否认得系统主题（`unknown` 表示不支持/无 portal）。
+    out property <bool> system-theme-known: Palette.color-scheme != ColorScheme.unknown;
+    // 是否深色：显式钉死（light/dark）优先；auto 时用探测值，探测未知才问后端。
+    out property <bool> dark: theme-mode == ThemeMode.dark
+        || (theme-mode == ThemeMode.auto
+            && (system-theme == 2
+                || (system-theme != 1 && Palette.color-scheme == ColorScheme.dark)));
+
+    // ── 外观（高级）令牌（09 §101-104 / §111：出厂全部关闭）─────────
+    // 全局面板半透明度：`bg-*` 令牌统一按 `panel-alpha` 重建（见下方「面板底色」段），
+    // 组件侧零改动即透出背景图。出厂 1.0 = 完全不透明，Metro 纯色外观与 M17 骨架一致。
+    in-out property <float> panel-alpha: 1.0;
+    // 自定义窗口背景图（空 image = 纯色背景，出厂态）。
+    in-out property <image> bg-image;
+    // 背景图暗化层强度（0~0.95，越大前景越清晰）。Rust 侧夹到 schema 范围。
+    in-out property <float> bg-dim: 0.35;
+    // 玻璃拟态：预生成模糊层（Rust 侧降采样 + box blur），卡片内按 `absolute-position`
+    // 反向偏移对齐整窗，得到 Slint 版「毛玻璃」（无 backdrop-filter 的替代手法）。
+    in-out property <bool> glass: false;
+    in-out property <image> bg-blur;
+    // 玻璃层对齐用的窗口逻辑尺寸（AppShell 在 init/changed 里灌入）。
+    in-out property <length> window-width: 1180px;
+    in-out property <length> window-height: 760px;
+
+    // ── 强调色（accent 令牌全域生效；两套色板共享）──────────────────
+    // `accent-override` 的 alpha == 0 表示「未自定义」，走 D14 出厂 Metro 蓝。
+    // （color 的 `.alpha` 字段是 0~255 整数，不是 0~1 浮点。）
+    in-out property <color> accent-override: transparent;
+    out property <bool> accent-custom: accent-override.alpha > 1;
+    out property <color> accent: accent-custom ? accent-override : #0078D4;
+    // 自定义时由覆盖色派生 hover/pressed/soft（未自定义仍走双色板常量，出场观感不变）。
+    out property <color> accent-hover: accent-custom
+        ? (dark ? accent.brighter(0.18) : accent.darker(0.12))
+        : (dark ? DarkPalette.accent-hover : LightPalette.accent-hover);
+    out property <color> accent-pressed: accent-custom
+        ? (dark ? accent.brighter(0.28) : accent.darker(0.24))
+        : (dark ? DarkPalette.accent-pressed : LightPalette.accent-pressed);
+    out property <color> accent-soft: accent-custom
+        ? accent.mix(surface-solid, 0.82)
+        : (dark ? DarkPalette.accent-soft : LightPalette.accent-soft);
+    out property <color> accent-contrast: #FFFFFF;
+    // accent 上的前景色按相对亮度自动选黑/白（自定义亮黄、浅青时白字会糊）。
+    // 注意：Slint 的 color 通道字段（`.red` 等）是 0~255 的**整数**。
+    out property <float> accent-luma: accent.red * 0.299 + accent.green * 0.587 + accent.blue * 0.114;
+    out property <color> fg-on-accent: accent-luma > 160 ? #1A1A1A : #FFFFFF;
+
+    // ── 面板底色（`panel-alpha` 统一透出背景图）────────────────────
+    // `*-solid` 是不透明原件（窗口自身底色 / accent.mix 的混合基准必须不透明，
+    // 否则浮点叠加会让 accent-soft 随 panel-alpha 一起变淡）。
+    // 半透明色用 `rgba(r, g, b, a)` 重建而不是 `.with-alpha()`：后者返回 Brush，
+    // 赋给 `<color>` 属性会类型不符（Slint 无 Brush → color 隐式回退）。
+    out property <color> surface-solid: dark ? DarkPalette.bg-surface : LightPalette.bg-surface;
+    out property <color> canvas-solid: dark ? DarkPalette.bg-canvas : LightPalette.bg-canvas;
+    out property <color> surface-elevated-solid: dark ? DarkPalette.bg-elevated : LightPalette.bg-elevated;
+    out property <color> titlebar-solid: dark ? DarkPalette.bg-titlebar : LightPalette.bg-titlebar;
+    out property <color> hover-solid: dark ? DarkPalette.bg-hover : LightPalette.bg-hover;
+    out property <color> pressed-solid: dark ? DarkPalette.bg-pressed : LightPalette.bg-pressed;
+    out property <color> input-solid: dark ? DarkPalette.bg-input : LightPalette.bg-input;
+
+    out property <color> bg-canvas: rgba(
+        canvas-solid.red, canvas-solid.green, canvas-solid.blue, panel-alpha);
+    out property <color> bg-surface: rgba(
+        surface-solid.red, surface-solid.green, surface-solid.blue, panel-alpha);
+    out property <color> bg-elevated: rgba(
+        surface-elevated-solid.red, surface-elevated-solid.green, surface-elevated-solid.blue, panel-alpha);
+    out property <color> bg-titlebar: rgba(
+        titlebar-solid.red, titlebar-solid.green, titlebar-solid.blue, panel-alpha);
+    out property <color> bg-hover: rgba(
+        hover-solid.red, hover-solid.green, hover-solid.blue, panel-alpha);
+    out property <color> bg-pressed: rgba(
+        pressed-solid.red, pressed-solid.green, pressed-solid.blue, panel-alpha);
+    out property <color> bg-input: rgba(
+        input-solid.red, input-solid.green, input-solid.blue, panel-alpha);
+
+    out property <color> fg-primary: dark ? DarkPalette.fg-primary : LightPalette.fg-primary;
+    out property <color> fg-secondary: dark ? DarkPalette.fg-secondary : LightPalette.fg-secondary;
+    out property <color> fg-disabled: dark ? DarkPalette.fg-disabled : LightPalette.fg-disabled;
+
+    out property <color> stroke: dark ? DarkPalette.stroke : LightPalette.stroke;
+    out property <color> stroke-strong: dark ? DarkPalette.stroke-strong : LightPalette.stroke-strong;
+    out property <color> shadow: dark ? DarkPalette.shadow : LightPalette.shadow;
+    out property <color> scrim: dark ? DarkPalette.scrim : LightPalette.scrim;
+
+    out property <color> state-success: dark ? DarkPalette.state-success : LightPalette.state-success;
+    out property <color> state-success-soft: dark ? DarkPalette.state-success-soft : LightPalette.state-success-soft;
+    out property <color> state-warn: dark ? DarkPalette.state-warn : LightPalette.state-warn;
+    out property <color> state-warn-soft: dark ? DarkPalette.state-warn-soft : LightPalette.state-warn-soft;
+    out property <color> state-danger: dark ? DarkPalette.state-danger : LightPalette.state-danger;
+    out property <color> state-danger-hover: dark ? DarkPalette.state-danger-hover : LightPalette.state-danger-hover;
+    out property <color> state-danger-soft: dark ? DarkPalette.state-danger-soft : LightPalette.state-danger-soft;
+    out property <color> state-info-soft: dark ? DarkPalette.state-info-soft : LightPalette.state-info-soft;
+
+    // ── 字体 ────────────────────────────────────────────────────
+    // Segoe UI 不可再分发（微软许可）→ Windows 用系统自带，其他平台用 Selawik
+    // （微软官方开源、Segoe UI 度量兼容）+ Open Sans 回退栈（01c §7 第 5 条）。
+    // Slint 的 font-family 只吃单个家族名，回退链由 Rust 侧启动时按平台选择 + 注册字体族实现：
+    //   windows → "Segoe UI"，macos/linux → "Selawik"（随包）+ "Open Sans" 兜底。
+    in-out property <string> font-family: "Selawik";
+    in-out property <string> font-family-mono: "Cascadia Mono";
+    // 中文回退（思源黑体/微软雅黑由系统字体匹配，这里仅作显式声明）
+    in-out property <string> font-family-cjk: "Microsoft YaHei UI";
+
+    // 排版层级（Metro typography ramp）
+    out property <length> font-size-display: 24px;
+    out property <length> font-size-title: 20px;
+    out property <length> font-size-subtitle: 16px;
+    out property <length> font-size-body: 14px;
+    out property <length> font-size-caption: 12px;
+    out property <length> line-height-body: 20px;
+    out property <length> line-height-caption: 16px;
+
+    // ── 动效（Metro 快速、克制）───────────────────────────────────
+    out property <duration> motion-fast: 90ms;
+    out property <duration> motion-normal: 160ms;
+    out property <duration> motion-slow: 240ms;
+    // D17 动画强度倍率（P0 占位，P1 接设置页滑条与「减少动画」无障碍开关）
+    in-out property <float> motion-scale: 1.0;
+}
diff --git a/crates/app/ui/widgets/button.slint b/crates/app/ui/widgets/button.slint
new file mode 100644
index 0000000..7185f87
--- /dev/null
+++ b/crates/app/ui/widgets/button.slint
@@ -0,0 +1,83 @@
+// Metro 按钮：扁平 + accent 填充，无圆角渐变，hover 只变底色（D14）。
+// 四种语义：accent（主操作）/ standard（次要）/ subtle（工具条）/ danger（危险确认）。
+// grow = true 时占满布局剩余宽度（磁贴的启动键），否则保持内容宽度（工具按钮）。
+import { Theme } from "../theme/tokens.slint";
+import { Metrics } from "../theme/metrics.slint";
+import { AppIcon, IconKind } from "../components/icons.slint";
+import { UiText, TextRole } from "../components/label.slint";
+
+export enum ButtonKind {
+    accent,
+    standard,
+    subtle,
+    danger,
+}
+
+export component MetroButton inherits Rectangle {
+    in property <ButtonKind> kind: ButtonKind.standard;
+    in property <string> text: "";
+    in property <IconKind> icon: IconKind.plus;
+    /// 是否显示图标（纯文字按钮置 false）
+    in property <bool> show-icon: false;
+    in property <bool> enabled: true;
+    /// 图标按钮：不画文字，尺寸压到正方形
+    in property <bool> icon-only: false;
+    /// 在布局中占据剩余宽度
+    in property <bool> grow: false;
+    in property <length> button-height: Metrics.control-height;
+    callback clicked();
+
+    min-width: icon-only ? button-height : text-layout.preferred-width;
+    height: button-height;
+    horizontal-stretch: grow ? 1 : 0;
+    border-radius: Metrics.radius-sm;
+    border-width: kind == ButtonKind.standard ? 1px : 0px;
+    border-color: Theme.stroke-strong;
+    opacity: enabled ? 1.0 : 0.45;
+
+    background: kind == ButtonKind.accent
+            ? (touch.has-hover ? Theme.accent-hover : Theme.accent)
+        : kind == ButtonKind.danger
+            ? (touch.has-hover ? Theme.state-danger-hover : Theme.state-danger)
+        : kind == ButtonKind.subtle
+            ? (touch.pressed ? Theme.bg-pressed : touch.has-hover ? Theme.bg-hover : transparent)
+        : (touch.pressed ? Theme.bg-pressed : touch.has-hover ? Theme.bg-hover : Theme.bg-surface);
+    animate background { duration: Theme.motion-fast; }
+
+    text-layout := HorizontalLayout {
+        alignment: center;
+        padding-left: icon-only ? 0px : Metrics.gap-2;
+        padding-right: icon-only ? 0px : Metrics.gap-2;
+        spacing: Metrics.gap-1;
+
+        AppIcon {
+            icon-size: Metrics.touch-target / 2;
+            kind: root.icon;
+            visible: root.show-icon || root.icon-only;
+            tint: kind == ButtonKind.accent || kind == ButtonKind.danger
+                ? Theme.fg-on-accent
+                : Theme.fg-primary;
+        }
+        UiText {
+            role: TextRole.bodyStrong;
+            text: root.text;
+            visible: !root.icon-only;
+            color: kind == ButtonKind.accent || kind == ButtonKind.danger
+                ? Theme.fg-on-accent
+                : Theme.fg-primary;
+            horizontal-alignment: center;
+        }
+    }
+
+    touch := TouchArea {
+        mouse-cursor: root.enabled ? pointer : default;
+        clicked => {
+            if (root.enabled) {
+                root.clicked();
+            }
+        }
+    }
+
+    accessible-role: button;
+    accessible-label: root.text;
+}
diff --git a/crates/app/ui/widgets/dialog.slint b/crates/app/ui/widgets/dialog.slint
new file mode 100644
index 0000000..a8522fa
--- /dev/null
+++ b/crates/app/ui/widgets/dialog.slint
@@ -0,0 +1,122 @@
+// 对话框宿主：HMCL 队列语义（一次只显示一条，来源排序由 Rust DialogQueue 决定）+ Metro 化外观。
+// 类型：确认 / 输入 / 进度 / 错误（含诊断入口）。
+import { Theme } from "../theme/tokens.slint";
+import { Metrics } from "../theme/metrics.slint";
+import { UiDialog, DialogKind } from "../models.slint";
+import { UiText, TextRole } from "../components/label.slint";
+import { AppIcon, IconKind } from "../components/icons.slint";
+import { MetroButton, ButtonKind } from "button.slint";
+import { TextField } from "inputs.slint";
+
+export component DialogHost inherits Rectangle {
+    in property <UiDialog> current;
+    in property <bool> open: false;
+    /// 队列中剩余条数（>0 时卡片底部提示「还有 N 条待处理」，语义上是队列而非堆叠）
+    in property <int> queued: 0;
+    in-out property <string> input-text: "";
+    callback primary();
+    callback secondary();
+    callback dismissed();
+
+    width: 100%;
+    height: 100%;
+    background: Theme.scrim;
+    visible: open;
+
+    // 吞掉遮罩上的点击，避免误触下层页面
+    TouchArea {
+        clicked => { root.dismissed(); }
+    }
+
+    card := Rectangle {
+        x: (root.width - card.width) / 2;
+        y: (root.height - card.height) / 2;
+        width: 440px;
+        height: content.preferred-height;
+        background: Theme.bg-elevated;
+        border-radius: Metrics.radius-lg;
+        border-width: 1px;
+        border-color: Theme.stroke;
+        drop-shadow-blur: 24px;
+        drop-shadow-color: Theme.shadow;
+        drop-shadow-offset-y: 6px;
+
+        content := VerticalLayout {
+            padding: Metrics.gap-5;
+            spacing: Metrics.gap-3;
+
+            HorizontalLayout {
+                spacing: Metrics.gap-2;
+
+                if root.current.kind == DialogKind.error : AppIcon {
+                    kind: IconKind.error;
+                    icon-size: 20px;
+                    tint: Theme.state-danger;
+                }
+                if root.current.kind == DialogKind.confirm : AppIcon {
+                    kind: IconKind.warn;
+                    icon-size: 20px;
+                    tint: Theme.state-warn;
+                }
+                UiText {
+                    role: TextRole.title;
+                    text: root.current.title;
+                    horizontal-stretch: 1;
+                }
+            }
+
+            body-text := UiText {
+                role: TextRole.body;
+                text: root.current.body;
+                wrap: word-wrap;
+                overflow: elide;
+                color: Theme.fg-secondary;
+                vertical-alignment: top;
+                height: body-text.preferred-height;
+            }
+
+            if root.current.kind == DialogKind.input : TextField {
+                placeholder: root.current.input_label;
+                text <=> root.input-text;
+            }
+
+            if root.current.kind == DialogKind.progress : track := Rectangle {
+                height: 6px;
+                border-radius: 3px;
+                background: Theme.bg-pressed;
+
+                Rectangle {
+                    width: track.width * Math.min(Math.max(root.current.progress, 0), 1);
+                    height: track.height;
+                    border-radius: 3px;
+                    background: Theme.accent;
+                }
+            }
+
+            HorizontalLayout {
+                spacing: Metrics.gap-2;
+                alignment: end;
+                padding-top: Metrics.gap-2;
+
+                UiText {
+                    role: TextRole.caption;
+                    text: root.queued > 0 ? "还有 " + root.queued + " 条待处理" : "";
+                    horizontal-stretch: 1;
+                    horizontal-alignment: left;
+                }
+
+                if root.current.secondary != "" : MetroButton {
+                    kind: ButtonKind.subtle;
+                    text: root.current.secondary;
+                    clicked => { root.secondary(); }
+                }
+                MetroButton {
+                    kind: root.current.kind == DialogKind.error ? ButtonKind.danger : ButtonKind.accent;
+                    text: root.current.primary;
+                    enabled: root.current.kind != DialogKind.progress;
+                    clicked => { root.primary(); }
+                }
+            }
+        }
+    }
+}
diff --git a/crates/app/ui/widgets/inputs.slint b/crates/app/ui/widgets/inputs.slint
new file mode 100644
index 0000000..b522a00
--- /dev/null
+++ b/crates/app/ui/widgets/inputs.slint
@@ -0,0 +1,300 @@
+// 基础输入件：单行输入（含占位文本）、搜索框、开关、分段控件、复选框。
+// 一律自绘（Metro 需要方角 + accent 高亮）。占位文本手绘：内置 TextInput 没有
+// placeholder-text（那是 std-widgets 的 LineEdit，外观不可控）。
+import { Theme } from "../theme/tokens.slint";
+import { Metrics } from "../theme/metrics.slint";
+import { AppIcon, IconKind } from "../components/icons.slint";
+import { UiText, TextRole } from "../components/label.slint";
+
+/// 单行输入：内置 TextInput + 占位文本层（Focus 态由外部读 `focused`）。
+export component PlainInput inherits Rectangle {
+    in-out property <string> text: "";
+    in property <string> placeholder: "";
+    in property <color> text-color: Theme.fg-primary;
+    in property <length> text-padding: 0px;
+    out property <bool> focused: input.has-focus;
+    callback edited(string);
+    callback accepted(string);
+
+    background: transparent;
+
+    input := TextInput {
+        x: root.text-padding;
+        y: 0;
+        width: root.width - 2 * root.text-padding;
+        height: root.height;
+        color: root.text-color;
+        font-family: Theme.font-family;
+        font-size: Theme.font-size-body;
+        vertical-alignment: center;
+        single-line: true;
+        text <=> root.text;
+        edited => { root.edited(self.text); }
+        accepted => { root.accepted(self.text); }
+    }
+
+    if root.text == "" && root.placeholder != "" : UiText {
+        x: root.text-padding;
+        y: 0;
+        width: root.width - 2 * root.text-padding;
+        height: root.height;
+        role: TextRole.body;
+        text: root.placeholder;
+        color: Theme.fg-disabled;
+    }
+}
+
+export component SearchField inherits Rectangle {
+    in-out property <string> text: "";
+    in property <string> placeholder: "搜索";
+    callback edited(string);
+    callback accepted(string);
+
+    height: Metrics.control-height;
+    background: Theme.bg-input;
+    border-radius: Metrics.radius-sm;
+    border-width: 1px;
+    border-color: field.focused ? Theme.accent : Theme.stroke;
+
+    HorizontalLayout {
+        padding-left: Metrics.gap-2;
+        padding-right: Metrics.gap-2;
+        spacing: Metrics.gap-2;
+
+        AppIcon { kind: IconKind.search; icon-size: 14px; }
+
+        field := PlainInput {
+            placeholder: root.placeholder;
+            text <=> root.text;
+            edited(t) => { root.edited(t); }
+            accepted(t) => { root.accepted(t); }
+        }
+    }
+}
+
+export component TextField inherits Rectangle {
+    in-out property <string> text: "";
+    in property <string> placeholder: "";
+    callback edited(string);
+
+    height: Metrics.control-height;
+    background: Theme.bg-input;
+    border-radius: Metrics.radius-sm;
+    border-width: 1px;
+    border-color: field.focused ? Theme.accent : Theme.stroke;
+
+    field := PlainInput {
+        text-padding: Metrics.gap-2;
+        placeholder: root.placeholder;
+        text <=> root.text;
+        edited(t) => { root.edited(t); }
+    }
+}
+
+export component ToggleSwitch inherits Rectangle {
+    in-out property <bool> checked: false;
+    callback toggled(bool);
+
+    width: 40px;
+    height: 20px;
+    border-radius: 10px;
+    background: checked ? Theme.accent : Theme.stroke-strong;
+    animate background { duration: Theme.motion-normal; }
+
+    Rectangle {
+        width: 14px;
+        height: 14px;
+        y: 3px;
+        x: root.checked ? root.width - self.width - 3px : 3px;
+        border-radius: 7px;
+        background: Theme.fg-on-accent;
+        animate x { duration: Theme.motion-normal; easing: ease-in-out; }
+    }
+
+    TouchArea {
+        mouse-cursor: pointer;
+        clicked => {
+            root.checked = !root.checked;
+            root.toggled(root.checked);
+        }
+    }
+}
+
+/// 分段控件（视图切换、磁贴尺寸、主题三态共用）
+export component SegmentedControl inherits Rectangle {
+    in property <[string]> options;
+    in-out property <int> selected: 0;
+    callback changed(int);
+
+    height: Metrics.control-height;
+    background: Theme.bg-canvas;
+    border-radius: Metrics.radius-sm;
+    border-width: 1px;
+    border-color: Theme.stroke;
+
+    HorizontalLayout {
+        padding: 2px;
+        spacing: 2px;
+        for o[i] in options : Rectangle {
+            border-radius: Metrics.radius-sm;
+            background: i == root.selected
+                ? Theme.accent
+                : (seg.has-hover ? Theme.bg-hover : transparent);
+            animate background { duration: Theme.motion-fast; }
+
+            UiText {
+                role: TextRole.caption;
+                text: o;
+                horizontal-alignment: center;
+                color: i == root.selected ? Theme.fg-on-accent : Theme.fg-primary;
+            }
+
+            seg := TouchArea {
+                mouse-cursor: pointer;
+                clicked => {
+                    root.selected = i;
+                    root.changed(i);
+                }
+            }
+        }
+    }
+}
+
+export component CheckBox inherits Rectangle {    in-out property <bool> checked: false;
+    in property <string> text: "";
+    callback toggled(bool);
+
+    height: Metrics.touch-target;
+    background: transparent;
+
+    HorizontalLayout {
+        spacing: Metrics.gap-2;
+
+        Rectangle {
+            width: 16px;
+            height: 16px;
+            border-radius: Metrics.radius-sm;
+            border-width: 1px;
+            border-color: root.checked ? Theme.accent : Theme.stroke-strong;
+            background: root.checked ? Theme.accent : Theme.bg-input;
+
+            if root.checked : AppIcon {
+                kind: IconKind.check;
+                icon-size: 12px;
+                x: 2px;
+                y: 2px;
+                tint: Theme.fg-on-accent;
+            }
+        }
+
+        UiText { role: TextRole.body; text: root.text; }
+
+        TouchArea {
+            mouse-cursor: pointer;
+            clicked => {
+                root.checked = !root.checked;
+                root.toggled(root.checked);
+            }
+        }
+    }
+}
+
+/// 滑条（09 §102/§101 的「强度滑条」：暗化层强度、面板半透明度共用）。
+/// 自绘而非 std-widgets 的 Slider：Metro 需要方头轨道 + accent 填充，且要跟主题令牌一起换肤。
+export component MetroSlider inherits Rectangle {
+    in property <float> minimum: 0.0;
+    in property <float> maximum: 1.0;
+    in-out property <float> value: 1.0;
+    callback changed(float);
+
+    out property <float> ratio: root.maximum > root.minimum
+        ? Math.max(0.0, Math.min(1.0, (root.value - root.minimum) / (root.maximum - root.minimum)))
+        : 0.0;
+
+    width: 200px;
+    height: Metrics.touch-target;
+    background: transparent;
+
+    /// 鼠标位置 → 取值（Slint 的 function 不能声明局部变量，所以拆成纯函数；
+    /// 函数名不用 kebab-case：`value-at(...)` 会被当成减法解析）
+    pure function valueForX(x: length) -> float {
+        return root.minimum
+            + Math.max(0.0, Math.min(1.0, x / root.width)) * (root.maximum - root.minimum);
+    }
+
+    // 轨道 + 已填充段
+    Rectangle {
+        x: 0;
+        y: (root.height - 4px) / 2;
+        width: root.width;
+        height: 4px;
+        border-radius: 2px;
+        background: Theme.stroke-strong;
+    }
+    Rectangle {
+        x: 0;
+        y: (root.height - 4px) / 2;
+        width: root.width * root.ratio;
+        height: 4px;
+        border-radius: 2px;
+        background: Theme.accent;
+    }
+    // 滑块
+    Rectangle {
+        x: (root.width - 14px) * root.ratio;
+        y: (root.height - 14px) / 2;
+        width: 14px;
+        height: 14px;
+        border-radius: 7px;
+        background: Theme.accent;
+        border-width: 2px;
+        border-color: Theme.surface-solid;
+    }
+
+    area := TouchArea {
+        mouse-cursor: pointer;
+        moved => {
+            root.value = root.valueForX(self.mouse-x);
+            root.changed(root.value);
+        }
+        clicked => {
+            root.value = root.valueForX(self.mouse-x);
+            root.changed(root.value);
+        }
+    }
+
+    accessible-role: slider;
+}
+
+/// 预设色板（09 §104 自定义强调色：预设色板 + 取色器，取色器由十六进制输入承担）。
+export component ColorSwatches inherits Rectangle {
+    in property <[color]> palette;
+    in property <color> current;
+    /// 传**索引**而不是 color：Slint 没有「颜色 → #RRGGBB」的格式化，
+    /// 预设色板的十六进制串由 Rust 侧同一张表给出（一处真相）。
+    callback picked(int);
+
+    width: root.palette.length * 28px;
+    height: 28px;
+    background: transparent;
+
+    HorizontalLayout {
+        spacing: 4px;
+
+        for shade[i] in root.palette : Rectangle {
+            width: 24px;
+            height: 24px;
+            border-radius: Metrics.radius-sm;
+            background: shade;
+            border-width: shade == root.current ? 2px : 1px;
+            border-color: shade == root.current ? Theme.fg-primary : Theme.stroke;
+
+            swatch-touch := TouchArea {
+                mouse-cursor: pointer;
+                clicked => { root.picked(i); }
+            }
+
+            accessible-role: button;
+        }
+    }
+}
diff --git a/crates/app/ui/widgets/setting-item.slint b/crates/app/ui/widgets/setting-item.slint
new file mode 100644
index 0000000..e2f1f57
--- /dev/null
+++ b/crates/app/ui/widgets/setting-item.slint
@@ -0,0 +1,155 @@
+// 设置项行：左标签+说明，右控件。控件类型用 ControlKind 收敛，避免为每个设置项写一遍布局。
+// （Slint 没有 slot 机制，所以用 kind 枚举 + 通用属性把控件种类收在一处。）
+//
+// M41 增加两种控件：`slider`（强度/透明度滑条）与 `swatches`（预设色板 + 取色器入口），
+// 它们服务 09 §101-104 的「外观（高级）」四件——高级特性默认关闭，控件本身常显（关着也能调）。
+import { Theme } from "../theme/tokens.slint";
+import { Metrics } from "../theme/metrics.slint";
+import { UiText, TextRole } from "../components/label.slint";
+import { MetroButton, ButtonKind } from "button.slint";
+import {
+    ToggleSwitch, SegmentedControl, TextField, MetroSlider, ColorSwatches,
+} from "inputs.slint";
+
+export enum ControlKind {
+    none,
+    toggle,
+    segmented,
+    button,
+    text,
+    slider,
+    swatches,
+}
+
+export component SettingItem inherits Rectangle {
+    in property <string> label: "";
+    in property <string> description: "";
+    in property <ControlKind> kind: ControlKind.none;
+    in property <[string]> options;
+    in property <string> button-text: "";
+    in-out property <int> selected: 0;
+    in-out property <bool> checked: false;
+    in-out property <string> value: "";
+    // 滑条
+    in property <float> min-value: 0.0;
+    in property <float> max-value: 1.0;
+    in-out property <float> slider-value: 1.0;
+    // 色板
+    in property <[color]> swatch-colors;
+    in property <color> swatch-current: transparent;
+    // 危险/提示色描述（如「对比度偏低」）
+    in property <bool> warn: false;
+
+    callback toggled(bool);
+    callback changed(int);
+    callback clicked();
+    callback edited(string);
+    callback slid(float);
+    callback swatch-picked(int);
+
+    height: root.description == "" ? 44px : 60px;
+    background: transparent;
+
+    HorizontalLayout {
+        padding-left: Metrics.gap-4;
+        padding-right: Metrics.gap-4;
+        spacing: Metrics.gap-4;
+
+        VerticalLayout {
+            spacing: 0px;
+            vertical-stretch: 1;
+
+            UiText {
+                role: TextRole.body;
+                text: root.label;
+                horizontal-stretch: 1;
+            }
+            UiText {
+                role: TextRole.caption;
+                text: root.description;
+                visible: root.description != "";
+                color: root.warn ? Theme.state-warn : Theme.fg-secondary;
+                horizontal-stretch: 1;
+            }
+        }
+
+        if root.kind == ControlKind.toggle : ToggleSwitch {
+            checked: root.checked;
+            toggled(v) => {
+                root.checked = v;
+                root.toggled(v);
+            }
+        }
+
+        if root.kind == ControlKind.segmented : SegmentedControl {
+            width: root.options.length * 64px;
+            options: root.options;
+            selected: root.selected;
+            changed(i) => {
+                root.selected = i;
+                root.changed(i);
+            }
+        }
+
+        if root.kind == ControlKind.button : MetroButton {
+            kind: ButtonKind.standard;
+            text: root.button-text;
+            button-height: 28px;
+            clicked => { root.clicked(); }
+        }
+
+        if root.kind == ControlKind.text : TextField {
+            width: 240px;
+            placeholder: root.button-text;
+            text <=> root.value;
+            edited(t) => { root.edited(t); }
+        }
+
+        if root.kind == ControlKind.slider : HorizontalLayout {
+            spacing: Metrics.gap-2;
+            alignment: end;
+
+            UiText {
+                role: TextRole.caption;
+                text: (root.slider-value * 100).round() + "%";
+                width: 40px;
+                horizontal-alignment: right;
+                color: Theme.fg-secondary;
+            }
+            MetroSlider {
+                minimum: root.min-value;
+                maximum: root.max-value;
+                value: root.slider-value;
+                changed(v) => {
+                    root.slider-value = v;
+                    root.slid(v);
+                }
+            }
+        }
+
+        if root.kind == ControlKind.swatches : ColorSwatches {
+            palette: root.swatch-colors;
+            current: root.swatch-current;
+            picked(i) => { root.swatch-picked(i); }
+        }
+    }
+}
+
+/// 分组标题
+export component SettingGroup inherits Rectangle {
+    in property <string> title: "";
+
+    height: 36px;
+    background: transparent;
+
+    UiText {
+        x: Metrics.gap-4;
+        y: 0;
+        width: root.width - 2 * Metrics.gap-4;
+        height: root.height;
+        role: TextRole.caption;
+        text: root.title;
+        color: Theme.fg-secondary;
+        font-weight: 600;
+    }
+}
diff --git a/crates/app/ui/widgets/toast.slint b/crates/app/ui/widgets/toast.slint
new file mode 100644
index 0000000..d3a43c6
--- /dev/null
+++ b/crates/app/ui/widgets/toast.slint
@@ -0,0 +1,87 @@
+// Toast：右下角非阻塞提示（下载完成 / 复制成功 / 后台任务结论）。
+// 队列与自动消失时长由 Rust ToastCenter 管理（P0 默认 4s），这里只负责渲染与手动关闭。
+import { Theme } from "../theme/tokens.slint";
+import { Metrics } from "../theme/metrics.slint";
+import { UiToast, ToastKind } from "../models.slint";
+import { UiText, TextRole } from "../components/label.slint";
+import { AppIcon, IconKind } from "../components/icons.slint";
+
+component ToastCard inherits Rectangle {
+    in property <UiToast> data;
+    callback dismissed(string);
+
+    width: 300px;
+    height: body-layout.preferred-height;
+    background: Theme.bg-elevated;
+    border-radius: Metrics.radius-md;
+    border-width: 1px;
+    border-color: Theme.stroke;
+    drop-shadow-blur: 16px;
+    drop-shadow-color: Theme.shadow;
+    drop-shadow-offset-y: 3px;
+
+    // 左侧语义色条：Metro 用色块表达状态，不用图标喧宾夺主
+    Rectangle {
+        x: 0px;
+        y: 0px;
+        width: 3px;
+        height: root.height;
+        background: root.data.kind == ToastKind.success ? Theme.state-success
+            : root.data.kind == ToastKind.warn ? Theme.state-warn
+            : root.data.kind == ToastKind.error ? Theme.state-danger
+            : Theme.accent;
+    }
+
+    body-layout := HorizontalLayout {
+        padding-left: Metrics.gap-3;
+        padding-right: Metrics.gap-2;
+        padding-top: Metrics.gap-2;
+        padding-bottom: Metrics.gap-2;
+        spacing: Metrics.gap-2;
+
+        UiText {
+            role: TextRole.body;
+            text: root.data.text;
+            wrap: word-wrap;
+            horizontal-stretch: 1;
+        }
+
+        AppIcon {
+            kind: IconKind.close;
+            icon-size: 14px;
+            tint: Theme.fg-secondary;
+
+            TouchArea {
+                mouse-cursor: pointer;
+                clicked => { root.dismissed(root.data.id); }
+            }
+        }
+    }
+}
+
+export component ToastHost inherits Rectangle {
+    in property <[UiToast]> toasts;
+    callback dismissed(string);
+
+    width: 100%;
+    height: 100%;
+    background: transparent;
+
+    stack-box := Rectangle {
+        x: root.width - stack-box.width - Metrics.gap-4;
+        y: root.height - stack-box.height - Metrics.gap-4;
+        width: 300px;
+        height: stack.preferred-height;
+        background: transparent;
+
+        stack := VerticalLayout {
+            width: stack-box.width;
+            spacing: Metrics.gap-2;
+
+            for t in root.toasts : ToastCard {
+                data: t;
+                dismissed(id) => { root.dismissed(id); }
+            }
+        }
+    }
+}
diff --git a/crates/app/ui/widgets/wizard.slint b/crates/app/ui/widgets/wizard.slint
new file mode 100644
index 0000000..dda00f2
--- /dev/null
+++ b/crates/app/ui/widgets/wizard.slint
@@ -0,0 +1,301 @@
+// 新建实例向导（G5，全屏模态）：版本 → 加载器 → 名字 → 确认 → 进度。
+// 步骤推进/校验在 Rust（`crate::wizard`），这里只画当前步与提交按钮。
+import { Theme } from "../theme/tokens.slint";
+import { Metrics } from "../theme/metrics.slint";
+import { UiVersion, VersionKind } from "../models.slint";
+import { PageState } from "../page_state.slint";
+import { UiText, TextRole } from "../components/label.slint";
+import { Badge } from "../components/badge.slint";
+import { AppIcon, IconKind } from "../components/icons.slint";
+import { MetroButton, ButtonKind } from "../widgets/button.slint";
+import { SearchField } from "../widgets/inputs.slint";
+import { InstallPanel } from "../components/install-panel.slint";
+import { ScrollView } from "std-widgets.slint";
+
+component StepDot inherits Rectangle {
+    in property <int> index: 0;
+    in property <string> label: "";
+
+    height: 28px;
+    background: transparent;
+
+    HorizontalLayout {
+        spacing: Metrics.gap-1;
+        alignment: center;
+        Rectangle {
+            width: 18px;
+            height: 18px;
+            border-radius: 9px;
+            background: PageState.wizard.step >= root.index ? Theme.accent : Theme.bg-hover;
+            UiText {
+                role: TextRole.caption;
+                text: root.index + 1;
+                horizontal-alignment: center;
+                color: PageState.wizard.step >= root.index ? Theme.fg-on-accent : Theme.fg-secondary;
+            }
+        }
+        UiText {
+            role: TextRole.caption;
+            text: root.label;
+            color: PageState.wizard.step >= root.index ? Theme.fg-primary : Theme.fg-disabled;
+        }
+    }
+}
+
+component VersionChoice inherits Rectangle {
+    in property <UiVersion> data;
+    callback picked();
+
+    height: 36px;
+    background: PageState.wizard.version == root.data.id ? Theme.accent-soft
+        : (touch.has-hover ? Theme.bg-hover : transparent);
+
+    HorizontalLayout {
+        padding-left: Metrics.gap-3;
+        padding-right: Metrics.gap-3;
+        spacing: Metrics.gap-2;
+        UiText { role: TextRole.body; text: root.data.id; width: 160px; }
+        Badge {
+            text: root.data.kind == VersionKind.release ? "正式版" : "预览版";
+            tint: Theme.fg-secondary;
+        }
+        UiText { role: TextRole.caption; text: root.data.released; horizontal-stretch: 1; }
+        if PageState.wizard.version == root.data.id : AppIcon {
+            kind: IconKind.check;
+            icon-size: 14px;
+            tint: Theme.accent;
+        }
+    }
+
+    touch := TouchArea {
+        mouse-cursor: pointer;
+        clicked => { root.picked(); }
+    }
+}
+
+component LoaderChoice inherits Rectangle {
+    in property <string> label: "";
+    in property <string> hint: "";
+    in property <int> index: 0;
+    callback picked();
+
+    height: 48px;
+    background: PageState.wizard.loader == root.index ? Theme.accent-soft
+        : (touch.has-hover ? Theme.bg-hover : transparent);
+
+    HorizontalLayout {
+        padding-left: Metrics.gap-3;
+        padding-right: Metrics.gap-3;
+        spacing: Metrics.gap-2;
+        VerticalLayout {
+            vertical-stretch: 1;
+            spacing: 0px;
+            UiText { role: TextRole.body; text: root.label; }
+            UiText { role: TextRole.caption; text: root.hint; horizontal-stretch: 1; }
+        }
+        if PageState.wizard.loader == root.index : AppIcon {
+            kind: IconKind.check;
+            icon-size: 14px;
+            tint: Theme.accent;
+        }
+    }
+
+    touch := TouchArea {
+        mouse-cursor: pointer;
+        clicked => { root.picked(); }
+    }
+}
+
+export component NewInstanceWizard inherits Rectangle {
+    // 版本列表由 shell 传入（与下载页共用一份，避免二次拉取）
+    in property <[UiVersion]> versions;
+    in-out property <string> query: "";
+
+    visible: PageState.wizard.open;
+    background: rgba(0, 0, 0, 0.45);
+
+    // 吃掉底层点击（模态）
+    TouchArea { }
+
+    Rectangle {
+        x: (parent.width - self.width) / 2;
+        y: (parent.height - self.height) / 2;
+        width: min(parent.width - 80px, 720px);
+        height: min(parent.height - 60px, 560px);
+        background: Theme.bg-surface;
+        border-radius: Metrics.radius-md;
+        border-width: 1px;
+        border-color: Theme.stroke;
+
+        VerticalLayout {
+            // 标题栏
+            Rectangle {
+                height: 52px;
+                background: transparent;
+                HorizontalLayout {
+                    padding-left: Metrics.gap-4;
+                    padding-right: Metrics.gap-3;
+                    spacing: Metrics.gap-2;
+                    UiText {
+                        role: TextRole.subtitle;
+                        text: "新建实例 · " + PageState.wizard.step_label;
+                        horizontal-stretch: 1;
+                    }
+                    MetroButton {
+                        kind: ButtonKind.subtle;
+                        text: "关闭";
+                        button-height: 24px;
+                        clicked => { PageState.wizard-close(); }
+                    }
+                }
+            }
+
+            // 步骤指示
+            HorizontalLayout {
+                padding-left: Metrics.gap-4;
+                spacing: Metrics.gap-3;
+                StepDot { index: 0; label: "版本"; }
+                StepDot { index: 1; label: "加载器"; }
+                StepDot { index: 2; label: "名字"; }
+                StepDot { index: 3; label: "确认"; }
+                StepDot { index: 4; label: "进度"; }
+            }
+
+            Rectangle { height: 1px; background: Theme.stroke; }
+
+            // 步骤内容
+            Rectangle {
+                vertical-stretch: 1;
+                background: transparent;
+
+                // ① 选版本（只列正式版/快照，远古版走下载页的显式入口）
+                if PageState.wizard.step == 0 : VerticalLayout {
+                    padding: Metrics.gap-3;
+                    spacing: Metrics.gap-2;
+                    SearchField {
+                        width: 220px;
+                        text <=> root.query;
+                        placeholder: "筛选版本号";
+                    }
+                    ScrollView {
+                        vertical-stretch: 1;
+                        VerticalLayout {
+                            for v in root.versions : VersionChoice {
+                                visible: !v.ancient;
+                                data: v;
+                                picked => { PageState.wizard-select-version(v.id); }
+                            }
+                        }
+                    }
+                }
+
+                // ② 选加载器
+                if PageState.wizard.step == 1 : VerticalLayout {
+                    padding: Metrics.gap-3;
+                    spacing: 0px;
+                    LoaderChoice { index: 0; label: "原版（Vanilla）"; hint: "不装加载器，最快最稳"; picked => { PageState.wizard-select-loader(0); } }
+                    LoaderChoice { index: 1; label: "Fabric"; hint: "轻量模组加载器（GUI 可直接装）"; picked => { PageState.wizard-select-loader(1); } }
+                    LoaderChoice { index: 2; label: "Quilt"; hint: "Fabric 的分支（GUI 可直接装）"; picked => { PageState.wizard-select-loader(2); } }
+                    LoaderChoice { index: 3; label: "Forge"; hint: "需要 installer processors（首装会外调 java，约 1–3 分钟）"; picked => { PageState.wizard-select-loader(3); } }
+                    LoaderChoice { index: 4; label: "NeoForge"; hint: "需要 installer processors（首装会外调 java，约 1–3 分钟）"; picked => { PageState.wizard-select-loader(4); } }
+                }
+
+                // ③ 名字
+                if PageState.wizard.step == 2 : VerticalLayout {
+                    padding: Metrics.gap-4;
+                    spacing: Metrics.gap-2;
+                    UiText { role: TextRole.body; text: "实例名（默认用版本号）"; }
+                    SearchField {
+                        width: 320px;
+                        text: PageState.wizard.name;
+                        placeholder: "例如：生存 1.20.4";
+                        edited(t) => { PageState.wizard-name-changed(t); }
+                    }
+                    if PageState.wizard.error != "" : UiText {
+                        role: TextRole.caption;
+                        text: PageState.wizard.error;
+                        color: Theme.state-danger;
+                    }
+                    UiText {
+                        role: TextRole.caption;
+                        text: "不能包含 / \\ : * ? \" < > |，最多 64 个字符。";
+                    }
+                }
+
+                // ④ 确认
+                if PageState.wizard.step == 3 : VerticalLayout {
+                    padding: Metrics.gap-4;
+                    spacing: Metrics.gap-2;
+                    UiText { role: TextRole.bodyStrong; text: "将创建实例"; }
+                    UiText { role: TextRole.body; text: "版本 " + PageState.wizard.version; }
+                    UiText { role: TextRole.body; text: "加载器 " + PageState.wizard.loader_label; }
+                    UiText { role: TextRole.body; text: "实例名 " + PageState.wizard.name; }
+                    UiText {
+                        role: TextRole.caption;
+                        text: "确认后会按 core 安装管线下载：版本 JSON → 客户端 jar → 库 → 资源索引 → 登记实例。";
+                        wrap: word-wrap;
+                    }
+                    if PageState.wizard.error != "" : UiText {
+                        role: TextRole.caption;
+                        text: PageState.wizard.error;
+                        color: Theme.state-danger;
+                    }
+                }
+
+                // ⑤ 进度
+                if PageState.wizard.step == 4 : VerticalLayout {
+                    padding: Metrics.gap-3;
+                    spacing: Metrics.gap-2;
+                    InstallPanel {
+                        data: PageState.install;
+                        cancel => { PageState.install-cancel(); }
+                    }
+                    UiText {
+                        role: TextRole.caption;
+                        text: "装完会自动跳到实例页；失败原因会显示在上面。";
+                    }
+                }
+            }
+
+            Rectangle { height: 1px; background: Theme.stroke; }
+
+            // 底部按钮
+            Rectangle {
+                height: 56px;
+                background: transparent;
+                HorizontalLayout {
+                    padding: Metrics.gap-4;
+                    spacing: Metrics.gap-2;
+                    Rectangle { horizontal-stretch: 1; background: transparent; }
+                    MetroButton {
+                        kind: ButtonKind.subtle;
+                        text: "上一步";
+                        button-height: 30px;
+                        enabled: PageState.wizard.step > 0 && PageState.wizard.step < 4;
+                        clicked => { PageState.wizard-back(); }
+                    }
+                    if PageState.wizard.step < 3 : MetroButton {
+                        kind: ButtonKind.accent;
+                        text: "下一步";
+                        button-height: 30px;
+                        enabled: PageState.wizard.can-next;
+                        clicked => { PageState.wizard-next(); }
+                    }
+                    if PageState.wizard.step == 3 : MetroButton {
+                        kind: ButtonKind.accent;
+                        text: "开始安装";
+                        button-height: 30px;
+                        enabled: PageState.wizard.can-next && !PageState.wizard.busy;
+                        clicked => { PageState.wizard-confirm(); }
+                    }
+                    if PageState.wizard.step == 4 : MetroButton {
+                        kind: ButtonKind.standard;
+                        text: "后台继续";
+                        button-height: 30px;
+                        clicked => { PageState.wizard-close(); }
+                    }
+                }
+            }
+        }
+    }
+}
diff --git a/crates/cli/Cargo.toml b/crates/cli/Cargo.toml
new file mode 100644
index 0000000..81b016e
--- /dev/null
+++ b/crates/cli/Cargo.toml
@@ -0,0 +1,35 @@
+[package]
+name = "unlucky-cli"
+description = "Unlucky-Launcher 命令行（bin `ull`）：headless 消费者，零 UI 框架依赖（D18）"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+publish.workspace = true
+
+# 产物名钉死 `ull`（D18 定案）：单文件 CLI，与 GUI 的 `unlucky-launcher` 并列。
+[[bin]]
+name = "ull"
+path = "src/main.rs"
+
+[lib]
+name = "unlucky_cli"
+path = "src/lib.rs"
+
+# 依赖纪律（10-cli-design.md §2）：core + agent，**不引 Slint**。
+# 参数解析手写（不引 clap）：子命令集小，没必要为它多引一棵依赖树（Win10+ 单基线，
+# 但 CLI 是 headless/服务器场景的产物，体积与启动开销仍是关注项）。
+[dependencies]
+unlucky-core = { path = "../core", version = "0.2" }
+# agent：`redact`（输出脱敏）+ `ull agent serve`（M39 的 MCP server：注册表 → rmcp 双投影，
+# core 侧五个端口在 src/commands/agent/ports/ 装配）。
+unlucky-agent = { path = "../agent", version = "0.2" }
+# `ull agent serve` 要长驻跑 rmcp 的 stdio / Streamable HTTP 传输（tokio 运行时）。
+tokio.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+
+[lints]
+workspace = true
diff --git a/crates/cli/src/cli/help.rs b/crates/cli/src/cli/help.rs
new file mode 100644
index 0000000..c2689a6
--- /dev/null
+++ b/crates/cli/src/cli/help.rs
@@ -0,0 +1,183 @@
+//! 帮助文案（`ull --help` / `ull help <命令>`）。
+//!
+//! 命令集与 `10-cli-design.md` §3 对齐；`agent serve|config`（M39 的 MCP server）已列，
+//! `agent ask`（内置对话的 headless 形态）仍未列。
+
+/// 总帮助。
+#[must_use]
+pub const fn general() -> &'static str {
+    "\
+%prog% · Unlucky-Launcher 命令行（D18）
+
+用法:
+  %prog% [全局选项] <命令> [参数]
+
+命令:
+  instances list                      列出实例与已安装版本
+  install <version> [--loader X] [--loader-version V] [--name N] [--dry-run]
+                                      下载并安装版本本体（--loader fabric|quilt|neoforge|forge
+                                      时再叠一层加载器）→ 登记实例；--dry-run 只出计划
+  launch <instance> [--dry-run] [--account <name>] [--java <path>] [--username <name>]
+                   [--max-memory <MB>] 启动实例；--dry-run 只打印组装后的命令行
+  pack import <file> [--target <dir>] [--name N] [--overwrite] [--no-register]
+                                      导入整合包（CF manifest.json / Modrinth .mrpack /
+                                      MultiMC·Prism 实例）→ 落内容 → 登记实例；
+                                      缺文件降级为「部分成功」（退出码 3）
+  accounts list                       列出账户（名称 / 轨道 / UUID，**不含凭据**）
+  accounts add offline <name>         添加离线账户（HMCL 兼容 UUID）
+  accounts add msa                    添加微软账户（设备码交互式登录）
+  accounts remove <name>              删除账户（连同凭据）
+  sessions list [--limit N]           列出会话记录（倒序）
+  logs <sid> [--tail N]               打印会话事件流末尾
+  diag <sid> [--tail N]               对会话跑规则引擎诊断
+  config get [<key>] [--show-secret]  读配置（生效值；无 key 时输出整份）
+  config set <key> <value>            写配置（走 setting schema 校验）
+  java list                           列出可用 Java（含每个 JDK 的实际落点）
+  java install <major> [--vendor X]   安装托管 JDK（缺省按地区回退链选发行版；
+                                      --vendor temurin|oracle|microsoft|zulu 钉死一家）
+  java vendors                        列出四家发行版的镜像/支持版本/当前优先级
+  agent serve [--stdio] [--port N]    起对外 MCP server（默认 127.0.0.1 的 Streamable HTTP；
+                [--allow-write]       --stdio 给 llama.cpp 内置 client 用；默认只读）
+  agent config [--port N]             打印 Claude Code / Cursor 的配置样例
+  version                             版本 + 系统摘要（同 --version）
+  help [命令]                         本帮助
+
+全局选项:
+  --json          机器可读输出：成功 {\"ok\":true,\"data\":…}，失败 {\"ok\":false,\"error\":…}
+  --data-dir P    覆盖数据根（等价 custom 模式的根目录，即含 .ULL/ 与 .minecraft/ 的父目录）
+  --no-color      关闭颜色（v1 输出不含 ANSI，参数保留以兼容脚本）
+  --quiet         静默人类可读输出（错误与提示仍进 stderr）
+  --help, -h      帮助（有位置参数时按该命令给帮助）
+  --version, -V   版本 + 系统摘要
+
+退出码: 0 成功 / 1 用户错误 / 2 内部错误 / 3 部分成功（仅 pack import）"
+}
+
+/// 单个命令的帮助；未知主题返回 `None`（调用方退回总帮助）。
+#[must_use]
+pub fn topic(name: &str) -> Option<&'static str> {
+    match name {
+        "instances" => Some(
+            "\
+%prog% instances list
+
+列出 profiles.json 里的实例与 versions/ 下已安装的版本。
+ --json 输出 {\"data\":{\"instances\":[…],\"installed_versions\":[…],\"data_root\":…}}",
+        ),
+        "pack" => Some(
+            "\
+%prog% pack import <file> [--target <dir>] [--name N] [--overwrite] [--no-register]
+
+导入一个整合包到实例目录。三种格式按优先级探测（形状校验在前，不靠文件名抢）：
+  CurseForge  manifestType=minecraftModpack 的 manifest.json + overrides/
+  Modrinth    modrinth.index.json + overrides/ client-overrides/（后者胜；
+              server-overrides/ 客户端不解压）
+  MultiMC     mmc-pack.json（formatVersion 必须为 1）+ instance.cfg + .minecraft/
+              （Prism 实例；非加载器 component 会逐项列进报告，不静默丢）
+
+目标目录缺省 = 数据根的共享游戏目录（.minecraft/）；`--target` 可钉到实例目录。
+两阶段落盘：先 overrides（三方合并：包内原值 / 磁盘现状 / 上次基线），再补远端文件。
+  · 用户改过的文件不会被静默覆盖（默认保留，逐条进冲突清单）；`--overwrite` 才用包覆盖
+  · 缺文件（断网 / CurseForge files[] 补不出来）可容忍，但结果降级为「部分成功」
+  · 目录穿越 / 符号链接 / 清单损坏 / 摘要不符一律整包回滚，目标目录零残留
+`--no-register`：只落内容，不写 profiles.json。
+退出码：0 成功 / 3 部分成功 / 1 失败（2 内部错误）。
+--json：信封恒为 {\"ok\":true,\"data\":{…}}，分流看 data.status 与 data.error.code；
+        data.stages 列出实际走过的阶段。",
+        ),
+        "install" => Some(
+            "\
+%prog% install <version> [--loader X] [--loader-version V] [--name N] [--dry-run]
+
+解析版本清单与继承链 → 组下载计划 → 落盘（versions/ assets/ libraries/）→ 登记实例
+（profiles.json + config/instances/<id>.json）。已存在且校验通过的文件会跳过，
+重复装同一版本不重复下载、不重复建实例。
+--dry-run：只输出计划（文件清单 + 总大小 + 每类资源的源选择），不下载、不登记。
+--loader：vanilla（缺省）/ fabric / quilt / neoforge / forge。装加载器时先生成
+versions/<原版>-<加载器>-<版本>/<…>.json（inheritsFrom 原版 + 主类 + loader 库），
+原版没装会先装原版，实例的 versionId 指向 loader 版本。
+--loader-version：加载器版本；缺省取官方默认（Fabric 系首个稳定版，maven 系最新）。
+  Forge 可写 47.2.0 或 1.20.1-47.2.0 两种形态。
+  NeoForge/Forge 里需要跑官方 installer processors 的版本会真跑一遍（M35 已实装）：
+  缺 Java 时按 D23 的回退链自动装一个托管 JDK；--dry-run 只列出要跑的 processor 与依赖库。
+--json：stdout 是单个结果信封 {\"data\":{\"plan\":…,\"result\":…,\"instance\":…}}，
+实时进度改走 stderr 的 JSONL（一行一条 {\"event\":\"progress\"|\"file_failed\"}）；
+--quiet 时连进度也不打。",
+        ),
+        "launch" => Some(
+            "\
+%prog% launch <instance> [--dry-run] [--account <name>] [--java <path>] [--username <name>]
+            [--max-memory <MB>]
+
+<instance> 可以是实例 id、实例名，或直接是版本 id。
+--dry-run（D18）：只组装命令行并打印，不 spawn 进程、不写会话文件、不刷新令牌。
+账户：--account <name> 指定账户（玩家名或条目 id）；不给时用唯一账户，一个都没有则回落
+离线占位（--username 或 Player），有多个账户会报错并列出候选。
+accessToken 一律脱敏（输出里出现的是 <redacted:token>）。",
+        ),
+        "accounts" => Some(
+            "\
+%prog% accounts list
+%prog% accounts add offline <name>
+%prog% accounts add msa
+%prog% accounts remove <name>
+
+账户存在 <数据根>/.ULL/data/auth/：accounts.json（可公开元数据）与 credentials.dat（凭据）
+**分文件**存放，先写凭据后写元数据、原子写、凭据文件 POSIX 侧 0600。
+凭据永不打印：list 只输出名称/轨道/UUID。
+add msa 走微软 device-code（用户码打在 stderr，去 https://www.microsoft.com/link 输码）。
+它需要一个 Azure 公共客户端 id —— 登录链路是完整的，缺的只是这一项配置；id 不进仓库：
+  ULL_MSA_CLIENT_ID=<id> %prog% accounts add msa    每次运行时给（环境变量优先）
+  ULL_MSA_CLIENT_ID=<id> cargo build               构建时注入，二进制自带
+两处都没有时命令立刻报「微软登录未配置」（含怎么配），**不会去联网**。
+authlib-injector 账户的密码登录留给 GUI（密码进 argv 会泄露，CLI 不开这条通道）。",
+        ),
+        "sessions" => Some("%prog% sessions list [--limit N]  列出会话索引（按开始时间倒序，缺省 20 条）"),
+        "logs" => Some("%prog% logs <sid> [--tail N]  <sid> 允许唯一前缀；输出会话 JSONL 末尾 N 条事件（缺省 200）"),
+        "diag" => Some(
+            "%prog% diag <sid> [--tail N]  把会话的退出信号与日志喂给规则引擎（内嵌规则集），输出结构化诊断",
+        ),
+        "config" => Some(
+            "\
+%prog% config get [<key>] [--show-secret]
+%prog% config set <key> <value>
+
+读写 <数据根>/.ULL/config/launcher.json，走 core::setting 的 schema（类型/枚举校验、
+原子写）。敏感键 get 时脱敏，--show-secret 才给明文；值先按 JSON 解析，失败按字符串。",
+        ),
+        "java" => Some(
+            "\
+%prog% java list                           探测 JAVA_HOME / PATH / 托管目录 / 实例覆盖里的 Java
+                                        并打印每个 JDK 的实际落点（managed 项带目录）
+%prog% java install <major> [--vendor X]   安装托管 JDK（D13/D23）：回退链查版本 → 下载 → 解压 → 验证
+%prog% java vendors                        列出四家发行版的镜像/支持版本/当前优先级顺序
+
+落点（D23 三模式，随 core.data_mode 与设置键 java.installRoot 走）：
+  portable（默认）  <数据根>/.ULL/data/java-managed/jdk-<major>-<vendor>/
+  standard          Windows %APPDATA%\\Java\\<发行方>\\<版本>\\；macOS ~/Library/Application Support/Java/…
+                    Linux $XDG_DATA_HOME/java/…
+  custom            设置 java.installRoot 后按 <root>/<发行方>/<版本>/（覆盖前两者）
+
+发行版回退链（D23）：国内 temurin(TUNA) → oracle(华为云→南大) → microsoft(aka.ms)
+→ zulu；国外 temurin → microsoft → oracle → zulu。设置 java.vendorPriority 可改顺序
+（只写几家也行，其余按默认序补齐）；--vendor 钉死一家、不自动降级。
+每家失败的原因（版本不存在 / 镜像全 4xx / 校验失败）进 --json 的 chain 块与人读的「降级：」行。",
+        ),
+        "agent" => Some(
+            "\
+%prog% agent serve [--stdio] [--port N] [--host H] [--allow-write|--readonly]
+%prog% agent config [--port N]
+
+把 agent 的工具注册表挂成 **MCP server**（02 文档 §1 的第二形态：同一注册表、同一安全策略、
+同一审计）。默认走 Streamable HTTP，只绑回环地址（127.0.0.1，默认端口 47823）；
+--stdio 是给 llama.cpp server 的内置 MCP client 用的形态。
+
+写权限默认**关**（只读子集）：要放开需设置键 agent.mcp.allow_write=true 或 --allow-write。
+敏感键（High 分级）在 MCP 场景**默认拒绝**（外部客户端没有确认弹窗）：让用户去设置页改，
+或在设置 → AI 里打开 YOLO（审计照记 yolo=true）。
+令牌：设置键 agent.mcp.token；非空时要求 Authorization: Bearer <token>。
+`agent config` 直接给出 Claude Code {\"type\":\"http\",\"url\":…} 与 Cursor {\"url\":…} 的样例。",
+        ),
+        _ => None,
+    }
+}
diff --git a/crates/cli/src/cli/mod.rs b/crates/cli/src/cli/mod.rs
new file mode 100644
index 0000000..8f04c14
--- /dev/null
+++ b/crates/cli/src/cli/mod.rs
@@ -0,0 +1,109 @@
+//! 命令行解析（手写，不引 clap —— 子命令集小，省一棵依赖树）。
+//!
+//! 语法：`ull [全局选项] <命令> [子命令/参数]`。全局选项可以出现在任意位置
+//! （脚本里 `ull instances list --json` 与 `ull --json instances list` 等价）。
+//!
+//! 帮助与版本是「提前返回」的伪命令：`--help` / `-h` 出现在任何位置都立即给帮助，
+//! 有位置参数时按该主题给帮助。
+
+pub mod help;
+pub mod model;
+pub mod parse;
+pub mod program;
+
+pub use model::{
+    AccountsAddArgs, AccountsAddKind, AgentServeArgs, Command, ConfigGetArgs, ConfigSetArgs,
+    DiagArgs, Globals, InstallArgs, Invocation, LaunchArgs, LogsArgs, PackImportArgs,
+};
+pub use parse::parse;
+
+/// 这条命令行是 CLI 调用，还是「不该由 CLI 接管」（GUI 启动 / 只有全局选项）？
+///
+/// GUI 二进制（`unlucky-launcher` / `unlucky-launcher-iced`）用它做分发判据，`ull` 自己的
+/// `main` 不用——**判据只有这一处**，两个 GUI 各调一次，改语义不会漂。
+///
+/// 规则（刻意不列 GUI 的 flag 表：cli crate 不该知道 GUI 有什么参数）：
+///
+/// - 首个 token 是裸词（不以 `-` 开头）→ 一定在子命令位置（GUI 不接受位置参数，`--diff` /
+///   `--screenshot` 的取值都排在 flag 之后）→ 接管。未知子命令也在这里，由 CLI 自己报错。
+/// - 首个 token 是 flag → 只有当 [`parse`] 解析出一条**真命令**时才算 CLI 调用：`--help` /
+///   `--version` / `--json instances list` 接管；`--data-dir X` 解析成 [`Command::Welcome`]
+///   （没有子命令）、GUI 专属参数（`--screenshot` / `--renderer` / `--diff` …）根本解析失败，
+///   两种情况都不接管。**「解析失败」必须留在调用方**：`--screenshot out.png` 也会让本解析器
+///   报错，把它判成 CLI 就会让 GUI 的截图通道失效。
+#[must_use]
+pub fn looks_like_cli(args: &[String]) -> bool {
+    match args.first() {
+        None => false,
+        Some(first) if !first.starts_with('-') => true,
+        Some(_) => match parse(args) {
+            Ok(invocation) => !matches!(invocation.command, Command::Welcome),
+            Err(_) => false,
+        },
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::looks_like_cli;
+
+    fn cli(args: &[&str]) -> bool {
+        looks_like_cli(&args.iter().map(|arg| (*arg).to_owned()).collect::<Vec<_>>())
+    }
+
+    #[test]
+    fn no_args_is_not_a_cli_call() {
+        assert!(!cli(&[]));
+    }
+
+    #[test]
+    fn gui_flags_are_never_taken_over() {
+        // CI 与验收脚本在用这些参数，一条都不能被当成子命令吃掉。
+        assert!(!cli(&["--software-renderer"]));
+        assert!(!cli(&["--screenshot", "out.png", "--data-dir", "/d/tmp/x"]));
+        assert!(!cli(&["--screenshot-theme", "dark"]));
+        assert!(!cli(&["--renderer=gpu", "--theme=dark"]));
+        assert!(!cli(&["--scale-factor", "1.0"]));
+        assert!(!cli(&["--force-state", "hover"]));
+        assert!(!cli(&["--diff", "a.png", "b.png"]));
+        assert!(!cli(&["--mock"]));
+        // 只有 --data-dir 时解析成 Welcome（没有子命令），仍是 GUI 启动。
+        assert!(!cli(&["--data-dir", "/d/tmp/x"]));
+    }
+
+    #[test]
+    fn known_subcommands_are_taken_over() {
+        for args in [
+            vec!["instances", "list"],
+            vec!["install", "1.20.1", "--dry-run"],
+            vec!["launch", "1.20.1", "--dry-run"],
+            vec!["accounts", "list"],
+            vec!["sessions", "list"],
+            vec!["logs", "abc", "--tail", "10"],
+            vec!["diag", "abc"],
+            vec!["config", "get"],
+            vec!["java", "list"],
+            vec!["agent", "config"],
+            // 全局选项可以排在子命令前面
+            vec!["--json", "instances", "list"],
+        ] {
+            assert!(cli(&args), "{args:?} 应该交给 CLI");
+        }
+    }
+
+    #[test]
+    fn help_and_version_are_taken_over() {
+        assert!(cli(&["--version"]));
+        assert!(cli(&["--help"]));
+        assert!(cli(&["-h"]));
+        assert!(cli(&["-V"]));
+    }
+
+    #[test]
+    fn unknown_subcommands_are_left_to_the_cli_to_reject() {
+        // 语义定案（README 两版同款）：未知子命令 → CLI 报「未知命令 + <名字> --help」并以 1 退出，
+        // 不静默落到 GUI（否则脚本用户会以为参数生效了）。
+        assert!(cli(&["lst"]));
+        assert!(cli(&["intsances", "list"]));
+    }
+}
diff --git a/crates/cli/src/cli/model.rs b/crates/cli/src/cli/model.rs
new file mode 100644
index 0000000..19f5fd0
--- /dev/null
+++ b/crates/cli/src/cli/model.rs
@@ -0,0 +1,213 @@
+//! 命令模型（纯数据）：解析结果就是这里的一个 [`Invocation`]。
+
+use std::path::PathBuf;
+
+/// 全局选项（所有命令共享）。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct Globals {
+    /// `--json`：机器可读输出。
+    pub json: bool,
+    /// `--no-color`：关闭颜色。v1 输出本身不含 ANSI，参数保留以兼容脚本。
+    pub no_color: bool,
+    /// `--quiet`：静默人类可读输出（错误仍进 stderr）。
+    pub quiet: bool,
+    /// `--data-dir <dir>`：覆盖数据根（等价 custom 模式的 `custom_root`）。
+    pub data_dir: Option<PathBuf>,
+}
+
+/// 一条命令。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Command {
+    /// 无子命令：版本摘要 + 帮助（用户原话「无子命令时 --version + --help」）。
+    Welcome,
+    /// 只打印版本 + 系统摘要。
+    Version,
+    /// 帮助（`Some(topic)` 给该子命令的帮助）。
+    Help(Option<String>),
+    /// `instances list`。
+    InstancesList,
+    /// `install <version> [--loader X] [--name N]`。
+    Install(InstallArgs),
+    /// `pack import <file> [--target <dir>] [--name N] [--overwrite] [--no-register]`。
+    PackImport(PackImportArgs),
+    /// `launch <instance> [--dry-run]`。
+    Launch(LaunchArgs),
+    /// `sessions list [--limit N]`。
+    SessionsList {
+        /// 最多返回几条。
+        limit: usize,
+    },
+    /// `logs <sid> [--tail N]`。
+    Logs(LogsArgs),
+    /// `diag <sid>`。
+    Diag(DiagArgs),
+    /// `config get [<key>]`。
+    ConfigGet(ConfigGetArgs),
+    /// `config set <key> <value>`。
+    ConfigSet(ConfigSetArgs),
+    /// `java list`。
+    JavaList,
+    /// `java install <major> [--vendor X]`。
+    JavaInstall {
+        /// 目标 JDK 主版本（8 / 17 / 21）。
+        major: u32,
+        /// 钉死的发行版（缺省走 D23 的回退链）。
+        vendor: Option<unlucky_core::game::java::JdkVendor>,
+    },
+    /// `java vendors`：列出各发行版的可用性 / 镜像 / 当前优先级。
+    JavaVendors,
+    /// `accounts list`。
+    AccountsList,
+    /// `accounts add <kind> [<name>]`。
+    AccountsAdd(AccountsAddArgs),
+    /// `accounts remove <name>`。
+    AccountsRemove {
+        /// 账户名（或条目 id）。
+        name: String,
+    },
+    /// `agent serve`：对外 MCP server（长驻）。
+    AgentServe(AgentServeArgs),
+    /// `agent config`：打印 Claude Code / Cursor 的客户端配置样例。
+    AgentConfig {
+        /// 覆盖端点端口（默认取设置键 `agent.mcp.port`）。
+        port: Option<u16>,
+    },
+}
+
+/// `agent serve` 的参数（命令行只做覆盖，默认值来自设置键 `agent.mcp.*`）。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct AgentServeArgs {
+    /// 走 stdio 形态（llama.cpp 内置 MCP client 用）；缺省是 Streamable HTTP。
+    pub stdio: bool,
+    /// 覆盖端口。
+    pub port: Option<u16>,
+    /// 覆盖监听地址（只接受回环地址，非回环会被 server 拒绝）。
+    pub host: Option<String>,
+    /// 本次运行放开写工具（仍需设置键 `agent.mcp.allow_write` 或本 flag 之一）。
+    pub allow_write: bool,
+}
+
+/// `accounts add` 的轨道。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AccountsAddKind {
+    /// 离线（`add offline <name>`）。
+    Offline,
+    /// 微软 device-code（`add msa`，交互式）。
+    Microsoft,
+}
+
+impl AccountsAddKind {
+    /// 稳定名（帮助文案与 JSON 输出用）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Offline => "offline",
+            Self::Microsoft => "msa",
+        }
+    }
+}
+
+/// `accounts add` 的参数。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountsAddArgs {
+    /// 轨道。
+    pub kind: AccountsAddKind,
+    /// 离线轨的玩家名（微软轨不需要）。
+    pub name: Option<String>,
+}
+
+/// `install` 的参数。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct InstallArgs {
+    /// 目标版本 id（`1.20.1` / `1.20.1-forge-47.2.0`）。
+    pub version: String,
+    /// 加载器（`vanilla` 缺省 / `fabric` / `quilt` / `neoforge` / `forge`）。
+    pub loader: Option<String>,
+    /// 加载器版本（缺省取官方默认：Fabric 系首个稳定版，maven 系该原版下最新）。
+    pub loader_version: Option<String>,
+    /// 实例显示名（缺省用版本 id）。
+    pub name: Option<String>,
+    /// 只出安装计划（列清单 + 总大小 + 源选择），不下载、不登记。
+    pub dry_run: bool,
+    /// 是否往 stderr 打实时进度（`--quiet` 下关掉）。
+    pub progress: bool,
+    /// 实时进度用 JSONL 形态（`--json` 时开，stderr 一行一条，stdout 仍是单个信封）。
+    pub json_progress: bool,
+}
+
+/// `pack import` 的参数（M111）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PackImportArgs {
+    /// 整合包路径：`.zip` / `.mrpack` / MultiMC 实例目录。
+    pub path: PathBuf,
+    /// 目标实例目录（缺省 = 数据根的共享游戏目录 `game_home`）。
+    pub target: Option<PathBuf>,
+    /// 实例显示名（缺省 = 包名）。
+    pub name: Option<String>,
+    /// 冲突时用包内内容覆盖（缺省保留用户文件）。
+    pub overwrite: bool,
+    /// 不登记实例（只落内容）。
+    pub no_register: bool,
+}
+
+/// `launch` 的参数。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LaunchArgs {
+    /// 实例 id 或实例名；也可以直接给版本 id。
+    pub instance: String,
+    /// 只组装命令行，不 spawn（D18 的 `--dry-run`）。
+    pub dry_run: bool,
+    /// Java 可执行文件覆盖。
+    pub java: Option<PathBuf>,
+    /// 离线账户名（缺省 `Player`）。
+    pub username: Option<String>,
+    /// 账户名（`accounts` 里的玩家名或条目 id）；缺省用唯一账户。
+    pub account: Option<String>,
+    /// 最大堆（MB）。
+    pub max_memory: Option<u32>,
+}
+
+/// `logs` 的参数。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LogsArgs {
+    /// 会话 id（允许唯一前缀）。
+    pub session_id: String,
+    /// 只打印末尾 N 条事件（缺省 200）。
+    pub tail: usize,
+}
+
+/// `diag` 的参数。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DiagArgs {
+    /// 会话 id（允许唯一前缀）。
+    pub session_id: String,
+    /// 送入规则引擎的日志行上限（缺省 2000）。
+    pub tail: usize,
+}
+
+/// `config get` 的参数。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ConfigGetArgs {
+    /// 点分键路径；`None` 表示整份生效配置。
+    pub key: Option<String>,
+    /// 敏感键也输出明文（默认脱敏）。
+    pub show_secret: bool,
+}
+
+/// `config set` 的参数。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ConfigSetArgs {
+    /// 点分键路径。
+    pub key: String,
+    /// 值的原始文本（先按 JSON 解析，失败按字符串）。
+    pub value: String,
+}
+
+/// 一次调用的完整输入。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Invocation {
+    /// 全局选项。
+    pub globals: Globals,
+    /// 要执行的命令。
+    pub command: Command,
+}
diff --git a/crates/cli/src/cli/parse.rs b/crates/cli/src/cli/parse.rs
new file mode 100644
index 0000000..7280b77
--- /dev/null
+++ b/crates/cli/src/cli/parse.rs
@@ -0,0 +1,393 @@
+//! 手写解析器：全局选项 → 子命令 → 子命令内的选项。
+
+use std::collections::BTreeMap;
+use std::path::PathBuf;
+
+use unlucky_core::game::java::JdkVendor;
+
+use crate::error::CliError;
+
+mod accounts;
+mod agent;
+
+use super::model::{
+    Command, ConfigGetArgs, ConfigSetArgs, DiagArgs, Globals, InstallArgs, Invocation, LaunchArgs,
+    LogsArgs, PackImportArgs,
+};
+
+/// `logs` 缺省尾巴行数。
+const DEFAULT_LOG_TAIL: usize = 200;
+/// `diag` 缺省送入规则引擎的行数。
+const DEFAULT_DIAG_TAIL: usize = 2000;
+/// `sessions list` 缺省条数。
+const DEFAULT_SESSION_LIMIT: usize = 20;
+
+/// 解析整条命令行（不含 argv[0]）。
+///
+/// # Errors
+///
+/// 用法错误（未知命令/选项、缺参数、数字解析失败）返回 [`CliError`]（退出码 1）。
+pub fn parse(args: &[String]) -> Result<Invocation, CliError> {
+    let mut globals = Globals::default();
+    let mut rest: Vec<String> = Vec::new();
+    let mut help_requested = false;
+    let mut version_requested = false;
+    let mut index = 0;
+
+    while index < args.len() {
+        let arg = args[index].as_str();
+        match arg {
+            "--json" => globals.json = true,
+            "--no-color" => globals.no_color = true,
+            "--quiet" | "-q" => globals.quiet = true,
+            // 帮助/版本是「伪命令」，但不提前返回：`--help` 出现在命令前面时，
+            // 主题要从后面收完的位置参数里取（`ull --help launch` 与 `ull launch --help` 等价）。
+            "--help" | "-h" => help_requested = true,
+            "--version" | "-V" => version_requested = true,
+            "--data-dir" => {
+                index += 1;
+                globals.data_dir = Some(PathBuf::from(take_value(args, index, "data-dir")?));
+            }
+            _ => match arg.strip_prefix("--data-dir=") {
+                Some(value) => globals.data_dir = Some(PathBuf::from(value)),
+                None => rest.push(arg.to_string()),
+            },
+        }
+        index += 1;
+    }
+
+    if help_requested {
+        return Ok(Invocation {
+            globals,
+            command: Command::Help(rest.first().cloned()),
+        });
+    }
+    if version_requested {
+        return Ok(Invocation {
+            globals,
+            command: Command::Version,
+        });
+    }
+
+    let command = parse_command(&rest, &globals)?;
+    Ok(Invocation { globals, command })
+}
+
+fn parse_command(rest: &[String], globals: &Globals) -> Result<Command, CliError> {
+    let Some(name) = rest.first() else {
+        return Ok(Command::Welcome);
+    };
+    let tail = &rest[1..];
+    match name.as_str() {
+        "version" => Ok(Command::Version),
+        "help" => Ok(Command::Help(tail.first().cloned())),
+        "instances" => parse_instances(tail),
+        "install" => parse_install(tail, globals),
+        "pack" => parse_pack(tail),
+        "launch" => parse_launch(tail),
+        "sessions" => parse_sessions(tail),
+        "logs" => parse_logs(tail),
+        "diag" => parse_diag(tail),
+        "config" => parse_config(tail),
+        "java" => parse_java(tail),
+        "accounts" => accounts::parse_accounts(tail),
+        "agent" => agent::parse_agent(tail),
+        other => {
+            Err(CliError::usage(format!("未知命令 `{other}`"))
+                .with_hint("%prog% --help 查看命令列表"))
+        }
+    }
+}
+
+fn parse_instances(tail: &[String]) -> Result<Command, CliError> {
+    let args = match tail.first().map(String::as_str) {
+        None | Some("list") => tail.get(1..).unwrap_or_default(),
+        Some(other) => {
+            return Err(CliError::usage(format!(
+                "instances 的子命令只有 list，收到 `{other}`"
+            )));
+        }
+    };
+    let parsed = parse_flags(args, &[], &[])?;
+    ensure_no_positionals(&parsed, "instances list")?;
+    Ok(Command::InstancesList)
+}
+
+fn parse_install(tail: &[String], globals: &Globals) -> Result<Command, CliError> {
+    let parsed = parse_flags(tail, &["loader", "loader-version", "name"], &["dry-run"])?;
+    let version = require_single_positional(&parsed, "install <version>")?;
+    Ok(Command::Install(InstallArgs {
+        version,
+        loader: parsed.value("loader"),
+        loader_version: parsed.value("loader-version"),
+        name: parsed.value("name"),
+        dry_run: parsed.has("dry-run"),
+        // 实时进度进 stderr：人类模式是文本行，`--json` 模式是 JSONL（stdout 保持干净），
+        // `--quiet` 一律不打。
+        progress: !globals.quiet,
+        json_progress: globals.json,
+    }))
+}
+
+/// `pack import <file> [--target <dir>] [--name N] [--overwrite] [--no-register]`。
+fn parse_pack(tail: &[String]) -> Result<Command, CliError> {
+    let Some(sub) = tail.first().map(String::as_str) else {
+        return Err(CliError::usage("pack 需要子命令 import")
+            .with_hint("%prog% pack import <file> [--target <dir>]"));
+    };
+    if sub != "import" {
+        return Err(CliError::usage(format!(
+            "pack 的子命令只有 import，收到 `{sub}`"
+        )));
+    }
+    let parsed = parse_flags(
+        tail.get(1..).unwrap_or_default(),
+        &["target", "name"],
+        &["overwrite", "no-register"],
+    )?;
+    let path = require_single_positional(&parsed, "pack import <file>")?;
+    Ok(Command::PackImport(PackImportArgs {
+        path: PathBuf::from(path),
+        target: parsed.value("target").map(PathBuf::from),
+        name: parsed.value("name"),
+        overwrite: parsed.has("overwrite"),
+        no_register: parsed.has("no-register"),
+    }))
+}
+
+fn parse_launch(tail: &[String]) -> Result<Command, CliError> {
+    let parsed = parse_flags(
+        tail,
+        &["java", "username", "account", "max-memory"],
+        &["dry-run"],
+    )?;
+    let instance = require_single_positional(&parsed, "launch <instance>")?;
+    let max_memory = match parsed.value("max-memory") {
+        Some(raw) => Some(
+            raw.parse::<u32>()
+                .map_err(|_| CliError::usage(format!("--max-memory 需要整数 MB，收到 `{raw}`")))?,
+        ),
+        None => None,
+    };
+    Ok(Command::Launch(LaunchArgs {
+        instance,
+        dry_run: parsed.has("dry-run"),
+        java: parsed.value("java").map(PathBuf::from),
+        username: parsed.value("username"),
+        account: parsed.value("account"),
+        max_memory,
+    }))
+}
+
+fn parse_sessions(tail: &[String]) -> Result<Command, CliError> {
+    let args = match tail.first().map(String::as_str) {
+        None | Some("list") => tail.get(1..).unwrap_or_default(),
+        Some(other) => {
+            return Err(CliError::usage(format!(
+                "sessions 的子命令只有 list，收到 `{other}`"
+            )));
+        }
+    };
+    let parsed = parse_flags(args, &["limit"], &[])?;
+    ensure_no_positionals(&parsed, "sessions list")?;
+    let limit = match parsed.value("limit") {
+        Some(raw) => raw
+            .parse::<usize>()
+            .map_err(|_| CliError::usage(format!("--limit 需要整数，收到 `{raw}`")))?,
+        None => DEFAULT_SESSION_LIMIT,
+    };
+    Ok(Command::SessionsList { limit })
+}
+
+fn parse_logs(tail: &[String]) -> Result<Command, CliError> {
+    let parsed = parse_flags(tail, &["tail"], &[])?;
+    let session_id = require_single_positional(&parsed, "logs <sid>")?;
+    let tail_lines = optional_count(&parsed, "tail", DEFAULT_LOG_TAIL)?;
+    Ok(Command::Logs(LogsArgs {
+        session_id,
+        tail: tail_lines,
+    }))
+}
+
+fn parse_diag(tail: &[String]) -> Result<Command, CliError> {
+    let parsed = parse_flags(tail, &["tail"], &[])?;
+    let session_id = require_single_positional(&parsed, "diag <sid>")?;
+    let tail_lines = optional_count(&parsed, "tail", DEFAULT_DIAG_TAIL)?;
+    Ok(Command::Diag(DiagArgs {
+        session_id,
+        tail: tail_lines,
+    }))
+}
+
+fn parse_config(tail: &[String]) -> Result<Command, CliError> {
+    let Some(sub) = tail.first().map(String::as_str) else {
+        return Err(CliError::usage("config 需要子命令 get|set")
+            .with_hint("%prog% config get <key> / %prog% config set <key> <value>"));
+    };
+    let rest = tail.get(1..).unwrap_or_default();
+    match sub {
+        "get" => {
+            let parsed = parse_flags(rest, &[], &["show-secret"])?;
+            if parsed.positionals.len() > 1 {
+                return Err(CliError::usage("config get 最多接受一个键路径"));
+            }
+            Ok(Command::ConfigGet(ConfigGetArgs {
+                key: parsed.positionals.first().cloned(),
+                show_secret: parsed.has("show-secret"),
+            }))
+        }
+        "set" => {
+            let parsed = parse_flags(rest, &[], &[])?;
+            if parsed.positionals.len() != 2 {
+                return Err(CliError::usage(
+                    "config set 需要键路径与值：%prog% config set <key> <value>",
+                ));
+            }
+            Ok(Command::ConfigSet(ConfigSetArgs {
+                key: parsed.positionals[0].clone(),
+                value: parsed.positionals[1].clone(),
+            }))
+        }
+        other => Err(CliError::usage(format!(
+            "config 的子命令只有 get|set，收到 `{other}`"
+        ))),
+    }
+}
+
+fn parse_java(tail: &[String]) -> Result<Command, CliError> {
+    match tail.first().map(String::as_str) {
+        None | Some("list") => {
+            ensure_no_extra(tail.get(1..).unwrap_or_default(), "java list")?;
+            Ok(Command::JavaList)
+        }
+        Some("vendors") => {
+            ensure_no_extra(tail.get(1..).unwrap_or_default(), "java vendors")?;
+            Ok(Command::JavaVendors)
+        }
+        Some("install") => {
+            let parsed = parse_flags(tail.get(1..).unwrap_or_default(), &["vendor"], &[])?;
+            let raw = require_single_positional(&parsed, "java install <major>")?;
+            let major = raw
+                .parse::<u32>()
+                .map_err(|_| CliError::usage(format!("JDK 主版本需要整数，收到 `{raw}`")))?;
+            let vendor = match parsed.value("vendor") {
+                Some(text) => Some(JdkVendor::parse(&text).ok_or_else(|| {
+                    CliError::usage(format!(
+                        "--vendor 只有 temurin|oracle|microsoft|zulu，收到 `{text}`"
+                    ))
+                })?),
+                None => None,
+            };
+            Ok(Command::JavaInstall { major, vendor })
+        }
+        Some(other) => Err(CliError::usage(format!(
+            "java 的子命令只有 list|install|vendors，收到 `{other}`"
+        ))),
+    }
+}
+
+/// 单个位置参数（多一个少一个都算用法错误）。
+fn require_single_positional(parsed: &ParsedArgs, usage: &str) -> Result<String, CliError> {
+    match parsed.positionals.as_slice() {
+        [only] => Ok(only.clone()),
+        [] => Err(CliError::usage(format!("缺少参数：%prog% {usage}"))),
+        _ => Err(CliError::usage(format!("参数过多：%prog% {usage}"))),
+    }
+}
+
+fn optional_count(parsed: &ParsedArgs, name: &str, default: usize) -> Result<usize, CliError> {
+    match parsed.value(name) {
+        Some(raw) => raw
+            .parse::<usize>()
+            .map_err(|_| CliError::usage(format!("--{name} 需要整数，收到 `{raw}`"))),
+        None => Ok(default),
+    }
+}
+
+fn ensure_no_extra(args: &[String], usage: &str) -> Result<(), CliError> {
+    if args.is_empty() {
+        Ok(())
+    } else {
+        Err(CliError::usage(format!(
+            "{usage} 不接受参数：{}",
+            args.join(" ")
+        )))
+    }
+}
+
+fn ensure_no_positionals(parsed: &ParsedArgs, usage: &str) -> Result<(), CliError> {
+    ensure_no_extra(&parsed.positionals, usage)
+}
+
+/// 解析后的一条子命令参数。
+struct ParsedArgs {
+    positionals: Vec<String>,
+    flags: BTreeMap<String, Option<String>>,
+}
+
+impl ParsedArgs {
+    fn value(&self, name: &str) -> Option<String> {
+        self.flags.get(name).cloned().flatten()
+    }
+
+    fn has(&self, name: &str) -> bool {
+        self.flags.contains_key(name)
+    }
+}
+
+/// 取值形 flag 的下一 token。
+///
+/// 下一个 token 若以 `--` 开头，说明用户漏了值（`ull launch x --java --dry-run`），
+/// 此时报用法错误，而不是把 flag 当值吞掉后在下游报出费解的「找不到 Java」。
+/// 负数（`-1`）不以 `--` 开头，不会被误伤。
+fn take_value(args: &[String], index: usize, name: &str) -> Result<String, CliError> {
+    let value = args
+        .get(index)
+        .ok_or_else(|| CliError::usage(format!("--{name} 需要一个值")))?;
+    if value.starts_with("--") {
+        return Err(CliError::usage(format!(
+            "--{name} 需要一个值，但收到选项 `{value}`"
+        )));
+    }
+    Ok(value.clone())
+}
+
+/// `--flag` / `--flag=value` / `--flag value` + 位置参数。
+fn parse_flags(args: &[String], valued: &[&str], flags: &[&str]) -> Result<ParsedArgs, CliError> {
+    let mut parsed = ParsedArgs {
+        positionals: Vec::new(),
+        flags: BTreeMap::new(),
+    };
+    let mut index = 0;
+    while index < args.len() {
+        let arg = &args[index];
+        let Some(body) = arg.strip_prefix("--") else {
+            parsed.positionals.push(arg.clone());
+            index += 1;
+            continue;
+        };
+        let (name, inline) = match body.split_once('=') {
+            Some((name, value)) => (name, Some(value.to_string())),
+            None => (body, None),
+        };
+        if valued.contains(&name) {
+            let value = match inline {
+                Some(value) => value,
+                None => {
+                    index += 1;
+                    take_value(args, index, name)?
+                }
+            };
+            parsed.flags.insert(name.to_string(), Some(value));
+        } else if flags.contains(&name) {
+            if inline.is_some() {
+                return Err(CliError::usage(format!("--{name} 不接受值")));
+            }
+            parsed.flags.insert(name.to_string(), None);
+        } else {
+            return Err(CliError::usage(format!("未知选项 --{name}")));
+        }
+        index += 1;
+    }
+    Ok(parsed)
+}
diff --git a/crates/cli/src/cli/parse/accounts.rs b/crates/cli/src/cli/parse/accounts.rs
new file mode 100644
index 0000000..b8f7389
--- /dev/null
+++ b/crates/cli/src/cli/parse/accounts.rs
@@ -0,0 +1,68 @@
+//! `ull accounts` 子命令的解析（从 `parse.rs` 拆出，避免解析器主文件顶到 400 行）。
+//!
+//! 语法：
+//! - `ull accounts [list]`
+//! - `ull accounts add offline <name>`
+//! - `ull accounts add msa`（别名 `microsoft`）
+//! - `ull accounts remove <name>`（别名 `rm`）
+//!
+//! 只开这三条轨道入口：authlib 的密码登录不走 CLI（密码进 argv 会泄露，见
+//! `DevDocs/SubAgentsTalk/auth-接口约定.md` §4）。
+
+use super::{ensure_no_positionals, parse_flags, require_single_positional};
+use crate::cli::model::{AccountsAddArgs, AccountsAddKind, Command};
+use crate::error::CliError;
+
+/// 解析 `accounts ...`。
+pub(super) fn parse_accounts(tail: &[String]) -> Result<Command, CliError> {
+    let Some(sub) = tail.first().map(String::as_str) else {
+        return Ok(Command::AccountsList);
+    };
+    let rest = tail.get(1..).unwrap_or_default();
+    match sub {
+        "list" => {
+            let parsed = parse_flags(rest, &[], &[])?;
+            ensure_no_positionals(&parsed, "accounts list")?;
+            Ok(Command::AccountsList)
+        }
+        "add" => parse_add(rest),
+        "remove" | "rm" => {
+            let parsed = parse_flags(rest, &[], &[])?;
+            let name = require_single_positional(&parsed, "accounts remove <name>")?;
+            Ok(Command::AccountsRemove { name })
+        }
+        other => Err(CliError::usage(format!(
+            "accounts 的子命令只有 list|add|remove，收到 `{other}`"
+        ))),
+    }
+}
+
+fn parse_add(rest: &[String]) -> Result<Command, CliError> {
+    let Some(kind) = rest.first().map(String::as_str) else {
+        return Err(
+            CliError::usage("accounts add 需要轨道：offline|msa").with_hint(
+                "%prog% accounts add offline <玩家名> / %prog% accounts add msa（设备码交互式登录）",
+            ),
+        );
+    };
+    let parsed = parse_flags(rest.get(1..).unwrap_or_default(), &[], &[])?;
+    match kind {
+        "offline" => {
+            let name = require_single_positional(&parsed, "accounts add offline <name>")?;
+            Ok(Command::AccountsAdd(AccountsAddArgs {
+                kind: AccountsAddKind::Offline,
+                name: Some(name),
+            }))
+        }
+        "msa" | "microsoft" => {
+            ensure_no_positionals(&parsed, "accounts add msa")?;
+            Ok(Command::AccountsAdd(AccountsAddArgs {
+                kind: AccountsAddKind::Microsoft,
+                name: None,
+            }))
+        }
+        other => Err(CliError::usage(format!(
+            "accounts add 的轨道只有 offline|msa，收到 `{other}`"
+        ))),
+    }
+}
diff --git a/crates/cli/src/cli/parse/agent.rs b/crates/cli/src/cli/parse/agent.rs
new file mode 100644
index 0000000..ef39915
--- /dev/null
+++ b/crates/cli/src/cli/parse/agent.rs
@@ -0,0 +1,66 @@
+//! `agent` 子命令解析（`serve` / `config`）。
+//!
+//! 与 `parse::accounts` 同样的拆分理由：`parse.rs` 挨着 400 行硬上限，
+//! 而且「MCP server 的参数」本来就是一撮独立的东西，混在主解析器里迟早长成一片。
+
+use crate::cli::model::{AgentServeArgs, Command};
+use crate::cli::parse::ParsedArgs;
+use crate::error::CliError;
+
+use super::{ensure_no_positionals, parse_flags};
+
+/// 解析 `ull agent <sub>`。
+///
+/// # Errors
+/// 缺子命令、未知子命令、未知选项、端口不是 1~65535 时返回用法错误。
+pub fn parse_agent(tail: &[String]) -> Result<Command, CliError> {
+    let Some(sub) = tail.first().map(String::as_str) else {
+        return Err(CliError::usage("agent 需要子命令 serve|config")
+            .with_hint("%prog% agent serve / %prog% agent config"));
+    };
+    let rest = tail.get(1..).unwrap_or_default();
+    match sub {
+        "serve" => parse_serve(rest),
+        "config" => parse_config(rest),
+        other => Err(CliError::usage(format!(
+            "agent 的子命令只有 serve|config，收到 `{other}`"
+        ))),
+    }
+}
+
+fn parse_serve(rest: &[String]) -> Result<Command, CliError> {
+    let parsed = parse_flags(
+        rest,
+        &["port", "host"],
+        &["stdio", "allow-write", "readonly"],
+    )?;
+    ensure_no_positionals(&parsed, "agent serve")?;
+    if parsed.has("allow-write") && parsed.has("readonly") {
+        return Err(CliError::usage(
+            "--allow-write 与 --readonly 不能同时给（二选一）",
+        ));
+    }
+    Ok(Command::AgentServe(AgentServeArgs {
+        stdio: parsed.has("stdio"),
+        port: optional_port(&parsed)?,
+        host: parsed.value("host"),
+        allow_write: parsed.has("allow-write"),
+    }))
+}
+
+fn parse_config(rest: &[String]) -> Result<Command, CliError> {
+    let parsed = parse_flags(rest, &["port"], &[])?;
+    ensure_no_positionals(&parsed, "agent config")?;
+    Ok(Command::AgentConfig {
+        port: optional_port(&parsed)?,
+    })
+}
+
+fn optional_port(parsed: &ParsedArgs) -> Result<Option<u16>, CliError> {
+    match parsed.value("port") {
+        Some(raw) => Ok(Some(raw.parse::<u16>().map_err(|_| {
+            CliError::usage(format!("--port 需要 1~65535，收到 `{raw}`"))
+        })?)),
+        None => Ok(None),
+    }
+}
diff --git a/crates/cli/src/cli/program.rs b/crates/cli/src/cli/program.rs
new file mode 100644
index 0000000..d6f6d5c
--- /dev/null
+++ b/crates/cli/src/cli/program.rs
@@ -0,0 +1,120 @@
+//! 程序名：CLI 输出里自称什么，取决于**被调用的那个二进制**叫什么。
+//!
+//! GUI 二进制（`unlucky-launcher`）与 `ull` 共用同一套命令行（M82），所以 banner / 用法行 /
+//! 「`<名字> --help`」这类提示不能写死 `ull` —— 用户敲的是 `unlucky-launcher`，把他指去敲
+//! 一个可能不存在的名字只会让人困惑。
+//!
+//! 做法（M82 r2 定案）：文案里放**占位符**，渲染时替换；**绝不对插值后的整条文本做词替换**。
+//! 上一版按「独立词 `ull`」替换整条消息，于是用户数据被改坏过：账户名叫 `ull` 的会变成
+//! `unlucky-launcher`，路径 `D:/tmp/ull/.ULL` 会变成 `D:/tmp/unlucky-launcher/.ULL`。
+//! 占位符只在模板里出现，插值进来的用户名/路径碰不到它。
+//!
+//! 取不到 argv[0]（某些 exec 场景）就回落 [`FALLBACK`]，输出因此与老版本逐字相同。
+
+/// 文案里的程序名占位符。
+///
+/// 用 `%prog%` 而不是 `{prog}`：这些模板要活在 `format!` 里，`{prog}` 会被 `format!` 当成
+/// 参数名直接编译失败，而 `%prog%` 原样穿过去，到渲染时才替换。
+pub const PLACEHOLDER: &str = "%prog%";
+
+/// 取不到 argv[0] 时的回落名（也是 `crates/cli` 产出的那个 bin）。
+pub const FALLBACK: &str = "ull";
+
+/// 从 argv[0] 求程序名：剥目录、剥 `.exe`、空值回落。
+///
+/// Windows 上是 `C:\…\unlucky-launcher.exe`，unix 上是 `./target/release/unlucky-launcher`，
+/// 两种都要得到 `unlucky-launcher`。
+#[must_use]
+pub fn name_in(argv0: Option<&str>) -> String {
+    let Some(raw) = argv0 else {
+        return FALLBACK.to_owned();
+    };
+    let base = raw.rsplit(['/', '\\']).next().unwrap_or(raw);
+    let base = strip_exe(base);
+    if base.is_empty() {
+        FALLBACK.to_owned()
+    } else {
+        base.to_owned()
+    }
+}
+
+fn strip_exe(name: &str) -> &str {
+    match name
+        .strip_suffix(".exe")
+        .or_else(|| name.strip_suffix(".EXE"))
+    {
+        Some(stem) => stem,
+        None => name,
+    }
+}
+
+/// 当前进程的程序名。
+#[must_use]
+pub fn name() -> String {
+    let argv0 = std::env::args_os()
+        .next()
+        .map(|arg| arg.to_string_lossy().into_owned());
+    name_in(argv0.as_deref())
+}
+
+/// 把模板里的 [`PLACEHOLDER`] 换成程序名。
+///
+/// **只认占位符**：文本里其它位置的 `ull`（账户名、路径段、回显的子命令）原样保留——这是
+/// 与「按词替换整条文本」的分界线，也是本函数唯一要保证的事。
+#[must_use]
+pub fn fill(text: &str) -> String {
+    if !text.contains(PLACEHOLDER) {
+        return text.to_owned();
+    }
+    text.replace(PLACEHOLDER, &name())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{fill, name_in, FALLBACK, PLACEHOLDER};
+
+    #[test]
+    fn argv0_is_reduced_to_a_bare_name() {
+        assert_eq!(
+            name_in(Some(r"C:\Program Files\ULL\unlucky-launcher.exe")),
+            "unlucky-launcher"
+        );
+        assert_eq!(
+            name_in(Some("./target/release/unlucky-launcher")),
+            "unlucky-launcher"
+        );
+        assert_eq!(name_in(Some("ull")), "ull");
+        assert_eq!(name_in(Some("/usr/local/bin/ull.exe")), "ull");
+    }
+
+    #[test]
+    fn empty_or_missing_argv0_falls_back() {
+        assert_eq!(name_in(None), FALLBACK);
+        assert_eq!(name_in(Some("")), FALLBACK);
+        assert_eq!(name_in(Some("/usr/bin/")), FALLBACK);
+    }
+
+    #[test]
+    fn fill_replaces_only_the_placeholder() {
+        assert_eq!(
+            fill(&format!("{PLACEHOLDER} --help 查看命令列表")),
+            format!("{} --help 查看命令列表", super::name())
+        );
+        // 没有占位符就原样返回（不碰任何词）。
+        assert_eq!(fill("ull --help"), "ull --help");
+    }
+
+    #[test]
+    fn user_data_that_says_ull_is_never_rewritten() {
+        // 回归：账户名恰好是 `ull` / 路径里有 `\ull\` / 回显的子命令是 `ull`，
+        // 一个字节都不能被改成程序名（M82 r1 的真缺陷）。
+        for text in [
+            "找不到账户 `ull`",
+            r"索引文件：D:/tmp/ull\.ULL\data\agent\sessions\index.jsonl",
+            "未知命令 `ull`",
+            "过滤词 null 与 pull 也不算",
+        ] {
+            assert_eq!(fill(text), text, "{text} 被改了");
+        }
+    }
+}
diff --git a/crates/cli/src/commands/accounts.rs b/crates/cli/src/commands/accounts.rs
new file mode 100644
index 0000000..b4fffe0
--- /dev/null
+++ b/crates/cli/src/commands/accounts.rs
@@ -0,0 +1,198 @@
+//! `ull accounts list|add|remove`：账户元数据操作，**凭据永不打印**。
+//!
+//! 设计约束（D9/Q21 + D4 凭据红线）：
+//! - 只开四条路径：`list` / `add offline <name>` / `add msa` / `remove <name>`；
+//!   authlib 的密码登录**故意不开 CLI 通道**（密码进 argv 会直接进 shell 历史与
+//!   `ps` 输出，破坏红线；留给 GUI 输入框）；
+//! - 输出只经 `AccountMeta`（可公开字段），`Report`/`--json` 里没有任何 token 字段；
+//! - device-code 的 `user_code`/URL 打到 **stderr**（不管 `--quiet` 都要打：不打用户没法完成登录）。
+
+use serde_json::json;
+use unlucky_core::auth::account::{AccountKind, AccountMeta, Credentials};
+use unlucky_core::auth::microsoft::{now_ms, MicrosoftAuth};
+use unlucky_core::auth::offline::offline_meta;
+use unlucky_core::auth::{AccountStore, AuthJournal};
+
+use crate::cli::{AccountsAddArgs, AccountsAddKind};
+use crate::context::Ctx;
+use crate::error::CliError;
+use crate::output::{progress_line, Report};
+
+/// `accounts list`：列出账户（名称/轨道/UUID/创建时间）。
+///
+/// # Errors
+///
+/// 数据根解析失败（在 `Ctx`）或读盘 IO 失败。
+pub fn list(ctx: &Ctx) -> Result<Report, CliError> {
+    let store = open_store(ctx);
+    let mut human = Vec::new();
+    if store.is_empty() {
+        human.push("还没有账户。".to_string());
+        human.push("  离线：%prog% accounts add offline <玩家名>".to_string());
+        human.push("  微软：%prog% accounts add msa（设备码交互式登录）".to_string());
+    } else {
+        human.push(format!("账户（{} 个）：", store.accounts().len()));
+        for meta in store.accounts() {
+            human.push(format!(
+                "  {} · {} · {}",
+                meta.display_name(),
+                meta.kind.label(),
+                meta.profile_id
+            ));
+        }
+    }
+    for warning in store.warnings() {
+        human.push(format!("提示: {warning}"));
+    }
+    let accounts: Vec<serde_json::Value> = store.accounts().iter().map(account_json).collect();
+    let data = json!({
+        "accounts": accounts,
+        "count": accounts.len(),
+        "auth_dir": store.paths().root().display().to_string(),
+        "warnings": store.warnings(),
+    });
+    Ok(Report::new(data, human))
+}
+
+/// `accounts add offline <name>`。
+///
+/// # Errors
+///
+/// 名字不合法、同名账户已存在、落盘失败。
+pub fn add(ctx: &Ctx, args: &AccountsAddArgs) -> Result<Report, CliError> {
+    match args.kind {
+        AccountsAddKind::Offline => add_offline(ctx, args.name.as_deref().unwrap_or_default()),
+        AccountsAddKind::Microsoft => add_microsoft(ctx),
+    }
+}
+
+fn add_offline(ctx: &Ctx, name: &str) -> Result<Report, CliError> {
+    let meta = offline_meta(name, now_ms()).map_err(super::map_auth_error)?;
+    let mut store = open_store(ctx);
+    store
+        .insert(meta.clone(), Credentials::Offline)
+        .map_err(super::map_auth_error)?;
+    store.save().map_err(super::map_auth_error)?;
+    let human = vec![
+        format!(
+            "已添加离线账户 {}（HMCL 兼容 UUID {}）",
+            meta.display_name(),
+            meta.profile_id
+        ),
+        format!("账户文件：{}", store.paths().accounts_file().display()),
+    ];
+    Ok(Report::new(added_json(&meta), human))
+}
+
+/// `accounts add msa`：device-code 交互式登录。
+fn add_microsoft(ctx: &Ctx) -> Result<Report, CliError> {
+    // 失败日志落**本次命令的实际数据根**（`ctx.layout().logs()`）：`MicrosoftAuth::from_env()`
+    // 默认挂的是便携根（exe 同级 `.ULL/logs`），`--data-dir` / launcher.json 的 standard 模式下
+    // 那是别人的目录，排障时找不到 auth.jsonl（M38 遗留 finding）。
+    let auth = MicrosoftAuth::from_env()
+        .map_err(super::map_auth_error)?
+        .with_journal(Some(AuthJournal::in_logs_dir(ctx.layout().logs())));
+    // 设备码要先给用户看，再开始等：core 的 `present` 回调正好卡在这个时间点。
+    let session = unlucky_core::download::blocking::block_on(auth.device_code_login(|prompt| {
+        let (headline, code) = prompt.lines();
+        progress_line(&headline);
+        progress_line(&code);
+    }))
+    .map_err(super::map_auth_error)?;
+
+    let meta = AccountMeta::new(
+        AccountKind::Microsoft,
+        session.profile_id.clone(),
+        session.profile_name.clone(),
+        now_ms(),
+    );
+    let mut store = open_store(ctx);
+    store
+        .insert(meta.clone(), Credentials::Microsoft(session))
+        .map_err(super::map_auth_error)?;
+    store.save().map_err(super::map_auth_error)?;
+    let human = vec![
+        format!(
+            "已添加微软账户 {}（档案 UUID {}）",
+            meta.display_name(),
+            meta.profile_id
+        ),
+        format!("账户文件：{}", store.paths().accounts_file().display()),
+    ];
+    Ok(Report::new(added_json(&meta), human))
+}
+
+/// `accounts remove <name>`。
+///
+/// # Errors
+///
+/// 找不到该账户、落盘失败。
+pub fn remove(ctx: &Ctx, name: &str) -> Result<Report, CliError> {
+    let mut store = open_store(ctx);
+    let meta = store.remove(name).map_err(super::map_auth_error)?;
+    store.save().map_err(super::map_auth_error)?;
+    let human = vec![format!(
+        "已删除账户 {}（{}）",
+        meta.display_name(),
+        meta.kind.label()
+    )];
+    let data = json!({
+        "removed": account_json(&meta),
+        "count": store.accounts().len(),
+    });
+    Ok(Report::new(data, human))
+}
+
+fn open_store(ctx: &Ctx) -> AccountStore {
+    AccountStore::open(ctx.auth_data())
+}
+
+fn added_json(meta: &AccountMeta) -> serde_json::Value {
+    json!({
+        "account": account_json(meta),
+        "account_id": meta.id.as_str(),
+    })
+}
+
+/// 账户元数据 → JSON（**只含可公开字段**）。
+fn account_json(meta: &AccountMeta) -> serde_json::Value {
+    json!({
+        "name": meta.display_name(),
+        "profile_name": meta.profile_name,
+        "id": meta.id.as_str(),
+        "kind": meta.kind.as_str(),
+        "profile_id": meta.profile_id,
+        "login_name": meta.login_name,
+        "server_url": meta.server_url,
+        "created_at_ms": meta.created_at_ms,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::account_json;
+    use unlucky_core::auth::account::{AccountKind, AccountMeta};
+
+    #[test]
+    fn account_json_has_no_credential_fields() {
+        let mut meta = AccountMeta::new(
+            AccountKind::Microsoft,
+            "0f8fad5bd9cb469fa16570867728950e",
+            "Steve",
+            7,
+        );
+        meta.login_name = Some("me@example.com".to_string());
+        let value = account_json(&meta);
+        let keys: Vec<&str> = value
+            .as_object()
+            .expect("对象")
+            .keys()
+            .map(String::as_str)
+            .collect();
+        for forbidden in ["access_token", "refresh_token", "token", "password"] {
+            assert!(!keys.contains(&forbidden), "不该出现 {forbidden}");
+        }
+        assert_eq!(value["name"], "Steve");
+        assert_eq!(value["kind"], "microsoft");
+    }
+}
diff --git a/crates/cli/src/commands/agent/mod.rs b/crates/cli/src/commands/agent/mod.rs
new file mode 100644
index 0000000..06088e7
--- /dev/null
+++ b/crates/cli/src/commands/agent/mod.rs
@@ -0,0 +1,135 @@
+//! `ull agent`：对外 MCP server 的 headless 入口（02 文档 §1 的第二形态）。
+//!
+//! 两个子命令：
+//! - `agent serve`：长驻服务（`--stdio` 或 Streamable HTTP on 127.0.0.1）；
+//! - `agent config`：打印 Claude Code / Cursor 的配置样例（含当前端口与令牌状态）。
+//!
+//! 为什么 `serve` 不能走 `commands::run` 的「返回 Report 再打印」套路：stdio 形态下
+//! **stdout 就是 JSON-RPC 流**，任何一行多余输出都会让客户端解析失败。所以 runner
+//! 里对 `Command::AgentServe` 提前分流，不走 `output::print_report`。
+
+pub mod ports;
+pub mod serve;
+
+use serde_json::{json, Value};
+use unlucky_agent::mcp::config_samples;
+use unlucky_core::setting::keys::launcher_schema;
+use unlucky_core::setting::store::SettingStore;
+
+use crate::cli::AgentServeArgs;
+use crate::context::Ctx;
+use crate::error::CliError;
+use crate::output::Report;
+
+/// `ull agent serve`：起服务（阻塞）。
+///
+/// # Errors
+/// 见 [`serve::run`]。
+pub fn run_serve(ctx: &Ctx, args: &AgentServeArgs) -> Result<i32, CliError> {
+    serve::run(ctx, args)
+}
+
+/// runner 的分流入口：解析数据根 → 起服务。错误由 runner 统一打印。
+///
+/// # Errors
+/// 数据根缺失、平台不达基线、端口占用、非回环监听等返回用户错误。
+pub fn run_serve_with(
+    globals: &crate::cli::Globals,
+    args: &AgentServeArgs,
+    err: &mut dyn std::io::Write,
+) -> Result<i32, CliError> {
+    let ctx = Ctx::resolve(globals)?;
+    ctx.ensure_supported()?;
+    for note in ctx.notes() {
+        let _ = writeln!(err, "提示: {note}");
+    }
+    run_serve(&ctx, args)
+}
+
+/// `ull agent config`：输出两份可粘贴的客户端配置 + 当前设置状态。
+///
+/// # Errors
+/// 配置不可读时返回用户错误（schema 不认识的键不影响）。
+pub fn config_report(ctx: &Ctx, port: Option<u16>) -> Result<Report, CliError> {
+    let store = SettingStore::load(ctx.launcher_config(), launcher_schema());
+    let doc = store.doc();
+    let enabled = doc
+        .effective("agent.mcp.enabled")
+        .and_then(Value::as_bool)
+        .unwrap_or(false);
+    let allow_write = doc
+        .effective("agent.mcp.allow_write")
+        .and_then(Value::as_bool)
+        .unwrap_or(false);
+    let yolo = doc
+        .effective("ai.yolo")
+        .and_then(Value::as_bool)
+        .unwrap_or(false);
+    let token = doc
+        .effective_str("agent.mcp.token")
+        .map(str::trim)
+        .filter(|text| !text.is_empty())
+        .map(str::to_string);
+    let configured_port = doc
+        .effective("agent.mcp.port")
+        .and_then(Value::as_u64)
+        .and_then(|value| u16::try_from(value).ok())
+        .unwrap_or(47823);
+    let port = port.unwrap_or(configured_port);
+    let url = format!("http://127.0.0.1:{port}/mcp");
+    let samples = config_samples(&url, token.as_deref());
+    let registry = unlucky_agent::tools::build_v1_registry(&ports::build(ctx))
+        .map_err(|error| CliError::internal("agent_registry", error.to_string()))?;
+    let read_only_tools = registry.read_only_definitions().len();
+    let all_tools = registry.len();
+
+    let data = json!({
+        "url": url,
+        "enabled": enabled,
+        "allow_write": allow_write,
+        "yolo": yolo,
+        "token_configured": token.is_some(),
+        "read_only_tools": read_only_tools,
+        "all_tools": all_tools,
+        "claude_code": samples.claude_code,
+        "cursor": samples.cursor,
+    });
+
+    let mut human = vec![
+        format!("MCP 端点：{url}"),
+        format!(
+            "开关：{} · 写权限：{} · YOLO：{} · 令牌：{}",
+            if enabled {
+                "已启用"
+            } else {
+                "未启用（serve 仍可手动起）"
+            },
+            if allow_write {
+                "开"
+            } else {
+                "关（只读）"
+            },
+            if yolo { "开" } else { "关" },
+            if token.is_some() {
+                "已设置"
+            } else {
+                "未设置"
+            }
+        ),
+        "Claude Code（~/.claude.json 或 `claude mcp add --json`）：".to_string(),
+    ];
+    human.extend(pretty_lines(&samples.claude_code));
+    human.push("Cursor（.cursor/mcp.json）：".to_string());
+    human.extend(pretty_lines(&samples.cursor));
+    human.push(
+        "启动：%prog% agent serve（默认 Streamable HTTP） / %prog% agent serve --stdio".to_string(),
+    );
+    Ok(Report::new(data, human))
+}
+
+fn pretty_lines(value: &Value) -> Vec<String> {
+    match serde_json::to_string_pretty(value) {
+        Ok(text) => text.lines().map(|line| format!("  {line}")).collect(),
+        Err(_) => vec!["  （序列化失败）".to_string()],
+    }
+}
diff --git a/crates/cli/src/commands/agent/ports/accounts.rs b/crates/cli/src/commands/agent/ports/accounts.rs
new file mode 100644
index 0000000..39673d4
--- /dev/null
+++ b/crates/cli/src/commands/agent/ports/accounts.rs
@@ -0,0 +1,49 @@
+//! 账户端口：只读 `AccountStore::accounts()`（公开字段）。**凭据红线在这里落闸**。
+//!
+//! `AccountStore::credentials()` 存在，但本文件**不调用**它——agent 侧也没有能承接
+//! `Credentials` 的类型（[`unlucky_agent::port::AccountSummary`]）。这条界线不是靠自觉：
+//! 只要有人想从工具结果里带出 token，就必须先改 `AccountSummary`，而 `port::game` 的
+//! 单测会先炸（序列化结果里不许出现 token/password/secret）。
+
+use unlucky_agent::port::game::{AccountPort, AccountSummary};
+use unlucky_agent::port::PortResult;
+use unlucky_core::auth::AccountStore;
+
+/// M31 账户库的只读端口。
+#[derive(Debug, Clone)]
+pub struct CoreAccounts {
+    root: std::path::PathBuf,
+}
+
+impl CoreAccounts {
+    /// `root` = `<数据根>/.ULL/data/auth`。
+    #[must_use]
+    pub fn new(root: impl Into<std::path::PathBuf>) -> Self {
+        Self { root: root.into() }
+    }
+}
+
+impl AccountPort for CoreAccounts {
+    fn list_accounts(&self) -> PortResult<Vec<AccountSummary>> {
+        let store = AccountStore::open(self.root.clone());
+        if !store.warnings().is_empty() {
+            // 账户文件有坏条目：不阻断（用户还能看到其余账户），但要留痕到 stderr。
+            eprintln!(
+                "[unlucky-agent] 账户库有 {} 条提示（只读本工具不受影响）",
+                store.warnings().len()
+            );
+        }
+        Ok(store
+            .accounts()
+            .iter()
+            .map(|meta| AccountSummary {
+                id: meta.id.as_str().to_string(),
+                kind: meta.kind.as_str().to_string(),
+                profile_id: meta.profile_id.clone(),
+                profile_name: meta.profile_name.clone(),
+                login_name: meta.login_name.clone(),
+                created_at_ms: meta.created_at_ms,
+            })
+            .collect())
+    }
+}
diff --git a/crates/cli/src/commands/agent/ports/diagnose.rs b/crates/cli/src/commands/agent/ports/diagnose.rs
new file mode 100644
index 0000000..0143f0e
--- /dev/null
+++ b/crates/cli/src/commands/agent/ports/diagnose.rs
@@ -0,0 +1,187 @@
+//! 诊断端口：调用 M15 的规则引擎（**规则先跑，模型补位**，02 §3.2）。
+//!
+//! 工具层只把「规则结论 + 相关片段」交给模型，不把裸日志倒进去——这是 token 预算
+//! 与结论质量的双重考虑，也是 analyse/02 §8.3 的分层思路。
+
+use std::collections::BTreeMap;
+
+use unlucky_agent::port::{
+    CrashDiagnosis, DiagnosePort, DiagnosisCandidate, ExitSummary, FixAction, FixActionKind,
+    PortResult,
+};
+use unlucky_core::diagnose::collectors::{ExitSignal, SignalOrigin};
+use unlucky_core::diagnose::engine::{Diagnoser, DiagnosisInput, Finding};
+use unlucky_core::diagnose::loader::RuleLoader;
+use unlucky_core::diagnose::rules::FixActionKind as CoreFixKind;
+
+use super::events::{tail_join, SessionSource};
+
+/// 送进规则引擎的默认尾巴行数（与 CLI `diag` 同值，避免两条路看到不同证据）。
+pub const DEFAULT_TAIL: usize = 2000;
+
+/// M15 规则引擎的端口实现。
+#[derive(Debug, Clone)]
+pub struct CoreDiagnose {
+    source: SessionSource,
+    tail: usize,
+}
+
+impl CoreDiagnose {
+    /// `root` = `<数据根>/.ULL/data/agent/sessions`。
+    #[must_use]
+    pub fn new(root: impl Into<std::path::PathBuf>) -> Self {
+        Self {
+            source: SessionSource::new(root),
+            tail: DEFAULT_TAIL,
+        }
+    }
+}
+
+fn map_kind(kind: CoreFixKind) -> FixActionKind {
+    match kind {
+        CoreFixKind::ChangeJava => FixActionKind::ChangeJava,
+        CoreFixKind::AdjustMemory => FixActionKind::AdjustMemory,
+        CoreFixKind::ChangeGraphics => FixActionKind::ChangeGraphics,
+        CoreFixKind::RemoveMod => FixActionKind::RemoveMod,
+        CoreFixKind::Reinstall => FixActionKind::Reinstall,
+        CoreFixKind::SeekHelp => FixActionKind::SeekHelp,
+    }
+}
+
+fn candidate_of(finding: &Finding) -> DiagnosisCandidate {
+    let core_candidate = finding.to_candidate();
+    DiagnosisCandidate {
+        id: core_candidate.id,
+        severity: core_candidate.severity.to_string(),
+        category: core_candidate.category.to_string(),
+        confidence: core_candidate.confidence,
+        message_key: core_candidate.message_key,
+        message: core_candidate.message,
+        detail: core_candidate.detail.unwrap_or_default(),
+        evidence: core_candidate.evidence,
+        fix_actions: core_candidate
+            .fix_actions
+            .into_iter()
+            .map(|action| FixAction {
+                kind: map_kind(action.kind),
+                tool: action.tool.to_string(),
+                label: String::new(),
+                args: action
+                    .args
+                    .into_iter()
+                    .collect::<BTreeMap<String, String>>(),
+            })
+            .collect(),
+    }
+}
+
+impl DiagnosePort for CoreDiagnose {
+    fn diagnose(&self, session_id: &str) -> PortResult<CrashDiagnosis> {
+        let entry = self.source.find(session_id)?;
+        let events = self.source.events(&entry)?;
+        let (stdout, stderr, error_lines) = SessionSource::split_text(&events);
+
+        let exit = ExitSignal::classify(
+            entry.exit_code,
+            Some(entry.duration_ms),
+            error_lines,
+            &stderr.join("\n"),
+        );
+        let mut input = DiagnosisInput::new().with_exit(exit);
+        let stdout_text = tail_join(&stdout, self.tail);
+        if !stdout_text.is_empty() {
+            input.push_text(SignalOrigin::Stdout, stdout_text);
+        }
+        let stderr_text = tail_join(&stderr, self.tail);
+        if !stderr_text.is_empty() {
+            input.push_text(SignalOrigin::Stderr, stderr_text);
+        }
+
+        let loader = RuleLoader::embedded();
+        let diagnoser = Diagnoser::new(loader.rule_set().rules().to_vec());
+        let report = diagnoser.analyze(&input);
+
+        Ok(CrashDiagnosis {
+            session_id: entry.session_id.clone(),
+            source: "rules".to_string(),
+            needs_more_info: report.needs_more_info(),
+            candidates: report.findings.iter().map(candidate_of).collect(),
+            secondary: report.secondary.iter().map(candidate_of).collect(),
+            evidence: stderr.iter().rev().take(3).cloned().collect(),
+            exit: ExitSummary {
+                code: entry.exit_code,
+                exit_type: entry.exit_type.clone(),
+                silent_failure: entry.silent_failure,
+            },
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn seed(root: &std::path::Path, stderr_line: &str) {
+        let game = root.join("game");
+        std::fs::create_dir_all(&game).expect("建目录");
+        let entry = json!({
+            "v": 1,
+            "session_id": "20261029T124501-9f3c2a",
+            "instance_id": "inst-1",
+            "instance_name": "1.20.1 Forge",
+            "game_version": "1.20.1",
+            "started_at": "2026-10-29T12:45:01.123Z",
+            "ended_at": "2026-10-29T12:45:05.123Z",
+            "duration_ms": 4000,
+            "exit_code": 1,
+            "exit_type": "application_error",
+            "silent_failure": false,
+            "window_detected": false,
+            "event_count": 1,
+            "log_path": "20261029T124501-9f3c2a.jsonl",
+            "crash_found": true,
+            "diagnosis_top": null
+        });
+        std::fs::write(game.join("index.jsonl"), format!("{entry}\n")).expect("写索引");
+        let event = json!({
+            "seq": 0, "ts": "2026-10-29T12:45:01.123Z", "t_ms": 0,
+            "kind": "stderr",
+            "payload": { "line": stderr_line, "level": "error" }
+        });
+        std::fs::write(
+            game.join("20261029T124501-9f3c2a.jsonl"),
+            format!("{event}\n"),
+        )
+        .expect("写事件");
+    }
+
+    #[test]
+    fn runs_the_rule_engine_over_a_session() {
+        let root = std::env::temp_dir().join(format!("ull-mcp-diagnose-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&root);
+        seed(
+            &root,
+            "java.lang.NoClassDefFoundError: cpw/mods/bootstraplauncher/BootstrapLauncher",
+        );
+
+        let port = CoreDiagnose::new(root.clone());
+        let report = port.diagnose("20261029T124501-9f3c2a").expect("应能诊断");
+        assert_eq!(report.session_id, "20261029T124501-9f3c2a");
+        assert_eq!(report.source, "rules");
+        assert_eq!(report.exit.code, Some(1));
+        // 规则集里应有 JVM/完整性类结论命中这条 stderr
+        assert!(!report.candidates.is_empty(), "应至少命中一条规则");
+
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn unknown_session_is_a_readable_error() {
+        let root =
+            std::env::temp_dir().join(format!("ull-mcp-diagnose-none-{}", std::process::id()));
+        let port = CoreDiagnose::new(root);
+        let err = port.diagnose("nope").unwrap_err();
+        assert!(err.contains("找不到会话"), "{err}");
+    }
+}
diff --git a/crates/cli/src/commands/agent/ports/events.rs b/crates/cli/src/commands/agent/ports/events.rs
new file mode 100644
index 0000000..d313200
--- /dev/null
+++ b/crates/cli/src/commands/agent/ports/events.rs
@@ -0,0 +1,136 @@
+//! 会话数据的读取底座：索引（`index.jsonl`）+ 事件流（`<id>.jsonl`）。
+//!
+//! 三个端口（[`super::session::CoreSessions`] 的列表/切片、[`super::diagnose::CoreDiagnose`]
+//! 的规则跑批）共用这一份读取逻辑——「同一份 jsonl 两种读法」若各写一遍，
+//! 迟早出现「列表说有 5 条事件、诊断只看到 3 条」这种对不上的账。
+//!
+//! 形状依据 `DevDocs/SubAgentsTalk/launch-接口约定.md` §2/§5。
+
+use std::path::{Path, PathBuf};
+
+use serde_json::Value;
+use unlucky_core::launch::session_index::{self, SessionIndexEntry};
+
+use unlucky_agent::port::PortResult;
+
+/// 一个数据根下的会话索引 + 事件流。
+#[derive(Debug, Clone)]
+pub struct SessionSource {
+    root: PathBuf,
+}
+
+impl SessionSource {
+    /// `root` = `<数据根>/.ULL/data/agent/sessions`。
+    #[must_use]
+    pub fn new(root: impl Into<PathBuf>) -> Self {
+        Self { root: root.into() }
+    }
+
+    /// 索引文件路径。
+    #[must_use]
+    pub fn index(&self) -> PathBuf {
+        session_index::index_path(&self.root)
+    }
+
+    /// 全部会话（按 `started_at` 倒序，同 id 取最后一行）。
+    ///
+    /// # Errors
+    /// 索引读不了（权限/IO）时返回用户可读错误；不存在视为空列表。
+    pub fn entries(&self) -> PortResult<Vec<SessionIndexEntry>> {
+        let index = self.index();
+        let mut entries = session_index::read_all(&index)
+            .map_err(|error| format!("读会话索引 {} 失败：{error}", index.display()))?;
+        entries.sort_by(|a, b| b.started_at.cmp(&a.started_at));
+        Ok(entries)
+    }
+
+    /// 按完整 id 或唯一前缀找会话。
+    ///
+    /// # Errors
+    /// 找不到 / 前缀歧义时返回用户可读错误。
+    pub fn find(&self, key: &str) -> PortResult<SessionIndexEntry> {
+        let entries = self.entries()?;
+        if let Some(entry) = entries.iter().find(|entry| entry.session_id == key) {
+            return Ok(entry.clone());
+        }
+        let matches: Vec<&SessionIndexEntry> = entries
+            .iter()
+            .filter(|entry| entry.session_id.starts_with(key))
+            .collect();
+        match matches.as_slice() {
+            [only] => Ok((*only).clone()),
+            [] => Err(format!(
+                "找不到会话 `{key}`（索引：{}）",
+                self.index().display()
+            )),
+            _ => Err(format!(
+                "`{key}` 匹配到 {} 个会话，请给更长的前缀",
+                matches.len()
+            )),
+        }
+    }
+
+    /// 一个会话的原始事件行（解析失败的行跳过，容忍被 kill 时截断的尾行）。
+    ///
+    /// # Errors
+    /// 事件流文件读不了时返回用户可读错误。
+    pub fn events(&self, entry: &SessionIndexEntry) -> PortResult<Vec<Value>> {
+        let path = self.event_path(entry);
+        let text = std::fs::read_to_string(&path)
+            .map_err(|error| format!("读会话事件流 {} 失败：{error}", path.display()))?;
+        Ok(text
+            .lines()
+            .filter(|line| !line.trim().is_empty())
+            .filter_map(|line| serde_json::from_str::<Value>(line).ok())
+            .collect())
+    }
+
+    /// 事件流文件路径。
+    #[must_use]
+    pub fn event_path(&self, entry: &SessionIndexEntry) -> PathBuf {
+        self.root.join("game").join(&entry.log_path)
+    }
+
+    /// 事件里的 stdout / stderr 文本（诊断与日志阅读共用）。
+    ///
+    /// 返回 `(stdout 行, stderr 行, stderr 里 level=error 的条数)`。
+    #[must_use]
+    pub fn split_text(events: &[Value]) -> (Vec<String>, Vec<String>, u32) {
+        let mut stdout = Vec::new();
+        let mut stderr = Vec::new();
+        let mut error_lines = 0u32;
+        for event in events {
+            let Some(line) = event.pointer("/payload/line").and_then(Value::as_str) else {
+                continue;
+            };
+            match event.get("kind").and_then(Value::as_str) {
+                Some("stdout") => stdout.push(line.to_string()),
+                Some("stderr") => {
+                    stderr.push(line.to_string());
+                    if event.pointer("/payload/level").and_then(Value::as_str) == Some("error") {
+                        error_lines += 1;
+                    }
+                }
+                _ => {}
+            }
+        }
+        (stdout, stderr, error_lines)
+    }
+}
+
+/// 取末尾 `tail` 行并拼成文本（诊断输入用）。
+#[must_use]
+pub fn tail_join(lines: &[String], tail: usize) -> String {
+    let start = lines.len().saturating_sub(tail.max(1));
+    let mut text = lines[start..].join("\n");
+    if !text.is_empty() {
+        text.push('\n');
+    }
+    text
+}
+
+/// 索引里有没有这个会话（存在性判断，不读事件流）。
+#[must_use]
+pub fn index_exists(root: &Path) -> bool {
+    session_index::index_path(root).is_file()
+}
diff --git a/crates/cli/src/commands/agent/ports/game.rs b/crates/cli/src/commands/agent/ports/game.rs
new file mode 100644
index 0000000..cd845e6
--- /dev/null
+++ b/crates/cli/src/commands/agent/ports/game.rs
@@ -0,0 +1,204 @@
+//! 实例 / 版本 / Java 端口（M14 + M33）。
+
+use std::path::PathBuf;
+
+use unlucky_agent::port::game::{
+    GamePort, InstanceSummary, JavaRuntimeSummary, JavaStatus, VersionSummary,
+};
+use unlucky_agent::port::PortResult;
+use unlucky_core::game::java::{self, JavaOrigin};
+use unlucky_core::game::{install::instance::read_profiles, GameLayout};
+use unlucky_core::platform::data_dir::DataMode;
+use unlucky_core::platform::layout::LauncherLayout;
+use unlucky_core::platform::paths::{Platform, ProcessEnv};
+use unlucky_core::setting::keys::launcher_schema;
+use unlucky_core::setting::store::SettingStore;
+
+/// 实例 / 版本 / Java 的只读端口。
+#[derive(Debug, Clone)]
+pub struct CoreGame {
+    layout: LauncherLayout,
+    game: GameLayout,
+    launcher_config: PathBuf,
+    mode: DataMode,
+    platform: Platform,
+}
+
+impl CoreGame {
+    /// 装配：`layout` 是 `.ULL/`，`game` 是 `.minecraft/`。
+    #[must_use]
+    pub fn new(
+        layout: LauncherLayout,
+        game: GameLayout,
+        mode: DataMode,
+        platform: Platform,
+    ) -> Self {
+        let launcher_config = layout.launcher_config();
+        Self {
+            layout,
+            game,
+            launcher_config,
+            mode,
+            platform,
+        }
+    }
+
+    fn store(&self) -> SettingStore {
+        SettingStore::load(&self.launcher_config, launcher_schema())
+    }
+
+    fn managed_roots(&self) -> Vec<PathBuf> {
+        let store = self.store();
+        let install_root = store
+            .doc()
+            .effective_str("java.installRoot")
+            .map(str::trim)
+            .filter(|text| !text.is_empty())
+            .map(PathBuf::from);
+        java::location::scan_roots(
+            self.mode,
+            &self.layout,
+            install_root.as_deref(),
+            self.platform,
+            &ProcessEnv,
+        )
+    }
+}
+
+impl GamePort for CoreGame {
+    fn list_instances(&self) -> PortResult<Vec<InstanceSummary>> {
+        let profiles =
+            read_profiles(&self.layout).map_err(|error| format!("读实例清单失败：{error}"))?;
+        let mut out: Vec<InstanceSummary> = profiles
+            .profiles
+            .iter()
+            .map(|profile| InstanceSummary {
+                id: profile.id.as_str().to_string(),
+                name: profile.name.clone(),
+                version_id: profile.version_id.clone(),
+                version_present: self.game.is_version_installed(&profile.version_id),
+                game_dir: profile.game_dir.as_ref().map(|p| p.display().to_string()),
+                java_path: profile.java_path.as_ref().map(|p| p.display().to_string()),
+                last_played_at: profile.last_played_at.as_deref().and_then(parse_rfc3339_ms),
+            })
+            .collect();
+        // `profiles.json` 的顺序是 UI 顺序；这里按最近启动时间倒序（最近的先看）。
+        out.sort_by_key(|instance| std::cmp::Reverse(instance.last_played_at));
+        Ok(out)
+    }
+
+    fn list_versions(&self) -> PortResult<Vec<VersionSummary>> {
+        let versions = self
+            .game
+            .installed_versions()
+            .map_err(|error| format!("读已安装版本失败：{error}"))?;
+        let profiles = read_profiles(&self.layout).map_err(|error| error.to_string())?;
+        Ok(versions
+            .into_iter()
+            .map(|id| {
+                let instance_count = profiles
+                    .profiles
+                    .iter()
+                    .filter(|profile| profile.version_id == id)
+                    .count();
+                VersionSummary {
+                    id,
+                    kind: None,
+                    instance_count,
+                }
+            })
+            .collect())
+    }
+
+    fn java_status(&self) -> PortResult<JavaStatus> {
+        let roots = self.managed_roots();
+        let mut candidates = java::candidates_in_roots(&roots);
+        if let Ok(profiles) = read_profiles(&self.layout) {
+            for profile in &profiles.profiles {
+                if let Some(path) = &profile.java_path {
+                    candidates.push(java::probe(path, JavaOrigin::Instance));
+                }
+            }
+        }
+        let candidates = java::discover::dedupe(candidates);
+        let summary: Vec<JavaRuntimeSummary> = candidates
+            .iter()
+            .map(|runtime| JavaRuntimeSummary {
+                binary: runtime.binary.display().to_string(),
+                version: runtime.version.clone(),
+                major: runtime.major,
+                vendor: runtime.vendor.clone(),
+                origin: runtime.origin.category().to_string(),
+            })
+            .collect();
+
+        let default_memory = self
+            .store()
+            .effective("java.default_memory_mb")
+            .and_then(serde_json::Value::as_u64);
+
+        Ok(JavaStatus {
+            default_memory_mb: default_memory,
+            managed_roots: roots
+                .iter()
+                .map(|root| root.display().to_string())
+                .collect(),
+            candidates: summary,
+        })
+    }
+}
+
+/// RFC3339 → Unix 毫秒（解析失败返回 `None`，不让一个坏时间戳毁掉整个列表）。
+///
+/// 只处理 launch 写出来的那一种形态（总是 UTC、总是 `Z` 结尾）。不引第三方日期库：
+/// agent 侧只需要「排序用的毫秒」，多一棵依赖树不值当。
+fn parse_rfc3339_ms(text: &str) -> Option<u64> {
+    let body = text.trim().trim_end_matches('Z');
+    let (date, time) = body.split_once('T')?;
+    let mut date_parts = date.split('-');
+    let year: i64 = date_parts.next()?.parse().ok()?;
+    let month: i64 = date_parts.next()?.parse().ok()?;
+    let day: i64 = date_parts.next()?.parse().ok()?;
+    let mut time_parts = time.split(':');
+    let hour: i64 = time_parts.next()?.parse().ok()?;
+    let minute: i64 = time_parts.next()?.parse().ok()?;
+    let seconds_text = time_parts.next()?;
+    let (secs, millis) = match seconds_text.split_once('.') {
+        Some((secs, frac)) => (secs.parse::<i64>().ok()?, {
+            let padded = format!("{frac:0<3}");
+            padded.get(..3)?.parse::<i64>().ok()?
+        }),
+        None => (seconds_text.parse::<i64>().ok()?, 0),
+    };
+
+    let days = days_from_civil(year, month, day);
+    let total_ms = (((days * 24 + hour) * 60 + minute) * 60 + secs) * 1000 + millis;
+    u64::try_from(total_ms).ok()
+}
+
+/// Howard Hinnant 的 `days_from_civil`（1970-01-01 为 0）。
+fn days_from_civil(year: i64, month: i64, day: i64) -> i64 {
+    let y = if month <= 2 { year - 1 } else { year };
+    let era = if y >= 0 { y } else { y - 399 } / 400;
+    let yoe = y - era * 400;
+    let mp = (month + 9) % 12;
+    let doy = (153 * mp + 2) / 5 + day - 1;
+    let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy;
+    era * 146_097 + doe - 719_468
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_launch_timestamps() {
+        assert_eq!(parse_rfc3339_ms("1970-01-01T00:00:00.000Z"), Some(0));
+        // 与既有审计测试同源：1_793_304_753_123 = 2026-10-29T20:12:33.123Z
+        assert_eq!(
+            parse_rfc3339_ms("2026-10-29T20:12:33.123Z"),
+            Some(1_793_304_753_123)
+        );
+        assert_eq!(parse_rfc3339_ms("not-a-time"), None);
+    }
+}
diff --git a/crates/cli/src/commands/agent/ports/mod.rs b/crates/cli/src/commands/agent/ports/mod.rs
new file mode 100644
index 0000000..195b067
--- /dev/null
+++ b/crates/cli/src/commands/agent/ports/mod.rs
@@ -0,0 +1,58 @@
+//! 端口装配：把 `unlucky-core` 的实现塞进 agent 的五个端口。
+//!
+//! 为什么这一层在 CLI 而不在 agent：agent 只知道 trait（`#!` 依赖倒置），
+//! `crates/app` 是 GUI 的装配处，而 `ull agent serve` 是**headless 的另一个装配入口**。
+//! 放这里让 CLI 自洽，也让 GUI 后续复用同一批适配器（把本目录上移到 app 是一次纯搬家）。
+//!
+//! 每个文件一个端口，与 `crates/agent/src/port*.rs` 一一对应，读起来不用跳来跳去。
+
+pub mod accounts;
+pub mod diagnose;
+pub mod events;
+pub mod game;
+pub mod session;
+pub mod setting;
+
+use std::sync::Arc;
+
+use unlucky_agent::port::Ports;
+use unlucky_core::platform::data_dir::DataMode;
+use unlucky_core::platform::paths::Platform;
+
+use crate::context::Ctx;
+
+pub use accounts::CoreAccounts;
+pub use diagnose::CoreDiagnose;
+pub use game::CoreGame;
+pub use session::CoreSessions;
+pub use setting::CoreSetting;
+
+/// 按一次 CLI 上下文装配五个端口。
+#[must_use]
+pub fn build(ctx: &Ctx) -> Ports {
+    Ports {
+        // 数据根键（`core.*`）落便携目录那份，与 `Ctx::resolve` 同源——CLI `config set`
+        // 与 AI `set_config` 共用 `Ctx` 给出的两个落点（finding …-agent-settingport-core-ai）。
+        setting: Arc::new(CoreSetting::split(
+            ctx.launcher_config(),
+            ctx.portable_launcher_config(),
+        )),
+        sessions: Arc::new(CoreSessions::new(ctx.sessions_root())),
+        diagnose: Arc::new(CoreDiagnose::new(ctx.sessions_root())),
+        game: Arc::new(CoreGame::new(
+            ctx.layout(),
+            ctx.game(),
+            data_mode(ctx),
+            platform(ctx),
+        )),
+        accounts: Arc::new(CoreAccounts::new(ctx.auth_data())),
+    }
+}
+
+pub(crate) fn data_mode(ctx: &Ctx) -> DataMode {
+    ctx.data.mode
+}
+
+pub(crate) fn platform(ctx: &Ctx) -> Platform {
+    ctx.platform
+}
diff --git a/crates/cli/src/commands/agent/ports/session.rs b/crates/cli/src/commands/agent/ports/session.rs
new file mode 100644
index 0000000..773fc85
--- /dev/null
+++ b/crates/cli/src/commands/agent/ports/session.rs
@@ -0,0 +1,201 @@
+//! 会话端口：索引 → `list_game_sessions`，事件流切片 → `read_game_log`。
+
+use serde_json::{json, Value};
+
+use unlucky_agent::port::{
+    GameSessionPort, GameSessionSummary, LogEvent, LogPage, LogQuery, PortResult,
+};
+
+use super::events::SessionSource;
+
+/// M18 的会话索引 + 事件流。
+#[derive(Debug, Clone)]
+pub struct CoreSessions {
+    source: SessionSource,
+}
+
+impl CoreSessions {
+    /// `root` = `<数据根>/.ULL/data/agent/sessions`。
+    #[must_use]
+    pub fn new(root: impl Into<std::path::PathBuf>) -> Self {
+        Self {
+            source: SessionSource::new(root),
+        }
+    }
+}
+
+fn summary_of(
+    entry: &unlucky_core::launch::session_index::SessionIndexEntry,
+) -> GameSessionSummary {
+    GameSessionSummary {
+        session_id: entry.session_id.clone(),
+        instance_id: Some(entry.instance_id.clone()).filter(|id| !id.is_empty()),
+        instance_name: Some(entry.instance_name.clone()).filter(|name| !name.is_empty()),
+        game_version: Some(entry.game_version.clone()).filter(|v| !v.is_empty()),
+        started_at: Some(entry.started_at.clone()).filter(|v| !v.is_empty()),
+        ended_at: Some(entry.ended_at.clone()).filter(|v| !v.is_empty()),
+        duration_ms: entry.duration_ms,
+        exit_code: entry.exit_code,
+        exit_type: entry.exit_type.clone(),
+        silent_failure: entry.silent_failure,
+        window_detected: entry.window_detected,
+        event_count: entry.event_count,
+        crash_found: entry.crash_found,
+        diagnosis_top: entry.diagnosis_top.clone(),
+    }
+}
+
+fn to_log_event(event: &Value, fallback_seq: u64) -> LogEvent {
+    LogEvent {
+        seq: event
+            .get("seq")
+            .and_then(Value::as_u64)
+            .unwrap_or(fallback_seq),
+        ts: event
+            .get("ts")
+            .and_then(Value::as_str)
+            .unwrap_or_default()
+            .to_string(),
+        t_ms: event.get("t_ms").and_then(Value::as_u64).unwrap_or(0),
+        kind: event
+            .get("kind")
+            .and_then(Value::as_str)
+            .unwrap_or_default()
+            .to_string(),
+        payload: event.get("payload").cloned().unwrap_or(Value::Null),
+    }
+}
+
+impl GameSessionPort for CoreSessions {
+    fn list_sessions(
+        &self,
+        limit: usize,
+        instance_id: Option<&str>,
+    ) -> PortResult<Vec<GameSessionSummary>> {
+        let mut entries = self.source.entries()?;
+        if let Some(instance) = instance_id {
+            entries.retain(|entry| entry.instance_id == instance);
+        }
+        entries.truncate(limit);
+        Ok(entries.iter().map(summary_of).collect())
+    }
+
+    fn read_log(&self, session_id: &str, query: &LogQuery) -> PortResult<LogPage> {
+        let entry = self.source.find(session_id)?;
+        let raw = self.source.events(&entry)?;
+        let events: Vec<LogEvent> = raw
+            .iter()
+            .enumerate()
+            .map(|(index, event)| to_log_event(event, index as u64))
+            .collect();
+
+        let mut kind_counts = std::collections::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: entry.session_id,
+            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(),
+        })
+    }
+}
+
+/// 会话摘要 + 事件流 → JSON 里用得到的稳定形状（`read_game_log` 的 payload 直接透传）。
+#[must_use]
+pub fn log_event_json(event: &LogEvent) -> Value {
+    json!({
+        "seq": event.seq,
+        "ts": event.ts,
+        "t_ms": event.t_ms,
+        "kind": event.kind,
+        "payload": event.payload,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::path::Path;
+
+    fn seed_session(root: &Path) {
+        let game_dir = root.join("game");
+        std::fs::create_dir_all(&game_dir).expect("建目录");
+        let entry = json!({
+            "v": 1,
+            "session_id": "20261029T124501-9f3c2a",
+            "instance_id": "inst-1",
+            "instance_name": "1.20.1 Forge",
+            "game_version": "1.20.1",
+            "started_at": "2026-10-29T12:45:01.123Z",
+            "ended_at": "2026-10-29T12:46:31.123Z",
+            "duration_ms": 90000,
+            "exit_code": 1,
+            "exit_type": "application_error",
+            "silent_failure": false,
+            "window_detected": true,
+            "event_count": 2,
+            "log_path": "20261029T124501-9f3c2a.jsonl",
+            "crash_found": true,
+            "diagnosis_top": "integrity.forge_missing_library"
+        });
+        std::fs::write(game_dir.join("index.jsonl"), format!("{entry}\n")).expect("写索引");
+        let events = [
+            json!({"seq":0,"ts":"2026-10-29T12:45:01.123Z","t_ms":0,"kind":"stdout","payload":{"line":"hi","level":"info"}}),
+            json!({"seq":1,"ts":"2026-10-29T12:45:02.123Z","t_ms":1000,"kind":"stderr","payload":{"line":"boom","level":"error"}}),
+        ];
+        let text: String = events
+            .iter()
+            .map(|event| format!("{event}\n"))
+            .collect::<String>();
+        std::fs::write(game_dir.join("20261029T124501-9f3c2a.jsonl"), text).expect("写事件");
+    }
+
+    #[test]
+    fn lists_and_slices_a_session() {
+        let root = std::env::temp_dir().join(format!("ull-mcp-sessions-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&root);
+        seed_session(&root);
+
+        let port = CoreSessions::new(root.clone());
+        let sessions = port.list_sessions(10, None).expect("应能列出");
+        assert_eq!(sessions.len(), 1);
+        assert_eq!(sessions[0].exit_code, Some(1));
+        assert!(sessions[0].crash_found);
+
+        let page = port
+            .read_log(
+                "20261029T124501",
+                &LogQuery {
+                    max_events: 1,
+                    kinds: vec!["stderr".to_string()],
+                    ..LogQuery::default()
+                },
+            )
+            .expect("应能读");
+        assert_eq!(page.total_events, 2);
+        assert_eq!(page.events.len(), 1);
+        assert_eq!(page.events[0].kind, "stderr");
+        assert!(page.kind_counts.contains_key("stdout"));
+
+        let _ = std::fs::remove_dir_all(&root);
+    }
+}
diff --git a/crates/cli/src/commands/agent/ports/setting.rs b/crates/cli/src/commands/agent/ports/setting.rs
new file mode 100644
index 0000000..46f846b
--- /dev/null
+++ b/crates/cli/src/commands/agent/ports/setting.rs
@@ -0,0 +1,211 @@
+//! 配置端口：`core::setting` 的直译（**唯一真相源**在 core，这里不复制校验规则）。
+//!
+//! 三条纪律：
+//! 1. 每次调用都重新 `SettingStore::load`——外部 MCP 客户端可能刚改了配置，
+//!    缓存一份快照会让审计里的 `old` 骗人；
+//! 2. **敏感值一律掩码**（M12 `Sensitivity::High` + agent 的凭据词表两道）：
+//!    工具结果会回灌模型、也可能发往远端 LLM，AI 只需要知道「这个键是什么、怎么改」；
+//! 3. **落点与 `ull config` 同源**（分流规则仍只在 `crate::context` 一处）：数据根键
+//!    读写便携目录那份 `launcher.json`，其余键读写解析后的数据根。只持一份路径时
+//!    standard / `--data-dir` 模式下 AI 改 `core.data_mode` 会「写了没反应」
+//!    （finding 20261031-worker-chore40-improve-agent-settingport-core-ai）。
+
+use std::path::{Path, PathBuf};
+
+use serde_json::{json, Map, Value};
+use unlucky_agent::confirm::Sensitivity;
+use unlucky_agent::port::{PortResult, SettingChange, SettingKey, SettingPort};
+use unlucky_core::setting::keys::launcher_schema;
+use unlucky_core::setting::spec::{Sensitivity as CoreSensitivity, ValueKind};
+use unlucky_core::setting::store::{SaveOutcome, SettingStore, SkipReason};
+
+use crate::context::is_data_root_key;
+
+/// 掩码占位（与 CLI `config get` 同一串，读输出的人不用学两套）。
+pub const MASK: &str = "<redacted>";
+
+/// 把 `core::setting` 包成 agent 的 [`SettingPort`]。
+#[derive(Debug, Clone)]
+pub struct CoreSetting {
+    /// 解析后的数据根那份 `launcher.json`（非数据根键的落点）。
+    path: PathBuf,
+    /// 便携目录那份 `launcher.json`（数据根键的落点）；与 `path` 重合或拿不到
+    /// exe 目录时为 `None`。
+    core_path: Option<PathBuf>,
+}
+
+impl CoreSetting {
+    /// 只指向数据根那份 `<数据根>/.ULL/config/launcher.json`（两份落点重合时够用）。
+    #[must_use]
+    pub fn new(path: impl Into<PathBuf>) -> Self {
+        Self::split(path, None)
+    }
+
+    /// 数据根那份 + 便携目录那份（`Ctx::portable_launcher_config`，与数据根解析同源）。
+    ///
+    /// 两份路径重合（便携模式）时只留一份，免得同一个文件被加载两次。
+    #[must_use]
+    pub fn split(path: impl Into<PathBuf>, core_path: Option<PathBuf>) -> Self {
+        let path = path.into();
+        let core_path = core_path.filter(|core| core.as_path() != path.as_path());
+        Self { path, core_path }
+    }
+
+    /// 某个键的落点文件（数据根键 → 便携目录那份，其余 → 数据根那份）。
+    fn path_for(&self, key: &str) -> &Path {
+        match &self.core_path {
+            Some(core) if is_data_root_key(key) => core.as_path(),
+            _ => self.path.as_path(),
+        }
+    }
+
+    /// 按落点加载 store（读写都用它，`get`/`set` 不会各看一份文件）。
+    fn store_for(&self, key: &str) -> SettingStore {
+        SettingStore::load(self.path_for(key), launcher_schema())
+    }
+
+    /// 数据根那份（schema / 白名单等与落点无关的元数据都从它出）。
+    fn store(&self) -> SettingStore {
+        SettingStore::load(&self.path, launcher_schema())
+    }
+}
+
+/// `summary` 里某个键的**原始**取值来源（掩码在 `summary` 里做）：数据根键取便携目录
+/// 那份——也就是 `Ctx::resolve` 读的同一份，否则概要和「真正生效值」是两套真相。
+fn raw_value<'a>(
+    data: &'a SettingStore,
+    core: Option<&'a SettingStore>,
+    key: &str,
+) -> Option<&'a Value> {
+    match core {
+        Some(core) if is_data_root_key(key) => core.effective(key),
+        _ => data.effective(key),
+    }
+}
+
+fn sensitivity_of(value: CoreSensitivity) -> Sensitivity {
+    match value {
+        CoreSensitivity::Low => Sensitivity::Low,
+        CoreSensitivity::Medium => Sensitivity::Medium,
+        CoreSensitivity::High => Sensitivity::High,
+    }
+}
+
+fn kind_label(kind: &ValueKind) -> &'static str {
+    match kind {
+        ValueKind::Bool => "boolean",
+        ValueKind::Int { .. } => "integer",
+        ValueKind::Float { .. } => "number",
+        ValueKind::Text { .. } => "string",
+        ValueKind::Path => "path",
+        ValueKind::Enum(_) => "enum",
+        ValueKind::TextList => "string[]",
+        ValueKind::EnumList(_) => "enum[]",
+        ValueKind::Any => "json",
+    }
+}
+
+/// 该键的值要不要在 AI 侧掩码：凭据词表命中，或 schema 标 `High`。
+fn mask(value: Value, sensitive: bool) -> Value {
+    if sensitive {
+        json!(MASK)
+    } else {
+        value
+    }
+}
+
+impl SettingPort for CoreSetting {
+    /// 全量概要：每个键的生效值都取自**它自己的落点文件**（数据根键取便携目录那份）。
+    fn summary(&self) -> Value {
+        let store = self.store();
+        let core = self
+            .core_path
+            .as_ref()
+            .map(|path| SettingStore::load(path, launcher_schema()));
+        let schema = store.doc().schema().clone();
+        let mut map = Map::new();
+        for spec in schema.specs() {
+            if spec.is_deprecated() {
+                continue;
+            }
+            let sensitive = spec.ai.sensitivity == CoreSensitivity::High
+                || unlucky_agent::redact::is_sensitive_key(spec.key);
+            let value = raw_value(&store, core.as_ref(), spec.key)
+                .cloned()
+                .unwrap_or(Value::Null);
+            map.insert(spec.key.to_string(), mask(value, sensitive));
+        }
+        Value::Object(map)
+    }
+
+    fn get(&self, path: &str) -> PortResult<Value> {
+        if unlucky_agent::redact::is_sensitive_key(path) {
+            return Err(format!(
+                "`{path}` 是凭据类配置，AI 不可读取也不可写入；请让用户自己在设置页查看"
+            ));
+        }
+        let store = self.store_for(path);
+        let schema = store.doc().schema().clone();
+        let Some(value) = store.effective(path).cloned() else {
+            return Err(format!("配置键 `{path}` 不在 schema 里"));
+        };
+        let sensitive = schema.sensitivity(path) == Some(CoreSensitivity::High);
+        Ok(mask(value, sensitive))
+    }
+
+    fn set(&self, path: &str, value: &Value) -> PortResult<SettingChange> {
+        let file = self.path_for(path);
+        let mut store = self.store_for(path);
+        let schema = store.doc().schema().clone();
+        let sensitive = schema.sensitivity(path) == Some(CoreSensitivity::High);
+        let old = store
+            .effective(path)
+            .cloned()
+            .map(|old| mask(old, sensitive));
+        store
+            .set(path, value.clone())
+            .map_err(|error| error.to_string())?;
+        match store.save() {
+            Ok(SaveOutcome::Saved(_)) | Ok(SaveOutcome::Skipped(SkipReason::NotDirty)) => {}
+            // 只读/不可信：**不能**报成功——外部客户端会以为改完了。
+            Ok(SaveOutcome::Skipped(reason)) => {
+                return Err(format!(
+                    "{} 当前不可写（{}）；请让用户检查文件权限或内容",
+                    file.display(),
+                    reason.as_str()
+                ))
+            }
+            Err(error) => return Err(format!("写 {} 失败：{error}", file.display())),
+        }
+        Ok(SettingChange {
+            path: path.to_string(),
+            old,
+            new: mask(value.clone(), sensitive),
+        })
+    }
+
+    fn writable_keys(&self) -> Vec<SettingKey> {
+        let store = self.store();
+        let schema = store.doc().schema().clone();
+        schema
+            .specs()
+            .iter()
+            .filter(|spec| spec.ai.writable && !spec.is_deprecated())
+            .map(|spec| SettingKey {
+                path: spec.key.to_string(),
+                sensitivity: sensitivity_of(spec.ai.sensitivity),
+                value_type: kind_label(&spec.kind).to_string(),
+                description: spec.doc.to_string(),
+            })
+            .collect()
+    }
+
+    fn schema(&self) -> Value {
+        // core 的 `to_json_schema()` 只遍历 `ai.writable && !deprecated`，
+        // 凭据键（`locked`）天然不在其中——这正是 `get_config_schema` 要的东西。
+        self.store().doc().schema().to_json_schema()
+    }
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/cli/src/commands/agent/ports/setting/tests.rs b/crates/cli/src/commands/agent/ports/setting/tests.rs
new file mode 100644
index 0000000..2e84077
--- /dev/null
+++ b/crates/cli/src/commands/agent/ports/setting/tests.rs
@@ -0,0 +1,226 @@
+//! [`super`] 的单测：数据根键与其余键的落点分流、AI 侧写入真的生效。
+//!
+//! 与 `commands/config/tests.rs` 同一套造场手法：临时目录 + `Ctx::resolve_in`
+//! 把便携目录钉死在临时路径里，不动真实数据根。
+
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use super::*;
+use crate::cli::Globals;
+use crate::commands::agent::ports::build;
+use crate::context::Ctx;
+
+fn temp_config() -> PathBuf {
+    let dir = std::env::temp_dir().join(format!(
+        "ull-core-setting-{}-{:?}",
+        std::process::id(),
+        std::thread::current().id()
+    ));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).expect("建临时目录");
+    dir.join("launcher.json")
+}
+
+#[test]
+fn schema_omits_credential_keys_and_writable_keys_match_policy() {
+    let port = CoreSetting::new(temp_config());
+    let schema = port.schema();
+    let text = schema.to_string();
+    assert!(!text.contains("ai.api_key"), "凭据键不得进 AI schema");
+    assert!(text.contains("agent.mcp.port"), "M39 的新键应可写：{text}");
+
+    let paths: Vec<String> = port.writable_keys().into_iter().map(|k| k.path).collect();
+    assert!(paths.contains(&"download.concurrency".to_string()));
+    assert!(!paths.contains(&"ai.api_key".to_string()));
+}
+
+#[test]
+fn summary_masks_high_sensitivity_but_keeps_low() {
+    let port = CoreSetting::new(temp_config());
+    let summary = port.summary();
+    assert_eq!(summary["ai.base_url"], json!(MASK), "High 键要掩码");
+    assert_ne!(
+        summary["download.concurrency"],
+        json!(MASK),
+        "Low 键不必掩码"
+    );
+}
+
+#[test]
+fn credential_key_get_is_refused() {
+    let port = CoreSetting::new(temp_config());
+    let err = port.get("ai.api_key").unwrap_err();
+    assert!(err.contains("凭据类配置"), "{err}");
+}
+
+#[test]
+fn set_then_get_round_trips_a_low_key() {
+    let path = temp_config();
+    let port = CoreSetting::new(path.clone());
+    let change = port
+        .set("download.concurrency", &json!(16))
+        .expect("应写入");
+    assert_eq!(change.new, json!(16));
+    assert_eq!(port.get("download.concurrency").unwrap(), json!(16));
+    assert!(path.is_file(), "应落盘 {}", path.display());
+    let _ = std::fs::remove_dir_all(path.parent().unwrap());
+}
+
+/// 一次性临时目录（`Drop` 时清理；cli 没有 dev-dependency 的 tempfile）。
+struct TempDir(PathBuf);
+
+impl TempDir {
+    fn new(tag: &str) -> Self {
+        static COUNTER: AtomicU64 = AtomicU64::new(0);
+        let seq = COUNTER.fetch_add(1, Ordering::Relaxed);
+        let path =
+            std::env::temp_dir().join(format!("ull-ai-setting-{tag}-{}-{seq}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&path);
+        std::fs::create_dir_all(&path).expect("建临时目录");
+        Self(path)
+    }
+
+    fn path(&self) -> &Path {
+        &self.0
+    }
+}
+
+impl Drop for TempDir {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.0);
+    }
+}
+
+/// 正确的 `$schema`（认不出的前缀会让加载降级成只读）。
+fn schema_url() -> String {
+    use unlucky_core::setting::keys::launcher_version;
+    use unlucky_core::setting::schema::{SchemaId, SchemaRef};
+    SchemaRef::new(SchemaId::LAUNCHER, launcher_version()).url()
+}
+
+fn write_json(path: &Path, value: &Value) {
+    std::fs::create_dir_all(path.parent().expect("有父目录")).expect("建目录");
+    std::fs::write(path, value.to_string()).expect("写配置");
+}
+
+fn read_json(path: &Path) -> Value {
+    let bytes = std::fs::read(path).unwrap_or_else(|e| panic!("读 {} 失败：{e}", path.display()));
+    serde_json::from_slice(&bytes).expect("合法 JSON")
+}
+
+/// standard 模式现场：便携目录那份说 standard + 自定义 launcher home（数据根留在临时目录里）。
+fn standard_fixture(temp: &TempDir) -> (PathBuf, PathBuf, PathBuf) {
+    let exe = temp.path().join("exe");
+    let launcher_home = temp.path().join("lhome");
+    let portable = exe.join(".ULL").join("config").join("launcher.json");
+    write_json(
+        &portable,
+        &json!({
+            "$schema": schema_url(),
+            "schemaVersion": 1,
+            "core": {
+                "data_mode": "standard",
+                "launcher_home": launcher_home.display().to_string(),
+            },
+        }),
+    );
+    (exe, portable, launcher_home)
+}
+
+/// **AI 面改 `core.data_mode` 真的生效**：写便携目录那份，下一次解析换模式。
+///
+/// 走的是 `ports::build` 装出来的同一个端口（`set_config` 工具背后就是它）。
+#[test]
+fn ai_set_of_core_data_mode_takes_effect_on_the_next_resolve() {
+    let temp = TempDir::new("core-ai");
+    let (exe, portable, launcher_home) = standard_fixture(&temp);
+    let ctx = Ctx::resolve_in(&Globals::default(), Some(exe.clone())).expect("解析数据根");
+    assert_eq!(ctx.data.mode.as_str(), "standard");
+    let ports = build(&ctx);
+
+    ports
+        .setting
+        .set("core.data_mode", &json!("portable"))
+        .expect("AI 侧写 core.data_mode");
+
+    assert_eq!(
+        read_json(&portable)["core"]["data_mode"],
+        json!("portable"),
+        "数据根键要落在便携目录那份"
+    );
+    let data_file = launcher_home.join("config").join("launcher.json");
+    assert!(
+        !data_file.exists() || read_json(&data_file)["core"].get("data_mode").is_none(),
+        "数据根那份不该被写入 core.data_mode"
+    );
+
+    let next = Ctx::resolve_in(&Globals::default(), Some(exe)).expect("重新解析");
+    assert_eq!(
+        next.data.mode.as_str(),
+        "portable",
+        "改了没反应到此为止：下一次解析必须换模式"
+    );
+
+    // 其余键仍走数据根那份，且不污染便携目录那份。
+    ports
+        .setting
+        .set("download.concurrency", &json!(16))
+        .expect("AI 侧写普通键");
+    assert_eq!(read_json(&data_file)["download"]["concurrency"], json!(16));
+    assert!(
+        read_json(&portable)["download"]
+            .get("concurrency")
+            .is_none(),
+        "普通键不该写进便携目录那份"
+    );
+}
+
+/// 概要的取值来源与解析同源：数据根键取便携那份（哪怕数据根那份留着陈旧值）。
+#[test]
+fn summary_takes_data_root_keys_from_the_portable_file() {
+    let temp = TempDir::new("core-summary");
+    let (exe, portable, launcher_home) = standard_fixture(&temp);
+    // 老版本 AI 写错文件留下的现场：数据根那份有个陈旧的 core.data_mode。
+    let data_file = launcher_home.join("config").join("launcher.json");
+    write_json(
+        &data_file,
+        &json!({
+            "$schema": schema_url(),
+            "schemaVersion": 1,
+            "core": { "data_mode": "custom" },
+            "download": { "concurrency": 4 },
+        }),
+    );
+
+    let ctx = Ctx::resolve_in(&Globals::default(), Some(exe)).expect("解析数据根");
+    let port = CoreSetting::split(ctx.launcher_config(), ctx.portable_launcher_config());
+    let data = port.store();
+    let core = SettingStore::load(&portable, launcher_schema());
+
+    assert_eq!(
+        raw_value(&data, Some(&core), "core.data_mode"),
+        Some(&json!("standard")),
+        "数据根键取便携那份 = 解析读到的那份"
+    );
+    assert_eq!(
+        raw_value(&data, Some(&core), "download.concurrency"),
+        Some(&json!(4)),
+        "其余键仍取数据根那份"
+    );
+    // `core.*` 是 M12 的 High 键，概要里照旧掩码（值不可见，但来源必须对）。
+    assert_eq!(port.summary()["core.data_mode"], json!(MASK));
+}
+
+/// 便携模式下两份落点本就是同一份文件：不留第二份，免得重复加载。
+#[test]
+fn portable_mode_keeps_a_single_landing_file() {
+    let temp = TempDir::new("core-portable");
+    let ctx =
+        Ctx::resolve_in(&Globals::default(), Some(temp.path().to_path_buf())).expect("解析数据根");
+    assert_eq!(ctx.data.mode.as_str(), "portable");
+    let port = CoreSetting::split(ctx.launcher_config(), ctx.portable_launcher_config());
+    assert_eq!(
+        port.path_for("core.data_mode"),
+        ctx.launcher_config().as_path()
+    );
+}
diff --git a/crates/cli/src/commands/agent/serve.rs b/crates/cli/src/commands/agent/serve.rs
new file mode 100644
index 0000000..397b7b3
--- /dev/null
+++ b/crates/cli/src/commands/agent/serve.rs
@@ -0,0 +1,218 @@
+//! `ull agent serve`：把注册表挂成 MCP server，长驻运行。
+//!
+//! 装配顺序（每一步都对应 02 文档的一条约束）：
+//! 1. 设置 → `McpConfig`（`agent.mcp.*`，命令行可覆盖）；
+//! 2. 端口（[`super::ports`]）→ 注册表（`tools::build_v1_registry`）；
+//! 3. 只读模式 → `read_only_subset()`（物理上不含写工具，列表/调用天然一致）；
+//! 4. 执行器：`JsonlAudit`（落盘 `<data>/agent/audit`）+ fail-closed 闸门 +
+//!    `ConfirmPolicy { yolo }`（读 `ai.yolo`）+ `DenyGuidance::External`（没有弹窗可点）；
+//! 5. 传输：stdio 或 Streamable HTTP（127.0.0.1）。
+
+use std::sync::Arc;
+
+use serde_json::Value;
+use unlucky_agent::audit::{audit_dir, JsonlAudit};
+use unlucky_agent::brain::exec::ToolExecutor;
+use unlucky_agent::clock::SystemClock;
+use unlucky_agent::confirm::{ConfirmPolicy, DenyGuidance, NoUiGate};
+use unlucky_agent::event::NoopSink;
+use unlucky_agent::mcp::{serve_http, serve_stdio, McpConfig, RegistryServer};
+use unlucky_agent::tools::build_v1_registry;
+use unlucky_core::setting::keys::launcher_schema;
+use unlucky_core::setting::store::SettingStore;
+
+use crate::cli::AgentServeArgs;
+use crate::context::Ctx;
+use crate::error::CliError;
+
+/// 起一次 server（阻塞直到进程被杀/stdio 对端关闭）。
+///
+/// # Errors
+/// 注册表装配失败、端口被占用、非回环监听等返回用户错误。
+pub fn run(ctx: &Ctx, args: &AgentServeArgs) -> Result<i32, CliError> {
+    let settings = Settings::load(ctx);
+    let config = settings.mcp_config(args);
+    let yolo = settings.yolo();
+    let read_only = config.read_only;
+    if !settings.enabled {
+        eprintln!(
+            "[unlucky-agent] 提示：设置键 agent.mcp.enabled=false，本次是手动启动（GUI 不会自动起）"
+        );
+    }
+
+    let ports = super::ports::build(ctx);
+    let registry = Arc::new(
+        build_v1_registry(&ports)
+            .map_err(|error| CliError::internal("agent_registry", error.to_string()))?,
+    );
+    // 路由注册表始终是完整的那份；「哪些工具真能跑」由执行器持有的注册表决定
+    // （只读模式下是 read_only_subset）：硬调写工具会得到可读的 tool-level 错误 + 审计，
+    // 而不是 rmcp 的协议级 -32602（客户端只会显示 "internal error"）。
+    let exposed = if read_only {
+        Arc::new(registry.read_only_subset())
+    } else {
+        Arc::clone(&registry)
+    };
+
+    let audit = Arc::new(JsonlAudit::new(
+        audit_dir(&ctx.layout().data()),
+        Arc::new(SystemClock),
+    ));
+    let executor = Arc::new(
+        ToolExecutor::new(
+            Arc::clone(&exposed),
+            audit,
+            Arc::new(NoUiGate),
+            ConfirmPolicy { yolo },
+            Arc::new(SystemClock),
+            Arc::new(NoopSink),
+        )
+        .with_guidance(DenyGuidance::External),
+    );
+
+    let server = RegistryServer::new(registry, executor, transport_label(args), read_only);
+    if args.stdio {
+        // stdio：stdout 是协议流，人类提示一律走 stderr。
+        eprintln!(
+            "[unlucky-agent] MCP server 走 stdio（{} 个工具；写权限：{}；YOLO：{}）",
+            server.tool_count(),
+            if read_only { "关（只读）" } else { "开" },
+            yolo
+        );
+        return block_on(async move { serve_stdio(server).await })
+            .map(|()| crate::error::EXIT_OK)
+            .map_err(|error| CliError::user("mcp_stdio", error.to_string()));
+    }
+
+    let url = config.url();
+    eprintln!("[unlucky-agent] MCP 端点：{url}");
+    block_on(async move { serve_http(server, config).await })
+        .map(|()| crate::error::EXIT_OK)
+        .map_err(|error| CliError::user("mcp_http", error.to_string()))
+}
+
+fn transport_label(args: &AgentServeArgs) -> &'static str {
+    if args.stdio {
+        "mcp-stdio"
+    } else {
+        "mcp-http"
+    }
+}
+
+/// 在独立线程里跑一个 tokio 运行时（stdio 形态要独占 stdin/stdout，不能被主线程抢）。
+fn block_on<F, T>(future: F) -> Result<T, unlucky_agent::mcp::McpServeError>
+where
+    F: std::future::Future<Output = Result<T, unlucky_agent::mcp::McpServeError>> + Send + 'static,
+    T: Send + 'static,
+{
+    let runtime = tokio::runtime::Builder::new_multi_thread()
+        .enable_all()
+        .build()
+        .map_err(|error| unlucky_agent::mcp::McpServeError::Io(error.to_string()))?;
+    runtime.block_on(future)
+}
+
+/// 从 `launcher.json` 读 MCP 相关设置（坏文件退化成默认值，不阻断启动）。
+struct Settings {
+    enabled: bool,
+    port: u16,
+    allow_write: bool,
+    token: Option<String>,
+    yolo: bool,
+}
+
+impl Settings {
+    fn load(ctx: &Ctx) -> Self {
+        let store = SettingStore::load(ctx.launcher_config(), launcher_schema());
+        let doc = store.doc();
+        let port = doc
+            .effective("agent.mcp.port")
+            .and_then(Value::as_u64)
+            .and_then(|value| u16::try_from(value).ok())
+            .unwrap_or(47823);
+        Self {
+            enabled: doc
+                .effective("agent.mcp.enabled")
+                .and_then(Value::as_bool)
+                .unwrap_or(false),
+            port,
+            allow_write: doc
+                .effective("agent.mcp.allow_write")
+                .and_then(Value::as_bool)
+                .unwrap_or(false),
+            token: doc
+                .effective_str("agent.mcp.token")
+                .map(str::trim)
+                .filter(|text| !text.is_empty())
+                .map(str::to_string),
+            yolo: doc
+                .effective("ai.yolo")
+                .and_then(Value::as_bool)
+                .unwrap_or(false),
+        }
+    }
+
+    fn mcp_config(&self, args: &AgentServeArgs) -> McpConfig {
+        McpConfig {
+            host: args.host.clone().unwrap_or_else(|| "127.0.0.1".to_string()),
+            port: args.port.unwrap_or(self.port),
+            token: self.token.clone(),
+            // 命令行 --allow-write 只能**收紧或放开到设置允许的程度**：
+            // 设置里没开写权限时，命令行也不放开（设置是用户的意思表示，命令行是运行参数）。
+            read_only: !(self.allow_write || args.allow_write),
+        }
+    }
+
+    fn yolo(&self) -> bool {
+        self.yolo
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn args() -> AgentServeArgs {
+        AgentServeArgs::default()
+    }
+
+    #[test]
+    fn settings_default_to_read_only_on_47823() {
+        // Settings 需要 Ctx（要真实数据根），这里只测「无设置时的合成规则」：
+        // 用 Default 的字段逐项对照，避免为此造一个假 Ctx。
+        let defaults = Settings {
+            enabled: false,
+            port: 47823,
+            allow_write: false,
+            token: None,
+            yolo: false,
+        };
+        let config = defaults.mcp_config(&args());
+        assert_eq!(config.port, 47823);
+        assert!(config.read_only);
+        assert_eq!(config.host, "127.0.0.1");
+    }
+
+    #[test]
+    fn cli_flags_override_port_and_write_switch() {
+        let settings = Settings {
+            enabled: true,
+            port: 47823,
+            allow_write: true,
+            token: Some("t".to_string()),
+            yolo: true,
+        };
+        let overridden = settings.mcp_config(&AgentServeArgs {
+            port: Some(50000),
+            allow_write: false,
+            ..AgentServeArgs::default()
+        });
+        assert_eq!(overridden.port, 50000);
+        assert!(!overridden.read_only, "设置里允许写时命令行不必再开");
+        assert_eq!(overridden.token.as_deref(), Some("t"));
+        assert!(settings.yolo());
+        // `enabled` 只是 GUI 的自动启动开关：命令行显式 `agent serve` 不看它
+        // （所以这里 enabled=true 既不影响 mcp_config，也不影响能不能起服务）。
+        assert!(settings.enabled);
+    }
+}
diff --git a/crates/cli/src/commands/config.rs b/crates/cli/src/commands/config.rs
new file mode 100644
index 0000000..316cf53
--- /dev/null
+++ b/crates/cli/src/commands/config.rs
@@ -0,0 +1,341 @@
+//! `config get|set`：走 `core::setting` 的 schema API（单一真相源）。
+//!
+//! # 落点（M40：与数据根解析同源）
+//!
+//! - **数据根键**（[`DATA_ROOT_KEYS`]：`core.data_mode` / `core.data_custom_root` /
+//!   `core.launcher_home` / `core.game_home`）→ 便携目录那份 `launcher.json`
+//!   （`<exe 目录>/.ULL/config/launcher.json`）。这正是 `Ctx::resolve` 决定数据根时读的
+//!   同一份文件（落点由 `Ctx::setting_path_for` 给出），所以 `config get core.data_mode`
+//!   展示的就是真正生效的值，`config set` 也真的影响下一次解析；
+//! - 其余键 → 解析后的数据根（`<data>/.ULL/config/launcher.json`）。
+//!
+//! 之前两条路各看一份文件：`--data-dir` / standard 模式下「改了 `core.data_mode` 没反应、
+//! `config get` 还报另一份文件里的值」（finding `…-improve-ull-config-get-set-launcher-json`）。
+//!
+//! 实例级配置（`config/instances/<id>.json`）留给实例管理 mission，这里不半途实现。
+//!
+//! **凭据纪律**（D9 / `02-ai-agent-design.md` §3.1）：schema 标 `High` 的敏感键
+//! （`ai.api_key` / `download.proxy_url` / `java.extra_args` …）在 read 路径上一律掩码——
+//! 单键 get、无键全量 dump、set 的旧值回显**三条**都要掩，`--show-secret` 才放行明文。
+//! 判定叠两道：schema 的 `Sensitivity::High` + agent 的 `redact::is_sensitive_key` 词表。
+
+use serde_json::{json, Map, Value};
+use unlucky_core::setting::catalog::SettingSchema;
+use unlucky_core::setting::keys::launcher_schema;
+use unlucky_core::setting::spec::Sensitivity;
+use unlucky_core::setting::store::{SaveOutcome, SettingStore, SkipReason};
+
+use crate::context::{is_data_root_key, Ctx, DATA_ROOT_KEYS};
+use crate::error::CliError;
+use crate::output::Report;
+
+/// 敏感值在输出里的占位。
+const MASK: &str = "<redacted>";
+
+/// `ull config get [<key>] [--show-secret]`。
+///
+/// # Errors
+///
+/// 未知键、配置不可读时返回用户错误。
+pub fn get(ctx: &Ctx, key: Option<&str>, show_secret: bool) -> Result<Report, CliError> {
+    match key {
+        Some(key) => get_one(ctx, key, show_secret),
+        None => dump(ctx, show_secret),
+    }
+}
+
+/// 单键 get：读该键自己的落点文件（数据根键走便携目录那份）。
+fn get_one(ctx: &Ctx, key: &str, show_secret: bool) -> Result<Report, CliError> {
+    let path = ctx.setting_path_for(key);
+    let store = SettingStore::load(&path, launcher_schema());
+    let schema = store.doc().schema().clone();
+
+    let Some(value) = store.effective(key) else {
+        return Err(
+            CliError::user("unknown_key", format!("配置键 `{key}` 不在 schema 里"))
+                .with_hint("`%prog% config get`（不带键）可以看到全部生效键"),
+        );
+    };
+
+    let sensitive = is_sensitive(&schema, key);
+    let hidden = sensitive && !show_secret;
+    let shown = if hidden {
+        Value::String(MASK.to_string())
+    } else {
+        value.clone()
+    };
+    let problems = render_problems(&store);
+    let data = json!({
+        "key": key,
+        "value": shown,
+        "redacted": hidden,
+        "sensitive": sensitive,
+        "path": path.display().to_string(),
+        "problems": problems,
+    });
+    let mut human = vec![format!(
+        "{key} = {}{}",
+        render_value(&shown),
+        if hidden {
+            "（敏感键；加 --show-secret 显示明文）"
+        } else {
+            ""
+        }
+    )];
+    human.push(format!("来自 {}", path.display()));
+    for problem in &problems {
+        human.push(format!("问题：{problem}"));
+    }
+    human.extend(source_note(ctx, key));
+    Ok(Report::new(data, human))
+}
+
+/// 无键全量 dump：以数据根那份为底，`core.*` 数据根键换成便携目录那份的生效值。
+fn dump(ctx: &Ctx, show_secret: bool) -> Result<Report, CliError> {
+    let path = ctx.launcher_config();
+    let store = SettingStore::load(&path, launcher_schema());
+    let schema = store.doc().schema().clone();
+
+    let core_path = ctx
+        .portable_launcher_config()
+        .filter(|core| core.as_path() != path.as_path());
+    let core_store = core_path
+        .as_ref()
+        .map(|core| SettingStore::load(core, launcher_schema()));
+
+    let mut document = store.doc().to_value();
+    if let Some(core) = &core_store {
+        // 只叠加**便携目录那份里真有的键**（默认值不落盘，dump 也只展示文件里有的键）；
+        // 生效数据根在下面的 `data_root` 里单独给，不靠这里的默认值推。
+        for key in DATA_ROOT_KEYS {
+            if let Some(value) = core.doc().get(key) {
+                overlay(&mut document, key, value.clone());
+            }
+        }
+    }
+    let mut problems = render_problems(&store);
+    if let Some(core) = &core_store {
+        problems.extend(render_problems(core));
+    }
+
+    let (document, masked) = if show_secret {
+        (document, false)
+    } else {
+        mask_document(&schema, &document)
+    };
+
+    let text = match serde_json::to_string_pretty(&document) {
+        Ok(text) => text,
+        Err(error) => return Err(CliError::internal("config_serialize", error.to_string())),
+    };
+    let mut human: Vec<String> = Vec::new();
+    human.push(format!("配置 {}（{:?}）", path.display(), store.compat()));
+    if let Some(core) = &core_path {
+        human.push(format!("数据根键（core.*）读的是 {}", core.display()));
+    }
+    human.push(format!(
+        "数据根：{}（launcher home {}，游戏目录 {}）",
+        ctx.data.mode.as_str(),
+        ctx.data.launcher_home.display(),
+        ctx.data.game_home.display()
+    ));
+    human.extend(text.lines().map(str::to_string));
+    for problem in &problems {
+        human.push(format!("问题：{problem}"));
+    }
+    if masked {
+        human.push("（敏感值已掩码；加 --show-secret 显示明文）".to_string());
+    }
+    Ok(Report::new(
+        json!({
+            "path": path.display().to_string(),
+            "core_path": core_path.as_ref().map(|core| core.display().to_string()),
+            "config": document,
+            "redacted": masked,
+            "problems": problems,
+            "data_root": {
+                "mode": ctx.data.mode.as_str(),
+                "launcher_home": ctx.data.launcher_home.display().to_string(),
+                "game_home": ctx.data.game_home.display().to_string(),
+            },
+        }),
+        human,
+    ))
+}
+
+/// `ull config set <key> <value>`。
+///
+/// 敏感键的**旧值回显要掩码**（新值是用户刚敲进来的，照常回显）。
+///
+/// # Errors
+///
+/// 键不在 schema、值不合法、文件只读/不可读、写盘失败时返回用户错误。
+pub fn set(ctx: &Ctx, key: &str, raw: &str) -> Result<Report, CliError> {
+    let path = ctx.setting_path_for(key);
+    let mut store = SettingStore::load(&path, launcher_schema());
+    let sensitive = is_sensitive(store.doc().schema(), key);
+    let value = parse_value(raw);
+    let old = store.effective(key).cloned().map(|old| {
+        if sensitive {
+            Value::String(MASK.to_string())
+        } else {
+            old
+        }
+    });
+    store.set(key, value.clone()).map_err(|error| {
+        CliError::user("config_set", error.to_string())
+            .with_hint(format!("键与取值范围见 {}", path.display()))
+    })?;
+
+    let outcome = store.save().map_err(|error| {
+        CliError::user(
+            "config_save",
+            format!("写 {} 失败：{error}", path.display()),
+        )
+    })?;
+    match &outcome {
+        SaveOutcome::Saved(saved) => {
+            let data = json!({
+                "key": key,
+                "old": old,
+                "new": value,
+                "saved": saved.display().to_string(),
+            });
+            let mut human = vec![
+                format!(
+                    "{key} = {}（原值 {}）",
+                    render_value(&value),
+                    render_value(&old.unwrap_or(Value::Null))
+                ),
+                format!("已保存：{}", saved.display()),
+            ];
+            human.extend(source_note(ctx, key));
+            Ok(Report::new(data, human))
+        }
+        SaveOutcome::Skipped(SkipReason::NotDirty) => Ok(Report::new(
+            json!({ "key": key, "new": value, "saved": null }),
+            vec![format!("{key} 已经是该值，未写盘")],
+        )),
+        SaveOutcome::Skipped(reason) => {
+            let error = CliError::user(
+                "config_read_only",
+                format!("{} 当前不可写（{}）", path.display(), reason.as_str()),
+            );
+            // 不可写常常不是权限问题，而是文件内容让加载降级（`$schema` 认不出 / 版本更高）。
+            let problems = render_problems(&store);
+            Err(if problems.is_empty() {
+                error.with_hint("修好文件权限/内容后重试")
+            } else {
+                error.with_hint(problems.join("；"))
+            })
+        }
+    }
+}
+
+/// 数据根键的落点说明（其余键不需要：它们的落点就是数据根本身）。
+fn source_note(ctx: &Ctx, key: &str) -> Option<String> {
+    if !is_data_root_key(key) {
+        return None;
+    }
+    if ctx.data_dir_forced() {
+        return Some(
+            "本次由 --data-dir 指定数据根：该键在下次不带 --data-dir 运行时生效".to_string(),
+        );
+    }
+    if ctx.setting_path_for(key) != ctx.launcher_config() {
+        return Some("该键决定数据根，落点是便携目录那份（与数据根解析同源）".to_string());
+    }
+    None
+}
+
+/// 加载问题 → 人读一行（`problems` 通道与人类可读输出共用）。
+fn render_problems(store: &SettingStore) -> Vec<String> {
+    store.problems().iter().map(ToString::to_string).collect()
+}
+
+/// 把 `key` 的生效值写进 dump 文档（点分键 → 嵌套对象）。
+fn overlay(root: &mut Value, key: &str, value: Value) {
+    let mut segments = key.split('.').filter(|part| !part.is_empty());
+    let Some(head) = segments.next() else {
+        return;
+    };
+    let rest: Vec<&str> = segments.collect();
+    let Some(map) = root.as_object_mut() else {
+        return;
+    };
+    if rest.is_empty() {
+        map.insert(head.to_string(), value);
+        return;
+    }
+    overlay(
+        map.entry(head.to_string())
+            .or_insert_with(|| Value::Object(Map::new())),
+        &rest.join("."),
+        value,
+    );
+}
+
+/// 值先按 JSON 解析（数字/布尔/对象），失败按字符串。
+fn parse_value(raw: &str) -> Value {
+    serde_json::from_str::<Value>(raw).unwrap_or_else(|_| Value::String(raw.to_string()))
+}
+
+/// 敏感键：schema 标 `High`，或键名本身命中 agent 的敏感词表（双保险）。
+fn is_sensitive(schema: &SettingSchema, key: &str) -> bool {
+    matches!(schema.sensitivity(key), Some(Sensitivity::High))
+        || unlucky_agent::redact::is_sensitive_key(key)
+}
+
+/// 递归掩码渲染后的配置文档，返回（掩码后的文档，是否掩过）。
+///
+/// `to_value()` 是**嵌套对象**（点分键展开成层级），所以按路径下钻；
+/// 命中敏感路径时整棵子树一起掩码，数组元素沿用父路径继续下钻。
+fn mask_document(schema: &SettingSchema, document: &Value) -> (Value, bool) {
+    mask_at(schema, "", document)
+}
+
+fn mask_at(schema: &SettingSchema, path: &str, value: &Value) -> (Value, bool) {
+    if !path.is_empty() && is_sensitive(schema, path) {
+        return (Value::String(MASK.to_string()), true);
+    }
+    match value {
+        Value::Object(map) => {
+            let mut out = Map::with_capacity(map.len());
+            let mut masked = false;
+            for (key, child) in map {
+                let child_path = if path.is_empty() {
+                    key.clone()
+                } else {
+                    format!("{path}.{key}")
+                };
+                let (child, child_masked) = mask_at(schema, &child_path, child);
+                masked |= child_masked;
+                out.insert(key.clone(), child);
+            }
+            (Value::Object(out), masked)
+        }
+        Value::Array(items) => {
+            let mut masked = false;
+            let redacted: Vec<Value> = items
+                .iter()
+                .map(|item| {
+                    let (item, item_masked) = mask_at(schema, path, item);
+                    masked |= item_masked;
+                    item
+                })
+                .collect();
+            (Value::Array(redacted), masked)
+        }
+        other => (other.clone(), false),
+    }
+}
+
+fn render_value(value: &Value) -> String {
+    match value {
+        Value::String(text) => text.clone(),
+        other => other.to_string(),
+    }
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/cli/src/commands/config/tests.rs b/crates/cli/src/commands/config/tests.rs
new file mode 100644
index 0000000..62a7a22
--- /dev/null
+++ b/crates/cli/src/commands/config/tests.rs
@@ -0,0 +1,256 @@
+//! [`super`] 的单测：数据根键与其余键的落点分流、dump 合并、`problems` 通道。
+
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use serde_json::{json, Value};
+
+use super::{dump, get, set};
+use crate::cli::Globals;
+use crate::context::Ctx;
+
+/// 一次性临时目录（`Drop` 时清理；cli 没有 dev-dependency 的 tempfile）。
+struct TempDir(PathBuf);
+
+impl TempDir {
+    fn new(tag: &str) -> Self {
+        static COUNTER: AtomicU64 = AtomicU64::new(0);
+        let nanos = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .map_or(0, |duration| duration.as_nanos());
+        let seq = COUNTER.fetch_add(1, Ordering::Relaxed);
+        let path = std::env::temp_dir().join(format!(
+            "ull-config-test-{tag}-{}-{seq}-{nanos}",
+            std::process::id()
+        ));
+        std::fs::create_dir_all(&path).expect("建临时目录");
+        Self(path)
+    }
+
+    fn path(&self) -> &Path {
+        &self.0
+    }
+}
+
+impl Drop for TempDir {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.0);
+    }
+}
+
+/// 正确的 `$schema`（写成真前缀，加载才不会降级）。
+fn schema_url() -> String {
+    use unlucky_core::setting::keys::launcher_version;
+    use unlucky_core::setting::schema::{SchemaId, SchemaRef};
+    SchemaRef::new(SchemaId::LAUNCHER, launcher_version()).url()
+}
+
+fn write_json(path: &Path, value: &Value) {
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent).expect("建目录");
+    }
+    std::fs::write(path, value.to_string()).expect("写配置");
+}
+
+fn read_json(path: &Path) -> Value {
+    let bytes = std::fs::read(path).unwrap_or_else(|e| panic!("读 {} 失败：{e}", path.display()));
+    serde_json::from_slice(&bytes).expect("合法 JSON")
+}
+
+fn ctx_with(globals: Globals, exe_dir: &Path) -> Ctx {
+    Ctx::resolve_in(&globals, Some(exe_dir.to_path_buf())).expect("解析数据根")
+}
+
+/// 便携模式：两个落点是同一份文件，`core.data_mode` 改了立刻是生效值。
+#[test]
+fn portable_mode_keeps_core_keys_in_one_file() {
+    let temp = TempDir::new("portable");
+    let ctx = ctx_with(Globals::default(), temp.path());
+    assert_eq!(ctx.data.mode.as_str(), "portable");
+    assert_eq!(
+        ctx.setting_path_for("core.data_mode"),
+        ctx.launcher_config(),
+        "便携模式下两份路径本来就该重合"
+    );
+
+    set(&ctx, "core.data_mode", "standard").expect("写 core.data_mode");
+    let file = temp
+        .path()
+        .join(".ULL")
+        .join("config")
+        .join("launcher.json");
+    assert!(file.is_file(), "应落在 {}", file.display());
+    assert_eq!(read_json(&file)["core"]["data_mode"], json!("standard"));
+
+    let report = get(&ctx, Some("core.data_mode"), true).expect("读回来");
+    // `core.*` 在 schema 里标了 `AiPolicy::sensitive()`（High），读路径默认掩码成
+    // `<redacted>`，所以要看生效值得像用户那样加 `--show-secret`。
+    assert_eq!(report.data["value"], json!("standard"));
+    assert_eq!(
+        report.data["path"],
+        json!(file.display().to_string()),
+        "read 与 write 必须同一份"
+    );
+}
+
+/// standard 模式：数据根键走便携目录那份（与解析同源），其余键走数据根。
+#[test]
+fn standard_mode_routes_core_keys_to_the_portable_file() {
+    let temp = TempDir::new("standard");
+    let exe = temp.path().join("exe");
+    let portable = exe.join(".ULL").join("config").join("launcher.json");
+    let launcher_home = temp.path().join("lhome");
+    write_json(
+        &portable,
+        &json!({
+            "$schema": schema_url(),
+            "schemaVersion": 1,
+            "core": {
+                "data_mode": "standard",
+                "launcher_home": launcher_home.display().to_string(),
+            },
+        }),
+    );
+
+    let ctx = ctx_with(Globals::default(), &exe);
+    assert_eq!(ctx.data.mode.as_str(), "standard");
+    assert_eq!(ctx.data.launcher_home, launcher_home);
+    assert_ne!(
+        ctx.setting_path_for("core.data_mode"),
+        ctx.launcher_config()
+    );
+
+    let report = get(&ctx, Some("core.data_mode"), true).expect("读 core.data_mode");
+    assert_eq!(
+        report.data["value"],
+        json!("standard"),
+        "get 展示的必须是真正生效的值"
+    );
+    assert_eq!(report.data["path"], json!(portable.display().to_string()));
+
+    // 普通键仍写数据根。
+    set(&ctx, "download.concurrency", "16").expect("写 download.concurrency");
+    let core_file = ctx.launcher_config();
+    assert_eq!(read_json(&core_file)["download"]["concurrency"], json!(16));
+
+    // 数据根键写便携目录那份，且不动数据根那份的 core.*。
+    set(&ctx, "core.data_mode", "portable").expect("写 core.data_mode");
+    assert_eq!(read_json(&portable)["core"]["data_mode"], json!("portable"));
+    assert!(
+        read_json(&core_file)["core"].get("data_mode").is_none(),
+        "数据根那份不该被写入 core.data_mode"
+    );
+}
+
+/// `--data-dir` 模式：数据根由命令行钉死，core.* 仍落便携目录那份并给出提示。
+#[test]
+fn data_dir_flag_routes_core_keys_to_portable_and_says_so() {
+    let temp = TempDir::new("datadir");
+    let exe = temp.path().join("exe");
+    std::fs::create_dir_all(&exe).expect("建 exe 目录");
+    let data = temp.path().join("data");
+    let globals = Globals {
+        data_dir: Some(data.clone()),
+        ..Globals::default()
+    };
+    let ctx = ctx_with(globals, &exe);
+    assert_eq!(ctx.data.mode.as_str(), "custom");
+    assert_eq!(ctx.data.launcher_home, data.join(".ULL"));
+
+    let portable = exe.join(".ULL").join("config").join("launcher.json");
+    set(&ctx, "core.data_mode", "standard").expect("写 core.data_mode");
+    assert!(portable.is_file(), "应落在 {}", portable.display());
+    assert!(!data
+        .join(".ULL")
+        .join("config")
+        .join("launcher.json")
+        .exists());
+
+    let report = get(&ctx, Some("core.data_mode"), true).expect("读回来");
+    assert_eq!(report.data["value"], json!("standard"));
+    assert!(
+        report.human.iter().any(|line| line.contains("--data-dir")),
+        "{:?}",
+        report.human
+    );
+}
+
+/// 全量 dump：`core.*` 取便携目录那份的生效值，并标明两份文件与数据根。
+#[test]
+fn dump_merges_core_keys_from_the_portable_file() {
+    let temp = TempDir::new("dump");
+    let exe = temp.path().join("exe");
+    let portable = exe.join(".ULL").join("config").join("launcher.json");
+    let launcher_home = temp.path().join("home2");
+    write_json(
+        &portable,
+        &json!({
+            "$schema": schema_url(),
+            "schemaVersion": 1,
+            "core": {
+                "data_mode": "standard",
+                "launcher_home": launcher_home.display().to_string(),
+            },
+        }),
+    );
+    // 数据根那份写一个普通键（默认值不落盘，dump 里只有文件里真有的键）。
+    write_json(
+        &launcher_home.join("config").join("launcher.json"),
+        &json!({
+            "$schema": schema_url(),
+            "schemaVersion": 1,
+            "download": { "concurrency": 4 },
+        }),
+    );
+    let ctx = ctx_with(Globals::default(), &exe);
+
+    let report = dump(&ctx, true).expect("全量 dump");
+    assert_eq!(
+        report.data["config"]["core"]["data_mode"],
+        json!("standard")
+    );
+    assert_eq!(
+        report.data["core_path"],
+        json!(portable.display().to_string())
+    );
+    assert_eq!(report.data["data_root"]["mode"], json!("standard"));
+    assert_eq!(
+        report.data["config"]["download"]["concurrency"],
+        json!(4),
+        "非 core.* 键仍取数据根那份"
+    );
+}
+
+/// 认不出的 `$schema` 前缀：值照读 + `problems` 里有 UnknownSchema，不再静默回落。
+#[test]
+fn unknown_schema_prefix_warns_and_still_shows_file_values() {
+    let temp = TempDir::new("badschema");
+    let exe = temp.path().join("exe");
+    let portable = exe.join(".ULL").join("config").join("launcher.json");
+    write_json(
+        &portable,
+        &json!({
+            "$schema": "https://unlucky-launcher.local/schema/launcher/1.2.0.json",
+            "schemaVersion": 1,
+            "core": { "data_mode": "portable" },
+            "download": { "concurrency": 32 },
+        }),
+    );
+    let ctx = ctx_with(Globals::default(), &exe);
+
+    let report = get(&ctx, Some("download.concurrency"), false).expect("读普通键");
+    assert_eq!(report.data["value"], json!(32), "值不该被回落成默认 8");
+    let problems = report.data["problems"].as_array().expect("problems 数组");
+    assert!(
+        problems
+            .iter()
+            .any(|problem| problem.as_str().is_some_and(|p| p.contains("$schema"))),
+        "{problems:?}"
+    );
+    assert!(
+        report.human.iter().any(|line| line.contains("$schema")),
+        "{:?}",
+        report.human
+    );
+}
diff --git a/crates/cli/src/commands/identity.rs b/crates/cli/src/commands/identity.rs
new file mode 100644
index 0000000..3944f17
--- /dev/null
+++ b/crates/cli/src/commands/identity.rs
@@ -0,0 +1,216 @@
+//! `ull launch` 的账户选择：三轨账户 → [`AuthPlaceholders`]（唯一的身份出口）。
+//!
+//! 选择规则（headless 没有交互，必须确定）：
+//! - `--account <name>`：按玩家名 / 登录名 / 条目 id 精确找（大小写不敏感）；
+//! - 不给 `--account`：**唯一账户自动选中**；零账户回落离线占位（`--username` 或 `Player`，
+//!   与 M21 的行为一致，保证没有账户时 `ull launch` 照旧能跑）；多账户报错并列出候选
+//!   （猜一个等于让用户拿错身份进服务器，宁可让他选）。
+//!
+//! 令牌策略：`--dry-run` **不刷新、不写盘**（M30 的 dry-run 纯读语义），只对过期状态给告警；
+//! 真启动前对微软轨做一次 `ensure_fresh`（静默续期），刷新成功立刻回写凭据
+//! （refresh_token 轮换后旧值就作废了，不能丢）。
+
+use unlucky_core::auth::account::{AccountKind, AccountMeta, Credentials};
+use unlucky_core::auth::microsoft::MicrosoftAuth;
+use unlucky_core::auth::offline::offline_login;
+use unlucky_core::auth::AccountStore;
+use unlucky_core::download::blocking::block_on;
+use unlucky_core::game::ProfileId;
+use unlucky_core::launch::request::AuthPlaceholders;
+
+use crate::context::Ctx;
+use crate::error::CliError;
+
+/// 解析结果。
+pub struct Identity {
+    /// 喂给 launch 的占位符集合。
+    pub placeholders: AuthPlaceholders,
+    /// 选中的账户（`None` = 离线占位，没有账户）。
+    pub account: Option<AccountMeta>,
+    /// 需要展示给用户的说明（令牌过期、authlib 注入未落地等）。
+    pub notes: Vec<String>,
+}
+
+/// 解析本次启动的身份。
+///
+/// # Errors
+///
+/// 账户不存在/重名冲突/多账户未指定/凭据过期且刷新失败/凭据文件缺条目。
+pub fn resolve(
+    ctx: &Ctx,
+    account: Option<&str>,
+    username: Option<&str>,
+    dry_run: bool,
+) -> Result<Identity, CliError> {
+    let store = AccountStore::open(ctx.auth_data());
+    let chosen: Option<AccountMeta> = match account {
+        Some(key) => Some(
+            store
+                .find(key)
+                .ok_or_else(|| unknown_account(key, &store))?
+                .clone(),
+        ),
+        None => match store.accounts() {
+            [] => None,
+            [only] => Some(only.clone()),
+            many => {
+                return Err(CliError::user(
+                    "account_ambiguous",
+                    format!("有 {} 个账户，需要指定用哪个", many.len()),
+                )
+                .with_hint(format!(
+                    "%prog% launch <instance> --account <名字>；候选：{}",
+                    names_of(&store)
+                )))
+            }
+        },
+    };
+
+    let Some(meta) = chosen else {
+        // 零账户：回落离线占位（保留 M21 行为）。
+        return Ok(offline_fallback(username));
+    };
+    if username.is_some() {
+        return Err(CliError::usage(format!(
+            "已选中账户 {}，`--username` 只用于没有账户时的离线占位",
+            meta.display_name()
+        ))
+        .with_hint("去掉 --username，或用 `%prog% accounts add offline <名字>` 建账户"));
+    }
+
+    let mut notes = Vec::new();
+    let placeholders = match meta.kind {
+        AccountKind::Offline => offline_login(&meta).map_err(super::map_auth_error)?,
+        AccountKind::Microsoft => microsoft_identity(ctx, &store, &meta, dry_run, &mut notes)?,
+        AccountKind::AuthlibInjector => authlib_identity(&store, &meta, &mut notes)?,
+    };
+    Ok(Identity {
+        placeholders,
+        account: Some(meta),
+        notes,
+    })
+}
+
+/// 零账户时的离线占位（uuid 随机，userType 用 HMCL 的 `legacy` 占位口径不变）。
+fn offline_fallback(username: Option<&str>) -> Identity {
+    Identity {
+        placeholders: AuthPlaceholders {
+            player_name: username.unwrap_or("Player").to_string(),
+            uuid: ProfileId::generate().as_str().replace('-', ""),
+            user_type: "legacy".to_string(),
+            user_properties: "{}".to_string(),
+            ..AuthPlaceholders::default()
+        },
+        account: None,
+        notes: vec![
+            "没有账户，按离线占位启动（%prog% accounts add offline <名字> 可建账户）".to_string(),
+        ],
+    }
+}
+
+fn microsoft_identity(
+    ctx: &Ctx,
+    store: &AccountStore,
+    meta: &AccountMeta,
+    dry_run: bool,
+    notes: &mut Vec<String>,
+) -> Result<AuthPlaceholders, CliError> {
+    let Some(Credentials::Microsoft(session)) = store.credentials(&meta.id) else {
+        return Err(CliError::user(
+            "account_credentials",
+            format!("账户 {} 的微软凭据缺失或类型不符", meta.display_name()),
+        )
+        .with_hint("重新登录：%prog% accounts add msa"));
+    };
+
+    if dry_run {
+        // dry-run 不刷新：令牌过期只提示，命令行里的 token 反正会被脱敏。
+        if session.is_expired(unlucky_core::auth::microsoft::now_ms()) {
+            notes.push("微软令牌已过期（--dry-run 不刷新，真启动会自动续期）".to_string());
+        }
+        return session.to_placeholders().map_err(super::map_auth_error);
+    }
+
+    let auth = MicrosoftAuth::from_env().map_err(super::map_auth_error)?;
+    let (refreshed, reason) =
+        block_on(auth.ensure_fresh(session)).map_err(super::map_auth_error)?;
+    if let Some(reason) = reason {
+        notes.push(format!("{}（已静默续期）", reason.message()));
+        persist_refresh(ctx, meta, &refreshed)?;
+    }
+    refreshed.to_placeholders().map_err(super::map_auth_error)
+}
+
+/// 刷新成功后立刻回写凭据（refresh_token 已轮换，旧值作废）。
+fn persist_refresh(
+    ctx: &Ctx,
+    meta: &AccountMeta,
+    session: &unlucky_core::auth::MicrosoftSession,
+) -> Result<(), CliError> {
+    let mut store = AccountStore::open(ctx.auth_data());
+    store
+        .update_credentials(&meta.id, Credentials::Microsoft(session.clone()))
+        .map_err(super::map_auth_error)?;
+    let mut updated = meta.clone();
+    // profile_name 属于可变的私有缓存，刷新后顺手把元数据里的展示名补上。
+    if !session.profile_name.trim().is_empty() {
+        updated.profile_name = session.profile_name.clone();
+        store.update_meta(updated).map_err(super::map_auth_error)?;
+    }
+    store.save().map_err(super::map_auth_error)
+}
+
+fn authlib_identity(
+    store: &AccountStore,
+    meta: &AccountMeta,
+    notes: &mut Vec<String>,
+) -> Result<AuthPlaceholders, CliError> {
+    let Some(Credentials::AuthlibInjector(session)) = store.credentials(&meta.id) else {
+        return Err(CliError::user(
+            "account_credentials",
+            format!("账户 {} 的 authlib 凭据缺失或类型不符", meta.display_name()),
+        ));
+    };
+    if !session.has_profile() {
+        return Err(CliError::user(
+            "account_credentials",
+            format!("账户 {} 还没有选中角色", meta.display_name()),
+        )
+        .with_hint("多角色服务器要在图形界面里选角色"));
+    }
+    notes.push("authlib-injector 的 -javaagent 参数属后续 mission，本次启动不会注入".to_string());
+    session.to_placeholders().map_err(super::map_auth_error)
+}
+
+fn names_of(store: &AccountStore) -> String {
+    store
+        .accounts()
+        .iter()
+        .map(|meta| meta.display_name().to_string())
+        .collect::<Vec<_>>()
+        .join("、")
+}
+
+fn unknown_account(key: &str, store: &AccountStore) -> CliError {
+    let hint = if store.is_empty() {
+        "还没有账户：%prog% accounts add offline <名字> 或 %prog% accounts add msa".to_string()
+    } else {
+        format!("可用账户：{}", names_of(store))
+    };
+    CliError::user("not_found", format!("找不到账户 `{key}`")).with_hint(hint)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::offline_fallback;
+
+    #[test]
+    fn fallback_uses_username_or_player() {
+        let identity = offline_fallback(Some("Alex"));
+        assert_eq!(identity.placeholders.player_name, "Alex");
+        assert!(identity.account.is_none());
+        assert_eq!(identity.placeholders.user_type, "legacy");
+        assert_eq!(identity.placeholders.uuid.len(), 32);
+        assert_eq!(offline_fallback(None).placeholders.player_name, "Player");
+    }
+}
diff --git a/crates/cli/src/commands/install/loader.rs b/crates/cli/src/commands/install/loader.rs
new file mode 100644
index 0000000..4a7fb7c
--- /dev/null
+++ b/crates/cli/src/commands/install/loader.rs
@@ -0,0 +1,159 @@
+//! `ull install <version> --loader <kind> [--loader-version <v>]`：加载器层的编排。
+//!
+//! ```text
+//! LoaderSource::resolve（官方 meta：版本列表 → profile JSON / installer profile）
+//!   → LoaderInstallPlan::build（纯计算：库清单 + loader 版本 JSON 落点）
+//!   → [--dry-run 到此为止，但多带一段 processors 计划]
+//!   → 原版已装？否 → vanilla::plan_and_install（先装原版）
+//!   → 需要 installer？→ 依赖库 → 选 Java → 串行跑 processors（M35）
+//!   → execute（loader 库并发下载 → 全量就绪才写 versions/<loader-id>/<loader-id>.json）
+//!   → register（实例 versionId 指向 loader 版本）
+//! ```
+//!
+//! 「先装原版」是**硬前置**：loader 版本 JSON 只声明 `inheritsFrom`，jar 与资源都在原版那层，
+//! 原版缺失时启动链必然断裂。已装则跳过（`is_version_installed` 判据 = 版本 JSON 在盘上）。
+//!
+//! processors 段的顺序也是硬约束：**先跑 processors，再写版本 JSON**。版本清单存在是
+//! "这版装完了"的判据，抢在 processors 前写会留下一个启动必崩却被报成已安装的实例。
+
+use unlucky_core::addon::loader::{
+    LoaderError, LoaderInstallPlan, LoaderKind, LoaderPlanInput, LoaderSource,
+};
+use unlucky_core::download::blocking::block_on;
+use unlucky_core::download::cache::now_ms;
+use unlucky_core::game::arguments::Environment;
+use unlucky_core::game::install::execute;
+
+use super::report_loader::ProcessorSection;
+use super::{
+    build_engine, ensure_name_free, failure_error, loader_processors, map_install_error,
+    register_instance, report, report_loader, vanilla, CONCURRENCY,
+};
+use crate::cli::InstallArgs;
+use crate::context::Ctx;
+use crate::error::CliError;
+use crate::output::Report;
+
+/// 执行加载器安装。
+///
+/// # Errors
+///
+/// 用法错误、加载器未知/不支持、元数据读取失败、原版装不上、库下载失败、
+/// installer processors 失败、实例登记失败。
+pub(super) fn run(ctx: &Ctx, args: &InstallArgs, kind: LoaderKind) -> Result<Report, CliError> {
+    let version = args.version.trim().to_string();
+    if version.is_empty() {
+        return Err(CliError::usage(
+            "install 需要版本 id：%prog% install <version> --loader fabric",
+        ));
+    }
+
+    let engine = build_engine(ctx);
+    let layout = ctx.layout();
+    let game = ctx.game();
+    let meta_cache = layout.meta_cache();
+    let now = now_ms();
+
+    let release = block_on(async {
+        let source = LoaderSource::new(&engine, &meta_cache);
+        source
+            .resolve(kind, &version, args.loader_version.as_deref())
+            .await
+    })
+    .map_err(|error: LoaderError| map_loader_error(&error, ctx))?;
+
+    let name = args
+        .name
+        .clone()
+        .filter(|name| !name.trim().is_empty())
+        .unwrap_or_else(|| release.version_id.clone());
+    ensure_name_free(ctx, &name, &release.version_id)?;
+
+    let plan = LoaderInstallPlan::build(LoaderPlanInput {
+        layout: &game,
+        release: &release,
+        environment: &Environment::host(),
+        vanilla_installed: game.is_version_installed(&version),
+    });
+    let processor_plan = loader_processors::plan(ctx, &release)?;
+
+    if args.dry_run {
+        let section = processor_plan.as_ref().map(|plan| ProcessorSection {
+            plan,
+            libraries: None,
+            run: None,
+            skipped: false,
+        });
+        return Ok(report_loader::build(
+            ctx, &engine, now, true, &plan, None, None, &name, section,
+        ));
+    }
+
+    if plan.vanilla_install_needed {
+        let (_, vanilla_report) = vanilla::plan_and_install(
+            ctx,
+            &engine,
+            &version,
+            false,
+            args.progress,
+            args.json_progress,
+        )?;
+        if let Some(report) = &vanilla_report {
+            if !report.is_complete() {
+                return Err(failure_error(report, ctx));
+            }
+        }
+    }
+
+    // installer processors 段：版本 JSON 已在盘上 = 上一轮早已跑完，整段跳过。
+    let mut processor_libs = None;
+    let mut processor_run = None;
+    let mut processor_skipped = false;
+    if let Some(processor_plan) = &processor_plan {
+        if game.is_version_installed(&release.version_id) {
+            processor_skipped = true;
+        } else {
+            let (libraries, run) = loader_processors::execute(ctx, &engine, processor_plan, args)?;
+            processor_libs = Some(libraries);
+            processor_run = Some(run);
+        }
+    }
+
+    let sink = report::progress_sink(args.progress, args.json_progress, plan.files().len());
+    let install_report = block_on(execute(&engine, &plan.install, CONCURRENCY, sink))
+        .map_err(|error| map_install_error(&error, ctx))?;
+    if !install_report.is_complete() {
+        return Err(failure_error(&install_report, ctx));
+    }
+
+    let registration = register_instance(ctx, &name, &release.version_id)?;
+
+    let section = processor_plan
+        .as_ref()
+        .map(|processor_plan| ProcessorSection {
+            plan: processor_plan,
+            libraries: processor_libs.as_ref(),
+            run: processor_run.as_ref(),
+            skipped: processor_skipped,
+        });
+    Ok(report_loader::build(
+        ctx,
+        &engine,
+        now,
+        false,
+        &plan,
+        Some(&install_report),
+        Some(&registration),
+        &name,
+        section,
+    ))
+}
+
+/// 加载器错误 → CLI 错误（稳定码 `loader_*`）。
+fn map_loader_error(error: &LoaderError, ctx: &Ctx) -> CliError {
+    let hint = match error.hint() {
+        Some(hint) => format!("{hint}（游戏根：{}）", ctx.game().root().display()),
+        None => format!("游戏根：{}", ctx.game().root().display()),
+    };
+    CliError::user(error.kind().as_str(), error.message().to_string()).with_hint(hint)
+}
diff --git a/crates/cli/src/commands/install/loader_processors.rs b/crates/cli/src/commands/install/loader_processors.rs
new file mode 100644
index 0000000..60d1347
--- /dev/null
+++ b/crates/cli/src/commands/install/loader_processors.rs
@@ -0,0 +1,181 @@
+//! 加载器的 installer processors 段（M35）：依赖库下载 → 选 Java → 串行执行。
+//!
+//! 只在 `LoaderSupport::RequiresInstaller` 的版本上出现（Forge 1.13~1.20.x 主流段、
+//! NeoForge 1.20.5+）。其余加载器（Fabric/Quilt、Forge spec 0）走纯 json 路线，这一段整块跳过。
+//!
+//! ```text
+//! ProcessorPlan::build（core，纯计算：变量表 + 每步命令行 + 依赖库清单）
+//!   → download_libraries（M27 引擎：镜像/健康度/退避/校验）
+//!   → select_java（M33 解析链：托管 > JAVA_HOME > PATH > 扫盘）
+//!   → run（串行 java -cp，产物存在性硬校验、摘要软校验）
+//! ```
+//!
+//! 顺序上与版本 JSON 的关系是**硬约束**：processors 全部成功之后才让 M27 的 `execute`
+//! 写 `versions/<id>/<id>.json`——那份清单是"这版装完了"的判据，抢在 processors 前写会
+//! 留下一个启动必崩却被报成"已安装"的实例。
+
+use std::sync::Arc;
+
+use unlucky_core::addon::loader::processors::{
+    self, ProcessorError, ProcessorPlan, ProcessorPlanInput, ProcessorRun, StepOutcome, StepSink,
+};
+use unlucky_core::addon::loader::LoaderRelease;
+use unlucky_core::download::blocking::block_on;
+use unlucky_core::download::DownloadEngine;
+use unlucky_core::game::arguments::Environment;
+use unlucky_core::game::install::InstallReport;
+
+use super::{failure_error, report, CONCURRENCY};
+use crate::cli::InstallArgs;
+use crate::context::Ctx;
+use crate::error::CliError;
+use crate::output::progress_line;
+
+/// 组执行计划；不需要跑 installer 的加载器返回 `None`。
+///
+/// # Errors
+///
+/// install profile 的 `data` 表/`processors` 形状不对时返回 `processor_plan` 错误。
+pub(super) fn plan(ctx: &Ctx, release: &LoaderRelease) -> Result<Option<ProcessorPlan>, CliError> {
+    if !release.requires_installer() {
+        return Ok(None);
+    }
+    let (Some(profile), Some(installer)) = (
+        release.install_profile.as_ref(),
+        release.installer.as_deref(),
+    ) else {
+        return Err(CliError::user(
+            "loader_metadata",
+            format!(
+                "{} {} 需要跑 installer processors，但没拿到 install profile / installer 路径",
+                release.kind.label(),
+                release.loader_version
+            ),
+        )
+        .with_hint("重跑一次（元数据缓存可能不完整）"));
+    };
+    let game = ctx.game();
+    let scratch = ctx
+        .layout()
+        .cache()
+        .join("processors")
+        .join(safe_name(&release.version_id));
+    let plan = ProcessorPlan::build(ProcessorPlanInput {
+        kind: release.kind,
+        mc_version: &release.mc_version,
+        version_id: &release.version_id,
+        profile,
+        layout: &game,
+        installer,
+        scratch: &scratch,
+        environment: &Environment::host(),
+    })
+    .map_err(map_processor_error)?;
+    Ok(Some(plan))
+}
+
+/// 下载依赖库 + 执行 processors。
+///
+/// # Errors
+///
+/// 依赖库下载失败（稳定码沿用 `install_*`）、找不到可用 Java、processor 非零退出、
+/// 产物没落盘。
+pub(super) fn execute(
+    ctx: &Ctx,
+    engine: &DownloadEngine,
+    plan: &ProcessorPlan,
+    args: &InstallArgs,
+) -> Result<(InstallReport, ProcessorRun), CliError> {
+    let sink = report::progress_sink(args.progress, args.json_progress, plan.libraries.len());
+    let libraries = block_on(processors::download_libraries(
+        engine,
+        &plan.libraries,
+        CONCURRENCY,
+        sink,
+    ));
+    if !libraries.is_complete() {
+        return Err(failure_error(&libraries, ctx));
+    }
+
+    let managed = ctx.layout().java_managed();
+    let Some(java) = processors::select_java(&managed, &plan.java_requirement) else {
+        return Err(CliError::user(
+            "processor_java_missing",
+            format!(
+                "跑 installer processors 需要 {}，但一个可用的 Java 都没找到",
+                plan.java_requirement.describe()
+            ),
+        )
+        .with_hint(format!(
+            "`%prog% java install {}` 装一个托管 JDK，或把 JAVA_HOME 指向可用的 JDK（托管目录 {}）",
+            plan.java_requirement.minimum,
+            managed.display()
+        )));
+    };
+    let sink = step_sink(args.progress, args.json_progress, plan.step_count());
+    let run = processors::run(plan, &java, sink).map_err(map_processor_error)?;
+    Ok((libraries, run))
+}
+
+/// 每步一行的实时进度（只写 stderr）。
+fn step_sink(enabled: bool, json_mode: bool, total: usize) -> Option<StepSink> {
+    if !enabled {
+        return None;
+    }
+    Some(Arc::new(move |outcome: &StepOutcome| {
+        let record = serde_json::json!({
+            "event": "processor",
+            "index": outcome.index,
+            "total": total,
+            "jar": outcome.label,
+            "status": outcome.status.as_str(),
+            "elapsed_ms": outcome.elapsed_ms,
+        });
+        let text = format!(
+            "processor {}/{} {} → {}（输出 {} 个{}）",
+            outcome.index,
+            total,
+            outcome.label,
+            if outcome.status.as_str() == "skipped" {
+                "跳过（产物已就绪）"
+            } else {
+                "执行完成"
+            },
+            outcome.outputs,
+            if outcome.elapsed_ms > 0 {
+                format!("，{} ms", outcome.elapsed_ms)
+            } else {
+                String::new()
+            }
+        );
+        if json_mode {
+            progress_line(&record.to_string());
+        } else {
+            progress_line(&text);
+        }
+    }))
+}
+
+/// processor 执行错误 → CLI 错误（稳定码 `processor_*`）。
+fn map_processor_error(error: ProcessorError) -> CliError {
+    let cli = CliError::user(error.kind().as_str(), error.message().to_string());
+    match error.hint() {
+        Some(hint) => cli.with_hint(hint.to_string()),
+        None => cli,
+    }
+}
+
+/// 版本 id → 可做目录名的片段（`+` 与路径分隔符都换掉）。
+fn safe_name(raw: &str) -> String {
+    raw.chars()
+        .map(|ch| {
+            if ch.is_ascii_alphanumeric() || matches!(ch, '.' | '-' | '_') {
+                ch
+            } else {
+                '_'
+            }
+        })
+        .collect::<String>()
+        .trim_end_matches('.')
+        .to_string()
+}
diff --git a/crates/cli/src/commands/install/mod.rs b/crates/cli/src/commands/install/mod.rs
new file mode 100644
index 0000000..2d3553f
--- /dev/null
+++ b/crates/cli/src/commands/install/mod.rs
@@ -0,0 +1,151 @@
+//! `ull install <version> [--loader <kind>] [--loader-version <v>]`：装版本本体 / 装加载器层。
+//!
+//! ```text
+//! --loader 缺省        → vanilla：M27 原版安装（resolve → plan → execute → register）
+//! --loader fabric|quilt → addon::loader：原版（已装则跳）→ loader 版本 JSON → 补 loader 库 → register
+//! --loader neoforge|forge → 同上；需要 installer processors 的版本再跑 M35 执行器（依赖库 → java → 版本 JSON）
+//! ```
+//!
+//! CLI 只做四件事：建下载引擎、把计划/结果排版成人读与 `--json` 两种形态
+//! （[`report`] / [`report_loader`]）、把错误翻译成稳定错误码、往 stderr 打实时进度。
+//! 所有版本/继承/库/下载逻辑都在 core（CLI 不复制任何路径或镜像规则）。
+
+mod loader;
+mod loader_processors;
+mod report;
+mod report_loader;
+mod vanilla;
+
+use std::sync::Arc;
+
+use unlucky_core::addon::loader::LoaderKind;
+use unlucky_core::download::cache::now_ms;
+use unlucky_core::download::region::{decide_from, load_cached, store_cached};
+use unlucky_core::download::region_system::detect_signals;
+use unlucky_core::download::{
+    ContentCache, DownloadEngine, DownloadErrorKind, EngineConfig, HealthRegistry, MirrorTable,
+};
+use unlucky_core::game::install::{InstallError, InstallReport, Registration};
+
+use crate::cli::InstallArgs;
+use crate::context::Ctx;
+use crate::error::CliError;
+use crate::output::Report;
+
+/// 文件级并发上限：资源是海量小文件，16 路足够压满带宽又不至于打爆镜像。
+pub(super) const CONCURRENCY: usize = 16;
+
+/// 执行 `install`：按 `--loader` 分发。
+///
+/// # Errors
+///
+/// 用法错误、加载器未知、版本不存在、网络失败、校验不符、写盘失败、实例清单损坏。
+pub fn run(ctx: &Ctx, args: &InstallArgs) -> Result<Report, CliError> {
+    match args
+        .loader
+        .as_deref()
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+    {
+        None | Some("vanilla") | Some("none") => vanilla::run(ctx, args),
+        Some(raw) => match LoaderKind::parse(raw) {
+            Some(kind) => loader::run(ctx, args, kind),
+            None => Err(
+                CliError::user("loader_unknown", format!("未知加载器 `{raw}`"))
+                    .with_hint("--loader 取值：vanilla / fabric / quilt / neoforge / forge"),
+            ),
+        },
+    }
+}
+
+/// 登记实例（幂等）：`profiles.json` + `config/instances/<id>.json`。
+///
+/// 原版安装与加载器安装共用：前者 `version_id` = 原版 id，后者 = loader 版本 id
+/// （实例的 `versionId` 必须指向 loader 版本，否则启动会跑成原版）。
+pub(super) fn register_instance(
+    ctx: &Ctx,
+    name: &str,
+    version_id: &str,
+) -> Result<Registration, CliError> {
+    let created_at =
+        unlucky_core::launch::time::format_rfc3339_millis(unlucky_core::launch::time::now());
+    unlucky_core::game::install::instance::register(
+        &ctx.layout(),
+        name,
+        version_id,
+        Some(&created_at),
+    )
+    .map_err(|error| CliError::user("instance_register", format!("登记实例失败：{error}")))
+}
+
+/// 建下载引擎：内容寻址缓存落 `.ULL/cache/`，地区判定走 24h 缓存 + 环境信号。
+///
+/// 地区判定**不做网络探测**（P2 首版；探测开关属设置层接线），
+/// 因此中文环境默认镜像优先、其它环境直连——与 D7 的"不探测时"约定一致。
+pub(super) fn build_engine(ctx: &Ctx) -> DownloadEngine {
+    let layout = ctx.layout();
+    let cache_root = layout.cache();
+    let now = now_ms();
+    let region_path = cache_root.join("region.json");
+    let region = load_cached(&region_path, now).unwrap_or_else(|| {
+        let profile = decide_from(&detect_signals(), now);
+        let _ = store_cached(&region_path, &profile);
+        profile
+    });
+    DownloadEngine::new(
+        EngineConfig::default(),
+        Arc::new(MirrorTable::builtin()),
+        Arc::new(region),
+        Arc::new(HealthRegistry::open_in(&cache_root, now)),
+        Arc::new(ContentCache::open(&cache_root)),
+    )
+}
+
+/// 同名但绑定别的版本 → 冲突；同名同版本视为重装（复用实例，允许）。
+pub(super) fn ensure_name_free(ctx: &Ctx, name: &str, version: &str) -> Result<(), CliError> {
+    let profiles = super::instances::read_profiles(ctx)?;
+    let conflict = profiles
+        .profiles
+        .iter()
+        .find(|profile| profile.name == name && profile.version_id != version);
+    match conflict {
+        Some(profile) => Err(CliError::user(
+            "instance_exists",
+            format!("同名实例已存在：{name}（绑定版本 {}）", profile.version_id),
+        )
+        .with_hint("用 --name 换个名字，或 `%prog% instances list` 看看现有实例")),
+        None => Ok(()),
+    }
+}
+
+/// 安装期错误 → CLI 错误（保留稳定错误码与提示）。
+pub(super) fn map_install_error(error: &InstallError, ctx: &Ctx) -> CliError {
+    let hint = match error.hint() {
+        Some(hint) => format!("{hint}（游戏根：{}）", ctx.game().root().display()),
+        None => format!("游戏根：{}", ctx.game().root().display()),
+    };
+    CliError::user(error.kind().as_str(), error.message().to_string()).with_hint(hint)
+}
+
+/// 有文件失败 → 按"最严重的失败类别"给稳定码，并列出前几条明细。
+pub(super) fn failure_error(report: &InstallReport, ctx: &Ctx) -> CliError {
+    let code = match report.failure_kind() {
+        Some(DownloadErrorKind::Integrity) => "install_integrity",
+        Some(DownloadErrorKind::Io) => "install_io",
+        _ => "install_network",
+    };
+    let mut message = format!(
+        "{} 个文件没下成（共 {} 个）",
+        report.failed(),
+        report.files.len()
+    );
+    for outcome in report.failures(3) {
+        if let Some(failure) = &outcome.failure {
+            message.push_str(&format!("；{}：{}", outcome.name, failure.message));
+        }
+    }
+    CliError::user(code, message).with_hint(format!(
+        "重跑 `%prog% install` 会续传并跳过已就绪文件；游戏根 {}",
+        ctx.game().root().display()
+    ))
+}
diff --git a/crates/cli/src/commands/install/report.rs b/crates/cli/src/commands/install/report.rs
new file mode 100644
index 0000000..af04893
--- /dev/null
+++ b/crates/cli/src/commands/install/report.rs
@@ -0,0 +1,262 @@
+//! 安装结果的两种呈现形态：人类可读行 + `--json` 载荷，外加 stderr 实时进度。
+//!
+//! 拆出来是因为 `install` 的流程（规划 → 下载 → 登记）与排版彼此独立：
+//! 前者要能读懂，后者要能被脚本断言。`--dry-run` 与真实安装共用同一份排版，
+//! 差别只是多出逐文件清单与源选择。
+
+use std::sync::atomic::{AtomicUsize, Ordering};
+use std::sync::Arc;
+
+use serde_json::json;
+use unlucky_core::download::DownloadEngine;
+use unlucky_core::game::install::{
+    FileOutcome, InstallPlan, InstallReport, ProgressSink, Registration,
+};
+
+use crate::context::Ctx;
+use crate::output::{progress_line, Report};
+
+/// 每处理多少个文件打一行进度（3000 个资源下约 90 行，够用又不刷屏）。
+const PROGRESS_EVERY: usize = 32;
+
+/// 进度里最多逐条打印几条失败（其余交给最终错误汇总）。
+const MAX_PROGRESS_FAILURES: usize = 5;
+
+/// 实时进度回调（只写 stderr，不污染 `--json` 的 stdout）。
+///
+/// 两种形态：人类模式打文本行；`--json` 模式打 **JSONL**（一行一条事件，`event` 字段分流），
+/// 这样脚本既能吃 stdout 的最终信封，也能实时跟进而不必解析文本。
+///
+/// 失败行只打前几条：整源不可达时会一口气失败上千个文件，全打出来既没用又淹没原因。
+pub fn progress_sink(enabled: bool, json: bool, total: usize) -> Option<ProgressSink> {
+    if !enabled {
+        return None;
+    }
+    let done = Arc::new(AtomicUsize::new(0));
+    let failures = Arc::new(AtomicUsize::new(0));
+    Some(Arc::new(move |outcome: &FileOutcome| {
+        let index = done.fetch_add(1, Ordering::Relaxed) + 1;
+        if let Some(failure) = &outcome.failure {
+            let seen = failures.fetch_add(1, Ordering::Relaxed);
+            if seen < MAX_PROGRESS_FAILURES {
+                emit(
+                    json,
+                    json!({
+                        "event": "file_failed",
+                        "done": index,
+                        "total": total,
+                        "name": outcome.name,
+                        "role": outcome.role.as_str(),
+                        "kind": failure.kind.as_str(),
+                        "message": failure.message,
+                    }),
+                    &format!("失败 {index}/{total} {}：{}", outcome.name, failure.message),
+                );
+            } else if seen == MAX_PROGRESS_FAILURES {
+                emit(
+                    json,
+                    json!({"event": "progress_truncated", "suppressed_after": MAX_PROGRESS_FAILURES}),
+                    "（更多失败不再逐条打印，见最终错误汇总）",
+                );
+            }
+            return;
+        }
+        if index.is_multiple_of(PROGRESS_EVERY) || index == total {
+            emit(
+                json,
+                json!({"event": "progress", "done": index, "total": total}),
+                &format!("下载 {index}/{total}"),
+            );
+        }
+    }))
+}
+
+/// 一条进度：JSONL 模式打序列化后的一行，人类模式打短文本。
+fn emit(json_mode: bool, record: serde_json::Value, text: &str) {
+    if json_mode {
+        progress_line(&record.to_string());
+    } else {
+        progress_line(text);
+    }
+}
+
+/// 排版一次安装结果。
+#[allow(clippy::too_many_arguments)]
+pub fn build(
+    ctx: &Ctx,
+    engine: &DownloadEngine,
+    now: u64,
+    dry_run: bool,
+    plan: &InstallPlan,
+    report: Option<&InstallReport>,
+    registration: Option<&Registration>,
+    name: &str,
+    version: &str,
+) -> Report {
+    let samples = if dry_run {
+        plan.source_samples(engine, now)
+    } else {
+        Vec::new()
+    };
+    let mut data = json!({
+        "dry_run": dry_run,
+        "version_id": plan.version_id,
+        "jar_id": plan.jar_id,
+        "game_root": plan.game_root.display().to_string(),
+        "plan": plan.summary_json(),
+        "result": report.map(|report| json!({
+            "downloaded": report.downloaded(),
+            "skipped": report.skipped(),
+            "failed": report.failed(),
+            "bytes": report.bytes(),
+            "version_json": report.version_json.as_ref().map(|path| path.display().to_string()),
+            "warnings": report.warnings,
+            "files": report.files.iter().map(outcome_json).collect::<Vec<_>>(),
+        })),
+        "instance": registration.map(|registration| json!({
+            "id": registration.profile.id.as_str(),
+            "name": registration.profile.name,
+            "version_id": registration.profile.version_id,
+            "created": registration.created,
+            "config_path": registration.config_path.display().to_string(),
+            "profiles_path": ctx.profiles_config().display().to_string(),
+        })),
+    });
+    if dry_run {
+        data["files"] = json!(plan.files_json());
+        data["sources"] = json!(samples);
+    }
+
+    Report::new(
+        data,
+        human_lines(dry_run, plan, report, registration, &samples, name, version),
+    )
+}
+
+/// 单个文件的执行结果（`--json` 的 `result.files`；脚本据此分流"哪几个没下成"）。
+fn outcome_json(outcome: &FileOutcome) -> serde_json::Value {
+    json!({
+        "role": outcome.role.as_str(),
+        "name": outcome.name,
+        "dest": outcome.dest.display().to_string(),
+        "status": outcome.status.as_str(),
+        "bytes": outcome.bytes,
+        "source": outcome.source,
+        "error": outcome.failure.as_ref().map(|failure| json!({
+            "kind": failure.kind.as_str(),
+            "message": failure.message,
+        })),
+    })
+}
+
+fn human_lines(
+    dry_run: bool,
+    plan: &InstallPlan,
+    report: Option<&InstallReport>,
+    registration: Option<&Registration>,
+    samples: &[serde_json::Value],
+    name: &str,
+    version: &str,
+) -> Vec<String> {
+    let mut human = Vec::new();
+    let (total_bytes, unknown) = plan.total_bytes();
+    human.push(if dry_run {
+        format!("安装计划：{}（jar {}）", plan.version_id, plan.jar_id)
+    } else {
+        format!("已安装 {}（jar {}）", plan.version_id, plan.jar_id)
+    });
+    for (role, (count, bytes)) in plan.by_role() {
+        human.push(format!(
+            "  {:<8} {} 个 / {}",
+            role.label(),
+            count,
+            human_bytes(bytes)
+        ));
+    }
+    human.push(format!(
+        "  合计 {} 个文件 / {}{}（游戏根 {}）",
+        plan.file_count(),
+        human_bytes(total_bytes),
+        if unknown > 0 {
+            format!(" + {unknown} 个大小未知")
+        } else {
+            String::new()
+        },
+        plan.game_root.display()
+    ));
+    for sample in samples {
+        let sources: Vec<&str> = sample["candidates"]
+            .as_array()
+            .map(|list| {
+                list.iter()
+                    .filter_map(|candidate| candidate["source"].as_str())
+                    .collect()
+            })
+            .unwrap_or_default();
+        human.push(format!(
+            "  源选择 {} → {}",
+            sample["label"].as_str().unwrap_or_default(),
+            sources.join(" → ")
+        ));
+    }
+    for warning in &plan.warnings {
+        human.push(format!("告警: {warning}"));
+    }
+    if let Some(report) = report {
+        human.push(format!(
+            "下载 {} 个 / 跳过 {} 个已就绪 / 失败 {} 个（本次 {}）",
+            report.downloaded(),
+            report.skipped(),
+            report.failed(),
+            human_bytes(report.bytes())
+        ));
+        if let Some(path) = &report.version_json {
+            human.push(format!("版本清单: {}", path.display()));
+        }
+    }
+    match registration {
+        Some(registration) => human.push(format!(
+            "已登记实例 {}（{}）→ 版本 {}（{}）",
+            name,
+            registration.profile.id.as_str(),
+            version,
+            if registration.created {
+                "新建"
+            } else {
+                "已存在，复用"
+            }
+        )),
+        None => human.push("（--dry-run：未下载任何文件，未登记实例）".to_string()),
+    }
+    human
+}
+
+/// 字节 → 人读（MB/GB 一位小数，KB 取整；不做假精度）。
+pub fn human_bytes(bytes: u64) -> String {
+    const KB: u64 = 1024;
+    const MB: u64 = 1024 * KB;
+    const GB: u64 = 1024 * MB;
+    if bytes >= GB {
+        format!("{:.1} GB", bytes as f64 / GB as f64)
+    } else if bytes >= MB {
+        format!("{:.1} MB", bytes as f64 / MB as f64)
+    } else if bytes >= KB {
+        format!("{} KB", bytes / KB)
+    } else {
+        format!("{bytes} B")
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::human_bytes;
+
+    #[test]
+    fn formats_sizes_without_fake_precision() {
+        assert_eq!(human_bytes(0), "0 B");
+        assert_eq!(human_bytes(1023), "1023 B");
+        assert_eq!(human_bytes(1024), "1 KB");
+        assert_eq!(human_bytes(1024 * 1024), "1.0 MB");
+        assert_eq!(human_bytes(3 * 1024 * 1024 * 1024), "3.0 GB");
+    }
+}
diff --git a/crates/cli/src/commands/install/report_loader.rs b/crates/cli/src/commands/install/report_loader.rs
new file mode 100644
index 0000000..d94d215
--- /dev/null
+++ b/crates/cli/src/commands/install/report_loader.rs
@@ -0,0 +1,274 @@
+//! 加载器安装的呈现形态（人类可读行 + `--json` 载荷）。
+//!
+//! 与 [`super::report`] 的分工：那边是"原版安装"（客户端 jar + 资源 + 库），这边是
+//! "叠在原版上的 loader 层"（只有库）。共用同一套进度回调与字节格式化。
+
+use serde_json::json;
+use unlucky_core::addon::loader::processors::{ProcessorPlan, ProcessorRun};
+use unlucky_core::addon::loader::LoaderInstallPlan;
+use unlucky_core::download::DownloadEngine;
+use unlucky_core::game::install::{InstallReport, Registration};
+
+use super::report::human_bytes;
+use crate::context::Ctx;
+use crate::output::Report;
+
+/// processors 段（M35）的报告输入：计划 + 依赖库下载结果 + 执行结果。
+///
+/// `--dry-run` 只有 `plan`；幂等跳过时 `libraries`/`run` 都是 `None` 且 `skipped = true`。
+pub struct ProcessorSection<'a> {
+    /// 执行计划（dry-run 也带上：将执行的 processor 清单 + 所需 Java）。
+    pub plan: &'a ProcessorPlan,
+    /// processor 依赖库的下载结果。
+    pub libraries: Option<&'a InstallReport>,
+    /// 执行结果。
+    pub run: Option<&'a ProcessorRun>,
+    /// 整段跳过（版本 JSON 已在盘上 = processors 早已跑完）。
+    pub skipped: bool,
+}
+
+/// 排版一次加载器安装结果。
+///
+/// 参数多是因为载荷本身就多：计划（loader 版本 + 库）、processors 段、执行结果、实例登记、
+/// `--dry-run` 的源选择样本。拆成结构体会让调用方多写十行，不如保持扁平。
+#[allow(clippy::too_many_arguments)]
+pub fn build(
+    ctx: &Ctx,
+    engine: &DownloadEngine,
+    now: u64,
+    dry_run: bool,
+    plan: &LoaderInstallPlan,
+    report: Option<&InstallReport>,
+    registration: Option<&Registration>,
+    name: &str,
+    processors: Option<ProcessorSection<'_>>,
+) -> Report {
+    let samples = if dry_run {
+        plan.install.source_samples(engine, now)
+    } else {
+        Vec::new()
+    };
+    let mut data = json!({
+        "dry_run": dry_run,
+        "loader": plan.release.to_json(),
+        "vanilla_install_needed": plan.vanilla_install_needed,
+        "game_root": plan.install.game_root.display().to_string(),
+        "plan": plan.summary_json(),
+        "result": report.map(|report| json!({
+            "downloaded": report.downloaded(),
+            "skipped": report.skipped(),
+            "failed": report.failed(),
+            "bytes": report.bytes(),
+            "version_json": report.version_json.as_ref().map(|path| path.display().to_string()),
+            "warnings": report.warnings,
+        })),
+        "instance": registration.map(|registration| json!({
+            "id": registration.profile.id.as_str(),
+            "name": registration.profile.name,
+            "version_id": registration.profile.version_id,
+            "created": registration.created,
+            "config_path": registration.config_path.display().to_string(),
+            "profiles_path": ctx.profiles_config().display().to_string(),
+        })),
+    });
+    if dry_run {
+        data["files"] = json!(plan.install.files_json());
+        data["sources"] = json!(samples);
+    }
+    if let Some(section) = &processors {
+        data["processors"] = processor_json(section);
+    }
+
+    Report::new(
+        data,
+        human_lines(
+            dry_run,
+            plan,
+            report,
+            registration,
+            &samples,
+            name,
+            processors.as_ref(),
+        ),
+    )
+}
+
+/// processors 段的 JSON 载荷（计划 + 依赖库结果 + 逐步骤结果）。
+fn processor_json(section: &ProcessorSection<'_>) -> serde_json::Value {
+    let mut node = section.plan.to_json();
+    if let Some(object) = node.as_object_mut() {
+        object.insert("skipped".to_string(), json!(section.skipped));
+        object.insert(
+            "libraries_result".to_string(),
+            json!(section.libraries.map(|report| json!({
+                "downloaded": report.downloaded(),
+                "skipped": report.skipped(),
+                "failed": report.failed(),
+                "bytes": report.bytes(),
+            }))),
+        );
+        object.insert(
+            "run".to_string(),
+            json!(section.run.map(ProcessorRun::to_json)),
+        );
+    }
+    node
+}
+
+fn human_lines(
+    dry_run: bool,
+    plan: &LoaderInstallPlan,
+    report: Option<&InstallReport>,
+    registration: Option<&Registration>,
+    samples: &[serde_json::Value],
+    name: &str,
+    processors: Option<&ProcessorSection<'_>>,
+) -> Vec<String> {
+    let release = &plan.release;
+    let mut human = Vec::new();
+    human.push(format!(
+        "{} {}《{} {}》（继承原版 {}，主类 {}）",
+        if dry_run {
+            "加载器安装计划"
+        } else {
+            "已安装加载器"
+        },
+        release.kind.label(),
+        release.mc_version,
+        release.loader_version,
+        release.mc_version,
+        release.version_json.main_class.as_deref().unwrap_or("?"),
+    ));
+    human.push(format!(
+        "  版本 id {} → {}",
+        release.version_id,
+        plan.install.version_json_path.display()
+    ));
+    human.push(format!(
+        "  原版 {}",
+        if plan.vanilla_install_needed {
+            "未安装：执行时先装原版"
+        } else {
+            "已安装：跳过"
+        }
+    ));
+    let (total_bytes, unknown) = plan.install.total_bytes();
+    human.push(format!(
+        "  loader 库 {} 个 / {}{}",
+        plan.install.file_count(),
+        human_bytes(total_bytes),
+        if unknown > 0 {
+            format!(" + {unknown} 个大小未知")
+        } else {
+            String::new()
+        }
+    ));
+    for sample in samples {
+        let sources: Vec<&str> = sample["candidates"]
+            .as_array()
+            .map(|list| {
+                list.iter()
+                    .filter_map(|candidate| candidate["source"].as_str())
+                    .collect()
+            })
+            .unwrap_or_default();
+        human.push(format!(
+            "  源选择 {} → {}",
+            sample["label"].as_str().unwrap_or_default(),
+            sources.join(" → ")
+        ));
+    }
+    for warning in plan.warnings() {
+        human.push(format!("告警: {warning}"));
+    }
+    if let Some(section) = processors {
+        human.extend(processor_lines(section));
+    }
+    if let Some(report) = report {
+        human.push(format!(
+            "下载 {} 个 / 跳过 {} 个已就绪 / 失败 {} 个（本次 {}）",
+            report.downloaded(),
+            report.skipped(),
+            report.failed(),
+            human_bytes(report.bytes())
+        ));
+        if let Some(path) = &report.version_json {
+            human.push(format!("loader 版本清单: {}", path.display()));
+        }
+    }
+    match registration {
+        Some(registration) => human.push(format!(
+            "已登记实例 {}（{}）→ 版本 {}（{}）",
+            name,
+            registration.profile.id.as_str(),
+            registration.profile.version_id,
+            if registration.created {
+                "新建"
+            } else {
+                "已存在，复用"
+            }
+        )),
+        None => human.push("（--dry-run：未下载任何文件，未登记实例）".to_string()),
+    }
+    human
+}
+
+/// processors 段的人读行（计划 / 依赖库 / 逐步骤 / 告警）。
+fn processor_lines(section: &ProcessorSection<'_>) -> Vec<String> {
+    let plan = section.plan;
+    let mut lines = Vec::new();
+    lines.push(format!(
+        "  installer processors {} 步，需要 {}（installer {}）",
+        plan.step_count(),
+        plan.java_requirement.describe(),
+        plan.installer.display()
+    ));
+    if section.skipped {
+        lines.push("  版本清单已存在：processors 整段跳过（幂等）".to_string());
+    }
+    if let Some(libraries) = section.libraries {
+        lines.push(format!(
+            "  processor 依赖库 {} 个：下载 {} / 跳过 {} / 失败 {}",
+            plan.libraries.len(),
+            libraries.downloaded(),
+            libraries.skipped(),
+            libraries.failed()
+        ));
+    }
+    if let Some(run) = section.run {
+        lines.push(format!(
+            "  Java {}（{}）{}",
+            run.java
+                .major
+                .map_or_else(|| "未知".to_string(), |major| major.to_string()),
+            run.java.origin.as_str(),
+            run.java.binary.display()
+        ));
+        let total = run.steps.len();
+        for step in &run.steps {
+            lines.push(format!(
+                "    [{}/{}] {} → {}{}",
+                step.index,
+                total,
+                step.label,
+                if step.status.as_str() == "skipped" {
+                    "跳过（产物已就绪）".to_string()
+                } else {
+                    format!("执行 {} ms", step.elapsed_ms)
+                },
+                if step.outputs > 0 {
+                    format!("（产物 {} 个）", step.outputs)
+                } else {
+                    String::new()
+                }
+            ));
+        }
+        for warning in &run.warnings {
+            lines.push(format!("  告警: {warning}"));
+        }
+    }
+    for warning in &plan.warnings {
+        lines.push(format!("  告警: {warning}"));
+    }
+    lines
+}
diff --git a/crates/cli/src/commands/install/vanilla.rs b/crates/cli/src/commands/install/vanilla.rs
new file mode 100644
index 0000000..b0a074a
--- /dev/null
+++ b/crates/cli/src/commands/install/vanilla.rs
@@ -0,0 +1,160 @@
+//! `ull install <version>`（无加载器）：M27 原版安装流程的宿主。
+//!
+//! ```text
+//! RemoteSource::resolve（版本清单缓存 → 版本 JSON → 继承链）
+//!   → RemoteSource::asset_index（资源索引，顺便拿字节给下面预取）
+//!   → InstallPlan::build（纯计算：文件清单 / 总大小 / 角色）
+//!   → [--dry-run 到此为止]
+//!   → execute（跳过已就绪 → 引擎并发下载 → 原子写版本 JSON）
+//!   → register（profiles.json + config/instances/<id>.json）
+//! ```
+//!
+//! 异步整段包在一次 `block_on` 里：CLI 不依赖 tokio（D18 依赖树纪律），
+//! reqwest 的连接池也不会跨运行时而失效。
+
+use unlucky_core::download::blocking::block_on;
+use unlucky_core::download::cache::now_ms;
+use unlucky_core::download::DownloadEngine;
+use unlucky_core::game::arguments::Environment;
+use unlucky_core::game::install::{
+    execute, InstallError, InstallErrorKind, InstallPlan, InstallReport, PlanInput, RemoteSource,
+};
+
+use super::{
+    build_engine, ensure_name_free, failure_error, map_install_error, report, CONCURRENCY,
+};
+use crate::cli::InstallArgs;
+use crate::context::Ctx;
+use crate::error::CliError;
+use crate::output::Report;
+
+/// 执行 `install`（原版）。
+///
+/// # Errors
+///
+/// 用法错误、版本不存在、网络失败、校验不符、写盘失败、实例清单损坏。
+pub(super) fn run(ctx: &Ctx, args: &InstallArgs) -> Result<Report, CliError> {
+    let version = args.version.trim().to_string();
+    if version.is_empty() {
+        return Err(CliError::usage(
+            "install 需要版本 id：%prog% install <version>",
+        ));
+    }
+    let name = args
+        .name
+        .clone()
+        .filter(|name| !name.trim().is_empty())
+        .unwrap_or_else(|| version.clone());
+    ensure_name_free(ctx, &name, &version)?;
+
+    let engine = build_engine(ctx);
+    let now = now_ms();
+    let (plan, report) = plan_and_install(
+        ctx,
+        &engine,
+        &version,
+        args.dry_run,
+        args.progress,
+        args.json_progress,
+    )?;
+
+    if let Some(report) = &report {
+        if !report.is_complete() {
+            return Err(failure_error(report, ctx));
+        }
+    }
+
+    let registration = if args.dry_run {
+        None
+    } else {
+        Some(super::register_instance(ctx, &name, &version)?)
+    };
+
+    Ok(report::build(
+        ctx,
+        &engine,
+        now,
+        args.dry_run,
+        &plan,
+        report.as_ref(),
+        registration.as_ref(),
+        &name,
+        &version,
+    ))
+}
+
+/// 规划 + 执行原版安装（`--dry-run` 只规划），供加载器安装当"前置步骤"复用。
+///
+/// # Errors
+///
+/// 版本不存在、网络失败、清单装不全、写盘失败。
+pub(super) fn plan_and_install(
+    ctx: &Ctx,
+    engine: &DownloadEngine,
+    version: &str,
+    dry_run: bool,
+    progress: bool,
+    json_progress: bool,
+) -> Result<(InstallPlan, Option<InstallReport>), CliError> {
+    let game = ctx.game();
+    let meta_cache = ctx.layout().meta_cache();
+    let now = now_ms();
+
+    block_on(async {
+        let source = RemoteSource::new(engine, &game, &meta_cache, now);
+        let resolved = source.resolve(version).await?;
+        let fetched = match resolved
+            .asset_index
+            .as_ref()
+            .filter(|index| index.url.is_some())
+        {
+            Some(reference) => {
+                let (index, bytes) = source.asset_index(reference).await?;
+                Some((index, game.asset_index(&reference.id), bytes))
+            }
+            None => None,
+        };
+        let mut plan = InstallPlan::build(PlanInput {
+            layout: &game,
+            version_id: version,
+            resolved: &resolved,
+            asset_index: fetched.as_ref().map(|(index, _, _)| index),
+            environment: &Environment::host(),
+        })?;
+        if let Some((_, dest, bytes)) = fetched {
+            plan.prefetch(dest, bytes);
+        }
+        if dry_run {
+            return Ok::<Attempt, InstallError>(Attempt { plan, report: None });
+        }
+        // 计划里没有客户端 jar（旧版清单缺 downloads.client）→ 拒绝"装出个空壳"。
+        if !plan.is_installable() {
+            let reasons = if plan.warnings.is_empty() {
+                "清单缺少客户端 jar 的下载信息".to_string()
+            } else {
+                plan.warnings.join("；")
+            };
+            return Err(InstallError::new(
+                InstallErrorKind::Metadata,
+                format!("版本 {version} 装不全：{reasons}"),
+            )
+            .with_hint(
+                "旧版（pre-1.6）清单兜底待补；可先用官方启动器装好该版本再用 `%prog% launch`",
+            ));
+        }
+        let sink = report::progress_sink(progress, json_progress, plan.file_count());
+        let report = execute(engine, &plan, CONCURRENCY, sink).await?;
+        Ok(Attempt {
+            plan,
+            report: Some(report),
+        })
+    })
+    .map(|attempt| (attempt.plan, attempt.report))
+    .map_err(|error: InstallError| map_install_error(&error, ctx))
+}
+
+/// 一次安装尝试的产物（`--dry-run` 只有计划）。
+struct Attempt {
+    plan: InstallPlan,
+    report: Option<InstallReport>,
+}
diff --git a/crates/cli/src/commands/instances.rs b/crates/cli/src/commands/instances.rs
new file mode 100644
index 0000000..95a059d
--- /dev/null
+++ b/crates/cli/src/commands/instances.rs
@@ -0,0 +1,90 @@
+//! `instances list`：实例与已安装版本的总览。
+//!
+//! 安装/登记在 [`super::install`]；这里只读（`profiles.json` + `versions/` 的存在性）。
+//! 读 `profiles.json` 的实现委托给 `core::game::install::instance`，避免 CLI 自带一份
+//! 解析逻辑（同一份文件两处解析迟早会漂移）。
+
+use std::path::PathBuf;
+
+use serde_json::{json, Value};
+use unlucky_core::game::install::instance::read_profiles as read_profiles_from_layout;
+use unlucky_core::game::ProfileList;
+
+use crate::context::Ctx;
+use crate::error::CliError;
+use crate::output::Report;
+
+/// `ull instances list`。
+///
+/// # Errors
+///
+/// `profiles.json` 读不了或解析失败时返回用户错误。
+pub fn list(ctx: &Ctx) -> Result<Report, CliError> {
+    let profiles = read_profiles(ctx)?;
+    let game = ctx.game();
+    let installed = game.installed_versions().unwrap_or_default();
+
+    let mut rows: Vec<Value> = Vec::new();
+    let mut body: Vec<String> = Vec::new();
+    for profile in &profiles.profiles {
+        let present = game.is_version_installed(&profile.version_id);
+        body.push(format!(
+            "  {}  [{}]  {}  {}",
+            profile.name,
+            profile.version_id,
+            if present { "已安装" } else { "载荷缺失" },
+            profile.id.as_str()
+        ));
+        rows.push(json!({
+            "id": profile.id.as_str(),
+            "name": profile.name,
+            "version_id": profile.version_id,
+            "version_present": present,
+            "game_dir": option_path(profile.game_dir.as_ref()),
+            "java_path": option_path(profile.java_path.as_ref()),
+            "last_played_at": profile.last_played_at,
+        }));
+    }
+
+    let data = json!({
+        "data_root": ctx.data.launcher_home.display().to_string(),
+        "game_root": ctx.data.game_home.display().to_string(),
+        "instances": rows,
+        "installed_versions": installed,
+    });
+
+    let mut human = vec![format!(
+        "实例 {} 个（数据根 {}）",
+        profiles.profiles.len(),
+        ctx.data.launcher_home.display()
+    )];
+    if body.is_empty() {
+        human.push("  （空）用 `%prog% install <version>` 登记第一个实例".to_string());
+    }
+    human.extend(body);
+    if installed.is_empty() {
+        human.push("已安装版本: （无）".to_string());
+    } else {
+        human.push(format!("已安装版本: {}", installed.join(", ")));
+    }
+    Ok(Report::new(data, human))
+}
+
+/// 读实例清单（文件不存在 = 空列表，不算错误）。
+///
+/// # Errors
+///
+/// 读盘失败或 JSON 非法时返回用户错误。
+pub fn read_profiles(ctx: &Ctx) -> Result<ProfileList, CliError> {
+    let path = ctx.profiles_config();
+    read_profiles_from_layout(&ctx.layout()).map_err(|error| {
+        CliError::user(
+            "profiles_parse",
+            format!("读实例清单 {} 失败：{error}", path.display()),
+        )
+    })
+}
+
+fn option_path(path: Option<&PathBuf>) -> Option<String> {
+    path.map(|path| path.display().to_string())
+}
diff --git a/crates/cli/src/commands/java.rs b/crates/cli/src/commands/java.rs
new file mode 100644
index 0000000..1ab3622
--- /dev/null
+++ b/crates/cli/src/commands/java.rs
@@ -0,0 +1,365 @@
+//! Java 运行时：`ull java list` / `install` / `vendors`（D13 v1 + D23 v2）。
+//!
+//! 四件事：建下载引擎、把 core 的结果排成人读与 `--json` 两种形态、把错误翻成稳定码、
+//! 从设置里取 JDK 的落点与发行版优先级。探测/下载/解压/映射/回退链全在 `core::game::java`。
+//!
+//! D23 之后的三个用户可见变化：
+//!
+//! 1. **落点可选**：`java.installRoot` 设了就装到那里；否则 Standard 数据模式装到
+//!    `%APPDATA%\Java\<发行方>\<版本>\`（mac/Linux 见 `game::java::location`），
+//!    Portable 仍在数据根 `java-managed/`（v1 布局不变）；
+//! 2. **发行版可选**：`--vendor temurin|oracle|microsoft|zulu` 钉死一家；不给就按
+//!    `java.vendorPriority` → 地区默认序跑回退链，降级原因进 `--json` 的 `chain` 块；
+//! 3. **`java vendors`** 一眼看清四家的可用性、镜像与当前顺序。
+
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+
+use serde_json::{json, Value};
+use unlucky_core::download::blocking::block_on;
+use unlucky_core::download::cache::now_ms;
+use unlucky_core::download::region::{decide_from, load_cached, store_cached};
+use unlucky_core::download::region_system::detect_signals;
+use unlucky_core::download::{
+    ContentCache, DownloadEngine, EngineConfig, HealthRegistry, MirrorTable, RegionProfile,
+};
+use unlucky_core::game::java::{
+    self, location, vendor, InstallRequest, JavaOrigin, JavaRuntime, JdkVendor, LocationMode,
+    DEFAULT_MAJOR,
+};
+use unlucky_core::launch::request::JavaSelection;
+use unlucky_core::platform::paths::ProcessEnv;
+use unlucky_core::setting::keys::launcher_schema;
+use unlucky_core::setting::store::SettingStore;
+
+use crate::context::Ctx;
+use crate::error::CliError;
+use crate::output::Report;
+
+pub use super::java_launch::{resolve_for_launch, LaunchJava};
+pub use super::java_vendors::vendors;
+
+/// 可自动安装的最老大版本（再老的 Temurin 没有 GA 产物）。
+const MIN_INSTALLABLE_MAJOR: u32 = 8;
+
+/// 装配用的 Java 选择（`--java` > `JAVA_HOME` > PATH 上的 `java`）。
+///
+/// `snapshot::prepare` 调它拿 [`JavaSelection`]；真正的来源优先级在
+/// [`resolve_for_launch`] 里求值（那一步还会看托管目录与版本要求）。
+#[must_use]
+pub fn selection(explicit: Option<&Path>) -> JavaSelection {
+    let (binary, origin) = match explicit {
+        Some(path) => (path.to_path_buf(), JavaOrigin::Instance),
+        None => match env_java() {
+            Some(binary) => (binary, JavaOrigin::JavaHome),
+            None => (PathBuf::from(java::java_binary_name()), JavaOrigin::Path),
+        },
+    };
+    let runtime = java::probe(&binary, origin);
+    JavaSelection::new(binary, runtime.major.unwrap_or(DEFAULT_MAJOR), runtime.bits)
+}
+
+/// 托管 JDK 可能存在的全部安装根（Portable 数据根 + Standard/Custom 落点，D23 后不止一个）。
+#[must_use]
+pub fn managed_roots(ctx: &Ctx) -> Vec<PathBuf> {
+    let settings = JavaSettings::load(ctx);
+    location::scan_roots(
+        ctx.data.mode,
+        &ctx.layout(),
+        settings.install_root.as_deref(),
+        ctx.platform,
+        &ProcessEnv,
+    )
+}
+
+/// `ull java list`：探测托管目录 / `JAVA_HOME` / `PATH` / 实例覆盖，并显示各 JDK 的落点。
+///
+/// # Errors
+///
+/// 实例清单读不了时返回用户错误（其余探测失败只体现为缺项）。
+pub fn list(ctx: &Ctx) -> Result<Report, CliError> {
+    let settings = JavaSettings::load(ctx);
+    let roots = managed_roots(ctx);
+    // 托管 → JAVA_HOME → PATH → 标准安装位置（Program Files 系 / 官方启动器 runtime / 注册表），
+    // 同一路径只列一次且保留优先级高者（`discover::dedupe` 负责）。
+    let mut candidates = java::candidates_in_roots(&roots);
+    let profiles = super::instances::read_profiles(ctx)?;
+    for profile in &profiles.profiles {
+        if let Some(java_path) = &profile.java_path {
+            candidates.push(java::probe(java_path, JavaOrigin::Instance));
+        }
+    }
+    let candidates = java::discover::dedupe(candidates);
+    let candidates: Vec<JavaRuntime> = candidates
+        .into_iter()
+        .filter(|candidate| candidate.major.is_some())
+        .collect();
+
+    let mode = settings.location_mode(ctx);
+    let installed_root = settings.location(ctx).map(|root| root.root).ok();
+    let data = json!({
+        // 兼容 v1 的 `managed_root`（首个扫描根），同时给出多根清单（D23 之后不止一个根）。
+        "managed_root": roots.first().map(|root| root.display().to_string()),
+        "managed_roots": roots.iter().map(|root| root.display().to_string()).collect::<Vec<_>>(),
+        "install": {
+            "mode": mode.as_str(),
+            "root": installed_root.as_ref().map(|root| root.display().to_string()),
+            "override": settings.install_root.as_ref().map(|root| root.display().to_string()),
+        },
+        "candidates": candidates.iter().map(candidate_json).collect::<Vec<_>>(),
+    });
+    let mut human = vec![format!("Java {} 个", candidates.len())];
+    if candidates.is_empty() {
+        human.push(
+            "（没找到可用 Java）用 `%prog% java install 21` 装一个，或设 JAVA_HOME / `%prog% launch --java <path>`"
+                .to_string(),
+        );
+    }
+    human.push(format!(
+        "落点模式：{}",
+        describe_mode(mode, settings.install_root.as_deref())
+    ));
+    for root in &roots {
+        human.push(format!("  扫描根：{}", root.display()));
+    }
+    for candidate in &candidates {
+        human.push(format!(
+            "  {}  {}  [{}]",
+            candidate
+                .version
+                .clone()
+                .unwrap_or_else(|| "版本未知".to_string()),
+            candidate.binary.display(),
+            source_label(candidate)
+        ));
+    }
+    Ok(Report::new(data, human))
+}
+
+/// `ull java install <major> [--vendor X]`：回退链查版本 → 下载 → 解压 → `java -version` 验证。
+///
+/// 幂等：同一个归档装过就直接复用（不联网、不解压）。下载走 `core::download` 引擎，
+/// 国内环境按 D7 的地区策略优先院校/国内镜像。
+///
+/// # Errors
+///
+/// 大版本不合法、平台无产物、所有发行版都失败（网络/校验/解压/跑不起来）时返回用户错误。
+pub fn install(ctx: &Ctx, major: u32, vendor: Option<JdkVendor>) -> Result<Report, CliError> {
+    if !(MIN_INSTALLABLE_MAJOR..=99).contains(&major) {
+        return Err(CliError::usage(format!(
+            "大版本号看起来不对：{major}（可用 8 / 11 / 17 / 21 / 25 这类 GA 大版本）"
+        )));
+    }
+    let settings = JavaSettings::load(ctx);
+    let engine = build_engine(ctx);
+    let install_root = settings.location(ctx)?;
+    let request = match vendor {
+        Some(vendor) => {
+            InstallRequest::with_vendor(major, vendor).with_priority(settings.priority.clone())
+        }
+        None => InstallRequest::new(major).with_priority(settings.priority.clone()),
+    };
+    let installed =
+        block_on(java::install(&engine, &install_root, request)).map_err(map_java_error)?;
+
+    let data = json!({
+        "major": installed.major,
+        "vendor": installed.vendor.id(),
+        "release": installed.release.release_name,
+        "version": installed.release.version,
+        "semver": installed.release.semver,
+        "archive": installed.release.archive.name,
+        "sha256": installed.release.archive.sha256,
+        "size": installed.release.archive.size,
+        "root": installed.root.display().to_string(),
+        "install_mode": installed.mode.as_str(),
+        "binary": installed.binary().display().to_string(),
+        "reused": installed.reused(),
+        "source": installed.downloaded,
+        "bytes": installed.bytes,
+        "files": installed.files,
+        "extracted": installed.extracted,
+        "chain": installed.chain.to_json(),
+        "runtime": candidate_json(&installed.runtime),
+    });
+
+    let mut human = Vec::new();
+    if installed.reused() {
+        human.push(format!(
+            "Java {}（{}）已就绪（{}），未走网络",
+            installed.major,
+            installed.vendor.id(),
+            installed.root.display()
+        ));
+    } else {
+        human.push(format!(
+            "已安装 Java {}（{}，来源 {}，{} 字节 / {} 个文件）",
+            installed.major,
+            installed.release.summary(),
+            installed.downloaded.as_deref().unwrap_or("?"),
+            installed.bytes,
+            installed.files
+        ));
+    }
+    human.push(format!("落点：{}", installed.location_line()));
+    human.push(format!("可执行文件：{}", installed.binary().display()));
+    if let Some(version) = &installed.runtime.version {
+        human.push(format!("探测：{version}"));
+    }
+    for note in installed.chain.degradations() {
+        human.push(format!("降级：{note}"));
+    }
+    human.push("`%prog% launch` 会自动优先用它".to_string());
+    Ok(Report::new(data, human))
+}
+
+/// 设置里与 JDK 有关的两项（`java.installRoot` / `java.vendorPriority`）。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub(crate) struct JavaSettings {
+    pub(crate) install_root: Option<PathBuf>,
+    pub(crate) priority: Vec<JdkVendor>,
+}
+
+impl JavaSettings {
+    /// 读 `<数据根>/.ULL/config/launcher.json`（坏文件退化成默认值，不阻断命令）。
+    pub(crate) fn load(ctx: &Ctx) -> Self {
+        let store = SettingStore::load(ctx.launcher_config(), launcher_schema());
+        let install_root = store
+            .doc()
+            .effective_str("java.installRoot")
+            .map(str::trim)
+            .filter(|text| !text.is_empty())
+            .map(PathBuf::from);
+        let priority = store
+            .effective("java.vendorPriority")
+            .and_then(Value::as_array)
+            .map(|items| {
+                let texts: Vec<String> = items
+                    .iter()
+                    .filter_map(Value::as_str)
+                    .map(str::to_string)
+                    .collect();
+                vendor::parse_priority(&texts)
+            })
+            .unwrap_or_default();
+        Self {
+            install_root,
+            priority,
+        }
+    }
+
+    /// 落点模式（只描述，不建目录）。
+    fn location_mode(&self, ctx: &Ctx) -> LocationMode {
+        if self.install_root.is_some() {
+            LocationMode::Custom
+        } else if ctx.data.mode == unlucky_core::platform::data_dir::DataMode::Standard {
+            LocationMode::Standard
+        } else {
+            LocationMode::Portable
+        }
+    }
+
+    /// 真正要装到哪（解析失败 → 用户错误，带可照着做的提示）。
+    fn location(&self, ctx: &Ctx) -> Result<java::JavaInstallRoot, CliError> {
+        java::JavaInstallRoot::resolve(
+            ctx.data.mode,
+            &ctx.layout(),
+            self.install_root.as_deref(),
+            ctx.platform,
+            &ProcessEnv,
+        )
+        .map_err(map_java_error)
+    }
+}
+
+/// 落点模式 → 人读一行（含「没设覆盖键时默认落在哪」的解释）。
+fn describe_mode(mode: LocationMode, override_root: Option<&Path>) -> String {
+    match mode {
+        LocationMode::Custom => format!(
+            "custom（java.installRoot = {}）",
+            override_root.unwrap_or(Path::new("?")).display()
+        ),
+        LocationMode::Standard => {
+            "standard（%APPDATA%\\Java\\<发行方>\\<版本> 等系统标准目录）".to_string()
+        }
+        LocationMode::Portable => "portable（<数据根>/.ULL/data/java-managed）".to_string(),
+    }
+}
+
+/// 一个运行时的 `--json` 形状。
+fn candidate_json(runtime: &JavaRuntime) -> Value {
+    json!({
+        "binary": runtime.binary.display().to_string(),
+        "source": runtime.origin.as_str(),
+        "source_category": runtime.origin.category(),
+        "version": runtime.version,
+        "major": runtime.major,
+        "bits": runtime.bits,
+        "vendor": runtime.vendor,
+        "install_root": install_root_of(runtime),
+    })
+}
+
+/// 托管 JDK 的实际目录（`bin/java` 的上两级）；非托管来源为 `None`。
+fn install_root_of(runtime: &JavaRuntime) -> Option<String> {
+    if runtime.origin != JavaOrigin::Managed {
+        return None;
+    }
+    runtime
+        .binary
+        .parent()
+        .and_then(Path::parent)
+        .map(|dir| dir.display().to_string())
+}
+
+/// 建下载引擎：内容寻址缓存落 `.ULL/cache/`，地区判定走 24h 缓存 + 环境信号。
+fn build_engine(ctx: &Ctx) -> DownloadEngine {
+    let layout = ctx.layout();
+    let cache_root = layout.cache();
+    let now = now_ms();
+    let region_path = cache_root.join("region.json");
+    let region = load_cached(&region_path, now).unwrap_or_else(|| {
+        let profile = decide_from(&detect_signals(), now);
+        let _ = store_cached(&region_path, &profile);
+        profile
+    });
+    DownloadEngine::new(
+        EngineConfig::default(),
+        Arc::new(MirrorTable::builtin()),
+        Arc::new(region),
+        Arc::new(HealthRegistry::open_in(&cache_root, now)),
+        Arc::new(ContentCache::open(&cache_root)),
+    )
+}
+
+/// JDK 下载/解压错误 → CLI 错误（保留稳定码与提示）。
+fn map_java_error(error: java::JavaError) -> CliError {
+    let cli = CliError::user(error.code(), error.message().to_string());
+    match error.hint() {
+        Some(hint) => cli.with_hint(hint.to_string()),
+        None => cli,
+    }
+}
+
+/// `JAVA_HOME/bin/java`（存在才返回）。
+fn env_java() -> Option<PathBuf> {
+    let home = std::env::var_os("JAVA_HOME")?;
+    let binary = PathBuf::from(home)
+        .join("bin")
+        .join(java::java_binary_name());
+    binary.is_file().then_some(binary)
+}
+
+/// 运行时 → 展示标签（托管项带上 vendor）。
+fn source_label(runtime: &JavaRuntime) -> String {
+    match &runtime.vendor {
+        Some(vendor) => format!("{} · {vendor}", runtime.origin.as_str()),
+        None => runtime.origin.as_str().to_string(),
+    }
+}
+
+/// 当前地区档案（`java vendors` 展示「国内/国外」口径；也给 GUI 复用）。
+#[must_use]
+pub fn region_profile(ctx: &Ctx) -> RegionProfile {
+    build_engine(ctx).region().clone()
+}
diff --git a/crates/cli/src/commands/java_launch.rs b/crates/cli/src/commands/java_launch.rs
new file mode 100644
index 0000000..16f374d
--- /dev/null
+++ b/crates/cli/src/commands/java_launch.rs
@@ -0,0 +1,129 @@
+//! 启动期的 Java 解析（`ull launch` 用）：实例覆盖 > 托管匹配 > 系统。
+//!
+//! 从 `commands/java.rs` 拆出来（那边还要放 list/install/vendors，超 400 行硬上限）。
+//! 这里的职责只有两条：①按 D13 的优先链挑一个 Java；②把结果整理成 `--json` 块与告警行。
+//! 真正「谁优先」的判定在 `core::game::java::probe` / `select`（纯函数），本文件只做装配。
+
+use std::path::{Path, PathBuf};
+
+use serde_json::{json, Value};
+use unlucky_core::game::java::{self, JavaMismatch, JavaOrigin, JavaRequirement, JavaRuntime};
+
+use crate::context::Ctx;
+
+/// 启动期的 Java 解析结果。
+#[derive(Debug, Clone)]
+pub struct LaunchJava {
+    /// 喂给 `PlanInput.java` 的显式覆盖；`None` = 让 `snapshot::prepare` 按系统兜底。
+    pub override_path: Option<PathBuf>,
+    /// 实际选中的运行时。
+    pub runtime: Option<JavaRuntime>,
+    /// 目标版本对 Java 的要求。
+    pub requirement: JavaRequirement,
+    /// 不符说明（只提示，不阻断）。
+    pub mismatch: Option<JavaMismatch>,
+}
+
+impl LaunchJava {
+    /// `--json` 的 `java` 块（app 层 GUI 弹窗 P1 后直接吃这份数据）。
+    #[must_use]
+    pub fn to_json(&self) -> Value {
+        let runtime = self.runtime.as_ref();
+        json!({
+            "binary": runtime.map(|runtime| runtime.binary.display().to_string()),
+            "major": runtime.and_then(|runtime| runtime.major),
+            "bits": runtime.map(|runtime| runtime.bits),
+            "source": runtime.map(|runtime| runtime.origin.as_str()),
+            "vendor": runtime.and_then(|runtime| runtime.vendor.clone()),
+            "required": self.requirement.describe(),
+            "required_major": self.requirement.minimum,
+            "requirement_source": self.requirement.source.as_str(),
+            "mismatch": self.mismatch.map(|mismatch| json!({
+                "code": mismatch.code(),
+                "message": mismatch.message(),
+            })),
+        })
+    }
+
+    /// 告警行（dry-run 与真启动都输出）。
+    ///
+    /// 两类：①用户指定的 Java 探测不出来（路径写错了，静默退回默认版本会很难查）；
+    /// ②Java 与版本要求不符（D13：提示，不阻断）。
+    #[must_use]
+    pub fn warnings(&self) -> Vec<String> {
+        let mut warnings = Vec::new();
+        if let Some(runtime) = &self.runtime {
+            if runtime.major.is_none() {
+                warnings.push(format!(
+                    "探测不到 {} 的 `java -version` 输出（路径可能不对）",
+                    runtime.binary.display()
+                ));
+            }
+        }
+        if let Some(mismatch) = self.mismatch {
+            warnings.push(mismatch.message());
+        }
+        warnings
+    }
+
+    /// 人读一行（Java 来源 + 要求）。
+    #[must_use]
+    pub fn summary(&self) -> String {
+        let source = self
+            .runtime
+            .as_ref()
+            .map_or("未探测到", |runtime| runtime.origin.as_str());
+        let version = self
+            .runtime
+            .as_ref()
+            .and_then(|runtime| runtime.major)
+            .map_or_else(|| "未知".to_string(), |major| major.to_string());
+        format!(
+            "Java {version}（{source}）· 该版本要求 {}",
+            self.requirement.describe()
+        )
+    }
+}
+
+/// 解析启动用的 Java：实例覆盖 > 托管匹配 > 系统。
+///
+/// 覆盖优先级的求值顺序写在 `core::game::java::probe`（纯函数，可注入候选）；
+/// 这里只负责「实例覆盖单独成路」与「把结果钉成路径」。
+#[must_use]
+pub fn resolve_for_launch(ctx: &Ctx, version_id: &str, explicit: Option<&Path>) -> LaunchJava {
+    let requirement = java::requirement_for_version(&ctx.game(), version_id);
+    let (runtime, mismatch) = match explicit {
+        Some(path) => {
+            let runtime = java::probe(path, JavaOrigin::Instance);
+            let mismatch = runtime
+                .major
+                .and_then(|major| java::check(major, &requirement));
+            (Some(runtime), mismatch)
+        }
+        None => {
+            // 先看托管 + 环境变量；都不满足要求才去扫盘（别为了一次启动白跑 N 次 java -version）。
+            // 托管区可能不止一个根（Portable 与 Standard/Custom 并存，D23）。
+            let roots = super::java::managed_roots(ctx);
+            let mut candidates = java::discover_managed_roots(&roots);
+            candidates.extend(java::system_candidates());
+            let mut resolution = java::resolve(&candidates, &requirement);
+            if resolution.mismatch.is_some() {
+                candidates.extend(java::standard_candidates());
+                resolution = java::resolve(&java::discover::dedupe(candidates), &requirement);
+            }
+            (resolution.runtime, resolution.mismatch)
+        }
+    };
+    // 托管 JDK 要钉死路径（用户 PATH 上的 java 可能正是我们要避开的那一个）；
+    // 系统来源交回 `snapshot::prepare` 的 `selection()` 兜底，避免重复实现一遍环境判断。
+    let override_path = match &runtime {
+        Some(runtime) if runtime.origin == JavaOrigin::Managed => Some(runtime.binary.clone()),
+        _ => explicit.map(Path::to_path_buf),
+    };
+    LaunchJava {
+        override_path,
+        runtime,
+        requirement,
+        mismatch,
+    }
+}
diff --git a/crates/cli/src/commands/java_vendors.rs b/crates/cli/src/commands/java_vendors.rs
new file mode 100644
index 0000000..96cfb22
--- /dev/null
+++ b/crates/cli/src/commands/java_vendors.rs
@@ -0,0 +1,141 @@
+//! `ull java vendors`：四家发行版的可用性 / 镜像 / 当前优先级顺序（D23）。
+//!
+//! 从 `commands/java.rs` 拆出来（那边 list/install 已经占满一屏）。这里只读不写：
+//! 不联网、不改配置，把 `mirrors.json` 的表与设置里的优先级排成一张人读 + `--json` 的对照表。
+//!
+//! 存在的意义是**可观测**：用户问「国内为什么默认走 Oracle 而不是微软」时，命令要能直接答
+//! （顺序 + 每家的镜像与实测吞吐），而不是让人翻文档。
+
+use serde_json::{json, Value};
+use unlucky_core::download::MirrorTable;
+use unlucky_core::game::java::{vendor, JdkVendor};
+
+use super::java::{region_profile, JavaSettings};
+use crate::context::Ctx;
+use crate::error::CliError;
+use crate::output::Report;
+
+/// `ull java vendors`。
+///
+/// # Errors
+///
+/// 设置文件坏掉时退化为默认值；命令本身不产生用户错误。
+pub fn vendors(ctx: &Ctx) -> Result<Report, CliError> {
+    let settings = JavaSettings::load(ctx);
+    let domestic = region_profile(ctx).is_domestic();
+    let order = vendor::order(&settings.priority, domestic);
+    let table = MirrorTable::builtin();
+    let rows: Vec<Value> = order
+        .iter()
+        .enumerate()
+        .map(|(index, item)| vendor_json(&table, *item, index))
+        .collect();
+    let priority_source = if settings.priority.is_empty() {
+        "region_default"
+    } else {
+        "java.vendorPriority"
+    };
+    let data = json!({
+        "region": if domestic { "domestic" } else { "global" },
+        "priority_source": priority_source,
+        "order": vendor::ids(&order),
+        "vendors": rows,
+    });
+    let mut human = vec![format!(
+        "发行版顺序（{}，来源 {}）：{}",
+        if domestic { "国内" } else { "国外" },
+        if settings.priority.is_empty() {
+            "地区默认序"
+        } else {
+            "java.vendorPriority"
+        },
+        vendor::ids(&order).join(" → ")
+    )];
+    for row in &rows {
+        human.push(format!(
+            "  {} {}  {}  支持 Java {}",
+            row["rank"].as_u64().unwrap_or(0),
+            row["vendor"].as_str().unwrap_or("?"),
+            row["display"].as_str().unwrap_or(""),
+            join_numbers(&row["majors"], "/")
+        ));
+        for source in row["sources"].as_array().into_iter().flatten() {
+            if let Some(text) = source.as_str() {
+                human.push(format!("      源：{text}"));
+            }
+        }
+    }
+    Ok(Report::new(data, human))
+}
+
+/// 一家的 `--json` 形状（源清单按家取，缺表时为空数组而不是报错）。
+fn vendor_json(table: &MirrorTable, item: JdkVendor, index: usize) -> Value {
+    let sources: Vec<String> = match item {
+        JdkVendor::Temurin => table
+            .adoptium
+            .iter()
+            .filter(|mirror| mirror.enabled)
+            .map(|mirror| {
+                format!(
+                    "{}{}",
+                    mirror.name,
+                    if mirror.latest_only {
+                        "（只留最新补丁）"
+                    } else {
+                        ""
+                    }
+                )
+            })
+            .chain(std::iter::once(
+                "GitHub 官方（国内套 gh-proxy）".to_string(),
+            ))
+            .collect(),
+        JdkVendor::Oracle => table
+            .oracle_mirrors()
+            .map(|mirror| match mirror.speed.trim() {
+                "" => format!("{} {}", mirror.name, mirror.base()),
+                speed => format!("{} {} {}", mirror.name, mirror.base(), speed),
+            })
+            .collect(),
+        JdkVendor::Microsoft => table
+            .microsoft_openjdk()
+            .map(|microsoft| {
+                let speed = if microsoft.measured_speed.trim().is_empty() {
+                    "实测约 400 KB/s".to_string()
+                } else {
+                    microsoft.measured_speed.clone()
+                };
+                vec![format!(
+                    "aka.ms → VS CDN（{speed}）；无国内镜像、无 GitHub 资产"
+                )]
+            })
+            .unwrap_or_default(),
+        JdkVendor::Zulu => table
+            .zulu()
+            .map(|zulu| vec![format!("{}（{}）", zulu.api, zulu.measured_speed)])
+            .unwrap_or_default(),
+    };
+    json!({
+        "rank": index + 1,
+        "vendor": item.id(),
+        "display": item.display(),
+        "majors": item.hint_majors(),
+        "supported": (8..=99u32).filter(|major| item.supports(*major)).collect::<Vec<_>>(),
+        "sources": sources,
+    })
+}
+
+/// JSON 数字数组 → `21/17/11` 这种分隔串。
+fn join_numbers(value: &Value, separator: &str) -> String {
+    value
+        .as_array()
+        .map(|items| {
+            items
+                .iter()
+                .filter_map(Value::as_u64)
+                .map(|number| number.to_string())
+                .collect::<Vec<_>>()
+                .join(separator)
+        })
+        .unwrap_or_default()
+}
diff --git a/crates/cli/src/commands/launch.rs b/crates/cli/src/commands/launch.rs
new file mode 100644
index 0000000..8340651
--- /dev/null
+++ b/crates/cli/src/commands/launch.rs
@@ -0,0 +1,377 @@
+//! `ull launch <instance> [--dry-run]`（D18：`--dry-run` 只打印组装后的命令行）。
+//!
+//! D20 的隔离档位在**这里**落成 `--gameDir`：本命令按覆盖链
+//! （临时参数 > 实例 `isolation` > 全局 `instances.mode`）派生出运行目录，
+//! 交给 [`snapshot::prepare`] 装进 `LaunchDirs.game_dir`（占位符 `${game_directory}`
+//! 与子进程 CWD 都取这个值），并在启动时做一次切换检测（只探测、不迁移）。
+
+use std::path::PathBuf;
+
+use serde_json::json;
+use unlucky_core::game::install::instance::{
+    read_instance_config, write_instance_config, InstanceConfig, Isolation,
+};
+use unlucky_core::game::isolation::{derive_game_dir, observe_mode, IsolationMode};
+use unlucky_core::game::ProfileList;
+use unlucky_core::launch::time::{format_rfc3339_millis, now};
+use unlucky_core::launch::{LaunchError, Launcher, LauncherConfig};
+use unlucky_core::setting::keys::launcher_schema;
+use unlucky_core::setting::store::SettingStore;
+
+use crate::cli::LaunchArgs;
+use crate::context::Ctx;
+use crate::error::CliError;
+use crate::output::Report;
+
+use super::identity::{self, Identity};
+use super::snapshot::{self, PlanInput};
+
+/// 执行 `launch`。
+///
+/// # Errors
+///
+/// 实例/版本不存在、版本 JSON 不可用、命令行组装失败、进程起不来时返回用户错误。
+pub fn run(ctx: &Ctx, args: &LaunchArgs) -> Result<Report, CliError> {
+    let profiles = super::instances::read_profiles(ctx)?;
+    let game = ctx.game();
+    let profile = profiles
+        .profiles
+        .iter()
+        .find(|profile| profile.id.as_str() == args.instance || profile.name == args.instance);
+
+    let (input, instance_found) = match profile {
+        Some(profile) => (
+            PlanInput {
+                version_id: profile.version_id.clone(),
+                instance_id: profile.id.as_str().to_string(),
+                instance_name: profile.name.clone(),
+                game_dir: profile.game_dir.clone(),
+                java: args.java.clone().or_else(|| profile.java_path.clone()),
+                username: args.username.clone(),
+                max_memory: args.max_memory,
+                ..PlanInput::default()
+            },
+            true,
+        ),
+        None => {
+            // 也接受「直接给版本 id」：没有实例档案时按版本跑一次（脚本化常见）。
+            if !game.is_version_installed(&args.instance) {
+                return Err(CliError::user(
+                    "not_found",
+                    format!(
+                        "既没有实例 `{}`，也没有版本 `{}`",
+                        args.instance, args.instance
+                    ),
+                )
+                .with_hint(instance_hint(&profiles)));
+            }
+            (
+                PlanInput {
+                    version_id: args.instance.clone(),
+                    instance_name: args.instance.clone(),
+                    java: args.java.clone(),
+                    username: args.username.clone(),
+                    max_memory: args.max_memory,
+                    ..PlanInput::default()
+                },
+                false,
+            )
+        }
+    };
+
+    // 实例存在性先确认，再解析身份：微软轨解析身份会联网刷新令牌（有副作用），
+    // 不该在一个注定 not_found 的启动上白跑一遍、更不该顺手改写凭据。
+    let identity = identity::resolve(
+        ctx,
+        args.account.as_deref(),
+        args.username.as_deref(),
+        args.dry_run,
+    )?;
+    let input = PlanInput {
+        auth: Some(identity.placeholders.clone()),
+        ..input
+    };
+    let isolation = resolve_isolation(ctx, profile, &input, args.dry_run)?;
+    let input = PlanInput {
+        // 派生结果就是 `--gameDir` 的取值（覆盖链已求值完）。
+        game_dir: Some(isolation.game_dir.clone()),
+        ..input
+    };
+
+    // D13：实例覆盖 > 托管匹配 > 系统。托管命中时把路径钉死交给 `snapshot::prepare`。
+    let java = super::java::resolve_for_launch(ctx, &input.version_id, input.java.as_deref());
+    let input = PlanInput {
+        java: java.override_path.clone(),
+        ..input
+    };
+
+    let plan = snapshot::prepare(ctx, &input)?;
+    let config = LauncherConfig::new(ctx.sessions_root())
+        .with_launcher(super::meta::LAUNCHER_NAME, env!("CARGO_PKG_VERSION"));
+    let launcher = Launcher::new(config);
+    let mut human = Vec::new();
+    human.push(format!(
+        "隔离档位 {}（来源 {}）· 运行目录 {}",
+        isolation.isolation.as_str(),
+        isolation.source.as_str(),
+        isolation.game_dir.display()
+    ));
+    if let Some(warning) = &isolation.warning {
+        human.push(format!("提示: {warning}"));
+    }
+    human.push(identity_line(&identity));
+    for note in &identity.notes {
+        human.push(format!("提示: {note}"));
+    }
+    human.push(java.summary());
+    for warning in java.warnings() {
+        human.push(format!("告警: {warning}"));
+    }
+
+    if args.dry_run {
+        let dry = launcher
+            .dry_run(&plan.request)
+            .map_err(|error| map_launch_error(&error, ctx))?;
+        let mut lines = vec![dry.line().to_string()];
+        lines.push(format!(
+            "（--dry-run：未启动进程 · classpath {} 项 · 编码 {}）",
+            dry.classpath_entries, dry.encoding
+        ));
+        if let Some(natives) = &dry.natives {
+            lines.push(format!("natives：{}", natives.summary()));
+        }
+        let mut warnings = dry.warnings.clone();
+        warnings.extend(java.warnings());
+        // 人读行里 Java 告警已经在上面打过一次，这里只补 `dry_run` 自己新发现的。
+        for warning in &dry.warnings {
+            lines.push(format!("告警: {warning}"));
+        }
+        human.extend(lines);
+        let natives = dry.natives.as_ref().map(|natives| {
+            json!({
+                "dir": natives.dir.display().to_string(),
+                "files": natives.files,
+                "skipped": natives.skipped,
+                "ignored": natives.ignored,
+                "jars": natives.jars,
+                "custom": natives.custom,
+                "up_to_date": natives.up_to_date,
+                "era": natives.era.as_str(),
+            })
+        });
+        let data = json!({
+            "dry_run": true,
+            "instance_found": instance_found,
+            "version_id": plan.version_id,
+            "isolation": isolation.isolation.as_str(),
+            "isolation_source": isolation.source.as_str(),
+            "game_dir": isolation.game_dir.display().to_string(),
+            "mode_change_warning": isolation.warning,
+            "account": account_json(&identity),
+            "java": java.to_json(),
+            "program": dry.program.display().to_string(),
+            "argv": dry.argv,
+            "display": dry.display,
+            "classpath_entries": dry.classpath_entries,
+            "encoding": dry.encoding,
+            "warnings": warnings,
+            "natives": natives,
+            "adapter_warnings": plan.warnings,
+        });
+        return Ok(Report::new(data, human));
+    }
+
+    let handle = launcher
+        .launch(&plan.request)
+        .map_err(|error| map_launch_error(&error, ctx))?;
+    let data = json!({
+        "dry_run": false,
+        "instance_found": instance_found,
+        "isolation": isolation.isolation.as_str(),
+        "isolation_source": isolation.source.as_str(),
+        "game_dir": isolation.game_dir.display().to_string(),
+        "mode_change_warning": isolation.warning,
+        "account": account_json(&identity),
+        "java": java.to_json(),
+        "warnings": java.warnings(),
+        "session_id": handle.session_id,
+        "log_path": handle.log_path.display().to_string(),
+        "exit_code": handle.exit.code,
+        "exit_type": handle.exit.exit_type.as_str(),
+        "uptime_ms": handle.uptime_ms,
+        "summary": handle.exit.summary(),
+        "artifacts": handle.artifacts.iter().map(|artifact| artifact.path.display().to_string()).collect::<Vec<_>>(),
+        "adapter_warnings": plan.warnings,
+    });
+    human.push(format!(
+        "会话 {} 结束：{}",
+        handle.session_id,
+        handle.exit.summary()
+    ));
+    human.push(format!("事件流: {}", handle.log_path.display()));
+    Ok(Report::new(data, human))
+}
+
+/// 隔离派生的结果（运行目录 + 生效档位 + 提示）。
+struct IsolationPlan {
+    /// 生效运行目录（喂 `--gameDir`）。
+    game_dir: PathBuf,
+    /// 生效档位。
+    isolation: Isolation,
+    /// 档位来自哪一层（`temporary` / `instance` / `global`）。
+    source: unlucky_core::game::IsolationSource,
+    /// 切换检测提示（两侧都有内容时；`None` = 不必提示）。
+    warning: Option<String>,
+}
+
+/// 按覆盖链派生运行目录，并在启动时做一次切换检测。
+///
+/// 覆盖链：临时参数（`ull launch` 暂无该 flag，留 `None`） > 实例 `isolation` > 全局 `instances.mode`。
+/// 切换检测只探测 `mods/saves/config` 的条目数并写进实例文件的 `lastModeChange`，
+/// **不迁移任何数据**（D20 定案）；提示只展示一次（`warned` 落盘）。
+///
+/// 遗留实例（`profiles.json` 有档案、`config/instances/<id>.json` 还没有——M27 之前的形态）
+/// 会在**首次真启动**时补建基线文件：否则这批「最可能撞上存档消失」的用户永远拿不到提示。
+/// `--dry-run` 仍然一个字节都不写。
+fn resolve_isolation(
+    ctx: &Ctx,
+    profile: Option<&unlucky_core::game::InstanceProfile>,
+    input: &PlanInput,
+    dry_run: bool,
+) -> Result<IsolationPlan, CliError> {
+    let global_mode = global_mode(ctx);
+    let mut config = match profile {
+        Some(profile) => {
+            read_instance_config(&ctx.layout(), profile.id.as_str()).map_err(|error| {
+                CliError::user(
+                    "instance_config",
+                    format!("读实例设置 {} 失败：{error}", profile.id.as_str()),
+                )
+            })?
+        }
+        None => None,
+    };
+    // 补建基线：有档案没有设置文件 → 先按最小配置在内存里建一份（落盘看下面的 dirty）。
+    let bootstrap = config.is_none() && profile.is_some();
+    if bootstrap {
+        config = Some(InstanceConfig::new(
+            input.instance_id.clone(),
+            input.version_id.clone(),
+        ));
+    }
+    // 读兼容：M27 之前的档案只在 profiles.json 里存 `game_dir`；这种「显式指定目录」的历史语义
+    // 等价于 `custom`，不要静默退回全局共享。补建基线时把这条映射**写进文件**，
+    // 让实例文件成为唯一真相（profiles.json 的 `game_dir` 是遗留字段）。
+    if let Some(config) = config.as_mut() {
+        if config.isolation.is_none() {
+            if let Some(dir) = profile
+                .and_then(|profile| profile.game_dir.clone())
+                .filter(|dir| !dir.as_os_str().is_empty())
+            {
+                config.isolation = Some(Isolation::Custom);
+                config.game_dir = Some(dir);
+            }
+        }
+    }
+
+    let derivation = derive_game_dir(
+        &ctx.game(),
+        &input.version_id,
+        global_mode,
+        config.as_ref(),
+        None,
+    )
+    .map_err(|error| CliError::user("isolation", error.to_string()))?;
+
+    // 切换检测：生效档位与记录里的 `to` 不同 → 记一次（探测双侧，只记事实）。
+    let at = format_rfc3339_millis(now());
+    let mut dirty = false;
+    let warning = match config.as_mut() {
+        Some(config) => {
+            let changed = observe_mode(config, &ctx.game(), &at, derivation.isolation)
+                .map_err(|error| CliError::user("isolation_probe", error.to_string()))?;
+            let warning = config.take_mode_change_warning();
+            dirty = bootstrap || changed || warning.is_some();
+            warning.map(|warning| warning.message())
+        }
+        None => None,
+    };
+    // `--dry-run` 不落盘（否则「只看一眼」也会吃掉一次性提示、改写实例状态）。
+    if !dry_run && dirty {
+        if let Some(config) = config.as_ref() {
+            write_instance_config(&ctx.layout(), config).map_err(|error| {
+                CliError::user("instance_config", format!("写实例设置失败：{error}"))
+            })?;
+        }
+    }
+
+    Ok(IsolationPlan {
+        game_dir: derivation.game_dir,
+        isolation: derivation.isolation,
+        source: derivation.source,
+        warning,
+    })
+}
+
+/// 全局默认隔离模式（`launcher.json` 的 `instances.mode`，缺键/坏值一律按 D20 默认 `isolated`）。
+fn global_mode(ctx: &Ctx) -> IsolationMode {
+    let store = SettingStore::load(ctx.launcher_config(), launcher_schema());
+    store
+        .doc()
+        .effective_str("instances.mode")
+        .and_then(IsolationMode::parse)
+        .unwrap_or_default()
+}
+
+fn map_launch_error(error: &LaunchError, ctx: &Ctx) -> CliError {
+    let hint = format!("版本本体目录：{}", ctx.game().versions_dir().display());
+    CliError::user("launch", error.to_string()).with_hint(hint)
+}
+
+fn instance_hint(profiles: &ProfileList) -> String {
+    if profiles.profiles.is_empty() {
+        "用 `%prog% instances list` 查看实例，或 `%prog% install <version>` 登记一个".to_string()
+    } else {
+        let names: Vec<&str> = profiles
+            .profiles
+            .iter()
+            .map(|profile| profile.name.as_str())
+            .collect();
+        format!("可用实例：{}", names.join("、"))
+    }
+}
+
+/// 人读一行：本次用谁的身份启动。
+fn identity_line(identity: &Identity) -> String {
+    match &identity.account {
+        Some(meta) => format!(
+            "账户 {}（{}）· UUID {}",
+            meta.display_name(),
+            meta.kind.label(),
+            identity.placeholders.uuid
+        ),
+        None => format!(
+            "账户 离线占位 {}（未登记账户）",
+            identity.placeholders.player_name
+        ),
+    }
+}
+
+/// `--json` 里的身份块（**只有可公开字段**，token 永远不出现）。
+fn account_json(identity: &Identity) -> serde_json::Value {
+    match &identity.account {
+        Some(meta) => json!({
+            "name": meta.display_name(),
+            "kind": meta.kind.as_str(),
+            "profile_id": identity.placeholders.uuid,
+            "account_id": meta.id.as_str(),
+            "registered": true,
+        }),
+        None => json!({
+            "name": identity.placeholders.player_name,
+            "kind": "offline-placeholder",
+            "profile_id": identity.placeholders.uuid,
+            "registered": false,
+        }),
+    }
+}
diff --git a/crates/cli/src/commands/meta.rs b/crates/cli/src/commands/meta.rs
new file mode 100644
index 0000000..49dafa9
--- /dev/null
+++ b/crates/cli/src/commands/meta.rs
@@ -0,0 +1,68 @@
+//! 元命令：`--version` / 无子命令 / `help`。
+
+use serde_json::json;
+
+use crate::cli::{help, program};
+use crate::os;
+use crate::output::Report;
+
+/// 启动器名（`${launcher_name}` 与 `--version` 输出共用）。
+pub const LAUNCHER_NAME: &str = "UnluckyLauncher";
+
+/// 版本 + 系统摘要（`ull --version`，D19 §5-2 要求附带 os 摘要）。
+///
+/// 探测走 `core::platform::os_info::current()`（进程内缓存），未达基线时附带升级指引。
+/// 自称的名字取 argv[0]（M82）：GUI 二进制调进来时是 `unlucky-launcher`，`ull` 自己跑时仍是 `ull`。
+#[must_use]
+pub fn version() -> Report {
+    let info = os::detect();
+    let invoked_as = program::name();
+    let data = json!({
+        "name": invoked_as,
+        "package": env!("CARGO_PKG_NAME"),
+        "version": env!("CARGO_PKG_VERSION"),
+        "os": os::to_json(&info),
+    });
+    let mut human = vec![
+        format!(
+            "{invoked_as} {}（{}）",
+            env!("CARGO_PKG_VERSION"),
+            env!("CARGO_PKG_NAME")
+        ),
+        format!("os: {}", os::summary_line(&info)),
+    ];
+    human.extend(os::notes(&info));
+    Report::new(data, human)
+}
+
+/// 无子命令：版本摘要 + 帮助（用户原话「无子命令时 --version + --help」）。
+#[must_use]
+pub fn welcome() -> Report {
+    let version_report = version();
+    let mut human = version_report.human;
+    let text = general_help();
+    human.push(String::new());
+    human.extend(text.lines().map(str::to_string));
+    let mut data = version_report.data;
+    data["help"] = json!(text);
+    Report::new(data, human)
+}
+
+/// 帮助（`ull help <命令>` 给该命令，未知主题退回总帮助）。
+#[must_use]
+pub fn help(topic: Option<&str>) -> Report {
+    let text = match topic.and_then(help::topic) {
+        Some(text) => program::fill(text),
+        None => general_help(),
+    };
+    let data = json!({
+        "topic": topic,
+        "text": text,
+    });
+    Report::new(data, text.lines().map(str::to_string).collect())
+}
+
+/// 总帮助，按被调用的二进制名自述（`ull` 自己跑时逐字不变）。
+fn general_help() -> String {
+    program::fill(help::general())
+}
diff --git a/crates/cli/src/commands/mod.rs b/crates/cli/src/commands/mod.rs
new file mode 100644
index 0000000..b422684
--- /dev/null
+++ b/crates/cli/src/commands/mod.rs
@@ -0,0 +1,224 @@
+//! 命令分发：命令模型 → 具体实现，并统一挂上环境提示。
+
+pub mod accounts;
+pub mod agent;
+pub mod config;
+pub mod identity;
+pub mod install;
+pub mod instances;
+pub mod java;
+pub mod java_launch;
+pub mod java_vendors;
+pub mod launch;
+pub mod meta;
+pub mod pack;
+pub mod sessions;
+pub mod snapshot;
+
+use crate::cli::{Command, Globals, Invocation};
+use crate::context::Ctx;
+use crate::error::CliError;
+use crate::output::{Outcome, Report};
+
+/// 执行一条已解析的命令。
+///
+/// # Errors
+///
+/// 用法/数据根/目标不存在等用户错误，或序列化失配等内部错误。
+pub fn run(invocation: &Invocation) -> Result<Outcome, CliError> {
+    match &invocation.command {
+        // 这三条不需要数据根（`--version` 在不达基线的机器上也要能跑，用于诊断）。
+        Command::Welcome => Ok(Outcome::new(meta::welcome())),
+        Command::Version => Ok(Outcome::new(meta::version())),
+        Command::Help(topic) => Ok(Outcome::new(meta::help(topic.as_deref()))),
+        Command::InstancesList => with_ctx(&invocation.globals, instances::list),
+        Command::Install(args) => with_ctx(&invocation.globals, |ctx| install::run(ctx, args)),
+        Command::PackImport(args) => {
+            with_ctx_outcome(&invocation.globals, |ctx| pack::run(ctx, args))
+        }
+        Command::Launch(args) => with_ctx(&invocation.globals, |ctx| launch::run(ctx, args)),
+        Command::SessionsList { limit } => {
+            with_ctx(&invocation.globals, |ctx| sessions::list(ctx, *limit))
+        }
+        Command::Logs(args) => with_ctx(&invocation.globals, |ctx| sessions::logs(ctx, args)),
+        Command::Diag(args) => with_ctx(&invocation.globals, |ctx| sessions::diag(ctx, args)),
+        Command::ConfigGet(args) => with_ctx(&invocation.globals, |ctx| {
+            config::get(ctx, args.key.as_deref(), args.show_secret)
+        }),
+        Command::ConfigSet(args) => with_ctx(&invocation.globals, |ctx| {
+            config::set(ctx, &args.key, &args.value)
+        }),
+        Command::JavaList => with_ctx(&invocation.globals, java::list),
+        Command::JavaInstall { major, vendor } => with_ctx(&invocation.globals, |ctx| {
+            java::install(ctx, *major, *vendor)
+        }),
+        Command::JavaVendors => with_ctx(&invocation.globals, java::vendors),
+        Command::AccountsList => with_ctx(&invocation.globals, accounts::list),
+        Command::AccountsAdd(args) => with_ctx(&invocation.globals, |ctx| accounts::add(ctx, args)),
+        Command::AccountsRemove { name } => {
+            with_ctx(&invocation.globals, |ctx| accounts::remove(ctx, name))
+        }
+        // `AgentServe` 由 `runner::run` 提前分流（stdio 形态下 stdout 就是协议流，
+        // 不能走「先返回 Report 再打印」的路径）；这里只兜住「有人直接调 commands::run」。
+        Command::AgentServe(_) => Err(CliError::usage(
+            "agent serve 必须在进程入口直接运行（runner 会提前分流）",
+        )),
+        Command::AgentConfig { port } => {
+            with_ctx(&invocation.globals, |ctx| agent::config_report(ctx, *port))
+        }
+    }
+}
+
+/// `core::auth` 的错误 → CLI 错误（保留稳定机读码；文案已是人话，这里只补「下一步」）。
+///
+/// 集中一处的原因：账户相关命令（`accounts *`）与 `launch` 的身份解析要为**同一批**
+/// 错误给出一致的码与提示——两处各写一份必然会漂。
+pub(crate) fn map_auth_error(error: unlucky_core::auth::AuthError) -> CliError {
+    use unlucky_core::auth::body;
+    use unlucky_core::auth::AuthError;
+    let hint = match &error {
+        AuthError::Canceled => Some("登录被取消，可以重跑一次".to_string()),
+        AuthError::Timeout { .. } => {
+            Some("重新执行 `%prog% accounts add msa` 拿新的用户码".to_string())
+        }
+        AuthError::CredentialExpired => Some("重新登录：%prog% accounts add msa".to_string()),
+        // M117：id 缺失是「没配置」，不是「没实现」。hint 里给**能照抄的命令**（两条路：
+        // 运行期一次性的、构建期烘进二进制的），别只丢一个变量名让用户自己猜。
+        AuthError::Unsupported(_) => Some(format!(
+            "先配 Azure 公共客户端 id（id 不进仓库）：\
+`{env}=<id> %prog% accounts add msa`；\
+想让二进制自带就构建时注入 `{env}=<id> cargo build`。环境变量优先于构建期注入。",
+            env = unlucky_core::auth::microsoft::CLIENT_ID_ENV
+        )),
+        AuthError::Conflict { .. } => Some("用 `%prog% accounts list` 查看已有账户".to_string()),
+        AuthError::NotFound { .. } => Some("用 `%prog% accounts list` 查看账户名".to_string()),
+        AuthError::Denied { code, .. } if code == "no_profile" || code == "no_license" => {
+            Some("去 minecraft.net 检查该账号的 Java 版拥有权与档案".to_string())
+        }
+        AuthError::Xbox { .. } => {
+            Some("去 xbox.com / 家庭组设置里解决该账号的 Xbox 限制".to_string())
+        }
+        // M38 的两类分流落到 hint 行：拦截页（HTML/纯文本/空体）先查网络，
+        // JSON 拒绝按步骤查许可与区域。`code()` 仍是 "denied"（M31 兼容），
+        // 细分结论由 `detail_code()` 带在 hint 里，排障脚本照样能机读分流。
+        AuthError::Response(detail) if detail.is_interception() => Some(format!(
+            "检查网络或代理（关掉/换掉代理后再试，必要时用镜像方案）；诊断码 {}",
+            detail.detail_code()
+        )),
+        AuthError::Response(detail) => Some(format!(
+            "{}；诊断码 {}",
+            body::advice(&detail.step, detail.kind),
+            detail.detail_code()
+        )),
+        _ => None,
+    };
+    let cli = CliError::user(error.code(), error.message());
+    match hint {
+        Some(hint) => cli.with_hint(hint),
+        None => cli,
+    }
+}
+
+/// GUI / CLI 共用的**启动日志一行**：`[auth] msa client_id=configured|missing source=env|build|none`。
+///
+/// M117：判据（配没配 + 从哪来）在 `core::auth::microsoft::client_id_status()`，这里只做出面——
+/// `app-iced` 不直接依赖 `unlucky-core`，而 `unlucky-cli` 已经是它的依赖（同一个二进制既跑
+/// GUI 也跑 `ull` 子命令）。所以「谁打印」不在 UI 侧重算一遍判据，免得两份口径漂。
+///
+/// 用途：日后看启动日志能一眼分辨「没配置」与「配了但登录失败」，不用再猜。
+#[must_use]
+pub fn msa_client_id_log_line() -> String {
+    unlucky_core::auth::microsoft::client_id_status().log_line()
+}
+
+/// 需要数据根的命令：解析上下文 → D19 支持级别闸门 → 执行 → 挂环境提示。
+fn with_ctx<F>(globals: &Globals, action: F) -> Result<Outcome, CliError>
+where
+    F: FnOnce(&Ctx) -> Result<Report, CliError>,
+{
+    let ctx = Ctx::resolve(globals)?;
+    ctx.ensure_supported()?;
+    let report = action(&ctx)?;
+    Ok(Outcome::with_warnings(report, ctx.notes()))
+}
+
+/// 同 [`with_ctx`]，但命令自己组装 [`Outcome`]（需要指定退出码或多态结果时用）。
+///
+/// 只有 `pack import` 走这条路：它的三态要 0 / 3 / 1 三个退出码，`Report` 表达不了。
+fn with_ctx_outcome<F>(globals: &Globals, action: F) -> Result<Outcome, CliError>
+where
+    F: FnOnce(&Ctx) -> Result<Outcome, CliError>,
+{
+    let ctx = Ctx::resolve(globals)?;
+    ctx.ensure_supported()?;
+    let mut outcome = action(&ctx)?;
+    outcome.warnings.extend(
+        ctx.notes()
+            .into_iter()
+            .map(|line| crate::cli::program::fill(&line)),
+    );
+    Ok(outcome)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::map_auth_error;
+    use unlucky_core::auth::{AuthError, BodyKind, ResponseDetail};
+
+    fn response(step: &str, kind: BodyKind) -> AuthError {
+        AuthError::Response(Box::new(ResponseDetail {
+            step: step.to_string(),
+            what: "Minecraft 登录被拒".to_string(),
+            status: 403,
+            content_type: None,
+            kind,
+            server_message: None,
+            digest: String::new(),
+        }))
+    }
+
+    #[test]
+    fn response_hints_split_network_from_license_and_carry_detail_code() {
+        let blocked = map_auth_error(response("login_with_xbox", BodyKind::Html));
+        assert_eq!(blocked.code(), "denied", "code() 仍是 M31 的 denied");
+        let hint = blocked.hint().expect("拦截页要有 hint").to_string();
+        assert!(hint.contains("代理"), "{hint}");
+        assert!(hint.contains("login_with_xbox_non_json"), "{hint}");
+
+        let denied = map_auth_error(response("login_with_xbox", BodyKind::Json));
+        let hint = denied.hint().expect("JSON 拒绝要有 hint").to_string();
+        assert!(hint.contains("许可"), "{hint}");
+        assert!(!hint.contains("代理"), "{hint}");
+        assert!(hint.contains("login_with_xbox_403"), "{hint}");
+    }
+
+    #[test]
+    fn startup_log_line_is_one_machine_readable_line() {
+        // M117：这行是「没配置 vs 配了但登录失败」的唯一机读判据，形状不能漂。
+        let line = super::msa_client_id_log_line();
+        assert!(line.starts_with("[auth] msa client_id="), "{line}");
+        assert!(line.contains(" source="), "{line}");
+        assert!(!line.contains('\n'), "必须正好一行：{line}");
+        let source = line.rsplit("source=").next().unwrap_or_default();
+        assert!(matches!(source, "env" | "build" | "none"), "{line}");
+    }
+
+    #[test]
+    fn missing_client_id_hint_carries_a_runnable_command() {
+        // M117：用户实跑看到的「本期未支持」是错的表述，而且 hint 只丢了变量名。
+        // 判据：文案说「未配置」、不说「未支持/未实现」，并给出能照抄的命令（含变量名）。
+        let cli = map_auth_error(AuthError::Unsupported(
+            unlucky_core::auth::microsoft::MISSING_CLIENT_ID_MESSAGE.to_string(),
+        ));
+        let message = cli.message();
+        assert_eq!(cli.code(), "unsupported", "机读码保持兼容");
+        assert!(message.contains("客户端 id"), "{message}");
+        assert!(!message.contains("未支持"), "{message}");
+        assert!(!message.contains("未实现"), "{message}");
+
+        let hint = cli.hint().expect("缺配置要有 hint").to_string();
+        assert!(hint.contains("ULL_MSA_CLIENT_ID=<id>"), "{hint}");
+        assert!(hint.contains("cargo build"), "{hint}");
+        assert!(hint.contains("accounts add msa"), "{hint}");
+    }
+}
diff --git a/crates/cli/src/commands/pack.rs b/crates/cli/src/commands/pack.rs
new file mode 100644
index 0000000..b762652
--- /dev/null
+++ b/crates/cli/src/commands/pack.rs
@@ -0,0 +1,246 @@
+//! `pack import <file>`：整合包导入（M111）。
+//!
+//! 逻辑**全在** `core::addon::import`：本文件只做三件事——参数落地、下载引擎接线、两种输出。
+//! 之所以坚持这一层很薄，是因为 M113 的导入页要复用的是 core 的 `import_pack` + `ImportReport`，
+//! 不是这里的打印逻辑。
+//!
+//! # 三态退出码（脚本契约）
+//!
+//! | `data.status` | 退出码 | 含义 |
+//! |---------------|--------|------|
+//! | `success` | `0` | 全部落地、无冲突 |
+//! | `partial` | `3` | 有缺文件或有保留用户文件的冲突（实例可用但不完整） |
+//! | `failed` | `1` | 致命失败，**已整包回滚** |
+//!
+//! `--json` 的信封在三种状态下**都是** `{"ok":true,"data":{…}}`（命令跑完了），分流看
+//! `data.status` / `data.error.code` 或退出码；`ok:false` 只用于"命令没跑起来"（参数错、
+//! 数据根不可用），与其它命令一致。
+
+use std::path::Path;
+use std::sync::{Arc, Mutex};
+
+use serde_json::json;
+use unlucky_core::addon::import::{
+    import_pack, ConflictChoice, ConflictPolicy, DownloadEngineFetcher, FileAction, ImportProgress,
+    ImportReport, ImportRequest, ImportStatus,
+};
+use unlucky_core::download::blocking::block_on;
+use unlucky_core::download::cache::now_ms;
+use unlucky_core::download::region::{decide_from, load_cached, store_cached};
+use unlucky_core::download::region_system::detect_signals;
+use unlucky_core::download::{
+    ContentCache, DownloadEngine, EngineConfig, HealthRegistry, MirrorTable,
+};
+
+use crate::cli::PackImportArgs;
+use crate::context::Ctx;
+use crate::error::CliError;
+use crate::output::{Outcome, Report};
+
+/// `ull pack import`。
+///
+/// # Errors
+///
+/// 整合包路径不存在（用户错误）。导入本身的失败**不是** `Err`：它走三态报告 + 退出码。
+pub fn run(ctx: &Ctx, args: &PackImportArgs) -> Result<Outcome, CliError> {
+    if !args.path.exists() {
+        return Err(CliError::user(
+            "not_found",
+            format!("整合包不存在：{}", args.path.display()),
+        )
+        .with_hint("给 .zip / .mrpack 文件，或 MultiMC·Prism 的实例目录"));
+    }
+    let target = args
+        .target
+        .clone()
+        .unwrap_or_else(|| ctx.game().root().to_path_buf());
+
+    let stages: Arc<Mutex<Vec<&'static str>>> = Arc::new(Mutex::new(Vec::new()));
+    let recorder = Arc::clone(&stages);
+    let sink: unlucky_core::addon::ImportProgressSink =
+        Arc::new(move |progress: &ImportProgress| {
+            if let Ok(mut seen) = recorder.lock() {
+                if seen.last().copied() != Some(progress.stage.as_str()) {
+                    seen.push(progress.stage.as_str());
+                }
+            }
+        });
+
+    let engine = build_engine(ctx);
+    let fetcher = DownloadEngineFetcher::new(&engine);
+    let layout = ctx.layout();
+    let mut request = ImportRequest::new(&args.path, &target)
+        .with_fetcher(&fetcher)
+        .with_progress(sink);
+    if args.overwrite {
+        request = request.with_conflict_policy(ConflictPolicy::Overwrite);
+    }
+    if !args.no_register {
+        request = request.with_registration(&layout, args.name.as_deref());
+    }
+
+    let report = block_on(import_pack(&request));
+    let seen = stages.lock().map(|seen| seen.clone()).unwrap_or_default();
+    Ok(outcome(ctx, &report, &target, &seen, args))
+}
+
+/// 组装 `Outcome`（三态 → 退出码 + 两种输出）。
+fn outcome(
+    ctx: &Ctx,
+    report: &ImportReport,
+    target: &Path,
+    stages: &[&'static str],
+    args: &PackImportArgs,
+) -> Outcome {
+    let mut data = serde_json::to_value(report).unwrap_or_else(|_| {
+        json!({
+            "status": report.status.as_str(),
+            "error": {"code": "serialize", "message": "报告序列化失败"},
+        })
+    });
+    if let Some(object) = data.as_object_mut() {
+        object.insert("target".to_string(), json!(target.display().to_string()));
+        object.insert("stages".to_string(), json!(stages));
+        object.insert("status_key".to_string(), json!(report.status.message_key()));
+        object.insert("installed_files".to_string(), json!(report.installed()));
+        object.insert(
+            "target_is_default".to_string(),
+            json!(args.target.is_none()),
+        );
+    }
+
+    let mut human: Vec<String> = Vec::new();
+    human.push(format!(
+        "整合包 {}（{}）→ {}{}",
+        report.pack_name.as_deref().unwrap_or("<未读成>"),
+        report.format.as_deref().unwrap_or("-"),
+        target.display(),
+        if args.target.is_none() {
+            "（缺省 = 数据根的共享游戏目录）"
+        } else {
+            ""
+        }
+    ));
+    if !stages.is_empty() {
+        human.push(format!("阶段：{}", stages.join(" → ")));
+    }
+    human.push(format!(
+        "结果：{}  文件 新{} / 覆盖{} / 跳过{} / 保留{}  冲突 {}  缺文件 {}",
+        status_label(report),
+        count_action(report, FileAction::Installed),
+        count_action(report, FileAction::Replaced),
+        count_action(report, FileAction::SkippedIdentical),
+        count_action(report, FileAction::KeptUser),
+        report.conflicts.len(),
+        report.missing.len(),
+    ));
+    if let Some(loader) = &report.loader {
+        human.push(format!(
+            "加载器：{} {}（版本 id {}）",
+            loader.kind.label(),
+            loader.loader_version,
+            loader.version_id
+        ));
+        if let Some(version_id) = &report.version_id {
+            if !ctx.game().is_version_installed(version_id) {
+                human.push(format!(
+                    "提示：{version_id} 还没安装，启动前先跑 `%prog% install` 装它"
+                ));
+            }
+        }
+    }
+    if let Some(memory) = report.max_memory_mb {
+        human.push(format!("内存：{memory} MB（来自 instance.cfg）"));
+    }
+    for component in &report.rejected_components {
+        human.push(format!(
+            "未支持的 component：{} {}（{}）",
+            component.uid,
+            component.version.as_deref().unwrap_or("-"),
+            component.message_key
+        ));
+    }
+    for conflict in &report.conflicts {
+        human.push(format!(
+            "冲突：{}（{}，已{}）",
+            conflict.path,
+            conflict.message_key,
+            match conflict.choice {
+                ConflictChoice::KeepUser => "保留你的文件",
+                ConflictChoice::Overwrite => "按包覆盖",
+            }
+        ));
+    }
+    for missing in &report.missing {
+        human.push(format!(
+            "缺文件：{}（{}：{}）",
+            missing.display, missing.message_key, missing.detail
+        ));
+    }
+    if let Some(registered) = &report.registered {
+        human.push(format!(
+            "已登记实例 {}（{}）{}",
+            registered.name,
+            registered.version_id,
+            if registered.created {
+                ""
+            } else {
+                "·复用已有档案"
+            }
+        ));
+    }
+    if let Some(error) = &report.error {
+        human.push(format!("错误：{}（{}）", error.message(), error.code()));
+        if let Some(hint) = error.hint() {
+            human.push(format!("提示：{hint}"));
+        }
+        if report.rolled_back {
+            human.push("已整包回滚：目标目录与导入前一致".to_string());
+        } else if let Some(rollback) = &report.rollback {
+            human.push(format!(
+                "回滚未完整：{} 项没回去（详见 --json 的 rollback.failed）",
+                rollback.failure_count()
+            ));
+        }
+    }
+
+    Outcome::new(Report { data, human }).with_exit_code(report.status.exit_code())
+}
+
+/// 状态的人读名。**失败要按回滚是否干净分叉**：不完整时不能说"已回滚"。
+fn status_label(report: &ImportReport) -> &'static str {
+    match report.status {
+        ImportStatus::Success => "成功",
+        ImportStatus::Partial => "部分成功",
+        ImportStatus::Failed if report.rolled_back => "失败（已回滚）",
+        ImportStatus::Failed => "失败（回滚不完整）",
+    }
+}
+
+fn count_action(report: &ImportReport, action: FileAction) -> usize {
+    report
+        .files
+        .iter()
+        .filter(|file| file.action == action)
+        .count()
+}
+
+/// 与 `install` 共用同一套引擎构造（镜像 / 地区 / 健康度 / 内容缓存）。
+fn build_engine(ctx: &Ctx) -> DownloadEngine {
+    let layout = ctx.layout();
+    let cache_root = layout.cache();
+    let now = now_ms();
+    let region_path = cache_root.join("region.json");
+    let region = load_cached(&region_path, now).unwrap_or_else(|| {
+        let profile = decide_from(&detect_signals(), now);
+        let _ = store_cached(&region_path, &profile);
+        profile
+    });
+    DownloadEngine::new(
+        EngineConfig::default(),
+        Arc::new(MirrorTable::builtin()),
+        Arc::new(region),
+        Arc::new(HealthRegistry::open_in(&cache_root, now)),
+        Arc::new(ContentCache::open(&cache_root)),
+    )
+}
diff --git a/crates/cli/src/commands/sessions.rs b/crates/cli/src/commands/sessions.rs
new file mode 100644
index 0000000..e8865c0
--- /dev/null
+++ b/crates/cli/src/commands/sessions.rs
@@ -0,0 +1,292 @@
+//! `sessions list` / `logs` / `diag`：读 M18 的会话索引与 JSONL 事件流。
+//!
+//! 数据源形状见 `DevDocs/SubAgentsTalk/launch-接口约定.md` §2/§5：
+//! - `<sessions_root>/game/index.jsonl`：一会话一行摘要（同 id 取最后一行，倒序）；
+//! - `<sessions_root>/game/<id>.jsonl`：事件流（`kind` + `payload`）。
+//!
+//! `diag` 把「退出信号 + stdout/stderr 文本」喂给 M15 的内嵌规则集，输出结构化结论。
+
+use std::path::Path;
+
+use serde_json::{json, Value};
+use unlucky_core::diagnose::collectors::{ExitSignal, SignalOrigin};
+use unlucky_core::diagnose::engine::{Diagnoser, DiagnosisInput};
+use unlucky_core::diagnose::loader::RuleLoader;
+use unlucky_core::launch::session_index::{self, SessionIndexEntry};
+
+use crate::cli::{DiagArgs, LogsArgs};
+use crate::context::Ctx;
+use crate::error::CliError;
+use crate::output::Report;
+
+/// `ull sessions list [--limit N]`。
+///
+/// # Errors
+///
+/// 索引文件读不了时返回用户错误（不存在 = 空列表）。
+pub fn list(ctx: &Ctx, limit: usize) -> Result<Report, CliError> {
+    let index = ctx.session_index();
+    let entries = session_index::read_all(&index)
+        .map_err(|error| CliError::io("读会话索引", &index, &error))?;
+    let shown: Vec<&SessionIndexEntry> = entries.iter().take(limit).collect();
+
+    let rows: Vec<Value> = shown
+        .iter()
+        .map(|entry| {
+            json!({
+                "session_id": entry.session_id,
+                "instance_id": entry.instance_id,
+                "instance_name": entry.instance_name,
+                "game_version": entry.game_version,
+                "started_at": entry.started_at,
+                "ended_at": entry.ended_at,
+                "duration_ms": entry.duration_ms,
+                "exit_code": entry.exit_code,
+                "exit_type": entry.exit_type,
+                "silent_failure": entry.silent_failure,
+                "window_detected": entry.window_detected,
+                "crash_found": entry.crash_found,
+                "diagnosis_top": entry.diagnosis_top,
+            })
+        })
+        .collect();
+
+    let mut human = vec![format!(
+        "会话 {} 条（索引 {}）",
+        shown.len(),
+        index.display()
+    )];
+    if shown.is_empty() {
+        human.push("  （空）先用 `%prog% launch <实例>` 跑一局".to_string());
+    }
+    for entry in &shown {
+        human.push(format!(
+            "  {}  {}  {}  {}  {}",
+            entry.session_id,
+            entry.instance_name,
+            entry.game_version,
+            entry.started_at,
+            exit_label(entry),
+        ));
+    }
+
+    Ok(Report::new(json!({ "sessions": rows }), human))
+}
+
+/// `ull logs <sid> [--tail N]`：打印事件流末尾 N 条。
+///
+/// # Errors
+///
+/// 会话不存在/前缀有歧义、事件流读不了时返回用户错误。
+pub fn logs(ctx: &Ctx, args: &LogsArgs) -> Result<Report, CliError> {
+    let entry = find_entry(ctx, &args.session_id)?;
+    let path = event_path(ctx, &entry);
+    let events = read_events(&path)?;
+    let start = events.len().saturating_sub(args.tail.max(1));
+    let shown = &events[start..];
+
+    // 脱敏一次、两条输出共用：`--json` 是机器消费路径，不该比人类路径拿到更多原文。
+    let shown: Vec<Value> = shown.iter().map(redact_value).collect();
+    let mut human = vec![format!(
+        "会话 {} · {} · 事件 {} 条（显示末尾 {}）",
+        entry.session_id,
+        entry.instance_name,
+        events.len(),
+        shown.len()
+    )];
+    human.extend(shown.iter().map(render_event));
+
+    Ok(Report::new(
+        json!({
+            "session_id": entry.session_id,
+            "path": path.display().to_string(),
+            "total": events.len(),
+            "events": shown,
+        }),
+        human,
+    ))
+}
+
+/// `ull diag <sid> [--tail N]`：规则引擎诊断。
+///
+/// # Errors
+///
+/// 会话不存在、事件流读不了、结论序列化失败时返回错误。
+pub fn diag(ctx: &Ctx, args: &DiagArgs) -> Result<Report, CliError> {
+    let entry = find_entry(ctx, &args.session_id)?;
+    let path = event_path(ctx, &entry);
+    let events = read_events(&path)?;
+
+    let mut stdout_lines: Vec<&str> = Vec::new();
+    let mut stderr_lines: Vec<&str> = Vec::new();
+    let mut error_lines: u32 = 0;
+    for event in &events {
+        let Some(line) = event.pointer("/payload/line").and_then(Value::as_str) else {
+            continue;
+        };
+        match event.get("kind").and_then(Value::as_str) {
+            Some("stdout") => stdout_lines.push(line),
+            Some("stderr") => {
+                stderr_lines.push(line);
+                if event.pointer("/payload/level").and_then(Value::as_str) == Some("error") {
+                    error_lines += 1;
+                }
+            }
+            _ => {}
+        }
+    }
+    let stdout_text = tail_join(&stdout_lines, args.tail);
+    let stderr_text = tail_join(&stderr_lines, args.tail);
+
+    let exit = ExitSignal::classify(
+        entry.exit_code,
+        Some(entry.duration_ms),
+        error_lines,
+        &stderr_text,
+    );
+    let mut input = DiagnosisInput::new().with_exit(exit);
+    if !stdout_text.is_empty() {
+        input.push_text(SignalOrigin::Stdout, stdout_text);
+    }
+    if !stderr_text.is_empty() {
+        input.push_text(SignalOrigin::Stderr, stderr_text);
+    }
+
+    let loader = RuleLoader::embedded();
+    let diagnoser = Diagnoser::new(loader.rule_set().rules().to_vec());
+    let report = diagnoser.analyze(&input);
+    let record = serde_json::to_value(report.to_record())
+        .map_err(|error| CliError::internal("diagnosis_serialize", error.to_string()))?;
+
+    let mut human = vec![format!(
+        "会话 {} · {} · {} · {}",
+        entry.session_id,
+        entry.instance_name,
+        entry.game_version,
+        exit_label(&entry)
+    )];
+    match report.primary() {
+        Some(finding) => {
+            human.push(format!("主因: {}", finding.message));
+            if let Some(detail) = &finding.detail {
+                human.push(format!("说明: {detail}"));
+            }
+            for evidence in finding.evidence.iter().take(3) {
+                human.push(format!("证据: {}", evidence.render()));
+            }
+        }
+        None => human.push("规则引擎没有得出确定结论（needs_more_info）".to_string()),
+    }
+    human.push(format!(
+        "规则评估 {} 条 · 结论 {} 条 · 次生 {} 条",
+        report.rules_evaluated,
+        report.findings.len(),
+        report.secondary.len()
+    ));
+    let human: Vec<String> = human
+        .iter()
+        .map(|line| unlucky_agent::redact::redact_text(line))
+        .collect();
+
+    let payload = redact_value(&json!({
+        "session_id": entry.session_id,
+        "instance_id": entry.instance_id,
+        "game_version": entry.game_version,
+        "exit": {
+            "code": entry.exit_code,
+            "exit_type": entry.exit_type,
+            "silent_failure": entry.silent_failure,
+            "duration_ms": entry.duration_ms,
+        },
+        "diagnosis": record,
+    }));
+    Ok(Report::new(payload, human))
+}
+
+fn find_entry(ctx: &Ctx, key: &str) -> Result<SessionIndexEntry, CliError> {
+    let index = ctx.session_index();
+    let entries = session_index::read_all(&index)
+        .map_err(|error| CliError::io("读会话索引", &index, &error))?;
+    if let Some(entry) = entries.iter().find(|entry| entry.session_id == key) {
+        return Ok(entry.clone());
+    }
+    let matches: Vec<&SessionIndexEntry> = entries
+        .iter()
+        .filter(|entry| entry.session_id.starts_with(key))
+        .collect();
+    match matches.as_slice() {
+        [only] => Ok((*only).clone()),
+        [] => Err(
+            CliError::user("session_not_found", format!("找不到会话 `{key}`"))
+                .with_hint(format!("索引文件：{}", index.display())),
+        ),
+        _ => Err(CliError::user(
+            "session_ambiguous",
+            format!("`{key}` 匹配到 {} 个会话，请给更长的前缀", matches.len()),
+        )),
+    }
+}
+
+fn event_path(ctx: &Ctx, entry: &SessionIndexEntry) -> std::path::PathBuf {
+    ctx.sessions_root().join("game").join(&entry.log_path)
+}
+
+fn read_events(path: &Path) -> Result<Vec<Value>, CliError> {
+    let text = std::fs::read_to_string(path)
+        .map_err(|error| CliError::io("读会话事件流", path, &error))?;
+    Ok(text
+        .lines()
+        .filter(|line| !line.trim().is_empty())
+        .filter_map(|line| serde_json::from_str::<Value>(line).ok())
+        .collect())
+}
+
+fn tail_join(lines: &[&str], tail: usize) -> String {
+    let start = lines.len().saturating_sub(tail.max(1));
+    let mut text = lines[start..].join("\n");
+    if !text.is_empty() {
+        text.push('\n');
+    }
+    text
+}
+
+fn render_event(event: &Value) -> String {
+    let ts = event.get("ts").and_then(Value::as_str).unwrap_or("");
+    let kind = event.get("kind").and_then(Value::as_str).unwrap_or("?");
+    let detail = event
+        .pointer("/payload/line")
+        .and_then(Value::as_str)
+        .or_else(|| event.pointer("/payload/summary").and_then(Value::as_str))
+        .unwrap_or_default();
+    format!("[{ts}] {kind} {detail}")
+}
+
+/// 递归脱敏任意 JSON（所有字符串过 `redact_text`：主目录用户名段 + Bearer 令牌）。
+fn redact_value(value: &Value) -> Value {
+    match value {
+        Value::String(text) => Value::String(unlucky_agent::redact::redact_text(text)),
+        Value::Array(items) => Value::Array(items.iter().map(redact_value).collect()),
+        Value::Object(map) => Value::Object(
+            map.iter()
+                .map(|(key, child)| (key.clone(), redact_value(child)))
+                .collect(),
+        ),
+        other => other.clone(),
+    }
+}
+
+fn exit_label(entry: &SessionIndexEntry) -> String {
+    let code = entry
+        .exit_code
+        .map_or_else(|| "无退出码".to_string(), |code| format!("退出码 {code}"));
+    let exit_type = entry
+        .exit_type
+        .clone()
+        .unwrap_or_else(|| "unknown".to_string());
+    let silent = if entry.silent_failure {
+        " · 静默失败"
+    } else {
+        ""
+    };
+    format!("{code}/{exit_type}{silent}")
+}
diff --git a/crates/cli/src/commands/snapshot.rs b/crates/cli/src/commands/snapshot.rs
new file mode 100644
index 0000000..b37fd9a
--- /dev/null
+++ b/crates/cli/src/commands/snapshot.rs
@@ -0,0 +1,205 @@
+//! 实例 → [`LaunchRequest`] 的装配：launch 命令与 `--dry-run` 共用这一段。
+//!
+//! 全部走 core 的既有公共面（`game::resolve` / `arguments.expand` / `GameLayout` /
+//! `launch::adapter::build_request`），CLI 不复制任何继承/参数展开逻辑。
+
+use std::path::PathBuf;
+
+use crate::context::Ctx;
+use crate::error::CliError;
+use unlucky_core::game::arguments::Environment;
+use unlucky_core::game::{self, ProfileId, VersionJson};
+use unlucky_core::launch::adapter::{
+    self, AdapterOptions, AdapterWarning, LibraryInput, SnapshotInput,
+};
+use unlucky_core::launch::request::{AuthPlaceholders, LaunchRequest, MemoryOptions};
+
+/// 装配输入（来自命令行 + 实例档案）。
+#[derive(Debug, Clone, Default)]
+pub struct PlanInput {
+    /// 版本 id（实例绑定的 `versions/<id>/`）。
+    pub version_id: String,
+    /// 实例 id（写进会话索引；无档案时为空）。
+    pub instance_id: String,
+    /// 实例显示名。
+    pub instance_name: String,
+    /// 已派生的运行目录（D20 隔离覆盖链在 `super::launch` 求值完，这里只消费）。
+    pub game_dir: Option<PathBuf>,
+    /// Java 可执行文件覆盖。
+    pub java: Option<PathBuf>,
+    /// 离线账户名（无账户时生效；有账户时身份由 `auth` 决定）。
+    pub username: Option<String>,
+    /// 已解析好的账户占位（`None` = 退回 `username` 的离线占位）。
+    pub auth: Option<AuthPlaceholders>,
+    /// 最大堆 MB。
+    pub max_memory: Option<u32>,
+}
+
+/// 装配结果。
+#[derive(Debug, Clone)]
+pub struct Plan {
+    /// 实际使用的版本 id。
+    pub version_id: String,
+    /// 装配好的启动请求。
+    pub request: LaunchRequest,
+    /// 非致命告警（缺主类/缺资源索引等）。
+    pub warnings: Vec<String>,
+}
+
+/// 装配一个 [`LaunchRequest`]。
+///
+/// # Errors
+///
+/// 版本 JSON 缺失/非法、继承链断裂（缺父版本/成环）时返回用户错误。
+pub fn prepare(ctx: &Ctx, input: &PlanInput) -> Result<Plan, CliError> {
+    let game = ctx.game();
+    let version_id = input.version_id.clone();
+    let manifest_path = game.version_json(&version_id);
+    let manifest = read_version_json(&manifest_path)?;
+
+    let source = |id: &str| -> Option<VersionJson> {
+        let path = game.version_json(id);
+        read_version_json(&path).ok()
+    };
+    let resolved = game::resolve(&source, &manifest).map_err(|error| {
+        CliError::user("inherit", format!("解析继承链失败：{error}"))
+            .with_hint(format!("检查 {}", manifest_path.display()))
+    })?;
+
+    let environment = Environment::host();
+    let expanded = resolved
+        .arguments
+        .as_ref()
+        .map(|arguments| arguments.expand(&environment))
+        .unwrap_or_default();
+
+    let mut libraries: Vec<LibraryInput> = Vec::new();
+    for library in resolved.libraries.as_deref().unwrap_or_default() {
+        if !library.applies(&environment) || library.native_classifier(&environment).is_some() {
+            continue;
+        }
+        let Ok(coordinate) = library.coordinate() else {
+            continue;
+        };
+        let path = if library.is_local() {
+            game.version_library(&version_id, &coordinate)
+        } else {
+            game.library(&coordinate)
+        };
+        libraries.push(LibraryInput::new(path, library.name.clone()));
+    }
+
+    // natives 分类器构件（≤1.18.2 才有）：收集口径归 core，CLI 只搬运。
+    let natives = unlucky_core::launch::natives::collect(
+        &game,
+        &version_id,
+        resolved.libraries.as_deref().unwrap_or_default(),
+        &environment,
+    );
+
+    let jar_id = resolved.jar.clone().unwrap_or_else(|| version_id.clone());
+    let primary_jar = game.version_jar(&jar_id);
+    // 运行目录：调用方（`ull launch`）已按隔离覆盖链派生；`None` 兜底到游戏根
+    // （库/其它消费者直接构造 `PlanInput` 时保持旧行为）。
+    let game_dir = input
+        .game_dir
+        .clone()
+        .unwrap_or_else(|| ctx.data.game_home.clone());
+    let assets_root = game.assets_dir();
+    let assets_index = resolved
+        .assets
+        .clone()
+        .or_else(|| resolved.asset_index.as_ref().map(|index| index.id.clone()));
+
+    let snapshot = SnapshotInput {
+        version_id: &version_id,
+        version_name: Some(&input.instance_name),
+        version_type: None,
+        game_version: None,
+        main_class: resolved.main_class.as_deref(),
+        jvm_arguments: &expanded.jvm,
+        game_arguments: &expanded.game,
+        legacy_arguments: resolved.minecraft_arguments.as_deref(),
+        libraries: &libraries,
+        natives: &natives,
+        primary_jar,
+        game_dir,
+        assets_index: assets_index.as_deref(),
+        natives_dir: game.natives_dir(&version_id),
+        library_dir: game.libraries_dir(),
+        assets_root: assets_root.clone(),
+        game_assets: assets_root,
+    };
+
+    let options = AdapterOptions {
+        java: super::java::selection(input.java.as_deref()),
+        memory: MemoryOptions {
+            min_mb: None,
+            max_mb: input.max_memory,
+        },
+        auth: input.auth.clone().unwrap_or_else(|| AuthPlaceholders {
+            player_name: input
+                .username
+                .clone()
+                .unwrap_or_else(|| "Player".to_string()),
+            uuid: ProfileId::generate().as_str().replace('-', ""),
+            user_type: "legacy".to_string(),
+            user_properties: "{}".to_string(),
+            ..AuthPlaceholders::default()
+        }),
+        launcher_name: super::meta::LAUNCHER_NAME.to_string(),
+        launcher_version: env!("CARGO_PKG_VERSION").to_string(),
+        language: "zh-CN".to_string(),
+        ..AdapterOptions::strict()
+    };
+
+    let output = adapter::build_request(&snapshot, options);
+    let warnings = output.warnings.iter().map(describe_warning).collect();
+    let mut request = output.request;
+    // 会话索引要用实例身份（adapter 默认拿版本 id/名）。
+    if !input.instance_id.is_empty() {
+        request.instance.id = input.instance_id.clone();
+    }
+    request.instance.name = input.instance_name.clone();
+
+    Ok(Plan {
+        version_id,
+        request,
+        warnings,
+    })
+}
+
+fn read_version_json(path: &std::path::Path) -> Result<VersionJson, CliError> {
+    let text = match std::fs::read_to_string(path) {
+        Ok(text) => text,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+            return Err(CliError::user(
+                "version_missing",
+                format!("版本 JSON 不存在：{}", path.display()),
+            )
+            .with_hint("先准备好版本本体文件（下载装配属 P1 后续 mission）"));
+        }
+        Err(error) => return Err(CliError::io("读版本 JSON", path, &error)),
+    };
+    VersionJson::from_json_str(&text)
+        .map_err(|error| CliError::user("version_parse", format!("{}：{error}", path.display())))
+}
+
+/// 适配层告警 → 人读一行（`AdapterWarning` 没有 Display，这里集中翻译）。
+fn describe_warning(warning: &AdapterWarning) -> String {
+    match warning {
+        AdapterWarning::MissingLibrary { name, path } => {
+            format!("缺少库文件 {name}（{}）", path.display())
+        }
+        AdapterWarning::MissingGameArguments => {
+            "版本 JSON 既没有 arguments.game 也没有 minecraftArguments".to_string()
+        }
+        AdapterWarning::MissingAssetsIndex => {
+            "版本 JSON 没有资源索引 id（${assets_index_name} 为空）".to_string()
+        }
+        AdapterWarning::MissingMainClass => "版本 JSON 没有 mainClass".to_string(),
+        AdapterWarning::MissingNativeJar { name, path } => {
+            format!("缺少 natives 构件 {name}（{}）", path.display())
+        }
+    }
+}
diff --git a/crates/cli/src/context.rs b/crates/cli/src/context.rs
new file mode 100644
index 0000000..1ae4b90
--- /dev/null
+++ b/crates/cli/src/context.rs
@@ -0,0 +1,238 @@
+//! 数据根解析与目录视图。
+//!
+//! 三模式（D6 / `04-data-and-config.md` §1）全部交给 `core::platform::data_dir`：
+//! - `--data-dir <dir>` → custom 模式（`<dir>/.ULL` + `<dir>/.minecraft`）；
+//! - 否则先按便携目录的 `launcher.json` 读 `core.data_mode` / `core.data_custom_root` /
+//!   `core.launcher_home` / `core.game_home`，再交 [`Resolver`] 解析（含 `redirect.json` 跟随）。
+//!
+//! CLI 不自己拼路径：目录形状的真相在 `core::platform::layout`。
+//!
+//! `ull config get/set` 的落点也从这里出：[`Ctx::setting_path_for`] 让决定数据根的
+//! `core.*` 键落在**便携目录那份** `launcher.json`（与解析同源），其余键落解析后的数据根。
+
+use std::path::{Path, PathBuf};
+
+use unlucky_core::game::GameLayout;
+use unlucky_core::platform::data_dir::{DataDirRequest, DataMode, ResolvedData, Resolver};
+use unlucky_core::platform::layout::{
+    LauncherLayout, CONFIG_DIR, LAUNCHER_CONFIG_FILE, LAUNCHER_HOME_DIR,
+};
+use unlucky_core::platform::paths::Platform;
+use unlucky_core::setting::keys::launcher_schema;
+use unlucky_core::setting::store::SettingStore;
+
+use crate::cli::Globals;
+use crate::error::CliError;
+use crate::os;
+
+/// 决定数据根本身的配置键（`request_from_portable_config` 读的就是它们）。
+///
+/// `ull config get/set` 对这几个键必须读写**同一份文件**（便携目录那份），否则会出现
+/// 「`config get core.data_mode` 说 portable、实际按 standard 跑」这种两套真相
+/// （finding 20261030-worker-java2-improve-ull-config-get-set-launcher-json）。
+pub const DATA_ROOT_KEYS: [&str; 4] = [
+    "core.data_mode",
+    "core.data_custom_root",
+    "core.launcher_home",
+    "core.game_home",
+];
+
+/// 该键是否决定数据根。
+#[must_use]
+pub fn is_data_root_key(key: &str) -> bool {
+    DATA_ROOT_KEYS.contains(&key)
+}
+
+/// 便携目录那份 `launcher.json` 的路径（`<exe 目录>/.ULL/config/launcher.json`）。
+#[must_use]
+pub fn portable_config_path(exe_dir: &Path) -> PathBuf {
+    exe_dir
+        .join(LAUNCHER_HOME_DIR)
+        .join(CONFIG_DIR)
+        .join(LAUNCHER_CONFIG_FILE)
+}
+
+/// 一次命令执行的上下文：数据根 + 平台 + 系统摘要。
+#[derive(Debug, Clone)]
+pub struct Ctx {
+    /// 解析后的数据目录（launcher home / game home）。
+    pub data: ResolvedData,
+    /// 宿主平台族。
+    pub platform: Platform,
+    /// 系统信息与支持等级（D19 探测 / D21 Win10+ 单基线）。
+    pub os: unlucky_core::platform::os_info::OsInfo,
+    /// exe 目录（便携目录那份 `launcher.json` 的根；拿不到时为 `None`）。
+    exe_dir: Option<PathBuf>,
+    /// `--data-dir` 是否由命令行强制指定（此时数据根不看 `core.*` 键）。
+    data_dir_forced: bool,
+}
+
+impl Ctx {
+    /// 解析数据根。
+    ///
+    /// # Errors
+    ///
+    /// `--data-dir` 非绝对路径、exe 目录拿不到、`redirect.json` 损坏等返回用户错误。
+    pub fn resolve(globals: &Globals) -> Result<Self, CliError> {
+        let exe_dir = std::env::current_exe()
+            .ok()
+            .and_then(|path| path.parent().map(Path::to_path_buf));
+        Self::resolve_in(globals, exe_dir)
+    }
+
+    /// 指定 exe 目录的解析入口（单测用它把便携目录钉在临时目录里）。
+    ///
+    /// # Errors
+    ///
+    /// 同 [`Self::resolve`]。
+    pub fn resolve_in(globals: &Globals, exe_dir: Option<PathBuf>) -> Result<Self, CliError> {
+        let platform = Platform::current();
+        let data_dir_forced = globals.data_dir.is_some();
+        let request = match &globals.data_dir {
+            Some(dir) => {
+                if !dir.is_absolute() {
+                    return Err(CliError::usage(format!(
+                        "--data-dir 需要绝对路径，收到 `{}`",
+                        dir.display()
+                    )));
+                }
+                DataDirRequest {
+                    mode: DataMode::Custom,
+                    custom_root: Some(dir.clone()),
+                    ..DataDirRequest::default()
+                }
+            }
+            None => request_from_portable_config(exe_dir.clone()),
+        };
+        let resolver = Resolver::new(platform, exe_dir.clone());
+        let data = resolver
+            .resolve_default(&request)
+            .map_err(|error| CliError::user("data_dir", error.to_string()))?;
+        Ok(Self {
+            data,
+            platform,
+            os: os::detect(),
+            exe_dir,
+            data_dir_forced,
+        })
+    }
+
+    /// 启动器数据布局（`.ULL/` 四分区）。
+    #[must_use]
+    pub fn layout(&self) -> LauncherLayout {
+        self.data.layout()
+    }
+
+    /// 游戏目录布局（`.minecraft/`）。
+    #[must_use]
+    pub fn game(&self) -> GameLayout {
+        GameLayout::new(self.data.game_home.clone())
+    }
+
+    /// `launcher.json` 路径。
+    #[must_use]
+    pub fn launcher_config(&self) -> PathBuf {
+        self.layout().launcher_config()
+    }
+
+    /// 便携目录那份 `launcher.json`（数据根解析的唯一输入；拿不到 exe 目录时为 `None`）。
+    #[must_use]
+    pub fn portable_launcher_config(&self) -> Option<PathBuf> {
+        self.exe_dir.as_deref().map(portable_config_path)
+    }
+
+    /// `--data-dir` 是否由命令行强制指定（此时 `core.*` 数据根键本轮不参与解析）。
+    #[must_use]
+    pub const fn data_dir_forced(&self) -> bool {
+        self.data_dir_forced
+    }
+
+    /// 某个配置键的读写落点。
+    ///
+    /// 数据根键（[`DATA_ROOT_KEYS`]）走便携目录那份——和 [`Self::resolve`] 读的是同一份文件，
+    /// 这样 `config get core.data_mode` 展示的就是真正生效的值，`config set` 也真的会影响
+    /// 下次解析；其余键走解析后的数据根（`<data>/.ULL/config/launcher.json`）。
+    #[must_use]
+    pub fn setting_path_for(&self, key: &str) -> PathBuf {
+        if is_data_root_key(key) {
+            if let Some(path) = self.portable_launcher_config() {
+                return path;
+            }
+        }
+        self.launcher_config()
+    }
+
+    /// `profiles.json` 路径。
+    #[must_use]
+    pub fn profiles_config(&self) -> PathBuf {
+        self.layout().profiles_config()
+    }
+
+    /// 会话根（`<data>/agent/sessions`，launch 的事件流与索引都在这下面）。
+    #[must_use]
+    pub fn sessions_root(&self) -> PathBuf {
+        self.layout().agent_sessions()
+    }
+
+    /// 账户数据目录（`data/auth/`：`accounts.json` + `credentials.dat`）。
+    #[must_use]
+    pub fn auth_data(&self) -> PathBuf {
+        self.layout().auth_data()
+    }
+
+    /// 会话索引文件（`<sessions_root>/game/index.jsonl`）。
+    #[must_use]
+    pub fn session_index(&self) -> PathBuf {
+        unlucky_core::launch::session_index::index_path(&self.sessions_root())
+    }
+
+    /// D19/D21：低于基线（Win10+ / macOS 12+ / Linux 达标）时拒绝执行。
+    ///
+    /// # Errors
+    ///
+    /// 系统不支持时返回 `unsupported_os` 用户错误（文案与核心自检同一份）。
+    pub fn ensure_supported(&self) -> Result<(), CliError> {
+        let check = os::check();
+        if check.is_usable() {
+            return Ok(());
+        }
+        Err(CliError::user("unsupported_os", check.message)
+            .with_hint(format!("最低要求：{}", os::BASELINE)))
+    }
+
+    /// 环境级提示（低于基线时的升级指引；一等基线时为空）。
+    #[must_use]
+    pub fn notes(&self) -> Vec<String> {
+        os::notes(&self.os)
+    }
+}
+
+/// 便携目录的 `launcher.json` → 三模式请求。
+///
+/// 只读 `effective`（文件值 → 默认值），坏文件也永不 panic（`SettingStore` 的加载降级）。
+/// 路径由 [`portable_config_path`] 决定，`config get/set` 用的是同一个函数（同源）。
+fn request_from_portable_config(exe_dir: Option<PathBuf>) -> DataDirRequest {
+    let mut request = DataDirRequest::default();
+    let Some(exe_dir) = exe_dir else {
+        return request;
+    };
+    let path = portable_config_path(&exe_dir);
+    if !path.is_file() {
+        return request;
+    }
+    let store = SettingStore::load(&path, launcher_schema());
+    let text = |key: &str| store.doc().effective_str(key).map(str::to_string);
+    if let Some(mode) = text("core.data_mode").as_deref().and_then(DataMode::parse) {
+        request.mode = mode;
+    }
+    if let Some(root) = text("core.data_custom_root") {
+        request.custom_root = Some(PathBuf::from(root));
+    }
+    if let Some(home) = text("core.launcher_home") {
+        request.launcher_home = Some(PathBuf::from(home));
+    }
+    if let Some(home) = text("core.game_home") {
+        request.game_home = Some(PathBuf::from(home));
+    }
+    request
+}
diff --git a/crates/cli/src/error.rs b/crates/cli/src/error.rs
new file mode 100644
index 0000000..9416e32
--- /dev/null
+++ b/crates/cli/src/error.rs
@@ -0,0 +1,165 @@
+//! 错误形状与退出码。
+//!
+//! 约定（10-cli-design.md §3）：**0 成功 / 1 用户错误 / 2 内部错误**。
+//! 用户错误 = 用法错、目标不存在、环境不支持、依赖模块未接线；
+//! 内部错误 = 不该发生的事（序列化失配等），脚本见到 2 应该当 bug 报。
+
+use std::fmt;
+
+use serde_json::{json, Value};
+
+/// 退出码：成功。
+pub const EXIT_OK: i32 = 0;
+/// 退出码：用户错误。
+pub const EXIT_USER: i32 = 1;
+/// 退出码：内部错误。
+pub const EXIT_INTERNAL: i32 = 2;
+
+/// 错误大类（决定退出码）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ErrorKind {
+    /// 用户侧问题：改参数/改环境可解决。
+    User,
+    /// 内部问题：不该发生，应报 bug。
+    Internal,
+}
+
+impl ErrorKind {
+    /// 稳定名（`--json` 输出用）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::User => "user",
+            Self::Internal => "internal",
+        }
+    }
+
+    /// 对应的进程退出码。
+    #[must_use]
+    pub const fn exit_code(self) -> i32 {
+        match self {
+            Self::User => EXIT_USER,
+            Self::Internal => EXIT_INTERNAL,
+        }
+    }
+}
+
+/// 一条 CLI 错误。
+///
+/// `code` 是给脚本的稳定机读标识（`usage` / `not_found` / `unsupported_os` …），
+/// `message` 是给人看的中文说明，`hint` 是「下一步该做什么」。
+#[derive(Debug, Clone)]
+pub struct CliError {
+    kind: ErrorKind,
+    code: &'static str,
+    message: String,
+    hint: Option<String>,
+}
+
+/// 把模板里的程序名占位符渲染掉（M82 r3）。
+///
+/// 渲染放在**构造时**，而不是打印时：错误有两条出口（人类可读 stderr、`--json` 信封），
+/// 只在打印处渲染会漏掉 JSON 那条（r2 就是这么漏的，`%prog%` 直接出现在了 JSON 里）。
+fn render(text: impl Into<String>) -> String {
+    crate::cli::program::fill(&text.into())
+}
+
+impl CliError {
+    /// 用法错误（参数不对）。
+    #[must_use]
+    pub fn usage(message: impl Into<String>) -> Self {
+        Self {
+            kind: ErrorKind::User,
+            code: "usage",
+            message: render(message),
+            hint: None,
+        }
+    }
+
+    /// 用户错误，带稳定 code。
+    #[must_use]
+    pub fn user(code: &'static str, message: impl Into<String>) -> Self {
+        Self {
+            kind: ErrorKind::User,
+            code,
+            message: render(message),
+            hint: None,
+        }
+    }
+
+    /// 内部错误，带稳定 code。
+    #[must_use]
+    pub fn internal(code: &'static str, message: impl Into<String>) -> Self {
+        Self {
+            kind: ErrorKind::Internal,
+            code,
+            message: render(message),
+            hint: None,
+        }
+    }
+
+    /// IO 失败（读配置/读写会话文件）：按用户错误处理，路径进消息。
+    #[must_use]
+    pub fn io(op: &str, path: &std::path::Path, error: &std::io::Error) -> Self {
+        Self::user("io", format!("{op}失败：{}（{error}）", path.display()))
+    }
+
+    /// 补一句提示。
+    #[must_use]
+    pub fn with_hint(mut self, hint: impl Into<String>) -> Self {
+        self.hint = Some(render(hint));
+        self
+    }
+
+    /// 错误大类。
+    #[must_use]
+    pub const fn kind(&self) -> ErrorKind {
+        self.kind
+    }
+
+    /// 稳定错误码。
+    #[must_use]
+    pub const fn code(&self) -> &'static str {
+        self.code
+    }
+
+    /// 人类可读说明。
+    #[must_use]
+    pub fn message(&self) -> &str {
+        &self.message
+    }
+
+    /// 下一步提示。
+    #[must_use]
+    pub fn hint(&self) -> Option<&str> {
+        self.hint.as_deref()
+    }
+
+    /// 进程退出码。
+    #[must_use]
+    pub const fn exit_code(&self) -> i32 {
+        self.kind.exit_code()
+    }
+
+    /// `--json` 里的错误对象。
+    #[must_use]
+    pub fn to_json(&self) -> Value {
+        let mut error = json!({
+            "code": self.code,
+            "kind": self.kind.as_str(),
+            "message": self.message,
+        });
+        if let Some(hint) = &self.hint {
+            error["hint"] = Value::String(hint.clone());
+        }
+        json!({ "ok": false, "error": error })
+    }
+}
+
+impl fmt::Display for CliError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(formatter, "{}", self.message)
+    }
+}
+
+impl std::error::Error for CliError {}
diff --git a/crates/cli/src/lib.rs b/crates/cli/src/lib.rs
new file mode 100644
index 0000000..cdd8dcf
--- /dev/null
+++ b/crates/cli/src/lib.rs
@@ -0,0 +1,27 @@
+//! Unlucky-Launcher 命令行（`unlucky_cli`）：`ull` 二进制的可测试内核。
+//!
+//! 设计定稿：`DevDocs/PlanDoc/10-cli-design.md`（D18）—— core 是零 UI 纯库，
+//! CLI 只是与 Slint GUI 平级的第二个消费者，因此**本 crate 不依赖任何 UI 框架**。
+//!
+//! 分层：
+//! - [`cli`]：手写参数解析（不引 clap）+ 命令模型 + 帮助文案；
+//! - [`commands`]：每个子命令一个函数，输入 [`context::Ctx`]，输出 [`output::Report`]；
+//! - [`context`]：数据根解析（三模式 / `--data-dir` 覆盖）与目录视图；
+//! - [`os`]：系统摘要与 D19/D21 支持级别（事实来自 core::platform::os_info，这里只做呈现）；
+//! - [`output`]：人类可读 + `--json` 双格式输出；
+//! - [`error`]：错误形状与退出码（0 成功 / 1 用户错误 / 2 内部错误）。
+//!
+//! 可测试性：入口是 [`run`]，参数是 `&[String]`，输出写进两个 `&mut dyn Write`，
+//! 返回值就是进程退出码——集成测试因此不需要真的起子进程也能覆盖三条通道。
+
+#![forbid(unsafe_code)]
+
+pub mod cli;
+pub mod commands;
+pub mod context;
+pub mod error;
+pub mod os;
+pub mod output;
+pub mod runner;
+
+pub use runner::run;
diff --git a/crates/cli/src/main.rs b/crates/cli/src/main.rs
new file mode 100644
index 0000000..28afe48
--- /dev/null
+++ b/crates/cli/src/main.rs
@@ -0,0 +1,9 @@
+//! `ull` 二进制入口：把真实 stdio 交给 [`unlucky_cli::run`]，退出码照传。
+
+fn main() {
+    let args: Vec<String> = std::env::args().skip(1).collect();
+    let mut stdout = std::io::stdout();
+    let mut stderr = std::io::stderr();
+    let code = unlucky_cli::run(&args, &mut stdout, &mut stderr);
+    std::process::exit(code);
+}
diff --git a/crates/cli/src/os.rs b/crates/cli/src/os.rs
new file mode 100644
index 0000000..0957b67
--- /dev/null
+++ b/crates/cli/src/os.rs
@@ -0,0 +1,78 @@
+//! 系统摘要与启动自检的 **CLI 呈现层**（D19 探测 + D21 Win10+ 单基线）。
+//!
+//! 事实采集与等级判定全在 `unlucky_core::platform::os_info`（M20）：
+//! - [`os_info::detect`] 真探一次（会起子进程，别在热路径反复调用）；
+//! - [`os_info::current`] 进程内缓存（CLI 每次执行只真探一次）；
+//! - [`os_info::check`] 启动自检（等级 + 双语文案 + 系统信息）。
+//!
+//! 本模块只做 CLI 关心的事：一行摘要、`--json` 对象、拒绝运行时的文案。
+//! 支持级别只有两档（D21 用户拍板「直接 win10 起步」）：[`SupportLevel::One`] 与
+//! [`SupportLevel::Unsupported`]——Win8.1/8/7 不承诺 GUI 也不承诺 CLI，
+//! 识别出旧版本正是为了明确报「不支持」。
+
+use serde_json::{json, Value};
+use unlucky_core::platform::os_info::{self, OsInfo, SupportLevel};
+
+/// 取进程内缓存的系统信息（一次进程只真探一次）。
+#[must_use]
+pub fn detect() -> OsInfo {
+    os_info::current().clone()
+}
+
+/// 启动自检（等级 + 双语文案 + 系统信息），供拒绝运行时直接打印。
+#[must_use]
+pub fn check() -> os_info::SupportCheck {
+    os_info::check()
+}
+
+/// 一行摘要（`ull --version` 附带）。
+#[must_use]
+pub fn summary_line(info: &OsInfo) -> String {
+    let version = if info.version_string.is_empty() {
+        "版本未知"
+    } else {
+        info.version_string.as_str()
+    };
+    format!(
+        "{} · {}（{}）· {}",
+        info.product,
+        version,
+        info.arch,
+        support_label(info.support_level)
+    )
+}
+
+/// `--json` 里的系统对象。
+#[must_use]
+pub fn to_json(info: &OsInfo) -> Value {
+    json!({
+        "family": info.family.manifest_name(),
+        "product": info.product,
+        "version": if info.version_string.is_empty() { None } else { Some(&info.version_string) },
+        "major_minor": info.major_minor.map(|(major, minor)| format!("{major}.{minor}")),
+        "build": info.build,
+        "arch": info.arch,
+        "session": info.session.as_str(),
+        "support": info.support_level.as_str(),
+        "baseline": BASELINE,
+    })
+}
+
+/// 支持基线的一句话（`--json` 与帮助文案共用）。
+pub const BASELINE: &str = "Windows 10+ / macOS 12+ / Linux（内核 ≥ 3.2，glibc ≥ 2.17）";
+
+/// 环境级提示：仅在低于基线时非空（一等基线不打岔）。
+#[must_use]
+pub fn notes(info: &OsInfo) -> Vec<String> {
+    match info.support_level {
+        SupportLevel::One => Vec::new(),
+        SupportLevel::Unsupported => info.describe().zh.lines().map(str::to_string).collect(),
+    }
+}
+
+fn support_label(level: SupportLevel) -> &'static str {
+    match level {
+        SupportLevel::One => "满足最低要求",
+        SupportLevel::Unsupported => "不支持（低于最低要求）",
+    }
+}
diff --git a/crates/cli/src/output.rs b/crates/cli/src/output.rs
new file mode 100644
index 0000000..b34869c
--- /dev/null
+++ b/crates/cli/src/output.rs
@@ -0,0 +1,215 @@
+//! 双格式输出：人类可读行 + `--json` 机器可读载荷。
+//!
+//! 一个命令只产出 [`Report`]（`data` 给脚本，`human` 给人）；怎么打印由 [`print_report`]
+//! 一处决定，命令里不出现 `println!`——这样集成测试能直接断言输出形状，
+//! 也能保证 `--json` 覆盖到每个命令（10-cli-design.md §3 全局参数）。
+
+use std::io::Write;
+
+use serde_json::{json, Value};
+
+use crate::error::CliError;
+
+/// 一个命令的结果。
+#[derive(Debug, Clone)]
+pub struct Report {
+    /// `--json` 模式下的 `data` 载荷。
+    pub data: Value,
+    /// 人类可读输出（一行一条）。
+    pub human: Vec<String>,
+}
+
+impl Report {
+    /// 构造（人类可读行在这里就把程序名占位符渲染掉，见 [`crate::cli::program::PLACEHOLDER`]）。
+    #[must_use]
+    pub fn new(data: Value, human: Vec<String>) -> Self {
+        Self {
+            data,
+            human: human.into_iter().map(|line| fill_program(&line)).collect(),
+        }
+    }
+}
+
+/// 命令结果 + 环境提示（D19/D21 低于基线时的升级指引之类，不混进 `data`）。
+#[derive(Debug, Clone)]
+pub struct Outcome {
+    /// 命令结果。
+    pub report: Report,
+    /// 环境级提示（人类模式进 stderr，JSON 模式进信封的 `warnings`）。
+    pub warnings: Vec<String>,
+    /// 命令自定义的退出码；`None` = 0（绝大多数命令）。
+    ///
+    /// 只有"结果多态且脚本要分流"的命令才用得上：`ull pack import` 的三态是
+    /// `0` 成功 / `3` 部分成功 / `1` 失败，光靠 0/1 分不出来。加这个字段而不是让命令
+    /// 自己 `std::process::exit`，是为了让**输出照常刷新**（绕过 runner 的输出刷新会把
+    /// "输出没刷完就退出"这种 bug 装进 CLI）。
+    pub exit_code: Option<i32>,
+}
+
+impl Outcome {
+    /// 无提示的结果。
+    #[must_use]
+    pub fn new(report: Report) -> Self {
+        Self {
+            report,
+            warnings: Vec::new(),
+            exit_code: None,
+        }
+    }
+
+    /// 带上环境提示（同样在构造时渲染占位符，JSON 与人类可读两条出口才不会分叉）。
+    #[must_use]
+    pub fn with_warnings(report: Report, warnings: Vec<String>) -> Self {
+        Self {
+            report,
+            warnings: warnings
+                .into_iter()
+                .map(|line| fill_program(&line))
+                .collect(),
+            exit_code: None,
+        }
+    }
+
+    /// 指定进程退出码（不指定 = 0）。
+    #[must_use]
+    pub fn with_exit_code(mut self, code: i32) -> Self {
+        self.exit_code = Some(code);
+        self
+    }
+}
+
+/// 打印成功结果。
+///
+/// # Errors
+///
+/// 写 stdout/stderr 失败时返回 IO 错误（管道被关掉等）。
+pub fn print_report(
+    outcome: &Outcome,
+    json: bool,
+    quiet: bool,
+    out: &mut dyn Write,
+    err: &mut dyn Write,
+) -> std::io::Result<()> {
+    if json {
+        // 信封固定三个键，脚本按 `ok` 分流后直接吃 `data`。
+        let envelope = json!({
+            "ok": true,
+            "data": outcome.report.data,
+            "warnings": outcome.warnings,
+        });
+        writeln!(out, "{}", serde_json::to_string_pretty(&envelope)?)?;
+        return Ok(());
+    }
+    if !quiet {
+        for line in &outcome.report.human {
+            writeln!(out, "{line}")?;
+        }
+    }
+    for warning in &outcome.warnings {
+        writeln!(err, "提示: {warning}")?;
+    }
+    Ok(())
+}
+
+/// 打印错误（人类模式进 stderr，JSON 模式进 stdout 的错误信封）。
+///
+/// # Errors
+///
+/// 写 stdout/stderr 失败时返回 IO 错误。
+pub fn print_error(
+    error: &CliError,
+    json: bool,
+    out: &mut dyn Write,
+    err: &mut dyn Write,
+) -> std::io::Result<()> {
+    if json {
+        writeln!(out, "{}", serde_json::to_string_pretty(&error.to_json())?)?;
+        return Ok(());
+    }
+    writeln!(err, "错误: {}", error.message())?;
+    if let Some(hint) = error.hint() {
+        writeln!(err, "提示: {hint}")?;
+    }
+    Ok(())
+}
+
+/// 渲染文案里的程序名占位符（M82）。
+///
+/// **只替换占位符**，不对整条文本做词替换：消息里插值进来的账户名 / 路径 / 回显的子命令
+/// 一个字节都不动（r1 曾把账户名 `ull` 改成程序名、把 `D:/tmp/ull/.ULL` 改成
+/// `D:/tmp/unlucky-launcher/.ULL`）。
+fn fill_program(text: &str) -> String {
+    crate::cli::program::fill(text)
+}
+
+/// 长任务的实时进度行（**只进 stderr**，不参与 [`Report`]）。
+///
+/// 命令的正经输出仍然全部走 [`Report`]（stdout、可断言的形状）；下载/安装这类分钟级任务
+/// 需要无缓冲的实时反馈，才单独开这条通道。行内不含 ANSI，`--no-color` 无需处理。
+///
+/// `--json` / `--quiet` 的抑制由**调用方**决定（`InstallArgs::progress` 已按全局选项算好），
+/// 这样这条通道不需要知道全局选项长什么样。
+///
+/// 写不出去（管道早闭）就静默放弃：进度永远不该让命令失败。
+pub fn progress_line(text: &str) {
+    let mut stderr = std::io::stderr();
+    let _ = writeln!(stderr, "{text}");
+    let _ = stderr.flush();
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{print_report, progress_line, Outcome, Report};
+    use crate::cli::program::{self, PLACEHOLDER};
+    use crate::error::CliError;
+    use serde_json::json;
+
+    #[test]
+    fn progress_line_never_panics() {
+        // 只验证"写不出去也不抛"（真实 stderr 在测试里通常可写）。
+        progress_line("测试进度 1/2");
+        progress_line("");
+    }
+
+    #[test]
+    fn json_error_envelope_never_leaks_the_placeholder() {
+        // r2 的回归：JSON 分支直接序列化未渲染的 message/hint，`%prog%` 原样漏给脚本。
+        let error = CliError::usage(format!("{PLACEHOLDER} 需要一个值"))
+            .with_hint(format!("{PLACEHOLDER} --help 查看命令列表"));
+        let envelope = serde_json::to_string(&error.to_json()).expect("序列化");
+        assert!(!envelope.contains(PLACEHOLDER), "{envelope}");
+        assert!(envelope.contains(&program::name()), "{envelope}");
+    }
+
+    #[test]
+    fn json_warnings_never_leak_the_placeholder() {
+        // warnings 是第二条 JSON 出口（以前连人类可读那条都没走到）。
+        let report = Report::new(
+            json!({ "ok": true }),
+            vec![format!("{PLACEHOLDER} instances list 看看现有实例")],
+        );
+        let outcome =
+            Outcome::with_warnings(report, vec![format!("用 {PLACEHOLDER} install 装版本")]);
+        let mut out: Vec<u8> = Vec::new();
+        let mut err: Vec<u8> = Vec::new();
+        print_report(&outcome, true, false, &mut out, &mut err).expect("写 JSON");
+        let text = String::from_utf8_lossy(&out).into_owned();
+        assert!(!text.contains(PLACEHOLDER), "{text}");
+        assert!(text.contains(&program::name()), "{text}");
+    }
+
+    #[test]
+    fn human_lines_render_the_placeholder_too() {
+        let report = Report::new(
+            json!({}),
+            vec![format!("用 `{PLACEHOLDER} install` 登记实例")],
+        );
+        assert_eq!(
+            report.human[0],
+            format!("用 `{} install` 登记实例", program::name())
+        );
+        // 用户数据不受影响：账户名恰好叫 ull 的那种
+        let report = Report::new(json!({}), vec!["找不到账户 `ull`".to_string()]);
+        assert_eq!(report.human[0], "找不到账户 `ull`");
+    }
+}
diff --git a/crates/cli/src/runner.rs b/crates/cli/src/runner.rs
new file mode 100644
index 0000000..4bf4d0e
--- /dev/null
+++ b/crates/cli/src/runner.rs
@@ -0,0 +1,56 @@
+//! 进程入口的可测试形态：解析 → 分发 → 打印 → 退出码。
+//!
+//! `main` 只做两件事：把真实 stdio 传进来、把返回码交给进程。
+
+use std::io::Write;
+
+use crate::cli;
+use crate::commands;
+use crate::error::EXIT_OK;
+use crate::output;
+
+/// 跑一条命令行，返回进程退出码（0 / 1 / 2）。
+///
+/// `args` 不含 argv[0]。`--json` 与 `--quiet` 在解析失败时也要生效，
+/// 因此这里先扫一遍原始参数，而不是依赖解析结果。
+pub fn run(args: &[String], out: &mut dyn Write, err: &mut dyn Write) -> i32 {
+    let json = args.iter().any(|arg| arg == "--json");
+    let quiet = args.iter().any(|arg| arg == "--quiet" || arg == "-q");
+
+    let invocation = match cli::parse(args) {
+        Ok(invocation) => invocation,
+        Err(error) => {
+            let _ = output::print_error(&error, json, out, err);
+            return error.exit_code();
+        }
+    };
+
+    // `ull agent serve` 提前分流：stdio 形态下 stdout 是 JSON-RPC 流，
+    // 任何一行额外输出（包括返回后的 Report）都会让客户端解析失败。
+    if let cli::Command::AgentServe(serve_args) = &invocation.command {
+        return match crate::commands::agent::run_serve_with(&invocation.globals, serve_args, err) {
+            Ok(code) => code,
+            Err(error) => {
+                let _ = output::print_error(&error, json, out, err);
+                error.exit_code()
+            }
+        };
+    }
+
+    match commands::run(&invocation) {
+        Ok(outcome) => {
+            if let Err(write_err) = output::print_report(&outcome, json, quiet, out, err) {
+                // 输出写不出去（管道早闭）不再折腾，直接按内部错误退出。
+                let _ = writeln!(err, "错误: 写输出失败：{write_err}");
+                return crate::error::EXIT_INTERNAL;
+            }
+            // 命令可以自己指定退出码（`ull pack import` 的三态：0 / 3 / 1）；
+            // 没指定就是 0——其它命令的行为不变。
+            outcome.exit_code.unwrap_or(EXIT_OK)
+        }
+        Err(error) => {
+            let _ = output::print_error(&error, json, out, err);
+            error.exit_code()
+        }
+    }
+}
diff --git a/crates/cli/tests/accounts_test.rs b/crates/cli/tests/accounts_test.rs
new file mode 100644
index 0000000..023b485
--- /dev/null
+++ b/crates/cli/tests/accounts_test.rs
@@ -0,0 +1,293 @@
+//! `ull accounts` 与 `ull launch --account` 的端到端断言。
+//!
+//! 职责：证明「账户能建/能删/能选」，并且**凭据红线守住了**——
+//! stdout（含 `--json`）、`launch --dry-run` 的 argv 与身份块里都不出现 token 明文。
+
+#[path = "support/mod.rs"]
+mod support;
+
+use std::path::{Path, PathBuf};
+
+use support::{parse_json, run_cli, TempDir};
+use unlucky_core::auth::offline::offline_uuid;
+
+const VERSION: &str = "1.20.1";
+
+/// 建一个带「版本本体 + 一个实例」的数据根。
+fn data_root(tag: &str) -> TempDir {
+    let dir = TempDir::new(tag);
+    support::write_version(dir.path(), VERSION);
+    support::write_profiles(dir.path(), &[("生存服", VERSION)]);
+    dir
+}
+
+/// 覆盖版本 JSON：把 `${auth_access_token}` / `${auth_uuid}` 塞进命令行，
+/// 这样「脱敏」才是被真的跑到，而不是「压根没有 token 所以没有明文」。
+fn write_version_with_auth(root: &Path) {
+    let dir = root.join(".minecraft").join("versions").join(VERSION);
+    std::fs::create_dir_all(&dir).expect("建版本目录");
+    let version = serde_json::json!({
+        "id": VERSION,
+        "type": "release",
+        "mainClass": "net.minecraft.client.main.Main",
+        "assets": "5",
+        "assetIndex": { "id": "5" },
+        "arguments": {
+            "game": [
+                "--username", "${auth_player_name}",
+                "--uuid", "${auth_uuid}",
+                "--accessToken", "${auth_access_token}",
+                "--userType", "${auth_user_type}",
+                "--version", "${version_name}"
+            ],
+            "jvm": ["-Djava.library.path=${natives_directory}", "-cp", "${classpath}"]
+        },
+        "libraries": [],
+        "downloads": { "client": { "size": 4, "url": "http://example.invalid/client.jar" } }
+    });
+    std::fs::write(
+        dir.join(format!("{VERSION}.json")),
+        serde_json::to_vec_pretty(&version).expect("序列化版本 JSON"),
+    )
+    .expect("写版本 JSON");
+}
+
+fn auth_dir(root: &Path) -> PathBuf {
+    root.join(".ULL").join("data").join("auth")
+}
+
+/// 拼一条 `--json --data-dir <root> ...` 命令。
+fn cli(dir: &TempDir, tail: &[&str]) -> Vec<String> {
+    let mut args = vec!["--json".to_string(), "--data-dir".to_string(), dir.arg()];
+    args.extend(tail.iter().map(|item| (*item).to_string()));
+    args
+}
+
+/// 拼一条 `launch 生存服 --dry-run ...` 命令。
+fn launch(dir: &TempDir, extra: &[&str]) -> Vec<String> {
+    let mut tail = vec!["launch", "生存服", "--dry-run"];
+    tail.extend_from_slice(extra);
+    cli(dir, &tail)
+}
+
+/// 跑一条命令并断言退出码。
+fn run(args: &[String], expected: i32) -> (String, String) {
+    let refs: Vec<&str> = args.iter().map(String::as_str).collect();
+    let (code, out, err) = run_cli(&refs);
+    assert_eq!(code, expected, "args={refs:?}\nstdout={out}\nstderr={err}");
+    (out, err)
+}
+
+#[test]
+fn accounts_list_is_empty_at_first() {
+    let dir = data_root("accounts-empty");
+    let (out, _) = run(&cli(&dir, &["accounts", "list"]), 0);
+    let envelope = parse_json(&out);
+    assert_eq!(envelope["data"]["count"], 0);
+    assert_eq!(
+        envelope["data"]["accounts"].as_array().map(Vec::len),
+        Some(0)
+    );
+    assert!(!auth_dir(dir.path()).join("accounts.json").exists());
+}
+
+#[test]
+fn add_offline_writes_both_files_and_reports_hmcl_uuid() {
+    let dir = data_root("accounts-add");
+    let (out, _) = run(&cli(&dir, &["accounts", "add", "offline", "小明"]), 0);
+    let envelope = parse_json(&out);
+    let account = &envelope["data"]["account"];
+    assert_eq!(account["name"], "小明");
+    assert_eq!(account["kind"], "offline");
+    assert_eq!(account["profile_id"], offline_uuid("小明"));
+
+    let accounts_file = auth_dir(dir.path()).join("accounts.json");
+    let credentials_file = auth_dir(dir.path()).join("credentials.dat");
+    assert!(accounts_file.is_file(), "元数据文件必须落盘");
+    assert!(
+        credentials_file.is_file(),
+        "凭据文件必须落盘（哪怕离线轨是空的）"
+    );
+
+    // list 里能看到，且输出里没有任何凭据字段。
+    let (list_out, _) = run(&cli(&dir, &["accounts", "list"]), 0);
+    let list = parse_json(&list_out);
+    assert_eq!(list["data"]["count"], 1);
+    assert_eq!(list["data"]["accounts"][0]["name"], "小明");
+    for forbidden in ["access_token", "refresh_token", "client_token", "password"] {
+        assert!(
+            !list_out.contains(forbidden),
+            "accounts list 不该出现 {forbidden}"
+        );
+    }
+}
+
+#[test]
+fn duplicate_offline_account_is_rejected() {
+    let dir = data_root("accounts-dup");
+    run(&cli(&dir, &["accounts", "add", "offline", "Steve"]), 0);
+    let (out, _) = run(&cli(&dir, &["accounts", "add", "offline", "steve"]), 1);
+    assert_eq!(parse_json(&out)["error"]["code"], "conflict");
+}
+
+#[test]
+fn add_offline_requires_a_valid_name() {
+    let dir = data_root("accounts-badname");
+    let (out, _) = run(&cli(&dir, &["accounts", "add", "offline"]), 1);
+    assert_eq!(parse_json(&out)["error"]["code"], "usage");
+
+    let (out, _) = run(
+        &cli(&dir, &["accounts", "add", "offline", "0123456789abcdefg"]),
+        1,
+    );
+    assert_eq!(parse_json(&out)["error"]["code"], "malformed");
+}
+
+#[test]
+fn remove_deletes_account_and_reports_missing() {
+    let dir = data_root("accounts-remove");
+    run(&cli(&dir, &["accounts", "add", "offline", "Steve"]), 0);
+    let (out, _) = run(&cli(&dir, &["accounts", "remove", "Steve"]), 0);
+    assert_eq!(parse_json(&out)["data"]["removed"]["name"], "Steve");
+
+    let (out, _) = run(&cli(&dir, &["accounts", "list"]), 0);
+    assert_eq!(parse_json(&out)["data"]["count"], 0);
+
+    let (out, _) = run(&cli(&dir, &["accounts", "remove", "Steve"]), 1);
+    assert_eq!(parse_json(&out)["error"]["code"], "not_found");
+}
+
+#[test]
+fn add_msa_without_client_id_is_explained() {
+    // 没配 ULL_MSA_CLIENT_ID 时不该去联网，而是明确告知要配什么。
+    let saved = std::env::var("ULL_MSA_CLIENT_ID").ok();
+    std::env::remove_var("ULL_MSA_CLIENT_ID");
+    let dir = data_root("accounts-msa");
+    let (out, _) = run(&cli(&dir, &["accounts", "add", "msa"]), 1);
+    if let Some(value) = saved {
+        std::env::set_var("ULL_MSA_CLIENT_ID", value);
+    }
+    let envelope = parse_json(&out);
+    assert_eq!(envelope["error"]["code"], "unsupported");
+    assert!(envelope["error"]["hint"]
+        .as_str()
+        .unwrap_or_default()
+        .contains("ULL_MSA_CLIENT_ID"));
+}
+
+#[test]
+fn launch_dry_run_uses_the_only_account() {
+    let dir = data_root("launch-account");
+    write_version_with_auth(dir.path());
+    run(&cli(&dir, &["accounts", "add", "offline", "Steve"]), 0);
+    let (out, _) = run(&launch(&dir, &[]), 0);
+    let data = &parse_json(&out)["data"];
+    let account = &data["account"];
+    assert_eq!(account["name"], "Steve");
+    assert_eq!(account["kind"], "offline");
+    assert_eq!(account["profile_id"], offline_uuid("Steve"));
+    assert_eq!(account["registered"], true);
+
+    // argv 里玩家名与 UUID 都对上了，token 位置是脱敏占位。
+    let argv: Vec<String> = data["argv"]
+        .as_array()
+        .expect("argv")
+        .iter()
+        .map(|item| item.as_str().unwrap_or_default().to_string())
+        .collect();
+    let username_at = argv
+        .iter()
+        .position(|arg| arg == "--username")
+        .expect("有 --username");
+    assert_eq!(argv[username_at + 1], "Steve");
+    // launch 的脱敏器把 uuid 也当敏感值处理（M18 定案：dry-run 输出是「脱敏 uuid」），
+    // 真实 uuid 在下面的身份块里以可公开元数据的形式给出。
+    let uuid_at = argv
+        .iter()
+        .position(|arg| arg == "--uuid")
+        .expect("有 --uuid");
+    assert_eq!(argv[uuid_at + 1], "<redacted:token>");
+    // 真凭据位置：离线占位 token 是随机 32 hex，输出里必须只剩脱敏占位。
+    let token_at = argv
+        .iter()
+        .position(|arg| arg == "--accessToken")
+        .expect("有 --accessToken");
+    assert_eq!(argv[token_at + 1], "<redacted:token>");
+    assert!(out.contains("<redacted:token>"));
+    // 命令行与展示行里不该有任何 32 位十六进制串（= 没漏出 accessToken）。
+    let display = data["display"].as_str().unwrap_or_default();
+    assert!(!has_hex32(&argv.join(" ")), "argv 漏了 token：{argv:?}");
+    assert!(!has_hex32(display), "display 漏了 token：{display}");
+    assert!(
+        !out.contains("access_token"),
+        "输出不该出现 access_token 字段"
+    );
+}
+
+/// 输出里是否有 32 位十六进制串（token 形状）。
+fn has_hex32(text: &str) -> bool {
+    text.split(|ch: char| !ch.is_ascii_hexdigit())
+        .any(|run| run.len() == 32)
+}
+
+#[test]
+fn multiple_accounts_require_explicit_choice() {
+    let dir = data_root("launch-multi");
+    run(&cli(&dir, &["accounts", "add", "offline", "Steve"]), 0);
+    run(&cli(&dir, &["accounts", "add", "offline", "Alex"]), 0);
+    let (out, _) = run(&launch(&dir, &[]), 1);
+    let envelope = parse_json(&out);
+    assert_eq!(envelope["error"]["code"], "account_ambiguous");
+    assert!(
+        envelope["error"]["hint"]
+            .as_str()
+            .unwrap_or_default()
+            .contains("Steve"),
+        "hint 要列候选"
+    );
+
+    // 指定名字就能选出来（大小写不敏感）。
+    let (out, _) = run(&launch(&dir, &["--account", "alex"]), 0);
+    let data = &parse_json(&out)["data"];
+    assert_eq!(data["account"]["name"], "Alex");
+    assert_eq!(data["account"]["profile_id"], offline_uuid("Alex"));
+}
+
+#[test]
+fn unknown_account_and_username_conflict_are_usage_errors() {
+    let dir = data_root("launch-unknown");
+    run(&cli(&dir, &["accounts", "add", "offline", "Steve"]), 0);
+    let (out, _) = run(&launch(&dir, &["--account", "Nobody"]), 1);
+    assert_eq!(parse_json(&out)["error"]["code"], "not_found");
+
+    let (out, _) = run(&launch(&dir, &["--username", "Alex"]), 1);
+    assert_eq!(parse_json(&out)["error"]["code"], "usage");
+}
+
+#[test]
+fn launch_without_accounts_keeps_the_offline_placeholder() {
+    let dir = data_root("launch-placeholder");
+    let (out, _) = run(&launch(&dir, &["--username", "Node"]), 0);
+    let data = &parse_json(&out)["data"];
+    assert_eq!(data["account"]["registered"], false);
+    assert_eq!(data["account"]["kind"], "offline-placeholder");
+    assert_eq!(data["account"]["name"], "Node");
+    let argv: Vec<&str> = data["argv"]
+        .as_array()
+        .expect("argv")
+        .iter()
+        .map(|item| item.as_str().unwrap_or_default())
+        .collect();
+    let at = argv
+        .iter()
+        .position(|arg| *arg == "--username")
+        .expect("--username");
+    assert_eq!(argv[at + 1], "Node");
+}
+
+#[test]
+fn accounts_help_topic_exists() {
+    let (out, _) = run(&["help".to_string(), "accounts".to_string()], 0);
+    assert!(out.contains("credentials.dat"), "{out}");
+    assert!(out.contains("accounts add offline"), "{out}");
+}
diff --git a/crates/cli/tests/agent_mcp_stdio_test.rs b/crates/cli/tests/agent_mcp_stdio_test.rs
new file mode 100644
index 0000000..2600454
--- /dev/null
+++ b/crates/cli/tests/agent_mcp_stdio_test.rs
@@ -0,0 +1,185 @@
+//! 真机验收：起 `ull agent serve --stdio`，用裸 JSON-RPC 走一遍握手 → 列工具 → 调用。
+//!
+//! 这是 M39 任务 5 的自动化形态：**不引任何 MCP 客户端库**，直接按协议喂行给子进程。
+//! stdio 形态是 llama.cpp 内置 MCP client 的入口，它的 stdout 必须是纯 JSON-RPC——
+//! 本测试顺带守住「stdout 里没有多余输出」这条最容易破的约束。
+
+use std::io::{BufRead, BufReader, Write};
+use std::path::{Path, PathBuf};
+use std::process::{Command, Stdio};
+
+use serde_json::{json, Value};
+
+fn data_dir(tag: &str) -> PathBuf {
+    let dir = std::env::temp_dir().join(format!("ull-agent-stdio-{tag}-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).expect("建临时数据根");
+    dir
+}
+
+struct Session {
+    child: std::process::Child,
+    stdin: std::process::ChildStdin,
+    stdout: std::io::Lines<BufReader<std::process::ChildStdout>>,
+}
+
+impl Session {
+    fn start(dir: &Path) -> Self {
+        let mut child = Command::new(env!("CARGO_BIN_EXE_ull"))
+            .args([
+                "agent",
+                "serve",
+                "--stdio",
+                "--allow-write",
+                "--data-dir",
+                &dir.display().to_string(),
+            ])
+            .stdin(Stdio::piped())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::null())
+            .spawn()
+            .expect("应能起 ull agent serve --stdio");
+        let stdin = child.stdin.take().expect("stdin");
+        let stdout = BufReader::new(child.stdout.take().expect("stdout")).lines();
+        Self {
+            child,
+            stdin,
+            stdout,
+        }
+    }
+
+    fn send(&mut self, message: &Value) {
+        writeln!(self.stdin, "{message}").expect("写请求");
+        self.stdin.flush().expect("刷新 stdin");
+    }
+
+    fn next_response(&mut self) -> Value {
+        let line = self
+            .stdout
+            .next()
+            .expect("stdio 应有一行响应（不应挂断）")
+            .expect("读响应行失败");
+        serde_json::from_str(&line).unwrap_or_else(|_| panic!("stdout 不是 JSON-RPC：{line}"))
+    }
+
+    fn rpc(&mut self, id: u32, method: &str, params: Value) -> Value {
+        self.send(&json!({ "jsonrpc": "2.0", "id": id, "method": method, "params": params }));
+        self.next_response()
+    }
+}
+
+impl Drop for Session {
+    fn drop(&mut self) {
+        let _ = self.child.kill();
+        let _ = self.child.wait();
+    }
+}
+
+#[test]
+fn stdio_handshake_lists_tools_and_calls_them() {
+    let dir = data_dir("handshake");
+    let mut session = Session::start(&dir);
+
+    // 1. initialize
+    let init = session.rpc(
+        1,
+        "initialize",
+        json!({
+            "protocolVersion": "2025-03-26",
+            "capabilities": {},
+            "clientInfo": { "name": "ull-test", "version": "0.1" }
+        }),
+    );
+    assert_eq!(
+        init["result"]["serverInfo"]["name"],
+        json!("unlucky-launcher"),
+        "{init}"
+    );
+    session.send(&json!({ "jsonrpc": "2.0", "method": "notifications/initialized" }));
+
+    // 2. tools/list —— 写工具在（--allow-write），十个工具全在
+    let list = session.rpc(2, "tools/list", json!({}));
+    let names: Vec<String> = list["result"]["tools"]
+        .as_array()
+        .expect("tools 数组")
+        .iter()
+        .filter_map(|tool| tool["name"].as_str().map(str::to_string))
+        .collect();
+    assert_eq!(names.len(), 10, "{names:?}");
+    for expected in [
+        "get_config",
+        "set_config",
+        "list_instances",
+        "list_accounts",
+        "diagnose_crash",
+    ] {
+        assert!(names.iter().any(|name| name == expected), "缺 {expected}");
+    }
+
+    // 3. 只读工具真返回（真实 core 端口：空数据根 → 空实例/空账户）
+    let instances = session.rpc(
+        3,
+        "tools/call",
+        json!({ "name": "list_instances", "arguments": {} }),
+    );
+    assert_ne!(instances["result"]["isError"], json!(true), "{instances}");
+    let text = instances["result"]["content"][0]["text"]
+        .as_str()
+        .unwrap_or_default();
+    assert!(text.contains("\"total\":0"), "空数据根应 0 个实例：{text}");
+
+    // 4. 白名单普通键写入真落盘
+    let written = session.rpc(
+        4,
+        "tools/call",
+        json!({ "name": "set_config", "arguments": { "path": "download.concurrency", "value": 16 } }),
+    );
+    assert_ne!(written["result"]["isError"], json!(true), "{written}");
+    let launcher = dir.join(".ULL").join("config").join("launcher.json");
+    let content = std::fs::read_to_string(&launcher).expect("应写出 launcher.json");
+    assert!(content.contains("\"concurrency\""), "{content}");
+
+    // 5. 敏感键被拒（外部客户端没有弹窗），文案引导到设置页 / YOLO
+    let denied = session.rpc(
+        5,
+        "tools/call",
+        json!({ "name": "set_config", "arguments": { "path": "java.selected_path", "value": "D:/jdk17/bin/java.exe" } }),
+    );
+    assert_eq!(denied["result"]["isError"], json!(true), "{denied}");
+    let text = denied["result"]["content"][0]["text"]
+        .as_str()
+        .unwrap_or_default();
+    assert!(text.contains("YOLO"), "{text}");
+
+    // 6. 审计落盘：每一条都在，且会话标签能区分「外部 MCP」
+    let audit_dir = dir.join(".ULL").join("data").join("agent").join("audit");
+    let mut records: Vec<Value> = Vec::new();
+    for entry in std::fs::read_dir(&audit_dir)
+        .expect("审计目录应存在")
+        .flatten()
+    {
+        let text = std::fs::read_to_string(entry.path()).unwrap_or_default();
+        for line in text.lines() {
+            if let Ok(value) = serde_json::from_str::<Value>(line) {
+                records.push(value);
+            }
+        }
+    }
+    assert!(
+        records
+            .iter()
+            .any(|record| record["tool"] == json!("set_config") && record["outcome"] == json!("ok")),
+        "普通键写入应有 ok 审计：{records:?}"
+    );
+    assert!(
+        records
+            .iter()
+            .any(|record| record["outcome"] == json!("denied")),
+        "敏感键拒绝应有 denied 审计：{records:?}"
+    );
+    assert!(records
+        .iter()
+        .all(|record| record["agent_session_id"] == json!("mcp-stdio")));
+
+    let _ = std::fs::remove_dir_all(&dir);
+}
diff --git a/crates/cli/tests/config_secret_test.rs b/crates/cli/tests/config_secret_test.rs
new file mode 100644
index 0000000..ceae4c0
--- /dev/null
+++ b/crates/cli/tests/config_secret_test.rs
@@ -0,0 +1,179 @@
+//! 敏感键脱敏（P1-1 回归）：单键 get、无键全量 dump、set 的旧值回显三条路径
+//! 都不能把凭据明文交给用户或脚本。
+
+#[path = "support/mod.rs"]
+mod support;
+
+use support::{parse_json, run_cli, TempDir};
+
+/// 一眼可 grep 的假凭据。
+const SECRET: &str = "sk-live-THIS-MUST-NOT-LEAK";
+/// 代理 URL 里的口令（`download.proxy_url` 是 schema 的 High 档，但键名不含敏感词）。
+const PROXY: &str = "socks5://user:pw@127.0.0.1:1080";
+
+/// 建一个已经写入敏感键的数据根。
+fn data_dir_with_secrets() -> TempDir {
+    let dir = TempDir::new("secret");
+    let (code, _, stderr) = run_cli(&[
+        "config",
+        "set",
+        "ai.api_key",
+        SECRET,
+        "--data-dir",
+        &dir.arg(),
+    ]);
+    assert_eq!(code, 0, "{stderr}");
+    let (code, _, stderr) = run_cli(&[
+        "config",
+        "set",
+        "download.proxy_url",
+        PROXY,
+        "--data-dir",
+        &dir.arg(),
+    ]);
+    assert_eq!(code, 0, "{stderr}");
+    // 一个普通键：用来验证掩码没有把整份配置打成红条（默认值不落盘，必须先写一次）。
+    let (code, _, stderr) = run_cli(&[
+        "config",
+        "set",
+        "ui.language",
+        "en_us",
+        "--data-dir",
+        &dir.arg(),
+    ]);
+    assert_eq!(code, 0, "{stderr}");
+    dir
+}
+
+#[test]
+fn full_dump_redacts_sensitive_keys_by_default() {
+    let dir = data_dir_with_secrets();
+    let (code, stdout, stderr) = run_cli(&["config", "get", "--json", "--data-dir", &dir.arg()]);
+    assert_eq!(code, 0, "{stderr}");
+    assert!(!stdout.contains(SECRET), "全量 dump 泄出 API key：{stdout}");
+    assert!(
+        !stdout.contains("user:pw@"),
+        "全量 dump 泄出代理口令：{stdout}"
+    );
+
+    let value = parse_json(&stdout);
+    assert_eq!(value["data"]["config"]["ai"]["api_key"], "<redacted>");
+    assert_eq!(
+        value["data"]["config"]["download"]["proxy_url"],
+        "<redacted>"
+    );
+    assert_eq!(value["data"]["redacted"], true);
+    // 非敏感键照常可读（掩码不能把整份配置打成红条）。
+    assert_eq!(value["data"]["config"]["ui"]["language"], "en_us");
+}
+
+#[test]
+fn full_dump_human_output_is_redacted_too() {
+    let dir = data_dir_with_secrets();
+    let (code, stdout, _) = run_cli(&["config", "get", "--data-dir", &dir.arg()]);
+    assert_eq!(code, 0);
+    assert!(!stdout.contains(SECRET), "{stdout}");
+    assert!(!stdout.contains("user:pw@"), "{stdout}");
+    assert!(stdout.contains("<redacted>"), "{stdout}");
+    assert!(stdout.contains("--show-secret"), "{stdout}");
+}
+
+#[test]
+fn single_key_get_masks_by_default() {
+    let dir = data_dir_with_secrets();
+    let (code, stdout, _) = run_cli(&[
+        "config",
+        "get",
+        "ai.api_key",
+        "--json",
+        "--data-dir",
+        &dir.arg(),
+    ]);
+    assert_eq!(code, 0);
+    assert!(!stdout.contains(SECRET), "{stdout}");
+    let value = parse_json(&stdout);
+    assert_eq!(value["data"]["value"], "<redacted>");
+    assert_eq!(value["data"]["sensitive"], true);
+    assert_eq!(value["data"]["redacted"], true);
+}
+
+#[test]
+fn show_secret_reveals_plaintext() {
+    let dir = data_dir_with_secrets();
+    // 全量 dump + --show-secret：明文，且 redacted=false。
+    let (code, stdout, _) = run_cli(&[
+        "config",
+        "get",
+        "--show-secret",
+        "--json",
+        "--data-dir",
+        &dir.arg(),
+    ]);
+    assert_eq!(code, 0);
+    let value = parse_json(&stdout);
+    assert_eq!(value["data"]["config"]["ai"]["api_key"], SECRET);
+    assert_eq!(value["data"]["config"]["download"]["proxy_url"], PROXY);
+    assert_eq!(value["data"]["redacted"], false);
+
+    // 单键 + --show-secret：人类输出就是明文。
+    let (code, stdout, _) = run_cli(&[
+        "config",
+        "get",
+        "ai.api_key",
+        "--show-secret",
+        "--data-dir",
+        &dir.arg(),
+    ]);
+    assert_eq!(code, 0);
+    assert!(stdout.contains(SECRET), "{stdout}");
+}
+
+#[test]
+fn set_masks_old_value_but_echoes_new() {
+    let dir = data_dir_with_secrets();
+
+    let (code, stdout, stderr) = run_cli(&[
+        "config",
+        "set",
+        "ai.api_key",
+        "sk-new-value",
+        "--json",
+        "--data-dir",
+        &dir.arg(),
+    ]);
+    assert_eq!(code, 0, "{stderr}");
+    assert!(!stdout.contains(SECRET), "set 回显了旧密钥：{stdout}");
+    let value = parse_json(&stdout);
+    assert_eq!(value["data"]["old"], "<redacted>");
+    assert_eq!(value["data"]["new"], "sk-new-value");
+
+    // 人类模式同样不回显旧值明文（新值照常，用户刚敲的）。
+    let (code, stdout, _) = run_cli(&[
+        "config",
+        "set",
+        "ai.api_key",
+        "sk-third",
+        "--data-dir",
+        &dir.arg(),
+    ]);
+    assert_eq!(code, 0);
+    assert!(
+        !stdout.contains("sk-new-value"),
+        "人类输出回显旧值：{stdout}"
+    );
+    assert!(stdout.contains("<redacted>"), "{stdout}");
+    assert!(stdout.contains("sk-third"), "{stdout}");
+
+    // 非敏感键仍然正常回显原值。
+    let (code, stdout, _) = run_cli(&[
+        "config",
+        "set",
+        "ui.language",
+        "zh_cn",
+        "--json",
+        "--data-dir",
+        &dir.arg(),
+    ]);
+    assert_eq!(code, 0);
+    assert_eq!(parse_json(&stdout)["data"]["old"], "en_us");
+}
diff --git a/crates/cli/tests/exit_code_test.rs b/crates/cli/tests/exit_code_test.rs
new file mode 100644
index 0000000..8e732b1
--- /dev/null
+++ b/crates/cli/tests/exit_code_test.rs
@@ -0,0 +1,109 @@
+//! 退出码与输出通道（0 成功 / 1 用户错误 / 2 内部错误）。
+
+#[path = "support/mod.rs"]
+mod support;
+
+use support::{run_cli, write_version, TempDir};
+use unlucky_cli::error::{CliError, ErrorKind, EXIT_INTERNAL, EXIT_OK, EXIT_USER};
+
+#[test]
+fn exit_code_constants_match_kinds() {
+    assert_eq!(EXIT_OK, 0);
+    assert_eq!(EXIT_USER, 1);
+    assert_eq!(EXIT_INTERNAL, 2);
+    assert_eq!(ErrorKind::User.exit_code(), 1);
+    assert_eq!(ErrorKind::Internal.exit_code(), 2);
+    assert_eq!(CliError::usage("x").exit_code(), 1);
+    assert_eq!(CliError::user("io", "x").exit_code(), 1);
+    assert_eq!(CliError::internal("bug", "x").exit_code(), 2);
+}
+
+#[test]
+fn internal_errors_serialize_as_internal() {
+    let value = CliError::internal("serialize", "序列化失配").to_json();
+    assert_eq!(value["ok"], false);
+    assert_eq!(value["error"]["kind"], "internal");
+    assert_eq!(value["error"]["code"], "serialize");
+    assert!(value["error"].get("hint").is_none());
+}
+
+#[test]
+fn success_exits_zero() {
+    let dir = TempDir::new("code-ok");
+    let (code, _, _) = run_cli(&["instances", "list", "--data-dir", &dir.arg()]);
+    assert_eq!(code, 0);
+}
+
+#[test]
+fn user_error_exits_one() {
+    let dir = TempDir::new("code-user");
+    let cases: Vec<Vec<String>> = vec![
+        vec!["frobnicate".to_string()],
+        vec!["install".to_string()],
+        vec![
+            "launch".to_string(),
+            "nope".to_string(),
+            "--data-dir".to_string(),
+            dir.arg(),
+        ],
+        vec![
+            "logs".to_string(),
+            "deadbeef".to_string(),
+            "--data-dir".to_string(),
+            dir.arg(),
+        ],
+        // `java install` 已实装（会真联网下载）——用户错误只取参数校验这一层：
+        // 大版本号离谱时在联网之前就拒，测试因此保持零网络（M27 踩坑记录 G 节同款教训）。
+        vec![
+            "java".to_string(),
+            "install".to_string(),
+            "4".to_string(),
+            "--data-dir".to_string(),
+            dir.arg(),
+        ],
+        vec![
+            "--data-dir".to_string(),
+            "relative/path".to_string(),
+            "instances".to_string(),
+            "list".to_string(),
+        ],
+    ];
+    for args in cases {
+        let (code, _, stderr) = run_cli(&args.iter().map(String::as_str).collect::<Vec<_>>());
+        assert_eq!(code, 1, "args={args:?} stderr={stderr}");
+        assert!(stderr.contains("错误:"), "args={args:?} stderr={stderr}");
+    }
+}
+
+#[test]
+fn human_and_json_go_to_different_streams() {
+    let dir = TempDir::new("code-streams");
+    write_version(dir.path(), "1.20.1");
+
+    // 人类模式：结果进 stdout。
+    let (code, stdout, stderr) = run_cli(&["instances", "list", "--data-dir", &dir.arg()]);
+    assert_eq!(code, 0);
+    assert!(stdout.contains("实例"), "{stdout}");
+    assert!(stderr.is_empty(), "{stderr}");
+
+    // 错误进 stderr，不污染 stdout。
+    let (code, stdout, stderr) = run_cli(&["launch", "nope", "--data-dir", &dir.arg()]);
+    assert_eq!(code, 1);
+    assert!(stdout.is_empty(), "{stdout}");
+    assert!(stderr.contains("错误:"), "{stderr}");
+}
+
+#[test]
+fn quiet_suppresses_human_output_only() {
+    let dir = TempDir::new("code-quiet");
+    let (code, stdout, stderr) =
+        run_cli(&["instances", "list", "--quiet", "--data-dir", &dir.arg()]);
+    assert_eq!(code, 0);
+    assert!(stdout.is_empty(), "{stdout}");
+    assert!(stderr.is_empty(), "{stderr}");
+
+    // 错误不受 --quiet 影响（脚本仍要能看到原因）。
+    let (code, _, stderr) = run_cli(&["launch", "nope", "--quiet", "--data-dir", &dir.arg()]);
+    assert_eq!(code, 1);
+    assert!(stderr.contains("错误:"), "{stderr}");
+}
diff --git a/crates/cli/tests/isolation_launch_test.rs b/crates/cli/tests/isolation_launch_test.rs
new file mode 100644
index 0000000..2b8d4a2
--- /dev/null
+++ b/crates/cli/tests/isolation_launch_test.rs
@@ -0,0 +1,345 @@
+//! D20 隔离档位的 CLI 端到端：`ull launch` 按覆盖链把派生结果填进 `--gameDir`。
+//!
+//! 四条路径（全局 isolated / 全局 shared / 实例 override / custom）+ 旧档案读兼容 +
+//! `--dry-run` 不落盘。断言走 `--json` 输出的 `isolation` / `isolation_source` / `game_dir`，
+//! 也就是真正喂给 `${game_directory}` 与子进程 CWD 的那个值。
+
+#[path = "support/mod.rs"]
+mod support;
+
+use std::path::{Path, PathBuf};
+
+use support::{parse_json, run_cli, TempDir};
+
+/// 实例 id（与 `profiles.json` 里写的必须一致）。
+const INSTANCE_ID: &str = "11111111-2222-4333-8444-000000000001";
+/// 版本 id。
+const VERSION: &str = "1.20.1";
+
+/// 建数据根：版本本体 + `profiles.json`（一个实例「生存服」）。
+fn data_root(tag: &str) -> TempDir {
+    let dir = TempDir::new(tag);
+    write_version_with_game_dir(dir.path());
+    write_profiles(dir.path(), None);
+    dir
+}
+
+/// 写一份「带 `--gameDir ${game_directory}`」的最小版本 JSON + 空 client jar。
+///
+/// 比 `support::write_version` 多这一个参数——`--gameDir` 就是隔离档位的真实落点
+/// （正式版清单 1.13+ 都有这条），没有它就无法从命令行验证派生结果。
+fn write_version_with_game_dir(root: &Path) {
+    let dir = root.join(".minecraft").join("versions").join(VERSION);
+    std::fs::create_dir_all(&dir).expect("建版本目录");
+    let version = serde_json::json!({
+        "id": VERSION,
+        "type": "release",
+        "mainClass": "net.minecraft.client.main.Main",
+        "assets": "5",
+        "assetIndex": { "id": "5" },
+        "arguments": {
+            "game": [
+                "--username", "${auth_player_name}",
+                "--version", "${version_name}",
+                "--gameDir", "${game_directory}"
+            ],
+            "jvm": ["-Djava.library.path=${natives_directory}", "-cp", "${classpath}"]
+        },
+        "libraries": [],
+        "downloads": { "client": { "size": 4, "url": "http://example.invalid/client.jar" } }
+    });
+    std::fs::write(
+        dir.join(format!("{VERSION}.json")),
+        serde_json::to_vec_pretty(&version).expect("序列化版本 JSON"),
+    )
+    .expect("写版本 JSON");
+    std::fs::write(dir.join(format!("{VERSION}.jar")), b"junk").expect("写 client jar");
+}
+
+/// 写 `config/profiles.json`（可选 `game_dir` 遗留字段）。
+fn write_profiles(root: &Path, legacy_game_dir: Option<&Path>) {
+    let profiles_dir = root.join(".ULL").join("config");
+    std::fs::create_dir_all(&profiles_dir).expect("建配置目录");
+    let mut profile = serde_json::json!({
+        "id": INSTANCE_ID,
+        "name": "生存服",
+        "version_id": VERSION,
+    });
+    if let Some(game_dir) = legacy_game_dir {
+        profile["game_dir"] = serde_json::json!(game_dir.display().to_string());
+    }
+    let document = serde_json::json!({
+        "schema_version": 1,
+        "profiles": [profile],
+    });
+    std::fs::write(
+        profiles_dir.join("profiles.json"),
+        serde_json::to_vec_pretty(&document).expect("序列化 profiles.json"),
+    )
+    .expect("写 profiles.json");
+}
+
+/// 写实例设置文件（`config/instances/<id>.json`）。
+fn write_instance_config(dir: &Path, value: &serde_json::Value) {
+    let path = dir
+        .join(".ULL")
+        .join("config")
+        .join("instances")
+        .join(format!("{INSTANCE_ID}.json"));
+    std::fs::create_dir_all(path.parent().expect("父目录")).expect("建实例配置目录");
+    std::fs::write(
+        &path,
+        serde_json::to_vec_pretty(value).expect("序列化实例设置"),
+    )
+    .expect("写实例设置");
+}
+
+/// 跑一次 `launch <instance> --dry-run --json`。
+fn dry_run(dir: &TempDir) -> serde_json::Value {
+    let (code, stdout, stderr) = run_cli(&[
+        "launch",
+        "生存服",
+        "--dry-run",
+        "--json",
+        "--data-dir",
+        &dir.arg(),
+    ]);
+    assert_eq!(code, 0, "{stderr}");
+    parse_json(&stdout)["data"].clone()
+}
+
+/// 数据根下的游戏目录。
+fn game_root(dir: &TempDir) -> PathBuf {
+    dir.path().join(".minecraft")
+}
+
+#[test]
+fn default_mode_is_isolated_and_derives_version_dir() {
+    let dir = data_root("iso-default");
+    let data = dry_run(&dir);
+    assert_eq!(data["isolation"], "isolated", "D20 默认隔离");
+    assert_eq!(data["isolation_source"], "global");
+    assert_eq!(data["instance_found"], true, "实例名解析仍然有效");
+    assert_eq!(
+        PathBuf::from(data["game_dir"].as_str().expect("game_dir")),
+        game_root(&dir).join("versions").join(VERSION)
+    );
+    assert!(data["mode_change_warning"].is_null());
+
+    // 端到端：派生值必须是命令行里 `--gameDir` 的实参（占位符已替换、家目录已脱敏，
+    // 所以按路径后缀断言）。
+    let argv: Vec<&str> = data["argv"]
+        .as_array()
+        .expect("argv")
+        .iter()
+        .map(|token| token.as_str().expect("token"))
+        .collect();
+    let index = argv
+        .iter()
+        .position(|token| *token == "--gameDir")
+        .unwrap_or_else(|| panic!("命令行里没有 --gameDir：{argv:?}"));
+    let passed = PathBuf::from(argv[index + 1]);
+    assert!(
+        passed.ends_with(Path::new("versions").join(VERSION)),
+        "--gameDir 不是派生的隔离目录：{}",
+        passed.display()
+    );
+}
+
+#[test]
+fn shared_mode_switches_game_dir_to_game_root() {
+    let dir = data_root("iso-shared");
+    let (code, _, stderr) = run_cli(&[
+        "config",
+        "set",
+        "instances.mode",
+        "shared",
+        "--data-dir",
+        &dir.arg(),
+    ]);
+    assert_eq!(code, 0, "{stderr}");
+
+    let data = dry_run(&dir);
+    assert_eq!(data["isolation"], "shared");
+    assert_eq!(data["isolation_source"], "global");
+    assert_eq!(
+        PathBuf::from(data["game_dir"].as_str().expect("game_dir")),
+        game_root(&dir),
+        "共享档的运行目录就是 .minecraft 根"
+    );
+}
+
+#[test]
+fn instance_isolation_overrides_global_mode() {
+    let dir = data_root("iso-instance");
+    let (code, _, stderr) = run_cli(&[
+        "config",
+        "set",
+        "instances.mode",
+        "shared",
+        "--data-dir",
+        &dir.arg(),
+    ]);
+    assert_eq!(code, 0, "{stderr}");
+    write_instance_config(
+        dir.path(),
+        &serde_json::json!({
+            "schemaVersion": 1,
+            "id": INSTANCE_ID,
+            "versionId": VERSION,
+            "isolation": "isolated",
+        }),
+    );
+
+    let data = dry_run(&dir);
+    assert_eq!(data["isolation"], "isolated", "实例档位压过全局");
+    assert_eq!(data["isolation_source"], "instance");
+    assert_eq!(
+        PathBuf::from(data["game_dir"].as_str().expect("game_dir")),
+        game_root(&dir).join("versions").join(VERSION)
+    );
+}
+
+#[test]
+fn custom_isolation_uses_the_recorded_game_dir() {
+    let dir = data_root("iso-custom");
+    let custom = dir.path().join("mcs").join("farm");
+    write_instance_config(
+        dir.path(),
+        &serde_json::json!({
+            "schemaVersion": 1,
+            "id": INSTANCE_ID,
+            "versionId": VERSION,
+            "isolation": "custom",
+            "gameDir": custom.display().to_string(),
+        }),
+    );
+
+    let data = dry_run(&dir);
+    assert_eq!(data["isolation"], "custom");
+    assert_eq!(
+        PathBuf::from(data["game_dir"].as_str().expect("game_dir")),
+        custom
+    );
+}
+
+#[test]
+fn legacy_profile_game_dir_reads_as_custom() {
+    // M27 之前的档案只在 profiles.json 里存 game_dir（没有实例设置文件）：
+    // 显式指定过的目录不能被静默退回全局档。
+    let dir = TempDir::new("iso-legacy");
+    write_version_with_game_dir(dir.path());
+    let legacy = dir.path().join("old-instance-dir");
+    write_profiles(dir.path(), Some(&legacy));
+    let data = dry_run(&dir);
+    assert_eq!(data["isolation"], "custom");
+    assert_eq!(
+        PathBuf::from(data["game_dir"].as_str().expect("game_dir")),
+        legacy
+    );
+}
+
+#[test]
+fn dry_run_does_not_write_instance_state() {
+    // 切换检测只在真启动时落盘：`--dry-run` 不该吃掉「切换后首次启动提示一次」。
+    let dir = data_root("iso-dry-run");
+    let config_path = dir
+        .path()
+        .join(".ULL")
+        .join("config")
+        .join("instances")
+        .join(format!("{INSTANCE_ID}.json"));
+    assert!(!config_path.exists());
+    let _ = dry_run(&dir);
+    assert!(
+        !config_path.exists(),
+        "--dry-run 写盘了：{}",
+        config_path.display()
+    );
+}
+
+#[test]
+fn unknown_instance_still_reports_available_names() {
+    let dir = data_root("iso-unknown");
+    let (code, _, stderr) = run_cli(&[
+        "launch",
+        "不存在的实例",
+        "--dry-run",
+        "--data-dir",
+        &dir.arg(),
+    ]);
+    assert_ne!(code, 0, "未知实例要失败");
+    assert!(stderr.contains("生存服"), "提示里要列出可用实例：{stderr}");
+}
+
+/// 读实例设置文件（不存在返回 `None`）。
+fn read_instance_config(dir: &TempDir) -> Option<serde_json::Value> {
+    let path = dir
+        .path()
+        .join(".ULL")
+        .join("config")
+        .join("instances")
+        .join(format!("{INSTANCE_ID}.json"));
+    let text = std::fs::read_to_string(path).ok()?;
+    Some(serde_json::from_str(&text).expect("实例设置应为合法 JSON"))
+}
+
+/// 真启动一次（用一个不存在的 java，保证 spawn 必失败、不会真的跑起游戏），
+/// 只为驱动「真启动才写盘」的那段逻辑。
+fn real_launch_that_fails(dir: &TempDir) -> (i32, String, String) {
+    let bogus_java = dir.path().join("no-such-java.exe");
+    run_cli(&[
+        "launch",
+        "生存服",
+        "--java",
+        &bogus_java.display().to_string(),
+        "--data-dir",
+        &dir.arg(),
+    ])
+}
+
+#[test]
+fn first_real_launch_bootstraps_instance_file() {
+    // 回归 P2-3（review r1）：profiles.json 有档案但没有实例设置文件（M27 之前的形态），
+    // 真启动要补建基线文件，否则切换检测对这批遗留实例永远不启动。
+    let dir = data_root("iso-bootstrap");
+    assert!(read_instance_config(&dir).is_none(), "前置：还没有设置文件");
+
+    let (code, _, stderr) = real_launch_that_fails(&dir);
+    assert_ne!(code, 0, "假 java 必然启动失败：{stderr}");
+
+    let config = read_instance_config(&dir).expect("首次真启动应补建设置文件");
+    assert_eq!(config["versionId"], VERSION);
+    assert_eq!(config["id"], INSTANCE_ID);
+    // 基线：from == to，且已经标记 warned（不该平白弹一次提示）。
+    assert_eq!(config["lastModeChange"]["from"], "isolated");
+    assert_eq!(config["lastModeChange"]["to"], "isolated");
+    assert_eq!(config["lastModeChange"]["warned"], true);
+    assert!(config["lastModeChange"]["at"].is_string());
+    assert!(config["lastModeChange"]["probe"]["isolatedSide"].is_number());
+    assert!(config["lastModeChange"]["probe"]["sharedSide"].is_number());
+    // inherit 不落盘。
+    assert!(config.get("isolation").is_none(), "{config}");
+}
+
+#[test]
+fn legacy_profile_dir_is_recorded_as_custom_on_bootstrap() {
+    // 同一批遗留档案里「显式指定过目录」的那部分：补建时把 old profiles.game_dir → custom
+    // 固化进实例文件，之后实例文件就是唯一真相。
+    let dir = TempDir::new("iso-bootstrap-legacy");
+    write_version_with_game_dir(dir.path());
+    let legacy = dir.path().join("old-instance-dir");
+    write_profiles(dir.path(), Some(&legacy));
+
+    let (code, _, stderr) = real_launch_that_fails(&dir);
+    assert_ne!(code, 0, "假 java 必然启动失败：{stderr}");
+
+    let config = read_instance_config(&dir).expect("首次真启动应补建设置文件");
+    assert_eq!(config["isolation"], "custom");
+    assert_eq!(
+        PathBuf::from(config["gameDir"].as_str().expect("gameDir")),
+        legacy
+    );
+    assert_eq!(config["lastModeChange"]["to"], "custom");
+    assert_eq!(config["lastModeChange"]["warned"], true, "基线不弹提示");
+}
diff --git a/crates/cli/tests/java_test.rs b/crates/cli/tests/java_test.rs
new file mode 100644
index 0000000..c1570ae
--- /dev/null
+++ b/crates/cli/tests/java_test.rs
@@ -0,0 +1,197 @@
+//! `ull java list` / `ull java install` / `ull launch` 的 Java 选择（D13）CLI 端。
+//!
+//! 不联网：`install` 只测参数校验与稳定错误码；`launch --dry-run` 断言 `java` 块的结构
+//! 与「实例覆盖优先」——真正的下载/解压由 `core::game::java` 的测试与本机验收覆盖。
+
+#[path = "support/mod.rs"]
+mod support;
+
+use support::{parse_json, run_cli, write_version, TempDir};
+
+/// 一个可组装的版本 id。
+const VERSION: &str = "1.20.1";
+
+#[test]
+fn java_list_reports_the_managed_root() {
+    let dir = TempDir::new("java-list");
+    let (code, stdout, stderr) = run_cli(&["--json", "--data-dir", &dir.arg(), "java", "list"]);
+    assert_eq!(code, 0, "stderr: {stderr}");
+    let envelope = parse_json(&stdout);
+    let json = &envelope["data"];
+    assert!(
+        json["managed_root"]
+            .as_str()
+            .is_some_and(|root| root.ends_with("java-managed")),
+        "managed_root 应是 data/java-managed：{json}"
+    );
+    // D23：多根扫描 + 落点模式要说清（`--data-dir` 是 custom 数据模式 → portable 落点）。
+    assert!(
+        json["managed_roots"]
+            .as_array()
+            .is_some_and(|roots| !roots.is_empty()),
+        "{json}"
+    );
+    assert_eq!(json["install"]["mode"], "portable", "{json}");
+    assert!(
+        json["install"]["root"]
+            .as_str()
+            .is_some_and(|root| root.ends_with("java-managed")),
+        "落点根应是数据根里的 java-managed：{json}"
+    );
+    assert!(json["candidates"].is_array(), "{json}");
+}
+
+#[test]
+fn java_vendors_lists_the_four_vendors_with_the_current_order() {
+    let dir = TempDir::new("java-vendors");
+    let (code, stdout, stderr) = run_cli(&["--json", "--data-dir", &dir.arg(), "java", "vendors"]);
+    assert_eq!(code, 0, "stderr: {stderr}");
+    let envelope = parse_json(&stdout);
+    let json = &envelope["data"];
+    let order: Vec<&str> = json["order"]
+        .as_array()
+        .expect("order 数组")
+        .iter()
+        .filter_map(|item| item.as_str())
+        .collect();
+    assert_eq!(order.len(), 4, "{json}");
+    assert!(order.contains(&"temurin"), "{json}");
+    assert!(order.contains(&"oracle"), "{json}");
+    assert!(order.contains(&"microsoft"), "{json}");
+    assert!(order.contains(&"zulu"), "{json}");
+    // 本机时区/语言决定 domestic/global，两种默认序都合法，但来源必须明示。
+    let source = json["priority_source"].as_str().unwrap_or("?");
+    assert_eq!(
+        source, "region_default",
+        "没设 java.vendorPriority 时：{json}"
+    );
+    let vendors = json["vendors"].as_array().expect("vendors 数组");
+    assert_eq!(vendors.len(), 4);
+    let microsoft = vendors
+        .iter()
+        .find(|row| row["vendor"] == "microsoft")
+        .expect("应有 microsoft 行");
+    assert_eq!(
+        microsoft["supported"].as_array().map(Vec::len),
+        Some(4),
+        "MS 只发 25/21/17/11：{microsoft}"
+    );
+    assert!(
+        microsoft["sources"]
+            .as_array()
+            .is_some_and(|sources| !sources.is_empty()),
+        "MS 的源（aka.ms → VS CDN）要列出来：{microsoft}"
+    );
+}
+
+#[test]
+fn java_install_rejects_an_unknown_vendor_without_network() {
+    let dir = TempDir::new("java-vendor-bad");
+    let (code, stdout, _stderr) = run_cli(&[
+        "--json",
+        "--data-dir",
+        &dir.arg(),
+        "java",
+        "install",
+        "21",
+        "--vendor",
+        "graalvm",
+    ]);
+    assert_eq!(code, 1);
+    let envelope = parse_json(&stdout);
+    assert_eq!(envelope["error"]["code"], "usage", "{envelope}");
+}
+
+#[test]
+fn java_install_rejects_an_absurd_major_without_network() {
+    let dir = TempDir::new("java-install");
+    let (code, stdout, _stderr) =
+        run_cli(&["--json", "--data-dir", &dir.arg(), "java", "install", "4"]);
+    assert_eq!(code, 1);
+    let envelope = parse_json(&stdout);
+    assert_eq!(envelope["error"]["code"], "usage", "{envelope}");
+}
+
+#[test]
+fn launch_dry_run_reports_the_java_requirement_of_the_version() {
+    let dir = TempDir::new("java-launch");
+    write_version(dir.path(), VERSION);
+    let (code, stdout, stderr) = run_cli(&[
+        "--json",
+        "--data-dir",
+        &dir.arg(),
+        "launch",
+        VERSION,
+        "--dry-run",
+    ]);
+    assert_eq!(code, 0, "stderr: {stderr}");
+    let envelope = parse_json(&stdout);
+    let json = &envelope["data"];
+    let java = &json["java"];
+    // 1.20.1 的清单没写 javaVersion → 静态表兜底 17。
+    assert_eq!(java["required_major"], 17, "{json}");
+    assert_eq!(java["requirement_source"], "table", "{json}");
+    assert_eq!(json["version_id"], VERSION);
+    // `source` 只可能是探测到的来源之一（本机未必装了 Java）。
+    let source = java["source"].as_str().unwrap_or("none");
+    assert!(
+        ["instance", "managed", "JAVA_HOME", "PATH", "none"].contains(&source),
+        "意外的来源：{source}"
+    );
+}
+
+#[test]
+fn instance_java_override_wins_over_the_system_java() {
+    let dir = TempDir::new("java-override");
+    write_version(dir.path(), VERSION);
+    // 故意给一个不存在的路径：只要能进 `source=instance` 就说明覆盖优先级生效
+    // （探测失败只影响 major，不该把用户指定的路径换成系统 Java）。
+    let fake = dir.path().join("some-jdk").join("bin").join("java");
+    let (code, stdout, stderr) = run_cli(&[
+        "--json",
+        "--data-dir",
+        &dir.arg(),
+        "launch",
+        VERSION,
+        "--dry-run",
+        "--java",
+        &fake.display().to_string(),
+    ]);
+    assert_eq!(code, 0, "stderr: {stderr}");
+    let envelope = parse_json(&stdout);
+    let json = &envelope["data"];
+    assert_eq!(json["java"]["source"], "instance", "{json}");
+    assert_eq!(
+        json["java"]["binary"].as_str(),
+        Some(fake.display().to_string().as_str())
+    );
+}
+
+#[test]
+fn legacy_version_requires_java_8_and_flags_a_newer_runtime() {
+    let dir = TempDir::new("java-legacy");
+    write_version(dir.path(), "1.12.2");
+    let (code, stdout, stderr) = run_cli(&[
+        "--json",
+        "--data-dir",
+        &dir.arg(),
+        "launch",
+        "1.12.2",
+        "--dry-run",
+    ]);
+    assert_eq!(code, 0, "stderr: {stderr}");
+    let envelope = parse_json(&stdout);
+    let json = &envelope["data"];
+    assert_eq!(json["java"]["required_major"], 8, "{json}");
+    assert_eq!(json["java"]["required"], "Java 8", "{json}");
+    // 本机若有比 8 新的 Java，必须给出 java_too_new 告警（不能只靠「最低版本」）。
+    if let Some(code) = json["java"]["mismatch"]["code"].as_str() {
+        assert!(code == "java_too_new" || code == "java_too_old", "{json}");
+        assert!(
+            json["warnings"]
+                .as_array()
+                .is_some_and(|warnings| !warnings.is_empty()),
+            "不符时必须进 warnings：{json}"
+        );
+    }
+}
diff --git a/crates/cli/tests/os_test.rs b/crates/cli/tests/os_test.rs
new file mode 100644
index 0000000..086da5f
--- /dev/null
+++ b/crates/cli/tests/os_test.rs
@@ -0,0 +1,115 @@
+//! D19/D21 支持基线：core 的纯判定函数 + CLI 的呈现层（注入样本，不动真机）。
+
+use unlucky_cli::os;
+use unlucky_core::platform::linux_caps::{GlProbe, SessionKind};
+use unlucky_core::platform::os_info::{
+    self, linux_level, macos_level, support_level_for, windows_level, OsFamily, OsInfo,
+    SupportLevel,
+};
+use unlucky_core::platform::vk_probe::VkProbe;
+
+/// 手工构造一份样本系统信息（字段全是探测事实，等级用 core 的纯函数算）。
+fn sample(family: OsFamily, version: Option<(u32, u32)>, product: &str) -> OsInfo {
+    let version_string =
+        version.map_or_else(String::new, |(major, minor)| format!("{major}.{minor}"));
+    OsInfo {
+        family,
+        arch: "x86_64".to_string(),
+        major_minor: version,
+        build: None,
+        product: product.to_string(),
+        version_string,
+        session: SessionKind::Unknown,
+        gl: GlProbe::Unknown,
+        vk: VkProbe::Unknown,
+        kernel: None,
+        glibc: None,
+        support_level: support_level_for(family, version, None, None),
+    }
+}
+
+#[test]
+fn windows_samples_below_win10_are_unsupported() {
+    // D21 用户拍板「直接 win10 起步」：Win8.1 / 8 / 7 及更旧一律不支持。
+    assert_eq!(windows_level(Some((6, 1))), SupportLevel::Unsupported); // Win7
+    assert_eq!(windows_level(Some((6, 2))), SupportLevel::Unsupported); // Win8
+    assert_eq!(windows_level(Some((6, 3))), SupportLevel::Unsupported); // Win8.1
+    assert_eq!(windows_level(Some((5, 1))), SupportLevel::Unsupported); // XP
+    assert_eq!(windows_level(Some((10, 0))), SupportLevel::One); // Win10
+
+    // 探不到版本 → 保守判不支持（不能因为"探不到"就放行）。
+    assert_eq!(windows_level(None), SupportLevel::Unsupported);
+}
+
+#[test]
+fn macos_and_linux_samples() {
+    assert_eq!(macos_level(Some(11)), SupportLevel::Unsupported);
+    assert_eq!(macos_level(Some(12)), SupportLevel::One);
+    assert_eq!(macos_level(None), SupportLevel::Unsupported);
+    // Linux：内核/glibc 探得到但过低 → 不支持；取不到（容器/musl/Termux）不阻塞。
+    assert_eq!(linux_level(Some((2, 6)), None), SupportLevel::Unsupported);
+    assert_eq!(linux_level(None, Some((2, 12))), SupportLevel::Unsupported);
+    assert_eq!(linux_level(Some((6, 8)), Some((2, 39))), SupportLevel::One);
+    assert_eq!(linux_level(None, None), SupportLevel::One);
+}
+
+#[test]
+fn unsupported_sample_renders_upgrade_hint() {
+    let info = sample(OsFamily::Windows, Some((6, 3)), "Windows 8.1");
+
+    assert!(!info.support_level.is_usable());
+    let line = os::summary_line(&info);
+    assert!(line.contains("Windows 8.1"), "{line}");
+    assert!(line.contains("6.3"), "{line}");
+    assert!(line.contains("不支持"), "{line}");
+
+    let notes = os::notes(&info);
+    assert_eq!(notes.len(), 1);
+    assert!(notes[0].contains("Windows 10 或更高版本"), "{notes:?}");
+
+    // 文案是中英双语（core 同一份措辞），脚本只读 --json。
+    let message = info.describe().combined();
+    assert!(message.contains("Windows 10 或更高版本"), "{message}");
+    assert!(message.contains("Windows 10 or newer"), "{message}");
+
+    let value = os::to_json(&info);
+    assert_eq!(value["family"], "windows");
+    assert_eq!(value["product"], "Windows 8.1");
+    assert_eq!(value["support"], "unsupported");
+    assert_eq!(value["major_minor"], "6.3");
+}
+
+#[test]
+fn supported_sample_has_no_notes() {
+    let info = sample(OsFamily::Windows, Some((10, 0)), "Windows 11");
+    assert!(info.support_level.is_usable());
+    assert!(os::notes(&info).is_empty());
+    assert!(os::summary_line(&info).contains("满足最低要求"));
+    assert_eq!(os::to_json(&info)["support"], "one");
+}
+
+#[test]
+fn missing_version_is_reported_as_null_not_zero() {
+    // 探不到版本时 `version` 是 null（脚本按 null 判定"未探测"），而不是空串。
+    let info = sample(OsFamily::Windows, None, "Windows");
+    let value = os::to_json(&info);
+    assert!(value["version"].is_null());
+    assert!(value["major_minor"].is_null());
+    assert_eq!(value["support"], "unsupported");
+    assert!(os::summary_line(&info).contains("版本未知"));
+}
+
+#[test]
+fn real_detect_matches_core_cache() {
+    // 真机上 CLI 的摘要必须就是 core 的缓存快照（同一份事实，不做二次加工）。
+    let info = os::detect();
+    assert_eq!(&info, os_info::current());
+    assert!(!info.arch.is_empty());
+    assert!(!info.product.is_empty());
+    // 自检形态与事实一致。
+    let check = os::check();
+    assert_eq!(check.level, info.support_level);
+    assert_eq!(check.os, info);
+    assert_eq!(check.is_usable(), info.support_level.is_usable());
+    assert!(check.message.contains(&info.product), "{}", check.message);
+}
diff --git a/crates/cli/tests/output_test.rs b/crates/cli/tests/output_test.rs
new file mode 100644
index 0000000..862842c
--- /dev/null
+++ b/crates/cli/tests/output_test.rs
@@ -0,0 +1,295 @@
+//! `--json` 输出形状与真实 core 轻量路径（只读命令 + dry-run）。
+
+#[path = "support/mod.rs"]
+mod support;
+
+use support::{parse_json, run_cli, write_profiles, write_session, write_version, TempDir};
+
+#[test]
+fn version_json_has_os_summary() {
+    let (code, stdout, _) = run_cli(&["--version", "--json"]);
+    assert_eq!(code, 0);
+    let value = parse_json(&stdout);
+    assert_eq!(value["ok"], true);
+    // M82：自称的名字跟着被调用的二进制走（test harness 里是测试二进制名，`ull` 里是 `ull`）；
+    // argv[0] → 名字的映射由 cli::program 的单测钉死。
+    assert_eq!(
+        value["data"]["name"],
+        unlucky_cli::cli::program::name(),
+        "{stdout}"
+    );
+    assert_eq!(value["data"]["version"], env!("CARGO_PKG_VERSION"));
+    // D19/D21：os 对象来自 core::platform::os_info（family + 两档 support）。
+    assert!(value["data"]["os"]["family"].is_string());
+    let support = value["data"]["os"]["support"].as_str().unwrap_or_default();
+    assert!(matches!(support, "one" | "unsupported"), "{support}");
+}
+
+#[test]
+fn welcome_without_subcommand_prints_version_and_help() {
+    let (code, stdout, _) = run_cli(&[]);
+    assert_eq!(code, 0);
+    // banner 用被调用的二进制名（M82），不写死 `ull`。
+    let banner = format!("{} ", unlucky_cli::cli::program::name());
+    assert!(stdout.starts_with(&banner), "{stdout}");
+    assert!(stdout.contains("用法:"), "{stdout}");
+
+    let (code, stdout, _) = run_cli(&["--json"]);
+    assert_eq!(code, 0);
+    let value = parse_json(&stdout);
+    assert!(value["data"]["help"]
+        .as_str()
+        .unwrap_or_default()
+        .contains("用法:"));
+}
+
+#[test]
+fn instances_list_json_shape() {
+    let dir = TempDir::new("instances");
+    write_version(dir.path(), "1.20.1");
+    write_profiles(dir.path(), &[("生存服", "1.20.1"), ("空实例", "1.19.4")]);
+
+    let (code, stdout, _) = run_cli(&["instances", "list", "--json", "--data-dir", &dir.arg()]);
+    assert_eq!(code, 0);
+    let value = parse_json(&stdout);
+    let instances = value["data"]["instances"]
+        .as_array()
+        .expect("instances 数组");
+    assert_eq!(instances.len(), 2);
+    assert_eq!(instances[0]["name"], "生存服");
+    assert_eq!(instances[0]["version_present"], true);
+    assert_eq!(instances[1]["version_present"], false);
+    let installed = value["data"]["installed_versions"]
+        .as_array()
+        .expect("已安装版本");
+    assert_eq!(installed.len(), 1);
+    assert_eq!(installed[0], "1.20.1");
+}
+
+#[test]
+fn install_rejects_unknown_loader_before_touching_network() {
+    let dir = TempDir::new("install-loader");
+    let (code, stdout, _) = run_cli(&[
+        "install",
+        "1.20.1",
+        "--loader",
+        "liteloader",
+        "--json",
+        "--data-dir",
+        &dir.arg(),
+    ]);
+    assert_eq!(code, 1, "未知加载器是用户错误");
+    let value = parse_json(&stdout);
+    assert_eq!(value["error"]["code"], "loader_unknown");
+    assert!(
+        !dir.path()
+            .join(".ULL")
+            .join("config")
+            .join("profiles.json")
+            .exists(),
+        "拒绝时不该登记任何实例"
+    );
+}
+
+#[test]
+fn install_reports_name_conflict_without_downloading() {
+    let dir = TempDir::new("install-conflict");
+    write_profiles(dir.path(), &[("生存服", "1.19.4")]);
+
+    // 同名但绑定别的版本 → 冲突，且这一步在联网/下载之前就返回。
+    let (code, stdout, _) = run_cli(&[
+        "install",
+        "1.20.1",
+        "--name",
+        "生存服",
+        "--json",
+        "--data-dir",
+        &dir.arg(),
+    ]);
+    assert_eq!(code, 1);
+    let value = parse_json(&stdout);
+    assert_eq!(value["error"]["code"], "instance_exists");
+    assert!(
+        value["error"]["message"]
+            .as_str()
+            .unwrap_or_default()
+            .contains("1.19.4"),
+        "错误里应说明冲突版本：{stdout}"
+    );
+}
+
+#[test]
+fn install_requires_a_version_id() {
+    let dir = TempDir::new("install-empty");
+    let (code, _, stderr) = run_cli(&["install", " ", "--data-dir", &dir.arg()]);
+    assert_eq!(code, 1);
+    assert!(stderr.contains("版本 id"), "stderr={stderr}");
+}
+
+#[test]
+fn launch_dry_run_prints_assembled_command() {
+    let dir = TempDir::new("dryrun");
+    write_version(dir.path(), "1.20.1");
+    write_profiles(dir.path(), &[("生存服", "1.20.1")]);
+
+    let (code, stdout, _) = run_cli(&[
+        "launch",
+        "生存服",
+        "--dry-run",
+        "--username",
+        "Steve",
+        "--max-memory",
+        "2048",
+        "--json",
+        "--data-dir",
+        &dir.arg(),
+    ]);
+    assert_eq!(code, 0, "{stdout}");
+    let value = parse_json(&stdout);
+    let data = &value["data"];
+    assert_eq!(data["dry_run"], true);
+    assert_eq!(data["instance_found"], true);
+    let argv = data["argv"].as_array().expect("argv 数组");
+    let joined = argv
+        .iter()
+        .filter_map(|item| item.as_str())
+        .collect::<Vec<_>>()
+        .join(" ");
+    assert!(joined.contains("-Xmx2048"), "{joined}");
+    assert!(
+        joined.contains("net.minecraft.client.main.Main"),
+        "{joined}"
+    );
+    assert!(joined.contains("--username Steve"), "{joined}");
+    // 凭据绝不落到 dry-run 输出里。
+    assert!(!joined.contains("accessToken "), "{joined}");
+    assert!(data["classpath_entries"].as_u64().unwrap_or(0) >= 1);
+}
+
+#[test]
+fn sessions_logs_and_diag_read_the_index() {
+    let dir = TempDir::new("sessions");
+    let sid = write_session(dir.path());
+
+    let (code, stdout, _) = run_cli(&["sessions", "list", "--json", "--data-dir", &dir.arg()]);
+    assert_eq!(code, 0);
+    let value = parse_json(&stdout);
+    let sessions = value["data"]["sessions"].as_array().expect("sessions 数组");
+    assert_eq!(sessions.len(), 1);
+    assert_eq!(sessions[0]["session_id"], sid);
+    assert_eq!(sessions[0]["exit_code"], 1);
+
+    let (code, stdout, _) = run_cli(&[
+        "logs",
+        &sid,
+        "--tail",
+        "1",
+        "--json",
+        "--data-dir",
+        &dir.arg(),
+    ]);
+    assert_eq!(code, 0);
+    let value = parse_json(&stdout);
+    let events = value["data"]["events"].as_array().expect("events 数组");
+    assert_eq!(events.len(), 1);
+    assert_eq!(events[0]["kind"], "stderr");
+
+    // 前缀匹配唯一即可（脚本里手打全 id 太长）。
+    let (code, stdout, _) = run_cli(&["diag", "20261030", "--json", "--data-dir", &dir.arg()]);
+    assert_eq!(code, 0, "{stdout}");
+    let value = parse_json(&stdout);
+    assert_eq!(value["data"]["session_id"], sid);
+    let candidates = value["data"]["diagnosis"]["candidates"]
+        .as_array()
+        .expect("candidates 数组");
+    assert!(!candidates.is_empty(), "OOM 日志应命中规则：{stdout}");
+    assert_eq!(value["data"]["diagnosis"]["needs_more_info"], false);
+}
+
+#[test]
+fn logs_json_payload_is_redacted_like_human_output() {
+    // P2-1：`--json` 是机器消费路径，不该比人类输出拿到更多原文（主目录用户名段）。
+    let dir = TempDir::new("logs-redact");
+    let sid = write_session(dir.path());
+    let events = dir
+        .path()
+        .join(".ULL")
+        .join("data")
+        .join("agent")
+        .join("sessions")
+        .join("game")
+        .join(format!("{sid}.jsonl"));
+    let extra = serde_json::json!({
+        "v": 1, "seq": 9, "ts": "2026-10-30T10:15:07Z", "t_ms": 6000,
+        "kind": "stdout", "session_id": sid,
+        "payload": { "line": r"cat C:\Users\Bob\secret.txt failed", "level": "info" }
+    });
+    let mut text = std::fs::read_to_string(&events).expect("读事件流");
+    text.push_str(&serde_json::to_string(&extra).expect("序列化事件"));
+    text.push('\n');
+    std::fs::write(&events, text).expect("写事件流");
+
+    let (code, stdout, stderr) = run_cli(&["logs", &sid, "--json", "--data-dir", &dir.arg()]);
+    assert_eq!(code, 0, "{stderr}");
+    assert!(!stdout.contains("Bob"), "JSON 载荷泄出用户名：{stdout}");
+    assert!(stdout.contains("***"), "JSON 载荷未脱敏：{stdout}");
+}
+
+#[test]
+fn config_get_set_round_trip() {
+    let dir = TempDir::new("config");
+    let data_dir = dir.arg();
+
+    let (code, stdout, _) = run_cli(&[
+        "config",
+        "get",
+        "ui.language",
+        "--json",
+        "--data-dir",
+        &data_dir,
+    ]);
+    assert_eq!(code, 0);
+    let value = parse_json(&stdout);
+    assert_eq!(value["data"]["key"], "ui.language");
+    assert_eq!(value["data"]["value"], "zh_cn");
+
+    let (code, stdout, _) = run_cli(&[
+        "config",
+        "set",
+        "ui.language",
+        "en_us",
+        "--json",
+        "--data-dir",
+        &data_dir,
+    ]);
+    assert_eq!(code, 0, "{stdout}");
+    let value = parse_json(&stdout);
+    assert_eq!(value["data"]["old"], "zh_cn");
+    assert_eq!(value["data"]["new"], "en_us");
+
+    let (_, stdout, _) = run_cli(&[
+        "config",
+        "get",
+        "ui.language",
+        "--json",
+        "--data-dir",
+        &data_dir,
+    ]);
+    assert_eq!(parse_json(&stdout)["data"]["value"], "en_us");
+}
+
+#[test]
+fn error_envelope_shape() {
+    let dir = TempDir::new("errors");
+    let (code, stdout, _) = run_cli(&["launch", "nope", "--json", "--data-dir", &dir.arg()]);
+    assert_eq!(code, 1);
+    let value = parse_json(&stdout);
+    assert_eq!(value["ok"], false);
+    assert_eq!(value["error"]["code"], "not_found");
+    assert_eq!(value["error"]["kind"], "user");
+    assert!(value["error"]["message"]
+        .as_str()
+        .unwrap_or_default()
+        .contains("nope"));
+    assert!(value["error"]["hint"].is_string());
+}
diff --git a/crates/cli/tests/pack_test.rs b/crates/cli/tests/pack_test.rs
new file mode 100644
index 0000000..196b8b1
--- /dev/null
+++ b/crates/cli/tests/pack_test.rs
@@ -0,0 +1,199 @@
+//! `ull pack import` 的三态契约：退出码 0 / 3 / 1 + `--json` 信封恒有结构。
+//!
+//! **全部离线、全部不依赖 zip**：
+//!
+//! - MultiMC / Prism 的真实形态就是**目录**，直接拷 → `0`；
+//! - mrpack 也能以**目录**打开（`PackArchive` 对目录与 zip 一视同仁），造一条 `downloads` 为空的
+//!   `files[]` 条目 ⇒ 补不出来 ⇒ `3`，不会发任何请求；
+//! - 坏包用**一个不是 zip 的普通文件** ⇒ 开包即拒 ⇒ `1`（具体的恶意样本分类在 core 的
+//!   `addon/tests/import_failures.rs`，这里只钉 CLI 的退出码与 JSON 契约）。
+
+#[path = "support/mod.rs"]
+mod support;
+
+use std::path::{Path, PathBuf};
+
+use serde_json::Value;
+use support::{run_cli, TempDir};
+
+/// 写一个文件（自动建父目录）。
+fn write_file(path: &Path, bytes: &[u8]) {
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent).expect("建目录");
+    }
+    std::fs::write(path, bytes).expect("写文件");
+}
+
+/// 造一个最小 MultiMC / Prism 实例目录。
+fn multimc_instance(root: &Path) -> PathBuf {
+    let instance = root.join("mmc");
+    write_file(
+        &instance.join("mmc-pack.json"),
+        br#"{"formatVersion": 1, "components": [
+            {"uid": "net.minecraft", "version": "1.20.1"},
+            {"uid": "net.fabricmc.fabric-loader", "version": "0.15.11"},
+            {"uid": "org.lwjgl3", "version": "3.3.2"}]}"#,
+    );
+    write_file(
+        &instance.join("instance.cfg"),
+        b"InstanceType=OneSix\nname=cli pack\n",
+    );
+    write_file(&instance.join(".minecraft/mods/a.jar"), b"jar bytes");
+    instance
+}
+
+/// 造一个目录形式的 mrpack：一条远端条目，但 `downloads` 为空（补不出来 ⇒ 缺文件）。
+fn mrpack_directory(root: &Path) -> PathBuf {
+    let source = root.join("mr-src");
+    write_file(
+        &source.join("modrinth.index.json"),
+        br#"{"game": "minecraft", "formatVersion": 1, "versionId": "1.0.0",
+             "name": "cli mrpack", "summary": "dir-form mrpack",
+             "files": [{"path": "mods/ghost.jar",
+                        "hashes": {"sha1": "0123456789abcdef0123456789abcdef01234567",
+                                   "sha512": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"},
+                        "env": {"client": "required", "server": "required"},
+                        "downloads": [], "fileSize": 11}],
+             "dependencies": {"minecraft": "1.20.1", "fabric-loader": "0.15.11"}}"#,
+    );
+    write_file(&source.join("overrides/config/known.toml"), b"k = 1\n");
+    source
+}
+
+fn parse_json(stdout: &str) -> Value {
+    serde_json::from_str(stdout)
+        .unwrap_or_else(|error| panic!("stdout 不是合法 JSON（{error}）：{stdout}"))
+}
+
+#[test]
+fn imports_a_multimc_instance_and_exits_zero() {
+    let data = TempDir::new("pack-ok");
+    let source = multimc_instance(data.path());
+    let target = data.path().join("inst");
+    let (code, stdout, stderr) = run_cli(&[
+        "pack",
+        "import",
+        &source.display().to_string(),
+        "--target",
+        &target.display().to_string(),
+        "--data-dir",
+        &data.arg(),
+        "--no-register",
+        "--json",
+    ]);
+
+    assert_eq!(code, 0, "stdout={stdout} stderr={stderr}");
+    let value = parse_json(&stdout);
+    assert_eq!(value["ok"], Value::Bool(true));
+    assert_eq!(value["data"]["status"], Value::String("success".into()));
+    assert_eq!(value["data"]["format"], Value::String("multimc".into()));
+    assert_eq!(
+        value["data"]["loader"]["kind"],
+        Value::String("fabric".into())
+    );
+    // 走过的阶段都记下来了。
+    let stages = value["data"]["stages"].as_array().expect("stages 数组");
+    assert!(stages.iter().any(|stage| stage == "probe"), "{stages:?}");
+    assert!(stages.iter().any(|stage| stage == "commit"), "{stages:?}");
+    // 内容真的落地了。
+    assert_eq!(
+        std::fs::read(target.join("mods/a.jar")).expect("a.jar"),
+        b"jar bytes"
+    );
+    // 未支持的 component 逐项进 JSON。
+    assert_eq!(
+        value["data"]["rejected_components"][0]["uid"],
+        Value::String("org.lwjgl3".into())
+    );
+}
+
+#[test]
+fn missing_files_make_it_partial_and_exit_three() {
+    let data = TempDir::new("pack-partial");
+    let source = mrpack_directory(data.path());
+    let target = data.path().join("inst");
+    let (code, stdout, stderr) = run_cli(&[
+        "pack",
+        "import",
+        &source.display().to_string(),
+        "--target",
+        &target.display().to_string(),
+        "--data-dir",
+        &data.arg(),
+        "--no-register",
+        "--json",
+    ]);
+
+    assert_eq!(
+        code, 3,
+        "部分成功是 3，不是 0/1：stdout={stdout} stderr={stderr}"
+    );
+    let value = parse_json(&stdout);
+    assert_eq!(value["data"]["status"], Value::String("partial".into()));
+    assert_eq!(
+        value["data"]["missing"].as_array().map(Vec::len),
+        Some(1),
+        "补不出来的条目要如实记缺：{stdout}"
+    );
+    // 覆盖内容照装。
+    assert!(target.join("config/known.toml").is_file());
+}
+
+#[test]
+fn failed_import_exits_one_and_still_emits_structured_json() {
+    let data = TempDir::new("pack-fail");
+    let pack = data.path().join("broken.zip");
+    // 一个根本不是 zip 的文件：开包即拒。
+    write_file(&pack, b"this is not a zip archive");
+
+    let target = data.path().join("inst");
+    let (code, stdout, stderr) = run_cli(&[
+        "pack",
+        "import",
+        &pack.display().to_string(),
+        "--target",
+        &target.display().to_string(),
+        "--data-dir",
+        &data.arg(),
+        "--no-register",
+        "--json",
+    ]);
+
+    assert_eq!(code, 1, "stdout={stdout} stderr={stderr}");
+    // 失败也**必须**是结构化 JSON（不抛栈、不打人类可读文本到 stdout）。
+    let value = parse_json(&stdout);
+    assert_eq!(value["ok"], Value::Bool(true));
+    assert_eq!(value["data"]["status"], Value::String("failed".into()));
+    assert!(
+        value["data"]["error"]["code"].is_string(),
+        "失败要带稳定码：{stdout}"
+    );
+    assert_eq!(value["data"]["rolled_back"], Value::Bool(true));
+    // 零残留。
+    assert!(!target.exists(), "致命失败后目标目录必须不存在");
+    // 失败也不是"崩了"：stderr 里不该出现 panic 之类的栈信息。
+    assert!(!stderr.contains("panicked"), "{stderr}");
+}
+
+#[test]
+fn other_commands_still_exit_zero() {
+    // `Outcome::exit_code` 是给 pack import 用的；其它命令的行为不许变。
+    let data = TempDir::new("pack-regression");
+    let (code, stdout, _) = run_cli(&["instances", "list", "--data-dir", &data.arg()]);
+    assert_eq!(code, 0, "{stdout}");
+    let (code, _, _) = run_cli(&["--help"]);
+    assert_eq!(code, 0);
+    let (code, _, _) = run_cli(&["config", "get", "--data-dir", &data.arg()]);
+    assert_eq!(code, 0);
+}
+
+#[test]
+fn help_lists_the_pack_command() {
+    let (code, stdout, _) = run_cli(&["help", "pack"]);
+    assert_eq!(code, 0);
+    assert!(stdout.contains("pack import"), "{stdout}");
+    assert!(stdout.contains("部分成功"), "{stdout}");
+    let (code, stdout, _) = run_cli(&["--help"]);
+    assert_eq!(code, 0);
+    assert!(stdout.contains("pack import"), "总帮助里也要有：{stdout}");
+}
diff --git a/crates/cli/tests/parse_test.rs b/crates/cli/tests/parse_test.rs
new file mode 100644
index 0000000..62a17cb
--- /dev/null
+++ b/crates/cli/tests/parse_test.rs
@@ -0,0 +1,338 @@
+//! 子命令解析：手写解析器的语法契约。
+
+#[path = "support/mod.rs"]
+mod support;
+
+use unlucky_cli::cli::{parse, AccountsAddKind, Command, Globals};
+use unlucky_cli::error::ErrorKind;
+
+fn invoke(args: &[&str]) -> unlucky_cli::cli::Invocation {
+    let owned: Vec<String> = args.iter().map(|arg| arg.to_string()).collect();
+    parse(&owned).unwrap_or_else(|error| panic!("解析失败：{error}"))
+}
+
+#[test]
+fn no_args_is_welcome() {
+    let invocation = invoke(&[]);
+    assert_eq!(invocation.command, Command::Welcome);
+    assert_eq!(invocation.globals, Globals::default());
+}
+
+#[test]
+fn version_flags() {
+    assert_eq!(invoke(&["--version"]).command, Command::Version);
+    assert_eq!(invoke(&["-V"]).command, Command::Version);
+    assert_eq!(invoke(&["version"]).command, Command::Version);
+}
+
+#[test]
+fn help_takes_topic_from_positional() {
+    assert_eq!(invoke(&["--help"]).command, Command::Help(None));
+    assert_eq!(
+        invoke(&["--help", "launch"]).command,
+        Command::Help(Some("launch".to_string()))
+    );
+    assert_eq!(
+        invoke(&["help", "config"]).command,
+        Command::Help(Some("config".to_string()))
+    );
+}
+
+#[test]
+fn globals_are_position_independent() {
+    let invocation = invoke(&["instances", "list", "--json", "--quiet"]);
+    assert_eq!(invocation.command, Command::InstancesList);
+    assert!(invocation.globals.json);
+    assert!(invocation.globals.quiet);
+
+    let before = invoke(&["--json", "instances", "list"]);
+    assert!(before.globals.json);
+    assert_eq!(before.command, Command::InstancesList);
+}
+
+#[test]
+fn data_dir_accepts_both_forms() {
+    assert_eq!(
+        invoke(&["--data-dir", "/tmp/ull", "instances", "list"])
+            .globals
+            .data_dir,
+        Some(std::path::PathBuf::from("/tmp/ull"))
+    );
+    assert_eq!(
+        invoke(&["instances", "list", "--data-dir=/tmp/ull"])
+            .globals
+            .data_dir,
+        Some(std::path::PathBuf::from("/tmp/ull"))
+    );
+}
+
+#[test]
+fn install_flags() {
+    let Command::Install(args) =
+        invoke(&["install", "1.20.1", "--loader", "vanilla", "--name=x"]).command
+    else {
+        panic!("应为 install");
+    };
+    assert_eq!(args.version, "1.20.1");
+    assert_eq!(args.loader.as_deref(), Some("vanilla"));
+    assert_eq!(args.name.as_deref(), Some("x"));
+    assert!(!args.dry_run);
+    assert!(args.progress, "人类模式默认打实时进度");
+}
+
+#[test]
+fn install_loader_version_flag() {
+    let Command::Install(args) = invoke(&[
+        "install",
+        "1.20.1",
+        "--loader",
+        "fabric",
+        "--loader-version",
+        "0.15.11",
+    ])
+    .command
+    else {
+        panic!("应为 install");
+    };
+    assert_eq!(args.loader.as_deref(), Some("fabric"));
+    assert_eq!(args.loader_version.as_deref(), Some("0.15.11"));
+    // 不带该 flag 时为 None（由 core 取官方默认版本）。
+    let Command::Install(default) = invoke(&["install", "1.20.1"]).command else {
+        panic!("应为 install");
+    };
+    assert!(default.loader_version.is_none());
+}
+
+#[test]
+fn install_dry_run_flag_and_progress_suppression() {
+    let Command::Install(args) = invoke(&["install", "1.20.1", "--dry-run"]).command else {
+        panic!("应为 install");
+    };
+    assert!(args.dry_run);
+    assert!(args.progress);
+    assert!(!args.json_progress, "人类模式打文本进度");
+
+    // `--json`：stderr 换成 JSONL 进度（stdout 仍是单个信封）。
+    let Command::Install(args) = invoke(&["--json", "install", "1.20.1"]).command else {
+        panic!("应为 install");
+    };
+    assert!(args.progress);
+    assert!(args.json_progress);
+
+    // `--quiet`：一律不打进度。
+    let Command::Install(args) = invoke(&["install", "1.20.1", "-q"]).command else {
+        panic!("应为 install");
+    };
+    assert!(!args.progress);
+    assert!(!args.dry_run);
+}
+
+#[test]
+fn launch_flags_and_defaults() {
+    let Command::Launch(args) = invoke(&["launch", "生存服"]).command else {
+        panic!("应为 launch");
+    };
+    assert_eq!(args.instance, "生存服");
+    assert!(!args.dry_run);
+    assert_eq!(args.java, None);
+    assert_eq!(args.max_memory, None);
+
+    let Command::Launch(args) = invoke(&[
+        "launch",
+        "生存服",
+        "--dry-run",
+        "--java",
+        "/opt/jdk/bin/java",
+        "--username",
+        "Steve",
+        "--max-memory",
+        "4096",
+    ])
+    .command
+    else {
+        panic!("应为 launch");
+    };
+    assert!(args.dry_run);
+    assert_eq!(args.username.as_deref(), Some("Steve"));
+    assert_eq!(args.max_memory, Some(4096));
+}
+
+#[test]
+fn accounts_subcommands() {
+    assert_eq!(invoke(&["accounts"]).command, Command::AccountsList);
+    assert_eq!(invoke(&["accounts", "list"]).command, Command::AccountsList);
+
+    let Command::AccountsAdd(args) = invoke(&["accounts", "add", "offline", "Steve"]).command
+    else {
+        panic!("应为 accounts add offline");
+    };
+    assert_eq!(args.kind, AccountsAddKind::Offline);
+    assert_eq!(args.name.as_deref(), Some("Steve"));
+
+    let Command::AccountsAdd(args) = invoke(&["accounts", "add", "msa"]).command else {
+        panic!("应为 accounts add msa");
+    };
+    assert_eq!(args.kind, AccountsAddKind::Microsoft);
+    assert_eq!(args.name, None);
+
+    let Command::AccountsRemove { name } = invoke(&["accounts", "remove", "Steve"]).command else {
+        panic!("应为 accounts remove");
+    };
+    assert_eq!(name, "Steve");
+}
+
+#[test]
+fn launch_account_flag() {
+    let Command::Launch(args) = invoke(&["launch", "生存服", "--account", "Steve"]).command
+    else {
+        panic!("应为 launch");
+    };
+    assert_eq!(args.account.as_deref(), Some("Steve"));
+    assert_eq!(args.username, None);
+}
+
+#[test]
+fn logs_and_diag_default_tails() {
+    let Command::Logs(args) = invoke(&["logs", "abc"]).command else {
+        panic!("应为 logs");
+    };
+    assert_eq!(args.tail, 200);
+
+    let Command::Diag(args) = invoke(&["diag", "abc", "--tail", "10"]).command else {
+        panic!("应为 diag");
+    };
+    assert_eq!(args.tail, 10);
+}
+
+#[test]
+fn config_get_set_forms() {
+    let Command::ConfigGet(args) = invoke(&["config", "get"]).command else {
+        panic!("应为 config get");
+    };
+    assert_eq!(args.key, None);
+    assert!(!args.show_secret);
+
+    let Command::ConfigGet(args) =
+        invoke(&["config", "get", "ui.language", "--show-secret"]).command
+    else {
+        panic!("应为 config get");
+    };
+    assert_eq!(args.key.as_deref(), Some("ui.language"));
+    assert!(args.show_secret);
+
+    let Command::ConfigSet(args) = invoke(&["config", "set", "ui.language", "en_us"]).command
+    else {
+        panic!("应为 config set");
+    };
+    assert_eq!(args.key, "ui.language");
+    assert_eq!(args.value, "en_us");
+}
+
+#[test]
+fn java_subcommands() {
+    assert_eq!(invoke(&["java"]).command, Command::JavaList);
+    assert_eq!(invoke(&["java", "list"]).command, Command::JavaList);
+    assert_eq!(
+        invoke(&["java", "install", "21"]).command,
+        Command::JavaInstall {
+            major: 21,
+            vendor: None
+        }
+    );
+    // D23：`--vendor` 钉死发行版（别名也认），`java vendors` 列出四家。
+    assert_eq!(
+        invoke(&["java", "install", "21", "--vendor", "oracle"]).command,
+        Command::JavaInstall {
+            major: 21,
+            vendor: Some(unlucky_core::game::java::JdkVendor::Oracle),
+        }
+    );
+    assert_eq!(
+        invoke(&["java", "install", "17", "--vendor", "adoptium"]).command,
+        Command::JavaInstall {
+            major: 17,
+            vendor: Some(unlucky_core::game::java::JdkVendor::Temurin),
+        }
+    );
+    assert_eq!(invoke(&["java", "vendors"]).command, Command::JavaVendors);
+}
+
+#[test]
+fn usage_errors_are_user_errors() {
+    let cases: &[&[&str]] = &[
+        &["frobnicate"],
+        &["install"],
+        &["launch"],
+        &["launch", "a", "b"],
+        &["instances", "list", "--nope"],
+        &["install", "1.20.1", "--dry-run=1"],
+        &["config", "set", "only-key"],
+        &["java", "install", "abc"],
+        &["--data-dir"],
+        &["sessions", "watch"],
+        &["accounts", "add"],
+        &["accounts", "add", "offline"],
+        &["accounts", "add", "authlib"],
+        &["accounts", "remove"],
+        &["accounts", "frobnicate"],
+    ];
+    for args in cases {
+        let owned: Vec<String> = args.iter().map(|arg| arg.to_string()).collect();
+        let error = parse(&owned).unwrap_err();
+        assert_eq!(error.kind(), ErrorKind::User, "args={args:?}");
+        assert_eq!(error.exit_code(), 1, "args={args:?}");
+    }
+}
+
+#[test]
+fn value_flags_do_not_swallow_the_next_flag() {
+    // P2-2：漏了值的写法必须在解析期报用法错误，而不是把 `--dry-run` 当成 Java 路径。
+    let cases: &[&[&str]] = &[
+        &["launch", "x", "--java", "--dry-run"],
+        &["launch", "x", "--username", "--json"],
+        &["install", "1.20.1", "--name", "--loader", "fabric"],
+        &["install", "1.20.1", "--loader", "--name", "x"],
+        &["logs", "abc", "--tail", "--json"],
+        &["--data-dir", "--json", "instances", "list"],
+    ];
+    for args in cases {
+        let owned: Vec<String> = args.iter().map(|arg| arg.to_string()).collect();
+        let error = parse(&owned).expect_err(&format!("args={args:?} 应当报用法错误"));
+        assert_eq!(error.code(), "usage", "args={args:?}");
+        assert!(
+            error.message().contains("需要一个值"),
+            "args={args:?} message={}",
+            error.message()
+        );
+    }
+
+    // 负数值与正常值不受影响（只拒 `--` 开头的 token）。
+    let Command::Launch(args) = invoke(&["launch", "x", "--java", "/opt/jdk/bin/java"]).command
+    else {
+        panic!("应为 launch");
+    };
+    assert_eq!(
+        args.java.as_deref(),
+        Some(std::path::Path::new("/opt/jdk/bin/java"))
+    );
+}
+
+#[test]
+fn help_text_covers_every_command() {
+    for topic in [
+        "instances",
+        "install",
+        "launch",
+        "sessions",
+        "logs",
+        "diag",
+        "config",
+        "java",
+    ] {
+        assert!(
+            unlucky_cli::cli::help::topic(topic).is_some(),
+            "缺少 {topic} 的帮助"
+        );
+    }
+    assert!(unlucky_cli::cli::help::topic("nope").is_none());
+}
diff --git a/crates/cli/tests/support/mod.rs b/crates/cli/tests/support/mod.rs
new file mode 100644
index 0000000..a14e011
--- /dev/null
+++ b/crates/cli/tests/support/mod.rs
@@ -0,0 +1,159 @@
+//! 集成测试共用夹具：临时数据根、命令执行器、最小版本 JSON / 会话索引。
+//!
+//! 每个测试目标都会整份编译本文件但只用其中一部分，因此这里放开 dead_code。
+#![allow(dead_code)]
+
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+/// 一次性临时目录（`Drop` 时清理）。
+pub struct TempDir {
+    path: PathBuf,
+}
+
+impl TempDir {
+    /// 建一个唯一目录。
+    pub fn new(tag: &str) -> Self {
+        static COUNTER: AtomicU64 = AtomicU64::new(0);
+        let nanos = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .map_or(0, |duration| duration.as_nanos());
+        let seq = COUNTER.fetch_add(1, Ordering::Relaxed);
+        let path = std::env::temp_dir().join(format!(
+            "ull-cli-test-{tag}-{}-{seq}-{nanos}",
+            std::process::id()
+        ));
+        std::fs::create_dir_all(&path).expect("创建临时目录");
+        Self { path }
+    }
+
+    /// 目录路径。
+    pub fn path(&self) -> &Path {
+        &self.path
+    }
+
+    /// 目录的字符串形式（喂给 `--data-dir`）。
+    pub fn arg(&self) -> String {
+        self.path.display().to_string()
+    }
+}
+
+impl Drop for TempDir {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.path);
+    }
+}
+
+/// 跑一次 CLI，返回（退出码, stdout, stderr）。
+pub fn run_cli(args: &[&str]) -> (i32, String, String) {
+    let owned: Vec<String> = args.iter().map(|arg| arg.to_string()).collect();
+    let mut out: Vec<u8> = Vec::new();
+    let mut err: Vec<u8> = Vec::new();
+    let code = unlucky_cli::run(&owned, &mut out, &mut err);
+    (
+        code,
+        String::from_utf8_lossy(&out).into_owned(),
+        String::from_utf8_lossy(&err).into_owned(),
+    )
+}
+
+/// 解析 `--json` 输出（断言它是合法 JSON 并返回）。
+pub fn parse_json(stdout: &str) -> serde_json::Value {
+    serde_json::from_str(stdout).unwrap_or_else(|error| panic!("输出不是 JSON：{error}\n{stdout}"))
+}
+
+/// 写一份最小可组装的新版版本 JSON + 空 client jar。
+pub fn write_version(data_root: &Path, id: &str) {
+    let dir = data_root.join(".minecraft").join("versions").join(id);
+    std::fs::create_dir_all(&dir).expect("创建版本目录");
+    let version = serde_json::json!({
+        "id": id,
+        "type": "release",
+        "mainClass": "net.minecraft.client.main.Main",
+        "assets": "5",
+        "assetIndex": { "id": "5" },
+        "arguments": {
+            "game": ["--username", "${auth_player_name}", "--version", "${version_name}"],
+            "jvm": ["-Djava.library.path=${natives_directory}", "-cp", "${classpath}"]
+        },
+        "libraries": [],
+        "downloads": { "client": { "size": 4, "url": "http://example.invalid/client.jar" } }
+    });
+    std::fs::write(
+        dir.join(format!("{id}.json")),
+        serde_json::to_vec_pretty(&version).expect("序列化版本 JSON"),
+    )
+    .expect("写版本 JSON");
+    std::fs::write(dir.join(format!("{id}.jar")), b"junk").expect("写 client jar");
+}
+
+/// 写 `config/profiles.json`（实例名 → 版本 id）。
+pub fn write_profiles(data_root: &Path, profiles: &[(&str, &str)]) {
+    let dir = data_root.join(".ULL").join("config");
+    std::fs::create_dir_all(&dir).expect("创建配置目录");
+    let entries: Vec<serde_json::Value> = profiles
+        .iter()
+        .enumerate()
+        .map(|(index, (name, version))| {
+            serde_json::json!({
+                "id": format!("11111111-2222-4333-8444-{:012}", index + 1),
+                "name": name,
+                "version_id": version,
+            })
+        })
+        .collect();
+    let document = serde_json::json!({ "schema_version": 1, "profiles": entries });
+    std::fs::write(
+        dir.join("profiles.json"),
+        serde_json::to_vec_pretty(&document).expect("序列化 profiles.json"),
+    )
+    .expect("写 profiles.json");
+}
+
+/// 写一份「退出码 1 + OOM」的会话索引与事件流，返回会话 id。
+pub fn write_session(data_root: &Path) -> String {
+    let sid = "20261030T101500-abcdef";
+    let dir = data_root
+        .join(".ULL")
+        .join("data")
+        .join("agent")
+        .join("sessions")
+        .join("game");
+    std::fs::create_dir_all(&dir).expect("创建会话目录");
+    let events = [
+        serde_json::json!({"v":1,"seq":0,"ts":"2026-10-30T10:15:00Z","t_ms":0,"kind":"session_start","session_id":sid,"payload":{"instance_name":"生存服","game_version":"1.20.1"}}),
+        serde_json::json!({"v":1,"seq":1,"ts":"2026-10-30T10:15:02Z","t_ms":1500,"kind":"stdout","session_id":sid,"payload":{"line":"[main/INFO]: Loading Minecraft 1.20.1","level":"info"}}),
+        serde_json::json!({"v":1,"seq":2,"ts":"2026-10-30T10:15:05Z","t_ms":4200,"kind":"stderr","session_id":sid,"payload":{"line":"java.lang.OutOfMemoryError: Java heap space","level":"error"}}),
+    ];
+    let mut text = String::new();
+    for event in events {
+        text.push_str(&serde_json::to_string(&event).expect("序列化事件"));
+        text.push('\n');
+    }
+    std::fs::write(dir.join(format!("{sid}.jsonl")), text).expect("写事件流");
+    let entry = serde_json::json!({
+        "v": 1,
+        "session_id": sid,
+        "instance_id": "11111111-2222-4333-8444-555555555555",
+        "instance_name": "生存服",
+        "game_version": "1.20.1",
+        "started_at": "2026-10-30T10:15:00Z",
+        "ended_at": "2026-10-30T10:15:06Z",
+        "duration_ms": 5000,
+        "exit_code": 1,
+        "exit_type": "application_error",
+        "silent_failure": false,
+        "window_detected": false,
+        "event_count": 3,
+        "log_path": format!("{sid}.jsonl"),
+        "crash_found": false,
+        "diagnosis_top": null
+    });
+    std::fs::write(
+        dir.join("index.jsonl"),
+        format!("{}\n", serde_json::to_string(&entry).expect("序列化索引")),
+    )
+    .expect("写会话索引");
+    sid.to_string()
+}
diff --git a/crates/core/Cargo.toml b/crates/core/Cargo.toml
new file mode 100644
index 0000000..d39441e
--- /dev/null
+++ b/crates/core/Cargo.toml
@@ -0,0 +1,74 @@
+[package]
+name = "unlucky-core"
+description = "Unlucky-Launcher 领域库：纯逻辑，零 UI 依赖（D3 架构纪律）"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+publish.workspace = true
+
+# 零 UI 依赖是硬约束：这里只允许纯逻辑/协议/IO 类依赖（serde/tokio/reqwest 等后续按模块加），
+# 任何时候都不得出现 slint / egui / iced / winit / gtk / javafx —— CI 的 core-no-ui job 守门。
+[dependencies]
+# M15（core::diagnose）预接线：59 条规则正则、规则 YAML 解析、诊断输出序列化。
+# 真正使用方是 crates/core/src/diagnose/ 下的 collectors/engine/hs_err/loader/rules（M15 落地）。
+regex.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+serde_yaml_ng.workspace = true
+
+# M13（core::download）预接线：HTTP / 异步运行时 / 流 / 哈希校验。
+reqwest.workspace = true
+tokio.workspace = true
+futures-util.workspace = true
+sha1.workspace = true
+sha2.workspace = true
+zip.workspace = true
+# M31（core::auth）：离线 UUID = MD5 v3（与 HMCL / 服务端 nameUUIDFromBytes 对拍）。
+md-5.workspace = true
+# M33（core::game::java）预接线：tar.gz 解压（Temurin 的 Linux/macOS 产物）。
+flate2.workspace = true
+tar.workspace = true
+
+# M13 的 8 个下载测试 target（文件由 M13 阶段 B 用真实用例覆盖；脚手架期是占位）。
+# `tests/download/support/mod.rs` 是被各 test include 的公共夹具，不单独注册。
+[[test]]
+name = "backoff"
+path = "tests/download/backoff_test.rs"
+
+[[test]]
+name = "health"
+path = "tests/download/health_test.rs"
+
+[[test]]
+name = "mirrors"
+path = "tests/download/mirrors_test.rs"
+
+[[test]]
+name = "region"
+path = "tests/download/region_test.rs"
+
+[[test]]
+name = "cache"
+path = "tests/download/cache_test.rs"
+
+[[test]]
+name = "chunked"
+path = "tests/download/chunked_test.rs"
+
+[[test]]
+name = "resume"
+path = "tests/download/resume_test.rs"
+
+[[test]]
+name = "engine_mock"
+path = "tests/download/engine_mock_test.rs"
+
+[[test]]
+name = "partfile"
+path = "tests/download/partfile_test.rs"
+
+[lints]
+workspace = true
diff --git a/crates/core/src/addon/export.rs b/crates/core/src/addon/export.rs
new file mode 100644
index 0000000..7068744
--- /dev/null
+++ b/crates/core/src/addon/export.rs
@@ -0,0 +1,65 @@
+//! 整合包**导出**（M112）：实例目录 → `.mrpack`（优先）/ CurseForge `manifest.json`（次之）。
+//!
+//! 设计依据：`DevDocs/PlanDoc/08-mod-and-recommend.md` §2（D10）、
+//! `DevDocs/SubAgentsTalk/addon-整合包导入导出对接要点.md` §4（导出八条），格式模型与安全闸
+//! 是 M110 的 [`crate::addon::pack`]，本模块**只消费，不重写**。
+//!
+//! # 一句话口径：不认识的 mod 不能丢、不能编
+//!
+//! 用户原话（M112 任务书）：「要么能证明它可被远程替代，要么就必须内联进 `overrides/` 并在
+//! 结果里逐条报告」。落到代码就是三分类，**没有第四类**：
+//!
+//! | 分类 | 判据 | 产物 |
+//! |------|------|------|
+//! | 远程引用（[`FileClass::Remote`]） | 目标格式**能表达**它 + 某个目录（[`RemoteCatalog`]）**能证明**它的身份 | 清单 `files[]` 一条 |
+//! | 内联（[`FileClass::Inline`]） | 证明不了，或证明了但目标格式表达不了 | 进 `overrides/`，原字节照搬 |
+//! | 跳过（[`FileClass::Skipped`]） | 读不了 / 是符号链接 / 路径不安全 | 不写进包，**逐条**进报告 |
+//!
+//! 「能证明」用两条独立查询（契约 §4.4 的顺序）：**Modrinth SHA-1** →
+//! [`RemoteCatalog::modrinth_by_sha1`]；**CurseForge 指纹**（[`crate::addon::pack::curseforge::fingerprint`]）
+//! → [`RemoteCatalog::curseforge_by_fingerprint`]。两条都命中时两条直链都进 `downloads[]`
+//! （HMCL 同款，兼容面更大）。**没有网络时**用 [`OfflineCatalog`]：所有文件都内联，包照样完整可导入
+//! ——这不是降级失败，是"证明不了就内联"的正面行为。
+//!
+//! # 每条格式决策落在哪（tower 定案，别按任务书原话改回去）
+//!
+//! 1. **`.disabled` 走路径后缀**（`mods/x.jar.disabled`），不是 `env.client=optional`：后者只是
+//!    "安装时可取消勾选"，装回来默认仍然启用 ⇒ 跨启动器不保真。官方 Modrinth 导出也是后缀。
+//! 2. **覆盖目录一律 `overrides/`**（不用 HMCL 那套 `client-overrides/`）：Modrinth 官方与
+//!    Prism 都用它，兼容面最大。分侧语义在本轮导出里不产生（实例目录本身不分侧）。
+//! 3. **`game` + `dependencies` 从实例快照取**，绝不只写 `minecraft` 漏加载器：快照来自
+//!    `versions/<id>/<id>.json` 的继承链 + 库坐标（[`snapshot`]），**不解析**
+//!    `<mc>-<loader>-<ver>` 这类实例 id 字符串（社区实例名不统一，那是猜）。
+//! 4. **CF `files[]` 只写能确定 `projectID`/`fileID` 的项**：CF 没有"内联到 files[]"的概念，
+//!    证明不了的（以及**禁用文件**：CF 根本没有禁用表达）一律进 `overrides/` 并进报告。
+//! 5. **尺寸护栏**：`fileSize` 是 u32（超了报 `pack_limits`，不静默截断）、整包撞 ZIP64 阈值由
+//!    `format::write` 拒绝（`pack_limits`，不留半个包）。
+//!
+//! # 刻意不做的事（分工边界，别以为是漏做）
+//!
+//! - **MultiMC / Prism 导出**：不做（P1 只做导入）。它的包是"整实例快照"，要先把所有远程文件
+//!   下载下来再打包，成本极高；导入侧 M111 已覆盖。**这是有意省略。**
+//! - **不装加载器 / 不补全清单**：加载器元数据解析与库下载是 `addon::loader` + `game::install`；
+//!   CF 的 `projectID/fileID → 文件名/URL` 补全需要 CF 客户端（D10 §5 规划中），本轮由调用方注入
+//!   [`RemoteCatalog`]，本模块不发网络请求。
+//! - **不碰 UI 类型**：core 零 UI 依赖（`core-no-ui` 门禁），报告只出现 `String` / `&'static str`。
+//! - **不改实例**：导出只读实例目录。
+//!
+//! # 没验的部分（报告里同样登记）
+//!
+//! 真实 Modrinth / CurseForge API 查询（要网络与 key，`RemoteCatalog` 目前只有离线实现）、
+//! 超大实例（GB 级、上千文件——指纹要对每个文件多读两遍）、Windows 之外的平台、
+//! 以及「M111 合并后的 `import_pack → export → import_pack` 真端到端」。
+
+pub mod catalog;
+pub(crate) mod classify;
+pub mod pipeline;
+pub mod report;
+pub mod scan;
+pub mod snapshot;
+
+pub use catalog::{OfflineCatalog, RemoteCatalog, RemoteHit, RemoteSource};
+pub use pipeline::{export_instance, ExportRequest};
+pub use report::{ExportFile, ExportReport, FileClass, FileReason};
+pub use scan::{scan_instance, LocalFile, SkippedLocal, DEFAULT_CONTENT_ROOTS, OVERRIDES_DIR};
+pub use snapshot::{read_instance_snapshot, InstanceSnapshot, SnapshotLoader};
diff --git a/crates/core/src/addon/export/catalog.rs b/crates/core/src/addon/export/catalog.rs
new file mode 100644
index 0000000..6147886
--- /dev/null
+++ b/crates/core/src/addon/export/catalog.rs
@@ -0,0 +1,147 @@
+//! 「能否被远程替代」的**注入点**：两条查询 + 一个离线默认实现。
+//!
+//! # 为什么是 trait 而不是直接调 API
+//!
+//! 与 M111 的 `PackFetcher` 同一条理由：测试不能联网；CF 的查表要 `x-api-key`（D10 §5 的客户端
+//! 还没写）；而"证明不了"必须能被如实表达——查表失败 ≠ 文件有问题。所以导出管线只认这个 trait，
+//! 生产实现将来接 Modrinth `/v2/version_file/{sha1}` 与 CF `/v1/fingerprints/432`。
+//!
+//! # 两条查询的语义差别（别合并成一个）
+//!
+//! | 查询 | 键 | 命中能给出什么 | 谁用得上 |
+//! |------|-----|----------------|----------|
+//! | [`RemoteCatalog::modrinth_by_sha1`] | 文件 SHA-1 | `downloads[]` + `hashes`（含 `sha512`）+ `fileSize` | mrpack（它要求 sha512） |
+//! | [`RemoteCatalog::curseforge_by_fingerprint`] | CF 指纹 | `projectID`/`fileID`（+ 可选直链） | CF 清单（它只认这两个 id） |
+//!
+//! 只命中一条时，另一格式通常用不上它——这正是 [`crate::addon::export::report::FileReason`]
+//! 要区分 `CurseOnlyMatch` / `ModrinthOnlyMatch` 的原因：报告要说清"证明了，但目标格式表达不了"，
+//! 而不是笼统地写"找不到"。
+//!
+//! # 哨兵值
+//!
+//! CF 指纹 `811513880` 会误命中（HMCL issue #4597），由**调用方**在建表前短路：
+//! 见 `curseforge::fingerprint::is_sentinel`。
+
+use std::collections::BTreeMap;
+
+/// 这条命中来自哪个目录。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RemoteSource {
+    /// Modrinth（按 SHA-1 查）。
+    Modrinth,
+    /// CurseForge（按文件指纹查）。
+    CurseForge,
+}
+
+/// 一次远程命中的结果。
+///
+/// 字段刻意按"能写进目标清单"组织，而不是按某个 API 的响应形状：
+/// mrpack 要 `downloads` + `hashes`，CF 要 `projectID`/`fileID`，两个都给了就是两份清单都能写。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RemoteHit {
+    /// 来源目录。
+    pub source: RemoteSource,
+    /// 直链候选（多源；mrpack 写进 `downloads[]`，CF 清单没有这个字段但也留着做日志）。
+    pub downloads: Vec<String>,
+    /// 摘要表（键名小写）。Modrinth 侧必须含 `sha1` 与 `sha512`——后者是 mrpack 的硬要求。
+    pub hashes: BTreeMap<String, String>,
+    /// 服务端记录的文件字节数（与本地实际字节数不一致时以本地为准，见 `pipeline`）。
+    pub size: Option<u64>,
+    /// CurseForge `projectID`。
+    pub project_id: Option<i64>,
+    /// CurseForge `fileID`。
+    pub file_id: Option<i64>,
+}
+
+impl RemoteHit {
+    /// 一次 Modrinth 命中：直链 + 摘要表（必须有 `sha512`，否则 mrpack 写不出来）。
+    #[must_use]
+    pub fn modrinth(
+        downloads: Vec<String>,
+        hashes: BTreeMap<String, String>,
+        size: Option<u64>,
+    ) -> Self {
+        Self {
+            source: RemoteSource::Modrinth,
+            downloads,
+            hashes,
+            size,
+            project_id: None,
+            file_id: None,
+        }
+    }
+
+    /// 一次 CurseForge 命中：`projectID`/`fileID` 是 CF 清单的**全部**必需信息。
+    #[must_use]
+    pub fn curseforge(project_id: i64, file_id: i64) -> Self {
+        Self {
+            source: RemoteSource::CurseForge,
+            downloads: Vec::new(),
+            hashes: BTreeMap::new(),
+            size: None,
+            project_id: Some(project_id),
+            file_id: Some(file_id),
+        }
+    }
+
+    /// 顺带给一条 CF 直链（有就写进 `downloads[]`，没有也不影响 CF 清单）。
+    #[must_use]
+    pub fn with_download(mut self, url: impl Into<String>) -> Self {
+        self.downloads.push(url.into());
+        self
+    }
+
+    /// `hashes.sha512`。
+    #[must_use]
+    pub fn sha512(&self) -> Option<&str> {
+        self.hashes.get("sha512").map(String::as_str)
+    }
+
+    /// 能不能写进 CF 的 `files[]`。
+    #[must_use]
+    pub fn curse_ids(&self) -> Option<(i64, i64)> {
+        match (self.project_id, self.file_id) {
+            (Some(project), Some(file)) => Some((project, file)),
+            _ => None,
+        }
+    }
+
+    /// 有没有能写进 mrpack 的 `downloads[]` 的非空直链。
+    #[must_use]
+    pub fn has_download(&self) -> bool {
+        self.downloads.iter().any(|url| !url.trim().is_empty())
+    }
+}
+
+/// 「这个文件在远端是谁」的查询接口。
+///
+/// 两个方法都必须**只做本地判据 + 调用方给的缓存**：实现里如果联网，那就是生产的
+/// Modrinth/CF 客户端（D10 §5），本模块不关心它怎么拿到答案。
+pub trait RemoteCatalog {
+    /// 按 SHA-1 查 Modrinth 版本文件；查不到返回 `None`（**不要**用 `None` 表示网络失败以外的
+    /// 「本地构造不了查询」——那种情况应当返回 `None` 并让文件内联）。
+    fn modrinth_by_sha1(&self, sha1: &str) -> Option<RemoteHit>;
+
+    /// 按 CurseForge 指纹查项目/文件；查不到返回 `None`。
+    ///
+    /// 调用方已按哨兵值（`811513880`）短路，实现不必重复判断。
+    fn curseforge_by_fingerprint(&self, fingerprint: u32) -> Option<RemoteHit>;
+}
+
+/// 离线：什么都证明不了 ⇒ 所有文件内联。
+///
+/// 这是**默认**行为，也是本仓库当前的唯一实现：没有 CF 客户端（要 key）、没有 Modrinth 客户端
+/// （D10 §5 规划中），联网查询在测试里也不允许。用它的导出结果是"一个完整、可导入、全部走
+/// `overrides/` 的包"——不是残废包。
+#[derive(Debug, Clone, Copy, Default)]
+pub struct OfflineCatalog;
+
+impl RemoteCatalog for OfflineCatalog {
+    fn modrinth_by_sha1(&self, _sha1: &str) -> Option<RemoteHit> {
+        None
+    }
+
+    fn curseforge_by_fingerprint(&self, _fingerprint: u32) -> Option<RemoteHit> {
+        None
+    }
+}
diff --git a/crates/core/src/addon/export/classify.rs b/crates/core/src/addon/export/classify.rs
new file mode 100644
index 0000000..e302331
--- /dev/null
+++ b/crates/core/src/addon/export/classify.rs
@@ -0,0 +1,112 @@
+//! 逐文件判定（导出管线的第 ③ 步）：这份本地文件在目标格式里能不能被远程替代。
+//!
+//! 判定要**两个条件同时成立**才算远程引用：
+//!
+//! 1. 某个目录（[`RemoteCatalog`]）能**证明**它的身份——Modrinth 按 SHA-1、CurseForge 按指纹；
+//! 2. 目标格式**表达得了**这个证明——mrpack 要 `path` + `sha512` + `downloads`，
+//!    CF 清单要 `projectID` + `fileID`。
+//!
+//! 只满足第一条时就是"证明了但用不上"，它有自己的原因（`CurseOnlyMatch` /
+//! `ModrinthOnlyMatch`），不能和"两个目录都不认识"混成一句话。
+//!
+//! 分成单独一个文件是为了让 [`super::pipeline`] 只讲流程；这里全是判据，可以逐条对着测
+//! （`classify_with` 甚至允许测试直接喂指纹——哨兵值 `811513880` 用真实文件测不出来）。
+
+use super::catalog::{RemoteCatalog, RemoteHit};
+use super::report::{ExportFile, FileReason};
+use super::scan::LocalFile;
+use crate::addon::pack::curseforge::fingerprint;
+use crate::addon::pack::manifest::{EnvSupport, PackFile};
+
+/// 判定一条本地文件属于哪一类（外加命中，供组 `files[]` 用）。
+pub(super) fn classify(
+    local: &LocalFile,
+    catalog: &dyn RemoteCatalog,
+    target_is_curse: bool,
+) -> (FileReason, Option<RemoteHit>) {
+    // 指纹要读两遍盘；读不出来就按"没有 CF 侧证据"处理（文件本身仍会内联进包）。
+    let value = fingerprint::fingerprint_file(&local.disk).ok();
+    classify_with(local, catalog, target_is_curse, value)
+}
+
+/// 同 [`classify`]，但指纹由调用方给（`None` = 读不出来）。
+///
+/// `pub(crate)` 只有一个理由：哨兵值 `811513880` 那条分支**没法用真实文件测**——它是误命中，
+/// 找不到一个能算出它的样本（要 2^32 次穷举）。测试直接喂这个数，验证它被当成"查不到"。
+pub(crate) fn classify_with(
+    local: &LocalFile,
+    catalog: &dyn RemoteCatalog,
+    target_is_curse: bool,
+    fingerprint: Option<u32>,
+) -> (FileReason, Option<RemoteHit>) {
+    let modrinth = catalog.modrinth_by_sha1(&local.sha1);
+    let curseforge = match fingerprint {
+        Some(value) if !fingerprint::is_sentinel(value) => catalog.curseforge_by_fingerprint(value),
+        Some(_) | None => None,
+    };
+    if target_is_curse {
+        if local.disabled {
+            // CF 没有禁用表达：`required:false` 是"可选"不是"禁用"，硬写就等于把它变成启用。
+            return (FileReason::DisabledNotExpressible, None);
+        }
+        return match curseforge {
+            Some(hit) if hit.curse_ids().is_some() => {
+                (FileReason::CurseForgeFingerprint, Some(hit))
+            }
+            Some(_) => (FileReason::MissingCurseIds, None),
+            None if modrinth.is_some() => (FileReason::ModrinthOnlyMatch, None),
+            None => (FileReason::NoRemoteMatch, None),
+        };
+    }
+    match modrinth {
+        Some(hit) if hit.sha512().is_some() && hit.has_download() => {
+            let mut merged = hit;
+            // 两条都命中：两条直链都写进 downloads[]（HMCL 同款，兼容面更大）。
+            if let Some(curse) = curseforge {
+                for url in curse.downloads {
+                    if !url.trim().is_empty() && !merged.downloads.iter().any(|seen| seen == &url) {
+                        merged.downloads.push(url);
+                    }
+                }
+                merged.project_id = merged.project_id.or(curse.project_id);
+                merged.file_id = merged.file_id.or(curse.file_id);
+            }
+            (FileReason::ModrinthSha1, Some(merged))
+        }
+        Some(_) => (FileReason::MissingSha512, None),
+        None if curseforge.is_some() => (FileReason::CurseOnlyMatch, None),
+        None => (FileReason::NoRemoteMatch, None),
+    }
+}
+
+/// 远程条目：`path` 用实例内路径（禁用文件已带 `.disabled` 后缀），`size` 用本地实测字节数。
+pub(super) fn remote_entry(local: &LocalFile, hit: &RemoteHit) -> PackFile {
+    let mut hashes = hit.hashes.clone();
+    hashes.insert("sha1".to_string(), local.sha1.clone());
+    PackFile {
+        path: Some(local.path.clone()),
+        project_id: hit.project_id,
+        file_id: hit.file_id,
+        hashes,
+        downloads: hit.downloads.clone(),
+        size: Some(local.bytes),
+        disabled: local.disabled,
+        client: EnvSupport::Required,
+        server: EnvSupport::Required,
+        ..PackFile::default()
+    }
+}
+
+/// 报告里的一条。
+pub(super) fn entry(local: &LocalFile, reason: FileReason, hit: Option<&RemoteHit>) -> ExportFile {
+    ExportFile {
+        path: local.path.clone(),
+        class: reason.class(),
+        reason,
+        bytes: local.bytes,
+        downloads: hit.map(|hit| hit.downloads.clone()).unwrap_or_default(),
+        project_id: hit.and_then(|hit| hit.project_id),
+        file_id: hit.and_then(|hit| hit.file_id),
+        disabled: local.disabled,
+    }
+}
diff --git a/crates/core/src/addon/export/pipeline.rs b/crates/core/src/addon/export/pipeline.rs
new file mode 100644
index 0000000..89fc21c
--- /dev/null
+++ b/crates/core/src/addon/export/pipeline.rs
@@ -0,0 +1,310 @@
+//! 导出管线：实例目录 → 三分类 → 清单 + `overrides/` → 包。
+//!
+//! 顺序是写死的，每一步都可单独测：
+//!
+//! ```text
+//! ① 实例快照（snapshot）       versions/<id>/<id>.json 的继承链 + 库坐标 ⇒ game / dependencies
+//! ② 扫描（scan）               内容目录 → 路径 + 字节数 + SHA-1 + 禁用位；读不了的进跳过表
+//! ③ 逐文件判定（classify）     Modrinth SHA-1 → CF 指纹 → 目标格式能不能表达 ⇒ 远程 / 内联 / 跳过
+//! ④ 组模型                    files[] = 远程；overrides = 内联（统一 `overrides/`）
+//! ⑤ 写包                      走 M110 的 `PackFormat::write`（临时文件 + rename，失败不留半个包）
+//! ```
+//!
+//! # 判定为什么要"目标格式能力"参与
+//!
+//! 「能被远程替代」不是文件自己的属性，是**文件 + 目标格式**的属性：同一个文件，CF 认得
+//! `projectID/fileID` 就能写进 CF 的 `files[]`，但 mrpack 要 `sha512` 才写得出来；反过来
+//! mrpack 认可 Modrinth 直链，CF 清单却只认两个整数 id。所以
+//! [`crate::addon::export::report::FileReason`] 里 `CurseOnlyMatch` 与 `ModrinthOnlyMatch`
+//! 是两个不同的事实，不能合并成"没找到"。
+//!
+//! # 一条禁令
+//!
+//! **不猜**：目录没给命中就内联；命中缺必需字段（`sha512` / `projectID`）也内联；只有
+//! "两条硬要求都齐"才写进 `files[]`。这样导出的包在任何启动器里都能装出**同一份内容**，
+//! 最多是"该远程的走了内联"（体积大一点，内容不会变）。
+
+use std::collections::BTreeMap;
+use std::path::{Path, PathBuf};
+
+use serde_json::Map;
+
+use super::catalog::{OfflineCatalog, RemoteCatalog};
+use super::classify::{classify, entry, remote_entry};
+use super::report::{ExportFile, ExportReport, FileClass};
+use super::scan::{scan_instance, DEFAULT_CONTENT_ROOTS, OVERRIDES_DIR};
+use super::snapshot::{read_instance_snapshot, InstanceSnapshot};
+use crate::addon::pack::curseforge;
+use crate::addon::pack::error::{PackError, PackResult};
+use crate::addon::pack::format::{PackFormat, PackPayload};
+use crate::addon::pack::manifest::{
+    OverrideFile, PackLoader, PackManifest, PackOverrides, PackSide,
+};
+
+/// 包版本缺省值（CF `version` / mrpack `versionId` 都必填，调用方没给就用它）。
+pub const DEFAULT_VERSION: &str = "1.0.0";
+
+/// 默认目录（离线）：所有文件内联。
+static OFFLINE: OfflineCatalog = OfflineCatalog;
+
+/// 一次导出的输入。
+pub struct ExportRequest<'a> {
+    root: &'a Path,
+    target: &'a Path,
+    format: &'static dyn PackFormat,
+    name: Option<String>,
+    version: Option<String>,
+    version_id: Option<&'a str>,
+    content_roots: Option<Vec<String>>,
+    catalog: &'a dyn RemoteCatalog,
+    snapshot: Option<&'a InstanceSnapshot>,
+}
+
+impl<'a> ExportRequest<'a> {
+    /// 从 `root`（实例游戏目录）导出到 `target`，用 `format` 的清单形状。
+    ///
+    /// 默认：包名取目录名、版本 [`DEFAULT_VERSION`]、内容目录取 [`DEFAULT_CONTENT_ROOTS`]、
+    /// 目录用 [`OfflineCatalog`]（= 全部内联）。
+    #[must_use]
+    pub fn new(root: &'a Path, target: &'a Path, format: &'static dyn PackFormat) -> Self {
+        Self {
+            root,
+            target,
+            format,
+            name: None,
+            version: None,
+            version_id: None,
+            content_roots: None,
+            catalog: &OFFLINE,
+            snapshot: None,
+        }
+    }
+
+    /// 包名（写进清单 `name`）。
+    #[must_use]
+    pub fn with_name(mut self, name: impl Into<String>) -> Self {
+        self.name = Some(name.into());
+        self
+    }
+
+    /// 包版本（写进 CF `version` / mrpack `versionId`）。
+    #[must_use]
+    pub fn with_version(mut self, version: impl Into<String>) -> Self {
+        self.version = Some(version.into());
+        self
+    }
+
+    /// 实例绑定的版本 id；不给就要求 `versions/` 下只有一个版本。
+    #[must_use]
+    pub fn with_version_id(mut self, version_id: &'a str) -> Self {
+        self.version_id = Some(version_id);
+        self
+    }
+
+    /// 覆盖要扫的内容目录（默认 [`DEFAULT_CONTENT_ROOTS`]）。
+    #[must_use]
+    pub fn with_content_roots(mut self, roots: Vec<String>) -> Self {
+        self.content_roots = Some(roots);
+        self
+    }
+
+    /// 注入远端查表（默认离线：全部内联）。
+    #[must_use]
+    pub fn with_catalog(mut self, catalog: &'a dyn RemoteCatalog) -> Self {
+        self.catalog = catalog;
+        self
+    }
+
+    /// 直接给实例快照，跳过 `versions/<id>/<id>.json` 的读取。
+    ///
+    /// 用于两种实例：①**Prism / MultiMC 实例**（游戏目录里没有 `versions/`，快照只能从
+    /// `mmc-pack.json` 的组件表来，调用方用 `pack::multimc` 读出来再传）；②调用方已经解析过
+    /// 快照（UI 侧手里就有 profile + 加载器信息），不必再读一遍盘。
+    #[must_use]
+    pub fn with_snapshot(mut self, snapshot: &'a InstanceSnapshot) -> Self {
+        self.snapshot = Some(snapshot);
+        self
+    }
+}
+
+/// 导出一个实例。
+///
+/// # Errors
+///
+/// - `pack_unsupported`：实例里找不到唯一的版本 JSON / 目标格式表达不了布局；
+/// - `pack_metadata`：版本 JSON 坏了（继承成环、不是 JSON）；
+/// - `pack_limits`：单文件 `fileSize` 超 u32、或整包撞 ZIP64 阈值；
+/// - `pack_io`：读写盘失败（失败时目标路径不留半个包）。
+pub fn export_instance(request: &ExportRequest<'_>) -> PackResult<ExportReport> {
+    let snapshot = match request.snapshot {
+        Some(snapshot) => snapshot.clone(),
+        None => read_instance_snapshot(request.root, request.version_id)?,
+    };
+    let roots = request
+        .content_roots
+        .clone()
+        .unwrap_or_else(|| DEFAULT_CONTENT_ROOTS.map(str::to_string).to_vec());
+    let (locals, skipped) = scan_instance(request.root, &roots);
+
+    // CF 清单只认 projectID/fileID；mrpack 要 path + sha512 + downloads。
+    let target_is_curse = request.format.id() == curseforge::ID;
+    let mut manifest = build_manifest(request, &snapshot);
+    let mut entries: Vec<ExportFile> = Vec::with_capacity(locals.len() + skipped.len());
+    let mut overrides: Vec<OverrideFile> = Vec::new();
+    let mut sources: BTreeMap<String, PathBuf> = BTreeMap::new();
+
+    for local in &locals {
+        let (reason, hit) = classify(local, request.catalog, target_is_curse);
+        match reason.class() {
+            FileClass::Remote => {
+                let Some(hit) = hit else {
+                    // 判定逻辑的自我约束：Remote 必带命中。真走到这里说明分类函数被改坏了。
+                    return Err(PackError::unsupported(format!(
+                        "内部不一致：{} 被判为远程引用却没有命中",
+                        local.path
+                    )));
+                };
+                manifest.files.push(remote_entry(local, &hit));
+                entries.push(entry(local, reason, Some(&hit)));
+            }
+            FileClass::Inline => {
+                overrides.push(OverrideFile {
+                    path: local.path.clone(),
+                    sha1: local.sha1.clone(),
+                    size: local.bytes,
+                });
+                sources.insert(
+                    format!("{OVERRIDES_DIR}/{}", local.path),
+                    local.disk.clone(),
+                );
+                entries.push(entry(local, reason, None));
+            }
+            FileClass::Skipped => unreachable!("扫描阶段不会产出可导出项"),
+        }
+    }
+    // 跳过项照原样进报告（逐条给原因），不进包。
+    for item in &skipped {
+        entries.push(ExportFile {
+            path: item.path.clone(),
+            class: FileClass::Skipped,
+            reason: item.reason,
+            bytes: 0,
+            downloads: Vec::new(),
+            project_id: None,
+            file_id: None,
+            disabled: false,
+        });
+    }
+
+    if !overrides.is_empty() {
+        // 一律 `overrides/`（Modrinth 官方 + Prism 的写法）。实例目录不分侧，所以只有一个 Both 组。
+        manifest.overrides.push(PackOverrides {
+            dir: OVERRIDES_DIR.to_string(),
+            side: PackSide::Both,
+            files: overrides,
+        });
+    }
+
+    request.format.write(
+        &manifest,
+        PackPayload::with_sources(request.root, &sources),
+        request.target,
+    )?;
+    let bytes = std::fs::metadata(request.target)
+        .map_err(|error| {
+            PackError::io(format!(
+                "量 {} 的字节数失败：{error}",
+                request.target.display()
+            ))
+        })?
+        .len();
+
+    entries.sort_by(|left, right| left.path.cmp(&right.path));
+    let notes = notes(target_is_curse, &manifest);
+    Ok(ExportReport {
+        format: request.format.id(),
+        label: request.format.label(),
+        path: request.target.to_path_buf(),
+        bytes,
+        name: manifest.name.clone(),
+        version: manifest.version.clone(),
+        minecraft: manifest.minecraft.clone(),
+        loaders: manifest
+            .loaders
+            .iter()
+            .map(|loader| {
+                format!(
+                    "{} {}",
+                    loader.dependency_key(),
+                    loader.version.clone().unwrap_or_default()
+                )
+            })
+            .collect(),
+        files: entries,
+        notes,
+    })
+}
+
+/// 组清单：`game` / `minecraft` / `loaders` 全部来自实例快照。
+fn build_manifest(request: &ExportRequest<'_>, snapshot: &InstanceSnapshot) -> PackManifest {
+    let name = request
+        .name
+        .clone()
+        .or_else(|| {
+            request
+                .root
+                .file_name()
+                .map(|name| name.to_string_lossy().to_string())
+        })
+        .unwrap_or_else(|| "整合包".to_string());
+    let mut manifest = PackManifest::new(name);
+    manifest.version = Some(
+        request
+            .version
+            .clone()
+            .unwrap_or_else(|| DEFAULT_VERSION.to_string()),
+    );
+    manifest.format_version = Some(1);
+    manifest.game = Some(crate::addon::pack::modrinth::GAME.to_string());
+    manifest.minecraft = Some(snapshot.game_version.clone());
+    manifest.loaders = snapshot
+        .loaders
+        .iter()
+        .enumerate()
+        .map(|(index, loader)| PackLoader {
+            raw: String::new(),
+            kind: Some(loader.kind),
+            version: Some(loader.version.clone()),
+            primary: index == 0,
+            extra: Map::new(),
+        })
+        .collect();
+    manifest
+}
+
+/// 格式层面表达不了的东西（已知损失）——必须显式列出来，别让用户以为往返无损。
+fn notes(target_is_curse: bool, manifest: &PackManifest) -> Vec<String> {
+    let mut notes = vec![
+        "覆盖内容统一写进 `overrides/`（Modrinth 官方与 Prism 的写法）；实例目录不分侧，\
+         所以不产生 client-overrides / server-overrides。"
+            .to_string(),
+        "禁用文件用**路径后缀 `.disabled`** 表达（不是 `env.client=optional`：后者装回来默认启用）。"
+            .to_string(),
+        "MultiMC / Prism 导出本轮不做（只有导入），这是有意省略，不是遗漏。".to_string(),
+    ];
+    if target_is_curse {
+        notes.push("mrpack 的 `summary` 在 CF 清单里没有字段；CF 也只认 projectID/fileID，禁用文件只能内联。".to_string());
+    } else {
+        notes.push(
+            "CF 清单的 `author` / `manifestVersion` 之外的扩展字段在 mrpack 里没有对应位置。"
+                .to_string(),
+        );
+    }
+    if !manifest.files.is_empty() {
+        notes.push(format!(
+            "{} 条写进 files[]（远程引用），其余在 overrides/ 里；每条的原因见 files[].reason。",
+            manifest.files.len()
+        ));
+    }
+    notes
+}
diff --git a/crates/core/src/addon/export/report.rs b/crates/core/src/addon/export/report.rs
new file mode 100644
index 0000000..231570a
--- /dev/null
+++ b/crates/core/src/addon/export/report.rs
@@ -0,0 +1,235 @@
+//! 导出结果：**三分类 + 逐条原因**，给 CLI 的 `--json` 与 M113 的页面直接消费。
+//!
+//! # 为什么每条都要有原因
+//!
+//! 用户要的是「不认识的 mod 不能丢、不能编」。光说"导出了 120 个文件"会掩盖真正的信息：
+//! 其中多少条**能证明**可被远程替代、多少条**证明不了所以内联**、多少条**干脆没进包**。
+//! 所以 [`ExportFile`] 的 `class` 与 `reason` 是两个独立维度，且 `reason` 决定 `class`
+//! （[`FileReason::class`] 是唯一映射处，写死在这里，别在别处再判一遍）。
+//!
+//! # 「允许的差异」也进报告
+//!
+//! [`ExportReport::notes`] 收的是**格式层面表达不了**的东西（CF 的 `author`、mrpack 的
+//! `summary`、CF 表达不了禁用位……）。它们是已知损失，必须显式列出，不能让用户以为"往返无损"。
+
+use std::path::PathBuf;
+
+use serde::{Serialize, Serializer};
+
+/// 一条文件在导出结果里的归类。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum FileClass {
+    /// 写进清单 `files[]`（靠远端直链/项目 id 代替本地字节）。
+    Remote,
+    /// 写进 `overrides/`（原字节照搬）。
+    Inline,
+    /// 没进包（读不了 / 符号链接 / 路径不安全）。
+    Skipped,
+}
+
+impl FileClass {
+    /// 稳定字符串 id（进 `--json` 与日志，**不要改名**）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Remote => "remote",
+            Self::Inline => "inline",
+            Self::Skipped => "skipped",
+        }
+    }
+}
+
+impl Serialize for FileClass {
+    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        serializer.serialize_str(self.as_str())
+    }
+}
+
+/// 一条文件为什么归到那个类里。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum FileReason {
+    /// 远程引用：Modrinth SHA-1 查到了版本文件。
+    ModrinthSha1,
+    /// 远程引用：CurseForge 指纹查到了项目/文件。
+    CurseForgeFingerprint,
+    /// 内联：两个目录都不认识它。
+    NoRemoteMatch,
+    /// 内联：CF 认识，但目标格式（mrpack）用不上——CF 命中不含 `sha512`。
+    CurseOnlyMatch,
+    /// 内联：Modrinth 认识，但目标格式（CF 清单）只认 `projectID`/`fileID`。
+    ModrinthOnlyMatch,
+    /// 内联：目录给了命中但缺 `hashes.sha512`（mrpack 的硬要求）。
+    MissingSha512,
+    /// 内联：目录给了命中但缺 `projectID`/`fileID`（CF 清单的硬要求）。
+    MissingCurseIds,
+    /// 内联：文件是禁用的（`.disabled`），而目标格式表达不了禁用位（CF）。
+    DisabledNotExpressible,
+    /// 跳过：符号链接。
+    SymbolicLink,
+    /// 跳过：文件名过不了包内路径规整（`:` / `\` / `..` / 绝对路径…）。
+    UnsafePath,
+    /// 跳过：读盘或算摘要失败。
+    Unreadable,
+}
+
+impl FileReason {
+    /// 稳定字符串 id（进 `--json` 与日志，**不要改名**）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::ModrinthSha1 => "modrinth_sha1",
+            Self::CurseForgeFingerprint => "curseforge_fingerprint",
+            Self::NoRemoteMatch => "no_remote_match",
+            Self::CurseOnlyMatch => "curse_only_match",
+            Self::ModrinthOnlyMatch => "modrinth_only_match",
+            Self::MissingSha512 => "missing_sha512",
+            Self::MissingCurseIds => "missing_curse_ids",
+            Self::DisabledNotExpressible => "disabled_not_expressible",
+            Self::SymbolicLink => "symbolic_link",
+            Self::UnsafePath => "unsafe_path",
+            Self::Unreadable => "unreadable",
+        }
+    }
+
+    /// 人读说明（中文，进报告与日志；UI 文案后续按 key 本地化）。
+    #[must_use]
+    pub const fn label(self) -> &'static str {
+        match self {
+            Self::ModrinthSha1 => "Modrinth 命中（SHA-1）",
+            Self::CurseForgeFingerprint => "CurseForge 命中（文件指纹）",
+            Self::NoRemoteMatch => "两个目录都不认识，已内联",
+            Self::CurseOnlyMatch => "只有 CF 认识，目标格式用不上，已内联",
+            Self::ModrinthOnlyMatch => "只有 Modrinth 认识，CF 清单用不上，已内联",
+            Self::MissingSha512 => "命中缺 sha512，mrpack 写不出，已内联",
+            Self::MissingCurseIds => "命中缺 projectID/fileID，CF 清单写不出，已内联",
+            Self::DisabledNotExpressible => "禁用文件 CF 表达不了，已内联（保留 .disabled 后缀）",
+            Self::SymbolicLink => "符号链接，已跳过",
+            Self::UnsafePath => "路径过不了包内规整，已跳过",
+            Self::Unreadable => "读不出来，已跳过",
+        }
+    }
+
+    /// 这个原因属于哪一类（**唯一映射处**）。
+    #[must_use]
+    pub const fn class(self) -> FileClass {
+        match self {
+            Self::ModrinthSha1 | Self::CurseForgeFingerprint => FileClass::Remote,
+            Self::NoRemoteMatch
+            | Self::CurseOnlyMatch
+            | Self::ModrinthOnlyMatch
+            | Self::MissingSha512
+            | Self::MissingCurseIds
+            | Self::DisabledNotExpressible => FileClass::Inline,
+            Self::SymbolicLink | Self::UnsafePath | Self::Unreadable => FileClass::Skipped,
+        }
+    }
+}
+
+impl Serialize for FileReason {
+    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        serializer.serialize_str(self.as_str())
+    }
+}
+
+/// 一条文件的导出结果。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+pub struct ExportFile {
+    /// 实例内相对路径（含 `.disabled` 后缀，与磁盘上一致）。
+    pub path: String,
+    /// 归类。
+    pub class: FileClass,
+    /// 原因。
+    pub reason: FileReason,
+    /// 字节数（跳过项记磁盘上的大小，读不到就是 0）。
+    pub bytes: u64,
+    /// 远程引用给的直链（内联/跳过为空）。
+    pub downloads: Vec<String>,
+    /// CurseForge `projectID`（远程引用到 CF 时才有）。
+    pub project_id: Option<i64>,
+    /// CurseForge `fileID`。
+    pub file_id: Option<i64>,
+    /// 是否禁用态（`.disabled`）。
+    pub disabled: bool,
+}
+
+/// 一次导出的结构化结果。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+pub struct ExportReport {
+    /// 目标格式 id（`modrinth` / `curseforge`）。
+    pub format: &'static str,
+    /// 目标格式人读名。
+    pub label: &'static str,
+    /// 产出的包路径。
+    pub path: PathBuf,
+    /// 包的字节数（写完之后量的，不是估算）。
+    pub bytes: u64,
+    /// 包名（写进清单的 `name`）。
+    pub name: String,
+    /// 包版本（`versionId` / `version`）。
+    pub version: Option<String>,
+    /// 游戏版本（来自实例快照）。
+    pub minecraft: Option<String>,
+    /// 加载器（`fabric-loader 0.15.11` 这种人读串，来自实例快照）。
+    pub loaders: Vec<String>,
+    /// 逐文件结果（按路径排序）。
+    pub files: Vec<ExportFile>,
+    /// 已知的表达不了的差异 / 值得用户知道的取舍。
+    pub notes: Vec<String>,
+}
+
+impl ExportReport {
+    /// 远程引用的条数。
+    #[must_use]
+    pub fn remote_count(&self) -> usize {
+        self.count(FileClass::Remote)
+    }
+
+    /// 内联的条数。
+    #[must_use]
+    pub fn inline_count(&self) -> usize {
+        self.count(FileClass::Inline)
+    }
+
+    /// 跳过的条数。
+    #[must_use]
+    pub fn skipped_count(&self) -> usize {
+        self.count(FileClass::Skipped)
+    }
+
+    fn count(&self, class: FileClass) -> usize {
+        self.files.iter().filter(|file| file.class == class).count()
+    }
+
+    /// 有没有文件没进包（`false` = 包内容完整，只是有些走了内联）。
+    #[must_use]
+    pub fn is_complete(&self) -> bool {
+        self.skipped_count() == 0
+    }
+
+    /// 内联文件（`overrides/` 里的那些）。
+    pub fn inline_files(&self) -> impl Iterator<Item = &ExportFile> {
+        self.files
+            .iter()
+            .filter(|file| file.class == FileClass::Inline)
+    }
+
+    /// 不可导出的项（逐条给 `path` + `reason` 用）。
+    pub fn skipped_files(&self) -> impl Iterator<Item = &ExportFile> {
+        self.files
+            .iter()
+            .filter(|file| file.class == FileClass::Skipped)
+    }
+
+    /// 一句话摘要（日志/CLI 一行输出用）。
+    #[must_use]
+    pub fn summary(&self) -> String {
+        format!(
+            "{}：{} 个远程引用 / {} 个内联 / {} 个跳过，{} 字节",
+            self.label,
+            self.remote_count(),
+            self.inline_count(),
+            self.skipped_count(),
+            self.bytes
+        )
+    }
+}
diff --git a/crates/core/src/addon/export/scan.rs b/crates/core/src/addon/export/scan.rs
new file mode 100644
index 0000000..1b6e274
--- /dev/null
+++ b/crates/core/src/addon/export/scan.rs
@@ -0,0 +1,189 @@
+//! 实例目录扫描：把"磁盘上有什么"变成 [`LocalFile`] 表（路径 + 字节数 + SHA-1 + 禁用位）。
+//!
+//! # 扫哪些目录（写死白名单，不是"排除法"）
+//!
+//! 默认只扫 [`DEFAULT_CONTENT_ROOTS`] 这 8 个内容目录：`mods` / `config` / `defaultconfigs` /
+//! `scripts` / `resourcepacks` / `shaderpacks` / `kubejs` / `openloader`。
+//!
+//! 为什么用白名单而不是"排除 `versions/` `libraries/` `assets/`"：
+//!
+//! - 那三个目录是**启动器/游戏自己管的**（版本 JSON、依赖库、资源对象），塞进整合包只会让包
+//!   变成几 GB，且与"远程可替代"完全无关；
+//! - `journals` `logs/` `crash-reports/` `saves/` `screenshots/` `backups/` **不属于**整合包内容
+//!   （社区导出器一致不打包它们）；
+//! - 排除法是"忘了就漏"的写法：以后实例里出现新目录（`.mixin.out`、`essential`…）会被静默打进去。
+//!
+//! 白名单之外的东西**不是丢了**——它们本来就不该在整合包里。要打别的目录，用
+//! [`crate::addon::export::ExportRequest::with_content_roots`] 显式加。
+//!
+//! # 内容目录里的一切都收（认不出的 mod 不能丢）
+//!
+//! 白名单目录里**不按扩展名过滤**：`mods/` 下的 `.jar`、`.jar.disabled`、`.jar.old`、
+//! `.ds_store`、社区自造后缀，一律按文件收。丢掉"我不认识的东西"正是用户点名不许的。
+//!
+//! # 禁用它只看路径后缀
+//!
+//! `x.jar` / `x.jar.disabled` / `x.jar.old` / `x.jar.disabled.old` 四种里，含 `.disabled`
+//! （中间可能夹 `.old`）的才算禁用；`.old` 单独出现只是"旧版本残留"，原样保留、语义不变。
+//! 后缀**原样进包**——这是官方 Modrinth 导出的表达，也是唯一跨启动器保真的那条
+//! （`env.client=optional` 不是禁用，见 `crate::addon::pack::manifest::PackFile::disabled`）。
+//!
+//! # 安全
+//!
+//! 每条相对路径都要过 [`normalize_file`]（七条规则）才进表；不过的记
+//! [`SkipReason::UnsafePath`]。符号链接**不跟随**，记 [`SkipReason::SymbolicLink`]
+//! （导出包里出现符号链接条目，解压端会把它当内容写出来）。
+
+use std::path::{Path, PathBuf};
+
+use super::report::FileReason;
+use crate::addon::pack::path::{normalize_dir, normalize_file};
+use crate::download::types::HashAlgo;
+use crate::download::verify::digest_file;
+
+/// 包内唯一的覆盖目录名（Modrinth 官方与 Prism 都用它，兼容面最大）。
+pub const OVERRIDES_DIR: &str = "overrides";
+
+/// 默认扫的 8 个内容目录。
+pub const DEFAULT_CONTENT_ROOTS: [&str; 8] = [
+    "mods",
+    "config",
+    "defaultconfigs",
+    "scripts",
+    "resourcepacks",
+    "shaderpacks",
+    "kubejs",
+    "openloader",
+];
+
+/// 一个待判定的本地文件。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LocalFile {
+    /// 实例内相对路径（`/` 分隔，含 `.disabled` / `.old` 后缀，与磁盘上一致）。
+    pub path: String,
+    /// 磁盘上的绝对路径（导出时按这个读字节）。
+    pub disk: PathBuf,
+    /// 字节数。
+    pub bytes: u64,
+    /// 内容 SHA-1（小写十六进制）。
+    pub sha1: String,
+    /// 是否禁用态（路径后缀含 `.disabled`）。
+    pub disabled: bool,
+}
+
+/// 一个没能进包的文件，与它为什么没进。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SkippedLocal {
+    /// 实例内相对路径（过不了规整时给原始串）。
+    pub path: String,
+    /// 原因。
+    pub reason: FileReason,
+}
+
+/// 扫描一个实例目录，返回（可导出的文件表，跳过表），两张表都按路径排序。
+///
+/// 内容目录不存在不算错（空实例导出空包是合法的，只是报告里一个文件都没有）。
+#[must_use]
+pub fn scan_instance(root: &Path, content_roots: &[String]) -> (Vec<LocalFile>, Vec<SkippedLocal>) {
+    let mut files: Vec<LocalFile> = Vec::new();
+    let mut skipped: Vec<SkippedLocal> = Vec::new();
+
+    for content_root in content_roots {
+        let Ok(dir_name) = normalize_dir(content_root) else {
+            skipped.push(SkippedLocal {
+                path: content_root.clone(),
+                reason: FileReason::UnsafePath,
+            });
+            continue;
+        };
+        let start = root.join(&dir_name);
+        if !start.is_dir() {
+            continue;
+        }
+        // 迭代而不是递归：深度由磁盘决定，别让深层目录把栈吃掉。
+        let mut pending: Vec<PathBuf> = vec![start];
+        while let Some(dir) = pending.pop() {
+            let Ok(entries) = std::fs::read_dir(&dir) else {
+                skipped.push(SkippedLocal {
+                    path: relative_name(root, &dir),
+                    reason: FileReason::Unreadable,
+                });
+                continue;
+            };
+            let mut children: Vec<_> = entries.collect::<Result<Vec<_>, _>>().unwrap_or_default();
+            children.sort_by_key(std::fs::DirEntry::file_name);
+            for child in children {
+                let path = child.path();
+                let name = relative_name(root, &path);
+                let Ok(file_type) = child.file_type() else {
+                    skipped.push(SkippedLocal {
+                        path: name,
+                        reason: FileReason::Unreadable,
+                    });
+                    continue;
+                };
+                if file_type.is_symlink() {
+                    skipped.push(SkippedLocal {
+                        path: name,
+                        reason: FileReason::SymbolicLink,
+                    });
+                    continue;
+                }
+                if file_type.is_dir() {
+                    pending.push(path);
+                    continue;
+                }
+                if !file_type.is_file() {
+                    // 设备文件 / 管道 / 套接字：不是整合包内容。
+                    skipped.push(SkippedLocal {
+                        path: name,
+                        reason: FileReason::Unreadable,
+                    });
+                    continue;
+                }
+                let Ok(normalized) = normalize_file(&name) else {
+                    skipped.push(SkippedLocal {
+                        path: name,
+                        reason: FileReason::UnsafePath,
+                    });
+                    continue;
+                };
+                let bytes = child.metadata().map(|meta| meta.len()).unwrap_or(0);
+                let Ok(sha1) = digest_file(&path, HashAlgo::Sha1) else {
+                    skipped.push(SkippedLocal {
+                        path: normalized,
+                        reason: FileReason::Unreadable,
+                    });
+                    continue;
+                };
+                files.push(LocalFile {
+                    disabled: is_disabled_path(&normalized),
+                    path: normalized,
+                    disk: path,
+                    bytes,
+                    sha1,
+                });
+            }
+        }
+    }
+
+    files.sort_by(|left, right| left.path.cmp(&right.path));
+    skipped.sort_by(|left, right| left.path.cmp(&right.path));
+    (files, skipped)
+}
+
+/// 实例内相对路径（`/` 分隔）；拿不到就退回文件名。
+fn relative_name(root: &Path, path: &Path) -> String {
+    path.strip_prefix(root)
+        .unwrap_or(path)
+        .to_string_lossy()
+        .replace('\\', "/")
+}
+
+/// 路径后缀是否带 `.disabled`（允许 `x.jar.disabled.old` 这种"禁用 + 旧残留"组合）。
+#[must_use]
+pub fn is_disabled_path(path: &str) -> bool {
+    let lowered = path.trim_end().to_ascii_lowercase();
+    let without_old = lowered.strip_suffix(".old").unwrap_or(&lowered);
+    without_old.ends_with(".disabled")
+}
diff --git a/crates/core/src/addon/export/snapshot.rs b/crates/core/src/addon/export/snapshot.rs
new file mode 100644
index 0000000..c733a99
--- /dev/null
+++ b/crates/core/src/addon/export/snapshot.rs
@@ -0,0 +1,209 @@
+//! 实例快照：`game` 与 `dependencies` 的唯一来源（**不解析实例 id 字符串**）。
+//!
+//! # 为什么要读版本 JSON 而不是拆 `versions/<id>` 的名字
+//!
+//! 实例 id 的形状是社区约定，不是规范：`1.20.1-fabric-0.15.11`（本仓库 `LoaderKind::version_id`
+//! 的拼法）、`1.20.1-forge-47.2.0`、`Fabric 1.20.1`、`我的整合包 v3`……按 `-` 切串去猜
+//! "哪段是加载器、哪段是版本"必然在真实实例上翻车。**证据只能在版本 JSON 里**：
+//!
+//! - 游戏版本 = `inheritsFrom` 链**最深的那个祖先**的 `id`（加载器层都叠在原版之上）；
+//! - 加载器 = 各层 `libraries[]` 里的 Maven 坐标：`net.fabricmc:fabric-loader:<ver>`、
+//!   `org.quiltmc:quilt-loader:<ver>`、`net.minecraftforge:forge:<ver>`、
+//!   `net.neoforged:neoforge:<ver>`（`fmlloader` 也认，它是 Forge 的拆分包）。
+//!
+//! 这条口径由 tower 批准（M112）："解析 `<mc>-<loader>-<ver>` 字符串是猜"。
+//!
+//! # 版本号里的 MC 前缀
+//!
+//! NeoForge 在 MC 1.20.1 上的库坐标版本是 `1.20.1-47.1.106`（CF 导出的
+//! `neoforge-1.20.1-47.1.106` 同源）。这里统一剥成 `47.1.106`：mrpack 的
+//! `dependencies["neoforge"]` 要裸版本，CF 的 `modLoaders[].id` 由
+//! `PackLoader::curse_id_for` 在 1.20.1 上再把前缀拼回去。
+//!
+//! # 没有加载器是合法的
+//!
+//! 原版实例的 `dependencies` 只有 `minecraft`——那不是"漏了加载器"，是真的没装。任务书说的
+//! 「不得只写 `minecraft` 漏加载器」针对的是**装了加载器却漏写**，两者靠这条链区分得清清楚楚。
+
+use std::path::Path;
+
+use crate::addon::pack::error::{PackError, PackResult};
+use crate::addon::LoaderKind;
+use crate::game::library::MavenCoordinate;
+use crate::game::manifest::VersionJson;
+
+/// 实例里认出的一条加载器依赖。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SnapshotLoader {
+    /// 加载器种类。
+    pub kind: LoaderKind,
+    /// 加载器版本（已剥掉可能存在的 `<mc>-` 前缀）。
+    pub version: String,
+}
+
+/// 实例快照：游戏版本 + 加载器集合（顺序即 `libraries[]` 里出现的顺序）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct InstanceSnapshot {
+    /// 原版游戏版本（`1.20.1`）。
+    pub game_version: String,
+    /// 加载器依赖（原版实例为空）。
+    pub loaders: Vec<SnapshotLoader>,
+}
+
+/// 读一个实例目录的快照。
+///
+/// `version_id` 给定时只读 `versions/<id>/<id>.json`；`None` 时取 `versions/` 里**继承链的叶子**
+/// （真实实例有"原版 + 加载器层"两个目录，叶子才是实例自己）。叶子多于一个时无法判断，
+/// 宁可报错也不猜。
+pub fn read_instance_snapshot(
+    root: &Path,
+    version_id: Option<&str>,
+) -> PackResult<InstanceSnapshot> {
+    let versions_dir = root.join("versions");
+    let id = match version_id {
+        Some(id) => id.to_string(),
+        None => instance_version_id(&versions_dir)?,
+    };
+    let layers = load_chain(&versions_dir, &id)?;
+
+    let deepest = layers
+        .last()
+        .and_then(|layer| layer.id.clone())
+        .ok_or_else(|| {
+            PackError::metadata(format!("versions/{id}/{id}.json 的继承链末端没有 id"))
+        })?;
+
+    let mut loaders: Vec<SnapshotLoader> = Vec::new();
+    for layer in &layers {
+        for library in layer.libraries.iter().flatten() {
+            let Ok(coordinate) = MavenCoordinate::parse(&library.name) else {
+                continue;
+            };
+            let Some(kind) = loader_kind_of(&coordinate.group, &coordinate.artifact) else {
+                continue;
+            };
+            if loaders.iter().any(|seen| seen.kind == kind) {
+                continue;
+            }
+            loaders.push(SnapshotLoader {
+                kind,
+                version: strip_game_prefix(&deepest, &coordinate.version),
+            });
+        }
+    }
+
+    Ok(InstanceSnapshot {
+        game_version: deepest,
+        loaders,
+    })
+}
+
+/// `versions/` 下"这个实例"的版本 id：**继承链的叶子**（没有被别的版本当作 `inheritsFrom`）。
+///
+/// 为什么不是"只有一个版本目录"：真实实例必然有"原版 + 加载器层"两个目录（`1.20.1` 与
+/// `1.20.1-fabric-0.15.11`），叶子才是实例自己。这条判据不看目录名形状，只看 JSON 里的
+/// `inheritsFrom` 关系——与"不解析实例 id 字符串"是同一条纪律。
+fn instance_version_id(versions_dir: &Path) -> PackResult<String> {
+    let entries = std::fs::read_dir(versions_dir).map_err(|error| {
+        PackError::unsupported(format!(
+            "实例里没有可读的 {}：{error}",
+            versions_dir.display()
+        ))
+        .with_hint("导出需要实例的版本 JSON（versions/<id>/<id>.json 给出游戏版本与加载器）")
+    })?;
+    let mut versions: Vec<(String, Option<String>)> = Vec::new();
+    for entry in entries.flatten() {
+        let Ok(file_type) = entry.file_type() else {
+            continue;
+        };
+        if !file_type.is_dir() {
+            continue;
+        }
+        let name = entry.file_name().to_string_lossy().to_string();
+        let path = entry.path().join(format!("{name}.json"));
+        if !path.is_file() {
+            continue;
+        }
+        let text = std::fs::read_to_string(&path).map_err(|error| {
+            PackError::metadata(format!("读版本 JSON {} 失败：{error}", path.display()))
+        })?;
+        let layer: VersionJson = serde_json::from_str(&text).map_err(|error| {
+            PackError::metadata(format!("{} 不是合法版本 JSON：{error}", path.display()))
+        })?;
+        versions.push((name, layer.inherits_from));
+    }
+    if versions.is_empty() {
+        return Err(
+            PackError::unsupported("实例的 versions/ 下没有 <id>/<id>.json".to_string()).with_hint(
+                "先装好游戏/加载器再导出；导出需要版本 JSON 才能写 game 与 dependencies",
+            ),
+        );
+    }
+    let referenced: Vec<&str> = versions
+        .iter()
+        .filter_map(|(_, parent)| parent.as_deref())
+        .collect();
+    let mut leaves: Vec<String> = versions
+        .iter()
+        .filter(|(id, _)| !referenced.contains(&id.as_str()))
+        .map(|(id, _)| id.clone())
+        .collect();
+    leaves.sort();
+    match leaves.len() {
+        1 => Ok(leaves.remove(0)),
+        _ => Err(PackError::unsupported(format!(
+            "实例的 versions/ 下有 {} 条继承链末端（{}），无法判断哪个属于这个实例",
+            leaves.len(),
+            leaves.join(", ")
+        ))
+        .with_hint("调用方应显式给出 versionId（实例档案的 version_id）")),
+    }
+}
+
+/// 从 `id` 起沿 `inheritsFrom` 收集各层（第一层是实例自己，最后一层是最深的祖先）。
+fn load_chain(versions_dir: &Path, id: &str) -> PackResult<Vec<VersionJson>> {
+    let mut layers: Vec<VersionJson> = Vec::new();
+    let mut visited: Vec<String> = Vec::new();
+    let mut current = Some(id.to_string());
+    while let Some(next) = current {
+        if visited.iter().any(|seen| seen == &next) {
+            return Err(PackError::metadata(format!(
+                "版本 JSON 的继承链成环：{} → {next}",
+                visited.join(" → ")
+            )));
+        }
+        visited.push(next.clone());
+        let path = versions_dir.join(&next).join(format!("{next}.json"));
+        let text = std::fs::read_to_string(&path).map_err(|error| {
+            PackError::metadata(format!("读版本 JSON {} 失败：{error}", path.display()))
+                .with_hint("继承链上的父版本也必须装在实例里")
+        })?;
+        let layer: VersionJson = serde_json::from_str(&text).map_err(|error| {
+            PackError::metadata(format!("{} 不是合法版本 JSON：{error}", path.display()))
+        })?;
+        current = layer.inherits_from.clone();
+        layers.push(layer);
+    }
+    Ok(layers)
+}
+
+/// Maven 坐标 → 加载器种类（认不出的返回 `None`，不影响别的库）。
+fn loader_kind_of(group: &str, artifact: &str) -> Option<LoaderKind> {
+    match (group, artifact) {
+        ("net.fabricmc", "fabric-loader") => Some(LoaderKind::Fabric),
+        ("org.quiltmc", "quilt-loader") => Some(LoaderKind::Quilt),
+        ("net.minecraftforge", "forge" | "fmlloader") => Some(LoaderKind::Forge),
+        ("net.neoforged", "neoforge") => Some(LoaderKind::NeoForge),
+        _ => None,
+    }
+}
+
+/// 剥掉版本号里又写了一遍的 `<mc>-` 前缀（`1.20.1-47.1.106` → `47.1.106`）。
+fn strip_game_prefix(game_version: &str, version: &str) -> String {
+    let prefix = format!("{game_version}-");
+    version
+        .strip_prefix(&prefix)
+        .filter(|rest| !rest.is_empty())
+        .unwrap_or(version)
+        .to_string()
+}
diff --git a/crates/core/src/addon/import.rs b/crates/core/src/addon/import.rs
new file mode 100644
index 0000000..201b67f
--- /dev/null
+++ b/crates/core/src/addon/import.rs
@@ -0,0 +1,179 @@
+//! 整合包**导入**（M111）：CurseForge `manifest.json` / Modrinth `.mrpack` / MultiMC·Prism 实例
+//! → 一个可启动的实例目录。
+//!
+//! 设计依据：`DevDocs/PlanDoc/08-mod-and-recommend.md` §2（D10）、
+//! `DevDocs/PlanDoc/research/18-modpack-formats*.md`（字段清单，A/B 级来源）、
+//! `DevDocs/SubAgentsTalk/addon-整合包导入导出对接要点.md`（施工口径）。
+//! 格式模型与安全闸是 M110 的 [`crate::addon::pack`]：本模块**只消费，不重写**。
+//!
+//! # 三条硬要求落在哪
+//!
+//! | 要求 | 落点 |
+//! |------|------|
+//! | overrides 哈希**三方合并**（不静默覆盖用户改动） | [`merge`] 的判据 + [`baseline`] 的 base 侧 |
+//! | 两阶段补全 + **失败分级**（仅"缺文件"可容忍） | [`pipeline`] 的顺序 + [`report::MissingFile`] 与 [`error::ImportError`] 的分工 |
+//! | 路径穿越**双检** | 开包时 M110 [`crate::addon::pack::PackArchive::open`]，落地时 [`stage`] 的 `normalize_file` + `starts_with` 复核 |
+//!
+//! # 三种格式的语义（tower 定案，与 HMCL 相反的两条要记住）
+//!
+//! - **mrpack**：`overrides/` 与 `client-overrides/` 都解压，**后者胜**（Modrinth 官方客户端语义；
+//!   HMCL 恰好相反）；`server-overrides/` 客户端**不解压**；其余同名路径无官方优先级 ⇒ 按侧
+//!   优先级落地，不自创排序。
+//! - **CF**：溢出目录名取自清单 `overrides` 字段；`files[]` 只有 `projectID/fileID`，要 CF API
+//!   才能补出文件名/地址——仓库里还没有 CF 客户端（D10 §5），因此这部分条目的**当前正确行为**
+//!   是记成 `missing`（`Partial`），**绝不猜 `edge.forgecdn.net` 那类 URL**。
+//! - **MultiMC / Prism**：`mmc-pack.json` 的 `formatVersion` 必须恰为 `1`（M110 的读者会拒绝
+//!   其余值）；`.minecraft/` 直拷；非加载器 component（`org.lwjgl3` 等）**逐项**进
+//!   [`report::RejectedComponent`]，不静默丢；只有导入，没有导出。
+//!
+//! # `.disabled` 只按路径后缀
+//!
+//! `x.jar` / `x.jar.disabled` / `x.jar.old` / `x.jar.disabled.old` 四种变体都识别，后缀**原样
+//! 保留**；`.old` 只识别与保留（不清除、不改名、不当回滚语义）。`env.client=optional` **不是**
+//! 禁用——"可选"的语义是"安装时可取消勾选"，装回来默认仍然启用，两者不是一回事。
+//!
+//! # 用法
+//!
+//! ```ignore
+//! let engine = /* core::download::DownloadEngine */;
+//! let fetcher = DownloadEngineFetcher::new(&engine);
+//! let request = ImportRequest::new(pack_path, instance_dir)
+//!     .with_fetcher(&fetcher)
+//!     .with_registration(&launcher_layout, None);
+//! let report = download::blocking::block_on(import_pack(&request));
+//! match report.status { /* Success / Partial / Failed */ }
+//! ```
+//!
+//! # 刻意不做的事（分工边界）
+//!
+//! - **不删除**整合包升级后不再包含的文件：磁盘上的 `mods/` 里可能有用户自己装的模组，
+//!   删旧文件是"清理"而不是"导入"（要做得先有"这个文件是整合包装的"的完整账本 + 用户确认）；
+//! - **不装加载器**：只把清单翻译成 [`report::LoaderTarget`]（`kind` + 原版版本 + 加载器版本
+//!   + 版本 id），真正的元数据解析/库下载仍是 `addon::loader` + `game::install` 的既有路径；
+//! - **不碰 UI 类型**：core 零 UI 依赖（`core-no-ui` 门禁），报告只出现 `String` / `&'static str`；
+//! - **不绕过下载引擎**：所有网络只经 [`fetch::PackFetcher`]，生产实现只有
+//!   [`fetch::DownloadEngineFetcher`]（走 `core::download`）。
+//!
+//! # 没验的部分（真实世界的欠账，报告里同样登记）
+//!
+//! 真实 CF / MultiMC 导出物（夹具是手造的）、超大包（>2G）、Windows 之外的平台、断网中途、
+//! 磁盘满、真实 CurseForge `files[]` 补全（缺 CF 客户端，见 [`fetch`] 的说明）。
+
+pub mod baseline;
+pub mod error;
+pub mod fetch;
+pub mod merge;
+pub mod phase;
+pub mod pipeline;
+pub mod plan;
+pub mod report;
+pub mod stage;
+
+pub use baseline::{PackBaseline, BASELINE_FILE};
+pub use error::{ImportError, ImportErrorKind};
+pub use fetch::{
+    CurseFileMeta, DownloadEngineFetcher, FetchError, FetchErrorKind, FetchFuture, FetchRequest,
+    FetchedFile, PackFetcher,
+};
+pub use merge::{MergeAction, MergeDecision};
+pub use pipeline::baseline_relative;
+pub use plan::{ImportPlan, PlanOverride, PlanRemote, SuffixVariant};
+pub use report::{
+    keys, ConflictChoice, ConflictFile, ConflictReason, FileAction, FileSource, ImportIssue,
+    ImportProgress, ImportProgressSink, ImportReport, ImportStage, ImportStatus, ImportedFile,
+    LoaderTarget, MissingFile, MissingReason, RegisteredInstance, RejectedComponent,
+};
+pub use stage::{RollbackOutcome, Staging};
+
+use std::path::Path;
+
+use crate::addon::pack::PackLimits;
+use crate::platform::layout::LauncherLayout;
+
+/// 冲突处置策略（默认保留用户文件）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum ConflictPolicy {
+    /// 保留用户那一侧（不覆盖、不补回被删的文件），冲突逐条进报告。
+    #[default]
+    KeepUser,
+    /// 用包内内容覆盖（用户明确要求"整合包说了算"）。
+    Overwrite,
+}
+
+/// 一次导入请求。
+pub struct ImportRequest<'a> {
+    /// 包路径：zip（`.zip` / `.mrpack`）或 MultiMC 实例目录。
+    pub pack: &'a Path,
+    /// 目标实例的游戏目录（`mods/` 直接在其下）。
+    pub target: &'a Path,
+    /// 远端补全 + 下载；`None` = 离线导入（远端条目全部记成 `missing`）。
+    pub fetcher: Option<&'a dyn PackFetcher>,
+    /// 数据根布局；给了才登记实例（`profiles.json`）。
+    pub register: Option<&'a LauncherLayout>,
+    /// 实例展示名（缺省用包名）。
+    pub instance_name: Option<&'a str>,
+    /// 冲突策略。
+    pub conflict_policy: ConflictPolicy,
+    /// 包读取限额（条数 / 单条体积 / 解压总量）。
+    pub limits: PackLimits,
+    /// 进度回调。
+    pub progress: Option<ImportProgressSink>,
+}
+
+impl<'a> ImportRequest<'a> {
+    /// 最小请求（离线、不登记、保留用户文件、默认限额）。
+    #[must_use]
+    pub fn new(pack: &'a Path, target: &'a Path) -> Self {
+        Self {
+            pack,
+            target,
+            fetcher: None,
+            register: None,
+            instance_name: None,
+            conflict_policy: ConflictPolicy::KeepUser,
+            limits: PackLimits::default(),
+            progress: None,
+        }
+    }
+
+    /// 挂上远端补全 / 下载。
+    #[must_use]
+    pub fn with_fetcher(mut self, fetcher: &'a dyn PackFetcher) -> Self {
+        self.fetcher = Some(fetcher);
+        self
+    }
+
+    /// 挂上实例登记（`name` 为 `None` 时用包名）。
+    #[must_use]
+    pub fn with_registration(mut self, layout: &'a LauncherLayout, name: Option<&'a str>) -> Self {
+        self.register = Some(layout);
+        self.instance_name = name;
+        self
+    }
+
+    /// 改冲突策略。
+    #[must_use]
+    pub fn with_conflict_policy(mut self, policy: ConflictPolicy) -> Self {
+        self.conflict_policy = policy;
+        self
+    }
+
+    /// 改读取限额。
+    #[must_use]
+    pub fn with_limits(mut self, limits: PackLimits) -> Self {
+        self.limits = limits;
+        self
+    }
+
+    /// 挂进度回调。
+    #[must_use]
+    pub fn with_progress(mut self, sink: ImportProgressSink) -> Self {
+        self.progress = Some(sink);
+        self
+    }
+}
+
+/// 导入一个整合包。**永不返回 `Err`**：三态与逐项原因都在 [`ImportReport`] 里。
+pub async fn import_pack(request: &ImportRequest<'_>) -> ImportReport {
+    pipeline::run(request).await
+}
diff --git a/crates/core/src/addon/import/baseline.rs b/crates/core/src/addon/import/baseline.rs
new file mode 100644
index 0000000..db49a12
--- /dev/null
+++ b/crates/core/src/addon/import/baseline.rs
@@ -0,0 +1,162 @@
+//! 三方合并的 **base 侧**：上次导入写下的"包给的哈希"。
+//!
+//! # 为什么必须落盘
+//!
+//! 三方合并的三个输入是：`theirs`（这次包里给的）、`ours`（磁盘现状）、`base`（**上次**包里
+//! 给的）。`base` 不能从这次的包现算——那是 `theirs`；也不能从磁盘现算——那是 `ours`。少了
+//! `base` 就分不清两种截然不同的事实：
+//!
+//! - 磁盘内容 ≠ 新包内容，且磁盘内容 == 上次包内容 ⇒ **整合包升级**，该覆盖（用户没动过）；
+//! - 磁盘内容 ≠ 新包内容，且磁盘内容 ≠ 上次包内容 ⇒ **用户改过**，不许静默覆盖。
+//!
+//! 所以第一次导入就在实例根写一份基线；没有基线时（首次导入 / 用户手动塞进来的文件 / 基线
+//! 属于别的整合包）一律按"磁盘上已有同名文件"处理 —— 不覆盖、进冲突清单（最安全的一侧）。
+//!
+//! # 落点：**唯一来源是 [`crate::game::layout::GameLayout::ull_root`]**
+//!
+//! `<实例根>/.ull/pack-baseline.json`（游戏根内的启动器私有目录）。
+//!
+//! 这里有个踩过的坑（复审 r5 P1-1）：基线最初写成 `<实例根>/.ULL/…`（用了
+//! [`crate::platform::layout::LAUNCHER_HOME_DIR`]，那是**启动器数据根**的名字，在 exe/portable
+//! 那一层），而读侧用 `GameLayout::ull_root()`（`<实例根>/.ull`，小写，实例**游戏根**内的
+//! 私有目录）。Windows / macOS 的大小写不敏感文件系统上两者是同一个文件，本机全绿；ext4 上
+//! 是两个文件 ⇒ 基线永远读不到（`UserModified`/`UserDeleted` 永不出现）。
+//!
+//! 现在**读写都从 `ull_root()` 派生**：绝对路径 [`PackBaseline::path`]，相对路径
+//! [`PackBaseline::relative_path`]，两者由 `addon/tests/import_merge.rs` 的一条断言钉死
+//! （`path(root) == root.join(relative_path())`）——这条在大小写敏感的系统上也抓得住。
+//!
+//! # 包身份
+//!
+//! 基线记包名与格式；下次导入发现"基线属于另一个包"时**不拿它当 base**（否则跨包导入同一
+//! 目录会把别人的哈希当成本次包的历史），而是降级成"无基线"并如实告警。
+//!
+//! 基线里存的是**包声明的哈希**（不是磁盘实际哈希）：用户改过的文件在基线里仍是包的值，
+//! 下次导入才会继续判成"用户改过"，而不会被"上次也是改动值"洗白。`.disabled` / `.old`
+//! 后缀按原样进键名（后缀是路径的一部分，不附加语义）。
+//!
+//! 读失败**不是**致命错误：基线坏了最多退化成"全部按 pre-existing 冲突处理"（保留用户文件），
+//! 比"因为读不出基线就整包回滚"合理。
+
+use std::collections::BTreeMap;
+use std::path::{Path, PathBuf};
+
+use serde::{Deserialize, Serialize};
+
+use crate::game::layout::GameLayout;
+
+/// 基线文件名。
+pub const BASELINE_FILE: &str = "pack-baseline.json";
+/// 基线 schema 版本。
+pub const BASELINE_SCHEMA: u32 = 1;
+
+/// 上次导入写下的包声明哈希表。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PackBaseline {
+    /// schema 版本（迁移链入口）。
+    #[serde(default = "default_schema")]
+    pub schema_version: u32,
+    /// 上次导入的包名（诊断 + 包身份判据）。
+    #[serde(default)]
+    pub pack_name: String,
+    /// 上次导入命中的格式 id（包身份判据的另一半）。
+    #[serde(default)]
+    pub format: String,
+    /// 实例内相对路径 → 包声明的 SHA-1。
+    #[serde(default)]
+    pub files: BTreeMap<String, String>,
+}
+
+const fn default_schema() -> u32 {
+    BASELINE_SCHEMA
+}
+
+impl Default for PackBaseline {
+    fn default() -> Self {
+        Self {
+            schema_version: BASELINE_SCHEMA,
+            pack_name: String::new(),
+            format: String::new(),
+            files: BTreeMap::new(),
+        }
+    }
+}
+
+impl PackBaseline {
+    /// 实例根下的基线**绝对**路径。
+    ///
+    /// 唯一来源是 `GameLayout::ull_root()`：实例的游戏根里那个启动器私有目录。
+    #[must_use]
+    pub fn path(game_root: &Path) -> PathBuf {
+        GameLayout::new(game_root).ull_root().join(BASELINE_FILE)
+    }
+
+    /// 基线**相对实例根**的路径（暂存期与写盘用；与 [`Self::path`] 同源）。
+    #[must_use]
+    pub fn relative_path() -> PathBuf {
+        // 用空根求 `ull_root()` 就得到那一段相对目录名（`.ull`），不另抄一份字符串。
+        GameLayout::new(Path::new(""))
+            .ull_root()
+            .join(BASELINE_FILE)
+    }
+
+    /// 基线是否属于这份包（空基线 / 没有身份信息的老基线一律放行）。
+    #[must_use]
+    pub fn matches_pack(&self, format: &str, pack_name: &str) -> bool {
+        if self.pack_name.is_empty() && self.format.is_empty() {
+            return true;
+        }
+        self.format == format && self.pack_name == pack_name
+    }
+
+    /// 读基线；文件不存在返回空表（**不是错误**），形状不符返回 `Err`。
+    ///
+    /// # Errors
+    ///
+    /// 非 UTF-8 / JSON 非法 / 版本号比本进程新（未来版本写的）时返回人读原因。
+    pub fn load(game_root: &Path) -> Result<Self, String> {
+        let path = Self::path(game_root);
+        let bytes = match std::fs::read(&path) {
+            Ok(bytes) => bytes,
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+                return Ok(Self::default())
+            }
+            Err(error) => {
+                return Err(format!("读 {} 失败：{error}", path.display()));
+            }
+        };
+        let text = String::from_utf8(bytes)
+            .map_err(|error| format!("{} 不是 UTF-8：{error}", path.display()))?;
+        let baseline: Self = serde_json::from_str(&text)
+            .map_err(|error| format!("{} 形状不符：{error}", path.display()))?;
+        if baseline.schema_version > BASELINE_SCHEMA {
+            return Err(format!(
+                "{} 的 schemaVersion={} 比本进程（{BASELINE_SCHEMA}）新",
+                path.display(),
+                baseline.schema_version
+            ));
+        }
+        Ok(baseline)
+    }
+
+    /// 查上次给这个路径的哈希。
+    #[must_use]
+    pub fn sha1(&self, path: &str) -> Option<&str> {
+        self.files.get(path).map(String::as_str)
+    }
+
+    /// 记一条。
+    pub fn insert(&mut self, path: impl Into<String>, sha1: impl Into<String>) {
+        self.files.insert(path.into(), sha1.into());
+    }
+
+    /// 序列化成落盘字节（pretty：这文件是给人排障看的）。
+    ///
+    /// # Errors
+    ///
+    /// 序列化失败（纯理论，`BTreeMap<String, String>` 不会失败）。
+    pub fn to_bytes(&self) -> Result<Vec<u8>, String> {
+        serde_json::to_vec_pretty(self).map_err(|error| format!("基线序列化失败：{error}"))
+    }
+}
diff --git a/crates/core/src/addon/import/error.rs b/crates/core/src/addon/import/error.rs
new file mode 100644
index 0000000..600a977
--- /dev/null
+++ b/crates/core/src/addon/import/error.rs
@@ -0,0 +1,204 @@
+//! 导入链路的**致命**失败分类（能容忍的缺文件不在这里，它们在
+//! [`super::report::MissingFile`] 里逐条记账）。
+//!
+//! # 为什么要跟 `MissingFile` 分开
+//!
+//! D10 §2 的失败分级只有一条判据：**这个错误是不是"某个文件搞不到"**。
+//!
+//! | 情形 | 处置 | 落在哪 |
+//! |------|------|--------|
+//! | 某个远端文件下载失败 / 补全不出地址 / 没有网络 | 容忍，实例照装，状态降级 `Partial` | [`super::report::MissingFile`] |
+//! | 路径穿越 / 符号链接 / 超限额 / 清单坏 / 本地 IO / 摘要不符 | **整包回滚**，目标目录零残留 | 本模块 |
+//!
+//! 因此 [`ImportError`] 只描述**必须回滚**的失败；能容忍的东西一旦也塞进来，调用方就再也
+//! 分不清"该重试"和"该报恶意包"了。
+//!
+//! # 稳定码
+//!
+//! 包相关六类**直接沿用 M110 的码**（`pack_unsupported` / `pack_metadata` /
+//! `pack_traversal` / `pack_symlink` / `pack_limits` / `pack_io`），不另起一套同义词：
+//! 同一个事实在 CLI、日志、事件流里只能有一个字符串。导入独有的三类加 `import_` 前缀。
+
+use std::fmt;
+
+use super::super::pack::{PackError, PackErrorKind};
+use super::fetch::{FetchError, FetchErrorKind};
+
+/// 导入失败大类（稳定码进 `--json` 的 `error.code` 与日志，**不要改名**）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ImportErrorKind {
+    /// 透传 M110 的六类包错误（稳定码沿用 `pack_*`）。
+    Pack(PackErrorKind),
+    /// 下载到的内容与清单声明的摘要/大小**不符**（`import_integrity`）。
+    Integrity,
+    /// 远端补全/下载在**致命**情形下失败（`import_fetch`；本地 IO 归 `pack_io`）。
+    Fetch,
+    /// 清单里的加载器信息不足以组出安装计划（`import_loader`）。
+    Loader,
+    /// 实例登记失败（`import_instance`）。
+    Instance,
+}
+
+impl ImportErrorKind {
+    /// 稳定字符串 id（进 `--json` 与日志）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Pack(kind) => kind.as_str(),
+            Self::Integrity => "import_integrity",
+            Self::Fetch => "import_fetch",
+            Self::Loader => "import_loader",
+            Self::Instance => "import_instance",
+        }
+    }
+
+    /// 人读大类名（报告表格用）。
+    #[must_use]
+    pub const fn label(self) -> &'static str {
+        match self {
+            Self::Pack(kind) => pack_label(kind),
+            Self::Integrity => "内容与清单不符",
+            Self::Fetch => "远端补全失败",
+            Self::Loader => "加载器信息不足",
+            Self::Instance => "实例登记失败",
+        }
+    }
+}
+
+/// M110 六个大类的人读名（与 `PackErrorKind` 的稳定码一一对应，不另起一套枚举）。
+const fn pack_label(kind: PackErrorKind) -> &'static str {
+    match kind {
+        PackErrorKind::Unsupported => "格式不支持",
+        PackErrorKind::Metadata => "清单损坏",
+        PackErrorKind::Traversal => "路径穿越",
+        PackErrorKind::Symlink => "符号链接条目",
+        PackErrorKind::Limits => "超出安全限额",
+        PackErrorKind::Io => "本地 IO 失败",
+    }
+}
+
+/// 一次**必须回滚**的导入失败。
+#[derive(Debug, Clone)]
+pub struct ImportError {
+    kind: ImportErrorKind,
+    message: String,
+    hint: Option<String>,
+}
+
+impl ImportError {
+    /// 构造。
+    #[must_use]
+    pub fn new(kind: ImportErrorKind, message: impl Into<String>) -> Self {
+        Self {
+            kind,
+            message: message.into(),
+            hint: None,
+        }
+    }
+
+    /// 内容与清单声明不符。
+    #[must_use]
+    pub fn integrity(message: impl Into<String>) -> Self {
+        Self::new(ImportErrorKind::Integrity, message)
+    }
+
+    /// 远端补全/下载的致命失败。
+    #[must_use]
+    pub fn fetch(message: impl Into<String>) -> Self {
+        Self::new(ImportErrorKind::Fetch, message)
+    }
+
+    /// 加载器信息不足。
+    #[must_use]
+    pub fn loader(message: impl Into<String>) -> Self {
+        Self::new(ImportErrorKind::Loader, message)
+    }
+
+    /// 实例登记失败。
+    #[must_use]
+    pub fn instance(message: impl Into<String>) -> Self {
+        Self::new(ImportErrorKind::Instance, message)
+    }
+
+    /// 补一句提示。
+    #[must_use]
+    pub fn with_hint(mut self, hint: impl Into<String>) -> Self {
+        self.hint = Some(hint.into());
+        self
+    }
+
+    /// 大类。
+    #[must_use]
+    pub const fn kind(&self) -> ImportErrorKind {
+        self.kind
+    }
+
+    /// 稳定码。
+    #[must_use]
+    pub const fn code(&self) -> &'static str {
+        self.kind.as_str()
+    }
+
+    /// 人读说明。
+    #[must_use]
+    pub fn message(&self) -> &str {
+        &self.message
+    }
+
+    /// 下一步提示。
+    #[must_use]
+    pub fn hint(&self) -> Option<&str> {
+        self.hint.as_deref()
+    }
+}
+
+impl fmt::Display for ImportError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str(&self.message)
+    }
+}
+
+impl std::error::Error for ImportError {}
+
+impl From<PackError> for ImportError {
+    fn from(error: PackError) -> Self {
+        Self {
+            kind: ImportErrorKind::Pack(error.kind()),
+            message: error.message().to_string(),
+            hint: error.hint().map(str::to_string),
+        }
+    }
+}
+
+impl From<FetchError> for ImportError {
+    fn from(error: FetchError) -> Self {
+        // 分级判据只有一处：`Integrity` 与 `Io` 必须回滚，其余三类是"搞不到"。
+        let kind = match error.kind() {
+            FetchErrorKind::Integrity => ImportErrorKind::Integrity,
+            FetchErrorKind::Io => ImportErrorKind::Pack(PackErrorKind::Io),
+            FetchErrorKind::NotFound | FetchErrorKind::Network | FetchErrorKind::Unsupported => {
+                ImportErrorKind::Fetch
+            }
+        };
+        Self {
+            kind,
+            message: error.message().to_string(),
+            hint: None,
+        }
+    }
+}
+
+impl serde::Serialize for ImportError {
+    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        use serde::ser::SerializeMap;
+
+        let mut map = serializer.serialize_map(None)?;
+        map.serialize_entry("code", self.code())?;
+        map.serialize_entry("kind", self.kind.label())?;
+        map.serialize_entry("message", &self.message)?;
+        if let Some(hint) = &self.hint {
+            map.serialize_entry("hint", hint)?;
+        }
+        map.end()
+    }
+}
diff --git a/crates/core/src/addon/import/fetch.rs b/crates/core/src/addon/import/fetch.rs
new file mode 100644
index 0000000..3017224
--- /dev/null
+++ b/crates/core/src/addon/import/fetch.rs
@@ -0,0 +1,234 @@
+//! 远端补全与下载的**注入点**：导入管线自己不碰网络，只认这个 trait。
+//!
+//! # 为什么是 trait 而不是直接调 `DownloadEngine`
+//!
+//! 三条理由，每条都对应一个真实麻烦：
+//!
+//! 1. **测试不能联网**：三种格式的端到端用例必须离线跑（CI 没有网，也不该有）；
+//! 2. **CurseForge 的 `files[]` 补全还没有客户端**：CF 官方清单只有 `projectID/fileID`，
+//!    要 `x-api-key` 的 `api.curseforge.com/v1/mods/<id>/files/<fid>` 才能换出文件名与地址。
+//!    仓库里没有这个客户端（D10 §5 规划中），而 [`crate::download::DownloadRequest`] **没有
+//!    自定义 header 字段**——硬塞进去会把"补不出来"伪装成"网络失败"。所以默认实现诚实地
+//!    返回 [`FetchErrorKind::Unsupported`]（= 可容忍的"搞不到"，进报告的 `missing`），
+//!    **绝不猜下载 URL**：猜出来的地址一旦 404，用户看到的是"导入失败"而不是"这条暂时补不了"；
+//! 3. **依赖方向**：`addon` 属于更高层的领域逻辑，让它直接持有一个 `DownloadEngine` 会把
+//!    镜像/健康度/地区档案这些下载侧策略涌进导入链路。
+//!
+//! # 生产实现只走 `core::download`
+//!
+//! [`DownloadEngineFetcher`] 是本 crate 里**唯一**的生产实现，它只做一件事：把
+//! [`FetchRequest`] 翻译成 [`crate::download::DownloadRequest`] 交给引擎（镜像展开、退避、
+//! 续传、边下边算都在引擎里）。导入链路里**没有**第二个 `reqwest::Client`。
+
+use std::future::Future;
+use std::path::Path;
+use std::pin::Pin;
+
+use crate::download::{
+    DownloadEngine, DownloadError, DownloadErrorKind, DownloadRequest, Integrity, ResourceKind,
+};
+
+/// "搞不到"的成因（**分级判据只在这里**）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum FetchErrorKind {
+    /// 源上确实没有（404 / 文件被删）。
+    NotFound,
+    /// 网络侧失败（超时、连不上、所有候选源都失败）。
+    Network,
+    /// 本地 IO（写盘失败、磁盘满）。
+    Io,
+    /// 内容与声明的摘要不符。
+    Integrity,
+    /// 这条路走不通（CF 无客户端 / 没有可用下载地址）。
+    Unsupported,
+}
+
+impl FetchErrorKind {
+    /// 稳定字符串 id。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::NotFound => "fetch_not_found",
+            Self::Network => "fetch_network",
+            Self::Io => "fetch_io",
+            Self::Integrity => "fetch_integrity",
+            Self::Unsupported => "fetch_unsupported",
+        }
+    }
+
+    /// 是否属于"某个文件搞不到"（可容忍，实例照装）。
+    #[must_use]
+    pub const fn is_tolerable(self) -> bool {
+        matches!(self, Self::NotFound | Self::Network | Self::Unsupported)
+    }
+}
+
+/// 一次取数失败。
+#[derive(Debug, Clone)]
+pub struct FetchError {
+    kind: FetchErrorKind,
+    message: String,
+}
+
+impl FetchError {
+    /// 构造。
+    #[must_use]
+    pub fn new(kind: FetchErrorKind, message: impl Into<String>) -> Self {
+        Self {
+            kind,
+            message: message.into(),
+        }
+    }
+
+    /// 这条路走不通。
+    #[must_use]
+    pub fn unsupported(message: impl Into<String>) -> Self {
+        Self::new(FetchErrorKind::Unsupported, message)
+    }
+
+    /// 内容与声明不符。
+    #[must_use]
+    pub fn integrity(message: impl Into<String>) -> Self {
+        Self::new(FetchErrorKind::Integrity, message)
+    }
+
+    /// 大类。
+    #[must_use]
+    pub const fn kind(&self) -> FetchErrorKind {
+        self.kind
+    }
+
+    /// 人读说明。
+    #[must_use]
+    pub fn message(&self) -> &str {
+        &self.message
+    }
+}
+
+impl std::fmt::Display for FetchError {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter.write_str(&self.message)
+    }
+}
+
+impl std::error::Error for FetchError {}
+
+impl From<DownloadError> for FetchError {
+    fn from(error: DownloadError) -> Self {
+        let kind = match error.kind {
+            DownloadErrorKind::NotFound => FetchErrorKind::NotFound,
+            DownloadErrorKind::Integrity => FetchErrorKind::Integrity,
+            DownloadErrorKind::Io => FetchErrorKind::Io,
+            DownloadErrorKind::InvalidRequest => FetchErrorKind::Unsupported,
+            DownloadErrorKind::ServerError
+            | DownloadErrorKind::Timeout
+            | DownloadErrorKind::Network
+            | DownloadErrorKind::RangeUnsupported
+            | DownloadErrorKind::AllSourcesFailed => FetchErrorKind::Network,
+        };
+        Self::new(kind, error.message)
+    }
+}
+
+/// trait 方法返回的装箱 future（core 不引 `async-trait`，手写 `Pin<Box<dyn Future>>` 即可）。
+pub type FetchFuture<'a, T> = Pin<Box<dyn Future<Output = T> + Send + 'a>>;
+
+/// CurseForge 一个文件的元数据（`files[]` 补全的产物）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CurseFileMeta {
+    /// 文件名（`jei-1.20.1-15.2.0.27.jar`）。
+    pub file_name: String,
+    /// 下载地址；`None` = 作者关了 API 分发（CF 官方允许），需要用户手动提供。
+    pub url: Option<String>,
+    /// 官方给的 SHA-1。
+    pub sha1: Option<String>,
+    /// 字节数。
+    pub size: Option<u64>,
+    /// 项目类别（CF `classId`：6 = mods、12 = resource packs、6945 = shaders …）。
+    pub class_id: Option<i64>,
+}
+
+/// 一次文件下载请求。
+#[derive(Debug, Clone, Copy)]
+pub struct FetchRequest<'a> {
+    /// 逻辑下载地址（官方源）。
+    pub url: &'a str,
+    /// 落盘路径（导入器给的**暂存**路径，不是最终实例路径）。
+    pub dest: &'a Path,
+    /// 期望 SHA-1（清单声明的）。
+    pub sha1: Option<&'a str>,
+    /// 期望字节数。
+    pub size: Option<u64>,
+}
+
+/// 一次下载的产物。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct FetchedFile {
+    /// 落盘字节数。
+    pub bytes: u64,
+}
+
+/// 远端补全 + 下载（测试注入假件，生产走 [`DownloadEngineFetcher`]）。
+pub trait PackFetcher: Send + Sync {
+    /// CurseForge `projectID/fileID` → 文件名 / 下载地址 / 摘要。
+    ///
+    /// 默认实现返回 [`FetchErrorKind::Unsupported`]：见模块文档第 2 条（**不许猜 URL**）。
+    fn curse_file<'a>(
+        &'a self,
+        project_id: i64,
+        file_id: i64,
+    ) -> FetchFuture<'a, Result<CurseFileMeta, FetchError>> {
+        Box::pin(async move {
+            Err(FetchError::unsupported(format!(
+                "CurseForge files[] 补全需要 CF API 客户端（projectID={project_id} fileID={file_id}）；当前版本没有，本条记为缺文件"
+            )))
+        })
+    }
+
+    /// 把 `request.url` 下到 `request.dest`。
+    fn fetch_file<'a>(
+        &'a self,
+        request: FetchRequest<'a>,
+    ) -> FetchFuture<'a, Result<FetchedFile, FetchError>>;
+}
+
+/// 生产实现：把请求交给 `core::download` 的引擎。
+#[derive(Debug, Clone, Copy)]
+pub struct DownloadEngineFetcher<'a> {
+    engine: &'a DownloadEngine,
+}
+
+impl<'a> DownloadEngineFetcher<'a> {
+    /// 绑定引擎。
+    #[must_use]
+    pub const fn new(engine: &'a DownloadEngine) -> Self {
+        Self { engine }
+    }
+}
+
+impl PackFetcher for DownloadEngineFetcher<'_> {
+    fn fetch_file<'a>(
+        &'a self,
+        request: FetchRequest<'a>,
+    ) -> FetchFuture<'a, Result<FetchedFile, FetchError>> {
+        Box::pin(async move {
+            let mut download = DownloadRequest::new(
+                ResourceKind::ModFile,
+                request.url,
+                request.dest.to_path_buf(),
+            );
+            // 摘要长度不对就当"没给"：引擎白跑一趟网络比这更贵。
+            if let Some(sha1) = request.sha1 {
+                let integrity = Integrity::sha1(sha1);
+                if integrity.is_well_formed() {
+                    download.integrity = Some(integrity);
+                }
+            }
+            download.expected_size = request.size;
+            let outcome = self.engine.download(download).await?;
+            Ok(FetchedFile {
+                bytes: outcome.bytes,
+            })
+        })
+    }
+}
diff --git a/crates/core/src/addon/import/merge.rs b/crates/core/src/addon/import/merge.rs
new file mode 100644
index 0000000..95c6775
--- /dev/null
+++ b/crates/core/src/addon/import/merge.rs
@@ -0,0 +1,139 @@
+//! overrides 三方合并的**判据**（纯函数，无 IO）：包内原值 / 磁盘现状 / 基线哈希。
+//!
+//! # 一张表看完全部情形
+//!
+//! 记 `T` = 包内声明（theirs）、`B` = 基线（base，上次导入的包声明）、`D` = 磁盘现状（ours）。
+//! `D` 为 `None` 表示文件不存在。
+//!
+//! | `D` | `B` | 关系 | 结论 | 理由 |
+//! |-----|-----|------|------|------|
+//! | 无 | 无 | — | [`MergeAction::Install`] | 全新文件，没有可保护的东西 |
+//! | 无 | 有 | `B` 任意 | [`MergeAction::KeepUser`] + `UserDeleted` | 用户删过：**不许**偷偷装回来 |
+//! | 有 | 无 | `D == T` | [`MergeAction::SkipIdentical`] | 内容一样，写盘是浪费 |
+//! | 有 | 无 | `D != T` | [`MergeAction::KeepUser`] + `PreExisting` | 没有基线可判 ⇒ 当用户已有内容 |
+//! | 有 | 有 | `D == T` | [`MergeAction::SkipIdentical`] | 已经是最新 |
+//! | 有 | 有 | `D == B` | [`MergeAction::Install`] | 用户没动过 ⇒ 整合包升级，覆盖是对的 |
+//! | 有 | 有 | `D != B` | [`MergeAction::KeepUser`] + `UserModified` | 用户改过：**不许**静默覆盖 |
+//!
+//! 两条"不许"就是任务里的硬要求（"不得直接盖掉用户改过的文件"）。判据只此一处：
+//! `ImportRequest::conflict_policy = Overwrite` 时，`KeepUser` 才会被判据的调用方翻成
+//! [`MergeAction::Install`]，**判据本身不读策略**——这样"哪些情形算冲突"与"冲突怎么处置"
+//! 是两个可独立验证的事实。
+//!
+//! # `.disabled` / `.old` 不参与判据
+//!
+//! 后缀是路径的一部分（`mods/x.jar.disabled` 与 `mods/x.jar` 是**两个文件**），所以它们
+//! 天然按不同键各自走上面的表。不给 `.old` 附加"清理/回滚"语义（tower 定案：只识别与保留）。
+
+use super::report::ConflictReason;
+
+/// 判据给出的动作（策略开关在调用方）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MergeAction {
+    /// 写入包内内容（新建或覆盖）。
+    Install,
+    /// 磁盘内容已经与包内一致，什么都不做。
+    SkipIdentical,
+    /// 保留用户那一侧（不写盘）。
+    KeepUser,
+}
+
+/// 一次判定。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct MergeDecision {
+    /// 动作。
+    pub action: MergeAction,
+    /// 算冲突时的成因（`None` = 不是冲突）。
+    pub reason: Option<ConflictReason>,
+}
+
+impl MergeDecision {
+    const fn plain(action: MergeAction) -> Self {
+        Self {
+            action,
+            reason: None,
+        }
+    }
+
+    const fn conflict(reason: ConflictReason) -> Self {
+        Self {
+            action: MergeAction::KeepUser,
+            reason: Some(reason),
+        }
+    }
+
+    /// 是否冲突（与最终处置无关）。
+    #[must_use]
+    pub const fn is_conflict(self) -> bool {
+        self.reason.is_some()
+    }
+}
+
+/// 三方合并判据。
+#[must_use]
+pub fn decide(pack_sha1: &str, base_sha1: Option<&str>, disk_sha1: Option<&str>) -> MergeDecision {
+    match (disk_sha1, base_sha1) {
+        // 磁盘上没有这个文件。
+        (None, None) => MergeDecision::plain(MergeAction::Install),
+        (None, Some(_)) => MergeDecision::conflict(ConflictReason::UserDeleted),
+        // 磁盘上有。
+        (Some(disk), _) if disk == pack_sha1 => MergeDecision::plain(MergeAction::SkipIdentical),
+        (Some(_), None) => MergeDecision::conflict(ConflictReason::PreExisting),
+        (Some(disk), Some(base)) if disk == base => MergeDecision::plain(MergeAction::Install),
+        (Some(_), Some(_)) => MergeDecision::conflict(ConflictReason::UserModified),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const T: &str = "aaaa";
+    const B: &str = "bbbb";
+
+    #[test]
+    fn fresh_file_is_installed() {
+        let decision = decide(T, None, None);
+        assert_eq!(decision.action, MergeAction::Install);
+        assert!(!decision.is_conflict());
+    }
+
+    #[test]
+    fn untouched_file_is_replaced_on_upgrade() {
+        // 磁盘 == 基线（用户没动过）⇒ 整合包升级，覆盖。
+        let decision = decide(T, Some(B), Some(B));
+        assert_eq!(decision.action, MergeAction::Install);
+        assert!(!decision.is_conflict());
+    }
+
+    #[test]
+    fn user_modification_is_a_conflict() {
+        let decision = decide(T, Some(B), Some("cccc"));
+        assert_eq!(decision.action, MergeAction::KeepUser);
+        assert_eq!(decision.reason, Some(ConflictReason::UserModified));
+    }
+
+    #[test]
+    fn user_deletion_is_a_conflict() {
+        let decision = decide(T, Some(B), None);
+        assert_eq!(decision.action, MergeAction::KeepUser);
+        assert_eq!(decision.reason, Some(ConflictReason::UserDeleted));
+    }
+
+    #[test]
+    fn pre_existing_without_baseline_is_a_conflict() {
+        let decision = decide(T, None, Some("dddd"));
+        assert_eq!(decision.action, MergeAction::KeepUser);
+        assert_eq!(decision.reason, Some(ConflictReason::PreExisting));
+    }
+
+    #[test]
+    fn identical_content_is_skipped() {
+        // 无论有没有基线，磁盘与包内一致就不写。
+        assert_eq!(decide(T, None, Some(T)).action, MergeAction::SkipIdentical);
+        assert_eq!(
+            decide(T, Some(B), Some(T)).action,
+            MergeAction::SkipIdentical
+        );
+    }
+}
diff --git a/crates/core/src/addon/import/phase.rs b/crates/core/src/addon/import/phase.rs
new file mode 100644
index 0000000..1d24268
--- /dev/null
+++ b/crates/core/src/addon/import/phase.rs
@@ -0,0 +1,379 @@
+//! 两个落盘阶段的实现：**覆盖内容解压** 与 **远端补全下载**（共用同一张三方合并表）。
+//!
+//! 拆出来是为了让 `pipeline.rs` 只剩"顺序与收尾"：阶段实现里看得见"每个文件怎么判"，
+//! 编排里看得见"什么时候回滚"。
+
+use std::path::Path;
+
+use super::super::pack::{PackArchive, PackError};
+use super::baseline::PackBaseline;
+use super::error::ImportError;
+use super::fetch::{FetchError, FetchRequest};
+use super::merge::{self, MergeAction};
+use super::pipeline::tell;
+use super::plan::{curse_class_dir, ImportPlan, PlanRemote};
+use super::report::{
+    ConflictChoice, ConflictFile, ConflictReason, FileAction, ImportReport, ImportStage,
+    ImportedFile, MissingFile, MissingReason,
+};
+use super::stage::Staging;
+use super::ImportRequest;
+use crate::download::verify::{self, digest_bytes};
+use crate::download::HashAlgo;
+
+/// 阶段一：覆盖条目落暂存 + 三方合并。
+pub(crate) async fn extract_overrides(
+    request: &ImportRequest<'_>,
+    archive: &PackArchive,
+    plan: &ImportPlan,
+    baseline: &PackBaseline,
+    staging: &Staging,
+    report: &mut ImportReport,
+    next: &mut PackBaseline,
+) -> Result<(), ImportError> {
+    let total = plan.overrides.len();
+    let target = staging.target().to_path_buf();
+    for (index, entry) in plan.overrides.iter().enumerate() {
+        tell(
+            &request.progress,
+            ImportStage::Extract,
+            index,
+            total,
+            Some(entry.path.clone()),
+        );
+        let name = format!("{}/{}", entry.dir, entry.path);
+        let bytes = archive.read(&name)?.ok_or_else(|| {
+            ImportError::from(PackError::metadata(format!(
+                "清单列了 {name}，但包里读不到这个条目（声明与实际不符）"
+            )))
+        })?;
+        // 用**实测**摘要而不是模型里记的那个：模型可能来自外部构造。
+        let pack_sha1 = digest_bytes(HashAlgo::Sha1, &bytes);
+        next.insert(entry.path.clone(), pack_sha1.clone());
+        let disk = disk_sha1(&target.join(&entry.path))?;
+        let decision = merge::decide(&pack_sha1, baseline.sha1(&entry.path), disk.as_deref());
+        let (action, choice) = settle(decision, disk.is_some(), request.conflict_policy);
+        if let Some(reason) = decision.reason {
+            report.conflicts.push(conflict(
+                entry.path.clone(),
+                reason,
+                choice,
+                &pack_sha1,
+                bytes.len() as u64,
+                baseline.sha1(&entry.path).map(str::to_string),
+                disk,
+            ));
+        }
+        if action.wrote() {
+            staging.write(&entry.path, &bytes)?;
+            report.bytes_written += bytes.len() as u64;
+        }
+        report.files.push(ImportedFile {
+            path: entry.path.clone(),
+            source: entry.source,
+            sha1: Some(pack_sha1),
+            bytes: bytes.len() as u64,
+            disabled: entry.disabled,
+            action,
+            note: entry.note.clone(),
+        });
+    }
+    Ok(())
+}
+
+/// 阶段二：远端条目补全 + 下载 + 同一张合并表。
+pub(crate) async fn fetch_remote(
+    request: &ImportRequest<'_>,
+    plan: &ImportPlan,
+    baseline: &PackBaseline,
+    staging: &Staging,
+    report: &mut ImportReport,
+    next: &mut PackBaseline,
+) -> Result<(), ImportError> {
+    let total = plan.remote.len();
+    let target = staging.target().to_path_buf();
+    for (index, entry) in plan.remote.iter().enumerate() {
+        let display = entry.path.clone().unwrap_or_else(|| entry.file.key());
+        tell(
+            &request.progress,
+            ImportStage::Fetch,
+            index,
+            total,
+            Some(display),
+        );
+        let Some(resolved) = resolve(request, entry).await? else {
+            report
+                .missing
+                .push(missing_for(entry, request.fetcher.is_some()));
+            continue;
+        };
+        let disk = disk_sha1(&target.join(&resolved.path))?;
+        // 有声明摘要就能先判合并：命中"保留用户 / 已一致"时**不必下载**（省一次网络）。
+        if let Some(declared) = resolved.sha1.clone() {
+            let decision = merge::decide(&declared, baseline.sha1(&resolved.path), disk.as_deref());
+            let (action, choice) = settle(decision, disk.is_some(), request.conflict_policy);
+            if !action.wrote() {
+                next.insert(resolved.path.clone(), declared.clone());
+                if let Some(reason) = decision.reason {
+                    report.conflicts.push(conflict(
+                        resolved.path.clone(),
+                        reason,
+                        choice,
+                        &declared,
+                        resolved.size.unwrap_or(0),
+                        baseline.sha1(&resolved.path).map(str::to_string),
+                        disk.clone(),
+                    ));
+                }
+                report.files.push(ImportedFile {
+                    path: resolved.path,
+                    source: entry.source,
+                    sha1: Some(declared),
+                    bytes: resolved.size.unwrap_or(0),
+                    disabled: entry.disabled,
+                    action,
+                    note: None,
+                });
+                continue;
+            }
+        }
+        let dest = staging.dest_for(&resolved.path)?;
+        let fetched = match request.fetcher {
+            Some(fetcher) => {
+                fetcher
+                    .fetch_file(FetchRequest {
+                        url: &resolved.url,
+                        dest: &dest,
+                        sha1: resolved.sha1.as_deref(),
+                        size: resolved.size,
+                    })
+                    .await
+            }
+            None => Err(FetchError::unsupported("本次导入没有 fetcher（离线）")),
+        };
+        let fetched = match fetched {
+            Ok(fetched) => fetched,
+            Err(error) if error.kind().is_tolerable() => {
+                report.missing.push(missing_from_error(
+                    &resolved.path,
+                    entry,
+                    MissingReason::FetchFailed,
+                    error.message(),
+                ));
+                continue;
+            }
+            Err(error) => return Err(error.into()),
+        };
+        let pack_sha1 = digest_file(&dest)?;
+        if let Some(declared) = resolved.sha1.as_deref() {
+            if !verify::matches(declared, &pack_sha1) {
+                // 摘要不符 = 内容坏了 / 被换过，**不许**当成"暂时搞不到"混过去。
+                return Err(ImportError::integrity(format!(
+                    "{} 的摘要与清单声明不符（声明 {declared}，实际 {pack_sha1}）",
+                    resolved.path
+                )));
+            }
+        }
+        let decision = merge::decide(&pack_sha1, baseline.sha1(&resolved.path), disk.as_deref());
+        let (action, choice) = settle(decision, disk.is_some(), request.conflict_policy);
+        if let Some(reason) = decision.reason {
+            report.conflicts.push(conflict(
+                resolved.path.clone(),
+                reason,
+                choice,
+                &pack_sha1,
+                fetched.bytes,
+                baseline.sha1(&resolved.path).map(str::to_string),
+                disk,
+            ));
+        }
+        if action.wrote() {
+            report.bytes_written += fetched.bytes;
+        } else {
+            staging.discard(&resolved.path)?;
+        }
+        next.insert(resolved.path.clone(), pack_sha1.clone());
+        report.files.push(ImportedFile {
+            path: resolved.path,
+            source: entry.source,
+            sha1: Some(pack_sha1),
+            bytes: fetched.bytes,
+            disabled: entry.disabled,
+            action,
+            note: None,
+        });
+    }
+    Ok(())
+}
+
+/// 一个已解析出"路径 + 地址"的远端条目。
+struct Resolved {
+    path: String,
+    url: String,
+    sha1: Option<String>,
+    size: Option<u64>,
+}
+
+/// 把条目补全成"有路径、有地址"。
+///
+/// `Ok(None)` = 这条补不出来（进 `missing`）；`Err` = 致命（本地 IO / 内容不符）。
+async fn resolve(
+    request: &ImportRequest<'_>,
+    entry: &PlanRemote,
+) -> Result<Option<Resolved>, ImportError> {
+    if let Some(path) = &entry.path {
+        // mrpack：路径与地址都在清单里，取第一个非空地址。
+        let Some(url) = entry
+            .file
+            .downloads
+            .iter()
+            .find(|url| !url.trim().is_empty())
+            .cloned()
+        else {
+            return Ok(None);
+        };
+        return Ok(Some(Resolved {
+            path: path.clone(),
+            url,
+            sha1: entry.file.sha1().map(str::to_string),
+            size: entry.file.size,
+        }));
+    }
+    // CurseForge：只有 projectID/fileID，必须靠 CF API 补全（当前默认不支持 ⇒ 如实记缺）。
+    let (Some(project_id), Some(file_id)) = (entry.file.project_id, entry.file.file_id) else {
+        return Ok(None);
+    };
+    let Some(fetcher) = request.fetcher else {
+        return Ok(None);
+    };
+    let meta = match fetcher.curse_file(project_id, file_id).await {
+        Ok(meta) => meta,
+        Err(error) if error.kind().is_tolerable() => return Ok(None),
+        Err(error) => return Err(error.into()),
+    };
+    let (Some(url), Some(dir)) = (
+        meta.url.clone().filter(|url| !url.trim().is_empty()),
+        meta.class_id.and_then(curse_class_dir),
+    ) else {
+        // 作者关了 API 分发 / classId 认不出 ⇒ **不猜**目录、不猜 URL。
+        return Ok(None);
+    };
+    Ok(Some(Resolved {
+        path: format!("{dir}/{}", meta.file_name),
+        url,
+        sha1: meta.sha1,
+        size: meta.size,
+    }))
+}
+
+/// 合并判定 + 策略 → 实际动作。
+fn settle(
+    decision: merge::MergeDecision,
+    disk_exists: bool,
+    policy: super::ConflictPolicy,
+) -> (FileAction, ConflictChoice) {
+    let overwrite = policy == super::ConflictPolicy::Overwrite;
+    match decision.action {
+        MergeAction::Install => (
+            if disk_exists {
+                FileAction::Replaced
+            } else {
+                FileAction::Installed
+            },
+            ConflictChoice::Overwrite,
+        ),
+        MergeAction::SkipIdentical => (FileAction::SkippedIdentical, ConflictChoice::KeepUser),
+        MergeAction::KeepUser if overwrite => (
+            if disk_exists {
+                FileAction::Replaced
+            } else {
+                FileAction::Installed
+            },
+            ConflictChoice::Overwrite,
+        ),
+        MergeAction::KeepUser => (FileAction::KeptUser, ConflictChoice::KeepUser),
+    }
+}
+
+/// 组装一条冲突记录。
+fn conflict(
+    path: String,
+    reason: ConflictReason,
+    choice: ConflictChoice,
+    pack_sha1: &str,
+    pack_size: u64,
+    base_sha1: Option<String>,
+    disk_sha1: Option<String>,
+) -> ConflictFile {
+    ConflictFile {
+        path,
+        reason,
+        choice,
+        message_key: reason.message_key(),
+        pack_sha1: pack_sha1.to_string(),
+        pack_size,
+        base_sha1,
+        disk_sha1,
+    }
+}
+
+/// 组装一条缺失记录（条目本身补不出来）。
+fn missing_for(entry: &PlanRemote, fetcher_present: bool) -> MissingFile {
+    let reason = if fetcher_present {
+        MissingReason::NoSource
+    } else {
+        MissingReason::Offline
+    };
+    let detail = if fetcher_present {
+        "清单里没有可用下载地址，或 CurseForge 元数据补不出来（不猜 URL）"
+    } else {
+        "本次导入没有接 fetcher（离线），远端文件一律跳过"
+    };
+    missing_from_error(
+        &entry.path.clone().unwrap_or_else(|| entry.file.key()),
+        entry,
+        reason,
+        detail,
+    )
+}
+
+/// 组装一条缺失记录（已知原因与细节）。
+fn missing_from_error(
+    display: &str,
+    entry: &PlanRemote,
+    reason: MissingReason,
+    detail: &str,
+) -> MissingFile {
+    MissingFile {
+        path: entry.path.clone(),
+        display: display.to_string(),
+        project_id: entry.file.project_id,
+        file_id: entry.file.file_id,
+        reason,
+        message_key: reason.message_key(),
+        detail: detail.to_string(),
+    }
+}
+
+/// 磁盘现状的 SHA-1（不存在 ⇒ `None`）。
+fn disk_sha1(path: &Path) -> Result<Option<String>, ImportError> {
+    match std::fs::metadata(path) {
+        Ok(metadata) if metadata.is_file() => verify::digest_file(path, HashAlgo::Sha1)
+            .map(Some)
+            .map_err(|error| pack_io(format!("算 {} 的摘要失败：{error}", path.display()))),
+        Ok(_) => Ok(None),
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(None),
+        Err(error) => Err(pack_io(format!("看 {} 失败：{error}", path.display()))),
+    }
+}
+
+/// 文件的 SHA-1。
+fn digest_file(path: &Path) -> Result<String, ImportError> {
+    verify::digest_file(path, HashAlgo::Sha1)
+        .map_err(|error| pack_io(format!("算 {} 的摘要失败：{error}", path.display())))
+}
+
+/// `pack_io` 便捷构造（本地 IO 复用 M110 的稳定码，不再造新码）。
+fn pack_io(message: impl Into<String>) -> ImportError {
+    PackError::io(message).into()
+}
diff --git a/crates/core/src/addon/import/pipeline.rs b/crates/core/src/addon/import/pipeline.rs
new file mode 100644
index 0000000..22c2d04
--- /dev/null
+++ b/crates/core/src/addon/import/pipeline.rs
@@ -0,0 +1,389 @@
+//! 导入编排：**读取清单 → 解压覆盖内容 → 补全下载 → 落地 → 登记**，每步都可中断、可失败、可重试。
+//!
+//! # 两阶段落盘（任务硬要求）
+//!
+//! 先落 `overrides/`（离线、包内自带），再去补远端文件。顺序不是审美问题：
+//!
+//! - 覆盖内容是最可能被用户改过的那部分——先判定冲突，才能在"用户改过"时**既不覆盖**也不
+//!   白下载同名文件（远端条目走同一张三方合并表，冲突就直接跳过下载）；
+//! - 远端补全是唯一会失败于网络的一步，放最后意味着"网络不通"最多让结果变成 `Partial`，
+//!   不会让已经解好的覆盖内容白干。
+//!
+//! # 失败分级（判据只在一处：是不是"某个文件搞不到"）
+//!
+//! | 失败 | 结果 |
+//! |------|------|
+//! | 开包/探测/读清单/组计划失败（穿越、符号链接、限额、清单坏） | `Failed`，临时目录删掉，目标目录零残留 |
+//! | 某条远端文件摸不到（离线 / CF 无客户端 / 404） | `Partial`，逐条进 `missing`，实例照装 |
+//! | 下载到的内容与声明摘要不符 | `Failed`（这是**损坏或被换过**，不是"暂时搞不到"） |
+//! | 本地写盘失败 | `Failed` |
+//! | 实例登记失败 | `Failed`（连内容一起回滚，不留"有目录没档案"的半个实例；回滚不完整时如实列出） |
+//!
+//! **回滚也要如实**：回滚本身可能失败（文件被占用、权限），这时 `rolled_back` 为 `false`
+//! 并在 `rollback.failed` 里逐项列出——不许在"可能没回干净"时宣称一致。
+//!
+//! # 可重试
+//!
+//! 失败后目标目录与导入前一致（或明确告诉你哪几项没回去），重跑同一个包是安全的；成功后再跑
+//! 一遍会靠基线里的哈希走"跳过 / 已一致"路径，不会重复写盘。
+
+use super::super::pack::{PackArchive, PackError, PackRegistry};
+use super::baseline::PackBaseline;
+use super::error::ImportError;
+use super::phase;
+use super::plan::ImportPlan;
+use super::report::{
+    keys, ImportIssue, ImportProgress, ImportReport, ImportStage, RegisteredInstance,
+};
+use super::stage::{RollbackOutcome, Staging};
+use super::ImportRequest;
+
+/// 跑一次导入。**永不返回 `Err`**：所有失败都在报告的三态里。
+pub async fn run(request: &ImportRequest<'_>) -> ImportReport {
+    let mut report = ImportReport::empty(request.target.to_path_buf());
+
+    tell(&request.progress, ImportStage::Probe, 0, 0, None);
+    let (archive, plan) = match probe_and_plan(request) {
+        Ok(pair) => pair,
+        Err(error) => return abandoned(report, error),
+    };
+    account_plan(&mut report, &plan);
+
+    let baseline = load_baseline(request.target, &plan, &mut report);
+    let staging = match Staging::begin(request.target) {
+        Ok(staging) => staging,
+        Err(error) => return abandoned(report, error),
+    };
+
+    let mut next = baseline.clone();
+    let staged = async {
+        phase::extract_overrides(
+            request,
+            &archive,
+            &plan,
+            &baseline,
+            &staging,
+            &mut report,
+            &mut next,
+        )
+        .await?;
+        phase::fetch_remote(request, &plan, &baseline, &staging, &mut report, &mut next).await?;
+        write_baseline(&staging, &plan, &next)
+    }
+    .await;
+    if let Err(error) = staged {
+        staging.abort();
+        return abandoned(report, error);
+    }
+
+    // 引擎的续传残片（`.ullpart-*`）与 meta 不是整合包内容，提交前剔掉。
+    match staging.purge_engine_artifacts() {
+        Ok(0) => {}
+        Ok(removed) => report.warnings.push(ImportIssue::new(
+            keys::NOTE_ENGINE_ARTIFACTS_DROPPED,
+            format!("提交前剔除了 {removed} 个下载引擎的中间产物（.ullpart-* / .ullmeta.json）"),
+        )),
+        Err(error) => {
+            staging.abort();
+            return abandoned(report, error);
+        }
+    }
+
+    tell(&request.progress, ImportStage::Commit, 0, 0, None);
+    let guard = match staging.commit() {
+        Ok(guard) => guard,
+        Err(failure) => return record_rollback(failed(report, failure.error), failure.rollback),
+    };
+
+    if let Some(layout) = request.register {
+        tell(&request.progress, ImportStage::Register, 0, 0, None);
+        let name = request
+            .instance_name
+            .filter(|name| !name.trim().is_empty())
+            .unwrap_or(plan.manifest.name.as_str());
+        match crate::game::install::register(layout, name, &plan.version_id, None) {
+            Ok(registration) => {
+                report.registered = Some(RegisteredInstance {
+                    id: registration.profile.id.as_str().to_string(),
+                    name: registration.profile.name.clone(),
+                    version_id: registration.profile.version_id.clone(),
+                    created: registration.created,
+                });
+                report.warnings.push(ImportIssue::new(
+                    keys::NOTE_REGISTERED,
+                    format!(
+                        "已登记实例 {:?}（{}）",
+                        registration.profile.name, plan.version_id
+                    ),
+                ));
+            }
+            Err(error) => {
+                // 内容落盘了但档案没建起来 = 用户看不见的半个实例 ⇒ 连内容一起回滚。
+                let outcome = guard.rollback();
+                return record_rollback(
+                    failed(report, ImportError::instance(error.to_string())),
+                    outcome,
+                );
+            }
+        }
+    }
+    guard.finish();
+
+    report.finish_status();
+    report
+}
+
+/// 开包 + 探测 + 组计划（任何失败都是 `Failed`）。
+fn probe_and_plan(request: &ImportRequest<'_>) -> Result<(PackArchive, ImportPlan), ImportError> {
+    // 路径穿越双检 + 符号链接 + 条数/体积限额都在 `open` 里一次做完（M110 的 `archive`）。
+    let archive = PackArchive::open(request.pack, request.limits)?;
+    let (format, manifest) = PackRegistry::builtin().read(&archive)?;
+    let plan = ImportPlan::build(&archive, format.id(), manifest)?;
+    Ok((archive, plan))
+}
+
+/// 把计划里的静态信息抄进报告。
+fn account_plan(report: &mut ImportReport, plan: &ImportPlan) {
+    report.format = Some(plan.format.clone());
+    report.pack_name = Some(plan.manifest.name.clone());
+    report.pack_version = plan.manifest.version.clone();
+    report.game_version = Some(plan.mc_version.clone());
+    report.loader = plan.loader.clone();
+    report.version_id = Some(plan.version_id.clone());
+    report.max_memory_mb = plan.max_memory_mb;
+    report.rejected_components.clone_from(&plan.rejected);
+    report.warnings.extend(plan.notes.iter().cloned());
+}
+
+/// 读三方合并的 base 侧：没有 / 读不出来 / **属于别的包** 三条路都不致命。
+///
+/// "属于别的包"要单独说一句：同一目录先后导入两个整合包时，若拿别人的基线当 base，用户改过
+/// 的文件会被判成"整合包升级"而**被静默覆盖**。所以身份不符时降级成"没有基线"并告警。
+fn load_baseline(
+    target: &std::path::Path,
+    plan: &ImportPlan,
+    report: &mut ImportReport,
+) -> PackBaseline {
+    match PackBaseline::load(target) {
+        Ok(baseline) => {
+            if baseline.matches_pack(&plan.format, &plan.manifest.name) {
+                return baseline;
+            }
+            report.warnings.push(ImportIssue::new(
+                keys::NOTE_BASELINE_PACK_MISMATCH,
+                format!(
+                    "基线属于另一个整合包（{} / {:?}），本次按「没有基线」处理：磁盘上同名文件一律算用户已有内容",
+                    if baseline.format.is_empty() {
+                        "?"
+                    } else {
+                        &baseline.format
+                    },
+                    baseline.pack_name
+                ),
+            ));
+            PackBaseline::default()
+        }
+        Err(reason) => {
+            report.warnings.push(ImportIssue::new(
+                keys::NOTE_BASELINE_UNREADABLE,
+                format!(
+                    "基线读不出来，本次按「没有基线」处理（磁盘上同名文件一律算用户已有内容）：{reason}"
+                ),
+            ));
+            PackBaseline::default()
+        }
+    }
+}
+
+/// 把一次回滚的结果写进报告：**文案与机器位同源**，只有完整回滚才宣称"与导入前一致"。
+fn record_rollback(mut report: ImportReport, outcome: RollbackOutcome) -> ImportReport {
+    if outcome.is_complete() {
+        report.rolled_back = true;
+        report.warnings.push(ImportIssue::new(
+            keys::ROLLBACK_DONE,
+            format!(
+                "已回滚 {} 项：目标目录恢复为导入前的样子（{}）",
+                outcome.attempted,
+                report.target.display()
+            ),
+        ));
+    } else {
+        report.rolled_back = false;
+        report.warnings.push(ImportIssue::new(
+            keys::NOTE_ROLLBACK_INCOMPLETE,
+            format!(
+                "有 {} 项未能回滚（目标目录可能与导入前不同）：{}",
+                outcome.failure_count(),
+                outcome.failed.join("；")
+            ),
+        ));
+    }
+    report.rollback = Some(outcome);
+    report
+}
+
+/// 基线作为**最后一个暂存文件**写进去：它跟同一个事务一起提交 / 回滚。
+fn write_baseline(
+    staging: &Staging,
+    plan: &ImportPlan,
+    next: &PackBaseline,
+) -> Result<(), ImportError> {
+    let mut baseline = next.clone();
+    baseline.pack_name.clone_from(&plan.manifest.name);
+    baseline.format.clone_from(&plan.format);
+    let bytes = baseline.to_bytes().map_err(PackError::io)?;
+    staging.write(&baseline_relative(), &bytes)?;
+    Ok(())
+}
+
+/// 基线相对实例根的路径（`<根>/.ull/pack-baseline.json`；与读侧同源，见
+/// [`PackBaseline::relative_path`]）。
+#[must_use]
+pub fn baseline_relative() -> String {
+    PackBaseline::relative_path()
+        .to_string_lossy()
+        .replace('\\', "/")
+}
+
+/// 发一条进度事件（`sink` 为 `None` 时什么都不做）。
+pub(super) fn tell(
+    sink: &Option<super::report::ImportProgressSink>,
+    stage: ImportStage,
+    done: usize,
+    total: usize,
+    current: Option<String>,
+) {
+    if let Some(sink) = sink {
+        sink(&ImportProgress {
+            stage,
+            done,
+            total,
+            current,
+        });
+    }
+}
+
+/// 失败收尾：**只落错误，不宣称目标目录状态**。
+///
+/// 口径由调用方补：从未写过目标目录 ⇒ [`abandoned`]；已经写过 ⇒ [`record_rollback`]。
+/// 早先这里无条件推"目标目录保持导入前的样子"，而随后的 `record_rollback` 可能再推
+/// "有 N 项未能回滚"——同一份 warnings 自相矛盾（复审 r6 抓到）。
+fn failed(mut report: ImportReport, error: ImportError) -> ImportReport {
+    report.rolled_back = false;
+    report.fail(error);
+    report
+}
+
+/// 失败发生在**碰目标目录之前**（暂存目录已清）：这时才可以宣称"目标目录未被写入"。
+fn abandoned(report: ImportReport, error: ImportError) -> ImportReport {
+    let mut report = failed(report, error);
+    report.rolled_back = true;
+    report.warnings.push(ImportIssue::new(
+        keys::ROLLBACK_DONE,
+        format!(
+            "导入失败，已清理临时目录；目标目录未被写入（{}）",
+            report.target.display()
+        ),
+    ));
+    report
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::addon::import::ImportStatus;
+
+    fn base() -> ImportReport {
+        ImportReport::empty(std::path::PathBuf::from("instance"))
+    }
+
+    fn messages(report: &ImportReport) -> Vec<&str> {
+        report
+            .warnings
+            .iter()
+            .map(|note| note.message.as_str())
+            .collect()
+    }
+
+    fn incomplete() -> RollbackOutcome {
+        RollbackOutcome {
+            attempted: 3,
+            failed: vec!["删除 config/a.toml 失败：拒绝访问".to_string()],
+        }
+    }
+
+    #[test]
+    fn incomplete_rollback_never_claims_the_target_is_untouched() {
+        // 复审 r6 第 1 条：机器位（rolled_back=false）诚实，文案位也必须诚实——同一份 warnings
+        // 里不许同时出现"保持导入前的样子"与"有 N 项未能回滚"。
+        let report = record_rollback(failed(base(), ImportError::fetch("提交失败")), incomplete());
+
+        assert_eq!(report.status, ImportStatus::Failed);
+        assert!(!report.rolled_back, "回滚不完整时不许宣称一致");
+        assert_eq!(
+            report.rollback.as_ref().map(RollbackOutcome::failure_count),
+            Some(1)
+        );
+        let messages = messages(&report);
+        assert!(
+            messages
+                .iter()
+                .any(|line| line.contains("未能回滚") && line.contains("config/a.toml")),
+            "失败项要逐条列出：{messages:?}"
+        );
+        assert!(
+            !messages.iter().any(|line| line.contains("保持导入前的样子")
+                || line.contains("未被写入")
+                || line.contains("恢复为导入前的样子")),
+            "回滚不完整却宣称一致（自相矛盾）：{messages:?}"
+        );
+    }
+
+    #[test]
+    fn complete_rollback_claims_consistency_exactly_once() {
+        let report = record_rollback(
+            failed(base(), ImportError::fetch("提交失败")),
+            RollbackOutcome {
+                attempted: 2,
+                failed: Vec::new(),
+            },
+        );
+
+        assert!(report.rolled_back);
+        assert_eq!(
+            report.rollback.as_ref().map(RollbackOutcome::failure_count),
+            Some(0)
+        );
+        let messages = messages(&report);
+        assert!(
+            messages
+                .iter()
+                .any(|line| line.contains("恢复为导入前的样子")),
+            "{messages:?}"
+        );
+        assert!(
+            !messages.iter().any(|line| line.contains("未能回滚")),
+            "{messages:?}"
+        );
+    }
+
+    #[test]
+    fn pre_commit_failure_claims_untouched_only_via_abandoned() {
+        // `failed()` 本身不宣称任何目标目录状态；"从未写过目标目录"这条口径只由 `abandoned()` 给。
+        let bare = failed(base(), ImportError::fetch("开包失败"));
+        assert!(!bare.rolled_back);
+        assert!(bare.rollback.is_none());
+        assert!(!messages(&bare)
+            .iter()
+            .any(|line| line.contains("保持导入前的样子") || line.contains("未被写入")));
+
+        let report = abandoned(base(), ImportError::fetch("开包失败"));
+        assert!(report.rolled_back);
+        assert!(report.rollback.is_none());
+        let messages = messages(&report);
+        assert!(
+            messages.iter().any(|line| line.contains("未被写入")),
+            "{messages:?}"
+        );
+    }
+}
diff --git a/crates/core/src/addon/import/plan.rs b/crates/core/src/addon/import/plan.rs
new file mode 100644
index 0000000..f9d5631
--- /dev/null
+++ b/crates/core/src/addon/import/plan.rs
@@ -0,0 +1,373 @@
+//! 清单 → **导入计划**：把三种格式的差异在进解压器之前全部拍平。
+//!
+//! 计划是纯计算（只额外读一次 `instance.cfg`），产出四张表：覆盖条目、远端条目、
+//! 加载器计划输入、被拒绝的 component。落盘与合并都不在这里。
+//!
+//! # 三种格式的语义在这层定死
+//!
+//! | 事 | CurseForge | Modrinth | MultiMC / Prism |
+//! |----|-----------|----------|-----------------|
+//! | 覆盖目录 | 清单点名的**一个**目录（任意名字） | `overrides/` + `client-overrides/`（`server-overrides/` **不解压**） | `.minecraft/` |
+//! | 同名冲突 | 不存在（单目录） | `client-overrides` **胜** `overrides`（Modrinth 官方客户端语义；与 HMCL 相反） | 不存在 |
+//! | 远端条目 | `projectID/fileID`，**无路径无地址** ⇒ 必须补全 | 自带 `path`/`downloads`/`hashes` | 没有远端条目（内容就是目录） |
+//! | 加载器 | `modLoaders[].id`（`neoforge-1.20.1-47.1.106` 的版本段**带 MC 前缀**） | `dependencies` 的键 | `components[].uid` |
+//! # 三处"不许自创"的边界
+//!
+//! 1. **覆盖目录的优先级只按侧**：`overrides/` 先、`client-overrides/` 后（后者胜）。同一
+//!    目录内的条目顺序**不重要**——M110 的 [`crate::addon::pack::PackOverrides::files`] 按路径
+//!    排序，zip 条目顺序没有保留；而同一目录内路径唯一，所以"按 zip 条目顺序落盘"与"按路径
+//!    排序落盘"在无重复时等价。有重复（跨目录）时由侧优先级决定，不靠条目顺序。
+//! 2. **`.disabled` 只认路径后缀**（官方 Modrinth 表达），`.old` **只识别与保留**（不清不删
+//!    不改名）。`env.client=optional` **不是**禁用（"可选"＝安装时可取消勾选）。判据在
+//!    [`paths`]。
+//! 3. **MultiMC 的非加载器 component 逐项进报告**（`org.lwjgl3` / `net.fabricmc.intermediary`
+//!    / 社区自定义 uid）：静默丢它们等于"看起来装好了、其实少了补丁层"。
+
+pub mod paths;
+
+pub use paths::{curse_class_dir, strip_mc_prefix, suffix_note, suffix_variant, SuffixVariant};
+
+use super::super::pack::{
+    curseforge, multimc, EnvSupport, PackArchive, PackError, PackFile, PackLoader, PackManifest,
+    PackOverrides, PackSide,
+};
+use super::error::ImportError;
+use super::report::{keys, FileSource, ImportIssue, LoaderTarget, RejectedComponent};
+
+/// 一条要落地的覆盖条目。
+#[derive(Debug, Clone)]
+pub struct PlanOverride {
+    /// 包内目录前缀（读包时拼 `<dir>/<path>`）。
+    pub dir: String,
+    /// 实例内相对路径。
+    pub path: String,
+    /// 来源侧。
+    pub source: FileSource,
+    /// 包内实际 SHA-1（M110 读包时现算）。
+    pub sha1: String,
+    /// 字节数。
+    pub size: u64,
+    /// 是否禁用态（路径后缀）。
+    pub disabled: bool,
+    /// 可选注记（`.disabled` / `.old`）。
+    pub note: Option<ImportIssue>,
+}
+
+/// 一条要补全/下载的远端条目。
+#[derive(Debug, Clone)]
+pub struct PlanRemote {
+    /// 原清单条目（摘要表 / downloads / env / project/file id 都在里面）。
+    pub file: PackFile,
+    /// 已知的实例内相对路径（mrpack 有；CF 需要补全才有）。
+    pub path: Option<String>,
+    /// 来源。
+    pub source: FileSource,
+    /// 是否禁用态（路径后缀）。
+    pub disabled: bool,
+}
+
+/// 一次导入的计划。
+#[derive(Debug, Clone)]
+pub struct ImportPlan {
+    /// 命中的格式 id。
+    pub format: String,
+    /// 原始模型（`extra` 等诊断信息留着）。
+    pub manifest: PackManifest,
+    /// 游戏版本。
+    pub mc_version: String,
+    /// 加载器安装计划输入（`None` = 纯原版）。
+    pub loader: Option<LoaderTarget>,
+    /// 实例绑定版本 id。
+    pub version_id: String,
+    /// 不支持的 component（逐项）。
+    pub rejected: Vec<RejectedComponent>,
+    /// 注记。
+    pub notes: Vec<ImportIssue>,
+    /// 覆盖条目（已按侧优先级排好、已剔除 `server-overrides`）。
+    pub overrides: Vec<PlanOverride>,
+    /// 远端条目。
+    pub remote: Vec<PlanRemote>,
+    /// `instance.cfg` 里受开关门控的内存上限（MB）。
+    pub max_memory_mb: Option<u64>,
+}
+
+impl ImportPlan {
+    /// 组计划。
+    ///
+    /// # Errors
+    ///
+    /// 清单缺游戏版本、加载器条目缺版本号、MultiMC 的 `formatVersion != 1` 等"清单自身非法"
+    /// 的情形返回 [`ImportError`]（调用方据此整包回滚）。"某条文件缺地址"**不是**错误。
+    pub fn build(
+        pack: &PackArchive,
+        format_id: &str,
+        manifest: PackManifest,
+    ) -> Result<Self, ImportError> {
+        let mut notes: Vec<ImportIssue> = Vec::new();
+        let mut rejected: Vec<RejectedComponent> = Vec::new();
+
+        // Prism 的规矩（A 级来源 `PackProfile.cpp:207-210`）：`formatVersion` 必须恰为 1，
+        // 否则**整份丢弃**——不是降级解析。M110 的读者把缺省值当 1（老包不写这一行），
+        // 因此这里只拒"写了非 1 的值"。
+        if format_id == multimc::ID && manifest.format_version != Some(1) {
+            return Err(ImportError::from(PackError::metadata(format!(
+                "{} 的 formatVersion 是 {:?}，必须恰为 1（Prism 自己也是整份丢弃，不降级解析）",
+                multimc::METADATA_ENTRY,
+                manifest.format_version
+            ))));
+        }
+
+        let mc_version = manifest
+            .minecraft
+            .as_deref()
+            .map(str::trim)
+            .filter(|version| !version.is_empty())
+            .map(str::to_string)
+            .ok_or_else(|| {
+                ImportError::from(PackError::metadata(
+                    "清单里没有游戏版本（CF minecraft.version / mrpack dependencies.minecraft / MultiMC net.minecraft 组件）",
+                ))
+            })?;
+
+        let loader = select_loader(&manifest, &mc_version, format_id, &mut notes, &mut rejected)?;
+        let version_id = loader
+            .as_ref()
+            .map_or_else(|| mc_version.clone(), |target| target.version_id.clone());
+
+        let mut overrides: Vec<PlanOverride> = Vec::new();
+        let mut skipped_server_files = 0_usize;
+        for group in ordered_overrides(&manifest) {
+            if group.side == PackSide::Server {
+                // Modrinth 官方客户端安装器就不解压 server-overrides/（A 级来源：
+                // install_mrpack.rs 的 strip_prefix 链只有 overrides/ 与 client-overrides/）。
+                skipped_server_files += group.files.len();
+                continue;
+            }
+            for file in &group.files {
+                let variant = suffix_variant(&file.path);
+                overrides.push(PlanOverride {
+                    dir: group.dir.clone(),
+                    path: file.path.clone(),
+                    source: FileSource::from_side(group.side),
+                    sha1: file.sha1.clone(),
+                    size: file.size,
+                    disabled: variant.is_disabled(),
+                    note: suffix_note(variant, &file.path),
+                });
+            }
+        }
+        if skipped_server_files > 0 {
+            notes.push(ImportIssue::new(
+                keys::NOTE_SERVER_OVERRIDES_SKIPPED,
+                format!(
+                    "server-overrides/ 里的 {skipped_server_files} 个文件是服务端内容，客户端导入不解压（Modrinth 官方语义）"
+                ),
+            ));
+        }
+
+        let mut remote: Vec<PlanRemote> = Vec::new();
+        let source = if format_id == curseforge::ID {
+            FileSource::CurseForge
+        } else {
+            FileSource::Modrinth
+        };
+        for file in &manifest.files {
+            if file.client == EnvSupport::Unsupported {
+                notes.push(
+                    ImportIssue::new(
+                        keys::NOTE_ENV_UNSUPPORTED,
+                        "env.client=unsupported：客户端不需要这个文件，跳过".to_string(),
+                    )
+                    .with_path(file.path.clone().unwrap_or_else(|| file.key())),
+                );
+                continue;
+            }
+            let variant = file
+                .path
+                .as_deref()
+                .map_or(SuffixVariant::Plain, suffix_variant);
+            if file.client == EnvSupport::Optional {
+                notes.push(
+                    ImportIssue::new(
+                        keys::NOTE_OPTIONAL_FILE,
+                        "env.client=optional：可选条目照常安装（「可选」不等于「禁用」）"
+                            .to_string(),
+                    )
+                    .with_path(file.path.clone().unwrap_or_else(|| file.key())),
+                );
+            }
+            if let Some(note) = file
+                .path
+                .as_deref()
+                .and_then(|path| suffix_note(variant, path))
+            {
+                notes.push(note);
+            }
+            remote.push(PlanRemote {
+                path: file.path.clone(),
+                source,
+                disabled: variant.is_disabled(),
+                file: file.clone(),
+            });
+        }
+
+        let max_memory_mb = if format_id == multimc::ID {
+            instance_memory(pack, &mut notes)?
+        } else {
+            None
+        };
+
+        Ok(Self {
+            format: format_id.to_string(),
+            manifest,
+            mc_version,
+            loader,
+            version_id,
+            rejected,
+            notes,
+            overrides,
+            remote,
+            max_memory_mb,
+        })
+    }
+}
+
+/// 覆盖目录按侧排序：`Both`（`overrides/`）先、`Client`（`client-overrides/`）后 = 后者胜。
+fn ordered_overrides(manifest: &PackManifest) -> Vec<&PackOverrides> {
+    let mut groups: Vec<&PackOverrides> = manifest.overrides.iter().collect();
+    groups.sort_by_key(|group| match group.side {
+        PackSide::Both => 0_u8,
+        PackSide::Client => 1,
+        PackSide::Server => 2,
+    });
+    groups
+}
+
+/// 选一个加载器并翻译成 [`LoaderTarget`]。
+fn select_loader(
+    manifest: &PackManifest,
+    mc_version: &str,
+    format_id: &str,
+    notes: &mut Vec<ImportIssue>,
+    rejected: &mut Vec<RejectedComponent>,
+) -> Result<Option<LoaderTarget>, ImportError> {
+    let recognized: Vec<&PackLoader> = manifest
+        .loaders
+        .iter()
+        .filter(|loader| loader.kind.is_some())
+        .collect();
+
+    // 认不出的条目：MultiMC 是"不支持的 component"（逐项列），其它格式是"不认识的依赖键"。
+    for loader in manifest
+        .loaders
+        .iter()
+        .filter(|loader| loader.kind.is_none())
+    {
+        if format_id == multimc::ID {
+            rejected.push(RejectedComponent {
+                uid: loader.raw.clone(),
+                version: loader.version.clone(),
+                message_key: keys::REJECTED_COMPONENT,
+            });
+        } else {
+            notes.push(ImportIssue::new(
+                keys::NOTE_UNKNOWN_DEPENDENCY,
+                format!("认不出的加载器/依赖键 {:?}：本启动器不安装它", loader.raw),
+            ));
+        }
+    }
+
+    if recognized.len() > 1 {
+        notes.push(ImportIssue::new(
+            keys::NOTE_LOADER_MULTIPLE,
+            format!(
+                "清单里有 {} 个可识别的加载器，只按 primary/第一条组计划：{}",
+                recognized.len(),
+                recognized
+                    .iter()
+                    .map(|loader| loader.raw.as_str())
+                    .collect::<Vec<_>>()
+                    .join(", ")
+            ),
+        ));
+    }
+
+    let Some(loader) = recognized
+        .iter()
+        .find(|loader| loader.primary)
+        .or_else(|| recognized.first())
+        .copied()
+    else {
+        return Ok(None);
+    };
+    let Some(kind) = loader.kind else {
+        return Ok(None);
+    };
+    let raw_version = loader
+        .version
+        .as_deref()
+        .map(str::trim)
+        .filter(|version| !version.is_empty())
+        .ok_or_else(|| {
+            ImportError::loader(format!(
+                "加载器条目 {:?} 没有版本号，组不出安装计划（清单自身非法）",
+                loader.raw
+            ))
+        })?;
+    let loader_version = strip_mc_prefix(mc_version, raw_version);
+    Ok(Some(LoaderTarget {
+        kind,
+        mc_version: mc_version.to_string(),
+        version_id: kind.version_id(mc_version, &loader_version),
+        loader_version,
+        raw: loader.raw.clone(),
+    }))
+}
+
+/// 从 `instance.cfg` 取受开关门控的内存上限（MB）。
+fn instance_memory(
+    pack: &PackArchive,
+    notes: &mut Vec<ImportIssue>,
+) -> Result<Option<u64>, ImportError> {
+    let Some(text) = pack.read_text(multimc::INSTANCE_ENTRY)? else {
+        return Ok(None);
+    };
+    let mut values: Vec<(&str, &str)> = Vec::new();
+    for line in text.lines() {
+        let line = line.trim();
+        if line.is_empty() || line.starts_with('#') || line.starts_with(';') {
+            continue;
+        }
+        // `[General]` 这类小节标记直接跳过：instance.cfg 平铺，真出现也不该把它们当键。
+        if line.starts_with('[') {
+            continue;
+        }
+        // 值里含 `:` 与 `\`（Windows 路径）是常态，所以只按**第一个** `=` 切。
+        if let Some((key, value)) = line.split_once('=') {
+            values.push((key.trim(), value.trim()));
+        }
+    }
+    let get = |name: &str| -> Option<&str> {
+        values
+            .iter()
+            .find(|(key, _)| key.eq_ignore_ascii_case(name))
+            .map(|(_, value)| *value)
+    };
+    let Some(max) = get("MaxMemAlloc").and_then(|value| value.parse::<u64>().ok()) else {
+        return Ok(None);
+    };
+    // Prism 的规矩：这些值只在开关为 true 时生效（只看值不看开关会误判）。
+    let enabled = get("OverrideMemory").is_some_and(|value| value.eq_ignore_ascii_case("true"));
+    if !enabled {
+        notes.push(ImportIssue::new(
+            keys::NOTE_INSTANCE_CFG_MEMORY,
+            format!("instance.cfg 写了 MaxMemAlloc={max}，但 OverrideMemory 未开：不采用"),
+        ));
+        return Ok(None);
+    }
+    notes.push(ImportIssue::new(
+        keys::NOTE_INSTANCE_CFG_MEMORY,
+        format!("从 instance.cfg 取到内存上限 {max} MB（OverrideMemory=true）"),
+    ));
+    Ok(Some(max))
+}
diff --git a/crates/core/src/addon/import/plan/paths.rs b/crates/core/src/addon/import/plan/paths.rs
new file mode 100644
index 0000000..366596e
--- /dev/null
+++ b/crates/core/src/addon/import/plan/paths.rs
@@ -0,0 +1,160 @@
+//! 路径与版本号的小判据（纯函数）：`.disabled` / `.old` 后缀变体与注记、CF 类别目录、MC 版本前缀。
+//!
+//! 拆出来是因为它们是**格式事实**而非管线逻辑：`.disabled` 只按路径后缀（tower 定案，不用
+//! `env.client=optional`）、`.old` 只识别与保留（不清不删）、CF 的 `classId` 认不出就不猜。
+
+use super::super::report::{keys, ImportIssue};
+
+/// 路径后缀变体（`.disabled` / `.old` 的四种组合）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SuffixVariant {
+    /// `mods/x.jar`。
+    Plain,
+    /// `mods/x.jar.disabled`（官方 Modrinth 的禁用表达）。
+    Disabled,
+    /// `mods/x.jar.old`（HMCL 生态常见：旧版本残留）。
+    Old,
+    /// `mods/x.jar.disabled.old`。
+    DisabledOld,
+}
+
+impl SuffixVariant {
+    /// 是否禁用态。
+    #[must_use]
+    pub const fn is_disabled(self) -> bool {
+        matches!(self, Self::Disabled | Self::DisabledOld)
+    }
+
+    /// 是否带 `.old`（只用于报告，不附加清理语义）。
+    #[must_use]
+    pub const fn is_old(self) -> bool {
+        matches!(self, Self::Old | Self::DisabledOld)
+    }
+}
+
+/// 识别四种路径后缀变体。
+#[must_use]
+pub fn suffix_variant(path: &str) -> SuffixVariant {
+    let lowered = path.trim_end().to_ascii_lowercase();
+    let stripped = lowered.strip_suffix(".old").unwrap_or(&lowered);
+    let old = stripped.len() != lowered.len();
+    let disabled = stripped.ends_with(".disabled");
+    match (disabled, old) {
+        (false, false) => SuffixVariant::Plain,
+        (true, false) => SuffixVariant::Disabled,
+        (false, true) => SuffixVariant::Old,
+        (true, true) => SuffixVariant::DisabledOld,
+    }
+}
+
+/// 后缀注记（`.disabled` / `.old`）：进报告，告诉用户"这个名字我们是认得的"。
+#[must_use]
+pub fn suffix_note(variant: SuffixVariant, path: &str) -> Option<ImportIssue> {
+    match variant {
+        SuffixVariant::Plain => None,
+        SuffixVariant::Disabled => Some(
+            ImportIssue::new(
+                keys::NOTE_DISABLED_SUFFIX,
+                "路径以 .disabled 结尾：按禁用态安装，后缀原样保留".to_string(),
+            )
+            .with_path(path),
+        ),
+        SuffixVariant::Old => Some(
+            ImportIssue::new(
+                keys::NOTE_OLD_SUFFIX,
+                "路径以 .old 结尾：识别并原样保留（不清除、不改名）".to_string(),
+            )
+            .with_path(path),
+        ),
+        SuffixVariant::DisabledOld => Some(
+            ImportIssue::new(
+                keys::NOTE_DISABLED_SUFFIX,
+                "路径以 .disabled.old 结尾：禁用态的旧文件，原样保留".to_string(),
+            )
+            .with_path(path),
+        ),
+    }
+}
+
+/// CurseForge `classId` → 实例内目录（**认不出的类别返回 `None`**，由调用方告警）。
+///
+/// 依据：CF 官方 `classId` 枚举（`6` mods / `12` resource packs / `6945` shaders /
+/// `17` worlds / `4546` customization / `4471` modpacks）。未知类别**不猜**：
+/// 计划层返回 `None`，导入时进 `missing`/告警，而不是"随手塞进 mods/"。
+#[must_use]
+pub const fn curse_class_dir(class_id: i64) -> Option<&'static str> {
+    match class_id {
+        6 => Some("mods"),
+        12 => Some("resourcepacks"),
+        6945 => Some("shaderpacks"),
+        17 => Some("saves"),
+        4546 => Some("customize"),
+        _ => None,
+    }
+}
+
+/// 剥掉 CF 在版本段里又写一遍的 MC 前缀（`neoforge-1.20.1-47.1.106` 的坑）。
+///
+/// 只在"版本段以 `<mc>-` 开头"时剥——这是 CF 导出器在 NeoForge/Forge 上会写出的形状
+/// （A 级来源 `FlamePackExportTask.cpp:404-410`）。不按 `-` 硬切第三段：`47.1.106` 本身
+/// 也有不同风格，切错会把版本号喂成 `1.20.1`。
+#[must_use]
+pub fn strip_mc_prefix(mc_version: &str, loader_version: &str) -> String {
+    let prefix = format!("{mc_version}-");
+    loader_version
+        .strip_prefix(&prefix)
+        .filter(|rest| !rest.is_empty())
+        .unwrap_or(loader_version)
+        .to_string()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn recognises_four_suffix_variants() {
+        assert_eq!(suffix_variant("mods/x.jar"), SuffixVariant::Plain);
+        assert_eq!(
+            suffix_variant("mods/x.jar.disabled"),
+            SuffixVariant::Disabled
+        );
+        assert_eq!(suffix_variant("mods/x.jar.old"), SuffixVariant::Old);
+        assert_eq!(
+            suffix_variant("mods/x.jar.disabled.old"),
+            SuffixVariant::DisabledOld
+        );
+        assert!(suffix_variant("mods/x.jar.disabled").is_disabled());
+        assert!(!suffix_variant("mods/x.jar.old").is_disabled());
+        assert!(suffix_variant("mods/x.jar.old").is_old());
+    }
+
+    #[test]
+    fn suffix_notes_only_for_recognised_variants() {
+        assert!(suffix_note(SuffixVariant::Plain, "mods/x.jar").is_none());
+        let disabled = suffix_note(SuffixVariant::Disabled, "mods/x.jar.disabled").expect("有注记");
+        assert_eq!(disabled.message_key, keys::NOTE_DISABLED_SUFFIX);
+        assert_eq!(disabled.path.as_deref(), Some("mods/x.jar.disabled"));
+        let old = suffix_note(SuffixVariant::Old, "mods/x.jar.old").expect("有注记");
+        assert_eq!(old.message_key, keys::NOTE_OLD_SUFFIX);
+    }
+
+    #[test]
+    fn strips_mc_prefix_from_loader_version() {
+        // NeoForge 在 1.20.1 上的真实形状。
+        assert_eq!(strip_mc_prefix("1.20.1", "1.20.1-47.1.106"), "47.1.106");
+        // 没有前缀的照原样（Fabric / 正常 Forge）。
+        assert_eq!(strip_mc_prefix("1.20.1", "0.15.11"), "0.15.11");
+        // 只剥一层，且剥完不能是空串。
+        assert_eq!(strip_mc_prefix("1.20.1", "1.20.1-"), "1.20.1-");
+    }
+
+    #[test]
+    fn knows_curse_class_directories() {
+        assert_eq!(curse_class_dir(6), Some("mods"));
+        assert_eq!(curse_class_dir(12), Some("resourcepacks"));
+        assert_eq!(curse_class_dir(6945), Some("shaderpacks"));
+        // 认不出的类别不猜。
+        assert_eq!(curse_class_dir(999_999), None);
+    }
+}
diff --git a/crates/core/src/addon/import/report.rs b/crates/core/src/addon/import/report.rs
new file mode 100644
index 0000000..9181c2d
--- /dev/null
+++ b/crates/core/src/addon/import/report.rs
@@ -0,0 +1,243 @@
+//! 导入结果：**三态 + 逐项原因**，给 CLI 的 `--json` 与 M109/M113 的页面直接消费。
+//!
+//! # 三态不是"成功/失败"两态（M111 任务原文要求）
+//!
+//! | 状态 | 判据 | 退出码（CLI） |
+//! |------|------|---------------|
+//! | [`ImportStatus::Success`] | 清单里每条文件都落地、没有冲突 | `0` |
+//! | [`ImportStatus::Partial`] | 有"搞不到"的文件（[`MissingFile`]）或有保留用户文件的冲突（[`ConflictFile`]） | `3` |
+//! | [`ImportStatus::Failed`] | 致命错误（[`ImportError`]），**已整包回滚** | `1` |
+//!
+//! 把"部分成功"记成 `Success` 是这条管线最容易犯的错：用户会以为 mods 齐了，启动才发现缺
+//! 依赖。所以 [`ImportReport::finish_status`] 是**唯一**算状态的地方，字段私有语义由它收敛。
+//!
+//! # 分文件
+//!
+//! - [`keys`]：文案 key 常量表（稳定字符串，含 `ALL` 守门表）；
+//! - [`items`]：条目类型（一条文件 / 一条冲突 / 一条缺失 / 一个 component / 加载器目标）；
+//! - 本文件：三态、阶段、进度、以及总的 [`ImportReport`]。
+
+pub mod items;
+pub mod keys;
+
+pub use items::{
+    ConflictChoice, ConflictFile, ConflictReason, FileAction, FileSource, ImportIssue,
+    ImportedFile, LoaderTarget, MissingFile, MissingReason, RegisteredInstance, RejectedComponent,
+};
+
+use std::path::PathBuf;
+
+use serde::Serialize;
+
+use super::error::ImportError;
+use super::stage::RollbackOutcome;
+
+/// 导入三态。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ImportStatus {
+    /// 全部落地、无冲突。
+    Success,
+    /// 有缺文件或有冲突（内容不完整，但实例可用）。
+    Partial,
+    /// 致命失败，已整包回滚。
+    Failed,
+}
+
+impl ImportStatus {
+    /// 稳定字符串 id。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Success => "success",
+            Self::Partial => "partial",
+            Self::Failed => "failed",
+        }
+    }
+
+    /// 文案 key。
+    #[must_use]
+    pub const fn message_key(self) -> &'static str {
+        match self {
+            Self::Success => keys::STATUS_SUCCESS,
+            Self::Partial => keys::STATUS_PARTIAL,
+            Self::Failed => keys::STATUS_FAILED,
+        }
+    }
+
+    /// CLI 退出码：`0` / `3` / `1`（`2` 留给内部错误，`1` 与用法错误同码但 JSON 里可区分）。
+    #[must_use]
+    pub const fn exit_code(self) -> i32 {
+        match self {
+            Self::Success => 0,
+            Self::Partial => 3,
+            Self::Failed => 1,
+        }
+    }
+}
+
+/// 导入阶段（进度回调按这个分组）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ImportStage {
+    /// 读取清单（开包 + 安全四检 + 探测 + 读成模型）。
+    Probe,
+    /// 解压 / 三方合并覆盖内容。
+    Extract,
+    /// 补全并下载远端文件。
+    Fetch,
+    /// 落地（临时目录 rename 或 journal 合并）。
+    Commit,
+    /// 登记实例。
+    Register,
+}
+
+impl ImportStage {
+    /// 稳定字符串 id。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Probe => "probe",
+            Self::Extract => "extract",
+            Self::Fetch => "fetch",
+            Self::Commit => "commit",
+            Self::Register => "register",
+        }
+    }
+
+    /// 文案 key。
+    #[must_use]
+    pub const fn message_key(self) -> &'static str {
+        match self {
+            Self::Probe => keys::STAGE_PROBE,
+            Self::Extract => keys::STAGE_EXTRACT,
+            Self::Fetch => keys::STAGE_FETCH,
+            Self::Commit => keys::STAGE_COMMIT,
+            Self::Register => keys::STAGE_REGISTER,
+        }
+    }
+}
+
+/// 一条进度事件（同步回调，跨线程安全）。
+#[derive(Debug, Clone, Serialize)]
+pub struct ImportProgress {
+    /// 当前阶段。
+    pub stage: ImportStage,
+    /// 阶段内已完成条目数。
+    pub done: usize,
+    /// 阶段内总条目数（未知时为 0）。
+    pub total: usize,
+    /// 当前条目的实例内路径（阶段刚开始时为 `None`）。
+    pub current: Option<String>,
+}
+
+/// 进度回调。
+pub type ImportProgressSink = std::sync::Arc<dyn Fn(&ImportProgress) + Send + Sync>;
+
+/// 一次导入的完整结果。
+#[derive(Debug, Clone, Serialize)]
+pub struct ImportReport {
+    /// 三态。
+    pub status: ImportStatus,
+    /// 命中的格式 id（`curseforge` / `modrinth` / `multimc`）。
+    pub format: Option<String>,
+    /// 包名。
+    pub pack_name: Option<String>,
+    /// 包版本。
+    pub pack_version: Option<String>,
+    /// 游戏版本。
+    pub game_version: Option<String>,
+    /// 加载器安装计划输入（没有加载器时 `None` = 纯原版）。
+    pub loader: Option<LoaderTarget>,
+    /// 实例绑定的版本 id。
+    pub version_id: Option<String>,
+    /// 目标实例目录。
+    pub target: PathBuf,
+    /// 落地的文件（含 `SkippedIdentical`）。
+    pub files: Vec<ImportedFile>,
+    /// 冲突清单。
+    pub conflicts: Vec<ConflictFile>,
+    /// 缺文件清单（容忍）。
+    pub missing: Vec<MissingFile>,
+    /// MultiMC 不支持的 component（逐项）。
+    pub rejected_components: Vec<RejectedComponent>,
+    /// 注记。
+    pub warnings: Vec<ImportIssue>,
+    /// 致命错误（`status == Failed` 时必有）。
+    pub error: Option<ImportError>,
+    /// 登记的实例。
+    pub registered: Option<RegisteredInstance>,
+    /// 回滚结果（只有真的执行过回滚才有）。[`ImportReport::rolled_back`] 只在它**完整**时为真。
+    pub rollback: Option<RollbackOutcome>,
+    /// `instance.cfg` 里受开关门控的内存上限（MB；仅 MultiMC / Prism 有）。
+    pub max_memory_mb: Option<u64>,
+    /// 本次写入的字节数。
+    pub bytes_written: u64,
+    /// 是否已确认"目标目录与导入前一致"：回滚**完整**完成、或从未写过目标目录时为 `true`；
+    /// 回滚有失败项时为 `false`（失败项在 [`ImportReport::rollback`] 里）。
+    pub rolled_back: bool,
+}
+
+impl ImportReport {
+    /// 一次尚未发生任何事的空报告（失败路径的起点）。
+    #[must_use]
+    pub fn empty(target: PathBuf) -> Self {
+        Self {
+            status: ImportStatus::Success,
+            format: None,
+            pack_name: None,
+            pack_version: None,
+            game_version: None,
+            loader: None,
+            version_id: None,
+            target,
+            files: Vec::new(),
+            conflicts: Vec::new(),
+            missing: Vec::new(),
+            rejected_components: Vec::new(),
+            warnings: Vec::new(),
+            error: None,
+            registered: None,
+            rollback: None,
+            max_memory_mb: None,
+            bytes_written: 0,
+            rolled_back: false,
+        }
+    }
+
+    /// 真正写了盘的文件数。
+    #[must_use]
+    pub fn installed(&self) -> usize {
+        self.files.iter().filter(|file| file.action.wrote()).count()
+    }
+
+    /// 是否"部分成功"。
+    ///
+    /// 判据是**结果对用户是否干净**：有"搞不到"的文件，或有保留了用户文件的冲突（说明整合包
+    /// 与磁盘内容不一致）都不是干净的成功。用户选了"覆盖"的冲突不算——那侧的意图已落实。
+    #[must_use]
+    pub fn is_partial(&self) -> bool {
+        !self.missing.is_empty()
+            || self
+                .conflicts
+                .iter()
+                .any(|conflict| conflict.choice == ConflictChoice::KeepUser)
+    }
+
+    /// 按 `error` / `missing` / `conflicts` 收敛三态（**唯一**算状态的地方）。
+    pub fn finish_status(&mut self) {
+        self.status = if self.error.is_some() {
+            ImportStatus::Failed
+        } else if self.is_partial() {
+            ImportStatus::Partial
+        } else {
+            ImportStatus::Success
+        };
+    }
+
+    /// 记一条致命错误并把状态落到 `Failed`。
+    pub fn fail(&mut self, error: ImportError) {
+        self.error = Some(error);
+        self.status = ImportStatus::Failed;
+    }
+}
diff --git a/crates/core/src/addon/import/report/items.rs b/crates/core/src/addon/import/report/items.rs
new file mode 100644
index 0000000..9434a93
--- /dev/null
+++ b/crates/core/src/addon/import/report/items.rs
@@ -0,0 +1,265 @@
+//! 报告里的**条目类型**：一条文件、一条冲突、一条缺失、一个 component、一个加载器目标。
+
+use serde::Serialize;
+
+use super::keys;
+use crate::addon::loader::LoaderKind;
+use crate::addon::pack::PackSide;
+
+/// 一条文件来自哪里。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum FileSource {
+    /// 包内 `overrides/`（或 CF 清单点名的那个目录 / MultiMC 的 `.minecraft/`）。
+    Overrides,
+    /// 包内 `client-overrides/`。
+    ClientOverrides,
+    /// CurseForge `files[]` 条目（靠 projectID/fileID 补全）。
+    CurseForge,
+    /// Modrinth `files[]` 条目（清单自带 path + downloads）。
+    Modrinth,
+}
+
+impl FileSource {
+    /// 从覆盖目录的侧别取来源。
+    #[must_use]
+    pub const fn from_side(side: PackSide) -> Self {
+        match side {
+            PackSide::Both => Self::Overrides,
+            PackSide::Client => Self::ClientOverrides,
+            // 服务端覆盖在客户端导入里不会落地（见 `plan` 的侧别优先级）。
+            PackSide::Server => Self::Overrides,
+        }
+    }
+}
+
+/// 一个文件本次被怎么处理。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum FileAction {
+    /// 新写入（磁盘上原本没有）。
+    Installed,
+    /// 覆盖写入（用户没改过，整合包升级）。
+    Replaced,
+    /// 磁盘内容与包内一致，没动。
+    SkippedIdentical,
+    /// 用户改过 / 删过，按策略保留了用户那一侧。
+    KeptUser,
+}
+
+impl FileAction {
+    /// 是否真的写了盘。
+    #[must_use]
+    pub const fn wrote(self) -> bool {
+        matches!(self, Self::Installed | Self::Replaced)
+    }
+}
+
+/// 冲突的成因。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ConflictReason {
+    /// 基线里记过这个文件，磁盘内容与基线不同 ⇒ 用户改过。
+    UserModified,
+    /// 基线里记过这个文件，磁盘上却没了 ⇒ 用户删过。
+    UserDeleted,
+    /// 没有基线可判，磁盘上本来就有同名文件。
+    PreExisting,
+}
+
+impl ConflictReason {
+    /// 文案 key。
+    #[must_use]
+    pub const fn message_key(self) -> &'static str {
+        match self {
+            Self::UserModified => keys::CONFLICT_USER_MODIFIED,
+            Self::UserDeleted => keys::CONFLICT_USER_DELETED,
+            Self::PreExisting => keys::CONFLICT_PRE_EXISTING,
+        }
+    }
+}
+
+/// 冲突实际采用的处置（由 [`super::super::ConflictPolicy`] 决定）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ConflictChoice {
+    /// 保留用户侧（不写盘）。
+    KeepUser,
+    /// 用包内内容覆盖（用户选了"覆盖"）。
+    Overwrite,
+}
+
+/// 一条冲突（"无法判定时给可选择的冲突清单"就是这张表）。
+#[derive(Debug, Clone, Serialize)]
+pub struct ConflictFile {
+    /// 实例内相对路径。
+    pub path: String,
+    /// 成因。
+    pub reason: ConflictReason,
+    /// 本次实际采用的一侧。
+    pub choice: ConflictChoice,
+    /// 文案 key（= `reason.message_key()`）。
+    pub message_key: &'static str,
+    /// 包内声明的 SHA-1。
+    pub pack_sha1: String,
+    /// 包内声明的字节数。
+    pub pack_size: u64,
+    /// 上次导入写下的 SHA-1（没有基线时 `None`）。
+    pub base_sha1: Option<String>,
+    /// 磁盘现状的 SHA-1（文件不存在时 `None`）。
+    pub disk_sha1: Option<String>,
+}
+
+/// 一个"搞不到"的文件（**容忍**，但必须逐条列出）。
+#[derive(Debug, Clone, Serialize)]
+pub struct MissingFile {
+    /// 实例内相对路径（mrpack 有；CF 补全失败时没有）。
+    pub path: Option<String>,
+    /// 人读标识（CF 条目是 `projectID:fileID`，其余是路径）。
+    pub display: String,
+    /// CF `projectID`。
+    pub project_id: Option<i64>,
+    /// CF `fileID`。
+    pub file_id: Option<i64>,
+    /// 为什么搞不到。
+    pub reason: MissingReason,
+    /// 文案 key。
+    pub message_key: &'static str,
+    /// 细节（错误原文）。
+    pub detail: String,
+}
+
+/// "搞不到"的成因。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum MissingReason {
+    /// 调用方没给 fetcher（离线）。
+    Offline,
+    /// 条目补不出下载地址（CF 缺 API 客户端 / `downloads` 为空）。
+    NoSource,
+    /// 尝试过但失败（404 / 网络）。
+    FetchFailed,
+}
+
+impl MissingReason {
+    /// 文案 key。
+    #[must_use]
+    pub const fn message_key(self) -> &'static str {
+        match self {
+            Self::Offline => keys::MISSING_OFFLINE,
+            Self::NoSource => keys::MISSING_NO_SOURCE,
+            Self::FetchFailed => keys::MISSING_FETCH_FAILED,
+        }
+    }
+}
+
+/// 一个 MultiMC / Prism component 被识别为"本启动器不支持"（**逐项**列出，不静默丢）。
+#[derive(Debug, Clone, Serialize)]
+pub struct RejectedComponent {
+    /// 原始 uid（`org.lwjgl3` / `net.fabricmc.intermediary` / 社区自定义）。
+    pub uid: String,
+    /// 该组件声明的版本。
+    pub version: Option<String>,
+    /// 文案 key（恒为 [`keys::REJECTED_COMPONENT`]）。
+    pub message_key: &'static str,
+}
+
+/// 加载器安装计划的输入：**只需要这三个参数**就能接上 `addon::loader` 的既有能力。
+#[derive(Debug, Clone)]
+pub struct LoaderTarget {
+    /// 加载器种类。
+    pub kind: LoaderKind,
+    /// 目标原版版本。
+    pub mc_version: String,
+    /// 加载器版本（已剥掉 CF 的 MC 版本前缀）。
+    pub loader_version: String,
+    /// 清单里的原始标识（诊断用）。
+    pub raw: String,
+    /// 实例绑定的版本 id（`1.20.1-fabric-0.15.11` 或纯原版 `1.20.1`）。
+    pub version_id: String,
+}
+
+impl LoaderTarget {
+    /// 直接喂给 `LoaderSource::resolve(kind, mc_version, Some(loader_version))`。
+    #[must_use]
+    pub fn resolve_args(&self) -> (LoaderKind, &str, &str) {
+        (self.kind, &self.mc_version, &self.loader_version)
+    }
+}
+
+impl Serialize for LoaderTarget {
+    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        use serde::ser::SerializeMap;
+
+        let mut map = serializer.serialize_map(None)?;
+        map.serialize_entry("kind", self.kind.as_str())?;
+        map.serialize_entry("label", self.kind.label())?;
+        map.serialize_entry("mc_version", &self.mc_version)?;
+        map.serialize_entry("loader_version", &self.loader_version)?;
+        map.serialize_entry("version_id", &self.version_id)?;
+        map.serialize_entry("raw", &self.raw)?;
+        map.end()
+    }
+}
+
+/// 一条落地的文件。
+#[derive(Debug, Clone, Serialize)]
+pub struct ImportedFile {
+    /// 实例内相对路径（`.disabled` 后缀原样保留）。
+    pub path: String,
+    /// 来源。
+    pub source: FileSource,
+    /// 实际写入/比对用的 SHA-1。
+    pub sha1: Option<String>,
+    /// 字节数。
+    pub bytes: u64,
+    /// 是否禁用态（路径后缀表达，不附加语义）。
+    pub disabled: bool,
+    /// 处理方式。
+    pub action: FileAction,
+    /// 可选注记（`.disabled` / `optional` 之类）。
+    pub note: Option<ImportIssue>,
+}
+
+/// 一条人读注记（带稳定 key）。
+#[derive(Debug, Clone, Serialize)]
+pub struct ImportIssue {
+    /// 文案 key。
+    pub message_key: &'static str,
+    /// 人读细节。
+    pub message: String,
+    /// 相关实例内路径。
+    pub path: Option<String>,
+}
+
+impl ImportIssue {
+    /// 构造。
+    #[must_use]
+    pub fn new(message_key: &'static str, message: impl Into<String>) -> Self {
+        Self {
+            message_key,
+            message: message.into(),
+            path: None,
+        }
+    }
+
+    /// 挂一条路径。
+    #[must_use]
+    pub fn with_path(mut self, path: impl Into<String>) -> Self {
+        self.path = Some(path.into());
+        self
+    }
+}
+
+/// 登记出来的实例（给 UI 显示"装到哪了"）。
+#[derive(Debug, Clone, Serialize)]
+pub struct RegisteredInstance {
+    /// 实例 id（稳定 UUID）。
+    pub id: String,
+    /// 展示名。
+    pub name: String,
+    /// 绑定版本 id。
+    pub version_id: String,
+    /// 是否本次新建（`false` = 复用已有档案）。
+    pub created: bool,
+}
diff --git a/crates/core/src/addon/import/report/keys.rs b/crates/core/src/addon/import/report/keys.rs
new file mode 100644
index 0000000..e373a37
--- /dev/null
+++ b/crates/core/src/addon/import/report/keys.rs
@@ -0,0 +1,105 @@
+//! 文案 key 常量表（**稳定字符串**，M109/M113 的页面按这些字符串查本地化文案）。
+//!
+//! core 不出现面向用户的成品文案（诊断信息除外）；三态/阶段/缺失/冲突/注记各自带一个 key，
+//! 逐条原因也在报告条目里（`message_key` 字段）。
+//!
+//! `ALL` 是"没有死常量"的守门用表：`addon/tests/import_report.rs` 会核对
+//! ①常量定义集合 == `ALL`（不多不少）；②每个常量除了定义与 `ALL` 里的列举之外，至少还有
+//! 一处真实引用。任何一条不满足就失败——避免这张表腐烂成"看着齐全、其实没人用"。
+
+/// 阶段：读取清单。
+pub const STAGE_PROBE: &str = "pack.import.stage.probe";
+/// 阶段：解压覆盖内容。
+pub const STAGE_EXTRACT: &str = "pack.import.stage.extract";
+/// 阶段：补全缺失文件。
+pub const STAGE_FETCH: &str = "pack.import.stage.fetch";
+/// 阶段：落地（rename / journal）。
+pub const STAGE_COMMIT: &str = "pack.import.stage.commit";
+/// 阶段：登记实例。
+pub const STAGE_REGISTER: &str = "pack.import.stage.register";
+
+/// 状态：成功。
+pub const STATUS_SUCCESS: &str = "pack.import.status.success";
+/// 状态：部分成功。
+pub const STATUS_PARTIAL: &str = "pack.import.status.partial";
+/// 状态：失败（是否回滚干净看 `ImportReport::rolled_back`）。
+pub const STATUS_FAILED: &str = "pack.import.status.failed";
+
+/// 注记：`server-overrides/` 客户端不解压。
+pub const NOTE_SERVER_OVERRIDES_SKIPPED: &str = "pack.import.note.server_overrides_skipped";
+/// 注记：`dependencies` 里不认识的键（`parchment` 之类）。
+pub const NOTE_UNKNOWN_DEPENDENCY: &str = "pack.import.note.unknown_dependency";
+/// 注记：`env.client=unsupported` 的条目被跳过。
+pub const NOTE_ENV_UNSUPPORTED: &str = "pack.import.note.env_unsupported";
+/// 注记：路径以 `.disabled` 结尾（禁用态，按原后缀落地）。
+pub const NOTE_DISABLED_SUFFIX: &str = "pack.import.note.disabled_suffix";
+/// 注记：路径以 `.old` 结尾（只识别与保留，不加语义）。
+pub const NOTE_OLD_SUFFIX: &str = "pack.import.note.old_suffix";
+/// 注记：`env.client=optional`（"可选"不等于"禁用"，照装）。
+pub const NOTE_OPTIONAL_FILE: &str = "pack.import.note.optional_file";
+/// 注记：清单里有多个加载器，只按 primary/第一条组计划。
+pub const NOTE_LOADER_MULTIPLE: &str = "pack.import.note.loader_multiple";
+/// 注记：实例已登记。
+pub const NOTE_REGISTERED: &str = "pack.import.note.registered";
+/// 注记：从 `instance.cfg` 取到了内存设置。
+pub const NOTE_INSTANCE_CFG_MEMORY: &str = "pack.import.note.instance_cfg_memory";
+/// 注记：基线文件读不出来（本次按"没有基线"处理）。
+pub const NOTE_BASELINE_UNREADABLE: &str = "pack.import.note.baseline_unreadable";
+/// 注记：基线属于**另一个整合包**（本次按"没有基线"处理）。
+pub const NOTE_BASELINE_PACK_MISMATCH: &str = "pack.import.note.baseline_pack_mismatch";
+/// 注记：提交前清掉了下载引擎的中间产物（`.ullpart-*` / `.ullmeta.json`）。
+pub const NOTE_ENGINE_ARTIFACTS_DROPPED: &str = "pack.import.note.engine_artifacts_dropped";
+/// 注记：回滚**未完整完成**（逐项列失败，`rolled_back` 为 false）。
+pub const NOTE_ROLLBACK_INCOMPLETE: &str = "pack.import.note.rollback_incomplete";
+
+/// 缺失：调用方没给 fetcher（离线导入）。
+pub const MISSING_OFFLINE: &str = "pack.import.missing.offline";
+/// 缺失：条目本身补不出下载地址（CF `files[]` 缺 API 客户端 / `downloads` 为空）。
+pub const MISSING_NO_SOURCE: &str = "pack.import.missing.no_source";
+/// 缺失：下载/补全尝试过但失败（404 / 网络）。
+pub const MISSING_FETCH_FAILED: &str = "pack.import.missing.fetch_failed";
+
+/// 冲突：用户改过这个文件。
+pub const CONFLICT_USER_MODIFIED: &str = "pack.import.conflict.user_modified";
+/// 冲突：用户删过这个文件。
+pub const CONFLICT_USER_DELETED: &str = "pack.import.conflict.user_deleted";
+/// 冲突：磁盘上本来就有同名内容（没有基线可判）。
+pub const CONFLICT_PRE_EXISTING: &str = "pack.import.conflict.pre_existing";
+
+/// MultiMC 不支持的 component（逐项列出）。
+pub const REJECTED_COMPONENT: &str = "pack.import.rejected.component";
+/// 致命失败后已完成回滚（目标目录零残留）。
+pub const ROLLBACK_DONE: &str = "pack.import.rollback.done";
+
+/// 全部 key（守门断言"没有死常量"用）。
+pub const ALL: &[&str] = &[
+    STAGE_PROBE,
+    STAGE_EXTRACT,
+    STAGE_FETCH,
+    STAGE_COMMIT,
+    STAGE_REGISTER,
+    STATUS_SUCCESS,
+    STATUS_PARTIAL,
+    STATUS_FAILED,
+    NOTE_SERVER_OVERRIDES_SKIPPED,
+    NOTE_UNKNOWN_DEPENDENCY,
+    NOTE_ENV_UNSUPPORTED,
+    NOTE_DISABLED_SUFFIX,
+    NOTE_OLD_SUFFIX,
+    NOTE_OPTIONAL_FILE,
+    NOTE_LOADER_MULTIPLE,
+    NOTE_REGISTERED,
+    NOTE_INSTANCE_CFG_MEMORY,
+    NOTE_BASELINE_UNREADABLE,
+    NOTE_BASELINE_PACK_MISMATCH,
+    NOTE_ENGINE_ARTIFACTS_DROPPED,
+    NOTE_ROLLBACK_INCOMPLETE,
+    MISSING_OFFLINE,
+    MISSING_NO_SOURCE,
+    MISSING_FETCH_FAILED,
+    CONFLICT_USER_MODIFIED,
+    CONFLICT_USER_DELETED,
+    CONFLICT_PRE_EXISTING,
+    REJECTED_COMPONENT,
+    ROLLBACK_DONE,
+];
diff --git a/crates/core/src/addon/import/stage.rs b/crates/core/src/addon/import/stage.rs
new file mode 100644
index 0000000..23dee9d
--- /dev/null
+++ b/crates/core/src/addon/import/stage.rs
@@ -0,0 +1,334 @@
+//! 落地事务：**临时目录 + rename**，合并态用 journal 回滚（回滚细节在 [`commit`]）。
+//!
+//! # 两种起点，两条事务路径
+//!
+//! | 起点 | 做法 | 失败后的样子 |
+//! |------|------|--------------|
+//! | 目标目录不存在 / 是空目录（全新导入） | 在**同卷兄弟目录**里把整个实例建好，最后一次 `rename` 到位 | 目标目录**从未出现**（rename 是原子的） |
+//! | 目标目录已有内容（升级 / 重导） | 逐文件 `rename` 进目标；被替换的旧文件先改名成 `<dest>.ullbak-<pid>` 当备份 | journal 逆序回滚：新文件删掉、旧备份改回原名 |
+//!
+//! 为什么全新导入不逐文件搬：逐文件搬意味着"搬到一半失败"会留下一个**看起来存在**的
+//! 半个实例，而 `rename` 一个目录是单步原子操作——失败就只有"没有"这一种结果。
+//!
+//! # 两道路径检查都在这层再走一遍
+//!
+//! 第一道是 M110 的 [`normalize_file`]（七条写死规则：空名 / `\0` / `\` / `:` / 前导 `/` /
+//! 任何 `..` 段 / 规整后为空），第二道是**落盘前的 `starts_with` 复核**（Modrinth 官方安装器
+//! 同款做法：`install_mrpack.rs:169-170` 按 `strip_prefix(instance_root)` 再判一次）。
+//! 模型可能来自外部构造，`zip` 侧的双检挡不住"调用方直接塞了个 `../x` 进来"。
+
+pub mod commit;
+
+pub use commit::{CommitFailure, CommitGuard, RollbackOutcome};
+
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use super::super::pack::path::normalize_file;
+use super::super::pack::PackError;
+use super::error::ImportError;
+use crate::platform::atomic::write_atomic;
+
+use crate::download::atomic::{META_SUFFIX, PART_SUFFIX};
+use commit::{rollback_merge, Applied};
+
+/// 临时目录名里的进程内序号（同一进程并发导入不撞名）。
+static SEQ: AtomicU64 = AtomicU64::new(0);
+
+/// 目标目录的起点形态。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(super) enum Mode {
+    /// 全新：整目录 rename。
+    Fresh,
+    /// 合并：逐文件 rename + journal。
+    Merge,
+}
+
+/// 一个进行中的落地事务。
+#[derive(Debug)]
+pub struct Staging {
+    target: PathBuf,
+    temp: PathBuf,
+    mode: Mode,
+    /// 本次是否由我们创建了目标目录的父目录（回滚时顺手清掉，避免"空壳目录"残留）。
+    created_parent: bool,
+}
+
+impl Staging {
+    /// 开一个事务（临时目录立刻建好，目标目录此刻一个字节都没动）。
+    ///
+    /// # Errors
+    ///
+    /// 目标路径是文件、父目录建不出来、临时目录建不出来时返回 `pack_io`。
+    pub fn begin(target: &Path) -> Result<Self, ImportError> {
+        if target.is_file() {
+            return Err(io_error(format!(
+                "目标路径是个文件，不是目录：{}",
+                target.display()
+            )));
+        }
+        let parent = target
+            .parent()
+            .filter(|path| !path.as_os_str().is_empty())
+            .map_or_else(|| PathBuf::from("."), Path::to_path_buf);
+        let created_parent = !parent.exists();
+        std::fs::create_dir_all(&parent)
+            .map_err(|error| io_error(format!("建 {} 失败：{error}", parent.display())))?;
+
+        let name = target.file_name().map_or_else(
+            || "instance".to_string(),
+            |name| name.to_string_lossy().to_string(),
+        );
+        let seq = SEQ.fetch_add(1, Ordering::Relaxed);
+        let temp = parent.join(format!(".{name}.ull-import-{}-{seq}", std::process::id()));
+        if temp.exists() {
+            std::fs::remove_dir_all(&temp).map_err(|error| {
+                io_error(format!("清旧临时目录 {} 失败：{error}", temp.display()))
+            })?;
+        }
+        std::fs::create_dir_all(&temp)
+            .map_err(|error| io_error(format!("建临时目录 {} 失败：{error}", temp.display())))?;
+
+        let mode = match std::fs::read_dir(target) {
+            Ok(mut entries) => {
+                if entries.next().is_some() {
+                    Mode::Merge
+                } else {
+                    Mode::Fresh
+                }
+            }
+            Err(_) => Mode::Fresh,
+        };
+        Ok(Self {
+            target: target.to_path_buf(),
+            temp,
+            mode,
+            created_parent,
+        })
+    }
+
+    /// 临时目录根（调试 / 测试断言用）。
+    #[must_use]
+    pub fn temp(&self) -> &Path {
+        &self.temp
+    }
+
+    /// 目标目录。
+    #[must_use]
+    pub fn target(&self) -> &Path {
+        &self.target
+    }
+
+    /// 是否合并态（目标目录已有内容）。
+    #[must_use]
+    pub const fn is_merge(&self) -> bool {
+        matches!(self.mode, Mode::Merge)
+    }
+
+    /// 规划一个暂存路径：走**两道**路径检查后返回可写的绝对路径。
+    ///
+    /// # Errors
+    ///
+    /// 路径穿越 / 空路径 / 规整后越出临时目录时返回 `pack_traversal`。
+    pub fn dest_for(&self, relative: &str) -> Result<PathBuf, ImportError> {
+        let normalized = normalize_file(relative)?;
+        let path = self.temp.join(&normalized);
+        // 第二检：规整之后仍要确认它真的在临时目录下面（不靠 `join` 的语义"讲道理"）。
+        if !path.starts_with(&self.temp) {
+            return Err(PackError::traversal(format!("暂存路径越出临时目录：{relative:?}")).into());
+        }
+        Ok(path)
+    }
+
+    /// 写一个暂存文件（自动建父目录）。
+    ///
+    /// # Errors
+    ///
+    /// 路径不安全、写盘失败。
+    pub fn write(&self, relative: &str, bytes: &[u8]) -> Result<PathBuf, ImportError> {
+        let dest = self.dest_for(relative)?;
+        write_atomic(&dest, bytes)
+            .map_err(|error| io_error(format!("写 {} 失败：{error}", dest.display())))?;
+        Ok(dest)
+    }
+
+    /// 删掉一个暂存文件（例如发现内容与磁盘一致，不必落地）。
+    pub fn discard(&self, relative: &str) -> Result<(), ImportError> {
+        let dest = self.dest_for(relative)?;
+        match std::fs::remove_file(&dest) {
+            Ok(()) => Ok(()),
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
+            Err(error) => Err(io_error(format!("删 {} 失败：{error}", dest.display()))),
+        }
+    }
+
+    /// 放弃事务：临时目录整个删掉，目标目录保持导入前的样子。
+    pub fn abort(self) {
+        self.abort_inner();
+    }
+
+    fn abort_inner(&self) {
+        let _ = std::fs::remove_dir_all(&self.temp);
+        if self.created_parent {
+            // 只删空目录：非空说明有别人用了，别动。
+            let _ = std::fs::remove_dir(self.temp.parent().unwrap_or(&self.temp));
+        }
+    }
+
+    /// 提交事务：返回一个**必须显式 `finish`** 的守卫（析构即回滚）。
+    ///
+    /// # Errors
+    ///
+    /// `rename` 失败、合并态逐文件搬动失败。**回滚已经在这条路径上做过**，其结果连同错误
+    /// 一起返回（[`CommitFailure::rollback`]）：调用方必须把它写进报告，不许假设"失败 = 已回滚干净"。
+    pub fn commit(self) -> Result<CommitGuard, CommitFailure> {
+        match self.mode {
+            Mode::Fresh => match std::fs::rename(&self.temp, &self.target) {
+                Ok(()) => Ok(CommitGuard::fresh(self.target.clone(), self.temp.clone())),
+                Err(error) => {
+                    self.abort_inner();
+                    Err(CommitFailure::io(
+                        format!(
+                            "把 {} 改名成 {} 失败：{error}",
+                            self.temp.display(),
+                            self.target.display()
+                        ),
+                        RollbackOutcome::default(),
+                    ))
+                }
+            },
+            Mode::Merge => {
+                let mut applied: Vec<Applied> = Vec::new();
+                match self.apply_merge(&mut applied) {
+                    Ok(()) => Ok(CommitGuard::merge(
+                        self.target.clone(),
+                        self.temp.clone(),
+                        applied,
+                    )),
+                    Err(error) => {
+                        let rollback = rollback_merge(&mut applied);
+                        self.abort_inner();
+                        Err(CommitFailure::new(error, rollback))
+                    }
+                }
+            }
+        }
+    }
+
+    /// 删掉暂存目录里的**下载引擎中间产物**（续传 part 与 meta），返回删掉的个数。
+    ///
+    /// 为什么必须在提交前删：引擎在下载失败时**故意**保留 `<name>.ullpart-<session>-<seq>`
+    /// 与 `<name>.ullmeta.json` 供下次续传（`core::download::atomic` 的设计）。这些文件躺在
+    /// 暂存目录里，提交阶段会跟内容一起搬进实例——实例里冒出 `.ullpart-…` 既不是整合包内容，
+    /// 又会被下次导入的基线/冲突判定当成"用户文件"，从此谁也说不清。
+    ///
+    /// 冲突口径：整合包里真有一个叫 `x.ullpart` 的文件几乎不可能；真出现时以"不入实例"为准。
+    ///
+    /// # Errors
+    ///
+    /// 遍历或删除失败返回 `pack_io`。
+    pub fn purge_engine_artifacts(&self) -> Result<usize, ImportError> {
+        let mut files: Vec<PathBuf> = Vec::new();
+        collect_files(&self.temp, &mut files)?;
+        let mut removed = 0_usize;
+        for path in files {
+            if !is_engine_artifact(&path) {
+                continue;
+            }
+            std::fs::remove_file(&path).map_err(|error| {
+                io_error(format!("删中间产物 {} 失败：{error}", path.display()))
+            })?;
+            removed += 1;
+        }
+        Ok(removed)
+    }
+
+    /// 合并态：把临时目录里的文件逐个搬进目标目录（每个都带备份）。
+    fn apply_merge(&self, applied: &mut Vec<Applied>) -> Result<(), ImportError> {
+        let mut staged: Vec<PathBuf> = Vec::new();
+        collect_files(&self.temp, &mut staged)?;
+        staged.sort();
+        for source in staged {
+            let relative = source
+                .strip_prefix(&self.temp)
+                .map_err(|_| io_error(format!("暂存路径不在临时目录里：{}", source.display())))?;
+            let relative_text = relative.to_string_lossy().replace('\\', "/");
+            // 搬动前再规整一次（第三道，防"临时目录里被塞了奇怪的名字"）。
+            let normalized = normalize_file(&relative_text)?;
+            let dest = self.target.join(&normalized);
+            if !dest.starts_with(&self.target) {
+                return Err(PackError::traversal(format!(
+                    "落地路径越出实例目录：{relative_text:?}"
+                ))
+                .into());
+            }
+            if let Some(parent) = dest.parent() {
+                std::fs::create_dir_all(parent)
+                    .map_err(|error| io_error(format!("建 {} 失败：{error}", parent.display())))?;
+            }
+            let backup = if dest.exists() {
+                let backup = commit::backup_path(&dest);
+                std::fs::rename(&dest, &backup).map_err(|error| {
+                    io_error(format!(
+                        "备份 {} → {} 失败：{error}",
+                        dest.display(),
+                        backup.display()
+                    ))
+                })?;
+                Some(backup)
+            } else {
+                None
+            };
+            applied.push(Applied {
+                dest: dest.clone(),
+                backup,
+                moved: false,
+            });
+            std::fs::rename(&source, &dest).map_err(|error| {
+                io_error(format!(
+                    "把 {} 搬到 {} 失败：{error}",
+                    source.display(),
+                    dest.display()
+                ))
+            })?;
+            if let Some(last) = applied.last_mut() {
+                last.moved = true;
+            }
+        }
+        Ok(())
+    }
+}
+
+/// 引擎中间产物的文件名判据（`.ullpart` 在中段、`.ullmeta.json` 在结尾）。
+#[must_use]
+pub fn is_engine_artifact(path: &Path) -> bool {
+    let Some(name) = path.file_name().and_then(|name| name.to_str()) else {
+        return false;
+    };
+    name.ends_with(META_SUFFIX) || name.contains(PART_SUFFIX)
+}
+
+/// 递归收集目录下的全部文件（绝对路径）。
+fn collect_files(dir: &Path, out: &mut Vec<PathBuf>) -> Result<(), ImportError> {
+    let entries = std::fs::read_dir(dir)
+        .map_err(|error| io_error(format!("读 {} 失败：{error}", dir.display())))?;
+    for entry in entries {
+        let entry =
+            entry.map_err(|error| io_error(format!("读 {} 失败：{error}", dir.display())))?;
+        let path = entry.path();
+        let file_type = entry
+            .file_type()
+            .map_err(|error| io_error(format!("读 {} 类型失败：{error}", path.display())))?;
+        if file_type.is_dir() {
+            collect_files(&path, out)?;
+        } else {
+            out.push(path);
+        }
+    }
+    Ok(())
+}
+
+/// 本地 IO 失败（统一包成 M110 的 `pack_io`，不再造新码）。
+pub(super) fn io_error(message: impl Into<String>) -> ImportError {
+    PackError::io(message).into()
+}
diff --git a/crates/core/src/addon/import/stage/commit.rs b/crates/core/src/addon/import/stage/commit.rs
new file mode 100644
index 0000000..25a1e38
--- /dev/null
+++ b/crates/core/src/addon/import/stage/commit.rs
@@ -0,0 +1,290 @@
+//! 提交守卫、回滚与**回滚本身失败的记账**：`Drop` 即回滚，除非显式 `finish`。
+//!
+//! 靠调用方在每个错误分支手动清理，早晚会漏一条——所以把"回滚"绑在析构上：任何提前
+//! `return`、`?` 冒泡、panic 展开都不会留下半个实例。
+//!
+//! 回滚分两种：
+//!
+//! - **全新导入**：目标目录整个是本事务建的 ⇒ 删干净就是零残留；
+//! - **合并态**：按 journal **逆序**撤回——新文件删掉、被替换的旧文件从 `.ullbak-<pid>` 改回原名。
+//!
+//! # 回滚也可能失败（复审 r5 P2-2）
+//!
+//! 早期实现把每一步写成 `let _ = …`，失败被吞，报告却照样宣称"目标目录与导入前一致"。
+//! 现在每次回滚都返回 [`RollbackOutcome`]：调用的**显式**回滚路径（`CommitGuard::rollback`）
+//! 由导入管线把结果写进报告（`rolled_back` 只在**完整**回滚时为 `true`，否则列出失败项）；
+//! `Drop` 那条兜底路径拿不到调用方，只能尽力而为——所以它是"防漏"而不是"承诺"，文档与
+//! 报告口径都按这个写。
+
+use std::path::{Path, PathBuf};
+
+use super::io_error;
+use crate::addon::import::ImportError;
+
+/// 备份后缀（合并态的 journal 备份文件）。
+const BACKUP_TAG: &str = "ullbak";
+
+/// 一次回滚的结果（**失败项要能被报告出来**）。
+#[derive(Debug, Clone, Default, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RollbackOutcome {
+    /// 尝试过的回滚动作数（删新文件 + 恢复备份）。
+    pub attempted: usize,
+    /// 失败项的人读描述（路径 + 原因）；空表 = 完整回滚。
+    pub failed: Vec<String>,
+}
+
+impl RollbackOutcome {
+    /// 是否完整回滚（没有失败项）。
+    #[must_use]
+    pub fn is_complete(&self) -> bool {
+        self.failed.is_empty()
+    }
+
+    /// 失败项数。
+    #[must_use]
+    pub fn failure_count(&self) -> usize {
+        self.failed.len()
+    }
+}
+
+/// 一条已应用的搬动记录。
+#[derive(Debug)]
+pub struct Applied {
+    /// 目标路径。
+    pub(super) dest: PathBuf,
+    /// 被替换下来的旧文件备份。
+    pub(super) backup: Option<PathBuf>,
+    /// 新文件是否已经搬到位。
+    pub(super) moved: bool,
+}
+
+/// 提交守卫：**析构即回滚**，除非显式 [`CommitGuard::finish`]。
+#[derive(Debug)]
+pub struct CommitGuard {
+    inner: Option<Inner>,
+}
+
+#[derive(Debug)]
+struct Inner {
+    target: PathBuf,
+    temp: PathBuf,
+    /// 本次是否**新建**了目标目录（全新导入）。
+    created_target: bool,
+    applied: Vec<Applied>,
+    finished: bool,
+}
+
+impl CommitGuard {
+    /// 全新导入留下的守卫（目标目录已是 rename 后的成品）。
+    pub(super) fn fresh(target: PathBuf, temp: PathBuf) -> Self {
+        Self {
+            inner: Some(Inner {
+                target,
+                temp,
+                created_target: true,
+                applied: Vec::new(),
+                finished: false,
+            }),
+        }
+    }
+
+    /// 合并态留下的守卫（`applied` 是已搬进去的 journal）。
+    pub(super) fn merge(target: PathBuf, temp: PathBuf, applied: Vec<Applied>) -> Self {
+        Self {
+            inner: Some(Inner {
+                target,
+                temp,
+                created_target: false,
+                applied,
+                finished: false,
+            }),
+        }
+    }
+
+    /// 目标目录。
+    #[must_use]
+    pub fn target(&self) -> &Path {
+        self.inner
+            .as_ref()
+            .map_or(Path::new(""), |inner| inner.target.as_path())
+    }
+
+    /// 确认提交：删备份、清临时目录。
+    pub fn finish(mut self) {
+        if let Some(inner) = self.inner.as_mut() {
+            for applied in &inner.applied {
+                if let Some(backup) = &applied.backup {
+                    let _ = std::fs::remove_file(backup);
+                }
+            }
+            let _ = std::fs::remove_dir_all(&inner.temp);
+            inner.finished = true;
+        }
+    }
+
+    /// 显式回滚，并**返回结果**（失败的项由调用方写进报告）。
+    ///
+    /// `Drop` 也会回滚，但那条路径没法上报——因此真正需要"宣称一致"的地方必须调这个。
+    pub fn rollback(mut self) -> RollbackOutcome {
+        match self.inner.as_mut() {
+            Some(inner) => rollback_inner(inner),
+            None => RollbackOutcome::default(),
+        }
+    }
+}
+
+impl Drop for CommitGuard {
+    fn drop(&mut self) {
+        if let Some(inner) = self.inner.as_mut() {
+            if !inner.finished {
+                // 兜底：拿不到调用方，失败只能丢在这里（所以别依赖 Drop 去做"宣称"）。
+                let _ = rollback_inner(inner);
+            }
+        }
+    }
+}
+
+/// 回滚一次提交。
+fn rollback_inner(inner: &mut Inner) -> RollbackOutcome {
+    let mut outcome = RollbackOutcome::default();
+    if inner.created_target {
+        // 全新导入：目标目录整个是本事务建的，删干净 = 零残留。
+        outcome.attempted += 1;
+        if let Err(error) = std::fs::remove_dir_all(&inner.target) {
+            if error.kind() != std::io::ErrorKind::NotFound {
+                outcome.failed.push(format!(
+                    "删除本次新建的实例目录 {} 失败：{error}",
+                    inner.target.display()
+                ));
+            }
+        }
+    } else {
+        outcome = rollback_merge(&mut inner.applied);
+    }
+    let _ = std::fs::remove_dir_all(&inner.temp);
+    inner.finished = true;
+    outcome
+}
+
+/// 合并态回滚：新文件删掉、备份改回原名（**失败逐项记下来**）。
+pub(super) fn rollback_merge(applied: &mut [Applied]) -> RollbackOutcome {
+    let mut outcome = RollbackOutcome::default();
+    for entry in applied.iter().rev() {
+        if entry.moved {
+            outcome.attempted += 1;
+            match std::fs::remove_file(&entry.dest) {
+                Ok(()) => {}
+                Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
+                Err(error) => outcome
+                    .failed
+                    .push(format!("删除 {} 失败：{error}", entry.dest.display())),
+            }
+        }
+        if let Some(backup) = &entry.backup {
+            if backup.exists() {
+                outcome.attempted += 1;
+                if let Err(error) = std::fs::rename(backup, &entry.dest) {
+                    outcome.failed.push(format!(
+                        "把备份 {} 改回 {} 失败：{error}",
+                        backup.display(),
+                        entry.dest.display()
+                    ));
+                }
+            }
+        }
+    }
+    outcome
+}
+
+/// 备份路径：`<dest>.ullbak-<pid>`。
+pub(super) fn backup_path(dest: &Path) -> PathBuf {
+    let mut name = dest.file_name().map_or_else(
+        || std::ffi::OsString::from("file"),
+        std::ffi::OsStr::to_os_string,
+    );
+    name.push(format!(".{BACKUP_TAG}-{}", std::process::id()));
+    dest.with_file_name(name)
+}
+
+/// 一次**失败的回滚**（提交阶段失败时连同错误一起交回调用方）。
+///
+/// `io_error` 让"把一个 IO 原因包成 `pack_io`"只在一处定义。
+#[derive(Debug)]
+pub struct CommitFailure {
+    /// 提交阶段本身的错误。
+    pub error: ImportError,
+    /// 回滚结果（可能不完整）。
+    pub rollback: RollbackOutcome,
+}
+
+impl CommitFailure {
+    /// 用一条 IO 原因建失败结果。
+    #[must_use]
+    pub(super) fn io(message: impl Into<String>, rollback: RollbackOutcome) -> Self {
+        Self {
+            error: io_error(message),
+            rollback,
+        }
+    }
+
+    /// 用已有的导入错误建失败结果。
+    #[must_use]
+    pub(super) fn new(error: ImportError, rollback: RollbackOutcome) -> Self {
+        Self { error, rollback }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn applied(dest: PathBuf, backup: Option<PathBuf>, moved: bool) -> Applied {
+        Applied {
+            dest,
+            backup,
+            moved,
+        }
+    }
+
+    #[test]
+    fn complete_rollback_has_no_failures() {
+        let root = std::env::temp_dir().join(format!("ull-rb-ok-{}", std::process::id()));
+        std::fs::create_dir_all(root.join("config")).expect("建目录");
+        let dest = root.join("config/a.toml");
+        let backup = root.join("config/a.toml.ullbak-test");
+        std::fs::write(&dest, b"new").expect("写新文件");
+        std::fs::write(&backup, b"old").expect("写备份");
+        let mut journal = vec![applied(dest.clone(), Some(backup.clone()), true)];
+
+        let outcome = rollback_merge(&mut journal);
+
+        assert!(outcome.is_complete(), "{outcome:?}");
+        assert_eq!(outcome.attempted, 2);
+        assert_eq!(
+            std::fs::read(&dest).expect("读回"),
+            b"old",
+            "备份要改回原名"
+        );
+        assert!(!backup.exists());
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn rollback_failures_are_reported_not_swallowed() {
+        // 目标位置上是个**非空目录**：`remove_file` 与随后的备份改回都会失败
+        // （Windows / Unix 一致），于是"回滚失败"这条路径被确定性地打到。
+        let root = std::env::temp_dir().join(format!("ull-rb-fail-{}", std::process::id()));
+        let dest = root.join("a.toml");
+        std::fs::create_dir_all(dest.join("occupied")).expect("用非空目录占住目标");
+        let backup = root.join("a.toml.ullbak-test");
+        std::fs::write(&backup, b"old").expect("写备份");
+        let mut journal = vec![applied(dest.clone(), Some(backup), true)];
+
+        let outcome = rollback_merge(&mut journal);
+
+        assert!(!outcome.is_complete(), "失败必须被记下来：{outcome:?}");
+        assert_eq!(outcome.failure_count(), 2, "{outcome:?}");
+        let _ = std::fs::remove_dir_all(&root);
+    }
+}
diff --git a/crates/core/src/addon/loader/fabric.rs b/crates/core/src/addon/loader/fabric.rs
new file mode 100644
index 0000000..ec28c57
--- /dev/null
+++ b/crates/core/src/addon/loader/fabric.rs
@@ -0,0 +1,247 @@
+//! Fabric 系（Fabric / Quilt）：官方 meta → loader 版本 JSON。
+//!
+//! 依据 `DevDocs/analyse/05-modloader-modpack.md` §1.4：这两个加载器**没有 installer**，
+//! `meta.fabricmc.net` / `meta.quiltmc.org` 直接给 launcher 可用的 profile JSON，
+//! 所以安装 = "把 profile 收成我们的版本 JSON + 补库"，没有任何子进程。
+//!
+//! 本文件是**纯函数**（不进网络）：URL 拼装与 JSON 归一化分开写，测试直接喂离线夹具。
+//!
+//! # 归一化做了三件容易被上游坑的事
+//!
+//! 1. **`jar` 钉成原版 id**：profile 通常不写 `jar`，而 `game::inherit::resolve` 在缺 `jar`
+//!    时会把 `jar` 兜底成**自身 id**——那会让启动去找 `versions/<loader>/<loader>.jar`
+//!    （不存在）。这里显式写 `jar = <原版 id>`，让继承链正确地回到原版 jar。
+//! 2. **`mainClass` 断言**：缺主类就不是一份能启动的清单，宁可在安装期报 metadata，
+//!    也不要装出一个起不来的实例（HMCL 同款防御，analyse/05 §1.4）。
+//! 3. **扁平 `sha1`/`size` 提升成 `downloads.artifact`**：Fabric profile 的库把摘要写在
+//!    库对象顶层，M27 的库展开只认 `downloads.artifact`。不提上来的后果是"没有校验值 →
+//!    存在即信"，重装时无法识别被截断的库文件。
+
+use std::collections::BTreeMap;
+
+use serde::{Deserialize, Serialize};
+
+use super::plan::{LoaderRelease, LoaderSupport};
+use super::{LoaderError, LoaderKind};
+use crate::game::library::{Library, LibraryDownloads};
+use crate::game::manifest::{DownloadInfo, VersionJson};
+
+/// Fabric 官方 meta 根（BMCLAPI 有对应镜像规则 `bmclapi-fabric-meta`）。
+pub const FABRIC_META: &str = "https://meta.fabricmc.net/v2";
+/// Quilt 官方 meta 根（同上，`bmclapi-quilt-meta`）。
+pub const QUILT_META: &str = "https://meta.quiltmc.org/v3";
+
+/// meta 根地址（按加载器）。
+#[must_use]
+pub fn meta_base(kind: LoaderKind) -> &'static str {
+    match kind {
+        LoaderKind::Quilt => QUILT_META,
+        _ => FABRIC_META,
+    }
+}
+
+/// 该原版版本可用的加载器版本列表地址。
+#[must_use]
+pub fn loader_list_url(kind: LoaderKind, mc_version: &str) -> String {
+    format!("{}/versions/loader/{mc_version}", meta_base(kind))
+}
+
+/// 指定加载器版本的 launcher profile 地址（官方直出可用的版本 JSON）。
+#[must_use]
+pub fn profile_url(kind: LoaderKind, mc_version: &str, loader_version: &str) -> String {
+    format!(
+        "{}/versions/loader/{mc_version}/{loader_version}/profile/json",
+        meta_base(kind)
+    )
+}
+
+/// 列表里的一个加载器版本。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct LoaderEntry {
+    /// 版本号（`0.15.11`）。
+    #[serde(default)]
+    pub version: String,
+    /// 是否稳定版（Quilt 的列表不带这个键，缺省按稳定处理）。
+    #[serde(default = "default_true")]
+    pub stable: bool,
+    /// Maven 坐标（`net.fabricmc:fabric-loader:0.15.11`）。
+    #[serde(default)]
+    pub maven: String,
+}
+
+const fn default_true() -> bool {
+    true
+}
+
+/// 列表响应的一行（`[{ "loader": {…}, "intermediary": {…}, … }]`）。
+#[derive(Debug, Deserialize)]
+struct ListRow {
+    #[serde(default)]
+    loader: Option<LoaderEntry>,
+}
+
+/// 解析版本列表（最新的排在前，与官方顺序一致——**不重排**）。
+///
+/// # Errors
+///
+/// JSON 非法、或列表形状完全不符（顶层不是数组 / 一条都认不出）时返回 metadata 错误。
+pub fn parse_loader_list(kind: LoaderKind, json: &str) -> Result<Vec<LoaderEntry>, LoaderError> {
+    let rows: Vec<ListRow> = serde_json::from_str(json).map_err(|error| {
+        LoaderError::metadata(format!("{} 版本列表解析失败：{error}", kind.label()))
+    })?;
+    let entries: Vec<LoaderEntry> = rows
+        .into_iter()
+        .filter_map(|row| row.loader)
+        .filter(|entry| !entry.version.is_empty())
+        .collect();
+    if entries.is_empty() {
+        return Err(LoaderError::not_found(format!(
+            "{} 版本列表为空（该原版版本可能还没有对应加载器）",
+            kind.label()
+        )));
+    }
+    Ok(entries)
+}
+
+/// 从列表里挑一个默认版本：优先第一个稳定版，否则取第一个（列表最新在前）。
+#[must_use]
+pub fn pick_default(entries: &[LoaderEntry]) -> Option<&LoaderEntry> {
+    entries
+        .iter()
+        .find(|entry| entry.stable)
+        .or_else(|| entries.first())
+}
+
+/// 把官方 profile JSON 归一化成 `<mc>-<kind>-<loader>` 的 loader 版本 JSON。
+///
+/// # Errors
+///
+/// profile 不是合法版本 JSON、缺主类时返回 metadata 错误。
+pub fn build_release(
+    kind: LoaderKind,
+    mc_version: &str,
+    loader_version: &str,
+    profile_json: &str,
+) -> Result<LoaderRelease, LoaderError> {
+    let mut version_json = VersionJson::from_json_str(profile_json).map_err(|error| {
+        LoaderError::metadata(format!(
+            "{} {loader_version} 的 profile JSON 解析失败：{error}",
+            kind.label()
+        ))
+    })?;
+    let mut warnings = Vec::new();
+
+    let version_id = kind.version_id(mc_version, loader_version);
+    version_json.id = Some(version_id.clone());
+    version_json.name = Some(format!("{mc_version} · {} {loader_version}", kind.label()));
+    version_json.inherits_from = Some(mc_version.to_string());
+    // 启动用原版 jar（见模块文档第 1 条）。
+    version_json.jar = Some(mc_version.to_string());
+
+    if version_json
+        .main_class
+        .as_deref()
+        .is_none_or(|value| value.trim().is_empty())
+    {
+        return Err(LoaderError::metadata(format!(
+            "{} {loader_version} 的 profile 没有 mainClass：这份清单装上去也起不来",
+            kind.label()
+        ))
+        .with_hint("换一个加载器版本，或用官方启动器核对"));
+    }
+
+    let libraries = version_json.libraries.get_or_insert_with(Vec::new);
+    for library in libraries.iter_mut() {
+        lift_flat_digest(library);
+    }
+    ensure_loader_library(kind, loader_version, libraries, &mut warnings);
+
+    Ok(LoaderRelease {
+        kind,
+        mc_version: mc_version.to_string(),
+        loader_version: loader_version.to_string(),
+        version_id,
+        version_json,
+        support: LoaderSupport::JsonRoute,
+        installer: None,
+        install_profile: None,
+        warnings,
+    })
+}
+
+/// 把库对象顶层的 `sha1`/`size` 提升成 `downloads.artifact`（Fabric profile 的写法）。
+fn lift_flat_digest(library: &mut Library) {
+    if library.downloads.is_some() {
+        return;
+    }
+    let Some(base) = library
+        .url
+        .as_deref()
+        .filter(|url| !url.is_empty())
+        .map(str::to_string)
+    else {
+        return;
+    };
+    let Ok(relative) = library.relative_path() else {
+        return;
+    };
+    let sha1 = library
+        .extra
+        .get("sha1")
+        .and_then(serde_json::Value::as_str)
+        .map(str::to_string);
+    let size = library
+        .extra
+        .get("size")
+        .and_then(serde_json::Value::as_u64);
+    let path = relative.to_string_lossy().replace('\\', "/");
+    let url = if base.ends_with('/') {
+        format!("{base}{path}")
+    } else {
+        format!("{base}/{path}")
+    };
+    library.downloads = Some(LibraryDownloads {
+        artifact: Some(DownloadInfo {
+            id: None,
+            sha1,
+            size,
+            url: Some(url),
+            path: Some(path),
+        }),
+        classifiers: BTreeMap::new(),
+    });
+}
+
+/// loader 本体库必须在列表里：缺了就补一条（并用告警说明），别装出个"没有 loader"的实例。
+fn ensure_loader_library(
+    kind: LoaderKind,
+    loader_version: &str,
+    libraries: &mut Vec<Library>,
+    warnings: &mut Vec<String>,
+) {
+    let (group, artifact) = match kind {
+        LoaderKind::Quilt => ("org.quiltmc", "quilt-loader"),
+        _ => ("net.fabricmc", "fabric-loader"),
+    };
+    let present = libraries.iter().any(|library| {
+        library
+            .coordinate()
+            .is_ok_and(|coordinate| coordinate.group == group && coordinate.artifact == artifact)
+    });
+    if present {
+        return;
+    }
+    let maven_base = match kind {
+        LoaderKind::Quilt => "https://maven.quiltmc.org/repository/release/",
+        _ => "https://maven.fabricmc.net/",
+    };
+    libraries.push(Library {
+        name: format!("{group}:{artifact}:{loader_version}"),
+        url: Some(maven_base.to_string()),
+        ..Library::default()
+    });
+    warnings.push(format!(
+        "{} {loader_version} 的 profile 没带 {group}:{artifact}：已按 maven 坐标补一条（缺库会让游戏起不来）",
+        kind.label()
+    ));
+}
diff --git a/crates/core/src/addon/loader/forge.rs b/crates/core/src/addon/loader/forge.rs
new file mode 100644
index 0000000..76c0ee5
--- /dev/null
+++ b/crates/core/src/addon/loader/forge.rs
@@ -0,0 +1,280 @@
+//! NeoForge / Forge：installer 内的 install profile → loader 版本 JSON。
+//!
+//! 依据 `DevDocs/analyse/05-modloader-modpack.md` §1.2/§1.3：Forge 有两代 installer 协议，
+//! NeoForge 是 fork（早期与 Forge 完全同构）。判据也在那儿：install profile 有没有
+//! `spec` / processors、有没有独立的 `version.json`。maven 坐标与版本表在 [`super::maven`]。
+//!
+//! # 本模块的取舍（为什么只做一部分）
+//!
+//! 这两家都**不发**launcher 直接可用的 profile，只发 installer jar；能纯 json 化到什么程度
+//! 取决于 installer 声明的处理器：
+//!
+//! | install profile 形状 | 实测样例 | 本模块结论 |
+//! |----------------------|----------|-----------|
+//! | `spec: 1` + 有 client 侧 processors | Forge 1.20.1-47.2.0、NeoForge 21.1.80 | [`LoaderSupport::RequiresInstaller`] |
+//! | `spec: 0` + 无 processors + 内嵌 `version.json` | Forge 1.12.2-14.23.5.2860 | [`LoaderSupport::JsonRoute`] |
+//! | 只有内联 `versionInfo`（+ `install.filePath` 解包） | 1.12.2 之前的老重建版 | 明确 unsupported |
+//!
+//! 第一类必须跑 `java -cp … installertools …` 才能产出 `client-slim/extra` 等打补丁产物
+//! （processor 的 `data` 变量表里有 `MC_SLIM`/`MC_EXTRA`/`PATCHED`），解析结果因此带上
+//! [`LoaderSupport::RequiresInstaller`] 标记 + install profile 本体，交给
+//! [`super::processors`]（M35 执行器）真跑；这里的**判定**仍只管「要不要跑 installer」。
+//!
+//! 第二类的本体 jar 在 version.json 里 `url` 是空串，且**官方 maven 只发布 `-universal`
+//! classifier**（无 classifier 路径官方 404，只有 BMCLAPI 的 302 别名兜底）——
+//! 补救见 [`fill_missing_urls`]，URL 带 classifier、磁盘落点保持官方 installer 的原样。
+//!
+//! # 一条容易踩的坑：processor 的库不进启动 classpath
+//!
+//! install profile 自带的 `libraries` 是**processor 依赖**（installertools/srgutils…），
+//! 它们不属于游戏 classpath。把它们并进 loader 版本 JSON 会让启动多加载一堆无关 jar，
+//! 因此这里只记数量进告警、绝不合并；真下载它们的是 [`super::processors`]。
+
+use std::collections::BTreeMap;
+
+use serde::Deserialize;
+
+use super::maven;
+use super::plan::{LoaderRelease, LoaderSupport};
+use super::{LoaderError, LoaderKind};
+use crate::game::library::Library;
+use crate::game::manifest::VersionJson;
+
+pub use super::processors::spec::{Datum, Processor};
+
+/// 老协议 installer 的 `install` 段（`filePath` 指向内嵌的 universal jar）。
+#[derive(Debug, Clone, Default, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct LegacyInstall {
+    /// 内嵌 jar 在 installer 里的相对路径。
+    #[serde(default)]
+    pub file_path: Option<String>,
+}
+
+/// installer 里的 `install_profile.json`（只解析我们需要的键，其余忽略）。
+#[derive(Debug, Clone, Default, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct InstallProfile {
+    /// 协议代号（`1` = processor 时代）。
+    #[serde(default)]
+    pub spec: Option<i64>,
+    /// 组件名（`forge` / `NeoForge`）。
+    #[serde(default)]
+    pub profile: Option<String>,
+    /// installer 自己的版本串（`1.20.1-forge-47.2.0`）。
+    #[serde(default)]
+    pub version: Option<String>,
+    /// 目标原版版本。
+    #[serde(default)]
+    pub minecraft: Option<String>,
+    /// 内嵌版本 JSON 在 installer 里的路径（通常是 `/version.json`）。
+    #[serde(default, rename = "json")]
+    pub version_json_path: Option<String>,
+    /// universal jar 的 maven 坐标（`net.minecraftforge:forge:…`，spec 0 才有）。
+    #[serde(default)]
+    pub path: Option<String>,
+    /// processor 列表。
+    #[serde(default)]
+    pub processors: Vec<Processor>,
+    /// processor 的变量表（`{MAPPINGS}` / `{MC_SLIM}` 之类占位的数据源）。
+    #[serde(default)]
+    pub data: BTreeMap<String, Datum>,
+    /// processor / universal jar 依赖（**不是**启动 classpath，别合并）。
+    #[serde(default)]
+    pub libraries: Vec<Library>,
+    /// 老协议：内嵌 jar 解包信息。
+    #[serde(default)]
+    pub install: Option<LegacyInstall>,
+    /// 老协议：内联的版本 JSON 片段。
+    #[serde(default, rename = "versionInfo")]
+    pub version_info: Option<VersionJson>,
+}
+
+impl InstallProfile {
+    /// client 侧 processor 数量。
+    #[must_use]
+    pub fn client_processors(&self) -> usize {
+        self.processors
+            .iter()
+            .filter(|processor| processor.applies_to_client())
+            .count()
+    }
+
+    /// 是否是老协议 installer（内联 `versionInfo` + 解包 universal jar）。
+    #[must_use]
+    pub fn is_legacy_protocol(&self) -> bool {
+        self.version_json_path.is_none() && (self.install.is_some() || self.version_info.is_some())
+    }
+}
+
+/// 用 install profile + 内嵌版本 JSON 组 loader 版本。
+///
+/// `embedded` 是 installer 内 `version.json` 的内容（读不到就是 `None`）。
+///
+/// # Errors
+///
+/// 原版版本对不上、installer 里没有 `version.json`、生成的清单缺主类时返回错误。
+pub fn build_release(
+    kind: LoaderKind,
+    mc_version: &str,
+    maven_version: &str,
+    profile: &InstallProfile,
+    embedded: Option<&VersionJson>,
+) -> Result<LoaderRelease, LoaderError> {
+    if let Some(declared) = profile.minecraft.as_deref() {
+        if declared != mc_version {
+            return Err(LoaderError::metadata(format!(
+                "installer 声明的原版是 {declared}，与目标的 {mc_version} 不符（选错了加载器版本）"
+            ))
+            .with_hint("`--loader-version` 要和 `install <version>` 的原版版本配套"));
+        }
+    }
+    let loader_version = maven::display_loader_version(kind, mc_version, maven_version);
+    let version_id = kind.version_id(mc_version, &loader_version);
+    let mut warnings = Vec::new();
+
+    let Some(embedded) = embedded else {
+        let reason = if profile.is_legacy_protocol() {
+            format!(
+                "{} {} 走老协议 installer（内联 versionInfo + 解包 universal jar），本期不做解包路线",
+                kind.label(),
+                loader_version
+            )
+        } else {
+            format!(
+                "{} {} 的 installer 里没有可读的 version.json",
+                kind.label(),
+                loader_version
+            )
+        };
+        return Err(LoaderError::unsupported(reason).with_hint(
+            "这段协议要动 installer 内的 jar，属后续 mission；可先用官方启动器装好该加载器",
+        ));
+    };
+
+    let mut version_json = embedded.clone();
+    let mut support = LoaderSupport::JsonRoute;
+    let client_processors = profile.client_processors();
+    if client_processors > 0 {
+        support = LoaderSupport::RequiresInstaller {
+            reason: format!(
+                "{} {} 的 installer 声明了 {client_processors} 个 client 侧 processor（拆包/映射/打补丁），必须先外调 java 执行",
+                kind.label(),
+                loader_version
+            ),
+        };
+        warnings.push(format!(
+            "install profile 里另有 {} 个 processor 依赖（installertools 等）：它们不进启动 classpath，只在安装期给执行器用",
+            profile.libraries.len()
+        ));
+    }
+
+    version_json.id = Some(version_id.clone());
+    version_json.name = Some(format!("{mc_version} · {} {loader_version}", kind.label()));
+    version_json.inherits_from = Some(mc_version.to_string());
+    version_json.jar = Some(mc_version.to_string());
+
+    if version_json
+        .main_class
+        .as_deref()
+        .is_none_or(|value| value.trim().is_empty())
+    {
+        return Err(LoaderError::metadata(format!(
+            "{} {} 的 version.json 没有 mainClass",
+            kind.label(),
+            loader_version
+        )));
+    }
+
+    let libraries = version_json.libraries.get_or_insert_with(Vec::new);
+    let installer_body = profile.path.as_deref();
+    for library in libraries.iter_mut() {
+        fill_missing_urls(library, maven::base(kind), installer_body);
+    }
+
+    Ok(LoaderRelease {
+        kind,
+        mc_version: mc_version.to_string(),
+        loader_version,
+        version_id,
+        version_json,
+        support,
+        installer: None,
+        install_profile: Some(profile.clone()),
+        warnings,
+    })
+}
+
+/// spec 0 的 version.json 里，forge 本体库的 `url` 常是空串（jar 原本内嵌在 installer 里），
+/// 于是"补一个 maven 地址"就能直取，省掉解包 installer。
+///
+/// ⚠️ 本体 jar 的**发布 classifier 是 `universal`**：installer 内嵌的条目叫
+/// `maven/…/forge-<ver>.jar`（无 classifier），但官方 maven 只托管
+/// `forge-<ver>-universal.jar`——无 classifier 的那条路径**官方 404**
+/// （实测 1.12.2-14.23.5.2860：`-universal.jar` 200 / 4466148 字节，sha1 与 version.json 一致；
+/// 无 classifier 路径仅靠 BMCLAPI 的 302 别名兜底）。
+/// 因此这里**只改 URL**：给 installer 声明的本体构件追加 `-universal`；
+/// `artifact.path`（磁盘落点）保持官方 installer 的原样，启动 classpath 与官方布局一致。
+fn fill_missing_urls(library: &mut Library, base: &str, installer_body: Option<&str>) {
+    if library
+        .url
+        .as_deref()
+        .is_none_or(|url| url.trim().is_empty())
+    {
+        library.url = Some(if base.ends_with('/') {
+            base.to_string()
+        } else {
+            format!("{base}/")
+        });
+    }
+    // 先算"是不是 installer 声明的本体"（要读 library 的坐标），再拿 artifact 的可变借用。
+    let is_body = is_installer_body(library, installer_body);
+    let root = library.url.clone().unwrap_or_else(|| base.to_string());
+    let Some(artifact) = library
+        .downloads
+        .as_mut()
+        .and_then(|downloads| downloads.artifact.as_mut())
+    else {
+        return;
+    };
+    if artifact.has_url() {
+        return;
+    }
+    let Some(path) = artifact.path.clone() else {
+        return;
+    };
+    let remote_path = if is_body {
+        with_universal_classifier(&path)
+    } else {
+        path
+    };
+    artifact.url = Some(if root.ends_with('/') {
+        format!("{root}{remote_path}")
+    } else {
+        format!("{root}/{remote_path}")
+    });
+}
+
+/// 这条库是不是 install profile 的 `path` 声明的本体构件（`group:artifact:version`，无 classifier）。
+fn is_installer_body(library: &Library, installer_body: Option<&str>) -> bool {
+    let Some(body) = installer_body else {
+        return false;
+    };
+    let mut parts = body.split(':');
+    let (Some(group), Some(artifact)) = (parts.next(), parts.next()) else {
+        return false;
+    };
+    library.coordinate().is_ok_and(|coordinate| {
+        coordinate.classifier.is_none()
+            && coordinate.group == group
+            && coordinate.artifact == artifact
+    })
+}
+
+/// `…/forge-1.12.2-14.23.5.2860.jar` → `…/forge-1.12.2-14.23.5.2860-universal.jar`。
+fn with_universal_classifier(path: &str) -> String {
+    match path.strip_suffix(".jar") {
+        Some(stem) => format!("{stem}-universal.jar"),
+        None => path.to_string(),
+    }
+}
diff --git a/crates/core/src/addon/loader/maven.rs b/crates/core/src/addon/loader/maven.rs
new file mode 100644
index 0000000..898e2f4
--- /dev/null
+++ b/crates/core/src/addon/loader/maven.rs
@@ -0,0 +1,173 @@
+//! Maven 坐标与版本表（Forge / NeoForge）：版本列表地址、版本选择、installer 地址。
+//!
+//! 与 [`super::forge`] 的分工：这里只管"maven 上有什么版本、jar 在哪"，
+//! 那边只管"installer 里的 profile 怎么变成版本 JSON"。
+//!
+//! 镜像：两家 maven 都在 D7 镜像表里有 BMCLAPI 规则（`bmclapi-neoforge` /
+//! `bmclapi-forge-maven-net`），所以这里一律**写官方地址**，重写交给 `core::download`
+//! 的镜像展开（与 M27 的"不拼镜像 URL"纪律一致）。
+
+use super::LoaderKind;
+
+/// NeoForge maven 根（规则 `bmclapi-neoforge` 把 `/releases` 重写到 `/maven`）。
+pub const NEOFORGE_MAVEN: &str = "https://maven.neoforged.net/releases";
+/// Forge maven 根（规则 `bmclapi-forge-maven-net`）。
+pub const FORGE_MAVEN: &str = "https://maven.minecraftforge.net";
+/// NeoForge 唯一走 Forge 布局的原版版本（1.20.1 是"NeoForge 还叫 forge 的时候"）。
+pub const NEOFORGE_FORGE_LAYOUT_MC: &str = "1.20.1";
+
+/// maven 根地址。
+#[must_use]
+pub fn base(kind: LoaderKind) -> &'static str {
+    match kind {
+        LoaderKind::NeoForge => NEOFORGE_MAVEN,
+        _ => FORGE_MAVEN,
+    }
+}
+
+/// 该原版版本对应的 `maven-metadata.xml` 地址。
+#[must_use]
+pub fn metadata_url(kind: LoaderKind, mc_version: &str) -> String {
+    let (root, path) = match kind {
+        LoaderKind::NeoForge if mc_version == NEOFORGE_FORGE_LAYOUT_MC => {
+            (NEOFORGE_MAVEN, "net/neoforged/forge")
+        }
+        LoaderKind::NeoForge => (NEOFORGE_MAVEN, "net/neoforged/neoforge"),
+        _ => (FORGE_MAVEN, "net/minecraftforge/forge"),
+    };
+    format!("{root}/{path}/maven-metadata.xml")
+}
+
+/// installer jar 地址。
+#[must_use]
+pub fn installer_url(kind: LoaderKind, mc_version: &str, maven_version: &str) -> String {
+    let (root, path, file) = match kind {
+        LoaderKind::NeoForge if mc_version == NEOFORGE_FORGE_LAYOUT_MC => (
+            NEOFORGE_MAVEN,
+            "net/neoforged/forge",
+            format!("forge-{maven_version}-installer.jar"),
+        ),
+        LoaderKind::NeoForge => (
+            NEOFORGE_MAVEN,
+            "net/neoforged/neoforge",
+            format!("neoforge-{maven_version}-installer.jar"),
+        ),
+        _ => (
+            FORGE_MAVEN,
+            "net/minecraftforge/forge",
+            format!("forge-{maven_version}-installer.jar"),
+        ),
+    };
+    format!("{root}/{path}/{maven_version}/{file}")
+}
+
+/// 扫 maven-metadata.xml 里的 `<version>` 值。
+///
+/// 故意不引 XML 库：maven 元数据是**极简且稳定**的格式（只有一层 `<version>` 列表），
+/// 为它拉一个 XML 解析器不划算。解析不出就返回空表，由上层报"没有可用版本"。
+#[must_use]
+pub fn parse_metadata_versions(xml: &str) -> Vec<String> {
+    const OPEN: &str = "<version>";
+    const CLOSE: &str = "</version>";
+    let mut out = Vec::new();
+    let mut rest = xml;
+    while let Some(start) = rest.find(OPEN) {
+        let after = &rest[start + OPEN.len()..];
+        let Some(end) = after.find(CLOSE) else {
+            break;
+        };
+        let value = after[..end].trim();
+        if !value.is_empty() {
+            out.push(value.to_string());
+        }
+        rest = &after[end + CLOSE.len()..];
+    }
+    out
+}
+
+/// NeoForge 版本号 → 原版版本号（`21.1.80` → `1.21.1`，analyse/05 §1.3 的反解规则）。
+///
+/// - 主版本 `0` 是快照版（命名不带原版版本，返回 `None`）；
+/// - 主版本 `≥26` 是 MC 新命名方案（`26.1.2.125` → `26.1`）；
+/// - 其余是 `1.<主>.<次>`（`20.4.237` → `1.20.4`）。
+#[must_use]
+pub fn neoforge_mc_version(version: &str) -> Option<String> {
+    let core = version.split(['-', '+']).next().unwrap_or(version);
+    let segments: Vec<u64> = core
+        .split('.')
+        .map(str::parse::<u64>)
+        .collect::<Result<_, _>>()
+        .ok()?;
+    let (major, minor) = (*segments.first()?, *segments.get(1)?);
+    match major {
+        0 => None,
+        26.. => Some(format!("{major}.{minor}")),
+        _ => Some(format!("1.{major}.{minor}")),
+    }
+}
+
+/// maven 版本是否属于该原版版本。
+#[must_use]
+pub fn matches_mc(kind: LoaderKind, mc_version: &str, version: &str) -> bool {
+    match kind {
+        LoaderKind::NeoForge if mc_version == NEOFORGE_FORGE_LAYOUT_MC => {
+            version.starts_with(&format!("{mc_version}-"))
+        }
+        LoaderKind::NeoForge => neoforge_mc_version(version).as_deref() == Some(mc_version),
+        _ => version.starts_with(&format!("{mc_version}-")),
+    }
+}
+
+/// 从 maven 版本表里挑出属于该原版版本的加载器版本（**升序**，末尾最好）。
+#[must_use]
+pub fn select_versions(kind: LoaderKind, mc_version: &str, versions: &[String]) -> Vec<String> {
+    let mut picked: Vec<String> = versions
+        .iter()
+        .filter(|version| matches_mc(kind, mc_version, version))
+        .cloned()
+        .collect();
+    picked.sort_by(|left, right| {
+        numeric_key(left)
+            .cmp(&numeric_key(right))
+            .then_with(|| left.cmp(right))
+    });
+    picked
+}
+
+/// 用户给的版本号归一成 maven 版本号（Forge 的 maven 版本带原版前缀）。
+///
+/// `--loader-version 47.2.0` 与 `--loader-version 1.20.1-47.2.0` 都接受；
+/// NeoForge（非 1.20.1 布局）本身就是完整 maven 版本，原样返回。
+#[must_use]
+pub fn normalize_maven_version(kind: LoaderKind, mc_version: &str, raw: &str) -> String {
+    let raw = raw.trim();
+    let needs_prefix = match kind {
+        LoaderKind::NeoForge => mc_version == NEOFORGE_FORGE_LAYOUT_MC,
+        _ => true,
+    };
+    if needs_prefix && !raw.starts_with(&format!("{mc_version}-")) {
+        format!("{mc_version}-{raw}")
+    } else {
+        raw.to_string()
+    }
+}
+
+/// 用户视角的加载器版本号（Forge 去掉原版前缀，NeoForge 原样）。
+#[must_use]
+pub fn display_loader_version(kind: LoaderKind, mc_version: &str, maven_version: &str) -> String {
+    match kind {
+        LoaderKind::NeoForge if mc_version != NEOFORGE_FORGE_LAYOUT_MC => maven_version.to_string(),
+        _ => maven_version
+            .strip_prefix(&format!("{mc_version}-"))
+            .unwrap_or(maven_version)
+            .to_string(),
+    }
+}
+
+/// 版本号 → 可比较的数字键（非数字段按 0，保证不 panic）。
+fn numeric_key(version: &str) -> Vec<u64> {
+    version
+        .split(['-', '.', '+'])
+        .map(|segment| segment.parse::<u64>().unwrap_or(0))
+        .collect()
+}
diff --git a/crates/core/src/addon/loader/meta.rs b/crates/core/src/addon/loader/meta.rs
new file mode 100644
index 0000000..29d0367
--- /dev/null
+++ b/crates/core/src/addon/loader/meta.rs
@@ -0,0 +1,242 @@
+//! 加载器元数据的网络层：版本列表 + 官方 profile/installer → [`LoaderRelease`]。
+//!
+//! 分工与 M27 的 [`crate::game::install::RemoteSource`] 一样：**只发请求、只解析**，
+//! 不写游戏目录（installer jar 落 `.ULL/cache/meta/` 作离线复用），镜像/退避/health 全在
+//! `core::download` 的引擎里（我们一律递**官方地址**，重写由镜像表负责）。
+//!
+//! 两族的取数路径完全不同：
+//!
+//! ```text
+//! Fabric / Quilt : meta API → profile/json（官方直出可用版本 JSON）
+//! NeoForge/Forge : maven-metadata.xml → installer jar → 读 install_profile.json + version.json
+//! ```
+
+use std::fs::File;
+use std::path::{Path, PathBuf};
+
+use zip::ZipArchive;
+
+use super::fabric;
+use super::forge::{self, InstallProfile};
+use super::maven;
+use super::plan::LoaderRelease;
+use super::{LoaderError, LoaderKind};
+use crate::download::{DownloadEngine, DownloadRequest, ResourceKind};
+use crate::game::manifest::VersionJson;
+
+/// installer jar 的缓存文件名前缀（超长/含 `+` 的版本串会被规整成安全文件名）。
+const INSTALLER_TAG: &str = "installer";
+
+/// 远端加载器元数据来源。
+pub struct LoaderSource<'a> {
+    engine: &'a DownloadEngine,
+    meta_cache: &'a Path,
+}
+
+impl<'a> LoaderSource<'a> {
+    /// 绑定下载引擎与元数据缓存目录（`.ULL/cache/meta/`）。
+    #[must_use]
+    pub fn new(engine: &'a DownloadEngine, meta_cache: &'a Path) -> Self {
+        Self { engine, meta_cache }
+    }
+
+    /// 取该原版版本可用的加载器版本列表（**最新在前**）。
+    ///
+    /// # Errors
+    ///
+    /// 网络失败、元数据解析失败、该原版版本没有加载器版本时返回 [`LoaderError`]。
+    pub async fn loader_versions(
+        &self,
+        kind: LoaderKind,
+        mc_version: &str,
+    ) -> Result<Vec<String>, LoaderError> {
+        if kind.is_fabric_family() {
+            let url = fabric::loader_list_url(kind, mc_version);
+            let body = self.fetch_text(&url).await?;
+            let entries = fabric::parse_loader_list(kind, &body)?;
+            return Ok(entries.into_iter().map(|entry| entry.version).collect());
+        }
+        let url = maven::metadata_url(kind, mc_version);
+        let body = self.fetch_text(&url).await?;
+        let all = maven::parse_metadata_versions(&body);
+        // maven 表是升序的，统一成"最新在前"。
+        let mut picked = maven::select_versions(kind, mc_version, &all);
+        picked.reverse();
+        if picked.is_empty() {
+            return Err(LoaderError::not_found(format!(
+                "{} 在 {} 上没有可用版本（maven 表 {} 条，全部与该原版版本不匹配）",
+                kind.label(),
+                mc_version,
+                all.len()
+            )));
+        }
+        Ok(picked)
+    }
+
+    /// 解析一个加载器版本（`loader_version` 为 `None` 时取官方默认：Fabric 系取首个稳定版，
+    /// maven 系取该原版版本下最新的一版）。
+    ///
+    /// # Errors
+    ///
+    /// 网络失败、版本不存在、installer 缺 profile、协议不受支持时返回 [`LoaderError`]。
+    pub async fn resolve(
+        &self,
+        kind: LoaderKind,
+        mc_version: &str,
+        loader_version: Option<&str>,
+    ) -> Result<LoaderRelease, LoaderError> {
+        let requested = loader_version
+            .map(str::trim)
+            .filter(|value| !value.is_empty());
+        if kind.is_fabric_family() {
+            let version = match requested {
+                Some(version) => version.to_string(),
+                None => {
+                    let url = fabric::loader_list_url(kind, mc_version);
+                    let body = self.fetch_text(&url).await?;
+                    let entries = fabric::parse_loader_list(kind, &body)?;
+                    fabric::pick_default(&entries)
+                        .map(|entry| entry.version.clone())
+                        .ok_or_else(|| {
+                            LoaderError::not_found(format!("{} 没有可用的加载器版本", kind.label()))
+                        })?
+                }
+            };
+            let url = fabric::profile_url(kind, mc_version, &version);
+            let body = self.fetch_text(&url).await?;
+            return fabric::build_release(kind, mc_version, &version, &body);
+        }
+
+        let maven_version = match requested {
+            Some(raw) => maven::normalize_maven_version(kind, mc_version, raw),
+            None => self
+                .loader_versions(kind, mc_version)
+                .await?
+                .into_iter()
+                .next()
+                .ok_or_else(|| {
+                    LoaderError::not_found(format!("{} 没有可用的加载器版本", kind.label()))
+                })?,
+        };
+        let url = maven::installer_url(kind, mc_version, &maven_version);
+        let path = self.installer_path(kind, &maven_version);
+        let jar = self.fetch_installer(&url, &path).await?;
+        let (profile, embedded) = read_installer(&jar)?;
+        let mut release = forge::build_release(
+            kind,
+            mc_version,
+            &maven_version,
+            &profile,
+            embedded.as_ref(),
+        )?;
+        // M35 执行器要的两样东西：installer 本体（跑 processor 与解包）与它声明的 profile。
+        release.installer = Some(jar);
+        Ok(release)
+    }
+
+    /// installer jar 的本地缓存路径（`+`/非法字符规整成 `_`）。
+    fn installer_path(&self, kind: LoaderKind, maven_version: &str) -> PathBuf {
+        let safe: String = maven_version
+            .chars()
+            .map(|ch| {
+                if ch.is_ascii_alphanumeric() || matches!(ch, '.' | '-' | '_') {
+                    ch
+                } else {
+                    '_'
+                }
+            })
+            .collect();
+        self.meta_cache
+            .join(format!("{}-{safe}-{INSTALLER_TAG}.jar", kind.as_str()))
+    }
+
+    /// 取 installer jar：本地缓存里有可读的 zip 就直接用（离线复用），否则下载。
+    async fn fetch_installer(&self, url: &str, path: &Path) -> Result<PathBuf, LoaderError> {
+        if path.is_file() && ZipArchive::new(File::open(path).map_err(io_error(path))?).is_ok() {
+            return Ok(path.to_path_buf());
+        }
+        let request = DownloadRequest::new(ResourceKind::Library, url, path.to_path_buf());
+        let outcome = self.engine.download(request).await?;
+        Ok(outcome.path)
+    }
+
+    /// 取一小段文本元数据（版本列表 / profile JSON / maven metadata）。
+    async fn fetch_text(&self, url: &str) -> Result<String, LoaderError> {
+        let dest = self.meta_cache.join("loader-meta.bin");
+        let bytes = self
+            .engine
+            .download_bytes(DownloadRequest::new(
+                ResourceKind::VersionManifest,
+                url,
+                dest,
+            ))
+            .await?;
+        String::from_utf8(bytes)
+            .map_err(|_| LoaderError::metadata(format!("元数据不是 UTF-8：{url}")))
+    }
+}
+
+/// 读 installer jar 里的 `install_profile.json` 与内嵌的版本 JSON。
+///
+/// 内嵌版本 JSON 的路径来自 profile 的 `json` 字段（通常 `/version.json`）；
+/// 该条目不存在时返回 `None`，由 [`forge::build_release`] 判定为 unsupported。
+///
+/// # Errors
+///
+/// 不是合法 zip、缺 `install_profile.json`、profile/版本 JSON 无法解析时返回 metadata 错误。
+pub fn read_installer(path: &Path) -> Result<(InstallProfile, Option<VersionJson>), LoaderError> {
+    let file = File::open(path).map_err(io_error(path))?;
+    let mut archive = ZipArchive::new(file).map_err(|error| {
+        LoaderError::metadata(format!("{} 不是合法 zip：{error}", path.display()))
+    })?;
+
+    let profile_text = read_entry(&mut archive, "install_profile.json")?.ok_or_else(|| {
+        LoaderError::metadata(format!(
+            "{} 里没有 install_profile.json（不是 Forge/NeoForge installer？）",
+            path.display()
+        ))
+    })?;
+    let profile: InstallProfile = serde_json::from_str(&profile_text).map_err(|error| {
+        LoaderError::metadata(format!("install_profile.json 解析失败：{error}"))
+    })?;
+
+    let embedded = match profile
+        .version_json_path
+        .as_deref()
+        .map(|entry| entry.trim_start_matches('/'))
+        .filter(|entry| !entry.is_empty())
+    {
+        Some(entry) => match read_entry(&mut archive, entry)? {
+            Some(text) => Some(VersionJson::from_json_str(&text).map_err(|error| {
+                LoaderError::metadata(format!("installer 内 {entry} 解析失败：{error}"))
+            })?),
+            None => None,
+        },
+        None => None,
+    };
+    Ok((profile, embedded))
+}
+
+/// 读一个 zip 条目成字符串；条目不存在返回 `Ok(None)`。
+fn read_entry(archive: &mut ZipArchive<File>, name: &str) -> Result<Option<String>, LoaderError> {
+    use std::io::Read;
+
+    let mut entry = match archive.by_name(name) {
+        Ok(entry) => entry,
+        Err(zip::result::ZipError::FileNotFound) => return Ok(None),
+        Err(error) => {
+            return Err(LoaderError::metadata(format!(
+                "读 installer 条目 {name} 失败：{error}"
+            )))
+        }
+    };
+    let mut text = String::new();
+    entry
+        .read_to_string(&mut text)
+        .map_err(|error| LoaderError::io(format!("installer 条目 {name} 不是可读文本：{error}")))?;
+    Ok(Some(text))
+}
+
+fn io_error(path: &Path) -> impl FnOnce(std::io::Error) -> LoaderError + '_ {
+    move |error| LoaderError::io(format!("{} 读写失败：{error}", path.display()))
+}
diff --git a/crates/core/src/addon/loader/mod.rs b/crates/core/src/addon/loader/mod.rs
new file mode 100644
index 0000000..d8eee17
--- /dev/null
+++ b/crates/core/src/addon/loader/mod.rs
@@ -0,0 +1,249 @@
+//! 加载器安装（Fabric / Quilt / NeoForge / Forge）：官方元数据 → loader 版本 JSON → 补库清单。
+//!
+//! 设计输入：`DevDocs/PlanDoc/08-mod-and-recommend.md` §1（D10 加载器安装）、
+//! `DevDocs/analyse/05-modloader-modpack.md` §1（五加载器安装协议、`patch + priority` 主线）。
+//!
+//! # 与 M27 安装层的关系（不复制粘贴，只叠一层）
+//!
+//! 加载器不是"另一个版本"，而是**叠在已装原版之上的一个 `inheritsFrom` 层**：
+//!
+//! ```text
+//! versions/1.20.1/1.20.1.json              原版（M27 负责装）
+//! versions/1.20.1-fabric-0.15.11/…json    loader 层：inheritsFrom=1.20.1 + 主类 + loader 库
+//! ```
+//!
+//! 因此本模块**只做两件事**：①把官方元数据翻译成一份 loader 版本 JSON；
+//! ②把它的库列表交给 [`crate::game::install::libraries`] 展开成下载计划。
+//! 落盘、跳过判定、实例登记一律复用 M27（[`crate::game::install::execute`] / `register`），
+//! 不另起一套下载/写盘逻辑。
+//!
+//! # 三条路线（按"能不能不跑 java 就装出来"分类，而不是按加载器名字）
+//!
+//! | 路线 | 加载器 | 做法 |
+//! |------|--------|------|
+//! | [`LoaderSupport::JsonRoute`] | Fabric / Quilt | 官方 meta 直接给 launcher 用的 profile JSON |
+//! | [`LoaderSupport::JsonRoute`] | Forge spec-0（如 1.12.2 重建版） | installer 里的 `version.json` + 库清单，universal jar 走 maven 直取 |
+//! | [`LoaderSupport::RequiresInstaller`] | Forge spec≥1 / NeoForge | installer 声明了 client 侧 processors（拆包/映射），**必须外调 java** |
+//!
+//! 第三类本期只出**明确 unsupported**：版本 JSON 与库清单仍照常生成（`--dry-run` 可看），
+//! 但真装会被拒——半成品实例比明确报错更糟（沿 M27 §7「如实告知」的纪律）。
+//! 老协议 installer（内联 `versionInfo` + universal jar 解包，≈1.12.2 之前的重建版）同样归 unsupported。
+
+pub mod fabric;
+pub mod forge;
+pub mod maven;
+pub mod meta;
+pub mod plan;
+pub mod processors;
+
+#[cfg(test)]
+mod tests;
+
+pub use meta::LoaderSource;
+pub use plan::{LoaderInstallPlan, LoaderPlanInput, LoaderRelease, LoaderSupport};
+
+use std::fmt;
+
+use crate::download::{DownloadError, DownloadErrorKind};
+
+/// 支持的加载器种类。
+///
+/// `vanilla` / `none` **不在这里**：那是"不装加载器"，由 CLI 走 M27 的原版路径。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub enum LoaderKind {
+    /// Fabric（`meta.fabricmc.net`，纯 meta，无 installer）。
+    Fabric,
+    /// Quilt（`meta.quiltmc.org`，与 Fabric 同构）。
+    Quilt,
+    /// NeoForge（`maven.neoforged.net`，installer 内嵌 install profile）。
+    NeoForge,
+    /// Forge（`maven.minecraftforge.net`，两代 installer 协议）。
+    Forge,
+}
+
+impl LoaderKind {
+    /// 解析命令行里的加载器名（大小写不敏感；`neo-forge` 是 Modrinth 的另一种拼法）。
+    #[must_use]
+    pub fn parse(raw: &str) -> Option<Self> {
+        match raw.trim().to_ascii_lowercase().as_str() {
+            "fabric" => Some(Self::Fabric),
+            "quilt" => Some(Self::Quilt),
+            "neoforge" | "neo-forge" => Some(Self::NeoForge),
+            "forge" => Some(Self::Forge),
+            _ => None,
+        }
+    }
+
+    /// 稳定字符串 id（进版本 id、JSON 输出与日志，**不要改名**）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Fabric => "fabric",
+            Self::Quilt => "quilt",
+            Self::NeoForge => "neoforge",
+            Self::Forge => "forge",
+        }
+    }
+
+    /// 人读名称。
+    #[must_use]
+    pub const fn label(self) -> &'static str {
+        match self {
+            Self::Fabric => "Fabric",
+            Self::Quilt => "Quilt",
+            Self::NeoForge => "NeoForge",
+            Self::Forge => "Forge",
+        }
+    }
+
+    /// 是否属于 Fabric 系（纯 meta、profile JSON 直接可用）。
+    #[must_use]
+    pub const fn is_fabric_family(self) -> bool {
+        matches!(self, Self::Fabric | Self::Quilt)
+    }
+
+    /// 全部加载器（CLI 的 `--loader` 枚举提示用）。
+    #[must_use]
+    pub const fn all() -> &'static [Self] {
+        &[Self::Fabric, Self::Quilt, Self::NeoForge, Self::Forge]
+    }
+
+    /// loader 版本 id 的词根：`<mc>-<kind>-<loader>`（`versions/<id>/` 与实例 `versionId` 都用它）。
+    #[must_use]
+    pub fn version_id(self, mc_version: &str, loader_version: &str) -> String {
+        format!("{mc_version}-{}-{loader_version}", self.as_str())
+    }
+}
+
+impl fmt::Display for LoaderKind {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str(self.label())
+    }
+}
+
+/// 加载器安装失败的大类（CLI 据此给稳定错误码 `loader_*`）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum LoaderErrorKind {
+    /// 该加载器/该版本走不通我们的路线（需要跑 installer 或属未支持的老协议）。
+    Unsupported,
+    /// 官方元数据里没有这个加载器版本（或没有匹配该原版版本的版本）。
+    NotFound,
+    /// 元数据解析失败（profile JSON / install profile / maven metadata 坏了）。
+    Metadata,
+    /// 网络侧失败（所有候选源都失败 / 超时）。
+    Network,
+    /// 本地 IO（读 installer 缓存、写盘失败）。
+    Io,
+}
+
+impl LoaderErrorKind {
+    /// 稳定字符串 id（进 `--json` 的 `error.code`）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Unsupported => "loader_unsupported",
+            Self::NotFound => "loader_not_found",
+            Self::Metadata => "loader_metadata",
+            Self::Network => "loader_network",
+            Self::Io => "loader_io",
+        }
+    }
+}
+
+/// 加载器安装错误：大类 + 人读说明 + 可选提示。
+#[derive(Debug, Clone)]
+pub struct LoaderError {
+    kind: LoaderErrorKind,
+    message: String,
+    hint: Option<String>,
+}
+
+impl LoaderError {
+    /// 构造。
+    #[must_use]
+    pub fn new(kind: LoaderErrorKind, message: impl Into<String>) -> Self {
+        Self {
+            kind,
+            message: message.into(),
+            hint: None,
+        }
+    }
+
+    /// 走不通我们的路线（需要外调 java installer / 老协议）。
+    #[must_use]
+    pub fn unsupported(message: impl Into<String>) -> Self {
+        Self::new(LoaderErrorKind::Unsupported, message)
+    }
+
+    /// 元数据里查不到。
+    #[must_use]
+    pub fn not_found(message: impl Into<String>) -> Self {
+        Self::new(LoaderErrorKind::NotFound, message)
+    }
+
+    /// 元数据坏了/形状不符。
+    #[must_use]
+    pub fn metadata(message: impl Into<String>) -> Self {
+        Self::new(LoaderErrorKind::Metadata, message)
+    }
+
+    /// 本地 IO。
+    #[must_use]
+    pub fn io(message: impl Into<String>) -> Self {
+        Self::new(LoaderErrorKind::Io, message)
+    }
+
+    /// 补一句提示。
+    #[must_use]
+    pub fn with_hint(mut self, hint: impl Into<String>) -> Self {
+        self.hint = Some(hint.into());
+        self
+    }
+
+    /// 大类。
+    #[must_use]
+    pub const fn kind(&self) -> LoaderErrorKind {
+        self.kind
+    }
+
+    /// 人读说明。
+    #[must_use]
+    pub fn message(&self) -> &str {
+        &self.message
+    }
+
+    /// 下一步提示。
+    #[must_use]
+    pub fn hint(&self) -> Option<&str> {
+        self.hint.as_deref()
+    }
+}
+
+impl fmt::Display for LoaderError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str(&self.message)
+    }
+}
+
+impl std::error::Error for LoaderError {}
+
+impl From<DownloadError> for LoaderError {
+    fn from(error: DownloadError) -> Self {
+        let kind = match error.kind {
+            DownloadErrorKind::Io => LoaderErrorKind::Io,
+            DownloadErrorKind::InvalidRequest => LoaderErrorKind::Metadata,
+            DownloadErrorKind::Integrity
+            | DownloadErrorKind::NotFound
+            | DownloadErrorKind::ServerError
+            | DownloadErrorKind::Timeout
+            | DownloadErrorKind::Network
+            | DownloadErrorKind::RangeUnsupported
+            | DownloadErrorKind::AllSourcesFailed => LoaderErrorKind::Network,
+        };
+        let mut message = error.message.clone();
+        if let Some(source) = &error.source {
+            message.push_str(&format!("（源 {source}）"));
+        }
+        Self::new(kind, message)
+    }
+}
diff --git a/crates/core/src/addon/loader/plan.rs b/crates/core/src/addon/loader/plan.rs
new file mode 100644
index 0000000..dc8aae8
--- /dev/null
+++ b/crates/core/src/addon/loader/plan.rs
@@ -0,0 +1,235 @@
+//! 加载器安装计划：一份 loader 版本 JSON + 需要补下载的库清单。
+//!
+//! 计划层与网络层分开：网络在 [`super::meta`]，这里只做**纯计算**——把已经解析好的
+//! loader 版本 JSON 交给 [`crate::game::install::libraries`] 展开成待下载文件，再包成
+//! M27 的 [`InstallPlan`]（落盘/跳过判定/原子写版本 JSON 全部沿用同一套实现）。
+//!
+//! 为什么不直接调 [`InstallPlan::build`]：那是"装一个完整原版版本"的入口（客户端 jar +
+//! 资源索引 + 逐对象），而 loader 层**只有库**——jar 与资源都由 `inheritsFrom` 的原版提供。
+//! 直接组 [`InstallPlan`] 的字段既省掉一堆"没有 jar"的告警，又不复制任何路径规则。
+
+use std::path::PathBuf;
+
+use serde_json::{json, Value};
+
+use super::forge::InstallProfile;
+use super::LoaderKind;
+use crate::game::arguments::Environment;
+use crate::game::install::libraries;
+use crate::game::install::{InstallPlan, PlanFile};
+use crate::game::layout::GameLayout;
+use crate::game::manifest::VersionJson;
+
+/// 加载器版本的可用路线（判据是"能不能不跑 java 就装出来"，不是加载器名字）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum LoaderSupport {
+    /// 纯元数据/纯下载路线：不跑任何外部进程。
+    JsonRoute,
+    /// 官方 installer 声明了必须先跑的 processors（拆包/映射），走 M35 执行器外调 java。
+    RequiresInstaller {
+        /// 人读原因（含该版本声明的 processors 数量与作用）。
+        reason: String,
+    },
+}
+
+impl LoaderSupport {
+    /// 稳定字符串 id（JSON 输出用）。
+    #[must_use]
+    pub const fn as_str(&self) -> &'static str {
+        match self {
+            Self::JsonRoute => "json_route",
+            Self::RequiresInstaller { .. } => "requires_installer",
+        }
+    }
+
+    /// 是否可真正安装（两条路线都走到了：processors 走 M35 执行器）。
+    #[must_use]
+    pub const fn is_installable(&self) -> bool {
+        true
+    }
+
+    /// 是否要外调 java 跑 installer processors。
+    #[must_use]
+    pub const fn requires_installer(&self) -> bool {
+        matches!(self, Self::RequiresInstaller { .. })
+    }
+
+    /// JSON 视图。
+    #[must_use]
+    pub fn to_json(&self) -> Value {
+        match self {
+            Self::JsonRoute => json!({"mode": self.as_str(), "requires_installer": false}),
+            Self::RequiresInstaller { reason } => {
+                json!({"mode": self.as_str(), "requires_installer": true, "reason": reason})
+            }
+        }
+    }
+}
+
+/// 一次解析出来的加载器版本（网络层产物，计划层的输入）。
+#[derive(Debug, Clone)]
+pub struct LoaderRelease {
+    /// 加载器种类。
+    pub kind: LoaderKind,
+    /// 目标原版版本（`inheritsFrom` 的父版本 id）。
+    pub mc_version: String,
+    /// 加载器自身版本号（`0.15.11` / `47.2.0` / `21.1.80`）。
+    pub loader_version: String,
+    /// 生成的 loader 版本 id（`1.20.1-fabric-0.15.11`，即 `versions/<id>/` 的目录名）。
+    pub version_id: String,
+    /// loader 版本 JSON（`inheritsFrom` 指向原版）。
+    pub version_json: VersionJson,
+    /// 可走哪条路线。
+    pub support: LoaderSupport,
+    /// installer jar 的磁盘路径（M35 执行器的输入；Fabric 系为 `None`）。
+    pub installer: Option<PathBuf>,
+    /// installer 里读出来的 install profile（执行器要 `processors` / `data` / `libraries`）。
+    pub install_profile: Option<InstallProfile>,
+    /// 解析期告警（不致命：例如 profile 缺 loader 库时我们补了一条）。
+    pub warnings: Vec<String>,
+}
+
+impl LoaderRelease {
+    /// 是否可真正安装。
+    #[must_use]
+    pub const fn is_installable(&self) -> bool {
+        self.support.is_installable()
+    }
+
+    /// 是否要外调 java 跑 installer processors。
+    #[must_use]
+    pub const fn requires_installer(&self) -> bool {
+        self.support.requires_installer()
+    }
+
+    /// 需要 installer 时的原因（`JsonRoute` 返回 `None`）。
+    #[must_use]
+    pub fn installer_reason(&self) -> Option<&str> {
+        match &self.support {
+            LoaderSupport::JsonRoute => None,
+            LoaderSupport::RequiresInstaller { reason } => Some(reason),
+        }
+    }
+
+    /// JSON 视图（`--dry-run` 与诊断共用）。
+    #[must_use]
+    pub fn to_json(&self) -> Value {
+        json!({
+            "kind": self.kind.as_str(),
+            "label": self.kind.label(),
+            "mc_version": self.mc_version,
+            "loader_version": self.loader_version,
+            "version_id": self.version_id,
+            "inherits_from": self.version_json.inherits_from,
+            "jar": self.version_json.jar,
+            "main_class": self.version_json.main_class,
+            "libraries": self.version_json.libraries.as_ref().map_or(0, Vec::len),
+            "support": self.support.to_json(),
+            "warnings": self.warnings,
+        })
+    }
+}
+
+/// [`LoaderInstallPlan::build`] 的输入。
+pub struct LoaderPlanInput<'a> {
+    /// 游戏目录布局（`versions/` `libraries/` 的路径规则）。
+    pub layout: &'a GameLayout,
+    /// 已解析的加载器版本。
+    pub release: &'a LoaderRelease,
+    /// 规则求值环境（OS / 架构 / 特性开关）。
+    pub environment: &'a Environment,
+    /// 原版的 `versions/<mc>/<mc>.json` 是否已在盘上。
+    pub vanilla_installed: bool,
+}
+
+/// 加载器安装计划：M27 的 [`InstallPlan`] + 加载器自己的上下文。
+///
+/// 执行期直接 `execute(&engine, &plan.install, …)`：那份计划里的 `version_json` 就是
+/// 带 `inheritsFrom` 的 loader 层，`execute` 会在**全部库就绪后**原子写到
+/// `versions/<loader-id>/<loader-id>.json`（半成品不写，沿 M27 的纪律）。
+#[derive(Debug, Clone)]
+pub struct LoaderInstallPlan {
+    /// 加载器版本上下文。
+    pub release: LoaderRelease,
+    /// 待执行的下载计划（库 + 版本 JSON 落盘）。
+    pub install: InstallPlan,
+    /// 是否还需要先装原版（原版已装则 `false`，真装时会跳过）。
+    pub vanilla_install_needed: bool,
+}
+
+impl LoaderInstallPlan {
+    /// 组计划。
+    ///
+    /// 缺下载地址的库降级成告警（见 [`Self::summary_json`] 的 `warnings`），不硬失败——
+    /// 与 M27「宁可给出可修复的骨架，也不静默假装成功」一致。
+    #[must_use]
+    pub fn build(input: LoaderPlanInput<'_>) -> Self {
+        let release = input.release;
+        let (files, library_warnings) = libraries::plan(
+            input.layout,
+            &release.version_id,
+            release
+                .version_json
+                .libraries
+                .as_deref()
+                .unwrap_or_default(),
+            input.environment,
+        );
+
+        let mut warnings = release.warnings.clone();
+        warnings.extend(library_warnings);
+        if let Some(reason) = release.installer_reason() {
+            warnings.push(format!("需要外调 java 跑 installer processors：{reason}"));
+        }
+        if !input.vanilla_installed {
+            warnings.push(format!(
+                "原版 {} 尚未安装：执行时会先装原版再叠加载器",
+                release.mc_version
+            ));
+        }
+
+        let install = InstallPlan {
+            version_id: release.version_id.clone(),
+            // jar 来自原版层（生成的 loader JSON 已把 `jar` 钉成原版 id）。
+            jar_id: release.mc_version.clone(),
+            game_root: input.layout.root().to_path_buf(),
+            version_json_path: input.layout.version_json(&release.version_id),
+            files,
+            version_json: release.version_json.clone(),
+            prefetched: Vec::new(),
+            warnings,
+        };
+
+        Self {
+            release: release.clone(),
+            install,
+            vanilla_install_needed: !input.vanilla_installed,
+        }
+    }
+
+    /// 计划里的待下载文件。
+    #[must_use]
+    pub fn files(&self) -> &[PlanFile] {
+        &self.install.files
+    }
+
+    /// 告警（含"原版未装""本期不能真装"）。
+    #[must_use]
+    pub fn warnings(&self) -> &[String] {
+        &self.install.warnings
+    }
+
+    /// 汇总 JSON（`--dry-run` 的主载荷）。
+    #[must_use]
+    pub fn summary_json(&self) -> Value {
+        let mut summary = self.install.summary_json();
+        if let Some(object) = summary.as_object_mut() {
+            object.insert("loader".to_string(), self.release.to_json());
+            object.insert(
+                "vanilla_install_needed".to_string(),
+                json!(self.vanilla_install_needed),
+            );
+        }
+        summary
+    }
+}
diff --git a/crates/core/src/addon/loader/processors/download.rs b/crates/core/src/addon/loader/processors/download.rs
new file mode 100644
index 0000000..a9e39ba
--- /dev/null
+++ b/crates/core/src/addon/loader/processors/download.rs
@@ -0,0 +1,83 @@
+//! processor 依赖库的下载：把 [`ProcessorPlan::libraries`] 交给 M27 的下载引擎。
+//!
+//! 为什么不直接复用 `game::install::execute`：那个入口在**全量就绪后写版本 JSON**，
+//! 而 processors 的产物要先于版本清单落盘（版本 JSON 存在 = 这版真装完了）。
+//! 所以这里只借它的**逐文件跳过判定**（`current_bytes`：摘要 → 大小 → 存在即信）
+//! 与结果类型，下载本身仍走同一个引擎——镜像、健康度、退避、续传一条不少。
+
+use futures_util::stream::{self, StreamExt};
+
+use crate::download::DownloadEngine;
+use crate::game::install::execute::current_bytes;
+use crate::game::install::{
+    FileFailure, FileOutcome, FileStatus, InstallReport, PlanFile, ProgressSink,
+};
+
+/// 并发下载 processor 依赖库（`concurrency` 上限，引擎内部另有信号量）。
+///
+/// 失败**不**中断：与 M27 一致，逐文件结构化返回，由调用方决定是否继续。
+pub async fn download_libraries(
+    engine: &DownloadEngine,
+    files: &[PlanFile],
+    concurrency: usize,
+    sink: Option<ProgressSink>,
+) -> InstallReport {
+    let outcomes: Vec<FileOutcome> = stream::iter(files.iter())
+        .map(|file| {
+            let sink = sink.clone();
+            async move {
+                let outcome = install_one(engine, file).await;
+                if let Some(sink) = &sink {
+                    sink(&outcome);
+                }
+                outcome
+            }
+        })
+        .buffer_unordered(concurrency.max(1))
+        .collect()
+        .await;
+
+    InstallReport {
+        files: outcomes,
+        version_json: None,
+        warnings: Vec::new(),
+    }
+}
+
+/// 单文件：先判「已就绪」，否则走引擎下载。
+async fn install_one(engine: &DownloadEngine, file: &PlanFile) -> FileOutcome {
+    if let Some(bytes) = current_bytes(file) {
+        return FileOutcome {
+            role: file.role,
+            name: file.name.clone(),
+            dest: file.dest.clone(),
+            status: FileStatus::Skipped,
+            bytes,
+            source: None,
+            failure: None,
+        };
+    }
+    match engine.download(file.request()).await {
+        Ok(outcome) => FileOutcome {
+            role: file.role,
+            name: file.name.clone(),
+            dest: file.dest.clone(),
+            status: FileStatus::Downloaded,
+            bytes: outcome.bytes,
+            source: Some(outcome.source),
+            failure: None,
+        },
+        Err(error) => FileOutcome {
+            role: file.role,
+            name: file.name.clone(),
+            dest: file.dest.clone(),
+            status: FileStatus::Failed,
+            bytes: 0,
+            source: None,
+            failure: Some(FileFailure {
+                kind: error.kind,
+                message: error.message.clone(),
+            }),
+        },
+    }
+}
diff --git a/crates/core/src/addon/loader/processors/error.rs b/crates/core/src/addon/loader/processors/error.rs
new file mode 100644
index 0000000..99d53ad
--- /dev/null
+++ b/crates/core/src/addon/loader/processors/error.rs
@@ -0,0 +1,181 @@
+//! processors 执行器的错误分类（CLI 据此给稳定错误码 `processor_*`）。
+//!
+//! 与 [`crate::addon::loader::LoaderError`] 分开是刻意的：加载器**解析**阶段的失败
+//! （元数据坏了、版本不存在）与**执行**阶段的失败（java 跑挂了、产物没落盘）对用户
+//! 是完全不同的两件事——前者换版本/换线路，后者多半是 Java 或磁盘问题。
+//! 失败分流也是 mission 的硬要求：`processor_failed` 必须能单独被脚本识别。
+
+use std::fmt;
+
+/// processor 执行失败的大类。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ProcessorErrorKind {
+    /// 规划期：install profile 形状不对（缺 `jar`、坐标不合法、变量缺定义）。
+    Plan,
+    /// 找不到可用的 Java（M33 的解析链一个候选都没有）。
+    Java,
+    /// processor 自己要用的 jar/依赖不在盘上（下载没覆盖到）。
+    Library,
+    /// 外调 java 失败（非零退出），消息里带脱敏后的 stderr 尾部。
+    Failed,
+    /// processor 跑完了但产物没落盘。
+    Output,
+    /// 本地 IO（解包 installer 条目、建目录、复制 MC jar、起进程失败）。
+    Io,
+}
+
+impl ProcessorErrorKind {
+    /// 稳定字符串 id（进 `--json` 的 `error.code`）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Plan => "processor_plan",
+            Self::Java => "processor_java_missing",
+            Self::Library => "processor_library_missing",
+            Self::Failed => "processor_failed",
+            Self::Output => "processor_output_missing",
+            Self::Io => "processor_io",
+        }
+    }
+}
+
+/// processor 执行错误：大类 + 人读说明 + 可选提示 + 可选 stderr 尾部（已脱敏）。
+#[derive(Debug, Clone)]
+pub struct ProcessorError {
+    kind: ProcessorErrorKind,
+    message: String,
+    hint: Option<String>,
+    stderr_tail: Option<String>,
+}
+
+impl ProcessorError {
+    /// 构造。
+    #[must_use]
+    pub fn new(kind: ProcessorErrorKind, message: impl Into<String>) -> Self {
+        Self {
+            kind,
+            message: message.into(),
+            hint: None,
+            stderr_tail: None,
+        }
+    }
+
+    /// 规划期失败（install profile 形状/变量问题）。
+    #[must_use]
+    pub fn plan(message: impl Into<String>) -> Self {
+        Self::new(ProcessorErrorKind::Plan, message)
+    }
+
+    /// 找不到可用的 Java。
+    #[must_use]
+    pub fn java_missing(message: impl Into<String>) -> Self {
+        Self::new(ProcessorErrorKind::Java, message)
+    }
+
+    /// processor 依赖不在盘上。
+    #[must_use]
+    pub fn library_missing(message: impl Into<String>) -> Self {
+        Self::new(ProcessorErrorKind::Library, message)
+    }
+
+    /// processor 产物没落盘。
+    #[must_use]
+    pub fn output_missing(message: impl Into<String>) -> Self {
+        Self::new(ProcessorErrorKind::Output, message)
+    }
+
+    /// 本地 IO 失败。
+    #[must_use]
+    pub fn io(message: impl Into<String>) -> Self {
+        Self::new(ProcessorErrorKind::Io, message)
+    }
+
+    /// 外调 java 非零退出：消息 = 说明 + 脱敏后的 stderr 尾部。
+    #[must_use]
+    pub fn failed(label: &str, exit: &str, stderr_tail: &str) -> Self {
+        let mut message = format!("processor {label} 执行失败（退出码 {exit}）");
+        if !stderr_tail.trim().is_empty() {
+            message.push_str("；stderr 尾部：\n");
+            message.push_str(stderr_tail.trim_end());
+        }
+        let mut error = Self::new(ProcessorErrorKind::Failed, message);
+        error.stderr_tail = Some(stderr_tail.trim_end().to_string());
+        error
+    }
+
+    /// 补一句提示。
+    #[must_use]
+    pub fn with_hint(mut self, hint: impl Into<String>) -> Self {
+        self.hint = Some(hint.into());
+        self
+    }
+
+    /// 大类。
+    #[must_use]
+    pub const fn kind(&self) -> ProcessorErrorKind {
+        self.kind
+    }
+
+    /// 人读说明。
+    #[must_use]
+    pub fn message(&self) -> &str {
+        &self.message
+    }
+
+    /// 下一步提示。
+    #[must_use]
+    pub fn hint(&self) -> Option<&str> {
+        self.hint.as_deref()
+    }
+
+    /// 脱敏后的 stderr 尾部（只有 `processor_failed` 会有）。
+    #[must_use]
+    pub fn stderr_tail(&self) -> Option<&str> {
+        self.stderr_tail.as_deref()
+    }
+}
+
+impl fmt::Display for ProcessorError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str(&self.message)
+    }
+}
+
+impl std::error::Error for ProcessorError {}
+
+#[cfg(test)]
+mod tests {
+    use super::{ProcessorError, ProcessorErrorKind};
+
+    #[test]
+    fn stable_codes_are_distinct_and_prefixed() {
+        let kinds = [
+            ProcessorErrorKind::Plan,
+            ProcessorErrorKind::Java,
+            ProcessorErrorKind::Library,
+            ProcessorErrorKind::Failed,
+            ProcessorErrorKind::Output,
+            ProcessorErrorKind::Io,
+        ];
+        for kind in kinds {
+            assert!(kind.as_str().starts_with("processor_"), "{}", kind.as_str());
+        }
+        assert_eq!(ProcessorErrorKind::Failed.as_str(), "processor_failed");
+    }
+
+    #[test]
+    fn failed_carries_the_stderr_tail_in_message_and_accessor() {
+        let error = ProcessorError::failed("g:a:1", "1", "boom\nCaused by: x");
+        assert_eq!(error.kind(), ProcessorErrorKind::Failed);
+        assert!(error.message().contains("退出码 1"), "{}", error.message());
+        assert!(error.message().contains("Caused by: x"));
+        assert_eq!(error.stderr_tail(), Some("boom\nCaused by: x"));
+    }
+
+    #[test]
+    fn empty_stderr_keeps_the_message_clean() {
+        let error = ProcessorError::failed("g:a:1", "255", "");
+        assert!(!error.message().contains("stderr 尾部"));
+        assert_eq!(error.stderr_tail(), Some(""));
+    }
+}
diff --git a/crates/core/src/addon/loader/processors/exec.rs b/crates/core/src/addon/loader/processors/exec.rs
new file mode 100644
index 0000000..0c2029c
--- /dev/null
+++ b/crates/core/src/addon/loader/processors/exec.rs
@@ -0,0 +1,363 @@
+//! 逐个外调 java 执行 processor：`java -cp <依赖…>:<jar> <主类> <参数…>`。
+//!
+//! 依据 `DevDocs/analyse/05-modloader-modpack.md` §1.2（Forge 新式 installer 的 processors
+//! 流水线）与 HMCL `ForgeNewInstallTask.ProcessorTask` 的实现，四条硬规矩：
+//!
+//! 1. **串行**：后面的 processor 吃前面的产物（拆包 → 映射 → 打补丁），并行必炸；
+//! 2. **幂等**：每步先按 `outputs` 的 SHA-1 判定，全部命中就整步跳过（重跑 install 零成本）；
+//! 3. **主类来自 jar 的 MANIFEST**：官方 install profile 不写主类（少数 fork 给 `mainClass`）；
+//! 4. **失败要能定位**：非零退出带脱敏后的 stderr 尾部（路径/用户名不能泄漏到日志外）。
+//!
+//! # 关于产物 SHA-1 与 zlib 变体（HMCL 踩过的坑）
+//!
+//! processor 动态生成的 jar 是用**本机 JDK 的 zlib** 压缩的。zlib-ng 之类非标准实现会把
+//! 同样的内容压出不同字节 → SHA-1 与 profile 里的期望值不符。HMCL 的处置是「哈希不符时
+//! 退化成 ZIP 结构校验」。我们的处置更保守：**存在性强制、摘要不符只告警**，
+//! 既不误杀真实装，也不假装校验通过。
+
+use std::path::Path;
+use std::process::Command;
+use std::sync::Arc;
+use std::time::Instant;
+
+use serde_json::{json, Value};
+
+use super::error::ProcessorError;
+use super::jar::read_main_class;
+use super::plan::{ProcessorPlan, ProcessorStep};
+use super::prepare::prepare;
+use super::text::{host_redactor, non_empty, tail};
+use crate::download::verify;
+use crate::download::HashAlgo;
+use crate::game::java::{self, JavaRequirement, JavaRuntime};
+use crate::launch::redact::Redactor;
+
+/// 一步的结局。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum StepStatus {
+    /// 产物已就绪（SHA-1 命中），整步跳过。
+    Skipped,
+    /// 真的起了一次 java。
+    Executed,
+}
+
+impl StepStatus {
+    /// 稳定字符串 id（`--json` 用）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Skipped => "skipped",
+            Self::Executed => "executed",
+        }
+    }
+}
+
+/// 一步的执行结果。
+#[derive(Debug, Clone)]
+pub struct StepOutcome {
+    /// 序号（从 1 起）。
+    pub index: usize,
+    /// jar 的 maven 坐标。
+    pub label: String,
+    /// 结局。
+    pub status: StepStatus,
+    /// 产物个数。
+    pub outputs: usize,
+    /// 耗时（毫秒；跳过时为 0）。
+    pub elapsed_ms: u128,
+    /// stdout 尾巴（已脱敏，可能为空）。
+    pub stdout_tail: Option<String>,
+    /// stderr 尾巴（已脱敏，可能为空）。
+    pub stderr_tail: Option<String>,
+}
+
+impl StepOutcome {
+    /// JSON 视图。
+    #[must_use]
+    pub fn to_json(&self) -> Value {
+        json!({
+            "index": self.index,
+            "jar": self.label,
+            "status": self.status.as_str(),
+            "outputs": self.outputs,
+            "elapsed_ms": self.elapsed_ms,
+            "stderr_tail": self.stderr_tail,
+        })
+    }
+}
+
+/// 一次 processors 执行的汇总。
+#[derive(Debug, Clone)]
+pub struct ProcessorRun {
+    /// 实际用的 Java（含来源与主版本）。
+    pub java: JavaRuntime,
+    /// 逐步骤结果（顺序即执行顺序）。
+    pub steps: Vec<StepOutcome>,
+    /// 不致命的告警（摘要不符、没有 outputs 的步骤等）。
+    pub warnings: Vec<String>,
+}
+
+impl ProcessorRun {
+    /// 真正跑过的步数。
+    #[must_use]
+    pub fn executed(&self) -> usize {
+        self.steps
+            .iter()
+            .filter(|step| step.status == StepStatus::Executed)
+            .count()
+    }
+
+    /// 跳过的步数（幂等命中）。
+    #[must_use]
+    pub fn skipped(&self) -> usize {
+        self.steps
+            .iter()
+            .filter(|step| step.status == StepStatus::Skipped)
+            .count()
+    }
+
+    /// JSON 视图。
+    #[must_use]
+    pub fn to_json(&self) -> Value {
+        json!({
+            "java": {
+                "binary": self.java.binary.display().to_string(),
+                "source": self.java.origin.as_str(),
+                "major": self.java.major,
+                "version": self.java.version,
+            },
+            "executed": self.executed(),
+            "skipped": self.skipped(),
+            "steps": self.steps.iter().map(StepOutcome::to_json).collect::<Vec<_>>(),
+            "warnings": self.warnings,
+        })
+    }
+}
+
+/// 每步完成的回调（CLI 往 stderr 打实时进度用）。
+pub type StepSink = Arc<dyn Fn(&StepOutcome) + Send + Sync>;
+
+/// 按 M33 的解析链挑一个能跑 installer 的 Java：托管 > `JAVA_HOME` > `PATH` > 扫盘。
+///
+/// 与启动路径的差异只有一点：**扫盘只在前面都不满足时才做**（别为了一次安装白跑
+/// N 次 `java -version`），这里复用 [`crate::game::java::pick`] 的同一套优先序。
+#[must_use]
+pub fn select_java(managed_root: &Path, requirement: &JavaRequirement) -> Option<JavaRuntime> {
+    let mut candidates = java::discover_managed(managed_root);
+    candidates.extend(java::system_candidates());
+    if let Some(runtime) = java::pick(&candidates, requirement) {
+        if usable(runtime) {
+            return Some(runtime.clone());
+        }
+    }
+    candidates.extend(java::standard_candidates());
+    let deduped = java::discover::dedupe(candidates);
+    java::pick(&deduped, requirement).cloned().filter(usable)
+}
+
+/// 候选是否真的能用：探测到主版本，或者那个文件确实在盘上。
+fn usable(runtime: &JavaRuntime) -> bool {
+    runtime.major.is_some() || runtime.binary.is_file()
+}
+
+/// 顺序执行所有 processor。
+///
+/// 全部产物已就绪时走快路径：不复制 client jar、不解包 installer、不起任何进程。
+///
+/// # Errors
+///
+/// 临时目录/解包/复制失败（IO）、依赖缺失、`java -cp` 起不来或非零退出、
+/// 产物没落盘时返回 [`ProcessorError`]。
+pub fn run(
+    plan: &ProcessorPlan,
+    runtime: &JavaRuntime,
+    sink: Option<StepSink>,
+) -> Result<ProcessorRun, ProcessorError> {
+    let redactor = host_redactor();
+    let mut warnings = Vec::new();
+    let mut outcomes = Vec::with_capacity(plan.steps.len());
+    let satisfied: Vec<bool> = plan
+        .steps
+        .iter()
+        .map(|step| outputs_satisfied(step, &mut warnings))
+        .collect();
+    if satisfied.iter().any(|done| !done) {
+        prepare(plan)?;
+    }
+    for (step, done) in plan.steps.iter().zip(satisfied) {
+        let outcome = if done {
+            StepOutcome {
+                index: step.index,
+                label: step.label.clone(),
+                status: StepStatus::Skipped,
+                outputs: step.outputs.len(),
+                elapsed_ms: 0,
+                stdout_tail: None,
+                stderr_tail: None,
+            }
+        } else {
+            run_step(plan, runtime, step, &redactor, &mut warnings)?
+        };
+        if let Some(sink) = &sink {
+            sink(&outcome);
+        }
+        outcomes.push(outcome);
+    }
+
+    Ok(ProcessorRun {
+        java: runtime.clone(),
+        steps: outcomes,
+        warnings,
+    })
+}
+
+/// 起一次 java，跑完校验产物。
+fn run_step(
+    plan: &ProcessorPlan,
+    runtime: &JavaRuntime,
+    step: &ProcessorStep,
+    redactor: &Redactor,
+    warnings: &mut Vec<String>,
+) -> Result<StepOutcome, ProcessorError> {
+    ensure_dependencies(step)?;
+    let main_class = match &step.main_class {
+        Some(main_class) => main_class.clone(),
+        None => read_main_class(&step.jar)?,
+    };
+    let classpath = step.classpath_join()?;
+
+    let started = Instant::now();
+    let output = Command::new(&runtime.binary)
+        .arg("-cp")
+        .arg(&classpath)
+        .arg(&main_class)
+        .args(&step.args)
+        .current_dir(&plan.scratch)
+        .output()
+        .map_err(|error| {
+            ProcessorError::io(format!(
+                "起 java 失败（{}）：{error}",
+                runtime.binary.display()
+            ))
+            .with_hint(
+                "确认 `ull java list` 里的路径可用，或用 `ull java install <major>` 装一个托管 JDK",
+            )
+        })?;
+    let elapsed_ms = started.elapsed().as_millis();
+    let stdout = redactor
+        .scrub(&String::from_utf8_lossy(&output.stdout))
+        .into_owned();
+    let stderr = redactor
+        .scrub(&String::from_utf8_lossy(&output.stderr))
+        .into_owned();
+
+    if !output.status.success() {
+        let exit = output
+            .status
+            .code()
+            .map_or_else(|| "signal".to_string(), |code| code.to_string());
+        return Err(
+            ProcessorError::failed(&step.label, &exit, &tail(&stderr)).with_hint(
+                "installer 的 processor 是官方产物，失败多半是 Java 版本/磁盘权限/网络（部分步骤要联网取映射）",
+            ),
+        );
+    }
+
+    verify_outputs(step, warnings)?;
+    Ok(StepOutcome {
+        index: step.index,
+        label: step.label.clone(),
+        status: StepStatus::Executed,
+        outputs: step.outputs.len(),
+        elapsed_ms,
+        stdout_tail: non_empty(tail(&stdout)),
+        stderr_tail: non_empty(tail(&stderr)),
+    })
+}
+
+/// 依赖 jar 是否都在盘上（缺了直接报错：起了 java 也只会得到 `NoClassDefFoundError`）。
+fn ensure_dependencies(step: &ProcessorStep) -> Result<(), ProcessorError> {
+    if !step.jar.is_file() {
+        return Err(ProcessorError::library_missing(format!(
+            "processor {} 的可执行 jar 不在盘上：{}",
+            step.label,
+            step.jar.display()
+        )));
+    }
+    let missing: Vec<String> = step
+        .classpath
+        .iter()
+        .filter(|path| !path.is_file())
+        .map(|path| path.display().to_string())
+        .collect();
+    if missing.is_empty() {
+        return Ok(());
+    }
+    Err(ProcessorError::library_missing(format!(
+        "processor {} 有 {} 个依赖 jar 不在盘上：{}",
+        step.label,
+        missing.len(),
+        missing.join("；")
+    ))
+    .with_hint("重跑一次 `ull install` 会补齐依赖（下载走镜像/健康度引擎）"))
+}
+
+/// 产物存在性（硬）与摘要（软）校验。
+fn verify_outputs(step: &ProcessorStep, warnings: &mut Vec<String>) -> Result<(), ProcessorError> {
+    let missing: Vec<String> = step
+        .outputs
+        .iter()
+        .filter(|output| !output.path.is_file())
+        .map(|output| output.path.display().to_string())
+        .collect();
+    if !missing.is_empty() {
+        return Err(ProcessorError::output_missing(format!(
+            "processor {} 跑完了但产物没落盘：{}",
+            step.label,
+            missing.join("；")
+        ))
+        .with_hint("磁盘权限/杀软拦截是常见原因；也可以删掉 versions/ 下这版后重装"));
+    }
+    for output in &step.outputs {
+        let Some(expected) = &output.sha1 else {
+            continue;
+        };
+        let Ok(actual) = verify::digest_file(&output.path, HashAlgo::Sha1) else {
+            continue;
+        };
+        if !verify::matches(expected, &actual) {
+            warnings.push(format!(
+                "processor {} 的产物摘要与 profile 不符（期望 {expected} 实际 {actual}）：非标准 zlib 实现会压出不同字节，按可用处理",
+                step.label
+            ));
+        }
+    }
+    Ok(())
+}
+
+/// 产物是否都已就绪（幂等判据：存在 + 摘要命中；profile 没给摘要就只认存在）。
+fn outputs_satisfied(step: &ProcessorStep, warnings: &mut Vec<String>) -> bool {
+    if step.outputs.is_empty() {
+        // 没有产物声明 → 无法判断是否跑过，只能每次都跑（HMCL 同样处理）。
+        return false;
+    }
+    for output in &step.outputs {
+        if !output.path.is_file() {
+            return false;
+        }
+        let Some(expected) = &output.sha1 else {
+            continue;
+        };
+        let Ok(actual) = verify::digest_file(&output.path, HashAlgo::Sha1) else {
+            return false;
+        };
+        if !verify::matches(expected, &actual) {
+            warnings.push(format!(
+                "{} 的摘要与 profile 不符，重新执行该 processor",
+                output.path.display()
+            ));
+            return false;
+        }
+    }
+    true
+}
diff --git a/crates/core/src/addon/loader/processors/jar.rs b/crates/core/src/addon/loader/processors/jar.rs
new file mode 100644
index 0000000..93b265a
--- /dev/null
+++ b/crates/core/src/addon/loader/processors/jar.rs
@@ -0,0 +1,83 @@
+//! 从 processor jar 的 `MANIFEST.MF` 里取 `Main-Class`。
+//!
+//! 官方 install profile **不写主类**（`processors[].jar` 只给坐标），主类在 jar 的清单里；
+//! 少数 fork 会额外给 `mainClass`（那条路走 [`super::plan::ProcessorStep::main_class`]，
+//! 不到这里）。清单按 RFC 822 折行：续行以**单个空格**开头。
+
+use std::path::Path;
+
+use super::error::ProcessorError;
+
+/// 读 jar 的 `Main-Class`。
+///
+/// # Errors
+///
+/// jar 打不开/不是 zip（IO/规划错误）、没有 `META-INF/MANIFEST.MF` 或清单里没有
+/// `Main-Class`（规划错误）。
+pub(super) fn read_main_class(jar: &Path) -> Result<String, ProcessorError> {
+    use std::io::Read;
+
+    let file = std::fs::File::open(jar).map_err(|error| {
+        ProcessorError::io(format!(
+            "打开 processor jar 失败（{}）：{error}",
+            jar.display()
+        ))
+    })?;
+    let mut archive = zip::ZipArchive::new(file).map_err(|error| {
+        ProcessorError::plan(format!("{} 不是合法 jar：{error}", jar.display()))
+    })?;
+    let mut manifest = String::new();
+    {
+        let mut entry = archive.by_name("META-INF/MANIFEST.MF").map_err(|error| {
+            ProcessorError::plan(format!(
+                "{} 里没有 META-INF/MANIFEST.MF（拿不到主类）：{error}",
+                jar.display()
+            ))
+        })?;
+        entry.read_to_string(&mut manifest).map_err(|error| {
+            ProcessorError::io(format!("读 {} 的 MANIFEST 失败：{error}", jar.display()))
+        })?;
+    }
+    parse_main_class(&manifest).ok_or_else(|| {
+        ProcessorError::plan(format!(
+            "{} 的 MANIFEST 里没有 Main-Class（install profile 也没给 mainClass）",
+            jar.display()
+        ))
+    })
+}
+
+/// 从 MANIFEST 文本里取 `Main-Class`（续行以单个空格开头）。
+fn parse_main_class(manifest: &str) -> Option<String> {
+    let mut lines = manifest.lines().peekable();
+    while let Some(line) = lines.next() {
+        let Some(rest) = line.strip_prefix("Main-Class:") else {
+            continue;
+        };
+        let mut value = rest.trim().to_string();
+        while let Some(next) = lines.peek() {
+            let Some(continuation) = next.strip_prefix(' ') else {
+                break;
+            };
+            value.push_str(continuation.trim());
+            lines.next();
+        }
+        return (!value.is_empty()).then_some(value);
+    }
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::parse_main_class;
+
+    #[test]
+    fn parses_main_class_with_continuation_lines() {
+        let manifest = "Manifest-Version: 1.0\r\nMain-Class: com.example.\r\n Tool\r\n\r\n";
+        assert_eq!(
+            parse_main_class(manifest).as_deref(),
+            Some("com.example.Tool")
+        );
+        assert!(parse_main_class("Manifest-Version: 1.0\n").is_none());
+        assert!(parse_main_class("Main-Class:   \n").is_none());
+    }
+}
diff --git a/crates/core/src/addon/loader/processors/mod.rs b/crates/core/src/addon/loader/processors/mod.rs
new file mode 100644
index 0000000..aa68102
--- /dev/null
+++ b/crates/core/src/addon/loader/processors/mod.rs
@@ -0,0 +1,56 @@
+//! Installer Processors 执行器（M35）：把 install profile 的 `processors[]` 跑起来。
+//!
+//! 设计输入：`DevDocs/analyse/05-modloader-modpack.md` §1.2（Forge 新式 installer 的
+//! processor 流水线）与 HMCL `ForgeNewInstallTask` / `ProcessorTask` 的实现。
+//!
+//! # 覆盖范围
+//!
+//! | 版本段 | 有无客户端 processor | 本模块 |
+//! |--------|----------------------|--------|
+//! | Forge 1.13 ~ 1.20.x（spec 1） | 有（拆包/映射/打补丁） | ✅ 真跑 |
+//! | NeoForge 1.20.5+（26.x 只剩 1 个 `PROCESS_MINECRAFT_JAR`） | 有 | ✅ 真跑 |
+//! | Forge spec 0（1.12.2 重建版）/ Fabric / Quilt | 无 | 不需要（走 M32 的 json 路线） |
+//!
+//! # 流水线
+//!
+//! ```text
+//! plan    install profile 的 data 表 → 变量表（{MINECRAFT_JAR}/{SIDE}/[坐标]/'字面量'）
+//!         → 每步 java -cp 参数 + 产物/摘要 + processor 依赖库待下清单
+//! download 依赖库（走 M27 引擎：镜像/健康度/退避/校验）
+//! exec    串行外调 java（主类取自 jar 的 MANIFEST）→ 产物存在性（硬）+ 摘要（软）
+//! ```
+//!
+//! # 三条边界
+//!
+//! 1. **不写版本 JSON**：那是 M27 `execute` 的事，且必须等 processors 全部成功
+//!    （版本清单存在 = 这一版真的装完了，半成品不许留）；
+//! 2. **不改共享层**：原版 client jar 先复制到临时目录再交给 processor，
+//!    processor 只会改临时副本；
+//! 3. **不猜**：`data` 表里缺变量、processor 缺 `jar`、产物没落盘，一律明确报错，
+//!    不拿半截参数去试（那种失败的 stderr 更难查）。
+//!
+//! # 幂等
+//!
+//! 两级：①每步按 `outputs` 的 SHA-1 命中整步跳过（重跑零成本、不碰文件系统）；
+//! ②调用方以「版本 JSON 已落盘」为粗粒度判据整段跳过。
+
+pub mod download;
+pub mod error;
+pub mod exec;
+pub mod jar;
+pub mod plan;
+pub mod prepare;
+pub mod spec;
+pub mod text;
+pub mod vars;
+
+#[cfg(test)]
+mod tests;
+
+pub use download::download_libraries;
+pub use error::{ProcessorError, ProcessorErrorKind};
+pub use exec::{run, select_java, ProcessorRun, StepOutcome, StepSink, StepStatus};
+pub use plan::{ProcessorPlan, ProcessorPlanInput, ProcessorStep, StepOutput};
+pub use spec::{Datum, Processor};
+pub use text::{host_redactor, tail};
+pub use vars::{EmbeddedFile, Variables, VariablesInput, MINECRAFT_JAR_NAME};
diff --git a/crates/core/src/addon/loader/processors/plan.rs b/crates/core/src/addon/loader/processors/plan.rs
new file mode 100644
index 0000000..8665ad6
--- /dev/null
+++ b/crates/core/src/addon/loader/processors/plan.rs
@@ -0,0 +1,366 @@
+//! processor 执行计划：`data` 表展开 → 每步的 `java -cp …` 命令行 → 依赖库待下载清单。
+//!
+//! 纯计算（不下载、不起进程），因此 `--dry-run` 能直接把「将执行的 processor 清单 +
+//! 所需 Java + 依赖库」打出来。唯一读盘的动作是 [`crate::game::java::requirement_for_version`]
+//! 读原版版本 JSON 判 Java 要求——那是诊断信息，读不到就按静态表兜底。
+//!
+//! # 为什么依赖库与启动 classpath 要分开
+//!
+//! install profile 的 `libraries` 是 **processor 依赖**（installertools / jarsplitter /
+//! srgutils…），它们不进游戏 classpath。M32 只把数量记进告警，M35 起真正下载它们
+//! （否则 `java -cp` 一排文件都不在盘上），但仍然**绝不**并进 loader 版本 JSON。
+
+use std::path::{Path, PathBuf};
+
+use serde_json::{json, Value};
+
+use super::error::ProcessorError;
+use super::spec::Processor;
+use super::vars::{absolute, Variables, VariablesInput, MINECRAFT_JAR_NAME};
+use crate::addon::loader::forge::InstallProfile;
+use crate::addon::loader::{maven, LoaderKind};
+use crate::download::ResourceKind;
+use crate::game::arguments::Environment;
+use crate::game::install::libraries;
+use crate::game::install::{FileRole, PlanFile};
+use crate::game::java::{requirement_for_version, JavaRequirement};
+use crate::game::layout::GameLayout;
+use crate::game::library::MavenCoordinate;
+
+/// 一个 processor 的某个产物。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct StepOutput {
+    /// 产物绝对路径。
+    pub path: PathBuf,
+    /// 期望 SHA-1（profile 没给或给的不是摘要时为 `None`，只能按存在性判定）。
+    pub sha1: Option<String>,
+}
+
+/// 一个待执行的 processor（已展开参数，不再依赖 install profile）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProcessorStep {
+    /// 序号（从 1 起，顺序即执行顺序）。
+    pub index: usize,
+    /// 人读标识（jar 的 maven 坐标）。
+    pub label: String,
+    /// 可执行 jar 的磁盘路径。
+    pub jar: PathBuf,
+    /// 主类（profile 没写就留 `None`，执行期读 jar 的 MANIFEST）。
+    pub main_class: Option<String>,
+    /// `-cp` 的依赖 jar（不含 `jar` 自己）。
+    pub classpath: Vec<PathBuf>,
+    /// 已展开的参数。
+    pub args: Vec<String>,
+    /// 产物与期望摘要。
+    pub outputs: Vec<StepOutput>,
+}
+
+impl ProcessorStep {
+    /// 一步的 `-cp` 全串（依赖在前、可执行 jar 在后，与 HMCL 一致）。
+    ///
+    /// # Errors
+    ///
+    /// 路径里含分隔符时返回 IO 错误（Windows 的 `;` 不可能出现在合法路径里，
+    /// 真出现说明路径是拼错的）。
+    pub fn classpath_join(&self) -> Result<String, ProcessorError> {
+        let paths = self
+            .classpath
+            .iter()
+            .chain(std::iter::once(&self.jar))
+            .map(|path| path.as_path());
+        std::env::join_paths(paths)
+            .map(|joined| joined.to_string_lossy().into_owned())
+            .map_err(|error| ProcessorError::io(format!("classpath 拼不起来：{error}")))
+    }
+}
+
+/// [`ProcessorPlan::build`] 的输入。
+pub struct ProcessorPlanInput<'a> {
+    /// 加载器种类（只影响补库时的 maven 基址兜底）。
+    pub kind: LoaderKind,
+    /// 目标原版版本。
+    pub mc_version: &'a str,
+    /// loader 版本 id（依赖库 `hint=local` 的落点）。
+    pub version_id: &'a str,
+    /// installer 里读出来的 install profile。
+    pub profile: &'a InstallProfile,
+    /// 游戏目录布局。
+    pub layout: &'a GameLayout,
+    /// installer jar 的磁盘路径。
+    pub installer: &'a Path,
+    /// 临时目录（解包/`MINECRAFT_JAR` 副本都落这里）。
+    pub scratch: &'a Path,
+    /// 规则求值环境。
+    pub environment: &'a Environment,
+}
+
+/// processor 执行计划。
+#[derive(Debug, Clone)]
+pub struct ProcessorPlan {
+    /// loader 版本 id。
+    pub version_id: String,
+    /// installer jar 路径。
+    pub installer: PathBuf,
+    /// 临时目录。
+    pub scratch: PathBuf,
+    /// 原版 client jar（复制源）。
+    pub minecraft_jar: PathBuf,
+    /// 交给 processor 的 client jar 副本（`{MINECRAFT_JAR}`）。
+    pub minecraft_jar_copy: PathBuf,
+    /// 展开后的变量表。
+    pub variables: Variables,
+    /// 按顺序待执行的 processor。
+    pub steps: Vec<ProcessorStep>,
+    /// processor 依赖库（走 M27 引擎下载）。
+    pub libraries: Vec<PlanFile>,
+    /// 跑 installer 需要的 Java 要求。
+    pub java_requirement: JavaRequirement,
+    /// 规划期告警（不致命）。
+    pub warnings: Vec<String>,
+}
+
+impl ProcessorPlan {
+    /// 组计划。
+    ///
+    /// # Errors
+    ///
+    /// `data` 表变量缺定义、构件坐标不合法、processor 缺 `jar` 字段时返回规划错误。
+    pub fn build(input: ProcessorPlanInput<'_>) -> Result<Self, ProcessorError> {
+        let scratch = absolute(input.scratch);
+        let variables = Variables::build(VariablesInput {
+            data: &input.profile.data,
+            layout: input.layout,
+            mc_version: input.mc_version,
+            installer: input.installer,
+            scratch: &scratch,
+        })?;
+
+        let mut warnings = Vec::new();
+        let mut steps = Vec::new();
+        let mut needed: Vec<(String, PathBuf)> = Vec::new();
+        for processor in input
+            .profile
+            .processors
+            .iter()
+            .filter(|processor| processor.applies_to_client())
+        {
+            let coordinate = processor.jar_coordinate().ok_or_else(|| {
+                ProcessorError::plan("install profile 里有 processor 缺 `jar` 字段")
+            })?;
+            let jar = library_path(input.layout, coordinate)?;
+            needed.push((coordinate.to_string(), jar.clone()));
+            let mut classpath = Vec::with_capacity(processor.classpath.len());
+            for entry in &processor.classpath {
+                let path = library_path(input.layout, entry)?;
+                needed.push((entry.trim().to_string(), path.clone()));
+                classpath.push(path);
+            }
+            let mut args = Vec::with_capacity(processor.args.len());
+            for arg in &processor.args {
+                args.push(variables.expand(arg)?);
+            }
+            let outputs = step_outputs(&variables, processor, coordinate, &scratch, &mut warnings)?;
+            steps.push(ProcessorStep {
+                index: steps.len() + 1,
+                label: coordinate.to_string(),
+                jar,
+                main_class: processor.main_class().map(str::to_string),
+                classpath,
+                args,
+                outputs,
+            });
+        }
+
+        let (mut libraries, library_warnings) = libraries::plan(
+            input.layout,
+            input.version_id,
+            &input.profile.libraries,
+            input.environment,
+        );
+        warnings.extend(library_warnings);
+        let base = library_base(input.kind, input.profile);
+        for (coordinate, dest) in &needed {
+            if libraries.iter().any(|file| &file.dest == dest) {
+                continue;
+            }
+            warnings.push(format!(
+                "processor 依赖 {coordinate} 不在 install profile 的 libraries 节里，按 maven 基址补一条"
+            ));
+            let Ok(parsed) = MavenCoordinate::parse(coordinate) else {
+                continue;
+            };
+            libraries.push(PlanFile {
+                role: FileRole::Library,
+                name: coordinate.clone(),
+                url: join_url(&base, &parsed.relative_path()),
+                sha1: None,
+                size: None,
+                dest: dest.clone(),
+                resource: ResourceKind::Library,
+            });
+        }
+        // NeoForge 的 install profile 会把同一条依赖**声明多次**（实测 21.1.80：
+        // cli-utils / srgutils / jopt-simple / gson 各 2~3 次）。不下重：同一落点被下两次
+        // 会在同一个 `.part` 中间文件上互相抢（真机现场：原子落盘 os error 2）。
+        let (libraries, duplicated) = dedupe_by_dest(libraries);
+        if duplicated > 0 {
+            warnings.push(format!(
+                "install profile 重复声明了 {duplicated} 个 processor 依赖，已按落点去重"
+            ));
+        }
+
+        let java_requirement = requirement_for_version(input.layout, input.mc_version);
+        let minecraft_jar_copy = variables
+            .get("MINECRAFT_JAR")
+            .map_or_else(|| scratch.join(MINECRAFT_JAR_NAME), PathBuf::from);
+        Ok(Self {
+            version_id: input.version_id.to_string(),
+            installer: absolute(input.installer),
+            scratch,
+            minecraft_jar: input.layout.version_jar(input.mc_version),
+            minecraft_jar_copy,
+            variables,
+            steps,
+            libraries,
+            java_requirement,
+            warnings,
+        })
+    }
+
+    /// 是否一个 processor 都没有。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.steps.is_empty()
+    }
+
+    /// 汇总行数（CLI 人读输出用）。
+    #[must_use]
+    pub fn step_count(&self) -> usize {
+        self.steps.len()
+    }
+
+    /// `--dry-run` / 报告里的 processors 载荷。
+    #[must_use]
+    pub fn to_json(&self) -> Value {
+        json!({
+            "count": self.steps.len(),
+            "installer": self.installer.display().to_string(),
+            "scratch": self.scratch.display().to_string(),
+            "minecraft_jar": self.minecraft_jar.display().to_string(),
+            "libraries": self.libraries.len(),
+            "library_files": self.libraries.iter().map(|file| json!({
+                "name": file.name,
+                "url": file.url,
+                "dest": file.dest.display().to_string(),
+                "sha1": file.sha1,
+                "size": file.size,
+            })).collect::<Vec<_>>(),
+            "variables": self.variables.len(),
+            "embedded_files": self.variables.embedded().len(),
+            "java_requirement": {
+                "minimum": self.java_requirement.minimum,
+                "maximum": self.java_requirement.maximum,
+                "describe": self.java_requirement.describe(),
+                "source": self.java_requirement.source.as_str(),
+            },
+            "steps": self.steps.iter().map(step_json).collect::<Vec<_>>(),
+            "warnings": self.warnings,
+        })
+    }
+}
+
+/// 一条 processor 的 JSON 视图。
+fn step_json(step: &ProcessorStep) -> Value {
+    json!({
+        "index": step.index,
+        "jar": step.label,
+        "jar_path": step.jar.display().to_string(),
+        "main_class": step.main_class,
+        "classpath": step.classpath.len(),
+        "args": step.args,
+        "outputs": step.outputs.iter().map(|output| json!({
+            "path": output.path.display().to_string(),
+            "sha1": output.sha1,
+        })).collect::<Vec<_>>(),
+    })
+}
+
+/// 展开一步的 `outputs` 表（路径 + 期望摘要）。
+fn step_outputs(
+    variables: &Variables,
+    processor: &Processor,
+    coordinate: &str,
+    scratch: &Path,
+    warnings: &mut Vec<String>,
+) -> Result<Vec<StepOutput>, ProcessorError> {
+    let mut outputs = Vec::with_capacity(processor.outputs.len());
+    for (raw_path, raw_sha1) in &processor.outputs {
+        let expanded = variables.expand(raw_path)?;
+        let path = PathBuf::from(&expanded);
+        let path = if path.is_absolute() {
+            path
+        } else {
+            scratch.join(path)
+        };
+        let expanded_sha1 = variables.expand(raw_sha1).unwrap_or_default();
+        let sha1 = is_sha1(&expanded_sha1).then(|| expanded_sha1.to_ascii_lowercase());
+        if sha1.is_none() {
+            warnings.push(format!(
+                "processor {coordinate} 的输出 {} 没给 SHA-1，只能按存在性判定",
+                path.display()
+            ));
+        }
+        outputs.push(StepOutput { path, sha1 });
+    }
+    Ok(outputs)
+}
+
+/// 40 位十六进制（SHA-1 的样子）。
+fn is_sha1(value: &str) -> bool {
+    value.len() == 40 && value.chars().all(|ch| ch.is_ascii_hexdigit())
+}
+
+/// 坐标 → `libraries/` 下的路径。
+fn library_path(layout: &GameLayout, raw: &str) -> Result<PathBuf, ProcessorError> {
+    let coordinate = MavenCoordinate::parse(raw.trim()).map_err(|error| {
+        ProcessorError::plan(format!("processor 依赖坐标不合法：`{raw}`（{error}）"))
+    })?;
+    Ok(layout.libraries_dir().join(coordinate.relative_path()))
+}
+
+/// 补库时用的 maven 基址：install profile 自己声明的 `url` 优先，否则按加载器兜底。
+fn library_base(kind: LoaderKind, profile: &InstallProfile) -> String {
+    profile
+        .libraries
+        .iter()
+        .filter_map(|library| library.url.as_deref())
+        .map(str::trim)
+        .find(|url| !url.is_empty())
+        .map_or_else(|| maven::base(kind).to_string(), str::to_string)
+}
+
+/// `基址 + 相对路径`（保证中间恰好一个 `/`）。
+fn join_url(base: &str, relative: &Path) -> String {
+    let path = relative.to_string_lossy().replace('\\', "/");
+    if base.ends_with('/') {
+        format!("{base}{path}")
+    } else {
+        format!("{base}/{path}")
+    }
+}
+
+/// 按落点去重（保留首次出现的条目），返回（去重后的清单，丢掉几条）。
+fn dedupe_by_dest(files: Vec<PlanFile>) -> (Vec<PlanFile>, usize) {
+    let total = files.len();
+    let mut seen: Vec<PathBuf> = Vec::with_capacity(total);
+    let mut kept: Vec<PlanFile> = Vec::with_capacity(total);
+    for file in files {
+        if seen.contains(&file.dest) {
+            continue;
+        }
+        seen.push(file.dest.clone());
+        kept.push(file);
+    }
+    let dropped = total - kept.len();
+    (kept, dropped)
+}
diff --git a/crates/core/src/addon/loader/processors/prepare.rs b/crates/core/src/addon/loader/processors/prepare.rs
new file mode 100644
index 0000000..aa4a49d
--- /dev/null
+++ b/crates/core/src/addon/loader/processors/prepare.rs
@@ -0,0 +1,201 @@
+//! 临时目录准备：建目录、解包 installer 内的文件、复制原版 client jar。
+//!
+//! 三条都是「起 java 之前的脏活」，失败一律归 `processor_io`/`processor_plan`
+//! （区别于 processor 自己跑挂的 `processor_failed`）。
+
+use super::error::ProcessorError;
+use super::plan::ProcessorPlan;
+
+/// 单条目的**预分配**上限（64 MiB）：installer jar 下载后只校验「是合法 zip」，
+/// 没有校验和（`meta.rs` 的 `fetch_installer`），因此 zip header 里声明的解压尺寸
+/// 是不可信输入——损坏或镜像投毒的 installer 可以声明天文数字，让一次小文件解包直接
+/// 申请多 GB 内存。`Vec` 仍按实际读入增长，合法条目行为不变。
+const PREALLOC_MAX: u64 = 64 << 20;
+
+/// 单条目的**实际字节**上限（256 MiB）：预分配封顶挡不住「声明小、解压极大」的
+/// zip bomb，所以读入过程本身也要有硬顶。超过就明确报错（不静默截断）。
+const MAX_EMBEDDED_BYTES: u64 = 256 << 20;
+
+/// 执行前的准备：建临时目录、解包 installer 内的文件、复制原版 client jar。
+pub(super) fn prepare(plan: &ProcessorPlan) -> Result<(), ProcessorError> {
+    std::fs::create_dir_all(&plan.scratch).map_err(|error| {
+        ProcessorError::io(format!(
+            "建临时目录失败（{}）：{error}",
+            plan.scratch.display()
+        ))
+    })?;
+    extract_embedded(plan)?;
+    copy_minecraft_jar(plan)
+}
+
+/// 把 install profile 声明要解包的文件从 installer zip 里抽到临时目录。
+fn extract_embedded(plan: &ProcessorPlan) -> Result<(), ProcessorError> {
+    let embedded = plan.variables.embedded();
+    if embedded.is_empty() {
+        return Ok(());
+    }
+    use std::io::Read;
+
+    let installer = &plan.installer;
+    let file = std::fs::File::open(installer).map_err(|error| {
+        ProcessorError::io(format!(
+            "打开 installer 失败（{}）：{error}",
+            installer.display()
+        ))
+    })?;
+    let mut archive = zip::ZipArchive::new(file).map_err(|error| {
+        ProcessorError::plan(format!("{} 不是合法 zip：{error}", installer.display()))
+    })?;
+    for item in embedded {
+        let mut entry = archive.by_name(&item.entry).map_err(|error| {
+            ProcessorError::plan(format!(
+                "installer 里没有 {}（data 表声明要解包）：{error}",
+                item.entry
+            ))
+        })?;
+        let mut bytes = Vec::with_capacity(prealloc_hint(entry.size()));
+        let read = (&mut entry)
+            .take(MAX_EMBEDDED_BYTES + 1)
+            .read_to_end(&mut bytes)
+            .map_err(|error| {
+                ProcessorError::io(format!("读 installer 条目 {} 失败：{error}", item.entry))
+            })?;
+        if read as u64 > MAX_EMBEDDED_BYTES {
+            return Err(ProcessorError::plan(format!(
+                "installer 条目 {} 解压后超过 {} MiB，拒绝继续（installer 可能损坏或被投毒）",
+                item.entry,
+                MAX_EMBEDDED_BYTES >> 20
+            )));
+        }
+        crate::platform::atomic::write_atomic(&item.dest, &bytes).map_err(|error| {
+            ProcessorError::io(format!(
+                "写临时文件失败（{}）：{error}",
+                item.dest.display()
+            ))
+        })?;
+    }
+    Ok(())
+}
+
+/// 预分配提示：**不信任** header 声明的尺寸，封顶 [`PREALLOC_MAX`]。
+fn prealloc_hint(declared: u64) -> usize {
+    declared.min(PREALLOC_MAX) as usize
+}
+
+/// 复制原版 client jar 到临时目录（processor 会改写输入，不能让它碰共享层）。
+fn copy_minecraft_jar(plan: &ProcessorPlan) -> Result<(), ProcessorError> {
+    let source = &plan.minecraft_jar;
+    let target = &plan.minecraft_jar_copy;
+    let fresh = match (std::fs::metadata(source), std::fs::metadata(target)) {
+        (Ok(left), Ok(right)) => left.len() != right.len(),
+        (Ok(_), Err(_)) => true,
+        (Err(error), _) => {
+            return Err(ProcessorError::io(format!(
+                "原版 client jar 不在盘上（{}）：{error}",
+                source.display()
+            ))
+            .with_hint("先装原版：`ull install <version>`"))
+        }
+    };
+    if !fresh {
+        return Ok(());
+    }
+    if let Some(parent) = target.parent() {
+        std::fs::create_dir_all(parent).map_err(|error| {
+            ProcessorError::io(format!("建目录失败（{}）：{error}", parent.display()))
+        })?;
+    }
+    std::fs::copy(source, target).map_err(|error| {
+        ProcessorError::io(format!(
+            "复制 {} → {} 失败：{error}",
+            source.display(),
+            target.display()
+        ))
+    })?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use std::path::Path;
+
+    use super::{prealloc_hint, prepare, PREALLOC_MAX};
+    use crate::addon::loader::forge::InstallProfile;
+    use crate::addon::loader::processors::{ProcessorPlan, ProcessorPlanInput};
+    use crate::addon::loader::LoaderKind;
+    use crate::game::arguments::Environment;
+    use crate::game::layout::GameLayout;
+
+    /// 一步 processor + 一个要从 installer 里解包的 data 值。
+    const PROFILE: &str = r#"{
+      "spec": 1, "minecraft": "1.20.1", "json": "/version.json",
+      "processors": [{"jar": "net.minecraftforge:binarypatcher:1.1.1", "args": ["--apply", "{BINPATCH}"]}],
+      "libraries": [],
+      "data": {"BINPATCH": {"client": "/data/client.lzma"}}
+    }"#;
+
+    #[test]
+    fn preallocation_is_capped_so_a_forged_header_cannot_oom() {
+        // installer jar 没有校验和：header 可以声称 16 EiB 的解压尺寸。
+        assert_eq!(prealloc_hint(u64::MAX), PREALLOC_MAX as usize);
+        assert_eq!(prealloc_hint(1 << 40), PREALLOC_MAX as usize);
+        // 合法条目照旧按实际尺寸预分配（封顶不影响常见大小）。
+        assert_eq!(prealloc_hint(0), 0);
+        assert_eq!(prealloc_hint(4096), 4096);
+        assert_eq!(prealloc_hint(PREALLOC_MAX), PREALLOC_MAX as usize);
+        assert_eq!(prealloc_hint(PREALLOC_MAX - 1), PREALLOC_MAX as usize - 1);
+    }
+
+    #[test]
+    fn prepare_extracts_the_declared_entry_and_copies_the_client_jar() {
+        let root = super::super::tests::temp_root("prepare-extract");
+        let layout = GameLayout::new(&root);
+        let profile: InstallProfile = serde_json::from_str(PROFILE).expect("夹具应可解析");
+        let installer = root.join("cache/installer.jar");
+        write_zip(&installer, "data/client.lzma", b"patch-bytes");
+        let vanilla = root.join("versions/1.20.1/1.20.1.jar");
+        std::fs::create_dir_all(vanilla.parent().expect("有父目录")).expect("建目录");
+        std::fs::write(&vanilla, b"client-jar").expect("写原版 jar");
+
+        let plan = ProcessorPlan::build(ProcessorPlanInput {
+            kind: LoaderKind::Forge,
+            mc_version: "1.20.1",
+            version_id: "1.20.1-forge-47.2.0",
+            profile: &profile,
+            layout: &layout,
+            installer: &installer,
+            scratch: &root.join("scratch"),
+            environment: &Environment::host(),
+        })
+        .expect("计划应能组出来");
+        assert_eq!(plan.variables.embedded().len(), 1);
+
+        prepare(&plan).expect("准备应成功");
+        let dest = &plan.variables.embedded()[0].dest;
+        assert_eq!(std::fs::read(dest).expect("读解包产物"), b"patch-bytes");
+        // processor 拿到的是副本，共享层的原版 jar 内容不受影响。
+        assert_eq!(
+            std::fs::read(&plan.minecraft_jar_copy).expect("读 client jar 副本"),
+            b"client-jar"
+        );
+        assert_ne!(plan.minecraft_jar_copy, plan.minecraft_jar);
+        // 幂等：重跑按大小判定，不重复复制、不报错。
+        prepare(&plan).expect("重跑应成功");
+    }
+
+    /// 写一个只含一条 Stored 条目的 zip（installer 夹具）。
+    fn write_zip(path: &Path, entry: &str, bytes: &[u8]) {
+        use std::io::Write;
+
+        if let Some(parent) = path.parent() {
+            std::fs::create_dir_all(parent).expect("建目录");
+        }
+        let file = std::fs::File::create(path).expect("建 zip");
+        let mut writer = zip::ZipWriter::new(file);
+        let options = zip::write::SimpleFileOptions::default()
+            .compression_method(zip::CompressionMethod::Stored);
+        writer.start_file(entry, options).expect("写条目");
+        writer.write_all(bytes).expect("写内容");
+        writer.finish().expect("收尾 zip");
+    }
+}
diff --git a/crates/core/src/addon/loader/processors/spec.rs b/crates/core/src/addon/loader/processors/spec.rs
new file mode 100644
index 0000000..09372cc
--- /dev/null
+++ b/crates/core/src/addon/loader/processors/spec.rs
@@ -0,0 +1,121 @@
+//! install profile 的 `processors[]` 与 `data` 表：**纯解析，不动作**。
+//!
+//! 字段含义照 Forge installer spec（与 HMCL `ForgeNewInstallProfile.Processor/Datum` 一致）：
+//!
+//! ```json
+//! "processors": [{
+//!   "sides": ["client"],                                   // 缺省 = 两侧都跑
+//!   "jar": "net.minecraftforge:installertools:1.3.0",      // 可执行 jar（主类在 MANIFEST 里）
+//!   "classpath": ["net.minecraftforge:jarsplitter:1.1.4"], // 依赖 jar（jar 自己不在里面）
+//!   "args": ["--task", "MCP_DATA", "--output", "{MAPPINGS}"],
+//!   "outputs": {"{MAPPINGS}": "ab12…（期望 SHA-1）"}
+//! }],
+//! "data": {"MAPPINGS": {"client": "[de.oceanlabs.mcp:mcp_config:1.20.1@zip]", "server": "…"}}
+//! ```
+//!
+//! 三条容易看错的点：
+//!
+//! 1. `data` 的每条是**按侧**的（`client` / `server`），client 侧只取 `.client`；
+//! 2. 官方只写 `jar`，**不写主类**——主类在 jar 的 `META-INF/MANIFEST.MF`（`Main-Class`）；
+//!    少数 fork 会额外给 `mainClass`，所以这里留了口子；
+//! 3. `classpath` **不含** `jar` 自己（Forge 的约定），拼 `-cp` 时要补上。
+
+use std::collections::BTreeMap;
+
+use serde::Deserialize;
+
+/// install profile 里的一个 processor。
+#[derive(Debug, Clone, Default, Deserialize, PartialEq, Eq)]
+pub struct Processor {
+    /// 生效侧（`client` / `server`；空表示两侧都要）。
+    #[serde(default)]
+    pub sides: Vec<String>,
+    /// 可执行 jar 的 maven 坐标。
+    #[serde(default)]
+    pub jar: Option<String>,
+    /// 主类覆盖（官方 profile 不写，留给少数 fork）。
+    #[serde(default, rename = "mainClass")]
+    pub main_class: Option<String>,
+    /// 依赖 jar 的 maven 坐标（**不含** `jar` 自己）。
+    #[serde(default)]
+    pub classpath: Vec<String>,
+    /// 命令行参数（可含 `{VAR}` / `[坐标]` / `'字面量'` 三种占位）。
+    #[serde(default)]
+    pub args: Vec<String>,
+    /// 产物表：路径占位 → 期望 SHA-1（既有产物可用于幂等跳过）。
+    #[serde(default)]
+    pub outputs: BTreeMap<String, String>,
+}
+
+impl Processor {
+    /// 是否在 client 侧生效。
+    #[must_use]
+    pub fn applies_to_client(&self) -> bool {
+        self.sides.is_empty() || self.sides.iter().any(|side| side == "client")
+    }
+
+    /// `jar` 坐标（去掉首尾空白；缺失或空串返回 `None`）。
+    #[must_use]
+    pub fn jar_coordinate(&self) -> Option<&str> {
+        self.jar
+            .as_deref()
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+    }
+
+    /// 主类覆盖（缺失或空串返回 `None`）。
+    #[must_use]
+    pub fn main_class(&self) -> Option<&str> {
+        self.main_class
+            .as_deref()
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+    }
+}
+
+/// `data` 表的一条：按侧给值（client 侧只用 `.client`）。
+#[derive(Debug, Clone, Default, Deserialize, PartialEq, Eq)]
+pub struct Datum {
+    /// client 侧的值（`[坐标]` / `'字面量'` / installer 内的文件路径）。
+    #[serde(default)]
+    pub client: Option<String>,
+    /// server 侧的值（本期不跑 server 安装，只解析不动作）。
+    #[serde(default)]
+    pub server: Option<String>,
+}
+
+impl Datum {
+    /// client 侧的值（空串视为没有）。
+    #[must_use]
+    pub fn client_value(&self) -> Option<&str> {
+        self.client
+            .as_deref()
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::Processor;
+
+    #[test]
+    fn sides_empty_means_both_and_client_subset_is_recognised() {
+        let both: Processor = serde_json::from_str(r#"{"jar": "g:a:1"}"#).expect("应可解析");
+        assert!(both.applies_to_client());
+        let server: Processor =
+            serde_json::from_str(r#"{"sides": ["server"], "jar": "g:a:1"}"#).expect("应可解析");
+        assert!(!server.applies_to_client());
+        let client: Processor =
+            serde_json::from_str(r#"{"sides": ["client"], "jar": "g:a:1"}"#).expect("应可解析");
+        assert!(client.applies_to_client());
+    }
+
+    #[test]
+    fn blank_jar_and_main_class_are_treated_as_absent() {
+        let processor: Processor =
+            serde_json::from_str(r#"{"jar": " ", "mainClass": ""}"#).expect("应可解析");
+        assert!(processor.jar_coordinate().is_none());
+        assert!(processor.main_class().is_none());
+    }
+}
diff --git a/crates/core/src/addon/loader/processors/tests/exec.rs b/crates/core/src/addon/loader/processors/tests/exec.rs
new file mode 100644
index 0000000..7354b00
--- /dev/null
+++ b/crates/core/src/addon/loader/processors/tests/exec.rs
@@ -0,0 +1,185 @@
+//! 执行器：幂等跳过（不碰文件系统）、依赖缺失分流、起不来 java 的分类、脱敏器。
+
+use std::path::{Path, PathBuf};
+
+use crate::addon::loader::forge::InstallProfile;
+use crate::addon::loader::processors::{host_redactor, run};
+use crate::addon::loader::processors::{ProcessorErrorKind, ProcessorPlan, ProcessorPlanInput};
+use crate::addon::loader::LoaderKind;
+use crate::game::arguments::Environment;
+use crate::game::java::{JavaOrigin, JavaRuntime};
+use crate::game::layout::GameLayout;
+
+use super::temp_root;
+
+/// 一个最小 profile：一步 processor，产物是临时目录里的 `built.jar`（只按存在性判定）。
+const MINIMAL_PROFILE: &str = r#"{
+  "spec": 1,
+  "minecraft": "1.20.1",
+  "json": "/version.json",
+  "processors": [{
+    "jar": "net.minecraftforge:installertools:1.3.0",
+    "classpath": ["net.minecraftforge:jarsplitter:1.1.4"],
+    "args": ["--task", "SPLIT"],
+    "outputs": {"{OUT}": "'not-a-sha1'"}
+  }],
+  "libraries": [],
+  "data": {"OUT": {"client": "'built.jar'"}}
+}"#;
+
+fn minimal_profile() -> InstallProfile {
+    serde_json::from_str(MINIMAL_PROFILE).expect("夹具应可解析")
+}
+
+/// 组装计划（依赖库不落盘：执行器不负责下载，缺失由用例自己摆）。
+fn plan(root: &Path) -> ProcessorPlan {
+    let profile = minimal_profile();
+    let layout = GameLayout::new(root);
+    ProcessorPlan::build(ProcessorPlanInput {
+        kind: LoaderKind::Forge,
+        mc_version: "1.20.1",
+        version_id: "1.20.1-forge-47.2.0",
+        profile: &profile,
+        layout: &layout,
+        installer: &root.join("installer.jar"),
+        scratch: &root.join("scratch"),
+        environment: &Environment::host(),
+    })
+    .expect("计划应能组出来")
+}
+
+/// 一个「必然起不来」的 java：这些用例只验证分类与顺序，不验证 java 行为。
+fn missing_java() -> JavaRuntime {
+    JavaRuntime::unknown(
+        PathBuf::from("/nonexistent/ull-test-java"),
+        JavaOrigin::Path,
+    )
+}
+
+fn touch(path: &Path) {
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent).expect("建目录");
+    }
+    std::fs::write(path, b"stub").expect("写夹具文件");
+}
+
+/// 写一个最小 jar（可选带 `Main-Class`），给"主类从 MANIFEST 读"的用例用。
+fn write_jar(path: &Path, main_class: Option<&str>) {
+    use std::io::Write;
+
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent).expect("建目录");
+    }
+    let file = std::fs::File::create(path).expect("建 jar");
+    let mut writer = zip::ZipWriter::new(file);
+    let options =
+        zip::write::SimpleFileOptions::default().compression_method(zip::CompressionMethod::Stored);
+    if let Some(main_class) = main_class {
+        writer
+            .start_file("META-INF/MANIFEST.MF", options)
+            .expect("写 manifest 条目");
+        write!(
+            writer,
+            "Manifest-Version: 1.0\r\nMain-Class: {main_class}\r\n\r\n"
+        )
+        .expect("写 manifest");
+    }
+    writer.finish().expect("收尾 jar");
+}
+
+#[test]
+fn ready_outputs_skip_the_whole_step_without_touching_the_disk() {
+    let root = temp_root("exec-idempotent");
+    let plan = plan(&root);
+    // 产物已就绪：原版 client jar 压根不存在也无所谓——幂等快路径不该去复制它。
+    touch(&plan.steps[0].outputs[0].path);
+
+    let run = run(&plan, &missing_java(), None).expect("产物齐备时不该跑任何进程");
+    assert_eq!(run.executed(), 0);
+    assert_eq!(run.skipped(), 1);
+    assert_eq!(run.steps[0].status.as_str(), "skipped");
+    assert_eq!(run.to_json()["steps"][0]["status"], "skipped");
+    // prepare 不该跑：原版 jar 压根不存在、client jar 副本没被复制。
+    assert!(!plan.minecraft_jar_copy.exists());
+}
+
+#[test]
+fn missing_minecraft_jar_is_reported_before_any_java_runs() {
+    let root = temp_root("exec-no-vanilla");
+    let plan = plan(&root);
+    let error = run(&plan, &missing_java(), None).expect_err("缺原版 jar 必须报错");
+    assert_eq!(error.kind(), ProcessorErrorKind::Io);
+    assert!(
+        error.message().contains("原版 client jar"),
+        "{}",
+        error.message()
+    );
+}
+
+#[test]
+fn missing_processor_jar_is_a_library_error_naming_the_file() {
+    let root = temp_root("exec-no-lib");
+    let plan = plan(&root);
+    touch(&plan.minecraft_jar);
+
+    let error = run(&plan, &missing_java(), None).expect_err("缺依赖必须报错");
+    assert_eq!(error.kind(), ProcessorErrorKind::Library);
+    assert!(
+        error.message().contains("installertools-1.3.0.jar"),
+        "{}",
+        error.message()
+    );
+}
+
+#[test]
+fn a_java_that_cannot_start_is_an_io_error_with_a_hint() {
+    let root = temp_root("exec-no-java");
+    let plan = plan(&root);
+    touch(&plan.minecraft_jar);
+    // 可执行 jar 得是真的 zip + MANIFEST：主类只从那儿来（profile 没写 mainClass）。
+    write_jar(
+        &plan.steps[0].jar,
+        Some("net.minecraftforge.installertools.Main"),
+    );
+    touch(&plan.steps[0].classpath[0]);
+
+    let error = run(&plan, &missing_java(), None).expect_err("java 起不来必须报错");
+    assert_eq!(error.kind(), ProcessorErrorKind::Io);
+    assert!(
+        error.message().contains("起 java 失败"),
+        "{}",
+        error.message()
+    );
+    assert!(error.hint().is_some());
+    // 走到这一步说明临时目录、MC jar 副本都准备好了（顺序：prepare → 起进程）。
+    assert!(plan.minecraft_jar_copy.is_file());
+}
+
+#[test]
+fn a_jar_without_a_main_class_is_a_plan_error() {
+    let root = temp_root("exec-no-main");
+    let plan = plan(&root);
+    touch(&plan.minecraft_jar);
+    write_jar(&plan.steps[0].jar, None);
+    touch(&plan.steps[0].classpath[0]);
+
+    let error = run(&plan, &missing_java(), None).expect_err("拿不到主类必须报错");
+    assert_eq!(error.kind(), ProcessorErrorKind::Plan);
+    assert!(error.message().contains("主类"), "{}", error.message());
+}
+
+#[test]
+fn host_redactor_masks_the_user_home_directory() {
+    let redactor = host_redactor();
+    let home = std::env::var_os("USERPROFILE").or_else(|| std::env::var_os("HOME"));
+    let Some(home) = home else {
+        return; // 极简环境（无 HOME/USERPROFILE）时跳过
+    };
+    let text = format!("{}/game/libraries/x.jar", home.to_string_lossy());
+    let scrubbed = redactor.scrub(&text);
+    assert!(scrubbed.contains("<home>"), "{scrubbed}");
+    assert!(
+        !scrubbed.contains(&home.to_string_lossy().to_string()),
+        "{scrubbed}"
+    );
+}
diff --git a/crates/core/src/addon/loader/processors/tests/mod.rs b/crates/core/src/addon/loader/processors/tests/mod.rs
new file mode 100644
index 0000000..6e706f4
--- /dev/null
+++ b/crates/core/src/addon/loader/processors/tests/mod.rs
@@ -0,0 +1,71 @@
+//! `addon::loader::processors` 的单元测试：占位替换 / 计划形状 / 执行与失败分流 / 幂等跳过。
+//!
+//! 刻意**全部离线**：installer 用夹具 JSON 描述，依赖库的"在不在盘上"由测试自己摆，
+//! 真正外调 java 的用例只走「起不来」这一条确定性分支（假 java 路径不存在），
+//! 真机执行由验收（Forge 1.20.1 / NeoForge 21.1.80）覆盖。
+
+mod exec;
+mod plan;
+mod vars;
+
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use crate::addon::loader::forge::InstallProfile;
+
+/// 实测 Forge 1.20.1-47.2.0 的形状（裁剪到 3 个 processor：2 个 client 侧 + 1 个仅 server）。
+pub(crate) const FORGE_PROFILE: &str = r#"{
+  "spec": 1,
+  "profile": "forge",
+  "version": "1.20.1-forge-47.2.0",
+  "minecraft": "1.20.1",
+  "json": "/version.json",
+  "processors": [
+    {
+      "sides": ["client"],
+      "jar": "net.minecraftforge:installertools:1.3.0",
+      "classpath": ["net.minecraftforge:jarsplitter:1.1.4"],
+      "args": ["--task", "MCP_DATA", "--input", "{MAPPINGS}", "--output", "{MC_SLIM}", "--side", "{SIDE}"],
+      "outputs": {"{MC_SLIM}": "aa11bb22cc33dd44ee55ff660011223344556677"}
+    },
+    {
+      "sides": ["server"],
+      "jar": "net.minecraftforge:installertools:1.3.0",
+      "classpath": [],
+      "args": ["--task", "SERVER"],
+      "outputs": {}
+    },
+    {
+      "jar": "net.minecraftforge:jarsplitter:1.1.4",
+      "classpath": ["net.minecraftforge:installertools:1.3.0"],
+      "args": ["--input", "{MINECRAFT_JAR}", "--output", "{MC_EXTRA}", "--singleThreaded"],
+      "outputs": {"{MC_EXTRA}": "'not-a-sha1'"}
+    }
+  ],
+  "libraries": [
+    {"name": "net.minecraftforge:installertools:1.3.0", "url": "https://maven.minecraftforge.net/"},
+    {"name": "net.minecraftforge:jarsplitter:1.1.4", "url": "https://maven.minecraftforge.net/"}
+  ],
+  "data": {
+    "MAPPINGS": {"client": "[de.oceanlabs.mcp:mcp_config:1.20.1-20230612.114412@zip]", "server": "[de.oceanlabs.mcp:mcp_config:1.20.1-20230612.114412@zip]"},
+    "MC_SLIM": {"client": "[net.minecraft:client:1.20.1-20230612.114412:slim]", "server": "[net.minecraft:server:1.20.1-20230612.114412:slim]"},
+    "MC_EXTRA": {"client": "[net.minecraft:client:1.20.1-20230612.114412:extra]", "server": "[net.minecraft:server:1.20.1-20230612.114412:extra]"},
+    "BINPATCH": {"client": "/data/client.lzma", "server": "/data/server.lzma"},
+    "SERVER_ONLY": {"server": "'server'"}
+  }
+}"#;
+
+/// 夹具 profile。
+pub(crate) fn profile() -> InstallProfile {
+    serde_json::from_str(FORGE_PROFILE).expect("夹具 install profile 应可解析")
+}
+
+/// 一次性临时目录（用例结束不清理，落在系统 temp 下）。
+pub(crate) fn temp_root(tag: &str) -> PathBuf {
+    static COUNTER: AtomicU64 = AtomicU64::new(0);
+    let unique = COUNTER.fetch_add(1, Ordering::Relaxed);
+    std::env::temp_dir().join(format!(
+        "ull-processors-{}-{tag}-{unique}",
+        std::process::id()
+    ))
+}
diff --git a/crates/core/src/addon/loader/processors/tests/plan.rs b/crates/core/src/addon/loader/processors/tests/plan.rs
new file mode 100644
index 0000000..c5bce32
--- /dev/null
+++ b/crates/core/src/addon/loader/processors/tests/plan.rs
@@ -0,0 +1,224 @@
+//! 执行计划：client 侧过滤、参数展开、产物/摘要、依赖库补齐、Java 要求。
+
+use crate::addon::loader::forge::InstallProfile;
+use crate::addon::loader::processors::{ProcessorErrorKind, ProcessorPlan, ProcessorPlanInput};
+use crate::addon::loader::LoaderKind;
+use crate::game::arguments::Environment;
+use crate::game::layout::GameLayout;
+
+use super::{profile, temp_root};
+
+fn plan_for(root: &std::path::Path, profile: &InstallProfile) -> ProcessorPlan {
+    let layout = GameLayout::new(root);
+    ProcessorPlan::build(ProcessorPlanInput {
+        kind: LoaderKind::Forge,
+        mc_version: "1.20.1",
+        version_id: "1.20.1-forge-47.2.0",
+        profile,
+        layout: &layout,
+        installer: &root.join("cache/forge-installer.jar"),
+        scratch: &root.join("cache/processors"),
+        environment: &Environment::host(),
+    })
+    .expect("计划应能组出来")
+}
+
+#[test]
+fn only_client_side_processors_become_steps_in_declared_order() {
+    let root = temp_root("plan-order");
+    let plan = plan_for(&root, &profile());
+
+    assert_eq!(plan.step_count(), 2, "server-only 的 processor 必须被过滤");
+    assert_eq!(plan.steps[0].index, 1);
+    assert_eq!(
+        plan.steps[0].label,
+        "net.minecraftforge:installertools:1.3.0"
+    );
+    assert_eq!(plan.steps[1].index, 2);
+    assert_eq!(plan.steps[1].label, "net.minecraftforge:jarsplitter:1.1.4");
+    assert_eq!(plan.steps[1].classpath.len(), 1);
+    assert!(!plan.is_empty());
+}
+
+#[test]
+fn args_are_expanded_with_paths_and_the_client_side() {
+    let root = temp_root("plan-args");
+    let plan = plan_for(&root, &profile());
+    let args = &plan.steps[0].args;
+
+    assert_eq!(args[0], "--task");
+    assert_eq!(args[1], "MCP_DATA");
+    assert!(
+        args[3].ends_with("mcp_config-1.20.1-20230612.114412.zip"),
+        "输入构件应展开成 libraries 路径：{}",
+        args[3]
+    );
+    assert!(
+        args[5].ends_with("client-1.20.1-20230612.114412-slim.jar"),
+        "产物路径应按 data 表展开：{}",
+        args[5]
+    );
+    assert_eq!(args[7], "client");
+    // 第二步用的是临时目录里的 client jar 副本，不是共享层的原版 jar。
+    assert_eq!(
+        plan.steps[1].args[1],
+        plan.minecraft_jar_copy.to_string_lossy()
+    );
+    assert!(plan
+        .minecraft_jar_copy
+        .to_string_lossy()
+        .ends_with("minecraft.jar"));
+    assert!(!plan.minecraft_jar_copy.starts_with(root.join("versions")));
+}
+
+#[test]
+fn outputs_carry_paths_and_only_real_sha1s() {
+    let root = temp_root("plan-outputs");
+    let plan = plan_for(&root, &profile());
+
+    let first = &plan.steps[0].outputs;
+    assert_eq!(first.len(), 1);
+    assert_eq!(
+        first[0].sha1.as_deref(),
+        Some("aa11bb22cc33dd44ee55ff660011223344556677")
+    );
+    assert!(first[0].path.to_string_lossy().ends_with("-slim.jar"));
+    // 非 SHA-1 的 values 只算"存在性校验"，并留一条告警。
+    assert!(plan.steps[1].outputs[0].sha1.is_none());
+    assert!(
+        plan.warnings
+            .iter()
+            .any(|warning| warning.contains("没给 SHA-1")),
+        "{:?}",
+        plan.warnings
+    );
+}
+
+#[test]
+fn processor_dependencies_are_planned_once_even_when_libraries_omit_them() {
+    let root = temp_root("plan-libs");
+    let lean = serde_json::from_str(
+        r#"{"spec": 1, "minecraft": "1.20.1", "json": "/version.json",
+            "processors": [{"jar": "net.minecraftforge:installertools:1.3.0",
+                            "classpath": ["net.minecraftforge:jarsplitter:1.1.4"],
+                            "args": [], "outputs": {}}],
+            "libraries": [],
+            "data": {}}"#,
+    )
+    .expect("夹具应可解析");
+    let layout = GameLayout::new(&root);
+    let plan = ProcessorPlan::build(ProcessorPlanInput {
+        kind: LoaderKind::NeoForge,
+        mc_version: "1.20.1",
+        version_id: "1.20.1-neoforge-21.1.80",
+        profile: &lean,
+        layout: &layout,
+        installer: &root.join("installer.jar"),
+        scratch: &root.join("tmp"),
+        environment: &Environment::host(),
+    })
+    .expect("计划应能组出来");
+
+    assert_eq!(plan.libraries.len(), 2, "jar 与 classpath 各补一条");
+    for file in &plan.libraries {
+        assert!(
+            file.url.contains("neoforged") || file.url.contains("minecraftforge"),
+            "补库应落在加载器的 maven 上：{}",
+            file.url
+        );
+        assert!(file.dest.starts_with(root.join("libraries")));
+    }
+    assert!(plan
+        .warnings
+        .iter()
+        .any(|warning| warning.contains("不在 install profile 的 libraries 节里")));
+}
+
+#[test]
+fn java_requirement_follows_the_target_minecraft_version() {
+    let root = temp_root("plan-java");
+    let plan = plan_for(&root, &profile());
+    assert_eq!(plan.java_requirement.minimum, 17);
+    assert_eq!(plan.java_requirement.maximum, None);
+    assert_eq!(plan.java_requirement.describe(), "Java 17+");
+}
+
+#[test]
+fn json_view_lists_every_step_for_dry_run() {
+    let root = temp_root("plan-json");
+    let plan = plan_for(&root, &profile());
+    let json = plan.to_json();
+
+    assert_eq!(json["count"], 2);
+    assert_eq!(json["java_requirement"]["describe"], "Java 17+");
+    assert_eq!(
+        json["steps"][0]["jar"],
+        "net.minecraftforge:installertools:1.3.0"
+    );
+    assert_eq!(json["steps"][0]["classpath"], 1);
+    assert_eq!(
+        json["steps"][1]["outputs"][0]["sha1"],
+        serde_json::Value::Null
+    );
+}
+
+#[test]
+fn duplicated_library_declarations_are_deduped_by_destination() {
+    // NeoForge 21.1.80 实测：install profile 把 cli-utils / srgutils 等声明了 2~3 次。
+    // 同一落点下两次会在同一个 `.part` 中间文件上互相抢（真机 os error 2），必须去重。
+    let root = temp_root("plan-dedup");
+    let duplicated: InstallProfile = serde_json::from_str(
+        r#"{"spec": 1, "minecraft": "1.20.1", "json": "/version.json",
+            "processors": [{"jar": "net.neoforged.installertools:cli-utils:2.1.2@jar"}],
+            "libraries": [
+              {"name": "net.neoforged.installertools:cli-utils:2.1.2@jar", "url": "https://maven.neoforged.net/releases/"},
+              {"name": "net.neoforged.installertools:cli-utils:2.1.2@jar", "url": "https://maven.neoforged.net/releases/"},
+              {"name": "net.neoforged.installertools:cli-utils:2.1.2@jar", "url": "https://maven.neoforged.net/releases/"}
+            ],
+            "data": {}}"#,
+    )
+    .expect("夹具应可解析");
+    let layout = GameLayout::new(&root);
+    let plan = ProcessorPlan::build(ProcessorPlanInput {
+        kind: LoaderKind::NeoForge,
+        mc_version: "1.20.1",
+        version_id: "1.20.1-neoforge-21.1.80",
+        profile: &duplicated,
+        layout: &layout,
+        installer: &root.join("installer.jar"),
+        scratch: &root.join("tmp"),
+        environment: &Environment::host(),
+    })
+    .expect("计划应能组出来");
+
+    assert_eq!(plan.libraries.len(), 1, "同一落点只应留一条");
+    assert!(
+        plan.warnings.iter().any(|warning| warning.contains("去重")),
+        "{:?}",
+        plan.warnings
+    );
+}
+
+#[test]
+fn processor_without_jar_is_a_plan_error() {
+    let root = temp_root("plan-nojar");
+    let broken: InstallProfile = serde_json::from_str(
+        r#"{"spec": 1, "minecraft": "1.20.1", "json": "/version.json",
+            "processors": [{"args": ["--task", "X"]}], "libraries": [], "data": {}}"#,
+    )
+    .expect("夹具应可解析");
+    let layout = GameLayout::new(&root);
+    let error = ProcessorPlan::build(ProcessorPlanInput {
+        kind: LoaderKind::Forge,
+        mc_version: "1.20.1",
+        version_id: "1.20.1-forge-47.2.0",
+        profile: &broken,
+        layout: &layout,
+        installer: &root.join("installer.jar"),
+        scratch: &root.join("tmp"),
+        environment: &Environment::host(),
+    })
+    .expect_err("缺 jar 必须报错");
+    assert_eq!(error.kind(), ProcessorErrorKind::Plan);
+    assert!(error.message().contains("jar"), "{}", error.message());
+}
diff --git a/crates/core/src/addon/loader/processors/tests/vars.rs b/crates/core/src/addon/loader/processors/tests/vars.rs
new file mode 100644
index 0000000..8c33dc9
--- /dev/null
+++ b/crates/core/src/addon/loader/processors/tests/vars.rs
@@ -0,0 +1,181 @@
+//! 变量表：三种字面量、标准变量、token 替换的边界。
+
+use std::collections::BTreeMap;
+use std::path::Path;
+
+use crate::addon::loader::processors::spec::Datum;
+use crate::addon::loader::processors::vars::{Variables, VariablesInput};
+use crate::addon::loader::processors::ProcessorErrorKind;
+use crate::game::layout::GameLayout;
+
+use super::{profile, temp_root};
+
+fn data(entries: &[(&str, &str)]) -> BTreeMap<String, Datum> {
+    entries
+        .iter()
+        .map(|(key, value)| {
+            (
+                (*key).to_string(),
+                Datum {
+                    client: Some((*value).to_string()),
+                    server: None,
+                },
+            )
+        })
+        .collect()
+}
+
+fn build<'a>(
+    layout: &'a GameLayout,
+    data: &'a BTreeMap<String, Datum>,
+    installer: &'a Path,
+    scratch: &'a Path,
+) -> Variables {
+    Variables::build(VariablesInput {
+        data,
+        layout,
+        mc_version: "1.20.1",
+        installer,
+        scratch,
+    })
+    .expect("变量表应能组装")
+}
+
+#[test]
+fn artifact_literals_resolve_into_the_libraries_directory() {
+    let root = temp_root("vars-artifact");
+    let layout = GameLayout::new(&root);
+    let installer = root.join("installer.jar");
+    let scratch = root.join("tmp");
+    let table = data(&[("MAPPINGS", "[de.oceanlabs.mcp:mcp_config:1.20.1@zip]")]);
+    let variables = build(&layout, &table, &installer, &scratch);
+
+    let value = variables.get("MAPPINGS").expect("应有 MAPPINGS");
+    assert!(
+        Path::new(value).ends_with("de/oceanlabs/mcp/mcp_config/1.20.1/mcp_config-1.20.1.zip"),
+        "{value}"
+    );
+    assert!(Path::new(value).is_absolute(), "{value}");
+    assert!(
+        Path::new(value).starts_with(layout.libraries_dir()),
+        "{value}"
+    );
+
+    // 官方 profile 也把坐标直接写在 `args` 里（`--input [de.oceanlabs.mcp:…@zip]`），
+    // 整段是坐标时同样要展开成路径。
+    let arg = variables
+        .expand("[de.oceanlabs.mcp:mcp_config:1.20.1@zip]")
+        .expect("整段坐标应能展开");
+    assert_eq!(arg, value);
+}
+
+#[test]
+fn quoted_literals_lose_the_quotes() {
+    let root = temp_root("vars-literal");
+    let layout = GameLayout::new(&root);
+    let table = data(&[("SIDE_HINT", "'client'")]);
+    let variables = build(&layout, &table, &root.join("i.jar"), &root.join("tmp"));
+    assert_eq!(variables.get("SIDE_HINT"), Some("client"));
+}
+
+#[test]
+fn plain_paths_are_extracted_from_the_installer_into_scratch() {
+    let root = temp_root("vars-embedded");
+    let layout = GameLayout::new(&root);
+    let installer = root.join("installer.jar");
+    let scratch = root.join("tmp");
+    let table = data(&[("BINPATCH", "/data/client.lzma")]);
+    let variables = build(&layout, &table, &installer, &scratch);
+
+    let value = variables.get("BINPATCH").expect("应有 BINPATCH");
+    assert!(value.ends_with("data-client.lzma"), "{value}");
+    assert!(
+        value.starts_with(&scratch.to_string_lossy().to_string()),
+        "{value}"
+    );
+    assert_eq!(variables.embedded().len(), 1);
+    assert_eq!(variables.embedded()[0].entry, "data/client.lzma");
+}
+
+#[test]
+fn server_only_entries_are_ignored_for_client_installs() {
+    let root = temp_root("vars-server");
+    let layout = GameLayout::new(&root);
+    let variables = build(
+        &layout,
+        &profile().data,
+        &root.join("i.jar"),
+        &root.join("tmp"),
+    );
+    assert!(variables.get("SERVER_ONLY").is_none());
+    assert!(variables.get("MAPPINGS").is_some());
+}
+
+#[test]
+fn standard_variables_are_absolute_and_side_is_client() {
+    let root = temp_root("vars-standard");
+    let layout = GameLayout::new(&root);
+    let installer = root.join("installer.jar");
+    let scratch = root.join("tmp");
+    let variables = build(&layout, &BTreeMap::new(), &installer, &scratch);
+
+    assert_eq!(variables.get("SIDE"), Some("client"));
+    assert_eq!(variables.get("MINECRAFT_VERSION"), Some("1.20.1"));
+    for key in ["MINECRAFT_JAR", "ROOT", "INSTALLER", "LIBRARY_DIR"] {
+        let value = variables.get(key).unwrap_or_else(|| panic!("缺 {key}"));
+        assert!(
+            Path::new(value).is_absolute(),
+            "{key} 不是绝对路径：{value}"
+        );
+    }
+    assert!(variables
+        .get("MINECRAFT_JAR")
+        .unwrap_or_default()
+        .ends_with("minecraft.jar"));
+}
+
+#[test]
+fn token_replacement_handles_quotes_and_escapes() {
+    let root = temp_root("vars-expand");
+    let layout = GameLayout::new(&root);
+    let variables = build(
+        &layout,
+        &BTreeMap::new(),
+        &root.join("i.jar"),
+        &root.join("tmp"),
+    );
+
+    assert_eq!(
+        variables.expand("--side '{SIDE}'").expect("应能展开"),
+        "--side {SIDE}"
+    );
+    assert_eq!(variables.expand("a\\{b").expect("应能展开"), "a{b");
+    assert_eq!(
+        variables.expand("--side {SIDE}").expect("应能展开"),
+        "--side client"
+    );
+}
+
+#[test]
+fn missing_or_unclosed_placeholders_are_plan_errors() {
+    let root = temp_root("vars-error");
+    let layout = GameLayout::new(&root);
+    let variables = build(
+        &layout,
+        &BTreeMap::new(),
+        &root.join("i.jar"),
+        &root.join("tmp"),
+    );
+
+    let missing = variables
+        .expand("--output {NOPE}")
+        .expect_err("缺变量必须报错");
+    assert_eq!(missing.kind(), ProcessorErrorKind::Plan);
+    assert!(missing.message().contains("NOPE"), "{}", missing.message());
+
+    let unclosed = variables.expand("{SIDE").expect_err("未闭合必须报错");
+    assert_eq!(unclosed.kind(), ProcessorErrorKind::Plan);
+
+    let bad_escape = variables.expand("abc\\").expect_err("悬空转义必须报错");
+    assert_eq!(bad_escape.kind(), ProcessorErrorKind::Plan);
+}
diff --git a/crates/core/src/addon/loader/processors/text.rs b/crates/core/src/addon/loader/processors/text.rs
new file mode 100644
index 0000000..bbf387c
--- /dev/null
+++ b/crates/core/src/addon/loader/processors/text.rs
@@ -0,0 +1,71 @@
+//! 进程输出的尾部截取与脱敏。
+//!
+//! processor 的 stdout/stderr 是外部程序（而且部分步骤要联网）写的，内容不可控：
+//! 可能带绝对路径、用户名、甚至一大段堆栈。进错误消息/`--json` 前必须做两件事：
+//! **只留尾巴**（够定位、不灌满日志）与**抹掉主目录**（`C:\Users\<名>` → `<home>`）。
+
+use std::path::PathBuf;
+
+use crate::launch::redact::Redactor;
+
+/// 尾巴保留的行数（够看异常栈头）。
+const TAIL_LINES: usize = 12;
+/// 尾巴保留的字符上限。
+const TAIL_CHARS: usize = 1200;
+
+/// 宿主脱敏器：把用户主目录换成 `<home>`。
+///
+/// 复用 [`crate::launch::redact::Redactor`]（与 M15/M31 落地的同一套规则：token、
+/// `<home>`、长不透明串、带点 token/JWT）。注册 `USERPROFILE`（Windows）/`HOME`（macOS、Linux）
+/// 两个来源，因为 MSYS/CI 环境下两者可能只有一个在场。
+#[must_use]
+pub fn host_redactor() -> Redactor {
+    let mut redactor = Redactor::new();
+    for key in ["USERPROFILE", "HOME"] {
+        if let Some(value) = std::env::var_os(key) {
+            redactor = redactor.with_home(PathBuf::from(value));
+        }
+    }
+    redactor
+}
+
+/// 取文本尾部（末 [`TAIL_LINES`] 行，再截到 [`TAIL_CHARS`] 字符）。
+#[must_use]
+pub fn tail(text: &str) -> String {
+    let trimmed = text.trim_end();
+    if trimmed.is_empty() {
+        return String::new();
+    }
+    let lines: Vec<&str> = trimmed.lines().collect();
+    let start = lines.len().saturating_sub(TAIL_LINES);
+    let mut joined = lines[start..].join("\n");
+    let length = joined.chars().count();
+    if length > TAIL_CHARS {
+        joined = joined.chars().skip(length - TAIL_CHARS).collect();
+        joined.insert(0, '…');
+    }
+    joined
+}
+
+/// 空串 → `None`（JSON 里不吐空字段）。
+pub(super) fn non_empty(value: String) -> Option<String> {
+    (!value.is_empty()).then_some(value)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::tail;
+
+    #[test]
+    fn tail_keeps_the_last_lines_and_truncates_long_ones() {
+        let text: String = (1..=40).map(|index| format!("line {index}\n")).collect();
+        let tailed = tail(&text);
+        assert!(tailed.starts_with("line 29"), "{tailed}");
+        assert!(tailed.ends_with("line 40"));
+        let long = "x".repeat(5000);
+        let tailed = tail(&long);
+        assert!(tailed.starts_with('…'));
+        assert_eq!(tailed.chars().count(), 1201);
+        assert_eq!(tail("   \n"), "");
+    }
+}
diff --git a/crates/core/src/addon/loader/processors/vars.rs b/crates/core/src/addon/loader/processors/vars.rs
new file mode 100644
index 0000000..a0b7524
--- /dev/null
+++ b/crates/core/src/addon/loader/processors/vars.rs
@@ -0,0 +1,324 @@
+//! 占位替换：install profile 的 `data` 表 + 标准变量 → 一张 `{键 → 值}` 表。
+//!
+//! 这是 Forge processor 协议里最容易出错的一层，三种字面量语义（照 installer spec，
+//! 与 HMCL `ForgeNewInstallTask.parseLiteral` 同构）：
+//!
+//! | 写法 | 含义 | 例 |
+//! |------|------|----|
+//! | `[group:artifact:version(:classifier)(@ext)]` | maven 构件 → `libraries/` 下的绝对路径 | `[de.oceanlabs.mcp:mcp_config:1.20.1@zip]` |
+//! | `'literal'` | 去掉引号的常量 | `'client'` |
+//! | 其它 | **installer 里的文件路径** → 解包到临时目录后的绝对路径 | `/data/client.lzma` |
+//!
+//! 展开（`{KEY}`）的规则与 HMCL 的 `replaceTokens` 一致：`\` 转义下一个字符、
+//! `'…'` 原样输出、`{KEY}` 查表替换（**查不到就报错**，不静默留空——留空会让
+//! processor 拿着半截参数跑出更难查的错）。
+//!
+//! # 为什么 `MINECRAFT_JAR` 指向临时目录的副本
+//!
+//! HMCL 在起 processor 前把原版 client jar **复制到临时目录**再用，注释写得很直白：
+//! `External processors must not receive the shared cache path`。processor 会改写输入的
+//! jar（拆包/打补丁），直接把 `versions/<mc>/<mc>.jar` 递过去等于让外挂程序改共享层。
+
+use std::collections::BTreeMap;
+use std::path::{Path, PathBuf};
+
+use super::error::ProcessorError;
+use super::spec::Datum;
+use crate::game::layout::GameLayout;
+use crate::game::library::MavenCoordinate;
+
+/// 临时目录里那份原版 client jar 的文件名。
+pub const MINECRAFT_JAR_NAME: &str = "minecraft.jar";
+
+/// 一个需要从 installer zip 里解出来的文件。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct EmbeddedFile {
+    /// installer 内的条目路径（`data/client.lzma`）。
+    pub entry: String,
+    /// 解包落点（临时目录下的扁平文件名）。
+    pub dest: PathBuf,
+}
+
+/// 变量表的构造输入。
+pub struct VariablesInput<'a> {
+    /// install profile 的 `data` 表。
+    pub data: &'a BTreeMap<String, Datum>,
+    /// 游戏目录布局（`libraries/` 与 `versions/` 的路径规则）。
+    pub layout: &'a GameLayout,
+    /// 目标原版版本（`net.minecraft:client:<ver>` 这类坐标回落用）。
+    pub mc_version: &'a str,
+    /// installer jar 的磁盘路径（`{INSTALLER}`，也是解包来源）。
+    pub installer: &'a Path,
+    /// 临时目录（`{MINECRAFT_JAR}` 与解包文件都落这里）。
+    pub scratch: &'a Path,
+}
+
+/// 展开后的变量表。
+#[derive(Debug, Clone, Default)]
+pub struct Variables {
+    values: BTreeMap<String, String>,
+    embedded: Vec<EmbeddedFile>,
+    /// 参数里 `[坐标]` 的解析上下文（官方 profile 会在 `args` 里直接写坐标，不只写在 `data` 里）。
+    artifacts: Option<ArtifactRoots>,
+}
+
+/// `[坐标]` 的解析上下文。
+#[derive(Debug, Clone)]
+struct ArtifactRoots {
+    libraries: PathBuf,
+    vanilla_jar: PathBuf,
+}
+
+impl Variables {
+    /// 组装变量表：先展开 `data` 表，再注入标准变量。
+    ///
+    /// # Errors
+    ///
+    /// 构件坐标不合法、`data` 表里的值是空路径、变量引用缺定义时返回
+    /// [`ProcessorErrorKind::Plan`](super::error::ProcessorErrorKind::Plan) 错误。
+    pub fn build(input: VariablesInput<'_>) -> Result<Self, ProcessorError> {
+        let mut variables = Self {
+            artifacts: Some(ArtifactRoots {
+                libraries: input.layout.libraries_dir(),
+                vanilla_jar: input.layout.version_jar(input.mc_version),
+            }),
+            ..Self::default()
+        };
+        for (key, datum) in input.data {
+            let Some(raw) = datum.client_value() else {
+                continue;
+            };
+            let value = variables.resolve_literal(raw, &input)?;
+            variables.values.insert(key.clone(), value);
+        }
+        variables.inject_standard(&input);
+        Ok(variables)
+    }
+
+    /// 标准变量（installer spec 没有写死，但各家启动器都注入同一套）。
+    fn inject_standard(&mut self, input: &VariablesInput<'_>) {
+        let scratch = absolute(input.scratch);
+        let standard = [
+            ("SIDE", "client".to_string()),
+            ("MINECRAFT_VERSION", input.mc_version.to_string()),
+            (
+                "MINECRAFT_JAR",
+                absolute(&scratch.join(MINECRAFT_JAR_NAME))
+                    .to_string_lossy()
+                    .into_owned(),
+            ),
+            (
+                "ROOT",
+                absolute(input.layout.root()).to_string_lossy().into_owned(),
+            ),
+            (
+                "INSTALLER",
+                absolute(input.installer).to_string_lossy().into_owned(),
+            ),
+            (
+                "LIBRARY_DIR",
+                absolute(&input.layout.libraries_dir())
+                    .to_string_lossy()
+                    .into_owned(),
+            ),
+        ];
+        for (key, value) in standard {
+            self.values.insert(key.to_string(), value);
+        }
+    }
+
+    /// 把一个 `data` 表的值展开成实际字符串。
+    fn resolve_literal(
+        &mut self,
+        raw: &str,
+        input: &VariablesInput<'_>,
+    ) -> Result<String, ProcessorError> {
+        let trimmed = raw.trim();
+        if let Some(inner) = trim_brackets(trimmed) {
+            return self.resolve_artifact(inner);
+        }
+        if let Some(inner) = trimmed
+            .strip_prefix('\'')
+            .and_then(|rest| rest.strip_suffix('\''))
+        {
+            return Ok(inner.to_string());
+        }
+        if trimmed.starts_with('{') {
+            // data 表自己引用别的键：官方 profile 不这么写，但展开一次成本为零。
+            return self.expand(trimmed);
+        }
+        let entry = trimmed.trim_start_matches('/').to_string();
+        if entry.is_empty() {
+            return Err(ProcessorError::plan(format!(
+                "install profile 的 data 表里有空路径：`{raw}`"
+            )));
+        }
+        // 其余一律当 installer 内的文件：解到临时目录（执行期才真正解包）。
+        let dest = absolute(&absolute(input.scratch).join(embedded_name(&entry)));
+        self.embedded.push(EmbeddedFile {
+            entry,
+            dest: dest.clone(),
+        });
+        Ok(dest.to_string_lossy().into_owned())
+    }
+
+    /// `[坐标]` → `libraries/` 下的绝对路径。
+    fn resolve_artifact(&self, descriptor: &str) -> Result<String, ProcessorError> {
+        let Some(roots) = &self.artifacts else {
+            return Err(ProcessorError::plan(format!(
+                "构件坐标 `{descriptor}` 需要游戏目录上下文才能解析"
+            )));
+        };
+        artifact_path(&roots.libraries, &roots.vanilla_jar, descriptor)
+    }
+
+    /// 展开一段含占位的文本（`{KEY}` / `'字面量'` / `[坐标]` / `\` 转义）。
+    ///
+    /// `[坐标]` 只在**整段就是坐标**时生效（与 HMCL `parseLiteral` 一致）：
+    /// official profile 的 `args` 里常直接写 `--input [de.oceanlabs.mcp:…@zip]`。
+    ///
+    /// # Errors
+    ///
+    /// `{KEY}` 在表里查不到、`\` 结尾无字符可转义、`{`/`'` 未闭合、坐标不合法时返回规划错误。
+    pub fn expand(&self, pattern: &str) -> Result<String, ProcessorError> {
+        let trimmed = pattern.trim();
+        if let Some(inner) = trim_brackets(trimmed) {
+            return self.resolve_artifact(inner);
+        }
+        let mut out = String::with_capacity(pattern.len());
+        let mut chars = pattern.chars();
+        while let Some(ch) = chars.next() {
+            match ch {
+                '\\' => match chars.next() {
+                    Some(next) => out.push(next),
+                    None => {
+                        return Err(ProcessorError::plan(format!(
+                            "占位文本以 `\\` 结尾（无法转义）：`{pattern}`"
+                        )))
+                    }
+                },
+                '{' => {
+                    let key = collect_until(&mut chars, '}', pattern)?;
+                    let value = self.values.get(&key).ok_or_else(|| {
+                        ProcessorError::plan(format!(
+                            "占位 {{{key}}} 在 install profile 的 data 表里没有定义（原文 `{pattern}`）"
+                        ))
+                    })?;
+                    out.push_str(value);
+                }
+                '\'' => out.push_str(&collect_until(&mut chars, '\'', pattern)?),
+                other => out.push(other),
+            }
+        }
+        Ok(out)
+    }
+
+    /// 某个变量的值。
+    #[must_use]
+    pub fn get(&self, key: &str) -> Option<&str> {
+        self.values.get(key).map(String::as_str)
+    }
+
+    /// 需要从 installer 里解包的文件（执行期用）。
+    #[must_use]
+    pub fn embedded(&self) -> &[EmbeddedFile] {
+        &self.embedded
+    }
+
+    /// 变量条数（`--dry-run` 只报数量，不吐全部路径）。
+    #[must_use]
+    pub fn len(&self) -> usize {
+        self.values.len()
+    }
+
+    /// 是否一条变量都没有（实际不可能：标准变量恒在）。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.values.is_empty()
+    }
+}
+
+/// 读到 `closing` 为止（跳过 `\` 转义），返回中间文本。
+fn collect_until(
+    chars: &mut impl Iterator<Item = char>,
+    closing: char,
+    pattern: &str,
+) -> Result<String, ProcessorError> {
+    let mut out = String::new();
+    while let Some(ch) = chars.next() {
+        if ch == '\\' {
+            match chars.next() {
+                Some(next) => out.push(next),
+                None => {
+                    return Err(ProcessorError::plan(format!(
+                        "占位文本以 `\\` 结尾（无法转义）：`{pattern}`"
+                    )))
+                }
+            }
+        } else if ch == closing {
+            return Ok(out);
+        } else {
+            out.push(ch);
+        }
+    }
+    Err(ProcessorError::plan(format!(
+        "占位文本缺少收尾的 `{closing}`：`{pattern}`"
+    )))
+}
+
+/// 整段是 `[坐标]` 时取出坐标（不到首尾就返回 `None`）。
+fn trim_brackets(raw: &str) -> Option<&str> {
+    raw.strip_prefix('[')
+        .and_then(|rest| rest.strip_suffix(']'))
+}
+
+/// `[坐标]` → `libraries/` 下的绝对路径。
+///
+/// 少数坐标进不了 `libraries/`：`net.minecraft:client:<ver>`（无 classifier）对应的是
+/// `versions/<ver>/<ver>.jar`。官方 installer 会把 client jar 塞进本地 maven 布局，
+/// 我们不复制（磁盘上原版 jar 只有一份），因此按目标版本回落。
+fn artifact_path(
+    libraries: &Path,
+    vanilla_jar: &Path,
+    descriptor: &str,
+) -> Result<String, ProcessorError> {
+    let coordinate = MavenCoordinate::parse(descriptor).map_err(|error| {
+        ProcessorError::plan(format!(
+            "install profile 里的构件坐标不合法：`{descriptor}`（{error}）"
+        ))
+    })?;
+    let path = libraries.join(coordinate.relative_path());
+    if coordinate.group == "net.minecraft"
+        && coordinate.artifact == "client"
+        && coordinate.classifier.is_none()
+        && vanilla_jar.is_file()
+    {
+        return Ok(absolute(vanilla_jar).to_string_lossy().into_owned());
+    }
+    Ok(absolute(&path).to_string_lossy().into_owned())
+}
+
+/// installer 内的条目 → 临时目录里的扁平文件名（`data/client.lzma` → `data-client.lzma`）。
+///
+/// 压平是为了防路径穿越：`../` 与绝对路径在拼进临时目录时都会失去意义。
+fn embedded_name(entry: &str) -> String {
+    entry
+        .chars()
+        .map(|ch| {
+            if matches!(ch, '/' | '\\' | ':') {
+                '-'
+            } else {
+                ch
+            }
+        })
+        .collect()
+}
+
+/// 尽量转绝对路径（相对路径按当前工作目录；失败就原样返回）。
+#[must_use]
+pub fn absolute(path: &Path) -> PathBuf {
+    if path.is_absolute() {
+        return path.to_path_buf();
+    }
+    std::path::absolute(path).unwrap_or_else(|_| path.to_path_buf())
+}
diff --git a/crates/core/src/addon/loader/tests/fabric.rs b/crates/core/src/addon/loader/tests/fabric.rs
new file mode 100644
index 0000000..ca9a43e
--- /dev/null
+++ b/crates/core/src/addon/loader/tests/fabric.rs
@@ -0,0 +1,135 @@
+//! Fabric / Quilt：profile 归一化的形状对拍。
+
+use super::{FABRIC_PROFILE, QUILT_PROFILE};
+use crate::addon::loader::fabric::{build_release, parse_loader_list, pick_default};
+use crate::addon::loader::{LoaderErrorKind, LoaderKind, LoaderSupport};
+
+#[test]
+fn fabric_profile_becomes_inheriting_loader_version() {
+    let release = build_release(LoaderKind::Fabric, "1.20.1", "0.15.11", FABRIC_PROFILE)
+        .expect("fabric profile 应可归一化");
+
+    assert_eq!(release.version_id, "1.20.1-fabric-0.15.11");
+    let json = &release.version_json;
+    assert_eq!(json.id.as_deref(), Some("1.20.1-fabric-0.15.11"));
+    assert_eq!(json.inherits_from.as_deref(), Some("1.20.1"));
+    // ★ 关键：jar 必须钉成原版 id，否则继承解析会把 jar 兜底成 loader 自身 id。
+    assert_eq!(json.jar.as_deref(), Some("1.20.1"));
+    assert_eq!(
+        json.main_class.as_deref(),
+        Some("net.fabricmc.loader.impl.launch.knot.KnotClient")
+    );
+    // jvm 参数（`-DFabricMcEmu`）必须原样保留：老版本启动靠它。
+    let jvm = json
+        .arguments
+        .as_ref()
+        .map(|arguments| arguments.jvm.len())
+        .unwrap_or_default();
+    assert_eq!(jvm, 1, "profile 的 jvm 参数丢了");
+    assert_eq!(release.support, LoaderSupport::JsonRoute);
+    assert!(release.is_installable());
+    assert!(release.warnings.is_empty(), "{:?}", release.warnings);
+}
+
+#[test]
+fn fabric_flat_digest_is_lifted_into_artifact() {
+    let release = build_release(LoaderKind::Fabric, "1.20.1", "0.15.11", FABRIC_PROFILE)
+        .expect("fabric profile 应可归一化");
+    let libraries = release.version_json.libraries.expect("应有库");
+    let asm = libraries
+        .iter()
+        .find(|library| library.name.starts_with("org.ow2.asm:asm:"))
+        .expect("应有 asm");
+    let artifact = asm
+        .downloads
+        .as_ref()
+        .and_then(|downloads| downloads.artifact.as_ref())
+        .expect("扁平 sha1/size 应提升成 downloads.artifact");
+    assert_eq!(
+        artifact.sha1.as_deref(),
+        Some("aa205cf0a06dbd8e04ece91c0b37c3f5d567546a")
+    );
+    assert_eq!(artifact.size, Some(123_598));
+    assert_eq!(
+        artifact.url.as_deref(),
+        Some("https://maven.fabricmc.net/org/ow2/asm/asm/9.6/asm-9.6.jar")
+    );
+}
+
+#[test]
+fn quilt_profile_is_isomorphic() {
+    let release = build_release(LoaderKind::Quilt, "1.20.1", "0.20.0-beta.9", QUILT_PROFILE)
+        .expect("quilt profile 应可归一化");
+
+    assert_eq!(release.version_id, "1.20.1-quilt-0.20.0-beta.9");
+    assert_eq!(release.version_json.jar.as_deref(), Some("1.20.1"));
+    assert_eq!(
+        release.version_json.main_class.as_deref(),
+        Some("org.quiltmc.loader.impl.launch.knot.KnotClient")
+    );
+    assert_eq!(release.support, LoaderSupport::JsonRoute);
+    // Quilt 的 profile 没有 loading 库时不该编造；这里有 quilt-loader，因此无告警。
+    assert!(release.warnings.is_empty(), "{:?}", release.warnings);
+}
+
+#[test]
+fn missing_main_class_is_metadata_error() {
+    let profile = r#"{"id":"x","inheritsFrom":"1.20.1","libraries":[]}"#;
+    let error = build_release(LoaderKind::Fabric, "1.20.1", "0.15.11", profile)
+        .expect_err("缺主类必须报错");
+    assert_eq!(error.kind(), LoaderErrorKind::Metadata);
+}
+
+#[test]
+fn missing_loader_library_is_appended_with_warning() {
+    // 去掉 fabric-loader 那条，看归一化会不会补。
+    let profile = r#"{
+      "id": "fabric-loader-0.15.11-1.20.1",
+      "inheritsFrom": "1.20.1",
+      "mainClass": "net.fabricmc.loader.impl.launch.knot.KnotClient",
+      "libraries": [{"name": "org.ow2.asm:asm:9.6", "url": "https://maven.fabricmc.net/"}]
+    }"#;
+    let release = build_release(LoaderKind::Fabric, "1.20.1", "0.15.11", profile)
+        .expect("缺 loader 库应降级为告警 + 补一条");
+    assert_eq!(release.warnings.len(), 1);
+    let libraries = release.version_json.libraries.expect("应有库");
+    assert!(libraries
+        .iter()
+        .any(|library| library.name == "net.fabricmc:fabric-loader:0.15.11"));
+}
+
+#[test]
+fn loader_list_parses_and_prefers_stable() {
+    let list = r#"[
+      {"loader": {"version": "0.16.0-beta.1", "stable": false, "maven": "net.fabricmc:fabric-loader:0.16.0-beta.1"}},
+      {"loader": {"version": "0.15.11", "stable": true, "maven": "net.fabricmc:fabric-loader:0.15.11"}},
+      {"loader": {"version": "0.15.10", "stable": true, "maven": "net.fabricmc:fabric-loader:0.15.10"}}
+    ]"#;
+    let entries = parse_loader_list(LoaderKind::Fabric, list).expect("列表应可解析");
+    assert_eq!(entries.len(), 3);
+    assert_eq!(
+        pick_default(&entries).map(|entry| entry.version.as_str()),
+        Some("0.15.11")
+    );
+}
+
+#[test]
+fn quilt_loader_list_without_stable_flag_still_picks_first() {
+    // 实测 Quilt 的 loader 条目没有 stable 键。
+    let list = r#"[
+      {"loader": {"version": "0.20.0-beta.9", "maven": "org.quiltmc:quilt-loader:0.20.0-beta.9"}},
+      {"loader": {"version": "0.19.2", "maven": "org.quiltmc:quilt-loader:0.19.2"}}
+    ]"#;
+    let entries = parse_loader_list(LoaderKind::Quilt, list).expect("列表应可解析");
+    assert!(entries.iter().all(|entry| entry.stable));
+    assert_eq!(
+        pick_default(&entries).map(|entry| entry.version.as_str()),
+        Some("0.20.0-beta.9")
+    );
+}
+
+#[test]
+fn empty_loader_list_is_not_found() {
+    let error = parse_loader_list(LoaderKind::Fabric, "[]").expect_err("空列表应报错");
+    assert_eq!(error.kind(), LoaderErrorKind::NotFound);
+}
diff --git a/crates/core/src/addon/loader/tests/forge.rs b/crates/core/src/addon/loader/tests/forge.rs
new file mode 100644
index 0000000..123c426
--- /dev/null
+++ b/crates/core/src/addon/loader/tests/forge.rs
@@ -0,0 +1,258 @@
+//! NeoForge / Forge：install profile 解析与三条路线的判定。
+
+use crate::addon::loader::forge::{build_release, InstallProfile};
+use crate::addon::loader::{LoaderErrorKind, LoaderKind, LoaderSupport};
+use crate::game::manifest::VersionJson;
+
+/// spec 1 + client 侧 processor（实测 NeoForge 21.1.80 / Forge 1.20.1 的形状，裁剪过）。
+pub(crate) const NEOFORGE_PROFILE: &str = r#"{
+  "spec": 1,
+  "profile": "NeoForge",
+  "version": "neoforge-21.1.80",
+  "minecraft": "1.21.1",
+  "json": "/version.json",
+  "path": null,
+  "processors": [
+    {"sides": ["server"], "jar": "net.neoforged.installertools:installertools:2.1.2"},
+    {"sides": ["client"], "jar": "net.neoforged.installertools:installertools:2.1.2"},
+    {"jar": "net.neoforged.installertools:installertools:2.1.2"},
+    {"sides": ["client"], "jar": "net.neoforged.installertools:installertools:2.1.2"}
+  ],
+  "libraries": [
+    {"name": "com.google.code.gson:gson:2.8.9@jar"},
+    {"name": "org.apache.commons:commons-text:1.3@jar"}
+  ],
+  "data": {"MC_SLIM": {"client": "[net.neoforged:neoforge:21.1.80:client-slim]"}}
+}"#;
+
+/// spec 1 版本 JSON 的裁剪版（内容形状照 21.1.80）。
+pub(crate) const NEOFORGE_VERSION_JSON: &str = r#"{
+  "id": "neoforge-21.1.80",
+  "inheritsFrom": "1.21.1",
+  "type": "release",
+  "mainClass": "cpw.mods.bootstraplauncher.BootstrapLauncher",
+  "arguments": {"game": ["--launchTarget", "forgeclient"], "jvm": ["-DignoreList=bootstraplauncher"]},
+  "libraries": [
+    {"name": "cpw.mods:securejarhandler:2.1.10",
+     "downloads": {"artifact": {"path": "cpw/mods/securejarhandler/2.1.10/securejarhandler-2.1.10.jar",
+       "url": "https://maven.neoforged.net/releases/cpw/mods/securejarhandler/2.1.10/securejarhandler-2.1.10.jar",
+       "sha1": "51e6a22c6c716beb11e244bf5b8be480f51dd6b5", "size": 88749}}}
+  ]
+}"#;
+
+/// spec 0 + 无 processors（实测 Forge 1.12.2-14.23.5.2860），universal jar 的 url 是空串。
+pub(crate) const FORGE_LEGACY_PROFILE: &str = r#"{
+  "spec": 0,
+  "profile": "forge",
+  "version": "1.12.2-forge-14.23.5.2860",
+  "minecraft": "1.12.2",
+  "json": "/version.json",
+  "path": "net.minecraftforge:forge:1.12.2-14.23.5.2860",
+  "processors": [],
+  "libraries": [{"name": "net.minecraftforge:forge:1.12.2-14.23.5.2860"}]
+}"#;
+
+pub(crate) const FORGE_LEGACY_VERSION_JSON: &str = r#"{
+  "id": "1.12.2-forge-14.23.5.2860",
+  "inheritsFrom": "1.12.2",
+  "mainClass": "net.minecraft.launchwrapper.Launch",
+  "minecraftArguments": "--username ${auth_player_name} --tweakClass net.minecraftforge.fml.common.launcher.FMLTweaker",
+  "libraries": [
+    {"name": "net.minecraftforge:forge:1.12.2-14.23.5.2860",
+     "downloads": {"artifact": {"path": "net/minecraftforge/forge/1.12.2-14.23.5.2860/forge-1.12.2-14.23.5.2860.jar",
+       "url": "", "sha1": "029250575d3aa2cf80b56dffb66238a1eeaea2ac", "size": 4466148}}}
+  ]
+}"#;
+
+fn profile(json: &str) -> InstallProfile {
+    serde_json::from_str(json).expect("夹具 profile 应可解析")
+}
+
+fn version_json(json: &str) -> VersionJson {
+    VersionJson::from_json_str(json).expect("夹具版本 JSON 应可解析")
+}
+
+#[test]
+fn client_processors_mark_version_as_installer_required() {
+    let release = build_release(
+        LoaderKind::NeoForge,
+        "1.21.1",
+        "21.1.80",
+        &profile(NEOFORGE_PROFILE),
+        Some(&version_json(NEOFORGE_VERSION_JSON)),
+    )
+    .expect("版本 JSON 齐备时应能生成清单");
+
+    // 2 条 sides 含 client + 1 条无 sides（两侧都要）= 3 条 client 侧。
+    assert_eq!(profile(NEOFORGE_PROFILE).client_processors(), 3);
+    // M35 起 RequiresInstaller 是可真装的路线（外调 java 跑 processors），
+    // 但"要跑 installer"这个事实仍要能被上层看见。
+    assert!(release.is_installable());
+    assert!(release.requires_installer());
+    let reason = release
+        .installer_reason()
+        .expect("应给需要 installer 的原因");
+    assert!(reason.contains("3 个 client 侧 processor"), "{reason}");
+    // 版本清单本身仍然正确生成（--dry-run 能看到它）。
+    assert_eq!(release.version_id, "1.21.1-neoforge-21.1.80");
+    assert_eq!(
+        release.version_json.inherits_from.as_deref(),
+        Some("1.21.1")
+    );
+    assert_eq!(release.version_json.jar.as_deref(), Some("1.21.1"));
+    // processor 依赖不进启动 classpath，只记数量进告警。
+    assert_eq!(release.version_json.libraries.map_or(0, |l| l.len()), 1);
+    assert!(release
+        .warnings
+        .iter()
+        .any(|warning| warning.contains("processor 依赖")));
+}
+
+#[test]
+fn spec_zero_profile_is_json_route_and_fills_empty_url() {
+    let release = build_release(
+        LoaderKind::Forge,
+        "1.12.2",
+        "1.12.2-14.23.5.2860",
+        &profile(FORGE_LEGACY_PROFILE),
+        Some(&version_json(FORGE_LEGACY_VERSION_JSON)),
+    )
+    .expect("spec 0 应走 json 路线");
+
+    assert_eq!(release.support, LoaderSupport::JsonRoute);
+    assert_eq!(release.loader_version, "14.23.5.2860");
+    assert_eq!(release.version_id, "1.12.2-forge-14.23.5.2860");
+    assert_eq!(
+        release.version_json.main_class.as_deref(),
+        Some("net.minecraft.launchwrapper.Launch")
+    );
+
+    // 空 url 必须补成 maven 地址：本体 jar 在官方 maven 上**只发布在 -universal classifier 下**
+    // （无 classifier 路径官方 404，仅靠 BMCLAPI 302 别名兜底），所以 URL 要带 -universal。
+    let library = release
+        .version_json
+        .libraries
+        .as_ref()
+        .and_then(|libraries| libraries.first())
+        .expect("应有 forge 本体库");
+    let artifact = library
+        .downloads
+        .as_ref()
+        .and_then(|downloads| downloads.artifact.as_ref())
+        .expect("应有 artifact");
+    assert_eq!(
+        artifact.url.as_deref(),
+        Some(
+            "https://maven.minecraftforge.net/net/minecraftforge/forge/1.12.2-14.23.5.2860/forge-1.12.2-14.23.5.2860-universal.jar"
+        ),
+        "URL 必须带 -universal（官方 maven 只托管这个 classifier）"
+    );
+    assert_eq!(artifact.size, Some(4_466_148));
+    assert!(library
+        .url
+        .as_deref()
+        .unwrap_or_default()
+        .contains("minecraftforge"));
+
+    // 磁盘落点仍用原 path（与官方 installer 内嵌条目同名，启动 classpath 布局不变）。
+    assert_eq!(
+        artifact.path.as_deref(),
+        Some("net/minecraftforge/forge/1.12.2-14.23.5.2860/forge-1.12.2-14.23.5.2860.jar")
+    );
+    let dest = library.relative_path().expect("落点应可推导");
+    assert!(
+        dest.ends_with("forge-1.12.2-14.23.5.2860.jar"),
+        "落点不该带 classifier：{}",
+        dest.display()
+    );
+}
+
+#[test]
+fn legacy_inline_protocol_is_unsupported() {
+    // 老协议：没有独立 version.json，只有内联 versionInfo + 解包信息。
+    let profile = profile(
+        r#"{"spec": 1, "minecraft": "1.7.10",
+            "install": {"filePath": "forge-1.7.10-10.13.4.1614-universal.jar"},
+            "versionInfo": {"id": "1.7.10-Forge10.13.4.1614", "mainClass": "net.minecraft.launchwrapper.Launch"},
+            "processors": []}"#,
+    );
+    assert!(profile.is_legacy_protocol());
+    let error = build_release(
+        LoaderKind::Forge,
+        "1.7.10",
+        "1.7.10-10.13.4.1614",
+        &profile,
+        None,
+    )
+    .expect_err("老协议必须明确 unsupported");
+    assert_eq!(error.kind(), LoaderErrorKind::Unsupported);
+    assert!(error.message().contains("老协议"), "{}", error.message());
+    assert!(error.hint().is_some());
+}
+
+#[test]
+fn universal_classifier_rewrite_is_scoped_to_the_installer_body() {
+    // 只有 install profile 的 `path` 声明的本体构件走 -universal；
+    // 其它同样"空 url + 有 path"的库必须保持原路径（乱加 classifier 会 404）。
+    let embedded = version_json(
+        r#"{"id": "1.12.2-forge-14.23.5.2860", "inheritsFrom": "1.12.2",
+            "mainClass": "net.minecraft.launchwrapper.Launch",
+            "libraries": [
+              {"name": "net.minecraftforge:forge:1.12.2-14.23.5.2860",
+               "downloads": {"artifact": {"path": "net/minecraftforge/forge/1.12.2-14.23.5.2860/forge-1.12.2-14.23.5.2860.jar", "url": ""}}},
+              {"name": "net.minecraftforge:mergetool:1.1.5",
+               "downloads": {"artifact": {"path": "net/minecraftforge/mergetool/1.1.5/mergetool-1.1.5.jar", "url": ""}}}
+            ]}"#,
+    );
+    let release = build_release(
+        LoaderKind::Forge,
+        "1.12.2",
+        "1.12.2-14.23.5.2860",
+        &profile(FORGE_LEGACY_PROFILE),
+        Some(&embedded),
+    )
+    .expect("spec 0 应走 json 路线");
+    let libraries = release.version_json.libraries.expect("应有库");
+    let url_of = |name: &str| {
+        libraries
+            .iter()
+            .find(|library| library.name == name)
+            .and_then(|library| library.downloads.as_ref())
+            .and_then(|downloads| downloads.artifact.as_ref())
+            .and_then(|artifact| artifact.url.clone())
+            .unwrap_or_default()
+    };
+    assert!(url_of("net.minecraftforge:forge:1.12.2-14.23.5.2860").ends_with("-universal.jar"));
+    assert_eq!(
+        url_of("net.minecraftforge:mergetool:1.1.5"),
+        "https://maven.minecraftforge.net/net/minecraftforge/mergetool/1.1.5/mergetool-1.1.5.jar"
+    );
+}
+
+#[test]
+fn version_mismatch_between_installer_and_target_is_metadata_error() {
+    let error = build_release(
+        LoaderKind::NeoForge,
+        "1.20.1",
+        "21.1.80",
+        &profile(NEOFORGE_PROFILE),
+        Some(&version_json(NEOFORGE_VERSION_JSON)),
+    )
+    .expect_err("原版版本不符必须报错");
+    assert_eq!(error.kind(), LoaderErrorKind::Metadata);
+    assert!(error.message().contains("1.21.1"), "{}", error.message());
+}
+
+#[test]
+fn missing_main_class_is_metadata_error() {
+    let embedded = version_json(r#"{"id": "x", "inheritsFrom": "1.12.2", "libraries": []}"#);
+    let error = build_release(
+        LoaderKind::Forge,
+        "1.12.2",
+        "1.12.2-14.23.5.2860",
+        &profile(FORGE_LEGACY_PROFILE),
+        Some(&embedded),
+    )
+    .expect_err("缺主类必须报错");
+    assert_eq!(error.kind(), LoaderErrorKind::Metadata);
+}
diff --git a/crates/core/src/addon/loader/tests/maven.rs b/crates/core/src/addon/loader/tests/maven.rs
new file mode 100644
index 0000000..2d30b12
--- /dev/null
+++ b/crates/core/src/addon/loader/tests/maven.rs
@@ -0,0 +1,134 @@
+//! maven 版本表：XML 扫描、NeoForge 版本反解、版本挑选、installer 地址。
+
+use crate::addon::loader::maven::{
+    display_loader_version, installer_url, matches_mc, metadata_url, neoforge_mc_version,
+    normalize_maven_version, parse_metadata_versions, select_versions,
+};
+use crate::addon::loader::LoaderKind;
+
+/// 裁剪过的 maven-metadata.xml（真实结构，只留 `<version>` 列表）。
+const METADATA: &str = r#"<?xml version="1.0" encoding="UTF-8"?>
+<metadata>
+  <groupId>net.neoforged</groupId>
+  <artifactId>neoforge</artifactId>
+  <versioning>
+    <latest>26.1.2.125</latest>
+    <versions>
+      <version>20.4.237</version>
+      <version>21.1.9</version>
+      <version>21.1.80</version>
+      <version>26.1.2.125</version>
+      <version>0.0.1-snapshot-1</version>
+    </versions>
+  </versioning>
+</metadata>"#;
+
+#[test]
+fn metadata_versions_are_scanned() {
+    let versions = parse_metadata_versions(METADATA);
+    assert_eq!(
+        versions,
+        vec![
+            "20.4.237",
+            "21.1.9",
+            "21.1.80",
+            "26.1.2.125",
+            "0.0.1-snapshot-1"
+        ]
+    );
+    assert!(parse_metadata_versions("not xml").is_empty());
+}
+
+#[test]
+fn neoforge_versions_map_back_to_minecraft() {
+    // analyse/05 §1.3 的三条规则。
+    assert_eq!(neoforge_mc_version("21.1.80").as_deref(), Some("1.21.1"));
+    assert_eq!(neoforge_mc_version("20.4.237").as_deref(), Some("1.20.4"));
+    assert_eq!(neoforge_mc_version("26.1.2.125").as_deref(), Some("26.1"));
+    // 快照（主版本 0）不挂原版版本号。
+    assert_eq!(neoforge_mc_version("0.0.1-snapshot-1"), None);
+}
+
+#[test]
+fn select_versions_filters_and_sorts_numerically() {
+    let versions = parse_metadata_versions(METADATA);
+    let picked = select_versions(LoaderKind::NeoForge, "1.21.1", &versions);
+    // 数字序：9 < 80（字符串序会反过来）。
+    assert_eq!(picked, vec!["21.1.9", "21.1.80"]);
+    assert!(select_versions(LoaderKind::NeoForge, "1.19.2", &versions).is_empty());
+}
+
+#[test]
+fn forge_versions_carry_the_minecraft_prefix() {
+    let versions = vec![
+        "1.20.1-47.3.0".to_string(),
+        "1.20.1-47.2.0".to_string(),
+        "1.12.2-14.23.5.2860".to_string(),
+    ];
+    let picked = select_versions(LoaderKind::Forge, "1.20.1", &versions);
+    assert_eq!(picked, vec!["1.20.1-47.2.0", "1.20.1-47.3.0"]);
+    assert!(matches_mc(LoaderKind::Forge, "1.20.1", "1.20.1-47.3.0"));
+    assert!(!matches_mc(LoaderKind::Forge, "1.20.2", "1.20.1-47.3.0"));
+}
+
+#[test]
+fn neoforge_1201_uses_forge_layout() {
+    // 1.20.1 的 NeoForge 早产版挂在 net/neoforged/forge 下，版本串带原版前缀。
+    assert!(metadata_url(LoaderKind::NeoForge, "1.20.1")
+        .ends_with("net/neoforged/forge/maven-metadata.xml"));
+    assert!(metadata_url(LoaderKind::NeoForge, "1.21.1")
+        .ends_with("net/neoforged/neoforge/maven-metadata.xml"));
+    assert!(metadata_url(LoaderKind::Forge, "1.20.1")
+        .ends_with("net/minecraftforge/forge/maven-metadata.xml"));
+
+    let versions = vec!["1.20.1-47.1.106".to_string(), "1.20.1-47.1.90".to_string()];
+    let picked = select_versions(LoaderKind::NeoForge, "1.20.1", &versions);
+    assert_eq!(picked.len(), 2);
+    assert_eq!(
+        display_loader_version(LoaderKind::NeoForge, "1.20.1", "1.20.1-47.1.106"),
+        "47.1.106"
+    );
+}
+
+#[test]
+fn versions_are_normalized_and_displayed() {
+    // Forge：用户给 "47.2.0"，maven 上是 "1.20.1-47.2.0"。
+    assert_eq!(
+        normalize_maven_version(LoaderKind::Forge, "1.20.1", "47.2.0"),
+        "1.20.1-47.2.0"
+    );
+    assert_eq!(
+        normalize_maven_version(LoaderKind::Forge, "1.20.1", "1.20.1-47.2.0"),
+        "1.20.1-47.2.0"
+    );
+    assert_eq!(
+        display_loader_version(LoaderKind::Forge, "1.20.1", "1.20.1-47.2.0"),
+        "47.2.0"
+    );
+    // NeoForge（非 1.20.1 布局）本身就是完整 maven 版本。
+    assert_eq!(
+        normalize_maven_version(LoaderKind::NeoForge, "1.21.1", "21.1.80"),
+        "21.1.80"
+    );
+    assert_eq!(
+        display_loader_version(LoaderKind::NeoForge, "1.21.1", "21.1.80"),
+        "21.1.80"
+    );
+}
+
+#[test]
+fn installer_urls_point_at_official_maven() {
+    assert_eq!(
+        installer_url(LoaderKind::Forge, "1.20.1", "1.20.1-47.2.0"),
+        "https://maven.minecraftforge.net/net/minecraftforge/forge/1.20.1-47.2.0/forge-1.20.1-47.2.0-installer.jar"
+    );
+    assert_eq!(
+        installer_url(LoaderKind::NeoForge, "1.21.1", "21.1.80"),
+        "https://maven.neoforged.net/releases/net/neoforged/neoforge/21.1.80/neoforge-21.1.80-installer.jar"
+    );
+    // 1.20.1 的 NeoForge 走 forge 布局（文件名也是 forge-）。
+    assert_eq!(
+        installer_url(LoaderKind::NeoForge, "1.20.1", "1.20.1-47.1.106"),
+        "https://maven.neoforged.net/releases/net/neoforged/forge/1.20.1-47.1.106/forge-1.20.1-47.1.106-installer.jar"
+    );
+}
diff --git a/crates/core/src/addon/loader/tests/mod.rs b/crates/core/src/addon/loader/tests/mod.rs
new file mode 100644
index 0000000..4d2f93f
--- /dev/null
+++ b/crates/core/src/addon/loader/tests/mod.rs
@@ -0,0 +1,56 @@
+//! `addon::loader` 的单元测试：离线夹具对拍 + 镜像选择 + unsupported 判定。
+//!
+//! 刻意**不打真实网络**：JSON 归一化、版本表挑选、镜像候选、计划形状全是纯计算。
+//! 夹具是官方响应的**裁剪版**（保留形状与关键字段，去掉几百行库与 base64 图标）。
+
+mod fabric;
+mod forge;
+mod maven;
+mod plan;
+
+/// 裁剪过的 Fabric `/profile/json`（1.20.1 + fabric-loader 0.15.11）。
+pub(crate) const FABRIC_PROFILE: &str = r#"{
+  "id": "fabric-loader-0.15.11-1.20.1",
+  "inheritsFrom": "1.20.1",
+  "releaseTime": "2026-10-29T10:25:18+0000",
+  "time": "2026-10-29T10:25:18+0000",
+  "type": "release",
+  "mainClass": "net.fabricmc.loader.impl.launch.knot.KnotClient",
+  "arguments": {"game": [], "jvm": ["-DFabricMcEmu= net.minecraft.client.main.Main "]},
+  "libraries": [
+    {"name": "org.ow2.asm:asm:9.6", "url": "https://maven.fabricmc.net/",
+     "sha1": "aa205cf0a06dbd8e04ece91c0b37c3f5d567546a", "size": 123598},
+    {"name": "net.fabricmc:sponge-mixin:0.13.3+mixin.0.8.5", "url": "https://maven.fabricmc.net/"},
+    {"name": "net.fabricmc:intermediary:1.20.1", "url": "https://maven.fabricmc.net/"},
+    {"name": "net.fabricmc:fabric-loader:0.15.11", "url": "https://maven.fabricmc.net/"}
+  ]
+}"#;
+
+/// 裁剪过的 Quilt `/profile/json`（1.20.1 + quilt-loader 0.20.0-beta.9）。
+pub(crate) const QUILT_PROFILE: &str = r#"{
+  "id": "quilt-loader-0.20.0-beta.9-1.20.1",
+  "inheritsFrom": "1.20.1",
+  "type": "release",
+  "mainClass": "org.quiltmc.loader.impl.launch.knot.KnotClient",
+  "arguments": {"game": []},
+  "libraries": [
+    {"name": "net.fabricmc:tiny-mappings-parser:0.3.0+build.17", "url": "https://maven.fabricmc.net/"},
+    {"name": "org.quiltmc:quilt-json5:1.0.4+final", "url": "https://maven.quiltmc.org/repository/release/"},
+    {"name": "org.quiltmc:quilt-loader:0.20.0-beta.9", "url": "https://maven.quiltmc.org/repository/release/"}
+  ]
+}"#;
+
+/// 原版 1.20.1 的**已裁剪**版本 JSON（继承链解析的父层）。
+pub(crate) const VANILLA_1201: &str = r#"{
+  "id": "1.20.1",
+  "type": "release",
+  "mainClass": "net.minecraft.client.main.Main",
+  "assets": "5",
+  "assetIndex": {"id": "5", "sha1": "0000", "size": 1,
+                 "url": "https://piston-meta.mojang.com/v1/packages/5.json"},
+  "downloads": {"client": {"sha1": "1111", "size": 2,
+                           "url": "https://piston-data.mojang.com/v1/objects/1/client.jar"}},
+  "libraries": [
+    {"name": "com.mojang:brigadier:1.0.18", "url": "https://libraries.minecraft.net/"}
+  ]
+}"#;
diff --git a/crates/core/src/addon/loader/tests/plan.rs b/crates/core/src/addon/loader/tests/plan.rs
new file mode 100644
index 0000000..fbe193e
--- /dev/null
+++ b/crates/core/src/addon/loader/tests/plan.rs
@@ -0,0 +1,192 @@
+//! 计划形状 / 继承链两级解析 / 镜像选择。
+
+use std::collections::BTreeMap;
+
+use super::{FABRIC_PROFILE, VANILLA_1201};
+use crate::addon::loader::fabric::{build_release, loader_list_url, profile_url};
+use crate::addon::loader::maven;
+use crate::addon::loader::{
+    LoaderInstallPlan, LoaderKind, LoaderPlanInput, LoaderRelease, LoaderSupport,
+};
+use crate::download::mirrors::MirrorTable;
+use crate::download::region::RegionProfile;
+use crate::download::types::ResourceKind;
+use crate::game::arguments::Environment;
+use crate::game::install::FileRole;
+use crate::game::{inherit, layout::GameLayout, VersionJson};
+
+fn fabric_release() -> LoaderRelease {
+    build_release(LoaderKind::Fabric, "1.20.1", "0.15.11", FABRIC_PROFILE).expect("夹具应可归一化")
+}
+
+fn environment() -> Environment {
+    Environment {
+        os: "windows".to_string(),
+        os_version: String::new(),
+        arch: "x86_64".to_string(),
+        ..Environment::host()
+    }
+}
+
+#[test]
+fn plan_contains_only_loader_libraries() {
+    let layout = GameLayout::new("/g/.minecraft");
+    let release = fabric_release();
+    let plan = LoaderInstallPlan::build(LoaderPlanInput {
+        layout: &layout,
+        release: &release,
+        environment: &environment(),
+        vanilla_installed: false,
+    });
+
+    assert_eq!(plan.install.version_id, "1.20.1-fabric-0.15.11");
+    // jar 与资源归原版层，loader 计划里只有库。
+    assert_eq!(plan.install.jar_id, "1.20.1");
+    assert!(plan
+        .files()
+        .iter()
+        .all(|file| file.role == FileRole::Library));
+    assert!(
+        plan.files()
+            .iter()
+            .any(|file| file.name.contains("fabric-loader")),
+        "缺 fabric-loader：{:?}",
+        plan.files().iter().map(|f| &f.name).collect::<Vec<_>>()
+    );
+    assert!(plan.install.version_json_path.ends_with(
+        std::path::Path::new("versions")
+            .join("1.20.1-fabric-0.15.11")
+            .join("1.20.1-fabric-0.15.11.json")
+    ));
+    // 只下 loader 那几个库，不该冒出资产/客户端 jar。
+    assert!(plan.install.file_count() >= 4);
+    assert!(plan.install.client_jar().is_none());
+}
+
+#[test]
+fn plan_marks_missing_vanilla_and_unsupported() {
+    let layout = GameLayout::new("/g/.minecraft");
+    let release = fabric_release();
+    let plan = LoaderInstallPlan::build(LoaderPlanInput {
+        layout: &layout,
+        release: &release,
+        environment: &environment(),
+        vanilla_installed: false,
+    });
+    assert!(plan.vanilla_install_needed);
+    assert!(plan
+        .warnings()
+        .iter()
+        .any(|warning| warning.contains("原版 1.20.1 尚未安装")));
+
+    let installed = LoaderInstallPlan::build(LoaderPlanInput {
+        layout: &layout,
+        release: &release,
+        environment: &environment(),
+        vanilla_installed: true,
+    });
+    assert!(!installed.vanilla_install_needed);
+
+    // 把 support 改成"需要 installer"，计划里要出现"要外调 java"的告警（M35 起可真装）。
+    let mut blocked = fabric_release();
+    blocked.support = LoaderSupport::RequiresInstaller {
+        reason: "需要 processors".to_string(),
+    };
+    let plan = LoaderInstallPlan::build(LoaderPlanInput {
+        layout: &layout,
+        release: &blocked,
+        environment: &environment(),
+        vanilla_installed: true,
+    });
+    assert!(plan
+        .warnings()
+        .iter()
+        .any(|warning| warning.contains("需要外调 java 跑 installer processors")));
+}
+
+#[test]
+fn summary_json_carries_loader_block() {
+    let layout = GameLayout::new("/g/.minecraft");
+    let release = fabric_release();
+    let plan = LoaderInstallPlan::build(LoaderPlanInput {
+        layout: &layout,
+        release: &release,
+        environment: &environment(),
+        vanilla_installed: true,
+    });
+    let summary = plan.summary_json();
+    assert_eq!(summary["loader"]["kind"], "fabric");
+    assert_eq!(summary["loader"]["version_id"], "1.20.1-fabric-0.15.11");
+    assert_eq!(summary["loader"]["support"]["mode"], "json_route");
+    assert_eq!(summary["loader"]["inherits_from"], "1.20.1");
+    assert_eq!(summary["vanilla_install_needed"], false);
+}
+
+#[test]
+fn loader_json_resolves_two_level_chain() {
+    // loader → 原版 两级继承：解析后必须是扁平的、jar 指原版、库两侧合并。
+    let vanilla = VersionJson::from_json_str(VANILLA_1201).expect("原版夹具");
+    let loader = fabric_release().version_json;
+    let mut table: BTreeMap<String, VersionJson> = BTreeMap::new();
+    table.insert("1.20.1".to_string(), vanilla);
+    table.insert("1.20.1-fabric-0.15.11".to_string(), loader.clone());
+
+    let resolved = inherit::resolve(&table, &loader).expect("两级链应可解析");
+    assert!(resolved.is_resolved());
+    assert_eq!(resolved.inherits_from, None);
+    assert_eq!(resolved.jar.as_deref(), Some("1.20.1"));
+    assert_eq!(
+        resolved.main_class.as_deref(),
+        Some("net.fabricmc.loader.impl.launch.knot.KnotClient")
+    );
+    // 资源来自原版层。
+    assert_eq!(resolved.assets.as_deref(), Some("5"));
+    assert!(resolved.client_jar().is_some());
+    // 库两层的并集（父在前，子在后）。
+    let libraries = resolved.libraries.expect("应有库");
+    assert_eq!(libraries.len(), 5);
+    assert_eq!(libraries[0].name, "com.mojang:brigadier:1.0.18");
+}
+
+#[test]
+fn loader_meta_and_maven_urls_hit_bmclapi_mirrors() {
+    let table = MirrorTable::builtin();
+    let mirror_first = RegionProfile::mirror_first(0);
+
+    let fabric_meta = loader_list_url(LoaderKind::Fabric, "1.20.1");
+    let candidates = table.expand(&fabric_meta, ResourceKind::VersionManifest, &mirror_first);
+    let sources: Vec<&str> = candidates.iter().map(|c| c.source.as_str()).collect();
+    assert_eq!(
+        sources.first(),
+        Some(&"bmclapi"),
+        "镜像优先时应先走 BMCLAPI"
+    );
+    assert!(candidates.iter().any(|candidate| candidate
+        .url
+        .contains("/fabric-meta/v2/versions/loader/1.20.1")));
+
+    let quilt_profile = profile_url(LoaderKind::Quilt, "1.20.1", "0.20.0-beta.9");
+    let candidates = table.expand(&quilt_profile, ResourceKind::VersionManifest, &mirror_first);
+    assert_eq!(candidates[0].source, "bmclapi");
+    assert!(candidates[0].url.contains("/quilt-meta/"));
+
+    let neoforge_installer = maven::installer_url(LoaderKind::NeoForge, "1.21.1", "21.1.80");
+    let candidates = table.expand(&neoforge_installer, ResourceKind::Library, &mirror_first);
+    assert_eq!(candidates[0].source, "bmclapi");
+    assert!(candidates[0]
+        .url
+        .starts_with("https://bmclapi2.bangbang93.com/maven/net/neoforged/neoforge/"));
+
+    let forge_meta = maven::metadata_url(LoaderKind::Forge, "1.20.1");
+    let candidates = table.expand(&forge_meta, ResourceKind::VersionManifest, &mirror_first);
+    assert_eq!(candidates[0].source, "bmclapi");
+    assert!(candidates[0]
+        .url
+        .starts_with("https://bmclapi2.bangbang93.com/maven/net/minecraftforge/forge/"));
+
+    // 直连模式：官方在前，镜像只兜底。
+    let direct = RegionProfile::direct(0);
+    let candidates = table.expand(&fabric_meta, ResourceKind::VersionManifest, &direct);
+    assert_eq!(candidates[0].source, "official");
+    assert_eq!(candidates[0].url, fabric_meta);
+}
diff --git a/crates/core/src/addon/mod.rs b/crates/core/src/addon/mod.rs
new file mode 100644
index 0000000..8cd9ca0
--- /dev/null
+++ b/crates/core/src/addon/mod.rs
@@ -0,0 +1,48 @@
+//! Mod 与整合包：加载器安装（Fabric/Quilt/NeoForge/Forge）、整合包双格式导入导出、
+//! 本地 Mod 管理、CurseForge / Modrinth 客户端。
+//!
+//! 设计定稿：`DevDocs/PlanDoc/08-mod-and-recommend.md`（决策 D10）。
+//! 安全要点：整合包路径穿越双检；AI 推荐走「结构化过滤在前 + LLM 排序在后 + 来源链接防幻觉」。
+//!
+//! # 当前公共面
+//!
+//! - [`loader`]（P2 · M32）：加载器安装——官方元数据 → 带 `inheritsFrom` 的 loader 版本 JSON
+//!   → 补库清单，落盘与实例登记复用 `core::game::install`（M27）。
+//! - [`pack`]（P2 · M110）：整合包的**格式无关模型**与**格式扩展点**——CF / Modrinth / MultiMC
+//!   三种格式的探测与读取、CF / mrpack 的渲染与导出、zip 安全读取（穿越双检 / 符号链接 /
+//!   条数体积上限）。
+//! - [`import`]（P2 · M111）：**导入管线**——三种格式 → 实例目录：跨段落地、overrides 三方
+//!   合并（保用户改动）、两阶段补全与失败分级、临时目录 + rename/journal 回滚、结构化报告。
+//!   导出（M112）另起模块。
+//! - [`export`]（P2 · M112）：**导出管线**——实例目录 → `.mrpack`（优先）/ CF `manifest.json`。
+//!   逐文件判定「能否被远程替代」（Modrinth SHA-1 + CF 指纹），判定不了的**内联进 `overrides/`**
+//!   并逐条进报告；`.disabled` 用路径后缀；`game`/`dependencies` 从实例快照取。
+//!   MultiMC/Prism **只导入不导出**（有意省略）。
+//!
+//! 规划中：本地 mod 管理（D10 §3）、CF/Modrinth 客户端（§5）。
+
+pub mod export;
+pub mod import;
+pub mod loader;
+pub mod pack;
+
+pub use export::{
+    export_instance, ExportFile, ExportReport, ExportRequest, FileClass, FileReason, RemoteCatalog,
+    RemoteHit,
+};
+pub use import::{
+    import_pack, ConflictFile, ConflictPolicy, ImportError, ImportErrorKind, ImportProgress,
+    ImportProgressSink, ImportReport, ImportRequest, ImportStage, ImportStatus, ImportedFile,
+    MissingFile, PackBaseline, PackFetcher, RejectedComponent,
+};
+pub use loader::{
+    LoaderError, LoaderErrorKind, LoaderInstallPlan, LoaderKind, LoaderPlanInput, LoaderRelease,
+    LoaderSource, LoaderSupport,
+};
+pub use pack::{
+    EnvSupport, PackArchive, PackError, PackErrorKind, PackFile, PackFormat, PackLimits,
+    PackLoader, PackManifest, PackOverrides, PackRegistry, PackResult, PackSide,
+};
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/core/src/addon/pack.rs b/crates/core/src/addon/pack.rs
new file mode 100644
index 0000000..a308012
--- /dev/null
+++ b/crates/core/src/addon/pack.rs
@@ -0,0 +1,71 @@
+//! 整合包的**格式无关模型**与**格式扩展点**（M110）。导入/导出管线（M111/M112）建在这上面。
+//!
+//! 设计定稿：`DevDocs/PlanDoc/08-mod-and-recommend.md` §2（D10），格式细节来自
+//! `DevDocs/analyse/05-modloader-modpack-p2.md` §2.1–§2.3（HMCL 源码级拆解，A 级来源）。
+//!
+//! # 本模块只做三件事
+//!
+//! | 层 | 模块 | 职责 |
+//! |----|------|------|
+//! | 安全读取 | [`archive`] | 目录与 zip 统一成"规整过的条目表"：路径穿越双检、符号链接拒绝、条数/体积上限 |
+//! | 格式 | [`format`] | [`format::PackFormat`] trait + [`format::PackRegistry`]：探测、读、渲染、写，**优先级写死** |
+//! | 模型 | [`manifest`] | [`manifest::PackManifest`]：包名/版本/作者/游戏版本/加载器/文件条目/覆盖目录，未知字段原样保留 |
+//!
+//! 三个内置格式：[`curseforge`]（`manifest.json`，可读可写）、[`modrinth`]（`.mrpack`，可读可写）、
+//! [`multimc`]（`mmc-pack.json`，**只读**）。
+//!
+//! # 导出面的边界（r1 之后写死）
+//!
+//! 默认 [`format::PackFormat::write`] **只保证同格式往返**：覆盖目录按模型原样搬，
+//! 不做目录映射 / `side` 分派 / 加载器 id 规范化 / `extra` 分桶（都属于 M112）。
+//! 表达不了的时候由 [`format::PackFormat::check_overrides`] 直接报 `pack_unsupported`，
+//! 而不是产出一个"成功但内容为空"的包。
+//!
+//! # 刻意不做的事（分工边界）
+//!
+//! - **不发网络请求**：CF 的 `projectID/fileID` → 文件名/URL 补全属于 M111（要用 CF API 与
+//!   MurmurHash2 指纹），本模块只把"缺什么"如实记成 `None`；
+//! - **不落盘解压**：`archive` 只读，不写实例目录。overrides 的三方合并（base/theirs/ours）
+//!   是 M111 的解压器职责，本模块提供它要的输入：每条覆盖文件的实例内相对路径 + SHA-1；
+//! - **不碰 UI 类型**：core 零 UI 依赖（`core-no-ui` 门禁），这里连 `String` 之外的表现层
+//!   类型都不出现；
+//! - **不猜格式**：探测顺序写死在 [`format::PackRegistry::builtin`]，同一份包命中多格式时
+//!   用固定的注册顺序选，并把其余命中记进 [`format::PackMatch::also_matched`]。
+//!
+//! # 安全（每条都有恶意样本测试，见 `tests/safety.rs`）
+//!
+//! 路径穿越判据是**两条独立检查**：①本模块的 [`path::normalize_file`]（七条写死的规则：
+//! 空名/`\0`/`\`/`:`/前导 `/`/任何 `..` 段/规整后为空）；②`zip` crate 的
+//! `enclosed_name()`（按 Windows 规则解析盘符、NTFS 数据流、保留设备名）。
+//! 为什么不能只留一条：`enclosed_name()` 允许"深度 0 的根目录"，也就是 `"/etc/passwd"`
+//! 它会放行；反过来，本模块的规则不认 Windows 保留设备名。**两条都过才算安全**。
+//!
+//! # 测试夹具的来源（不许把"看起来像"当真实）
+//!
+//! `tests/fixtures.rs` 里的 CF / mrpack / MultiMC 三个包**全部是手造的**：字段取自
+//! analyse/05 记录的 HMCL 解析器形状（A 级来源），内容是为了覆盖边界而编的（含一个刻意的
+//! 损坏文件：截断的 `config/broken.toml`、半截 `mods/half.jar`、零字节 `mods/broken.jar`）。
+//! **没有一个来自真实导出**——本任务环境离线，没有真实整合包样本可对照。真实样本的字段
+//! 偏移风险因此只能由 M111/M115（格式字段盘点）在拿到真包后回收，报告里已登记这条欠账。
+
+pub mod archive;
+pub mod curseforge;
+pub mod error;
+pub mod format;
+pub mod manifest;
+pub mod modrinth;
+pub mod multimc;
+pub mod path;
+
+#[cfg(test)]
+mod tests;
+
+pub use archive::{PackArchive, PackEntryInfo, PackLimits, ReadBudget};
+pub use curseforge::CurseForge;
+pub use error::{PackError, PackErrorKind, PackResult};
+pub use format::{PackFormat, PackMatch, PackPayload, PackRegistry};
+pub use manifest::{
+    EnvSupport, OverrideFile, PackFile, PackLoader, PackManifest, PackOverrides, PackSide,
+};
+pub use modrinth::Modrinth;
+pub use multimc::MultiMc;
diff --git a/crates/core/src/addon/pack/archive.rs b/crates/core/src/addon/pack/archive.rs
new file mode 100644
index 0000000..3a231a3
--- /dev/null
+++ b/crates/core/src/addon/pack/archive.rs
@@ -0,0 +1,298 @@
+//! 打包输入的安全读取层：[`PackArchive`] 把"目录"与"zip"统一成"一组规整过的条目"。
+//!
+//! # 为什么要有这一层
+//!
+//! 格式探测器要能对**目录**（MultiMC 实例、已解开的整合包）与**zip**（`.zip` / `.mrpack`）
+//! 一视同仁地问"有没有 `modrinth.index.json`"，而安全判据只有一份实现才不会漂。
+//!
+//! # 安全判据（每条都有恶意样本测试，见 `tests/safety.rs`）
+//!
+//! | 威胁 | 做法 |
+//! |------|------|
+//! | 路径穿越（`../x`、`/etc/x`、`C:\x`、`a\..\b`、`file:ads`） | 条目名过 [`normalize_file`]（第一检，平台无关的七条规则），再过 `zip` crate 的 `enclosed_name()`（第二检，**按 Windows 规则**解析盘符/ADS/保留设备名）；任一拒绝即整包拒绝 |
+//! | 符号链接条目 | `unix_mode()` 的 `S_IFLNK` 位命中即拒绝（Windows 上无合法用途；解压器会把目标当内容写出来） |
+//! | 条目数爆炸 | [`PackLimits::max_entries`]，打开时按中央目录长度先判 |
+//! | 解压体积爆炸（zip 炸弹） | [`PackLimits::max_uncompressed_bytes`] 累计 + [`PackLimits::max_entry_bytes`] 单条目；**读取时**再按实际读出的字节数封顶（中央目录里声明的大小可以撒谎） |
+//! | 同名条目（`./a` 与 `a` 规整后撞车） | 规整后的名字重复即拒绝 |
+//!
+//! **两条检查各补一条对方没有的规则**（谁也不能省）：
+//!
+//! - 第一检管**平台无关**的形状：空名、`\0`、`\`、`:`、前导 `/`、任何 `..` 段。
+//!   `enclosed_name()` 在这一点上更松——它允许"深度 0 处的根目录"，也就是 `"/etc/passwd"`
+//!   会返回 `Some("/etc/passwd")`，绝对路径必须由我们先干掉。
+//! - 第二检管 **Win32 命名空间**：DOS 设备名（`CON` / `NUL` / `AUX` / `COM1..9` / `LPT1..9`）、
+//!   结尾的点或空格（`a.`、`a `）、`< > " | ? *` 与控制字符。这些第一检全放行，而它们会让
+//!   落盘时撞到设备、或与另一个名字等价。第二检只在 **Windows 宿主**上生效（`zip` 的
+//!   `cfg(windows)` 分支），所以 `tests/safety.rs` 里对应的用例也是 `#[cfg(windows)]`。
+//!
+//! 也就是说：`CON` / `NUL` 这类在 Windows 上**是拦的**（由第二检），非 Windows 宿主上不拦
+//! （那里它们只是普通文件名，拦了反而拒掉合法包）。
+
+use std::cell::RefCell;
+use std::collections::HashMap;
+use std::fs::File;
+use std::io::Read;
+use std::path::{Path, PathBuf};
+
+use serde_json::Value;
+use zip::ZipArchive;
+
+use super::error::{PackError, PackResult};
+use super::manifest::OverrideFile;
+use super::path::normalize_dir;
+use crate::download::types::HashAlgo;
+use crate::download::verify::{self, Hasher};
+
+pub mod entry;
+pub mod limits;
+mod open;
+
+pub use entry::PackEntryInfo;
+pub use limits::{
+    PackLimits, ReadBudget, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_ENTRY_BYTES,
+    DEFAULT_MAX_UNCOMPRESSED_BYTES,
+};
+
+use limits::read_capped;
+
+/// 输入来源。
+pub(super) enum Source {
+    /// 目录（MultiMC 实例、已解开的包）。
+    Dir,
+    /// zip（`.zip` / `.mrpack`）。`RefCell` 让只读方法能取 `&mut ZipArchive`（解压需要）。
+    Zip(RefCell<ZipArchive<File>>),
+}
+
+/// 一个已校验的整合包输入（目录或 zip）。
+pub struct PackArchive {
+    root: PathBuf,
+    source: Source,
+    entries: Vec<PackEntryInfo>,
+    index: HashMap<String, usize>,
+    limits: PackLimits,
+}
+
+impl std::fmt::Debug for PackArchive {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("PackArchive")
+            .field("root", &self.root)
+            .field(
+                "source",
+                &match self.source {
+                    Source::Dir => "dir",
+                    Source::Zip(_) => "zip",
+                },
+            )
+            .field("entries", &self.entries.len())
+            .finish()
+    }
+}
+
+impl PackArchive {
+    /// 打开一个目录或 zip，按 [`PackLimits::default`] 校验。
+    pub fn open_default(path: impl AsRef<Path>) -> PackResult<Self> {
+        Self::open(path, PackLimits::default())
+    }
+
+    /// 打开一个目录或 zip，按给定限额校验。
+    ///
+    /// 校验是**全量**的：打开成功就说明整包的条目名都过了两道穿越检查、没有符号链接、
+    /// 条数与体积都在限额内。后续读取不再需要重复判断来源是否恶意。
+    pub fn open(path: impl AsRef<Path>, limits: PackLimits) -> PackResult<Self> {
+        let root = path.as_ref().to_path_buf();
+        let metadata = std::fs::symlink_metadata(&root)
+            .map_err(|error| PackError::io(format!("打不开整合包 {}：{error}", root.display())))?;
+        if metadata.file_type().is_symlink() {
+            return Err(PackError::symlink(format!(
+                "整合包本身是符号链接：{}",
+                root.display()
+            )));
+        }
+        if metadata.is_dir() {
+            Self::open_dir(root, limits)
+        } else {
+            Self::open_zip(root, limits)
+        }
+    }
+
+    /// 输入路径。
+    #[must_use]
+    pub fn root(&self) -> &Path {
+        &self.root
+    }
+
+    /// 是否目录输入。
+    #[must_use]
+    pub fn is_dir_source(&self) -> bool {
+        matches!(self.source, Source::Dir)
+    }
+
+    /// 全部条目（目录输入按名字排序，zip 输入保持中央目录顺序）。
+    #[must_use]
+    pub fn entries(&self) -> &[PackEntryInfo] {
+        &self.entries
+    }
+
+    /// 按规整名查一条。
+    #[must_use]
+    pub fn entry(&self, name: &str) -> Option<&PackEntryInfo> {
+        self.index.get(name).map(|slot| &self.entries[*slot])
+    }
+
+    /// 有没有这个条目（探测器用：只问存不存在，不读内容）。
+    #[must_use]
+    pub fn has_entry(&self, name: &str) -> bool {
+        self.index.contains_key(name)
+    }
+
+    /// 读一个条目；不存在返回 `Ok(None)`。
+    pub fn read(&self, name: &str) -> PackResult<Option<Vec<u8>>> {
+        let Some(entry) = self.entry(name) else {
+            return Ok(None);
+        };
+        if entry.is_dir {
+            return Ok(None);
+        }
+        match &self.source {
+            Source::Dir => {
+                let path = self.root.join(&entry.raw);
+                let bytes = std::fs::read(&path).map_err(|error| {
+                    PackError::io(format!("读 {} 失败：{error}", path.display()))
+                })?;
+                Ok(Some(bytes))
+            }
+            Source::Zip(archive) => {
+                let mut archive = archive.borrow_mut();
+                let mut reader = archive
+                    .by_name(&entry.raw)
+                    .map_err(|error| PackError::metadata(format!("解压 {name} 失败：{error}")))?;
+                let bytes = read_capped(&mut reader, self.limits.max_entry_bytes, None, name)?;
+                Ok(Some(bytes))
+            }
+        }
+    }
+
+    /// 按 UTF-8 读文本条目。
+    pub fn read_text(&self, name: &str) -> PackResult<Option<String>> {
+        let Some(bytes) = self.read(name)? else {
+            return Ok(None);
+        };
+        String::from_utf8(bytes)
+            .map(Some)
+            .map_err(|error| PackError::metadata(format!("{name} 不是 UTF-8 文本：{error}")))
+    }
+
+    /// 读 JSON 条目；不存在返回 `Ok(None)`。
+    pub fn read_json(&self, name: &str) -> PackResult<Option<Value>> {
+        let Some(text) = self.read_text(name)? else {
+            return Ok(None);
+        };
+        let value = serde_json::from_str(&text)
+            .map_err(|error| PackError::metadata(format!("{name} 不是合法 JSON：{error}")))?;
+        Ok(Some(value))
+    }
+
+    /// 算一个条目的 SHA-1；不存在返回 `Ok(None)`。
+    ///
+    /// 单条读取只受 [`PackLimits::max_entry_bytes`] 约束；要跨条目累计限额的批量读取
+    /// 请用 [`Self::override_files`]，或自己建 [`ReadBudget`] 交给 [`Self::override_files_with`]。
+    pub fn sha1(&self, name: &str) -> PackResult<Option<String>> {
+        self.sha1_with(name, None)
+    }
+
+    /// 算 SHA-1 并从 `budget` 里扣减实际读出的字节（批量读取用）。
+    fn sha1_with(&self, name: &str, budget: Option<&ReadBudget>) -> PackResult<Option<String>> {
+        let Some(entry) = self.entry(name) else {
+            return Ok(None);
+        };
+        if entry.is_dir {
+            return Ok(None);
+        }
+        match &self.source {
+            Source::Dir => {
+                let path = self.root.join(&entry.raw);
+                let digest = verify::digest_file(&path, HashAlgo::Sha1).map_err(|error| {
+                    PackError::io(format!("算 {} 的 SHA-1 失败：{error}", path.display()))
+                })?;
+                Ok(Some(digest))
+            }
+            Source::Zip(archive) => {
+                let mut archive = archive.borrow_mut();
+                let mut reader = archive
+                    .by_name(&entry.raw)
+                    .map_err(|error| PackError::metadata(format!("解压 {name} 失败：{error}")))?;
+                let mut hasher = Hasher::new(HashAlgo::Sha1);
+                let mut total = 0_u64;
+                let mut buffer = [0_u8; 64 * 1024];
+                loop {
+                    let read = reader
+                        .read(&mut buffer)
+                        .map_err(|error| PackError::io(format!("读 {name} 失败：{error}")))?;
+                    if read == 0 {
+                        break;
+                    }
+                    total += read as u64;
+                    if total > self.limits.max_entry_bytes {
+                        return Err(PackError::limits(format!(
+                            "{name} 实际解压超过单条目上限 {}",
+                            self.limits.max_entry_bytes
+                        )));
+                    }
+                    if let Some(budget) = budget {
+                        budget.spend(read as u64, name)?;
+                    }
+                    hasher.update(&buffer[..read]);
+                }
+                Ok(Some(hasher.finish()))
+            }
+        }
+    }
+
+    /// 收集一个覆盖目录下的文件（相对该目录的路径 + SHA-1 + 字节数），按路径排序。
+    ///
+    /// 目录不存在时返回空表——"包没带 overrides"不是错误。
+    ///
+    /// 这是**唯一会批量解压的 API**，所以它自己持有一个累计预算
+    /// （`PackLimits::max_uncompressed_bytes`），本次调用内逐条按实际读出的字节扣减：
+    /// 声明大小撒谎的包不会靠"很多条各自合规"把 CPU 时间耗光（r1 p3-4）。
+    ///
+    /// **额度是"每次调用一份"，不是"整包一份"**（r2 p3-b）：格式读者若对多个覆盖目录各调一次
+    /// （mrpack 会连调三次：`overrides` / `client-overrides` / `server-overrides`），理论上限
+    /// 是 `max_uncompressed_bytes × 调用次数`。要整包共用一份额度，就自己建 [`ReadBudget`]
+    /// 并走 [`Self::override_files_with`]；`open` 阶段的"声明总量"仍然是整包只判一次。
+    pub fn override_files(&self, dir: &str) -> PackResult<Vec<OverrideFile>> {
+        let budget = ReadBudget::new(self.limits.max_uncompressed_bytes);
+        self.override_files_with(dir, &budget)
+    }
+
+    /// 同 [`Self::override_files`]，但用调用方给的累计预算（M111 想与别处的解压共用额度时用）。
+    pub fn override_files_with(
+        &self,
+        dir: &str,
+        budget: &ReadBudget,
+    ) -> PackResult<Vec<OverrideFile>> {
+        let dir = normalize_dir(dir)?;
+        let prefix = format!("{dir}/");
+        let mut collected = Vec::new();
+        for entry in &self.entries {
+            if entry.is_dir || !entry.name.starts_with(&prefix) {
+                continue;
+            }
+            let relative = &entry.name[prefix.len()..];
+            if relative.is_empty() {
+                continue;
+            }
+            let sha1 = self
+                .sha1_with(&entry.name, Some(budget))?
+                .unwrap_or_default();
+            collected.push(OverrideFile {
+                path: relative.to_string(),
+                sha1,
+                size: entry.size,
+            });
+        }
+        collected.sort_by(|left, right| left.path.cmp(&right.path));
+        Ok(collected)
+    }
+}
diff --git a/crates/core/src/addon/pack/archive/entry.rs b/crates/core/src/addon/pack/archive/entry.rs
new file mode 100644
index 0000000..852c26a
--- /dev/null
+++ b/crates/core/src/addon/pack/archive/entry.rs
@@ -0,0 +1,30 @@
+//! 一条规整过的包内条目。
+
+/// 一条规整过的包内条目。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PackEntryInfo {
+    pub(in crate::addon::pack::archive) name: String,
+    pub(in crate::addon::pack::archive) raw: String,
+    pub(in crate::addon::pack::archive) size: u64,
+    pub(in crate::addon::pack::archive) is_dir: bool,
+}
+
+impl PackEntryInfo {
+    /// 规整后的相对路径（`/` 分隔，无前导斜杠、无 `.`/`..` 段）。
+    #[must_use]
+    pub fn name(&self) -> &str {
+        &self.name
+    }
+
+    /// 声明/实测的字节数（目录条目为 0）。
+    #[must_use]
+    pub const fn size(&self) -> u64 {
+        self.size
+    }
+
+    /// 是否是目录条目。
+    #[must_use]
+    pub const fn is_dir(&self) -> bool {
+        self.is_dir
+    }
+}
diff --git a/crates/core/src/addon/pack/archive/limits.rs b/crates/core/src/addon/pack/archive/limits.rs
new file mode 100644
index 0000000..03dbc11
--- /dev/null
+++ b/crates/core/src/addon/pack/archive/limits.rs
@@ -0,0 +1,167 @@
+//! 读取限额：条目数 / 解压总体积 / 单条目，以及两处封顶实现。
+//!
+//! # 两阶段限额（打开 vs 读取）
+//!
+//! 打开阶段（[`check_limits`]）只能拿**中央目录声明的大小**做判断——它会撒谎。
+//! 因此读取阶段还有第二道：单条目按实际读出字节封顶（[`read_capped`]），批量读取
+//! （[`super::PackArchive::override_files`]）再按**累计实际字节**从 [`ReadBudget`] 里扣减。
+//! 没有预算的批量读取等于把 `max_uncompressed_bytes` 降级成"每条单独算"——一个 2 万条目、
+//! 每条声明 1 字节却解出几十 MiB 的包能把 CPU/时间耗在这里（r1 p3-4）。
+
+use std::cell::Cell;
+use std::io::Read;
+
+use super::super::error::{PackError, PackResult};
+
+/// 默认条目数上限（一个巨型整合包 ≈ 数千条，2 万条已经很宽）。
+pub const DEFAULT_MAX_ENTRIES: usize = 20_000;
+/// 默认解压总体积上限（512 MiB；`.mrpack` 的 `overrides` 通常几十 MiB）。
+pub const DEFAULT_MAX_UNCOMPRESSED_BYTES: u64 = 512 * 1024 * 1024;
+/// 默认单条目上限（64 MiB；最大的 mod 也不过十几 MiB）。
+pub const DEFAULT_MAX_ENTRY_BYTES: u64 = 64 * 1024 * 1024;
+
+/// 包读取限额。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct PackLimits {
+    /// 条目数上限。
+    pub max_entries: usize,
+    /// 解压总体积上限。
+    pub max_uncompressed_bytes: u64,
+    /// 单条目上限。
+    pub max_entry_bytes: u64,
+}
+
+impl PackLimits {
+    /// 三档显式给值（测试与"可疑包"复查用）。
+    #[must_use]
+    pub const fn new(
+        max_entries: usize,
+        max_uncompressed_bytes: u64,
+        max_entry_bytes: u64,
+    ) -> Self {
+        Self {
+            max_entries,
+            max_uncompressed_bytes,
+            max_entry_bytes,
+        }
+    }
+}
+
+impl Default for PackLimits {
+    fn default() -> Self {
+        Self {
+            max_entries: DEFAULT_MAX_ENTRIES,
+            max_uncompressed_bytes: DEFAULT_MAX_UNCOMPRESSED_BYTES,
+            max_entry_bytes: DEFAULT_MAX_ENTRY_BYTES,
+        }
+    }
+}
+
+/// 一次批量读取的**累计**预算（读取阶段，按实际读出的字节扣减）。
+///
+/// 作用域是"拿到它的那次扫描"：`PackArchive::override_files` 每次调用新建一份，
+/// 所以要跨多次调用共享额度（例如整包只给一份 `max_uncompressed_bytes`），
+/// 必须由调用方自建一个并交给 `override_files_with`（r2 p3-b）。
+///
+/// 为什么需要它：中央目录声明的大小可以撒谎，单个条目也被限制在
+/// [`PackLimits::max_entry_bytes`]，但"很多条各自合规"累起来仍可能远超
+/// `max_uncompressed_bytes`。批量读取（`override_files`）持有一个预算，边读边扣。
+#[derive(Debug)]
+pub struct ReadBudget {
+    remaining: Cell<u64>,
+}
+
+impl ReadBudget {
+    /// 按总预算新建。
+    #[must_use]
+    pub fn new(limit: u64) -> Self {
+        Self {
+            remaining: Cell::new(limit),
+        }
+    }
+
+    /// 还剩多少字节。
+    #[must_use]
+    pub fn remaining(&self) -> u64 {
+        self.remaining.get()
+    }
+
+    /// 扣减一次实际读出的字节数；超额报 `pack_limits`。
+    ///
+    /// 超额时预算**照样扣到 0**（这些字节已经从流里读出来了），后续调用会继续失败——
+    /// 不给"失败一次、下次又能读一点"的机会。
+    pub(super) fn spend(&self, bytes: u64, name: &str) -> PackResult<()> {
+        let remaining = self.remaining.get();
+        self.remaining.set(remaining.saturating_sub(bytes));
+        if bytes > remaining {
+            return Err(PackError::limits(format!(
+                "{name} 之后累计解压超过上限（本次还需 {bytes} 字节，预算已用尽）"
+            )));
+        }
+        Ok(())
+    }
+}
+
+/// 累计与单条目限额检查（打开阶段）。
+pub(super) fn check_limits(
+    limits: &PackLimits,
+    total: &mut u64,
+    size: u64,
+    name: &str,
+    seen: usize,
+) -> PackResult<()> {
+    if size > limits.max_entry_bytes {
+        return Err(PackError::limits(format!(
+            "条目 {name} 声明 {} 字节，超过单条目上限 {}",
+            size, limits.max_entry_bytes
+        )));
+    }
+    *total = total.saturating_add(size);
+    if *total > limits.max_uncompressed_bytes {
+        return Err(PackError::limits(format!(
+            "解压总体积超过上限 {} 字节（累计到 {total}）",
+            limits.max_uncompressed_bytes
+        )));
+    }
+    if seen >= limits.max_entries {
+        return Err(PackError::limits(format!(
+            "条目数超过上限 {}",
+            limits.max_entries
+        )));
+    }
+    Ok(())
+}
+
+/// 带封顶的读：中央目录里声明的大小可以撒谎，这里按**实际读出的字节**封顶。
+///
+/// 给了 `budget` 就同时从累计预算里扣（批量读取）；单条读取给 `None`，
+/// 只受 [`PackLimits::max_entry_bytes`] 约束。
+pub(super) fn read_capped(
+    reader: &mut impl Read,
+    cap: u64,
+    budget: Option<&ReadBudget>,
+    name: &str,
+) -> PackResult<Vec<u8>> {
+    let mut bytes = Vec::new();
+    let mut buffer = [0_u8; 64 * 1024];
+    let mut total = 0_u64;
+    loop {
+        let read = reader
+            .read(&mut buffer)
+            .map_err(|error| PackError::io(format!("读 {name} 失败：{error}")))?;
+        if read == 0 {
+            break;
+        }
+        total += read as u64;
+        if total > cap {
+            return Err(PackError::limits(format!(
+                "{name} 实际解压超过单条目上限 {cap}"
+            )));
+        }
+        if let Some(budget) = budget {
+            budget.spend(read as u64, name)?;
+        }
+        bytes.extend_from_slice(&buffer[..read]);
+    }
+    Ok(bytes)
+}
diff --git a/crates/core/src/addon/pack/archive/open.rs b/crates/core/src/addon/pack/archive/open.rs
new file mode 100644
index 0000000..e91b6c4
--- /dev/null
+++ b/crates/core/src/addon/pack/archive/open.rs
@@ -0,0 +1,158 @@
+//! 打开与首轮校验：目录遍历 / zip 中央目录扫描，两道穿越检查、符号链接、限额都在这里。
+
+use std::cell::RefCell;
+use std::collections::HashMap;
+use std::fs::File;
+use std::path::PathBuf;
+
+use zip::ZipArchive;
+
+use super::entry::PackEntryInfo;
+use super::limits::{check_limits, PackLimits};
+use super::{PackArchive, Source};
+use crate::addon::pack::error::{PackError, PackResult};
+use crate::addon::pack::path::{has_trailing_slash, normalize_file};
+
+impl PackArchive {
+    pub(super) fn open_dir(root: PathBuf, limits: PackLimits) -> PackResult<Self> {
+        let mut entries = Vec::new();
+        let mut total: u64 = 0;
+        // 栈式遍历：不递归，避免深层目录把栈打穿。
+        let mut pending = vec![String::new()];
+        while let Some(relative) = pending.pop() {
+            let dir = if relative.is_empty() {
+                root.clone()
+            } else {
+                root.join(&relative)
+            };
+            let mut children = std::fs::read_dir(&dir)
+                .map_err(|error| PackError::io(format!("读目录 {} 失败：{error}", dir.display())))?
+                .collect::<Result<Vec<_>, _>>()
+                .map_err(PackError::from)?;
+            children.sort_by_key(std::fs::DirEntry::file_name);
+            for child in children {
+                let file_name =
+                    child
+                        .file_name()
+                        .to_str()
+                        .map(str::to_string)
+                        .ok_or_else(|| {
+                            PackError::metadata(format!(
+                                "包内文件名不是 UTF-8：{}",
+                                child.path().display()
+                            ))
+                        })?;
+                let raw = if relative.is_empty() {
+                    file_name
+                } else {
+                    format!("{relative}/{file_name}")
+                };
+                let file_type = child
+                    .file_type()
+                    .map_err(|error| PackError::io(format!("读 {} 类型失败：{error}", raw)))?;
+                if file_type.is_symlink() {
+                    return Err(PackError::symlink(format!("整合包里有符号链接条目：{raw}")));
+                }
+                let name = normalize_file(&raw)?;
+                if file_type.is_dir() {
+                    check_limits(&limits, &mut total, 0, &name, entries.len())?;
+                    pending.push(name.clone());
+                    entries.push(PackEntryInfo {
+                        name,
+                        raw,
+                        size: 0,
+                        is_dir: true,
+                    });
+                    continue;
+                }
+                if !file_type.is_file() {
+                    continue;
+                }
+                let size = child
+                    .metadata()
+                    .map_err(|error| PackError::io(format!("读 {raw} 大小失败：{error}")))?
+                    .len();
+                check_limits(&limits, &mut total, size, &name, entries.len())?;
+                entries.push(PackEntryInfo {
+                    name,
+                    raw,
+                    size,
+                    is_dir: false,
+                });
+            }
+        }
+        entries.sort_by(|left, right| left.name.cmp(&right.name));
+        Self::finish(root, Source::Dir, entries, limits)
+    }
+
+    pub(super) fn open_zip(root: PathBuf, limits: PackLimits) -> PackResult<Self> {
+        let file = File::open(&root)
+            .map_err(|error| PackError::io(format!("打开 {} 失败：{error}", root.display())))?;
+        let mut archive = ZipArchive::new(file)
+            .map_err(|error| PackError::metadata(format!("不是可读的 zip：{error}")))?;
+        if archive.len() > limits.max_entries {
+            return Err(PackError::limits(format!(
+                "zip 条目数 {} 超过上限 {}",
+                archive.len(),
+                limits.max_entries
+            )));
+        }
+        let mut entries = Vec::with_capacity(archive.len());
+        let mut total: u64 = 0;
+        for index in 0..archive.len() {
+            let entry = archive.by_index(index).map_err(|error| {
+                PackError::metadata(format!("读第 {index} 个条目失败：{error}"))
+            })?;
+            let Ok(raw) = entry.name() else {
+                return Err(PackError::metadata(format!(
+                    "第 {index} 个条目名编码不合法"
+                )));
+            };
+            let raw = raw.to_string();
+            let is_dir = entry.is_dir() || has_trailing_slash(&raw);
+            if entry.is_symlink() {
+                return Err(PackError::symlink(format!("zip 里有符号链接条目：{raw}")));
+            }
+            let name = normalize_file(&raw)?;
+            // 第二检：zip crate 按 Windows 规则再解析一遍（盘符 / ADS / 保留设备名）。
+            if entry.enclosed_name().is_none() {
+                return Err(PackError::traversal(format!(
+                    "zip 条目名过不了 enclosed_name 检查：{raw}"
+                )));
+            }
+            let size = if is_dir { 0 } else { entry.size() };
+            check_limits(&limits, &mut total, size, &name, entries.len())?;
+            entries.push(PackEntryInfo {
+                name,
+                raw,
+                size,
+                is_dir,
+            });
+        }
+        Self::finish(root, Source::Zip(RefCell::new(archive)), entries, limits)
+    }
+
+    fn finish(
+        root: PathBuf,
+        source: Source,
+        entries: Vec<PackEntryInfo>,
+        limits: PackLimits,
+    ) -> PackResult<Self> {
+        let mut index = HashMap::with_capacity(entries.len());
+        for (slot, entry) in entries.iter().enumerate() {
+            if index.insert(entry.name.clone(), slot).is_some() {
+                return Err(PackError::metadata(format!(
+                    "包里有规整后重名的条目：{}",
+                    entry.name
+                )));
+            }
+        }
+        Ok(Self {
+            root,
+            source,
+            entries,
+            index,
+            limits,
+        })
+    }
+}
diff --git a/crates/core/src/addon/pack/curseforge.rs b/crates/core/src/addon/pack/curseforge.rs
new file mode 100644
index 0000000..e1e6365
--- /dev/null
+++ b/crates/core/src/addon/pack/curseforge.rs
@@ -0,0 +1,339 @@
+//! CurseForge 格式：`manifest.json` + `overrides/`。
+//!
+//! # 形状（A 级来源：HMCL `CurseManifest.java` / `CurseManifestFile.java`，见 analyse/05 §2.2）
+//!
+//! ```jsonc
+//! {
+//!   "manifestType": "minecraftModpack", "manifestVersion": 1,
+//!   "name": "…", "version": "1.0.0", "author": "…",
+//!   "overrides": "overrides",
+//!   "minecraft": {"version": "1.20.1", "modLoaders": [{"id": "forge-47.2.0", "primary": true}]},
+//!   "files": [{"projectID": 238222, "fileID": 5102025, "required": true}]
+//! }
+//! ```
+//!
+//! 关键缺口（**模型如实记录，不假装有**）：
+//!
+//! - `files[]` **没有路径、没有 URL、没有哈希**。路径要按项目 `classId` 猜（`mods/` /
+//!   `resourcepacks/` / `shaderpacks/`），文件名要按 ForgeCDN 规则或 API 补——这正是 D10 §2
+//!   两阶段补全要补的东西，属于 M111，不在本模块。所以 [`PackFile::path`] 读出来是 `None`。
+//! - `minecraft.modLoaders[].id` 只认 `forge-` / `neoforge-` / `fabric-` / `quilt-` 前缀
+//!   （CurseForge 没有 Quilt 的正规表达方式）；不认识的 id **原样保留**在
+//!   [`PackLoader::raw`]，写回时逐字还原。
+//! - 只有一个 `required` 布尔 → 客户端/服务端同值；导出时 `client == Optional` 或
+//!   `disabled` 即 `required: false`。`client`/`server` 分侧语义 CF 表达不了（mrpack 专属）。
+//! - **跨格式导出不完整**（M112 的活）：`modLoaders[].id` 只对 CF 来源是合法形状；
+//!   MultiMC 的 `net.fabricmc.fabric-loader` / 非加载器组件会被逐字写进去（CF 不认）；
+//!   `overrides` 字段会照抄模型里的目录名（从 MultiMC 转过来是 `.minecraft`）。
+//!   按 CF 语义 `overrides` 只是 zip 内**前缀**，导入器把该前缀下的内容铺到游戏目录，
+//!   所以内容不会丢；但"前缀目录本身要不要跟着拷一层"取决于导入器实现（Prism/ULL 的实例根
+//!   本身就叫 `.minecraft` 时可能多出一层）。同一份模型只有 `read` 出来的那个格式才保证往返。
+//!
+//! CF 的**文件指纹**（`MurmurHash2-32` + 空白过滤）是导出侧「能否被远程替代」的判据，见
+//! [`fingerprint`]：它是"CF 格式知识"，不属于导出流程，所以留在这里而不是 `addon::export`。
+
+pub mod fingerprint;
+
+use serde::Deserialize;
+use serde_json::{json, Map, Value};
+
+use super::archive::PackArchive;
+use super::error::{PackError, PackResult};
+use super::format::PackFormat;
+use super::manifest::{
+    merge_unknown, EnvSupport, PackFile, PackLoader, PackManifest, PackOverrides, PackSide,
+};
+use super::path::normalize_dir;
+
+/// 格式 id。
+pub const ID: &str = "curseforge";
+/// 清单入口名。
+pub const METADATA_ENTRY: &str = "manifest.json";
+/// `manifestType` 的固定值。
+pub const MARKER: &str = "minecraftModpack";
+/// 默认覆盖目录名。
+pub const DEFAULT_OVERRIDES: &str = "overrides";
+
+/// 单例（进注册表用）。
+pub static CURSEFORGE: CurseForge = CurseForge;
+
+/// CurseForge 格式的值类型实现。
+#[derive(Debug, Clone, Copy, Default)]
+pub struct CurseForge;
+
+/// `manifest.json` 的原始形状（未知字段落 `extra`）。
+#[derive(Debug, Default, Deserialize)]
+struct RawManifest {
+    #[serde(rename = "manifestType", default)]
+    manifest_type: Option<String>,
+    #[serde(rename = "manifestVersion", default)]
+    manifest_version: Option<i64>,
+    #[serde(default)]
+    name: Option<String>,
+    #[serde(default)]
+    version: Option<String>,
+    #[serde(default)]
+    author: Option<String>,
+    #[serde(default)]
+    overrides: Option<String>,
+    #[serde(default)]
+    minecraft: Option<RawMinecraft>,
+    #[serde(default)]
+    files: Vec<RawFile>,
+    #[serde(flatten)]
+    extra: Map<String, Value>,
+}
+
+/// `minecraft` 对象。
+#[derive(Debug, Default, Deserialize)]
+struct RawMinecraft {
+    #[serde(default)]
+    version: Option<String>,
+    #[serde(rename = "modLoaders", default)]
+    mod_loaders: Vec<RawLoader>,
+    #[serde(flatten)]
+    extra: Map<String, Value>,
+}
+
+/// `minecraft.modLoaders[]` 的一条。
+#[derive(Debug, Default, Deserialize)]
+struct RawLoader {
+    #[serde(default)]
+    id: Option<String>,
+    #[serde(default)]
+    primary: bool,
+    #[serde(flatten)]
+    extra: Map<String, Value>,
+}
+
+/// `files[]` 的一条。
+#[derive(Debug, Default, Deserialize)]
+struct RawFile {
+    #[serde(rename = "projectID", default)]
+    project_id: Option<i64>,
+    #[serde(rename = "fileID", default)]
+    file_id: Option<i64>,
+    #[serde(default = "default_required")]
+    required: bool,
+    #[serde(flatten)]
+    extra: Map<String, Value>,
+}
+
+/// CF 的 `required` 缺省是 `true`（老包可能不写）。
+const fn default_required() -> bool {
+    true
+}
+
+impl PackFormat for CurseForge {
+    fn id(&self) -> &'static str {
+        ID
+    }
+
+    fn label(&self) -> &'static str {
+        "CurseForge"
+    }
+
+    fn metadata_entry(&self) -> Option<&'static str> {
+        Some(METADATA_ENTRY)
+    }
+
+    fn detect(&self, pack: &PackArchive) -> PackResult<Option<&'static str>> {
+        // 文件不存在 ≠ 包坏了：没有 `manifest.json` 就是"不是本格式"。
+        let Some(value) = pack.read_json(METADATA_ENTRY)? else {
+            return Ok(None);
+        };
+        // 文件在、但不是对象 = 形状坏了（`pack_metadata`），不是"不认识"（r1 p3-2）。
+        let object = value
+            .as_object()
+            .ok_or_else(|| PackError::metadata(format!("{METADATA_ENTRY} 存在但不是 JSON 对象")))?;
+        let matched = match object.get("manifestType").and_then(Value::as_str) {
+            // 有标记：只认固定值（`manifest.json` 这名字太泛，光凭名字不能认领）。
+            Some(kind) => kind == MARKER,
+            // 没有标记的老包：要求形状对得上（有 minecraft 对象 + files 数组）。
+            None => {
+                object.get("minecraft").is_some_and(Value::is_object)
+                    && object.get("files").is_some_and(Value::is_array)
+            }
+        };
+        Ok(matched.then_some(METADATA_ENTRY))
+    }
+
+    fn check_overrides(&self, manifest: &PackManifest) -> PackResult<()> {
+        // CF 只有**一个** `overrides` 目录，且清单里只有一个字段能声明它 ⇒ 只表达得了
+        // 一个 Both 侧组。Client/Server 分侧是 mrpack 的东西，这里宁可拒也不猜（r1 p2-1）。
+        let mut both = 0_usize;
+        for group in &manifest.overrides {
+            if group.side != PackSide::Both {
+                return Err(PackError::unsupported(format!(
+                    "CurseForge 只有一个 overrides 目录，表达不了 {} 侧的覆盖内容（{} 个文件）",
+                    group.side.as_str(),
+                    group.files.len()
+                ))
+                .with_hint("先按侧合并（或去掉不该带的组）再导出；分侧目录映射属 M112"));
+            }
+            both += 1;
+        }
+        if both > 1 {
+            return Err(PackError::unsupported(
+                "CurseForge 只有一个 overrides 目录字段，模型里却有多个 Both 侧覆盖组",
+            )
+            .with_hint("把它们合成一个组再导出；目录名映射属 M112"));
+        }
+        Ok(())
+    }
+
+    fn read(&self, pack: &PackArchive) -> PackResult<PackManifest> {
+        let value = pack
+            .read_json(METADATA_ENTRY)?
+            .ok_or_else(|| PackError::metadata(format!("包里没有 {METADATA_ENTRY}")))?;
+        let raw: RawManifest = serde_json::from_value(value)
+            .map_err(|error| PackError::metadata(format!("{METADATA_ENTRY} 形状不符：{error}")))?;
+        if let Some(kind) = &raw.manifest_type {
+            if kind != MARKER {
+                return Err(PackError::unsupported(format!(
+                    "{METADATA_ENTRY} 的 manifestType 是 {kind:?}，不是 {MARKER:?}"
+                )));
+            }
+        }
+        let name = raw
+            .name
+            .filter(|name| !name.trim().is_empty())
+            .ok_or_else(|| PackError::metadata(format!("{METADATA_ENTRY} 缺 name")))?;
+        let minecraft = raw.minecraft.unwrap_or_default();
+        let game_version = minecraft
+            .version
+            .filter(|version| !version.trim().is_empty())
+            .ok_or_else(|| PackError::metadata(format!("{METADATA_ENTRY} 缺 minecraft.version")))?;
+
+        let loaders = minecraft
+            .mod_loaders
+            .into_iter()
+            .map(|loader| {
+                let mut parsed = PackLoader::parse_curse(
+                    loader.id.as_deref().unwrap_or_default(),
+                    loader.primary,
+                );
+                parsed.extra = loader.extra;
+                parsed
+            })
+            .collect();
+
+        let files = raw
+            .files
+            .into_iter()
+            .map(|file| {
+                let env = if file.required {
+                    EnvSupport::Required
+                } else {
+                    EnvSupport::Optional
+                };
+                PackFile {
+                    project_id: file.project_id,
+                    file_id: file.file_id,
+                    client: env,
+                    server: env,
+                    extra: file.extra,
+                    ..PackFile::default()
+                }
+            })
+            .collect();
+
+        // CF 的 `overrides` 字段缺省就是 `"overrides"`（规范默认值），`render` 也总会写它；
+        // 读侧因此**永远**产出一个 Both 侧组，读写才对称（dir 不存在时 files 为空表）。
+        let overrides_dir = raw
+            .overrides
+            .as_deref()
+            .filter(|dir| !dir.trim().is_empty())
+            .unwrap_or(DEFAULT_OVERRIDES);
+        let overrides_dir = normalize_dir(overrides_dir)?;
+        let overrides = vec![PackOverrides {
+            files: pack.override_files(&overrides_dir)?,
+            dir: overrides_dir,
+            side: PackSide::Both,
+        }];
+
+        Ok(PackManifest {
+            name,
+            version: raw.version,
+            author: raw.author,
+            summary: None,
+            format_version: raw.manifest_version,
+            game: None,
+            minecraft: Some(game_version),
+            loaders,
+            files,
+            overrides,
+            extra: raw.extra,
+            minecraft_extra: minecraft.extra,
+        })
+    }
+
+    fn render(&self, manifest: &PackManifest) -> PackResult<String> {
+        let game_version = manifest.minecraft.as_deref().ok_or_else(|| {
+            PackError::metadata("CurseForge 清单需要 minecraft.version，模型里没有")
+        })?;
+        let mut root = Map::new();
+        root.insert("manifestType".into(), json!(MARKER));
+        root.insert(
+            "manifestVersion".into(),
+            json!(manifest.format_version.unwrap_or(1)),
+        );
+        root.insert("name".into(), json!(manifest.name));
+        if let Some(version) = &manifest.version {
+            root.insert("version".into(), json!(version));
+        }
+        if let Some(author) = &manifest.author {
+            root.insert("author".into(), json!(author));
+        }
+        let overrides_dir = manifest
+            .overrides_for(PackSide::Both)
+            .map_or(DEFAULT_OVERRIDES, |group| group.dir.as_str());
+        root.insert("overrides".into(), json!(overrides_dir));
+
+        let mut minecraft = Map::new();
+        minecraft.insert("version".into(), json!(game_version));
+        let mut mod_loaders = Vec::with_capacity(manifest.loaders.len());
+        for loader in &manifest.loaders {
+            let id = loader.curse_id_for(Some(game_version)).ok_or_else(|| {
+                PackError::unsupported(format!(
+                    "CurseForge 表达不了这条加载器依赖：raw={:?} kind={:?} version={:?}",
+                    loader.raw, loader.kind, loader.version
+                ))
+            })?;
+            let mut object = Map::new();
+            object.insert("id".into(), json!(id));
+            object.insert("primary".into(), json!(loader.primary));
+            merge_unknown(&mut object, &loader.extra);
+            mod_loaders.push(Value::Object(object));
+        }
+        minecraft.insert("modLoaders".into(), Value::Array(mod_loaders));
+        merge_unknown(&mut minecraft, &manifest.minecraft_extra);
+        root.insert("minecraft".into(), Value::Object(minecraft));
+
+        let mut files = Vec::with_capacity(manifest.files.len());
+        for file in &manifest.files {
+            let (Some(project_id), Some(file_id)) = (file.project_id, file.file_id) else {
+                return Err(PackError::unsupported(format!(
+                    "CurseForge 的 files[] 需要 projectID/fileID，这条没有（path={:?}）",
+                    file.path
+                ))
+                .with_hint("先用 CurseForge API 补全条目再导出，或改用 Modrinth 格式"));
+            };
+            let mut object = Map::new();
+            object.insert("projectID".into(), json!(project_id));
+            object.insert("fileID".into(), json!(file_id));
+            // CF 只有一个 `required` 布尔：`optional` 与"禁用"都只能落到 `false`
+            // （Prism 也是用 `required: false` 表达禁用的，见 M115 调研 §6）。
+            object.insert(
+                "required".into(),
+                json!(!(file.client.is_optional() || file.disabled)),
+            );
+            merge_unknown(&mut object, &file.extra);
+            files.push(Value::Object(object));
+        }
+        root.insert("files".into(), Value::Array(files));
+
+        merge_unknown(&mut root, &manifest.extra);
+        serde_json::to_string_pretty(&Value::Object(root)).map_err(Into::into)
+    }
+}
diff --git a/crates/core/src/addon/pack/curseforge/fingerprint.rs b/crates/core/src/addon/pack/curseforge/fingerprint.rs
new file mode 100644
index 0000000..6184b91
--- /dev/null
+++ b/crates/core/src/addon/pack/curseforge/fingerprint.rs
@@ -0,0 +1,262 @@
+//! CurseForge 文件指纹（`MurmurHash2-32` + 空白字节过滤），导出侧的「能否被远程替代」判据之一。
+//!
+//! # 算法（A 级规范缺失，这里是 B 级实现 + 双向验证）
+//!
+//! ```text
+//! data        = 原文件去掉所有 0x09 / 0x0A / 0x0D / 0x20 字节
+//! fingerprint = MurmurHash2_32(data, seed = 1, len = data 的长度)
+//! ```
+//!
+//! 三条容易写错的点，逐条钉住：
+//!
+//! 1. **长度用过滤后的长度**参与初始态（`h = seed ^ len`），不是原文件长度；
+//! 2. **seed 恒为 1**（MurmurHash2 的默认 seed 是 `0x9747b28c`，那是别的调用方的约定）；
+//! 3. 过滤是**逐字节**的，只在 0x09/0x0A/0x0D/0x20 上生效——不是"去空白"（`0x0B` 竖tab、
+//!    `0x0C` 换页都保留）。
+//!
+//! # 来源与验证
+//!
+//! CurseForge 官方只公开 `POST /v1/fingerprints/432` 端点，**没有公开算法**（A 级规范不存在）。
+//! 这里的实现对齐 B 级参考 `HMCL CurseForgeRemoteAddonRepository.calculateFingerprint`
+//! 与 `MurmurHash2.hash32(byte[], int, int)`（SMHasher `MurmurHash2.cpp` 的忠实转写）。
+//!
+//! **双向验证**（`tests` 模块）：一组固定输入的金标准值由一份**独立的 Java 实现**（HMCL 两份
+//! 源码的逐行移植，不在本仓库内）算出后写死在这里；Rust 侧同时跑「一次性字节序」与「流式文件」
+//! 两条路径，两条都要与金标准相等。所以这一层是"两套实现 + 两个入口"的四向对齐，而不是自证。
+//! 仍未验的部分：**真实 CF 文件**的官方指纹（要网络 + `x-api-key`，本任务环境离线）。
+//!
+//! # 哨兵值 `811513880`
+//!
+//! 这个值会误命中（HMCL issue #4597 的临时规避）：无论文件是什么，只要算出这个数就不能当成
+//! "已找到"。判据写成 [`is_sentinel`]，由调用方（导出管线）在查表前短路。
+
+use std::fs::File;
+use std::io::{self, Read};
+use std::path::Path;
+
+/// 误命中的哨兵指纹（HMCL issue #4597）。命中时按「查不到」处理。
+pub const SENTINEL: u32 = 811_513_880;
+
+/// 被过滤掉的四个字节：水平制表、换行、回车、空格。
+pub const FILTERED: [u8; 4] = [0x09, 0x0a, 0x0d, 0x20];
+
+/// 指纹查表时是否该按「没找到」处理。
+#[must_use]
+pub const fn is_sentinel(fingerprint: u32) -> bool {
+    fingerprint == SENTINEL
+}
+
+/// 这个字节参与计算吗（`0x09` / `0x0A` / `0x0D` / `0x20` 不参与）。
+#[must_use]
+pub const fn keeps(byte: u8) -> bool {
+    !matches!(byte, 0x09 | 0x0a | 0x0d | 0x20)
+}
+
+/// 对**内存里的一份内容**算指纹（过滤 + 一次性哈希）。
+///
+/// 小文件与测试用；大文件请用 [`fingerprint_file`]（两遍流式读，不把整份读进内存）。
+#[must_use]
+pub fn fingerprint_bytes(bytes: &[u8]) -> u32 {
+    let filtered: Vec<u8> = bytes.iter().copied().filter(|byte| keeps(*byte)).collect();
+    murmur2(&filtered)
+}
+
+/// 对一个**文件**算指纹：两遍流式读（先数过滤后长度，再喂哈希）。
+///
+/// MurmurHash2 的初始态要事先知道总长度，所以必须两遍；这里不把文件读进内存（mod jar 可以
+/// 有几百 MB，整包导出要对每个文件算一次）。
+pub fn fingerprint_file(path: &Path) -> io::Result<u32> {
+    let mut filtered_length = 0_u64;
+    let mut buffer = vec![0_u8; 1024 * 1024];
+    let mut file = File::open(path)?;
+    loop {
+        let read = file.read(&mut buffer)?;
+        if read == 0 {
+            break;
+        }
+        filtered_length += buffer[..read].iter().filter(|byte| keeps(**byte)).count() as u64;
+    }
+
+    // 长度参数是 u32（MurmurHash2-32 的初始态），超了要报错而不是截断。
+    let length = u32::try_from(filtered_length).map_err(|_| {
+        io::Error::new(
+            io::ErrorKind::InvalidData,
+            format!("文件过滤后仍有 {filtered_length} 字节，超出指纹长度参数（u32）上限"),
+        )
+    })?;
+    let mut hasher = Stream::new(length, 1);
+    file = File::open(path)?;
+    loop {
+        let read = file.read(&mut buffer)?;
+        if read == 0 {
+            break;
+        }
+        hasher.update(&buffer[..read]);
+    }
+    Ok(hasher.finish())
+}
+
+/// MurmurHash2 32 位，seed 固定 1（CurseForge 的约定）。
+///
+/// 实现是 SMHasher `MurmurHash2.cpp` 的形状：按 4 字节小端块混合，尾部 1–3 字节按小端补齐后
+/// 再乘一次；收尾两次移位混合。**不在这里做字节过滤**（调用方先过滤，见 [`fingerprint_bytes`]）。
+#[must_use]
+pub fn murmur2(data: &[u8]) -> u32 {
+    const M: u32 = 0x5bd1_e995;
+    const R: u32 = 24;
+
+    let mut h = 1_u32 ^ (data.len() as u32);
+    let blocks = data.len() / 4;
+    for index in 0..blocks {
+        let mut k = u32::from_le_bytes([
+            data[index * 4],
+            data[index * 4 + 1],
+            data[index * 4 + 2],
+            data[index * 4 + 3],
+        ]);
+        k = k.wrapping_mul(M);
+        k ^= k >> R;
+        k = k.wrapping_mul(M);
+        h = h.wrapping_mul(M);
+        h ^= k;
+    }
+    let tail = &data[blocks * 4..];
+    if !tail.is_empty() {
+        let mut packed = 0_u32;
+        for (shift, byte) in tail.iter().enumerate() {
+            packed |= u32::from(*byte) << (8 * shift);
+        }
+        h ^= packed;
+        h = h.wrapping_mul(M);
+    }
+    h ^= h >> 13;
+    h = h.wrapping_mul(M);
+    h ^= h >> 15;
+    h
+}
+
+/// 流式 MurmurHash2：长度先知道，字节可以分任意多段喂进来。
+struct Stream {
+    hash: u32,
+    tail: u32,
+    tail_len: u32,
+}
+
+impl Stream {
+    const fn new(length: u32, seed: u32) -> Self {
+        Self {
+            hash: seed ^ length,
+            tail: 0,
+            tail_len: 0,
+        }
+    }
+
+    fn update(&mut self, bytes: &[u8]) {
+        const M: u32 = 0x5bd1_e995;
+        const R: u32 = 24;
+        for byte in bytes {
+            if !keeps(*byte) {
+                continue;
+            }
+            self.tail |= u32::from(*byte) << (8 * self.tail_len);
+            self.tail_len += 1;
+            if self.tail_len == 4 {
+                let mut k = self.tail;
+                k = k.wrapping_mul(M);
+                k ^= k >> R;
+                k = k.wrapping_mul(M);
+                self.hash = self.hash.wrapping_mul(M);
+                self.hash ^= k;
+                self.tail = 0;
+                self.tail_len = 0;
+            }
+        }
+    }
+
+    fn finish(mut self) -> u32 {
+        const M: u32 = 0x5bd1_e995;
+        if self.tail_len != 0 {
+            self.hash ^= self.tail;
+            self.hash = self.hash.wrapping_mul(M);
+        }
+        self.hash ^= self.hash >> 13;
+        self.hash = self.hash.wrapping_mul(M);
+        self.hash ^= self.hash >> 15;
+        self.hash
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// 金标准值由一份独立的 Java 实现（HMCL `MurmurHash2.hash32` + `calculateFingerprint` 的
+    /// 逐行移植）对同一批输入算出。改了算法这两列会同时红——这就是"双向验证"的用处。
+    const GOLDEN: &[(&str, &[u8], u32)] = &[
+        ("空文件", b"", 1_540_447_798),
+        ("只有空白", b" \t\r\n \t\r\n", 1_540_447_798),
+        (
+            "夹具 jar 存根",
+            b"PK\x03\x04 hand-made jar stub",
+            489_715_614,
+        ),
+        ("混入空白", b"\x00\t\n\r AB\tC\n\r \x7f\xff", 3_734_724_774),
+        (
+            "ascii 36",
+            b"abcdefghijklmnopqrstuvwxyz0123456789",
+            3_026_742_571,
+        ),
+    ];
+
+    fn pattern(length: usize) -> Vec<u8> {
+        (0..length).map(|index| (index & 0xff) as u8).collect()
+    }
+
+    #[test]
+    fn matches_the_independent_implementation() {
+        for (label, bytes, expected) in GOLDEN {
+            assert_eq!(fingerprint_bytes(bytes), *expected, "{label}（一次性路径）");
+        }
+        assert_eq!(
+            fingerprint_bytes(&pattern(512)),
+            3_451_065_282,
+            "pattern-512"
+        );
+        assert_eq!(fingerprint_bytes(&pattern(5)), 813_985_283, "pattern-5");
+        assert_eq!(fingerprint_bytes(&pattern(7)), 2_174_351_703, "pattern-7");
+    }
+
+    #[test]
+    fn filtered_length_enters_the_initial_state() {
+        // 原文件长度 8、过滤后长度 0：与空文件同值。用原长度当 len 会得到另一个数（这里不是）。
+        assert_eq!(fingerprint_bytes(b" \t\r\n \t\r\n"), fingerprint_bytes(b""),);
+        assert_ne!(fingerprint_bytes(b"aaaaaaaa"), fingerprint_bytes(b"aaaa"),);
+    }
+
+    #[test]
+    fn only_the_four_documented_bytes_are_dropped() {
+        assert!(!keeps(0x09) && !keeps(0x0a) && !keeps(0x0d) && !keeps(0x20));
+        // 竖 tab、换页、NUL 都保留：过滤是四个字节，不是"去空白"。
+        assert!(keeps(0x0b) && keeps(0x0c) && keeps(0x00));
+    }
+
+    #[test]
+    fn streaming_and_one_shot_agree_at_every_split() {
+        let data = pattern(64);
+        let expected = fingerprint_bytes(&data);
+        for split in 0..=data.len() {
+            let mut hasher =
+                Stream::new(data.iter().filter(|byte| keeps(**byte)).count() as u32, 1);
+            hasher.update(&data[..split]);
+            hasher.update(&data[split..]);
+            assert_eq!(hasher.finish(), expected, "split={split}");
+        }
+    }
+
+    #[test]
+    fn sentinel_is_treated_as_missing() {
+        assert!(is_sentinel(SENTINEL));
+        assert!(!is_sentinel(0));
+        assert!(!is_sentinel(SENTINEL + 1));
+    }
+}
diff --git a/crates/core/src/addon/pack/error.rs b/crates/core/src/addon/pack/error.rs
new file mode 100644
index 0000000..92ab28d
--- /dev/null
+++ b/crates/core/src/addon/pack/error.rs
@@ -0,0 +1,161 @@
+//! 整合包失败分类：**可诊断**比"报了个错"重要。
+//!
+//! 每一类都对应导入链路上一个**不同的处置动作**（M111 据此分级）：
+//!
+//! | 大类 | 稳定码 | 谁该负责 |
+//! |------|--------|----------|
+//! | [`PackErrorKind::Unsupported`] | `pack_unsupported` | 换格式 / 让用户手工处理（没格式认领、或模型表达不了该格式） |
+//! | [`PackErrorKind::Metadata`] | `pack_metadata` | 包本身坏了（JSON 形状不符、哈希缺失），重试无意义 |
+//! | [`PackErrorKind::Traversal`] | `pack_traversal` | **拒绝**，且不写任何文件（恶意包） |
+//! | [`PackErrorKind::Symlink`] | `pack_symlink` | **拒绝**（符号链接条目在 Windows 上无合法用途） |
+//! | [`PackErrorKind::Limits`] | `pack_limits` | **拒绝**（条数/体积超限，zip 炸弹防线） |
+//! | [`PackErrorKind::Io`] | `pack_io` | 环境问题，可重试 |
+//!
+//! 文案与日志分离：`message()` 给人看，`kind().as_str()` 进事件流与 `--json`。
+
+use std::fmt;
+
+/// 整合包失败的大类。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PackErrorKind {
+    /// 没有格式认领这份包，或模型里的信息不足以写成该格式。
+    Unsupported,
+    /// 清单 JSON 坏了 / 形状不符 / 必需字段缺失。
+    Metadata,
+    /// 包内路径穿越（绝对路径、`..` 上跳、盘符、ADS、反斜杠分隔）。
+    Traversal,
+    /// zip 里有符号链接条目。
+    Symlink,
+    /// 条目数 / 解压体积超过限额。
+    Limits,
+    /// 本地 IO。
+    Io,
+}
+
+impl PackErrorKind {
+    /// 稳定字符串 id（进 `--json` 的 `error.code` 与日志，**不要改名**）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Unsupported => "pack_unsupported",
+            Self::Metadata => "pack_metadata",
+            Self::Traversal => "pack_traversal",
+            Self::Symlink => "pack_symlink",
+            Self::Limits => "pack_limits",
+            Self::Io => "pack_io",
+        }
+    }
+}
+
+/// 整合包错误：大类 + 人读说明 + 可选下一步提示。
+#[derive(Debug, Clone)]
+pub struct PackError {
+    kind: PackErrorKind,
+    message: String,
+    hint: Option<String>,
+}
+
+impl PackError {
+    /// 构造。
+    #[must_use]
+    pub fn new(kind: PackErrorKind, message: impl Into<String>) -> Self {
+        Self {
+            kind,
+            message: message.into(),
+            hint: None,
+        }
+    }
+
+    /// 没格式认领 / 模型表达不了该格式。
+    #[must_use]
+    pub fn unsupported(message: impl Into<String>) -> Self {
+        Self::new(PackErrorKind::Unsupported, message)
+    }
+
+    /// 清单形状不对 / 必填字段缺失。
+    #[must_use]
+    pub fn metadata(message: impl Into<String>) -> Self {
+        Self::new(PackErrorKind::Metadata, message)
+    }
+
+    /// 路径穿越。
+    #[must_use]
+    pub fn traversal(message: impl Into<String>) -> Self {
+        Self::new(PackErrorKind::Traversal, message)
+    }
+
+    /// 符号链接条目。
+    #[must_use]
+    pub fn symlink(message: impl Into<String>) -> Self {
+        Self::new(PackErrorKind::Symlink, message)
+    }
+
+    /// 超过限额。
+    #[must_use]
+    pub fn limits(message: impl Into<String>) -> Self {
+        Self::new(PackErrorKind::Limits, message)
+    }
+
+    /// 本地 IO。
+    #[must_use]
+    pub fn io(message: impl Into<String>) -> Self {
+        Self::new(PackErrorKind::Io, message)
+    }
+
+    /// 补一句提示。
+    #[must_use]
+    pub fn with_hint(mut self, hint: impl Into<String>) -> Self {
+        self.hint = Some(hint.into());
+        self
+    }
+
+    /// 大类。
+    #[must_use]
+    pub const fn kind(&self) -> PackErrorKind {
+        self.kind
+    }
+
+    /// 人读说明。
+    #[must_use]
+    pub fn message(&self) -> &str {
+        &self.message
+    }
+
+    /// 下一步提示。
+    #[must_use]
+    pub fn hint(&self) -> Option<&str> {
+        self.hint.as_deref()
+    }
+}
+
+impl fmt::Display for PackError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str(&self.message)
+    }
+}
+
+impl std::error::Error for PackError {}
+
+impl From<std::io::Error> for PackError {
+    fn from(error: std::io::Error) -> Self {
+        Self::io(error.to_string())
+    }
+}
+
+impl From<zip::result::ZipError> for PackError {
+    fn from(error: zip::result::ZipError) -> Self {
+        match error {
+            zip::result::ZipError::FileNotFound => Self::io("包内条目不存在"),
+            other => Self::metadata(format!("zip 读取失败：{other}")),
+        }
+    }
+}
+
+impl From<serde_json::Error> for PackError {
+    fn from(error: serde_json::Error) -> Self {
+        Self::metadata(format!("JSON 解析失败：{error}"))
+    }
+}
+
+/// `pack` 模块内的结果别名。
+pub type PackResult<T> = Result<T, PackError>;
diff --git a/crates/core/src/addon/pack/format.rs b/crates/core/src/addon/pack/format.rs
new file mode 100644
index 0000000..43cb9d4
--- /dev/null
+++ b/crates/core/src/addon/pack/format.rs
@@ -0,0 +1,391 @@
+//! 格式扩展点：[`PackFormat`] trait + 注册表 [`PackRegistry`] + **写死的探测优先级**。
+//!
+//! # 可扩展性的判据是测试，不是文档
+//!
+//! `tests/extend.rs` 里有一个只有几十行的假格式 `ToyFormat`（单文件、`toy.json` 当清单）：
+//! 它**只加一行注册**（`PackRegistry::builtin().with(&TOY)`）就能被探测、读取、渲染、写回，
+//! 不改模型、不改 CurseForge / Modrinth / MultiMC 任何一行。这是"社区标准加一个格式"的
+//! 最小代价证明。
+//!
+//! # 探测优先级写死在这里，顺序由注册表 `Vec` 位置决定
+//!
+//! [`PackRegistry::builtin`] 的顺序：**CurseForge → Modrinth → MultiMC**。
+//!
+//! - 跟 HMCL 对这三种格式的相对次序一致（`ModpackHelper.readModpackManifest`：Curse 在
+//!   Modrinth 前、Modrinth 在 MultiMC 前），减少与社区工具的行为差异；
+//! - 每个格式的 `detect` 都带**形状校验**（CF 要 `manifestType: minecraftModpack`、mrpack 要
+//!   `formatVersion` + `files` 数组、MultiMC 要 `components` 非空），所以名字很泛的
+//!   `manifest.json` 不会把 `.mrpack` 抢走；
+//! - 同一份包同时命中多个格式时，[`PackMatch::also_matched`] 会记下其余命中，调用方可以提示
+//!   "这包不标准"——不做静默判定，也不做自动合并；
+//! - [`PackRegistry::register`] 追加到**末尾**（= 最低优先级），所以测试里改一行顺序就能
+//!   证明"优先级来自注册表顺序"（`tests/detect.rs` 有一条反序注册的用例）。
+//!
+//! # 写：默认实现**只保证同格式往返**（这条是给 M111/M112 的边界声明）
+//!
+//! 默认实现（[`PackFormat::write`]）替所有格式做同一件事：写清单 entry（[`PackFormat::render`]
+//! 的产物）+ 把 `manifest.overrides` 的 `(dir, side, files)` **原样**搬进 zip。因此新格式只要
+//! 实现 `metadata_entry` + `render` 就同时获得导出能力；只读格式（MultiMC）不实现
+//! `metadata_entry`，写会得到明确的 `crate::addon::pack::error::PackErrorKind::Unsupported`。
+//!
+//! **它不做目标格式映射**，具体缺四件事（都属于 M112，别以为这一层已经做了）：
+//!
+//! 1. **目录名映射**：mrpack 的覆盖目录名由 `side` 决定（`overrides` / `client-overrides` /
+//!    `server-overrides`），CF 只有一个 `overrides`（名字由清单给）。`check_overrides` 只保证
+//!    "布局表达不了就报错"，不负责改名；
+//! 2. **`side` 合并/分派**：CF 表达不了 Client/Server 分侧，现在是**拒**而不是合并；
+//! 3. **加载器 id 规范化**：CF 要 `forge-47.2.0` / `fabric-0.15.11`，mrpack 要
+//!    `forge` / `fabric-loader` 这类键。`render` 只按模型里的 `raw`/`kind` 写，跨格式转出来的
+//!    id 形态可能不被目标平台接受（尤其 MultiMC 的 `net.fabricmc.fabric-loader`）；
+//! 4. **`extra` 不按格式分桶**：模型只有一份未知字段集合，跨格式导出会把别的格式的未知键
+//!    一起带过去。
+//!
+//! 换句话说：`X.read` → `X.write` 是可靠往返（有逐字段相等的测试）；`X.read` → `Y.write`
+//! 要么被 `check_overrides` 拒掉，要么"结构合法但语义不完整"。**要跨格式导出，先做映射。**
+//!
+//! # 映射层已经在了（M112）
+//!
+//! [`crate::addon::export`] 就是那层映射：它把实例目录扫成模型（覆盖目录统一到 `overrides/`、
+//! 禁用位落成路径后缀 `.disabled`、`dependencies` 从实例快照取），再用
+//! [`PackPayload::with_sources`] 把"包内条目名 → 实例里的源文件"交给本模块写盘。所以本文件
+//! 仍然不做映射（那是格式之上的事），但"跨格式导出无路可走"已经不再成立。
+
+use std::fmt::Debug;
+use std::fs::File;
+use std::io::Write;
+use std::path::{Path, PathBuf};
+
+use super::archive::PackArchive;
+use super::curseforge;
+use super::error::{PackError, PackResult};
+use super::manifest::PackManifest;
+use super::modrinth;
+use super::multimc;
+use super::path::{normalize_dir, normalize_file};
+
+mod payload;
+
+/// 导出时的覆盖内容来源在 [`payload`] 子模块里（`payload.rs`，与本文件拆开是为了守 400 行）：
+/// [`PackPayload::metadata_only`] 只写清单、[`PackPayload::from_root`] 按
+/// `<root>/<dir>/<path>` 取文件、[`PackPayload::with_sources`] 按**包内条目名**查表
+/// （跨格式导出 / 从实例导出用，M112）。
+pub use payload::PackPayload;
+
+/// 一种整合包格式（导入 + 导出的全部能力都在这里）。
+pub trait PackFormat: Debug + Send + Sync {
+    /// 稳定字符串 id（进日志/事件/CLI 参数，**不要改名**）。
+    fn id(&self) -> &'static str;
+
+    /// 人读名称。
+    fn label(&self) -> &'static str;
+
+    /// 清单文件在包内的入口名（`Some` = 本格式可导出）。
+    fn metadata_entry(&self) -> Option<&'static str> {
+        None
+    }
+
+    /// 这份输入是不是本格式；命中时返回**证据**（凭哪个条目认领的），未命中返回 `None`。
+    ///
+    /// **必须带形状校验**，不能只看文件名存在：`manifest.json` 这种泛名到处都是。
+    /// "选谁"不是格式自己的事——排序与歧义在 [`PackRegistry::detect`] 那一层做
+    /// （返回 [`PackMatch`]，带 `also_matched` 与本次命中的证据）。
+    ///
+    /// **清单在、但读不出来**时必须返回 `Err`（`pack_metadata` 一类），不要用
+    /// `.ok().flatten()` 吞掉：那样"包坏了"会被上层报成"没有格式认领"，M111 的失败分级
+    /// 就会把可以重下文件的包当成不支持（r1 p3-2）。
+    fn detect(&self, pack: &PackArchive) -> PackResult<Option<&'static str>>;
+
+    /// 读成中间模型。
+    fn read(&self, pack: &PackArchive) -> PackResult<PackManifest>;
+
+    /// 把模型渲染成清单 JSON（未知字段在这里回写）。
+    fn render(&self, manifest: &PackManifest) -> PackResult<String>;
+
+    /// 这份模型的**覆盖目录集合**能不能被本格式表达（默认 `write` 在写第一个字节前调用）。
+    ///
+    /// 默认实现不限制（"目录名原样写进包里"对同格式往返是对的）。凡是有**固定目录布局**
+    /// 的格式必须收紧：mrpack 的三个目录由 `side` 决定，CF 只有一个 `overrides` 目录。
+    /// 不收紧的后果不是报错而是**静默丢内容**——把一份 MultiMC 实例写成 `.mrpack` 时，
+    /// 文件会落在 `.minecraft/...`，而 mrpack 导入器只认
+    /// `overrides/` / `client-overrides/` / `server-overrides/`，读出来 mods 数量为 0（r1 p2-1）。
+    fn check_overrides(&self, manifest: &PackManifest) -> PackResult<()> {
+        let _ = manifest;
+        Ok(())
+    }
+
+    /// 导出一个整包（清单 + 覆盖内容）。
+    ///
+    /// 默认实现做四件事：①只读格式直接拒；②[`Self::check_overrides`] 挡跨格式导出；
+    /// ③`render` 出清单；④写进**临时文件**再 `rename` 到 `target`（失败不留半个包）。
+    ///
+    /// # 只保证同格式往返（写给 M111/M112）
+    ///
+    /// 默认 `write` 的覆盖目录策略是"把 `manifest.overrides` 里 `(dir, side, files)`
+    /// 原样再打一遍"，也就是"读出来的包按原样打包"。它**不做**目标格式的目录映射、`side`
+    /// 分派、加载器 id 规范化，也**不按格式分桶** `extra`。所以：
+    ///
+    /// - 同格式往返（`X.read` → `X.write`）可靠，有逐字段相等的测试；
+    /// - 跨格式导出（`X.read` → `Y.write`）在布局不同时被 [`Self::check_overrides`] 拒掉；
+    ///   但"布局恰好兼容、语义不兼容"的部分（加载器 id 形态、`extra` 里别的格式的未知键）
+    ///   **仍会被原样带过去**——那是 M112 的活，这一层不替谁做映射。
+    fn write(
+        &self,
+        manifest: &PackManifest,
+        payload: PackPayload<'_>,
+        target: &Path,
+    ) -> PackResult<()> {
+        let Some(entry) = self.metadata_entry() else {
+            return Err(PackError::unsupported(format!(
+                "格式 {}（{}）只支持读取，不支持导出",
+                self.id(),
+                self.label()
+            ))
+            .with_hint("导出请选 Modrinth（.mrpack）或 CurseForge 格式"));
+        };
+        // 先判"能不能表达"，再碰磁盘：跨格式导出宁可报错，也不产出空包。
+        self.check_overrides(manifest)?;
+        // 模型可能来自外部构造：搬内容前把每条路径重查一遍。
+        manifest.check_paths()?;
+        let json = self.render(manifest)?;
+        // 临时文件 + rename：中途失败时目标路径上不会留下"看起来能用"的半个 zip（r1 p3-1）。
+        let temp = temporary_path(target);
+        match write_container(self.id(), entry, &json, manifest, payload, &temp) {
+            Ok(()) => std::fs::rename(&temp, target).map_err(|error| {
+                let _ = std::fs::remove_file(&temp);
+                PackError::io(format!(
+                    "把 {} 改名成 {} 失败：{error}",
+                    temp.display(),
+                    target.display()
+                ))
+            }),
+            Err(error) => {
+                let _ = std::fs::remove_file(&temp);
+                Err(error)
+            }
+        }
+    }
+}
+
+/// 临时文件路径（与目标同目录，`rename` 才能原子替换）。
+fn temporary_path(target: &Path) -> PathBuf {
+    let mut name = target.file_name().map_or_else(
+        || std::ffi::OsString::from("pack"),
+        std::ffi::OsStr::to_os_string,
+    );
+    name.push(format!(".{}.part", std::process::id()));
+    target.with_file_name(name)
+}
+
+/// 真正写 zip 的那一段（失败了由调用方删临时文件）。
+fn write_container(
+    format_id: &str,
+    entry: &'static str,
+    json: &str,
+    manifest: &PackManifest,
+    payload: PackPayload<'_>,
+    temp: &Path,
+) -> PackResult<()> {
+    let file = File::create(temp)
+        .map_err(|error| PackError::io(format!("创建 {} 失败：{error}", temp.display())))?;
+    let mut writer = zip::ZipWriter::new(file);
+    let options = zip::write::SimpleFileOptions::default()
+        .compression_method(zip::CompressionMethod::Deflated)
+        .unix_permissions(0o644);
+    writer
+        .start_file(entry, options)
+        .map_err(|error| PackError::io(format!("写 {entry} 失败：{error}")))?;
+    writer
+        .write_all(json.as_bytes())
+        .map_err(|error| PackError::io(format!("写 {entry} 失败：{error}")))?;
+    // 未压缩总量封顶在 ZIP64 阈值（≈4 GiB）：Modrinth 官方导出也是这样拒绝的，而不是
+    // 静默截断（HMCL 那边 `(int)` 截断只打 warning 是反面教材）。临时文件由调用方删。
+    let mut total = json.len() as u64;
+    for group in &manifest.overrides {
+        let dir = normalize_dir(&group.dir)?;
+        for override_file in &group.files {
+            let path = normalize_file(&override_file.path)?;
+            let name = format!("{dir}/{path}");
+            let source = match payload.source_for(&name) {
+                Some(source) => source.to_path_buf(),
+                None => {
+                    let Some(root) = payload.root() else {
+                        return Err(PackError::unsupported(format!(
+                            "导出需要覆盖内容（{name}），但既没有来源映射也没有 payload 根目录"
+                        )));
+                    };
+                    root.join(&dir).join(&path)
+                }
+            };
+            let bytes = std::fs::read(&source).map_err(|error| {
+                PackError::io(format!("读覆盖文件 {} 失败：{error}", source.display()))
+            })?;
+            total += bytes.len() as u64;
+            if total >= zip::ZIP64_BYTES_THR {
+                return Err(PackError::limits(format!(
+                    "包体未压缩总量已超过 {} 字节（ZIP64 阈值），拒绝写出一个需要 ZIP64 的整合包",
+                    zip::ZIP64_BYTES_THR
+                ))
+                .with_hint("把超大的覆盖文件移出实例后再导出；mrpack/CF 都不接受 ZIP64"));
+            }
+            writer
+                .start_file(name.clone(), options)
+                .map_err(|error| PackError::io(format!("写 {name} 失败：{error}")))?;
+            writer
+                .write_all(&bytes)
+                .map_err(|error| PackError::io(format!("写 {name} 失败：{error}")))?;
+        }
+    }
+    writer
+        .finish()
+        .map_err(|error| PackError::io(format!("收尾 zip 失败：{error}（格式 {format_id}）")))?;
+    Ok(())
+}
+
+/// 一次探测的结果。
+#[derive(Debug, Clone)]
+pub struct PackMatch {
+    format: &'static dyn PackFormat,
+    evidence: &'static str,
+    also_matched: Vec<&'static str>,
+}
+
+impl PackMatch {
+    /// 选中的格式。
+    #[must_use]
+    pub fn format(&self) -> &'static dyn PackFormat {
+        self.format
+    }
+
+    /// 命中的证据条目名（探测器凭哪个文件认领的，进日志用）。
+    #[must_use]
+    pub fn evidence(&self) -> &'static str {
+        self.evidence
+    }
+
+    /// 同样命中的其它格式 id（探测顺序里排在后面的那些）。
+    #[must_use]
+    pub fn also_matched(&self) -> &[&'static str] {
+        &self.also_matched
+    }
+
+    /// 是否有"多格式同时命中"的歧义（不标准包）。
+    #[must_use]
+    pub fn is_ambiguous(&self) -> bool {
+        !self.also_matched.is_empty()
+    }
+}
+
+/// 格式注册表：**顺序即优先级**。
+#[derive(Debug, Clone, Default)]
+pub struct PackRegistry {
+    formats: Vec<&'static dyn PackFormat>,
+}
+
+impl PackRegistry {
+    /// 一个都没有的注册表（测试"没有格式认领"用）。
+    #[must_use]
+    pub fn empty() -> Self {
+        Self {
+            formats: Vec::new(),
+        }
+    }
+
+    /// 内置三格式，顺序即优先级：CurseForge → Modrinth → MultiMC。
+    #[must_use]
+    pub fn builtin() -> Self {
+        Self {
+            formats: vec![
+                &curseforge::CURSEFORGE,
+                &modrinth::MODRINTH,
+                &multimc::MULTIMC,
+            ],
+        }
+    }
+
+    /// 追加一种格式（追加 = 最低优先级）。加一种格式真的只要这一行。
+    pub fn register(&mut self, format: &'static dyn PackFormat) {
+        self.formats.push(format);
+    }
+
+    /// 链式注册。
+    #[must_use]
+    pub fn with(mut self, format: &'static dyn PackFormat) -> Self {
+        self.register(format);
+        self
+    }
+
+    /// 按优先级列出格式 id。
+    #[must_use]
+    pub fn ids(&self) -> Vec<&'static str> {
+        self.formats.iter().map(|format| format.id()).collect()
+    }
+
+    /// 按 id 找格式。
+    #[must_use]
+    pub fn get(&self, id: &str) -> Option<&'static dyn PackFormat> {
+        self.formats
+            .iter()
+            .copied()
+            .find(|format| format.id() == id)
+    }
+
+    /// 全部命中的格式 id（诊断"这包不标准"用；**只看命中**，单个格式的读错误被忽略——
+    /// 要区分"包坏了"与"不认识"请用 [`Self::detect`]）。
+    #[must_use]
+    pub fn detect_all(&self, pack: &PackArchive) -> Vec<&'static str> {
+        self.formats
+            .iter()
+            .filter(|format| matches!(format.detect(pack), Ok(Some(_))))
+            .map(|format| format.id())
+            .collect()
+    }
+
+    /// 按优先级选第一个命中的格式。
+    ///
+    /// 错误语义（M111 的失败分级依赖这两条的区别）：
+    ///
+    /// - **一个都不命中、但某个格式的清单读不出来** → 返回那个格式的错误
+    ///   （`pack_metadata` 一类：包坏了，换格式也没用）；
+    /// - **一个都不命中、也没有任何格式的清单在场** → `pack_unsupported`
+    ///   （真的不认识这份包）；
+    /// - 命中优先于失败：包里躺着一份别人的坏 `manifest.json` 不影响真的 `.mrpack` 被认出来。
+    pub fn detect(&self, pack: &PackArchive) -> PackResult<PackMatch> {
+        let mut matched: Vec<(&'static dyn PackFormat, &'static str)> = Vec::new();
+        // 命中优先于"某个格式的清单坏了"：包里躺着一份别人的坏 manifest.json 不该毁掉它。
+        let mut failures: Vec<PackError> = Vec::new();
+        for format in self.formats.iter().copied() {
+            match format.detect(pack) {
+                Ok(Some(evidence)) => matched.push((format, evidence)),
+                Ok(None) => {}
+                // 清单在、但读不出来 = 包坏了（`pack_metadata`），不是"不认识这个格式"。
+                Err(error) => failures.push(error),
+            }
+        }
+        if matched.is_empty() {
+            if let Some(error) = failures.into_iter().next() {
+                return Err(error);
+            }
+            let tried = self.ids().join(" / ");
+            return Err(
+                PackError::unsupported(format!("没有格式认领这份整合包（试过：{tried}）"))
+                    .with_hint(
+                        "确认它是 CurseForge manifest.json、Modrinth .mrpack 或 MultiMC 实例",
+                    ),
+            );
+        }
+        let (format, evidence) = matched.remove(0);
+        let also_matched = matched.iter().map(|(other, _)| other.id()).collect();
+        Ok(PackMatch {
+            format,
+            evidence,
+            also_matched,
+        })
+    }
+
+    /// 探测 + 读成模型（导入管线的第一步）。
+    pub fn read(&self, pack: &PackArchive) -> PackResult<(&'static dyn PackFormat, PackManifest)> {
+        let matched = self.detect(pack)?;
+        let manifest = matched.format().read(pack)?;
+        Ok((matched.format(), manifest))
+    }
+}
diff --git a/crates/core/src/addon/pack/format/payload.rs b/crates/core/src/addon/pack/format/payload.rs
new file mode 100644
index 0000000..ca852a7
--- /dev/null
+++ b/crates/core/src/addon/pack/format/payload.rs
@@ -0,0 +1,70 @@
+//! 导出时的覆盖内容来源：[`PackPayload`]。
+//!
+//! # 两种来源
+//!
+//! | 构造 | 用在哪 |
+//! |------|--------|
+//! | [`PackPayload::from_root`] | 同格式往返：包内 `overrides/mods/x.jar` 就是 `<root>/overrides/mods/x.jar` |
+//! | [`PackPayload::with_sources`] | 跨格式 / 从实例导出：包内路径由模型决定，源文件在实例目录的任意位置 |
+//!
+//! 第二种是 M112 需要的形状：实例里的 `mods/x.jar` 要落到包里的 `overrides/mods/x.jar`
+//! （CF 与 mrpack 都是这个前缀），路径**不能靠拼**（拼接只能表达"目录同名"）。所以来源表
+//! 以**包内条目名**为键：`{"overrides/mods/x.jar": <实例>/mods/x.jar}`。
+//!
+//! 查不到映射时退回 `root/dir/path`；两者都没有就报 `pack_unsupported`（不写空内容、不猜）。
+
+use std::collections::BTreeMap;
+use std::path::{Path, PathBuf};
+
+/// 导出时的覆盖内容来源。
+#[derive(Debug, Clone, Copy)]
+pub struct PackPayload<'a> {
+    root: Option<&'a Path>,
+    sources: Option<&'a BTreeMap<String, PathBuf>>,
+}
+
+impl<'a> PackPayload<'a> {
+    /// 只写清单，不搬覆盖内容。
+    #[must_use]
+    pub const fn metadata_only() -> Self {
+        Self {
+            root: None,
+            sources: None,
+        }
+    }
+
+    /// 覆盖内容从 `root` 取（`<root>/<dir>/<path>`，同格式往返用）。
+    #[must_use]
+    pub const fn from_root(root: &'a Path) -> Self {
+        Self {
+            root: Some(root),
+            sources: None,
+        }
+    }
+
+    /// 覆盖内容按**包内条目名**查表（`overrides/mods/x.jar` → 实例里的绝对/相对路径）。
+    ///
+    /// `root` 仍然要给：映射没覆盖到的条目退回 `<root>/<dir>/<path>`，
+    /// 这样"大部分文件原位、少数文件改名"的混合场景不必手写全表。
+    #[must_use]
+    pub const fn with_sources(root: &'a Path, sources: &'a BTreeMap<String, PathBuf>) -> Self {
+        Self {
+            root: Some(root),
+            sources: Some(sources),
+        }
+    }
+
+    /// 来源根目录。
+    #[must_use]
+    pub const fn root(&self) -> Option<&'a Path> {
+        self.root
+    }
+
+    /// 包内条目名 → 源文件（没有来源表或表里没这条时返回 `None`）。
+    #[must_use]
+    pub fn source_for(&self, entry_name: &str) -> Option<&'a Path> {
+        self.sources
+            .and_then(|sources| sources.get(entry_name))
+            .map(PathBuf::as_path)
+    }
+}
diff --git a/crates/core/src/addon/pack/manifest.rs b/crates/core/src/addon/pack/manifest.rs
new file mode 100644
index 0000000..64c4857
--- /dev/null
+++ b/crates/core/src/addon/pack/manifest.rs
@@ -0,0 +1,395 @@
+//! 与格式无关的中间模型 [`PackManifest`]。
+//!
+//! # 为什么要中间模型
+//!
+//! CF 的 `manifest.json` 与 Modrinth 的 `modrinth.index.json` 表达同一件事的方式不同：
+//!
+//! | 概念 | CurseForge | Modrinth `.mrpack` | 模型字段 |
+//! |------|-----------|--------------------|----------|
+//! | 包名 | `name` | `name` | [`PackManifest::name`] |
+//! | 包版本 | `version` | `versionId` | [`PackManifest::version`] |
+//! | 作者 | `author` | **没有** | [`PackManifest::author`] |
+//! | 简介 | **没有** | `summary` | [`PackManifest::summary`] |
+//! | 游戏版本 | `minecraft.version` | `dependencies.minecraft` | [`PackManifest::minecraft`] |
+//! | 加载器 | `minecraft.modLoaders[].id`（`forge-47.2.0`） | `dependencies["forge"] = "47.2.0"` | [`PackManifest::loaders`] |
+//! | 远端文件 | `files[].projectID/fileID`（**无路径、无 URL**） | `files[].path/hashes/downloads/env` | [`PackManifest::files`] |
+//! | 覆盖目录 | `overrides`（目录名由清单给，可任意） | `overrides` + `client-overrides` + `server-overrides` | [`PackManifest::overrides`] |
+//! | 禁用位 | 无（Prism 借 `required: false` 表达） | 路径 `.disabled` 后缀（官方，本仓库采这条） | [`PackFile::disabled`] |
+//! | 多 MC 实例（MultiMC） | — | — | 同上（`.minecraft` 当覆盖目录） |
+//!
+//! 方向不同造成的缺口**不靠"假装字段都在"抹平**，而是显式记录：
+//!
+//! - CF 的 `files[]` 没有路径 → [`PackFile::path`] 是 `Option`，`None` 表示"要靠远端 API 补全"
+//!   （D10 §2 的两阶段补全就是补这个）；写 mrpack 时缺路径即
+//!   `crate::addon::pack::error::PackErrorKind::Unsupported`。
+//! - CF 只有一个 `required` 布尔 → 读成 `client`/`server` 同值，写回时 `client == Optional` 即
+//!   `required = false`；`client`/`server` 不同的条目不适用于 CF 导出（文档写明，不静默降级）。
+//!
+//! # 未知字段不丢（"社区标准加字段不炸"的具体手段）
+//!
+//! 三处 `extra` 用 `serde(flatten)` 接住不认识的 JSON 字段，**原样 Value 保存**，
+//! 各格式的 `render` 再把它们并回去（已知字段优先，冲突时丢弃 extra 里的同名键）：
+//!
+//! - [`PackManifest::extra`]：清单顶层；
+//! - [`PackManifest::minecraft_extra`]：CF `minecraft` 对象内部（mrpack 没有这一层）；
+//! - [`PackFile::extra`] / [`PackFile::env_extra`] / [`PackLoader::extra`]：条目、`env`、加载器条目内部。
+//!
+//! 哈希不按"sha1/sha512 两个字段"建模，而是 [`PackFile::hashes`] 整张表：mrpack 允许
+//! `sha1`/`sha256`/`sha512`/`md5` 同时出现，只留两个字段就会丢信息。
+
+mod entries;
+
+pub use entries::{merge_unknown, OverrideFile, PackFile, PackOverrides};
+
+use std::collections::HashMap;
+
+use serde_json::{Map, Value};
+
+use super::path::normalize_file;
+use crate::addon::LoaderKind;
+
+/// 客户端 / 服务端环境标记（mrpack `env` 的三值，CF 只有 `required` 布尔）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum EnvSupport {
+    /// 必需（mrpack `required` / CF `required: true`）。
+    #[default]
+    Required,
+    /// 可选（mrpack `optional` / CF `required: false`）。
+    ///
+    /// **不是禁用位**：真实语义是"安装时用户可取消勾选"，装回来默认仍然启用。
+    /// 禁用是两回事，在 mrpack 里表达为路径后缀 `.disabled`（见 [`super::PackFile::disabled`]）。
+    Optional,
+    /// 本侧不支持（mrpack `unsupported`；CF 表达不了）。
+    Unsupported,
+}
+
+impl EnvSupport {
+    /// 解析 mrpack 的字符串形式；不认识的返回 `None`（调用方决定报错还是忽略）。
+    #[must_use]
+    pub fn parse(raw: &str) -> Option<Self> {
+        match raw.trim().to_ascii_lowercase().as_str() {
+            "required" => Some(Self::Required),
+            "optional" => Some(Self::Optional),
+            "unsupported" => Some(Self::Unsupported),
+            _ => None,
+        }
+    }
+
+    /// mrpack 的字符串形式。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Required => "required",
+            Self::Optional => "optional",
+            Self::Unsupported => "unsupported",
+        }
+    }
+
+    /// 是否"可以不要"。
+    #[must_use]
+    pub const fn is_optional(self) -> bool {
+        matches!(self, Self::Optional)
+    }
+}
+
+/// 覆盖目录的目标侧（mrpack 用三个目录区分，CF 只有一个）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
+pub enum PackSide {
+    /// 客户端与服务端都要（`overrides` / `.minecraft`）。
+    #[default]
+    Both,
+    /// 只要客户端（`client-overrides`）。
+    Client,
+    /// 只要服务端（`server-overrides`）。
+    Server,
+}
+
+impl PackSide {
+    /// 人读名称（进日志/报告）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Both => "both",
+            Self::Client => "client",
+            Self::Server => "server",
+        }
+    }
+
+    /// mrpack 里这一侧的标准目录名。
+    #[must_use]
+    pub const fn mrpack_dir(self) -> &'static str {
+        match self {
+            Self::Both => "overrides",
+            Self::Client => "client-overrides",
+            Self::Server => "server-overrides",
+        }
+    }
+
+    /// 该侧的覆盖内容对客户端是否生效。
+    #[must_use]
+    pub const fn applies_to_client(self) -> bool {
+        matches!(self, Self::Both | Self::Client)
+    }
+
+    /// 该侧的覆盖内容对服务端是否生效。
+    #[must_use]
+    pub const fn applies_to_server(self) -> bool {
+        matches!(self, Self::Both | Self::Server)
+    }
+}
+
+/// 一个加载器依赖。
+///
+/// `raw` 保留原始标识，读写两侧因此无损：
+/// - CF：`raw = "forge-47.2.0"`，`kind = Forge`，`version = "47.2.0"`；
+/// - mrpack：`raw = "fabric-loader"`，`kind = Fabric`，`version = "0.15.11"`；
+/// - MultiMC：`raw = "net.fabricmc.fabric-loader"`，`kind = Fabric`，`version = "0.15.11"`。
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct PackLoader {
+    /// 原始标识（按格式原样保存）。
+    pub raw: String,
+    /// 规范化加载器种类；不认识的加载器是 `None`（仍然保留 `raw` 与 `version`）。
+    pub kind: Option<LoaderKind>,
+    /// 加载器版本。
+    pub version: Option<String>,
+    /// 是否主加载器（CF `primary`；其它格式取"第一条能认出来的"）。
+    pub primary: bool,
+    /// 该加载器条目的未知字段。
+    pub extra: Map<String, Value>,
+}
+
+impl PackLoader {
+    /// 从 CF 的 `modLoaders[].id`（`forge-47.2.0`）解析。
+    #[must_use]
+    pub fn parse_curse(id: &str, primary: bool) -> Self {
+        let (kind, version) = split_curse_id(id);
+        Self {
+            raw: id.to_string(),
+            kind,
+            version,
+            primary,
+            extra: Map::new(),
+        }
+    }
+
+    /// 从 mrpack `dependencies` 的一条键值解析（`fabric-loader` → `0.15.11`）。
+    #[must_use]
+    pub fn parse_dependency(key: &str, version: &str, primary: bool) -> Self {
+        Self {
+            raw: key.to_string(),
+            kind: parse_kind_key(key),
+            version: Some(version.to_string()),
+            primary,
+            extra: Map::new(),
+        }
+    }
+
+    /// 从 MultiMC 组件 `uid` + `version` 解析（`net.fabricmc.fabric-loader`）。
+    #[must_use]
+    pub fn parse_multimc(uid: &str, version: &str, primary: bool) -> Self {
+        let kind = match uid {
+            "net.fabricmc.fabric-loader" => Some(LoaderKind::Fabric),
+            "org.quiltmc.quilt-loader" => Some(LoaderKind::Quilt),
+            "net.minecraftforge" => Some(LoaderKind::Forge),
+            "net.neoforged" => Some(LoaderKind::NeoForge),
+            _ => None,
+        };
+        Self {
+            raw: uid.to_string(),
+            kind,
+            version: Some(version.to_string()),
+            primary,
+            extra: Map::new(),
+        }
+    }
+
+    /// 写成 CF 的 `id`。
+    ///
+    /// `raw` 非空时**逐字回写**（CF 的 id 是不透明字符串，不认识的加载器也得原样带过去）；
+    /// 只有从别的格式转过来的 `raw` 为空的情况才用 `kind`+`version` 拼。等于
+    /// `curse_id_for(None)`——跨格式导出请用带游戏版本的那个，见 [`Self::curse_id_for`]。
+    #[must_use]
+    pub fn curse_id(&self) -> Option<String> {
+        self.curse_id_for(None)
+    }
+
+    /// 写成 CF 的 `id`，并按 CF 官方导出器的写法处理 **NeoForge 的 MC 前缀特例**。
+    ///
+    /// 证据（A 级 `FlamePackExportTask.cpp:404-410`，转述见 research/18 §8.2）：Prism 的 CF
+    /// 导出在 MC **1.20.1** 上写 `neoforge-1.20.1-<ver>`，其它版本写 `neoforge-<ver>`。
+    /// 原因是 NeoForge 在 1.20.1 上沿用 Forge 的 `47.x` 版本号，不写 MC 版本就分不清代际。
+    /// 读侧（`split_curse_id`）不剥这个前缀——那是 M111 的 `strip_mc_prefix` 的活。
+    #[must_use]
+    pub fn curse_id_for(&self, mc_version: Option<&str>) -> Option<String> {
+        if !self.raw.is_empty() {
+            return Some(self.raw.clone());
+        }
+        let kind = self.kind?;
+        let version = self.version.as_deref()?;
+        if kind == LoaderKind::NeoForge && mc_version == Some("1.20.1") {
+            return Some(format!("{}-1.20.1-{version}", kind.as_str()));
+        }
+        Some(format!("{}-{version}", kind.as_str()))
+    }
+
+    /// 写成 mrpack `dependencies` 的键。
+    ///
+    /// 认得种类时用 Modrinth 的规范拼法（`fabric-loader` / `quilt-loader` / `forge` /
+    /// `neoforge`）——这是 Modrinth 自己的键名约定，CF 的 `forge-47.2.0` 与 MultiMC 的
+    /// `net.fabricmc.fabric-loader` 都靠它翻译过去。种类未知时（社区新加载器）逐字回写 `raw`。
+    #[must_use]
+    pub fn dependency_key(&self) -> String {
+        match self.kind {
+            Some(LoaderKind::Fabric) => "fabric-loader".to_string(),
+            Some(LoaderKind::Quilt) => "quilt-loader".to_string(),
+            Some(kind) => kind.as_str().to_string(),
+            None => self.raw.clone(),
+        }
+    }
+}
+
+/// CF 的 `modLoaders[].id` 里认得上哪些前缀。
+fn split_curse_id(id: &str) -> (Option<LoaderKind>, Option<String>) {
+    for kind in LoaderKind::all() {
+        let prefix = format!("{}-", kind.as_str());
+        if let Some(rest) = id.strip_prefix(&prefix) {
+            if !rest.is_empty() {
+                return (Some(*kind), Some(rest.to_string()));
+            }
+        }
+    }
+    (None, None)
+}
+
+/// mrpack `dependencies` 的键 → 加载器种类（`fabric-loader` / `neo-forge` 两种拼法都认）。
+fn parse_kind_key(key: &str) -> Option<LoaderKind> {
+    let lowered = key.trim().to_ascii_lowercase();
+    let bare = lowered.strip_suffix("-loader").unwrap_or(&lowered);
+    LoaderKind::parse(bare)
+}
+
+/// 与格式无关的整合包模型。
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct PackManifest {
+    /// 包名（CF `name` / mrpack `name`）。
+    pub name: String,
+    /// 包版本（CF `version` / mrpack `versionId`）。
+    pub version: Option<String>,
+    /// 作者（CF `author`；mrpack 没有这一项）。
+    pub author: Option<String>,
+    /// 简介（mrpack `summary`；CF 没有这一项）。
+    pub summary: Option<String>,
+    /// 清单 schema 版本（CF `manifestVersion` / mrpack `formatVersion` / MultiMC `formatVersion`）。
+    pub format_version: Option<i64>,
+    /// 平台标识（mrpack `game`，恒为 `minecraft`；CF 隐式，`None`）。
+    pub game: Option<String>,
+    /// 游戏版本（`1.20.1`）。
+    pub minecraft: Option<String>,
+    /// 加载器依赖集合。
+    pub loaders: Vec<PackLoader>,
+    /// 远端文件条目（不含覆盖目录里的文件）。
+    pub files: Vec<PackFile>,
+    /// 覆盖目录清单。
+    pub overrides: Vec<PackOverrides>,
+    /// 清单顶层的未知字段（原样保存、导出时回写）。
+    pub extra: Map<String, Value>,
+    /// CF `minecraft` 对象里的未知字段（mrpack/MultiMC 没有这一层）。
+    pub minecraft_extra: Map<String, Value>,
+}
+
+impl PackManifest {
+    /// 建一个只有包名的空清单。
+    #[must_use]
+    pub fn new(name: impl Into<String>) -> Self {
+        Self {
+            name: name.into(),
+            ..Self::default()
+        }
+    }
+
+    /// 按目标侧找覆盖目录。
+    #[must_use]
+    pub fn overrides_for(&self, side: PackSide) -> Option<&PackOverrides> {
+        self.overrides.iter().find(|group| group.side == side)
+    }
+
+    /// 覆盖目录里的全部文件，按 `(side, path)` 展平（三方合并要按实例路径查）。
+    pub fn override_files(&self) -> impl Iterator<Item = (PackSide, &OverrideFile)> {
+        self.overrides
+            .iter()
+            .flat_map(|group| group.files.iter().map(move |file| (group.side, file)))
+    }
+
+    /// 某个加载器的依赖（有就返回第一条）。
+    #[must_use]
+    pub fn loader(&self, kind: LoaderKind) -> Option<&PackLoader> {
+        self.loaders.iter().find(|loader| loader.kind == Some(kind))
+    }
+
+    /// 有远端来源的条目（M111 的补全目标）。
+    pub fn remote_files(&self) -> impl Iterator<Item = &PackFile> {
+        self.files.iter().filter(|file| file.is_remote_reachable())
+    }
+
+    /// 校验模型里所有路径安全（导出前必过：模型可能来自外部构造）。
+    ///
+    /// 覆盖目录前缀与文件路径都要过 [`normalize_file`] / [`normalize_dir`] 的同一条规则。
+    pub fn check_paths(&self) -> super::error::PackResult<()> {
+        use super::path::normalize_dir;
+
+        for group in &self.overrides {
+            normalize_dir(&group.dir)?;
+            for file in &group.files {
+                normalize_file(&file.path)?;
+            }
+        }
+        for file in &self.files {
+            if let Some(path) = &file.path {
+                normalize_file(path)?;
+            }
+        }
+        Ok(())
+    }
+
+    /// 撞同一实例路径的覆盖条目：`(路径, 涉及的侧, 条目份数)`，按路径排序。
+    ///
+    /// **两种冲突都要报**（r2 p2-2：上一版按侧去重，把"同侧撞车"这条能力换掉了）：
+    ///
+    /// - **跨侧**：`overrides/`（Both）与 `client-overrides/`（Client）写同一个实例路径——
+    ///   mrpack 唯一的真实冲突。按 `(side, path)` 计数会恒返回空表（两侧键天然不同）。
+    /// - **同侧**：两个同侧组撞同一路径，或一个组里同一路径列了两次（模型被合并时才出现）。
+    ///   按侧去重会把这份重复折叠掉，于是同样"查不出来"。
+    ///
+    /// 判据：`侧数 > 1 || 条份数 > 侧数`（后者即同侧重复）。冲突由导入器决定优先级，
+    /// 本模块只报告、不选边。
+    #[must_use]
+    pub fn duplicate_override_paths(&self) -> Vec<(String, Vec<PackSide>, usize)> {
+        struct Slot {
+            sides: Vec<PackSide>,
+            occurrences: usize,
+        }
+
+        let mut slots: HashMap<&str, Slot> = HashMap::new();
+        for (side, file) in self.override_files() {
+            let slot = slots.entry(file.path.as_str()).or_insert(Slot {
+                sides: Vec::new(),
+                occurrences: 0,
+            });
+            slot.occurrences += 1;
+            if !slot.sides.contains(&side) {
+                slot.sides.push(side);
+            }
+        }
+
+        let mut duplicated: Vec<(String, Vec<PackSide>, usize)> = slots
+            .into_iter()
+            .filter(|(_, slot)| slot.sides.len() > 1 || slot.occurrences > slot.sides.len())
+            .map(|(path, mut slot)| {
+                slot.sides.sort_by_key(|side| side.as_str());
+                (path.to_string(), slot.sides, slot.occurrences)
+            })
+            .collect();
+        duplicated.sort_by(|left, right| left.0.cmp(&right.0));
+        duplicated
+    }
+}
diff --git a/crates/core/src/addon/pack/manifest/entries.rs b/crates/core/src/addon/pack/manifest/entries.rs
new file mode 100644
index 0000000..85be86e
--- /dev/null
+++ b/crates/core/src/addon/pack/manifest/entries.rs
@@ -0,0 +1,155 @@
+//! 条目级模型：远端文件、覆盖目录、以及"未知字段并回"的唯一实现。
+//!
+//! 拆在这里是为了守 400 行上限；对外仍是 [`crate::addon::pack::manifest`] 的一部分
+//! （`manifest` 用 `pub use` 重新导出）。
+
+use std::collections::BTreeMap;
+
+use serde_json::{Map, Value};
+
+use super::{EnvSupport, PackSide};
+
+/// 一个远端文件条目。
+///
+/// CF 只填 `project_id`/`file_id`/`client`/`server`；mrpack 只填 `path`/`hashes`/`downloads`/
+/// `size`/`client`/`server`。两者可以同时存在（例如 M111 补全 CF 条目之后）。
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct PackFile {
+    /// 实例内相对路径（`mods/jei.jar`）。CF 官方清单没有这一项 → `None`。
+    pub path: Option<String>,
+    /// CF `projectID`。
+    pub project_id: Option<i64>,
+    /// CF `fileID`。
+    pub file_id: Option<i64>,
+    /// 摘要表（键名小写：`sha1` / `sha512` / `sha256` / `md5`）。mrpack 要求有 `sha512`。
+    pub hashes: BTreeMap<String, String>,
+    /// 下载候选（mrpack `downloads`，多源；CF 官方清单没有，要靠 CDN 规则或 API 拼）。
+    pub downloads: Vec<String>,
+    /// 文件字节数（mrpack `fileSize`）。
+    pub size: Option<u64>,
+    /// 是否"以禁用态安装"（`.disabled`）。
+    ///
+    /// 社区里 `.disabled` 有三种表达（M115 调研 §字段缺口 2 / §8.1）：
+    /// - 官方 mrpack 导出器：**路径本身带 `.disabled` 后缀**（A 级）；
+    /// - HMCL/D10 旧措辞：去掉后缀，用 `env.client = optional`（B 级，**跨启动器不保真**）；
+    /// - CF：没有原生表达，Prism 借 `required: false`。
+    ///
+    /// **本仓库的定案（tower，M112）**：一律走路径后缀。`env.client=optional` 只是"安装时可
+    /// 取消勾选"，装回来默认仍然启用，不能当禁用；CF 表达不了禁用位，所以禁用文件只能内联进
+    /// `overrides/`（导出管线负责，见 `crate::addon::export`）。
+    pub disabled: bool,
+    /// 客户端支持度。
+    pub client: EnvSupport,
+    /// 服务端支持度。
+    pub server: EnvSupport,
+    /// 该条目的未知字段。
+    pub extra: Map<String, Value>,
+    /// `env` 对象里的未知字段。
+    pub env_extra: Map<String, Value>,
+}
+
+impl PackFile {
+    /// 只带路径的条目（mrpack 侧最简形态）。
+    #[must_use]
+    pub fn with_path(path: impl Into<String>) -> Self {
+        Self {
+            path: Some(path.into()),
+            ..Self::default()
+        }
+    }
+
+    /// 只带 CF 标识的条目。
+    #[must_use]
+    pub fn with_curse(project_id: i64, file_id: i64) -> Self {
+        Self {
+            project_id: Some(project_id),
+            file_id: Some(file_id),
+            ..Self::default()
+        }
+    }
+
+    /// SHA-1（有就返回）。
+    #[must_use]
+    pub fn sha1(&self) -> Option<&str> {
+        self.hashes.get("sha1").map(String::as_str)
+    }
+
+    /// SHA-512（有就返回）。
+    #[must_use]
+    pub fn sha512(&self) -> Option<&str> {
+        self.hashes.get("sha512").map(String::as_str)
+    }
+
+    /// 稳定标识：用于"用户取消勾选某文件"的排除集合，跨版本比对要稳。
+    ///
+    /// 与 HMCL 同构：`curseforge:<projectID>:<fileID>` / `modrinth:<sha512>:<path>`，
+    /// 两者都没有时退回路径。
+    #[must_use]
+    pub fn key(&self) -> String {
+        if let (Some(project), Some(file)) = (self.project_id, self.file_id) {
+            return format!("curseforge:{project}:{file}");
+        }
+        if let (Some(sha512), Some(path)) = (self.sha512(), self.path.as_deref()) {
+            return format!("modrinth:{sha512}:{path}");
+        }
+        self.path.clone().unwrap_or_default()
+    }
+
+    /// 这条目是否有远端下载来源（决定导入时能否自己补齐）。
+    #[must_use]
+    pub fn is_remote_reachable(&self) -> bool {
+        if self.downloads.iter().any(|url| !url.trim().is_empty()) {
+            return true;
+        }
+        self.project_id.is_some() && self.file_id.is_some()
+    }
+}
+
+/// 覆盖目录里的一个文件（三方合并的 `base` 侧：上次整合包给的哈希）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct OverrideFile {
+    /// 相对该覆盖目录的路径（等价于实例内相对路径，例如 `mods/jei.jar`）。
+    pub path: String,
+    /// 内容 SHA-1（读包时现算）。
+    pub sha1: String,
+    /// 字节数。
+    pub size: u64,
+}
+
+/// 一个覆盖目录（`overrides` / `client-overrides` / `server-overrides` / MultiMC 的 `.minecraft`）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PackOverrides {
+    /// 包内目录前缀（`/` 分隔，无尾斜杠）。
+    pub dir: String,
+    /// 目标侧。
+    pub side: PackSide,
+    /// 目录内的文件清单（按路径排序，保证同一份包两次读出的模型相等）。
+    pub files: Vec<OverrideFile>,
+}
+
+impl PackOverrides {
+    /// 建一个空目录清单。
+    #[must_use]
+    pub fn new(dir: impl Into<String>, side: PackSide) -> Self {
+        Self {
+            dir: dir.into(),
+            side,
+            files: Vec::new(),
+        }
+    }
+
+    /// 按实例内相对路径查一条。
+    #[must_use]
+    pub fn find(&self, path: &str) -> Option<&OverrideFile> {
+        self.files.iter().find(|file| file.path == path)
+    }
+}
+
+/// 把未知字段并回 JSON 对象：**已知字段优先**，extra 里的同名键丢弃（不覆盖模型的判断）。
+pub fn merge_unknown(target: &mut Map<String, Value>, extra: &Map<String, Value>) {
+    for (key, value) in extra {
+        if !target.contains_key(key) {
+            target.insert(key.clone(), value.clone());
+        }
+    }
+}
diff --git a/crates/core/src/addon/pack/modrinth.rs b/crates/core/src/addon/pack/modrinth.rs
new file mode 100644
index 0000000..4bb2a14
--- /dev/null
+++ b/crates/core/src/addon/pack/modrinth.rs
@@ -0,0 +1,394 @@
+//! Modrinth 格式：`modrinth.index.json` + `overrides/` `client-overrides/` `server-overrides/`。
+//!
+//! # 形状（A 级来源：HMCL `ModrinthManifest.java`，见 analyse/05 §2.3）
+//!
+//! ```jsonc
+//! {
+//!   "game": "minecraft", "formatVersion": 1, "versionId": "1.0.0",
+//!   "name": "…", "summary": "…",
+//!   "files": [{
+//!     "path": "mods/jei.jar",
+//!     "hashes": {"sha1": "…", "sha512": "…"},
+//!     "env": {"client": "required", "server": "unsupported"},
+//!     "downloads": ["https://cdn.modrinth.com/data/…/jei.jar"],
+//!     "fileSize": 123456
+//!   }],
+//!   "dependencies": {"minecraft": "1.20.1", "fabric-loader": "0.15.11"}
+//! }
+//! ```
+//!
+//! 比 CF 强的地方（也是模型主路径为什么按 mrpack 设计）：**有路径、有多源 URL、有摘要表、
+//! 有客户端/服务端分侧语义**。这三样正是「能否被远程替代」判据（D10 §2 导出侧）需要的输入。
+//!
+//! # 读取时坚持的三条校验（与 HMCL `File.validate()` 同源）
+//!
+//! 1. `path` 必须是不越界的相对路径（[`normalize_file`] 七条规则，第二检在 `archive`）；
+//! 2. `hashes.sha512` 必须存在且是 128 位十六进制——没有它，"远程替代"无从判断；
+//! 3. `env` 出现时 `client` 必须存在（`env.server` 缺省按 `required`）。
+//!
+//! 另有两条事实（M115 调研 §字段缺口 1/4）：`fileSize` 在规范里是**必填**（模型里是
+//! `Option`，未知就不写，由 M112 补全），`server-overrides` 客户端**不解压**（模型照记，
+//! 落地判断留给 M111）。
+//!
+//! 这三条是**读**的硬门槛；写（导出）另有四条：
+//!
+//! 1. 条目缺 `path` 或缺 `downloads` 一律报 `PackErrorKind::Unsupported`（CF 的裸
+//!    `projectID/fileID` 条目转不成 mrpack，必须先补全——这就是 M111/M112 的分工边界）；
+//! 2. 禁用位（[`PackFile::disabled`]）落成 **`path` 结尾的 `.disabled`**，不是
+//!    `env.client=optional`（tower 定案；后者跨启动器不保真，见 [`DISABLED_SUFFIX`]）；
+//! 3. `fileSize` 按规范的 u32 校验，超了报 `pack_limits`（HMCL 那边 `(int)` 截断只打 warning
+//!    是反面教材）；
+//! 4. 整包未压缩总量撞 ZIP64 阈值时由 `format::write` 拒绝（`pack_limits`），不写半成品。
+//!
+//! `dependencies` 里的 `neoforge` 与 `neo-forge` 两种拼法都认（HMCL PR #5170 的坑），
+//! 认不出的键（社区新加载器如 `parchment`）**原样保留**成一条 [`PackLoader`]。
+
+use std::collections::BTreeMap;
+
+use serde::Deserialize;
+use serde_json::{json, Map, Value};
+
+use super::archive::PackArchive;
+use super::error::{PackError, PackResult};
+use super::format::PackFormat;
+use super::manifest::{
+    merge_unknown, EnvSupport, PackFile, PackLoader, PackManifest, PackOverrides, PackSide,
+};
+use super::path::normalize_file;
+
+/// 格式 id。
+pub const ID: &str = "modrinth";
+/// 清单入口名。
+pub const METADATA_ENTRY: &str = "modrinth.index.json";
+/// `game` 的固定值。
+pub const GAME: &str = "minecraft";
+/// 依赖表里代表游戏版本的那个键。
+pub const MINECRAFT_KEY: &str = "minecraft";
+/// 禁用文件的路径后缀（Modrinth 官方导出用它表达"装进来但禁用"）。
+pub const DISABLED_SUFFIX: &str = ".disabled";
+
+/// 单例（进注册表用）。
+pub static MODRINTH: Modrinth = Modrinth;
+
+/// Modrinth 格式的值类型实现。
+#[derive(Debug, Clone, Copy, Default)]
+pub struct Modrinth;
+
+/// `modrinth.index.json` 的原始形状（未知字段落 `extra`）。
+#[derive(Debug, Default, Deserialize)]
+struct RawIndex {
+    #[serde(default)]
+    game: Option<String>,
+    #[serde(rename = "formatVersion", default)]
+    format_version: Option<i64>,
+    #[serde(rename = "versionId", default)]
+    version_id: Option<String>,
+    #[serde(default)]
+    name: Option<String>,
+    #[serde(default)]
+    summary: Option<String>,
+    #[serde(default)]
+    files: Vec<RawFile>,
+    #[serde(default)]
+    dependencies: BTreeMap<String, String>,
+    #[serde(flatten)]
+    extra: Map<String, Value>,
+}
+
+/// `files[]` 的一条。
+#[derive(Debug, Default, Deserialize)]
+struct RawFile {
+    #[serde(default)]
+    path: Option<String>,
+    #[serde(default)]
+    hashes: BTreeMap<String, String>,
+    #[serde(default)]
+    env: Option<RawEnv>,
+    #[serde(default)]
+    downloads: Vec<String>,
+    #[serde(rename = "fileSize", default)]
+    file_size: Option<u64>,
+    #[serde(flatten)]
+    extra: Map<String, Value>,
+}
+
+/// `files[].env`。
+#[derive(Debug, Default, Deserialize)]
+struct RawEnv {
+    #[serde(default)]
+    client: Option<String>,
+    #[serde(default)]
+    server: Option<String>,
+    #[serde(flatten)]
+    extra: Map<String, Value>,
+}
+
+impl PackFormat for Modrinth {
+    fn id(&self) -> &'static str {
+        ID
+    }
+
+    fn label(&self) -> &'static str {
+        "Modrinth"
+    }
+
+    fn metadata_entry(&self) -> Option<&'static str> {
+        Some(METADATA_ENTRY)
+    }
+
+    fn detect(&self, pack: &PackArchive) -> PackResult<Option<&'static str>> {
+        let Some(value) = pack.read_json(METADATA_ENTRY)? else {
+            return Ok(None);
+        };
+        let object = value
+            .as_object()
+            .ok_or_else(|| PackError::metadata(format!("{METADATA_ENTRY} 存在但不是 JSON 对象")))?;
+        // 有 formatVersion 数字即可认领；没有则要求 game + files 的形状对得上。
+        let matched = object.get("formatVersion").is_some_and(Value::is_number)
+            || (object.get("game").and_then(Value::as_str) == Some(GAME)
+                && object.get("files").is_some_and(Value::is_array));
+        Ok(matched.then_some(METADATA_ENTRY))
+    }
+
+    fn check_overrides(&self, manifest: &PackManifest) -> PackResult<()> {
+        // mrpack 的覆盖目录名由 side 决定，且每侧最多一个：不符合就别写（r1 p2-1）。
+        let mut seen: Vec<PackSide> = Vec::new();
+        for group in &manifest.overrides {
+            let expected = group.side.mrpack_dir();
+            if group.dir != expected {
+                return Err(PackError::unsupported(format!(
+                    "Modrinth 的覆盖目录名由侧决定：{} 侧必须是 {expected:?}，模型里是 {:?}",
+                    group.side.as_str(),
+                    group.dir
+                ))
+                .with_hint(
+                    "按 side 分派到 overrides / client-overrides / server-overrides 属 M112；\
+                     不同格式的实例目录（如 MultiMC 的 .minecraft）不能直接搬过来",
+                ));
+            }
+            if seen.contains(&group.side) {
+                return Err(PackError::unsupported(format!(
+                    "Modrinth 每个侧只能有一个覆盖目录，{} 侧出现了多次",
+                    group.side.as_str()
+                )));
+            }
+            seen.push(group.side);
+        }
+        Ok(())
+    }
+
+    fn read(&self, pack: &PackArchive) -> PackResult<PackManifest> {
+        let value = pack
+            .read_json(METADATA_ENTRY)?
+            .ok_or_else(|| PackError::metadata(format!("包里没有 {METADATA_ENTRY}")))?;
+        let raw: RawIndex = serde_json::from_value(value)
+            .map_err(|error| PackError::metadata(format!("{METADATA_ENTRY} 形状不符：{error}")))?;
+        let name = raw
+            .name
+            .filter(|name| !name.trim().is_empty())
+            .ok_or_else(|| PackError::metadata(format!("{METADATA_ENTRY} 缺 name")))?;
+
+        let mut minecraft = None;
+        let mut loaders: Vec<PackLoader> = Vec::new();
+        for (key, version) in &raw.dependencies {
+            if key == MINECRAFT_KEY {
+                minecraft = Some(version.clone());
+                continue;
+            }
+            let mut loader = PackLoader::parse_dependency(key, version, false);
+            // 第一条认得出来的加载器当主加载器（mrpack 没有 primary 概念）。
+            if loader.kind.is_some() && !loaders.iter().any(|seen| seen.kind.is_some()) {
+                loader.primary = true;
+            }
+            loaders.push(loader);
+        }
+
+        let mut files = Vec::with_capacity(raw.files.len());
+        for file in raw.files {
+            let path = file.path.as_deref().ok_or_else(|| {
+                PackError::metadata(format!("{METADATA_ENTRY} 有一条 files[] 没有 path"))
+            })?;
+            let path = normalize_file(path)?;
+            check_sha512(&path, &file.hashes)?;
+            let (client, server, env_extra) = match file.env {
+                None => (EnvSupport::Required, EnvSupport::Required, Map::new()),
+                Some(env) => {
+                    let client_raw = env.client.as_deref().ok_or_else(|| {
+                        PackError::metadata(format!(
+                            "files[] 条目 {path} 有 env 但没有 env.client（Modrinth 规范要求）"
+                        ))
+                    })?;
+                    let client = parse_env(&path, "client", client_raw)?;
+                    let server = match env.server.as_deref() {
+                        Some(raw) => parse_env(&path, "server", raw)?,
+                        None => EnvSupport::Required,
+                    };
+                    (client, server, env.extra)
+                }
+            };
+            files.push(PackFile {
+                path: Some(path),
+                hashes: file.hashes,
+                downloads: file.downloads,
+                size: file.file_size,
+                client,
+                server,
+                extra: file.extra,
+                env_extra,
+                ..PackFile::default()
+            });
+        }
+
+        let mut overrides = Vec::new();
+        for side in [PackSide::Both, PackSide::Client, PackSide::Server] {
+            let dir = side.mrpack_dir();
+            let files = pack.override_files(dir)?;
+            if pack.has_entry(dir) || !files.is_empty() {
+                overrides.push(PackOverrides {
+                    dir: dir.to_string(),
+                    side,
+                    files,
+                });
+            }
+        }
+
+        Ok(PackManifest {
+            name,
+            version: raw.version_id,
+            author: None,
+            summary: raw.summary,
+            format_version: raw.format_version,
+            game: raw.game.or_else(|| Some(GAME.to_string())),
+            minecraft,
+            loaders,
+            files,
+            overrides,
+            extra: raw.extra,
+            minecraft_extra: Map::new(),
+        })
+    }
+
+    fn render(&self, manifest: &PackManifest) -> PackResult<String> {
+        let version_id = manifest.version.as_deref().ok_or_else(|| {
+            PackError::metadata("Modrinth 清单需要 versionId（包版本），模型里没有")
+        })?;
+        let mut root = Map::new();
+        root.insert(
+            "game".into(),
+            json!(manifest.game.as_deref().unwrap_or(GAME)),
+        );
+        root.insert(
+            "formatVersion".into(),
+            json!(manifest.format_version.unwrap_or(1)),
+        );
+        root.insert("versionId".into(), json!(version_id));
+        root.insert("name".into(), json!(manifest.name));
+        if let Some(summary) = &manifest.summary {
+            root.insert("summary".into(), json!(summary));
+        }
+
+        let mut dependencies = Map::new();
+        if let Some(minecraft) = &manifest.minecraft {
+            dependencies.insert(MINECRAFT_KEY.into(), json!(minecraft));
+        }
+        for loader in &manifest.loaders {
+            let key = loader.dependency_key();
+            let Some(version) = loader.version.as_deref() else {
+                return Err(PackError::unsupported(format!(
+                    "Modrinth dependencies 需要版本号，这条加载器没有：raw={:?}",
+                    loader.raw
+                )));
+            };
+            if key.is_empty() {
+                return Err(PackError::unsupported(format!(
+                    "Modrinth dependencies 需要键名，这条加载器没有：version={version:?}"
+                )));
+            }
+            dependencies.insert(key, json!(version));
+        }
+        root.insert("dependencies".into(), Value::Object(dependencies));
+
+        let mut files = Vec::with_capacity(manifest.files.len());
+        for file in &manifest.files {
+            let path = file.path.as_deref().ok_or_else(|| {
+                PackError::unsupported(format!(
+                    "Modrinth 的 files[] 需要 path，这条没有（projectID={:?}）",
+                    file.project_id
+                ))
+                .with_hint("先用 CurseForge/Modrinth API 补全条目再导出")
+            })?;
+            let path = normalize_file(path)?;
+            file.sha512().ok_or_else(|| {
+                PackError::unsupported(format!("Modrinth 的 files[] 需要 hashes.sha512：{path}"))
+            })?;
+            if file.downloads.iter().all(|url| url.trim().is_empty()) {
+                return Err(PackError::unsupported(format!(
+                    "Modrinth 的 files[] 需要至少一个 downloads URL：{path}"
+                ))
+                .with_hint("内联覆盖内容无法用 mrpack 表达（见 M112 的内联兜底方案）"));
+            }
+            let mut hashes = Map::new();
+            for (algorithm, digest) in &file.hashes {
+                hashes.insert(algorithm.clone(), json!(digest));
+            }
+            let mut env = Map::new();
+            merge_unknown(&mut env, &file.env_extra);
+            env.insert("client".into(), json!(file.client.as_str()));
+            env.insert("server".into(), json!(file.server.as_str()));
+            // 禁用位用**路径后缀**表达（Modrinth 官方导出同款，`export_mrpack.rs:653-658`），
+            // 不用 `env.client=optional`：后者只是"安装时可取消勾选"，装回来默认仍然启用，
+            // 跨启动器不保真（tower 定案，D10 §2 的旧措辞已作废）。
+            let path = if file.disabled && !path.ends_with(DISABLED_SUFFIX) {
+                format!("{path}{DISABLED_SUFFIX}")
+            } else {
+                path
+            };
+
+            let mut object = Map::new();
+            object.insert("path".into(), json!(path));
+            object.insert("hashes".into(), Value::Object(hashes));
+            object.insert("env".into(), Value::Object(env));
+            object.insert("downloads".into(), json!(file.downloads));
+            if let Some(size) = file.size {
+                // 规范里 `fileSize` 是 u32（≈4 GiB）：超了要具名报错，不静默截断。
+                let size = u32::try_from(size).map_err(|_| {
+                    PackError::limits(format!(
+                        "文件 {path} 有 {size} 字节，超过 mrpack 的 fileSize 上限（u32，4294967295）"
+                    ))
+                    .with_hint("这种尺寸只能靠 overrides/ 内联，而内联又会撞 ZIP64 上限；先缩减实例")
+                })?;
+                object.insert("fileSize".into(), json!(size));
+            }
+            merge_unknown(&mut object, &file.extra);
+            files.push(Value::Object(object));
+        }
+        root.insert("files".into(), Value::Array(files));
+
+        merge_unknown(&mut root, &manifest.extra);
+        serde_json::to_string_pretty(&Value::Object(root)).map_err(Into::into)
+    }
+}
+
+/// `hashes.sha512` 必须是 128 位十六进制。
+fn check_sha512(path: &str, hashes: &BTreeMap<String, String>) -> PackResult<()> {
+    let Some(digest) = hashes.get("sha512") else {
+        return Err(PackError::metadata(format!(
+            "files[] 条目 {path} 缺 hashes.sha512（Modrinth 规范要求）"
+        )));
+    };
+    if digest.len() != 128 || !digest.bytes().all(|byte| byte.is_ascii_hexdigit()) {
+        return Err(PackError::metadata(format!(
+            "files[] 条目 {path} 的 sha512 不是 128 位十六进制"
+        )));
+    }
+    Ok(())
+}
+
+/// 解析 `env.client` / `env.server`；不认识的取值直接拒绝（不静默降级成全都要）。
+fn parse_env(path: &str, field: &str, raw: &str) -> PackResult<EnvSupport> {
+    EnvSupport::parse(raw).ok_or_else(|| {
+        PackError::metadata(format!(
+            "files[] 条目 {path} 的 env.{field} 是 {raw:?}，只认 required/optional/unsupported"
+        ))
+    })
+}
diff --git a/crates/core/src/addon/pack/multimc.rs b/crates/core/src/addon/pack/multimc.rs
new file mode 100644
index 0000000..b4d958b
--- /dev/null
+++ b/crates/core/src/addon/pack/multimc.rs
@@ -0,0 +1,183 @@
+//! MultiMC / Prism 格式：`mmc-pack.json` + `instance.cfg` + `.minecraft/` 目录。
+//!
+//! # 形状（A 级来源：HMCL `MultiMCModpackProvider` / `toGameSettings`，见 analyse/05 §2.6）
+//!
+//! ```jsonc
+//! // mmc-pack.json
+//! {"formatVersion": 1, "components": [
+//!   {"uid": "net.minecraft", "version": "1.20.1", "important": true},
+//!   {"uid": "net.fabricmc.fabric-loader", "version": "0.15.11"}]}
+//! // instance.cfg（ini）
+//! InstanceType=OneSix
+//! name=我的整合包
+//! ```
+//!
+//! **它不是一个"包"，而是一个"实例目录"**：模组就在 `.minecraft/mods/` 里，没有任何远端
+//! 条目、没有 URL、没有摘要表。所以：
+//!
+//! - 读：把 `.minecraft` 当成一个覆盖目录（[`PackSide::Both`]），模组按目录里的实际文件逐条
+//!   记 SHA-1；[`PackManifest::files`] 恒为空——这是格式事实，不是我们的偷懒；
+//! - 写：**不支持**。写回 MultiMC 需要重组 `mmc-pack.json` 的组件图（还要处理
+//!   `patches/`、`libraries/`、`jarmods/`），那是另一套协议，不在本模块的模型职责内，
+//!   也不该伪装成"能导出"。`metadata_entry` 返回 `None`，写会得到明确的
+//!   `pack_unsupported`。
+//!
+//! `components` 是**保序列表**，里面既有加载器，也有 mappings（`net.fabricmc.intermediary`
+//! 等）与 `org.lwjgl3` 这类非加载器组件——所以模型把**每一条组件**都留在
+//! [`PackManifest::loaders`] 里（顺序不动、原始 uid 在 [`PackLoader::raw`]、`kind` 能认就认），
+//! 组件自身的 `important` / `dependencyOnly` / `cachedName` 落在 [`PackLoader::extra`]（M115
+//! 调研 §字段缺口 3）。这样"加载器集合"是它的派生视图，而不是丢信息的收窄。
+//!
+//! 也就是说：本格式**能探测、能导入**，**不能导出**——报告里已把这条写清楚。
+
+use serde::Deserialize;
+use serde_json::{Map, Value};
+
+use super::archive::PackArchive;
+use super::error::{PackError, PackResult};
+use super::format::PackFormat;
+use super::manifest::{PackLoader, PackManifest, PackOverrides, PackSide};
+
+/// 格式 id。
+pub const ID: &str = "multimc";
+/// 清单入口名。
+pub const METADATA_ENTRY: &str = "mmc-pack.json";
+/// 实例配置文件名（包名在这里）。
+pub const INSTANCE_ENTRY: &str = "instance.cfg";
+/// 实例内容目录（模组/配置都在里面）。
+pub const CONTENT_DIR: &str = ".minecraft";
+/// 游戏本体的组件 uid。
+pub const MINECRAFT_UID: &str = "net.minecraft";
+
+/// 单例（进注册表用）。
+pub static MULTIMC: MultiMc = MultiMc;
+
+/// MultiMC / Prism 格式的值类型实现。
+#[derive(Debug, Clone, Copy, Default)]
+pub struct MultiMc;
+
+/// `mmc-pack.json` 的原始形状。
+#[derive(Debug, Default, Deserialize)]
+struct RawPack {
+    #[serde(rename = "formatVersion", default)]
+    format_version: Option<i64>,
+    #[serde(default)]
+    components: Vec<RawComponent>,
+    #[serde(flatten)]
+    extra: Map<String, Value>,
+}
+
+/// `components[]` 的一条。
+#[derive(Debug, Default, Deserialize)]
+struct RawComponent {
+    #[serde(default)]
+    uid: Option<String>,
+    #[serde(default)]
+    version: Option<String>,
+    #[serde(flatten)]
+    extra: Map<String, Value>,
+}
+
+impl PackFormat for MultiMc {
+    fn id(&self) -> &'static str {
+        ID
+    }
+
+    fn label(&self) -> &'static str {
+        "MultiMC / Prism"
+    }
+
+    fn detect(&self, pack: &PackArchive) -> PackResult<Option<&'static str>> {
+        let Some(value) = pack.read_json(METADATA_ENTRY)? else {
+            return Ok(None);
+        };
+        let object = value
+            .as_object()
+            .ok_or_else(|| PackError::metadata(format!("{METADATA_ENTRY} 存在但不是 JSON 对象")))?;
+        // 形状校验：必须有非空 components 数组（MultiMC 的组件图是它的身份证）。
+        let matched = object
+            .get("components")
+            .and_then(Value::as_array)
+            .is_some_and(|components| !components.is_empty());
+        Ok(matched.then_some(METADATA_ENTRY))
+    }
+
+    fn read(&self, pack: &PackArchive) -> PackResult<PackManifest> {
+        let value = pack
+            .read_json(METADATA_ENTRY)?
+            .ok_or_else(|| PackError::metadata(format!("包里没有 {METADATA_ENTRY}")))?;
+        let raw: RawPack = serde_json::from_value(value)
+            .map_err(|error| PackError::metadata(format!("{METADATA_ENTRY} 形状不符：{error}")))?;
+
+        let mut minecraft = None;
+        let mut loaders: Vec<PackLoader> = Vec::new();
+        for component in &raw.components {
+            let Some(uid) = component.uid.as_deref() else {
+                continue;
+            };
+            let Some(version) = component.version.as_deref() else {
+                continue;
+            };
+            if uid == MINECRAFT_UID {
+                minecraft = Some(version.to_string());
+                continue;
+            }
+            let mut loader = PackLoader::parse_multimc(uid, version, false);
+            if loader.kind.is_some() && !loaders.iter().any(|seen| seen.kind.is_some()) {
+                loader.primary = true;
+            }
+            loader.extra = component.extra.clone();
+            loaders.push(loader);
+        }
+
+        let name = instance_name(pack).unwrap_or_else(|| {
+            pack.root()
+                .file_stem()
+                .map(|stem| stem.to_string_lossy().to_string())
+                .unwrap_or_default()
+        });
+
+        let mut overrides = Vec::new();
+        let content = pack.override_files(CONTENT_DIR)?;
+        if pack.has_entry(CONTENT_DIR) || !content.is_empty() {
+            overrides.push(PackOverrides {
+                dir: CONTENT_DIR.to_string(),
+                side: PackSide::Both,
+                files: content,
+            });
+        }
+
+        Ok(PackManifest {
+            name,
+            version: None,
+            author: None,
+            summary: None,
+            format_version: raw.format_version.or(Some(1)),
+            game: Some("minecraft".to_string()),
+            minecraft,
+            loaders,
+            // MultiMC 没有远端条目：模组就是覆盖目录里的文件。
+            files: Vec::new(),
+            overrides,
+            extra: raw.extra,
+            minecraft_extra: Map::new(),
+        })
+    }
+
+    fn render(&self, _manifest: &PackManifest) -> PackResult<String> {
+        Err(PackError::unsupported(
+            "MultiMC 格式只支持导入：写回需要重组组件图与 patches/libraries，不在模型职责内",
+        )
+        .with_hint("导出请选 Modrinth（.mrpack）或 CurseForge 格式"))
+    }
+}
+
+/// 从 `instance.cfg` 的 `name=` 行取实例名（MultiMC 的 ini 很宽松，只认这一行）。
+fn instance_name(pack: &PackArchive) -> Option<String> {
+    let text = pack.read_text(INSTANCE_ENTRY).ok().flatten()?;
+    text.lines()
+        .filter_map(|line| line.trim().strip_prefix("name="))
+        .map(str::trim)
+        .find(|name| !name.is_empty())
+        .map(str::to_string)
+}
diff --git a/crates/core/src/addon/pack/path.rs b/crates/core/src/addon/pack/path.rs
new file mode 100644
index 0000000..323cd39
--- /dev/null
+++ b/crates/core/src/addon/pack/path.rs
@@ -0,0 +1,140 @@
+//! 包内路径规整：路径穿越**第一检**（第二检是 `zip` crate 的 `enclosed_name()`，见 `archive`）。
+//!
+//! 判据不是"看起来安全"，而是一条条写死的规则。任一条不满足就报
+//! `crate::addon::pack::error::PackErrorKind::Traversal`：
+//!
+//! 1. 空名字拒绝（`""` 与全 `/` 都不成路径）；
+//! 2. `\0` 拒绝（底层会被截断，产生"看得见查不着"的名字）；
+//! 3. `\` 拒绝——zip 规范要求 `/` 分隔，但 Win32 把 `\` 也当分隔符，于是
+//!    `mods\..\..\evil` 在"按 `/` 切"的检查里是一个普通名字、在落盘时却跳三层；
+//! 4. `:` 拒绝——盘符（`C:/x`）与 NTFS 交换数据流（`file:Zone.Identifier`）的共同记号；
+//! 5. 前导 `/` 拒绝（绝对路径）；
+//! 6. 任何 `..` 段拒绝（不"抵消"后放行：`a/../b` 与 `../b` 一律拒，避免归一化差异）；
+//! 7. `.` 段与空段（`a//b`）**丢弃**（纯噪声，不是穿越手法）。
+//!
+//! 规整后的名字一律 `/` 分隔、无前导斜杠、无 `.` / `..` 段，因此可以安全地
+//! `root.join(name)`——但**写盘前仍要再查一次**（`archive` 的 `sha1`/`read` 与 `format` 的
+//! `write` 都重新过一遍本模块），因为模型可能来自外部构造而非本模块的读者。
+
+use super::error::{PackError, PackResult};
+
+/// 规整一条**文件**条目名（目录条目请用 [`normalize_dir`]）。
+///
+/// 结尾的 `/` 视为目录标记并被去掉；去掉后为空则拒绝。
+pub fn normalize_file(raw: &str) -> PackResult<String> {
+    let text = normalize_text(raw)?;
+    if text.is_empty() {
+        return Err(PackError::traversal(format!("包内路径为空：{raw:?}")));
+    }
+    Ok(text)
+}
+
+/// 规整一条**目录**前缀（例如 CF 的 `overrides`、mrpack 的 `client-overrides`）。
+pub fn normalize_dir(raw: &str) -> PackResult<String> {
+    let text = normalize_text(raw)?;
+    if text.is_empty() {
+        return Err(PackError::traversal(format!("包内目录为空：{raw:?}")));
+    }
+    Ok(text)
+}
+
+/// 文件名是否以 `/` 结尾（zip 的目录条目约定）。
+#[must_use]
+pub fn has_trailing_slash(raw: &str) -> bool {
+    raw.ends_with('/')
+}
+
+/// 规则 1–7 的实现。返回可能为空的规整串（由调用方判定"空"是否合法）。
+fn normalize_text(raw: &str) -> PackResult<String> {
+    if raw.is_empty() {
+        return Err(PackError::traversal("包内路径为空"));
+    }
+    if raw.contains('\0') {
+        return Err(PackError::traversal(format!("包内路径含 NUL：{raw:?}")));
+    }
+    if raw.contains('\\') {
+        return Err(PackError::traversal(format!(
+            "包内路径含反斜杠（Win32 会当分隔符）：{raw:?}"
+        )));
+    }
+    if raw.contains(':') {
+        return Err(PackError::traversal(format!(
+            "包内路径含冒号（盘符 / NTFS 数据流）：{raw:?}"
+        )));
+    }
+    if raw.starts_with('/') {
+        return Err(PackError::traversal(format!("包内路径是绝对路径：{raw:?}")));
+    }
+
+    let mut segments: Vec<&str> = Vec::new();
+    for segment in raw.split('/') {
+        match segment {
+            "" | "." => continue,
+            ".." => {
+                return Err(PackError::traversal(format!(
+                    "包内路径含 `..` 上跳：{raw:?}"
+                )));
+            }
+            other => segments.push(other),
+        }
+    }
+    Ok(segments.join("/"))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::addon::pack::error::PackErrorKind;
+
+    #[test]
+    fn keeps_plain_relative_names() {
+        assert_eq!(normalize_file("mods/jei.jar").unwrap(), "mods/jei.jar");
+        assert_eq!(
+            normalize_file("config/a/b.toml").unwrap(),
+            "config/a/b.toml"
+        );
+        // `.` 段与空段是噪声，丢掉而不是报错。
+        assert_eq!(normalize_file("./mods//jei.jar").unwrap(), "mods/jei.jar");
+        assert_eq!(normalize_dir("overrides/").unwrap(), "overrides");
+        assert_eq!(
+            normalize_dir("client-overrides//").unwrap(),
+            "client-overrides"
+        );
+    }
+
+    #[test]
+    fn rejects_traversal_shapes() {
+        for raw in [
+            "../evil.jar",
+            "mods/../../evil.jar",
+            "a/../b",
+            "/etc/passwd",
+            "//server/share",
+            "C:/Windows/evil.dll",
+            "mods\\..\\..\\evil.jar",
+            "mods/jei.jar:Zone.Identifier",
+            "mods/\0jei.jar",
+            "",
+            "/",
+            "./",
+        ] {
+            let error = normalize_file(raw).expect_err(raw);
+            assert_eq!(
+                error.kind(),
+                PackErrorKind::Traversal,
+                "应判为穿越，实际 {raw:?} → {error}"
+            );
+        }
+    }
+
+    #[test]
+    fn trailing_slash_marks_directories() {
+        assert!(has_trailing_slash("overrides/"));
+        assert!(!has_trailing_slash("overrides"));
+        // 目录标记不改变规整结果：`overrides/` 与 `overrides` 是同一个前缀。
+        assert_eq!(
+            normalize_dir("overrides/").unwrap(),
+            normalize_dir("overrides").unwrap()
+        );
+    }
+}
diff --git a/crates/core/src/addon/pack/tests/detect.rs b/crates/core/src/addon/pack/tests/detect.rs
new file mode 100644
index 0000000..2692169
--- /dev/null
+++ b/crates/core/src/addon/pack/tests/detect.rs
@@ -0,0 +1,223 @@
+//! 探测优先级：顺序写死在注册表里，用例把"谁赢"和"为什么赢"都钉住。
+//!
+//! 判据分三层，缺一层都可能被"看起来对"糊过去：
+//! 1. 内置顺序本身（[`PackRegistry::ids`]）；
+//! 2. 同一份包命中多格式时选谁（含 `also_matched` 记录的其它命中）；
+//! 3. **换一下注册顺序，赢家跟着换**——这才证明优先级来自注册表，而不是代码里散落的 if。
+
+use super::{fixtures, temp_root, write_zip};
+use crate::addon::pack::archive::PackArchive;
+use crate::addon::pack::curseforge::CURSEFORGE;
+use crate::addon::pack::error::PackErrorKind;
+use crate::addon::pack::format::{PackFormat, PackRegistry};
+use crate::addon::pack::modrinth::MODRINTH;
+use crate::addon::pack::multimc::MULTIMC;
+
+const CF_MANIFEST: &[u8] = br#"{"manifestType":"minecraftModpack","manifestVersion":1,
+  "name":"hybrid pack","version":"1.0","minecraft":{"version":"1.20.1"},"files":[]}"#;
+
+const MR_INDEX: &[u8] = br#"{"game":"minecraft","formatVersion":1,"versionId":"1.0",
+  "name":"hybrid pack","files":[],"dependencies":{"minecraft":"1.20.1"}}"#;
+
+const MMC_PACK: &[u8] =
+    br#"{"formatVersion":1,"components":[{"uid":"net.minecraft","version":"1.20.1"}]}"#;
+
+/// 同时带三种身份标记的"不标准包"。
+fn hybrid_pack(tag: &str) -> std::path::PathBuf {
+    let target = temp_root(tag).join("hybrid.zip");
+    write_zip(
+        &target,
+        &[
+            ("manifest.json", CF_MANIFEST),
+            ("modrinth.index.json", MR_INDEX),
+            ("mmc-pack.json", MMC_PACK),
+            ("overrides/config/x.toml", &b"x = 1\n"[..]),
+        ],
+    );
+    target
+}
+
+#[test]
+fn builtin_priority_is_pinned() {
+    assert_eq!(
+        PackRegistry::builtin().ids(),
+        vec!["curseforge", "modrinth", "multimc"],
+        "探测顺序是决策，不是实现细节：改了要连着报告与测试一起改"
+    );
+}
+
+#[test]
+fn curseforge_wins_when_a_pack_carries_every_marker() {
+    let pack = PackArchive::open_default(hybrid_pack("detect-hybrid")).expect("打开混合包");
+    let matched = PackRegistry::builtin().detect(&pack).expect("要能选出格式");
+    assert_eq!(matched.format().id(), "curseforge");
+    assert_eq!(
+        matched.also_matched().to_vec(),
+        vec!["modrinth", "multimc"],
+        "其余命中必须可见（调用方据此提示「这包不标准」）"
+    );
+    assert!(matched.is_ambiguous());
+}
+
+#[test]
+fn a_plain_manifest_json_does_not_claim_curseforge() {
+    // `manifest.json` 这名字太泛：形状不符就不能认领，否则 mrpack 会被抢走。
+    let target = temp_root("detect-plain").join("plain.zip");
+    write_zip(
+        &target,
+        &[
+            ("manifest.json", &br#"{"hello":"world"}"#[..]),
+            ("modrinth.index.json", MR_INDEX),
+        ],
+    );
+    let pack = PackArchive::open_default(&target).expect("打开包");
+    let matched = PackRegistry::builtin().detect(&pack).expect("要能选出格式");
+    assert_eq!(matched.format().id(), "modrinth");
+    assert!(matched.also_matched().is_empty(), "CF 不该被「泛名」骗到");
+}
+
+#[test]
+fn registration_order_decides_the_winner() {
+    // 同一份包同时有 CF 与 mrpack 标记：只换注册顺序，赢家就该换。
+    let target = temp_root("detect-order").join("both.zip");
+    write_zip(
+        &target,
+        &[
+            ("manifest.json", CF_MANIFEST),
+            ("modrinth.index.json", MR_INDEX),
+        ],
+    );
+    let pack = PackArchive::open_default(&target).expect("打开双标记包");
+
+    let builtin = PackRegistry::builtin()
+        .detect(&pack)
+        .expect("默认顺序要能选");
+    assert_eq!(builtin.format().id(), "curseforge");
+    assert_eq!(builtin.also_matched().to_vec(), vec!["modrinth"]);
+
+    let reversed = PackRegistry::empty().with(&MODRINTH).with(&CURSEFORGE);
+    let matched = reversed.detect(&pack).expect("反序注册也要能选");
+    assert_eq!(
+        matched.format().id(),
+        "modrinth",
+        "反序注册后 Modrinth 排第一，就该它赢"
+    );
+    assert_eq!(matched.also_matched().to_vec(), vec!["curseforge"]);
+}
+
+#[test]
+fn unknown_package_is_rejected_with_the_list_of_tried_formats() {
+    let target = temp_root("detect-unknown").join("unknown.zip");
+    write_zip(&target, &[("readme.txt", &b"nothing to see"[..])]);
+    let pack = PackArchive::open_default(&target).expect("打开包");
+    assert!(PackRegistry::builtin().detect_all(&pack).is_empty());
+    let error = PackRegistry::builtin()
+        .detect(&pack)
+        .expect_err("没有格式认领就必须报错");
+    assert_eq!(error.kind(), PackErrorKind::Unsupported);
+    for id in ["curseforge", "modrinth", "multimc"] {
+        assert!(
+            error.message().contains(id),
+            "错误里要列出试过哪些格式，实际：{}",
+            error.message()
+        );
+    }
+}
+
+#[test]
+fn multimc_needs_a_non_empty_component_graph() {
+    let target = temp_root("detect-mmc-empty").join("empty-mmc.zip");
+    write_zip(
+        &target,
+        &[(
+            "mmc-pack.json",
+            &br#"{"formatVersion":1,"components":[]}"#[..],
+        )],
+    );
+    let pack = PackArchive::open_default(&target).expect("打开包");
+    assert_eq!(
+        MULTIMC.detect(&pack).expect("mmc-pack.json 可读"),
+        None,
+        "空 components 是空壳，不能当 MultiMC 实例"
+    );
+    assert_eq!(
+        PackRegistry::builtin()
+            .detect(&pack)
+            .expect_err("不该有格式认领")
+            .kind(),
+        PackErrorKind::Unsupported
+    );
+}
+
+#[test]
+fn multimc_instance_directory_is_detected() {
+    let root = fixtures::multimc("detect-mmc-dir");
+    let pack = PackArchive::open_default(&root).expect("打开实例目录");
+    let matched = PackRegistry::builtin()
+        .detect(&pack)
+        .expect("目录形式也要能探测");
+    assert_eq!(matched.format().id(), "multimc");
+    assert!(!matched.is_ambiguous());
+}
+
+#[test]
+fn a_corrupt_manifest_is_a_metadata_error_not_unsupported() {
+    // r1 p3-2：清单在、但读不出来 = 包坏了（`pack_metadata`）。之前三个 detect 都用
+    // `.ok().flatten()` 吞掉解析错误，结果被报成「没有格式认领」——M111 的失败分级会据此
+    // 把"可以重下文件"的包判成"不支持"。
+    let target = temp_root("corrupt-manifest").join("bad.zip");
+    write_zip(&target, &[("manifest.json", &br#"{"name": "#[..])]);
+    let pack = PackArchive::open_default(&target).expect("zip 本身可读");
+
+    let error = PackRegistry::builtin()
+        .detect(&pack)
+        .expect_err("坏清单必须报错");
+    assert_eq!(error.kind(), PackErrorKind::Metadata, "{error}");
+    assert!(
+        !error.message().contains("没有格式认领"),
+        "不许把「包坏了」说成「不认识」：{}",
+        error.message()
+    );
+}
+
+#[test]
+fn a_corrupt_foreign_manifest_does_not_hide_a_valid_mrpack() {
+    // 命中优先于失败：包里躺着一份别人的坏 manifest.json，不该让真 mrpack 也变得不可用。
+    let target = temp_root("corrupt-foreign").join("mixed.zip");
+    write_zip(
+        &target,
+        &[
+            ("manifest.json", &br#"{"name": "#[..]),
+            ("modrinth.index.json", MR_INDEX),
+        ],
+    );
+    let pack = PackArchive::open_default(&target).expect("zip 本身可读");
+    let matched = PackRegistry::builtin()
+        .detect(&pack)
+        .expect("mrpack 命中应当优先于其它格式的坏文件");
+    assert_eq!(matched.format().id(), "modrinth");
+    assert!(matched.also_matched().is_empty(), "CF 没命中（它坏了）");
+}
+
+#[test]
+fn a_missing_manifest_is_not_an_error() {
+    // 反向对照：**没有** `manifest.json` 是"不是 CF"，不是"包坏了"。
+    let target = temp_root("no-manifest").join("mmc.zip");
+    write_zip(
+        &target,
+        &[(
+            "mmc-pack.json",
+            &br#"{"formatVersion":1,"components":[{"uid":"net.minecraft","version":"1.20.1"}]}"#[..],
+        )],
+    );
+    let pack = PackArchive::open_default(&target).expect("zip 本身可读");
+    assert_eq!(CURSEFORGE.detect(&pack).expect("缺清单不是错误"), None);
+    assert_eq!(
+        PackRegistry::builtin()
+            .detect(&pack)
+            .expect("MultiMC 应当命中")
+            .format()
+            .id(),
+        "multimc"
+    );
+}
diff --git a/crates/core/src/addon/pack/tests/export.rs b/crates/core/src/addon/pack/tests/export.rs
new file mode 100644
index 0000000..14ab2aa
--- /dev/null
+++ b/crates/core/src/addon/pack/tests/export.rs
@@ -0,0 +1,156 @@
+//! 导出面的安全闸（r1 p2-1 / p3-1）：**跨格式导出必须被拒，失败不留半个包**。
+//!
+//! 这一组不测"映射是否做对"（那是 M112），只测"表达不了的时候会不会静默产出空包"。
+
+use super::{fixtures, temp_root};
+use crate::addon::pack::archive::PackArchive;
+use crate::addon::pack::curseforge::CURSEFORGE;
+use crate::addon::pack::error::PackErrorKind;
+use crate::addon::pack::format::{PackFormat, PackPayload};
+use crate::addon::pack::manifest::{OverrideFile, PackManifest, PackOverrides, PackSide};
+use crate::addon::pack::modrinth::MODRINTH;
+use crate::addon::pack::multimc::MULTIMC;
+
+#[test]
+fn a_multimc_instance_cannot_be_written_as_mrpack() {
+    // r1 p2-1 实测过的那条：MultiMC 模型写 mrpack 会返回 Ok，但覆盖内容落在 `.minecraft/...`，
+    // mrpack 导入器只解压 overrides / client-overrides / server-overrides ⇒ mods 数量为 0。
+    // 现在必须在写第一个字节之前就拒。
+    let root = fixtures::multimc("export-mmc-mr");
+    let pack = PackArchive::open_default(&root).expect("打开实例目录");
+    let mut manifest = MULTIMC.read(&pack).expect("读 MultiMC 清单");
+    manifest.version = Some("1.0.0".to_string()); // mrpack 需要 versionId，别让别的错误顶包
+
+    let target = root.with_file_name("cross.mrpack");
+    let error = MODRINTH
+        .write(&manifest, PackPayload::from_root(&root), &target)
+        .expect_err("跨格式导出必须被拒，不能产出 mods 为 0 的包");
+    assert_eq!(error.kind(), PackErrorKind::Unsupported, "{error}");
+    assert!(
+        error.message().contains(".minecraft"),
+        "错误要说清是哪个目录表达不了：{}",
+        error.message()
+    );
+    assert!(error.hint().is_some(), "要给下一步提示（目录映射属 M112）");
+    assert!(!target.exists(), "被拒时不许留下目标文件");
+}
+
+#[test]
+fn an_mrpack_with_split_sides_cannot_be_written_as_curseforge() {
+    // CF 只有一个 `overrides` 目录字段，表达不了 client/server 分侧；现在是拒，不是猜。
+    let fixture = fixtures::modrinth("export-mr-cf");
+    let pack = PackArchive::open_default(&fixture.zip).expect("打开 mrpack 夹具");
+    let manifest = MODRINTH.read(&pack).expect("读 mrpack 清单");
+
+    let target = fixture.zip.with_file_name("cross.zip");
+    let error = CURSEFORGE
+        .write(&manifest, PackPayload::from_root(&fixture.dir), &target)
+        .expect_err("CF 表达不了分侧覆盖目录");
+    assert_eq!(error.kind(), PackErrorKind::Unsupported, "{error}");
+    assert!(
+        error.message().contains("client"),
+        "错误要指出被拒的是哪一侧：{}",
+        error.message()
+    );
+    assert!(!target.exists(), "被拒时不许留下目标文件");
+}
+
+#[test]
+fn curseforge_refuses_more_than_one_both_side_group() {
+    // CF 的 `overrides` 只有一个字段：两个 Both 组必然有一个不被清单声明（静默丢内容）。
+    let mut manifest = PackManifest::new("两个 Both 组");
+    manifest.minecraft = Some("1.20.1".to_string());
+    manifest
+        .overrides
+        .push(PackOverrides::new("overrides", PackSide::Both));
+    manifest
+        .overrides
+        .push(PackOverrides::new("extra-overrides", PackSide::Both));
+
+    let target = temp_root("export-cf-two").join("out.zip");
+    let error = CURSEFORGE
+        .write(&manifest, PackPayload::metadata_only(), &target)
+        .expect_err("多出来的 Both 组会被清单漏掉，必须拒");
+    assert_eq!(error.kind(), PackErrorKind::Unsupported, "{error}");
+    assert!(!target.exists(), "被拒时不许留下目标文件");
+}
+
+#[test]
+fn a_failed_export_leaves_neither_a_half_pack_nor_a_temp_file() {
+    // r1 p3-1：清单写完了、覆盖文件读不出来 → 目标路径与临时文件都不许留。
+    let mut manifest = PackManifest::new("缺覆盖文件的模型");
+    manifest.minecraft = Some("1.20.1".to_string());
+    manifest.overrides.push(PackOverrides {
+        dir: "overrides".to_string(),
+        side: PackSide::Both,
+        files: vec![OverrideFile {
+            path: "mods/missing.jar".to_string(),
+            sha1: "0".repeat(40),
+            size: 1,
+        }],
+    });
+
+    let root = temp_root("export-half");
+    std::fs::create_dir_all(&root).expect("建目录");
+    let target = root.join("out.zip");
+    let error = CURSEFORGE
+        .write(&manifest, PackPayload::from_root(&root), &target)
+        .expect_err("覆盖文件不存在时必须失败");
+    assert_eq!(error.kind(), PackErrorKind::Io, "{error}");
+    assert!(!target.exists(), "失败后目标路径不许存在");
+
+    let leftovers: Vec<String> = std::fs::read_dir(&root)
+        .expect("列目录")
+        .filter_map(Result::ok)
+        .map(|entry| entry.file_name().to_string_lossy().to_string())
+        .collect();
+    assert!(
+        leftovers.is_empty(),
+        "临时文件没清干净（p3-1 回退）：{leftovers:?}"
+    );
+}
+
+#[test]
+fn same_format_export_is_still_allowed() {
+    // 反向对照：这两条闸不能把同格式往返也挡掉（那是 r1 明确要保住的）。
+    let fixture = fixtures::curseforge("export-same-cf");
+    let pack = PackArchive::open_default(&fixture.zip).expect("打开 CF 夹具");
+    let manifest = CURSEFORGE.read(&pack).expect("读 CF 清单");
+    CURSEFORGE
+        .check_overrides(&manifest)
+        .expect("CF 自己读出来的模型必须能被 CF 表达");
+
+    let fixture = fixtures::modrinth("export-same-mr");
+    let pack = PackArchive::open_default(&fixture.zip).expect("打开 mrpack 夹具");
+    let manifest = MODRINTH.read(&pack).expect("读 mrpack 清单");
+    MODRINTH
+        .check_overrides(&manifest)
+        .expect("mrpack 自己读出来的模型必须能被 mrpack 表达");
+}
+
+#[test]
+fn mrpack_refuses_two_override_groups_for_the_same_side() {
+    // r2 p3-a：mrpack 的「每侧只能有一个覆盖目录」分支此前零测试（删掉它 59 条全绿）。
+    // 目录名检查管不到这里：两个组的 `dir` 都合法，区别只在于同一侧出现了两次。
+    let mut manifest = PackManifest::new("同侧两个覆盖目录");
+    manifest.version = Some("1.0.0".to_string());
+    manifest.minecraft = Some("1.20.1".to_string());
+    manifest
+        .overrides
+        .push(PackOverrides::new("overrides", PackSide::Both));
+    manifest
+        .overrides
+        .push(PackOverrides::new("overrides", PackSide::Both));
+
+    let target = temp_root("export-mr-same-side").join("out.mrpack");
+    let error = MODRINTH
+        .write(&manifest, PackPayload::metadata_only(), &target)
+        .expect_err("同一侧两个覆盖目录必须拒");
+    assert_eq!(error.kind(), PackErrorKind::Unsupported, "{error}");
+    assert!(
+        error.message().contains("每个侧只能有一个覆盖目录"),
+        "错误要指出是「同侧重复」而不是「目录名不对」：{}",
+        error.message()
+    );
+    assert!(!target.exists(), "被拒时不许留下目标文件");
+}
diff --git a/crates/core/src/addon/pack/tests/export_harness.rs b/crates/core/src/addon/pack/tests/export_harness.rs
new file mode 100644
index 0000000..a6d4bcb
--- /dev/null
+++ b/crates/core/src/addon/pack/tests/export_harness.rs
@@ -0,0 +1,121 @@
+//! 导出测试的共用夹具（M112）：实例目录、`versions/` 版本层、假的远端目录。
+//!
+//! 这里的东西**只给测试用**：本仓库没有 Modrinth/CF 客户端（要网络与 key），所以远端查表一律
+//! 由 [`StubCatalog`] 注入；实例目录手造成"M111 导入产物"的形状（内容目录 + 版本 JSON）。
+
+use std::cell::RefCell;
+use std::collections::BTreeMap;
+use std::path::{Path, PathBuf};
+
+use super::{temp_root, write_file};
+use crate::addon::export::catalog::{RemoteCatalog, RemoteHit};
+use crate::addon::export::scan::{scan_instance, DEFAULT_CONTENT_ROOTS};
+use crate::addon::pack::curseforge::fingerprint;
+
+pub(super) const VANILLA_LAYER: &str = r#"{"id": "1.20.1", "libraries": []}"#;
+pub(super) const FABRIC_LAYER: &str = r#"{
+  "id": "1.20.1-fabric-0.15.11",
+  "inheritsFrom": "1.20.1",
+  "libraries": [{"name": "net.fabricmc:fabric-loader:0.15.11"}]
+}"#;
+pub(super) const NEOFORGE_LAYER: &str = r#"{
+  "id": "1.20.1-neoforge-47.1.106",
+  "inheritsFrom": "1.20.1",
+  "libraries": [
+    {"name": "net.neoforged:neoforge:1.20.1-47.1.106"},
+    {"name": "net.fancymodloader:loader:3.0.5"}
+  ]
+}"#;
+pub(super) const FORGE_LAYER: &str = r#"{
+  "id": "1.20.1-forge-47.2.0",
+  "inheritsFrom": "1.20.1",
+  "libraries": [{"name": "net.minecraftforge:forge:1.20.1-47.2.0:universal"}]
+}"#;
+
+/// 内容目录清单（与导出默认值同一份）。
+pub(super) fn defaults() -> Vec<String> {
+    DEFAULT_CONTENT_ROOTS.map(str::to_string).to_vec()
+}
+
+/// 写一份 `<id>/<id>.json`。
+pub(super) fn write_layer(game: &Path, id: &str, json: &str) {
+    write_file(
+        &game.join(format!("versions/{id}/{id}.json")),
+        json.as_bytes(),
+    );
+}
+
+/// 一个 Fabric 实例目录：两个 mod（其中一个禁用）+ 一份 config + 一份白名单外的日志。
+pub(super) fn fabric_instance(tag: &str) -> PathBuf {
+    let root = temp_root(tag).join("game");
+    write_layer(&root, "1.20.1", VANILLA_LAYER);
+    write_layer(&root, "1.20.1-fabric-0.15.11", FABRIC_LAYER);
+    write_file(&root.join("mods/jei.jar"), b"PK\x03\x04 jei body");
+    write_file(&root.join("mods/off.jar.disabled"), b"PK\x03\x04 off body");
+    write_file(&root.join("config/known.toml"), b"key = \"value\"\n");
+    write_file(&root.join("logs/latest.log"), b"not pack content\n");
+    root
+}
+
+/// 一个 NeoForge 1.20.1 实例目录（CF `modLoaders[].id` 的 MC 前缀特例用它）。
+pub(super) fn neoforge_instance(tag: &str) -> PathBuf {
+    let root = temp_root(tag).join("game");
+    write_layer(&root, "1.20.1", VANILLA_LAYER);
+    write_layer(&root, "1.20.1-neoforge-47.1.106", NEOFORGE_LAYER);
+    write_file(&root.join("mods/jei.jar"), b"PK\x03\x04 jei body");
+    root
+}
+
+/// 目录里的一个文件（路径 + SHA-1 + CF 指纹），与 `scan_instance` 同源。
+pub(super) fn digests(root: &Path, path: &str) -> (String, u32) {
+    let (locals, _) = scan_instance(root, &defaults());
+    let local = locals
+        .iter()
+        .find(|file| file.path == path)
+        .unwrap_or_else(|| panic!("夹具里没有 {path}"));
+    let value = fingerprint::fingerprint_file(&local.disk).expect("算指纹");
+    (local.sha1.clone(), value)
+}
+
+/// 一个能写进 mrpack 的 Modrinth 命中（sha1 + sha512 + 直链）。
+pub(super) fn modrinth_hit(sha1: &str, url: &str) -> RemoteHit {
+    let mut hashes = BTreeMap::new();
+    hashes.insert("sha1".to_string(), sha1.to_string());
+    hashes.insert("sha512".to_string(), "a".repeat(128));
+    RemoteHit::modrinth(vec![url.to_string()], hashes, Some(11))
+}
+
+/// 一个**假**的远端目录：查表结果由测试塞，调用过的指纹记下来（哨兵值那条分支靠它断言）。
+#[derive(Default)]
+pub(super) struct StubCatalog {
+    modrinth: BTreeMap<String, RemoteHit>,
+    curse: BTreeMap<u32, RemoteHit>,
+    curse_calls: RefCell<Vec<u32>>,
+}
+
+impl StubCatalog {
+    pub(super) fn with_modrinth(mut self, sha1: &str, hit: RemoteHit) -> Self {
+        self.modrinth.insert(sha1.to_string(), hit);
+        self
+    }
+
+    pub(super) fn with_curse(mut self, value: u32, hit: RemoteHit) -> Self {
+        self.curse.insert(value, hit);
+        self
+    }
+
+    pub(super) fn curse_calls(&self) -> Vec<u32> {
+        self.curse_calls.borrow().clone()
+    }
+}
+
+impl RemoteCatalog for StubCatalog {
+    fn modrinth_by_sha1(&self, sha1: &str) -> Option<RemoteHit> {
+        self.modrinth.get(sha1).cloned()
+    }
+
+    fn curseforge_by_fingerprint(&self, value: u32) -> Option<RemoteHit> {
+        self.curse_calls.borrow_mut().push(value);
+        self.curse.get(&value).cloned()
+    }
+}
diff --git a/crates/core/src/addon/pack/tests/export_pipeline.rs b/crates/core/src/addon/pack/tests/export_pipeline.rs
new file mode 100644
index 0000000..6e052c4
--- /dev/null
+++ b/crates/core/src/addon/pack/tests/export_pipeline.rs
@@ -0,0 +1,370 @@
+//! 导出管线（M112）：三分类、`.disabled` 路径后缀、`game`/`dependencies` 来自实例快照。
+//!
+//! 夹具在 [`super::export_harness`]：手造的实例目录（形状与 M111 导入产物一致）+
+//! 注入式假远端目录（本仓库没有 Modrinth/CF 客户端，测试也不许联网）。
+
+use std::collections::BTreeMap;
+use std::io::Read;
+use std::path::Path;
+
+use super::export_harness::{
+    defaults, digests, fabric_instance, modrinth_hit, neoforge_instance, StubCatalog,
+};
+use super::{temp_root, write_file};
+use crate::addon::export::classify::classify_with;
+use crate::addon::export::scan::{is_disabled_path, scan_instance};
+use crate::addon::export::{export_instance, ExportRequest, FileClass, FileReason, RemoteHit};
+use crate::addon::pack::archive::PackArchive;
+use crate::addon::pack::curseforge::{fingerprint, CURSEFORGE};
+use crate::addon::pack::error::PackErrorKind;
+use crate::addon::pack::format::PackFormat;
+use crate::addon::pack::manifest::{PackFile, PackManifest};
+use crate::addon::pack::modrinth::MODRINTH;
+use crate::addon::LoaderKind;
+
+fn entry_names(path: &Path) -> Vec<String> {
+    let pack = PackArchive::open_default(path).expect("打开 zip");
+    pack.entries()
+        .iter()
+        .map(|entry| entry.name().to_string())
+        .collect()
+}
+
+#[test]
+fn offline_mrpack_export_inlines_every_file_with_its_suffix() {
+    let root = fabric_instance("export-offline-mr");
+    let target = root.with_file_name("offline.mrpack");
+    let report =
+        export_instance(&ExportRequest::new(&root, &target, &MODRINTH)).expect("离线导出必须成功");
+
+    assert_eq!(report.format, "modrinth");
+    assert_eq!(report.remote_count(), 0);
+    assert_eq!(report.inline_count(), 3, "{:?}", report.files);
+    assert_eq!(report.skipped_count(), 0);
+    assert!(report.is_complete());
+    assert!(report.bytes > 0, "包路径与字节数必须结构化给出");
+    assert_eq!(report.minecraft.as_deref(), Some("1.20.1"));
+    assert_eq!(report.loaders, vec!["fabric-loader 0.15.11".to_string()]);
+
+    let pack = PackArchive::open_default(&target).expect("打开导出的包");
+    let manifest = MODRINTH.read(&pack).expect("读回 mrpack");
+    assert_eq!(manifest.name, "game");
+    assert_eq!(manifest.version.as_deref(), Some("1.0.0"));
+    assert_eq!(manifest.minecraft.as_deref(), Some("1.20.1"));
+    let loader = manifest.loader(LoaderKind::Fabric).expect("加载器不能漏");
+    assert_eq!(loader.version.as_deref(), Some("0.15.11"));
+
+    let paths: Vec<&str> = manifest
+        .override_files()
+        .map(|(_, file)| file.path.as_str())
+        .collect();
+    assert_eq!(
+        paths,
+        vec!["config/known.toml", "mods/jei.jar", "mods/off.jar.disabled"],
+        "三个内容文件都要在 overrides/ 里，禁用位保留后缀"
+    );
+    assert!(pack.has_entry("overrides/mods/off.jar.disabled"));
+    assert!(
+        !pack.has_entry("overrides/logs/latest.log"),
+        "白名单外（logs/）不打包"
+    );
+}
+
+#[test]
+fn mrpack_index_declares_game_and_every_dependency() {
+    let root = fabric_instance("export-index-mr");
+    let target = root.with_file_name("index.mrpack");
+    export_instance(&ExportRequest::new(&root, &target, &MODRINTH)).expect("导出");
+
+    let pack = PackArchive::open_default(&target).expect("打开");
+    let index = pack
+        .read_json("modrinth.index.json")
+        .expect("读清单")
+        .expect("有清单");
+    assert_eq!(index["game"], "minecraft");
+    assert_eq!(index["formatVersion"], 1);
+    assert_eq!(index["name"], "game");
+    assert_eq!(index["dependencies"]["minecraft"], "1.20.1");
+    assert_eq!(
+        index["dependencies"]["fabric-loader"], "0.15.11",
+        "只写 minecraft 漏加载器是本任务点名的不许"
+    );
+    assert!(index["files"].as_array().is_some_and(Vec::is_empty));
+}
+
+#[test]
+fn a_modrinth_hit_becomes_a_files_entry_with_both_catalogs_urls() {
+    let root = fabric_instance("export-remote-mr");
+    let (sha1, value) = digests(&root, "mods/jei.jar");
+    let catalog = StubCatalog::default()
+        .with_modrinth(
+            &sha1,
+            modrinth_hit(&sha1, "https://cdn.modrinth.com/data/x/jei.jar"),
+        )
+        .with_curse(
+            value,
+            RemoteHit::curseforge(238_222, 5_102_025)
+                .with_download("https://edge.forgecdn.net/files/5102/025/jei.jar"),
+        );
+    let target = root.with_file_name("remote.mrpack");
+    let report =
+        export_instance(&ExportRequest::new(&root, &target, &MODRINTH).with_catalog(&catalog))
+            .expect("导出");
+
+    assert_eq!(report.remote_count(), 1);
+    let entry = report
+        .files
+        .iter()
+        .find(|file| file.path == "mods/jei.jar")
+        .expect("jei 在报告里");
+    assert_eq!(entry.class, FileClass::Remote);
+    assert_eq!(entry.reason, FileReason::ModrinthSha1);
+    assert_eq!(
+        entry.downloads.len(),
+        2,
+        "两条目录的直链都要写进 downloads[]"
+    );
+
+    let pack = PackArchive::open_default(&target).expect("打开");
+    let manifest = MODRINTH.read(&pack).expect("读回");
+    assert_eq!(manifest.files.len(), 1);
+    let file = &manifest.files[0];
+    assert_eq!(file.path.as_deref(), Some("mods/jei.jar"));
+    assert_eq!(file.downloads.len(), 2);
+    assert_eq!(file.sha512().map(str::len), Some(128));
+    assert_eq!(
+        file.sha1(),
+        Some(sha1.as_str()),
+        "本地实测的 sha1 要覆盖目录给的值"
+    );
+    assert_eq!(file.size, Some(13), "字节数按磁盘实测");
+    assert_eq!(manifest.override_files().count(), 2, "另外两个文件仍然内联");
+}
+
+#[test]
+fn a_hit_without_sha512_is_inlined_with_a_reason() {
+    let root = fabric_instance("export-no-sha512");
+    let (sha1, _) = digests(&root, "mods/jei.jar");
+    let mut hashes = BTreeMap::new();
+    hashes.insert("sha1".to_string(), sha1.clone());
+    let catalog = StubCatalog::default().with_modrinth(
+        &sha1,
+        RemoteHit::modrinth(
+            vec!["https://cdn.modrinth.com/data/x/jei.jar".into()],
+            hashes,
+            None,
+        ),
+    );
+    let target = root.with_file_name("no-sha512.mrpack");
+    let report =
+        export_instance(&ExportRequest::new(&root, &target, &MODRINTH).with_catalog(&catalog))
+            .expect("导出");
+
+    let entry = report
+        .files
+        .iter()
+        .find(|file| file.path == "mods/jei.jar")
+        .expect("jei");
+    assert_eq!(entry.class, FileClass::Inline);
+    assert_eq!(entry.reason, FileReason::MissingSha512);
+    assert_eq!(report.remote_count(), 0);
+}
+
+#[test]
+fn a_curseforge_only_hit_cannot_be_written_into_an_mrpack() {
+    let root = fabric_instance("export-curse-only");
+    let (_, value) = digests(&root, "mods/jei.jar");
+    let catalog =
+        StubCatalog::default().with_curse(value, RemoteHit::curseforge(238_222, 5_102_025));
+    let target = root.with_file_name("curse-only.mrpack");
+    let report =
+        export_instance(&ExportRequest::new(&root, &target, &MODRINTH).with_catalog(&catalog))
+            .expect("导出");
+
+    let entry = report
+        .files
+        .iter()
+        .find(|file| file.path == "mods/jei.jar")
+        .expect("jei");
+    assert_eq!(entry.reason, FileReason::CurseOnlyMatch);
+    assert_eq!(entry.class, FileClass::Inline);
+}
+
+#[test]
+fn curseforge_export_writes_only_known_project_and_file_ids() {
+    let root = fabric_instance("export-cf");
+    let (_, value) = digests(&root, "mods/jei.jar");
+    let catalog =
+        StubCatalog::default().with_curse(value, RemoteHit::curseforge(238_222, 5_102_025));
+    let target = root.with_file_name("pack.zip");
+    let report =
+        export_instance(&ExportRequest::new(&root, &target, &CURSEFORGE).with_catalog(&catalog))
+            .expect("导出");
+
+    assert_eq!(report.format, "curseforge");
+    let reasons: Vec<(String, FileReason)> = report
+        .files
+        .iter()
+        .map(|file| (file.path.clone(), file.reason))
+        .collect();
+    assert_eq!(
+        reasons,
+        vec![
+            ("config/known.toml".to_string(), FileReason::NoRemoteMatch),
+            (
+                "mods/jei.jar".to_string(),
+                FileReason::CurseForgeFingerprint
+            ),
+            (
+                "mods/off.jar.disabled".to_string(),
+                FileReason::DisabledNotExpressible
+            ),
+        ]
+    );
+
+    let pack = PackArchive::open_default(&target).expect("打开");
+    let manifest = CURSEFORGE.read(&pack).expect("读回 CF 清单");
+    assert_eq!(manifest.files.len(), 1, "files[] 只写能确定 id 的项");
+    assert_eq!(manifest.files[0].project_id, Some(238_222));
+    assert_eq!(manifest.files[0].file_id, Some(5_102_025));
+    let names = entry_names(&target);
+    assert!(names.contains(&"overrides/mods/off.jar.disabled".to_string()));
+    assert!(names.contains(&"overrides/config/known.toml".to_string()));
+}
+
+#[test]
+fn curseforge_modloaders_use_the_official_id_shape() {
+    let root = neoforge_instance("export-cf-neo");
+    let target = root.with_file_name("neo.zip");
+    export_instance(&ExportRequest::new(&root, &target, &CURSEFORGE)).expect("导出");
+    let pack = PackArchive::open_default(&target).expect("打开");
+    let manifest = pack
+        .read_json("manifest.json")
+        .expect("读清单")
+        .expect("有清单");
+    assert_eq!(manifest["minecraft"]["version"], "1.20.1");
+    assert_eq!(
+        manifest["minecraft"]["modLoaders"][0]["id"], "neoforge-1.20.1-47.1.106",
+        "CF 官方导出在 1.20.1 上把 MC 版本拼回 NeoForge 版本号"
+    );
+    assert_eq!(manifest["minecraft"]["modLoaders"][0]["primary"], true);
+
+    let root = fabric_instance("export-cf-fabric");
+    let target = root.with_file_name("fabric.zip");
+    export_instance(&ExportRequest::new(&root, &target, &CURSEFORGE)).expect("导出");
+    let pack = PackArchive::open_default(&target).expect("打开");
+    let manifest = pack
+        .read_json("manifest.json")
+        .expect("读清单")
+        .expect("有清单");
+    assert_eq!(
+        manifest["minecraft"]["modLoaders"][0]["id"],
+        "fabric-0.15.11"
+    );
+    assert_eq!(manifest["overrides"], "overrides");
+}
+
+#[test]
+fn the_sentinel_fingerprint_never_reaches_the_catalog() {
+    let root = fabric_instance("export-sentinel");
+    let (locals, _) = scan_instance(&root, &defaults());
+    let local = locals
+        .iter()
+        .find(|file| file.path == "mods/jei.jar")
+        .expect("jei");
+    let catalog = StubCatalog::default()
+        .with_curse(fingerprint::SENTINEL, RemoteHit::curseforge(1, 2))
+        .with_curse(12345, RemoteHit::curseforge(1, 2));
+
+    let (reason, hit) = classify_with(local, &catalog, true, Some(fingerprint::SENTINEL));
+    assert_eq!(reason, FileReason::NoRemoteMatch);
+    assert!(hit.is_none());
+    assert!(
+        catalog.curse_calls().is_empty(),
+        "哨兵值必须短路，不能拿去查表（HMCL issue #4597 的误命中）"
+    );
+
+    // 对照：真实指纹会去查表。
+    let (reason, hit) = classify_with(local, &catalog, true, Some(12345));
+    assert_eq!(catalog.curse_calls(), vec![12345]);
+    assert_eq!(reason, FileReason::CurseForgeFingerprint, "塞了 id 就命中");
+    assert!(hit.is_some());
+}
+
+#[test]
+fn a_disabled_file_is_still_disabled_after_a_round_trip_through_the_package() {
+    // 任务要求的那条：禁用文件导出后仍能被"重新导入"且保持禁用。
+    // 本轮没有 M111 的导入器（M111 未合并），所以"重新导入"= 把包里的 overrides 解出来 +
+    // 重新扫一遍实例目录：扫出来的 disabled 位必须是 true。
+    let root = fabric_instance("export-disabled");
+    let target = root.with_file_name("disabled.mrpack");
+    export_instance(&ExportRequest::new(&root, &target, &MODRINTH)).expect("导出");
+
+    let again = temp_root("export-disabled-reimport");
+    let file = std::fs::File::open(&target).expect("打开包");
+    let mut archive = zip::ZipArchive::new(file).expect("读 zip");
+    for index in 0..archive.len() {
+        let mut entry = archive.by_index(index).expect("条目");
+        let name = entry.name().expect("条目名").to_string();
+        let Some(relative) = name.strip_prefix("overrides/") else {
+            continue;
+        };
+        let mut bytes = Vec::new();
+        entry.read_to_end(&mut bytes).expect("读条目内容");
+        write_file(&again.join(relative), &bytes);
+    }
+
+    let (locals, skipped) = scan_instance(&again, &defaults());
+    assert!(skipped.is_empty(), "{skipped:?}");
+    let disabled: Vec<&str> = locals
+        .iter()
+        .filter(|file| file.disabled)
+        .map(|file| file.path.as_str())
+        .collect();
+    assert_eq!(disabled, vec!["mods/off.jar.disabled"]);
+    assert!(is_disabled_path("mods/off.jar.disabled.old"));
+    assert!(
+        !is_disabled_path("mods/off.jar.old"),
+        "`.old` 只是旧残留，不是禁用"
+    );
+}
+
+#[test]
+fn a_file_bigger_than_u32_is_a_named_limits_error() {
+    // 真造一个 4 GiB 文件不现实：直接测格式层的那条闸（它是唯一写 `fileSize` 的地方）。
+    let mut manifest = PackManifest::new("超大文件");
+    manifest.version = Some("1.0.0".to_string());
+    manifest.minecraft = Some("1.20.1".to_string());
+    let mut hashes = BTreeMap::new();
+    hashes.insert("sha512".to_string(), "b".repeat(128));
+    manifest.files.push(PackFile {
+        path: Some("mods/huge.jar".to_string()),
+        hashes,
+        downloads: vec!["https://cdn.modrinth.com/data/x/huge.jar".to_string()],
+        size: Some(u64::from(u32::MAX) + 1),
+        ..PackFile::default()
+    });
+
+    let error = MODRINTH.render(&manifest).expect_err("超限必须报错");
+    assert_eq!(error.kind(), PackErrorKind::Limits);
+    assert!(error.message().contains("fileSize"), "{error}");
+}
+
+#[test]
+fn content_roots_can_be_extended_without_touching_the_pipeline() {
+    // 「社区标准的扩展性」的最小证明：加一个目录不用改管线。
+    let root = fabric_instance("export-extra-root");
+    write_file(&root.join("custom/extra.txt"), b"extra content\n");
+    let target = root.with_file_name("extra.mrpack");
+    let mut roots = defaults();
+    roots.push("custom".to_string());
+    let report =
+        export_instance(&ExportRequest::new(&root, &target, &MODRINTH).with_content_roots(roots))
+            .expect("导出");
+    assert!(report
+        .files
+        .iter()
+        .any(|file| file.path == "custom/extra.txt"));
+    let pack = PackArchive::open_default(&target).expect("打开");
+    assert!(pack.has_entry("overrides/custom/extra.txt"));
+}
diff --git a/crates/core/src/addon/pack/tests/export_roundtrip.rs b/crates/core/src/addon/pack/tests/export_roundtrip.rs
new file mode 100644
index 0000000..fb28874
--- /dev/null
+++ b/crates/core/src/addon/pack/tests/export_roundtrip.rs
@@ -0,0 +1,280 @@
+//! 往返保真（M112）：用 M110 的三种格式夹具做「读出来 → 摆成实例 → 导出 → 再读」。
+//!
+//! # 为什么不是 `import_pack → export → import_pack`
+//!
+//! M111 的导入管线**还没合并进本分支**（它在复审中）。所以这里的"导入"是 M110 的
+//! `PackFormat::read` + 一个**形状与 M111 导入产物一致**的实例目录（`mods/`、`config/`、
+//! `versions/<id>/<id>.json`）。真端到端欠账在 M112 报告里登记：M111 合并后要补一条
+//! `import_pack → export → import_pack`。
+//!
+//! # 允许的差异（逐条显式列出，别让后来人以为是 bug）
+//!
+//! | 方向 | 差异 | 原因 |
+//! |------|------|------|
+//! | CF → mrpack | `files[]` 的 `projectID/fileID` 条目全丢 | CF 的 `files[]` **没有路径**，磁盘上无法复原成文件；导出侧只能看到磁盘，看不见"清单里说该有但没落地"的条目 |
+//! | CF → mrpack | `author` / `minecraft.recommendedRam` 等扩展字段丢 | mrpack 没有这些字段（`extra` 不跨格式搬） |
+//! | mrpack → mrpack | 认不出的 dependency 键（`parchment`）丢 | 快照只从版本 JSON 的库坐标来；`parchment` 没有对应库 |
+//! | mrpack → mrpack | `files[]` 的条目要靠"文件真的在磁盘上"才会再写回去 | 读出来的模型里那两条是远程条目、本地没有字节；再导出时以磁盘为准 |
+//! | MultiMC → mrpack | 非加载器组件（`org.lwjgl3`）不进 `dependencies` | 它不是加载器；mrpack 的 `dependencies` 只表达 loader |
+
+use std::path::{Path, PathBuf};
+
+use super::export_harness::{
+    defaults, modrinth_hit, write_layer, StubCatalog, FORGE_LAYER, VANILLA_LAYER,
+};
+use super::{fixtures, temp_root, write_file};
+use crate::addon::export::snapshot::{InstanceSnapshot, SnapshotLoader};
+use crate::addon::export::{export_instance, ExportRequest};
+use crate::addon::pack::archive::PackArchive;
+use crate::addon::pack::curseforge::CURSEFORGE;
+use crate::addon::pack::format::PackFormat;
+use crate::addon::pack::manifest::{PackManifest, PackSide};
+use crate::addon::pack::modrinth::MODRINTH;
+use crate::addon::pack::multimc::MULTIMC;
+use crate::addon::LoaderKind;
+
+/// 把夹具里的覆盖内容铺成一个实例目录（`<game>/<path>`），并写一份版本 JSON。
+fn instance_from(fixture_dir: &Path, manifest: &PackManifest, tag: &str) -> PathBuf {
+    let game = temp_root(tag).join("game");
+    for (_, file) in manifest.override_files() {
+        let group = manifest
+            .overrides
+            .iter()
+            .find(|group| group.files.iter().any(|each| each.path == file.path))
+            .expect("找到文件所属的组");
+        let source = fixture_dir.join(&group.dir).join(&file.path);
+        let bytes = std::fs::read(&source).unwrap_or_else(|error| {
+            panic!("读夹具 {} 失败：{error}", source.display());
+        });
+        write_file(&game.join(&file.path), &bytes);
+    }
+    write_layer(&game, "1.20.1", VANILLA_LAYER);
+    game
+}
+
+/// 一个「读出来的 mrpack」的文件集合，按路径排序（比较用）。
+fn override_paths(manifest: &PackManifest) -> Vec<String> {
+    let mut paths: Vec<String> = manifest
+        .override_files()
+        .map(|(_, file)| file.path.clone())
+        .collect();
+    paths.sort();
+    paths
+}
+
+#[test]
+fn curseforge_fixture_round_trips_through_mrpack() {
+    let fixture = fixtures::curseforge("rt-cf");
+    let pack = PackArchive::open_default(&fixture.zip).expect("打开 CF 夹具");
+    let original = CURSEFORGE.read(&pack).expect("读 CF 清单");
+
+    let game = instance_from(&fixture.dir, &original, "rt-cf-mr");
+    write_layer(&game, "1.20.1-forge-47.2.0", FORGE_LAYER);
+    let target = game.with_file_name("cf-to-mr.mrpack");
+    let request = ExportRequest::new(&game, &target, &MODRINTH)
+        .with_name(original.name.clone())
+        .with_version(original.version.clone().unwrap_or_default())
+        .with_version_id("1.20.1-forge-47.2.0");
+    let report = export_instance(&request).expect("导出");
+    assert_eq!(report.inline_count(), 3, "{:?}", report.files);
+
+    let pack = PackArchive::open_default(&target).expect("打开导出的包");
+    let again = MODRINTH.read(&pack).expect("再读回来");
+
+    // 关键字段：名称 / 版本 / 游戏版本 / 加载器 / 文件集合。
+    assert_eq!(again.name, original.name);
+    assert_eq!(again.version, original.version);
+    assert_eq!(again.minecraft, original.minecraft);
+    let loader = again.loader(LoaderKind::Forge).expect("Forge 加载器");
+    assert_eq!(loader.version.as_deref(), Some("47.2.0"));
+    assert_eq!(override_paths(&again), override_paths(&original));
+
+    // 允许的差异①：CF 的 files[] 没有路径，磁盘上复原不出来 ⇒ 往返后 files[] 为空。
+    assert!(
+        again.files.is_empty(),
+        "CF 的 projectID/fileID 条目没有路径，无法从磁盘复原（已在文件头登记）"
+    );
+}
+
+#[test]
+fn mrpack_fixture_round_trips_with_a_catalog_and_keeps_the_disabled_suffix() {
+    let fixture = fixtures::modrinth("rt-mr");
+    let pack = PackArchive::open_default(&fixture.zip).expect("打开 mrpack 夹具");
+    let original = MODRINTH.read(&pack).expect("读 mrpack 清单");
+
+    // 三个覆盖目录都摊到同一个实例里（实例目录不分侧）。
+    let game = instance_from(&fixture.dir, &original, "rt-mr-mr");
+    let fabric = r#"{
+      "id": "1.20.1-fabric-0.15.11",
+      "inheritsFrom": "1.20.1",
+      "libraries": [{"name": "net.fabricmc:fabric-loader:0.15.11"}]
+    }"#;
+    write_layer(&game, "1.20.1", VANILLA_LAYER);
+    write_layer(&game, "1.20.1-fabric-0.15.11", fabric);
+    // 夹具里那两条远程条目在磁盘上不存在；这里补一条**真**文件，让"远程引用"这条路径被往返到。
+    write_file(&game.join("mods/jei.jar"), b"PK\x03\x04 jei body");
+    write_file(&game.join("mods/disabled.jar.disabled"), b"PK\x03\x04 off");
+
+    let (locals, _) = crate::addon::export::scan_instance(&game, &defaults());
+    let jei = locals
+        .iter()
+        .find(|file| file.path == "mods/jei.jar")
+        .expect("jei");
+    let catalog = StubCatalog::default().with_modrinth(
+        &jei.sha1,
+        modrinth_hit(&jei.sha1, "https://cdn.modrinth.com/data/x/jei.jar"),
+    );
+    let target = game.with_file_name("mr-to-mr.mrpack");
+    let request = ExportRequest::new(&game, &target, &MODRINTH)
+        .with_name(original.name.clone())
+        .with_version(original.version.clone().unwrap_or_default())
+        .with_version_id("1.20.1-fabric-0.15.11")
+        .with_catalog(&catalog);
+    let report = export_instance(&request).expect("导出");
+    assert_eq!(report.remote_count(), 1);
+    assert!(report.is_complete());
+
+    let pack = PackArchive::open_default(&target).expect("打开导出的包");
+    let again = MODRINTH.read(&pack).expect("再读回来");
+    assert_eq!(again.name, original.name);
+    assert_eq!(again.version, original.version);
+    assert_eq!(again.minecraft, original.minecraft);
+    let loader = again.loader(LoaderKind::Fabric).expect("Fabric 加载器");
+    assert_eq!(loader.version.as_deref(), Some("0.15.11"));
+
+    // 文件集合：远程那条回来了（同一个 path），其余内联。
+    assert_eq!(again.files.len(), 1);
+    assert_eq!(again.files[0].path.as_deref(), Some("mods/jei.jar"));
+    let mut files = override_paths(&again);
+    files.sort();
+    assert_eq!(
+        files,
+        vec![
+            "config/client-only.toml".to_string(),
+            "config/known.toml".to_string(),
+            "config/server.properties".to_string(),
+            "mods/disabled.jar.disabled".to_string(),
+            "mods/half.jar".to_string(),
+        ],
+        "夹具自带的四个覆盖文件 + 新增的禁用文件"
+    );
+    // 禁用位仍然靠路径后缀表达。
+    assert!(files
+        .iter()
+        .any(|path| path == "mods/disabled.jar.disabled"));
+    assert!(pack.has_entry("overrides/mods/disabled.jar.disabled"));
+
+    // 允许的差异②：认不出的 dependency 键（夹具里的 `parchment`）不复存在——
+    // 快照只来自版本 JSON 的库坐标，`parchment` 没有对应库。
+    assert!(
+        again.loaders.iter().all(|loader| loader.kind.is_some()),
+        "非加载器依赖不回写（已在文件头登记）"
+    );
+}
+
+#[test]
+fn multimc_fixture_exports_as_mrpack_from_its_game_directory() {
+    // MultiMC/Prism **格式**的导出不做（整实例快照包，成本极高），但"把 Prism 实例的游戏目录
+    // 导出成 mrpack"是正当用例：快照从 `mmc-pack.json` 的组件表来（调用方用 `pack::multimc` 读）。
+    let instance = fixtures::multimc("rt-mmc");
+    let pack = PackArchive::open_default(&instance).expect("打开 MultiMC 实例");
+    let original = MULTIMC.read(&pack).expect("读 mmc-pack.json");
+    let snapshot = InstanceSnapshot {
+        game_version: original.minecraft.clone().expect("net.minecraft 组件"),
+        loaders: original
+            .loaders
+            .iter()
+            .filter_map(|loader| {
+                Some(SnapshotLoader {
+                    kind: loader.kind?,
+                    version: loader.version.clone()?,
+                })
+            })
+            .collect(),
+    };
+
+    let game = instance.join(".minecraft");
+    let target = instance.with_file_name("mmc.mrpack");
+    let report = export_instance(
+        &ExportRequest::new(&game, &target, &MODRINTH)
+            .with_name("MultiMC 实例导出")
+            .with_snapshot(&snapshot),
+    )
+    .expect("导出");
+    assert_eq!(report.minecraft.as_deref(), Some("1.20.1"));
+    assert_eq!(report.loaders, vec!["fabric-loader 0.15.11".to_string()]);
+    assert_eq!(report.inline_count(), 3, "{:?}", report.files);
+
+    let pack = PackArchive::open_default(&target).expect("打开导出的包");
+    let again = MODRINTH.read(&pack).expect("再读回来");
+    assert_eq!(again.minecraft.as_deref(), Some("1.20.1"));
+    assert_eq!(
+        again
+            .loader(LoaderKind::Fabric)
+            .and_then(|loader| loader.version.clone()),
+        Some("0.15.11".to_string())
+    );
+    assert_eq!(
+        override_paths(&again),
+        vec![
+            "config/known.toml".to_string(),
+            "mods/broken.jar".to_string(),
+            "mods/example.jar".to_string(),
+        ]
+    );
+    // 有意的省略：MultiMC 格式本身仍然只读不写。
+    assert!(MULTIMC.metadata_entry().is_none(), "MultiMC 导出不做");
+
+    // 重新打成 MultiMC 形状的目录以确认没有丢内容（把 overrides 解出来再比）。
+    let unpacked = temp_root("rt-mmc-unpacked");
+    for entry in pack.entries() {
+        let name = entry.name();
+        let Some(relative) = name.strip_prefix("overrides/") else {
+            continue;
+        };
+        let bytes = pack.read(name).expect("读条目").expect("有条目");
+        write_file(&unpacked.join(relative), &bytes);
+    }
+    for relative in ["config/known.toml", "mods/broken.jar", "mods/example.jar"] {
+        assert!(
+            unpacked.join(relative).is_file(),
+            "{relative} 没进包（内容丢了）"
+        );
+    }
+}
+
+#[test]
+fn a_same_format_export_is_still_allowed_and_byte_stable() {
+    // 反向对照：新管线不能把 M110 的同格式往返弄坏（r1 明确要保住的能力）。
+    let fixture = fixtures::curseforge("rt-same-cf");
+    let pack = PackArchive::open_default(&fixture.zip).expect("打开 CF 夹具");
+    let original = CURSEFORGE.read(&pack).expect("读 CF 清单");
+    let game = instance_from(&fixture.dir, &original, "rt-same-cf-game");
+    write_layer(&game, "1.20.1-forge-47.2.0", FORGE_LAYER);
+
+    let target = game.with_file_name("same.zip");
+    export_instance(
+        &ExportRequest::new(&game, &target, &CURSEFORGE)
+            .with_name(original.name.clone())
+            .with_version(original.version.clone().unwrap_or_default())
+            .with_version_id("1.20.1-forge-47.2.0"),
+    )
+    .expect("导出");
+    let pack = PackArchive::open_default(&target).expect("打开导出结果");
+    let again = CURSEFORGE.read(&pack).expect("再读回来");
+    assert_eq!(again.name, original.name);
+    assert_eq!(again.minecraft, original.minecraft);
+    assert_eq!(
+        again
+            .loader(LoaderKind::Forge)
+            .and_then(|loader| loader.version.clone()),
+        Some("47.2.0".to_string())
+    );
+    assert_eq!(override_paths(&again), override_paths(&original));
+    assert_eq!(
+        again
+            .overrides_for(PackSide::Both)
+            .map(|group| group.dir.clone()),
+        Some("overrides".to_string())
+    );
+}
diff --git a/crates/core/src/addon/pack/tests/extend.rs b/crates/core/src/addon/pack/tests/extend.rs
new file mode 100644
index 0000000..f7554ab
--- /dev/null
+++ b/crates/core/src/addon/pack/tests/extend.rs
@@ -0,0 +1,172 @@
+//! 扩展点判据：加一个假格式（**一个文件、一条注册**）就能被探测与读写，
+//! 且不碰模型、不碰 CurseForge / Modrinth / MultiMC 任何一行。
+//!
+//! 这里刻意不写"文档说它可扩展"，而是真的实现一个 `toy.json` 格式走完整条链：
+//! 注册 → 探测 → 读 → 渲染 → 写 → 再读。
+
+use serde_json::{json, Value};
+
+use super::{temp_root, write_file, write_zip};
+use crate::addon::pack::archive::PackArchive;
+use crate::addon::pack::curseforge::CURSEFORGE;
+use crate::addon::pack::error::{PackError, PackErrorKind, PackResult};
+use crate::addon::pack::format::{PackFormat, PackPayload, PackRegistry};
+use crate::addon::pack::manifest::{PackFile, PackManifest};
+
+/// 测试专用假格式：`toy.json` = `{"name": …, "minecraft": …, "mods": ["mods/a.jar"]}`。
+///
+/// 全部实现加起来不到 40 行——这就是"社区加一个新格式"的代价上限。
+#[derive(Debug)]
+struct ToyFormat;
+
+/// 注册表要的是 `&'static dyn PackFormat`，所以用 `static`。
+static TOY: ToyFormat = ToyFormat;
+
+impl PackFormat for ToyFormat {
+    fn id(&self) -> &'static str {
+        "toy"
+    }
+
+    fn label(&self) -> &'static str {
+        "Toy（测试专用假格式）"
+    }
+
+    fn metadata_entry(&self) -> Option<&'static str> {
+        Some("toy.json")
+    }
+
+    fn detect(&self, pack: &PackArchive) -> PackResult<Option<&'static str>> {
+        let Some(value) = pack.read_json("toy.json")? else {
+            return Ok(None);
+        };
+        Ok(value.is_object().then_some("toy.json"))
+    }
+
+    fn read(&self, pack: &PackArchive) -> PackResult<PackManifest> {
+        let value = pack
+            .read_json("toy.json")?
+            .ok_or_else(|| PackError::metadata("没有 toy.json"))?;
+        let files = value
+            .get("mods")
+            .and_then(Value::as_array)
+            .map(|mods| {
+                mods.iter()
+                    .filter_map(Value::as_str)
+                    .map(PackFile::with_path)
+                    .collect()
+            })
+            .unwrap_or_default();
+        Ok(PackManifest {
+            name: value
+                .get("name")
+                .and_then(Value::as_str)
+                .unwrap_or_default()
+                .to_string(),
+            minecraft: value
+                .get("minecraft")
+                .and_then(Value::as_str)
+                .map(str::to_string),
+            files,
+            ..PackManifest::default()
+        })
+    }
+
+    fn render(&self, manifest: &PackManifest) -> PackResult<String> {
+        let mods: Vec<&str> = manifest
+            .files
+            .iter()
+            .filter_map(|file| file.path.as_deref())
+            .collect();
+        Ok(json!({
+            "name": manifest.name,
+            "minecraft": manifest.minecraft,
+            "mods": mods,
+        })
+        .to_string())
+    }
+}
+
+/// 造一个 toy 包（源目录形式，顺带能当导出 payload）。
+fn toy_pack(tag: &str) -> std::path::PathBuf {
+    let dir = temp_root(tag).join("toy");
+    write_file(
+        &dir.join("toy.json"),
+        br#"{"name":"Toy Pack","minecraft":"1.21","mods":["mods/a.jar","mods/b.jar"]}"#,
+    );
+    dir
+}
+
+#[test]
+fn a_new_format_needs_one_registration_line() {
+    let dir = toy_pack("extend-register");
+    let pack = PackArchive::open_default(&dir).expect("打开 toy 包");
+
+    // ① 没注册时：内置三格式都不认它（证明它不是"顺手"被认出来的）。
+    let error = PackRegistry::builtin()
+        .detect(&pack)
+        .expect_err("内置格式不该认领 toy 包");
+    assert_eq!(error.kind(), PackErrorKind::Unsupported);
+
+    // ② 加一行注册。
+    let registry = PackRegistry::builtin().with(&TOY);
+
+    // ③ 探测得到。
+    let matched = registry.detect(&pack).expect("注册后就该探测到");
+    assert_eq!(matched.format().id(), "toy");
+    assert!(!matched.is_ambiguous());
+
+    // ④ 读得到。
+    let manifest = matched.format().read(&pack).expect("读 toy 清单");
+    assert_eq!(manifest.name, "Toy Pack");
+    assert_eq!(manifest.minecraft.as_deref(), Some("1.21"));
+    assert_eq!(manifest.files.len(), 2);
+
+    // ⑤ 渲染 + 写（默认 write 实现直接用 metadata_entry + render，不用重写一遍 zip 逻辑）。
+    let rendered = matched.format().render(&manifest).expect("渲染 toy 清单");
+    assert!(rendered.contains("Toy Pack"));
+
+    let target = dir.with_file_name("toy.zip");
+    matched
+        .format()
+        .write(&manifest, PackPayload::metadata_only(), &target)
+        .expect("导出 toy 包");
+
+    // ⑥ 再读回来必须一样。
+    let written = PackArchive::open_default(&target).expect("打开导出的 toy 包");
+    let reread = matched.format().read(&written).expect("再读 toy 清单");
+    assert_eq!(reread, manifest);
+}
+
+#[test]
+fn appending_a_format_never_steals_existing_packs() {
+    // 同一份包同时有 CF 清单与 toy 清单。
+    let root = temp_root("extend-priority");
+    let target = root.join("both.zip");
+    write_zip(
+        &target,
+        &[
+            (
+                "manifest.json",
+                &br#"{"manifestType":"minecraftModpack","manifestVersion":1,
+                     "name":"real cf pack","minecraft":{"version":"1.20.1"},"files":[]}"#[..],
+            ),
+            (
+                "toy.json",
+                &br#"{"name":"Toy shadow","minecraft":"1.21","mods":[]}"#[..],
+            ),
+        ],
+    );
+    let pack = PackArchive::open_default(&target).expect("打开包");
+
+    // 追加到末尾 = 最低优先级：老包的行为不变，但歧义要看得见。
+    let appended = PackRegistry::builtin().with(&TOY);
+    let matched = appended.detect(&pack).expect("探测");
+    assert_eq!(matched.format().id(), "curseforge");
+    assert_eq!(matched.also_matched().to_vec(), vec!["toy"]);
+
+    // 反过来排到最前，就该 toy 赢——注册顺序就是优先级。
+    let front = PackRegistry::empty().with(&TOY).with(&CURSEFORGE);
+    let matched = front.detect(&pack).expect("探测");
+    assert_eq!(matched.format().id(), "toy");
+    assert_eq!(matched.also_matched().to_vec(), vec!["curseforge"]);
+}
diff --git a/crates/core/src/addon/pack/tests/fixtures.rs b/crates/core/src/addon/pack/tests/fixtures.rs
new file mode 100644
index 0000000..565f4df
--- /dev/null
+++ b/crates/core/src/addon/pack/tests/fixtures.rs
@@ -0,0 +1,185 @@
+//! 本地夹具：CurseForge / Modrinth / MultiMC 三种格式各一个最小但**形状真实**的包。
+//!
+//! # 来源声明（不许把"看起来像"当真实）
+//!
+//! | 夹具 | 来源 | 说明 |
+//! |------|------|------|
+//! | [`curseforge`] | **手造** | 字段取自 analyse/05 §2.2（HMCL `CurseManifest` / `CurseManifestFile`）；内容与数值是编的 |
+//! | [`modrinth`] | **手造** | 字段取自 analyse/05 §2.3（HMCL `ModrinthManifest`）；`hashes` 里的摘要是**形状正确的占位值**，不对应任何真实文件 |
+//! | [`multimc`] | **手造** | 字段取自 analyse/05 §2.6（HMCL `MultiMCModpackProvider`）；组件表比真实 Prism 实例小得多 |
+//!
+//! **没有一个来自真实导出**：本任务环境离线、仓库里也没有真实整合包样本。真实导出物的字段
+//! 偏移风险只能等 M111/M115 拿到真包后回收（报告里已登记这条欠账）。
+//!
+//! # 刻意造的坏文件（导入器不许崩、也不许悄悄丢掉）
+//!
+//! - CF：`overrides/config/broken.toml` —— 截断的 TOML（引号未闭合、段落未收尾）；
+//! - mrpack：`overrides/mods/half.jar` —— 只有半个 zip 头；
+//! - MultiMC：`.minecraft/mods/broken.jar` —— 零字节。
+//!
+//! 三种损坏都是**覆盖目录里的文件**：它们没有清单声明的摘要可比，读包时只能如实记下实际
+//! SHA-1/大小（三方合并的 base 侧就是这么来的），谁想"校验并修掉"必须另做判断。
+
+use std::path::PathBuf;
+
+use super::{temp_root, write_file, zip_dir};
+
+/// 一个既有源目录（可当导出 payload）又有打好的 zip 的夹具。
+pub(crate) struct Fixture {
+    /// 源目录（zip 的内容来源，也是 `PackPayload::from_root` 的根）。
+    pub dir: PathBuf,
+    /// 打好的包。
+    pub zip: PathBuf,
+}
+
+/// CF 夹具的包名。
+pub(crate) const CF_NAME: &str = "M110 手造 CurseForge 包";
+/// CF 夹具里那个坏文件的内容。
+pub(crate) const CF_BROKEN: &[u8] = b"broken = \"unterminated\n[section\n";
+/// mrpack 夹具的包名。
+pub(crate) const MR_NAME: &str = "M110 手造 Modrinth 包";
+/// mrpack 夹具里那个半截 jar 的内容。
+pub(crate) const MR_HALF_JAR: &[u8] = b"PK\x03\x04half";
+/// MultiMC 夹具的实例名（写在 `instance.cfg`）。
+pub(crate) const MMC_NAME: &str = "M110 手造 MultiMC 实例";
+
+/// 手造的 SHA-1 占位值（40 位十六进制）。
+const FAKE_SHA1: &str = "0123456789abcdef0123456789abcdef01234567";
+/// 手造的 SHA-256 占位值（64 位十六进制）。
+const FAKE_SHA256: &str = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
+/// 手造的 SHA-512 占位值（128 位十六进制）。
+const FAKE_SHA512: &str = concat!(
+    "0123456789abcdef",
+    "0123456789abcdef",
+    "0123456789abcdef",
+    "0123456789abcdef",
+    "0123456789abcdef",
+    "0123456789abcdef",
+    "0123456789abcdef",
+    "0123456789abcdef"
+);
+
+const CF_MANIFEST: &str = r#"{
+  "manifestType": "minecraftModpack",
+  "manifestVersion": 1,
+  "name": "M110 手造 CurseForge 包",
+  "version": "1.0.0",
+  "author": "AskaEth",
+  "overrides": "overrides",
+  "minecraft": {
+    "version": "1.20.1",
+    "modLoaders": [{"id": "forge-47.2.0", "primary": true}],
+    "recommendedRam": 4096
+  },
+  "files": [
+    {"projectID": 238222, "fileID": 5102025, "required": true},
+    {"projectID": 306612, "fileID": 4587454, "required": false}
+  ],
+  "customCommunityField": {"since": 2, "note": "社区新增字段，必须原样回写"}
+}
+"#;
+
+fn mrpack_index() -> String {
+    format!(
+        r#"{{
+  "game": "minecraft",
+  "formatVersion": 1,
+  "versionId": "2.0.0",
+  "name": "{MR_NAME}",
+  "summary": "手造夹具：只验证形状与边界，不是真实导出",
+  "files": [
+    {{
+      "path": "mods/jei.jar",
+      "hashes": {{"sha1": "{FAKE_SHA1}", "sha256": "{FAKE_SHA256}", "sha512": "{FAKE_SHA512}"}},
+      "env": {{"client": "required", "server": "unsupported"}},
+      "downloads": ["https://cdn.modrinth.com/data/AANobbMI/versions/abc/jei.jar"],
+      "fileSize": 1234567,
+      "customFileField": "社区新增字段"
+    }},
+    {{
+      "path": "mods/optional.jar",
+      "hashes": {{"sha1": "{FAKE_SHA1}", "sha512": "{FAKE_SHA512}"}},
+      "env": {{"client": "optional", "server": "unsupported"}},
+      "downloads": ["https://cdn.modrinth.com/data/opt/versions/x/optional.jar"],
+      "fileSize": 11
+    }}
+  ],
+  "dependencies": {{
+    "minecraft": "1.20.1",
+    "fabric-loader": "0.15.11",
+    "parchment": "2023.09.03"
+  }},
+  "customPackField": [1, 2, 3]
+}}
+"#
+    )
+}
+
+const MMC_PACK: &str = r#"{
+  "formatVersion": 1,
+  "components": [
+    {"uid": "net.minecraft", "version": "1.20.1", "important": true, "cachedName": "1.20.1"},
+    {"uid": "net.fabricmc.fabric-loader", "version": "0.15.11"},
+    {"uid": "org.lwjgl3", "version": "3.3.2"}
+  ],
+  "customComponentGraphField": true
+}
+"#;
+
+const MMC_INSTANCE: &str = "InstanceType=OneSix\nname=M110 手造 MultiMC 实例\niconKey=default\n";
+
+/// CurseForge 夹具（`manifest.json` + `overrides/`，含一个截断的 TOML）。
+pub(crate) fn curseforge(tag: &str) -> Fixture {
+    let root = temp_root(tag);
+    let dir = root.join("src");
+    write_file(&dir.join("manifest.json"), CF_MANIFEST.as_bytes());
+    write_file(
+        &dir.join("overrides/mods/example.jar"),
+        b"PK\x03\x04 hand-made jar stub",
+    );
+    write_file(
+        &dir.join("overrides/config/known.toml"),
+        b"key = \"value\"\n",
+    );
+    write_file(&dir.join("overrides/config/broken.toml"), CF_BROKEN);
+    let zip = root.join("pack.zip");
+    zip_dir(&dir, &zip);
+    Fixture { dir, zip }
+}
+
+/// Modrinth 夹具（`modrinth.index.json` + 三个覆盖目录，含一个半截 jar）。
+pub(crate) fn modrinth(tag: &str) -> Fixture {
+    let root = temp_root(tag);
+    let dir = root.join("src");
+    write_file(&dir.join("modrinth.index.json"), mrpack_index().as_bytes());
+    write_file(&dir.join("overrides/mods/half.jar"), MR_HALF_JAR);
+    write_file(&dir.join("overrides/config/known.toml"), b"shared = true\n");
+    write_file(
+        &dir.join("client-overrides/config/client-only.toml"),
+        b"client = true\n",
+    );
+    write_file(
+        &dir.join("server-overrides/config/server.properties"),
+        b"online-mode=true\n",
+    );
+    let zip = root.join("pack.mrpack");
+    zip_dir(&dir, &zip);
+    Fixture { dir, zip }
+}
+
+/// MultiMC 夹具：**目录形式**（真实形态就是实例目录，不是 zip），含一个零字节 jar。
+pub(crate) fn multimc(tag: &str) -> PathBuf {
+    let root = temp_root(tag).join("instance");
+    write_file(&root.join("mmc-pack.json"), MMC_PACK.as_bytes());
+    write_file(&root.join("instance.cfg"), MMC_INSTANCE.as_bytes());
+    write_file(
+        &root.join(".minecraft/mods/example.jar"),
+        b"PK\x03\x04 hand-made jar stub",
+    );
+    write_file(&root.join(".minecraft/mods/broken.jar"), b"");
+    write_file(
+        &root.join(".minecraft/config/known.toml"),
+        b"key = \"value\"\n",
+    );
+    root
+}
diff --git a/crates/core/src/addon/pack/tests/mod.rs b/crates/core/src/addon/pack/tests/mod.rs
new file mode 100644
index 0000000..d4458ee
--- /dev/null
+++ b/crates/core/src/addon/pack/tests/mod.rs
@@ -0,0 +1,107 @@
+//! `addon::pack` 的单元测试：夹具读回、未知字段往返、探测优先级、扩展点、恶意样本。
+//!
+//! **全部离线**：没有网络调用，也没有真实整合包样本（见 `fixtures` 的来源声明）。
+
+mod detect;
+mod export;
+mod export_harness;
+mod export_pipeline;
+mod export_roundtrip;
+mod extend;
+mod fixtures;
+mod model;
+mod roundtrip;
+mod safety;
+mod unknown_fields;
+
+use std::fs::File;
+use std::io::Write;
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+
+/// 本次进程内唯一的临时根目录（沿用仓库既有约定：不引 `tempfile`）。
+pub(crate) fn temp_root(tag: &str) -> PathBuf {
+    static COUNTER: AtomicU64 = AtomicU64::new(0);
+    let unique = COUNTER.fetch_add(1, Ordering::Relaxed);
+    std::env::temp_dir().join(format!("ull-pack-{}-{tag}-{unique}", std::process::id()))
+}
+
+/// 写一个夹具文件（自动建父目录）。
+pub(crate) fn write_file(path: &Path, bytes: &[u8]) {
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent).expect("建夹具目录");
+    }
+    std::fs::write(path, bytes).expect("写夹具文件");
+}
+
+/// 把一个目录打成 zip（`Stored` 压缩，方便测试直接改字节）。
+pub(crate) fn zip_dir(source: &Path, target: &Path) {
+    if let Some(parent) = target.parent() {
+        std::fs::create_dir_all(parent).expect("建 zip 目录");
+    }
+    let file = File::create(target).expect("建 zip");
+    let mut writer = zip::ZipWriter::new(file);
+    let options =
+        zip::write::SimpleFileOptions::default().compression_method(zip::CompressionMethod::Stored);
+    let mut pending = vec![PathBuf::new()];
+    while let Some(relative) = pending.pop() {
+        let dir = source.join(&relative);
+        let mut children: Vec<_> = std::fs::read_dir(&dir)
+            .expect("读夹具目录")
+            .collect::<Result<Vec<_>, _>>()
+            .expect("目录项");
+        children.sort_by_key(std::fs::DirEntry::file_name);
+        for child in children {
+            let relative = relative.join(child.file_name());
+            if child.file_type().expect("夹具类型").is_dir() {
+                pending.push(relative);
+                continue;
+            }
+            let bytes = std::fs::read(child.path()).expect("读夹具文件");
+            let entry = relative.to_string_lossy().replace('\\', "/");
+            writer.start_file(entry, options).expect("写 zip 条目");
+            writer.write_all(&bytes).expect("写 zip 内容");
+        }
+    }
+    writer.finish().expect("收尾 zip");
+}
+
+/// 用一张显式条目表打 zip（恶意样本用）。
+pub(crate) fn write_zip(target: &Path, entries: &[(&str, &[u8])]) {
+    if let Some(parent) = target.parent() {
+        std::fs::create_dir_all(parent).expect("建 zip 目录");
+    }
+    let file = File::create(target).expect("建 zip");
+    let mut writer = zip::ZipWriter::new(file);
+    let options =
+        zip::write::SimpleFileOptions::default().compression_method(zip::CompressionMethod::Stored);
+    for (name, bytes) in entries {
+        writer.start_file(*name, options).expect("写 zip 条目");
+        writer.write_all(bytes).expect("写 zip 内容");
+    }
+    writer.finish().expect("收尾 zip");
+}
+
+/// 打一个带**符号链接条目**的 zip（`S_IFLNK` + 目标当内容，与真实恶意包同构）。
+pub(crate) fn write_zip_with_symlink(
+    target: &Path,
+    entries: &[(&str, &[u8])],
+    link_name: &str,
+    link_target: &str,
+) {
+    if let Some(parent) = target.parent() {
+        std::fs::create_dir_all(parent).expect("建 zip 目录");
+    }
+    let file = File::create(target).expect("建 zip");
+    let mut writer = zip::ZipWriter::new(file);
+    let options =
+        zip::write::SimpleFileOptions::default().compression_method(zip::CompressionMethod::Stored);
+    for (name, bytes) in entries {
+        writer.start_file(*name, options).expect("写 zip 条目");
+        writer.write_all(bytes).expect("写 zip 内容");
+    }
+    writer
+        .add_symlink(link_name, link_target, options)
+        .expect("写符号链接条目");
+    writer.finish().expect("收尾 zip");
+}
diff --git a/crates/core/src/addon/pack/tests/model.rs b/crates/core/src/addon/pack/tests/model.rs
new file mode 100644
index 0000000..ad229a2
--- /dev/null
+++ b/crates/core/src/addon/pack/tests/model.rs
@@ -0,0 +1,111 @@
+//! 模型级辅助与读取预算：r1 p2-2（跨侧重名）与 p3-4（批量读取的累计限额）。
+
+use super::fixtures;
+use crate::addon::pack::archive::{PackArchive, ReadBudget};
+use crate::addon::pack::error::PackErrorKind;
+use crate::addon::pack::manifest::{OverrideFile, PackManifest, PackOverrides, PackSide};
+
+fn file(path: &str, sha1: &str, size: u64) -> OverrideFile {
+    OverrideFile {
+        path: path.to_string(),
+        sha1: sha1.to_string(),
+        size,
+    }
+}
+
+#[test]
+fn duplicate_override_paths_counts_across_sides_not_per_side() {
+    // r1 p2-2：mrpack 的真实冲突是 `overrides`(Both) 与 `client-overrides`(Client) 撞同一路径，
+    // 按 `(side, path)` 计数时两侧键天然不同 ⇒ 永远返回空表。
+    let mut both = PackOverrides::new("overrides", PackSide::Both);
+    both.files.push(file("config/x.toml", "a", 1));
+    both.files.push(file("config/only-both.toml", "b", 1));
+    let mut client = PackOverrides::new("client-overrides", PackSide::Client);
+    client.files.push(file("config/x.toml", "c", 2));
+    let mut server = PackOverrides::new("server-overrides", PackSide::Server);
+    server.files.push(file("config/only-server.toml", "d", 3));
+    let manifest = PackManifest {
+        overrides: vec![both, client, server],
+        ..PackManifest::default()
+    };
+
+    assert_eq!(
+        manifest.duplicate_override_paths(),
+        vec![(
+            "config/x.toml".to_string(),
+            vec![PackSide::Both, PackSide::Client],
+            2
+        )],
+        "只报真正撞车的路径，并给出涉及的侧与条目份数"
+    );
+}
+
+#[test]
+fn duplicate_override_paths_still_reports_two_groups_on_the_same_side() {
+    // r2 p2-2：上一版按侧去重，把这半能力换掉了 —— 两个 Both 组撞同一路径实测返回 `[]`。
+    // 现在判据是「侧数 > 1 || 条份数 > 侧数」，两种冲突同时报得出来。
+    let mut first = PackOverrides::new("overrides", PackSide::Both);
+    first.files.push(file("config/x.toml", "a", 1));
+    let mut second = PackOverrides::new("extra-overrides", PackSide::Both);
+    second.files.push(file("config/x.toml", "b", 2));
+    let manifest = PackManifest {
+        overrides: vec![first, second],
+        ..PackManifest::default()
+    };
+    assert_eq!(
+        manifest.duplicate_override_paths(),
+        vec![("config/x.toml".to_string(), vec![PackSide::Both], 2)],
+        "同侧两个组撞同一路径必须报（侧集合只有一个，份数是 2）"
+    );
+}
+
+#[test]
+fn duplicate_override_paths_reports_the_same_path_twice_inside_one_group() {
+    // 同侧撞车的另一种形态：一个组里同一路径列了两次（模型被合并出来时会出现）。
+    let mut group = PackOverrides::new("overrides", PackSide::Both);
+    group.files.push(file("config/x.toml", "a", 1));
+    group.files.push(file("config/x.toml", "b", 2));
+    let manifest = PackManifest {
+        overrides: vec![group],
+        ..PackManifest::default()
+    };
+    assert_eq!(
+        manifest.duplicate_override_paths(),
+        vec![("config/x.toml".to_string(), vec![PackSide::Both], 2)]
+    );
+}
+
+#[test]
+fn duplicate_override_paths_is_empty_when_nothing_collides() {
+    let mut both = PackOverrides::new("overrides", PackSide::Both);
+    both.files.push(file("config/a.toml", "a", 1));
+    let mut client = PackOverrides::new("client-overrides", PackSide::Client);
+    client.files.push(file("config/b.toml", "b", 1));
+    let manifest = PackManifest {
+        overrides: vec![both, client],
+        ..PackManifest::default()
+    };
+    assert!(manifest.duplicate_override_paths().is_empty());
+}
+
+#[test]
+fn a_batch_scan_spends_one_cumulative_budget() {
+    // r1 p3-4：打开阶段只能看声明大小；批量读取（override_files）必须按**实际字节**累计扣减，
+    // 否则"很多条各自合规"累起来就能绕过 `max_uncompressed_bytes`（CPU/时间 DoS）。
+    let fixture = fixtures::modrinth("budget");
+    let pack = PackArchive::open_default(&fixture.zip).expect("打开 mrpack 夹具");
+
+    let generous = ReadBudget::new(1024 * 1024);
+    let files = pack
+        .override_files_with("overrides", &generous)
+        .expect("预算够时必须成功");
+    assert_eq!(files.len(), 2);
+
+    // 预算只有 4 字节：第一个文件（config/known.toml，15 字节）就该把预算吃穿。
+    let tight = ReadBudget::new(4);
+    let error = pack
+        .override_files_with("overrides", &tight)
+        .expect_err("累计预算必须生效");
+    assert_eq!(error.kind(), PackErrorKind::Limits, "{error}");
+    assert_eq!(tight.remaining(), 0, "失败后预算不该被退回");
+}
diff --git a/crates/core/src/addon/pack/tests/roundtrip.rs b/crates/core/src/addon/pack/tests/roundtrip.rs
new file mode 100644
index 0000000..6e891ce
--- /dev/null
+++ b/crates/core/src/addon/pack/tests/roundtrip.rs
@@ -0,0 +1,306 @@
+//! 读回模型 + "导出后再读"的往返一致性：**未知字段不丢**就在这些断言里被钉住。
+
+use serde_json::json;
+
+use super::fixtures;
+use crate::addon::pack::archive::PackArchive;
+use crate::addon::pack::curseforge::CURSEFORGE;
+use crate::addon::pack::error::PackErrorKind;
+use crate::addon::pack::format::{PackFormat, PackPayload, PackRegistry};
+use crate::addon::pack::manifest::{EnvSupport, PackManifest, PackSide};
+use crate::addon::pack::modrinth::MODRINTH;
+use crate::addon::pack::multimc::MULTIMC;
+use crate::addon::LoaderKind;
+use crate::download::{verify, HashAlgo};
+
+fn sha1_hex(bytes: &[u8]) -> String {
+    verify::digest_bytes(HashAlgo::Sha1, bytes)
+}
+
+#[test]
+fn curseforge_reads_into_model() {
+    let fixture = fixtures::curseforge("cf-read");
+    let pack = PackArchive::open_default(&fixture.zip).expect("打开 CF 夹具");
+    let manifest = CURSEFORGE.read(&pack).expect("读 CF 清单");
+
+    assert_eq!(manifest.name, fixtures::CF_NAME);
+    assert_eq!(manifest.version.as_deref(), Some("1.0.0"));
+    assert_eq!(manifest.author.as_deref(), Some("AskaEth"));
+    assert_eq!(manifest.summary, None, "CF 没有 summary 字段");
+    assert_eq!(manifest.minecraft.as_deref(), Some("1.20.1"));
+    assert_eq!(manifest.game, None, "CF 没有 game 字段");
+    assert_eq!(manifest.format_version, Some(1));
+
+    assert_eq!(manifest.loaders.len(), 1);
+    let loader = &manifest.loaders[0];
+    assert_eq!(loader.raw, "forge-47.2.0");
+    assert_eq!(loader.kind, Some(LoaderKind::Forge));
+    assert_eq!(loader.version.as_deref(), Some("47.2.0"));
+    assert!(loader.primary, "primary=true 必须保住");
+
+    // CF 官方 files[] 没有路径/URL/摘要：模型如实记成 None，不猜。
+    assert_eq!(manifest.files.len(), 2);
+    let required = &manifest.files[0];
+    assert_eq!(required.project_id, Some(238222));
+    assert_eq!(required.file_id, Some(5102025));
+    assert_eq!(required.path, None);
+    assert_eq!(required.client, EnvSupport::Required);
+    assert_eq!(required.key(), "curseforge:238222:5102025");
+    let optional = &manifest.files[1];
+    assert_eq!(
+        optional.client,
+        EnvSupport::Optional,
+        "required=false → Optional"
+    );
+    assert_eq!(optional.server, EnvSupport::Optional);
+
+    // 覆盖目录：3 个文件，含那个刻意截断的 TOML（它没有清单摘要可比，只能记实测值）。
+    assert_eq!(manifest.overrides.len(), 1);
+    let group = &manifest.overrides[0];
+    assert_eq!(group.dir, "overrides");
+    assert_eq!(group.side, PackSide::Both);
+    assert_eq!(group.files.len(), 3);
+    let broken = group.find("config/broken.toml").expect("坏文件也要进清单");
+    assert_eq!(broken.size, fixtures::CF_BROKEN.len() as u64);
+    assert_eq!(broken.sha1, sha1_hex(fixtures::CF_BROKEN));
+
+    // 未知字段：顶层与 `minecraft` 对象各一处。
+    assert_eq!(manifest.extra["customCommunityField"]["since"], json!(2));
+    assert_eq!(manifest.minecraft_extra["recommendedRam"], json!(4096));
+}
+
+#[test]
+fn curseforge_export_round_trips_unknown_fields() {
+    let fixture = fixtures::curseforge("cf-roundtrip");
+    let pack = PackArchive::open_default(&fixture.zip).expect("打开 CF 夹具");
+    let manifest = CURSEFORGE.read(&pack).expect("读 CF 清单");
+
+    let target = fixture.zip.with_file_name("rewritten.zip");
+    CURSEFORGE
+        .write(&manifest, PackPayload::from_root(&fixture.dir), &target)
+        .expect("导出 CF 包");
+
+    let written = PackArchive::open_default(&target).expect("打开导出的 CF 包");
+    let reread = CURSEFORGE.read(&written).expect("再读导出的 CF 包");
+    assert_eq!(reread, manifest, "导出→再读必须逐字段相等（含未知字段）");
+    assert_eq!(
+        reread.extra["customCommunityField"]["note"],
+        json!("社区新增字段，必须原样回写")
+    );
+    assert_eq!(reread.minecraft_extra["recommendedRam"], json!(4096));
+}
+
+#[test]
+fn modrinth_reads_into_model() {
+    let fixture = fixtures::modrinth("mr-read");
+    let pack = PackArchive::open_default(&fixture.zip).expect("打开 mrpack 夹具");
+    let manifest = MODRINTH.read(&pack).expect("读 mrpack 清单");
+
+    assert_eq!(manifest.name, fixtures::MR_NAME);
+    assert_eq!(manifest.version.as_deref(), Some("2.0.0"));
+    assert_eq!(
+        manifest.summary.as_deref(),
+        Some("手造夹具：只验证形状与边界，不是真实导出")
+    );
+    assert_eq!(manifest.game.as_deref(), Some("minecraft"));
+    assert_eq!(manifest.minecraft.as_deref(), Some("1.20.1"));
+    assert_eq!(manifest.author, None, "mrpack 没有 author 字段");
+
+    // `dependencies` 里非 minecraft 的每条都成一条加载器依赖（认不出的也保留）。
+    assert_eq!(manifest.loaders.len(), 2);
+    let fabric = manifest
+        .loader(LoaderKind::Fabric)
+        .expect("要认出 fabric-loader");
+    assert_eq!(fabric.raw, "fabric-loader");
+    assert_eq!(fabric.version.as_deref(), Some("0.15.11"));
+    assert!(fabric.primary);
+    let parchment = manifest
+        .loaders
+        .iter()
+        .find(|loader| loader.raw == "parchment")
+        .expect("社区键也要保留");
+    assert_eq!(parchment.kind, None);
+    assert_eq!(parchment.version.as_deref(), Some("2023.09.03"));
+
+    assert_eq!(manifest.files.len(), 2);
+    let jei = &manifest.files[0];
+    assert_eq!(jei.path.as_deref(), Some("mods/jei.jar"));
+    assert_eq!(jei.size, Some(1_234_567));
+    assert_eq!(jei.client, EnvSupport::Required);
+    assert_eq!(jei.server, EnvSupport::Unsupported);
+    assert_eq!(jei.downloads.len(), 1);
+    assert!(jei.hashes.contains_key("sha256"), "整张摘要表都要留着");
+    assert!(jei.sha512().is_some());
+    assert!(jei.key().starts_with("modrinth:"));
+    assert_eq!(jei.extra["customFileField"], json!("社区新增字段"));
+    let optional = &manifest.files[1];
+    assert!(optional.client.is_optional(), "env.client=optional 要保住");
+
+    // 三个覆盖目录各成一侧。
+    assert_eq!(manifest.overrides.len(), 3);
+    let both = manifest.overrides_for(PackSide::Both).expect("overrides");
+    assert_eq!(both.files.len(), 2);
+    let client = manifest
+        .overrides_for(PackSide::Client)
+        .expect("client-overrides");
+    assert_eq!(client.files.len(), 1);
+    let server = manifest
+        .overrides_for(PackSide::Server)
+        .expect("server-overrides");
+    assert_eq!(server.files.len(), 1);
+    let half = both.find("mods/half.jar").expect("半截 jar 也要进清单");
+    assert_eq!(half.size, fixtures::MR_HALF_JAR.len() as u64);
+    assert_eq!(half.sha1, sha1_hex(fixtures::MR_HALF_JAR));
+
+    assert_eq!(manifest.extra["customPackField"], json!([1, 2, 3]));
+}
+
+#[test]
+fn modrinth_export_round_trips_unknown_fields() {
+    let fixture = fixtures::modrinth("mr-roundtrip");
+    let pack = PackArchive::open_default(&fixture.zip).expect("打开 mrpack 夹具");
+    let manifest = MODRINTH.read(&pack).expect("读 mrpack 清单");
+
+    let target = fixture.zip.with_file_name("rewritten.mrpack");
+    MODRINTH
+        .write(&manifest, PackPayload::from_root(&fixture.dir), &target)
+        .expect("导出 mrpack");
+
+    let written = PackArchive::open_default(&target).expect("打开导出的 mrpack");
+    let reread = MODRINTH.read(&written).expect("再读导出的 mrpack");
+    assert_eq!(reread, manifest, "导出→再读必须逐字段相等（含未知字段）");
+    assert_eq!(reread.extra["customPackField"], json!([1, 2, 3]));
+}
+
+#[test]
+fn multimc_reads_instance_directory() {
+    let root = fixtures::multimc("mmc-read");
+    let pack = PackArchive::open_default(&root).expect("打开 MultiMC 实例目录");
+    assert!(pack.is_dir_source());
+    let manifest = MULTIMC.read(&pack).expect("读 MultiMC 清单");
+
+    assert_eq!(manifest.name, fixtures::MMC_NAME, "包名来自 instance.cfg");
+    assert_eq!(manifest.minecraft.as_deref(), Some("1.20.1"));
+    assert_eq!(manifest.game.as_deref(), Some("minecraft"));
+    assert_eq!(manifest.format_version, Some(1));
+    assert_eq!(manifest.version, None, "MultiMC 的实例没有包版本");
+
+    let fabric = manifest
+        .loader(LoaderKind::Fabric)
+        .expect("组件 uid 要翻译成加载器");
+    assert_eq!(fabric.raw, "net.fabricmc.fabric-loader");
+    assert_eq!(fabric.version.as_deref(), Some("0.15.11"));
+    assert!(fabric.primary);
+    assert!(
+        manifest
+            .loaders
+            .iter()
+            .any(|loader| loader.raw == "org.lwjgl3"),
+        "认不出的组件也要保留"
+    );
+
+    assert!(manifest.files.is_empty(), "MultiMC 没有远端条目");
+    let content = manifest
+        .overrides_for(PackSide::Both)
+        .expect(".minecraft 当覆盖目录");
+    assert_eq!(content.dir, ".minecraft");
+    let broken = content
+        .find("mods/broken.jar")
+        .expect("零字节 jar 也要进清单");
+    assert_eq!(broken.size, 0);
+    assert_eq!(broken.sha1, sha1_hex(b""));
+    assert_eq!(content.files.len(), 3);
+    assert_eq!(manifest.extra["customComponentGraphField"], json!(true));
+}
+
+#[test]
+fn multimc_export_is_refused() {
+    let root = super::temp_root("mmc-write");
+    let target = root.join("out.zip");
+    let manifest = PackManifest::new("whatever");
+    let error = MULTIMC
+        .write(&manifest, PackPayload::metadata_only(), &target)
+        .expect_err("MultiMC 格式不支持导出");
+    assert_eq!(error.kind(), PackErrorKind::Unsupported);
+    assert!(!target.exists(), "拒绝导出时不该留下半个文件");
+}
+
+#[test]
+fn registry_read_reports_matched_format() {
+    let fixture = fixtures::curseforge("registry-read");
+    let pack = PackArchive::open_default(&fixture.zip).expect("打开 CF 夹具");
+    let (format, manifest) = PackRegistry::builtin().read(&pack).expect("探测 + 读");
+    assert_eq!(format.id(), "curseforge");
+    assert_eq!(manifest.name, fixtures::CF_NAME);
+}
+
+#[test]
+fn curseforge_without_name_is_a_metadata_error() {
+    let root = super::temp_root("cf-noname");
+    let target = root.join("nope.zip");
+    super::write_zip(
+        &target,
+        &[(
+            "manifest.json",
+            &br#"{"manifestType":"minecraftModpack","minecraft":{"version":"1.20.1"}}"#[..],
+        )],
+    );
+    let pack = PackArchive::open_default(&target).expect("zip 本身可读");
+    assert_eq!(
+        CURSEFORGE.detect(&pack).expect("清单可读"),
+        Some("manifest.json"),
+        "形状对得上就该被探测到"
+    );
+    let error = CURSEFORGE.read(&pack).expect_err("缺 name 必须报错");
+    assert_eq!(error.kind(), PackErrorKind::Metadata);
+}
+
+#[test]
+fn disabled_entries_export_as_path_suffix_on_mrpack_and_required_false_on_curseforge() {
+    // 禁用位（M115 调研 §字段缺口 2 / §8.1）在两边的落法不同，且都不该靠"猜"：
+    // mrpack → `files[].path` 结尾 `.disabled`（官方导出的表达，**不是** env.client=optional：
+    // 后者只是"安装时可取消勾选"，装回来默认仍然启用 ⇒ 跨启动器不保真）；
+    // CF → 没有原生表达，格式层只能写 `required: false`（Prism 同款）；导出**管线**更严：
+    // 禁用文件直接内联进 overrides/ 并保留后缀（见 export::pipeline 的 DisabledNotExpressible）。
+    let cf = fixtures::curseforge("disabled-cf");
+    let pack = PackArchive::open_default(&cf.zip).expect("打开 CF 夹具");
+    let mut manifest = CURSEFORGE.read(&pack).expect("读 CF 清单");
+    assert!(!manifest.files[0].disabled, "读包不会凭空造出禁用位");
+    manifest.files[0].disabled = true;
+    let target = cf.zip.with_file_name("disabled.zip");
+    CURSEFORGE
+        .write(&manifest, PackPayload::from_root(&cf.dir), &target)
+        .expect("导出 CF");
+    let written = PackArchive::open_default(&target).expect("打开导出的 CF 包");
+    let reread = CURSEFORGE.read(&written).expect("再读 CF");
+    assert_eq!(
+        reread.files[0].client,
+        EnvSupport::Optional,
+        "CF 没有禁用表达，格式层只能落 required=false"
+    );
+
+    let mr = fixtures::modrinth("disabled-mr");
+    let pack = PackArchive::open_default(&mr.zip).expect("打开 mrpack 夹具");
+    let mut manifest = MODRINTH.read(&pack).expect("读 mrpack 清单");
+    assert!(
+        !manifest.files[1].disabled,
+        "env.client=optional 是「可选」，不是「禁用」：两个事实不合并"
+    );
+    manifest.files[0].disabled = true;
+    let target = mr.zip.with_file_name("disabled.mrpack");
+    MODRINTH
+        .write(&manifest, PackPayload::from_root(&mr.dir), &target)
+        .expect("导出 mrpack");
+    let written = PackArchive::open_default(&target).expect("打开导出的 mrpack");
+    let reread = MODRINTH.read(&written).expect("再读 mrpack");
+    assert_eq!(
+        reread.files[0].path.as_deref(),
+        Some("mods/jei.jar.disabled"),
+        "禁用靠路径后缀表达（官方导出的做法，跨启动器保真）"
+    );
+    assert_eq!(
+        reread.files[0].client,
+        EnvSupport::Required,
+        "禁用不再被翻译成 env.client=optional（tower 定案）"
+    );
+}
diff --git a/crates/core/src/addon/pack/tests/safety.rs b/crates/core/src/addon/pack/tests/safety.rs
new file mode 100644
index 0000000..dad4f55
--- /dev/null
+++ b/crates/core/src/addon/pack/tests/safety.rs
@@ -0,0 +1,312 @@
+//! 恶意样本：每条安全判据都配一条"会失败的包"，而不是靠注释保证。
+//!
+//! 覆盖：路径穿越四类形状（`..` / 绝对路径 / 反斜杠 / 盘符）、符号链接条目、条目数上限、
+//! 解压总体积上限、单条目上限、规整后重名、篡改载荷（CRC 不符）、以及**清单字段里的**穿越
+//! （mrpack `files[].path`、CF `overrides`）。
+
+use std::path::{Path, PathBuf};
+
+use super::{temp_root, write_zip, write_zip_with_symlink};
+use crate::addon::pack::archive::{PackArchive, PackLimits};
+use crate::addon::pack::curseforge::CURSEFORGE;
+use crate::addon::pack::error::PackErrorKind;
+use crate::addon::pack::format::PackFormat;
+use crate::addon::pack::manifest::{PackLoader, PackManifest, PackOverrides, PackSide};
+use crate::addon::pack::modrinth::MODRINTH;
+
+/// 打一个只有一条恶意条目的 zip。
+fn single_entry(tag: &str, name: &str) -> PathBuf {
+    let target = temp_root(tag).join("evil.zip");
+    write_zip(&target, &[(name, &b"payload"[..])]);
+    target
+}
+
+fn open_error(target: &Path) -> crate::addon::pack::error::PackError {
+    PackArchive::open_default(target).expect_err("恶意包必须被拒")
+}
+
+#[test]
+fn rejects_parent_directory_entries() {
+    let target = single_entry("trav-parent", "../evil.txt");
+    let error = open_error(&target);
+    assert_eq!(
+        error.kind(),
+        PackErrorKind::Traversal,
+        "{}",
+        error.message()
+    );
+}
+
+#[test]
+fn rejects_absolute_entries() {
+    let target = single_entry("trav-absolute", "/etc/passwd");
+    let error = open_error(&target);
+    assert_eq!(
+        error.kind(),
+        PackErrorKind::Traversal,
+        "{}",
+        error.message()
+    );
+}
+
+#[test]
+fn rejects_backslash_separators() {
+    // Win32 把 `\` 当分隔符：按 `/` 切是"一个普通名字"，落盘却跳三层。
+    let target = single_entry("trav-backslash", "mods\\..\\..\\evil.jar");
+    let error = open_error(&target);
+    assert_eq!(
+        error.kind(),
+        PackErrorKind::Traversal,
+        "{}",
+        error.message()
+    );
+}
+
+#[test]
+fn rejects_drive_letter_and_ads_entries() {
+    for (tag, name) in [
+        ("trav-drive", "C:/Windows/evil.dll"),
+        ("trav-ads", "mods/jei.jar:Zone.Identifier"),
+    ] {
+        let target = single_entry(tag, name);
+        let error = open_error(&target);
+        assert_eq!(
+            error.kind(),
+            PackErrorKind::Traversal,
+            "{name}: {}",
+            error.message()
+        );
+    }
+}
+
+#[test]
+fn rejects_symlink_entries() {
+    let target = temp_root("symlink").join("link.zip");
+    write_zip_with_symlink(
+        &target,
+        &[("readme.txt", &b"x"[..])],
+        "mods/evil.jar",
+        "../../../etc/passwd",
+    );
+    let error = open_error(&target);
+    assert_eq!(error.kind(), PackErrorKind::Symlink, "{}", error.message());
+}
+
+#[test]
+fn rejects_too_many_entries() {
+    let target = temp_root("limit-count").join("many.zip");
+    write_zip(
+        &target,
+        &[
+            ("a.txt", &b"1"[..]),
+            ("b.txt", &b"2"[..]),
+            ("c.txt", &b"3"[..]),
+            ("d.txt", &b"4"[..]),
+        ],
+    );
+    let error = PackArchive::open(&target, PackLimits::new(3, 1024 * 1024, 1024 * 1024))
+        .expect_err("条目数超限必须拒");
+    assert_eq!(error.kind(), PackErrorKind::Limits, "{}", error.message());
+}
+
+#[test]
+fn rejects_uncompressed_volume_over_limit() {
+    let target = temp_root("limit-volume").join("big.zip");
+    let payload = vec![b'a'; 4096];
+    write_zip(
+        &target,
+        &[("a.bin", payload.as_slice()), ("b.bin", payload.as_slice())],
+    );
+    let error = PackArchive::open(&target, PackLimits::new(16, 4096, 4096))
+        .expect_err("解压总体积超限必须拒");
+    assert_eq!(error.kind(), PackErrorKind::Limits, "{}", error.message());
+}
+
+#[test]
+fn rejects_a_single_oversized_entry() {
+    let target = temp_root("limit-entry").join("big.zip");
+    let payload = vec![b'a'; 2048];
+    write_zip(&target, &[("a.bin", payload.as_slice())]);
+    let error = PackArchive::open(&target, PackLimits::new(16, 1024 * 1024, 512))
+        .expect_err("单条目超限必须拒");
+    assert_eq!(error.kind(), PackErrorKind::Limits, "{}", error.message());
+}
+
+#[test]
+fn rejects_names_that_collide_after_normalization() {
+    // `./a.txt` 与 `a.txt` 规整后同名：留着就是"读到的和落盘的"不是同一个文件的经典混淆。
+    let target = temp_root("dup-name").join("dup.zip");
+    write_zip(&target, &[("./a.txt", &b"1"[..]), ("a.txt", &b"2"[..])]);
+    let error = open_error(&target);
+    assert_eq!(error.kind(), PackErrorKind::Metadata, "{}", error.message());
+}
+
+#[test]
+fn a_tampered_payload_is_not_silently_accepted() {
+    // 中央目录没问题、数据被改过（CRC 不符）：打开能过，读内容必须报错。
+    const MARKER: &[u8] = b"UNIQUE-PAYLOAD-MARKER";
+    let target = temp_root("tampered").join("tampered.zip");
+    write_zip(
+        &target,
+        &[
+            (
+                "manifest.json",
+                br#"{"manifestType":"minecraftModpack","manifestVersion":1,
+                     "name":"tampered pack","minecraft":{"version":"1.20.1"},"files":[],
+                     "overrides":"overrides"}"#,
+            ),
+            ("overrides/config/bad.toml", MARKER),
+        ],
+    );
+    let mut bytes = std::fs::read(&target).expect("读 zip");
+    let at = bytes
+        .windows(MARKER.len())
+        .position(|window| window == MARKER)
+        .expect("找得到载荷");
+    bytes[at] = b'X';
+    std::fs::write(&target, bytes).expect("写回 zip");
+
+    let pack = PackArchive::open_default(&target).expect("中央目录完好，打开该成功");
+    let error = pack
+        .read("overrides/config/bad.toml")
+        .expect_err("载荷被改过，读内容必须失败");
+    assert!(
+        matches!(error.kind(), PackErrorKind::Io | PackErrorKind::Metadata),
+        "实际大类：{:?}（{}）",
+        error.kind(),
+        error.message()
+    );
+    // 整包读取会算覆盖文件的 SHA-1，因此也必须失败，而不是"算出一个错的哈希"。
+    assert!(CURSEFORGE.read(&pack).is_err());
+}
+
+#[test]
+fn mrpack_file_path_traversal_is_rejected() {
+    let target = temp_root("mr-trav").join("evil.mrpack");
+    let index = r#"{"game":"minecraft","formatVersion":1,"versionId":"1.0","name":"evil pack",
+      "files":[{"path":"../evil.jar",
+                "hashes":{"sha512":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"},
+                "downloads":["https://example.invalid/evil.jar"]}],
+      "dependencies":{"minecraft":"1.20.1"}}"#;
+    write_zip(&target, &[("modrinth.index.json", index.as_bytes())]);
+    let pack = PackArchive::open_default(&target).expect("zip 本身可读");
+    let error = MODRINTH.read(&pack).expect_err("清单里的穿越路径必须拒");
+    assert_eq!(
+        error.kind(),
+        PackErrorKind::Traversal,
+        "{}",
+        error.message()
+    );
+}
+
+#[test]
+fn curseforge_overrides_dir_traversal_is_rejected() {
+    let target = temp_root("cf-trav").join("evil.zip");
+    write_zip(
+        &target,
+        &[(
+            "manifest.json",
+            br#"{"manifestType":"minecraftModpack","manifestVersion":1,"name":"evil pack",
+                 "minecraft":{"version":"1.20.1"},"files":[],"overrides":"../../etc"}"#,
+        )],
+    );
+    let pack = PackArchive::open_default(&target).expect("zip 本身可读");
+    let error = CURSEFORGE
+        .read(&pack)
+        .expect_err("overrides 目录指向包外必须拒");
+    assert_eq!(
+        error.kind(),
+        PackErrorKind::Traversal,
+        "{}",
+        error.message()
+    );
+}
+
+#[test]
+fn write_side_path_check_catches_hand_built_models() {
+    // 模型可能不是我们读出来的（UI/AI 手搓）：导出前必须再查一遍。
+    let mut manifest = PackManifest::new("手搓模型");
+    manifest.overrides.push(PackOverrides {
+        dir: "overrides".to_string(),
+        side: PackSide::Both,
+        files: Vec::new(),
+    });
+    manifest
+        .loaders
+        .push(PackLoader::parse_curse("forge-47.2.0", true));
+    assert!(manifest.check_paths().is_ok());
+
+    manifest.overrides[0].dir = "../escape".to_string();
+    assert_eq!(
+        manifest
+            .check_paths()
+            .expect_err("越界目录必须被写侧检查拦下")
+            .kind(),
+        PackErrorKind::Traversal
+    );
+}
+
+#[test]
+fn missing_package_is_an_io_error() {
+    let target = temp_root("missing").join("does-not-exist.zip");
+    let error = open_error(&target);
+    assert_eq!(error.kind(), PackErrorKind::Io, "{}", error.message());
+}
+
+#[test]
+fn directory_source_rejects_symlinks_when_the_platform_can_make_them() {
+    // Windows 建符号链接需要开发者模式/管理员：建不出来就跳过，但绝不静默当通过。
+    #[cfg(unix)]
+    {
+        let root = temp_root("dir-symlink").join("instance");
+        std::fs::create_dir_all(&root).expect("建目录");
+        std::fs::write(root.join("mmc-pack.json"), b"{}").expect("写文件");
+        std::os::unix::fs::symlink("/etc/passwd", root.join("escape")).expect("建符号链接");
+        let error = open_error(&root);
+        assert_eq!(error.kind(), PackErrorKind::Symlink, "{}", error.message());
+    }
+    #[cfg(not(unix))]
+    {
+        eprintln!(
+            "跳过：当前平台建符号链接需要额外权限（目录侧的检查逻辑与 zip 侧共用同一条判据）"
+        );
+    }
+}
+
+#[test]
+#[cfg(windows)]
+fn the_second_check_catches_windows_device_names_and_dot_suffixes() {
+    // r1 p2-3：第一检（平台无关的七条）对这些名字是**放行**的，拦下它们的是第二检
+    // `enclosed_name()` 的 Win32 命名空间规则（DOS 设备名、结尾点/空格、`< > " | ? *`）。
+    // 删掉第二检，这条用例必须红——这是「双检各有一条恶意样本」的第二条。
+    for (tag, name) in [
+        ("dev-con", "CON"),
+        ("dev-nul-nested", "mods/NUL"),
+        ("dev-com1", "COM1.txt"),
+        ("dev-trailing-dot", "a."),
+        ("dev-trailing-space", "mods/b "),
+        ("dev-wildcard", "mods/*.jar"),
+    ] {
+        let target = single_entry(tag, name);
+        let error = open_error(&target);
+        assert_eq!(
+            error.kind(),
+            PackErrorKind::Traversal,
+            "{name}: {}",
+            error.message()
+        );
+        assert!(
+            error.message().contains("enclosed_name"),
+            "{name} 必须是被第二检拦下的（不然这条用例钉错了地方）：{}",
+            error.message()
+        );
+    }
+
+    // 对照：第一检对这些名字没有任何意见（所以它们只能靠第二检）。
+    for name in ["CON", "mods/NUL", "a.", "mods/b ", "mods/*.jar"] {
+        assert!(
+            crate::addon::pack::path::normalize_file(name).is_ok(),
+            "第一检不该拦 {name}（拦了这条用例就失去意义）"
+        );
+    }
+}
diff --git a/crates/core/src/addon/pack/tests/unknown_fields.rs b/crates/core/src/addon/pack/tests/unknown_fields.rs
new file mode 100644
index 0000000..bc7fa79
--- /dev/null
+++ b/crates/core/src/addon/pack/tests/unknown_fields.rs
@@ -0,0 +1,113 @@
+//! 「未知字段不丢」的三处条目级 flatten（r1 p3-3）：`env_extra`、CF `files[].extra`、
+//! `PackLoader::extra`。三处实现本来是对的，但此前一条断言都没有——而它们恰好是 M115 点名的
+//! HMCL 回写 `fileName`/`url` 的位置。每条都走「读 → render → 写整包 → 再读逐字段相等」。
+
+use serde_json::json;
+
+use crate::addon::pack::archive::PackArchive;
+use crate::addon::pack::curseforge::CURSEFORGE;
+use crate::addon::pack::format::{PackFormat, PackPayload};
+use crate::addon::pack::modrinth::MODRINTH;
+
+#[test]
+fn mrpack_env_unknown_keys_survive_read_write_reread() {
+    // r1 p3-3 的一处：`files[].env` 里的未知键（`env_extra`）此前没有任何断言。
+    let root = super::temp_root("env-extra");
+    let dir = root.join("src");
+    super::write_file(
+        &dir.join("modrinth.index.json"),
+        br#"{"game":"minecraft","formatVersion":1,"versionId":"1.0","name":"env extra keys",
+             "files":[{"path":"mods/a.jar",
+                       "hashes":{"sha512":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"},
+                       "env":{"client":"required","server":"unsupported","customEnvKey":{"k":1}},
+                       "downloads":["https://example.invalid/a.jar"]}],
+             "dependencies":{"minecraft":"1.20.1"}}"#,
+    );
+    let zip = root.join("pack.mrpack");
+    super::zip_dir(&dir, &zip);
+
+    let pack = PackArchive::open_default(&zip).expect("打开包");
+    let manifest = MODRINTH.read(&pack).expect("读 mrpack 清单");
+    assert_eq!(manifest.files[0].env_extra["customEnvKey"], json!({"k": 1}));
+
+    let target = root.join("out.mrpack");
+    MODRINTH
+        .write(&manifest, PackPayload::metadata_only(), &target)
+        .expect("导出 mrpack");
+    let reread = MODRINTH
+        .read(&PackArchive::open_default(&target).expect("打开导出包"))
+        .expect("再读");
+    assert_eq!(reread, manifest, "env 里的未知键必须原样回写");
+    assert_eq!(reread.files[0].env_extra["customEnvKey"], json!({"k": 1}));
+}
+
+#[test]
+fn curseforge_file_unknown_keys_survive_read_write_reread() {
+    // r1 p3-3 的另一处：CF `files[].fileName` / `url` 是 HMCL 补全后回写的扩展点。
+    let root = super::temp_root("cf-file-extra");
+    let dir = root.join("src");
+    super::write_file(
+        &dir.join("manifest.json"),
+        br#"{"manifestType":"minecraftModpack","manifestVersion":1,"name":"files extra keys",
+             "version":"1.0","minecraft":{"version":"1.20.1","modLoaders":[{"id":"forge-47.2.0","primary":true}]},
+             "files":[{"projectID":238222,"fileID":5102025,"required":true,
+                       "fileName":"jei-1.20.1-15.2.0.27.jar",
+                       "url":"https://edge.forgecdn.net/files/5102/25/jei.jar"}]}"#,
+    );
+    let zip = root.join("pack.zip");
+    super::zip_dir(&dir, &zip);
+
+    let pack = PackArchive::open_default(&zip).expect("打开包");
+    let manifest = CURSEFORGE.read(&pack).expect("读 CF 清单");
+    assert_eq!(
+        manifest.files[0].extra["fileName"],
+        json!("jei-1.20.1-15.2.0.27.jar")
+    );
+    assert_eq!(
+        manifest.files[0].extra["url"],
+        json!("https://edge.forgecdn.net/files/5102/25/jei.jar")
+    );
+
+    let target = root.join("out.zip");
+    CURSEFORGE
+        .write(&manifest, PackPayload::metadata_only(), &target)
+        .expect("导出 CF");
+    let reread = CURSEFORGE
+        .read(&PackArchive::open_default(&target).expect("打开导出包"))
+        .expect("再读");
+    assert_eq!(reread, manifest, "files[] 里的未知键必须原样回写");
+}
+
+#[test]
+fn curseforge_loader_unknown_keys_survive_read_write_reread() {
+    // r1 p3-3 的第三处：`modLoaders[]` 里的未知键（`PackLoader::extra`）。
+    let root = super::temp_root("cf-loader-extra");
+    let dir = root.join("src");
+    super::write_file(
+        &dir.join("manifest.json"),
+        br#"{"manifestType":"minecraftModpack","manifestVersion":1,"name":"loader extra keys",
+             "version":"1.0",
+             "minecraft":{"version":"1.20.1",
+                          "modLoaders":[{"id":"forge-47.2.0","primary":true,"cachedName":"Forge 47.2.0"}]},
+             "files":[]}"#,
+    );
+    let zip = root.join("pack.zip");
+    super::zip_dir(&dir, &zip);
+
+    let pack = PackArchive::open_default(&zip).expect("打开包");
+    let manifest = CURSEFORGE.read(&pack).expect("读 CF 清单");
+    assert_eq!(
+        manifest.loaders[0].extra["cachedName"],
+        json!("Forge 47.2.0")
+    );
+
+    let target = root.join("out.zip");
+    CURSEFORGE
+        .write(&manifest, PackPayload::metadata_only(), &target)
+        .expect("导出 CF");
+    let reread = CURSEFORGE
+        .read(&PackArchive::open_default(&target).expect("打开导出包"))
+        .expect("再读");
+    assert_eq!(reread, manifest, "modLoaders[] 里的未知键必须原样回写");
+    assert_eq!(reread.loaders[0].extra["cachedName"], json!("Forge 47.2.0"));
+}
diff --git a/crates/core/src/addon/tests/import_curseforge.rs b/crates/core/src/addon/tests/import_curseforge.rs
new file mode 100644
index 0000000..03d6d8c
--- /dev/null
+++ b/crates/core/src/addon/tests/import_curseforge.rs
@@ -0,0 +1,134 @@
+//! CurseForge `manifest.json` 端到端导入（离线，stub fetcher 充当 CF API + CDN）。
+//!
+//! 夹具是 M110 的手造包（`fixtures::curseforge`）：`overrides/` 里有一个**刻意的截断 TOML**
+//! （`config/broken.toml`）与一个假 jar。导入器不许因为坏内容崩，也不许悄悄丢掉它们。
+
+use crate::addon::import::{import_pack, ImportRequest, ImportStatus};
+use crate::addon::loader::LoaderKind;
+use crate::download::blocking::block_on;
+
+use super::support::{curse_meta, StubFetcher, CURSE_URL};
+use super::{fixtures, list_tree, read_text, temp_root};
+
+/// CF 夹具里那两个条目补全出来的内容。
+const CURSE_BYTES: &[u8] = b"stub curse file bytes";
+
+#[test]
+fn imports_curseforge_pack_end_to_end() {
+    let fixture = fixtures::curseforge("cf-e2e");
+    let target = temp_root("cf-e2e-out").join("instance");
+    let fetcher = StubFetcher::new()
+        .with_curse(238222, 5102025, curse_meta("jei.jar", CURSE_BYTES))
+        .with_curse(306612, 4587454, curse_meta("fabric-api.jar", CURSE_BYTES))
+        .with_file(CURSE_URL, CURSE_BYTES);
+
+    let request = ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher);
+    let report = block_on(import_pack(&request));
+
+    assert_eq!(
+        report.status,
+        ImportStatus::Success,
+        "状态 {:?}，缺文件 {:?}，冲突 {:?}，错误 {:?}",
+        report.status,
+        report.missing,
+        report.conflicts,
+        report.error
+    );
+    assert_eq!(report.format.as_deref(), Some("curseforge"));
+    assert_eq!(report.pack_name.as_deref(), Some(fixtures::CF_NAME));
+    assert_eq!(report.pack_version.as_deref(), Some("1.0.0"));
+    assert_eq!(report.game_version.as_deref(), Some("1.20.1"));
+    assert!(!report.rolled_back);
+
+    // 加载器被翻译成 addon::loader 的三元组（不另写一套安装逻辑）。
+    let loader = report.loader.as_ref().expect("CF 夹具带 forge");
+    assert_eq!(loader.kind, LoaderKind::Forge);
+    assert_eq!(loader.loader_version, "47.2.0");
+    assert_eq!(loader.version_id, "1.20.1-forge-47.2.0");
+    assert_eq!(
+        loader.resolve_args(),
+        (LoaderKind::Forge, "1.20.1", "47.2.0")
+    );
+    assert_eq!(report.version_id.as_deref(), Some("1.20.1-forge-47.2.0"));
+
+    // 覆盖内容（`overrides/` 的内容铺到实例根，不多一层目录）。
+    assert!(read_text(&target.join("config/known.toml")).contains("key"));
+    // 刻意的截断 TOML 必须原样落地：导入器不是校验器，不许因为内容坏就丢文件。
+    assert_eq!(
+        read_text(&target.join("config/broken.toml")),
+        String::from_utf8_lossy(fixtures::CF_BROKEN)
+    );
+    // 两个 CF 条目都被补全 + 下载（文件名与目录都来自 CF 元数据）。
+    assert_eq!(
+        std::fs::read(target.join("mods/jei.jar")).expect("jei.jar"),
+        CURSE_BYTES
+    );
+    assert_eq!(
+        std::fs::read(target.join("mods/fabric-api.jar")).expect("fabric-api.jar"),
+        CURSE_BYTES
+    );
+    assert_eq!(
+        fetcher.calls(),
+        vec![CURSE_URL.to_string(), CURSE_URL.to_string()]
+    );
+
+    // 基线写进去了（下次导入的 base 侧）。
+    let baseline = read_text(&target.join(super::baseline_rel()));
+    assert!(baseline.contains("mods/jei.jar"), "基线：{baseline}");
+    assert!(baseline.contains("config/known.toml"), "基线：{baseline}");
+
+    assert_eq!(
+        list_tree(&target),
+        vec![
+            super::baseline_rel(),
+            "config/broken.toml".to_string(),
+            "config/known.toml".to_string(),
+            "mods/example.jar".to_string(),
+            "mods/fabric-api.jar".to_string(),
+            "mods/jei.jar".to_string(),
+        ]
+    );
+}
+
+#[test]
+fn offline_curseforge_import_is_partial_not_success() {
+    // 没有 fetcher ⇒ CF 的 files[] 一条都补不出来。这**不是**失败，也**不许**记成成功。
+    let fixture = fixtures::curseforge("cf-offline");
+    let target = temp_root("cf-offline-out").join("instance");
+    let request = ImportRequest::new(&fixture.zip, &target);
+    let report = block_on(import_pack(&request));
+
+    assert_eq!(report.status, ImportStatus::Partial);
+    assert_eq!(report.missing.len(), 2, "{:?}", report.missing);
+    assert!(report
+        .missing
+        .iter()
+        .all(|missing| missing.message_key == crate::addon::import::keys::MISSING_OFFLINE));
+    // 覆盖内容照装（离线不影响包内自带的内容）。
+    assert!(target.join("config/known.toml").is_file());
+    assert!(!target.join("mods/jei.jar").exists());
+    // 3 = Partial 的退出码（CLI 契约）。
+    assert_eq!(report.status.exit_code(), 3);
+}
+
+#[test]
+fn curseforge_meta_without_download_url_is_missing_not_guessed() {
+    // CF 作者可以关掉 API 分发（`downloadUrl` 为 null）：我们**不猜** URL，只如实记缺。
+    let fixture = fixtures::curseforge("cf-nourl");
+    let target = temp_root("cf-nourl-out").join("instance");
+    let mut meta = curse_meta("jei.jar", CURSE_BYTES);
+    meta.url = None;
+    let fetcher = StubFetcher::new()
+        .with_curse(238222, 5102025, meta)
+        .with_file(CURSE_URL, CURSE_BYTES);
+    let request = ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher);
+    let report = block_on(import_pack(&request));
+
+    assert_eq!(report.status, ImportStatus::Partial);
+    assert!(report
+        .missing
+        .iter()
+        .any(|missing| missing.message_key == crate::addon::import::keys::MISSING_NO_SOURCE));
+    // 没有发出任何下载请求。
+    assert!(fetcher.calls().is_empty(), "{:?}", fetcher.calls());
+}
diff --git a/crates/core/src/addon/tests/import_failures.rs b/crates/core/src/addon/tests/import_failures.rs
new file mode 100644
index 0000000..57e8511
--- /dev/null
+++ b/crates/core/src/addon/tests/import_failures.rs
@@ -0,0 +1,254 @@
+//! **必须先失败**的样本：四条恶意/坏包 + 两条"证明双检真的在导入链上跑"的用例。
+//!
+//! # 复审要的那张表
+//!
+//! | 样本 | 期望结果 | 断言在哪 |
+//! |------|----------|----------|
+//! | 路径穿越条目（`../evil.jar`） | `Failed` + `pack_traversal` + 目标目录零残留 | [`traversal_entry_rolls_back_with_zero_residue`] |
+//! | 符号链接条目 | `Failed` + `pack_symlink` + 零残留 | [`symlink_entry_rolls_back_with_zero_residue`] |
+//! | 损坏清单（非法 JSON） | `Failed` + `pack_metadata` + 零残留 | [`corrupt_manifest_rolls_back_with_zero_residue`] |
+//! | 声明与实际不符（sha1 不符） | `Failed` + `import_integrity` + 零残留 | [`declared_hash_mismatch_rolls_back_everything`] |
+//!
+//! # 零残留的验证方式
+//!
+//! [`assert_clean`]：①目标目录不存在；②目标目录的父目录里没有 `.ull-import-*` 临时目录
+//! （临时目录是"事务没收拾干净"的唯一痕迹）；③合并态用例另外断言目标目录内容与导入前
+//! **逐项相同**。三条合起来就是"失败后既没有半个实例，也没有残留垃圾"。
+//!
+//! # 两条双检证明
+//!
+//! 路径穿越是**两条独立检查**（M110 `pack::path::normalize_file` + `zip` 的
+//! `enclosed_name()`）。要证明两条都真的接在导入链上，得各给一条**只有其中一条能拦**的样本：
+//!
+//! - 绝对路径 `/etc/passwd`：`enclosed_name()` 在深度 0 处**放行**（它允许根目录），只有第一检
+//!   能拦 ⇒ 它失败就说明第一检活着；
+//! - Windows 设备名 `NUL`：第一检七条规则全放行，只有第二检（按 Win32 命名空间解析）能拦
+//!   ⇒ 它失败就说明第二检活着（该用例仅在 Windows 宿主上有效，与 M110 的用例同构）。
+
+use std::path::Path;
+
+use crate::addon::import::{import_pack, ImportRequest, ImportStatus};
+use crate::download::blocking::block_on;
+
+use super::support::{StubFetcher, JEI_BYTES, JEI_PLACEHOLDER_URL, OPTIONAL_PLACEHOLDER_URL};
+use super::{
+    fixtures, list_tree, read_text, temp_root, write_file, write_zip, write_zip_with_symlink,
+};
+
+/// 一份形状合法的最小 CF 清单（恶意包要能被"探测成功"，失败必须发生在它该发生的阶段）。
+const CF_MANIFEST: &[u8] = br#"{"manifestType": "minecraftModpack", "manifestVersion": 1,
+  "name": "evil", "version": "1.0.0", "overrides": "overrides",
+  "minecraft": {"version": "1.20.1", "modLoaders": []}, "files": []}"#;
+
+/// 断言"目标目录零残留"：目录不存在、父目录里没有临时目录。
+fn assert_clean(target: &Path) {
+    assert!(
+        !target.exists(),
+        "目标目录必须不存在（零残留），实际：{:?}",
+        list_tree(target)
+    );
+    let parent = target.parent().expect("target 有父目录");
+    if let Ok(entries) = std::fs::read_dir(parent) {
+        for entry in entries.flatten() {
+            let name = entry.file_name().to_string_lossy().to_string();
+            assert!(!name.contains(".ull-import-"), "临时目录没清掉：{name}");
+        }
+    }
+}
+
+fn failing(tag: &str, entries: &[(&str, &[u8])]) -> (std::path::PathBuf, std::path::PathBuf) {
+    let root = temp_root(tag);
+    let pack = root.join("evil.zip");
+    write_zip(&pack, entries);
+    let target = root.join("instance");
+    (pack, target)
+}
+
+#[test]
+fn traversal_entry_rolls_back_with_zero_residue() {
+    let (pack, target) = failing(
+        "fail-traversal",
+        &[("manifest.json", CF_MANIFEST), ("../evil.jar", b"payload")],
+    );
+    let report = block_on(import_pack(&ImportRequest::new(&pack, &target)));
+
+    assert_eq!(report.status, ImportStatus::Failed);
+    assert_eq!(
+        report.error.as_ref().expect("具名错误").code(),
+        "pack_traversal"
+    );
+    assert!(report.rolled_back);
+    assert_clean(&target);
+    assert_eq!(report.status.exit_code(), 1);
+}
+
+#[test]
+fn absolute_entry_proves_the_first_check_is_live() {
+    // `enclosed_name()` 会放行深度 0 的绝对路径，只有 `normalize_file` 能拦。
+    let (pack, target) = failing(
+        "fail-absolute",
+        &[
+            ("manifest.json", CF_MANIFEST),
+            ("/etc/passwd", b"root::0:0"),
+        ],
+    );
+    let report = block_on(import_pack(&ImportRequest::new(&pack, &target)));
+
+    assert_eq!(report.status, ImportStatus::Failed);
+    assert_eq!(
+        report.error.as_ref().expect("具名错误").code(),
+        "pack_traversal"
+    );
+    assert_clean(&target);
+}
+
+#[cfg(windows)]
+#[test]
+fn windows_device_name_proves_the_second_check_is_live() {
+    // `NUL` 过得了第一检的七条规则，只有 `zip` 的 `enclosed_name()`（Win32 命名空间）会拦。
+    let (pack, target) = failing(
+        "fail-device",
+        &[("manifest.json", CF_MANIFEST), ("mods/NUL", b"x")],
+    );
+    let report = block_on(import_pack(&ImportRequest::new(&pack, &target)));
+
+    assert_eq!(report.status, ImportStatus::Failed);
+    assert_eq!(
+        report.error.as_ref().expect("具名错误").code(),
+        "pack_traversal"
+    );
+    assert_clean(&target);
+}
+
+#[test]
+fn symlink_entry_rolls_back_with_zero_residue() {
+    let root = temp_root("fail-symlink");
+    let pack = root.join("evil.zip");
+    let entries: [(&str, &[u8]); 1] = [("manifest.json", CF_MANIFEST)];
+    write_zip_with_symlink(&pack, &entries, "mods/evil.jar", "../../../etc/passwd");
+    let target = root.join("instance");
+
+    let report = block_on(import_pack(&ImportRequest::new(&pack, &target)));
+    assert_eq!(report.status, ImportStatus::Failed);
+    assert_eq!(
+        report.error.as_ref().expect("具名错误").code(),
+        "pack_symlink"
+    );
+    assert_clean(&target);
+}
+
+#[test]
+fn corrupt_manifest_rolls_back_with_zero_residue() {
+    let (pack, target) = failing(
+        "fail-json",
+        &[
+            ("manifest.json", b"{\"manifestType\": \"minecraftModpack\","),
+            ("overrides/config/a.toml", b"k = 1\n"),
+        ],
+    );
+    let report = block_on(import_pack(&ImportRequest::new(&pack, &target)));
+
+    assert_eq!(report.status, ImportStatus::Failed);
+    let code = report.error.as_ref().expect("具名错误").code();
+    assert!(
+        code == "pack_metadata" || code == "pack_unsupported",
+        "坏 JSON 要报成因，实际 {code}"
+    );
+    assert_clean(&target);
+}
+
+#[test]
+fn declared_hash_mismatch_rolls_back_everything() {
+    // 原始 M110 夹具：`hashes.sha1` 是形状正确的**占位值**，必然不等于 stub 给的字节。
+    // 这是"声明与实际不符"——它**不是**"暂时搞不到"，必须整包回滚。
+    let fixture = fixtures::modrinth("fail-integrity");
+    let root = temp_root("fail-integrity-out");
+    let target = root.join("instance");
+    let fetcher = StubFetcher::new()
+        .with_file(JEI_PLACEHOLDER_URL, JEI_BYTES)
+        .with_file(OPTIONAL_PLACEHOLDER_URL, b"stub optional");
+    let report = block_on(import_pack(
+        &ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher),
+    ));
+
+    assert_eq!(
+        report.status,
+        ImportStatus::Failed,
+        "缺文件 {:?}",
+        report.missing
+    );
+    assert_eq!(
+        report.error.as_ref().expect("具名错误").code(),
+        "import_integrity"
+    );
+    assert!(report.rolled_back);
+    assert_clean(&target);
+}
+
+#[test]
+fn fatal_error_in_merge_mode_leaves_the_target_untouched() {
+    // 目标目录已有内容（升级/重导）：致命错误时**只**清临时目录，不动目标目录。
+    let (pack, target) = failing(
+        "fail-merge",
+        &[("manifest.json", CF_MANIFEST), ("../evil.jar", b"payload")],
+    );
+    write_file(&target.join("keep.txt"), b"untouched");
+    write_file(&target.join("mods/mine.jar"), b"mine");
+    let before = list_tree(&target);
+
+    let report = block_on(import_pack(&ImportRequest::new(&pack, &target)));
+
+    assert_eq!(report.status, ImportStatus::Failed);
+    assert!(report.rolled_back);
+    assert_eq!(list_tree(&target), before, "目标目录必须逐项不变");
+    assert_eq!(
+        std::fs::read(target.join("keep.txt")).expect("keep.txt"),
+        b"untouched"
+    );
+}
+
+#[test]
+fn commit_failure_rolls_back_partially_applied_files() {
+    // 让合并态的**提交阶段**在中途失败：目标文件要被替换时必须先备份成
+    // `<dest>.ullbak-<pid>`，而那个位置已被一个**非空目录**占住 ⇒ `rename(dest → backup)`
+    // 必然失败（文件改不成非空目录，Windows / Unix 一致）。
+    // 这覆盖 journal 回滚 + `Drop` 兜底：前半截已经搬进去的文件（基线排最前）必须被撤回。
+    let root = temp_root("fail-commit");
+    let source = fixtures::multimc("fail-commit-src");
+    let target = root.join("instance");
+    let first = block_on(import_pack(&ImportRequest::new(&source, &target)));
+    assert_eq!(first.status, ImportStatus::Success, "{:?}", first.error);
+
+    // 新版本包内容变了（用户没动过 ⇒ 判据是 Install，会被暂存并尝试替换）。
+    write_file(
+        &source.join(".minecraft/config/known.toml"),
+        b"key = \"v2\"\n",
+    );
+    // 备份位置被非空目录占住。
+    let blocker = target.join(format!("config/known.toml.ullbak-{}", std::process::id()));
+    write_file(&blocker.join("blocker.txt"), b"block");
+    let before = list_tree(&target);
+
+    let second = block_on(import_pack(&ImportRequest::new(&source, &target)));
+
+    assert_eq!(
+        second.status,
+        ImportStatus::Failed,
+        "提交阶段失败必须整包回滚"
+    );
+    assert_eq!(
+        second.error.as_ref().expect("具名错误").code(),
+        "pack_io",
+        "{}",
+        second.error.as_ref().expect("具名错误").message()
+    );
+    assert!(second.rolled_back);
+    assert_eq!(list_tree(&target), before, "目标目录必须逐项回到导入前");
+    // 提交阶段排在最前面的基线被成功搬入又被撤回：内容仍是第一次导入的那份。
+    assert!(target.join(super::baseline_rel()).is_file());
+    assert_eq!(
+        read_text(&target.join("config/known.toml")),
+        "key = \"value\"\n",
+        "旧内容必须还在（新内容没落地）"
+    );
+}
diff --git a/crates/core/src/addon/tests/import_merge.rs b/crates/core/src/addon/tests/import_merge.rs
new file mode 100644
index 0000000..64cd84a
--- /dev/null
+++ b/crates/core/src/addon/tests/import_merge.rs
@@ -0,0 +1,293 @@
+//! overrides 三方合并的**行为**测试：用户改过 / 用户删过 / 没动过 / 没有基线 / 侧优先级。
+//!
+//! 判据本身（纯函数）在 `import::merge` 的单元测试里；这里验证的是"判据真的接在管线上了"：
+//! 真写盘、真重导、真读回内容。
+
+use crate::addon::import::{
+    import_pack, ConflictChoice, ConflictPolicy, ConflictReason, FileAction, ImportRequest,
+    ImportStatus,
+};
+use crate::download::blocking::block_on;
+
+use super::support::mrpack_stub;
+use super::{list_tree, read_text, temp_root, write_file, zip_dir};
+
+use crate::addon::import::{PackBaseline, BASELINE_FILE};
+
+#[test]
+fn user_modified_file_is_kept_and_reported() {
+    let (fixture, fetcher) = mrpack_stub("merge-modified");
+    let target = temp_root("merge-modified-out").join("instance");
+    let first = block_on(import_pack(
+        &ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher),
+    ));
+    assert_eq!(first.status, ImportStatus::Success, "{:?}", first.error);
+
+    // 用户动手改了一个包内文件。
+    write_file(&target.join("config/known.toml"), b"shared = false\n");
+    let second = block_on(import_pack(
+        &ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher),
+    ));
+
+    assert_eq!(
+        second.status,
+        ImportStatus::Partial,
+        "保留用户文件 ⇒ 部分成功"
+    );
+    assert_eq!(second.conflicts.len(), 1, "{:?}", second.conflicts);
+    let conflict = &second.conflicts[0];
+    assert_eq!(conflict.path, "config/known.toml");
+    assert_eq!(conflict.reason, ConflictReason::UserModified);
+    assert_eq!(conflict.choice, ConflictChoice::KeepUser);
+    assert_eq!(
+        conflict.message_key,
+        crate::addon::import::keys::CONFLICT_USER_MODIFIED
+    );
+    assert!(conflict.base_sha1.is_some(), "基线里应有上次的哈希");
+    assert!(conflict.disk_sha1.is_some());
+    // 磁盘内容没被盖掉。
+    assert_eq!(
+        read_text(&target.join("config/known.toml")),
+        "shared = false\n"
+    );
+    // 报告里这条的结局是"保留用户"。
+    assert!(second
+        .files
+        .iter()
+        .any(|file| file.path == "config/known.toml" && file.action == FileAction::KeptUser));
+    assert_eq!(second.status.exit_code(), 3);
+}
+
+#[test]
+fn user_deleted_file_is_not_restored() {
+    let (fixture, fetcher) = mrpack_stub("merge-deleted");
+    let target = temp_root("merge-deleted-out").join("instance");
+    let first = block_on(import_pack(
+        &ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher),
+    ));
+    assert_eq!(first.status, ImportStatus::Success, "{:?}", first.error);
+
+    // 用户删了一个包内文件。
+    std::fs::remove_file(target.join("mods/half.jar")).expect("删夹具文件");
+    let second = block_on(import_pack(
+        &ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher),
+    ));
+
+    assert_eq!(second.status, ImportStatus::Partial);
+    let conflict = second
+        .conflicts
+        .iter()
+        .find(|conflict| conflict.path == "mods/half.jar")
+        .expect("删除也要进冲突清单");
+    assert_eq!(conflict.reason, ConflictReason::UserDeleted);
+    assert_eq!(conflict.choice, ConflictChoice::KeepUser);
+    assert_eq!(conflict.disk_sha1, None);
+    assert!(
+        !target.join("mods/half.jar").exists(),
+        "用户删掉的文件不许偷偷装回来"
+    );
+}
+
+#[test]
+fn untouched_file_is_upgraded_by_a_newer_pack() {
+    let (fixture, fetcher) = mrpack_stub("merge-upgrade");
+    let target = temp_root("merge-upgrade-out").join("instance");
+    let first = block_on(import_pack(
+        &ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher),
+    ));
+    assert_eq!(first.status, ImportStatus::Success, "{:?}", first.error);
+
+    // 新版本包：同一个路径，内容变了；用户没动过。
+    write_file(
+        &fixture.dir.join("overrides/config/known.toml"),
+        b"shared = 2\n",
+    );
+    zip_dir(&fixture.dir, &fixture.zip);
+    let second = block_on(import_pack(
+        &ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher),
+    ));
+
+    assert_eq!(
+        second.status,
+        ImportStatus::Success,
+        "未改过的文件升级不算冲突"
+    );
+    assert!(second.conflicts.is_empty(), "{:?}", second.conflicts);
+    assert_eq!(read_text(&target.join("config/known.toml")), "shared = 2\n");
+    assert!(second
+        .files
+        .iter()
+        .any(|file| file.path == "config/known.toml" && file.action == FileAction::Replaced));
+}
+
+#[test]
+fn pre_existing_file_without_baseline_is_kept() {
+    let (fixture, fetcher) = mrpack_stub("merge-existing");
+    let target = temp_root("merge-existing-out").join("instance");
+    // 首次导入前磁盘上就有同名文件：没有基线可判 ⇒ 最安全的一侧（不覆盖）。
+    write_file(&target.join("config/known.toml"), b"mine\n");
+    let report = block_on(import_pack(
+        &ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher),
+    ));
+
+    assert_eq!(report.status, ImportStatus::Partial);
+    let conflict = report
+        .conflicts
+        .iter()
+        .find(|conflict| conflict.path == "config/known.toml")
+        .expect("要有冲突清单");
+    assert_eq!(conflict.reason, ConflictReason::PreExisting);
+    assert!(conflict.base_sha1.is_none());
+    assert_eq!(read_text(&target.join("config/known.toml")), "mine\n");
+}
+
+#[test]
+fn overwrite_policy_replaces_user_file_and_reports_the_choice() {
+    let (fixture, fetcher) = mrpack_stub("merge-overwrite");
+    let target = temp_root("merge-overwrite-out").join("instance");
+    let first = block_on(import_pack(
+        &ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher),
+    ));
+    assert_eq!(first.status, ImportStatus::Success, "{:?}", first.error);
+    write_file(&target.join("config/known.toml"), b"shared = false\n");
+
+    let report = block_on(import_pack(
+        &ImportRequest::new(&fixture.zip, &target)
+            .with_fetcher(&fetcher)
+            .with_conflict_policy(ConflictPolicy::Overwrite),
+    ));
+
+    assert_eq!(report.status, ImportStatus::Success, "覆盖后结果是干净的");
+    let conflict = report
+        .conflicts
+        .iter()
+        .find(|conflict| conflict.path == "config/known.toml")
+        .expect("冲突仍要记账");
+    assert_eq!(conflict.reason, ConflictReason::UserModified);
+    assert_eq!(conflict.choice, ConflictChoice::Overwrite);
+    assert_eq!(
+        read_text(&target.join("config/known.toml")),
+        "shared = true\n"
+    );
+}
+
+#[test]
+fn client_overrides_wins_over_overrides() {
+    // Modrinth 官方客户端语义：`client-overrides/` 后写 = 胜（HMCL 恰好相反）。
+    let root = temp_root("merge-priority");
+    let dir = root.join("src");
+    write_file(
+        &dir.join("modrinth.index.json"),
+        br#"{"game": "minecraft", "formatVersion": 1, "versionId": "1.0.0",
+             "name": "dup", "files": [], "dependencies": {"minecraft": "1.20.1"}}"#,
+    );
+    write_file(&dir.join("overrides/config/dup.toml"), b"from-overrides\n");
+    write_file(
+        &dir.join("client-overrides/config/dup.toml"),
+        b"from-client\n",
+    );
+    write_file(
+        &dir.join("server-overrides/config/dup.toml"),
+        b"from-server\n",
+    );
+    let pack = root.join("pack.mrpack");
+    zip_dir(&dir, &pack);
+
+    let target = root.join("instance");
+    let report = block_on(import_pack(&ImportRequest::new(&pack, &target)));
+
+    assert_eq!(report.status, ImportStatus::Success, "{:?}", report.error);
+    assert_eq!(read_text(&target.join("config/dup.toml")), "from-client\n");
+    assert!(
+        report.conflicts.is_empty(),
+        "侧优先级不是冲突：{:?}",
+        report.conflicts
+    );
+}
+
+#[test]
+fn baseline_read_and_write_paths_are_the_same_file() {
+    // 复审 r5 P1-1 的回归钉：读侧（`PackBaseline::path`）与写侧（`relative_path` 拼 root）
+    // **必须解析到同一个路径**。只测"读得到"在大小写不敏感的系统上会假绿。
+    let root = temp_root("baseline-path").join("instance");
+    let read = PackBaseline::path(&root);
+    let write = root.join(PackBaseline::relative_path());
+    assert_eq!(read, write, "读写必须是同一个文件：{read:?} vs {write:?}");
+    // 相对路径的唯一来源是 `GameLayout::ull_root()`（游戏根内的 `.ull/`），不是启动器数据根。
+    assert_eq!(
+        PackBaseline::relative_path(),
+        std::path::PathBuf::from(".ull").join(BASELINE_FILE)
+    );
+    assert_eq!(
+        read.parent(),
+        Some(
+            crate::game::layout::GameLayout::new(&root)
+                .ull_root()
+                .as_path()
+        )
+    );
+    // 写侧（pipeline 提交时用的相对路径）必须同源；`.ULL` 是**启动器数据根**的名字，
+    // 出现在实例内路径里就是 P1-1 那个 bug（大小写敏感的系统上会变成两个文件）。
+    let write_side = crate::addon::import::baseline_relative();
+    assert_eq!(
+        write_side,
+        PackBaseline::relative_path()
+            .to_string_lossy()
+            .replace('\\', "/"),
+        "写侧必须从同一个来源派生"
+    );
+    assert!(
+        !write_side.contains(".ULL"),
+        "实例内路径不许用启动器数据根的 `.ULL`：{write_side}"
+    );
+}
+
+#[test]
+fn baseline_of_another_pack_is_not_used_as_base() {
+    // 同一目录先后导入两个整合包：别人的基线当 base 会把"用户改过"误判成"整合包升级"而静默覆盖。
+    let root = temp_root("merge-identity");
+    let source = super::fixtures::multimc("merge-identity-a");
+    let target = root.join("instance");
+    let first = block_on(import_pack(&ImportRequest::new(&source, &target)));
+    assert_eq!(first.status, ImportStatus::Success, "{:?}", first.error);
+    // 用户改了一个包内文件。
+    write_file(&target.join("mods/example.jar"), b"mine");
+
+    // 另一个包（名字不同 + 同名文件内容不同）导进同一目录。
+    let other = root.join("other");
+    write_file(
+        &other.join("mmc-pack.json"),
+        br#"{"formatVersion": 1, "components": [
+            {"uid": "net.minecraft", "version": "1.20.1"},
+            {"uid": "net.fabricmc.fabric-loader", "version": "0.15.11"}]}"#,
+    );
+    write_file(
+        &other.join("instance.cfg"),
+        "InstanceType=OneSix\nname=另一个包\n".as_bytes(),
+    );
+    write_file(&other.join(".minecraft/mods/example.jar"), b"pack B jar");
+    let report = block_on(import_pack(&ImportRequest::new(&other, &target)));
+
+    assert!(
+        report
+            .warnings
+            .iter()
+            .any(|note| note.message_key == crate::addon::import::keys::NOTE_BASELINE_PACK_MISMATCH),
+        "跨包基线要具名告警：{:?}",
+        report.warnings
+    );
+    let conflict = report
+        .conflicts
+        .iter()
+        .find(|conflict| conflict.path == "mods/example.jar")
+        .expect("要有冲突");
+    assert_eq!(
+        conflict.reason,
+        ConflictReason::PreExisting,
+        "别人的基线不能拿来判 user_modified"
+    );
+    assert!(conflict.base_sha1.is_none(), "身份不符时基线应被忽略");
+    assert_eq!(read_text(&target.join("mods/example.jar")), "mine");
+    assert_eq!(report.status, ImportStatus::Partial);
+    assert!(list_tree(&target).contains(&"mods/example.jar".to_string()));
+}
diff --git a/crates/core/src/addon/tests/import_modrinth.rs b/crates/core/src/addon/tests/import_modrinth.rs
new file mode 100644
index 0000000..0dbb934
--- /dev/null
+++ b/crates/core/src/addon/tests/import_modrinth.rs
@@ -0,0 +1,178 @@
+//! Modrinth `.mrpack` 端到端导入：三目录优先级、`.disabled` 后缀、依赖翻译。
+//!
+//! 成功路径吃 [`super::support::mrpack_stub`]（同一份 M110 夹具，只把 `sha1`/`downloads`
+//! 换成真实值）；"声明与实际不符"那条用例用**原始**夹具，见 `import_failures.rs`。
+
+use crate::addon::import::{import_pack, keys, ImportRequest, ImportStatus};
+use crate::addon::loader::LoaderKind;
+use crate::download::blocking::block_on;
+
+use super::support::{mrpack_stub, JEI_BYTES, OPTIONAL_BYTES};
+use super::{fixtures, list_tree, read_text, temp_root};
+
+#[test]
+fn imports_mrpack_end_to_end() {
+    let (fixture, fetcher) = mrpack_stub("mr-e2e");
+    let target = temp_root("mr-e2e-out").join("instance");
+    let request = ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher);
+    let report = block_on(import_pack(&request));
+
+    assert_eq!(
+        report.status,
+        ImportStatus::Success,
+        "缺文件 {:?} 冲突 {:?} 错误 {:?}",
+        report.missing,
+        report.conflicts,
+        report.error
+    );
+    assert_eq!(report.format.as_deref(), Some("modrinth"));
+    assert_eq!(report.pack_name.as_deref(), Some(fixtures::MR_NAME));
+    assert_eq!(report.pack_version.as_deref(), Some("2.0.0"));
+    assert_eq!(report.game_version.as_deref(), Some("1.20.1"));
+
+    let loader = report.loader.as_ref().expect("mrpack 带 fabric-loader");
+    assert_eq!(loader.kind, LoaderKind::Fabric);
+    assert_eq!(loader.loader_version, "0.15.11");
+    assert_eq!(loader.version_id, "1.20.1-fabric-0.15.11");
+
+    // 覆盖内容：`overrides/` + `client-overrides/` 落地，`server-overrides/` **不落地**。
+    assert_eq!(
+        std::fs::read(target.join("mods/half.jar")).expect("half.jar"),
+        fixtures::MR_HALF_JAR
+    );
+    assert!(target.join("config/known.toml").is_file());
+    assert!(target.join("config/client-only.toml").is_file());
+    assert!(
+        !target.join("config/server.properties").exists(),
+        "server-overrides/ 客户端不许解压（Modrinth 官方语义）"
+    );
+
+    // 远端条目：路径与地址都在清单里，内容来自 stub。
+    assert_eq!(
+        std::fs::read(target.join("mods/jei.jar")).expect("jei.jar"),
+        JEI_BYTES
+    );
+    assert_eq!(
+        std::fs::read(target.join("mods/optional.jar")).expect("optional.jar"),
+        OPTIONAL_BYTES
+    );
+
+    // 三条注记：服务端覆盖被跳过 / 不认识的依赖键 / 可选条目不等于禁用。
+    let note_keys: Vec<&str> = report
+        .warnings
+        .iter()
+        .map(|note| note.message_key)
+        .collect();
+    assert!(
+        note_keys.contains(&keys::NOTE_SERVER_OVERRIDES_SKIPPED),
+        "{note_keys:?}"
+    );
+    assert!(
+        note_keys.contains(&keys::NOTE_UNKNOWN_DEPENDENCY),
+        "parchment 这类键要如实告警：{note_keys:?}"
+    );
+    assert!(
+        note_keys.contains(&keys::NOTE_OPTIONAL_FILE),
+        "env.client=optional 要提示但照装：{note_keys:?}"
+    );
+
+    assert_eq!(
+        list_tree(&target),
+        vec![
+            super::baseline_rel(),
+            "config/client-only.toml".to_string(),
+            "config/known.toml".to_string(),
+            "mods/half.jar".to_string(),
+            "mods/jei.jar".to_string(),
+            "mods/optional.jar".to_string(),
+        ]
+    );
+}
+
+#[test]
+fn engine_artifacts_never_reach_the_instance() {
+    // 引擎在下载失败时故意留下 `<name>.ullpart-<session>-<seq>` 与 `<name>.ullmeta.json`
+    // 供下次续传；它们躺在暂存目录里，提交前必须剔掉，否则会变成实例里的"内容"。
+    let (fixture, fetcher) = mrpack_stub("mr-artifacts");
+    let fetcher = fetcher.with_engine_artifacts();
+    let target = temp_root("mr-artifacts-out").join("instance");
+    let report = block_on(import_pack(
+        &ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher),
+    ));
+
+    assert_eq!(report.status, ImportStatus::Success, "{:?}", report.error);
+    let tree = list_tree(&target);
+    assert!(
+        tree.iter()
+            .all(|path| !path.contains(".ullpart") && !path.contains(".ullmeta")),
+        "中间产物不许进实例：{tree:?}"
+    );
+    assert!(
+        report
+            .warnings
+            .iter()
+            .any(|note| note.message_key == keys::NOTE_ENGINE_ARTIFACTS_DROPPED),
+        "剔除了就该留一条注记：{:?}",
+        report.warnings
+    );
+}
+
+#[test]
+fn disabled_suffix_is_preserved_verbatim() {
+    // 四种 `.disabled` / `.old` 变体都按原后缀落地，不改名、不清理（tower 定案）。
+    let (fixture, fetcher) = mrpack_stub("mr-disabled");
+    super::write_file(
+        &fixture.dir.join("overrides/mods/variant.jar.disabled"),
+        b"disabled bytes",
+    );
+    super::write_file(
+        &fixture.dir.join("overrides/mods/variant.jar.disabled.old"),
+        b"disabled old bytes",
+    );
+    super::write_file(
+        &fixture.dir.join("overrides/mods/variant.jar.old"),
+        b"old bytes",
+    );
+    super::zip_dir(&fixture.dir, &fixture.zip);
+
+    let target = temp_root("mr-disabled-out").join("instance");
+    let request = ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher);
+    let report = block_on(import_pack(&request));
+
+    assert_eq!(report.status, ImportStatus::Success, "{:?}", report.error);
+    for name in [
+        "mods/variant.jar.disabled",
+        "mods/variant.jar.disabled.old",
+        "mods/variant.jar.old",
+    ] {
+        assert!(target.join(name).is_file(), "{name} 应当按原后缀落地");
+    }
+    // 禁用位从后缀读出来，`.old` 不被当成禁用。
+    let disabled: Vec<(&str, bool)> = report
+        .files
+        .iter()
+        .filter(|file| file.path.starts_with("mods/variant"))
+        .map(|file| (file.path.as_str(), file.disabled))
+        .collect();
+    assert_eq!(
+        disabled,
+        vec![
+            ("mods/variant.jar.disabled", true),
+            ("mods/variant.jar.disabled.old", true),
+            ("mods/variant.jar.old", false),
+        ]
+    );
+    let note_keys: Vec<&str> = report
+        .files
+        .iter()
+        .filter(|file| file.path.starts_with("mods/variant"))
+        .filter_map(|file| file.note.as_ref().map(|note| note.message_key))
+        .collect();
+    assert!(
+        note_keys.contains(&keys::NOTE_DISABLED_SUFFIX),
+        "{note_keys:?}"
+    );
+    assert!(note_keys.contains(&keys::NOTE_OLD_SUFFIX), "{note_keys:?}");
+    // 报告里的内容仍是原文（没有"读出来再写一遍"导致的空白变化）。
+    assert_eq!(read_text(&target.join("mods/variant.jar.old")), "old bytes");
+}
diff --git a/crates/core/src/addon/tests/import_multimc.rs b/crates/core/src/addon/tests/import_multimc.rs
new file mode 100644
index 0000000..170b82e
--- /dev/null
+++ b/crates/core/src/addon/tests/import_multimc.rs
@@ -0,0 +1,210 @@
+//! MultiMC / Prism 实例目录导入：`.minecraft/` 直拷、component 逐项交代、`instance.cfg` 取内存。
+
+use serde_json::Value;
+
+use crate::addon::import::{import_pack, keys, ImportRequest, ImportStatus};
+use crate::addon::loader::LoaderKind;
+use crate::download::blocking::block_on;
+
+use super::{fixtures, list_tree, read_text, temp_root, write_file};
+
+#[test]
+fn imports_multimc_instance_end_to_end() {
+    let source = fixtures::multimc("mmc-e2e");
+    let target = temp_root("mmc-e2e-out").join("instance");
+    let request = ImportRequest::new(&source, &target);
+    let report = block_on(import_pack(&request));
+
+    assert_eq!(report.status, ImportStatus::Success, "{:?}", report.error);
+    assert_eq!(report.format.as_deref(), Some("multimc"));
+    assert_eq!(report.pack_name.as_deref(), Some(fixtures::MMC_NAME));
+    assert_eq!(report.game_version.as_deref(), Some("1.20.1"));
+    let loader = report.loader.as_ref().expect("fabric-loader 组件");
+    assert_eq!(loader.kind, LoaderKind::Fabric);
+    assert_eq!(loader.loader_version, "0.15.11");
+    assert_eq!(loader.version_id, "1.20.1-fabric-0.15.11");
+    // MultiMC 没有远端条目：内容就是目录。
+    assert!(report.missing.is_empty());
+    assert!(report
+        .files
+        .iter()
+        .all(|file| file.source == crate::addon::import::FileSource::Overrides));
+
+    // `.minecraft/` 直拷到实例根（不多一层 `.minecraft/`），零字节 jar 也照拷。
+    assert_eq!(
+        std::fs::read(target.join("mods/example.jar")).expect("example.jar"),
+        b"PK\x03\x04 hand-made jar stub"
+    );
+    assert_eq!(
+        std::fs::metadata(target.join("mods/broken.jar"))
+            .expect("broken.jar")
+            .len(),
+        0,
+        "零字节 jar 是夹具刻意造的：导入器不许悄悄丢掉它"
+    );
+    assert!(target.join("config/known.toml").is_file());
+    assert_eq!(
+        list_tree(&target),
+        vec![
+            super::baseline_rel(),
+            "config/known.toml".to_string(),
+            "mods/broken.jar".to_string(),
+            "mods/example.jar".to_string(),
+        ]
+    );
+}
+
+#[test]
+fn unsupported_components_are_listed_one_by_one_not_dropped() {
+    let source = fixtures::multimc("mmc-components");
+    let target = temp_root("mmc-components-out").join("instance");
+    let request = ImportRequest::new(&source, &target);
+    let report = block_on(import_pack(&request));
+
+    // 夹具里的 `org.lwjgl3` 不是加载器 ⇒ 必须逐项进"未支持清单"。
+    assert_eq!(
+        report.rejected_components.len(),
+        1,
+        "{:?}",
+        report.rejected_components
+    );
+    let rejected = &report.rejected_components[0];
+    assert_eq!(rejected.uid, "org.lwjgl3");
+    assert_eq!(rejected.version.as_deref(), Some("3.3.2"));
+    assert_eq!(rejected.message_key, keys::REJECTED_COMPONENT);
+
+    // **不静默丢**的断言：`mmc-pack.json` 里每一个 component 都能在报告里找到归宿。
+    let pack: Value =
+        serde_json::from_str(&read_text(&source.join("mmc-pack.json"))).expect("解析 mmc-pack");
+    let components = pack["components"].as_array().expect("components 数组");
+    assert!(!components.is_empty());
+    for component in components {
+        let uid = component["uid"].as_str().expect("uid");
+        let version = component["version"].as_str().expect("version");
+        if uid == "net.minecraft" {
+            assert_eq!(
+                report.game_version.as_deref(),
+                Some(version),
+                "{uid} 要变成游戏版本"
+            );
+            continue;
+        }
+        let as_loader = report
+            .loader
+            .as_ref()
+            .is_some_and(|loader| loader.raw == uid);
+        let as_rejected = report
+            .rejected_components
+            .iter()
+            .any(|rejected| rejected.uid == uid);
+        assert!(
+            as_loader || as_rejected,
+            "component {uid} 既没成为加载器、也没进未支持清单（= 静默丢了）"
+        );
+    }
+}
+
+#[test]
+fn reads_memory_from_instance_cfg_only_when_override_memory_is_on() {
+    let root = temp_root("mmc-mem");
+    let source = root.join("instance");
+    write_file(
+        &source.join("mmc-pack.json"),
+        br#"{"formatVersion": 1, "components": [
+            {"uid": "net.minecraft", "version": "1.20.1"},
+            {"uid": "net.fabricmc.fabric-loader", "version": "0.15.11"}]}"#,
+    );
+    write_file(
+        &source.join("instance.cfg"),
+        b"InstanceType=OneSix\nname=mem pack\nOverrideMemory=true\nMaxMemAlloc=6144\nMinMemAlloc=1024\n",
+    );
+    write_file(&source.join(".minecraft/mods/a.jar"), b"jar");
+
+    let target = temp_root("mmc-mem-out").join("instance");
+    let report = block_on(import_pack(&ImportRequest::new(&source, &target)));
+    assert_eq!(report.max_memory_mb, Some(6144), "{:?}", report.error);
+    assert!(report
+        .warnings
+        .iter()
+        .any(|note| note.message_key == keys::NOTE_INSTANCE_CFG_MEMORY));
+
+    // 开关没开时不采用（只看值不看开关会误判）。
+    let gated = root.join("gated");
+    write_file(
+        &gated.join("mmc-pack.json"),
+        br#"{"formatVersion": 1, "components": [
+            {"uid": "net.minecraft", "version": "1.20.1"}]}"#,
+    );
+    write_file(
+        &gated.join("instance.cfg"),
+        b"InstanceType=OneSix\nname=gated\nOverrideMemory=false\nMaxMemAlloc=6144\n",
+    );
+    write_file(&gated.join(".minecraft/mods/a.jar"), b"jar");
+    let gated_target = temp_root("mmc-mem-gated-out").join("instance");
+    let gated_report = block_on(import_pack(&ImportRequest::new(&gated, &gated_target)));
+    assert_eq!(gated_report.max_memory_mb, None);
+    assert!(gated_report
+        .warnings
+        .iter()
+        .any(|note| note.message_key == keys::NOTE_INSTANCE_CFG_MEMORY));
+}
+
+#[test]
+fn registers_the_instance_when_a_launcher_layout_is_given() {
+    // 登记阶段（读取清单 → 解压 → 补全 → 落地 → **注册实例**）的 happy path：
+    // 内容落盘后写 profiles.json + config/instances/<id>.json。
+    let root = temp_root("mmc-register");
+    let source = fixtures::multimc("mmc-register-src");
+    let target = root.join("instance");
+    let home = root.join("data");
+    let layout = crate::platform::layout::LauncherLayout::new(&home);
+    let request = ImportRequest::new(&source, &target).with_registration(&layout, Some("my pack"));
+    let report = block_on(import_pack(&request));
+
+    assert_eq!(report.status, ImportStatus::Success, "{:?}", report.error);
+    let registered = report.registered.as_ref().expect("要登记实例");
+    assert_eq!(registered.name, "my pack");
+    assert_eq!(registered.version_id, "1.20.1-fabric-0.15.11");
+    assert!(registered.created);
+    // profiles.json 真的写出来了，且指回同一个版本 id。
+    let profiles = crate::game::install::instance::read_profiles(&layout).expect("读档案");
+    assert_eq!(profiles.profiles.len(), 1);
+    assert_eq!(profiles.profiles[0].version_id, "1.20.1-fabric-0.15.11");
+    assert_eq!(profiles.profiles[0].name, "my pack");
+    assert!(report
+        .warnings
+        .iter()
+        .any(|note| note.message_key == keys::NOTE_REGISTERED));
+    assert!(report.rollback.is_none(), "成功路径不该有回滚记录");
+}
+
+#[test]
+fn rejects_mmc_pack_with_other_format_version() {
+    // Prism 的规矩：`formatVersion` 必须恰为 1，否则整份丢弃（不是降级解析）。
+    let root = temp_root("mmc-v2");
+    let source = root.join("instance");
+    write_file(
+        &source.join("mmc-pack.json"),
+        br#"{"formatVersion": 2, "components": [
+            {"uid": "net.minecraft", "version": "1.20.1"}]}"#,
+    );
+    write_file(
+        &source.join("instance.cfg"),
+        b"InstanceType=OneSix\nname=v2\n",
+    );
+    write_file(&source.join(".minecraft/mods/a.jar"), b"jar");
+
+    let target = temp_root("mmc-v2-out").join("instance");
+    let report = block_on(import_pack(&ImportRequest::new(&source, &target)));
+
+    assert_eq!(report.status, ImportStatus::Failed);
+    let error = report.error.as_ref().expect("必须有具名错误");
+    assert_eq!(error.code(), "pack_metadata");
+    assert!(
+        error.message().contains("formatVersion"),
+        "{}",
+        error.message()
+    );
+    assert!(report.rolled_back);
+    super::assert_absent(&target);
+}
diff --git a/crates/core/src/addon/tests/import_report.rs b/crates/core/src/addon/tests/import_report.rs
new file mode 100644
index 0000000..8c63dd3
--- /dev/null
+++ b/crates/core/src/addon/tests/import_report.rs
@@ -0,0 +1,159 @@
+//! 报告的**契约**测试：三态退出码、JSON 形状、文案 key 表没有死常量。
+
+use serde_json::Value;
+
+use crate::addon::import::{
+    import_pack, keys, ImportRequest, ImportStage, ImportStatus, MissingReason,
+};
+use crate::download::blocking::block_on;
+
+use super::support::mrpack_stub;
+use super::temp_root;
+
+#[test]
+fn status_maps_to_three_distinct_exit_codes() {
+    // CLI 契约：0 = Success，3 = Partial，1 = Failed（2 留给内部错误）。
+    assert_eq!(ImportStatus::Success.exit_code(), 0);
+    assert_eq!(ImportStatus::Partial.exit_code(), 3);
+    assert_eq!(ImportStatus::Failed.exit_code(), 1);
+    // 每个状态都有独立文案 key。
+    let mut keyed = vec![
+        ImportStatus::Success.message_key(),
+        ImportStatus::Partial.message_key(),
+        ImportStatus::Failed.message_key(),
+    ];
+    keyed.sort_unstable();
+    keyed.dedup();
+    assert_eq!(keyed.len(), 3);
+    // 五个阶段也各有 key，且都能进报告。
+    let stages = [
+        ImportStage::Probe,
+        ImportStage::Extract,
+        ImportStage::Fetch,
+        ImportStage::Commit,
+        ImportStage::Register,
+    ];
+    assert_eq!(stages.len(), 5);
+    for stage in stages {
+        assert!(keys::ALL.contains(&stage.message_key()), "{:?}", stage);
+    }
+}
+
+#[test]
+fn report_serialises_to_stable_json_with_structured_error() {
+    // 失败也要输出结构化 JSON（不抛栈）：`status` / `error.code` / `rolled_back` 一个不少。
+    let root = temp_root("report-json");
+    let pack = root.join("evil.zip");
+    super::write_zip(&pack, &[("manifest.json", b"{\"manifestType\":")]);
+    let target = root.join("instance");
+    let report = block_on(import_pack(&ImportRequest::new(&pack, &target)));
+
+    let value: Value = serde_json::to_value(&report).expect("报告要能序列化");
+    assert_eq!(value["status"], Value::String("failed".to_string()));
+    assert_eq!(value["rolled_back"], Value::Bool(true));
+    let error = value["error"].as_object().expect("error 是对象");
+    assert!(error["code"].is_string(), "{error:?}");
+    assert!(error["message"].is_string(), "{error:?}");
+    assert_eq!(report.status.exit_code(), 1);
+}
+
+#[test]
+fn successful_report_serialises_counts_and_loader() {
+    let (fixture, fetcher) = mrpack_stub("report-ok");
+    let target = temp_root("report-ok-out").join("instance");
+    let report = block_on(import_pack(
+        &ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher),
+    ));
+    assert_eq!(report.status, ImportStatus::Success, "{:?}", report.error);
+
+    let value: Value = serde_json::to_value(&report).expect("序列化");
+    assert_eq!(value["status"], Value::String("success".to_string()));
+    assert_eq!(value["format"], Value::String("modrinth".to_string()));
+    assert_eq!(value["loader"]["kind"], Value::String("fabric".to_string()));
+    assert_eq!(
+        value["loader"]["version_id"],
+        Value::String("1.20.1-fabric-0.15.11".to_string())
+    );
+    assert!(value["files"]
+        .as_array()
+        .is_some_and(|files| !files.is_empty()));
+    assert!(value["conflicts"].as_array().is_some_and(Vec::is_empty));
+    assert!(value["missing"].as_array().is_some_and(Vec::is_empty));
+}
+
+#[test]
+fn every_message_key_is_referenced_somewhere() {
+    // 防"死常量表"：keys 模块里每个常量除了**定义**与 `ALL` 里的**一处**列举，至少还要有
+    // 一处真实引用（`keys::X` 或同模块里的 `X`）。少于此数就说明它没人用。
+    let table = key_table();
+    let mut values: Vec<&str> = table.iter().map(|(_, value)| value.as_str()).collect();
+    values.sort_unstable();
+    let mut declared = keys::ALL.to_vec();
+    declared.sort_unstable();
+    assert_eq!(values, declared, "keys::ALL 与常量定义不一致");
+
+    let sources = SOURCES.concat();
+    let mut dead: Vec<&str> = Vec::new();
+    for (name, value) in &table {
+        let hits = sources.matches(name.as_str()).count();
+        assert!(
+            hits >= 3,
+            "key {name}（{value}）只出现 {hits} 次，像是死常量"
+        );
+        if hits < 3 {
+            dead.push(name);
+        }
+    }
+    assert!(dead.is_empty(), "{dead:?}");
+}
+
+#[test]
+fn reason_enums_carry_their_own_keys() {
+    for reason in [
+        MissingReason::Offline,
+        MissingReason::NoSource,
+        MissingReason::FetchFailed,
+    ] {
+        assert!(keys::ALL.contains(&reason.message_key()), "{reason:?}");
+    }
+}
+
+/// 导入模块的全部源码（key 引用计数用）。
+const SOURCES: &[&str] = &[
+    include_str!("../import.rs"),
+    include_str!("../import/error.rs"),
+    include_str!("../import/report.rs"),
+    include_str!("../import/report/keys.rs"),
+    include_str!("../import/report/items.rs"),
+    include_str!("../import/plan/paths.rs"),
+    include_str!("../import/stage/commit.rs"),
+    include_str!("../import/baseline.rs"),
+    include_str!("../import/fetch.rs"),
+    include_str!("../import/merge.rs"),
+    include_str!("../import/phase.rs"),
+    include_str!("../import/pipeline.rs"),
+    include_str!("../import/plan.rs"),
+    include_str!("../import/stage.rs"),
+    include_str!("../mod.rs"),
+];
+
+/// 从 `keys` 模块的源码里解析出 `(常量名, 常量值)` 表（不手抄第二份清单）。
+fn key_table() -> Vec<(String, String)> {
+    let source = include_str!("../import/report/keys.rs");
+    let mut out = Vec::new();
+    for line in source.lines() {
+        let line = line.trim();
+        let Some(rest) = line.strip_prefix("pub const ") else {
+            continue;
+        };
+        let Some((name, tail)) = rest.split_once(": &str = \"") else {
+            continue;
+        };
+        let Some((value, _)) = tail.split_once('"') else {
+            continue;
+        };
+        out.push((name.to_string(), value.to_string()));
+    }
+    assert!(!out.is_empty(), "没有解析到任何 key 常量");
+    out
+}
diff --git a/crates/core/src/addon/tests/mod.rs b/crates/core/src/addon/tests/mod.rs
new file mode 100644
index 0000000..6823527
--- /dev/null
+++ b/crates/core/src/addon/tests/mod.rs
@@ -0,0 +1,175 @@
+//! `addon` 的**导入管线**测试（M111）：三格式端到端 + 三方合并 + 必须先失败的恶意样本。
+//!
+//! # 夹具来源
+//!
+//! [`fixtures`] 不是本目录的文件，而是用 `#[path]` 直接吃 M110 的
+//! `addon/pack/tests/fixtures.rs`——**同一份手造包只维护一处**。它的来源声明也在那边：
+//! 三份 CF / mrpack / MultiMC 包全部手造（字段取自 analyse/05 的 HMCL 解析器形状），
+//! 没有一个来自真实导出；`mods/half.jar` / `config/broken.toml` / `mods/broken.jar`
+//! 是刻意造的坏文件（导入器不许崩，也不许悄悄丢）。
+//!
+//! 为了让 `mod` 路径上的 `use super::{temp_root, write_file, zip_dir}` 解析得到，本文件把
+//! 这三个辅助函数放在与 `addon/pack/tests/mod.rs` 同名同形的位置。
+//!
+//! # 全部离线
+//!
+//! 网络一律走 [`support::StubFetcher`]（内存里的假文件），没有一个用例发请求。
+
+// `fixtures.rs` 被 `addon::pack::tests` 与本目录**同时**编译（同一份手造包只维护一处），
+// 所以 clippy 的 `duplicate_mod` 在这里是刻意为之：改成两份副本才是真的错。
+#[allow(clippy::duplicate_mod)]
+#[path = "../pack/tests/fixtures.rs"]
+mod fixtures;
+mod import_curseforge;
+mod import_failures;
+mod import_merge;
+mod import_modrinth;
+mod import_multimc;
+mod import_report;
+mod support;
+
+use std::fs::File;
+use std::io::Write;
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+
+/// 本次进程内唯一的临时根目录（沿用仓库既有约定：不引 `tempfile`）。
+pub(crate) fn temp_root(tag: &str) -> PathBuf {
+    static COUNTER: AtomicU64 = AtomicU64::new(0);
+    let unique = COUNTER.fetch_add(1, Ordering::Relaxed);
+    std::env::temp_dir().join(format!("ull-import-{}-{tag}-{unique}", std::process::id()))
+}
+
+/// 写一个文件（自动建父目录）。
+pub(crate) fn write_file(path: &Path, bytes: &[u8]) {
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent).expect("建目录");
+    }
+    std::fs::write(path, bytes).expect("写文件");
+}
+
+/// 把一个目录打成 zip（`Stored`，方便断言字节）。
+pub(crate) fn zip_dir(source: &Path, target: &Path) {
+    if let Some(parent) = target.parent() {
+        std::fs::create_dir_all(parent).expect("建 zip 目录");
+    }
+    let file = File::create(target).expect("建 zip");
+    let mut writer = zip::ZipWriter::new(file);
+    let options =
+        zip::write::SimpleFileOptions::default().compression_method(zip::CompressionMethod::Stored);
+    let mut pending = vec![PathBuf::new()];
+    while let Some(relative) = pending.pop() {
+        let dir = source.join(&relative);
+        let mut children: Vec<_> = std::fs::read_dir(&dir)
+            .expect("读目录")
+            .collect::<Result<Vec<_>, _>>()
+            .expect("目录项");
+        children.sort_by_key(std::fs::DirEntry::file_name);
+        for child in children {
+            let relative = relative.join(child.file_name());
+            if child.file_type().expect("类型").is_dir() {
+                pending.push(relative);
+                continue;
+            }
+            let bytes = std::fs::read(child.path()).expect("读夹具文件");
+            let entry = relative.to_string_lossy().replace('\\', "/");
+            writer.start_file(entry, options).expect("写 zip 条目");
+            writer.write_all(&bytes).expect("写 zip 内容");
+        }
+    }
+    writer.finish().expect("收尾 zip");
+}
+
+/// 用一张显式条目表打 zip（恶意样本用）。
+pub(crate) fn write_zip(target: &Path, entries: &[(&str, &[u8])]) {
+    if let Some(parent) = target.parent() {
+        std::fs::create_dir_all(parent).expect("建 zip 目录");
+    }
+    let file = File::create(target).expect("建 zip");
+    let mut writer = zip::ZipWriter::new(file);
+    let options =
+        zip::write::SimpleFileOptions::default().compression_method(zip::CompressionMethod::Stored);
+    for (name, bytes) in entries {
+        writer.start_file(*name, options).expect("写 zip 条目");
+        writer.write_all(bytes).expect("写 zip 内容");
+    }
+    writer.finish().expect("收尾 zip");
+}
+
+/// 打一个带**符号链接条目**的 zip（`S_IFLNK` + 目标当内容）。
+pub(crate) fn write_zip_with_symlink(
+    target: &Path,
+    entries: &[(&str, &[u8])],
+    link_name: &str,
+    link_target: &str,
+) {
+    if let Some(parent) = target.parent() {
+        std::fs::create_dir_all(parent).expect("建 zip 目录");
+    }
+    let file = File::create(target).expect("建 zip");
+    let mut writer = zip::ZipWriter::new(file);
+    let options =
+        zip::write::SimpleFileOptions::default().compression_method(zip::CompressionMethod::Stored);
+    for (name, bytes) in entries {
+        writer.start_file(*name, options).expect("写 zip 条目");
+        writer.write_all(bytes).expect("写 zip 内容");
+    }
+    writer
+        .add_symlink(link_name, link_target, options)
+        .expect("写符号链接条目");
+    writer.finish().expect("收尾 zip");
+}
+
+/// 递归列出目录下的文件（`/` 分隔的相对路径，排序）。
+///
+/// "失败后目标目录零残留"就是靠它断言的：`Failed` 之后这里必须返回空表。
+pub(crate) fn list_tree(root: &Path) -> Vec<String> {
+    fn walk(base: &Path, dir: &Path, out: &mut Vec<String>) {
+        let Ok(entries) = std::fs::read_dir(dir) else {
+            return;
+        };
+        for entry in entries.flatten() {
+            let path = entry.path();
+            if path.is_dir() {
+                walk(base, &path, out);
+            } else {
+                out.push(
+                    path.strip_prefix(base)
+                        .unwrap_or(&path)
+                        .to_string_lossy()
+                        .replace('\\', "/"),
+                );
+            }
+        }
+    }
+    let mut out = Vec::new();
+    walk(root, root, &mut out);
+    out.sort();
+    out
+}
+
+/// 基线相对实例根的路径（`/` 分隔，给 `list_tree` 断言用）。
+///
+/// 从 `PackBaseline::relative_path()` 派生，**不在测试里手抄**目录名——手抄的那一份正是
+/// 复审 r5 P1-1 的成因（读写两条路径各写各的）。
+pub(crate) fn baseline_rel() -> String {
+    crate::addon::import::PackBaseline::relative_path()
+        .to_string_lossy()
+        .replace('\\', "/")
+}
+
+/// 读一个文件成字符串（断言覆盖内容用）。
+pub(crate) fn read_text(path: &Path) -> String {
+    let bytes =
+        std::fs::read(path).unwrap_or_else(|error| panic!("读 {} 失败：{error}", path.display()));
+    String::from_utf8_lossy(&bytes).to_string()
+}
+
+/// 断言目录不存在（= 零残留）。
+pub(crate) fn assert_absent(path: &Path) {
+    assert!(
+        !path.exists(),
+        "目标目录应当不存在（零残留），实际：{:?}",
+        list_tree(path)
+    );
+}
diff --git a/crates/core/src/addon/tests/support.rs b/crates/core/src/addon/tests/support.rs
new file mode 100644
index 0000000..e795797
--- /dev/null
+++ b/crates/core/src/addon/tests/support.rs
@@ -0,0 +1,208 @@
+//! 测试替身：内存里的远端（零网络）+ 把 M110 的 mrpack 夹具改成"声明与实际一致"的帮助器。
+//!
+//! # 为什么要改哈希
+//!
+//! M110 的 mrpack 夹具里 `hashes` 是**形状正确的占位值**（`0123456789abcdef…`），不对应任何
+//! 真实字节——那份夹具的用途是"读得出、写得回"，不是"能装上"。导入链要校验"声明与实际
+//! 是否相符"，所以：
+//!
+//! - **成功路径**用 [`mrpack_stub`]：沿用同一份夹具目录，只把 `sha1` 换成真实摘要、把
+//!   `downloads` 换成 `stub://` 地址（`sha512` 是占位值不影响：导入只校验 `sha1`，
+//!   而 M110 的读者只校验 `sha512` 的**形状**）；
+//! - **声明与实际不符**用原始夹具：占位 `sha1` 一定不等于实际字节 ⇒ 必须 `Failed`。
+//!
+//! 两件事用同一份夹具，比手搓两个包更能说明"判据真的在跑"。
+
+use std::collections::BTreeMap;
+use std::sync::Mutex;
+
+use serde_json::json;
+
+use super::super::import::{CurseFileMeta, FetchFuture, FetchRequest, FetchedFile, PackFetcher};
+use super::fixtures;
+use super::fixtures::Fixture;
+use super::{write_file, zip_dir};
+use crate::download::verify::digest_bytes;
+use crate::download::HashAlgo;
+
+/// 成功路径上 `mods/jei.jar` 的内容。
+pub(crate) const JEI_BYTES: &[u8] = b"stub jei jar: not a real jar, just bytes";
+/// 成功路径上 `mods/optional.jar` 的内容。
+pub(crate) const OPTIONAL_BYTES: &[u8] = b"stub optional";
+/// 成功路径上两个文件的下载地址。
+pub(crate) const JEI_URL: &str = "stub://mods/jei.jar";
+/// 第二个文件的下载地址。
+pub(crate) const OPTIONAL_URL: &str = "stub://mods/optional.jar";
+/// CF 夹具里两个条目的补全地址（stub）。
+pub(crate) const CURSE_URL: &str = "stub://curse/jei.jar";
+/// M110 mrpack 夹具里 `mods/jei.jar` 的**占位**下载地址（原始夹具用，配的是假哈希）。
+pub(crate) const JEI_PLACEHOLDER_URL: &str =
+    "https://cdn.modrinth.com/data/AANobbMI/versions/abc/jei.jar";
+/// M110 mrpack 夹具里 `mods/optional.jar` 的**占位**下载地址。
+pub(crate) const OPTIONAL_PLACEHOLDER_URL: &str =
+    "https://cdn.modrinth.com/data/opt/versions/x/optional.jar";
+
+/// 一个字节的 SHA-1（小写十六进制）。
+pub(crate) fn sha1(bytes: &[u8]) -> String {
+    digest_bytes(HashAlgo::Sha1, bytes)
+}
+
+/// 内存 fetcher：按 URL / (project, file) 查表，写盘后回成功。
+pub(crate) struct StubFetcher {
+    files: BTreeMap<String, Vec<u8>>,
+    curse: BTreeMap<(i64, i64), CurseFileMeta>,
+    /// 被请求过的 URL（断言"没白下载"用）。
+    calls: Mutex<Vec<String>>,
+    /// 是否像真引擎那样在目标旁边留下续传残片（`.ullpart-*` / `.ullmeta.json`）。
+    artifacts: bool,
+}
+
+impl StubFetcher {
+    /// 空表。
+    pub(crate) fn new() -> Self {
+        Self {
+            files: BTreeMap::new(),
+            curse: BTreeMap::new(),
+            calls: Mutex::new(Vec::new()),
+            artifacts: false,
+        }
+    }
+
+    /// 挂一个可下载的地址。
+    pub(crate) fn with_file(mut self, url: &str, bytes: &[u8]) -> Self {
+        self.files.insert(url.to_string(), bytes.to_vec());
+        self
+    }
+
+    /// 挂一条 CurseForge 元数据。
+    pub(crate) fn with_curse(mut self, project_id: i64, file_id: i64, meta: CurseFileMeta) -> Self {
+        self.curse.insert((project_id, file_id), meta);
+        self
+    }
+
+    /// 像真引擎那样在每次"下载"后留下续传残片与 meta（用来钉"中间产物不许进实例"）。
+    pub(crate) fn with_engine_artifacts(mut self) -> Self {
+        self.artifacts = true;
+        self
+    }
+
+    /// 被请求过的 URL 列表。
+    pub(crate) fn calls(&self) -> Vec<String> {
+        self.calls.lock().expect("calls 锁").clone()
+    }
+}
+
+impl PackFetcher for StubFetcher {
+    fn curse_file<'a>(
+        &'a self,
+        project_id: i64,
+        file_id: i64,
+    ) -> FetchFuture<'a, Result<CurseFileMeta, super::super::import::FetchError>> {
+        Box::pin(async move {
+            self.curse
+                .get(&(project_id, file_id))
+                .cloned()
+                .ok_or_else(|| {
+                    super::super::import::FetchError::new(
+                        super::super::import::FetchErrorKind::NotFound,
+                        format!("stub 里没有 {project_id}:{file_id}"),
+                    )
+                })
+        })
+    }
+
+    fn fetch_file<'a>(
+        &'a self,
+        request: FetchRequest<'a>,
+    ) -> FetchFuture<'a, Result<FetchedFile, super::super::import::FetchError>> {
+        Box::pin(async move {
+            self.calls
+                .lock()
+                .expect("calls 锁")
+                .push(request.url.to_string());
+            let bytes = self.files.get(request.url).cloned().ok_or_else(|| {
+                super::super::import::FetchError::new(
+                    super::super::import::FetchErrorKind::NotFound,
+                    format!("stub 里没有 {}", request.url),
+                )
+            })?;
+            if let Some(parent) = request.dest.parent() {
+                std::fs::create_dir_all(parent).map_err(|error| {
+                    super::super::import::FetchError::new(
+                        super::super::import::FetchErrorKind::Io,
+                        error.to_string(),
+                    )
+                })?;
+            }
+            std::fs::write(request.dest, &bytes).map_err(|error| {
+                super::super::import::FetchError::new(
+                    super::super::import::FetchErrorKind::Io,
+                    error.to_string(),
+                )
+            })?;
+            if self.artifacts {
+                leave_engine_artifacts(request.dest);
+            }
+            Ok(FetchedFile {
+                bytes: bytes.len() as u64,
+            })
+        })
+    }
+}
+
+/// 把 M110 的 mrpack 夹具改成"声明与实际一致"，并配好 stub fetcher。
+///
+/// 只改两处：`files[].hashes.sha1`（换成真实摘要）与 `files[].downloads`（换成 `stub://`）。
+pub(crate) fn mrpack_stub(tag: &str) -> (Fixture, StubFetcher) {
+    let fixture = fixtures::modrinth(tag);
+    let index_path = fixture.dir.join("modrinth.index.json");
+    let text = std::fs::read_to_string(&index_path).expect("读夹具 index");
+    let mut value: serde_json::Value = serde_json::from_str(&text).expect("解析夹具 index");
+    let entries = [
+        ("mods/jei.jar", JEI_BYTES, JEI_URL),
+        ("mods/optional.jar", OPTIONAL_BYTES, OPTIONAL_URL),
+    ];
+    let files = value["files"].as_array_mut().expect("夹具 files 是数组");
+    for (entry, (path, bytes, url)) in files.iter_mut().zip(entries) {
+        assert_eq!(
+            entry["path"],
+            json!(path),
+            "夹具条目顺序变了，本帮助器要跟着改"
+        );
+        entry["hashes"]["sha1"] = json!(sha1(bytes));
+        entry["downloads"] = json!([url]);
+        entry["fileSize"] = json!(bytes.len());
+    }
+    write_file(&index_path, value.to_string().as_bytes());
+    zip_dir(&fixture.dir, &fixture.zip);
+
+    let fetcher = StubFetcher::new()
+        .with_file(JEI_URL, JEI_BYTES)
+        .with_file(OPTIONAL_URL, OPTIONAL_BYTES);
+    (fixture, fetcher)
+}
+
+/// CF 夹具的 stub 元数据（两个条目都补得出来，落在 `mods/`）。
+pub(crate) fn curse_meta(file_name: &str, bytes: &[u8]) -> CurseFileMeta {
+    CurseFileMeta {
+        file_name: file_name.to_string(),
+        url: Some(CURSE_URL.to_string()),
+        sha1: Some(sha1(bytes)),
+        size: Some(bytes.len() as u64),
+        class_id: Some(6),
+    }
+}
+
+/// 在目标旁边留下与 `core::download::atomic` 同名的续传残片与 meta。
+fn leave_engine_artifacts(dest: &std::path::Path) {
+    let Some(name) = dest
+        .file_name()
+        .map(|name| name.to_string_lossy().to_string())
+    else {
+        return;
+    };
+    let part = dest.with_file_name(format!("{name}.ullpart-{}-0", std::process::id()));
+    let meta = dest.with_file_name(format!("{name}.ullmeta.json"));
+    std::fs::write(part, b"partial bytes").expect("写续传残片");
+    std::fs::write(meta, b"{}").expect("写续传 meta");
+}
diff --git a/crates/core/src/auth/account.rs b/crates/core/src/auth/account.rs
new file mode 100644
index 0000000..a7f51f1
--- /dev/null
+++ b/crates/core/src/auth/account.rs
@@ -0,0 +1,339 @@
+//! 账户模型：**条目 id 与 profileID 解耦**的三轨统一抽象。
+//!
+//! 承 `analyse/04` §2.3 / §3.2 / §12.1(1) 的三条硬教训：
+//! 1. 条目 id（`account:<32hex>`）**不得**等于 profileID / 登录名 / 服务器 URL——
+//!    这些值可能被多个条目共享（同一角色导入两次、服务器换域名）；
+//! 2. **元数据 / 凭据双写分离**：`AccountMeta` 只装「能公开」的字段（列表渲染不需要解密）；
+//! 3. 反序列化**允许不完整对象**（`profile_name` 可空 = 「有档案但名字待刷新」），
+//!    补齐推迟到登录时——不能因为名字未知就整条丢弃。
+
+use serde::{Deserialize, Serialize};
+
+use crate::auth::authlib::AuthlibSession;
+use crate::auth::error::{AuthError, AuthResult};
+use crate::auth::microsoft::MicrosoftSession;
+use crate::auth::secret::random_hex32;
+
+/// 条目 id 前缀（防被误当 UUID；承 HMCL `AccountID.PREFIX`）。
+pub const ACCOUNT_ID_PREFIX: &str = "account:";
+
+/// 账户条目 id：`account:<32 位十六进制>`。
+///
+/// 与 profileID 无关：改服务器地址、改玩家名、同角色多条目都不影响它。
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
+#[serde(transparent)]
+pub struct AccountId(String);
+
+impl AccountId {
+    /// 生成一个新条目 id。
+    #[must_use]
+    pub fn generate() -> Self {
+        Self(format!("{ACCOUNT_ID_PREFIX}{}", random_hex32()))
+    }
+
+    /// 从磁盘字符串解析（宽容：坏数据返回 `None`，不 panic）。
+    #[must_use]
+    pub fn parse(raw: &str) -> Option<Self> {
+        let body = raw.strip_prefix(ACCOUNT_ID_PREFIX)?;
+        if body.len() != 32 || !body.chars().all(|ch| ch.is_ascii_hexdigit()) {
+            return None;
+        }
+        Some(Self(raw.to_ascii_lowercase()))
+    }
+
+    /// 字符串视图。
+    #[must_use]
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+}
+
+impl std::fmt::Display for AccountId {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter.write_str(&self.0)
+    }
+}
+
+/// 三条轨道。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum AccountKind {
+    /// 离线（本地生成的 UUID，不联网）。
+    Offline,
+    /// 微软（device-code / 授权码浏览器）。
+    Microsoft,
+    /// authlib-injector 第三方认证服务器（标准 Yggdrasil 协议）。
+    AuthlibInjector,
+}
+
+impl AccountKind {
+    /// 落盘用的稳定名（承 HMCL 的 `offline` / `microsoft` / `authlibInjector`）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Offline => "offline",
+            Self::Microsoft => "microsoft",
+            Self::AuthlibInjector => "authlibInjector",
+        }
+    }
+
+    /// 解析（未知值返回 `None`，让上层跳过该条记录）。
+    #[must_use]
+    pub fn parse(raw: &str) -> Option<Self> {
+        match raw {
+            "offline" => Some(Self::Offline),
+            "microsoft" => Some(Self::Microsoft),
+            // 兼容两种写法：HMCL 用 camelCase，别的地方有人写 kebab。
+            "authlibInjector" | "authlib-injector" => Some(Self::AuthlibInjector),
+            _ => None,
+        }
+    }
+
+    /// 人读标签（CLI/JSON 展示用）。
+    #[must_use]
+    pub const fn label(self) -> &'static str {
+        match self {
+            Self::Offline => "离线",
+            Self::Microsoft => "微软",
+            Self::AuthlibInjector => "authlib-injector",
+        }
+    }
+}
+
+/// 账户元数据（**可公开**，不含任何凭据）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountMeta {
+    /// 条目 id。
+    pub id: AccountId,
+    /// 轨道。
+    pub kind: AccountKind,
+    /// Minecraft 档案 UUID（32 位无连字符）。**不可变**。
+    pub profile_id: String,
+    /// 展示名/玩家名；空串 = 「有档案但名字待刷新」（合法中间态）。
+    #[serde(default)]
+    pub profile_name: String,
+    /// 登录名（authlib 轨的邮箱/用户名；其余轨为 `None`）。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub login_name: Option<String>,
+    /// authlib 认证服务器 API 根（其余轨为 `None`；凭据之外唯一需要持久化的服务器信息）。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub server_url: Option<String>,
+    /// 创建时刻（Unix 毫秒；仅用于排序/展示）。
+    pub created_at_ms: u64,
+}
+
+impl AccountMeta {
+    /// 构造一条元数据（`profile_name` 可后补）。
+    #[must_use]
+    pub fn new(
+        kind: AccountKind,
+        profile_id: impl Into<String>,
+        profile_name: impl Into<String>,
+        created_at_ms: u64,
+    ) -> Self {
+        Self {
+            id: AccountId::generate(),
+            kind,
+            profile_id: profile_id.into(),
+            profile_name: profile_name.into(),
+            login_name: None,
+            server_url: None,
+            created_at_ms,
+        }
+    }
+
+    /// 展示名：优先玩家名，其次登录名，最后条目 id（永不 panic、永不空串）。
+    #[must_use]
+    pub fn display_name(&self) -> &str {
+        if !self.profile_name.trim().is_empty() {
+            return &self.profile_name;
+        }
+        if let Some(login_name) = &self.login_name {
+            if !login_name.trim().is_empty() {
+                return login_name;
+            }
+        }
+        self.id.as_str()
+    }
+
+    /// 该条目是否匹配一个查找键（名字 / 登录名 / 条目 id）。
+    ///
+    /// 大小写不敏感：玩家名在 MC 里大小写不敏感，CLI 用户不该为此折腾。
+    #[must_use]
+    pub fn matches(&self, key: &str) -> bool {
+        let key = key.trim();
+        if key.is_empty() {
+            return false;
+        }
+        self.profile_name.eq_ignore_ascii_case(key)
+            || self
+                .login_name
+                .as_deref()
+                .is_some_and(|name| name.eq_ignore_ascii_case(key))
+            || self.id.as_str().eq_ignore_ascii_case(key)
+    }
+
+    /// 该条目的凭据是否与轨道匹配（防止磁盘上元数据被换成另一轨）。
+    ///
+    /// # Errors
+    ///
+    /// 轨道与凭据种类不一致时返回 [`AuthError::Malformed`]。
+    pub fn check_credentials(&self, credentials: &Credentials) -> AuthResult<()> {
+        if credentials.kind() == self.kind {
+            return Ok(());
+        }
+        Err(AuthError::Malformed(format!(
+            "账户 {} 的元数据轨道是 {}，凭据却是 {}",
+            self.id,
+            self.kind.as_str(),
+            credentials.kind().as_str()
+        )))
+    }
+
+    /// 从 JSON 值宽容解析（单条坏记录只返回 `Err`，由调用方跳过并记 warning）。
+    ///
+    /// # Errors
+    ///
+    /// 缺字段/类型不符/轨道未知时返回 [`AuthError::Malformed`]。
+    pub fn from_value(value: &serde_json::Value) -> AuthResult<Self> {
+        serde_json::from_value(value.clone())
+            .map_err(|error| AuthError::Malformed(format!("账户元数据不合法：{error}")))
+    }
+}
+
+/// 凭据载荷（**私有**，只落 `credentials.dat`，永不进列表/日志）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "camelCase")]
+pub enum Credentials {
+    /// 离线账户没有凭据（accessToken 每次登录随机生成，不落盘）。
+    Offline,
+    /// 微软会话（access + refresh + `notAfter`）。
+    Microsoft(MicrosoftSession),
+    /// authlib 会话（accessToken + clientToken）。
+    AuthlibInjector(AuthlibSession),
+}
+
+impl Credentials {
+    /// 所属轨道。
+    #[must_use]
+    pub const fn kind(&self) -> AccountKind {
+        match self {
+            Self::Offline => AccountKind::Offline,
+            Self::Microsoft(_) => AccountKind::Microsoft,
+            Self::AuthlibInjector(_) => AccountKind::AuthlibInjector,
+        }
+    }
+
+    /// 该凭据里的所有明文敏感值（武装脱敏器用；离线轨为空）。
+    #[must_use]
+    pub fn secrets(&self) -> Vec<&str> {
+        match self {
+            Self::Offline => Vec::new(),
+            Self::Microsoft(session) => session
+                .secrets()
+                .into_iter()
+                .map(|secret| secret.expose())
+                .collect(),
+            Self::AuthlibInjector(session) => session
+                .secrets()
+                .into_iter()
+                .map(|secret| secret.expose())
+                .collect(),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{AccountId, AccountKind, AccountMeta, Credentials};
+    use crate::auth::microsoft::MicrosoftSession;
+    use crate::auth::secret::Secret;
+
+    #[test]
+    fn account_id_shape_and_parse() {
+        let id = AccountId::generate();
+        assert!(id.as_str().starts_with("account:"));
+        assert_eq!(id.as_str().len(), "account:".len() + 32);
+        assert_eq!(AccountId::parse(id.as_str()), Some(id.clone()));
+        assert_eq!(AccountId::parse("account:xyz"), None);
+        assert_eq!(AccountId::parse("0192-blah"), None);
+    }
+
+    #[test]
+    fn kind_roundtrip() {
+        for kind in [
+            AccountKind::Offline,
+            AccountKind::Microsoft,
+            AccountKind::AuthlibInjector,
+        ] {
+            assert_eq!(AccountKind::parse(kind.as_str()), Some(kind));
+            assert!(!kind.label().is_empty());
+        }
+        assert_eq!(AccountKind::parse("nope"), None);
+    }
+
+    #[test]
+    fn meta_matches_name_login_and_id() {
+        let mut meta = AccountMeta::new(AccountKind::Offline, "uuid32", "Steve", 1);
+        meta.login_name = Some("steve@example.com".to_string());
+        assert!(meta.matches("Steve"));
+        assert!(meta.matches("steve"));
+        assert!(meta.matches("steve@example.com"));
+        assert!(meta.matches(meta.id.as_str()));
+        assert!(!meta.matches("Alex"));
+        assert!(!meta.matches("  "));
+    }
+
+    #[test]
+    fn display_name_falls_back() {
+        let mut meta = AccountMeta::new(AccountKind::Microsoft, "uuid", "", 1);
+        assert_eq!(meta.display_name(), meta.id.as_str());
+        meta.login_name = Some("me@example.com".to_string());
+        assert_eq!(meta.display_name(), "me@example.com");
+        meta.profile_name = "Steve".to_string();
+        assert_eq!(meta.display_name(), "Steve");
+    }
+
+    #[test]
+    fn credential_kind_must_match_meta() {
+        let meta = AccountMeta::new(AccountKind::Microsoft, "uuid", "Steve", 1);
+        let session = MicrosoftSession::new(
+            "uuid",
+            "Steve",
+            Secret::new("a"),
+            Secret::new("r"),
+            60,
+            0,
+            None,
+        );
+        assert!(meta
+            .check_credentials(&Credentials::Microsoft(session))
+            .is_ok());
+        assert!(meta.check_credentials(&Credentials::Offline).is_err());
+    }
+
+    #[test]
+    fn secrets_only_expose_real_credentials() {
+        assert!(Credentials::Offline.secrets().is_empty());
+        let session = MicrosoftSession::new(
+            "uuid",
+            "Steve",
+            Secret::new("mc-token"),
+            Secret::new("live-refresh"),
+            60,
+            0,
+            None,
+        );
+        assert_eq!(
+            Credentials::Microsoft(session).secrets(),
+            vec!["mc-token", "live-refresh"]
+        );
+    }
+
+    #[test]
+    fn malformed_record_is_an_error_not_a_panic() {
+        let value = serde_json::json!({ "id": "account:zz", "kind": "offline" });
+        assert!(AccountMeta::from_value(&value).is_err());
+    }
+}
diff --git a/crates/core/src/auth/authlib.rs b/crates/core/src/auth/authlib.rs
new file mode 100644
index 0000000..f2dabff
--- /dev/null
+++ b/crates/core/src/auth/authlib.rs
@@ -0,0 +1,347 @@
+//! authlib-injector 轨（**账户侧**）：标准 Yggdrasil 协议的登录/刷新/校验/注销。
+//!
+//! 边界（mission 明示）：本模块只做「账户」；`-javaagent` 三件套（jar 下载、
+//! `-Dauthlibinjector.side=client`、`yggdrasil.prefetched` 的 Base64）归后续 mission。
+//! 依据 `analyse/04` §6.1–§6.2（端点布局与四动作报文）与 §6.3（服务发现约定）。
+//!
+//! 三条照抄要点：
+//! - 端点 = `<apiRoot>authserver/{authenticate,refresh,validate,invalidate}`，`apiRoot`
+//!   必须带尾斜杠（`https://littleskin.cn/api/yggdrasil/` 这种目录布局是规范要求）；
+//! - `clientToken` 是**启动器侧生成的随机值**，服务端回传必须一致（防会话被替换/重放）；
+//! - 「token 无效」用**返回值 `false`** 表达（`validate` 的 `ForbiddenOperationException`），
+//!   「服务器抽风」才抛错——调用方据此决定「刷新」还是「重试」。
+
+pub mod server_meta;
+
+pub use server_meta::AuthlibServerMeta;
+
+use reqwest::Client;
+use serde_json::json;
+
+use crate::auth::error::{AuthError, AuthResult};
+use crate::auth::http::{post_json, Reply};
+use crate::auth::secret::Secret;
+use crate::download::config::EngineConfig;
+use crate::download::http::build_client;
+use crate::launch::request::AuthPlaceholders;
+
+/// authlib 轨的 launch 用户类型（承 HMCL `YggdrasilSession.toAuthInfo`：也是 `msa`）。
+pub const USER_TYPE_MSA: &str = "msa";
+
+/// 把用户输入规范成 API 根：补 `https://`、补尾斜杠、去空白。
+///
+/// # Errors
+///
+/// 空串或只剩协议头时返回 [`AuthError::Malformed`]。
+pub fn normalize_api_root(input: &str) -> AuthResult<String> {
+    let trimmed = input.trim();
+    if trimmed.is_empty() {
+        return Err(AuthError::Malformed(
+            "认证服务器地址不能为空（例：https://littleskin.cn/api/yggdrasil/）".to_string(),
+        ));
+    }
+    let with_scheme = if trimmed.starts_with("https://") || trimmed.starts_with("http://") {
+        trimmed.to_string()
+    } else {
+        format!("https://{trimmed}")
+    };
+    let host = with_scheme
+        .split_once("://")
+        .map(|(_, rest)| rest)
+        .unwrap_or("");
+    if host.trim_matches('/').is_empty() {
+        return Err(AuthError::Malformed(format!(
+            "认证服务器地址不完整：`{input}`"
+        )));
+    }
+    Ok(if with_scheme.ends_with('/') {
+        with_scheme
+    } else {
+        format!("{with_scheme}/")
+    })
+}
+
+/// Yggdrasil 四个端点（都从 API 根派生）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AuthlibEndpoints {
+    /// `authserver/authenticate`。
+    pub authenticate: String,
+    /// `authserver/refresh`。
+    pub refresh: String,
+    /// `authserver/validate`。
+    pub validate: String,
+    /// `authserver/invalidate`。
+    pub invalidate: String,
+}
+
+impl AuthlibEndpoints {
+    /// 从 API 根派生（先 [`normalize_api_root`]）。
+    ///
+    /// # Errors
+    ///
+    /// 地址不合法时返回 [`AuthError::Malformed`]。
+    pub fn from_api_root(api_root: &str) -> AuthResult<Self> {
+        let root = normalize_api_root(api_root)?;
+        let join = |path: &str| format!("{root}{path}");
+        Ok(Self {
+            authenticate: join("authserver/authenticate"),
+            refresh: join("authserver/refresh"),
+            validate: join("authserver/validate"),
+            invalidate: join("authserver/invalidate"),
+        })
+    }
+}
+
+/// 一个 Yggdrasil 角色（`selectedProfile`）。
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct AuthlibProfile {
+    /// 32 位无连字符 UUID。
+    pub id: String,
+    /// 角色名。
+    pub name: String,
+}
+
+/// authlib 会话 = 该账户的凭据载荷。
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AuthlibSession {
+    /// Yggdrasil accessToken。
+    pub access_token: Secret,
+    /// 启动器生成的 clientToken（刷新/校验都要带）。
+    pub client_token: Secret,
+    /// 当前选中的角色（多角色服务器里由 refresh 的 `selectedProfile` 决定）。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub selected_profile: Option<AuthlibProfile>,
+}
+
+impl AuthlibSession {
+    /// 该会话的全部凭据值（武装脱敏器）。
+    #[must_use]
+    pub fn secrets(&self) -> Vec<&Secret> {
+        vec![&self.access_token, &self.client_token]
+    }
+
+    /// 有没有角色（没角色的会话不能启动游戏）。
+    #[must_use]
+    pub fn has_profile(&self) -> bool {
+        self.selected_profile
+            .as_ref()
+            .is_some_and(|profile| !profile.name.trim().is_empty() && !profile.id.is_empty())
+    }
+
+    /// 转成 launch 占位符。
+    ///
+    /// `user_properties` 用 `{}`：纹理由游戏进程经 authlib-injector 向服务器取
+    /// （注入参数属后续 mission），启动参数不需要它。
+    ///
+    /// # Errors
+    ///
+    /// 会话没有角色时返回 [`AuthError::CredentialExpired`]（需要重新选角色/登录）。
+    pub fn to_placeholders(&self) -> AuthResult<AuthPlaceholders> {
+        let profile = self
+            .selected_profile
+            .as_ref()
+            .filter(|profile| !profile.name.trim().is_empty())
+            .ok_or(AuthError::CredentialExpired)?;
+        Ok(AuthPlaceholders {
+            player_name: profile.name.clone(),
+            uuid: profile.id.clone(),
+            access_token: self.access_token.expose().to_string(),
+            user_type: USER_TYPE_MSA.to_string(),
+            user_properties: "{}".to_string(),
+        })
+    }
+}
+
+/// authlib 认证客户端。
+#[derive(Debug, Clone)]
+pub struct AuthlibAuth {
+    client: Client,
+}
+
+impl AuthlibAuth {
+    /// 构造（HTTP 基座复用 `core::download`）。
+    ///
+    /// # Errors
+    ///
+    /// 客户端建不起来时返回 [`AuthError::Network`]。
+    pub fn new() -> AuthResult<Self> {
+        let client = build_client(&EngineConfig::default())
+            .map_err(|error| AuthError::network("http-client", error.to_string()))?;
+        Ok(Self { client })
+    }
+
+    /// 注入客户端（测试）。
+    #[must_use]
+    pub fn with_client(mut self, client: Client) -> Self {
+        self.client = client;
+        self
+    }
+
+    /// 密码登录（**新账户**）。密码只在本调用栈里出现，不落盘、不入日志。
+    ///
+    /// # Errors
+    ///
+    /// 密码错/服务器拒绝 → [`AuthError::Denied`]；网络与结构问题各有分流。
+    pub async fn authenticate(
+        &self,
+        api_root: &str,
+        login_name: &str,
+        password: &Secret,
+        client_token: &Secret,
+    ) -> AuthResult<AuthlibSession> {
+        let endpoints = AuthlibEndpoints::from_api_root(api_root)?;
+        let body = json!({
+            "agent": { "name": "Minecraft", "version": 1 },
+            "username": login_name,
+            "password": password.expose(),
+            "clientToken": client_token.expose(),
+            "requestUser": true,
+        });
+        let reply = post_json(&self.client, &endpoints.authenticate, &body, None).await?;
+        if !reply.is_success() {
+            return Err(rejected(&reply, &endpoints.authenticate, "登录"));
+        }
+        let session = session_from(&reply, client_token, &endpoints.authenticate)?;
+        if !session.has_profile() {
+            // 服务端没自动选角色（多角色服务器）：交给调用方走 refresh + selectedProfile。
+            return Ok(session);
+        }
+        Ok(session)
+    }
+
+    /// 刷新（可顺带 `selectedProfile` 换角色）。
+    ///
+    /// # Errors
+    ///
+    /// token 失效 → [`AuthError::CredentialExpired`]；换角色失败 → [`AuthError::Malformed`]。
+    pub async fn refresh(
+        &self,
+        api_root: &str,
+        session: &AuthlibSession,
+        select: Option<&AuthlibProfile>,
+    ) -> AuthResult<AuthlibSession> {
+        let endpoints = AuthlibEndpoints::from_api_root(api_root)?;
+        let mut body = json!({
+            "accessToken": session.access_token.expose(),
+            "clientToken": session.client_token.expose(),
+            "requestUser": true,
+        });
+        if let Some(profile) = select {
+            body["selectedProfile"] = json!({ "id": profile.id, "name": profile.name });
+        }
+        let reply = post_json(&self.client, &endpoints.refresh, &body, None).await?;
+        if !reply.is_success() {
+            if is_forbidden(&reply) {
+                return Err(AuthError::CredentialExpired);
+            }
+            return Err(rejected(&reply, &endpoints.refresh, "刷新"));
+        }
+        let refreshed = session_from(&reply, &session.client_token, &endpoints.refresh)?;
+        if let Some(wanted) = select {
+            let got = refreshed.selected_profile.as_ref();
+            if got.map(|profile| profile.id.as_str()) != Some(wanted.id.as_str()) {
+                return Err(AuthError::Malformed(format!(
+                    "服务器没有切到角色 {}（refresh 未生效）",
+                    wanted.name
+                )));
+            }
+        }
+        Ok(refreshed)
+    }
+
+    /// 校验 token 是否仍有效（`ForbiddenOperationException` = `Ok(false)`）。
+    ///
+    /// # Errors
+    ///
+    /// 服务器 5xx/网络失败时返回错误（调用方据此区分「要刷新」与「要重试」）。
+    pub async fn validate(&self, api_root: &str, session: &AuthlibSession) -> AuthResult<bool> {
+        let endpoints = AuthlibEndpoints::from_api_root(api_root)?;
+        let body = json!({
+            "accessToken": session.access_token.expose(),
+            "clientToken": session.client_token.expose(),
+        });
+        let reply = post_json(&self.client, &endpoints.validate, &body, None).await?;
+        if is_forbidden(&reply) {
+            return Ok(false);
+        }
+        if !reply.is_success() {
+            return Err(rejected(&reply, &endpoints.validate, "校验"));
+        }
+        // 成功时 body 为空或 `{}`，都算有效。
+        Ok(true)
+    }
+
+    /// 主动注销（删账户时顺手清理服务端会话；失败按「尽力而为」返回错误，调用方可不理）。
+    ///
+    /// # Errors
+    ///
+    /// 网络/服务端失败时返回错误。
+    pub async fn invalidate(&self, api_root: &str, session: &AuthlibSession) -> AuthResult<()> {
+        let endpoints = AuthlibEndpoints::from_api_root(api_root)?;
+        let body = json!({
+            "accessToken": session.access_token.expose(),
+            "clientToken": session.client_token.expose(),
+        });
+        let reply = post_json(&self.client, &endpoints.invalidate, &body, None).await?;
+        if reply.is_success() || is_forbidden(&reply) {
+            return Ok(());
+        }
+        Err(rejected(&reply, &endpoints.invalidate, "注销"))
+    }
+}
+
+/// 响应 → 会话（`clientToken` 回传必须一致；缺失时保留原值）。
+fn session_from(reply: &Reply, client_token: &Secret, url: &str) -> AuthResult<AuthlibSession> {
+    let access_token = reply
+        .text("accessToken")
+        .ok_or_else(|| AuthError::Malformed(format!("{url} 响应缺 accessToken")))?;
+    if let Some(returned) = reply.text("clientToken") {
+        if returned != client_token.expose() {
+            return Err(AuthError::Malformed(
+                "服务器回传的 clientToken 与本地不一致（会话可能被替换）".to_string(),
+            ));
+        }
+    }
+    Ok(AuthlibSession {
+        access_token: Secret::new(access_token),
+        client_token: client_token.clone(),
+        selected_profile: selected_profile(reply),
+    })
+}
+
+fn selected_profile(reply: &Reply) -> Option<AuthlibProfile> {
+    let profile = reply
+        .body
+        .as_ref()
+        .and_then(|body| body.get("selectedProfile"))?;
+    let id = profile.get("id")?.as_str()?;
+    let name = profile.get("name")?.as_str()?;
+    Some(AuthlibProfile {
+        id: id.to_string(),
+        name: name.to_string(),
+    })
+}
+
+fn is_forbidden(reply: &Reply) -> bool {
+    reply.text("error") == Some("ForbiddenOperationException")
+}
+
+fn rejected(reply: &Reply, url: &str, what: &str) -> AuthError {
+    match reply.text("error") {
+        Some(code) => AuthError::Denied {
+            code: code.to_string(),
+            description: reply
+                .text("errorMessage")
+                .unwrap_or("服务器未给描述")
+                .to_string(),
+        },
+        None => AuthError::network(
+            url.split('?').next().unwrap_or(url),
+            format!("{what}失败（HTTP {}）", reply.status),
+        ),
+    }
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/core/src/auth/authlib/server_meta.rs b/crates/core/src/auth/authlib/server_meta.rs
new file mode 100644
index 0000000..5885293
--- /dev/null
+++ b/crates/core/src/auth/authlib/server_meta.rs
@@ -0,0 +1,86 @@
+//! 认证服务器元数据里我们真正需要的字段（服务发现的产物）。
+//!
+//! authlib-injector 规范里根路径 `/` 返回 `{ meta, skinDomains, signaturePublickey }`
+//! （`analyse/04` §6.3）。本期**只保存**名字/非邮箱登录/skinDomains：
+//! `signaturePublickey` 与 `prefetched` 的 Base64 属于注入参数（后续 mission），
+//! 现在存了也没人消费，不如不存。
+
+use serde_json::Value;
+
+/// 服务器元数据（缺失字段一律回落默认值）。
+#[derive(Debug, Clone, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AuthlibServerMeta {
+    /// 服务器显示名（缺省回落 URL）。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub name: Option<String>,
+    /// 是否允许非邮箱登录名（决定输入框校验）。
+    #[serde(default)]
+    pub non_email_login: bool,
+    /// `skinDomains`（纹理白名单，注入参数会用；本期只保存）。
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub skin_domains: Vec<String>,
+}
+
+impl AuthlibServerMeta {
+    /// 从根元数据 JSON 解析（容错：缺字段就用默认值）。
+    #[must_use]
+    pub fn from_value(value: &Value) -> Self {
+        let meta = value.get("meta");
+        let name = meta
+            .and_then(|meta| meta.get("serverName"))
+            .and_then(Value::as_str)
+            .map(str::to_string);
+        let non_email_login = meta
+            .and_then(|meta| meta.get("feature.non_email_login"))
+            .and_then(Value::as_bool)
+            .unwrap_or(false);
+        let skin_domains = value
+            .get("skinDomains")
+            .and_then(Value::as_array)
+            .map(|items| {
+                items
+                    .iter()
+                    .filter_map(Value::as_str)
+                    .map(str::to_string)
+                    .collect()
+            })
+            .unwrap_or_default();
+        Self {
+            name,
+            non_email_login,
+            skin_domains,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::AuthlibServerMeta;
+    use serde_json::json;
+
+    #[test]
+    fn parses_full_metadata() {
+        let value = json!({
+            "meta": {
+                "serverName": "Example Skin Site",
+                "feature.non_email_login": true
+            },
+            "skinDomains": ["example.com", "*.example.com"],
+            "signaturePublickey": "-----BEGIN PUBLIC KEY-----"
+        });
+        let meta = AuthlibServerMeta::from_value(&value);
+        assert_eq!(meta.name.as_deref(), Some("Example Skin Site"));
+        assert!(meta.non_email_login);
+        assert_eq!(meta.skin_domains.len(), 2);
+    }
+
+    #[test]
+    fn tolerates_missing_fields() {
+        let meta = AuthlibServerMeta::from_value(&json!({}));
+        assert_eq!(meta, AuthlibServerMeta::default());
+        assert!(meta.name.is_none());
+        assert!(!meta.non_email_login);
+        assert!(meta.skin_domains.is_empty());
+    }
+}
diff --git a/crates/core/src/auth/authlib/tests.rs b/crates/core/src/auth/authlib/tests.rs
new file mode 100644
index 0000000..2cb9bcc
--- /dev/null
+++ b/crates/core/src/auth/authlib/tests.rs
@@ -0,0 +1,97 @@
+//! authlib 轨的纯函数/模型测试（HTTP 部分在 `tests/auth/authlib_api.rs`）。
+
+use super::{normalize_api_root, AuthlibEndpoints, AuthlibProfile, AuthlibSession, USER_TYPE_MSA};
+use crate::auth::secret::Secret;
+
+#[test]
+fn api_root_normalization() {
+    assert_eq!(
+        normalize_api_root("littleskin.cn/api/yggdrasil").expect("补协议"),
+        "https://littleskin.cn/api/yggdrasil/"
+    );
+    assert_eq!(
+        normalize_api_root("  http://127.0.0.1:8080/api/yggdrasil/  ").expect("保留协议"),
+        "http://127.0.0.1:8080/api/yggdrasil/"
+    );
+    assert_eq!(
+        normalize_api_root("https://littleskin.cn").expect("根域名"),
+        "https://littleskin.cn/"
+    );
+    assert!(normalize_api_root("   ").is_err());
+    assert!(normalize_api_root("https://").is_err());
+}
+
+#[test]
+fn endpoints_follow_directory_layout() {
+    let endpoints =
+        AuthlibEndpoints::from_api_root("https://example.invalid/api/yggdrasil").expect("端点");
+    assert_eq!(
+        endpoints.authenticate,
+        "https://example.invalid/api/yggdrasil/authserver/authenticate"
+    );
+    assert_eq!(
+        endpoints.refresh,
+        "https://example.invalid/api/yggdrasil/authserver/refresh"
+    );
+    assert_eq!(
+        endpoints.validate,
+        "https://example.invalid/api/yggdrasil/authserver/validate"
+    );
+    assert_eq!(
+        endpoints.invalidate,
+        "https://example.invalid/api/yggdrasil/authserver/invalidate"
+    );
+}
+
+#[test]
+fn placeholders_require_a_profile() {
+    let without = AuthlibSession {
+        access_token: Secret::new("token"),
+        client_token: Secret::new("client"),
+        selected_profile: None,
+    };
+    assert!(!without.has_profile());
+    assert!(without.to_placeholders().is_err());
+
+    let with = AuthlibSession {
+        selected_profile: Some(AuthlibProfile {
+            id: "0123456789abcdef0123456789abcdef".to_string(),
+            name: "Steve".to_string(),
+        }),
+        ..without
+    };
+    assert!(with.has_profile());
+    let placeholders = with.to_placeholders().expect("占位符");
+    assert_eq!(placeholders.player_name, "Steve");
+    assert_eq!(placeholders.uuid, "0123456789abcdef0123456789abcdef");
+    assert_eq!(placeholders.user_type, USER_TYPE_MSA);
+    assert_eq!(placeholders.access_token, "token");
+}
+
+#[test]
+fn session_debug_never_leaks_tokens() {
+    let session = AuthlibSession {
+        access_token: Secret::new("access-token-value"),
+        client_token: Secret::new("client-token-value"),
+        selected_profile: None,
+    };
+    let debug = format!("{session:?}");
+    assert!(!debug.contains("access-token-value"));
+    assert!(!debug.contains("client-token-value"));
+    assert_eq!(session.secrets().len(), 2);
+}
+
+#[test]
+fn session_survives_json_roundtrip() {
+    let session = AuthlibSession {
+        access_token: Secret::new("access-token-value"),
+        client_token: Secret::new("client-token-value"),
+        selected_profile: Some(AuthlibProfile {
+            id: "0123456789abcdef0123456789abcdef".to_string(),
+            name: "Steve".to_string(),
+        }),
+    };
+    let text = serde_json::to_string(&session).expect("序列化");
+    let back: AuthlibSession = serde_json::from_str(&text).expect("反序列化");
+    assert_eq!(back, session);
+}
diff --git a/crates/core/src/auth/body/mod.rs b/crates/core/src/auth/body/mod.rs
new file mode 100644
index 0000000..91a1c53
--- /dev/null
+++ b/crates/core/src/auth/body/mod.rs
@@ -0,0 +1,279 @@
+//! 非 2xx 应答的**正文诊断**（M38）：把 M31「响应体一律丢掉」这个盲区补上。
+//!
+//! 起因是 `findings/20261030-tower-improve-login-with-xbox-403.md`：MSA 真机验收两轮都是
+//! OAuth→XBL→XSTS 全通、`login_with_xbox` 稳定 403，而旧 `rejected()` 只报状态码，
+//! 于是「区域/网络拦截页」和「服务端拒绝（许可/区域）」在文案上分不开。
+//!
+//! 这里只做三件事：
+//! 1. **分类**：JSON（真实服务应答）/ HTML 或纯文本（多为网关、风控或代理拦截页）/ 空体；
+//! 2. **提取**：JSON 里的 `error` / `errorMessage` / `reason` / `Message` 等服务端文案直出；
+//! 3. **摘要**：正文压成 ≤[`DIGEST_CHARS`] 字符，**先过 [`Redactor`] 再进错误消息**。
+//!
+//! 凭据红线（M31 的 `Secret`/脱敏体系不破）：
+//! - 摘要只从**非 2xx** 响应构造——OAuth 成功响应体（含 token）永远不会走到这里；
+//! - `Reply` 的原文快照只在 JSON 解析失败时保留（见 [`crate::auth::http`]），
+//!   解析成功的应答不留原文，避免把 token 文本复制进第二个字段；
+//! - 摘要与提取出的服务端文案都过同一套脱敏：[`Redactor::scrub`]（已登记 token 整串替换、
+//!   ≥64 不透明串打码、JWT 形状的带点 token 打码——第三条 M40 已上提到 `launch::redact`，
+//!   本模块不再自己补规则）。
+
+use serde_json::Value;
+
+use crate::auth::error::AuthError;
+use crate::auth::http::Reply;
+use crate::launch::redact::Redactor;
+
+#[cfg(test)]
+mod tests;
+
+/// 错误文案 / 事件里正文摘要的上限（字符）。
+pub const DIGEST_CHARS: usize = 200;
+
+/// 服务端文案的取值字段（按优先级，命中即收；`Message` 是 XSTS 的写法）。
+const SERVER_MESSAGE_KEYS: [&str; 6] = [
+    "errorMessage",
+    "error_message",
+    "error",
+    "errorType",
+    "reason",
+    "Message",
+];
+
+/// 一个非 2xx 应答的正文形状。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum BodyKind {
+    /// 合法 JSON（真实服务应答）。
+    Json,
+    /// HTML 页面（网关/风控/代理拦截页的典型形状）。
+    Html,
+    /// 其它非 JSON 文本。
+    Text,
+    /// 空体。
+    Empty,
+}
+
+impl BodyKind {
+    /// 稳定名（错误文案与 JSONL 事件共用）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Json => "json",
+            Self::Html => "html",
+            Self::Text => "text",
+            Self::Empty => "empty",
+        }
+    }
+
+    /// 是否是「拦截页」形状（HTML / 纯文本）：这一类先怀疑网络，而不是账号。
+    #[must_use]
+    pub const fn is_interception(self) -> bool {
+        matches!(self, Self::Html | Self::Text)
+    }
+}
+
+/// 一次非 2xx 的诊断结果（[`AuthError::Response`] 的载荷，也是 JSONL 事件的字段来源）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ResponseDetail {
+    /// 链上的步骤（`xbl` / `xsts` / `login_with_xbox` / `entitlements` / `profile`）。
+    pub step: String,
+    /// 这一步在做什么（人话前缀，如「Minecraft 登录被拒」）。
+    pub what: String,
+    /// HTTP 状态码。
+    pub status: u16,
+    /// `Content-Type`（服务端没给时为 `None`）。
+    pub content_type: Option<String>,
+    /// 正文形状。
+    pub kind: BodyKind,
+    /// 服务端文案（已脱敏、已截断）。
+    pub server_message: Option<String>,
+    /// 正文摘要（已脱敏，≤[`DIGEST_CHARS`] 字符）。
+    pub digest: String,
+}
+
+impl ResponseDetail {
+    /// 细分机读码（**只增不改**）：JSON 拒绝沿用 M31 的 `<step>_<status>`；
+    /// 非 JSON 用新增后缀 `<step>_non_json`；空体用 `<step>_empty_body`。
+    #[must_use]
+    pub fn detail_code(&self) -> String {
+        let suffix = match self.kind {
+            BodyKind::Json => self.status.to_string(),
+            BodyKind::Html | BodyKind::Text => "non_json".to_string(),
+            BodyKind::Empty => "empty_body".to_string(),
+        };
+        format!("{}_{suffix}", self.step)
+    }
+
+    /// 是否是「疑似网络拦截页」（HTML / 纯文本）。
+    #[must_use]
+    pub const fn is_interception(&self) -> bool {
+        self.kind.is_interception()
+    }
+
+    /// 「；服务端文案…；响应摘要…」片段（都没有时为空串，方便复用文案拼装）。
+    #[must_use]
+    pub fn note(&self) -> String {
+        let mut note = String::new();
+        if let Some(message) = &self.server_message {
+            note.push_str(&format!("；服务端文案「{message}」"));
+        }
+        if !self.digest.is_empty() {
+            note.push_str(&format!("；响应摘要：{}", self.digest));
+        }
+        note
+    }
+
+    /// 人读一句话（**不含凭据**），403 的两种分流在这里分开。
+    #[must_use]
+    pub fn message(&self) -> String {
+        let mut text = format!("{}（HTTP {}", self.what, self.status);
+        if let Some(content_type) = &self.content_type {
+            text.push_str(&format!("，Content-Type: {content_type}"));
+        }
+        text.push('）');
+        match self.kind {
+            BodyKind::Json => text.push_str("：服务端返回了 JSON 拒绝"),
+            BodyKind::Html | BodyKind::Text => {
+                text.push_str("：响应非 JSON（可能网络拦截/网关页）");
+            }
+            BodyKind::Empty => text.push_str("：响应体为空（可能网络拦截/网关页）"),
+        }
+        text.push('；');
+        text.push_str(advice(&self.step, self.kind));
+        text.push_str(&self.note());
+        text
+    }
+}
+
+/// 下一步该往哪查（403 分流的核心：拦截页查网络/代理，JSON 拒绝查账号许可）。
+#[must_use]
+pub fn advice(step: &str, kind: BodyKind) -> &'static str {
+    if kind.is_interception() {
+        return "请检查网络或代理（关掉/换掉代理后再试，必要时用镜像方案）";
+    }
+    match step {
+        "login_with_xbox" => "若网络正常，请检查该账号的 Minecraft 许可与所在区域",
+        "entitlements" => "若网络正常，请检查该账号是否拥有 Minecraft Java 版",
+        "profile" => "若网络正常，请去 minecraft.net 检查档案状态",
+        _ => "请按服务端文案处理；如反复失败，检查网络代理是否生效",
+    }
+}
+
+/// 分类一个非 2xx 应答。
+pub(crate) fn classify(reply: &Reply) -> BodyKind {
+    if reply.body.is_some() {
+        return BodyKind::Json;
+    }
+    let Some(raw) = reply
+        .raw
+        .as_deref()
+        .map(str::trim)
+        .filter(|raw| !raw.is_empty())
+    else {
+        return BodyKind::Empty;
+    };
+    let content_type = reply
+        .content_type
+        .as_deref()
+        .unwrap_or_default()
+        .to_ascii_lowercase();
+    if content_type.contains("html") || looks_like_html(raw) {
+        BodyKind::Html
+    } else {
+        BodyKind::Text
+    }
+}
+
+/// 正文是不是 HTML 文档（没给 `Content-Type` 时的兜底判断）。
+fn looks_like_html(raw: &str) -> bool {
+    raw.trim_start().starts_with('<')
+}
+
+/// 组装一条诊断（分类 + 服务端文案 + 摘要）。
+pub(crate) fn rejection(
+    step: &str,
+    reply: &Reply,
+    what: &str,
+    redactor: &Redactor,
+) -> ResponseDetail {
+    ResponseDetail {
+        step: step.to_string(),
+        what: what.to_string(),
+        status: reply.status,
+        content_type: reply.content_type.clone(),
+        kind: classify(reply),
+        server_message: server_message(reply, redactor),
+        digest: digest(reply, redactor),
+    }
+}
+
+/// 从 JSON 体里挑出服务端文案（去重后以 ` / ` 连接）。
+fn server_message(reply: &Reply, redactor: &Redactor) -> Option<String> {
+    let body = reply.body.as_ref()?;
+    let mut parts: Vec<String> = Vec::new();
+    for key in SERVER_MESSAGE_KEYS {
+        let Some(text) = body.get(key).and_then(Value::as_str) else {
+            continue;
+        };
+        let text = one_line(text);
+        if text.is_empty() || parts.iter().any(|part| part == &text) {
+            continue;
+        }
+        parts.push(text);
+    }
+    if parts.is_empty() {
+        return None;
+    }
+    Some(truncate(&scrub(&parts.join(" / "), redactor), DIGEST_CHARS))
+}
+
+/// 正文摘要：JSON 用紧凑文本，非 JSON 用原文快照；先脱敏再截断。
+fn digest(reply: &Reply, redactor: &Redactor) -> String {
+    let raw = match (&reply.body, &reply.raw) {
+        (Some(body), _) => body.to_string(),
+        (None, Some(raw)) => raw.to_string(),
+        (None, None) => return String::new(),
+    };
+    truncate(&scrub(&one_line(&raw), redactor), DIGEST_CHARS)
+}
+
+/// 走完整套脱敏：[`Redactor::scrub`] 的三条规则（已登记 token + ≥64 不透明串 + 带点 token）。
+///
+/// M40 之前这里自己补了一条「带点 token」规则：`Redactor` 只按「连续不透明串 ≥64」判形状，
+/// 而 JWT（`header.payload.signature`）里有点号，把连续段切短，恰好躲过那条规则——服务端
+/// 把 token 回显在错误体里时就会原样进摘要。现在规则已上提到 `launch::redact`（全局底座），
+/// 这里只调共用实现，两处规则不会再漂。
+fn scrub(text: &str, redactor: &Redactor) -> String {
+    redactor.scrub(text).into_owned()
+}
+
+/// 压成一行（HTML 的分行会让错误消息难以阅读）。
+fn one_line(text: &str) -> String {
+    let mut out = String::with_capacity(text.len());
+    let mut space = false;
+    for ch in text.chars() {
+        if ch.is_whitespace() {
+            space = !out.is_empty();
+            continue;
+        }
+        if std::mem::take(&mut space) {
+            out.push(' ');
+        }
+        out.push(ch);
+    }
+    out
+}
+
+/// 按字符截断（超长补 `…`）。
+fn truncate(text: &str, limit: usize) -> String {
+    if text.chars().count() <= limit {
+        return text.to_string();
+    }
+    let mut out: String = text.chars().take(limit.saturating_sub(1)).collect();
+    out.push('…');
+    out
+}
+
+/// 把诊断包成 [`AuthError::Response`]（链上各步骤的统一出口）。
+pub(crate) fn response(step: &str, reply: &Reply, what: &str, redactor: &Redactor) -> AuthError {
+    AuthError::Response(Box::new(rejection(step, reply, what, redactor)))
+}
diff --git a/crates/core/src/auth/body/tests.rs b/crates/core/src/auth/body/tests.rs
new file mode 100644
index 0000000..de5143c
--- /dev/null
+++ b/crates/core/src/auth/body/tests.rs
@@ -0,0 +1,168 @@
+//! [`super`] 的单测：分类、服务端文案提取、摘要脱敏与 403 分流文案。
+
+use super::{
+    advice, classify, digest, one_line, response, server_message, truncate, BodyKind, DIGEST_CHARS,
+};
+use crate::auth::error::AuthError;
+use crate::auth::http::Reply;
+use crate::auth::secret::{redactor_for, Secret};
+use crate::launch::redact::Redactor;
+use serde_json::json;
+
+const JWT: &str = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.c2lnbmF0dXJlLXZhbHVlLXRoYXQtaXMtbG9uZy1lbm91Z2g";
+
+fn json_reply(status: u16, body: serde_json::Value) -> Reply {
+    Reply {
+        status,
+        body: Some(body),
+        content_type: Some("application/json".to_string()),
+        raw: None,
+    }
+}
+
+fn text_reply(status: u16, content_type: Option<&str>, raw: &str) -> Reply {
+    Reply {
+        status,
+        body: None,
+        content_type: content_type.map(str::to_string),
+        raw: Some(raw.to_string()),
+    }
+}
+
+#[test]
+fn classification_splits_json_html_text_and_empty() {
+    assert_eq!(
+        classify(&json_reply(403, json!({ "error": "x" }))),
+        BodyKind::Json
+    );
+    assert_eq!(
+        classify(&text_reply(403, Some("text/html"), "<!DOCTYPE html>")),
+        BodyKind::Html
+    );
+    // 没给 Content-Type 时靠正文形状兜底。
+    assert_eq!(
+        classify(&text_reply(403, None, "<html><body>blocked")),
+        BodyKind::Html
+    );
+    assert_eq!(
+        classify(&text_reply(502, Some("text/plain"), "Bad Gateway")),
+        BodyKind::Text
+    );
+    assert_eq!(classify(&text_reply(403, None, "   ")), BodyKind::Empty);
+}
+
+#[test]
+fn server_message_prefers_error_fields_and_dedups() {
+    let redactor = Redactor::new();
+    let reply = json_reply(
+        403,
+        json!({ "error": "UNAUTHORIZED", "errorMessage": "no license", "path": "/x" }),
+    );
+    let message = server_message(&reply, &redactor).expect("应有服务端文案");
+    assert!(message.contains("no license"), "{message}");
+    assert!(message.contains("UNAUTHORIZED"), "{message}");
+
+    let same = json_reply(403, json!({ "error": "DENIED", "errorMessage": "DENIED" }));
+    assert_eq!(server_message(&same, &redactor).as_deref(), Some("DENIED"));
+    assert!(server_message(&json_reply(403, json!({ "path": "/x" })), &redactor).is_none());
+    assert!(server_message(&text_reply(500, None, "boom"), &redactor).is_none());
+}
+
+#[test]
+fn digest_is_redacted_and_capped() {
+    let token = Secret::new("mc-access-token-value");
+    let redactor = redactor_for([&token]);
+    let reply = json_reply(
+        403,
+        json!({ "error": "DENIED", "echo": format!("Bearer {}", token.expose()) }),
+    );
+    let masked_digest = digest(&reply, &redactor);
+    assert!(
+        !masked_digest.contains("mc-access-token-value"),
+        "{masked_digest}"
+    );
+
+    let long = "blocked ".repeat(60);
+    let capped = digest(&text_reply(500, Some("text/plain"), &long), &redactor);
+    assert!(capped.chars().count() <= DIGEST_CHARS);
+    assert!(capped.ends_with('…'));
+}
+
+#[test]
+fn opaque_runs_are_masked_even_without_known_secret() {
+    let masked = digest(&text_reply(401, Some("text/plain"), JWT), &Redactor::new());
+    assert!(!masked.contains("eyJhbGci"), "{masked}");
+    assert!(masked.contains("redacted"), "{masked}");
+}
+
+#[test]
+fn dotted_tokens_are_masked_by_the_shared_redactor() {
+    // 规则本体在 `launch::redact`（M40 上提），这里只验「auth 摘要走的是同一份实现」。
+    let redactor = Redactor::new();
+    assert!(!redactor.scrub(JWT).contains("eyJhbGci"), "JWT 应被打码");
+    // 普通文案里的点不会触发（分段太短）。
+    assert_eq!(
+        redactor.scrub("Service.Unavailable.today"),
+        "Service.Unavailable.today"
+    );
+    let masked = redactor.scrub(&format!("token={JWT}&end")).into_owned();
+    assert!(!masked.contains("eyJhbGci"), "{masked}");
+    assert!(masked.ends_with("&end"), "{masked}");
+}
+
+#[test]
+fn one_line_collapses_whitespace() {
+    assert_eq!(one_line("  a\n\n b\tc  "), "a b c");
+    assert_eq!(truncate("abcdef", 4), "abc…");
+    assert_eq!(truncate("abc", 4), "abc");
+}
+
+#[test]
+fn detail_codes_and_advice_split_network_from_license() {
+    let redactor = Redactor::new();
+    let blocked = response(
+        "login_with_xbox",
+        &text_reply(403, Some("text/html"), "<html>blocked</html>"),
+        "Minecraft 登录被拒",
+        &redactor,
+    );
+    let AuthError::Response(detail) = &blocked else {
+        panic!("应是 Response，实际 {blocked:?}");
+    };
+    assert_eq!(detail.detail_code(), "login_with_xbox_non_json");
+    assert!(
+        detail.message().contains("网络拦截"),
+        "{}",
+        detail.message()
+    );
+    assert!(detail.message().contains("代理"), "{}", detail.message());
+
+    let denied = response(
+        "login_with_xbox",
+        &json_reply(
+            403,
+            json!({ "error": "UNAUTHORIZED", "errorMessage": "nope" }),
+        ),
+        "Minecraft 登录被拒",
+        &redactor,
+    );
+    let AuthError::Response(detail) = &denied else {
+        panic!("应是 Response，实际 {denied:?}");
+    };
+    assert_eq!(detail.detail_code(), "login_with_xbox_403");
+    assert!(detail.message().contains("许可"), "{}", detail.message());
+    assert!(!detail.message().contains("代理"), "{}", detail.message());
+
+    let empty = response(
+        "profile",
+        &text_reply(500, None, ""),
+        "拉取档案被拒",
+        &redactor,
+    );
+    let AuthError::Response(detail) = &empty else {
+        panic!("应是 Response，实际 {empty:?}");
+    };
+    assert_eq!(detail.detail_code(), "profile_empty_body");
+    assert!(!advice("xbl", BodyKind::Html).is_empty());
+    assert!(!advice("xbl", BodyKind::Json).is_empty());
+}
diff --git a/crates/core/src/auth/error.rs b/crates/core/src/auth/error.rs
new file mode 100644
index 0000000..cad3632
--- /dev/null
+++ b/crates/core/src/auth/error.rs
@@ -0,0 +1,256 @@
+//! 认证错误：把 HMCL 的异常树压成「调用方能分流」的一层（`analyse/04` §2.6 / §4.5）。
+//!
+//! 三条设计：
+//! 1. **`CredentialExpired` 是唯一「要人再登录」的信号**（承 HMCL `CredentialExpiredException`），
+//!    其余错误都不该弹交互；
+//! 2. **取消 / 超时 / 被拒 三分**（mission 明示的错误分流）：用户关窗口 = `Canceled`，
+//!    设备码 15 分钟硬超时 = `Timeout`，`access_denied` = `Denied`；
+//! 3. **文案里永不含凭据**：错误只描述发生了什么，token 一律不进 message。
+
+use std::fmt;
+
+use crate::auth::body::ResponseDetail;
+
+/// Xbox Live 错误码：账号被封（`MicrosoftService.BANNED`）。
+pub const XERR_BANNED: u32 = 2_148_916_227;
+/// 没有 Xbox 账号（需先建档案）。
+pub const XERR_MISSING_XBOX_ACCOUNT: u32 = 2_148_916_233;
+/// 地区不可用。
+pub const XERR_COUNTRY_UNAVAILABLE: u32 = 2_148_916_235;
+/// 儿童账号未加入家庭组。
+pub const XERR_ADD_FAMILY: u32 = 2_148_916_238;
+
+/// 认证失败。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum AuthError {
+    /// 网络层失败（DNS/连接/TLS/超时以外的 IO）。
+    Network {
+        /// 目标 URL（不含 query 里的凭据）。
+        url: String,
+        /// 底层描述。
+        detail: String,
+    },
+    /// 超时：连接超时、整体超时，或设备码流程等满 `expires_in`/15 分钟。
+    Timeout {
+        /// 在等什么。
+        what: String,
+    },
+    /// 用户主动取消（关窗口、Ctrl+C、`access_denied` 也归这里）。
+    Canceled,
+    /// 凭据过期/被撤销，必须重新交互式登录（`AADSTS70000` 族）。
+    CredentialExpired,
+    /// 服务端明确拒绝（OAuth `error` + `error_description`）。
+    Denied {
+        /// OAuth 错误码（`invalid_grant` / `authorization_declined` …）。
+        code: String,
+        /// 服务端描述。
+        description: String,
+    },
+    /// 链上某一步拿到非 2xx，且带回了正文诊断（M38）。
+    ///
+    /// 与 [`Self::Denied`] 同一分流层（`code()` 仍是 `denied`，向后兼容 M31 的调用方），
+    /// 细分码看 [`AuthError::detail_code`]：JSON 拒绝沿用 `<step>_<status>`，
+    /// 拦截页（HTML/纯文本）是新增的 `<step>_non_json`，空体是 `<step>_empty_body`。
+    ///
+    /// 载荷装箱：`ResponseDetail` 有 7 个字段（含 4 个字符串），不装箱会把整个枚举撑到
+    /// 128 字节以上，`Result<T, AuthError>` 的每个 Ok 也跟着变胖（clippy `result_large_err`）。
+    Response(Box<ResponseDetail>),
+    /// Xbox Live / XSTS 业务错误码（`XErr`）。
+    Xbox {
+        /// `XErr` 数值。
+        code: u32,
+    },
+    /// 响应结构不合法（JSON 缺字段、类型不对、profile 被换掉）。
+    Malformed(String),
+    /// 凭据/元数据落盘或读取失败。
+    Store {
+        /// 涉及的路径。
+        path: String,
+        /// 底层描述。
+        detail: String,
+    },
+    /// 找不到指定账户。
+    NotFound {
+        /// 用户给的查找键。
+        account: String,
+    },
+    /// 账户重复（同名同轨已存在）。
+    Conflict {
+        /// 冲突的账户名。
+        account: String,
+    },
+    /// 该轨/该能力当前不可用：**未配置**（如缺 Azure client id）或本期未实现
+    /// （如 CLI 上的 authlib 密码登录）。
+    ///
+    /// 载荷必须**自带完整的人读句子**（「未配置 + 怎么配」/「未实现 + 为什么」），
+    /// 本层不再统一拼「本期未支持：」这类前缀——同一层里两种情况完全不同的事，
+    /// 硬拼一个前缀会让「没配置」被读成「没实现」（M117 用户实跑踩到）。
+    /// 机读码仍是 `unsupported`（[`Self::code`]），调用方分流不受影响。
+    Unsupported(String),
+}
+
+impl AuthError {
+    /// 稳定机读码（CLI `--json` 与日志都用它，不随文案变）。
+    #[must_use]
+    pub const fn code(&self) -> &'static str {
+        match self {
+            Self::Network { .. } => "network",
+            Self::Timeout { .. } => "timeout",
+            Self::Canceled => "canceled",
+            Self::CredentialExpired => "credential_expired",
+            Self::Denied { .. } => "denied",
+            // 与 `Denied` 同一粗分流层：M31 时代的调用方（CLI 提示、launch 身份解析）无需改。
+            Self::Response(_) => "denied",
+            Self::Xbox { .. } => "xbox",
+            Self::Malformed(_) => "malformed",
+            Self::Store { .. } => "store",
+            Self::NotFound { .. } => "not_found",
+            Self::Conflict { .. } => "conflict",
+            Self::Unsupported(_) => "unsupported",
+        }
+    }
+
+    /// 是否是「必须重新登录」的信号（唯一该弹交互的一类）。
+    #[must_use]
+    pub const fn is_credential_expired(&self) -> bool {
+        matches!(self, Self::CredentialExpired)
+    }
+
+    /// 是否属于「网络/服务端抽风，可重试或跳过」的一类。
+    #[must_use]
+    pub const fn is_transient(&self) -> bool {
+        match self {
+            Self::Network { .. } | Self::Timeout { .. } | Self::Xbox { .. } => true,
+            // 拦截页/空体多半是网络侧问题；JSON 拒绝是服务端明确表态，重试无意义。
+            Self::Response(detail) => detail.kind.is_interception(),
+            _ => false,
+        }
+    }
+
+    /// 细分机读码（M38 新增）：OAuth 拒绝返回 `<step>` 里带的错误码，链上非 2xx 返回
+    /// `<step>_<status>` / `<step>_non_json` / `<step>_empty_body`，其余回落到 [`Self::code`]。
+    ///
+    /// 与 [`Self::code`] 的分工：`code()` 是**分流层**（决定弹不弹交互、能不能重试），
+    /// 这个方法给日志与 `--json` 的**排障层**用。既有码一律不改，只增。
+    #[must_use]
+    pub fn detail_code(&self) -> String {
+        match self {
+            Self::Response(detail) => detail.detail_code(),
+            Self::Denied { code, .. } => code.clone(),
+            other => other.code().to_string(),
+        }
+    }
+
+    /// 网络错误的构造（`url` 只放 host+path，别把 query 里的 code 带进来）。
+    #[must_use]
+    pub fn network(url: impl Into<String>, detail: impl Into<String>) -> Self {
+        Self::Network {
+            url: url.into(),
+            detail: detail.into(),
+        }
+    }
+
+    /// 落盘错误的构造。
+    #[must_use]
+    pub fn store(path: impl fmt::Display, detail: impl Into<String>) -> Self {
+        Self::Store {
+            path: path.to_string(),
+            detail: detail.into(),
+        }
+    }
+
+    /// 人读一句话（**不含凭据**）。
+    #[must_use]
+    pub fn message(&self) -> String {
+        match self {
+            Self::Network { url, detail } => format!("网络请求失败（{url}）：{detail}"),
+            Self::Timeout { what } => format!("等待超时：{what}"),
+            Self::Canceled => "登录已取消".to_string(),
+            Self::CredentialExpired => "凭据已过期，需要重新登录".to_string(),
+            Self::Denied { code, description } => {
+                format!("服务端拒绝（{code}）：{description}")
+            }
+            Self::Response(detail) => detail.message(),
+            Self::Xbox { code } => format!("Xbox 授权失败（XErr {code}）：{}", xbox_hint(*code)),
+            Self::Malformed(detail) => format!("响应不符合预期：{detail}"),
+            Self::Store { path, detail } => format!("账户数据读写失败（{path}）：{detail}"),
+            Self::NotFound { account } => format!("找不到账户 `{account}`"),
+            Self::Conflict { account } => format!("账户 `{account}` 已存在"),
+            Self::Unsupported(detail) => detail.clone(),
+        }
+    }
+}
+
+impl fmt::Display for AuthError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str(&self.message())
+    }
+}
+
+impl std::error::Error for AuthError {}
+
+/// `XErr` 码 → 中文说明（承 `analyse/04` §5.2 的四码表）。
+#[must_use]
+pub fn xbox_hint(code: u32) -> &'static str {
+    match code {
+        XERR_BANNED => "该微软账号已被 Xbox Live 封禁",
+        XERR_MISSING_XBOX_ACCOUNT => "该微软账号还没有 Xbox 档案，请先去 xbox.com 创建",
+        XERR_COUNTRY_UNAVAILABLE => "该账号所在地区不被 Xbox Live 支持",
+        XERR_ADD_FAMILY => "儿童账号需要先加入 Microsoft 家庭组",
+        _ => "Xbox Live 拒绝了本次授权（可能无 Xbox 档案或账号受限）",
+    }
+}
+
+/// 结果别名。
+pub type AuthResult<T> = Result<T, AuthError>;
+
+#[cfg(test)]
+mod tests {
+    use super::{xbox_hint, AuthError, XERR_ADD_FAMILY};
+
+    #[test]
+    fn codes_are_stable() {
+        assert_eq!(AuthError::Canceled.code(), "canceled");
+        assert_eq!(AuthError::CredentialExpired.code(), "credential_expired");
+        assert!(AuthError::Xbox {
+            code: XERR_ADD_FAMILY
+        }
+        .is_transient());
+        assert!(!AuthError::Canceled.is_transient());
+    }
+
+    #[test]
+    fn messages_carry_no_secret_shape() {
+        let error = AuthError::Denied {
+            code: "invalid_grant".to_string(),
+            description: "AADSTS70000: bad redirect".to_string(),
+        };
+        assert!(error.message().contains("AADSTS70000"));
+        assert!(AuthError::Xbox { code: 2148916238 }
+            .message()
+            .contains("家庭组"));
+        assert!(!xbox_hint(0).is_empty());
+    }
+
+    #[test]
+    fn response_shares_denied_coarse_code_but_has_its_own_detail_code() {
+        let error = AuthError::Response(Box::new(super::ResponseDetail {
+            step: "login_with_xbox".to_string(),
+            what: "Minecraft 登录被拒".to_string(),
+            status: 403,
+            content_type: Some("text/html".to_string()),
+            kind: crate::auth::body::BodyKind::Html,
+            server_message: None,
+            digest: String::new(),
+        }));
+        // 粗分流层向后兼容：仍是 `denied`；排障层才是细分码。
+        assert_eq!(error.code(), "denied");
+        assert_eq!(error.detail_code(), "login_with_xbox_non_json");
+        assert!(error.is_transient(), "拦截页可以重试");
+        assert_eq!(
+            AuthError::Canceled.detail_code(),
+            "canceled",
+            "没有细分的错误回落到 code()"
+        );
+    }
+}
diff --git a/crates/core/src/auth/http.rs b/crates/core/src/auth/http.rs
new file mode 100644
index 0000000..ad42508
--- /dev/null
+++ b/crates/core/src/auth/http.rs
@@ -0,0 +1,208 @@
+//! 认证用的 HTTP 薄封装（三条轨共用）：**复用既有 download 引擎的客户端基座**
+//! （mission Context：网络操作走既有 HTTP 基座），只补三件认证需要的东西：
+//! 表单/JSON 体、Bearer 头、单请求整体超时。
+//!
+//! 三条纪律：
+//! 1. **响应体不原样进错误文案**——OAuth 的 token 响应体本身就是凭据，把它塞进
+//!    `Malformed` 的 message 就等于把 token 写进日志（`analyse/04` §11 观察项 9 的坑）；
+//!    因此解析失败只说「不是合法 JSON」，贴原文的唯一通道是
+//!    [`crate::auth::body`] 的脱敏摘要（M38：仅非 2xx、≤200 字符、过 Redactor）。
+//! 2. 状态码不做归类，**原样交给调用方**：XSTS 的 401 带 `XErr`、`/minecraft/profile` 的
+//!    404 要复判 license，都是「非 200 但有语义」的分支，提前归一化会丢掉信息。
+//! 3. **诊断留证，但不留凭据**（M38）：`Reply` 额外携带 `Content-Type` 与非 JSON 正文的快照
+//!    （[`RAW_PREVIEW_BYTES`] 字节封顶），诊断由 [`crate::auth::body`] 分类/脱敏后再进错误消息。
+//!    原文快照**只在 JSON 解析失败时**保留，所以 OAuth 成功响应体不会被复制进第二个字段。
+
+use std::time::Duration;
+
+use reqwest::header::{ACCEPT, AUTHORIZATION, CONTENT_TYPE};
+use reqwest::Client;
+use serde_json::Value;
+
+use crate::auth::error::{AuthError, AuthResult};
+use crate::auth::secret::Secret;
+
+/// 单请求整体超时（设备码轮询的每个请求都远快于此）。
+pub(crate) const REQUEST_TIMEOUT: Duration = Duration::from_secs(30);
+
+/// 非 JSON 正文保留的快照上限（字节）：够判断「是不是 HTML」并抓前几句文案。
+pub(crate) const RAW_PREVIEW_BYTES: usize = 512;
+
+/// 一次应答：状态码 + 可解析的 JSON 体 + 诊断用的头/正文快照。
+#[derive(Debug, Clone)]
+pub(crate) struct Reply {
+    /// HTTP 状态码。
+    pub status: u16,
+    /// 解析成功时的 JSON 体（空体/非 JSON 为 `None`）。
+    pub body: Option<Value>,
+    /// `Content-Type` 原样（诊断文案与分流判断用；缺失为 `None`）。
+    pub content_type: Option<String>,
+    /// 非 JSON 正文的前 [`RAW_PREVIEW_BYTES`] 字节（有损 UTF-8；JSON 解析成功时为 `None`）。
+    pub raw: Option<String>,
+}
+
+impl Reply {
+    /// 是否 2xx。
+    pub(crate) fn is_success(&self) -> bool {
+        (200..300).contains(&self.status)
+    }
+
+    /// 取一个字符串字段。
+    pub(crate) fn text(&self, path: &str) -> Option<&str> {
+        self.body.as_ref()?.get(path)?.as_str()
+    }
+
+    /// 取一个 u64 字段（数字或数字字符串都接受）。
+    pub(crate) fn number(&self, path: &str) -> Option<u64> {
+        let value = self.body.as_ref()?.get(path)?;
+        value
+            .as_u64()
+            .or_else(|| value.as_str().and_then(|raw| raw.trim().parse().ok()))
+    }
+}
+
+/// 表单 `POST`（OAuth 的设备码/token 端点）。
+pub(crate) async fn post_form(
+    client: &Client,
+    url: &str,
+    form: Vec<(&str, String)>,
+) -> AuthResult<Reply> {
+    let request = client
+        .post(url)
+        .header(ACCEPT, "application/json")
+        .timeout(REQUEST_TIMEOUT)
+        .form(&form);
+    send(request, url).await
+}
+
+/// JSON `POST`（XBL / XSTS / login_with_xbox）。
+pub(crate) async fn post_json(
+    client: &Client,
+    url: &str,
+    body: &Value,
+    bearer: Option<&Secret>,
+) -> AuthResult<Reply> {
+    let text = serde_json::to_string(body)
+        .map_err(|error| AuthError::Malformed(format!("请求体序列化失败：{error}")))?;
+    let mut request = client
+        .post(url)
+        .header(CONTENT_TYPE, "application/json")
+        .header(ACCEPT, "application/json")
+        .timeout(REQUEST_TIMEOUT)
+        .body(text);
+    if let Some(token) = bearer {
+        request = request.header(AUTHORIZATION, format!("Bearer {}", token.expose()));
+    }
+    send(request, url).await
+}
+
+/// 带 Bearer 的 `GET`（entitlements / profile）。
+pub(crate) async fn get_json(client: &Client, url: &str, bearer: &Secret) -> AuthResult<Reply> {
+    let request = client
+        .get(url)
+        .header(ACCEPT, "application/json")
+        .header(AUTHORIZATION, format!("Bearer {}", bearer.expose()))
+        .timeout(REQUEST_TIMEOUT);
+    send(request, url).await
+}
+
+/// 发请求并解析 JSON（无凭据泄漏的错误映射）。
+async fn send(request: reqwest::RequestBuilder, url: &str) -> AuthResult<Reply> {
+    let response = request
+        .send()
+        .await
+        .map_err(|error| http_error(url, &error))?;
+    let status = response.status().as_u16();
+    let content_type = response
+        .headers()
+        .get(CONTENT_TYPE)
+        .and_then(|value| value.to_str().ok())
+        .map(str::to_string);
+    let bytes = response
+        .bytes()
+        .await
+        .map_err(|error| http_error(url, &error))?;
+    let body = if bytes.is_empty() {
+        None
+    } else {
+        serde_json::from_slice::<Value>(&bytes).ok()
+    };
+    // 只有解析失败（HTML 拦截页 / 纯文本 / 坏 JSON）才留原文快照：
+    // 解析成功的响应体可能含 token，不留第二份副本。
+    let raw = match (&body, bytes.is_empty()) {
+        (None, false) => Some(preview(&bytes)),
+        _ => None,
+    };
+    Ok(Reply {
+        status,
+        body,
+        content_type,
+        raw,
+    })
+}
+
+/// 取正文前 [`RAW_PREVIEW_BYTES`] 字节（有损解码，截断时补 `…`）。
+fn preview(bytes: &[u8]) -> String {
+    let truncated = bytes.len() > RAW_PREVIEW_BYTES;
+    let head = &bytes[..bytes.len().min(RAW_PREVIEW_BYTES)];
+    let mut text = String::from_utf8_lossy(head).into_owned();
+    if truncated {
+        text.push('…');
+    }
+    text
+}
+
+/// `reqwest::Error` → [`AuthError`]（超时与非超时分开，文案只带 host+path）。
+fn http_error(url: &str, error: &reqwest::Error) -> AuthError {
+    let target = url.split('?').next().unwrap_or(url).to_string();
+    if error.is_timeout() {
+        AuthError::Timeout {
+            what: format!("请求 {target}"),
+        }
+    } else {
+        AuthError::network(target, error.to_string())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{preview, Reply, RAW_PREVIEW_BYTES};
+    use serde_json::json;
+
+    fn reply(status: u16, body: Option<serde_json::Value>) -> Reply {
+        Reply {
+            status,
+            body,
+            content_type: Some("application/json".to_string()),
+            raw: None,
+        }
+    }
+
+    #[test]
+    fn reply_reads_text_and_numbers() {
+        let sample = reply(
+            200,
+            Some(json!({ "user_code": "ABC", "expires_in": 900, "interval": "5" })),
+        );
+        assert!(sample.is_success());
+        assert_eq!(sample.text("user_code"), Some("ABC"));
+        assert_eq!(sample.number("expires_in"), Some(900));
+        assert_eq!(sample.number("interval"), Some(5));
+        assert_eq!(sample.number("missing"), None);
+        assert_eq!(sample.text("missing"), None);
+    }
+
+    #[test]
+    fn non_success_is_not_success() {
+        assert!(!reply(401, None).is_success());
+    }
+
+    #[test]
+    fn preview_caps_and_marks_truncation() {
+        let short = preview(b"Bad Gateway");
+        assert_eq!(short, "Bad Gateway");
+        let long = preview(&vec![b'x'; RAW_PREVIEW_BYTES + 64]);
+        assert!(long.ends_with('…'));
+        assert_eq!(long.trim_end_matches('…').len(), RAW_PREVIEW_BYTES);
+    }
+}
diff --git a/crates/core/src/auth/journal.rs b/crates/core/src/auth/journal.rs
new file mode 100644
index 0000000..6c54c67
--- /dev/null
+++ b/crates/core/src/auth/journal.rs
@@ -0,0 +1,266 @@
+//! auth 失败事件的落盘（`.ULL/logs/auth.jsonl`，M38）。
+//!
+//! 起因：MSA 真机验收两轮 403，`ull accounts add msa` 失败后终端只有一行文案，
+//! 验收人拿不到状态码/正文摘要去对账。这里把**失败**写成一行一条 JSONL：
+//! 便携模式数据根还没初始化时会先补建 `logs/` 分区，403 的细节不再随终端滚走。
+//!
+//! 三条纪律：
+//! 1. **只记失败**，不记成功（成功路径的凭据载荷一律不落日志）；
+//! 2. **记的是诊断字段**（`code` / `detail_code` / `status` / `content_type` / `body_kind` /
+//!    已脱敏的 `server_message`、`digest`），没有任何 token/密码字段；
+//! 3. **落盘是尽力而为**：写日志失败绝不让登录本身失败（调用方忽略返回值）。
+//!
+//! 数据根从哪来：默认走 `platform::data_dir` 的 **Portable** 解析（exe 同目录的 `.ULL`，
+//! 跟随 `redirect.json`）。宿主若用 `--data-dir` 等非便携模式，应显式
+//! [`AuthJournal::in_logs_dir`] 后交给 [`crate::auth::MicrosoftAuth::with_journal`]。
+
+use std::io::Write;
+use std::path::{Path, PathBuf};
+
+use serde_json::{json, Value};
+
+use crate::auth::body::BodyKind;
+use crate::auth::error::AuthError;
+use crate::launch::redact::Redactor;
+use crate::platform::data_dir::{DataDirRequest, Resolver};
+use crate::platform::layout::LauncherLayout;
+use crate::platform::paths::Platform;
+
+/// 认证失败事件文件名（在 `.ULL/logs/` 下）。
+pub const AUTH_LOG_FILE: &str = "auth.jsonl";
+
+/// 一行认证失败事件。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AuthFailureEvent {
+    /// Unix 毫秒。
+    pub ts_ms: u64,
+    /// 触发入口（`device_code_login` / `refresh` / `validate`）。
+    pub scope: String,
+    /// 链上的步骤（`AuthError::Response` 才有）。
+    pub step: Option<String>,
+    /// 粗分流码（[`AuthError::code`]）。
+    pub code: String,
+    /// 细分码（[`AuthError::detail_code`]）。
+    pub detail_code: String,
+    /// HTTP 状态码（链上拒绝才有）。
+    pub status: Option<u16>,
+    /// `Content-Type`（链上拒绝才有）。
+    pub content_type: Option<String>,
+    /// 正文形状（链上拒绝才有）。
+    pub body_kind: Option<BodyKind>,
+    /// 服务端文案（已脱敏）。
+    pub server_message: Option<String>,
+    /// 正文摘要（已脱敏，≤200 字符）。
+    pub digest: Option<String>,
+    /// 是否可重试（[`AuthError::is_transient`]）。
+    pub transient: bool,
+    /// 人读一句话（已脱敏，不含凭据）。
+    pub message: String,
+}
+
+impl AuthFailureEvent {
+    /// 从一条错误构造（`scope` 说明是哪个入口失败的）。
+    #[must_use]
+    pub fn of(scope: &str, error: &AuthError) -> Self {
+        let detail = match error {
+            AuthError::Response(detail) => Some(detail.as_ref()),
+            _ => None,
+        };
+        let scrub = |text: &str| Redactor::new().scrub(text).into_owned();
+        Self {
+            ts_ms: crate::auth::microsoft::now_ms(),
+            scope: scope.to_string(),
+            step: detail.map(|detail| detail.step.clone()),
+            code: error.code().to_string(),
+            detail_code: error.detail_code(),
+            status: detail.map(|detail| detail.status),
+            content_type: detail.and_then(|detail| detail.content_type.clone()),
+            body_kind: detail.map(|detail| detail.kind),
+            server_message: detail
+                .and_then(|detail| detail.server_message.as_deref())
+                .map(scrub),
+            digest: detail.map(|detail| scrub(&detail.digest)),
+            transient: error.is_transient(),
+            message: scrub(&error.message()),
+        }
+    }
+
+    /// JSON 形状（字段名稳定，给验收/排障工具读）。
+    #[must_use]
+    pub fn to_json(&self) -> Value {
+        json!({
+            "ts_ms": self.ts_ms,
+            "level": "error",
+            "event": "auth_failure",
+            "scope": self.scope,
+            "step": self.step,
+            "code": self.code,
+            "detail_code": self.detail_code,
+            "status": self.status,
+            "content_type": self.content_type,
+            "body_kind": self.body_kind.map(BodyKind::as_str),
+            "server_message": self.server_message,
+            "digest": self.digest,
+            "transient": self.transient,
+            "message": self.message,
+        })
+    }
+}
+
+/// 认证失败日志（JSONL，一行一条）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AuthJournal {
+    path: PathBuf,
+}
+
+impl AuthJournal {
+    /// 落在某个 `logs/` 分区下（`<logs>/auth.jsonl`）。
+    #[must_use]
+    pub fn in_logs_dir(logs: impl Into<PathBuf>) -> Self {
+        Self {
+            path: logs.into().join(AUTH_LOG_FILE),
+        }
+    }
+
+    /// 直接指定文件路径。
+    #[must_use]
+    pub fn at(path: impl Into<PathBuf>) -> Self {
+        Self { path: path.into() }
+    }
+
+    /// 便携模式默认位置（exe 同目录 `.ULL/logs/auth.jsonl`，跟随 `redirect.json`）。
+    ///
+    /// 拿不到 exe 目录（极少数嵌入场景）时返回 `None`——没有可写的日志根就不写。
+    #[must_use]
+    pub fn portable_default() -> Option<Self> {
+        let exe_dir = std::env::current_exe()
+            .ok()
+            .and_then(|path| path.parent().map(Path::to_path_buf))?;
+        let resolver = Resolver::new(Platform::current(), Some(exe_dir));
+        let resolved = resolver.resolve_default(&DataDirRequest::default()).ok()?;
+        Some(Self::in_logs_dir(
+            LauncherLayout::new(resolved.launcher_home).logs(),
+        ))
+    }
+
+    /// 日志文件路径。
+    #[must_use]
+    pub fn path(&self) -> &Path {
+        &self.path
+    }
+
+    /// 追加一条事件（父目录不存在时先建）。
+    ///
+    /// # Errors
+    ///
+    /// 建目录或追加失败；调用方按「尽力而为」处理即可。
+    pub fn record(&self, event: &AuthFailureEvent) -> std::io::Result<()> {
+        if let Some(parent) = self.path.parent() {
+            std::fs::create_dir_all(parent)?;
+        }
+        let mut line = serde_json::to_string(&event.to_json()).unwrap_or_default();
+        line.push('\n');
+        let mut file = std::fs::OpenOptions::new()
+            .create(true)
+            .append(true)
+            .open(&self.path)?;
+        file.write_all(line.as_bytes())?;
+        file.flush()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{AuthFailureEvent, AuthJournal};
+    use crate::auth::body::{BodyKind, ResponseDetail};
+    use crate::auth::error::AuthError;
+
+    fn temp_dir(tag: &str) -> std::path::PathBuf {
+        let dir = std::env::temp_dir().join(format!(
+            "ull-auth-journal-{tag}-{}-{:?}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .map(|since| since.as_nanos())
+                .unwrap_or(0)
+        ));
+        let _ = std::fs::remove_dir_all(&dir);
+        std::fs::create_dir_all(&dir).expect("建临时目录");
+        dir
+    }
+
+    fn blocked_error() -> AuthError {
+        AuthError::Response(Box::new(ResponseDetail {
+            step: "login_with_xbox".to_string(),
+            what: "Minecraft 登录被拒".to_string(),
+            status: 403,
+            content_type: Some("text/html".to_string()),
+            kind: BodyKind::Html,
+            server_message: None,
+            digest: "<html>blocked</html>".to_string(),
+        }))
+    }
+
+    #[test]
+    fn event_carries_structured_diagnostics() {
+        let event = AuthFailureEvent::of("device_code_login", &blocked_error());
+        assert_eq!(event.scope, "device_code_login");
+        assert_eq!(event.step.as_deref(), Some("login_with_xbox"));
+        assert_eq!(event.code, "denied");
+        assert_eq!(event.detail_code, "login_with_xbox_non_json");
+        assert_eq!(event.status, Some(403));
+        assert_eq!(event.content_type.as_deref(), Some("text/html"));
+        assert_eq!(event.body_kind, Some(BodyKind::Html));
+        assert!(event.transient);
+        let value = event.to_json();
+        assert_eq!(value["event"], "auth_failure");
+        assert_eq!(value["level"], "error");
+        assert_eq!(value["body_kind"], "html");
+        assert!(value["message"]
+            .as_str()
+            .is_some_and(|text| !text.is_empty()));
+    }
+
+    #[test]
+    fn non_chain_errors_still_record() {
+        let event = AuthFailureEvent::of("refresh", &AuthError::Canceled);
+        assert_eq!(event.detail_code, "canceled");
+        assert_eq!(event.step, None);
+        assert_eq!(event.status, None);
+        assert!(!event.transient);
+    }
+
+    #[test]
+    fn record_initializes_the_logs_dir_and_appends_one_line() {
+        let root = temp_dir("init");
+        let logs = root.join("logs");
+        let journal = AuthJournal::in_logs_dir(&logs);
+        assert!(!logs.exists(), "初始不该存在（模拟未初始化的数据根）");
+        journal
+            .record(&AuthFailureEvent::of("device_code_login", &blocked_error()))
+            .expect("写日志");
+        journal
+            .record(&AuthFailureEvent::of("refresh", &AuthError::Canceled))
+            .expect("写日志");
+        let text = std::fs::read_to_string(journal.path()).expect("读日志");
+        let lines: Vec<&str> = text.lines().collect();
+        assert_eq!(lines.len(), 2, "一行一条：{text}");
+        for line in lines {
+            let value: serde_json::Value = serde_json::from_str(line).expect("每行都是合法 JSON");
+            assert_eq!(value["event"], "auth_failure");
+        }
+        // 日志里不该出现任何凭据字段名。
+        for forbidden in ["access_token", "refresh_token", "password", "token"] {
+            assert!(!text.contains(forbidden), "日志出现了 {forbidden}：{text}");
+        }
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn journal_paths_are_layout_based() {
+        let journal = AuthJournal::in_logs_dir("/tmp/ull-logs");
+        assert!(journal.path().ends_with("auth.jsonl"));
+        let explicit = AuthJournal::at("/tmp/x/custom.jsonl");
+        assert_eq!(explicit.path(), std::path::Path::new("/tmp/x/custom.jsonl"));
+    }
+}
diff --git a/crates/core/src/auth/microsoft/authcode.rs b/crates/core/src/auth/microsoft/authcode.rs
new file mode 100644
index 0000000..6757829
--- /dev/null
+++ b/crates/core/src/auth/microsoft/authcode.rs
@@ -0,0 +1,284 @@
+//! 授权码流（`research/08` §3 方案 A）：授权 URL 构造 + code 换 token + 整链编排。
+//!
+//! 与设备码流的分工：**只多一跳**——拿 MS access_token 的方式不同，往后的
+//! XBL → XSTS → login_with_xbox → entitlements → profile 与刷新链完全复用
+//! （[`super::chain::complete_chain`]），所以两条流的凭据存储与刷新语义天然一致。
+//!
+//! # 三个硬性细节（都是「抄错就失败」的那一类）
+//!
+//! 1. **租户 `consumers`**：授权页与 token 端点都走 `login.microsoftonline.com/consumers/…`，
+//!    换成 `common`/AAD 租户 id 时 `XboxLive.signin` 直接被拒（`research/08` §2 约束 1）。
+//! 2. **重定向 URI 严格一致**：`http://localhost:{port}/auth` —— 授权 URL 里的、
+//!    token 请求体里的、本地服务器实际监听的必须是**同一个字符串**（含端口与路径），
+//!    所以本模块只从 [`RedirectUri`] 取这一个来源。
+//! 3. **`prompt=select_account`**：不带这个参数，用户会被静默塞进上一次的账号（坑 6）。
+//!
+//! scope 与设备码流共用 [`super::flow::SCOPE`]（`XboxLive.signin offline_access`）。
+
+use std::fmt;
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
+
+use reqwest::Client;
+
+use crate::auth::error::AuthResult;
+use crate::auth::http::post_form;
+use crate::auth::secret::Secret;
+
+use super::callback::{CallbackServer, REDIRECT_PATH};
+use super::chain::complete_chain;
+use super::endpoints::MicrosoftEndpoints;
+use super::flow::{oauth_error, tokens_from, OAuthTokens, SCOPE};
+use super::now_ms;
+use super::session::MicrosoftSession;
+
+/// 授权码 grant 类型。
+pub const AUTHORIZATION_CODE_GRANT: &str = "authorization_code";
+/// 默认等回调的时间预算（用户要开浏览器、登录、点同意）。
+pub const DEFAULT_CALLBACK_TIMEOUT: Duration = Duration::from_secs(300);
+/// 默认的端口绑定尝试次数。
+pub const DEFAULT_BIND_ATTEMPTS: u8 = 3;
+
+/// 回填到授权 URL 与 token 请求里的重定向 URI（**唯一来源**）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RedirectUri {
+    port: u16,
+    url: String,
+}
+
+impl RedirectUri {
+    /// 按实际绑定的端口构造 `http://localhost:{port}/auth`。
+    ///
+    /// 用 `localhost` 而不是 `127.0.0.1`：微软对两者处理不一致（`research/08` 坑 5）。
+    #[must_use]
+    pub fn new(port: u16) -> Self {
+        Self {
+            port,
+            url: format!("http://localhost:{port}{REDIRECT_PATH}"),
+        }
+    }
+
+    /// 端口。
+    #[must_use]
+    pub fn port(&self) -> u16 {
+        self.port
+    }
+
+    /// URI 字面量（授权 URL 与 token 请求共用，保证逐字节一致）。
+    #[must_use]
+    pub fn as_str(&self) -> &str {
+        &self.url
+    }
+}
+
+impl fmt::Display for RedirectUri {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str(&self.url)
+    }
+}
+
+/// 授权码流的运行参数（生产用 [`AuthCodePolicy::default`]，测试压短超时/固定端口）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AuthCodePolicy {
+    /// 等浏览器回调的上限。
+    pub callback_timeout: Duration,
+    /// 端口绑定尝试次数（`>= 1`）。
+    pub bind_attempts: u8,
+    /// 固定端口（`None` = 由内核分配，生产路径）。
+    pub port: Option<u16>,
+    /// CSRF 用的 `state`（`None` = 每次随机生成）。
+    pub state: Option<String>,
+}
+
+impl Default for AuthCodePolicy {
+    fn default() -> Self {
+        Self {
+            callback_timeout: DEFAULT_CALLBACK_TIMEOUT,
+            bind_attempts: DEFAULT_BIND_ATTEMPTS,
+            port: None,
+            state: None,
+        }
+    }
+}
+
+/// 要宿主做的事：打开浏览器（core 不碰 UI：谁来开由 CLI/GUI 决定）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AuthCodePrompt {
+    /// 授权页 URL（宿主交给系统默认浏览器；也可展示给用户手动打开）。
+    pub authorization_url: String,
+    /// 本地回调地址（展示/排障用；与授权 URL 里的 `redirect_uri` 同源）。
+    pub redirect_uri: String,
+    /// 最多等多久。
+    pub timeout: Duration,
+}
+
+/// 拼授权 URL（`response_type=code` + `prompt=select_account` + 严格编码的重定向 URI）。
+#[must_use]
+pub fn authorization_url(
+    endpoints: &MicrosoftEndpoints,
+    client_id: &str,
+    redirect_uri: &RedirectUri,
+    state: &str,
+) -> String {
+    format!(
+        "{}?client_id={}&response_type=code&redirect_uri={}&scope={}&prompt=select_account&state={}",
+        endpoints.authorize,
+        encode(client_id),
+        encode(redirect_uri.as_str()),
+        encode(SCOPE),
+        encode(state),
+    )
+}
+
+/// 授权码换 token（`grant_type=authorization_code`）。
+///
+/// # Errors
+///
+/// OAuth 拒绝（[`crate::auth::AuthError::Denied`] /
+/// [`crate::auth::AuthError::CredentialExpired`]）、网络失败、响应缺 token。
+pub(crate) async fn exchange_code(
+    client: &Client,
+    endpoints: &MicrosoftEndpoints,
+    client_id: &str,
+    code: &Secret,
+    redirect_uri: &RedirectUri,
+) -> AuthResult<OAuthTokens> {
+    let reply = post_form(
+        client,
+        &endpoints.token,
+        vec![
+            ("client_id", client_id.to_string()),
+            ("grant_type", AUTHORIZATION_CODE_GRANT.to_string()),
+            ("code", code.expose().to_string()),
+            ("redirect_uri", redirect_uri.as_str().to_string()),
+            ("scope", SCOPE.to_string()),
+        ],
+    )
+    .await?;
+    if reply.text("error").is_some() || !reply.is_success() {
+        return Err(oauth_error(&reply, &endpoints.token));
+    }
+    tokens_from(&reply, &endpoints.token)
+}
+
+/// 授权码登录主体：绑端口 → 出授权 URL（交给 `present`）→ 等回调 → 换 token → 整链。
+///
+/// `present` 在**端口绑定之后、等待之前**被调用：宿主此时才知道端口，也只有这时
+/// 打开浏览器才不会让用户对着还没起来的服务端登录。
+pub(crate) async fn login<F>(
+    client: &Client,
+    endpoints: &MicrosoftEndpoints,
+    client_id: &str,
+    policy: AuthCodePolicy,
+    present: F,
+) -> AuthResult<MicrosoftSession>
+where
+    F: FnOnce(&AuthCodePrompt),
+{
+    let state = policy.state.clone().unwrap_or_else(nonce);
+    let server = CallbackServer::bind(policy.port, policy.bind_attempts, state.clone()).await?;
+    let redirect_uri = RedirectUri::new(server.port());
+    present(&AuthCodePrompt {
+        authorization_url: authorization_url(endpoints, client_id, &redirect_uri, &state),
+        redirect_uri: redirect_uri.as_str().to_string(),
+        timeout: policy.callback_timeout,
+    });
+    let code = server.wait_for_code(policy.callback_timeout).await?;
+    let tokens = exchange_code(
+        client,
+        endpoints,
+        client_id,
+        &Secret::new(code),
+        &redirect_uri,
+    )
+    .await?;
+    complete_chain(client, endpoints, tokens, now_ms()).await
+}
+
+/// 每次登录一个 `state`（不用于加密，只用来把迟到的旧回调挡掉）。
+///
+/// 128 位（两个独立随机种子的 SipHash 输出拼接）：RFC 6749 §10.10 建议 `state` 至少
+/// 128 位熵，挡住「猜到 state 就能伪造回调」这类攻击面。
+fn nonce() -> String {
+    use std::collections::hash_map::RandomState;
+    use std::hash::{BuildHasher, Hasher};
+
+    let nanos = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|since| since.as_nanos())
+        .unwrap_or(0);
+    let mut halves = [String::new(), String::new()];
+    for half in &mut halves {
+        // 每次 `RandomState::new()` 都是独立随机种子 → 两段各 64 位、彼此不可推。
+        let mut hasher = RandomState::new().build_hasher();
+        hasher.write_u128(nanos);
+        hasher.write_u32(std::process::id());
+        *half = format!("{:016x}", hasher.finish());
+    }
+    format!("{}{}", halves[0], halves[1])
+}
+
+/// 百分号编码（RFC 3986 unreserved 之外一律转义；空格用 `%20` 而不是 `+`）。
+fn encode(raw: &str) -> String {
+    let mut out = String::with_capacity(raw.len());
+    for byte in raw.bytes() {
+        match byte {
+            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'.' | b'_' | b'~' => {
+                out.push(char::from(byte));
+            }
+            _ => out.push_str(&format!("%{byte:02X}")),
+        }
+    }
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{authorization_url, encode, RedirectUri, AUTHORIZATION_CODE_GRANT};
+    use crate::auth::microsoft::MicrosoftEndpoints;
+
+    #[test]
+    fn redirect_uri_is_localhost_with_exact_port_and_path() {
+        let uri = RedirectUri::new(51_234);
+        assert_eq!(uri.as_str(), "http://localhost:51234/auth");
+        assert_eq!(uri.port(), 51_234);
+        assert_eq!(uri.to_string(), uri.as_str());
+    }
+
+    #[test]
+    fn authorization_url_matches_research_08_vector() {
+        let endpoints = MicrosoftEndpoints::consumers();
+        let uri = RedirectUri::new(8_080);
+        let url = authorization_url(&endpoints, "0000-client", &uri, "state-123");
+        assert_eq!(
+            url,
+            "https://login.microsoftonline.com/consumers/oauth2/v2.0/authorize\
+?client_id=0000-client&response_type=code\
+&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fauth\
+&scope=XboxLive.signin%20offline_access&prompt=select_account&state=state-123"
+        );
+        // 三个硬性细节各断言一遍，改坏了立刻知道是哪一条。
+        assert!(url.contains("/consumers/oauth2/v2.0/authorize"));
+        assert!(url.contains("prompt=select_account"));
+        assert!(url.contains("scope=XboxLive.signin%20offline_access"));
+    }
+
+    #[test]
+    fn encode_escapes_everything_but_unreserved() {
+        assert_eq!(encode("abc-._~09"), "abc-._~09");
+        assert_eq!(encode("a b/c:"), "a%20b%2Fc%3A");
+    }
+
+    #[test]
+    fn grant_type_is_the_standard_one() {
+        assert_eq!(AUTHORIZATION_CODE_GRANT, "authorization_code");
+    }
+
+    #[test]
+    fn generated_state_has_128_bits_of_entropy() {
+        let first = super::nonce();
+        let second = super::nonce();
+        assert_eq!(first.len(), 32, "128 位 = 32 个 hex 字符：{first}");
+        assert!(first.chars().all(|c| c.is_ascii_hexdigit()), "{first}");
+        assert_ne!(first, second, "每次登录的 state 必须不同");
+    }
+}
diff --git a/crates/core/src/auth/microsoft/callback.rs b/crates/core/src/auth/microsoft/callback.rs
new file mode 100644
index 0000000..2e8a27c
--- /dev/null
+++ b/crates/core/src/auth/microsoft/callback.rs
@@ -0,0 +1,346 @@
+//! 授权码流的本地回调服务器（`research/08` §3 方案 A：HMCL 主流做法）。
+//!
+//! 只干一件事：等浏览器把 `?code=` 送到 `http://localhost:{port}/auth`，把 code 交出去。
+//! 协议面故意压到最小（只认一个 GET 路径、只回一个静态页），这样它能被单测直接驱动。
+//!
+//! # 四条容易踩的细节
+//!
+//! 1. **重定向 URI 用 `localhost`，监听绑 `127.0.0.1`**：微软对 `localhost` 与 `127.0.0.1`
+//!    处理不一致（坑 5），URI 只能写前者；浏览器把 `localhost` 解析到 `::1` 时会被拒一次
+//!    再回落 IPv4，Chrome/Edge 都走这条回退，所以只绑 v4 就够。
+//! 2. **端口由内核分配**（绑定 `:0`），端口被占时按 `attempts` 重试；授权 URL 里的
+//!    `redirect_uri` 必须用**最终绑到的端口**回填，换 token 时再原样带上（URI 严格一致）。
+//! 3. **非 `/auth` 的请求（`/favicon.ico`、浏览器预连）回 404 后继续等**：让一个 favicon
+//!    把整次登录判成失败是最容易犯的错。
+//! 4. **`state` 不匹配的请求一律回 400 后继续等**——包括带 `error=` 的那些：旧标签页的
+//!    迟到回调不该打断新的登录，更要紧的是 RFC 6749 §4.1.2.1 / RFC 9207 要求**错误响应同样
+//!    要校验 `state`**；否则任何人 `GET /auth?error=access_denied` 就能静默中止别人的登录。
+//!    真正的超时由调用方的时间预算兜底。
+
+use std::time::Duration;
+
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+use tokio::net::{TcpListener, TcpStream};
+
+use crate::auth::error::{AuthError, AuthResult};
+
+/// 回调路径（重定向 URI 的路径段）。
+pub const REDIRECT_PATH: &str = "/auth";
+/// 一次回调请求最多读这么多字节（超了就丢弃连接，防被灌内存）。
+pub const MAX_REQUEST_HEAD: usize = 8 * 1024;
+/// 端口被占用时的重试间隔。
+const RETRY_DELAY: Duration = Duration::from_millis(20);
+/// 单条连接读完请求头的上限（浏览器/预连不把请求头发完时不能把整个登录卡死）。
+const REQUEST_READ_TIMEOUT: Duration = Duration::from_secs(5);
+
+const SUCCESS_PAGE: &str = "<!DOCTYPE html><html lang=\"zh-CN\"><head><meta charset=\"utf-8\">\
+<title>登录完成</title></head><body style=\"font-family:system-ui;padding:40px\">\
+<h1>登录完成</h1><p>可以关闭此窗口，回到启动器继续。</p></body></html>";
+const DENIED_PAGE: &str = "<!DOCTYPE html><html lang=\"zh-CN\"><head><meta charset=\"utf-8\">\
+<title>登录未完成</title></head><body style=\"font-family:system-ui;padding:40px\">\
+<h1>登录未完成</h1><p>授权没有完成，可以回到启动器重试。</p></body></html>";
+const BAD_REQUEST_PAGE: &str = "<!DOCTYPE html><html lang=\"zh-CN\"><head><meta charset=\"utf-8\">\
+<title>回调无效</title></head><body style=\"font-family:system-ui;padding:40px\">\
+<h1>回调无效</h1><p>这个链接不属于本次登录。</p></body></html>";
+const NOT_FOUND_PAGE: &str = "<!DOCTYPE html><html lang=\"en\"><head><meta charset=\"utf-8\">\
+<title>Not Found</title></head><body><h1>Not Found</h1></body></html>";
+
+/// 本地回调服务器（一个实例只服务一次登录）。
+#[derive(Debug)]
+pub struct CallbackServer {
+    listener: TcpListener,
+    port: u16,
+    state: String,
+}
+
+impl CallbackServer {
+    /// 绑定回调端口。
+    ///
+    /// `port` 为 `None` 时由内核分配（生产路径）；给定端口时按 `attempts` 重试
+    /// （CLI/测试里固定端口用，端口被占会退避再试）。
+    ///
+    /// # Errors
+    ///
+    /// 全部尝试都绑定失败时返回 [`AuthError::Network`]（文案带端口与重试次数）。
+    pub async fn bind(
+        port: Option<u16>,
+        attempts: u8,
+        state: impl Into<String>,
+    ) -> AuthResult<Self> {
+        let wanted = port.unwrap_or(0);
+        let attempts = attempts.max(1);
+        let mut last = String::new();
+        for attempt in 0..attempts {
+            match TcpListener::bind(("127.0.0.1", wanted)).await {
+                Ok(listener) => {
+                    let port = listener
+                        .local_addr()
+                        .map_err(|error| AuthError::network("localhost", error.to_string()))?
+                        .port();
+                    return Ok(Self {
+                        listener,
+                        port,
+                        state: state.into(),
+                    });
+                }
+                Err(error) => {
+                    last = error.to_string();
+                    if attempt + 1 < attempts {
+                        tokio::time::sleep(RETRY_DELAY).await;
+                    }
+                }
+            }
+        }
+        let what = if wanted == 0 {
+            "本地回调端口分配失败".to_string()
+        } else {
+            format!("本地回调端口 {wanted} 绑定失败（重试 {attempts} 次）")
+        };
+        Err(AuthError::network("localhost", format!("{what}：{last}")))
+    }
+
+    /// 实际端口（回填 `redirect_uri` 用）。
+    #[must_use]
+    pub fn port(&self) -> u16 {
+        self.port
+    }
+
+    /// 本次登录的 `state`（授权 URL 与回调校验共用）。
+    #[must_use]
+    pub fn state(&self) -> &str {
+        &self.state
+    }
+
+    /// 等浏览器把 code 送到 `/auth`，最多等 `timeout`。
+    ///
+    /// # Errors
+    ///
+    /// 超时（[`AuthError::Timeout`]）、用户在授权页点了取消（[`AuthError::Canceled`]）、
+    /// 授权页回了别的 `error`（[`AuthError::Denied`]）、socket 出错（[`AuthError::Network`]）。
+    pub async fn wait_for_code(self, timeout: Duration) -> AuthResult<String> {
+        let deadline = tokio::time::Instant::now() + timeout;
+        loop {
+            let remaining = deadline.saturating_duration_since(tokio::time::Instant::now());
+            if remaining.is_zero() {
+                return Err(wait_timeout(timeout));
+            }
+            let accepted = tokio::time::timeout(remaining, self.listener.accept()).await;
+            let (mut stream, _) = match accepted {
+                Ok(Ok(pair)) => pair,
+                Ok(Err(error)) => {
+                    return Err(AuthError::network("localhost", error.to_string()));
+                }
+                Err(_) => return Err(wait_timeout(timeout)),
+            };
+            // 一条连接最多读这么久请求头：慢客户端/半开连接不能把整个登录拖过时间预算。
+            // 预算按 **accept 之后** 的剩余时间重算（用 accept 前那份会让总时长超发最多 5s）。
+            let budget = REQUEST_READ_TIMEOUT
+                .min(deadline.saturating_duration_since(tokio::time::Instant::now()));
+            if budget.is_zero() {
+                return Err(wait_timeout(timeout));
+            }
+            match tokio::time::timeout(budget, self.handle(&mut stream)).await {
+                Ok(result) => {
+                    if let Some(code) = result? {
+                        return Ok(code);
+                    }
+                }
+                Err(_) => continue,
+            }
+        }
+    }
+
+    /// 处理一条连接：`Some(code)` = 登录完成，`None` = 与本次登录无关，继续等。
+    async fn handle(&self, stream: &mut TcpStream) -> AuthResult<Option<String>> {
+        let Some(target) = read_request_target(stream).await else {
+            return Ok(None);
+        };
+        let (path, query) = match target.split_once('?') {
+            Some((path, query)) => (path, query),
+            None => (target.as_str(), ""),
+        };
+        if path != REDIRECT_PATH {
+            respond(stream, 404, NOT_FOUND_PAGE).await;
+            return Ok(None);
+        }
+        let params = Query::parse(query);
+        // state 必须先校验，且**先于** error：错误响应同样要认 state（RFC 6749 §4.1.2.1 /
+        // RFC 9207）。否则任意一次 `GET /auth?error=access_denied`（state 随便给或不给）就能
+        // 把这台机器上正在进行的登录静默中止 —— 不需要知道随机 state、不需要 code。
+        if params.get("state") != Some(self.state.as_str()) {
+            respond(stream, 400, BAD_REQUEST_PAGE).await;
+            return Ok(None);
+        }
+        if let Some(error) = params.get("error") {
+            respond(stream, 200, DENIED_PAGE).await;
+            return Err(oauth_error(error, params.get("error_description")));
+        }
+        let Some(code) = params.get("code").filter(|code| !code.is_empty()) else {
+            respond(stream, 400, BAD_REQUEST_PAGE).await;
+            return Ok(None);
+        };
+        respond(stream, 200, SUCCESS_PAGE).await;
+        Ok(Some(code.to_string()))
+    }
+}
+
+fn wait_timeout(timeout: Duration) -> AuthError {
+    AuthError::Timeout {
+        what: format!("等待浏览器回调（上限 {} 秒）", timeout.as_secs()),
+    }
+}
+
+/// 授权页回的 `error` → 错误分流（`access_denied` 归取消，其余归拒绝）。
+fn oauth_error(code: &str, description: Option<&str>) -> AuthError {
+    if matches!(code, "access_denied" | "authorization_declined") {
+        return AuthError::Canceled;
+    }
+    AuthError::Denied {
+        code: code.to_string(),
+        description: description.unwrap_or("授权页没有给出原因").to_string(),
+    }
+}
+
+/// 读请求行里的 target（`/auth?code=...`）。非 GET/HEAD、超长头、连接中断都给 `None`。
+async fn read_request_target(stream: &mut TcpStream) -> Option<String> {
+    let mut buffer = Vec::new();
+    let mut chunk = [0_u8; 1024];
+    loop {
+        if let Some(end) = find_headers_end(&buffer) {
+            let head = String::from_utf8_lossy(&buffer[..end]).into_owned();
+            let mut parts = head.lines().next()?.split(' ');
+            let method = parts.next()?;
+            if !method.eq_ignore_ascii_case("GET") && !method.eq_ignore_ascii_case("HEAD") {
+                return None;
+            }
+            return parts.next().map(str::to_string);
+        }
+        if buffer.len() > MAX_REQUEST_HEAD {
+            return None;
+        }
+        match stream.read(&mut chunk).await {
+            Ok(0) | Err(_) => return None,
+            Ok(read) => buffer.extend_from_slice(&chunk[..read]),
+        }
+    }
+}
+
+fn find_headers_end(buffer: &[u8]) -> Option<usize> {
+    buffer
+        .windows(4)
+        .position(|window| window == b"\r\n\r\n")
+        .map(|position| position + 4)
+}
+
+async fn respond(stream: &mut TcpStream, status: u16, page: &str) {
+    let response = format!(
+        "HTTP/1.1 {status} {}\r\nContent-Type: text/html; charset=utf-8\r\n\
+Content-Length: {}\r\nConnection: close\r\n\r\n{page}",
+        reason(status),
+        page.len()
+    );
+    let _ = stream.write_all(response.as_bytes()).await;
+    let _ = stream.flush().await;
+}
+
+fn reason(status: u16) -> &'static str {
+    match status {
+        200 => "OK",
+        400 => "Bad Request",
+        404 => "Not Found",
+        _ => "Status",
+    }
+}
+
+/// 回调 query 的最小解析（`k=v` 对，percent 解码）。
+struct Query(Vec<(String, String)>);
+
+impl Query {
+    fn parse(raw: &str) -> Self {
+        Self(
+            raw.split('&')
+                .filter(|pair| !pair.is_empty())
+                .filter_map(|pair| {
+                    let (key, value) = pair.split_once('=')?;
+                    Some((decode(key), decode(value)))
+                })
+                .collect(),
+        )
+    }
+
+    fn get(&self, key: &str) -> Option<&str> {
+        self.0
+            .iter()
+            .find(|(name, _)| name == key)
+            .map(|(_, value)| value.as_str())
+    }
+}
+
+/// `percent` 解码（`+` 视为空格；坏转义原样保留）。
+fn decode(raw: &str) -> String {
+    let bytes = raw.as_bytes();
+    let mut out = Vec::with_capacity(bytes.len());
+    let mut index = 0;
+    while index < bytes.len() {
+        match bytes[index] {
+            b'%' if index + 2 < bytes.len() => {
+                let parsed = std::str::from_utf8(&bytes[index + 1..index + 3])
+                    .ok()
+                    .and_then(|hex| u8::from_str_radix(hex, 16).ok());
+                match parsed {
+                    Some(byte) => {
+                        out.push(byte);
+                        index += 3;
+                    }
+                    None => {
+                        out.push(b'%');
+                        index += 1;
+                    }
+                }
+            }
+            b'+' => {
+                out.push(b' ');
+                index += 1;
+            }
+            byte => {
+                out.push(byte);
+                index += 1;
+            }
+        }
+    }
+    String::from_utf8_lossy(&out).into_owned()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{decode, oauth_error, Query};
+    use crate::auth::error::AuthError;
+
+    #[test]
+    fn query_decodes_percent_and_plus() {
+        let query = Query::parse("code=ab%2Fcd&state=s+1&empty=");
+        assert_eq!(query.get("code"), Some("ab/cd"));
+        assert_eq!(query.get("state"), Some("s 1"));
+        assert_eq!(query.get("empty"), Some(""));
+        assert_eq!(query.get("missing"), None);
+    }
+
+    #[test]
+    fn decode_keeps_broken_escapes() {
+        assert_eq!(decode("100%"), "100%");
+        assert_eq!(decode("%zz"), "%zz");
+        assert_eq!(decode("a%20b"), "a b");
+    }
+
+    #[test]
+    fn access_denied_maps_to_canceled() {
+        assert_eq!(oauth_error("access_denied", None), AuthError::Canceled);
+        match oauth_error("invalid_request", Some("bad scope")) {
+            AuthError::Denied { code, description } => {
+                assert_eq!(code, "invalid_request");
+                assert_eq!(description, "bad scope");
+            }
+            other => panic!("应是 Denied，实际 {other:?}"),
+        }
+    }
+}
diff --git a/crates/core/src/auth/microsoft/chain.rs b/crates/core/src/auth/microsoft/chain.rs
new file mode 100644
index 0000000..841ab82
--- /dev/null
+++ b/crates/core/src/auth/microsoft/chain.rs
@@ -0,0 +1,377 @@
+//! 微软五步链：Live token → **XBL** → **XSTS** → **login_with_xbox** → **entitlements** → **profile**。
+//!
+//! 逐条承 `analyse/04` §5.2（报文级别），四处容易抄错的地方都在注释里点名：
+//! 1. XBL 的 `RpsTicket` 必须带 **`d=` 前缀**（MSA 消费版票据标记）；
+//! 2. `identityToken` 是 **`XBL3.0 x=<uhs>;<xsts>`**（分号分隔，`x` 后紧跟 `=`）；
+//! 3. XSTS 在「无 Xbox 档案/儿童账号/地区不支持」时回 **401**（不是 200+JSON），
+//!    必须读 body 里的 `XErr` 才能给出准确原因；
+//! 4. `/minecraft/profile` 的 **404 二义**：没买游戏 vs 买了没建档案，
+//!    要用 `entitlements/license` 复判一次才分得清。
+//!
+//! **XSTS/MC 令牌不缓存**：刷新就是整链重跑（`analyse/04` §5.1），所以本模块只做无状态串联。
+
+use reqwest::Client;
+use serde_json::json;
+
+use crate::auth::body;
+use crate::auth::error::AuthError;
+use crate::auth::secret::{redactor_for, Secret};
+
+use super::endpoints::MicrosoftEndpoints;
+use super::flow::OAuthTokens;
+use super::session::MicrosoftSession;
+use crate::auth::http::{get_json, post_json, Reply};
+
+/// Xbox Live 用户票据 + 用户哈希。
+#[derive(Debug, Clone)]
+pub(crate) struct XboxTicket {
+    /// JWT 票据（凭据形状）。
+    pub token: Secret,
+    /// `uhs`（`XBL3.0 x=<uhs>;...` 的 userhash；本身不是凭据但只在本链内部用）。
+    pub uhs: String,
+}
+
+/// MC 侧换到的令牌。
+#[derive(Debug, Clone)]
+pub(crate) struct MinecraftToken {
+    /// MC access token（落盘）。
+    pub access_token: Secret,
+    /// 有效期（秒）。
+    pub expires_in: u64,
+}
+
+/// Minecraft 档案（不可变 id + 可变 name）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct GameProfile {
+    /// 32 位无连字符 UUID。
+    pub id: String,
+    /// 玩家名。
+    pub name: String,
+}
+
+/// 第 1 步：Xbox Live User Authenticate。
+pub(crate) async fn xbl_authenticate(
+    client: &Client,
+    endpoints: &MicrosoftEndpoints,
+    live_access_token: &Secret,
+) -> Result<XboxTicket, AuthError> {
+    let body = json!({
+        "Properties": {
+            "AuthMethod": "RPS",
+            "SiteName": "user.auth.xboxlive.com",
+            "RpsTicket": format!("d={}", live_access_token.expose()),
+        },
+        "RelyingParty": "http://auth.xboxlive.com",
+        "TokenType": "JWT",
+    });
+    let reply = post_json(client, &endpoints.xbl_authenticate, &body, None).await?;
+    if let Some(code) = xerr(&reply) {
+        return Err(AuthError::Xbox { code });
+    }
+    if !reply.is_success() {
+        // M38：XErr 优先（业务码才是真原因），没有 XErr 时把正文诊断补进文案。
+        return Err(body::response(
+            "xbl",
+            &reply,
+            "Xbox Live 用户认证被拒",
+            &redactor_for([live_access_token]),
+        ));
+    }
+    let token = reply
+        .text("Token")
+        .ok_or_else(|| AuthError::Malformed("XBL 响应缺 Token".to_string()))?;
+    let uhs = uhs_of(&reply)
+        .ok_or_else(|| AuthError::Malformed("XBL 响应缺 DisplayClaims.xui[0].uhs".to_string()))?;
+    Ok(XboxTicket {
+        token: Secret::new(token),
+        uhs,
+    })
+}
+
+/// 第 2 步：XSTS Authorize（401 也读 body，`XErr` 才是真原因）。
+pub(crate) async fn xsts_authorize(
+    client: &Client,
+    endpoints: &MicrosoftEndpoints,
+    xbl: &XboxTicket,
+) -> Result<XboxTicket, AuthError> {
+    let body = json!({
+        "Properties": { "SandboxId": "RETAIL", "UserTokens": [xbl.token.expose()] },
+        "RelyingParty": "rp://api.minecraftservices.com/",
+        "TokenType": "JWT",
+    });
+    let reply = post_json(client, &endpoints.xsts_authorize, &body, None).await?;
+    if let Some(code) = xerr(&reply) {
+        return Err(AuthError::Xbox { code });
+    }
+    if !reply.is_success() {
+        return Err(body::response(
+            "xsts",
+            &reply,
+            "XSTS 授权被拒",
+            &redactor_for([&xbl.token]),
+        ));
+    }
+    let token = reply
+        .text("Token")
+        .ok_or_else(|| AuthError::Malformed("XSTS 响应缺 Token".to_string()))?;
+    let uhs = uhs_of(&reply).ok_or_else(|| AuthError::Malformed("XSTS 响应缺 uhs".to_string()))?;
+    // 一致性断言：同一账号在 XBL 与 XSTS 两次返回的 userhash 必须相同。
+    if uhs != xbl.uhs {
+        return Err(AuthError::Malformed(
+            "XBL 与 XSTS 返回的 userhash 不一致".to_string(),
+        ));
+    }
+    Ok(XboxTicket {
+        token: Secret::new(token),
+        uhs,
+    })
+}
+
+/// 第 3 步：`login_with_xbox` 换 Minecraft 令牌。
+pub(crate) async fn login_with_xbox(
+    client: &Client,
+    endpoints: &MicrosoftEndpoints,
+    xsts: &XboxTicket,
+) -> Result<MinecraftToken, AuthError> {
+    let body = json!({
+        "identityToken": format!("XBL3.0 x={};{}", xsts.uhs, xsts.token.expose()),
+    });
+    let reply = post_json(client, &endpoints.login_with_xbox, &body, None).await?;
+    if !reply.is_success() {
+        // M38 的核心一行：403 到底是「拦截页」还是「服务端拒绝」，文案要分开引导。
+        return Err(body::response(
+            "login_with_xbox",
+            &reply,
+            "Minecraft 登录被拒",
+            &redactor_for([&xsts.token]),
+        ));
+    }
+    let access_token = reply
+        .text("access_token")
+        .ok_or_else(|| AuthError::Malformed("login_with_xbox 缺 access_token".to_string()))?;
+    Ok(MinecraftToken {
+        access_token: Secret::new(access_token),
+        expires_in: reply.number("expires_in").unwrap_or(0),
+    })
+}
+
+/// 第 4 步：拥有权校验（必须 200，否则后面启动时也会被服务端踢）。
+pub(crate) async fn check_entitlements(
+    client: &Client,
+    endpoints: &MicrosoftEndpoints,
+    mc_token: &Secret,
+) -> Result<(), AuthError> {
+    let reply = get_json(client, &endpoints.entitlements_mcstore, mc_token).await?;
+    if reply.is_success() {
+        return Ok(());
+    }
+    let detail = body::rejection(
+        "entitlements",
+        &reply,
+        "拥有权校验未通过",
+        &redactor_for([mc_token]),
+    );
+    // 拦截页（HTML/纯文本）与非 404 的空体先当网络问题报，别让用户去查许可；
+    // JSON 拒绝与 404 沿用 M31 的 `no_entitlement`（稳定码不改）。
+    let interception = detail.kind.is_interception()
+        || (detail.kind == body::BodyKind::Empty && reply.status != 404);
+    if interception {
+        return Err(AuthError::Response(Box::new(detail)));
+    }
+    let what = if reply.status == 404 {
+        "该账号没有 Minecraft Java 版拥有权"
+    } else {
+        detail.what.as_str()
+    };
+    Err(AuthError::Denied {
+        code: "no_entitlement".to_string(),
+        description: format!(
+            "{what}（entitlements/mcstore 返回 HTTP {}）{}",
+            reply.status,
+            detail.note()
+        ),
+    })
+}
+
+/// 第 5 步：拉档案（404 用 license 复判二义）。
+pub(crate) async fn fetch_profile(
+    client: &Client,
+    endpoints: &MicrosoftEndpoints,
+    mc_token: &Secret,
+) -> Result<GameProfile, AuthError> {
+    let reply = get_json(client, &endpoints.profile, mc_token).await?;
+    // 只有「像服务端应答」的 404 才走二义复判：HTML/纯文本的 404 是网关页，
+    // 拿它去复判 license 会得出错误的「没买游戏」结论。
+    if reply.status == 404 && !body::classify(&reply).is_interception() {
+        return Err(profile_missing(client, endpoints, mc_token).await);
+    }
+    if !reply.is_success() {
+        return Err(body::response(
+            "profile",
+            &reply,
+            "拉取 Minecraft 档案被拒",
+            &redactor_for([mc_token]),
+        ));
+    }
+    let id = reply
+        .text("id")
+        .ok_or_else(|| AuthError::Malformed("档案响应缺 id".to_string()))?;
+    let name = reply
+        .text("name")
+        .ok_or_else(|| AuthError::Malformed("档案响应缺 name".to_string()))?;
+    Ok(GameProfile {
+        id: id.to_string(),
+        name: name.to_string(),
+    })
+}
+
+/// 404 之后的二义消解：没买游戏 vs 买了没建档案。
+async fn profile_missing(
+    client: &Client,
+    endpoints: &MicrosoftEndpoints,
+    mc_token: &Secret,
+) -> AuthError {
+    let reply = match get_json(client, &endpoints.entitlements_license, mc_token).await {
+        Ok(reply) => reply,
+        // 复判本身失败时，退回「档案不存在」这个更保守的说法。
+        Err(_) => {
+            return AuthError::Denied {
+                code: "no_profile".to_string(),
+                description: "该账号没有 Minecraft 档案（复判 license 也失败）".to_string(),
+            }
+        }
+    };
+    if has_minecraft_license(&reply) {
+        AuthError::Denied {
+            code: "no_profile".to_string(),
+            description: "账号已拥有 Minecraft，但还没有创建档案（去 minecraft.net 起个名字）"
+                .to_string(),
+        }
+    } else {
+        AuthError::Denied {
+            code: "no_license".to_string(),
+            description: "该账号没有购买 Minecraft Java 版".to_string(),
+        }
+    }
+}
+
+/// `entitlements/license` 响应里是否有 `game_minecraft`。
+fn has_minecraft_license(reply: &Reply) -> bool {
+    reply
+        .body
+        .as_ref()
+        .and_then(|body| body.get("items"))
+        .and_then(|items| items.as_array())
+        .is_some_and(|items| {
+            items.iter().any(|item| {
+                item.get("name")
+                    .and_then(|name| name.as_str())
+                    .is_some_and(|name| name == "game_minecraft")
+            })
+        })
+}
+
+/// 整链：Live token → [`MicrosoftSession`]（刷新与新登录共用这一段）。
+pub(crate) async fn complete_chain(
+    client: &Client,
+    endpoints: &MicrosoftEndpoints,
+    tokens: OAuthTokens,
+    now_ms: u64,
+) -> Result<MicrosoftSession, AuthError> {
+    let xbl = xbl_authenticate(client, endpoints, &tokens.access_token).await?;
+    let xsts = xsts_authorize(client, endpoints, &xbl).await?;
+    let mc = login_with_xbox(client, endpoints, &xsts).await?;
+    check_entitlements(client, endpoints, &mc.access_token).await?;
+    let profile = fetch_profile(client, endpoints, &mc.access_token).await?;
+    Ok(MicrosoftSession::new(
+        profile.id,
+        profile.name,
+        mc.access_token,
+        tokens.refresh_token,
+        mc.expires_in,
+        now_ms,
+        None,
+    ))
+}
+
+/// 从响应里取 `XErr`（XSTS 的 401 业务码）。
+fn xerr(reply: &Reply) -> Option<u32> {
+    let body = reply.body.as_ref()?;
+    for key in ["XErr", "errorCode"] {
+        if let Some(code) = body.get(key).and_then(|value| value.as_u64()) {
+            if code != 0 {
+                return Some(code as u32);
+            }
+        }
+    }
+    None
+}
+
+fn uhs_of(reply: &Reply) -> Option<String> {
+    reply
+        .body
+        .as_ref()?
+        .get("DisplayClaims")?
+        .get("xui")?
+        .as_array()?
+        .first()?
+        .get("uhs")?
+        .as_str()
+        .map(str::to_string)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{has_minecraft_license, uhs_of, xerr, Reply};
+    use serde_json::{json, Value};
+
+    fn reply(status: u16, body: Option<Value>) -> Reply {
+        Reply {
+            status,
+            body,
+            content_type: Some("application/json".to_string()),
+            raw: None,
+        }
+    }
+
+    #[test]
+    fn xerr_is_read_from_401_body() {
+        let sample = reply(
+            401,
+            Some(json!({ "Identity": "0", "XErr": 2_148_916_238_u32, "Message": "" })),
+        );
+        assert_eq!(xerr(&sample), Some(2_148_916_238));
+        assert_eq!(xerr(&reply(200, Some(json!({ "XErr": 0 })))), None);
+        assert_eq!(xerr(&reply(200, None)), None);
+    }
+
+    #[test]
+    fn uhs_comes_from_first_xui_entry() {
+        let sample = reply(
+            200,
+            Some(json!({ "DisplayClaims": { "xui": [{ "uhs": "1234" }] } })),
+        );
+        assert_eq!(uhs_of(&sample).as_deref(), Some("1234"));
+        assert_eq!(
+            uhs_of(&reply(200, Some(json!({ "DisplayClaims": {} })))),
+            None
+        );
+    }
+
+    #[test]
+    fn license_detection() {
+        let with = reply(
+            200,
+            Some(
+                json!({ "items": [{ "name": "product_minecraft" }, { "name": "game_minecraft" }] }),
+            ),
+        );
+        let without = reply(
+            200,
+            Some(json!({ "items": [{ "name": "product_minecraft" }] })),
+        );
+        assert!(has_minecraft_license(&with));
+        assert!(!has_minecraft_license(&without));
+        assert!(!has_minecraft_license(&reply(500, None)));
+    }
+}
diff --git a/crates/core/src/auth/microsoft/client_id.rs b/crates/core/src/auth/microsoft/client_id.rs
new file mode 100644
index 0000000..d7194fb
--- /dev/null
+++ b/crates/core/src/auth/microsoft/client_id.rs
@@ -0,0 +1,248 @@
+//! Azure 公共客户端 id 的**配置状态**：从哪来、配没配、启动日志那一行长什么样。
+//!
+//! ## 为什么单独一块（M117）
+//!
+//! 这个 id 不进仓库（用户定案），所以它可以来自两处：运行期环境变量 [`CLIENT_ID_ENV`]，
+//! 或构建期 `option_env!` 注入（[`CLIENT_ID_BUILD`]）。**两处都没有**时登录是「没配置」，
+//! 不是「没实现」——这两件事在用户眼里完全不同，文案与日志都必须分清：
+//!
+//! | 现象 | 该说什么 |
+//! |---|---|
+//! | 两处都没配 | [`MISSING_CLIENT_ID_MESSAGE`]：未配置 + 怎么配（含可照抄的命令） |
+//! | 配了但登录失败 | 走 `AuthError` 的正常分流（网络/拒绝/无拥有权…），**不许**再提「未实现」 |
+//!
+//! [`ClientIdStatus::log_line`] 是给启动日志的那一行：`[auth] msa client_id=… source=…`。
+//! 有了它，「未配置」与「配了但登录失败」在日志里一眼可分，不用再猜。
+//!
+//! 本模块**零网络**：只读环境变量与编译期常量，连 HTTP 客户端都不建。
+
+/// 运行期环境变量名（配 client id）。
+pub const CLIENT_ID_ENV: &str = "ULL_MSA_CLIENT_ID";
+
+/// 构建期可注入的 client id（`ULL_MSA_CLIENT_ID=<id> cargo build`）。
+pub const CLIENT_ID_BUILD: Option<&str> = option_env!("ULL_MSA_CLIENT_ID");
+
+/// 两处都没配时给用户看的那句话（CLI / GUI / 启动日志共用，**不含任何真实 id**）。
+///
+/// 措辞纪律（M117）：说「未配置」，不说「未支持」——登录链路是完整的，缺的只是这一项；
+/// 并且句子里带**可照抄的命令**，因为失败横幅往往是用户唯一会看到的那段字。
+pub const MISSING_CLIENT_ID_MESSAGE: &str =
+    "微软登录未配置：缺少 Azure 公共客户端 id（登录功能已实现，只差这一项配置）。\
+构建时注入：`ULL_MSA_CLIENT_ID=<id> cargo build`；或启动前设置同名环境变量 `ULL_MSA_CLIENT_ID=<id>`。";
+
+/// client id 从哪来（启动日志与排障用）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ClientIdSource {
+    /// 运行期环境变量 `ULL_MSA_CLIENT_ID`（**优先于**构建期注入）。
+    Env,
+    /// 构建期 `option_env!` 注入。
+    Build,
+}
+
+impl ClientIdSource {
+    /// 启动日志里的机读标签（`env` / `build`）。
+    #[must_use]
+    pub const fn tag(self) -> &'static str {
+        match self {
+            Self::Env => "env",
+            Self::Build => "build",
+        }
+    }
+}
+
+/// client id 的配置状态：配没配 + 从哪来（`None` = 两处都没有）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ClientIdStatus {
+    source: Option<ClientIdSource>,
+}
+
+impl ClientIdStatus {
+    /// 拿到 id 了没（`false` = 需要配置，不是功能缺失）。
+    #[must_use]
+    pub const fn is_configured(self) -> bool {
+        self.source.is_some()
+    }
+
+    /// 来源（`None` = 两处都没有）。
+    #[must_use]
+    pub const fn source(self) -> Option<ClientIdSource> {
+        self.source
+    }
+
+    /// 启动日志那一行：`[auth] msa client_id=configured|missing source=env|build|none`。
+    ///
+    /// 判据（M117）：日后看日志能直接分辨「未配置」与「配置了但登录失败」。
+    #[must_use]
+    pub fn log_line(self) -> String {
+        format!(
+            "[auth] msa client_id={} source={}",
+            if self.source.is_some() {
+                "configured"
+            } else {
+                "missing"
+            },
+            self.source.map_or("none", ClientIdSource::tag)
+        )
+    }
+}
+
+/// 当前进程看到的 client id 与来源（**只读环境/编译期常量，不联网**）。
+///
+/// 优先级：环境变量 > 构建期注入。两者都存在时**不告警**（M117）：环境变量就是显式覆盖，
+/// 来源如实报 [`ClientIdSource::Env`]，日志里看得到。
+#[must_use]
+pub fn resolve_client_id() -> Option<(String, ClientIdSource)> {
+    let from_env = std::env::var(CLIENT_ID_ENV)
+        .ok()
+        .filter(|value| !value.trim().is_empty());
+    let from_build = CLIENT_ID_BUILD.filter(|value| !value.trim().is_empty());
+    match (from_env, from_build) {
+        (Some(value), _) => Some((value, ClientIdSource::Env)),
+        (None, Some(value)) => Some((value.to_string(), ClientIdSource::Build)),
+        (None, None) => None,
+    }
+}
+
+/// 只问「配没配 / 从哪来」——启动日志与 GUI 启动行用它（不建 HTTP 客户端、不联网）。
+#[must_use]
+pub fn client_id_status() -> ClientIdStatus {
+    ClientIdStatus {
+        source: resolve_client_id().map(|(_, source)| source),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::sync::Mutex;
+
+    use super::{
+        client_id_status, resolve_client_id, ClientIdSource, CLIENT_ID_BUILD, CLIENT_ID_ENV,
+        MISSING_CLIENT_ID_MESSAGE,
+    };
+    use crate::auth::error::AuthError;
+    use crate::auth::microsoft::MicrosoftAuth;
+
+    /// 环境变量是**进程级**的：动它的用例必须串行，否则并行跑会互相摘/设，结论随机。
+    static ENV_LOCK: Mutex<()> = Mutex::new(());
+
+    /// 用例结束后把环境变量还原（panic 也还原：`Drop` 跑得到）。
+    struct EnvGuard {
+        saved: Option<String>,
+    }
+
+    impl EnvGuard {
+        fn clear() -> Self {
+            let saved = std::env::var(CLIENT_ID_ENV).ok();
+            std::env::remove_var(CLIENT_ID_ENV);
+            Self { saved }
+        }
+
+        fn set(value: &str) -> Self {
+            let saved = std::env::var(CLIENT_ID_ENV).ok();
+            std::env::set_var(CLIENT_ID_ENV, value);
+            Self { saved }
+        }
+    }
+
+    impl Drop for EnvGuard {
+        fn drop(&mut self) {
+            match self.saved.take() {
+                Some(value) => std::env::set_var(CLIENT_ID_ENV, value),
+                None => std::env::remove_var(CLIENT_ID_ENV),
+            }
+        }
+    }
+
+    #[test]
+    fn missing_client_id_message_says_unconfigured_not_unimplemented() {
+        // 抓得住：文案退回「本期未支持」这类说法（用户实跑到的那个 bug），
+        //         或者只说「需要 id」却不给怎么配（用户下一步就卡在这里）。
+        // 抓不住：文案好不好读——那要靠 review。
+        assert!(MISSING_CLIENT_ID_MESSAGE.contains("客户端 id"));
+        assert!(MISSING_CLIENT_ID_MESSAGE.contains("未配置"));
+        assert!(!MISSING_CLIENT_ID_MESSAGE.contains("未支持"));
+        assert!(!MISSING_CLIENT_ID_MESSAGE.contains("未实现"));
+        assert!(MISSING_CLIENT_ID_MESSAGE.contains(CLIENT_ID_ENV));
+        assert!(MISSING_CLIENT_ID_MESSAGE.contains("cargo build"));
+        // 硬约束：这句话进日志、进横幅、进错误，**示例一律是 `<id>` 占位**，不出现真 id。
+        assert!(MISSING_CLIENT_ID_MESSAGE.contains("<id>"));
+    }
+
+    #[test]
+    fn from_env_without_client_id_is_a_config_error_not_a_feature_gap() {
+        let _lock = ENV_LOCK.lock().unwrap_or_else(|error| error.into_inner());
+        let _guard = EnvGuard::clear();
+        let result = MicrosoftAuth::from_env();
+        match result {
+            Err(AuthError::Unsupported(message)) => {
+                // 机读码保持 `unsupported`（CLI `--json` 与既有调用方靠它分流），
+                // 但**人读文案**必须说「未配置」。
+                assert_eq!(message, MISSING_CLIENT_ID_MESSAGE);
+                assert!(!message.contains("未支持"));
+            }
+            // 构建期注入过 id 时唯一合法（本仓库 CI/本地都不注入，走不到这里）。
+            Ok(_) => assert!(
+                CLIENT_ID_BUILD.is_some_and(|value| !value.trim().is_empty()),
+                "没配 id 却构造成功"
+            ),
+            Err(other) => panic!("应是 Unsupported，实际 {other:?}"),
+        }
+    }
+
+    #[test]
+    fn env_client_id_wins_over_build_and_the_log_says_so() {
+        let _lock = ENV_LOCK.lock().unwrap_or_else(|error| error.into_inner());
+        let _guard = EnvGuard::set("0000-test-env-id");
+
+        let (id, source) = resolve_client_id().expect("环境变量给了 id");
+        assert_eq!(id, "0000-test-env-id");
+        // 两者都存在时环境变量优先，且**不告警**，但来源必须是 env。
+        assert_eq!(source, ClientIdSource::Env);
+
+        let status = client_id_status();
+        assert!(status.is_configured());
+        assert_eq!(status.source(), Some(ClientIdSource::Env));
+        assert_eq!(
+            status.log_line(),
+            "[auth] msa client_id=configured source=env"
+        );
+
+        // 有 id 时**不再报配置错误**：只验到「进得了登录流程的入口」为止，
+        // `from_env` 本身零网络（它只建 reqwest 客户端，不发请求）。
+        let auth = MicrosoftAuth::from_env().expect("配了 id 就该构造成功");
+        assert!(auth.endpoints().profile.contains("minecraftservices.com"));
+    }
+
+    #[test]
+    fn missing_client_id_log_line_is_machine_readable() {
+        let _lock = ENV_LOCK.lock().unwrap_or_else(|error| error.into_inner());
+        let _guard = EnvGuard::clear();
+        if CLIENT_ID_BUILD.is_some_and(|value| !value.trim().is_empty()) {
+            // 构建期注入过 id：这条没有「缺配置」可言，跳过。
+            return;
+        }
+        let status = client_id_status();
+        assert!(!status.is_configured());
+        assert_eq!(status.source(), None);
+        assert_eq!(
+            status.log_line(),
+            "[auth] msa client_id=missing source=none"
+        );
+    }
+
+    #[test]
+    fn blank_env_value_counts_as_missing() {
+        // 抓得住：`ULL_MSA_CLIENT_ID=""`（空串/全空白）被当成配好了，进而拿空 id 去联网。
+        let _lock = ENV_LOCK.lock().unwrap_or_else(|error| error.into_inner());
+        let _guard = EnvGuard::set("   ");
+        if CLIENT_ID_BUILD.is_some_and(|value| !value.trim().is_empty()) {
+            assert_eq!(
+                resolve_client_id().map(|(_, source)| source),
+                Some(ClientIdSource::Build),
+                "空白环境变量必须让位给构建期注入"
+            );
+        } else {
+            assert!(resolve_client_id().is_none());
+        }
+    }
+}
diff --git a/crates/core/src/auth/microsoft/endpoints.rs b/crates/core/src/auth/microsoft/endpoints.rs
new file mode 100644
index 0000000..bea5f1c
--- /dev/null
+++ b/crates/core/src/auth/microsoft/endpoints.rs
@@ -0,0 +1,132 @@
+//! 微软端点表：**直连**（不走镜像，承 mission Context 与 `analyse/04` §4 的端点族区分）。
+//!
+//! 两条流**共用同一个端点族**（`research/08` §2 硬性约束 1：租户只能用 `consumers`）：
+//! - 设备码流：`devicecode` + `token`；
+//! - 授权码流：`authorize`（浏览器打开）+ 同一个 `token`（`grant_type=authorization_code`）。
+//!
+//! 都走 `login.microsoftonline.com/consumers/oauth2/v2.0/*`：用 `common` 或 AAD 租户 id
+//! 拿 `XboxLive.signin` 会直接被拒（`analyse/04` §4 的「第一个坑」）。
+//!
+//! 端点集中成一张表是为了**测试可替换**：整表指向一个进程内 mock 服务器即可覆盖全链，
+//! 生产默认走 [`MicrosoftEndpoints::consumers`]。
+
+/// 微软账户 OAuth 与 Xbox / Minecraft 服务端点。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct MicrosoftEndpoints {
+    /// 设备码申请（`POST`，表单 `client_id` + `scope`）。
+    pub device_code: String,
+    /// 授权码流的授权页（`GET`，浏览器打开；`research/08` §3 方案 A）。
+    pub authorize: String,
+    /// 换 token / 刷新 token / 授权码换 token（`POST`，表单）。
+    pub token: String,
+    /// Xbox Live 用户认证（`POST` JSON）。
+    pub xbl_authenticate: String,
+    /// XSTS 授权（`POST` JSON；无 Xbox 档案时回 **401** 带 `XErr`）。
+    pub xsts_authorize: String,
+    /// `login_with_xbox`（`POST` JSON，`identityToken = "XBL3.0 x=<uhs>;<xsts>"`）。
+    pub login_with_xbox: String,
+    /// 拥有权校验 `entitlements/mcstore`（`GET`，必须 200）。
+    pub entitlements_mcstore: String,
+    /// 拥有权细分 `entitlements/license`（`GET`，`/minecraft/profile` 404 时复判用）。
+    pub entitlements_license: String,
+    /// 档案 `minecraft/profile`（`GET`，带 Bearer）。
+    pub profile: String,
+}
+
+impl MicrosoftEndpoints {
+    /// 生产端点（微软消费版账户，直连）。
+    #[must_use]
+    pub fn consumers() -> Self {
+        Self {
+            device_code: "https://login.microsoftonline.com/consumers/oauth2/v2.0/devicecode"
+                .to_string(),
+            authorize: "https://login.microsoftonline.com/consumers/oauth2/v2.0/authorize"
+                .to_string(),
+            token: "https://login.microsoftonline.com/consumers/oauth2/v2.0/token".to_string(),
+            xbl_authenticate: "https://user.auth.xboxlive.com/user/authenticate".to_string(),
+            xsts_authorize: "https://xsts.auth.xboxlive.com/xsts/authorize".to_string(),
+            login_with_xbox: "https://api.minecraftservices.com/authentication/login_with_xbox"
+                .to_string(),
+            entitlements_mcstore: "https://api.minecraftservices.com/entitlements/mcstore"
+                .to_string(),
+            entitlements_license: "https://api.minecraftservices.com/entitlements/license"
+                .to_string(),
+            profile: "https://api.minecraftservices.com/minecraft/profile".to_string(),
+        }
+    }
+
+    /// 把整表指向同一个基址（测试用；各端点用自己的路径后缀区分）。
+    #[must_use]
+    pub fn all_on(base: &str) -> Self {
+        let join = |path: &str| format!("{}/{path}", base.trim_end_matches('/'));
+        Self {
+            device_code: join("devicecode"),
+            authorize: join("authorize"),
+            token: join("token"),
+            xbl_authenticate: join("xbl"),
+            xsts_authorize: join("xsts"),
+            login_with_xbox: join("login_with_xbox"),
+            entitlements_mcstore: join("entitlements/mcstore"),
+            entitlements_license: join("entitlements/license"),
+            profile: join("profile"),
+        }
+    }
+
+    /// 所有端点（调试/诊断用）。
+    #[must_use]
+    pub fn all(&self) -> [&str; 9] {
+        [
+            &self.device_code,
+            &self.authorize,
+            &self.token,
+            &self.xbl_authenticate,
+            &self.xsts_authorize,
+            &self.login_with_xbox,
+            &self.entitlements_mcstore,
+            &self.entitlements_license,
+            &self.profile,
+        ]
+    }
+}
+
+impl Default for MicrosoftEndpoints {
+    fn default() -> Self {
+        Self::consumers()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::MicrosoftEndpoints;
+
+    #[test]
+    fn consumers_endpoints_stay_on_two_families() {
+        let endpoints = MicrosoftEndpoints::consumers();
+        assert!(endpoints.device_code.contains("login.microsoftonline.com"));
+        assert!(endpoints.token.contains("/consumers/oauth2/v2.0/token"));
+        // 授权码流的授权页与设备码流同族同租户（`research/08` §2：只能用 consumers）。
+        assert!(endpoints
+            .authorize
+            .contains("/consumers/oauth2/v2.0/authorize"));
+        assert!(endpoints
+            .xbl_authenticate
+            .contains("user.auth.xboxlive.com"));
+        assert!(endpoints.xsts_authorize.contains("xsts.auth.xboxlive.com"));
+        // 微软 OAuth 两流都不走 HMCL 的 login.live.com 端点族。
+        assert!(endpoints
+            .all()
+            .iter()
+            .all(|url| !url.contains("login.live.com")));
+    }
+
+    #[test]
+    fn all_on_keeps_paths_distinct() {
+        let endpoints = MicrosoftEndpoints::all_on("http://127.0.0.1:1234/");
+        assert_eq!(endpoints.device_code, "http://127.0.0.1:1234/devicecode");
+        assert_eq!(endpoints.authorize, "http://127.0.0.1:1234/authorize");
+        assert_eq!(
+            endpoints.entitlements_license,
+            "http://127.0.0.1:1234/entitlements/license"
+        );
+    }
+}
diff --git a/crates/core/src/auth/microsoft/flow.rs b/crates/core/src/auth/microsoft/flow.rs
new file mode 100644
index 0000000..9cc8e0f
--- /dev/null
+++ b/crates/core/src/auth/microsoft/flow.rs
@@ -0,0 +1,313 @@
+//! device-code 流：发起（拿 `user_code` + `verification_uri`）→ 轮询换 token →（刷新同构）。
+//!
+//! 逐条承 `analyse/04` §4.3 / §4.4 / §4.5：
+//! - **硬超时**：只等 `min(expires_in, 900s)`，防止后台任务永久挂起；
+//! - **`slow_down` 是流程内状态**，不是失败：轮询间隔 +5 秒继续；
+//! - **每次轮询前先 sleep**（别密集打服务端）；
+//! - **refresh 同时返回新 refresh_token**，调用方必须整体覆盖（轮换）；
+//! - 收紧 HMCL 的观察项 1：**只要 `error` 非空就失败**，不再「描述为空就静默放行」。
+//!
+//! 打印 `user_code`/URL 不在这里：core 不做 UI，宿主拿 [`DeviceCodePrompt`] 自己决定
+//! （CLI 打到 stderr，GUI 弹对话框 + 二维码）。
+
+use std::time::{Duration, Instant};
+
+use reqwest::Client;
+
+use crate::auth::error::{AuthError, AuthResult};
+use crate::auth::secret::Secret;
+
+use super::endpoints::MicrosoftEndpoints;
+use crate::auth::http::{post_form, Reply};
+
+/// 申请的 scope（`XboxLive.signin` + 长期刷新）。
+pub const SCOPE: &str = "XboxLive.signin offline_access";
+/// 设备码流程的硬上限：无论服务端给多长，最多等这么久。
+pub const DEVICE_CODE_MAX_WAIT: Duration = Duration::from_secs(900);
+/// 默认轮询间隔下限（服务端 `interval` 更小时按下限走）。
+pub const DEFAULT_MIN_INTERVAL: Duration = Duration::from_secs(1);
+/// `slow_down` 的退避步长（承 HMCL：+5 秒）。
+pub const DEFAULT_SLOW_DOWN_STEP: Duration = Duration::from_secs(5);
+/// device_code grant 类型。
+pub const DEVICE_CODE_GRANT: &str = "urn:ietf:params:oauth:grant-type:device_code";
+
+/// 轮询策略（生产用 [`PollPolicy::default`]，测试用小间隔跑同一套状态机）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct PollPolicy {
+    /// 轮询间隔下限。
+    pub min_interval: Duration,
+    /// `slow_down` 的退避步长。
+    pub slow_down_step: Duration,
+    /// 整个流程最多等多久（还会与 `expires_in` 取小）。
+    pub max_wait: Duration,
+}
+
+impl Default for PollPolicy {
+    fn default() -> Self {
+        Self {
+            min_interval: DEFAULT_MIN_INTERVAL,
+            slow_down_step: DEFAULT_SLOW_DOWN_STEP,
+            max_wait: DEVICE_CODE_MAX_WAIT,
+        }
+    }
+}
+
+/// 要展示给用户的信息（URL + 用户码）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DeviceCodePrompt {
+    /// 用户在验证页输入的短码（如 `ABCD1234`）。**不是凭据**，可打印。
+    pub user_code: String,
+    /// 验证地址（`https://www.microsoft.com/link` 等）。
+    pub verification_uri: String,
+    /// 服务端给的有效期。
+    pub expires_in: Duration,
+    /// 服务端建议的轮询间隔。
+    pub interval: Duration,
+}
+
+impl DeviceCodePrompt {
+    /// 人读两行（CLI 打到 stderr，GUI 直接展示）。
+    #[must_use]
+    pub fn lines(&self) -> (String, String) {
+        (
+            format!("请在任意设备打开 {} 并输入代码：", self.verification_uri),
+            format!(
+                "用户码 {}（{} 分钟内有效）",
+                self.user_code,
+                self.expires_in.as_secs() / 60
+            ),
+        )
+    }
+}
+
+/// 设备码申请的中间态（`device_code` 是凭据形状，不进日志）。
+#[derive(Debug, Clone)]
+pub(crate) struct DeviceCodeGrant {
+    /// 展示信息。
+    pub prompt: DeviceCodePrompt,
+    /// 轮询用的长码（脱敏 Debug，永不打印）。
+    pub device_code: Secret,
+}
+
+/// OAuth 换到的 token 对。
+#[derive(Debug, Clone)]
+pub(crate) struct OAuthTokens {
+    /// Live access token（只在链内用，不落盘）。
+    pub access_token: Secret,
+    /// Live refresh token（落盘、轮换）。
+    pub refresh_token: Secret,
+}
+
+/// 申请设备码。
+pub(crate) async fn request_device_code(
+    client: &Client,
+    endpoints: &MicrosoftEndpoints,
+    client_id: &str,
+) -> AuthResult<DeviceCodeGrant> {
+    let reply = post_form(
+        client,
+        &endpoints.device_code,
+        vec![
+            ("client_id", client_id.to_string()),
+            ("scope", SCOPE.to_string()),
+        ],
+    )
+    .await?;
+    if !reply.is_success() {
+        return Err(oauth_error(&reply, &endpoints.device_code));
+    }
+    let user_code = reply
+        .text("user_code")
+        .ok_or_else(|| AuthError::Malformed("设备码响应缺 user_code".to_string()))?;
+    let device_code = reply
+        .text("device_code")
+        .ok_or_else(|| AuthError::Malformed("设备码响应缺 device_code".to_string()))?;
+    let verification_uri = reply
+        .text("verification_uri")
+        .or_else(|| reply.text("verification_url"))
+        .ok_or_else(|| AuthError::Malformed("设备码响应缺 verification_uri".to_string()))?;
+    let expires_in = reply.number("expires_in").unwrap_or(900).max(1);
+    // 服务端间隔原样收下，下限交给 [`PollPolicy::min_interval`]（生产 1 秒，测试可压到毫秒）。
+    let interval = reply.number("interval").unwrap_or(5);
+    Ok(DeviceCodeGrant {
+        prompt: DeviceCodePrompt {
+            user_code: user_code.to_string(),
+            verification_uri: verification_uri.to_string(),
+            expires_in: Duration::from_secs(expires_in),
+            interval: Duration::from_secs(interval),
+        },
+        device_code: Secret::new(device_code),
+    })
+}
+
+/// 轮询直到用户完成授权（或超时/被拒/取消）。
+pub(crate) async fn poll_device_token(
+    client: &Client,
+    endpoints: &MicrosoftEndpoints,
+    client_id: &str,
+    grant: &DeviceCodeGrant,
+    policy: PollPolicy,
+) -> AuthResult<OAuthTokens> {
+    let limit = grant.prompt.expires_in.min(policy.max_wait);
+    let mut interval = grant.prompt.interval.max(policy.min_interval);
+    let started = Instant::now();
+    loop {
+        if started.elapsed() >= limit {
+            return Err(AuthError::Timeout {
+                what: format!("等待设备码授权（上限 {} 秒）", limit.as_secs()),
+            });
+        }
+        tokio::time::sleep(interval).await;
+        let reply = post_form(
+            client,
+            &endpoints.token,
+            vec![
+                ("client_id", client_id.to_string()),
+                ("grant_type", DEVICE_CODE_GRANT.to_string()),
+                ("code", grant.device_code.expose().to_string()),
+            ],
+        )
+        .await?;
+
+        if let Some(error) = reply.text("error") {
+            match error {
+                "authorization_pending" => continue,
+                // 服务端压力反馈：不是失败，退避后继续（承 HMCL）。
+                "slow_down" => {
+                    interval += policy.slow_down_step;
+                    continue;
+                }
+                "expired_token" => {
+                    return Err(AuthError::Timeout {
+                        what: "设备码已过期（需重新发起登录）".to_string(),
+                    })
+                }
+                "access_denied" | "authorization_declined" => return Err(AuthError::Canceled),
+                _ => return Err(oauth_error(&reply, &endpoints.token)),
+            }
+        }
+        return tokens_from(&reply, &endpoints.token);
+    }
+}
+
+/// 用 refresh_token 换新的 token 对（**刷新也会返回新 refresh_token**）。
+pub(crate) async fn refresh_tokens(
+    client: &Client,
+    endpoints: &MicrosoftEndpoints,
+    client_id: &str,
+    refresh_token: &Secret,
+) -> AuthResult<OAuthTokens> {
+    let reply = post_form(
+        client,
+        &endpoints.token,
+        vec![
+            ("client_id", client_id.to_string()),
+            ("grant_type", "refresh_token".to_string()),
+            ("refresh_token", refresh_token.expose().to_string()),
+        ],
+    )
+    .await?;
+    if let Some(error) = reply.text("error") {
+        // `invalid_grant` + `AADSTS70000` = 授权被撤销/过期 → 唯一该重新登录的信号。
+        if error == "invalid_grant" {
+            let description = reply.text("error_description").unwrap_or("");
+            if description.contains("AADSTS70000") {
+                return Err(AuthError::CredentialExpired);
+            }
+        }
+        return Err(oauth_error(&reply, &endpoints.token));
+    }
+    if !reply.is_success() {
+        return Err(oauth_error(&reply, &endpoints.token));
+    }
+    tokens_from(&reply, &endpoints.token)
+}
+
+pub(crate) fn tokens_from(reply: &Reply, url: &str) -> AuthResult<OAuthTokens> {
+    let access_token = reply
+        .text("access_token")
+        .ok_or_else(|| AuthError::Malformed(format!("{url} 响应缺 access_token")))?;
+    let refresh_token = reply
+        .text("refresh_token")
+        .ok_or_else(|| AuthError::Malformed(format!("{url} 响应缺 refresh_token")))?;
+    Ok(OAuthTokens {
+        access_token: Secret::new(access_token),
+        refresh_token: Secret::new(refresh_token),
+    })
+}
+
+/// OAuth 错误归一：**`error` 非空即失败**（HMCL 只在两个字段都非空时处理，我们收紧）。
+pub(crate) fn oauth_error(reply: &Reply, url: &str) -> AuthError {
+    let Some(code) = reply.text("error") else {
+        return AuthError::network(
+            url.split('?').next().unwrap_or(url),
+            format!("HTTP {}（响应不是 OAuth 错误体）", reply.status),
+        );
+    };
+    let description = reply
+        .text("error_description")
+        .unwrap_or("服务端未给描述")
+        .to_string();
+    if code == "invalid_grant" && description.contains("AADSTS70000") {
+        return AuthError::CredentialExpired;
+    }
+    AuthError::Denied {
+        code: code.to_string(),
+        description,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{oauth_error, PollPolicy, DEFAULT_MIN_INTERVAL, DEVICE_CODE_MAX_WAIT};
+    use crate::auth::error::AuthError;
+    use crate::auth::http::Reply;
+    use serde_json::json;
+
+    #[test]
+    fn default_policy_matches_hmcl_bounds() {
+        let policy = PollPolicy::default();
+        assert_eq!(policy.min_interval, DEFAULT_MIN_INTERVAL);
+        assert_eq!(policy.max_wait, DEVICE_CODE_MAX_WAIT);
+        assert_eq!(policy.max_wait.as_secs(), 900);
+    }
+
+    #[test]
+    fn error_without_description_still_fails() {
+        let reply = reply(400, Some(json!({ "error": "invalid_request" })));
+        match oauth_error(&reply, "https://example.invalid/token") {
+            AuthError::Denied { code, .. } => assert_eq!(code, "invalid_request"),
+            other => panic!("应是 Denied，实际 {other:?}"),
+        }
+    }
+
+    #[test]
+    fn aadsts70000_becomes_credential_expired() {
+        let reply = reply(
+            400,
+            Some(json!({
+                "error": "invalid_grant",
+                "error_description": "AADSTS70000: The grant is expired or revoked"
+            })),
+        );
+        assert!(oauth_error(&reply, "https://example.invalid/token").is_credential_expired());
+    }
+
+    #[test]
+    fn non_oauth_body_is_network_error() {
+        let reply = reply(500, None);
+        assert_eq!(
+            oauth_error(&reply, "https://example.invalid/token").code(),
+            "network"
+        );
+    }
+
+    fn reply(status: u16, body: Option<serde_json::Value>) -> Reply {
+        Reply {
+            status,
+            body,
+            content_type: Some("application/json".to_string()),
+            raw: None,
+        }
+    }
+}
diff --git a/crates/core/src/auth/microsoft/mod.rs b/crates/core/src/auth/microsoft/mod.rs
new file mode 100644
index 0000000..ec8c3af
--- /dev/null
+++ b/crates/core/src/auth/microsoft/mod.rs
@@ -0,0 +1,366 @@
+//! 微软轨：device-code 与授权码（浏览器）两条登录流 + 会话/刷新语义
+//! （`PlanDoc/07-accounts.md` §1、`analyse/04` §4–§5、`research/08` §3）。
+//!
+//! 分六块，各管一件事：
+//! - [`client_id`]：Azure 公共客户端 id 的**配置状态**（来源 / 配没配 / 启动日志那一行，零网络）；
+//! - [`session`]：`MicrosoftSession`（凭据载荷）与**刷新判定**（纯函数，可脱离网络单测）；
+//! - [`endpoints`]：端点表（生产 = 微软消费版直连；测试 = 整表指向 mock）；
+//! - [`flow`]：device-code 发起 / 轮询 / refresh（OAuth 层）；
+//! - [`authcode`] + [`callback`]：授权码流（授权 URL + 本地 HTTP 回调服务器 + code 换 token）；
+//! - [`chain`]：XBL → XSTS → login_with_xbox → entitlements → profile（Xbox/MC 层）。
+//!
+//! 两条流只差「怎么拿到 MS access_token」：拿到之后都进同一个 [`chain::complete_chain`]，
+//! 落盘/刷新也共用 [`MicrosoftSession`]，所以 GUI 账户页的两颗按钮不会长出两套凭据语义。
+//!
+//! # client id 从哪来
+//!
+//! 两条流都必须带一个**已在 Azure 注册的公共客户端 id**（且租户是 `consumers`、
+//! 重定向 URI 登记为 `http://localhost`）。HMCL 把它烘进 jar 的
+//! manifest（`hmcl.microsoft.auth.id`），我们同理：二进制里不硬编码，改由
+//! `ULL_MSA_CLIENT_ID`（运行期）或构建期 `option_env!` 提供。没有配时
+//! [`MicrosoftAuth::from_env`] 返回 [`AuthError::Unsupported`]，文案是
+//! [`client_id::MISSING_CLIENT_ID_MESSAGE`]（「未配置」+ 怎么配，见 [`client_id`]）——
+//! 这比编一个假 id 让用户看到 `invalid_client` 诚实。
+//!
+//! 措辞纪律（M117）：id 缺失是**没配置**，不是「本期未支持」。判定与那行启动日志都在
+//! [`client_id`]，本模块只消费结论。
+
+pub mod authcode;
+pub mod callback;
+pub mod chain;
+pub mod client_id;
+pub mod endpoints;
+pub mod flow;
+
+pub mod session;
+
+pub use authcode::{AuthCodePolicy, AuthCodePrompt, RedirectUri};
+pub use callback::CallbackServer;
+// client id 的判定与启动日志行留一层 re-export：调用方（CLI / GUI / 启动日志）只认
+// `auth::microsoft::*` 这一条路径，不必知道它是单独一块（M117）。
+pub use client_id::{
+    client_id_status, resolve_client_id, ClientIdSource, ClientIdStatus, CLIENT_ID_BUILD,
+    CLIENT_ID_ENV, MISSING_CLIENT_ID_MESSAGE,
+};
+pub use endpoints::MicrosoftEndpoints;
+pub use flow::{DeviceCodePrompt, PollPolicy};
+pub use session::{MicrosoftSession, RefreshDecision, RefreshReason, USER_TYPE_MSA};
+
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use reqwest::Client;
+
+use crate::auth::error::{AuthError, AuthResult};
+use crate::auth::journal::{AuthFailureEvent, AuthJournal};
+use crate::download::config::EngineConfig;
+use crate::download::http::build_client;
+
+/// 微软账户登录/刷新。
+#[derive(Debug, Clone)]
+pub struct MicrosoftAuth {
+    client: Client,
+    client_id: String,
+    endpoints: MicrosoftEndpoints,
+    poll: PollPolicy,
+    authcode: AuthCodePolicy,
+    journal: Option<AuthJournal>,
+}
+
+impl MicrosoftAuth {
+    /// 按显式 client id 构造（HTTP 基座复用 `core::download` 的客户端构造）。
+    ///
+    /// # Errors
+    ///
+    /// HTTP 客户端建不起来时返回 [`AuthError::Network`]。
+    pub fn new(client_id: impl Into<String>) -> AuthResult<Self> {
+        let client = build_client(&EngineConfig::default())
+            .map_err(|error| AuthError::network("http-client", error.to_string()))?;
+        Ok(Self {
+            client,
+            client_id: client_id.into(),
+            endpoints: MicrosoftEndpoints::consumers(),
+            poll: PollPolicy::default(),
+            authcode: AuthCodePolicy::default(),
+            journal: None,
+        })
+    }
+
+    /// 从环境/构建期取 client id（CLI 与 GUI 的默认入口）。
+    ///
+    /// 与 [`Self::new`] 的唯一差别：这条**生产入口**默认挂上便携数据根的失败日志
+    /// （`.ULL/logs/auth.jsonl`，见 [`AuthJournal::portable_default`]），
+    /// 交互式命令失败时 403 的状态码/正文摘要不会再随终端滚走。
+    ///
+    /// # Errors
+    ///
+    /// 两处都没配时返回 [`AuthError::Unsupported`]，文案是
+    /// [`MISSING_CLIENT_ID_MESSAGE`]（「未配置」+ 怎么配）。这条路径**零网络**：
+    /// id 判定在网络之前，判断失败就地早退，连 HTTP 客户端都不建。
+    pub fn from_env() -> AuthResult<Self> {
+        let Some((client_id, _source)) = resolve_client_id() else {
+            return Err(AuthError::Unsupported(
+                MISSING_CLIENT_ID_MESSAGE.to_string(),
+            ));
+        };
+        let mut auth = Self::new(client_id)?;
+        auth.journal = AuthJournal::portable_default();
+        Ok(auth)
+    }
+
+    /// 换失败日志落点（`None` = 不落盘；CI/单测用）。
+    #[must_use]
+    pub fn with_journal(mut self, journal: Option<AuthJournal>) -> Self {
+        self.journal = journal;
+        self
+    }
+
+    /// 关掉失败日志。
+    #[must_use]
+    pub fn without_journal(mut self) -> Self {
+        self.journal = None;
+        self
+    }
+
+    /// 失败日志落点（测试断言/宿主展示用）。
+    #[must_use]
+    pub fn journal(&self) -> Option<&AuthJournal> {
+        self.journal.as_ref()
+    }
+
+    /// 换 HTTP 客户端（测试注入 / 复用宿主连接池）。
+    #[must_use]
+    pub fn with_client(mut self, client: Client) -> Self {
+        self.client = client;
+        self
+    }
+
+    /// 换端点表（测试整表指向 mock 服务器）。
+    #[must_use]
+    pub fn with_endpoints(mut self, endpoints: MicrosoftEndpoints) -> Self {
+        self.endpoints = endpoints;
+        self
+    }
+
+    /// 换轮询策略（测试用小间隔）。
+    #[must_use]
+    pub fn with_poll_policy(mut self, poll: PollPolicy) -> Self {
+        self.poll = poll;
+        self
+    }
+
+    /// 换授权码流参数（回调超时 / 固定端口 / 绑定重试 / 固定 state；测试与 CLI 用）。
+    #[must_use]
+    pub fn with_authcode_policy(mut self, policy: AuthCodePolicy) -> Self {
+        self.authcode = policy;
+        self
+    }
+
+    /// 当前端点表。
+    #[must_use]
+    pub fn endpoints(&self) -> &MicrosoftEndpoints {
+        &self.endpoints
+    }
+
+    /// device-code 登录全流程。
+    ///
+    /// `present` 在拿到用户码后**立刻**被调用（CLI 打到 stderr、GUI 弹框/二维码），
+    /// 然后才开始轮询——用户有整整 `expires_in` 的时间去另一台设备上输码。
+    ///
+    /// 失败时除返回错误外，还会往失败日志（若配了）追加一条结构化记录。
+    ///
+    /// # Errors
+    ///
+    /// 网络/超时/取消/被拒/无拥有权/无档案，见 [`AuthError`]。
+    pub async fn device_code_login<F>(&self, mut present: F) -> AuthResult<MicrosoftSession>
+    where
+        F: FnMut(&DeviceCodePrompt),
+    {
+        let result = self.login_and_chain(&mut present).await;
+        if let Err(error) = &result {
+            self.record_failure("device_code_login", error);
+        }
+        result
+    }
+
+    /// 登录主体（`device_code_login` 的失败日志由外层统一记）。
+    async fn login_and_chain(
+        &self,
+        present: &mut impl FnMut(&DeviceCodePrompt),
+    ) -> AuthResult<MicrosoftSession> {
+        let grant =
+            flow::request_device_code(&self.client, &self.endpoints, &self.client_id).await?;
+        present(&grant.prompt);
+        let tokens = flow::poll_device_token(
+            &self.client,
+            &self.endpoints,
+            &self.client_id,
+            &grant,
+            self.poll,
+        )
+        .await?;
+        chain::complete_chain(&self.client, &self.endpoints, tokens, now_ms()).await
+    }
+
+    /// 授权码流登录（浏览器 + 本地回调，`research/08` §3 方案 A，GUI 的默认入口）。
+    ///
+    /// `present` 在端口绑定之后、等待回调之前被调用：宿主在这一刻拉起系统默认浏览器
+    /// （core 不做 UI，也不假设有 GUI——CLI 可以只把 URL 打到 stderr）。
+    /// 失败时与 [`Self::device_code_login`] 一样往失败日志追加一条结构化记录（M38）。
+    ///
+    /// # Errors
+    ///
+    /// 端口绑不上/网络失败、等回调超时、用户在授权页取消、OAuth 拒绝，以及整链的
+    /// [`AuthError`]（含白名单未批时 `login_with_xbox` 的 403 诊断）。
+    pub async fn authcode_login<F>(&self, present: F) -> AuthResult<MicrosoftSession>
+    where
+        F: FnOnce(&AuthCodePrompt),
+    {
+        let result = authcode::login(
+            &self.client,
+            &self.endpoints,
+            &self.client_id,
+            self.authcode.clone(),
+            present,
+        )
+        .await;
+        if let Err(error) = &result {
+            self.record_failure("authcode_login", error);
+        }
+        result
+    }
+
+    /// 刷新：Live refresh → 整链重跑（**原样覆盖 refresh_token**）。
+    ///
+    /// # Errors
+    ///
+    /// 凭据被撤销时返回 [`AuthError::CredentialExpired`]（唯一该重新交互的信号）。
+    pub async fn refresh(&self, session: &MicrosoftSession) -> AuthResult<MicrosoftSession> {
+        let result = self.refresh_and_chain(session).await;
+        if let Err(error) = &result {
+            self.record_failure("refresh", error);
+        }
+        result
+    }
+
+    /// 刷新主体（失败日志由外层统一记）。
+    async fn refresh_and_chain(&self, session: &MicrosoftSession) -> AuthResult<MicrosoftSession> {
+        let tokens = flow::refresh_tokens(
+            &self.client,
+            &self.endpoints,
+            &self.client_id,
+            &session.refresh_token,
+        )
+        .await?;
+        let refreshed =
+            chain::complete_chain(&self.client, &self.endpoints, tokens, now_ms()).await?;
+        if !session.same_profile(&refreshed) {
+            // 防「刷出来是另一个账号」（承 HMCL WrongAccountException）。
+            return Err(AuthError::Malformed(format!(
+                "刷新后档案变了（{} → {}）",
+                session.profile_id, refreshed.profile_id
+            )));
+        }
+        Ok(refreshed)
+    }
+
+    /// 尽力而为地记一条失败事件（写日志失败绝不影响登录本身的结论）。
+    fn record_failure(&self, scope: &str, error: &AuthError) {
+        if let Some(journal) = &self.journal {
+            let _ = journal.record(&AuthFailureEvent::of(scope, error));
+        }
+    }
+
+    /// 网络侧校验：`GET /minecraft/profile` 是否还认这个 token。
+    ///
+    /// 404 的二义在这里**不吞**：档案被删是真实错误，不该被当成「token 失效」静默刷新
+    /// （`analyse/04` §11 观察项 3 那个隐式约定，我们写明）。
+    ///
+    /// # Errors
+    ///
+    /// 网络失败、无拥有权、无档案等。
+    pub async fn validate(&self, session: &MicrosoftSession) -> AuthResult<bool> {
+        if session.is_expired(now_ms()) {
+            return Ok(false);
+        }
+        match chain::fetch_profile(&self.client, &self.endpoints, &session.access_token).await {
+            Ok(_) => Ok(true),
+            // 「档案被删 / 没买游戏」是真实错误，穿透上抛（别静默当成 token 失效去刷新）。
+            Err(error @ AuthError::Denied { .. }) => {
+                let fatal = matches!(
+                    &error,
+                    AuthError::Denied { code, .. } if code == "no_profile" || code == "no_license"
+                );
+                if fatal {
+                    Err(error)
+                } else {
+                    Ok(false)
+                }
+            }
+            // 链上非 2xx：拦截页（HTML/纯文本）说明网络有问题，别伪装成「token 失效」；
+            // 服务端的 JSON 拒绝 / 空体仍按「token 不被接受」处理（与 M31 语义一致）。
+            Err(error @ AuthError::Response(_)) => {
+                let interception = matches!(
+                    &error,
+                    AuthError::Response(detail) if detail.is_interception()
+                );
+                if interception {
+                    Err(error)
+                } else {
+                    Ok(false)
+                }
+            }
+            Err(other) => Err(other),
+        }
+    }
+
+    /// 需要就刷新（本地判定，不打网络），返回 `(会话, 是否刷新过)`。
+    ///
+    /// 这是 GUI/CLI 的「静默续期」入口：`Reuse` 时零网络，`Refresh` 时整链重跑。
+    ///
+    /// # Errors
+    ///
+    /// 刷新失败时原样上抛（含 [`AuthError::CredentialExpired`]）。
+    pub async fn ensure_fresh(
+        &self,
+        session: &MicrosoftSession,
+    ) -> AuthResult<(MicrosoftSession, Option<RefreshReason>)> {
+        match session.refresh_decision(now_ms()) {
+            RefreshDecision::Reuse => Ok((session.clone(), None)),
+            RefreshDecision::Refresh(reason) => {
+                let refreshed = self.refresh(session).await?;
+                Ok((refreshed, Some(reason)))
+            }
+        }
+    }
+}
+
+/// 当前 Unix 毫秒。
+#[must_use]
+pub fn now_ms() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|duration| duration.as_millis() as u64)
+        .unwrap_or(0)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{now_ms, MicrosoftAuth};
+
+    #[test]
+    fn explicit_client_id_builds() {
+        let auth = MicrosoftAuth::new("0000-test-client").expect("构造");
+        assert!(auth
+            .endpoints()
+            .profile
+            .contains("api.minecraftservices.com"));
+    }
+
+    #[test]
+    fn now_ms_is_sane() {
+        // 2020-01-01 之后、2100 之前（防止本地时钟/单位抄错）。
+        let now = now_ms();
+        assert!(now > 1_577_836_800_000);
+        assert!(now < 4_102_444_800_000);
+    }
+}
diff --git a/crates/core/src/auth/microsoft/session.rs b/crates/core/src/auth/microsoft/session.rs
new file mode 100644
index 0000000..b6df49b
--- /dev/null
+++ b/crates/core/src/auth/microsoft/session.rs
@@ -0,0 +1,231 @@
+//! 微软会话与刷新语义：**HMCL 三层判定的类型化版本**（`analyse/04` §5.3 / §3.5 / §8.4）。
+//!
+//! 三层判定原样平移：
+//! 1. `has_profile_name()`：没有玩家名就没法启动（`--username` 不能为空）；
+//! 2. `not_after`：本地时间戳过期即视为未登录（省一次网络）；
+//! 3. 进程内 `authenticated` 标记归宿主（GUI/CLI）持有，不在本类型里。
+//!
+//! 关键语义（照 HMCL，别自己发明）：
+//! - 存下来的 `refresh_token` 是 **Live（MSA）** 的，`access_token` 是 **Minecraft** 的；
+//! - 刷新 = 整条链重跑（Live refresh → XBL → XSTS → login_with_xbox → entitlements → profile），
+//!   不存在「只刷 MC token」的捷径；
+//! - `profile_name` 属于**可变的私有缓存**（2022 年后允许改名），元数据里只留不可变的 profileID。
+
+use serde::{Deserialize, Serialize};
+
+use crate::auth::error::{AuthError, AuthResult};
+use crate::auth::secret::Secret;
+use crate::launch::request::AuthPlaceholders;
+
+/// 微软账户的 launch 用户类型（`AuthInfo.USER_TYPE_MSA`）。
+pub const USER_TYPE_MSA: &str = "msa";
+
+/// 一次成功登录后的会话（= 该账户的凭据载荷）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct MicrosoftSession {
+    /// Minecraft 档案 UUID（32 位无连字符）。**不可变**。
+    pub profile_id: String,
+    /// 玩家名（可空串：磁盘恢复允许「有档案但名字未知」，登录时补齐）。
+    #[serde(default)]
+    pub profile_name: String,
+    /// MC token 类型（`Bearer`）。
+    pub token_type: String,
+    /// Minecraft access token。
+    pub access_token: Secret,
+    /// Live refresh token（轮换：每次刷新都会被新值整体覆盖）。
+    pub refresh_token: Secret,
+    /// MC token 过期时刻（Unix 毫秒；0 = 未知 → 强制刷新）。
+    pub not_after_ms: u64,
+    /// Xbox user id（`XUID`，诊断/排障用，非凭据）。
+    pub user_id: Option<String>,
+}
+
+/// 过期判定的结论。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RefreshDecision {
+    /// 本地认为可用（有玩家名且未过期）：直接复用，不打网络。
+    Reuse,
+    /// 需要整链重跑。
+    Refresh(RefreshReason),
+}
+
+/// 为什么要刷新。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RefreshReason {
+    /// 玩家名缺失（改名或历史档案）——启动参数拿不到 `--username`。
+    MissingProfileName,
+    /// 本地时间戳已过期。
+    Expired,
+    /// 名字缺失**且**过期（两条理由都成立）。
+    MissingProfileNameAndExpired,
+}
+
+impl RefreshReason {
+    /// 人读一行。
+    #[must_use]
+    pub const fn message(self) -> &'static str {
+        match self {
+            Self::MissingProfileName => "会话缺少玩家名，需要刷新",
+            Self::Expired => "Minecraft 令牌已过期，需要刷新",
+            Self::MissingProfileNameAndExpired => "会话缺少玩家名且令牌已过期，需要刷新",
+        }
+    }
+}
+
+impl MicrosoftSession {
+    /// 构造（`expires_in` 是秒，`now_ms` 是当前 Unix 毫秒）。
+    #[must_use]
+    pub fn new(
+        profile_id: impl Into<String>,
+        profile_name: impl Into<String>,
+        access_token: Secret,
+        refresh_token: Secret,
+        expires_in_secs: u64,
+        now_ms: u64,
+        user_id: Option<String>,
+    ) -> Self {
+        Self {
+            profile_id: profile_id.into(),
+            profile_name: profile_name.into(),
+            token_type: "Bearer".to_string(),
+            access_token,
+            refresh_token,
+            not_after_ms: now_ms.saturating_add(expires_in_secs.saturating_mul(1000)),
+            user_id,
+        }
+    }
+
+    /// 有没有玩家名（空串/全空白都算没有）。
+    #[must_use]
+    pub fn has_profile_name(&self) -> bool {
+        !self.profile_name.trim().is_empty()
+    }
+
+    /// 本地是否过期（`not_after_ms == 0` 视为过期，承 HMCL「坏数据强制刷新」）。
+    #[must_use]
+    pub fn is_expired(&self, now_ms: u64) -> bool {
+        self.not_after_ms == 0 || now_ms >= self.not_after_ms
+    }
+
+    /// 刷新判定（纯函数，可单测；不打网络）。
+    #[must_use]
+    pub fn refresh_decision(&self, now_ms: u64) -> RefreshDecision {
+        match (self.has_profile_name(), self.is_expired(now_ms)) {
+            (true, false) => RefreshDecision::Reuse,
+            (false, false) => RefreshDecision::Refresh(RefreshReason::MissingProfileName),
+            (true, true) => RefreshDecision::Refresh(RefreshReason::Expired),
+            (false, true) => RefreshDecision::Refresh(RefreshReason::MissingProfileNameAndExpired),
+        }
+    }
+
+    /// 该会话所有凭据值（武装脱敏器用）。
+    #[must_use]
+    pub fn secrets(&self) -> Vec<&Secret> {
+        vec![&self.access_token, &self.refresh_token]
+    }
+
+    /// 转成 launch 的占位符集合（`user_properties` 为 `{}`，承 HMCL）。
+    ///
+    /// # Errors
+    ///
+    /// 会话缺少玩家名/UUID 时返回 [`AuthError::CredentialExpired`]——此时必须刷新，
+    /// 不能拿空名字去拼命令行（`--username` 空串会导致游戏直接退出）。
+    pub fn to_placeholders(&self) -> AuthResult<AuthPlaceholders> {
+        if !self.has_profile_name() {
+            return Err(AuthError::CredentialExpired);
+        }
+        if self.profile_id.is_empty() {
+            return Err(AuthError::Malformed("会话缺少 profileID".to_string()));
+        }
+        Ok(AuthPlaceholders {
+            player_name: self.profile_name.clone(),
+            uuid: self.profile_id.clone(),
+            access_token: self.access_token.expose().to_string(),
+            user_type: USER_TYPE_MSA.to_string(),
+            user_properties: "{}".to_string(),
+        })
+    }
+
+    /// 刷新后守住两条不变量（`analyse/04` §5.3 的 `WrongAccountException` / `hasProfileName`）。
+    ///
+    /// 返回 `false` 表示「刷出来的不是同一个档案」，调用方必须当错误处理。
+    #[must_use]
+    pub fn same_profile(&self, other: &Self) -> bool {
+        self.profile_id == other.profile_id
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{MicrosoftSession, RefreshDecision, RefreshReason};
+    use crate::auth::secret::Secret;
+
+    fn session(name: &str, not_after_ms: u64) -> MicrosoftSession {
+        MicrosoftSession {
+            profile_id: "0f8fad5bd9cb469fa16570867728950e".to_string(),
+            profile_name: name.to_string(),
+            token_type: "Bearer".to_string(),
+            access_token: Secret::new("mc-token-value"),
+            refresh_token: Secret::new("live-refresh-value"),
+            not_after_ms,
+            user_id: None,
+        }
+    }
+
+    #[test]
+    fn decision_matrix() {
+        let now = 1_000_000;
+        assert_eq!(
+            session("Steve", now + 1).refresh_decision(now),
+            RefreshDecision::Reuse
+        );
+        assert_eq!(
+            session("", now + 1).refresh_decision(now),
+            RefreshDecision::Refresh(RefreshReason::MissingProfileName)
+        );
+        assert_eq!(
+            session("Steve", now - 1).refresh_decision(now),
+            RefreshDecision::Refresh(RefreshReason::Expired)
+        );
+        assert_eq!(
+            session("   ", now).refresh_decision(now),
+            RefreshDecision::Refresh(RefreshReason::MissingProfileNameAndExpired)
+        );
+    }
+
+    #[test]
+    fn zero_not_after_forces_refresh() {
+        assert_eq!(
+            session("Steve", 0).refresh_decision(5),
+            RefreshDecision::Refresh(RefreshReason::Expired)
+        );
+    }
+
+    #[test]
+    fn new_computes_not_after_from_expires_in() {
+        let built = MicrosoftSession::new(
+            "uuid",
+            "Steve",
+            Secret::new("a"),
+            Secret::new("r"),
+            86_400,
+            1_000,
+            None,
+        );
+        assert_eq!(built.not_after_ms, 1_000 + 86_400_000);
+        assert_eq!(built.token_type, "Bearer");
+    }
+
+    #[test]
+    fn placeholders_need_a_name() {
+        assert!(session("", 10).to_placeholders().is_err());
+        let placeholders = session("Steve", 10).to_placeholders().expect("占位符");
+        assert_eq!(placeholders.player_name, "Steve");
+        assert_eq!(placeholders.user_type, "msa");
+        assert_eq!(placeholders.user_properties, "{}");
+        // token 进了占位符（启动需要），但它自己的 Debug 是脱敏的。
+        assert_eq!(placeholders.access_token, "mc-token-value");
+        assert!(!format!("{:?}", session("Steve", 10)).contains("mc-token-value"));
+    }
+}
diff --git a/crates/core/src/auth/mod.rs b/crates/core/src/auth/mod.rs
new file mode 100644
index 0000000..4ba53c1
--- /dev/null
+++ b/crates/core/src/auth/mod.rs
@@ -0,0 +1,55 @@
+//! 账户体系：三轨（离线 UUID / 微软 device-code 与授权码 / authlib-injector）、凭据存储边界。
+//!
+//! 设计定稿：`DevDocs/PlanDoc/07-accounts.md`（决策 D9/Q21），协议细节来自
+//! `DevDocs/analyse/04-authentication.md`（HMCL v3.17 拆解，逐报文对照）。
+//!
+//! # 三条铁律
+//!
+//! 1. **凭据永不外泄**：token/密码不落日志、不进事件流、不打印（`AGENTS.md` §6、D4）。
+//!    类型层保证：[`Secret`] 的 `Debug`/`Display` 恒为 `<redacted>`，取明文只能 `.expose()`；
+//!    对外展示一律走元数据（[`AccountMeta`]，不含凭据）。
+//! 2. **账户操作永不 YOLO**：本模块不向 AI 暴露任何账户读写面（07 §3）；
+//!    CLI 也只开 `list / add offline / add msa / remove` 四条（authlib 密码登录走 GUI 输入框，
+//!    避免密码进 argv）。
+//! 3. **元数据 / 凭据分文件**：`data/auth/accounts.json` + `data/auth/credentials.dat`，
+//!    先写凭据后写元数据，原子写，单条坏记录只跳过不整体失败。
+//!
+//! # 公共面
+//!
+//! - [`account`]：`AccountId` / `AccountKind` / `AccountMeta` / `Credentials`（三轨统一抽象）；
+//! - [`store`]：`AccountStore`（加载/增删/落盘，`data/auth/`）；
+//! - [`offline`]：HMCL 兼容离线 UUID + 启动占位；
+//! - [`microsoft`]：微软两条登录流（device-code / 授权码+本地回调）+ 共用后链
+//!   （XBL→XSTS→login_with_xbox→entitlements→profile）+ 刷新判定；
+//! - [`authlib`]：标准 Yggdrasil 协议（authenticate/refresh/validate/invalidate，账户侧）；
+//! - [`error`]：错误分流（取消 / 超时 / 被拒 / 凭据过期）；
+//! - [`body`]：非 2xx 应答的正文诊断（分类 JSON/HTML/空体 + 脱敏摘要，M38）；
+//! - [`journal`]：认证失败事件落盘（`.ULL/logs/auth.jsonl`，M38）；
+//! - [`secret`]：凭据值包装与脱敏。
+//!
+//! # 本期不做（后续 mission）
+//!
+//! OS keychain / AES-256-GCM 凭据加密（07 §2 分级 1–2）、authlib-injector 的
+//! `-javaagent` 三件套与 jar 下载、皮肤与多角色选择、离线 UUID 的「官方风格」双模式
+//! （07 §1 升级 2，口径待定案）。接口约定见 `DevDocs/SubAgentsTalk/auth-接口约定.md`。
+
+pub mod account;
+pub mod authlib;
+pub mod body;
+pub mod error;
+pub mod http;
+pub mod journal;
+pub mod microsoft;
+pub mod offline;
+pub mod secret;
+pub mod store;
+
+pub use account::{AccountId, AccountKind, AccountMeta, Credentials};
+pub use body::{BodyKind, ResponseDetail};
+pub use error::{AuthError, AuthResult};
+pub use journal::{AuthFailureEvent, AuthJournal};
+pub use microsoft::{
+    AuthCodePolicy, AuthCodePrompt, MicrosoftAuth, MicrosoftSession, RefreshDecision, RefreshReason,
+};
+pub use secret::Secret;
+pub use store::{AccountStore, AuthPaths};
diff --git a/crates/core/src/auth/offline.rs b/crates/core/src/auth/offline.rs
new file mode 100644
index 0000000..3ab321f
--- /dev/null
+++ b/crates/core/src/auth/offline.rs
@@ -0,0 +1,197 @@
+//! 离线轨：**HMCL / Minecraft 服务端同款离线 UUID** + 启动占位字段。
+//!
+//! UUID 算法（`analyse/04` §7.1）：`UUID.nameUUIDFromBytes("OfflinePlayer:" + name)`
+//! = 对 UTF-8 字节做 MD5，再按 RFC 4122 改写成 **v3** 版本位与 **IETF 变体**位。
+//! 必须逐字节一致：离线服务器的 `ops.json` / 白名单 / 领地数据全按这个 UUID 存，
+//! 算错就对不上（皮肤、权限、存档全乱）。因此有与 JDK `UUID.nameUUIDFromBytes`
+//! 对拍的已知向量测试（见 `crates/core/tests/auth/offline_uuid.rs`）。
+//!
+//! 启动占位（`analyse/04` §7.2，承 `OfflineAccount.logInWithoutSkin`）：
+//! - `accessToken` = **每次登录随机生成的 32 位十六进制**（游戏客户端不接受空 token）；
+//! - `userType` = `msa`（HMCL 现版本如此；历史注释提过 `legacy`，但那是旧结论）；
+//! - `userProperties` = `{}`；
+//! - `uuid` 用**无连字符** 32 位形式（`--uuid` 参数要求）。
+
+use md5::{Digest, Md5};
+
+use crate::auth::account::{AccountKind, AccountMeta};
+use crate::auth::error::{AuthError, AuthResult};
+use crate::auth::secret::{random_hex32, Secret};
+use crate::launch::request::AuthPlaceholders;
+
+/// 离线 UUID 的固定前缀（改一个字节就会与所有服务端对不上）。
+pub const OFFLINE_PREFIX: &str = "OfflinePlayer:";
+/// 离线账户的 launch 用户类型（`AuthInfo.USER_TYPE_MSA`）。
+pub const OFFLINE_USER_TYPE: &str = "msa";
+/// 玩家名长度上限（MC 客户端 `--username` 的实际上限）。
+pub const MAX_NAME_CHARS: usize = 16;
+
+/// 算离线 UUID（**32 位无连字符小写十六进制**）。
+#[must_use]
+pub fn offline_uuid(name: &str) -> String {
+    let digest = Md5::digest(format!("{OFFLINE_PREFIX}{name}").as_bytes());
+    let mut bytes = [0_u8; 16];
+    bytes.copy_from_slice(&digest);
+
+    // RFC 4122 §4.3：版本位 3（MD5 based）、变体位 IETF（10xx）。
+    bytes[6] = (bytes[6] & 0x0F) | 0x30;
+    bytes[8] = (bytes[8] & 0x3F) | 0x80;
+
+    let mut hex = String::with_capacity(32);
+    for byte in bytes {
+        hex.push_str(&format!("{byte:02x}"));
+    }
+    hex
+}
+
+/// 带连字符的离线 UUID（展示/诊断用；启动参数要的是无连字符版）。
+#[must_use]
+pub fn offline_uuid_dashed(name: &str) -> String {
+    let raw = offline_uuid(name);
+    format!(
+        "{}-{}-{}-{}-{}",
+        &raw[0..8],
+        &raw[8..12],
+        &raw[12..16],
+        &raw[16..20],
+        &raw[20..32]
+    )
+}
+
+/// 校验并规范化离线玩家名。
+///
+/// 规则：非空、去掉首尾空白后 ≤16 字符、不含控制字符。
+/// **允许非 ASCII**（中文名在离线服里很常见，UUID 按 UTF-8 字节算即可）。
+///
+/// # Errors
+///
+/// 空名/过长/含控制字符时返回 [`AuthError::Malformed`]。
+pub fn normalize_name(name: &str) -> AuthResult<String> {
+    let trimmed = name.trim();
+    if trimmed.is_empty() {
+        return Err(AuthError::Malformed("玩家名不能为空".to_string()));
+    }
+    if trimmed.chars().count() > MAX_NAME_CHARS {
+        return Err(AuthError::Malformed(format!(
+            "玩家名最长 {MAX_NAME_CHARS} 个字符，收到 {} 个",
+            trimmed.chars().count()
+        )));
+    }
+    if trimmed.chars().any(char::is_control) {
+        return Err(AuthError::Malformed("玩家名不能含控制字符".to_string()));
+    }
+    Ok(trimmed.to_string())
+}
+
+/// 建一条离线账户元数据（名字已规范化）。
+///
+/// # Errors
+///
+/// 名字不合法时返回 [`AuthError::Malformed`]。
+pub fn offline_meta(name: &str, created_at_ms: u64) -> AuthResult<AccountMeta> {
+    let name = normalize_name(name)?;
+    Ok(AccountMeta::new(
+        AccountKind::Offline,
+        offline_uuid(&name),
+        name,
+        created_at_ms,
+    ))
+}
+
+/// 生成一次「登录」的启动占位（不联网、不落盘）。
+///
+/// # Errors
+///
+/// 元数据不是离线轨或名字为空时返回 [`AuthError::Malformed`] / [`AuthError::CredentialExpired`]。
+pub fn offline_login(meta: &AccountMeta) -> AuthResult<AuthPlaceholders> {
+    if meta.kind != AccountKind::Offline {
+        return Err(AuthError::Malformed(format!(
+            "账户 {} 不是离线轨（{}）",
+            meta.id,
+            meta.kind.as_str()
+        )));
+    }
+    if meta.profile_name.trim().is_empty() {
+        return Err(AuthError::CredentialExpired);
+    }
+    Ok(AuthPlaceholders {
+        player_name: meta.profile_name.clone(),
+        uuid: meta.profile_id.clone(),
+        // 随机占位：每次登录都变（与 HMCL 一致），不落盘、不进日志。
+        access_token: Secret::new(random_hex32()).expose().to_string(),
+        user_type: OFFLINE_USER_TYPE.to_string(),
+        user_properties: "{}".to_string(),
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{
+        normalize_name, offline_login, offline_meta, offline_uuid, offline_uuid_dashed,
+        OFFLINE_USER_TYPE,
+    };
+    use crate::auth::account::AccountKind;
+
+    #[test]
+    fn uuid_matches_jdk_name_uuid_from_bytes() {
+        // 向量由 JDK 25 的 UUID.nameUUIDFromBytes 生成（见 tests/auth/offline_uuid.rs 的说明）。
+        assert_eq!(
+            offline_uuid("Notch"),
+            "b50ad385829d3141a2167e7d7539ba7f".to_string()
+        );
+        assert_eq!(
+            offline_uuid_dashed("Notch"),
+            "b50ad385-829d-3141-a216-7e7d7539ba7f"
+        );
+    }
+
+    #[test]
+    fn uuid_has_v3_and_ietf_bits() {
+        let raw = offline_uuid("AnyPlayer");
+        let version = u8::from_str_radix(&raw[12..13], 16).expect("版本位");
+        assert_eq!(version, 3, "必须标记为 v3（MD5）");
+        let variant = u8::from_str_radix(&raw[16..17], 16).expect("变体位");
+        assert!(
+            (0x8..=0xb).contains(&variant),
+            "变体位必须是 IETF（10xx），实际 {variant:x}"
+        );
+    }
+
+    #[test]
+    fn uuid_is_stable_and_case_sensitive() {
+        assert_eq!(offline_uuid("Steve"), offline_uuid("Steve"));
+        assert_ne!(offline_uuid("Steve"), offline_uuid("steve"));
+    }
+
+    #[test]
+    fn name_validation() {
+        assert_eq!(normalize_name("  Steve  ").expect("合法"), "Steve");
+        assert_eq!(normalize_name("小明").expect("中文合法"), "小明");
+        assert!(normalize_name("   ").is_err());
+        assert!(normalize_name("0123456789abcdefg").is_err());
+        assert!(normalize_name("bad\u{7}name").is_err());
+    }
+
+    #[test]
+    fn offline_meta_and_login_shape() {
+        let meta = offline_meta("小明", 1_000).expect("建元数据");
+        assert_eq!(meta.kind, AccountKind::Offline);
+        assert_eq!(meta.profile_id, offline_uuid("小明"));
+        let placeholders = offline_login(&meta).expect("占位符");
+        assert_eq!(placeholders.player_name, "小明");
+        assert_eq!(placeholders.uuid, offline_uuid("小明"));
+        assert_eq!(placeholders.user_type, OFFLINE_USER_TYPE);
+        assert_eq!(placeholders.user_properties, "{}");
+        assert_eq!(placeholders.access_token.len(), 32);
+        // 每次登录的占位 token 都不同（HMCL 行为）。
+        let again = offline_login(&meta).expect("占位符");
+        assert_ne!(placeholders.access_token, again.access_token);
+    }
+
+    #[test]
+    fn offline_login_rejects_other_tracks() {
+        let mut meta = offline_meta("Steve", 1).expect("建元数据");
+        meta.kind = AccountKind::Microsoft;
+        assert!(offline_login(&meta).is_err());
+    }
+}
diff --git a/crates/core/src/auth/secret.rs b/crates/core/src/auth/secret.rs
new file mode 100644
index 0000000..8296db4
--- /dev/null
+++ b/crates/core/src/auth/secret.rs
@@ -0,0 +1,182 @@
+//! 凭据值包装：**打印出来永远是 `<redacted>`**。
+//!
+//! 依据 `DevDocs/PlanDoc/07-accounts.md` §3 与 `DevDocs/AGENTS.md` §6 的凭据红线：
+//! token/密码永不进日志、事件流、stdout、测试快照。HMCL 靠「往日志过滤器注册 token」
+//! （`analyse/04` §11 观察项 9：绕开 Logger 就失效），我们在**类型层**堵：
+//! 只要某值被包成 [`Secret`]，`Debug`/`Display`/`{:?}`/`{}` 都拿不到明文，
+//! 取明文必须显式写 `.expose()`（一眼可搜、CR 可审）。
+//!
+//! 落盘仍然需要明文（凭据文件），因此保留 serde 透明序列化——序列化不是打印。
+
+use std::borrow::Cow;
+use std::fmt;
+
+use serde::{Deserialize, Serialize};
+
+use crate::launch::redact::{Redactor, TOKEN_PLACEHOLDER};
+
+/// `Debug`/`Display` 与脱敏替换的统一标记。
+pub const REDACTED: &str = "<redacted>";
+
+/// 一个凭据值（access token / refresh token / client token / 密码）。
+///
+/// 相等性按明文比较（刷新后判断「token 有没有变」要用到），哈希同理。
+#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(transparent)]
+pub struct Secret(String);
+
+impl Secret {
+    /// 包住一个明文值。
+    pub fn new(value: impl Into<String>) -> Self {
+        Self(value.into())
+    }
+
+    /// 取明文。**唯一取明文入口**：出现处都应能说清「这是发请求，不是打印」。
+    #[must_use]
+    pub fn expose(&self) -> &str {
+        &self.0
+    }
+
+    /// 是否为空（空 token 等价于「没有凭据」）。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.0.is_empty()
+    }
+
+    /// 明文字节长度（判空/判占位长度用，不泄露内容）。
+    #[must_use]
+    pub fn len(&self) -> usize {
+        self.0.len()
+    }
+}
+
+impl fmt::Debug for Secret {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str(REDACTED)
+    }
+}
+
+impl fmt::Display for Secret {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str(REDACTED)
+    }
+}
+
+impl From<String> for Secret {
+    fn from(value: String) -> Self {
+        Self(value)
+    }
+}
+
+impl From<&str> for Secret {
+    fn from(value: &str) -> Self {
+        Self(value.to_string())
+    }
+}
+
+/// 生成 32 个十六进制字符的随机串（离线 accessToken 占位、条目 id）。
+///
+/// **不是密码学随机**（同 `game::ProfileId::generate` 的取舍）：混合纳秒时间戳、进程 id、
+/// 进程内计数器后过 SplitMix64。这些值不参与任何服务端校验（HMCL 同样用
+/// `UUID.randomUUID().toString()` 的紧凑形式当占位），唯一性够用即可。
+#[must_use]
+pub fn random_hex32() -> String {
+    use std::sync::atomic::{AtomicU64, Ordering};
+
+    static COUNTER: AtomicU64 = AtomicU64::new(0);
+
+    let nanos = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map_or(0, |duration| duration.as_nanos() as u64);
+    let seq = COUNTER.fetch_add(1, Ordering::Relaxed);
+    let mut seed = nanos ^ u64::from(std::process::id()).rotate_left(17) ^ seq.rotate_left(41);
+
+    let mut out = String::with_capacity(32);
+    let mut state = seed;
+    while out.len() < 32 {
+        // 两个 u64 混合出 16 个 hex 字符一轮。
+        state = split_mix64(state);
+        seed ^= split_mix64(seed.rotate_left(29) ^ state);
+        out.push_str(&format!("{:016x}", seed));
+    }
+    out.truncate(32);
+    out
+}
+
+fn split_mix64(seed: u64) -> u64 {
+    let mut z = seed.wrapping_add(0x9E37_79B9_7F4A_7C15);
+    z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
+    z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
+    z ^ (z >> 31)
+}
+
+/// 用一组凭据武装一个日志脱敏器（`launch::redact::Redactor` 的唯一构造入口）。
+///
+/// 太短的值（< 6 字节）会被 `Redactor` 自动忽略，避免把正常文本搅乱。
+#[must_use]
+pub fn redactor_for<'a>(secrets: impl IntoIterator<Item = &'a Secret>) -> Redactor {
+    let mut redactor = Redactor::new();
+    for secret in secrets {
+        if !secret.is_empty() {
+            redactor = redactor.with_secret(secret.expose().to_string());
+        }
+    }
+    redactor
+}
+
+/// 对一段文本做凭据脱敏（走 `launch::redact` 的三条规则：已登记凭据、长度 ≥64 不透明串、
+/// 带点 token/JWT）。
+#[must_use]
+pub fn scrub<'a>(text: &'a str, secrets: &[&Secret]) -> Cow<'a, str> {
+    let owned: Vec<Secret> = secrets.iter().map(|secret| (*secret).clone()).collect();
+    redactor_for(owned.iter()).scrub(text)
+}
+
+/// 占位常量转出（给调用方断言 / 拼提示用）。
+#[must_use]
+pub const fn token_placeholder() -> &'static str {
+    TOKEN_PLACEHOLDER
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{random_hex32, scrub, Secret, REDACTED, TOKEN_PLACEHOLDER};
+
+    #[test]
+    fn debug_and_display_never_leak() {
+        let secret = Secret::new("SUPER-SECRET-TOKEN-VALUE");
+        assert_eq!(format!("{secret:?}"), REDACTED);
+        assert_eq!(format!("{secret}"), REDACTED);
+        assert!(!format!("{secret:?}").contains("SUPER"));
+        let bundle = format!("{:?}", vec![secret.clone()]);
+        assert!(!bundle.contains("SECRET"), "{bundle}");
+        assert_eq!(secret.expose(), "SUPER-SECRET-TOKEN-VALUE");
+    }
+
+    #[test]
+    fn serde_roundtrip_keeps_plaintext() {
+        let secret = Secret::new("abc123");
+        let text = serde_json::to_string(&secret).expect("序列化");
+        assert_eq!(text, "\"abc123\"");
+        let back: Secret = serde_json::from_str(&text).expect("反序列化");
+        assert_eq!(back, secret);
+    }
+
+    #[test]
+    fn scrub_replaces_registered_secret() {
+        let secret = Secret::new("0f8fad5bd9cb469fa16570867728950e");
+        let text = format!("--accessToken {} --uuid abc", secret.expose());
+        let scrubbed = scrub(&text, &[&secret]).into_owned();
+        assert!(!scrubbed.contains("0f8fad"));
+        assert!(scrubbed.contains(TOKEN_PLACEHOLDER));
+    }
+
+    #[test]
+    fn random_hex32_is_32_hex_and_unique() {
+        let first = random_hex32();
+        let second = random_hex32();
+        assert_eq!(first.len(), 32);
+        assert!(first.chars().all(|ch| ch.is_ascii_hexdigit()));
+        assert_ne!(first, second);
+    }
+}
diff --git a/crates/core/src/auth/store.rs b/crates/core/src/auth/store.rs
new file mode 100644
index 0000000..0021b24
--- /dev/null
+++ b/crates/core/src/auth/store.rs
@@ -0,0 +1,251 @@
+//! 账户存储：`data/auth/` 下的**元数据 / 凭据分文件**落盘（内存视图与增删）。
+//!
+//! 契约（`PlanDoc/07-accounts.md` §2、`PlanDoc/04-data-and-config.md`）：
+//! 1. **分文件**：`accounts.json`（可公开）+ `credentials.dat`（凭据）。列账户不碰凭据文件；
+//! 2. **先写凭据、再写元数据**（HMCL 安全顺序）——元数据永不指向不存在的凭据；
+//! 3. **原子写**：走 `platform::atomic::write_atomic`（tmp → fsync → rename）；
+//! 4. **容错**：单条坏记录只跳过该条并留 warning，绝不整体加载失败；
+//! 5. **孤儿清理**：`save()` 只写「元数据里还存在」的凭据。
+//!
+//! 落盘细节（payload 形状、权限收紧）在同目录的 [`payload`] 子模块，本文件只管模型与不变量。
+//!
+//! 保护级别：本期 `plain-v1`（分文件 + 权限 + 全链脱敏）。OS keychain / AES-256-GCM
+//! 分级是 07 §2 的第 1–2 条，需要 keyring/aes-gcm/argon2 的依赖决策，属后续 mission。
+
+mod payload;
+
+use std::collections::BTreeMap;
+use std::path::{Path, PathBuf};
+
+use crate::auth::account::{AccountId, AccountMeta, Credentials};
+use crate::auth::error::{AuthError, AuthResult};
+
+/// 元数据文件名（`data/auth/accounts.json`）。
+pub const ACCOUNTS_FILE: &str = "accounts.json";
+/// 凭据文件名（`data/auth/credentials.dat`）。
+pub const CREDENTIALS_FILE: &str = "credentials.dat";
+/// 元数据 schema 版本。
+pub const AUTH_SCHEMA_VERSION: u32 = 1;
+/// 本期凭据保护级别（明文 + 分文件 + 权限 + 脱敏）。
+pub const PROTECTION_PLAIN_V1: &str = "plain-v1";
+
+/// `data/auth/` 的两个文件位置。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AuthPaths {
+    root: PathBuf,
+}
+
+impl AuthPaths {
+    /// 以数据分区为根（`LauncherLayout::auth_data()`）。
+    #[must_use]
+    pub fn new(root: impl Into<PathBuf>) -> Self {
+        Self { root: root.into() }
+    }
+
+    /// 根目录。
+    #[must_use]
+    pub fn root(&self) -> &Path {
+        &self.root
+    }
+
+    /// 元数据文件。
+    #[must_use]
+    pub fn accounts_file(&self) -> PathBuf {
+        self.root.join(ACCOUNTS_FILE)
+    }
+
+    /// 凭据文件。
+    #[must_use]
+    pub fn credentials_file(&self) -> PathBuf {
+        self.root.join(CREDENTIALS_FILE)
+    }
+}
+
+/// 账户库（内存视图 + 落盘）。
+#[derive(Debug, Clone)]
+pub struct AccountStore {
+    paths: AuthPaths,
+    accounts: Vec<AccountMeta>,
+    credentials: BTreeMap<String, Credentials>,
+    warnings: Vec<String>,
+}
+
+impl AccountStore {
+    /// 打开（不存在就是空库；坏记录进 warnings）。
+    #[must_use]
+    pub fn open(root: impl Into<PathBuf>) -> Self {
+        Self::open_paths(AuthPaths::new(root))
+    }
+
+    /// 打开指定文件位置。
+    #[must_use]
+    pub fn open_paths(paths: AuthPaths) -> Self {
+        let mut warnings = Vec::new();
+        let mut accounts = payload::read_accounts(&paths.accounts_file(), &mut warnings);
+        accounts.sort_by_key(|meta| meta.created_at_ms);
+        let known: Vec<String> = accounts
+            .iter()
+            .map(|meta| meta.id.as_str().to_string())
+            .collect();
+        let credentials =
+            payload::read_credentials(&paths.credentials_file(), &known, &mut warnings);
+        Self {
+            paths,
+            accounts,
+            credentials,
+            warnings,
+        }
+    }
+
+    /// 文件位置。
+    #[must_use]
+    pub fn paths(&self) -> &AuthPaths {
+        &self.paths
+    }
+
+    /// 账户列表（按创建时间排序，展示顺序稳定）。
+    #[must_use]
+    pub fn accounts(&self) -> &[AccountMeta] {
+        &self.accounts
+    }
+
+    /// 加载过程中的告警（坏记录、孤儿凭据等）。
+    #[must_use]
+    pub fn warnings(&self) -> &[String] {
+        &self.warnings
+    }
+
+    /// 是否没有任何账户。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.accounts.is_empty()
+    }
+
+    /// 按名字 / 登录名 / 条目 id 查找（大小写不敏感）。
+    #[must_use]
+    pub fn find(&self, key: &str) -> Option<&AccountMeta> {
+        self.accounts.iter().find(|meta| meta.matches(key))
+    }
+
+    /// 取某条目的凭据。
+    #[must_use]
+    pub fn credentials(&self, id: &AccountId) -> Option<&Credentials> {
+        self.credentials.get(id.as_str())
+    }
+
+    /// 取某条目的「元数据 + 凭据」（找不到凭据时报错）。
+    ///
+    /// # Errors
+    ///
+    /// 条目不存在 → [`AuthError::NotFound`]；条目在但凭据缺失 → [`AuthError::Malformed`]
+    /// （说明文件被手工删过，别静默当成「没登录」）。
+    pub fn entry(&self, id: &AccountId) -> AuthResult<(&AccountMeta, &Credentials)> {
+        let meta = self
+            .accounts
+            .iter()
+            .find(|meta| meta.id == *id)
+            .ok_or_else(|| AuthError::NotFound {
+                account: id.to_string(),
+            })?;
+        let credentials = self
+            .credentials
+            .get(id.as_str())
+            .ok_or_else(|| AuthError::Malformed(format!("账户 {id} 的凭据缺失")))?;
+        Ok((meta, credentials))
+    }
+
+    /// 新增账户（内存）。同名同轨冲突时报错——`--account <名字>` 才有唯一解。
+    ///
+    /// # Errors
+    ///
+    /// 重复、条目 id 重复、轨道与凭据不符都返回错误。
+    pub fn insert(&mut self, meta: AccountMeta, credentials: Credentials) -> AuthResult<()> {
+        meta.check_credentials(&credentials)?;
+        if self.accounts.iter().any(|existing| existing.id == meta.id) {
+            return Err(AuthError::Conflict {
+                account: meta.id.to_string(),
+            });
+        }
+        let duplicate = self
+            .accounts
+            .iter()
+            .any(|existing| existing.kind == meta.kind && existing.matches(meta.display_name()));
+        if duplicate {
+            return Err(AuthError::Conflict {
+                account: meta.display_name().to_string(),
+            });
+        }
+        self.credentials
+            .insert(meta.id.as_str().to_string(), credentials);
+        self.accounts.push(meta);
+        self.accounts.sort_by_key(|meta| meta.created_at_ms);
+        Ok(())
+    }
+
+    /// 删除账户（连同凭据）。
+    ///
+    /// # Errors
+    ///
+    /// 找不到时返回 [`AuthError::NotFound`]。
+    pub fn remove(&mut self, key: &str) -> AuthResult<AccountMeta> {
+        let index = self
+            .accounts
+            .iter()
+            .position(|meta| meta.matches(key))
+            .ok_or_else(|| AuthError::NotFound {
+                account: key.to_string(),
+            })?;
+        let meta = self.accounts.remove(index);
+        self.credentials.remove(meta.id.as_str());
+        Ok(meta)
+    }
+
+    /// 更新某条目的凭据（刷新后轮换 token 用）。
+    ///
+    /// # Errors
+    ///
+    /// 条目不存在或轨道不符时返回错误。
+    pub fn update_credentials(
+        &mut self,
+        id: &AccountId,
+        credentials: Credentials,
+    ) -> AuthResult<()> {
+        let meta = self
+            .accounts
+            .iter()
+            .find(|meta| meta.id == *id)
+            .ok_or_else(|| AuthError::NotFound {
+                account: id.to_string(),
+            })?;
+        meta.check_credentials(&credentials)?;
+        self.credentials
+            .insert(id.as_str().to_string(), credentials);
+        Ok(())
+    }
+
+    /// 同步某条目的元数据字段（刷新补齐了玩家名之后写回）。
+    ///
+    /// # Errors
+    ///
+    /// 条目不存在时返回 [`AuthError::NotFound`]。
+    pub fn update_meta(&mut self, meta: AccountMeta) -> AuthResult<()> {
+        let slot = self
+            .accounts
+            .iter_mut()
+            .find(|existing| existing.id == meta.id)
+            .ok_or_else(|| AuthError::NotFound {
+                account: meta.id.to_string(),
+            })?;
+        *slot = meta;
+        Ok(())
+    }
+
+    /// 落盘：**先凭据、后元数据**。
+    ///
+    /// # Errors
+    ///
+    /// 两个文件任一写失败都返回 [`AuthError::Store`]。
+    pub fn save(&self) -> AuthResult<()> {
+        payload::write(&self.paths, &self.accounts, &self.credentials)
+    }
+}
diff --git a/crates/core/src/auth/store/payload.rs b/crates/core/src/auth/store/payload.rs
new file mode 100644
index 0000000..b070278
--- /dev/null
+++ b/crates/core/src/auth/store/payload.rs
@@ -0,0 +1,247 @@
+//! 落盘细节：payload 形状、宽容解析、凭据文件权限。
+//!
+//! 两个文件的形状（都带 `schemaVersion`，便于以后演进）：
+//!
+//! ```json
+//! // accounts.json —— 可公开
+//! { "schemaVersion": 1, "accounts": [ { "id": "account:…", "kind": "offline",
+//!   "profileId": "…", "profileName": "Steve", "createdAtMs": 1700000000000 } ] }
+//!
+//! // credentials.dat —— 凭据
+//! { "schemaVersion": 1, "protection": "plain-v1",
+//!   "entries": [ { "accountId": "account:…", "data": { "kind": "microsoft", … } } ] }
+//! ```
+//!
+//! `entries[].data` 里是 [`Credentials`] 的序列化结果（由 serde 自己定义形状），
+//! 本模块只负责「哪条属于哪个账户」。
+
+use std::collections::BTreeMap;
+use std::path::Path;
+
+use serde_json::{json, Value};
+
+use crate::auth::account::{AccountMeta, Credentials};
+use crate::auth::error::{AuthError, AuthResult};
+use crate::platform::atomic::write_atomic;
+
+use super::{AuthPaths, AUTH_SCHEMA_VERSION, PROTECTION_PLAIN_V1};
+
+/// 写两处文件：**先凭据、后元数据**。
+pub(super) fn write(
+    paths: &AuthPaths,
+    accounts: &[AccountMeta],
+    credentials: &BTreeMap<String, Credentials>,
+) -> AuthResult<()> {
+    let credentials_payload = credentials_payload(accounts, credentials);
+    let path = paths.credentials_file();
+    write_atomic(&path, credentials_payload.as_bytes())
+        .map_err(|error| AuthError::store(path.display(), error.to_string()))?;
+    restrict(&path)?;
+
+    let accounts_payload = accounts_payload(accounts);
+    let path = paths.accounts_file();
+    write_atomic(&path, accounts_payload.as_bytes())
+        .map_err(|error| AuthError::store(path.display(), error.to_string()))?;
+    Ok(())
+}
+
+fn credentials_payload(
+    accounts: &[AccountMeta],
+    credentials: &BTreeMap<String, Credentials>,
+) -> String {
+    let mut entries = Vec::new();
+    for meta in accounts {
+        // 孤儿凭据（元数据已删）不写回。
+        let Some(data) = credentials.get(meta.id.as_str()) else {
+            continue;
+        };
+        entries.push(json!({
+            "accountId": meta.id.as_str(),
+            "data": data,
+        }));
+    }
+    let payload = json!({
+        "schemaVersion": AUTH_SCHEMA_VERSION,
+        "protection": PROTECTION_PLAIN_V1,
+        "entries": entries,
+    });
+    serde_json::to_string_pretty(&payload).unwrap_or_else(|_| "{}".to_string())
+}
+
+fn accounts_payload(accounts: &[AccountMeta]) -> String {
+    let payload = json!({
+        "schemaVersion": AUTH_SCHEMA_VERSION,
+        "accounts": accounts,
+    });
+    serde_json::to_string_pretty(&payload).unwrap_or_else(|_| "{}".to_string())
+}
+
+/// 读元数据（坏记录跳过并记 warning）。
+pub(super) fn read_accounts(path: &Path, warnings: &mut Vec<String>) -> Vec<AccountMeta> {
+    let mut accounts = Vec::new();
+    let Some(text) = read_to_string(path, warnings) else {
+        return accounts;
+    };
+    let Ok(value) = serde_json::from_str::<Value>(&text) else {
+        warnings.push(format!("{} 不是合法 JSON，按空账户库处理", path.display()));
+        return accounts;
+    };
+    let Some(items) = value.get("accounts").and_then(Value::as_array) else {
+        warnings.push(format!("{} 缺 accounts 数组", path.display()));
+        return accounts;
+    };
+    for item in items {
+        match AccountMeta::from_value(item) {
+            Ok(meta) => accounts.push(meta),
+            Err(error) => warnings.push(format!("跳过一条账户元数据：{}", error.message())),
+        }
+    }
+    accounts
+}
+
+/// 读凭据（只保留 `known` 里存在的账户，孤儿丢弃并记 warning）。
+pub(super) fn read_credentials(
+    path: &Path,
+    known: &[String],
+    warnings: &mut Vec<String>,
+) -> BTreeMap<String, Credentials> {
+    let mut credentials = BTreeMap::new();
+    let Some(text) = read_to_string(path, warnings) else {
+        return credentials;
+    };
+    let Ok(value) = serde_json::from_str::<Value>(&text) else {
+        warnings.push(format!(
+            "{} 不是合法 JSON，按「无凭据」处理（账户列表仍可用）",
+            path.display()
+        ));
+        return credentials;
+    };
+    if let Some(protection) = value.get("protection").and_then(Value::as_str) {
+        if protection != PROTECTION_PLAIN_V1 {
+            warnings.push(format!(
+                "{} 的保护级别是 `{protection}`，本期只认 `{PROTECTION_PLAIN_V1}`",
+                path.display()
+            ));
+        }
+    }
+    let Some(entries) = value.get("entries").and_then(Value::as_array) else {
+        return credentials;
+    };
+    for entry in entries {
+        let Some(account_id) = entry.get("accountId").and_then(Value::as_str) else {
+            continue;
+        };
+        let account_id = account_id.to_ascii_lowercase();
+        if !known.contains(&account_id) {
+            warnings.push(format!("凭据 {account_id} 没有对应账户，已忽略"));
+            continue;
+        }
+        let Some(data) = entry.get("data") else {
+            continue;
+        };
+        match serde_json::from_value::<Credentials>(data.clone()) {
+            Ok(parsed) => {
+                credentials.insert(account_id, parsed);
+            }
+            Err(error) => warnings.push(format!("跳过一条凭据（{account_id}）：{error}")),
+        }
+    }
+    credentials
+}
+
+fn read_to_string(path: &Path, warnings: &mut Vec<String>) -> Option<String> {
+    match std::fs::read_to_string(path) {
+        Ok(text) => Some(text),
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => None,
+        Err(error) => {
+            warnings.push(format!("读 {} 失败：{error}", path.display()));
+            None
+        }
+    }
+}
+
+/// 把凭据文件收紧到「仅本人可读写」。
+///
+/// POSIX 侧显式 `0600`；Windows 侧 `set_permissions` 只能表达只读位，凭据保护依赖
+/// 用户目录默认 ACL（`data/auth/` 位于用户数据根下）。**这是已知缺口**：
+/// 补一个 `platform::atomic::write_atomic_private` 比在 auth 里散写 cfg 更对，
+/// 已作为 finding 报给 tower（见完成报告）。
+fn restrict(path: &Path) -> AuthResult<()> {
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        let permissions = std::fs::Permissions::from_mode(0o600);
+        std::fs::set_permissions(path, permissions)
+            .map_err(|error| AuthError::store(path.display(), error.to_string()))?;
+    }
+    #[cfg(not(unix))]
+    {
+        let _ = path;
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use std::collections::BTreeMap;
+
+    use super::{accounts_payload, credentials_payload};
+    use crate::auth::account::{AccountKind, AccountMeta, Credentials};
+    use crate::auth::microsoft::MicrosoftSession;
+    use crate::auth::secret::Secret;
+
+    fn microsoft_meta() -> (AccountMeta, Credentials) {
+        let meta = AccountMeta::new(
+            AccountKind::Microsoft,
+            "0f8fad5bd9cb469fa16570867728950e",
+            "Steve",
+            7,
+        );
+        let session = MicrosoftSession::new(
+            "0f8fad5bd9cb469fa16570867728950e",
+            "Steve",
+            Secret::new("mc-access-token"),
+            Secret::new("live-refresh-token"),
+            3600,
+            1_000,
+            None,
+        );
+        (meta, Credentials::Microsoft(session))
+    }
+
+    #[test]
+    fn metadata_payload_never_contains_tokens() {
+        let (meta, creds) = microsoft_meta();
+        let payload = accounts_payload(std::slice::from_ref(&meta));
+        assert!(payload.contains("0f8fad5bd9cb469fa16570867728950e"));
+        assert!(payload.contains("\"kind\": \"microsoft\""));
+        assert!(!payload.contains("mc-access-token"));
+        assert!(!payload.contains("live-refresh-token"));
+        // 凭据对象的 Debug 也是脱敏的，别把 token 带进 payload。
+        assert!(!format!("{creds:?}").contains("mc-access-token"));
+    }
+
+    #[test]
+    fn credentials_payload_carries_protection_and_entries() {
+        let (meta, creds) = microsoft_meta();
+        let mut map = BTreeMap::new();
+        map.insert(meta.id.as_str().to_string(), creds);
+        let payload = credentials_payload(std::slice::from_ref(&meta), &map);
+        assert!(payload.contains("\"protection\": \"plain-v1\""));
+        assert!(payload.contains(meta.id.as_str()));
+        assert!(payload.contains("mc-access-token"));
+    }
+
+    #[test]
+    fn orphan_credentials_are_not_written() {
+        let (meta, creds) = microsoft_meta();
+        let mut map = BTreeMap::new();
+        map.insert(
+            "account:deadbeefdeadbeefdeadbeefdeadbeef".to_string(),
+            creds,
+        );
+        let payload = credentials_payload(std::slice::from_ref(&meta), &map);
+        assert!(!payload.contains("mc-access-token"));
+        assert!(payload.contains("\"entries\": []"));
+    }
+}
diff --git a/crates/core/src/diagnose/collectors.rs b/crates/core/src/diagnose/collectors.rs
new file mode 100644
index 0000000..d418031
--- /dev/null
+++ b/crates/core/src/diagnose/collectors.rs
@@ -0,0 +1,267 @@
+//! 五类信号采集接口：退出码 / 日志环形缓冲 / crash-reports / hs_err / 环境快照（+ mod 清单）。
+//!
+//! 分工（与 `launch-接口约定.md` 对齐）：
+//! - **推送类**（[`ExitCollector`] / [`EnvironmentCollector`]）：launch 已经算出事实，直接塞进 [`SignalBundle`]；
+//! - **磁盘类**（[`CrashReportCollector`] / [`HsErrCollector`] / [`LatestLogCollector`]）：本模块自己按
+//!   mtime 取最新一份，并可用 [`CollectionContext::started_at`] 过滤历史崩溃；
+//! - 日志行由 launch 逐行喂 [`LogBuffer::push`]，diagnose 不解析会话 JSONL（两边零类型耦合）。
+//!
+//! 采集是**尽力而为**：[`collect_all`] 把单个来源的失败收集成 [`CollectError`] 而不是中断整体——
+//! 崩溃现场本来就残缺，少一个来源不该失去全部结论。
+
+use std::fmt;
+use std::io;
+use std::path::{Path, PathBuf};
+use std::time::SystemTime;
+
+#[path = "environment.rs"]
+pub mod environment;
+#[path = "signals.rs"]
+pub mod signals;
+#[path = "sources.rs"]
+pub mod sources;
+
+pub use environment::{ComponentVersion, EnvironmentSnapshot, ModRecord};
+pub use signals::{
+    ExitSignal, ExitType, LogBuffer, LogLine, SignalOrigin, CRASH_KEYWORDS, EXIT_ACCESS_VIOLATION,
+    EXIT_DLL_NOT_FOUND, EXIT_SIGKILL, EXIT_SIGTERM, EXIT_STACK_BUFFER_OVERRUN, JVM_ERROR_KEYWORDS,
+};
+pub use sources::{
+    CrashReportCollector, EnvironmentCollector, ExitCollector, HsErrCollector, LatestLogCollector,
+};
+
+use super::engine::DiagnosisInput;
+use super::hs_err::HsErrReport;
+
+/// 信号种类（可观测性 / 采集计划编排用）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub enum SignalKind {
+    /// 退出码 + 退出类型。
+    Exit,
+    /// stdout/stderr 环形缓冲。
+    Log,
+    /// `crash-reports/crash-*.txt`。
+    CrashReport,
+    /// `hs_err_pid*.log`。
+    HsErr,
+    /// 环境快照。
+    Environment,
+    /// mod 清单。
+    Mods,
+}
+
+impl SignalKind {
+    /// 稳定字符串。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Exit => "exit",
+            Self::Log => "log",
+            Self::CrashReport => "crash_report",
+            Self::HsErr => "hs_err",
+            Self::Environment => "environment",
+            Self::Mods => "mods",
+        }
+    }
+}
+
+/// 采集上下文。
+#[derive(Debug, Clone, Default)]
+pub struct CollectionContext {
+    /// 游戏工作目录（`crash-reports/`、`hs_err_pid*.log`、`logs/latest.log` 都在它下面）。
+    pub run_dir: PathBuf,
+    /// 进程启动时刻：只采集修改时间 ≥ 它的文件，避免把上次崩溃算进本次。
+    pub started_at: Option<SystemTime>,
+}
+
+impl CollectionContext {
+    /// 以工作目录构造。
+    #[must_use]
+    pub fn new(run_dir: impl Into<PathBuf>) -> Self {
+        Self {
+            run_dir: run_dir.into(),
+            started_at: None,
+        }
+    }
+
+    /// 带「只认本次会话文件」的时间下界。
+    #[must_use]
+    pub fn since(mut self, started_at: SystemTime) -> Self {
+        self.started_at = Some(started_at);
+        self
+    }
+}
+
+/// 采集失败（尽力而为：单源失败不影响其它来源）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CollectError {
+    /// 出错的信号种类。
+    pub kind: SignalKind,
+    /// 相关路径（可能为空，例如纯逻辑错误）。
+    pub path: Option<PathBuf>,
+    /// 人类可读原因。
+    pub message: String,
+}
+
+impl CollectError {
+    fn io(kind: SignalKind, path: &Path, error: &io::Error) -> Self {
+        Self {
+            kind,
+            path: Some(path.to_path_buf()),
+            message: error.to_string(),
+        }
+    }
+}
+
+impl fmt::Display for CollectError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let path = self
+            .path
+            .as_deref()
+            .map_or_else(String::new, |path| format!("（{}）", path.display()));
+        write!(f, "{} 采集失败{path}：{}", self.kind.as_str(), self.message)
+    }
+}
+
+impl std::error::Error for CollectError {}
+
+/// 采到的源文件列表（诊断包导出 / 可观测性）。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct CollectedSources {
+    /// 文件路径。
+    pub paths: Vec<PathBuf>,
+}
+
+impl CollectedSources {
+    /// 空。
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// 记一个源文件。
+    pub fn push(&mut self, path: impl Into<PathBuf>) {
+        self.paths.push(path.into());
+    }
+
+    /// 是否什么都没采到。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.paths.is_empty()
+    }
+}
+
+/// 一个来源的采到的文本（含来源文件与时间）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CapturedText {
+    /// 来源文件。
+    pub path: PathBuf,
+    /// 文本。
+    pub text: String,
+    /// 修改时间。
+    pub modified: Option<SystemTime>,
+}
+
+/// 采集到的全部信号。
+#[derive(Debug, Clone, Default)]
+pub struct SignalBundle {
+    /// 退出信号。
+    pub exit: Option<ExitSignal>,
+    /// 日志环形缓冲（launch 逐行喂；`latest.log` 兜底也进这里）。
+    pub log: LogBuffer,
+    /// 崩溃报告全文。
+    pub crash_report: Option<CapturedText>,
+    /// hs_err 解析结果。
+    pub hs_err: Option<HsErrReport>,
+    /// 环境快照。
+    pub environment: Option<EnvironmentSnapshot>,
+    /// mod 清单。
+    pub mods: Vec<ModRecord>,
+    /// 本次采到的源文件。
+    pub sources: Vec<PathBuf>,
+}
+
+impl SignalBundle {
+    /// 空包（日志缓冲默认 2000 行）。
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// 是否没有任何信号。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.exit.is_none()
+            && self.log.is_empty()
+            && self.crash_report.is_none()
+            && self.hs_err.is_none()
+            && self.environment.is_none()
+            && self.mods.is_empty()
+    }
+
+    /// 转成规则引擎的输入。
+    ///
+    /// 日志按来源分组成多份待匹配文本（stdout/stderr 分开），这样证据里能保留来源；
+    /// crash-report 与 hs_err 各占一份，取证优先级由 `SignalOrigin::evidence_rank` 决定。
+    #[must_use]
+    pub fn diagnosis_input(&self) -> DiagnosisInput {
+        let mut input = DiagnosisInput::new();
+        input.exit = self.exit.clone();
+        for (origin, text) in grouped_log_text(&self.log) {
+            input.push_text(origin, text);
+        }
+        if let Some(crash_report) = &self.crash_report {
+            input.push_text(SignalOrigin::CrashReport, crash_report.text.clone());
+        }
+        if let Some(report) = &self.hs_err {
+            input.push_hs_err(report.clone());
+        }
+        input
+    }
+}
+
+fn grouped_log_text(log: &LogBuffer) -> Vec<(SignalOrigin, String)> {
+    let mut groups: Vec<(SignalOrigin, String)> = Vec::new();
+    for line in log.lines() {
+        match groups.iter_mut().find(|(origin, _)| *origin == line.origin) {
+            Some((_, text)) => {
+                text.push_str(&line.text);
+                text.push('\n');
+            }
+            None => groups.push((line.origin, format!("{}\n", line.text))),
+        }
+    }
+    groups
+}
+
+/// 信号采集器。
+pub trait SignalCollector {
+    /// 采哪种信号。
+    fn kind(&self) -> SignalKind;
+
+    /// 采集并写入 `out`；返回本次采到的源文件。
+    ///
+    /// # Errors
+    ///
+    /// 读盘失败 / 解析失败时返回 [`CollectError`]；调用方（[`collect_all`]）会收集错误继续。
+    fn collect(
+        &self,
+        ctx: &CollectionContext,
+        out: &mut SignalBundle,
+    ) -> Result<CollectedSources, CollectError>;
+}
+
+/// 按顺序跑一批采集器，单源失败只记录不中断。
+pub fn collect_all(
+    collectors: &[&dyn SignalCollector],
+    ctx: &CollectionContext,
+) -> (SignalBundle, Vec<CollectError>) {
+    let mut bundle = SignalBundle::new();
+    let mut errors = Vec::new();
+    for collector in collectors {
+        if let Err(error) = collector.collect(ctx, &mut bundle) {
+            errors.push(error);
+        }
+    }
+    (bundle, errors)
+}
diff --git a/crates/core/src/diagnose/engine.rs b/crates/core/src/diagnose/engine.rs
new file mode 100644
index 0000000..5549de9
--- /dev/null
+++ b/crates/core/src/diagnose/engine.rs
@@ -0,0 +1,321 @@
+//! 规则引擎：全量匹配 → 去重 → 抑制关系 → 置信度排序 → 结构化报告。
+//!
+//! 与 HMCL `CrashReportAnalyzer.analyze` + `GameCrashWindow.merge` 的差异（analyse/02 §7.6 §7.10）：
+//! 1. 同一条规则只留**最优证据来源**的那次命中（崩溃报告 > hs_err > 日志 > stdout > stderr）；
+//! 2. 结论带 `priority`/`confidence`，主因在 `findings[0]`，被抑制的次生结论进 `secondary`；
+//! 3. 输出是纯数据 [`DiagnosisRecord`]（可序列化、可跨线程），不再泄漏匹配器状态；
+//! 4. 退出码 / hs_err 这类**结构化信号**由内置结论补位（见 `synthetic.rs`）。
+//!
+//! 性能取舍：`scope: line` 逐行扫（59 条 × 行数，弱机可接受）；`scope: file` 的跨行规则
+//! 只在 ≤1 MiB 文本上跑，超长日志取首尾各 512 KiB。
+
+use std::collections::BTreeMap;
+
+use crate::diagnose::collectors::{ExitSignal, SignalOrigin};
+use crate::diagnose::hs_err::HsErrReport;
+use crate::diagnose::rules::{CompiledRule, MatchScope};
+
+#[path = "finding.rs"]
+mod finding;
+#[path = "synthetic.rs"]
+mod synthetic;
+
+pub use finding::{
+    Candidate, DiagnosisRecord, DiagnosisReport, Evidence, ExitRecord, Finding,
+    CONCLUSIVE_CONFIDENCE,
+};
+pub use synthetic::synthetic_findings;
+
+/// 超过这个字节数就不再整份扫描 `scope: file` 规则（取首尾窗口）。
+const FILE_SCOPE_LIMIT: usize = 1024 * 1024;
+/// 超长文本的扫描窗口（首尾各一份）。
+const FILE_SCOPE_WINDOW: usize = 512 * 1024;
+/// 证据行截断长度（避免把整份栈塞进诊断输出）。
+const EVIDENCE_MAX_CHARS: usize = 300;
+
+/// 待匹配的一段文本（一个信号来源一份）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Haystack {
+    /// 来源（决定证据前缀与取证优先级）。
+    pub origin: SignalOrigin,
+    /// 文本。
+    pub text: String,
+}
+
+impl Haystack {
+    /// 构造。
+    #[must_use]
+    pub fn new(origin: SignalOrigin, text: impl Into<String>) -> Self {
+        Self {
+            origin,
+            text: text.into(),
+        }
+    }
+}
+
+/// 引擎输入：退出信号 + 若干待匹配文本 +（可选）解析好的 hs_err。
+#[derive(Debug, Clone, Default)]
+pub struct DiagnosisInput {
+    /// 退出信号。
+    pub exit: Option<ExitSignal>,
+    /// 待匹配文本（按 `SignalOrigin::evidence_rank` 优先取证据）。
+    pub haystacks: Vec<Haystack>,
+    /// 解析好的 `hs_err_pid*.log`（产生内置结论，其摘要也已进 `haystacks`）。
+    pub hs_err: Option<HsErrReport>,
+}
+
+impl DiagnosisInput {
+    /// 空输入。
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// 带退出信号。
+    #[must_use]
+    pub fn with_exit(mut self, exit: ExitSignal) -> Self {
+        self.exit = Some(exit);
+        self
+    }
+
+    /// 追加一段待匹配文本。
+    pub fn push_text(&mut self, origin: SignalOrigin, text: impl Into<String>) {
+        self.haystacks.push(Haystack::new(origin, text));
+    }
+
+    /// 追加解析好的 hs_err：摘要进待匹配文本，结构留给内置结论。
+    pub fn push_hs_err(&mut self, report: HsErrReport) {
+        self.haystacks
+            .push(Haystack::new(SignalOrigin::HsErr, report.digest()));
+        self.hs_err = Some(report);
+    }
+
+    /// 是否什么信号都没有。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.exit.is_none() && self.haystacks.is_empty()
+    }
+}
+
+/// 规则引擎（规则只编译一次，可跨线程共享）。
+#[derive(Debug, Clone, Default)]
+pub struct Diagnoser {
+    rules: Vec<CompiledRule>,
+}
+
+impl Diagnoser {
+    /// 用一组已编译的规则构造。
+    #[must_use]
+    pub fn new(rules: Vec<CompiledRule>) -> Self {
+        Self { rules }
+    }
+
+    /// 规则表。
+    #[must_use]
+    pub fn rules(&self) -> &[CompiledRule] {
+        &self.rules
+    }
+
+    /// 跑一遍诊断。
+    #[must_use]
+    pub fn analyze(&self, input: &DiagnosisInput) -> DiagnosisReport {
+        let mut ordered = input.haystacks.iter().collect::<Vec<_>>();
+        ordered.sort_by_key(|haystack| haystack.origin.evidence_rank());
+
+        let mut findings = Vec::new();
+        for rule in &self.rules {
+            for haystack in &ordered {
+                if let Some(found) = scan(rule, haystack) {
+                    findings.push(build_finding(rule, haystack, &found));
+                    break;
+                }
+            }
+        }
+        findings.extend(synthetic_findings(input));
+
+        let (mut findings, mut secondary) = split_suppressed(findings);
+        findings.sort_by(Finding::rank_cmp);
+        secondary.sort_by(Finding::rank_cmp);
+
+        DiagnosisReport {
+            findings,
+            secondary,
+            exit: input.exit.clone(),
+            rules_evaluated: self.rules.len(),
+            hs_err: input.hs_err.clone(),
+        }
+    }
+}
+
+/// 一次正则命中（绝对偏移 + 命名捕获组）。
+#[derive(Debug)]
+struct RawMatch {
+    groups: BTreeMap<String, String>,
+    offset: usize,
+}
+
+fn scan(rule: &CompiledRule, haystack: &Haystack) -> Option<RawMatch> {
+    match rule.scope() {
+        MatchScope::Line => scan_lines(rule, &haystack.text),
+        MatchScope::Block => scan_blocks(rule, &haystack.text),
+        MatchScope::File => scan_file(rule, &haystack.text),
+    }
+}
+
+/// 逐行匹配（返回命中行的起始偏移，行号即证据行号）。
+fn scan_lines(rule: &CompiledRule, text: &str) -> Option<RawMatch> {
+    let mut offset = 0;
+    for chunk in text.split_inclusive('\n') {
+        let line = chunk.trim_end_matches(['\r', '\n']);
+        if let Some(caps) = rule.regex().captures(line) {
+            return Some(capture_groups(rule, &caps, offset));
+        }
+        offset += chunk.len();
+    }
+    None
+}
+
+/// 按空行切块匹配（一段异常 + 其上下文）。
+///
+/// 分隔符是**空行**而不是字面 `"\n\n"`：日志文件可能是 CRLF（Windows 上 `latest.log` 常见），
+/// 按字节找 `\n\n` 会把整份日志当成一个块，`scope: block` 的规则就退化成整份扫描。
+fn scan_blocks(rule: &CompiledRule, text: &str) -> Option<RawMatch> {
+    let mut block_start = 0;
+    let mut offset = 0;
+    for chunk in text.split_inclusive('\n') {
+        offset += chunk.len();
+        if chunk.trim().is_empty() {
+            if let Some(caps) = rule.regex().captures(&text[block_start..offset]) {
+                return Some(capture_groups(rule, &caps, block_start));
+            }
+            block_start = offset;
+        }
+    }
+    if block_start < text.len() {
+        let caps = rule.regex().captures(&text[block_start..])?;
+        return Some(capture_groups(rule, &caps, block_start));
+    }
+    None
+}
+
+/// 整份匹配；超长文本只看首尾窗口（跨行贪婪规则的性能边界）。
+fn scan_file(rule: &CompiledRule, text: &str) -> Option<RawMatch> {
+    if text.len() <= FILE_SCOPE_LIMIT {
+        let caps = rule.regex().captures(text)?;
+        let offset = caps.get(0).map_or(0, |found| found.start());
+        return Some(capture_groups(rule, &caps, offset));
+    }
+    let head_end = ceil_boundary(text, FILE_SCOPE_WINDOW);
+    if let Some(caps) = rule.regex().captures(&text[..head_end]) {
+        let offset = caps.get(0).map_or(0, |found| found.start());
+        return Some(capture_groups(rule, &caps, offset));
+    }
+    let tail_start = floor_boundary(text, text.len() - FILE_SCOPE_WINDOW);
+    let caps = rule.regex().captures(&text[tail_start..])?;
+    let offset = tail_start + caps.get(0).map_or(0, |found| found.start());
+    Some(capture_groups(rule, &caps, offset))
+}
+
+fn capture_groups(rule: &CompiledRule, caps: &regex::Captures<'_>, offset: usize) -> RawMatch {
+    let mut groups = BTreeMap::new();
+    for name in rule.regex().capture_names().flatten() {
+        if let Some(found) = caps.name(name) {
+            groups.insert(name.to_owned(), found.as_str().trim().to_owned());
+        }
+    }
+    RawMatch { groups, offset }
+}
+
+fn build_finding(compiled: &CompiledRule, haystack: &Haystack, found: &RawMatch) -> Finding {
+    let rule = compiled.rule();
+    let (message, detail) = rule.cause.render(&found.groups);
+    Finding {
+        rule_id: rule.id.clone(),
+        category: compiled.category(),
+        severity: rule.severity,
+        confidence: rule.confidence.clamp(0.0, 1.0),
+        priority: rule.priority,
+        message_key: rule.cause.key.clone(),
+        message,
+        detail,
+        evidence: vec![Evidence::new(
+            haystack.origin,
+            line_of(&haystack.text, found.offset),
+            snippet(&haystack.text, found.offset),
+        )],
+        fix_actions: rule.fix_action.clone(),
+        groups: found.groups.clone(),
+        suppress: rule.suppress.clone(),
+        suppressed_by: None,
+    }
+}
+
+/// 把被 suppress 的结论拆到次生列表（不丢弃，UI 折叠展示）。
+fn split_suppressed(findings: Vec<Finding>) -> (Vec<Finding>, Vec<Finding>) {
+    let suppressers = findings
+        .iter()
+        .map(|finding| {
+            (
+                finding.rule_id.clone(),
+                finding.priority,
+                finding.suppress.clone(),
+            )
+        })
+        .collect::<Vec<_>>();
+    let mut kept = Vec::new();
+    let mut suppressed = Vec::new();
+    for mut finding in findings {
+        let mut best: Option<(&str, u8)> = None;
+        for (id, priority, suppress) in &suppressers {
+            if *id == finding.rule_id || !suppress.iter().any(|item| item == &finding.rule_id) {
+                continue;
+            }
+            if best.is_none_or(|(_, best_priority)| *priority > best_priority) {
+                best = Some((id.as_str(), *priority));
+            }
+        }
+        match best {
+            Some((id, _)) => {
+                finding.suppressed_by = Some(id.to_owned());
+                suppressed.push(finding);
+            }
+            None => kept.push(finding),
+        }
+    }
+    (kept, suppressed)
+}
+
+fn line_of(text: &str, offset: usize) -> usize {
+    let offset = offset.min(text.len());
+    1 + text[..offset].matches('\n').count()
+}
+
+fn snippet(text: &str, offset: usize) -> String {
+    let offset = offset.min(text.len());
+    let start = text[..offset].rfind('\n').map_or(0, |index| index + 1);
+    let end = text[start..]
+        .find('\n')
+        .map_or(text.len(), |index| start + index);
+    let line = text[start..end].trim();
+    let mut out = line.chars().take(EVIDENCE_MAX_CHARS).collect::<String>();
+    if line.chars().count() > EVIDENCE_MAX_CHARS {
+        out.push('…');
+    }
+    out
+}
+
+fn ceil_boundary(text: &str, mut index: usize) -> usize {
+    index = index.min(text.len());
+    while index < text.len() && !text.is_char_boundary(index) {
+        index += 1;
+    }
+    index
+}
+
+fn floor_boundary(text: &str, mut index: usize) -> usize {
+    index = index.min(text.len());
+    while index > 0 && !text.is_char_boundary(index) {
+        index -= 1;
+    }
+    index
+}
diff --git a/crates/core/src/diagnose/environment.rs b/crates/core/src/diagnose/environment.rs
new file mode 100644
index 0000000..2545bdb
--- /dev/null
+++ b/crates/core/src/diagnose/environment.rs
@@ -0,0 +1,155 @@
+//! 环境快照与 mod 清单（analyse/02 §7.1 信号 E）。
+//!
+//! HMCL 只在崩溃窗口里散着展示这些信息；我们做成结构化数据，
+//! 既进诊断输出（`environment.json` 一样的机器可读上下文），也让规则能按版本号做前置判断。
+//! 由 `collectors.rs` 用 `#[path]` 声明并统一导出。
+
+use std::path::PathBuf;
+
+/// 一个已装组件的版本（Forge/Fabric/OptiFine…）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ComponentVersion {
+    /// 组件名（`forge`/`fabric`/`optifine`/`minecraft`…）。
+    pub name: String,
+    /// 版本串。
+    pub version: String,
+}
+
+impl ComponentVersion {
+    /// 构造。
+    #[must_use]
+    pub fn new(name: impl Into<String>, version: impl Into<String>) -> Self {
+        Self {
+            name: name.into(),
+            version: version.into(),
+        }
+    }
+}
+
+/// 一个已装 mod（供交叉验证「冲突/mixin 失败」类结论，analyse/02 §8.4-10）。
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct ModRecord {
+    /// modid（解析不出时为空）。
+    pub id: String,
+    /// 展示名。
+    pub name: Option<String>,
+    /// 版本。
+    pub version: Option<String>,
+    /// jar 文件名（诊断包里给人看）。
+    pub file: Option<String>,
+    /// 是否启用（`.disabled` 视为未启用）。
+    pub enabled: bool,
+}
+
+impl ModRecord {
+    /// 从文件名构造（不解 jar，P0 足够：冲突类结论要的是「装了哪些文件」）。
+    #[must_use]
+    pub fn from_file_name(file: &str) -> Self {
+        let enabled = !file.ends_with(".disabled");
+        let stem = file
+            .trim_end_matches(".disabled")
+            .trim_end_matches(".jar")
+            .to_owned();
+        let (name, version) = stem
+            .rsplit_once('-')
+            .filter(|(_, version)| version.chars().next().is_some_and(|ch| ch.is_ascii_digit()))
+            .map_or((stem.clone(), None), |(name, version)| {
+                (name.to_owned(), Some(version.to_owned()))
+            });
+        Self {
+            id: name.to_lowercase(),
+            name: Some(name),
+            version,
+            file: Some(file.to_owned()),
+            enabled,
+        }
+    }
+}
+
+/// 启动环境快照（Java/内存/OS/组件/mod 清单）。
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct EnvironmentSnapshot {
+    /// 启动器版本（`ull 0.2.0`）。
+    pub launcher: Option<String>,
+    /// 实例 id。
+    pub instance_id: Option<String>,
+    /// 游戏版本。
+    pub game_version: Option<String>,
+    /// 操作系统名（`Windows 10.0.19045`）。
+    pub os_name: Option<String>,
+    /// 架构（`x86_64` / `aarch64`）。
+    pub os_arch: Option<String>,
+    /// 物理内存（MB）。
+    pub physical_memory_mb: Option<u64>,
+    /// Java 可执行文件。
+    pub java_path: Option<PathBuf>,
+    /// Java 大版本。
+    pub java_major: Option<u32>,
+    /// Java 位数（32 / 64）。
+    pub java_bits: Option<u32>,
+    /// `-Xmx`（MB）。
+    pub xmx_mb: Option<u32>,
+    /// `-Xms`（MB）。
+    pub xms_mb: Option<u32>,
+    /// 工作目录（跑游戏的 cwd）。
+    pub run_dir: Option<PathBuf>,
+    /// 已装组件版本。
+    pub components: Vec<ComponentVersion>,
+    /// 已装 mod。
+    pub mods: Vec<ModRecord>,
+}
+
+impl EnvironmentSnapshot {
+    /// 一行人类可读摘要（证据行 / UI 头部）。
+    #[must_use]
+    pub fn summary(&self) -> String {
+        let os = format!(
+            "{} {}",
+            self.os_name.as_deref().unwrap_or("未知系统"),
+            self.os_arch.as_deref().unwrap_or("")
+        );
+        let java = self.java_major.map_or_else(
+            || "Java 未知".to_owned(),
+            |major| match self.java_bits {
+                Some(bits) => format!("Java {major}（{bits} 位）"),
+                None => format!("Java {major}"),
+            },
+        );
+        let memory = match (self.xmx_mb, self.physical_memory_mb) {
+            (Some(xmx), Some(physical)) => format!("-Xmx {xmx} MB / 物理 {physical} MB"),
+            (Some(xmx), None) => format!("-Xmx {xmx} MB"),
+            (None, Some(physical)) => format!("物理 {physical} MB"),
+            (None, None) => "内存未知".to_owned(),
+        };
+        let mods = self.mods.len();
+        format!("{} / {} / {} / {} 个 mod", os.trim(), java, memory, mods)
+    }
+
+    /// 是不是 32 位 Java（`-Xmx` 超过 ~1.5 GB 必崩的直接证据）。
+    #[must_use]
+    pub fn is_java_32bit(&self) -> bool {
+        self.java_bits == Some(32)
+    }
+
+    /// 组件版本（按名字查，`optifine` 之类的冲突规则用）。
+    #[must_use]
+    pub fn component(&self, name: &str) -> Option<&str> {
+        self.components
+            .iter()
+            .find(|component| component.name.eq_ignore_ascii_case(name))
+            .map(|component| component.version.as_str())
+    }
+
+    /// 是否装了某个 mod（按 id 或文件名模糊匹配）。
+    #[must_use]
+    pub fn has_mod(&self, id: &str) -> bool {
+        let needle = id.to_ascii_lowercase();
+        self.mods.iter().any(|record| {
+            record.id.contains(&needle)
+                || record
+                    .file
+                    .as_deref()
+                    .is_some_and(|file| file.to_ascii_lowercase().contains(&needle))
+        })
+    }
+}
diff --git a/crates/core/src/diagnose/finding.rs b/crates/core/src/diagnose/finding.rs
new file mode 100644
index 0000000..0b5388f
--- /dev/null
+++ b/crates/core/src/diagnose/finding.rs
@@ -0,0 +1,256 @@
+//! 结论与报告的数据结构（纯数据，可序列化，不持有匹配器状态）。
+//!
+//! HMCL 的 `CrashReportAnalyzer.Result` 直接把 `Matcher` 传出去（不可序列化、不能跨线程），
+//! 这里改成「证据 + 已渲染文案 + 物化动作」的结构化记录（analyse/02 §7.10-6）。
+//!
+//! 由 `engine.rs` 用 `#[path]` 声明并统一导出；拆分只为守单文件 400 行上限。
+
+use std::collections::BTreeMap;
+
+use serde::Serialize;
+
+use crate::diagnose::collectors::{ExitSignal, SignalOrigin};
+use crate::diagnose::hs_err::HsErrReport;
+use crate::diagnose::rules::{FixAction, MaterializedFixAction, RuleCategory, Severity};
+
+/// 「结论足够确定」的可信度门槛：低于它就该交给 AI 深化（PlanDoc/06 §2.3）。
+pub const CONCLUSIVE_CONFIDENCE: f32 = 0.8;
+
+/// 一条证据（哪个来源的第几行的哪段文本）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Evidence {
+    /// 来源。
+    pub origin: SignalOrigin,
+    /// 行号（1 起；结构化信号为 0）。
+    pub line: usize,
+    /// 文本片段（≤300 字符）。
+    pub text: String,
+}
+
+impl Evidence {
+    /// 构造。
+    #[must_use]
+    pub fn new(origin: SignalOrigin, line: usize, text: impl Into<String>) -> Self {
+        Self {
+            origin,
+            line,
+            text: text.into(),
+        }
+    }
+
+    /// 诊断输出里的字符串形式：`"<origin>:<line> <text>"`。
+    #[must_use]
+    pub fn render(&self) -> String {
+        format!("{}:{} {}", self.origin, self.line, self.text)
+    }
+}
+
+/// 一条结论。
+#[derive(Debug, Clone)]
+pub struct Finding {
+    /// 规则 id（内置结论用 `signal.*` / `hs_err.*`）。
+    pub rule_id: String,
+    /// 分类。
+    pub category: RuleCategory,
+    /// 严重度。
+    pub severity: Severity,
+    /// 可信度。
+    pub confidence: f32,
+    /// 主因权重。
+    pub priority: u8,
+    /// i18n / AI 引用 id。
+    pub message_key: String,
+    /// 渲染后的中文结论（M16 `diagnose_crash` 直接给模型看）。
+    pub message: String,
+    /// 细化说明 / 处理建议。
+    pub detail: Option<String>,
+    /// 证据。
+    pub evidence: Vec<Evidence>,
+    /// 六维修复动作。
+    pub fix_actions: Vec<FixAction>,
+    /// 规则捕获组（供动作模板替换）。
+    pub groups: BTreeMap<String, String>,
+    /// 本结论会抑制哪些规则 id。
+    pub suppress: Vec<String>,
+    /// 被哪条结论抑制（`Some` 即次生结论）。
+    pub suppressed_by: Option<String>,
+}
+
+impl Finding {
+    /// 一条只有骨架的结论（内置结论的构造起点，其余字段由调用方填）。
+    #[must_use]
+    pub fn skeleton(
+        rule_id: &str,
+        category: RuleCategory,
+        severity: Severity,
+        confidence: f32,
+        priority: u8,
+        message_key: &str,
+        message: &str,
+    ) -> Self {
+        Self {
+            rule_id: rule_id.to_owned(),
+            category,
+            severity,
+            confidence,
+            priority,
+            message_key: message_key.to_owned(),
+            message: message.to_owned(),
+            detail: None,
+            evidence: Vec::new(),
+            fix_actions: Vec::new(),
+            groups: BTreeMap::new(),
+            suppress: Vec::new(),
+            suppressed_by: None,
+        }
+    }
+
+    /// 物化后的修复动作（模板已替换）。
+    #[must_use]
+    pub fn materialized_actions(&self) -> Vec<MaterializedFixAction> {
+        self.fix_actions
+            .iter()
+            .map(|action| action.materialize(&self.groups))
+            .collect()
+    }
+
+    /// 转成诊断输出里的候选。
+    #[must_use]
+    pub fn to_candidate(&self) -> Candidate {
+        Candidate {
+            id: self.rule_id.clone(),
+            severity: self.severity.as_str(),
+            category: self.category.as_str(),
+            confidence: self.confidence,
+            message_key: self.message_key.clone(),
+            message: self.message.clone(),
+            detail: self.detail.clone(),
+            evidence: self.evidence.iter().map(Evidence::render).collect(),
+            fix_actions: self.materialized_actions(),
+        }
+    }
+
+    /// 排序：priority 高 → confidence 高 → id 字典序（保证确定性）。
+    #[must_use]
+    pub fn rank_cmp(&self, other: &Self) -> std::cmp::Ordering {
+        other
+            .priority
+            .cmp(&self.priority)
+            .then_with(|| other.confidence.total_cmp(&self.confidence))
+            .then_with(|| self.rule_id.cmp(&other.rule_id))
+    }
+}
+
+/// 诊断输出里的一条候选结论（字段名与 `launch-接口约定.md` §3 `diagnosis` 对齐）。
+#[derive(Debug, Clone, Serialize)]
+pub struct Candidate {
+    /// 规则 id。
+    pub id: String,
+    /// 严重度。
+    pub severity: &'static str,
+    /// 分类。
+    pub category: &'static str,
+    /// 可信度。
+    pub confidence: f32,
+    /// i18n / AI 引用 id。
+    pub message_key: String,
+    /// 渲染后的中文结论。
+    pub message: String,
+    /// 细化说明。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub detail: Option<String>,
+    /// 证据字符串。
+    pub evidence: Vec<String>,
+    /// 六维修复动作（M16/UI 一键修复入口）。
+    pub fix_actions: Vec<MaterializedFixAction>,
+}
+
+/// 退出信号摘要（诊断输出用）。
+#[derive(Debug, Clone, Serialize)]
+pub struct ExitRecord {
+    /// 退出码。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub code: Option<i32>,
+    /// 退出类型（与 launch 约定同值）。
+    pub exit_type: &'static str,
+    /// 疑似静默失败。
+    pub silent_failure: bool,
+    /// 存活毫秒数。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub uptime_ms: Option<u64>,
+}
+
+/// 交给 launch 写入 `diagnosis` 事件的结构化结果。
+#[derive(Debug, Clone, Serialize)]
+pub struct DiagnosisRecord {
+    /// 结论来源（`rules` / `ai`）。
+    pub source: &'static str,
+    /// 规则没把握、需要 AI 或用户补充信息。
+    pub needs_more_info: bool,
+    /// 结论（`candidates[0]` 是主因）。
+    pub candidates: Vec<Candidate>,
+    /// 被抑制的次生结论。
+    pub secondary: Vec<Candidate>,
+    /// 本次判定用的退出信号摘要。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub exit: Option<ExitRecord>,
+}
+
+/// 一次诊断的完整结果。
+#[derive(Debug, Clone, Default)]
+pub struct DiagnosisReport {
+    /// 结论（已排序，主因在前）。
+    pub findings: Vec<Finding>,
+    /// 被抑制的次生结论。
+    pub secondary: Vec<Finding>,
+    /// 本次判定用的退出信号。
+    pub exit: Option<ExitSignal>,
+    /// 评估了多少条规则（可观测性）。
+    pub rules_evaluated: usize,
+    /// 解析出的 hs_err（若有）。
+    pub hs_err: Option<HsErrReport>,
+}
+
+impl DiagnosisReport {
+    /// 主因（可能没有）。
+    #[must_use]
+    pub fn primary(&self) -> Option<&Finding> {
+        self.findings.first()
+    }
+
+    /// 规则层有没有把握：没有任何结论，或主因可信度 < [`CONCLUSIVE_CONFIDENCE`]。
+    #[must_use]
+    pub fn needs_more_info(&self) -> bool {
+        self.primary()
+            .is_none_or(|finding| finding.confidence < CONCLUSIVE_CONFIDENCE)
+    }
+
+    /// 去重后的修复动作（主因优先，供 UI 一键修复 / agent 直接执行）。
+    #[must_use]
+    pub fn fix_actions(&self) -> Vec<MaterializedFixAction> {
+        let mut out: Vec<MaterializedFixAction> = Vec::new();
+        for action in self.findings.iter().flat_map(Finding::materialized_actions) {
+            if !out.contains(&action) {
+                out.push(action);
+            }
+        }
+        out
+    }
+
+    /// 转成可序列化的诊断记录。
+    #[must_use]
+    pub fn to_record(&self) -> DiagnosisRecord {
+        DiagnosisRecord {
+            source: "rules",
+            needs_more_info: self.needs_more_info(),
+            candidates: self.findings.iter().map(Finding::to_candidate).collect(),
+            secondary: self.secondary.iter().map(Finding::to_candidate).collect(),
+            exit: self.exit.as_ref().map(|exit| ExitRecord {
+                code: exit.code,
+                exit_type: exit.exit_type.as_str(),
+                silent_failure: exit.silent_failure,
+                uptime_ms: exit.uptime_ms,
+            }),
+        }
+    }
+}
diff --git a/crates/core/src/diagnose/fix_action.rs b/crates/core/src/diagnose/fix_action.rs
new file mode 100644
index 0000000..2be9b00
--- /dev/null
+++ b/crates/core/src/diagnose/fix_action.rs
@@ -0,0 +1,213 @@
+//! 六维修复动作本体：枚举、维度、以及「代入捕获组 → agent 工具参数」的物化。
+//!
+//! 六个维度与 analyse/02 §7.7 的动作分类一一对应，也是 M16 `ToolSpec` 的参数来源
+//! （契约见同目录 `CONTRACT.md` §3）。
+
+use std::collections::BTreeMap;
+
+use serde::{Deserialize, Serialize};
+
+use super::fix_params::{AdjustMemory, ChangeGraphics, ChangeJava, Reinstall, RemoveMod, SeekHelp};
+use super::substitute;
+
+/// 六维修复动作（YAML 里 `kind:` 选维度）。
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum FixAction {
+    /// 换 Java。
+    ChangeJava(ChangeJava),
+    /// 调内存。
+    AdjustMemory(AdjustMemory),
+    /// 改图形设置。
+    ChangeGraphics(ChangeGraphics),
+    /// 删/禁/换 mod。
+    RemoveMod(RemoveMod),
+    /// 重装/修组件。
+    Reinstall(Reinstall),
+    /// 求助上报。
+    SeekHelp(SeekHelp),
+}
+
+/// 六维动作的维度枚举（不含参数，便于判等/去重/映射工具）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum FixActionKind {
+    /// 换 Java。
+    ChangeJava,
+    /// 调内存。
+    AdjustMemory,
+    /// 改图形设置。
+    ChangeGraphics,
+    /// 删/禁/换 mod。
+    RemoveMod,
+    /// 重装/修组件。
+    Reinstall,
+    /// 求助上报。
+    SeekHelp,
+}
+
+impl FixActionKind {
+    /// 稳定字符串（诊断输出的 `kind` 字段，与 YAML 的 `kind:` 一致）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::ChangeJava => "change_java",
+            Self::AdjustMemory => "adjust_memory",
+            Self::ChangeGraphics => "change_graphics",
+            Self::RemoveMod => "remove_mod",
+            Self::Reinstall => "reinstall",
+            Self::SeekHelp => "seek_help",
+        }
+    }
+
+    /// 建议的 agent 工具 id。
+    ///
+    /// M16 的 P0 工具只有 5 个（`get_config`/`set_config`/`list_game_sessions`/`read_game_log`/
+    /// `diagnose_crash`），因此它按 `kind` 桥接；这里的 id 是 P1 落地细分工具时的直接映射。
+    #[must_use]
+    pub const fn agent_tool(self) -> &'static str {
+        match self {
+            Self::ChangeJava => "java.set",
+            Self::AdjustMemory => "memory.set",
+            Self::ChangeGraphics => "graphics.set",
+            Self::RemoveMod => "mod.remove",
+            Self::Reinstall => "component.reinstall",
+            Self::SeekHelp => "diagnostics.report",
+        }
+    }
+
+    /// 全部六维（测试与 UI 遍历用）。
+    #[must_use]
+    pub const fn all() -> [Self; 6] {
+        [
+            Self::ChangeJava,
+            Self::AdjustMemory,
+            Self::ChangeGraphics,
+            Self::RemoveMod,
+            Self::Reinstall,
+            Self::SeekHelp,
+        ]
+    }
+}
+
+/// 已做模板替换/单位换算的动作，可直接当 agent 工具参数。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+pub struct MaterializedFixAction {
+    /// 维度。
+    pub kind: FixActionKind,
+    /// agent 工具 id（见 [`FixActionKind::agent_tool`]）。
+    pub tool: &'static str,
+    /// 扁平字符串参数表。
+    pub args: BTreeMap<String, String>,
+}
+
+impl FixAction {
+    /// 维度。
+    #[must_use]
+    pub const fn kind(&self) -> FixActionKind {
+        match self {
+            Self::ChangeJava(_) => FixActionKind::ChangeJava,
+            Self::AdjustMemory(_) => FixActionKind::AdjustMemory,
+            Self::ChangeGraphics(_) => FixActionKind::ChangeGraphics,
+            Self::RemoveMod(_) => FixActionKind::RemoveMod,
+            Self::Reinstall(_) => FixActionKind::Reinstall,
+            Self::SeekHelp(_) => FixActionKind::SeekHelp,
+        }
+    }
+
+    /// 代入规则命名捕获组，产出 agent 工具可直接用的参数表。
+    #[must_use]
+    pub fn materialize(&self, groups: &BTreeMap<String, String>) -> MaterializedFixAction {
+        let kind = self.kind();
+        let mut args = BTreeMap::new();
+        match self {
+            Self::ChangeJava(p) => {
+                let derived = p
+                    .class_file_version_group
+                    .as_ref()
+                    .and_then(|group| groups.get(group))
+                    .and_then(|raw| raw.trim().parse::<u32>().ok())
+                    .and_then(class_file_to_java_major);
+                put_opt(&mut args, "required_major", p.required_major.or(derived));
+                put_opt(&mut args, "max_major", p.max_major);
+                put_str(&mut args, "vendor", p.vendor.as_str());
+                put_opt_str(&mut args, "note", render_opt(&p.note, groups));
+            }
+            Self::AdjustMemory(p) => {
+                put_opt(&mut args, "suggested_xmx_mb", p.suggested_xmx_mb);
+                put_opt(&mut args, "min_xmx_mb", p.min_xmx_mb);
+                put_bool(&mut args, "need_64bit_java", p.need_64bit_java);
+                put_bool(&mut args, "increase_system_swap", p.increase_system_swap);
+                put_opt_str(&mut args, "note", render_opt(&p.note, groups));
+            }
+            Self::ChangeGraphics(p) => {
+                put_str(&mut args, "setting", p.setting.as_str());
+                put_bool(&mut args, "update_driver", p.update_driver);
+                put_opt_str(&mut args, "suggested_value", p.suggested_value.clone());
+                put_opt_str(&mut args, "note", render_opt(&p.note, groups));
+            }
+            Self::RemoveMod(p) => {
+                let ids = p
+                    .mod_ids
+                    .iter()
+                    .map(|id| substitute(id, groups))
+                    .collect::<Vec<_>>();
+                if !ids.is_empty() {
+                    args.insert("mod_ids".to_owned(), ids.join(","));
+                }
+                put_str(&mut args, "action", p.action.as_str());
+                put_opt_str(&mut args, "note", render_opt(&p.note, groups));
+            }
+            Self::Reinstall(p) => {
+                put_str(&mut args, "component", p.component.as_str());
+                put_opt_str(&mut args, "path_hint", render_opt(&p.path_hint, groups));
+                put_opt_str(&mut args, "note", render_opt(&p.note, groups));
+            }
+            Self::SeekHelp(p) => {
+                put_bool(&mut args, "export_diagnostics", p.export_diagnostics);
+                if !p.needs_more_info.is_empty() {
+                    args.insert("needs_more_info".to_owned(), p.needs_more_info.join("; "));
+                }
+                put_opt_str(&mut args, "note", render_opt(&p.note, groups));
+            }
+        }
+        MaterializedFixAction {
+            kind,
+            tool: kind.agent_tool(),
+            args,
+        }
+    }
+}
+
+/// 可选的模板字段：`Some` 时做 `{group}` 替换，`None` 保持 `None`。
+fn render_opt(value: &Option<String>, groups: &BTreeMap<String, String>) -> Option<String> {
+    value.as_ref().map(|text| substitute(text, groups))
+}
+
+fn put_str(args: &mut BTreeMap<String, String>, key: &str, value: &str) {
+    args.insert(key.to_owned(), value.to_owned());
+}
+
+fn put_opt_str(args: &mut BTreeMap<String, String>, key: &str, value: Option<String>) {
+    if let Some(value) = value {
+        args.insert(key.to_owned(), value);
+    }
+}
+
+fn put_opt(args: &mut BTreeMap<String, String>, key: &str, value: Option<u32>) {
+    if let Some(value) = value {
+        args.insert(key.to_owned(), value.to_string());
+    }
+}
+
+fn put_bool(args: &mut BTreeMap<String, String>, key: &str, value: bool) {
+    args.insert(key.to_owned(), value.to_string());
+}
+
+/// `class file version 52` → `Java 8`（HMCL `getJavaVersionFromMajorVersion` 同式）。
+#[must_use]
+pub fn class_file_to_java_major(class_file_version: u32) -> Option<u32> {
+    class_file_version
+        .checked_sub(44)
+        .filter(|major| *major > 0)
+}
diff --git a/crates/core/src/diagnose/fix_params.rs b/crates/core/src/diagnose/fix_params.rs
new file mode 100644
index 0000000..3b4b891
--- /dev/null
+++ b/crates/core/src/diagnose/fix_params.rs
@@ -0,0 +1,252 @@
+//! 六维修复动作的参数类型（`fix_action.rs` 的载荷 + 几个小枚举）。
+//!
+//! 由 `rules.rs` 用 `#[path]` 声明并统一导出；文件拆分只为守 400 行上限。
+
+use serde::Deserialize;
+
+/// 建议的 JVM 实现。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum JavaVendor {
+    /// 不限定（HotSpot 优先）。
+    #[default]
+    Any,
+    /// 必须 HotSpot（OpenJ9 等不兼容实现的反面）。
+    Hotspot,
+}
+
+impl JavaVendor {
+    /// 稳定字符串。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Any => "any",
+            Self::Hotspot => "hotspot",
+        }
+    }
+}
+
+/// 图形侧要修的那一类设置。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum GraphicsSetting {
+    /// 不指定具体项，只表达「图形相关」。
+    #[default]
+    Any,
+    /// 渲染器（OpenGL 核心/兼容、ANGLE、软渲染）。
+    Renderer,
+    /// 显卡驱动。
+    Driver,
+    /// 图形 API（MC 26.2+ 的「默认 / 优先 Vulkan / 优先 OpenGL」三选一）。
+    GraphicsApi,
+    /// 分辨率 / 资源包分辨率。
+    Resolution,
+    /// 覆盖层类软件（RTSS、Discord 等）。
+    Overlay,
+    /// 软件渲染兜底。
+    SoftwareRenderer,
+}
+
+impl GraphicsSetting {
+    /// 稳定字符串。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Any => "any",
+            Self::Renderer => "renderer",
+            Self::Driver => "driver",
+            Self::GraphicsApi => "graphics_api",
+            Self::Resolution => "resolution",
+            Self::Overlay => "overlay",
+            Self::SoftwareRenderer => "software_renderer",
+        }
+    }
+}
+
+/// 对 mod 的处理方式。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ModAction {
+    /// 移出 mods 目录。
+    #[default]
+    Remove,
+    /// 暂时禁用（挪到 `.disabled`）。
+    Disable,
+    /// 换一个版本 / 换替代品。
+    Replace,
+    /// 升级到兼容版本。
+    Upgrade,
+}
+
+impl ModAction {
+    /// 稳定字符串。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Remove => "remove",
+            Self::Disable => "disable",
+            Self::Replace => "replace",
+            Self::Upgrade => "upgrade",
+        }
+    }
+}
+
+/// 要重装/修复的组件。粒度对齐 download/game 侧的组件概念，便于 agent 直接调用。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ComponentKind {
+    /// Java 运行时本身。
+    Java,
+    /// 游戏主 jar。
+    GameJar,
+    /// 版本清单（version JSON）。
+    GameJson,
+    /// 未指定具体 loader。
+    Loader,
+    /// Fabric loader。
+    Fabric,
+    /// Forge。
+    Forge,
+    /// NeoForge。
+    #[serde(rename = "neoforge")]
+    NeoForge,
+    /// OptiFine。
+    #[serde(rename = "optifine")]
+    OptiFine,
+    /// natives 原生库。
+    Natives,
+    /// mods 目录（含「jar 被解压成目录」的修复）。
+    Mods,
+    /// libraries 库文件。
+    Libraries,
+    /// assets 资源。
+    Assets,
+    /// MixinBootstrap 等前置。
+    MixinBootstrap,
+}
+
+impl ComponentKind {
+    /// 稳定字符串。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Java => "java",
+            Self::GameJar => "game_jar",
+            Self::GameJson => "game_json",
+            Self::Loader => "loader",
+            Self::Fabric => "fabric",
+            Self::Forge => "forge",
+            Self::NeoForge => "neoforge",
+            Self::OptiFine => "optifine",
+            Self::Natives => "natives",
+            Self::Mods => "mods",
+            Self::Libraries => "libraries",
+            Self::Assets => "assets",
+            Self::MixinBootstrap => "mixin_bootstrap",
+        }
+    }
+}
+
+/// 换 Java 的参数。
+#[derive(Debug, Clone, PartialEq, Eq, Default, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ChangeJava {
+    /// 建议的大版本（17 / 21 …）。
+    #[serde(default)]
+    pub required_major: Option<u32>,
+    /// 允许的最高大版本（老 Forge 只能用 Java 8 时给 `8`）。
+    #[serde(default)]
+    pub max_major: Option<u32>,
+    /// 从该命名捕获组取 `class file version N`，按 `N - 44` 换算成 Java 大版本。
+    #[serde(default)]
+    pub class_file_version_group: Option<String>,
+    /// JVM 实现偏好。
+    #[serde(default)]
+    pub vendor: JavaVendor,
+    /// 给用户看的补充说明。
+    #[serde(default)]
+    pub note: Option<String>,
+}
+
+/// 调内存的参数。
+#[derive(Debug, Clone, PartialEq, Eq, Default, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct AdjustMemory {
+    /// 建议的 `-Xmx`（MB）；规则不确定时留空，由 UI 按物理内存算。
+    #[serde(default)]
+    pub suggested_xmx_mb: Option<u32>,
+    /// `-Xmx` 的下限（MB）。
+    #[serde(default)]
+    pub min_xmx_mb: Option<u32>,
+    /// 需要 32 位 → 64 位 Java（「Could not reserve enough space」类）。
+    #[serde(default)]
+    pub need_64bit_java: bool,
+    /// 需要用户扩大系统虚拟内存 / 关掉占内存的程序。
+    #[serde(default)]
+    pub increase_system_swap: bool,
+    /// 补充说明。
+    #[serde(default)]
+    pub note: Option<String>,
+}
+
+/// 改图形设置的参数。
+#[derive(Debug, Clone, PartialEq, Eq, Default, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ChangeGraphics {
+    /// 要改的设置类别。
+    #[serde(default)]
+    pub setting: GraphicsSetting,
+    /// 建议更新显卡驱动。
+    #[serde(default)]
+    pub update_driver: bool,
+    /// 建议的目标值（如 `854x480`、`OpenGL 兼容模式`）。
+    #[serde(default)]
+    pub suggested_value: Option<String>,
+    /// 补充说明。
+    #[serde(default)]
+    pub note: Option<String>,
+}
+
+/// 删/禁/换 mod 的参数。
+#[derive(Debug, Clone, PartialEq, Eq, Default, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct RemoveMod {
+    /// modid 列表，允许 `{group}` 模板（由规则命名捕获组代入）。
+    #[serde(default)]
+    pub mod_ids: Vec<String>,
+    /// 处理方式。
+    #[serde(default)]
+    pub action: ModAction,
+    /// 补充说明。
+    #[serde(default)]
+    pub note: Option<String>,
+}
+
+/// 重装/修组件的参数。
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Reinstall {
+    /// 要修的组件。
+    pub component: ComponentKind,
+    /// 出问题的路径提示（来自规则捕获组或原文）。
+    #[serde(default)]
+    pub path_hint: Option<String>,
+    /// 补充说明。
+    #[serde(default)]
+    pub note: Option<String>,
+}
+
+/// 求助/上报的参数。
+#[derive(Debug, Clone, PartialEq, Eq, Default, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct SeekHelp {
+    /// 建议导出诊断包（日志 + 崩溃报告 + 清单 + 环境）。
+    #[serde(default)]
+    pub export_diagnostics: bool,
+    /// 还需要用户补充什么（「把日志上限调到 20000 行再复现」）。
+    #[serde(default)]
+    pub needs_more_info: Vec<String>,
+    /// 补充说明。
+    #[serde(default)]
+    pub note: Option<String>,
+}
diff --git a/crates/core/src/diagnose/hs_err.rs b/crates/core/src/diagnose/hs_err.rs
new file mode 100644
index 0000000..24e4ae5
--- /dev/null
+++ b/crates/core/src/diagnose/hs_err.rs
@@ -0,0 +1,298 @@
+//! `hs_err_pid*.log`（JVM 致命错误日志）解析器。
+//!
+//! HMCL 完全不解析它（analyse/02 §7.10-8），而 `EXCEPTION_ACCESS_VIOLATION` 这类问题
+//! 只有这份文件能给出权威证据（失败帧落在显卡驱动 DLL 里就是驱动问题）。
+//! 格式稳定：**标题行 + 线程段 + 内存段**，本模块只做容错抽取，字段全部 `Option`，永不失败。
+//!
+//! 用法（launch 对接见 `CONTRACT.md` §5）：
+//! - `parse(&text)`：已有全文时用（首选，避免二次截断）；
+//! - `parse_file(&path)`：给路径时用；
+//! - [`HsErrReport::digest`] 产出的摘要既是规则匹配的文本，也是给它人看的证据。
+
+use std::fs;
+use std::io;
+use std::path::Path;
+
+#[path = "hs_err_report.rs"]
+mod report;
+
+pub use report::{FailedFrame, FrameKind, HsErrKind, HsErrReport, MemorySummary};
+
+/// 解析文本（永不失败；无法识别的行直接跳过）。
+#[must_use]
+pub fn parse(text: &str) -> HsErrReport {
+    let mut report = HsErrReport::default();
+    let lines = text.lines().collect::<Vec<_>>();
+
+    for (index, raw) in lines.iter().enumerate() {
+        let line = raw.trim_end_matches('\r');
+        let body = line.trim_start_matches('#').trim();
+        if report.header.is_none() && is_header(body) {
+            report.header = Some(body.to_owned());
+        }
+        if report.exception.is_none() {
+            report.exception = extract_exception(body);
+        }
+        if report.siginfo.is_none() && body.starts_with("siginfo:") {
+            report.siginfo = Some(body.to_owned());
+        }
+        if report.signal.is_none() {
+            report.signal = body
+                .contains("si_signo:")
+                .then(|| body.to_owned())
+                .or_else(|| extract_signal(body));
+        }
+        if report.jre_version.is_none() && body.contains("JRE version:") {
+            report.jre_version = Some(body.to_owned());
+        }
+        if report.java_vm.is_none() && body.contains("Java VM:") {
+            report.java_vm = Some(body.to_owned());
+        }
+        if report.os.is_none() && body.starts_with("OS:") {
+            report.os = Some(body.to_owned());
+        }
+        if report.command_line.is_none() && body.starts_with("java_command:") {
+            report.command_line = Some(body.to_owned());
+        }
+        if report.current_thread.is_none() && body.starts_with("Current thread (") {
+            report.current_thread = Some(body.to_owned());
+        }
+        if report.memory.is_none() && body.starts_with("Memory:") {
+            report.memory = parse_memory(body);
+        }
+        if report.failed_frame.is_none() && body.eq_ignore_ascii_case("Problematic frame:") {
+            report.failed_frame = lines
+                .iter()
+                .skip(index + 1)
+                .map(|next| next.trim_end_matches('\r'))
+                .find(|next| !next.trim().is_empty() && next.trim() != "#")
+                .map(|next| parse_frame(next.trim_start_matches('#').trim()));
+        }
+        if report.pc.is_none() && body.contains("pc=") {
+            report.pc = field(body, "pc=");
+        }
+        if report.pid.is_none() && body.contains("pid=") {
+            report.pid = field(body, "pid=").and_then(|raw| raw.parse::<u32>().ok());
+        }
+        if report.tid.is_none() && body.contains("tid=") {
+            report.tid = field(body, "tid=");
+        }
+        if body.eq_ignore_ascii_case("VM Arguments:") {
+            // 真实 hs_err 里 jvm_args/java_command 是顶格写的，不缩进
+            report.vm_arguments = collect_unindented(&lines, index + 1, 32);
+        }
+        if body.starts_with("Heap:") {
+            // "Heap:" 之后的缩进行才是内容（garbage-first heap total … used …）
+            report.heap = collect_block(&lines, index + 1, 6);
+        }
+    }
+
+    report.header_lines = collect_header_block(&lines);
+    report.pc = report
+        .exception
+        .as_deref()
+        .and_then(|line| field(line, "pc="))
+        .or(report.pc);
+    // pid/tid 在「异常行」和「Out of Memory Error (os_*.cpp:NNN), pid=…」两种标题里都出现，
+    // 所以两种形态都认，先到先得。
+    if report.pid.is_none() {
+        report.pid = report
+            .exception
+            .as_deref()
+            .and_then(|line| field(line, "pid="))
+            .and_then(|raw| raw.parse::<u32>().ok());
+    }
+    if report.tid.is_none() {
+        report.tid = report
+            .exception
+            .as_deref()
+            .and_then(|line| field(line, "tid="));
+    }
+    report.kind = classify(&report);
+    report
+}
+
+/// 读文件并解析（非 UTF-8 字节按 U+FFFD 替换，不报错）。
+pub fn parse_file(path: impl AsRef<Path>) -> io::Result<HsErrReport> {
+    let path = path.as_ref();
+    let bytes = fs::read(path)?;
+    let text = String::from_utf8_lossy(&bytes);
+    let mut report = parse(&text);
+    report.path = Some(path.to_path_buf());
+    Ok(report)
+}
+
+fn is_header(body: &str) -> bool {
+    const MARKERS: [&str; 5] = [
+        "insufficient memory",
+        "A fatal error has been detected",
+        "Out of Memory Error",
+        "Internal Error",
+        "SIGSEGV",
+    ];
+    MARKERS.iter().any(|marker| body.contains(marker))
+}
+
+fn extract_exception(body: &str) -> Option<String> {
+    let marker = "EXCEPTION_";
+    let start = body.find(marker)?;
+    let rest = &body[start..];
+    let end = rest
+        .find(" at pc=")
+        .or_else(|| rest.find(", pid="))
+        .unwrap_or(rest.len());
+    Some(rest[..end].trim().to_owned())
+}
+
+fn extract_signal(body: &str) -> Option<String> {
+    let start = body.find("SIG")?;
+    let rest = &body[start..];
+    let end = rest.find(')').map_or(rest.len(), |index| index + 1);
+    Some(rest[..end].trim().to_owned())
+}
+
+/// 从 `key=value` 形态里取值（到下一个空格/逗号为止）。
+fn field(line: &str, key: &str) -> Option<String> {
+    let start = line.find(key)? + key.len();
+    let rest = &line[start..];
+    let end = rest.find([' ', ',', ']']).unwrap_or(rest.len());
+    let value = rest[..end].trim();
+    (!value.is_empty()).then(|| value.to_owned())
+}
+
+fn parse_frame(raw: &str) -> FailedFrame {
+    let kind = match raw.chars().next() {
+        Some('C') => FrameKind::Native,
+        Some('J' | 'j') => FrameKind::Java,
+        Some('V') => FrameKind::VmStub,
+        _ => FrameKind::Unknown,
+    };
+    let (module, offset) = raw
+        .find('[')
+        .and_then(|start| {
+            let inner = &raw[start + 1..];
+            let inner = &inner[..inner.find(']')?];
+            let mut parts = inner.split('+');
+            let module = parts.next().map(str::trim).filter(|m| !m.is_empty())?;
+            Some((
+                Some(module.to_owned()),
+                parts.next().map(|o| o.trim().to_owned()),
+            ))
+        })
+        .unwrap_or((None, None));
+    FailedFrame {
+        raw: raw.to_owned(),
+        kind,
+        module,
+        offset,
+    }
+}
+
+fn parse_memory(body: &str) -> Option<MemorySummary> {
+    let mut summary = MemorySummary {
+        raw: body.to_owned(),
+        ..MemorySummary::default()
+    };
+    for part in body.split(',') {
+        let part = part.trim();
+        if part.contains("page") {
+            summary.page_size = part
+                .trim_start_matches("Memory:")
+                .split_whitespace()
+                .next()
+                .map(|value| value.trim_end_matches(',').to_owned());
+        } else if part.starts_with("physical") {
+            let (total, free) = parse_kb_pair(part);
+            summary.physical_kb = total;
+            summary.physical_free_kb = free;
+        } else if part.starts_with("swap") {
+            let (total, free) = parse_kb_pair(part);
+            summary.swap_kb = total;
+            summary.swap_free_kb = free;
+        }
+    }
+    Some(summary)
+}
+
+/// `physical 16741480k(4716856k free)` → (16741480, 4716856)。
+fn parse_kb_pair(part: &str) -> (Option<u64>, Option<u64>) {
+    let numbers = part
+        .split(|ch: char| !ch.is_ascii_digit())
+        .filter(|token| !token.is_empty())
+        .filter_map(|token| token.parse::<u64>().ok())
+        .collect::<Vec<_>>();
+    (numbers.first().copied(), numbers.get(1).copied())
+}
+
+/// 取从 `start` 开始、到第一个空行为止的连续行（VM Arguments / java_command 段）。
+fn collect_unindented(lines: &[&str], start: usize, limit: usize) -> Vec<String> {
+    lines
+        .iter()
+        .skip(start)
+        .map(|line| line.trim_end_matches('\r'))
+        .take_while(|line| !line.trim().is_empty())
+        .take(limit)
+        .map(|line| line.trim().to_owned())
+        .collect()
+}
+
+/// 取从 `start` 开始、以空白/制表缩进的连续行（最多 `limit` 行）。
+fn collect_block(lines: &[&str], start: usize, limit: usize) -> Vec<String> {
+    lines
+        .iter()
+        .skip(start)
+        .map(|line| line.trim_end_matches('\r'))
+        .skip_while(|line| line.trim().is_empty())
+        .take_while(|line| line.starts_with([' ', '\t']))
+        .take(limit)
+        .map(|line| line.trim().to_owned())
+        .collect()
+}
+
+/// 文件开头的 `#` 注释块（真实 hs_err 的标题/异常/失败帧都在这里）。
+fn collect_header_block(lines: &[&str]) -> Vec<String> {
+    let mut out = Vec::new();
+    for line in lines {
+        let line = line.trim_end_matches('\r');
+        let trimmed = line.trim();
+        if trimmed.is_empty() || trimmed.starts_with('#') {
+            if trimmed.starts_with('#') {
+                out.push(trimmed.to_owned());
+            }
+        } else {
+            break;
+        }
+        if out.len() >= 64 {
+            break;
+        }
+    }
+    out
+}
+
+fn classify(report: &HsErrReport) -> HsErrKind {
+    let haystack = [
+        report.header.as_deref(),
+        report.exception.as_deref(),
+        report.siginfo.as_deref(),
+    ]
+    .into_iter()
+    .flatten()
+    .collect::<Vec<_>>()
+    .join("\n");
+    if haystack.contains("EXCEPTION_ACCESS_VIOLATION") || haystack.contains("SIGSEGV") {
+        HsErrKind::AccessViolation
+    } else if haystack.contains("insufficient memory")
+        || haystack.contains("Out of Memory")
+        || haystack.contains("OutOfMemory")
+    {
+        HsErrKind::OutOfMemory
+    } else if haystack.contains("StackOverflow") || haystack.contains("stack overflow") {
+        HsErrKind::StackOverflow
+    } else if haystack.contains("Internal Error")
+        || haystack.contains("A fatal error has been detected")
+    {
+        HsErrKind::InternalError
+    } else {
+        HsErrKind::Other
+    }
+}
diff --git a/crates/core/src/diagnose/hs_err_report.rs b/crates/core/src/diagnose/hs_err_report.rs
new file mode 100644
index 0000000..a4bb49b
--- /dev/null
+++ b/crates/core/src/diagnose/hs_err_report.rs
@@ -0,0 +1,210 @@
+//! `hs_err_pid*.log` 解析结果的数据结构（标题行 / 线程段 / 内存段 / 失败帧）。
+//!
+//! 由 `hs_err.rs` 用 `#[path]` 声明并重新导出；拆分只为守单文件 400 行上限。
+
+use std::fmt;
+use std::path::PathBuf;
+
+/// hs_err 的崩溃类别（标题行/异常名归并成少数几类，供内置结论判定）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum HsErrKind {
+    /// `EXCEPTION_ACCESS_VIOLATION` / `SIGSEGV`：野指针，显卡驱动/原生库最常见。
+    AccessViolation,
+    /// 内存不足（`insufficient memory` / `Out of Memory Error`）。
+    OutOfMemory,
+    /// 栈溢出。
+    StackOverflow,
+    /// JVM 内部致命错误（`Internal Error` / `A fatal error has been detected`）。
+    InternalError,
+    /// 其它 / 无法归类。
+    #[default]
+    Other,
+}
+
+impl HsErrKind {
+    /// 稳定字符串。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::AccessViolation => "access_violation",
+            Self::OutOfMemory => "out_of_memory",
+            Self::StackOverflow => "stack_overflow",
+            Self::InternalError => "internal_error",
+            Self::Other => "other",
+        }
+    }
+}
+
+impl fmt::Display for HsErrKind {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+/// 失败帧的类型（`# C` 原生码、`# J`/`# j` Java 帧、`# V` VM 生成桩帧）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum FrameKind {
+    /// 原生（C/C++）帧：出现在显卡驱动/OpenGL 里基本可判定驱动问题。
+    Native,
+    /// Java 帧（`# J` / `# j`，二者区别是解释执行还是编译执行，诊断不需要再细分）。
+    Java,
+    /// VM 生成桩帧（`# V`）：JIT/解释器生成的运行时代码，不是用户代码。
+    VmStub,
+    /// 未识别。
+    #[default]
+    Unknown,
+}
+
+impl FrameKind {
+    /// 稳定字符串。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Native => "native",
+            Self::Java => "java",
+            Self::VmStub => "vm_stub",
+            Self::Unknown => "unknown",
+        }
+    }
+}
+
+/// `# Problematic frame:` 之后的那一行。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct FailedFrame {
+    /// 原始文本（`C  [ig8d64.dll+0x9b3c4d]`）。
+    pub raw: String,
+    /// 帧类型。
+    pub kind: FrameKind,
+    /// 命中的模块/DLL（`ig8d64.dll`）。
+    pub module: Option<String>,
+    /// 模块内偏移（`0x9b3c4d`）。
+    pub offset: Option<String>,
+}
+
+/// 内存段摘要（`Memory: 4k page, physical …, swap …`）。
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct MemorySummary {
+    /// 页大小（`4k`）。
+    pub page_size: Option<String>,
+    /// 物理内存 kB。
+    pub physical_kb: Option<u64>,
+    /// 物理可用 kB。
+    pub physical_free_kb: Option<u64>,
+    /// 交换区 kB。
+    pub swap_kb: Option<u64>,
+    /// 交换区可用 kB。
+    pub swap_free_kb: Option<u64>,
+    /// 原始行。
+    pub raw: String,
+}
+
+impl MemorySummary {
+    /// 一行人类可读摘要（GB 保留一位小数）。
+    #[must_use]
+    pub fn summary(&self) -> String {
+        let gb = |kb: Option<u64>| {
+            kb.map(|kb| format!("{:.1} GB", kb as f64 / 1024.0 / 1024.0))
+                .unwrap_or_else(|| "?".to_owned())
+        };
+        format!(
+            "物理内存 {}（可用 {}），交换区 {}（可用 {}）",
+            gb(self.physical_kb),
+            gb(self.physical_free_kb),
+            gb(self.swap_kb),
+            gb(self.swap_free_kb)
+        )
+    }
+}
+
+/// 解析结果。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct HsErrReport {
+    /// 来源文件（`parse` 时为 `None`）。
+    pub path: Option<PathBuf>,
+    /// 标题行（`#[derive(Default)]` 之外的语义见 `parse`）。
+    pub header: Option<String>,
+    /// 崩溃类别。
+    pub kind: HsErrKind,
+    /// 异常名（`EXCEPTION_ACCESS_VIOLATION (0xc0000005)`）。
+    pub exception: Option<String>,
+    /// `siginfo:` 行（Unix 侧带 si_signo / si_addr）。
+    pub siginfo: Option<String>,
+    /// 信号名（`SIGSEGV (0xb)`）。
+    pub signal: Option<String>,
+    /// 出错时的指令指针。
+    pub pc: Option<String>,
+    /// 进程 pid。
+    pub pid: Option<u32>,
+    /// 线程 tid（保留原始十六进制/十进制串）。
+    pub tid: Option<String>,
+    /// 失败帧。
+    pub failed_frame: Option<FailedFrame>,
+    /// 当前线程（`JavaThread "Render thread" [_thread_in_native, id=…]`）。
+    pub current_thread: Option<String>,
+    /// JRE 版本行内容。
+    pub jre_version: Option<String>,
+    /// JVM 实现行内容。
+    pub java_vm: Option<String>,
+    /// 操作系统行内容。
+    pub os: Option<String>,
+    /// `java_command` 行。
+    pub command_line: Option<String>,
+    /// `VM Arguments:` 段的参数行。
+    pub vm_arguments: Vec<String>,
+    /// 内存段摘要。
+    pub memory: Option<MemorySummary>,
+    /// `Heap:` 段的前几行（原样，含 total/used）。
+    pub heap: Vec<String>,
+    /// 标题块原文（逐行保留 `#` 前缀，规则可以直接在上面匹配）。
+    pub header_lines: Vec<String>,
+}
+
+impl HsErrReport {
+    /// 供规则匹配 / 证据展示的摘要文本。
+    ///
+    /// 保留标题块原文（`EXCEPTION_ACCESS_VIOLATION` 与 `# C  [ig…dll]` 的相对位置不变，
+    /// 因此 `graphics.graphics_driver` 这类跨行规则可以直接命中），再补上线程/内存段要点。
+    #[must_use]
+    pub fn digest(&self) -> String {
+        let mut out = String::new();
+        for line in &self.header_lines {
+            out.push_str(line);
+            out.push('\n');
+        }
+        for line in [
+            self.siginfo.as_deref(),
+            self.current_thread.as_deref(),
+            self.jre_version.as_deref(),
+            self.java_vm.as_deref(),
+            self.os.as_deref(),
+            self.command_line.as_deref(),
+        ]
+        .into_iter()
+        .flatten()
+        {
+            out.push_str(line);
+            out.push('\n');
+        }
+        for line in &self.heap {
+            out.push_str(line);
+            out.push('\n');
+        }
+        if let Some(memory) = &self.memory {
+            out.push_str(&memory.raw);
+            out.push('\n');
+        }
+        out
+    }
+
+    /// 一句话摘要（诊断输出 / UI 头部）。
+    #[must_use]
+    pub fn summary(&self) -> String {
+        let kind = self.kind.as_str();
+        let frame = self
+            .failed_frame
+            .as_ref()
+            .map_or_else(String::new, |frame| format!("，失败帧 {}", frame.raw));
+        let header = self.header.as_deref().unwrap_or("JVM 致命错误");
+        format!("{header}（{kind}{frame}）")
+    }
+}
diff --git a/crates/core/src/diagnose/loader.rs b/crates/core/src/diagnose/loader.rs
new file mode 100644
index 0000000..7cdb8fa
--- /dev/null
+++ b/crates/core/src/diagnose/loader.rs
@@ -0,0 +1,398 @@
+//! 规则库加载：YAML 分组文件 + 内嵌兜底 + 热重载。
+//!
+//! 对应 PlanDoc/06 §2.2「规则文件 YAML 外置可热更」（修 HMCL 编译期枚举不可热更的债）：
+//! 1. 内嵌一份（`include_str!`）：任何情况下都能诊断，不依赖安装目录完整；
+//! 2. 用户目录 `data/diagnose/rules.d/*.yaml` 覆盖内嵌的同名文件（缺哪个用内嵌补哪个）；
+//! 3. 热重载是 **mtime+size 指纹轮询**（[`RuleLoader::refresh`]），不引 `notify` 依赖；
+//!    解析失败时**保留上一份好规则**并返回错误列表——用户手改错 YAML 不会让诊断能力归零。
+
+use std::collections::hash_map::DefaultHasher;
+use std::collections::HashSet;
+use std::fmt;
+use std::fs;
+use std::hash::{Hash, Hasher};
+use std::path::{Path, PathBuf};
+
+use serde::Deserialize;
+
+use super::rules::{CompiledRule, Rule, RuleCategory};
+
+/// 规则目录（相对数据根，由 platform 模块解析）。
+pub const RULES_DIR: &str = "diagnose/rules.d";
+
+/// 规则 schema 版本（文件里 `version: 1`）。
+pub const SCHEMA_VERSION: u32 = 1;
+
+/// 内嵌规则库：`(文件名, 内容)`。按分类拆文件，每文件守 400 行上限。
+pub const EMBEDDED_RULES: &[(&str, &str)] = &[
+    ("jvm.yaml", include_str!("rules.d/jvm.yaml")),
+    ("memory.yaml", include_str!("rules.d/memory.yaml")),
+    ("graphics.yaml", include_str!("rules.d/graphics.yaml")),
+    ("integrity.yaml", include_str!("rules.d/integrity.yaml")),
+    ("fabric.yaml", include_str!("rules.d/fabric.yaml")),
+    ("forge.yaml", include_str!("rules.d/forge.yaml")),
+    ("mod_runtime.yaml", include_str!("rules.d/mod_runtime.yaml")),
+    (
+        "mod_conflict.yaml",
+        include_str!("rules.d/mod_conflict.yaml"),
+    ),
+    ("world.yaml", include_str!("rules.d/world.yaml")),
+    ("other.yaml", include_str!("rules.d/other.yaml")),
+];
+
+/// 一个 YAML 文件的 schema。
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct RuleFile {
+    #[serde(default)]
+    version: u32,
+    category: RuleCategory,
+    rules: Vec<Rule>,
+}
+
+/// 编译好的规则集（字段私有，只能经 loader 构造，保证「id 唯一 + 正则可编译」）。
+#[derive(Debug, Clone, Default)]
+pub struct RuleSet {
+    rules: Vec<CompiledRule>,
+}
+
+impl RuleSet {
+    /// 规则表。
+    #[must_use]
+    pub fn rules(&self) -> &[CompiledRule] {
+        &self.rules
+    }
+
+    /// 规则条数。
+    #[must_use]
+    pub fn len(&self) -> usize {
+        self.rules.len()
+    }
+
+    /// 是否空规则集。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.rules.is_empty()
+    }
+
+    /// 按 id 查规则（测试 / 调试用）。
+    #[must_use]
+    pub fn get(&self, id: &str) -> Option<&CompiledRule> {
+        self.rules.iter().find(|rule| rule.id() == id)
+    }
+
+    /// 从 `(文件名, 内容)` 列表编译；有任何错误就整体失败（调用方决定是否回退）。
+    pub fn from_sources(sources: &[(String, String)]) -> Result<Self, Vec<LoadError>> {
+        let mut errors = Vec::new();
+        let mut rules: Vec<CompiledRule> = Vec::new();
+        let mut seen: HashSet<String> = HashSet::new();
+        for (file, text) in sources {
+            let parsed = match serde_yaml_ng::from_str::<RuleFile>(text) {
+                Ok(parsed) => parsed,
+                Err(error) => {
+                    errors.push(LoadError::yaml(file, &error));
+                    continue;
+                }
+            };
+            if parsed.version > SCHEMA_VERSION {
+                errors.push(LoadError {
+                    file: file.clone(),
+                    kind: LoadErrorKind::UnsupportedVersion,
+                    message: format!(
+                        "规则文件 version={} 高于本程序支持的 {}",
+                        parsed.version, SCHEMA_VERSION
+                    ),
+                });
+                continue;
+            }
+            for rule in parsed.rules {
+                if !seen.insert(rule.id.clone()) {
+                    errors.push(LoadError {
+                        file: file.clone(),
+                        kind: LoadErrorKind::DuplicateId,
+                        message: format!("规则 id 重复：{}", rule.id),
+                    });
+                    continue;
+                }
+                match CompiledRule::compile(rule, parsed.category) {
+                    Ok(compiled) => rules.push(compiled),
+                    Err(error) => errors.push(LoadError {
+                        file: file.clone(),
+                        kind: LoadErrorKind::Regex,
+                        message: error.to_string(),
+                    }),
+                }
+            }
+        }
+        if errors.is_empty() {
+            Ok(Self { rules })
+        } else {
+            Err(errors)
+        }
+    }
+}
+
+/// 加载错误分类。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum LoadErrorKind {
+    /// 读盘失败。
+    Io,
+    /// YAML 语法/schema 错误（`serde_yaml_ng` 的报错带行号）。
+    Yaml,
+    /// 正则编译失败。
+    Regex,
+    /// 规则 id 跨文件重复。
+    DuplicateId,
+    /// 规则文件版本高于本程序。
+    UnsupportedVersion,
+}
+
+impl LoadErrorKind {
+    /// 稳定字符串。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Io => "io",
+            Self::Yaml => "yaml",
+            Self::Regex => "regex",
+            Self::DuplicateId => "duplicate_id",
+            Self::UnsupportedVersion => "unsupported_version",
+        }
+    }
+}
+
+/// 一条加载错误（带文件名，用户改 YAML 时能定位）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LoadError {
+    /// 文件名（磁盘目录加载时是完整路径）。
+    pub file: String,
+    /// 分类。
+    pub kind: LoadErrorKind,
+    /// 报错原文（YAML 错误含行号）。
+    pub message: String,
+}
+
+impl LoadError {
+    fn yaml(file: &str, error: &serde_yaml_ng::Error) -> Self {
+        Self {
+            file: file.to_owned(),
+            kind: LoadErrorKind::Yaml,
+            message: error.to_string(),
+        }
+    }
+
+    fn io(file: &Path, error: &std::io::Error) -> Self {
+        Self {
+            file: file.display().to_string(),
+            kind: LoadErrorKind::Io,
+            message: error.to_string(),
+        }
+    }
+}
+
+impl fmt::Display for LoadError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(
+            f,
+            "[{}] {}：{}",
+            self.kind.as_str(),
+            self.file,
+            self.message
+        )
+    }
+}
+
+impl std::error::Error for LoadError {}
+
+/// 热重载结果。
+#[derive(Debug, Clone, PartialEq)]
+pub enum ReloadOutcome {
+    /// 指纹没变，规则未动。
+    Unchanged,
+    /// 重新加载成功。
+    Reloaded {
+        /// 新规则条数。
+        rules: usize,
+    },
+    /// 新文件有错：**保留旧规则**，错误交给调用方展示。
+    Rejected {
+        /// 错误列表。
+        errors: Vec<LoadError>,
+    },
+}
+
+/// 规则库加载器（持有当前生效的规则集 + 目录指纹）。
+#[derive(Debug, Clone)]
+pub struct RuleLoader {
+    dir: Option<PathBuf>,
+    set: RuleSet,
+    fingerprint: u64,
+    last_errors: Vec<LoadError>,
+}
+
+impl Default for RuleLoader {
+    fn default() -> Self {
+        Self::embedded()
+    }
+}
+
+impl RuleLoader {
+    /// 只用内嵌规则（无磁盘目录）。
+    #[must_use]
+    pub fn embedded() -> Self {
+        let sources = embedded_sources();
+        let (set, errors) = compile_sources(&sources);
+        Self {
+            dir: None,
+            set,
+            fingerprint: 0,
+            last_errors: errors,
+        }
+    }
+
+    /// 以磁盘目录为准、内嵌补齐缺文件。
+    ///
+    /// 磁盘规则有任何错误时**退回内嵌规则**并记录错误（保证永远有可用规则集）。
+    #[must_use]
+    pub fn from_dir(dir: impl Into<PathBuf>) -> Self {
+        let dir = dir.into();
+        let (sources, mut errors) = merged_sources(Some(&dir));
+        let set = match RuleSet::from_sources(&sources) {
+            Ok(set) => set,
+            Err(mut load_errors) => {
+                errors.append(&mut load_errors);
+                RuleSet::from_sources(&embedded_sources()).unwrap_or_default()
+            }
+        };
+        Self {
+            fingerprint: dir_fingerprint(&dir),
+            dir: Some(dir),
+            set,
+            last_errors: errors,
+        }
+    }
+
+    /// 当前生效的规则。
+    #[must_use]
+    pub fn rules(&self) -> &[CompiledRule] {
+        self.set.rules()
+    }
+
+    /// 当前生效的规则集。
+    #[must_use]
+    pub fn rule_set(&self) -> &RuleSet {
+        &self.set
+    }
+
+    /// 上次加载留下的错误（UI 可提示「你的规则文件有错，已用内置规则」）。
+    #[must_use]
+    pub fn last_errors(&self) -> &[LoadError] {
+        &self.last_errors
+    }
+
+    /// 规则目录（内嵌模式为 `None`）。
+    #[must_use]
+    pub fn dir(&self) -> Option<&Path> {
+        self.dir.as_deref()
+    }
+
+    /// 目录指纹（测试用：确认 mtime/size 变化真的改变了指纹）。
+    #[must_use]
+    pub fn fingerprint(&self) -> u64 {
+        self.fingerprint
+    }
+
+    /// 轮询热重载：指纹变了才重新解析。
+    pub fn refresh(&mut self) -> ReloadOutcome {
+        let Some(dir) = self.dir.clone() else {
+            return ReloadOutcome::Unchanged;
+        };
+        let fingerprint = dir_fingerprint(&dir);
+        if fingerprint == self.fingerprint {
+            return ReloadOutcome::Unchanged;
+        }
+        self.fingerprint = fingerprint;
+        let (sources, mut errors) = merged_sources(Some(&dir));
+        match RuleSet::from_sources(&sources) {
+            Ok(set) => {
+                self.set = set;
+                self.last_errors = errors;
+                ReloadOutcome::Reloaded {
+                    rules: self.set.len(),
+                }
+            }
+            Err(mut load_errors) => {
+                errors.append(&mut load_errors);
+                self.last_errors = errors.clone();
+                ReloadOutcome::Rejected { errors }
+            }
+        }
+    }
+}
+
+fn embedded_sources() -> Vec<(String, String)> {
+    EMBEDDED_RULES
+        .iter()
+        .map(|(name, text)| ((*name).to_owned(), (*text).to_owned()))
+        .collect()
+}
+
+/// 磁盘文件覆盖内嵌：磁盘有的用磁盘，没的用内嵌。
+fn merged_sources(dir: Option<&Path>) -> (Vec<(String, String)>, Vec<LoadError>) {
+    let mut sources = Vec::new();
+    let mut errors = Vec::new();
+    for (name, embedded) in EMBEDDED_RULES {
+        let path = dir.map(|dir| dir.join(name));
+        match path {
+            Some(path) if path.is_file() => match fs::read_to_string(&path) {
+                Ok(text) => sources.push((path.display().to_string(), text)),
+                Err(error) => {
+                    errors.push(LoadError::io(&path, &error));
+                    sources.push(((*name).to_owned(), (*embedded).to_owned()));
+                }
+            },
+            _ => sources.push(((*name).to_owned(), (*embedded).to_owned())),
+        }
+    }
+    (sources, errors)
+}
+
+fn compile_sources(sources: &[(String, String)]) -> (RuleSet, Vec<LoadError>) {
+    match RuleSet::from_sources(sources) {
+        Ok(set) => (set, Vec::new()),
+        Err(errors) => (RuleSet::default(), errors),
+    }
+}
+
+/// 目录指纹：所有 `*.yaml` 的（文件名, 长度, mtime）之和。
+///
+/// 长度 + mtime 足以发现「保存了但秒级 mtime 未变」之外的一切编辑；漏检时用户点刷新即可。
+fn dir_fingerprint(dir: &Path) -> u64 {
+    let mut entries = fs::read_dir(dir)
+        .map(|entries| {
+            entries
+                .flatten()
+                .map(|entry| entry.path())
+                .filter(|path| {
+                    path.extension()
+                        .is_some_and(|ext| ext.eq_ignore_ascii_case("yaml"))
+                })
+                .collect::<Vec<_>>()
+        })
+        .unwrap_or_default();
+    entries.sort();
+    let mut hasher = DefaultHasher::new();
+    for path in entries {
+        path.file_name().unwrap_or_default().hash(&mut hasher);
+        if let Ok(metadata) = fs::metadata(&path) {
+            metadata.len().hash(&mut hasher);
+            metadata
+                .modified()
+                .ok()
+                .and_then(|time| time.duration_since(std::time::UNIX_EPOCH).ok())
+                .map(|duration| duration.as_nanos())
+                .hash(&mut hasher);
+        }
+    }
+    hasher.finish()
+}
diff --git a/crates/core/src/diagnose/mod.rs b/crates/core/src/diagnose/mod.rs
new file mode 100644
index 0000000..d026f43
--- /dev/null
+++ b/crates/core/src/diagnose/mod.rs
@@ -0,0 +1,17 @@
+//! 崩溃诊断：五类信号采集（含 hs_err_pid 解析）、YAML 规则引擎（59 条规则起步，可热更新）、
+//! exit0 静默失败检测、结构化诊断结论。
+//!
+//! 设计定稿：`DevDocs/PlanDoc/06-launch-and-diagnostics.md` §2（采集 / 规则 / 流水线）。
+//! 定位：规则引擎为主、AI 补位；AI 拿到的应是「规则结论 + 相关片段」而非裸日志
+//! （`DevDocs/PlanDoc/02-ai-agent-design.md` §3.2）。
+//!
+//! 规划中的公共面（M15）：信号采集、规则匹配、诊断报告、规则热加载。
+
+// 只有这五个顶层模块；子模块（collectors 下的 signals/sources/environment、engine 下的
+// finding/synthetic、hs_err 下的 hs_err_report、rules 下的 fix_action/fix_params）由各自的
+// 父文件用 #[path] 声明。这里**不要**重复声明，否则同一文件会被编译成两份不同类型。
+pub mod collectors;
+pub mod engine;
+pub mod hs_err;
+pub mod loader;
+pub mod rules;
diff --git a/crates/core/src/diagnose/rules.d/fabric.yaml b/crates/core/src/diagnose/rules.d/fabric.yaml
new file mode 100644
index 0000000..9a9db85
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/fabric.yaml
@@ -0,0 +1,141 @@
+# 规则库 · Fabric mod 解析（8 条）
+# 移植自 HMCL CrashReportAnalyzer.Rule 的 Fabric 组（analyse/02 §7.3 第 5 组）。
+# Fabric 的 ModResolutionException 家族特征：异常后面跟一段以 " - " 开头的列表，
+# 因此这些规则用 file scope（跨行）。
+version: 1
+category: fabric
+rules:
+  - id: fabric.mod_resolution
+    severity: critical
+    scope: file
+    pattern: 'ModResolutionException: (?<reason>(.*)[\n\r]*( - (.*)[\n\r]*)+)'
+    confidence: 0.75
+    priority: 70
+    cause:
+      key: diagnose.cause.fabric.mod_resolution
+      summary: 'Fabric 解析 mod 依赖失败（缺依赖/版本冲突/模组不配套）'
+      detail: '按下方列出的 mod 名单逐个处理：缺依赖就补装，冲突就删一个'
+    fix_action:
+      - kind: remove_mod
+        action: disable
+        note: '按 Fabric 报的 mod 名单逐个禁用排查'
+    sample: samples/fabric/mod_resolution.log
+    source: 'HMCL CrashReportAnalyzer.Rule.MOD_RESOLUTION'
+
+  - id: fabric.mod_resolution_conflict
+    severity: critical
+    pattern: 'ModResolutionException: Found conflicting mods: (?<sourcemod>.*) conflicts with (?<destmod>.*)'
+    confidence: 0.92
+    priority: 86
+    suppress:
+      - integrity.no_class_def_found
+      - integrity.no_such_method
+    cause:
+      key: diagnose.cause.fabric.mod_resolution_conflict
+      summary: 'Fabric 报告 mod 冲突：{sourcemod} 与 {destmod} 不能共存'
+      detail: '两个只能留一个（或都升级到互相兼容的版本）'
+    fix_action:
+      - kind: remove_mod
+        mod_ids:
+          - '{sourcemod}'
+          - '{destmod}'
+        action: remove
+    sample: samples/fabric/mod_resolution_conflict.log
+    source: 'HMCL CrashReportAnalyzer.Rule.MOD_RESOLUTION_CONFLICT'
+
+  - id: fabric.mod_resolution_missing
+    severity: critical
+    pattern: 'ModResolutionException: Could not find required mod: (?<sourcemod>.*) requires (?<destmod>.*)'
+    confidence: 0.9
+    priority: 85
+    cause:
+      key: diagnose.cause.fabric.mod_resolution_missing
+      summary: '缺少前置 mod：{sourcemod} 需要 {destmod}'
+      detail: '装上 {destmod} 的对应版本；装不上就删掉 {sourcemod}'
+    fix_action:
+      - kind: remove_mod
+        mod_ids:
+          - '{sourcemod}'
+        action: replace
+        note: '补装前置 {destmod}，或换掉 {sourcemod}'
+    sample: samples/fabric/mod_resolution_missing.log
+    source: 'HMCL CrashReportAnalyzer.Rule.MOD_RESOLUTION_MISSING'
+
+  - id: fabric.mod_resolution_missing_minecraft
+    severity: critical
+    pattern: 'ModResolutionException: Could not find required mod: (?<mod>.*) requires \{minecraft @ (?<version>.*)\}'
+    confidence: 0.9
+    priority: 85
+    cause:
+      key: diagnose.cause.fabric.mod_resolution_missing_minecraft
+      summary: '{mod} 要求 Minecraft {version}，与当前实例版本不一致'
+    fix_action:
+      - kind: remove_mod
+        mod_ids:
+          - '{mod}'
+        action: replace
+        note: '换该 mod 的 {version} 版本，或改实例版本'
+    sample: samples/fabric/mod_resolution_missing_minecraft.log
+    source: 'HMCL CrashReportAnalyzer.Rule.MOD_RESOLUTION_MISSING_MINECRAFT'
+
+  - id: fabric.mod_resolution_collection
+    severity: critical
+    pattern: 'ModResolutionException: Could not resolve valid mod collection \(at: (?<sourcemod>.*) requires (?<destmod>.*)\)'
+    confidence: 0.88
+    priority: 84
+    cause:
+      key: diagnose.cause.fabric.mod_resolution_collection
+      summary: 'mod 集合无法解析：{sourcemod} 与 {destmod} 的版本组合不成立'
+    fix_action:
+      - kind: remove_mod
+        mod_ids:
+          - '{sourcemod}'
+        action: upgrade
+    sample: samples/fabric/mod_resolution_collection.log
+    source: 'HMCL CrashReportAnalyzer.Rule.MOD_RESOLUTION_COLLECTION'
+
+  - id: fabric.mod_resolution_details
+    severity: warning
+    pattern: '(\tMod File:|-- MOD |\tFailure message:)'
+    confidence: 0.5
+    priority: 45
+    cause:
+      key: diagnose.cause.fabric.mod_resolution_details
+      summary: 'Fabric 打印了 mod 解析明细（Mod File / Failure message）：具体结论见上方规则'
+      detail: '这条只表示「日志里有解析失败明细」，用于把证据片段指给 AI/用户'
+    fix_action:
+      - kind: seek_help
+        export_diagnostics: true
+    sample: samples/fabric/mod_resolution_details.log
+    source: 'HMCL CrashReportAnalyzer.Rule.MOD_RESOLUTION0'
+
+  - id: fabric.loader_0_12
+    severity: critical
+    pattern: 'java\.lang\.NoClassDefFoundError: org/spongepowered/asm/mixin/transformer/FabricMixinTransformerProxy'
+    confidence: 0.85
+    priority: 80
+    cause:
+      key: diagnose.cause.fabric.loader_0_12
+      summary: 'Fabric Loader 0.12 与旧 mixin 类不兼容（loader 删掉了 deprecated 类）'
+    fix_action:
+      - kind: reinstall
+        component: fabric
+        note: '换匹配的 Fabric Loader 版本'
+    sample: samples/fabric/loader_0_12.log
+    source: 'HMCL CrashReportAnalyzer.Rule.FABRIC_VERSION_0_12'
+
+  - id: fabric.warnings
+    severity: warning
+    scope: file
+    pattern: '(Warnings were found!|Incompatible mod set!|Incompatible mods found!)(.*?)[\n\r]+(?<reason>[^\[]+)\['
+    confidence: 0.7
+    priority: 62
+    cause:
+      key: diagnose.cause.fabric.warnings
+      summary: 'Fabric 报告 mod 集合不兼容：{reason}'
+    fix_action:
+      - kind: remove_mod
+        action: disable
+        note: '按警告列表逐个禁用'
+    sample: samples/fabric/warnings.log
+    source: 'HMCL CrashReportAnalyzer.Rule.FABRIC_WARNINGS'
diff --git a/crates/core/src/diagnose/rules.d/forge.yaml b/crates/core/src/diagnose/rules.d/forge.yaml
new file mode 100644
index 0000000..71aa1cd
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/forge.yaml
@@ -0,0 +1,136 @@
+# 规则库 · Forge mod 解析（8 条）
+# 移植自 HMCL CrashReportAnalyzer.Rule 的 Forge 组（analyse/02 §7.3 第 6 组）。
+version: 1
+category: forge
+rules:
+  - id: forge.missing_dependencies
+    severity: critical
+    scope: file
+    pattern: 'Missing or unsupported mandatory dependencies:(?<reason>(.*)[\n\r]*(\t(.*)[\n\r]*)+)'
+    confidence: 0.85
+    priority: 80
+    cause:
+      key: diagnose.cause.forge.missing_dependencies
+      summary: 'Forge 报「缺少或不支持强制依赖」：有 mod 的前置没装或版本不对'
+      detail: '按报错里的 mod 名补齐前置；装不上就删掉依赖它的 mod'
+    fix_action:
+      - kind: remove_mod
+        action: disable
+        note: '按报错逐条补齐/禁用'
+    sample: samples/forge/missing_dependencies.log
+    source: 'HMCL CrashReportAnalyzer.Rule.FORGEMOD_RESOLUTION'
+
+  - id: forge.duplicate_mods
+    severity: critical
+    scope: file
+    pattern: 'Found duplicate mods:(?<reason>(.*)(?:\r\n|\n|\r)*(\t(.*)(?:\r\n|\n|\r)*)+)'
+    confidence: 0.9
+    priority: 86
+    cause:
+      key: diagnose.cause.forge.duplicate_mods
+      summary: '同一个 mod 装了两份（mods 目录里重复的 jar）'
+      detail: '删掉重复的那一份，只留一个版本'
+    fix_action:
+      - kind: remove_mod
+        action: remove
+        note: '保留一个版本'
+    sample: samples/forge/duplicate_mods.log
+    source: 'HMCL CrashReportAnalyzer.Rule.FORGE_FOUND_DUPLICATE_MODS'
+
+  - id: forge.duplicated_mod
+    severity: critical
+    pattern: 'Found a duplicate mod (?<name>.*) at (?<path>.*)'
+    confidence: 0.92
+    priority: 88
+    cause:
+      key: diagnose.cause.forge.duplicated_mod
+      summary: 'mod 重复：{name} 同时出现在 {path}'
+    fix_action:
+      - kind: remove_mod
+        mod_ids:
+          - '{name}'
+        action: remove
+        note: '删除路径 {path} 那一份'
+    sample: samples/forge/duplicated_mod.log
+    source: 'HMCL CrashReportAnalyzer.Rule.DUPLICATED_MOD'
+
+  - id: forge.repeat_installation
+    severity: critical
+    pattern: 'MultipleArgumentsForOptionException: Found multiple arguments for option (.*?), but you asked for only one'
+    confidence: 0.85
+    priority: 80
+    cause:
+      key: diagnose.cause.forge.repeat_installation
+      summary: 'Forge 被装了两次（同一版本出现多个安装参数）'
+      detail: '删掉重复的 Forge 安装/版本 JSON，再重装一次'
+    fix_action:
+      - kind: reinstall
+        component: forge
+    sample: samples/forge/repeat_installation.log
+    source: 'HMCL CrashReportAnalyzer.Rule.FORGE_REPEAT_INSTALLATION'
+
+  - id: forge.optifine_repeat_installation
+    severity: critical
+    pattern: 'ResolutionException: Module optifine reads another module named optifine'
+    confidence: 0.88
+    priority: 82
+    cause:
+      key: diagnose.cause.forge.optifine_repeat_installation
+      summary: 'OptiFine 装了两份（mods 里一个 + 自动安装一个）'
+    fix_action:
+      - kind: remove_mod
+        mod_ids:
+          - optifine
+        action: remove
+        note: '只保留一种安装方式'
+    sample: samples/forge/optifine_repeat_installation.log
+    source: 'HMCL CrashReportAnalyzer.Rule.OPTIFINE_REPEAT_INSTALLATION'
+
+  - id: forge.too_many_mods
+    severity: critical
+    pattern: 'maximum id range exceeded'
+    confidence: 0.9
+    priority: 80
+    cause:
+      key: diagnose.cause.forge.too_many_mods
+      summary: '装的 mod 太多，方块/物品 ID 超出上限（1.12 及更早的经典问题）'
+      detail: '删掉一部分 mod，或换用 1.13+ 的版本（不再有 ID 上限）'
+    fix_action:
+      - kind: remove_mod
+        action: disable
+        note: '减量或换版本'
+    sample: samples/forge/too_many_mods.log
+    source: 'HMCL CrashReportAnalyzer.Rule.TOO_MANY_MODS_LEAD_TO_EXCEEDING_THE_ID_LIMIT'
+
+  - id: forge.module_name_invalid
+    severity: warning
+    pattern: >-
+      Invalid module name: '' is not a Java identifier
+    confidence: 0.8
+    priority: 70
+    cause:
+      key: diagnose.cause.forge.module_name_invalid
+      summary: '某个 mod 的 jar 文件名不含英文字母/数字，Forge 把它当成非法 JPMS 模块名（如「拔刀剑.jar」）'
+      detail: '把该 jar 改成英文文件名（保留 .jar 后缀）再启动'
+    fix_action:
+      - kind: remove_mod
+        action: replace
+        note: '把 jar 改成英文文件名'
+    sample: samples/forge/module_name_invalid.log
+    source: 'HMCL CrashReportAnalyzer.Rule.MOD_NAME'
+
+  - id: forge.bootstrap_failed
+    severity: critical
+    pattern: 'Failed to create mod instance\. ModID: (?<id>.*?),'
+    confidence: 0.85
+    priority: 80
+    cause:
+      key: diagnose.cause.forge.bootstrap_failed
+      summary: 'mod {id} 的实例创建失败（初始化就抛异常）'
+    fix_action:
+      - kind: remove_mod
+        mod_ids:
+          - '{id}'
+        action: disable
+    sample: samples/forge/bootstrap_failed.log
+    source: 'HMCL CrashReportAnalyzer.Rule.BOOTSTRAP_FAILED'
diff --git a/crates/core/src/diagnose/rules.d/graphics.yaml b/crates/core/src/diagnose/rules.d/graphics.yaml
new file mode 100644
index 0000000..a070e88
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/graphics.yaml
@@ -0,0 +1,221 @@
+# 规则库 · 显卡 / 图形（11 条 = HMCL 移植 6 + Vulkan 组 5）
+# 移植自 HMCL CrashReportAnalyzer.Rule 的图形组（analyse/02 §7.3 第 3 组）；
+# Vulkan 组见文件末尾（依据 research/05-mc-vulkan.md §3.4 的 renderpearl 原因码）。
+version: 1
+category: graphics
+rules:
+  - id: graphics.gl_operation_failure
+    severity: warning
+    pattern: '(1282: Invalid operation|Maybe try a lower resolution resourcepack\?)'
+    confidence: 0.7
+    priority: 60
+    cause:
+      key: diagnose.cause.graphics.gl_operation_failure
+      summary: '某个 mod/光影包做了非法的 OpenGL 操作（GL_INVALID_OPERATION）'
+      detail: '换掉最近装的光影/资源包，或把资源包分辨率降下来'
+    fix_action:
+      - kind: change_graphics
+        setting: renderer
+        suggested_value: 'OpenGL 兼容模式'
+        note: '先低分辨率资源包验证'
+    sample: samples/graphics/gl_operation_failure.log
+    source: 'HMCL CrashReportAnalyzer.Rule.GL_OPERATION_FAILURE'
+
+  - id: graphics.opengl_not_supported
+    severity: critical
+    pattern: 'The driver does not appear to support OpenGL'
+    confidence: 0.85
+    priority: 75
+    cause:
+      key: diagnose.cause.graphics.opengl_not_supported
+      summary: '显卡驱动不支持 OpenGL（多半是没装显卡驱动，走了软件渲染）'
+      detail: '装/更新显卡厂商驱动；虚拟机里需要开 3D 加速'
+    fix_action:
+      - kind: change_graphics
+        setting: driver
+        update_driver: true
+    sample: samples/graphics/opengl_not_supported.log
+    source: 'HMCL CrashReportAnalyzer.Rule.OPENGL_NOT_SUPPORTED'
+
+  - id: graphics.graphics_driver
+    severity: critical
+    # HMCL 的跨行贪婪模式（EXCEPTION_ACCESS_VIOLATION … # C  [ig/nvoglv/atio）→ file scope。
+    # 末四段是 SDL 变体：26.3-snapshot-4 起窗口层 GLFW→SDL（lwjgl-glfw 消失、lwjgl-sdl 出现），
+    # 同类故障的原文会变成 SDL_GetError 的文本；旧 GLFW 模式保留（老版本日志仍需要）。
+    scope: file
+    pattern: '(Pixel format not accelerated|GLX: Failed to create context: GLXBadFBConfig|Couldn''t set pixel format|net\.minecraftforge\.fml\.client\.SplashProgress|org\.lwjgl\.LWJGLException|EXCEPTION_ACCESS_VIOLATION(.|\n|\r)+# C {2}\[(ig|atio|nvoglv)|SDL_CreateWindow failed|Couldn''t find matching render driver|No available video device)'
+    confidence: 0.8
+    priority: 78
+    cause:
+      key: diagnose.cause.graphics.graphics_driver
+      summary: '显卡驱动侧创建 OpenGL 上下文失败（像素格式/驱动崩溃）'
+      detail: '更新显卡驱动并重启；老显卡可用软渲染或换 OpenGL 兼容模式'
+    fix_action:
+      - kind: change_graphics
+        setting: driver
+        update_driver: true
+      - kind: change_graphics
+        setting: software_renderer
+        note: '驱动更新无效时用软渲染兜底（性能会掉）'
+    sample: samples/graphics/graphics_driver.log
+    source: 'HMCL CrashReportAnalyzer.Rule.GRAPHICS_DRIVER'
+
+  - id: graphics.macos_display_port
+    severity: critical
+    # 原 GLFW 模式保留。后两段是 SDL 变体（26.3 起窗口层换 SDL，无显示器/远程会话在 SDL 侧
+    # 报 SDL_Init 失败）——**但它必须和 `cocoa` 同时出现才命中**：SDL 在 macOS 上的视频驱动
+    # 就叫 `cocoa`，用它把本规则的 macOS 特异性钉住，免得 Windows/Linux 的 SDL_Init 失败被
+    # 误归因成「macOS 显示器问题」。⚠️ SDL 侧原文未在 26.3 实机验证（预测模式），拿到真实
+    # 日志后按实际文本收紧；宁可漏诊也不要跨平台误归因。
+    pattern: '(java\.lang\.IllegalStateException: GLFW error before init: \[0x10008\]Cocoa: Failed to find service port for display|(?i:cocoa).*SDL_Init.*failed|SDL_Init.*failed.*(?i:cocoa))'
+    confidence: 0.85
+    priority: 78
+    cause:
+      key: diagnose.cause.graphics.macos_display_port
+      summary: 'macOS 上 GLFW 初始化窗口失败（Cocoa 找不到 display service port）'
+      detail: '多见于远程桌面/无显示器会话；换成本机登录或升级 macOS 后再试'
+    fix_action:
+      - kind: change_graphics
+        setting: any
+        note: 'macOS 会话/显示器问题'
+    sample: samples/graphics/macos_display_port.log
+    source: 'HMCL CrashReportAnalyzer.Rule.MACOS_FAILED_TO_FIND_SERVICE_PORT_FOR_DISPLAY'
+
+  - id: graphics.resolution_too_high
+    severity: warning
+    pattern: 'Maybe try a (lower resolution|lowerresolution) (resourcepack|texturepack)\?'
+    confidence: 0.8
+    priority: 65
+    cause:
+      key: diagnose.cause.graphics.resolution_too_high
+      summary: '资源包分辨率过高（游戏直接提示换低分辨率资源包）'
+    fix_action:
+      - kind: change_graphics
+        setting: resolution
+        suggested_value: '低分辨率资源包'
+    sample: samples/graphics/resolution_too_high.log
+    source: 'HMCL CrashReportAnalyzer.Rule.RESOLUTION_TOO_HIGH'
+
+  - id: graphics.rtss_sodium
+    severity: warning
+    pattern: 'RivaTuner Statistics Server \(RTSS\) is not compatible with Sodium'
+    confidence: 0.9
+    priority: 70
+    cause:
+      key: diagnose.cause.graphics.rtss_sodium
+      summary: 'RTSS（微星小飞机/帧数显示）与 Sodium 不兼容'
+      detail: '关掉或卸载 RTSS 的 OSD 覆盖层，或改用 Sodium 兼容的帧数显示'
+    fix_action:
+      - kind: change_graphics
+        setting: overlay
+        suggested_value: '关闭 RTSS 覆盖层'
+    sample: samples/graphics/rtss_sodium.log
+    source: 'HMCL CrashReportAnalyzer.Rule.RTSS_FOREST_SODIUM'
+
+  # ── Vulkan 后端组（MC 26.2+ 的实验性 Vulkan 渲染）────────────────────────────
+  # 证据：research/05-mc-vulkan.md §3.4。renderpearl 的
+  # `BackendCreationException$Reason` 有五个稳定原因码（四个 vulkan_* + opengl_missing），
+  # 它们同时出现在 latest.log 的 `Backend failure reason: <码>` 与崩溃报告的
+  # `Backend failure reason` 行，是最可靠的落点（比英文正文稳，正文会随版本改）。
+  # 注意语义：26.2/26.3 的 Vulkan 首选失败会**自动回落 OpenGL**，所以单条 vulkan_* 命中
+  # 通常不是崩溃主因（warning）；只有五个后端全挂才是 critical（见最后一条）。
+
+  - id: graphics.vulkan_loader_missing
+    severity: warning
+    pattern: '(Vulkan loader library is missing|vulkan_loader_missing)'
+    confidence: 0.85
+    priority: 80
+    cause:
+      key: diagnose.cause.graphics.vulkan_loader_missing
+      summary: '机器上没有 Vulkan loader（Vulkan 后端起不来，游戏已回落 OpenGL）'
+      detail: '装/更新显卡驱动（Windows 需要 vulkan-1.dll，Linux 需要 libvulkan.so.1）；装不上就改用 OpenGL 后端'
+    fix_action:
+      - kind: change_graphics
+        setting: graphics_api
+        suggested_value: 'opengl'
+        note: 'Vulkan loader 缺失时强制 OpenGL，避免每次启动都白试一遍'
+      - kind: change_graphics
+        setting: driver
+        update_driver: true
+    sample: samples/graphics/vulkan_loader_missing.log
+    source: 'research/05-mc-vulkan.md §3.4（renderpearl BackendCreationException.Reason）'
+
+  - id: graphics.vulkan_device_version_too_low
+    severity: warning
+    pattern: '(vulkan_device_version_too_low|Vulkan [0-9]\.[0-9].{0,40}at least [0-9]\.[0-9] required)'
+    confidence: 0.85
+    priority: 78
+    cause:
+      key: diagnose.cause.graphics.vulkan_device_version_too_low
+      summary: '显卡/驱动支持的 Vulkan 版本低于 1.2（Vulkan 后端起不来）'
+      detail: '更新显卡驱动；驱动停更的老卡（10 年以上）没有 Vulkan 1.2，只能继续用 OpenGL'
+    fix_action:
+      - kind: change_graphics
+        setting: graphics_api
+        suggested_value: 'opengl'
+      - kind: change_graphics
+        setting: driver
+        update_driver: true
+    sample: samples/graphics/vulkan_device_version_too_low.log
+    source: 'research/05-mc-vulkan.md §3.4'
+
+  - id: graphics.vulkan_missing_extension
+    severity: warning
+    pattern: '(vulkan_missing_extension|missing: .*VK_KHR_(dynamic_rendering|push_descriptor))'
+    confidence: 0.85
+    priority: 76
+    cause:
+      key: diagnose.cause.graphics.vulkan_missing_extension
+      summary: '驱动缺 Vulkan 必需扩展（VK_KHR_dynamic_rendering / VK_KHR_push_descriptor）'
+      detail: 'MC 26.2+ 的 Vulkan 后端要求 VK 1.2 + dynamic_rendering + push_descriptor，三者缺一就跑不了；Mesa Dozen 也不支持 push_descriptor'
+    fix_action:
+      - kind: change_graphics
+        setting: graphics_api
+        suggested_value: 'opengl'
+      - kind: change_graphics
+        setting: driver
+        update_driver: true
+        note: '只有在驱动有新版本时才可能补上扩展'
+    sample: samples/graphics/vulkan_missing_extension.log
+    source: 'research/05-mc-vulkan.md §3.4 + §4.4（Dozen 反例）'
+
+  - id: graphics.vulkan_missing_feature
+    severity: warning
+    pattern: '(vulkan_missing_feature|missing capabilities: .*VULKAN_CORE_1_2)'
+    confidence: 0.8
+    priority: 74
+    cause:
+      key: diagnose.cause.graphics.vulkan_missing_feature
+      summary: '驱动缺 Vulkan 必需特性集（VULKAN_CORE_1_2）'
+      detail: '同上，属于驱动能力不足；老核显/虚拟机里常见，用 OpenGL 后端即可'
+    fix_action:
+      - kind: change_graphics
+        setting: graphics_api
+        suggested_value: 'opengl'
+    sample: samples/graphics/vulkan_missing_feature.log
+    source: 'research/05-mc-vulkan.md §3.4'
+
+  - id: graphics.no_graphics_backend
+    severity: critical
+    pattern: 'No supported graphics backend was found'
+    confidence: 0.9
+    priority: 82
+    suppress:
+      - graphics.vulkan_loader_missing
+      - graphics.vulkan_device_version_too_low
+      - graphics.vulkan_missing_extension
+      - graphics.vulkan_missing_feature
+    cause:
+      key: diagnose.cause.graphics.no_graphics_backend
+      summary: 'Vulkan 与 OpenGL 两个后端都创建失败（26.2+ 只有这两条路）'
+      detail: '硬件/驱动两侧都不满足：先更新显卡驱动；虚拟机需要开 3D 加速；实在不行只能换机器'
+    fix_action:
+      - kind: change_graphics
+        setting: graphics_api
+        suggested_value: 'opengl'
+        note: '先确认 Vulkan 失败原因再决定是否强推 OpenGL'
+      - kind: change_graphics
+        setting: software_renderer
+        note: '软渲染兜底能起来但基本没法玩，只用于导数据/排查'
+    sample: samples/graphics/no_graphics_backend.log
+    source: 'research/05-mc-vulkan.md §1.5（两个后端全失败才崩）'
diff --git a/crates/core/src/diagnose/rules.d/integrity.yaml b/crates/core/src/diagnose/rules.d/integrity.yaml
new file mode 100644
index 0000000..5eda6ee
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/integrity.yaml
@@ -0,0 +1,138 @@
+# 规则库 · 文件与安装完整性（8 条）
+# 移植自 HMCL CrashReportAnalyzer.Rule 的完整性组（analyse/02 §7.3 第 4 组）。
+# 组内约定：通用异常（NoSuchMethodError / NoClassDefFoundError）优先级低，
+# 让「安装不完整 / jar 被解压 / mod 冲突」这类能定位根因的规则通过 suppress 把它们降级为次生结论。
+version: 1
+category: integrity
+rules:
+  - id: integrity.file_changed
+    severity: critical
+    pattern: 'java\.lang\.SecurityException: SHA1 digest error for (?<file>.*)|signer information does not match signer information of other classes in the same package'
+    confidence: 0.85
+    priority: 85
+    cause:
+      key: diagnose.cause.integrity.file_changed
+      summary: '游戏文件被改过（SHA1 校验不一致）：jar 内容与清单哈希对不上'
+      detail: '重新下载/校验该文件；不要手改 jar 里的内容'
+    fix_action:
+      - kind: reinstall
+        component: game_jar
+        path_hint: '{file}'
+    sample: samples/integrity/file_changed.log
+    source: 'HMCL CrashReportAnalyzer.Rule.FILE_CHANGED'
+
+  - id: integrity.no_such_method
+    severity: warning
+    pattern: 'java\.lang\.NoSuchMethodError: (?<class>.*?)'
+    confidence: 0.6
+    priority: 40
+    cause:
+      key: diagnose.cause.integrity.no_such_method
+      summary: 'NoSuchMethodError：加载器/coremod 注入的东西与当前库版本不匹配'
+      detail: '常见于 mod 与游戏版本/Forge 版本不配套；重装加载器或删掉冲突 mod'
+    fix_action:
+      - kind: reinstall
+        component: loader
+        note: '先重装加载器；仍失败再逐个禁用 mod'
+    sample: samples/integrity/no_such_method.log
+    source: 'HMCL CrashReportAnalyzer.Rule.NO_SUCH_METHOD_ERROR'
+
+  - id: integrity.no_class_def_found
+    severity: warning
+    pattern: 'java\.lang\.NoClassDefFoundError: (?<class>.*)'
+    confidence: 0.6
+    priority: 40
+    cause:
+      key: diagnose.cause.integrity.no_class_def_found
+      summary: 'NoClassDefFoundError：缺少类文件（库没下全 / jar 被解压 / mod 不配套）'
+      detail: '先检查 libraries 是否完整，再排查 mods 里的解压目录'
+    fix_action:
+      - kind: reinstall
+        component: libraries
+    sample: samples/integrity/no_class_def_found.log
+    source: 'HMCL CrashReportAnalyzer.Rule.NO_CLASS_DEF_FOUND_ERROR'
+
+  - id: integrity.illegal_access
+    severity: warning
+    pattern: 'java\.lang\.IllegalAccessError: tried to access class (.*?) from class (?<class>.*?)'
+    confidence: 0.55
+    priority: 45
+    cause:
+      key: diagnose.cause.integrity.illegal_access
+      summary: 'IllegalAccessError：某个 coremod 想反射访问别的类的内部成员（在新 JDK 上被封了）'
+    fix_action:
+      - kind: reinstall
+        component: loader
+        note: '或换该 coremod/mod 的兼容版本'
+    sample: samples/integrity/illegal_access.log
+    source: 'HMCL CrashReportAnalyzer.Rule.ILLEGAL_ACCESS_ERROR'
+
+  - id: integrity.file_already_exists
+    severity: warning
+    pattern: 'java\.nio\.file\.FileAlreadyExistsException: (?<file>.*)'
+    confidence: 0.75
+    priority: 60
+    cause:
+      key: diagnose.cause.integrity.file_already_exists
+      summary: '某个 mod 要求一个「不该存在」的文件/目录，导致写入失败'
+      detail: '按提示删掉该文件（通常是玩家手建的空目录/unzip 残留）'
+    fix_action:
+      - kind: reinstall
+        component: mods
+        path_hint: '{file}'
+        note: '按路径删掉多余文件'
+    sample: samples/integrity/file_already_exists.log
+    source: 'HMCL CrashReportAnalyzer.Rule.FILE_ALREADY_EXISTS'
+
+  - id: integrity.mod_files_decompressed
+    severity: critical
+    pattern: '(The directories below appear to be extracted jar files\. Fix this before you continue|Extracted mod jars found, loading will NOT continue)'
+    confidence: 0.95
+    priority: 90
+    suppress:
+      - integrity.no_class_def_found
+      - integrity.no_such_method
+    cause:
+      key: diagnose.cause.integrity.mod_files_decompressed
+      summary: 'mods 目录里有被解压成文件夹的 jar：加载器会直接拒绝启动'
+      detail: '把解压出来的目录删掉，只保留 .jar 文件（很多压缩软件双击就解压了）'
+    fix_action:
+      - kind: reinstall
+        component: mods
+        note: '删掉解压出来的目录'
+    sample: samples/integrity/mod_files_decompressed.log
+    source: 'HMCL CrashReportAnalyzer.Rule.MOD_FILES_ARE_DECOMPRESSED'
+
+  - id: integrity.incomplete_forge
+    severity: critical
+    pattern: '(java\.io\.UncheckedIOException: java\.io\.IOException: Invalid paths argument, contained no existing paths: \[(.*?)(forge-(.*?)-client\.jar|fmlcore-(.*?)\.jar)\]|Failed to find Minecraft resource version (.*?) at (.*?)forge-(.*?)-client\.jar|Cannot find launch target fmlclient, unable to launch|java\.lang\.IllegalStateException: Could not find net/minecraft/client/Minecraft\.class in classloader SecureModuleClassLoader)'
+    confidence: 0.9
+    priority: 88
+    suppress:
+      - integrity.no_class_def_found
+      - integrity.no_such_method
+    cause:
+      key: diagnose.cause.integrity.incomplete_forge
+      summary: 'Forge 安装不完整（缺 forge-*-client.jar / fmlcore）'
+      detail: '重装该版本的 Forge，并检查 libraries 是否下全'
+    fix_action:
+      - kind: reinstall
+        component: forge
+    sample: samples/integrity/incomplete_forge.log
+    source: 'HMCL CrashReportAnalyzer.Rule.INCOMPLETE_FORGE_INSTALLATION'
+
+  - id: integrity.unsatisfied_link
+    severity: critical
+    pattern: 'java\.lang\.UnsatisfiedLinkError: Failed to locate library: (?<name>.*)'
+    confidence: 0.85
+    priority: 82
+    cause:
+      key: diagnose.cause.integrity.unsatisfied_link
+      summary: '找不到原生库（natives）：{name} 没解压出来或被杀软删了'
+      detail: '重装组件（重新解压 natives）；Windows 上检查杀软隔离区'
+    fix_action:
+      - kind: reinstall
+        component: natives
+        path_hint: '{name}'
+    sample: samples/integrity/unsatisfied_link.log
+    source: 'HMCL CrashReportAnalyzer.Rule.UNSATISFIED_LINK_ERROR'
diff --git a/crates/core/src/diagnose/rules.d/jvm.yaml b/crates/core/src/diagnose/rules.d/jvm.yaml
new file mode 100644
index 0000000..780258c
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/jvm.yaml
@@ -0,0 +1,142 @@
+# 规则库 · JVM / Java 版本（8 条）
+# 移植自 HMCL CrashReportAnalyzer.Rule（analyse/02 §7.3 第 1 组）。
+# schema 见 ../CONTRACT.md §2：pattern(regex) -> {cause, confidence, fix_action[]}
+version: 1
+category: jvm
+rules:
+  - id: jvm.openj9
+    severity: critical
+    pattern: '(Open J9 is not supported|OpenJ9 is incompatible|\.J9VMInternals\.)'
+    confidence: 0.9
+    priority: 88
+    cause:
+      key: diagnose.cause.jvm.openj9
+      summary: '当前用的是 OpenJ9 虚拟机：Minecraft 与绝大多数 mod 只支持 HotSpot（Oracle/OpenJDK）'
+      detail: '请换成 HotSpot 的 Java 8/17/21（Adoptium、Zulu、Microsoft OpenJDK 的 hotspot 版本都可以）'
+    fix_action:
+      - kind: change_java
+        vendor: hotspot
+        note: 'OpenJ9 不兼容，换 HotSpot'
+    sample: samples/jvm/openj9.log
+    source: 'HMCL CrashReportAnalyzer.Rule.OPENJ9'
+
+  - id: jvm.need_jdk11
+    severity: critical
+    pattern: '(no such method: sun\.misc\.Unsafe\.defineAnonymousClass\(Class,byte\[\],Object\[\]\)Class/invokeVirtual|java\.lang\.UnsupportedClassVersionError: icyllis/modernui/forge/MixinConnector has been compiled by a more recent version of the Java Runtime \(class file version 55\.0\), this version of the Java Runtime only recognizes class file versions up to 52\.0|java\.lang\.IllegalArgumentException: The requested compatibility level JAVA_11 could not be set\. Level is not supported by the active JRE or ASM version)'
+    confidence: 0.92
+    priority: 90
+    cause:
+      key: diagnose.cause.jvm.need_jdk11
+      summary: '模组/加载器需要 Java 11，当前 Java 版本不够'
+      detail: '把实例的 Java 换到 11 或更高（1.17+ 的游戏通常要 17/21）'
+    fix_action:
+      - kind: change_java
+        required_major: 11
+    sample: samples/jvm/need_jdk11.log
+    source: 'HMCL CrashReportAnalyzer.Rule.NEED_JDK11'
+
+  - id: jvm.too_old_java
+    severity: critical
+    pattern: 'java\.lang\.UnsupportedClassVersionError: (.*?) version (?<expected>\d+)\.0'
+    confidence: 0.92
+    priority: 88
+    cause:
+      key: diagnose.cause.jvm.too_old_java
+      summary: 'Java 版本过低：无法加载用 class file version {expected} 编译的类，请换用更高版本的 Java'
+      detail: '这个 class 版本号减去 44 就是所需的 Java 大版本（52→Java 8、61→Java 17）'
+    fix_action:
+      - kind: change_java
+        class_file_version_group: expected
+    sample: samples/jvm/too_old_java.log
+    source: 'HMCL CrashReportAnalyzer.Rule.TOO_OLD_JAVA'
+
+  - id: jvm.32bit
+    severity: critical
+    pattern: '(Could not reserve enough space for (.*?)KB object heap|The specified size exceeds the maximum representable size|Invalid maximum heap size)'
+    scope: line
+    confidence: 0.9
+    priority: 92
+    suppress:
+      - memory.out_of_memory
+    cause:
+      key: diagnose.cause.jvm.32bit
+      summary: '分配堆内存失败：多半是 32 位 Java 或 -Xmx 超过系统可用内存'
+      detail: '32 位 Java 最多只能用约 1.5 GB；换 64 位 Java 或把 -Xmx 降到 2048 MB 以下'
+    fix_action:
+      - kind: adjust_memory
+        need_64bit_java: true
+        min_xmx_mb: 1024
+      - kind: change_java
+        required_major: 17
+        note: '32 位换 64 位'
+    sample: samples/jvm/jvm_32bit.log
+    source: 'HMCL CrashReportAnalyzer.Rule.JVM_32BIT'
+
+  - id: jvm.jdk_9
+    severity: critical
+    pattern: 'java\.lang\.ClassCastException: (java\.base/jdk|class jdk)'
+    confidence: 0.8
+    priority: 80
+    cause:
+      key: diagnose.cause.jvm.jdk_9
+      summary: '游戏只能在 Java 8 上跑（Forge/旧核心库不兼容 Java 9+），当前 Java 版本太高'
+    fix_action:
+      - kind: change_java
+        max_major: 8
+    sample: samples/jvm/jdk_9.log
+    source: 'HMCL CrashReportAnalyzer.Rule.JDK_9'
+
+  - id: jvm.version_too_high
+    severity: critical
+    pattern: '(Unable to make protected final java\.lang\.Class java\.lang\.ClassLoader\.defineClass|java\.lang\.NoSuchFieldException: ucp|Unsupported class file major version|because module java\.base does not export|java\.lang\.ClassNotFoundException: jdk\.nashorn\.api\.scripting\.NashornScriptEngineFactory|java\.lang\.ClassNotFoundException: java\.lang\.invoke\.LambdaMetafactory|Exception in thread "main" java\.lang\.NullPointerException: Cannot read the array length because "urls" is null)'
+    confidence: 0.85
+    priority: 84
+    cause:
+      key: diagnose.cause.jvm.version_too_high
+      summary: 'Java 版本过高：老版本 Forge/核心库用了被新 JDK 移除或封装的接口'
+      detail: '1.16 及更早优先用 Java 8；1.17–1.20.4 用 Java 17；1.20.5+ 用 Java 21'
+    fix_action:
+      - kind: change_java
+        vendor: hotspot
+        note: '降到该游戏版本要求的 Java'
+      - kind: reinstall
+        component: loader
+        note: '或把 Forge/加载器升级到支持新 Java 的版本'
+    sample: samples/jvm/java_version_is_too_high.log
+    source: 'HMCL CrashReportAnalyzer.Rule.JAVA_VERSION_IS_TOO_HIGH'
+
+  - id: jvm.modlauncher_8
+    severity: critical
+    pattern: 'java\.lang\.NoSuchMethodError: (''void sun\.security\.util\.ManifestEntryVerifier\.<init>\(java\.util\.jar\.Manifest\)''|sun\.security\.util\.ManifestEntryVerifier\.<init>\(Ljava/util/jar/Manifest;\)V)'
+    confidence: 0.9
+    priority: 86
+    cause:
+      key: diagnose.cause.jvm.modlauncher_8
+      summary: 'ModLauncher 8 与当前 Java 不兼容（JDK-8273826）：1.16+ Forge 在新 JDK 上会这样崩'
+    fix_action:
+      - kind: change_java
+        max_major: 8
+      - kind: reinstall
+        component: forge
+        note: '或升级 Forge 到新版'
+    sample: samples/jvm/modlauncher_8.log
+    source: 'HMCL CrashReportAnalyzer.Rule.MODLAUNCHER_8'
+
+  - id: jvm.mac_jdk8u261
+    severity: critical
+    pattern: >-
+      Terminating app due to uncaught exception 'NSInternalInconsistencyException', reason: 'NSWindow drag regions should only be invalidated on the Main Thread!'
+    confidence: 0.85
+    priority: 82
+    cause:
+      key: diagnose.cause.jvm.mac_jdk8u261
+      summary: 'macOS 上 JDK 8u261+ 用新 Xcode 编译导致的 Forge/OptiFine 崩溃（sp614x/optifine#4824）'
+      detail: '换 Java 8u252 及更早，或升级 Forge/OptiFine'
+    fix_action:
+      - kind: change_java
+        max_major: 8
+        note: '优先试 8u252'
+      - kind: reinstall
+        component: optifine
+    sample: samples/jvm/mac_jdk8u261.log
+    source: 'HMCL CrashReportAnalyzer.Rule.MAC_JDK_8U261'
diff --git a/crates/core/src/diagnose/rules.d/memory.yaml b/crates/core/src/diagnose/rules.d/memory.yaml
new file mode 100644
index 0000000..44b7385
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/memory.yaml
@@ -0,0 +1,39 @@
+# 规则库 · 内存（2 条）
+# 移植自 HMCL CrashReportAnalyzer.Rule 的内存组（analyse/02 §7.3 第 2 组）。
+version: 1
+category: memory
+rules:
+  - id: memory.out_of_memory
+    severity: critical
+    # 最后一条是跨行组合（"Error occurred during initialization of VM" + "Too small maximum heap"），
+    # 因此整条规则用 file scope；HMCL 的 \R 在 Rust regex 里写成 (?:\r\n|\n|\r)。
+    scope: file
+    pattern: '(java\.lang\.OutOfMemoryError|The system is out of physical RAM or swap space|Out of Memory Error|Error occurred during initialization of VM(?:\r\n|\n|\r)Too small maximum heap)'
+    confidence: 0.9
+    priority: 80
+    cause:
+      key: diagnose.cause.memory.out_of_memory
+      summary: '游戏内存不足（OutOfMemoryError）：-Xmx 太小，或装的 mod 太多/整合包太大'
+      detail: '把 -Xmx 调到物理内存的一半左右（一般 4096–8192 MB），装光影/大量 mod 时适度加大'
+    fix_action:
+      - kind: adjust_memory
+        min_xmx_mb: 2048
+        note: '优先加大 -Xmx；若已经是 32 位 Java，先换 64 位'
+    sample: samples/memory/out_of_memory.log
+    source: 'HMCL CrashReportAnalyzer.Rule.OUT_OF_MEMORY'
+
+  - id: memory.memory_exceeded
+    severity: critical
+    pattern: 'There is insufficient memory for the Java Runtime Environment to continue'
+    confidence: 0.88
+    priority: 82
+    cause:
+      key: diagnose.cause.memory.memory_exceeded
+      summary: '系统物理内存/交换区耗尽：JVM 连续分配失败，整机内存不够'
+      detail: '关掉占内存的程序、降低 -Xmx，或扩大系统虚拟内存（页面文件）'
+    fix_action:
+      - kind: adjust_memory
+        increase_system_swap: true
+        note: '整机内存不足，不只是 -Xmx 的问题'
+    sample: samples/memory/memory_exceeded.log
+    source: 'HMCL CrashReportAnalyzer.Rule.MEMORY_EXCEEDED'
diff --git a/crates/core/src/diagnose/rules.d/mod_conflict.yaml b/crates/core/src/diagnose/rules.d/mod_conflict.yaml
new file mode 100644
index 0000000..6f0b867
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/mod_conflict.yaml
@@ -0,0 +1,152 @@
+# 规则库 · 模组互斥（8 条）
+# 移植自 HMCL CrashReportAnalyzer.Rule 的互斥组（analyse/02 §7.3 第 8 组）：
+# 具体到某个知名 mod 与 OptiFine / Sodium 的成名冲突，修复动作几乎都是「删 OptiFine 或其对手」。
+version: 1
+category: mod_conflict
+rules:
+  - id: conflict.optifine_forge
+    severity: critical
+    scope: file
+    # 移植说明：HMCL 原文里的 \> / \< 在这里改成裸 > / <（正则里 \< \> 是词边界断言，要字面量得写裸字符）。
+    # 末尾 alternative 保持 upstream 语义：`\(Reflector\.java)` 的前置 \( 是**字面括号**，尾部裸 ) 才是**闭合外层分组**，
+    # 因此它是前缀匹配。这里显式写成 `\(Reflector\.java(?::\d+)?\))`：裸 `(Reflector.java)` 与带行号的
+    # `(Reflector.java:455)` 两种真实栈帧形态都能命中（P2-1 回归，见 tests/diagnose/engine_rank.rs）。
+    pattern: >-
+      (java\.lang\.NoSuchMethodError: 'java\.lang\.Class sun\.misc\.Unsafe\.defineAnonymousClass\(java\.lang\.Class, byte\[\], java\.lang\.Object\[\]\)'|java\.lang\.NoSuchMethodError: 'void net\.minecraft\.client\.renderer\.texture\.SpriteContents\.<init>\(net\.minecraft\.resources\.ResourceLocation, |java\.lang\.NoSuchMethodError: 'void net\.minecraftforge\.client\.gui\.overlay\.ForgeGui\.renderSelectedItemName\(net\.minecraft\.client\.gui\.GuiGraphics, int\)'|java\.lang\.NoSuchMethodError: 'java\.lang\.String com\.mojang\.blaze3d\.systems\.RenderSystem\.getBackendDescription\(\)'|java\.lang\.NoSuchMethodError: 'net\.minecraft\.network\.chat\.FormattedText net\.minecraft\.client\.gui\.Font\.ellipsize\(net\.minecraft\.network\.chat\.FormattedText, int\)'|java\.lang\.NoSuchMethodError: 'void net\.minecraft\.server\.level\.DistanceManager\.(.*?)\(net\.minecraft\.server\.level\.TicketType, net\.minecraft\.world\.level\.ChunkPos, int, java\.lang\.Object, boolean\)'|java\.lang\.NoSuchMethodError: 'void net\.minecraft\.client\.renderer\.block\.model\.BakedQuad\.<init>\(int\[\], int, net\.minecraft\.core\.Direction, net\.minecraft\.client\.renderer\.texture\.TextureAtlasSprite, boolean, boolean\)'|TRANSFORMER/net\.optifine/net\.optifine\.reflect\.Reflector\.<clinit>\(Reflector\.java(?::\d+)?\))
+    confidence: 0.9
+    priority: 87
+    suppress:
+      - integrity.no_such_method
+      - integrity.no_class_def_found
+    cause:
+      key: diagnose.cause.conflict.optifine_forge
+      summary: 'OptiFine 与 Forge（或某个 Forge mod）不兼容：NoSuchMethodError 指向被 OptiFine 改写的原版方法'
+      detail: '删掉 OptiFine，改用同类替代（Sodium/Iris、Embeddium、Oculus 等），或换 OptiFine 的匹配版本'
+    fix_action:
+      - kind: remove_mod
+        mod_ids:
+          - optifine
+        action: remove
+        note: 'OptiFine 与 Forge 冲突，删掉其一'
+    sample: samples/mod_conflict/optifine_forge.log
+    source: 'HMCL CrashReportAnalyzer.Rule.OPTIFINE_IS_NOT_COMPATIBLE_WITH_FORGE'
+
+  - id: conflict.shaders_mod
+    severity: critical
+    pattern: 'java\.lang\.RuntimeException: Shaders Mod detected\. Please remove it, OptiFine has built-in support for shaders\.'
+    confidence: 0.95
+    priority: 85
+    cause:
+      key: diagnose.cause.conflict.shaders_mod
+      summary: '装了独立的 Shaders Mod，但 OptiFine 自带光影支持，两者不能共存'
+    fix_action:
+      - kind: remove_mod
+        mod_ids:
+          - shadersmod
+        action: remove
+    sample: samples/mod_conflict/shaders_mod.log
+    source: 'HMCL CrashReportAnalyzer.Rule.SHADERS_MOD'
+
+  - id: conflict.multipart_optifine
+    severity: critical
+    pattern: 'Error occurred applying transform of coremod META-INF/asm/multipart\.js function render'
+    confidence: 0.8
+    priority: 80
+    cause:
+      key: diagnose.cause.conflict.multipart_optifine
+      summary: 'Forge Multipart 的 coremod 转换失败（多为 OptiFine 同时存在导致）'
+    fix_action:
+      - kind: remove_mod
+        mod_ids:
+          - optifine
+        action: remove
+        note: '删 OptiFine 或 ForgeMultipart 之一'
+    sample: samples/mod_conflict/multipart_optifine.log
+    source: 'HMCL CrashReportAnalyzer.Rule.MOD_FOREST_OPTIFINE'
+
+  - id: conflict.performant_optifine
+    severity: critical
+    pattern: 'org\.spongepowered\.asm\.mixin\.injection\.throwables\.InjectionError: Critical injection failure: Redirector OnisOnLadder\(Lnet/minecraft/block/BlockState;Lnet/minecraft/world/World;Lnet/minecraft/util/math/BlockPos;Lnet/minecraft/entity/LivingEntity;\)Z in performant\.mixins\.json:entity\.LivingEntityMixin failed injection check, \(0/1\) succeeded\. Scanned 1 target\(s\)\. Using refmap performant\.refmap\.json'
+    confidence: 0.9
+    priority: 86
+    cause:
+      key: diagnose.cause.conflict.performant_optifine
+      summary: 'Performant 与 OptiFine 的 mixin 冲突（LivingEntityMixin 注入失败）'
+    fix_action:
+      - kind: remove_mod
+        mod_ids:
+          - performant
+          - optifine
+        action: remove
+        note: '两者只能留一个'
+    sample: samples/mod_conflict/performant_optifine.log
+    source: 'HMCL CrashReportAnalyzer.Rule.PERFORMANT_FOREST_OPTIFINE'
+
+  - id: conflict.twilight_optifine
+    severity: warning
+    pattern: 'java\.lang\.IllegalArgumentException: (.*) outside of image bounds (.*)'
+    confidence: 0.6
+    priority: 70
+    cause:
+      key: diagnose.cause.conflict.twilight_optifine
+      summary: '贴图越界（outside of image bounds）：1.16 上 Twilight Forest 与 OptiFine 的经典冲突'
+    fix_action:
+      - kind: remove_mod
+        mod_ids:
+          - optifine
+        action: remove
+        note: '删 OptiFine 或 Twilight Forest 的兼容版本'
+    sample: samples/mod_conflict/twilight_optifine.log
+    source: 'HMCL CrashReportAnalyzer.Rule.TWILIGHT_FOREST_OPTIFINE'
+
+  - id: conflict.jade_optifine
+    severity: critical
+    pattern: 'Critical injection failure: LVT in net/minecraft/client/renderer/GameRenderer::m_109093_\(FJZ\)V has incompatible changes at opcode 760 in callback jade\.mixins\.json:GameRendererMixin->@Inject::jade\$runTick\(FJZLorg/spongepowered/asm/mixin/injection/callback/CallbackInfo;IILcom/mojang/blaze3d/platform/Window;Lorg/joml/Matrix4f;Lcom/mojang/blaze3d/vertex/PoseStack;Lnet/minecraft/client/gui/GuiGraphics;\)V\.'
+    confidence: 0.9
+    priority: 86
+    cause:
+      key: diagnose.cause.conflict.jade_optifine
+      summary: 'Jade 与 OptiFine 在 1.20+ 冲突（GameRendererMixin 注入失败）'
+    fix_action:
+      - kind: remove_mod
+        mod_ids:
+          - optifine
+          - jade
+        action: remove
+        note: '两者只能留一个'
+    sample: samples/mod_conflict/jade_optifine.log
+    source: 'HMCL CrashReportAnalyzer.Rule.JADE_FOREST_OPTIFINE'
+
+  - id: conflict.neoforge_optifine
+    severity: critical
+    pattern: 'cpw\.mods\.modlauncher\.InvalidLauncherSetupException: Invalid Services found OptiFine'
+    confidence: 0.9
+    priority: 86
+    cause:
+      key: diagnose.cause.conflict.neoforge_optifine
+      summary: 'NeoForge 与 OptiFine 不兼容（launcher setup 阶段就拒绝）'
+    fix_action:
+      - kind: remove_mod
+        mod_ids:
+          - optifine
+        action: remove
+    sample: samples/mod_conflict/neoforge_optifine.log
+    source: 'HMCL CrashReportAnalyzer.Rule.NEOFORGE_FOREST_OPTIFINE'
+
+  - id: conflict.optifine_world_load
+    severity: critical
+    # 移植修正：HMCL 原文写的是 ChunkManager$ProxyTicketManager，Java 正则里 $ 是行尾锚点，
+    # 那条规则实际上永远命中不了。这里转义成字面量 $，规则才能真正生效。
+    pattern: 'java\.lang\.NoSuchMethodError: net\.minecraft\.world\.server\.ChunkManager\$ProxyTicketManager\.shouldForceTicks\(J\)Z'
+    confidence: 0.85
+    priority: 84
+    cause:
+      key: diagnose.cause.conflict.optifine_world_load
+      summary: 'OptiFine 导致世界无法加载（ChunkManager$ProxyTicketManager 方法被改写）'
+    fix_action:
+      - kind: remove_mod
+        mod_ids:
+          - optifine
+        action: remove
+    sample: samples/mod_conflict/optifine_world_load.log
+    source: 'HMCL CrashReportAnalyzer.Rule.OPTIFINE_CAUSES_THE_WORLD_TO_FAIL_TO_LOAD'
diff --git a/crates/core/src/diagnose/rules.d/mod_runtime.yaml b/crates/core/src/diagnose/rules.d/mod_runtime.yaml
new file mode 100644
index 0000000..04f4707
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/mod_runtime.yaml
@@ -0,0 +1,136 @@
+# 规则库 · mod 运行期崩（8 条）
+# 移植自 HMCL CrashReportAnalyzer.Rule 的运行期组（analyse/02 §7.3 第 7 组）。
+version: 1
+category: mod_runtime
+rules:
+  - id: mod.loading_crashed_forge
+    severity: critical
+    pattern: 'LoaderExceptionModCrash: Caught exception from (?<name>.*?) \((?<id>.*)\)'
+    confidence: 0.9
+    priority: 85
+    cause:
+      key: diagnose.cause.mod.loading_crashed_forge
+      summary: 'Forge 抓到 {name}（{id}）在加载时抛异常'
+      detail: '禁用该 mod 或换它的兼容版本；同一条栈里往往还有具体异常类型'
+    fix_action:
+      - kind: remove_mod
+        mod_ids:
+          - '{id}'
+        action: disable
+    sample: samples/mod_runtime/loading_crashed_forge.log
+    source: 'HMCL CrashReportAnalyzer.Rule.LOADING_CRASHED_FORGE'
+
+  - id: mod.loading_crashed_fabric
+    severity: critical
+    pattern: >-
+      Could not execute entrypoint stage '(.*?)' due to errors, provided by '(?<id>.*)'!
+    confidence: 0.9
+    priority: 85
+    cause:
+      key: diagnose.cause.mod.loading_crashed_fabric
+      summary: 'Fabric 在入口点阶段执行 mod {id} 时出错'
+    fix_action:
+    - kind: remove_mod
+      mod_ids:
+        - '{id}'
+      action: disable
+    sample: samples/mod_runtime/loading_crashed_fabric.log
+    source: 'HMCL CrashReportAnalyzer.Rule.LOADING_CRASHED_FABRIC'
+
+  - id: mod.config_failed
+    severity: warning
+    pattern: 'Failed loading config file (?<file>.*?) of type (.*?) for modid (?<id>.*)'
+    confidence: 0.7
+    priority: 60
+    cause:
+      key: diagnose.cause.mod.config_failed
+      summary: 'mod {id} 的配置文件 {file} 解析失败（多半是被手改坏或版本升级后格式变了）'
+      detail: '删掉该配置文件让 mod 重新生成默认值'
+    fix_action:
+      - kind: remove_mod
+        mod_ids:
+          - '{id}'
+        action: disable
+        note: '删配置文件 {file} 后重试（不一定要禁用 mod）'
+    sample: samples/mod_runtime/config_failed.log
+    source: 'HMCL CrashReportAnalyzer.Rule.CONFIG'
+
+  - id: mod.mixin_failure
+    severity: critical
+    pattern: '(MixinApplyError|Mixin prepare failed |Mixin apply failed |mixin\.injection\.throwables\.|\.mixins\.json\] FAILED during \))'
+    confidence: 0.7
+    priority: 65
+    cause:
+      key: diagnose.cause.mod.mixin_failure
+      summary: 'Mixin 注入失败：某个 mod 的 mixin 与当前游戏/其他 mod 的代码不匹配'
+      detail: '常见于 mod 与游戏版本不配套；看日志里 mixin 的 target 类名能定位到 mod'
+    fix_action:
+      - kind: remove_mod
+        action: disable
+        note: '按 mixin 配置文件名（xxx.mixins.json）定位 mod'
+    sample: samples/mod_runtime/mixin_failure.log
+    source: 'HMCL CrashReportAnalyzer.Rule.MODMIXIN_FAILURE'
+
+  - id: mod.mixin_apply_failed
+    severity: critical
+    pattern: 'Mixin apply for mod (?<id>.*) failed'
+    confidence: 0.85
+    priority: 82
+    cause:
+      key: diagnose.cause.mod.mixin_apply_failed
+      summary: 'mod {id} 的 mixin 应用失败'
+    fix_action:
+    - kind: remove_mod
+      mod_ids:
+        - '{id}'
+      action: disable
+    sample: samples/mod_runtime/mixin_apply_failed.log
+    source: 'HMCL CrashReportAnalyzer.Rule.MIXIN_APPLY_MOD_FAILED'
+
+  - id: mod.forge_error
+    severity: warning
+    scope: file
+    pattern: 'An exception was thrown, the game will display an error screen and halt\.(?:\r\n|\n|\r)*(?<reason>.*(?:\r\n|\n|\r)*(\s*at .*(?:\r\n|\n|\r))+)'
+    confidence: 0.6
+    priority: 55
+    cause:
+      key: diagnose.cause.mod.forge_error
+      summary: 'Forge 捕获到未处理异常并已弹出错误界面（Forge 自己给了栈）'
+      detail: '栈顶的 at 行指向哪个 mod 的包名，就去禁用/升级那个 mod'
+    fix_action:
+      - kind: seek_help
+        export_diagnostics: true
+    sample: samples/mod_runtime/forge_error.log
+    source: 'HMCL CrashReportAnalyzer.Rule.FORGE_ERROR'
+
+  - id: mod.night_config_fixes
+    severity: warning
+    pattern: 'com\.electronwill\.nightconfig\.core\.io\.ParsingException: Not enough data available'
+    confidence: 0.85
+    priority: 75
+    cause:
+      key: diagnose.cause.mod.night_config_fixes
+      summary: 'night-config 配置文件读坏了（常见于 nightconfigfixes 相关 mod 组合）'
+      detail: '删掉对应 mod 的配置文件，或移除 nightconfigfixes'
+    fix_action:
+      - kind: remove_mod
+        mod_ids:
+          - nightconfigfixes
+        action: remove
+    sample: samples/mod_runtime/night_config_fixes.log
+    source: 'HMCL CrashReportAnalyzer.Rule.NIGHT_CONFIG_FIXES'
+
+  - id: mod.install_mixinbootstrap
+    severity: critical
+    pattern: 'java\.lang\.ClassNotFoundException: org\.spongepowered\.asm\.launch\.MixinTweaker'
+    confidence: 0.8
+    priority: 75
+    cause:
+      key: diagnose.cause.mod.install_mixinbootstrap
+      summary: '缺少 MixinBootstrap 前置（Forge 1.12.2 上很多 mod 需要它）'
+    fix_action:
+      - kind: reinstall
+        component: mixin_bootstrap
+        note: '装上 MixinBootstrap 0.8+'
+    sample: samples/mod_runtime/install_mixinbootstrap.log
+    source: 'HMCL CrashReportAnalyzer.Rule.INSTALL_MIXINBOOTSTRAP'
diff --git a/crates/core/src/diagnose/rules.d/other.yaml b/crates/core/src/diagnose/rules.d/other.yaml
new file mode 100644
index 0000000..e7b61b1
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/other.yaml
@@ -0,0 +1,22 @@
+# 规则库 · 其它（1 条）
+# 移植自 HMCL CrashReportAnalyzer.Rule 的杂项组（analyse/02 §7.3 第 10 组）。
+# 将来「用户反馈沉淀的新规则」如果归不了类，也先落这里（标记 source 与需要复核）。
+version: 1
+category: other
+rules:
+  - id: other.debug_crash
+    severity: info
+    pattern: 'Manually triggered debug crash'
+    confidence: 0.95
+    priority: 70
+    cause:
+      key: diagnose.cause.other.debug_crash
+      summary: '这次崩溃是手动触发的（游戏里按 F3+C），不是真的故障'
+      detail: '如果用户点了「导出诊断包」做测试，可以忽略这条'
+    fix_action:
+      - kind: seek_help
+        export_diagnostics: false
+        needs_more_info:
+          - '确认是否手动触发的调试崩溃'
+    sample: samples/other/debug_crash.log
+    source: 'HMCL CrashReportAnalyzer.Rule.DEBUG_CRASH'
diff --git a/crates/core/src/diagnose/rules.d/samples/fabric/loader_0_12.log b/crates/core/src/diagnose/rules.d/samples/fabric/loader_0_12.log
new file mode 100644
index 0000000..0f5b91c
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/fabric/loader_0_12.log
@@ -0,0 +1,2 @@
+[12:00:40] [main/ERROR]: Failed to start Fabric loader
+java.lang.NoClassDefFoundError: org/spongepowered/asm/mixin/transformer/FabricMixinTransformerProxy
diff --git a/crates/core/src/diagnose/rules.d/samples/fabric/mod_resolution.log b/crates/core/src/diagnose/rules.d/samples/fabric/mod_resolution.log
new file mode 100644
index 0000000..7ecdc20
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/fabric/mod_resolution.log
@@ -0,0 +1,3 @@
+net.fabricmc.loader.impl.FormattedException: net.fabricmc.loader.impl.discovery.ModResolutionException: Mod resolution encountered an incompatible mod set!
+ - Mod 'Sodium' (sodium) 0.5.8 requires version 0.6.0 or later of mod 'Iris' (iris)
+ - Mod 'Iris' (iris) 0.5.0 is present but is incompatible
diff --git a/crates/core/src/diagnose/rules.d/samples/fabric/mod_resolution_collection.log b/crates/core/src/diagnose/rules.d/samples/fabric/mod_resolution_collection.log
new file mode 100644
index 0000000..c57dca2
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/fabric/mod_resolution_collection.log
@@ -0,0 +1 @@
+net.fabricmc.loader.impl.discovery.ModResolutionException: Could not resolve valid mod collection (at: iris requires sodium)
diff --git a/crates/core/src/diagnose/rules.d/samples/fabric/mod_resolution_conflict.log b/crates/core/src/diagnose/rules.d/samples/fabric/mod_resolution_conflict.log
new file mode 100644
index 0000000..0ceb775
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/fabric/mod_resolution_conflict.log
@@ -0,0 +1 @@
+net.fabricmc.loader.impl.discovery.ModResolutionException: Found conflicting mods: sodium conflicts with sodium-extra
diff --git a/crates/core/src/diagnose/rules.d/samples/fabric/mod_resolution_details.log b/crates/core/src/diagnose/rules.d/samples/fabric/mod_resolution_details.log
new file mode 100644
index 0000000..03c4c77
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/fabric/mod_resolution_details.log
@@ -0,0 +1,3 @@
+	Mod File: /mods/sodium-fabric-0.5.0.jar
+	Failure message: Mod resolution failed
+net.fabricmc.loader.impl.discovery.ModResolutionException: see above
diff --git a/crates/core/src/diagnose/rules.d/samples/fabric/mod_resolution_missing.log b/crates/core/src/diagnose/rules.d/samples/fabric/mod_resolution_missing.log
new file mode 100644
index 0000000..94eedaa
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/fabric/mod_resolution_missing.log
@@ -0,0 +1 @@
+net.fabricmc.loader.impl.discovery.ModResolutionException: Could not find required mod: sodium requires iris
diff --git a/crates/core/src/diagnose/rules.d/samples/fabric/mod_resolution_missing_minecraft.log b/crates/core/src/diagnose/rules.d/samples/fabric/mod_resolution_missing_minecraft.log
new file mode 100644
index 0000000..b7d94aa
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/fabric/mod_resolution_missing_minecraft.log
@@ -0,0 +1 @@
+net.fabricmc.loader.impl.discovery.ModResolutionException: Could not find required mod: sodium requires {minecraft @ 1.20.1}
diff --git a/crates/core/src/diagnose/rules.d/samples/fabric/warnings.log b/crates/core/src/diagnose/rules.d/samples/fabric/warnings.log
new file mode 100644
index 0000000..20dab22
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/fabric/warnings.log
@@ -0,0 +1,3 @@
+Warnings were found!
+ - Sodium 0.4.10 is incompatible with Iris 1.6.0
+[
diff --git a/crates/core/src/diagnose/rules.d/samples/forge/bootstrap_failed.log b/crates/core/src/diagnose/rules.d/samples/forge/bootstrap_failed.log
new file mode 100644
index 0000000..98dee26
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/forge/bootstrap_failed.log
@@ -0,0 +1 @@
+[12:00:55] [main/ERROR]: Failed to create mod instance. ModID: alexsmobs, Class: com.github.alexthe666.alexsmobs.AlexsMobs
diff --git a/crates/core/src/diagnose/rules.d/samples/forge/duplicate_mods.log b/crates/core/src/diagnose/rules.d/samples/forge/duplicate_mods.log
new file mode 100644
index 0000000..04a2863
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/forge/duplicate_mods.log
@@ -0,0 +1,3 @@
+Found duplicate mods:
+	jei-1.20.1-15.2.0.27.jar
+	jei-1.20.1-15.2.0.28.jar
diff --git a/crates/core/src/diagnose/rules.d/samples/forge/duplicated_mod.log b/crates/core/src/diagnose/rules.d/samples/forge/duplicated_mod.log
new file mode 100644
index 0000000..83c75f2
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/forge/duplicated_mod.log
@@ -0,0 +1 @@
+[12:00:50] [main/ERROR]: Found a duplicate mod jei at /mods/jei-1.20.1-15.2.0.28.jar
diff --git a/crates/core/src/diagnose/rules.d/samples/forge/missing_dependencies.log b/crates/core/src/diagnose/rules.d/samples/forge/missing_dependencies.log
new file mode 100644
index 0000000..c6b364d
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/forge/missing_dependencies.log
@@ -0,0 +1,2 @@
+Missing or unsupported mandatory dependencies:
+	Mod ID: citadel, Requested by: alexsmobs, Expected range: [1.20.1-2.4.0,), Actual version: MISSING
diff --git a/crates/core/src/diagnose/rules.d/samples/forge/module_name_invalid.log b/crates/core/src/diagnose/rules.d/samples/forge/module_name_invalid.log
new file mode 100644
index 0000000..f77b204
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/forge/module_name_invalid.log
@@ -0,0 +1 @@
+[12:00:54] [main/ERROR]: java.lang.IllegalArgumentException: Invalid module name: '' is not a Java identifier
diff --git a/crates/core/src/diagnose/rules.d/samples/forge/optifine_repeat_installation.log b/crates/core/src/diagnose/rules.d/samples/forge/optifine_repeat_installation.log
new file mode 100644
index 0000000..f8450c6
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/forge/optifine_repeat_installation.log
@@ -0,0 +1 @@
+[12:00:52] [main/ERROR]: org.spongepowered.asm.launch.platform.MixinPlatformManager threw ResolutionException: Module optifine reads another module named optifine
diff --git a/crates/core/src/diagnose/rules.d/samples/forge/repeat_installation.log b/crates/core/src/diagnose/rules.d/samples/forge/repeat_installation.log
new file mode 100644
index 0000000..203ec4b
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/forge/repeat_installation.log
@@ -0,0 +1 @@
+[12:00:51] [main/ERROR]: joptsimple.MultipleArgumentsForOptionException: Found multiple arguments for option net.minecraftforge, but you asked for only one
diff --git a/crates/core/src/diagnose/rules.d/samples/forge/too_many_mods.log b/crates/core/src/diagnose/rules.d/samples/forge/too_many_mods.log
new file mode 100644
index 0000000..73430ec
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/forge/too_many_mods.log
@@ -0,0 +1 @@
+[12:00:53] [main/ERROR]: java.lang.RuntimeException: maximum id range exceeded
diff --git a/crates/core/src/diagnose/rules.d/samples/graphics/gl_operation_failure.log b/crates/core/src/diagnose/rules.d/samples/graphics/gl_operation_failure.log
new file mode 100644
index 0000000..8e8d5ab
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/graphics/gl_operation_failure.log
@@ -0,0 +1,3 @@
+[12:00:20] [Render thread/ERROR]: ########## GL ERROR ##########
+[12:00:20] [Render thread/ERROR]: @ Pre render
+[12:00:20] [Render thread/ERROR]: 1282: Invalid operation
diff --git a/crates/core/src/diagnose/rules.d/samples/graphics/graphics_driver.log b/crates/core/src/diagnose/rules.d/samples/graphics/graphics_driver.log
new file mode 100644
index 0000000..7baa8ef
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/graphics/graphics_driver.log
@@ -0,0 +1,7 @@
+#
+# A fatal error has been detected by the Java Runtime Environment:
+#
+#  EXCEPTION_ACCESS_VIOLATION (0xc0000005) at pc=0x00007ffb1a2b3c4d, pid=12344, tid=0x0000000000002a1c
+#
+# Problematic frame:
+# C  [ig8d64.dll+0x9b3c4d]
diff --git a/crates/core/src/diagnose/rules.d/samples/graphics/macos_display_port.log b/crates/core/src/diagnose/rules.d/samples/graphics/macos_display_port.log
new file mode 100644
index 0000000..e15d8ab
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/graphics/macos_display_port.log
@@ -0,0 +1 @@
+[12:00:22] [main/ERROR]: java.lang.IllegalStateException: GLFW error before init: [0x10008]Cocoa: Failed to find service port for display
diff --git a/crates/core/src/diagnose/rules.d/samples/graphics/no_graphics_backend.log b/crates/core/src/diagnose/rules.d/samples/graphics/no_graphics_backend.log
new file mode 100644
index 0000000..33dcf79
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/graphics/no_graphics_backend.log
@@ -0,0 +1,15 @@
+---- Minecraft Crash Report ----
+// I let you down. Sorry :(
+
+Time: 2026-10-30 12:00:21
+Description: Initializing game
+
+net.minecraft.client.Minecraft$GameLoadException: No supported graphics backend was found.
+	at net.minecraft.client.Minecraft.<init>(Minecraft.java:612)
+	at net.minecraft.client.main.Main.main(Main.java:184)
+
+-- Graphics Backend --
+	Backend: VULKAN
+	Backend failure reason: vulkan_loader_missing
+	Backend: OPENGL
+	Backend failure reason: opengl_missing
diff --git a/crates/core/src/diagnose/rules.d/samples/graphics/opengl_not_supported.log b/crates/core/src/diagnose/rules.d/samples/graphics/opengl_not_supported.log
new file mode 100644
index 0000000..e6d21b3
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/graphics/opengl_not_supported.log
@@ -0,0 +1 @@
+[12:00:21] [main/ERROR]: The driver does not appear to support OpenGL
diff --git a/crates/core/src/diagnose/rules.d/samples/graphics/resolution_too_high.log b/crates/core/src/diagnose/rules.d/samples/graphics/resolution_too_high.log
new file mode 100644
index 0000000..684495b
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/graphics/resolution_too_high.log
@@ -0,0 +1 @@
+[12:00:23] [Render thread/WARN]: Maybe try a lower resolution resourcepack?
diff --git a/crates/core/src/diagnose/rules.d/samples/graphics/rtss_sodium.log b/crates/core/src/diagnose/rules.d/samples/graphics/rtss_sodium.log
new file mode 100644
index 0000000..7528a6d
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/graphics/rtss_sodium.log
@@ -0,0 +1 @@
+[12:00:24] [main/ERROR]: RivaTuner Statistics Server (RTSS) is not compatible with Sodium
diff --git a/crates/core/src/diagnose/rules.d/samples/graphics/vulkan_device_version_too_low.log b/crates/core/src/diagnose/rules.d/samples/graphics/vulkan_device_version_too_low.log
new file mode 100644
index 0000000..f4756a5
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/graphics/vulkan_device_version_too_low.log
@@ -0,0 +1,5 @@
+[12:00:21] [Render thread/INFO]: Using graphics backend VULKAN, using drivers: Intel proprietary driver
+[12:00:21] [Render thread/ERROR]: Backend failure reason: vulkan_device_version_too_low
+[12:00:21] [Render thread/ERROR]: Backend failure message: Device NVIDIA GeForce GT 710 reports Vulkan 1.0.0, at least 1.2 required
+[12:00:21] [Render thread/ERROR]: Failed to create backend VULKAN
+[12:00:21] [Render thread/INFO]: Falling back to OpenGL
diff --git a/crates/core/src/diagnose/rules.d/samples/graphics/vulkan_loader_missing.log b/crates/core/src/diagnose/rules.d/samples/graphics/vulkan_loader_missing.log
new file mode 100644
index 0000000..3580d49
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/graphics/vulkan_loader_missing.log
@@ -0,0 +1,5 @@
+[12:00:21] [Render thread/INFO]: Backend library: LWJGL version 3.4.3+13
+[12:00:21] [Render thread/INFO]: Using graphics backend VULKAN, using drivers: AMD proprietary driver
+[12:00:21] [Render thread/ERROR]: Vulkan loader library is missing
+[12:00:21] [Render thread/ERROR]: Failed to create backend VULKAN: Backend failure reason: vulkan_loader_missing
+[12:00:21] [Render thread/INFO]: Falling back to OpenGL
diff --git a/crates/core/src/diagnose/rules.d/samples/graphics/vulkan_missing_extension.log b/crates/core/src/diagnose/rules.d/samples/graphics/vulkan_missing_extension.log
new file mode 100644
index 0000000..aabed4e
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/graphics/vulkan_missing_extension.log
@@ -0,0 +1,5 @@
+[12:00:21] [Render thread/INFO]: Using graphics backend VULKAN, using drivers: Mesa (zink)
+[12:00:21] [Render thread/ERROR]: Backend failure reason: vulkan_missing_extension
+[12:00:21] [Render thread/ERROR]: Device [AMD Radeon RX 580] does not support required extensions from FeatureSet [VULKAN_12], missing: [VK_KHR_dynamic_rendering, VK_KHR_push_descriptor]
+[12:00:21] [Render thread/ERROR]: Failed to create backend VULKAN
+[12:00:21] [Render thread/INFO]: Falling back to OpenGL
diff --git a/crates/core/src/diagnose/rules.d/samples/graphics/vulkan_missing_feature.log b/crates/core/src/diagnose/rules.d/samples/graphics/vulkan_missing_feature.log
new file mode 100644
index 0000000..be3a375
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/graphics/vulkan_missing_feature.log
@@ -0,0 +1,5 @@
+[12:00:21] [Render thread/INFO]: Using graphics backend VULKAN, using drivers: llvmpipe (Mesa)
+[12:00:21] [Render thread/ERROR]: Backend failure reason: vulkan_missing_feature
+[12:00:21] [Render thread/ERROR]: Backend failure missing capabilities: VULKAN_CORE_1_2
+[12:00:21] [Render thread/ERROR]: Failed to create backend VULKAN
+[12:00:21] [Render thread/INFO]: Falling back to OpenGL
diff --git a/crates/core/src/diagnose/rules.d/samples/hs_err/access_violation.log b/crates/core/src/diagnose/rules.d/samples/hs_err/access_violation.log
new file mode 100644
index 0000000..072f1a2
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/hs_err/access_violation.log
@@ -0,0 +1,34 @@
+#
+# A fatal error has been detected by the Java Runtime Environment:
+#
+#  EXCEPTION_ACCESS_VIOLATION (0xc0000005) at pc=0x00007ffb1a2b3c4d, pid=12344, tid=0x0000000000002a1c
+#
+# JRE version: Java(TM) SE Runtime Environment (8.0_51-b16) (build 1.8.0_51-b16)
+# Java VM: Java HotSpot(TM) 64-Bit Server VM (25.51-b03 mixed mode windows-amd64 compressed oops)
+# Problematic frame:
+# C  [ig8d64.dll+0x9b3c4d]
+#
+# Failed to write core dump. Minidumps are not enabled by default on client versions of Windows
+#
+# If you would like to submit a bug report, please visit:
+#   http://bugreport.java.com/bugreport/crash.jsp
+# The crash happened outside the Java Virtual Machine in native code.
+# See problematic frame for where to report the bug.
+#
+
+---------------  T H R E A D  ---------------
+
+Current thread (0x000000001f3b8000):  JavaThread "Render thread" [_thread_in_native, id=10780, stack(0x000000001a000000,0x000000001a100000)]
+
+siginfo: ExceptionCode=0xc0000005, ExceptionInformation=0x0000000000000000 0x0000000000000000 0x0000000000000000
+
+VM Arguments:
+jvm_args: -Xmx4096m -Xms1024m -Djava.library.path=C:\Users\player\.minecraft\natives
+java_command: net.minecraft.launchwrapper.Launch --gameDir . --assetsDir assets
+
+---------------  H E A P  ---------------
+
+Heap:
+ garbage-first heap   total 4194304K, used 1048576K [0x0000000700000000, 0x0000000800000000)
+
+Memory: 4k page, physical 16741480k(4716856k free), swap 18672384k(9433608k free)
diff --git a/crates/core/src/diagnose/rules.d/samples/hs_err/out_of_memory.log b/crates/core/src/diagnose/rules.d/samples/hs_err/out_of_memory.log
new file mode 100644
index 0000000..28e5158
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/hs_err/out_of_memory.log
@@ -0,0 +1,19 @@
+#
+# There is insufficient memory for the Java Runtime Environment to continue.
+# Native memory allocation (mmap) failed to map 1073741824 bytes for committing reserved memory.
+#
+#  Out of Memory Error (os_windows.cpp:3521), pid=9876, tid=0x0000000000001f44
+#
+# JRE version: Java(TM) SE Runtime Environment (17.0.9+9) (build 17.0.9+9-LTS-211)
+# Java VM: Java HotSpot(TM) 64-Bit Server VM (17.0.9+9-LTS-211, mixed mode, sharing, tiered, compressed oops, compressed class ptrs, g1 gc, windows-amd64)
+#
+
+---------------  T H R E A D  ---------------
+
+Current thread (0x0000021d6f82b1a0):  JavaThread "Render thread" [_thread_in_vm, id=14120, stack(0x000000a1b0000000,0x000000a1b0100000)]
+
+VM Arguments:
+jvm_args: -Xmx8192m -Xms2048m
+java_command: net.fabricmc.loader.impl.launch.knot.KnotClient --gameDir .
+
+Memory: 4k page, physical 8134564k(120944k free), swap 9723904k(550664k free)
diff --git a/crates/core/src/diagnose/rules.d/samples/integrity/file_already_exists.log b/crates/core/src/diagnose/rules.d/samples/integrity/file_already_exists.log
new file mode 100644
index 0000000..6538598
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/integrity/file_already_exists.log
@@ -0,0 +1 @@
+[12:00:34] [main/ERROR]: java.nio.file.FileAlreadyExistsException: config/example-mod.toml
diff --git a/crates/core/src/diagnose/rules.d/samples/integrity/file_changed.log b/crates/core/src/diagnose/rules.d/samples/integrity/file_changed.log
new file mode 100644
index 0000000..c61c24e
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/integrity/file_changed.log
@@ -0,0 +1,2 @@
+[12:00:30] [main/ERROR]: Failed to verify class file
+java.lang.SecurityException: SHA1 digest error for net/minecraft/client/main/Main.class
diff --git a/crates/core/src/diagnose/rules.d/samples/integrity/illegal_access.log b/crates/core/src/diagnose/rules.d/samples/integrity/illegal_access.log
new file mode 100644
index 0000000..ae7a12c
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/integrity/illegal_access.log
@@ -0,0 +1,2 @@
+[12:00:33] [main/ERROR]: coremod failed
+java.lang.IllegalAccessError: tried to access class net.minecraft.client.Minecraft from class com.example.coremod.Hook
diff --git a/crates/core/src/diagnose/rules.d/samples/integrity/incomplete_forge.log b/crates/core/src/diagnose/rules.d/samples/integrity/incomplete_forge.log
new file mode 100644
index 0000000..6471fca
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/integrity/incomplete_forge.log
@@ -0,0 +1 @@
+[12:00:36] [main/ERROR]: java.io.UncheckedIOException: java.io.IOException: Invalid paths argument, contained no existing paths: [/home/user/.minecraft/libraries/net/minecraftforge/forge/1.20.1-47.2.0/forge-1.20.1-47.2.0-client.jar]
diff --git a/crates/core/src/diagnose/rules.d/samples/integrity/mod_files_decompressed.log b/crates/core/src/diagnose/rules.d/samples/integrity/mod_files_decompressed.log
new file mode 100644
index 0000000..0456caf
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/integrity/mod_files_decompressed.log
@@ -0,0 +1,2 @@
+[12:00:35] [main/ERROR]: Extracted mod jars found, loading will NOT continue
+[12:00:35] [main/ERROR]: The directories below appear to be extracted jar files. Fix this before you continue
diff --git a/crates/core/src/diagnose/rules.d/samples/integrity/no_class_def_found.log b/crates/core/src/diagnose/rules.d/samples/integrity/no_class_def_found.log
new file mode 100644
index 0000000..e9b4360
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/integrity/no_class_def_found.log
@@ -0,0 +1,2 @@
+[12:00:32] [main/ERROR]: A mod crashed on startup
+java.lang.NoClassDefFoundError: net/minecraftforge/fml/loading/FMLEnvironment
diff --git a/crates/core/src/diagnose/rules.d/samples/integrity/no_such_method.log b/crates/core/src/diagnose/rules.d/samples/integrity/no_such_method.log
new file mode 100644
index 0000000..cbafdd0
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/integrity/no_such_method.log
@@ -0,0 +1,3 @@
+[12:00:31] [main/ERROR]: Failed to start
+java.lang.NoSuchMethodError: net.minecraft.world.World.getBlockState(Lnet/minecraft/core/BlockPos;)Lnet/minecraft/world/level/block/state/BlockState;
+	at com.example.mod.Foo.bar(Foo.java:42)
diff --git a/crates/core/src/diagnose/rules.d/samples/integrity/unsatisfied_link.log b/crates/core/src/diagnose/rules.d/samples/integrity/unsatisfied_link.log
new file mode 100644
index 0000000..3504911
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/integrity/unsatisfied_link.log
@@ -0,0 +1,2 @@
+[12:00:37] [main/ERROR]: Failed to initialise LWJGL
+java.lang.UnsatisfiedLinkError: Failed to locate library: lwjgl.dll
diff --git a/crates/core/src/diagnose/rules.d/samples/jvm/java_version_is_too_high.log b/crates/core/src/diagnose/rules.d/samples/jvm/java_version_is_too_high.log
new file mode 100644
index 0000000..7f53dd0
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/jvm/java_version_is_too_high.log
@@ -0,0 +1,3 @@
+[12:00:06] [main/ERROR]: Unable to launch
+java.lang.NoSuchFieldException: ucp
+	at java.base/java.lang.ClassLoader$UnsafeAccessor.getUnsafe(ClassLoader.java:123)
diff --git a/crates/core/src/diagnose/rules.d/samples/jvm/jdk_9.log b/crates/core/src/diagnose/rules.d/samples/jvm/jdk_9.log
new file mode 100644
index 0000000..b4670b3
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/jvm/jdk_9.log
@@ -0,0 +1,2 @@
+[12:00:05] [main/ERROR]: Failed to launch
+java.lang.ClassCastException: java.base/jdk.internal.loader.ClassLoaders$AppClassLoader cannot be cast to java.net.URLClassLoader
diff --git a/crates/core/src/diagnose/rules.d/samples/jvm/jvm_32bit.log b/crates/core/src/diagnose/rules.d/samples/jvm/jvm_32bit.log
new file mode 100644
index 0000000..37f7dcc
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/jvm/jvm_32bit.log
@@ -0,0 +1,3 @@
+[12:00:04] [main/INFO]: Starting JVM with -Xmx4096m
+Error occurred during initialization of VM
+Could not reserve enough space for 4194304KB object heap
diff --git a/crates/core/src/diagnose/rules.d/samples/jvm/mac_jdk8u261.log b/crates/core/src/diagnose/rules.d/samples/jvm/mac_jdk8u261.log
new file mode 100644
index 0000000..9fe8637
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/jvm/mac_jdk8u261.log
@@ -0,0 +1 @@
+Terminating app due to uncaught exception 'NSInternalInconsistencyException', reason: 'NSWindow drag regions should only be invalidated on the Main Thread!'
diff --git a/crates/core/src/diagnose/rules.d/samples/jvm/modlauncher_8.log b/crates/core/src/diagnose/rules.d/samples/jvm/modlauncher_8.log
new file mode 100644
index 0000000..07308da
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/jvm/modlauncher_8.log
@@ -0,0 +1,3 @@
+[12:00:07] [main/ERROR]: ModLauncher failed
+java.lang.NoSuchMethodError: 'void sun.security.util.ManifestEntryVerifier.<init>(java.util.jar.Manifest)'
+	at cpw.mods.modlauncher.TransformingClassLoader.buildTransformedClassNodeFor(TransformingClassLoader.java:151)
diff --git a/crates/core/src/diagnose/rules.d/samples/jvm/need_jdk11.log b/crates/core/src/diagnose/rules.d/samples/jvm/need_jdk11.log
new file mode 100644
index 0000000..0fc8526
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/jvm/need_jdk11.log
@@ -0,0 +1,2 @@
+[12:00:02] [main/ERROR]: Failed to start the game
+java.lang.IllegalArgumentException: The requested compatibility level JAVA_11 could not be set. Level is not supported by the active JRE or ASM version
diff --git a/crates/core/src/diagnose/rules.d/samples/jvm/openj9.log b/crates/core/src/diagnose/rules.d/samples/jvm/openj9.log
new file mode 100644
index 0000000..346f9fb
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/jvm/openj9.log
@@ -0,0 +1,2 @@
+[12:00:01] [main/INFO]: Loading Minecraft 1.20.1 with Forge 47.2.0
+OpenJ9 is incompatible with the authentication libraries used by this launcher
diff --git a/crates/core/src/diagnose/rules.d/samples/jvm/too_old_java.log b/crates/core/src/diagnose/rules.d/samples/jvm/too_old_java.log
new file mode 100644
index 0000000..0546e67
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/jvm/too_old_java.log
@@ -0,0 +1,2 @@
+[12:00:03] [main/ERROR]: Could not find or load main class net.fabricmc.loader.impl.launch.knot.KnotClient
+java.lang.UnsupportedClassVersionError: net/fabricmc/loader/impl/launch/knot/KnotClient has been compiled by a more recent version of the Java Runtime (class file version 61.0), this version of the Java Runtime only recognizes class file versions up to 52.0
diff --git a/crates/core/src/diagnose/rules.d/samples/memory/memory_exceeded.log b/crates/core/src/diagnose/rules.d/samples/memory/memory_exceeded.log
new file mode 100644
index 0000000..83afa47
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/memory/memory_exceeded.log
@@ -0,0 +1,3 @@
+#
+# There is insufficient memory for the Java Runtime Environment to continue.
+# Native memory allocation (mmap) failed to map 67108864 bytes for committing reserved memory.
diff --git a/crates/core/src/diagnose/rules.d/samples/memory/out_of_memory.log b/crates/core/src/diagnose/rules.d/samples/memory/out_of_memory.log
new file mode 100644
index 0000000..10c2b86
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/memory/out_of_memory.log
@@ -0,0 +1,3 @@
+[12:00:10] [Render thread/ERROR]: Encountered an unexpected exception
+java.lang.OutOfMemoryError: Java heap space
+	at net.minecraft.client.renderer.chunk.RenderChunk.rebuildChunk(RenderChunk.java:123)
diff --git a/crates/core/src/diagnose/rules.d/samples/mod_conflict/jade_optifine.log b/crates/core/src/diagnose/rules.d/samples/mod_conflict/jade_optifine.log
new file mode 100644
index 0000000..f6d34cc
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/mod_conflict/jade_optifine.log
@@ -0,0 +1 @@
+[12:01:15] [main/ERROR]: Critical injection failure: LVT in net/minecraft/client/renderer/GameRenderer::m_109093_(FJZ)V has incompatible changes at opcode 760 in callback jade.mixins.json:GameRendererMixin->@Inject::jade$runTick(FJZLorg/spongepowered/asm/mixin/injection/callback/CallbackInfo;IILcom/mojang/blaze3d/platform/Window;Lorg/joml/Matrix4f;Lcom/mojang/blaze3d/vertex/PoseStack;Lnet/minecraft/client/gui/GuiGraphics;)V.
diff --git a/crates/core/src/diagnose/rules.d/samples/mod_conflict/multipart_optifine.log b/crates/core/src/diagnose/rules.d/samples/mod_conflict/multipart_optifine.log
new file mode 100644
index 0000000..54d6c01
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/mod_conflict/multipart_optifine.log
@@ -0,0 +1 @@
+[12:01:12] [main/ERROR]: Error occurred applying transform of coremod META-INF/asm/multipart.js function render
diff --git a/crates/core/src/diagnose/rules.d/samples/mod_conflict/neoforge_optifine.log b/crates/core/src/diagnose/rules.d/samples/mod_conflict/neoforge_optifine.log
new file mode 100644
index 0000000..34a268c
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/mod_conflict/neoforge_optifine.log
@@ -0,0 +1 @@
+[12:01:16] [main/ERROR]: cpw.mods.modlauncher.InvalidLauncherSetupException: Invalid Services found OptiFine
diff --git a/crates/core/src/diagnose/rules.d/samples/mod_conflict/optifine_forge.log b/crates/core/src/diagnose/rules.d/samples/mod_conflict/optifine_forge.log
new file mode 100644
index 0000000..f271bd8
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/mod_conflict/optifine_forge.log
@@ -0,0 +1,4 @@
+[12:01:10] [main/ERROR]: Failed to launch Forge
+java.lang.NoSuchMethodError: 'java.lang.String com.mojang.blaze3d.systems.RenderSystem.getBackendDescription()'
+	at net.optifine.reflect.Reflector.<clinit>(Reflector.java:455)
+	TRANSFORMER/net.optifine/net.optifine.reflect.Reflector.<clinit>(Reflector.java:455)
diff --git a/crates/core/src/diagnose/rules.d/samples/mod_conflict/optifine_world_load.log b/crates/core/src/diagnose/rules.d/samples/mod_conflict/optifine_world_load.log
new file mode 100644
index 0000000..3bdf673
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/mod_conflict/optifine_world_load.log
@@ -0,0 +1 @@
+[12:01:17] [main/ERROR]: java.lang.NoSuchMethodError: net.minecraft.world.server.ChunkManager$ProxyTicketManager.shouldForceTicks(J)Z
diff --git a/crates/core/src/diagnose/rules.d/samples/mod_conflict/performant_optifine.log b/crates/core/src/diagnose/rules.d/samples/mod_conflict/performant_optifine.log
new file mode 100644
index 0000000..43cbeb0
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/mod_conflict/performant_optifine.log
@@ -0,0 +1 @@
+[12:01:13] [main/ERROR]: org.spongepowered.asm.mixin.injection.throwables.InjectionError: Critical injection failure: Redirector OnisOnLadder(Lnet/minecraft/block/BlockState;Lnet/minecraft/world/World;Lnet/minecraft/util/math/BlockPos;Lnet/minecraft/entity/LivingEntity;)Z in performant.mixins.json:entity.LivingEntityMixin failed injection check, (0/1) succeeded. Scanned 1 target(s). Using refmap performant.refmap.json
diff --git a/crates/core/src/diagnose/rules.d/samples/mod_conflict/shaders_mod.log b/crates/core/src/diagnose/rules.d/samples/mod_conflict/shaders_mod.log
new file mode 100644
index 0000000..0af6950
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/mod_conflict/shaders_mod.log
@@ -0,0 +1 @@
+[12:01:11] [main/ERROR]: java.lang.RuntimeException: Shaders Mod detected. Please remove it, OptiFine has built-in support for shaders.
diff --git a/crates/core/src/diagnose/rules.d/samples/mod_conflict/twilight_optifine.log b/crates/core/src/diagnose/rules.d/samples/mod_conflict/twilight_optifine.log
new file mode 100644
index 0000000..e58781c
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/mod_conflict/twilight_optifine.log
@@ -0,0 +1 @@
+[12:01:14] [main/ERROR]: java.lang.IllegalArgumentException: 512 outside of image bounds 256
diff --git a/crates/core/src/diagnose/rules.d/samples/mod_runtime/config_failed.log b/crates/core/src/diagnose/rules.d/samples/mod_runtime/config_failed.log
new file mode 100644
index 0000000..b77ae0b
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/mod_runtime/config_failed.log
@@ -0,0 +1 @@
+[12:01:02] [main/ERROR]: Failed loading config file alexsmobs-common.toml of type COMMON for modid alexsmobs
diff --git a/crates/core/src/diagnose/rules.d/samples/mod_runtime/forge_error.log b/crates/core/src/diagnose/rules.d/samples/mod_runtime/forge_error.log
new file mode 100644
index 0000000..9a53a92
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/mod_runtime/forge_error.log
@@ -0,0 +1,3 @@
+[12:01:05] [main/ERROR]: An exception was thrown, the game will display an error screen and halt.
+java.lang.NullPointerException: Cannot invoke "net.minecraft.world.level.Level.getBlockState()" because "level" is null
+	at com.example.mod.Foo.tick(Foo.java:123)
diff --git a/crates/core/src/diagnose/rules.d/samples/mod_runtime/install_mixinbootstrap.log b/crates/core/src/diagnose/rules.d/samples/mod_runtime/install_mixinbootstrap.log
new file mode 100644
index 0000000..e810221
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/mod_runtime/install_mixinbootstrap.log
@@ -0,0 +1 @@
+[12:01:07] [main/ERROR]: java.lang.ClassNotFoundException: org.spongepowered.asm.launch.MixinTweaker
diff --git a/crates/core/src/diagnose/rules.d/samples/mod_runtime/loading_crashed_fabric.log b/crates/core/src/diagnose/rules.d/samples/mod_runtime/loading_crashed_fabric.log
new file mode 100644
index 0000000..70bb109
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/mod_runtime/loading_crashed_fabric.log
@@ -0,0 +1 @@
+[12:01:01] [main/ERROR]: Could not execute entrypoint stage 'main' due to errors, provided by 'sodium'!
diff --git a/crates/core/src/diagnose/rules.d/samples/mod_runtime/loading_crashed_forge.log b/crates/core/src/diagnose/rules.d/samples/mod_runtime/loading_crashed_forge.log
new file mode 100644
index 0000000..786ce0c
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/mod_runtime/loading_crashed_forge.log
@@ -0,0 +1 @@
+[12:01:00] [main/ERROR]: LoaderExceptionModCrash: Caught exception from Alex's Mobs (alexsmobs)
diff --git a/crates/core/src/diagnose/rules.d/samples/mod_runtime/mixin_apply_failed.log b/crates/core/src/diagnose/rules.d/samples/mod_runtime/mixin_apply_failed.log
new file mode 100644
index 0000000..60d2499
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/mod_runtime/mixin_apply_failed.log
@@ -0,0 +1 @@
+[12:01:04] [main/ERROR]: Mixin apply for mod examplemod failed examplemod.mixins.json:MixinFoo from mod examplemod->@Inject::handler
diff --git a/crates/core/src/diagnose/rules.d/samples/mod_runtime/mixin_failure.log b/crates/core/src/diagnose/rules.d/samples/mod_runtime/mixin_failure.log
new file mode 100644
index 0000000..40c6276
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/mod_runtime/mixin_failure.log
@@ -0,0 +1 @@
+[12:01:03] [main/ERROR]: org.spongepowered.asm.mixin.injection.throwables.InvalidInjectionException: Critical injection failure: @Inject annotation could not find target method
diff --git a/crates/core/src/diagnose/rules.d/samples/mod_runtime/night_config_fixes.log b/crates/core/src/diagnose/rules.d/samples/mod_runtime/night_config_fixes.log
new file mode 100644
index 0000000..1a4cbe5
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/mod_runtime/night_config_fixes.log
@@ -0,0 +1 @@
+[12:01:06] [main/ERROR]: com.electronwill.nightconfig.core.io.ParsingException: Not enough data available
diff --git a/crates/core/src/diagnose/rules.d/samples/other/debug_crash.log b/crates/core/src/diagnose/rules.d/samples/other/debug_crash.log
new file mode 100644
index 0000000..eef42ff
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/other/debug_crash.log
@@ -0,0 +1 @@
+[12:01:30] [Render thread/INFO]: Manually triggered debug crash
diff --git a/crates/core/src/diagnose/rules.d/samples/world/block_model.log b/crates/core/src/diagnose/rules.d/samples/world/block_model.log
new file mode 100644
index 0000000..627f520
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/world/block_model.log
@@ -0,0 +1,6 @@
+[12:01:21] [Worker-Main-1/ERROR]: Unable to bake model
+java.lang.RuntimeException: Failed to tessellate
+-- Block being tessellated --
+Details:
+	Block: minecraft:grass_block
+	Block location: World: (12,64,-34)
diff --git a/crates/core/src/diagnose/rules.d/samples/world/entity_tick.log b/crates/core/src/diagnose/rules.d/samples/world/entity_tick.log
new file mode 100644
index 0000000..f0bfd21
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/samples/world/entity_tick.log
@@ -0,0 +1,6 @@
+[12:01:20] [Server thread/ERROR]: Encountered an unexpected exception
+java.lang.NullPointerException: Ticking entity
+-- Entity being ticked --
+Details:
+	Entity Type: minecraft:cow (net.minecraft.world.entity.animal.Cow)
+	Entity's Exact location: 123.45, 64.00, -67.89
diff --git a/crates/core/src/diagnose/rules.d/world.yaml b/crates/core/src/diagnose/rules.d/world.yaml
new file mode 100644
index 0000000..7c197eb
--- /dev/null
+++ b/crates/core/src/diagnose/rules.d/world.yaml
@@ -0,0 +1,39 @@
+# 规则库 · 游戏实体/方块（2 条）
+# 移植自 HMCL CrashReportAnalyzer.Rule 的实体/方块组（analyse/02 §7.3 第 9 组）：
+# 崩在 tick 时能拿到实体类型/方块类型与坐标，是「哪个 mod 的实体坏了」的直接线索。
+version: 1
+category: world
+rules:
+  - id: world.entity_tick
+    severity: critical
+    scope: file
+    pattern: "Entity Type: (?<type>.*)[\\w\\W\\n\\r]*?Entity's Exact location: (?<location>.*)"
+    confidence: 0.75
+    priority: 70
+    cause:
+      key: diagnose.cause.world.entity_tick
+      summary: '崩在实体 tick：实体 {type}（坐标 {location}）'
+      detail: '看看这个实体来自哪个 mod（血条/怪物增强/刷怪类 mod 居多），禁用该 mod 或删掉存档里这个实体'
+    fix_action:
+      - kind: remove_mod
+        action: disable
+        note: '按实体类型定位 mod'
+    sample: samples/world/entity_tick.log
+    source: 'HMCL CrashReportAnalyzer.Rule.ENTITY'
+
+  - id: world.block_model
+    severity: warning
+    scope: file
+    pattern: 'Block: (?<type>.*)[\w\W\n\r]*?Block location: (?<location>.*)'
+    confidence: 0.65
+    priority: 65
+    cause:
+      key: diagnose.cause.world.block_model
+      summary: '崩在方块（{type}，坐标 {location}）：多半是方块模型/贴图相关 mod 的问题'
+      detail: '定位该方块所属 mod；资源包也可能导致（先换回原版资源包验证）'
+    fix_action:
+      - kind: remove_mod
+        action: disable
+        note: '按方块类型定位 mod / 先换回原版资源包'
+    sample: samples/world/block_model.log
+    source: 'HMCL CrashReportAnalyzer.Rule.BLOCK'
diff --git a/crates/core/src/diagnose/rules.rs b/crates/core/src/diagnose/rules.rs
new file mode 100644
index 0000000..c61e852
--- /dev/null
+++ b/crates/core/src/diagnose/rules.rs
@@ -0,0 +1,319 @@
+//! 诊断规则模型：YAML schema + 编译后的规则。
+//!
+//! 设计定稿：`DevDocs/PlanDoc/06-launch-and-diagnostics.md` §2.2–§2.3；
+//! 规则来源：HMCL `CrashReportAnalyzer.Rule` 59 条（`DevDocs/analyse/02-launch-pipeline.md` §7.3）。
+//! 字段说明与给 M16/M18 的契约见同目录 `CONTRACT.md`。
+//!
+//! 相对 HMCL「枚举即签名库」的四处升级（analyse/02 §7.10）：
+//! 1. 规则是**数据**不是代码：加规则只改 `rules.d/*.yaml`，不重编译；
+//! 2. 每条规则带 `confidence`/`priority`/`suppress`，可做主因排序（HMCL 只能平铺）；
+//! 3. 命名捕获组由正则自声明，不再有 `groupNames` 顺序契约；
+//! 4. 每条规则绑定六维修复动作，直接成为 agent 工具的参数来源。
+
+use std::collections::BTreeMap;
+use std::fmt;
+
+use regex::Regex;
+use serde::Deserialize;
+
+// 六维修复动作按体量拆两个文件（本目录文件上限 400 行），从本模块统一导出公开面。
+#[path = "fix_action.rs"]
+mod fix_action;
+#[path = "fix_params.rs"]
+mod fix_params;
+
+pub use fix_action::{class_file_to_java_major, FixAction, FixActionKind, MaterializedFixAction};
+pub use fix_params::{
+    AdjustMemory, ChangeGraphics, ChangeJava, ComponentKind, GraphicsSetting, JavaVendor,
+    ModAction, Reinstall, RemoveMod, SeekHelp,
+};
+
+/// 规则分类：HMCL 59 条规则的 10 个根因分组，与 `rules.d/<category>.yaml` 一一对应。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum RuleCategory {
+    /// JVM 实现 / Java 版本不兼容。
+    Jvm,
+    /// 堆内存不足、系统内存耗尽。
+    Memory,
+    /// 显卡驱动 / OpenGL / 分辨率 / 图形覆盖层。
+    Graphics,
+    /// 文件被改、安装不完整、原生库缺失。
+    Integrity,
+    /// Fabric 的 ModResolutionException 家族。
+    Fabric,
+    /// Forge 的依赖解析 / 重复安装 / mod 元数据。
+    Forge,
+    /// mod 加载期或运行期崩溃（含 mixin）。
+    ModRuntime,
+    /// 具体 mod 与 OptiFine 等成名冲突。
+    ModConflict,
+    /// 崩在某个实体 / 方块的 tick。
+    World,
+    /// 其它（手动触发调试崩溃等）。
+    Other,
+}
+
+impl RuleCategory {
+    /// 稳定字符串（也用于诊断输出的 `category` 字段）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Jvm => "jvm",
+            Self::Memory => "memory",
+            Self::Graphics => "graphics",
+            Self::Integrity => "integrity",
+            Self::Fabric => "fabric",
+            Self::Forge => "forge",
+            Self::ModRuntime => "mod_runtime",
+            Self::ModConflict => "mod_conflict",
+            Self::World => "world",
+            Self::Other => "other",
+        }
+    }
+
+    /// 全部分类（loader 校验规则文件归属、测试遍历用）。
+    #[must_use]
+    pub const fn all() -> [Self; 10] {
+        [
+            Self::Jvm,
+            Self::Memory,
+            Self::Graphics,
+            Self::Integrity,
+            Self::Fabric,
+            Self::Forge,
+            Self::ModRuntime,
+            Self::ModConflict,
+            Self::World,
+            Self::Other,
+        ]
+    }
+}
+
+impl fmt::Display for RuleCategory {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+/// 结论严重度（UI 配色与「是否弹窗」的依据）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum Severity {
+    /// 提示性：能跑但不最佳。
+    Info,
+    /// 警告：可疑但结论不确定。
+    #[default]
+    Warning,
+    /// 严重：基本可以确定崩溃原因。
+    Critical,
+}
+
+impl Severity {
+    /// 稳定字符串（诊断输出用）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Info => "info",
+            Self::Warning => "warning",
+            Self::Critical => "critical",
+        }
+    }
+}
+
+impl fmt::Display for Severity {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+/// 匹配范围：决定引擎怎么切文本，也是性能开关（analyse/02 §8.3 第 1 条）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum MatchScope {
+    /// 逐行匹配（默认，绝大多数 Java 异常都是单行签名）。
+    #[default]
+    Line,
+    /// 按空行切块匹配（一段异常 + 上下文）。
+    Block,
+    /// 整份文本匹配（仅跨行贪婪模式：mod 解析列表、实体 tick 上下文等）。
+    File,
+}
+
+/// 结论文案（`summary` 支持 `{group}` 占位符，`key` 是稳定的 i18n/AI 引用 id）。
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Cause {
+    /// 稳定 id，如 `diagnose.cause.jvm.too_old_java`。
+    pub key: String,
+    /// 一句话结论（中文，可直接给用户看）。
+    pub summary: String,
+    /// 更细的解释 / 处理建议。
+    #[serde(default)]
+    pub detail: Option<String>,
+}
+
+impl Cause {
+    /// 代入捕获组后的（结论, 细化说明）。
+    #[must_use]
+    pub fn render(&self, groups: &BTreeMap<String, String>) -> (String, Option<String>) {
+        (
+            substitute(&self.summary, groups),
+            self.detail
+                .as_ref()
+                .map(|detail| substitute(detail, groups)),
+        )
+    }
+}
+
+/// 一条规则的 YAML schema。
+#[derive(Debug, Clone, PartialEq, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Rule {
+    /// 全局唯一 id（`命名空间.短名`）。
+    pub id: String,
+    /// 严重度。
+    #[serde(default)]
+    pub severity: Severity,
+    /// 正则（Rust `regex` 语法，命名组用 `(?<name>…)`）。
+    pub pattern: String,
+    /// 匹配范围。
+    #[serde(default)]
+    pub scope: MatchScope,
+    /// 命中可信度 0.0~1.0。
+    #[serde(default = "default_confidence")]
+    pub confidence: f32,
+    /// 主因排序权重 0~100。
+    #[serde(default = "default_priority")]
+    pub priority: u8,
+    /// 命中本规则时把列出的规则降级为次生结论。
+    #[serde(default)]
+    pub suppress: Vec<String>,
+    /// 结论文案。
+    pub cause: Cause,
+    /// 六维修复动作。
+    #[serde(default)]
+    pub fix_action: Vec<FixAction>,
+    /// 回归样本路径（相对 `rules.d/`）。
+    #[serde(default)]
+    pub sample: Option<String>,
+    /// 出处（HMCL 枚举名 / issue 链接）。
+    #[serde(default)]
+    pub source: Option<String>,
+}
+
+fn default_confidence() -> f32 {
+    0.5
+}
+
+fn default_priority() -> u8 {
+    50
+}
+
+/// 编译后的规则（正则只编译一次）。
+#[derive(Debug, Clone)]
+pub struct CompiledRule {
+    rule: Rule,
+    category: RuleCategory,
+    regex: Regex,
+}
+
+impl CompiledRule {
+    /// 编译一条规则。
+    pub fn compile(rule: Rule, category: RuleCategory) -> Result<Self, RuleError> {
+        let regex = Regex::new(&rule.pattern).map_err(|err| RuleError::InvalidPattern {
+            id: rule.id.clone(),
+            message: err.to_string(),
+        })?;
+        Ok(Self {
+            rule,
+            category,
+            regex,
+        })
+    }
+
+    /// 原始规则。
+    #[must_use]
+    pub const fn rule(&self) -> &Rule {
+        &self.rule
+    }
+
+    /// 规则 id。
+    #[must_use]
+    pub fn id(&self) -> &str {
+        &self.rule.id
+    }
+
+    /// 所属分类。
+    #[must_use]
+    pub const fn category(&self) -> RuleCategory {
+        self.category
+    }
+
+    /// 匹配范围。
+    #[must_use]
+    pub const fn scope(&self) -> MatchScope {
+        self.rule.scope
+    }
+
+    /// 编译好的正则。
+    #[must_use]
+    pub const fn regex(&self) -> &Regex {
+        &self.regex
+    }
+
+    /// 命名捕获组名（文档/测试用；顺序无关，取代 HMCL 的 `groupNames` 契约）。
+    #[must_use]
+    pub fn named_groups(&self) -> Vec<&str> {
+        self.regex.capture_names().flatten().collect()
+    }
+}
+
+/// 规则编译错误。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum RuleError {
+    /// 正则非法（规则 id + 正则库报错原文）。
+    InvalidPattern {
+        /// 出错的规则 id。
+        id: String,
+        /// 正则库报错。
+        message: String,
+    },
+}
+
+impl fmt::Display for RuleError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::InvalidPattern { id, message } => {
+                write!(f, "规则 {id} 的正则非法：{message}")
+            }
+        }
+    }
+}
+
+impl std::error::Error for RuleError {}
+
+/// 把 `{group}` 占位符替换成捕获组值；未知占位符原样保留（便于发现规则写错）。
+#[must_use]
+pub fn substitute(template: &str, groups: &BTreeMap<String, String>) -> String {
+    if !template.contains('{') {
+        return template.to_owned();
+    }
+    let mut out = String::with_capacity(template.len());
+    let mut rest = template;
+    while let Some(start) = rest.find('{') {
+        let Some(close) = rest[start..].find('}') else {
+            break;
+        };
+        let end = start + close;
+        let name = &rest[start + 1..end];
+        out.push_str(&rest[..start]);
+        match groups.get(name) {
+            Some(value) => out.push_str(value),
+            None => out.push_str(&rest[start..=end]),
+        }
+        rest = &rest[end + 1..];
+    }
+    out.push_str(rest);
+    out
+}
diff --git a/crates/core/src/diagnose/signals.rs b/crates/core/src/diagnose/signals.rs
new file mode 100644
index 0000000..73a34d7
--- /dev/null
+++ b/crates/core/src/diagnose/signals.rs
@@ -0,0 +1,396 @@
+//! 采集到的原子信号：日志环形缓冲 + 退出信号。
+//!
+//! 五类信号里的「退出码」和「日志环形缓冲」两种（analyse/02 §7.1 信号 A/B）。
+//! 环境快照（信号 E）与 mod 清单在 [`crate::diagnose::collectors`] 里，因为它带采集动作。
+//!
+//! 环形缓冲相对 HMCL `Log.java`（固定 2000 行、一律淘汰）的升级：
+//! 命中 `Exception|Error|Caused by|OutOfMemory` 的行**永久保留**，
+//! 解决「崩在启动早期、根因被后续输出挤出缓冲区」（analyse/02 §7.10-3）。
+
+use std::collections::VecDeque;
+use std::fmt;
+
+/// 一条日志文本的来源（诊断输出的 `evidence[]` 前缀也是它）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub enum SignalOrigin {
+    /// 游戏进程 stdout。
+    Stdout,
+    /// 游戏进程 stderr。
+    Stderr,
+    /// `logs/latest.log`（内存缓冲不够长时的兜底）。
+    LatestLog,
+    /// `crash-reports/crash-*.txt`。
+    CrashReport,
+    /// `hs_err_pid*.log` 的摘要文本。
+    HsErr,
+    /// 启动器自身日志 / 结构化事件（`cmd_built`、`assembly_failed` 等）。
+    Launcher,
+}
+
+impl SignalOrigin {
+    /// 稳定字符串（evidence 前缀 / 序列化用）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Stdout => "stdout",
+            Self::Stderr => "stderr",
+            Self::LatestLog => "latest_log",
+            Self::CrashReport => "crash_report",
+            Self::HsErr => "hs_err",
+            Self::Launcher => "launcher",
+        }
+    }
+
+    /// `launch` 侧 `LineSink` 的 `stream` 字段映射（`stdout` / `stderr`）。
+    #[must_use]
+    pub fn from_stream_name(stream: &str) -> Self {
+        match stream.trim().to_ascii_lowercase().as_str() {
+            "stderr" => Self::Stderr,
+            _ => Self::Stdout,
+        }
+    }
+
+    /// 取证优先级：同一规则在多个来源命中时保留 rank 最小者（崩溃报告 > hs_err > 日志）。
+    #[must_use]
+    pub const fn evidence_rank(self) -> u8 {
+        match self {
+            Self::CrashReport => 0,
+            Self::HsErr => 1,
+            Self::Launcher => 2,
+            Self::LatestLog => 3,
+            Self::Stdout => 4,
+            Self::Stderr => 5,
+        }
+    }
+}
+
+impl fmt::Display for SignalOrigin {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+/// 环形缓冲里的一行。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LogLine {
+    /// 来源。
+    pub origin: SignalOrigin,
+    /// 行文本（不含行尾换行）。
+    pub text: String,
+}
+
+impl LogLine {
+    /// 构造一行。
+    #[must_use]
+    pub fn new(origin: SignalOrigin, text: impl Into<String>) -> Self {
+        Self {
+            origin,
+            text: text.into(),
+        }
+    }
+}
+
+/// 是否「关键行」：不随环形淘汰（HMCL 局限 3 的正面修正）。
+#[must_use]
+pub fn is_key_line(text: &str) -> bool {
+    const MARKERS: [&str; 4] = ["Exception", "Error", "Caused by", "OutOfMemory"];
+    MARKERS.iter().any(|marker| text.contains(marker))
+}
+
+/// 日志环形缓冲：最近 N 行 + 被判为关键行的历史永久保留。
+#[derive(Debug, Clone)]
+pub struct LogBuffer {
+    capacity: usize,
+    key_capacity: usize,
+    recent: VecDeque<LogLine>,
+    /// 已从环形区淘汰、但因为是关键行而留下来的行（按时间顺序）。
+    kept: VecDeque<LogLine>,
+    pushed: usize,
+    dropped: usize,
+}
+
+impl Default for LogBuffer {
+    fn default() -> Self {
+        Self::new(2000)
+    }
+}
+
+impl LogBuffer {
+    /// 默认容量 2000 行（与 HMCL 的 `Log` 一致）。
+    #[must_use]
+    pub fn new(capacity: usize) -> Self {
+        Self {
+            capacity: capacity.max(1),
+            key_capacity: capacity.max(1),
+            recent: VecDeque::new(),
+            kept: VecDeque::new(),
+            pushed: 0,
+            dropped: 0,
+        }
+    }
+
+    /// 关键行保留上限（默认 = 环形容量）。
+    #[must_use]
+    pub fn with_key_capacity(mut self, key_capacity: usize) -> Self {
+        self.key_capacity = key_capacity.max(1);
+        self
+    }
+
+    /// 记一行（`launch` 的 stdout/stderr 事件逐行喂进来）。
+    pub fn push(&mut self, origin: SignalOrigin, line: &str) {
+        let text = line.trim_end_matches(['\r', '\n']).to_owned();
+        self.pushed += 1;
+        if self.recent.len() >= self.capacity {
+            if let Some(evicted) = self.recent.pop_front() {
+                self.dropped += 1;
+                if is_key_line(&evicted.text) {
+                    if self.kept.len() >= self.key_capacity {
+                        self.kept.pop_front();
+                    }
+                    self.kept.push_back(evicted);
+                }
+            }
+        }
+        self.recent.push_back(LogLine::new(origin, text));
+    }
+
+    /// 一次性喂多行（导入日志、`latest.log` 兜底）。
+    pub fn extend<'a, I>(&mut self, origin: SignalOrigin, lines: I)
+    where
+        I: IntoIterator<Item = &'a str>,
+    {
+        for line in lines {
+            self.push(origin, line);
+        }
+    }
+
+    /// 按时间顺序返回全部保留行（关键行历史在前，最近 N 行在后）。
+    pub fn lines(&self) -> impl Iterator<Item = &LogLine> {
+        self.kept.iter().chain(self.recent.iter())
+    }
+
+    /// 拼成可供规则匹配的文本（`\n` 连接）。
+    #[must_use]
+    pub fn text(&self) -> String {
+        let mut out = String::with_capacity(self.byte_len());
+        for line in self.lines() {
+            out.push_str(&line.text);
+            out.push('\n');
+        }
+        out
+    }
+
+    /// 当前保留行数。
+    #[must_use]
+    pub fn len(&self) -> usize {
+        self.kept.len() + self.recent.len()
+    }
+
+    /// 是否一行都没有。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.len() == 0
+    }
+
+    /// 一共推入多少行。
+    #[must_use]
+    pub const fn pushed(&self) -> usize {
+        self.pushed
+    }
+
+    /// 被淘汰多少行（不含被永久保留的关键行）。
+    #[must_use]
+    pub const fn dropped(&self) -> usize {
+        self.dropped
+    }
+
+    /// 因关键行规则而保留下来的历史行数。
+    #[must_use]
+    pub fn kept_key_lines(&self) -> usize {
+        self.kept.len()
+    }
+
+    fn byte_len(&self) -> usize {
+        self.lines().map(|line| line.text.len() + 1).sum()
+    }
+}
+
+/// 退出类型。字符串值与 `launch-接口约定.md` §3 `exit.exit_type` 完全一致。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
+pub enum ExitType {
+    /// 正常退出（但可能是静默失败，见 [`ExitSignal::silent_failure`]）。
+    #[default]
+    Normal,
+    /// 应用层崩溃（有崩溃关键字 / 非 0 退出码）。
+    ApplicationError,
+    /// JVM 没起来（`-Xmx` 过大、参数非法、JVM 致命错误）。
+    JvmError,
+    /// 被 SIGKILL（Linux 137 / 系统 OOM killer）。
+    Sigkill,
+    /// 被 SIGTERM（143）。
+    Sigterm,
+    /// 被启动器主动停止（用户取消 / watchdog）。
+    Killed,
+    /// 等待被中断（会话被丢弃）。
+    Interrupted,
+}
+
+impl ExitType {
+    /// 稳定字符串（与 launch 约定同值）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Normal => "normal",
+            Self::ApplicationError => "application_error",
+            Self::JvmError => "jvm_error",
+            Self::Sigkill => "sigkill",
+            Self::Sigterm => "sigterm",
+            Self::Killed => "killed",
+            Self::Interrupted => "interrupted",
+        }
+    }
+
+    /// 从 launch 约定字符串反解（未知值回落 `ApplicationError`，绝不 panic）。
+    #[must_use]
+    pub fn from_name(name: &str) -> Self {
+        match name.trim().to_ascii_lowercase().as_str() {
+            "normal" => Self::Normal,
+            "jvm_error" => Self::JvmError,
+            "sigkill" => Self::Sigkill,
+            "sigterm" => Self::Sigterm,
+            "killed" => Self::Killed,
+            "interrupted" => Self::Interrupted,
+            _ => Self::ApplicationError,
+        }
+    }
+
+    /// 是否异常结束（非 `Normal`）。
+    #[must_use]
+    pub const fn is_abnormal(self) -> bool {
+        !matches!(self, Self::Normal)
+    }
+}
+
+impl fmt::Display for ExitType {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+/// JVM 没起来的三个签名（analyse/02 §7.2，`JVM_ERROR` 判定依据）。
+pub const JVM_ERROR_KEYWORDS: [&str; 3] = [
+    "Could not create the Java Virtual Machine",
+    "Error occurred during initialization of VM",
+    "A fatal exception has occurred. Program will exit.",
+];
+
+/// 应用层崩溃关键字（HMCL `ExitWaiter` 的 5 条 + 我们能拿到的补充）。
+pub const CRASH_KEYWORDS: [&str; 5] = [
+    "Game crashed! Crash report saved to",
+    "Exception in thread",
+    "Unhandled exception",
+    "Unable to launch",
+    "An exception was thrown, the game will display an error screen and halt",
+];
+
+/// Windows 常见退出码（`0xC0000005` 等按 `i32` 表示，analyse/02 §8.4-2）。
+pub const EXIT_ACCESS_VIOLATION: i32 = -1_073_741_819;
+/// `0xC0000409` STACK_BUFFER_OVERRUN。
+pub const EXIT_STACK_BUFFER_OVERRUN: i32 = -1_073_740_791;
+/// `0xC0000135` DLL_NOT_FOUND。
+pub const EXIT_DLL_NOT_FOUND: i32 = -1_073_741_515;
+/// POSIX SIGKILL（128 + 9）。
+pub const EXIT_SIGKILL: i32 = 137;
+/// POSIX SIGTERM（128 + 15）。
+pub const EXIT_SIGTERM: i32 = 143;
+
+/// 进程退出信号（`launch` 的 `exit` 事件映射过来；离线诊断时由 [`ExitSignal::classify`] 反推）。
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct ExitSignal {
+    /// 退出码（被信号杀死时为负或 128+N）。
+    pub code: Option<i32>,
+    /// 退出类型。
+    pub exit_type: ExitType,
+    /// 进程存活毫秒数。
+    pub uptime_ms: Option<u64>,
+    /// stderr/错误行条数。
+    pub error_lines: u32,
+    /// 退出码 0 但疑似静默失败（存活 <30s 或 stderr 有错误特征）。
+    pub silent_failure: bool,
+    /// Windows 状态码原始串（`0xc0000005`）。
+    pub windows_status: Option<String>,
+    /// 命中的崩溃关键字。
+    pub crash_keywords: Vec<String>,
+}
+
+impl ExitSignal {
+    /// 从原始退出事实推断类型（离线诊断 / 导入日志用；launch 侧有权威版本）。
+    #[must_use]
+    pub fn classify(
+        code: Option<i32>,
+        uptime_ms: Option<u64>,
+        error_lines: u32,
+        error_text: &str,
+    ) -> Self {
+        let has = |keywords: &[&str]| keywords.iter().any(|kw| error_text.contains(kw));
+        let mut crash_keywords = Vec::new();
+        for keyword in CRASH_KEYWORDS {
+            if error_text.contains(keyword) {
+                crash_keywords.push(keyword.to_owned());
+            }
+        }
+        let exit_type = match code {
+            Some(EXIT_SIGKILL) => ExitType::Sigkill,
+            Some(EXIT_SIGTERM) => ExitType::Sigterm,
+            // 与 HMCL `ExitType` 一致：只有「非 0 退出码 + JVM 关键字」才算 JVM_ERROR。
+            // exit 0 却打出这些关键字的场景归到靜默失败（silent_failure）而不是 JVM 错误。
+            Some(0) => ExitType::Normal,
+            Some(_) if has(&JVM_ERROR_KEYWORDS) => ExitType::JvmError,
+            Some(_) => ExitType::ApplicationError,
+            None => ExitType::ApplicationError,
+        };
+        let short_lived = uptime_ms.is_some_and(|ms| ms < 30_000);
+        let silent_failure = exit_type == ExitType::Normal
+            && (short_lived || error_lines > 0 || has(&CRASH_KEYWORDS));
+        Self {
+            code,
+            exit_type,
+            uptime_ms,
+            error_lines,
+            silent_failure,
+            windows_status: code.and_then(hex_status),
+            crash_keywords,
+        }
+    }
+
+    /// Windows 状态码的十六进制串（如 `0xc0000005`）。
+    #[must_use]
+    pub fn status_hex(&self) -> Option<String> {
+        self.windows_status
+            .clone()
+            .or_else(|| self.code.and_then(hex_status))
+    }
+
+    /// 退出码是否是 Windows 访问违例（`0xC0000005`）。
+    #[must_use]
+    pub fn is_access_violation(&self) -> bool {
+        self.code == Some(EXIT_ACCESS_VIOLATION)
+    }
+
+    /// 一句话摘要（写进诊断报告 / 证据行）。
+    #[must_use]
+    pub fn summary(&self) -> String {
+        let code = self
+            .code
+            .map_or_else(|| "未知".to_owned(), |code| code.to_string());
+        let uptime = self
+            .uptime_ms
+            .map_or_else(String::new, |ms| format!("，存活 {} ms", ms));
+        format!("退出码 {code}（{}）{uptime}", self.exit_type)
+    }
+}
+
+fn hex_status(code: i32) -> Option<String> {
+    // 只有 Windows 的 NTSTATUS 形态（负数高位为 1）才有意义。
+    (code < 0).then(|| format!("0x{:08x}", code as u32))
+}
diff --git a/crates/core/src/diagnose/sources.rs b/crates/core/src/diagnose/sources.rs
new file mode 100644
index 0000000..49cddd1
--- /dev/null
+++ b/crates/core/src/diagnose/sources.rs
@@ -0,0 +1,299 @@
+//! 五类信号的具体采集器（推送类 2 个 + 磁盘类 3 个）。
+//!
+//! 由 `collectors.rs` 用 `#[path]` 声明并统一导出；拆分只为守单文件 400 行上限。
+
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::time::SystemTime;
+
+use crate::diagnose::hs_err;
+
+use super::{
+    CapturedText, CollectError, CollectedSources, CollectionContext, EnvironmentSnapshot,
+    ExitSignal, SignalBundle, SignalCollector, SignalKind, SignalOrigin,
+};
+
+/// 推送类：退出信号（launch 的 `exit` 事件已算好）。
+#[derive(Debug, Clone)]
+pub struct ExitCollector {
+    signal: ExitSignal,
+}
+
+impl ExitCollector {
+    /// 构造。
+    #[must_use]
+    pub fn new(signal: ExitSignal) -> Self {
+        Self { signal }
+    }
+}
+
+impl SignalCollector for ExitCollector {
+    fn kind(&self) -> SignalKind {
+        SignalKind::Exit
+    }
+
+    fn collect(
+        &self,
+        _ctx: &CollectionContext,
+        out: &mut SignalBundle,
+    ) -> Result<CollectedSources, CollectError> {
+        out.exit = Some(self.signal.clone());
+        Ok(CollectedSources::new())
+    }
+}
+
+/// 推送类：环境快照 + mod 清单（launch/game 侧已有数据）。
+#[derive(Debug, Clone, Default)]
+pub struct EnvironmentCollector {
+    snapshot: EnvironmentSnapshot,
+}
+
+impl EnvironmentCollector {
+    /// 构造。
+    #[must_use]
+    pub fn new(snapshot: EnvironmentSnapshot) -> Self {
+        Self { snapshot }
+    }
+}
+
+impl SignalCollector for EnvironmentCollector {
+    fn kind(&self) -> SignalKind {
+        SignalKind::Environment
+    }
+
+    fn collect(
+        &self,
+        _ctx: &CollectionContext,
+        out: &mut SignalBundle,
+    ) -> Result<CollectedSources, CollectError> {
+        out.mods = self.snapshot.mods.clone();
+        out.environment = Some(self.snapshot.clone());
+        Ok(CollectedSources::new())
+    }
+}
+
+/// 磁盘类：`crash-reports/crash-*.txt`（双通道里的「权威全文」）。
+#[derive(Debug, Clone, Default)]
+pub struct CrashReportCollector {
+    dir: Option<PathBuf>,
+}
+
+impl CrashReportCollector {
+    /// 默认扫 `<run_dir>/crash-reports`。
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// 指定目录。
+    #[must_use]
+    pub fn with_dir(dir: impl Into<PathBuf>) -> Self {
+        Self {
+            dir: Some(dir.into()),
+        }
+    }
+}
+
+impl SignalCollector for CrashReportCollector {
+    fn kind(&self) -> SignalKind {
+        SignalKind::CrashReport
+    }
+
+    fn collect(
+        &self,
+        ctx: &CollectionContext,
+        out: &mut SignalBundle,
+    ) -> Result<CollectedSources, CollectError> {
+        let dir = self
+            .dir
+            .clone()
+            .unwrap_or_else(|| ctx.run_dir.join("crash-reports"));
+        let Some(path) = newest_file(&dir, ctx.started_at, |name| {
+            name.starts_with("crash-") && name.ends_with(".txt")
+        }) else {
+            return Ok(CollectedSources::new());
+        };
+        let text = read_lossy(SignalKind::CrashReport, &path)?;
+        let modified = modified_at(&path);
+        let mut sources = CollectedSources::new();
+        sources.push(&path);
+        out.sources.push(path.clone());
+        out.crash_report = Some(CapturedText {
+            path,
+            text,
+            modified,
+        });
+        Ok(sources)
+    }
+}
+
+/// 磁盘类：`hs_err_pid*.log`（HMCL 的空白区，显卡驱动类崩溃的唯一权威证据）。
+#[derive(Debug, Clone, Default)]
+pub struct HsErrCollector {
+    dirs: Vec<PathBuf>,
+}
+
+impl HsErrCollector {
+    /// 默认扫 `<run_dir>`（JVM 把 hs_err 写在进程工作目录）。
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// 指定候选目录表（**整表替换**，不是追加；给出后不再自动扫 `run_dir`）。
+    ///
+    /// 典型用法：`HsErrCollector::with_dirs([run_dir.clone(), home_dir])`。
+    #[must_use]
+    pub fn with_dirs(dirs: impl IntoIterator<Item = PathBuf>) -> Self {
+        Self {
+            dirs: dirs.into_iter().collect(),
+        }
+    }
+}
+
+impl SignalCollector for HsErrCollector {
+    fn kind(&self) -> SignalKind {
+        SignalKind::HsErr
+    }
+
+    fn collect(
+        &self,
+        ctx: &CollectionContext,
+        out: &mut SignalBundle,
+    ) -> Result<CollectedSources, CollectError> {
+        let dirs = if self.dirs.is_empty() {
+            vec![ctx.run_dir.clone()]
+        } else {
+            self.dirs.clone()
+        };
+        let mut newest: Option<PathBuf> = None;
+        for dir in dirs {
+            if let Some(path) = newest_file(&dir, ctx.started_at, |name| {
+                name.starts_with("hs_err_pid") && name.ends_with(".log")
+            }) {
+                newest = match newest {
+                    Some(current) => match (modified_at(&current), modified_at(&path)) {
+                        (Some(a), Some(b)) if b <= a => Some(current),
+                        _ => Some(path),
+                    },
+                    None => Some(path),
+                };
+            }
+        }
+        let Some(path) = newest else {
+            return Ok(CollectedSources::new());
+        };
+        let report = hs_err::parse_file(&path).map_err(|error| CollectError {
+            kind: SignalKind::HsErr,
+            path: Some(path.clone()),
+            message: error.to_string(),
+        })?;
+        let mut sources = CollectedSources::new();
+        sources.push(&path);
+        out.sources.push(path);
+        out.hs_err = Some(report);
+        Ok(sources)
+    }
+}
+
+/// 磁盘类：`logs/latest.log` 尾巴（内存缓冲不够长时的兜底）。
+#[derive(Debug, Clone)]
+pub struct LatestLogCollector {
+    path: Option<PathBuf>,
+    max_lines: usize,
+}
+
+impl Default for LatestLogCollector {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl LatestLogCollector {
+    /// 默认读 `<run_dir>/logs/latest.log` 的最后 5000 行。
+    #[must_use]
+    pub fn new() -> Self {
+        Self {
+            path: None,
+            max_lines: 5000,
+        }
+    }
+
+    /// 保留行数上限。
+    #[must_use]
+    pub fn with_max_lines(mut self, max_lines: usize) -> Self {
+        self.max_lines = max_lines.max(1);
+        self
+    }
+
+    /// 指定文件。
+    #[must_use]
+    pub fn with_path(path: impl Into<PathBuf>) -> Self {
+        Self {
+            path: Some(path.into()),
+            max_lines: 5000,
+        }
+    }
+}
+
+impl SignalCollector for LatestLogCollector {
+    fn kind(&self) -> SignalKind {
+        SignalKind::Log
+    }
+
+    fn collect(
+        &self,
+        ctx: &CollectionContext,
+        out: &mut SignalBundle,
+    ) -> Result<CollectedSources, CollectError> {
+        let path = self
+            .path
+            .clone()
+            .unwrap_or_else(|| ctx.run_dir.join("logs").join("latest.log"));
+        if !path.is_file() {
+            return Ok(CollectedSources::new());
+        }
+        let text = read_lossy(SignalKind::Log, &path)?;
+        let lines = text.lines().collect::<Vec<_>>();
+        let start = lines.len().saturating_sub(self.max_lines);
+        out.log
+            .extend(SignalOrigin::LatestLog, lines[start..].iter().copied());
+        let mut sources = CollectedSources::new();
+        sources.push(&path);
+        out.sources.push(path);
+        Ok(sources)
+    }
+}
+
+fn newest_file(
+    dir: &Path,
+    since: Option<SystemTime>,
+    matches: impl Fn(&str) -> bool,
+) -> Option<PathBuf> {
+    let entries = fs::read_dir(dir).ok()?;
+    entries
+        .flatten()
+        .filter_map(|entry| {
+            let name = entry.file_name().to_string_lossy().into_owned();
+            if !matches(&name) {
+                return None;
+            }
+            let path = entry.path();
+            let modified = modified_at(&path)?;
+            if since.is_some_and(|since| modified < since) {
+                return None;
+            }
+            Some((modified, path))
+        })
+        .max_by(|a, b| a.0.cmp(&b.0))
+        .map(|(_, path)| path)
+}
+
+fn modified_at(path: &Path) -> Option<SystemTime> {
+    fs::metadata(path).ok()?.modified().ok()
+}
+
+fn read_lossy(kind: SignalKind, path: &Path) -> Result<String, CollectError> {
+    let bytes = fs::read(path).map_err(|error| CollectError::io(kind, path, &error))?;
+    Ok(String::from_utf8_lossy(&bytes).into_owned())
+}
diff --git a/crates/core/src/diagnose/synthetic.rs b/crates/core/src/diagnose/synthetic.rs
new file mode 100644
index 0000000..3353bd6
--- /dev/null
+++ b/crates/core/src/diagnose/synthetic.rs
@@ -0,0 +1,279 @@
+//! 引擎内置结论：退出码 / hs_err 这类**结构化信号**没有文本签名，塞 YAML 别扭，放在这里。
+//!
+//! 它们参与和其它规则一样的排序与抑制流程（`priority`/`confidence`/`suppress` 语义相同），
+//! 所以「主因是驱动、次生是图形规则」这种关系能自动成立。
+//! 由 `engine.rs` 用 `#[path]` 声明，拆分只为守单文件 400 行上限。
+
+use super::{DiagnosisInput, Evidence, Finding};
+use crate::diagnose::collectors::{
+    ExitSignal, ExitType, SignalOrigin, EXIT_DLL_NOT_FOUND, EXIT_STACK_BUFFER_OVERRUN,
+};
+use crate::diagnose::hs_err::{HsErrKind, HsErrReport};
+use crate::diagnose::rules::{
+    AdjustMemory, ChangeGraphics, ChangeJava, ComponentKind, FixAction, GraphicsSetting,
+    JavaVendor, Reinstall, RuleCategory, SeekHelp, Severity,
+};
+
+/// 所有内置结论。
+#[must_use]
+pub fn synthetic_findings(input: &DiagnosisInput) -> Vec<Finding> {
+    let mut out = Vec::new();
+    if let Some(exit) = &input.exit {
+        out.extend(exit_findings(exit));
+    }
+    if let Some(report) = &input.hs_err {
+        out.extend(hs_err_findings(report));
+    }
+    out
+}
+
+fn exit_findings(exit: &ExitSignal) -> Vec<Finding> {
+    let mut out = Vec::new();
+    if exit.is_access_violation() {
+        let mut finding = base(
+            "signal.access_violation",
+            RuleCategory::Graphics,
+            Severity::Critical,
+            0.55,
+            82,
+            "diagnose.cause.signal.access_violation",
+            &format!(
+                "进程以 0xC0000005（访问违例）退出：多半是显卡驱动/渲染栈崩溃，建议先更新显卡驱动或换渲染器（{}）",
+                exit.summary()
+            ),
+        );
+        finding.fix_actions = vec![FixAction::ChangeGraphics(ChangeGraphics {
+            setting: GraphicsSetting::Driver,
+            update_driver: true,
+            suggested_value: None,
+            note: Some("访问违例优先怀疑显卡驱动".to_owned()),
+        })];
+        finding.suppress = vec!["graphics.graphics_driver".to_owned()];
+        finding.evidence = vec![Evidence::new(SignalOrigin::Launcher, 0, exit.summary())];
+        out.push(finding);
+    }
+    if exit.code == Some(EXIT_DLL_NOT_FOUND) {
+        let mut finding = base(
+            "signal.dll_not_found",
+            RuleCategory::Integrity,
+            Severity::Critical,
+            0.7,
+            85,
+            "diagnose.cause.signal.dll_not_found",
+            "进程以 0xC0000135（找不到 DLL）退出：缺原生库或 Java 安装损坏，重装 natives/Java 组件",
+        );
+        finding.fix_actions = vec![FixAction::Reinstall(Reinstall {
+            component: ComponentKind::Natives,
+            path_hint: None,
+            note: Some("找不到 DLL：优先修 natives，其次重装 Java".to_owned()),
+        })];
+        finding.evidence = vec![Evidence::new(SignalOrigin::Launcher, 0, exit.summary())];
+        out.push(finding);
+    }
+    if exit.code == Some(EXIT_STACK_BUFFER_OVERRUN) {
+        let mut finding = base(
+            "signal.stack_buffer_overrun",
+            RuleCategory::Jvm,
+            Severity::Warning,
+            0.5,
+            60,
+            "diagnose.cause.signal.stack_buffer_overrun",
+            "进程以 0xC0000409（栈缓冲区溢出）退出：JVM/原生库内部错误，需要 hs_err 或崩溃报告进一步判断",
+        );
+        finding.fix_actions = vec![FixAction::SeekHelp(SeekHelp {
+            export_diagnostics: true,
+            needs_more_info: vec!["run 目录下的 hs_err_pid*.log".to_owned()],
+            note: None,
+        })];
+        finding.evidence = vec![Evidence::new(SignalOrigin::Launcher, 0, exit.summary())];
+        out.push(finding);
+    }
+    if exit.exit_type == ExitType::Sigkill {
+        let mut finding = base(
+            "signal.sigkill",
+            RuleCategory::Memory,
+            Severity::Warning,
+            0.6,
+            70,
+            "diagnose.cause.signal.sigkill",
+            "进程被 SIGKILL 强杀：常见于系统内存耗尽（OOM killer）或外部清理进程，建议降低 -Xmx 或扩大虚拟内存",
+        );
+        finding.fix_actions = vec![FixAction::AdjustMemory(AdjustMemory {
+            increase_system_swap: true,
+            note: Some("被强杀：先确认系统内存是否够".to_owned()),
+            ..AdjustMemory::default()
+        })];
+        finding.evidence = vec![Evidence::new(SignalOrigin::Launcher, 0, exit.summary())];
+        out.push(finding);
+    }
+    if exit.exit_type == ExitType::JvmError {
+        let mut finding = base(
+            "signal.jvm_error",
+            RuleCategory::Jvm,
+            Severity::Critical,
+            0.55,
+            72,
+            "diagnose.cause.signal.jvm_error",
+            "JVM 未能启动（游戏根本没跑起来）：先查 -Xmx 是否超过可用内存、JVM 参数是否非法",
+        );
+        finding.fix_actions = vec![
+            FixAction::AdjustMemory(AdjustMemory {
+                increase_system_swap: true,
+                note: Some("JVM 初始化失败，优先怀疑 -Xmx 过大".to_owned()),
+                ..AdjustMemory::default()
+            }),
+            FixAction::ChangeJava(ChangeJava {
+                vendor: JavaVendor::Hotspot,
+                note: Some("换成 HotSpot 的官方 Java 试试".to_owned()),
+                ..ChangeJava::default()
+            }),
+        ];
+        finding.evidence = vec![Evidence::new(SignalOrigin::Launcher, 0, exit.summary())];
+        out.push(finding);
+    }
+    if exit.silent_failure {
+        let mut finding = base(
+            "signal.silent_failure",
+            RuleCategory::Other,
+            Severity::Warning,
+            0.4,
+            55,
+            "diagnose.cause.signal.silent_failure",
+            &format!(
+                "退出码为 0 但疑似静默失败（{} 条错误行）：游戏可能刚起来就被 mod 异常终止，需要更长的日志确认",
+                exit.error_lines
+            ),
+        );
+        finding.fix_actions = vec![FixAction::SeekHelp(SeekHelp {
+            export_diagnostics: true,
+            needs_more_info: vec!["把日志行数上限调到 20000 后复现一次".to_owned()],
+            note: None,
+        })];
+        finding.evidence = vec![Evidence::new(SignalOrigin::Launcher, 0, exit.summary())];
+        out.push(finding);
+    }
+    out
+}
+
+fn hs_err_findings(report: &HsErrReport) -> Vec<Finding> {
+    let mut out = Vec::new();
+    match report.kind {
+        HsErrKind::AccessViolation => {
+            let module = report
+                .failed_frame
+                .as_ref()
+                .and_then(|frame| frame.module.clone())
+                .unwrap_or_else(|| "未知模块".to_owned());
+            let mut finding = base(
+                "hs_err.access_violation",
+                RuleCategory::Graphics,
+                Severity::Critical,
+                0.75,
+                88,
+                "diagnose.cause.hs_err.access_violation",
+                &format!(
+                    "JVM 致命错误 {module}（访问违例，失败帧 {}）：原生层崩溃，显卡驱动/渲染栈是首要嫌疑",
+                    report
+                        .failed_frame
+                        .as_ref()
+                        .map_or("未知", |frame| frame.raw.as_str())
+                ),
+            );
+            finding.fix_actions = vec![
+                FixAction::ChangeGraphics(ChangeGraphics {
+                    setting: GraphicsSetting::Driver,
+                    update_driver: true,
+                    suggested_value: None,
+                    note: Some(format!("失败帧落在 {module}")),
+                }),
+                FixAction::SeekHelp(SeekHelp {
+                    export_diagnostics: true,
+                    needs_more_info: Vec::new(),
+                    note: Some("把 hs_err 一并上报，便于确认驱动版本".to_owned()),
+                }),
+            ];
+            finding.suppress = vec!["graphics.graphics_driver".to_owned()];
+            finding.evidence = vec![Evidence::new(SignalOrigin::HsErr, 1, report.summary())];
+            out.push(finding);
+        }
+        HsErrKind::OutOfMemory => {
+            let memory = report
+                .memory
+                .as_ref()
+                .map_or_else(String::new, |memory| memory.summary());
+            let mut finding = base(
+                "hs_err.out_of_memory",
+                RuleCategory::Memory,
+                Severity::Critical,
+                0.85,
+                86,
+                "diagnose.cause.hs_err.out_of_memory",
+                &format!("JVM 因内存不足终止：{memory}，降低 -Xmx 或扩大系统虚拟内存"),
+            );
+            finding.fix_actions = vec![FixAction::AdjustMemory(AdjustMemory {
+                increase_system_swap: true,
+                note: Some(memory),
+                ..AdjustMemory::default()
+            })];
+            finding.evidence = vec![Evidence::new(SignalOrigin::HsErr, 1, report.summary())];
+            out.push(finding);
+        }
+        HsErrKind::StackOverflow => {
+            let mut finding = base(
+                "hs_err.stack_overflow",
+                RuleCategory::ModRuntime,
+                Severity::Warning,
+                0.6,
+                62,
+                "diagnose.cause.hs_err.stack_overflow",
+                "JVM 栈溢出导致的致命错误：通常是某个 mod 的递归/死循环，禁用最近装的 mod 再试",
+            );
+            finding.fix_actions = vec![FixAction::SeekHelp(SeekHelp {
+                export_diagnostics: true,
+                needs_more_info: vec!["最近安装/更新的 mod 列表".to_owned()],
+                note: None,
+            })];
+            finding.evidence = vec![Evidence::new(SignalOrigin::HsErr, 1, report.summary())];
+            out.push(finding);
+        }
+        HsErrKind::InternalError => {
+            let mut finding = base(
+                "hs_err.internal_error",
+                RuleCategory::Jvm,
+                Severity::Warning,
+                0.5,
+                62,
+                "diagnose.cause.hs_err.internal_error",
+                "JVM 内部致命错误：优先换官方 HotSpot Java，其次怀疑原生库（natives）损坏",
+            );
+            finding.fix_actions = vec![FixAction::ChangeJava(ChangeJava {
+                vendor: JavaVendor::Hotspot,
+                ..ChangeJava::default()
+            })];
+            finding.evidence = vec![Evidence::new(SignalOrigin::HsErr, 1, report.summary())];
+            out.push(finding);
+        }
+        HsErrKind::Other => {}
+    }
+    out
+}
+
+fn base(
+    rule_id: &str,
+    category: RuleCategory,
+    severity: Severity,
+    confidence: f32,
+    priority: u8,
+    message_key: &str,
+    message: &str,
+) -> Finding {
+    Finding::skeleton(
+        rule_id,
+        category,
+        severity,
+        confidence,
+        priority,
+        message_key,
+        message,
+    )
+}
diff --git a/crates/core/src/download/adoptium.rs b/crates/core/src/download/adoptium.rs
new file mode 100644
index 0000000..a08f6ca
--- /dev/null
+++ b/crates/core/src/download/adoptium.rs
@@ -0,0 +1,204 @@
+//! Adoptium（Temurin）JDK 的院校镜像展开。
+//!
+//! D13 定案：国内模式下 JDK 按健康度在 TUNA / 华为云 等镜像之间选，
+//! 全部不可达才回官方。难点是**镜像路径与官方下载链接不同形**：
+//!
+//! 官方（api.adoptium.net 会 302 到这里）：
+//! `https://github.com/adoptium/temurin17-binaries/releases/download/JDK17.0.13+11/OpenJDK17U-jdk_x64_windows_hotspot_17.0.13_11.zip`
+//! 清华 TUNA：
+//! `https://mirrors.tuna.tsinghua.edu.cn/Adoptium/17/jdk/x64/windows/OpenJDK17U-jdk_x64_windows_hotspot_17.0.13_11.zip`
+//!
+//! 所以这里按产物文件名反解 `(major, flavor, arch, os, filename)`，再按各镜像的模板拼目标 URL。
+//! **`flavor` 必须是 `jdk` 或 `jre`**：院校镜像的目录结构是 `/{major}/{jdk|jre}/{arch}/{os}/`，
+//! JRE 请求若错拼成 `/jdk/` 会 404 打满所有镜像，最后退回官方直链（镜像加速白费）。
+//! 解析失败不报错——只保留官方源，下载照常能完成。
+//!
+//! # 清单可用性（M33 实测，2026-10-30）
+//!
+//! 按 `{base}/{21}/jdk/x64/windows/<Temurin 文件名>` 逐个打点：
+//!
+//! | 镜像 | 结果 |
+//! | --- | --- |
+//! | 清华 TUNA `mirrors.tuna.tsinghua.edu.cn/Adoptium` | 200（真实下载 205 MB / 22 秒成功） |
+//! | 中科大 USTC | **404**——`/adoptium/` 下只有 `deb/` `rpm/` `releases/`，没有这套目录树 |
+//! | 上交 SJTU / 北外 BFSU | **404**（同样没有该目录树） |
+//! | 华为云 | **假阳性**：门户对任意路径都回 `200` + 12 KB HTML（M34 实测，`/v1/repositories` 里没有 adoptium） |
+//!
+//! 因此 `mirrors.json` 里这四项全是 `enabled: false`：留着当「将来恢复」的登记，
+//! 但不让它们每次安装都白跑一趟（健康度虽然会冷却，首轮仍要付代价）。
+//! **判可用性别只看状态码**：真仓库目录页含 `<pre>`，门户兜底页没有——状态码 200 说明不了什么。
+//!
+//! # 4xx 不是「源坏」
+//!
+//! TUNA 每个 `{major}/{jdk|jre}/{arch}/{os}/` 目录只保留**最新一个补丁**（实测 21.0.12 → 404，
+//! 21.0.13 → 200 且大小与 Adoptium API 一致）。所以 `NotFound` 在引擎里走
+//! `HealthRegistry::record_missing`：不计失败、不进冷却，只留诊断痕迹。
+
+use serde::{Deserialize, Serialize};
+
+use super::mirrors::MirrorTable;
+use super::types::Candidate;
+
+const fn default_true() -> bool {
+    true
+}
+
+/// 一个 Adoptium 院校镜像。
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AdoptiumMirror {
+    /// 源标识（`tuna` / `ustc` / `sjtu` / `bfsu`）。
+    pub id: String,
+    /// 展示名。
+    pub name: String,
+    /// 镜像根（形如 `https://mirrors.tuna.tsinghua.edu.cn/Adoptium`）。
+    pub base: String,
+    /// 是否启用。
+    #[serde(default = "default_true")]
+    pub enabled: bool,
+    /// 该源只保留「最新补丁」（TUNA 实测：每个 `{major}/{jdk|jre}/{arch}/{os}/` 只有 1 个归档）。
+    ///
+    /// 标记本身不改 URL 形态，只给诊断与 `java vendors` 提示用：旧补丁在这里必然 404，
+    /// 引擎侧把 4xx 当「正常降级」而不是「源坏」（见 `download::health::record_missing`）。
+    #[serde(default)]
+    pub latest_only: bool,
+}
+
+impl MirrorTable {
+    /// Adoptium 类 URL 展开成院校镜像候选（按清单顺序；健康度排序由引擎负责）。
+    #[must_use]
+    pub fn adoptium_candidates(&self, url: &str) -> Vec<Candidate> {
+        let Some(artifact) = parse_adoptium_artifact(url) else {
+            return Vec::new();
+        };
+        self.adoptium
+            .iter()
+            .filter(|mirror| mirror.enabled)
+            .map(|mirror| {
+                let base = mirror.base.trim_end_matches('/');
+                Candidate::new(mirror.id.clone(), artifact.mirror_url(base))
+            })
+            .collect()
+    }
+}
+
+/// Adoptium 产物形态：JDK 还是 JRE（决定镜像的 `{major}/jdk|jre/` 路径段）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum JdkFlavor {
+    /// 完整开发包（`OpenJDK17U-jdk_...`）。
+    Jdk,
+    /// 运行时（`OpenJDK17U-jre_...`）。
+    Jre,
+}
+
+impl JdkFlavor {
+    /// 镜像路径里的段名。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Jdk => "jdk",
+            Self::Jre => "jre",
+        }
+    }
+
+    /// 从产物文件名判形态：`OpenJDK17U-jdk_` / `OpenJDK17U-jre_` / `*-jre-17…` 兜底。
+    #[must_use]
+    fn from_filename(filename: &str) -> Self {
+        if filename.contains("-jre") || filename.contains("_jre") {
+            Self::Jre
+        } else {
+            Self::Jdk
+        }
+    }
+}
+
+/// 解析出来的 Adoptium 产物。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AdoptiumArtifact {
+    /// 大版本号（`17` / `21`）。
+    pub major: String,
+    /// JDK 还是 JRE。
+    pub flavor: JdkFlavor,
+    /// CPU 架构（`x64` / `aarch64` / …）。
+    pub arch: String,
+    /// 目标系统（`windows` / `linux` / `mac` / …）。
+    pub os: String,
+    /// 产物文件名（含扩展名）。
+    pub filename: String,
+}
+
+impl AdoptiumArtifact {
+    /// 拼某个镜像根下的下载地址：`{base}/{major}/{jdk|jre}/{arch}/{os}/{filename}`。
+    #[must_use]
+    pub fn mirror_url(&self, base: &str) -> String {
+        format!(
+            "{}/{}/{}/{}/{}/{}",
+            base.trim_end_matches('/'),
+            self.major,
+            self.flavor.as_str(),
+            self.arch,
+            self.os,
+            self.filename
+        )
+    }
+}
+
+/// 解析 Adoptium 产物名。
+///
+/// 输入形如 `https://github.com/adoptium/temurin17-binaries/releases/download/JDK17.0.13%2B11/OpenJDK17U-jdk_x64_windows_hotspot_17.0.13_11.zip`。
+/// 解析失败返回 `None`（此时只保留官方源，不影响下载）。
+#[must_use]
+pub fn parse_adoptium_artifact(url: &str) -> Option<AdoptiumArtifact> {
+    let filename = url.rsplit('/').next()?;
+    if filename.is_empty()
+        || (!filename.contains("OpenJDK") && !filename.contains("jdk") && !filename.contains("jre"))
+    {
+        return None;
+    }
+    let mut major: Option<String> = None;
+    let mut arch: Option<&str> = None;
+    let mut os: Option<&str> = None;
+    for token in filename.split('_') {
+        if let Some(stripped) = token.strip_prefix("OpenJDK") {
+            let digits: String = stripped.chars().take_while(char::is_ascii_digit).collect();
+            if !digits.is_empty() {
+                major = Some(digits);
+            }
+        }
+        arch = arch.or(match token {
+            "x64" => Some("x64"),
+            "x86-32" | "x86" => Some("x86-32"),
+            "aarch64" => Some("aarch64"),
+            "arm" => Some("arm"),
+            "ppc64le" => Some("ppc64le"),
+            "s390x" => Some("s390x"),
+            _ => None,
+        });
+        os = os.or(match token {
+            "windows" => Some("windows"),
+            "linux" => Some("linux"),
+            "mac" => Some("mac"),
+            "alpine-linux" => Some("alpine-linux"),
+            "aix" => Some("aix"),
+            _ => None,
+        });
+    }
+    let major = match major {
+        Some(major) => major,
+        None => {
+            // 兜底形态：`jdk-17.0.13+11_...` 之类。
+            let rest = filename.split("jdk-").nth(1)?;
+            let digits: String = rest.chars().take_while(char::is_ascii_digit).collect();
+            if digits.is_empty() {
+                return None;
+            }
+            digits
+        }
+    };
+    Some(AdoptiumArtifact {
+        major,
+        flavor: JdkFlavor::from_filename(filename),
+        arch: arch?.to_string(),
+        os: os?.to_string(),
+        filename: filename.to_string(),
+    })
+}
diff --git a/crates/core/src/download/atomic.rs b/crates/core/src/download/atomic.rs
new file mode 100644
index 0000000..1a09327
--- /dev/null
+++ b/crates/core/src/download/atomic.rs
@@ -0,0 +1,384 @@
+//! 原子落盘：临时文件守卫 + `tmp → rename`。
+//!
+//! 设计文档 §4 的 HMCL 坑之一：没有「先校验后落盘」，崩溃/取消会留下「看起来存在但内容坏了」
+//! 的文件，之后所有「存在即跳过」的判断全部失效。这里的规矩：
+//!
+//! * 下载永远写进同级中间文件，校验通过才 `rename` 到目标路径；
+//! * `PartFile` 在 `Drop` 时自动清理（除非已 `commit`），取消/early-return 都不会留垃圾；
+//! * 小文件（索引、健康度）走 `write_atomic`，同样先写临时文件再 `rename`。
+//!
+//! # 中间文件的身份
+//!
+//! 中间文件名是 `<name>.ullpart-<session>-<seq>`：`session` 是进程号，`seq` 是进程内
+//! 自增序号（一个 `PartFile` 一个）。旧版命名只由目标路径决定（`<name>.ullpart`），
+//! 同一数据根同时跑两个启动器进程时两边共用一个中间文件：先提交的一方 `rename` 走，
+//! 另一方就拿到 `os error 2`（M35 真机：两个 `ull install` 并行装同一数据根，
+//! 各失败 819 / 1116 个资源）。
+//!
+//! 单进程语义（幂等 / 断点续传 / `current_bytes` 跳过判定）刻意保持不变：
+//!
+//! * [`PartFile::for_dest`] 先在目标目录里找这个目标的旧中间文件并**收养**（本进程的、
+//!   旧版无主的、以及外进程但静置超过 [`ADOPT_MIN_AGE`] 的），改名成本次路径；后续
+//!   续传判定完全照旧，跨进程/跨版本中断的下载仍然续得上。
+//! * 孤儿清理只碰两类：本会话留下又没人在用的副本，和无主（旧版命名）且超过
+//!   [`ORPHAN_MAX_AGE`] 的残留。本进程正在用的路径登记在活跃表里一律让开；外进程的
+//!   中间文件除了「静置超过 [`ORPHAN_MAX_AGE`] 且同一个目标」的，一概不删——没有进程
+//!   存活性探测就无法证明那边已经死了，宁可再生点垃圾也不重犯 `os error 2`。
+
+use std::collections::HashSet;
+use std::ffi::OsString;
+use std::fs::{self, File, OpenOptions};
+use std::io::{self, Write};
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::{Mutex, OnceLock};
+use std::time::{Duration, SystemTime};
+
+/// 下载中间文件后缀（中间文件家族的前缀：`<name>.ullpart` 或 `<name>.ullpart-<session>-<seq>`）。
+pub const PART_SUFFIX: &str = ".ullpart";
+/// 续传元数据后缀（挂在中间文件路径后面）。
+pub const META_SUFFIX: &str = ".ullmeta.json";
+/// 收养阈值：别的进程留下的中间文件静置这么久才敢接管。
+///
+/// 活着的下载每读到一个块就写一次（读超时默认 30s 就报错退出），所以「10 分钟没写」
+/// 基本等价于「那边已经死了」。
+pub const ADOPT_MIN_AGE: Duration = Duration::from_secs(10 * 60);
+/// 孤儿阈值：无主（旧版命名）中间文件超过这个岁数才清。
+pub const ORPHAN_MAX_AGE: Duration = Duration::from_secs(24 * 60 * 60);
+
+/// 同进程内中间文件/临时文件的去重序号。
+static SEQ: AtomicU64 = AtomicU64::new(0);
+
+fn sibling(dest: &Path, suffix: &str) -> PathBuf {
+    let mut name = dest.file_name().map_or_else(OsString::new, OsString::from);
+    name.push(suffix);
+    match dest.parent() {
+        Some(parent) => parent.join(name),
+        None => PathBuf::from(name),
+    }
+}
+
+/// 本进程序号（中间文件与 `write_atomic` 的临时文件共用）。
+fn next_seq() -> u64 {
+    SEQ.fetch_add(1, Ordering::Relaxed)
+}
+
+/// 本进程此刻仍在用的中间文件路径（清理与收养都必须让开）。
+fn live_parts() -> &'static Mutex<HashSet<PathBuf>> {
+    static LIVE: OnceLock<Mutex<HashSet<PathBuf>>> = OnceLock::new();
+    LIVE.get_or_init(|| Mutex::new(HashSet::new()))
+}
+
+fn mark_live(path: &Path, live: bool) {
+    let mut set = live_parts()
+        .lock()
+        .unwrap_or_else(std::sync::PoisonError::into_inner);
+    if live {
+        set.insert(path.to_path_buf());
+    } else {
+        set.remove(path);
+    }
+}
+
+fn is_live(path: &Path) -> bool {
+    live_parts()
+        .lock()
+        .unwrap_or_else(std::sync::PoisonError::into_inner)
+        .contains(path)
+}
+
+/// 中间文件属主（从文件名解析）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum Owner {
+    /// 旧版命名：没有进程标识（加标识之前留下的续传材料）。
+    Legacy,
+    /// 某个进程（会话）留下的中间文件。
+    Session(u32),
+}
+
+fn strip_meta(name: &str) -> &str {
+    name.strip_suffix(META_SUFFIX).unwrap_or(name)
+}
+
+/// 名字里指向的中间文件属主；不是我们认识的名字形状 → `None`（一概不碰）。
+fn owner_of(file_name: &str) -> Option<Owner> {
+    let base = strip_meta(file_name);
+    let index = base.rfind(PART_SUFFIX)?;
+    if index == 0 {
+        return None;
+    }
+    let tail = &base[index + PART_SUFFIX.len()..];
+    if tail.is_empty() {
+        return Some(Owner::Legacy);
+    }
+    let mut pieces = tail.strip_prefix('-')?.split('-');
+    let session = pieces.next()?.parse::<u32>().ok()?;
+    pieces.next()?.parse::<u64>().ok()?;
+    if pieces.next().is_some() {
+        return None;
+    }
+    Some(Owner::Session(session))
+}
+
+/// 本次会话的中间文件路径：`<name>.ullpart-<session>-<seq>`。
+fn part_path(dest: &Path, session: u32, seq: u64) -> PathBuf {
+    let mut name = dest.file_name().map_or_else(OsString::new, OsString::from);
+    name.push(format!("{PART_SUFFIX}-{session}-{seq}"));
+    match dest.parent() {
+        Some(parent) => parent.join(name),
+        None => PathBuf::from(name),
+    }
+}
+
+/// 文件距上次修改多久（取不到就当刚写过：清理与收养一律保守）。
+fn age_of(path: &Path) -> Duration {
+    fs::metadata(path)
+        .and_then(|meta| meta.modified())
+        .ok()
+        .and_then(|modified| SystemTime::now().duration_since(modified).ok())
+        .unwrap_or_default()
+}
+
+/// 删掉一个中间文件连同它挂的续传元数据。
+fn remove_family(part: &Path) {
+    let _ = fs::remove_file(part);
+    let _ = fs::remove_file(sibling(part, META_SUFFIX));
+}
+
+/// 目录扫描的三类结果。
+#[derive(Default)]
+struct Scan {
+    /// 可收养的旧中间文件（最年轻的那个）。
+    adopted: Option<PathBuf>,
+    /// 本目标的全部中间文件副本（含被收养者）。
+    leftovers: Vec<(PathBuf, Owner, Duration)>,
+    /// 无主且超龄的孤儿。
+    orphans: Vec<PathBuf>,
+}
+
+fn scan(dest: &Path, session: u32) -> Scan {
+    let mut scan = Scan::default();
+    let Some(dir) = dest
+        .parent()
+        .filter(|parent| !parent.as_os_str().is_empty())
+    else {
+        return scan;
+    };
+    let Some(dest_name) = dest.file_name() else {
+        return scan;
+    };
+    let family = format!("{}{PART_SUFFIX}", dest_name.to_string_lossy());
+    let Ok(entries) = fs::read_dir(dir) else {
+        return scan;
+    };
+    let mut newest: Option<Duration> = None;
+    for entry in entries.flatten() {
+        let name = entry.file_name().to_string_lossy().into_owned();
+        if name.ends_with(META_SUFFIX) {
+            continue; // 元数据跟着它挂的中间文件一起处理
+        }
+        let Some(owner) = owner_of(&name) else {
+            continue;
+        };
+        let file = entry.path();
+        if !file.is_file() {
+            continue;
+        }
+        let age = age_of(&file);
+        if !name.starts_with(&family) {
+            if owner == Owner::Legacy && age >= ORPHAN_MAX_AGE {
+                scan.orphans.push(file);
+            }
+            continue;
+        }
+        let adoptable = match owner {
+            // 本会话的旧副本：没人在用就能接管（保留「同一进程内重跑可续传」）。
+            Owner::Session(owner_session) if owner_session == session => !is_live(&file),
+            // 外进程的：静置够久才敢动手，否则可能正在被写。
+            Owner::Session(_) => age >= ADOPT_MIN_AGE,
+            Owner::Legacy => true,
+        };
+        if adoptable && newest.is_none_or(|best| age < best) {
+            newest = Some(age);
+            scan.adopted = Some(file.clone());
+        }
+        scan.leftovers.push((file, owner, age));
+    }
+    scan
+}
+
+/// 为本次下载准备中间文件：收养可续传的旧文件，清掉本会话多余副本与无主孤儿。
+///
+/// 全程尽力而为：清理失败绝不影响下载本身。
+fn prepare(dest: &Path, path: &Path, session: u32) {
+    let scan = scan(dest, session);
+
+    if let Some(found) = scan.adopted {
+        // 同一目录内改名，跨进程也是原子的：谁先动手谁拿到这份续传材料。
+        if found != *path && fs::rename(&found, path).is_ok() {
+            let meta = sibling(&found, META_SUFFIX);
+            if meta.is_file() {
+                let _ = fs::rename(&meta, sibling(path, META_SUFFIX));
+            }
+        }
+    }
+
+    for (leftover, owner, age) in scan.leftovers {
+        if leftover == *path || is_live(&leftover) {
+            continue;
+        }
+        // 本会话落败的副本留着没意义；外进程的只有超龄才敢清。
+        if owner == Owner::Session(session) || age >= ORPHAN_MAX_AGE {
+            remove_family(&leftover);
+        }
+    }
+
+    for orphan in scan.orphans {
+        remove_family(&orphan);
+    }
+}
+
+/// 下载中间文件的守卫。
+#[derive(Debug)]
+pub struct PartFile {
+    path: PathBuf,
+    committed: bool,
+    preserved: bool,
+}
+
+impl PartFile {
+    /// 为目标路径派生中间文件（名字带进程标识，并顺手收养旧的续传材料）。
+    #[must_use]
+    pub fn for_dest(dest: &Path) -> Self {
+        let session = std::process::id();
+        let path = part_path(dest, session, next_seq());
+        mark_live(&path, true);
+        prepare(dest, &path, session);
+        Self {
+            path,
+            committed: false,
+            preserved: false,
+        }
+    }
+
+    /// 中间文件路径。
+    #[must_use]
+    pub fn path(&self) -> &Path {
+        &self.path
+    }
+
+    /// 续传元数据路径。
+    #[must_use]
+    pub fn meta_path(&self) -> PathBuf {
+        sibling(&self.path, META_SUFFIX)
+    }
+
+    /// 中间文件是否存在。
+    #[must_use]
+    pub fn exists(&self) -> bool {
+        self.path.is_file()
+    }
+
+    /// 已写入的字节数（不存在时为 0）。
+    #[must_use]
+    pub fn len(&self) -> u64 {
+        fs::metadata(&self.path).map_or(0, |meta| meta.len())
+    }
+
+    /// 是否为空（续传判定要区分「文件不存在」和「文件存在但 0 字节」）。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.len() == 0
+    }
+
+    /// 以追加方式打开（续传）。
+    pub fn open_append(&self) -> io::Result<File> {
+        ensure_parent(&self.path)?;
+        OpenOptions::new()
+            .create(true)
+            .append(true)
+            .open(&self.path)
+    }
+
+    /// 以截断方式打开（从头下载）。
+    pub fn open_truncate(&self) -> io::Result<File> {
+        ensure_parent(&self.path)?;
+        OpenOptions::new()
+            .create(true)
+            .write(true)
+            .truncate(true)
+            .open(&self.path)
+    }
+
+    /// 校验通过后提交：把中间文件 `rename` 到目标路径（同一目录，跨文件系统不会发生）。
+    pub fn commit(mut self, dest: &Path) -> io::Result<()> {
+        ensure_parent(dest)?;
+        fs::rename(&self.path, dest)?;
+        self.committed = true;
+        // rename 后中间文件已不存在，元数据是纯冗余，顺手清掉。
+        let _ = fs::remove_file(self.meta_path());
+        Ok(())
+    }
+
+    /// 主动丢弃中间文件（换源/校验失败）。
+    pub fn discard(&mut self) {
+        remove_family(&self.path);
+    }
+
+    /// 确保中间文件的父目录存在（异步版）。
+    ///
+    /// 单连接路径由 [`Self::open_append`] / [`Self::open_truncate`] 顺手建目录，
+    /// 但**分块路径**是先 `tokio::fs::OpenOptions` 预分配整文件、再并发写段——
+    /// 它不走那两个入口，所以得显式补这一步，否则「下到还不存在的目录」会全部源失败
+    /// （现场故障：`data/java-managed/.cache/` 尚未创建时 6 个候选源瞬间全挂）。
+    pub(crate) async fn ensure_parent_async(&self) -> io::Result<()> {
+        let Some(parent) = self.path.parent() else {
+            return Ok(());
+        };
+        if parent.as_os_str().is_empty() {
+            return Ok(());
+        }
+        tokio::fs::create_dir_all(parent).await
+    }
+
+    /// 保留中间文件（跨会话续传用）：`Drop` 时不再清理。
+    pub fn preserve(&mut self) {
+        self.preserved = true;
+    }
+}
+
+impl Drop for PartFile {
+    fn drop(&mut self) {
+        if !self.committed && !self.preserved {
+            remove_family(&self.path);
+        }
+        mark_live(&self.path, false);
+    }
+}
+
+/// 原子写小文件：`<path>.tmp-<session>-<seq>` → `rename(path)`。
+///
+/// 临时名同样带进程标识：两个进程同时写同一份小文件（健康度、续传元数据）时
+/// 不会互相把对方的临时文件 `rename` 走。
+pub fn write_atomic(path: &Path, bytes: &[u8]) -> io::Result<()> {
+    ensure_parent(path)?;
+    let tmp = sibling(path, &format!(".tmp-{}-{}", std::process::id(), next_seq()));
+    {
+        let mut file = File::create(&tmp)?;
+        file.write_all(bytes)?;
+        file.flush()?;
+        file.sync_all()?;
+    }
+    fs::rename(&tmp, path).inspect_err(|_| {
+        let _ = fs::remove_file(&tmp);
+    })
+}
+
+fn ensure_parent(path: &Path) -> io::Result<()> {
+    if let Some(parent) = path.parent() {
+        if !parent.as_os_str().is_empty() {
+            fs::create_dir_all(parent)?;
+        }
+    }
+    Ok(())
+}
diff --git a/crates/core/src/download/backoff.rs b/crates/core/src/download/backoff.rs
new file mode 100644
index 0000000..980f42c
--- /dev/null
+++ b/crates/core/src/download/backoff.rs
@@ -0,0 +1,120 @@
+//! 指数退避 + 抖动。
+//!
+//! 修 HMCL 的坑（analyse/03 §7.6 第 5 点）：它的重试循环里没有 sleep，5xx 会变成
+//! 「6 次瞬时连打」，把弱网镜像直接压垮。这里给出 1s / 2s / 4s… 上限 30s，
+//! ±30% 抖动打散多实例/多文件的同步重试风暴。
+//!
+//! 抖动源是自带的 xorshift64*，不引 `rand`（体积 + Win7 依赖面）。
+
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
+
+use serde::{Deserialize, Serialize};
+
+/// 退避策略（可序列化进设置）。
+#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
+pub struct BackoffPolicy {
+    /// 首次退避（毫秒）。
+    pub base_ms: u64,
+    /// 单次退避上限（毫秒）。
+    pub max_ms: u64,
+    /// 抖动比例（0.0~1.0，0.3 = ±30%）。
+    pub jitter_ratio: f64,
+    /// 每个源的尝试次数上限。
+    pub max_attempts: u32,
+}
+
+impl BackoffPolicy {
+    /// 不重试（一次失败立刻换源）。
+    #[must_use]
+    pub const fn none() -> Self {
+        Self {
+            base_ms: 0,
+            max_ms: 0,
+            jitter_ratio: 0.0,
+            max_attempts: 1,
+        }
+    }
+
+    /// 第 `attempt` 次重试前的**无抖动**等待时间（`attempt` 从 0 起）。
+    #[must_use]
+    pub fn delay(&self, attempt: u32) -> Duration {
+        let factor = 1u64.checked_shl(attempt.min(32)).unwrap_or(u64::MAX).max(1);
+        Duration::from_millis(self.base_ms.saturating_mul(factor).min(self.max_ms))
+    }
+
+    /// 第 `attempt` 次重试前的等待时间，`rng` 为 `[0,1)` 的抖动量（可复现，便于单测）。
+    ///
+    /// 结果永不超过 `max_ms`，且永不低于 `base_ms`（当 `base_ms <= max_ms` 时）。
+    #[must_use]
+    pub fn delay_jittered(&self, attempt: u32, rng: f64) -> Duration {
+        let base_ms = self.delay(attempt).as_millis() as f64;
+        let ratio = self.jitter_ratio.clamp(0.0, 1.0);
+        let factor = 1.0 + ratio * (2.0 * rng.clamp(0.0, 1.0) - 1.0);
+        let ceiling = (self.max_ms as f64).max(base_ms);
+        let jittered_ms = (base_ms * factor).clamp(0.0, ceiling);
+        Duration::from_millis(jittered_ms as u64)
+    }
+
+    /// 用抖动源取一次等待时间。
+    #[must_use]
+    pub fn next_delay(&self, attempt: u32, jitter: &mut Jitter) -> Duration {
+        self.delay_jittered(attempt, jitter.next_fraction())
+    }
+}
+
+impl Default for BackoffPolicy {
+    fn default() -> Self {
+        Self {
+            base_ms: 1_000,
+            max_ms: 30_000,
+            jitter_ratio: 0.3,
+            max_attempts: 3,
+        }
+    }
+}
+
+/// xorshift64* 抖动源：确定性、无外部依赖。
+#[derive(Debug, Clone)]
+pub struct Jitter {
+    state: u64,
+}
+
+impl Jitter {
+    /// 固定种子构造（同种子的序列可复现 → 单测友好）。
+    #[must_use]
+    pub const fn new(seed: u64) -> Self {
+        Self {
+            state: if seed == 0 {
+                0x9E37_79B9_7F4A_7C15
+            } else {
+                seed
+            },
+        }
+    }
+
+    /// 下一个 64 位随机数。
+    pub fn next_u64(&mut self) -> u64 {
+        let mut x = self.state;
+        x ^= x << 13;
+        x ^= x >> 7;
+        x ^= x << 17;
+        self.state = x;
+        x.wrapping_mul(0x2545_F491_4F6C_DD1D)
+    }
+
+    /// 下一个 `[0,1)` 的浮点。
+    pub fn next_fraction(&mut self) -> f64 {
+        // 取高 53 位映射到 [0,1)，与 f64 的尾数精度一致。
+        (self.next_u64() >> 11) as f64 / (1u64 << 53) as f64
+    }
+}
+
+impl Default for Jitter {
+    fn default() -> Self {
+        let seed = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .map(|d| d.as_nanos() as u64)
+            .unwrap_or(0x1234_5678_9ABC_DEF0);
+        Self::new(seed)
+    }
+}
diff --git a/crates/core/src/download/blocking.rs b/crates/core/src/download/blocking.rs
new file mode 100644
index 0000000..1a3c4f2
--- /dev/null
+++ b/crates/core/src/download/blocking.rs
@@ -0,0 +1,55 @@
+//! 同步桥：让**非 async 宿主**驱动异步下载引擎。
+//!
+//! `core::download` 的引擎是异步的（tokio + reqwest），GUI 侧自带运行时；
+//! 但 headless 消费者（`crates/cli` 的 `ull`）不依赖 tokio，也不该为一次安装
+//! 把整个异步运行时依赖树拉进 CLI 的 manifest（D18：CLI 依赖树保持干净）。
+//!
+//! 因此把「建一个短命运行时 + 跑完整段 future」这两件事收在 core 里：
+//!
+//! ```ignore
+//! let outcome = unlucky_core::download::blocking::block_on(async { /* 规划 + 下载 */ });
+//! ```
+//!
+//! 约定：**整段**安装流程包在一次 `block_on` 里（同一个运行时），不要每次下载都建一个——
+//! reqwest 的连接池绑定在创建它的运行时上，跨运行时会退化甚至报「dispatch task is gone」。
+//!
+//! 这是给「单线程 CLI」用的逃生口，不是通用设施：app 层请直接用原生异步。
+
+use std::future::Future;
+
+/// 在一个临时 tokio 多线程运行时上跑完 `future`。
+///
+/// 运行时随调用结束销毁，因此适合「一条命令一次阻塞」的 CLI 生命周期。
+///
+/// # Panics
+///
+/// 运行时建不起来（系统资源耗尽）时 panic：此时进程已无法继续，早点暴露比静默降级好。
+/// 在已有 tokio 运行时上下文里调用同样会 panic（tokio 不允许嵌套 `block_on`）。
+pub fn block_on<F: Future>(future: F) -> F::Output {
+    let runtime = tokio::runtime::Builder::new_multi_thread()
+        .worker_threads(2)
+        .thread_name("ull-blocking")
+        .enable_all()
+        .build()
+        .expect("创建 tokio 运行时失败（内存/线程资源不足）");
+    runtime.block_on(future)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::block_on;
+
+    #[test]
+    fn drives_a_plain_future_to_completion() {
+        assert_eq!(block_on(async { 1 + 1 }), 2);
+    }
+
+    #[test]
+    fn drives_tokio_timers() {
+        let start = std::time::Instant::now();
+        block_on(async {
+            tokio::time::sleep(std::time::Duration::from_millis(5)).await;
+        });
+        assert!(start.elapsed() >= std::time::Duration::from_millis(5));
+    }
+}
diff --git a/crates/core/src/download/bytes.rs b/crates/core/src/download/bytes.rs
new file mode 100644
index 0000000..f191f51
--- /dev/null
+++ b/crates/core/src/download/bytes.rs
@@ -0,0 +1,138 @@
+//! 内存下载：版本清单 / 版本 JSON / 资源索引这类「小文本」资源。
+//!
+//! 与文件下载共用候选源、退避与健康度逻辑，但不续传、不分块——它们要么很小，
+//! 要么强时效（`ETag` 语义比续传更合适）。
+
+use std::time::Instant;
+
+use super::cache::now_ms;
+use super::engine::{millis, DownloadEngine};
+use super::error::{DownloadError, DownloadErrorKind};
+use super::http;
+use super::progress::ProgressEvent;
+use super::types::{Candidate, DownloadId, DownloadRequest};
+use super::verify;
+
+/// 内存下载的上限（manifest 类资源不该有几十 MB；防御恶意镜像把人撑爆）。
+pub const MAX_IN_MEMORY_BYTES: u64 = 64 * 1024 * 1024;
+
+impl DownloadEngine {
+    /// 内存下载（版本清单 / 版本 JSON / 索引等小文本资源）。
+    pub async fn download_bytes(&self, req: DownloadRequest) -> Result<Vec<u8>, DownloadError> {
+        let started = Instant::now();
+        let id = DownloadId::next();
+        req.validate()?;
+        let plan = self.plan(&req, now_ms());
+        self.announce(&id, &req, plan.len());
+        if plan.is_empty() {
+            return Err(DownloadError::new(
+                DownloadErrorKind::InvalidRequest,
+                format!("没有可用候选源：{}", req.url),
+            ));
+        }
+
+        let _permit = self.acquire().await?;
+        let mut suppressed: Vec<String> = Vec::new();
+
+        for candidate in &plan {
+            // 与文件下载同一套规则：冷却中/刚出冷却的源只给一次探测机会。
+            let max_attempts = self.attempts_for(&candidate.source, req.kind, now_ms());
+            for attempt in 0..max_attempts {
+                match self.fetch_bytes(&req, candidate).await {
+                    Ok(bytes) => {
+                        self.health.record_success(
+                            &candidate.source,
+                            req.kind,
+                            started.elapsed(),
+                            now_ms(),
+                        );
+                        self.emit(ProgressEvent::Completed {
+                            id,
+                            bytes: bytes.len() as u64,
+                            from_cache: false,
+                            source: candidate.source.clone(),
+                            elapsed_ms: millis(started.elapsed()),
+                        });
+                        self.flush_health();
+                        return Ok(bytes);
+                    }
+                    Err(err) => {
+                        self.health.record_failure(
+                            &candidate.source,
+                            req.kind,
+                            &err.message,
+                            now_ms(),
+                        );
+                        let retry = err.kind.is_retryable() && attempt + 1 < max_attempts;
+                        let delay = self.next_delay(attempt);
+                        self.emit(ProgressEvent::SourceFailed {
+                            id,
+                            source: candidate.source.clone(),
+                            reason: err.message.clone(),
+                            attempt,
+                            will_retry: retry,
+                            retry_in_ms: if retry { millis(delay) } else { 0 },
+                        });
+                        if !retry {
+                            suppressed.push(format!("{}: {}", candidate.source, err.message));
+                            break;
+                        }
+                        tokio::time::sleep(delay).await;
+                    }
+                }
+            }
+        }
+
+        self.flush_health();
+        Err(DownloadError::new(
+            DownloadErrorKind::AllSourcesFailed,
+            format!("所有候选源都取不到文本资源：{}", req.url),
+        )
+        .with_suppressed(suppressed))
+    }
+
+    async fn fetch_bytes(
+        &self,
+        req: &DownloadRequest,
+        candidate: &Candidate,
+    ) -> Result<Vec<u8>, DownloadError> {
+        let response = self
+            .http
+            .get(&candidate.url)
+            .send()
+            .await
+            .map_err(|err| http::classify_reqwest(&err, &candidate.url))?;
+        let status = response.status();
+        if !status.is_success() {
+            return Err(http::classify_status(status.as_u16(), &candidate.url)
+                .with_source(candidate.source.as_str()));
+        }
+        if let Some(len) = http::content_length(response.headers()) {
+            if len > MAX_IN_MEMORY_BYTES {
+                return Err(DownloadError::new(
+                    DownloadErrorKind::InvalidRequest,
+                    format!(
+                        "文本资源过大（{len} 字节），拒绝载入内存：{}",
+                        candidate.url
+                    ),
+                )
+                .with_source(candidate.source.as_str()));
+            }
+        }
+        let body = response
+            .bytes()
+            .await
+            .map_err(|err| http::classify_reqwest(&err, &candidate.url))?;
+        if let Some(integrity) = &req.integrity {
+            let actual = verify::digest_bytes(integrity.algo, &body);
+            if !verify::matches(&integrity.hex, &actual) {
+                return Err(DownloadError::new(
+                    DownloadErrorKind::Integrity,
+                    format!("校验不符：期望 {} 实得 {actual}", integrity.hex),
+                )
+                .with_source(candidate.source.as_str()));
+            }
+        }
+        Ok(body.to_vec())
+    }
+}
diff --git a/crates/core/src/download/cache.rs b/crates/core/src/download/cache.rs
new file mode 100644
index 0000000..7676e83
--- /dev/null
+++ b/crates/core/src/download/cache.rs
@@ -0,0 +1,285 @@
+//! 内容寻址缓存：两级分片 + 「记录信任」命中快路径。
+//!
+//! 布局承设计文档 `04 §2` 与 analyse/03 §5.7：`<cache>/sha1/<hash[0..2]>/<hash>`（两级分片，
+//! 避开 NTFS 单目录几十万条目塌陷）。
+//!
+//! 修 HMCL 的坑（analyse/03 §8.2 第 7 点）：它每次命中都重算整个文件的 SHA-1，
+//! 3000 个资源对象意味着启动期几百 MB 的无谓读盘。这里写入时记录 `{hash, size, mtime}`，
+//! **此后信任记录**：size/mtime 都没变就直接命中；只有元数据变了才重算一次摘要并刷新记录。
+
+use std::collections::BTreeMap;
+use std::io;
+use std::path::{Path, PathBuf};
+use std::sync::Mutex;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use serde::{Deserialize, Serialize};
+
+use super::atomic::write_atomic;
+use super::types::{HashAlgo, Integrity};
+use super::verify;
+
+/// 索引文件名（放在缓存根下）。
+pub const INDEX_FILE: &str = "index.json";
+/// 索引格式版本。
+pub const INDEX_VERSION: u32 = 1;
+
+/// 一条缓存记录。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct CacheRecord {
+    /// 算法。
+    pub algo: HashAlgo,
+    /// 摘要（小写十六进制）。
+    pub hash: String,
+    /// 字节数。
+    pub size: u64,
+    /// 文件修改时间（unix 毫秒）——记录信任的锚点。
+    pub mtime_ms: u64,
+    /// 写入缓存时间。
+    pub cached_at_ms: u64,
+    /// 最近一次真正校验的时间（0 = 从未校验，走记录信任）。
+    pub last_verified_ms: u64,
+}
+
+/// 缓存统计（诊断页）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub struct CacheStats {
+    /// 条目数。
+    pub entries: usize,
+    /// 总字节数。
+    pub total_bytes: u64,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+struct CacheIndex {
+    version: u32,
+    #[serde(default)]
+    entries: BTreeMap<String, CacheRecord>,
+}
+
+impl Default for CacheIndex {
+    fn default() -> Self {
+        Self {
+            version: INDEX_VERSION,
+            entries: BTreeMap::new(),
+        }
+    }
+}
+
+/// 内容寻址缓存。
+#[derive(Debug)]
+pub struct ContentCache {
+    root: PathBuf,
+    index: Mutex<CacheIndex>,
+}
+
+impl ContentCache {
+    /// 打开（或初始化）缓存根目录；索引损坏时从空表重建（缓存随时可丢，不阻断启动）。
+    #[must_use]
+    pub fn open(root: impl Into<PathBuf>) -> Self {
+        let root = root.into();
+        let index_path = root.join(INDEX_FILE);
+        let index = std::fs::read(&index_path)
+            .ok()
+            .and_then(|bytes| serde_json::from_slice::<CacheIndex>(&bytes).ok())
+            .unwrap_or_default();
+        Self {
+            root,
+            index: Mutex::new(index),
+        }
+    }
+
+    /// 缓存根目录。
+    #[must_use]
+    pub fn root(&self) -> &Path {
+        &self.root
+    }
+
+    /// 某个摘要对应的缓存路径（两级分片）。
+    #[must_use]
+    pub fn path_for(&self, algo: HashAlgo, hash: &str) -> PathBuf {
+        let shard = hash.get(..2).unwrap_or(hash);
+        self.root.join(algo.as_str()).join(shard).join(hash)
+    }
+
+    fn lock(&self) -> std::sync::MutexGuard<'_, CacheIndex> {
+        self.index
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner())
+    }
+
+    fn key(algo: HashAlgo, hash: &str) -> String {
+        format!("{}:{hash}", algo.as_str())
+    }
+
+    /// 命中查询（记录信任：size + mtime 未变则**不重算**摘要）。
+    #[must_use]
+    pub fn lookup(&self, integrity: &Integrity, now_ms: u64) -> Option<PathBuf> {
+        let path = self.path_for(integrity.algo, &integrity.hex);
+        let record = self
+            .lock()
+            .entries
+            .get(&Self::key(integrity.algo, &integrity.hex))
+            .cloned()?;
+        let Ok(meta) = std::fs::metadata(&path) else {
+            // 文件被删：记录作废，避免每次命中都白查一次磁盘。
+            self.forget(integrity);
+            return None;
+        };
+        if !meta.is_file() || meta.len() != record.size {
+            // 文件被删/被截断：记录作废。
+            self.forget(integrity);
+            return None;
+        }
+        let mtime_ms = mtime_ms(&meta);
+        if mtime_ms == record.mtime_ms {
+            return Some(path);
+        }
+        // 元数据变了（外部动过文件）：重算一次摘要再决定。
+        let Ok(actual) = verify::digest_file(&path, integrity.algo) else {
+            self.forget(integrity);
+            return None;
+        };
+        if !verify::matches(&integrity.hex, &actual) {
+            self.forget(integrity);
+            return None;
+        }
+        self.refresh_record(integrity, &meta, now_ms);
+        Some(path)
+    }
+
+    /// 强制校验的命中查询（抽样/定期后台校验用，慢但可信）。
+    #[must_use]
+    pub fn lookup_verified(&self, integrity: &Integrity, now_ms: u64) -> Option<PathBuf> {
+        let path = self.path_for(integrity.algo, &integrity.hex);
+        let meta = std::fs::metadata(&path).ok()?;
+        if !meta.is_file() {
+            self.forget(integrity);
+            return None;
+        }
+        let actual = verify::digest_file(&path, integrity.algo).ok()?;
+        if !verify::matches(&integrity.hex, &actual) {
+            self.forget(integrity);
+            return None;
+        }
+        self.refresh_record(integrity, &meta, now_ms);
+        Some(path)
+    }
+
+    /// 把已校验通过的文件放进缓存（硬链接优先，跨卷退化为复制）。
+    pub fn insert(&self, source: &Path, integrity: &Integrity, now_ms: u64) -> io::Result<PathBuf> {
+        let target = self.path_for(integrity.algo, &integrity.hex);
+        if let Some(parent) = target.parent() {
+            std::fs::create_dir_all(parent)?;
+        }
+        if !target.is_file() {
+            link_or_copy(source, &target)?;
+        }
+        self.register(&target, integrity, now_ms)?;
+        Ok(target)
+    }
+
+    /// 登记一个已在缓存位的文件（`assets` 已在游戏目录里的补登记场景）。
+    pub fn register(&self, path: &Path, integrity: &Integrity, now_ms: u64) -> io::Result<()> {
+        let meta = std::fs::metadata(path)?;
+        let record = CacheRecord {
+            algo: integrity.algo,
+            hash: integrity.hex.clone(),
+            size: meta.len(),
+            mtime_ms: mtime_ms(&meta),
+            cached_at_ms: now_ms,
+            last_verified_ms: now_ms,
+        };
+        self.lock()
+            .entries
+            .insert(Self::key(integrity.algo, &integrity.hex), record);
+        Ok(())
+    }
+
+    /// 删除一条缓存（含文件）。
+    pub fn remove(&self, integrity: &Integrity) -> io::Result<()> {
+        let path = self.path_for(integrity.algo, &integrity.hex);
+        self.forget(integrity);
+        match std::fs::remove_file(&path) {
+            Ok(()) => Ok(()),
+            Err(err) if err.kind() == io::ErrorKind::NotFound => Ok(()),
+            Err(err) => Err(err),
+        }
+    }
+
+    fn forget(&self, integrity: &Integrity) {
+        self.lock()
+            .entries
+            .remove(&Self::key(integrity.algo, &integrity.hex));
+    }
+
+    fn refresh_record(&self, integrity: &Integrity, meta: &std::fs::Metadata, now_ms: u64) {
+        if let Some(record) = self
+            .lock()
+            .entries
+            .get_mut(&Self::key(integrity.algo, &integrity.hex))
+        {
+            record.size = meta.len();
+            record.mtime_ms = mtime_ms(meta);
+            record.last_verified_ms = now_ms;
+        }
+    }
+
+    /// 统计。
+    #[must_use]
+    pub fn stats(&self) -> CacheStats {
+        let index = self.lock();
+        CacheStats {
+            entries: index.entries.len(),
+            total_bytes: index.entries.values().map(|record| record.size).sum(),
+        }
+    }
+
+    /// 索引条目数（`stats` 的便捷版本）。
+    #[must_use]
+    pub fn len(&self) -> usize {
+        self.lock().entries.len()
+    }
+
+    /// 索引是否为空。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.len() == 0
+    }
+
+    /// 原子持久化索引（`cache/index.json`）。
+    pub fn persist(&self) -> io::Result<()> {
+        let json = {
+            let index = self.lock();
+            serde_json::to_vec_pretty(&*index).map_err(io::Error::other)?
+        };
+        write_atomic(&self.root.join(INDEX_FILE), &json)
+    }
+}
+
+/// 硬链接优先，失败退化为复制（跨卷/权限不足时）。
+fn link_or_copy(source: &Path, target: &Path) -> io::Result<()> {
+    match std::fs::hard_link(source, target) {
+        Ok(()) => Ok(()),
+        Err(_) => std::fs::copy(source, target).map(|_| ()),
+    }
+}
+
+fn mtime_ms(meta: &std::fs::Metadata) -> u64 {
+    meta.modified()
+        .ok()
+        .and_then(|time| time.duration_since(UNIX_EPOCH).ok())
+        .map_or(0, |since| {
+            u64::try_from(since.as_millis()).unwrap_or(u64::MAX)
+        })
+}
+
+/// 当前 unix 毫秒（引擎统一取一次再往下传，避免测试里到处读时钟）。
+#[must_use]
+pub fn now_ms() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map_or(0, |since| {
+            u64::try_from(since.as_millis()).unwrap_or(u64::MAX)
+        })
+}
diff --git a/crates/core/src/download/chunked.rs b/crates/core/src/download/chunked.rs
new file mode 100644
index 0000000..61853e3
--- /dev/null
+++ b/crates/core/src/download/chunked.rs
@@ -0,0 +1,296 @@
+//! 大文件多连接分块下载：分块规划、`Content-Range` 解析、Range 能力判定与单块抓取。
+//!
+//! HMCL 只做「单文件单连接 + 全局并发闸门」（analyse/03 §5.5），大 jar 会抢占许可并形成
+//! 头阻塞。这里对「大文件 + 支持 Range」的资源开 N 条连接并行取段（默认 N=4），
+//! 每条连接写进同一个**预分配**中间文件的不同偏移；服务器不支持 Range（返回 200 而不是 206）
+//! 时由引擎自动退化为单连接。
+
+use std::path::Path;
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::Duration;
+
+use super::error::{DownloadError, DownloadErrorKind};
+use super::http;
+use super::types::ResourceKind;
+
+/// 默认分块连接数（设计文档 Q19 定案 N=4）。
+pub const DEFAULT_CONNECTIONS: usize = 4;
+/// 分块连接数上限（再多收益递减且容易被镜像限流）。
+pub const MAX_CONNECTIONS: usize = 16;
+/// 默认开启分块的最小文件大小（8 MiB）。
+pub const DEFAULT_MIN_SIZE: u64 = 8 * 1024 * 1024;
+
+/// 分块下载配置。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ChunkedConfig {
+    /// 总开关（设置项）。
+    pub enabled: bool,
+    /// 并行连接数。
+    pub connections: usize,
+    /// 小于该大小不做分块。
+    pub min_size: u64,
+}
+
+impl Default for ChunkedConfig {
+    fn default() -> Self {
+        Self {
+            enabled: true,
+            connections: DEFAULT_CONNECTIONS,
+            min_size: DEFAULT_MIN_SIZE,
+        }
+    }
+}
+
+impl ChunkedConfig {
+    /// 关闭分块。
+    #[must_use]
+    pub const fn disabled() -> Self {
+        Self {
+            enabled: false,
+            connections: 1,
+            min_size: DEFAULT_MIN_SIZE,
+        }
+    }
+
+    /// 该资源当前是否走分块。
+    #[must_use]
+    pub fn applies_to(&self, kind: ResourceKind, size: Option<u64>) -> bool {
+        self.enabled
+            && self.connections > 1
+            && kind.prefers_chunked()
+            && size.is_some_and(|size| size >= self.min_size)
+    }
+
+    /// 实际生效的连接数（夹在 `1..=MAX_CONNECTIONS`）。
+    #[must_use]
+    pub fn effective_connections(&self) -> usize {
+        self.connections.clamp(1, MAX_CONNECTIONS)
+    }
+}
+
+/// 闭区间字节段（HTTP Range 的语义是闭区间，这里保持一致免得 +1/-1 到处飞）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ByteRange {
+    /// 起始偏移（含）。
+    pub start: u64,
+    /// 结束偏移（**含**）。
+    pub end: u64,
+}
+
+impl ByteRange {
+    /// 构造。
+    #[must_use]
+    pub const fn new(start: u64, end: u64) -> Self {
+        Self { start, end }
+    }
+
+    /// 段长度（字节）。
+    #[must_use]
+    pub const fn len(&self) -> u64 {
+        if self.end < self.start {
+            0
+        } else {
+            self.end - self.start + 1
+        }
+    }
+
+    /// 空段。
+    #[must_use]
+    pub const fn is_empty(&self) -> bool {
+        self.end < self.start
+    }
+
+    /// `Range` 头的值。
+    #[must_use]
+    pub fn header_value(&self) -> String {
+        format!("bytes={}-{}", self.start, self.end)
+    }
+}
+
+/// 把 `total` 均分成不超过 `connections` 段（纯函数，单测重点）。
+///
+/// 保证：段序列连续、无重叠、并集恰为 `[0, total)`；段数 = `min(connections, total)`。
+#[must_use]
+pub fn plan(total: u64, connections: usize) -> Vec<ByteRange> {
+    if total == 0 {
+        return Vec::new();
+    }
+    let parts = connections.clamp(1, MAX_CONNECTIONS) as u64;
+    let count = parts.min(total);
+    let base = total / count;
+    let remainder = total % count;
+
+    let mut ranges = Vec::with_capacity(count as usize);
+    let mut offset = 0_u64;
+    for index in 0..count {
+        // 余数摊到前几段，避免最后一段特别大。
+        let extra = u64::from(index < remainder);
+        let len = base + extra;
+        if len == 0 {
+            continue;
+        }
+        ranges.push(ByteRange::new(offset, offset + len - 1));
+        offset += len;
+    }
+    ranges
+}
+
+/// `Content-Range: bytes 0-99/1000` 的解析结果。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ContentRange {
+    /// 起始。
+    pub start: u64,
+    /// 结束（含）。
+    pub end: u64,
+    /// 总长度（`*` 时为 `None`）。
+    pub total: Option<u64>,
+}
+
+/// 解析 `Content-Range`（畸形一律 `None`，调用方退化处理）。
+#[must_use]
+pub fn parse_content_range(value: &str) -> Option<ContentRange> {
+    let rest = value.trim().strip_prefix("bytes")?.trim_start();
+    let (range, total) = rest.split_once('/')?;
+    let (start, end) = range.split_once('-')?;
+    let start: u64 = start.trim().parse().ok()?;
+    let end: u64 = end.trim().parse().ok()?;
+    if end < start {
+        return None;
+    }
+    let total = match total.trim() {
+        "*" => None,
+        other => Some(other.parse().ok()?),
+    };
+    Some(ContentRange { start, end, total })
+}
+
+/// 服务器对 Range 的支持度。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RangeSupport {
+    /// 支持（`Accept-Ranges: bytes` 或正常返回 206）。
+    Supported,
+    /// 明确不支持。
+    Unsupported,
+    /// 未知（既没头也没探测）。
+    Unknown,
+}
+
+/// 判定 Range 支持度。
+#[must_use]
+pub fn range_support(accept_ranges: Option<&str>, status: u16) -> RangeSupport {
+    if status == 206 {
+        return RangeSupport::Supported;
+    }
+    match accept_ranges {
+        Some(value) if value.to_ascii_lowercase().contains("bytes") => RangeSupport::Supported,
+        Some(value) if value.to_ascii_lowercase().contains("none") => RangeSupport::Unsupported,
+        Some(_) => RangeSupport::Unsupported,
+        None => RangeSupport::Unknown,
+    }
+}
+
+/// 206 响应的 `Content-Range` 是否与请求段一致。
+///
+/// * 缺头 → 宽松放过（个别服务器省略该头，后面的长度校验仍能兜底）；
+/// * 有头 → 起止必须严格等于请求段，畸形头一律判不符。
+///
+/// 这条防御与单连接路径（`transfer.rs` 里比对 `content_range.start != offset`）对齐：
+/// 只在「长度恰好」时坏文件才会溜过长度校验，起止比对把这条路堵死。
+#[must_use]
+pub fn content_range_matches(requested: ByteRange, value: Option<&str>) -> bool {
+    let Some(value) = value else {
+        return true;
+    };
+    parse_content_range(value)
+        .is_some_and(|parsed| parsed.start == requested.start && parsed.end == requested.end)
+}
+
+/// 抓一个段，写到预分配文件的 `range.start` 偏移处，并把字节数累加进 `progress`。
+///
+/// 服务器若对带 `Range` 的请求返回 200（无视 Range），立刻返回 `RangeUnsupported`
+/// —— 引擎据此退化单连接，而不是把整份文件重复写 N 遍。
+pub async fn fetch_chunk(
+    client: &reqwest::Client,
+    url: &str,
+    range: ByteRange,
+    part: &Path,
+    read_timeout: Duration,
+    progress: &AtomicU64,
+) -> Result<u64, DownloadError> {
+    use tokio::io::{AsyncSeekExt, AsyncWriteExt};
+
+    let request = client
+        .get(url)
+        .header(reqwest::header::RANGE, range.header_value());
+    let response = request
+        .send()
+        .await
+        .map_err(|err| http::classify_reqwest(&err, url))?;
+
+    let status = response.status().as_u16();
+    if status == 200 {
+        return Err(DownloadError::new(
+            DownloadErrorKind::RangeUnsupported,
+            format!("服务器忽略 Range 请求（{url}）"),
+        ));
+    }
+    if status != 206 {
+        return Err(http::classify_status(status, url));
+    }
+    // 服务器可能「回 206 但段不对」（CDN 缓存错位、Range 实现有 bug）。
+    // 判不符时按 RangeUnsupported 处理：引擎会丢弃中间文件、退化单连接重下，
+    // 这比在同一条坏路径上重试更划算。
+    let content_range = http::header_str(response.headers(), reqwest::header::CONTENT_RANGE);
+    if !content_range_matches(range, content_range) {
+        return Err(DownloadError::new(
+            DownloadErrorKind::RangeUnsupported,
+            format!(
+                "Content-Range 与请求段不符（{url}）：请求 {}，响应 {}",
+                range.header_value(),
+                content_range.unwrap_or("<缺失>")
+            ),
+        ));
+    }
+
+    let mut file = tokio::fs::OpenOptions::new()
+        .write(true)
+        .open(part)
+        .await
+        .map_err(|err| io_error(&err, "打开分块中间文件失败"))?;
+    file.seek(std::io::SeekFrom::Start(range.start))
+        .await
+        .map_err(|err| io_error(&err, "定位分块偏移失败"))?;
+
+    let mut stream = response.bytes_stream();
+    let mut written = 0_u64;
+    loop {
+        let next = tokio::time::timeout(read_timeout, futures_util::StreamExt::next(&mut stream))
+            .await
+            .map_err(|_| {
+                DownloadError::new(DownloadErrorKind::Timeout, format!("分块读取超时（{url}）"))
+            })?;
+        let Some(chunk) = next else { break };
+        let chunk = chunk.map_err(|err| http::classify_reqwest(&err, url))?;
+        file.write_all(&chunk)
+            .await
+            .map_err(|err| io_error(&err, "写入分块失败"))?;
+        let len = chunk.len() as u64;
+        written += len;
+        progress.fetch_add(len, Ordering::Relaxed);
+    }
+    file.flush()
+        .await
+        .map_err(|err| io_error(&err, "刷新分块失败"))?;
+
+    if written != range.len() {
+        return Err(DownloadError::new(
+            DownloadErrorKind::Network,
+            format!("分块长度不符：期望 {} 实得 {written}（{url}）", range.len()),
+        ));
+    }
+    Ok(written)
+}
+
+fn io_error(err: &std::io::Error, context: &str) -> DownloadError {
+    DownloadError::new(DownloadErrorKind::Io, format!("{context}: {err}"))
+}
diff --git a/crates/core/src/download/config.rs b/crates/core/src/download/config.rs
new file mode 100644
index 0000000..8fcf892
--- /dev/null
+++ b/crates/core/src/download/config.rs
@@ -0,0 +1,46 @@
+//! 引擎配置：设置层（core::setting）直接映射到这里。
+
+use std::time::Duration;
+
+use super::backoff::BackoffPolicy;
+use super::chunked::ChunkedConfig;
+use super::types::ResumePolicy;
+
+/// 引擎配置。
+#[derive(Debug, Clone)]
+pub struct EngineConfig {
+    /// 全局并发许可数（tokio `Semaphore`），默认 64。
+    pub max_concurrency: usize,
+    /// 每个源的尝试次数上限，默认 3。
+    pub max_attempts_per_source: u32,
+    /// 连接超时，默认 10s。
+    pub connect_timeout: Duration,
+    /// 单次读超时（读空闲判定，不是整体超时），默认 30s。
+    pub read_timeout: Duration,
+    /// User-Agent。
+    pub user_agent: String,
+    /// 进度事件节流间隔，默认 250ms。
+    pub progress_throttle: Duration,
+    /// 退避策略。
+    pub backoff: BackoffPolicy,
+    /// 分块下载配置。
+    pub chunked: ChunkedConfig,
+    /// 默认续传策略（请求级 `Never` 优先级更高）。
+    pub resume: ResumePolicy,
+}
+
+impl Default for EngineConfig {
+    fn default() -> Self {
+        Self {
+            max_concurrency: 64,
+            max_attempts_per_source: 3,
+            connect_timeout: Duration::from_secs(10),
+            read_timeout: Duration::from_secs(30),
+            user_agent: concat!("UnluckyLauncher/", env!("CARGO_PKG_VERSION")).to_string(),
+            progress_throttle: Duration::from_millis(250),
+            backoff: BackoffPolicy::default(),
+            chunked: ChunkedConfig::default(),
+            resume: ResumePolicy::Conservative,
+        }
+    }
+}
diff --git a/crates/core/src/download/engine.rs b/crates/core/src/download/engine.rs
new file mode 100644
index 0000000..1c73895
--- /dev/null
+++ b/crates/core/src/download/engine.rs
@@ -0,0 +1,397 @@
+//! 下载引擎：编排层。
+//!
+//! 一次 `download()` 的固定剧情：
+//!
+//! ```text
+//! 校验请求 → 内容寻址缓存直取（零网络）
+//!          → 候选规划（镜像表展开 + 健康度排序）
+//!          → Semaphore 限流
+//!          → 候选源外循环（换源），每源内循环（指数退避 + 抖动）
+//!              → 续传判定（保守）→ 单连接 / 多连接分块 → 流式校验 → 原子落盘
+//!          → 失败则保留中间文件供下次续传
+//! ```
+//!
+//! 最后一步保留的是**本会话命名的**中间文件（`<name>.ullpart-<session>-<seq>`，不再固定
+//! 叫 `<name>.ullpart`）：下次（甚至下次启动、重启后再下同一个文件）由 `PartFile::for_dest`
+//! 在目标目录里认领它并改名成新的会话名，续传判定照旧。详细身份规则见 `atomic.rs` 模块头的
+//! 「中间文件的身份」。
+//!
+//! 具体传输细节在 `transfer.rs`，错误分类在 `http.rs`，本文件只负责顺序与策略。
+
+use std::path::Path;
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+
+use tokio::sync::Semaphore;
+
+use super::atomic::PartFile;
+use super::backoff::Jitter;
+use super::cache::{now_ms, ContentCache};
+use super::config::EngineConfig;
+use super::error::{DownloadError, DownloadErrorKind};
+use super::health::HealthRegistry;
+use super::http;
+use super::mirrors::MirrorTable;
+use super::progress::{ProgressEmitter, ProgressEvent};
+use super::region::RegionProfile;
+use super::types::{
+    Candidate, DownloadId, DownloadOutcome, DownloadRequest, ResourceKind, ResumePolicy,
+    SOURCE_OFFICIAL,
+};
+
+/// 一次成功尝试的产物描述。
+pub(crate) struct AttemptOk {
+    /// 文件总字节数。
+    pub bytes: u64,
+    /// 续传起点（0 = 从头下）。
+    pub resumed_from: u64,
+}
+
+/// 下载引擎（`Arc` 后全局共享；内部无状态以外的可变数据只有抖动源）。
+#[derive(Debug)]
+pub struct DownloadEngine {
+    pub(crate) http: reqwest::Client,
+    pub(crate) cfg: EngineConfig,
+    pub(crate) progress: ProgressEmitter,
+    pub(crate) health: Arc<HealthRegistry>,
+    pub(crate) cache: Arc<ContentCache>,
+    pub(crate) jitter: std::sync::Mutex<Jitter>,
+    mirrors: Arc<MirrorTable>,
+    region: Arc<RegionProfile>,
+    sem: Arc<Semaphore>,
+}
+
+impl DownloadEngine {
+    /// 构造引擎（用 `with_progress` 挂事件流）。
+    #[must_use]
+    pub fn new(
+        cfg: EngineConfig,
+        mirrors: Arc<MirrorTable>,
+        region: Arc<RegionProfile>,
+        health: Arc<HealthRegistry>,
+        cache: Arc<ContentCache>,
+    ) -> Self {
+        let http = http::build_client(&cfg).unwrap_or_else(|_| reqwest::Client::new());
+        let sem = Arc::new(Semaphore::new(cfg.max_concurrency.max(1)));
+        let seed = now_ms() ^ (u64::from(cfg.max_concurrency as u32) << 32);
+        Self {
+            http,
+            cfg,
+            progress: ProgressEmitter::silent(),
+            health,
+            cache,
+            jitter: std::sync::Mutex::new(Jitter::new(seed)),
+            mirrors,
+            region,
+            sem,
+        }
+    }
+
+    /// 挂上进度事件发射器。
+    #[must_use]
+    pub fn with_progress(mut self, progress: ProgressEmitter) -> Self {
+        self.progress = progress;
+        self
+    }
+
+    /// 配置。
+    #[must_use]
+    pub fn config(&self) -> &EngineConfig {
+        &self.cfg
+    }
+
+    /// HTTP 客户端（同一条连接池与超时配置）。
+    ///
+    /// 给「一锤子查询」用——例如 Adoptium 的版本查询（`core::game::java::api`）：
+    /// 没必要为了一个 GET 再造一个 client，代理/超时/证书栈都在这里统一。
+    #[must_use]
+    pub fn client(&self) -> &reqwest::Client {
+        &self.http
+    }
+
+    /// 当前地区档案（设置页展示）。
+    #[must_use]
+    pub fn region(&self) -> &RegionProfile {
+        &self.region
+    }
+
+    /// 镜像表（`game::java` 的 Oracle / MS / Zulu 分发表在这里查）。
+    #[must_use]
+    pub fn mirrors(&self) -> &MirrorTable {
+        &self.mirrors
+    }
+
+    /// 健康度注册表（诊断页）。
+    #[must_use]
+    pub fn health(&self) -> &HealthRegistry {
+        &self.health
+    }
+
+    /// 内容寻址缓存。
+    #[must_use]
+    pub fn cache(&self) -> &ContentCache {
+        &self.cache
+    }
+
+    /// 候选规划：镜像展开 → 官方位置保持不变 → 其余按健康度排序。
+    #[must_use]
+    pub fn plan(&self, req: &DownloadRequest, now_ms: u64) -> Vec<Candidate> {
+        let expanded = self.mirrors.expand(&req.url, req.kind, &self.region);
+        let official_first = expanded
+            .first()
+            .is_none_or(|candidate| candidate.source == SOURCE_OFFICIAL);
+        let mut official = Vec::new();
+        let mut mirrors = Vec::new();
+        for candidate in expanded {
+            if candidate.source == SOURCE_OFFICIAL {
+                official.push(candidate);
+            } else {
+                mirrors.push(candidate);
+            }
+        }
+        let ranked = self.health.rank(&mirrors, req.kind, now_ms);
+        if official_first {
+            official.extend(ranked);
+            official
+        } else {
+            let mut out = ranked;
+            out.extend(official);
+            out
+        }
+    }
+
+    /// 单文件下载。
+    pub async fn download(
+        &self,
+        mut req: DownloadRequest,
+    ) -> Result<DownloadOutcome, DownloadError> {
+        let started = Instant::now();
+        let id = DownloadId::next();
+        req.validate()?;
+        if self.cfg.resume == ResumePolicy::Never {
+            req.resume = ResumePolicy::Never;
+        }
+
+        if let Some(integrity) = req.integrity.clone() {
+            if let Some(cached) = self.cache.lookup(&integrity, now_ms()) {
+                let bytes = materialize(&cached, &req.dest).map_err(|err| {
+                    DownloadError::new(
+                        DownloadErrorKind::Io,
+                        format!("缓存直取失败（{}）：{err}", req.dest.display()),
+                    )
+                })?;
+                self.emit(ProgressEvent::Completed {
+                    id,
+                    bytes,
+                    from_cache: true,
+                    source: "cache".to_string(),
+                    elapsed_ms: millis(started.elapsed()),
+                });
+                return Ok(DownloadOutcome {
+                    id,
+                    path: req.dest,
+                    bytes,
+                    from_cache: true,
+                    source: "cache".to_string(),
+                    resumed_from: 0,
+                    elapsed: started.elapsed(),
+                });
+            }
+        }
+
+        let plan = self.plan(&req, now_ms());
+        self.announce(&id, &req, plan.len());
+        if plan.is_empty() {
+            return Err(DownloadError::new(
+                DownloadErrorKind::InvalidRequest,
+                format!("没有可用候选源：{}", req.url),
+            ));
+        }
+
+        let _permit = self.acquire().await?;
+        let mut part = PartFile::for_dest(&req.dest);
+        let mut suppressed: Vec<String> = Vec::new();
+        let mut previous: Option<String> = None;
+
+        for candidate in &plan {
+            if let Some(from) = previous.take() {
+                self.emit(ProgressEvent::SourceSwitched {
+                    id,
+                    from,
+                    to: candidate.source.clone(),
+                });
+            }
+            // 冷却中 / 刚出冷却的源只给一次机会（那就是「恢复探测」）。
+            let max_attempts = self.attempts_for(&candidate.source, req.kind, now_ms());
+
+            for attempt in 0..max_attempts {
+                let attempt_started = Instant::now();
+                let outcome = self.attempt(id, &req, candidate, &mut part).await;
+                match outcome {
+                    Ok(ok) => {
+                        self.health.record_success(
+                            &candidate.source,
+                            req.kind,
+                            attempt_started.elapsed(),
+                            now_ms(),
+                        );
+                        let outcome = self.finish(&req, part, id, candidate, ok, started)?;
+                        self.flush_health();
+                        return Ok(outcome);
+                    }
+                    Err(err) => {
+                        // 4xx（NotFound）不算「源坏」：院校镜像只留最新补丁，请求旧补丁必然 404，
+                        // 记成失败会把唯一可用镜像冷却掉（M33/M34 实测：TUNA 每个目录只保 1 个归档）。
+                        if err.kind == DownloadErrorKind::NotFound {
+                            self.health.record_missing(
+                                &candidate.source,
+                                req.kind,
+                                &err.message,
+                                now_ms(),
+                            );
+                        } else {
+                            self.health.record_failure(
+                                &candidate.source,
+                                req.kind,
+                                &err.message,
+                                now_ms(),
+                            );
+                        }
+                        let retry = err.kind.is_retryable() && attempt + 1 < max_attempts;
+                        let delay = self.next_delay(attempt);
+                        self.emit(ProgressEvent::SourceFailed {
+                            id,
+                            source: candidate.source.clone(),
+                            reason: err.message.clone(),
+                            attempt,
+                            will_retry: retry,
+                            retry_in_ms: if retry { millis(delay) } else { 0 },
+                        });
+                        if !retry {
+                            suppressed.push(format!("{}: {}", candidate.source, err.message));
+                            break;
+                        }
+                        tokio::time::sleep(delay).await;
+                    }
+                }
+            }
+            previous = Some(candidate.source.clone());
+        }
+
+        // 全部候选失败：保留中间文件与元数据，下次（甚至下次启动）可续传。
+        part.preserve();
+        self.flush_health();
+        Err(DownloadError::new(
+            DownloadErrorKind::AllSourcesFailed,
+            format!("{} 个候选源全部失败：{}", plan.len(), req.url),
+        )
+        .with_suppressed(suppressed))
+    }
+
+    fn finish(
+        &self,
+        req: &DownloadRequest,
+        part: PartFile,
+        id: DownloadId,
+        candidate: &Candidate,
+        ok: AttemptOk,
+        started: Instant,
+    ) -> Result<DownloadOutcome, DownloadError> {
+        if let Some(integrity) = &req.integrity {
+            // 缓存写入失败不影响交付（缓存纯属加速）。
+            let _ = self.cache.insert(part.path(), integrity, now_ms());
+            let _ = self.cache.persist();
+        }
+        part.commit(&req.dest).map_err(|err| {
+            DownloadError::new(
+                DownloadErrorKind::Io,
+                format!("原子落盘失败（{}）：{err}", req.dest.display()),
+            )
+        })?;
+        let elapsed = started.elapsed();
+        self.emit(ProgressEvent::Completed {
+            id,
+            bytes: ok.bytes,
+            from_cache: false,
+            source: candidate.source.clone(),
+            elapsed_ms: millis(elapsed),
+        });
+        Ok(DownloadOutcome {
+            id,
+            path: req.dest.clone(),
+            bytes: ok.bytes,
+            from_cache: false,
+            source: candidate.source.clone(),
+            resumed_from: ok.resumed_from,
+            elapsed,
+        })
+    }
+
+    pub(crate) fn announce(&self, id: &DownloadId, req: &DownloadRequest, candidates: usize) {
+        self.emit(ProgressEvent::Started {
+            id: *id,
+            kind: req.kind,
+            url: req.url.clone(),
+            dest: req.dest.display().to_string(),
+            candidates,
+            total_bytes: req.expected_size,
+        });
+    }
+
+    pub(crate) async fn acquire(&self) -> Result<tokio::sync::OwnedSemaphorePermit, DownloadError> {
+        Arc::clone(&self.sem).acquire_owned().await.map_err(|_| {
+            DownloadError::new(DownloadErrorKind::Io, "并发闸门已关闭（引擎正在销毁）")
+        })
+    }
+
+    /// 该源此刻给几次尝试：
+    ///
+    /// * 冷却中 → 1 次（这次就是「恢复探测」，失败会重新冷却）；
+    /// * 刚出冷却、还没洗白 → 也只给 1 次（`is_probe()`，别让死源每次到期都吃满 3 次）；
+    /// * 正常 → 配置的 `max_attempts_per_source`。
+    pub(crate) fn attempts_for(&self, source: &str, kind: ResourceKind, now_ms: u64) -> u32 {
+        let health = self.health.health_of(source, kind);
+        if health.is_cooling_down(now_ms) || health.is_probe(now_ms) {
+            1
+        } else {
+            self.cfg.max_attempts_per_source.max(1)
+        }
+    }
+
+    /// 一次下载收尾时把健康度节流落盘（对齐 `cache.persist()` 的位置，但带节流）。
+    pub(crate) fn flush_health(&self) {
+        let _ = self.health.flush(now_ms());
+    }
+
+    pub(crate) fn next_delay(&self, attempt: u32) -> Duration {
+        let mut jitter = self
+            .jitter
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner());
+        self.cfg.backoff.next_delay(attempt, &mut jitter)
+    }
+
+    pub(crate) fn emit(&self, event: ProgressEvent) {
+        self.progress.emit(event);
+    }
+}
+
+/// 缓存命中时把文件变成工作副本（硬链接优先，跨卷退化为复制）。
+fn materialize(source: &Path, dest: &Path) -> std::io::Result<u64> {
+    if let Some(parent) = dest.parent() {
+        if !parent.as_os_str().is_empty() {
+            std::fs::create_dir_all(parent)?;
+        }
+    }
+    if dest.exists() {
+        let _ = std::fs::remove_file(dest);
+    }
+    if std::fs::hard_link(source, dest).is_err() {
+        std::fs::copy(source, dest)?;
+    }
+    Ok(std::fs::metadata(dest)?.len())
+}
+
+pub(crate) fn millis(duration: Duration) -> u64 {
+    u64::try_from(duration.as_millis()).unwrap_or(u64::MAX)
+}
diff --git a/crates/core/src/download/error.rs b/crates/core/src/download/error.rs
new file mode 100644
index 0000000..ed5f6cc
--- /dev/null
+++ b/crates/core/src/download/error.rs
@@ -0,0 +1,125 @@
+//! 下载错误：三态分类（同源重试 / 立刻换源 / 整体失败）+ 失败摘要。
+//!
+//! core 不引 `thiserror`（P0 阶段少一个依赖），手写 `Display`/`Error` 足够。
+
+use std::fmt;
+
+use serde::{Deserialize, Serialize};
+
+/// 错误分类：决定「同源重试」「立刻换源」还是「整体失败」。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum DownloadErrorKind {
+    /// 请求本身不合法（不重试）。
+    InvalidRequest,
+    /// 404/410/403：该源没有这个资源，立刻换源。
+    NotFound,
+    /// 5xx / 429：同源退避重试。
+    ServerError,
+    /// 超时：同源退避重试，多次后换源。
+    Timeout,
+    /// 连接/传输层错误。
+    Network,
+    /// 校验不符：同源重试一次后换源（可能是镜像内容不一致）。
+    Integrity,
+    /// 服务器不支持 Range（内部用于退化单连接，不向上暴露为失败）。
+    RangeUnsupported,
+    /// 本地 IO 错误（不重试）。
+    Io,
+    /// 所有候选源都失败。
+    AllSourcesFailed,
+}
+
+impl DownloadErrorKind {
+    /// 稳定字符串 id。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::InvalidRequest => "invalid_request",
+            Self::NotFound => "not_found",
+            Self::ServerError => "server_error",
+            Self::Timeout => "timeout",
+            Self::Network => "network",
+            Self::Integrity => "integrity",
+            Self::RangeUnsupported => "range_unsupported",
+            Self::Io => "io",
+            Self::AllSourcesFailed => "all_sources_failed",
+        }
+    }
+
+    /// 是否值得在同源上退避重试。
+    #[must_use]
+    pub const fn is_retryable(self) -> bool {
+        matches!(
+            self,
+            Self::ServerError | Self::Timeout | Self::Network | Self::Integrity
+        )
+    }
+}
+
+/// 下载错误。
+#[derive(Debug, Clone)]
+pub struct DownloadError {
+    /// 分类。
+    pub kind: DownloadErrorKind,
+    /// 出错的源（整体失败时为 `None`）。
+    pub source: Option<String>,
+    /// 人类可读描述。
+    pub message: String,
+    /// 已经尝试的次数（含本次）。
+    pub attempts: usize,
+    /// 其它候选源的失败摘要，便于诊断「到底哪一层挂了」。
+    pub suppressed: Vec<String>,
+}
+
+impl DownloadError {
+    /// 构造错误。
+    #[must_use]
+    pub fn new(kind: DownloadErrorKind, message: impl Into<String>) -> Self {
+        Self {
+            kind,
+            source: None,
+            message: message.into(),
+            attempts: 0,
+            suppressed: Vec::new(),
+        }
+    }
+
+    /// 标注出错的源。
+    #[must_use]
+    pub fn with_source(mut self, source: impl Into<String>) -> Self {
+        self.source = Some(source.into());
+        self
+    }
+
+    /// 标注尝试次数。
+    #[must_use]
+    pub fn with_attempts(mut self, attempts: usize) -> Self {
+        self.attempts = attempts;
+        self
+    }
+
+    /// 汇总其它源的失败摘要。
+    #[must_use]
+    pub fn with_suppressed(mut self, suppressed: Vec<String>) -> Self {
+        self.suppressed = suppressed;
+        self
+    }
+}
+
+impl fmt::Display for DownloadError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match &self.source {
+            Some(source) => write!(
+                f,
+                "[{}] {}（源 {}）",
+                self.kind.as_str(),
+                self.message,
+                source
+            ),
+            None => write!(f, "[{}] {}", self.kind.as_str(), self.message),
+        }
+    }
+}
+
+impl std::error::Error for DownloadError {}
diff --git a/crates/core/src/download/health.rs b/crates/core/src/download/health.rs
new file mode 100644
index 0000000..d3f6169
--- /dev/null
+++ b/crates/core/src/download/health.rs
@@ -0,0 +1,399 @@
+//! 源健康度记忆：`源 × 资源类型` 的 EMA RTT / 失败率 / 连续失败。
+//!
+//! HMCL 没有这一层（analyse/03 §8.4 的「下载快」一栏是纯并发 + 缓存），于是同一台机器上
+//! 一个常年 502 的镜像会被每个文件重试一遍。这里的规则：
+//!
+//! * 连续 **3** 次失败 → 冷却 **10 分钟**，期间该源排到最后（仍保留为兜底候选）；
+//! * 冷却结束后自动进入**恢复探测**：下一次尝试就是一次探测，成功即清零回队，失败则重新冷却；
+//! * 记录持久化到 `cache/health.json`（原子写），进程重启后仍然生效：
+//!   **冷却状态迁移时立刻落盘**（进入/退出冷却这种罕见事件），其余变化标脏，
+//!   由引擎在一次 `download()` / `download_bytes()` 收尾时 `flush()` 节流落盘，
+//!   避免「批量下 3000 个资源 = 3000 次原子写」；
+//! * 排序打分 = EMA RTT + 失败率惩罚 + 连续失败惩罚，冷却中的源加一个大惩罚。
+
+use std::collections::HashMap;
+use std::io;
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::Mutex;
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
+
+use serde::{Deserialize, Serialize};
+
+use super::health_store;
+use super::types::{Candidate, ResourceKind, SOURCE_OFFICIAL};
+
+/// 连续失败多少次进入冷却。
+pub const FAILURE_THRESHOLD: u32 = 3;
+/// 冷却时长（毫秒）：连续失败后的冷板凳时间。
+pub const COOLDOWN_MS: u64 = 10 * 60 * 1000;
+/// EMA 的平滑系数（0.3 意味着新样本占 30%）。
+pub const EMA_ALPHA: f64 = 0.3;
+/// 冷板凳/未知源的基础打分。
+pub const SCORE_UNKNOWN: f64 = 400.0;
+/// 落盘节流：两次 flush 之间的最小间隔（毫秒）。
+pub const SAVE_THROTTLE_MS: u64 = 5_000;
+/// 冷却中的惩罚项。
+pub const SCORE_COOLDOWN_PENALTY: f64 = 1_000.0;
+
+/// 健康度的记忆键：一个源在一种资源类型上的表现是独立的。
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub struct HealthKey {
+    /// 源标识（`official` / `bmclapi` / `tuna` …）。
+    pub source: String,
+    /// 资源类型。
+    pub kind: ResourceKind,
+}
+
+impl HealthKey {
+    /// 构造键。
+    #[must_use]
+    pub fn new(source: impl Into<String>, kind: ResourceKind) -> Self {
+        Self {
+            source: source.into(),
+            kind,
+        }
+    }
+}
+
+/// 单个 `源 × 资源类型` 的健康记录。
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct SourceHealth {
+    /// 成功请求的 RTT 指数移动平均（毫秒）；无样本时为 0。
+    pub ema_rtt_ms: f64,
+    /// 参与 EMA 的样本数。
+    pub samples: u64,
+    /// 累计成功次数。
+    pub successes: u64,
+    /// 累计失败次数。
+    pub failures: u64,
+    /// 累计「该源没有这个资源」（4xx）。**不计失败、不进冷却**——院校镜像通常只留最新补丁，
+    /// 请求旧补丁必然 404，把这种情况算成「源坏」会在一次安装里把唯一可用镜像冷却掉。
+    #[serde(default)]
+    pub not_found: u64,
+    /// 连续失败次数。
+    pub consecutive_failures: u32,
+    /// 冷却截止时间（unix 毫秒，0 = 未冷却）。
+    pub cooldown_until_ms: u64,
+    /// 最近一次失败原因（诊断页用）。
+    pub last_error: Option<String>,
+    /// 最后更新时间（unix 毫秒）。
+    pub updated_at_ms: u64,
+}
+
+impl Default for SourceHealth {
+    fn default() -> Self {
+        Self {
+            ema_rtt_ms: 0.0,
+            samples: 0,
+            successes: 0,
+            failures: 0,
+            not_found: 0,
+            consecutive_failures: 0,
+            cooldown_until_ms: 0,
+            last_error: None,
+            updated_at_ms: 0,
+        }
+    }
+}
+
+impl SourceHealth {
+    /// 记录一次成功：重置连续失败与冷却，更新 EMA RTT。
+    pub fn record_success(&mut self, rtt_ms: u64, now_ms: u64) {
+        self.successes += 1;
+        self.consecutive_failures = 0;
+        self.cooldown_until_ms = 0;
+        self.last_error = None;
+        self.updated_at_ms = now_ms;
+        let rtt = rtt_ms as f64;
+        self.ema_rtt_ms = if self.samples == 0 {
+            rtt
+        } else {
+            EMA_ALPHA * rtt + (1.0 - EMA_ALPHA) * self.ema_rtt_ms
+        };
+        self.samples += 1;
+    }
+
+    /// 记录一次失败：达到阈值即进入冷却。
+    pub fn record_failure(&mut self, reason: &str, now_ms: u64) {
+        self.failures += 1;
+        self.consecutive_failures = self.consecutive_failures.saturating_add(1);
+        self.updated_at_ms = now_ms;
+        self.last_error = Some(reason.to_string());
+        if self.consecutive_failures >= FAILURE_THRESHOLD {
+            self.cooldown_until_ms = now_ms.saturating_add(COOLDOWN_MS);
+        }
+    }
+
+    /// 记录一次「该源没有这个资源」（HTTP 4xx）：只留诊断痕迹，不动失败率与冷却。
+    pub fn record_missing(&mut self, reason: &str, now_ms: u64) {
+        self.not_found = self.not_found.saturating_add(1);
+        self.updated_at_ms = now_ms;
+        self.last_error = Some(reason.to_string());
+    }
+
+    /// 是否处于冷却期。
+    #[must_use]
+    pub fn is_cooling_down(&self, now_ms: u64) -> bool {
+        self.cooldown_until_ms > now_ms
+    }
+
+    /// 上次冷却是否已到期（此时这次尝试就是「恢复探测」）。
+    #[must_use]
+    pub fn is_probe(&self, now_ms: u64) -> bool {
+        self.cooldown_until_ms != 0 && self.cooldown_until_ms <= now_ms
+    }
+
+    /// 失败率（0.0~1.0）。
+    #[must_use]
+    pub fn failure_rate(&self) -> f64 {
+        let total = self.successes + self.failures;
+        if total == 0 {
+            0.0
+        } else {
+            self.failures as f64 / total as f64
+        }
+    }
+
+    /// 排序打分（越小越优先）。
+    #[must_use]
+    pub fn score(&self, now_ms: u64) -> f64 {
+        if self.is_cooling_down(now_ms) {
+            return SCORE_COOLDOWN_PENALTY + self.ema_rtt_ms;
+        }
+        if self.samples == 0 && self.failures == 0 {
+            return SCORE_UNKNOWN;
+        }
+        self.ema_rtt_ms + self.failure_rate() * 500.0 + f64::from(self.consecutive_failures) * 50.0
+    }
+}
+
+/// 健康度注册表（进程内共享，`Arc` 后传给引擎）。
+#[derive(Debug)]
+pub struct HealthRegistry {
+    path: Option<PathBuf>,
+    entries: Mutex<HashMap<HealthKey, SourceHealth>>,
+    dirty: AtomicBool,
+    last_save_ms: AtomicU64,
+}
+
+impl Default for HealthRegistry {
+    fn default() -> Self {
+        Self::in_memory()
+    }
+}
+
+impl HealthRegistry {
+    /// 纯内存实例（测试用 / 用户关掉健康度记忆时）。
+    #[must_use]
+    pub fn in_memory() -> Self {
+        Self {
+            path: None,
+            entries: Mutex::new(HashMap::new()),
+            dirty: AtomicBool::new(false),
+            last_save_ms: AtomicU64::new(0),
+        }
+    }
+
+    /// 打开持久化文件（不存在则从空表开始；损坏/超龄记录则忽略）。
+    #[must_use]
+    pub fn open(path: impl Into<PathBuf>, max_age_ms: u64, now_ms: u64) -> Self {
+        let path = path.into();
+        let entries = health_store::load(&path, max_age_ms, now_ms);
+        Self {
+            path: Some(path),
+            entries: Mutex::new(entries),
+            dirty: AtomicBool::new(false),
+            last_save_ms: AtomicU64::new(now_ms),
+        }
+    }
+
+    /// 按 `cache/` 根目录打开（**生产接线用这一条**）：文件固定在 `<cache>/health.json`，
+    /// 保留期用默认值。
+    #[must_use]
+    pub fn open_in(cache_root: impl AsRef<Path>, now_ms: u64) -> Self {
+        Self::open(
+            cache_root.as_ref().join(health_store::FILE_NAME),
+            health_store::MAX_AGE_MS,
+            now_ms,
+        )
+    }
+
+    /// 持久化文件路径（诊断页展示用）。
+    #[must_use]
+    pub fn path(&self) -> Option<&Path> {
+        self.path.as_deref()
+    }
+
+    fn lock(&self) -> std::sync::MutexGuard<'_, HashMap<HealthKey, SourceHealth>> {
+        self.entries
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner())
+    }
+
+    /// 读取某个键的记录（不存在则返回默认值）。
+    #[must_use]
+    pub fn health_of(&self, source: &str, kind: ResourceKind) -> SourceHealth {
+        self.lock()
+            .get(&HealthKey::new(source, kind))
+            .cloned()
+            .unwrap_or_default()
+    }
+
+    /// 记录成功；返回冷却状态是否发生变化（变化即立刻落盘）。
+    pub fn record_success(
+        &self,
+        source: &str,
+        kind: ResourceKind,
+        rtt: Duration,
+        now_ms: u64,
+    ) -> bool {
+        let changed = {
+            let mut entries = self.lock();
+            let health = entries.entry(HealthKey::new(source, kind)).or_default();
+            let before = health.cooldown_until_ms;
+            health.record_success(rtt.as_millis() as u64, now_ms);
+            before != health.cooldown_until_ms
+        };
+        self.after_record(changed);
+        changed
+    }
+
+    /// 记录失败；返回冷却状态是否发生变化（第 3 次连续失败会进入冷却 → 立刻落盘）。
+    pub fn record_failure(
+        &self,
+        source: &str,
+        kind: ResourceKind,
+        reason: &str,
+        now_ms: u64,
+    ) -> bool {
+        let changed = {
+            let mut entries = self.lock();
+            let health = entries.entry(HealthKey::new(source, kind)).or_default();
+            let before = health.cooldown_until_ms;
+            health.record_failure(reason, now_ms);
+            before != health.cooldown_until_ms
+        };
+        self.after_record(changed);
+        changed
+    }
+
+    /// 记录「该源没有这个资源」（4xx）：不计失败、不进冷却，只更新诊断字段。
+    pub fn record_missing(&self, source: &str, kind: ResourceKind, reason: &str, now_ms: u64) {
+        {
+            let mut entries = self.lock();
+            let health = entries.entry(HealthKey::new(source, kind)).or_default();
+            health.record_missing(reason, now_ms);
+        }
+        self.after_record(false);
+    }
+
+    /// 记录后：标脏，冷却状态迁移则立刻落盘（这种事件很少，不会打爆磁盘）。
+    fn after_record(&self, cooldown_changed: bool) {
+        self.dirty.store(true, Ordering::Relaxed);
+        if cooldown_changed {
+            let _ = self.save();
+        }
+    }
+
+    /// 该源当前是否在冷却期。
+    #[must_use]
+    pub fn is_cooling_down(&self, source: &str, kind: ResourceKind, now_ms: u64) -> bool {
+        self.health_of(source, kind).is_cooling_down(now_ms)
+    }
+
+    /// 按健康度重排候选序列：健康好的在前，冷却中的排到最后（仍保留为兜底）。
+    #[must_use]
+    pub fn rank(
+        &self,
+        candidates: &[Candidate],
+        kind: ResourceKind,
+        now_ms: u64,
+    ) -> Vec<Candidate> {
+        let entries = self.lock();
+        let mut scored: Vec<(f64, usize, Candidate)> = candidates
+            .iter()
+            .enumerate()
+            .map(|(index, candidate)| {
+                let score = entries
+                    .get(&HealthKey::new(candidate.source.clone(), kind))
+                    .map_or(SCORE_UNKNOWN, |health| health.score(now_ms));
+                (score, index, candidate.clone())
+            })
+            .collect();
+        scored.sort_by(|a, b| a.0.total_cmp(&b.0).then(a.1.cmp(&b.1)));
+        scored
+            .into_iter()
+            .map(|(_, _, candidate)| candidate)
+            .collect()
+    }
+
+    /// 快照（诊断页/测试用），按源名排序保证稳定。
+    #[must_use]
+    pub fn snapshot(&self) -> Vec<(HealthKey, SourceHealth)> {
+        let entries = self.lock();
+        let mut rows: Vec<(HealthKey, SourceHealth)> = entries
+            .iter()
+            .map(|(key, health)| (key.clone(), health.clone()))
+            .collect();
+        rows.sort_by(|a, b| {
+            a.0.source
+                .cmp(&b.0.source)
+                .then(a.0.kind.as_str().cmp(b.0.kind.as_str()))
+        });
+        rows
+    }
+
+    /// 清空（设置页「重置下载源健康度」）。
+    pub fn clear(&self) {
+        self.lock().clear();
+    }
+
+    /// 无条件原子持久化到 `cache/health.json`（纯内存实例上是空操作）。
+    pub fn save(&self) -> io::Result<()> {
+        let Some(path) = self.path.clone() else {
+            self.dirty.store(false, Ordering::Relaxed);
+            return Ok(());
+        };
+        health_store::store(&path, &self.lock())?;
+        self.dirty.store(false, Ordering::Relaxed);
+        self.last_save_ms.store(now_wall_ms(), Ordering::Relaxed);
+        Ok(())
+    }
+
+    /// 下载收尾时的节流落盘：只有「脏」且距上次落盘超过 [`SAVE_THROTTLE_MS`] 才写。
+    ///
+    /// 引擎在每个 `download()` / `download_bytes()` 结束时调它——批量下载因此最多
+    /// 每 5 秒写一次盘，而不是每个文件一次。
+    pub fn flush(&self, now_ms: u64) -> io::Result<()> {
+        if self.path.is_none() || !self.dirty.load(Ordering::Relaxed) {
+            return Ok(());
+        }
+        let last = self.last_save_ms.load(Ordering::Relaxed);
+        if now_ms.saturating_sub(last) < SAVE_THROTTLE_MS {
+            return Ok(());
+        }
+        self.save()
+    }
+
+    /// 是否有未落盘的改动（诊断页/测试用）。
+    #[must_use]
+    pub fn is_dirty(&self) -> bool {
+        self.dirty.load(Ordering::Relaxed)
+    }
+}
+
+/// 官方源的空健康记录便捷构造（game 层拼候选时常用）。
+#[must_use]
+pub fn official_key(kind: ResourceKind) -> HealthKey {
+    HealthKey::new(SOURCE_OFFICIAL, kind)
+}
+
+/// 记录落盘时刻用的墙钟（不为它引入时钟抽象，测试走显式 `now_ms` 参数）。
+fn now_wall_ms() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map_or(0, |since| {
+            u64::try_from(since.as_millis()).unwrap_or(u64::MAX)
+        })
+}
diff --git a/crates/core/src/download/health_store.rs b/crates/core/src/download/health_store.rs
new file mode 100644
index 0000000..179d8fa
--- /dev/null
+++ b/crates/core/src/download/health_store.rs
@@ -0,0 +1,80 @@
+//! 健康度的落盘格式与读盘/写盘（`cache/health.json`）。
+//!
+//! 与 `health.rs` 分开的原因很实际：序列化格式与文件 IO 的细节会随版本增长（字段增删、
+//! 迁移、按源分文件…），把这些从「打分/冷却」的纯逻辑里挪出来，两边都好读好改。
+
+use std::collections::HashMap;
+use std::io;
+use std::path::Path;
+
+use serde::{Deserialize, Serialize};
+
+use super::atomic::write_atomic;
+use super::health::{HealthKey, SourceHealth};
+use super::types::ResourceKind;
+
+/// 健康度文件名（放在 `cache/` 下，与 `index.json` 同级）。
+pub const FILE_NAME: &str = "health.json";
+/// 记录保留期：超过这个时间没更新过的源直接丢掉（缓存目录可能被放很久）。
+pub const MAX_AGE_MS: u64 = 7 * 24 * 60 * 60 * 1000;
+
+/// 持久化的条目形态（`HealthKey` 拍平，便于 JSON 阅读）。
+#[derive(Debug, Clone, Serialize, Deserialize)]
+struct PersistedEntry {
+    source: String,
+    kind: ResourceKind,
+    health: SourceHealth,
+}
+
+/// 持久化文件的容器。
+#[derive(Debug, Clone, Serialize, Deserialize)]
+struct PersistedFile {
+    version: u32,
+    #[serde(default)]
+    entries: Vec<PersistedEntry>,
+}
+
+/// 读盘：不存在/损坏/超龄都只丢掉对应记录，绝不阻断启动。
+pub(crate) fn load(path: &Path, max_age_ms: u64, now_ms: u64) -> HashMap<HealthKey, SourceHealth> {
+    let mut entries = HashMap::new();
+    let Ok(bytes) = std::fs::read(path) else {
+        return entries;
+    };
+    match serde_json::from_slice::<PersistedFile>(&bytes) {
+        Ok(file) => {
+            for entry in file.entries {
+                if entry.health.updated_at_ms.saturating_add(max_age_ms) >= now_ms {
+                    entries.insert(HealthKey::new(entry.source, entry.kind), entry.health);
+                }
+            }
+        }
+        Err(err) => warn(&format!("健康度文件解析失败，按空表处理：{err}")),
+    }
+    entries
+}
+
+/// 写盘：原子写（`tmp → rename`），失败由调用方决定是记日志还是忽略。
+pub(crate) fn store(path: &Path, entries: &HashMap<HealthKey, SourceHealth>) -> io::Result<()> {
+    let file = PersistedFile {
+        version: 1,
+        entries: entries
+            .iter()
+            .map(|(key, health)| PersistedEntry {
+                source: key.source.clone(),
+                kind: key.kind,
+                health: health.clone(),
+            })
+            .collect(),
+    };
+    let json = serde_json::to_vec_pretty(&file).map_err(io::Error::other)?;
+    write_atomic(path, &json)
+}
+
+/// core 不引 tracing（P0 阶段日志由 app 层接管），这里只做一次静默的 stderr 兜底。
+fn warn(message: &str) {
+    if cfg!(debug_assertions) {
+        eprintln!("[ull::download] {message}");
+    } else {
+        let _ = message;
+    }
+}
diff --git a/crates/core/src/download/http.rs b/crates/core/src/download/http.rs
new file mode 100644
index 0000000..6e6fd66
--- /dev/null
+++ b/crates/core/src/download/http.rs
@@ -0,0 +1,183 @@
+//! HTTP 薄封装：客户端构造、错误分类、响应头读取。
+//!
+//! 关键取舍：
+//! * **`Accept-Encoding: identity`** —— 下载要按字节对齐做 Range/校验，gzip 会让
+//!   `Content-Length` 与实际写入量打架（HMCL 为此专门写了按解压后偏移计数的
+//!   `HttpResumeContext`，analyse/03 §5.4），我们直接从协议层绕开这个问题；
+//! * 重定向上限 20 跳（承 HMCL），跳转后仍按最终 URL 做 host 校验由调用方负责；
+//! * 错误分类只做「同源重试 / 立刻换源 / 整体失败」三态，不做细颗粒映射。
+
+use reqwest::header::{
+    HeaderMap, HeaderName, ACCEPT_ENCODING, CONTENT_LENGTH, CONTENT_TYPE, ETAG, LAST_MODIFIED,
+};
+use reqwest::redirect::Policy;
+
+use super::config::EngineConfig;
+use super::error::{DownloadError, DownloadErrorKind};
+
+/// 重定向上限（承 HMCL 的 20 跳）。
+pub const MAX_REDIRECTS: usize = 20;
+
+/// 构造共享的 `reqwest::Client`（连接池、超时、重定向策略一次定好）。
+pub fn build_client(cfg: &EngineConfig) -> Result<reqwest::Client, DownloadError> {
+    let mut headers = HeaderMap::new();
+    headers.insert(
+        ACCEPT_ENCODING,
+        reqwest::header::HeaderValue::from_static("identity"),
+    );
+    reqwest::Client::builder()
+        .user_agent(cfg.user_agent.clone())
+        .connect_timeout(cfg.connect_timeout)
+        .redirect(Policy::limited(MAX_REDIRECTS))
+        .default_headers(headers)
+        .build()
+        .map_err(|err| {
+            DownloadError::new(
+                DownloadErrorKind::Network,
+                format!("构造 HTTP 客户端失败：{err}"),
+            )
+        })
+}
+
+/// 把 `reqwest::Error` 映射成我们的错误分类。
+#[must_use]
+pub fn classify_reqwest(err: &reqwest::Error, url: &str) -> DownloadError {
+    let kind = if err.is_timeout() {
+        DownloadErrorKind::Timeout
+    } else if let Some(status) = err.status() {
+        return classify_status(status.as_u16(), url);
+    } else {
+        DownloadErrorKind::Network
+    };
+    DownloadError::new(kind, format!("{err}")).with_source(url)
+}
+
+/// HTTP 状态码 → 错误分类。
+#[must_use]
+pub fn classify_status(status: u16, url: &str) -> DownloadError {
+    let kind = match status {
+        404 | 410 => DownloadErrorKind::NotFound,
+        // 403/401 对镜像来说基本等于「这条路不能走」，直接换源比退避更有用。
+        401 | 403 => DownloadErrorKind::NotFound,
+        408 => DownloadErrorKind::Timeout,
+        416 => DownloadErrorKind::RangeUnsupported,
+        429 => DownloadErrorKind::ServerError,
+        500..=599 => DownloadErrorKind::ServerError,
+        _ => DownloadErrorKind::ServerError,
+    };
+    DownloadError::new(kind, format!("HTTP {status}")).with_source(url)
+}
+
+/// 读一个头的字符串值。
+#[must_use]
+pub fn header_str(headers: &HeaderMap, name: HeaderName) -> Option<&str> {
+    headers.get(name).and_then(|value| value.to_str().ok())
+}
+
+/// `Content-Length`。
+#[must_use]
+pub fn content_length(headers: &HeaderMap) -> Option<u64> {
+    header_str(headers, CONTENT_LENGTH).and_then(|value| value.trim().parse().ok())
+}
+
+/// `ETag`（续传的强校验器）。
+#[must_use]
+pub fn etag(headers: &HeaderMap) -> Option<String> {
+    header_str(headers, ETAG).map(str::to_string)
+}
+
+/// `Last-Modified`（弱校验器，ETag 缺失时的兜底）。
+#[must_use]
+pub fn last_modified(headers: &HeaderMap) -> Option<String> {
+    header_str(headers, LAST_MODIFIED).map(str::to_string)
+}
+
+/// `Content-Type`。
+#[must_use]
+pub fn content_type(headers: &HeaderMap) -> Option<&str> {
+    header_str(headers, CONTENT_TYPE)
+}
+
+/// 判断一个 2xx 响应是不是「伪装的档案」（镜像门户的假阳性兜底页）。
+///
+/// 出处：research/06 §0.2 / §5.3 第 2 条——`mirrors.huaweicloud.com` 对**任意不存在的路径**
+/// 都回 `200 + 12 434 字节 Angular 门户 HTML`，只看状态码会把死源当活源。
+///
+/// 两条判据（都只在证据充分时才拒）：
+/// 1. `Content-Type` 含 `html` → 一定是门户页，不是归档；
+/// 2. 已知期望大小、且是整文件请求（`offset == 0`）、响应带 `Content-Length` 却对不上
+///    → 长度对拍失败，同样不是我们要的那个文件。
+///
+/// 返回 `Some(原因)` 时调用方应当**换源**（归到 `NotFound` 类：不算源坏、不进冷却）。
+#[must_use]
+pub fn html_mirror_reason(
+    headers: &HeaderMap,
+    expected_size: Option<u64>,
+    offset: u64,
+) -> Option<&'static str> {
+    if content_type(headers).is_some_and(|value| value.to_ascii_lowercase().contains("html")) {
+        return Some("源返回 HTML（镜像门户兜底页，假阳性：该路径没有真实归档）");
+    }
+    if offset == 0 {
+        if let (Some(expected), Some(actual)) = (expected_size, content_length(headers)) {
+            if expected > 0 && actual != expected {
+                return Some("源返回的 Content-Length 与期望大小不符（疑似门户页/截断响应）");
+            }
+        }
+    }
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use reqwest::header::{HeaderMap, HeaderValue, CONTENT_LENGTH, CONTENT_TYPE};
+
+    use super::{html_mirror_reason, MAX_REDIRECTS};
+
+    fn headers(content_type: Option<&str>, length: Option<u64>) -> HeaderMap {
+        let mut map = HeaderMap::new();
+        if let Some(value) = content_type {
+            map.insert(CONTENT_TYPE, HeaderValue::from_str(value).expect("头值"));
+        }
+        if let Some(value) = length {
+            map.insert(CONTENT_LENGTH, HeaderValue::from(value));
+        }
+        map
+    }
+
+    #[test]
+    fn html_portal_page_is_rejected_even_with_200() {
+        // 华为云实测：任意不存在的路径 → 200 + text/html + 12434 字节。
+        let map = headers(Some("text/html;charset=UTF-8"), Some(12_434));
+        assert_eq!(
+            html_mirror_reason(&map, Some(201_328_186), 0),
+            Some("源返回 HTML（镜像门户兜底页，假阳性：该路径没有真实归档）")
+        );
+        // 只有 Content-Type 也能判（没有期望大小时）。
+        assert!(html_mirror_reason(&map, None, 0).is_some());
+    }
+
+    #[test]
+    fn real_archive_matching_the_expected_size_passes() {
+        let map = headers(Some("application/zip"), Some(201_328_186));
+        assert_eq!(html_mirror_reason(&map, Some(201_328_186), 0), None);
+        // 镜像没给 Content-Type 也照放行（有 sha256 兜底）。
+        let bare = headers(None, Some(201_328_186));
+        assert_eq!(html_mirror_reason(&bare, Some(201_328_186), 0), None);
+    }
+
+    #[test]
+    fn mismatched_length_is_rejected_but_resumed_reads_are_left_alone() {
+        let map = headers(Some("application/octet-stream"), Some(973_920));
+        assert!(html_mirror_reason(&map, Some(205_421_281), 0).is_some());
+        // 续传片段当然比全量小：不能按整文件口径对拍。
+        assert_eq!(html_mirror_reason(&map, Some(205_421_281), 973_920), None);
+        // 未知期望大小 → 不做长度判定。
+        assert_eq!(html_mirror_reason(&map, None, 0), None);
+    }
+
+    #[test]
+    fn redirect_cap_is_still_twenty() {
+        assert_eq!(MAX_REDIRECTS, 20);
+    }
+}
diff --git a/crates/core/src/download/jdk_sources.rs b/crates/core/src/download/jdk_sources.rs
new file mode 100644
index 0000000..428f3e8
--- /dev/null
+++ b/crates/core/src/download/jdk_sources.rs
@@ -0,0 +1,178 @@
+//! JDK 分发源表（`mirrors.json` v3）：Oracle OpenJDK / Microsoft OpenJDK / Azul Zulu。
+//!
+//! v2 只有 `adoptium`（Temurin）一张表，因为当时只做一家发行版。D23 定下三家 + 第四备选后，
+//! 三家的分发形态各不相同，表结构也就各有一套（research/06 §5.2 条目样例照抄）：
+//!
+//! | 发行版 | 枚举方式 | 下载形态 |
+//! | --- | --- | --- |
+//! | Oracle OpenJDK | Apache 目录页（华为云 / 南大，与 `download.java.net` 同构） | `{base}/{ver}/{filename}`，hash 段不可推导 |
+//! | Microsoft OpenJDK | 内置版本快照（官方只有人读 HTML 表） | `aka.ms` 模板 301 → VS CDN，校验走成对的 `.sha256sum.txt` |
+//! | Zulu | 免登录 JSON API（两跳：列表 → 详情） | `download_url` 直出，只信 `sha256_hash` |
+//!
+//! 表本身只是「数据」：怎么用由 `game::java` 的 `oracle` / `microsoft` / `zulu` 决定。
+//! v3 兼容读 v2：新表全部 `#[serde(default)]`，老文件照常解析（新表为空，回退链自然退化成只有 Temurin）。
+
+use serde::{Deserialize, Serialize};
+
+use super::mirrors::MirrorTable;
+
+const fn default_true() -> bool {
+    true
+}
+
+/// 一个 Oracle OpenJDK 镜像（`download.java.net/openjdk` 的忠实镜像）。
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct OracleMirror {
+    /// 源标识（`huawei` / `nju`）。
+    pub id: String,
+    /// 展示名。
+    pub name: String,
+    /// 目录根（形如 `https://mirrors.huaweicloud.com/openjdk`）。
+    pub base: String,
+    /// 是否启用。
+    #[serde(default = "default_true")]
+    pub enabled: bool,
+    /// 实测吞吐（展示用，不参与决策）。
+    #[serde(default)]
+    pub speed: String,
+    /// 备注（展示用）。
+    #[serde(default)]
+    pub note: String,
+}
+
+impl OracleMirror {
+    /// 目录根（去掉尾斜杠，拼路径时不会再出双斜杠）。
+    #[must_use]
+    pub fn base(&self) -> &str {
+        self.base.trim_end_matches('/')
+    }
+}
+
+/// Microsoft OpenJDK 的分发表：官方模板 + 内置版本快照。
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MsOpenJdkTable {
+    /// 人读清单页（刷新快照时抓的页面，仅供排查）。
+    #[serde(default)]
+    pub list: String,
+    /// 下载模板：`microsoft-jdk-{version}-{os}-{arch}.zip`。
+    pub template: String,
+    /// 校验模板：同一文件名 + `.sha256sum.txt`。
+    pub sha256_template: String,
+    /// 官方在发的 GA 大版本（没有 8——微软已停发，官方页面让去用 Temurin 8）。
+    #[serde(default)]
+    pub majors: Vec<u32>,
+    /// 国内镜像（实测为空数组：三家云都没有 MS OpenJDK）。
+    #[serde(default)]
+    pub domestic_mirrors: Vec<String>,
+    /// 实测吞吐（展示用）。
+    #[serde(default)]
+    pub measured_speed: String,
+}
+
+/// Zulu（Azul）的元数据表。
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ZuluTable {
+    /// 包列表 API 根。
+    pub api: String,
+    /// 包详情 API（`{uuid}` 占位）——`latest=true` 的响应不含 sha256，必须再取一次。
+    pub detail: String,
+    /// CDN host（`cdn.azul.com`，展示用）。
+    #[serde(default)]
+    pub cdn_host: String,
+    /// 实测吞吐（展示用）。
+    #[serde(default)]
+    pub measured_speed: String,
+    /// `size` 字段是否可与真实字节数对拍（实测 `false`，差 133 B）。
+    #[serde(default)]
+    pub size_field_reliable: bool,
+}
+
+impl MirrorTable {
+    /// 启用的 Oracle OpenJDK 镜像（清单顺序 = 默认尝试顺序）。
+    pub fn oracle_mirrors(&self) -> impl Iterator<Item = &OracleMirror> {
+        self.oracle_openjdk.iter().filter(|mirror| mirror.enabled)
+    }
+
+    /// 按 id 找 Oracle 镜像（诊断 / `java vendors` 用；停用的也能查到）。
+    #[must_use]
+    pub fn oracle_mirror(&self, id: &str) -> Option<&OracleMirror> {
+        self.oracle_openjdk
+            .iter()
+            .find(|mirror| mirror.id.eq_ignore_ascii_case(id))
+    }
+
+    /// Microsoft OpenJDK 分发表（v2 清单没有 → `None`）。
+    #[must_use]
+    pub fn microsoft_openjdk(&self) -> Option<&MsOpenJdkTable> {
+        self.microsoft_openjdk.as_ref()
+    }
+
+    /// Zulu 元数据表。
+    #[must_use]
+    pub fn zulu(&self) -> Option<&ZuluTable> {
+        self.zulu.as_ref()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::MirrorTable;
+
+    #[test]
+    fn builtin_table_is_v3_with_all_four_source_families() {
+        let table = MirrorTable::builtin();
+        assert_eq!(table.version, 3);
+        // Temurin：只剩 TUNA 一家启用，且带 latest_only 标记。
+        let enabled: Vec<&str> = table
+            .adoptium
+            .iter()
+            .filter(|mirror| mirror.enabled)
+            .map(|mirror| mirror.id.as_str())
+            .collect();
+        assert_eq!(enabled, vec!["tuna"]);
+        assert!(table
+            .adoptium
+            .iter()
+            .filter(|m| m.enabled)
+            .all(|m| m.latest_only));
+        // 停用的登记项要在（将来恢复时不需要重写清单）。
+        for id in ["ustc", "sjtu", "bfsu", "nju", "zju", "163"] {
+            assert!(
+                table.adoptium.iter().any(|mirror| mirror.id == id),
+                "{id} 应登记为 disabled"
+            );
+        }
+        assert!(table.oracle_mirrors().any(|mirror| mirror.id == "huawei"));
+        let microsoft = table.microsoft_openjdk().expect("v3 应带 MS 表");
+        assert_eq!(microsoft.majors, vec![25, 21, 17, 11]);
+        assert!(microsoft.template.contains("{version}"));
+        assert!(microsoft.sha256_template.ends_with(".sha256sum.txt"));
+        let zulu = table.zulu().expect("v3 应带 Zulu 表");
+        assert!(zulu.detail.contains("{uuid}"));
+        assert!(!zulu.size_field_reliable, "Zulu 的 size 字段不可对拍");
+    }
+
+    #[test]
+    fn v2_table_still_parses() {
+        // v2 清单（没有三张新表）必须照常解析，回退链退化为「只有 Temurin」。
+        let v2 = r#"{
+            "version": 2,
+            "adoptium": [
+                { "id": "tuna", "name": "清华 TUNA",
+                  "base": "https://mirrors.tuna.tsinghua.edu.cn/Adoptium", "enabled": true }
+            ],
+            "gh_proxies": [],
+            "rules": []
+        }"#;
+        let table = MirrorTable::parse(v2).expect("v2 应兼容");
+        assert_eq!(table.version, 2);
+        assert_eq!(table.adoptium.len(), 1);
+        assert!(
+            !table.adoptium[0].latest_only,
+            "v2 没有 latest_only → 默认 false"
+        );
+        assert!(table.microsoft_openjdk().is_none());
+        assert!(table.zulu().is_none());
+        assert_eq!(table.oracle_mirrors().count(), 0);
+    }
+}
diff --git a/crates/core/src/download/mirrors.json b/crates/core/src/download/mirrors.json
new file mode 100644
index 0000000..8075108
--- /dev/null
+++ b/crates/core/src/download/mirrors.json
@@ -0,0 +1,169 @@
+{
+  "version": 3,
+  "notes": [
+    "v3（D23/M36）：adoptium 表收敛到清华 TUNA 一家（其余院校实测 404，登记保留但 enabled=false）；新增 oracle_openjdk / microsoft_openjdk / zulu 三张表，供 game::java 的三发行版回退链使用。",
+    "华为云 / 腾讯云 / 阿里云没有 Adoptium 镜像：华为云门户对任意不存在的路径都回 200 + 12KB HTML（假阳性，M34 实测），腾讯云 /v1/source.js 与华为云 /v1/repositories 的权威清单里都没有 JDK 项。据此不再登记 adoptium.huaweicloud。",
+    "oracle_openjdk 的目录与文件名与 download.java.net 完全同构，但 hash 段（f2283984656d49d69e91c558476027ac）不可推导——候选 URL 只能来自对镜像目录页的解析，禁止拼装。",
+    "microsoft_openjdk 没有国内镜像，也没有 GitHub 资产（api.github.com 的 microsoft/openjdk releases 里 assets 全空）；唯一渠道是 aka.ms 模板 301 → download.visualstudio.microsoft.com（国内约 400 KB/s）。",
+    "zulu 的 API size 字段与真实字节数差 133 B，只能用于展示；校验一律用 sha256_hash。"
+  ],
+  "gh_proxies": [
+    {
+      "id": "gh-proxy",
+      "name": "gh-proxy.com",
+      "prefix": "https://gh-proxy.com/",
+      "enabled": true
+    }
+  ],
+  "adoptium": [
+    {
+      "id": "tuna",
+      "name": "清华 TUNA",
+      "base": "https://mirrors.tuna.tsinghua.edu.cn/Adoptium",
+      "enabled": true,
+      "latest_only": true
+    },
+    {
+      "id": "ustc",
+      "name": "中科大 USTC（无 Adoptium 目录树：只有 deb/rpm/releases，实测 404）",
+      "base": "https://mirrors.ustc.edu.cn/adoptium",
+      "enabled": false
+    },
+    {
+      "id": "sjtu",
+      "name": "上交 SJTU（无 Adoptium 目录树，实测 404）",
+      "base": "https://mirror.sjtu.edu.cn/adoptium",
+      "enabled": false
+    },
+    {
+      "id": "bfsu",
+      "name": "北外 BFSU（无 Adoptium 目录树，实测 404）",
+      "base": "https://mirrors.bfsu.edu.cn/Adoptium",
+      "enabled": false
+    },
+    {
+      "id": "nju",
+      "name": "南大 NJU（adoptium 路径实测 404；/openjdk/ 走 oracle_openjdk 表）",
+      "base": "https://mirror.nju.edu.cn/adoptium",
+      "enabled": false
+    },
+    {
+      "id": "zju",
+      "name": "浙大 ZJU（无 Adoptium 目录树，实测 404 搜索页）",
+      "base": "https://mirrors.zju.edu.cn/adoptium",
+      "enabled": false
+    },
+    {
+      "id": "163",
+      "name": "网易 163（无 Adoptium 目录树，实测 404 且 18 秒才回）",
+      "base": "https://mirrors.163.com/adoptium",
+      "enabled": false
+    }
+  ],
+  "oracle_openjdk": [
+    {
+      "id": "huawei",
+      "name": "华为云",
+      "base": "https://mirrors.huaweicloud.com/openjdk",
+      "enabled": true,
+      "speed": "11.5MB/s",
+      "note": "逐字节忠实镜像（21.0.2 = 201328186 B 与官方一致）；目录页是 Apache 列表，带 <pre>；归档旁有 .sha256"
+    },
+    {
+      "id": "nju",
+      "name": "南大 NJU",
+      "base": "https://mirror.nju.edu.cn/openjdk",
+      "enabled": true,
+      "speed": "8.3MB/s",
+      "note": "需先吃一次 bcheck cookie（裸 GET 是 302 回自己）；健康度会把它排在华为云之后，失败即降级"
+    }
+  ],
+  "microsoft_openjdk": {
+    "list": "https://learn.microsoft.com/java/openjdk/download",
+    "template": "https://aka.ms/download-jdk/microsoft-jdk-{version}-{os}-{arch}.zip",
+    "sha256_template": "https://aka.ms/download-jdk/microsoft-jdk-{version}-{os}-{arch}.zip.sha256sum.txt",
+    "majors": [25, 21, 17, 11],
+    "domestic_mirrors": [],
+    "measured_speed": "398KB/s"
+  },
+  "zulu": {
+    "api": "https://api.azul.com/metadata/v1/zulu/packages/",
+    "detail": "https://api.azul.com/metadata/v1/zulu/packages/{uuid}",
+    "cdn_host": "cdn.azul.com",
+    "measured_speed": "3.3MB/s",
+    "size_field_reliable": false
+  },
+  "rules": [
+    {
+      "id": "bmclapi-launchermeta",
+      "from": "https://launchermeta.mojang.com",
+      "to": "https://bmclapi2.bangbang93.com"
+    },
+    {
+      "id": "bmclapi-piston-meta",
+      "from": "https://piston-meta.mojang.com",
+      "to": "https://bmclapi2.bangbang93.com"
+    },
+    {
+      "id": "bmclapi-piston-data",
+      "from": "https://piston-data.mojang.com",
+      "to": "https://bmclapi2.bangbang93.com"
+    },
+    {
+      "id": "bmclapi-launcher",
+      "from": "https://launcher.mojang.com",
+      "to": "https://bmclapi2.bangbang93.com"
+    },
+    {
+      "id": "bmclapi-libraries",
+      "from": "https://libraries.minecraft.net",
+      "to": "https://bmclapi2.bangbang93.com"
+    },
+    {
+      "id": "bmclapi-assets-objects",
+      "from": "https://resources.download.minecraft.net",
+      "to": "https://bmclapi2.bangbang93.com",
+      "inject": "/assets"
+    },
+    {
+      "id": "bmclapi-forge-maven",
+      "from": "https://files.minecraftforge.net/maven",
+      "to": "https://bmclapi2.bangbang93.com/maven"
+    },
+    {
+      "id": "bmclapi-forge-maven-net",
+      "from": "https://maven.minecraftforge.net",
+      "to": "https://bmclapi2.bangbang93.com/maven"
+    },
+    {
+      "id": "bmclapi-neoforge",
+      "from": "https://maven.neoforged.net/releases",
+      "to": "https://bmclapi2.bangbang93.com/maven"
+    },
+    {
+      "id": "bmclapi-fabric-meta",
+      "from": "https://meta.fabricmc.net",
+      "to": "https://bmclapi2.bangbang93.com/fabric-meta"
+    },
+    {
+      "id": "bmclapi-fabric-maven",
+      "from": "https://maven.fabricmc.net",
+      "to": "https://bmclapi2.bangbang93.com/maven"
+    },
+    {
+      "id": "bmclapi-quilt-meta",
+      "from": "https://meta.quiltmc.org",
+      "to": "https://bmclapi2.bangbang93.com/quilt-meta"
+    },
+    {
+      "id": "bmclapi-liteloader",
+      "from": "https://dl.liteloader.com/versions",
+      "to": "https://bmclapi2.bangbang93.com/maven"
+    },
+    {
+      "id": "bmclapi-authlib-injector",
+      "from": "https://authlib-injector.yushi.moe",
+      "to": "https://bmclapi2.bangbang93.com/mirrors/authlib-injector"
+    }
+  ]
+}
diff --git a/crates/core/src/download/mirrors.rs b/crates/core/src/download/mirrors.rs
new file mode 100644
index 0000000..e16b6cb
--- /dev/null
+++ b/crates/core/src/download/mirrors.rs
@@ -0,0 +1,386 @@
+//! 镜像清单与 URL 前缀重写。
+//!
+//! 内置清单 `mirrors.json` 随源码嵌入（`include_str!`），发行后可由设置层追加自定义规则。
+//! 重写语义承 analyse/03 §5.2 的「前缀替换而非全量重写」——保留子路径，因此 `/libraries`、
+//! `/maven`、`/fabric-meta` 这类子路径天然兼容；`inject` 用于补上路径形状不同的场景
+//! （资源对象：官方 `<xx>/<hash>`，BMCLAPI `/assets/<xx>/<hash>`）。
+//!
+//! gh-proxy 规则（用户定案）：**只有国内模式 + GitHub host** 才套前缀，其它资源不受影响。
+
+use serde::{Deserialize, Serialize};
+
+pub use super::adoptium::AdoptiumMirror;
+use super::jdk_sources::{MsOpenJdkTable, OracleMirror, ZuluTable};
+use super::region::{RegionMode, RegionProfile};
+use super::types::{Candidate, ResourceKind, SOURCE_OFFICIAL};
+
+/// gh-proxy 候选的源标识。
+pub const SOURCE_GH_PROXY: &str = "gh_proxy";
+
+const fn default_true() -> bool {
+    true
+}
+
+/// 一条前缀重写规则。
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PrefixRule {
+    /// 规则 id（日志/诊断用）。
+    pub id: String,
+    /// 匹配的 URL 前缀（含 scheme）。
+    pub from: String,
+    /// 替换成的前缀。
+    pub to: String,
+    /// 插在 `to` 与剩余路径之间的内容（默认空）。
+    #[serde(default)]
+    pub inject: String,
+    /// 「仅加速不替代」：镜像优先模式下仍排在官方之后。
+    #[serde(default)]
+    pub fallback: bool,
+    /// 只对这些资源类型生效（空 = 全部）。
+    #[serde(default)]
+    pub kinds: Vec<ResourceKind>,
+    /// 是否启用（设置层可关）。
+    #[serde(default = "default_true")]
+    pub enabled: bool,
+}
+
+impl PrefixRule {
+    /// 构造一条最简规则。
+    #[must_use]
+    pub fn new(id: impl Into<String>, from: impl Into<String>, to: impl Into<String>) -> Self {
+        Self {
+            id: id.into(),
+            from: from.into(),
+            to: to.into(),
+            inject: String::new(),
+            fallback: false,
+            kinds: Vec::new(),
+            enabled: true,
+        }
+    }
+
+    /// 设一个「仅加速」标记。
+    #[must_use]
+    pub fn fallback(mut self) -> Self {
+        self.fallback = true;
+        self
+    }
+
+    /// 设置注入片段。
+    #[must_use]
+    pub fn with_inject(mut self, inject: impl Into<String>) -> Self {
+        self.inject = inject.into();
+        self
+    }
+
+    /// 是否命中该 URL（前缀匹配 + 资源类型过滤 + 启用位）。
+    #[must_use]
+    pub fn matches(&self, url: &str, kind: ResourceKind) -> bool {
+        self.enabled
+            && url.starts_with(&self.from)
+            && (self.kinds.is_empty() || self.kinds.contains(&kind))
+    }
+
+    /// 生成镜像候选。
+    #[must_use]
+    pub fn apply(&self, url: &str) -> Option<Candidate> {
+        if !url.starts_with(&self.from) {
+            return None;
+        }
+        let rest = &url[self.from.len()..];
+        let rewritten = format!("{}{}{}", self.to, self.inject, rest);
+        Some(Candidate::new(source_id_for(&rewritten), rewritten))
+    }
+}
+
+/// 一个 gh-proxy 类前缀。
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct GhProxy {
+    /// 源标识。
+    pub id: String,
+    /// 展示名。
+    pub name: String,
+    /// 前缀（形如 `https://gh-proxy.com/`）。
+    pub prefix: String,
+    /// 是否启用。
+    #[serde(default = "default_true")]
+    pub enabled: bool,
+}
+
+/// 镜像表：内置规则 + 用户自定义规则。
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MirrorTable {
+    /// 清单版本（便于诊断页显示「镜像表是哪一版」）。
+    pub version: u32,
+    /// 清单自带的说明（假阳性成因、不可推导项等，给运维看的原地注释）。
+    #[serde(default)]
+    pub notes: Vec<String>,
+    /// 前缀重写规则（前面的优先）。
+    #[serde(default)]
+    pub rules: Vec<PrefixRule>,
+    /// Adoptium 院校镜像。
+    #[serde(default)]
+    pub adoptium: Vec<AdoptiumMirror>,
+    /// Oracle OpenJDK 镜像（v3 新增）。
+    #[serde(default)]
+    pub oracle_openjdk: Vec<OracleMirror>,
+    /// Microsoft OpenJDK 分发模板（v3 新增）。
+    #[serde(default)]
+    pub microsoft_openjdk: Option<MsOpenJdkTable>,
+    /// Zulu 元数据（v3 新增）。
+    #[serde(default)]
+    pub zulu: Option<ZuluTable>,
+    /// gh-proxy 类前缀。
+    #[serde(default)]
+    pub gh_proxies: Vec<GhProxy>,
+}
+
+impl Default for MirrorTable {
+    fn default() -> Self {
+        Self::builtin()
+    }
+}
+
+impl MirrorTable {
+    /// 内置清单（编译期嵌入）。
+    #[must_use]
+    pub fn builtin() -> Self {
+        Self::parse(include_str!("mirrors.json")).unwrap_or_else(|err| {
+            debug_note(&format!("内置 mirrors.json 解析失败（不应发生）：{err}"));
+            Self {
+                version: 0,
+                notes: Vec::new(),
+                rules: Vec::new(),
+                adoptium: Vec::new(),
+                oracle_openjdk: Vec::new(),
+                microsoft_openjdk: None,
+                zulu: None,
+                gh_proxies: Vec::new(),
+            }
+        })
+    }
+
+    /// 从 JSON 解析。
+    pub fn parse(json: &str) -> Result<Self, serde_json::Error> {
+        serde_json::from_str(json)
+    }
+
+    /// 序列化成 JSON（诊断页/用户自定义文件回写用）。
+    pub fn to_json_pretty(&self) -> Result<String, serde_json::Error> {
+        serde_json::to_string_pretty(self)
+    }
+
+    /// 追加用户自定义规则（插到最前，优先于内置规则）。
+    pub fn add_custom_rule(&mut self, rule: PrefixRule) {
+        self.rules.insert(0, rule);
+    }
+
+    /// 覆盖 gh-proxy 前缀（设置项）；传 `None` 表示不默认启用。
+    pub fn set_gh_proxy(&mut self, prefix: Option<&str>) {
+        match prefix {
+            Some(prefix) => {
+                if let Some(proxy) = self.gh_proxies.first_mut() {
+                    proxy.prefix = prefix.to_string();
+                    proxy.enabled = true;
+                } else {
+                    self.gh_proxies.push(GhProxy {
+                        id: "gh-proxy".to_string(),
+                        name: "自定义 gh-proxy".to_string(),
+                        prefix: prefix.to_string(),
+                        enabled: true,
+                    });
+                }
+            }
+            None => {
+                for proxy in &mut self.gh_proxies {
+                    proxy.enabled = false;
+                }
+            }
+        }
+    }
+
+    /// 找到第一条命中的前缀规则。
+    #[must_use]
+    pub fn prefix_rule_for(&self, url: &str, kind: ResourceKind) -> Option<&PrefixRule> {
+        self.rules.iter().find(|rule| rule.matches(url, kind))
+    }
+
+    /// 清单里第一个启用的 gh-proxy 前缀（默认值来源；设置层用它初始化地区档案）。
+    #[must_use]
+    pub fn default_gh_proxy(&self) -> Option<&str> {
+        self.gh_proxies
+            .iter()
+            .find(|proxy| proxy.enabled && !proxy.prefix.is_empty())
+            .map(|proxy| proxy.prefix.as_str())
+    }
+
+    /// GitHub host 且允许时套 gh-proxy 前缀。
+    ///
+    /// **生效前缀的唯一真相源是 `region.gh_proxy`**（设置层/地区判定写入，`None` = 用户关闭）。
+    /// 表格里的 `gh_proxies` 只是「已知可用前缀」清单，配合 `default_gh_proxy()` 给设置做默认值。
+    #[must_use]
+    pub fn gh_proxy_candidates(&self, url: &str, region: &RegionProfile) -> Vec<Candidate> {
+        if region.mode != RegionMode::MirrorFirst {
+            return Vec::new();
+        }
+        let Some(prefix) = region
+            .gh_proxy
+            .as_deref()
+            .map(str::trim)
+            .filter(|prefix| !prefix.is_empty())
+        else {
+            return Vec::new();
+        };
+        let Some(host) = host_of(url) else {
+            return Vec::new();
+        };
+        if !is_github_host(host) {
+            return Vec::new();
+        }
+        vec![Candidate::new(SOURCE_GH_PROXY, format!("{prefix}{url}"))]
+    }
+
+    /// 展开候选序列：镜像优先模式下镜像在前、官方兜底；直连模式下官方在前、镜像兜底。
+    #[must_use]
+    pub fn expand(&self, url: &str, kind: ResourceKind, region: &RegionProfile) -> Vec<Candidate> {
+        let official = Candidate::new(direct_source_id(url), url);
+        let mut mirrors: Vec<Candidate> = Vec::new();
+        let mut official_first = false;
+
+        for candidate in self.adoptium_candidates(url) {
+            push_unique(&mut mirrors, url, candidate);
+        }
+        if let Some(rule) = self.prefix_rule_for(url, kind) {
+            if let Some(candidate) = rule.apply(url) {
+                // 「仅加速不替代」的规则在镜像优先模式下也排官方之后。
+                official_first = rule.fallback;
+                push_unique(&mut mirrors, url, candidate);
+            }
+        }
+        for candidate in self.gh_proxy_candidates(url, region) {
+            push_unique(&mut mirrors, url, candidate);
+        }
+
+        if region.mode == RegionMode::MirrorFirst && !official_first {
+            mirrors.push(official);
+            mirrors
+        } else {
+            let mut out = Vec::with_capacity(mirrors.len() + 1);
+            out.push(official);
+            out.append(&mut mirrors);
+            out
+        }
+    }
+}
+
+fn push_unique(list: &mut Vec<Candidate>, official_url: &str, candidate: Candidate) {
+    if candidate.url == official_url || list.iter().any(|known| known.url == candidate.url) {
+        return;
+    }
+    list.push(candidate);
+}
+
+/// 直连候选的源标识。
+///
+/// 绝大多数资源是 Mojang/CDN 的「官方源」，标 `official`；但 JDK 的四家发行版里，
+/// Oracle（国内镜像）/ MS（VS CDN）/ Zulu（Azul CDN）的**直连 URL 本身就是某个厂商的 CDN**，
+/// 标成 `official` 会让用户和健康度记忆都看错（「来源 official」其实来自华为云）。
+/// 所以：认得的厂商/镜像 host 用它的稳定 id，其余一律 `official`。
+#[must_use]
+pub fn direct_source_id(url: &str) -> String {
+    let id = source_id_for(url);
+    if MIRROR_SOURCE_IDS.contains(&id.as_str()) {
+        id
+    } else {
+        SOURCE_OFFICIAL.to_string()
+    }
+}
+
+/// 会被 `direct_source_id` 认出来的厂商/镜像源 id（都是「非官方 CDN/镜像」那一类）。
+pub const MIRROR_SOURCE_IDS: &[&str] = &[
+    "bmclapi",
+    "tuna",
+    "ustc",
+    "sjtu",
+    "bfsu",
+    "nju",
+    "huawei",
+    "azul",
+    "microsoft",
+    SOURCE_GH_PROXY,
+];
+
+/// 从 URL 里抠出 host（无 `url` 依赖）。
+#[must_use]
+pub fn host_of(url: &str) -> Option<&str> {
+    let rest = url.split_once("://").map_or(url, |(_, rest)| rest);
+    let authority = rest.split(['/', '?', '#']).next()?;
+    let host_port = authority.rsplit('@').next()?;
+    let host = host_port.split(':').next()?;
+    if host.is_empty() {
+        None
+    } else {
+        Some(host)
+    }
+}
+
+/// 是否是 GitHub 系 host（gh-proxy 只对这些套前缀）。
+#[must_use]
+pub fn is_github_host(host: &str) -> bool {
+    matches!(
+        host,
+        "github.com"
+            | "raw.githubusercontent.com"
+            | "objects.githubusercontent.com"
+            | "codeload.github.com"
+            | "gist.github.com"
+            | "gist.githubusercontent.com"
+    ) || host.ends_with(".githubusercontent.com")
+}
+
+/// URL 的源标识（健康度按此归并；不知名 host 直接用 host）。
+#[must_use]
+pub fn source_id_for(url: &str) -> String {
+    let Some(host) = host_of(url) else {
+        return SOURCE_OFFICIAL.to_string();
+    };
+    if host.ends_with("bangbang93.com") {
+        return "bmclapi".to_string();
+    }
+    if host.contains("tuna.tsinghua.edu.cn") {
+        return "tuna".to_string();
+    }
+    if host.contains("ustc.edu.cn") {
+        return "ustc".to_string();
+    }
+    if host.contains("sjtu.edu.cn") {
+        return "sjtu".to_string();
+    }
+    if host.contains("bfsu.edu.cn") {
+        return "bfsu".to_string();
+    }
+    if host.contains("nju.edu.cn") {
+        return "nju".to_string();
+    }
+    if host.contains("huaweicloud.com") {
+        return "huawei".to_string();
+    }
+    if host.contains("azul.com") {
+        return "azul".to_string();
+    }
+    if host.contains("visualstudio.microsoft.com") || host == "aka.ms" {
+        return "microsoft".to_string();
+    }
+    if host.contains("gh-proxy") {
+        return SOURCE_GH_PROXY.to_string();
+    }
+    host.to_string()
+}
+
+fn debug_note(message: &str) {
+    if cfg!(debug_assertions) {
+        eprintln!("[ull::download] {message}");
+    } else {
+        let _ = message;
+    }
+}
diff --git a/crates/core/src/download/mod.rs b/crates/core/src/download/mod.rs
new file mode 100644
index 0000000..a66155a
--- /dev/null
+++ b/crates/core/src/download/mod.rs
@@ -0,0 +1,90 @@
+//! 下载引擎：多源健康度、指数退避、分层下载（大文件分块）、边下边算、原子落盘。
+//!
+//! 设计定稿：`DevDocs/PlanDoc/05-download-and-mirrors.md`（决策 D7）。
+//! 镜像清单随更新可刷新（BMCLAPI / TUNA / USTC / SJTU / gh-proxy），
+//! 地区自动判定 = 时区 + 语言 + 网络探测组合信号，可手动覆盖。
+//!
+//! 与其它模块的契约：`DownloadRequest` / 进度事件的类型需与 game、agent 对齐
+//! （`DevDocs/SubAgentsTalk/README.md` 的对齐点）。
+//!
+//! # 公共面
+//!
+//! 调用方只需要三件套：构造 [`DownloadRequest`] → [`DownloadEngine::download`] →
+//! 消费 [`ProgressEvent`]。「用哪个镜像、要不要续传、开几条连接、失败重试几次」
+//! 全部由引擎内部决定，调用方既不拼镜像 URL 也不写重试循环。
+//!
+//! 其余构件（镜像表 / 地区档案 / 健康度 / 内容寻址缓存 / 续传元数据）都作为
+//! 可注入对象暴露出来：设置层要把它们接进 schema，诊断页要直接读它们的状态，
+//! 测试要能把它们换成确定性的假件。
+//!
+//! # 分层
+//!
+//! ```text
+//! engine        编排：缓存直取 → 候选规划 → 限流 → 候选外循环 / 退避内循环
+//! transfer      单连接尝试（续传 + 流式校验）
+//! transfer_chunk 多连接分块编排
+//! chunked       分块规划 / Range 语义 / 单块抓取
+//! mirrors       镜像清单 + URL 前缀重写      adoptium  JDK 院校镜像
+//! region        时区 + 语言 + 探测 → 直连/镜像优先
+//! health        源 × 资源类型的健康度记忆
+//! cache         内容寻址缓存（记录信任）      atomic    落盘守卫 / 原子写
+//! resume        保守续传判定                  verify    流式摘要
+//! progress      事件流                        error     错误分类
+//! ```
+//!
+//! 落盘守卫（[`PartFile`]）中间文件名是 `<name>.ullpart-<session>-<seq>`：`session` 是
+//! 进程号，`seq` 是进程内序号。同一数据根跑两个启动器进程时不会互相搬走对方的中间文件
+//! （M35 真机：并行两次 `ull install` 各失败数百个资源，`os error 2`）；旧续传材料由
+//! `PartFile::for_dest` 收养，单进程语义不变。
+//!
+//! 依赖纪律：本模块只用 `reqwest` / `tokio` / `futures-util` / `sha1` / `sha2` /
+//! `serde` / `serde_json`，不触碰任何 UI 框架（`crates/core` 的硬约束）。
+
+// 对外可用的构件（设置层 / 诊断页 / 其它模块直接消费）。
+pub mod adoptium;
+pub mod backoff;
+pub mod blocking;
+pub mod cache;
+pub mod chunked;
+pub mod config;
+pub mod engine;
+pub mod error;
+pub mod health;
+pub mod jdk_sources;
+pub mod mirrors;
+pub mod progress;
+pub mod region;
+pub mod region_system;
+pub mod resume;
+pub mod types;
+pub mod verify;
+
+// 内部实现细节：只在 download 模块内（含 crate 内）可见，不承诺兼容性。
+pub(crate) mod atomic;
+pub(crate) mod bytes;
+pub(crate) mod health_store;
+pub(crate) mod http;
+pub(crate) mod transfer;
+pub(crate) mod transfer_chunk;
+
+pub use self::adoptium::{AdoptiumArtifact, JdkFlavor};
+pub use self::atomic::{PartFile, ADOPT_MIN_AGE, META_SUFFIX, ORPHAN_MAX_AGE, PART_SUFFIX};
+pub use self::backoff::{BackoffPolicy, Jitter};
+pub use self::blocking::block_on;
+pub use self::cache::{CacheRecord, CacheStats, ContentCache};
+pub use self::chunked::{ByteRange, ChunkedConfig, RangeSupport};
+pub use self::config::EngineConfig;
+pub use self::engine::DownloadEngine;
+pub use self::error::{DownloadError, DownloadErrorKind};
+pub use self::health::{HealthKey, HealthRegistry, SourceHealth};
+pub use self::jdk_sources::{MsOpenJdkTable, OracleMirror, ZuluTable};
+pub use self::mirrors::{direct_source_id, AdoptiumMirror, GhProxy, MirrorTable, PrefixRule};
+pub use self::progress::{ProgressEmitter, ProgressEvent, ProgressThrottle};
+pub use self::region::{RegionMode, RegionProfile, RegionTrigger, Signals};
+pub use self::region_system::detect_signals;
+pub use self::resume::{RestartReason, ResumeDecision, ResumeMeta};
+pub use self::types::{
+    Candidate, DownloadId, DownloadOutcome, DownloadRequest, HashAlgo, Integrity, ResourceKind,
+    ResumePolicy, SOURCE_OFFICIAL,
+};
+pub use self::verify::Hasher;
diff --git a/crates/core/src/download/progress.rs b/crates/core/src/download/progress.rs
new file mode 100644
index 0000000..4dea5f0
--- /dev/null
+++ b/crates/core/src/download/progress.rs
@@ -0,0 +1,197 @@
+//! 进度事件与发射器。
+//!
+//! 事件是「字节级 + 文件级」双层的载体（设计文档 §5）：文件级由 `Started/Completed/Failed`
+//! 表达，字节级由节流后的 `Progress` 表达。`total_bytes` 未知时给 `None`——不做假进度。
+
+use std::time::{Duration, Instant};
+
+use serde::{Deserialize, Serialize};
+use tokio::sync::mpsc::{self, UnboundedReceiver, UnboundedSender};
+
+use super::error::DownloadErrorKind;
+use super::types::{DownloadId, HashAlgo, ResourceKind};
+
+/// 一条下载进度事件。
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "event", rename_all = "snake_case")]
+pub enum ProgressEvent {
+    /// 开始一次下载（含候选数量与总字节预算）。
+    Started {
+        /// 关联 id。
+        id: DownloadId,
+        /// 资源类型。
+        kind: ResourceKind,
+        /// 逻辑 URL。
+        url: String,
+        /// 落盘路径。
+        dest: String,
+        /// 候选源数量。
+        candidates: usize,
+        /// 总字节数（未知为 `None`）。
+        total_bytes: Option<u64>,
+    },
+    /// 字节级进度（节流后）。
+    Progress {
+        /// 关联 id。
+        id: DownloadId,
+        /// 已下载字节。
+        downloaded: u64,
+        /// 总字节数（未知为 `None`）。
+        total_bytes: Option<u64>,
+    },
+    /// 某个源失败（单次尝试）。
+    SourceFailed {
+        /// 关联 id。
+        id: DownloadId,
+        /// 源标识。
+        source: String,
+        /// 失败原因（短描述）。
+        reason: String,
+        /// 第几次尝试（从 0 起）。
+        attempt: u32,
+        /// 是否还会在同源重试。
+        will_retry: bool,
+        /// 下次重试的等待毫秒数。
+        retry_in_ms: u64,
+    },
+    /// 切换到下一个候选源。
+    SourceSwitched {
+        /// 关联 id。
+        id: DownloadId,
+        /// 原源。
+        from: String,
+        /// 新源。
+        to: String,
+    },
+    /// 进入校验阶段。
+    Verifying {
+        /// 关联 id。
+        id: DownloadId,
+        /// 算法。
+        algo: HashAlgo,
+        /// 期望摘要前缀（8 位，够定位又不太啰嗦）。
+        expected_prefix: String,
+    },
+    /// 下载成功。
+    Completed {
+        /// 关联 id。
+        id: DownloadId,
+        /// 字节数。
+        bytes: u64,
+        /// 是否命中内容寻址缓存。
+        from_cache: bool,
+        /// 成功的源。
+        source: String,
+        /// 耗时毫秒。
+        elapsed_ms: u64,
+    },
+    /// 下载失败（所有候选源都失败或不可重试）。
+    Failed {
+        /// 关联 id。
+        id: DownloadId,
+        /// 错误分类。
+        kind: DownloadErrorKind,
+        /// 错误描述。
+        message: String,
+    },
+}
+
+impl ProgressEvent {
+    /// 事件归属的下载 id。
+    #[must_use]
+    pub const fn id(&self) -> DownloadId {
+        match self {
+            Self::Started { id, .. }
+            | Self::Progress { id, .. }
+            | Self::SourceFailed { id, .. }
+            | Self::SourceSwitched { id, .. }
+            | Self::Verifying { id, .. }
+            | Self::Completed { id, .. }
+            | Self::Failed { id, .. } => *id,
+        }
+    }
+}
+
+/// 进度发射器：没有接收端时退化为空操作（core 不关心谁在听）。
+#[derive(Debug, Clone, Default)]
+pub struct ProgressEmitter {
+    tx: Option<UnboundedSender<ProgressEvent>>,
+}
+
+impl ProgressEmitter {
+    /// 静默发射器（测试、后台静默下载用）。
+    #[must_use]
+    pub const fn silent() -> Self {
+        Self { tx: None }
+    }
+
+    /// 建一对（发射器, 接收端）；接收端由 app 层转成 IPC DTO。
+    #[must_use]
+    pub fn channel() -> (Self, UnboundedReceiver<ProgressEvent>) {
+        let (tx, rx) = mpsc::unbounded_channel();
+        (Self { tx: Some(tx) }, rx)
+    }
+
+    /// 发一条事件；接收端已关闭则静默丢弃。
+    pub fn emit(&self, event: ProgressEvent) {
+        if let Some(tx) = &self.tx {
+            let _ = tx.send(event);
+        }
+    }
+
+    /// 是否没有接收端。
+    #[must_use]
+    pub const fn is_silent(&self) -> bool {
+        self.tx.is_none()
+    }
+}
+
+/// 进度节流器：距上次发射不足 `interval` 且未完成时压掉本次事件。
+#[derive(Debug, Clone)]
+pub struct ProgressThrottle {
+    interval: Duration,
+    last_emit: Option<Instant>,
+}
+
+impl ProgressThrottle {
+    /// 构造节流器。
+    #[must_use]
+    pub const fn new(interval: Duration) -> Self {
+        Self {
+            interval,
+            last_emit: None,
+        }
+    }
+
+    /// 节流间隔。
+    #[must_use]
+    pub const fn interval(&self) -> Duration {
+        self.interval
+    }
+
+    /// 是否应该发射本次进度（`finished = true` 时无条件放行）。
+    pub fn should_emit(&mut self, now: Instant, finished: bool) -> bool {
+        if finished {
+            self.last_emit = Some(now);
+            return true;
+        }
+        match self.last_emit {
+            Some(last) if now.duration_since(last) < self.interval => false,
+            _ => {
+                self.last_emit = Some(now);
+                true
+            }
+        }
+    }
+
+    /// 复位（换源/重试时重新计时）。
+    pub fn reset(&mut self) {
+        self.last_emit = None;
+    }
+}
+
+impl Default for ProgressThrottle {
+    fn default() -> Self {
+        Self::new(Duration::from_millis(250))
+    }
+}
diff --git a/crates/core/src/download/region.rs b/crates/core/src/download/region.rs
new file mode 100644
index 0000000..5dc7c09
--- /dev/null
+++ b/crates/core/src/download/region.rs
@@ -0,0 +1,343 @@
+//! 地区自动判定：时区 + 系统语言 + 网络探测 → 直连 / 镜像优先。
+//!
+//! 设计文档 05 §3.2（用户 Q19 定案）：
+//!
+//! * 信号①时区 ∈ 大中华区列表，或 信号②系统语言 zh-* → 「大中华区候选」；
+//! * 信号③网络探测（google/baidu，各 3s 超时，结果缓存 24h，可关）；
+//! * 判定：大中华区 && google 不可达 → **镜像优先**（并启用 gh-proxy）；
+//!   google 可达（已有全局代理）→ **直连**（尊重用户代理）；非大中华区 → 直连；
+//! * 探测被关闭时，中文环境默认镜像优先（用户拍板的默认值）。
+//!
+//! 判定结果可由用户在设置里钉死（`RegionTrigger::UserPinned`），此时不参与自动重判。
+
+use std::path::Path;
+use std::time::Duration;
+
+use serde::{Deserialize, Serialize};
+
+use super::atomic::write_atomic;
+
+/// 大中华区时区（IANA 名）。
+pub const GREATER_CHINA_TIMEZONES: &[&str] = &[
+    "Asia/Shanghai",
+    "Asia/Urumqi",
+    "Asia/Chongqing",
+    "Asia/Harbin",
+    "Asia/Hong_Kong",
+    "Asia/Macau",
+    "Asia/Taipei",
+];
+
+/// 中文语言前缀（大小写不敏感的前缀匹配）。
+pub const GREATER_CHINA_LANGUAGE_PREFIXES: &[&str] = &["zh", "wuu", "yue", "lzh"];
+
+/// 默认 gh-proxy 前缀（2026-10 实测可用；设置可改，`None` 表示不默认启用）。
+pub const DEFAULT_GH_PROXY: &str = "https://gh-proxy.com/";
+
+/// 探测超时（设计文档定死 3s）。
+pub const PROBE_TIMEOUT: Duration = Duration::from_secs(3);
+
+/// 自动判定的有效期（24h）。
+pub const DECISION_TTL_MS: u64 = 24 * 60 * 60 * 1000;
+
+/// google 可达性探测点（204 短响应）。
+pub const GOOGLE_PROBE_URL: &str = "https://www.gstatic.com/generate_204";
+
+/// 百度可达性探测点。
+pub const BAIDU_PROBE_URL: &str = "https://www.baidu.com/robots.txt";
+
+/// 源选择模式。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum RegionMode {
+    /// 直连：官方在前，镜像只做兜底。
+    Direct,
+    /// 镜像优先：镜像在前，官方兜底；GitHub 资源套 gh-proxy。
+    MirrorFirst,
+}
+
+impl RegionMode {
+    /// 稳定字符串 id。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Direct => "direct",
+            Self::MirrorFirst => "mirror_first",
+        }
+    }
+}
+
+/// 判定来源：自动 or 用户钉死。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum RegionTrigger {
+    /// 自动判定（24h 后可重判）。
+    Auto,
+    /// 用户手动钉死（不参与自动重判）。
+    UserPinned,
+}
+
+/// 地区档案：引擎唯一需要知道的「用哪套源顺序」。
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct RegionProfile {
+    /// 直连 / 镜像优先。
+    pub mode: RegionMode,
+    /// 判定来源。
+    pub trigger: RegionTrigger,
+    /// 是否落在「大中华区候选」。
+    pub greater_china: bool,
+    /// gh-proxy 前缀（`None` = 不启用）。
+    pub gh_proxy: Option<String>,
+    /// 是否做过网络探测（设置里可关）。
+    pub probes_enabled: bool,
+    /// 判定时间（unix 毫秒）。
+    pub decided_at_ms: u64,
+}
+
+impl Default for RegionProfile {
+    fn default() -> Self {
+        Self::direct(0)
+    }
+}
+
+impl RegionProfile {
+    /// 显式直连。
+    #[must_use]
+    pub fn direct(now_ms: u64) -> Self {
+        Self {
+            mode: RegionMode::Direct,
+            trigger: RegionTrigger::Auto,
+            greater_china: false,
+            gh_proxy: None,
+            probes_enabled: false,
+            decided_at_ms: now_ms,
+        }
+    }
+
+    /// 镜像优先（并启用默认 gh-proxy）。
+    #[must_use]
+    pub fn mirror_first(now_ms: u64) -> Self {
+        Self {
+            mode: RegionMode::MirrorFirst,
+            trigger: RegionTrigger::Auto,
+            greater_china: true,
+            gh_proxy: Some(DEFAULT_GH_PROXY.to_string()),
+            probes_enabled: false,
+            decided_at_ms: now_ms,
+        }
+    }
+
+    /// 用户钉死某个模式（设置页「直连 / 镜像优先」）。
+    #[must_use]
+    pub fn pinned(mode: RegionMode, now_ms: u64) -> Self {
+        let mut profile = match mode {
+            RegionMode::Direct => Self::direct(now_ms),
+            RegionMode::MirrorFirst => Self::mirror_first(now_ms),
+        };
+        profile.trigger = RegionTrigger::UserPinned;
+        profile
+    }
+
+    /// gh-proxy 是否真的会生效（镜像优先 + 配了前缀）。
+    #[must_use]
+    pub fn gh_proxy_enabled(&self) -> bool {
+        self.mode == RegionMode::MirrorFirst
+            && self
+                .gh_proxy
+                .as_deref()
+                .is_some_and(|prefix| !prefix.is_empty())
+    }
+
+    /// 是否按「国内」口径选源（镜像优先，或判定落在大中华区）。
+    ///
+    /// 给 JDK 发行版默认优先级用（D23：国内 Temurin→Oracle→MS，国外 Temurin→MS→Oracle）：
+    /// 用户把模式钉成直连但机器仍在国内时，仍然应该吃国内镜像更快的那个顺序。
+    #[must_use]
+    pub fn is_domestic(&self) -> bool {
+        self.mode == RegionMode::MirrorFirst || self.greater_china
+    }
+
+    /// 覆盖 gh-proxy 前缀。
+    #[must_use]
+    pub fn with_gh_proxy(mut self, prefix: Option<&str>) -> Self {
+        self.gh_proxy = prefix
+            .map(str::trim)
+            .filter(|prefix| !prefix.is_empty())
+            .map(str::to_string);
+        self
+    }
+
+    /// 标记是否允许网络探测。
+    #[must_use]
+    pub fn with_probes(mut self, enabled: bool) -> Self {
+        self.probes_enabled = enabled;
+        self
+    }
+
+    /// 自动判定是否已过期（用户钉死永不过期）。
+    #[must_use]
+    pub fn is_stale(&self, now_ms: u64) -> bool {
+        self.trigger == RegionTrigger::Auto
+            && now_ms.saturating_sub(self.decided_at_ms) > DECISION_TTL_MS
+    }
+
+    /// 设置页展示用的中文标签。
+    #[must_use]
+    pub const fn label(&self) -> &'static str {
+        match self.mode {
+            RegionMode::Direct => "直连",
+            RegionMode::MirrorFirst => "镜像优先",
+        }
+    }
+}
+
+/// 判定输入信号。`None` 表示「未知/未探测」。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct Signals {
+    /// 时区名（IANA）。
+    pub timezone: Option<String>,
+    /// 系统语言列表（BCP-47 或 POSIX locale，取首个非空即可）。
+    pub languages: Vec<String>,
+    /// google 可达性（`None` = 未探测/探测被关）。
+    pub google_reachable: Option<bool>,
+    /// baidu 可达性（诊断信息，暂不参与判定）。
+    pub baidu_reachable: Option<bool>,
+}
+
+impl Signals {
+    /// 从环境变量读（尽力而为：Windows 上通常没有 `TZ`，此时由 platform 层补精确值）。
+    #[must_use]
+    pub fn from_env() -> Self {
+        let timezone = std::env::var("TZ").ok().filter(|tz| !tz.trim().is_empty());
+        let mut languages = Vec::new();
+        for key in ["LC_ALL", "LC_MESSAGES", "LANG", "LANGUAGE"] {
+            if let Ok(value) = std::env::var(key) {
+                for part in value.split([':', ';']) {
+                    let part = part.trim();
+                    if !part.is_empty() && !languages.iter().any(|known: &String| known == part) {
+                        languages.push(part.to_string());
+                    }
+                }
+            }
+        }
+        Self {
+            timezone,
+            languages,
+            google_reachable: None,
+            baidu_reachable: None,
+        }
+    }
+
+    /// 时区是否落在大中华区。
+    #[must_use]
+    pub fn timezone_in_greater_china(&self) -> bool {
+        self.timezone.as_deref().is_some_and(|tz| {
+            GREATER_CHINA_TIMEZONES
+                .iter()
+                .any(|known| known.eq_ignore_ascii_case(tz.trim()))
+        })
+    }
+
+    /// 系统语言是否是中文（含 `zh_CN.UTF-8` 这类 POSIX 形态）。
+    #[must_use]
+    pub fn language_in_greater_china(&self) -> bool {
+        self.languages.iter().any(|language| {
+            let lower = language.to_ascii_lowercase().replace('_', "-");
+            GREATER_CHINA_LANGUAGE_PREFIXES
+                .iter()
+                .any(|prefix| lower.starts_with(prefix))
+        })
+    }
+
+    /// 是否是大中华区候选（信号① 或 信号②）。
+    #[must_use]
+    pub fn is_greater_china(&self) -> bool {
+        self.timezone_in_greater_china() || self.language_in_greater_china()
+    }
+}
+
+/// 纯判定函数（不发请求 → 好测）。
+#[must_use]
+pub fn decide_from(signals: &Signals, now_ms: u64) -> RegionProfile {
+    let greater_china = signals.is_greater_china();
+    let mode = match (greater_china, signals.google_reachable) {
+        // 非大中华区：一律直连。
+        (false, _) => RegionMode::Direct,
+        // 大中华区但 google 可达：用户已有全局代理，尊重直连。
+        (true, Some(true)) => RegionMode::Direct,
+        // 大中华区且 google 不可达：镜像优先。
+        (true, Some(false)) => RegionMode::MirrorFirst,
+        // 探测被关：中文环境默认镜像优先（用户拍板）。
+        (true, None) => RegionMode::MirrorFirst,
+    };
+    let mut profile = match mode {
+        RegionMode::Direct => RegionProfile::direct(now_ms),
+        RegionMode::MirrorFirst => RegionProfile::mirror_first(now_ms),
+    };
+    profile.greater_china = greater_china;
+    profile.probes_enabled = signals.google_reachable.is_some();
+    if mode == RegionMode::Direct {
+        profile.gh_proxy = None;
+    }
+    profile
+}
+
+/// 单点可达性探测（3s 超时，任何错误都算不可达）。
+pub async fn probe_reachable(client: &reqwest::Client, url: &str) -> bool {
+    let request = client.get(url).header(reqwest::header::RANGE, "bytes=0-0");
+    match tokio::time::timeout(PROBE_TIMEOUT, request.send()).await {
+        Ok(Ok(response)) => {
+            let status = response.status();
+            status.is_success() || status.is_redirection() || status.as_u16() == 204
+        }
+        _ => false,
+    }
+}
+
+/// 并发探测 google 与 baidu（两个都 3s 上限，总耗时约 3s）。
+pub async fn probe_signals(client: &reqwest::Client) -> (Option<bool>, Option<bool>) {
+    let (google, baidu) = tokio::join!(
+        probe_reachable(client, GOOGLE_PROBE_URL),
+        probe_reachable(client, BAIDU_PROBE_URL)
+    );
+    (Some(google), Some(baidu))
+}
+
+/// 完整判定：读信号 →（可选）探测 → 决定。
+pub async fn detect(client: &reqwest::Client, probes_enabled: bool, now_ms: u64) -> RegionProfile {
+    let mut signals = Signals::from_env();
+    if probes_enabled {
+        let (google, baidu) = probe_signals(client).await;
+        signals.google_reachable = google;
+        signals.baidu_reachable = baidu;
+    }
+    decide_from(&signals, now_ms)
+}
+
+/// 判定结果的落盘形态。
+#[derive(Debug, Clone, Serialize, Deserialize)]
+struct PersistedProfile {
+    version: u32,
+    profile: RegionProfile,
+}
+
+/// 读 24h 缓存（过期或损坏返回 `None`）。
+#[must_use]
+pub fn load_cached(path: &Path, now_ms: u64) -> Option<RegionProfile> {
+    let bytes = std::fs::read(path).ok()?;
+    let persisted: PersistedProfile = serde_json::from_slice(&bytes).ok()?;
+    if persisted.profile.is_stale(now_ms) {
+        return None;
+    }
+    Some(persisted.profile)
+}
+
+/// 写 24h 缓存（原子写）。
+pub fn store_cached(path: &Path, profile: &RegionProfile) -> std::io::Result<()> {
+    let persisted = PersistedProfile {
+        version: 1,
+        profile: profile.clone(),
+    };
+    let json = serde_json::to_vec_pretty(&persisted).map_err(std::io::Error::other)?;
+    write_atomic(path, &json)
+}
diff --git a/crates/core/src/download/region_system.rs b/crates/core/src/download/region_system.rs
new file mode 100644
index 0000000..eb60e48
--- /dev/null
+++ b/crates/core/src/download/region_system.rs
@@ -0,0 +1,158 @@
+//! 地区判定的**系统级**信号补充：环境变量之外的那一半（D23「国内用户默认都走镜像」）。
+//!
+//! 为什么需要它：`Signals::from_env` 只读 `TZ` / `LANG` / `LC_*`。Windows 上这三个通常**全是空的**
+//! ——中文版 Windows 既不设 `TZ` 也不设 `LANG`，于是「国内机器」被误判成国外，
+//! D23 定下的国内默认序（Temurin→Oracle→MS）就拿不到了。本机实测就是这个现象。
+//!
+//! 补法（只在环境变量没给出答案时才做，且读不到就静默跳过）：
+//!
+//! | 平台 | 时区 | 语言 |
+//! | --- | --- | --- |
+//! | Windows | `tzutil /g` → `China Standard Time` | `reg query` 的 `LocaleName` → `zh-CN` |
+//! | 其它 | 不补（Unix 一般都有 `LANG`，`/etc/localtime` 解析成本不划算） | 同左 |
+//!
+//! 两个纪律：①**不引依赖**——`tzutil` / `reg` 都是系统自带，`discover.rs` 早就有 `reg query`
+//! 的先例；②**不做网络探测**——探测（google 可达性）仍由调用方决定开不开。
+
+use std::process::Command;
+
+use super::region::{Signals, GREATER_CHINA_TIMEZONES};
+
+/// Windows 时区显示名里能判成「大中华区」的关键词（`tzutil /g` 的输出形态）。
+const GREATER_CHINA_ZONE_HINTS: &[&str] = &[
+    "China Standard Time",
+    "Taipei Standard Time",
+    "Hong Kong Standard Time",
+    "Ulaanbaatar",
+];
+
+/// 系统级信号（环境变量之外；读不到就是空信号）。
+#[must_use]
+pub fn system_signals() -> Signals {
+    let mut signals = Signals::default();
+    if !cfg!(windows) {
+        return signals;
+    }
+    if let Some(zone) = windows_timezone() {
+        if zone_in_greater_china(&zone) {
+            // 折成 IANA 名，和 `Signals::from_env` 的取值空间保持一致。
+            signals.timezone = Some("Asia/Shanghai".to_string());
+        }
+    }
+    if let Some(locale) = windows_locale() {
+        signals.languages.push(locale);
+    }
+    signals
+}
+
+/// 环境变量信号 + 系统级信号（系统级只补空缺，不覆盖环境变量）。
+#[must_use]
+pub fn detect_signals() -> Signals {
+    let mut signals = Signals::from_env();
+    let system = system_signals();
+    if signals.timezone.is_none() {
+        signals.timezone = system.timezone;
+    }
+    for language in system.languages {
+        if !signals.languages.contains(&language) {
+            signals.languages.push(language);
+        }
+    }
+    signals
+}
+
+/// `tzutil /g` 的输出（失败为 `None`）。
+#[must_use]
+pub fn windows_timezone() -> Option<String> {
+    let output = Command::new("tzutil").arg("/g").output().ok()?;
+    if !output.status.success() {
+        return None;
+    }
+    let text = String::from_utf8_lossy(&output.stdout).trim().to_string();
+    (!text.is_empty()).then_some(text)
+}
+
+/// 系统的 locale 名（`HKCU\Control Panel\International` 的 `LocaleName`）。
+#[must_use]
+pub fn windows_locale() -> Option<String> {
+    let output = Command::new("reg")
+        .args([
+            "query",
+            "HKCU\\Control Panel\\International",
+            "/v",
+            "LocaleName",
+        ])
+        .output()
+        .ok()?;
+    if !output.status.success() {
+        return None;
+    }
+    let stdout = String::from_utf8_lossy(&output.stdout).into_owned();
+    parse_reg_locale_name(&stdout)
+}
+
+/// 从 `reg query` 的输出里取 `LocaleName` 的值（`    LocaleName    REG_SZ    zh-CN`）。
+#[must_use]
+pub fn parse_reg_locale_name(stdout: &str) -> Option<String> {
+    for line in stdout.lines() {
+        let line = line.trim();
+        if !line.starts_with("LocaleName") {
+            continue;
+        }
+        let value = line.rsplit("REG_SZ").next()?.trim();
+        if !value.is_empty() {
+            return Some(value.to_string());
+        }
+    }
+    None
+}
+
+/// Windows 时区显示名是否落在大中华区。
+#[must_use]
+pub fn zone_in_greater_china(zone: &str) -> bool {
+    let zone = zone.trim();
+    GREATER_CHINA_ZONE_HINTS
+        .iter()
+        .any(|hint| zone.eq_ignore_ascii_case(hint))
+        || GREATER_CHINA_TIMEZONES
+            .iter()
+            .any(|known| known.eq_ignore_ascii_case(zone))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{detect_signals, parse_reg_locale_name, zone_in_greater_china};
+
+    #[test]
+    fn windows_zone_names_map_to_the_greater_china_list() {
+        assert!(zone_in_greater_china("China Standard Time"));
+        assert!(zone_in_greater_china("Taipei Standard Time"));
+        assert!(zone_in_greater_china("Asia/Shanghai"), "IANA 名同样要认");
+        assert!(!zone_in_greater_china("Pacific Standard Time"));
+        assert!(!zone_in_greater_china(""));
+    }
+
+    #[test]
+    fn reg_output_yields_the_locale_name() {
+        // 真机 `reg query "HKCU\Control Panel\International" /v LocaleName` 的形态。
+        let stdout = "\r\nHKEY_CURRENT_USER\\Control Panel\\International\r\n    \
+                      LocaleName    REG_SZ    zh-CN\r\n\r\n";
+        assert_eq!(parse_reg_locale_name(stdout).as_deref(), Some("zh-CN"));
+        assert_eq!(
+            parse_reg_locale_name("    LocaleName    REG_SZ    \r\n"),
+            None
+        );
+        assert_eq!(parse_reg_locale_name("没有这一行"), None);
+    }
+
+    #[test]
+    fn detect_layers_system_signals_under_the_environment() {
+        // 环境变量优先：这里能断言的只有「不 panic 且返回一个 Signals」，
+        // 具体取值取决于跑测试的机器（CI 上没有 tzutil/reg 也要安静退化）。
+        let signals = detect_signals();
+        // 无论哪种情况，都不该凭空造出「大中华区」以外的时区值。
+        if let Some(zone) = &signals.timezone {
+            assert!(!zone.trim().is_empty());
+        }
+    }
+}
diff --git a/crates/core/src/download/resume.rs b/crates/core/src/download/resume.rs
new file mode 100644
index 0000000..976cf57
--- /dev/null
+++ b/crates/core/src/download/resume.rs
@@ -0,0 +1,235 @@
+//! 断点续传的**保守判定**。
+//!
+//! 承 analyse/03 §5.4 与设计文档 §4 最后一行：「拒绝『能续传但会坏』场景」是 HMCL 做对的事。
+//! 我们把它写成纯函数，判定条件全部显式：
+//!
+//! 1. 策略不是 `Never`；
+//! 2. 中间文件存在且长度 > 0；
+//! 3. 有上一次的元数据（URL、摘要、总长、校验器）；
+//! 4. URL 与期望摘要都没变；
+//! 5. 总长已知且 `0 < 已下 < 总长`；
+//! 6. 有 ETag 或 Last-Modified 作为校验器（否则服务器换了内容我们也发现不了）。
+//!
+//! 任何一条不满足就**从头下**——重下 100MB 也比交付一个坏文件便宜。
+//! 另外单独处理 416（`Requested Range Not Satisfiable`）：已下满则直接进入校验，
+//! 否则丢弃中间文件重来。
+
+use std::io;
+use std::path::Path;
+
+use serde::{Deserialize, Serialize};
+
+use super::atomic::write_atomic;
+use super::types::{HashAlgo, ResumePolicy};
+
+/// 上一次下载留下的续传元数据。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ResumeMeta {
+    /// 当时请求的 URL（镜像可能换掉，URL 变了就不续传）。
+    pub url: String,
+    /// 响应 `ETag`。
+    pub etag: Option<String>,
+    /// 响应 `Last-Modified`。
+    pub last_modified: Option<String>,
+    /// 响应告知的总长度。
+    pub total: Option<u64>,
+    /// 摘要算法。
+    pub algo: HashAlgo,
+    /// 期望摘要。
+    pub hash: String,
+    /// 保存时间（unix 毫秒）。
+    pub saved_at_ms: u64,
+}
+
+impl ResumeMeta {
+    /// 从磁盘读（不存在/损坏 → `None`）。
+    #[must_use]
+    pub fn load(path: &Path) -> Option<Self> {
+        let bytes = std::fs::read(path).ok()?;
+        serde_json::from_slice(&bytes).ok()
+    }
+
+    /// 原子写。
+    pub fn save(&self, path: &Path) -> io::Result<()> {
+        let json = serde_json::to_vec_pretty(self).map_err(io::Error::other)?;
+        write_atomic(path, &json)
+    }
+
+    /// 删除（校验通过或放弃续传时）。
+    pub fn remove(path: &Path) {
+        let _ = std::fs::remove_file(path);
+    }
+
+    /// 本记录可用的校验器。
+    #[must_use]
+    pub fn validator(&self) -> Validator {
+        Validator {
+            etag: self.etag.clone(),
+            last_modified: self.last_modified.clone(),
+        }
+    }
+}
+
+/// 续传用的校验器（`If-Range` 头的取值来源）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Validator {
+    /// 强校验器。
+    pub etag: Option<String>,
+    /// 弱校验器。
+    pub last_modified: Option<String>,
+}
+
+impl Validator {
+    /// `If-Range` 头的值（ETag 优先，其次 Last-Modified）。
+    #[must_use]
+    pub fn if_range_value(&self) -> Option<&str> {
+        self.etag.as_deref().or(self.last_modified.as_deref())
+    }
+}
+
+/// 不复续传的原因（日志与诊断页用）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RestartReason {
+    /// 策略要求从不续传。
+    PolicyNever,
+    /// 没有中间文件。
+    NoPart,
+    /// 中间文件是 0 字节。
+    EmptyPart,
+    /// 没有元数据（无法证明中间文件是同一次下载的产物）。
+    NoMeta,
+    /// URL 变了（换源后偏移不可信）。
+    UrlChanged,
+    /// 期望摘要变了（目标文件已经不是同一个东西）。
+    HashChanged,
+    /// 总长未知（无法判断是否已下满）。
+    TotalUnknown,
+    /// 已下字节超过总长（中间文件被污染）。
+    Oversize,
+    /// 没有 ETag/Last-Modified，无法证明远端内容没变。
+    NoValidator,
+    /// 服务器 416 且未下满。
+    RangeUnsatisfiable,
+}
+
+impl RestartReason {
+    /// 稳定字符串 id。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::PolicyNever => "policy_never",
+            Self::NoPart => "no_part",
+            Self::EmptyPart => "empty_part",
+            Self::NoMeta => "no_meta",
+            Self::UrlChanged => "url_changed",
+            Self::HashChanged => "hash_changed",
+            Self::TotalUnknown => "total_unknown",
+            Self::Oversize => "oversize",
+            Self::NoValidator => "no_validator",
+            Self::RangeUnsatisfiable => "range_unsatisfiable",
+        }
+    }
+}
+
+/// 续传决策。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ResumeDecision {
+    /// 可以续传：从 `offset` 起发 `Range` + `If-Range`。
+    Resume {
+        /// 已下字节数。
+        offset: u64,
+        /// 校验器。
+        validator: Validator,
+    },
+    /// 从头下载。
+    Restart {
+        /// 原因。
+        reason: RestartReason,
+    },
+    /// 中间文件已经是完整长度：跳过传输，直接校验。
+    Complete {
+        /// 文件长度。
+        size: u64,
+    },
+}
+
+impl ResumeDecision {
+    /// 是否要丢掉中间文件（`Complete` 不能丢）。
+    #[must_use]
+    pub const fn should_drop_part(&self) -> bool {
+        matches!(self, Self::Restart { .. })
+    }
+}
+
+/// 判定是否续传（纯函数）。
+#[must_use]
+pub fn decide(
+    policy: ResumePolicy,
+    part_len: u64,
+    meta: Option<&ResumeMeta>,
+    url: &str,
+    integrity: Option<(HashAlgo, &str)>,
+    expected_size: Option<u64>,
+) -> ResumeDecision {
+    if policy == ResumePolicy::Never {
+        return ResumeDecision::Restart {
+            reason: RestartReason::PolicyNever,
+        };
+    }
+    if part_len == 0 {
+        return ResumeDecision::Restart {
+            reason: RestartReason::EmptyPart,
+        };
+    }
+    let Some(meta) = meta else {
+        return ResumeDecision::Restart {
+            reason: RestartReason::NoMeta,
+        };
+    };
+    if meta.url != url {
+        return ResumeDecision::Restart {
+            reason: RestartReason::UrlChanged,
+        };
+    }
+    if let Some((algo, hash)) = integrity {
+        if meta.algo != algo || !meta.hash.eq_ignore_ascii_case(hash) {
+            return ResumeDecision::Restart {
+                reason: RestartReason::HashChanged,
+            };
+        }
+    }
+    let Some(total) = meta.total.or(expected_size) else {
+        return ResumeDecision::Restart {
+            reason: RestartReason::TotalUnknown,
+        };
+    };
+    if part_len > total {
+        return ResumeDecision::Restart {
+            reason: RestartReason::Oversize,
+        };
+    }
+    if part_len == total {
+        return ResumeDecision::Complete { size: total };
+    }
+    let validator = meta.validator();
+    if validator.if_range_value().is_none() {
+        return ResumeDecision::Restart {
+            reason: RestartReason::NoValidator,
+        };
+    }
+    ResumeDecision::Resume {
+        offset: part_len,
+        validator,
+    }
+}
+
+/// 收到 416 后的决策。
+#[must_use]
+pub fn on_range_unsatisfiable(part_len: u64, total: Option<u64>) -> ResumeDecision {
+    match total {
+        Some(total) if part_len == total => ResumeDecision::Complete { size: total },
+        _ => ResumeDecision::Restart {
+            reason: RestartReason::RangeUnsatisfiable,
+        },
+    }
+}
diff --git a/crates/core/src/download/transfer.rs b/crates/core/src/download/transfer.rs
new file mode 100644
index 0000000..42f27ee
--- /dev/null
+++ b/crates/core/src/download/transfer.rs
@@ -0,0 +1,305 @@
+//! 传输细节：单连接（含续传）+ 多连接分块，产出「已校验的完整中间文件」。
+//!
+//! 本文件只管「一个候选源的一次尝试」——换源、退避、限流在 `engine.rs`。
+
+use std::time::Instant;
+
+use tokio::io::AsyncWriteExt;
+
+use super::atomic::PartFile;
+use super::cache::now_ms;
+use super::chunked;
+use super::engine::{AttemptOk, DownloadEngine};
+use super::error::{DownloadError, DownloadErrorKind};
+use super::http;
+use super::progress::{ProgressEvent, ProgressThrottle};
+use super::resume::{self, RestartReason, ResumeDecision, ResumeMeta};
+use super::types::{Candidate, DownloadId, DownloadRequest, HashAlgo};
+use super::verify;
+
+/// 续传起点（无续传时全为默认值）。
+struct ResumeCut {
+    /// 已下字节数。
+    offset: u64,
+    /// 续传起点（事件字段）。
+    resumed_from: u64,
+    /// `If-Range` 的取值。
+    if_range: Option<String>,
+}
+
+impl ResumeCut {
+    /// 从头下载。
+    const fn none() -> Self {
+        Self {
+            offset: 0,
+            resumed_from: 0,
+            if_range: None,
+        }
+    }
+}
+
+impl DownloadEngine {
+    /// 一次尝试：续传判定 → 分块 or 单连接 → 流式校验。
+    pub(crate) async fn attempt(
+        &self,
+        id: DownloadId,
+        req: &DownloadRequest,
+        candidate: &Candidate,
+        part: &mut PartFile,
+    ) -> Result<AttemptOk, DownloadError> {
+        let integrity = req.integrity.as_ref();
+        let meta_path = part.meta_path();
+        let previous = ResumeMeta::load(&meta_path);
+        // 「没有中间文件」和「有但 0 字节」是两种不同的原因，分开报出来便于诊断。
+        let decision = if !part.exists() {
+            ResumeDecision::Restart {
+                reason: RestartReason::NoPart,
+            }
+        } else if part.is_empty() {
+            ResumeDecision::Restart {
+                reason: RestartReason::EmptyPart,
+            }
+        } else {
+            resume::decide(
+                req.resume,
+                part.len(),
+                previous.as_ref(),
+                &candidate.url,
+                integrity.map(|item| (item.algo, item.hex.as_str())),
+                req.expected_size,
+            )
+        };
+
+        let mut cut = ResumeCut::none();
+        match decision {
+            ResumeDecision::Complete { size } => {
+                self.verify_part(part, integrity, id)?;
+                return Ok(AttemptOk {
+                    bytes: size,
+                    resumed_from: size,
+                });
+            }
+            ResumeDecision::Resume { offset, validator } => {
+                if let Some(value) = validator.if_range_value() {
+                    cut = ResumeCut {
+                        offset,
+                        resumed_from: offset,
+                        if_range: Some(value.to_string()),
+                    };
+                }
+            }
+            ResumeDecision::Restart { .. } => {}
+        }
+
+        if cut.offset == 0 && self.cfg.chunked.applies_to(req.kind, req.expected_size) {
+            match self
+                .attempt_chunked(id, req, candidate, part, req.expected_size)
+                .await
+            {
+                Ok(ok) => return Ok(ok),
+                // Range 不支持/切不出足够段：静默退化为单连接（不算源失败）。
+                Err(err) if err.kind == DownloadErrorKind::RangeUnsupported => {}
+                Err(err) => return Err(err),
+            }
+        }
+
+        self.attempt_single(id, req, candidate, part, cut).await
+    }
+
+    async fn attempt_single(
+        &self,
+        id: DownloadId,
+        req: &DownloadRequest,
+        candidate: &Candidate,
+        part: &mut PartFile,
+        cut: ResumeCut,
+    ) -> Result<AttemptOk, DownloadError> {
+        let integrity = req.integrity.as_ref();
+        let mut offset = cut.offset;
+        let mut resumed_from = cut.resumed_from;
+        let mut request = self.http.get(&candidate.url);
+        if offset > 0 {
+            match cut.if_range.as_deref() {
+                Some(value) => {
+                    request = request
+                        .header(reqwest::header::RANGE, format!("bytes={offset}-"))
+                        .header(reqwest::header::IF_RANGE, value);
+                }
+                // 没有校验器就不能保证远端内容没变，直接从头下。
+                None => {
+                    offset = 0;
+                    resumed_from = 0;
+                }
+            }
+        }
+
+        let response = request.send().await.map_err(|err| {
+            http::classify_reqwest(&err, &candidate.url).with_source(candidate.source.as_str())
+        })?;
+        let status = response.status();
+
+        if status.as_u16() == 416 {
+            return match resume::on_range_unsatisfiable(part.len(), req.expected_size) {
+                ResumeDecision::Complete { size } => {
+                    self.verify_part(part, integrity, id)?;
+                    Ok(AttemptOk {
+                        bytes: size,
+                        resumed_from: size,
+                    })
+                }
+                _ => {
+                    part.discard();
+                    Err(DownloadError::new(
+                        DownloadErrorKind::RangeUnsupported,
+                        "416：丢弃中间文件重下",
+                    )
+                    .with_source(candidate.source.as_str()))
+                }
+            };
+        }
+        if !status.is_success() {
+            return Err(http::classify_status(status.as_u16(), &candidate.url)
+                .with_source(candidate.source.as_str()));
+        }
+
+        // 2xx 不等于「拿到归档」：镜像门户对任意路径都回 200 + HTML（华为云实测）。
+        // 归到 NotFound（换源，不算源坏不进冷却），否则假阳性源会一直挡在队首。
+        if let Some(reason) =
+            http::html_mirror_reason(response.headers(), req.expected_size, offset)
+        {
+            return Err(DownloadError::new(DownloadErrorKind::NotFound, reason)
+                .with_source(candidate.source.as_str()));
+        }
+
+        // 服务器无视了 Range（200 而非 206）→ 从头写。
+        if offset > 0 && status.as_u16() != 206 {
+            offset = 0;
+            resumed_from = 0;
+        }
+
+        let content_range = http::header_str(response.headers(), reqwest::header::CONTENT_RANGE)
+            .and_then(chunked::parse_content_range);
+        let etag = http::etag(response.headers());
+        let last_modified = http::last_modified(response.headers());
+        let content_length = http::content_length(response.headers());
+
+        let mut total = req.expected_size;
+        if let Some(content_range) = content_range {
+            if content_range.start != offset {
+                // 服务器给的起点和我们以为的不一样：偏移不可信，从头来。
+                offset = 0;
+                resumed_from = 0;
+            }
+            total = content_range.total.or(total);
+        }
+        total = total.or_else(|| content_length.map(|len| len + offset));
+
+        // 记下续传元数据（跨进程续传的凭据）。
+        let meta = ResumeMeta {
+            url: candidate.url.clone(),
+            etag,
+            last_modified,
+            total,
+            algo: integrity.map_or(HashAlgo::Sha1, |item| item.algo),
+            hash: integrity.map_or_else(String::new, |item| item.hex.clone()),
+            saved_at_ms: now_ms(),
+        };
+        let _ = meta.save(&part.meta_path());
+
+        let std_file = if offset > 0 {
+            part.open_append()
+        } else {
+            part.open_truncate()
+        }
+        .map_err(|err| io_err("打开中间文件失败", &err))?;
+        let mut file = tokio::fs::File::from_std(std_file);
+
+        let mut hasher = integrity.map(|item| verify::Hasher::new(item.algo));
+        if offset > 0 {
+            if let Some(hasher) = hasher.as_mut() {
+                verify::update_hasher_from_file(hasher, part.path(), offset)
+                    .map_err(|err| io_err("读取续传前缀失败", &err))?;
+            }
+        }
+
+        let mut throttle = ProgressThrottle::new(self.cfg.progress_throttle);
+        let mut written = offset;
+        let mut stream = response.bytes_stream();
+        loop {
+            let next = tokio::time::timeout(
+                self.cfg.read_timeout,
+                futures_util::StreamExt::next(&mut stream),
+            )
+            .await
+            .map_err(|_| {
+                DownloadError::new(
+                    DownloadErrorKind::Timeout,
+                    format!("读取超时（{}）", candidate.url),
+                )
+                .with_source(candidate.source.as_str())
+            })?;
+            let Some(chunk) = next else { break };
+            let chunk = chunk.map_err(|err| http::classify_reqwest(&err, &candidate.url))?;
+            if let Some(hasher) = hasher.as_mut() {
+                hasher.update(&chunk);
+            }
+            file.write_all(&chunk)
+                .await
+                .map_err(|err| io_err("写入中间文件失败", &err))?;
+            written += chunk.len() as u64;
+            if throttle.should_emit(Instant::now(), false) {
+                self.emit(ProgressEvent::Progress {
+                    id,
+                    downloaded: written,
+                    total_bytes: total,
+                });
+            }
+        }
+        file.flush()
+            .await
+            .map_err(|err| io_err("刷新中间文件失败", &err))?;
+        // Windows 上打开中的文件不能被 rename，必须先关。
+        drop(file);
+
+        if let Some(total) = total {
+            if written != total {
+                return Err(DownloadError::new(
+                    DownloadErrorKind::Network,
+                    format!("长度不符：期望 {total} 实得 {written}（{}）", candidate.url),
+                )
+                .with_source(candidate.source.as_str()));
+            }
+        }
+
+        if let (Some(integrity), Some(hasher)) = (integrity, hasher) {
+            self.emit(ProgressEvent::Verifying {
+                id,
+                algo: integrity.algo,
+                expected_prefix: integrity.short_prefix().to_string(),
+            });
+            let actual = hasher.finish();
+            if !verify::matches(&integrity.hex, &actual) {
+                part.discard();
+                return Err(DownloadError::new(
+                    DownloadErrorKind::Integrity,
+                    format!("校验不符：期望 {} 实得 {actual}", integrity.hex),
+                )
+                .with_source(candidate.source.as_str()));
+            }
+        }
+
+        self.emit(ProgressEvent::Progress {
+            id,
+            downloaded: written,
+            total_bytes: total,
+        });
+        Ok(AttemptOk {
+            bytes: written,
+            resumed_from,
+        })
+    }
+}
+
+fn io_err(context: &str, err: &std::io::Error) -> DownloadError {
+    DownloadError::new(DownloadErrorKind::Io, format!("{context}: {err}"))
+}
diff --git a/crates/core/src/download/transfer_chunk.rs b/crates/core/src/download/transfer_chunk.rs
new file mode 100644
index 0000000..c9bbe8a
--- /dev/null
+++ b/crates/core/src/download/transfer_chunk.rs
@@ -0,0 +1,163 @@
+//! 大文件多连接分块的编排与校验。
+//!
+//! 分块本身由 `chunked.rs` 负责（纯规划 + 单块抓取），这里负责并发、进度上报、
+//! 失败清理与「整文件重算一次摘要」（分块是乱序写，只能整文件校验）。
+
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::Arc;
+use std::time::Duration;
+
+use super::atomic::PartFile;
+use super::chunked;
+use super::engine::{AttemptOk, DownloadEngine};
+use super::error::{DownloadError, DownloadErrorKind};
+use super::progress::ProgressEvent;
+use super::types::{Candidate, DownloadId, DownloadRequest, Integrity};
+use super::verify;
+
+impl DownloadEngine {
+    pub(crate) async fn attempt_chunked(
+        &self,
+        id: DownloadId,
+        req: &DownloadRequest,
+        candidate: &Candidate,
+        part: &mut PartFile,
+        total: Option<u64>,
+    ) -> Result<AttemptOk, DownloadError> {
+        let Some(total) = total.filter(|total| *total > 0) else {
+            return Err(DownloadError::new(
+                DownloadErrorKind::RangeUnsupported,
+                "总长未知，无法分块",
+            ));
+        };
+        let ranges = chunked::plan(total, self.cfg.chunked.effective_connections());
+        if ranges.len() < 2 {
+            return Err(DownloadError::new(
+                DownloadErrorKind::RangeUnsupported,
+                "可切分段不足，退化为单连接",
+            ));
+        }
+
+        part.discard();
+        part.ensure_parent_async()
+            .await
+            .map_err(|err| io_err("创建下载目录失败", &err))?;
+        {
+            let file = tokio::fs::OpenOptions::new()
+                .create(true)
+                .write(true)
+                .truncate(true)
+                .open(part.path())
+                .await
+                .map_err(|err| io_err("预分配中间文件失败", &err))?;
+            file.set_len(total)
+                .await
+                .map_err(|err| io_err("预分配长度失败", &err))?;
+        }
+
+        let counter = Arc::new(AtomicU64::new(0));
+        let reporter = self.spawn_reporter(id, Arc::clone(&counter), total);
+
+        let mut set = tokio::task::JoinSet::new();
+        for range in ranges {
+            let client = self.http.clone();
+            let url = candidate.url.clone();
+            let path = part.path().to_path_buf();
+            let read_timeout = self.cfg.read_timeout;
+            let progress = Arc::clone(&counter);
+            set.spawn(async move {
+                chunked::fetch_chunk(&client, &url, range, &path, read_timeout, &progress).await
+            });
+        }
+
+        let mut failure: Option<DownloadError> = None;
+        while let Some(joined) = set.join_next().await {
+            match joined {
+                Ok(Ok(_)) => {}
+                Ok(Err(err)) => {
+                    failure = Some(err.with_source(candidate.source.as_str()));
+                    set.abort_all();
+                    break;
+                }
+                Err(err) => {
+                    failure = Some(DownloadError::new(
+                        DownloadErrorKind::Network,
+                        format!("分块任务异常：{err}"),
+                    ));
+                    set.abort_all();
+                    break;
+                }
+            }
+        }
+        reporter.abort();
+
+        if let Some(err) = failure {
+            part.discard();
+            return Err(err);
+        }
+
+        // 分块是乱序写，只能整文件重算一次摘要。
+        self.verify_part(part, req.integrity.as_ref(), id)?;
+        self.emit(ProgressEvent::Progress {
+            id,
+            downloaded: total,
+            total_bytes: Some(total),
+        });
+        Ok(AttemptOk {
+            bytes: total,
+            resumed_from: 0,
+        })
+    }
+
+    fn spawn_reporter(
+        &self,
+        id: DownloadId,
+        counter: Arc<AtomicU64>,
+        total: u64,
+    ) -> tokio::task::JoinHandle<()> {
+        let emitter = self.progress.clone();
+        let interval = self.cfg.progress_throttle.max(Duration::from_millis(50));
+        tokio::spawn(async move {
+            let mut ticker = tokio::time::interval(interval);
+            loop {
+                ticker.tick().await;
+                let downloaded = counter.load(Ordering::Relaxed).min(total);
+                emitter.emit(ProgressEvent::Progress {
+                    id,
+                    downloaded,
+                    total_bytes: Some(total),
+                });
+            }
+        })
+    }
+
+    pub(crate) fn verify_part(
+        &self,
+        part: &mut PartFile,
+        integrity: Option<&Integrity>,
+        id: DownloadId,
+    ) -> Result<(), DownloadError> {
+        let Some(integrity) = integrity else {
+            return Ok(());
+        };
+        self.emit(ProgressEvent::Verifying {
+            id,
+            algo: integrity.algo,
+            expected_prefix: integrity.short_prefix().to_string(),
+        });
+        let actual = verify::digest_file(part.path(), integrity.algo)
+            .map_err(|err| io_err("读取中间文件失败", &err))?;
+        if verify::matches(&integrity.hex, &actual) {
+            return Ok(());
+        }
+        part.discard();
+        Err(DownloadError::new(
+            DownloadErrorKind::Integrity,
+            format!("校验不符：期望 {} 实得 {actual}", integrity.hex),
+        ))
+    }
+}
+
+fn io_err(context: &str, err: &std::io::Error) -> DownloadError {
+    DownloadError::new(DownloadErrorKind::Io, format!("{context}: {err}"))
+}
diff --git a/crates/core/src/download/types.rs b/crates/core/src/download/types.rs
new file mode 100644
index 0000000..722d2a0
--- /dev/null
+++ b/crates/core/src/download/types.rs
@@ -0,0 +1,307 @@
+//! 下载引擎的请求/结果类型：资源类型、摘要、请求、候选源、结果。
+//!
+//! 调用方（game / launch / agent）只需要描述「逻辑资源 + 落盘路径 + 期望校验」，
+//! 镜像展开、地区模式、健康度排序、重试、续传、分块全部由引擎内部完成。
+
+use std::fmt;
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::Duration;
+
+use serde::{Deserialize, Serialize};
+
+/// 资源类型。
+///
+/// 同时用作三件事：健康度统计的第二维度（`源 × 资源类型`）、分块下载的准入条件、
+/// 进度事件的分类标签。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ResourceKind {
+    /// 资源对象（`assets/objects/<xx>/<hash>`），海量小文件。
+    Asset,
+    /// 库文件（MB 级）。
+    Library,
+    /// 客户端 jar（MB~几十 MB）。
+    ClientJar,
+    /// 版本清单 / 版本 JSON（强时效，短 TTL）。
+    VersionManifest,
+    /// 资源索引 `assets/indexes/<id>.json`。
+    AssetIndex,
+    /// JDK 运行时（~180MB），分块下载的主力场景。
+    JavaRuntime,
+    /// GitHub release 产物（自更新 / mod）。
+    GitHubRelease,
+    /// mod 文件（CurseForge / Modrinth）。
+    ModFile,
+    /// 其它。
+    Other,
+}
+
+impl ResourceKind {
+    /// 稳定字符串 id（持久化与日志用，**不要改名**）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Asset => "asset",
+            Self::Library => "library",
+            Self::ClientJar => "client_jar",
+            Self::VersionManifest => "version_manifest",
+            Self::AssetIndex => "asset_index",
+            Self::JavaRuntime => "java_runtime",
+            Self::GitHubRelease => "github_release",
+            Self::ModFile => "mod_file",
+            Self::Other => "other",
+        }
+    }
+
+    /// 是否默认走多连接分块下载（大文件）。
+    #[must_use]
+    pub const fn prefers_chunked(self) -> bool {
+        matches!(self, Self::JavaRuntime | Self::ModFile)
+    }
+
+    /// 是否属于「小文件」：小文件不开分块（续传开销大于收益）。
+    #[must_use]
+    pub const fn is_small(self) -> bool {
+        matches!(
+            self,
+            Self::Asset | Self::VersionManifest | Self::AssetIndex | Self::Other
+        )
+    }
+}
+
+/// 摘要算法。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum HashAlgo {
+    /// SHA-1（Mojang 全线使用）。
+    Sha1,
+    /// SHA-256（自更新产物与部分镜像）。
+    Sha256,
+}
+
+impl HashAlgo {
+    /// 稳定字符串 id（缓存目录名与索引键用）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Sha1 => "sha1",
+            Self::Sha256 => "sha256",
+        }
+    }
+
+    /// 十六进制摘要的字符数。
+    #[must_use]
+    pub const fn hex_len(self) -> usize {
+        match self {
+            Self::Sha1 => 40,
+            Self::Sha256 => 64,
+        }
+    }
+}
+
+/// 期望校验值。构造时自动归一化为小写十六进制。
+#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub struct Integrity {
+    /// 算法。
+    pub algo: HashAlgo,
+    /// 小写十六进制摘要。
+    pub hex: String,
+}
+
+impl Integrity {
+    /// 构造 SHA-1 校验值。
+    #[must_use]
+    pub fn sha1(hex: impl Into<String>) -> Self {
+        Self {
+            algo: HashAlgo::Sha1,
+            hex: hex.into().trim().to_ascii_lowercase(),
+        }
+    }
+
+    /// 构造 SHA-256 校验值。
+    #[must_use]
+    pub fn sha256(hex: impl Into<String>) -> Self {
+        Self {
+            algo: HashAlgo::Sha256,
+            hex: hex.into().trim().to_ascii_lowercase(),
+        }
+    }
+
+    /// 长度与字符集是否合法（不合法时调用方应显式传 `None`，别让引擎白跑一趟）。
+    #[must_use]
+    pub fn is_well_formed(&self) -> bool {
+        self.hex.len() == self.algo.hex_len() && self.hex.bytes().all(|b| b.is_ascii_hexdigit())
+    }
+
+    /// 给日志/事件用的短前缀（前 8 位）。
+    #[must_use]
+    pub fn short_prefix(&self) -> &str {
+        let end = self.hex.len().min(8);
+        &self.hex[..end]
+    }
+}
+
+/// 断点续传策略。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ResumePolicy {
+    /// 保守判定（默认）：长度、ETag/Last-Modified 都对得上才续传（承 HMCL `HttpResumeContext`）。
+    #[default]
+    Conservative,
+    /// 从不续传（强时效资源、或镜像对 Range 支持可疑时）。
+    Never,
+}
+
+/// 单次下载的关联 id（进度事件靠它归并）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
+pub struct DownloadId(pub u64);
+
+impl DownloadId {
+    /// 进程内单调递增的 id。
+    #[must_use]
+    pub fn next() -> Self {
+        static NEXT: AtomicU64 = AtomicU64::new(1);
+        Self(NEXT.fetch_add(1, Ordering::Relaxed))
+    }
+
+    /// 原始数值。
+    #[must_use]
+    pub const fn value(self) -> u64 {
+        self.0
+    }
+}
+
+impl fmt::Display for DownloadId {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "#{}", self.0)
+    }
+}
+
+/// 一个下载请求：逻辑资源描述，不含任何镜像/重试策略。
+#[derive(Debug, Clone)]
+pub struct DownloadRequest {
+    /// 资源类型。
+    pub kind: ResourceKind,
+    /// **逻辑 URL（官方源）**。镜像按镜像表 + 地区模式展开成候选序列。
+    pub url: String,
+    /// 最终落盘路径（父目录自动创建）。
+    pub dest: PathBuf,
+    /// 期望校验值；`None` 表示只能靠长度兜底（不推荐，清单类资源必须带）。
+    pub integrity: Option<Integrity>,
+    /// 期望大小（进度预算 + 分块规划）。
+    pub expected_size: Option<u64>,
+    /// 续传策略。
+    pub resume: ResumePolicy,
+}
+
+impl DownloadRequest {
+    /// 构造请求（默认保守续传、无校验）。
+    #[must_use]
+    pub fn new(kind: ResourceKind, url: impl Into<String>, dest: impl Into<PathBuf>) -> Self {
+        Self {
+            kind,
+            url: url.into(),
+            dest: dest.into(),
+            integrity: None,
+            expected_size: None,
+            resume: ResumePolicy::Conservative,
+        }
+    }
+
+    /// 设置 SHA-1 校验。
+    #[must_use]
+    pub fn with_sha1(mut self, hex: impl Into<String>) -> Self {
+        self.integrity = Some(Integrity::sha1(hex));
+        self
+    }
+
+    /// 设置 SHA-256 校验。
+    #[must_use]
+    pub fn with_sha256(mut self, hex: impl Into<String>) -> Self {
+        self.integrity = Some(Integrity::sha256(hex));
+        self
+    }
+
+    /// 设置期望大小。
+    #[must_use]
+    pub fn with_size(mut self, size: u64) -> Self {
+        self.expected_size = Some(size);
+        self
+    }
+
+    /// 设置续传策略。
+    #[must_use]
+    pub fn with_resume(mut self, resume: ResumePolicy) -> Self {
+        self.resume = resume;
+        self
+    }
+
+    /// 请求本身是否自洽（运行期挡住明显错误的请求）。
+    pub fn validate(&self) -> Result<(), super::error::DownloadError> {
+        use super::error::{DownloadError, DownloadErrorKind};
+        if self.url.is_empty() {
+            return Err(DownloadError::new(
+                DownloadErrorKind::InvalidRequest,
+                "url 为空",
+            ));
+        }
+        if !(self.url.starts_with("http://") || self.url.starts_with("https://")) {
+            return Err(DownloadError::new(
+                DownloadErrorKind::InvalidRequest,
+                format!("仅支持 http(s) URL：{}", self.url),
+            ));
+        }
+        if let Some(integrity) = &self.integrity {
+            if !integrity.is_well_formed() {
+                return Err(DownloadError::new(
+                    DownloadErrorKind::InvalidRequest,
+                    format!("校验值不合法：{}", integrity.hex),
+                ));
+            }
+        }
+        Ok(())
+    }
+}
+
+/// 一个候选源（镜像展开产物）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Candidate {
+    /// 真正要请求的 URL。
+    pub url: String,
+    /// 源标识（`official` / `bmclapi` / `tuna` / `gh_proxy` …），健康度按此归并。
+    pub source: String,
+}
+
+impl Candidate {
+    /// 构造候选。
+    #[must_use]
+    pub fn new(source: impl Into<String>, url: impl Into<String>) -> Self {
+        Self {
+            source: source.into(),
+            url: url.into(),
+        }
+    }
+}
+
+/// 官方源候选的固定 `source` 标识。
+pub const SOURCE_OFFICIAL: &str = "official";
+
+/// 下载成功的结果。
+#[derive(Debug, Clone)]
+pub struct DownloadOutcome {
+    /// 关联 id。
+    pub id: DownloadId,
+    /// 落盘路径。
+    pub path: PathBuf,
+    /// 实际字节数（续传时含已存在的部分）。
+    pub bytes: u64,
+    /// 是否零网络命中内容寻址缓存。
+    pub from_cache: bool,
+    /// 实际成功的源。
+    pub source: String,
+    /// 续传起点（0 = 从头下载）。
+    pub resumed_from: u64,
+    /// 耗时。
+    pub elapsed: Duration,
+}
diff --git a/crates/core/src/download/verify.rs b/crates/core/src/download/verify.rs
new file mode 100644
index 0000000..3eb2859
--- /dev/null
+++ b/crates/core/src/download/verify.rs
@@ -0,0 +1,123 @@
+//! 流式摘要：边下边算，不额外读一遍盘。
+//!
+//! 承 analyse/03 §5.6 的「先校验后落盘」：`MessageDigest` 在写流的同时喂数据，
+//! 流结束时比对，不符就丢掉中间文件。
+
+use std::fs::File;
+use std::io::{self, Read};
+use std::path::Path;
+
+use sha1::Digest;
+
+use super::types::HashAlgo;
+
+/// 小写十六进制编码（不引 `hex` 依赖）。
+#[must_use]
+pub fn to_hex(bytes: &[u8]) -> String {
+    const HEX: &[u8; 16] = b"0123456789abcdef";
+    let mut out = String::with_capacity(bytes.len() * 2);
+    for byte in bytes {
+        out.push(char::from(HEX[usize::from(byte >> 4)]));
+        out.push(char::from(HEX[usize::from(byte & 0x0f)]));
+    }
+    out
+}
+
+/// 增量摘要器。
+#[derive(Debug)]
+pub enum Hasher {
+    /// SHA-1。
+    Sha1(sha1::Sha1),
+    /// SHA-256。
+    Sha256(sha2::Sha256),
+}
+
+impl Hasher {
+    /// 按算法新建。
+    #[must_use]
+    pub fn new(algo: HashAlgo) -> Self {
+        match algo {
+            HashAlgo::Sha1 => Self::Sha1(sha1::Sha1::new()),
+            HashAlgo::Sha256 => Self::Sha256(sha2::Sha256::new()),
+        }
+    }
+
+    /// 算法。
+    #[must_use]
+    pub const fn algo(&self) -> HashAlgo {
+        match self {
+            Self::Sha1(_) => HashAlgo::Sha1,
+            Self::Sha256(_) => HashAlgo::Sha256,
+        }
+    }
+
+    /// 喂一段数据。
+    pub fn update(&mut self, bytes: &[u8]) {
+        match self {
+            Self::Sha1(hasher) => Digest::update(hasher, bytes),
+            Self::Sha256(hasher) => Digest::update(hasher, bytes),
+        }
+    }
+
+    /// 收尾成小写十六进制。
+    #[must_use]
+    pub fn finish(self) -> String {
+        match self {
+            Self::Sha1(hasher) => to_hex(&hasher.finalize()),
+            Self::Sha256(hasher) => to_hex(&hasher.finalize()),
+        }
+    }
+}
+
+/// 一次性算内存里的摘要。
+#[must_use]
+pub fn digest_bytes(algo: HashAlgo, bytes: &[u8]) -> String {
+    let mut hasher = Hasher::new(algo);
+    hasher.update(bytes);
+    hasher.finish()
+}
+
+/// 算整个文件的摘要（`cache` 的抽样校验与 `register` 路径用）。
+pub fn digest_file(path: &Path, algo: HashAlgo) -> io::Result<String> {
+    let mut hasher = Hasher::new(algo);
+    let mut buffer = vec![0_u8; 64 * 1024];
+    let mut file = File::open(path)?;
+    loop {
+        let read = file.read(&mut buffer)?;
+        if read == 0 {
+            break;
+        }
+        hasher.update(&buffer[..read]);
+    }
+    Ok(hasher.finish())
+}
+
+/// 把文件前 `limit` 字节喂进已有摘要器（续传时让「边下边算」接得上）。
+pub fn update_hasher_from_file(hasher: &mut Hasher, path: &Path, limit: u64) -> io::Result<()> {
+    if limit == 0 {
+        return Ok(());
+    }
+    let mut buffer = vec![0_u8; 64 * 1024];
+    let mut reader = File::open(path)?.take(limit);
+    loop {
+        let read = reader.read(&mut buffer)?;
+        if read == 0 {
+            break;
+        }
+        hasher.update(&buffer[..read]);
+    }
+    Ok(())
+}
+
+/// 对已有文件的前 `prefix_len` 字节补算摘要（诊断/抽样校验用）。
+pub fn digest_prefix(path: &Path, algo: HashAlgo, prefix_len: u64) -> io::Result<String> {
+    let mut hasher = Hasher::new(algo);
+    update_hasher_from_file(&mut hasher, path, prefix_len)?;
+    Ok(hasher.finish())
+}
+
+/// 摘要比较（大小写不敏感，避免上游给了大写 hex 就白跑一趟）。
+#[must_use]
+pub fn matches(expected_hex: &str, actual_hex: &str) -> bool {
+    expected_hex.len() == actual_hex.len() && expected_hex.eq_ignore_ascii_case(actual_hex)
+}
diff --git a/crates/core/src/game/arguments.rs b/crates/core/src/game/arguments.rs
new file mode 100644
index 0000000..5317069
--- /dev/null
+++ b/crates/core/src/game/arguments.rs
@@ -0,0 +1,331 @@
+//! 版本 JSON 的 `arguments` 模型：规则（rules）求值与参数展开。
+//!
+//! 依据：`DevDocs/analyse/03-version-download.md` §4.4（`arguments` 的合并语义）、
+//! §4.6（`minecraftArguments` 单串形式与新版 `arguments` 并存）。
+//!
+//! 规则求值语义照抄 Mojang/HMCL（`CompatibilityRule.appliesToCurrentEnvironment`）：
+//! 规则列表为空 → 生效；否则**从 DISALLOW 开始**逐条覆盖，最后是 ALLOW 才算生效。
+//! 这是"白名单式"语义，与"最后一条匹配者胜"不同，抄错会漏掉/多带启动参数。
+
+use std::collections::BTreeMap;
+
+use serde::{Deserialize, Serialize};
+
+use crate::platform::os_info::OsInfo;
+
+/// 规则动作。
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum RuleAction {
+    /// 允许（命中后该参数/库生效）。
+    #[default]
+    Allow,
+    /// 禁止（命中后该参数/库失效）。
+    Disallow,
+}
+
+/// 一条规则。
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Rule {
+    /// 动作；缺省按 `allow` 处理（Mojang 老写法里 rules 只写 os 的情况）。
+    #[serde(default)]
+    pub action: RuleAction,
+    /// 操作系统限制。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub os: Option<OsRestriction>,
+    /// 特性开关限制（`has_custom_resolution`、`is_demo_user`…）。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub features: Option<BTreeMap<String, bool>>,
+}
+
+/// 规则的 OS 限制。`version`/`arch` 在官方 JSON 里是**正则**，见 [`matches_simple_pattern`]。
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct OsRestriction {
+    /// `windows` / `osx` / `linux`；也接受模组包里的 `win-x86` 这种合并写法。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub name: Option<String>,
+    /// OS 版本模式。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub version: Option<String>,
+    /// 架构模式（`x86`、`x86_64`、`arm64`）。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub arch: Option<String>,
+}
+
+/// 求值时的运行环境（OS / 架构 / 特性开关）。
+///
+/// 现由 [`Environment::host`] 从 `core::platform::os_info` 的探测快照构造（同 crate 依赖），
+/// 因此 `os_version` 是真实系统版本而不是空串；单测可以注入假快照做到不碰真机。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Environment {
+    /// Mojang 口径的 OS 名：`windows` / `osx` / `linux`。
+    pub os: String,
+    /// OS 版本字符串（Windows 上是 `10.0.19045` 之类；探测失败时为空串）。
+    pub os_version: String,
+    /// Mojang 口径的架构：`x86` / `x86_64` / `arm64`。
+    pub arch: String,
+    /// 特性开关，缺省全部视为 `false`。
+    pub features: BTreeMap<String, bool>,
+}
+
+impl Default for Environment {
+    fn default() -> Self {
+        Self::host()
+    }
+}
+
+impl Environment {
+    /// 当前主机环境。
+    ///
+    /// `os` / `arch` / `os_version` 全部取自 [`crate::platform::os_info::current`]
+    /// （进程内缓存，探测只做一次）：`os_version` 不再是空串，因此带 `os.version` 限制的
+    /// 规则（官方 JSON 里用正则写系统版本）能按真实值求值。
+    pub fn host() -> Self {
+        Self::from_os_info(crate::platform::os_info::current())
+    }
+
+    /// 从一份系统信息快照构造环境（单测注入假快照，不碰真机；也让 app/CLI 能复用已探测结果）。
+    pub fn from_os_info(info: &OsInfo) -> Self {
+        Self {
+            os: info.family.manifest_name().to_owned(),
+            os_version: info.os_version().to_owned(),
+            arch: info.arch.clone(),
+            features: BTreeMap::new(),
+        }
+    }
+
+    /// 打开/关闭一个特性开关（构建器风格，便于 launch 侧串起来）。
+    pub fn with_feature(mut self, name: impl Into<String>, value: bool) -> Self {
+        self.features.insert(name.into(), value);
+        self
+    }
+
+    /// 读一个特性开关；未声明视为 `false`。
+    pub fn feature(&self, name: &str) -> bool {
+        self.features.get(name).copied().unwrap_or(false)
+    }
+}
+
+impl OsRestriction {
+    /// 该限制是否匹配当前环境。
+    pub fn allows(&self, env: &Environment) -> bool {
+        if let Some(name) = &self.name {
+            // 模组包常见 `{ "name": "win-x86" }`：OS 名与架构合写。
+            let (os_name, arch) = match name.split_once('-') {
+                Some((os_part, arch_part)) if is_known_os(os_part) && is_known_arch(arch_part) => {
+                    (os_part, Some(arch_part))
+                }
+                _ => (name.as_str(), None),
+            };
+            if is_known_os(os_name) && os_name != env.os {
+                return false;
+            }
+            if let Some(arch) = arch {
+                if arch != env.arch {
+                    return false;
+                }
+            }
+        }
+        if let Some(version) = &self.version {
+            if !matches_simple_pattern(version, &env.os_version) {
+                return false;
+            }
+        }
+        if let Some(arch) = &self.arch {
+            if !matches_simple_pattern(arch, &env.arch) {
+                return false;
+            }
+        }
+        true
+    }
+}
+
+fn is_known_os(name: &str) -> bool {
+    matches!(name, "windows" | "osx" | "linux")
+}
+
+fn is_known_arch(name: &str) -> bool {
+    matches!(name, "x86" | "x86_64" | "arm64")
+}
+
+/// 极简正则匹配（官方 JSON 里 `os.version`/`os.arch` 用的是正则）。
+///
+/// 只覆盖实际出现过的形态：`^字面量`（前缀）、`字面量`（全等）、`字面量$`、
+/// 以及里面的 `\.`/`.*` 展开。**遇到其它元字符一律放宽为匹配**——
+/// 宁可多带一个参数（例如 Windows 专用 `-Dos.name`），也不要因为不会解析正则而漏掉参数。
+/// 阶段 B 若真有 JSON 用到复杂模式，再引入 `regex` 依赖替换本函数。
+pub fn matches_simple_pattern(pattern: &str, actual: &str) -> bool {
+    let anchored_start = pattern.starts_with('^');
+    let body = pattern.strip_prefix('^').unwrap_or(pattern);
+    let anchored_end = body.ends_with('$');
+    let body = body.strip_suffix('$').unwrap_or(body);
+
+    let mut literal = String::with_capacity(body.len());
+    let mut chars = body.chars();
+    while let Some(c) = chars.next() {
+        match c {
+            // `.*` 视作通配：丢掉两个字符即可（前后锚点仍然生效）。
+            '.' if chars.as_str().starts_with('*') => {
+                chars.next();
+            }
+            // `\.` 展开成字面点号。
+            '\\' => match chars.next() {
+                Some('.') => literal.push('.'),
+                _ => return true,
+            },
+            '.' => literal.push('.'),
+            '|' | '[' | ']' | '(' | ')' | '+' | '?' | '{' | '}' | '^' | '$' => return true,
+            other => literal.push(other),
+        }
+    }
+
+    match (anchored_start, anchored_end) {
+        (true, true) => actual == literal,
+        (true, false) => actual.starts_with(&literal),
+        (false, true) => actual.ends_with(&literal),
+        (false, false) => actual == literal || actual.starts_with(&literal),
+    }
+}
+
+impl Rule {
+    /// 该规则在当前环境下的动作；不匹配环境时返回 `None`。
+    pub fn action_in(&self, env: &Environment) -> Option<RuleAction> {
+        if let Some(os) = &self.os {
+            if !os.allows(env) {
+                return None;
+            }
+        }
+        if let Some(features) = &self.features {
+            for (name, expected) in features {
+                if env.feature(name) != *expected {
+                    return None;
+                }
+            }
+        }
+        Some(self.action)
+    }
+}
+
+/// 一组规则的求值（Mojang 白名单语义）。
+pub fn rules_allow(rules: &[Rule], env: &Environment) -> bool {
+    if rules.is_empty() {
+        return true;
+    }
+    let mut action = RuleAction::Disallow;
+    for rule in rules {
+        if let Some(this) = rule.action_in(env) {
+            action = this;
+        }
+    }
+    action == RuleAction::Allow
+}
+
+/// `arguments` 里的一项：纯字符串参数，或带规则的条件参数。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(untagged)]
+pub enum Argument {
+    /// 无条件参数。
+    Plain(String),
+    /// 带规则的条件参数。
+    Conditional(ConditionalArgument),
+}
+
+/// 带规则的条件参数。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ConditionalArgument {
+    /// 规则列表（白名单语义，见 [`rules_allow`]）。
+    #[serde(default)]
+    pub rules: Vec<Rule>,
+    /// 命中后的参数值（单个或多个）。
+    pub value: ArgumentValue,
+}
+
+/// 参数值：单个字符串或多个字符串。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(untagged)]
+pub enum ArgumentValue {
+    /// 单个参数。
+    One(String),
+    /// 多个参数。
+    Many(Vec<String>),
+}
+
+impl ArgumentValue {
+    /// 逐个参数借用（`One` 给一个，`Many` 给若干个）。
+    pub fn strings(&self) -> Vec<&str> {
+        match self {
+            Self::One(value) => vec![value.as_str()],
+            Self::Many(values) => values.iter().map(String::as_str).collect(),
+        }
+    }
+}
+
+impl Argument {
+    /// 在当前环境下展开为具体参数（占位符替换归 launch 负责）。
+    pub fn expand_into(&self, env: &Environment, out: &mut Vec<String>) {
+        match self {
+            Self::Plain(value) => out.push(value.clone()),
+            Self::Conditional(cond) => {
+                if rules_allow(&cond.rules, env) {
+                    match &cond.value {
+                        ArgumentValue::One(value) => out.push(value.clone()),
+                        ArgumentValue::Many(values) => out.extend(values.iter().cloned()),
+                    }
+                }
+            }
+        }
+    }
+}
+
+/// 版本 JSON 的 `arguments` 对象。
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Arguments {
+    /// 游戏参数（`mainClass` 之后）。
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub game: Vec<Argument>,
+    /// JVM 参数（`-Xmx` 之类之外的那部分）。
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub jvm: Vec<Argument>,
+}
+
+impl Arguments {
+    /// 合并两层参数：**父在前、子在后**（analyse/03 §4.4）。
+    pub fn merge(parent: Option<&Arguments>, child: Option<&Arguments>) -> Option<Arguments> {
+        match (parent, child) {
+            (None, None) => None,
+            (Some(parent), None) => Some(parent.clone()),
+            (None, Some(child)) => Some(child.clone()),
+            (Some(parent), Some(child)) => Some(Arguments {
+                game: parent
+                    .game
+                    .iter()
+                    .chain(child.game.iter())
+                    .cloned()
+                    .collect(),
+                jvm: parent.jvm.iter().chain(child.jvm.iter()).cloned().collect(),
+            }),
+        }
+    }
+
+    /// 按环境展开成扁平参数表（占位符 `--username ${auth_player_name}` 不在这里替换）。
+    pub fn expand(&self, env: &Environment) -> ExpandedArguments {
+        let mut game = Vec::new();
+        let mut jvm = Vec::new();
+        for argument in &self.game {
+            argument.expand_into(env, &mut game);
+        }
+        for argument in &self.jvm {
+            argument.expand_into(env, &mut jvm);
+        }
+        ExpandedArguments { game, jvm }
+    }
+}
+
+/// [`Arguments::expand`] 的结果。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct ExpandedArguments {
+    /// 展开后的游戏参数。
+    pub game: Vec<String>,
+    /// 展开后的 JVM 参数。
+    pub jvm: Vec<String>,
+}
diff --git a/crates/core/src/game/capability.rs b/crates/core/src/game/capability.rs
new file mode 100644
index 0000000..7247555
--- /dev/null
+++ b/crates/core/src/game/capability.rs
@@ -0,0 +1,83 @@
+//! 版本能力位：从版本 JSON 的**库表**推断「这个版本带不带某个渲染后端」。
+//!
+//! 依据 `DevDocs/PlanDoc/research/05-mc-vulkan.md`（M26）§2.2 与 §4.2：
+//! Vulkan 的三件套（`lwjgl-vulkan` / `lwjgl-shaderc` / `lwjgl-spvc` / `lwjgl-vma`）从
+//! **`26.2-snapshot-1`（2026-04-07）** 起进入官方库列表，26.1 全线（含 `26w14a` 这类周快照）没有。
+//!
+//! # 为什么用库表而不是版本号
+//!
+//! 硬编码 `is_at_least("26.2-snapshot-2")` 对官方主线是对的，但周快照（`26w14a`）、
+//! 继承版本、第三方改版都拿不到可靠的比较结果（`GameVersion::is_known() == false` 时
+//! 门限恒假）。库表是版本自己声明的**事实**，比版本号串稳。
+//!
+//! # ⚠️ 「库存在」≠「参数可用」
+//!
+//! `26.2-snapshot-1` 已经有 `lwjgl-vulkan`，但 `--graphicsBackend` 要到
+//! **`26.2-snapshot-2`（2026-04-09）** 才进 `Main.class`，两者差两天（实测结论）。
+//! 因此能力位只适合做：
+//! - **必要条件的快速否定**（没有库 → 一定没有 Vulkan 后端）；
+//! - UI 可用性提示（渲染设置里出不出「图形 API」三选一）；
+//! - **无法排序的版本**（周快照）的兜底判据。
+//!
+//! 可解析版本的下发门限仍以 `26.2-snapshot-2` 为准，见
+//! [`crate::launch::game_args::graphics_backend_allowed`]。
+
+use super::manifest::VersionJson;
+
+/// Vulkan 后端的 Maven 坐标（`group:artifact`）。
+pub const VULKAN_LIBRARY_GROUP: &str = "org.lwjgl";
+/// Vulkan 后端的 Maven 坐标（artifact）。
+pub const VULKAN_LIBRARY_ARTIFACT: &str = "lwjgl-vulkan";
+
+/// 一条库名是否是 LWJGL 的 Vulkan 绑定。
+///
+/// 吃 `group:artifact:version[:classifier][@ext]` 全形态；只比对前两段，因此
+/// `org.lwjgl:lwjgl-vulkan:3.4.3`、`org.lwjgl:lwjgl-vulkan:3.4.3:natives-macos`
+/// 与 `org.lwjgl:lwjgl-vulkan:3.4.3@jar` 都算命中。
+#[must_use]
+pub fn is_vulkan_library(name: &str) -> bool {
+    let mut parts = name.split(':');
+    let (Some(group), Some(artifact)) = (parts.next(), parts.next()) else {
+        return false;
+    };
+    // classifier / `@ext` 可能粘在 artifact 上（`lwjgl-vulkan@jar`）。
+    let artifact = artifact.split('@').next().unwrap_or(artifact);
+    group.trim() == VULKAN_LIBRARY_GROUP && artifact.trim() == VULKAN_LIBRARY_ARTIFACT
+}
+
+/// 从一份版本 JSON 推出的能力位（目前只有 Vulkan 一项，后续可加）。
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub struct VersionCapabilities {
+    /// `libraries` 里存在 `org.lwjgl:lwjgl-vulkan`。
+    ///
+    /// **注意语义**：这是「版本带 Vulkan 后端实现」的**必要条件**，不是
+    /// 「`--graphicsBackend` 可下发」的充分条件（见模块文档）。
+    pub has_vulkan_backend: bool,
+}
+
+impl VersionCapabilities {
+    /// 从版本 JSON 解析能力位（只读 `libraries[].name`，不看下载信息与规则）。
+    #[must_use]
+    pub fn from_json(json: &VersionJson) -> Self {
+        Self {
+            has_vulkan_backend: json
+                .libraries
+                .as_deref()
+                .unwrap_or_default()
+                .iter()
+                .any(|library| is_vulkan_library(&library.name)),
+        }
+    }
+
+    /// 是否带 Vulkan 后端。
+    #[must_use]
+    pub const fn has_vulkan_backend(&self) -> bool {
+        self.has_vulkan_backend
+    }
+}
+
+/// 快捷方式：库名列表里是否有 Vulkan 绑定（launch 侧拿到的库名表也能直接用）。
+#[must_use]
+pub fn library_names_have_vulkan<'a>(names: impl IntoIterator<Item = &'a str>) -> bool {
+    names.into_iter().any(is_vulkan_library)
+}
diff --git a/crates/core/src/game/data/unlisted-versions.json b/crates/core/src/game/data/unlisted-versions.json
new file mode 100644
index 0000000..0a62625
--- /dev/null
+++ b/crates/core/src/game/data/unlisted-versions.json
@@ -0,0 +1,209 @@
+{
+  "versions": [
+    {"id": "1.21.11_unobfuscated", "type": "unobfuscated", "url": "https://piston-meta.mojang.com/v1/packages/327be7759157b04495c591dbb721875e341877af/1.21.11_unobfuscated.json", "time": "2025-12-09T12:43:15+00:00", "releaseTime": "2025-12-09T12:43:15+00:00"},
+    {"id": "1.21.11-rc3_unobfuscated", "type": "unobfuscated", "url": "https://piston-meta.mojang.com/v1/packages/ce3f7ac6d0e9d23ea4e5f0354b91ff15039d9931/1.21.11-rc3_unobfuscated.json", "time": "2025-12-08T13:59:34+00:00", "releaseTime": "2025-12-08T13:59:34+00:00"},
+    {"id": "1.21.11-rc2_unobfuscated", "type": "unobfuscated", "url": "https://piston-meta.mojang.com/v1/packages/9282a3fb154d2a425086c62c11827281308bf93b/1.21.11-rc2_unobfuscated.json", "time": "2025-12-05T11:57:45+00:00", "releaseTime": "2025-12-05T11:57:45+00:00"},
+    {"id": "1.21.11-rc1_unobfuscated", "type": "unobfuscated", "url": "https://piston-meta.mojang.com/v1/packages/5d3ee0ef1f0251cf7e073354ca9e085a884a643d/1.21.11-rc1_unobfuscated.json", "time": "2025-12-04T15:56:55+00:00", "releaseTime": "2025-12-04T15:56:55+00:00"},
+    {"id": "1.21.11-pre5_unobfuscated", "type": "unobfuscated", "url": "https://piston-meta.mojang.com/v1/packages/1028441ca6d288bbf2103e773196bf524f7260fd/1.21.11-pre5_unobfuscated.json", "time": "2025-12-03T13:34:06+00:00", "releaseTime": "2025-12-03T13:34:06+00:00"},
+    {"id": "1.21.11-pre4_unobfuscated", "type": "unobfuscated", "url": "https://piston-meta.mojang.com/v1/packages/410ce37a2506adcfd54ef7d89168cfbe89cac4cb/1.21.11-pre4_unobfuscated.json", "time": "2025-12-01T13:40:12+00:00", "releaseTime": "2025-12-01T13:40:12+00:00"},
+    {"id": "1.21.11-pre3_unobfuscated", "type": "unobfuscated", "url": "https://piston-meta.mojang.com/v1/packages/579bf3428f72b5ea04883d202e4831bfdcb2aa8d/1.21.11-pre3_unobfuscated.json", "time": "2025-11-25T14:14:30+00:00", "releaseTime": "2025-11-25T14:14:30+00:00"},
+    {"id": "1.21.11-pre2_unobfuscated", "type": "unobfuscated", "url": "https://piston-meta.mojang.com/v1/packages/2955ce0af0512fdfe53ff0740b017344acf6f397/1.21.11-pre2_unobfuscated.json", "time": "2025-11-21T12:07:21+00:00", "releaseTime": "2025-11-21T12:07:21+00:00"},
+    {"id": "1.21.11-pre1_unobfuscated", "type": "unobfuscated", "url": "https://piston-meta.mojang.com/v1/packages/9c267f8dda2728bae55201a753cdd07b584709f1/1.21.11-pre1_unobfuscated.json", "time": "2025-11-19T08:30:46+00:00", "releaseTime": "2025-11-19T08:30:46+00:00"},
+    {"id": "25w46a_unobfuscated", "type": "unobfuscated", "url": "https://piston-meta.mojang.com/v1/packages/314ade2afeada364047798e163ef8e82427c69e1/25w46a_unobfuscated.json", "time": "2025-11-11T13:20:54+00:00", "releaseTime": "2025-11-11T13:20:54+00:00"},
+    {"id": "25w45a_unobfuscated", "type": "unobfuscated", "url": "https://piston-meta.mojang.com/v1/packages/7a3c149f148b6aa5ac3af48c4f701adea7e5b615/25w45a_unobfuscated.json", "time": "2025-11-04T14:07:08+00:00", "releaseTime": "2025-11-04T14:07:08+00:00"},
+    {"id": "1.19_deep_dark_experimental_snapshot-1", "type": "pending", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/1_19_deep_dark_experimental_snapshot-1/1_19_deep_dark_experimental_snapshot-1.json", "time": "2022-02-17T13:55:59+00:00", "releaseTime": "2022-02-17T13:55:59+00:00"},
+    {"id": "1.18_experimental-snapshot-7", "type": "pending", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/1_18_experimental-snapshot-7/1_18_experimental-snapshot-7.json", "time": "2021-09-08T12:33:23+00:00", "releaseTime": "2021-09-08T12:33:23+00:00"},
+    {"id": "1.18_experimental-snapshot-6", "type": "pending", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/1_18_experimental-snapshot-6/1_18_experimental-snapshot-6.json", "time": "2021-09-01T12:53:14+00:00", "releaseTime": "2021-09-01T12:53:14+00:00"},
+    {"id": "1.18_experimental-snapshot-5", "type": "pending", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/1_18_experimental-snapshot-5/1_18_experimental-snapshot-5.json", "time": "2021-08-25T14:41:57+00:00", "releaseTime": "2021-08-25T14:41:57+00:00"},
+    {"id": "1.18_experimental-snapshot-4", "type": "pending", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/1_18_experimental-snapshot-4/1_18_experimental-snapshot-4.json", "time": "2021-08-17T16:10:25+00:00", "releaseTime": "2021-08-17T16:10:25+00:00"},
+    {"id": "1.18_experimental-snapshot-3", "type": "pending", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/1_18_experimental-snapshot-3/1_18_experimental-snapshot-3.json", "time": "2021-08-10T12:42:45+00:00", "releaseTime": "2021-08-10T12:42:45+00:00"},
+    {"id": "1.18_experimental-snapshot-2", "type": "pending", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/1_18_experimental-snapshot-2/1_18_experimental-snapshot-2.json", "time": "2021-07-20T13:35:08+00:00", "releaseTime": "2021-07-20T13:35:08+00:00"},
+    {"id": "1.18_experimental-snapshot-1", "type": "pending", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/1_18_experimental-snapshot-1/1_18_experimental-snapshot-1.json", "time": "2021-07-13T12:54:19+00:00", "releaseTime": "2021-07-13T12:54:19+00:00"},
+    {"id": "1.16_combat-6", "type": "pending", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/1_16_combat-6/1_16_combat-6.json", "time": "2020-08-26T06:24:28+00:00", "releaseTime": "2020-08-26T06:24:28+00:00"},
+    {"id": "1.16_combat-5", "type": "pending", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/1_16_combat-5/1_16_combat-5.json", "time": "2020-08-21T09:23:13+00:00", "releaseTime": "2020-08-21T09:23:13+00:00"},
+    {"id": "1.16_combat-4", "type": "pending", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/1_16_combat-4/1_16_combat-4.json", "time": "2020-08-19T11:14:58+00:00", "releaseTime": "2020-08-19T11:14:58+00:00"},
+    {"id": "1.16_combat-3", "type": "pending", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/1_16_combat-3/1_16_combat-3.json", "time": "2020-08-14T09:02:15+00:00", "releaseTime": "2020-08-14T09:02:15+00:00"},
+    {"id": "1.16_combat-2", "type": "pending", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/1_16_combat-2/1_16_combat-2.json", "time": "2020-08-13T11:56:30+00:00", "releaseTime": "2020-08-13T11:56:30+00:00"},
+    {"id": "1.16_combat-1", "type": "pending", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/1_16_combat-1/1_16_combat-1.json", "time": "2020-08-12T14:07:25+00:00", "releaseTime": "2020-08-12T14:07:25+00:00"},
+    {"id": "1.16_combat-0", "type": "pending", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/1_16_combat-0/1_16_combat-0.json", "time": "2020-08-07T10:44:47+00:00", "releaseTime": "2020-08-07T10:44:47+00:00"},
+    {"id": "1.15_combat-6", "type": "pending", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/1_15_combat-6/1_15_combat-6.json", "time": "2020-01-15T09:46:35+00:00", "releaseTime": "2020-01-15T09:46:35+00:00"},
+    {"id": "1.15_combat-1", "type": "pending", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/1_15_combat-1/1_15_combat-1.json", "time": "2019-11-29T15:41:39+00:00", "releaseTime": "2019-11-29T15:41:39+00:00"},
+    {"id": "1.14_combat-3", "type": "pending", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/1_14_combat-3/1_14_combat-3.json", "time": "2019-10-31T14:31:38+00:00", "releaseTime": "2019-10-31T14:31:38+00:00"},
+    {"id": "1.14_combat-0", "type": "pending", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/1_14_combat-0/1_14_combat-0.json", "time": "2019-08-13T07:33:42+00:00", "releaseTime": "2019-08-13T07:33:42+00:00"},
+    {"id": "1.14_combat-212796", "type": "pending", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/1_14_combat-212796/1_14_combat-212796.json", "time": "2019-06-20T13:23:44+00:00", "releaseTime": "2019-06-20T13:23:44+00:00"},
+    {"id": "2.0_blue", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/2point0_blue/2point0_blue.json", "time": "2013-08-06T06:00:02-05:00", "releaseTime": "2013-03-20T05:00:02-05:00"},
+    {"id": "2.0_red", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/2point0_red/2point0_red.json", "time": "2013-08-06T06:00:01-05:00", "releaseTime": "2013-03-20T05:00:01-05:00"},
+    {"id": "2.0_purple", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/2point0_purple/2point0_purple.json", "time": "2013-08-06T06:00:00-05:00", "releaseTime": "2013-03-20T05:00:00-05:00"},
+    {"id": "13w12~", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/13w12-/13w12-.json", "time": "2013-03-19T00:00:00+00:00", "releaseTime": "2013-03-19T00:00:00+00:00"},
+    {"id": "13w10b", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/13w10b/13w10b.json", "time": "2013-03-06T00:00:00+00:00", "releaseTime": "2013-03-06T00:00:00+00:00"},
+    {"id": "13w10a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/13w10a/13w10a.json", "time": "2013-03-04T00:00:00+00:00", "releaseTime": "2013-03-04T00:00:00+00:00"},
+    {"id": "13w09c", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/13w09c/13w09c.json", "time": "2013-03-01T00:00:00+00:00", "releaseTime": "2013-03-01T00:00:00+00:00"},
+    {"id": "13w09b", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/13w09b/13w09b.json", "time": "2013-02-27T00:00:00+00:00", "releaseTime": "2013-02-27T00:00:00+00:00"},
+    {"id": "13w09a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/13w09a/13w09a.json", "time": "2013-02-26T00:00:00+00:00", "releaseTime": "2013-02-26T00:00:00+00:00"},
+    {"id": "13w07a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/13w07a/13w07a.json", "time": "2013-02-14T00:00:00+00:00", "releaseTime": "2013-02-14T00:00:00+00:00"},
+    {"id": "13w11a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/13w11a/13w11a.json", "time": "2013-02-14T00:00:00+00:00", "releaseTime": "2013-02-14T00:00:00+00:00"},
+    {"id": "13w06a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/13w06a/13w06a.json", "time": "2013-02-07T00:00:00+00:00", "releaseTime": "2013-02-07T00:00:00+00:00"},
+    {"id": "13w05b", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/13w05b/13w05b.json", "time": "2013-02-01T00:00:00+00:00", "releaseTime": "2013-02-01T00:00:00+00:00"},
+    {"id": "13w05a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/13w05a/13w05a.json", "time": "2013-01-31T00:00:00+00:00", "releaseTime": "2013-01-31T00:00:00+00:00"},
+    {"id": "13w04a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/13w04a/13w04a.json", "time": "2013-01-24T00:00:00+00:00", "releaseTime": "2013-01-24T00:00:00+00:00"},
+    {"id": "13w03a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/13w03a/13w03a.json", "time": "2013-01-17T00:00:00+00:00", "releaseTime": "2013-01-17T00:00:00+00:00"},
+    {"id": "13w02b", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/13w02b/13w02b.json", "time": "2013-01-11T00:00:00+00:00", "releaseTime": "2013-01-11T00:00:00+00:00"},
+    {"id": "13w02a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/13w02a/13w02a.json", "time": "2013-01-10T00:00:00+00:00", "releaseTime": "2013-01-10T00:00:00+00:00"},
+    {"id": "13w01b", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/13w01b/13w01b.json", "time": "2013-01-04T00:00:00+00:00", "releaseTime": "2013-01-04T00:00:00+00:00"},
+    {"id": "13w01a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/13w01a/13w01a.json", "time": "2013-01-03T00:00:00+00:00", "releaseTime": "2013-01-03T00:00:00+00:00"},
+    {"id": "12w50b", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w50b/12w50b.json", "time": "2012-12-14T00:00:00+00:00", "releaseTime": "2012-12-14T00:00:00+00:00"},
+    {"id": "12w50a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w50a/12w50a.json", "time": "2012-12-13T00:00:00+00:00", "releaseTime": "2012-12-13T00:00:00+00:00"},
+    {"id": "12w49a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w49a/12w49a.json", "time": "2012-12-07T00:00:00+00:00", "releaseTime": "2012-12-07T00:00:00+00:00"},
+    {"id": "12w42b", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w42b/12w42b.json", "time": "2012-10-18T00:00:00+00:00", "releaseTime": "2012-10-18T00:00:00+00:00"},
+    {"id": "12w42a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w42a/12w42a.json", "time": "2012-10-17T00:00:00+00:00", "releaseTime": "2012-10-17T00:00:00+00:00"},
+    {"id": "12w41b", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w41b/12w41b.json", "time": "2012-10-12T00:00:00+00:00", "releaseTime": "2012-10-12T00:00:00+00:00"},
+    {"id": "12w41a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w41a/12w41a.json", "time": "2012-10-11T00:00:00+00:00", "releaseTime": "2012-10-11T00:00:00+00:00"},
+    {"id": "12w40b", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w40b/12w40b.json", "time": "2012-10-05T00:00:00+00:00", "releaseTime": "2012-10-05T00:00:00+00:00"},
+    {"id": "12w40a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w40a/12w40a.json", "time": "2012-10-04T00:00:00+00:00", "releaseTime": "2012-10-04T00:00:00+00:00"},
+    {"id": "12w39b", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w39b/12w39b.json", "time": "2012-09-28T00:00:00+00:00", "releaseTime": "2012-09-28T00:00:00+00:00"},
+    {"id": "12w39a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w39a/12w39a.json", "time": "2012-09-27T00:00:00+00:00", "releaseTime": "2012-09-27T00:00:00+00:00"},
+    {"id": "12w38b", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w38b/12w38b.json", "time": "2012-09-21T00:00:00+00:00", "releaseTime": "2012-09-21T00:00:00+00:00"},
+    {"id": "12w38a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w38a/12w38a.json", "time": "2012-09-20T00:00:00+00:00", "releaseTime": "2012-09-20T00:00:00+00:00"},
+    {"id": "12w37a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w37a/12w37a.json", "time": "2012-09-13T00:00:00+00:00", "releaseTime": "2012-09-13T00:00:00+00:00"},
+    {"id": "12w36a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w36a/12w36a.json", "time": "2012-09-06T00:00:00+00:00", "releaseTime": "2012-09-06T00:00:00+00:00"},
+    {"id": "12w34b", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w34b/12w34b.json", "time": "2012-08-24T00:00:00+00:00", "releaseTime": "2012-08-24T00:00:00+00:00"},
+    {"id": "12w34a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w34a/12w34a.json", "time": "2012-08-23T00:00:00+00:00", "releaseTime": "2012-08-23T00:00:00+00:00"},
+    {"id": "12w32a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w32a/12w32a.json", "time": "2012-08-09T00:00:00+00:00", "releaseTime": "2012-08-09T00:00:00+00:00"},
+    {"id": "12w30d", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w30d/12w30d.json", "time": "2012-07-25T00:00:00+00:00", "releaseTime": "2012-07-25T00:00:00+00:00"},
+    {"id": "12w30e", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w30e/12w30e.json", "time": "2012-07-25T00:00:00+00:00", "releaseTime": "2012-07-25T00:00:00+00:00"},
+    {"id": "12w30c", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w30c/12w30c.json", "time": "2012-07-24T00:00:00+00:00", "releaseTime": "2012-07-24T00:00:00+00:00"},
+    {"id": "12w30a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w30a/12w30a.json", "time": "2012-07-23T00:00:00+00:00", "releaseTime": "2012-07-23T00:00:00+00:00"},
+    {"id": "12w30b", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w30b/12w30b.json", "time": "2012-07-23T00:00:00+00:00", "releaseTime": "2012-07-23T00:00:00+00:00"},
+    {"id": "12w27a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w27a/12w27a.json", "time": "2012-07-05T00:00:00+00:00", "releaseTime": "2012-07-05T00:00:00+00:00"},
+    {"id": "12w26a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w26a/12w26a.json", "time": "2012-06-27T00:00:00+00:00", "releaseTime": "2012-06-27T00:00:00+00:00"},
+    {"id": "12w25a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w25a/12w25a.json", "time": "2012-06-21T00:00:00+00:00", "releaseTime": "2012-06-21T00:00:00+00:00"},
+    {"id": "12w24a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w24a/12w24a.json", "time": "2012-06-14T00:00:00+00:00", "releaseTime": "2012-06-14T00:00:00+00:00"},
+    {"id": "12w23a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w23a/12w23a.json", "time": "2012-06-07T00:00:00+00:00", "releaseTime": "2012-06-07T00:00:00+00:00"},
+    {"id": "12w23b", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w23b/12w23b.json", "time": "2012-06-07T00:00:00+00:00", "releaseTime": "2012-06-07T00:00:00+00:00"},
+    {"id": "12w22a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w22a/12w22a.json", "time": "2012-05-31T00:00:00+00:00", "releaseTime": "2012-05-31T00:00:00+00:00"},
+    {"id": "12w21b", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w21b/12w21b.json", "time": "2012-05-25T00:00:00+00:00", "releaseTime": "2012-05-25T00:00:00+00:00"},
+    {"id": "12w21a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w21a/12w21a.json", "time": "2012-05-24T00:00:00+00:00", "releaseTime": "2012-05-24T00:00:00+00:00"},
+    {"id": "12w19a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w19a/12w19a.json", "time": "2012-05-10T00:00:00+00:00", "releaseTime": "2012-05-10T00:00:00+00:00"},
+    {"id": "12w18a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w18a/12w18a.json", "time": "2012-05-03T00:00:00+00:00", "releaseTime": "2012-05-03T00:00:00+00:00"},
+    {"id": "12w17a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w17a/12w17a.json", "time": "2012-04-26T00:00:00+00:00", "releaseTime": "2012-04-26T00:00:00+00:00"},
+    {"id": "12w16a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w16a/12w16a.json", "time": "2012-04-19T00:00:00+00:00", "releaseTime": "2012-04-19T00:00:00+00:00"},
+    {"id": "1.2", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/1_2/1_2.json", "time": "2012-02-29T00:00:00+00:00", "releaseTime": "2012-02-29T00:00:00+00:00"},
+    {"id": "12w08a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w08a/12w08a.json", "time": "2012-02-23T00:00:00+00:00", "releaseTime": "2012-02-23T00:00:00+00:00"},
+    {"id": "12w07a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w07a/12w07a.json", "time": "2012-02-15T00:00:00+00:00", "releaseTime": "2012-02-15T00:00:00+00:00"},
+    {"id": "12w07b", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w07b/12w07b.json", "time": "2012-02-15T00:00:00+00:00", "releaseTime": "2012-02-15T00:00:00+00:00"},
+    {"id": "12w06a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w06a/12w06a.json", "time": "2012-02-09T00:00:00+00:00", "releaseTime": "2012-02-09T00:00:00+00:00"},
+    {"id": "12w05b", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w05b/12w05b.json", "time": "2012-02-03T00:00:00+00:00", "releaseTime": "2012-02-03T00:00:00+00:00"},
+    {"id": "12w05a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w05a/12w05a.json", "time": "2012-02-02T00:00:00+00:00", "releaseTime": "2012-02-02T00:00:00+00:00"},
+    {"id": "12w04a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w04a/12w04a.json", "time": "2012-01-26T00:00:00+00:00", "releaseTime": "2012-01-26T00:00:00+00:00"},
+    {"id": "12w03a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w03a/12w03a.json", "time": "2012-01-19T00:00:00+00:00", "releaseTime": "2012-01-19T00:00:00+00:00"},
+    {"id": "12w01a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/12w01a/12w01a.json", "time": "2012-01-05T00:00:00+00:00", "releaseTime": "2012-01-05T00:00:00+00:00"},
+    {"id": "11w50a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/11w50a/11w50a.json", "time": "2011-12-15T00:00:00+00:00", "releaseTime": "2011-12-15T00:00:00+00:00"},
+    {"id": "11w49a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/11w49a/11w49a.json", "time": "2011-12-08T00:00:00+00:00", "releaseTime": "2011-12-08T00:00:00+00:00"},
+    {"id": "11w48a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/11w48a/11w48a.json", "time": "2011-12-01T00:00:00+00:00", "releaseTime": "2011-12-01T00:00:00+00:00"},
+    {"id": "11w47a", "type": "snapshot", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/11w47a/11w47a.json", "time": "2011-11-24T00:00:00+00:00", "releaseTime": "2011-11-24T00:00:00+00:00"},
+    {"id": "1.0.0-rc2-3", "type": "old_beta", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/1.0.0-rc2-3/1.0.0-rc2-3.json", "time": "2013-08-06T07:33:30-07:00", "releaseTime": "2011-11-14T15:00:00-07:00"},
+    {"id": "1.0.0-rc2-2", "type": "old_beta", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/1.0.0-rc2-2/1.0.0-rc2-2.json", "time": "2019-04-21T21:04:24+00:00", "releaseTime": "2011-11-14T00:00:00+00:00"},
+    {"id": "1.0.0-rc2-1", "type": "old_beta", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/1.0.0-rc2-1/1.0.0-rc2-1.json", "time": "2019-11-21T22:37:45+00:00", "releaseTime": "2011-11-13T17:33:00+00:00"},
+    {"id": "1.0.0-rc1", "type": "old_beta", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/1.0.0-rc1/1.0.0-rc1.json", "time": "2013-08-06T07:33:30-07:00", "releaseTime": "2011-11-13T15:00:00-07:00"},
+    {"id": "b1.9-pre6", "type": "old_beta", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/b1_9-pre6/b1_9-pre6.json", "time": "2011-11-11T00:00:00+00:00", "releaseTime": "2011-11-11T00:00:00+00:00"},
+    {"id": "b1.9-pre5", "type": "old_beta", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/b1_9-pre5/b1_9-pre5.json", "time": "2011-10-27T00:00:00+00:00", "releaseTime": "2011-10-27T00:00:00+00:00"},
+    {"id": "b1.9-pre4", "type": "old_beta", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/b1_9-pre4/b1_9-pre4.json", "time": "2011-10-13T00:00:00+00:00", "releaseTime": "2011-10-13T00:00:00+00:00"},
+    {"id": "b1.9-pre3", "type": "old_beta", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/b1_9-pre3/b1_9-pre3.json", "time": "2011-10-06T00:00:00+00:00", "releaseTime": "2011-10-06T00:00:00+00:00"},
+    {"id": "b1.9-pre2", "type": "old_beta", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/b1_9-pre2/b1_9-pre2.json", "time": "2011-09-29T00:00:00+00:00", "releaseTime": "2011-09-29T00:00:00+00:00"},
+    {"id": "b1.9-pre1", "type": "old_beta", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/b1_9-pre1/b1_9-pre1.json", "time": "2011-09-22T00:00:00+00:00", "releaseTime": "2011-09-22T00:00:00+00:00"},
+    {"id": "b1.8-pre2", "type": "old_beta", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/b1_8-pre2/b1_8-pre2.json", "time": "2011-09-13T00:00:00+00:00", "releaseTime": "2011-09-13T00:00:00+00:00"},
+    {"id": "b1.8-pre1-2", "type": "old_beta", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/b1_8-pre1/b1_8-pre1.json", "time": "2011-09-09T00:00:00+00:00", "releaseTime": "2011-09-09T00:00:00+00:00"},
+    {"id": "b1.8-pre1-1", "type": "old_beta", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/b1.8-pre1-1/b1.8-pre1-1.json", "time": "2011-09-09T00:00:00+00:00", "releaseTime": "2011-09-09T00:00:00+00:00"},
+    {"id": "b1.6-tb3", "type": "old_beta", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/b1.6-tb3/b1.6-tb3.json", "time": "2013-08-06T07:33:30-07:00", "releaseTime": "2011-05-24T15:00:00-07:00"},
+    {"id": "b1.1-1", "type": "old_beta", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/b1.1-1/b1.1-1.json", "time": "2016-02-02T15:37:47+00:00", "releaseTime": "2010-12-21T22:00:00+00:00"},
+    {"id": "b1.1-2", "type": "old_beta", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/b1.1-2/b1.1-2.json", "time": "2016-02-02T15:37:47+00:00", "releaseTime": "2010-12-21T22:00:00+00:00"},
+    {"id": "a1.1.1", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/a1.1.1/a1.1.1.json", "time": "2010-09-18T19:29:56+02:00", "releaseTime": "2010-09-18T19:29:56+02:00"},
+    {"id": "a1.1.0-2", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/a1.1.0-2/a1.1.0-2.json", "time": "2016-02-02T15:37:47+00:00", "releaseTime": "2010-09-12T22:00:00+00:00"},
+    {"id": "a1.1.0-1", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/a1.1.0-1/a1.1.0-1.json", "time": "2017-10-22T05:26:50+00:00", "releaseTime": "2010-09-10T00:00:00+00:00"},
+    {"id": "a1.0.17_03", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/a1.0.17_03/a1.0.17_03.json", "time": "2017-10-22T05:26:50+00:00", "releaseTime": "2010-08-23T00:00:00+00:00"},
+    {"id": "a1.0.16_02", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/a1.0.16_02/a1.0.16_02.json", "time": "2017-10-22T05:26:50+00:00", "releaseTime": "2010-08-13T00:00:00+00:00"},
+    {"id": "a1.0.16_01", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/a1.0.16_01/a1.0.16_01.json", "time": "2013-08-06T04:00:00-07:00", "releaseTime": "2010-08-12T15:00:00-07:00"},
+    {"id": "a1.0.14-1", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/a1.0.14-1/a1.0.14-1.json", "time": "2017-10-22T05:26:50+00:00", "releaseTime": "2010-07-30T00:00:00+00:00"},
+    {"id": "a1.0.14-2", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/a1.0.14-2/a1.0.14-2.json", "time": "2017-10-22T05:26:50+00:00", "releaseTime": "2010-07-30T00:00:00+00:00"},
+    {"id": "a1.0.13_01-1", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/a1.0.13_01-1/a1.0.13_01-1.json", "time": "2017-10-22T05:26:50+00:00", "releaseTime": "2010-07-29T00:00:00+00:00"},
+    {"id": "a1.0.13_01-2", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/a1.0.13_01-2/a1.0.13_01-2.json", "time": "2017-10-22T05:26:50+00:00", "releaseTime": "2010-07-29T00:00:00+00:00"},
+    {"id": "a1.0.13", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/a1.0.13/a1.0.13.json", "time": "2017-10-22T05:26:50+00:00", "releaseTime": "2010-07-28T00:00:00+00:00"},
+    {"id": "a1.0.12", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/a1.0.12/a1.0.12.json", "time": "2017-10-22T05:26:50+00:00", "releaseTime": "2010-07-26T00:00:00+00:00"},
+    {"id": "a1.0.10", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/a1.0.10/a1.0.10.json", "time": "2017-10-22T05:26:50+00:00", "releaseTime": "2010-07-22T00:00:00+00:00"},
+    {"id": "a1.0.9", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/a1.0.9/a1.0.9.json", "time": "2017-10-22T05:26:50+00:00", "releaseTime": "2010-07-21T00:00:00+00:00"},
+    {"id": "a1.0.7", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/a1.0.7/a1.0.7.json", "time": "2013-08-06T04:00:00-07:00", "releaseTime": "2010-07-19T15:00:00-07:00"},
+    {"id": "a1.0.8_01", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/a1.0.8_01/a1.0.8_01.json", "time": "2013-08-06T04:00:00-07:00", "releaseTime": "2010-07-19T15:00:00-07:00"},
+    {"id": "a1.0.6_01", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/a1.0.6_01/a1.0.6_01.json", "time": "2017-10-22T05:26:50+00:00", "releaseTime": "2010-07-17T00:00:00+00:00"},
+    {"id": "a1.0.6_03", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/a1.0.6_03/a1.0.6_03.json", "time": "2017-10-22T05:26:50+00:00", "releaseTime": "2010-07-17T00:00:00+00:00"},
+    {"id": "a1.0.6", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/a1.0.6/a1.0.6.json", "time": "2017-10-22T05:26:50+00:00", "releaseTime": "2010-07-16T00:00:00+00:00"},
+    {"id": "a1.0.5", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/a1.0.5/a1.0.5.json", "time": "2017-10-22T05:26:50+00:00", "releaseTime": "2010-07-13T00:00:00+00:00"},
+    {"id": "a1.0.3", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/a1.0.3/a1.0.3.json", "time": "2017-10-22T05:26:50+00:00", "releaseTime": "2010-07-07T00:00:00+00:00"},
+    {"id": "a1.0.2_01", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/a1.0.2_01/a1.0.2_01.json", "time": "2017-10-22T05:26:50+00:00", "releaseTime": "2010-07-06T00:00:00+00:00"},
+    {"id": "a1.0.2_02", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/a1.0.2_02/a1.0.2_02.json", "time": "2017-10-22T05:26:50+00:00", "releaseTime": "2010-07-06T00:00:00+00:00"},
+    {"id": "a1.0.1_01", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/a1.0.1_01/a1.0.1_01.json", "time": "2017-10-22T05:26:50+00:00", "releaseTime": "2010-07-03T22:00:00+00:00"},
+    {"id": "inf-20100630-1", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/inf-20100630-1/inf-20100630-1.json", "time": "2015-04-13T07:33:30-07:00", "releaseTime": "2010-06-30T00:00:00-00:00"},
+    {"id": "inf-20100630-2", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/inf-20100630-2/inf-20100630-2.json", "time": "2015-04-13T07:33:30-07:00", "releaseTime": "2010-06-30T00:00:00-00:00"},
+    {"id": "inf-20100629", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/inf-20100629/inf-20100629.json", "time": "2015-04-13T07:33:30-07:00", "releaseTime": "2010-06-29T00:00:00-00:00"},
+    {"id": "inf-20100627", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/inf-20100627/inf-20100627.json", "time": "2015-04-13T07:33:30-07:00", "releaseTime": "2010-06-27T15:00:00-07:00"},
+    {"id": "inf-20100625-1", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/inf-20100625-1/inf-20100625-1.json", "time": "2015-04-13T07:33:30-07:00", "releaseTime": "2010-06-25T00:00:00-00:00"},
+    {"id": "inf-20100625-2", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/inf-20100625-2/inf-20100625-2.json", "time": "2015-04-13T07:33:30-07:00", "releaseTime": "2010-06-25T00:00:00-00:00"},
+    {"id": "inf-20100624", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/inf-20100624/inf-20100624.json", "time": "2015-04-13T07:33:30-07:00", "releaseTime": "2010-06-24T00:00:00-00:00"},
+    {"id": "inf-20100617-2", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/inf-20100617-2/inf-20100617-2.json", "time": "2010-06-17T00:00:00-00:00", "releaseTime": "2010-06-17T00:00:00-00:00"},
+    {"id": "inf-20100617-3", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/inf-20100617-3/inf-20100617-3.json", "time": "2010-06-17T00:00:00-00:00", "releaseTime": "2010-06-17T00:00:00-00:00"},
+    {"id": "inf-20100615", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/inf-20100615/inf-20100615.json", "time": "2015-04-13T07:33:30-07:00", "releaseTime": "2010-06-15T00:00:00-00:00"},
+    {"id": "inf-20100611", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/inf-20100611/inf-20100611.json", "time": "2015-04-13T07:33:30-07:00", "releaseTime": "2010-06-11T00:00:00-00:00"},
+    {"id": "inf-20100608", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/inf-20100608/inf-20100608.json", "time": "2015-04-13T07:33:30-07:00", "releaseTime": "2010-06-08T15:00:00-07:00"},
+    {"id": "inf-20100607", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/inf-20100607/inf-20100607.json", "time": "2015-04-13T07:33:30-07:00", "releaseTime": "2010-06-07T00:00:00-00:00"},
+    {"id": "inf-20100420", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/inf-20100420/inf-20100420.json", "time": "2015-04-13T07:33:30-07:00", "releaseTime": "2010-04-20T15:00:00-07:00"},
+    {"id": "inf-20100415", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/inf-20100415/inf-20100415.json", "time": "2015-04-13T07:33:30-07:00", "releaseTime": "2010-04-15T15:00:00-07:00"},
+    {"id": "inf-20100414", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/inf-20100414/inf-20100414.json", "time": "2015-04-13T07:33:30-07:00", "releaseTime": "2010-04-14T00:00:00-00:00"},
+    {"id": "inf-20100413", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/inf-20100413/inf-20100413.json", "time": "2015-04-13T07:33:30-07:00", "releaseTime": "2010-04-13T00:00:00-00:00"},
+    {"id": "inf-20100330", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/inf-20100330/inf-20100330.json", "time": "2010-03-30T00:00:00-00:00", "releaseTime": "2010-03-30T00:00:00-00:00"},
+    {"id": "inf-20100327", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/inf-20100327/inf-20100327.json", "time": "2010-03-27T00:00:00-00:00", "releaseTime": "2010-03-27T00:00:00-00:00"},
+    {"id": "inf-20100325", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/inf-20100325/inf-20100325.json", "time": "2015-04-13T07:33:30-07:00", "releaseTime": "2010-03-25T00:00:00-00:00"},
+    {"id": "inf-20100321", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/inf-20100321/inf-20100321.json", "time": "2015-04-13T07:33:30-07:00", "releaseTime": "2010-03-21T00:00:00-00:00"},
+    {"id": "inf-20100320", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/inf-20100320/inf-20100320.json", "time": "2015-04-13T07:33:30-07:00", "releaseTime": "2010-03-20T00:00:00-00:00"},
+    {"id": "inf-20100316", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/inf-20100316/inf-20100316.json", "time": "2015-04-13T07:33:30-07:00", "releaseTime": "2010-03-16T00:00:00-00:00"},
+    {"id": "inf-20100313", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/inf-20100313/inf-20100313.json", "time": "2015-04-13T07:33:30-07:00", "releaseTime": "2010-03-13T00:00:00-00:00"},
+    {"id": "in-20100223", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/in-20100223/in-20100223.json", "time": "2013-08-06T07:33:30-07:00", "releaseTime": "2010-02-23T15:00:00-07:00"},
+    {"id": "in-20100219", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/in-20100219/in-20100219.json", "time": "2017-10-24T00:00:00+00:00", "releaseTime": "2010-02-19T00:00:00+00:00"},
+    {"id": "in-20100218", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/in-20100218/in-20100218.json", "time": "2017-09-20T00:00:00+00:00", "releaseTime": "2010-02-18T00:00:00+00:00"},
+    {"id": "in-20100214-2", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/in-20100214-2/in-20100214-2.json", "time": "2017-09-20T00:00:00+00:00", "releaseTime": "2010-02-14T00:00:01+00:00"},
+    {"id": "in-20100214-1", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/in-20100214-1/in-20100214-1.json", "time": "2017-09-20T00:00:00+00:00", "releaseTime": "2010-02-14T00:00:00+00:00"},
+    {"id": "in-20100212-2", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/in-20100212-2/in-20100212-2.json", "time": "2017-09-20T00:00:00+00:00", "releaseTime": "2010-02-12T00:00:01+00:00"},
+    {"id": "in-20100212-1", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/in-20100212-1/in-20100212-1.json", "time": "2017-09-20T00:00:00+00:00", "releaseTime": "2010-02-12T00:00:00+00:00"},
+    {"id": "in-20100207-2", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/in-20100207-2/in-20100207-2.json", "time": "2017-09-20T00:00:00+00:00", "releaseTime": "2010-02-07T00:00:01+00:00"},
+    {"id": "in-20100207-1", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/in-20100207-1/in-20100207-1.json", "time": "2017-09-20T00:00:00+00:00", "releaseTime": "2010-02-07T00:00:00+00:00"},
+    {"id": "in-20100206-2103", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/in-20100206-2103/in-20100206-2103.json", "time": "2020-10-14T18:51:02+00:00", "releaseTime": "2010-02-06T21:03:00+00:00"},
+    {"id": "in-20100203", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/in-20100203/in-20100203.json", "time": "2017-09-20T19:21:48+02:00", "releaseTime": "2010-02-03T00:30:00+02:00"},
+    {"id": "in-20100201-2", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/in-20100201-2/in-20100201-2.json", "time": "2017-09-20T19:21:48+02:00", "releaseTime": "2010-02-01T00:00:00+00:00"},
+    {"id": "in-20100201-3", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/in-20100201-3/in-20100201-3.json", "time": "2017-09-20T19:21:48+02:00", "releaseTime": "2010-02-01T00:00:00+00:00"},
+    {"id": "in-20100130", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/in-20100130/in-20100130.json", "time": "2013-08-06T07:33:30-07:00", "releaseTime": "2010-01-30T00:00:00-00:00"},
+    {"id": "in-20100129", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/in-20100129/in-20100129.json", "time": "2010-01-29T00:00:00-00:00", "releaseTime": "2010-01-29T00:00:00-00:00"},
+    {"id": "in-20100128-2304", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/in-20100128-2304/in-20100128-2304.json", "time": "2010-01-28T23:04:00-00:00", "releaseTime": "2010-01-28T23:04:00-00:00"},
+    {"id": "in-20100125-2", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/in-20100125-2/in-20100125-2.json", "time": "2017-09-20T00:00:00+00:00", "releaseTime": "2010-01-25T15:00:01-07:00"},
+    {"id": "in-20100125-1", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/in-20100125-1/in-20100125-1.json", "time": "2017-09-20T00:00:00+00:00", "releaseTime": "2010-01-25T15:00:00-07:00"},
+    {"id": "in-20100111-1", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/in-20100111-1/in-20100111-1.json", "time": "2017-09-20T00:00:00+00:00", "releaseTime": "2010-01-11T15:00:00-07:00"},
+    {"id": "in-20100105", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/in-20100105/in-20100105.json", "time": "2013-08-06T07:33:30-07:00", "releaseTime": "2010-01-05T00:00:00-00:00"},
+    {"id": "in-20091231-2", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/in-20091231-2/in-20091231-2.json", "time": "2021-06-26T22:48:05+00:00", "releaseTime": "2009-12-31T23:55:00+00:00"},
+    {"id": "in-20091223-2", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/in-20091223-2/in-20091223-2.json", "time": "2009-12-23T00:00:00-00:00", "releaseTime": "2009-12-23T00:00:00-00:00"},
+    {"id": "c0.30-2", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/c0.30-2/c0.30-2.json", "time": "2013-08-06T17:33:30+03:00", "releaseTime": "2009-11-10T00:00:01+02:00"},
+    {"id": "c0.30-1", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/c0.30-1/c0.30-1.json", "time": "2013-08-06T17:33:30+03:00", "releaseTime": "2009-11-10T00:00:00+02:00"},
+    {"id": "c0.29_02", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/c0.29_02/c0.29_02.json", "time": "2017-09-20T03:05:00+01:00", "releaseTime": "2009-10-30T00:00:00+00:00"},
+    {"id": "c0.29_01", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/c0.29_01/c0.29_01.json", "time": "2021-06-26T12:16:50+00:00", "releaseTime": "2009-10-29T00:00:00+00:00"},
+    {"id": "c0.28_01", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/c0.28_01/c0.28_01.json", "time": "2017-09-20T03:19:48+01:00", "releaseTime": "2009-10-27T00:00:00+00:00"},
+    {"id": "c0.27_st", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/c0.27_st/c0.27_st.json", "time": "2017-09-17T16:33:30+02:00", "releaseTime": "2009-10-24T24:00:00+00:00"},
+    {"id": "c0.25_05_st", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/c0.25_05_st/c0.25_05_st.json", "time": "2009-09-03T00:00:00+00:00", "releaseTime": "2009-09-03T00:00:00+00:00"},
+    {"id": "c0.24_st_03", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/c0.24_st_03/c0.24_st_03.json", "time": "2009-09-01T00:00:00+00:00", "releaseTime": "2009-09-01T00:00:00+00:00"},
+    {"id": "c0.0.22a_05", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/c0.0.22a_05/c0.0.22a_05.json", "time": "2009-06-30T00:00:00+00:00", "releaseTime": "2009-06-30T00:00:00+00:00"},
+    {"id": "c0.0.21a", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/c0.0.21a/c0.0.21a.json", "time": "2017-09-20T03:12:34+01:00", "releaseTime": "2009-06-22T23:11:11+01:00"},
+    {"id": "c0.0.20a_01", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/c0.0.20a_01/c0.0.20a_01.json", "time": "2020-10-14T23:51:10+00:00", "releaseTime": "2009-06-20T23:10:00+00:00"},
+    {"id": "c0.0.19a_06-2", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/c0.0.19a_06-2/c0.0.19a_06-2.json", "time": "2020-10-17T19:47:58-00:00", "releaseTime": "2009-06-20T01:37:00-00:00"},
+    {"id": "c0.0.18a_02", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/c0.0.18a_02/c0.0.18a_02.json", "time": "2020-10-15T18:45:15-00:00", "releaseTime": "2009-06-14T10:53:00-00:00"},
+    {"id": "c0.0.17a", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/c0.0.17a/c0.0.17a.json", "time": "2021-04-17T21:49:29-00:00", "releaseTime": "2009-06-10T20:14:00-00:00"},
+    {"id": "c0.0.16a_02", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/c0.0.16a_02/c0.0.16a_02.json", "time": "2019-10-20T21:42:41+00:00", "releaseTime": "2009-06-08T12:47:00+00:00"},
+    {"id": "c0.0.23a_01", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/c0.0.23a_01/c0.0.23a_01.json", "time": "2013-08-06T15:33:30+01:00", "releaseTime": "2009-05-28T23:11:11+01:00"},
+    {"id": "c0.0.14a_08", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/c0.0.14a_08/c0.0.14a_08.json", "time": "2019-10-20T21:41:28+00:00", "releaseTime": "2009-05-28T22:37:00+00:00"},
+    {"id": "c0.0.12a_03", "type": "old_alpha", "url": "https://zkitefly.github.io/unlisted-versions-of-minecraft/files/c0.0.12a_03/c0.0.12a_03.json", "time": "2021-04-26T19:18:00-00:00", "releaseTime": "2009-05-20T00:00:00-00:00"}
+  ]
+}
diff --git a/crates/core/src/game/error.rs b/crates/core/src/game/error.rs
new file mode 100644
index 0000000..f2601e1
--- /dev/null
+++ b/crates/core/src/game/error.rs
@@ -0,0 +1,124 @@
+//! `core::game` 的错误类型。
+//!
+//! 采用手写 `Display`/`Error` 而不用 `thiserror`：core 的依赖面越窄越好（D3 模块纪律），
+//! 且这里的变体数量固定、不需要派生宏的收益。
+
+use std::fmt;
+use std::path::PathBuf;
+
+/// `core::game` 的失败集合。
+#[derive(Debug)]
+pub enum GameError {
+    /// JSON 解析/序列化失败（版本清单、版本 JSON、profiles）。
+    Json {
+        /// 出错的文档种类，用于给用户看上下文（如 `version_manifest_v2`）。
+        context: String,
+        /// 底层 serde_json 错误。
+        source: serde_json::Error,
+    },
+    /// 清单或版本 JSON 缺少必需的 `id`。
+    MissingVersionId,
+    /// `inheritsFrom` 指向的父版本在本仓库中不存在。
+    MissingParent {
+        /// 缺失的父版本 id。
+        parent: String,
+        /// 发起继承的子版本 id。
+        required_by: String,
+    },
+    /// `inheritsFrom` 成环。
+    CircularInheritance {
+        /// 从根到环的 id 链（首尾为同一个 id）。
+        chain: Vec<String>,
+    },
+    /// Maven 坐标（`group:artifact:version[:classifier][@ext]`）不合法。
+    InvalidCoordinate {
+        /// 原始字符串。
+        raw: String,
+        /// 不合法的原因。
+        reason: &'static str,
+    },
+    /// 资源对象哈希不合法（长度不足以做两级分片）。
+    InvalidAssetHash {
+        /// 原始哈希。
+        hash: String,
+    },
+    /// 文件系统错误。
+    Io {
+        /// 出错的路径。
+        path: PathBuf,
+        /// 底层 IO 错误。
+        source: std::io::Error,
+    },
+    /// 已有草稿持有写权，同一仓库同时只允许一个写会话。
+    DraftBusy,
+    /// 实例隔离档位是 `custom`，但没有可用的自定义目录（不猜默认值）。
+    CustomIsolationWithoutDir {
+        /// 实例 id（可能为空：调用方没给实例上下文）。
+        instance: String,
+    },
+}
+
+impl fmt::Display for GameError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Json { context, source } => write!(f, "解析 {context} 失败: {source}"),
+            Self::MissingVersionId => write!(f, "版本 JSON 缺少 id"),
+            Self::MissingParent {
+                parent,
+                required_by,
+            } => write!(
+                f,
+                "版本 {required_by} 继承的父版本 {parent} 不存在（缺失前置版本）"
+            ),
+            Self::CircularInheritance { chain } => {
+                write!(f, "版本继承成环: {}", chain.join(" -> "))
+            }
+            Self::InvalidCoordinate { raw, reason } => {
+                write!(f, "Maven 坐标不合法（{reason}）: {raw}")
+            }
+            Self::InvalidAssetHash { hash } => {
+                write!(f, "资源哈希不合法（短于两个字符）: {hash}")
+            }
+            Self::Io { path, source } => write!(f, "IO 失败 {}: {source}", path.display()),
+            Self::DraftBusy => write!(f, "已有草稿持有写权（单写者约束）"),
+            Self::CustomIsolationWithoutDir { instance } => {
+                if instance.is_empty() {
+                    write!(f, "隔离档位为 custom，但没有指定自定义运行目录")
+                } else {
+                    write!(
+                        f,
+                        "实例 {instance} 的隔离档位为 custom，但没有指定自定义运行目录"
+                    )
+                }
+            }
+        }
+    }
+}
+
+impl std::error::Error for GameError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            Self::Json { source, .. } => Some(source),
+            Self::Io { source, .. } => Some(source),
+            _ => None,
+        }
+    }
+}
+
+impl GameError {
+    /// 包装 serde_json 错误并带上文档上下文。
+    pub fn json(context: impl Into<String>, source: serde_json::Error) -> Self {
+        Self::Json {
+            context: context.into(),
+            source,
+        }
+    }
+
+    /// 包装 IO 错误并带上路径。
+    pub fn io(path: impl Into<PathBuf>, source: std::io::Error) -> Self {
+        Self::Io {
+            path: path.into(),
+            source,
+        }
+    }
+}
diff --git a/crates/core/src/game/inherit.rs b/crates/core/src/game/inherit.rs
new file mode 100644
index 0000000..2760ac4
--- /dev/null
+++ b/crates/core/src/game/inherit.rs
@@ -0,0 +1,198 @@
+//! `inheritsFrom` 继承解析、逐字段合并语义、patch 优先级排序。
+//!
+//! 依据：`DevDocs/analyse/03-version-download.md` §4.3（`resolve()`）、§4.4（merge 语义表）、
+//! §4.5（patch 生命周期）。
+//!
+//! 与 HMCL 的三处**有意差异**（都在 §4.3 的对照里）：
+//! 1. **成环即报错**（[`GameError::CircularInheritance`]）而不是"断链后降级启动"：
+//!    静默降级会让用户拿到"能启动但缺库"的实例，宁可明确告知清单坏了。
+//! 2. **缺失父版本报错**（[`GameError::MissingParent`]），与 HMCL 的
+//!    `NoSuchGameInstanceException` 一致。
+//! 3. 不实现 `toPatch()` 的"把已解析父层固化进 patches"优化——P0 实例数量小，
+//!    每次启动重算继承链（毫秒级）；等有性能证据再加缓存。
+
+use std::collections::BTreeMap;
+
+use super::arguments::Arguments;
+use super::error::GameError;
+use super::manifest::VersionJson;
+
+/// 父版本来源（仓库快照或测试里的内存表）。
+pub trait VersionSource {
+    /// 按 id 取一份版本 JSON；不存在返回 `None`。
+    ///
+    /// 实现方应自行处理 IO 错误——把失败转成 `None` 会让"父版本缺失"和"读盘失败"
+    /// 混为一谈，因此读盘失败的实现应当在调用 [`resolve`] 前就把它暴露给用户。
+    fn load(&self, id: &str) -> Option<VersionJson>;
+}
+
+impl VersionSource for BTreeMap<String, VersionJson> {
+    fn load(&self, id: &str) -> Option<VersionJson> {
+        self.get(id).cloned()
+    }
+}
+
+impl<F> VersionSource for F
+where
+    F: Fn(&str) -> Option<VersionJson>,
+{
+    fn load(&self, id: &str) -> Option<VersionJson> {
+        self(id)
+    }
+}
+
+/// 解析继承链，返回可交给 launch/download 的扁平清单。
+///
+/// 返回的清单保证：`inherits_from == None`、`patches == None`、`jar` 已回退为实例 id、
+/// `root == Some(true)`（见 [`VersionJson::is_resolved`]）。
+///
+/// # Errors
+///
+/// - 清单缺 `id` → [`GameError::MissingVersionId`]
+/// - 父版本缺失 → [`GameError::MissingParent`]
+/// - 继承成环 → [`GameError::CircularInheritance`]
+pub fn resolve<S: VersionSource>(
+    source: &S,
+    manifest: &VersionJson,
+) -> Result<VersionJson, GameError> {
+    let root_id = manifest.require_id()?.to_owned();
+
+    // 1. 自根向祖先收集层（迭代而非递归：深层整合包的链可以很长）。
+    let mut chain = vec![root_id.clone()];
+    let mut layers = vec![manifest.clone()];
+    while let Some(parent_id) = layers.last().and_then(|l| l.inherits_from.clone()) {
+        if chain.iter().any(|id| id == &parent_id) {
+            chain.push(parent_id);
+            return Err(GameError::CircularInheritance { chain });
+        }
+        let required_by = layers
+            .last()
+            .and_then(|l| l.id.clone())
+            .unwrap_or_else(|| root_id.clone());
+        let parent = source
+            .load(&parent_id)
+            .ok_or_else(|| GameError::MissingParent {
+                parent: parent_id.clone(),
+                required_by,
+            })?;
+        chain.push(parent_id);
+        layers.push(parent);
+    }
+
+    // 2. 自最祖先向根折叠：每一层先与父层合并，再合并它自己的 patches。
+    let mut folded: Option<VersionJson> = None;
+    for layer in layers.into_iter().rev() {
+        let merged = match &folded {
+            Some(parent) => merge(&layer, parent),
+            None => merge(&layer, &VersionJson::default()),
+        };
+        folded = Some(apply_patches(
+            merged,
+            &layer.patches.clone().unwrap_or_default(),
+        ));
+    }
+
+    // 3. 收尾：清继承标记、jar 兜底、补 id。
+    let mut resolved = folded.unwrap_or_default();
+    resolved.inherits_from = None;
+    resolved.patches = None;
+    resolved.priority = None;
+    resolved.root = Some(true);
+    if resolved.id.is_none() {
+        resolved.id = Some(root_id.clone());
+    }
+    if resolved.jar.is_none() {
+        resolved.jar = Some(root_id);
+    }
+    Ok(resolved)
+}
+
+/// 按 `priority` 升序排好的 patch 列表（`None` 视作最小值，稳定排序保持插入顺序）。
+pub fn sorted_patches(patches: &[VersionJson]) -> Vec<&VersionJson> {
+    let mut sorted: Vec<&VersionJson> = patches.iter().collect();
+    sorted.sort_by_key(|p| p.priority.unwrap_or(i32::MIN));
+    sorted
+}
+
+/// 把 patch 层按优先级依次叠加到基底清单上（先原版、后 loader：`0 < 30000`）。
+pub fn apply_patches(base: VersionJson, patches: &[VersionJson]) -> VersionJson {
+    let mut out = base;
+    for patch in sorted_patches(patches) {
+        out = merge(patch, &out);
+    }
+    out
+}
+
+/// 合并两层清单：**子（或后合并的层）覆盖父**，语义逐字段照 analyse/03 §4.4。
+///
+/// 非直觉的两点，测试里各有一条守门：
+/// - `downloads`/`logging` **整体覆盖**：子层只写 `server` 会让父层的 `client` 消失；
+/// - `compliance_level` **只取子**：父层的值被丢弃（缺则是 `None`）。
+///
+/// 这两点**与 analyse/03 §8.3 第 15 条建议相左**（该条主张逐字段/逐 key 合并）。
+/// 保留现状的理由是生态兼容：现实 modpack/loader 的版本 JSON 按 HMCL/原版语义编写，
+/// 逐 key 合并会让"子层想整份换掉 downloads"的场景语义漂移。经 tower 裁决 2026-10-29 维持。
+pub fn merge(child: &VersionJson, parent: &VersionJson) -> VersionJson {
+    let mut extra = parent.extra.clone();
+    extra.extend(child.extra.iter().map(|(k, v)| (k.clone(), v.clone())));
+
+    VersionJson {
+        id: child.id.clone().or_else(|| parent.id.clone()),
+        name: child.name.clone().or_else(|| parent.name.clone()),
+        // 解析后不再带继承。
+        inherits_from: None,
+        jar: child.jar.clone().or_else(|| parent.jar.clone()),
+        main_class: child
+            .main_class
+            .clone()
+            .or_else(|| parent.main_class.clone()),
+        minecraft_arguments: child
+            .minecraft_arguments
+            .clone()
+            .or_else(|| parent.minecraft_arguments.clone()),
+        arguments: Arguments::merge(parent.arguments.as_ref(), child.arguments.as_ref()),
+        assets: child.assets.clone().or_else(|| parent.assets.clone()),
+        asset_index: child
+            .asset_index
+            .clone()
+            .or_else(|| parent.asset_index.clone()),
+        compliance_level: child.compliance_level,
+        java_version: child
+            .java_version
+            .clone()
+            .or_else(|| parent.java_version.clone()),
+        libraries: match (&parent.libraries, &child.libraries) {
+            (None, None) => None,
+            (Some(parent), None) => Some(parent.clone()),
+            (None, Some(child)) => Some(child.clone()),
+            // 父在前、子在后追加（重复项由使用方按需去重）。
+            (Some(parent), Some(child)) => {
+                Some(parent.iter().chain(child.iter()).cloned().collect())
+            }
+        },
+        // 整体覆盖，不逐 key 合并。
+        downloads: child.downloads.clone().or_else(|| parent.downloads.clone()),
+        logging: child.logging.clone().or_else(|| parent.logging.clone()),
+        version_type: child.version_type.or(parent.version_type),
+        time: child.time.clone().or_else(|| parent.time.clone()),
+        release_time: child
+            .release_time
+            .clone()
+            .or_else(|| parent.release_time.clone()),
+        minimum_launcher_version: match (
+            parent.minimum_launcher_version,
+            child.minimum_launcher_version,
+        ) {
+            (Some(a), Some(b)) => Some(a.max(b)),
+            (a, None) => a,
+            (None, b) => b,
+        },
+        // 合并结果一律是"根清单"。
+        root: Some(true),
+        hidden: child.hidden,
+        // patch 生命周期由 resolve/apply_patches 管，合并结果不带 patches。
+        patches: None,
+        priority: None,
+        extra,
+    }
+}
diff --git a/crates/core/src/game/install/assets.rs b/crates/core/src/game/install/assets.rs
new file mode 100644
index 0000000..fefcd83
--- /dev/null
+++ b/crates/core/src/game/install/assets.rs
@@ -0,0 +1,190 @@
+//! 资源索引（`assets/indexes/<id>.json`）的模型与逐对象展开。
+//!
+//! 依据：`DevDocs/analyse/03-version-download.md` §6.5（索引下载）、§6.6（逐对象下载）。
+//!
+//! 对象是**内容寻址**的：路径 `assets/objects/<hash[0..2]>/<hash>`、URL
+//! `https://resources.download.minecraft.net/<hash[0..2]>/<hash>`，校验值就是哈希本身。
+//! 因此索引里不需要 `sha1` 字段——文件名即摘要，这也是"两个实例共用同一资源"零成本的原因。
+//!
+//! 本模块只做"索引 → 待下载对象"的纯计算，不碰网络；落盘路径一律问
+//! [`GameLayout`]，不在本地拼字符串。
+
+use std::collections::BTreeMap;
+
+use serde::{Deserialize, Serialize};
+
+use super::super::error::GameError;
+use super::super::layout::GameLayout;
+use super::plan::{FileRole, PlanFile};
+use crate::download::ResourceKind;
+
+/// 资源对象的官方源基址。
+pub const ASSET_OBJECT_BASE: &str = "https://resources.download.minecraft.net";
+
+/// 一个资源对象。
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AssetObject {
+    /// 内容 SHA-1（同时是文件名）。
+    #[serde(default)]
+    pub hash: String,
+    /// 字节数。
+    #[serde(default)]
+    pub size: u64,
+}
+
+impl AssetObject {
+    /// 相对 `assets/objects/` 的路径 `xx/<hash>`。
+    #[must_use]
+    pub fn location(&self) -> String {
+        let shard = self.hash.get(0..2).unwrap_or_default();
+        format!("{shard}/{}", self.hash)
+    }
+
+    /// 官方下载地址（镜像由下载引擎按前缀规则展开）。
+    #[must_use]
+    pub fn url(&self) -> String {
+        format!("{ASSET_OBJECT_BASE}/{}", self.location())
+    }
+
+    /// 哈希是否够做两级分片（短于两个字符说明索引坏了）。
+    #[must_use]
+    pub fn is_well_formed(&self) -> bool {
+        self.hash.len() >= 2 && self.hash.bytes().all(|b| b.is_ascii_hexdigit())
+    }
+}
+
+/// 一份资源索引。
+///
+/// `virtual` / `map_to_resources` 只影响**启动期**的目录映射（`assets/virtual/<id>`、
+/// `resources/`），不影响下载，这里保真存下但不消费。
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AssetIndex {
+    /// 对象表：键是资源名（`minecraft/sounds/...ogg`），值是内容描述。
+    #[serde(default)]
+    pub objects: BTreeMap<String, AssetObject>,
+    /// 旧版：是否要在启动期铺到 `assets/virtual/<id>/`。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub r#virtual: Option<bool>,
+    /// 旧版：是否要映射到存档目录旁的 `resources/`。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub map_to_resources: Option<bool>,
+}
+
+impl AssetIndex {
+    /// 解析索引 JSON。
+    ///
+    /// # Errors
+    ///
+    /// JSON 非法（例如镜像返回了 HTML 错误页）时返回 [`GameError::Json`]。
+    pub fn from_json_slice(bytes: &[u8]) -> Result<Self, GameError> {
+        serde_json::from_slice(bytes).map_err(|e| GameError::json("asset_index", e))
+    }
+
+    /// 对象数量。
+    #[must_use]
+    pub fn len(&self) -> usize {
+        self.objects.len()
+    }
+
+    /// 是否没有对象。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.objects.is_empty()
+    }
+
+    /// 全部对象的总字节数（进度预算与 `--dry-run` 总大小用）。
+    #[must_use]
+    pub fn total_bytes(&self) -> u64 {
+        self.objects.values().map(|object| object.size).sum()
+    }
+}
+
+/// 把索引展开成待下载文件清单（按资源名排序，保证计划可复现）。
+///
+/// # Errors
+///
+/// 某个对象哈希不合法（短于两字符 / 非十六进制）时返回 [`GameError::InvalidAssetHash`]。
+pub fn plan(layout: &GameLayout, index: &AssetIndex) -> Result<Vec<PlanFile>, GameError> {
+    let mut files = Vec::with_capacity(index.objects.len());
+    for (name, object) in &index.objects {
+        if !object.is_well_formed() {
+            return Err(GameError::InvalidAssetHash {
+                hash: object.hash.clone(),
+            });
+        }
+        files.push(PlanFile {
+            role: FileRole::Asset,
+            name: name.clone(),
+            url: object.url(),
+            sha1: Some(object.hash.clone()),
+            size: Some(object.size),
+            dest: layout.asset_object(&object.hash)?,
+            resource: ResourceKind::Asset,
+        });
+    }
+    Ok(files)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{plan, AssetIndex, AssetObject};
+    use crate::game::layout::GameLayout;
+
+    const HASH: &str = "0f9d6b1c0d5f4e3b2a1908070605040302010f0e";
+
+    #[test]
+    fn location_and_url_use_two_char_shard() {
+        let object = AssetObject {
+            hash: HASH.to_string(),
+            size: 7,
+        };
+        assert_eq!(object.location(), format!("0f/{HASH}"));
+        assert_eq!(
+            object.url(),
+            format!("https://resources.download.minecraft.net/0f/{HASH}")
+        );
+    }
+
+    #[test]
+    fn parses_index_and_plans_objects() {
+        let json = format!(
+            r#"{{"objects":{{"minecraft/lang/zh_cn.json":{{"hash":"{HASH}","size":42}}}}}}"#
+        );
+        let index = AssetIndex::from_json_slice(json.as_bytes()).expect("索引应可解析");
+        assert_eq!(index.len(), 1);
+        assert_eq!(index.total_bytes(), 42);
+
+        let layout = GameLayout::new("/games/.minecraft");
+        let files = plan(&layout, &index).expect("展开应成功");
+        assert_eq!(files.len(), 1);
+        let file = &files[0];
+        assert_eq!(file.sha1.as_deref(), Some(HASH));
+        assert_eq!(file.size, Some(42));
+        assert!(file.dest.ends_with(format!("objects/0f/{HASH}")));
+    }
+
+    #[test]
+    fn rejects_short_hash() {
+        let mut index = AssetIndex::default();
+        index.objects.insert(
+            "a".to_string(),
+            AssetObject {
+                hash: "a".to_string(),
+                size: 1,
+            },
+        );
+        let layout = GameLayout::new("/games/.minecraft");
+        assert!(plan(&layout, &index).is_err());
+    }
+
+    #[test]
+    fn keeps_asset_keys_as_names() {
+        let json = format!(
+            r#"{{"objects":{{"icons/icon_16x16.png":{{"hash":"{HASH}","size":1}},"lang/en_us.json":{{"hash":"{HASH}","size":2}}}}}}"#
+        );
+        let index = AssetIndex::from_json_slice(json.as_bytes()).expect("索引应可解析");
+        let files = plan(&GameLayout::new("/g"), &index).expect("展开应成功");
+        let names: Vec<&str> = files.iter().map(|f| f.name.as_str()).collect();
+        assert_eq!(names, vec!["icons/icon_16x16.png", "lang/en_us.json"]);
+    }
+}
diff --git a/crates/core/src/game/install/execute.rs b/crates/core/src/game/install/execute.rs
new file mode 100644
index 0000000..f5c380a
--- /dev/null
+++ b/crates/core/src/game/install/execute.rs
@@ -0,0 +1,339 @@
+//! 落盘执行：跳过判定 → 并发下载（引擎负责镜像/退避/续传/校验）→ 原子写版本 JSON。
+//!
+//! 依据：`DevDocs/analyse/03-version-download.md` §6.9（完整性修复路径的"存在即信"分级）、
+//! `DevDocs/PlanDoc/05-download-and-mirrors.md` §2（按资源类型分层）、§5（静态展开并行度）。
+//!
+//! # 跳过判定（幂等的地基）
+//!
+//! 判据分三级，与 analyse/03 §6.9 的思路一致：
+//! - 有 sha1 → **重算摘要比对**（唯一可信判据；代价是读一遍盘）；
+//! - 无 sha1 有大小 → 只比大小（清单没给摘要时退一步）；
+//! - 两者都没有 → 存在即信（HMCL 同类做法，留给后续"一键修复"补校验）。
+//!
+//! 跳过不写盘、不进网络，因此"重复 install 同版本"第二次几乎零成本。
+//!
+//! # 失败策略
+//!
+//! **不整体回滚**：已下好的共享层文件（libraries/assets）留在原地复用，失败信息逐文件结构化
+//! 返回，由调用方决定是重试、还是只提示"缺哪几个文件"。这与 analyse/03 §6.3 的"宁可给出
+//! 可修复的骨架"一致，但**版本清单与实例登记只在全量成功后才写**，不会出现半实例。
+//!
+//! # 取消（M105：GUI 的「取消安装」要**真停**）
+//!
+//! [`execute`] 与 CLI 的契约**一字不变**（不传取消标志 = 今天的行为）；
+//! 取消走 [`execute_with_cancel`]，判据三条：
+//!
+//! 1. **不再起新文件**：流里**每个 item 的第一句**就看标志，置位直接返回 `None` ⇒
+//!    那些 item **连 `install_one` 都不进**（不发请求、不算整文件 sha1、不回调 `sink`）。
+//!    这一句不能挪到 `select` 的右支：`select` 先轮询左支，左支第一次 poll 就把
+//!    `engine.download(…)` 派出去了（复审 P2-1 就是从这条抓出来的）。
+//! 2. **在飞的文件就地掐断**：`install_one` 与「取消 future」`select` 赛跑，
+//!    取消赢就 drop 掉下载 future —— reqwest 的响应流随之关闭（socket 断开），
+//!    `.ullpart` 由 [`PartFile`](crate::download::PartFile) 的 `Drop` 清掉（不留半截垃圾）。
+//! 3. **半成品不许变成品**：取消后不再写版本 JSON，返回
+//!    [`InstallErrorKind::Cancelled`](super::InstallErrorKind)，调用方（presenter）据此把阶段
+//!    记成「已取消」而不是「失败」。
+//!
+//! 于是取消延迟 = **一个数据块的唤醒**（不是「等一个文件下完」，也不是「等这一段跑完」）。
+//!
+//! ## 固有边界（复审要求留档，别把它当 bug 修）
+//!
+//! `buffer_unordered(concurrency)` 在取消那一刻**已经有最多 `concurrency`（GUI 传 16）个 future
+//! 被拉起来了**，它们已经过了第 1 条那道门。所以最坏情况下这 16 个文件里：
+//!
+//! - **盘上已就绪的**（第一 poll 就 `Ready`）会照常「跑完」并被回调一次 `sink` ——
+//!   presenter 侧靠**安装代次**（`CoreHost::install_epoch`）把这些回调带来的进度事件丢掉，
+//!   所以面板不会因此复燃；
+//! - **真在下载的**会在同一次 poll 的右支被取消掉（future drop、连接关掉、`.ullpart` 清掉）。
+//!
+//! 也就是说：**「取消之后一个字节都不会再写」这句话只对「还没被拉起的 item」成立**；
+//! 在飞的 16 个里已就绪的那些仍会走完自己的回调。要连这一步都收掉，得让
+//! `buffer_unordered` 支持「取消即清空队列」，本轮不做（不在 M105 的验收口径里）。
+
+use std::future::poll_fn;
+use std::path::Path;
+use std::pin::pin;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::task::Poll;
+
+use futures_util::future::{select, Either};
+use futures_util::stream::{self, StreamExt};
+
+use super::plan::PlanFile;
+use super::{InstallError, InstallErrorKind, InstallPlan};
+use crate::download::verify;
+use crate::download::{DownloadEngine, DownloadError, DownloadErrorKind, HashAlgo};
+use crate::platform::atomic::write_atomic;
+
+pub use super::report::{FileFailure, FileOutcome, FileStatus, InstallReport, ProgressSink};
+
+/// 执行安装计划。
+///
+/// 具体步骤：
+/// 1. 规划期已取到的元数据（资源索引，见 [`InstallPlan::prefetch`]）先原子落盘，零网络；
+/// 2. 其余文件并发下载（`concurrency` 上限，引擎内部另有信号量），每个文件带进度回调；
+/// 3. **全量就绪**才写 `versions/<id>/<id>.json`：这份清单是"已安装"的判据
+///    （[`GameLayout::is_version_installed`]），半成品写进去会把缺件的版本报成已安装。
+///    共享层里已下好的文件留着复用，重跑 `ull install` 会补齐剩下的。
+///
+/// # Errors
+///
+/// 版本 JSON 落盘失败时返回 IO 错误；文件下载失败**不**返回错误，而是进
+/// [`InstallReport`]（调用方按 [`InstallReport::is_complete`] 决策）。
+pub async fn execute(
+    engine: &DownloadEngine,
+    plan: &InstallPlan,
+    concurrency: usize,
+    sink: Option<ProgressSink>,
+) -> Result<InstallReport, super::InstallError> {
+    execute_with_cancel(engine, plan, concurrency, sink, None).await
+}
+
+/// 同 [`execute`]，但可以带一个**取消标志**（M105）。
+///
+/// `cancel = None` 与 [`execute`] 逐字等价（CLI 走这条）；`Some(flag)` 时：
+/// 置位就不再起新文件、并就地掐断在飞的文件，最后返回
+/// [`InstallErrorKind::Cancelled`]（**不写版本 JSON**）。
+///
+/// # Errors
+///
+/// 同 [`execute`]；另外取消时返回 `Cancelled` 大类。
+pub async fn execute_with_cancel(
+    engine: &DownloadEngine,
+    plan: &InstallPlan,
+    concurrency: usize,
+    sink: Option<ProgressSink>,
+    cancel: Option<&AtomicBool>,
+) -> Result<InstallReport, super::InstallError> {
+    if is_cancelled(cancel) {
+        return Err(cancelled_error());
+    }
+    let mut outcomes: Vec<FileOutcome> = Vec::with_capacity(plan.files.len());
+    let mut prefetched: Vec<&PlanFile> = Vec::new();
+
+    for payload in &plan.prefetched {
+        let Some(file) = plan.files.iter().find(|file| file.dest == payload.dest) else {
+            continue;
+        };
+        // 盘上已是同一份内容就不再重写（规划期为了枚举对象必须联网取索引，
+        // 但那不等于"需要重新落盘"——重装的"下载 0 个"要名副其实）。
+        if let Some(bytes) = current_bytes(file) {
+            let outcome = FileOutcome {
+                role: file.role,
+                name: file.name.clone(),
+                dest: file.dest.clone(),
+                status: FileStatus::Skipped,
+                bytes,
+                source: None,
+                failure: None,
+            };
+            if let Some(sink) = &sink {
+                sink(&outcome);
+            }
+            outcomes.push(outcome);
+            prefetched.push(file);
+            continue;
+        }
+        let written = write_atomic(&payload.dest, &payload.bytes).map_err(|error| {
+            super::InstallError::new(super::InstallErrorKind::Io, error.to_string())
+        });
+        let outcome = match written {
+            Ok(()) => FileOutcome {
+                role: file.role,
+                name: file.name.clone(),
+                dest: file.dest.clone(),
+                status: FileStatus::Downloaded,
+                bytes: payload.bytes.len() as u64,
+                source: Some("metadata".to_string()),
+                failure: None,
+            },
+            Err(error) => FileOutcome {
+                role: file.role,
+                name: file.name.clone(),
+                dest: file.dest.clone(),
+                status: FileStatus::Failed,
+                bytes: 0,
+                source: None,
+                failure: Some(FileFailure {
+                    kind: DownloadErrorKind::Io,
+                    message: error.to_string(),
+                }),
+            },
+        };
+        if let Some(sink) = &sink {
+            sink(&outcome);
+        }
+        outcomes.push(outcome);
+        prefetched.push(file);
+    }
+
+    let pending: Vec<&PlanFile> = plan
+        .files
+        .iter()
+        .filter(|file| !prefetched.iter().any(|done| done.dest == file.dest))
+        .collect();
+
+    let downloaded: Vec<FileOutcome> = stream::iter(pending)
+        .map(|file| {
+            let sink = sink.clone();
+            async move {
+                // **每个 item 的第一句就查标志**（复审 P2-1，p1）：`select` 先轮询左支，
+                // 左支第一次 poll 就会把 `engine.download(...)` 派发出去 —— 只把标志检查写在
+                // `select` 的右支，等于「取消之后每个剩余文件仍各发一次整文件 sha1 + 一次请求」，
+                // 1.20.1 那种四位数文件的 plan 会一直走到列表末尾，而且「盘上已就绪」的文件
+                // 第一 poll 就 `Ready` ⇒ 还会各回调一次 `sink`。
+                // 放在这里，取消后这些 item **连 `install_one` 都不进**。
+                if is_cancelled(cancel) {
+                    return None;
+                }
+                // 已经开始的那些（`buffer_unordered` 在飞，最多 `concurrency` 个）与取消 future 赛跑：
+                // 取消赢就 drop 掉下载 future（响应流关闭 + `.ullpart` 由 `PartFile::Drop` 清掉）。
+                let outcome = match cancel {
+                    Some(flag) => {
+                        let download = install_one(engine, file);
+                        let abort = cancelled(flag);
+                        let mut download = pin!(download);
+                        let mut abort = pin!(abort);
+                        match select(download.as_mut(), abort.as_mut()).await {
+                            Either::Left((outcome, _)) => Some(outcome),
+                            Either::Right(((), _)) => None,
+                        }
+                    }
+                    None => Some(install_one(engine, file).await),
+                };
+                if let (Some(sink), Some(outcome)) = (&sink, &outcome) {
+                    sink(outcome);
+                }
+                outcome
+            }
+        })
+        .buffer_unordered(concurrency.max(1))
+        .filter_map(|outcome| async move { outcome })
+        .collect()
+        .await;
+    outcomes.extend(downloaded);
+
+    // 取消了就到此为止：**不写版本清单**（否则半成品会被 `is_version_installed()` 当成已安装）。
+    if is_cancelled(cancel) {
+        return Err(cancelled_error());
+    }
+
+    // 版本清单只在**全量就绪**时落盘：`is_version_installed()` 以清单存在为判据，
+    // 半成品写进去会让 `instances list` 把"缺 jar 的版本"报成已安装。
+    let complete = outcomes.iter().all(|outcome| !outcome.failed());
+    let version_json = if complete {
+        write_version_json(&plan.version_json_path, plan)?;
+        Some(plan.version_json_path.clone())
+    } else {
+        None
+    };
+
+    Ok(InstallReport {
+        files: outcomes,
+        version_json,
+        warnings: plan.warnings.clone(),
+    })
+}
+
+/// 标志是否已置位（`None` = 没有取消通道，永远 false）。
+///
+/// 用 `SeqCst` 与 presenter 侧 `store` 的强度一致：这里不是性能热点（每个文件一次），
+/// 换更强的顺序只买一个「不给自己留疑问」。
+fn is_cancelled(cancel: Option<&AtomicBool>) -> bool {
+    cancel.is_some_and(|flag| flag.load(Ordering::SeqCst))
+}
+
+/// 取消 future：标志一置位就 `Ready`，否则永远 `Pending`（不注册 waker）。
+///
+/// 为什么敢用「不注册 waker 的 Pending」：它只跟下载 future 一起被 `select` 轮询，
+/// 下载每读到一个数据块就会唤醒 executor、连带重新 poll 这个 future，所以取消延迟
+/// 天然是「一个数据块」；真正卡死的连接另有读超时兜底（`chunked` 的 30 s）。
+async fn cancelled(flag: &AtomicBool) {
+    poll_fn(|_| {
+        if flag.load(Ordering::SeqCst) {
+            Poll::Ready(())
+        } else {
+            Poll::Pending
+        }
+    })
+    .await;
+}
+
+/// 取消的稳定错误（大类 `Cancelled`，不是失败）。
+fn cancelled_error() -> InstallError {
+    InstallError::new(
+        InstallErrorKind::Cancelled,
+        "已取消：剩下的文件没有开始下载，已下好的文件保留（重装续用）",
+    )
+}
+
+/// 单文件：先判"已就绪"，否则走引擎下载。
+async fn install_one(engine: &DownloadEngine, file: &PlanFile) -> FileOutcome {
+    if let Some(bytes) = current_bytes(file) {
+        return FileOutcome {
+            role: file.role,
+            name: file.name.clone(),
+            dest: file.dest.clone(),
+            status: FileStatus::Skipped,
+            bytes,
+            source: None,
+            failure: None,
+        };
+    }
+    match engine.download(file.request()).await {
+        Ok(outcome) => FileOutcome {
+            role: file.role,
+            name: file.name.clone(),
+            dest: file.dest.clone(),
+            status: FileStatus::Downloaded,
+            bytes: outcome.bytes,
+            source: Some(outcome.source),
+            failure: None,
+        },
+        Err(error) => FileOutcome {
+            role: file.role,
+            name: file.name.clone(),
+            dest: file.dest.clone(),
+            status: FileStatus::Failed,
+            bytes: 0,
+            source: None,
+            failure: Some(describe(&error)),
+        },
+    }
+}
+
+/// 文件已就绪则返回盘上大小（跳过判定，见模块文档的三级分级）。
+#[must_use]
+pub fn current_bytes(file: &PlanFile) -> Option<u64> {
+    if !file.dest.is_file() {
+        return None;
+    }
+    let size = std::fs::metadata(&file.dest).ok()?.len();
+    match file.sha1.as_deref().filter(|hex| !hex.is_empty()) {
+        Some(expected) => {
+            let actual = verify::digest_file(&file.dest, HashAlgo::Sha1).ok()?;
+            verify::matches(expected, &actual).then_some(size)
+        }
+        None => match file.size {
+            Some(expected) => (size == expected).then_some(size),
+            // 没有摘要也没有大小：存在即信（后续"一键修复"再补校验）。
+            None => Some(size),
+        },
+    }
+}
+
+/// 写解析后的版本清单（原子写）。
+fn write_version_json(path: &Path, plan: &InstallPlan) -> Result<(), super::InstallError> {
+    let text = plan.version_json.to_json_string().map_err(|error| {
+        super::InstallError::new(super::InstallErrorKind::Metadata, error.to_string())
+    })?;
+    write_atomic(path, text.as_bytes())
+        .map_err(|error| super::InstallError::new(super::InstallErrorKind::Io, error.to_string()))
+}
+
+fn describe(error: &DownloadError) -> FileFailure {
+    FileFailure {
+        kind: error.kind,
+        message: error.message.clone(),
+    }
+}
diff --git a/crates/core/src/game/install/instance.rs b/crates/core/src/game/install/instance.rs
new file mode 100644
index 0000000..8fa0aa3
--- /dev/null
+++ b/crates/core/src/game/install/instance.rs
@@ -0,0 +1,351 @@
+//! 实例登记：`config/profiles.json` + `config/instances/<id>.json`（稀疏、幂等）。
+//!
+//! 依据：`DevDocs/PlanDoc/04-data-and-config.md` §4（D20 实例模型）、§2（`.ULL/config/`）、
+//! `DevDocs/PlanDoc/research/04-launcher-configs.md` §5（实例键草案）。
+//!
+//! # 为什么是两份文件
+//!
+//! - `profiles.json` = **档案列表**（UI 顺序、展示名、绑定版本），是"有哪些实例"的真相源；
+//! - `instances/<id>.json` = **每实例设置**，稀疏：只写用户显式改过的键。
+//!
+//! §5 的关键结论：`isolation` 默认 `inherit` 且**不落盘**——这样改全局模式对存量实例立即生效，
+//! 直接避开 PCL2"默认值被固化成实例值"的缺陷。因此 [`InstanceConfig::new`] 的
+//! `isolation` 是 `None`（序列化时整个键消失）；档位的**派生与切换检测**在
+//! [`crate::game::isolation`]（M30 落地），本模块只管结构与落盘。
+//!
+//! # 幂等
+//!
+//! 同一版本重复 `install`：按 `version_id` + 展示名复用已有档案，返回 `created = false`，
+//! 不产生第二个实例、不改已有实例的 id（id 一旦写进档案就是稳定的）。
+
+use std::collections::BTreeMap;
+use std::path::PathBuf;
+
+use serde::{Deserialize, Serialize};
+
+use super::super::error::GameError;
+use super::super::isolation::{IsolationMode, ModeChange, ModeChangeWarning};
+use super::super::profiles::{InstanceProfile, ProfileList};
+use crate::platform::atomic::write_atomic;
+use crate::platform::layout::LauncherLayout;
+
+/// 每实例设置文件的 schema 版本。
+///
+/// 与 `setting::instance_keys::instance_version` 的 minor 对应：D20 加了 `lastModeChange`，
+/// 老文件缺这个键即「没切换过」，不需要迁移步骤。
+pub const INSTANCE_CONFIG_VERSION: u32 = 1;
+
+/// 版本隔离档位（`isolation`）。
+///
+/// 缺省 `inherit` **不是**这个枚举的一个值，而是"键不存在"（[`InstanceConfig::isolation`]
+/// 为 `None`）——这样稀疏序列化天然表达"跟随全局"。
+///
+/// 派生规则见 [`crate::game::isolation::derive_game_dir`]：`isolated` → `versions/<versionId>/`、
+/// `shared` → 游戏根 `.minecraft/`、`custom` → 用户指定的 `gameDir`。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum Isolation {
+    /// 独立游戏目录（派生 `versions/<versionId>/`）。
+    #[serde(alias = "per_version")]
+    Isolated,
+    /// 与全局共用 `.minecraft`（HMCL 传统形态）。
+    Shared,
+    /// 用户指定的目录（此时 `gameDir` 必须有值）。
+    Custom,
+}
+
+impl Isolation {
+    /// 稳定字符串 id。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Isolated => "isolated",
+            Self::Shared => "shared",
+            Self::Custom => "custom",
+        }
+    }
+
+    /// 从字符串解析（未知值返回 `None`，由调用方决定是报错还是忽略）。
+    ///
+    /// `per_version` 是 M12 键草案里的旧字面量，读兼容映射到 `isolated`（语义相同）。
+    #[must_use]
+    pub fn parse(raw: &str) -> Option<Self> {
+        match raw.trim() {
+            "isolated" | "per_version" => Some(Self::Isolated),
+            "shared" => Some(Self::Shared),
+            "custom" => Some(Self::Custom),
+            _ => None,
+        }
+    }
+}
+
+/// 实例可覆盖的设置键（enum 白名单）。
+///
+/// research/04 §5 的教训：**不要用字符串集合**，拼错会静默不生效；这里用枚举，
+/// 后续 M28 接语义时编译器会逼着把每个键处理干净。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum OverrideKey {
+    /// 最大堆内存。
+    MaxMemory,
+    /// Java 运行时选择。
+    JavaType,
+    /// 工作目录覆盖。
+    RunningDirectory,
+}
+
+/// 每实例设置（`config/instances/<id>.json`）。
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct InstanceConfig {
+    /// schema 版本（迁移链入口）。
+    #[serde(default = "default_version")]
+    pub schema_version: u32,
+    /// 实例 id（稳定 UUID，与文件名一致）。
+    pub id: String,
+    /// 绑定的版本 id（`versions/<versionId>/`）。
+    pub version_id: String,
+    /// 隔离档位；`None` = `inherit`（跟随全局，不落盘）。
+    ///
+    /// 显式写 `"inherit"` 也照读（归一成 `None`）——见
+    /// [`deserialize_isolation`]：schema 白名单允许用户/AI 写这个字面量，
+    /// 读路径必须闭环，否则「显式写回默认值」的实例文件会让启动直接报 unknown variant。
+    #[serde(
+        default,
+        skip_serializing_if = "Option::is_none",
+        deserialize_with = "deserialize_isolation"
+    )]
+    pub isolation: Option<Isolation>,
+    /// 自定义游戏目录（仅 `isolation = custom` 时有值）。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub game_dir: Option<PathBuf>,
+    /// 该实例覆盖了哪些设置键。
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub overrides: Vec<OverrideKey>,
+    /// 上次隔离档位切换的记录（`lastModeChange`；没切过就不落盘）。
+    ///
+    /// 由 [`crate::game::isolation::observe_mode`] 维护，只记事实（含双侧探测），**不迁移数据**。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub last_mode_change: Option<ModeChange>,
+    /// 未识别字段原样保留（向前兼容）。
+    #[serde(flatten)]
+    pub extra: BTreeMap<String, serde_json::Value>,
+}
+
+fn default_version() -> u32 {
+    INSTANCE_CONFIG_VERSION
+}
+
+/// `isolation` 的反序列化：显式 `"inherit"` 归一成「键不存在」（`None`）。
+///
+/// 为什么需要：`setting::instance_keys` 的白名单里有 `inherit`（读/显示要用），
+/// 用户或 AI 把档位写回默认值时就会落一个 `"isolation": "inherit"`；从枚举角度它
+/// 是**没有变体**的（`inherit` 的真相是稀疏 —— 键缺失），所以在这里折叠成 `None`，
+/// 顺带把 `per_version` 旧字面量也接住（`Isolation::parse` 负责映射）。
+fn deserialize_isolation<'de, D>(deserializer: D) -> Result<Option<Isolation>, D::Error>
+where
+    D: serde::Deserializer<'de>,
+{
+    match Option::<String>::deserialize(deserializer)? {
+        None => Ok(None),
+        Some(text) if text.trim() == "inherit" => Ok(None),
+        Some(text) => Isolation::parse(&text).map(Some).ok_or_else(|| {
+            serde::de::Error::unknown_variant(&text, &["inherit", "isolated", "shared", "custom"])
+        }),
+    }
+}
+
+impl InstanceConfig {
+    /// 新建一份最小设置：`isolation` 留空（= inherit，不落盘）。
+    #[must_use]
+    pub fn new(id: impl Into<String>, version_id: impl Into<String>) -> Self {
+        Self {
+            schema_version: INSTANCE_CONFIG_VERSION,
+            id: id.into(),
+            version_id: version_id.into(),
+            isolation: None,
+            game_dir: None,
+            overrides: Vec::new(),
+            last_mode_change: None,
+            extra: BTreeMap::new(),
+        }
+    }
+
+    /// 是否跟随全局隔离模式（`isolation` 键缺失）。
+    #[must_use]
+    pub fn inherits_isolation(&self) -> bool {
+        self.isolation.is_none()
+    }
+
+    /// 生效隔离档位（覆盖链第二层落到全局第一层，`inherit` 在这里被解析掉）。
+    #[must_use]
+    pub fn effective_isolation(&self, global: IsolationMode) -> Isolation {
+        self.isolation.unwrap_or_else(|| global.as_isolation())
+    }
+
+    /// 取走待展示的切换提示（取走后 `warned` 置真，调用方负责落盘）。
+    pub fn take_mode_change_warning(&mut self) -> Option<ModeChangeWarning> {
+        self.last_mode_change.as_mut()?.take_warning()
+    }
+
+    /// 解析。
+    ///
+    /// # Errors
+    ///
+    /// JSON 非法时返回 [`GameError::Json`]。
+    pub fn from_json_str(json: &str) -> Result<Self, GameError> {
+        serde_json::from_str(json).map_err(|e| GameError::json("instance_config", e))
+    }
+
+    /// 序列化（格式化，便于用户手改与 diff）。
+    ///
+    /// # Errors
+    ///
+    /// 序列化失败时返回 [`GameError::Json`]。
+    pub fn to_json_string(&self) -> Result<String, GameError> {
+        serde_json::to_string_pretty(self).map_err(|e| GameError::json("instance_config", e))
+    }
+}
+
+/// 一次登记的结果。
+#[derive(Debug, Clone)]
+pub struct Registration {
+    /// 档案（新建或复用）。
+    pub profile: InstanceProfile,
+    /// 每实例设置文件路径。
+    pub config_path: PathBuf,
+    /// 是否新建（`false` = 已有同版本同名的实例，直接复用）。
+    pub created: bool,
+}
+
+/// 登记一个实例（幂等）。
+///
+/// 行为：
+/// 1. 已有"同 `version_id` + 同展示名"的档案 → 复用（`created = false`），只补写缺失的设置文件；
+/// 2. 否则新建档案（稳定 UUID）→ 写 `profiles.json` → 写 `config/instances/<id>.json`。
+///
+/// `created_at` 由调用方给（core::game 不碰时钟格式；CLI 用 `launch::time` 的 RFC3339）。
+///
+/// # Errors
+///
+/// 读/写 `profiles.json`、实例 id 不合法、原子写失败。
+pub fn register(
+    layout: &LauncherLayout,
+    name: &str,
+    version_id: &str,
+    created_at: Option<&str>,
+) -> Result<Registration, GameError> {
+    let mut profiles = read_profiles(layout)?;
+    let existing = profiles
+        .profiles
+        .iter()
+        .find(|profile| profile.version_id == version_id && profile.name == name)
+        .cloned();
+
+    if let Some(profile) = existing {
+        let config_path = instance_config_path(layout, profile.id.as_str())?;
+        // 老档案可能还没有设置文件（早期 CLI 只写 profiles.json），这里补齐。
+        if !config_path.is_file() {
+            write_instance_config(
+                layout,
+                &InstanceConfig::new(profile.id.as_str(), version_id),
+            )?;
+        }
+        return Ok(Registration {
+            profile,
+            config_path,
+            created: false,
+        });
+    }
+
+    let mut profile = InstanceProfile::new(name, version_id);
+    profile.created_at = created_at.map(str::to_string);
+    let id = profile.id.as_str().to_string();
+    profiles.upsert(profile.clone());
+    write_profiles(layout, &profiles)?;
+
+    let config_path = write_instance_config(layout, &InstanceConfig::new(id, version_id))?;
+    Ok(Registration {
+        profile,
+        config_path,
+        created: true,
+    })
+}
+
+/// 读实例清单（文件缺失 = 空列表，不算错误）。
+///
+/// # Errors
+///
+/// 读盘失败、非 UTF-8 或 JSON 非法。
+pub fn read_profiles(layout: &LauncherLayout) -> Result<ProfileList, GameError> {
+    let path = layout.profiles_config();
+    let bytes = match std::fs::read(&path) {
+        Ok(bytes) => bytes,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+            return Ok(ProfileList::default());
+        }
+        Err(error) => return Err(GameError::io(&path, error)),
+    };
+    let Ok(text) = String::from_utf8(bytes) else {
+        return Err(GameError::io(
+            &path,
+            std::io::Error::new(std::io::ErrorKind::InvalidData, "profiles.json 不是 UTF-8"),
+        ));
+    };
+    ProfileList::from_json_str(&text)
+}
+
+/// 写实例清单（原子写）。
+///
+/// # Errors
+///
+/// 序列化失败或原子写失败。
+pub fn write_profiles(layout: &LauncherLayout, profiles: &ProfileList) -> Result<(), GameError> {
+    let text = profiles.to_json_string()?;
+    write_atomic(&layout.profiles_config(), text.as_bytes())
+        .map_err(|error| GameError::io(layout.profiles_config(), std::io::Error::other(error)))
+}
+
+/// 写每实例设置（原子写）。
+///
+/// # Errors
+///
+/// 实例 id 不合法、序列化失败或原子写失败。
+pub fn write_instance_config(
+    layout: &LauncherLayout,
+    config: &InstanceConfig,
+) -> Result<PathBuf, GameError> {
+    let path = instance_config_path(layout, &config.id)?;
+    let text = config.to_json_string()?;
+    write_atomic(&path, text.as_bytes())
+        .map_err(|error| GameError::io(&path, std::io::Error::other(error)))?;
+    Ok(path)
+}
+
+/// 读每实例设置；缺失返回 `None`。
+///
+/// # Errors
+///
+/// 实例 id 不合法、读盘失败或 JSON 非法。
+pub fn read_instance_config(
+    layout: &LauncherLayout,
+    id: &str,
+) -> Result<Option<InstanceConfig>, GameError> {
+    let path = instance_config_path(layout, id)?;
+    match std::fs::read_to_string(&path) {
+        Ok(text) => InstanceConfig::from_json_str(&text).map(Some),
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(None),
+        Err(error) => Err(GameError::io(&path, error)),
+    }
+}
+
+/// `config/instances/<id>.json`（实例 id 白名单校验在布局层，挡掉 `../` 穿越）。
+///
+/// # Errors
+///
+/// 实例 id 不合法时返回 [`GameError::Io`]（`PlatformError` 没有对应变体）。
+fn instance_config_path(layout: &LauncherLayout, id: &str) -> Result<PathBuf, GameError> {
+    layout
+        .instance_config(id)
+        .map_err(|error| GameError::io(layout.config(), std::io::Error::other(error)))
+}
diff --git a/crates/core/src/game/install/libraries.rs b/crates/core/src/game/install/libraries.rs
new file mode 100644
index 0000000..6638c38
--- /dev/null
+++ b/crates/core/src/game/install/libraries.rs
@@ -0,0 +1,258 @@
+//! 依赖库展开：主构件 + natives 分类器构件 → 待下载文件。
+//!
+//! 依据：`DevDocs/analyse/03-version-download.md` §6.4（libraries 含 natives 规则）、
+//! §6.8（目录布局速查）。
+//!
+//! 三条容易踩的规则：
+//! 1. **主构件与 natives 构件都要下**：老版本（lwjgl 2.x）一条库里同时有
+//!    `downloads.artifact` 与 `natives` 表，HMCL 也是两者都取；
+//! 2. **路径优先用 JSON 给的 `path`**（Mojang 权威值），缺了才按 Maven 坐标推导；
+//! 3. **`hint=local` 的库落到实例私有目录** `versions/<id>/libraries/`，其余一律进
+//!    恒共享的 `libraries/`（D20：任何模式都不按实例复制）。
+
+use std::path::{Path, PathBuf};
+
+use super::super::arguments::Environment;
+use super::super::layout::GameLayout;
+use super::super::library::Library;
+use super::plan::{FileRole, PlanFile};
+use crate::download::ResourceKind;
+
+/// 没写 `url` 的库兜底用的 Maven 基址（Mojang 官方库仓）。
+pub const DEFAULT_MAVEN_BASE: &str = "https://libraries.minecraft.net/";
+
+/// 展开一层（已合并）清单里的库列表。
+///
+/// 返回（文件清单，人读告警）。告警不致命：缺下载地址的库会被跳过并告知，
+/// 让用户知道"缺哪个文件"而不是拿到一个静默不完整的实例。
+#[must_use]
+pub fn plan(
+    layout: &GameLayout,
+    version_id: &str,
+    libraries: &[Library],
+    environment: &Environment,
+) -> (Vec<PlanFile>, Vec<String>) {
+    let mut files = Vec::new();
+    let mut warnings = Vec::new();
+
+    for library in libraries {
+        if !library.applies(environment) {
+            continue;
+        }
+        if library.coordinate().is_err() {
+            warnings.push(format!("库坐标不合法，已跳过：{}", library.name));
+            continue;
+        }
+        let Ok(relative) = library.relative_path() else {
+            warnings.push(format!("库路径推导失败，已跳过：{}", library.name));
+            continue;
+        };
+        let dest = library_dest(layout, version_id, library, &relative);
+
+        match library.artifact() {
+            Some(artifact) if artifact.has_url() => files.push(PlanFile {
+                role: FileRole::Library,
+                name: library.name.clone(),
+                url: artifact.url.clone().unwrap_or_default(),
+                sha1: artifact.sha1.clone(),
+                size: artifact.size,
+                dest,
+                resource: ResourceKind::Library,
+            }),
+            // natives-only 库（1.6 时代的 `lwjgl-platform` / `jinput-platform`）**没有主构件**，
+            // 只要 `downloads.classifiers`。这里若按坐标硬拼 URL 会拼出一个不存在的 jar
+            // （实测：官方与 BMCLAPI 双双 404）。判据是 `natives` 在场。
+            None if library.natives.is_some() => {}
+            // 魔改/现代 loader 的库常见"只给 name 不给 downloads"，按坐标拼仓库地址。
+            _ => files.push(PlanFile {
+                role: FileRole::Library,
+                name: library.name.clone(),
+                url: maven_url(library, &relative),
+                sha1: None,
+                size: None,
+                dest,
+                resource: ResourceKind::Library,
+            }),
+        }
+
+        // natives 分类器构件（存在才下；解压发生在启动期，不归安装管）。
+        let Some(classifier) = library.native_classifier(environment) else {
+            continue;
+        };
+        let Some(artifact) = library.native_artifact(&classifier) else {
+            warnings.push(format!(
+                "{} 的 natives 分类器 {classifier} 没有下载信息，已跳过",
+                library.name
+            ));
+            continue;
+        };
+        let Ok(native_relative) = library.native_relative_path(&classifier) else {
+            warnings.push(format!("{} 的 natives 路径推导失败，已跳过", library.name));
+            continue;
+        };
+        if !artifact.has_url() {
+            warnings.push(format!(
+                "{} 的 natives 构件 {classifier} 没有下载地址，已跳过",
+                library.name
+            ));
+            continue;
+        }
+        files.push(PlanFile {
+            role: FileRole::Native,
+            name: format!("{}:{classifier}", library.name),
+            url: artifact.url.clone().unwrap_or_default(),
+            sha1: artifact.sha1.clone(),
+            size: artifact.size,
+            dest: layout.libraries_dir().join(native_relative),
+            resource: ResourceKind::Library,
+        });
+    }
+
+    (files, warnings)
+}
+
+/// 库文件落点：实例私有（`hint=local`）或恒共享 `libraries/`。
+fn library_dest(
+    layout: &GameLayout,
+    version_id: &str,
+    library: &Library,
+    relative: &Path,
+) -> PathBuf {
+    if library.is_local() {
+        layout.version_libraries_dir(version_id).join(relative)
+    } else {
+        layout.libraries_dir().join(relative)
+    }
+}
+
+/// 按库声明（或默认）的 Maven 基址拼下载地址。
+fn maven_url(library: &Library, relative: &Path) -> String {
+    let base = library
+        .url
+        .as_deref()
+        .map(str::trim)
+        .filter(|base| !base.is_empty())
+        .unwrap_or(DEFAULT_MAVEN_BASE);
+    let path = relative.to_string_lossy().replace('\\', "/");
+    if base.ends_with('/') {
+        format!("{base}{path}")
+    } else {
+        format!("{base}/{path}")
+    }
+}
+
+/// 供上层判错用：库展开不产生硬失败，缺地址一律降级成告警。
+#[cfg(test)]
+mod tests {
+    use super::plan;
+    use crate::game::arguments::Environment;
+    use crate::game::layout::GameLayout;
+    use crate::game::library::Library;
+
+    fn environment() -> Environment {
+        Environment {
+            os: "windows".to_string(),
+            os_version: String::new(),
+            arch: "x86_64".to_string(),
+            ..Environment::host()
+        }
+    }
+
+    fn library_with_artifact(json: &str) -> Library {
+        serde_json::from_str(json).expect("库 JSON 应可解析")
+    }
+
+    #[test]
+    fn plans_artifact_at_maven_path() {
+        let library = library_with_artifact(
+            r#"{"name":"org.ow2.asm:asm:9.6","downloads":{"artifact":{"path":"org/ow2/asm/asm/9.6/asm-9.6.jar","sha1":"aa","size":122,"url":"https://libraries.minecraft.net/org/ow2/asm/asm/9.6/asm-9.6.jar"}}}"#,
+        );
+        let layout = GameLayout::new("/g/.minecraft");
+        let (files, warnings) = plan(&layout, "1.20.1", &[library], &environment());
+        assert!(warnings.is_empty());
+        assert_eq!(files.len(), 1);
+        assert_eq!(files[0].sha1.as_deref(), Some("aa"));
+        assert_eq!(files[0].size, Some(122));
+        assert!(files[0]
+            .dest
+            .ends_with("libraries/org/ow2/asm/asm/9.6/asm-9.6.jar"));
+    }
+
+    #[test]
+    fn natives_only_library_plans_no_artifact() {
+        // 1.6 时代的 lwjgl-platform / jinput-platform：有 natives 表、只有 classifiers，
+        // **没有 downloads.artifact**。按坐标硬拼主构件会拼出不存在的 jar（实测双源 404）。
+        let library = library_with_artifact(
+            r#"{"name":"org.lwjgl.lwjgl:lwjgl-platform:2.9.0",
+                "natives":{"windows":"natives-windows","linux":"natives-linux","osx":"natives-osx"},
+                "downloads":{"classifiers":{"natives-windows":{"path":"org/lwjgl/lwjgl/lwjgl-platform/2.9.0/lwjgl-platform-2.9.0-natives-windows.jar","sha1":"3f11","size":609967,"url":"https://libraries.minecraft.net/natives-windows.jar"}}}}"#,
+        );
+        let layout = GameLayout::new("/g/.minecraft");
+        let (files, warnings) = plan(&layout, "1.6.4", &[library], &environment());
+        assert!(warnings.is_empty(), "不该有告警：{warnings:?}");
+        assert_eq!(files.len(), 1, "只应有 natives 构件：{files:?}");
+        assert_eq!(files[0].role.as_str(), "native");
+        assert_eq!(files[0].sha1.as_deref(), Some("3f11"));
+    }
+
+    #[test]
+    fn plans_both_artifact_and_native_jar() {
+        let library = library_with_artifact(
+            r#"{"name":"org.lwjgl.lwjgl:lwjgl-platform:2.9.4","natives":{"windows":"natives-windows"},
+                "downloads":{"artifact":{"path":"org/lwjgl/lwjgl/lwjgl-platform/2.9.4/lwjgl-platform-2.9.4.jar","sha1":"bb","size":1,"url":"https://libraries.minecraft.net/a.jar"},
+                "classifiers":{"natives-windows":{"path":"org/lwjgl/lwjgl/lwjgl-platform/2.9.4/lwjgl-platform-2.9.4-natives-windows.jar","sha1":"cc","size":2,"url":"https://libraries.minecraft.net/b.jar"}}}}"#,
+        );
+        let layout = GameLayout::new("/g/.minecraft");
+        let (files, _) = plan(&layout, "1.7.10", &[library], &environment());
+        assert_eq!(files.len(), 2);
+        let native = files
+            .iter()
+            .find(|f| f.role.as_str() == "native")
+            .expect("应有 natives 构件");
+        assert_eq!(native.sha1.as_deref(), Some("cc"));
+        assert!(native
+            .dest
+            .ends_with("lwjgl-platform-2.9.4-natives-windows.jar"));
+    }
+
+    #[test]
+    fn derives_url_for_libraries_without_downloads() {
+        let library = library_with_artifact(
+            r#"{"name":"net.minecraftforge:forge:1.20.1-47.2.0:universal","url":"https://maven.minecraftforge.net/"}"#,
+        );
+        let layout = GameLayout::new("/g/.minecraft");
+        let (files, warnings) = plan(&layout, "1.20.1-forge", &[library], &environment());
+        assert!(warnings.is_empty());
+        assert_eq!(files.len(), 1);
+        assert_eq!(
+            files[0].url,
+            "https://maven.minecraftforge.net/net/minecraftforge/forge/1.20.1-47.2.0/forge-1.20.1-47.2.0-universal.jar"
+        );
+        assert!(files[0].sha1.is_none());
+    }
+
+    #[test]
+    fn skips_libraries_filtered_by_rules() {
+        let library = library_with_artifact(
+            r#"{"name":"org.lwjgl:lwjgl:3.3.2","rules":[{"action":"allow","os":{"name":"linux"}}],
+                "downloads":{"artifact":{"url":"https://libraries.minecraft.net/x.jar","sha1":"dd"}}}"#,
+        );
+        let layout = GameLayout::new("/g/.minecraft");
+        let (files, _) = plan(&layout, "1.20.1", &[library], &environment());
+        assert!(files.is_empty());
+    }
+
+    #[test]
+    fn local_hint_libraries_land_in_instance_dir() {
+        let library = library_with_artifact(
+            r#"{"name":"net.minecraftforge:forge:1.20.1-47.2.0","hint":"local",
+                "downloads":{"artifact":{"path":"net/minecraftforge/forge/1.20.1-47.2.0.jar","url":"https://libraries.minecraft.net/y.jar"}}}"#,
+        );
+        let layout = GameLayout::new("/g/.minecraft");
+        let (files, _) = plan(&layout, "inst", &[library], &environment());
+        assert_eq!(files.len(), 1);
+        assert!(files[0]
+            .dest
+            .ends_with("versions/inst/libraries/net/minecraftforge/forge/1.20.1-47.2.0.jar"));
+    }
+}
diff --git a/crates/core/src/game/install/mod.rs b/crates/core/src/game/install/mod.rs
new file mode 100644
index 0000000..63a3358
--- /dev/null
+++ b/crates/core/src/game/install/mod.rs
@@ -0,0 +1,193 @@
+//! 安装层：版本链 → 下载计划 → 分区落盘 → 实例登记（P2 核心闭环「装一个版本并启动它」）。
+//!
+//! 设计输入：`DevDocs/analyse/03-version-download.md` §6（逐类资源拆解）、
+//! `DevDocs/PlanDoc/04-data-and-config.md` §4（D20 实例模型）、§2（`.ULL/` 四分区）、
+//! `DevDocs/PlanDoc/05-download-and-mirrors.md` §2（分层下载策略）、
+//! `DevDocs/PlanDoc/research/04-launcher-configs.md` §5（实例键草案）。
+//!
+//! # 分工（每层只做一件事，谁都不越界）
+//!
+//! ```text
+//! source    网络：版本清单（带 TTL 缓存）→ 版本 JSON 链 → 资源索引      （异步）
+//! plan      纯计算：清单 + 索引 → InstallPlan（文件清单 / 总大小 / 角色）  （同步、可 dry-run）
+//! execute   落盘：逐文件跳过判定 + 下载引擎 + 原子写版本 JSON            （异步）
+//! instance  登记：profiles.json + config/instances/<id>.json（稀疏、幂等）（同步）
+//! ```
+//!
+//! # 三条硬约定
+//!
+//! 1. **恒共享层**（D20）：`versions/` `assets/` `libraries/` 一律进游戏根，任何模式都不按实例复制；
+//! 2. **幂等**：重复装同一版本不重复下载（按 sha1 跳过）、不重复建实例（按 `versionId` 复用档案）；
+//! 3. **如实告知**：清单缺件（旧版无 `downloads.client` / 无 `assetIndex`）只降级成计划告警，
+//!    不静默假装成功，也不编造 URL。
+//!
+//! # 同步宿主怎么用
+//!
+//! `crates/cli` 不依赖 tokio：整段「规划 + 下载」包在一次
+//! [`crate::download::blocking::block_on`] 里，见 `ull install` 的实现。
+
+pub mod assets;
+pub mod execute;
+pub mod instance;
+pub mod libraries;
+pub mod plan;
+pub mod plan_view;
+mod report;
+pub mod source;
+
+use std::fmt;
+
+pub use assets::{AssetIndex, AssetObject, ASSET_OBJECT_BASE};
+pub use execute::{execute, execute_with_cancel};
+pub use instance::{register, InstanceConfig, Registration};
+pub use plan::{FileRole, InstallPlan, PlanFile, PlanInput};
+pub use report::{FileFailure, FileOutcome, FileStatus, InstallReport, ProgressSink};
+pub use source::{ManifestFreshness, RemoteSource, MANIFEST_TTL_MS};
+
+use crate::download::{DownloadError, DownloadErrorKind};
+use crate::game::error::GameError;
+
+/// 安装失败的大类（CLI 据此给稳定错误码，脚本可分流）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum InstallErrorKind {
+    /// 版本 id 在官方清单与本地仓库里都不存在。
+    VersionNotFound,
+    /// 网络侧失败（所有候选源都失败 / 超时 / 连接错误）。
+    Network,
+    /// 内容校验不符（镜像给了错内容）。
+    Integrity,
+    /// 本地 IO（写盘失败、目录权限）。
+    Io,
+    /// 元数据解析失败（清单/版本 JSON/资源索引坏了）。
+    Metadata,
+    /// 用户取消（`execute_with_cancel` 看到取消标志；不是失败，也不是网络问题）。
+    ///
+    /// CLI 永远走 [`execute`]（不传取消标志），所以这个大类只可能从 GUI 的取消路径出来。
+    Cancelled,
+}
+
+impl InstallErrorKind {
+    /// 稳定字符串 id（进 `--json` 的 `error.code`）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::VersionNotFound => "install_version_not_found",
+            Self::Network => "install_network",
+            Self::Integrity => "install_integrity",
+            Self::Io => "install_io",
+            Self::Metadata => "install_metadata",
+            Self::Cancelled => "install_cancelled",
+        }
+    }
+}
+
+/// 安装期错误：大类 + 人读说明 + 可选提示。
+#[derive(Debug, Clone)]
+pub struct InstallError {
+    kind: InstallErrorKind,
+    message: String,
+    hint: Option<String>,
+}
+
+impl InstallError {
+    /// 构造。
+    #[must_use]
+    pub fn new(kind: InstallErrorKind, message: impl Into<String>) -> Self {
+        Self {
+            kind,
+            message: message.into(),
+            hint: None,
+        }
+    }
+
+    /// 版本不存在。
+    #[must_use]
+    pub fn version_not_found(id: &str) -> Self {
+        Self::new(
+            InstallErrorKind::VersionNotFound,
+            format!("版本 {id} 不在版本清单里，也不在本地 versions/ 下"),
+        )
+        .with_hint("用 `ull --json install <version>` 前先确认版本 id（如 26.3 / 1.21.4）；快照版本 id 形如 24w14a")
+    }
+
+    /// 补一句提示。
+    #[must_use]
+    pub fn with_hint(mut self, hint: impl Into<String>) -> Self {
+        self.hint = Some(hint.into());
+        self
+    }
+
+    /// 大类。
+    #[must_use]
+    pub const fn kind(&self) -> InstallErrorKind {
+        self.kind
+    }
+
+    /// 人读说明。
+    #[must_use]
+    pub fn message(&self) -> &str {
+        &self.message
+    }
+
+    /// 下一步提示。
+    #[must_use]
+    pub fn hint(&self) -> Option<&str> {
+        self.hint.as_deref()
+    }
+}
+
+impl fmt::Display for InstallError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str(&self.message)
+    }
+}
+
+impl std::error::Error for InstallError {}
+
+impl From<DownloadError> for InstallError {
+    fn from(error: DownloadError) -> Self {
+        let kind = match error.kind {
+            DownloadErrorKind::Integrity => InstallErrorKind::Integrity,
+            DownloadErrorKind::Io => InstallErrorKind::Io,
+            DownloadErrorKind::InvalidRequest => InstallErrorKind::Metadata,
+            DownloadErrorKind::NotFound
+            | DownloadErrorKind::ServerError
+            | DownloadErrorKind::Timeout
+            | DownloadErrorKind::Network
+            | DownloadErrorKind::RangeUnsupported
+            | DownloadErrorKind::AllSourcesFailed => InstallErrorKind::Network,
+        };
+        let mut message = error.message.clone();
+        if let Some(source) = &error.source {
+            message.push_str(&format!("（源 {source}）"));
+        }
+        Self::new(kind, message)
+    }
+}
+
+impl From<GameError> for InstallError {
+    fn from(error: GameError) -> Self {
+        let kind = match &error {
+            GameError::Io { .. } => InstallErrorKind::Io,
+            GameError::Json { .. } | GameError::InvalidAssetHash { .. } => {
+                InstallErrorKind::Metadata
+            }
+            GameError::MissingVersionId
+            | GameError::MissingParent { .. }
+            | GameError::CircularInheritance { .. }
+            | GameError::InvalidCoordinate { .. }
+            | GameError::CustomIsolationWithoutDir { .. }
+            | GameError::DraftBusy => InstallErrorKind::Metadata,
+        };
+        Self::new(kind, error.to_string())
+    }
+}
+
+impl From<crate::platform::error::PlatformError> for InstallError {
+    fn from(error: crate::platform::error::PlatformError) -> Self {
+        Self::new(InstallErrorKind::Io, error.to_string())
+    }
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/core/src/game/install/plan.rs b/crates/core/src/game/install/plan.rs
new file mode 100644
index 0000000..8310353
--- /dev/null
+++ b/crates/core/src/game/install/plan.rs
@@ -0,0 +1,342 @@
+//! 安装计划：把「已解析的版本清单 + 资源索引」翻译成一份可下载文件清单。
+//!
+//! 依据：`DevDocs/analyse/03-version-download.md` §6（安装期资源清单逐类拆解）、
+//! `DevDocs/PlanDoc/05-download-and-mirrors.md`（镜像由下载引擎展开）。
+//!
+//! 本模块是**纯计算**：输入已解析清单（[`VersionJson`]）与已取到的资源索引，输出
+//! [`InstallPlan`]；不发请求、不写文件。网络在 [`super::source`]、落盘在 [`super::execute`]。
+//! 这样 `--dry-run`、测试、以及 GUI 的"安装前确认页"共用同一份计划真相。
+//!
+//! 恒共享层（D20）：`versions/`、`assets/`、`libraries/` 一律进游戏根，不按实例复制；
+//! 只有 `hint=local` 的库落实例私有目录（见 [`super::libraries`]）。
+
+use std::collections::BTreeMap;
+use std::path::PathBuf;
+
+use serde::{Deserialize, Serialize};
+use serde_json::{json, Value};
+
+use super::super::arguments::Environment;
+use super::super::error::GameError;
+use super::super::layout::GameLayout;
+use super::super::manifest::{Logging, VersionJson};
+use super::assets::{self, AssetIndex};
+use super::libraries;
+use crate::download::{DownloadRequest, ResourceKind};
+
+/// 一个待落盘文件的角色（进度分组、`--dry-run` 汇总、错误定位都用它）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum FileRole {
+    /// 客户端 jar `versions/<jarId>/<jarId>.jar`。
+    ClientJar,
+    /// 共享库 `libraries/...`。
+    Library,
+    /// natives 分类器构件（也进 `libraries/`，启动期解压）。
+    Native,
+    /// 资源索引 `assets/indexes/<id>.json`。
+    AssetIndex,
+    /// 资源对象 `assets/objects/<hash[0..2]>/<hash>`。
+    Asset,
+    /// 日志配置 `assets/log_configs/<id>`。
+    LogConfig,
+}
+
+impl FileRole {
+    /// 稳定字符串 id（JSON 输出与日志用，**不要改名**）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::ClientJar => "client_jar",
+            Self::Library => "library",
+            Self::Native => "native",
+            Self::AssetIndex => "asset_index",
+            Self::Asset => "asset",
+            Self::LogConfig => "log_config",
+        }
+    }
+
+    /// 人读名称（汇总行用）。
+    #[must_use]
+    pub const fn label(self) -> &'static str {
+        match self {
+            Self::ClientJar => "客户端 jar",
+            Self::Library => "依赖库",
+            Self::Native => "natives",
+            Self::AssetIndex => "资源索引",
+            Self::Asset => "资源对象",
+            Self::LogConfig => "日志配置",
+        }
+    }
+}
+
+/// 清单里的一个待下载文件。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PlanFile {
+    /// 角色。
+    pub role: FileRole,
+    /// 人读标识（库坐标 / 资源名 / 索引 id / jar id）。
+    pub name: String,
+    /// 官方逻辑 URL（镜像展开由下载引擎负责）。
+    pub url: String,
+    /// 期望 SHA-1（`None` = 清单没给，只能靠大小/存在性兜底）。
+    pub sha1: Option<String>,
+    /// 期望字节数。
+    pub size: Option<u64>,
+    /// 最终落盘路径。
+    pub dest: PathBuf,
+    /// 资源类型（健康度统计与分块准入的第二维度）。
+    pub resource: ResourceKind,
+}
+
+impl PlanFile {
+    /// 转成下载引擎的请求（校验值/大小原样透传）。
+    #[must_use]
+    pub fn request(&self) -> DownloadRequest {
+        let mut request = DownloadRequest::new(self.resource, self.url.clone(), self.dest.clone());
+        request.integrity = self
+            .sha1
+            .clone()
+            .filter(|hex| !hex.is_empty())
+            .map(crate::download::Integrity::sha1);
+        request.expected_size = self.size;
+        request
+    }
+
+    /// `--dry-run` 的单行描述。
+    #[must_use]
+    pub fn to_json(&self) -> Value {
+        json!({
+            "role": self.role.as_str(),
+            "name": self.name,
+            "url": self.url,
+            "sha1": self.sha1,
+            "size": self.size,
+            "dest": self.dest.display().to_string(),
+            "resource": self.resource.as_str(),
+        })
+    }
+}
+
+/// 规划阶段已经取到内容、但因 `--dry-run` / 时序原因还没落盘的元数据文件。
+///
+/// 典型场景：资源索引——不先取到它就无法枚举对象，所以规划期已经下载在内存里；
+/// 执行期直接原子写盘，不再重复走一次网络。
+#[derive(Debug, Clone)]
+pub struct Prefetched {
+    /// 目标路径（必须与计划里的某个 [`PlanFile::dest`] 一致）。
+    pub dest: PathBuf,
+    /// 内容字节。
+    pub bytes: Vec<u8>,
+}
+
+/// 一次安装的完整计划。
+#[derive(Debug, Clone)]
+pub struct InstallPlan {
+    /// 目标版本 id（`versions/<id>/`）。
+    pub version_id: String,
+    /// 实际提供 jar 的版本 id（继承链上可能是父版本）。
+    pub jar_id: String,
+    /// 游戏根目录（恒共享层的根）。
+    pub game_root: PathBuf,
+    /// 版本清单落盘路径 `versions/<id>/<id>.json`。
+    pub version_json_path: PathBuf,
+    /// 待下载文件（按 dest 去重、按角色排序）。
+    pub files: Vec<PlanFile>,
+    /// 已解析的扁平清单（落盘时写进 `versions/<id>/<id>.json`）。
+    pub version_json: VersionJson,
+    /// 规划期已取到内容的文件（见 [`Prefetched`]）。
+    pub prefetched: Vec<Prefetched>,
+    /// 人读告警（缺哪类资源一律如实告知，不静默降级）。
+    pub warnings: Vec<String>,
+}
+
+/// [`InstallPlan::build`] 的输入。
+pub struct PlanInput<'a> {
+    /// 游戏目录布局。
+    pub layout: &'a GameLayout,
+    /// 目标版本 id。
+    pub version_id: &'a str,
+    /// 已 resolve 的扁平清单。
+    pub resolved: &'a VersionJson,
+    /// 已取到并解析的资源索引（缺 = 老版本没有 `assetIndex`）。
+    pub asset_index: Option<&'a AssetIndex>,
+    /// 规则求值环境（OS / 架构 / 特性开关）。
+    pub environment: &'a Environment,
+}
+
+impl InstallPlan {
+    /// 组计划。
+    ///
+    /// # Errors
+    ///
+    /// 资源对象的哈希不合法（索引坏了）时返回 [`GameError::InvalidAssetHash`]。
+    pub fn build(input: PlanInput<'_>) -> Result<Self, GameError> {
+        let layout = input.layout;
+        let version_id = input.version_id;
+        let resolved = input.resolved;
+        let mut files: Vec<PlanFile> = Vec::new();
+        let mut warnings: Vec<String> = Vec::new();
+
+        let jar_id = resolved
+            .jar
+            .clone()
+            .unwrap_or_else(|| version_id.to_string());
+
+        // ① 客户端 jar：老版本（pre-1.6）没有 `downloads.client`，如实告知而不是编 URL。
+        match resolved.client_jar() {
+            Some(info) if info.has_url() => files.push(PlanFile {
+                role: FileRole::ClientJar,
+                name: jar_id.clone(),
+                url: info.url.clone().unwrap_or_default(),
+                sha1: info.sha1.clone(),
+                size: info.size,
+                dest: layout.version_jar(&jar_id),
+                resource: ResourceKind::ClientJar,
+            }),
+            _ => warnings.push(format!(
+                "版本 {version_id} 的清单没有 downloads.client：客户端 jar 无法自动获取（pre-1.6 旧清单待补兜底）"
+            )),
+        }
+
+        // ② 依赖库 + natives。
+        let (library_files, library_warnings) = libraries::plan(
+            layout,
+            version_id,
+            resolved.libraries.as_deref().unwrap_or_default(),
+            input.environment,
+        );
+        files.extend(library_files);
+        warnings.extend(library_warnings);
+
+        // ③ 资源索引 + 逐对象。
+        match resolved.asset_index.as_ref() {
+            Some(reference) if reference.url.is_some() => files.push(PlanFile {
+                role: FileRole::AssetIndex,
+                name: reference.id.clone(),
+                url: reference.url.clone().unwrap_or_default(),
+                sha1: reference.sha1.clone(),
+                size: reference.size,
+                dest: layout.asset_index(&reference.id),
+                resource: ResourceKind::AssetIndex,
+            }),
+            Some(reference) => warnings.push(format!(
+                "资源索引 {} 没有下载地址，跳过（对象无法枚举）",
+                reference.id
+            )),
+            None => warnings.push(format!(
+                "版本 {version_id} 的清单没有 assetIndex：资源对象无法枚举（旧版 sha1 反查表待补）"
+            )),
+        }
+        if let Some(index) = input.asset_index {
+            files.extend(assets::plan(layout, index)?);
+        }
+
+        // ④ 日志配置（官方 manifest 带的 appender 配置；有就下，没有就用启动器的内置模板）。
+        if let Some(logging) = resolved.logging.as_ref().and_then(Logging::client) {
+            if logging.file.has_url() {
+                let file_id = logging
+                    .file
+                    .id
+                    .clone()
+                    .unwrap_or_else(|| format!("{version_id}-client"));
+                files.push(PlanFile {
+                    role: FileRole::LogConfig,
+                    name: file_id.clone(),
+                    url: logging.file.url.clone().unwrap_or_default(),
+                    sha1: logging.file.sha1.clone(),
+                    size: logging.file.size,
+                    dest: layout.log_config(&file_id),
+                    resource: ResourceKind::Other,
+                });
+            }
+        }
+
+        let files = dedupe(files);
+
+        Ok(Self {
+            version_id: version_id.to_string(),
+            jar_id,
+            game_root: layout.root().to_path_buf(),
+            version_json_path: layout.version_json(version_id),
+            files,
+            version_json: resolved.clone(),
+            prefetched: Vec::new(),
+            warnings,
+        })
+    }
+
+    /// 挂一份"规划期已取到内容"的文件（内容必须与计划里的对应文件同一落点）。
+    pub fn prefetch(&mut self, dest: PathBuf, bytes: Vec<u8>) {
+        self.prefetched.push(Prefetched { dest, bytes });
+    }
+
+    /// 客户端 jar 的待下载项（`None` = 旧版清单没给下载信息）。
+    #[must_use]
+    pub fn client_jar(&self) -> Option<&PlanFile> {
+        self.files
+            .iter()
+            .find(|file| file.role == FileRole::ClientJar)
+    }
+
+    /// 这份计划能否真的装出一个可启动的版本（判据：有客户端 jar）。
+    ///
+    /// 旧版（pre-1.6）清单没有 `downloads.client`，计划里就没有 jar——此时"装成功"
+    /// 等于骗人，调用方应当拒绝执行而不是登记一个起不来的实例。
+    #[must_use]
+    pub fn is_installable(&self) -> bool {
+        self.client_jar().is_some()
+    }
+
+    /// 文件数。
+    #[must_use]
+    pub fn file_count(&self) -> usize {
+        self.files.len()
+    }
+
+    /// 总字节数（已知大小的合计；`unknown_size` 给出"有几个文件大小未知"）。
+    #[must_use]
+    pub fn total_bytes(&self) -> (u64, usize) {
+        let mut total = 0_u64;
+        let mut unknown = 0_usize;
+        for file in &self.files {
+            match file.size {
+                Some(size) => total += size,
+                None => unknown += 1,
+            }
+        }
+        (total, unknown)
+    }
+
+    /// 按角色统计（角色 → （文件数, 字节数））。
+    #[must_use]
+    pub fn by_role(&self) -> BTreeMap<FileRole, (usize, u64)> {
+        let mut out: BTreeMap<FileRole, (usize, u64)> = BTreeMap::new();
+        for file in &self.files {
+            let entry = out.entry(file.role).or_insert((0, 0));
+            entry.0 += 1;
+            entry.1 += file.size.unwrap_or(0);
+        }
+        out
+    }
+}
+
+/// 按落盘路径去重：同一目标只留一条，优先保留带 sha1 的那条（后出现的更可信时覆盖）。
+fn dedupe(files: Vec<PlanFile>) -> Vec<PlanFile> {
+    let mut by_dest: BTreeMap<PathBuf, PlanFile> = BTreeMap::new();
+    for file in files {
+        match by_dest.get(&file.dest) {
+            Some(existing) if existing.sha1.is_some() || file.sha1.is_none() => {}
+            _ => {
+                by_dest.insert(file.dest.clone(), file);
+            }
+        }
+    }
+    let mut out: Vec<PlanFile> = by_dest.into_values().collect();
+    out.sort_by(|left, right| {
+        left.role
+            .cmp(&right.role)
+            .then_with(|| left.dest.cmp(&right.dest))
+    });
+    out
+}
diff --git a/crates/core/src/game/install/plan_view.rs b/crates/core/src/game/install/plan_view.rs
new file mode 100644
index 0000000..119df0e
--- /dev/null
+++ b/crates/core/src/game/install/plan_view.rs
@@ -0,0 +1,72 @@
+//! 计划的 JSON 视图与源选择样本（`--dry-run` 的输出形状）。
+//!
+//! 单独一份是为了让 [`InstallPlan`](super::plan::InstallPlan) 的"计算"与"呈现"分开：
+//! 形状变了只动这里，计划算法不受影响；也让 `plan.rs` 不至于越过 400 行硬约束。
+
+use std::collections::{BTreeMap, BTreeSet};
+
+use serde_json::{json, Value};
+
+use super::plan::{FileRole, InstallPlan, PlanFile};
+use crate::download::DownloadEngine;
+
+impl InstallPlan {
+    /// 计划摘要（`--dry-run` 与日志共用；不含逐文件明细）。
+    #[must_use]
+    pub fn summary_json(&self) -> Value {
+        let (total, unknown) = self.total_bytes();
+        let by_role: BTreeMap<String, Value> = self
+            .by_role()
+            .into_iter()
+            .map(|(role, (count, bytes))| {
+                (
+                    role.as_str().to_string(),
+                    json!({"files": count, "bytes": bytes, "label": role.label()}),
+                )
+            })
+            .collect();
+        json!({
+            "version_id": self.version_id,
+            "jar_id": self.jar_id,
+            "game_root": self.game_root.display().to_string(),
+            "file_count": self.file_count(),
+            "total_bytes": total,
+            "unknown_size_files": unknown,
+            "by_role": by_role,
+            "warnings": self.warnings,
+        })
+    }
+
+    /// 逐文件明细（`--dry-run` 的"列清单"用它；真实安装不输出，避免上千行噪声）。
+    #[must_use]
+    pub fn files_json(&self) -> Vec<Value> {
+        self.files.iter().map(PlanFile::to_json).collect()
+    }
+
+    /// 每个角色取第一个文件，[`DownloadEngine::plan`] 给出候选源顺序（"源选择"）。
+    ///
+    /// 只取每类的**首个**文件做样本：3000 个资源对象的候选源是一样的，
+    /// 逐文件列源选择既没用也没法读。
+    #[must_use]
+    pub fn source_samples(&self, engine: &DownloadEngine, now_ms: u64) -> Vec<Value> {
+        let mut seen: BTreeSet<FileRole> = BTreeSet::new();
+        let mut samples = Vec::new();
+        for file in &self.files {
+            if !seen.insert(file.role) {
+                continue;
+            }
+            let candidates: Vec<Value> = engine
+                .plan(&file.request(), now_ms)
+                .into_iter()
+                .map(|candidate| json!({"source": candidate.source, "url": candidate.url}))
+                .collect();
+            samples.push(json!({
+                "role": file.role.as_str(),
+                "label": file.role.label(),
+                "sample": file.name,
+                "candidates": candidates,
+            }));
+        }
+        samples
+    }
+}
diff --git a/crates/core/src/game/install/report.rs b/crates/core/src/game/install/report.rs
new file mode 100644
index 0000000..576b4ad
--- /dev/null
+++ b/crates/core/src/game/install/report.rs
@@ -0,0 +1,154 @@
+//! 安装报告与进度回调的形状（M105 从 `execute.rs` 搬出，守 400 行硬线）。
+//!
+//! 纯数据 + 纯方法：`execute.rs`（执行）与 CLI（汇总打印）都读它，谁也不改它。
+//! 搬移是**逐字**的，只有 `use` 断了回来（原来靠 `execute.rs` 的 import 活着）。
+
+use std::path::PathBuf;
+use std::sync::Arc;
+
+use crate::download::DownloadErrorKind;
+
+use super::plan::FileRole;
+
+/// 单个文件的结局。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum FileStatus {
+    /// 本次真的下载（或从缓存直取）并落盘。
+    Downloaded,
+    /// 已存在且校验通过，跳过。
+    Skipped,
+    /// 失败（原因在 [`FileOutcome::failure`]）。
+    Failed,
+}
+
+impl FileStatus {
+    /// 稳定字符串 id。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Downloaded => "downloaded",
+            Self::Skipped => "skipped",
+            Self::Failed => "failed",
+        }
+    }
+}
+
+/// 一次失败的分类信息（调用方据此给 `install_network` / `install_integrity` 等稳定码）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct FileFailure {
+    /// 下载错误分类。
+    pub kind: DownloadErrorKind,
+    /// 人读说明。
+    pub message: String,
+}
+
+/// 一个文件的执行结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct FileOutcome {
+    /// 角色。
+    pub role: FileRole,
+    /// 人读标识。
+    pub name: String,
+    /// 落盘路径。
+    pub dest: std::path::PathBuf,
+    /// 结局。
+    pub status: FileStatus,
+    /// 实际字节数（跳过时为盘上大小）。
+    pub bytes: u64,
+    /// 成功的源标识（`bmclapi` / `official` / `cache` / `metadata`）。
+    pub source: Option<String>,
+    /// 失败详情。
+    pub failure: Option<FileFailure>,
+}
+
+impl FileOutcome {
+    /// 是否失败。
+    #[must_use]
+    pub fn failed(&self) -> bool {
+        self.status == FileStatus::Failed
+    }
+}
+
+/// 进度回调：每完成一个文件调用一次（可跨线程，由执行器持有 `Arc`）。
+///
+/// CLI 用它往 stderr 打实时进度；GUI 侧直接消费 `ProgressEvent` 事件流即可，不必用这个。
+pub type ProgressSink = Arc<dyn Fn(&FileOutcome) + Send + Sync>;
+
+/// 一次安装的执行结果。
+#[derive(Debug, Clone)]
+pub struct InstallReport {
+    /// 逐文件结果（顺序不保证，按角色/大小汇总即可）。
+    pub files: Vec<FileOutcome>,
+    /// 版本清单落盘路径；`None` = 有文件失败，故意没写（见 `execute` 的说明）。
+    pub version_json: Option<PathBuf>,
+    /// 计划阶段带来的告警（缺件降级说明）。
+    pub warnings: Vec<String>,
+}
+
+impl InstallReport {
+    /// 真正下载的文件数。
+    #[must_use]
+    pub fn downloaded(&self) -> usize {
+        self.files
+            .iter()
+            .filter(|file| file.status == FileStatus::Downloaded)
+            .count()
+    }
+
+    /// 跳过（已存在且校验通过）的文件数。
+    #[must_use]
+    pub fn skipped(&self) -> usize {
+        self.files
+            .iter()
+            .filter(|file| file.status == FileStatus::Skipped)
+            .count()
+    }
+
+    /// 失败的文件数。
+    #[must_use]
+    pub fn failed(&self) -> usize {
+        self.files.iter().filter(|file| file.failed()).count()
+    }
+
+    /// 本次写入的字节数（只算真正下载的）。
+    #[must_use]
+    pub fn bytes(&self) -> u64 {
+        self.files
+            .iter()
+            .filter(|file| file.status == FileStatus::Downloaded)
+            .map(|file| file.bytes)
+            .sum()
+    }
+
+    /// 是否全部就绪（无失败）。
+    #[must_use]
+    pub fn is_complete(&self) -> bool {
+        self.failed() == 0
+    }
+
+    /// 失败文件列表（最多取前 `limit` 条，给 CLI 拼提示用）。
+    #[must_use]
+    pub fn failures(&self, limit: usize) -> Vec<&FileOutcome> {
+        self.files
+            .iter()
+            .filter(|file| file.failed())
+            .take(limit)
+            .collect()
+    }
+
+    /// 失败里最"严重"的大类：有校验不符就先报它，其余按网络/IO 归。
+    #[must_use]
+    pub fn failure_kind(&self) -> Option<DownloadErrorKind> {
+        let mut fallback = None;
+        for file in self.files.iter().filter(|file| file.failed()) {
+            let Some(failure) = &file.failure else {
+                continue;
+            };
+            if failure.kind == DownloadErrorKind::Integrity {
+                return Some(DownloadErrorKind::Integrity);
+            }
+            fallback.get_or_insert(failure.kind);
+        }
+        fallback
+    }
+}
diff --git a/crates/core/src/game/install/source.rs b/crates/core/src/game/install/source.rs
new file mode 100644
index 0000000..e9e5b4d
--- /dev/null
+++ b/crates/core/src/game/install/source.rs
@@ -0,0 +1,353 @@
+//! 远端元数据：版本清单（带 TTL 缓存与过期回退）、版本 JSON 链、资源索引。
+//!
+//! 依据：`DevDocs/analyse/03-version-download.md` §2.6（清单缓存）、§4.3（继承解析）、
+//! §6.2（版本 JSON）、§6.5（资源索引）；`DevDocs/PlanDoc/05-download-and-mirrors.md` §2
+//! （清单类资源"短 TTL + 失败立切源"）。
+//!
+//! 三条与 HMCL 有意的差异（都是 analyse/03 §8 点名的上游坑）：
+//! 1. **清单与版本 JSON 一律校验 sha1**（v2 端点自带），镜像篡改/截断在下载阶段就暴露；
+//! 2. **清单缓存过期自动刷新**，且刷新失败时**回退到过期缓存**并标注
+//!    [`ManifestFreshness::StaleFallback`]——离线机器上也能装已缓存的清单；
+//! 3. 版本 JSON 链**远端优先、本地兜底**：装已存在的 loader 实例时不会因为"官方清单里没有
+//!    这个魔改 id"就直接失败。
+
+use std::collections::{BTreeMap, BTreeSet};
+use std::path::{Path, PathBuf};
+
+use serde::{Deserialize, Serialize};
+
+use super::super::error::GameError;
+use super::super::inherit;
+use super::super::layout::GameLayout;
+use super::super::manifest::{AssetIndexRef, VersionJson};
+use super::super::unlisted;
+use super::super::version::{RemoteVersion, VersionList, VERSION_MANIFEST_V2_URL};
+use super::assets::AssetIndex;
+use super::InstallError;
+use super::InstallErrorKind;
+use crate::download::{DownloadEngine, DownloadRequest, ResourceKind};
+use crate::platform::atomic::write_atomic;
+
+/// 版本清单缓存有效期（12 小时）。过期后自动重新拉取；拉取失败退回旧缓存。
+pub const MANIFEST_TTL_MS: u64 = 12 * 60 * 60 * 1000;
+
+/// 清单缓存文件名（落在 `.ULL/cache/meta/`）。
+pub const MANIFEST_CACHE_FILE: &str = "version_manifest_v2.json";
+
+/// 继承链最大层数（防御恶意/损坏清单造成的无限展开；`resolve` 另有成环检测）。
+const MAX_CHAIN_DEPTH: usize = 16;
+
+/// 清单内容的来源（可观测性：诊断页/事件流要能说明"这次用的是缓存还是新拉的"）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ManifestFreshness {
+    /// 本次真实拉取。
+    Fetched,
+    /// 命中未过期的本地缓存。
+    Cached,
+    /// 拉取失败，退回过期缓存（离线可用）。
+    StaleFallback,
+}
+
+impl ManifestFreshness {
+    /// 稳定字符串 id。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Fetched => "fetched",
+            Self::Cached => "cached",
+            Self::StaleFallback => "stale_fallback",
+        }
+    }
+}
+
+/// 落盘的缓存形态（带拉取时刻，TTL 判定用）。
+#[derive(Debug, Clone, Serialize, Deserialize)]
+struct ManifestCache {
+    fetched_at_ms: u64,
+    list: VersionList,
+}
+
+/// 远端元数据来源。
+pub struct RemoteSource<'a> {
+    engine: &'a DownloadEngine,
+    game: &'a GameLayout,
+    meta_cache: &'a Path,
+    manifest_url: String,
+    now_ms: u64,
+}
+
+impl<'a> RemoteSource<'a> {
+    /// 绑定引擎、游戏布局与缓存目录。
+    #[must_use]
+    pub fn new(
+        engine: &'a DownloadEngine,
+        game: &'a GameLayout,
+        meta_cache: &'a Path,
+        now_ms: u64,
+    ) -> Self {
+        Self {
+            engine,
+            game,
+            meta_cache,
+            manifest_url: VERSION_MANIFEST_V2_URL.to_string(),
+            now_ms,
+        }
+    }
+
+    /// 覆盖清单地址（内网专有清单/测试用）。
+    #[must_use]
+    pub fn with_manifest_url(mut self, url: impl Into<String>) -> Self {
+        self.manifest_url = url.into();
+        self
+    }
+
+    /// 取版本清单（带 TTL 缓存；`refresh = true` 强制重新拉取）。
+    ///
+    /// # Errors
+    ///
+    /// 无可用缓存且网络失败、或清单 JSON/校验失败时返回 [`InstallError`]。
+    pub async fn manifest(
+        &self,
+        refresh: bool,
+    ) -> Result<(VersionList, ManifestFreshness), InstallError> {
+        let path = self.meta_cache.join(MANIFEST_CACHE_FILE);
+        let cached = read_cache(&path);
+        if !refresh {
+            if let Some(cache) = &cached {
+                if self.now_ms.saturating_sub(cache.fetched_at_ms) < MANIFEST_TTL_MS {
+                    return Ok((cache.list.clone(), ManifestFreshness::Cached));
+                }
+            }
+        }
+        match self.fetch_manifest(&path).await {
+            Ok(list) => Ok((list, ManifestFreshness::Fetched)),
+            Err(error) => match cached {
+                Some(cache) => Ok((cache.list, ManifestFreshness::StaleFallback)),
+                None => Err(error),
+            },
+        }
+    }
+
+    /// 解析目标版本的扁平清单（远端取版本 JSON，递归拉父层，再走
+    /// [`inherit::resolve`]）。
+    ///
+    /// # Errors
+    ///
+    /// 版本不存在（[`InstallError::version_not_found`]）、网络失败、继承链断裂/成环、
+    /// JSON 非法。
+    pub async fn resolve(&self, version_id: &str) -> Result<VersionJson, InstallError> {
+        let (manifest, _) = self.manifest(false).await?;
+        let root = self.load_one(version_id, &manifest).await?;
+
+        let mut table: BTreeMap<String, VersionJson> = BTreeMap::new();
+        table.insert(version_id.to_string(), root.clone());
+        let mut visited: BTreeSet<String> = BTreeSet::new();
+        visited.insert(version_id.to_string());
+        let mut pending = vec![root.clone()];
+        let mut depth = 0_usize;
+
+        while let Some(layer) = pending.pop() {
+            let Some(parent_id) = layer.inherits_from.clone() else {
+                continue;
+            };
+            depth += 1;
+            if depth > MAX_CHAIN_DEPTH {
+                return Err(InstallError::new(
+                    InstallErrorKind::Metadata,
+                    format!("版本 {version_id} 的继承链超过 {MAX_CHAIN_DEPTH} 层，疑似清单损坏"),
+                ));
+            }
+            // 环不在这里报：交给 resolve 给出完整 id 链（信息更全）。
+            if !visited.insert(parent_id.clone()) {
+                continue;
+            }
+            let parent = self.load_one(&parent_id, &manifest).await?;
+            pending.push(parent.clone());
+            table.insert(parent_id, parent);
+        }
+
+        inherit::resolve(&table, &root)
+            .map_err(|error| InstallError::new(InstallErrorKind::Metadata, error.to_string()))
+    }
+
+    /// 取资源索引，返回（索引模型，原始字节）。
+    ///
+    /// 原始字节一并返回，是因为**规划必须先有索引内容**才能枚举对象；这份字节随后由
+    /// [`super::execute`] 原子落到 `assets/indexes/<id>.json`，不重复下载。
+    ///
+    /// # Errors
+    ///
+    /// 索引没有下载地址、网络失败、sha1 不符或 JSON 非法。
+    pub async fn asset_index(
+        &self,
+        reference: &AssetIndexRef,
+    ) -> Result<(AssetIndex, Vec<u8>), InstallError> {
+        let url = reference.url.clone().ok_or_else(|| {
+            InstallError::new(
+                InstallErrorKind::Metadata,
+                format!("资源索引 {} 没有下载地址", reference.id),
+            )
+        })?;
+        let bytes = self
+            .fetch_bytes(ResourceKind::AssetIndex, &url, reference.sha1.as_deref())
+            .await?;
+        let index = AssetIndex::from_json_slice(&bytes)?;
+        Ok((index, bytes))
+    }
+
+    /// 拉清单并落缓存（成功才写，失败不动旧缓存）。
+    async fn fetch_manifest(&self, cache_path: &Path) -> Result<VersionList, InstallError> {
+        let request = DownloadRequest::new(
+            ResourceKind::VersionManifest,
+            self.manifest_url.clone(),
+            cache_path,
+        );
+        let bytes = self.engine.download_bytes(request).await?;
+        let mut list =
+            VersionList::from_json_str(std::str::from_utf8(&bytes).map_err(|_| {
+                InstallError::new(InstallErrorKind::Metadata, "版本清单不是 UTF-8")
+            })?)
+            .map_err(|error| InstallError::new(InstallErrorKind::Metadata, error.to_string()))?;
+        // 官方清单没有的远古版本/魔改条目由内嵌补充清单兜底（analyse/03 §2.3）。
+        unlisted::merge_into(&mut list);
+        let cache = ManifestCache {
+            fetched_at_ms: self.now_ms,
+            list: list.clone(),
+        };
+        let json = serde_json::to_vec(&cache).map_err(|error| {
+            InstallError::new(
+                InstallErrorKind::Metadata,
+                format!("序列化清单缓存失败：{error}"),
+            )
+        })?;
+        write_atomic(cache_path, &json)?;
+        Ok(list)
+    }
+
+    /// 取一份版本 JSON：远端优先（带 v2 的 sha1 校验），本地 `versions/<id>/<id>.json` 兜底。
+    async fn load_one(
+        &self,
+        id: &str,
+        manifest: &VersionList,
+    ) -> Result<VersionJson, InstallError> {
+        let remote = match manifest.find(id) {
+            Some(entry) => Some(self.fetch_version_json(entry).await),
+            None => None,
+        };
+        match remote {
+            Some(Ok(version)) => Ok(version),
+            Some(Err(remote_error)) => {
+                let local = self.read_local(id)?;
+                match local {
+                    Some(version) => Ok(version),
+                    None => Err(remote_error),
+                }
+            }
+            None => match self.read_local(id)? {
+                Some(version) => Ok(version),
+                None => Err(InstallError::version_not_found(id)),
+            },
+        }
+    }
+
+    async fn fetch_version_json(&self, entry: &RemoteVersion) -> Result<VersionJson, InstallError> {
+        let bytes = self
+            .fetch_bytes(
+                ResourceKind::VersionManifest,
+                &entry.url,
+                entry.sha1.as_deref(),
+            )
+            .await?;
+        VersionJson::from_json_slice(&bytes).map_err(InstallError::from)
+    }
+
+    async fn fetch_bytes(
+        &self,
+        kind: ResourceKind,
+        url: &str,
+        sha1: Option<&str>,
+    ) -> Result<Vec<u8>, InstallError> {
+        let mut request = DownloadRequest::new(kind, url, self.meta_cache.join("download.bin"));
+        if let Some(hex) = sha1.filter(|hex| !hex.is_empty()) {
+            request = request.with_sha1(hex);
+        }
+        Ok(self.engine.download_bytes(request).await?)
+    }
+
+    /// 读本地版本 JSON（`versions/<id>/<id>.json`）；不存在返回 `Ok(None)`。
+    fn read_local(&self, id: &str) -> Result<Option<VersionJson>, InstallError> {
+        let path: PathBuf = self.game.version_json(id);
+        match std::fs::read(&path) {
+            Ok(bytes) => VersionJson::from_json_slice(&bytes)
+                .map(Some)
+                .map_err(|error| InstallError::new(InstallErrorKind::Metadata, error.to_string())),
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(None),
+            Err(error) => Err(InstallError::new(
+                InstallErrorKind::Io,
+                format!("读 {} 失败：{error}", path.display()),
+            )),
+        }
+    }
+}
+
+/// 读清单缓存（文件缺失/损坏都当没有，不报错——缓存坏了就重新拉）。
+fn read_cache(path: &Path) -> Option<ManifestCache> {
+    let bytes = std::fs::read(path).ok()?;
+    serde_json::from_slice(&bytes).ok()
+}
+
+/// 当前毫秒时间戳（缓存 TTL 判定用；与下载引擎同一个时钟来源）。
+pub use crate::download::cache::now_ms;
+
+/// 把 [`GameError`] 转成"缺元数据"错误（供上层统一处理）。
+#[must_use]
+pub fn metadata_error(error: GameError) -> InstallError {
+    InstallError::new(InstallErrorKind::Metadata, error.to_string())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{metadata_error, now_ms, read_cache, ManifestCache, MANIFEST_TTL_MS};
+    use crate::game::error::GameError;
+    use crate::game::version::VersionList;
+
+    #[test]
+    fn ttl_constant_is_half_a_day() {
+        assert_eq!(MANIFEST_TTL_MS, 43_200_000);
+    }
+
+    #[test]
+    fn now_ms_is_a_plausible_wall_clock() {
+        // 2020-01-01 之后、2100 年之前：只用来挡住"单位错成秒"这类退化。
+        let now = now_ms();
+        assert!(now > 1_577_836_800_000, "now_ms 太小：{now}");
+        assert!(now < 4_102_444_800_000, "now_ms 太大：{now}");
+    }
+
+    #[test]
+    fn cache_roundtrip_and_corruption_tolerance() {
+        let dir = std::env::temp_dir().join(format!("ull-manifest-cache-{}", std::process::id()));
+        std::fs::create_dir_all(&dir).expect("建临时目录");
+        let path = dir.join("version_manifest_v2.json");
+
+        let cache = ManifestCache {
+            fetched_at_ms: 123,
+            list: VersionList::default(),
+        };
+        std::fs::write(&path, serde_json::to_vec(&cache).expect("序列化")).expect("写");
+        let read = read_cache(&path).expect("应读回");
+        assert_eq!(read.fetched_at_ms, 123);
+
+        std::fs::write(&path, b"not json").expect("写坏内容");
+        assert!(read_cache(&path).is_none());
+
+        assert!(read_cache(&dir.join("missing.json")).is_none());
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn game_error_becomes_metadata_error() {
+        let error = metadata_error(GameError::MissingVersionId);
+        assert_eq!(error.kind().as_str(), "install_metadata");
+    }
+}
diff --git a/crates/core/src/game/install/tests/execute.rs b/crates/core/src/game/install/tests/execute.rs
new file mode 100644
index 0000000..881ce3d
--- /dev/null
+++ b/crates/core/src/game/install/tests/execute.rs
@@ -0,0 +1,397 @@
+//! 落盘执行：跳过判定（三级）、幂等重装、预取元数据落盘、失败分类聚合。
+//!
+//! 全部用例都**已把文件放好**或**只做纯函数判定**，因此不发网络请求。
+
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
+use std::sync::Arc;
+
+use crate::download::verify;
+use crate::download::ResourceKind;
+use crate::download::{
+    ContentCache, DownloadEngine, DownloadErrorKind, EngineConfig, HashAlgo, HealthRegistry,
+    MirrorTable, RegionProfile,
+};
+use crate::game::arguments::Environment;
+use crate::game::install::assets::{AssetIndex, AssetObject};
+use crate::game::install::execute::{
+    current_bytes, execute, execute_with_cancel, FileOutcome, FileStatus,
+};
+use crate::game::install::plan::{FileRole, InstallPlan, PlanFile, PlanInput};
+use crate::game::layout::GameLayout;
+use crate::game::manifest::VersionJson;
+
+fn temp_root(tag: &str) -> PathBuf {
+    static COUNTER: AtomicU64 = AtomicU64::new(0);
+    let unique = COUNTER.fetch_add(1, Ordering::Relaxed);
+    std::env::temp_dir().join(format!(
+        "ull-install-exec-{}-{tag}-{unique}",
+        std::process::id()
+    ))
+}
+
+fn engine(root: &Path) -> DownloadEngine {
+    DownloadEngine::new(
+        EngineConfig::default(),
+        Arc::new(MirrorTable::builtin()),
+        Arc::new(RegionProfile::direct(0)),
+        Arc::new(HealthRegistry::in_memory()),
+        Arc::new(ContentCache::open(root.join("cache"))),
+    )
+}
+
+fn sha1_of(bytes: &[u8]) -> String {
+    verify::digest_bytes(HashAlgo::Sha1, bytes)
+}
+
+fn write_file(path: &Path, bytes: &[u8]) {
+    std::fs::create_dir_all(path.parent().expect("有父目录")).expect("建目录");
+    std::fs::write(path, bytes).expect("写文件");
+}
+
+#[test]
+fn current_bytes_matches_by_sha1_then_size_then_existence() {
+    let root = temp_root("current");
+    let payload = b"client jar payload";
+    let dest: PathBuf = root.join("versions/1.20.1/1.20.1.jar");
+    write_file(&dest, payload);
+
+    let with_sha1 = PlanFile {
+        role: FileRole::ClientJar,
+        name: "1.20.1".to_string(),
+        url: "https://example.invalid/x.jar".to_string(),
+        sha1: Some(sha1_of(payload)),
+        size: Some(payload.len() as u64),
+        dest: dest.clone(),
+        resource: ResourceKind::ClientJar,
+    };
+    assert_eq!(current_bytes(&with_sha1), Some(payload.len() as u64));
+
+    let wrong_sha1 = PlanFile {
+        sha1: Some("0".repeat(40)),
+        ..with_sha1.clone()
+    };
+    assert_eq!(current_bytes(&wrong_sha1), None, "sha1 不符必须重下");
+
+    let size_only = PlanFile {
+        sha1: None,
+        size: Some(payload.len() as u64),
+        ..with_sha1.clone()
+    };
+    assert_eq!(current_bytes(&size_only), Some(payload.len() as u64));
+
+    let size_mismatch = PlanFile {
+        sha1: None,
+        size: Some(1),
+        ..with_sha1.clone()
+    };
+    assert_eq!(current_bytes(&size_mismatch), None);
+
+    let bare = PlanFile {
+        sha1: None,
+        size: None,
+        ..with_sha1.clone()
+    };
+    assert_eq!(current_bytes(&bare), Some(payload.len() as u64), "存在即信");
+
+    let missing = PlanFile {
+        dest: root.join("nope.jar"),
+        ..with_sha1
+    };
+    assert_eq!(current_bytes(&missing), None);
+    std::fs::remove_dir_all(&root).ok();
+}
+
+/// 一份"客户端 jar 已存在"的清单 + 计划，用于幂等与跳过用例。
+fn plan_with_existing_jar(root: &Path) -> (InstallPlan, Vec<u8>) {
+    let payload = b"already installed client jar".to_vec();
+    let layout = GameLayout::new(root);
+    let sha1 = sha1_of(&payload);
+    write_file(&layout.version_jar("1.20.1"), &payload);
+
+    let resolved = VersionJson::from_json_str(&format!(
+        r#"{{"id": "1.20.1", "mainClass": "net.minecraft.client.main.Main",
+            "downloads": {{"client": {{"sha1": "{sha1}", "size": {}, "url": "https://piston-data.mojang.com/v1/objects/{sha1}/client.jar"}}}}}}"#,
+        payload.len()
+    ))
+    .expect("清单应可解析");
+
+    let plan = InstallPlan::build(PlanInput {
+        layout: &layout,
+        version_id: "1.20.1",
+        resolved: &resolved,
+        asset_index: None,
+        environment: &Environment::host(),
+    })
+    .expect("组计划应成功");
+    (plan, payload)
+}
+
+#[tokio::test]
+async fn skips_existing_files_and_writes_version_json() {
+    let root = temp_root("skip");
+    let (plan, payload) = plan_with_existing_jar(&root);
+    let engine = engine(&root);
+    let calls = Arc::new(AtomicUsize::new(0));
+    let sink_calls = Arc::clone(&calls);
+
+    let report = execute(
+        &engine,
+        &plan,
+        4,
+        Some(Arc::new(move |_outcome: &FileOutcome| {
+            sink_calls.fetch_add(1, Ordering::Relaxed);
+        })),
+    )
+    .await
+    .expect("执行应成功");
+
+    assert!(report.is_complete());
+    assert_eq!(report.downloaded(), 0, "已存在且校验通过的文件不该重下");
+    assert_eq!(report.skipped(), 1);
+    assert_eq!(report.bytes(), 0);
+    assert_eq!(calls.load(Ordering::Relaxed), 1, "每个文件回调一次");
+
+    // 版本清单必须落盘且能被重新解析。
+    let version_json = report.version_json.clone().expect("全量成功应写版本清单");
+    let text = std::fs::read_to_string(&version_json).expect("版本清单应已写盘");
+    let written = VersionJson::from_json_str(&text).expect("写出的清单应可解析");
+    assert_eq!(written.id.as_deref(), Some("1.20.1"));
+    assert_eq!(
+        written.main_class.as_deref(),
+        Some("net.minecraft.client.main.Main")
+    );
+
+    // 盘上内容没被改动（跳过 = 不动文件）。
+    assert_eq!(
+        std::fs::read(GameLayout::new(&root).version_jar("1.20.1")).expect("读 jar"),
+        payload
+    );
+    std::fs::remove_dir_all(&root).ok();
+}
+
+/// **取消：一个文件都不下、版本清单不落盘**（M105 的「半成品不许变成品」）。
+///
+/// 标志**开工前**就置位 ⇒ 走「一个文件都不起」那条路，全程零网络（所以这条能进 CI，
+/// 真网络的那条在 `crates/presenter/src/host/cancel_tests.rs`，`#[ignore]` 守着）。
+///
+/// 抓得住：取消返回 `Cancelled` 大类、`version_json` 没写、盘上没多出 jar。
+/// 抓不住：在飞的文件被掐断的那一刻（那要真网络 + 真字节流，见 presenter 的实测装置）。
+#[tokio::test]
+async fn cancelling_before_the_first_file_downloads_nothing_and_writes_no_manifest() {
+    let root = temp_root("cancel");
+    let layout = GameLayout::new(&root);
+    // jar **不在**盘上：真跑就会去下（本用例不许它跑起来）
+    let sha1 = "3f".repeat(20);
+    let resolved = VersionJson::from_json_str(&format!(
+        r#"{{"id": "1.20.1", "mainClass": "net.minecraft.client.main.Main",
+            "downloads": {{"client": {{"sha1": "{sha1}", "size": 32, "url": "https://piston-data.mojang.com/v1/objects/{sha1}/client.jar"}}}}}}"#
+    ))
+    .expect("清单应可解析");
+    let plan = InstallPlan::build(PlanInput {
+        layout: &layout,
+        version_id: "1.20.1",
+        resolved: &resolved,
+        asset_index: None,
+        environment: &Environment::host(),
+    })
+    .expect("组计划应成功");
+
+    let cancel = std::sync::atomic::AtomicBool::new(true);
+    let error = execute_with_cancel(&engine(&root), &plan, 4, None, Some(&cancel))
+        .await
+        .expect_err("取消了就不要返回 report");
+    assert_eq!(
+        error.kind(),
+        crate::game::install::InstallErrorKind::Cancelled,
+        "取消是独立大类，不是网络/IO 失败"
+    );
+    assert!(
+        !plan.version_json_path.is_file(),
+        "取消后不许落版本清单（否则半成品会被当成已安装）"
+    );
+    assert!(!layout.version_jar("1.20.1").is_file(), "一个文件都不该下");
+    std::fs::remove_dir_all(&root).ok();
+}
+
+#[tokio::test]
+async fn reinstalling_twice_is_idempotent() {
+    let root = temp_root("idempotent");
+    let (plan, _) = plan_with_existing_jar(&root);
+    let engine = engine(&root);
+    let first = execute(&engine, &plan, 2, None).await.expect("第一次");
+    let second = execute(&engine, &plan, 2, None).await.expect("第二次");
+
+    assert!(first.is_complete() && second.is_complete());
+    assert_eq!(second.downloaded(), 0);
+    assert_eq!(second.skipped(), second.files.len());
+    std::fs::remove_dir_all(&root).ok();
+}
+
+#[tokio::test]
+async fn prefetched_metadata_is_written_without_network() {
+    let root = temp_root("prefetch");
+    let layout = GameLayout::new(&root);
+    let hash = "0f9d6b1c0d5f4e3b2a1908070605040302010f0e";
+    // 规划期"已经下载到内存"的资源索引字节（sha1 必须与清单声明一致，否则跳过判定不成立）。
+    let index_bytes = br#"{"objects":{}}"#.to_vec();
+    let index_sha1 = sha1_of(&index_bytes);
+    let resolved = VersionJson::from_json_str(&format!(
+        r#"{{"id": "1.20.1", "assetIndex": {{"id": "17", "sha1": "{index_sha1}", "size": {}, "url": "https://piston-meta.mojang.com/v1/packages/{index_sha1}/17.json"}}}}"#,
+        index_bytes.len()
+    ))
+    .expect("清单应可解析");
+    let mut index = AssetIndex::default();
+    index.objects.insert(
+        "minecraft/lang/zh_cn.json".to_string(),
+        AssetObject {
+            hash: hash.to_string(),
+            size: 3,
+        },
+    );
+
+    let mut plan = InstallPlan::build(PlanInput {
+        layout: &layout,
+        version_id: "1.20.1",
+        resolved: &resolved,
+        asset_index: Some(&index),
+        environment: &Environment::host(),
+    })
+    .expect("组计划应成功");
+
+    let index_dest = layout.asset_index("17");
+    plan.prefetch(index_dest.clone(), index_bytes.clone());
+
+    // 只跑索引这一个文件：把资源对象从计划里摘掉，避免真发网络请求。
+    plan.files.retain(|file| file.role != FileRole::Asset);
+    let engine = engine(&root);
+    let report = execute(&engine, &plan, 2, None).await.expect("执行应成功");
+
+    assert!(report.is_complete(), "不该有失败：{:?}", report.failures(3));
+    assert_eq!(report.downloaded(), 1);
+    assert_eq!(
+        std::fs::read(&index_dest).expect("索引应已写盘"),
+        index_bytes
+    );
+    let outcome = report
+        .files
+        .iter()
+        .find(|file| file.dest == index_dest)
+        .expect("应有索引结果");
+    assert_eq!(outcome.source.as_deref(), Some("metadata"));
+
+    // 重跑：索引已在盘上且 sha1 一致 → 跳过，不重写、不算"下载"。
+    let again = execute(&engine, &plan, 2, None).await.expect("第二次");
+    assert_eq!(again.downloaded(), 0, "重装不该再写索引");
+    assert_eq!(again.skipped(), 1);
+    std::fs::remove_dir_all(&root).ok();
+}
+
+#[test]
+fn failure_kind_prefers_integrity() {
+    let failed = |kind: DownloadErrorKind| FileOutcome {
+        role: FileRole::Asset,
+        name: "x".to_string(),
+        dest: PathBuf::from("/x"),
+        status: FileStatus::Failed,
+        bytes: 0,
+        source: None,
+        failure: Some(crate::game::install::FileFailure {
+            kind,
+            message: "boom".to_string(),
+        }),
+    };
+    let report = crate::game::install::InstallReport {
+        files: vec![
+            failed(DownloadErrorKind::AllSourcesFailed),
+            failed(DownloadErrorKind::Integrity),
+        ],
+        version_json: None,
+        warnings: Vec::new(),
+    };
+    assert_eq!(report.failed(), 2);
+    assert!(!report.is_complete());
+    assert_eq!(report.failure_kind(), Some(DownloadErrorKind::Integrity));
+    assert_eq!(report.failures(1).len(), 1);
+}
+
+/// **取消之后，剩下的文件连 `install_one` 都不许进**（复审 P2-1 的守门，p1）。
+///
+/// 现场（修前）：标志检查只写在 `select` 的右支，而 `select` 先轮询左支 —— 左支第一次 poll
+/// 就把 `engine.download(…)` 派出去了。于是取消后 `buffer_unordered` 立刻让出槽位、流继续被拉，
+/// **每一个剩余 item 都会各发一次整文件 sha1 + 一次请求**，1.20.1 那种四位数文件的 plan 会一直
+/// 走到列表末尾；盘上已就绪的文件第一 poll 就 `Ready` ⇒ 还会各回调一次 `sink`。
+///
+/// 这条用例把它钉成可数的东西：三个文件全在盘上（`install_one` 直接判 Skipped、零网络），
+/// 并发 1，`sink` 第一次回调时置取消标志 —— 于是「取消后还剩几个文件被处理」= `sink` 的调用次数。
+/// 修好后必须是 **1**（只有第一个），修前是 **3**。
+///
+/// 抓得住：`async move` 开头那句 `if is_cancelled(cancel) { return None; }` 被删掉/挪到 `select` 右支。
+/// 抓不住：在飞的那一个文件被掐断的时机（那要真字节流，见 presenter 的真网络装置）。
+#[tokio::test]
+async fn cancelling_mid_run_stops_creating_remaining_files() {
+    let root = temp_root("cancel-mid");
+    let layout = GameLayout::new(&root);
+    let jar = b"client jar payload".to_vec();
+    let sha1 = sha1_of(&jar);
+    write_file(&layout.version_jar("1.20.1"), &jar);
+    let resolved = VersionJson::from_json_str(&format!(
+        r#"{{"id": "1.20.1", "mainClass": "net.minecraft.client.main.Main",
+            "downloads": {{"client": {{"sha1": "{sha1}", "size": {}, "url": "https://piston-data.mojang.com/v1/objects/{sha1}/client.jar"}}}}}}"#,
+        jar.len()
+    ))
+    .expect("清单应可解析");
+    let mut plan = InstallPlan::build(PlanInput {
+        layout: &layout,
+        version_id: "1.20.1",
+        resolved: &resolved,
+        asset_index: None,
+        environment: &Environment::host(),
+    })
+    .expect("组计划应成功");
+
+    // 再挂两个"已在盘上"的库文件：内容与声明的 sha1 一致 ⇒ 跳过判定成立、零网络。
+    for name in ["org.example:a:1.0", "org.example:b:1.0"] {
+        let bytes = format!("payload for {name}").into_bytes();
+        let dest = root
+            .join("libraries")
+            .join(format!("{}.jar", name.replace(':', "-")));
+        write_file(&dest, &bytes);
+        plan.files.push(PlanFile {
+            role: FileRole::Library,
+            name: name.to_string(),
+            url: format!("https://example.invalid/{name}.jar"),
+            sha1: Some(sha1_of(&bytes)),
+            size: Some(bytes.len() as u64),
+            dest,
+            resource: ResourceKind::Library,
+        });
+    }
+    assert_eq!(plan.files.len(), 3, "三个文件全在盘上 ⇒ 全程零网络");
+
+    let seen = Arc::new(AtomicUsize::new(0));
+    // `sink` 是 `Fn + 'static`，所以标志也必须 `Arc` 进来；第一次回调就置取消。
+    let flag = Arc::new(std::sync::atomic::AtomicBool::new(false));
+    let sink_seen = Arc::clone(&seen);
+    let sink_flag = Arc::clone(&flag);
+    let sink: crate::game::install::ProgressSink = Arc::new(move |_outcome: &FileOutcome| {
+        sink_seen.fetch_add(1, Ordering::SeqCst);
+        sink_flag.store(true, Ordering::SeqCst);
+    });
+
+    let error = execute_with_cancel(&engine(&root), &plan, 1, Some(sink), Some(flag.as_ref()))
+        .await
+        .expect_err("取消之后不许返回成功 report");
+    assert_eq!(
+        error.kind(),
+        crate::game::install::InstallErrorKind::Cancelled
+    );
+    assert_eq!(
+        seen.load(Ordering::SeqCst),
+        1,
+        "取消只该让**第一个**文件走完回调；剩下的 item 必须连 install_one 都不进\
+         （修前这里会是 3：每个剩余文件各多算一次 sha1、各多发一次请求）"
+    );
+    assert!(!plan.version_json_path.is_file(), "取消后不许落版本清单");
+    std::fs::remove_dir_all(&root).ok();
+}
diff --git a/crates/core/src/game/install/tests/instance.rs b/crates/core/src/game/install/tests/instance.rs
new file mode 100644
index 0000000..797859c
--- /dev/null
+++ b/crates/core/src/game/install/tests/instance.rs
@@ -0,0 +1,122 @@
+//! 实例登记：幂等（同版本同名复用）、`isolation: inherit` 不落盘、两份文件各就各位。
+
+use std::path::PathBuf;
+
+use crate::game::install::instance::{
+    read_instance_config, read_profiles, register, InstanceConfig, Isolation,
+};
+use crate::platform::layout::LauncherLayout;
+
+fn temp_layout(tag: &str) -> (LauncherLayout, PathBuf) {
+    let unique = format!(
+        "{}-{}-{tag}",
+        std::process::id(),
+        std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .map(|d| d.as_nanos())
+            .unwrap_or(0)
+    );
+    let root = std::env::temp_dir().join(format!("ull-install-instance-{unique}"));
+    let layout = LauncherLayout::new(&root);
+    layout.ensure().expect("建四分区");
+    (layout, root)
+}
+
+#[test]
+fn registers_profile_and_sparse_instance_config() {
+    let (layout, root) = temp_layout("new");
+    let registration = register(
+        &layout,
+        "1.20.1",
+        "1.20.1",
+        Some("2026-10-30T00:00:00.000Z"),
+    )
+    .expect("登记应成功");
+    assert!(registration.created);
+    assert!(
+        registration.profile.id.is_uuid_shaped(),
+        "实例 id 必须是稳定 UUID 形状"
+    );
+    assert!(registration.config_path.is_file());
+
+    let profiles = read_profiles(&layout).expect("读实例清单");
+    assert_eq!(profiles.len(), 1);
+    assert_eq!(profiles.profiles[0].version_id, "1.20.1");
+    assert_eq!(
+        profiles.profiles[0].created_at.as_deref(),
+        Some("2026-10-30T00:00:00.000Z")
+    );
+
+    // 每实例设置：id / versionId / schemaVersion 在，isolation 缺省不落盘。
+    let text = std::fs::read_to_string(&registration.config_path).expect("读设置文件");
+    assert!(
+        text.contains("\"versionId\": \"1.20.1\""),
+        "键名用 camelCase：{text}"
+    );
+    assert!(
+        !text.contains("isolation"),
+        "inherit 是默认值且不落盘：{text}"
+    );
+    assert!(!text.contains("gameDir"), "非 custom 不写 gameDir：{text}");
+
+    let config = read_instance_config(&layout, registration.profile.id.as_str())
+        .expect("读设置")
+        .expect("设置文件应存在");
+    assert!(config.inherits_isolation());
+    assert_eq!(config.id, registration.profile.id.as_str());
+    std::fs::remove_dir_all(&root).ok();
+}
+
+#[test]
+fn reinstall_same_version_reuses_instance() {
+    let (layout, root) = temp_layout("idempotent");
+    let first = register(&layout, "1.20.1", "1.20.1", None).expect("第一次登记");
+    let second = register(&layout, "1.20.1", "1.20.1", None).expect("第二次登记");
+
+    assert!(!second.created, "同版本同名应复用");
+    assert_eq!(second.profile.id.as_str(), first.profile.id.as_str());
+    assert_eq!(read_profiles(&layout).expect("读清单").len(), 1);
+    std::fs::remove_dir_all(&root).ok();
+}
+
+#[test]
+fn distinct_names_create_distinct_instances_of_same_version() {
+    let (layout, root) = temp_layout("names");
+    let a = register(&layout, "生存", "1.20.1", None).expect("A");
+    let b = register(&layout, "创造", "1.20.1", None).expect("B");
+
+    assert!(a.created && b.created);
+    assert_ne!(a.profile.id.as_str(), b.profile.id.as_str());
+    assert_eq!(read_profiles(&layout).expect("读清单").len(), 2);
+    std::fs::remove_dir_all(&root).ok();
+}
+
+#[test]
+fn instance_config_roundtrip_keeps_explicit_isolation() {
+    let mut config = InstanceConfig::new("11111111-2222-4333-8444-555555555555", "1.20.1");
+    config.isolation = Some(Isolation::Isolated);
+    let text = config.to_json_string().expect("序列化");
+    assert!(text.contains("\"isolation\": \"isolated\""));
+    let back = InstanceConfig::from_json_str(&text).expect("反序列化");
+    assert_eq!(back.isolation, Some(Isolation::Isolated));
+    assert!(!back.inherits_isolation());
+    assert_eq!(Isolation::parse("custom"), Some(Isolation::Custom));
+    assert_eq!(Isolation::parse("inherit"), None, "inherit 不是显式值");
+}
+
+#[test]
+fn registers_legacy_profile_without_config_file() {
+    let (layout, root) = temp_layout("legacy");
+    // 早期 CLI 只写 profiles.json（没有 instances/<id>.json）。
+    let profile = crate::game::profiles::InstanceProfile::new("老实例", "1.20.1");
+    let id = profile.id.as_str().to_string();
+    let mut profiles = crate::game::profiles::ProfileList::default();
+    profiles.upsert(profile);
+    super::super::instance::write_profiles(&layout, &profiles).expect("写清单");
+
+    let registration = register(&layout, "老实例", "1.20.1", None).expect("补登记");
+    assert!(!registration.created, "已有档案应复用");
+    assert_eq!(registration.profile.id.as_str(), id);
+    assert!(registration.config_path.is_file(), "缺失的设置文件应补齐");
+    std::fs::remove_dir_all(&root).ok();
+}
diff --git a/crates/core/src/game/install/tests/mod.rs b/crates/core/src/game/install/tests/mod.rs
new file mode 100644
index 0000000..21cecbe
--- /dev/null
+++ b/crates/core/src/game/install/tests/mod.rs
@@ -0,0 +1,8 @@
+//! `game::install` 的单元测试：计划正确性 / 跳过与幂等 / 实例登记。
+//!
+//! 刻意**不打真实网络**：计划是纯计算，跳过判定只看盘，实例登记只看文件系统。
+//! 需要"引擎"的用例只要求它"不联网也能跑"（全部文件已就位 → 全跳过）。
+
+mod execute;
+mod instance;
+mod plan;
diff --git a/crates/core/src/game/install/tests/plan.rs b/crates/core/src/game/install/tests/plan.rs
new file mode 100644
index 0000000..dddf582
--- /dev/null
+++ b/crates/core/src/game/install/tests/plan.rs
@@ -0,0 +1,285 @@
+//! 计划正确性：多级继承折叠后的文件清单、URL/sha1/落点逐项、JSON 形状。
+
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use crate::game::arguments::Environment;
+use crate::game::inherit::resolve;
+use crate::game::install::assets::{AssetIndex, AssetObject};
+use crate::game::install::plan::{FileRole, InstallPlan, PlanInput};
+use crate::game::layout::GameLayout;
+use crate::game::manifest::VersionJson;
+
+fn temp_root(tag: &str) -> std::path::PathBuf {
+    static COUNTER: AtomicU64 = AtomicU64::new(0);
+    let unique = COUNTER.fetch_add(1, Ordering::Relaxed);
+    std::env::temp_dir().join(format!(
+        "ull-install-plan-{}-{tag}-{unique}",
+        std::process::id()
+    ))
+}
+
+/// 三层继承：base（客户端 jar + 资源索引 + 库）← mid（库）← top（库）。
+fn resolved_three_levels() -> VersionJson {
+    let base = VersionJson::from_json_str(
+        r#"{
+            "id": "base",
+            "mainClass": "net.minecraft.client.main.Main",
+            "downloads": {"client": {"sha1": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "size": 100, "url": "https://piston-data.mojang.com/v1/objects/aa/client.jar"}},
+            "assetIndex": {"id": "17", "sha1": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "size": 200, "totalSize": 300, "url": "https://piston-meta.mojang.com/v1/packages/bb/17.json"},
+            "assets": "17",
+            "libraries": [
+                {"name": "org.ow2.asm:asm:9.6", "downloads": {"artifact": {"path": "org/ow2/asm/asm/9.6/asm-9.6.jar", "sha1": "c1", "size": 11, "url": "https://libraries.minecraft.net/org/ow2/asm/asm/9.6/asm-9.6.jar"}}},
+                {"name": "org.lwjgl:lwjgl:3.3.2", "rules": [{"action": "allow", "os": {"name": "linux"}}], "downloads": {"artifact": {"url": "https://libraries.minecraft.net/lwjgl-linux-only.jar", "sha1": "c2", "size": 5}}}
+            ]
+        }"#,
+    )
+    .expect("base 清单应可解析");
+    let mid = VersionJson::from_json_str(
+        r#"{"id": "mid", "inheritsFrom": "base", "libraries": [
+            {"name": "net.minecraftforge:forge:1.20.1-47.2.0", "downloads": {"artifact": {"path": "net/minecraftforge/forge/1.20.1-47.2.0/forge-1.20.1-47.2.0.jar", "sha1": "c3", "size": 22, "url": "https://maven.minecraftforge.net/forge.jar"}}}
+        ]}"#,
+    )
+    .expect("mid 清单应可解析");
+    let top = VersionJson::from_json_str(
+        r#"{"id": "top", "inheritsFrom": "mid", "libraries": [
+            {"name": "top.patch:core:1.0", "downloads": {"artifact": {"path": "top/patch/core/1.0/core-1.0.jar", "sha1": "c4", "size": 33, "url": "https://example.invalid/core-1.0.jar"}}}
+        ], "logging": {"client": {"argument": "-Dlog4j.configurationFile=${path}", "file": {"id": "client-1.12.xml", "sha1": "dd", "size": 44, "url": "https://piston-data.mojang.com/v1/objects/dd/client-1.12.xml"}}}}"#,
+    )
+    .expect("top 清单应可解析");
+
+    let mut table = std::collections::BTreeMap::new();
+    table.insert("base".to_string(), base);
+    table.insert("mid".to_string(), mid);
+    table.insert("top".to_string(), top.clone());
+    resolve(&table, &top).expect("三层继承应解析成功")
+}
+
+fn asset_index() -> AssetIndex {
+    let mut index = AssetIndex::default();
+    index.objects.insert(
+        "minecraft/lang/zh_cn.json".to_string(),
+        AssetObject {
+            hash: "0f9d6b1c0d5f4e3b2a1908070605040302010f0e".to_string(),
+            size: 55,
+        },
+    );
+    index
+}
+
+fn build(layout: &GameLayout, resolved: &VersionJson, index: Option<&AssetIndex>) -> InstallPlan {
+    InstallPlan::build(PlanInput {
+        layout,
+        version_id: "top",
+        resolved,
+        asset_index: index,
+        environment: &Environment::host(),
+    })
+    .expect("组计划应成功")
+}
+
+#[test]
+fn folds_inheritance_chain_into_one_plan() {
+    let root = temp_root("chain");
+    let layout = GameLayout::new(&root);
+    let resolved = resolved_three_levels();
+    // 三层库都保留（父在前、子在后，去重后按角色/路径排序）。
+    assert_eq!(resolved.libraries.as_ref().map(Vec::len), Some(4));
+
+    let index = asset_index();
+    let plan = build(&layout, &resolved, Some(&index));
+
+    // 客户端 jar 1 + 库 4（linux 规则那条在 Windows 上被过滤）+ 索引 1 + 资源 1 + 日志配置 1。
+    let host_linux = Environment::host().os == "linux";
+    let expected_libraries = if host_linux { 4 } else { 3 };
+    assert_eq!(
+        plan.by_role()
+            .get(&FileRole::ClientJar)
+            .map(|entry| entry.0),
+        Some(1)
+    );
+    assert_eq!(
+        plan.by_role().get(&FileRole::Library).map(|entry| entry.0),
+        Some(expected_libraries)
+    );
+    assert_eq!(
+        plan.by_role()
+            .get(&FileRole::AssetIndex)
+            .map(|entry| entry.0),
+        Some(1)
+    );
+    assert_eq!(
+        plan.by_role().get(&FileRole::Asset).map(|entry| entry.0),
+        Some(1)
+    );
+    assert_eq!(
+        plan.by_role()
+            .get(&FileRole::LogConfig)
+            .map(|entry| entry.0),
+        Some(1)
+    );
+    assert!(plan.warnings.is_empty(), "不应有告警：{:?}", plan.warnings);
+    std::fs::remove_dir_all(&root).ok();
+}
+
+#[test]
+fn client_jar_lands_in_version_dir_with_manifest_hash() {
+    let root = temp_root("jar");
+    let layout = GameLayout::new(&root);
+    let resolved = resolved_three_levels();
+    let plan = build(&layout, &resolved, None);
+
+    let jar = plan
+        .files
+        .iter()
+        .find(|file| file.role == FileRole::ClientJar)
+        .expect("应有客户端 jar");
+    assert_eq!(plan.jar_id, "top");
+    assert!(jar.dest.ends_with("versions/top/top.jar"));
+    assert_eq!(
+        jar.sha1.as_deref(),
+        Some("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
+    );
+    assert_eq!(jar.size, Some(100));
+    assert_eq!(
+        jar.url,
+        "https://piston-data.mojang.com/v1/objects/aa/client.jar"
+    );
+    std::fs::remove_dir_all(&root).ok();
+}
+
+#[test]
+fn asset_object_paths_and_hashes_are_exact() {
+    let root = temp_root("assets");
+    let layout = GameLayout::new(&root);
+    let resolved = resolved_three_levels();
+    let index = asset_index();
+    let plan = build(&layout, &resolved, Some(&index));
+
+    let object = plan
+        .files
+        .iter()
+        .find(|file| file.role == FileRole::Asset)
+        .expect("应有资源对象");
+    assert_eq!(
+        object.url,
+        "https://resources.download.minecraft.net/0f/0f9d6b1c0d5f4e3b2a1908070605040302010f0e"
+    );
+    assert_eq!(
+        object.sha1.as_deref(),
+        Some("0f9d6b1c0d5f4e3b2a1908070605040302010f0e")
+    );
+    assert_eq!(object.size, Some(55));
+    assert!(object
+        .dest
+        .ends_with("assets/objects/0f/0f9d6b1c0d5f4e3b2a1908070605040302010f0e"));
+
+    let index_file = plan
+        .files
+        .iter()
+        .find(|file| file.role == FileRole::AssetIndex)
+        .expect("应有资源索引");
+    assert!(index_file.dest.ends_with("assets/indexes/17.json"));
+    assert_eq!(
+        index_file.sha1.as_deref(),
+        Some("bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb")
+    );
+    std::fs::remove_dir_all(&root).ok();
+}
+
+#[test]
+fn shares_libraries_across_versions_and_sums_totals() {
+    let root = temp_root("totals");
+    let layout = GameLayout::new(&root);
+    let resolved = resolved_three_levels();
+    let index = asset_index();
+    let plan = build(&layout, &resolved, Some(&index));
+
+    let (total, unknown) = plan.total_bytes();
+    // jar 100 + 索引 200 + 资源 55 + 日志 44 + 各库大小（host 上生效的那几条）。
+    assert_eq!(unknown, 0);
+    assert!(total >= 399, "总大小应至少含 jar+索引+资源+日志：{total}");
+
+    // 库落恒共享层（不是实例私有）。
+    for file in plan
+        .files
+        .iter()
+        .filter(|file| file.role == FileRole::Library)
+    {
+        assert!(file.dest.starts_with(root.join("libraries")));
+    }
+    std::fs::remove_dir_all(&root).ok();
+}
+
+#[test]
+fn warns_instead_of_inventing_urls_for_legacy_manifests() {
+    let root = temp_root("legacy");
+    let layout = GameLayout::new(&root);
+    let legacy = VersionJson::from_json_str(r#"{"id": "c0.30_01c", "assets": "legacy"}"#)
+        .expect("旧清单应可解析");
+    let plan = build(&layout, &legacy, None);
+
+    assert!(plan.files.is_empty(), "旧清单没有可下文件");
+    assert_eq!(
+        plan.warnings.len(),
+        2,
+        "应分别告警缺 jar 与缺索引：{:?}",
+        plan.warnings
+    );
+    assert!(plan.warnings.iter().any(|w| w.contains("downloads.client")));
+    assert!(plan.warnings.iter().any(|w| w.contains("assetIndex")));
+    std::fs::remove_dir_all(&root).ok();
+}
+
+#[test]
+fn json_shape_is_stable_for_dry_run_consumers() {
+    let root = temp_root("json");
+    let layout = GameLayout::new(&root);
+    let resolved = resolved_three_levels();
+    let index = asset_index();
+    let plan = build(&layout, &resolved, Some(&index));
+
+    let summary = plan.summary_json();
+    assert_eq!(summary["version_id"], "top");
+    assert_eq!(summary["jar_id"], "top");
+    assert_eq!(summary["file_count"], plan.file_count());
+    assert!(summary["total_bytes"].as_u64().unwrap_or(0) > 0);
+    assert!(summary["by_role"]["client_jar"]["files"].as_u64() == Some(1));
+    assert!(summary["warnings"].is_array());
+
+    let files = plan.files_json();
+    assert_eq!(files.len(), plan.file_count());
+    for row in &files {
+        assert!(row["role"].as_str().is_some());
+        assert!(row["url"].as_str().is_some());
+        assert!(row["dest"].as_str().is_some());
+        assert!(row["resource"].as_str().is_some());
+    }
+    std::fs::remove_dir_all(&root).ok();
+}
+
+#[test]
+fn deduplicates_same_destination_and_prefers_hashed_copy() {
+    let root = temp_root("dedupe");
+    let layout = GameLayout::new(&root);
+    let resolved = VersionJson::from_json_str(
+        r#"{"id": "1.20.1", "libraries": [
+            {"name": "a.b:c:1", "downloads": {"artifact": {"path": "a/b/c/1/c-1.jar", "url": "https://libraries.minecraft.net/c-1.jar"}}},
+            {"name": "a.b:c:1", "downloads": {"artifact": {"path": "a/b/c/1/c-1.jar", "sha1": "ff", "size": 9, "url": "https://libraries.minecraft.net/c-1.jar"}}}
+        ]}"#,
+    )
+    .expect("清单应可解析");
+    let plan = build(&layout, &resolved, None);
+
+    let libraries: Vec<_> = plan
+        .files
+        .iter()
+        .filter(|file| file.role == FileRole::Library)
+        .collect();
+    assert_eq!(libraries.len(), 1, "同一落点只应留一条");
+    assert_eq!(
+        libraries[0].sha1.as_deref(),
+        Some("ff"),
+        "应保留带 sha1 的那条"
+    );
+    std::fs::remove_dir_all(&root).ok();
+}
diff --git a/crates/core/src/game/isolation.rs b/crates/core/src/game/isolation.rs
new file mode 100644
index 0000000..e575962
--- /dev/null
+++ b/crates/core/src/game/isolation.rs
@@ -0,0 +1,345 @@
+//! 实例隔离档位的**派生**与**切换检测**（D20 定案）。
+//!
+//! 依据：`DevDocs/PlanDoc/research/04-launcher-configs.md` §5.1-§5.2（键草案 + 切换检测）、
+//! `DevDocs/analyse/07-settings-packaging-update.md` §2.4（HMCL 用 `runningDirectory` 覆盖表达隔离）、
+//! `DevDocs/PlanDoc/04-data-and-config.md` §4（实例模型）。
+//!
+//! # D20 的语义（用户定案，不可改）
+//!
+//! - **默认隔离**：全局 `instances.mode` 默认 `isolated`，用户可手动切 `shared`；
+//! - **恒共享层不可配**：`versions/` `assets/` `libraries/` 永远在游戏根，隔离只改**运行目录**
+//!   （= `--gameDir` 的取值 + 进程 CWD），见 [`SHARED_LAYERS`]；
+//! - **切换不迁移 + 双侧内容提示**：切档只改路径语义，不动任何数据；两侧都有内容时提示
+//!   （[`ModeChange::take_warning`]），避免「存档消失」错觉。
+//!
+//! # 覆盖链（三层，左优先）
+//!
+//! ```text
+//! 临时启动参数（--game-dir 之类）  >  实例 isolation  >  全局 instances.mode
+//! ```
+//!
+//! `isolation` 的 `inherit` 不是第四个档位，而是「键不存在」→ 落到全局（[`IsolationMode`]）；
+//! 这样改全局对存量实例立即生效，不需要迁移（research/04 §5.3 的 PCL2 反面教材）。
+//!
+//! 本模块只做**纯路径计算 + 只读探测**：不建目录、不搬文件、不写配置。
+
+use std::path::{Path, PathBuf};
+
+use serde::{Deserialize, Serialize};
+
+use super::error::GameError;
+use super::install::instance::{InstanceConfig, Isolation};
+use super::layout::GameLayout;
+
+/// 恒共享层（任何隔离档位都不按实例复制；natives 例外，按实例解包）。
+pub const SHARED_LAYERS: &[&str] = &["versions", "assets", "libraries"];
+
+/// 切换检测探测的三类内容目录（两家启动器一致：只关心玩家数据）。
+pub const PROBED_CONTENT_DIRS: &[&str] = &["mods", "saves", "config"];
+
+/// 全局默认隔离模式（`launcher.json` 的 `instances.mode`）。
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum IsolationMode {
+    /// 每实例运行目录 = `versions/<versionId>/`（D20 默认）。
+    #[default]
+    Isolated,
+    /// 所有实例共用 `.minecraft` 根（HMCL 传统单目录形态）。
+    Shared,
+}
+
+impl IsolationMode {
+    /// 稳定字符串 id（与 `setting::keys::INSTANCE_MODES` 同字面量）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Isolated => "isolated",
+            Self::Shared => "shared",
+        }
+    }
+
+    /// 从字符串解析（未知值返回 `None`，由调用方决定报错还是取默认）。
+    #[must_use]
+    pub fn parse(raw: &str) -> Option<Self> {
+        match raw.trim() {
+            "isolated" => Some(Self::Isolated),
+            "shared" => Some(Self::Shared),
+            _ => None,
+        }
+    }
+
+    /// 折算成实例档位（全局模式只有两档，`inherit`/`custom` 不存在）。
+    #[must_use]
+    pub const fn as_isolation(self) -> Isolation {
+        match self {
+            Self::Isolated => Isolation::Isolated,
+            Self::Shared => Isolation::Shared,
+        }
+    }
+}
+
+/// 派生结论的来源（诊断/日志用，`mode` 变了要能解释为什么）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum IsolationSource {
+    /// 临时启动参数覆盖（最高优先）。
+    Temporary,
+    /// 实例文件里的 `isolation`。
+    Instance,
+    /// 全局 `instances.mode`（实例 `inherit` 或没有实例文件）。
+    Global,
+}
+
+impl IsolationSource {
+    /// 稳定名。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Temporary => "temporary",
+            Self::Instance => "instance",
+            Self::Global => "global",
+        }
+    }
+}
+
+/// 一次派生（覆盖链求值）的结论。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Derivation {
+    /// 生效档位（`inherit` 已被解析掉）。
+    pub isolation: Isolation,
+    /// 生效运行目录（喂 `--gameDir` 与进程 CWD）。
+    pub game_dir: PathBuf,
+    /// 档位来自哪一层。
+    pub source: IsolationSource,
+}
+
+/// 按覆盖链派生运行目录（纯计算，不碰盘）。
+///
+/// - `temporary`：临时启动参数给的目录（空路径视为未给）；
+/// - `instance`：实例设置；`isolation` 为 `None`（= `inherit`）或没有实例时落到 `global_mode`；
+/// - `custom` 却没有 `gameDir` → [`GameError::CustomIsolationWithoutDir`]（不猜默认目录）。
+///
+/// # Errors
+///
+/// `custom` 档位缺 `gameDir` 时返回 [`GameError::CustomIsolationWithoutDir`]。
+pub fn derive_game_dir(
+    layout: &GameLayout,
+    version_id: &str,
+    global_mode: IsolationMode,
+    instance: Option<&InstanceConfig>,
+    temporary: Option<&Path>,
+) -> Result<Derivation, GameError> {
+    let (isolation, source) = match instance.and_then(|config| config.isolation) {
+        Some(isolation) => (isolation, IsolationSource::Instance),
+        None => (global_mode.as_isolation(), IsolationSource::Global),
+    };
+    if let Some(path) = temporary.filter(|path| !path.as_os_str().is_empty()) {
+        return Ok(Derivation {
+            isolation,
+            game_dir: path.to_path_buf(),
+            source: IsolationSource::Temporary,
+        });
+    }
+    let game_dir = match isolation {
+        Isolation::Isolated => layout.version_dir(version_id),
+        Isolation::Shared => layout.root().to_path_buf(),
+        Isolation::Custom => match instance.and_then(|config| config.game_dir.clone()) {
+            Some(path) if !path.as_os_str().is_empty() => path,
+            _ => {
+                return Err(GameError::CustomIsolationWithoutDir {
+                    instance: instance.map_or_else(String::new, |config| config.id.clone()),
+                })
+            }
+        },
+    };
+    Ok(Derivation {
+        isolation,
+        game_dir,
+        source,
+    })
+}
+
+/// 一侧目录的内容探测结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SideContent {
+    /// 探测的目录（隔离侧 = `versions/<versionId>/`，共享侧 = `.minecraft/`）。
+    pub path: PathBuf,
+    /// `mods` `saves` `config` 三类内容的条目数合计。
+    pub entries: u32,
+}
+
+impl SideContent {
+    /// 是否有玩家数据（条目数 > 0）。
+    #[must_use]
+    pub const fn occupied(&self) -> bool {
+        self.entries > 0
+    }
+}
+
+/// 切换检测的双侧快照（落进 `lastModeChange.probe`）。
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ModeChangeProbe {
+    /// 隔离侧条目数。
+    pub isolated_side: u32,
+    /// 共享侧条目数。
+    pub shared_side: u32,
+}
+
+impl ModeChangeProbe {
+    /// 两侧都有内容（切换后玩家会以为「存档消失」的条件）。
+    #[must_use]
+    pub const fn both_occupied(&self) -> bool {
+        self.isolated_side > 0 && self.shared_side > 0
+    }
+}
+
+/// 一次隔离档位切换的记录（实例文件的 `lastModeChange`，启动器写入）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ModeChange {
+    /// 切换时间（RFC-3339，由调用方给——core::game 不碰时钟格式）。
+    pub at: String,
+    /// 切换前生效档位。
+    pub from: Isolation,
+    /// 切换后生效档位。
+    pub to: Isolation,
+    /// 切换当时的双侧内容探测（只探测，不迁移）。
+    #[serde(default)]
+    pub probe: ModeChangeProbe,
+    /// 提示是否已展示过（保证「切换后首次启动提示一次」而不是每次启动都刷）。
+    #[serde(default)]
+    pub warned: bool,
+}
+
+impl ModeChange {
+    /// 是否是一次**真的**切换（`from != to`；首启建基线时两者相同）。
+    #[must_use]
+    pub fn is_real_change(&self) -> bool {
+        self.from != self.to
+    }
+
+    /// 取走待展示的提示：真切换 + 两侧都有内容 + 还没提示过。
+    ///
+    /// 取走后把 `warned` 置真（调用方负责落盘），因此同一次切换只提示一次。
+    pub fn take_warning(&mut self) -> Option<ModeChangeWarning> {
+        if self.warned || !self.is_real_change() || !self.probe.both_occupied() {
+            return None;
+        }
+        self.warned = true;
+        Some(ModeChangeWarning {
+            from: self.from,
+            to: self.to,
+            probe: self.probe,
+        })
+    }
+}
+
+/// 「切换后两侧都有内容」的提示（D20：**只提示不迁移**）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ModeChangeWarning {
+    /// 切换前档位。
+    pub from: Isolation,
+    /// 切换后档位。
+    pub to: Isolation,
+    /// 双侧探测结果。
+    pub probe: ModeChangeProbe,
+}
+
+impl ModeChangeWarning {
+    /// 一句给人看的文案（含两侧条目数与「不自动搬迁」的说明）。
+    #[must_use]
+    pub fn message(&self) -> String {
+        format!(
+            "隔离档位已从 {} 切到 {}：隔离侧 {} 条、共享侧 {} 条，两侧都有内容。\
+             ULL 不会自动搬数据——旧内容仍在原来那一侧，需要的话请手动把 mods/saves/config 挪到新目录。",
+            self.from.as_str(),
+            self.to.as_str(),
+            self.probe.isolated_side,
+            self.probe.shared_side,
+        )
+    }
+}
+
+/// 探测一侧目录的内容条目数（`mods` `saves` `config` 的直接子项合计）。
+///
+/// 目录不存在按 0 计（新实例、纯新的隔离目录都是常态，不是错误）。
+///
+/// # Errors
+///
+/// 目录存在但**读不了**（权限/被占用）时返回 [`GameError::Io`]——这种情况不能当成「空」，
+/// 否则切换检测会给出错误的「那侧没内容」结论。
+pub fn probe_side(path: &Path) -> Result<SideContent, GameError> {
+    let mut entries: u32 = 0;
+    for name in PROBED_CONTENT_DIRS {
+        let dir = path.join(name);
+        let reader = match std::fs::read_dir(&dir) {
+            Ok(reader) => reader,
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => continue,
+            Err(error) => return Err(GameError::io(&dir, error)),
+        };
+        for entry in reader {
+            entry.map_err(|error| GameError::io(&dir, error))?;
+            entries = entries.saturating_add(1);
+        }
+    }
+    Ok(SideContent {
+        path: path.to_path_buf(),
+        entries,
+    })
+}
+
+/// 同时探测隔离侧（`versions/<versionId>/`）与共享侧（游戏根）。
+///
+/// # Errors
+///
+/// 任一侧读不了时返回 [`GameError::Io`]。
+pub fn probe_both_sides(
+    layout: &GameLayout,
+    version_id: &str,
+) -> Result<(SideContent, SideContent), GameError> {
+    Ok((
+        probe_side(&layout.version_dir(version_id))?,
+        probe_side(layout.root())?,
+    ))
+}
+
+/// 启动时刷新切换记录（幂等）：生效档位与记录里的 `to` 不同才记一次。
+///
+/// 返回 `true` 表示 `config` 被改动（调用方负责落盘——本模块不写文件）。
+///
+/// 首次观察（没有记录）会建一条基线：`from == to`，`warned = true`——这样老实例
+/// 升级到 D20 后不会平白弹一次「两侧都有内容」。
+///
+/// # Errors
+///
+/// 探测读盘失败时返回 [`GameError::Io`]。
+pub fn observe_mode(
+    config: &mut InstanceConfig,
+    layout: &GameLayout,
+    at: &str,
+    effective: Isolation,
+) -> Result<bool, GameError> {
+    if config
+        .last_mode_change
+        .as_ref()
+        .is_some_and(|change| change.to == effective)
+    {
+        return Ok(false);
+    }
+    let from = config
+        .last_mode_change
+        .as_ref()
+        .map_or(effective, |change| change.to);
+    let (isolated_side, shared_side) = probe_both_sides(layout, &config.version_id)?;
+    config.last_mode_change = Some(ModeChange {
+        at: at.to_string(),
+        from,
+        to: effective,
+        probe: ModeChangeProbe {
+            isolated_side: isolated_side.entries,
+            shared_side: shared_side.entries,
+        },
+        warned: from == effective,
+    });
+    Ok(true)
+}
diff --git a/crates/core/src/game/java/api.rs b/crates/core/src/game/java/api.rs
new file mode 100644
index 0000000..c04b47e
--- /dev/null
+++ b/crates/core/src/game/java/api.rs
@@ -0,0 +1,344 @@
+//! Adoptium（Eclipse Temurin）版本查询：`api.adoptium.net` → 一个可下载的 JDK 归档。
+//!
+//! 只用 v3 的 `assets/latest/{major}/hotspot` 这一条接口（D13：自动下载只装最新 GA）：
+//!
+//! ```text
+//! GET https://api.adoptium.net/v3/assets/latest/21/hotspot?os=windows&arch=x64&image_type=jdk&vendor=eclipse
+//!     → [ { release_name, version{major,semver}, binary{os,architecture,image_type,package{name,link,checksum,size}} } ]
+//! ```
+//!
+//! 两个实测坑（都在 Windows x64 / Linux x64 上确认过）：
+//!
+//! 1. **`arch` 参数不参与过滤**：`os=windows&arch=x64` 也会把 `aarch64` 的条目一起返回，
+//!    必须自己按 `binary.architecture` 再筛一遍，否则 ARM 包会被当成 x64 装下来；
+//! 2. **`package.link` 是 GitHub release 直链**（`github.com/adoptium/temurin21-binaries/releases/download/…`），
+//!    这正是 [`crate::download::adoptium`] 的镜像展开所认识的形态——所以院校镜像加速
+//!    不需要本模块拼任何 URL。
+
+use serde::Deserialize;
+
+use super::error::{JavaError, JavaErrorKind};
+use super::release::version_from_release_name;
+use super::target::AdoptiumTarget;
+use super::vendor::JdkVendor;
+
+/// Adoptium API 根。
+pub const ADOPTIUM_API_BASE: &str = "https://api.adoptium.net/v3";
+
+/// 托管 JDK 的默认供应商标识（D13 v1 的目录名 `jdk-<major>-vendor` 沿用它）。
+pub const JDK_VENDOR: &str = "temurin";
+
+/// 归档与查询结果的结构定义在 [`super::release`]（四家发行版共用）；这里重导出以保持
+/// `api::JdkRelease` / `api::JdkArchive` 这两个老路径可用。
+pub use super::release::{JdkArchive, JdkRelease};
+
+/// 拼 `latest/{major}` 的查询地址。
+#[must_use]
+pub fn latest_url(major: u32, target: AdoptiumTarget) -> String {
+    format!(
+        "{ADOPTIUM_API_BASE}/assets/latest/{major}/hotspot?os={}&arch={}&image_type=jdk&vendor=eclipse",
+        target.os, target.arch
+    )
+}
+
+/// 解析 `assets/latest` 的响应体，挑出与目标平台匹配的那一条。
+///
+/// # Errors
+///
+/// 响应体不是 JSON、列表为空、没有匹配 `os` + `arch` 的 jdk 条目、sha256 不合法时返回错误。
+pub fn parse_latest(json: &str, target: AdoptiumTarget) -> Result<JdkRelease, JavaError> {
+    let assets: Vec<ApiAsset> = serde_json::from_str(json).map_err(|error| {
+        JavaError::new(
+            JavaErrorKind::Metadata,
+            format!("Adoptium 响应不是预期 JSON：{error}"),
+        )
+    })?;
+    let matched = assets
+        .into_iter()
+        .find(|asset| asset.matches(target))
+        .ok_or_else(|| {
+            JavaError::new(
+                JavaErrorKind::Metadata,
+                format!(
+                    "Adoptium 没有 {}/{} 的 jdk 产物（响应里 {} 条都不匹配）",
+                    target.os, target.arch, "全部"
+                ),
+            )
+            .with_hint("可能该大版本只有别的架构；用 `ull java list` 挑已有 JDK")
+        })?;
+    matched.into_release()
+}
+
+/// 请求一次「某大版本的最新 GA」。
+///
+/// # Errors
+///
+/// 网络不可达、HTTP 非 2xx、响应体不认识、没有对应平台产物时返回错误。
+pub async fn fetch_latest(
+    client: &reqwest::Client,
+    major: u32,
+    target: AdoptiumTarget,
+) -> Result<JdkRelease, JavaError> {
+    let url = latest_url(major, target);
+    let response = client.get(&url).send().await.map_err(|error| {
+        JavaError::new(
+            JavaErrorKind::Network,
+            format!("连不上 Adoptium API：{error}"),
+        )
+        .with_hint("检查网络/代理；已装的 JDK 仍可用 `ull java list` 看到")
+    })?;
+    let status = response.status();
+    if status == reqwest::StatusCode::NOT_FOUND {
+        return Err(JavaError::new(
+            JavaErrorKind::Metadata,
+            format!("Adoptium 没有 {major} 的 GA 产物（HTTP 404）"),
+        )
+        .with_hint("可自动下载的一般是 8 / 11 / 17 / 21 / 25 这类 GA 大版本"));
+    }
+    if !status.is_success() {
+        return Err(JavaError::new(
+            JavaErrorKind::Network,
+            format!("Adoptium API 返回 HTTP {status}（{url}）"),
+        ));
+    }
+    let body = response.text().await.map_err(|error| {
+        JavaError::new(
+            JavaErrorKind::Network,
+            format!("读 Adoptium 响应失败：{error}"),
+        )
+    })?;
+    parse_latest(&body, target)
+}
+
+/// 响应里的 `package` 子对象。
+#[derive(Debug, Deserialize)]
+struct ApiPackage {
+    name: String,
+    link: String,
+    #[serde(default)]
+    checksum: Option<String>,
+    #[serde(default)]
+    size: u64,
+}
+
+/// 响应里的 `binary` 子对象。
+#[derive(Debug, Deserialize)]
+struct ApiBinary {
+    #[serde(default)]
+    os: Option<String>,
+    #[serde(default)]
+    architecture: Option<String>,
+    #[serde(default)]
+    image_type: Option<String>,
+    #[serde(default)]
+    package: Option<ApiPackage>,
+}
+
+/// 响应里的 `version` 子对象。
+#[derive(Debug, Deserialize)]
+struct ApiVersion {
+    #[serde(default)]
+    major: Option<u32>,
+    #[serde(default)]
+    semver: Option<String>,
+}
+
+/// 响应列表里的一条。
+#[derive(Debug, Deserialize)]
+struct ApiAsset {
+    #[serde(default)]
+    release_name: String,
+    #[serde(default)]
+    version: Option<ApiVersion>,
+    #[serde(default)]
+    binary: Option<ApiBinary>,
+}
+
+impl ApiAsset {
+    /// 是否就是目标平台的 jdk 归档（`arch` 参数不过滤，必须自己判）。
+    fn matches(&self, target: AdoptiumTarget) -> bool {
+        let Some(binary) = &self.binary else {
+            return false;
+        };
+        let same_os = binary.os.as_deref().is_some_and(|os| os == target.os);
+        let same_arch = binary
+            .architecture
+            .as_deref()
+            .is_some_and(|arch| arch == target.arch);
+        let is_jdk = binary.image_type.as_deref() != Some("jre");
+        same_os && same_arch && is_jdk && binary.package.is_some()
+    }
+
+    /// 转成对外结果（校验 sha256 形态）。
+    fn into_release(self) -> Result<JdkRelease, JavaError> {
+        let package = self
+            .binary
+            .and_then(|binary| binary.package)
+            .ok_or_else(|| {
+                JavaError::new(JavaErrorKind::Metadata, "Adoptium 条目缺少 package 子对象")
+            })?;
+        let sha256 = package
+            .checksum
+            .as_deref()
+            .map(|hex| hex.trim().to_ascii_lowercase())
+            .filter(|hex| hex.len() == 64 && hex.bytes().all(|byte| byte.is_ascii_hexdigit()))
+            .ok_or_else(|| {
+                JavaError::new(
+                    JavaErrorKind::Integrity,
+                    format!("Adoptium 没给可用的 sha256（{}）", package.name),
+                )
+                .with_hint("换一个大版本，或手动装 JDK 后设 JAVA_HOME")
+            })?;
+        let version = self.version;
+        let major = version
+            .as_ref()
+            .and_then(|version| version.major)
+            .or_else(|| major_from_name(&package.name))
+            .ok_or_else(|| {
+                JavaError::new(
+                    JavaErrorKind::Metadata,
+                    format!("Adoptium 条目里读不出大版本号（{}）", package.name),
+                )
+            })?;
+        let native_version = version_from_release_name(&self.release_name)
+            .or_else(|| version.as_ref().and_then(|version| version.semver.clone()))
+            .unwrap_or_else(|| major.to_string());
+        Ok(JdkRelease {
+            vendor: JdkVendor::Temurin,
+            major,
+            version: native_version,
+            semver: version.and_then(|version| version.semver),
+            release_name: self.release_name,
+            archive: JdkArchive {
+                name: package.name,
+                url: package.link,
+                sha256,
+                size: package.size,
+            },
+        })
+    }
+}
+
+/// 从产物名兜底读大版本（`OpenJDK21U-jdk_x64_windows_hotspot_…` → `21`）。
+fn major_from_name(name: &str) -> Option<u32> {
+    let rest = name.split_once("OpenJDK")?.1;
+    let digits: String = rest.chars().take_while(char::is_ascii_digit).collect();
+    digits.parse().ok()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{latest_url, parse_latest, ApiAsset};
+    use crate::game::java::error::JavaErrorKind;
+    use crate::game::java::target::AdoptiumTarget;
+
+    const WINDOWS: AdoptiumTarget = AdoptiumTarget::new("windows", "x64");
+
+    fn sample() -> String {
+        // 实测：`arch` 参数不过滤，响应里会混进别的架构。
+        r#"[
+          {
+            "release_name": "jdk-21.0.13+9",
+            "version": {"major": 21, "semver": "21.0.13+9.0.LTS"},
+            "binary": {
+              "os": "windows", "architecture": "aarch64", "image_type": "jdk",
+              "package": {
+                "name": "OpenJDK21U-jdk_aarch64_windows_hotspot_21.0.12.1_1.zip",
+                "link": "https://github.com/adoptium/temurin21-binaries/releases/download/jdk-21.0.12.1%2B1/OpenJDK21U-jdk_aarch64_windows_hotspot_21.0.12.1_1.zip",
+                "checksum": "9dcbb8ebe24aa9ee5a47a7fab2106a7c8988d7acee461260fef107411df91dc5",
+                "size": 179666944
+              }
+            }
+          },
+          {
+            "release_name": "jdk-21.0.13+9",
+            "version": {"major": 21, "semver": "21.0.13+9.0.LTS"},
+            "binary": {
+              "os": "windows", "architecture": "x64", "image_type": "jdk",
+              "package": {
+                "name": "OpenJDK21U-jdk_x64_windows_hotspot_21.0.13_9.zip",
+                "link": "https://github.com/adoptium/temurin21-binaries/releases/download/jdk-21.0.13%2B9/OpenJDK21U-jdk_x64_windows_hotspot_21.0.13_9.zip",
+                "checksum": "a4dbaa05fca4bd89d84584e58c459bd732efebb1722af80ab13c6516832004f9",
+                "size": 190000000
+              }
+            }
+          }
+        ]"#
+        .to_string()
+    }
+
+    #[test]
+    fn picks_the_matching_arch_and_keeps_the_github_link() {
+        let release = parse_latest(&sample(), WINDOWS).expect("应解析出 x64 条目");
+        assert_eq!(release.major, 21);
+        assert_eq!(
+            release.vendor,
+            crate::game::java::vendor::JdkVendor::Temurin
+        );
+        assert_eq!(release.version, "21.0.13+9", "版本串取自 release_name");
+        assert_eq!(release.release_name, "jdk-21.0.13+9");
+        assert_eq!(release.semver.as_deref(), Some("21.0.13+9.0.LTS"));
+        assert_eq!(
+            release.archive.name,
+            "OpenJDK21U-jdk_x64_windows_hotspot_21.0.13_9.zip"
+        );
+        assert_eq!(release.archive.size, 190_000_000);
+        assert!(release.archive.url.contains("temurin21-binaries"));
+        assert_eq!(
+            crate::download::adoptium::parse_adoptium_artifact(&release.archive.url)
+                .map(|artifact| (artifact.major, artifact.arch, artifact.os)),
+            Some(("21".to_string(), "x64".to_string(), "windows".to_string()))
+        );
+    }
+
+    #[test]
+    fn missing_arch_is_an_error_not_a_guess() {
+        let error = parse_latest(&sample(), AdoptiumTarget::new("windows", "x86-32"))
+            .expect_err("x86-32 应没有条目");
+        assert_eq!(error.kind(), JavaErrorKind::Metadata);
+    }
+
+    #[test]
+    fn bad_checksum_is_rejected() {
+        let body = sample().replace(
+            "a4dbaa05fca4bd89d84584e58c459bd732efebb1722af80ab13c6516832004f9",
+            "deadbeef",
+        );
+        let error = parse_latest(&body, WINDOWS).expect_err("短 sha256 应被拒");
+        assert_eq!(error.kind(), JavaErrorKind::Integrity);
+    }
+
+    #[test]
+    fn latest_url_carries_os_arch_and_flavor() {
+        let url = latest_url(17, AdoptiumTarget::new("linux", "aarch64"));
+        assert!(url.starts_with("https://api.adoptium.net/v3/assets/latest/17/hotspot?"));
+        assert!(url.contains("os=linux"));
+        assert!(url.contains("arch=aarch64"));
+        assert!(url.contains("image_type=jdk"));
+    }
+
+    #[test]
+    fn non_json_body_is_metadata_error() {
+        let error = parse_latest("<html>502</html>", WINDOWS).expect_err("HTML 应被拒");
+        assert_eq!(error.kind(), JavaErrorKind::Metadata);
+    }
+
+    #[test]
+    fn major_falls_back_to_the_artifact_name() {
+        let body = r#"[{"release_name":"jdk-17.0.13+11",
+            "binary":{"os":"windows","architecture":"x64","image_type":"jdk",
+            "package":{"name":"OpenJDK17U-jdk_x64_windows_hotspot_17.0.13_11.zip",
+            "link":"https://example.invalid/x.zip",
+            "checksum":"a4dbaa05fca4bd89d84584e58c459bd732efebb1722af80ab13c6516832004f9",
+            "size":1}}}]"#;
+        let release = parse_latest(body, WINDOWS).expect("应解析");
+        assert_eq!(release.major, 17);
+        assert_eq!(release.semver, None);
+    }
+
+    #[test]
+    fn asset_without_binary_never_matches() {
+        let asset: ApiAsset = serde_json::from_str(r#"{"release_name":"x"}"#).expect("最小条目");
+        assert!(!asset.matches(WINDOWS));
+    }
+}
diff --git a/crates/core/src/game/java/discover.rs b/crates/core/src/game/java/discover.rs
new file mode 100644
index 0000000..b44a3e5
--- /dev/null
+++ b/crates/core/src/game/java/discover.rs
@@ -0,0 +1,326 @@
+//! 标准安装位置扫描 + 全部发现源的合并去重（`java list` 的「系统发现」半边）。
+//!
+//! 只认 `JAVA_HOME`/`PATH` 会漏掉最常见的一类用户：**用 MSI 装的 Temurin / Microsoft OpenJDK
+//! 不设环境变量**（安装器只登记开始菜单）。HMCL 的 `JavaManager.searchAllJavaInRepository`
+//! 与 PCL 的 `JavaUtils.SearchFolders` 都扫这些位置，本模块照同一思路：
+//!
+//! | 平台 | 扫描位置 |
+//! | --- | --- |
+//! | Windows | `%ProgramFiles%\{Java, Eclipse Adoptium, Microsoft, Zulu, Amazon Corretto, BellSoft, Semeru}\*`（含 `ProgramFiles(x86)` / `ProgramW6432` 变体，WOW64 才看得到 32 位安装）、`%APPDATA%\.minecraft\runtime\*`（**官方启动器装的运行时**，跨产品兼容）、`HKLM\SOFTWARE\JavaSoft\JDK`（老 Oracle 写的，新版发行版通常没有→容错跳过） |
+//! | Linux | `/usr/lib/jvm/*`、`/usr/java/*` |
+//! | macOS | `/Library/Java/JavaVirtualMachines/*.jdk/Contents/Home` |
+//!
+//! 三个纪律：
+//!
+//! 1. **目录不存在是常态**（本机实测 `%APPDATA%\.minecraft\runtime` 与 `JavaSoft\JDK` 都没有），
+//!    一律静默跳过，绝不报错；
+//! 2. **同一路径多来源命中只列一次**，保留优先级高者（`JAVA_HOME` 指向 Program Files 里的
+//!    JDK 时，用户看到的是 `JAVA_HOME` 而不是 `system`）；
+//! 3. **扫描只在需要时才做**：`java list` 全扫；启动路径上先看托管+环境，不满足才扫盘
+//!    （别为了一次启动白跑 N 次 `java -version`）。
+
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+use super::extract::java_binary_name;
+use super::probe::{self, discover_managed_roots, system_candidates, JavaOrigin, JavaRuntime};
+
+/// 全部发现源（托管 → `JAVA_HOME` → `PATH` → 标准安装位置），已按路径去重。
+#[must_use]
+pub fn candidates(managed_root: &Path) -> Vec<JavaRuntime> {
+    candidates_in_roots(std::slice::from_ref(&managed_root.to_path_buf()))
+}
+
+/// 同上，但托管区可以是**多个安装根**（Portable 数据根 + Standard/Custom 落点，D23）。
+#[must_use]
+pub fn candidates_in_roots(managed_roots: &[PathBuf]) -> Vec<JavaRuntime> {
+    let mut all = discover_managed_roots(managed_roots);
+    all.extend(system_candidates());
+    all.extend(standard_candidates());
+    dedupe(all)
+}
+
+/// 标准安装位置扫出来的运行时（逐个探测）。
+#[must_use]
+pub fn standard_candidates() -> Vec<JavaRuntime> {
+    scan_java_binaries()
+        .into_iter()
+        .map(|binary| probe::probe(&binary, JavaOrigin::System))
+        .collect()
+}
+
+/// 扫描标准安装位置，返回 `bin/java[.exe]` 路径表（稳定排序，未探测）。
+#[must_use]
+pub fn scan_java_binaries() -> Vec<PathBuf> {
+    let mut found: Vec<PathBuf> = Vec::new();
+    for root in standard_roots() {
+        let binary = root.join("bin").join(java_binary_name());
+        if binary.is_file() {
+            found.push(binary);
+        }
+    }
+    for home in registry_homes() {
+        let binary = home.join("bin").join(java_binary_name());
+        if binary.is_file() {
+            found.push(binary);
+        }
+    }
+    found.sort();
+    found.dedup();
+    found
+}
+
+/// 候选 JDK 根目录（`bin/java` 的父目录的父目录）。
+#[must_use]
+pub fn standard_roots() -> Vec<PathBuf> {
+    let mut roots = Vec::new();
+    if cfg!(windows) {
+        for variable in ["ProgramW6432", "ProgramFiles", "ProgramFiles(x86)"] {
+            let Some(base) = std::env::var_os(variable) else {
+                continue;
+            };
+            let base = PathBuf::from(base);
+            for vendor in WINDOWS_VENDOR_DIRS {
+                roots.extend(child_dirs(&base.join(vendor)));
+            }
+        }
+        if let Some(appdata) = std::env::var_os("APPDATA") {
+            roots.extend(child_dirs(
+                &PathBuf::from(appdata).join(".minecraft").join("runtime"),
+            ));
+        }
+    } else if cfg!(target_os = "macos") {
+        for entry in child_dirs(Path::new("/Library/Java/JavaVirtualMachines")) {
+            // `*.jdk/Contents/Home`（`java_home` 语义）。
+            let home = entry.join("Contents").join("Home");
+            roots.push(if home.is_dir() { home } else { entry });
+        }
+    } else {
+        for base in ["/usr/lib/jvm", "/usr/java"] {
+            roots.extend(child_dirs(Path::new(base)));
+        }
+    }
+    roots.sort();
+    roots.dedup();
+    roots
+}
+
+/// Windows 各发行版的安装父目录（每种下面按子目录名当版本）。
+const WINDOWS_VENDOR_DIRS: &[&str] = &[
+    "Java",
+    "Eclipse Adoptium",
+    "Microsoft",
+    "Zulu",
+    "Amazon Corretto",
+    "BellSoft",
+    "Semeru",
+];
+
+/// 列一个目录的直接子目录（不存在/无权限一律空）。
+fn child_dirs(dir: &Path) -> Vec<PathBuf> {
+    let Ok(entries) = std::fs::read_dir(dir) else {
+        return Vec::new();
+    };
+    entries
+        .flatten()
+        .filter(|entry| entry.file_type().is_ok_and(|kind| kind.is_dir()))
+        .map(|entry| entry.path())
+        .collect()
+}
+
+/// 注册表里登记的 `JavaHome`（只查老 Oracle 的 `JavaSoft\JDK`；查不到返回空）。
+///
+/// 不走额外依赖：`reg.exe` 在 Win10+ 恒定存在，输出格式也稳定
+/// （`    JavaHome    REG_SZ    C:\Program Files\Java\jdk-17`）。
+#[must_use]
+pub fn registry_homes() -> Vec<PathBuf> {
+    if !cfg!(windows) {
+        return Vec::new();
+    }
+    let mut homes = Vec::new();
+    for view in ["64", "32"] {
+        let Ok(output) = Command::new("reg")
+            .args(["query", "HKLM\\SOFTWARE\\JavaSoft\\JDK", "/s", "/reg:"])
+            .arg(view)
+            .output()
+        else {
+            continue;
+        };
+        if !output.status.success() {
+            continue;
+        }
+        homes.extend(parse_java_home(&String::from_utf8_lossy(&output.stdout)));
+    }
+    homes.sort();
+    homes.dedup();
+    homes
+}
+
+/// 从 `reg query /s` 的输出里抠出 `JavaHome` 的值（纯函数，便于用真实输出做单测）。
+#[must_use]
+pub fn parse_java_home(output: &str) -> Vec<PathBuf> {
+    output
+        .lines()
+        .filter_map(|line| {
+            let rest = line.trim().strip_prefix("JavaHome")?;
+            let (_, value) = rest.split_once("REG_SZ")?;
+            let home = value.trim();
+            (!home.is_empty()).then(|| PathBuf::from(home))
+        })
+        .collect()
+}
+
+/// 按路径去重，保留**先出现**的那个（调用方按优先级排好序）。
+#[must_use]
+pub fn dedupe(runtimes: Vec<JavaRuntime>) -> Vec<JavaRuntime> {
+    let mut seen: Vec<String> = Vec::with_capacity(runtimes.len());
+    let mut kept = Vec::with_capacity(runtimes.len());
+    for runtime in runtimes {
+        let key = path_key(&runtime.binary);
+        if seen.contains(&key) {
+            continue;
+        }
+        seen.push(key);
+        kept.push(runtime);
+    }
+    kept
+}
+
+/// 去重键：剥掉 Windows 的 `\\?\` 前缀、分隔符一律折成 `/`、大小写只在 Windows 折叠。
+///
+/// 前两步与平台无关：同一条 `bin/java[.exe]` 用 `/` 还是 `\` 拼出来都是同一个文件，
+/// 键必须相同——`JAVA_HOME` 的写法与扫盘拼出来的路径常在这点上不一致，键不齐就重复列。
+/// 大小写折叠**只能**跟着平台走：NTFS 不区分大小写，而 POSIX 上 `Java` 与 `java` 是两个
+/// 目录，折了会把两份真实安装误并成一个。
+///
+/// 代价（已知且有意的取舍）：POSIX 上文件名里的字面反斜杠也会被当分隔符。JDK 安装路径带
+/// 反斜杠属于病态情况，换来的是「同一条 java 的两种拼法永远同键」这条平台无关的不变量。
+#[must_use]
+pub fn path_key(path: &Path) -> String {
+    let text = path.display().to_string();
+    let text = text
+        .strip_prefix(r"\\?\")
+        .unwrap_or(&text)
+        .replace('\\', "/");
+    if cfg!(windows) {
+        text.to_ascii_lowercase()
+    } else {
+        text
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{dedupe, parse_java_home, path_key, standard_roots};
+    use crate::game::java::probe::{JavaOrigin, JavaRuntime};
+
+    fn runtime(path: &str, origin: JavaOrigin) -> JavaRuntime {
+        JavaRuntime {
+            binary: std::path::PathBuf::from(path),
+            origin,
+            version: None,
+            major: Some(21),
+            bits: 64,
+            vendor: None,
+        }
+    }
+
+    #[test]
+    fn dedupe_keeps_the_higher_priority_source() {
+        let list = vec![
+            runtime(
+                "C:/Program Files/Java/jdk-21/bin/java.exe",
+                JavaOrigin::JavaHome,
+            ),
+            runtime(
+                "C:\\Program Files\\Java\\jdk-21\\bin\\java.exe",
+                JavaOrigin::System,
+            ),
+            runtime(
+                "C:/Program Files/Zulu/zulu-17/bin/java.exe",
+                JavaOrigin::System,
+            ),
+        ];
+        let kept = dedupe(list);
+        assert_eq!(kept.len(), 2);
+        assert_eq!(kept[0].origin, JavaOrigin::JavaHome, "重复路径保留高优先级");
+    }
+
+    #[test]
+    fn path_key_normalises_separators_on_every_platform() {
+        // 平台无关的不变量：同一条 `bin/java` 用 `/` 还是 `\` 拼出来，键必须相同。
+        // （M49：原来这里只在 Windows 上成立，Linux 上 `\` 原样留着 → 断言挂。）
+        let forward = path_key(std::path::Path::new("C:/a/b/java.exe"));
+        let backward = path_key(std::path::Path::new("C:\\a\\b\\java.exe"));
+        assert_eq!(forward, backward);
+        assert!(
+            !forward.contains('\\'),
+            "键里不该残留反斜杠（与平台无关）：{forward}"
+        );
+        assert!(
+            !forward.starts_with(r"\\"),
+            "`\\\\?\\` 前缀不进键：{forward}"
+        );
+    }
+
+    #[test]
+    fn one_install_normalises_to_one_key_whatever_the_spelling() {
+        // 回归钉子：`JAVA_HOME` 与扫盘常对同一个 java 给出不同写法，四种拼法必须同键。
+        let spellings = [
+            "C:/Program Files/Java/jdk-21/bin/java.exe",
+            r"C:\Program Files\Java\jdk-21\bin\java.exe",
+            r"\\?\C:\Program Files\Java\jdk-21\bin\java.exe",
+            r"C:\Program Files\Java\jdk-21/bin/java.exe",
+        ];
+        let key = path_key(std::path::Path::new(spellings[0]));
+        for spelling in spellings {
+            assert_eq!(
+                path_key(std::path::Path::new(spelling)),
+                key,
+                "同一安装的两种写法必须同键：{spelling}"
+            );
+        }
+    }
+
+    #[test]
+    fn path_key_folds_case_only_where_the_filesystem_does() {
+        // 大小写折叠跟平台走，两侧都钉住：NTFS 不区分大小写 → 折；
+        // POSIX 上 `Java` 与 `java` 是两个目录 → 不折（折了会把两份真实安装误并）。
+        let upper = path_key(std::path::Path::new(
+            "C:/Program Files/Java/jdk-21/bin/java.exe",
+        ));
+        let lower = path_key(std::path::Path::new(
+            "c:/program files/java/jdk-21/bin/java.exe",
+        ));
+        if cfg!(windows) {
+            assert_eq!(upper, lower, "Windows：大小写不同的同一路径应同键");
+        } else {
+            assert_ne!(upper, lower, "POSIX：大小写是有效区别，不应同键");
+        }
+    }
+
+    #[test]
+    fn parses_real_reg_query_output() {
+        // 实测形态（`reg query HKLM\SOFTWARE\JavaSoft\JDK /s`）。
+        let output = "\r\nHKEY_LOCAL_MACHINE\\SOFTWARE\\JavaSoft\\JDK\r\n    CurrentVersion    REG_SZ    1.8\r\n\r\nHKEY_LOCAL_MACHINE\\SOFTWARE\\JavaSoft\\JDK\\1.8\r\n    JavaHome    REG_SZ    C:\\Program Files\\Java\\jdk1.8.0_402\r\n";
+        let homes = parse_java_home(output);
+        assert_eq!(
+            homes,
+            vec![std::path::PathBuf::from(
+                r"C:\Program Files\Java\jdk1.8.0_402"
+            )]
+        );
+    }
+
+    #[test]
+    fn missing_registry_key_is_not_an_error() {
+        assert!(parse_java_home("错误: 系统找不到指定的注册表项或值。\r\n").is_empty());
+    }
+
+    #[test]
+    fn standard_roots_never_panic_on_missing_directories() {
+        // 本机大概率缺若干目录；这里只要求「能跑、不 panic」。
+        let roots = standard_roots();
+        assert!(roots.iter().all(|root| !root.as_os_str().is_empty()));
+    }
+}
diff --git a/crates/core/src/game/java/error.rs b/crates/core/src/game/java/error.rs
new file mode 100644
index 0000000..0cdc3d5
--- /dev/null
+++ b/crates/core/src/game/java/error.rs
@@ -0,0 +1,138 @@
+//! Java 管理模块的错误形状：稳定分类 + 人读说明 + 下一步提示。
+//!
+//! 与 `core::game::install::InstallError` 同一个套路（分类进 `--json` 的 `error.code`，
+//! 说明给人看，提示告诉用户下一步做什么），只是没有复用那个类型——安装层的错误语义
+//! 绑在版本本体上，JDK 下载的失败面（API 不可达 / 无对应产物 / 解压后跑不起来）不一样。
+
+use std::fmt;
+
+use crate::download::{DownloadError, DownloadErrorKind};
+
+/// 失败大类（CLI 映射成稳定错误码，脚本可分流）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum JavaErrorKind {
+    /// 网络侧：Adoptium API 不可达，或所有候选镜像源都失败。
+    Network,
+    /// 元数据不认识：API 返回体缺字段、空列表、要的大版本没有 GA 产物。
+    Metadata,
+    /// 摘要校验不符（镜像给了错内容）或 API 没给可用的 sha256。
+    Integrity,
+    /// 本地 IO：建目录 / 解压 / 落盘。
+    Io,
+    /// 当前平台没有对应的 Temurin 产物（架构不认识等）。
+    Unsupported,
+    /// 装完探测不到可用 java（解压成功但跑不起来 / 版本不符）。
+    Probe,
+}
+
+impl JavaErrorKind {
+    /// 稳定字符串 id（进 `--json` 的 `error.code`）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Network => "java_network",
+            Self::Metadata => "java_metadata",
+            Self::Integrity => "java_integrity",
+            Self::Io => "java_io",
+            Self::Unsupported => "java_unsupported",
+            Self::Probe => "java_probe",
+        }
+    }
+}
+
+/// Java 管理期错误。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct JavaError {
+    kind: JavaErrorKind,
+    message: String,
+    hint: Option<String>,
+}
+
+impl JavaError {
+    /// 构造。
+    #[must_use]
+    pub fn new(kind: JavaErrorKind, message: impl Into<String>) -> Self {
+        Self {
+            kind,
+            message: message.into(),
+            hint: None,
+        }
+    }
+
+    /// 补一句「下一步怎么办」。
+    #[must_use]
+    pub fn with_hint(mut self, hint: impl Into<String>) -> Self {
+        self.hint = Some(hint.into());
+        self
+    }
+
+    /// 分类。
+    #[must_use]
+    pub const fn kind(&self) -> JavaErrorKind {
+        self.kind
+    }
+
+    /// 稳定错误码。
+    #[must_use]
+    pub const fn code(&self) -> &'static str {
+        self.kind.as_str()
+    }
+
+    /// 人读说明。
+    #[must_use]
+    pub fn message(&self) -> &str {
+        &self.message
+    }
+
+    /// 下一步提示。
+    #[must_use]
+    pub fn hint(&self) -> Option<&str> {
+        self.hint.as_deref()
+    }
+
+    /// 在说明前面加一段上下文（保留分类与提示）。
+    #[must_use]
+    pub fn with_context(mut self, context: impl fmt::Display) -> Self {
+        self.message = format!("{context}：{}", self.message);
+        self
+    }
+}
+
+impl fmt::Display for JavaError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str(&self.message)
+    }
+}
+
+impl std::error::Error for JavaError {}
+
+impl From<DownloadError> for JavaError {
+    fn from(error: DownloadError) -> Self {
+        let kind = match error.kind {
+            DownloadErrorKind::Integrity => JavaErrorKind::Integrity,
+            DownloadErrorKind::Io => JavaErrorKind::Io,
+            DownloadErrorKind::InvalidRequest => JavaErrorKind::Metadata,
+            DownloadErrorKind::NotFound
+            | DownloadErrorKind::ServerError
+            | DownloadErrorKind::Timeout
+            | DownloadErrorKind::Network
+            | DownloadErrorKind::RangeUnsupported
+            | DownloadErrorKind::AllSourcesFailed => JavaErrorKind::Network,
+        };
+        let mut message = error.message.clone();
+        if let Some(source) = &error.source {
+            message.push_str(&format!("（源 {source}）"));
+        }
+        // 逐源失败摘要：没有这一段，「全部失败」在现场只能靠复现去猜（本轮真机验收就踩到了）。
+        if !error.suppressed.is_empty() {
+            message.push_str(&format!("；逐源明细：{}", error.suppressed.join(" / ")));
+        }
+        Self::new(kind, message)
+    }
+}
+
+/// IO 错误包装（带上「在做什么 / 哪个路径」，日志里才追得动）。
+#[must_use]
+pub fn io_error(op: &'static str, path: impl fmt::Display, source: &std::io::Error) -> JavaError {
+    JavaError::new(JavaErrorKind::Io, format!("{op} 失败（{path}）：{source}"))
+}
diff --git a/crates/core/src/game/java/extract.rs b/crates/core/src/game/java/extract.rs
new file mode 100644
index 0000000..44b392f
--- /dev/null
+++ b/crates/core/src/game/java/extract.rs
@@ -0,0 +1,318 @@
+//! 归档解压：zip（Windows）/ tar.gz（Linux、macOS 的 Temurin 只发这种）+ 幂等戳记。
+//!
+//! # 为什么不用「解压到最终目录」了事
+//!
+//! Temurin 的归档里所有条目都在一个顶层目录下（`jdk-21.0.13+9/bin/java`），
+//! 而托管布局要的是 `java-managed/jdk-21-temurin/bin/java`。裸解压会多出一层，
+//! 于是这里先在**暂存目录**里解完，再把那个唯一的顶层目录（或暂存目录本身）
+//! 提升成最终目录——这样终态恒定，`bin/java` 的位置不会因为厂商换打包方式而漂移。
+//!
+//! # 幂等
+//!
+//! 戳记 `.ull-jdk.json` 记下「这份目录是用哪个 sha256 的归档解出来的 + 文件数」。
+//! 重复 `ull java install 21` 时 sha256 相同就**一个字节都不动**（返回 `skipped`）；
+//! 官方发了新版（sha256 变）才重解。戳记缺失/损坏一律当「没装过」。
+//!
+//! # 安全
+//!
+//! zip 走 `enclosed_name()`（拒绝 `..` 与绝对路径），tar 走 `unpack_in()`
+//! （同样拒绝越界），两者都不会把文件写到目标目录之外（zip-slip）。
+//! tar 里的符号链接条目跳过（Windows 建不了；Temurin 的 JDK 归档不依赖它们）。
+
+use std::fs::{self, File};
+use std::io;
+use std::path::{Path, PathBuf};
+
+use flate2::read::GzDecoder;
+use serde::{Deserialize, Serialize};
+use zip::ZipArchive;
+
+use super::error::{io_error, JavaError, JavaErrorKind};
+
+/// 戳记文件名（放在托管 JDK 根目录里）。
+pub const STAMP_FILE: &str = ".ull-jdk.json";
+
+/// 戳记 schema 版本（改字段语义才升）。
+const STAMP_VERSION: u8 = 1;
+
+/// 暂存目录前缀（解压在它里面进行，成功后提升成最终目录）。
+const STAGING_PREFIX: &str = ".staging-";
+
+/// 托管 JDK 的戳记。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct JdkStamp {
+    /// schema 版本。
+    pub v: u8,
+    /// 归档文件名。
+    pub archive: String,
+    /// 归档的 SHA-256（幂等判据）。
+    pub sha256: String,
+    /// 大版本号。
+    pub major: u32,
+    /// 解出来的文件数。
+    pub files: usize,
+}
+
+/// 一次解压的结果。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ExtractReport {
+    /// 本次落盘的文件数（`skipped` 时为 0）。
+    pub files: usize,
+    /// 是否因为戳记命中而整体跳过。
+    pub skipped: bool,
+}
+
+impl ExtractReport {
+    /// 是否真的写盘了。
+    #[must_use]
+    pub const fn wrote(self) -> bool {
+        !self.skipped
+    }
+}
+
+/// 托管 JDK 的 `java` 可执行文件路径。
+#[must_use]
+pub fn java_binary(dir: &Path) -> PathBuf {
+    dir.join("bin").join(java_binary_name())
+}
+
+/// 平台上的 java 可执行文件名。
+#[must_use]
+pub const fn java_binary_name() -> &'static str {
+    if cfg!(windows) {
+        "java.exe"
+    } else {
+        "java"
+    }
+}
+
+/// 读戳记（不存在 / 损坏 / 版本不符都当作「没有」）。
+#[must_use]
+pub fn read_stamp(dir: &Path) -> Option<JdkStamp> {
+    let text = fs::read_to_string(dir.join(STAMP_FILE)).ok()?;
+    let stamp: JdkStamp = serde_json::from_str(&text).ok()?;
+    (stamp.v == STAMP_VERSION).then_some(stamp)
+}
+
+/// 这个目录里是不是已经躺着一份用**同一个归档**解出来的 JDK。
+#[must_use]
+pub fn is_ready(dir: &Path, sha256: &str) -> bool {
+    let Some(stamp) = read_stamp(dir) else {
+        return false;
+    };
+    stamp.sha256 == sha256.to_ascii_lowercase() && java_binary(dir).is_file()
+}
+
+/// 解压一个 JDK 归档到 `dest`（幂等）。
+///
+/// # Errors
+///
+/// 归档打不开/格式不认识、解压写盘失败、`dest` 已存在却不由我们管理
+/// （没有戳记）时返回错误。
+pub fn extract_archive(
+    archive: &Path,
+    sha256: &str,
+    major: u32,
+    dest: &Path,
+) -> Result<ExtractReport, JavaError> {
+    if is_ready(dest, sha256) {
+        return Ok(ExtractReport {
+            files: 0,
+            skipped: true,
+        });
+    }
+    let parent = dest.parent().ok_or_else(|| {
+        JavaError::new(
+            JavaErrorKind::Io,
+            format!("托管目录没有父目录：{}", dest.display()),
+        )
+    })?;
+    fs::create_dir_all(parent)
+        .map_err(|error| io_error("创建托管目录", parent.display(), &error))?;
+
+    let folder = dest
+        .file_name()
+        .map(|name| name.to_string_lossy().into_owned())
+        .unwrap_or_else(|| "jdk".to_string());
+    let staging = parent.join(format!("{STAGING_PREFIX}{folder}"));
+    if staging.exists() {
+        fs::remove_dir_all(&staging)
+            .map_err(|error| io_error("清理暂存目录", staging.display(), &error))?;
+    }
+    fs::create_dir_all(&staging)
+        .map_err(|error| io_error("创建暂存目录", staging.display(), &error))?;
+
+    let extracted = if is_zip(archive) {
+        extract_zip(archive, &staging)
+    } else {
+        extract_tar_gz(archive, &staging)
+    };
+    let files = match extracted {
+        Ok(files) => files,
+        Err(error) => {
+            let _ = fs::remove_dir_all(&staging);
+            return Err(error);
+        }
+    };
+
+    let root = single_top_level_dir(&staging).unwrap_or_else(|| staging.clone());
+    if dest.exists() {
+        // 只回收「我们自己装的」目录：有戳记，或空目录。其余一律不碰。
+        let ours = read_stamp(dest).is_some() || is_empty_dir(dest);
+        if !ours {
+            let _ = fs::remove_dir_all(&staging);
+            return Err(JavaError::new(
+                JavaErrorKind::Io,
+                format!("目标目录已存在且不是托管 JDK：{}", dest.display()),
+            )
+            .with_hint("换个目录（`--data-dir`），或先手动清掉它"));
+        }
+        fs::remove_dir_all(dest)
+            .map_err(|error| io_error("清空旧托管目录", dest.display(), &error))?;
+    }
+    fs::rename(&root, dest).map_err(|error| {
+        io_error(
+            "提升暂存目录",
+            format!("{} → {}", root.display(), dest.display()),
+            &error,
+        )
+    })?;
+    if root != staging {
+        let _ = fs::remove_dir_all(&staging);
+    }
+    if !java_binary(dest).is_file() {
+        return Err(JavaError::new(
+            JavaErrorKind::Probe,
+            format!("解压完成但找不到 bin/{}", java_binary_name()),
+        )
+        .with_hint("归档形态与平台不匹配（例如把 Linux 包当成 Windows 包装）"));
+    }
+
+    let stamp = JdkStamp {
+        v: STAMP_VERSION,
+        archive: archive
+            .file_name()
+            .map(|name| name.to_string_lossy().into_owned())
+            .unwrap_or_default(),
+        sha256: sha256.to_ascii_lowercase(),
+        major,
+        files,
+    };
+    let text = serde_json::to_string_pretty(&stamp).map_err(|error| {
+        JavaError::new(
+            JavaErrorKind::Metadata,
+            format!("序列化 JDK 戳记失败：{error}"),
+        )
+    })?;
+    let stamp_path = dest.join(STAMP_FILE);
+    fs::write(&stamp_path, text)
+        .map_err(|error| io_error("写 JDK 戳记", stamp_path.display(), &error))?;
+    Ok(ExtractReport {
+        files,
+        skipped: false,
+    })
+}
+
+/// 归档是不是 zip（魔数优先，读不到才退回扩展名）。
+///
+/// 不按扩展名一刀切：镜像把 `.zip` 存成 `.zip.tmp` 之类时魔数仍然可靠，
+/// 反过来把 tar.gz 命名成 `.zip` 也不会被错解。
+#[must_use]
+pub fn is_zip(archive: &Path) -> bool {
+    let mut head = [0u8; 4];
+    let magic = File::open(archive)
+        .and_then(|mut file| io::Read::read_exact(&mut file, &mut head).map(|()| head));
+    if let Ok(head) = magic {
+        // `PK\x03\x04` 普通条目 / `PK\x05\x06` 空归档。
+        return head == *b"PK\x03\x04" || head == *b"PK\x05\x06";
+    }
+    archive
+        .file_name()
+        .map(|name| name.to_string_lossy().to_ascii_lowercase())
+        .is_some_and(|name| name.ends_with(".zip"))
+}
+
+/// zip：逐条目落盘，`enclosed_name` 挡路径穿越。
+fn extract_zip(archive: &Path, dir: &Path) -> Result<usize, JavaError> {
+    let file = File::open(archive)
+        .map_err(|error| io_error("打开 JDK 归档", archive.display(), &error))?;
+    let mut zip = ZipArchive::new(file).map_err(|error| {
+        JavaError::new(
+            JavaErrorKind::Io,
+            format!("JDK 归档不是合法 zip（{}）：{error}", archive.display()),
+        )
+    })?;
+    let mut files = 0;
+    for index in 0..zip.len() {
+        let mut entry = zip.by_index(index).map_err(|error| {
+            JavaError::new(
+                JavaErrorKind::Io,
+                format!("读 zip 条目失败（{}）：{error}", archive.display()),
+            )
+        })?;
+        if entry.is_dir() {
+            continue;
+        }
+        let Some(relative) = entry.enclosed_name() else {
+            continue;
+        };
+        let dest = dir.join(&relative);
+        if let Some(parent) = dest.parent() {
+            fs::create_dir_all(parent)
+                .map_err(|error| io_error("创建解压子目录", parent.display(), &error))?;
+        }
+        let mut out = File::create(&dest)
+            .map_err(|error| io_error("创建解压文件", dest.display(), &error))?;
+        io::copy(&mut entry, &mut out)
+            .map_err(|error| io_error("写解压文件", dest.display(), &error))?;
+        files += 1;
+    }
+    Ok(files)
+}
+
+/// tar.gz：`unpack_in` 挡路径穿越，符号链接条目跳过。
+fn extract_tar_gz(archive: &Path, dir: &Path) -> Result<usize, JavaError> {
+    let file = File::open(archive)
+        .map_err(|error| io_error("打开 JDK 归档", archive.display(), &error))?;
+    let mut tar = tar::Archive::new(GzDecoder::new(file));
+    let entries = tar.entries().map_err(|error| {
+        JavaError::new(
+            JavaErrorKind::Io,
+            format!("JDK 归档不是合法 tar.gz（{}）：{error}", archive.display()),
+        )
+    })?;
+    let mut files = 0;
+    for entry in entries {
+        let mut entry = entry.map_err(|error| {
+            JavaError::new(
+                JavaErrorKind::Io,
+                format!("读 tar 条目失败（{}）：{error}", archive.display()),
+            )
+        })?;
+        if !entry.header().entry_type().is_file() {
+            continue;
+        }
+        let unpacked = entry
+            .unpack_in(dir)
+            .map_err(|error| io_error("解压 tar 条目", dir.display(), &error))?;
+        if unpacked {
+            files += 1;
+        }
+    }
+    Ok(files)
+}
+
+/// 暂存目录里是不是只有一个顶层目录（Temurin 的 `jdk-21.0.13+9/`）。
+fn single_top_level_dir(dir: &Path) -> Option<PathBuf> {
+    let mut entries = fs::read_dir(dir).ok()?;
+    let first = entries.next()?.ok()?;
+    if entries.next().is_some() {
+        return None;
+    }
+    let path = first.path();
+    path.is_dir().then_some(path)
+}
+
+fn is_empty_dir(dir: &Path) -> bool {
+    fs::read_dir(dir).is_ok_and(|mut entries| entries.next().is_none())
+}
diff --git a/crates/core/src/game/java/install.rs b/crates/core/src/game/java/install.rs
new file mode 100644
index 0000000..654dbc6
--- /dev/null
+++ b/crates/core/src/game/java/install.rs
@@ -0,0 +1,379 @@
+//! 托管 JDK 安装编排：发行版回退链 → 下载引擎 → 解压 → `java -version` 验证。
+//!
+//! ```text
+//! vendor::order(用户优先级, 地区)                  D23 的尝试顺序
+//!   → source::fetch(vendor, major)                查到该家最新 GA（Temurin/Oracle/MS/Zulu）
+//!   → location::JavaInstallRoot::jdk_dir          按落点模式算目录
+//!   → [戳记 sha256 相同 && bin/java 在] 复用      幂等的第一层
+//!   → engine.download(JavaRuntime 请求)           镜像/健康度/退避/续传/边下边算全在引擎
+//!   → extract::extract_archive                    zip / tar.gz + 幂等戳记
+//!   → probe::probe(bin/java -version)             幂等的第二层，也是「装完真能用」的证据
+//! ```
+//!
+//! **回退的粒度是发行版**（D23）：该家没有这个大版本、镜像全 4xx、sha256 取不到、下载校验失败，
+//! 都记一条降级原因然后换下一家；只有全部失败才整体报错，错误里带上每一跳的原因。
+//!
+//! 这一步**不拼任何镜像 URL**（Oracle 的哈希段不可推导，见 `oracle` 模块）：Temurin 的
+//! GitHub 直链交给 `MirrorTable::expand` 展开成院校镜像，Oracle/MS/Zulu 的链接由各自模块
+//! 从目录页/模板/API 拿到最终形态，引擎只负责「把这个 URL 下下来并校验」。
+
+use std::path::{Path, PathBuf};
+
+use super::error::{io_error, JavaError, JavaErrorKind};
+use super::extract;
+use super::location::{JavaInstallRoot, LocationMode};
+use super::probe::{self, JavaOrigin, JavaRuntime};
+use super::release::JdkRelease;
+use super::source::{self, ChainLog};
+use super::target::AdoptiumTarget;
+use super::vendor::{self, JdkVendor};
+use crate::download::{DownloadEngine, DownloadRequest, ResourceKind};
+
+/// 归档缓存目录名（在安装根下；托管目录扫描跳过它）。
+pub use super::location::CACHE_DIR;
+
+/// 一次安装请求。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct InstallRequest {
+    /// 目标大版本。
+    pub major: u32,
+    /// 钉死某一家发行版（`--vendor`）；`None` = 按回退链自己选。
+    pub vendor: Option<JdkVendor>,
+    /// 用户优先级（`java.vendorPriority`，空 = 按地区默认序）。
+    pub priority: Vec<JdkVendor>,
+}
+
+impl InstallRequest {
+    /// 只要大版本（走回退链，优先级用地区默认）。
+    #[must_use]
+    pub const fn new(major: u32) -> Self {
+        Self {
+            major,
+            vendor: None,
+            priority: Vec::new(),
+        }
+    }
+
+    /// 钉死发行版。
+    #[must_use]
+    pub const fn with_vendor(major: u32, vendor: JdkVendor) -> Self {
+        Self {
+            major,
+            vendor: Some(vendor),
+            priority: Vec::new(),
+        }
+    }
+
+    /// 带上用户优先级（只影响没有 `--vendor` 的情形）。
+    #[must_use]
+    pub fn with_priority(mut self, priority: Vec<JdkVendor>) -> Self {
+        self.priority = priority;
+        self
+    }
+
+    /// 实际尝试顺序（`--vendor` 钉死时链里只放它）。
+    #[must_use]
+    pub fn order(&self, domestic: bool) -> Vec<JdkVendor> {
+        match self.vendor {
+            Some(vendor) => vec![vendor],
+            None => vendor::order(&self.priority, domestic),
+        }
+    }
+}
+
+/// 会真正进入回退链的发行版（顺序 + 能力过滤）。
+///
+/// 与 [`install`] 的循环同源，但**纯**：不联网、不落盘，给 `--dry-run` 与离线测试用。
+/// 过滤条件只有一条——该家发不发这个 GA 大版本（MS 没有 8、Oracle 从 9 起）。
+/// `--vendor` 钉死时**不过滤**：链里就它一个，由 `install` 明确报「不支持 Java X」，
+/// 而不是悄悄把用户点名的发行版换成别的。
+#[must_use]
+pub fn chain_order(request: &InstallRequest, domestic: bool) -> Vec<JdkVendor> {
+    if request.vendor.is_some() {
+        return request.order(domestic);
+    }
+    request
+        .order(domestic)
+        .into_iter()
+        .filter(|vendor| vendor.supports(request.major))
+        .collect()
+}
+
+/// 一次成功安装的结果。
+#[derive(Debug, Clone)]
+pub struct InstalledJdk {
+    /// 大版本号。
+    pub major: u32,
+    /// 实际装上的发行版。
+    pub vendor: JdkVendor,
+    /// 版本查询结果（含归档名与 sha256）。
+    pub release: JdkRelease,
+    /// 托管目录（Portable：`java-managed/jdk-21-temurin`；Standard：`Java/oracle/21.0.2`）。
+    pub root: PathBuf,
+    /// 落点模式（报告里要说清「装到哪」）。
+    pub mode: LocationMode,
+    /// 归档路径（缓存）。
+    pub archive: PathBuf,
+    /// 探测到的运行时。
+    pub runtime: JavaRuntime,
+    /// 实际下载的源标识（`None` = 复用已装，没走网络）。
+    pub downloaded: Option<String>,
+    /// 本次下载字节数（复用已装时为 0）。
+    pub bytes: u64,
+    /// 本次解压的文件数（复用已装时可能为 0）。
+    pub files: usize,
+    /// 本次是否真的解压了。
+    pub extracted: bool,
+    /// 回退链记录（命中与降级原因）。
+    pub chain: ChainLog,
+}
+
+impl InstalledJdk {
+    /// 是否完全复用了已装的那一份。
+    #[must_use]
+    pub fn reused(&self) -> bool {
+        self.downloaded.is_none()
+    }
+
+    /// `bin/java[.exe]` 路径。
+    #[must_use]
+    pub fn binary(&self) -> PathBuf {
+        extract::java_binary(&self.root)
+    }
+
+    /// 实际落点（人读一行）。
+    #[must_use]
+    pub fn location_line(&self) -> String {
+        format!("{} · {}", self.mode.as_str(), self.root.display())
+    }
+}
+
+/// 托管目录路径（Portable 布局 `java-managed/jdk-<major>-<vendor>`）。
+#[must_use]
+pub fn managed_root_dir(managed_root: &Path, major: u32, vendor: &str) -> PathBuf {
+    managed_root.join(probe::managed_dir_name(major, vendor))
+}
+
+/// 归档缓存路径（`<root>/.cache/<归档名>`）。
+#[must_use]
+pub fn archive_path(root: &Path, release: &JdkRelease) -> PathBuf {
+    root.join(CACHE_DIR).join(&release.archive.name)
+}
+
+/// 归档下载请求（`ResourceKind::JavaRuntime` + sha256 + 期望大小）。
+#[must_use]
+pub fn archive_request(release: &JdkRelease, dest: PathBuf) -> DownloadRequest {
+    let request =
+        DownloadRequest::new(ResourceKind::JavaRuntime, release.archive.url.clone(), dest)
+            .with_sha256(release.archive.sha256.clone());
+    if release.archive.size > 0 {
+        request.with_size(release.archive.size)
+    } else {
+        request
+    }
+}
+
+/// 按优先级链装一个托管 JDK（幂等：同一份归档装过就直接复用）。
+///
+/// # Errors
+///
+/// 全部发行版都失败（没有该大版本 / 平台无产物 / 网络 / 校验 / 解压 / 装完跑不起来）时
+/// 返回错误，`message()` 里带着每一跳的降级原因。
+pub async fn install(
+    engine: &DownloadEngine,
+    location: &JavaInstallRoot,
+    request: InstallRequest,
+) -> Result<InstalledJdk, JavaError> {
+    let target = AdoptiumTarget::host()?;
+    let domestic = engine.region().is_domestic();
+    let priority = request.order(domestic);
+    let mut chain = ChainLog::new();
+    let mut reasons: Vec<String> = Vec::new();
+    // 清掉上次中断留下的 .staging-* 与空壳（只碰我们自己的形状，见 location 模块）。
+    let _ = super::location::cleanup_orphans(&location.root);
+
+    for candidate in &priority {
+        let vendor = *candidate;
+        if !vendor.supports(request.major) {
+            let reason = format!(
+                "不支持 Java {}（{} 只发 {}）",
+                request.major,
+                vendor.id(),
+                majors_text(vendor)
+            );
+            chain.skip(vendor, reason.clone());
+            reasons.push(format!("{}：{reason}", vendor.id()));
+            continue;
+        }
+        let release = match source::fetch(engine, vendor, request.major, target).await {
+            Ok(release) => release,
+            Err(error) => {
+                chain.failed(vendor, error.message().to_string());
+                reasons.push(format!("{}：{}", vendor.id(), error.message()));
+                continue;
+            }
+        };
+        match install_one(engine, location, &release).await {
+            Ok(prepared) => {
+                chain.hit(vendor, format!("命中 {}", release.summary()));
+                return Ok(InstalledJdk {
+                    major: release.major,
+                    vendor,
+                    release,
+                    root: prepared.root,
+                    mode: location.mode,
+                    archive: prepared.archive,
+                    runtime: prepared.runtime,
+                    downloaded: prepared.downloaded,
+                    bytes: prepared.bytes,
+                    files: prepared.files,
+                    extracted: prepared.extracted,
+                    chain,
+                });
+            }
+            Err(error) => {
+                chain.failed(vendor, error.message().to_string());
+                reasons.push(format!("{}：{}", vendor.id(), error.message()));
+            }
+        }
+    }
+
+    Err(JavaError::new(
+        JavaErrorKind::Metadata,
+        format!(
+            "没有装成 Java {}（试过 {}）：{}",
+            request.major,
+            priority.len(),
+            reasons.join("；")
+        ),
+    )
+    .with_hint("`ull java vendors` 看各发行版的可用性；或手动装 JDK 后设 JAVA_HOME"))
+}
+
+/// 某一家的中间结果（把七元组元组换成具名结构，读起来才不费劲）。
+struct Prepared {
+    root: PathBuf,
+    archive: PathBuf,
+    runtime: JavaRuntime,
+    downloaded: Option<String>,
+    bytes: u64,
+    files: usize,
+    extracted: bool,
+}
+
+/// 装某一家的那一份（下载 → 解压 → 探测）。
+async fn install_one(
+    engine: &DownloadEngine,
+    location: &JavaInstallRoot,
+    release: &JdkRelease,
+) -> Result<Prepared, JavaError> {
+    let root = location.jdk_dir(release.major, release.vendor, &release.version);
+    let binary = extract::java_binary(&root);
+    let archive = archive_path(&location.root, release);
+
+    // 幂等第一层：戳记里的 sha256 与本次一致，且 bin/java 在 → 一个字节都不动。
+    if extract::is_ready(&root, release.sha256()) {
+        let runtime = probe::probe(&binary, JavaOrigin::Managed);
+        if runtime.major == Some(release.major) {
+            let mut runtime = runtime;
+            runtime.vendor = Some(release.vendor.id().to_string());
+            return Ok(Prepared {
+                root,
+                archive,
+                runtime,
+                downloaded: None,
+                bytes: 0,
+                files: 0,
+                extracted: false,
+            });
+        }
+        note(&format!(
+            "托管目录 {} 里的 java 跑不起来，重装一份",
+            root.display()
+        ));
+    }
+
+    if let Some(parent) = archive.parent() {
+        std::fs::create_dir_all(parent)
+            .map_err(|error| io_error("创建归档缓存目录", parent.display(), &error))?;
+    }
+    let outcome = engine
+        .download(archive_request(release, archive.clone()))
+        .await?;
+    let report = extract::extract_archive(&archive, release.sha256(), release.major, &root)?;
+    let mut runtime = probe::probe(&binary, JavaOrigin::Managed);
+    runtime.vendor = Some(release.vendor.id().to_string());
+    if runtime.major != Some(release.major) {
+        return Err(JavaError::new(
+            JavaErrorKind::Probe,
+            format!(
+                "装好的 JDK 探测结果是 Java {}，与请求的 {} 不符（{}）",
+                runtime
+                    .major
+                    .map_or_else(|| "未知".to_string(), |major| major.to_string()),
+                release.major,
+                binary.display()
+            ),
+        )
+        .with_hint("删掉该托管目录后重跑 `ull java install`；或手动设 JAVA_HOME"));
+    }
+    Ok(Prepared {
+        root,
+        archive,
+        runtime,
+        downloaded: Some(outcome.source),
+        bytes: outcome.bytes,
+        files: report.files,
+        extracted: report.wrote(),
+    })
+}
+
+/// 只做规划不落盘：返回将要安装的版本、目标目录与「是否已经装好」。
+///
+/// # Errors
+///
+/// 与 [`install`] 的查询段相同（平台不支持 / 网络失败 / 所有发行版都没有该大版本）。
+pub async fn plan(
+    engine: &DownloadEngine,
+    location: &JavaInstallRoot,
+    major: u32,
+) -> Result<(JdkRelease, PathBuf, bool), JavaError> {
+    let target = AdoptiumTarget::host()?;
+    let domestic = engine.region().is_domestic();
+    let mut reasons: Vec<String> = Vec::new();
+    for vendor in vendor::order(&[], domestic) {
+        if !vendor.supports(major) {
+            reasons.push(format!("{}：不支持 Java {major}", vendor.id()));
+            continue;
+        }
+        match source::fetch(engine, vendor, major, target).await {
+            Ok(release) => {
+                let root = location.jdk_dir(release.major, release.vendor, &release.version);
+                let ready = extract::is_ready(&root, release.sha256());
+                return Ok((release, root, ready));
+            }
+            Err(error) => reasons.push(format!("{}：{}", vendor.id(), error.message())),
+        }
+    }
+    Err(JavaError::new(
+        JavaErrorKind::Metadata,
+        format!("没有可用的 Java {major}（{} ）", reasons.join("；")),
+    ))
+}
+
+fn majors_text(vendor: JdkVendor) -> String {
+    vendor
+        .hint_majors()
+        .iter()
+        .map(u32::to_string)
+        .collect::<Vec<_>>()
+        .join("/")
+}
+
+fn note(message: &str) {
+    if cfg!(debug_assertions) {
+        eprintln!("[ull::game::java] {message}");
+    } else {
+        let _ = message;
+    }
+}
diff --git a/crates/core/src/game/java/location.rs b/crates/core/src/game/java/location.rs
new file mode 100644
index 0000000..21fac8b
--- /dev/null
+++ b/crates/core/src/game/java/location.rs
@@ -0,0 +1,335 @@
+//! 托管 JDK 的落点模式（D23 三模式，与 D6 数据目录三模式对齐）。
+//!
+//! | 模式 | 落点 | 说明 |
+//! | --- | --- | --- |
+//! | Portable | `<数据根>/.ULL/data/java-managed/jdk-<major>-<vendor>/` | v1 既有布局，M33/M35 的托管根解析语义不变 |
+//! | Standard | Windows `%APPDATA%\Java\<vendor>\<version>\`；macOS `~/Library/Application Support/Java/<vendor>/<version>`；Linux `$XDG_DATA_HOME/java/<vendor>/<version>`（回落 `~/.local/share/java/…`） | 用户原话「安装到 %APPDATA%\Java\发行方\Java版本\」 |
+//! | Custom | 设置键 `java.installRoot` 指定的目录，同样按 `<vendor>/<version>` 分层 | 覆盖前两种模式 |
+//!
+//! 三条纪律：
+//!
+//! 1. **不猜平台目录**：`%APPDATA%` / `XDG_DATA_HOME` / `HOME` 全走 `platform::paths::EnvSource`，
+//!    测试能注入假环境确定性地覆盖各 OS 落点；
+//! 2. **Portable 布局永不改**：`.ULL/data/java-managed/jdk-<major>-<vendor>` 是 M33 定下的，
+//!    改成 `<vendor>/<version>` 会让既有托管 JDK 变成孤儿——迁移语义靠「两种形状都扫得到」兜住；
+//! 3. **清理只碰自己的形状**：`cleanup_orphans` 只删 `.staging-*` 半成品与空目录，
+//!    没有戳记的非空目录一律不动（用户可能自己往里塞了 JDK）。
+
+use std::path::{Path, PathBuf};
+
+use crate::platform::data_dir::DataMode;
+use crate::platform::layout::LauncherLayout;
+use crate::platform::paths::{home_dir, EnvSource, Platform};
+
+use super::error::{JavaError, JavaErrorKind};
+use super::vendor::JdkVendor;
+
+/// Standard 模式下 JDK 的父目录名（Windows 是 `%APPDATA%\Java`）。
+pub const JAVA_DIR_NAME: &str = "Java";
+
+/// 归档缓存目录名（在安装根下；托管目录扫描跳过它）。
+pub const CACHE_DIR: &str = ".cache";
+
+/// 解压暂存目录前缀（中断后残留的就是孤儿）。
+pub const STAGING_PREFIX: &str = ".staging-";
+
+/// 落地模式。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum LocationMode {
+    /// 数据根内（v1 布局）。
+    Portable,
+    /// OS 标准应用数据目录。
+    Standard,
+    /// `java.installRoot` 指定。
+    Custom,
+}
+
+impl LocationMode {
+    /// 稳定名（JSON / 日志）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Portable => "portable",
+            Self::Standard => "standard",
+            Self::Custom => "custom",
+        }
+    }
+
+    /// 从配置字符串解析。
+    #[must_use]
+    pub fn parse(text: &str) -> Option<Self> {
+        match text {
+            "portable" => Some(Self::Portable),
+            "standard" => Some(Self::Standard),
+            "custom" => Some(Self::Custom),
+            _ => None,
+        }
+    }
+}
+
+/// 解析好的安装根 + 它是怎么来的。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct JavaInstallRoot {
+    /// 落地模式。
+    pub mode: LocationMode,
+    /// 安装根目录（各 JDK 目录在它下面）。
+    pub root: PathBuf,
+}
+
+impl JavaInstallRoot {
+    /// Portable：`<数据根>/.ULL/data/java-managed`。
+    #[must_use]
+    pub fn portable(launcher: &LauncherLayout) -> Self {
+        Self {
+            mode: LocationMode::Portable,
+            root: launcher.java_managed(),
+        }
+    }
+
+    /// Standard：OS 标准应用数据目录 + `Java`。
+    ///
+    /// 平台约定与 `platform::paths::standard_launcher_home` 同源：
+    /// - Windows：`%APPDATA%\Java`（回落 `%USERPROFILE%\AppData\Roaming\Java`）
+    /// - macOS：`~/Library/Application Support/Java`
+    /// - Linux / 其它：`$XDG_DATA_HOME/java`（回落 `~/.local/share/java`）
+    #[must_use]
+    pub fn standard(platform: Platform, env: &dyn EnvSource) -> Option<Self> {
+        standard_java_root(platform, env).map(|root| Self {
+            mode: LocationMode::Standard,
+            root,
+        })
+    }
+
+    /// Custom：`java.installRoot` 指定的目录（相对路径按数据根解析）。
+    #[must_use]
+    pub fn custom(root: impl Into<PathBuf>) -> Self {
+        Self {
+            mode: LocationMode::Custom,
+            root: root.into(),
+        }
+    }
+
+    /// 按设置解析出真正的落点。
+    ///
+    /// 顺序：`java.installRoot`（设了就用，模式 Custom）→ Standard（数据目录 Standard 模式）
+    /// → Portable（数据根内，含 `--data-dir` 的 Custom 数据模式）。
+    ///
+    /// # Errors
+    ///
+    /// 数据目录是 Standard 但拿不到系统标准目录时返回 [`JavaErrorKind::Unsupported`]
+    /// （不静默落到别处——否则用户会在 `%APPDATA%\Java` 里找不到刚装的 JDK）。
+    pub fn resolve(
+        data_mode: DataMode,
+        launcher: &LauncherLayout,
+        override_root: Option<&Path>,
+        platform: Platform,
+        env: &dyn EnvSource,
+    ) -> Result<Self, JavaError> {
+        if let Some(root) = override_root.filter(|root| !root.as_os_str().is_empty()) {
+            let root = if root.is_absolute() {
+                root.to_path_buf()
+            } else {
+                launcher.home().join(root)
+            };
+            return Ok(Self::custom(root));
+        }
+        if data_mode == DataMode::Standard {
+            return Self::standard(platform, env).ok_or_else(|| {
+                JavaError::new(
+                    JavaErrorKind::Unsupported,
+                    "Standard 模式下拿不到系统标准目录（%APPDATA% / HOME 都读不到）",
+                )
+                .with_hint(
+                    "设置 `java.installRoot` 指定一个目录，或把 `core.data_mode` 改回 portable",
+                )
+            });
+        }
+        Ok(Self::portable(launcher))
+    }
+
+    /// 某个 JDK 的目录。
+    ///
+    /// Standard / Custom 用 `<vendor>/<version>`（D23 用户原话的 `<发行方>\<Java版本>\`），
+    /// Portable 保持 v1 的 `jdk-<major>-<vendor>`（改形状会让既有托管 JDK 变孤儿）。
+    #[must_use]
+    pub fn jdk_dir(&self, major: u32, vendor: JdkVendor, version: &str) -> PathBuf {
+        match self.mode {
+            LocationMode::Standard | LocationMode::Custom => {
+                self.root.join(vendor.id()).join(sanitize_version(version))
+            }
+            LocationMode::Portable => self
+                .root
+                .join(super::probe::managed_dir_name(major, vendor.id())),
+        }
+    }
+
+    /// 归档缓存目录（`<root>/.cache`）。
+    #[must_use]
+    pub fn cache_dir(&self) -> PathBuf {
+        self.root.join(CACHE_DIR)
+    }
+
+    /// 人读描述（`Standard（%APPDATA%\Java）` 这种）。
+    #[must_use]
+    pub fn describe(&self) -> String {
+        format!("{}（{}）", self.mode.as_str(), self.root.display())
+    }
+}
+
+/// OS 标准 JDK 根（纯函数，测试注入环境）。
+///
+/// 注意 `HOME` 不用 `platform::paths::home_dir`：那个函数按**编译目标**分叉（Windows 上读
+/// `USERPROFILE`），会让「在 Windows 上断言 macOS/Linux 落点」这种测试无法成立。
+/// 这里按传入的 `platform` 参数走，语义与 `paths::standard_launcher_home` 的落点一致。
+#[must_use]
+pub fn standard_java_root(platform: Platform, env: &dyn EnvSource) -> Option<PathBuf> {
+    match platform {
+        Platform::Windows => roaming_app_data(env).map(|dir| dir.join(JAVA_DIR_NAME)),
+        Platform::MacOs => {
+            unix_home(env).map(|home| home.join("Library/Application Support").join(JAVA_DIR_NAME))
+        }
+        Platform::Linux | Platform::Other => env
+            .var("XDG_DATA_HOME")
+            .map(PathBuf::from)
+            .filter(|dir| dir.is_absolute())
+            .or_else(|| unix_home(env).map(|home| home.join(".local/share")))
+            .map(|dir| dir.join("java")),
+    }
+}
+
+/// Unix 家目录（`HOME`，缺了才退回 `platform::paths::home_dir`）。
+fn unix_home(env: &dyn EnvSource) -> Option<PathBuf> {
+    env.var("HOME").map(PathBuf::from).or_else(|| home_dir(env))
+}
+
+/// `%APPDATA%`，回落 `%USERPROFILE%\AppData\Roaming`。
+fn roaming_app_data(env: &dyn EnvSource) -> Option<PathBuf> {
+    env.var("APPDATA").map(PathBuf::from).or_else(|| {
+        env.var("USERPROFILE")
+            .map(|profile| PathBuf::from(profile).join("AppData/Roaming"))
+    })
+}
+
+/// 版本号 → 目录名（只保留文件系统安全的字符）。
+///
+/// Temurin `21.0.13+9`、MS `21.0.13.0.2`、Zulu `21.0.13+3` 都原样可作目录名；
+/// 遇到 `~` / `/` 这类才替换（Zulu 的 `21.0.13+3-x86_64` 之类不会出现，但别赌）。
+#[must_use]
+pub fn sanitize_version(version: &str) -> String {
+    let cleaned: String = version
+        .trim()
+        .chars()
+        .map(|ch| {
+            if ch.is_ascii_alphanumeric() || matches!(ch, '.' | '-' | '_' | '+') {
+                ch
+            } else {
+                '_'
+            }
+        })
+        .collect();
+    if cleaned.is_empty() {
+        "unknown".to_string()
+    } else {
+        cleaned
+    }
+}
+
+/// `java list` 要扫的全部安装根（Portable 数据根在前，去重）。
+#[must_use]
+pub fn scan_roots(
+    data_mode: DataMode,
+    launcher: &LauncherLayout,
+    override_root: Option<&Path>,
+    platform: Platform,
+    env: &dyn EnvSource,
+) -> Vec<PathBuf> {
+    let mut roots = vec![launcher.java_managed()];
+    if let Ok(resolved) =
+        JavaInstallRoot::resolve(data_mode, launcher, override_root, platform, env)
+    {
+        if !roots.contains(&resolved.root) {
+            roots.push(resolved.root);
+        }
+    }
+    // 数据目录是 Standard 时，便携目录里的老装法仍然可能还在（用户从便携切过来的）。
+    if let Some(standard) = standard_java_root(platform, env) {
+        if !roots.contains(&standard) {
+            roots.push(standard);
+        }
+    }
+    roots
+}
+
+/// 清理结果。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct CleanupReport {
+    /// 删掉的路径（暂存目录、空壳目录）。
+    pub removed: Vec<PathBuf>,
+    /// 保留下来的条目数（都是我们没资格动的）。
+    pub kept: usize,
+}
+
+impl CleanupReport {
+    /// 是否什么都没删。
+    #[must_use]
+    pub fn is_noop(&self) -> bool {
+        self.removed.is_empty()
+    }
+}
+
+/// 清掉安装根下的半成品与空壳。
+///
+/// 只碰两种东西：①`.staging-*`（解压中断的残留，永远可以删）②空目录（含空 vendor 目录）。
+/// 其余一律保留并计入 `kept`——**宁可不删，也不误删用户手工放进来的 JDK**。
+#[must_use]
+pub fn cleanup_orphans(root: &Path) -> CleanupReport {
+    let mut report = CleanupReport::default();
+    let Ok(entries) = std::fs::read_dir(root) else {
+        return report;
+    };
+    for entry in entries.flatten() {
+        let path = entry.path();
+        let name = entry.file_name().to_string_lossy().into_owned();
+        if !path.is_dir() || name == CACHE_DIR {
+            report.kept += 1;
+            continue;
+        }
+        if name.starts_with(STAGING_PREFIX) {
+            if std::fs::remove_dir_all(&path).is_ok() {
+                report.removed.push(path);
+            } else {
+                report.kept += 1;
+            }
+            continue;
+        }
+        if is_empty_dir(&path) {
+            if std::fs::remove_dir(&path).is_ok() {
+                report.removed.push(path);
+            } else {
+                report.kept += 1;
+            }
+            continue;
+        }
+        // 两层的 Standard/Custom 布局：`<vendor>/<version>` 里的空目录也要收。
+        if JdkVendor::parse(&name).is_some() {
+            for child in std::fs::read_dir(&path).into_iter().flatten().flatten() {
+                let child_path = child.path();
+                if child_path.is_dir()
+                    && is_empty_dir(&child_path)
+                    && std::fs::remove_dir(&child_path).is_ok()
+                {
+                    report.removed.push(child_path);
+                }
+            }
+            if is_empty_dir(&path) && std::fs::remove_dir(&path).is_ok() {
+                report.removed.push(path);
+            }
+        }
+        report.kept += 1;
+    }
+    report
+}
+
+fn is_empty_dir(dir: &Path) -> bool {
+    std::fs::read_dir(dir).is_ok_and(|mut entries| entries.next().is_none())
+}
diff --git a/crates/core/src/game/java/mapping.rs b/crates/core/src/game/java/mapping.rs
new file mode 100644
index 0000000..930b889
--- /dev/null
+++ b/crates/core/src/game/java/mapping.rs
@@ -0,0 +1,376 @@
+//! MC 版本 ↔ Java 版本映射（平移 HMCL 约束体系）+ 不符检查。
+//!
+//! 依据 `DevDocs/analyse/02-launch-pipeline.md` §5.4（HMCL `GameJavaVersion.getMinimumJavaVersion`）
+//! 与 §3.1 的强制约束清单（`JavaVersionConstraint` 的 `isMandatory` 项）。两条权威叠加：
+//!
+//! | MC 版本 | 最低 | 最高 | 出处 |
+//! | --- | --- | --- | --- |
+//! | ≥ 26.1 | 25 | — | `java-runtime-epsilon` |
+//! | ≥ 1.20.5 | 21 | — | `java-runtime-delta` |
+//! | ≥ 1.18 | 17 | — | `java-runtime-beta` |
+//! | ≥ 1.17 | 16 | — | `java-runtime-alpha` |
+//! | ≥ 1.13 | 8 | — | `jre-legacy` |
+//! | < 1.13 | 8 | **8** | `LAUNCH_WRAPPER`：LaunchWrapper 的 `URLClassLoader` 只能吃 Java 8 |
+//!
+//! **版本 JSON 优先**：装了 1.17 的玩家看的是 Mojang 自己写的 `javaVersion.majorVersion`
+//! （1.17 就是 16），静态表只在清单没写时兜底——这也是 HMCL 的 `GAME_JSON` 强制项语义。
+//!
+//! 上限（`maximum`）只对老版本存在：1.12.2 用 Java 17 会直接
+//! `UnsupportedClassVersionError`-级别的失败（启动器侧是 LaunchWrapper 假设），
+//! 所以「1.12.2 + Java 21」要被判成不符，而不是「19 以上都能跑」。
+
+use std::cmp::Ordering;
+
+use super::super::inherit::resolve;
+use super::super::layout::GameLayout;
+use super::super::manifest::{JavaVersion, VersionJson};
+
+/// 要求来源（`--json` 的 `requirement_source`）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RequirementSource {
+    /// 版本 JSON 的 `javaVersion`（含继承链解析）。
+    Manifest,
+    /// 静态表（HMCL 约束体系的平移）。
+    Table,
+}
+
+impl RequirementSource {
+    /// 稳定字符串 id。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Manifest => "manifest",
+            Self::Table => "table",
+        }
+    }
+}
+
+/// 一个版本对 Java 的要求（闭区间）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct JavaRequirement {
+    /// 最低主版本号（`21`）。
+    pub minimum: u32,
+    /// 最高主版本号（`Some(8)` = 只能用 8 及以下）。
+    pub maximum: Option<u32>,
+    /// 来源。
+    pub source: RequirementSource,
+}
+
+impl JavaRequirement {
+    /// 构造。
+    #[must_use]
+    pub const fn new(minimum: u32, maximum: Option<u32>, source: RequirementSource) -> Self {
+        Self {
+            minimum,
+            maximum,
+            source,
+        }
+    }
+
+    /// 静态表来源的构造。
+    #[must_use]
+    pub const fn table(minimum: u32, maximum: Option<u32>) -> Self {
+        Self::new(minimum, maximum, RequirementSource::Table)
+    }
+
+    /// 某主版本号是否满足要求。
+    #[must_use]
+    pub fn satisfied_by(&self, major: u32) -> bool {
+        major >= self.minimum && self.maximum.is_none_or(|maximum| major <= maximum)
+    }
+
+    /// 人读描述（`Java 21+` / `Java 8` / `Java 8–16`）。
+    #[must_use]
+    pub fn describe(&self) -> String {
+        match self.maximum {
+            Some(maximum) if maximum == self.minimum => format!("Java {}", self.minimum),
+            Some(maximum) => format!("Java {}–{}", self.minimum, maximum),
+            None => format!("Java {}+", self.minimum),
+        }
+    }
+}
+
+/// 不符的两种形态（D13：只提示，不阻断）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum JavaMismatch {
+    /// Java 太低。
+    TooOld {
+        /// 需要的最低主版本。
+        required: u32,
+        /// 实际主版本。
+        actual: u32,
+    },
+    /// Java 太高（老版本只能用 8）。
+    TooNew {
+        /// 允许的最高主版本。
+        maximum: u32,
+        /// 实际主版本。
+        actual: u32,
+    },
+}
+
+impl JavaMismatch {
+    /// 稳定字符串 id（`--json` 的 `mismatch.code`）。
+    #[must_use]
+    pub const fn code(self) -> &'static str {
+        match self {
+            Self::TooOld { .. } => "java_too_old",
+            Self::TooNew { .. } => "java_too_new",
+        }
+    }
+
+    /// 人读说明（GUI 弹窗 P1 后直接复用这句）。
+    #[must_use]
+    pub fn message(self) -> String {
+        match self {
+            Self::TooOld { required, actual } => format!(
+                "该版本需要 Java {required} 及以上，当前用的是 Java {actual}（大概率起不来）"
+            ),
+            Self::TooNew { maximum, actual } => format!(
+                "该版本只能用 Java {maximum} 及以下，当前用的是 Java {actual}（老加载器吃不了新 class 文件）"
+            ),
+        }
+    }
+}
+
+/// 判需求与实际是否相符（`None` = 相符）。
+#[must_use]
+pub fn check(actual: u32, required: &JavaRequirement) -> Option<JavaMismatch> {
+    if actual < required.minimum {
+        return Some(JavaMismatch::TooOld {
+            required: required.minimum,
+            actual,
+        });
+    }
+    if let Some(maximum) = required.maximum {
+        if actual > maximum {
+            return Some(JavaMismatch::TooNew { maximum, actual });
+        }
+    }
+    None
+}
+
+/// 静态表：MC 版本 → Java 要求。
+///
+/// 无法解析的版本（周快照 `20w14a`、魔改 id）只给下限 `8`、不设上限——
+/// 宁可漏判一次，也不要把「Java 21 + 1.20 快照」误锁成「必须降到 8」。
+#[must_use]
+pub fn requirement_for(mc_version: &str) -> JavaRequirement {
+    let parts = version_parts(mc_version);
+    if parts.is_empty() {
+        return JavaRequirement::table(8, None);
+    }
+    if at_least(&parts, &[26, 1]) {
+        return JavaRequirement::table(25, None);
+    }
+    if at_least(&parts, &[1, 20, 5]) {
+        return JavaRequirement::table(21, None);
+    }
+    if at_least(&parts, &[1, 18]) {
+        return JavaRequirement::table(17, None);
+    }
+    if at_least(&parts, &[1, 17]) {
+        return JavaRequirement::table(16, None);
+    }
+    if at_least(&parts, &[1, 13]) {
+        return JavaRequirement::table(8, None);
+    }
+    JavaRequirement::table(8, Some(8))
+}
+
+/// 静态表的最低位（`recommended_major("1.20.5") == 21`）。
+#[must_use]
+pub fn recommended_major(mc_version: &str) -> u32 {
+    requirement_for(mc_version).minimum
+}
+
+/// 版本 JSON 的 `javaVersion` → 要求（字段缺失或为 0 时返回 `None`）。
+///
+/// Mojang 这个字段给的是**最低**要求（`majorVersion: 21` 表示 21 起跳），
+/// 不声明上限——所以这里 `maximum` 恒为 `None`；上限由 [`requirement_for`] 补
+/// （见 [`requirement_for_version`] 的合成说明）。
+#[must_use]
+pub fn requirement_from_manifest(java: &JavaVersion) -> Option<JavaRequirement> {
+    let major = java.major_version.filter(|major| *major > 0)?;
+    Some(JavaRequirement::new(
+        major,
+        None,
+        RequirementSource::Manifest,
+    ))
+}
+
+/// 已安装版本的 Java 要求：解析继承链 → 版本 JSON 的 `javaVersion` 优先 → 静态表兜底。
+///
+/// **下限与上限来源不同**：Mojang 的 `javaVersion` 只声明「最低要多少」，
+/// 而「1.12.2 及更早吃不了 Java 9+」这条知识来自 HMCL 的 `LAUNCH_WRAPPER` 约束，
+/// 不在清单里。所以合成时下限取清单、上限取静态表——否则「1.12.2 + Java 21」
+/// 会被判成完全合法（真机上必崩）。
+///
+/// 版本 JSON 读不到（未安装 / 损坏）时直接走静态表，不报错——这是「启动前提示」的路径，
+/// 不该因为清单缺件就拦住用户（真正拦人的是 `snapshot::prepare`）。
+#[must_use]
+pub fn requirement_for_version(layout: &GameLayout, version_id: &str) -> JavaRequirement {
+    let table = requirement_for(version_id);
+    let read = |id: &str| -> Option<VersionJson> {
+        let text = std::fs::read_to_string(layout.version_json(id)).ok()?;
+        VersionJson::from_json_str(&text).ok()
+    };
+    let Some(manifest) = read(version_id) else {
+        return table;
+    };
+    let resolved = resolve(&read, &manifest).unwrap_or(manifest);
+    let Some(declared) = resolved
+        .java_version
+        .as_ref()
+        .and_then(requirement_from_manifest)
+    else {
+        // 清单没写 javaVersion：按 id 的静态表（继承来的 id 可能是魔改名）。
+        return match resolved.id.as_deref() {
+            Some(id) => requirement_for(id),
+            None => table,
+        };
+    };
+    JavaRequirement {
+        minimum: declared.minimum,
+        maximum: table.maximum,
+        source: RequirementSource::Manifest,
+    }
+}
+
+/// 版本串 → 数字分量（`1.20.5-pre1` → `[1, 20, 5]`；周快照 → 空）。
+fn version_parts(raw: &str) -> Vec<u32> {
+    let trimmed = raw.trim();
+    if is_weekly_snapshot(trimmed) {
+        return Vec::new();
+    }
+    let mut parts = Vec::new();
+    for piece in trimmed.split('.') {
+        let digits: String = piece.chars().take_while(char::is_ascii_digit).collect();
+        match digits.parse::<u32>() {
+            Ok(value) => parts.push(value),
+            Err(_) => break,
+        }
+    }
+    parts
+}
+
+/// `20w14a` / `26w14a` 形态（与 `launch::game_version` 同一套判据）。
+fn is_weekly_snapshot(raw: &str) -> bool {
+    let bytes = raw.as_bytes();
+    bytes.len() == 6
+        && bytes[..2].iter().all(u8::is_ascii_digit)
+        && bytes[2].eq_ignore_ascii_case(&b'w')
+        && bytes[3..5].iter().all(u8::is_ascii_digit)
+        && bytes[5].is_ascii_alphabetic()
+}
+
+/// `parts >= floor`（缺位按 0：`1.20` < `1.20.5`）。
+fn at_least(parts: &[u32], floor: &[u32]) -> bool {
+    let len = parts.len().max(floor.len());
+    for index in 0..len {
+        let left = parts.get(index).copied().unwrap_or(0);
+        let right = floor.get(index).copied().unwrap_or(0);
+        match left.cmp(&right) {
+            Ordering::Greater => return true,
+            Ordering::Less => return false,
+            Ordering::Equal => {}
+        }
+    }
+    true
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{check, recommended_major, requirement_for, JavaMismatch, JavaRequirement};
+
+    #[test]
+    fn table_covers_the_hmcl_boundaries() {
+        let cases: &[(&str, u32, Option<u32>)] = &[
+            ("1.6.4", 8, Some(8)),
+            ("1.12.2", 8, Some(8)),
+            ("1.13", 8, None),
+            ("1.15.2", 8, None),
+            ("1.16.5", 8, None),
+            ("1.17", 16, None),
+            ("1.17.1", 16, None),
+            ("1.18", 17, None),
+            ("1.19.4", 17, None),
+            ("1.20.1", 17, None),
+            ("1.20.4", 17, None),
+            ("1.20.5", 21, None),
+            ("1.21.4", 21, None),
+            ("26.1", 25, None),
+            ("26.3", 25, None),
+            ("26.3-snapshot-1", 25, None),
+        ];
+        for (version, minimum, maximum) in cases {
+            let requirement = requirement_for(version);
+            assert_eq!(
+                (requirement.minimum, requirement.maximum),
+                (*minimum, *maximum),
+                "{version}"
+            );
+            assert_eq!(recommended_major(version), *minimum, "{version}");
+        }
+    }
+
+    #[test]
+    fn weekly_snapshots_get_no_upper_bound() {
+        // 20w14a 的前导数字是 20，绝不能被当成「26.x」或误锁上限。
+        let requirement = requirement_for("20w14a");
+        assert_eq!(requirement.minimum, 8);
+        assert_eq!(requirement.maximum, None);
+        assert!(requirement.satisfied_by(21));
+    }
+
+    #[test]
+    fn pre_release_suffixes_do_not_change_the_floor() {
+        assert_eq!(requirement_for("1.20.5-pre1").minimum, 21);
+        assert_eq!(requirement_for("1.20.4-rc1").minimum, 17);
+    }
+
+    #[test]
+    fn check_reports_both_directions() {
+        let modern = JavaRequirement::table(21, None);
+        assert_eq!(check(21, &modern), None);
+        assert_eq!(check(25, &modern), None);
+        assert_eq!(
+            check(17, &modern),
+            Some(JavaMismatch::TooOld {
+                required: 21,
+                actual: 17
+            })
+        );
+        let legacy = JavaRequirement::table(8, Some(8));
+        assert_eq!(check(8, &legacy), None);
+        assert_eq!(
+            check(21, &legacy),
+            Some(JavaMismatch::TooNew {
+                maximum: 8,
+                actual: 21
+            })
+        );
+        assert_eq!(legacy.describe(), "Java 8");
+        assert_eq!(modern.describe(), "Java 21+");
+        assert_eq!(JavaRequirement::table(8, Some(16)).describe(), "Java 8–16");
+    }
+
+    #[test]
+    fn mismatch_messages_name_both_sides() {
+        let message = JavaMismatch::TooOld {
+            required: 21,
+            actual: 8,
+        }
+        .message();
+        assert!(message.contains("Java 21"));
+        assert!(message.contains("Java 8"));
+        assert_eq!(
+            JavaMismatch::TooNew {
+                maximum: 8,
+                actual: 21
+            }
+            .code(),
+            "java_too_new"
+        );
+    }
+}
diff --git a/crates/core/src/game/java/microsoft.rs b/crates/core/src/game/java/microsoft.rs
new file mode 100644
index 0000000..957c59c
--- /dev/null
+++ b/crates/core/src/game/java/microsoft.rs
@@ -0,0 +1,261 @@
+//! Microsoft OpenJDK：`aka.ms` 模板下载 + 成对 `.sha256sum.txt` 校验。
+//!
+//! 分发形态与 Temurin / Oracle 都不同（research/06 §3.2）：
+//!
+//! ```text
+//! 下载   https://aka.ms/download-jdk/microsoft-jdk-{version}-{os}-{arch}.zip
+//!        → 301 → https://download.visualstudio.microsoft.com/download/pr/{guid}/{hash}/{同名}
+//! 校验   https://aka.ms/download-jdk/<同一文件名>.sha256sum.txt   # "<hash>  <filename>"
+//! ```
+//!
+//! 三条硬事实（都影响实现）：
+//!
+//! 1. **版本是四段/五段**（`21.0.13.0.2` = JDK 21.0.13+2；11 线是 `11.0.32.1`），
+//!    不能拿 Temurin 的三段号直接拼——所以这里有自己的 [`parse_version`] 与内置快照表；
+//! 2. **没有 8**（微软已停发，官方页面让去下 Temurin 8），`supports()` 也这么判；
+//! 3. **GitHub 侧没有任何资产**（`microsoft/openjdk` 的 release `assets` 全空），
+//!    所以 gh-proxy 对这条链毫无用处——`domestic_mirrors` 实测为空数组。
+
+use super::error::{JavaError, JavaErrorKind};
+use super::net;
+use super::release::{parse_sha256_text, JdkArchive, JdkRelease};
+use super::target::AdoptiumTarget;
+use super::vendor::JdkVendor;
+use crate::download::MsOpenJdkTable;
+
+/// 内置版本快照（`learn.microsoft.com/java/openjdk/download` 2026-10-30 的表，research/06 §1.3）。
+///
+/// 官方只有人读 HTML 表、没有 JSON API，逐版本探测又要 `aka.ms` 301（0.3–0.8 s/次），
+/// 所以按 research/06 §3.3 的建议 A 内置快照；`size` 与实测字节数一致，用于长度对拍。
+pub const SNAPSHOT: &[(u32, &str, u64)] = &[
+    (25, "25.0.5.0.2", 220_869_659),
+    (21, "21.0.13.0.2", 201_450_315),
+    (17, "17.0.21.0.2", 187_236_595),
+    (11, "11.0.32.1", 191_250_397),
+];
+
+/// 四段/五段版本号（`21.0.13.0.2` / `11.0.32.1`）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct MsVersion {
+    /// 大版本（`21`）。
+    pub major: u32,
+    /// 各数字段（长度 3..=5）。
+    pub segments: Vec<u32>,
+}
+
+impl MsVersion {
+    /// 原样的版本串。
+    #[must_use]
+    pub fn text(&self) -> String {
+        self.segments
+            .iter()
+            .map(u32::to_string)
+            .collect::<Vec<_>>()
+            .join(".")
+    }
+}
+
+/// 解析 MS 的版本串；段数必须 3..=5（MS 的语义：`major.update.patch[.build[.rev]]`）。
+#[must_use]
+pub fn parse_version(text: &str) -> Option<MsVersion> {
+    let mut segments = Vec::new();
+    for segment in text.trim().split('.') {
+        segments.push(segment.parse::<u32>().ok()?);
+    }
+    if segments.len() < 3 || segments.len() > 5 {
+        return None;
+    }
+    Some(MsVersion {
+        major: segments[0],
+        segments,
+    })
+}
+
+/// MS 的 os 段（`windows` / `macos` / `linux`）。
+#[must_use]
+pub fn ms_os(target: AdoptiumTarget) -> &'static str {
+    match target.os {
+        "mac" => "macos",
+        other => other,
+    }
+}
+
+/// MS 的 arch 段（`x64` / `aarch64`）。
+#[must_use]
+pub fn ms_arch(target: AdoptiumTarget) -> &'static str {
+    target.arch
+}
+
+/// 归档文件名（模板：`microsoft-jdk-{version}-{os}-{arch}.zip`，全平台都是 zip）。
+#[must_use]
+pub fn archive_name(version: &str, target: AdoptiumTarget) -> String {
+    format!(
+        "microsoft-jdk-{version}-{}-{}.zip",
+        ms_os(target),
+        ms_arch(target)
+    )
+}
+
+/// 把模板里的 `{version}` / `{os}` / `{arch}` 换掉。
+#[must_use]
+pub fn expand_template(template: &str, version: &str, target: AdoptiumTarget) -> String {
+    template
+        .replace("{version}", version)
+        .replace("{os}", ms_os(target))
+        .replace("{arch}", ms_arch(target))
+}
+
+/// 快照里该大版本的版本串（没有 → `None`）。
+#[must_use]
+pub fn snapshot_version(major: u32) -> Option<&'static str> {
+    SNAPSHOT
+        .iter()
+        .find(|(known, _, _)| *known == major)
+        .map(|(_, version, _)| *version)
+}
+
+/// 快照里该大版本的字节数。
+#[must_use]
+pub fn snapshot_size(major: u32) -> Option<u64> {
+    SNAPSHOT
+        .iter()
+        .find(|(known, _, _)| *known == major)
+        .map(|(_, _, size)| *size)
+}
+
+/// 查一次「某大版本的最新 MS OpenJDK」。
+///
+/// 两跳：内置快照挑版本 → 取 `.sha256sum.txt` 拿哈希。校验文件取不到就整家失败
+/// （宁可降级到 Zulu，也不下一个没法验证的 200 MB 归档）。
+///
+/// # Errors
+///
+/// 表里没配模板、该大版本微软不发（含 8）、校验文件取不到或格式不对时返回错误。
+pub async fn fetch_latest(
+    client: &reqwest::Client,
+    table: &MsOpenJdkTable,
+    major: u32,
+    target: AdoptiumTarget,
+) -> Result<JdkRelease, JavaError> {
+    let version = snapshot_version(major).ok_or_else(|| {
+        JavaError::new(
+            JavaErrorKind::Metadata,
+            format!(
+                "Microsoft OpenJDK 没有 {major} 的 GA（只发 {}）",
+                majors_text()
+            ),
+        )
+        .with_hint("8 用 temurin；其它大版本用 oracle / zulu")
+    })?;
+    let filename = archive_name(version, target);
+    let sha_url = expand_template(&table.sha256_template, version, target);
+    let sha_text = net::get_text(client, &sha_url, "Microsoft OpenJDK 校验文件").await?;
+    let sha256 = parse_sha256_text(&sha_text).ok_or_else(|| {
+        JavaError::new(
+            JavaErrorKind::Integrity,
+            format!("{filename} 的 .sha256sum.txt 里没有 64 位哈希"),
+        )
+    })?;
+    Ok(JdkRelease {
+        vendor: JdkVendor::Microsoft,
+        major,
+        version: version.to_string(),
+        semver: None,
+        release_name: version.to_string(),
+        archive: JdkArchive {
+            name: filename.clone(),
+            url: expand_template(&table.template, version, target),
+            sha256,
+            size: snapshot_size(major).unwrap_or(0),
+        },
+    })
+}
+
+fn majors_text() -> String {
+    SNAPSHOT
+        .iter()
+        .map(|(major, _, _)| major.to_string())
+        .collect::<Vec<_>>()
+        .join(" / ")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{
+        archive_name, expand_template, ms_os, parse_version, snapshot_size, snapshot_version,
+        SNAPSHOT,
+    };
+    use crate::game::java::target::AdoptiumTarget;
+
+    const WINDOWS: AdoptiumTarget = AdoptiumTarget::new("windows", "x64");
+
+    #[test]
+    fn snapshot_covers_the_four_majors_microsoft_ships() {
+        assert_eq!(snapshot_version(21), Some("21.0.13.0.2"));
+        assert_eq!(snapshot_version(11), Some("11.0.32.1"));
+        assert_eq!(snapshot_version(8), None, "微软已停发 8");
+        assert_eq!(snapshot_size(17), Some(187_236_595));
+        assert_eq!(
+            SNAPSHOT
+                .iter()
+                .map(|(major, _, _)| *major)
+                .collect::<Vec<_>>(),
+            vec![25, 21, 17, 11]
+        );
+    }
+
+    #[test]
+    fn four_and_five_segment_versions_have_their_own_semantics() {
+        // 21.0.13.0.2 = JDK 21.0.13+2（五段）；11 线只有四段。
+        let ms = parse_version("21.0.13.0.2").expect("五段应解析");
+        assert_eq!(ms.major, 21);
+        assert_eq!(ms.segments.len(), 5);
+        assert_eq!(ms.text(), "21.0.13.0.2");
+        let eleven = parse_version("11.0.32.1").expect("四段应解析");
+        assert_eq!(eleven.major, 11);
+        assert_eq!(eleven.segments.len(), 4);
+        // Temurin 的三段号形态在这里同样成立，但语义由快照表定义，不共用 Temurin 的解析。
+        assert_eq!(
+            parse_version("17.0.21").map(|version| version.major),
+            Some(17)
+        );
+        assert_eq!(parse_version("21"), None);
+        assert_eq!(parse_version("21.0"), None);
+        assert_eq!(parse_version("21.0.13.0.2.1"), None);
+        assert_eq!(parse_version("21.0.x.2"), None);
+    }
+
+    #[test]
+    fn archive_names_and_templates_expand_per_platform() {
+        assert_eq!(
+            archive_name("21.0.13.0.2", WINDOWS),
+            "microsoft-jdk-21.0.13.0.2-windows-x64.zip"
+        );
+        let template = "https://aka.ms/download-jdk/microsoft-jdk-{version}-{os}-{arch}.zip";
+        assert_eq!(
+            expand_template(template, "17.0.21.0.2", WINDOWS),
+            "https://aka.ms/download-jdk/microsoft-jdk-17.0.21.0.2-windows-x64.zip"
+        );
+        assert_eq!(
+            expand_template(
+                "https://aka.ms/download-jdk/microsoft-jdk-{version}-{os}-{arch}.zip.sha256sum.txt",
+                "21.0.13.0.2",
+                AdoptiumTarget::new("linux", "aarch64")
+            ),
+            "https://aka.ms/download-jdk/microsoft-jdk-21.0.13.0.2-linux-aarch64.zip.sha256sum.txt"
+        );
+        assert_eq!(ms_os(AdoptiumTarget::new("mac", "x64")), "macos");
+    }
+
+    #[test]
+    fn builtin_table_uses_the_official_templates() {
+        let table = crate::download::MirrorTable::builtin();
+        let microsoft = table.microsoft_openjdk().expect("内置表应带 MS 分发");
+        assert!(microsoft
+            .template
+            .starts_with("https://aka.ms/download-jdk/"));
+        assert!(microsoft.sha256_template.ends_with(".sha256sum.txt"));
+        assert!(microsoft.domestic_mirrors.is_empty(), "MS 无国内镜像");
+        assert_eq!(microsoft.majors, vec![25, 21, 17, 11]);
+    }
+}
diff --git a/crates/core/src/game/java/mod.rs b/crates/core/src/game/java/mod.rs
new file mode 100644
index 0000000..45e0110
--- /dev/null
+++ b/crates/core/src/game/java/mod.rs
@@ -0,0 +1,90 @@
+//! Java 运行时管理（D13 v1 → D23 v2）：托管 JDK 的查询 / 下载 / 解压 / 探测，以及 MC↔Java 映射。
+//!
+//! ```text
+//! target    宿主平台 → Adoptium 的 os/arch（Win=zip、Linux/mac=tar.gz）
+//! vendor    四家发行版与用户可调的优先级链（国内 Temurin→Oracle→MS / 国外 Temurin→MS→Oracle）
+//! api       Temurin：api.adoptium.net 查询最新 GA → (github 直链, sha256, size)
+//! oracle    Oracle OpenJDK：镜像目录页解析（hash 段不可推导，禁止拼 URL）+ .sha256
+//! microsoft MS OpenJDK：aka.ms 模板 + 内置四段版本快照 + .sha256sum.txt
+//! zulu      Azul Zulu：两跳 JSON API（列表 → 详情）+ CDN 直链（第四备选）
+//! source    发行版分派 + 回退链记录（命中与降级原因进事件流）
+//! location  落点三模式（Portable / Standard / Custom）+ 孤儿目录清理
+//! release   一次版本查询的统一产物（vendor 原生版本串 + 归档 + sha256 + 大小）
+//! net       版本查询用的极小 GET 文本工具（下载不走这里）
+//! install   编排：回退链 → 下载引擎（镜像/健康度/退避）→ 解压 → 探测验证
+//! extract   zip / tar.gz 解压 + 顶层目录剥离 + 幂等戳记 + zip-slip 防护
+//! probe     java -version 探测、托管目录扫描（两种布局都认）
+//! discover  标准安装位置扫描（Program Files 系 / 官方启动器 runtime / 注册表 / /usr/lib/jvm）+ 去重
+//! select    启动选 Java 的**纯**优先链（满足要求优先，再按来源）
+//! mapping   MC↔Java 静态表（HMCL `GameJavaVersion`）+ 版本 JSON 优先 + 不符检查
+//! ```
+//!
+//! # 三条边界
+//!
+//! 1. **不碰网络细节**：包下载一律交 `core::download` 的引擎，本模块不写重试循环
+//!    （`MirrorTable::expand` 负责 Temurin 的镜像展开；Oracle 的目录解析在 `oracle`）；
+//! 2. **不弹窗**：不符检查只产出数据（[`JavaMismatch`]），提示交给 CLI 的告警行与 GUI；
+//! 3. **不改启动策略**：「用哪个 Java 启动」是启动期的派生结果，不落盘；落盘的是**装到哪**
+//!    （[`JavaInstallRoot`]，由 `java.installRoot` + 数据目录模式决定）。
+//!
+//! # 托管布局（D23 后两种并存）
+//!
+//! ```text
+//! Portable：data/java-managed/
+//! ├── .cache/OpenJDK21U-jdk_x64_windows_hotspot_21.0.13_9.zip   归档缓存（可删）
+//! └── jdk-21-temurin/                                          一个 major+vendor 一份（永不改）
+//!     ├── .ull-jdk.json                                        戳记（幂等判据）
+//!     └── bin/java[.exe]
+//!
+//! Standard / Custom：%APPDATA%\Java\<vendor>\<version>\     （mac/Linux 见 location 模块）
+//! ```
+
+pub mod api;
+pub mod discover;
+pub mod error;
+pub mod extract;
+pub mod install;
+pub mod location;
+pub mod mapping;
+pub mod microsoft;
+pub mod net;
+pub mod oracle;
+pub mod probe;
+pub mod release;
+pub mod select;
+pub mod source;
+pub mod target;
+pub mod vendor;
+pub mod zulu;
+
+pub use self::api::{
+    latest_url, parse_latest, JdkArchive, JdkRelease, ADOPTIUM_API_BASE, JDK_VENDOR,
+};
+pub use self::discover::{
+    candidates, candidates_in_roots, scan_java_binaries, standard_candidates, standard_roots,
+};
+pub use self::error::{JavaError, JavaErrorKind};
+pub use self::extract::{
+    extract_archive, is_ready, java_binary, java_binary_name, read_stamp, ExtractReport, JdkStamp,
+    STAMP_FILE,
+};
+pub use self::install::{
+    archive_path, archive_request, chain_order, install, managed_root_dir, plan, InstallRequest,
+    InstalledJdk,
+};
+pub use self::location::{
+    cleanup_orphans, sanitize_version, scan_roots, CleanupReport, JavaInstallRoot, LocationMode,
+};
+pub use self::mapping::{
+    check, recommended_major, requirement_for, requirement_for_version, JavaMismatch,
+    JavaRequirement, RequirementSource,
+};
+pub use self::probe::{
+    discover_managed, discover_managed_roots, managed_dir_name, parse_managed_dir, probe,
+    resolve_on_path, system_candidates, JavaOrigin, JavaRuntime, DEFAULT_MAJOR,
+};
+pub use self::release::parse_sha256_text;
+pub use self::select::{pick, resolve, JavaResolution};
+pub use self::source::{ChainLog, VendorAttempt};
+pub use self::target::AdoptiumTarget;
+pub use self::vendor::{order as vendor_order, JdkVendor, VENDOR_IDS};
diff --git a/crates/core/src/game/java/net.rs b/crates/core/src/game/java/net.rs
new file mode 100644
index 0000000..991d994
--- /dev/null
+++ b/crates/core/src/game/java/net.rs
@@ -0,0 +1,60 @@
+//! 版本查询用的极小 HTTP 取文本工具（四家发行版的「一锤子 GET」共用）。
+//!
+//! 只有一件事：GET → 状态分类 → 整段文本。**下载不走这里**（那归 `core::download` 引擎），
+//! 所以没有重试、没有镜像展开、没有进度事件——查清单失败就直接把错误抛给发行版回退链，
+//! 让它换下一家（这是 D23「vendor 级失败自动降下一 vendor」的最短路径）。
+
+use super::error::{JavaError, JavaErrorKind};
+
+/// 取一段文本（`what` 是给用户看的名词，例如「华为云 openjdk 目录」）。
+///
+/// # Errors
+///
+/// 连不上 / 超时 → [`JavaErrorKind::Network`]；404 或 410 → [`JavaErrorKind::Metadata`]
+/// （「这个东西上游没有」比「网络坏了」更准确，回退链据此换 vendor 而不是重试同一条）。
+pub async fn get_text(
+    client: &reqwest::Client,
+    url: &str,
+    what: &str,
+) -> Result<String, JavaError> {
+    let response = client.get(url).send().await.map_err(|error| {
+        JavaError::new(
+            JavaErrorKind::Network,
+            format!("取 {what} 失败：{error}（{url}）"),
+        )
+    })?;
+    let status = response.status();
+    if status == reqwest::StatusCode::NOT_FOUND || status == reqwest::StatusCode::GONE {
+        return Err(JavaError::new(
+            JavaErrorKind::Metadata,
+            format!("{what} 不存在（HTTP {status}）：{url}"),
+        ));
+    }
+    if !status.is_success() {
+        return Err(JavaError::new(
+            JavaErrorKind::Network,
+            format!("{what} 返回 HTTP {status}：{url}"),
+        ));
+    }
+    let content_type = response
+        .headers()
+        .get(reqwest::header::CONTENT_TYPE)
+        .and_then(|value| value.to_str().ok())
+        .unwrap_or_default()
+        .to_string();
+    let body = response.text().await.map_err(|error| {
+        JavaError::new(
+            JavaErrorKind::Network,
+            format!("读 {what} 响应失败：{error}"),
+        )
+    })?;
+    // 门户兜底页会把「路径不存在」伪装成 200 + HTML；版本清单页面本身可能也是 HTML，
+    // 所以这里不做内容判定，只看调用方能不能解析出来（解析失败会给出更准的原因）。
+    if body.trim().is_empty() {
+        return Err(JavaError::new(
+            JavaErrorKind::Metadata,
+            format!("{what} 返回空响应（Content-Type: {content_type}）：{url}"),
+        ));
+    }
+    Ok(body)
+}
diff --git a/crates/core/src/game/java/oracle.rs b/crates/core/src/game/java/oracle.rs
new file mode 100644
index 0000000..08530f8
--- /dev/null
+++ b/crates/core/src/game/java/oracle.rs
@@ -0,0 +1,344 @@
+//! Oracle OpenJDK（`download.java.net` GA）：**枚举与下载都走国内镜像目录页**。
+//!
+//! 为什么不能像 Temurin 那样「先拿官方链接、再反解镜像路径」：Oracle 的直链里有一整段
+//! 构建哈希（`/GA/jdk21.0.2/f2283984656d49d69e91c558476027ac/13/GPL/openjdk-21.0.2_windows-x64_bin.zip`），
+//! 那段**不可推导**（research/06 §4.1 实测）。于是本模块的纪律是：
+//!
+//! > 候选 URL 的 `{ver}` 段与文件名段都必须来自对镜像目录页的解析（`parse_links`），
+//! > 代码里没有任何一处把哈希段拼出来。
+//!
+//! 目录形状（华为云 / 南大与官方完全同构，§4.2）：
+//!
+//! ```text
+//! {base}/                      → Apache 列表页：21/ 21.0.1/ 21.0.2/ 27.0.1.0.3/ …
+//! {base}/{ver}/                → 文件列表：openjdk-21.0.2_windows-x64_bin.zip …
+//! {base}/{ver}/{filename}      → 归档本体（大小与官方逐字节一致）
+//! {base}/{ver}/{filename}.sha256 → 64 位哈希纯文本（成对提供）
+//! ```
+//!
+//! 三处实测坑（都写进了实现）：
+//!
+//! 1. **华为云对任意不存在的路径都回 200 + 12 434 B 门户 HTML**（假阳性）——所以本模块只信
+//!    「目录页里真的出现了这个文件名」，不信状态码；下载侧另有 `download::http::html_mirror_reason`
+//!    兜一层（Content-Type 非 HTML + Content-Length 对拍）。
+//! 2. **只发「首个 GA + ≤2 个 update」**：21 线最高只到 21.0.2，别当补丁源用。
+//! 3. **目录页给的大小是四舍五入的**（`192 MB`）→ 不可当 `expected_size`，本模块一律填 0，
+//!    校验交给成对的 `.sha256`。
+
+use super::error::{JavaError, JavaErrorKind};
+use super::net;
+use super::release::{parse_sha256_text, JdkArchive, JdkRelease};
+use super::target::AdoptiumTarget;
+use super::vendor::JdkVendor;
+use crate::download::MirrorTable;
+
+/// Oracle 的 os 段（Adoptium 的 `mac` 在 Oracle 里叫 `macos`）。
+#[must_use]
+pub fn oracle_os(target: AdoptiumTarget) -> &'static str {
+    match target.os {
+        "mac" => "macos",
+        other => other,
+    }
+}
+
+/// Oracle 的 arch 段（`x86-32` → `x86`）。
+#[must_use]
+pub fn oracle_arch(target: AdoptiumTarget) -> &'static str {
+    match target.arch {
+        "x86-32" => "x86",
+        other => other,
+    }
+}
+
+/// 目录页 → 本级条目名列表（去掉尾部 `/`、跳过 `../` 与绝对链接，去重保序）。
+#[must_use]
+pub fn parse_links(html: &str) -> Vec<String> {
+    let mut out: Vec<String> = Vec::new();
+    let mut rest = html;
+    while let Some(start) = rest.find("href=\"") {
+        let after = &rest[start + "href=\"".len()..];
+        let Some(end) = after.find('"') else {
+            break;
+        };
+        let value = after[..end].trim();
+        rest = &after[end..];
+        if value.is_empty()
+            || value.starts_with("http")
+            || value.starts_with("//")
+            || value.starts_with('?')
+            || value.contains('#')
+        {
+            continue;
+        }
+        let name = value.trim_end_matches('/');
+        let Some(name) = name.rsplit('/').next() else {
+            continue;
+        };
+        if name.is_empty() || name == "." || name == ".." {
+            continue;
+        }
+        if !out.iter().any(|known| known == name) {
+            out.push(name.to_string());
+        }
+    }
+    out
+}
+
+/// 版本串 → 可比较的数字段（`21.0.2` → `[21, 0, 2]`，`27.0.1.0.3` → `[27,0,1,0,3]`）。
+#[must_use]
+pub fn version_key(version: &str) -> Option<Vec<u64>> {
+    let mut parts = Vec::new();
+    for segment in version.split('.') {
+        parts.push(segment.parse::<u64>().ok()?);
+    }
+    (!parts.is_empty()).then_some(parts)
+}
+
+/// 目录页里属于 `major` 的版本串，按版本**降序**（最新在前）。
+#[must_use]
+pub fn versions_for(html: &str, major: u32) -> Vec<String> {
+    let mut found: Vec<(Vec<u64>, String)> = parse_links(html)
+        .into_iter()
+        .filter_map(|name| {
+            let key = version_key(&name)?;
+            (key.first() == Some(&u64::from(major))).then_some((key, name))
+        })
+        .collect();
+    found.sort_by(|left, right| right.0.cmp(&left.0));
+    found.into_iter().map(|(_, name)| name).collect()
+}
+
+/// 取 `major` 线的最新 GA 版本串。
+#[must_use]
+pub fn pick_version(html: &str, major: u32) -> Option<String> {
+    versions_for(html, major).into_iter().next()
+}
+
+/// 期望文件名（Oracle 的命名是**模板**，哈希只在目录层级上，不在文件名里）。
+#[must_use]
+pub fn archive_name(version: &str, target: AdoptiumTarget) -> String {
+    format!(
+        "openjdk-{version}_{}-{}_bin.{}",
+        oracle_os(target),
+        oracle_arch(target),
+        target.archive_ext()
+    )
+}
+
+/// `{base}/{ver}/{filename}`。
+#[must_use]
+pub fn archive_url(base: &str, version: &str, filename: &str) -> String {
+    format!("{}/{version}/{filename}", base.trim_end_matches('/'))
+}
+
+/// 归档旁的 `.sha256` 地址。
+#[must_use]
+pub fn checksum_url(base: &str, version: &str, filename: &str) -> String {
+    format!("{}.sha256", archive_url(base, version, filename))
+}
+
+/// 目录页里是否有这个文件（**唯一**的「存在」判据：不信状态码）。
+#[must_use]
+pub fn find_archive(html: &str, filename: &str) -> bool {
+    parse_links(html).iter().any(|name| name == filename)
+}
+
+/// 查一次「某大版本的最新 Oracle OpenJDK GA」。
+///
+/// 按 `mirrors.json` 里 `oracle_openjdk` 的启用顺序逐个镜像试（国内：华为云 → 南大），
+/// 每个镜像三跳：目录页 → 版本目录页 → `.sha256`。任何一跳失败就记下原因换下一个镜像。
+///
+/// # Errors
+///
+/// 所有镜像都失败（没有该大版本 / 目录页不可解析 / 缺 sha256）时返回错误，
+/// 由回退链决定降级到下一家发行版。
+pub async fn fetch_latest(
+    client: &reqwest::Client,
+    table: &MirrorTable,
+    major: u32,
+    target: AdoptiumTarget,
+) -> Result<JdkRelease, JavaError> {
+    let mirrors: Vec<_> = table.oracle_mirrors().collect();
+    if mirrors.is_empty() {
+        return Err(JavaError::new(
+            JavaErrorKind::Metadata,
+            "镜像清单里没有启用的 oracle_openjdk 源",
+        )
+        .with_hint("`mirrors.json` 的 `oracle_openjdk` 表需要至少一个 enabled 条目"));
+    }
+    let mut reasons: Vec<String> = Vec::new();
+    for mirror in mirrors {
+        match fetch_from(client, mirror.base(), major, target).await {
+            Ok(release) => return Ok(release),
+            Err(error) => reasons.push(format!("{}：{}", mirror.name, error.message())),
+        }
+    }
+    Err(JavaError::new(
+        JavaErrorKind::Network,
+        format!(
+            "Oracle OpenJDK {major} 在所有镜像上都取不到：{}",
+            reasons.join("；")
+        ),
+    )
+    .with_hint("Oracle 的 21 线只到 21.0.2（只发首个 GA + ≤2 update）；换 17/25 或改用 temurin"))
+}
+
+/// 单个镜像的完整三跳查询。
+async fn fetch_from(
+    client: &reqwest::Client,
+    base: &str,
+    major: u32,
+    target: AdoptiumTarget,
+) -> Result<JdkRelease, JavaError> {
+    let index = net::get_text(
+        client,
+        &format!("{}/", base.trim_end_matches('/')),
+        "Oracle 镜像根目录",
+    )
+    .await?;
+    let version = pick_version(&index, major).ok_or_else(|| {
+        JavaError::new(
+            JavaErrorKind::Metadata,
+            format!(
+                "镜像目录里没有 {major} 线的 Oracle OpenJDK（目录页 {} 项）",
+                parse_links(&index).len()
+            ),
+        )
+    })?;
+    let filename = archive_name(&version, target);
+    let listing = net::get_text(
+        client,
+        &format!("{}/{version}/", base.trim_end_matches('/')),
+        "Oracle 版本目录",
+    )
+    .await?;
+    if !find_archive(&listing, &filename) {
+        return Err(JavaError::new(
+            JavaErrorKind::Metadata,
+            format!("{version} 目录里没有 {filename}（该平台没有产物，或目录页不可解析）"),
+        ));
+    }
+    let sha_text = net::get_text(
+        client,
+        &checksum_url(base, &version, &filename),
+        "Oracle 归档 sha256",
+    )
+    .await?;
+    let sha256 = parse_sha256_text(&sha_text).ok_or_else(|| {
+        JavaError::new(
+            JavaErrorKind::Integrity,
+            format!("{filename} 的 .sha256 不是 64 位十六进制"),
+        )
+    })?;
+    Ok(JdkRelease {
+        vendor: JdkVendor::Oracle,
+        major,
+        version: version.clone(),
+        semver: None,
+        release_name: version.clone(),
+        archive: JdkArchive {
+            name: filename.clone(),
+            url: archive_url(base, &version, &filename),
+            sha256,
+            // 目录页给的是四舍五入的大小（192 MB），不能当 expected_size。
+            size: 0,
+        },
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{
+        archive_name, archive_url, checksum_url, find_archive, oracle_os, parse_links,
+        pick_version, version_key, versions_for,
+    };
+    use crate::game::java::target::AdoptiumTarget;
+
+    /// 华为云 `/openjdk/` 的真实目录页片段（2026-10-30 抓取，`<pre>` 列表）。
+    const INDEX: &str = r#"<html><body><pre>Name         Last modified     Size</pre><hr><pre>
+<a href="10/" onclick="handleLinkUrl(this)">10/</a>          22-Aug-2021 15:18 -
+<a href="17.0.2/" onclick="handleLinkUrl(this)">17.0.2/</a>      22-Aug-2021 15:19 -
+<a href="21/" onclick="handleLinkUrl(this)">21/</a>          22-Aug-2021 15:19 -
+<a href="21.0.1/" onclick="handleLinkUrl(this)">21.0.1/</a>      22-Aug-2021 15:19 -
+<a href="21.0.2/" onclick="handleLinkUrl(this)">21.0.2/</a>      06-Jan-2024 15:26 -
+<a href="27.0.1.0.3/" onclick="handleLinkUrl(this)">27.0.1.0.3/</a> 06-Jan-2026 15:26 -
+<a href="../" onclick="handleLinkUrl(this)">../</a>
+</pre></body></html>"#;
+
+    /// 华为云 `/openjdk/21.0.2/` 的真实文件列表片段。
+    const LISTING: &str = r#"<html><body><pre><a href="../">../</a>
+<a href="openjdk-21.0.2_linux-x64_bin.tar.gz" onclick="handleLinkUrl(this)">openjdk-21.0.2_linux-x64_bin.tar.gz</a> 194.18 MB
+<a href="openjdk-21.0.2_windows-x64_bin.zip" onclick="handleLinkUrl(this)">openjdk-21.0.2_windows-x64_bin.zip</a> 192 MB
+</pre></body></html>"#;
+
+    const WINDOWS: AdoptiumTarget = AdoptiumTarget::new("windows", "x64");
+
+    #[test]
+    fn directory_links_are_scraped_without_any_hash_segment() {
+        let links = parse_links(INDEX);
+        assert!(links.contains(&"21.0.2".to_string()));
+        assert!(!links.iter().any(|name| name == ".."));
+        // Oracle 直链里的构建哈希（f2283984656d49d69e91c558476027ac）在镜像目录里根本不存在：
+        // 目录层级只有 `{ver}/`，所以实现里没有任何拼哈希的位置。
+        assert!(!links.iter().any(|name| name.len() == 32));
+    }
+
+    #[test]
+    fn newest_version_of_a_line_wins_and_ordering_is_numeric() {
+        assert_eq!(
+            versions_for(INDEX, 21),
+            vec!["21.0.2".to_string(), "21.0.1".to_string(), "21".to_string()]
+        );
+        assert_eq!(pick_version(INDEX, 21).as_deref(), Some("21.0.2"));
+        // 27.0.1.0.3 是四段+，比 27.0.1 新（字符串比较会得出相反结论）。
+        assert_eq!(version_key("27.0.1.0.3"), Some(vec![27, 0, 1, 0, 3]));
+        assert_eq!(version_key("27.0.1"), Some(vec![27, 0, 1]));
+        assert!(version_key("27.0.1") < version_key("27.0.1.0.3"));
+        assert_eq!(pick_version(INDEX, 8), None);
+    }
+
+    #[test]
+    fn filename_template_matches_the_archive_on_every_platform() {
+        assert_eq!(
+            archive_name("21.0.2", WINDOWS),
+            "openjdk-21.0.2_windows-x64_bin.zip"
+        );
+        assert_eq!(
+            archive_name("21.0.2", AdoptiumTarget::new("linux", "aarch64")),
+            "openjdk-21.0.2_linux-aarch64_bin.tar.gz"
+        );
+        assert_eq!(
+            archive_name("17.0.2", AdoptiumTarget::new("mac", "x64")),
+            "openjdk-17.0.2_macos-x64_bin.tar.gz"
+        );
+        assert_eq!(oracle_os(AdoptiumTarget::new("mac", "x64")), "macos");
+        assert_eq!(oracle_os(WINDOWS), "windows");
+    }
+
+    #[test]
+    fn archive_is_only_published_when_it_really_appears_in_the_listing() {
+        let filename = archive_name("21.0.2", WINDOWS);
+        assert!(find_archive(LISTING, &filename));
+        // 华为云的门户兜底页（任意路径 200 + HTML）里没有这个链接 → 必须判为不存在。
+        assert!(!find_archive(
+            "<html><body>mirrors 门户</body></html>",
+            &filename
+        ));
+        assert_eq!(
+            archive_url(
+                "https://mirrors.huaweicloud.com/openjdk/",
+                "21.0.2",
+                &filename
+            ),
+            format!("https://mirrors.huaweicloud.com/openjdk/21.0.2/{filename}")
+        );
+        assert_eq!(
+            checksum_url(
+                "https://mirrors.huaweicloud.com/openjdk",
+                "21.0.2",
+                &filename
+            ),
+            format!("https://mirrors.huaweicloud.com/openjdk/21.0.2/{filename}.sha256")
+        );
+    }
+}
diff --git a/crates/core/src/game/java/probe.rs b/crates/core/src/game/java/probe.rs
new file mode 100644
index 0000000..5dee6eb
--- /dev/null
+++ b/crates/core/src/game/java/probe.rs
@@ -0,0 +1,370 @@
+//! Java 运行时探测：跑一次 `java -version`、扫托管目录、列系统候选。
+//!
+//! 探测动作只有两种：读托管目录（`.ULL/data/java-managed/jdk-<major>-<vendor>/`）
+//! 与跑 `java -version`（输出在 stderr，主版本号从引号里的版本号解析，
+//! `1.8.0_402` 这种老形态换算成 8）。
+//!
+//! 「选哪个 Java 启动」不在这里，而在 [`super::select`]——那边是**纯函数**，
+//! 候选运行时由调用方注入，测试因此不需要真的装三个 JDK。
+
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+use super::extract::{java_binary_name, read_stamp};
+use super::vendor::JdkVendor;
+
+/// 缺省 Java 主版本（探测不到任何东西时的保守值，D13：JDK 17 基准）。
+pub const DEFAULT_MAJOR: u32 = 17;
+
+/// 托管目录名前缀。
+pub const MANAGED_PREFIX: &str = "jdk-";
+
+/// 一个 Java 运行时的来源。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub enum JavaOrigin {
+    /// 实例覆盖（`--java` 参数或实例档案的 `javaPath`）。
+    Instance,
+    /// 托管目录（`ull java install` 装的）。
+    Managed,
+    /// `JAVA_HOME`。
+    JavaHome,
+    /// `PATH` 上的 `java`。
+    Path,
+    /// 标准安装位置扫出来的（MSI 装的 Temurin / 官方启动器的 `runtime/` / 注册表等）。
+    System,
+}
+
+impl JavaOrigin {
+    /// 稳定字符串 id（`--json` 的 `source` 字段）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Instance => "instance",
+            Self::Managed => "managed",
+            Self::JavaHome => "JAVA_HOME",
+            Self::Path => "PATH",
+            Self::System => "system",
+        }
+    }
+
+    /// 展示类别（`--json` 的 `source_category`）：GUI 用它分组，不必区分 `JAVA_HOME`/`PATH`。
+    #[must_use]
+    pub const fn category(self) -> &'static str {
+        match self {
+            Self::Instance => "instance",
+            Self::Managed => "managed",
+            Self::JavaHome | Self::Path => "env",
+            Self::System => "system",
+        }
+    }
+
+    /// 同档内的优先序（小者优先）。
+    ///
+    /// 「环境变量」先于「扫盘」：用户显式设过的 `JAVA_HOME`/`PATH` 是意图表达，
+    /// 盘上扫出来的只是候选（HMCL/PCL 也是这个顺序）。
+    #[must_use]
+    pub const fn rank(self) -> u8 {
+        match self {
+            Self::Instance => 0,
+            Self::Managed => 1,
+            Self::JavaHome => 2,
+            Self::Path => 3,
+            Self::System => 4,
+        }
+    }
+}
+
+/// 一个探测到的 Java 运行时。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct JavaRuntime {
+    /// 可执行文件。
+    pub binary: PathBuf,
+    /// 来源。
+    pub origin: JavaOrigin,
+    /// `java -version` 的首行（含 `version` 字样）。
+    pub version: Option<String>,
+    /// 主版本号（`1.8.0_402` → 8）。
+    pub major: Option<u32>,
+    /// 位数（32 / 64；探测不到时按宿主）。
+    pub bits: u32,
+    /// 托管目录里的供应商（`temurin`）；其它来源为 `None`。
+    pub vendor: Option<String>,
+}
+
+impl JavaRuntime {
+    /// 探测不出来时给个「版本未知」的占位。
+    #[must_use]
+    pub fn unknown(binary: impl Into<PathBuf>, origin: JavaOrigin) -> Self {
+        Self {
+            binary: binary.into(),
+            origin,
+            version: None,
+            major: None,
+            bits: host_bits(),
+            vendor: None,
+        }
+    }
+
+    /// 主版本号（未知时退回 [`DEFAULT_MAJOR`]）。
+    #[must_use]
+    pub fn major_or_default(&self) -> u32 {
+        self.major.unwrap_or(DEFAULT_MAJOR)
+    }
+}
+
+/// 跑一次 `java -version` 填满运行时信息（探测失败不报错，只留空字段）。
+///
+/// 失败不报错的理由：`ull java list` 要能列出「探测不到的项」而不是整体失败，
+/// 而启动路径上探测失败会自然退化为系统默认 Java（见 [`super::select::resolve`]）。
+#[must_use]
+pub fn probe(binary: &Path, origin: JavaOrigin) -> JavaRuntime {
+    let mut runtime = JavaRuntime::unknown(binary.to_path_buf(), origin);
+    let Ok(output) = Command::new(binary).arg("-version").output() else {
+        return runtime;
+    };
+    let mut text = String::from_utf8_lossy(&output.stderr).into_owned();
+    text.push_str(&String::from_utf8_lossy(&output.stdout));
+    if let Some((line, major)) = parse_version_output(&text) {
+        runtime.major = Some(major);
+        runtime.version = Some(line);
+        runtime.bits = bits_of(&text);
+    }
+    runtime
+}
+
+/// 扫描一个安装根里的托管 JDK，逐个探测。
+///
+/// **两种布局都要认**（D23 之后同时存在）：
+///
+/// ```text
+/// <root>/jdk-<major>-<vendor>/bin/java      Portable（v1 布局，M33 定下，永不改）
+/// <root>/<vendor>/<version>/bin/java        Standard / Custom（D23 的 <发行方>/<版本>）
+/// ```
+///
+/// 只认带戳记的目录：托管区是我们自己写的地方，但没有戳记的子目录可能是用户塞进来的
+/// 别的东西，不去猜它。`major` 一律以 `java -version` 为准（戳记只用于幂等判定）。
+#[must_use]
+pub fn discover_managed(managed_root: &Path) -> Vec<JavaRuntime> {
+    let mut found: Vec<JavaRuntime> = Vec::new();
+    let Ok(entries) = std::fs::read_dir(managed_root) else {
+        return found;
+    };
+    for entry in entries.flatten() {
+        let path = entry.path();
+        let name = entry.file_name().to_string_lossy().into_owned();
+        if !path.is_dir() || name.starts_with('.') {
+            continue;
+        }
+        if let Some(runtime) = probe_managed_dir(&path, parse_managed_dir(&name).map(|(_, v)| v)) {
+            found.push(runtime);
+            continue;
+        }
+        // 两层布局：`<vendor>/<version>`——vendor 名取自父目录名。
+        if JdkVendor::parse(&name).is_some() {
+            let Ok(children) = std::fs::read_dir(&path) else {
+                continue;
+            };
+            for child in children.flatten() {
+                let child_path = child.path();
+                if let Some(runtime) = probe_managed_dir(&child_path, Some(&name)) {
+                    found.push(runtime);
+                }
+            }
+        }
+    }
+    sort_runtimes(&mut found);
+    found
+}
+
+/// 扫多个安装根（Portable 数据根 + Standard/Custom 落点），按 `bin` 路径去重。
+#[must_use]
+pub fn discover_managed_roots(roots: &[PathBuf]) -> Vec<JavaRuntime> {
+    let mut found: Vec<JavaRuntime> = Vec::new();
+    for root in roots {
+        for runtime in discover_managed(root) {
+            if !found.iter().any(|known| known.binary == runtime.binary) {
+                found.push(runtime);
+            }
+        }
+    }
+    sort_runtimes(&mut found);
+    found
+}
+
+/// 探测一个候选托管目录（有戳记 + `bin/java` 才算数）。
+fn probe_managed_dir(path: &Path, vendor: Option<&str>) -> Option<JavaRuntime> {
+    if !path.is_dir() || read_stamp(path).is_none() {
+        return None;
+    }
+    let binary = path.join("bin").join(java_binary_name());
+    if !binary.is_file() {
+        return None;
+    }
+    let mut runtime = probe(&binary, JavaOrigin::Managed);
+    runtime.vendor = vendor.map(str::to_string);
+    Some(runtime)
+}
+
+/// 大版本升序，输出稳定（同 major 按路径）。
+fn sort_runtimes(found: &mut [JavaRuntime]) {
+    found.sort_by(|left, right| {
+        left.major
+            .cmp(&right.major)
+            .then_with(|| left.binary.cmp(&right.binary))
+    });
+}
+
+/// 系统来源的候选：`JAVA_HOME` 与 `PATH` 上的 `java`（都探测一次）。
+///
+/// `PATH` 上的那一项会先**解析成绝对路径**再探测：否则它与扫盘结果（绝对路径）看起来是
+/// 两个不同的文件，`java list` 会把同一个 JDK 列两次。
+#[must_use]
+pub fn system_candidates() -> Vec<JavaRuntime> {
+    let mut found = Vec::new();
+    if let Some(home) = std::env::var_os("JAVA_HOME") {
+        let binary = PathBuf::from(home).join("bin").join(java_binary_name());
+        if binary.is_file() {
+            found.push(probe(&binary, JavaOrigin::JavaHome));
+        }
+    }
+    let name = java_binary_name();
+    let binary = resolve_on_path(name).unwrap_or_else(|| PathBuf::from(name));
+    found.push(probe(&binary, JavaOrigin::Path));
+    found
+}
+
+/// 在 `PATH` 里找某个可执行文件的绝对路径（找不到返回 `None`）。
+#[must_use]
+pub fn resolve_on_path(name: &str) -> Option<PathBuf> {
+    let path = std::env::var_os("PATH")?;
+    std::env::split_paths(&path)
+        .map(|dir| dir.join(name))
+        .find(|candidate| candidate.is_file())
+}
+
+/// 托管目录名（`jdk-21-temurin`）。
+#[must_use]
+pub fn managed_dir_name(major: u32, vendor: &str) -> String {
+    format!("{MANAGED_PREFIX}{major}-{vendor}")
+}
+
+/// 反解托管目录名 →（大版本，供应商）。
+#[must_use]
+pub fn parse_managed_dir(name: &str) -> Option<(u32, &str)> {
+    let rest = name.strip_prefix(MANAGED_PREFIX)?;
+    let (major, vendor) = rest.split_once('-')?;
+    let major: u32 = major.parse().ok()?;
+    (!vendor.is_empty()).then_some((major, vendor))
+}
+
+/// 从 `java -version` 输出里取（含 `version` 的首行，主版本号）。
+#[must_use]
+pub fn parse_version_output(text: &str) -> Option<(String, u32)> {
+    let line = text
+        .lines()
+        .find(|line| line.contains("version"))
+        .or_else(|| text.lines().find(|line| !line.trim().is_empty()))?
+        .trim();
+    let version = quoted_version(line).or_else(|| bare_version(line))?;
+    let major = major_of(&version)?;
+    Some((line.to_string(), major))
+}
+
+/// 引号里的版本号（`openjdk version "21.0.13" 2026-01-20 LTS`）。
+fn quoted_version(line: &str) -> Option<String> {
+    let start = line.find('"')? + 1;
+    let rest = &line[start..];
+    let end = rest.find('"')?;
+    Some(rest[..end].to_string())
+}
+
+/// 无引号形态（`openjdk 25.0.3 2026-04-21`）。
+///
+/// 「含 `version` 的那一段之后逐个试」优先——避开 `Java(TM) SE Runtime` 这类噪声；
+/// 没有 `version` 字样时从头试（部分精简发行版就这么打印）。
+fn bare_version(line: &str) -> Option<String> {
+    let tokens: Vec<&str> = line.split_whitespace().collect();
+    let start = tokens
+        .iter()
+        .position(|token| token.contains("version"))
+        .map_or(0, |position| position + 1);
+    tokens[start..].iter().find_map(|token| {
+        let candidate = token.trim_matches(['"', ',', '(', ')']);
+        (candidate.contains('.') && major_of(candidate).is_some()).then(|| candidate.to_string())
+    })
+}
+
+/// 版本号 → 主版本（`1.8.0_402` → 8，`21.0.13` → 21）。
+#[must_use]
+pub fn major_of(version: &str) -> Option<u32> {
+    let mut parts = version.split(['.', '_', '-']);
+    let first = parts.next()?.parse::<u32>().ok()?;
+    if first == 1 {
+        parts.next()?.parse::<u32>().ok()
+    } else {
+        Some(first)
+    }
+}
+
+/// `java -version` 输出里的位数（`64-Bit` / `32-Bit`；读不到按宿主）。
+#[must_use]
+pub fn bits_of(text: &str) -> u32 {
+    let lowered = text.to_ascii_lowercase();
+    if lowered.contains("64-bit") {
+        64
+    } else if lowered.contains("32-bit") {
+        32
+    } else {
+        host_bits()
+    }
+}
+
+/// 宿主指针宽度（32 / 64）。
+#[must_use]
+pub const fn host_bits() -> u32 {
+    if cfg!(target_pointer_width = "64") {
+        64
+    } else {
+        32
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{bits_of, major_of, managed_dir_name, parse_managed_dir, parse_version_output};
+
+    #[test]
+    fn parses_modern_and_legacy_version_lines() {
+        let modern =
+            parse_version_output("openjdk version \"21.0.13\" 2026-01-20 LTS\nOpenJDK 64-Bit");
+        assert_eq!(modern.map(|(_, major)| major), Some(21));
+        let legacy = parse_version_output("java version \"1.8.0_402\"\nJava(TM) SE Runtime");
+        assert_eq!(legacy.map(|(_, major)| major), Some(8));
+        let bare = parse_version_output("openjdk 25.0.3 2026-04-21\nOpenJDK 64-Bit Server VM");
+        assert_eq!(bare.map(|(_, major)| major), Some(25));
+        assert!(parse_version_output("no java here").is_none());
+    }
+
+    #[test]
+    fn parses_bit_width() {
+        assert_eq!(bits_of("OpenJDK 64-Bit Server VM (build 25.0.3)"), 64);
+        assert_eq!(bits_of("Java HotSpot(TM) Client VM (32-Bit)"), 32);
+    }
+
+    #[test]
+    fn major_of_handles_legacy_scheme() {
+        assert_eq!(major_of("1.8.0_402"), Some(8));
+        assert_eq!(major_of("17.0.13+11"), Some(17));
+        assert_eq!(major_of("not-a-version"), None);
+    }
+
+    #[test]
+    fn managed_dir_names_round_trip() {
+        assert_eq!(parse_managed_dir("jdk-21-temurin"), Some((21, "temurin")));
+        assert_eq!(parse_managed_dir("jdk-8-temurin"), Some((8, "temurin")));
+        assert_eq!(parse_managed_dir(".staging-jdk-21-temurin"), None);
+        assert_eq!(parse_managed_dir("java-21-temurin"), None);
+        assert_eq!(parse_managed_dir("jdk-x-temurin"), None);
+        assert_eq!(managed_dir_name(25, "temurin"), "jdk-25-temurin");
+    }
+}
diff --git a/crates/core/src/game/java/release.rs b/crates/core/src/game/java/release.rs
new file mode 100644
index 0000000..8e80ec3
--- /dev/null
+++ b/crates/core/src/game/java/release.rs
@@ -0,0 +1,170 @@
+//! 一次版本查询的统一产物：一个可下载的 JDK 归档（四家发行版共用形态）。
+//!
+//! 各家的**版本号语义不同**（research/06 §5.3 第 3 条），所以这里只存「vendor 原生的版本串」
+//! 而不是硬拆成 semver 四段：
+//!
+//! | 发行版 | 版本串 | 出处 |
+//! | --- | --- | --- |
+//! | Temurin | `21.0.13+9`（三段+构建号） | Adoptium `release_name` |
+//! | Oracle OpenJDK | `21.0.2`（三段，只到 GA + ≤2 update） | 镜像目录名 |
+//! | Microsoft OpenJDK | `21.0.13.0.2`（四段/五段），11 线是 `11.0.32.1` | `aka.ms` 文件名 |
+//! | Azul Zulu | `21.0.13+3`（三段+构建号，文件名里还有 `21.0.13.0.3` 另一种写法） | Zulu API |
+//!
+//! 目录名、戳记、`--json` 都直接用这个串（`location::sanitize_version` 只做字符白名单）。
+
+use super::vendor::JdkVendor;
+
+/// 一个可下载的 JDK 归档。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct JdkArchive {
+    /// 产物文件名（`OpenJDK21U-jdk_x64_windows_hotspot_21.0.13_9.zip`）。
+    pub name: String,
+    /// 官方下载链接（镜像展开的输入；Oracle / MS / Zulu 已经是最终链接）。
+    pub url: String,
+    /// SHA-256（小写十六进制）。
+    pub sha256: String,
+    /// 字节数（`0` = 上游没给可信大小，引擎跳过长度对拍只验哈希）。
+    pub size: u64,
+}
+
+/// 一次版本查询的结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct JdkRelease {
+    /// 发行版。
+    pub vendor: JdkVendor,
+    /// 大版本号（`21`）。
+    pub major: u32,
+    /// vendor 原生的完整版本串（目录名与展示都用它）。
+    pub version: String,
+    /// Temurin 系才有的 semver（其它家为 `None`）。
+    pub semver: Option<String>,
+    /// release 名（Temurin `jdk-21.0.13+9`；其它家用版本串）。
+    pub release_name: String,
+    /// 归档。
+    pub archive: JdkArchive,
+}
+
+impl JdkRelease {
+    /// 是否就是这个发行版 + 大版本的产物。
+    #[must_use]
+    pub fn matches(&self, vendor: JdkVendor, major: u32) -> bool {
+        self.vendor == vendor && self.major == major
+    }
+
+    /// sha256（幂等判据用）。
+    #[must_use]
+    pub fn sha256(&self) -> &str {
+        &self.archive.sha256
+    }
+
+    /// 人读一行（`Temurin 21.0.13+9 · OpenJDK21U-…zip`）。
+    #[must_use]
+    pub fn summary(&self) -> String {
+        format!(
+            "{} {} · {}",
+            self.vendor.display(),
+            self.version,
+            self.archive.name
+        )
+    }
+
+    /// `--json` 的归档块（四家共用一个形状）。
+    #[must_use]
+    pub fn archive_json(&self) -> serde_json::Value {
+        serde_json::json!({
+            "vendor": self.vendor.id(),
+            "version": self.version,
+            "name": self.archive.name,
+            "url": self.archive.url,
+            "sha256": self.archive.sha256,
+            "size": self.archive.size,
+        })
+    }
+}
+
+/// 从 `release_name`（Temurin 的 `jdk-21.0.13+9`）取版本串。
+#[must_use]
+pub fn version_from_release_name(release_name: &str) -> Option<String> {
+    let trimmed = release_name.trim();
+    let stripped = trimmed.strip_prefix("jdk-").unwrap_or(trimmed);
+    (!stripped.is_empty()).then(|| stripped.to_string())
+}
+
+/// 解析 sha256 文本（`.sha256` / `.sha256sum.txt` / 裸哈希都吃），校验 64 位十六进制。
+#[must_use]
+pub fn parse_sha256_text(text: &str) -> Option<String> {
+    for token in text.split_whitespace() {
+        let lowered = token.trim().to_ascii_lowercase();
+        let candidate = lowered.strip_prefix('*').unwrap_or(lowered.as_str());
+        if candidate.len() == 64 && candidate.bytes().all(|byte| byte.is_ascii_hexdigit()) {
+            return Some(candidate.to_string());
+        }
+    }
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{parse_sha256_text, version_from_release_name, JdkArchive, JdkRelease};
+    use crate::game::java::vendor::JdkVendor;
+
+    fn release() -> JdkRelease {
+        JdkRelease {
+            vendor: JdkVendor::Oracle,
+            major: 21,
+            version: "21.0.2".to_string(),
+            semver: None,
+            release_name: "21.0.2".to_string(),
+            archive: JdkArchive {
+                name: "openjdk-21.0.2_windows-x64_bin.zip".to_string(),
+                url: "https://mirrors.huaweicloud.com/openjdk/21.0.2/openjdk-21.0.2_windows-x64_bin.zip"
+                    .to_string(),
+                sha256: "b6c17e747ae78cdd6de4d7532b3164b277daee97c007d3eaa2b39cca99882664"
+                    .to_string(),
+                size: 0,
+            },
+        }
+    }
+
+    #[test]
+    fn release_carries_vendor_and_native_version() {
+        let item = release();
+        assert!(item.matches(JdkVendor::Oracle, 21));
+        assert!(!item.matches(JdkVendor::Microsoft, 21));
+        assert!(item.summary().contains("Oracle OpenJDK 21.0.2"));
+        assert_eq!(item.archive_json()["vendor"], "oracle");
+    }
+
+    #[test]
+    fn sha256_texts_from_every_vendor_parse_the_same_way() {
+        // Huawei 的 .sha256：只有 64 位哈希，没有文件名。
+        assert_eq!(
+            parse_sha256_text("b6c17e747ae78cdd6de4d7532b3164b277daee97c007d3eaa2b39cca99882664\n")
+                .as_deref(),
+            Some("b6c17e747ae78cdd6de4d7532b3164b277daee97c007d3eaa2b39cca99882664")
+        );
+        // MS 的 .sha256sum.txt：`<hash>  <filename>`，并且带大写与 CRLF。
+        assert_eq!(
+            parse_sha256_text(
+                "6ECFA864AE0A1B2C3D4E5F60718293A4B5C6D7E8F90A1B2C3D4E5F60718293A4  microsoft-jdk-21.0.13-windows-x64.zip\r\n"
+            )
+            .as_deref(),
+            Some("6ecfa864ae0a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4")
+        );
+        assert_eq!(parse_sha256_text("<html>404</html>"), None);
+        assert_eq!(parse_sha256_text("deadbeef"), None);
+    }
+
+    #[test]
+    fn version_falls_back_to_the_release_name() {
+        assert_eq!(
+            version_from_release_name("jdk-21.0.13+9").as_deref(),
+            Some("21.0.13+9")
+        );
+        assert_eq!(
+            version_from_release_name("21.0.13+9").as_deref(),
+            Some("21.0.13+9")
+        );
+        assert_eq!(version_from_release_name(""), None);
+    }
+}
diff --git a/crates/core/src/game/java/select.rs b/crates/core/src/game/java/select.rs
new file mode 100644
index 0000000..496a0fd
--- /dev/null
+++ b/crates/core/src/game/java/select.rs
@@ -0,0 +1,160 @@
+//! 「启动选哪个 Java」的**纯**优先链（D13）。
+//!
+//! 优先级：实例覆盖（`--java` / 档案 `javaPath`）> 托管目录里**满足要求**的 JDK >
+//! `JAVA_HOME` > `PATH`。实例覆盖由调用方单独判（用户明确指定了就不参与打分），
+//! 这里只处理「一堆已探测的候选 + 一个要求」的挑选。
+//!
+//! 挑选规则（比「机械按来源排序」更贴近用户预期）：
+//!
+//! 1. **满足要求的候选优先**——1.12.2 只能用 Java 8，托管的 21 再新也不能选；
+//! 2. 同档内按来源：托管 > `JAVA_HOME` > `PATH`（D13：托管目录是启动器的地盘，
+//!    用户 PATH 上的 java 可能是另一个 JDK 的残留）；
+//! 3. 全都不满足时仍给一个（按来源优先取最好那个），并报不符——**提示而不是拒绝**。
+//!
+//! 抽成纯函数是为了可测：测试注入「托管 21 + PATH 8」这类组合，不必真装 JDK。
+
+use super::mapping::{check, JavaMismatch, JavaRequirement};
+use super::probe::{JavaRuntime, DEFAULT_MAJOR};
+
+/// 一次启动的 Java 选择结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct JavaResolution {
+    /// 选中的运行时（一个候选都没有时 `None`）。
+    pub runtime: Option<JavaRuntime>,
+    /// 目标版本对 Java 的要求。
+    pub required: JavaRequirement,
+    /// 不符说明（`None` = 满足要求，或压根没探测到 Java）。
+    pub mismatch: Option<JavaMismatch>,
+}
+
+impl JavaResolution {
+    /// 生效的主版本号（没有运行时按缺省值）。
+    #[must_use]
+    pub fn major(&self) -> u32 {
+        self.runtime
+            .as_ref()
+            .map_or(DEFAULT_MAJOR, JavaRuntime::major_or_default)
+    }
+
+    /// 是否满足要求（没有运行时视为「不知道」，返回 `true`）。
+    #[must_use]
+    pub fn is_satisfied(&self) -> bool {
+        self.mismatch.is_none()
+    }
+}
+
+/// 从候选里挑一个：满足要求的优先，同档内按来源优先序。
+#[must_use]
+pub fn pick<'a>(
+    candidates: &'a [JavaRuntime],
+    required: &JavaRequirement,
+) -> Option<&'a JavaRuntime> {
+    candidates.iter().min_by_key(|runtime| {
+        let ok = runtime
+            .major
+            .is_some_and(|major| required.satisfied_by(major));
+        // 先排「不满足」（`ok=false` 的 key 大），再排来源优先序。
+        (!ok, runtime.origin.rank())
+    })
+}
+
+/// 挑 + 判不符。
+#[must_use]
+pub fn resolve(candidates: &[JavaRuntime], required: &JavaRequirement) -> JavaResolution {
+    let runtime = pick(candidates, required).cloned();
+    let mismatch = runtime
+        .as_ref()
+        .and_then(|runtime| runtime.major)
+        .and_then(|major| check(major, required));
+    JavaResolution {
+        runtime,
+        required: required.clone(),
+        mismatch,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::resolve;
+    use crate::game::java::mapping::{JavaRequirement, RequirementSource};
+    use crate::game::java::probe::{JavaOrigin, JavaRuntime, DEFAULT_MAJOR};
+
+    fn runtime(major: u32, origin: JavaOrigin) -> JavaRuntime {
+        JavaRuntime {
+            binary: std::path::PathBuf::from(format!("java{major}")),
+            origin,
+            version: Some(format!("openjdk version \"{major}.0.1\"")),
+            major: Some(major),
+            bits: 64,
+            vendor: None,
+        }
+    }
+
+    fn at_least(minimum: u32) -> JavaRequirement {
+        JavaRequirement::new(minimum, None, RequirementSource::Table)
+    }
+
+    #[test]
+    fn satisfying_managed_runtime_beats_mismatching_system_java() {
+        let candidates = [
+            runtime(8, JavaOrigin::Path),
+            runtime(21, JavaOrigin::Managed),
+        ];
+        let picked = resolve(&candidates, &at_least(17));
+        assert_eq!(picked.major(), 21);
+        assert!(picked.is_satisfied());
+    }
+
+    #[test]
+    fn satisfying_system_java_beats_mismatching_managed() {
+        // 1.12.2 只能 Java 8：托管的 21 不满足，PATH 上的 8 满足 → 选 8。
+        let required = JavaRequirement::new(8, Some(8), RequirementSource::Table);
+        let candidates = [
+            runtime(21, JavaOrigin::Managed),
+            runtime(8, JavaOrigin::Path),
+        ];
+        let picked = resolve(&candidates, &required);
+        assert_eq!(picked.major(), 8);
+        assert!(picked.is_satisfied());
+    }
+
+    #[test]
+    fn managed_wins_when_both_satisfy() {
+        let candidates = [
+            runtime(21, JavaOrigin::Path),
+            runtime(17, JavaOrigin::JavaHome),
+            runtime(17, JavaOrigin::Managed),
+        ];
+        assert_eq!(resolve(&candidates, &at_least(17)).major(), 17);
+    }
+
+    #[test]
+    fn java_home_beats_path_when_both_satisfy() {
+        let candidates = [
+            runtime(21, JavaOrigin::Path),
+            runtime(21, JavaOrigin::JavaHome),
+        ];
+        let picked = resolve(&candidates, &at_least(21));
+        assert_eq!(
+            picked.runtime.map(|runtime| runtime.origin),
+            Some(JavaOrigin::JavaHome)
+        );
+    }
+
+    #[test]
+    fn no_candidate_keeps_the_default_and_reports_no_mismatch() {
+        let picked = resolve(&[], &at_least(21));
+        assert_eq!(picked.major(), DEFAULT_MAJOR);
+        assert!(picked.runtime.is_none());
+        assert!(picked.is_satisfied());
+    }
+
+    #[test]
+    fn mismatch_is_reported_when_nothing_fits() {
+        let candidates = [runtime(8, JavaOrigin::Path)];
+        let picked = resolve(&candidates, &at_least(21));
+        assert_eq!(picked.major(), 8);
+        let mismatch = picked.mismatch.expect("应报不符");
+        assert_eq!(mismatch.code(), "java_too_old");
+    }
+}
diff --git a/crates/core/src/game/java/source.rs b/crates/core/src/game/java/source.rs
new file mode 100644
index 0000000..112691f
--- /dev/null
+++ b/crates/core/src/game/java/source.rs
@@ -0,0 +1,199 @@
+//! 版本查询的发行版分派 + 回退链记录（D23）。
+//!
+//! 两件事：
+//!
+//! 1. [`fetch`]：把一次「某发行版某大版本的最新 GA」查询分派给对应实现——
+//!    Temurin 走 `api.adoptium.net`（v1 既有），Oracle / MS / Zulu 各走自己的源表；
+//! 2. [`ChainLog`]：按用户优先级依次尝试时，**每一跳的结果与降级原因**都记下来。
+//!    这份记录直接进 `--json` 与事件流，是「为什么最后装的是 MS 而不是 Temurin」的唯一解释。
+//!
+//! 回退的粒度是**发行版级**（D23 原话）：版本不存在、镜像全 4xx、校验失败都算这一家失败，
+//! 换下一家；同一家内部的镜像换源（TUNA→官方、华为云→南大）仍然归 `core::download` 引擎管。
+
+use super::api;
+use super::error::JavaError;
+use super::microsoft;
+use super::oracle;
+use super::release::JdkRelease;
+use super::target::AdoptiumTarget;
+use super::vendor::JdkVendor;
+use super::zulu;
+use crate::download::DownloadEngine;
+
+/// 查一次「某发行版某大版本的最新 GA」。
+///
+/// # Errors
+///
+/// 平台无产物、清单不可达、该家没有这个大版本、校验缺失时返回错误——调用方据此降级。
+pub async fn fetch(
+    engine: &DownloadEngine,
+    vendor: JdkVendor,
+    major: u32,
+    target: AdoptiumTarget,
+) -> Result<JdkRelease, JavaError> {
+    let client = engine.client();
+    let table = engine.mirrors();
+    match vendor {
+        JdkVendor::Temurin => api::fetch_latest(client, major, target).await,
+        JdkVendor::Oracle => oracle::fetch_latest(client, table, major, target).await,
+        JdkVendor::Microsoft => {
+            let table = table.microsoft_openjdk().ok_or_else(|| {
+                JavaError::new(
+                    super::error::JavaErrorKind::Metadata,
+                    "镜像清单里没有 microsoft_openjdk 表",
+                )
+                .with_hint("升级 mirrors.json 到 v3，或改用 --vendor temurin")
+            })?;
+            microsoft::fetch_latest(client, table, major, target).await
+        }
+        JdkVendor::Zulu => {
+            let table = table.zulu().ok_or_else(|| {
+                JavaError::new(
+                    super::error::JavaErrorKind::Metadata,
+                    "镜像清单里没有 zulu 表",
+                )
+                .with_hint("升级 mirrors.json 到 v3，或改用 --vendor temurin")
+            })?;
+            zulu::fetch_latest(client, table, major, target).await
+        }
+    }
+}
+
+/// 一跳的结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct VendorAttempt {
+    /// 尝试的发行版。
+    pub vendor: JdkVendor,
+    /// 是否命中（成功拿到可下载的归档）。
+    pub ok: bool,
+    /// 命中/降级的一句话原因（`"命中"` / `"没有 8 的 GA（只发 11/17/21/25）"`）。
+    pub detail: String,
+}
+
+impl VendorAttempt {
+    /// `--json` 形状。
+    #[must_use]
+    pub fn to_json(&self) -> serde_json::Value {
+        serde_json::json!({
+            "vendor": self.vendor.id(),
+            "ok": self.ok,
+            "detail": self.detail,
+        })
+    }
+}
+
+/// 一条回退链的执行记录。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct ChainLog {
+    attempts: Vec<VendorAttempt>,
+}
+
+impl ChainLog {
+    /// 空记录。
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// 记一次「跳过」（该家不支持这个大版本，根本没查网络）。
+    pub fn skip(&mut self, vendor: JdkVendor, detail: impl Into<String>) {
+        self.attempts.push(VendorAttempt {
+            vendor,
+            ok: false,
+            detail: detail.into(),
+        });
+    }
+
+    /// 记一次失败（查到了但拿不到、或下载/校验失败）。
+    pub fn failed(&mut self, vendor: JdkVendor, detail: impl Into<String>) {
+        self.attempts.push(VendorAttempt {
+            vendor,
+            ok: false,
+            detail: detail.into(),
+        });
+    }
+
+    /// 记一次命中。
+    pub fn hit(&mut self, vendor: JdkVendor, detail: impl Into<String>) {
+        self.attempts.push(VendorAttempt {
+            vendor,
+            ok: true,
+            detail: detail.into(),
+        });
+    }
+
+    /// 是否已经命中（命中后不再往下试）。
+    #[must_use]
+    pub fn hit_vendor(&self) -> Option<JdkVendor> {
+        self.attempts
+            .iter()
+            .find(|attempt| attempt.ok)
+            .map(|attempt| attempt.vendor)
+    }
+
+    /// 全部记录。
+    #[must_use]
+    pub fn attempts(&self) -> &[VendorAttempt] {
+        &self.attempts
+    }
+
+    /// 降级说明（「已跳过」的那些；给事件流与人读告警用）。
+    #[must_use]
+    pub fn degradations(&self) -> Vec<String> {
+        self.attempts
+            .iter()
+            .filter(|attempt| !attempt.ok)
+            .map(|attempt| format!("{}：{}", attempt.vendor.id(), attempt.detail))
+            .collect()
+    }
+
+    /// 实际尝试了几家（不含跳过）。
+    #[must_use]
+    pub fn tried(&self) -> usize {
+        self.attempts.len()
+    }
+
+    /// `--json` 形状。
+    #[must_use]
+    pub fn to_json(&self) -> serde_json::Value {
+        serde_json::json!({
+            "hit": self.hit_vendor().map(JdkVendor::id),
+            "attempts": self.attempts.iter().map(VendorAttempt::to_json).collect::<Vec<_>>(),
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::ChainLog;
+    use crate::game::java::vendor::JdkVendor;
+
+    #[test]
+    fn chain_skips_unsupported_majors_and_records_the_reason() {
+        let mut log = ChainLog::new();
+        log.skip(JdkVendor::Oracle, "不支持 8（Oracle archive 从 9 起）");
+        log.skip(JdkVendor::Microsoft, "没有 8 的 GA（只发 11/17/21/25）");
+        log.hit(JdkVendor::Temurin, "命中 8.0.504+1");
+        assert_eq!(log.hit_vendor(), Some(JdkVendor::Temurin));
+        let degradations = log.degradations();
+        assert_eq!(degradations.len(), 2);
+        assert!(degradations[1].contains("microsoft"));
+        assert_eq!(log.attempts().len(), 3);
+        let json = log.to_json();
+        assert_eq!(json["hit"], "temurin");
+        assert_eq!(json["attempts"][0]["vendor"], "oracle");
+    }
+
+    #[test]
+    fn failure_reasons_are_kept_for_the_event_stream() {
+        let mut log = ChainLog::new();
+        log.failed(JdkVendor::Temurin, "所有镜像都 4xx");
+        log.hit(JdkVendor::Oracle, "命中 21.0.2");
+        assert_eq!(
+            log.degradations(),
+            vec!["temurin：所有镜像都 4xx".to_string()],
+            "降级原因必须原样可读（用户要能看懂为什么换了发行版）"
+        );
+        assert_eq!(log.tried(), 2);
+    }
+}
diff --git a/crates/core/src/game/java/target.rs b/crates/core/src/game/java/target.rs
new file mode 100644
index 0000000..29fe094
--- /dev/null
+++ b/crates/core/src/game/java/target.rs
@@ -0,0 +1,85 @@
+//! 宿主平台 → Adoptium 请求参数，以及归档形态（Win = zip，Linux/mac = tar.gz）。
+//!
+//! Adoptium 的 `os` / `arch` 取值与 Rust 的 `target_os` / `target_arch` 不同形
+//! （`windows`/`mac`/`linux` × `x64`/`aarch64`/`x86-32`……），这里做唯一一次翻译。
+//! 平台差异仍然按项目纪律收敛在 `core::platform` 的语义里，本文件只做**命名映射**，
+//! 不写任何能力探测。
+
+use super::error::{JavaError, JavaErrorKind};
+
+/// 一次 Adoptium 请求的目标。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct AdoptiumTarget {
+    /// Adoptium 的 `os` 段（`windows` / `linux` / `mac`）。
+    pub os: &'static str,
+    /// Adoptium 的 `arch` 段（`x64` / `aarch64` / `x86-32` …）。
+    pub arch: &'static str,
+}
+
+impl AdoptiumTarget {
+    /// 宿主平台（不认识的架构直接拒绝，不猜一个错的产物下来）。
+    ///
+    /// # Errors
+    ///
+    /// 当前 OS / 架构没有 Temurin 产物时返回 [`JavaErrorKind::Unsupported`]。
+    pub fn host() -> Result<Self, JavaError> {
+        let os = if cfg!(windows) {
+            "windows"
+        } else if cfg!(target_os = "macos") {
+            "mac"
+        } else if cfg!(target_os = "linux") {
+            "linux"
+        } else {
+            return Err(JavaError::new(
+                JavaErrorKind::Unsupported,
+                format!("当前系统（{}）没有 Temurin 产物", std::env::consts::OS),
+            )
+            .with_hint("手动指定 JAVA_HOME，或用 `ull launch --java <path>` 挑已有 JDK"));
+        };
+        let arch = arch_name(std::env::consts::ARCH).ok_or_else(|| {
+            JavaError::new(
+                JavaErrorKind::Unsupported,
+                format!("当前架构（{}）没有 Temurin 产物", std::env::consts::ARCH),
+            )
+            .with_hint("手动指定 JAVA_HOME，或用 `ull launch --java <path>` 挑已有 JDK")
+        })?;
+        Ok(Self { os, arch })
+    }
+
+    /// 构造（测试注入用）。
+    #[must_use]
+    pub const fn new(os: &'static str, arch: &'static str) -> Self {
+        Self { os, arch }
+    }
+
+    /// 该平台的产物是不是 zip（Windows 是；Linux/mac 的 Temurin 只发 `.tar.gz`）。
+    #[must_use]
+    pub fn is_zip(self) -> bool {
+        self.os == "windows"
+    }
+
+    /// 归档扩展名（拼「期望文件名」与给出「不支持的形态」提示时用）。
+    #[must_use]
+    pub fn archive_ext(self) -> &'static str {
+        if self.is_zip() {
+            "zip"
+        } else {
+            "tar.gz"
+        }
+    }
+}
+
+/// Rust 架构名 → Adoptium 架构名（不认识返回 `None`）。
+#[must_use]
+pub fn arch_name(arch: &str) -> Option<&'static str> {
+    match arch {
+        "x86_64" => Some("x64"),
+        "aarch64" => Some("aarch64"),
+        "x86" | "i686" => Some("x86-32"),
+        "arm" => Some("arm"),
+        "ppc64le" => Some("ppc64le"),
+        "s390x" => Some("s390x"),
+        "riscv64" => Some("riscv64"),
+        _ => None,
+    }
+}
diff --git a/crates/core/src/game/java/vendor.rs b/crates/core/src/game/java/vendor.rs
new file mode 100644
index 0000000..76dd270
--- /dev/null
+++ b/crates/core/src/game/java/vendor.rs
@@ -0,0 +1,219 @@
+//! JDK 发行版（vendor）抽象与用户可调优先级链（D23）。
+//!
+//! 四家发行版的**默认顺序按地区分区**（用户定案 + research/06 §5.1 实测修正）：
+//!
+//! ```text
+//! 国内：Temurin(TUNA) → Oracle OpenJDK(华为云→南大) → MS OpenJDK(境外 CDN) → Zulu
+//! 国外：Temurin        → MS OpenJDK                 → Oracle OpenJDK       → Zulu
+//! ```
+//!
+//! 国内把 Oracle 提到 MS 之前的依据是实测差 28×（Oracle 国内 11.5 MB/s vs MS 410 KB/s）；
+//! 用户原话是「Temurin → MS → Oracle」，但同一句话里给了「优先级可调」，所以这只是默认值，
+//! 设置键 `java.vendorPriority` 可以整体覆盖（D23 定稿）。
+//!
+//! 这里的表只描述**能力与顺序**，不碰网络：怎么查、怎么下在 `oracle` / `microsoft` /
+//! `zulu` / `api`（Temurin）四个模块里。
+
+/// 设置键 `java.vendorPriority` 的允许值（顺序即默认序的覆盖来源）。
+pub const VENDOR_IDS: &[&str] = &["temurin", "oracle", "microsoft", "zulu"];
+
+/// 一家 JDK 发行版。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub enum JdkVendor {
+    /// Eclipse Temurin（Adoptium），v1 唯一实现。
+    Temurin,
+    /// Oracle OpenJDK（`download.java.net` GA，只发首个 GA + ≤2 个 update）。
+    Oracle,
+    /// Microsoft OpenJDK（`aka.ms` 模板 + VS CDN，无 8）。
+    Microsoft,
+    /// Azul Zulu（第四备选，API 元数据 + CDN 直链）。
+    Zulu,
+}
+
+impl JdkVendor {
+    /// 全部发行版（枚举顺序，不是优先级顺序）。
+    pub const ALL: [Self; 4] = [Self::Temurin, Self::Oracle, Self::Microsoft, Self::Zulu];
+
+    /// 稳定 id（目录名段、`--vendor` 取值、设置值、JSON 字段）。
+    #[must_use]
+    pub const fn id(self) -> &'static str {
+        match self {
+            Self::Temurin => "temurin",
+            Self::Oracle => "oracle",
+            Self::Microsoft => "microsoft",
+            Self::Zulu => "zulu",
+        }
+    }
+
+    /// 展示名（人读输出 + `java vendors`）。
+    #[must_use]
+    pub const fn display(self) -> &'static str {
+        match self {
+            Self::Temurin => "Eclipse Temurin",
+            Self::Oracle => "Oracle OpenJDK",
+            Self::Microsoft => "Microsoft OpenJDK",
+            Self::Zulu => "Azul Zulu",
+        }
+    }
+
+    /// 解析 `--vendor` / 设置值（容忍常见别名，大小写不敏感）。
+    #[must_use]
+    pub fn parse(text: &str) -> Option<Self> {
+        match text.trim().to_ascii_lowercase().as_str() {
+            "temurin" | "adoptium" | "eclipse" | "eclipse-temurin" => Some(Self::Temurin),
+            "oracle" | "oracle_openjdk" | "openjdk" | "java.net" => Some(Self::Oracle),
+            "microsoft" | "ms" | "msopenjdk" | "ms_openjdk" | "microsoft-openjdk" => {
+                Some(Self::Microsoft)
+            }
+            "zulu" | "azul" => Some(Self::Zulu),
+            _ => None,
+        }
+    }
+
+    /// 该发行版能不能装这个大版本。
+    ///
+    /// Temurin / Zulu 覆盖 8 起的全部 GA；Oracle 的 archive 从 9 起（8 由 Temurin 负责）；
+    /// MS 只发 11/17/21/25（**已停发 8**，官方页面直接让去下 Temurin 8）。
+    #[must_use]
+    pub const fn supports(self, major: u32) -> bool {
+        match self {
+            Self::Temurin | Self::Zulu => major >= 8,
+            Self::Oracle => major >= 9,
+            Self::Microsoft => matches!(major, 11 | 17 | 21 | 25),
+        }
+    }
+
+    /// 已知在发的 GA 大版本（`java vendors` 展示与设置页提示用；不是硬上限）。
+    #[must_use]
+    pub const fn hint_majors(self) -> &'static [u32] {
+        match self {
+            Self::Temurin => &[8, 11, 17, 21, 25],
+            Self::Oracle => &[17, 21, 25],
+            Self::Microsoft => &[11, 17, 21, 25],
+            Self::Zulu => &[8, 11, 17, 21, 25],
+        }
+    }
+
+    /// 国内默认序（用户定案 + 实测修正）。
+    #[must_use]
+    pub const fn domestic_default() -> [Self; 4] {
+        [Self::Temurin, Self::Oracle, Self::Microsoft, Self::Zulu]
+    }
+
+    /// 国外默认序（用户原话顺序）。
+    #[must_use]
+    pub const fn global_default() -> [Self; 4] {
+        [Self::Temurin, Self::Microsoft, Self::Oracle, Self::Zulu]
+    }
+
+    /// 按地区取默认序。
+    #[must_use]
+    pub const fn default_order(domestic: bool) -> [Self; 4] {
+        if domestic {
+            Self::domestic_default()
+        } else {
+            Self::global_default()
+        }
+    }
+}
+
+/// 用户优先级（设置值）→ 实际尝试顺序。
+///
+/// 语义刻意做成「**补集追加**」而不是「必须写全」：用户写了 `["oracle"]` 就只把 oracle 提上来，
+/// 其余按地区默认序跟在后面。理由——写全四家是负担，漏写更不该等于「其余不试」。
+#[must_use]
+pub fn order(priority: &[JdkVendor], domestic: bool) -> Vec<JdkVendor> {
+    let mut out: Vec<JdkVendor> = Vec::with_capacity(JdkVendor::ALL.len());
+    for vendor in priority {
+        if !out.contains(vendor) {
+            out.push(*vendor);
+        }
+    }
+    for vendor in JdkVendor::default_order(domestic) {
+        if !out.contains(&vendor) {
+            out.push(vendor);
+        }
+    }
+    out
+}
+
+/// 解析设置值里的字符串数组（未知项忽略；顺序保留）。
+#[must_use]
+pub fn parse_priority(items: &[String]) -> Vec<JdkVendor> {
+    let mut out = Vec::with_capacity(items.len());
+    for item in items {
+        if let Some(vendor) = JdkVendor::parse(item) {
+            if !out.contains(&vendor) {
+                out.push(vendor);
+            }
+        }
+    }
+    out
+}
+
+/// 尝试顺序 → 稳定 id 列表（JSON / 人读输出）。
+#[must_use]
+pub fn ids(vendors: &[JdkVendor]) -> Vec<&'static str> {
+    vendors.iter().map(|vendor| vendor.id()).collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{ids, order, parse_priority, JdkVendor};
+
+    #[test]
+    fn domestic_and_global_defaults_follow_d23() {
+        assert_eq!(
+            ids(&order(&[], true)),
+            vec!["temurin", "oracle", "microsoft", "zulu"],
+            "国内：Oracle 在 MS 之前（实测差 28×）"
+        );
+        assert_eq!(
+            ids(&order(&[], false)),
+            vec!["temurin", "microsoft", "oracle", "zulu"],
+            "国外：维持用户原话 Temurin→MS→Oracle"
+        );
+    }
+
+    #[test]
+    fn user_priority_leads_and_the_rest_follows_as_a_complement() {
+        let priority = parse_priority(&["microsoft".to_string()]);
+        assert_eq!(
+            ids(&order(&priority, true)),
+            vec!["microsoft", "temurin", "oracle", "zulu"],
+            "只写一家也要把其余按默认序补齐"
+        );
+        let full = parse_priority(&["zulu".to_string(), "oracle".to_string(), "zulu".to_string()]);
+        assert_eq!(
+            ids(&order(&full, true)),
+            vec!["zulu", "oracle", "temurin", "microsoft"],
+            "重复项去重，未列出的追加在后面"
+        );
+    }
+
+    #[test]
+    fn unknown_setting_values_are_ignored() {
+        let parsed = parse_priority(&["graalvm".to_string(), "AZUL".to_string()]);
+        assert_eq!(parsed, vec![JdkVendor::Zulu]);
+    }
+
+    #[test]
+    fn vendor_ids_majors_and_aliases() {
+        assert_eq!(JdkVendor::parse("Adoptium"), Some(JdkVendor::Temurin));
+        assert_eq!(JdkVendor::parse("ms"), Some(JdkVendor::Microsoft));
+        assert_eq!(JdkVendor::parse("graalvm"), None);
+        // MS 没有 8：这是「回退链要跳过某家」的真实判据。
+        assert!(!JdkVendor::Microsoft.supports(8));
+        assert!(JdkVendor::Microsoft.supports(21));
+        assert!(JdkVendor::Oracle.supports(9));
+        assert!(!JdkVendor::Oracle.supports(8), "8 交给 Temurin");
+        assert!(JdkVendor::Temurin.supports(8));
+        for vendor in JdkVendor::ALL {
+            assert!(
+                vendor.hint_majors().contains(&21),
+                "{} 应发 21",
+                vendor.id()
+            );
+        }
+    }
+}
diff --git a/crates/core/src/game/java/zulu.rs b/crates/core/src/game/java/zulu.rs
new file mode 100644
index 0000000..b572d7f
--- /dev/null
+++ b/crates/core/src/game/java/zulu.rs
@@ -0,0 +1,275 @@
+//! Azul Zulu：**第四备选**（D23）。API 元数据 + CDN 直链，实现刻意简化。
+//!
+//! 为什么排最后：国内没有任何 Zulu 镜像（三家云 + 四家校园源全无 `zulu`/`azul` 目录），
+//! 只能吃 `cdn.azul.com` 的 3.3 MB/s（211 MB ≈ 64 s）；而前三家在国内都有更好的路。
+//! 留这一家的价值是「三家全挂时的最后一条活路」，以及 Temurin/Oracle/MS 都缺某版本时的兜底。
+//!
+//! 两跳（research/06 §4.3）：
+//!
+//! ```text
+//! GET {api}?java_version=21&os=windows&arch=x64&java_package_type=jdk&archive_type=zip&latest=true
+//!     → [{ package_uuid, name, java_version, download_url }]      # 注意：不含 sha256
+//! GET {detail（{uuid} 占位）} → { sha256_hash, size（不可信，差 133 B） }
+//! ```
+//!
+//! 三条实测约束：①`latest=true` 的响应**没有** `sha256_hash`，必须再取一次详情；
+//! ②`size` 字段与真实字节数差 133 B → 一律不信，只填 0；③文件名必须照抄 API 返回值
+//! （`zulu21.54.109-ca-jdk21.0.13.0.3-win_x64.zip` 里混着三段与四段两种写法，拼不出来）。
+
+use serde::Deserialize;
+
+use super::error::{JavaError, JavaErrorKind};
+use super::net;
+use super::release::{JdkArchive, JdkRelease};
+use super::target::AdoptiumTarget;
+use super::vendor::JdkVendor;
+use crate::download::ZuluTable;
+
+/// Zulu 的 os 段（`windows` / `macos` / `linux`）。
+#[must_use]
+pub fn zulu_os(target: AdoptiumTarget) -> &'static str {
+    match target.os {
+        "mac" => "macos",
+        other => other,
+    }
+}
+
+/// 包列表查询地址（`latest=true` 只返回最新一个）。
+#[must_use]
+pub fn api_url(table: &ZuluTable, major: u32, target: AdoptiumTarget) -> String {
+    format!(
+        "{}?java_version={major}&os={}&arch={}&java_package_type=jdk&archive_type=zip&latest=true",
+        table.api,
+        zulu_os(target),
+        target.arch
+    )
+}
+
+/// 包详情地址（`{uuid}` 占位替换）。
+#[must_use]
+pub fn detail_url(table: &ZuluTable, uuid: &str) -> String {
+    table.detail.replace("{uuid}", uuid)
+}
+
+/// 列表响应里我们关心的字段。
+///
+/// ⚠️ 真机形态（2026-10-30 实测）：`latest=true` **不止返回一条**，而且 `java_version` 是
+/// **数字数组**（`[21,0,13,0,3]`）而不是字符串；同一批里还混着 `-crac-`（CRaC）与
+/// `-fx-`（JavaFX）变体。所以这里按「字段宽进 + 只挑纯 JDK 包」处理，见 [`parse_packages`]。
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
+pub struct ZuluPackage {
+    /// 包 id（取详情用）。
+    pub package_uuid: String,
+    /// 归档文件名（照抄，不拼）。
+    pub name: String,
+    /// JDK 版本（`[21,0,13,0,3]`，Azul 用数组给）。
+    #[serde(default)]
+    pub java_version: Vec<u32>,
+    /// CDN 直链。
+    pub download_url: String,
+}
+
+impl ZuluPackage {
+    /// 版本串（`[21,0,13,0,3]` → `21.0.13.0.3`；空数组时退回文件名）。
+    #[must_use]
+    pub fn version_text(&self) -> String {
+        if self.java_version.is_empty() {
+            return self.name.clone();
+        }
+        self.java_version
+            .iter()
+            .map(u32::to_string)
+            .collect::<Vec<_>>()
+            .join(".")
+    }
+}
+
+/// 是否是「纯 JDK」包（排除 CRaC / JavaFX / JRE 变体）。
+#[must_use]
+pub fn is_plain_jdk(name: &str) -> bool {
+    name.contains("-jdk")
+        && !name.contains("-jre")
+        && !name.contains("crac")
+        && !name.contains("-fx")
+}
+
+/// 列表响应 → 纯 JDK 包（`latest=true` 会给多条，必须自己挑）。
+///
+/// # Errors
+///
+/// 响应不是 JSON、列表为空时返回错误。
+pub fn parse_packages(json: &str) -> Result<ZuluPackage, JavaError> {
+    let packages: Vec<ZuluPackage> = serde_json::from_str(json).map_err(|error| {
+        JavaError::new(
+            JavaErrorKind::Metadata,
+            format!("Zulu 列表响应不是预期 JSON：{error}"),
+        )
+    })?;
+    let picked = packages
+        .iter()
+        .find(|package| is_plain_jdk(&package.name))
+        .or_else(|| packages.first())
+        .ok_or_else(|| {
+            JavaError::new(
+                JavaErrorKind::Metadata,
+                "Zulu 没有该版本/平台的 JDK 包（列表为空）",
+            )
+        })?;
+    Ok(picked.clone())
+}
+
+/// 详情响应里的 `sha256_hash`（只信这一个字段，`size` 不可对拍）。
+///
+/// # Errors
+///
+/// 响应不是 JSON 或缺可用哈希时返回错误。
+pub fn parse_detail_sha256(json: &str) -> Result<String, JavaError> {
+    #[derive(Deserialize)]
+    struct Detail {
+        #[serde(default)]
+        sha256_hash: Option<String>,
+    }
+    let detail: Detail = serde_json::from_str(json).map_err(|error| {
+        JavaError::new(
+            JavaErrorKind::Metadata,
+            format!("Zulu 详情响应不是预期 JSON：{error}"),
+        )
+    })?;
+    detail
+        .sha256_hash
+        .map(|hex| hex.trim().to_ascii_lowercase())
+        .filter(|hex| hex.len() == 64 && hex.bytes().all(|byte| byte.is_ascii_hexdigit()))
+        .ok_or_else(|| {
+            JavaError::new(
+                JavaErrorKind::Integrity,
+                "Zulu 详情里没有可用的 sha256_hash",
+            )
+        })
+}
+
+/// 查一次「某大版本的最新 Zulu JDK」。
+///
+/// # Errors
+///
+/// 表里没配 Zulu、API 不可达/无包、详情缺哈希时返回错误（回退链到此为止，报总失败）。
+pub async fn fetch_latest(
+    client: &reqwest::Client,
+    table: &ZuluTable,
+    major: u32,
+    target: AdoptiumTarget,
+) -> Result<JdkRelease, JavaError> {
+    let list = net::get_text(client, &api_url(table, major, target), "Zulu 包列表").await?;
+    let package = parse_packages(&list)?;
+    let detail = net::get_text(
+        client,
+        &detail_url(table, &package.package_uuid),
+        "Zulu 包详情",
+    )
+    .await?;
+    let sha256 = parse_detail_sha256(&detail)?;
+    // Zulu 的版本串用 `java_version` 数组拼（真机是数组不是字符串）；文件名照抄，
+    // 因为文件名里 `jdk21.0.13.0.3` 这类四段/五段写法拼不出来。
+    Ok(JdkRelease {
+        vendor: JdkVendor::Zulu,
+        major,
+        version: package.version_text(),
+        semver: None,
+        release_name: package.name.clone(),
+        archive: JdkArchive {
+            name: package.name,
+            url: package.download_url,
+            sha256,
+            // size 字段不可信（实测差 133 B）→ 填 0，交给 sha256 校验。
+            size: 0,
+        },
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{api_url, detail_url, is_plain_jdk, parse_detail_sha256, parse_packages, zulu_os};
+    use crate::download::MirrorTable;
+    use crate::game::java::target::AdoptiumTarget;
+
+    const WINDOWS: AdoptiumTarget = AdoptiumTarget::new("windows", "x64");
+
+    fn table() -> crate::download::ZuluTable {
+        MirrorTable::builtin()
+            .zulu()
+            .expect("内置表应带 Zulu")
+            .clone()
+    }
+
+    #[test]
+    fn urls_carry_every_filter_the_api_needs() {
+        let table = table();
+        let url = api_url(&table, 21, WINDOWS);
+        assert!(url.starts_with("https://api.azul.com/metadata/v1/zulu/packages/?"));
+        for needle in [
+            "java_version=21",
+            "os=windows",
+            "arch=x64",
+            "java_package_type=jdk",
+            "archive_type=zip",
+            "latest=true",
+        ] {
+            assert!(url.contains(needle), "{needle} 应在 {url}");
+        }
+        assert_eq!(
+            detail_url(&table, "abc-123"),
+            "https://api.azul.com/metadata/v1/zulu/packages/abc-123"
+        );
+        assert_eq!(zulu_os(AdoptiumTarget::new("mac", "aarch64")), "macos");
+    }
+
+    #[test]
+    fn latest_listing_gives_the_uuid_and_the_exact_filename() {
+        // 真机响应（2026-10-30）：`latest=true` 返回多条，`java_version` 是数组，
+        // 并且混着 `-crac-` / `-fx-` 变体——必须挑出纯 JDK 那条。
+        let json = r#"[
+          {"package_uuid":"4ee30e3a-b26a-40d3-9d04-2182eae4075e",
+           "name":"zulu21.54.109-ca-jdk21.0.13.0.3-win_x64.zip",
+           "java_version":[21,0,13,0,3],
+           "download_url":"https://cdn.azul.com/zulu/bin/zulu21.54.109-ca-jdk21.0.13.0.3-win_x64.zip"},
+          {"package_uuid":"2781fb21-9401-40d3-a88e-cf8f36541e3c",
+           "name":"zulu21.52.203-ca-crac-jdk21.0.12.1-win_x64.zip",
+           "java_version":[21,0,12,1],
+           "download_url":"https://cdn.azul.com/zulu/bin/zulu21.52.203-ca-crac-jdk21.0.12.1-win_x64.zip"},
+          {"package_uuid":"49851aa2-4fd2-4e54-a903-323989cdf711",
+           "name":"zulu21.52.203-ca-fx-jdk21.0.12.1-win_x64.zip",
+           "java_version":[21,0,12,1],
+           "download_url":"https://cdn.azul.com/zulu/bin/zulu21.52.203-ca-fx-jdk21.0.12.1-win_x64.zip"}
+        ]"#;
+        let package = parse_packages(json).expect("应解析");
+        assert_eq!(package.package_uuid, "4ee30e3a-b26a-40d3-9d04-2182eae4075e");
+        assert_eq!(
+            package.name, "zulu21.54.109-ca-jdk21.0.13.0.3-win_x64.zip",
+            "文件名必须照抄 API（三段/四段混写，拼不出来）"
+        );
+        assert_eq!(package.version_text(), "21.0.13.0.3");
+        assert!(is_plain_jdk(&package.name));
+        assert!(!is_plain_jdk(
+            "zulu21.52.203-ca-crac-jdk21.0.12.1-win_x64.zip"
+        ));
+        assert!(!is_plain_jdk(
+            "zulu21.52.203-ca-fx-jdk21.0.12.1-win_x64.zip"
+        ));
+        assert!(
+            parse_packages("[]").is_err(),
+            "空列表要报错而不是造一个空包"
+        );
+        assert!(parse_packages("<html>502</html>").is_err());
+    }
+
+    #[test]
+    fn detail_gives_a_trustworthy_sha256_only() {
+        let json = r#"{"package_uuid":"x","size":211151000,
+            "sha256_hash":"6B0E2B0F4C1D2A3E4F5061728394A5B6C7D8E9F0A1B2C3D4E5F60718293A4B5C"}"#;
+        assert_eq!(
+            parse_detail_sha256(json).expect("大写哈希应被接受并转小写"),
+            "6b0e2b0f4c1d2a3e4f5061728394a5b6c7d8e9f0a1b2c3d4e5f60718293a4b5c"
+        );
+        assert!(parse_detail_sha256(r#"{"size":1}"#).is_err());
+        assert!(parse_detail_sha256("not json").is_err());
+    }
+}
diff --git a/crates/core/src/game/layout.rs b/crates/core/src/game/layout.rs
new file mode 100644
index 0000000..408473e
--- /dev/null
+++ b/crates/core/src/game/layout.rs
@@ -0,0 +1,165 @@
+//! `.minecraft` 实例目录布局：`versions/` `libraries/` `assets/` + ULL 扩展 `.ull/`。
+//!
+//! 依据：`DevDocs/analyse/03-version-download.md` §6.8（目录布局速查）、
+//! `DevDocs/PlanDoc/04-data-and-config.md` §2（`.minecraft/` 遵循 Mojang 标准 +
+//! ULL 扩展 `.ull/`）。
+//!
+//! 布局是**纯路径计算**：不建目录、不写文件。所有路径规则集中在这里，
+//! 这样将来要支持 MultiMC 家族布局（`instances/<id>/minecraft/`）只需再加一个实现
+//! （analyse/01 §3.3 的 `GameRepositoryLayout` 抽象意义）。
+
+use std::path::{Path, PathBuf};
+
+use super::error::GameError;
+use super::library::MavenCoordinate;
+
+/// 一个游戏根目录（通常就是 `.minecraft/`）的布局规则。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct GameLayout {
+    root: PathBuf,
+}
+
+impl GameLayout {
+    /// 以给定根目录构造布局。
+    pub fn new(root: impl Into<PathBuf>) -> Self {
+        Self { root: root.into() }
+    }
+
+    /// 根目录。
+    pub fn root(&self) -> &Path {
+        &self.root
+    }
+
+    /// `versions/`。
+    pub fn versions_dir(&self) -> PathBuf {
+        self.root.join("versions")
+    }
+
+    /// `libraries/`。
+    pub fn libraries_dir(&self) -> PathBuf {
+        self.root.join("libraries")
+    }
+
+    /// `assets/`。
+    pub fn assets_dir(&self) -> PathBuf {
+        self.root.join("assets")
+    }
+
+    /// `assets/indexes/`。
+    pub fn indexes_dir(&self) -> PathBuf {
+        self.assets_dir().join("indexes")
+    }
+
+    /// `assets/objects/`（两级分片，避开 NTFS 单目录塌陷）。
+    pub fn objects_dir(&self) -> PathBuf {
+        self.assets_dir().join("objects")
+    }
+
+    /// `assets/log_configs/`（日志配置缓存）。
+    pub fn log_configs_dir(&self) -> PathBuf {
+        self.assets_dir().join("log_configs")
+    }
+
+    /// 实例根目录 `versions/<id>/`。
+    pub fn version_dir(&self, id: &str) -> PathBuf {
+        self.versions_dir().join(id)
+    }
+
+    /// 实例清单 `versions/<id>/<id>.json`。
+    pub fn version_json(&self, id: &str) -> PathBuf {
+        self.version_dir(id).join(format!("{id}.json"))
+    }
+
+    /// 实例 jar `versions/<id>/<id>.jar`。
+    pub fn version_jar(&self, id: &str) -> PathBuf {
+        self.version_dir(id).join(format!("{id}.jar"))
+    }
+
+    /// natives 解压目录 `versions/<id>/natives/`（ULL 约定，HMCL 用 `natives/<ver>`）。
+    pub fn natives_dir(&self, id: &str) -> PathBuf {
+        self.version_dir(id).join("natives")
+    }
+
+    /// 实例私有状态目录 `versions/<id>/.ull/`（上次会话日志索引、安装收据等）。
+    pub fn version_state_dir(&self, id: &str) -> PathBuf {
+        self.version_dir(id).join(".ull")
+    }
+
+    /// 实例私有库目录 `versions/<id>/libraries/`（HMCL `hint=local` 的落点）。
+    pub fn version_libraries_dir(&self, id: &str) -> PathBuf {
+        self.version_dir(id).join("libraries")
+    }
+
+    /// 启动器全局私有目录 `<root>/.ull/`。
+    pub fn ull_root(&self) -> PathBuf {
+        self.root.join(".ull")
+    }
+
+    /// 资源索引 `assets/indexes/<assetsId>.json`。
+    pub fn asset_index(&self, assets_id: &str) -> PathBuf {
+        self.indexes_dir().join(format!("{assets_id}.json"))
+    }
+
+    /// 资源对象 `assets/objects/<hash[0..2]>/<hash>`。
+    ///
+    /// # Errors
+    ///
+    /// 哈希短于两个字符时返回 [`GameError::InvalidAssetHash`]。
+    pub fn asset_object(&self, hash: &str) -> Result<PathBuf, GameError> {
+        let shard = hash.get(0..2).ok_or_else(|| GameError::InvalidAssetHash {
+            hash: hash.to_owned(),
+        })?;
+        Ok(self.objects_dir().join(shard).join(hash))
+    }
+
+    /// 公共库 `libraries/<group path>/<artifact>-<version>[-<classifier>].<ext>`。
+    pub fn library(&self, coordinate: &MavenCoordinate) -> PathBuf {
+        self.libraries_dir().join(coordinate.relative_path())
+    }
+
+    /// 实例私有库 `versions/<id>/libraries/...`。
+    pub fn version_library(&self, version_id: &str, coordinate: &MavenCoordinate) -> PathBuf {
+        self.version_libraries_dir(version_id)
+            .join(coordinate.relative_path())
+    }
+
+    /// 日志配置文件 `assets/log_configs/<id>`。
+    pub fn log_config(&self, file_id: &str) -> PathBuf {
+        self.log_configs_dir().join(file_id)
+    }
+
+    /// 该版本是否已安装（判据：清单文件存在）。
+    pub fn is_version_installed(&self, id: &str) -> bool {
+        self.version_json(id).is_file()
+    }
+
+    /// 列出已安装的版本 id（有 `versions/<id>/<id>.json` 的目录），按字典序排列。
+    ///
+    /// # Errors
+    ///
+    /// 读 `versions/` 失败时返回 [`GameError::Io`]；目录不存在视为空列表。
+    pub fn installed_versions(&self) -> Result<Vec<String>, GameError> {
+        let dir = self.versions_dir();
+        let entries = match std::fs::read_dir(&dir) {
+            Ok(entries) => entries,
+            Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(Vec::new()),
+            Err(e) => return Err(GameError::io(&dir, e)),
+        };
+        let mut ids = Vec::new();
+        for entry in entries {
+            let entry = entry.map_err(|e| GameError::io(&dir, e))?;
+            let path = entry.path();
+            if !path.is_dir() {
+                continue;
+            }
+            let Some(name) = path.file_name().and_then(|n| n.to_str()) else {
+                continue;
+            };
+            if path.join(format!("{name}.json")).is_file() {
+                ids.push(name.to_owned());
+            }
+        }
+        ids.sort();
+        Ok(ids)
+    }
+}
diff --git a/crates/core/src/game/library.rs b/crates/core/src/game/library.rs
new file mode 100644
index 0000000..230c4b9
--- /dev/null
+++ b/crates/core/src/game/library.rs
@@ -0,0 +1,213 @@
+//! 依赖库模型：Maven 坐标、natives 选择、库文件相对路径。
+//!
+//! 依据：`DevDocs/analyse/03-version-download.md` §6.4（libraries 含 natives 规则）、
+//! §6.8（目录布局速查）。
+//!
+//! 这里只做"数据 → 路径/候选"的纯计算，**不碰网络与文件系统**：
+//! 真正的下载归 `core::download`，放置归 [`super::layout`]。
+
+use std::collections::BTreeMap;
+use std::path::PathBuf;
+
+use serde::{Deserialize, Serialize};
+
+use super::arguments::{rules_allow, Environment, Rule};
+use super::error::GameError;
+use super::manifest::DownloadInfo;
+
+/// 一条依赖库。
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Library {
+    /// Maven 坐标 `group:artifact:version[:classifier][@ext]`。
+    #[serde(default)]
+    pub name: String,
+    /// 下载信息；老 JSON/魔改 JSON 可能没有。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub downloads: Option<LibraryDownloads>,
+    /// natives 选择表：`{ "windows": "natives-windows-${arch}" }`。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub natives: Option<BTreeMap<String, String>>,
+    /// 生效规则（空 = 生效）。
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub rules: Vec<Rule>,
+    /// natives 解压规则。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub extract: Option<Extract>,
+    /// Maven 仓库基地址覆盖。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub url: Option<String>,
+    /// HMCL 私有：`local` 表示库放在实例私有的 `versions/<id>/libraries/` 下。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub hint: Option<String>,
+    /// 未识别字段原样保留。
+    #[serde(flatten)]
+    pub extra: BTreeMap<String, serde_json::Value>,
+}
+
+/// 一条依赖库的下载表。
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct LibraryDownloads {
+    /// 主构件。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub artifact: Option<DownloadInfo>,
+    /// 分类器构件（natives 走这里）。
+    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
+    pub classifiers: BTreeMap<String, DownloadInfo>,
+}
+
+/// natives 解压规则：命中 `exclude` 的条目不解压。
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Extract {
+    /// 排除的路径模式（`META-INF/`）。
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub exclude: Vec<String>,
+}
+
+/// Maven 坐标（`group:artifact:version[:classifier][@ext]`）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct MavenCoordinate {
+    /// group，如 `org.lwjgl`。
+    pub group: String,
+    /// artifact，如 `lwjgl`。
+    pub artifact: String,
+    /// version，如 `3.3.2`。
+    pub version: String,
+    /// classifier（natives 常用），如 `natives-windows`。
+    pub classifier: Option<String>,
+    /// 扩展名，缺省 `jar`。
+    pub extension: String,
+}
+
+impl MavenCoordinate {
+    /// 解析坐标字符串。
+    pub fn parse(raw: &str) -> Result<Self, GameError> {
+        let invalid = |reason: &'static str| GameError::InvalidCoordinate {
+            raw: raw.to_owned(),
+            reason,
+        };
+        let (body, extension) = match raw.split_once('@') {
+            Some((body, ext)) if !ext.is_empty() => (body, ext.to_owned()),
+            Some(_) => return Err(invalid("扩展名为空")),
+            None => (raw, String::from("jar")),
+        };
+        let parts: Vec<&str> = body.split(':').collect();
+        if parts.len() < 3 {
+            return Err(invalid("至少需要 group:artifact:version 三段"));
+        }
+        if parts.iter().any(|p| p.is_empty()) {
+            return Err(invalid("存在空字段"));
+        }
+        match parts.len() {
+            3 => Ok(Self {
+                group: parts[0].to_owned(),
+                artifact: parts[1].to_owned(),
+                version: parts[2].to_owned(),
+                classifier: None,
+                extension,
+            }),
+            4 => Ok(Self {
+                group: parts[0].to_owned(),
+                artifact: parts[1].to_owned(),
+                version: parts[2].to_owned(),
+                classifier: Some(parts[3].to_owned()),
+                extension,
+            }),
+            _ => Err(invalid("字段多于四段")),
+        }
+    }
+
+    /// group 转目录形式（`org.lwjgl` → `org/lwjgl`）。
+    pub fn group_path(&self) -> String {
+        self.group.replace('.', "/")
+    }
+
+    /// 文件名：`<artifact>-<version>[-<classifier>].<ext>`。
+    pub fn file_name(&self) -> String {
+        match &self.classifier {
+            Some(classifier) => format!(
+                "{}-{}-{}.{}",
+                self.artifact, self.version, classifier, self.extension
+            ),
+            None => format!("{}-{}.{}", self.artifact, self.version, self.extension),
+        }
+    }
+
+    /// 相对 `libraries/` 的路径：
+    /// `<group path>/<artifact>/<version>/<artifact>-<version>[-<classifier>].<ext>`。
+    pub fn relative_path(&self) -> PathBuf {
+        PathBuf::from(self.group_path())
+            .join(&self.artifact)
+            .join(&self.version)
+            .join(self.file_name())
+    }
+
+    /// 换一个 classifier 的副本（natives 用）。
+    pub fn with_classifier(&self, classifier: impl Into<String>) -> Self {
+        Self {
+            classifier: Some(classifier.into()),
+            ..self.clone()
+        }
+    }
+}
+
+impl Library {
+    /// 解析本库的 Maven 坐标。
+    pub fn coordinate(&self) -> Result<MavenCoordinate, GameError> {
+        MavenCoordinate::parse(&self.name)
+    }
+
+    /// 该库在当前环境下是否生效。
+    pub fn applies(&self, env: &Environment) -> bool {
+        rules_allow(&self.rules, env)
+    }
+
+    /// 是否是实例私有库（HMCL `hint=local`）。
+    pub fn is_local(&self) -> bool {
+        self.hint.as_deref() == Some("local")
+    }
+
+    /// 主构件下载信息。
+    pub fn artifact(&self) -> Option<&DownloadInfo> {
+        self.downloads.as_ref()?.artifact.as_ref()
+    }
+
+    /// natives 分类器名：按 OS 查 `natives` 表并展开 `${arch}`（64 位为 `64`）。
+    pub fn native_classifier(&self, env: &Environment) -> Option<String> {
+        let raw = self.natives.as_ref()?.get(&env.os)?;
+        let arch = if matches!(env.arch.as_str(), "x86_64" | "arm64") {
+            "64"
+        } else {
+            ""
+        };
+        Some(raw.replace("${arch}", arch))
+    }
+
+    /// natives 构件下载信息（按分类器查 `downloads.classifiers`）。
+    pub fn native_artifact(&self, classifier: &str) -> Option<&DownloadInfo> {
+        self.downloads.as_ref()?.classifiers.get(classifier)
+    }
+
+    /// 主构件相对 `libraries/` 的路径。
+    ///
+    /// 优先用 JSON 里给出的 `artifact.path`（Mojang 官方的权威值），否则按坐标推导。
+    pub fn relative_path(&self) -> Result<PathBuf, GameError> {
+        if let Some(path) = self.artifact().and_then(|a| a.path.as_deref()) {
+            return Ok(PathBuf::from(path));
+        }
+        Ok(self.coordinate()?.relative_path())
+    }
+
+    /// natives 构件相对 `libraries/` 的路径。
+    pub fn native_relative_path(&self, classifier: &str) -> Result<PathBuf, GameError> {
+        if let Some(path) = self
+            .native_artifact(classifier)
+            .and_then(|a| a.path.as_deref())
+        {
+            return Ok(PathBuf::from(path));
+        }
+        Ok(self
+            .coordinate()?
+            .with_classifier(classifier)
+            .relative_path())
+    }
+}
diff --git a/crates/core/src/game/manifest.rs b/crates/core/src/game/manifest.rs
new file mode 100644
index 0000000..0fca0d6
--- /dev/null
+++ b/crates/core/src/game/manifest.rs
@@ -0,0 +1,265 @@
+//! 版本 JSON（`versions/<id>/<id>.json`）的数据模型。
+//!
+//! 依据：`DevDocs/analyse/03-version-download.md` §4.1（Manifest + Patch 两层模型）、
+//! §4.2（宽松解析 + `rawJson` 保真）、§4.6（旧版 JSON 的四个特殊分支）。
+//!
+//! 一个类型吃两种形态：磁盘上的实例清单（`root`/`hidden`/`patches`）与可合并的补丁层
+//! （多一个 `priority`）。合并语义不在这里，而在 [`super::inherit`]——模型只管形状。
+//!
+//! **保真**：未知字段全部落进 `extra`（`#[serde(flatten)]`），回写时原样带出。
+//! 第三方启动器的私有字段（`MMC-*`、`tlauncherVersion`…）因此不会丢。
+
+use std::collections::BTreeMap;
+
+use serde::{Deserialize, Serialize};
+
+use super::arguments::Arguments;
+use super::error::GameError;
+use super::library::Library;
+use super::version::ReleaseType;
+
+/// 单个文件的下载信息（`downloads.client`、库 artifact、资源索引、日志配置都用它）。
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct DownloadInfo {
+    /// 内容 id（资源索引/日志配置用；例如日志配置的 `client-1.12.xml`）。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub id: Option<String>,
+    /// SHA-1 校验值。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub sha1: Option<String>,
+    /// 字节数。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub size: Option<u64>,
+    /// 下载地址（老版本的版本 JSON 可能完全没有）。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub url: Option<String>,
+    /// 库文件相对 `libraries/` 的路径（Mojang 在 artifact 里给出）。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub path: Option<String>,
+}
+
+impl DownloadInfo {
+    /// URL 是否可用。
+    pub fn has_url(&self) -> bool {
+        self.url.as_deref().is_some_and(|u| !u.is_empty())
+    }
+}
+
+/// 版本 JSON 的 `downloads` 对象：`client` / `server` / `client_mappings` / `server_mappings`。
+///
+/// 用"字符串键 + 映射"而不是枚举，是因为魔改 JSON 里会出现未知键
+/// （analyse/03 §4.2：HMCL 对未知键 `catch` 后忽略），枚举键会让整份 JSON 解析失败。
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(transparent)]
+pub struct Downloads(pub BTreeMap<String, DownloadInfo>);
+
+impl Downloads {
+    /// 客户端 jar 的下载信息。
+    pub fn client(&self) -> Option<&DownloadInfo> {
+        self.0.get("client")
+    }
+
+    /// 服务端 jar 的下载信息。
+    pub fn server(&self) -> Option<&DownloadInfo> {
+        self.0.get("server")
+    }
+
+    /// 按原始键取。
+    pub fn get(&self, key: &str) -> Option<&DownloadInfo> {
+        self.0.get(key)
+    }
+
+    /// 条目数。
+    pub fn len(&self) -> usize {
+        self.0.len()
+    }
+
+    /// 是否为空。
+    pub fn is_empty(&self) -> bool {
+        self.0.is_empty()
+    }
+}
+
+/// 日志配置（`logging.client`）。
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct LoggingInfo {
+    /// JVM 参数模板，含 `${path}` 占位符。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub argument: Option<String>,
+    /// 配置文件本体。
+    #[serde(default)]
+    pub file: DownloadInfo,
+    /// `log4j2-xml` 之类。
+    #[serde(rename = "type", default, skip_serializing_if = "Option::is_none")]
+    pub kind: Option<String>,
+}
+
+/// 版本 JSON 的 `logging` 对象（键通常是 `client`）。
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(transparent)]
+pub struct Logging(pub BTreeMap<String, LoggingInfo>);
+
+impl Logging {
+    /// 客户端日志配置。
+    pub fn client(&self) -> Option<&LoggingInfo> {
+        self.0.get("client")
+    }
+}
+
+/// `javaVersion`：组件名 + 主版本号（D13 的 MC↔Java 映射用）。
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct JavaVersion {
+    /// 官方 Java 运行时组件名，例如 `java-runtime-gamma`。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub component: Option<String>,
+    /// 主版本号，例如 `17`。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub major_version: Option<u32>,
+}
+
+/// `assetIndex`：资源索引的引用。
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AssetIndexRef {
+    /// 索引 id（`1.20`、`legacy`…），对应 `assets/indexes/<id>.json`。
+    #[serde(default)]
+    pub id: String,
+    /// 索引文件 SHA-1。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub sha1: Option<String>,
+    /// 索引文件字节数。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub size: Option<u64>,
+    /// 全部对象的总字节数（`totalSize`，进度估算用）。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub total_size: Option<u64>,
+    /// 索引下载地址。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub url: Option<String>,
+}
+
+/// 一份版本 JSON（磁盘上的 `<id>.json`，或一个可合并的补丁层）。
+///
+/// 字段几乎全部可空——这是"容忍残缺清单"的前提（analyse/03 §4.1：HMCL 22 个字段全可空）。
+/// 解析后的不变量（由 [`super::inherit::resolve`] 保证）：`inherits_from == None`、
+/// `jar` 已回退成实例 id、`patches` 已清空、`root == Some(true)`。
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", default)]
+pub struct VersionJson {
+    /// 版本 id。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub id: Option<String>,
+    /// 展示名（部分整合包写入）。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub name: Option<String>,
+    /// 继承的父版本 id。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub inherits_from: Option<String>,
+    /// 启动用的 jar 所在版本 id；`None` 表示用本实例的 jar。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub jar: Option<String>,
+    /// 主类。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub main_class: Option<String>,
+    /// 旧版单串游戏参数（pre-1.13），与 `arguments` 并存。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub minecraft_arguments: Option<String>,
+    /// 新版结构化参数。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub arguments: Option<Arguments>,
+    /// 资源版本名（`1.20`、`legacy`…）；缺失按 `legacy` 处理（analyse/03 §4.6）。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub assets: Option<String>,
+    /// 资源索引引用。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub asset_index: Option<AssetIndexRef>,
+    /// 兼容级别。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub compliance_level: Option<u32>,
+    /// 需要的 Java 版本。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub java_version: Option<JavaVersion>,
+    /// 依赖库列表。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub libraries: Option<Vec<Library>>,
+    /// 下载信息。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub downloads: Option<Downloads>,
+    /// 日志配置。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub logging: Option<Logging>,
+    /// 版本分类。
+    #[serde(rename = "type", skip_serializing_if = "Option::is_none")]
+    pub version_type: Option<ReleaseType>,
+    /// 最后修改时间。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub time: Option<String>,
+    /// 发布时间。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub release_time: Option<String>,
+    /// 启动器最低版本要求。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub minimum_launcher_version: Option<u32>,
+    /// 是否为根清单（HMCL 私有字段）。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub root: Option<bool>,
+    /// 是否在 UI 中隐藏（HMCL 私有字段）。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub hidden: Option<bool>,
+    /// 补丁层，按 `priority` 升序合并（HMCL 私有字段）。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub patches: Option<Vec<VersionJson>>,
+    /// 补丁优先级；`None` 视作最小值（最先合并，analyse/03 §4.1）。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub priority: Option<i32>,
+    /// 未识别的字段，原样保留（`rawJson` 保真）。
+    #[serde(flatten)]
+    pub extra: BTreeMap<String, serde_json::Value>,
+}
+
+impl VersionJson {
+    /// 解析一份版本 JSON。
+    pub fn from_json_str(json: &str) -> Result<Self, GameError> {
+        serde_json::from_str(json).map_err(|e| GameError::json("version_json", e))
+    }
+
+    /// 从字节解析（直接吃 HTTP 响应体）。
+    pub fn from_json_slice(bytes: &[u8]) -> Result<Self, GameError> {
+        serde_json::from_slice(bytes).map_err(|e| GameError::json("version_json", e))
+    }
+
+    /// 序列化回 JSON。
+    pub fn to_json_string(&self) -> Result<String, GameError> {
+        serde_json::to_string(self).map_err(|e| GameError::json("version_json", e))
+    }
+
+    /// 取 `id`，缺失则报错。
+    pub fn require_id(&self) -> Result<&str, GameError> {
+        self.id.as_deref().ok_or(GameError::MissingVersionId)
+    }
+
+    /// 客户端 jar 的下载信息；老版本 JSON 没有 `downloads.client`（analyse/03 §4.6），
+    /// 兜底 URL 由 download/launch 侧按镜像表拼，不在模型里硬编码 BMCLAPI。
+    pub fn client_jar(&self) -> Option<&DownloadInfo> {
+        self.downloads.as_ref().and_then(Downloads::client)
+    }
+
+    /// 资源版本名，缺失时按 `legacy`（analyse/03 §4.6 第 3 条）。
+    pub fn assets_id(&self) -> &str {
+        self.assets.as_deref().unwrap_or("legacy")
+    }
+
+    /// 是否已是被解析过的扁平清单。
+    pub fn is_resolved(&self) -> bool {
+        self.inherits_from.is_none() && self.patches.is_none() && self.jar.is_some()
+    }
+
+    /// 版本是否带 Vulkan 后端（`libraries` 含 `org.lwjgl:lwjgl-vulkan`）。
+    ///
+    /// 只是**必要条件**：`26.2-snapshot-1` 有库但还没有 `--graphicsBackend`
+    /// （差两天，实测），下发门限见 [`crate::game::capability`] 的模块文档。
+    pub fn has_vulkan_backend(&self) -> bool {
+        super::capability::VersionCapabilities::from_json(self).has_vulkan_backend()
+    }
+}
diff --git a/crates/core/src/game/mod.rs b/crates/core/src/game/mod.rs
new file mode 100644
index 0000000..e05e441
--- /dev/null
+++ b/crates/core/src/game/mod.rs
@@ -0,0 +1,64 @@
+//! 版本与实例仓库：不可变快照 + 单写者草稿、版本 JSON 继承解析、实例目录布局。
+//!
+//! 设计定稿：`DevDocs/PlanDoc/04-data-and-config.md` §4（实例模型）、
+//! `DevDocs/PlanDoc/01-tech-stack-and-architecture.md` §3（Snapshot/Draft 纪律），
+//! 源证据 `DevDocs/analyse/01-architecture-overview.md` §3.3。
+//!
+//! 与其它模块的契约：快照（Snapshot）类型与继承解析结果要与 launch 对齐
+//! （`DevDocs/SubAgentsTalk/README.md` 的对齐点；详细约定见 `SubAgentsTalk/game-接口约定.md`）。
+//!
+//! 公共面（M14）：
+//! - 版本清单：[`VersionList`] / [`RemoteVersion`] / [`ReleaseType`] / [`VersionCategory`]，
+//!   外加内嵌补充清单 [`unlisted`]；
+//! - 版本 JSON 与继承：[`VersionJson`]、[`resolve`]、[`merge`]、[`apply_patches`]；
+//! - 参数与库：[`Arguments`] / [`Environment`] / [`Rule`]、[`Library`] / [`MavenCoordinate`]；
+//! - 能力位：[`capability`]（版本 JSON 库表 → `has_vulkan_backend`）；
+//! - 实例：目录布局 [`GameLayout`]、档案 [`ProfileList`] / [`InstanceProfile`] / [`ProfileId`]；
+//! - 发布：快照仓库 [`Store`] / [`Snapshot`] / [`Draft`]。
+//!
+//! 安装层（M27，[`install`]）：版本链 → 下载计划 → 分区落盘 → 实例登记。
+//! 它把上面这些"模型"串成可执行的流程，但**自己不碰 UI、不拼镜像 URL**：
+//! 下载全部交给 `core::download` 的引擎（镜像/健康度/续传/校验都在那边）。
+//!
+//! Java 管理（M33，[`java`]）：托管 JDK 的查询/下载/解压/探测（`.ULL/data/java-managed/`）
+//! 与 MC↔Java 映射表。同样只借 `core::download` 的引擎做下载，自己不拼镜像 URL。
+//!
+//! 模块分工按"数据形状 / 纯计算 / 状态"切开，任何模块都不碰网络与 UI：
+//! 下载归 `core::download`、进程归 `core::launch`、配置落盘归 `core::setting`。
+
+pub mod arguments;
+pub mod capability;
+pub mod error;
+pub mod inherit;
+pub mod install;
+pub mod isolation;
+pub mod java;
+pub mod layout;
+pub mod library;
+pub mod manifest;
+pub mod profiles;
+pub mod snapshot;
+pub mod unlisted;
+pub mod version;
+
+pub use arguments::{rules_allow, Arguments, Environment, ExpandedArguments, Rule, RuleAction};
+pub use capability::{
+    is_vulkan_library, library_names_have_vulkan, VersionCapabilities, VULKAN_LIBRARY_ARTIFACT,
+    VULKAN_LIBRARY_GROUP,
+};
+pub use error::GameError;
+pub use inherit::{apply_patches, merge, resolve, sorted_patches, VersionSource};
+pub use isolation::{
+    derive_game_dir, observe_mode, probe_both_sides, probe_side, Derivation, IsolationMode,
+    IsolationSource, ModeChange, ModeChangeProbe, ModeChangeWarning, SideContent,
+    PROBED_CONTENT_DIRS, SHARED_LAYERS,
+};
+pub use layout::GameLayout;
+pub use library::{Library, MavenCoordinate};
+pub use manifest::{AssetIndexRef, DownloadInfo, Downloads, JavaVersion, Logging, VersionJson};
+pub use profiles::{InstanceProfile, ProfileId, ProfileList, PROFILE_SCHEMA_VERSION};
+pub use snapshot::{Draft, Snapshot, Store};
+pub use version::{
+    LatestVersions, ReleaseType, RemoteVersion, VersionCategory, VersionList,
+    VERSION_MANIFEST_V2_URL,
+};
diff --git a/crates/core/src/game/profiles.rs b/crates/core/src/game/profiles.rs
new file mode 100644
index 0000000..db222db
--- /dev/null
+++ b/crates/core/src/game/profiles.rs
@@ -0,0 +1,244 @@
+//! 实例清单（`profiles.json`）模型：稳定 UUID + 实例档案。
+//!
+//! 依据：`DevDocs/PlanDoc/04-data-and-config.md` §4（实例模型预告）、§2（`.ULL/config/profiles.json`）。
+//!
+//! 两条硬约束（来自 analyse/01 §7.6 的教训）：
+//! 1. **实例 id 用稳定 UUID，不用路径**——路径会变（用户挪目录、迁移数据目录），
+//!    而 id 一旦写进档案就不能变；
+//! 2. 档案只存**绑定关系**（版本 id、独立目录、Java 覆盖），不存派生的绝对路径结论；
+//!    全局/实例/临时三层设置的合并归 `core::setting`，这里不重复。
+//!
+//! 落盘归 `core::setting` 的原子写 + schema 迁移（M12），本模块只提供模型与不变量。
+
+use std::collections::BTreeMap;
+use std::fmt;
+use std::path::PathBuf;
+use std::str::FromStr;
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use serde::{Deserialize, Serialize};
+
+/// `profiles.json` 的 schema 版本（迁移链由 `core::setting` 驱动）。
+pub const PROFILE_SCHEMA_VERSION: u32 = 1;
+
+/// 实例 id：UUID 形状的稳定标识。
+#[derive(Debug, Clone, Default, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
+#[serde(transparent)]
+pub struct ProfileId(String);
+
+impl ProfileId {
+    /// 生成一个新 id（v4 形状）。
+    ///
+    /// **不是密码学随机**：由纳秒时间戳 + 进程 id + 进程内计数器经 SplitMix64 混合而来，
+    /// 足以保证单机唯一；删除实例后不复用即可。真要密码学随机，阶段 B 引 `uuid` crate。
+    pub fn generate() -> Self {
+        static COUNTER: AtomicU64 = AtomicU64::new(0);
+
+        let nanos = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .map_or(0, |d| d.as_nanos() as u64);
+        let seq = COUNTER.fetch_add(1, Ordering::Relaxed);
+        let mut seed = nanos ^ u64::from(std::process::id()).rotate_left(17) ^ seq.rotate_left(41);
+
+        let mut bytes = [0u8; 16];
+        for chunk in bytes.chunks_mut(8) {
+            seed = split_mix64(seed);
+            let source = seed.to_le_bytes();
+            chunk.copy_from_slice(&source[..chunk.len()]);
+        }
+        // RFC 4122 v4 形状：版本位 + 变体位。
+        bytes[6] = (bytes[6] & 0x0F) | 0x40;
+        bytes[8] = (bytes[8] & 0x3F) | 0x80;
+
+        let mut hex = String::with_capacity(36);
+        for (index, byte) in bytes.iter().enumerate() {
+            if matches!(index, 4 | 6 | 8 | 10) {
+                hex.push('-');
+            }
+            hex.push_str(&format!("{byte:02x}"));
+        }
+        Self(hex)
+    }
+
+    /// 从字符串构造（不校验，用于读回历史档案；校验用 [`ProfileId::is_uuid_shaped`]）。
+    pub fn new(raw: impl Into<String>) -> Self {
+        Self(raw.into())
+    }
+
+    /// 字符串视图。
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+
+    /// 是否是 UUID 形状（`8-4-4-4-12` 十六进制）。
+    pub fn is_uuid_shaped(&self) -> bool {
+        let bytes = self.0.as_bytes();
+        if bytes.len() != 36 {
+            return false;
+        }
+        bytes.iter().enumerate().all(|(index, byte)| match index {
+            8 | 13 | 18 | 23 => *byte == b'-',
+            _ => byte.is_ascii_hexdigit(),
+        })
+    }
+}
+
+fn split_mix64(mut state: u64) -> u64 {
+    state = state.wrapping_add(0x9E37_79B9_7F4A_7C15);
+    let mut z = state;
+    z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
+    z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
+    z ^ (z >> 31)
+}
+
+impl fmt::Display for ProfileId {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(&self.0)
+    }
+}
+
+impl FromStr for ProfileId {
+    type Err = std::convert::Infallible;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        Ok(Self(s.to_owned()))
+    }
+}
+
+impl From<String> for ProfileId {
+    fn from(value: String) -> Self {
+        Self(value)
+    }
+}
+
+/// 一个实例档案。
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct InstanceProfile {
+    /// 稳定 id。
+    pub id: ProfileId,
+    /// 展示名。
+    #[serde(default)]
+    pub name: String,
+    /// 绑定的版本 id（`versions/<id>/`）。
+    #[serde(default)]
+    pub version_id: String,
+    /// 独立游戏目录；`None` 表示使用全局 `.minecraft`。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub game_dir: Option<PathBuf>,
+    /// 工作目录覆盖（HMCL 的"版本隔离"）。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub running_dir: Option<PathBuf>,
+    /// Java 路径覆盖。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub java_path: Option<PathBuf>,
+    /// 创建时间（RFC-3339 字符串，由调用方填写）。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub created_at: Option<String>,
+    /// 最近启动时间。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub last_played_at: Option<String>,
+    /// 未识别字段原样保留（向前兼容）。
+    #[serde(flatten)]
+    pub extra: BTreeMap<String, serde_json::Value>,
+}
+
+impl InstanceProfile {
+    /// 建一个最小档案（新实例默认值）。
+    pub fn new(name: impl Into<String>, version_id: impl Into<String>) -> Self {
+        Self {
+            id: ProfileId::generate(),
+            name: name.into(),
+            version_id: version_id.into(),
+            ..Self::default()
+        }
+    }
+}
+
+/// `profiles.json` 的内容。
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct ProfileList {
+    /// schema 版本。
+    #[serde(default = "default_schema_version")]
+    pub schema_version: u32,
+    /// 档案列表（顺序即 UI 顺序）。
+    #[serde(default)]
+    pub profiles: Vec<InstanceProfile>,
+}
+
+fn default_schema_version() -> u32 {
+    PROFILE_SCHEMA_VERSION
+}
+
+impl Default for ProfileList {
+    fn default() -> Self {
+        Self {
+            schema_version: PROFILE_SCHEMA_VERSION,
+            profiles: Vec::new(),
+        }
+    }
+}
+
+impl ProfileList {
+    /// 按 id 查。
+    pub fn get(&self, id: &ProfileId) -> Option<&InstanceProfile> {
+        self.profiles.iter().find(|p| &p.id == id)
+    }
+
+    /// 按 id 改。
+    pub fn get_mut(&mut self, id: &ProfileId) -> Option<&mut InstanceProfile> {
+        self.profiles.iter_mut().find(|p| &p.id == id)
+    }
+
+    /// 插入或替换同 id 档案，返回被替换的旧档案。
+    pub fn upsert(&mut self, profile: InstanceProfile) -> Option<InstanceProfile> {
+        match self.profiles.iter().position(|p| p.id == profile.id) {
+            Some(index) => Some(std::mem::replace(&mut self.profiles[index], profile)),
+            None => {
+                self.profiles.push(profile);
+                None
+            }
+        }
+    }
+
+    /// 删除档案，返回被删的档案。
+    pub fn remove(&mut self, id: &ProfileId) -> Option<InstanceProfile> {
+        let index = self.profiles.iter().position(|p| &p.id == id)?;
+        Some(self.profiles.remove(index))
+    }
+
+    /// 绑定到某版本的档案（同一版本可以有多个实例：隔离目录不同）。
+    pub fn for_version(&self, version_id: &str) -> Vec<&InstanceProfile> {
+        self.profiles
+            .iter()
+            .filter(|p| p.version_id == version_id)
+            .collect()
+    }
+
+    /// 档案数。
+    pub fn len(&self) -> usize {
+        self.profiles.len()
+    }
+
+    /// 是否没有档案。
+    pub fn is_empty(&self) -> bool {
+        self.profiles.is_empty()
+    }
+
+    /// 解析 `profiles.json`。
+    ///
+    /// # Errors
+    ///
+    /// JSON 非法时返回 [`super::error::GameError::Json`]。
+    pub fn from_json_str(json: &str) -> Result<Self, super::error::GameError> {
+        serde_json::from_str(json).map_err(|e| super::error::GameError::json("profiles", e))
+    }
+
+    /// 序列化（格式化输出，便于用户手改与 diff）。
+    ///
+    /// # Errors
+    ///
+    /// 序列化失败时返回 [`super::error::GameError::Json`]。
+    pub fn to_json_string(&self) -> Result<String, super::error::GameError> {
+        serde_json::to_string_pretty(self).map_err(|e| super::error::GameError::json("profiles", e))
+    }
+}
diff --git a/crates/core/src/game/snapshot.rs b/crates/core/src/game/snapshot.rs
new file mode 100644
index 0000000..c224721
--- /dev/null
+++ b/crates/core/src/game/snapshot.rs
@@ -0,0 +1,174 @@
+//! 不可变快照 + 单写者草稿（Snapshot / Draft）。
+//!
+//! 依据：`DevDocs/analyse/01-architecture-overview.md` §3.3（HMCL 最值得抄的一处设计）、
+//! `DevDocs/PlanDoc/01-tech-stack-and-architecture.md` 公理 2。
+//!
+//! 收益：**读端永远看到一整份自洽的数据**，不会出现"遍历到一半列表被改"
+//! （HMCL 老式 `synchronized` 实现的典型 bug）。写端同一时刻只允许一个草稿，
+//! 发布 = 指针交换，读端持有的旧快照继续有效直到自己放手。
+//!
+//! **实现说明**：读路径持一把共享锁，只为把 `Arc` 克隆出来（纳秒级），随后所有遍历都在锁外；
+//! 真正的无锁读需要 `arc-swap` 这类依赖，P0 不引入（core 依赖面越窄越好）。
+//! 与 HMCL 的另一处差异：**发布不需要 UI 线程桥接**——发布是纯指针交换，
+//! 订阅通知属于 app 层（`crates/app`），core 不做线程模型假设。
+
+use std::fmt;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, RwLock};
+
+use super::error::GameError;
+
+/// 一份不可变快照：克隆只是 `Arc` 计数，内容只读。
+pub struct Snapshot<T> {
+    data: Arc<T>,
+}
+
+impl<T> Snapshot<T> {
+    /// 用给定内容构造快照。
+    pub fn new(data: T) -> Self {
+        Self {
+            data: Arc::new(data),
+        }
+    }
+
+    /// 读内容。
+    pub fn get(&self) -> &T {
+        &self.data
+    }
+
+    /// 共享同一份内容的强引用。
+    pub fn shared(&self) -> Arc<T> {
+        Arc::clone(&self.data)
+    }
+}
+
+impl<T> Clone for Snapshot<T> {
+    fn clone(&self) -> Self {
+        Self {
+            data: Arc::clone(&self.data),
+        }
+    }
+}
+
+impl<T: fmt::Debug> fmt::Debug for Snapshot<T> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_tuple("Snapshot").field(&self.data).finish()
+    }
+}
+
+impl<T: PartialEq> PartialEq for Snapshot<T> {
+    fn eq(&self, other: &Self) -> bool {
+        self.data == other.data
+    }
+}
+
+/// 写权凭证：唯一的写权持有者，`drop` 即释放（发布与放弃都走它）。
+struct WriteToken<'a> {
+    store: &'a AtomicBool,
+}
+
+impl<'a> WriteToken<'a> {
+    fn acquire(flag: &'a AtomicBool) -> Result<Self, GameError> {
+        if flag
+            .compare_exchange(false, true, Ordering::AcqRel, Ordering::Acquire)
+            .is_err()
+        {
+            return Err(GameError::DraftBusy);
+        }
+        Ok(Self { store: flag })
+    }
+}
+
+impl Drop for WriteToken<'_> {
+    fn drop(&mut self) {
+        self.store.store(false, Ordering::Release);
+    }
+}
+
+/// 快照仓库：持有当前快照，串行化写入。
+pub struct Store<T> {
+    current: RwLock<Arc<T>>,
+    writing: AtomicBool,
+}
+
+impl<T: Clone> Store<T> {
+    /// 以初始内容建立仓库。
+    pub fn new(initial: T) -> Self {
+        Self {
+            current: RwLock::new(Arc::new(initial)),
+            writing: AtomicBool::new(false),
+        }
+    }
+
+    /// 取当前快照（读路径：一次共享锁 + `Arc` 克隆，锁内不做别的）。
+    pub fn snapshot(&self) -> Snapshot<T> {
+        let guard = self.current.read().unwrap_or_else(|e| e.into_inner());
+        Snapshot {
+            data: Arc::clone(&guard),
+        }
+    }
+
+    /// 打开草稿（写会话）。同一时刻只允许一个，违反单写者约束返回
+    /// [`GameError::DraftBusy`]。
+    pub fn open_draft(&self) -> Result<Draft<'_, T>, GameError> {
+        let token = WriteToken::acquire(&self.writing)?;
+        let working = self.snapshot().get().clone();
+        Ok(Draft {
+            store: self,
+            token,
+            working,
+        })
+    }
+
+    /// 整表替换（加载完成后一次性发布，仍受单写者约束）。
+    pub fn replace(&self, value: T) -> Result<Snapshot<T>, GameError> {
+        let mut draft = self.open_draft()?;
+        *draft.edit() = value;
+        Ok(draft.commit())
+    }
+}
+
+/// 草稿：持有写权的可变副本。
+///
+/// 未 [`commit`](Draft::commit) 就 `drop` 会**放弃改动并释放写权**（不会污染快照）。
+pub struct Draft<'a, T> {
+    store: &'a Store<T>,
+    token: WriteToken<'a>,
+    working: T,
+}
+
+impl<T> Draft<'_, T> {
+    /// 读草稿内容。
+    pub fn view(&self) -> &T {
+        &self.working
+    }
+
+    /// 改草稿内容。
+    pub fn edit(&mut self) -> &mut T {
+        &mut self.working
+    }
+
+    /// 发布：把草稿内容换成仓库当前快照，并释放写权。
+    pub fn commit(self) -> Snapshot<T> {
+        let Draft {
+            store,
+            token,
+            working,
+        } = self;
+        let snapshot = Snapshot::new(working);
+        {
+            let mut guard = store.current.write().unwrap_or_else(|e| e.into_inner());
+            *guard = snapshot.shared();
+        }
+        drop(token);
+        snapshot
+    }
+}
+
+impl<T: fmt::Debug> fmt::Debug for Draft<'_, T> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("Draft")
+            .field("working", &self.working)
+            .finish()
+    }
+}
diff --git a/crates/core/src/game/unlisted.rs b/crates/core/src/game/unlisted.rs
new file mode 100644
index 0000000..6d939bc
--- /dev/null
+++ b/crates/core/src/game/unlisted.rs
@@ -0,0 +1,54 @@
+//! 内嵌补充清单 `unlisted-versions.json`（205 条，编进二进制）。
+//!
+//! 官方清单本来就有 `old_beta`/`old_alpha`，但**不完整**：大量 alpha/classic 构建、
+//! `pending` 实验快照、`_unobfuscated` 版本从未进官方清单。
+//! HMCL 的做法是把社区维护的补充清单编进发行包，换取"零网络依赖也能列出旧版"，
+//! 依据见 `DevDocs/analyse/03-version-download.md` §2.3。
+//!
+//! 数据来源：HMCL `HMCLCore/src/main/resources/assets/game/unlisted-versions.json`
+//! （实测 205 条：`old_alpha 88` / `old_beta 16` / `snapshot 70` / `pending 20` /
+//! `unobfuscated 11`），原样拷进 `game/data/` 由 `include_str!` 内嵌。
+//!
+//! **与 HMCL 的差异**：同 id 冲突时我们让**官方条目胜出**。理由是官方 v2 清单带
+//! `sha1`/`size` 且更新鲜；HMCL 因先插 unlisted 进 `TreeSet` 而让社区条目抢了同 id，
+//! 会把官方 URL 换成社区镜像 URL（analyse/03 §2.5）。补充清单只用来补官方缺口。
+//! 后续计划（analyse/03 §2.3 建议）：把该清单改为可远程更新的数据 + ETag 缓存，
+//! 内嵌版本降级为离线回退。
+
+use std::sync::OnceLock;
+
+use super::version::{RemoteVersion, VersionList};
+
+/// 内嵌清单的原始 JSON（`crates/core/src/game/data/unlisted-versions.json`）。
+const EMBEDDED_UNLISTED_JSON: &str = include_str!("data/unlisted-versions.json");
+
+/// 内嵌清单预期的条目数，用于数据完整性自检与文档口径一致。
+pub const EMBEDDED_VERSION_COUNT: usize = 205;
+
+static UNLISTED: OnceLock<VersionList> = OnceLock::new();
+
+/// 内嵌补充清单（进程内只解析一次）。
+///
+/// # Panics
+///
+/// 内嵌数据是编译期常量，可解析性由 `tests/game/unlisted.rs` 守门；
+/// 若构建产物被破坏导致解析失败则 panic——这是构建错误，不是运行时输入错误。
+pub fn versions() -> &'static VersionList {
+    UNLISTED.get_or_init(|| {
+        VersionList::from_json_str(EMBEDDED_UNLISTED_JSON)
+            .expect("内嵌 unlisted-versions.json 必须可解析")
+    })
+}
+
+/// 内嵌清单的条目（借用）。
+pub fn entries() -> &'static [RemoteVersion] {
+    &versions().versions
+}
+
+/// 把内嵌补充清单合并进给定清单，返回新增条目数。
+///
+/// 同 id 时**保留已有条目**（官方胜出，理由见模块注释）；新条目按数据文件原顺序追加，
+/// 调用方如需展示顺序再调用 [`VersionList::sort_newest_first`]。
+pub fn merge_into(target: &mut VersionList) -> usize {
+    target.merge_missing(entries().iter().cloned())
+}
diff --git a/crates/core/src/game/version.rs b/crates/core/src/game/version.rs
new file mode 100644
index 0000000..bdd6c91
--- /dev/null
+++ b/crates/core/src/game/version.rs
@@ -0,0 +1,238 @@
+//! 版本清单（`version_manifest_v2.json`）模型、分类与合并。
+//!
+//! 设计依据：`DevDocs/analyse/03-version-download.md` §2（清单处理）、§2.4（三层分类）、
+//! §2.5（排序与相等）、§2.2（v2 的 `sha1`/`size` 校验字段）。
+//!
+//! 与 HMCL 的差异（有意为之）：
+//! - **直接用 v2 端点**并保留 `sha1`/`size`，让"清单被镜像篡改/截断"在下载阶段就暴露；
+//! - 分类枚举保留 `pending`/`unobfuscated`/`modified`，不再压进 `OLD` 桶后又让过滤器不一致；
+//! - 未知 `type` 值不丢弃整条记录，落到 [`ReleaseType::Unknown`]（对应 HMCL 的 null）。
+
+use std::fmt;
+
+use serde::{Deserialize, Deserializer, Serialize, Serializer};
+
+use super::error::GameError;
+
+/// Mojang 官方清单 v2 端点（带 `sha1`/`size`）。
+pub const VERSION_MANIFEST_V2_URL: &str =
+    "https://piston-meta.mojang.com/mc/game/version_manifest_v2.json";
+
+/// 版本 JSON 里 `type` 字段的取值，见 analyse/03 §2.4。
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash)]
+pub enum ReleaseType {
+    /// 正式版。
+    Release,
+    /// 快照（含愚人节、`pending` 之外的实验构建）。
+    Snapshot,
+    /// 远古 beta。
+    OldBeta,
+    /// 远古 alpha（含 classic、`rd-`/`inf-` 系列归此）。
+    OldAlpha,
+    /// `pending`：已推送 JSON 但未正式发布的构建。
+    Pending,
+    /// `_unobfuscated` 形式的反混淆构建（官方 CDN 有、普通清单没有）。
+    Unobfuscated,
+    /// 第三方/魔改清单自定义分类。
+    Modified,
+    /// 未知取值——保留记录但无法分类（HMCL 里是 `null`）。
+    #[default]
+    Unknown,
+}
+
+impl ReleaseType {
+    /// 从 JSON 原始字符串解析（未知值落到 `Unknown`，不报错）。
+    pub fn from_json_str(raw: &str) -> Self {
+        match raw {
+            "release" => Self::Release,
+            "snapshot" => Self::Snapshot,
+            "old_beta" => Self::OldBeta,
+            "old_alpha" => Self::OldAlpha,
+            "pending" => Self::Pending,
+            "unobfuscated" => Self::Unobfuscated,
+            "modified" => Self::Modified,
+            _ => Self::Unknown,
+        }
+    }
+
+    /// 回到 JSON 原始字符串。
+    pub fn as_json_str(self) -> &'static str {
+        match self {
+            Self::Release => "release",
+            Self::Snapshot => "snapshot",
+            Self::OldBeta => "old_beta",
+            Self::OldAlpha => "old_alpha",
+            Self::Pending => "pending",
+            Self::Unobfuscated => "unobfuscated",
+            Self::Modified => "modified",
+            Self::Unknown => "unknown",
+        }
+    }
+
+    /// UI 侧的归类（analyse/03 §2.4 的五态，去掉 `uncategorized` 之外的分歧）。
+    pub fn category(self) -> VersionCategory {
+        match self {
+            Self::Release => VersionCategory::Release,
+            Self::Snapshot => VersionCategory::Snapshot,
+            Self::OldBeta | Self::OldAlpha | Self::Modified => VersionCategory::Old,
+            Self::Pending => VersionCategory::Pending,
+            Self::Unobfuscated => VersionCategory::Unobfuscated,
+            Self::Unknown => VersionCategory::Uncategorized,
+        }
+    }
+}
+
+impl fmt::Display for ReleaseType {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(self.as_json_str())
+    }
+}
+
+impl Serialize for ReleaseType {
+    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        serializer.serialize_str(self.as_json_str())
+    }
+}
+
+impl<'de> Deserialize<'de> for ReleaseType {
+    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        let raw = String::deserialize(deserializer)?;
+        Ok(Self::from_json_str(&raw))
+    }
+}
+
+/// 版本列表的 UI 归类（对应 HMCL `ComponentRemoteVersion.Type`，见 analyse/03 §2.4）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum VersionCategory {
+    /// 正式版。
+    Release,
+    /// 快照。
+    Snapshot,
+    /// 远古版（old_beta / old_alpha / modified）。
+    Old,
+    /// 未正式发布的 pending 构建。
+    Pending,
+    /// 反混淆构建。
+    Unobfuscated,
+    /// 无法归类。
+    Uncategorized,
+}
+
+/// 清单里的 `latest` 对象。Mojang 用它标注"当前最新正式版/快照"，与条目列表无关。
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct LatestVersions {
+    /// 最新正式版 id。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub release: Option<String>,
+    /// 最新快照 id。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub snapshot: Option<String>,
+}
+
+/// 版本清单里的一条记录。
+///
+/// `sha1`/`size` 只在 v2 端点出现（v1 与内嵌 unlisted 清单没有），因此都是可选的。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct RemoteVersion {
+    /// 版本 id（`1.20.1`、`12w01a`、`a1.1.1`…）。
+    pub id: String,
+    /// 分类。
+    #[serde(rename = "type", default)]
+    pub version_type: ReleaseType,
+    /// 该版本 JSON 的下载地址。
+    pub url: String,
+    /// 该版本 JSON 的最后修改时间（ISO-8601 字符串）。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub time: Option<String>,
+    /// 该版本的发布时刻（ISO-8601 字符串，排序键）。
+    #[serde(
+        rename = "releaseTime",
+        default,
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub release_time: Option<String>,
+    /// 版本 JSON 的 SHA-1（v2 才有）。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub sha1: Option<String>,
+    /// 版本 JSON 的字节数（v2 才有）。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub size: Option<u64>,
+}
+
+impl RemoteVersion {
+    /// 该条目是否带 v2 的校验信息。
+    pub fn is_verifiable(&self) -> bool {
+        self.sha1.is_some()
+    }
+}
+
+/// 一份版本清单（官方 `version_manifest_v2.json` 或内嵌 unlisted 清单）。
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct VersionList {
+    /// `latest` 对象；unlisted 清单没有。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub latest: Option<LatestVersions>,
+    /// 条目列表。
+    #[serde(default)]
+    pub versions: Vec<RemoteVersion>,
+}
+
+impl VersionList {
+    /// 解析清单 JSON。
+    pub fn from_json_str(json: &str) -> Result<Self, GameError> {
+        serde_json::from_str(json).map_err(|e| GameError::json("version_manifest", e))
+    }
+
+    /// 序列化回 JSON（便于缓存落盘/测试对拍）。
+    pub fn to_json_string(&self) -> Result<String, GameError> {
+        serde_json::to_string(self).map_err(|e| GameError::json("version_manifest", e))
+    }
+
+    /// 按 id 查条目。
+    pub fn find(&self, id: &str) -> Option<&RemoteVersion> {
+        self.versions.iter().find(|v| v.id == id)
+    }
+
+    /// 已存在的版本 id 数。
+    pub fn len(&self) -> usize {
+        self.versions.len()
+    }
+
+    /// 是否为空清单。
+    pub fn is_empty(&self) -> bool {
+        self.versions.is_empty()
+    }
+
+    /// 合并补充清单：**同 id 时先插入者胜**（analyse/03 §2.5 的 `TreeSet` 语义）。
+    ///
+    /// 调用方应先合并 unlisted 再合并官方清单，这样社区清单里那些"官方没有/官方 URL 更差"
+    /// 的条目会被保留。返回新插入的条目数。
+    pub fn merge_missing(&mut self, extra: impl IntoIterator<Item = RemoteVersion>) -> usize {
+        let mut added = 0;
+        for item in extra {
+            if self.find(&item.id).is_some() {
+                continue;
+            }
+            self.versions.push(item);
+            added += 1;
+        }
+        added
+    }
+
+    /// 按发布时间**倒序**排列；同时间再按 id 倒序（analyse/03 §2.5）。
+    pub fn sort_newest_first(&mut self) {
+        self.versions.sort_by(|a, b| {
+            let at = a.release_time.as_deref().unwrap_or_default();
+            let bt = b.release_time.as_deref().unwrap_or_default();
+            bt.cmp(at).then_with(|| b.id.cmp(&a.id))
+        });
+    }
+
+    /// 按 UI 归类过滤（保持当前顺序）。
+    pub fn filter_category(&self, category: VersionCategory) -> Vec<&RemoteVersion> {
+        self.versions
+            .iter()
+            .filter(|v| v.version_type.category() == category)
+            .collect()
+    }
+}
diff --git a/crates/core/src/launch/adapter.rs b/crates/core/src/launch/adapter.rs
new file mode 100644
index 0000000..0b4729f
--- /dev/null
+++ b/crates/core/src/launch/adapter.rs
@@ -0,0 +1,368 @@
+//! game 快照 → [`LaunchRequest`] 的适配层。
+//!
+//! launch 不 import `crate::game` 的**清单类型**（避免对 M14 的模型产生编译期耦合，见
+//! `DevDocs/SubAgentsTalk/launch-接口约定.md` §6）：本模块只吃 game 侧**已经算好**的纯数据——
+//! `arguments.expand(&env)` 的展开结果（rules 已在 game 求值）、库文件路径、目录布局，
+//! 把它们装配成命令行组装所需的结构。
+//!
+//! 唯一例外是 [`crate::game::capability`] 里的 `&str → bool` 纯谓词：能力位的判据属于
+//! 版本 JSON 的语义、必须只有一处实现，抄第二份必然漂移。它不带任何 game 结构体。
+//!
+//! 三个职责：
+//! 1. classpath 过滤 + **缺失库显式记录**（analyse/02 §8.4-3：不再静默跳过，否则只能靠
+//!    `NoClassDefFoundError` 事后猜）；
+//! 2. features 开关的派生（`has_custom_resolution` / `has_quick_plays_support`）；
+//! 3. 组装 `LaunchRequest`（内存/账户/加载器/分辨率/QuickPlay/代理/日志配置）。
+
+use std::path::PathBuf;
+
+use crate::game::capability::library_names_have_vulkan;
+use crate::launch::argument::ArgumentEntry;
+use crate::launch::error::MissingComponent;
+use crate::launch::game_version::GameVersion;
+use crate::launch::natives::{NativeJar, NativesEra, NativesPlan};
+use crate::launch::request::{
+    AuthPlaceholders, FeatureSet, InstanceInfo, JavaSelection, LaunchDirs, LaunchRequest,
+    LauncherInfo, Log4jOptions, ManifestArgs, MemoryOptions, ModLoaderKind, OptimizationOptions,
+    QuickPlay, RendererOptions, Resolution, SocksProxy, UserArgs,
+};
+
+/// 一个待进 classpath 的库（game 侧已按环境过滤）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LibraryInput {
+    /// 落盘路径（`GameLayout::library(coord)` 的结果）。
+    pub path: PathBuf,
+    /// 坐标或展示名（缺失时报错用，例 `org.lwjgl:lwjgl:3.3.1`）。
+    pub name: String,
+}
+
+impl LibraryInput {
+    /// 构造。
+    pub fn new(path: impl Into<PathBuf>, name: impl Into<String>) -> Self {
+        Self {
+            path: path.into(),
+            name: name.into(),
+        }
+    }
+}
+
+/// 版本快照里 launch 需要的部分（全部是纯数据，不依赖 game 类型）。
+#[derive(Debug, Clone)]
+pub struct SnapshotInput<'a> {
+    /// 版本 id（`versions/<id>/`）。
+    pub version_id: &'a str,
+    /// 展示名（缺省用 version_id）。
+    pub version_name: Option<&'a str>,
+    /// 版本类型（`release` / `snapshot`）。
+    pub version_type: Option<&'a str>,
+    /// 游戏版本串（门限判断用；缺省用 version_id）。
+    pub game_version: Option<&'a str>,
+    /// 主类。
+    pub main_class: Option<&'a str>,
+    /// `arguments.jvm` 展开后的 token。
+    pub jvm_arguments: &'a [String],
+    /// `arguments.game` 展开后的 token。
+    pub game_arguments: &'a [String],
+    /// 旧版 `minecraftArguments` 整串。
+    pub legacy_arguments: Option<&'a str>,
+    /// 待进 classpath 的库（已过滤环境、不含 native）。
+    pub libraries: &'a [LibraryInput],
+    /// natives 分类器构件（`natives` 表命中的 jar；1.19+ 为空，natives jar 在 classpath 里）。
+    pub natives: &'a [NativeJar],
+    /// 主 jar 路径。
+    pub primary_jar: PathBuf,
+    /// 运行目录（`${game_directory}`）。
+    pub game_dir: PathBuf,
+    /// 资产索引 id。
+    pub assets_index: Option<&'a str>,
+    /// 原生库目录。
+    pub natives_dir: PathBuf,
+    /// 库根目录。
+    pub library_dir: PathBuf,
+    /// 资产根。
+    pub assets_root: PathBuf,
+    /// 虚拟资产目录（`${game_assets}`；无虚拟化时等于 assets_root）。
+    pub game_assets: PathBuf,
+}
+
+impl<'a> SnapshotInput<'a> {
+    /// 最小构造：只给版本 id 与主类，其余留空（测试/CLI 组装用）。
+    pub fn minimal(version_id: &'a str, main_class: &'a str) -> Self {
+        Self {
+            version_id,
+            version_name: None,
+            version_type: None,
+            game_version: None,
+            main_class: Some(main_class),
+            jvm_arguments: &[],
+            game_arguments: &[],
+            legacy_arguments: None,
+            libraries: &[],
+            natives: &[],
+            primary_jar: PathBuf::new(),
+            game_dir: PathBuf::new(),
+            assets_index: None,
+            natives_dir: PathBuf::new(),
+            library_dir: PathBuf::new(),
+            assets_root: PathBuf::new(),
+            game_assets: PathBuf::new(),
+        }
+    }
+
+    fn resolved_version(&self) -> GameVersion {
+        GameVersion::parse(self.game_version.unwrap_or(self.version_id))
+    }
+}
+
+/// 适配选项（账户/内存/加载器/一键进入等运行期选择）。
+#[derive(Debug, Clone, Default)]
+pub struct AdapterOptions {
+    /// Java 运行时。
+    pub java: JavaSelection,
+    /// 内存。
+    pub memory: MemoryOptions,
+    /// 账户占位符。
+    pub auth: AuthPlaceholders,
+    /// 启动器名（`${launcher_name}`）。
+    pub launcher_name: String,
+    /// 启动器版本（`${launcher_version}`）。
+    pub launcher_version: String,
+    /// 模组加载器。
+    pub mod_loader: ModLoaderKind,
+    /// 分辨率（`Some` 时自动打开 `has_custom_resolution`）。
+    pub resolution: Option<Resolution>,
+    /// 全屏。
+    pub fullscreen: bool,
+    /// 一键进入。
+    pub quick_play: Option<QuickPlay>,
+    /// SOCKS 代理。
+    pub proxy: Option<SocksProxy>,
+    /// 图形后端。
+    pub graphics_backend: Option<String>,
+    /// log4j 配置文件（launch 侧注入）。
+    pub log4j_config: Option<PathBuf>,
+    /// `-Dfile.encoding` 指定值。
+    pub encoding: Option<String>,
+    /// 界面语言。
+    pub language: String,
+    /// 额外环境变量。
+    pub environment: Vec<(String, String)>,
+    /// JVM 自动优化。
+    pub optimization: OptimizationOptions,
+    /// 渲染器开关。
+    pub renderer: RendererOptions,
+    /// 用户自定义参数。
+    pub user: UserArgs,
+    /// 是否要求库文件真实存在。
+    ///
+    /// - `true`（默认，严格）：缺库/缺主 jar → 记 `AdapterWarning::MissingLibrary` 并填进
+    ///   `missing_components`，组装前显式失败（analyse/02 §8.4-3）；
+    /// - `false`（宽松，HMCL 行为）：**不检查存在性、不跳过、不告警**，库照进 classpath，
+    ///   交给运行时（`NoClassDefFoundError`）——仅在用户明确选“跳过校验”时用。
+    pub check_classpath: bool,
+}
+
+impl AdapterOptions {
+    /// 默认严格模式：库必须存在（analyse/02 §8.4-3）。
+    pub fn strict() -> Self {
+        Self {
+            check_classpath: true,
+            language: "zh-CN".to_string(),
+            ..Self::default()
+        }
+    }
+}
+
+/// 适配告警（非致命）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum AdapterWarning {
+    /// 库文件缺失（严格模式下同时会变成 `missing_components` → 组装失败）。
+    MissingLibrary {
+        /// 坐标/展示名。
+        name: String,
+        /// 期望路径。
+        path: PathBuf,
+    },
+    /// 既没有展开后的游戏参数，也没有 legacy 整串。
+    MissingGameArguments,
+    /// 没有资产索引 id（`${assets_index_name}` 会是空串）。
+    MissingAssetsIndex,
+    /// 主类缺失（组装一定会报错，这里提前给出中文提示）。
+    MissingMainClass,
+    /// natives 分类器 jar 缺失（严格模式下同时会变成 `missing_components` → 组装失败）。
+    MissingNativeJar {
+        /// 坐标 + 分类器。
+        name: String,
+        /// 期望路径。
+        path: PathBuf,
+    },
+}
+
+/// 适配结果。
+#[derive(Debug, Clone)]
+pub struct AdapterOutput {
+    /// 组装输入。
+    pub request: LaunchRequest,
+    /// 告警。
+    pub warnings: Vec<AdapterWarning>,
+    /// 实际进 classpath 的条目数（库 + 主 jar）。
+    pub classpath_entries: usize,
+    /// 缺失库清单。
+    pub missing: Vec<MissingComponent>,
+}
+
+/// 把快照 + 选项装配成 [`LaunchRequest`]。
+pub fn build_request(snapshot: &SnapshotInput<'_>, options: AdapterOptions) -> AdapterOutput {
+    let mut warnings = Vec::new();
+    let mut missing = Vec::new();
+    let mut classpath = Vec::new();
+    for library in snapshot.libraries {
+        if options.check_classpath && !library.path.is_file() {
+            warnings.push(AdapterWarning::MissingLibrary {
+                name: library.name.clone(),
+                path: library.path.clone(),
+            });
+            missing.push(MissingComponent::at_path(
+                library.name.clone(),
+                library.path.clone(),
+            ));
+            continue;
+        }
+        if options.check_classpath && classpath.contains(&library.path) {
+            continue;
+        }
+        classpath.push(library.path.clone());
+    }
+    if !snapshot.primary_jar.as_os_str().is_empty()
+        && options.check_classpath
+        && !snapshot.primary_jar.is_file()
+    {
+        let name = snapshot
+            .primary_jar
+            .file_name()
+            .map(|name| name.to_string_lossy().into_owned())
+            .unwrap_or_else(|| "client.jar".to_string());
+        warnings.push(AdapterWarning::MissingLibrary {
+            name: name.clone(),
+            path: snapshot.primary_jar.clone(),
+        });
+        missing.push(MissingComponent::at_path(
+            name,
+            snapshot.primary_jar.clone(),
+        ));
+    }
+    if snapshot.main_class.is_none() {
+        warnings.push(AdapterWarning::MissingMainClass);
+    }
+    if snapshot.assets_index.is_none() {
+        warnings.push(AdapterWarning::MissingAssetsIndex);
+    }
+    if snapshot.game_arguments.is_empty() && snapshot.legacy_arguments.is_none() {
+        warnings.push(AdapterWarning::MissingGameArguments);
+    }
+    // natives jar 缺失同样属「组件缺失」：解压期才发现会只剩一句 UnsatisfiedLinkError。
+    for native in snapshot.natives {
+        if options.check_classpath && !native.path.is_file() {
+            warnings.push(AdapterWarning::MissingNativeJar {
+                name: native.name.clone(),
+                path: native.path.clone(),
+            });
+            missing.push(MissingComponent::at_path(
+                native.name.clone(),
+                native.path.clone(),
+            ));
+        }
+    }
+
+    let version = snapshot.resolved_version();
+    let features = FeatureSet {
+        has_custom_resolution: options.resolution.is_some(),
+        is_demo_user: false,
+        has_quick_plays_support: version.is_at_least("1.20"),
+    };
+    let manifest = ManifestArgs {
+        main_class: snapshot.main_class.map(str::to_string),
+        jvm: entries(snapshot.jvm_arguments),
+        game: entries(snapshot.game_arguments),
+        legacy_arguments: snapshot.legacy_arguments.map(str::to_string),
+        has_vulkan_backend: library_names_have_vulkan(
+            snapshot
+                .libraries
+                .iter()
+                .map(|library| library.name.as_str()),
+        ),
+    };
+
+    let classpath_entries =
+        classpath.len() + usize::from(!snapshot.primary_jar.as_os_str().is_empty());
+    let era = NativesEra::detect(snapshot.jvm_arguments.len(), snapshot.natives.len());
+    let natives = NativesPlan {
+        jars: snapshot.natives.to_vec(),
+        era,
+        custom: false,
+    };
+    let request = LaunchRequest {
+        instance: InstanceInfo {
+            id: snapshot.version_id.to_string(),
+            name: snapshot
+                .version_name
+                .unwrap_or(snapshot.version_id)
+                .to_string(),
+            version,
+            version_type: snapshot.version_type.unwrap_or("release").to_string(),
+        },
+        launcher: LauncherInfo {
+            name: options.launcher_name,
+            version: options.launcher_version,
+        },
+        java: options.java,
+        memory: options.memory,
+        manifest,
+        dirs: LaunchDirs {
+            game_dir: snapshot.game_dir.clone(),
+            assets_root: snapshot.assets_root.clone(),
+            game_assets: snapshot.game_assets.clone(),
+            assets_index: snapshot.assets_index.unwrap_or("legacy").to_string(),
+            natives_dir: snapshot.natives_dir.clone(),
+            library_dir: snapshot.library_dir.clone(),
+            primary_jar: snapshot.primary_jar.clone(),
+        },
+        natives,
+        auth: options.auth,
+        user: options.user,
+        features,
+        resolution: options.resolution,
+        quick_play: options.quick_play,
+        proxy: options.proxy,
+        graphics_backend: options.graphics_backend,
+        fullscreen: options.fullscreen,
+        mod_loader: options.mod_loader,
+        log4j: Log4jOptions {
+            enabled: true,
+            config_file: options.log4j_config,
+            debug: false,
+        },
+        renderer: options.renderer,
+        optimization: options.optimization,
+        encoding: options.encoding,
+        language: options.language,
+        classpath,
+        missing_components: missing.clone(),
+        extra_jvm: Vec::new(),
+        ..LaunchRequest::default()
+    };
+    AdapterOutput {
+        request,
+        warnings,
+        classpath_entries,
+        missing,
+    }
+}
+
+fn entries(tokens: &[String]) -> Vec<ArgumentEntry> {
+    if tokens.is_empty() {
+        Vec::new()
+    } else {
+        vec![ArgumentEntry::plain(tokens.iter().cloned())]
+    }
+}
diff --git a/crates/core/src/launch/args_table.rs b/crates/core/src/launch/args_table.rs
new file mode 100644
index 0000000..0cc9370
--- /dev/null
+++ b/crates/core/src/launch/args_table.rs
@@ -0,0 +1,253 @@
+//! 命令行组装总表：`analyse/02` §4.1 的 33 项顺序表的 Rust 化。
+//!
+//! 顺序本身有语义（后加的默认值会被先加的显式值抑制）：
+//!
+//! | # | 内容 | 本文件落点 |
+//! |---|------|-----------|
+//! | 1~3 | `nice` / 用户包装器 / java 可执行文件 | [`assemble`] |
+//! | 4 | 最高优先级 JVM 参数（含 `@argfile` 展开） | [`assemble`] |
+//! | 5~7 | `-Xmx`/`-Xms`、Metaspace、用户 JVM 参数（按默认值） | [`assemble`] |
+//! | 8~17 | 编码、Log4j、主 jar、代理、自动优化、版本开关、FML、渲染器 | `jvm_args` |
+//! | 18~19 | classpath 计算与占位符表（`${classpath}` 等 26 项） | [`assemble`] + `placeholders` |
+//! | 20~32 | 清单 JVM 参数、主类、游戏参数、QuickPlay、代理、图形后端、用户参数 | `game_args` |
+//! | 33 | 删除被禁止参数（`-Xincgc`） | [`assemble`] |
+//!
+//! 组装是**纯函数**：给定 `LaunchRequest` + `PlatformCtx` 一定得到同样的命令行，
+//! 因此可以整体快照测试（`crates/core/tests/launch/cmdline_snapshot.rs`）。
+
+use std::fmt;
+use std::path::PathBuf;
+
+use crate::launch::command_builder::{quote_for_display, CommandBuilder};
+use crate::launch::defaults;
+use crate::launch::error::{AssemblyError, Result};
+use crate::launch::game_args;
+use crate::launch::jvm_args;
+use crate::launch::placeholders::{join_classpath, PlaceholderMap};
+use crate::launch::platform::PlatformCtx;
+use crate::launch::request::{LaunchRequest, MemoryOptions};
+
+/// 组装过程中的“非致命”告警（不中断启动，但要告诉用户我们改了什么）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum AssemblyWarning {
+    /// 注入了 log4j 参数却没有配置文件。
+    Log4jConfigMissing,
+    /// 用户自己写了代理参数，我们跳过自动代理参数。
+    ProxyJvmArgsSkipped,
+    /// `-Xms` 大于 `-Xmx`，已忽略 `-Xms`。
+    MemoryMinIgnored {
+        /// 请求的最小堆。
+        min_mb: u32,
+        /// 请求的最大堆。
+        max_mb: u32,
+    },
+    /// 版本不支持 QuickPlay，已退化成 `--server/--port`。
+    QuickPlayDegraded {
+        /// 原始地址。
+        address: String,
+    },
+    /// 服务器地址非法，QuickPlay 被丢弃。
+    QuickPlayAddressInvalid {
+        /// 原始地址。
+        address: String,
+    },
+    /// 版本不支持 QuickPlay 且无法退化（存档/Realms）。
+    QuickPlayUnsupported {
+        /// 游戏版本。
+        version: String,
+    },
+    /// 版本用不了 `--graphicsBackend`，已丢弃。
+    ///
+    /// 两种来源：可解析版本低于 `26.2-snapshot-2`；或周快照（`26w14a`）但版本库表里
+    /// 没有 `lwjgl-vulkan`（见 `game_args::graphics_backend_allowed`）。
+    GraphicsBackendSkipped {
+        /// 游戏版本。
+        version: String,
+    },
+}
+
+impl fmt::Display for AssemblyWarning {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Log4jConfigMissing => f.write_str("log4j 注入已启用但缺少配置文件，已跳过"),
+            Self::ProxyJvmArgsSkipped => f.write_str("用户已指定代理参数，跳过自动代理 JVM 参数"),
+            Self::MemoryMinIgnored { min_mb, max_mb } => {
+                write!(f, "-Xms{min_mb}m 大于 -Xmx{max_mb}m，已忽略 -Xms")
+            }
+            Self::QuickPlayDegraded { address } => {
+                write!(f, "版本不支持 QuickPlay，已退化为 --server {address}")
+            }
+            Self::QuickPlayAddressInvalid { address } => {
+                write!(f, "服务器地址非法，已丢弃 QuickPlay：{address}")
+            }
+            Self::QuickPlayUnsupported { version } => {
+                write!(f, "版本 {version} 不支持该 QuickPlay 目标，已丢弃")
+            }
+            Self::GraphicsBackendSkipped { version } => {
+                write!(f, "版本 {version} 不支持 --graphicsBackend，已丢弃")
+            }
+        }
+    }
+}
+
+/// 组装结果。
+#[derive(Debug, Clone)]
+pub struct AssembledCommand {
+    /// 实际要 spawn 的程序（通常是 java，带包装器时是包装器）。
+    pub program: PathBuf,
+    /// 参数（不含 `program`）。
+    pub args: Vec<String>,
+    /// 完整 classpath（库 + 主 jar 末位）。
+    pub classpath: Vec<PathBuf>,
+    /// 日志解码编码（决定 pump 用什么解码子进程输出）。
+    pub encoding: String,
+    /// 内存设置（与 `-Xmx`/`-Xms` 一致）。
+    pub memory: MemoryOptions,
+    /// 环境变量（实例标识/渲染/加载器/用户自定义）。
+    pub env: Vec<(String, String)>,
+    /// 组装告警。
+    pub warnings: Vec<AssemblyWarning>,
+    /// 主类。
+    pub main_class: String,
+}
+
+impl AssembledCommand {
+    /// 完整 argv（`program` 在第一个）。
+    pub fn argv(&self) -> Vec<String> {
+        let mut argv = Vec::with_capacity(self.args.len() + 1);
+        argv.push(self.program.display().to_string());
+        argv.extend(self.args.iter().cloned());
+        argv
+    }
+
+    /// 人读形式（含空格的参数加引号），用于日志与快照测试。
+    pub fn display(&self) -> String {
+        let mut parts = Vec::with_capacity(self.args.len() + 1);
+        parts.push(quote_for_display(&self.program.display().to_string()));
+        for arg in &self.args {
+            parts.push(quote_for_display(arg));
+        }
+        parts.join(" ")
+    }
+}
+
+/// 组装完整命令行。
+pub fn assemble(req: &LaunchRequest, ctx: &PlatformCtx) -> Result<AssembledCommand> {
+    let main_class = req
+        .manifest
+        .main_class
+        .as_deref()
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .ok_or(AssemblyError::MissingMainClass)?
+        .to_string();
+    if req.java.binary.as_os_str().is_empty() {
+        return Err(AssemblyError::EmptyJavaPath.into());
+    }
+    if !req.missing_components.is_empty() {
+        return Err(AssemblyError::MissingComponents(req.missing_components.clone()).into());
+    }
+    let classpath = effective_classpath(req);
+    if classpath.is_empty() {
+        return Err(AssemblyError::EmptyClasspath.into());
+    }
+
+    // 第 19 项：占位符表（`${classpath}` 用最终 classpath，主 jar 已在末位）。
+    let mut placeholders = PlaceholderMap::from_request(req, ctx);
+    placeholders.insert(
+        "classpath",
+        join_classpath(&classpath, ctx.path_separator()),
+    );
+
+    // 第 1~3 项：优先级包装 → 用户包装器 → java 可执行文件。
+    let mut head: Vec<String> = Vec::new();
+    if let Some(nice) = req.nice {
+        if ctx.os.is_posix() {
+            head.push("nice".to_string());
+            head.push("-n".to_string());
+            head.push(nice.to_string());
+        }
+    }
+    head.extend(req.wrapper.iter().cloned());
+    head.push(req.java.binary.display().to_string());
+    let program = PathBuf::from(head.remove(0));
+
+    let mut builder = CommandBuilder::with_placeholders(placeholders);
+    for token in &head {
+        builder.add_without_parsing(token.clone());
+    }
+
+    // 第 4 项：最高优先级 JVM 参数（原样追加，且登记 @argfile 展开结果）。
+    builder.add_all_without_parsing_and_read_external(
+        &req.user.override_jvm,
+        &crate::launch::command_builder::read_argfile,
+    );
+
+    let mut warnings = Vec::new();
+
+    // 第 5 项：`-Xmx` / `-Xms`（`-Xms` 必须 ≤ `-Xmx`）。
+    if let Some(max_mb) = req.memory.max_mb {
+        let _ = builder.add_default("-Xmx", &format!("{max_mb}m"));
+    }
+    if let Some(min_mb) = req.memory.min_mb {
+        match req.memory.max_mb {
+            Some(max_mb) if min_mb > max_mb => {
+                warnings.push(AssemblyWarning::MemoryMinIgnored { min_mb, max_mb });
+            }
+            _ => {
+                let _ = builder.add_default("-Xms", &format!("{min_mb}m"));
+            }
+        }
+    }
+
+    // 第 6 项：Metaspace（Java ≥8）或 PermSize（更早）。
+    if req.java.major >= 8 {
+        let _ = builder.add_default("-XX:MetaspaceSize=", "64m");
+    } else {
+        let _ = builder.add_default("-XX:PermSize=", "64m");
+    }
+
+    // 第 7 项：用户 JVM 参数——整体按“默认值”处理。
+    builder.add_all_default(&req.user.jvm);
+
+    // 第 8~17 项。
+    let (encoding, jvm_warnings) = jvm_args::apply_jvm_arguments(req, ctx, &mut builder);
+    warnings.extend(jvm_warnings);
+
+    // 第 20~32 项。
+    warnings.extend(game_args::apply_game_arguments(req, ctx, &mut builder));
+
+    // 第 33 项：删除禁用参数。
+    builder.remove_forbidden(&defaults::forbidden_args(req.java.major));
+
+    let env = defaults::environment(req, ctx.os);
+    Ok(AssembledCommand {
+        program,
+        args: builder.into_args(),
+        classpath,
+        encoding,
+        memory: req.memory,
+        env,
+        warnings,
+        main_class,
+    })
+}
+
+/// 最终 classpath：库按给定顺序去重，主 jar 永远追加在末位（Mojang 惯例，
+/// 影响同名类优先级，`analyse/02` §4.5）。
+pub fn effective_classpath(req: &LaunchRequest) -> Vec<PathBuf> {
+    let mut classpath: Vec<PathBuf> = Vec::new();
+    let candidates = req
+        .classpath
+        .iter()
+        .chain(std::iter::once(&req.dirs.primary_jar));
+    for path in candidates {
+        if path.as_os_str().is_empty() {
+            continue;
+        }
+        if !classpath.contains(path) {
+            classpath.push(path.clone());
+        }
+    }
+    classpath
+}
diff --git a/crates/core/src/launch/argument.rs b/crates/core/src/launch/argument.rs
new file mode 100644
index 0000000..351ba52
--- /dev/null
+++ b/crates/core/src/launch/argument.rs
@@ -0,0 +1,205 @@
+//! 清单参数模型：`arguments.jvm` / `arguments.game` 的 `{rules, value}` 求值。
+//!
+//! 平移自 `analyse/02` §4.7：`Argument` 是 `StringArgument | RuledArgument`，
+//! `CompatibilityRule` 默认 `DISALLOW`、按顺序取最后一个命中的 action；
+//! `os` 不匹配的规则整体“无效”（不是“不满足”），`features` 必须逐项相等。
+
+use crate::launch::request::FeatureSet;
+
+/// 规则动作。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RuleAction {
+    /// 允许。
+    Allow,
+    /// 禁止。
+    Disallow,
+}
+
+/// `rules.os` 子句。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct OsRule {
+    /// `windows` / `osx` / `linux`。
+    pub name: Option<String>,
+    /// `x86` / `x86_64` / `arm64`。
+    pub arch: Option<String>,
+    /// 系统版本模式（Mojang 用正则，这里只做前缀/子串匹配）。
+    pub version: Option<String>,
+}
+
+/// 单条规则。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Rule {
+    /// 命中后的动作。
+    pub action: RuleAction,
+    /// 系统条件。
+    pub os: Option<OsRule>,
+    /// 特性条件（逐项相等才算命中）。
+    pub features: Vec<(String, bool)>,
+}
+
+impl Rule {
+    /// 允许规则。
+    pub fn allow() -> Self {
+        Self {
+            action: RuleAction::Allow,
+            os: None,
+            features: Vec::new(),
+        }
+    }
+
+    /// 禁止规则。
+    pub fn disallow() -> Self {
+        Self {
+            action: RuleAction::Disallow,
+            os: None,
+            features: Vec::new(),
+        }
+    }
+
+    /// 加系统条件。
+    pub fn with_os_name(mut self, name: impl Into<String>) -> Self {
+        let mut os = self.os.take().unwrap_or_default();
+        os.name = Some(name.into());
+        self.os = Some(os);
+        self
+    }
+
+    /// 加特性条件。
+    pub fn with_feature(mut self, name: impl Into<String>, expected: bool) -> Self {
+        self.features.push((name.into(), expected));
+        self
+    }
+
+    /// 求值：`Some(true)` 命中且允许，`Some(false)` 命中且禁止，`None` 不适用（规则无效）。
+    pub fn evaluate(&self, ctx: &RuleContext<'_>) -> Option<bool> {
+        if let Some(os) = &self.os {
+            if let Some(name) = &os.name {
+                if name != ctx.os_name {
+                    return None;
+                }
+            }
+            if let Some(arch) = &os.arch {
+                if !arch_matches(arch, ctx.os_arch) {
+                    return None;
+                }
+            }
+            if let Some(pattern) = &os.version {
+                if !version_matches(pattern, ctx.os_version) {
+                    return None;
+                }
+            }
+        }
+        for (name, expected) in &self.features {
+            if ctx.features.get(name) != Some(*expected) {
+                return None;
+            }
+        }
+        Some(self.action == RuleAction::Allow)
+    }
+}
+
+/// 一个参数项：一组规则 + 一组取值（取值里可含 `${...}` 占位符）。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct ArgumentEntry {
+    /// 规则（空表示无条件适用）。
+    pub rules: Vec<Rule>,
+    /// 取值（每个元素是一个独立命令行 token）。
+    pub values: Vec<String>,
+}
+
+impl ArgumentEntry {
+    /// 无条件参数项。
+    pub fn plain(values: impl IntoIterator<Item = impl Into<String>>) -> Self {
+        Self {
+            rules: Vec::new(),
+            values: values.into_iter().map(Into::into).collect(),
+        }
+    }
+
+    /// 带规则参数项。
+    pub fn ruled(rules: Vec<Rule>, values: impl IntoIterator<Item = impl Into<String>>) -> Self {
+        Self {
+            rules,
+            values: values.into_iter().map(Into::into).collect(),
+        }
+    }
+
+    /// 是否在当前环境下适用。
+    pub fn applies(&self, ctx: &RuleContext<'_>) -> bool {
+        if self.rules.is_empty() {
+            return true;
+        }
+        let mut allowed = false;
+        for rule in &self.rules {
+            if let Some(action) = rule.evaluate(ctx) {
+                allowed = action;
+            }
+        }
+        allowed
+    }
+}
+
+/// rules 求值上下文。
+#[derive(Debug, Clone, Copy)]
+pub struct RuleContext<'a> {
+    /// `rules.os.name` 取值。
+    pub os_name: &'a str,
+    /// `rules.os.arch` 取值。
+    pub os_arch: &'a str,
+    /// `rules.os.version` 取值。
+    pub os_version: &'a str,
+    /// 特性开关。
+    pub features: &'a FeatureSet,
+}
+
+impl<'a> RuleContext<'a> {
+    /// 构造。
+    pub fn new(
+        os_name: &'a str,
+        os_arch: &'a str,
+        os_version: &'a str,
+        features: &'a FeatureSet,
+    ) -> Self {
+        Self {
+            os_name,
+            os_arch,
+            os_version,
+            features,
+        }
+    }
+}
+
+fn arch_matches(rule_arch: &str, actual: &str) -> bool {
+    if rule_arch == actual {
+        return true;
+    }
+    // Mojang 用 "x86" 表示 32 位，我们的实际值可能是 "i686" 之类。
+    matches!(
+        (rule_arch, actual),
+        ("x86", "i686") | ("x86_64", "amd64") | ("arm64", "aarch64")
+    )
+}
+
+/// 只做保守匹配：支持 `^10\.` / `^10\.15` 这类前缀模式与纯子串，无法识别的模式按“不匹配”处理
+/// （宁可少加一个参数，也不要给错误平台加参数）。
+///
+/// 处理：去掉前置 `^` 与结尾 `$`、`\.` 反转义成 `.`、去掉结尾的点（`^10\.` 的语义就是
+/// “以 `10.` 开头”，点本身不参与前缀比较）。含 `[ ( { | * + ?` 等真需要正则的模式一律不匹配。
+fn version_matches(pattern: &str, actual: &str) -> bool {
+    if actual.is_empty() {
+        return false;
+    }
+    let trimmed = pattern.trim();
+    let stripped = trimmed.strip_prefix('^').unwrap_or(trimmed);
+    if stripped.contains(['[', '(', '{', '|', '*', '+', '?']) {
+        return false;
+    }
+    let mut literal = stripped.replace("\\.", ".");
+    while literal.ends_with(['$', '.']) {
+        literal.pop();
+    }
+    if literal.is_empty() {
+        return false;
+    }
+    actual.starts_with(&literal) || actual.contains(&literal)
+}
diff --git a/crates/core/src/launch/command_builder.rs b/crates/core/src/launch/command_builder.rs
new file mode 100644
index 0000000..da54304
--- /dev/null
+++ b/crates/core/src/launch/command_builder.rs
@@ -0,0 +1,335 @@
+//! `CommandBuilder`：命令行组装器与“默认值抑制”语义。
+//!
+//! 平移自 `analyse/02` §4.2（`CommandBuilder.java`）——这是 HMCL 命令行正确性的基石，
+//! 也是“用户参数永远优先、我们只补缺”的唯一可靠实现：
+//!
+//! - [`CommandBuilder::add`] 无条件追加（占位符已替换）；
+//! - [`CommandBuilder::add_without_parsing`] 原样追加（已带引号或变量的串）；
+//! - [`CommandBuilder::add_default`] 若已存在同前缀参数则不追加（opt=前缀，如 `-Xmx`）；
+//! - [`CommandBuilder::add_unstable_flag`] / [`CommandBuilder::add_unstable_default`]
+//!   按 `-XX:key=value` 与 `-XX:±key` 两种形态判重，避免同时出现 `+UseG1GC` 与 `-UseG1GC`；
+//! - [`CommandBuilder::add_all_default`] 把一组参数整体按“默认值”处理（`-D` 拆键值、
+//!   `-XX:` 走 unstable 分支、`-Xmx/-Xms/-Xmn/-Xss` 拆前缀、`-cp` 成对处理，其余要求完全相同）；
+//! - `@argfile` 感知：Java 9+ 的 `@options-file` 展开后的参数登记进 `external`，
+//!   让后续默认值同样被抑制。
+//!
+//! 与 HMCL 的差异（已记录在 `DevDocs/SubAgentsTalk/launch-接口约定.md` §7）：我们直接 spawn
+//! 子进程、不经过 shell，因此不做批处理/Shell 转义；转义只在“生成启动脚本”（P1）时需要。
+
+use std::path::Path;
+
+use crate::launch::placeholders::PlaceholderMap;
+
+/// 命令行组装器。
+#[derive(Debug, Clone, Default)]
+pub struct CommandBuilder {
+    args: Vec<String>,
+    external: Vec<String>,
+    placeholders: PlaceholderMap,
+}
+
+impl CommandBuilder {
+    /// 空构造器。
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// 带占位符表的构造器。
+    pub fn with_placeholders(placeholders: PlaceholderMap) -> Self {
+        Self {
+            args: Vec::new(),
+            external: Vec::new(),
+            placeholders,
+        }
+    }
+
+    /// 占位符表。
+    pub fn placeholders(&self) -> &PlaceholderMap {
+        &self.placeholders
+    }
+
+    /// 追加一个参数（替换占位符）。
+    pub fn add(&mut self, arg: &str) {
+        let rendered = self.placeholders.render(arg);
+        self.args.push(rendered);
+    }
+
+    /// 追加一组参数（替换占位符）。
+    pub fn add_all(&mut self, args: &[String]) {
+        for arg in args {
+            self.add(arg);
+        }
+    }
+
+    /// 原样追加（不替换占位符）。
+    pub fn add_without_parsing(&mut self, arg: impl Into<String>) {
+        self.args.push(arg.into());
+    }
+
+    /// 原样追加一组。
+    pub fn add_all_without_parsing(&mut self, args: &[String]) {
+        for arg in args {
+            self.add_without_parsing(arg.clone());
+        }
+    }
+
+    /// 原样追加一组，并读取其中的 `@argfile`：
+    /// 文件里展开出来的参数登记为 `external`，后续 [`Self::add_default`] 会被它们抑制。
+    pub fn add_all_without_parsing_and_read_external(
+        &mut self,
+        args: &[String],
+        read_argfile: &dyn Fn(&str) -> Option<String>,
+    ) {
+        for arg in args {
+            self.add_without_parsing(arg.clone());
+            if let Some(path) = arg.strip_prefix('@') {
+                if let Some(contents) = read_argfile(path) {
+                    for extra in parse_argfile(&contents) {
+                        self.external.push(extra);
+                    }
+                }
+            }
+        }
+    }
+
+    /// 已存在以 `prefix` 开头的参数则返回它，否则追加 `prefix + value` 并返回 `None`。
+    ///
+    /// 返回值的语义与 HMCL 一致：`None` = “是我加的”，`Some(已有值)` = “用户已经指定过”。
+    pub fn add_default(&mut self, prefix: &str, value: &str) -> Option<String> {
+        if let Some(existing) = self.find_starting_with(prefix) {
+            return Some(existing.to_string());
+        }
+        let rendered = self.placeholders.render(&format!("{prefix}{value}"));
+        self.args.push(rendered);
+        None
+    }
+
+    /// `-XX:key=value` 形态的默认值；已存在该 key 的任何形态则不追加。
+    pub fn add_unstable_default(&mut self, key: &str, value: &str) -> Option<String> {
+        if let Some(existing) = self.find_unstable(key) {
+            return Some(existing.to_string());
+        }
+        let rendered = self.placeholders.render(&format!("-XX:{key}={value}"));
+        self.args.push(rendered);
+        None
+    }
+
+    /// `-XX:+key` / `-XX:-key` 形态的默认值；已存在该 key 的任何形态则不追加。
+    pub fn add_unstable_flag(&mut self, key: &str, enabled: bool) -> Option<String> {
+        if let Some(existing) = self.find_unstable(key) {
+            return Some(existing.to_string());
+        }
+        let sign = if enabled { '+' } else { '-' };
+        self.args.push(format!("-XX:{sign}{key}"));
+        None
+    }
+
+    /// 一组参数整体按“默认值”处理。
+    pub fn add_all_default(&mut self, args: &[String]) {
+        let mut index = 0;
+        while index < args.len() {
+            let raw = args[index].trim();
+            if raw.is_empty() {
+                index += 1;
+                continue;
+            }
+            let resolved = self.placeholders.render(raw);
+            if matches!(raw, "-cp" | "-classpath") {
+                let exists = self.find_starting_with(raw).is_some();
+                if !exists {
+                    self.args.push(resolved);
+                    if let Some(value) = args.get(index + 1) {
+                        let value = self.placeholders.render(value);
+                        self.args.push(value);
+                    }
+                }
+                index += 2;
+                continue;
+            }
+            if self.try_add_key_value_default(&resolved) {
+                index += 1;
+                continue;
+            }
+            let exists = self
+                .args
+                .iter()
+                .chain(self.external.iter())
+                .any(|arg| arg == &resolved);
+            if !exists {
+                self.args.push(resolved);
+            }
+            index += 1;
+        }
+    }
+
+    /// 已存在的、以 `prefix` 开头的参数。
+    pub fn find_starting_with(&self, prefix: &str) -> Option<&str> {
+        self.args
+            .iter()
+            .chain(self.external.iter())
+            .find(|arg| arg.starts_with(prefix))
+            .map(String::as_str)
+    }
+
+    /// 已存在的、提到 `key` 的 `-XX:` 参数（两种形态都算）。
+    pub fn find_unstable(&self, key: &str) -> Option<&str> {
+        self.args
+            .iter()
+            .chain(self.external.iter())
+            .find(|arg| unstable_key(arg) == Some(key))
+            .map(String::as_str)
+    }
+
+    /// 是否已存在完全相同的参数。
+    pub fn contains_exact(&self, arg: &str) -> bool {
+        self.args.iter().any(|existing| existing == arg)
+    }
+
+    /// 删除禁用参数（例如 Java ≥9 上的 `-Xincgc`），返回被删掉的项。
+    pub fn remove_forbidden(&mut self, forbidden: &[&str]) -> Vec<String> {
+        let mut removed = Vec::new();
+        self.args.retain(|arg| {
+            if forbidden.contains(&arg.as_str()) {
+                removed.push(arg.clone());
+                false
+            } else {
+                true
+            }
+        });
+        removed
+    }
+
+    /// 当前参数列表。
+    pub fn args(&self) -> &[String] {
+        &self.args
+    }
+
+    /// 取走参数列表。
+    pub fn into_args(self) -> Vec<String> {
+        self.args
+    }
+
+    /// 人读形式（含空格的参数加双引号），用于日志与快照测试。
+    pub fn display_args(&self) -> String {
+        self.args
+            .iter()
+            .map(|arg| quote_for_display(arg))
+            .collect::<Vec<_>>()
+            .join(" ")
+    }
+
+    fn try_add_key_value_default(&mut self, resolved: &str) -> bool {
+        if let Some(rest) = resolved.strip_prefix("-D") {
+            if let Some(eq) = rest.find('=') {
+                let split = 2 + eq + 1;
+                let prefix = resolved[..split].to_string();
+                let value = resolved[split..].to_string();
+                let _ = self.add_default(&prefix, &value);
+                return true;
+            }
+        }
+        if let Some(rest) = resolved.strip_prefix("-XX:") {
+            if let Some(eq) = rest.find('=') {
+                let _ = self.add_unstable_default(&rest[..eq], &rest[eq + 1..]);
+                return true;
+            }
+            if let Some(signless) = rest.strip_prefix(['+', '-']) {
+                let _ = self.add_unstable_flag(signless, rest.starts_with('+'));
+                return true;
+            }
+        }
+        for prefix in ["-Xmx", "-Xms", "-Xmn", "-Xss"] {
+            if let Some(value) = resolved.strip_prefix(prefix) {
+                let _ = self.add_default(prefix, value);
+                return true;
+            }
+        }
+        false
+    }
+}
+
+fn unstable_key(arg: &str) -> Option<&str> {
+    let rest = arg.strip_prefix("-XX:")?;
+    let body = rest.strip_prefix(['+', '-']).unwrap_or(rest);
+    Some(body.split('=').next().unwrap_or(body))
+}
+
+/// 把 `minecraftArguments` 之类的一整串拆成参数（引号感知，反斜杠转义 `"` 与 `\`）。
+pub fn tokenize(text: &str) -> Vec<String> {
+    let mut out = Vec::new();
+    let mut current = String::new();
+    let mut has_token = false;
+    let mut in_single = false;
+    let mut in_double = false;
+    let mut chars = text.chars().peekable();
+    while let Some(ch) = chars.next() {
+        match ch {
+            '\'' if !in_double => {
+                in_single = !in_single;
+                has_token = true;
+            }
+            '"' if !in_single => {
+                in_double = !in_double;
+                has_token = true;
+            }
+            '\\' if !in_single => match chars.peek() {
+                Some(&next) if next == '"' || next == '\\' => {
+                    current.push(next);
+                    chars.next();
+                    has_token = true;
+                }
+                _ => {
+                    current.push(ch);
+                    has_token = true;
+                }
+            },
+            c if c.is_whitespace() && !in_single && !in_double => {
+                if has_token {
+                    out.push(std::mem::take(&mut current));
+                    has_token = false;
+                }
+            }
+            c => {
+                current.push(c);
+                has_token = true;
+            }
+        }
+    }
+    if has_token {
+        out.push(current);
+    }
+    out
+}
+
+/// 解析 `@argfile` 内容：忽略空行与 `#` 注释行，每行再走 [`tokenize`]。
+pub fn parse_argfile(contents: &str) -> Vec<String> {
+    let mut out = Vec::new();
+    for line in contents.lines() {
+        let line = line.trim();
+        if line.is_empty() || line.starts_with('#') {
+            continue;
+        }
+        out.extend(tokenize(line));
+    }
+    out
+}
+
+/// 从磁盘读取 `@argfile`（读不到就当没有；不因用户文件缺失而中断启动）。
+pub fn read_argfile(path: &str) -> Option<String> {
+    let path = path.strip_prefix('@').unwrap_or(path);
+    std::fs::read(Path::new(path))
+        .ok()
+        .map(|bytes| String::from_utf8_lossy(&bytes).into_owned())
+}
+
+/// 人读引用：含空白或引号的参数加双引号并转义内部引号。
+pub fn quote_for_display(arg: &str) -> String {
+    if arg.is_empty() {
+        return "\"\"".to_string();
+    }
+    if arg.contains([' ', '\t', '"']) {
+        format!("\"{}\"", arg.replace('"', "\\\""))
+    } else {
+        arg.to_string()
+    }
+}
diff --git a/crates/core/src/launch/crash_scan.rs b/crates/core/src/launch/crash_scan.rs
new file mode 100644
index 0000000..66da94b
--- /dev/null
+++ b/crates/core/src/launch/crash_scan.rs
@@ -0,0 +1,152 @@
+//! 崩溃现场扫描：`crash-reports/*.txt`、`hs_err_pid*.log`、`logs/latest.log`。
+//!
+//! 按 `DevDocs/SubAgentsTalk/launch-接口约定.md` §3：`crash_found` 事件的 `path` 是
+//! **权威字段**（M15 按路径自己读盘，`excerpt` 仅供人读）。所以这里只做“找到并给出路径”，
+//! 不做解析——解析（hs_err 的失败帧/内存段）是 M15 的 `hs_err` 解析器。
+//!
+//! 只收**本次会话之后**动过的文件（`since` = 进程启动时刻），避免把上一局的崩溃报告
+//! 算到这一局头上（这是 HMCL 会犯的错）。
+
+use std::path::{Path, PathBuf};
+use std::time::{Duration, SystemTime};
+
+/// 崩溃现场文件来源。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CrashSource {
+    /// `crash-reports/crash-*.txt`（游戏自己写的权威 Description + 栈）。
+    CrashReport,
+    /// JVM 致命错误 `hs_err_pid*.log`（HMCL 完全不解析的空白区）。
+    HsErr,
+    /// `logs/latest.log`（内存缓冲不够长时的兜底全文）。
+    LatestLog,
+}
+
+impl CrashSource {
+    /// 事件流里的字符串。
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::CrashReport => "crash_report",
+            Self::HsErr => "hs_err",
+            Self::LatestLog => "latest_log",
+        }
+    }
+}
+
+/// 一个现场文件。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CrashArtifact {
+    /// 来源类型。
+    pub source: CrashSource,
+    /// 绝对/相对路径（交给 M15）。
+    pub path: PathBuf,
+    /// 供人读的开头片段（`latest.log` 不给，太大）。见 `DevDocs/SubAgentsTalk/launch-接口约定.md` §4（写入前脱敏）。
+    pub excerpt: Option<String>,
+}
+
+/// 默认摘录上限（字符）。
+pub const MAX_EXCERPT_CHARS: usize = 2000;
+
+/// 扫描一次运行目录，返回按修改时间倒序的现场文件（最多 `limit` 个）。
+///
+/// `since` 之前的文件视为上一局遗留，忽略；给 `since` 留 1 秒容差以吸收文件系统时间精度。
+pub fn scan(run_dir: &Path, since: SystemTime, limit: usize) -> Vec<CrashArtifact> {
+    let since = since.checked_sub(Duration::from_secs(1)).unwrap_or(since);
+    let mut found: Vec<(SystemTime, CrashArtifact)> = Vec::new();
+
+    collect_matching(
+        &run_dir.join("crash-reports"),
+        CrashSource::CrashReport,
+        since,
+        &mut found,
+    );
+    collect_matching(run_dir, CrashSource::HsErr, since, &mut found);
+    if let Some(artifact) = latest_log(run_dir, since) {
+        let modified = artifact_time(&artifact.path).unwrap_or(since);
+        found.push((modified, artifact));
+    }
+
+    found.sort_by_key(|item| std::cmp::Reverse(item.0));
+    found
+        .into_iter()
+        .take(limit)
+        .map(|(_, artifact)| artifact)
+        .collect()
+}
+
+fn collect_matching(
+    dir: &Path,
+    source: CrashSource,
+    since: SystemTime,
+    out: &mut Vec<(SystemTime, CrashArtifact)>,
+) {
+    let Ok(entries) = std::fs::read_dir(dir) else {
+        return;
+    };
+    for entry in entries.flatten() {
+        let path = entry.path();
+        if !is_candidate(&path, source) {
+            continue;
+        }
+        let Some(modified) = artifact_time(&path) else {
+            continue;
+        };
+        if modified < since {
+            continue;
+        }
+        out.push((
+            modified,
+            CrashArtifact {
+                source,
+                path: path.clone(),
+                excerpt: read_excerpt(&path, MAX_EXCERPT_CHARS),
+            },
+        ));
+    }
+}
+
+fn is_candidate(path: &Path, source: CrashSource) -> bool {
+    if !path.is_file() {
+        return false;
+    }
+    let name = path
+        .file_name()
+        .map(|name| name.to_string_lossy().to_ascii_lowercase())
+        .unwrap_or_default();
+    match source {
+        CrashSource::CrashReport => name.ends_with(".txt"),
+        CrashSource::HsErr => name.starts_with("hs_err_pid") && name.ends_with(".log"),
+        CrashSource::LatestLog => false,
+    }
+}
+
+fn latest_log(run_dir: &Path, since: SystemTime) -> Option<CrashArtifact> {
+    let path = run_dir.join("logs").join("latest.log");
+    let modified = artifact_time(&path)?;
+    if modified < since {
+        return None;
+    }
+    Some(CrashArtifact {
+        source: CrashSource::LatestLog,
+        path,
+        excerpt: None,
+    })
+}
+
+fn artifact_time(path: &Path) -> Option<SystemTime> {
+    std::fs::metadata(path).ok()?.modified().ok()
+}
+
+/// 读文件开头 `max_chars` 个字符（读不到就 `None`，不因权限/编码问题中断收尾）。
+pub fn read_excerpt(path: &Path, max_chars: usize) -> Option<String> {
+    let bytes = std::fs::read(path).ok()?;
+    let text = String::from_utf8_lossy(&bytes);
+    let mut excerpt = String::new();
+    for (count, ch) in text.chars().enumerate() {
+        if count >= max_chars {
+            excerpt.push('…');
+            break;
+        }
+        excerpt.push(ch);
+    }
+    Some(excerpt)
+}
diff --git a/crates/core/src/launch/defaults.rs b/crates/core/src/launch/defaults.rs
new file mode 100644
index 0000000..ffcc157
--- /dev/null
+++ b/crates/core/src/launch/defaults.rs
@@ -0,0 +1,203 @@
+//! 默认参数表：JVM 优化、编码、log4j、禁用参数、环境变量。
+//!
+//! 平移自 `analyse/02` §4.3（自动优化）、§4.4（编码/Log4j）、§4.1 #33（禁用参数）、
+//! §4.10（环境变量）。所有函数都是纯函数——同样的输入永远给同样的参数，便于快照测试。
+
+use crate::launch::platform::OsFamily;
+use crate::launch::request::{LaunchRequest, ModLoaderKind, RendererOptions, Resolution};
+
+/// 旧版清单的默认 JVM 参数（`analyse/02` §4.7 的 `DEFAULT_JVM_ARGUMENTS`）。
+///
+/// 现代清单把这两项写在自己的 `arguments.jvm` 里，只有 legacy 需要补。
+pub fn legacy_jvm_arguments() -> Vec<String> {
+    vec![
+        "-Djava.library.path=${natives_directory}".to_string(),
+        "-cp".to_string(),
+        "${classpath}".to_string(),
+    ]
+}
+
+/// stdout/stderr 编码参数。
+///
+/// Java ≥19 用 `-Dstdout.encoding`，更早用 `-Dsun.stdout.encoding`（`analyse/02` §4.4：
+/// 用户指定的 `-Dfile.encoding` 会决定日志泵的解码方式，这里必须跟随）。
+pub fn stream_encoding_args(java_major: u32, encoding: &str) -> Vec<String> {
+    if java_major >= 19 {
+        vec![
+            format!("-Dstdout.encoding={encoding}"),
+            format!("-Dstderr.encoding={encoding}"),
+        ]
+    } else {
+        vec![
+            format!("-Dsun.stdout.encoding={encoding}"),
+            format!("-Dsun.stderr.encoding={encoding}"),
+        ]
+    }
+}
+
+/// Log4j2 RCE 缓解三件套（`analyse/02` §4.1 #9）。
+pub fn log4j_mitigation_args() -> Vec<String> {
+    vec![
+        "-Djava.rmi.server.useCodebaseOnly=true".to_string(),
+        "-Dcom.sun.jndi.rmi.object.trustURLCodebase=false".to_string(),
+        "-Dcom.sun.jndi.cosnaming.object.trustURLCodebase=false".to_string(),
+    ]
+}
+
+/// 自动优化参数（`analyse/02` §4.3）。
+///
+/// `user_specified_gc` 为真时不注入 G1 整组（用户显式挑了 GC 就别打架）；
+/// 其它每一条都还会被 `CommandBuilder` 的默认值抑制再筛一遍。
+pub fn optimization_args(
+    java_major: u32,
+    bits: u32,
+    physical_memory_mb: Option<u64>,
+    user_specified_gc: bool,
+) -> Vec<String> {
+    let mut args = vec![
+        "-XX:+UnlockExperimentalVMOptions".to_string(),
+        "-XX:+UnlockDiagnosticVMOptions".to_string(),
+    ];
+    if java_major >= 8 && !user_specified_gc {
+        for arg in [
+            "-XX:+UseG1GC",
+            "-XX:G1MixedGCCountTarget=5",
+            "-XX:G1NewSizePercent=20",
+            "-XX:G1ReservePercent=20",
+            "-XX:MaxGCPauseMillis=50",
+            "-XX:G1HeapRegionSize=32m",
+        ] {
+            args.push(arg.to_string());
+        }
+    }
+    // 崩溃诊断关键项：关掉“快速抛出时省略栈”，保证日志里有完整堆栈。
+    args.push("-XX:-OmitStackTraceInFastThrow".to_string());
+    if java_major <= 8 {
+        args.push("-XX:MaxInlineLevel=15".to_string());
+    }
+    if bits >= 64 && physical_memory_mb.is_some_and(|mb| mb > 4096) {
+        for arg in [
+            "-XX:-DontCompileHugeMethods",
+            "-XX:MaxNodeLimit=240000",
+            "-XX:NodeLimitFudgeFactor=8000",
+            "-XX:TieredCompileTaskTimeout=10000",
+            "-XX:ReservedCodeCacheSize=400M",
+            "-XX:NonNMethodCodeHeapSize=12M",
+            "-XX:ProfiledCodeHeapSize=194M",
+            "-XX:NmethodSweepActivity=1",
+        ] {
+            args.push(arg.to_string());
+        }
+    }
+    if bits >= 64 && (25..=26).contains(&java_major) {
+        args.push("-XX:+UseCompactObjectHeaders".to_string());
+    }
+    args
+}
+
+/// 版本特定的 JVM 开关（`analyse/02` §4.1 #15）。
+pub fn version_specific_args(java_major: u32) -> Vec<String> {
+    match java_major {
+        16 => vec!["--illegal-access=permit".to_string()],
+        24 | 25 => vec!["--sun-misc-unsafe-memory-access=allow".to_string()],
+        _ => Vec::new(),
+    }
+}
+
+/// Forge/NeoForge 的证书校验豁免（`analyse/02` §4.1 #16）。
+pub fn fml_args() -> Vec<String> {
+    vec![
+        "-Dfml.ignoreInvalidMinecraftCertificates=true".to_string(),
+        "-Dfml.ignorePatchDiscrepancies=true".to_string(),
+    ]
+}
+
+/// 渲染器相关 `-D` 参数（`analyse/02` §4.1 #17，v1 只做 native 路径覆盖）。
+///
+/// 软件渲染的细节开关走环境变量（[`environment`]），因为 Mesa/llvmpipe 读的是 env。
+pub fn renderer_args(renderer: &RendererOptions) -> Vec<String> {
+    let mut args = Vec::new();
+    if let Some(dir) = &renderer.mesa_native_dir {
+        args.push(format!("-Dorg.lwjgl.librarypath={}", dir.display()));
+    }
+    args
+}
+
+/// 被禁止的参数（最后统一清理，`analyse/02` §4.1 #33）。
+pub fn forbidden_args(java_major: u32) -> Vec<&'static str> {
+    if java_major >= 9 {
+        vec!["-Xincgc"]
+    } else {
+        Vec::new()
+    }
+}
+
+/// 旧版清单的默认游戏参数（分辨率，`analyse/02` §4.1 #26）。
+pub fn legacy_game_args(resolution: Option<&Resolution>) -> Vec<String> {
+    let mut args = Vec::new();
+    if let Some(res) = resolution {
+        args.push("--width".to_string());
+        args.push(res.width.to_string());
+        args.push("--height".to_string());
+        args.push(res.height.to_string());
+    }
+    args
+}
+
+/// 进程环境变量（`analyse/02` §4.10）。
+///
+/// 顺序：实例标识 → 渲染器开关 → 加载器标记 → 用户自定义（最后覆盖）。
+pub fn environment(req: &LaunchRequest, os: OsFamily) -> Vec<(String, String)> {
+    let mut env: Vec<(String, String)> = Vec::new();
+    set_env(&mut env, "INST_NAME", &req.instance.name);
+    set_env(&mut env, "INST_ID", &req.instance.id);
+    set_env(
+        &mut env,
+        "INST_DIR",
+        &req.dirs.game_dir.display().to_string(),
+    );
+    set_env(
+        &mut env,
+        "INST_MC_DIR",
+        &req.dirs.game_dir.display().to_string(),
+    );
+    set_env(
+        &mut env,
+        "INST_JAVA",
+        &req.java.binary.display().to_string(),
+    );
+    if req.mod_loader == ModLoaderKind::OptiFine {
+        set_env(&mut env, "INST_OPTIFINE", "1");
+    }
+    if req.renderer.software {
+        set_env(&mut env, "LIBGL_ALWAYS_SOFTWARE", "1");
+        set_env(&mut env, "MESA_LOADER_DRIVER_OVERRIDE", "llvmpipe");
+        set_env(&mut env, "GALLIUM_DRIVER", "llvmpipe");
+    }
+    if os == OsFamily::MacOs {
+        if let Some(icd) = &req.renderer.vulkan_icd {
+            set_env(&mut env, "VK_ICD_FILENAMES", &icd.display().to_string());
+            set_env(&mut env, "VK_DRIVER_FILES", &icd.display().to_string());
+        }
+    }
+    match req.mod_loader {
+        ModLoaderKind::Forge => set_env(&mut env, "FORGE_INSTALL", "1"),
+        ModLoaderKind::NeoForge => set_env(&mut env, "NEOFORGE_INSTALL", "1"),
+        ModLoaderKind::Fabric => set_env(&mut env, "FABRIC_INSTALL", "1"),
+        ModLoaderKind::Quilt => set_env(&mut env, "QUILT_INSTALL", "1"),
+        ModLoaderKind::LiteLoader => set_env(&mut env, "LITELOADER_INSTALL", "1"),
+        ModLoaderKind::OptiFine | ModLoaderKind::Vanilla => {}
+    }
+    for (key, value) in &req.user.environment {
+        set_env(&mut env, key, value);
+    }
+    env
+}
+
+fn set_env(env: &mut Vec<(String, String)>, key: &str, value: &str) {
+    if let Some(slot) = env.iter_mut().find(|(existing, _)| existing == key) {
+        slot.1 = value.to_string();
+    } else {
+        env.push((key.to_string(), value.to_string()));
+    }
+}
diff --git a/crates/core/src/launch/diagnosis_hook.rs b/crates/core/src/launch/diagnosis_hook.rs
new file mode 100644
index 0000000..889c7c6
--- /dev/null
+++ b/crates/core/src/launch/diagnosis_hook.rs
@@ -0,0 +1,97 @@
+//! 诊断挂钩：launch 与 M15（`core::diagnose`）之间的唯一接缝。
+//!
+//! 分工（`DevDocs/SubAgentsTalk/launch-接口约定.md` §3）：**launch 报事实、M15 下结论**。
+//! launch 在进程结束后把「退出判定 + 日志环形缓冲 + 崩溃现场文件 + 环境快照」打包成
+//! [`DiagnosisRequest`] 交给挂钩；挂钩返回结构化 payload（`candidates[]` 等），由 launch
+//! 脱敏后写进同一个 JSONL（单一真相源）。
+//!
+//! 这样 M15 不需要 import launch 的类型，launch 也不需要 import diagnose 的类型——
+//! 阶段 B 的 diagnose 尚未合并，P0 先用 [`NoopDiagnosis`] 占位。
+
+use std::path::PathBuf;
+
+use serde_json::Value;
+
+use crate::launch::crash_scan::CrashArtifact;
+use crate::launch::exit_analysis::ExitAnalysis;
+use crate::launch::pump::LogLine;
+
+/// 诊断挂钩。
+pub trait DiagnosisHook: Send + Sync {
+    /// 需要诊断时调用；返回 `None` 表示“这次没有结论”（事件流里就不会有 `diagnosis` 事件）。
+    fn analyze(&self, request: &DiagnosisRequest) -> Option<Value>;
+}
+
+/// 空挂钩：不诊断（占位 / 用户关闭 AI）。
+#[derive(Debug, Default, Clone, Copy)]
+pub struct NoopDiagnosis;
+
+impl DiagnosisHook for NoopDiagnosis {
+    fn analyze(&self, _request: &DiagnosisRequest) -> Option<Value> {
+        None
+    }
+}
+
+/// 交给诊断挂钩的完整事实包。
+#[derive(Debug, Clone)]
+pub struct DiagnosisRequest {
+    /// 会话 id（M15 可据此回读 jsonl）。
+    pub session_id: String,
+    /// 实例 id。
+    pub instance_id: String,
+    /// 实例名。
+    pub instance_name: String,
+    /// 游戏版本。
+    pub game_version: String,
+    /// 退出判定。
+    pub exit: ExitAnalysis,
+    /// 存活毫秒数。
+    pub uptime_ms: u64,
+    /// 环形缓冲里的日志行（按时间顺序，已脱敏）。
+    pub log_lines: Vec<LogLine>,
+    /// 崩溃现场文件（crash-report / hs_err / latest.log）。
+    pub artifacts: Vec<CrashArtifact>,
+    /// 脱敏后的完整 argv。
+    pub argv: Vec<String>,
+    /// 最大堆（MiB）。
+    pub memory_mb: Option<u32>,
+    /// Java 主版本。
+    pub java_major: u32,
+    /// Java 可执行文件。
+    pub java_binary: PathBuf,
+    /// 运行目录。
+    pub game_dir: PathBuf,
+}
+
+impl DiagnosisRequest {
+    /// 错误级日志行（M15 规则匹配的主输入）。
+    pub fn error_lines(&self) -> Vec<String> {
+        self.log_lines
+            .iter()
+            .filter(|line| line.is_error())
+            .map(|line| line.text.clone())
+            .collect()
+    }
+
+    /// 全部日志拼成文本（M15 自己的 `LogBuffer` 也能直接用 `log_lines`）。
+    pub fn log_text(&self) -> String {
+        let mut text = String::new();
+        for line in &self.log_lines {
+            text.push_str(&line.text);
+            text.push('\n');
+        }
+        text
+    }
+
+    /// 一句话摘要（日志/UI 展示）。
+    pub fn summary(&self) -> String {
+        format!(
+            "会话 {} 退出：[{}]；错误行 {}；现场文件 {}；需诊断={}",
+            self.session_id,
+            self.exit.summary(),
+            self.error_lines().len(),
+            self.artifacts.len(),
+            self.exit.needs_diagnosis
+        )
+    }
+}
diff --git a/crates/core/src/launch/error.rs b/crates/core/src/launch/error.rs
new file mode 100644
index 0000000..1d5d435
--- /dev/null
+++ b/crates/core/src/launch/error.rs
@@ -0,0 +1,165 @@
+//! launch 模块统一错误类型。
+//!
+//! 设计依据：`DevDocs/PlanDoc/06-launch-and-diagnostics.md` §1、`analyse/02` §8.4-3
+//! （缺库/缺组件必须结构化报错并显式失败，而不是交给运行时 `NoClassDefFoundError`）。
+
+use std::fmt;
+use std::path::PathBuf;
+
+/// launch 相关操作的统一结果类型。
+pub type Result<T> = std::result::Result<T, LaunchError>;
+
+/// 缺失的组件（库 / natives / 资产），供 UI 与 agent 直接展示与修复。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct MissingComponent {
+    /// 逻辑名，例如 `org.lwjgl:lwjgl:3.3.1` 或 `libraries/foo/bar.jar`。
+    pub name: String,
+    /// 期望落盘路径（未知时为 `None`）。
+    pub path: Option<PathBuf>,
+}
+
+impl MissingComponent {
+    /// 只按名字构造（路径未知）。
+    pub fn named(name: impl Into<String>) -> Self {
+        Self {
+            name: name.into(),
+            path: None,
+        }
+    }
+
+    /// 带期望路径构造。
+    pub fn at_path(name: impl Into<String>, path: impl Into<PathBuf>) -> Self {
+        Self {
+            name: name.into(),
+            path: Some(path.into()),
+        }
+    }
+}
+
+/// 命令行组装阶段的失败原因（全部是“启动前就能确定”的错误）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum AssemblyError {
+    /// 清单里没有主类，无法启动（HMCL 在此直接抛异常）。
+    MissingMainClass,
+    /// classpath 为空（一个库和主 jar 都没有）。
+    EmptyClasspath,
+    /// Java 可执行文件路径为空。
+    EmptyJavaPath,
+    /// 组件不完整：启动前显式失败，附结构化清单。
+    MissingComponents(Vec<MissingComponent>),
+    /// 清单参数畸形（例如空参数项）。
+    MalformedArgument {
+        /// 原始参数项文本。
+        entry: String,
+        /// 原因说明。
+        reason: &'static str,
+    },
+    /// natives 解压失败（jar 缺失/损坏、目录不可写）。
+    ///
+    /// 归到「启动前失败」而不是运行时错误：native 库没落地时游戏只会给出
+    /// `UnsatisfiedLinkError`，那时候已经离「到底哪个 jar 坏了」太远了。
+    NativesExtraction {
+        /// 人读原因（含失败路径）。
+        message: String,
+    },
+}
+
+impl fmt::Display for AssemblyError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::MissingMainClass => f.write_str("版本清单缺少主类（mainClass）"),
+            Self::EmptyClasspath => f.write_str("classpath 为空：没有任何库或主 jar"),
+            Self::EmptyJavaPath => f.write_str("Java 可执行文件路径为空"),
+            Self::MissingComponents(items) => {
+                write!(f, "组件缺失 {} 项", items.len())?;
+                for item in items.iter().take(8) {
+                    write!(f, "; {}", item.name)?;
+                }
+                Ok(())
+            }
+            Self::MalformedArgument { entry, reason } => {
+                write!(f, "参数畸形（{reason}）：{entry}")
+            }
+            Self::NativesExtraction { message } => {
+                write!(f, "natives 解压失败：{message}")
+            }
+        }
+    }
+}
+
+impl std::error::Error for AssemblyError {}
+
+/// launch 模块的统一错误。
+#[derive(Debug)]
+pub enum LaunchError {
+    /// 命令行组装失败（纯计算，可单测）。
+    Assembly(AssemblyError),
+    /// 文件系统操作失败。
+    Io {
+        /// 操作名（`create_session` / `read_argfile` 等）。
+        op: &'static str,
+        /// 相关路径。
+        path: PathBuf,
+        /// 底层错误。
+        source: std::io::Error,
+    },
+    /// 进程派生失败（Java 不存在、权限不足等）。
+    Spawn {
+        /// 被执行的程序。
+        program: PathBuf,
+        /// 底层错误。
+        source: std::io::Error,
+    },
+    /// 会话事件流写入/解析失败。
+    Session {
+        /// 会话文件路径。
+        path: PathBuf,
+        /// 原因说明。
+        reason: String,
+    },
+    /// 进程树 kill 失败。
+    Kill {
+        /// 目标进程号。
+        pid: u32,
+        /// 底层错误。
+        source: std::io::Error,
+    },
+}
+
+impl fmt::Display for LaunchError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Assembly(err) => write!(f, "命令行组装失败：{err}"),
+            Self::Io { op, path, source } => {
+                write!(f, "{op} 失败（{}）：{source}", path.display())
+            }
+            Self::Spawn { program, source } => {
+                write!(f, "启动进程失败（{}）：{source}", program.display())
+            }
+            Self::Session { path, reason } => {
+                write!(f, "会话事件流错误（{}）：{reason}", path.display())
+            }
+            Self::Kill { pid, source } => {
+                write!(f, "结束进程树失败（pid {pid}）：{source}")
+            }
+        }
+    }
+}
+
+impl std::error::Error for LaunchError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            Self::Assembly(err) => Some(err),
+            Self::Io { source, .. } | Self::Spawn { source, .. } | Self::Kill { source, .. } => {
+                Some(source)
+            }
+            Self::Session { .. } => None,
+        }
+    }
+}
+
+impl From<AssemblyError> for LaunchError {
+    fn from(err: AssemblyError) -> Self {
+        Self::Assembly(err)
+    }
+}
diff --git a/crates/core/src/launch/exit_analysis.rs b/crates/core/src/launch/exit_analysis.rs
new file mode 100644
index 0000000..a4bc842
--- /dev/null
+++ b/crates/core/src/launch/exit_analysis.rs
@@ -0,0 +1,264 @@
+//! 退出分析：退出码语义 + `exit 0` 静默失败检测。
+//!
+//! 平移自 `analyse/02` §6.3/§7.2（`ExitWaiter` 的三源判定），并按 §8.4-2 / §7.10-10 做两处升级：
+//!
+//! 1. **完整退出码表**：不只认 Linux 的 `137`，Windows 的 NTSTATUS
+//!    （`0xC0000005` 等）也要能说清是什么；
+//! 2. **静默失败单独立标**：退出码 0 但存活 <30s 或 stderr 带错误特征时标记
+//!    `silent_failure`——HMCL 会判 NORMAL 放过（LaunchWrapper 吞异常后 `exit 0` 是
+//!    真实存在的失败形态）。
+
+use crate::launch::pump::LogLine;
+
+/// 退出判定类型。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ExitType {
+    /// 正常退出。
+    Normal,
+    /// 应用层崩溃（游戏起来了但崩了）。
+    ApplicationError,
+    /// JVM 都没起来（`-Xmx` 过大、JVM 参数非法等）。
+    JvmError,
+    /// 被 `SIGKILL` 结束（POSIX 137）。
+    SigKill,
+    /// 被 `SIGTERM` 结束（POSIX 143）。
+    SigTerm,
+    /// 被启动器主动结束（用户点取消 / 看门狗强制）。
+    Killed,
+    /// 等待被中断。
+    Interrupted,
+}
+
+impl ExitType {
+    /// 事件流里的字符串形式（与 M15 `ExitType` 刻意保持一致）。
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Normal => "normal",
+            Self::ApplicationError => "application_error",
+            Self::JvmError => "jvm_error",
+            Self::SigKill => "sigkill",
+            Self::SigTerm => "sigterm",
+            Self::Killed => "killed",
+            Self::Interrupted => "interrupted",
+        }
+    }
+
+    /// 是否属于“非正常退出”。
+    pub fn is_abnormal(self) -> bool {
+        self != Self::Normal
+    }
+}
+
+/// JVM 未能启动的三条关键字（`analyse/02` §7.2）。
+pub const JVM_FAILURE_KEYWORDS: &[&str] = &[
+    "Could not create the Java Virtual Machine.",
+    "Error occurred during initialization of VM",
+    "A fatal exception has occurred. Program will exit.",
+];
+
+/// 应用层崩溃的五条关键字（`analyse/02` §7.2，覆盖三种崩法）。
+pub const CRASH_KEYWORDS: &[&str] = &[
+    "Crash report saved to",
+    "Could not save crash report to",
+    "This crash report has been saved to:",
+    "Unable to launch",
+    "An exception was thrown, the game will display an error screen and halt.",
+];
+
+/// 静默失败的存活阈值（毫秒）：<30s 视为“没真正跑起来”。
+pub const SHORT_LIVED_MS: u64 = 30_000;
+
+/// 退出分析的输入。
+#[derive(Debug, Clone, Copy)]
+pub struct ExitSignals<'a> {
+    /// 退出码。
+    pub code: i32,
+    /// 进程存活毫秒数。
+    pub uptime_ms: u64,
+    /// 环形缓冲里的日志行。
+    pub lines: &'a [LogLine],
+    /// 是否启动器主动结束。
+    pub killed: bool,
+    /// 等待是否被中断。
+    pub interrupted: bool,
+    /// 是否 POSIX（决定 137/143 是否按信号解读）。
+    pub is_posix: bool,
+}
+
+impl<'a> ExitSignals<'a> {
+    /// 构造。
+    pub fn new(code: i32, uptime_ms: u64, lines: &'a [LogLine]) -> Self {
+        Self {
+            code,
+            uptime_ms,
+            lines,
+            killed: false,
+            interrupted: false,
+            is_posix: cfg!(unix),
+        }
+    }
+}
+
+/// 静默失败标记。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct SilentFailure {
+    /// 存活时间过短。
+    pub short_lived: bool,
+    /// stderr/日志里有错误特征。
+    pub error_output: bool,
+}
+
+impl SilentFailure {
+    /// 人读说明。
+    pub fn describe(&self) -> String {
+        match (self.short_lived, self.error_output) {
+            (true, true) => "退出码 0，但存活不足 30 秒且输出含错误特征".to_string(),
+            (true, false) => "退出码 0，但存活不足 30 秒".to_string(),
+            (false, true) => "退出码 0，但输出含错误特征".to_string(),
+            (false, false) => "退出码 0".to_string(),
+        }
+    }
+}
+
+/// 退出分析结果（`exit` 事件的 payload 来源）。
+#[derive(Debug, Clone)]
+pub struct ExitAnalysis {
+    /// 退出码。
+    pub code: i32,
+    /// 判定类型。
+    pub exit_type: ExitType,
+    /// 存活毫秒数。
+    pub uptime_ms: u64,
+    /// 错误级日志行数。
+    pub error_lines: u32,
+    /// 命中的崩溃关键字。
+    pub crash_keywords: Vec<String>,
+    /// 命中的 JVM 失败关键字。
+    pub jvm_keywords: Vec<String>,
+    /// 静默失败标记（仅 `Normal` 时可能非空）。
+    pub silent_failure: Option<SilentFailure>,
+    /// Windows NTSTATUS 解释（例 `0xC0000005 ACCESS_VIOLATION`）。
+    pub windows_status: Option<String>,
+    /// 是否应该进入诊断流水线（M15）。
+    pub needs_diagnosis: bool,
+}
+
+impl ExitAnalysis {
+    /// 一句话摘要（UI/agent 可直接展示）。
+    pub fn summary(&self) -> String {
+        let mut text = format!(
+            "退出码 {}（{}），存活 {:.1}s，错误行 {}",
+            self.code,
+            self.exit_type.as_str(),
+            self.uptime_ms as f64 / 1000.0,
+            self.error_lines
+        );
+        if let Some(status) = &self.windows_status {
+            text.push_str(&format!("，{status}"));
+        }
+        if !self.crash_keywords.is_empty() {
+            text.push_str(&format!("，崩溃关键字 {}", self.crash_keywords.len()));
+        }
+        if let Some(silent) = &self.silent_failure {
+            text.push_str(&format!("，{}", silent.describe()));
+        }
+        text
+    }
+}
+
+/// 做退出分析。
+pub fn analyze(signals: &ExitSignals<'_>) -> ExitAnalysis {
+    let error_lines = signals.lines.iter().filter(|line| line.is_error()).count();
+    let crash_keywords = matched_keywords(signals.lines, CRASH_KEYWORDS);
+    let jvm_keywords = matched_keywords(signals.lines, JVM_FAILURE_KEYWORDS);
+    let error_output = signals
+        .lines
+        .iter()
+        .any(|line| line.is_error() && looks_like_failure(&line.text));
+
+    let exit_type = if signals.interrupted {
+        ExitType::Interrupted
+    } else if signals.killed {
+        ExitType::Killed
+    } else if signals.code != 0 && !jvm_keywords.is_empty() {
+        ExitType::JvmError
+    } else if signals.is_posix && signals.code == 137 {
+        ExitType::SigKill
+    } else if signals.is_posix && signals.code == 143 {
+        ExitType::SigTerm
+    } else if signals.code != 0 || !crash_keywords.is_empty() {
+        ExitType::ApplicationError
+    } else {
+        ExitType::Normal
+    };
+
+    let silent_failure = if exit_type == ExitType::Normal {
+        let short_lived = signals.uptime_ms < SHORT_LIVED_MS;
+        if short_lived || error_output {
+            Some(SilentFailure {
+                short_lived,
+                error_output,
+            })
+        } else {
+            None
+        }
+    } else {
+        None
+    };
+
+    ExitAnalysis {
+        code: signals.code,
+        exit_type,
+        uptime_ms: signals.uptime_ms,
+        error_lines: u32::try_from(error_lines).unwrap_or(u32::MAX),
+        crash_keywords: crash_keywords.clone(),
+        jvm_keywords,
+        silent_failure,
+        windows_status: windows_status_name(signals.code),
+        needs_diagnosis: exit_type.is_abnormal()
+            || silent_failure.is_some()
+            || !crash_keywords.is_empty(),
+    }
+}
+
+/// Windows NTSTATUS → 解释。
+pub fn windows_status_name(code: i32) -> Option<String> {
+    let (hex, name) = match code {
+        -1_073_741_819 => ("0xC0000005", "ACCESS_VIOLATION"),
+        -1_073_740_791 => ("0xC0000409", "STACK_BUFFER_OVERRUN"),
+        -1_073_741_515 => ("0xC0000135", "DLL_NOT_FOUND"),
+        -1_073_741_571 => ("0xC00000FD", "STACK_OVERFLOW"),
+        -1_073_741_510 => ("0xC000013A", "CONTROL_C_EXIT"),
+        _ => return None,
+    };
+    Some(format!("{hex} {name}"))
+}
+
+/// 退出码的人工提示（附录 C 速查表的裁剪版）。
+pub fn exit_code_hint(code: i32, is_posix: bool) -> Option<&'static str> {
+    match code {
+        0 => Some("正常退出"),
+        1 => Some("通用失败（含 JVM 启动失败）"),
+        137 if is_posix => Some("SIGKILL：被强杀"),
+        143 if is_posix => Some("SIGTERM：被请求退出"),
+        _ => None,
+    }
+}
+
+fn matched_keywords(lines: &[LogLine], keywords: &[&str]) -> Vec<String> {
+    keywords
+        .iter()
+        .filter(|keyword| lines.iter().any(|line| line.text.contains(**keyword)))
+        .map(|keyword| (*keyword).to_string())
+        .collect()
+}
+
+/// “像失败的输出”：显式异常/错误特征（不是任何 stderr 输出都算）。
+fn looks_like_failure(text: &str) -> bool {
+    let lower = text.to_ascii_lowercase();
+    lower.contains("exception")
+        || lower.contains("caused by")
+        || lower.contains("fatal")
+        || lower.contains("error:")
+        || lower.contains("failed")
+}
diff --git a/crates/core/src/launch/game_args.rs b/crates/core/src/launch/game_args.rs
new file mode 100644
index 0000000..4d33865
--- /dev/null
+++ b/crates/core/src/launch/game_args.rs
@@ -0,0 +1,206 @@
+//! 参数后段：清单 JVM 参数尾部（第 20~23 项）与游戏参数（第 24~32 项）。
+//!
+//! 顺序本身有语义（`analyse/02` §4.1）：清单 JVM 参数在用户 `javaArguments` 之后
+//! **无条件追加**，因此能覆盖用户参数，但覆盖不了用户的 override 参数；
+//! 用户自定义游戏参数永远最后追加，是可以覆盖前面一切游戏参数的“逃生门”。
+
+use crate::launch::args_table::AssemblyWarning;
+use crate::launch::argument::{ArgumentEntry, RuleContext};
+use crate::launch::command_builder::{tokenize, CommandBuilder};
+use crate::launch::defaults;
+use crate::launch::game_version::GameVersion;
+use crate::launch::platform::PlatformCtx;
+use crate::launch::request::{LaunchRequest, QuickPlay};
+
+/// `--graphicsBackend` 的最低版本（实测首发：`26.2-snapshot-2`，2026-04-09）。
+pub const GRAPHICS_BACKEND_MIN_VERSION: &str = "26.2-snapshot-2";
+
+/// `--graphicsBackend` 能否下发给这个版本。
+///
+/// 两条判据**不要合并**（`research/05-mc-vulkan.md` §3.2/§4.2 的实测结论）：
+///
+/// - **可解析版本**走精确门限 `26.2-snapshot-2`。`26.2-snapshot-1` 已经有 `lwjgl-vulkan`
+///   库但 `Main.class` 还没声明这个参数，用能力位放行会让它 `UnrecognizedOptionException`
+///   直接起不来——库早了两天。
+/// - **周快照**（`26w14a` 形态）无法与 `26.2-snapshot-N` 排序，只能信版本库表：
+///   带 `lwjgl-vulkan` 就放行（26.1 全线含周快照都没有该库，所以这个推断安全）。
+pub fn graphics_backend_allowed(version: &GameVersion, has_vulkan_backend: bool) -> bool {
+    if version.is_known() {
+        return version.is_at_least(GRAPHICS_BACKEND_MIN_VERSION);
+    }
+    version.is_weekly_snapshot() && has_vulkan_backend
+}
+
+/// 应用第 20~32 项，返回告警。
+pub(crate) fn apply_game_arguments(
+    req: &LaunchRequest,
+    ctx: &PlatformCtx,
+    builder: &mut CommandBuilder,
+) -> Vec<AssemblyWarning> {
+    let mut warnings = Vec::new();
+    let rule_ctx = RuleContext::new(
+        ctx.os.manifest_name(),
+        &ctx.arch,
+        &ctx.os_version,
+        &req.features,
+    );
+
+    // 第 20 项：清单 JVM 参数（现代）或 legacy 默认 JVM 参数。
+    if req.manifest.jvm.is_empty() {
+        builder.add_all_default(&defaults::legacy_jvm_arguments());
+    } else {
+        let values = collect_applicable(&req.manifest.jvm, &rule_ctx);
+        builder.add_all(&values);
+    }
+
+    // 第 21 项：登录源提供的 JVM 参数（authlib-injector 等）。
+    for arg in &req.auth_jvm_args {
+        builder.add(arg);
+    }
+
+    // 第 22 项：`-javaagent:` × N。
+    for agent in &req.java_agents {
+        builder.add(&format!("-javaagent:{agent}"));
+    }
+
+    // 第 23 项：主类（args_table 已保证非空）。
+    if let Some(main_class) = &req.manifest.main_class {
+        builder.add(main_class);
+    }
+
+    // 第 24 项：legacy `minecraftArguments` 整串分词。
+    if let Some(legacy) = &req.manifest.legacy_arguments {
+        for token in tokenize(legacy) {
+            builder.add(&token);
+        }
+    }
+
+    // 第 25 项：现代 `arguments.game`（带 rules/features）。
+    if !req.manifest.game.is_empty() {
+        let values = collect_applicable(&req.manifest.game, &rule_ctx);
+        builder.add_all(&values);
+    }
+
+    // 第 26 项：legacy 默认游戏参数（分辨率）。
+    if req.manifest.legacy_arguments.is_some() {
+        builder.add_all(&defaults::legacy_game_args(req.resolution.as_ref()));
+    }
+
+    // 第 27 项：登录源提供的游戏参数。
+    for arg in &req.auth_game_args {
+        builder.add(arg);
+    }
+
+    // 第 28 项：QuickPlay / `--server --port`。
+    apply_quick_play(req, builder, &mut warnings);
+
+    // 第 29 项：全屏。
+    if req.fullscreen {
+        builder.add("--fullscreen");
+    }
+
+    // 第 30 项：SOCKS 代理的游戏侧参数。
+    if let Some(proxy) = &req.proxy {
+        builder.add("--proxyHost");
+        builder.add(&proxy.host);
+        builder.add("--proxyPort");
+        builder.add(&proxy.port.to_string());
+        if let Some(username) = &proxy.username {
+            builder.add("--proxyUser");
+            builder.add(username);
+        }
+        if let Some(password) = &proxy.password {
+            builder.add("--proxyPass");
+            builder.add(password);
+        }
+    }
+
+    // 第 31 项：图形后端（精确门限 ≥26.2-snapshot-2，周快照走库表兜底）。
+    if let Some(backend) = &req.graphics_backend {
+        if graphics_backend_allowed(&req.instance.version, req.manifest.has_vulkan_backend) {
+            builder.add("--graphicsBackend");
+            builder.add(backend);
+        } else {
+            warnings.push(AssemblyWarning::GraphicsBackendSkipped {
+                version: req.instance.version.raw().to_string(),
+            });
+        }
+    }
+
+    // 第 32 项：用户自定义游戏参数（最后追加，可覆盖一切）。
+    builder.add_all(&req.user.game);
+
+    warnings
+}
+
+fn apply_quick_play(
+    req: &LaunchRequest,
+    builder: &mut CommandBuilder,
+    warnings: &mut Vec<AssemblyWarning>,
+) {
+    let Some(quick_play) = &req.quick_play else {
+        return;
+    };
+    let supports = req.instance.version.is_at_least("1.20");
+    match quick_play {
+        QuickPlay::Singleplayer { world } if supports => {
+            builder.add("--quickPlaySingleplayer");
+            builder.add(world);
+        }
+        QuickPlay::Multiplayer { address } if supports => {
+            builder.add("--quickPlayMultiplayer");
+            builder.add(address);
+        }
+        QuickPlay::Realms { realm_id } if supports => {
+            builder.add("--quickPlayRealms");
+            builder.add(realm_id);
+        }
+        QuickPlay::Multiplayer { address } => match parse_server_address(address) {
+            Some((host, port)) => {
+                builder.add("--server");
+                builder.add(&host);
+                if let Some(port) = port {
+                    builder.add("--port");
+                    builder.add(&port.to_string());
+                }
+                warnings.push(AssemblyWarning::QuickPlayDegraded {
+                    address: address.clone(),
+                });
+            }
+            None => warnings.push(AssemblyWarning::QuickPlayAddressInvalid {
+                address: address.clone(),
+            }),
+        },
+        QuickPlay::Singleplayer { .. } | QuickPlay::Realms { .. } => {
+            warnings.push(AssemblyWarning::QuickPlayUnsupported {
+                version: req.instance.version.raw().to_string(),
+            });
+        }
+    }
+}
+
+/// 解析 `host[:port]`；端口非法或为空时该段视为不存在。
+pub fn parse_server_address(address: &str) -> Option<(String, Option<u16>)> {
+    let trimmed = address.trim();
+    if trimmed.is_empty() {
+        return None;
+    }
+    match trimmed.rsplit_once(':') {
+        Some((host, port)) if !host.is_empty() => match port.parse::<u16>() {
+            Ok(port) if port > 0 => Some((host.to_string(), Some(port))),
+            _ => None,
+        },
+        Some(_) => None,
+        None => Some((trimmed.to_string(), None)),
+    }
+}
+
+fn collect_applicable(entries: &[ArgumentEntry], ctx: &RuleContext<'_>) -> Vec<String> {
+    let mut values = Vec::new();
+    for entry in entries {
+        if entry.applies(ctx) {
+            values.extend(entry.values.iter().cloned());
+        }
+    }
+    values
+}
diff --git a/crates/core/src/launch/game_version.rs b/crates/core/src/launch/game_version.rs
new file mode 100644
index 0000000..05e348b
--- /dev/null
+++ b/crates/core/src/launch/game_version.rs
@@ -0,0 +1,178 @@
+//! 游戏版本号解析与比较（供命令行组装的分支门限使用）。
+//!
+//! 依据 `analyse/02` §5.2（版本号驱动的分支：legacy/modern 参数模板、log4j 注入、
+//! `--quickPlay*` 门限、`--graphicsBackend` 门限）。
+//!
+//! 说明：这是 launch 侧的最小比较器。若 M14（game）后续提供权威 `GameVersion` 比较器，
+//! 只需替换本文件内部实现，`is_at_least` / `is_before` 的调用点不用动
+//! （见 `DevDocs/SubAgentsTalk/launch-接口约定.md` §7-3）。
+
+use std::cmp::Ordering;
+use std::fmt;
+
+/// 版本的发布阶段。派生 `Ord` 的变体顺序即排序顺序：Snapshot < PreRelease < ReleaseCandidate < Release。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub enum Stage {
+    /// 快照（`26.2-snapshot-2`），数字为快照序号。
+    Snapshot(u32),
+    /// 预发布（`1.20-pre1`）。
+    PreRelease(u32),
+    /// 候选发布（`1.20-rc1`）。
+    ReleaseCandidate(u32),
+    /// 正式版。
+    Release,
+}
+
+/// 游戏版本号。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct GameVersion {
+    raw: String,
+    parts: Vec<u32>,
+    stage: Stage,
+}
+
+impl GameVersion {
+    /// 解析版本串；无法识别（如 `20w14a`）时返回 [`GameVersion::unknown`]。
+    pub fn parse(raw: &str) -> Self {
+        let trimmed = raw.trim();
+        let (base, stage) = split_stage(trimmed);
+        let parts = base
+            .split('.')
+            .map_while(|piece| piece.parse::<u32>().ok())
+            .collect::<Vec<_>>();
+        if parts.is_empty() {
+            return Self::unknown(trimmed);
+        }
+        Self {
+            raw: trimmed.to_string(),
+            parts,
+            stage,
+        }
+    }
+
+    /// 未知/无法解析的版本（比较结果为“不满足任何门限”，由调用方给默认分支）。
+    pub fn unknown(raw: &str) -> Self {
+        Self {
+            raw: raw.to_string(),
+            parts: Vec::new(),
+            stage: Stage::Release,
+        }
+    }
+
+    /// 原始版本串。
+    pub fn raw(&self) -> &str {
+        &self.raw
+    }
+
+    /// 是否解析出了数字版本（`false` 表示未知形状，例如周快照）。
+    pub fn is_known(&self) -> bool {
+        !self.parts.is_empty()
+    }
+
+    /// 是否是**周快照**形态（`20w14a` / `26w14a`）。
+    ///
+    /// 周快照是「年(2 位) + `w` + 周(2 位) + 字母」的独立命名族，与 `26.2-snapshot-N`
+    /// 分属两套编号，**无法**可靠排序；所以 [`Self::is_known`] 对它恒为 `false`
+    /// （不猜，免得误触发「老版本」分支去套 legacy 参数模板）。要判能力请改看版本 JSON 的
+    /// 库表（[`crate::game::capability`]），别在这里编一套排序规则。
+    pub fn is_weekly_snapshot(&self) -> bool {
+        is_weekly_snapshot_str(&self.raw)
+    }
+
+    /// 主版本号（`1.20.1` → 1，`26.2` → 26）。
+    pub fn major(&self) -> u32 {
+        self.parts.first().copied().unwrap_or(0)
+    }
+
+    /// 是否 `>= other`。自身或 `other` 不可解析时返回 `false`。
+    pub fn is_at_least(&self, other: &str) -> bool {
+        let other = Self::parse(other);
+        if !self.is_known() || !other.is_known() {
+            return false;
+        }
+        self.cmp(&other) != Ordering::Less
+    }
+
+    /// 是否 `< other`。自身不可解析时返回 `false`（未知版本不触发“老版本”分支）。
+    pub fn is_before(&self, other: &str) -> bool {
+        let other = Self::parse(other);
+        if !self.is_known() || !other.is_known() {
+            return false;
+        }
+        self.cmp(&other) == Ordering::Less
+    }
+
+    /// 去掉尾部 0 后的分量序列（`1.20.0` 与 `1.20` 等价）。
+    fn trimmed_parts(&self) -> &[u32] {
+        let mut end = self.parts.len();
+        while end > 0 && self.parts[end - 1] == 0 {
+            end -= 1;
+        }
+        &self.parts[..end]
+    }
+}
+
+impl Ord for GameVersion {
+    fn cmp(&self, other: &Self) -> Ordering {
+        self.trimmed_parts()
+            .cmp(other.trimmed_parts())
+            .then_with(|| self.stage.cmp(&other.stage))
+    }
+}
+
+impl PartialOrd for GameVersion {
+    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
+        Some(self.cmp(other))
+    }
+}
+
+impl fmt::Display for GameVersion {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(&self.raw)
+    }
+}
+
+impl Default for GameVersion {
+    fn default() -> Self {
+        Self::unknown("")
+    }
+}
+
+fn split_stage(raw: &str) -> (&str, Stage) {
+    for marker in ["-snapshot", " snapshot"] {
+        if let Some(pos) = raw.find(marker) {
+            let number = trailing_number(&raw[pos + marker.len()..]);
+            return (&raw[..pos], Stage::Snapshot(number));
+        }
+    }
+    for marker in ["-pre", "-preview"] {
+        if let Some(pos) = raw.find(marker) {
+            let number = trailing_number(&raw[pos + marker.len()..]);
+            return (&raw[..pos], Stage::PreRelease(number));
+        }
+    }
+    if let Some(pos) = raw.find("-rc") {
+        let number = trailing_number(&raw[pos + 3..]);
+        return (&raw[..pos], Stage::ReleaseCandidate(number));
+    }
+    (raw, Stage::Release)
+}
+
+fn trailing_number(text: &str) -> u32 {
+    let digits = text.trim_start_matches(['-', '.', '_']);
+    digits
+        .split(|ch: char| !ch.is_ascii_digit())
+        .next()
+        .and_then(|piece| piece.parse::<u32>().ok())
+        .unwrap_or(0)
+}
+
+/// `20w14a` / `26w14a` 形态判定（纯函数，便于单测）。
+fn is_weekly_snapshot_str(raw: &str) -> bool {
+    let bytes = raw.trim().as_bytes();
+    bytes.len() == 6
+        && bytes[..2].iter().all(u8::is_ascii_digit)
+        && bytes[2].eq_ignore_ascii_case(&b'w')
+        && bytes[3..5].iter().all(u8::is_ascii_digit)
+        && bytes[5].is_ascii_alphabetic()
+}
diff --git a/crates/core/src/launch/jvm_args.rs b/crates/core/src/launch/jvm_args.rs
new file mode 100644
index 0000000..0794cb2
--- /dev/null
+++ b/crates/core/src/launch/jvm_args.rs
@@ -0,0 +1,149 @@
+//! JVM 参数段（`analyse/02` §4.1 的第 8~17 项）。
+//!
+//! 这一段全部走“默认值抑制”：用户/清单显式写过的键我们一律不覆盖。
+//! 返回最终生效的日志解码编码——它要传给日志泵（`analyse/02` §4.4）。
+
+use crate::launch::args_table::AssemblyWarning;
+use crate::launch::command_builder::CommandBuilder;
+use crate::launch::defaults;
+use crate::launch::platform::{OsFamily, PlatformCtx};
+use crate::launch::request::LaunchRequest;
+
+/// 应用第 8~17 项，返回（日志解码编码，告警）。
+pub(crate) fn apply_jvm_arguments(
+    req: &LaunchRequest,
+    ctx: &PlatformCtx,
+    builder: &mut CommandBuilder,
+) -> (String, Vec<AssemblyWarning>) {
+    let mut warnings = Vec::new();
+    let java = &req.java;
+
+    // 第 8 项：编码（`-Dfile.encoding=` + stdout/stderr 编码）。
+    let requested = match req.encoding.as_deref() {
+        Some(value) if !value.eq_ignore_ascii_case("COMPAT") => value.to_string(),
+        _ => ctx.native_charset.clone(),
+    };
+    let existing = builder.add_default("-Dfile.encoding=", &requested);
+    let mut encoding = existing
+        .as_deref()
+        .and_then(|arg| arg.strip_prefix("-Dfile.encoding="))
+        .unwrap_or(&requested)
+        .to_string();
+    if encoding.eq_ignore_ascii_case("COMPAT") {
+        encoding = ctx.native_charset.clone();
+    }
+    builder.add_all_default(&defaults::stream_encoding_args(java.major, &encoding));
+
+    // 第 9 项：Log4j2 RCE 缓解三件套。
+    builder.add_all_default(&defaults::log4j_mitigation_args());
+
+    // 第 10 项：formatMsgNoLookups + 日志配置注入。
+    let lookups = builder.add_default("-Dlog4j2.formatMsgNoLookups=", "true");
+    let user_disabled_lookups = lookups.as_deref() == Some("-Dlog4j2.formatMsgNoLookups=false");
+    if req.log4j.enabled && (!user_disabled_lookups || req.log4j.debug) {
+        match &req.log4j.config_file {
+            Some(path) => {
+                let value = path.display().to_string();
+                let _ = builder.add_default("-Dlog4j.configurationFile=", &value);
+            }
+            None => warnings.push(AssemblyWarning::Log4jConfigMissing),
+        }
+    }
+
+    // 第 11 项：品牌/特性钩子注入的额外 JVM 参数。
+    for arg in &req.extra_jvm {
+        builder.add(arg);
+    }
+
+    // 第 12 项：主 jar、macOS dock、`-Duser.home`（仅非 Windows）。
+    let primary_jar = req.dirs.primary_jar.display().to_string();
+    let _ = builder.add_default("-Dminecraft.client.jar=", &primary_jar);
+    if ctx.os == OsFamily::MacOs && !req.launcher.name.is_empty() {
+        let name = req.launcher.name.clone();
+        let _ = builder.add_default("-Xdock:name=", &name);
+    }
+    if ctx.os != OsFamily::Windows {
+        if let Some(home) = &ctx.home_dir {
+            let value = home.display().to_string();
+            let _ = builder.add_default("-Duser.home=", &value);
+        }
+    }
+
+    // 第 13 项：代理（用户已写任意代理参数则整体跳过，`analyse/02` §4.1 #13）。
+    if let Some(proxy) = &req.proxy {
+        if user_has_proxy_args(req) {
+            warnings.push(AssemblyWarning::ProxyJvmArgsSkipped);
+        } else {
+            apply_proxy(builder, proxy);
+        }
+    }
+
+    // 第 14 项：自动优化。
+    if req.optimization.enabled {
+        let args = defaults::optimization_args(
+            java.major,
+            java.bits,
+            req.optimization.physical_memory_mb,
+            user_specified_gc(req),
+        );
+        builder.add_all_default(&args);
+    }
+
+    // 第 15 项：版本特定开关。
+    builder.add_all_default(&defaults::version_specific_args(java.major));
+
+    // 第 16 项：FML 证书豁免。
+    if req.mod_loader.is_fml_like() {
+        builder.add_all_default(&defaults::fml_args());
+    }
+
+    // 第 17 项：渲染器。
+    builder.add_all_default(&defaults::renderer_args(&req.renderer));
+
+    (encoding, warnings)
+}
+
+fn apply_proxy(builder: &mut CommandBuilder, proxy: &crate::launch::request::SocksProxy) {
+    let port = proxy.port.to_string();
+    for key in ["http.proxyHost", "https.proxyHost", "socksProxyHost"] {
+        let _ = builder.add_default(&format!("-D{key}="), &proxy.host);
+    }
+    for key in ["http.proxyPort", "https.proxyPort", "socksProxyPort"] {
+        let _ = builder.add_default(&format!("-D{key}="), &port);
+    }
+    if let Some(username) = &proxy.username {
+        for key in ["http.proxyUser", "https.proxyUser"] {
+            let _ = builder.add_default(&format!("-D{key}="), username);
+        }
+    }
+    if let Some(password) = &proxy.password {
+        for key in ["http.proxyPassword", "https.proxyPassword"] {
+            let _ = builder.add_default(&format!("-D{key}="), password);
+        }
+    }
+}
+
+fn user_has_proxy_args(req: &LaunchRequest) -> bool {
+    req.user
+        .override_jvm
+        .iter()
+        .chain(req.user.jvm.iter())
+        .any(|arg| arg.starts_with("-D") && arg.to_ascii_lowercase().contains("proxy"))
+}
+
+fn user_specified_gc(req: &LaunchRequest) -> bool {
+    req.user
+        .override_jvm
+        .iter()
+        .chain(req.user.jvm.iter())
+        .chain(
+            req.manifest
+                .jvm
+                .iter()
+                .flat_map(|entry| entry.values.iter()),
+        )
+        .any(|arg| {
+            let lower = arg.to_ascii_lowercase();
+            lower.starts_with("-xx:+use") || lower.starts_with("-xx:-use")
+        })
+}
diff --git a/crates/core/src/launch/launch_session.rs b/crates/core/src/launch/launch_session.rs
new file mode 100644
index 0000000..529a406
--- /dev/null
+++ b/crates/core/src/launch/launch_session.rs
@@ -0,0 +1,329 @@
+//! 运行中的启动会话与收尾流水线。
+//!
+//! 一次启动的生命周期（`DevDocs/PlanDoc/06-launch-and-diagnostics.md` §1 的第 7~10 阶段）：
+//! `spawn` → 用户可能 [`LaunchSession::stop`] → [`LaunchSession::finish`]
+//! （等进程 → 等日志泵（有预算）→ 退出分析 → 扫崩溃现场 → 诊断挂钩 → 写事件 + 索引）。
+
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+use std::time::SystemTime;
+
+use serde_json::Value;
+
+use crate::launch::args_table::AssembledCommand;
+use crate::launch::crash_scan::{self, CrashArtifact};
+use crate::launch::diagnosis_hook::{DiagnosisHook, DiagnosisRequest};
+use crate::launch::error::Result;
+use crate::launch::exit_analysis::{self, ExitAnalysis, ExitSignals};
+use crate::launch::launcher::LauncherConfig;
+use crate::launch::process::{self, RunningProcess};
+use crate::launch::pump::{LineSink, LogLine};
+use crate::launch::redact::Redactor;
+use crate::launch::request::LaunchRequest;
+use crate::launch::session::{EndReason, SessionSink};
+use crate::launch::session_index::SessionIndexEntry;
+
+/// 一次运行中的启动会话。
+pub struct LaunchSession {
+    config: LauncherConfig,
+    hook: Arc<dyn DiagnosisHook>,
+    redactor: Redactor,
+    request: LaunchRequest,
+    session_id: String,
+    log_path: PathBuf,
+    command: AssembledCommand,
+    pid: u32,
+    process: RunningProcess,
+    sink: Arc<SessionSink>,
+    started_wall: SystemTime,
+    killed: bool,
+}
+
+impl std::fmt::Debug for LaunchSession {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("LaunchSession")
+            .field("session_id", &self.session_id)
+            .field("pid", &self.pid)
+            .field("log_path", &self.log_path)
+            .finish()
+    }
+}
+
+impl LaunchSession {
+    #[allow(clippy::too_many_arguments)]
+    pub(crate) fn new(
+        config: LauncherConfig,
+        hook: Arc<dyn DiagnosisHook>,
+        redactor: Redactor,
+        request: LaunchRequest,
+        session_id: String,
+        log_path: PathBuf,
+        command: AssembledCommand,
+        pid: u32,
+        process: RunningProcess,
+        sink: Arc<SessionSink>,
+    ) -> Self {
+        Self {
+            config,
+            hook,
+            redactor,
+            request,
+            session_id,
+            log_path,
+            command,
+            pid,
+            process,
+            sink,
+            started_wall: SystemTime::now(),
+            killed: false,
+        }
+    }
+
+    /// 进程号。
+    pub fn pid(&self) -> u32 {
+        self.pid
+    }
+
+    /// 会话 id。
+    pub fn session_id(&self) -> &str {
+        &self.session_id
+    }
+
+    /// 事件流文件路径。
+    pub fn log_path(&self) -> &Path {
+        &self.log_path
+    }
+
+    /// 组装结果。
+    pub fn command(&self) -> &AssembledCommand {
+        &self.command
+    }
+
+    /// 是否已请求停止。
+    pub fn is_killed(&self) -> bool {
+        self.killed
+    }
+
+    /// 日志 sink（可再叠加 UI/测试消费者，见 [`crate::launch::sink`]）。
+    pub fn sink(&self) -> Arc<dyn LineSink> {
+        self.sink.clone() as Arc<dyn LineSink>
+    }
+
+    /// 已运行毫秒数。
+    pub fn uptime_ms(&self) -> u64 {
+        self.process.uptime_ms()
+    }
+
+    /// 用户/看门狗请求停止：三段式回收进程树，并记 `killed` 事件。
+    pub fn stop(&mut self) -> Result<()> {
+        if self.killed {
+            return Ok(());
+        }
+        self.killed = true;
+        if let Some(result) = self.sink.with_writer(|writer| writer.killed("user", None)) {
+            let _ = result;
+        }
+        self.process.stop()
+    }
+
+    /// 收尾：等进程 → 等日志泵 → 退出分析 → 现场扫描 → 诊断 → 事件 + 索引。
+    pub fn finish(mut self) -> Result<SessionHandle> {
+        let status = self.process.wait()?;
+        let code = process::exit_code(&status);
+        // uptime 必须在等日志泵之前取（泵的等待预算不算进游戏存活时间）。
+        let uptime_ms = self.process.uptime_ms();
+        let verdict = self.process.supervise();
+        let pump_stalled = !verdict.is_complete();
+        let lines = self.process.lines();
+
+        let mut signals = ExitSignals::new(code, uptime_ms, &lines);
+        signals.killed = self.killed;
+        signals.is_posix = self.config.platform.os.is_posix();
+        let exit = exit_analysis::analyze(&signals);
+
+        let artifacts = self.collect_artifacts();
+        // 脱敏只算一次：诊断包与 `SessionHandle::redacted_argv()` 共用。
+        let redacted_argv = self.redactor.scrub_all(&self.command.argv());
+        let diagnosis_request = self.build_diagnosis_request(
+            &exit,
+            &lines,
+            &artifacts,
+            uptime_ms,
+            redacted_argv.clone(),
+        );
+        let should_diagnose = exit.needs_diagnosis || !artifacts.is_empty();
+        let diagnosis = if should_diagnose {
+            self.hook.analyze(&diagnosis_request)
+        } else {
+            None
+        };
+
+        let mut event_write_errors = Vec::new();
+        let mut diagnostics = None;
+        let mut index = None;
+        let end_reason = if self.killed {
+            EndReason::Killed
+        } else {
+            EndReason::Exit
+        };
+        let completed = self.sink.with_writer(|writer| {
+            if let Err(err) = writer.exit(&exit) {
+                event_write_errors.push(err.to_string());
+            }
+            for artifact in &artifacts {
+                let result = writer.crash_found(
+                    artifact.source.as_str(),
+                    &artifact.path,
+                    artifact.excerpt.as_deref(),
+                );
+                if let Err(err) = result {
+                    event_write_errors.push(err.to_string());
+                }
+            }
+            if let Some(record) = diagnosis {
+                if let Err(err) = writer.diagnosis(record.clone()) {
+                    event_write_errors.push(err.to_string());
+                }
+                diagnostics = Some(record);
+            }
+            match writer.finish(end_reason) {
+                Ok(entry) => index = Some(entry),
+                Err(err) => event_write_errors.push(err.to_string()),
+            }
+        });
+        if completed.is_none() {
+            event_write_errors.push("会话写入器不可用（锁中毒）".to_string());
+        }
+
+        Ok(SessionHandle {
+            session_id: self.session_id,
+            log_path: self.log_path,
+            command: self.command,
+            redacted_argv,
+            exit,
+            diagnostics,
+            index,
+            artifacts,
+            uptime_ms,
+            pump_stalled,
+            event_write_errors,
+        })
+    }
+
+    fn collect_artifacts(&self) -> Vec<CrashArtifact> {
+        if !self.config.scan_crash_reports {
+            return Vec::new();
+        }
+        let run_dir = self.run_dir();
+        crash_scan::scan(&run_dir, self.started_wall, self.config.max_crash_artifacts)
+    }
+
+    fn build_diagnosis_request(
+        &self,
+        exit: &ExitAnalysis,
+        lines: &[LogLine],
+        artifacts: &[CrashArtifact],
+        uptime_ms: u64,
+        argv: Vec<String>,
+    ) -> DiagnosisRequest {
+        DiagnosisRequest {
+            session_id: self.session_id.clone(),
+            instance_id: self.request.instance.id.clone(),
+            instance_name: self.request.instance.name.clone(),
+            game_version: self.request.instance.version.raw().to_string(),
+            exit: exit.clone(),
+            uptime_ms,
+            log_lines: lines
+                .iter()
+                .map(|line| LogLine::new(line.stream, self.redactor.scrub(&line.text).into_owned()))
+                .collect(),
+            artifacts: artifacts.to_vec(),
+            argv,
+            memory_mb: self.command.memory.max_mb,
+            java_major: self.request.java.major,
+            java_binary: self.request.java.binary.clone(),
+            game_dir: self.run_dir(),
+        }
+    }
+
+    fn run_dir(&self) -> PathBuf {
+        if self.request.dirs.game_dir.as_os_str().is_empty() {
+            std::env::current_dir().unwrap_or_default()
+        } else {
+            self.request.dirs.game_dir.clone()
+        }
+    }
+}
+
+/// 一次启动的结果。
+#[derive(Debug, Clone)]
+pub struct SessionHandle {
+    /// 会话 id。
+    pub session_id: String,
+    /// 事件流文件。
+    pub log_path: PathBuf,
+    /// 组装结果（`argv()` 含凭据明文；对外展示/上报请用 [`Self::redacted_argv`]）。
+    pub command: AssembledCommand,
+    /// 脱敏后的完整 argv（accessToken → `<redacted:token>`，主目录 → `<home>`）。
+    redacted_argv: Vec<String>,
+    /// 退出判定。
+    pub exit: ExitAnalysis,
+    /// 诊断结论（M15 产出，已写入事件流）。
+    pub diagnostics: Option<Value>,
+    /// 索引条目（写入 `index.jsonl` 的那一行）。
+    pub index: Option<SessionIndexEntry>,
+    /// 崩溃现场文件。
+    pub artifacts: Vec<CrashArtifact>,
+    /// 游戏存活毫秒数。
+    pub uptime_ms: u64,
+    /// 日志泵是否超时（watchdog 触发 = 有子进程没关 stdout）。
+    pub pump_stalled: bool,
+    /// 会话写入错误（磁盘问题；不影响进程结果）。
+    pub event_write_errors: Vec<String>,
+}
+
+impl SessionHandle {
+    /// 脱敏后的完整 argv（UI/日志/上报都用它，别直接外发 `command.argv()`）。
+    pub fn redacted_argv(&self) -> &[String] {
+        &self.redacted_argv
+    }
+
+    /// 脱敏后的一行人读命令行。
+    pub fn redacted_display(&self) -> String {
+        self.redacted_argv
+            .iter()
+            .map(|arg| crate::launch::command_builder::quote_for_display(arg))
+            .collect::<Vec<_>>()
+            .join(" ")
+    }
+
+    /// 是否“正常且无异常”：退出判定 NORMAL 且没有静默失败标记。
+    pub fn succeeded(&self) -> bool {
+        !self.exit.exit_type.is_abnormal() && self.exit.silent_failure.is_none()
+    }
+
+    /// 是否需要进诊断（等价于 `exit.needs_diagnosis`，保留给上层判空）。
+    pub fn needs_diagnosis(&self) -> bool {
+        self.exit.needs_diagnosis
+    }
+
+    /// 一句话摘要。
+    pub fn summary(&self) -> String {
+        let mut text = format!("会话 {}：{}", self.session_id, self.exit.summary());
+        if self.pump_stalled {
+            text.push_str("；日志泵超时");
+        }
+        if let Some(top) = &self.diagnostics {
+            if let Some(id) = top
+                .get("candidates")
+                .and_then(Value::as_array)
+                .and_then(|items| items.first())
+                .and_then(|item| item.get("id"))
+                .and_then(Value::as_str)
+            {
+                text.push_str(&format!("；诊断首因 {id}"));
+            }
+        }
+        text
+    }
+}
diff --git a/crates/core/src/launch/launcher.rs b/crates/core/src/launch/launcher.rs
new file mode 100644
index 0000000..ea023b6
--- /dev/null
+++ b/crates/core/src/launch/launcher.rs
@@ -0,0 +1,298 @@
+//! 顶层启动管线：组装 → 会话 → 进程 → 退出分析 → 诊断 → 索引。
+//!
+//! 对应 `DevDocs/PlanDoc/06-launch-and-diagnostics.md` §1 的 10 阶段：
+//! 1~2（快照/账户）由调用方与 `adapter` 完成，3（Java 选择）由 D13 给出 `JavaSelection`，
+//! 4（组件就绪检查）由 download/game 给出 `missing_components`，6（环境准备的 natives 段）
+//! 由 [`crate::launch::natives`] 在本模块收口，5、7~10 见下。
+//!
+//! 两个入口：
+//! - [`Launcher::dry_run`]（D18 接线点）：只组装、不 spawn、不写会话文件，返回完整命令行；
+//! - [`Launcher::launch`]：完整跑一局，返回 [`SessionHandle`]（退出判定 + 诊断结论 + 索引条目）。
+//!
+//! 阶段 B 说明：diagnose（M15）尚未合并，诊断走 [`DiagnosisHook`] 接缝，默认 [`NoopDiagnosis`]。
+
+use std::path::PathBuf;
+use std::sync::Arc;
+use std::time::Instant;
+
+use crate::launch::args_table::{assemble, AssembledCommand};
+use crate::launch::diagnosis_hook::{DiagnosisHook, NoopDiagnosis};
+use crate::launch::error::{AssemblyError, Result};
+use crate::launch::launch_session::{LaunchSession, SessionHandle};
+use crate::launch::natives::{self, NativesReport};
+use crate::launch::platform::PlatformCtx;
+use crate::launch::process::{ProcessConfig, RunningProcess};
+use crate::launch::redact::Redactor;
+use crate::launch::request::LaunchRequest;
+use crate::launch::session::{EndReason, SessionMeta, SessionSink, SessionWriter};
+
+/// 启动器配置。
+#[derive(Debug, Clone)]
+pub struct LauncherConfig {
+    /// 会话文件根目录（`<data_root>/agent/sessions`）。
+    pub sessions_root: PathBuf,
+    /// 平台上下文（命令行分支 + 退出码语义）。
+    pub platform: PlatformCtx,
+    /// 进程管理配置（看门狗/宽限期/环形缓冲）。
+    pub process: ProcessConfig,
+    /// 启动器名（`${launcher_name}`，请求里非空时以请求为准）。
+    pub launcher_name: String,
+    /// 启动器版本。
+    pub launcher_version: String,
+    /// 用户主目录（脱敏用）。
+    pub home_dir: Option<PathBuf>,
+    /// 结束后是否扫描崩溃现场文件。
+    pub scan_crash_reports: bool,
+    /// 现场文件最多收几个。
+    pub max_crash_artifacts: usize,
+}
+
+impl LauncherConfig {
+    /// 以会话根目录构造（其余取默认）。
+    pub fn new(sessions_root: impl Into<PathBuf>) -> Self {
+        let platform = PlatformCtx::current();
+        Self {
+            sessions_root: sessions_root.into(),
+            home_dir: platform.home_dir.clone(),
+            platform,
+            process: ProcessConfig::default(),
+            launcher_name: "UnluckyLauncher".to_string(),
+            launcher_version: env!("CARGO_PKG_VERSION").to_string(),
+            scan_crash_reports: true,
+            max_crash_artifacts: 4,
+        }
+    }
+
+    /// 补启动器名/版本。
+    pub fn with_launcher(mut self, name: impl Into<String>, version: impl Into<String>) -> Self {
+        self.launcher_name = name.into();
+        self.launcher_version = version.into();
+        self
+    }
+}
+
+/// `--dry-run` 的输出（D18）：完整命令行，但**不 spawn、不写会话文件**。
+///
+/// 会做的事与真实启动**一致到「环境准备」为止**：natives 解压照做（幂等，`natives` 字段
+/// 回报结果），因为「装完能不能起」的一半答案就在「native 库有没有落地」上。
+#[derive(Debug, Clone)]
+pub struct DryRun {
+    /// 实际要执行的程序。
+    pub program: PathBuf,
+    /// 参数（已脱敏：accessToken 一定是 `<redacted:token>`）。
+    pub argv: Vec<String>,
+    /// 人读单行（可直接 `println!`，含空格的参数带引号）。
+    pub display: String,
+    /// 组装告警。
+    pub warnings: Vec<String>,
+    /// classpath 条目数。
+    pub classpath_entries: usize,
+    /// 日志解码编码。
+    pub encoding: String,
+    /// natives 解压结果（没有 natives 目录、即请求未配置时为 `None`）。
+    pub natives: Option<NativesReport>,
+}
+
+impl DryRun {
+    /// 一行命令行（D18 打印用）。
+    pub fn line(&self) -> &str {
+        &self.display
+    }
+}
+
+/// 启动器。
+#[derive(Clone)]
+pub struct Launcher {
+    config: LauncherConfig,
+    hook: Arc<dyn DiagnosisHook>,
+}
+
+impl std::fmt::Debug for Launcher {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("Launcher")
+            .field("config", &self.config)
+            .field("hook", &"<diagnosis hook>")
+            .finish()
+    }
+}
+
+impl Launcher {
+    /// 构造（无诊断挂钩）。
+    pub fn new(config: LauncherConfig) -> Self {
+        Self {
+            config,
+            hook: Arc::new(NoopDiagnosis),
+        }
+    }
+
+    /// 接上诊断挂钩（M15 适配器）。
+    pub fn with_diagnosis_hook(mut self, hook: Arc<dyn DiagnosisHook>) -> Self {
+        self.hook = hook;
+        self
+    }
+
+    /// 配置。
+    pub fn config(&self) -> &LauncherConfig {
+        &self.config
+    }
+
+    /// 只组装命令行（纯计算，可单测/可透传）。
+    pub fn plan(&self, request: &LaunchRequest) -> Result<AssembledCommand> {
+        assemble(request, &self.config.platform)
+    }
+
+    /// 环境准备（管线第 6 段）：natives 解压。
+    ///
+    /// 目标目录取 `request.dirs.natives_dir`（与 `${natives_directory}` 同一真相源）；
+    /// 目录为空视为调用方不需要，返回 `Ok(None)`。
+    fn prepare_environment(&self, request: &LaunchRequest) -> Result<Option<NativesReport>> {
+        if request.dirs.natives_dir.as_os_str().is_empty() {
+            return Ok(None);
+        }
+        natives::extract(&request.dirs.natives_dir, &request.natives)
+            .map(Some)
+            .map_err(|err| AssemblyError::NativesExtraction {
+                message: err.message(),
+            })
+            .map_err(Into::into)
+    }
+
+    /// D18：组装完整命令行并返回，**不 spawn 进程、不写会话文件**。
+    ///
+    /// 供 `unlucky-launcher --dry-run <instance>` 打印一行命令行后退出；
+    /// accessToken 已脱敏（绝不把凭据打到终端/日志里）。
+    pub fn dry_run(&self, request: &LaunchRequest) -> Result<DryRun> {
+        let natives = self.prepare_environment(request)?;
+        let command = self.plan(request)?;
+        let redactor = self.redactor(request);
+        let warnings = command
+            .warnings
+            .iter()
+            .map(ToString::to_string)
+            .collect::<Vec<_>>();
+        Ok(DryRun {
+            program: command.program.clone(),
+            argv: redactor.scrub_all(&command.argv()),
+            display: redactor.scrub(&command.display()).into_owned(),
+            warnings,
+            classpath_entries: command.classpath.len(),
+            encoding: command.encoding.clone(),
+            natives,
+        })
+    }
+
+    /// 启动一局并返回会话（可中途 [`LaunchSession::stop`]）。
+    pub fn spawn(&self, request: &LaunchRequest) -> Result<LaunchSession> {
+        let redactor = self.redactor(request);
+        let meta = self.session_meta(request);
+        let mut writer = SessionWriter::create(&self.config.sessions_root, meta, redactor.clone())?;
+        let session_id = writer.session_id().to_string();
+        let log_path = writer.path().to_path_buf();
+        writer.session_start()?;
+
+        // 阶段 6「环境准备」：natives 必须落到 java.library.path 指向的目录，且在组装前完成
+        // （HMCL 同序），失败即启动前失败——native 库缺了游戏只会给 UnsatisfiedLinkError。
+        let natives = match self.prepare_environment(request) {
+            Ok(report) => report,
+            Err(err) => {
+                let _ = writer.assembly_failed(&launch_error_assembly(&err));
+                let _ = writer.finish(EndReason::AssemblyFailed);
+                return Err(err);
+            }
+        };
+        if let Some(report) = &natives {
+            writer.natives_extracted(report)?;
+        }
+
+        let command = match self.plan(request) {
+            Ok(command) => command,
+            Err(err) => {
+                // 启动前失败也要留下证据：assembly_failed + session_end + 索引。
+                let _ = writer.assembly_failed(&launch_error_assembly(&err));
+                let _ = writer.finish(EndReason::AssemblyFailed);
+                return Err(err);
+            }
+        };
+        writer.cmd_built(&command)?;
+
+        let sink = Arc::new(SessionSink::with_start(writer, Instant::now()));
+        let working_dir = if request.dirs.game_dir.as_os_str().is_empty() {
+            None
+        } else {
+            Some(request.dirs.game_dir.as_path())
+        };
+        let process =
+            match RunningProcess::spawn(&command, working_dir, sink.clone(), self.config.process) {
+                Ok(process) => process,
+                Err(err) => {
+                    let _ = sink.with_writer(|writer| writer.finish(EndReason::SpawnFailed));
+                    return Err(err);
+                }
+            };
+        let pid = process.pid();
+        if let Some(result) = sink.with_writer(|writer| writer.proc_start(pid)) {
+            result?;
+        }
+        Ok(LaunchSession::new(
+            self.config.clone(),
+            self.hook.clone(),
+            redactor,
+            request.clone(),
+            session_id,
+            log_path,
+            command,
+            pid,
+            process,
+            sink,
+        ))
+    }
+
+    /// 启动并阻塞到进程结束（P0 主入口）。
+    pub fn launch(&self, request: &LaunchRequest) -> Result<SessionHandle> {
+        self.spawn(request)?.finish()
+    }
+
+    fn redactor(&self, request: &LaunchRequest) -> Redactor {
+        let mut redactor = Redactor::new().with_secret(request.auth.access_token.clone());
+        if let Some(home) = &self.config.home_dir {
+            redactor = redactor.with_home(home);
+        }
+        if !request.auth.uuid.is_empty() {
+            redactor = redactor.with_secret(request.auth.uuid.clone());
+        }
+        redactor
+    }
+
+    fn session_meta(&self, request: &LaunchRequest) -> SessionMeta {
+        let launcher_name = if request.launcher.name.is_empty() {
+            self.config.launcher_name.clone()
+        } else {
+            request.launcher.name.clone()
+        };
+        let launcher_version = if request.launcher.version.is_empty() {
+            self.config.launcher_version.clone()
+        } else {
+            request.launcher.version.clone()
+        };
+        SessionMeta::new(
+            request.instance.id.clone(),
+            request.instance.name.clone(),
+            request.instance.version.raw().to_string(),
+        )
+        .with_launcher(launcher_name, launcher_version)
+        .with_platform(&self.config.platform)
+    }
+}
+
+/// 把错误拆成 `assembly_failed` 事件需要的结构化原因。
+pub(crate) fn launch_error_assembly(
+    error: &crate::launch::error::LaunchError,
+) -> crate::launch::error::AssemblyError {
+    match error {
+        crate::launch::error::LaunchError::Assembly(assembly) => assembly.clone(),
+        other => crate::launch::error::AssemblyError::MalformedArgument {
+            entry: other.to_string(),
+            reason: "非组装类失败",
+        },
+    }
+}
diff --git a/crates/core/src/launch/log_level.rs b/crates/core/src/launch/log_level.rs
new file mode 100644
index 0000000..5fa1a95
--- /dev/null
+++ b/crates/core/src/launch/log_level.rs
@@ -0,0 +1,114 @@
+//! 日志级别猜测与“关键行”判定。
+//!
+//! 平移自 `analyse/02` §6.4（`Log4jLevel.guessLevel`）：先认 log4j 注入的
+//! `[HH:mm:ss] [thread/LEVEL]` 格式，再退到 JUL 的 `[INFO]` 形态；`stderr` 一律当
+//! ERROR（`[authlib-injector]` 例外）。
+//!
+//! 目的有两个：给事件流打 `level`，以及让环形缓冲能“关键行永久保留”
+//! （`analyse/02` §7.10-3：2000 行截断会把根因行挤掉）。
+
+/// 日志级别（认知顺序：Error 最严重）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub enum Level {
+    /// 错误。
+    Error,
+    /// 警告。
+    Warn,
+    /// 信息。
+    Info,
+    /// 调试。
+    Debug,
+    /// 无法判断。
+    Unknown,
+}
+
+impl Level {
+    /// 事件流里用的字符串形式。
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Error => "error",
+            Self::Warn => "warn",
+            Self::Info => "info",
+            Self::Debug => "debug",
+            Self::Unknown => "unknown",
+        }
+    }
+
+    /// 是否错误级（退出分析筛行用）。
+    pub fn is_error(self) -> bool {
+        self == Self::Error
+    }
+}
+
+/// 猜测一行日志的级别。
+pub fn guess(is_stderr: bool, line: &str) -> Level {
+    let trimmed = line.trim_start();
+    if is_stderr {
+        // authlib-injector 往 stderr 打的都是正常信息（`analyse/02` §6.4）。
+        if trimmed.starts_with("[authlib-injector]") {
+            return Level::Info;
+        }
+        return Level::Error;
+    }
+    if let Some(level) = log4j_level(trimmed) {
+        return level;
+    }
+    jul_level(trimmed).unwrap_or(Level::Unknown)
+}
+
+/// 是否“关键行”：命中这些特征的行不随环形淘汰（`Exception|Error|Caused by|OutOfMemory`）。
+pub fn is_key_line(line: &str) -> bool {
+    let lower = line.to_ascii_lowercase();
+    lower.contains("exception")
+        || lower.contains("error")
+        || lower.contains("caused by")
+        || lower.contains("outofmemory")
+        || lower.contains("fatal")
+}
+
+/// 从 `[12:34:56] [Render thread/INFO]: ...` 里取级别。
+///
+/// 逐段扫描方括号内容，取第一段形如 `<线程名>/<LEVEL>` 的级别，最多看 3 段。
+fn log4j_level(line: &str) -> Option<Level> {
+    let mut rest = line;
+    for _ in 0..3 {
+        let open = rest.find('[')?;
+        let tail = &rest[open + 1..];
+        let close = tail.find(']')?;
+        let segment = &tail[..close];
+        if let Some(slash) = segment.rfind('/') {
+            if let Some(level) = level_from_name(&segment[slash + 1..]) {
+                return Some(level);
+            }
+        }
+        rest = &tail[close + 1..];
+    }
+    None
+}
+
+fn level_from_name(name: &str) -> Option<Level> {
+    match name.trim() {
+        "ERROR" | "FATAL" => Some(Level::Error),
+        "WARN" | "WARNING" => Some(Level::Warn),
+        "INFO" | "NOTICE" => Some(Level::Info),
+        "DEBUG" | "TRACE" | "FINE" | "FINER" | "FINEST" => Some(Level::Debug),
+        _ => None,
+    }
+}
+
+/// JUL/裸标记形态：`[INFO]`、`[SEVERE]`、`[WARNING]`。
+fn jul_level(line: &str) -> Option<Level> {
+    const MARKERS: &[(&str, Level)] = &[
+        ("[SEVERE]", Level::Error),
+        ("[ERROR]", Level::Error),
+        ("[WARNING]", Level::Warn),
+        ("[WARN]", Level::Warn),
+        ("[INFO]", Level::Info),
+        ("[DEBUG]", Level::Debug),
+        ("[FINE]", Level::Debug),
+    ];
+    MARKERS
+        .iter()
+        .find(|(marker, _)| line.starts_with(marker))
+        .map(|(_, level)| *level)
+}
diff --git a/crates/core/src/launch/mod.rs b/crates/core/src/launch/mod.rs
new file mode 100644
index 0000000..02db942
--- /dev/null
+++ b/crates/core/src/launch/mod.rs
@@ -0,0 +1,75 @@
+//! 启动管线：10 阶段命令行组装、Java 选择、子进程管理、结构化 JSONL 事件流。
+//!
+//! 设计定稿：`DevDocs/PlanDoc/06-launch-and-diagnostics.md` §1（管线）与 §3（事件流），
+//! Java 侧约束见 `DevDocs/PlanDoc/01d-language-choice.md` §3（JDK 17 基准 + 版本映射提示）。
+//!
+//! 事件流是 core → app 的唯一启动反馈通道（另一条是快照发布），
+//! 不做 200ms 批量刷 UI 式的隐式耦合。
+//!
+//! # 公共面
+//!
+//! - [`Launcher`]：`dry_run`（D18，只组装命令行）、`spawn`/`launch`（完整管线）；
+//! - [`LaunchRequest`] 是命令行组装的**纯数据输入**，由 [`adapter`] 从 game 快照映射而来；
+//! - [`AssembledCommand`] 是组装结果（program + argv + classpath + 环境变量 + 告警）；
+//! - 事件流（[`session`]）与索引（[`session_index`]）是 M15 诊断采集器与
+//!   M16 `read_game_log`/`list_game_sessions` 的数据源，schema 见
+//!   `DevDocs/SubAgentsTalk/launch-接口约定.md`；
+//! - [`DiagnosisHook`] 是接 M15 的唯一接缝（launch 报事实、M15 下结论）。
+//!
+//! # 与 HMCL 的三处差异（`analyse/02` §8.5）
+//!
+//! 1. `exit 0` 静默失败单独立标（[`exit_analysis`]）；
+//! 2. 日志泵 join 有预算（[`watchdog`]），进程树三段式回收（[`tree_kill`]，P1 换 Job Object）；
+//! 3. 窗口出现检测带启发式名称/耗时/证据（[`window_detect`]）。
+//!
+//! 零 UI 依赖：本模块只产出结构化事件与纯数据，不 import 任何 UI 类型。
+
+pub mod adapter;
+pub mod args_table;
+pub mod argument;
+pub mod command_builder;
+pub mod crash_scan;
+pub mod defaults;
+pub mod diagnosis_hook;
+pub mod error;
+pub mod exit_analysis;
+pub mod game_args;
+pub mod game_version;
+pub mod jvm_args;
+pub mod launch_session;
+pub mod launcher;
+pub mod log_level;
+pub mod natives;
+pub mod placeholders;
+pub mod platform;
+pub mod process;
+pub mod pump;
+pub mod redact;
+pub mod request;
+pub mod session;
+pub mod session_index;
+pub mod session_meta;
+pub mod session_payload;
+pub mod session_sink;
+pub mod sink;
+pub mod time;
+pub mod tree_kill;
+pub mod watchdog;
+pub mod window_detect;
+
+pub use adapter::{
+    build_request, AdapterOptions, AdapterOutput, AdapterWarning, LibraryInput, SnapshotInput,
+};
+pub use args_table::{assemble, AssembledCommand, AssemblyWarning};
+pub use crash_scan::{CrashArtifact, CrashSource};
+pub use diagnosis_hook::{DiagnosisHook, DiagnosisRequest, NoopDiagnosis};
+pub use error::{LaunchError, MissingComponent, Result};
+pub use exit_analysis::{ExitAnalysis, ExitType, SilentFailure};
+pub use launch_session::{LaunchSession, SessionHandle};
+pub use launcher::{DryRun, Launcher, LauncherConfig};
+pub use natives::{NativeJar, NativesEra, NativesPlan, NativesReport};
+pub use process::{ProcessConfig, RunningProcess};
+pub use request::LaunchRequest;
+pub use session::{EndReason, SessionMeta, SessionSink, SessionWriter};
+pub use session_index::SessionIndexEntry;
+pub use sink::{CompositeSink, CountingSink, FnSink};
diff --git a/crates/core/src/launch/natives/jar.rs b/crates/core/src/launch/natives/jar.rs
new file mode 100644
index 0000000..5e8c559
--- /dev/null
+++ b/crates/core/src/launch/natives/jar.rs
@@ -0,0 +1,250 @@
+//! natives jar 的读取细节：zip 遍历、条目筛选、目录清理、戳记读写。
+//!
+//! 与 [`super`] 的分工：`super` 管「计划与报告」，这里管「怎么把一个 jar 里的原生库落到盘上」。
+
+use std::fs::{self, File};
+use std::io;
+use std::path::{Path, PathBuf};
+use std::time::UNIX_EPOCH;
+
+use serde::{Deserialize, Serialize};
+use zip::ZipArchive;
+
+use super::{NativeJar, NativesError, NativesReport, STAMP_FILE};
+
+/// 戳记 schema 版本（改字段语义才升）。
+const STAMP_VERSION: u8 = 1;
+
+/// 内置排除前缀：Mojang 清单惯例，manifest 没写 `extract` 规则时也这么办。
+const DEFAULT_EXCLUDES: &[&str] = &["META-INF/"];
+
+/// 原生库扩展名白名单（Windows / Linux / macOS；`jnilib` 是 JDK6 时代的老 mac 后缀）。
+const NATIVE_EXTENSIONS: &[&str] = &["dll", "so", "dylib", "jnilib"];
+
+/// 签名 / 校验附属文件扩展名：即使在 natives jar 根目录也绝不落地。
+const SIGNATURE_EXTENSIONS: &[&str] = &["sf", "rsa", "dsa", "ec", "asc", "sha1", "sha256", "git"];
+
+/// 戳记的一条：源 jar 的「路径 + 字节数 + mtime」指纹。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub(crate) struct JarStamp {
+    /// 源 jar 绝对路径（同一目录换了别的版本时必须能区分开）。
+    pub path: String,
+    /// 字节数。
+    pub len: u64,
+    /// 修改时间（Unix 毫秒；读不到时 0，等价于「每次都当它变了」）。
+    pub mtime_ms: u64,
+}
+
+/// 目录戳记文件内容。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub(crate) struct Stamp {
+    v: u8,
+    files: usize,
+    jars: Vec<JarStamp>,
+}
+
+impl Stamp {
+    /// 戳记是否仍然对应当前的 jar 集（版本 + 指纹逐一相等）。
+    pub(crate) fn matches(&self, stamps: &[JarStamp]) -> bool {
+        self.v == STAMP_VERSION && self.jars == stamps
+    }
+
+    /// 上次解压的文件数。
+    pub(crate) fn files(&self) -> usize {
+        self.files
+    }
+}
+
+/// 构造 `NativesError::Io`。
+pub(crate) fn io_error(
+    op: &'static str,
+    path: impl Into<PathBuf>,
+    source: io::Error,
+) -> NativesError {
+    NativesError::Io {
+        op,
+        path: path.into(),
+        source,
+    }
+}
+
+/// 解压单个 jar：排除前缀 → 原生库白名单 → zip-slip 防护 → 落盘。
+pub(crate) fn extract_jar(
+    native: &NativeJar,
+    dir: &Path,
+    report: &mut NativesReport,
+) -> Result<(), NativesError> {
+    let file = File::open(&native.path)
+        .map_err(|source| io_error("open_native_jar", &native.path, source))?;
+    let mut archive = ZipArchive::new(file).map_err(|err| NativesError::Zip {
+        path: native.path.clone(),
+        reason: err.to_string(),
+    })?;
+    let excludes: Vec<&str> = DEFAULT_EXCLUDES
+        .iter()
+        .copied()
+        .chain(native.exclude.iter().map(String::as_str))
+        .collect();
+
+    for index in 0..archive.len() {
+        let mut entry = archive.by_index(index).map_err(|err| NativesError::Zip {
+            path: native.path.clone(),
+            reason: err.to_string(),
+        })?;
+        if entry.is_dir() {
+            continue;
+        }
+        // `enclosed_name` 拒绝 `..` / 绝对路径条目（zip-slip）。
+        let Some(relative) = entry.enclosed_name() else {
+            report.ignored += 1;
+            continue;
+        };
+        let name = relative.to_string_lossy().replace('\\', "/");
+        if !should_extract(&name, &excludes) {
+            report.ignored += 1;
+            continue;
+        }
+        let dest = dir.join(&relative);
+        if let Some(parent) = dest.parent() {
+            fs::create_dir_all(parent)
+                .map_err(|source| io_error("create_natives_subdir", parent, source))?;
+        }
+        let mut out =
+            File::create(&dest).map_err(|source| io_error("create_native_file", &dest, source))?;
+        io::copy(&mut entry, &mut out)
+            .map_err(|source| io_error("write_native_file", &dest, source))?;
+        report.files += 1;
+    }
+    Ok(())
+}
+
+/// 该条目要不要解压：排除前缀命中、签名文件、非原生库扩展名 → 跳过。
+pub(crate) fn should_extract(name: &str, excludes: &[&str]) -> bool {
+    if excludes.iter().any(|prefix| name.starts_with(prefix)) {
+        return false;
+    }
+    let lower = name.to_ascii_lowercase();
+    let extension = lower.rsplit_once('.').map(|(_, ext)| ext).unwrap_or("");
+    if SIGNATURE_EXTENSIONS.contains(&extension) {
+        return false;
+    }
+    NATIVE_EXTENSIONS.contains(&extension)
+}
+
+/// 清掉目录里已有的原生库与戳记（尽力而为：删不掉的留着，后面覆盖写会报错）。
+pub(crate) fn clear_natives(dir: &Path) {
+    let Ok(entries) = fs::read_dir(dir) else {
+        return;
+    };
+    for entry in entries.flatten() {
+        let path = entry.path();
+        if path.is_dir() {
+            continue;
+        }
+        let name = path
+            .file_name()
+            .map(|name| name.to_string_lossy().to_ascii_lowercase())
+            .unwrap_or_default();
+        if name == STAMP_FILE {
+            let _ = fs::remove_file(&path);
+            continue;
+        }
+        let is_native = name
+            .rsplit_once('.')
+            .map(|(_, ext)| NATIVE_EXTENSIONS.contains(&ext))
+            .unwrap_or(false);
+        if is_native {
+            let _ = fs::remove_file(&path);
+        }
+    }
+}
+
+/// 源 jar 指纹（路径 + 字节数 + mtime）。
+pub(crate) fn jar_stamps(jars: &[NativeJar]) -> Vec<JarStamp> {
+    jars.iter()
+        .map(|native| {
+            let metadata = fs::metadata(&native.path);
+            let len = metadata.as_ref().map(|meta| meta.len()).unwrap_or(0);
+            let mtime_ms = metadata
+                .ok()
+                .and_then(|meta| meta.modified().ok())
+                .and_then(|time| time.duration_since(UNIX_EPOCH).ok())
+                .map(|elapsed| elapsed.as_millis() as u64)
+                .unwrap_or(0);
+            JarStamp {
+                path: native.path.display().to_string(),
+                len,
+                mtime_ms,
+            }
+        })
+        .collect()
+}
+
+/// 读戳记（不存在 / 损坏 / 版本不符都当作「没有戳记」）。
+pub(crate) fn read_stamp(dir: &Path) -> Option<Stamp> {
+    let text = fs::read_to_string(dir.join(STAMP_FILE)).ok()?;
+    let stamp: Stamp = serde_json::from_str(&text).ok()?;
+    if stamp.v == STAMP_VERSION {
+        Some(stamp)
+    } else {
+        None
+    }
+}
+
+/// 写戳记（直接覆盖写：半截文件下次解析失败即视为「没有戳记」，重解一遍就行）。
+pub(crate) fn write_stamp(dir: &Path, files: usize, jars: &[JarStamp]) -> Result<(), NativesError> {
+    let path = dir.join(STAMP_FILE);
+    let stamp = Stamp {
+        v: STAMP_VERSION,
+        files,
+        jars: jars.to_vec(),
+    };
+    let text = serde_json::to_string_pretty(&stamp).map_err(|err| NativesError::Zip {
+        path: path.clone(),
+        reason: err.to_string(),
+    })?;
+    fs::write(&path, text).map_err(|source| io_error("write_natives_stamp", &path, source))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{should_extract, DEFAULT_EXCLUDES};
+
+    #[test]
+    fn native_library_extensions_pass() {
+        for name in [
+            "lwjgl.dll",
+            "OpenAL.dll",
+            "liblwjgl.so",
+            "liblwjgl.dylib",
+            "liblwjgl.jnilib",
+        ] {
+            assert!(should_extract(name, DEFAULT_EXCLUDES), "{name} 应解压");
+        }
+    }
+
+    #[test]
+    fn metadata_and_signature_entries_are_skipped() {
+        for name in [
+            "META-INF/MANIFEST.MF",
+            "META-INF/FOO.SF",
+            "META-INF/FOO.RSA",
+            "lwjgl.dll.sha1",
+            "lwjgl.dll.sha256",
+            "README.txt",
+            "LICENSE",
+            // 无扩展名的文件一律不进 java.library.path。
+            "lwjgl",
+        ] {
+            assert!(!should_extract(name, DEFAULT_EXCLUDES), "{name} 不该解压");
+        }
+    }
+
+    #[test]
+    fn manifest_exclude_prefixes_apply_on_top_of_builtin() {
+        assert!(!should_extract("extra/x.dll", &["extra/"]));
+        assert!(should_extract("x.dll", &["extra/"]));
+        // 大小写不敏感只对扩展名生效（排除前缀按清单原样比较，与 HMCL 一致）。
+        assert!(should_extract("X.DLL", DEFAULT_EXCLUDES));
+    }
+}
diff --git a/crates/core/src/launch/natives/mod.rs b/crates/core/src/launch/natives/mod.rs
new file mode 100644
index 0000000..a57e83c
--- /dev/null
+++ b/crates/core/src/launch/natives/mod.rs
@@ -0,0 +1,355 @@
+//! natives 解压：把版本链里的 natives 分类器构件解到 `versions/<id>/natives/`。
+//!
+//! 这是 10 阶段管线里**第 6 段「环境准备」**的落盘部分（`PlanDoc/06` §1），发生顺序在
+//! 命令行组装之前（HMCL 也在组装期做：`DefaultLauncher.decompressNatives`，
+//! `analyse/03` §6.4-(7)），因此 `--dry-run` 也能验证「装完到底能不能起」。
+//!
+//! # 三个时代（`SubAgentsTalk/launch-natives-解压与时代分界.md`，piston-meta 实测）
+//!
+//! | 版本区间 | natives 形态 | 谁负责 `-Djava.library.path` |
+//! |---|---|---|
+//! | ≤1.12.2（LWJGL 2.9） | `natives` 表 + `downloads.classifiers` | 启动器补（`defaults::legacy_jvm_arguments`） |
+//! | 1.13–1.18.2（LWJGL 3.1/3.2） | 同上（另有同坐标的主构件条目） | 清单自己写 `arguments.jvm` |
+//! | 1.19+（LWJGL 3.3） | **没有 `natives` 表**：natives jar 是普通 classpath 库 | 清单写 4 个目录属性，LWJGL 运行期自解压 |
+//!
+//! 所以三个时代走**同一条代码路径**：有 jar 就解压，没 jar 就只把目录建出来
+//! （1.19+ 的 `-Dorg.lwjgl.system.SharedLibraryExtractPath` 指向它；目录不存在时
+//! LWJGL 会静默走到「找不到 native」）。
+//!
+//! # 幂等
+//!
+//! 解压完在目录里写一份戳记 [`jar::STAMP_FILE`]（每个源 jar 的路径 + 字节数 + mtime）。
+//! 下次启动：戳记与当前 jar 集完全一致 → 目录视为就绪，**不读 jar、不写盘**直接跳过；
+//! 不一致（换版本 / 库升级 / 用户删了目录）→ 清掉旧原生库再全量解压，避免两代 dll
+//! 混在同一个 `java.library.path` 里（HMCL 也是每次清目录，这里只把「没变就不动」补上）。
+
+pub(crate) mod jar;
+
+use std::path::{Path, PathBuf};
+
+use crate::game::arguments::Environment;
+use crate::game::layout::GameLayout;
+use crate::game::library::Library;
+use crate::launch::natives::jar::{
+    clear_natives, extract_jar, jar_stamps, read_stamp, write_stamp,
+};
+
+/// 戳记文件名：放在 natives 目录里，跟着目录一起删 / 建。
+///
+/// 公开出来是为了「一键修复」类功能能认出自己的痕迹（判断目录里哪些文件是我们解出来的）。
+pub const STAMP_FILE: &str = ".ull-natives.json";
+
+/// 一个待解压的 natives 构件（版本链里 `natives` 分类器命中的 jar）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct NativeJar {
+    /// 磁盘路径（`libraries/<group>/.../<artifact>-<ver>-natives-<os>.jar`）。
+    pub path: PathBuf,
+    /// 坐标 + 分类器（`org.lwjgl:lwjgl:3.2.2:natives-windows`，报错与事件里用）。
+    pub name: String,
+    /// 清单 `extract.exclude` 的排除前缀（`["META-INF/"]`）。
+    pub exclude: Vec<String>,
+}
+
+impl NativeJar {
+    /// 构造（无排除规则）。
+    pub fn new(path: impl Into<PathBuf>, name: impl Into<String>) -> Self {
+        Self {
+            path: path.into(),
+            name: name.into(),
+            exclude: Vec::new(),
+        }
+    }
+
+    /// 带清单排除规则构造。
+    pub fn with_exclude(
+        path: impl Into<PathBuf>,
+        name: impl Into<String>,
+        exclude: Vec<String>,
+    ) -> Self {
+        Self {
+            path: path.into(),
+            name: name.into(),
+            exclude,
+        }
+    }
+}
+
+/// natives 处理的时代（决定「要不要解压」以及「`-Djava.library.path` 从哪来」）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum NativesEra {
+    /// ≤1.12.2：清单没有 `arguments.jvm`，启动器自己补 `-Djava.library.path`。
+    #[default]
+    Legacy,
+    /// 1.13–1.18.2：清单有 `arguments.jvm`，natives 走分类器 jar（需要解压）。
+    Lwjgl3,
+    /// 1.19+：natives jar 是普通 classpath 库，LWJGL 3.3 运行期自解压（只需目录存在）。
+    ClasspathNative,
+}
+
+impl NativesEra {
+    /// 按「清单有没有 `arguments.jvm`」+「有没有 natives 分类器 jar」判时代。
+    pub fn detect(manifest_jvm_args: usize, natives_jars: usize) -> Self {
+        if manifest_jvm_args == 0 {
+            Self::Legacy
+        } else if natives_jars == 0 {
+            Self::ClasspathNative
+        } else {
+            Self::Lwjgl3
+        }
+    }
+
+    /// 事件/日志里的稳定字符串。
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Legacy => "legacy",
+            Self::Lwjgl3 => "lwjgl3",
+            Self::ClasspathNative => "classpath_native",
+        }
+    }
+}
+
+/// 解压计划（`LaunchRequest` 的一部分，纯数据）。
+///
+/// 目标目录**不在**这里：唯一真相源是 `LaunchDirs::natives_dir`（`${natives_directory}` 也用它），
+/// 免得出现「参数指向 A、dll 解到 B」的静默错位。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct NativesPlan {
+    /// 待解压的 natives 分类器构件。
+    pub jars: Vec<NativeJar>,
+    /// 时代（只影响报告字段；解压路径三时代统一）。
+    pub era: NativesEra,
+    /// 目录是否用户自定义（事件 payload 的 `custom` 字段，给「自备 dll 被覆盖」留证据）。
+    pub custom: bool,
+}
+
+impl Default for NativesPlan {
+    fn default() -> Self {
+        Self {
+            jars: Vec::new(),
+            era: NativesEra::ClasspathNative,
+            custom: false,
+        }
+    }
+}
+
+impl NativesPlan {
+    /// 以 jar 清单构造：有 jar 按 [`NativesEra::Lwjgl3`]，没有按 [`NativesEra::ClasspathNative`]。
+    ///
+    /// 这一层分不出「≤1.12.2 的 LWJGL 2」与「1.13–1.18.2 的 LWJGL 3」（两者都有分类器 jar），
+    /// 所以适配层用 [`NativesPlan::with_era`] 明确给值；直接构造只适合测试与脚本。
+    pub fn new(jars: Vec<NativeJar>) -> Self {
+        let era = NativesEra::detect(usize::from(!jars.is_empty()), jars.len());
+        Self {
+            jars,
+            era,
+            custom: false,
+        }
+    }
+
+    /// 指定时代。
+    pub fn with_era(mut self, era: NativesEra) -> Self {
+        self.era = era;
+        self
+    }
+
+    /// 标记目录为用户自定义。
+    pub fn with_custom(mut self, custom: bool) -> Self {
+        self.custom = custom;
+        self
+    }
+
+    /// 没有任何 natives 构件（1.19+ 的常态）。
+    pub fn is_empty(&self) -> bool {
+        self.jars.is_empty()
+    }
+}
+
+/// 解压结果（进 `natives_extracted` 事件与 `--dry-run` 输出）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct NativesReport {
+    /// 目标目录。
+    pub dir: PathBuf,
+    /// 时代。
+    pub era: NativesEra,
+    /// 参与的 jar 数。
+    pub jars: usize,
+    /// 本次写盘的原生库文件数。
+    pub files: usize,
+    /// 按戳记跳过、未重新解压的文件数（= 上次解压的文件数）。
+    pub skipped: usize,
+    /// 被排除 / 非原生库而忽略的条目数（`META-INF/`、签名文件）。
+    pub ignored: usize,
+    /// 目录是否用户自定义。
+    pub custom: bool,
+    /// 是否按戳记判定「目录已就绪」而整体跳过。
+    pub up_to_date: bool,
+}
+
+impl NativesReport {
+    /// 人读一行（CLI / 日志用）。
+    pub fn summary(&self) -> String {
+        if self.jars == 0 {
+            return format!(
+                "natives 目录已就绪（该版本无需解压，LWJGL 运行期自取）→ {}",
+                self.dir.display()
+            );
+        }
+        if self.up_to_date {
+            return format!(
+                "natives 已就绪（{} 个原生库，{} 个 jar 未变）",
+                self.skipped, self.jars
+            );
+        }
+        format!(
+            "natives 解压 {} 个原生库（{} 个 jar，忽略 {} 个条目）→ {}",
+            self.files,
+            self.jars,
+            self.ignored,
+            self.dir.display()
+        )
+    }
+}
+
+/// 解压失败原因。
+#[derive(Debug)]
+pub enum NativesError {
+    /// 目标目录为空（调用方漏填 `natives_dir`）。
+    NoDir,
+    /// 文件系统操作失败。
+    Io {
+        /// 操作名。
+        op: &'static str,
+        /// 相关路径。
+        path: PathBuf,
+        /// 底层错误。
+        source: std::io::Error,
+    },
+    /// natives jar 打不开 / 不是合法 zip（下载损坏的最常见形态）。
+    Zip {
+        /// jar 路径。
+        path: PathBuf,
+        /// 原因。
+        reason: String,
+    },
+}
+
+impl NativesError {
+    /// 一行人读描述。
+    pub fn message(&self) -> String {
+        match self {
+            Self::NoDir => "natives 目录未配置（natives_dir 为空）".to_string(),
+            Self::Io { op, path, source } => {
+                format!("{op} 失败（{}）：{source}", path.display())
+            }
+            Self::Zip { path, reason } => {
+                format!(
+                    "natives jar 无法作为 zip 打开（{}）：{reason}",
+                    path.display()
+                )
+            }
+        }
+    }
+}
+
+impl std::fmt::Display for NativesError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(&self.message())
+    }
+}
+
+impl std::error::Error for NativesError {}
+
+/// 从版本链库表收集 natives 分类器构件（adapter / app / CLI 共用这一段，别各写一份）。
+///
+/// 口径与安装层 `game::install::libraries::plan` **除 `hint=local` 落点外**逐条对齐：
+/// 1. 先按环境过滤（`Library::applies`）；
+/// 2. `natives` 表命中当前 OS 才取分类器（1.19+ 没有 `natives` 表 → 返回空表）；
+/// 3. 落点优先用清单 `downloads.classifiers.<classifier>.path`，缺了才按 Maven 坐标推导
+///    （`Library::native_relative_path`）；`hint=local` 的库在实例私有目录里
+///    （`analyse/03` §6.8 的 HMCL 口径）。
+///
+/// ⚠️ 安装层当前的 natives 分类器分支硬编码共享 `libraries/`、不认 `hint=local`（主构件认），
+/// 所以「`hint=local` + `natives` 同体」的 manifest（只有 HMCL 补丁导入才会有）会出现
+/// 「装到共享目录、解压去实例目录」→ 由 [`crate::launch::adapter::AdapterWarning::MissingNativeJar`]
+/// 转成启动前 `missing_components` 显式失败。此处仍按 HMCL 权威口径实现，等 install 侧对齐。
+pub fn collect(
+    layout: &GameLayout,
+    version_id: &str,
+    libraries: &[Library],
+    environment: &Environment,
+) -> Vec<NativeJar> {
+    let mut natives = Vec::new();
+    for library in libraries {
+        if !library.applies(environment) {
+            continue;
+        }
+        let Some(classifier) = library.native_classifier(environment) else {
+            continue;
+        };
+        let Ok(relative) = library.native_relative_path(&classifier) else {
+            continue;
+        };
+        // 安装层当前对 natives 不做这条分支（见上方警告）；这里按 HMCL 口径落实例私有目录。
+        let base = if library.is_local() {
+            layout.version_libraries_dir(version_id)
+        } else {
+            layout.libraries_dir()
+        };
+        let exclude = library
+            .extract
+            .as_ref()
+            .map(|extract| extract.exclude.clone())
+            .unwrap_or_default();
+        natives.push(NativeJar::with_exclude(
+            base.join(relative),
+            format!("{}:{classifier}", library.name),
+            exclude,
+        ));
+    }
+    natives
+}
+
+/// 解压一个计划（幂等：目录与源 jar 都没变时零写盘）。
+///
+/// # Errors
+///
+/// 目录为空、建目录 / 写文件失败、jar 不是合法 zip 时返回 [`NativesError`]。
+pub fn extract(dir: &Path, plan: &NativesPlan) -> Result<NativesReport, NativesError> {
+    if dir.as_os_str().is_empty() {
+        return Err(NativesError::NoDir);
+    }
+    let mut report = NativesReport {
+        dir: dir.to_path_buf(),
+        era: plan.era,
+        jars: plan.jars.len(),
+        files: 0,
+        skipped: 0,
+        ignored: 0,
+        custom: plan.custom,
+        up_to_date: false,
+    };
+    // 1.19+ 没有 jar 也要建目录：LWJGL 3.3 往 SharedLibraryExtractPath 里解压。
+    std::fs::create_dir_all(dir)
+        .map_err(|source| jar::io_error("create_natives_dir", dir, source))?;
+    if plan.jars.is_empty() {
+        report.up_to_date = true;
+        return Ok(report);
+    }
+
+    let stamps = jar_stamps(&plan.jars);
+    if let Some(stamp) = read_stamp(dir) {
+        if stamp.matches(&stamps) {
+            report.up_to_date = true;
+            report.skipped = stamp.files();
+            return Ok(report);
+        }
+    }
+
+    // 源变了：先清旧原生库（避免两代 dll 混在同一个 java.library.path 里），再全量解。
+    clear_natives(dir);
+    for native in &plan.jars {
+        extract_jar(native, dir, &mut report)?;
+    }
+    write_stamp(dir, report.files, &stamps)?;
+    Ok(report)
+}
diff --git a/crates/core/src/launch/placeholders.rs b/crates/core/src/launch/placeholders.rs
new file mode 100644
index 0000000..b99f42b
--- /dev/null
+++ b/crates/core/src/launch/placeholders.rs
@@ -0,0 +1,173 @@
+//! 参数占位符字典与替换。
+//!
+//! 占位符清单平移自 `analyse/02` §4.8（`DefaultLauncher.getConfigurations()`）：
+//! 版本清单里的 `arguments.*` 用 `${...}` 引用运行时值，启动器负责在组装时替换。
+//! 替换语义与 HMCL 一致：**单遍、不递归**；未定义的占位符原样保留（便于发现清单漏项）。
+
+use std::collections::BTreeMap;
+use std::path::Path;
+
+use crate::launch::platform::PlatformCtx;
+use crate::launch::request::LaunchRequest;
+
+/// 我们支持的占位符键（不含 `${}` 包裹）。
+pub const PLACEHOLDER_KEYS: &[&str] = &[
+    "auth_player_name",
+    "auth_session",
+    "auth_access_token",
+    "auth_uuid",
+    "user_type",
+    "user_properties",
+    "version_name",
+    "version_type",
+    "profile_name",
+    "game_directory",
+    "assets_index_name",
+    "game_assets",
+    "assets_root",
+    "natives_directory",
+    "classpath",
+    "classpath_separator",
+    "launcher_name",
+    "launcher_version",
+    "library_directory",
+    "libraries_directory",
+    "primary_jar",
+    "primary_jar_name",
+    "file_separator",
+    "resolution_width",
+    "resolution_height",
+    "language",
+];
+
+/// 占位符表。
+#[derive(Debug, Clone, Default)]
+pub struct PlaceholderMap {
+    entries: BTreeMap<String, String>,
+}
+
+impl PlaceholderMap {
+    /// 空表。
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// 插入一个占位符（键不含 `${}`）。
+    pub fn insert(&mut self, key: &str, value: impl Into<String>) {
+        self.entries.insert(key.to_string(), value.into());
+    }
+
+    /// 查询。
+    pub fn get(&self, key: &str) -> Option<&str> {
+        self.entries.get(key).map(String::as_str)
+    }
+
+    /// 已登记的键数。
+    pub fn len(&self) -> usize {
+        self.entries.len()
+    }
+
+    /// 是否为空。
+    pub fn is_empty(&self) -> bool {
+        self.entries.is_empty()
+    }
+
+    /// 单遍替换 `${key}`；未定义键原样保留。
+    pub fn render(&self, template: &str) -> String {
+        if !template.contains("${") {
+            return template.to_string();
+        }
+        let mut out = String::with_capacity(template.len() + 16);
+        let mut rest = template;
+        while let Some(start) = rest.find("${") {
+            out.push_str(&rest[..start]);
+            let after = &rest[start + 2..];
+            match after.find('}') {
+                Some(end) => {
+                    let key = &after[..end];
+                    match self.entries.get(key) {
+                        Some(value) => out.push_str(value),
+                        None => {
+                            out.push_str("${");
+                            out.push_str(key);
+                            out.push('}');
+                        }
+                    }
+                    rest = &after[end + 1..];
+                }
+                None => {
+                    out.push_str(&rest[start..]);
+                    rest = "";
+                }
+            }
+        }
+        out.push_str(rest);
+        out
+    }
+
+    /// 由启动请求构造完整占位符表。
+    pub fn from_request(req: &LaunchRequest, ctx: &PlatformCtx) -> Self {
+        let mut map = Self::new();
+        let auth = &req.auth;
+        map.insert("auth_player_name", auth.player_name.clone());
+        map.insert("auth_session", auth.access_token.clone());
+        map.insert("auth_access_token", auth.access_token.clone());
+        map.insert("auth_uuid", auth.uuid.clone());
+        map.insert("user_type", auth.user_type.clone());
+        map.insert("user_properties", auth.user_properties.clone());
+
+        map.insert("version_name", req.instance.name.clone());
+        map.insert("version_type", req.instance.version_type.clone());
+        map.insert("profile_name", req.instance.id.clone());
+
+        let dirs = &req.dirs;
+        map.insert("game_directory", path_str(&dirs.game_dir));
+        map.insert("assets_index_name", dirs.assets_index.clone());
+        map.insert("game_assets", path_str(&dirs.game_assets));
+        map.insert("assets_root", path_str(&dirs.assets_root));
+        map.insert("natives_directory", path_str(&dirs.natives_dir));
+        map.insert(
+            "classpath",
+            join_classpath(&req.classpath, ctx.path_separator()),
+        );
+        map.insert("classpath_separator", ctx.path_separator().to_string());
+        map.insert("launcher_name", req.launcher.name.clone());
+        map.insert("launcher_version", req.launcher.version.clone());
+        map.insert("library_directory", path_str(&dirs.library_dir));
+        map.insert("libraries_directory", path_str(&dirs.library_dir));
+        map.insert("primary_jar", path_str(&dirs.primary_jar));
+        map.insert(
+            "primary_jar_name",
+            dirs.primary_jar
+                .file_name()
+                .map(|name| name.to_string_lossy().into_owned())
+                .unwrap_or_default(),
+        );
+        map.insert("file_separator", ctx.file_separator().to_string());
+        match &req.resolution {
+            Some(res) => {
+                map.insert("resolution_width", res.width.to_string());
+                map.insert("resolution_height", res.height.to_string());
+            }
+            None => {
+                map.insert("resolution_width", String::new());
+                map.insert("resolution_height", String::new());
+            }
+        }
+        map.insert("language", req.language.clone());
+        map
+    }
+}
+
+/// 按平台分隔符拼接 classpath。
+pub fn join_classpath(paths: &[std::path::PathBuf], separator: char) -> String {
+    paths
+        .iter()
+        .map(|path| path.display().to_string())
+        .collect::<Vec<_>>()
+        .join(&separator.to_string())
+}
+
+fn path_str(path: &Path) -> String {
+    path.display().to_string()
+}
diff --git a/crates/core/src/launch/platform.rs b/crates/core/src/launch/platform.rs
new file mode 100644
index 0000000..435b4a0
--- /dev/null
+++ b/crates/core/src/launch/platform.rs
@@ -0,0 +1,95 @@
+//! 平台上下文：命令行组装与进程管理需要知道的操作系统事实。
+//!
+//! 依据 `analyse/02` §4.1（Linux/macOS `nice`）、§4.4（原生编码）、§4.6（原生库路径）、
+//! §4.10（环境变量，`APPDATA` 重定向只在 Windows 有意义）。
+//!
+//! `os_version` 不再是空占位：`current()` 从 [`crate::platform::os_info`] 的运行期探测取值，
+//! 清单里带 `rules.os.version` 的参数项因此能真正命中（D19 · `PlanDoc/11-os-detection.md` §2）。
+
+use std::path::PathBuf;
+
+pub use crate::platform::os_info::OsFamily;
+
+/// 平台上下文。
+#[derive(Debug, Clone)]
+pub struct PlatformCtx {
+    /// 操作系统家族。
+    pub os: OsFamily,
+    /// `rules.os.arch` 用的架构名。
+    pub arch: String,
+    /// 系统原生编码（`-Dfile.encoding` 的默认值来源）。
+    pub native_charset: String,
+    /// 主目录（脱敏与 `-Duser.home` 用）。
+    pub home_dir: Option<PathBuf>,
+    /// 系统版本串（`rules.os.version` 用，例如 `10.0.19045`）。
+    pub os_version: String,
+}
+
+impl PlatformCtx {
+    /// 按当前编译目标推断，版本串取运行期真实探测值。
+    pub fn current() -> Self {
+        let info = crate::platform::os_info::current();
+        Self {
+            os: info.family,
+            arch: info.arch.clone(),
+            native_charset: native_charset().to_string(),
+            home_dir: home_dir(),
+            os_version: info.os_version().to_string(),
+        }
+    }
+
+    /// 测试用：显式指定系统与架构，版本串留空（规则求值走保守分支）。
+    pub fn new(os: OsFamily, arch: &str) -> Self {
+        Self {
+            os,
+            arch: arch.to_string(),
+            native_charset: native_charset().to_string(),
+            home_dir: None,
+            os_version: String::new(),
+        }
+    }
+
+    /// 显式指定版本串（测试与适配层注入用）。
+    pub fn with_os_version(mut self, version: impl Into<String>) -> Self {
+        self.os_version = version.into();
+        self
+    }
+
+    /// classpath 分隔符（Windows `;`，POSIX `:`）。
+    pub fn path_separator(&self) -> char {
+        if self.os == OsFamily::Windows {
+            ';'
+        } else {
+            ':'
+        }
+    }
+
+    /// 文件名分隔符的字符串形式（供 `${file_separator}` 占位符）。
+    pub fn file_separator(&self) -> &'static str {
+        if self.os == OsFamily::Windows {
+            "\\"
+        } else {
+            "/"
+        }
+    }
+}
+
+impl Default for PlatformCtx {
+    fn default() -> Self {
+        Self::current()
+    }
+}
+
+/// 系统原生编码名。
+///
+/// 中文 Windows 上系统编码是 GBK，但 Java 18+ 默认 UTF-8；这里统一给 `UTF-8`，
+/// 需要跟随系统时由用户在 `-Dfile.encoding=COMPAT` 语义下覆盖（`analyse/02` §4.4）。
+fn native_charset() -> &'static str {
+    "UTF-8"
+}
+
+fn home_dir() -> Option<PathBuf> {
+    std::env::var_os("USERPROFILE")
+        .or_else(|| std::env::var_os("HOME"))
+        .map(PathBuf::from)
+}
diff --git a/crates/core/src/launch/process.rs b/crates/core/src/launch/process.rs
new file mode 100644
index 0000000..79a9582
--- /dev/null
+++ b/crates/core/src/launch/process.rs
@@ -0,0 +1,231 @@
+//! 进程管理：spawn + stdout/stderr 泵 + 进程树回收。
+//!
+//! 对应 `analyse/02` §6 的四条线程模型（`stdout-pump` / `stderr-pump` / `exit-waiter`），
+//! 但线程生命周期的收尾由 [`crate::launch::watchdog`] 兜底，不无条件 `join`。
+//!
+//! 本模块只管“把命令行跑起来并收集输出”，不做组件检查、不做诊断——
+//! 那些是 `launch` 上层流水线（阶段B）与 M15 的职责。
+
+use std::path::{Path, PathBuf};
+use std::process::{Child, Command, ExitStatus, Stdio};
+use std::sync::{Arc, Mutex};
+use std::time::{Duration, Instant};
+
+use crate::launch::args_table::AssembledCommand;
+use crate::launch::error::{LaunchError, Result};
+use crate::launch::pump::{LineSink, LogLine, PumpGroup, RingBuffer, RingBufferConfig};
+use crate::launch::tree_kill;
+use crate::launch::watchdog::{self, PumpVerdict, WatchdogConfig};
+
+/// 强制结束后等进程消失的预算。
+const FORCE_KILL_BUDGET: Duration = Duration::from_secs(5);
+/// 轮询进程状态的间隔。
+const POLL_INTERVAL: Duration = Duration::from_millis(20);
+
+/// 进程管理配置。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ProcessConfig {
+    /// 日志泵等待预算。
+    pub watchdog: WatchdogConfig,
+    /// 停止时温和关闭的宽限期。
+    pub graceful_stop: Duration,
+    /// 环形缓冲配置。
+    pub buffer: RingBufferConfig,
+}
+
+impl Default for ProcessConfig {
+    fn default() -> Self {
+        Self {
+            watchdog: WatchdogConfig::default(),
+            graceful_stop: Duration::from_secs(3),
+            buffer: RingBufferConfig::default(),
+        }
+    }
+}
+
+/// 已启动的游戏进程。
+#[derive(Debug)]
+pub struct RunningProcess {
+    child: Child,
+    pump: PumpGroup,
+    buffer: Arc<Mutex<RingBuffer>>,
+    started_at: Instant,
+    pid: u32,
+    config: ProcessConfig,
+}
+
+impl RunningProcess {
+    /// 启动进程并接管两条输出流。
+    pub fn spawn(
+        command: &AssembledCommand,
+        working_dir: Option<&Path>,
+        sink: Arc<dyn LineSink>,
+        config: ProcessConfig,
+    ) -> Result<Self> {
+        let mut process = Command::new(&command.program);
+        process.args(&command.args);
+        for (key, value) in &command.env {
+            process.env(key, value);
+        }
+        if let Some(dir) = working_dir {
+            process.current_dir(dir);
+        }
+        process
+            .stdin(Stdio::null())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::piped());
+        #[cfg(windows)]
+        {
+            use std::os::windows::process::CommandExt;
+            /// 独立进程组：便于 `taskkill /T` 递归回收。
+            const CREATE_NEW_PROCESS_GROUP: u32 = 0x0000_0200;
+            process.creation_flags(CREATE_NEW_PROCESS_GROUP);
+        }
+        #[cfg(unix)]
+        {
+            use std::os::unix::process::CommandExt;
+            // 与 Windows 的 CREATE_NEW_PROCESS_GROUP 对称：子进程自成一个进程组，
+            // `tree_kill` 的 `kill -- -<pgid>` 才能覆盖整棵子树。`process_group` 是
+            // std 1.64+ 的**安全** API，不需要 pre_exec / unsafe（旧注释说“unsafe 被挡”已过时）。
+            // 参数 0 = `pgid = 子进程 pid`。
+            process.process_group(0);
+        }
+
+        let mut child = process.spawn().map_err(|source| LaunchError::Spawn {
+            program: command.program.clone(),
+            source,
+        })?;
+        let pid = child.id();
+        let buffer = Arc::new(Mutex::new(RingBuffer::new(config.buffer)));
+        let stdout = child.stdout.take();
+        let stderr = child.stderr.take();
+        let pump = PumpGroup::spawn(stdout, stderr, buffer.clone(), sink);
+        Ok(Self {
+            child,
+            pump,
+            buffer,
+            started_at: Instant::now(),
+            pid,
+            config,
+        })
+    }
+
+    /// 进程号。
+    pub fn pid(&self) -> u32 {
+        self.pid
+    }
+
+    /// 已运行毫秒数。
+    pub fn uptime_ms(&self) -> u64 {
+        u64::try_from(self.started_at.elapsed().as_millis()).unwrap_or(u64::MAX)
+    }
+
+    /// 启动时刻（窗口检测计时用）。
+    pub fn started_at(&self) -> Instant {
+        self.started_at
+    }
+
+    /// 共享的日志环形缓冲。
+    pub fn buffer(&self) -> Arc<Mutex<RingBuffer>> {
+        self.buffer.clone()
+    }
+
+    /// 当前可读日志快照。
+    pub fn lines(&self) -> Vec<LogLine> {
+        match self.buffer.lock() {
+            Ok(guard) => guard.lines().cloned().collect(),
+            Err(_) => Vec::new(),
+        }
+    }
+
+    /// 等待进程退出（不等待日志泵）。
+    pub fn wait(&mut self) -> Result<ExitStatus> {
+        self.child.wait().map_err(|source| LaunchError::Io {
+            op: "wait_child",
+            path: PathBuf::from(self.pid.to_string()),
+            source,
+        })
+    }
+
+    /// 进程退出后，按预算收尾日志泵。
+    pub fn supervise(&mut self) -> PumpVerdict {
+        watchdog::wait_for_pumps(&mut self.pump, &self.config.watchdog)
+    }
+
+    /// 进程是否仍在运行。
+    pub fn is_running(&mut self) -> bool {
+        matches!(self.child.try_wait(), Ok(None))
+    }
+
+    /// 三段式停止整棵进程树（温和 → 宽限 → 强制）。
+    ///
+    /// 判定标准是**进程是否真的没了**，不是 `taskkill`/`kill` 的退出码：
+    /// 外部命令对“已经退出的进程”会返回非 0（Windows 上 `taskkill` 报 128），
+    /// 把它当失败会误报——尤其是温和阶段已经把进程关掉的情况。
+    pub fn stop(&mut self) -> Result<()> {
+        if !self.is_running() {
+            return Ok(());
+        }
+        let _ = tree_kill::terminate(self.pid);
+        if self.wait_until_exit(self.config.graceful_stop) {
+            return Ok(());
+        }
+        let _ = tree_kill::force_kill(self.pid);
+        if self.wait_until_exit(FORCE_KILL_BUDGET) {
+            return Ok(());
+        }
+        Err(LaunchError::Kill {
+            pid: self.pid,
+            source: std::io::Error::other("强制结束后进程仍在运行"),
+        })
+    }
+
+    /// 直接强杀（看门狗/崩溃兜底路径）。
+    pub fn force_kill(&mut self) -> Result<()> {
+        if !self.is_running() {
+            return Ok(());
+        }
+        let _ = tree_kill::force_kill(self.pid);
+        if self.wait_until_exit(FORCE_KILL_BUDGET) {
+            Ok(())
+        } else {
+            Err(LaunchError::Kill {
+                pid: self.pid,
+                source: std::io::Error::other("强制结束后进程仍在运行"),
+            })
+        }
+    }
+
+    fn wait_until_exit(&mut self, budget: Duration) -> bool {
+        let deadline = Instant::now() + budget;
+        loop {
+            match self.child.try_wait() {
+                Ok(Some(_)) => return true,
+                Ok(None) => {}
+                Err(_) => return false,
+            }
+            if Instant::now() >= deadline {
+                return false;
+            }
+            std::thread::sleep(POLL_INTERVAL);
+        }
+    }
+}
+
+/// 从退出状态取整数退出码。
+///
+/// POSIX 上被子进程信号杀死没有 `code()`，按 shell 惯例补 `128 + signal`
+/// （`SIGKILL` → 137、`SIGTERM` → 143，与 `analyse/02` 附录 C 一致）。
+pub fn exit_code(status: &ExitStatus) -> i32 {
+    if let Some(code) = status.code() {
+        return code;
+    }
+    #[cfg(unix)]
+    {
+        use std::os::unix::process::ExitStatusExt;
+        if let Some(signal) = status.signal() {
+            return 128 + signal;
+        }
+    }
+    -1
+}
diff --git a/crates/core/src/launch/pump.rs b/crates/core/src/launch/pump.rs
new file mode 100644
index 0000000..f7fd684
--- /dev/null
+++ b/crates/core/src/launch/pump.rs
@@ -0,0 +1,379 @@
+//! stdout/stderr 泵与日志环形缓冲。
+//!
+//! 平移自 `analyse/02` §6.1/§6.2（`StreamPump` + `ManagedProcess.lines`），并补两处改进：
+//! 缓冲按“行数 + 字节数”双上限（§8.4-9），且命中 `Exception|Error|Caused by|OutOfMemory`
+//! 的关键行**不随环形淘汰**——2000 行截断会把根因行挤掉（§7.10-3）。
+//!
+//! 解码：我们强制给子进程下发 `-Dstdout.encoding=UTF-8`（`-Dsun.stdout.encoding`
+//! for Java <19），因此泵按 UTF-8 宽松解码；用户把编码改成 GBK 时会出现替换字符，
+//! 阶段B 再视需要引入 `encoding_rs`（记录在 `launch-接口约定.md` §7）。
+
+use std::collections::VecDeque;
+use std::io::{BufRead, BufReader, Read};
+use std::process::{ChildStderr, ChildStdout};
+use std::sync::mpsc::{self, Receiver, Sender};
+use std::sync::{Arc, Mutex};
+use std::thread::{self, JoinHandle};
+use std::time::{Duration, Instant};
+
+use crate::launch::log_level;
+
+/// 默认环形缓冲行数（与 HMCL 一致）。
+pub const DEFAULT_MAX_LINES: usize = 2000;
+/// 默认环形缓冲字节上限。
+pub const DEFAULT_MAX_BYTES: usize = 4 * 1024 * 1024;
+/// 单行最大字符数（超出截断并标注，避免单行撑爆事件流）。
+pub const MAX_LINE_CHARS: usize = 8192;
+
+/// 输出流。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Stream {
+    /// 标准输出。
+    Stdout,
+    /// 标准错误。
+    Stderr,
+}
+
+impl Stream {
+    /// 事件流里的字符串形式（`"stdout"` / `"stderr"`）。
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Stdout => "stdout",
+            Self::Stderr => "stderr",
+        }
+    }
+
+    /// 是否标准错误。
+    pub fn is_stderr(self) -> bool {
+        self == Self::Stderr
+    }
+}
+
+/// 一行日志。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LogLine {
+    /// 来源流。
+    pub stream: Stream,
+    /// 文本（已去行尾、超长已截断）。
+    pub text: String,
+}
+
+impl LogLine {
+    /// 构造。
+    pub fn new(stream: Stream, text: impl Into<String>) -> Self {
+        Self {
+            stream,
+            text: text.into(),
+        }
+    }
+
+    /// 猜测的级别。
+    pub fn level(&self) -> log_level::Level {
+        log_level::guess(self.stream.is_stderr(), &self.text)
+    }
+
+    /// 是否错误级。
+    pub fn is_error(&self) -> bool {
+        self.level().is_error()
+    }
+}
+
+/// 日志观察者（会话事件流、M15 采集器适配层都实现它）。
+pub trait LineSink: Send + Sync {
+    /// 收到一行日志。
+    fn on_line(&self, line: &LogLine);
+}
+
+/// 丢弃所有行的 sink（测试/无监听场景）。
+#[derive(Debug, Default, Clone, Copy)]
+pub struct NullSink;
+
+impl LineSink for NullSink {
+    fn on_line(&self, _line: &LogLine) {}
+}
+
+/// 环形缓冲配置。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct RingBufferConfig {
+    /// 行数上限。
+    pub max_lines: usize,
+    /// 字节上限。
+    pub max_bytes: usize,
+}
+
+impl Default for RingBufferConfig {
+    fn default() -> Self {
+        Self {
+            max_lines: DEFAULT_MAX_LINES,
+            max_bytes: DEFAULT_MAX_BYTES,
+        }
+    }
+}
+
+/// 环形日志缓冲：近期行 + 永久保留的关键行。
+#[derive(Debug)]
+pub struct RingBuffer {
+    config: RingBufferConfig,
+    recent: VecDeque<LogLine>,
+    retained: Vec<LogLine>,
+    bytes: usize,
+    pushed: u64,
+}
+
+impl RingBuffer {
+    /// 构造。
+    pub fn new(config: RingBufferConfig) -> Self {
+        Self {
+            config,
+            recent: VecDeque::new(),
+            retained: Vec::new(),
+            bytes: 0,
+            pushed: 0,
+        }
+    }
+
+    /// 压入一行，必要时淘汰最早的行（关键行转入 `retained`）。
+    pub fn push(&mut self, line: LogLine) {
+        self.pushed += 1;
+        let size = line.text.len();
+        self.bytes += size;
+        self.recent.push_back(line);
+        while self.recent.len() > self.config.max_lines || self.bytes > self.config.max_bytes {
+            let Some(evicted) = self.recent.pop_front() else {
+                break;
+            };
+            self.bytes = self.bytes.saturating_sub(evicted.text.len());
+            if log_level::is_key_line(&evicted.text) {
+                self.retained.push(evicted);
+            }
+        }
+    }
+
+    /// 按时间顺序取全部可读行（保留的关键行在前）。
+    pub fn lines(&self) -> impl Iterator<Item = &LogLine> {
+        self.retained.iter().chain(self.recent.iter())
+    }
+
+    /// 拼接成文本（喂给规则引擎/日志切片）。
+    pub fn text(&self) -> String {
+        let mut out = String::with_capacity(self.bytes.min(64 * 1024));
+        for line in self.lines() {
+            out.push_str(&line.text);
+            out.push('\n');
+        }
+        out
+    }
+
+    /// 只要错误级行（退出分析的输入）。
+    pub fn error_lines(&self) -> Vec<&LogLine> {
+        self.lines().filter(|line| line.is_error()).collect()
+    }
+
+    /// 当前可读行数。
+    pub fn len(&self) -> usize {
+        self.retained.len() + self.recent.len()
+    }
+
+    /// 是否为空。
+    pub fn is_empty(&self) -> bool {
+        self.len() == 0
+    }
+
+    /// 累计压入行数（含已被淘汰的）。
+    pub fn total_pushed(&self) -> u64 {
+        self.pushed
+    }
+}
+
+impl Default for RingBuffer {
+    fn default() -> Self {
+        Self::new(RingBufferConfig::default())
+    }
+}
+
+/// 单条流结束的回执。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct StreamFinished {
+    /// 哪条流。
+    pub stream: Stream,
+    /// 累计行数。
+    pub line_count: u64,
+    /// 读取错误（有的话）。
+    pub error: Option<String>,
+}
+
+/// 一次等待 PumpGroup 的结果。
+#[derive(Debug, Clone, Default)]
+pub struct PumpCompletion {
+    /// 已结束的流。
+    pub finished: Vec<StreamFinished>,
+    /// 超时仍未结束的流。
+    pub stalled: Vec<Stream>,
+}
+
+impl PumpCompletion {
+    /// 是否全部结束。
+    pub fn is_complete(&self) -> bool {
+        self.stalled.is_empty()
+    }
+
+    /// 累计行数。
+    pub fn total_lines(&self) -> u64 {
+        self.finished.iter().map(|item| item.line_count).sum()
+    }
+}
+
+/// 一组泵线程（stdout + stderr）。
+#[derive(Debug)]
+pub struct PumpGroup {
+    handles: Vec<JoinHandle<()>>,
+    receiver: Receiver<StreamFinished>,
+    streams: Vec<Stream>,
+    completed: Vec<Stream>,
+}
+
+impl PumpGroup {
+    /// 为子进程的输出流派生泵线程。
+    ///
+    /// `buffer` 与 `sink` 同时被两个泵线程共享：缓冲区用于“最后 N 行”，
+    /// sink 用于事件流落盘。
+    pub fn spawn(
+        stdout: Option<ChildStdout>,
+        stderr: Option<ChildStderr>,
+        buffer: Arc<Mutex<RingBuffer>>,
+        sink: Arc<dyn LineSink>,
+    ) -> Self {
+        let (sender, receiver) = mpsc::channel();
+        let mut handles = Vec::new();
+        let mut streams = Vec::new();
+        if let Some(stdout) = stdout {
+            streams.push(Stream::Stdout);
+            handles.push(spawn_one(
+                Box::new(stdout),
+                Stream::Stdout,
+                buffer.clone(),
+                sink.clone(),
+                sender.clone(),
+            ));
+        }
+        if let Some(stderr) = stderr {
+            streams.push(Stream::Stderr);
+            handles.push(spawn_one(
+                Box::new(stderr),
+                Stream::Stderr,
+                buffer,
+                sink,
+                sender.clone(),
+            ));
+        }
+        drop(sender);
+        Self {
+            handles,
+            receiver,
+            streams,
+            completed: Vec::new(),
+        }
+    }
+
+    /// 期望的流数。
+    pub fn expected(&self) -> usize {
+        self.streams.len()
+    }
+
+    /// 等待所有泵结束（带超时，避免 HMCL `pump.join()` 永久挂死的风险）。
+    pub fn wait(&mut self, timeout: Duration) -> PumpCompletion {
+        let deadline = Instant::now() + timeout;
+        let mut finished = Vec::new();
+        while self.completed.len() < self.streams.len() {
+            let remaining = deadline.saturating_duration_since(Instant::now());
+            if remaining.is_zero() {
+                break;
+            }
+            match self.receiver.recv_timeout(remaining) {
+                Ok(item) => {
+                    if !self.completed.contains(&item.stream) {
+                        self.completed.push(item.stream);
+                    }
+                    finished.push(item);
+                }
+                Err(_) => break,
+            }
+        }
+        let stalled = self
+            .streams
+            .iter()
+            .copied()
+            .filter(|stream| !self.completed.contains(stream))
+            .collect();
+        PumpCompletion { finished, stalled }
+    }
+
+    /// 强制 join（可能永久阻塞——只在上层已经确认流已关闭时使用）。
+    pub fn join_all(&mut self) {
+        for handle in self.handles.drain(..) {
+            let _ = handle.join();
+        }
+    }
+}
+
+type BoxedReader = Box<dyn Read + Send>;
+
+fn spawn_one(
+    reader: BoxedReader,
+    stream: Stream,
+    buffer: Arc<Mutex<RingBuffer>>,
+    sink: Arc<dyn LineSink>,
+    sender: Sender<StreamFinished>,
+) -> JoinHandle<()> {
+    thread::Builder::new()
+        .name(format!("launch-pump-{}", stream.as_str()))
+        .spawn(move || {
+            let mut reader = BufReader::new(reader);
+            let mut raw = Vec::with_capacity(4096);
+            let mut line_count = 0u64;
+            let mut error = None;
+            loop {
+                raw.clear();
+                match reader.read_until(b'\n', &mut raw) {
+                    Ok(0) => break,
+                    Ok(_) => {
+                        let text = decode_line(&raw);
+                        if text.is_empty() {
+                            continue;
+                        }
+                        line_count += 1;
+                        let line = LogLine::new(stream, text);
+                        if let Ok(mut guard) = buffer.lock() {
+                            guard.push(line.clone());
+                        }
+                        sink.on_line(&line);
+                    }
+                    Err(err) => {
+                        error = Some(err.to_string());
+                        break;
+                    }
+                }
+            }
+            let _ = sender.send(StreamFinished {
+                stream,
+                line_count,
+                error,
+            });
+        })
+        .expect("spawn log pump thread")
+}
+
+fn decode_line(raw: &[u8]) -> String {
+    let text = String::from_utf8_lossy(raw);
+    let trimmed = text.trim_end_matches(['\r', '\n']);
+    truncate_line(trimmed)
+}
+
+fn truncate_line(text: &str) -> String {
+    if text.chars().count() <= MAX_LINE_CHARS {
+        return text.to_string();
+    }
+    let head: String = text.chars().take(MAX_LINE_CHARS).collect();
+    let extra = text.chars().count() - MAX_LINE_CHARS;
+    format!("{head}…[truncated {extra} chars]")
+}
diff --git a/crates/core/src/launch/redact.rs b/crates/core/src/launch/redact.rs
new file mode 100644
index 0000000..78b7425
--- /dev/null
+++ b/crates/core/src/launch/redact.rs
@@ -0,0 +1,299 @@
+//! 日志与事件流的脱敏（写入前执行，落盘即脱敏）。
+//!
+//! 规则见 `DevDocs/SubAgentsTalk/launch-接口约定.md` §4：
+//! token 整串替换、用户主目录替换、长度 ≥64 的不透明串（base64/hex token）替换。
+//! 依据 `analyse/02` §6.4 / §8.4-5（HMCL 只过滤 access token，我们要求导出前全量脱敏）。
+//!
+//! 第四条规则（M40 从 `auth::body` 上提）：**带点 token** 整串替换。JWT 形状是
+//! `header.payload.signature`（XSTS/XBL 票据正是这个），点号把连续段切开，单看
+//! 「连续不透明串 ≥64」这条会整串原样放过。规则只在这里实现一份，所有调用方
+//! （launch 会话 / 诊断 / auth 错误摘要 …）共用，避免各自补一套后漂移。
+
+use std::borrow::Cow;
+use std::path::Path;
+
+use serde_json::Value;
+
+/// access token / session token 的替换标记。
+pub const TOKEN_PLACEHOLDER: &str = "<redacted:token>";
+/// 用户主目录的替换标记。
+pub const HOME_PLACEHOLDER: &str = "<home>";
+/// 形似 token 的长不透明串的替换标记。
+pub const OPAQUE_PLACEHOLDER: &str = "<redacted:opaque>";
+
+/// 判定“像 token”的最短连续长度。
+const MAX_OPAQUE_RUN: usize = 64;
+/// 「带点 token」（JWT 三段式）判定的最短总长。
+const DOTTED_TOKEN_MIN_TOTAL: usize = 40;
+/// 「带点 token」每一段的最短长度（挡住 `Service.Unavailable.today` 这类正常文案）。
+const DOTTED_TOKEN_MIN_SEGMENT: usize = 8;
+
+/// 脱敏器：持有需要抹掉的敏感值（token、主目录）。
+#[derive(Debug, Clone, Default)]
+pub struct Redactor {
+    secrets: Vec<String>,
+    homes: Vec<String>,
+}
+
+impl Redactor {
+    /// 空脱敏器（不做任何替换）。
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// 登记一个敏感值（access token、userhash、xuid 等）。
+    ///
+    /// 太短的值（< 6 字节）会被忽略：替换一个 3 字符串会把正常日志搅乱。
+    pub fn with_secret(mut self, secret: impl Into<String>) -> Self {
+        let secret = secret.into();
+        if secret.trim().len() >= 6 && !self.secrets.contains(&secret) {
+            self.secrets.push(secret);
+        }
+        self
+    }
+
+    /// 登记一个需要抹掉的主目录（替换成 `<home>`）。
+    pub fn with_home(mut self, home: impl AsRef<Path>) -> Self {
+        let home = home.as_ref().to_string_lossy().into_owned();
+        if home.len() > 3 && !self.homes.contains(&home) {
+            self.homes.push(home);
+        }
+        self
+    }
+
+    /// 登记一个主目录字符串。
+    pub fn with_home_str(mut self, home: impl Into<String>) -> Self {
+        let home = home.into();
+        if home.len() > 3 && !self.homes.contains(&home) {
+            self.homes.push(home);
+        }
+        self
+    }
+
+    /// 是否登记了任何规则。
+    pub fn is_empty(&self) -> bool {
+        self.secrets.is_empty() && self.homes.is_empty()
+    }
+
+    /// 对文本脱敏；无需修改时返回借用，避免无谓拷贝。
+    pub fn scrub<'a>(&self, text: &'a str) -> Cow<'a, str> {
+        let mut current: Cow<'a, str> = Cow::Borrowed(text);
+        for secret in &self.secrets {
+            if current.contains(secret.as_str()) {
+                current = Cow::Owned(current.replace(secret.as_str(), TOKEN_PLACEHOLDER));
+            }
+        }
+        for home in &self.homes {
+            if current.contains(home.as_str()) {
+                current = Cow::Owned(current.replace(home.as_str(), HOME_PLACEHOLDER));
+            }
+        }
+        if has_dotted_token(&current) {
+            current = Cow::Owned(mask_dotted_tokens(&current));
+        }
+        if has_opaque_run(&current) {
+            current = Cow::Owned(mask_opaque(&current));
+        }
+        current
+    }
+
+    /// 对整条命令行脱敏（`cmd_built.argv` 必然含 accessToken，必须走这里）。
+    pub fn scrub_all(&self, values: &[String]) -> Vec<String> {
+        values
+            .iter()
+            .map(|value| self.scrub(value).into_owned())
+            .collect()
+    }
+
+    /// 递归脱敏一个 JSON 值。
+    ///
+    /// **只改字符串**：数值/布尔/null 与字段名原样保留——满足「launch 只做脱敏、不改写字段」
+    /// 的契约（`DevDocs/SubAgentsTalk/launch-接口约定.md` §9.3）。诊断结论里的证据行常带
+    /// 崩溃报告/`hs_err` 的绝对路径，正是要过 `<home>` 规则的地方。
+    pub fn scrub_json(&self, value: &Value) -> Value {
+        match value {
+            Value::String(text) => Value::String(self.scrub(text).into_owned()),
+            Value::Array(items) => {
+                Value::Array(items.iter().map(|item| self.scrub_json(item)).collect())
+            }
+            Value::Object(map) => Value::Object(
+                map.iter()
+                    .map(|(key, value)| (key.clone(), self.scrub_json(value)))
+                    .collect(),
+            ),
+            other => other.clone(),
+        }
+    }
+}
+
+/// 文本里是否含长度 ≥64 的“不透明串”（base64/hex token 的特征）。
+pub fn has_opaque_run(text: &str) -> bool {
+    let mut run = 0usize;
+    for ch in text.chars() {
+        if is_opaque_char(ch) {
+            run += 1;
+            if run >= MAX_OPAQUE_RUN {
+                return true;
+            }
+        } else {
+            run = 0;
+        }
+    }
+    false
+}
+
+/// 把长度 ≥64 的不透明串替换成 [`OPAQUE_PLACEHOLDER`]。
+pub fn mask_opaque(text: &str) -> String {
+    let mut out = String::with_capacity(text.len());
+    let mut run_start: Option<usize> = None;
+    for (idx, ch) in text.char_indices() {
+        if is_opaque_char(ch) {
+            if run_start.is_none() {
+                run_start = Some(idx);
+            }
+        } else {
+            if let Some(start) = run_start.take() {
+                push_masked(&mut out, &text[start..idx]);
+            }
+            out.push(ch);
+        }
+    }
+    if let Some(start) = run_start {
+        push_masked(&mut out, &text[start..]);
+    }
+    out
+}
+
+fn push_masked(out: &mut String, run: &str) {
+    if run.len() >= MAX_OPAQUE_RUN {
+        out.push_str(OPAQUE_PLACEHOLDER);
+    } else {
+        out.push_str(run);
+    }
+}
+
+fn is_opaque_char(ch: char) -> bool {
+    ch.is_ascii_alphanumeric() || matches!(ch, '+' | '/' | '=' | '_' | '-')
+}
+
+/// 文本里是否含「带点 token」（≥3 段、每段 ≥8、总长 ≥40）。
+pub fn has_dotted_token(text: &str) -> bool {
+    let mut start: Option<usize> = None;
+    for (idx, ch) in text.char_indices() {
+        if is_dotted_token_char(ch) {
+            start.get_or_insert(idx);
+            continue;
+        }
+        if let Some(from) = start.take() {
+            if is_dotted_token(&text[from..idx]) {
+                return true;
+            }
+        }
+    }
+    start.is_some_and(|from| is_dotted_token(&text[from..]))
+}
+
+/// 把「带点 token」整串替换成 [`TOKEN_PLACEHOLDER`]（段外文本原样保留）。
+pub fn mask_dotted_tokens(text: &str) -> String {
+    let mut out = String::with_capacity(text.len());
+    let mut start: Option<usize> = None;
+    for (idx, ch) in text.char_indices() {
+        if is_dotted_token_char(ch) {
+            start.get_or_insert(idx);
+            continue;
+        }
+        if let Some(from) = start.take() {
+            push_dotted(&mut out, &text[from..idx]);
+        }
+        out.push(ch);
+    }
+    if let Some(from) = start {
+        push_dotted(&mut out, &text[from..]);
+    }
+    out
+}
+
+fn push_dotted(out: &mut String, run: &str) {
+    if is_dotted_token(run) {
+        out.push_str(TOKEN_PLACEHOLDER);
+    } else {
+        out.push_str(run);
+    }
+}
+
+/// 「带点 token」的字符集：比不透明串多一个 `.`（JWT 的分段符）。
+fn is_dotted_token_char(ch: char) -> bool {
+    is_opaque_char(ch) || ch == '.'
+}
+
+/// 单段连写（无空白）的串是否像 JWT：段数 ≥3、每段 ≥8 字节、总长 ≥40。
+fn is_dotted_token(run: &str) -> bool {
+    run.len() >= DOTTED_TOKEN_MIN_TOTAL
+        && run.split('.').count() >= 3
+        && run
+            .split('.')
+            .all(|segment| segment.len() >= DOTTED_TOKEN_MIN_SEGMENT)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// 真实形状的 JWT（header.payload.signature，三段各 ≥8）。
+    const JWT: &str = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.c2lnbmF0dXJlLXZhbHVlLXRoYXQtaXMtbG9uZy1lbm91Z2g";
+
+    #[test]
+    fn jwt_token_is_masked_without_any_registered_secret() {
+        let scrubbed = Redactor::new().scrub(JWT).into_owned();
+        assert!(scrubbed.contains(TOKEN_PLACEHOLDER), "{scrubbed}");
+        assert!(!scrubbed.contains("eyJhbGci"), "{scrubbed}");
+
+        // 嵌在别的内容里也只换 token 本体。
+        let masked = Redactor::new()
+            .scrub(&format!("authorization: Bearer {JWT}, retry=1"))
+            .into_owned();
+        assert_eq!(
+            masked,
+            format!("authorization: Bearer {TOKEN_PLACEHOLDER}, retry=1")
+        );
+    }
+
+    #[test]
+    fn dotted_token_rule_does_not_eat_normal_text() {
+        // 分段太短、总长不够、段数不够：三种都不算 token。
+        for text in [
+            "Service.Unavailable.today",
+            "1.2.0",
+            "xbl.xsts.entitlements.profile",
+            "eyJhbGciOiJIUzI1NiJ9.short.abc",
+        ] {
+            assert!(!has_dotted_token(text), "{text}");
+            assert_eq!(Redactor::new().scrub(text), text, "{text}");
+        }
+    }
+
+    #[test]
+    fn existing_rules_still_apply() {
+        let redactor = Redactor::new()
+            .with_secret("SECRET-TOKEN-123456")
+            .with_home_str("/home/alice");
+        let scrubbed = redactor
+            .scrub("/home/alice/game.log: token=SECRET-TOKEN-123456")
+            .into_owned();
+        assert!(scrubbed.contains(HOME_PLACEHOLDER), "{scrubbed}");
+        assert!(scrubbed.contains(TOKEN_PLACEHOLDER), "{scrubbed}");
+        assert!(
+            !scrubbed.contains("alice") && !scrubbed.contains("SECRET"),
+            "{scrubbed}"
+        );
+
+        // 没有点号的长不透明串仍走 ≥64 规则，替换标记也不同。
+        let long = "A".repeat(MAX_OPAQUE_RUN);
+        assert!(has_opaque_run(&long));
+        assert!(!has_dotted_token(&long));
+        assert_eq!(
+            Redactor::new().scrub(&long).into_owned(),
+            OPAQUE_PLACEHOLDER.to_string()
+        );
+    }
+}
diff --git a/crates/core/src/launch/request.rs b/crates/core/src/launch/request.rs
new file mode 100644
index 0000000..6a4f54d
--- /dev/null
+++ b/crates/core/src/launch/request.rs
@@ -0,0 +1,358 @@
+//! 启动请求：命令行组装的输入模型（纯数据，无 IO，便于快照测试）。
+//!
+//! 与 `crate::game` / `crate::download` 的映射关系见
+//! `DevDocs/SubAgentsTalk/launch-接口约定.md` §6：launch 阶段只消费本结构，
+//! 由薄适配层把 game 的快照搬进来，避免 launch 对 manifest 类型产生编译期依赖。
+
+use std::path::PathBuf;
+
+use crate::launch::argument::ArgumentEntry;
+use crate::launch::error::MissingComponent;
+use crate::launch::game_version::GameVersion;
+use crate::launch::natives::NativesPlan;
+
+/// 实例信息。
+#[derive(Debug, Clone, Default)]
+pub struct InstanceInfo {
+    /// 实例/版本 id（稳定 UUID 或版本目录名）。
+    pub id: String,
+    /// 展示名（`${version_name}`）。
+    pub name: String,
+    /// 游戏版本号（分支门限用）。
+    pub version: GameVersion,
+    /// 版本类型（`release` / `snapshot`；`${version_type}`）。
+    pub version_type: String,
+}
+
+/// 启动器自身信息（`${launcher_name}` / `${launcher_version}`）。
+#[derive(Debug, Clone, Default)]
+pub struct LauncherInfo {
+    /// 名称。
+    pub name: String,
+    /// 版本。
+    pub version: String,
+}
+
+/// 选定的 Java 运行时。
+#[derive(Debug, Clone, Default)]
+pub struct JavaSelection {
+    /// `java` 可执行文件路径。
+    pub binary: PathBuf,
+    /// 主版本号（8 / 17 / 21 / 25 …）。
+    pub major: u32,
+    /// 位数（32 / 64）。
+    pub bits: u32,
+}
+
+impl JavaSelection {
+    /// 构造。
+    pub fn new(binary: impl Into<PathBuf>, major: u32, bits: u32) -> Self {
+        Self {
+            binary: binary.into(),
+            major,
+            bits,
+        }
+    }
+
+    /// 是否 64 位 JVM。
+    pub fn is_64bit(&self) -> bool {
+        self.bits == 64
+    }
+}
+
+/// 内存设置（MiB）。
+#[derive(Debug, Clone, Copy, Default)]
+pub struct MemoryOptions {
+    /// 初始堆 `-Xms`。
+    pub min_mb: Option<u32>,
+    /// 最大堆 `-Xmx`。
+    pub max_mb: Option<u32>,
+}
+
+/// 版本清单里的参数（`arguments.jvm` / `arguments.game` / 旧版 `minecraftArguments`）。
+#[derive(Debug, Clone, Default)]
+pub struct ManifestArgs {
+    /// 主类。
+    pub main_class: Option<String>,
+    /// 现代清单的 JVM 参数（带 rules）。
+    pub jvm: Vec<ArgumentEntry>,
+    /// 现代清单的游戏参数（带 rules）。
+    pub game: Vec<ArgumentEntry>,
+    /// 旧版清单的整串游戏参数（1.12 及更早）。
+    pub legacy_arguments: Option<String>,
+    /// 版本库表里带 LWJGL 的 Vulkan 绑定（`org.lwjgl:lwjgl-vulkan`）。
+    ///
+    /// 只作「无法排序的版本」（周快照）的 `--graphicsBackend` 兜底判据与 UI 提示；
+    /// 可解析版本的下发门限仍是 `26.2-snapshot-2`（见
+    /// [`graphics_backend_allowed`](crate::launch::game_args::graphics_backend_allowed)）。
+    pub has_vulkan_backend: bool,
+}
+
+impl ManifestArgs {
+    /// 是否走旧版参数模板（只有 `minecraftArguments`，没有 `arguments`）。
+    pub fn is_legacy(&self) -> bool {
+        self.jvm.is_empty() && self.legacy_arguments.is_some()
+    }
+}
+
+/// 目录布局。
+#[derive(Debug, Clone, Default)]
+pub struct LaunchDirs {
+    /// 运行目录（`${game_directory}`，同时是子进程的 CWD）。
+    ///
+    /// D20：这个值是**隔离覆盖链的派生结果**（`game::isolation::derive_game_dir`：
+    /// 临时参数 > 实例 `isolation` > 全局 `instances.mode`）。launch 侧只消费、不派生，
+    /// 也不读配置——路径语义的真相在 `core::game`。
+    pub game_dir: PathBuf,
+    /// 资产根。
+    pub assets_root: PathBuf,
+    /// 重建后的虚拟资产目录（`${game_assets}`）。
+    pub game_assets: PathBuf,
+    /// 资产索引 id（`${assets_index_name}`）。
+    pub assets_index: String,
+    /// 原生库目录（按 Java 平台选择，`analyse/02` §4.6）。
+    pub natives_dir: PathBuf,
+    /// 库根目录。
+    pub library_dir: PathBuf,
+    /// 主 jar。
+    pub primary_jar: PathBuf,
+}
+
+/// 账户占位符值。
+#[derive(Debug, Clone, Default)]
+pub struct AuthPlaceholders {
+    /// 玩家名。
+    pub player_name: String,
+    /// 无连字符 UUID。
+    pub uuid: String,
+    /// 访问令牌（落盘前必须脱敏）。
+    pub access_token: String,
+    /// `msa` / `legacy`。
+    pub user_type: String,
+    /// `user_properties` JSON 串。
+    pub user_properties: String,
+}
+
+/// 用户自定义参数。
+#[derive(Debug, Clone, Default)]
+pub struct UserArgs {
+    /// 最高优先级 JVM 参数（不解析转义，会读 `@argfile`）。
+    pub override_jvm: Vec<String>,
+    /// 普通 JVM 参数（整体按“默认值”处理）。
+    pub jvm: Vec<String>,
+    /// 追加在最后、可覆盖前面一切的 game 参数。
+    pub game: Vec<String>,
+    /// 额外环境变量（用户自定义，最后覆盖）。
+    pub environment: Vec<(String, String)>,
+}
+
+/// 清单参数 rules 求值所需的特性开关。
+#[derive(Debug, Clone, Copy, Default)]
+pub struct FeatureSet {
+    /// 用户指定了分辨率（`--width/--height` 的开关）。
+    pub has_custom_resolution: bool,
+    /// 演示模式。
+    pub is_demo_user: bool,
+    /// 支持 QuickPlay（1.20+）。
+    pub has_quick_plays_support: bool,
+}
+
+impl FeatureSet {
+    /// 按特性名查询（未知特性为 `None`）。
+    pub fn get(&self, name: &str) -> Option<bool> {
+        match name {
+            "has_custom_resolution" => Some(self.has_custom_resolution),
+            "is_demo_user" => Some(self.is_demo_user),
+            "has_quick_plays_support" => Some(self.has_quick_plays_support),
+            _ => None,
+        }
+    }
+}
+
+/// 窗口分辨率。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Resolution {
+    /// 宽。
+    pub width: u32,
+    /// 高。
+    pub height: u32,
+}
+
+/// 一键进入目标。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum QuickPlay {
+    /// 直入存档。
+    Singleplayer {
+        /// 存档目录名。
+        world: String,
+    },
+    /// 直入服务器。
+    Multiplayer {
+        /// `host:port` 形式地址。
+        address: String,
+    },
+    /// 直入 Realms。
+    Realms {
+        /// Realm id。
+        realm_id: String,
+    },
+}
+
+/// SOCKS 代理。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SocksProxy {
+    /// 主机。
+    pub host: String,
+    /// 端口。
+    pub port: u16,
+    /// 用户名。
+    pub username: Option<String>,
+    /// 密码。
+    pub password: Option<String>,
+}
+
+/// 模组加载器种类（决定 Forge 专属参数与环境变量）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum ModLoaderKind {
+    /// 原版。
+    #[default]
+    Vanilla,
+    /// Forge。
+    Forge,
+    /// NeoForge。
+    NeoForge,
+    /// Fabric。
+    Fabric,
+    /// Quilt。
+    Quilt,
+    /// LiteLoader。
+    LiteLoader,
+    /// OptiFine（独立安装器）。
+    OptiFine,
+}
+
+impl ModLoaderKind {
+    /// 是否使用 FML/LaunchWrapper（决定 `-Dfml.ignore*` 参数）。
+    pub fn is_fml_like(self) -> bool {
+        matches!(self, Self::Forge | Self::NeoForge | Self::LiteLoader)
+    }
+}
+
+/// Log4j 注入选项。
+#[derive(Debug, Clone)]
+pub struct Log4jOptions {
+    /// 是否注入日志配置（HMCL：版本 ≥1.7 即注入，探测失败按 1.7 兜底）。
+    pub enabled: bool,
+    /// 配置文件路径（`-Dlog4j.configurationFile=`）。
+    pub config_file: Option<PathBuf>,
+    /// 调试日志变体。
+    pub debug: bool,
+}
+
+impl Default for Log4jOptions {
+    fn default() -> Self {
+        Self {
+            enabled: true,
+            config_file: None,
+            debug: false,
+        }
+    }
+}
+
+/// 渲染器相关开关（`analyse/02` §4.1 #17、§4.10）。
+#[derive(Debug, Clone, Default)]
+pub struct RendererOptions {
+    /// 软件渲染（Mesa/llvmpipe）。
+    pub software: bool,
+    /// Windows 上 mesa 的 native 目录。
+    pub mesa_native_dir: Option<PathBuf>,
+    /// macOS 上的 Vulkan ICD JSON。
+    pub vulkan_icd: Option<PathBuf>,
+}
+
+/// JVM 自动优化选项。
+#[derive(Debug, Clone)]
+pub struct OptimizationOptions {
+    /// 是否注入自动优化参数（用户可关）。
+    pub enabled: bool,
+    /// 物理内存 MiB（决定 CodeCache 一组参数的开关）。
+    pub physical_memory_mb: Option<u64>,
+}
+
+impl Default for OptimizationOptions {
+    fn default() -> Self {
+        Self {
+            enabled: true,
+            physical_memory_mb: None,
+        }
+    }
+}
+
+/// 一次启动的完整输入。
+#[derive(Debug, Clone, Default)]
+pub struct LaunchRequest {
+    /// 实例信息。
+    pub instance: InstanceInfo,
+    /// 启动器信息。
+    pub launcher: LauncherInfo,
+    /// Java 运行时。
+    pub java: JavaSelection,
+    /// 内存。
+    pub memory: MemoryOptions,
+    /// 清单参数。
+    pub manifest: ManifestArgs,
+    /// 目录布局。
+    pub dirs: LaunchDirs,
+    /// natives 解压计划（`dirs.natives_dir` 为目标目录，`jars` 为分类器构件清单）。
+    ///
+    /// 解压发生在**组装期**（`Launcher::dry_run`/`spawn` 的「环境准备」段），
+    /// 见 [`crate::launch::natives`] 与 `SubAgentsTalk/launch-natives-解压与时代分界.md`。
+    pub natives: NativesPlan,
+    /// 账户。
+    pub auth: AuthPlaceholders,
+    /// 用户参数。
+    pub user: UserArgs,
+    /// 特性开关。
+    pub features: FeatureSet,
+    /// 分辨率（`None` 表示不指定）。
+    pub resolution: Option<Resolution>,
+    /// 一键进入。
+    pub quick_play: Option<QuickPlay>,
+    /// SOCKS 代理。
+    pub proxy: Option<SocksProxy>,
+    /// 图形后端（`default` / `opengl` / `vulkan`）。
+    ///
+    /// 下发门限见 [`graphics_backend_allowed`](crate::launch::game_args::graphics_backend_allowed)：
+    /// 可解析版本 ≥ `26.2-snapshot-2`，周快照另按版本库表的能力位判。
+    pub graphics_backend: Option<String>,
+    /// 全屏。
+    pub fullscreen: bool,
+    /// 进程优先级（POSIX `nice -n`，Windows 忽略）。
+    pub nice: Option<i32>,
+    /// 命令包装器（`optirun`、`prime-run` 等）。
+    pub wrapper: Vec<String>,
+    /// `-javaagent:` 列表。
+    pub java_agents: Vec<String>,
+    /// 登录源提供的 JVM 参数（authlib-injector）。
+    pub auth_jvm_args: Vec<String>,
+    /// 登录源提供的游戏参数。
+    pub auth_game_args: Vec<String>,
+    /// 模组加载器。
+    pub mod_loader: ModLoaderKind,
+    /// Log4j 注入。
+    pub log4j: Log4jOptions,
+    /// 渲染器开关。
+    pub renderer: RendererOptions,
+    /// JVM 自动优化。
+    pub optimization: OptimizationOptions,
+    /// `-Dfile.encoding` 指定值（`COMPAT` 表示跟随系统）。
+    pub encoding: Option<String>,
+    /// 界面语言（`${language}`）。
+    pub language: String,
+    /// 已过滤为“确实存在”的 classpath（主 jar 由组装器追加到末位）。
+    pub classpath: Vec<PathBuf>,
+    /// 组件就绪检查发现的缺失项（非空则组装直接失败）。
+    pub missing_components: Vec<MissingComponent>,
+    /// 额外注入的 JVM 参数（品牌/特性钩子，`appendJvmArgs` 的替代者）。
+    pub extra_jvm: Vec<String>,
+}
diff --git a/crates/core/src/launch/session.rs b/crates/core/src/launch/session.rs
new file mode 100644
index 0000000..54c4989
--- /dev/null
+++ b/crates/core/src/launch/session.rs
@@ -0,0 +1,375 @@
+//! JSONL 会话事件流：`<sessions_root>/game/<session-id>.jsonl`。
+//!
+//! schema 见 `DevDocs/SubAgentsTalk/launch-接口约定.md` §2/§3（v1）——M15 诊断采集器与
+//! M16 `read_game_log`/`list_game_sessions` 消费同一份文件，是**单一真相源**。
+//!
+//! 两条纪律写死在实现里：
+//! 1. 脱敏在写入前做（[`Redactor`]），`cmd_built.argv` 也不例外（命令行必含 accessToken）；
+//! 2. 「launch 报事实、M15 下结论」：`diagnosis` 事件由 M15 产出、由本模块落盘。
+
+use std::fs::{self, File, OpenOptions};
+use std::io::{BufWriter, Write};
+use std::path::{Path, PathBuf};
+
+use serde::Serialize;
+use serde_json::Value;
+
+use crate::launch::args_table::AssembledCommand;
+use crate::launch::error::{AssemblyError, LaunchError, Result};
+use crate::launch::exit_analysis::ExitAnalysis;
+use crate::launch::natives::NativesReport;
+use crate::launch::pump::{LogLine, Stream};
+use crate::launch::redact::Redactor;
+use crate::launch::session_index::{self, SessionIndexEntry};
+use crate::launch::session_payload as payload;
+use crate::launch::time::{self, SessionClock};
+use crate::launch::window_detect::Detection;
+
+/// 事件 schema 版本。
+pub const SCHEMA_VERSION: u8 = 1;
+
+/// 事件类型。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum EventKind {
+    /// 会话开始。
+    SessionStart,
+    /// Java 选择结果。
+    JavaSelected,
+    /// 命令行组装完成。
+    CmdBuilt,
+    /// natives 解压结果。
+    NativesExtracted,
+    /// 启动前失败（没有进程）。
+    AssemblyFailed,
+    /// 进程已启动。
+    ProcStart,
+    /// stdout 行。
+    Stdout,
+    /// stderr 行。
+    Stderr,
+    /// 检测到游戏窗口。
+    WindowDetected,
+    /// 进程退出。
+    Exit,
+    /// 发现崩溃报告 / hs_err。
+    CrashFound,
+    /// 诊断结论（M15 产出）。
+    Diagnosis,
+    /// 被主动结束。
+    Killed,
+    /// 会话结束。
+    SessionEnd,
+}
+
+impl EventKind {
+    /// JSONL 里的 `kind` 字符串。
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::SessionStart => "session_start",
+            Self::JavaSelected => "java_selected",
+            Self::CmdBuilt => "cmd_built",
+            Self::NativesExtracted => "natives_extracted",
+            Self::AssemblyFailed => "assembly_failed",
+            Self::ProcStart => "proc_start",
+            Self::Stdout => "stdout",
+            Self::Stderr => "stderr",
+            Self::WindowDetected => "window_detected",
+            Self::Exit => "exit",
+            Self::CrashFound => "crash_found",
+            Self::Diagnosis => "diagnosis",
+            Self::Killed => "killed",
+            Self::SessionEnd => "session_end",
+        }
+    }
+}
+
+/// 会话结束原因。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum EndReason {
+    /// 进程自然退出。
+    Exit,
+    /// 被主动结束。
+    Killed,
+    /// 启动前失败（组装/组件检查）。
+    AssemblyFailed,
+    /// 进程派生失败。
+    SpawnFailed,
+}
+
+impl EndReason {
+    /// JSONL 里的 `reason` 字符串。
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Exit => "exit",
+            Self::Killed => "killed",
+            Self::AssemblyFailed => "assembly_failed",
+            Self::SpawnFailed => "spawn_failed",
+        }
+    }
+}
+
+pub use crate::launch::session_meta::SessionMeta;
+pub use crate::launch::session_sink::SessionSink;
+
+#[derive(Serialize)]
+struct EventLine<'a> {
+    v: u8,
+    seq: u64,
+    ts: String,
+    t_ms: u64,
+    kind: &'a str,
+    session_id: &'a str,
+    payload: &'a Value,
+}
+
+/// 会话事件流写入器。
+#[derive(Debug)]
+pub struct SessionWriter {
+    session_id: String,
+    clock: SessionClock,
+    file: BufWriter<File>,
+    path: PathBuf,
+    index_path: PathBuf,
+    seq: u64,
+    event_count: u64,
+    redactor: Redactor,
+    meta: SessionMeta,
+    started_at: String,
+    window_detected: bool,
+    crash_found: bool,
+    exit_code: Option<i32>,
+    exit_type: Option<String>,
+    silent_failure: bool,
+    diagnosis_top: Option<String>,
+    finished: bool,
+}
+
+impl SessionWriter {
+    /// 新建会话（id 由时间 + pid 生成）。
+    pub fn create(sessions_root: &Path, meta: SessionMeta, redactor: Redactor) -> Result<Self> {
+        let session_id = time::make_session_id(time::now(), std::process::id());
+        Self::create_with_id(sessions_root, &session_id, meta, redactor)
+    }
+
+    /// 用指定 id 新建会话（测试与“续写”场景）。
+    pub fn create_with_id(
+        sessions_root: &Path,
+        session_id: &str,
+        meta: SessionMeta,
+        redactor: Redactor,
+    ) -> Result<Self> {
+        let dir = sessions_root.join("game");
+        fs::create_dir_all(&dir).map_err(|source| LaunchError::Io {
+            op: "create_session_dir",
+            path: dir.clone(),
+            source,
+        })?;
+        let path = dir.join(format!("{session_id}.jsonl"));
+        let file = OpenOptions::new()
+            .create(true)
+            .append(true)
+            .open(&path)
+            .map_err(|source| LaunchError::Io {
+                op: "create_session_file",
+                path: path.clone(),
+                source,
+            })?;
+        let clock = SessionClock::start_new();
+        let started_at = clock.started_at_iso();
+        Ok(Self {
+            session_id: session_id.to_string(),
+            clock,
+            file: BufWriter::new(file),
+            path,
+            index_path: session_index::index_path(sessions_root),
+            seq: 0,
+            event_count: 0,
+            redactor,
+            meta,
+            started_at,
+            window_detected: false,
+            crash_found: false,
+            exit_code: None,
+            exit_type: None,
+            silent_failure: false,
+            diagnosis_top: None,
+            finished: false,
+        })
+    }
+
+    /// 会话 id。
+    pub fn session_id(&self) -> &str {
+        &self.session_id
+    }
+
+    /// 事件文件路径。
+    pub fn path(&self) -> &Path {
+        &self.path
+    }
+
+    /// 已写入事件数。
+    pub fn event_count(&self) -> u64 {
+        self.event_count
+    }
+
+    /// 是否已结束。
+    pub fn is_finished(&self) -> bool {
+        self.finished
+    }
+
+    /// 写一条事件。
+    pub fn record(&mut self, kind: EventKind, payload: Value) -> Result<()> {
+        let seq = self.seq;
+        let line = EventLine {
+            v: SCHEMA_VERSION,
+            seq,
+            ts: self.clock.now_iso(),
+            t_ms: self.clock.elapsed_ms(),
+            kind: kind.as_str(),
+            session_id: &self.session_id,
+            payload: &payload,
+        };
+        let serialized = serde_json::to_string(&line).map_err(|err| LaunchError::Session {
+            path: self.path.clone(),
+            reason: err.to_string(),
+        })?;
+        self.file
+            .write_all(serialized.as_bytes())
+            .and_then(|()| self.file.write_all(b"\n"))
+            .and_then(|()| self.file.flush())
+            .map_err(|source| LaunchError::Io {
+                op: "write_session_event",
+                path: self.path.clone(),
+                source,
+            })?;
+        self.seq += 1;
+        self.event_count += 1;
+        Ok(())
+    }
+
+    /// `session_start`。
+    pub fn session_start(&mut self) -> Result<()> {
+        let payload = payload::session_start(&self.meta, SCHEMA_VERSION);
+        self.record(EventKind::SessionStart, payload)
+    }
+
+    /// `cmd_built`：完整 argv（已脱敏）+ classpath 摘要。
+    pub fn cmd_built(&mut self, command: &AssembledCommand) -> Result<()> {
+        let payload = payload::cmd_built(command, &self.redactor);
+        self.record(EventKind::CmdBuilt, payload)
+    }
+
+    /// `assembly_failed`：启动前失败，附结构化缺失清单（M15 据此下结论）。
+    pub fn assembly_failed(&mut self, error: &AssemblyError) -> Result<()> {
+        let payload = payload::assembly_failed(error);
+        self.record(EventKind::AssemblyFailed, payload)
+    }
+
+    /// `proc_start`。
+    pub fn proc_start(&mut self, pid: u32) -> Result<()> {
+        let payload = payload::proc_start(pid, &self.clock.now_iso());
+        self.record(EventKind::ProcStart, payload)
+    }
+
+    /// `natives_extracted`：natives 解压结果（启动期 `UnsatisfiedLinkError` 的第一嫌疑）。
+    pub fn natives_extracted(&mut self, report: &NativesReport) -> Result<()> {
+        let payload = payload::natives_extracted(report, &self.redactor);
+        self.record(EventKind::NativesExtracted, payload)
+    }
+
+    /// `stdout` / `stderr` 行事件。
+    pub fn line(&mut self, line: &LogLine) -> Result<()> {
+        let kind = match line.stream {
+            Stream::Stdout => EventKind::Stdout,
+            Stream::Stderr => EventKind::Stderr,
+        };
+        let text = self.redactor.scrub(&line.text).into_owned();
+        let payload = payload::log_line(&text, line.level());
+        self.record(kind, payload)
+    }
+
+    /// `window_detected`。
+    pub fn window_detected(&mut self, detection: &Detection) -> Result<()> {
+        self.window_detected = true;
+        let payload = payload::window_detected(detection, &self.redactor);
+        self.record(EventKind::WindowDetected, payload)
+    }
+
+    /// 是否已检测到游戏窗口（索引摘要用）。
+    pub fn is_window_detected(&self) -> bool {
+        self.window_detected
+    }
+
+    /// `killed`。
+    pub fn killed(&mut self, by: &str, signal: Option<&str>) -> Result<()> {
+        let payload = payload::killed(by, signal);
+        self.record(EventKind::Killed, payload)
+    }
+
+    /// `exit`。
+    pub fn exit(&mut self, analysis: &ExitAnalysis) -> Result<()> {
+        self.exit_code = Some(analysis.code);
+        self.exit_type = Some(analysis.exit_type.as_str().to_string());
+        self.silent_failure = analysis.silent_failure.is_some();
+        let payload = payload::exit(analysis);
+        self.record(EventKind::Exit, payload)
+    }
+
+    /// `crash_found`：以 `path` 为权威字段（M15 自己读盘）。
+    pub fn crash_found(&mut self, source: &str, path: &Path, excerpt: Option<&str>) -> Result<()> {
+        self.crash_found = true;
+        let payload = payload::crash_found(source, path, excerpt, &self.redactor);
+        self.record(EventKind::CrashFound, payload)
+    }
+
+    /// `diagnosis`：M15 产出的结构化结论，由 launch 脱敏后落盘（单一真相源）。
+    ///
+    /// M15 会按 `crash_found.path` 自己读盘再组 payload，崩溃报告/`latest.log` 里的
+    /// 用户主目录路径与 token 会由此带进结论，所以这里必须再过一遍 [`Redactor`]
+    /// （只改字符串，字段名/数值/布尔不动——`launch-接口约定.md` §9.3）。
+    pub fn diagnosis(&mut self, record: Value) -> Result<()> {
+        let record = self.redactor.scrub_json(&record);
+        if self.diagnosis_top.is_none() {
+            self.diagnosis_top = record
+                .get("candidates")
+                .and_then(Value::as_array)
+                .and_then(|items| items.first())
+                .and_then(|item| item.get("id"))
+                .and_then(Value::as_str)
+                .map(str::to_string);
+        }
+        self.record(EventKind::Diagnosis, record)
+    }
+
+    /// `session_end` + 追加索引，返回索引条目。
+    pub fn finish(&mut self, reason: EndReason) -> Result<SessionIndexEntry> {
+        let duration_ms = self.clock.elapsed_ms();
+        let payload = payload::session_end(reason.as_str(), duration_ms);
+        self.record(EventKind::SessionEnd, payload)?;
+        self.finished = true;
+        let entry = SessionIndexEntry {
+            v: SCHEMA_VERSION,
+            session_id: self.session_id.clone(),
+            instance_id: self.meta.instance_id.clone(),
+            instance_name: self.meta.instance_name.clone(),
+            game_version: self.meta.game_version.clone(),
+            started_at: self.started_at.clone(),
+            ended_at: self.clock.now_iso(),
+            duration_ms,
+            exit_code: self.exit_code,
+            exit_type: self.exit_type.clone(),
+            silent_failure: self.silent_failure,
+            window_detected: self.window_detected,
+            event_count: self.event_count,
+            log_path: format!("game/{}.jsonl", self.session_id),
+            crash_found: self.crash_found,
+            diagnosis_top: self.diagnosis_top.clone(),
+        };
+        session_index::append(&self.index_path, &entry).map_err(|source| LaunchError::Io {
+            op: "append_session_index",
+            path: self.index_path.clone(),
+            source,
+        })?;
+        Ok(entry)
+    }
+}
diff --git a/crates/core/src/launch/session_index.rs b/crates/core/src/launch/session_index.rs
new file mode 100644
index 0000000..4dfc47d
--- /dev/null
+++ b/crates/core/src/launch/session_index.rs
@@ -0,0 +1,120 @@
+//! 会话记录索引：`list_game_sessions` 的数据源。
+//!
+//! 文件：`<sessions_root>/game/index.jsonl`，每会话一行摘要，会话结束时追加。
+//! 读取约定（`DevDocs/SubAgentsTalk/launch-接口约定.md` §2）：同一 `session_id`
+//! 可能出现多行（崩溃后重写索引），读取方**按 id 去重取最后一行**，再按 `started_at` 倒序。
+
+use std::fs::{File, OpenOptions};
+use std::io::{BufRead, BufReader, Write};
+use std::path::{Path, PathBuf};
+
+use serde::{Deserialize, Serialize};
+
+/// 索引条目的 schema 版本。
+pub const INDEX_VERSION: u8 = 1;
+
+/// 一次会话的摘要。
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct SessionIndexEntry {
+    /// schema 版本。
+    #[serde(default)]
+    pub v: u8,
+    /// 会话 id。
+    pub session_id: String,
+    /// 实例 id。
+    pub instance_id: String,
+    /// 实例名。
+    pub instance_name: String,
+    /// 游戏版本。
+    pub game_version: String,
+    /// 开始时间（RFC3339 UTC）。
+    pub started_at: String,
+    /// 结束时间（RFC3339 UTC）。
+    pub ended_at: String,
+    /// 时长毫秒。
+    pub duration_ms: u64,
+    /// 退出码（未跑到进程时为 `None`）。
+    pub exit_code: Option<i32>,
+    /// 退出判定字符串。
+    pub exit_type: Option<String>,
+    /// 是否静默失败。
+    pub silent_failure: bool,
+    /// 是否检测到游戏窗口。
+    pub window_detected: bool,
+    /// 事件条数。
+    pub event_count: u64,
+    /// 相对 `game/` 的日志文件名。
+    pub log_path: String,
+    /// 是否抓到崩溃报告/hs_err。
+    pub crash_found: bool,
+    /// 诊断首因（M15 写入的第一个候选 id）。
+    pub diagnosis_top: Option<String>,
+}
+
+/// 索引文件路径（`<sessions_root>/game/index.jsonl`）。
+pub fn index_path(sessions_root: &Path) -> PathBuf {
+    sessions_root.join("game").join("index.jsonl")
+}
+
+/// 追加一行摘要。
+pub fn append(index: &Path, entry: &SessionIndexEntry) -> std::io::Result<()> {
+    if let Some(parent) = index.parent() {
+        std::fs::create_dir_all(parent)?;
+    }
+    let mut file = OpenOptions::new().create(true).append(true).open(index)?;
+    let line = serde_json::to_string(entry)
+        .map_err(|err| std::io::Error::other(format!("序列化索引失败：{err}")))?;
+    file.write_all(line.as_bytes())?;
+    file.write_all(b"\n")?;
+    file.flush()
+}
+
+/// 读取全部条目（同一 id 取最后一行，按开始时间倒序）。
+pub fn read_all(index: &Path) -> std::io::Result<Vec<SessionIndexEntry>> {
+    let file = match File::open(index) {
+        Ok(file) => file,
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => return Ok(Vec::new()),
+        Err(err) => return Err(err),
+    };
+    let mut entries: Vec<SessionIndexEntry> = Vec::new();
+    for line in BufReader::new(file).lines() {
+        let line = match line {
+            Ok(line) => line,
+            Err(_) => break,
+        };
+        let trimmed = line.trim();
+        if trimmed.is_empty() {
+            continue;
+        }
+        // 容忍坏行（半截 JSON）：索引是“尽力而为”的数据源，不能因为一行坏数据丢掉整份列表。
+        let Ok(entry) = serde_json::from_str::<SessionIndexEntry>(trimmed) else {
+            continue;
+        };
+        match entries
+            .iter_mut()
+            .find(|item| item.session_id == entry.session_id)
+        {
+            Some(slot) => *slot = entry,
+            None => entries.push(entry),
+        }
+    }
+    entries.sort_by(|left, right| right.started_at.cmp(&left.started_at));
+    Ok(entries)
+}
+
+/// `list_game_sessions` 语义：可选实例过滤 + 条数上限，按开始时间倒序。
+pub fn list(
+    index: &Path,
+    limit: usize,
+    instance_id: Option<&str>,
+) -> std::io::Result<Vec<SessionIndexEntry>> {
+    let entries = read_all(index)?;
+    Ok(entries
+        .into_iter()
+        .filter(|entry| match instance_id {
+            Some(id) => entry.instance_id == id,
+            None => true,
+        })
+        .take(limit)
+        .collect())
+}
diff --git a/crates/core/src/launch/session_meta.rs b/crates/core/src/launch/session_meta.rs
new file mode 100644
index 0000000..d56118e
--- /dev/null
+++ b/crates/core/src/launch/session_meta.rs
@@ -0,0 +1,62 @@
+//! 会话元信息（`session_start` 的 payload 来源 + 索引摘要字段）。
+//!
+//! 从 `session.rs` 拆出以守住“单文件 ≤400 行”的硬约束；公开路径仍是
+//! `launch::session::SessionMeta`（在 `session.rs` 里 re-export）。
+
+use crate::launch::platform::PlatformCtx;
+
+/// 会话元信息（`session_start` 的 payload 来源）。
+#[derive(Debug, Clone, Default)]
+pub struct SessionMeta {
+    /// 实例 id。
+    pub instance_id: String,
+    /// 实例名。
+    pub instance_name: String,
+    /// 游戏版本。
+    pub game_version: String,
+    /// 启动器名。
+    pub launcher_name: String,
+    /// 启动器版本。
+    pub launcher_version: String,
+    /// 系统名。
+    pub os_name: String,
+    /// 架构。
+    pub os_arch: String,
+    /// 位数。
+    pub os_bits: u32,
+}
+
+impl SessionMeta {
+    /// 基本构造。
+    pub fn new(
+        instance_id: impl Into<String>,
+        instance_name: impl Into<String>,
+        game_version: impl Into<String>,
+    ) -> Self {
+        Self {
+            instance_id: instance_id.into(),
+            instance_name: instance_name.into(),
+            game_version: game_version.into(),
+            ..Self::default()
+        }
+    }
+
+    /// 补启动器信息。
+    pub fn with_launcher(mut self, name: impl Into<String>, version: impl Into<String>) -> Self {
+        self.launcher_name = name.into();
+        self.launcher_version = version.into();
+        self
+    }
+
+    /// 补平台信息。
+    pub fn with_platform(mut self, ctx: &PlatformCtx) -> Self {
+        self.os_name = ctx.os.manifest_name().to_string();
+        self.os_arch = ctx.arch.clone();
+        self.os_bits = if cfg!(target_pointer_width = "64") {
+            64
+        } else {
+            32
+        };
+        self
+    }
+}
diff --git a/crates/core/src/launch/session_payload.rs b/crates/core/src/launch/session_payload.rs
new file mode 100644
index 0000000..f647a87
--- /dev/null
+++ b/crates/core/src/launch/session_payload.rs
@@ -0,0 +1,159 @@
+//! 会话事件 payload 构造（schema 见 `DevDocs/SubAgentsTalk/launch-接口约定.md` §3）。
+//!
+//! 拆出来是为了让 [`crate::launch::session::SessionWriter`] 只关心“写文件 + seq + 索引”，
+//! 字段定义集中在一处，评审时一眼能对完整张表。
+
+use std::path::Path;
+
+use serde_json::{json, Value};
+
+use crate::launch::args_table::AssembledCommand;
+use crate::launch::error::AssemblyError;
+use crate::launch::exit_analysis::ExitAnalysis;
+use crate::launch::log_level::Level;
+use crate::launch::natives::NativesReport;
+use crate::launch::redact::Redactor;
+use crate::launch::session::SessionMeta;
+use crate::launch::window_detect::Detection;
+
+/// `session_start`。
+pub(crate) fn session_start(meta: &SessionMeta, schema: u8) -> Value {
+    json!({
+        "instance_id": meta.instance_id,
+        "instance_name": meta.instance_name,
+        "game_version": meta.game_version,
+        "launcher": {
+            "name": meta.launcher_name,
+            "version": meta.launcher_version,
+        },
+        "os": {
+            "name": meta.os_name,
+            "arch": meta.os_arch,
+            "bits": meta.os_bits,
+        },
+        "schema": schema,
+    })
+}
+
+/// `cmd_built`：完整 argv（脱敏）+ classpath 摘要 + 组装告警。
+pub(crate) fn cmd_built(command: &AssembledCommand, redactor: &Redactor) -> Value {
+    let argv = redactor.scrub_all(&command.argv());
+    let program = redactor
+        .scrub(&command.program.display().to_string())
+        .into_owned();
+    json!({
+        "program": program,
+        "argv": argv,
+        "main_class": command.main_class,
+        "classpath_entries": command.classpath.len(),
+        "classpath_missing": Vec::<String>::new(),
+        "memory": {
+            "xmx_mb": command.memory.max_mb,
+            "xms_mb": command.memory.min_mb,
+        },
+        "encoding": command.encoding,
+        "warnings": command.warnings.iter().map(ToString::to_string).collect::<Vec<_>>(),
+    })
+}
+
+/// `assembly_failed`：启动前失败的结构化事实（结论由 M15 下）。
+pub(crate) fn assembly_failed(error: &AssemblyError) -> Value {
+    let (code, components) = match error {
+        AssemblyError::MissingMainClass => ("missing_main_class", Vec::new()),
+        AssemblyError::EmptyClasspath => ("empty_classpath", Vec::new()),
+        AssemblyError::EmptyJavaPath => ("empty_java_path", Vec::new()),
+        AssemblyError::MalformedArgument { .. } => ("malformed_argument", Vec::new()),
+        AssemblyError::NativesExtraction { .. } => ("natives_extraction", Vec::new()),
+        AssemblyError::MissingComponents(items) => (
+            "missing_components",
+            items
+                .iter()
+                .map(|item| {
+                    json!({
+                        "name": item.name,
+                        "path": item.path.as_ref().map(|path| path.display().to_string()),
+                    })
+                })
+                .collect::<Vec<_>>(),
+        ),
+    };
+    json!({
+        "error_code": code,
+        "message": error.to_string(),
+        "missing_components": components,
+    })
+}
+
+/// `proc_start`。
+pub(crate) fn proc_start(pid: u32, started_at: &str) -> Value {
+    json!({ "pid": pid, "started_at": started_at })
+}
+
+/// `natives_extracted`：解压事实（`files`/`skipped`/`custom` 是既有约定字段，
+/// 其余为 v1 追加字段，读取方按「未知字段忽略」处理）。
+pub(crate) fn natives_extracted(report: &NativesReport, redactor: &Redactor) -> Value {
+    json!({
+        "dir": redactor.scrub(&report.dir.display().to_string()).into_owned(),
+        "files": report.files,
+        "skipped": report.skipped,
+        "custom": report.custom,
+        "jars": report.jars,
+        "ignored": report.ignored,
+        "up_to_date": report.up_to_date,
+        "era": report.era.as_str(),
+    })
+}
+
+/// `killed`。
+pub(crate) fn killed(by: &str, signal: Option<&str>) -> Value {
+    json!({ "by": by, "signal": signal })
+}
+
+/// `stdout` / `stderr` 行事件。
+pub(crate) fn log_line(text: &str, level: Level) -> Value {
+    json!({ "line": text, "level": level.as_str() })
+}
+
+/// `window_detected`。
+pub(crate) fn window_detected(detection: &Detection, redactor: &Redactor) -> Value {
+    json!({
+        "heuristic": detection.heuristic,
+        "took_ms": detection.took_ms,
+        "evidence": redactor.scrub(&detection.evidence),
+    })
+}
+
+/// `exit`。
+pub(crate) fn exit(analysis: &ExitAnalysis) -> Value {
+    json!({
+        "code": analysis.code,
+        "exit_type": analysis.exit_type.as_str(),
+        "uptime_ms": analysis.uptime_ms,
+        "error_lines": analysis.error_lines,
+        "crash_keywords": analysis.crash_keywords,
+        "jvm_keywords": analysis.jvm_keywords,
+        "silent_failure": analysis.silent_failure.is_some(),
+        "windows_status": analysis.windows_status,
+        "needs_diagnosis": analysis.needs_diagnosis,
+        "summary": analysis.summary(),
+    })
+}
+
+/// `crash_found`：`path` 是权威字段，`excerpt` 仅供人读。
+pub(crate) fn crash_found(
+    source: &str,
+    path: &Path,
+    excerpt: Option<&str>,
+    redactor: &Redactor,
+) -> Value {
+    json!({
+        "source": source,
+        "path": path.display().to_string(),
+        "excerpt": excerpt.map(|text| redactor.scrub(text).into_owned()),
+    })
+}
+
+/// `session_end`。
+pub(crate) fn session_end(reason: &str, duration_ms: u64) -> Value {
+    json!({ "reason": reason, "duration_ms": duration_ms })
+}
diff --git a/crates/core/src/launch/session_sink.rs b/crates/core/src/launch/session_sink.rs
new file mode 100644
index 0000000..712b28e
--- /dev/null
+++ b/crates/core/src/launch/session_sink.rs
@@ -0,0 +1,64 @@
+//! 把会话事件流接到日志泵上：逐行落盘 + 自动窗口出现检测。
+//!
+//! 放在单独文件是为了让 [`crate::launch::session`] 保持“只写事件、只管索引”的单一职责，
+//! 也避免单文件超过 400 行的硬约束。
+
+use std::sync::Mutex;
+
+use crate::launch::pump::{LineSink, LogLine};
+use crate::launch::session::SessionWriter;
+use crate::launch::window_detect::WindowDetector;
+
+/// 会话日志 sink。
+#[derive(Debug)]
+pub struct SessionSink {
+    writer: Mutex<SessionWriter>,
+    detector: Mutex<WindowDetector>,
+}
+
+impl SessionSink {
+    /// 以进程启动时刻为窗口检测起点。
+    pub fn new(writer: SessionWriter) -> Self {
+        Self {
+            writer: Mutex::new(writer),
+            detector: Mutex::new(WindowDetector::new()),
+        }
+    }
+
+    /// 指定窗口检测计时起点（进程 spawn 时刻）。
+    pub fn with_start(writer: SessionWriter, started_at: std::time::Instant) -> Self {
+        Self {
+            writer: Mutex::new(writer),
+            detector: Mutex::new(WindowDetector::with_start(started_at)),
+        }
+    }
+
+    /// 借用写入器（退出分析、结束会话等需要可变访问的场合）。
+    pub fn with_writer<R>(&self, action: impl FnOnce(&mut SessionWriter) -> R) -> Option<R> {
+        self.writer.lock().ok().map(|mut guard| action(&mut guard))
+    }
+
+    /// 是否已检测到游戏窗口。
+    pub fn window_detected(&self) -> bool {
+        match self.writer.lock() {
+            Ok(writer) => writer.is_window_detected(),
+            Err(_) => false,
+        }
+    }
+}
+
+impl LineSink for SessionSink {
+    fn on_line(&self, line: &LogLine) {
+        let detection = match self.detector.lock() {
+            Ok(mut detector) => detector.observe(&line.text),
+            Err(_) => None,
+        };
+        let Ok(mut writer) = self.writer.lock() else {
+            return;
+        };
+        if let Some(detection) = detection {
+            let _ = writer.window_detected(&detection);
+        }
+        let _ = writer.line(line);
+    }
+}
diff --git a/crates/core/src/launch/sink.rs b/crates/core/src/launch/sink.rs
new file mode 100644
index 0000000..8b5809a
--- /dev/null
+++ b/crates/core/src/launch/sink.rs
@@ -0,0 +1,138 @@
+//! 日志 sink 组合：把同一个进程的输出同时喂给多个消费者。
+//!
+//! 设计依据 `DevDocs/SubAgentsTalk/launch-接口约定.md` §3（单一真相源）与 tower 批复的
+//! “复合 sink”方案：会话事件流（落盘）是必需的一个 sink，M15 采集器 / UI 日志页 /
+//! 测试断言各自挂自己的 sink，彼此不感知。
+//!
+//! 接 M15 的姿态：diagnose 不解析 jsonl、也不 import launch 类型，所以它只需要一个
+//! `FnSink` 包一层 `LogBuffer::push(stream, line)`；这里只提供通用的组合原语。
+
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::Arc;
+
+use crate::launch::pump::{LineSink, LogLine, Stream};
+
+/// 把一条日志广播给多个 sink（顺序 = 注册顺序）。
+#[derive(Default)]
+pub struct CompositeSink {
+    sinks: Vec<Arc<dyn LineSink>>,
+}
+
+impl CompositeSink {
+    /// 空组合。
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// 追加一个 sink（builder 风格）。
+    pub fn with(mut self, sink: Arc<dyn LineSink>) -> Self {
+        self.sinks.push(sink);
+        self
+    }
+
+    /// 追加一个 sink。
+    pub fn push(&mut self, sink: Arc<dyn LineSink>) {
+        self.sinks.push(sink);
+    }
+
+    /// 已注册的 sink 数。
+    pub fn len(&self) -> usize {
+        self.sinks.len()
+    }
+
+    /// 是否为空。
+    pub fn is_empty(&self) -> bool {
+        self.sinks.is_empty()
+    }
+}
+
+impl std::fmt::Debug for CompositeSink {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("CompositeSink")
+            .field("sinks", &self.sinks.len())
+            .finish()
+    }
+}
+
+impl LineSink for CompositeSink {
+    fn on_line(&self, line: &LogLine) {
+        for sink in &self.sinks {
+            sink.on_line(line);
+        }
+    }
+}
+
+/// 闭包 sink：把 M15 采集器、UI 通道、测试断言接进来的最轻方式。
+///
+/// ```ignore
+/// let sink = FnSink::new(move |line: &LogLine| {
+///     bundle.log.push(stream_kind(line.stream), &line.text);
+/// });
+/// ```
+pub struct FnSink<F: Fn(&LogLine) + Send + Sync> {
+    action: F,
+}
+
+impl<F: Fn(&LogLine) + Send + Sync> FnSink<F> {
+    /// 用闭包构造。
+    pub fn new(action: F) -> Self {
+        Self { action }
+    }
+}
+
+impl<F: Fn(&LogLine) + Send + Sync + 'static> FnSink<F> {
+    /// 转成 `Arc<dyn LineSink>`（可直接塞进 [`CompositeSink`] / `RunningProcess`）。
+    pub fn shared(self) -> Arc<dyn LineSink> {
+        Arc::new(self)
+    }
+}
+
+impl<F: Fn(&LogLine) + Send + Sync> std::fmt::Debug for FnSink<F> {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str("FnSink")
+    }
+}
+
+impl<F: Fn(&LogLine) + Send + Sync> LineSink for FnSink<F> {
+    fn on_line(&self, line: &LogLine) {
+        (self.action)(line);
+    }
+}
+
+/// 计数 sink：给进度条/测试一个“已收多少行”的廉价探针。
+#[derive(Debug, Default)]
+pub struct CountingSink {
+    stdout: AtomicU64,
+    stderr: AtomicU64,
+}
+
+impl CountingSink {
+    /// 新计数器。
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// 标准输出行数。
+    pub fn stdout_lines(&self) -> u64 {
+        self.stdout.load(Ordering::Relaxed)
+    }
+
+    /// 标准错误行数。
+    pub fn stderr_lines(&self) -> u64 {
+        self.stderr.load(Ordering::Relaxed)
+    }
+
+    /// 总行数。
+    pub fn total_lines(&self) -> u64 {
+        self.stdout_lines() + self.stderr_lines()
+    }
+}
+
+impl LineSink for CountingSink {
+    fn on_line(&self, line: &LogLine) {
+        match line.stream {
+            Stream::Stdout => self.stdout.fetch_add(1, Ordering::Relaxed),
+            Stream::Stderr => self.stderr.fetch_add(1, Ordering::Relaxed),
+        };
+    }
+}
diff --git a/crates/core/src/launch/time.rs b/crates/core/src/launch/time.rs
new file mode 100644
index 0000000..39f1ead
--- /dev/null
+++ b/crates/core/src/launch/time.rs
@@ -0,0 +1,118 @@
+//! 时间工具：RFC3339（毫秒，UTC）格式化与会话时钟。
+//!
+//! 会话事件流的 `ts` / `t_ms` 字段由这里产出（schema 见
+//! `DevDocs/SubAgentsTalk/launch-接口约定.md` §2）。
+//! 只用 `std::time`，不引入 chrono/time 依赖。
+
+use std::time::{Instant, SystemTime, UNIX_EPOCH};
+
+/// 把 `SystemTime` 格式化成 RFC3339 UTC 毫秒精度串，例 `2026-10-29T12:45:01.123Z`。
+///
+/// 早于 Unix 纪元的时间按纪元处理（不会 panic：事件流宁可有 1970 的时间戳也不能丢事件）。
+pub fn format_rfc3339_millis(time: SystemTime) -> String {
+    let since_epoch = time.duration_since(UNIX_EPOCH).unwrap_or_default();
+    let secs = since_epoch.as_secs();
+    let millis = since_epoch.subsec_millis();
+    let days = i64::try_from(secs / 86_400).unwrap_or(i64::MAX);
+    let secs_of_day = secs % 86_400;
+    let (year, month, day) = civil_from_days(days);
+    let hour = secs_of_day / 3_600;
+    let minute = (secs_of_day % 3_600) / 60;
+    let second = secs_of_day % 60;
+    format!("{year:04}-{month:02}-{day:02}T{hour:02}:{minute:02}:{second:02}.{millis:03}Z")
+}
+
+/// 当前墙上时间（便于测试替换的单一入口）。
+pub fn now() -> SystemTime {
+    SystemTime::now()
+}
+
+/// 由“自 1970-01-01 起的天数”还原公历年月日（Howard Hinnant 的 civil_from_days）。
+pub fn civil_from_days(days: i64) -> (i64, u32, u32) {
+    let z = days + 719_468;
+    let era = if z >= 0 { z } else { z - 146_096 } / 146_097;
+    let doe = z - era * 146_097;
+    let yoe = (doe - doe / 1_460 + doe / 36_524 - doe / 146_096) / 365;
+    let year = yoe + era * 400;
+    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
+    let mp = (5 * doy + 2) / 153;
+    let day = doy - (153 * mp + 2) / 5 + 1;
+    let month = if mp < 10 { mp + 3 } else { mp - 9 };
+    let year = if month <= 2 { year + 1 } else { year };
+    (
+        year,
+        u32::try_from(month).unwrap_or(1),
+        u32::try_from(day).unwrap_or(1),
+    )
+}
+
+/// 会话时钟：同时记录单调时刻（`t_ms`）与墙上时刻（`ts`）。
+#[derive(Debug, Clone)]
+pub struct SessionClock {
+    start_instant: Instant,
+    started_at: SystemTime,
+}
+
+impl SessionClock {
+    /// 以“现在”为起点创建时钟。
+    pub fn start_new() -> Self {
+        Self {
+            start_instant: Instant::now(),
+            started_at: now(),
+        }
+    }
+
+    /// 用给定的墙上时间与单调时刻创建（测试可注入）。
+    pub fn started_at(start_instant: Instant, started_at: SystemTime) -> Self {
+        Self {
+            start_instant,
+            started_at,
+        }
+    }
+
+    /// 会话开始的墙上时间。
+    pub fn started_at_wall(&self) -> SystemTime {
+        self.started_at
+    }
+
+    /// 会话开始时刻的 RFC3339 串。
+    pub fn started_at_iso(&self) -> String {
+        format_rfc3339_millis(self.started_at)
+    }
+
+    /// 距会话开始的毫秒数（`t_ms`）。
+    pub fn elapsed_ms(&self) -> u64 {
+        u64::try_from(self.start_instant.elapsed().as_millis()).unwrap_or(u64::MAX)
+    }
+
+    /// 当前墙上时间的 RFC3339 串（`ts`）。
+    pub fn now_iso(&self) -> String {
+        format_rfc3339_millis(now())
+    }
+}
+
+impl Default for SessionClock {
+    fn default() -> Self {
+        Self::start_new()
+    }
+}
+
+/// 生成会话 id：`YYYYMMDDTHHMMSS-<6 位十六进制>`。
+///
+/// 十六进制段由墙上时间与 pid 混合而来——不引入 rand 依赖，同一秒同一进程内也能区分
+/// （调用方可在冲突时追加序号）。
+pub fn make_session_id(wall: SystemTime, pid: u32) -> String {
+    let since_epoch = wall.duration_since(UNIX_EPOCH).unwrap_or_default();
+    let secs = since_epoch.as_secs();
+    let days = i64::try_from(secs / 86_400).unwrap_or(i64::MAX);
+    let (year, month, day) = civil_from_days(days);
+    let secs_of_day = secs % 86_400;
+    let hour = secs_of_day / 3_600;
+    let minute = (secs_of_day % 3_600) / 60;
+    let second = secs_of_day % 60;
+    let mut hash: u64 = u64::from(since_epoch.subsec_nanos()).wrapping_add(u64::from(pid));
+    hash ^= secs.rotate_left(17);
+    hash = hash.wrapping_mul(0x9E37_79B9_7F4A_7C15);
+    let suffix = (hash >> 40) & 0xFF_FFFF;
+    format!("{year:04}{month:02}{day:02}T{hour:02}{minute:02}{second:02}-{suffix:06x}")
+}
diff --git a/crates/core/src/launch/tree_kill.rs b/crates/core/src/launch/tree_kill.rs
new file mode 100644
index 0000000..278a0ba
--- /dev/null
+++ b/crates/core/src/launch/tree_kill.rs
@@ -0,0 +1,195 @@
+//! 进程树回收：`SIGTERM → 宽限 → SIGKILL` 三段式关闭。
+//!
+//! HMCL 只 `process.destroy()` 单进程（`analyse/02` §6.8），子进程会残留、日志尾部丢失。
+//! 这里做进程**树**回收：
+//!
+//! - Windows：`taskkill /T /F /PID`（`/T` 递归子树）。P0 不引入 `windows-sys`，因此没有
+//!   Job Object——Job Object（`JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`）留 P1，替换点就在本文件
+//!   （tower 已批准，见 `launch-接口约定.md` §7-1）。
+//! - POSIX：子进程由 [`crate::launch::process`] 用 `CommandExt::process_group(0)` 放进**自己的**
+//!   进程组（与 Windows 的 `CREATE_NEW_PROCESS_GROUP` 对称，std 1.64+ 的安全 API），因此
+//!   `kill -TERM -- -<pgid>` 一次覆盖整棵子树 → 宽限 → `kill -KILL -- -<pgid>`，再补一发单 pid。
+//!
+//! 两个平台都先尝试“温和”，宽限期后再“强制”。
+//!
+//! # 两条来自 CI 的硬约束
+//!
+//! 1. **组杀必须先验组**（[`group_kill_target`]）：目标进程必须是它自己进程组的**组长**，
+//!    且该组不能是我们所在的组。否则一次 `kill -- -<pgid>` 会把测试进程（CI 容器里全体进程
+//!    常常共用 pgid 1）一起带走——M48 之前 `test (ubuntu-latest)` 就是这么被 SIGTERM 打断的。
+//!    验不过就只发单 pid。
+//! 2. **`--` 不能省**：procps-ng 的 `kill` 会把裸 `-<pgid>` 当成又一个信号选项吞掉，**退出码 0
+//!    却什么都没发**（procps-ng 4.0.2 实测）。旧实现把这种“假成功”当组杀成功直接返回，
+//!    于是单 pid 兜底永远不执行，`stop()` 只能干等超时——`stop_kills_process_tree` 与
+//!    `pipeline_stop_records_killed_exit` 两条红灯的真正死因。
+//!
+//! ⚠️ 外部命令的退出码**不能**用来判断“进程是否已被结束”：温和阶段成功关掉进程后，
+//! 再发 `taskkill /F` 会得到 128（“没有这个运行实例”）。所以 [`crate::launch::process`]
+//! 的实际停止流程以“进程是否真的消失”为准（`try_wait` 轮询），本模块只提供发送动作。
+
+use std::io;
+use std::process::Command;
+
+/// 温和关闭（Windows 无 `/F`；POSIX `SIGTERM`）。
+pub fn terminate(pid: u32) -> io::Result<()> {
+    check_pid(pid)?;
+    imp::signal(pid, false)
+}
+
+/// 强制关闭（Windows `/F`；POSIX `SIGKILL`），并尽量覆盖整棵进程树。
+pub fn force_kill(pid: u32) -> io::Result<()> {
+    check_pid(pid)?;
+    imp::signal(pid, true)
+}
+
+/// 三段式：温和 → 宽限 → 强制。返回**强制阶段**的结果（温和阶段失败不致命）。
+///
+/// 注意：返回值不代表“进程已经死了”（见模块注释）。需要准确判定请用
+/// [`crate::launch::process::RunningProcess::stop`]。
+pub fn kill_tree(pid: u32, grace: std::time::Duration) -> io::Result<()> {
+    check_pid(pid)?;
+    let _ = terminate(pid);
+    if !grace.is_zero() {
+        std::thread::sleep(grace);
+    }
+    force_kill(pid)
+}
+
+/// `pid` 0 意味着“当前进程组”（POSIX `kill` 的 `-0`）——绝不能顺手发出去。
+fn check_pid(pid: u32) -> io::Result<()> {
+    if pid == 0 {
+        return Err(io::Error::new(
+            io::ErrorKind::InvalidInput,
+            "无效的 pid 0：拒绝向当前进程组发信号",
+        ));
+    }
+    Ok(())
+}
+
+/// 允许组杀的进程组号；`None` = 只能发单 pid。
+///
+/// 三重校验，任一不过就退回单 pid：
+/// 1. 目标必须是它自己进程组的组长（`pgid == pid`）——否则 `-<pgid>` 指的不是“它的”子树；
+/// 2. 必须能读到我们自己所在的进程组；
+/// 3. 目标组不能就是我们所在的组——否则信号会打到自己人身上。
+#[cfg(unix)]
+pub fn group_kill_target(pid: u32) -> Option<u32> {
+    if pid == 0 {
+        return None;
+    }
+    let target = pgid_of(pid)?;
+    if target != pid {
+        return None;
+    }
+    let own = pgid_of(std::process::id())?;
+    (target != own).then_some(target)
+}
+
+/// 读 `pid` 所在进程组号。Linux 走 `/proc`，其它 POSIX 用 `ps`；读不到就是 `None`（不发组杀）。
+#[cfg(target_os = "linux")]
+fn pgid_of(pid: u32) -> Option<u32> {
+    // `/proc/<pid>/stat`: `pid (comm) state ppid pgrp ...`，`comm` 可能含空格和括号，
+    // 所以从**最后一个** `)` 之后开始数字段。
+    let stat = std::fs::read_to_string(format!("/proc/{pid}/stat")).ok()?;
+    let tail = &stat[stat.rfind(')')? + 1..];
+    let mut fields = tail.split_whitespace();
+    fields.next()?; // state
+    fields.next()?; // ppid
+    fields.next()?.parse().ok() // pgrp
+}
+
+#[cfg(all(unix, not(target_os = "linux")))]
+fn pgid_of(pid: u32) -> Option<u32> {
+    let output = Command::new("ps")
+        .args(["-o", "pgid=", "-p", &pid.to_string()])
+        .output()
+        .ok()?;
+    if !output.status.success() {
+        return None;
+    }
+    String::from_utf8_lossy(&output.stdout).trim().parse().ok()
+}
+
+#[cfg(windows)]
+mod imp {
+    use super::*;
+    use std::os::windows::process::CommandExt;
+
+    /// 不弹控制台窗口（否则 kill 子进程会闪一个黑框）。
+    const CREATE_NO_WINDOW: u32 = 0x0800_0000;
+
+    pub(super) fn signal(pid: u32, force: bool) -> io::Result<()> {
+        let mut command = Command::new("taskkill");
+        command.arg("/PID").arg(pid.to_string()).arg("/T");
+        if force {
+            command.arg("/F");
+        }
+        command.creation_flags(CREATE_NO_WINDOW);
+        let status = command
+            .stdout(std::process::Stdio::null())
+            .stderr(std::process::Stdio::null())
+            .status()?;
+        if status.success() {
+            Ok(())
+        } else {
+            // taskkill 对已退出的进程返回非 0，这不值得中断关闭流程。
+            Err(io::Error::other(format!("taskkill 退出码 {status}")))
+        }
+    }
+}
+
+#[cfg(unix)]
+mod imp {
+    use super::*;
+
+    pub(super) fn signal(pid: u32, force: bool) -> io::Result<()> {
+        let flag = if force { "-KILL" } else { "-TERM" };
+        let mut delivered = false;
+        // 验过的独立进程组：一次覆盖组长 + 它的全部后代。
+        if let Some(pgid) = group_kill_target(pid) {
+            let group = format!("-{pgid}");
+            delivered |= run_kill(flag, &["--", &group])?;
+        }
+        // 单 pid 兜底永远执行：组杀不可用/进程已不在组里时靠它。
+        let single = pid.to_string();
+        delivered |= run_kill(flag, &[&single])?;
+        if delivered {
+            Ok(())
+        } else {
+            // 常见于“进程已经退出”，不值得中断关闭流程；但绝不谎报成功。
+            Err(io::Error::other(format!(
+                "kill {flag} {pid} 没有送达（进程可能已退出）"
+            )))
+        }
+    }
+
+    /// 发一发 `kill <flag> <args...>`，返回是否送达。
+    ///
+    /// `kill` 不存在时给**明确**错误而不是静默失败：否则调用方只会看到“进程仍在运行”，
+    /// 排查方向会被带偏（M48 之前的红灯就是这么来的）。
+    fn run_kill(flag: &str, args: &[&str]) -> io::Result<bool> {
+        match Command::new("kill")
+            .arg(flag)
+            .args(args)
+            .stdout(std::process::Stdio::null())
+            .stderr(std::process::Stdio::null())
+            .status()
+        {
+            Ok(status) => Ok(status.success()),
+            Err(err) if err.kind() == io::ErrorKind::NotFound => Err(io::Error::new(
+                io::ErrorKind::NotFound,
+                "找不到 kill 命令：POSIX 进程树回收依赖 procps（Linux）或系统自带 kill（macOS/BSD）",
+            )),
+            Err(err) => Err(err),
+        }
+    }
+}
+
+#[cfg(not(any(windows, unix)))]
+mod imp {
+    use super::*;
+
+    pub(super) fn signal(_pid: u32, _force: bool) -> io::Result<()> {
+        Err(io::Error::other("当前平台不支持进程树 kill"))
+    }
+}
diff --git a/crates/core/src/launch/watchdog.rs b/crates/core/src/launch/watchdog.rs
new file mode 100644
index 0000000..745ef53
--- /dev/null
+++ b/crates/core/src/launch/watchdog.rs
@@ -0,0 +1,71 @@
+//! 看门狗：给 pump 的 join 加超时。
+//!
+//! HMCL 的 `ExitWaiter` 在 `waitFor()` 之后无条件 `join` 两条泵线程
+//! （`analyse/02` §6.1、§8.5）：若子进程自己不关闭 stdout（例如它又拉起了不退出的
+//! 子进程），`onExit` 永远不回调，UI 卡在“正在启动”。这里把“等日志落盘”改成
+//! 有预算的等待——超时就带着已收集到的日志继续做退出分析，绝不无限等待。
+
+use std::time::Duration;
+
+use crate::launch::pump::{PumpCompletion, PumpGroup, Stream};
+
+/// 看门狗配置。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct WatchdogConfig {
+    /// 进程退出后等待日志泵结束的预算。
+    pub pump_timeout: Duration,
+}
+
+impl Default for WatchdogConfig {
+    fn default() -> Self {
+        Self {
+            pump_timeout: Duration::from_secs(10),
+        }
+    }
+}
+
+/// 看门狗判定。
+#[derive(Debug, Clone)]
+pub enum PumpVerdict {
+    /// 两条流都正常结束。
+    Complete(PumpCompletion),
+    /// 超时：仍有流未结束（附带是哪几条）。
+    Stalled {
+        /// 等待结果（含已完成流与行数）。
+        completion: PumpCompletion,
+        /// 卡住的流。
+        streams: Vec<Stream>,
+        /// 等待了多久。
+        waited: Duration,
+    },
+}
+
+impl PumpVerdict {
+    /// 是否一切正常。
+    pub fn is_complete(&self) -> bool {
+        matches!(self, Self::Complete(_))
+    }
+
+    /// 等待结果（两种情形都有）。
+    pub fn completion(&self) -> &PumpCompletion {
+        match self {
+            Self::Complete(completion) => completion,
+            Self::Stalled { completion, .. } => completion,
+        }
+    }
+}
+
+/// 用配置里的预算等待日志泵结束。
+pub fn wait_for_pumps(group: &mut PumpGroup, config: &WatchdogConfig) -> PumpVerdict {
+    let completion = group.wait(config.pump_timeout);
+    if completion.is_complete() {
+        PumpVerdict::Complete(completion)
+    } else {
+        let streams = completion.stalled.clone();
+        PumpVerdict::Stalled {
+            completion,
+            streams,
+            waited: config.pump_timeout,
+        }
+    }
+}
diff --git a/crates/core/src/launch/window_detect.rs b/crates/core/src/launch/window_detect.rs
new file mode 100644
index 0000000..1a1a667
--- /dev/null
+++ b/crates/core/src/launch/window_detect.rs
@@ -0,0 +1,86 @@
+//! “游戏窗口是否出现”的检测（日志启发式）。
+//!
+//! HMCL 只看两条小写子串（`analyse/02` §6.5：`lwjgl version` / `lwjgl openal`），
+//! 换日志格式就失效。v1 保持同样的启发式但做成**可扩展模式表 + 命中证据 + 耗时**，
+//! 这样 `window_detected` 事件能告诉 AI“靠哪一行判定的、花了多久”；
+//! 进程/窗口级信号（Windows `EnumWindows` 按 PID）留 P1（`PlanDoc/06` §1 升级点 3）。
+
+use std::time::Instant;
+
+/// 一次成功检测。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Detection {
+    /// 启发式名称（事件流 `window_detected.heuristic`）。
+    pub heuristic: String,
+    /// 从进程启动到命中的毫秒数。
+    pub took_ms: u64,
+    /// 命中的日志行（事件流 `evidence`）。
+    pub evidence: String,
+}
+
+/// 启发式模式表：（小写子串，启发式名称）。
+pub const HEURISTICS: &[(&str, &str)] = &[
+    ("lwjgl version", "lwjgl_version"),
+    ("lwjgl openal", "lwjgl_openal"),
+    ("sound engine started", "sound_engine"),
+];
+
+/// 窗口检测器。
+#[derive(Debug, Clone)]
+pub struct WindowDetector {
+    started_at: Instant,
+    detection: Option<Detection>,
+}
+
+impl WindowDetector {
+    /// 以“现在”为计时起点。
+    pub fn new() -> Self {
+        Self {
+            started_at: Instant::now(),
+            detection: None,
+        }
+    }
+
+    /// 指定计时起点（进程 spawn 时刻）。
+    pub fn with_start(started_at: Instant) -> Self {
+        Self {
+            started_at,
+            detection: None,
+        }
+    }
+
+    /// 观察一行日志；首次命中返回检测结果。
+    pub fn observe(&mut self, line: &str) -> Option<Detection> {
+        if self.detection.is_some() {
+            return None;
+        }
+        let lower = line.to_ascii_lowercase();
+        let (needle, name) = HEURISTICS
+            .iter()
+            .find(|(needle, _)| lower.contains(needle))?;
+        let _ = needle;
+        let detection = Detection {
+            heuristic: (*name).to_string(),
+            took_ms: u64::try_from(self.started_at.elapsed().as_millis()).unwrap_or(u64::MAX),
+            evidence: line.trim().to_string(),
+        };
+        self.detection = Some(detection.clone());
+        Some(detection)
+    }
+
+    /// 是否已经检测到窗口。
+    pub fn is_detected(&self) -> bool {
+        self.detection.is_some()
+    }
+
+    /// 检测结果。
+    pub fn detection(&self) -> Option<&Detection> {
+        self.detection.as_ref()
+    }
+}
+
+impl Default for WindowDetector {
+    fn default() -> Self {
+        Self::new()
+    }
+}
diff --git a/crates/core/src/lib.rs b/crates/core/src/lib.rs
new file mode 100644
index 0000000..16966bf
--- /dev/null
+++ b/crates/core/src/lib.rs
@@ -0,0 +1,24 @@
+//! Unlucky-Launcher 领域库（`unlucky_core`）。
+//!
+//! 本 crate **零 UI 依赖**：UI 框架（Slint）只允许出现在 `crates/app`。
+//! 这是对 HMCL「HMCLCore 34 处 import javafx」架构债的正面修正，
+//! 由 `.github/workflows/guards.yml` 的 `core-no-ui` job 在 CI 守门。
+//!
+//! core 对 UI 的回调只有三条通道（见 `DevDocs/PlanDoc/01-tech-stack-and-architecture.md` §3）：
+//! 1. 不可变快照发布；2. 事件流（启动/下载/诊断 JSONL 事件）；3. 注入的显示服务接口（进度/确认）。
+//!
+//! 设计定稿索引：`DevDocs/PlanDoc/00-master-architecture.md`。
+//! 各模块的设计文档在对应 `mod.rs` 的模块注释里点名。
+//!
+//! 当前状态：P0 脚手架，只有模块骨架与设计注释，实现按 M12–M15/M18 分批落地。
+
+#![forbid(unsafe_code)]
+
+pub mod addon;
+pub mod auth;
+pub mod diagnose;
+pub mod download;
+pub mod game;
+pub mod launch;
+pub mod platform;
+pub mod setting;
diff --git a/crates/core/src/platform/atomic.rs b/crates/core/src/platform/atomic.rs
new file mode 100644
index 0000000..9448a84
--- /dev/null
+++ b/crates/core/src/platform/atomic.rs
@@ -0,0 +1,79 @@
+//! 原子写：临时文件 → fsync → rename。
+//!
+//! 出处：`DevDocs/analyse/07-settings-packaging-update.md` §1.6（HMCL `FileUtils.saveSafely`：
+//! 写 tmp + `Files.move(REPLACE_EXISTING)`）。配置与下载落盘都该走这里，禁止直接 `fs::write`。
+//!
+//! `std::fs::rename` 在 Unix 与 Windows 上都是「替换式」语义
+//! （Windows 侧 std 用 `MoveFileExW(MOVEFILE_REPLACE_EXISTING)`），因此不需要先删目标文件。
+
+use std::io::{self, Write};
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use super::error::{io_at, PlatformError, PlatformResult};
+
+/// 同进程内的 tmp 名去重计数器。
+static TMP_COUNTER: AtomicU64 = AtomicU64::new(0);
+
+/// 原子地把 `bytes` 写到 `path`（父目录不存在会创建）。
+///
+/// # Errors
+/// 建目录、写临时文件、fsync、rename 任一步失败都返回 [`PlatformError::Io`]，
+/// 且失败时会尽力清理临时文件，不留垃圾。
+pub fn write_atomic(path: &Path, bytes: &[u8]) -> PlatformResult<()> {
+    let parent = path.parent().unwrap_or_else(|| Path::new(""));
+    if !parent.as_os_str().is_empty() {
+        std::fs::create_dir_all(parent).map_err(io_at(parent))?;
+    }
+
+    let tmp = tmp_path(path);
+    let write_result = (|| -> io::Result<()> {
+        let mut file = std::fs::File::create(&tmp)?;
+        file.write_all(bytes)?;
+        file.sync_all()?;
+        Ok(())
+    })();
+    if let Err(source) = write_result {
+        std::fs::remove_file(&tmp).ok();
+        return Err(PlatformError::Io { path: tmp, source });
+    }
+
+    if let Err(source) = std::fs::rename(&tmp, path) {
+        std::fs::remove_file(&tmp).ok();
+        return Err(PlatformError::Io {
+            path: path.to_path_buf(),
+            source,
+        });
+    }
+    Ok(())
+}
+
+/// 读文件；不存在返回 `None`，其它错误照原样上报（用于区分「没配过」和「读不了」）。
+///
+/// # Errors
+/// 除 `NotFound` 以外的读失败返回 [`PlatformError::Io`]。
+pub fn read_optional(path: &Path) -> PlatformResult<Option<Vec<u8>>> {
+    match std::fs::read(path) {
+        Ok(bytes) => Ok(Some(bytes)),
+        Err(source) if source.kind() == io::ErrorKind::NotFound => Ok(None),
+        Err(source) => Err(PlatformError::Io {
+            path: path.to_path_buf(),
+            source,
+        }),
+    }
+}
+
+/// 同目录下的临时文件名（`launcher.json` → `launcher.json.tmp<pid>-<n>`）。
+#[must_use]
+pub fn tmp_path(path: &Path) -> PathBuf {
+    let counter = TMP_COUNTER.fetch_add(1, Ordering::Relaxed);
+    let name = path.file_name().map_or_else(
+        || String::from("ull"),
+        |name| name.to_string_lossy().into_owned(),
+    );
+    let tmp_name = format!(".{name}.tmp{}-{counter}", std::process::id());
+    match path.parent() {
+        Some(parent) => parent.join(tmp_name),
+        None => PathBuf::from(tmp_name),
+    }
+}
diff --git a/crates/core/src/platform/data_dir.rs b/crates/core/src/platform/data_dir.rs
new file mode 100644
index 0000000..f1ca7b0
--- /dev/null
+++ b/crates/core/src/platform/data_dir.rs
@@ -0,0 +1,235 @@
+//! 三模式数据目录解析（Portable 默认 / Standard / Custom）。
+//!
+//! 设计出处：`DevDocs/PlanDoc/04-data-and-config.md` §1——
+//! 用户原话定案：「1.默认在运行目录下生成 .ULL .minecraft 目录 2.设置内可以更改到标准的用户应用数据目录
+//! 3.用户可手动指定数据目录」。
+//!
+//! 附加约束：`.ULL` 与 `.minecraft` 同根但**可分离**（`launcher_home` / `game_home` 覆盖项），
+//! macOS `.app` 只读所以默认走 Standard。
+
+use std::fmt;
+use std::path::PathBuf;
+
+use serde::{Deserialize, Serialize};
+
+use super::error::{PlatformError, PlatformResult};
+use super::layout::{GAME_HOME_DIR, LAUNCHER_HOME_DIR};
+use super::paths::{self, EnvSource, Platform, ProcessEnv};
+use super::redirect;
+
+/// 数据目录三模式。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum DataMode {
+    /// exe 运行目录下生成 `.ULL/` 与 `.minecraft/`（首次运行的默认）。
+    #[default]
+    Portable,
+    /// 各 OS 标准应用数据目录。
+    Standard,
+    /// 用户手动指定目录。
+    Custom,
+}
+
+impl DataMode {
+    /// 稳定名（写进 launcher.json 与日志）。
+    #[must_use]
+    pub const fn as_str(&self) -> &'static str {
+        match self {
+            Self::Portable => "portable",
+            Self::Standard => "standard",
+            Self::Custom => "custom",
+        }
+    }
+
+    /// 从配置字符串解析。
+    #[must_use]
+    pub fn parse(text: &str) -> Option<Self> {
+        match text {
+            "portable" => Some(Self::Portable),
+            "standard" => Some(Self::Standard),
+            "custom" => Some(Self::Custom),
+            _ => None,
+        }
+    }
+
+    /// 该平台的默认模式：macOS 的 `.app` 内是只读的 → 默认 Standard（§1 细节）。
+    #[must_use]
+    pub const fn default_for(platform: Platform) -> Self {
+        match platform {
+            Platform::MacOs => Self::Standard,
+            _ => Self::Portable,
+        }
+    }
+}
+
+impl fmt::Display for DataMode {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+/// 设置里关于数据目录的原始输入。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct DataDirRequest {
+    /// 三模式。
+    pub mode: DataMode,
+    /// Custom 模式的根目录（必须绝对路径）。
+    pub custom_root: Option<PathBuf>,
+    /// 高级：显式覆盖启动器数据目录（`.ULL` 的等价物）。
+    pub launcher_home: Option<PathBuf>,
+    /// 高级：游戏目录与数据目录分离指定（整合包用户：游戏在 D 盘，配置在用户目录）。
+    pub game_home: Option<PathBuf>,
+}
+
+/// 解析结果：实际生效的两个 home。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ResolvedData {
+    /// 生效模式。
+    pub mode: DataMode,
+    /// 启动器数据目录（四分区之家）。
+    pub launcher_home: PathBuf,
+    /// 游戏目录（`.minecraft`）。
+    pub game_home: PathBuf,
+    /// 经 `redirect.json` 跳转时的原始目录（未跳转为 `None`）。
+    pub redirected_from: Option<PathBuf>,
+}
+
+impl ResolvedData {
+    /// 生效的启动器布局视图。
+    #[must_use]
+    pub fn layout(&self) -> super::layout::LauncherLayout {
+        super::layout::LauncherLayout::new(self.launcher_home.clone())
+    }
+
+    /// 是否和另一份解析结果指向同一组目录（迁移判定用）。
+    #[must_use]
+    pub fn same_target(&self, other: &Self) -> bool {
+        self.launcher_home == other.launcher_home && self.game_home == other.game_home
+    }
+}
+
+/// 三模式解析器。环境与 exe 目录都可注入，单测里能确定性地覆盖各 OS 落点。
+pub struct Resolver<'env> {
+    platform: Platform,
+    exe_dir: Option<PathBuf>,
+    env: &'env dyn EnvSource,
+}
+
+impl Resolver<'static> {
+    /// 用真实进程环境构造。
+    #[must_use]
+    pub fn new(platform: Platform, exe_dir: Option<PathBuf>) -> Self {
+        Self {
+            platform,
+            exe_dir,
+            env: &ProcessEnv,
+        }
+    }
+}
+
+impl<'env> Resolver<'env> {
+    /// 注入环境来源（测试 / 便携化封装）。
+    #[must_use]
+    pub fn with_env(
+        platform: Platform,
+        exe_dir: Option<PathBuf>,
+        env: &'env dyn EnvSource,
+    ) -> Self {
+        Self {
+            platform,
+            exe_dir,
+            env,
+        }
+    }
+
+    /// 平台。
+    #[must_use]
+    pub const fn platform(&self) -> Platform {
+        self.platform
+    }
+
+    /// 该平台的默认模式。
+    #[must_use]
+    pub const fn default_mode(&self) -> DataMode {
+        DataMode::default_for(self.platform)
+    }
+
+    /// 按三模式解析出实际目录（不跟随 `redirect.json`）。
+    ///
+    /// # Errors
+    /// Portable 拿不到 exe 目录、Standard 拿不到标准目录、Custom 没给绝对路径时返回错误。
+    pub fn resolve(&self, request: &DataDirRequest) -> PlatformResult<ResolvedData> {
+        let (launcher_home, game_home) = match request.mode {
+            DataMode::Portable => {
+                let exe_dir = self.exe_dir.clone().ok_or(PlatformError::NoExecutableDir)?;
+                (exe_dir.join(LAUNCHER_HOME_DIR), exe_dir.join(GAME_HOME_DIR))
+            }
+            DataMode::Standard => {
+                let launcher = paths::standard_launcher_home(self.platform, self.env).ok_or(
+                    PlatformError::NoStandardDataDir {
+                        platform: self.platform.as_str(),
+                    },
+                )?;
+                let game = paths::standard_game_home(self.platform, self.env).ok_or(
+                    PlatformError::NoStandardDataDir {
+                        platform: self.platform.as_str(),
+                    },
+                )?;
+                (launcher, game)
+            }
+            DataMode::Custom => {
+                let root = request.custom_root.clone().ok_or_else(|| {
+                    PlatformError::InvalidCustomRoot {
+                        root: PathBuf::new(),
+                    }
+                })?;
+                if !root.is_absolute() {
+                    return Err(PlatformError::InvalidCustomRoot { root });
+                }
+                (root.join(LAUNCHER_HOME_DIR), root.join(GAME_HOME_DIR))
+            }
+        };
+
+        Ok(ResolvedData {
+            mode: request.mode,
+            launcher_home: request.launcher_home.clone().unwrap_or(launcher_home),
+            game_home: request.game_home.clone().unwrap_or(game_home),
+            redirected_from: None,
+        })
+    }
+
+    /// 解析并跟随 `<launcher_home>/redirect.json`（便携盘被搬走后旧目录不再自己长出新实例）。
+    ///
+    /// # Errors
+    /// 解析失败、指针损坏、跳转成环/超限时返回错误。
+    pub fn resolve_effective(
+        &self,
+        request: &DataDirRequest,
+        max_hops: usize,
+    ) -> PlatformResult<ResolvedData> {
+        let resolved = self.resolve(request)?;
+        let followed = redirect::follow(&resolved.launcher_home, max_hops)?;
+        match followed {
+            Some(followed) => Ok(ResolvedData {
+                mode: resolved.mode,
+                launcher_home: followed.pointer.launcher_home.clone(),
+                game_home: followed.pointer.game_home.clone(),
+                redirected_from: Some(resolved.launcher_home),
+            }),
+            None => Ok(resolved),
+        }
+    }
+}
+
+/// 默认跟随跳数上限（防成环）。
+pub const DEFAULT_REDIRECT_MAX_HOPS: usize = 8;
+
+impl<'env> Resolver<'env> {
+    /// [`Self::resolve_effective`] 的默认跳数版本。
+    ///
+    /// # Errors
+    /// 同 [`Self::resolve_effective`]。
+    pub fn resolve_default(&self, request: &DataDirRequest) -> PlatformResult<ResolvedData> {
+        self.resolve_effective(request, DEFAULT_REDIRECT_MAX_HOPS)
+    }
+}
diff --git a/crates/core/src/platform/dir_migration.rs b/crates/core/src/platform/dir_migration.rs
new file mode 100644
index 0000000..7a1a14e
--- /dev/null
+++ b/crates/core/src/platform/dir_migration.rs
@@ -0,0 +1,252 @@
+//! 数据目录迁移：计划 → 执行 → 失败回滚 → 收据 + `redirect.json` 指针。
+//!
+//! 设计出处：`DevDocs/PlanDoc/04-data-and-config.md` §1 细节——
+//! 「迁移 = 移动 + 原地留 redirect.json 指针；迁移失败自动回滚（HMCL `MigrationReceipt` 指纹防重放思想）」。
+//!
+//! 安全取舍（都是显式拒绝，不猜用户意图）：
+//! 1. 目标目录已有数据 → 拒绝（不合并，避免半合并状态）；
+//! 2. 任一步失败 → 逆序回滚已搬的分区；回滚也失败 → [`PlatformError::RollbackFailed`] 要求人工介入；
+//! 3. `cache/` 是纯缓存，默认一起搬但可以关掉。
+
+use std::io;
+use std::path::{Path, PathBuf};
+
+use super::data_dir::ResolvedData;
+use super::error::{io_at, PlatformError, PlatformResult};
+use super::layout::{LauncherLayout, Partition};
+use super::receipt::{self, MigrationReceipt};
+use super::redirect::{self, RedirectPointer, REDIRECT_SCHEMA_VERSION};
+
+/// 迁移选项。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct DirMigrationOptions {
+    /// 是否连 `cache/` 一起搬（关掉则目标侧重建缓存）。
+    pub migrate_cache: bool,
+}
+
+impl Default for DirMigrationOptions {
+    fn default() -> Self {
+        Self {
+            migrate_cache: true,
+        }
+    }
+}
+
+/// 一步分区搬运。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct MoveStep {
+    /// 分区。
+    pub partition: Partition,
+    /// 源目录。
+    pub source: PathBuf,
+    /// 目标目录。
+    pub target: PathBuf,
+}
+
+/// 已校验过的迁移计划。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DirMigrationPlan {
+    /// 源布局。
+    pub from: ResolvedData,
+    /// 目标布局。
+    pub to: ResolvedData,
+    /// 要搬的分区（按搬动顺序：config → data → logs → cache）。
+    pub steps: Vec<MoveStep>,
+}
+
+/// 迁移结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DirMigrationOutcome {
+    /// 已搬的分区（按搬动顺序）。
+    pub moved: Vec<Partition>,
+    /// 写入目标的收据。
+    pub receipt: MigrationReceipt,
+    /// 写入旧目录的指针。
+    pub pointer: RedirectPointer,
+    /// 收据落盘路径。
+    pub receipt_path: PathBuf,
+    /// 指针落盘路径。
+    pub pointer_path: PathBuf,
+}
+
+/// 搬动顺序：配置文件最重要、缓存最后（且可跳过）。
+const ORDER: [Partition; 4] = [
+    Partition::Config,
+    Partition::Data,
+    Partition::Logs,
+    Partition::Cache,
+];
+
+/// 生成计划（不改动磁盘，只校验）。目标目录已存在且非空 → 拒绝。
+///
+/// # Errors
+/// 源目标相同、源目录不存在、目标非空、没有可搬分区时返回 [`PlatformError::MigrationRefused`]。
+pub fn plan(
+    from: &ResolvedData,
+    to: &ResolvedData,
+    options: &DirMigrationOptions,
+) -> PlatformResult<DirMigrationPlan> {
+    if from.same_target(to) {
+        return Err(PlatformError::MigrationRefused {
+            reason: format!("源与目标相同: {}", from.launcher_home.display()),
+        });
+    }
+    if !from.launcher_home.is_dir() {
+        return Err(PlatformError::MigrationRefused {
+            reason: format!("源数据目录不存在: {}", from.launcher_home.display()),
+        });
+    }
+    if is_non_empty_dir(&to.launcher_home) {
+        return Err(PlatformError::MigrationRefused {
+            reason: format!("目标数据目录已有数据: {}", to.launcher_home.display()),
+        });
+    }
+
+    let from_layout = LauncherLayout::new(from.launcher_home.clone());
+    let to_layout = LauncherLayout::new(to.launcher_home.clone());
+    let mut steps = Vec::new();
+    for partition in ORDER {
+        if partition.is_disposable() && !options.migrate_cache {
+            continue;
+        }
+        let source = from_layout.partition(partition);
+        if !source.is_dir() {
+            continue;
+        }
+        steps.push(MoveStep {
+            partition,
+            source,
+            target: to_layout.partition(partition),
+        });
+    }
+    if steps.is_empty() {
+        return Err(PlatformError::MigrationRefused {
+            reason: format!(
+                "源数据目录里没有可搬的分区: {}",
+                from.launcher_home.display()
+            ),
+        });
+    }
+    Ok(DirMigrationPlan {
+        from: from.clone(),
+        to: to.clone(),
+        steps,
+    })
+}
+
+/// 执行计划：逐分区搬 → 失败逆序回滚 → 成功后写收据 + 旧目录指针。
+///
+/// # Errors
+/// 写/搬失败且回滚成功 → 返回原始错误（磁盘已还原）；回滚也失败 → [`PlatformError::RollbackFailed`]。
+pub fn execute(plan: &DirMigrationPlan, now_ms: u64) -> PlatformResult<DirMigrationOutcome> {
+    let mut applied: Vec<&MoveStep> = Vec::new();
+    for step in &plan.steps {
+        match move_tree(&step.source, &step.target) {
+            Ok(()) => applied.push(step),
+            Err(err) => return Err(rollback(&applied, err)),
+        }
+    }
+
+    let from_layout = LauncherLayout::new(plan.from.launcher_home.clone());
+    let to_layout = LauncherLayout::new(plan.to.launcher_home.clone());
+    std::fs::create_dir_all(from_layout.home()).map_err(io_at(from_layout.home()))?;
+    std::fs::create_dir_all(to_layout.config()).map_err(io_at(to_layout.config()))?;
+
+    let receipt = MigrationReceipt::data_dir_move(
+        plan.from.launcher_home.clone(),
+        plan.to.launcher_home.clone(),
+        now_ms,
+    );
+    let receipt_path = to_layout.migration_receipt();
+    receipt::write(&receipt_path, &receipt)?;
+
+    let pointer = RedirectPointer {
+        schema_version: REDIRECT_SCHEMA_VERSION,
+        mode: plan.to.mode,
+        launcher_home: plan.to.launcher_home.clone(),
+        game_home: plan.to.game_home.clone(),
+        migrated_at_ms: now_ms,
+    };
+    let pointer_path = redirect::write(from_layout.home(), &pointer)?;
+
+    Ok(DirMigrationOutcome {
+        moved: plan.steps.iter().map(|step| step.partition).collect(),
+        receipt,
+        pointer,
+        receipt_path,
+        pointer_path,
+    })
+}
+
+/// 逆序回滚已搬分区；回滚本身失败时升级为 [`PlatformError::RollbackFailed`]。
+fn rollback(applied: &[&MoveStep], cause: PlatformError) -> PlatformError {
+    for step in applied.iter().rev() {
+        if let Err(rollback_err) = move_tree(&step.target, &step.source) {
+            return PlatformError::RollbackFailed {
+                reason: format!(
+                    "分区 {} 搬运失败（{cause}），且回滚 {} 失败（{rollback_err}）",
+                    step.partition.as_str(),
+                    step.partition.as_str()
+                ),
+            };
+        }
+    }
+    cause
+}
+
+/// 搬一棵目录树：优先 `rename`（同盘瞬时）；跨盘失败回落「复制 + 校验 + 删源」。
+///
+/// 目标已存在则拒绝（绝不合并）。源不存在视为无事可做。
+fn move_tree(source: &Path, target: &Path) -> PlatformResult<()> {
+    if !source.exists() {
+        return Ok(());
+    }
+    if target.exists() {
+        return Err(PlatformError::MigrationRefused {
+            reason: format!("目标已存在，拒绝覆盖: {}", target.display()),
+        });
+    }
+    let parent = target.parent().unwrap_or_else(|| Path::new(""));
+    if !parent.as_os_str().is_empty() {
+        std::fs::create_dir_all(parent).map_err(io_at(parent))?;
+    }
+
+    match std::fs::rename(source, target) {
+        Ok(()) => Ok(()),
+        Err(_) => {
+            // 跨盘（便携盘 → 内置盘）时 rename 会失败，改用复制 + 删源。
+            copy_tree(source, target).map_err(|err| {
+                std::fs::remove_dir_all(target).ok();
+                PlatformError::Io {
+                    path: target.to_path_buf(),
+                    source: err,
+                }
+            })?;
+            std::fs::remove_dir_all(source).map_err(io_at(source))
+        }
+    }
+}
+
+/// 递归复制（不跟随符号链接，避免把外部大目录拖进来）。
+fn copy_tree(from: &Path, to: &Path) -> io::Result<()> {
+    std::fs::create_dir_all(to)?;
+    for entry in std::fs::read_dir(from)? {
+        let entry = entry?;
+        let file_type = entry.file_type()?;
+        let destination = to.join(entry.file_name());
+        if file_type.is_dir() {
+            copy_tree(&entry.path(), &destination)?;
+        } else if file_type.is_file() {
+            std::fs::copy(entry.path(), &destination)?;
+        }
+    }
+    Ok(())
+}
+
+/// 目录存在且非空。
+fn is_non_empty_dir(path: &Path) -> bool {
+    if !path.is_dir() {
+        return false;
+    }
+    std::fs::read_dir(path).is_ok_and(|mut entries| entries.next().is_some())
+}
diff --git a/crates/core/src/platform/error.rs b/crates/core/src/platform/error.rs
new file mode 100644
index 0000000..95e392e
--- /dev/null
+++ b/crates/core/src/platform/error.rs
@@ -0,0 +1,124 @@
+//! platform 层错误类型与结果别名。
+//!
+//! 设计出处：`DevDocs/PlanDoc/04-data-and-config.md` §1（三模式 + 迁移收据）、
+//! `DevDocs/analyse/07-settings-packaging-update.md` §1.6（保存通道）、§1.8（遗留迁移收据）。
+
+use std::fmt;
+use std::io;
+use std::path::PathBuf;
+
+/// platform 层的结果别名。
+pub type PlatformResult<T> = Result<T, PlatformError>;
+
+/// 数据目录解析、文件系统原语、目录迁移可能出的问题。
+#[derive(Debug)]
+pub enum PlatformError {
+    /// 文件系统操作失败（带出错路径）。
+    Io {
+        /// 出错的文件或目录。
+        path: PathBuf,
+        /// 底层 IO 错误。
+        source: io::Error,
+    },
+    /// Portable 模式拿不到可执行文件所在目录。
+    NoExecutableDir,
+    /// Standard 模式拿不到宿主标准数据目录（环境变量缺失）。
+    NoStandardDataDir {
+        /// 平台名（`windows` / `macos` / `linux` / `other`）。
+        platform: &'static str,
+    },
+    /// Custom 模式没给目录，或给的不是绝对路径。
+    InvalidCustomRoot {
+        /// 用户给的目录。
+        root: PathBuf,
+    },
+    /// 实例 id 非法（只允许 `[A-Za-z0-9_-]`，挡掉 `../` 路径穿越）。
+    InvalidInstanceId {
+        /// 用户/档案里给的 id。
+        id: String,
+    },
+    /// `redirect.json` 链超过跳数上限或成环。
+    RedirectCycle {
+        /// 起始目录。
+        dir: PathBuf,
+        /// 实际跳数。
+        hops: usize,
+    },
+    /// `redirect.json` 内容损坏。
+    RedirectCorrupt {
+        /// 指针文件路径。
+        path: PathBuf,
+        /// 原因。
+        reason: String,
+    },
+    /// 拒绝迁移（目标已有数据、源不存在等），原因写在消息里。
+    MigrationRefused {
+        /// 拒绝原因。
+        reason: String,
+    },
+    /// 迁移失败且回滚也失败——需要人工介入，不能当成普通失败吞掉。
+    RollbackFailed {
+        /// 原始失败 + 回滚失败串起来的原因。
+        reason: String,
+    },
+    /// 迁移收据损坏。
+    ReceiptCorrupt {
+        /// 收据文件路径。
+        path: PathBuf,
+        /// 原因。
+        reason: String,
+    },
+}
+
+impl fmt::Display for PlatformError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Io { path, source } => write!(f, "IO 失败 @ {}: {source}", path.display()),
+            Self::NoExecutableDir => write!(f, "Portable 模式无法定位可执行文件所在目录"),
+            Self::NoStandardDataDir { platform } => {
+                write!(
+                    f,
+                    "Standard 模式在 {platform} 上拿不到标准数据目录（环境变量缺失）"
+                )
+            }
+            Self::InvalidCustomRoot { root } => {
+                write!(
+                    f,
+                    "Custom 数据目录不合法（必须是绝对路径）: {}",
+                    root.display()
+                )
+            }
+            Self::InvalidInstanceId { id } => {
+                write!(f, "实例 id 非法（只允许 [A-Za-z0-9_-]）: {id:?}")
+            }
+            Self::RedirectCycle { dir, hops } => write!(
+                f,
+                "redirect.json 跳转成环或超限（{hops} 跳）@ {}",
+                dir.display()
+            ),
+            Self::RedirectCorrupt { path, reason } => {
+                write!(f, "redirect.json 损坏 @ {}: {reason}", path.display())
+            }
+            Self::MigrationRefused { reason } => write!(f, "拒绝迁移: {reason}"),
+            Self::RollbackFailed { reason } => write!(f, "迁移回滚失败，需人工介入: {reason}"),
+            Self::ReceiptCorrupt { path, reason } => {
+                write!(f, "迁移收据损坏 @ {}: {reason}", path.display())
+            }
+        }
+    }
+}
+
+impl std::error::Error for PlatformError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            Self::Io { source, .. } => Some(source),
+            _ => None,
+        }
+    }
+}
+
+/// 把 `io::Error` 绑上路径，给 `map_err` 用。
+pub(crate) fn io_at<P: Into<PathBuf>>(path: P) -> impl FnOnce(io::Error) -> PlatformError {
+    let path = path.into();
+    move |source| PlatformError::Io { path, source }
+}
diff --git a/crates/core/src/platform/hash.rs b/crates/core/src/platform/hash.rs
new file mode 100644
index 0000000..9b31944
--- /dev/null
+++ b/crates/core/src/platform/hash.rs
@@ -0,0 +1,95 @@
+//! 迁移收据的源文件指纹（SHA-256），委托给 `sha2`。
+//!
+//! 出处：`DevDocs/analyse/07-settings-packaging-update.md` §1.8——收据里存源文件 `sourceSHA256`，
+//! 这样「删掉新文件但旧文件没变」时不会重复迁移，旧文件变了才重放。
+//!
+//! 阶段A 在「不许动 Cargo.toml」的约束下自带过一版 FIPS 180-4 实现；阶段B 按 tower 批复
+//! 改用 `sha2`（安全哈希不自维护），**公开签名不变**，单测从「自带实现的标准向量」
+//! 变为「wrapper 与 `sha2` 一致 + 标准向量兜底」。
+
+use std::io;
+use std::path::Path;
+
+use sha2::{Digest, Sha256};
+
+/// 计算 32 字节摘要。
+#[must_use]
+pub fn sha256(data: &[u8]) -> [u8; 32] {
+    let digest = Sha256::digest(data);
+    let mut out = [0u8; 32];
+    out.copy_from_slice(digest.as_slice());
+    out
+}
+
+/// 计算小写十六进制摘要。
+#[must_use]
+pub fn sha256_hex(data: &[u8]) -> String {
+    to_hex(&sha256(data))
+}
+
+/// 读文件算十六进制摘要（配置文件很小，整读即可）。
+///
+/// # Errors
+/// 文件读失败时返回原始 `io::Error`。
+pub fn sha256_hex_file(path: &Path) -> io::Result<String> {
+    let bytes = std::fs::read(path)?;
+    Ok(sha256_hex(&bytes))
+}
+
+fn to_hex(bytes: &[u8]) -> String {
+    const HEX: &[u8; 16] = b"0123456789abcdef";
+    let mut out = String::with_capacity(bytes.len() * 2);
+    for byte in bytes {
+        out.push(char::from(HEX[usize::from(byte >> 4)]));
+        out.push(char::from(HEX[usize::from(byte & 0x0f)]));
+    }
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use sha2::Digest;
+
+    use super::{sha256, sha256_hex, sha256_hex_file};
+
+    #[test]
+    fn matches_fips_vectors() {
+        assert_eq!(
+            sha256_hex(b""),
+            "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+        );
+        assert_eq!(
+            sha256_hex(b"abc"),
+            "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
+        );
+        assert_eq!(
+            sha256_hex(b"abcdbcdecdefdefgefghfghighijhijkijkljklmklmnlmnomnopnopq"),
+            "248d6a61d20638b8e5c026930c3e6039a33ce45964ff2167f6ecedd419db06c1"
+        );
+    }
+
+    #[test]
+    fn agrees_with_sha2_at_block_boundaries() {
+        // 55 / 56 / 63 / 64 / 65 是补齐逻辑最容易出错的长度，wrapper 必须与 sha2 完全一致。
+        for len in [55usize, 56, 63, 64, 65, 128, 1000] {
+            let data = vec![b'a'; len];
+            let expected = sha2::Sha256::digest(&data);
+            assert_eq!(&sha256(&data)[..], expected.as_slice(), "length {len}");
+            assert_eq!(sha256_hex(&data).len(), 64);
+        }
+    }
+
+    #[test]
+    fn hashes_file_contents() {
+        let dir = std::env::temp_dir().join(format!("ull-hash-{}", std::process::id()));
+        std::fs::create_dir_all(&dir).expect("create temp dir");
+        let path = dir.join("a.txt");
+        std::fs::write(&path, b"abc").expect("write");
+        let hex = sha256_hex_file(&path).expect("hash file");
+        std::fs::remove_dir_all(&dir).ok();
+        assert_eq!(
+            hex,
+            "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
+        );
+    }
+}
diff --git a/crates/core/src/platform/layout.rs b/crates/core/src/platform/layout.rs
new file mode 100644
index 0000000..146a011
--- /dev/null
+++ b/crates/core/src/platform/layout.rs
@@ -0,0 +1,223 @@
+//! `.ULL/` 四分区布局——所有模块取路径的唯一入口，禁止各自手拼路径。
+//!
+//! 布局依据 `DevDocs/PlanDoc/04-data-and-config.md` §2（承 HMCL 四分区）：
+//! `config/`（schema 化 JSON）、`data/`（可重建但优先保留）、`cache/`（随时可删）、`logs/`。
+
+use std::path::{Path, PathBuf};
+
+use super::error::{io_at, PlatformError, PlatformResult};
+
+/// Portable 模式下启动器数据目录名（exe 同目录）。
+pub const LAUNCHER_HOME_DIR: &str = ".ULL";
+/// 游戏数据目录名。
+pub const GAME_HOME_DIR: &str = ".minecraft";
+/// 分区：配置。
+pub const CONFIG_DIR: &str = "config";
+/// 分区：状态数据。
+pub const DATA_DIR: &str = "data";
+/// 分区：纯缓存。
+pub const CACHE_DIR: &str = "cache";
+/// 分区：启动器日志。
+pub const LOGS_DIR: &str = "logs";
+
+/// 全局设置文件名。
+pub const LAUNCHER_CONFIG_FILE: &str = "launcher.json";
+/// 实例档案列表文件名。
+pub const PROFILES_CONFIG_FILE: &str = "profiles.json";
+/// 每实例设置所在子目录。
+pub const INSTANCES_DIR: &str = "instances";
+/// 迁移后留在旧目录的指针文件名。
+pub const REDIRECT_FILE: &str = "redirect.json";
+/// 目录迁移收据文件名（写在目标 `config/`）。
+pub const MIGRATION_RECEIPT_FILE: &str = "migration-receipt.json";
+
+/// `.ULL/` 下的四个分区。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub enum Partition {
+    /// `config/`：配置（迁移时优先搬）。
+    Config,
+    /// `data/`：状态数据（不可丢）。
+    Data,
+    /// `cache/`：纯缓存（可丢，迁移可选）。
+    Cache,
+    /// `logs/`：启动器日志。
+    Logs,
+}
+
+impl Partition {
+    /// 全部四个分区。
+    pub const ALL: [Self; 4] = [Self::Config, Self::Data, Self::Cache, Self::Logs];
+
+    /// 分区目录名。
+    #[must_use]
+    pub const fn dir_name(&self) -> &'static str {
+        match self {
+            Self::Config => CONFIG_DIR,
+            Self::Data => DATA_DIR,
+            Self::Cache => CACHE_DIR,
+            Self::Logs => LOGS_DIR,
+        }
+    }
+
+    /// 稳定名（日志 / 收据用）。
+    #[must_use]
+    pub const fn as_str(&self) -> &'static str {
+        self.dir_name()
+    }
+
+    /// 是否为可丢弃分区（迁移时可跳过）。
+    #[must_use]
+    pub const fn is_disposable(&self) -> bool {
+        matches!(self, Self::Cache)
+    }
+}
+
+/// 一个 launcher home（`.ULL` 的等价物）的路径视图。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LauncherLayout {
+    home: PathBuf,
+}
+
+impl LauncherLayout {
+    /// 绑定到某个 home 目录（不创建任何东西，创建用 [`Self::ensure`]）。
+    #[must_use]
+    pub fn new(home: impl Into<PathBuf>) -> Self {
+        Self { home: home.into() }
+    }
+
+    /// home 根目录。
+    #[must_use]
+    pub fn home(&self) -> &Path {
+        &self.home
+    }
+
+    /// 任一分区目录。
+    #[must_use]
+    pub fn partition(&self, partition: Partition) -> PathBuf {
+        self.home.join(partition.dir_name())
+    }
+
+    /// `config/`。
+    #[must_use]
+    pub fn config(&self) -> PathBuf {
+        self.partition(Partition::Config)
+    }
+
+    /// `data/`。
+    #[must_use]
+    pub fn data(&self) -> PathBuf {
+        self.partition(Partition::Data)
+    }
+
+    /// `cache/`。
+    #[must_use]
+    pub fn cache(&self) -> PathBuf {
+        self.partition(Partition::Cache)
+    }
+
+    /// `logs/`。
+    #[must_use]
+    pub fn logs(&self) -> PathBuf {
+        self.partition(Partition::Logs)
+    }
+
+    /// `config/<name>`。
+    #[must_use]
+    pub fn config_file(&self, name: &str) -> PathBuf {
+        self.config().join(name)
+    }
+
+    /// `config/launcher.json`。
+    #[must_use]
+    pub fn launcher_config(&self) -> PathBuf {
+        self.config_file(LAUNCHER_CONFIG_FILE)
+    }
+
+    /// `config/profiles.json`。
+    #[must_use]
+    pub fn profiles_config(&self) -> PathBuf {
+        self.config_file(PROFILES_CONFIG_FILE)
+    }
+
+    /// `config/instances/<id>.json`。
+    ///
+    /// # Errors
+    /// 实例 id 只允许 `[A-Za-z0-9_-]`（正常是稳定 UUID），否则返回
+    /// [`super::error::PlatformError::InvalidInstanceId`]，挡掉 `../` 穿越。
+    pub fn instance_config(&self, id: &str) -> PlatformResult<PathBuf> {
+        if !is_valid_instance_id(id) {
+            return Err(PlatformError::InvalidInstanceId { id: id.to_owned() });
+        }
+        Ok(self.config().join(INSTANCES_DIR).join(format!("{id}.json")))
+    }
+
+    /// `cache/sha1/<h2>`——内容寻址缓存的两级分片（避开 NTFS 单目录塌陷）。
+    #[must_use]
+    pub fn sha1_cache(&self, shard: &str) -> PathBuf {
+        self.cache().join("sha1").join(shard)
+    }
+
+    /// `cache/etag.json`——共享 ETag 表。
+    #[must_use]
+    pub fn etag_cache(&self) -> PathBuf {
+        self.cache().join("etag.json")
+    }
+
+    /// `cache/meta/`——列表 API 响应缓存（带 TTL）。
+    #[must_use]
+    pub fn meta_cache(&self) -> PathBuf {
+        self.cache().join("meta")
+    }
+
+    /// `data/java-managed/`——自动下载的 JDK。
+    #[must_use]
+    pub fn java_managed(&self) -> PathBuf {
+        self.data().join("java-managed")
+    }
+
+    /// `data/auth/`——账户元数据与凭据。
+    #[must_use]
+    pub fn auth_data(&self) -> PathBuf {
+        self.data().join("auth")
+    }
+
+    /// `data/agent/sessions/`——AI 会话 jsonl 与审计日志。
+    #[must_use]
+    pub fn agent_sessions(&self) -> PathBuf {
+        self.data().join("agent").join("sessions")
+    }
+
+    /// `<home>/redirect.json`——「我已迁走」指针。
+    #[must_use]
+    pub fn redirect_path(&self) -> PathBuf {
+        self.home.join(REDIRECT_FILE)
+    }
+
+    /// `config/migration-receipt.json`——迁移收据。
+    #[must_use]
+    pub fn migration_receipt(&self) -> PathBuf {
+        self.config_file(MIGRATION_RECEIPT_FILE)
+    }
+
+    /// 一次性建齐四分区。
+    ///
+    /// # Errors
+    /// 目录创建失败时返回带路径的 [`super::error::PlatformError::Io`]。
+    pub fn ensure(&self) -> PlatformResult<()> {
+        for partition in Partition::ALL {
+            let dir = self.partition(partition);
+            std::fs::create_dir_all(&dir).map_err(io_at(&dir))?;
+        }
+        Ok(())
+    }
+}
+
+/// 实例 id 白名单：字母数字与 `_`/`-`。
+#[must_use]
+pub fn is_valid_instance_id(id: &str) -> bool {
+    !id.is_empty()
+        && id.len() <= 64
+        && id
+            .chars()
+            .all(|ch| ch.is_ascii_alphanumeric() || ch == '_' || ch == '-')
+}
diff --git a/crates/core/src/platform/linux_caps.rs b/crates/core/src/platform/linux_caps.rs
new file mode 100644
index 0000000..3397e9d
--- /dev/null
+++ b/crates/core/src/platform/linux_caps.rs
@@ -0,0 +1,225 @@
+//! Linux 探测：**能力**而非版本号（D19 · `PlanDoc/11-os-detection.md` §2）。
+//!
+//! 发行版版本对能不能跑没有意义，所以这里分三类事实：
+//! - `/etc/os-release` 的 `PRETTY_NAME` —— **仅供显示/日志**；
+//! - 内核 release（`/proc/sys/kernel/osrelease`，退化 `uname -r`）—— 喂 MC 的
+//!   `rules.os.version`，同时给出最低内核判定用的 `major.minor`；
+//! - 能力探测：图形会话类型（Wayland / X11 / 无显示）与 GL 能力钩子（见 [`probe_gl`]）。
+//!
+//! glibc 版本用 `ldd --version` 探测（musl / Termux 上取不到，此时不阻塞）。
+//! fontconfig 可用性与 `xdg-desktop-portal` 同理留到 app 层（字体回退、主题跟随、文件选择器），
+//! core 只报环境事实，不做渲染后端决策。
+//! 解析函数是纯函数且跨平台编译，单测用注入样本覆盖（见 `tests/platform/`）。
+
+/// 图形会话类型（`Unknown` 是派生默认值：未探测）。
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub enum SessionKind {
+    /// Wayland 会话（`WAYLAND_DISPLAY` 或 `XDG_SESSION_TYPE=wayland`）。
+    Wayland,
+    /// X11 会话（`DISPLAY` 或 `XDG_SESSION_TYPE=x11`）。
+    X11,
+    /// 没有图形会话（服务器 / 容器 / SSH）。GUI 用不了，CLI 照常。
+    Headless,
+    /// 未探测（非 Linux 平台，或探测未执行）。
+    #[default]
+    Unknown,
+}
+
+impl SessionKind {
+    /// 简短名（日志用）。
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Wayland => "wayland",
+            Self::X11 => "x11",
+            Self::Headless => "headless",
+            Self::Unknown => "unknown",
+        }
+    }
+
+    /// 是否存在可用的显示服务器。
+    pub fn has_display(self) -> bool {
+        matches!(self, Self::Wayland | Self::X11)
+    }
+}
+
+/// GL/EGL 能力探测结果。
+///
+/// P1 只留钩子：真探测要 `dlopen("libEGL.so")` + `eglQueryString`，那是 FFI，
+/// 而 core 是 `#![forbid(unsafe_code)]`；因此真实探测放在 app 层「渲染后端选择」里做，
+/// core 只负责把 `Unknown` 如实报出来，不阻塞任何流程。
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub enum GlProbe {
+    /// 未探测（P1 常态）。
+    #[default]
+    Unknown,
+    /// 有可用的 GL/EGL。
+    Available,
+    /// 没有可用 GL（调用方应降级到软渲染）。
+    Missing,
+}
+
+impl GlProbe {
+    /// 简短名（日志用）。
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Unknown => "unknown",
+            Self::Available => "available",
+            Self::Missing => "missing",
+        }
+    }
+}
+
+/// Linux 探测结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LinuxCaps {
+    /// 发行版展示名（`PRETTY_NAME`，仅显示）。
+    pub distro: Option<String>,
+    /// 内核 release 原始串（`6.8.0-45-generic`），喂 `rules.os.version`。
+    pub kernel: Option<String>,
+    /// 内核 `major.minor`（最低内核判定用）。
+    pub kernel_version: Option<(u32, u32)>,
+    /// glibc `major.minor`；musl / 取不到时为 `None`。
+    pub glibc: Option<(u32, u32)>,
+    /// 图形会话类型。
+    pub session: SessionKind,
+    /// GL 能力（P1 恒为 [`GlProbe::Unknown`]）。
+    pub gl: GlProbe,
+}
+
+/// 探测当前 Linux 环境；非 Linux 平台返回全空的默认值。
+#[cfg(target_os = "linux")]
+pub fn probe() -> LinuxCaps {
+    let distro = std::fs::read_to_string("/etc/os-release")
+        .ok()
+        .and_then(|text| parse_os_release(&text));
+    let kernel = std::fs::read_to_string("/proc/sys/kernel/osrelease")
+        .ok()
+        .map(|text| text.trim().to_string())
+        .filter(|value| !value.is_empty())
+        .or_else(|| run("uname", &["-r"]));
+    let glibc = run("ldd", &["--version"]).and_then(|text| parse_glibc_version(&text));
+    LinuxCaps {
+        distro,
+        kernel_version: kernel.as_deref().and_then(parse_kernel_version),
+        kernel,
+        glibc,
+        session: current_session(),
+        gl: probe_gl(),
+    }
+}
+
+/// 探测当前 Linux 环境；非 Linux 平台返回全空的默认值。
+#[cfg(not(target_os = "linux"))]
+pub fn probe() -> LinuxCaps {
+    LinuxCaps {
+        distro: None,
+        kernel: None,
+        kernel_version: None,
+        glibc: None,
+        session: SessionKind::Unknown,
+        gl: GlProbe::Unknown,
+    }
+}
+
+/// GL/EGL 探测钩子（P1 返回 [`GlProbe::Unknown`]，见类型文档）。
+pub fn probe_gl() -> GlProbe {
+    GlProbe::Unknown
+}
+
+/// 按当前环境变量判定会话类型。
+pub fn current_session() -> SessionKind {
+    session_from_env(|key| std::env::var(key).ok())
+}
+
+/// 按注入的环境变量读取函数判定会话类型（便于单测）。
+///
+/// 判定顺序：`WAYLAND_DISPLAY` → `XDG_SESSION_TYPE` → `DISPLAY` → 无显示。
+pub fn session_from_env(get: impl Fn(&str) -> Option<String>) -> SessionKind {
+    let has = |key: &str| get(key).map(|v| !v.trim().is_empty()).unwrap_or(false);
+    if has("WAYLAND_DISPLAY") {
+        return SessionKind::Wayland;
+    }
+    match get("XDG_SESSION_TYPE").as_deref().map(str::trim) {
+        Some(value) if value.eq_ignore_ascii_case("wayland") => return SessionKind::Wayland,
+        Some(value) if value.eq_ignore_ascii_case("x11") => return SessionKind::X11,
+        _ => {}
+    }
+    if has("DISPLAY") {
+        return SessionKind::X11;
+    }
+    SessionKind::Headless
+}
+
+/// 从 `/etc/os-release` 取 `PRETTY_NAME`（去引号）。
+pub fn parse_os_release(text: &str) -> Option<String> {
+    let mut fallback = None;
+    for line in text.lines() {
+        let line = line.trim();
+        let Some((key, value)) = line.split_once('=') else {
+            continue;
+        };
+        let value = value.trim().trim_matches('"').trim_matches('\'').trim();
+        if value.is_empty() {
+            continue;
+        }
+        match key.trim() {
+            "PRETTY_NAME" => return Some(value.to_string()),
+            // 没有 PRETTY_NAME 时用 NAME + VERSION_ID 拼一个（某些裁剪发行版只给这两个）。
+            "NAME" => {
+                let name = value.to_string();
+                fallback = Some(match fallback.take() {
+                    Some(prev) => format!("{prev} {name}"),
+                    None => name,
+                });
+            }
+            "VERSION_ID" => {
+                let version = value.to_string();
+                fallback = Some(match fallback.take() {
+                    Some(prev) => format!("{prev} {version}"),
+                    None => version,
+                });
+            }
+            _ => {}
+        }
+    }
+    fallback
+}
+
+/// 从内核 release 串取 `major.minor`（`6.8.0-45-generic` → `(6, 8)`）。
+pub fn parse_kernel_version(release: &str) -> Option<(u32, u32)> {
+    let trimmed = release.trim();
+    let mut parts = trimmed.split(|c: char| !c.is_ascii_digit());
+    let major: u32 = parts.next()?.parse().ok()?;
+    let minor: u32 = parts.next().unwrap_or("0").parse().unwrap_or(0);
+    Some((major, minor))
+}
+
+/// 从 `ldd --version` 输出取 glibc `major.minor`
+/// （`ldd (Ubuntu GLIBC 2.39-0ubuntu8.3) 2.39` → `(2, 39)`）。
+pub fn parse_glibc_version(text: &str) -> Option<(u32, u32)> {
+    // 只看第一行：后面是版权声明，可能含有别的数字。
+    let first = text.lines().next().unwrap_or_default();
+    first.split_whitespace().rev().find_map(|token| {
+        let (major, minor) = token.split_once('.')?;
+        let minor = minor
+            .split(|c: char| !c.is_ascii_digit())
+            .next()
+            .unwrap_or_default();
+        Some((major.parse().ok()?, minor.parse().ok()?))
+    })
+}
+
+/// `(2, 31)` → `"2.31"`（展示用）。
+pub fn format_version(version: (u32, u32)) -> String {
+    format!("{}.{}", version.0, version.1)
+}
+
+#[cfg(target_os = "linux")]
+fn run(program: &str, args: &[&str]) -> Option<String> {
+    use std::process::Command;
+    let output = Command::new(program).args(args).output().ok()?;
+    if output.stdout.is_empty() {
+        return None;
+    }
+    Some(String::from_utf8_lossy(&output.stdout).into_owned())
+}
diff --git a/crates/core/src/platform/macos_version.rs b/crates/core/src/platform/macos_version.rs
new file mode 100644
index 0000000..bc18447
--- /dev/null
+++ b/crates/core/src/platform/macos_version.rs
@@ -0,0 +1,100 @@
+//! macOS 探测：产品版本 + 运行架构（D19 · `PlanDoc/11-os-detection.md` §2）。
+//!
+//! - 产品版本：`sw_vers -productVersion` → `12.3.1`（最低部署目标判定 + MC `os.version` 规则）；
+//! - 运行架构：`sysctl -n hw.optional.arm64` 输出 `1` 表示**当前运行在 Apple Silicon 上**
+//!   （关键：Rosetta 2 下 `cfg!(target_arch)` 仍是 `x86_64`，但原生渲染路径与 MC 原生库
+//!   要的是真实架构，所以必须运行期探）；
+//! - 内核版本：`uname -r`（`22.4.0`）只进日志，不参与判定。
+//!
+//! 解析函数是纯函数且跨平台编译，单测用注入样本覆盖（见 `tests/platform/`）。
+
+/// macOS 版本 + 运行架构。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct MacOsVersion {
+    /// 主版本号（macOS 12 Monterey = 12）。
+    pub major: u32,
+    /// 次版本号。
+    pub minor: u32,
+    /// 补丁号。
+    pub patch: u32,
+    /// 是否运行在 Apple Silicon（含 Rosetta 2 场景）。
+    pub arm64: bool,
+}
+
+impl MacOsVersion {
+    /// 构造。
+    pub fn new(major: u32, minor: u32, patch: u32, arm64: bool) -> Self {
+        Self {
+            major,
+            minor,
+            patch,
+            arm64,
+        }
+    }
+
+    /// 产品版本串（`rules.os.version` 用，例如 `12.3.1`）。
+    pub fn version_string(&self) -> String {
+        format!("{}.{}.{}", self.major, self.minor, self.patch)
+    }
+
+    /// 展示名（`macOS 12.3.1 (arm64)`）。
+    pub fn display_name(&self) -> String {
+        let arch = if self.arm64 { "arm64" } else { "x86_64" };
+        format!("macOS {} ({arch})", self.version_string())
+    }
+
+    /// `rules.os.arch` 取值：Apple Silicon 上必须是 `arm64`。
+    pub fn runtime_arch(&self) -> &'static str {
+        if self.arm64 {
+            "arm64"
+        } else {
+            "x86_64"
+        }
+    }
+}
+
+/// 真实探测；非 macOS 平台恒为 `None`。
+#[cfg(target_os = "macos")]
+pub fn probe() -> Option<MacOsVersion> {
+    let (major, minor, patch) =
+        run("sw_vers", &["-productVersion"]).and_then(|text| parse_product_version(&text))?;
+    // sysctl 在 Intel 机器上以非零码退出（键不存在）→ stdout 为空 → false。
+    let arm64 = run("sysctl", &["-n", "hw.optional.arm64"])
+        .map(|text| parse_sysctl_bool(&text))
+        .unwrap_or(false);
+    Some(MacOsVersion::new(major, minor, patch, arm64))
+}
+
+/// 真实探测；非 macOS 平台恒为 `None`。
+#[cfg(not(target_os = "macos"))]
+pub fn probe() -> Option<MacOsVersion> {
+    None
+}
+
+/// 解析 `12.3.1` / `12.3` / `12`（`sw_vers -productVersion` 的输出）。
+pub fn parse_product_version(text: &str) -> Option<(u32, u32, u32)> {
+    let trimmed = text.trim();
+    let token = trimmed
+        .split_whitespace()
+        .find(|token| token.starts_with(|c: char| c.is_ascii_digit()))?;
+    let mut parts = token.split('.').map(str::parse::<u32>);
+    let major = parts.next()?.ok()?;
+    let minor = parts.next().map(|value| value.unwrap_or(0)).unwrap_or(0);
+    let patch = parts.next().map(|value| value.unwrap_or(0)).unwrap_or(0);
+    Some((major, minor, patch))
+}
+
+/// 解析 `sysctl -n hw.optional.arm64` 的输出（`1` 为真）。
+pub fn parse_sysctl_bool(text: &str) -> bool {
+    text.trim() == "1"
+}
+
+#[cfg(target_os = "macos")]
+fn run(program: &str, args: &[&str]) -> Option<String> {
+    use std::process::Command;
+    let output = Command::new(program).args(args).output().ok()?;
+    if !output.status.success() || output.stdout.is_empty() {
+        return None;
+    }
+    Some(String::from_utf8_lossy(&output.stdout).into_owned())
+}
diff --git a/crates/core/src/platform/mod.rs b/crates/core/src/platform/mod.rs
new file mode 100644
index 0000000..5691acb
--- /dev/null
+++ b/crates/core/src/platform/mod.rs
@@ -0,0 +1,46 @@
+//! OS 抽象层：路径规则、平台目录差异、进程与文件锁、软渲染/显示能力探测辅助。
+//!
+//! 设计定稿：`DevDocs/PlanDoc/04-data-and-config.md` §1–§2（三模式路径与 `.ULL` 四分区）。
+//! Win7 单独适配（决策 D11）在此收敛平台差异判断，避免散落各模块打补丁。
+//!
+//! 公共面（M12 已落地）：
+//! - [`paths`]：宿主平台族与标准目录探测（环境变量可注入），可搬运路径字符串；
+//! - [`layout`]：`.ULL/` 四分区（config/data/cache/logs）与各已知路径的唯一入口；
+//! - [`data_dir`]：三模式数据目录解析（Portable 默认 / Standard / Custom + 高级覆盖）；
+//! - [`redirect`]：迁移后留在旧目录的 `redirect.json` 指针（防便携盘旧目录被再次初始化）；
+//! - [`receipt`]：迁移收据（源指纹防重放）；
+//! - [`dir_migration`]：数据目录迁移（分区逐个搬 + 失败逆序回滚）；
+//! - [`atomic`]：原子写（tmp → fsync → rename）；[`hash`]：迁移收据用的 SHA-256。
+//!
+//! 运行期系统探测（M20 / D19 · `11-os-detection.md`）：
+//! - [`os_info`]：`OsInfo` 快照 + 最低支持判定（One / Unsupported，基线 **Windows 10+ /
+//!   macOS 12+ / Linux 达标**）+ 启动自检；
+//! - [`windows_version`]：真实 `major.minor.build`（注册表 `CurrentBuildNumber` 快路径 →
+//!   整键 `CurrentVersion` 家族 → `cmd /c ver` 兜底）；
+//! - [`macos_version`]：`sw_vers` 产品版本 + `sysctl hw.optional.arm64` 运行架构；
+//! - [`linux_caps`]：发行版（仅显示）+ 内核 release（喂 `os.version`）+ 会话/GL 能力探测；
+//! - [`vk_probe`]：Vulkan 能力的安全层探测（loader 文件 / ICD 注册 / 环境变量，无 `unsafe`）；
+//! - [`theme_probe`]：系统主题（浅色/深色）探测，供主题三态的 `auto` 初始化对齐与兜底跟随。
+//! - [`wallpaper`]：桌面壁纸**路径探测**（D38 配色三级优先里第②级的输入）。本模块只做路径
+//!   探测——不解码图片、不取色、不生成调色板，莫奈取色与三级降级在 `crates/design` 的
+//!   后续 mission。
+//!
+//! 尚未落地（后续 mission）：文件锁、进程工具、真实 GL/Vulkan 能力探测（钩子见
+//! [`linux_caps::probe_gl`] 与 [`vk_probe::probe_vk`]，FFI 受限，实际探测归 app 层渲染后端选择）。
+
+pub mod atomic;
+pub mod data_dir;
+pub mod dir_migration;
+pub mod error;
+pub mod hash;
+pub mod layout;
+pub mod linux_caps;
+pub mod macos_version;
+pub mod os_info;
+pub mod paths;
+pub mod receipt;
+pub mod redirect;
+pub mod theme_probe;
+pub mod vk_probe;
+pub mod wallpaper;
+pub mod windows_version;
diff --git a/crates/core/src/platform/os_info.rs b/crates/core/src/platform/os_info.rs
new file mode 100644
index 0000000..70a9eb9
--- /dev/null
+++ b/crates/core/src/platform/os_info.rs
@@ -0,0 +1,388 @@
+//! 运行期系统探测与最低支持判定（D19 · `DevDocs/PlanDoc/11-os-detection.md`）。
+//!
+//! 事实通道按平台分流（各文件里的 `probe()`）：[`windows_version`] 注册表 `CurrentBuildNumber`
+//! 快路径 → 整键 `CurrentVersion` 家族 → `cmd /c ver` 兜底；[`macos_version`] `sw_vers` +
+//! `sysctl`；[`linux_caps`] `/etc/os-release`（仅显示）+ 内核 release + 会话/GL 能力探测。
+//! 不用 `RtlGetVersion` FFI 是因为 core 是 `#![forbid(unsafe_code)]`，而这些路径读的是同一份
+//! 真实事实，代价只是一次性几十毫秒。
+//!
+//! 支持基线（用户拍板）：**Windows 10 起、macOS 12 起、Linux（内核/glibc 达标）**。
+//! 因此等级只有两档：[`SupportLevel::One`] 与 [`SupportLevel::Unsupported`]——Win8.1/8/7
+//! 不承诺 GUI，也不承诺 CLI（识别出旧版本正是为了报「不支持」）。
+//!
+//! 入口：[`detect`]（真探）· [`current`]（进程内缓存）· [`check`]（CLI 启动自检）；
+//! 等级映射是纯函数（[`support_level_for`] 及三平台分解），单测用注入式假数据覆盖。
+
+use std::sync::OnceLock;
+
+use crate::platform::linux_caps::{self, GlProbe, SessionKind};
+use crate::platform::macos_version;
+use crate::platform::vk_probe::{self, VkProbe};
+use crate::platform::windows_version;
+
+/// 最低支持的 Windows 版本（10.0 = Windows 10，build 10240 起）。
+pub const MIN_WINDOWS: (u32, u32) = (10, 0);
+/// 最低支持的 macOS 主版本（Slint / winit 的现实部署下限，见 D19 §4）。
+pub const MIN_MACOS_MAJOR: u32 = 12;
+/// 最低 Linux 内核（Rust std 的 Linux 下限）。
+pub const MIN_LINUX_KERNEL: (u32, u32) = (3, 2);
+/// 最低 glibc（`x86_64-unknown-linux-gnu` 构建产物能跑的下限）。
+pub const MIN_GLIBC: (u32, u32) = (2, 17);
+
+/// 操作系统家族。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum OsFamily {
+    /// Windows。
+    Windows,
+    /// macOS。
+    MacOs,
+    /// Linux 及其它 POSIX 系统。
+    Linux,
+}
+
+impl OsFamily {
+    /// 当前编译目标的系统家族。
+    pub fn current() -> Self {
+        if cfg!(target_os = "windows") {
+            Self::Windows
+        } else if cfg!(target_os = "macos") {
+            Self::MacOs
+        } else {
+            Self::Linux
+        }
+    }
+
+    /// Mojang 清单里 `rules.os.name` 的取值。
+    pub fn manifest_name(self) -> &'static str {
+        match self {
+            Self::Windows => "windows",
+            Self::MacOs => "osx",
+            Self::Linux => "linux",
+        }
+    }
+
+    /// `rules.os.arch` 的取值（按编译目标；Apple Silicon 的真实架构另见
+    /// [`MacOsVersion::runtime_arch`](crate::platform::macos_version::MacOsVersion::runtime_arch)）。
+    pub fn manifest_arch(self) -> &'static str {
+        if cfg!(target_arch = "x86_64") {
+            "x86_64"
+        } else if cfg!(target_arch = "x86") {
+            "x86"
+        } else if cfg!(target_arch = "aarch64") {
+            "arm64"
+        } else {
+            "unknown"
+        }
+    }
+
+    /// 是否为 POSIX 系统（决定 `nice`、进程组 kill 等分支）。
+    pub fn is_posix(self) -> bool {
+        !matches!(self, Self::Windows)
+    }
+}
+
+/// 支持等级（两档：满足基线 / 不满足）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SupportLevel {
+    /// 一等：基线以上（Windows 10+ / macOS 12+ / Linux 达标），GUI + CLI。
+    One,
+    /// 不支持：低于基线，启动时拒绝并给升级指引。
+    Unsupported,
+}
+
+impl SupportLevel {
+    /// 简短名（日志/事件用）。
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::One => "one",
+            Self::Unsupported => "unsupported",
+        }
+    }
+
+    /// 是否允许运行。
+    pub fn is_usable(self) -> bool {
+        matches!(self, Self::One)
+    }
+}
+
+/// 运行期系统信息（不可变快照，可跨线程共享；字段全是探测出来的事实）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct OsInfo {
+    /// 系统家族。
+    pub family: OsFamily,
+    /// `rules.os.arch` 用的架构名。
+    pub arch: String,
+    /// 版本 `major.minor`（探测失败为 `None`）。
+    pub major_minor: Option<(u32, u32)>,
+    /// 构建号（Windows build，其它平台 `None`）。
+    pub build: Option<u32>,
+    /// 展示名（`Windows 11` / `macOS 12.3.1 (arm64)` / `Ubuntu 24.04.1 LTS`）。
+    pub product: String,
+    /// 版本串（`rules.os.version` 用；Linux 上是内核 release）。
+    pub version_string: String,
+    /// 图形会话类型（Linux 有意义，其它平台 `Unknown`）。
+    pub session: SessionKind,
+    /// GL 能力（P1 恒为 `Unknown`，见 [`GlProbe`]）。
+    pub gl: GlProbe,
+    /// Vulkan 能力（文件/注册表层，无 `unsafe`；真探测归 app 层，见 [`VkProbe`]）。
+    pub vk: VkProbe,
+    /// Linux 内核 `major.minor`。
+    pub kernel: Option<(u32, u32)>,
+    /// glibc `major.minor`（musl / 取不到为 `None`）。
+    pub glibc: Option<(u32, u32)>,
+    /// 支持等级（由 [`support_level_for`] 从上面的事实算出）。
+    pub support_level: SupportLevel,
+}
+
+impl OsInfo {
+    /// `rules.os.version` 的取值（探测失败时为空串 —— 规则求值会走保守分支）。
+    pub fn os_version(&self) -> &str {
+        &self.version_string
+    }
+
+    /// 一行日志摘要（`§5.3` 每次启动写日志 / 诊断包环境快照）。
+    pub fn summary_line(&self) -> String {
+        let version = if self.version_string.is_empty() {
+            "unknown"
+        } else {
+            self.version_string.as_str()
+        };
+        format!(
+            "os={} version={version} arch={} level={} product=\"{}\" session={} gl={} vk={}",
+            self.family.manifest_name(),
+            self.arch,
+            self.support_level.as_str(),
+            self.product,
+            self.session.as_str(),
+            self.gl.as_str(),
+            self.vk.as_str(),
+        )
+    }
+
+    /// 用户可读文案（中英双语）。
+    pub fn describe(&self) -> SupportText {
+        match self.support_level {
+            SupportLevel::One => self.text_supported(),
+            SupportLevel::Unsupported => self.text_unsupported(),
+        }
+    }
+
+    fn text_supported(&self) -> SupportText {
+        let mut zh = format!("系统满足最低要求：{}（{}）。", self.product, self.arch);
+        let mut en = format!("Meets minimum requirements: {}.", self.product);
+        if self.family == OsFamily::Linux && !self.session.has_display() {
+            zh.push_str("\n注意：未检测到 Wayland/X11 图形会话，GUI 需要图形会话；CLI 不受影响。");
+            en.push_str(
+                "\nNote: no Wayland/X11 graphical session; the GUI needs one. CLI is fine.",
+            );
+        }
+        SupportText { zh, en }
+    }
+
+    fn text_unsupported(&self) -> SupportText {
+        let product = if self.product.is_empty() {
+            "未知系统"
+        } else {
+            self.product.as_str()
+        };
+        let (need_zh, need_en) = match self.family {
+            OsFamily::Windows => (
+                " Windows 10 或更高版本".to_string(),
+                "Windows 10 or newer".to_string(),
+            ),
+            OsFamily::MacOs => (
+                format!(" macOS {MIN_MACOS_MAJOR} 或更高版本"),
+                format!("macOS {MIN_MACOS_MAJOR} or newer"),
+            ),
+            OsFamily::Linux => {
+                let kernel = format!("{}.{}", MIN_LINUX_KERNEL.0, MIN_LINUX_KERNEL.1);
+                let glibc = MIN_GLIBC.0;
+                (
+                    format!(" Linux 内核 ≥ {kernel}（glibc ≥ {glibc}）"),
+                    format!("Linux kernel >= {kernel} (glibc >= {glibc})"),
+                )
+            }
+        };
+        // Windows 上版本探测失败时要说清楚是「探不到」而不是「探到旧版本」。
+        let hint = if self.family == OsFamily::Windows && self.major_minor.is_none() {
+            "（未能探测到系统版本）"
+        } else {
+            ""
+        };
+        SupportText {
+            zh: format!("不支持的系统：{product}{hint}。本启动器要求{need_zh}。"),
+            en: format!("Unsupported system: {product}. This launcher requires {need_en}."),
+        }
+    }
+}
+
+/// 双语用户文案。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SupportText {
+    /// 中文文案。
+    pub zh: String,
+    /// 英文文案。
+    pub en: String,
+}
+
+impl SupportText {
+    /// 中文 + 换行 + 英文（CLI 直接打印的形态）。
+    pub fn combined(&self) -> String {
+        format!("{}\n{}", self.zh, self.en)
+    }
+}
+
+/// 启动自检结果（CLI 打印 + 写日志用）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SupportCheck {
+    /// 支持等级。
+    pub level: SupportLevel,
+    /// 用户可读文案（中英双语，多行）。
+    pub message: String,
+    /// 探测到的系统信息（写日志 / 诊断包用）。
+    pub os: OsInfo,
+}
+
+impl SupportCheck {
+    /// 是否允许继续启动。
+    pub fn is_usable(&self) -> bool {
+        self.level.is_usable()
+    }
+}
+
+/// 按家族选对应的等级判定（探测与单测走同一条路径）。
+pub fn support_level_for(
+    family: OsFamily,
+    major_minor: Option<(u32, u32)>,
+    kernel: Option<(u32, u32)>,
+    glibc: Option<(u32, u32)>,
+) -> SupportLevel {
+    match family {
+        OsFamily::Windows => windows_level(major_minor),
+        OsFamily::MacOs => macos_level(major_minor.map(|(major, _)| major)),
+        OsFamily::Linux => linux_level(kernel, glibc),
+    }
+}
+
+/// Windows 等级：≥ Windows 10 → 一等；Win8.1/8/7 及更旧 → 不支持；探测不到 → 不支持（保守）。
+pub fn windows_level(major_minor: Option<(u32, u32)>) -> SupportLevel {
+    match major_minor {
+        Some(version) if version >= MIN_WINDOWS => SupportLevel::One,
+        _ => SupportLevel::Unsupported,
+    }
+}
+
+/// macOS 等级：≥ 12 → 一等；更低或不认识 → 不支持。
+pub fn macos_level(major: Option<u32>) -> SupportLevel {
+    match major {
+        Some(major) if major >= MIN_MACOS_MAJOR => SupportLevel::One,
+        _ => SupportLevel::Unsupported,
+    }
+}
+
+/// Linux 等级：内核/glibc 探得到但过低 → 不支持；取不到（容器、musl、Termux）不阻塞 → 一等。
+pub fn linux_level(kernel: Option<(u32, u32)>, glibc: Option<(u32, u32)>) -> SupportLevel {
+    if kernel.is_some_and(|version| version < MIN_LINUX_KERNEL) {
+        return SupportLevel::Unsupported;
+    }
+    if glibc.is_some_and(|version| version < MIN_GLIBC) {
+        return SupportLevel::Unsupported;
+    }
+    SupportLevel::One
+}
+
+/// 真探一次当前系统（会起子进程，别在热路径反复调用；常规路径用 [`current`]）。
+pub fn detect() -> OsInfo {
+    let family = OsFamily::current();
+    let facts = probe(family);
+    let arch = if facts.arm64 {
+        "arm64".to_string()
+    } else {
+        family.manifest_arch().to_string()
+    };
+    let product = facts
+        .product
+        .unwrap_or_else(|| family.manifest_name().to_string());
+    OsInfo {
+        family,
+        arch,
+        major_minor: facts.major_minor,
+        build: facts.build,
+        product,
+        version_string: facts.version_string.unwrap_or_default(),
+        session: facts.session,
+        gl: facts.gl,
+        vk: vk_probe::probe_vk(),
+        kernel: facts.kernel,
+        glibc: facts.glibc,
+        support_level: support_level_for(family, facts.major_minor, facts.kernel, facts.glibc),
+    }
+}
+
+/// 三平台探测结果统一成同一形状（内部用；`None` 表示该平台没有这项事实）。
+#[derive(Default)]
+struct Facts {
+    major_minor: Option<(u32, u32)>,
+    build: Option<u32>,
+    product: Option<String>,
+    version_string: Option<String>,
+    kernel: Option<(u32, u32)>,
+    glibc: Option<(u32, u32)>,
+    session: SessionKind,
+    gl: GlProbe,
+    arm64: bool,
+}
+
+fn probe(family: OsFamily) -> Facts {
+    match family {
+        OsFamily::Windows => {
+            let version = windows_version::probe();
+            Facts {
+                major_minor: version.map(|v| v.major_minor()),
+                build: version.map(|v| v.build),
+                product: version.map(|v| v.display_name().to_string()),
+                version_string: version.map(|v| v.version_string()),
+                ..Facts::default()
+            }
+        }
+        OsFamily::MacOs => {
+            let version = macos_version::probe();
+            Facts {
+                major_minor: version.map(|v| (v.major, v.minor)),
+                product: version.map(|v| v.display_name()),
+                version_string: version.map(|v| v.version_string()),
+                arm64: version.is_some_and(|v| v.arm64),
+                ..Facts::default()
+            }
+        }
+        OsFamily::Linux => {
+            let caps = linux_caps::probe();
+            Facts {
+                major_minor: caps.kernel_version,
+                product: caps.distro,
+                version_string: caps.kernel,
+                kernel: caps.kernel_version,
+                glibc: caps.glibc,
+                session: caps.session,
+                gl: caps.gl,
+                ..Facts::default()
+            }
+        }
+    }
+}
+
+/// 进程内缓存的一次探测结果（启动时多处以它为准，避免重复起子进程）。
+pub fn current() -> &'static OsInfo {
+    static CACHED: OnceLock<OsInfo> = OnceLock::new();
+    CACHED.get_or_init(detect)
+}
+
+/// CLI 启动自检：等级 + 双语文案 + 系统信息。
+pub fn check() -> SupportCheck {
+    let os = current().clone();
+    SupportCheck {
+        level: os.support_level,
+        message: os.describe().combined(),
+        os,
+    }
+}
diff --git a/crates/core/src/platform/paths.rs b/crates/core/src/platform/paths.rs
new file mode 100644
index 0000000..afb2a8e
--- /dev/null
+++ b/crates/core/src/platform/paths.rs
@@ -0,0 +1,186 @@
+//! 宿主平台探测与标准目录解析。
+//!
+//! 环境变量读取走 [`EnvSource`] 注入，因此三模式落点可以在单测里确定性地覆盖各 OS。
+//! 设计出处：`DevDocs/PlanDoc/04-data-and-config.md` §1（三模式落点）。
+
+use std::collections::BTreeMap;
+use std::path::{Path, PathBuf};
+
+/// 需要分支处理的宿主平台族。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Platform {
+    /// Windows。
+    Windows,
+    /// macOS。
+    MacOs,
+    /// Linux 及其它 Unix。
+    Linux,
+    /// 其它（按 Linux 的 XDG 习惯兜底）。
+    Other,
+}
+
+impl Platform {
+    /// 编译目标决定的当前平台。
+    #[must_use]
+    pub const fn current() -> Self {
+        if cfg!(windows) {
+            Self::Windows
+        } else if cfg!(target_os = "macos") {
+            Self::MacOs
+        } else if cfg!(unix) {
+            Self::Linux
+        } else {
+            Self::Other
+        }
+    }
+
+    /// 稳定名（写日志 / 序列化用）。
+    #[must_use]
+    pub const fn as_str(&self) -> &'static str {
+        match self {
+            Self::Windows => "windows",
+            Self::MacOs => "macos",
+            Self::Linux => "linux",
+            Self::Other => "other",
+        }
+    }
+}
+
+/// 环境变量来源（生产用 [`ProcessEnv`]，测试用 [`MapEnv`]）。
+pub trait EnvSource {
+    /// 读一个环境变量；空串按不存在处理。
+    fn var(&self, name: &str) -> Option<String>;
+}
+
+/// 真实进程环境。
+#[derive(Debug, Clone, Copy, Default)]
+pub struct ProcessEnv;
+
+impl ProcessEnv {
+    /// 构造。
+    #[must_use]
+    pub const fn new() -> Self {
+        Self
+    }
+}
+
+impl EnvSource for ProcessEnv {
+    fn var(&self, name: &str) -> Option<String> {
+        std::env::var(name)
+            .ok()
+            .filter(|value| !value.trim().is_empty())
+    }
+}
+
+/// 固定环境（测试 / 便携化封装用）。
+#[derive(Debug, Clone, Default)]
+pub struct MapEnv {
+    vars: BTreeMap<String, String>,
+}
+
+impl MapEnv {
+    /// 空环境。
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// 链式塞一条变量：`MapEnv::new().with("HOME", "/home/u")`。
+    #[must_use]
+    pub fn with(mut self, name: &str, value: &str) -> Self {
+        self.vars.insert(name.to_owned(), value.to_owned());
+        self
+    }
+}
+
+impl EnvSource for MapEnv {
+    fn var(&self, name: &str) -> Option<String> {
+        self.vars.get(name).cloned()
+    }
+}
+
+/// 用户主目录。
+#[must_use]
+pub fn home_dir(env: &dyn EnvSource) -> Option<PathBuf> {
+    if cfg!(windows) {
+        env.var("USERPROFILE")
+            .or_else(|| env.var("HOME"))
+            .map(PathBuf::from)
+    } else {
+        env.var("HOME").map(PathBuf::from)
+    }
+}
+
+/// 可执行文件所在目录（Portable 模式的根）。
+///
+/// Linux 上 `/proc/self/exe` 由 `std` 处理；AppImage 场景下指向挂载点内的 exe，
+/// 因此 AppImage 想要「便携到 exe 旁边」需由打包层设置环境变量接管（见 §1 细节）。
+#[must_use]
+pub fn exe_dir() -> Option<PathBuf> {
+    std::env::current_exe()
+        .ok()
+        .and_then(|exe| exe.parent().map(Path::to_path_buf))
+}
+
+/// Standard 模式下的启动器数据目录（`.ULL` 的等价物）。
+///
+/// - Windows：`%APPDATA%\ULL`
+/// - macOS：`~/Library/Application Support/ULL`
+/// - Linux / 其它：`$XDG_DATA_HOME/ull`，回落 `~/.local/share/ull`
+#[must_use]
+pub fn standard_launcher_home(platform: Platform, env: &dyn EnvSource) -> Option<PathBuf> {
+    match platform {
+        Platform::Windows => roaming_app_data(env).map(|dir| dir.join("ULL")),
+        Platform::MacOs => home_dir(env).map(|home| home.join("Library/Application Support/ULL")),
+        Platform::Linux | Platform::Other => xdg_data_home(env).map(|dir| dir.join("ull")),
+    }
+}
+
+/// Standard 模式下的游戏目录（Mojang 约定，与 HMCL 的 HOME 目录一致）。
+///
+/// - Windows：`%APPDATA%\.minecraft`
+/// - macOS：`~/Library/Application Support/minecraft`
+/// - Linux / 其它：`~/.minecraft`
+#[must_use]
+pub fn standard_game_home(platform: Platform, env: &dyn EnvSource) -> Option<PathBuf> {
+    match platform {
+        Platform::Windows => roaming_app_data(env).map(|dir| dir.join(".minecraft")),
+        Platform::MacOs => {
+            home_dir(env).map(|home| home.join("Library/Application Support/minecraft"))
+        }
+        Platform::Linux | Platform::Other => home_dir(env).map(|home| home.join(".minecraft")),
+    }
+}
+
+/// `%APPDATA%`，回落 `%USERPROFILE%\AppData\Roaming`。
+fn roaming_app_data(env: &dyn EnvSource) -> Option<PathBuf> {
+    env.var("APPDATA").map(PathBuf::from).or_else(|| {
+        env.var("USERPROFILE")
+            .map(|profile| PathBuf::from(profile).join("AppData/Roaming"))
+    })
+}
+
+/// `$XDG_DATA_HOME`，回落 `~/.local/share`。
+fn xdg_data_home(env: &dyn EnvSource) -> Option<PathBuf> {
+    env.var("XDG_DATA_HOME")
+        .map(PathBuf::from)
+        .filter(|dir| dir.is_absolute())
+        .or_else(|| home_dir(env).map(|home| home.join(".local/share")))
+}
+
+/// 写成可搬运字符串：相对路径统一用 `/`（HMCL `PortablePath` 做法），绝对路径原样保留。
+#[must_use]
+pub fn to_portable_string(path: &Path) -> String {
+    let text = path.to_string_lossy();
+    if path.is_absolute() {
+        text.into_owned()
+    } else {
+        text.replace('\\', "/")
+    }
+}
+
+/// 解析可搬运字符串。
+#[must_use]
+pub fn from_portable_string(text: &str) -> PathBuf {
+    PathBuf::from(text)
+}
diff --git a/crates/core/src/platform/receipt.rs b/crates/core/src/platform/receipt.rs
new file mode 100644
index 0000000..5ea0a02
--- /dev/null
+++ b/crates/core/src/platform/receipt.rs
@@ -0,0 +1,202 @@
+//! 迁移收据：指纹 + 幂等，防重复迁移 / 半迁移（HMCL `MigrationReceipt` 思想）。
+//!
+//! 出处：`DevDocs/analyse/07-settings-packaging-update.md` §1.8——
+//! 收据里存源文件 `sourceSHA256`，这样「用户删掉新文件、但旧文件没变」时不会重复迁移，旧文件变了才重放。
+
+use std::path::{Path, PathBuf};
+
+use serde::{Deserialize, Serialize};
+
+use super::atomic;
+use super::error::PlatformError;
+use super::error::PlatformResult;
+use super::hash;
+
+/// 本实现能读懂的收据版本。
+pub const RECEIPT_SCHEMA_VERSION: u32 = 1;
+
+/// 收据类型。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ReceiptKind {
+    /// 数据目录迁移。
+    DataDirMove,
+    /// 遗留配置格式迁移。
+    LegacyConfig,
+}
+
+impl ReceiptKind {
+    /// 稳定名。
+    #[must_use]
+    pub const fn as_str(&self) -> &'static str {
+        match self {
+            Self::DataDirMove => "data_dir_move",
+            Self::LegacyConfig => "legacy_config",
+        }
+    }
+}
+
+/// 一次已完成的迁移记录。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct MigrationReceipt {
+    /// 格式版本。
+    pub schema_version: u32,
+    /// 收据类型。
+    pub kind: ReceiptKind,
+    /// 源指纹（普通配置迁移 = 源文件内容 SHA-256；目录迁移 = 源/目标路径签名）。
+    pub source_fingerprint: String,
+    /// 源路径。
+    pub source: PathBuf,
+    /// 目标路径。
+    pub target: PathBuf,
+    /// 完成时间（毫秒 since UNIX_EPOCH）。
+    pub applied_at_ms: u64,
+}
+
+impl MigrationReceipt {
+    /// 构造数据目录迁移收据。
+    #[must_use]
+    pub fn data_dir_move(source: PathBuf, target: PathBuf, applied_at_ms: u64) -> Self {
+        let fingerprint = fingerprint_data_dir_move(&source, &target);
+        Self {
+            schema_version: RECEIPT_SCHEMA_VERSION,
+            kind: ReceiptKind::DataDirMove,
+            source_fingerprint: fingerprint,
+            source,
+            target,
+            applied_at_ms,
+        }
+    }
+
+    /// 构造遗留配置迁移收据。
+    #[must_use]
+    pub fn legacy_config(
+        source: PathBuf,
+        target: PathBuf,
+        source_fingerprint: impl Into<String>,
+        applied_at_ms: u64,
+    ) -> Self {
+        Self {
+            schema_version: RECEIPT_SCHEMA_VERSION,
+            kind: ReceiptKind::LegacyConfig,
+            source_fingerprint: source_fingerprint.into(),
+            source,
+            target,
+            applied_at_ms,
+        }
+    }
+}
+
+/// 是否该重放这次迁移。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ReplayDecision {
+    /// 收据在且源指纹相同 → 已经迁过，跳过（防重放）。
+    SkipSameSource,
+    /// 收据在但源指纹变了 → 允许重放。
+    ReplayChangedSource,
+    /// 没有收据 → 正常迁移。
+    ReplayNoReceipt,
+}
+
+impl ReplayDecision {
+    /// 是否需要执行迁移。
+    #[must_use]
+    pub const fn should_replay(&self) -> bool {
+        !matches!(self, Self::SkipSameSource)
+    }
+
+    /// 稳定名（日志 / 审计）。
+    #[must_use]
+    pub const fn as_str(&self) -> &'static str {
+        match self {
+            Self::SkipSameSource => "skip_same_source",
+            Self::ReplayChangedSource => "replay_changed_source",
+            Self::ReplayNoReceipt => "replay_no_receipt",
+        }
+    }
+}
+
+/// 根据已有收据与当前源指纹决定是否重放。
+#[must_use]
+pub fn decide(existing: Option<&MigrationReceipt>, fingerprint: &str) -> ReplayDecision {
+    match existing {
+        None => ReplayDecision::ReplayNoReceipt,
+        Some(receipt) if receipt.source_fingerprint == fingerprint => {
+            ReplayDecision::SkipSameSource
+        }
+        Some(_) => ReplayDecision::ReplayChangedSource,
+    }
+}
+
+/// 读收据；不存在返回 `None`。
+///
+/// # Errors
+/// 读失败或 JSON 损坏、版本不认识时返回 [`PlatformError::ReceiptCorrupt`] / [`PlatformError::Io`]。
+pub fn read(path: &Path) -> PlatformResult<Option<MigrationReceipt>> {
+    let Some(bytes) = atomic::read_optional(path)? else {
+        return Ok(None);
+    };
+    let receipt: MigrationReceipt =
+        serde_json::from_slice(&bytes).map_err(|err| PlatformError::ReceiptCorrupt {
+            path: path.to_path_buf(),
+            reason: err.to_string(),
+        })?;
+    if receipt.schema_version > RECEIPT_SCHEMA_VERSION {
+        return Err(PlatformError::ReceiptCorrupt {
+            path: path.to_path_buf(),
+            reason: format!(
+                "收据版本 {} 高于本实现支持的 {RECEIPT_SCHEMA_VERSION}",
+                receipt.schema_version
+            ),
+        });
+    }
+    Ok(Some(receipt))
+}
+
+/// 原子写收据。
+///
+/// # Errors
+/// 序列化或写盘失败时返回 [`PlatformError`]。
+pub fn write(path: &Path, receipt: &MigrationReceipt) -> PlatformResult<()> {
+    let bytes =
+        serde_json::to_vec_pretty(receipt).map_err(|err| PlatformError::ReceiptCorrupt {
+            path: path.to_path_buf(),
+            reason: format!("无法序列化收据: {err}"),
+        })?;
+    atomic::write_atomic(path, &bytes)
+}
+
+/// 内容指纹（SHA-256 十六进制）。
+#[must_use]
+pub fn fingerprint_bytes(bytes: &[u8]) -> String {
+    hash::sha256_hex(bytes)
+}
+
+/// 文件内容指纹；文件不存在返回 `None`。
+///
+/// # Errors
+/// 读失败时返回 [`PlatformError::Io`]。
+pub fn fingerprint_file(path: &Path) -> PlatformResult<Option<String>> {
+    match hash::sha256_hex_file(path) {
+        Ok(hex) => Ok(Some(hex)),
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(None),
+        Err(err) => Err(PlatformError::Io {
+            path: path.to_path_buf(),
+            source: err,
+        }),
+    }
+}
+
+/// 目录迁移的源指纹：源/目标路径签名。
+///
+/// 目录内容的哈希代价太高且天然易变（缓存/日志一直在动），因此目录迁移的抗重放主力是
+/// [`super::redirect`] 指针 + 「目标非空则拒绝」，收据负责留痕与「同源同目标不重做」。
+#[must_use]
+pub fn fingerprint_data_dir_move(source: &Path, target: &Path) -> String {
+    let signature = format!(
+        "{}|{}",
+        super::paths::to_portable_string(source),
+        super::paths::to_portable_string(target)
+    );
+    fingerprint_bytes(signature.as_bytes())
+}
diff --git a/crates/core/src/platform/redirect.rs b/crates/core/src/platform/redirect.rs
new file mode 100644
index 0000000..aa16a2f
--- /dev/null
+++ b/crates/core/src/platform/redirect.rs
@@ -0,0 +1,137 @@
+//! `redirect.json` 指针文件——迁移后留在旧目录，防止便携盘被搬走后旧目录重新长出一个新实例。
+//!
+//! 出处：`DevDocs/PlanDoc/04-data-and-config.md` §1 细节（「迁移 = 移动 + 原地留 redirect.json 指针」）。
+
+use std::collections::BTreeSet;
+use std::path::{Path, PathBuf};
+
+use serde::{Deserialize, Serialize};
+
+use super::atomic;
+use super::data_dir::DataMode;
+use super::error::{io_at, PlatformError, PlatformResult};
+use super::layout::REDIRECT_FILE;
+
+/// 本实现能读懂的指针文件版本；更高版本视为不认识（避免瞎读新格式）。
+pub const REDIRECT_SCHEMA_VERSION: u32 = 1;
+
+/// 指针内容：旧目录 → 新目录。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct RedirectPointer {
+    /// 格式版本。
+    pub schema_version: u32,
+    /// 迁移时采用的模式。
+    pub mode: DataMode,
+    /// 新的启动器数据目录。
+    pub launcher_home: PathBuf,
+    /// 新的游戏目录。
+    pub game_home: PathBuf,
+    /// 迁移时间（毫秒 since UNIX_EPOCH）。
+    pub migrated_at_ms: u64,
+}
+
+/// 跟随指针的结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Followed {
+    /// 最终命中的指针。
+    pub pointer: RedirectPointer,
+    /// 实际跟随跳数（1 = 只跟了一跳）。
+    pub hops: usize,
+}
+
+/// `<dir>/redirect.json`。
+#[must_use]
+pub fn redirect_path(dir: &Path) -> PathBuf {
+    dir.join(REDIRECT_FILE)
+}
+
+/// 读指针；没有指针文件返回 `None`。
+///
+/// # Errors
+/// 读失败或 JSON 损坏、版本不认识时返回 [`PlatformError`]。
+pub fn read(dir: &Path) -> PlatformResult<Option<RedirectPointer>> {
+    let path = redirect_path(dir);
+    let Some(bytes) = atomic::read_optional(&path)? else {
+        return Ok(None);
+    };
+    let pointer: RedirectPointer =
+        serde_json::from_slice(&bytes).map_err(|err| PlatformError::RedirectCorrupt {
+            path: path.clone(),
+            reason: err.to_string(),
+        })?;
+    if pointer.schema_version > REDIRECT_SCHEMA_VERSION {
+        return Err(PlatformError::RedirectCorrupt {
+            path,
+            reason: format!(
+                "指针版本 {} 高于本实现支持的 {REDIRECT_SCHEMA_VERSION}",
+                pointer.schema_version
+            ),
+        });
+    }
+    Ok(Some(pointer))
+}
+
+/// 原子写指针（父目录自动创建）。
+///
+/// # Errors
+/// 序列化或写盘失败时返回 [`PlatformError`]。
+pub fn write(dir: &Path, pointer: &RedirectPointer) -> PlatformResult<PathBuf> {
+    let path = redirect_path(dir);
+    let bytes =
+        serde_json::to_vec_pretty(pointer).map_err(|err| PlatformError::RedirectCorrupt {
+            path: path.clone(),
+            reason: format!("无法序列化指针: {err}"),
+        })?;
+    std::fs::create_dir_all(dir).map_err(io_at(dir))?;
+    atomic::write_atomic(&path, &bytes)?;
+    Ok(path)
+}
+
+/// 删除指针（`None` = 本来就没有）。
+///
+/// # Errors
+/// 删除失败时返回 [`PlatformError::Io`]。
+pub fn remove(dir: &Path) -> PlatformResult<bool> {
+    let path = redirect_path(dir);
+    match std::fs::remove_file(&path) {
+        Ok(()) => Ok(true),
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(false),
+        Err(err) => Err(PlatformError::Io { path, source: err }),
+    }
+}
+
+/// 跟随指针链（最多 `max_hops` 跳，成环或超限报错）。
+///
+/// # Errors
+/// 指针损坏或跳转成环/超限时返回 [`PlatformError`]。
+pub fn follow(dir: &Path, max_hops: usize) -> PlatformResult<Option<Followed>> {
+    let mut current = dir.to_path_buf();
+    let mut visited: BTreeSet<PathBuf> = BTreeSet::new();
+    visited.insert(current.clone());
+    let mut hops = 0usize;
+
+    loop {
+        let Some(pointer) = read(&current)? else {
+            return Ok(None);
+        };
+        hops += 1;
+        if hops > max_hops {
+            return Err(PlatformError::RedirectCycle {
+                dir: dir.to_path_buf(),
+                hops,
+            });
+        }
+        let next = pointer.launcher_home.clone();
+        if !visited.insert(next.clone()) {
+            return Err(PlatformError::RedirectCycle {
+                dir: dir.to_path_buf(),
+                hops,
+            });
+        }
+        // 还有下一跳就继续跟，否则这就是终点。
+        if !redirect_path(&next).exists() {
+            return Ok(Some(Followed { pointer, hops }));
+        }
+        current = next;
+    }
+}
diff --git a/crates/core/src/platform/theme_probe.rs b/crates/core/src/platform/theme_probe.rs
new file mode 100644
index 0000000..e1216de
--- /dev/null
+++ b/crates/core/src/platform/theme_probe.rs
@@ -0,0 +1,182 @@
+//! 系统主题（浅色/深色）探测：给主题三态的 `auto` 模式做**初始化对齐**与后端不支持时的兜底跟随。
+//!
+//! 出处：`DevDocs/PlanDoc/09-ui-layout.md` §2「主题模式三态」（D17 用户定案：Win/mac 用 Slint
+//! `Palette.color-scheme` 原生跟随 OS 热切；Linux 依 DE 的 xdg-desktop-portal，缺省回落浅色并
+//! 允许手动钉死）。Slint 后端会在运行期自己监听 OS 主题变化，所以这里**只补两件事**：
+//!
+//! 1. 启动时先读一次真实系统主题，避免「auto 模式下首帧按浅色画、几百毫秒后突然翻黑」的闪变；
+//! 2. 后端把 `Palette.color-scheme` 报成 `unknown`（无 portal 的 Linux / 软渲染后端）时，
+//!    由 app 轮询本模块把系统主题补上，`auto` 仍然可用。
+//!
+//! 与 platform 层其他探测一致（见 [`super::windows_version`]）：core 是 `#![forbid(unsafe_code)]`，
+//! 一律走外部命令 + 纯函数解析。解析函数跨平台编译，任意宿主都能单测（`tests/platform/theme_cases.rs`）。
+
+/// 系统主题三态。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SystemTheme {
+    /// 浅色。
+    Light,
+    /// 深色。
+    Dark,
+    /// 读不到（无桌面环境 / 命令缺失 / 输出无法解析）。
+    Unknown,
+}
+
+impl SystemTheme {
+    /// 稳定名（日志用）。
+    #[must_use]
+    pub const fn as_str(&self) -> &'static str {
+        match self {
+            Self::Light => "light",
+            Self::Dark => "dark",
+            Self::Unknown => "unknown",
+        }
+    }
+
+    /// 是否深色（`Unknown` 为 `None`，调用方决定回落）。
+    #[must_use]
+    pub const fn is_dark(&self) -> Option<bool> {
+        match self {
+            Self::Light => Some(false),
+            Self::Dark => Some(true),
+            Self::Unknown => None,
+        }
+    }
+}
+
+/// Windows 个性化键（`AppsUseLightTheme` = 应用/任务栏主题，与 `SystemUsesLightTheme` 区分）。
+pub const WINDOWS_PERSONALIZE_KEY: &str =
+    r"HKCU\Software\Microsoft\Windows\CurrentVersion\Themes\Personalize";
+
+/// 真实探测系统主题。
+///
+/// - Windows：注册表 `AppsUseLightTheme`（DWORD，1 = 浅色 / 0 = 深色）；
+/// - macOS：`defaults read -g AppleInterfaceStyle`（深色时输出 `Dark`，浅色时该键不存在）；
+/// - Linux：`gsettings get org.gnome.desktop.interface color-scheme`，退到 `gtk-theme` 名字。
+#[must_use]
+pub fn probe() -> SystemTheme {
+    #[cfg(target_os = "windows")]
+    {
+        run(
+            "reg",
+            &["query", WINDOWS_PERSONALIZE_KEY, "/v", "AppsUseLightTheme"],
+        )
+        .and_then(|text| parse_apps_use_light_theme(&text))
+        .unwrap_or(SystemTheme::Unknown)
+    }
+    #[cfg(target_os = "macos")]
+    {
+        // 键不存在 = 浅色（defaults 会非零退出，stdout 为空 → 回落 Light）。
+        match run("defaults", &["read", "-g", "AppleInterfaceStyle"]) {
+            Some(text) => parse_macos_interface_style(&text).unwrap_or(SystemTheme::Unknown),
+            None => SystemTheme::Light,
+        }
+    }
+    #[cfg(not(any(target_os = "windows", target_os = "macos")))]
+    {
+        probe_linux()
+    }
+}
+
+/// Linux：先问 GNOME/portal 的 `color-scheme`，再退到 `gtk-theme` 名字里是否带 `-dark`。
+#[cfg(not(any(target_os = "windows", target_os = "macos")))]
+fn probe_linux() -> SystemTheme {
+    if let Some(text) = run(
+        "gsettings",
+        &["get", "org.gnome.desktop.interface", "color-scheme"],
+    ) {
+        if let Some(theme) = parse_gsettings_color_scheme(&text) {
+            return theme;
+        }
+    }
+    if let Some(text) = run(
+        "gsettings",
+        &["get", "org.gnome.desktop.interface", "gtk-theme"],
+    ) {
+        if let Some(theme) = parse_gtk_theme(&text) {
+            return theme;
+        }
+    }
+    SystemTheme::Unknown
+}
+
+/// 解析 `reg query ... /v AppsUseLightTheme` 的输出。
+///
+/// 形如 `    AppsUseLightTheme    REG_DWORD    0x1`；`0x0` = 深色。
+#[must_use]
+pub fn parse_apps_use_light_theme(text: &str) -> Option<SystemTheme> {
+    text.lines().find_map(|line| {
+        let mut fields = line.split_whitespace();
+        let name = fields.next()?;
+        if !name.eq_ignore_ascii_case("AppsUseLightTheme") {
+            return None;
+        }
+        let _kind = fields.next()?;
+        let raw = fields.next().unwrap_or_default();
+        parse_dword(raw).map(|value| {
+            if value == 0 {
+                SystemTheme::Dark
+            } else {
+                SystemTheme::Light
+            }
+        })
+    })
+}
+
+/// 解析 `defaults read -g AppleInterfaceStyle` 的输出（深色 = `Dark`；浅色时该键不存在）。
+#[must_use]
+pub fn parse_macos_interface_style(text: &str) -> Option<SystemTheme> {
+    match text.trim() {
+        "" => None,
+        value if value.eq_ignore_ascii_case("dark") => Some(SystemTheme::Dark),
+        _ => Some(SystemTheme::Light),
+    }
+}
+
+/// 解析 `gsettings get ... color-scheme`：`'prefer-dark'` / `'prefer-light'` / `'default'`。
+///
+/// `default` 表示「未指定」，要继续看 `gtk-theme`，故返回 `None`。
+#[must_use]
+pub fn parse_gsettings_color_scheme(text: &str) -> Option<SystemTheme> {
+    let value = text.trim().trim_matches('\'').trim_matches('"');
+    if value.eq_ignore_ascii_case("prefer-dark") {
+        Some(SystemTheme::Dark)
+    } else if value.eq_ignore_ascii_case("prefer-light") {
+        Some(SystemTheme::Light)
+    } else {
+        None
+    }
+}
+
+/// 解析 `gsettings get ... gtk-theme`：主题名带 `dark` 即深色（`Yaru-dark`、`Adwaita-dark`）。
+#[must_use]
+pub fn parse_gtk_theme(text: &str) -> Option<SystemTheme> {
+    let value = text.trim().trim_matches('\'').trim_matches('"');
+    if value.is_empty() {
+        return None;
+    }
+    if value.to_ascii_lowercase().contains("dark") {
+        Some(SystemTheme::Dark)
+    } else {
+        Some(SystemTheme::Light)
+    }
+}
+
+fn parse_dword(raw: &str) -> Option<u32> {
+    let raw = raw.trim();
+    if let Some(hex) = raw.strip_prefix("0x").or_else(|| raw.strip_prefix("0X")) {
+        u32::from_str_radix(hex, 16).ok()
+    } else {
+        raw.parse().ok()
+    }
+}
+
+/// 跑一个外部命令，取 stdout（命令缺失 / 非零退出 / 空输出都返回 `None`）。
+fn run(program: &str, args: &[&str]) -> Option<String> {
+    use std::process::Command;
+    let output = Command::new(program).args(args).output().ok()?;
+    if output.stdout.is_empty() {
+        return None;
+    }
+    Some(String::from_utf8_lossy(&output.stdout).into_owned())
+}
diff --git a/crates/core/src/platform/vk_probe.rs b/crates/core/src/platform/vk_probe.rs
new file mode 100644
index 0000000..25a817e
--- /dev/null
+++ b/crates/core/src/platform/vk_probe.rs
@@ -0,0 +1,305 @@
+//! Vulkan 能力探测的**安全层**（无 `unsafe`，无 FFI）：只报可观测事实，不下「能不能玩」的结论。
+//!
+//! 依据 `DevDocs/PlanDoc/research/05-mc-vulkan.md`（M26）§2.3 与 §4.3：
+//! MC 的 Vulkan 后端在 Windows/Linux 上**不打包** `vulkan-1.dll` / `libvulkan.so.1`，
+//! 而是运行期去加载系统的 loader（natives 只给 macOS 发 MoltenVK）。所以「版本支持 Vulkan」
+//! 与「这台机器能跑 Vulkan」是两件事，前置探测不可省。
+//!
+//! 分工照抄 [`super::linux_caps::probe_gl`]：core 只做「文件存在性 / 注册表 / 环境变量 /
+//! 标准目录」这一层，真探测（建 instance、枚举物理设备、查 `VK 1.2` +
+//! `VK_KHR_dynamic_rendering` + `VK_KHR_push_descriptor` 三项硬门槛）归 app 层。
+//!
+//! # ⚠️ 注册表键缺失 ≠ 没有 Vulkan（真机证据）
+//!
+//! 实测机（Windows 11 + AMD 独显，Vulkan 1.3.217 可用）上
+//! `HKLM\SOFTWARE\Khronos\Vulkan\Drivers` **压根不存在**——ICD 由 loader 自己按
+//! `%SystemRoot%\System32` 与驱动安装目录自寻。因此该键只作**加分项**（[`VkProbe::Available`]），
+//! 缺失时降级为 [`VkProbe::LoaderOnly`]、**绝不**判 [`VkProbe::Missing`]。
+//!
+//! 解析函数是纯函数且跨平台编译，单测用注入样本覆盖三平台（见 `tests/platform/vk_cases.rs`）。
+
+use std::path::{Path, PathBuf};
+
+use crate::platform::os_info::OsFamily;
+
+/// Windows 上的 Vulkan loader 文件名（系统目录内）。
+pub const WINDOWS_LOADER: &str = "vulkan-1.dll";
+
+/// `HKLM\SOFTWARE\Khronos\Vulkan\Drivers`：显式 ICD 注册键（**只作加分**，见模块文档）。
+///
+/// ICD 注册为这个键下的**值**（值名 = manifest 绝对路径，数据是 `dword:00000000`），
+/// 不是子键（Vulkan-Loader `LoaderDriverInterface.md` 的 Windows 驱动发现一节）。
+pub const VULKAN_DRIVERS_KEY: &str = r"HKLM\SOFTWARE\Khronos\Vulkan\Drivers";
+
+/// 同一个键在 `reg query` 输出里的**键头行**形态。
+///
+/// `reg query` 即使传入缩写 hive 名（`HKLM`），输出也用完整 hive 名
+/// （`HKEY_LOCAL_MACHINE`）且不带尾反斜杠——解析时必须按这个形态比对。
+pub const VULKAN_DRIVERS_KEY_HEADER: &str = r"HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\Vulkan\Drivers";
+
+/// Khronos loader 认的 ICD 路径环境变量（旧名在前，新名在后）。
+pub const ICD_ENV_VARS: &[&str] = &["VK_ICD_FILENAMES", "VK_DRIVER_FILES"];
+
+/// Linux 的 ICD 清单目录（`*.json`，loader 启动时按此枚举驱动）。
+pub const ICD_DIRS: &[&str] = &[
+    "/usr/share/vulkan/icd.d",
+    "/usr/local/share/vulkan/icd.d",
+    "/etc/vulkan/icd.d",
+];
+
+/// Vulkan 能力（四档；`Unknown` 是派生默认值，「没探过」不等于「没有」）。
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub enum VkProbe {
+    /// 未探测（非探测路径构造的快照）。
+    #[default]
+    Unknown,
+    /// loader 在，但没有看到任何 ICD 注册信号。
+    ///
+    /// **不是**「没有 Vulkan」：Windows 上注册表键缺失是常态（模块文档的真机证据），
+    /// 设备是否存在要靠 app 层的真探测确认。
+    LoaderOnly,
+    /// loader + 驱动信号都在（或 macOS 上 MoltenVK 在场）——大概率可用。
+    Available,
+    /// 连 loader 都找不到：Vulkan 后端一定起不来。
+    Missing,
+}
+
+impl VkProbe {
+    /// 简短名（日志/摘要行用）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Unknown => "unknown",
+            Self::LoaderOnly => "loader_only",
+            Self::Available => "available",
+            Self::Missing => "missing",
+        }
+    }
+
+    /// loader 是否在场（`Available` 与 `LoaderOnly` 都为真）。
+    #[must_use]
+    pub const fn has_loader(self) -> bool {
+        matches!(self, Self::Available | Self::LoaderOnly)
+    }
+
+    /// 是否已能确定「这台机器跑不了 Vulkan」（只有 [`Self::Missing`]）。
+    #[must_use]
+    pub const fn is_missing(self) -> bool {
+        matches!(self, Self::Missing)
+    }
+
+    /// 是否足够确定「可以用 Vulkan」（只有 [`Self::Available`]）。
+    ///
+    /// UI/建议路径用它可以保守一点：`LoaderOnly` 应当提示「先试一次再说」而不是承诺可用。
+    #[must_use]
+    pub const fn is_available(self) -> bool {
+        matches!(self, Self::Available)
+    }
+}
+
+/// 平台无关的探测证据（单测直接注入，不读真机）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct VkEvidence {
+    /// 系统家族（决定判定口径）。
+    pub family: OsFamily,
+    /// loader 文件是否找到（`vulkan-1.dll` / `libvulkan.so.1` / `libvulkan.1.dylib` / MoltenVK）。
+    pub loader_present: bool,
+    /// 是否看到驱动信号：Windows 注册表键、Linux 的 ICD 目录/环境变量、macOS 无此项。
+    pub icd_signal: bool,
+}
+
+impl VkEvidence {
+    /// 构造。
+    #[must_use]
+    pub const fn new(family: OsFamily, loader_present: bool, icd_signal: bool) -> Self {
+        Self {
+            family,
+            loader_present,
+            icd_signal,
+        }
+    }
+}
+
+/// 证据 → 结论（纯函数，三平台共用；macOS 单独口径见函数体注释）。
+#[must_use]
+pub fn classify(evidence: VkEvidence) -> VkProbe {
+    if evidence.family == OsFamily::MacOs {
+        // macOS 没有系统 Vulkan：LWJGL 自带的 MoltenVK 既是 loader 又是 ICD（Vulkan→Metal 翻译），
+        // 所以「MoltenVK/libvulkan.1.dylib 在」本身就是可用证据，没有 LoaderOnly 这一档。
+        return if evidence.loader_present {
+            VkProbe::Available
+        } else {
+            VkProbe::Missing
+        };
+    }
+    if !evidence.loader_present {
+        return VkProbe::Missing;
+    }
+    if evidence.icd_signal {
+        VkProbe::Available
+    } else {
+        // 注册表键缺失是常态，只降级不否定（模块文档的真机证据）。
+        VkProbe::LoaderOnly
+    }
+}
+
+/// 探测当前机器的 Vulkan 能力（一次性，结果由 [`crate::platform::os_info::current`] 缓存）。
+#[must_use]
+pub fn probe_vk() -> VkProbe {
+    classify(probe_evidence())
+}
+
+/// 采集当前机器的探测证据（真读盘/注册表；单测请直接用 [`classify`]）。
+#[must_use]
+pub fn probe_evidence() -> VkEvidence {
+    let family = OsFamily::current();
+    VkEvidence::new(family, loader_present(family), icd_signal(family))
+}
+
+/// loader 候选绝对路径（按平台；`SystemRoot` 缺失时回落到 `C:\Windows`）。
+#[must_use]
+pub fn loader_candidates(family: OsFamily) -> Vec<PathBuf> {
+    match family {
+        OsFamily::Windows => {
+            let root = std::env::var("SystemRoot").unwrap_or_else(|_| r"C:\Windows".to_owned());
+            vec![Path::new(&root).join("System32").join(WINDOWS_LOADER)]
+        }
+        OsFamily::MacOs => [
+            "/usr/local/lib/libvulkan.1.dylib",
+            "/opt/homebrew/lib/libvulkan.1.dylib",
+            "/usr/local/lib/libvulkan.dylib",
+            "/opt/homebrew/lib/libvulkan.dylib",
+            // MC 的 lwjgl-vulkan natives 里带的就是这个。
+            "/usr/local/lib/libMoltenVK.dylib",
+            "/opt/homebrew/lib/libMoltenVK.dylib",
+        ]
+        .iter()
+        .map(PathBuf::from)
+        .collect(),
+        OsFamily::Linux => [
+            "/usr/lib/x86_64-linux-gnu/libvulkan.so.1",
+            "/usr/lib/aarch64-linux-gnu/libvulkan.so.1",
+            "/usr/lib64/libvulkan.so.1",
+            "/usr/lib/libvulkan.so.1",
+            "/usr/local/lib/libvulkan.so.1",
+            // 开发包只给不带版本号的名字（`libvulkan.so`）。
+            "/usr/lib/x86_64-linux-gnu/libvulkan.so",
+            "/usr/lib64/libvulkan.so",
+            "/usr/local/lib/libvulkan.so",
+        ]
+        .iter()
+        .map(PathBuf::from)
+        .collect(),
+    }
+}
+
+fn loader_present(family: OsFamily) -> bool {
+    if loader_candidates(family).iter().any(|path| path.is_file()) {
+        return true;
+    }
+    // 标准路径没命中时，Linux 用 `ldconfig -p` 兜底（发行版把 loader 放在别处时更权威）。
+    #[cfg(target_os = "linux")]
+    {
+        ldconfig_has_libvulkan(&run("ldconfig", &["-p"]).unwrap_or_default())
+    }
+    #[cfg(not(target_os = "linux"))]
+    {
+        false
+    }
+}
+
+fn icd_signal(family: OsFamily) -> bool {
+    match family {
+        OsFamily::Windows => {
+            let text = run("reg", &["query", VULKAN_DRIVERS_KEY]).unwrap_or_default();
+            registry_has_driver_entry(&text)
+        }
+        OsFamily::Linux => {
+            env_icd_path(|key| std::env::var(key).ok()).is_some()
+                || ICD_DIRS
+                    .iter()
+                    .any(|dir| count_icd_manifests(Path::new(dir)) > 0)
+        }
+        // macOS 的 ICD 就是 MoltenVK 本身，已在 loader 判据里。
+        OsFamily::MacOs => false,
+    }
+}
+
+/// 从环境变量取 ICD 清单路径（`VK_ICD_FILENAMES` 优先，其次 `VK_DRIVER_FILES`）。
+#[must_use]
+pub fn env_icd_path(get: impl Fn(&str) -> Option<String>) -> Option<String> {
+    ICD_ENV_VARS.iter().find_map(|key| {
+        get(key)
+            .map(|value| value.trim().to_owned())
+            .filter(|value| !value.is_empty())
+    })
+}
+
+/// 目录下 `*.json` ICD 清单的条数（目录不存在返回 0）。
+#[must_use]
+pub fn count_icd_manifests(dir: &Path) -> usize {
+    let Ok(entries) = std::fs::read_dir(dir) else {
+        return 0;
+    };
+    entries
+        .flatten()
+        .filter(|entry| {
+            entry
+                .path()
+                .extension()
+                .is_some_and(|ext| ext.eq_ignore_ascii_case("json"))
+        })
+        .count()
+}
+
+/// `reg query <键>`（**不带** `/s`）的输出里，该键是否存在**值项**。
+///
+/// 真实格式（本机实测，Win11 22H2）：一个空行 → 键头行（顶格、用完整 hive 名、无尾反斜杠）
+/// → 缩进的值行 `    <值名>    REG_DWORD    0x0`。Vulkan 的 ICD 注册正是「**值名 = manifest
+/// 绝对路径**」（`"C:\vendor\vk.json"=dword:00000000`，见 Vulkan-Loader
+/// `LoaderDriverInterface.md` 的 Windows 驱动发现一节），不是子键。
+///
+/// 所以判据是「键头行 + 其后至少一条带 `REG_` 类型标记的缩进行」：键存在但没有任何值时
+/// 只有键头行；子键在没有 `/s` 时也缩进打印，但**不带** `REG_` 标记，据此区分。键不存在时
+/// 输出只有本地化错误行（`ERROR: The system was unable to find…` /
+/// `错误: 系统找不到指定的注册表项或值。`），既无键头也无数值行。
+///
+/// 注：值名可能含空格（manifest 绝对路径），所以不能按列切分，只能按 token 找类型标记。
+#[must_use]
+pub fn registry_has_driver_entry(text: &str) -> bool {
+    let mut in_key = false;
+    for line in text.lines() {
+        let trimmed = line.trim();
+        if trimmed.is_empty() {
+            continue;
+        }
+        if !line.starts_with([' ', '\t']) {
+            // 顶格行 = 键头行（或错误行）；遇到别的键就重置状态。
+            in_key = trimmed
+                .trim_end_matches('\\')
+                .eq_ignore_ascii_case(VULKAN_DRIVERS_KEY_HEADER);
+            continue;
+        }
+        if in_key && trimmed.split_whitespace().any(|t| t.starts_with("REG_")) {
+            return true;
+        }
+    }
+    false
+}
+
+/// `ldconfig -p` 输出里是否列了 `libvulkan.so.1`。
+#[must_use]
+pub fn ldconfig_has_libvulkan(text: &str) -> bool {
+    text.lines()
+        .any(|line| line.contains("libvulkan.so.1") || line.contains("libvulkan.so "))
+}
+
+/// 跑一个只读命令取 stdout（`reg query` / `ldconfig -p`；失败返回 `None`）。
+fn run(program: &str, args: &[&str]) -> Option<String> {
+    use std::process::Command;
+    let output = Command::new(program).args(args).output().ok()?;
+    if output.stdout.is_empty() {
+        return None;
+    }
+    Some(String::from_utf8_lossy(&output.stdout).into_owned())
+}
diff --git a/crates/core/src/platform/wallpaper.rs b/crates/core/src/platform/wallpaper.rs
new file mode 100644
index 0000000..03e803a
--- /dev/null
+++ b/crates/core/src/platform/wallpaper.rs
@@ -0,0 +1,358 @@
+//! 桌面壁纸**路径探测**（D38 配色三级优先里的第②级输入）。
+//!
+//! 用户原话（D38，2026-11-01）：「如果用户设置了启动器背景图，则使用莫奈取色从背景图取，
+//! 没有背景图时用户也可以开启莫奈取色，此时从桌面壁纸取色。」本模块只承担中间那一级的
+//! **输入**：按可信度给出「这台机器的桌面壁纸可能是哪个文件」的有序候选列表。
+//!
+//! # 边界（只做路径探测）
+//!
+//! - **不解码图片、不取色、不生成调色板**。莫奈取色本身、D38 三级降级、
+//!   「取色失败回落到色卡当前选择 + 设置页可读提示」都在 `crates/design` 的后续 mission。
+//! - 全部找不到时返回**空列表**（[`WallpaperProbe::is_empty`]）而不是错误：没有桌面壁纸是
+//!   正常状态（服务器、无桌面环境、壁纸是纯色），调用方按 D38 直接落到第③级色卡。
+//! - **零 `unsafe`、零 FFI**（core 是 `#![forbid(unsafe_code)]`）：不用
+//!   `SystemParametersInfo(SPI_GETDESKWALLPAPER)`、不碰 win32 注册表 API，全部走文件读取与
+//!   `reg.exe` / `gsettings` / `defaults` 子进程——与 [`super::theme_probe`]、
+//!   [`super::windows_version`] 同一套路子。
+//!
+//! # 分层与可测性
+//!
+//! - 采集逻辑按平台分文件（`windows` / `linux` / `macos` 子模块），**无条件编译**、不按
+//!   `cfg` 裁剪：CI 是 Linux，Windows / macOS 的夹具用例同样要能在那里跑；
+//! - 平台分流只发生在 [`detect_with`] 一处；
+//! - 外部 IO 全部经 [`ProbeIo`]（文件内容 / 文件头 / 目录列表 / 子进程）与
+//!   [`EnvSource`]（环境变量表）注入，[`detect`] 只是把它们换成真实实现。
+//!
+//! # 什么算「候选壁纸」
+//!
+//! 只收「归一化后是绝对路径 + 文件头认得出是图片」的条目（魔数集合见 `parse` 子模块的
+//! `looks_like_image`）。这条校验既挡掉过期配置里指向已删除文件的路径，也挡掉 macOS
+//! 二进制 plist 字符串扫描出的碎片串。
+
+use std::path::PathBuf;
+
+use crate::platform::paths::{EnvSource, Platform, ProcessEnv};
+
+use self::io::{HostIo, HostRoots, ProbeIo};
+use self::parse::{looks_like_image, normalize_path};
+
+mod io;
+mod linux;
+mod macos;
+mod parse;
+mod windows;
+
+/// 读文件头做魔数嗅探时的字节数（够 `ftyp` 分支与文本 SVG 头）。
+const IMAGE_HEAD_LEN: usize = 512;
+
+/// 一个候选壁纸是**怎么被找到的**：平台 + 桌面环境标识。
+///
+/// 标识只表示「这条路径从哪个通道读出来」，不承诺该通道一定存在（读不到就走下一个）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SourceKind {
+    /// Windows：`%APPDATA%\Microsoft\Windows\Themes\TranscodedWallpaper`（系统转码后的当前壁纸）。
+    WindowsTranscoded,
+    /// Windows：`HKCU\Software\Microsoft\Windows\CurrentVersion\Themes` 的 `CurrentTheme`
+    /// 指向的 `.theme`（Win10+ 落在 `%LOCALAPPDATA%\Microsoft\Windows\Themes\Custom.theme`）。
+    ///
+    /// 这是**当前生效**的那份主题，比 `%APPDATA%` 下的主题包可靠得多。
+    WindowsCurrentTheme,
+    /// Windows：`%APPDATA%\Microsoft\Windows\Themes\*.theme` 里的 `Wallpaper=` 行。
+    ///
+    /// 用户另存的主题包（不一定被启用），只作最后一档兜底。
+    WindowsThemeFile,
+    /// Windows：注册表 `HKCU\Control Panel\Desktop` 的 `WallPaper` 值（`reg.exe` 子进程）。
+    WindowsRegistry,
+    /// Linux · GNOME：`gsettings get org.gnome.desktop.background picture-uri`(`-dark`)。
+    Gnome,
+    /// Linux · KDE Plasma：`plasma-org.kde.plasma.desktop-appletsrc` 的 `Image=` 行。
+    Kde,
+    /// Linux · swaybg / hyprpaper 配置里的 wallpaper 行。
+    WlrootsCompositor,
+    /// Linux · XFCE：`xfce4-desktop.xml` 的 `last-image` / `image-path` 属性。
+    Xfce,
+    /// macOS：`com.apple.wallpaper/Store/Index.plist` 里的 file URL / 绝对路径串。
+    MacOsStore,
+    /// macOS：`defaults read com.apple.desktop Background`（老式每屏壁纸设置）。
+    MacOsDesktopDefaults,
+}
+
+impl SourceKind {
+    /// 稳定标识（日志 / 设置页提示用）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::WindowsTranscoded => "windows-transcoded",
+            Self::WindowsCurrentTheme => "windows-current-theme",
+            Self::WindowsThemeFile => "windows-theme-file",
+            Self::WindowsRegistry => "windows-registry",
+            Self::Gnome => "linux-gnome",
+            Self::Kde => "linux-kde",
+            Self::WlrootsCompositor => "linux-wlroots",
+            Self::Xfce => "linux-xfce",
+            Self::MacOsStore => "macos-store",
+            Self::MacOsDesktopDefaults => "macos-desktop-defaults",
+        }
+    }
+
+    /// 这条通道属于哪个平台族。
+    #[must_use]
+    pub const fn platform(self) -> Platform {
+        match self {
+            Self::WindowsTranscoded
+            | Self::WindowsCurrentTheme
+            | Self::WindowsThemeFile
+            | Self::WindowsRegistry => Platform::Windows,
+            Self::MacOsStore | Self::MacOsDesktopDefaults => Platform::MacOs,
+            Self::Gnome | Self::Kde | Self::WlrootsCompositor | Self::Xfce => Platform::Linux,
+        }
+    }
+}
+
+/// 一个候选壁纸来源。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct WallpaperSource {
+    /// 通道标识（平台 + 桌面环境）。
+    pub kind: SourceKind,
+    /// 归一化后的绝对路径。
+    pub path: PathBuf,
+    /// 原始证据：配置文件 / 注册表键 / 命令行，用于日志与设置页的「从哪读到的」。
+    pub evidence: String,
+}
+
+/// 探测结果：有序候选列表 + 各步失败原因。
+///
+/// 列表**不是** `Result`：找不到壁纸不是错误，见模块文档的边界一节。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct WallpaperProbe {
+    sources: Vec<WallpaperSource>,
+    notes: Vec<String>,
+}
+
+impl WallpaperProbe {
+    /// 候选列表，按可信度从高到低（第一个就是首选）。
+    #[must_use]
+    pub fn sources(&self) -> &[WallpaperSource] {
+        &self.sources
+    }
+
+    /// 首选候选（等价于 `sources().first()`）。
+    #[must_use]
+    pub fn best(&self) -> Option<&WallpaperSource> {
+        self.sources.first()
+    }
+
+    /// 候选迭代器（按可信度顺序）。
+    pub fn iter(&self) -> impl Iterator<Item = &WallpaperSource> {
+        self.sources.iter()
+    }
+
+    /// 候选个数。
+    #[must_use]
+    pub fn len(&self) -> usize {
+        self.sources.len()
+    }
+
+    /// 一个候选都没有（调用方应落到 D38 的第③级色卡）。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.sources.is_empty()
+    }
+
+    /// 各步的失败原因（`通道: 原因`），可直接展示在设置页的提示里。
+    #[must_use]
+    pub fn notes(&self) -> &[String] {
+        &self.notes
+    }
+
+    /// 取走候选列表。
+    #[must_use]
+    pub fn into_sources(self) -> Vec<WallpaperSource> {
+        self.sources
+    }
+}
+
+/// 真实探测宿主平台（[`HostIo`] + 进程环境 + 编译目标平台）。
+#[must_use]
+pub fn detect() -> WallpaperProbe {
+    detect_with(&HostIo, &ProcessEnv, Platform::current())
+}
+
+/// 注入式探测：IO、环境变量表、平台族全部由调用方给。
+///
+/// 三平台采集逻辑都不带 `cfg`，所以任意宿主都能用固定夹具跑某一平台的用例。
+#[must_use]
+pub fn detect_with(io: &dyn ProbeIo, env: &dyn EnvSource, platform: Platform) -> WallpaperProbe {
+    let Some(roots) = HostRoots::from_env(env) else {
+        return WallpaperProbe {
+            sources: Vec::new(),
+            notes: vec!["host: HOME / USERPROFILE 都读不到，无法定位用户目录".to_owned()],
+        };
+    };
+    let mut collect = Collect::new(io, roots, platform);
+    match platform {
+        Platform::Windows => windows::collect(&mut collect),
+        Platform::MacOs => macos::collect(&mut collect),
+        // 其它 Unix 按 Linux 的桌面习惯兜底（与 `paths` 模块的处理一致）。
+        Platform::Linux | Platform::Other => linux::collect(&mut collect),
+    }
+    collect.finish()
+}
+
+/// 采集过程的累加器：负责归一化、去重、图片校验与失败原因记录。
+pub(crate) struct Collect<'io> {
+    io: &'io dyn ProbeIo,
+    roots: HostRoots,
+    platform: Platform,
+    sources: Vec<WallpaperSource>,
+    notes: Vec<String>,
+    seen: Vec<String>,
+}
+
+impl<'io> Collect<'io> {
+    /// 构造空累加器。
+    pub(crate) fn new(io: &'io dyn ProbeIo, roots: HostRoots, platform: Platform) -> Self {
+        Self {
+            io,
+            roots,
+            platform,
+            sources: Vec::new(),
+            notes: Vec::new(),
+            seen: Vec::new(),
+        }
+    }
+
+    /// 注入的 IO（文件 / 目录 / 子进程）。
+    pub(crate) fn io(&self) -> &'io dyn ProbeIo {
+        self.io
+    }
+
+    /// 宿主根目录（由环境变量表推出）。
+    pub(crate) fn roots(&self) -> &HostRoots {
+        &self.roots
+    }
+
+    /// 记一条失败原因，探测继续往下走。
+    pub(crate) fn note(&mut self, step: &str, detail: impl std::fmt::Display) {
+        self.notes.push(format!("{step}: {detail}"));
+    }
+
+    /// 收一个候选：归一化 → 去重 → 图片校验，任何一步不过都只记原因、不中断。
+    ///
+    /// 返回是否真的收下（调用方据此决定要不要继续试别名）。
+    pub(crate) fn add(&mut self, kind: SourceKind, evidence: &str, raw: &str) -> bool {
+        match normalize_path(raw, &self.roots) {
+            Some(path) => self.add_path(kind, evidence, path),
+            None => {
+                self.note(evidence, format!("不是可用的绝对路径（{raw}）"));
+                false
+            }
+        }
+    }
+
+    /// 收一个已经算好的路径（调用方自己拼的，不再归一化）。
+    pub(crate) fn add_path(&mut self, kind: SourceKind, evidence: &str, path: PathBuf) -> bool {
+        let key = dedupe_key(self.platform, &path);
+        if self.seen.contains(&key) {
+            return false;
+        }
+        let head = self.io.read_head(&path, IMAGE_HEAD_LEN);
+        if !head.as_deref().is_some_and(looks_like_image) {
+            self.note(
+                evidence,
+                format!("读不到或认不出图片格式（{}）", path.display()),
+            );
+            return false;
+        }
+        self.seen.push(key);
+        self.sources.push(WallpaperSource {
+            kind,
+            path,
+            evidence: evidence.to_owned(),
+        });
+        true
+    }
+
+    /// 收尾。
+    pub(crate) fn finish(self) -> WallpaperProbe {
+        WallpaperProbe {
+            sources: self.sources,
+            notes: self.notes,
+        }
+    }
+}
+
+/// 去重键：Windows 路径大小写不敏感（同一文件可能被写出两种大小写），其它平台按原样。
+fn dedupe_key(platform: Platform, path: &std::path::Path) -> String {
+    let text = path.to_string_lossy().into_owned();
+    if platform == Platform::Windows {
+        text.to_ascii_lowercase()
+    } else {
+        text
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::io::{HostIo, HostRoots};
+    use super::*;
+    use crate::platform::paths::MapEnv;
+
+    #[test]
+    fn empty_probe_is_empty_not_error() {
+        let probe = WallpaperProbe::default();
+        assert!(probe.is_empty());
+        assert_eq!(probe.len(), 0);
+        assert!(probe.best().is_none());
+        assert_eq!(probe.iter().count(), 0);
+        assert!(probe.notes().is_empty());
+        assert!(probe.into_sources().is_empty());
+    }
+
+    #[test]
+    fn missing_home_yields_note_and_no_candidates() {
+        let env = MapEnv::new();
+        for platform in [Platform::Windows, Platform::MacOs, Platform::Linux] {
+            let probe = detect_with(&HostIo, &env, platform);
+            assert!(probe.is_empty(), "{platform:?} 没有 HOME 时不该有候选");
+            assert_eq!(probe.notes().len(), 1);
+            assert!(probe.notes()[0].contains("HOME"));
+        }
+    }
+
+    #[test]
+    fn source_kind_exposes_platform_and_stable_name() {
+        assert_eq!(SourceKind::Gnome.platform(), Platform::Linux);
+        assert_eq!(SourceKind::WindowsRegistry.platform(), Platform::Windows);
+        assert_eq!(SourceKind::MacOsStore.platform(), Platform::MacOs);
+        assert_eq!(SourceKind::WindowsTranscoded.as_str(), "windows-transcoded");
+        assert!(SourceKind::Kde.as_str().starts_with("linux-"));
+    }
+
+    #[test]
+    fn collect_dedupes_and_keeps_priority_order() {
+        let env = MapEnv::new().with("HOME", "/home/u");
+        let roots = HostRoots::from_env(&env).expect("HOME 已给");
+        let io = io::fake::FakeIo::new()
+            .with_image("/home/u/a.png")
+            .with_image("/home/u/b.jpg");
+        let mut collect = Collect::new(&io, roots, Platform::Linux);
+        collect.add(SourceKind::Gnome, "gsettings", "/home/u/a.png");
+        collect.add(SourceKind::Kde, "kde", "file:///home/u/b.jpg");
+        // 同一条路径再来一次（换了个通道）不该重复计入。
+        collect.add(SourceKind::Xfce, "xfce", "/home/u/a.png");
+        collect.add(SourceKind::Xfce, "xfce", "/home/u/missing.png");
+        let probe = collect.finish();
+        assert_eq!(probe.len(), 2);
+        assert_eq!(probe.best().expect("有候选").kind, SourceKind::Gnome);
+        assert_eq!(probe.sources()[1].path, PathBuf::from("/home/u/b.jpg"));
+        assert!(
+            probe
+                .notes()
+                .iter()
+                .any(|note| note.contains("missing.png")),
+            "落选的候选要留原因：{:?}",
+            probe.notes()
+        );
+    }
+}
diff --git a/crates/core/src/platform/wallpaper/io.rs b/crates/core/src/platform/wallpaper/io.rs
new file mode 100644
index 0000000..3655957
--- /dev/null
+++ b/crates/core/src/platform/wallpaper/io.rs
@@ -0,0 +1,297 @@
+//! 壁纸探测要用的外部 IO：文件读取、文件头、目录列表、子进程，以及宿主根目录。
+//!
+//! 生产实现是 [`HostIo`]，测试实现是 `fake::FakeIo`（固定夹具，不碰真机壁纸）。
+//! 这一层的存在只为把「外部世界」变成注入参数，不含任何平台判断。
+
+use std::path::{Path, PathBuf};
+
+use crate::platform::paths::EnvSource;
+
+/// 探测需要的外部世界：四个方法覆盖三平台的全部读法。
+pub trait ProbeIo {
+    /// 读整个文件并按 UTF-8 lossy 转文本。
+    ///
+    /// 二进制 plist 也走这里：路径串本身是可读 ASCII，坏字节会被替换成 U+FFFD 而不影响
+    /// 路径串的完整性（macOS 的 `Index.plist` 就是 bplist00）。
+    fn read_text(&self, path: &Path) -> Option<String>;
+
+    /// 读文件头最多 `limit` 字节（图片魔数嗅探用；不存在或读不了返回 `None`）。
+    fn read_head(&self, path: &Path, limit: usize) -> Option<Vec<u8>>;
+
+    /// 列出目录里的**文件**（非递归、不排序；目录不存在返回空列表）。排序由调用方做。
+    fn list_dir(&self, dir: &Path) -> Vec<PathBuf>;
+
+    /// 跑一个外部命令取 stdout（命令缺失 / 非零退出 / 空输出都返回 `None`）。
+    fn run(&self, program: &str, args: &[&str]) -> Option<String>;
+}
+
+/// 真实宿主 IO。
+#[derive(Debug, Clone, Copy, Default)]
+pub struct HostIo;
+
+impl ProbeIo for HostIo {
+    fn read_text(&self, path: &Path) -> Option<String> {
+        let bytes = std::fs::read(path).ok()?;
+        Some(String::from_utf8_lossy(&bytes).into_owned())
+    }
+
+    fn read_head(&self, path: &Path, limit: usize) -> Option<Vec<u8>> {
+        use std::io::Read;
+        let file = std::fs::File::open(path).ok()?;
+        let mut buffer = vec![0_u8; limit];
+        let mut handle = file.take(limit as u64);
+        let read = handle.read(&mut buffer).ok()?;
+        buffer.truncate(read);
+        Some(buffer)
+    }
+
+    fn list_dir(&self, dir: &Path) -> Vec<PathBuf> {
+        let Ok(entries) = std::fs::read_dir(dir) else {
+            return Vec::new();
+        };
+        entries
+            .filter_map(Result::ok)
+            .filter(|entry| {
+                entry
+                    .file_type()
+                    .map(|kind| kind.is_file())
+                    .unwrap_or(false)
+            })
+            .map(|entry| entry.path())
+            .collect()
+    }
+
+    fn run(&self, program: &str, args: &[&str]) -> Option<String> {
+        let output = std::process::Command::new(program)
+            .args(args)
+            .output()
+            .ok()?;
+        // `Command::output` 对非零退出同样返回 `Ok`，所以退出码要单独判：三条命令
+        // （`reg.exe` / `gsettings` / `defaults`）出错时都走 stderr，只看 stdout 会把
+        // 「查不到」和「命令失败」混成一种，调用方的原因文案就名不副实了。
+        if !output.status.success() || output.stdout.is_empty() {
+            return None;
+        }
+        Some(String::from_utf8_lossy(&output.stdout).into_owned())
+    }
+}
+
+/// 探测要用的宿主根目录（全部由环境变量表推出，因此测试可以整体替换）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct HostRoots {
+    /// 用户主目录（`HOME`，退 `USERPROFILE`）。
+    pub home: PathBuf,
+    /// Windows `%APPDATA%`（退 `~/AppData/Roaming`）；其它平台用不到，但仍填上以免分支取空。
+    pub app_data: PathBuf,
+    /// Windows `%LOCALAPPDATA%`（退 `~/AppData/Local`）：Win10+ 的「当前主题」
+    /// `Custom.theme` 落在这一侧。
+    pub local_app_data: PathBuf,
+    /// `$XDG_CONFIG_HOME`（仅接受绝对路径），退 `~/.config`。
+    pub config_home: PathBuf,
+    /// Windows `%SystemRoot%`（`.theme` 里 `Wallpaper=%SystemRoot%\...` 展开用），无则不展开。
+    pub system_root: Option<PathBuf>,
+}
+
+impl HostRoots {
+    /// 从环境变量表推出根目录；连主目录都没有时返回 `None`（调用方记一条原因）。
+    ///
+    /// 顺序固定（`HOME` 优先于 `USERPROFILE`），**不按编译目标分支**：否则在 Windows 上
+    /// 跑 Linux 夹具时会被 `USERPROFILE` 抢走主目录，夹具就不再确定。
+    #[must_use]
+    pub fn from_env(env: &dyn EnvSource) -> Option<Self> {
+        let home = env
+            .var("HOME")
+            .or_else(|| env.var("USERPROFILE"))
+            .map(PathBuf::from)?;
+        let app_data = env
+            .var("APPDATA")
+            .map(PathBuf::from)
+            .unwrap_or_else(|| home.join("AppData/Roaming"));
+        let local_app_data = env
+            .var("LOCALAPPDATA")
+            .map(PathBuf::from)
+            .unwrap_or_else(|| home.join("AppData/Local"));
+        let config_home = env
+            .var("XDG_CONFIG_HOME")
+            .map(PathBuf::from)
+            .filter(|dir| dir.is_absolute())
+            .unwrap_or_else(|| home.join(".config"));
+        let system_root = env
+            .var("SYSTEMROOT")
+            .or_else(|| env.var("WINDIR"))
+            .map(PathBuf::from);
+        Some(Self {
+            home,
+            app_data,
+            local_app_data,
+            config_home,
+            system_root,
+        })
+    }
+}
+
+#[cfg(test)]
+pub(crate) mod fake {
+    use std::collections::BTreeMap;
+    use std::path::{Path, PathBuf};
+
+    use super::ProbeIo;
+
+    /// PNG 魔数（夹具用它冒充「像图片」的文件）。
+    pub(crate) const PNG_HEAD: &[u8] = b"\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR";
+
+    /// 固定夹具 IO：文件内容、图片、目录列表、命令输出全部预先给定。
+    ///
+    /// 未登记的路径一律「不存在 / 读不出 / 目录为空」，命令也未登记则报失败。
+    #[derive(Debug, Default, Clone)]
+    pub struct FakeIo {
+        texts: BTreeMap<PathBuf, String>,
+        images: Vec<PathBuf>,
+        dirs: BTreeMap<PathBuf, Vec<PathBuf>>,
+        commands: BTreeMap<String, String>,
+    }
+
+    impl FakeIo {
+        /// 空世界（一切探测都会失败）。
+        pub(crate) fn new() -> Self {
+            Self::default()
+        }
+
+        /// 登记一个文本文件（配置文件、`.theme`、plist、xml……）。
+        pub(crate) fn with_file(mut self, path: impl AsRef<Path>, text: &str) -> Self {
+            self.texts
+                .insert(path.as_ref().to_path_buf(), text.to_owned());
+            self
+        }
+
+        /// 登记一个「图片」文件（`read_head` 返回 PNG 魔数）。
+        pub(crate) fn with_image(mut self, path: impl AsRef<Path>) -> Self {
+            self.images.push(path.as_ref().to_path_buf());
+            self
+        }
+
+        /// 登记目录内容（按文件名给，路径拼在 `dir` 上）。
+        pub(crate) fn with_dir(mut self, dir: impl AsRef<Path>, names: &[&str]) -> Self {
+            let dir = dir.as_ref();
+            let entries = names.iter().map(|name| dir.join(name)).collect();
+            self.dirs.insert(dir.to_path_buf(), entries);
+            self
+        }
+
+        /// 登记一条命令的 stdout；`key` 是「程序名 + 空格分隔的参数」整串。
+        pub(crate) fn with_command(mut self, key: &str, stdout: &str) -> Self {
+            self.commands.insert(key.to_owned(), stdout.to_owned());
+            self
+        }
+    }
+
+    fn command_key(program: &str, args: &[&str]) -> String {
+        let mut key = program.to_owned();
+        for arg in args {
+            key.push(' ');
+            key.push_str(arg);
+        }
+        key
+    }
+
+    impl ProbeIo for FakeIo {
+        fn read_text(&self, path: &Path) -> Option<String> {
+            self.texts.get(path).cloned()
+        }
+
+        fn read_head(&self, path: &Path, limit: usize) -> Option<Vec<u8>> {
+            if self.images.iter().any(|image| image.as_path() == path) {
+                return Some(PNG_HEAD[..limit.min(PNG_HEAD.len())].to_vec());
+            }
+            let text = self.texts.get(path)?;
+            let bytes = text.as_bytes();
+            Some(bytes[..limit.min(bytes.len())].to_vec())
+        }
+
+        fn list_dir(&self, dir: &Path) -> Vec<PathBuf> {
+            self.dirs.get(dir).cloned().unwrap_or_default()
+        }
+
+        fn run(&self, program: &str, args: &[&str]) -> Option<String> {
+            let key = command_key(program, args);
+            let stdout = self.commands.get(&key)?;
+            if stdout.is_empty() {
+                return None;
+            }
+            Some(stdout.clone())
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::platform::paths::MapEnv;
+
+    #[test]
+    fn roots_come_from_env_in_fixed_order() {
+        let env = MapEnv::new()
+            .with("HOME", "/home/u")
+            .with("USERPROFILE", "C:/Users/ignored")
+            .with("SYSTEMROOT", "C:/Windows");
+        let roots = HostRoots::from_env(&env).expect("HOME 已给");
+        assert_eq!(roots.home, PathBuf::from("/home/u"));
+        assert_eq!(roots.app_data, PathBuf::from("/home/u/AppData/Roaming"));
+        assert_eq!(roots.local_app_data, PathBuf::from("/home/u/AppData/Local"));
+        assert_eq!(roots.config_home, PathBuf::from("/home/u/.config"));
+        assert_eq!(roots.system_root, Some(PathBuf::from("C:/Windows")));
+    }
+
+    #[test]
+    fn roots_prefer_explicit_appdata_and_absolute_xdg() {
+        let env = MapEnv::new()
+            .with("HOME", "/home/u")
+            .with("APPDATA", "C:/Users/u/AppData/Roaming")
+            .with("LOCALAPPDATA", "C:/Users/u/AppData/Local")
+            // 相对路径按 XDG 规范忽略。
+            .with("XDG_CONFIG_HOME", "relative/dir");
+        let roots = HostRoots::from_env(&env).expect("HOME 已给");
+        assert_eq!(roots.app_data, PathBuf::from("C:/Users/u/AppData/Roaming"));
+        assert_eq!(
+            roots.local_app_data,
+            PathBuf::from("C:/Users/u/AppData/Local")
+        );
+        assert_eq!(roots.config_home, PathBuf::from("/home/u/.config"));
+        assert_eq!(roots.system_root, None);
+    }
+
+    #[test]
+    fn host_io_treats_non_zero_exit_as_failure() {
+        // 有 stdout 但退出码非零：只看 stdout 的旧实现会把这种输出当成功。
+        #[cfg(windows)]
+        let (program, args) = ("cmd", ["/c", "echo hi & exit 3"]);
+        #[cfg(not(windows))]
+        let (program, args) = ("sh", ["-c", "echo hi; exit 3"]);
+        assert!(HostIo.run(program, &args).is_none());
+    }
+
+    #[test]
+    fn fake_io_serves_only_registered_world() {
+        let io = fake::FakeIo::new()
+            .with_file("/home/u/note.txt", "hello")
+            .with_image("/home/u/a.png")
+            .with_dir("/home/u/dir", &["a.png", "b.theme"])
+            .with_command("gsettings get x y", "'file:///home/u/a.png'");
+        assert_eq!(
+            io.read_text(Path::new("/home/u/note.txt")).as_deref(),
+            Some("hello")
+        );
+        assert_eq!(
+            io.read_head(Path::new("/home/u/note.txt"), 4).as_deref(),
+            Some(&b"hell"[..])
+        );
+        assert_eq!(
+            io.read_head(Path::new("/home/u/a.png"), 8).as_deref(),
+            Some(&fake::PNG_HEAD[..8])
+        );
+        assert_eq!(io.list_dir(Path::new("/home/u/dir")).len(), 2);
+        assert!(io.run("gsettings", &["get", "x", "y"]).is_some());
+        assert!(io.run("reg.exe", &["query"]).is_none());
+        assert!(io.read_text(Path::new("/nope")).is_none());
+    }
+}
diff --git a/crates/core/src/platform/wallpaper/linux.rs b/crates/core/src/platform/wallpaper/linux.rs
new file mode 100644
index 0000000..e2f7219
--- /dev/null
+++ b/crates/core/src/platform/wallpaper/linux.rs
@@ -0,0 +1,396 @@
+//! Linux 壁纸路径探测：GNOME → KDE Plasma → swaybg / hyprpaper → XFCE。
+//!
+//! 四步互相独立：`gsettings` 缺失、配置文件不存在、解析不到值都只记一条原因，探测继续往下
+//! 走（Wayland 上一条配置都读不到是常态，此时应直接落到 D38 的第③级色卡）。
+//!
+//! 探测路径全部来自「桌面环境自己记在磁盘上的东西」，不需要 D-Bus 与 xdg-desktop-portal：
+//!
+//! 1. GNOME / Ubuntu 系：`gsettings get org.gnome.desktop.background picture-uri`，再看
+//!    `picture-uri-dark`（深色壁纸是独立键）；
+//! 2. KDE Plasma：`~/.config/plasma-org.kde.plasma.desktop-appletsrc` 的 `Image=` 行；
+//! 3. swaybg / hyprpaper：`~/.config/hypr/hyprpaper.conf`（`wallpaper =` / `preload =`）与
+//!    `~/.config/sway/config`（`output <name> bg <path>`）；
+//! 4. XFCE：`~/.config/xfce4/xfconf/xfce-perchannel-xml/xfce4-desktop.xml` 的
+//!    `last-image` / `image-path` 属性。
+//!
+//! 本文件不带 `cfg`：平台分流只在 [`super::detect_with`] 一处，任何宿主都能跑夹具用例。
+
+use super::{Collect, SourceKind};
+
+/// GNOME 壁纸 schema。
+pub(super) const GNOME_SCHEMA: &str = "org.gnome.desktop.background";
+
+/// 探测的键，顺序即优先级（浅色在前，深色壁纸在后）。
+pub(super) const GNOME_KEYS: &[&str] = &["picture-uri", "picture-uri-dark"];
+
+const KDE_CONFIG: &str = "plasma-org.kde.plasma.desktop-appletsrc";
+const HYPRPAPER_CONFIG: &str = "hypr/hyprpaper.conf";
+const SWAY_CONFIG: &str = "sway/config";
+const XFCE_DESKTOP_XML: &str = "xfce4/xfconf/xfce-perchannel-xml/xfce4-desktop.xml";
+
+/// 四步依次探测。
+pub(super) fn collect(collect: &mut Collect<'_>) {
+    gnome(collect);
+    kde(collect);
+    compositors(collect);
+    xfce(collect);
+}
+
+/// 第一步：GNOME 的 `picture-uri` / `picture-uri-dark`。
+fn gnome(collect: &mut Collect<'_>) {
+    for key in GNOME_KEYS {
+        let evidence = format!("gsettings get {GNOME_SCHEMA} {key}");
+        match collect.io().run("gsettings", &["get", GNOME_SCHEMA, key]) {
+            Some(text) => match parse_gsettings_value(&text) {
+                Some(value) => {
+                    collect.add(SourceKind::Gnome, &evidence, &value);
+                }
+                None => collect.note(
+                    SourceKind::Gnome.as_str(),
+                    format!("{evidence} = {}（没有设壁纸）", text.trim()),
+                ),
+            },
+            None => collect.note(
+                SourceKind::Gnome.as_str(),
+                format!("{evidence} 失败（命令缺失 / 非零退出 / 空输出）"),
+            ),
+        }
+    }
+}
+
+/// 第二步：KDE Plasma 的壁纸插件配置。
+fn kde(collect: &mut Collect<'_>) {
+    let Some(text) = read_config(collect, SourceKind::Kde, KDE_CONFIG) else {
+        return;
+    };
+    let values = parse_kde_images(&text);
+    if values.is_empty() {
+        collect.note(
+            SourceKind::Kde.as_str(),
+            format!("{KDE_CONFIG} 里没有 Image= 行"),
+        );
+    }
+    let evidence = format!("{KDE_CONFIG} 的 Image=");
+    for value in values {
+        collect.add(SourceKind::Kde, &evidence, &value);
+    }
+}
+
+/// 第三步：swaybg（sway 配置）/ hyprpaper。
+fn compositors(collect: &mut Collect<'_>) {
+    for (relative, what) in [
+        (HYPRPAPER_CONFIG, "wallpaper/preload 行"),
+        (SWAY_CONFIG, "output ... bg 行"),
+    ] {
+        let Some(text) = read_config(collect, SourceKind::WlrootsCompositor, relative) else {
+            continue;
+        };
+        let values = match relative {
+            HYPRPAPER_CONFIG => parse_hyprpaper_wallpapers(&text),
+            _ => parse_sway_backgrounds(&text),
+        };
+        if values.is_empty() {
+            collect.note(
+                SourceKind::WlrootsCompositor.as_str(),
+                format!("{relative} 里没有 {what}"),
+            );
+        }
+        let evidence = format!("{relative} 的 {what}");
+        for value in values {
+            collect.add(SourceKind::WlrootsCompositor, &evidence, &value);
+        }
+    }
+}
+
+/// 第四步：XFCE 的 xfconf XML。
+fn xfce(collect: &mut Collect<'_>) {
+    let Some(text) = read_config(collect, SourceKind::Xfce, XFCE_DESKTOP_XML) else {
+        return;
+    };
+    let values = parse_xfce_last_image(&text);
+    if values.is_empty() {
+        collect.note(
+            SourceKind::Xfce.as_str(),
+            format!("{XFCE_DESKTOP_XML} 里没有 last-image/image-path 属性"),
+        );
+    }
+    let evidence = format!("{XFCE_DESKTOP_XML} 的 last-image/image-path");
+    for value in values {
+        collect.add(SourceKind::Xfce, &evidence, &value);
+    }
+}
+
+/// 读 `$XDG_CONFIG_HOME` 下的一个配置文件；读不到只记原因并返回 `None`。
+fn read_config(collect: &mut Collect<'_>, kind: SourceKind, relative: &str) -> Option<String> {
+    let path = collect.roots().config_home.join(relative);
+    match collect.io().read_text(&path) {
+        Some(text) => Some(text),
+        None => {
+            collect.note(kind.as_str(), format!("读不到 {}", path.display()));
+            None
+        }
+    }
+}
+
+/// 解析 `gsettings get` 的输出：`'file:///home/u/a.png'`；`'none'` / 空串返回 `None`。
+pub(super) fn parse_gsettings_value(text: &str) -> Option<String> {
+    let trimmed = text.trim();
+    let value = trimmed
+        .strip_prefix('\'')
+        .and_then(|rest| rest.strip_suffix('\''))
+        .unwrap_or(trimmed)
+        .trim();
+    if value.is_empty() || value.eq_ignore_ascii_case("none") {
+        return None;
+    }
+    Some(value.to_owned())
+}
+
+/// 取 Plasma 配置里的 `Image=` 值（壁纸插件是 `[org.kde.image][General]` 段）。
+///
+/// 只收绝对路径与 `file://` URI：Plasma 的其它插件也有 `Image=` 键，相对值当成非壁纸。
+pub(super) fn parse_kde_images(text: &str) -> Vec<String> {
+    text.lines()
+        .filter_map(|line| {
+            let (key, value) = line.trim().split_once('=')?;
+            if !key.trim().eq_ignore_ascii_case("image") {
+                return None;
+            }
+            let value = value.trim();
+            let usable = value.starts_with('/')
+                || value.starts_with("file://")
+                || value
+                    .get(..2)
+                    .is_some_and(|head| head.eq_ignore_ascii_case("~/"));
+            usable.then(|| value.to_owned())
+        })
+        .collect()
+}
+
+/// 取 hyprpaper 的 `wallpaper = <监视器>,<路径>` 与 `preload = <路径>` 行。
+pub(super) fn parse_hyprpaper_wallpapers(text: &str) -> Vec<String> {
+    text.lines()
+        .filter_map(|line| {
+            let line = line.trim();
+            if line.starts_with('#') {
+                return None;
+            }
+            let (key, value) = line.split_once('=')?;
+            let value = value.trim();
+            match key.trim().to_ascii_lowercase().as_str() {
+                "preload" => non_empty(value),
+                // `wallpaper = eDP-1,/path/a.png`（监视器可留空）；没写逗号时整段就是路径。
+                "wallpaper" => match value.split_once(',') {
+                    Some((_, path)) => non_empty(path),
+                    None => non_empty(value),
+                },
+                _ => None,
+            }
+        })
+        .collect()
+}
+
+/// 取 sway 配置里 `output <名字|*> bg <路径> [填充方式]` 的路径。
+///
+/// sway 允许用引号包住含空格的对象名/路径，这里把引号拼回来；解析不出来的行直接跳过。
+pub(super) fn parse_sway_backgrounds(text: &str) -> Vec<String> {
+    text.lines()
+        .filter_map(|line| {
+            let line = line.trim();
+            if line.starts_with('#') {
+                return None;
+            }
+            let tokens: Vec<&str> = line.split_whitespace().collect();
+            if tokens.len() < 4 || tokens[0] != "output" || tokens[2] != "bg" {
+                return None;
+            }
+            let raw = tokens[3];
+            let mut value = raw.trim_start_matches('"').to_owned();
+            if raw.starts_with('"') && !raw.ends_with('"') {
+                for token in &tokens[4..] {
+                    value.push(' ');
+                    match token.strip_suffix('"') {
+                        Some(tail) => {
+                            value.push_str(tail);
+                            break;
+                        }
+                        None => value.push_str(token),
+                    }
+                }
+            }
+            non_empty(value.trim_end_matches('"'))
+        })
+        .collect()
+}
+
+/// 取 XFCE `xfce4-desktop.xml` 里 `last-image` / `image-path` 属性的值。
+pub(super) fn parse_xfce_last_image(text: &str) -> Vec<String> {
+    text.lines()
+        .filter(|line| line.contains("last-image") || line.contains("image-path"))
+        .filter_map(|line| non_empty(&attribute(line, "value")?))
+        .collect()
+}
+
+/// 取 XML 一行里 `name="..."` 属性的值。
+fn attribute(line: &str, name: &str) -> Option<String> {
+    let needle = format!("{name}=\"");
+    let start = line.find(&needle)? + needle.len();
+    let rest = &line[start..];
+    let end = rest.find('"')?;
+    Some(rest[..end].to_owned())
+}
+
+fn non_empty(value: &str) -> Option<String> {
+    let trimmed = value.trim();
+    (!trimmed.is_empty()).then(|| trimmed.to_owned())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::io::fake::FakeIo;
+    use super::super::{detect_with, SourceKind};
+    use super::*;
+    use crate::platform::paths::{MapEnv, Platform};
+
+    const CONFIG: &str = "/home/u/.config";
+
+    fn env() -> MapEnv {
+        MapEnv::new().with("HOME", "/home/u")
+    }
+
+    fn gsettings(key: &str) -> String {
+        format!("gsettings get {GNOME_SCHEMA} {key}")
+    }
+
+    fn config(name: &str) -> String {
+        format!("{CONFIG}/{name}")
+    }
+
+    #[test]
+    fn gnome_picture_uri_hit_decodes_percent_escapes() {
+        let io = FakeIo::new()
+            .with_command(
+                &gsettings("picture-uri"),
+                "'file:///home/u/my%20wall.png'\n",
+            )
+            .with_image("/home/u/my wall.png");
+        let probe = detect_with(&io, &env(), Platform::Linux);
+        assert_eq!(probe.len(), 1, "{:?}", probe.notes());
+        let best = probe.best().expect("有候选");
+        assert_eq!(best.kind, SourceKind::Gnome);
+        assert_eq!(best.path.display().to_string(), "/home/u/my wall.png");
+    }
+
+    #[test]
+    fn four_steps_yield_ordered_candidates() {
+        let io = ["a", "b", "k", "h", "h2", "s", "x"]
+            .into_iter()
+            .map(|name| format!("/home/u/{name}.png"))
+            .fold(
+                FakeIo::new()
+                    .with_command(&gsettings("picture-uri"), "'file:///home/u/a.png'\n")
+                    .with_command(&gsettings("picture-uri-dark"), "'file:///home/u/b.png'\n")
+                    .with_file(config(KDE_CONFIG), "Image=file:///home/u/k.png\n")
+                    .with_file(
+                        config(HYPRPAPER_CONFIG),
+                        "preload = /home/u/h.png\nwallpaper = eDP-1, /home/u/h2.png\n",
+                    )
+                    .with_file(config(SWAY_CONFIG), "output * bg /home/u/s.png fill\n")
+                    .with_file(
+                        config(XFCE_DESKTOP_XML),
+                        "<property name=\"last-image\" value=\"/home/u/x.png\"/>\n",
+                    ),
+                FakeIo::with_image,
+            );
+        let probe = detect_with(&io, &env(), Platform::Linux);
+        let seen: Vec<(SourceKind, String)> = probe
+            .iter()
+            .map(|source| (source.kind, source.path.display().to_string()))
+            .collect();
+        assert_eq!(
+            seen,
+            [
+                (SourceKind::Gnome, "/home/u/a.png"),
+                (SourceKind::Gnome, "/home/u/b.png"),
+                (SourceKind::Kde, "/home/u/k.png"),
+                (SourceKind::WlrootsCompositor, "/home/u/h.png"),
+                (SourceKind::WlrootsCompositor, "/home/u/h2.png"),
+                (SourceKind::WlrootsCompositor, "/home/u/s.png"),
+                (SourceKind::Xfce, "/home/u/x.png"),
+            ]
+            .map(|(kind, path)| (kind, path.to_owned()))
+        );
+    }
+
+    #[test]
+    fn failing_step_does_not_stop_later_steps() {
+        // gsettings 说「没设壁纸」，KDE 指向一个不存在的文件，XFCE 才是真的。
+        let io = FakeIo::new()
+            .with_command(&gsettings("picture-uri"), "'none'\n")
+            .with_file(config(KDE_CONFIG), "Image=file:///home/u/gone.png\n")
+            .with_file(
+                config(XFCE_DESKTOP_XML),
+                "<property name=\"image-path\" value=\"/home/u/x.png\"/>\n",
+            )
+            .with_image("/home/u/x.png");
+        let probe = detect_with(&io, &env(), Platform::Linux);
+        assert_eq!(probe.len(), 1, "{:?}", probe.notes());
+        assert_eq!(probe.best().expect("有候选").kind, SourceKind::Xfce);
+        assert!(
+            probe.notes().iter().any(|note| note.contains("gone.png")),
+            "落选原因要留：{:?}",
+            probe.notes()
+        );
+    }
+
+    #[test]
+    fn everything_missing_returns_empty_with_reasons() {
+        let probe = detect_with(&FakeIo::new(), &env(), Platform::Linux);
+        assert!(probe.is_empty(), "全部失败要返回空列表");
+        let notes = probe.notes().join("\n");
+        assert!(notes.contains("gsettings"), "{notes}");
+        assert!(notes.contains("xfce4-desktop.xml"), "{notes}");
+        assert!(notes.contains("hyprpaper.conf"), "{notes}");
+    }
+
+    #[test]
+    fn gsettings_output_parsing() {
+        assert_eq!(
+            parse_gsettings_value("'file:///home/u/a.png'\n"),
+            Some("file:///home/u/a.png".to_owned())
+        );
+        assert_eq!(parse_gsettings_value("'none'\n"), None);
+        assert_eq!(parse_gsettings_value("''"), None);
+        assert_eq!(parse_gsettings_value(""), None);
+    }
+
+    #[test]
+    fn config_line_parsing() {
+        assert_eq!(
+            parse_kde_images("Image=file:///home/u/a.png\nImage=relative/b.png\n"),
+            vec!["file:///home/u/a.png".to_owned()]
+        );
+        assert_eq!(
+            parse_hyprpaper_wallpapers(
+                "# 注释行\npreload = /home/u/a.png\nwallpaper = eDP-1, /home/u/b.png\nwallpaper = ,/home/u/c.png\nsplash = false\n"
+            ),
+            vec![
+                "/home/u/a.png".to_owned(),
+                "/home/u/b.png".to_owned(),
+                "/home/u/c.png".to_owned(),
+            ]
+        );
+        assert_eq!(
+            parse_sway_backgrounds(
+                "output * bg /home/u/a.png fill\noutput eDP-1 bg \"/home/u/b c.png\" stretch\n"
+            ),
+            vec!["/home/u/a.png".to_owned(), "/home/u/b c.png".to_owned()]
+        );
+        assert_eq!(
+            parse_xfce_last_image(
+                "<property name=\"last-image\" value=\"/home/u/a.png\"/>\n<property name=\"image-style\" value=\"3\"/>\n"
+            ),
+            vec!["/home/u/a.png".to_owned()]
+        );
+    }
+}
diff --git a/crates/core/src/platform/wallpaper/macos.rs b/crates/core/src/platform/wallpaper/macos.rs
new file mode 100644
index 0000000..a3223a3
--- /dev/null
+++ b/crates/core/src/platform/wallpaper/macos.rs
@@ -0,0 +1,304 @@
+//! macOS 壁纸路径探测：`com.apple.wallpaper` 的 `Index.plist` → 老式 `com.apple.desktop` 域。
+//!
+//! 两条通道：
+//!
+//! 1. `~/Library/Application Support/com.apple.wallpaper/Store/Index.plist`——Big Sur 之后
+//!    壁纸设置的真实落点，**二进制 plist（`bplist00`）**，里面记着
+//!    `file:///…/xxx.heic` 与裸绝对路径；
+//! 2. `defaults read com.apple.desktop Background`——Catalina 及更早的每屏壁纸配置
+//!    （`ImageFilePath = "/Library/Desktop Pictures/…"`），新系统上该域通常已不存在。
+//!
+//! # 未在真机验证
+//!
+//! 本机（Windows）与 CI（Linux）都没有 macOS 通道：**下列代码没有在 macOS 真机上跑过**。
+//! 因此这里刻意不引入 plist 解析依赖（`plist` crate 会为「读几个路径串」多背一个依赖），
+//! 改成手写的字符串扫描：plist 里的路径串本身是可读 ASCII，按「可打印 ASCII 连续段」切出来
+//! 再按「行首/分隔符后的 `/`」认路径开头即可，二进制 plist 的二进制部分天然成为分隔符。
+//! 扫出的碎片串由 [`super::Collect`] 的图片头校验兜掉，不会喂给取色器。
+//! 真机行为待后续 mission 在 macOS 上补充验证（`Index.plist` 的真实结构、`.heic` 壁纸路径）。
+
+use super::{Collect, SourceKind};
+
+/// Big Sur 之后的壁纸设置存储（相对用户主目录）。
+pub(super) const STORE_INDEX: &str =
+    "Library/Application Support/com.apple.wallpaper/Store/Index.plist";
+
+/// 老式壁纸配置域。
+pub(super) const DESKTOP_DOMAIN: &str = "com.apple.desktop";
+
+/// 一次扫描最多收多少个候选串（防止异常文件把内存打满；正常情况下只有个位数）。
+const MAX_SCANNED: usize = 64;
+
+/// 两步依次探测。
+pub(super) fn collect(collect: &mut Collect<'_>) {
+    store_index(collect);
+    desktop_defaults(collect);
+}
+
+/// 第一步：壁纸 Store 的 `Index.plist`。
+fn store_index(collect: &mut Collect<'_>) {
+    let path = collect.roots().home.join(STORE_INDEX);
+    let Some(text) = collect.io().read_text(&path) else {
+        collect.note(
+            SourceKind::MacOsStore.as_str(),
+            format!("读不到 {}（Catalina 及更早没有这个文件）", path.display()),
+        );
+        return;
+    };
+    let values = scan_string_paths(&text);
+    if values.is_empty() {
+        collect.note(
+            SourceKind::MacOsStore.as_str(),
+            format!("{} 里没有路径串", path.display()),
+        );
+        return;
+    }
+    let evidence = "Library/Application Support/com.apple.wallpaper/Store/Index.plist 的路径串";
+    for value in values {
+        collect.add(SourceKind::MacOsStore, evidence, &value);
+    }
+}
+
+/// 第二步：`defaults read com.apple.desktop Background`（老系统）。
+fn desktop_defaults(collect: &mut Collect<'_>) {
+    let evidence = format!("defaults read {DESKTOP_DOMAIN} Background");
+    match collect
+        .io()
+        .run("defaults", &["read", DESKTOP_DOMAIN, "Background"])
+    {
+        Some(text) => {
+            let values = scan_defaults_background(&text);
+            if values.is_empty() {
+                collect.note(
+                    SourceKind::MacOsDesktopDefaults.as_str(),
+                    format!("{evidence} 里没有 ImageFilePath"),
+                );
+                return;
+            }
+            for value in values {
+                collect.add(SourceKind::MacOsDesktopDefaults, &evidence, &value);
+            }
+        }
+        None => collect.note(
+            SourceKind::MacOsDesktopDefaults.as_str(),
+            format!("{evidence} 失败（命令缺失 / 非零退出 / 该域不存在）"),
+        ),
+    }
+}
+
+/// 从 plist 原文里扫出候选串：`file://` URL 与裸绝对路径。
+///
+/// 输入既可能是 XML plist（`<string>file:///…</string>`）也可能是二进制 plist 的 lossy 文本
+/// （可读 ASCII 串之间夹着不可打印字节）。因此先按「可打印 ASCII 连续段」切，再在每段里认：
+///
+/// - 任意位置的 `file://` 开头；
+/// - 「段首 / 分隔符之后 / `~` 之后」的 `/` 开头（路径中间的 `/` 不算新起点，避免同一路径
+///   被切成好几段）。
+#[must_use]
+pub(super) fn scan_string_paths(text: &str) -> Vec<String> {
+    let mut found = Vec::new();
+    for run in printable_runs(text) {
+        let mut cursor = 0;
+        while let Some(offset) = run[cursor..].find("file://") {
+            let start = cursor + offset;
+            push_candidate(&mut found, &run[start..]);
+            cursor = start + "file://".len();
+        }
+        for (position, _) in run.match_indices('/') {
+            let Some(start) = path_start(run, position) else {
+                continue;
+            };
+            push_candidate(&mut found, &run[start..]);
+        }
+        if found.len() >= MAX_SCANNED {
+            break;
+        }
+    }
+    found.truncate(MAX_SCANNED);
+    found
+}
+
+/// 解析 `defaults read com.apple.desktop Background` 的文本：只认 `ImageFilePath` / `NewPath`。
+#[must_use]
+pub(super) fn scan_defaults_background(text: &str) -> Vec<String> {
+    text.lines()
+        .filter_map(|line| {
+            let (key, value) = line.split_once('=')?;
+            let key = key.trim().trim_matches('"');
+            if !key.eq_ignore_ascii_case("ImageFilePath") && !key.eq_ignore_ascii_case("NewPath") {
+                return None;
+            }
+            let value = value.trim().trim_end_matches(';').trim().trim_matches('"');
+            (!value.is_empty()).then(|| value.to_owned())
+        })
+        .collect()
+}
+
+/// 可打印 ASCII 连续段（二进制 plist 的二进制字节在这里变成分隔符）。
+fn printable_runs(text: &str) -> Vec<&str> {
+    text.split(|ch: char| !(ch.is_ascii_graphic() || ch == ' '))
+        .map(str::trim)
+        .filter(|run| !run.is_empty())
+        .collect()
+}
+
+/// 判断 `run[position]` 的 `/` 是不是一个路径起点；是则返回该路径在 `run` 里的起点。
+fn path_start(run: &str, position: usize) -> Option<usize> {
+    let next = run[position + 1..].chars().next()?;
+    if !(next.is_ascii_alphanumeric() || next == '_') {
+        return None;
+    }
+    match run[..position].chars().next_back() {
+        // 段首：路径直接跟在二进制分隔符后面。
+        None => Some(position),
+        // `~/Library/...`：连 `~` 一起收，交给路径归一化展开。
+        Some('~') => Some(position - 1),
+        // 闭合标签 `</string>` 里的那个斜杠不是路径。
+        Some('<') => None,
+        // 路径中间的 `/`（前面还是路径字符）不当新起点。
+        Some(prev) if is_path_char(prev) => None,
+        Some(_) => Some(position),
+    }
+}
+
+fn is_path_char(ch: char) -> bool {
+    ch.is_ascii_alphanumeric() || matches!(ch, '/' | '.' | '_' | '-' | '%' | '+' | '@' | '~' | ' ')
+}
+
+/// plist/XML 序列化里的终止字符（`<string>` 的尖括号、引号、实体）切掉。
+fn push_candidate(found: &mut Vec<String>, raw: &str) {
+    let end = raw.find(['<', '>', '"', '&', '\'']).unwrap_or(raw.len());
+    let candidate = raw[..end].trim_end();
+    if !candidate.is_empty() && !found.iter().any(|seen| seen.as_str() == candidate) {
+        found.push(candidate.to_owned());
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::io::fake::FakeIo;
+    use super::super::{detect_with, SourceKind};
+    use super::*;
+    use crate::platform::paths::{MapEnv, Platform};
+
+    const STORE_PATH: &str =
+        "/Users/me/Library/Application Support/com.apple.wallpaper/Store/Index.plist";
+    const DEFAULTS_KEY: &str = "defaults read com.apple.desktop Background";
+
+    fn env() -> MapEnv {
+        MapEnv::new().with("HOME", "/Users/me")
+    }
+
+    fn xml_plist(body: &str) -> String {
+        format!("<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<plist version=\"1.0\">\n{body}\n</plist>\n")
+    }
+
+    #[test]
+    fn store_index_hit_decodes_file_url() {
+        let io = FakeIo::new()
+            .with_file(
+                STORE_PATH,
+                &xml_plist("<string>file:///Users/me/Pictures/my%20wall.heic</string>"),
+            )
+            .with_image("/Users/me/Pictures/my wall.heic");
+        let probe = detect_with(&io, &env(), Platform::MacOs);
+        assert_eq!(probe.len(), 1, "{:?}", probe.notes());
+        let best = probe.best().expect("有候选");
+        assert_eq!(best.kind, SourceKind::MacOsStore);
+        assert_eq!(
+            best.path,
+            std::path::PathBuf::from("/Users/me/Pictures/my wall.heic")
+        );
+    }
+
+    #[test]
+    fn multiple_candidates_from_both_channels_keep_order() {
+        let io = FakeIo::new()
+            .with_file(
+                STORE_PATH,
+                &xml_plist(
+                    "<array>\n\
+                     <string>file:///System/Library/Desktop Pictures/a.heic</string>\n\
+                     <string>/Users/me/Library/Application Support/com.apple.wallpaper/Store/b.heic</string>\n\
+                     </array>",
+                ),
+            )
+            .with_image("/System/Library/Desktop Pictures/a.heic")
+            .with_image(
+                "/Users/me/Library/Application Support/com.apple.wallpaper/Store/b.heic",
+            )
+            .with_image("/Library/Desktop Pictures/legacy.jpg")
+            .with_command(
+                DEFAULTS_KEY,
+                "{\n    \"Display Identifier\" = \"Main\";\n    \
+                 ImageFilePath = \"/Library/Desktop Pictures/legacy.jpg\";\n}\n",
+            );
+        let probe = detect_with(&io, &env(), Platform::MacOs);
+        let kinds: Vec<SourceKind> = probe.iter().map(|source| source.kind).collect();
+        assert_eq!(
+            kinds,
+            vec![
+                SourceKind::MacOsStore,
+                SourceKind::MacOsStore,
+                SourceKind::MacOsDesktopDefaults,
+            ]
+        );
+        assert_eq!(
+            probe.best().expect("有候选").path,
+            std::path::PathBuf::from("/System/Library/Desktop Pictures/a.heic")
+        );
+    }
+
+    #[test]
+    fn everything_missing_returns_empty_with_reasons() {
+        let probe = detect_with(&FakeIo::new(), &env(), Platform::MacOs);
+        assert!(probe.is_empty(), "全部失败要返回空列表");
+        let notes = probe.notes().join("\n");
+        assert!(notes.contains("Index.plist"), "{notes}");
+        assert!(notes.contains("defaults"), "{notes}");
+    }
+
+    #[test]
+    fn binary_plist_strings_are_scanned_between_binary_bytes() {
+        // bplist00 的形态：控制字符/长度字节把可读 ASCII 串隔开。
+        let raw = "\u{0}\u{1}\u{2}/Users/me/Pictures/a.heic\u{0}\u{3}file:///Users/me/b.jpg\u{0}";
+        let found = scan_string_paths(raw);
+        assert_eq!(
+            found,
+            vec![
+                "/Users/me/Pictures/a.heic".to_owned(),
+                "file:///Users/me/b.jpg".to_owned(),
+            ]
+        );
+    }
+
+    #[test]
+    fn xml_tags_are_not_part_of_the_candidate() {
+        let found = scan_string_paths(&xml_plist(
+            "<key>Content</key>\n<string>/Users/me/a.png</string>",
+        ));
+        assert_eq!(found, vec!["/Users/me/a.png".to_owned()]);
+    }
+
+    #[test]
+    fn defaults_output_parsing() {
+        assert_eq!(
+            scan_defaults_background(
+                "{\n    \"Display Identifier\" = \"Main\";\n    \
+                 ImageFilePath = \"/Library/Desktop Pictures/a.jpg\";\n    \
+                 NewPath = \"/Users/me/b.png\";\n}\n"
+            ),
+            vec![
+                "/Library/Desktop Pictures/a.jpg".to_owned(),
+                "/Users/me/b.png".to_owned(),
+            ]
+        );
+        assert!(scan_defaults_background("{\n    BackgroundColor = \"0 0 0\";\n}\n").is_empty());
+    }
+
+    #[test]
+    fn tilde_paths_keep_their_prefix() {
+        let found = scan_string_paths("<string>~/Library/Desktop Pictures/a.heic</string>");
+        assert_eq!(found, vec!["~/Library/Desktop Pictures/a.heic".to_owned()]);
+    }
+}
diff --git a/crates/core/src/platform/wallpaper/parse.rs b/crates/core/src/platform/wallpaper/parse.rs
new file mode 100644
index 0000000..41a7ce6
--- /dev/null
+++ b/crates/core/src/platform/wallpaper/parse.rs
@@ -0,0 +1,320 @@
+//! 路径归一化与图片头嗅探：把各平台读出的「原始串」变成可用的绝对路径候选。
+//!
+//! 三平台读出来的东西形状都不一样（gsettings 的 `'file:///x'`、KDE 的 `file:///x`、
+//! Windows `.theme` 的 `%SystemRoot%\x`、plist 里裸的 `/x`），全部在这里收口，
+//! 上层子模块只管「从哪读」。
+
+use std::path::PathBuf;
+
+use super::io::HostRoots;
+
+/// 图片文件头识别（不用解码库，只看魔数与文本 SVG 头）。
+///
+/// 认得的：PNG / JPEG / GIF / BMP / WebP / HEIF-AVIF / TIFF，外加头部出现 `<svg` 的文本。
+/// 认不出的一律不收——壁纸探测宁可少一个候选，也不要把随便一个文件喂给取色器。
+#[must_use]
+pub(super) fn looks_like_image(head: &[u8]) -> bool {
+    const PNG: &[u8] = b"\x89PNG\r\n\x1a\n";
+    if head.starts_with(PNG) {
+        return true;
+    }
+    if head.starts_with(&[0xFF, 0xD8, 0xFF]) {
+        return true; // JPEG
+    }
+    if head.starts_with(b"GIF87a") || head.starts_with(b"GIF89a") {
+        return true;
+    }
+    if head.len() >= 14 && head.starts_with(b"BM") {
+        return true; // BMP
+    }
+    if head.len() >= 12 && &head[0..4] == b"RIFF" && &head[8..12] == b"WEBP" {
+        return true;
+    }
+    if head.len() >= 12 && &head[4..8] == b"ftyp" {
+        // ISO-BMFF 家族：HEIC / HEIF 是 macOS 的默认壁纸容器（`.heic`），AVIF 是新格式。
+        let brand = &head[8..12];
+        return matches!(
+            brand,
+            b"avif" | b"avis" | b"heic" | b"heix" | b"mif1" | b"msf1"
+        );
+    }
+    if head.starts_with(b"II*\0") || head.starts_with(b"MM\0*") {
+        return true; // TIFF
+    }
+    contains_ignore_ascii_case(head, b"<svg")
+}
+
+/// 把一条原始串归一化成绝对路径；不像壁纸路径的返回 `None`（具体原因由调用方记）。
+///
+/// 处理顺序：去引号 → 认 `file://` URI（含百分号解码与 `/C:/` 盘符还原）→ 展开
+/// `%USERPROFILE%` 之类的 Windows 变量 → 展开 `~/` → 要求绝对路径。
+#[must_use]
+pub(super) fn normalize_path(raw: &str, roots: &HostRoots) -> Option<PathBuf> {
+    let unquoted = unquote(raw).trim();
+    if unquoted.is_empty() {
+        return None;
+    }
+    // GNOME 的「无壁纸」与 macOS `defaults` 的「未设置」占位值。
+    if unquoted.eq_ignore_ascii_case("none") || unquoted.eq_ignore_ascii_case("default") {
+        return None;
+    }
+    let text = match strip_prefix_ignore_ascii_case(unquoted, "file://") {
+        Some(rest) => strip_uri_drive_prefix(&percent_decode(rest)),
+        None => expand_vars(unquoted, roots),
+    };
+    let text = text.trim();
+    if let Some(rest) = text.strip_prefix("~/") {
+        return Some(roots.home.join(rest));
+    }
+    if !looks_absolute(text) {
+        return None;
+    }
+    Some(PathBuf::from(text))
+}
+
+/// 去掉成对的单/双引号（`gsettings get` 的输出是 `'file:///x'`）。
+fn unquote(raw: &str) -> &str {
+    let trimmed = raw.trim();
+    let bytes = trimmed.as_bytes();
+    if bytes.len() >= 2 {
+        let first = bytes[0];
+        if (first == b'\'' || first == b'"') && bytes[bytes.len() - 1] == first {
+            return &trimmed[1..trimmed.len() - 1];
+        }
+    }
+    trimmed
+}
+
+fn strip_prefix_ignore_ascii_case<'a>(text: &'a str, prefix: &str) -> Option<&'a str> {
+    let head = text.get(..prefix.len())?;
+    head.eq_ignore_ascii_case(prefix)
+        .then(|| &text[prefix.len()..])
+}
+
+/// `file://` URI 的路径部分：`/C:/Users/me/a.jpg` 在 Windows 上是 `C:/Users/me/a.jpg`。
+///
+/// 非 Windows 上这条分支不会命中（Unix 路径不会以 `/C:` 开头），统一处理不影响正确性。
+fn strip_uri_drive_prefix(text: &str) -> String {
+    let bytes = text.as_bytes();
+    if bytes.len() >= 3 && bytes[0] == b'/' && bytes[1].is_ascii_alphabetic() && bytes[2] == b':' {
+        text[1..].to_owned()
+    } else {
+        text.to_owned()
+    }
+}
+
+/// 百分号解码（GNOME 会把空格编码成 `%20`；非法转义原样保留）。
+fn percent_decode(text: &str) -> String {
+    let bytes = text.as_bytes();
+    let mut out = Vec::with_capacity(bytes.len());
+    let mut index = 0;
+    while index < bytes.len() {
+        if bytes[index] == b'%'
+            && index + 2 < bytes.len()
+            && bytes[index + 1].is_ascii_hexdigit()
+            && bytes[index + 2].is_ascii_hexdigit()
+        {
+            let hex = &text[index + 1..index + 3];
+            if let Ok(byte) = u8::from_str_radix(hex, 16) {
+                out.push(byte);
+                index += 3;
+                continue;
+            }
+        }
+        out.push(bytes[index]);
+        index += 1;
+    }
+    String::from_utf8_lossy(&out).into_owned()
+}
+
+/// 展开 Windows 路径里的 `%VAR%`（`.theme` 的 `Wallpaper=%SystemRoot%\web\...`）。
+///
+/// 认不出的变量原样保留，让后面的图片校验把它判掉——这里不猜路径。
+fn expand_vars(text: &str, roots: &HostRoots) -> String {
+    let mut out = String::with_capacity(text.len());
+    let mut rest = text;
+    while let Some(start) = rest.find('%') {
+        let Some(offset) = rest[start + 1..].find('%') else {
+            break;
+        };
+        let name = &rest[start + 1..start + 1 + offset];
+        let value = match name.to_ascii_lowercase().as_str() {
+            "userprofile" | "home" => Some(roots.home.to_string_lossy()),
+            "appdata" => Some(roots.app_data.to_string_lossy()),
+            // Win10+ 的「当前主题」`Custom.theme` 在 `%LOCALAPPDATA%` 一侧。
+            "localappdata" => Some(roots.local_app_data.to_string_lossy()),
+            "systemroot" | "windir" => roots
+                .system_root
+                .as_deref()
+                .map(std::path::Path::to_string_lossy),
+            _ => None,
+        };
+        match value {
+            Some(value) => {
+                out.push_str(&rest[..start]);
+                out.push_str(&value);
+                rest = &rest[start + offset + 2..];
+            }
+            None => {
+                out.push_str(&rest[..=start]);
+                rest = &rest[start + 1..];
+            }
+        }
+    }
+    out.push_str(rest);
+    out
+}
+
+/// 字符串层面判绝对路径：`/x`、`\\server\share`、`C:/x`、`C:\x`。
+///
+/// 不用 `Path::is_absolute` 是因为它按**编译目标**判，Windows 夹具在 Linux CI 上会被判成
+/// 相对路径，夹具就不跨宿主了。
+fn looks_absolute(text: &str) -> bool {
+    let bytes = text.as_bytes();
+    if text.starts_with('/') || text.starts_with('\\') {
+        return true;
+    }
+    bytes.len() >= 3
+        && bytes[0].is_ascii_alphabetic()
+        && bytes[1] == b':'
+        && matches!(bytes[2], b'/' | b'\\')
+}
+
+fn contains_ignore_ascii_case(haystack: &[u8], needle: &[u8]) -> bool {
+    if needle.is_empty() || haystack.len() < needle.len() {
+        return false;
+    }
+    haystack
+        .windows(needle.len())
+        .any(|window| window.eq_ignore_ascii_case(needle))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::platform::paths::MapEnv;
+
+    fn roots() -> HostRoots {
+        let env = MapEnv::new()
+            .with("HOME", "/home/u")
+            .with("APPDATA", "C:/Users/u/AppData/Roaming")
+            .with("SYSTEMROOT", "C:/Windows");
+        HostRoots::from_env(&env).expect("HOME 已给")
+    }
+
+    #[test]
+    fn image_sniff_accepts_common_wallpaper_containers() {
+        assert!(looks_like_image(b"\x89PNG\r\n\x1a\n\x00\x00"));
+        assert!(looks_like_image(b"\xFF\xD8\xFF\xE0\x00\x10JFIF"));
+        assert!(looks_like_image(b"GIF89a---"));
+        assert!(looks_like_image(
+            b"BM\x36\x00\x00\x00\x00\x00\x00\x00\x36\x00\x00\x00"
+        ));
+        assert!(looks_like_image(b"RIFF\x24\x00\x00\x00WEBPVP8 "));
+        assert!(looks_like_image(
+            b"\x00\x00\x00\x18ftypheic\x00\x00\x00\x00heicmif1"
+        ));
+        assert!(looks_like_image(b"II*\x00\x08\x00\x00\x00"));
+        assert!(looks_like_image(
+            b"<?xml version=\"1.0\"?><svg xmlns=\"...\""
+        ));
+    }
+
+    #[test]
+    fn image_sniff_rejects_non_images_and_short_heads() {
+        assert!(!looks_like_image(b""));
+        assert!(!looks_like_image(b"BM"));
+        assert!(!looks_like_image(
+            b"[Control Panel\\Desktop]\r\nWallpaper=x\r\n"
+        ));
+        assert!(!looks_like_image(b"RIFF\x24\x00\x00\x00AVI LIST"));
+        assert!(!looks_like_image(b"\x00\x00\x00\x18ftypmp42"));
+    }
+
+    #[test]
+    fn normalize_handles_file_uris_quotes_and_percent_encoding() {
+        let roots = roots();
+        assert_eq!(
+            normalize_path("'file:///home/u/Pictures/my%20wall.png'", &roots),
+            Some(PathBuf::from("/home/u/Pictures/my wall.png"))
+        );
+        // Windows 的 URI 会多一个前导斜杠，盘符要还原。
+        assert_eq!(
+            normalize_path("file:///C:/Users/u/a.jpg", &roots),
+            Some(PathBuf::from("C:/Users/u/a.jpg"))
+        );
+        assert_eq!(
+            normalize_path("\"C:\\Users\\u\\a.jpg\"", &roots),
+            Some(PathBuf::from("C:\\Users\\u\\a.jpg"))
+        );
+        // 非法百分号转义原样保留，不 panic（多字节字符也要安全）。
+        assert_eq!(
+            normalize_path("file:///home/u/100%zz%日.png", &roots),
+            Some(PathBuf::from("/home/u/100%zz%日.png"))
+        );
+    }
+
+    #[test]
+    fn normalize_expands_windows_vars_and_home() {
+        let roots = roots();
+        assert_eq!(
+            normalize_path(r"%SystemRoot%\web\wallpaper\a.jpg", &roots),
+            Some(PathBuf::from("C:/Windows\\web\\wallpaper\\a.jpg"))
+        );
+        assert_eq!(
+            normalize_path(
+                "%APPDATA%\\Microsoft\\Windows\\Themes\\TranscodedWallpaper",
+                &roots
+            ),
+            Some(PathBuf::from(
+                "C:/Users/u/AppData/Roaming\\Microsoft\\Windows\\Themes\\TranscodedWallpaper"
+            ))
+        );
+        // Win10+ 的当前主题在 %LOCALAPPDATA%，展开失败就会白丢最可靠的候选。
+        assert_eq!(
+            normalize_path(
+                "%LOCALAPPDATA%\\Microsoft\\Windows\\Themes\\Custom.theme",
+                &roots
+            ),
+            Some(PathBuf::from(
+                "/home/u/AppData/Local\\Microsoft\\Windows\\Themes\\Custom.theme"
+            ))
+        );
+        assert_eq!(
+            normalize_path("~/Library/Desktop Pictures/a.heic", &roots),
+            Some(PathBuf::from("/home/u/Library/Desktop Pictures/a.heic"))
+        );
+        // 认不出的变量不猜：整串保留，随后被「必须绝对路径」这条校验判掉。
+        assert_eq!(normalize_path("%NOPE%\\a.jpg", &roots), None);
+    }
+
+    #[test]
+    fn normalize_rejects_placeholders_relative_and_empty() {
+        let roots = roots();
+        for raw in [
+            "",
+            "   ",
+            "none",
+            "'none'",
+            "default",
+            "relative/a.png",
+            "./a.png",
+        ] {
+            assert_eq!(
+                normalize_path(raw, &roots),
+                None,
+                "{raw:?} 不该被当成壁纸路径"
+            );
+        }
+    }
+
+    #[test]
+    fn absolute_detection_is_host_independent() {
+        assert!(looks_absolute("/home/u/a.png"));
+        assert!(looks_absolute(r"\\server\share\a.png"));
+        assert!(looks_absolute("C:/Users/u/a.png"));
+        assert!(looks_absolute(r"C:\Users\u\a.png"));
+        assert!(!looks_absolute("a.png"));
+        assert!(!looks_absolute("C:"));
+    }
+}
diff --git a/crates/core/src/platform/wallpaper/windows.rs b/crates/core/src/platform/wallpaper/windows.rs
new file mode 100644
index 0000000..f10ad58
--- /dev/null
+++ b/crates/core/src/platform/wallpaper/windows.rs
@@ -0,0 +1,371 @@
+//! Windows 壁纸路径探测：四步，可信度从高到低。
+//!
+//! Win10+ 的真机事实（Windows 11 24H2 实测）：`%APPDATA%\Microsoft\Windows\Themes\` 里
+//! **通常只有** `TranscodedWallpaper`，一个 `.theme` 都没有；当前生效的主题记在
+//! `HKCU\Software\Microsoft\Windows\CurrentVersion\Themes` 的 `CurrentTheme` 值里，指向
+//! `%LOCALAPPDATA%\Microsoft\Windows\Themes\Custom.theme`。所以「扫 `%APPDATA%` 下的
+//! `*.theme`」只能当最后一档兜底：那里的主题包是用户另存的，**可能从未启用**，拿它取色会
+//! 取到与当前桌面无关的图（宁可少给一个候选，也不给错路径）。
+//!
+//! 1. `%APPDATA%\Microsoft\Windows\Themes\TranscodedWallpaper`——系统**当前**壁纸转码后的
+//!    副本，没有扩展名（部分版本还有 `TranscodedWallpaper.jpg` 别名），所以「像不像图片」
+//!    只看文件头魔数，不看后缀；
+//! 2. `CurrentTheme` 指向的 `.theme`——当前生效主题里的 `Wallpaper=` 行（Win10+ 在
+//!    `%LOCALAPPDATA%` 一侧，支持 `%LOCALAPPDATA%` / `%SystemRoot%` 之类变量展开）；
+//! 3. `HKCU\Control Panel\Desktop` 的 `WallPaper` 值——注册表权威来源；
+//! 4. `%APPDATA%\...\Themes\*.theme`——用户另存的主题包，`evidence` 里如实标「可能未启用」。
+//!
+//! 第 2、3 步走 `reg.exe` 子进程，不用 win32 API（core 是 `#![forbid(unsafe_code)]`，
+//! 见 [`super`] 模块文档）；命令缺失 / 非零退出 / 空输出都只记一条原因，探测继续。
+//!
+//! 本文件不带 `cfg`：Linux CI 上同样要能跑夹具用例，平台分流只在
+//! [`super::detect_with`] 一处。
+
+use std::path::{Path, PathBuf};
+
+use self::parse::{parse_reg_sz_value, parse_theme_wallpaper};
+use super::io::HostRoots;
+use super::parse::normalize_path;
+use super::{Collect, SourceKind};
+
+mod parse;
+
+/// `reg query` 用的桌面键（`HKCU\Control Panel\Desktop`，壁纸值名 `WallPaper`）。
+pub(super) const DESKTOP_KEY: &str = r"HKCU\Control Panel\Desktop";
+
+/// `reg query` 用的主题键（Win10+ 当前主题记录在这里）。
+pub(super) const THEMES_KEY: &str = r"HKCU\Software\Microsoft\Windows\CurrentVersion\Themes";
+
+/// 壁纸值名（注册表里是 `WallPaper`，`.theme` 里是 `Wallpaper=`，比对时都忽略大小写）。
+pub(super) const WALLPAPER_VALUE: &str = "WallPaper";
+
+/// 当前主题文件名（值是指向 `.theme` 的绝对路径）。
+pub(super) const CURRENT_THEME_VALUE: &str = "CurrentTheme";
+
+/// `%APPDATA%` 下的主题目录（分段拼，避免 Windows 上出现混用的分隔符）。
+const THEMES_PARTS: &[&str] = &["Microsoft", "Windows", "Themes"];
+
+/// 转码副本的两个已知文件名（无扩展名的是主力）。
+const TRANSCODED_NAMES: &[&str] = &["TranscodedWallpaper", "TranscodedWallpaper.jpg"];
+
+/// 主题文件后缀。
+const THEME_EXTENSION: &str = "theme";
+
+/// 四步依次探测。
+pub(super) fn collect(collect: &mut Collect<'_>) {
+    transcoded(collect);
+    current_theme(collect);
+    registry(collect);
+    saved_theme_packages(collect);
+}
+
+fn themes_dir(roots: &HostRoots) -> PathBuf {
+    let mut dir = roots.app_data.clone();
+    for part in THEMES_PARTS {
+        dir.push(part);
+    }
+    dir
+}
+
+/// 第一步：系统转码后的当前壁纸副本（第一个名字命中后就不再试别名）。
+fn transcoded(collect: &mut Collect<'_>) {
+    let dir = themes_dir(collect.roots());
+    for name in TRANSCODED_NAMES {
+        let path = dir.join(name);
+        let evidence = format!("%APPDATA%\\Microsoft\\Windows\\Themes\\{name}");
+        if collect.add_path(SourceKind::WindowsTranscoded, &evidence, path) {
+            return;
+        }
+    }
+}
+
+/// 第二步：当前生效主题（`CurrentTheme` 指向的 `.theme`）里的 `Wallpaper=`。
+fn current_theme(collect: &mut Collect<'_>) {
+    let Some(raw) = query_reg(
+        collect,
+        SourceKind::WindowsCurrentTheme,
+        THEMES_KEY,
+        CURRENT_THEME_VALUE,
+    ) else {
+        return;
+    };
+    let Some(theme) = normalize_path(&raw, collect.roots()) else {
+        collect.note(
+            SourceKind::WindowsCurrentTheme.as_str(),
+            format!("{CURRENT_THEME_VALUE} 不是可用的绝对路径（{raw}）"),
+        );
+        return;
+    };
+    let label = format!(
+        "reg query {THEMES_KEY} /v {CURRENT_THEME_VALUE} → {}",
+        theme.display()
+    );
+    collect_theme_file(collect, SourceKind::WindowsCurrentTheme, &theme, &label);
+}
+
+/// 第三步：注册表里的权威壁纸值。
+fn registry(collect: &mut Collect<'_>) {
+    let Some(value) = query_reg(
+        collect,
+        SourceKind::WindowsRegistry,
+        DESKTOP_KEY,
+        WALLPAPER_VALUE,
+    ) else {
+        return;
+    };
+    let label = format!("reg query {DESKTOP_KEY} /v {WALLPAPER_VALUE}");
+    collect.add(SourceKind::WindowsRegistry, &label, &value);
+}
+
+/// 第四步（兜底）：`%APPDATA%\...\Themes\*.theme`——用户另存的主题包，**可能未启用**。
+fn saved_theme_packages(collect: &mut Collect<'_>) {
+    let dir = themes_dir(collect.roots());
+    let mut themes: Vec<PathBuf> = collect
+        .io()
+        .list_dir(&dir)
+        .into_iter()
+        .filter(|path| {
+            path.extension()
+                .is_some_and(|ext| ext.eq_ignore_ascii_case(THEME_EXTENSION))
+        })
+        .collect();
+    themes.sort();
+    if themes.is_empty() {
+        collect.note(
+            SourceKind::WindowsThemeFile.as_str(),
+            format!("{} 下没有 .theme 文件", dir.display()),
+        );
+        return;
+    }
+    for theme in themes {
+        let label = format!("{}（用户另存的主题包，可能未启用）", theme.display());
+        collect_theme_file(collect, SourceKind::WindowsThemeFile, &theme, &label);
+    }
+}
+
+/// 读一个 `.theme` 文件，把里面的 `Wallpaper=` 收成候选；读不到 / 没值只记原因。
+fn collect_theme_file(collect: &mut Collect<'_>, kind: SourceKind, file: &Path, label: &str) {
+    let Some(text) = collect.io().read_text(file) else {
+        collect.note(kind.as_str(), format!("读不到 {}", file.display()));
+        return;
+    };
+    let values = parse_theme_wallpaper(&text);
+    if values.is_empty() {
+        collect.note(
+            kind.as_str(),
+            format!("{} 里没有 Wallpaper= 行", file.display()),
+        );
+        return;
+    }
+    let evidence = format!("{label} 的 Wallpaper=");
+    for value in values {
+        collect.add(kind, &evidence, &value);
+    }
+}
+
+/// 跑一次 `reg query <键> /v <值名>` 并取出值；失败或缺值都只记原因、返回 `None`。
+fn query_reg(
+    collect: &mut Collect<'_>,
+    kind: SourceKind,
+    key: &str,
+    value_name: &str,
+) -> Option<String> {
+    let query = format!("reg query {key} /v {value_name}");
+    match collect
+        .io()
+        .run("reg.exe", &["query", key, "/v", value_name])
+    {
+        Some(text) => match parse_reg_sz_value(&text, value_name) {
+            Some(value) => Some(value),
+            None => {
+                collect.note(
+                    kind.as_str(),
+                    format!("{query} 输出里没有 {value_name} 值（可能被策略禁用或壁纸为纯色）"),
+                );
+                None
+            }
+        },
+        None => {
+            collect.note(
+                kind.as_str(),
+                format!("{query} 失败（命令缺失 / 非零退出 / 空输出）"),
+            );
+            None
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::io::fake::FakeIo;
+    use super::super::{detect_with, SourceKind};
+    use super::*;
+    use crate::platform::paths::{MapEnv, Platform};
+
+    const APP_DATA: &str = "C:/Users/u/AppData/Roaming";
+    const LOCAL_APP_DATA: &str = "C:/Users/u/AppData/Local";
+    const DESKTOP_QUERY: &str = "reg.exe query HKCU\\Control Panel\\Desktop /v WallPaper";
+    const THEMES_QUERY: &str =
+        "reg.exe query HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Themes /v CurrentTheme";
+    const CUSTOM_THEME: &str = r"C:\Users\u\AppData\Local\Microsoft\Windows\Themes\Custom.theme";
+
+    fn env() -> MapEnv {
+        MapEnv::new()
+            .with("HOME", "C:/Users/u")
+            .with("APPDATA", APP_DATA)
+            .with("LOCALAPPDATA", LOCAL_APP_DATA)
+            .with("SYSTEMROOT", "C:/Windows")
+    }
+
+    fn roots() -> HostRoots {
+        HostRoots::from_env(&env()).expect("HOME 已给")
+    }
+
+    /// 夹具用**生产代码同一个拼法**造路径，所以 Windows / Linux 宿主上都能对上
+    /// （另有一条字面量断言盯着这个拼法本身，见 `transcoded_wallpaper_hit_comes_first`）。
+    fn themes() -> PathBuf {
+        themes_dir(&roots())
+    }
+
+    #[test]
+    fn transcoded_wallpaper_hit_comes_first() {
+        let io = FakeIo::new().with_image(themes().join("TranscodedWallpaper"));
+        let probe = detect_with(&io, &env(), Platform::Windows);
+        assert_eq!(probe.len(), 1, "{:?}", probe.notes());
+        let best = probe.best().expect("有候选");
+        assert_eq!(best.kind, SourceKind::WindowsTranscoded);
+        assert_eq!(best.path, themes().join("TranscodedWallpaper"));
+        // 字面量：夹具路径是拿生产代码的构造函数造出来的，这条断言防止两边一起拼错。
+        assert_eq!(
+            best.path,
+            PathBuf::from(
+                "C:/Users/u/AppData/Roaming/Microsoft/Windows/Themes/TranscodedWallpaper"
+            )
+        );
+        assert!(best.evidence.contains("TranscodedWallpaper"));
+    }
+
+    #[test]
+    fn current_theme_is_read_from_local_app_data() {
+        // Win10+ 的真机形态：%APPDATA% 下没有 .theme，当前主题在 %LOCALAPPDATA%。
+        let io = FakeIo::new()
+            .with_command(
+                THEMES_QUERY,
+                &format!("    CurrentTheme    REG_SZ    {CUSTOM_THEME}\r\n"),
+            )
+            .with_file(
+                CUSTOM_THEME,
+                "[Control Panel\\Desktop]\r\nWallpaper=%SystemRoot%\\web\\wallpaper\\Windows\\img0.jpg\r\n",
+            )
+            .with_image("C:/Windows\\web\\wallpaper\\Windows\\img0.jpg");
+        let probe = detect_with(&io, &env(), Platform::Windows);
+        assert_eq!(probe.len(), 1, "{:?}", probe.notes());
+        let best = probe.best().expect("有候选");
+        assert_eq!(best.kind, SourceKind::WindowsCurrentTheme);
+        assert_eq!(
+            best.path,
+            PathBuf::from("C:/Windows\\web\\wallpaper\\Windows\\img0.jpg")
+        );
+        assert!(best.evidence.contains("CurrentTheme"), "{}", best.evidence);
+        assert!(best.evidence.contains("Windows\\Themes\\Custom.theme"));
+    }
+
+    #[test]
+    fn current_theme_expands_local_app_data_env_var() {
+        let io = FakeIo::new()
+            .with_command(
+                THEMES_QUERY,
+                "    CurrentTheme    REG_SZ    %LOCALAPPDATA%\\Microsoft\\Windows\\Themes\\Custom.theme\r\n",
+            )
+            .with_file(
+                CUSTOM_THEME,
+                "Wallpaper=C:\\Users\\u\\Pictures\\a.jpg\r\n",
+            )
+            .with_image(r"C:\Users\u\Pictures\a.jpg");
+        let probe = detect_with(&io, &env(), Platform::Windows);
+        assert_eq!(probe.len(), 1, "{:?}", probe.notes());
+        assert_eq!(
+            probe.best().expect("有候选").kind,
+            SourceKind::WindowsCurrentTheme
+        );
+    }
+
+    #[test]
+    fn authority_order_puts_saved_packages_last() {
+        // 四步全在场，路径互不相同：顺序必须是 转码副本 > 当前主题 > 注册表 > 另存包。
+        let package = themes().join("a.theme");
+        let io = FakeIo::new()
+            .with_image(themes().join("TranscodedWallpaper"))
+            .with_command(
+                THEMES_QUERY,
+                &format!("    CurrentTheme    REG_SZ    {CUSTOM_THEME}\r\n"),
+            )
+            .with_file(
+                CUSTOM_THEME,
+                "Wallpaper=C:\\Users\\u\\Pictures\\one.jpg\r\n",
+            )
+            .with_command(
+                DESKTOP_QUERY,
+                "    WallPaper    REG_SZ    C:\\Users\\u\\Pictures\\two.jpg\r\n",
+            )
+            .with_dir(themes(), &["a.theme", "b.theme", "notes.txt"])
+            .with_file(
+                package.clone(),
+                "Wallpaper=%SystemRoot%\\web\\wallpaper\\three.jpg\r\n",
+            )
+            .with_image(r"C:\Users\u\Pictures\one.jpg")
+            .with_image(r"C:\Users\u\Pictures\two.jpg")
+            .with_image("C:/Windows\\web\\wallpaper\\three.jpg");
+        let probe = detect_with(&io, &env(), Platform::Windows);
+        let seen: Vec<(SourceKind, String)> = probe
+            .iter()
+            .map(|source| (source.kind, source.path.display().to_string()))
+            .collect();
+        assert_eq!(seen.len(), 4, "{:?}", probe.notes());
+        assert_eq!(seen[0].0, SourceKind::WindowsTranscoded);
+        assert_eq!(seen[1].0, SourceKind::WindowsCurrentTheme);
+        assert_eq!(seen[2].0, SourceKind::WindowsRegistry);
+        assert_eq!(seen[3].0, SourceKind::WindowsThemeFile);
+        // 兜底档在 evidence 里如实标明「可能未启用」，调用方据此可降权。
+        assert!(
+            probe.sources()[3].evidence.contains("可能未启用"),
+            "{}",
+            probe.sources()[3].evidence
+        );
+    }
+
+    #[test]
+    fn everything_missing_returns_empty_with_reasons() {
+        let probe = detect_with(&FakeIo::new(), &env(), Platform::Windows);
+        assert!(probe.is_empty(), "全部失败要返回空列表而不是错误");
+        let notes = probe.notes().join("\n");
+        assert!(notes.contains("reg query"), "注册表失败要留原因：{notes}");
+        assert!(
+            notes.contains("CurrentTheme"),
+            "当前主题失败要留原因：{notes}"
+        );
+        assert!(
+            notes.contains("TranscodedWallpaper"),
+            "转码副本缺失要留原因：{notes}"
+        );
+    }
+
+    #[test]
+    fn same_path_from_two_steps_is_deduped() {
+        let transcoded = themes().join("TranscodedWallpaper");
+        let registry_value = transcoded.display().to_string().to_ascii_uppercase();
+        let io = FakeIo::new()
+            .with_image(&transcoded)
+            // 注册表指向同一个文件，大小写还不同（Windows 路径大小写不敏感）。
+            .with_command(
+                DESKTOP_QUERY,
+                &format!("    WallPaper    REG_SZ    {registry_value}\r\n"),
+            );
+        let probe = detect_with(&io, &env(), Platform::Windows);
+        assert_eq!(probe.len(), 1, "{:?}", probe.sources());
+        assert_eq!(
+            probe.best().expect("有候选").kind,
+            SourceKind::WindowsTranscoded
+        );
+    }
+}
diff --git a/crates/core/src/platform/wallpaper/windows/parse.rs b/crates/core/src/platform/wallpaper/windows/parse.rs
new file mode 100644
index 0000000..c737e72
--- /dev/null
+++ b/crates/core/src/platform/wallpaper/windows/parse.rs
@@ -0,0 +1,100 @@
+//! Windows 侧的纯解析函数：`.theme` 的 `Wallpaper=` 行与 `reg query` 输出的取值。
+//!
+//! 单独一个文件只为守住「单文件 ≤400 行」（`guards.yml` 的 file-size 闸）：这里没有任何
+//! IO，全部是纯函数，跨平台编译，夹具用例覆盖在文件尾部。
+
+/// 取 `.theme` 文本里所有 `Wallpaper=` 行的值（键名大小写不敏感，值去首尾空白）。
+///
+/// `.theme` 是 INI：`[Control Panel\Desktop]` 段下的 `Wallpaper=...`。`Wallpaper` 这个键名
+/// 本身不随系统语言变（Windows 只本地化少数键），所以直接按 ASCII 比对。
+pub(super) fn parse_theme_wallpaper(text: &str) -> Vec<String> {
+    text.lines()
+        .filter_map(|line| {
+            let (key, value) = line.split_once('=')?;
+            if !key.trim().eq_ignore_ascii_case("wallpaper") {
+                return None;
+            }
+            let value = value.trim();
+            (!value.is_empty()).then(|| value.to_owned())
+        })
+        .collect()
+}
+
+/// 取 `reg query <键> /v <值名>` 输出里某个值的原文。
+///
+/// 形如 `    WallPaper    REG_SZ    C:\Users\me\Pictures\a.jpg`；值里的空格要保留，所以
+/// 「值名 + 类型」之后的部分整段取原文（不能 `split_whitespace` 再拼，会吃掉连续空格）。
+/// 值名为 `WallPaper` 时是壁纸路径，`CurrentTheme` 时是 `.theme` 文件路径。
+pub(super) fn parse_reg_sz_value(text: &str, value_name: &str) -> Option<String> {
+    text.lines().find_map(|line| {
+        let trimmed = line.trim_start();
+        let name_end = trimmed.find(char::is_whitespace)?;
+        if !trimmed[..name_end].eq_ignore_ascii_case(value_name) {
+            return None;
+        }
+        let after_name = trimmed[name_end..].trim_start();
+        let kind_end = after_name.find(char::is_whitespace)?;
+        let value = after_name[kind_end..].trim();
+        (!value.is_empty()).then(|| value.to_owned())
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::{CURRENT_THEME_VALUE, WALLPAPER_VALUE};
+    use super::*;
+
+    const CUSTOM_THEME: &str = r"C:\Users\u\AppData\Local\Microsoft\Windows\Themes\Custom.theme";
+
+    #[test]
+    fn theme_text_yields_only_wallpaper_values() {
+        let text = "[Control Panel\\Desktop]\r\n\
+                    Wallpaper=C:\\Users\\u\\a.jpg\r\n\
+                    wallpaper = %SystemRoot%\\web\\wallpaper\\b.jpg\r\n\
+                    [Slideshow]\r\n\
+                    ImagesRootPath=C:\\Users\\u\\Pictures\r\n\
+                    Wallpaper=\r\n";
+        assert_eq!(
+            parse_theme_wallpaper(text),
+            vec![
+                r"C:\Users\u\a.jpg".to_owned(),
+                r"%SystemRoot%\web\wallpaper\b.jpg".to_owned(),
+            ]
+        );
+        assert!(parse_theme_wallpaper("").is_empty());
+    }
+
+    #[test]
+    fn reg_output_parses_value_and_keeps_spaces() {
+        assert_eq!(
+            parse_reg_sz_value(
+                "HKEY_CURRENT_USER\\Control Panel\\Desktop\r\n    \
+                 WallPaper    REG_SZ    C:\\Users\\Jak e\\Desktop Pictures\\a.jpg\r\n",
+                WALLPAPER_VALUE
+            ),
+            Some(r"C:\Users\Jak e\Desktop Pictures\a.jpg".to_owned())
+        );
+        // 纯色壁纸 = 空值。
+        assert_eq!(
+            parse_reg_sz_value("    WallPaper    REG_SZ    \r\n", WALLPAPER_VALUE),
+            None
+        );
+        assert_eq!(parse_reg_sz_value("", WALLPAPER_VALUE), None);
+        assert_eq!(
+            parse_reg_sz_value("    TileWallpaper    REG_SZ    0\r\n", WALLPAPER_VALUE),
+            None
+        );
+        // 当前主题：值名换成 CurrentTheme，取到的是 `.theme` 的绝对路径。
+        assert_eq!(
+            parse_reg_sz_value(
+                &format!("    CurrentTheme    REG_SZ    {CUSTOM_THEME}\r\n"),
+                CURRENT_THEME_VALUE
+            ),
+            Some(CUSTOM_THEME.to_owned())
+        );
+        assert_eq!(
+            parse_reg_sz_value("    CurrentTheme    REG_SZ    \r\n", CURRENT_THEME_VALUE),
+            None
+        );
+    }
+}
diff --git a/crates/core/src/platform/windows_version.rs b/crates/core/src/platform/windows_version.rs
new file mode 100644
index 0000000..bc9fd9b
--- /dev/null
+++ b/crates/core/src/platform/windows_version.rs
@@ -0,0 +1,215 @@
+//! Windows 版本探测：真实的 `major.minor.build`（D19 · `PlanDoc/11-os-detection.md` §2）。
+//!
+//! 数据源（从快到慢，探测发生在启动路径上）：
+//!
+//! 1. `reg query ... /v CurrentBuildNumber` 取 build 号，由 [`from_build`] 反推 `major.minor`
+//!    （build 号在版本族内单调；实测单值查询约 50ms，整键查询约 150ms）；
+//! 2. 整键 `HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion`：Win10+ 有
+//!    `CurrentMajorVersionNumber` / `CurrentMinorVersionNumber`（REG_DWORD，`reg query` 以
+//!    `0x..` 十六进制输出），Win7 / 8 / 8.1 只有 `CurrentVersion`（`6.1` / `6.2` / `6.3`，
+//!    Win10+ 上它是过期值）；
+//! 3. 兜底 `cmd /c ver`：输出 `Microsoft Windows [Version 10.0.19045.4046]`（中文系统为
+//!    `[版本 …]`）。只取方括号内的数字段，因此与系统语言无关。
+//!
+//! # 为什么不用 `RtlGetVersion`
+//!
+//! D19 原文方案是 `RtlGetVersion`（ntdll），但 core 是 `#![forbid(unsafe_code)]`
+//! （`lib.rs`，D3 架构纪律 + workspace lint `unsafe_code = deny`），FFI 一律不可用。
+//! 上面两条路径读的是同一份真实事实（`cmd.exe` 自带 manifest，报真实版本，不受
+//! `GetVersionEx` 兼容层欺骗），差别只是启动时一次性几毫秒 —— 结果由
+//! [`crate::platform::os_info::current`] 缓存，不会重复付这个代价。
+//!
+//! 解析函数是纯函数且**跨平台编译**，单测用注入样本覆盖各版本输出（见 `tests/platform/`）。
+
+/// Windows 11 的起始 build 号（22H2 之前就有 22000）。
+pub const WIN11_MIN_BUILD: u32 = 22_000;
+
+/// 存放版本值的注册表键。
+pub const VERSION_KEY: &str = r"HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion";
+
+/// Windows 真实版本。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct WindowsVersion {
+    /// 主版本号（Win7 = 6，Win10/11 = 10）。
+    pub major: u32,
+    /// 次版本号（Win7 = 1，Win10/11 = 0）。
+    pub minor: u32,
+    /// 构建号（Win7 SP1 = 7601，Win10 22H2 = 19045，Win11 = 22000+）。
+    pub build: u32,
+}
+
+impl WindowsVersion {
+    /// 构造。
+    pub fn new(major: u32, minor: u32, build: u32) -> Self {
+        Self {
+            major,
+            minor,
+            build,
+        }
+    }
+
+    /// `major.minor` 元组（最低版本判定用）。
+    pub fn major_minor(&self) -> (u32, u32) {
+        (self.major, self.minor)
+    }
+
+    /// 版本串（`rules.os.version` 用，例如 `10.0.19045`）。
+    pub fn version_string(&self) -> String {
+        format!("{}.{}.{}", self.major, self.minor, self.build)
+    }
+
+    /// 产品名（由版本号推导，不用本地化的注册表 `ProductName`）。
+    pub fn display_name(&self) -> &'static str {
+        match self.major_minor() {
+            (10, _) if self.build >= WIN11_MIN_BUILD => "Windows 11",
+            (10, _) => "Windows 10",
+            (6, 3) => "Windows 8.1",
+            (6, 2) => "Windows 8",
+            (6, 1) => "Windows 7",
+            (6, 0) => "Windows Vista",
+            (5, _) => "Windows XP",
+            _ => "Windows",
+        }
+    }
+}
+
+/// 真实探测；非 Windows 平台恒为 `None`。
+///
+/// 三档，从快到慢（探测在启动路径上，实测整键 `reg query` 会枚举上百个子键，约 150ms：
+/// 单值查询约 50ms）：
+/// 1. `reg query ... /v CurrentBuildNumber` 取 build，再由 [`from_build`] 反推 `major.minor`；
+/// 2. 整键查询（Win7 的 `CurrentVersion`、Win10+ 的数字键都在这里解析，见 [`parse_reg_query`]）；
+/// 3. `cmd /c ver`（注册表被策略禁用时的兜底）。
+#[cfg(target_os = "windows")]
+pub fn probe() -> Option<WindowsVersion> {
+    let fast = run("reg", &["query", VERSION_KEY, "/v", "CurrentBuildNumber"])
+        .and_then(|text| parse_build_number(&text))
+        .and_then(from_build);
+    if fast.is_some() {
+        return fast;
+    }
+    if let Some(version) =
+        run("reg", &["query", VERSION_KEY]).and_then(|text| parse_reg_query(&text))
+    {
+        return Some(version);
+    }
+    run("cmd", &["/c", "ver"]).and_then(|text| parse_ver_output(&text))
+}
+
+/// 真实探测；非 Windows 平台恒为 `None`。
+#[cfg(not(target_os = "windows"))]
+pub fn probe() -> Option<WindowsVersion> {
+    None
+}
+
+/// 由 build 号反推 `major.minor`（build 号在版本族内单调，是唯一一条免整键查询的快路径）。
+///
+/// 7600/7601 = 6.1（Win7 / 2008 R2）、9200 = 6.2（Win8 / 2012）、9600 = 6.3（Win8.1 / 2012 R2）、
+/// 10240+ = 10.0（Win10 / Win11 / Server 2016+）。认不出的 build 返回 `None`，
+/// 由 [`parse_reg_query`] / [`parse_ver_output`] 兜底。
+pub fn from_build(build: u32) -> Option<WindowsVersion> {
+    let (major, minor) = match build {
+        6000..=7599 => (6, 0),
+        7600..=9199 => (6, 1),
+        9200..=9599 => (6, 2),
+        9600..=10239 => (6, 3),
+        10240.. => (10, 0),
+        // Vista 之前的 build 号太小，不猜（交给整键/`ver` 解析）。
+        _ => return None,
+    };
+    Some(WindowsVersion::new(major, minor, build))
+}
+
+/// 从 `reg query ... /v CurrentBuildNumber` 的输出取 build 号。
+pub fn parse_build_number(text: &str) -> Option<u32> {
+    text.lines().find_map(|line| {
+        let mut fields = line.split_whitespace();
+        let name = fields.next()?;
+        if !name.eq_ignore_ascii_case("currentbuildnumber") {
+            return None;
+        }
+        let _kind = fields.next();
+        parse_number(fields.next().unwrap_or_default())
+    })
+}
+
+/// 解析 `reg query <VERSION_KEY>` 的输出。
+///
+/// 形如 `    CurrentBuildNumber    REG_SZ    19045`；DWORD 值以 `0x..` 输出。
+pub fn parse_reg_query(text: &str) -> Option<WindowsVersion> {
+    let mut major = None;
+    let mut minor = None;
+    let mut build = None;
+    let mut legacy = None;
+    for line in text.lines() {
+        let mut fields = line.split_whitespace();
+        let Some(name) = fields.next() else {
+            continue;
+        };
+        let _kind = fields.next();
+        let value = fields.next().unwrap_or_default();
+        match name.to_ascii_lowercase().as_str() {
+            "currentmajorversionnumber" => major = parse_number(value),
+            "currentminorversionnumber" => minor = parse_number(value),
+            "currentbuildnumber" => build = parse_number(value),
+            "currentversion" => legacy = parse_version_pair(value),
+            _ => {}
+        }
+    }
+    let build = build?;
+    let (major, minor) = match major {
+        Some(major) => (major, minor.unwrap_or(0)),
+        // Win7 / 8 / 8.1：没有 CurrentMajorVersionNumber，只能读 CurrentVersion。
+        None => legacy?,
+    };
+    Some(WindowsVersion::new(major, minor, build))
+}
+
+/// 解析 `cmd /c ver` 的输出（`Microsoft Windows [Version 10.0.19045.4046]`，
+/// 中文系统 `Microsoft Windows [版本 10.0.19045.4046]`）。
+pub fn parse_ver_output(text: &str) -> Option<WindowsVersion> {
+    let start = text.find('[')? + 1;
+    let rest = &text[start..];
+    let inner = &rest[..rest.find(']')?];
+    // 只保留数字与点，语言相关的字样（`Version` / `版本`）会被切成空段。
+    let digits = inner
+        .split(|c: char| !(c.is_ascii_digit() || c == '.'))
+        .find(|segment| segment.contains('.'))?;
+    let parts: Vec<u32> = digits
+        .split('.')
+        .take(3)
+        .map(str::parse)
+        .collect::<Result<_, _>>()
+        .ok()?;
+    match parts.as_slice() {
+        [major, minor, build] => Some(WindowsVersion::new(*major, *minor, *build)),
+        _ => None,
+    }
+}
+
+fn parse_number(value: &str) -> Option<u32> {
+    let trimmed = value.trim();
+    if let Some(hex) = trimmed
+        .strip_prefix("0x")
+        .or_else(|| trimmed.strip_prefix("0X"))
+    {
+        u32::from_str_radix(hex, 16).ok()
+    } else {
+        trimmed.parse().ok()
+    }
+}
+
+fn parse_version_pair(value: &str) -> Option<(u32, u32)> {
+    let (major, minor) = value.trim().split_once('.')?;
+    Some((major.parse().ok()?, minor.parse().ok()?))
+}
+
+#[cfg(target_os = "windows")]
+fn run(program: &str, args: &[&str]) -> Option<String> {
+    use std::process::Command;
+    let output = Command::new(program).args(args).output().ok()?;
+    if output.stdout.is_empty() {
+        return None;
+    }
+    Some(String::from_utf8_lossy(&output.stdout).into_owned())
+}
diff --git a/crates/core/src/setting/appearance/mod.rs b/crates/core/src/setting/appearance/mod.rs
new file mode 100644
index 0000000..e104f57
--- /dev/null
+++ b/crates/core/src/setting/appearance/mod.rs
@@ -0,0 +1,307 @@
+//! 「外观（高级）」配置簇的读写（D17 · `09-ui-layout.md` §2 G6 + §111 约束）。
+//!
+//! 为什么放在 core：主题令牌的**取值与校验**是配置事实，视觉实现（Slint 侧）只消费结果。
+//! 分层纪律要求 core 零 UI 依赖——本文件只认 `appearance.*` 这些键与它们的取值形状，
+//! 不认任何像素/控件（[`super::keys`] 登记同一份键表，两边由 `tests/setting/appearance_keys.rs` 固定）。
+//!
+//! 设计约束（09 §111）：一切高级特性**默认关闭**（出厂 Metro 纯色）；全部走 D6 schema
+//! （AI 可写白名单内，可被 agent 调节）。因此默认值必须等于「什么都没开」的出厂态：
+//! `panel_alpha = 1.0`、`glass = false`、`bg_image_enabled = false`、`accent` 空串（= 出厂 accent）。
+//!
+//! P4 追加的三个「下层键」（M91 / D34·D36·D37·D38，同样是**出厂即可见**的默认值）：
+//!
+//! | 键 | 取值 | 出厂 | 本模块负责 / 不负责 |
+//! |---|---|---|---|
+//! | `appearance.window_opacity` | `0.08..=1.0` | `1.0` | 负责钳位；**不**调 FFI（落点在 `app-iced` 的 win32 层） |
+//! | `appearance.titlebar_mode` | `auto` / `always` / `never` | `auto` | 只存值；`auto` 的判定属于 UI 侧（WCHROME-IMPL） |
+//! | `appearance.palette_source` | `background-image` / `wallpaper` / `preset` | `preset` | 只存档位；三级编排在 `unlucky-design`（D38） |
+//! | `appearance.window_corner` | `system` / `square` | `system` | 只存策略；「这台机器能不能圆」的判定在 `app-iced` 的 `platform`（M116） |
+//!
+//! 非法枚举**不报错**但也**不静默**：[`diagnostics`] 给出「读到什么 → 生效什么」的可读说明。
+
+use serde_json::Value;
+
+use super::document::SettingDocument;
+use super::store::SettingStore;
+
+mod modes;
+
+pub use modes::{
+    diagnostics, AppearanceDiagnostic, PaletteSource, TitlebarMode, WindowCorner, PALETTE_SOURCES,
+    TITLEBAR_MODES, WINDOW_CORNERS,
+};
+
+#[cfg(test)]
+mod tests;
+
+/// `appearance.bg_fill` 的允许值（09 §101：cover / contain / tile）。**顺序即 UI 分段控件的顺序**。
+pub const BG_FILLS: &[&str] = &["cover", "contain", "tile"];
+
+/// 出厂强调色（Metro 蓝，D14）；`appearance.accent_color` 为空串时用它。
+pub const DEFAULT_ACCENT: &str = "#0078D4";
+
+/// `appearance.panel_alpha` 下限：再低前景就压不住背景图（09 §111「对比度检查提示」的硬底）。
+pub const PANEL_ALPHA_MIN: f64 = 0.4;
+/// `appearance.bg_dim` 下限（0 = 不暗化，允许但设置页会提示对比度风险）。
+pub const BG_DIM_MIN: f64 = 0.0;
+/// `appearance.bg_dim` 上限：再高背景图基本看不见，等于关掉。
+pub const BG_DIM_MAX: f64 = 0.95;
+
+/// `appearance.window_opacity` 下限（D36 定案 0.08）：这是**整窗** α 的硬底。
+///
+/// 为什么不是 0：α = 0 时窗口内容整体不可见 = 整窗穿透，用户会以为程序卡死/消失了。
+/// 0.08 是「几乎看不见但仍能点到」的最后一档，比它更低不给设置。面板 α（[`PANEL_ALPHA_MIN`]）
+/// 是另一回事，两者互不推导。
+pub const WINDOW_ALPHA_MIN: f64 = 0.08;
+
+/// 背景图填充模式。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum BgFill {
+    /// 等比铺满、裁切溢出（默认：不露底色）
+    #[default]
+    Cover,
+    /// 等比完整显示、留底色
+    Contain,
+    /// 原始尺寸平铺
+    Tile,
+}
+
+impl BgFill {
+    /// 落盘取值。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Cover => "cover",
+            Self::Contain => "contain",
+            Self::Tile => "tile",
+        }
+    }
+
+    /// 从落盘取值解析；未知值按 `cover` 兜底（手改坏配置也不崩）。
+    #[must_use]
+    pub fn from_key_value(value: &str) -> Self {
+        match value {
+            "contain" => Self::Contain,
+            "tile" => Self::Tile,
+            _ => Self::Cover,
+        }
+    }
+}
+
+/// 外观（高级）配置簇：**只是取值快照**，读写都走 [`super::store::SettingStore`]。
+#[derive(Debug, Clone, PartialEq)]
+pub struct Appearance {
+    /// 主题三态：`auto` / `light` / `dark`（与 `prefs::ThemeMode` 同名同值）。
+    pub theme_mode: String,
+    /// 自定义窗口背景图开关（默认关）。
+    pub bg_image_enabled: bool,
+    /// 背景图路径（PNG；空 = 未设置）。
+    pub bg_image: String,
+    /// 背景图填充模式。
+    pub bg_fill: BgFill,
+    /// 叠加暗化层强度 0.0~0.95（越大前景越清晰）。
+    pub bg_dim: f64,
+    /// 全局面板半透明度 0.4~1.0（1.0 = 出厂不透明）。
+    pub panel_alpha: f64,
+    /// 玻璃拟态卡片（预生成模糊背景层）。
+    pub glass: bool,
+    /// 自定义强调色 `#RRGGBB`（空串 = 出厂 [`DEFAULT_ACCENT`]）。
+    pub accent_color: String,
+    /// 整窗透明度 [`WINDOW_ALPHA_MIN`]~1.0（1.0 = 出厂完全不透明；D36）。
+    ///
+    /// 只管取值：真正的窗口 α 由 `unlucky-app-iced` 的 win32 层调
+    /// `SetLayeredWindowAttributes(LWA_ALPHA)` 落地，core 不碰 FFI。
+    pub window_opacity: f64,
+    /// 标题栏三态（D37）。`auto` 怎么判定属于 UI 侧，core 只存用户的选择。
+    pub titlebar_mode: TitlebarMode,
+    /// 配色来源档（D38 三级；默认 [`PaletteSource::Preset`] = 内置色卡）。
+    pub palette_source: PaletteSource,
+    /// 窗口外框圆角策略（M116；默认 [`WindowCorner::System`] = 跟随系统）。
+    ///
+    /// 只管用户要什么：真能不能圆由平台决定（Win11/Server 2025 走 DWM，Win10 保持直角），
+    /// 判定在 `unlucky-app-iced` 的 `platform`，core 不探测系统。
+    pub window_corner: WindowCorner,
+}
+
+impl Default for Appearance {
+    fn default() -> Self {
+        Self {
+            theme_mode: "auto".to_owned(),
+            bg_image_enabled: false,
+            bg_image: String::new(),
+            bg_fill: BgFill::Cover,
+            bg_dim: 0.35,
+            panel_alpha: 1.0,
+            glass: false,
+            accent_color: String::new(),
+            window_opacity: 1.0,
+            titlebar_mode: TitlebarMode::Auto,
+            palette_source: PaletteSource::Preset,
+            window_corner: WindowCorner::System,
+        }
+    }
+}
+
+impl Appearance {
+    /// 从配置文档读一份快照（文件值 → 默认值；坏值按默认值兜底，绝不 panic）。
+    #[must_use]
+    pub fn read(doc: &SettingDocument) -> Self {
+        let default = Self::default();
+        let text = |key: &str| doc.effective_str(key).map(str::to_owned);
+        let boolean = |key: &str| doc.effective(key).and_then(Value::as_bool);
+        let number = |key: &str| doc.effective(key).and_then(Value::as_f64);
+
+        Self {
+            theme_mode: text("appearance.theme_mode").unwrap_or(default.theme_mode),
+            bg_image_enabled: boolean("appearance.bg_image_enabled").unwrap_or(false),
+            bg_image: text("appearance.bg_image").unwrap_or_default(),
+            bg_fill: text("appearance.bg_fill")
+                .map_or(default.bg_fill, |value| BgFill::from_key_value(&value)),
+            bg_dim: number("appearance.bg_dim")
+                .map_or(default.bg_dim, |value| clamp(value, BG_DIM_MIN, BG_DIM_MAX)),
+            panel_alpha: number("appearance.panel_alpha").map_or(default.panel_alpha, |value| {
+                clamp(value, PANEL_ALPHA_MIN, 1.0)
+            }),
+            glass: boolean("appearance.glass").unwrap_or(false),
+            accent_color: text("appearance.accent_color")
+                .map(|value| normalize_hex(&value).unwrap_or_default())
+                .unwrap_or_default(),
+            window_opacity: number("appearance.window_opacity")
+                .map_or(default.window_opacity, |value| {
+                    clamp(value, WINDOW_ALPHA_MIN, 1.0)
+                }),
+            titlebar_mode: text("appearance.titlebar_mode")
+                .map_or(default.titlebar_mode, |value| {
+                    TitlebarMode::from_key_value(&value)
+                }),
+            palette_source: text("appearance.palette_source")
+                .map_or(default.palette_source, |value| {
+                    PaletteSource::from_key_value(&value)
+                }),
+            window_corner: text("appearance.window_corner")
+                .map_or(default.window_corner, |value| {
+                    WindowCorner::from_key_value(&value)
+                }),
+        }
+    }
+
+    /// 从 store 读（配置读写的统一入口）。
+    #[must_use]
+    pub fn from_store(store: &SettingStore) -> Self {
+        Self::read(store.doc())
+    }
+
+    /// 实际生效的强调色：未自定义时回落到出厂 accent。
+    #[must_use]
+    pub fn accent_or_default(&self) -> &str {
+        if self.accent_color.is_empty() {
+            DEFAULT_ACCENT
+        } else {
+            &self.accent_color
+        }
+    }
+
+    /// 背景图是否真的会用上（开关打开 **且** 路径非空）。
+    #[must_use]
+    pub fn bg_image_active(&self) -> bool {
+        self.bg_image_enabled && !self.bg_image.trim().is_empty()
+    }
+
+    /// 写回一组键（调用方负责 `save()`；默认值不落盘由 `SettingDocument` 决定）。
+    ///
+    /// 值先过一遍规范化：`bg_fill` 认枚举、`bg_dim`/`panel_alpha` 夹到范围内、
+    /// `accent_color` 只接受 `#RRGGBB`（空串表示清掉自定义）。
+    ///
+    /// # Errors
+    /// 键值被 schema 拒绝（只读文件 / 未知键 / 越界）时返回 [`super::error::SettingError`]。
+    pub fn write(&self, store: &mut SettingStore) -> super::error::SettingResult<()> {
+        store.set(
+            "appearance.theme_mode",
+            Value::from(self.theme_mode.as_str()),
+        )?;
+        store.set(
+            "appearance.bg_image_enabled",
+            Value::from(self.bg_image_enabled),
+        )?;
+        store.set("appearance.bg_image", Value::from(self.bg_image.as_str()))?;
+        store.set("appearance.bg_fill", Value::from(self.bg_fill.as_str()))?;
+        store.set(
+            "appearance.bg_dim",
+            Value::from(clamp(self.bg_dim, BG_DIM_MIN, BG_DIM_MAX)),
+        )?;
+        store.set(
+            "appearance.panel_alpha",
+            Value::from(clamp(self.panel_alpha, PANEL_ALPHA_MIN, 1.0)),
+        )?;
+        store.set("appearance.glass", Value::from(self.glass))?;
+        store.set(
+            "appearance.accent_color",
+            Value::from(self.accent_color.as_str()),
+        )?;
+        // 越界钳位而不是报错（D36）：α 的下限是硬底，不许把窗口写到穿透；
+        // 上限 1.0 = 完全不透明。非法枚举（titlebar_mode / palette_source）由
+        // `as_str()` 保证永远是合法字面量，不会写坏文件。
+        store.set(
+            "appearance.window_opacity",
+            Value::from(clamp(self.window_opacity, WINDOW_ALPHA_MIN, 1.0)),
+        )?;
+        store.set(
+            "appearance.titlebar_mode",
+            Value::from(self.titlebar_mode.as_str()),
+        )?;
+        store.set(
+            "appearance.palette_source",
+            Value::from(self.palette_source.as_str()),
+        )?;
+        store.set(
+            "appearance.window_corner",
+            Value::from(self.window_corner.as_str()),
+        )?;
+        Ok(())
+    }
+}
+
+/// `#RRGGBB` 规范化（大写、去空格）；不合法返回 `None`。
+#[must_use]
+pub fn normalize_hex(text: &str) -> Option<String> {
+    let trimmed = text.trim();
+    let body = trimmed.strip_prefix('#').unwrap_or(trimmed);
+    if body.len() != 6 || !body.chars().all(|ch| ch.is_ascii_hexdigit()) {
+        return None;
+    }
+    Some(format!("#{}", body.to_ascii_uppercase()))
+}
+
+/// `#RRGGBB` → `(r, g, b)`（UI 侧构造颜色用）。
+#[must_use]
+pub fn hex_to_rgb(text: &str) -> Option<(u8, u8, u8)> {
+    let hex = normalize_hex(text)?;
+    let byte = |range: std::ops::Range<usize>| u8::from_str_radix(&hex[range], 16).ok();
+    Some((byte(1..3)?, byte(3..5)?, byte(5..7)?))
+}
+
+/// 相对亮度（WCAG 2.x，`0.0`~`1.0`）：设置页「对比度检查提示」用它判断前景是否够读。
+#[must_use]
+pub fn relative_luminance(text: &str) -> Option<f64> {
+    let (r, g, b) = hex_to_rgb(text)?;
+    let channel = |value: u8| {
+        let value = f64::from(value) / 255.0;
+        if value <= 0.039_28 {
+            value / 12.92
+        } else {
+            ((value + 0.055) / 1.055).powf(2.4)
+        }
+    };
+    Some(0.2126f64.mul_add(
+        channel(r),
+        0.7152f64.mul_add(channel(g), 0.0722 * channel(b)),
+    ))
+}
+
+fn clamp(value: f64, min: f64, max: f64) -> f64 {
+    if value.is_nan() {
+        min
+    } else {
+        value.clamp(min, max)
+    }
+}
diff --git a/crates/core/src/setting/appearance/modes.rs b/crates/core/src/setting/appearance/modes.rs
new file mode 100644
index 0000000..4828d3b
--- /dev/null
+++ b/crates/core/src/setting/appearance/modes.rs
@@ -0,0 +1,207 @@
+//! 外观三键的取值表与「非法值回落」诊断（D36 / D37 / D38）。
+//!
+//! 与 [`super`] 拆开只为单文件 ≤400 行的纪律：这里是纯字面量表 + 纯判据，
+//! 不碰文档读写。对外路径仍是 `setting::appearance::*`（[`super`] 逐个重导出）。
+
+use serde_json::Value;
+
+use crate::setting::document::SettingDocument;
+
+/// `appearance.titlebar_mode` 的允许值（D37 三态）。**顺序即设置页分段控件的顺序**。
+pub const TITLEBAR_MODES: &[&str] = &["auto", "always", "never"];
+
+/// `appearance.window_corner` 的允许值（M116）。**顺序即设置页分段控件的顺序**。
+///
+/// 只有两档是**刻意**的：系统不暴露圆角半径（Win32 没有「给我 DWM 的圆角像素值」这种 API），
+/// 所以「固定 8/12/16」这类档位只能是自绘圆角，而自绘圆角在 `decorations=false` + 整窗 α 的
+/// 窗口上必须裁内容层，会把标题栏三键与缩放热区一起裁掉。用户定案（2026-11-03）：只留
+/// 「跟随系统 / 直角」。
+pub const WINDOW_CORNERS: &[&str] = &["system", "square"];
+
+/// 窗口外框圆角策略（M116）。
+///
+/// 只表达**用户要什么**；「这台机器能做到什么」的判定在 UI 侧（`app-iced` 的 `platform`）：
+/// core 不探测系统能力（与 [`TitlebarMode`] 同一条纪律）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum WindowCorner {
+    /// 跟随系统：Win11 / Server 2025 内核（build ≥ 22000）用 DWM 圆角，Win10 保持直角
+    #[default]
+    System,
+    /// 直角：任何平台都不加圆角
+    Square,
+}
+
+impl WindowCorner {
+    /// 落盘取值。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::System => "system",
+            Self::Square => "square",
+        }
+    }
+
+    /// 从落盘取值解析；未知值按 `system` 兜底（手改坏配置也不崩，回落原因由
+    /// [`diagnostics`] 给出可读诊断）。
+    #[must_use]
+    pub fn from_key_value(value: &str) -> Self {
+        match value {
+            "square" => Self::Square,
+            _ => Self::System,
+        }
+    }
+}
+
+/// 标题栏三态（D37）。
+///
+/// 只持有「用户想要哪种」，**不含** `auto` 的判定 —— 「非 Wayland → 显示 / 合成器名精确命中
+/// → 隐藏 / 旁证 / 兜底显示」那套顺序属于 UI 侧（WCHROME-IMPL），core 不探测环境。
+/// 特别地：判定不许用 `is_decorated()`，那条纪律与本文档无关，别在这里实现。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum TitlebarMode {
+    /// 按平台/合成器自动决定（默认；由 UI 侧判定）
+    #[default]
+    Auto,
+    /// 永远显示自绘标题栏
+    Always,
+    /// 永远不显示（合成器已给服务端装饰时）
+    Never,
+}
+
+impl TitlebarMode {
+    /// 落盘取值。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Auto => "auto",
+            Self::Always => "always",
+            Self::Never => "never",
+        }
+    }
+
+    /// 从落盘取值解析；未知值按 `auto` 兜底（手改坏配置也不崩，
+    /// 回落原因由 [`diagnostics`] 给出可读诊断）。
+    #[must_use]
+    pub fn from_key_value(value: &str) -> Self {
+        match value {
+            "always" => Self::Always,
+            "never" => Self::Never,
+            _ => Self::Auto,
+        }
+    }
+}
+
+/// `appearance.palette_source` 的允许值：D38 的三级配色来源。
+///
+/// **取值与 `unlucky_design::palette::Level::code()` 同名同值**（`background-image` /
+/// `wallpaper` / `preset`）。这里抄字面量而不是引用 design：`core` 不许反过来依赖 UI 侧
+/// （分层纪律，D3），一致性由 `tests` 里的字面量断言固定 —— 与 `JDK_VENDORS` 的处理同一条路子。
+pub const PALETTE_SOURCES: &[&str] = &["background-image", "wallpaper", "preset"];
+
+/// 配色来源档（D38：背景图取色 > 桌面壁纸取色 > 内置色卡）。
+///
+/// 这个键**不是**优先级链本身（链在 `design::palette::resolve` 里），而是「当前生效的档」
+/// 与「用户/调用方希望的最强来源」的登记位：默认 [`Self::Preset`] 对应莫奈取色关闭的出厂态。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum PaletteSource {
+    /// ① 启动器背景图取色
+    BackgroundImage,
+    /// ② 桌面壁纸取色
+    Wallpaper,
+    /// ③ 内置色卡（默认：出厂不取色）
+    #[default]
+    Preset,
+}
+
+impl PaletteSource {
+    /// 落盘取值（与 design 侧 `Level::code()` 逐字一致）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::BackgroundImage => "background-image",
+            Self::Wallpaper => "wallpaper",
+            Self::Preset => "preset",
+        }
+    }
+
+    /// 从落盘取值解析；未知值按 `preset`（内置色卡）兜底。
+    #[must_use]
+    pub fn from_key_value(value: &str) -> Self {
+        match value {
+            "background-image" => Self::BackgroundImage,
+            "wallpaper" => Self::Wallpaper,
+            _ => Self::Preset,
+        }
+    }
+}
+
+/// 一次「按默认档兜底」的诊断：哪个键、读到了什么、兜底成什么、一句给人看的话。
+///
+/// 存在的理由：非法枚举**不报错**（配置坏掉不该把启动器卡住），但也**不许静默**——
+/// 用户/日志要能看出「我写的 `always` 拼错了，现在按 auto 跑」。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AppearanceDiagnostic {
+    /// 出问题的键。
+    pub key: &'static str,
+    /// 文件里读到的原始文本。
+    pub raw: String,
+    /// 实际生效的兜底档。
+    pub fallback: &'static str,
+    /// 一句可读的说明（可直接进日志；UI 侧可再包一层文案）。
+    pub message: String,
+}
+
+/// 读出需要提示的回落（空 = 一切正常）。
+///
+/// 只覆盖**枚举型**键（`titlebar_mode` / `palette_source` / `window_corner`）。数值键
+/// （`window_opacity`）越界是「钳位且不报错」的既定语义（D36 下限 0.08），不算诊断项。
+#[must_use]
+pub fn diagnostics(doc: &SettingDocument) -> Vec<AppearanceDiagnostic> {
+    let mut found = Vec::new();
+    let text = |key: &str| {
+        doc.effective(key)
+            .and_then(Value::as_str)
+            .map(str::to_owned)
+    };
+
+    if let Some(raw) = text("appearance.titlebar_mode") {
+        if !TITLEBAR_MODES.contains(&raw.as_str()) {
+            let fallback = TitlebarMode::Auto.as_str();
+            found.push(AppearanceDiagnostic {
+                key: "appearance.titlebar_mode",
+                message: format!(
+                    "appearance.titlebar_mode 的值 {raw:?} 不在 {TITLEBAR_MODES:?} 之中，已按 {fallback} 处理"
+                ),
+                raw,
+                fallback,
+            });
+        }
+    }
+    if let Some(raw) = text("appearance.palette_source") {
+        if !PALETTE_SOURCES.contains(&raw.as_str()) {
+            let fallback = PaletteSource::Preset.as_str();
+            found.push(AppearanceDiagnostic {
+                key: "appearance.palette_source",
+                message: format!(
+                    "appearance.palette_source 的值 {raw:?} 不在 {PALETTE_SOURCES:?} 之中，已按 {fallback} 处理"
+                ),
+                raw,
+                fallback,
+            });
+        }
+    }
+    if let Some(raw) = text("appearance.window_corner") {
+        if !WINDOW_CORNERS.contains(&raw.as_str()) {
+            let fallback = WindowCorner::System.as_str();
+            found.push(AppearanceDiagnostic {
+                key: "appearance.window_corner",
+                message: format!(
+                    "appearance.window_corner 的值 {raw:?} 不在 {WINDOW_CORNERS:?} 之中，已按 {fallback} 处理"
+                ),
+                raw,
+                fallback,
+            });
+        }
+    }
+    found
+}
diff --git a/crates/core/src/setting/appearance/tests.rs b/crates/core/src/setting/appearance/tests.rs
new file mode 100644
index 0000000..4775522
--- /dev/null
+++ b/crates/core/src/setting/appearance/tests.rs
@@ -0,0 +1,215 @@
+//! 外观三键（整窗透明度 / 标题栏三态 / 配色来源）的读侧契约。
+//!
+//! 与 `mod.rs` 拆开只为单文件 ≤400 行的纪律（D36/D37/D38 的键仍是
+//! `setting::appearance::*`），测试属于同一个模块。
+
+use serde_json::json;
+
+use super::{
+    diagnostics, Appearance, PaletteSource, TitlebarMode, WindowCorner, PALETTE_SOURCES,
+    TITLEBAR_MODES, WINDOW_ALPHA_MIN, WINDOW_CORNERS,
+};
+use crate::setting::document::SettingDocument;
+use crate::setting::keys::launcher_schema;
+use crate::setting::schema::{SchemaId, SchemaRef, SchemaVersion};
+use crate::setting::store::SettingStore;
+
+fn doc(raw: serde_json::Value) -> SettingDocument {
+    SettingDocument::load(&launcher_schema(), &raw).0
+}
+
+#[test]
+fn missing_keys_fall_back_to_factory_values() {
+    let document = doc(json!({}));
+    let appearance = Appearance::read(&document);
+    assert_eq!(appearance.window_opacity, 1.0, "D36：出厂完全不透明");
+    assert_eq!(
+        appearance.titlebar_mode,
+        TitlebarMode::Auto,
+        "D37：默认 auto"
+    );
+    assert_eq!(
+        appearance.palette_source,
+        PaletteSource::Preset,
+        "D38：默认内置色卡（莫奈取色关闭的出厂档）"
+    );
+    assert!(
+        diagnostics(&document).is_empty(),
+        "缺键 = 取默认，不该产生回落诊断"
+    );
+}
+
+#[test]
+fn window_opacity_is_clamped_to_the_d36_floor() {
+    let cases = [
+        (0.0, WINDOW_ALPHA_MIN),
+        (0.02, WINDOW_ALPHA_MIN),
+        (WINDOW_ALPHA_MIN, WINDOW_ALPHA_MIN),
+        (0.5, 0.5),
+        (1.0, 1.0),
+        (4.0, 1.0),
+    ];
+    for (raw, want) in cases {
+        let appearance = Appearance::read(&doc(json!({ "appearance": { "window_opacity": raw } })));
+        assert!(
+            (appearance.window_opacity - want).abs() < 1e-9,
+            "window_opacity={raw} 应读出 {want}，实际 {}",
+            appearance.window_opacity
+        );
+    }
+}
+
+#[test]
+fn out_of_range_opacity_is_clamped_not_rejected() {
+    // 手改文件绕过 schema：load 只记一条 problem（不失败、不 panic），读侧再夹一次。
+    let (document, problems) = SettingDocument::load(
+        &launcher_schema(),
+        &json!({ "appearance": { "window_opacity": 0.02 } }),
+    );
+    assert!(
+        !problems.is_empty(),
+        "越界值必须留下痕迹（LoadProblem），否则「钳位」变成静默改用户的数"
+    );
+    assert!((Appearance::read(&document).window_opacity - WINDOW_ALPHA_MIN).abs() < 1e-9);
+
+    // 类型错（字符串）也不算错误：回落默认 1.0。
+    let appearance = Appearance::read(&doc(json!({ "appearance": { "window_opacity": "half" } })));
+    assert_eq!(appearance.window_opacity, 1.0);
+}
+
+#[test]
+fn illegal_enum_falls_back_and_leaves_a_readable_diagnostic() {
+    let document = doc(json!({
+        "appearance": { "titlebar_mode": "allways", "palette_source": "desktop" }
+    }));
+    let appearance = Appearance::read(&document);
+    assert_eq!(appearance.titlebar_mode, TitlebarMode::Auto);
+    assert_eq!(appearance.palette_source, PaletteSource::Preset);
+
+    let found = diagnostics(&document);
+    assert_eq!(found.len(), 2, "两个非法枚举各一条诊断：{found:?}");
+    assert_eq!(found[0].key, "appearance.titlebar_mode");
+    assert_eq!(found[0].raw, "allways");
+    assert_eq!(found[0].fallback, "auto");
+    assert!(
+        found[0].message.contains("allways") && found[0].message.contains("auto"),
+        "诊断要同时说清「读到了什么」和「生效的是什么」：{}",
+        found[0].message
+    );
+    assert_eq!(found[1].key, "appearance.palette_source");
+    assert_eq!(found[1].raw, "desktop");
+    assert_eq!(found[1].fallback, "preset");
+}
+
+#[test]
+fn value_tables_are_self_consistent() {
+    assert_eq!(TITLEBAR_MODES, ["auto", "always", "never"], "D37 三态");
+    // 这里只钉 **core 自己的字面量**（改这三个字符串要过这一关）。
+    // 与 `unlucky_design::palette::Level::code()` 的一致性 core 守不了——core 不依赖 design
+    // （分层纪律），本 crate 的测试永远看不到 design 的代码。那条一致性由
+    // `crates/app-iced/src/platform/mod.rs::palette_source_codes_match_design_level_codes`
+    // 守（那个 crate 同时依赖 design 与 presenter，是唯一能对照的地方）。
+    assert_eq!(
+        PALETTE_SOURCES,
+        ["background-image", "wallpaper", "preset"],
+        "D38 三级（与 design 的 Level::code() 同名）"
+    );
+    for source in [
+        PaletteSource::BackgroundImage,
+        PaletteSource::Wallpaper,
+        PaletteSource::Preset,
+    ] {
+        assert_eq!(PaletteSource::from_key_value(source.as_str()), source);
+        assert!(PALETTE_SOURCES.contains(&source.as_str()));
+    }
+    for mode in [
+        TitlebarMode::Auto,
+        TitlebarMode::Always,
+        TitlebarMode::Never,
+    ] {
+        assert_eq!(TitlebarMode::from_key_value(mode.as_str()), mode);
+        assert!(TITLEBAR_MODES.contains(&mode.as_str()));
+    }
+}
+
+#[test]
+fn older_document_loads_and_write_back_keeps_existing_keys() {
+    let temp = std::env::temp_dir().join(format!(
+        "ull-appearance-base-{}-{}",
+        std::process::id(),
+        line!()
+    ));
+    std::fs::create_dir_all(temp.join("config")).expect("临时目录");
+    let path = temp.join("config/launcher.json");
+    let _ = std::fs::remove_file(&path);
+
+    // 1.3.0 的老文件：没有任何新键，但已有外观键要原样保住。
+    let old = json!({
+        "$schema": SchemaRef::new(SchemaId::LAUNCHER, SchemaVersion::new(1, 3, 0)).url(),
+        "appearance": { "theme_mode": "dark", "panel_alpha": 0.8, "glass": true }
+    });
+    std::fs::write(&path, serde_json::to_vec_pretty(&old).expect("序列化")).expect("写老文件");
+
+    let mut store = SettingStore::load(&path, launcher_schema());
+    let before = Appearance::read(store.doc());
+    assert_eq!(before.theme_mode, "dark", "老文件的已有键照读");
+    assert!((before.panel_alpha - 0.8).abs() < 1e-9);
+    assert!(before.glass);
+
+    let mut appearance = before;
+    appearance.window_opacity = 0.9;
+    appearance.titlebar_mode = TitlebarMode::Always;
+    appearance.write(&mut store).expect("写新键");
+    store.save().expect("落盘");
+
+    let reloaded = Appearance::from_store(&SettingStore::load(&path, launcher_schema()));
+    assert!((reloaded.window_opacity - 0.9).abs() < 1e-9);
+    assert_eq!(reloaded.titlebar_mode, TitlebarMode::Always);
+    assert_eq!(
+        reloaded.palette_source,
+        PaletteSource::Preset,
+        "未写的键仍是默认"
+    );
+    assert_eq!(reloaded.theme_mode, "dark", "写回不许丢已有键");
+    assert!((reloaded.panel_alpha - 0.8).abs() < 1e-9);
+    assert!(reloaded.glass);
+
+    std::fs::remove_dir_all(&temp).ok();
+}
+
+/// **M116**：圆角键的三条读侧语义——缺键取默认、合法值往返、坏值落回 `system` 并**留诊断**。
+///
+/// 抓得住：把 `from_key_value` 的兜底写成 `Square`（那会让「配置写坏了」变成「用户想要直角」）、
+/// 或者漏掉 `diagnostics` 里那一条（静默回落）。
+/// 抓不住：这台机器能不能真圆（那是 UI 侧 `platform::plan_corner` 的事）。
+#[test]
+fn window_corner_falls_back_to_follow_system_and_says_so() {
+    let appearance = Appearance::read(&doc(json!({})));
+    assert_eq!(
+        appearance.window_corner,
+        WindowCorner::System,
+        "缺键 = 出厂 = 跟随系统"
+    );
+    assert!(
+        diagnostics(&doc(json!({}))).is_empty(),
+        "缺键不是回落，不该有诊断"
+    );
+
+    for corner in [WindowCorner::System, WindowCorner::Square] {
+        assert_eq!(WindowCorner::from_key_value(corner.as_str()), corner);
+        assert!(WINDOW_CORNERS.contains(&corner.as_str()));
+        let read = Appearance::read(&doc(
+            json!({ "appearance": { "window_corner": corner.as_str() } }),
+        ));
+        assert_eq!(read.window_corner, corner);
+    }
+
+    // 坏值：不报错、不崩，落到 system，但**必须**留下可读诊断。
+    let bad = doc(json!({ "appearance": { "window_corner": "rounded" } }));
+    assert_eq!(Appearance::read(&bad).window_corner, WindowCorner::System);
+    let notes = diagnostics(&bad);
+    assert_eq!(notes.len(), 1, "{notes:?}");
+    assert_eq!(notes[0].key, "appearance.window_corner");
+    assert_eq!(notes[0].fallback, "system");
+    assert!(notes[0].message.contains("rounded"), "{}", notes[0].message);
+}
diff --git a/crates/core/src/setting/catalog.rs b/crates/core/src/setting/catalog.rs
new file mode 100644
index 0000000..2535618
--- /dev/null
+++ b/crates/core/src/setting/catalog.rs
@@ -0,0 +1,195 @@
+//! 一份配置文件的键目录：[`SettingSchema`] 把 key → 元数据查表能力收拢在一处。
+//!
+//! 与 [`super::spec`] 的分工：`spec` 定义「一个键长什么样」，这里定义「一份文件的键集合」，
+//! 并对外提供 AI 白名单 / 校验 / 工具 JSON Schema 投影（M16 `ToolSpec` 直接吃这份投影）。
+
+use std::collections::BTreeSet;
+
+use serde_json::{json, Map, Value};
+
+use super::error::{SettingError, SettingResult};
+use super::schema::{SchemaId, SchemaRef, SchemaVersion};
+use super::spec::{Sensitivity, SettingSpec};
+
+/// 一份配置文件里所有键的集合。
+#[derive(Debug, Clone, PartialEq)]
+pub struct SettingSchema {
+    id: SchemaId,
+    version: SchemaVersion,
+    specs: Vec<SettingSpec>,
+}
+
+impl SettingSchema {
+    /// 空 schema。
+    #[must_use]
+    pub fn new(id: SchemaId, version: SchemaVersion) -> Self {
+        Self {
+            id,
+            version,
+            specs: Vec::new(),
+        }
+    }
+
+    /// 链式加一个键（重复键直接 panic —— 这是编译期就该发现的表写错）。
+    #[must_use]
+    pub fn with(mut self, spec: SettingSpec) -> Self {
+        assert!(
+            !self.specs.iter().any(|existing| existing.key == spec.key),
+            "重复的配置键: {}",
+            spec.key
+        );
+        self.specs.push(spec);
+        self
+    }
+
+    /// 种类。
+    #[must_use]
+    pub const fn id(&self) -> SchemaId {
+        self.id
+    }
+
+    /// 版本。
+    #[must_use]
+    pub const fn version(&self) -> SchemaVersion {
+        self.version
+    }
+
+    /// `$schema` 标识。
+    #[must_use]
+    pub const fn schema_ref(&self) -> SchemaRef {
+        SchemaRef::new(self.id, self.version)
+    }
+
+    /// 全部键元数据。
+    #[must_use]
+    pub fn specs(&self) -> &[SettingSpec] {
+        &self.specs
+    }
+
+    /// 按键名取元数据。
+    #[must_use]
+    pub fn spec(&self, key: &str) -> Option<&SettingSpec> {
+        self.specs.iter().find(|spec| spec.key == key)
+    }
+
+    /// 是否定义了该键。
+    #[must_use]
+    pub fn is_known(&self, key: &str) -> bool {
+        self.spec(key).is_some()
+    }
+
+    /// 是否是某个已知键的**前缀路径**（用于区分「嵌套对象」与「陌生整棵子树」）。
+    #[must_use]
+    pub fn has_prefix(&self, segments: &[&str]) -> bool {
+        let mut prefix = segments.join(".");
+        prefix.push('.');
+        self.specs.iter().any(|spec| spec.key.starts_with(&prefix))
+    }
+
+    /// 默认值。
+    #[must_use]
+    pub fn default_value(&self, key: &str) -> Option<&Value> {
+        self.spec(key).map(|spec| &spec.default)
+    }
+
+    /// 校验一个键值对。
+    ///
+    /// # Errors
+    /// 未定义的键 → [`SettingError::UnknownKey`]；值不合法 → [`SettingError::InvalidValue`]。
+    pub fn validate(&self, key: &str, value: &Value) -> SettingResult<()> {
+        let spec = self.spec(key).ok_or_else(|| SettingError::UnknownKey {
+            key: key.to_owned(),
+        })?;
+        spec.kind
+            .check(value)
+            .map_err(|reason| SettingError::InvalidValue {
+                key: key.to_owned(),
+                reason,
+            })
+    }
+
+    /// AI 可写键白名单（供 M16 `set_config` 前置检查）。
+    #[must_use]
+    pub fn ai_writable_keys(&self) -> Vec<&'static str> {
+        self.specs
+            .iter()
+            .filter(|spec| spec.ai.writable && !spec.is_deprecated())
+            .map(|spec| spec.key)
+            .collect()
+    }
+
+    /// AI 是否允许写该键（未定义的键 = 不允许）。
+    #[must_use]
+    pub fn accepts_ai_write(&self, key: &str) -> bool {
+        self.spec(key)
+            .is_some_and(|spec| spec.ai.writable && !spec.is_deprecated())
+    }
+
+    /// 已废弃键清单（只读兼容，不再落盘）。
+    #[must_use]
+    pub fn deprecated_keys(&self) -> Vec<&'static str> {
+        self.specs
+            .iter()
+            .filter(|spec| spec.is_deprecated())
+            .map(|spec| spec.key)
+            .collect()
+    }
+
+    /// 某键的替代键（不是废弃键则 `None`）。
+    #[must_use]
+    pub fn replacement_of(&self, key: &str) -> Option<&'static str> {
+        self.spec(key)?.deprecated.map(|info| info.replaced_by)
+    }
+
+    /// 敏感分级。
+    #[must_use]
+    pub fn sensitivity(&self, key: &str) -> Option<Sensitivity> {
+        self.spec(key).map(|spec| spec.ai.sensitivity)
+    }
+
+    /// 顶层键名集合（`download.concurrency` → `download`）。
+    #[must_use]
+    pub fn top_level_keys(&self) -> BTreeSet<&'static str> {
+        self.specs
+            .iter()
+            .filter_map(|spec| spec.key.split('.').next())
+            .collect()
+    }
+
+    /// 生成给 AI 工具用的 JSON Schema（只含 AI 可写键）。
+    #[must_use]
+    pub fn to_json_schema(&self) -> Value {
+        let mut properties = Map::new();
+        for spec in self
+            .specs
+            .iter()
+            .filter(|spec| spec.ai.writable && !spec.is_deprecated())
+        {
+            let mut property = match spec.kind.to_json_schema() {
+                Value::Object(map) => map,
+                other => {
+                    let mut map = Map::new();
+                    map.insert("schema".to_owned(), other);
+                    map
+                }
+            };
+            property.insert("description".to_owned(), Value::from(spec.doc));
+            property.insert(
+                "x-ai-sensitivity".to_owned(),
+                Value::from(spec.ai.sensitivity.as_str()),
+            );
+            if !spec.default.is_null() {
+                property.insert("default".to_owned(), spec.default.clone());
+            }
+            properties.insert(spec.key.to_owned(), Value::Object(property));
+        }
+
+        json!({
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "title": format!("ull.{}", self.id.as_str()),
+            "type": "object",
+            "additionalProperties": false,
+            "properties": properties,
+        })
+    }
+}
diff --git a/crates/core/src/setting/document.rs b/crates/core/src/setting/document.rs
new file mode 100644
index 0000000..f59d050
--- /dev/null
+++ b/crates/core/src/setting/document.rs
@@ -0,0 +1,399 @@
+//! 配置文档模型：嵌套点路径取值、脏字段追踪、未知字段保留、`$schema` 保留。
+//!
+//! 出处：`DevDocs/analyse/07-settings-packaging-update.md` §1.2-§1.3（HMCL `DirtyTracker` +
+//! `unknownFields` + `RawPreservingProperty`）与 `DevDocs/PlanDoc/04-data-and-config.md` §3。
+//!
+//! 三个关键取舍：
+//! 1. **默认值不进文件**——只有「文件里读到的键」和「本次显式设过的键」会出现在落盘视图里，
+//!    因此改默认值不需要写迁移代码；
+//! 2. **未知字段整棵保留**——旧版本打开新版本写的文件不会丢配置；
+//! 3. **坏值原样保留**——单个键解析/校验失败只记 `LoadProblem`，不丢数据、不整文件报废。
+
+use std::collections::BTreeSet;
+use std::fmt;
+
+use serde_json::{Map, Value};
+
+use super::catalog::SettingSchema;
+use super::error::{SettingError, SettingResult};
+use super::json_path::{collect_unknown, flatten, insert_at, lookup, merge_maps, segments};
+use super::schema::{
+    SchemaCompat, SchemaRef, SchemaVersion, SCHEMA_KEY, SCHEMA_URL_PREFIX, SCHEMA_VERSION_KEY,
+};
+
+/// 落盘视图模式。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RenderMode {
+    /// 完整视图：`$schema` + `schemaVersion` + 已读/已设键 + 未知键（保存用，无损）。
+    Full,
+    /// 只含本次脏字段（AI 增量 / IPC 同步 / 审计用）。
+    DirtyOnly,
+}
+
+/// 加载时发现的问题（都不致命，配置照常用）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum LoadProblem {
+    /// 文件里有、schema 不认识的键（整棵子树原样保留）。
+    UnknownKey {
+        /// 点分键；陌生子树按**最上层**节点报一次（不做逐叶展开）。
+        key: String,
+    },
+    /// 已知键但值不合法（原样保留，等用户/AI 修）。
+    InvalidValue {
+        /// 点分键。
+        key: String,
+        /// 原因。
+        reason: String,
+    },
+    /// 已知键的父路径类型不符（如 `download` 本该是对象却是字符串）。
+    InvalidShape {
+        /// 点分键。
+        key: String,
+        /// 原因。
+        reason: String,
+    },
+    /// `schemaVersion` 镜像与 `$schema` 尾部不一致（以 `$schema` 为准）。
+    SchemaVersionMismatch {
+        /// 文件里写的整数。
+        declared: u64,
+        /// `$schema` 推出的 major。
+        expected: u32,
+    },
+    /// 文件用的是已废弃键：值已按映射带到替代键，下次保存只写替代键。
+    DeprecatedKey {
+        /// 已废弃的键。
+        key: String,
+        /// 替代键。
+        replaced_by: &'static str,
+    },
+    /// `$schema` 本身的状态（缺失 / 非法 / 更高版本等）。
+    Schema(SchemaCompat),
+    /// 有 `$schema` 字符串但认不出前缀（M40：值照读、文件按只读，不再静默回落默认值）。
+    UnknownSchema {
+        /// 文件里写的原串。
+        url: String,
+    },
+}
+
+impl fmt::Display for LoadProblem {
+    /// 人读一行（CLI 的 `problems` 通道、日志与设置页共用一份文案）。
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::UnknownKey { key } => write!(f, "{key}：schema 不认识的键（已原样保留）"),
+            Self::InvalidValue { key, reason } => write!(f, "{key}：值不合法（{reason}），已保留"),
+            Self::InvalidShape { key, reason } => write!(f, "{key}：结构不符（{reason}）"),
+            Self::SchemaVersionMismatch { declared, expected } => {
+                write!(
+                    f,
+                    "schemaVersion={declared} 不是 $schema 的 major {expected}"
+                )
+            }
+            Self::DeprecatedKey { key, replaced_by } => write!(f, "{key}：改用 {replaced_by}"),
+            Self::Schema(compat) => write!(f, "$schema 状态：{}", compat.as_str()),
+            Self::UnknownSchema { url } => {
+                write!(f, "$schema 认不出「{url}」，前缀需为 {SCHEMA_URL_PREFIX}")
+            }
+        }
+    }
+}
+
+/// 一份配置文件的内存视图。
+#[derive(Debug, Clone)]
+pub struct SettingDocument {
+    schema: SettingSchema,
+    version: SchemaVersion,
+    values: Map<String, Value>,
+    /// 已废弃键的原始值：只供诊断/UI 提示，**永远不落盘**。
+    legacy: Map<String, Value>,
+    /// 废弃键（点分）清单。
+    legacy_keys: BTreeSet<String>,
+    dirty: BTreeSet<String>,
+    unknown: Map<String, Value>,
+    unknown_keys: BTreeSet<String>,
+    preserve_schema: Option<String>,
+}
+
+impl SettingDocument {
+    /// 空文档（全部走默认值），版本取 schema 版本。
+    #[must_use]
+    pub fn new(schema: SettingSchema) -> Self {
+        let version = schema.version();
+        Self {
+            schema,
+            version,
+            values: Map::new(),
+            legacy: Map::new(),
+            legacy_keys: BTreeSet::new(),
+            dirty: BTreeSet::new(),
+            unknown: Map::new(),
+            unknown_keys: BTreeSet::new(),
+            preserve_schema: None,
+        }
+    }
+
+    /// 从文件内容加载；返回文档与问题清单（永不失败）。
+    #[must_use]
+    pub fn load(schema: &SettingSchema, raw: &Value) -> (Self, Vec<LoadProblem>) {
+        let mut problems = Vec::new();
+        let mut document = Self::new(schema.clone());
+
+        let original_schema = raw
+            .get(SCHEMA_KEY)
+            .and_then(Value::as_str)
+            .map(str::to_owned);
+        let compat = match &original_schema {
+            Some(url) => SchemaCompat::check_url(url, schema.schema_ref()),
+            None => SchemaCompat::Missing,
+        };
+        if compat.preserve_schema() {
+            document.preserve_schema = original_schema.clone();
+        }
+        // 认得 `$schema` 键、但前缀解析不出来：别静默按「没有声明」装默认值。
+        if let (SchemaCompat::Invalid, Some(url)) = (compat, original_schema.clone()) {
+            problems.push(LoadProblem::UnknownSchema { url });
+        }
+        if let Some(parsed) = original_schema.as_deref().and_then(SchemaRef::parse_url) {
+            document.version = parsed.version;
+        }
+        if let Some(declared) = raw.get(SCHEMA_VERSION_KEY).and_then(Value::as_u64) {
+            let expected = document.version.major;
+            if declared != u64::from(expected) {
+                problems.push(LoadProblem::SchemaVersionMismatch { declared, expected });
+            }
+        }
+
+        let Some(object) = raw.as_object() else {
+            if !raw.is_null() {
+                problems.push(LoadProblem::Schema(compat));
+            }
+            return (document, problems);
+        };
+
+        for spec in schema.specs() {
+            let path = segments(spec.key);
+            let Some(value) = lookup(object, &path) else {
+                continue;
+            };
+
+            if let Some(deprecation) = spec.deprecated {
+                // 废弃键：原文进 legacy（不落盘），值按映射带到替代键（新键已在则新键优先）。
+                insert_at(&mut document.legacy, &path, value.clone());
+                problems.push(LoadProblem::DeprecatedKey {
+                    key: spec.key.to_owned(),
+                    replaced_by: deprecation.replaced_by,
+                });
+                let replacement = segments(deprecation.replaced_by);
+                if lookup(object, &replacement).is_none() {
+                    let translated = deprecation.translate(value);
+                    if schema
+                        .validate(deprecation.replaced_by, &translated)
+                        .is_err()
+                    {
+                        problems.push(LoadProblem::InvalidValue {
+                            key: deprecation.replaced_by.to_owned(),
+                            reason: format!("旧键 {} 的值 {value} 无法映射到新键", spec.key),
+                        });
+                    }
+                    insert_at(&mut document.values, &replacement, translated);
+                }
+                continue;
+            }
+
+            if let Err(err) = schema.validate(spec.key, value) {
+                problems.push(LoadProblem::InvalidValue {
+                    key: spec.key.to_owned(),
+                    reason: err.to_string(),
+                });
+            }
+            insert_at(&mut document.values, &path, value.clone());
+        }
+
+        document.legacy_keys = flatten(&document.legacy);
+
+        let unknown = collect_unknown(&[], object, schema, &mut problems);
+        document.unknown_keys = flatten(&unknown);
+        document.unknown = unknown;
+
+        (document, problems)
+    }
+
+    /// 键表。
+    #[must_use]
+    pub const fn schema(&self) -> &SettingSchema {
+        &self.schema
+    }
+
+    /// 文档版本（来自文件 `$schema`；迁移后用 [`Self::set_version`] 推进）。
+    #[must_use]
+    pub const fn version(&self) -> SchemaVersion {
+        self.version
+    }
+
+    /// 设置文档版本（迁移链推进后调用）。
+    pub const fn set_version(&mut self, version: SchemaVersion) {
+        self.version = version;
+    }
+
+    /// 文件里显式出现过的值（不含默认值）。
+    #[must_use]
+    pub fn get(&self, key: &str) -> Option<&Value> {
+        let path = segments(key);
+        lookup(&self.values, &path).or_else(|| lookup(&self.legacy, &path))
+    }
+
+    /// 已废弃键在文件里的原文（仅供诊断/UI 提示；不参与落盘）。
+    #[must_use]
+    pub fn legacy_value(&self, key: &str) -> Option<&Value> {
+        lookup(&self.legacy, &segments(key))
+    }
+
+    /// 废弃键清单（文件里真的出现过的）。
+    pub fn legacy_keys(&self) -> impl Iterator<Item = &str> {
+        self.legacy_keys.iter().map(String::as_str)
+    }
+
+    /// 生效值：文件值 → schema 默认值（默认值为 `null` 视为未设置）。
+    #[must_use]
+    pub fn effective(&self, key: &str) -> Option<&Value> {
+        self.get(key)
+            .or_else(|| self.schema.default_value(key))
+            .filter(|value| !value.is_null())
+    }
+
+    /// 生效布尔值。
+    #[must_use]
+    pub fn effective_bool(&self, key: &str) -> Option<bool> {
+        self.effective(key).and_then(Value::as_bool)
+    }
+
+    /// 生效整数。
+    #[must_use]
+    pub fn effective_i64(&self, key: &str) -> Option<i64> {
+        self.effective(key).and_then(Value::as_i64)
+    }
+
+    /// 生效浮点。
+    #[must_use]
+    pub fn effective_f64(&self, key: &str) -> Option<f64> {
+        self.effective(key).and_then(Value::as_f64)
+    }
+
+    /// 生效文本。
+    #[must_use]
+    pub fn effective_str(&self, key: &str) -> Option<&str> {
+        self.effective(key).and_then(Value::as_str)
+    }
+
+    /// 写一个键（走 schema 校验，并标脏）。
+    ///
+    /// # Errors
+    /// 未定义的键或值不合法时返回 [`SettingError`]。
+    pub fn set(&mut self, key: &str, value: Value) -> SettingResult<()> {
+        if let Some(replaced_by) = self.schema.replacement_of(key) {
+            return Err(SettingError::DeprecatedKey {
+                key: key.to_owned(),
+                replaced_by,
+            });
+        }
+        self.schema.validate(key, &value)?;
+        insert_at(&mut self.values, &segments(key), value);
+        self.dirty.insert(key.to_owned());
+        Ok(())
+    }
+
+    /// 是否有未落盘的改动。
+    #[must_use]
+    pub fn is_dirty(&self) -> bool {
+        !self.dirty.is_empty()
+    }
+
+    /// 脏键清单。
+    pub fn dirty_keys(&self) -> impl Iterator<Item = &str> {
+        self.dirty.iter().map(String::as_str)
+    }
+
+    /// 把当前所有已读/已设键全部标脏（迁移后强制回写用）。
+    ///
+    /// 废弃键跳过：它们只做读兼容、不落盘，不需要回写。
+    pub fn mark_all_dirty(&mut self) {
+        for spec in self.schema.specs() {
+            if spec.is_deprecated() {
+                continue;
+            }
+            if self.get(spec.key).is_some() {
+                self.dirty.insert(spec.key.to_owned());
+            }
+        }
+    }
+
+    /// 清脏（保存成功后调用）。
+    pub fn mark_clean(&mut self) {
+        self.dirty.clear();
+    }
+
+    /// 未知键（点分）清单。
+    pub fn unknown_keys(&self) -> impl Iterator<Item = &str> {
+        self.unknown_keys.iter().map(String::as_str)
+    }
+
+    /// 文件里原有的 `$schema`（仅 `preserve_schema` 状态下有值）。
+    #[must_use]
+    pub fn preserve_schema(&self) -> Option<&str> {
+        self.preserve_schema.as_deref()
+    }
+
+    /// 显式指定保存时沿用的 `$schema` 字符串。
+    pub fn set_preserve_schema(&mut self, url: Option<String>) {
+        self.preserve_schema = url;
+    }
+
+    /// 落盘视图。
+    #[must_use]
+    pub fn render(&self, mode: RenderMode) -> Value {
+        let mut root = Map::new();
+        root.insert(SCHEMA_KEY.to_owned(), Value::String(self.schema_url()));
+        root.insert(
+            SCHEMA_VERSION_KEY.to_owned(),
+            Value::from(self.version.major),
+        );
+        match mode {
+            RenderMode::Full => {
+                merge_maps(&mut root, &self.values);
+                merge_maps(&mut root, &self.unknown);
+            }
+            RenderMode::DirtyOnly => {
+                let patch = self.dirty_patch_map();
+                merge_maps(&mut root, &patch);
+            }
+        }
+        Value::Object(root)
+    }
+
+    /// 完整落盘视图（等价 `render(RenderMode::Full)`）。
+    #[must_use]
+    pub fn to_value(&self) -> Value {
+        self.render(RenderMode::Full)
+    }
+
+    /// 只含脏字段的嵌套对象。
+    #[must_use]
+    pub fn dirty_patch(&self) -> Value {
+        Value::Object(self.dirty_patch_map())
+    }
+
+    fn dirty_patch_map(&self) -> Map<String, Value> {
+        let mut patch = Map::new();
+        for key in &self.dirty {
+            if let Some(value) = lookup(&self.values, &segments(key)) {
+                insert_at(&mut patch, &segments(key), value.clone());
+            }
+        }
+        patch
+    }
+
+    fn schema_url(&self) -> String {
+        self.preserve_schema
+            .clone()
+            .unwrap_or_else(|| self.schema.schema_ref().url())
+    }
+}
diff --git a/crates/core/src/setting/error.rs b/crates/core/src/setting/error.rs
new file mode 100644
index 0000000..186a29b
--- /dev/null
+++ b/crates/core/src/setting/error.rs
@@ -0,0 +1,121 @@
+//! setting 层错误类型与结果别名。
+
+use std::fmt;
+use std::io;
+use std::path::PathBuf;
+
+use crate::platform::error::PlatformError;
+
+use super::schema::{SchemaCompat, SchemaVersion};
+
+/// setting 层的结果别名。
+pub type SettingResult<T> = Result<T, SettingError>;
+
+/// 配置读写与迁移可能出的问题。
+#[derive(Debug)]
+pub enum SettingError {
+    /// 文件系统操作失败。
+    Io {
+        /// 出错路径。
+        path: PathBuf,
+        /// 底层错误。
+        source: io::Error,
+    },
+    /// JSON 解析/序列化失败。
+    Json {
+        /// 出错路径。
+        path: PathBuf,
+        /// 底层错误。
+        source: serde_json::Error,
+    },
+    /// 文件是只读档（`READ_ONLY`），拒绝保存。
+    ReadOnly {
+        /// 文件路径。
+        path: PathBuf,
+    },
+    /// 文件不可读档（`UNREADABLE`），全程不写。
+    Unreadable {
+        /// 文件路径。
+        path: PathBuf,
+        /// 判定依据。
+        compat: SchemaCompat,
+    },
+    /// schema 里没有这个键（AI 白名单外的键也走这里）。
+    UnknownKey {
+        /// 键。
+        key: String,
+    },
+    /// 值不合法（类型/范围/枚举）。
+    InvalidValue {
+        /// 键。
+        key: String,
+        /// 原因。
+        reason: String,
+    },
+    /// 键已废弃，写必须走替代键。
+    DeprecatedKey {
+        /// 用户/调用方给的旧键。
+        key: String,
+        /// 替代键。
+        replaced_by: &'static str,
+    },
+    /// 迁移链断链/缺环/顺序错。
+    ChainBroken {
+        /// 原因。
+        reason: String,
+    },
+    /// 单步迁移失败。
+    Migration {
+        /// 起始版本。
+        from: SchemaVersion,
+        /// 目标版本。
+        to: SchemaVersion,
+        /// 原因。
+        reason: String,
+    },
+    /// platform 层错误透传。
+    Platform(PlatformError),
+}
+
+impl fmt::Display for SettingError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Io { path, source } => write!(f, "IO 失败 @ {}: {source}", path.display()),
+            Self::Json { path, source } => write!(f, "JSON 失败 @ {}: {source}", path.display()),
+            Self::ReadOnly { path } => write!(f, "文件只读，拒绝保存: {}", path.display()),
+            Self::Unreadable { path, compat } => write!(
+                f,
+                "文件不可读（{}），全程不写: {}",
+                compat.as_str(),
+                path.display()
+            ),
+            Self::UnknownKey { key } => write!(f, "schema 未定义该键: {key}"),
+            Self::InvalidValue { key, reason } => write!(f, "值不合法 [{key}]: {reason}"),
+            Self::DeprecatedKey { key, replaced_by } => {
+                write!(f, "键 {key} 已废弃，请改用 {replaced_by}")
+            }
+            Self::ChainBroken { reason } => write!(f, "迁移链不完整: {reason}"),
+            Self::Migration { from, to, reason } => {
+                write!(f, "迁移 {from} → {to} 失败: {reason}")
+            }
+            Self::Platform(err) => write!(f, "{err}"),
+        }
+    }
+}
+
+impl std::error::Error for SettingError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            Self::Io { source, .. } => Some(source),
+            Self::Json { source, .. } => Some(source),
+            Self::Platform(err) => Some(err),
+            _ => None,
+        }
+    }
+}
+
+impl From<PlatformError> for SettingError {
+    fn from(err: PlatformError) -> Self {
+        Self::Platform(err)
+    }
+}
diff --git a/crates/core/src/setting/instance_keys.rs b/crates/core/src/setting/instance_keys.rs
new file mode 100644
index 0000000..aaa7948
--- /dev/null
+++ b/crates/core/src/setting/instance_keys.rs
@@ -0,0 +1,155 @@
+//! `config/profiles.json` 与 `config/instances/<id>.json` 的键表。
+//!
+//! 实例模型预告见 `DevDocs/PlanDoc/04-data-and-config.md` §4：
+//! 每实例 = 一个 `.minecraft` 目录绑定 + 独立设置覆盖链（全局 → 实例 → 临时启动参数），
+//! 实例 id 用稳定 UUID（不用路径——路径会变）。
+//!
+//! # 实例文件的形状（D20 定案，research/04 §5.1）
+//!
+//! 实例文件是**稀疏 camelCase 扁平结构**，与 `game::install::instance::InstanceConfig`
+//! 的 serde 形状逐键一致（那份结构才是写入者，本文件是它的 schema 白名单视图）：
+//!
+//! ```jsonc
+//! {
+//!   "schemaVersion": 1,
+//!   "id": "<uuid>",
+//!   "versionId": "1.20.1",
+//!   "isolation": "custom",          // 缺键 = inherit（跟随全局，不落盘）
+//!   "gameDir": "D:/mcs/farm",       // 仅 custom 时有值
+//!   "overrides": ["maxMemory"],
+//!   "lastModeChange": { "at": "2026-10-30T12:00:00Z", "from": "shared", "to": "isolated",
+//!                       "probe": { "isolatedSide": 0, "sharedSide": 12 }, "warned": true }
+//! }
+//! ```
+//!
+//! 三条不变量：
+//! 1. `isolation` 默认 `inherit` 且**不落盘**——改全局模式对存量实例立即生效
+//!    （`document` 的「默认值不进文件」保证这一点，直接避开 PCL2 的默认值固化缺陷）；
+//!    显式写 `"isolation": "inherit"` 也合法：`InstanceConfig` 的反序列化把它归一成
+//!    「键不存在」（等价语义，不会出现两层读写回环不一致）；
+//! 2. `isolation`/`lastModeChange` 由用户（前者）与启动器（后者）维护，**AI 不可写**；
+//! 3. 派生的绝对路径不入档：`isolated` 只是「运行目录 = `versions/<versionId>`」的语法糖，
+//!    派生实现归 `game::isolation`。
+
+use super::catalog::SettingSchema;
+use super::schema::{SchemaId, SchemaVersion};
+use super::spec::{AiPolicy, SettingSpec};
+
+/// 实例级 `isolation` 允许值（`inherit` = 键缺失，跟随全局 `instances.mode`）。
+pub const ISOLATION_OVERRIDES: &[&str] = &["inherit", "isolated", "shared", "custom"];
+/// 切换检测记录里 `from`/`to` 的允许值（`inherit` 不是生效档位，故不在表里）。
+pub const ISOLATION_RESOLVED: &[&str] = &["isolated", "shared", "custom"];
+/// 实例可覆盖的设置键（enum 白名单，拼错即校验失败而不是静默不生效）。
+pub const OVERRIDE_KEYS: &[&str] = &["maxMemory", "javaType", "runningDirectory"];
+
+/// profiles.json 当前 schema 版本。
+#[must_use]
+pub fn profiles_version() -> SchemaVersion {
+    SchemaVersion::new(1, 0, 0)
+}
+
+/// instances/<id>.json 当前 schema 版本。
+///
+/// `1.1.0` 登记 D20 的 `isolation` 档位（`inherit`/`isolated`/`shared`/`custom`）与
+/// `lastModeChange` 切换检测键；老文件缺键即默认值，不需要迁移步骤（major 未变）。
+#[must_use]
+pub fn instance_version() -> SchemaVersion {
+    SchemaVersion::new(1, 1, 0)
+}
+
+/// `config/profiles.json` 的 schema。
+#[must_use]
+pub fn profiles_schema() -> SettingSchema {
+    SettingSchema::new(SchemaId::PROFILES, profiles_version())
+        .with(SettingSpec::text(
+            "selected_profile_id",
+            "",
+            64,
+            AiPolicy::audited(),
+            "上次选中的实例 id",
+        ))
+        .with(SettingSpec::any(
+            "profiles",
+            AiPolicy::locked(),
+            "实例档案列表（数据而非配置，由 game 模块维护；AI 不得整体改写）",
+        ))
+}
+
+/// `config/instances/<id>.json` 的 schema。
+#[must_use]
+pub fn instance_schema() -> SettingSchema {
+    SettingSchema::new(SchemaId::INSTANCE, instance_version())
+        .with(SettingSpec::text(
+            "id",
+            "",
+            64,
+            AiPolicy::locked(),
+            "实例稳定 id（UUID，与文件名一致；不允许改写身份）",
+        ))
+        .with(SettingSpec::text(
+            "versionId",
+            "",
+            128,
+            AiPolicy::audited(),
+            "绑定的版本 id（versions/<id>）",
+        ))
+        .with(SettingSpec::enumeration(
+            "isolation",
+            "inherit",
+            ISOLATION_OVERRIDES,
+            AiPolicy::sensitive(),
+            "实例隔离档位：inherit（跟随全局 instances.mode，不落盘）/ isolated（运行目录派生 versions/<versionId>）/ shared（共用 .minecraft 根）/ custom（用 gameDir）",
+        ))
+        .with(SettingSpec::path(
+            "gameDir",
+            AiPolicy::sensitive(),
+            "自定义运行目录（仅 isolation=custom 生效）",
+        ))
+        .with(SettingSpec::enum_list(
+            "overrides",
+            OVERRIDE_KEYS,
+            AiPolicy::locked(),
+            "该实例覆盖了全局哪些设置键（enum 白名单，拼错即校验失败）",
+        ))
+        .with(SettingSpec::text(
+            "lastModeChange.at",
+            "",
+            40,
+            AiPolicy::locked(),
+            "上次切换隔离档位的时间（RFC-3339，启动器写入）",
+        ))
+        .with(SettingSpec::enumeration(
+            "lastModeChange.from",
+            "isolated",
+            ISOLATION_RESOLVED,
+            AiPolicy::locked(),
+            "切换前的生效档位（启动器写入）",
+        ))
+        .with(SettingSpec::enumeration(
+            "lastModeChange.to",
+            "isolated",
+            ISOLATION_RESOLVED,
+            AiPolicy::locked(),
+            "切换后的生效档位（启动器写入）",
+        ))
+        .with(SettingSpec::int(
+            "lastModeChange.probe.isolatedSide",
+            0,
+            (0, 1_000_000_000),
+            AiPolicy::locked(),
+            "切换时隔离侧（versions/<versionId>）的内容条目数（只探测，不迁移）",
+        ))
+        .with(SettingSpec::int(
+            "lastModeChange.probe.sharedSide",
+            0,
+            (0, 1_000_000_000),
+            AiPolicy::locked(),
+            "切换时共享侧（.minecraft 根）的内容条目数（只探测，不迁移）",
+        ))
+        .with(SettingSpec::bool(
+            "lastModeChange.warned",
+            false,
+            AiPolicy::locked(),
+            "该次切换的提示是否已展示过（保证切换后首次启动只提示一次）",
+        ))
+}
diff --git a/crates/core/src/setting/json_path.rs b/crates/core/src/setting/json_path.rs
new file mode 100644
index 0000000..3cfaf93
--- /dev/null
+++ b/crates/core/src/setting/json_path.rs
@@ -0,0 +1,124 @@
+//! 点分键（`download.concurrency`）与嵌套 JSON 之间的最小工具集。
+//!
+//! 单独成文件：这些函数是 [`super::document`] 的机械部件，和「配置语义」无关，
+//! 也是容易出边界 bug（空路径、中间层不是对象）的地方。
+
+use std::collections::BTreeSet;
+
+use serde_json::{Map, Value};
+
+use super::catalog::SettingSchema;
+use super::document::LoadProblem;
+use super::schema::{SCHEMA_KEY, SCHEMA_VERSION_KEY};
+
+/// 点分键 → 路径段。
+pub(crate) fn segments(key: &str) -> Vec<&str> {
+    key.split('.').filter(|part| !part.is_empty()).collect()
+}
+
+/// 沿路径取嵌套值。
+pub(crate) fn lookup<'a>(root: &'a Map<String, Value>, path: &[&str]) -> Option<&'a Value> {
+    let (head, tail) = path.split_first()?;
+    let value = root.get(*head)?;
+    if tail.is_empty() {
+        Some(value)
+    } else {
+        lookup(value.as_object()?, tail)
+    }
+}
+
+/// 沿路径写嵌套值（中间层不是对象则重建）。
+pub(crate) fn insert_at(root: &mut Map<String, Value>, path: &[&str], value: Value) {
+    let Some((head, tail)) = path.split_first() else {
+        return;
+    };
+    if tail.is_empty() {
+        root.insert((*head).to_owned(), value);
+        return;
+    }
+    let entry = root
+        .entry((*head).to_owned())
+        .or_insert_with(|| Value::Object(Map::new()));
+    if !entry.is_object() {
+        *entry = Value::Object(Map::new());
+    }
+    if let Some(child) = entry.as_object_mut() {
+        insert_at(child, tail, value);
+    }
+}
+
+/// 深合并（`extra` 覆盖 `target` 的同名叶子）。
+pub(crate) fn merge_maps(target: &mut Map<String, Value>, extra: &Map<String, Value>) {
+    for (key, value) in extra {
+        if let Some(Value::Object(existing)) = target.get_mut(key) {
+            if let Some(incoming) = value.as_object() {
+                merge_maps(existing, incoming);
+                continue;
+            }
+        }
+        target.insert(key.clone(), value.clone());
+    }
+}
+
+/// 收集 schema 不认识的键（整棵保留），并把形状问题记进 `problems`。
+pub(crate) fn collect_unknown(
+    prefix: &[&str],
+    node: &Map<String, Value>,
+    schema: &SettingSchema,
+    problems: &mut Vec<LoadProblem>,
+) -> Map<String, Value> {
+    let mut out = Map::new();
+    for (key, value) in node {
+        if prefix.is_empty() && (key == SCHEMA_KEY || key == SCHEMA_VERSION_KEY) {
+            continue;
+        }
+        let mut path = prefix.to_vec();
+        path.push(key.as_str());
+        let dotted = path.join(".");
+        if schema.is_known(&dotted) {
+            continue;
+        }
+        if schema.has_prefix(&path) {
+            match value.as_object() {
+                Some(child) => {
+                    let nested = collect_unknown(&path, child, schema, problems);
+                    if !nested.is_empty() {
+                        out.insert(key.clone(), Value::Object(nested));
+                    }
+                }
+                None => problems.push(LoadProblem::InvalidShape {
+                    key: path.join("."),
+                    reason: "期望对象（其下还有已知键）".to_owned(),
+                }),
+            }
+            continue;
+        }
+        problems.push(LoadProblem::UnknownKey {
+            key: path.join("."),
+        });
+        out.insert(key.clone(), value.clone());
+    }
+    out
+}
+
+/// 把嵌套对象摊平成点分叶子集合。
+pub(crate) fn flatten(map: &Map<String, Value>) -> BTreeSet<String> {
+    fn walk(prefix: &str, node: &Map<String, Value>, out: &mut BTreeSet<String>) {
+        for (key, value) in node {
+            let dotted = if prefix.is_empty() {
+                key.clone()
+            } else {
+                format!("{prefix}.{key}")
+            };
+            match value.as_object() {
+                Some(child) if !child.is_empty() => walk(&dotted, child, out),
+                _ => {
+                    out.insert(dotted);
+                }
+            }
+        }
+    }
+    let mut out = BTreeSet::new();
+    walk("", map, &mut out);
+    out
+}
diff --git a/crates/core/src/setting/keys.rs b/crates/core/src/setting/keys.rs
new file mode 100644
index 0000000..5e31902
--- /dev/null
+++ b/crates/core/src/setting/keys.rs
@@ -0,0 +1,398 @@
+//! `config/launcher.json` 的键表（全局设置）。
+//!
+//! 键名与默认值对齐 `DevDocs/PlanDoc/04-data-and-config.md` §2-§3 与 `05/06/07/08` 各专题；
+//! AI 可写 + 敏感分级按 `02-ai-agent-design.md` §3.1 的边界落：**密钥类一律 locked**。
+
+use super::catalog::SettingSchema;
+use super::schema::{SchemaId, SchemaVersion};
+use super::spec::{AiPolicy, SettingSpec};
+
+/// `core.data_mode` 允许值。
+pub const DATA_MODES: &[&str] = &["portable", "standard", "custom"];
+/// `download.region` 允许值。
+pub const REGIONS: &[&str] = &["auto", "cn", "global"];
+/// `download.mirror_preference` 允许值。
+pub const MIRROR_PREFERENCES: &[&str] = &["auto", "official", "mirror"];
+/// `download.proxy_mode` 允许值。
+pub const PROXY_MODES: &[&str] = &["none", "system", "manual"];
+/// `ai.provider` 允许值。
+pub const AI_PROVIDERS: &[&str] = &["openai_compatible", "anthropic", "ollama", "disabled"];
+/// `ui.language` 允许值。
+pub const LANGUAGES: &[&str] = &["zh_cn", "en_us"];
+/// `appearance.theme_mode` 允许值（D17 定案：auto/light/dark）。
+pub const THEME_MODES: &[&str] = &["auto", "light", "dark"];
+/// `ui.theme` 的旧允许值（该键已废弃，仅读兼容，不再落盘）。
+pub const LEGACY_THEMES: &[&str] = &["system", "metro_light", "metro_dark"];
+/// 旧 `ui.theme` 值 → 新 `appearance.theme_mode` 值（tower 键冲突裁决的读兼容映射）。
+pub const THEME_ALIASES: &[(&str, &str)] = &[
+    ("system", "auto"),
+    ("metro_light", "light"),
+    ("metro_dark", "dark"),
+];
+/// `log.level` 允许值。
+pub const LOG_LEVELS: &[&str] = &["error", "warn", "info", "debug", "trace"];
+/// `instances.mode` 允许值（D20 定案：默认隔离，用户可手动切共享）。
+pub const INSTANCE_MODES: &[&str] = &["isolated", "shared"];
+/// `java.installRoot` 未设置时的哨兵（空串 = 按数据目录模式派生落点）。
+pub const JAVA_INSTALL_ROOT_UNSET: &str = "";
+/// `java.vendorPriority` 的允许值（D23：四家发行版，顺序即优先级）。
+///
+/// 与 `crate::game::java::vendor::VENDOR_IDS` 必须是同一份集合——setting 层不依赖 game 层
+/// （分层纪律），一致性由 `tests/setting/java_install_keys.rs` 的契约测试固定。
+pub const JDK_VENDORS: &[&str] = &["temurin", "oracle", "microsoft", "zulu"];
+
+/// launcher.json 当前 schema 版本。
+///
+/// `1.1.0` 登记 D20 实例隔离键（`instances.mode` 等）。
+/// `1.2.0` 登记 D23 的 JDK 落点与发行版优先级键（`java.installRoot` / `java.vendorPriority`）：
+/// 同样只推 minor、不强制迁移——[`super::document`] 的「默认值不落盘」让老文件缺键即取默认，
+/// 迁移链（按 major 走）不需要新步骤；`1.1.0 → 1.2.0` 的差异只体现在文件里出现新键之后。
+/// `1.3.0` 登记 D17 的「外观（高级）」P1 键（`appearance.bg_image*` / `panel_alpha` / `glass` /
+/// `accent_color`）：同一套纯增量语义——出厂全默认（高级特性全关）即等于老文件缺键。
+/// `1.4.0` 登记 P4 的外观下层三键（`appearance.window_opacity` / `titlebar_mode` /
+/// `palette_source`，M91 · D36/D37/D38）：仍然只推 minor、不加迁移步骤——三者的出厂值
+/// （不透明 / auto / 内置色卡）正是「老文件没有这些键」时的等价物。
+/// `1.5.0` 登记 M116 的窗口圆角策略（`appearance.window_corner`，出厂 `system`）：
+/// 同一套纯增量语义——**新读旧**：老文件缺该键 ⇒ 读默认 `system` ⇒ 跟随系统，与写进文件后行为一致。
+///
+/// **旧读新（方向相反，措辞必须精确）**：1.4.0 的客户端读 1.5.0 的文件时，
+/// [`super::schema::SchemaCompat::check_url`] 走 `found.minor > expected.minor` →
+/// `ReadOnlyPreserveSchema` → [`super::schema::SchemaCompat::access`] → `FileAccess::ReadOnly`。
+/// 也就是说**整份配置对它只读**（值照读、`store.set` 一律 `SettingError::ReadOnly`、
+/// `save` 跳过），不是「只是少一档」。这是 minor 提升的既定代价——也正是这条键必须推 minor
+/// 而不是偷偷塞进 1.4.0 的原因：回退到旧版本会出现「设置改不动」，而原因只在
+/// `$schema` 那一行里，不看版本号无从排查。
+#[must_use]
+pub fn launcher_version() -> SchemaVersion {
+    SchemaVersion::new(1, 5, 0)
+}
+
+/// `config/launcher.json` 的 schema。
+#[must_use]
+pub fn launcher_schema() -> SettingSchema {
+    SettingSchema::new(SchemaId::LAUNCHER, launcher_version())
+        .with(SettingSpec::enumeration(
+            "core.data_mode",
+            "portable",
+            DATA_MODES,
+            AiPolicy::sensitive(),
+            "数据目录模式：portable（exe 旁）/ standard（系统标准目录）/ custom（自定义）",
+        ))
+        .with(SettingSpec::path(
+            "core.data_custom_root",
+            AiPolicy::sensitive(),
+            "custom 模式的根目录（必须是绝对路径）",
+        ))
+        .with(SettingSpec::path(
+            "core.launcher_home",
+            AiPolicy::sensitive(),
+            "显式覆盖启动器数据目录（.ULL 的等价物）",
+        ))
+        .with(SettingSpec::path(
+            "core.game_home",
+            AiPolicy::sensitive(),
+            "游戏目录（.minecraft），与数据目录分离指定",
+        ))
+        // D20（research/04 §5.1）：只留一个全局默认档，实例级 override 在
+        // `instance_keys::instance_schema`（`isolation`），派生逻辑在 `game::isolation`。
+        .with(SettingSpec::enumeration(
+            "instances.mode",
+            "isolated",
+            INSTANCE_MODES,
+            AiPolicy::sensitive(),
+            "实例默认隔离模式：isolated（运行目录派生 versions/<版本 id>，D20 默认）/ shared（所有实例共用 .minecraft 根）",
+        ))
+        .with(SettingSpec::int(
+            "download.concurrency",
+            8,
+            (1, 256),
+            AiPolicy::silent(),
+            "下载并发数",
+        ))
+        .with(SettingSpec::int(
+            "download.retry_limit",
+            3,
+            (0, 10),
+            AiPolicy::silent(),
+            "单个文件重试次数",
+        ))
+        .with(SettingSpec::enumeration(
+            "download.region",
+            "auto",
+            REGIONS,
+            AiPolicy::audited(),
+            "下载地区判定：auto（时区+语言+探测）/ cn / global",
+        ))
+        .with(SettingSpec::enumeration(
+            "download.mirror_preference",
+            "auto",
+            MIRROR_PREFERENCES,
+            AiPolicy::audited(),
+            "镜像偏好：auto（健康度评分）/ official（官方源优先）/ mirror（镜像优先）",
+        ))
+        .with(SettingSpec::enumeration(
+            "download.proxy_mode",
+            "none",
+            PROXY_MODES,
+            AiPolicy::sensitive(),
+            "代理模式：none / system / manual",
+        ))
+        .with(SettingSpec::text(
+            "download.proxy_url",
+            "",
+            512,
+            AiPolicy::sensitive(),
+            "manual 代理地址（如 http://127.0.0.1:7890）",
+        ))
+        .with(SettingSpec::path(
+            "java.selected_path",
+            AiPolicy::sensitive(),
+            "用户选定的 Java 可执行文件路径",
+        ))
+        .with(SettingSpec::bool(
+            "java.auto_install",
+            true,
+            AiPolicy::audited(),
+            "缺 Java 时自动下载（D13 基准 JDK17）",
+        ))
+        // D23：托管 JDK 的落点三模式。语义在 `game::java::location`：
+        // 未设置（空串）→ 按 `core.data_mode` 派生（Portable 数据根 / Standard 系统目录）；
+        // 设置了 → 覆盖前两者，按 `<vendor>/<version>` 分层。
+        .with(SettingSpec::text(
+            "java.installRoot",
+            JAVA_INSTALL_ROOT_UNSET,
+            512,
+            AiPolicy::sensitive(),
+            "托管 JDK 的自定义安装根（留空 = 按数据目录模式：portable 进数据根、standard 进 %APPDATA%\\Java）；设置后覆盖两者，JDK 落在 <root>/<发行方>/<版本>/",
+        ))
+        // D23：发行版回退链的用户优先级。空数组 = 按地区默认序
+        // （国内 Temurin→Oracle→Microsoft→Zulu；国外 Temurin→Microsoft→Oracle→Zulu）。
+        .with(SettingSpec::enum_list(
+            "java.vendorPriority",
+            JDK_VENDORS,
+            AiPolicy::audited(),
+            "JDK 发行版优先级（temurin/oracle/microsoft/zulu）；留空按地区默认序，只写几家则其余按默认序补齐",
+        ))
+        .with(SettingSpec::int(
+            "java.default_memory_mb",
+            2048,
+            (512, 65536),
+            AiPolicy::silent(),
+            "默认分配给游戏的最大堆内存（MB）",
+        ))
+        .with(SettingSpec::text(
+            "java.extra_args",
+            "",
+            1024,
+            AiPolicy::sensitive(),
+            "附加 JVM 参数（原样拼到命令行）",
+        ))
+        .with(SettingSpec::bool(
+            "ai.enabled",
+            true,
+            AiPolicy::silent(),
+            "启用内置 AI agent（关闭后规则引擎诊断仍可用）",
+        ))
+        .with(SettingSpec::enumeration(
+            "ai.provider",
+            "openai_compatible",
+            AI_PROVIDERS,
+            AiPolicy::sensitive(),
+            "LLM 提供方：openai_compatible（含本地 llama.cpp/DeepSeek/Qwen）/ anthropic / ollama / disabled",
+        ))
+        .with(SettingSpec::text(
+            "ai.base_url",
+            "",
+            512,
+            AiPolicy::sensitive(),
+            "LLM 端点 base_url（OpenAI 兼容形态）",
+        ))
+        .with(SettingSpec::text(
+            "ai.model",
+            "",
+            128,
+            AiPolicy::audited(),
+            "模型名（如 gpt-4o-mini / deepseek-chat）",
+        ))
+        .with(SettingSpec::bool(
+            "ai.yolo",
+            false,
+            AiPolicy::sensitive(),
+            "自动批准全部工具调用（审计照记，白名单不变）",
+        ))
+        .with(SettingSpec::new(
+            "ai.api_key",
+            super::spec::ValueKind::Text { max_len: 4096 },
+            serde_json::Value::Null,
+            AiPolicy::locked(),
+            "LLM API 密钥——AI 永不读写的凭据（D9）",
+        ))
+        // M39（P3 MCP server，02 §0「传输定论」）：对外 agent 工具服务。
+        // 三个开关默认「关 / 只读」——外部客户端拿到的是与内置客户端**同一注册表**的工具，
+        // 但写权限必须用户显式打开（02 §1「同一注册表、同一安全策略、同一审计日志」）。
+        .with(SettingSpec::bool(
+            "agent.mcp.enabled",
+            false,
+            AiPolicy::sensitive(),
+            "对外 MCP server 总开关（127.0.0.1 上的 Streamable HTTP；stdio 形态按需显式启动）",
+        ))
+        .with(SettingSpec::int(
+            "agent.mcp.port",
+            47823,
+            (1024, 65535),
+            AiPolicy::sensitive(),
+            "MCP server 的 Streamable HTTP 端口（只绑 127.0.0.1）",
+        ))
+        .with(SettingSpec::bool(
+            "agent.mcp.allow_write",
+            false,
+            AiPolicy::sensitive(),
+            "允许外部 MCP 客户端调用写工具（默认只读；敏感键仍受分级确认与 YOLO 规则约束）",
+        ))
+        .with(SettingSpec::text(
+            "agent.mcp.token",
+            "",
+            256,
+            AiPolicy::locked(),
+            "MCP server 本地访问令牌（Authorization: Bearer；空 = 不校验，仅绑 127.0.0.1）",
+        ))
+        .with(SettingSpec::enumeration(
+            "ui.language",
+            "zh_cn",
+            LANGUAGES,
+            AiPolicy::audited(),
+            "界面语言",
+        ))
+        .with(SettingSpec::enumeration(
+            "appearance.theme_mode",
+            "auto",
+            THEME_MODES,
+            AiPolicy::silent(),
+            "主题模式：auto（跟随系统）/ light（Metro 浅色）/ dark（Metro 深色）",
+        ))
+        // D17「外观（高级）」P1 四件（09 §101-104 / §111）：**默认全部关闭**（出厂 Metro 纯色）。
+        // 分级一律 audited（Medium）：全部是纯视觉、可一键复原的键，没有安全面（不碰凭据/网络/
+        // 数据根），谈不上 High 级确认；但 AI 改过什么要留审计痕迹，故不用 silent。
+        .with(SettingSpec::bool(
+            "appearance.bg_image_enabled",
+            false,
+            AiPolicy::audited(),
+            "自定义窗口背景图开关（默认关；开启时设置页给出对比度提示）",
+        ))
+        .with(SettingSpec::text(
+            "appearance.bg_image",
+            "",
+            512,
+            AiPolicy::audited(),
+            "背景图路径（PNG；空 = 未设置。Slint 默认解码器只带 PNG）",
+        ))
+        .with(SettingSpec::enumeration(
+            "appearance.bg_fill",
+            "cover",
+            super::appearance::BG_FILLS,
+            AiPolicy::audited(),
+            "背景图填充模式：cover（铺满裁切）/ contain（完整留底色）/ tile（平铺）",
+        ))
+        .with(SettingSpec::float(
+            "appearance.bg_dim",
+            0.35,
+            (
+                super::appearance::BG_DIM_MIN,
+                super::appearance::BG_DIM_MAX,
+            ),
+            AiPolicy::audited(),
+            "背景图叠加暗化层强度（越大前景越清晰；09 §101 的对比度保底手法）",
+        ))
+        .with(SettingSpec::float(
+            "appearance.panel_alpha",
+            1.0,
+            (super::appearance::PANEL_ALPHA_MIN, 1.0),
+            AiPolicy::audited(),
+            "全局面板半透明度（卡片/导航/AI 栏统一透明度；1.0 = 出厂不透明）",
+        ))
+        .with(SettingSpec::bool(
+            "appearance.glass",
+            false,
+            AiPolicy::audited(),
+            "玻璃拟态卡片（背景图预生成模糊层作卡片底；Slint 无 backdrop-filter 的替代）",
+        ))
+        .with(SettingSpec::text(
+            "appearance.accent_color",
+            "",
+            9,
+            AiPolicy::audited(),
+            "自定义强调色 #RRGGBB（空 = 出厂 #0078D4；accent 令牌全域生效）",
+        ))
+        // M91（P4 / D36·D37·D38）：「外观下层」三键——只登记取值与范围，判定与落地都在 UI 侧。
+        // 分级同 D17 那批（audited/Medium）：纯视觉、可一键复原，但要留审计痕迹。
+        .with(SettingSpec::float(
+            "appearance.window_opacity",
+            1.0,
+            (super::appearance::WINDOW_ALPHA_MIN, 1.0),
+            AiPolicy::audited(),
+            "整窗透明度 0.08~1.0（1.0 = 完全不透明；下限 0.08 是为了不把窗口写到穿透，D36）",
+        ))
+        .with(SettingSpec::enumeration(
+            "appearance.titlebar_mode",
+            "auto",
+            super::appearance::TITLEBAR_MODES,
+            AiPolicy::audited(),
+            "标题栏三态：auto（按合成器判定）/ always（总是自绘）/ never（合成器已装饰），默认 auto（D37）",
+        ))
+        .with(SettingSpec::enumeration(
+            "appearance.palette_source",
+            "preset",
+            super::appearance::PALETTE_SOURCES,
+            AiPolicy::audited(),
+            "配色来源档（D38 三级）：background-image（背景图取色）/ wallpaper（桌面壁纸取色）/ preset（内置色卡，默认）",
+        ))
+        // M116：窗口外框圆角策略。只有两档（system / square）——系统不暴露圆角半径，
+        // 「固定 8/12/16」只能是自绘圆角，而自绘圆角在无边框 + 整窗 α 上要裁内容层，
+        // 会连标题栏三键与缩放热区一起裁掉（用户定案 2026-11-03）。
+        .with(SettingSpec::enumeration(
+            "appearance.window_corner",
+            "system",
+            super::appearance::WINDOW_CORNERS,
+            AiPolicy::audited(),
+            "窗口圆角：system（跟随系统：Win11/Server 2025 走 DWM，Win10 保持直角）/ square（总是直角），默认 system",
+        ))
+        // 已废弃：D17 定案 appearance.theme_mode 为准（旧值读兼容映射，写永远走新键）。
+        .with(
+            SettingSpec::new(
+                "ui.theme",
+                super::spec::ValueKind::Enum(LEGACY_THEMES),
+                serde_json::Value::Null,
+                AiPolicy::retired(),
+                "【已废弃】改用 appearance.theme_mode；旧值读兼容：system→auto / metro_light→light / metro_dark→dark",
+            )
+            .deprecated("appearance.theme_mode", THEME_ALIASES),
+        )
+        .with(SettingSpec::float(
+            "ui.scale",
+            1.0,
+            (0.75, 2.0),
+            AiPolicy::silent(),
+            "界面缩放系数",
+        ))
+        .with(SettingSpec::int(
+            "ui.window.width",
+            1280,
+            (320, 16384),
+            AiPolicy::silent(),
+            "主窗口宽度（逻辑像素）",
+        ))
+        .with(SettingSpec::int(
+            "ui.window.height",
+            800,
+            (200, 16384),
+            AiPolicy::silent(),
+            "主窗口高度（逻辑像素）",
+        ))
+        .with(SettingSpec::enumeration(
+            "log.level",
+            "info",
+            LOG_LEVELS,
+            AiPolicy::audited(),
+            "启动器日志级别",
+        ))
+}
diff --git a/crates/core/src/setting/migrate.rs b/crates/core/src/setting/migrate.rs
new file mode 100644
index 0000000..03bd13a
--- /dev/null
+++ b/crates/core/src/setting/migrate.rs
@@ -0,0 +1,222 @@
+//! 迁移链：`schemaVersion N → N+1` 顺序迁移框架 + 收据闸门（防重放）。
+//!
+//! 出处：`DevDocs/PlanDoc/04-data-and-config.md` §3（迁移链 + 迁移收据）、
+//! `DevDocs/analyse/07-settings-packaging-update.md` §1.8（收据存源文件 `sourceSHA256`）。
+//!
+//! 与 HMCL 的差别：HMCL 完全靠 `$schema` 字段做兼容、迁移只处理遗留格式；ULL 在这之上补一条
+//! 「major 逐级迁移链」——每一步只跨一个 major，缺环/重复/逆序在 `push` 时就报错，
+//! 避免出现「跳版迁移脚本」这种组合爆炸。
+
+use std::path::Path;
+
+use serde_json::{Map, Value};
+
+use crate::platform::error::PlatformResult;
+use crate::platform::receipt::{self, MigrationReceipt, ReplayDecision};
+
+use super::error::{SettingError, SettingResult};
+use super::schema::{SchemaVersion, SCHEMA_VERSION_KEY};
+
+/// 一步迁移。实现者只管把 `root` 从 `from` 改造成 `to`。
+pub trait SettingMigration: Send + Sync {
+    /// 起始版本。
+    fn from(&self) -> SchemaVersion;
+    /// 目标版本（必须等于 `from.next_major()`）。
+    fn to(&self) -> SchemaVersion;
+    /// 一句话说明（进日志与迁移报告）。
+    fn describe(&self) -> &'static str;
+    /// 就地改 JSON 对象；`Err(String)` 会被包成 [`SettingError::Migration`]。
+    ///
+    /// # Errors
+    /// 结构不符合预期（该有的键没有/类型不对）时返回原因。
+    fn apply(&self, root: &mut Map<String, Value>) -> Result<(), String>;
+}
+
+/// 迁移报告（进日志 / 遥测 / 收据）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct MigrationReport {
+    /// 起始版本。
+    pub from: SchemaVersion,
+    /// 结束版本。
+    pub to: SchemaVersion,
+    /// 依次执行的步骤说明。
+    pub applied: Vec<&'static str>,
+}
+
+impl MigrationReport {
+    /// 是否真的做了迁移。
+    #[must_use]
+    pub fn is_noop(&self) -> bool {
+        self.applied.is_empty()
+    }
+}
+
+/// 有序迁移链。
+#[derive(Default)]
+pub struct MigrationChain {
+    steps: Vec<Box<dyn SettingMigration>>,
+}
+
+impl std::fmt::Debug for MigrationChain {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_list()
+            .entries(self.steps.iter().map(|step| step.describe()))
+            .finish()
+    }
+}
+
+impl MigrationChain {
+    /// 空链。
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// 追加一步；必须与上一环首尾相接，且只跨一个 major。
+    ///
+    /// # Errors
+    /// 跨多个 major、起始版本重复、顺序错乱时返回 [`SettingError::ChainBroken`]。
+    pub fn push(&mut self, step: Box<dyn SettingMigration>) -> SettingResult<()> {
+        let from = step.from();
+        let to = step.to();
+        if to != from.next_major() {
+            return Err(SettingError::ChainBroken {
+                reason: format!("一步迁移只能跨一个 major：{from} → {to}"),
+            });
+        }
+        if self.steps.iter().any(|existing| existing.from() == from) {
+            return Err(SettingError::ChainBroken {
+                reason: format!("{from} 已有迁移步骤"),
+            });
+        }
+        if let Some(last) = self.steps.last() {
+            if last.to() != from {
+                return Err(SettingError::ChainBroken {
+                    reason: format!("顺序错误：上一环到 {}，本环从 {from}", last.to()),
+                });
+            }
+        }
+        self.steps.push(step);
+        Ok(())
+    }
+
+    /// 步骤数。
+    #[must_use]
+    pub fn len(&self) -> usize {
+        self.steps.len()
+    }
+
+    /// 是否没有步骤。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.steps.is_empty()
+    }
+
+    /// 步骤说明清单（日志用）。
+    #[must_use]
+    pub fn describe(&self) -> Vec<&'static str> {
+        self.steps.iter().map(|step| step.describe()).collect()
+    }
+
+    /// 链能达到的最新版本。
+    #[must_use]
+    pub fn latest(&self) -> Option<SchemaVersion> {
+        self.steps.last().map(|step| step.to())
+    }
+
+    /// 从 `from` 起要执行的步骤（含 `from` 那一步）。
+    ///
+    /// # Errors
+    /// 链里没有以 `from` 开头的步骤（版本不认识）时返回 [`SettingError::ChainBroken`]。
+    pub fn plan_from(&self, from: SchemaVersion) -> SettingResult<Vec<&dyn SettingMigration>> {
+        let start = self
+            .steps
+            .iter()
+            .position(|step| step.from() == from)
+            .ok_or_else(|| SettingError::ChainBroken {
+                reason: format!("链里没有以 {from} 起始的迁移步骤"),
+            })?;
+        Ok(self.steps[start..]
+            .iter()
+            .map(|step| step.as_ref())
+            .collect())
+    }
+
+    /// 顺序执行迁移，并把 `schemaVersion` 镜像更新成最终 major。
+    ///
+    /// # Errors
+    /// 缺环 → [`SettingError::ChainBroken`]；某步失败 → [`SettingError::Migration`]。
+    pub fn migrate(
+        &self,
+        from: SchemaVersion,
+        root: &mut Map<String, Value>,
+    ) -> SettingResult<MigrationReport> {
+        let plan = self.plan_from(from)?;
+        let mut current = from;
+        let mut applied = Vec::with_capacity(plan.len());
+        for step in plan {
+            step.apply(root).map_err(|reason| SettingError::Migration {
+                from: current,
+                to: step.to(),
+                reason,
+            })?;
+            current = step.to();
+            applied.push(step.describe());
+        }
+        root.insert(SCHEMA_VERSION_KEY.to_owned(), Value::from(current.major));
+        Ok(MigrationReport {
+            from,
+            to: current,
+            applied,
+        })
+    }
+}
+
+/// 收据闸门：迁移前问一句「这次该不该跑」。
+#[derive(Debug, Clone, Copy)]
+pub struct MigrationGate<'a> {
+    receipt_path: &'a Path,
+    now_ms: u64,
+}
+
+impl<'a> MigrationGate<'a> {
+    /// 绑定收据路径与当前时间（毫秒 since UNIX_EPOCH，注入便于测试）。
+    #[must_use]
+    pub const fn new(receipt_path: &'a Path, now_ms: u64) -> Self {
+        Self {
+            receipt_path,
+            now_ms,
+        }
+    }
+
+    /// 当前时间。
+    #[must_use]
+    pub const fn now_ms(&self) -> u64 {
+        self.now_ms
+    }
+
+    /// 读收据并判断是否重放。
+    ///
+    /// # Errors
+    /// 收据损坏或读失败时返回 [`crate::platform::error::PlatformError`]。
+    pub fn evaluate(&self, source_fingerprint: &str) -> PlatformResult<ReplayDecision> {
+        let existing = receipt::read(self.receipt_path)?;
+        Ok(receipt::decide(existing.as_ref(), source_fingerprint))
+    }
+
+    /// 是否该执行迁移（收据在且源指纹相同 → `false`）。
+    ///
+    /// # Errors
+    /// 同 [`Self::evaluate`]。
+    pub fn should_run(&self, source_fingerprint: &str) -> PlatformResult<bool> {
+        Ok(self.evaluate(source_fingerprint)?.should_replay())
+    }
+
+    /// 记录一次迁移收据。
+    ///
+    /// # Errors
+    /// 写盘失败时返回 [`crate::platform::error::PlatformError`]。
+    pub fn record(&self, receipt: &MigrationReceipt) -> PlatformResult<()> {
+        receipt::write(self.receipt_path, receipt)
+    }
+}
diff --git a/crates/core/src/setting/mod.rs b/crates/core/src/setting/mod.rs
new file mode 100644
index 0000000..f968aae
--- /dev/null
+++ b/crates/core/src/setting/mod.rs
@@ -0,0 +1,36 @@
+//! 配置与数据目录：三模式数据根（Portable 默认 / Standard / Custom）、schema 化配置、原子写、迁移收据。
+//!
+//! 设计定稿：`DevDocs/PlanDoc/04-data-and-config.md`（决策 D6）。
+//! 刻意把 setting 放在 core 而不是 UI 层——这是 HMCL 的架构债
+//! （`DevDocs/analyse/01-architecture-overview.md` §3.5），我们反过来做。
+//!
+//! 与其它模块的契约：所有模块的配置读写统一走本模块的 schema API，
+//! 模块自有配置键需先在 `DevDocs/SubAgentsTalk/` 报备（见该目录 README 的对齐点）。
+//! 暴露给各模块的签名清单见 `DevDocs/SubAgentsTalk/setting-接口约定.md`。
+//!
+//! 公共面（M12 已落地）：
+//! - [`schema`]：`$schema` / `schemaVersion` 标识、8 态兼容判定 → 三档访问权；
+//! - [`spec`] + [`catalog`]：键元数据（类型/范围、默认值）与键目录；
+//! - [`policy`]：AI 可写白名单与敏感分级（`setting::spec::AiPolicy` 仍是兼容别名）；
+//! - [`keys`] / [`instance_keys`]：`launcher.json`、`profiles.json`、`instances/<id>.json` 的键表；
+//! - [`appearance`]：D17「外观（高级）」键簇的取值快照与校验（主题三态 / 背景图 / 面板透明度 /
+//!   玻璃拟态 / 强调色）；
+//! - [`document`]：内存文档（点分键、脏字段、未知字段保留、默认值不落盘）；
+//! - [`store`]：单文件加载降级 + 原子保存 + 坏文件备份；
+//! - [`save`] / [`save_worker`]：200ms 去抖攒批与后台保存线程；
+//! - [`migrate`]：`schemaVersion N → N+1` 迁移链 + 收据闸门。
+
+pub mod appearance;
+pub mod catalog;
+pub mod document;
+pub mod error;
+pub mod instance_keys;
+pub mod json_path;
+pub mod keys;
+pub mod migrate;
+pub mod policy;
+pub mod save;
+pub mod save_worker;
+pub mod schema;
+pub mod spec;
+pub mod store;
diff --git a/crates/core/src/setting/policy.rs b/crates/core/src/setting/policy.rs
new file mode 100644
index 0000000..f071ace
--- /dev/null
+++ b/crates/core/src/setting/policy.rs
@@ -0,0 +1,92 @@
+//! 键的 AI 边界：可写白名单与敏感分级（弹窗确认）。
+//!
+//! 出处：`DevDocs/PlanDoc/02-ai-agent-design.md` §3.1（AI 安全边界：白名单 + 类型/范围校验 +
+//! 分级确认）、`DevDocs/PlanDoc/04-data-and-config.md` §3（schema 化）。
+//!
+//! 从 [`super::spec`] 拆出来的原因很实际：`spec.rs` 摸到 400 行硬上限（`guards.yml` 的
+//! file-size 门禁），而「策略」与「键的形状」本来就是两件事。
+
+/// 敏感分级：决定 AI 改这个键时要不要弹窗。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub enum Sensitivity {
+    /// 普通键：静默生效。
+    Low,
+    /// 静默生效但审计标记（便于回看「AI 动过什么」）。
+    Medium,
+    /// 敏感键：必须 UI 弹窗确认。
+    High,
+}
+
+impl Sensitivity {
+    /// 稳定名。
+    #[must_use]
+    pub const fn as_str(&self) -> &'static str {
+        match self {
+            Self::Low => "low",
+            Self::Medium => "medium",
+            Self::High => "high",
+        }
+    }
+
+    /// 是否必须人工确认。
+    #[must_use]
+    pub const fn requires_confirmation(&self) -> bool {
+        matches!(self, Self::High)
+    }
+}
+
+/// 一个键的 AI 可写策略。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct AiPolicy {
+    /// AI 是否允许写这个键（白名单）。
+    pub writable: bool,
+    /// 敏感分级。
+    pub sensitivity: Sensitivity,
+}
+
+impl AiPolicy {
+    /// 普通键：AI 可写，静默生效。
+    #[must_use]
+    pub const fn silent() -> Self {
+        Self {
+            writable: true,
+            sensitivity: Sensitivity::Low,
+        }
+    }
+
+    /// 可写但要审计标记。
+    #[must_use]
+    pub const fn audited() -> Self {
+        Self {
+            writable: true,
+            sensitivity: Sensitivity::Medium,
+        }
+    }
+
+    /// 可写但必须弹窗确认（java 路径 / 数据目录 / 代理 / AI 端点 / 隔离档位）。
+    #[must_use]
+    pub const fn sensitive() -> Self {
+        Self {
+            writable: true,
+            sensitivity: Sensitivity::High,
+        }
+    }
+
+    /// 已废弃键：AI 不可写，读兼容映射到替代键后由替代键承担策略。
+    #[must_use]
+    pub const fn retired() -> Self {
+        Self {
+            writable: false,
+            sensitivity: Sensitivity::Low,
+        }
+    }
+
+    /// 锁死：AI 永远不能写（凭据/密钥，D9「AI 永不触凭据」）。
+    #[must_use]
+    pub const fn locked() -> Self {
+        Self {
+            writable: false,
+            sensitivity: Sensitivity::High,
+        }
+    }
+}
diff --git a/crates/core/src/setting/save.rs b/crates/core/src/setting/save.rs
new file mode 100644
index 0000000..679469d
--- /dev/null
+++ b/crates/core/src/setting/save.rs
@@ -0,0 +1,217 @@
+//! 保存通道的**去抖攒批**部分（纯逻辑，可注入时钟，确定性单测）。
+//!
+//! 出处：`DevDocs/analyse/07-settings-packaging-update.md` §1.6（HMCL `FileSaver`）：
+//! 入队 → 消费线程先 `sleep(200ms)` 等更多改动 → 全量 drain 去重 → 逐条 `saveSync`（tmp + move）。
+//! 效果：一次窗口拖拽只产生一次写盘，而不是 60 次。
+//!
+//! 分层：本文件只管「什么时候写、写什么」；真正落盘由 [`JobSink`] 决定
+//! （生产用 [`AtomicSink`]，测试用记录型 sink）。
+
+use std::collections::BTreeMap;
+use std::path::{Path, PathBuf};
+use std::time::{Duration, Instant};
+
+use super::error::SettingResult;
+
+/// 默认去抖窗口（analyse/07 §1.6 的 200ms）。
+pub const DEFAULT_DEBOUNCE: Duration = Duration::from_millis(200);
+
+/// 一条待写任务。
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct Pending {
+    payload: Vec<u8>,
+    queued_at: Instant,
+}
+
+/// 按 key 去重的去抖队列：同一 key 的新内容覆盖旧内容，但**保留首次入队时间**
+/// （窗口从第一次改动开始算，避免连续改动把写盘无限推迟）。
+#[derive(Debug, Clone)]
+pub struct DebounceQueue<K: Ord> {
+    debounce: Duration,
+    pending: BTreeMap<K, Pending>,
+}
+
+impl<K: Ord + Clone> DebounceQueue<K> {
+    /// 新建一个去抖队列。
+    #[must_use]
+    pub fn new(debounce: Duration) -> Self {
+        Self {
+            debounce,
+            pending: BTreeMap::new(),
+        }
+    }
+
+    /// 去抖窗口。
+    #[must_use]
+    pub const fn debounce(&self) -> Duration {
+        self.debounce
+    }
+
+    /// 入队（同 key 覆盖内容）。返回 `true` 表示是新增条目。
+    pub fn enqueue(&mut self, key: K, payload: impl Into<Vec<u8>>, now: Instant) -> bool {
+        match self.pending.get_mut(&key) {
+            Some(existing) => {
+                existing.payload = payload.into();
+                false
+            }
+            None => {
+                self.pending.insert(
+                    key,
+                    Pending {
+                        payload: payload.into(),
+                        queued_at: now,
+                    },
+                );
+                true
+            }
+        }
+    }
+
+    /// 待写条目数。
+    #[must_use]
+    pub fn len(&self) -> usize {
+        self.pending.len()
+    }
+
+    /// 是否没有待写任务。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.pending.is_empty()
+    }
+
+    /// 某 key 是否在队列里。
+    #[must_use]
+    pub fn contains(&self, key: &K) -> bool {
+        self.pending.contains_key(key)
+    }
+
+    /// 最早该写盘的时刻。
+    #[must_use]
+    pub fn next_due(&self) -> Option<Instant> {
+        self.pending
+            .values()
+            .map(|pending| pending.queued_at + self.debounce)
+            .min()
+    }
+
+    /// 取出所有已过窗口的任务（按键排序，保证写盘顺序稳定）。
+    pub fn drain_due(&mut self, now: Instant) -> Vec<(K, Vec<u8>)> {
+        let due: Vec<K> = self
+            .pending
+            .iter()
+            .filter(|(_, pending)| pending.queued_at + self.debounce <= now)
+            .map(|(key, _)| key.clone())
+            .collect();
+        self.take(due)
+    }
+
+    /// 取出全部任务（关停兜底）。
+    pub fn drain_all(&mut self) -> Vec<(K, Vec<u8>)> {
+        let all: Vec<K> = self.pending.keys().cloned().collect();
+        self.take(all)
+    }
+
+    fn take(&mut self, keys: Vec<K>) -> Vec<(K, Vec<u8>)> {
+        keys.into_iter()
+            .filter_map(|key| {
+                self.pending
+                    .remove(&key)
+                    .map(|pending| (key, pending.payload))
+            })
+            .collect()
+    }
+}
+
+impl<K: Ord + Clone> Default for DebounceQueue<K> {
+    fn default() -> Self {
+        Self::new(DEFAULT_DEBOUNCE)
+    }
+}
+
+/// 真正落盘的执行者（测试可注入记录型实现）。
+pub trait JobSink {
+    /// 写一个文件。
+    ///
+    /// # Errors
+    /// 落盘失败时返回 [`super::error::SettingError`]。
+    fn write(&self, path: &Path, payload: &[u8]) -> SettingResult<()>;
+}
+
+/// 生产用 sink：tmp → fsync → rename。
+#[derive(Debug, Clone, Copy, Default)]
+pub struct AtomicSink;
+
+impl JobSink for AtomicSink {
+    fn write(&self, path: &Path, payload: &[u8]) -> SettingResult<()> {
+        crate::platform::atomic::write_atomic(path, payload)?;
+        Ok(())
+    }
+}
+
+/// 去抖队列 + sink 的组合体（app 层持有它，或交给 [`super::save_worker::SaveWorker`] 托管）。
+#[derive(Debug, Clone)]
+pub struct CoalescingWriter<S: JobSink> {
+    queue: DebounceQueue<PathBuf>,
+    sink: S,
+}
+
+impl<S: JobSink> CoalescingWriter<S> {
+    /// 组合去抖队列与 sink。
+    #[must_use]
+    pub fn new(sink: S, debounce: Duration) -> Self {
+        Self {
+            queue: DebounceQueue::new(debounce),
+            sink,
+        }
+    }
+
+    /// 入队一次写盘。
+    pub fn queue(&mut self, path: impl Into<PathBuf>, payload: impl Into<Vec<u8>>, now: Instant) {
+        self.queue.enqueue(path.into(), payload, now);
+    }
+
+    /// 待写条目数。
+    #[must_use]
+    pub fn pending_len(&self) -> usize {
+        self.queue.len()
+    }
+
+    /// 是否没有待写任务。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.queue.is_empty()
+    }
+
+    /// 最早该写盘的时刻。
+    #[must_use]
+    pub fn next_due(&self) -> Option<Instant> {
+        self.queue.next_due()
+    }
+
+    /// 写掉已过窗口的任务，返回写了几个文件。
+    ///
+    /// # Errors
+    /// sink 落盘失败时返回 [`super::error::SettingError`]。
+    pub fn flush_due(&mut self, now: Instant) -> SettingResult<usize> {
+        let jobs = self.queue.drain_due(now);
+        self.run(jobs)
+    }
+
+    /// 写掉全部任务（关停兜底），返回写了几个文件。
+    ///
+    /// # Errors
+    /// sink 落盘失败时返回 [`super::error::SettingError`]。
+    pub fn flush_all(&mut self) -> SettingResult<usize> {
+        let jobs = self.queue.drain_all();
+        self.run(jobs)
+    }
+
+    fn run(&mut self, jobs: Vec<(PathBuf, Vec<u8>)>) -> SettingResult<usize> {
+        let mut written = 0usize;
+        for (path, payload) in jobs {
+            self.sink.write(&path, &payload)?;
+            written += 1;
+        }
+        Ok(written)
+    }
+}
diff --git a/crates/core/src/setting/save_worker.rs b/crates/core/src/setting/save_worker.rs
new file mode 100644
index 0000000..78adf63
--- /dev/null
+++ b/crates/core/src/setting/save_worker.rs
@@ -0,0 +1,181 @@
+//! 去抖保存的线程封装：app 层持有它，界面改配置只入队，后台线程负责攒批落盘。
+//!
+//! 出处：`DevDocs/analyse/07-settings-packaging-update.md` §1.6（HMCL `FileSaver` 消费线程 +
+//! 关停钩子 `waitForAllSaves()`）。本实现的「攒批/去抖/落盘」逻辑在 [`super::save`]，
+//! 这里只做线程与命令通道，方便对时序逻辑保持确定性单测。
+
+use std::io;
+use std::path::PathBuf;
+use std::sync::mpsc::{self, Receiver, RecvTimeoutError, Sender};
+use std::thread::{self, JoinHandle};
+use std::time::{Duration, Instant};
+
+use super::error::{SettingError, SettingResult};
+use super::save::{AtomicSink, CoalescingWriter, DEFAULT_DEBOUNCE};
+
+/// 线程没起时的兜底路径标记（只为让 [`SettingError::Io`] 有出处）。
+const WORKER_PATH: &str = "<save-worker>";
+
+enum Command {
+    Queue { path: PathBuf, payload: Vec<u8> },
+    Flush(Sender<SettingResult<()>>),
+    Shutdown(Sender<SettingResult<()>>),
+}
+
+/// 后台保存线程句柄。
+#[derive(Debug)]
+pub struct SaveWorker {
+    tx: Option<Sender<Command>>,
+    handle: Option<JoinHandle<()>>,
+}
+
+impl SaveWorker {
+    /// 用默认 200ms 去抖窗口起线程。
+    ///
+    /// # Errors
+    /// 线程创建失败时返回 [`SettingError::Io`]。
+    pub fn spawn_default() -> SettingResult<Self> {
+        Self::spawn(DEFAULT_DEBOUNCE)
+    }
+
+    /// 用指定去抖窗口起线程。
+    ///
+    /// # Errors
+    /// 线程创建失败时返回 [`SettingError::Io`]。
+    pub fn spawn(debounce: Duration) -> SettingResult<Self> {
+        let (tx, rx) = mpsc::channel();
+        let handle = thread::Builder::new()
+            .name("ull-save".to_owned())
+            .spawn(move || run_loop(&rx, debounce))
+            .map_err(io_error)?;
+        Ok(Self {
+            tx: Some(tx),
+            handle: Some(handle),
+        })
+    }
+
+    /// 入队一次写盘（不阻塞）。
+    ///
+    /// # Errors
+    /// 保存线程已停止时返回 [`SettingError::Io`]。
+    pub fn queue(
+        &self,
+        path: impl Into<PathBuf>,
+        payload: impl Into<Vec<u8>>,
+    ) -> SettingResult<()> {
+        let command = Command::Queue {
+            path: path.into(),
+            payload: payload.into(),
+        };
+        self.send(command)
+    }
+
+    /// 同步落盘（返回时队列已空，且错误已带回当前线程）。
+    ///
+    /// # Errors
+    /// 保存线程已停止，或后台落盘失败时返回 [`SettingError`]。
+    pub fn flush(&self) -> SettingResult<()> {
+        let (ack_tx, ack_rx) = mpsc::channel();
+        self.send(Command::Flush(ack_tx))?;
+        ack_rx.recv().map_err(|_| {
+            io_error(io::Error::new(
+                io::ErrorKind::BrokenPipe,
+                "保存线程未回传结果",
+            ))
+        })?
+    }
+
+    /// drain 全部任务后停止线程。
+    ///
+    /// # Errors
+    /// 落盘失败时返回 [`SettingError`]。
+    pub fn shutdown(&mut self) -> SettingResult<()> {
+        let Some(tx) = self.tx.take() else {
+            return Ok(());
+        };
+        let (ack_tx, ack_rx) = mpsc::channel();
+        let sent = tx.send(Command::Shutdown(ack_tx));
+        let result = match sent {
+            Ok(()) => ack_rx.recv().unwrap_or_else(|_| {
+                Err(io_error(io::Error::new(
+                    io::ErrorKind::BrokenPipe,
+                    "保存线程未回传结果",
+                )))
+            }),
+            Err(_) => Ok(()),
+        };
+        if let Some(handle) = self.handle.take() {
+            handle.join().ok();
+        }
+        result
+    }
+
+    fn send(&self, command: Command) -> SettingResult<()> {
+        let Some(tx) = self.tx.as_ref() else {
+            return Err(io_error(io::Error::new(
+                io::ErrorKind::BrokenPipe,
+                "保存线程已停止",
+            )));
+        };
+        tx.send(command)
+            .map_err(|_| io_error(io::Error::new(io::ErrorKind::BrokenPipe, "保存线程已停止")))
+    }
+}
+
+impl Drop for SaveWorker {
+    fn drop(&mut self) {
+        self.shutdown().ok();
+    }
+}
+
+fn run_loop(rx: &Receiver<Command>, debounce: Duration) {
+    let mut writer = CoalescingWriter::new(AtomicSink, debounce);
+    let mut last_error: Option<SettingError> = None;
+
+    loop {
+        let wait = writer
+            .next_due()
+            .map(|due| due.saturating_duration_since(Instant::now()))
+            .unwrap_or(Duration::from_secs(3600))
+            .max(Duration::from_millis(1));
+
+        match rx.recv_timeout(wait) {
+            Ok(Command::Queue { path, payload }) => {
+                writer.queue(path, payload, Instant::now());
+            }
+            Ok(Command::Flush(ack)) => {
+                let result = combine(last_error.take(), writer.flush_all());
+                ack.send(result).ok();
+            }
+            Ok(Command::Shutdown(ack)) => {
+                let result = combine(last_error.take(), writer.flush_all());
+                ack.send(result).ok();
+                break;
+            }
+            Err(RecvTimeoutError::Timeout) => {
+                if let Err(err) = writer.flush_due(Instant::now()) {
+                    last_error = Some(err);
+                }
+            }
+            Err(RecvTimeoutError::Disconnected) => {
+                writer.flush_all().ok();
+                break;
+            }
+        }
+    }
+}
+
+/// 后台静默失败过的错误优先上报（不吞掉）。
+fn combine(previous: Option<SettingError>, result: SettingResult<usize>) -> SettingResult<()> {
+    match previous {
+        Some(err) => Err(err),
+        None => result.map(|_| ()),
+    }
+}
+
+fn io_error(source: io::Error) -> SettingError {
+    SettingError::Io {
+        path: PathBuf::from(WORKER_PATH),
+        source,
+    }
+}
diff --git a/crates/core/src/setting/schema.rs b/crates/core/src/setting/schema.rs
new file mode 100644
index 0000000..5849f00
--- /dev/null
+++ b/crates/core/src/setting/schema.rs
@@ -0,0 +1,292 @@
+//! `$schema` 与 `schemaVersion`：版本标识、8 态兼容判定、三档访问权。
+//!
+//! 出处：`DevDocs/analyse/07-settings-packaging-update.md` §1.5（`JsonSchema.check` 8 态 +
+//! `SettingFileAccess` 三档），`DevDocs/PlanDoc/04-data-and-config.md` §3。
+//!
+//! 我们抄的是「一个 `$schema` 字段决定可读/可写/是否保留原 schema」，不抄 HMCL 的
+//! `major.minor.patch` 三级分支——ULL 的迁移链按 **major** 走：`1.0.0 → 2.0.0 → 3.0.0`。
+
+use std::fmt;
+
+use serde_json::Value;
+
+/// `$schema` 键名。
+pub const SCHEMA_KEY: &str = "$schema";
+/// `schemaVersion` 键名（整数镜像 = major）。
+pub const SCHEMA_VERSION_KEY: &str = "schemaVersion";
+/// schema URL 前缀（逻辑标识，暂不对外发布）。
+pub const SCHEMA_URL_PREFIX: &str = "https://schemas.unlucky-launcher.dev/ull/";
+
+/// 配置文件的语义版本。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Default)]
+pub struct SchemaVersion {
+    /// 主版本（迁移链单位）。
+    pub major: u32,
+    /// 次版本（新版本文件只读）。
+    pub minor: u32,
+    /// 修订号。
+    pub patch: u32,
+}
+
+impl SchemaVersion {
+    /// 构造。
+    #[must_use]
+    pub const fn new(major: u32, minor: u32, patch: u32) -> Self {
+        Self {
+            major,
+            minor,
+            patch,
+        }
+    }
+
+    /// 解析 `1.0.0` 形式。
+    #[must_use]
+    pub fn parse(text: &str) -> Option<Self> {
+        let mut parts = text.split('.');
+        let major = parts.next()?.parse().ok()?;
+        let minor = parts.next()?.parse().ok()?;
+        let patch = parts.next()?.parse().ok()?;
+        if parts.next().is_some() {
+            return None;
+        }
+        Some(Self::new(major, minor, patch))
+    }
+
+    /// 下一个主版本（迁移链的一步）。
+    #[must_use]
+    pub const fn next_major(&self) -> Self {
+        Self::new(self.major + 1, 0, 0)
+    }
+}
+
+impl fmt::Display for SchemaVersion {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}.{}.{}", self.major, self.minor, self.patch)
+    }
+}
+
+/// 配置文件种类。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct SchemaId(&'static str);
+
+impl SchemaId {
+    /// `config/launcher.json`。
+    pub const LAUNCHER: Self = Self("launcher");
+    /// `config/profiles.json`。
+    pub const PROFILES: Self = Self("profiles");
+    /// `config/instances/<id>.json`。
+    pub const INSTANCE: Self = Self("instance");
+
+    /// 全部已知 id。
+    pub const ALL: [Self; 3] = [Self::LAUNCHER, Self::PROFILES, Self::INSTANCE];
+
+    /// 稳定名。
+    #[must_use]
+    pub const fn as_str(&self) -> &'static str {
+        self.0
+    }
+
+    /// 从字符串解析（只认已知 id）。
+    #[must_use]
+    pub fn parse(text: &str) -> Option<Self> {
+        Self::ALL.into_iter().find(|id| id.0 == text)
+    }
+}
+
+/// `$schema` 的完整标识：种类 + 版本。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct SchemaRef {
+    /// 种类。
+    pub id: SchemaId,
+    /// 版本。
+    pub version: SchemaVersion,
+}
+
+impl SchemaRef {
+    /// 构造。
+    #[must_use]
+    pub const fn new(id: SchemaId, version: SchemaVersion) -> Self {
+        Self { id, version }
+    }
+
+    /// 写进文件的 `$schema` 字符串。
+    #[must_use]
+    pub fn url(&self) -> String {
+        format!(
+            "{SCHEMA_URL_PREFIX}{}/{}.{}.{}",
+            self.id.as_str(),
+            self.version.major,
+            self.version.minor,
+            self.version.patch
+        )
+    }
+
+    /// 反解 `$schema` 字符串。
+    #[must_use]
+    pub fn parse_url(text: &str) -> Option<Self> {
+        let tail = text.strip_prefix(SCHEMA_URL_PREFIX)?;
+        let (id, version) = tail.split_once('/')?;
+        Some(Self::new(
+            SchemaId::parse(id)?,
+            SchemaVersion::parse(version)?,
+        ))
+    }
+}
+
+/// 文件与本实现期望 schema 的兼容状态（8 态）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SchemaCompat {
+    /// 同版本或更旧的版本：可读可写，正常升级。
+    ReadWrite,
+    /// 同 minor、更高 patch：可读可写，但保留原 `$schema`。
+    ReadWritePreserveSchema,
+    /// 同 major、更高 minor：可读不可写（新版写的文件），保留原 `$schema`。
+    ReadOnlyPreserveSchema,
+    /// 文件没有 `$schema`（首建 / 遗留格式）。
+    Missing,
+    /// `$schema` 不是我们能解析的 URL。
+    ///
+    /// 手写配置最容易踩的一格：前缀写错（`https://unlucky-launcher.local/schema/...`）后整份
+    /// 文件的价值都不该被丢掉，所以 M40 起按**只读**处理——值照读、不静默回落默认值，
+    /// 同时由 [`super::document::LoadProblem::UnknownSchema`] 明确告警。
+    Invalid,
+    /// 文件连 JSON 都解析不了（由加载方给出）。
+    Unparseable,
+    /// `$schema` 指向别的配置文件种类。
+    UnexpectedId,
+    /// 文件 major 高于本实现——不认识，绝不能覆盖。
+    UnsupportedMajor,
+}
+
+impl SchemaCompat {
+    /// 判定文件里的 `$schema`（缺失时由调用方给 [`Self::Missing`]）。
+    #[must_use]
+    pub fn check(value: &Value, expected: SchemaRef) -> Self {
+        match value.get(SCHEMA_KEY).and_then(Value::as_str) {
+            None => Self::Missing,
+            Some(url) => Self::check_url(url, expected),
+        }
+    }
+
+    /// 判定 `$schema` 字符串。
+    #[must_use]
+    pub fn check_url(url: &str, expected: SchemaRef) -> Self {
+        let Some(found) = SchemaRef::parse_url(url) else {
+            return Self::Invalid;
+        };
+        if found.id != expected.id {
+            return Self::UnexpectedId;
+        }
+        if found.version.major > expected.version.major {
+            return Self::UnsupportedMajor;
+        }
+        if found.version.major < expected.version.major {
+            // 旧文件：正常升级（迁移链负责搬运语义）。
+            return Self::ReadWrite;
+        }
+        if found.version.minor > expected.version.minor {
+            return Self::ReadOnlyPreserveSchema;
+        }
+        if found.version.minor == expected.version.minor
+            && found.version.patch > expected.version.patch
+        {
+            return Self::ReadWritePreserveSchema;
+        }
+        Self::ReadWrite
+    }
+
+    /// 稳定名（日志 / 收据）。
+    #[must_use]
+    pub const fn as_str(&self) -> &'static str {
+        match self {
+            Self::ReadWrite => "read_write",
+            Self::ReadWritePreserveSchema => "read_write_preserve_schema",
+            Self::ReadOnlyPreserveSchema => "read_only_preserve_schema",
+            Self::Missing => "missing",
+            Self::Invalid => "invalid",
+            Self::Unparseable => "unparseable",
+            Self::UnexpectedId => "unexpected_id",
+            Self::UnsupportedMajor => "unsupported_major",
+        }
+    }
+
+    /// 是否可读。
+    #[must_use]
+    pub const fn readable(&self) -> bool {
+        matches!(
+            self,
+            Self::ReadWrite
+                | Self::ReadWritePreserveSchema
+                | Self::ReadOnlyPreserveSchema
+                | Self::Missing
+                | Self::Invalid
+        )
+    }
+
+    /// 保存时是否沿用文件里原有的 `$schema` 字符串（不降级覆盖新版本标记）。
+    #[must_use]
+    pub const fn preserve_schema(&self) -> bool {
+        matches!(
+            self,
+            Self::ReadWritePreserveSchema | Self::ReadOnlyPreserveSchema
+        )
+    }
+
+    /// 映射到运行时三档访问权。
+    ///
+    /// [`Self::Invalid`] 走**只读**：认不出的 `$schema` 前缀不该让整份配置失效（值照读，
+    /// 由 [`super::document::LoadProblem::UnknownSchema`] 告警），但也不该被我们悄悄改写。
+    #[must_use]
+    pub const fn access(&self) -> FileAccess {
+        match self {
+            Self::ReadWrite | Self::ReadWritePreserveSchema | Self::Missing => {
+                FileAccess::ReadWrite
+            }
+            Self::ReadOnlyPreserveSchema | Self::Invalid => FileAccess::ReadOnly,
+            Self::Unparseable | Self::UnexpectedId | Self::UnsupportedMajor => {
+                FileAccess::Unreadable
+            }
+        }
+    }
+}
+
+/// 运行时访问权三档（锁文件/权限异常时降级运行而非崩溃）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum FileAccess {
+    /// 可读可写。
+    ReadWrite,
+    /// 可读不可写（新版文件 / 权限受限）。
+    ReadOnly,
+    /// 读不了：值不可信，全程不写（防止覆盖新版本配置）。
+    Unreadable,
+}
+
+impl FileAccess {
+    /// 能否使用文件里的值。
+    #[must_use]
+    pub const fn can_read(&self) -> bool {
+        !matches!(self, Self::Unreadable)
+    }
+
+    /// 能否保存。
+    #[must_use]
+    pub const fn can_save(&self) -> bool {
+        matches!(self, Self::ReadWrite)
+    }
+
+    /// UI 是否该禁用编辑。
+    #[must_use]
+    pub const fn blocks_editing(&self) -> bool {
+        !self.can_save()
+    }
+
+    /// 稳定名。
+    #[must_use]
+    pub const fn as_str(&self) -> &'static str {
+        match self {
+            Self::ReadWrite => "read_write",
+            Self::ReadOnly => "read_only",
+            Self::Unreadable => "unreadable",
+        }
+    }
+}
diff --git a/crates/core/src/setting/spec.rs b/crates/core/src/setting/spec.rs
new file mode 100644
index 0000000..90a751f
--- /dev/null
+++ b/crates/core/src/setting/spec.rs
@@ -0,0 +1,331 @@
+//! 配置键元数据：类型/范围、默认值、AI 可写白名单、敏感分级。
+//!
+//! 出处：`DevDocs/PlanDoc/04-data-and-config.md` §3（schema 化 + AI 可写键 = schema 子集）、
+//! `DevDocs/PlanDoc/02-ai-agent-design.md` §3.1（AI 安全边界：白名单 + 类型/范围校验 + 分级确认）。
+//!
+//! 这份元数据是「唯一真相源」：UI 设置页、AI 的 `get_config`/`set_config`、审计日志都读它。
+
+use serde_json::{json, Value};
+
+/// 键的值类型与约束。
+#[derive(Debug, Clone, PartialEq)]
+pub enum ValueKind {
+    /// 布尔。
+    Bool,
+    /// 整数（含闭区间范围）。
+    Int {
+        /// 下界（含）。
+        min: i64,
+        /// 上界（含）。
+        max: i64,
+    },
+    /// 浮点（含闭区间范围）。
+    Float {
+        /// 下界（含）。
+        min: f64,
+        /// 上界（含）。
+        max: f64,
+    },
+    /// 文本（长度上限，按字符数）。
+    Text {
+        /// 最大字符数。
+        max_len: usize,
+    },
+    /// 枚举（只允许列出的字面量）。
+    Enum(&'static [&'static str]),
+    /// 路径（非空字符串；绝对/相对都由业务层决定）。
+    Path,
+    /// 字符串列表。
+    TextList,
+    /// 枚举字面量数组：每个元素都必须落在白名单里（`overrides` 这类键用）。
+    EnumList(&'static [&'static str]),
+    /// 任意 JSON（数据结构本身不参与校验，用于档案列表这类「数据而非配置」的键）。
+    Any,
+}
+
+impl ValueKind {
+    /// 校验；返回中文原因便于直接给用户看。
+    pub fn check(&self, value: &Value) -> Result<(), String> {
+        match self {
+            Self::Bool => value
+                .is_boolean()
+                .then_some(())
+                .ok_or_else(|| format!("期望布尔，实际是 {value}")),
+            Self::Int { min, max } => {
+                let Some(number) = value.as_i64() else {
+                    return Err(format!("期望整数，实际是 {value}"));
+                };
+                if number < *min || number > *max {
+                    return Err(format!("{number} 超出范围 [{min}, {max}]"));
+                }
+                Ok(())
+            }
+            Self::Float { min, max } => {
+                let Some(number) = value.as_f64() else {
+                    return Err(format!("期望数字，实际是 {value}"));
+                };
+                if number < *min || number > *max {
+                    return Err(format!("{number} 超出范围 [{min}, {max}]"));
+                }
+                Ok(())
+            }
+            Self::Text { max_len } => {
+                let Some(text) = value.as_str() else {
+                    return Err(format!("期望文本，实际是 {value}"));
+                };
+                let len = text.chars().count();
+                if len > *max_len {
+                    return Err(format!("文本 {len} 字符，超过上限 {max_len}"));
+                }
+                Ok(())
+            }
+            Self::Enum(allowed) => {
+                let Some(text) = value.as_str() else {
+                    return Err(format!("期望枚举字面量，实际是 {value}"));
+                };
+                if allowed.contains(&text) {
+                    Ok(())
+                } else {
+                    Err(format!("{text:?} 不在 {allowed:?} 之中"))
+                }
+            }
+            Self::Path => match value.as_str() {
+                Some(text) if !text.trim().is_empty() => Ok(()),
+                _ => Err(format!("期望非空路径字符串，实际是 {value}")),
+            },
+            Self::TextList => {
+                let Some(items) = value.as_array() else {
+                    return Err(format!("期望字符串数组，实际是 {value}"));
+                };
+                if items.iter().all(Value::is_string) {
+                    Ok(())
+                } else {
+                    Err("数组里含非字符串元素".to_owned())
+                }
+            }
+            Self::EnumList(allowed) => {
+                let Some(items) = value.as_array() else {
+                    return Err(format!("期望枚举字面量数组，实际是 {value}"));
+                };
+                for item in items {
+                    let Some(text) = item.as_str() else {
+                        return Err(format!("数组里含非字符串元素: {item}"));
+                    };
+                    if !allowed.contains(&text) {
+                        return Err(format!("{text:?} 不在 {allowed:?} 之中"));
+                    }
+                }
+                Ok(())
+            }
+            Self::Any => Ok(()),
+        }
+    }
+
+    /// 转成 JSON Schema 片段（喂给 M16 的 `ToolSpec`）。
+    #[must_use]
+    pub(crate) fn to_json_schema(&self) -> Value {
+        match self {
+            Self::Bool => json!({ "type": "boolean" }),
+            Self::Int { min, max } => json!({ "type": "integer", "minimum": min, "maximum": max }),
+            Self::Float { min, max } => json!({ "type": "number", "minimum": min, "maximum": max }),
+            Self::Text { max_len } => json!({ "type": "string", "maxLength": max_len }),
+            Self::Enum(allowed) => json!({ "type": "string", "enum": allowed }),
+            Self::Path => json!({ "type": "string", "minLength": 1 }),
+            Self::TextList => json!({ "type": "array", "items": { "type": "string" } }),
+            Self::EnumList(allowed) => {
+                json!({ "type": "array", "items": { "type": "string", "enum": allowed } })
+            }
+            Self::Any => json!({}),
+        }
+    }
+}
+
+// AI 边界类型从 [`super::policy`] 拆出去（`spec.rs` 摸到 400 行硬上限），
+// 路径保持不变：`setting::spec::AiPolicy` 仍是可用名。
+pub use super::policy::{AiPolicy, Sensitivity};
+
+/// 键废弃信息：替代键 + 旧值映射表。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Deprecation {
+    /// 替代键（写永远走这里）。
+    pub replaced_by: &'static str,
+    /// 旧值 → 新值映射（读兼容）；表里没有的值原样带过去。
+    pub aliases: &'static [(&'static str, &'static str)],
+}
+
+impl Deprecation {
+    /// 把旧值翻译成新键能接受的值（非字符串或表里没有的值原样返回）。
+    #[must_use]
+    pub fn translate(&self, legacy: &Value) -> Value {
+        match legacy.as_str() {
+            Some(text) => self
+                .aliases
+                .iter()
+                .find(|(old, _)| *old == text)
+                .map_or_else(|| legacy.clone(), |(_, new)| Value::from(*new)),
+            None => legacy.clone(),
+        }
+    }
+}
+
+/// 一个配置键的完整元数据。
+#[derive(Debug, Clone, PartialEq)]
+pub struct SettingSpec {
+    /// 点分键名（如 `download.concurrency`）。
+    pub key: &'static str,
+    /// 类型与约束。
+    pub kind: ValueKind,
+    /// 默认值；`Value::Null` 表示「无默认」（如用户必须先选的路径）。
+    pub default: Value,
+    /// AI 策略。
+    pub ai: AiPolicy,
+    /// 一句话说明（UI 提示 + AI 工具描述）。
+    pub doc: &'static str,
+    /// 废弃信息：有值表示这个键只做**读兼容**，写必须走替代键。
+    pub deprecated: Option<Deprecation>,
+}
+
+impl SettingSpec {
+    /// 完全手工构造。
+    #[must_use]
+    pub const fn new(
+        key: &'static str,
+        kind: ValueKind,
+        default: Value,
+        ai: AiPolicy,
+        doc: &'static str,
+    ) -> Self {
+        Self {
+            key,
+            kind,
+            default,
+            ai,
+            doc,
+            deprecated: None,
+        }
+    }
+
+    /// 标记为「已废弃，读兼容到 `replaced_by`」，并按 `aliases` 翻译旧值。
+    ///
+    /// 用于键改名/语义变更（如 `ui.theme` → `appearance.theme_mode`，tower 键冲突裁决）：
+    /// 旧文件照读、下次保存只写新键，AI 白名单与工具 JSON Schema 自动排除本键。
+    #[must_use]
+    pub const fn deprecated(
+        mut self,
+        replaced_by: &'static str,
+        aliases: &'static [(&'static str, &'static str)],
+    ) -> Self {
+        self.deprecated = Some(Deprecation {
+            replaced_by,
+            aliases,
+        });
+        self
+    }
+
+    /// 该键是否已废弃。
+    #[must_use]
+    pub const fn is_deprecated(&self) -> bool {
+        self.deprecated.is_some()
+    }
+
+    /// 布尔键。
+    #[must_use]
+    pub fn bool(key: &'static str, default: bool, ai: AiPolicy, doc: &'static str) -> Self {
+        Self::new(key, ValueKind::Bool, Value::Bool(default), ai, doc)
+    }
+
+    /// 整数键（闭区间）。
+    #[must_use]
+    pub fn int(
+        key: &'static str,
+        default: i64,
+        (min, max): (i64, i64),
+        ai: AiPolicy,
+        doc: &'static str,
+    ) -> Self {
+        Self::new(
+            key,
+            ValueKind::Int { min, max },
+            Value::from(default),
+            ai,
+            doc,
+        )
+    }
+
+    /// 浮点键（闭区间）。
+    #[must_use]
+    pub fn float(
+        key: &'static str,
+        default: f64,
+        (min, max): (f64, f64),
+        ai: AiPolicy,
+        doc: &'static str,
+    ) -> Self {
+        Self::new(
+            key,
+            ValueKind::Float { min, max },
+            Value::from(default),
+            ai,
+            doc,
+        )
+    }
+
+    /// 文本键。
+    #[must_use]
+    pub fn text(
+        key: &'static str,
+        default: &str,
+        max_len: usize,
+        ai: AiPolicy,
+        doc: &'static str,
+    ) -> Self {
+        Self::new(
+            key,
+            ValueKind::Text { max_len },
+            Value::from(default),
+            ai,
+            doc,
+        )
+    }
+
+    /// 枚举键。
+    #[must_use]
+    pub fn enumeration(
+        key: &'static str,
+        default: &'static str,
+        allowed: &'static [&'static str],
+        ai: AiPolicy,
+        doc: &'static str,
+    ) -> Self {
+        Self::new(key, ValueKind::Enum(allowed), Value::from(default), ai, doc)
+    }
+
+    /// 路径键（无默认值，未设置时为 `null`）。
+    #[must_use]
+    pub fn path(key: &'static str, ai: AiPolicy, doc: &'static str) -> Self {
+        Self::new(key, ValueKind::Path, Value::Null, ai, doc)
+    }
+
+    /// 枚举字面量数组键（默认空数组；元素逐个校验）。
+    #[must_use]
+    pub fn enum_list(
+        key: &'static str,
+        allowed: &'static [&'static str],
+        ai: AiPolicy,
+        doc: &'static str,
+    ) -> Self {
+        Self::new(
+            key,
+            ValueKind::EnumList(allowed),
+            Value::Array(Vec::new()),
+            ai,
+            doc,
+        )
+    }
+
+    /// 任意 JSON 键（数据结构不参与校验）。
+    #[must_use]
+    pub fn any(key: &'static str, ai: AiPolicy, doc: &'static str) -> Self {
+        Self::new(key, ValueKind::Any, Value::Null, ai, doc)
+    }
+}
diff --git a/crates/core/src/setting/store.rs b/crates/core/src/setting/store.rs
new file mode 100644
index 0000000..737bc04
--- /dev/null
+++ b/crates/core/src/setting/store.rs
@@ -0,0 +1,301 @@
+//! 一个配置文件 = 一个 [`SettingStore`]：加载降级 → 编辑 → 原子保存 → 坏文件备份。
+//!
+//! 出处：`DevDocs/analyse/07-settings-packaging-update.md` §1.5-§1.6（8 态 schema / 三档访问权 /
+//! 「文件损坏 → 默认值 + 下次保存前备份 `xxx.json.1`」），`DevDocs/PlanDoc/04-data-and-config.md` §3。
+//!
+//! 加载永不 panic：读不了/版本不认识就降级成只读或不可读，让启动器带着默认值继续跑
+//! （analyse/07 §1「锁文件/权限异常时降级运行而非崩溃」）。
+
+use std::io;
+use std::path::{Path, PathBuf};
+
+use serde_json::Value;
+
+use crate::platform::atomic;
+
+use super::catalog::SettingSchema;
+use super::document::{LoadProblem, SettingDocument};
+use super::error::{SettingError, SettingResult};
+use super::migrate::{MigrationChain, MigrationReport};
+use super::schema::{FileAccess, SchemaCompat, SCHEMA_KEY, SCHEMA_VERSION_KEY};
+
+/// 保存结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum SaveOutcome {
+    /// 已原子落盘。
+    Saved(PathBuf),
+    /// 没有写盘，原因见 [`SkipReason`]。
+    Skipped(SkipReason),
+}
+
+impl SaveOutcome {
+    /// 是否真的写了盘。
+    #[must_use]
+    pub fn wrote(&self) -> bool {
+        matches!(self, Self::Saved(_))
+    }
+}
+
+/// 跳过保存的原因。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SkipReason {
+    /// 没有脏字段。
+    NotDirty,
+    /// 文件只读（`READ_ONLY`）。
+    ReadOnly,
+    /// 文件不可信（`UNREADABLE`），全程不写。
+    Unreadable,
+}
+
+impl SkipReason {
+    /// 稳定名。
+    #[must_use]
+    pub const fn as_str(&self) -> &'static str {
+        match self {
+            Self::NotDirty => "not_dirty",
+            Self::ReadOnly => "read_only",
+            Self::Unreadable => "unreadable",
+        }
+    }
+}
+
+/// 单个配置文件的内存 + 磁盘视图。
+#[derive(Debug, Clone)]
+pub struct SettingStore {
+    path: PathBuf,
+    doc: SettingDocument,
+    access: FileAccess,
+    compat: SchemaCompat,
+    problems: Vec<LoadProblem>,
+    backup_on_next_save: bool,
+}
+
+impl SettingStore {
+    /// 加载（或首建）一个配置文件；永不失败，状态从 [`Self::access`] 读。
+    #[must_use]
+    pub fn load(path: impl Into<PathBuf>, schema: SettingSchema) -> Self {
+        let mut store = Self {
+            path: path.into(),
+            doc: SettingDocument::new(schema.clone()),
+            access: FileAccess::ReadWrite,
+            compat: SchemaCompat::Missing,
+            problems: Vec::new(),
+            backup_on_next_save: false,
+        };
+        store.reload_inner();
+        store
+    }
+
+    /// 文件路径。
+    #[must_use]
+    pub fn path(&self) -> &Path {
+        &self.path
+    }
+
+    /// 访问权三档。
+    #[must_use]
+    pub const fn access(&self) -> FileAccess {
+        self.access
+    }
+
+    /// `$schema` 兼容状态。
+    #[must_use]
+    pub const fn compat(&self) -> SchemaCompat {
+        self.compat
+    }
+
+    /// 加载时的问题清单（未知键 / 坏值 / 版本镜像不一致…）。
+    #[must_use]
+    pub fn problems(&self) -> &[LoadProblem] {
+        &self.problems
+    }
+
+    /// 只读视图。
+    #[must_use]
+    pub const fn doc(&self) -> &SettingDocument {
+        &self.doc
+    }
+
+    /// 可变视图（迁移 / 导入用；正常改配置请走 [`Self::set`]，那里带访问权检查）。
+    pub const fn doc_mut(&mut self) -> &mut SettingDocument {
+        &mut self.doc
+    }
+
+    /// 生效值：文件值 → 默认值。
+    #[must_use]
+    pub fn effective(&self, key: &str) -> Option<&Value> {
+        self.doc.effective(key)
+    }
+
+    /// 是否有未落盘改动。
+    #[must_use]
+    pub fn is_dirty(&self) -> bool {
+        self.doc.is_dirty()
+    }
+
+    /// 改一个键（只读/不可读时直接拒绝，不静默丢改动）。
+    ///
+    /// # Errors
+    /// 文件只读 → [`SettingError::ReadOnly`]；不可读 → [`SettingError::Unreadable`]；
+    /// 键值不合法 → [`SettingError::InvalidValue`] / [`SettingError::UnknownKey`]。
+    pub fn set(&mut self, key: &str, value: Value) -> SettingResult<()> {
+        match self.access {
+            FileAccess::ReadWrite => self.doc.set(key, value),
+            FileAccess::ReadOnly => Err(SettingError::ReadOnly {
+                path: self.path.clone(),
+            }),
+            FileAccess::Unreadable => Err(SettingError::Unreadable {
+                path: self.path.clone(),
+                compat: self.compat,
+            }),
+        }
+    }
+
+    /// 保存（只写脏字段、原子落盘；不满足条件时返回 [`SaveOutcome::Skipped`]）。
+    ///
+    /// # Errors
+    /// 序列化 / 备份 / 写盘失败时返回 [`SettingError`]。
+    pub fn save(&mut self) -> SettingResult<SaveOutcome> {
+        if !self.access.can_save() {
+            let reason = if matches!(self.access, FileAccess::ReadOnly) {
+                SkipReason::ReadOnly
+            } else {
+                SkipReason::Unreadable
+            };
+            return Ok(SaveOutcome::Skipped(reason));
+        }
+        if !self.doc.is_dirty() {
+            return Ok(SaveOutcome::Skipped(SkipReason::NotDirty));
+        }
+        if self.backup_on_next_save {
+            self.backup_existing()?;
+        }
+        self.write_document()?;
+        Ok(SaveOutcome::Saved(self.path.clone()))
+    }
+
+    /// 显式强写（用户在 UI 上确认「覆盖只读/损坏文件」后调用）：先备份，再覆盖，恢复可写。
+    ///
+    /// # Errors
+    /// 备份或写盘失败时返回 [`SettingError`]。
+    pub fn save_forced(&mut self) -> SettingResult<SaveOutcome> {
+        self.backup_existing()?;
+        self.write_document()?;
+        self.access = FileAccess::ReadWrite;
+        self.backup_on_next_save = false;
+        Ok(SaveOutcome::Saved(self.path.clone()))
+    }
+
+    /// 重新从磁盘加载（丢弃内存改动）。
+    pub fn reload(&mut self) {
+        self.reload_inner();
+    }
+
+    /// 按迁移链把文件从旧版本推进到 schema 版本（补丁后再落盘由调用方决定）。
+    ///
+    /// # Errors
+    /// 链不完整或某步迁移失败时返回 [`SettingError`]。
+    pub fn apply_chain(
+        &mut self,
+        chain: &MigrationChain,
+    ) -> SettingResult<Option<MigrationReport>> {
+        let schema = self.doc.schema().clone();
+        if !self.access.can_read() || self.doc.version() == schema.version() {
+            return Ok(None);
+        }
+        let Value::Object(mut root) = self.doc.to_value() else {
+            return Ok(None);
+        };
+        let report = chain.migrate(self.doc.version(), &mut root)?;
+        root.insert(
+            SCHEMA_KEY.to_owned(),
+            Value::String(schema.schema_ref().url()),
+        );
+        root.insert(
+            SCHEMA_VERSION_KEY.to_owned(),
+            Value::from(schema.version().major),
+        );
+
+        let (mut document, problems) = SettingDocument::load(&schema, &Value::Object(root));
+        document.set_version(schema.version());
+        document.mark_all_dirty();
+        self.doc = document;
+        self.problems = problems;
+        Ok(Some(report))
+    }
+
+    /// 下一个空位的备份路径（`launcher.json.1`、`.2`…）。
+    #[must_use]
+    pub fn next_backup_path(&self) -> PathBuf {
+        for index in 1..=999u32 {
+            let candidate = PathBuf::from(format!("{}.{index}", self.path.display()));
+            if !candidate.exists() {
+                return candidate;
+            }
+        }
+        PathBuf::from(format!("{}.1", self.path.display()))
+    }
+
+    fn reload_inner(&mut self) {
+        let schema = self.doc.schema().clone();
+        self.doc = SettingDocument::new(schema.clone());
+        self.problems.clear();
+        self.access = FileAccess::ReadWrite;
+        self.compat = SchemaCompat::Missing;
+        self.backup_on_next_save = false;
+
+        let bytes = match std::fs::read(&self.path) {
+            Ok(bytes) => bytes,
+            // 首建：可写 + 全默认值。
+            Err(err) if err.kind() == io::ErrorKind::NotFound => return,
+            // 读不了（权限/被占用）：值不可信，全程不写。
+            Err(_) => {
+                self.access = FileAccess::Unreadable;
+                self.compat = SchemaCompat::Unparseable;
+                return;
+            }
+        };
+
+        match serde_json::from_slice::<Value>(&bytes) {
+            // 文件损坏：默认值 + 下次保存前先备份（不把坏文件当未知字段回写）。
+            Err(_) => {
+                self.compat = SchemaCompat::Unparseable;
+                self.backup_on_next_save = true;
+            }
+            Ok(value) => {
+                let compat = SchemaCompat::check(&value, schema.schema_ref());
+                self.compat = compat;
+                self.access = compat.access();
+                if !self.access.can_read() {
+                    return;
+                }
+                let (document, problems) = SettingDocument::load(&schema, &value);
+                self.doc = document;
+                self.problems = problems;
+            }
+        }
+    }
+
+    fn write_document(&mut self) -> SettingResult<()> {
+        let value = self.doc.to_value();
+        let bytes = serde_json::to_vec_pretty(&value).map_err(|source| SettingError::Json {
+            path: self.path.clone(),
+            source,
+        })?;
+        atomic::write_atomic(&self.path, &bytes)?;
+        self.doc.mark_clean();
+        Ok(())
+    }
+
+    fn backup_existing(&mut self) -> SettingResult<Option<PathBuf>> {
+        if !self.path.exists() {
+            return Ok(None);
+        }
+        let backup = self.next_backup_path();
+        std::fs::rename(&self.path, &backup).map_err(|source| SettingError::Io {
+            path: self.path.clone(),
+            source,
+        })?;
+        Ok(Some(backup))
+    }
+}
diff --git a/crates/core/tests/auth/auth_failure_journal.rs b/crates/core/tests/auth/auth_failure_journal.rs
new file mode 100644
index 0000000..a7e6755
--- /dev/null
+++ b/crates/core/tests/auth/auth_failure_journal.rs
@@ -0,0 +1,151 @@
+//! M38：认证失败事件落盘（`.ULL/logs/auth.jsonl`）与凭据红线。
+//!
+//! 验收场景：`ull accounts add msa` 失败后，终端文案会滚走；日志区里要留下
+//! 一行结构化记录（`code` / `detail_code` / `status` / `content_type` / `body_kind` /
+//! 已脱敏摘要），且**不含任何 token**。便携数据根还没初始化时先补建 `logs/`。
+
+use serde_json::json;
+use unlucky_core::auth::{AuthError, AuthFailureEvent, AuthJournal, BodyKind};
+
+use crate::support::{
+    assert_no_credentials, auth_for, expired_session, full_routes, routes_until_login, temp_dir,
+    AuthMock, MockReply, HTML_BLOCK_PAGE,
+};
+
+const JWT: &str = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.c2lnbmF0dXJlLXZhbHVlLXRoYXQtaXMtbG9uZy1lbm91Z2g";
+
+#[tokio::test]
+async fn body_digest_never_carries_credentials() {
+    let mut routes = routes_until_login();
+    routes.push((
+        "/login_with_xbox",
+        vec![MockReply::json_status(
+            403,
+            json!({ "error": "DENIED", "echo": "xsts-token-value", "jwt": JWT }),
+        )],
+    ));
+    let mock = AuthMock::start(routes).await;
+    let error = auth_for(&mock.base())
+        .device_code_login(|_| {})
+        .await
+        .expect_err("应失败");
+
+    let message = error.message();
+    assert_no_credentials(&message);
+    // 长不透明串（JWT）必须打码，别把 token 回显抄进摘要。
+    assert!(!message.contains("eyJhbGci"), "JWT 必须脱敏：{message}");
+    assert!(message.contains("redacted"), "{message}");
+
+    // 事件层同样不落凭据。
+    let event = AuthFailureEvent::of("device_code_login", &error);
+    let json = event.to_json().to_string();
+    assert_no_credentials(&json);
+    assert!(!json.contains("eyJhbGci"), "{json}");
+    assert!(json.contains("login_with_xbox_403"), "{json}");
+    mock.stop();
+}
+
+#[tokio::test]
+async fn failure_journal_initializes_logs_and_records_the_403() {
+    let root = temp_dir("diag-journal");
+    let logs = root.join(".ULL").join("logs");
+    let journal = AuthJournal::in_logs_dir(&logs);
+    assert!(!logs.exists(), "模拟未初始化的便携数据根");
+
+    let mut routes = routes_until_login();
+    routes.push((
+        "/login_with_xbox",
+        vec![MockReply::html(403, HTML_BLOCK_PAGE)],
+    ));
+    let mock = AuthMock::start(routes).await;
+    let error = auth_for(&mock.base())
+        .with_journal(Some(journal.clone()))
+        .device_code_login(|_| {})
+        .await
+        .expect_err("应失败");
+
+    let text = std::fs::read_to_string(journal.path()).expect("失败日志必须落盘");
+    let lines: Vec<&str> = text.lines().collect();
+    assert_eq!(lines.len(), 1, "一次失败一条记录：{text}");
+    let record: serde_json::Value = serde_json::from_str(lines[0]).expect("合法 JSONL");
+    assert_eq!(record["event"], "auth_failure");
+    assert_eq!(record["level"], "error");
+    assert_eq!(record["scope"], "device_code_login");
+    assert_eq!(record["step"], "login_with_xbox");
+    assert_eq!(record["detail_code"], "login_with_xbox_non_json");
+    assert_eq!(record["status"], 403);
+    assert_eq!(record["body_kind"], "html");
+    assert_eq!(record["transient"], true);
+    assert_eq!(
+        record["message"],
+        error.message(),
+        "事件里的文案要与返回的错误一致"
+    );
+    assert_no_credentials(&text);
+    mock.stop();
+    let _ = std::fs::remove_dir_all(&root);
+}
+
+#[tokio::test]
+async fn journal_event_shape_covers_non_chain_errors() {
+    let event = AuthFailureEvent::of("refresh", &AuthError::Canceled);
+    assert_eq!(event.detail_code, "canceled");
+    assert_eq!(event.step, None);
+    assert_eq!(event.status, None);
+    assert_eq!(event.body_kind, None);
+    assert!(!event.transient);
+    assert_eq!(event.to_json()["scope"], "refresh");
+
+    let detail = unlucky_core::auth::ResponseDetail {
+        step: "profile".to_string(),
+        what: "拉取 Minecraft 档案被拒".to_string(),
+        status: 401,
+        content_type: Some("application/json".to_string()),
+        kind: BodyKind::Json,
+        server_message: Some("Unauthorized".to_string()),
+        digest: "{\"error\":\"Unauthorized\"}".to_string(),
+    };
+    let chain = AuthFailureEvent::of("device_code_login", &AuthError::Response(Box::new(detail)));
+    assert_eq!(chain.step.as_deref(), Some("profile"));
+    assert_eq!(chain.detail_code, "profile_401");
+    assert_eq!(chain.status, Some(401));
+    assert!(!chain.transient, "JSON 拒绝不是可重试的网络问题");
+}
+
+#[tokio::test]
+async fn successful_login_writes_no_journal_and_refresh_failures_do() {
+    let root = temp_dir("diag-journal-ok");
+    let journal = AuthJournal::in_logs_dir(root.join("logs"));
+
+    // 成功：不落盘。
+    let mock = AuthMock::start(full_routes()).await;
+    auth_for(&mock.base())
+        .with_journal(Some(journal.clone()))
+        .device_code_login(|_| {})
+        .await
+        .expect("应登录成功");
+    assert!(!journal.path().exists(), "成功路径不写失败日志");
+    mock.stop();
+
+    // 刷新失败：落一条（凭据被撤销 = 要人重新登录）。
+    let failing = AuthMock::start(vec![(
+        "/token",
+        vec![MockReply::json_status(
+            400,
+            json!({ "error": "invalid_grant", "error_description": "AADSTS70000" }),
+        )],
+    )])
+    .await;
+    let error = auth_for(&failing.base())
+        .with_journal(Some(journal.clone()))
+        .refresh(&expired_session())
+        .await
+        .expect_err("应失败");
+    assert!(error.is_credential_expired());
+    let text = std::fs::read_to_string(journal.path()).expect("刷新失败也要落盘");
+    assert_eq!(text.lines().count(), 1, "{text}");
+    assert!(text.contains("refresh"), "{text}");
+    assert!(text.contains("credential_expired"), "{text}");
+    failing.stop();
+    let _ = std::fs::remove_dir_all(&root);
+}
diff --git a/crates/core/tests/auth/authlib_api.rs b/crates/core/tests/auth/authlib_api.rs
new file mode 100644
index 0000000..dcdb8d7
--- /dev/null
+++ b/crates/core/tests/auth/authlib_api.rs
@@ -0,0 +1,307 @@
+//! Yggdrasil（authlib-injector）四动作的报文级对接：登录 / 刷新 / 校验 / 注销。
+
+use serde_json::json;
+use unlucky_core::auth::authlib::{
+    AuthlibAuth, AuthlibEndpoints, AuthlibProfile, AuthlibServerMeta, AuthlibSession,
+};
+use unlucky_core::auth::{AuthError, Secret};
+
+use crate::support::{AuthMock, MockReply};
+
+const API_ROOT: &str = "https://example.invalid/api/yggdrasil/";
+const PROFILE_ID: &str = "0123456789abcdef0123456789abcdef";
+
+fn paths() -> (&'static str, &'static str, &'static str, &'static str) {
+    (
+        "/api/yggdrasil/authserver/authenticate",
+        "/api/yggdrasil/authserver/refresh",
+        "/api/yggdrasil/authserver/validate",
+        "/api/yggdrasil/authserver/invalidate",
+    )
+}
+
+/// 把 API 根改指到 mock（`base` 代替 https://example.invalid）。
+fn mock_root(mock: &AuthMock) -> String {
+    format!("{}/api/yggdrasil", mock.base())
+}
+
+fn session() -> AuthlibSession {
+    AuthlibSession {
+        access_token: Secret::new("access-token-value"),
+        client_token: Secret::new("client-token-value"),
+        selected_profile: Some(AuthlibProfile {
+            id: PROFILE_ID.to_string(),
+            name: "Steve".to_string(),
+        }),
+    }
+}
+
+#[tokio::test]
+async fn authenticate_sends_the_canonical_body() {
+    let (authenticate, _, _, _) = paths();
+    let mock = AuthMock::start(vec![(
+        authenticate,
+        vec![MockReply::json(json!({
+            "accessToken": "access-token-value",
+            "clientToken": "client-token-value",
+            "selectedProfile": { "id": PROFILE_ID, "name": "Steve" }
+        }))],
+    )])
+    .await;
+    let auth = AuthlibAuth::new().expect("构造");
+    let login = auth
+        .authenticate(
+            &mock_root(&mock),
+            "steve@example.com",
+            &Secret::new("hunter2-password"),
+            &Secret::new("client-token-value"),
+        )
+        .await
+        .expect("登录成功");
+
+    assert_eq!(login.access_token.expose(), "access-token-value");
+    assert_eq!(login.client_token.expose(), "client-token-value");
+    assert!(login.has_profile());
+    assert_eq!(
+        login.selected_profile.as_ref().map(|p| p.name.as_str()),
+        Some("Steve")
+    );
+
+    let body = &mock.bodies_on(authenticate)[0];
+    assert!(
+        body.contains("\"agent\":{\"name\":\"Minecraft\",\"version\":1}"),
+        "{body}"
+    );
+    assert!(body.contains("\"requestUser\":true"), "{body}");
+    assert!(
+        body.contains("\"username\":\"steve@example.com\""),
+        "{body}"
+    );
+    assert!(
+        body.contains("\"clientToken\":\"client-token-value\""),
+        "{body}"
+    );
+    // 密码确实发了（否则登录不了），但会话 Debug 里看不到它。
+    assert!(body.contains("hunter2-password"));
+    assert!(!format!("{login:?}").contains("hunter2-password"));
+    mock.stop();
+}
+
+#[tokio::test]
+async fn wrong_password_is_denied_with_server_message() {
+    let (authenticate, _, _, _) = paths();
+    let mock = AuthMock::start(vec![(
+        authenticate,
+        vec![MockReply::json_status(
+            403,
+            json!({
+                "error": "ForbiddenOperationException",
+                "errorMessage": "Invalid credentials. Invalid username or password."
+            }),
+        )],
+    )])
+    .await;
+    let auth = AuthlibAuth::new().expect("构造");
+    let error = auth
+        .authenticate(
+            &mock_root(&mock),
+            "steve",
+            &Secret::new("wrong"),
+            &Secret::new("client-token-value"),
+        )
+        .await
+        .expect_err("应失败");
+    match error {
+        AuthError::Denied { code, description } => {
+            assert_eq!(code, "ForbiddenOperationException");
+            assert!(description.contains("Invalid credentials"));
+        }
+        other => panic!("应是 Denied，实际 {other:?}"),
+    }
+    mock.stop();
+}
+
+#[tokio::test]
+async fn server_must_echo_the_client_token() {
+    let (authenticate, _, _, _) = paths();
+    let mock = AuthMock::start(vec![(
+        authenticate,
+        vec![MockReply::json(json!({
+            "accessToken": "access-token-value",
+            "clientToken": "someone-elses-token",
+            "selectedProfile": { "id": PROFILE_ID, "name": "Steve" }
+        }))],
+    )])
+    .await;
+    let auth = AuthlibAuth::new().expect("构造");
+    let error = auth
+        .authenticate(
+            &mock_root(&mock),
+            "steve",
+            &Secret::new("pw"),
+            &Secret::new("client-token-value"),
+        )
+        .await
+        .expect_err("应拒绝");
+    assert_eq!(error.code(), "malformed");
+    assert!(
+        error.message().contains("clientToken"),
+        "{}",
+        error.message()
+    );
+    mock.stop();
+}
+
+#[tokio::test]
+async fn refresh_can_select_a_character() {
+    let (_, refresh, _, _) = paths();
+    let mock = AuthMock::start(vec![(
+        refresh,
+        vec![MockReply::json(json!({
+            "accessToken": "access-token-2",
+            "clientToken": "client-token-value",
+            "selectedProfile": { "id": PROFILE_ID, "name": "Alex" }
+        }))],
+    )])
+    .await;
+    let auth = AuthlibAuth::new().expect("构造");
+    let wanted = AuthlibProfile {
+        id: PROFILE_ID.to_string(),
+        name: "Alex".to_string(),
+    };
+    let refreshed = auth
+        .refresh(&mock_root(&mock), &session(), Some(&wanted))
+        .await
+        .expect("刷新成功");
+    assert_eq!(refreshed.access_token.expose(), "access-token-2");
+    assert_eq!(refreshed.selected_profile.expect("角色").name, "Alex");
+    // 新的 refresh_token 不存在于 Yggdrasil：clientToken 保持不变。
+    assert_eq!(refreshed.client_token.expose(), "client-token-value");
+
+    let body = &mock.bodies_on(refresh)[0];
+    assert!(body.contains("\"selectedProfile\":{\"id\":\"0123456789abcdef0123456789abcdef\""));
+    assert!(body.contains("\"accessToken\":\"access-token-value\""));
+    mock.stop();
+}
+
+#[tokio::test]
+async fn refresh_that_did_not_switch_character_is_malformed() {
+    let (_, refresh, _, _) = paths();
+    let mock = AuthMock::start(vec![(
+        refresh,
+        vec![MockReply::json(json!({
+            "accessToken": "access-token-2",
+            "clientToken": "client-token-value",
+            "selectedProfile": { "id": PROFILE_ID, "name": "Steve" }
+        }))],
+    )])
+    .await;
+    let auth = AuthlibAuth::new().expect("构造");
+    let wanted = AuthlibProfile {
+        id: "ffffffffffffffffffffffffffffffff".to_string(),
+        name: "Ghost".to_string(),
+    };
+    let error = auth
+        .refresh(&mock_root(&mock), &session(), Some(&wanted))
+        .await
+        .expect_err("应失败");
+    assert_eq!(error.code(), "malformed");
+    mock.stop();
+}
+
+#[tokio::test]
+async fn forbidden_on_refresh_means_credential_expired() {
+    let (_, refresh, _, _) = paths();
+    let mock = AuthMock::start(vec![(
+        refresh,
+        vec![MockReply::json_status(
+            403,
+            json!({ "error": "ForbiddenOperationException", "errorMessage": "Invalid token." }),
+        )],
+    )])
+    .await;
+    let auth = AuthlibAuth::new().expect("构造");
+    let error = auth
+        .refresh(&mock_root(&mock), &session(), None)
+        .await
+        .expect_err("应失败");
+    assert!(error.is_credential_expired(), "{error:?}");
+    mock.stop();
+}
+
+#[tokio::test]
+async fn validate_distinguishes_invalid_token_from_server_trouble() {
+    let (_, _, validate, _) = paths();
+    // 空体 200 → 有效
+    let ok = AuthMock::start(vec![(validate, vec![MockReply::status(200)])]).await;
+    let auth = AuthlibAuth::new().expect("构造");
+    assert!(auth
+        .validate(&mock_root(&ok), &session())
+        .await
+        .expect("有效"));
+    ok.stop();
+
+    // 403 ForbiddenOperationException → 无效（返回值 false，不抛错）
+    let invalid = AuthMock::start(vec![(
+        validate,
+        vec![MockReply::json_status(
+            403,
+            json!({ "error": "ForbiddenOperationException", "errorMessage": "Invalid token." }),
+        )],
+    )])
+    .await;
+    assert!(!auth
+        .validate(&mock_root(&invalid), &session())
+        .await
+        .expect("无效"));
+    invalid.stop();
+
+    // 500 → 服务器问题，必须抛错（调用方才会重试而不是刷新）
+    let broken = AuthMock::start(vec![(validate, vec![MockReply::status(500)])]).await;
+    let error = auth
+        .validate(&mock_root(&broken), &session())
+        .await
+        .expect_err("应失败");
+    assert_eq!(error.code(), "network");
+    broken.stop();
+}
+
+#[tokio::test]
+async fn invalidate_tolerates_already_invalid_tokens() {
+    let (_, _, _, invalidate) = paths();
+    let auth = AuthlibAuth::new().expect("构造");
+    let ok = AuthMock::start(vec![(invalidate, vec![MockReply::status(200)])]).await;
+    auth.invalidate(&mock_root(&ok), &session())
+        .await
+        .expect("注销成功");
+    ok.stop();
+
+    let gone = AuthMock::start(vec![(
+        invalidate,
+        vec![MockReply::json_status(
+            403,
+            json!({ "error": "ForbiddenOperationException" }),
+        )],
+    )])
+    .await;
+    auth.invalidate(&mock_root(&gone), &session())
+        .await
+        .expect("已失效也算成功");
+    gone.stop();
+}
+
+#[test]
+fn endpoints_and_metadata_stay_in_sync_with_the_protocol() {
+    let endpoints = AuthlibEndpoints::from_api_root(API_ROOT).expect("端点");
+    assert_eq!(
+        endpoints.authenticate,
+        format!("{API_ROOT}authserver/authenticate")
+    );
+    let meta = AuthlibServerMeta::from_value(&json!({
+        "meta": { "serverName": "Example", "feature.non_email_login": true },
+        "skinDomains": ["example.invalid"]
+    }));
+    assert_eq!(meta.name.as_deref(), Some("Example"));
+    assert!(meta.non_email_login);
+    assert_eq!(meta.skin_domains, vec!["example.invalid".to_string()]);
+}
diff --git a/crates/core/tests/auth/main.rs b/crates/core/tests/auth/main.rs
new file mode 100644
index 0000000..6fba1e5
--- /dev/null
+++ b/crates/core/tests/auth/main.rs
@@ -0,0 +1,21 @@
+//! `core::auth` 的集成测试入口。
+//!
+//! 每个子模块对应 mission 的一项验收：
+//! - `offline_uuid`：离线 UUID 与 JDK（= HMCL 算法）**逐字节对拍**的已知向量；
+//! - `store_separation`：元数据/凭据分文件、原子写、写序、容错与孤儿清理；
+//! - `microsoft_flow`：device-code 全链（含 pending / slow_down / 取消 / 超时 / XErr）；
+//! - `microsoft_authcode`：授权码流（本地回调服务器 / 授权 URL 向量 / code 换链 / 403 诊断）；
+//! - `microsoft_diagnostics`：非 2xx 正文诊断（JSON/HTML/空体分流）+ 失败日志落盘（M38）；
+//! - `microsoft_refresh`：refresh 轮换、profile 变脸防线、validate 语义、404 二义；
+//! - `authlib_api`：Yggdrasil 四动作的报文级对接。
+
+mod support;
+
+mod auth_failure_journal;
+mod authlib_api;
+mod microsoft_authcode;
+mod microsoft_diagnostics;
+mod microsoft_flow;
+mod microsoft_refresh;
+mod offline_uuid;
+mod store_separation;
diff --git a/crates/core/tests/auth/microsoft_authcode.rs b/crates/core/tests/auth/microsoft_authcode.rs
new file mode 100644
index 0000000..303101c
--- /dev/null
+++ b/crates/core/tests/auth/microsoft_authcode.rs
@@ -0,0 +1,295 @@
+//! 授权码流（`research/08` §3 方案 A）：本地回调服务器 + 授权 URL + code 换链。
+//!
+//! 覆盖验收口径：授权码换到 MS token → XBL → XSTS 全通；白名单未批前
+//! `login_with_xbox` 的 403 只要求**诊断文案正确**（M38 版），不绕过。
+
+use std::time::Duration;
+
+use serde_json::json;
+use unlucky_core::auth::microsoft::{
+    AuthCodePolicy, AuthCodePrompt, CallbackServer, MicrosoftAuth, MicrosoftEndpoints,
+};
+use unlucky_core::auth::AuthError;
+
+use crate::support::{full_routes, response_of, AuthMock, MockReply};
+
+const CLIENT_ID: &str = "test-client-id";
+
+fn policy(state: &str, timeout_ms: u64) -> AuthCodePolicy {
+    AuthCodePolicy {
+        callback_timeout: Duration::from_millis(timeout_ms),
+        bind_attempts: 3,
+        port: None,
+        state: Some(state.to_string()),
+    }
+}
+
+/// 模拟浏览器：把 `code` 送到本地回调地址（真发一次 HTTP，走 localhost 解析）。
+async fn deliver(redirect_uri: &str, query: &str) {
+    let url = format!("{redirect_uri}?{query}");
+    // 回调服务器可能在 accept 中，给一拍让绑定先落地。
+    tokio::time::sleep(Duration::from_millis(10)).await;
+    let response = reqwest::get(&url).await.expect("浏览器回调");
+    assert_eq!(response.status(), 200, "回调页应回 200");
+    let page = response.text().await.expect("回调页正文");
+    assert!(page.contains("登录完成"), "回调页应是给用户看的完成页");
+}
+
+#[tokio::test]
+async fn authcode_login_completes_the_chain() {
+    let mock = AuthMock::start(full_routes()).await;
+    let auth = MicrosoftAuth::new(CLIENT_ID)
+        .expect("构造")
+        .with_endpoints(MicrosoftEndpoints::all_on(&mock.base()))
+        .with_authcode_policy(policy("state-abc", 5_000));
+
+    let mut prompted: Option<AuthCodePrompt> = None;
+    let session = auth
+        .authcode_login(|prompt| {
+            prompted = Some(prompt.clone());
+            let redirect = prompt.redirect_uri.clone();
+            tokio::spawn(
+                async move { deliver(&redirect, "code=the-auth-code&state=state-abc").await },
+            );
+        })
+        .await
+        .expect("授权码登录成功");
+
+    // 1. 宿主拿到的是「授权 URL + 本地回调地址」，两者端口必须一致。
+    let prompt = prompted.expect("必须回调展示授权 URL");
+    let redirect = prompt.redirect_uri.clone();
+    assert!(redirect.starts_with("http://localhost:"), "{redirect}");
+    assert!(redirect.ends_with("/auth"), "{redirect}");
+    assert!(prompt.authorization_url.contains("prompt=select_account"));
+    // 端点表在测试里整体指向 mock，所以授权页的路径是 `/authorize`（租户口径见向量单测）。
+    assert!(
+        prompt.authorization_url.starts_with(&mock.base())
+            && prompt
+                .authorization_url
+                .contains("/authorize?client_id=test-client-id"),
+        "{}",
+        prompt.authorization_url
+    );
+    assert!(prompt.authorization_url.contains("state=state-abc"));
+    assert_eq!(prompt.timeout, Duration::from_millis(5_000));
+
+    // 2. code 换 token 的表单：grant_type + 原样重定向 URI（URI 严格一致那条坑）。
+    let token_bodies = mock.bodies_on("/token");
+    assert_eq!(token_bodies.len(), 1, "只该换一次 token");
+    let body = &token_bodies[0];
+    assert!(body.contains("grant_type=authorization_code"), "{body}");
+    assert!(body.contains("code=the-auth-code"), "{body}");
+    assert!(
+        body.contains("redirect_uri=http%3A%2F%2Flocalhost%3A") && !body.contains(&redirect),
+        "redirect_uri 必须是编码后的同一字面量：{body}"
+    );
+    assert!(
+        body.contains("scope=XboxLive.signin+offline_access")
+            || body.contains("scope=XboxLive.signin%20offline_access"),
+        "{body}"
+    );
+    // 授权 URL 里的 redirect_uri 与 token 请求里的必须是同一个端口。
+    let encoded = redirect.replace(':', "%3A").replace('/', "%2F");
+    assert!(
+        prompt.authorization_url.contains(&encoded),
+        "{}",
+        prompt.authorization_url
+    );
+    assert!(body.contains(&encoded), "{body}");
+
+    // 3. 后链与会话：与设备码流同一套字段语义。
+    assert_eq!(session.profile_name, "Steve");
+    assert_eq!(session.access_token.expose(), "mc-access-token-value");
+    assert_eq!(session.refresh_token.expose(), "live-refresh-token-value");
+    assert!(!format!("{session:?}").contains("mc-access-token-value"));
+    assert_eq!(mock.bodies_on("/xbl").len(), 1);
+    assert_eq!(mock.bodies_on("/xsts").len(), 1);
+    mock.stop();
+}
+
+#[tokio::test]
+async fn callback_server_ignores_unrelated_requests_and_bad_state() {
+    let server = CallbackServer::bind(None, 1, "state-ok")
+        .await
+        .expect("绑定");
+    let port = server.port();
+    let browser = tokio::spawn(async move {
+        tokio::time::sleep(Duration::from_millis(20)).await;
+        let base = format!("http://localhost:{port}");
+        // favicon / 浏览器预热：404 但绝不能结束等待。
+        let favicon = reqwest::get(format!("{base}/favicon.ico"))
+            .await
+            .expect("favicon");
+        assert_eq!(favicon.status(), 404);
+        // state 不匹配（旧标签页的迟到回调）：400，继续等。
+        let stale = reqwest::get(format!("{base}/auth?code=stale-code&state=state-old"))
+            .await
+            .expect("迟到的回调");
+        assert_eq!(stale.status(), 400);
+        let good = reqwest::get(format!("{base}/auth?code=good-code&state=state-ok"))
+            .await
+            .expect("真回调");
+        assert_eq!(good.status(), 200);
+    });
+
+    let code = server
+        .wait_for_code(Duration::from_secs(5))
+        .await
+        .expect("应拿到 code");
+    assert_eq!(code, "good-code");
+    browser.await.expect("模拟浏览器任务");
+}
+
+#[tokio::test]
+async fn foreign_state_cannot_cancel_the_login() {
+    // P2 回归：回调先校验 state，再处理 error（RFC 6749 §4.1.2.1 / RFC 9207）。
+    // 修之前 `GET /auth?error=access_denied`（state 随便给或不给）就能把登录判成 Canceled。
+    let server = CallbackServer::bind(None, 1, "state-ok")
+        .await
+        .expect("绑定");
+    let port = server.port();
+    let browser = tokio::spawn(async move {
+        tokio::time::sleep(Duration::from_millis(20)).await;
+        let base = format!("http://localhost:{port}/auth");
+        // 1. 连 state 都不给：与本次登录无关 → 400，继续等。
+        let bare = reqwest::get(format!("{base}?error=access_denied"))
+            .await
+            .expect("伪造取消");
+        assert_eq!(bare.status(), 400);
+        // 2. state 明显不匹配：同样忽略，绝不当成用户取消。
+        let foreign = reqwest::get(format!("{base}?error=access_denied&state=not-our-state"))
+            .await
+            .expect("伪造取消带错 state");
+        assert_eq!(foreign.status(), 400);
+        // 3. 真正带对 state 的回调仍然能完成登录。
+        let good = reqwest::get(format!("{base}?code=good-code&state=state-ok"))
+            .await
+            .expect("真回调");
+        assert_eq!(good.status(), 200);
+    });
+
+    let code = server
+        .wait_for_code(Duration::from_secs(5))
+        .await
+        .expect("伪造的 access_denied 不能中止登录");
+    assert_eq!(code, "good-code");
+    browser.await.expect("模拟浏览器任务");
+}
+
+#[tokio::test]
+async fn access_denied_with_our_state_is_still_canceled() {
+    // 另一半语义：用户真的在授权页点了取消（带本机 state）→ 仍然是 Canceled。
+    let server = CallbackServer::bind(None, 1, "state-ok")
+        .await
+        .expect("绑定");
+    let port = server.port();
+    let browser = tokio::spawn(async move {
+        tokio::time::sleep(Duration::from_millis(20)).await;
+        let url = format!("http://localhost:{port}/auth?error=access_denied&state=state-ok");
+        let _ = reqwest::get(url).await;
+    });
+    let error = server
+        .wait_for_code(Duration::from_secs(5))
+        .await
+        .expect_err("本机 state 的取消要生效");
+    assert_eq!(error, AuthError::Canceled);
+    browser.await.expect("模拟浏览器任务");
+}
+
+#[tokio::test]
+async fn callback_timeout_is_reported() {
+    let auth = MicrosoftAuth::new(CLIENT_ID)
+        .expect("构造")
+        .with_authcode_policy(policy("state-abc", 30));
+    let error = auth
+        .authcode_login(|_prompt| {})
+        .await
+        .expect_err("没人回调就该超时");
+    assert_eq!(error.code(), "timeout");
+    assert!(
+        error.message().contains("浏览器回调"),
+        "{}",
+        error.message()
+    );
+}
+
+#[tokio::test]
+async fn access_denied_on_the_callback_page_is_canceled() {
+    let auth = MicrosoftAuth::new(CLIENT_ID)
+        .expect("构造")
+        .with_authcode_policy(policy("state-abc", 5_000));
+    let error = auth
+        .authcode_login(|prompt| {
+            let redirect = prompt.redirect_uri.clone();
+            tokio::spawn(async move {
+                tokio::time::sleep(Duration::from_millis(10)).await;
+                let url = format!("{redirect}?error=access_denied&state=state-abc");
+                let _ = reqwest::get(&url).await;
+            });
+        })
+        .await
+        .expect_err("用户取消");
+    assert_eq!(error, AuthError::Canceled);
+}
+
+#[tokio::test]
+async fn busy_port_retries_then_reports_which_port() {
+    // 先占住一个端口，再让回调服务器去绑同一个：必须失败并说清是哪个端口。
+    let occupied = tokio::net::TcpListener::bind(("127.0.0.1", 0))
+        .await
+        .expect("占端口");
+    let port = occupied.local_addr().expect("地址").port();
+    let error = CallbackServer::bind(Some(port), 2, "s")
+        .await
+        .expect_err("端口已被占");
+    assert_eq!(error.code(), "network");
+    assert!(
+        error.message().contains(&port.to_string()),
+        "文案要指出端口：{}",
+        error.message()
+    );
+    assert!(error.message().contains("重试 2 次"), "{}", error.message());
+    // 同一台机器上换个端口就能绑上（重试机制不是把错误吞掉）。
+    let ok = CallbackServer::bind(None, 1, "s").await.expect("内核分配");
+    assert_ne!(ok.port(), port);
+}
+
+#[tokio::test]
+async fn login_with_xbox_403_keeps_the_m38_diagnostic() {
+    // 白名单未批的真机状态：授权码换到 token、XBL/XSTS 全通，最后一步 403。
+    let mut routes = full_routes();
+    let (_, login) = routes
+        .iter_mut()
+        .find(|(path, _)| *path == "/login_with_xbox")
+        .expect("路由表里有 login_with_xbox");
+    *login = vec![MockReply::json_status(
+        403,
+        json!({ "path": "/authentication/login_with_xbox", "errorType": "FORBIDDEN",
+                "error": "Invalid app registration" }),
+    )];
+    let mock = AuthMock::start(routes).await;
+    let auth = MicrosoftAuth::new(CLIENT_ID)
+        .expect("构造")
+        .with_endpoints(MicrosoftEndpoints::all_on(&mock.base()))
+        .with_authcode_policy(policy("state-abc", 5_000));
+
+    let error = auth
+        .authcode_login(|prompt| {
+            let redirect = prompt.redirect_uri.clone();
+            tokio::spawn(async move { deliver(&redirect, "code=c&state=state-abc").await });
+        })
+        .await
+        .expect_err("403 必须冒出来");
+
+    let detail = response_of(&error);
+    assert_eq!(detail.status, 403);
+    assert_eq!(detail.detail_code(), "login_with_xbox_403");
+    // 「授权码这条流本身是通的」——这正是验收止步的位置。
+    assert_eq!(mock.bodies_on("/token").len(), 1);
+    assert_eq!(mock.bodies_on("/xbl").len(), 1);
+    assert_eq!(mock.bodies_on("/xsts").len(), 1);
+    let message = error.message();
+    assert!(message.contains("Minecraft 登录被拒"), "{message}");
+    assert!(message.contains("Invalid app registration"), "{message}");
+    mock.stop();
+}
diff --git a/crates/core/tests/auth/microsoft_diagnostics.rs b/crates/core/tests/auth/microsoft_diagnostics.rs
new file mode 100644
index 0000000..1a90e11
--- /dev/null
+++ b/crates/core/tests/auth/microsoft_diagnostics.rs
@@ -0,0 +1,231 @@
+//! M38：非 2xx 应答正文诊断（`AuthError::Response`）。
+//!
+//! 覆盖 MSA 真机验收里分不开的那几类：
+//! - **JSON 403**：真实服务拒绝（服务端文案直出，引导查许可/区域）；
+//! - **HTML 403**：网关/风控拦截页（引导查网络/代理，独立细分码 `*_non_json`）；
+//! - **空体 403**：同样按「不确定」分流（`*_empty_body`）；
+//! - 4xx / 5xx 各一，外加 XErr 优先级与 JSON 码的向后兼容。
+//!
+//! 失败日志（JSONL）与凭据红线在同一目录的 `auth_failure_journal.rs`。
+
+use serde_json::json;
+use unlucky_core::auth::{AuthError, BodyKind};
+
+use crate::support::{
+    assert_no_credentials, auth_for, full_routes, response_of, routes_until_login, AuthMock,
+    MockReply, HTML_BLOCK_PAGE,
+};
+
+#[tokio::test]
+async fn json_403_surfaces_server_message_and_points_at_license() {
+    let mut routes = routes_until_login();
+    routes.push((
+        "/login_with_xbox",
+        vec![MockReply::json_status(
+            403,
+            json!({
+                "path": "/authentication/login_with_xbox",
+                "error": "UNAUTHORIZED",
+                "errorMessage": "You do not own Minecraft Java Edition"
+            }),
+        )],
+    ));
+    let mock = AuthMock::start(routes).await;
+    let error = auth_for(&mock.base())
+        .device_code_login(|_| {})
+        .await
+        .expect_err("应失败");
+
+    assert_eq!(error.code(), "denied", "粗分流层保持 M31 的 denied");
+    assert_eq!(error.detail_code(), "login_with_xbox_403");
+    assert!(!error.is_transient(), "服务端明确拒绝，重试无意义");
+    let detail = response_of(&error);
+    assert_eq!(detail.status, 403);
+    assert_eq!(detail.kind, BodyKind::Json);
+    assert_eq!(detail.content_type.as_deref(), Some("application/json"));
+    let message = error.message();
+    // 服务端文案直出（验收要看到真实原因）。
+    assert!(message.contains("You do not own"), "{message}");
+    assert!(message.contains("UNAUTHORIZED"), "{message}");
+    assert!(message.contains("许可"), "应引导查许可：{message}");
+    assert!(
+        !message.contains("代理"),
+        "JSON 拒绝不该往网络引：{message}"
+    );
+    assert!(message.contains("响应摘要"), "{message}");
+    assert_no_credentials(&message);
+    mock.stop();
+}
+
+#[tokio::test]
+async fn html_403_is_routed_to_network_and_proxy() {
+    let mut routes = routes_until_login();
+    routes.push((
+        "/login_with_xbox",
+        vec![MockReply::html(403, HTML_BLOCK_PAGE)],
+    ));
+    let mock = AuthMock::start(routes).await;
+    let error = auth_for(&mock.base())
+        .device_code_login(|_| {})
+        .await
+        .expect_err("应失败");
+
+    assert_eq!(error.code(), "denied");
+    assert_eq!(
+        error.detail_code(),
+        "login_with_xbox_non_json",
+        "拦截页要有独立细分码"
+    );
+    assert!(error.is_transient(), "拦截页可以换代理重试");
+    let detail = response_of(&error);
+    assert_eq!(detail.kind, BodyKind::Html);
+    assert!(detail.is_interception());
+    assert_eq!(detail.status, 403);
+    assert!(
+        detail
+            .content_type
+            .as_deref()
+            .is_some_and(|value| value.contains("text/html")),
+        "{:?}",
+        detail.content_type
+    );
+    let message = error.message();
+    assert!(message.contains("响应非 JSON"), "{message}");
+    assert!(message.contains("网络"), "{message}");
+    assert!(message.contains("代理"), "{message}");
+    assert!(
+        message.contains("blocked by gateway"),
+        "摘要要留下证据：{message}"
+    );
+    assert!(
+        !message.contains("许可"),
+        "拦截页不该把用户引向许可：{message}"
+    );
+    assert_no_credentials(&message);
+    mock.stop();
+}
+
+#[tokio::test]
+async fn empty_403_reports_the_empty_body() {
+    let mut routes = routes_until_login();
+    routes.push(("/login_with_xbox", vec![MockReply::status(403)]));
+    let mock = AuthMock::start(routes).await;
+    let error = auth_for(&mock.base())
+        .device_code_login(|_| {})
+        .await
+        .expect_err("应失败");
+
+    assert_eq!(error.detail_code(), "login_with_xbox_empty_body");
+    let detail = response_of(&error);
+    assert_eq!(detail.kind, BodyKind::Empty);
+    assert!(detail.digest.is_empty());
+    assert!(error.message().contains("为空"), "{}", error.message());
+    mock.stop();
+}
+
+#[tokio::test]
+async fn profile_4xx_keeps_the_step_status_code() {
+    let mut routes = full_routes();
+    routes[6].1 = vec![MockReply::json_status(
+        401,
+        json!({ "path": "/minecraft/profile", "error": "Unauthorized" }),
+    )];
+    let mock = AuthMock::start(routes).await;
+    let error = auth_for(&mock.base())
+        .device_code_login(|_| {})
+        .await
+        .expect_err("应失败");
+    assert_eq!(error.detail_code(), "profile_401");
+    assert!(error.message().contains("档案"), "{}", error.message());
+    assert_no_credentials(&error.message());
+    mock.stop();
+}
+
+#[tokio::test]
+async fn entitlements_5xx_text_is_an_interception_not_a_license_verdict() {
+    let mut routes = full_routes();
+    routes[5].1 = vec![MockReply::text(503, "Service Unavailable")];
+    let mock = AuthMock::start(routes).await;
+    let error = auth_for(&mock.base())
+        .device_code_login(|_| {})
+        .await
+        .expect_err("应失败");
+    // 关键：网关页不能报成「你没买游戏」（M31 的 no_entitlement 只留给 JSON/空体）。
+    assert_eq!(error.detail_code(), "entitlements_non_json");
+    let detail = response_of(&error);
+    assert_eq!(detail.kind, BodyKind::Text);
+    assert_eq!(detail.status, 503);
+    assert!(
+        error.message().contains("Service Unavailable"),
+        "{}",
+        error.message()
+    );
+    mock.stop();
+}
+
+#[tokio::test]
+async fn entitlements_404_with_empty_body_still_reports_no_entitlement() {
+    let mut routes = full_routes();
+    routes[5].1 = vec![MockReply::status(404)];
+    let mock = AuthMock::start(routes).await;
+    let error = auth_for(&mock.base())
+        .device_code_login(|_| {})
+        .await
+        .expect_err("应失败");
+    // 向后兼容：M31 的稳定码 `no_entitlement` 不动。
+    match error {
+        AuthError::Denied { code, description } => {
+            assert_eq!(code, "no_entitlement");
+            assert!(description.contains("404"), "{description}");
+        }
+        other => panic!("应是 Denied，实际 {other:?}"),
+    }
+    mock.stop();
+}
+
+#[tokio::test]
+async fn entitlements_403_with_empty_body_is_not_a_license_verdict() {
+    let mut routes = full_routes();
+    routes[5].1 = vec![MockReply::status(403)];
+    let mock = AuthMock::start(routes).await;
+    let error = auth_for(&mock.base())
+        .device_code_login(|_| {})
+        .await
+        .expect_err("应失败");
+    // 403 且没正文：说不清是许可还是拦截，按「不确定」报，不下「没买游戏」的结论。
+    assert_eq!(error.detail_code(), "entitlements_empty_body");
+    mock.stop();
+}
+
+#[tokio::test]
+async fn xsts_401_without_xerr_still_reports_body_context() {
+    let mut routes = routes_until_login();
+    routes[3].1 = vec![MockReply::html(401, HTML_BLOCK_PAGE)];
+    let mock = AuthMock::start(routes).await;
+    let error = auth_for(&mock.base())
+        .device_code_login(|_| {})
+        .await
+        .expect_err("应失败");
+    assert_eq!(error.detail_code(), "xsts_non_json");
+    assert!(error.message().contains("XSTS"), "{}", error.message());
+    mock.stop();
+}
+
+#[tokio::test]
+async fn xerr_still_wins_over_the_body_diagnostic() {
+    let mut routes = routes_until_login();
+    routes[3].1 = vec![MockReply::json_status(
+        401,
+        json!({ "XErr": 2_148_916_235_u32, "Message": "country unavailable" }),
+    )];
+    let mock = AuthMock::start(routes).await;
+    let error = auth_for(&mock.base())
+        .device_code_login(|_| {})
+        .await
+        .expect_err("应失败");
+    match error {
+        AuthError::Xbox { code } => assert_eq!(code, 2_148_916_235),
+        other => panic!("XErr 判定必须优先，实际 {other:?}"),
+    }
+    mock.stop();
+}
diff --git a/crates/core/tests/auth/microsoft_flow.rs b/crates/core/tests/auth/microsoft_flow.rs
new file mode 100644
index 0000000..3cc3cb3
--- /dev/null
+++ b/crates/core/tests/auth/microsoft_flow.rs
@@ -0,0 +1,274 @@
+//! device-code 全链（打到进程内 mock 服务器）：报文形状 + 轮询状态机 + 错误分流。
+
+use std::time::Duration;
+
+use serde_json::json;
+use unlucky_core::auth::microsoft::{
+    DeviceCodePrompt, MicrosoftAuth, MicrosoftEndpoints, PollPolicy,
+};
+use unlucky_core::auth::AuthError;
+
+use crate::support::{AuthMock, MockReply};
+
+const PROFILE_ID: &str = "0f8fad5bd9cb469fa16570867728950e";
+const CLIENT_ID: &str = "test-client-id";
+
+fn fast_poll() -> PollPolicy {
+    PollPolicy {
+        min_interval: Duration::from_millis(1),
+        slow_down_step: Duration::from_millis(1),
+        max_wait: Duration::from_secs(5),
+    }
+}
+
+fn device_code_reply() -> MockReply {
+    MockReply::json(json!({
+        "user_code": "ABCD-1234",
+        "device_code": "device-code-secret-value",
+        "verification_uri": "https://www.microsoft.com/link",
+        "expires_in": 900,
+        "interval": 0,
+        "message": "go to the url"
+    }))
+}
+
+fn chain_replies() -> Vec<(&'static str, Vec<MockReply>)> {
+    vec![
+        ("/devicecode", vec![device_code_reply()]),
+        (
+            "/token",
+            vec![
+                MockReply::json(json!({ "error": "authorization_pending" })),
+                MockReply::json(json!({
+                    "access_token": "live-access-token-value",
+                    "refresh_token": "live-refresh-token-value"
+                })),
+            ],
+        ),
+        (
+            "/xbl",
+            vec![MockReply::json(json!({
+                "Token": "xbl-token-value",
+                "DisplayClaims": { "xui": [{ "uhs": "uhs-1" }] }
+            }))],
+        ),
+        (
+            "/xsts",
+            vec![MockReply::json(json!({
+                "Token": "xsts-token-value",
+                "DisplayClaims": { "xui": [{ "uhs": "uhs-1" }] }
+            }))],
+        ),
+        (
+            "/login_with_xbox",
+            vec![MockReply::json(json!({
+                "username": "Steve",
+                "access_token": "mc-access-token-value",
+                "token_type": "Bearer",
+                "expires_in": 86_400
+            }))],
+        ),
+        (
+            "/entitlements/mcstore",
+            vec![MockReply::json(json!({ "items": [] }))],
+        ),
+        (
+            "/profile",
+            vec![MockReply::json(
+                json!({ "id": PROFILE_ID, "name": "Steve" }),
+            )],
+        ),
+    ]
+}
+
+#[tokio::test]
+async fn device_code_login_runs_the_whole_chain() {
+    let mock = AuthMock::start(chain_replies()).await;
+    let auth = MicrosoftAuth::new(CLIENT_ID)
+        .expect("构造")
+        .with_endpoints(MicrosoftEndpoints::all_on(&mock.base()))
+        .with_poll_policy(fast_poll());
+
+    let mut prompted: Option<DeviceCodePrompt> = None;
+    let session = auth
+        .device_code_login(|prompt| prompted = Some(prompt.clone()))
+        .await
+        .expect("登录成功");
+
+    // 1. 用户码/URL 在轮询前就交给宿主了（CLI 才能先打印再等）。
+    let prompt = prompted.expect("必须回调展示用户码");
+    assert_eq!(prompt.user_code, "ABCD-1234");
+    assert_eq!(prompt.verification_uri, "https://www.microsoft.com/link");
+    assert_eq!(prompt.expires_in, Duration::from_secs(900));
+    assert_eq!(prompt.interval, Duration::ZERO, "服务端 interval 原样收下");
+    let (line1, line2) = prompt.lines();
+    assert!(line1.contains("https://www.microsoft.com/link"));
+    assert!(line2.contains("ABCD-1234"));
+
+    // 2. 会话字段：MC token 落 access_token，Live refresh 落 refresh_token。
+    assert_eq!(session.profile_id, PROFILE_ID);
+    assert_eq!(session.profile_name, "Steve");
+    assert_eq!(session.access_token.expose(), "mc-access-token-value");
+    assert_eq!(session.refresh_token.expose(), "live-refresh-token-value");
+    assert!(session.not_after_ms > 1_577_836_800_000);
+    assert!(session.has_profile_name());
+    // Debug 里不能出现任何 token。
+    let debug = format!("{session:?}");
+    assert!(!debug.contains("mc-access-token-value"), "{debug}");
+    assert!(!debug.contains("live-refresh-token-value"), "{debug}");
+
+    // 3. 报文形状（这几处抄错就会 400，必须逐条盯住）。
+    let device_bodies = mock.bodies_on("/devicecode");
+    assert_eq!(device_bodies.len(), 1);
+    assert!(device_bodies[0].contains("client_id=test-client-id"));
+    assert!(
+        device_bodies[0].contains("scope=XboxLive.signin+offline_access")
+            || device_bodies[0].contains("scope=XboxLive.signin%20offline_access")
+    );
+
+    let token_bodies = mock.bodies_on("/token");
+    assert_eq!(token_bodies.len(), 2, "pending 一次后成功");
+    for body in &token_bodies {
+        assert!(body.contains("grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code"));
+        assert!(body.contains("code=device-code-secret-value"));
+        assert!(!body.contains("{"), "表单体不该是 JSON：{body}");
+    }
+
+    let xbl = &mock.bodies_on("/xbl")[0];
+    // `d=` 前缀是 MSA 消费版票据标记（漏了就 400）。
+    assert!(
+        xbl.contains("\"RpsTicket\":\"d=live-access-token-value\""),
+        "{xbl}"
+    );
+    assert!(xbl.contains("user.auth.xboxlive.com"));
+
+    let xsts = &mock.bodies_on("/xsts")[0];
+    assert!(xsts.contains("rp://api.minecraftservices.com/"), "{xsts}");
+    assert!(xsts.contains("\"SandboxId\":\"RETAIL\""), "{xsts}");
+    assert!(xsts.contains("xbl-token-value"), "{xsts}");
+
+    let login = &mock.bodies_on("/login_with_xbox")[0];
+    assert!(
+        login.contains("XBL3.0 x=uhs-1;xsts-token-value"),
+        "identityToken 拼接错：{login}"
+    );
+
+    mock.stop();
+}
+
+#[tokio::test]
+async fn slow_down_backs_off_instead_of_failing() {
+    let mut routes = chain_replies();
+    // 把 /token 换成 pending → slow_down → 成功。
+    routes[1].1 = vec![
+        MockReply::json(json!({ "error": "authorization_pending" })),
+        MockReply::json(json!({ "error": "slow_down" })),
+        MockReply::json(json!({
+            "access_token": "live-access-token-value",
+            "refresh_token": "live-refresh-token-value"
+        })),
+    ];
+    let mock = AuthMock::start(routes).await;
+    let auth = MicrosoftAuth::new(CLIENT_ID)
+        .expect("构造")
+        .with_endpoints(MicrosoftEndpoints::all_on(&mock.base()))
+        .with_poll_policy(fast_poll());
+    let session = auth.device_code_login(|_| {}).await.expect("登录成功");
+    assert_eq!(session.profile_name, "Steve");
+    assert_eq!(mock.bodies_on("/token").len(), 3, "三次轮询");
+    mock.stop();
+}
+
+#[tokio::test]
+async fn access_denied_is_reported_as_canceled() {
+    let mut routes = chain_replies();
+    routes[1].1 = vec![MockReply::json(json!({ "error": "access_denied" }))];
+    let mock = AuthMock::start(routes).await;
+    let auth = MicrosoftAuth::new(CLIENT_ID)
+        .expect("构造")
+        .with_endpoints(MicrosoftEndpoints::all_on(&mock.base()))
+        .with_poll_policy(fast_poll());
+    let error = auth.device_code_login(|_| {}).await.expect_err("应取消");
+    assert_eq!(error, AuthError::Canceled);
+    assert_eq!(error.code(), "canceled");
+    mock.stop();
+}
+
+#[tokio::test]
+async fn expired_device_code_is_a_timeout() {
+    let mut routes = chain_replies();
+    routes[1].1 = vec![MockReply::json(json!({ "error": "expired_token" }))];
+    let mock = AuthMock::start(routes).await;
+    let auth = MicrosoftAuth::new(CLIENT_ID)
+        .expect("构造")
+        .with_endpoints(MicrosoftEndpoints::all_on(&mock.base()))
+        .with_poll_policy(fast_poll());
+    let error = auth.device_code_login(|_| {}).await.expect_err("应超时");
+    assert_eq!(error.code(), "timeout");
+    mock.stop();
+}
+
+#[tokio::test]
+async fn polling_gives_up_after_the_wait_budget() {
+    let mut routes = chain_replies();
+    let pending = MockReply::json(json!({ "error": "authorization_pending" }));
+    routes[1].1 = vec![pending; 64];
+    let mock = AuthMock::start(routes).await;
+    let auth = MicrosoftAuth::new(CLIENT_ID)
+        .expect("构造")
+        .with_endpoints(MicrosoftEndpoints::all_on(&mock.base()))
+        .with_poll_policy(PollPolicy {
+            min_interval: Duration::from_millis(1),
+            slow_down_step: Duration::from_millis(1),
+            max_wait: Duration::from_millis(20),
+        });
+    let error = auth.device_code_login(|_| {}).await.expect_err("应超时");
+    assert_eq!(error.code(), "timeout");
+    assert!(mock.bodies_on("/token").len() < 64, "超时后必须停止轮询");
+    mock.stop();
+}
+
+#[tokio::test]
+async fn xsts_401_with_xerr_is_mapped() {
+    let mut routes = chain_replies();
+    routes[2].1 = vec![MockReply::json_status(
+        401,
+        json!({ "Identity": "0", "XErr": 2_148_916_233_u32, "Message": "no xbox account" }),
+    )];
+    let mock = AuthMock::start(routes).await;
+    let auth = MicrosoftAuth::new(CLIENT_ID)
+        .expect("构造")
+        .with_endpoints(MicrosoftEndpoints::all_on(&mock.base()))
+        .with_poll_policy(fast_poll());
+    let error = auth.device_code_login(|_| {}).await.expect_err("应失败");
+    match error {
+        AuthError::Xbox { code } => {
+            assert_eq!(code, 2_148_916_233);
+            assert!(unlucky_core::auth::error::xbox_hint(code).contains("Xbox 档案"));
+        }
+        other => panic!("应是 Xbox 错误，实际 {other:?}"),
+    }
+    mock.stop();
+}
+
+#[tokio::test]
+async fn device_code_endpoint_failure_is_denied() {
+    let mock = AuthMock::start(vec![(
+        "/devicecode",
+        vec![MockReply::json_status(
+            400,
+            json!({ "error": "invalid_client", "error_description": "bad client id" }),
+        )],
+    )])
+    .await;
+    let auth = MicrosoftAuth::new(CLIENT_ID)
+        .expect("构造")
+        .with_endpoints(MicrosoftEndpoints::all_on(&mock.base()))
+        .with_poll_policy(fast_poll());
+    let error = auth.device_code_login(|_| {}).await.expect_err("应失败");
+    match error {
+        AuthError::Denied { code, .. } => assert_eq!(code, "invalid_client"),
+        other => panic!("应是 Denied，实际 {other:?}"),
+    }
+    mock.stop();
+}
diff --git a/crates/core/tests/auth/microsoft_refresh.rs b/crates/core/tests/auth/microsoft_refresh.rs
new file mode 100644
index 0000000..1b475ba
--- /dev/null
+++ b/crates/core/tests/auth/microsoft_refresh.rs
@@ -0,0 +1,283 @@
+//! refresh 语义与 validate 分支：轮换、换号防线、404 二义、拥有权门禁。
+
+use std::time::Duration;
+
+use serde_json::json;
+use unlucky_core::auth::microsoft::{
+    MicrosoftAuth, MicrosoftEndpoints, MicrosoftSession, PollPolicy, RefreshDecision, RefreshReason,
+};
+use unlucky_core::auth::Secret;
+
+use crate::support::{AuthMock, MockReply};
+
+const PROFILE_ID: &str = "0f8fad5bd9cb469fa16570867728950e";
+const OTHER_PROFILE_ID: &str = "11111111111111111111111111111111";
+const CLIENT_ID: &str = "test-client-id";
+
+fn auth_for(base: &str) -> MicrosoftAuth {
+    MicrosoftAuth::new(CLIENT_ID)
+        .expect("构造")
+        .with_endpoints(MicrosoftEndpoints::all_on(base))
+        .with_poll_policy(PollPolicy {
+            min_interval: Duration::from_millis(1),
+            slow_down_step: Duration::from_millis(1),
+            max_wait: Duration::from_secs(5),
+        })
+}
+
+/// 一个「已过期」的旧会话（`not_after` 早于当前时刻）。
+fn expired_session() -> MicrosoftSession {
+    MicrosoftSession::new(
+        PROFILE_ID,
+        "Steve",
+        Secret::new("mc-access-token-1"),
+        Secret::new("live-refresh-token-1"),
+        3_600,
+        0,
+        None,
+    )
+}
+
+/// 一个「新鲜」的会话。
+fn fresh_session() -> MicrosoftSession {
+    MicrosoftSession::new(
+        PROFILE_ID,
+        "Steve",
+        Secret::new("mc-access-token-1"),
+        Secret::new("live-refresh-token-1"),
+        86_400,
+        unlucky_core::auth::microsoft::now_ms(),
+        None,
+    )
+}
+
+/// 刷新链（Live refresh + 五步）。
+fn refresh_routes(profile_id: &str, license: bool) -> Vec<(&'static str, Vec<MockReply>)> {
+    vec![
+        (
+            "/token",
+            vec![MockReply::json(json!({
+                "access_token": "live-access-token-2",
+                "refresh_token": "live-refresh-token-2"
+            }))],
+        ),
+        (
+            "/xbl",
+            vec![MockReply::json(json!({
+                "Token": "xbl-token-2",
+                "DisplayClaims": { "xui": [{ "uhs": "uhs-2" }] }
+            }))],
+        ),
+        (
+            "/xsts",
+            vec![MockReply::json(json!({
+                "Token": "xsts-token-2",
+                "DisplayClaims": { "xui": [{ "uhs": "uhs-2" }] }
+            }))],
+        ),
+        (
+            "/login_with_xbox",
+            vec![MockReply::json(json!({
+                "username": "Steve",
+                "access_token": "mc-access-token-2",
+                "expires_in": 86_400
+            }))],
+        ),
+        (
+            "/entitlements/mcstore",
+            vec![MockReply::json(json!({ "items": [] }))],
+        ),
+        (
+            "/entitlements/license",
+            vec![MockReply::json(if license {
+                json!({ "items": [{ "name": "game_minecraft" }] })
+            } else {
+                json!({ "items": [{ "name": "product_minecraft" }] })
+            })],
+        ),
+        (
+            "/profile",
+            vec![MockReply::json(
+                json!({ "id": profile_id, "name": "Steve" }),
+            )],
+        ),
+    ]
+}
+
+#[test]
+fn refresh_decision_table() {
+    let expired = expired_session();
+    assert_eq!(
+        expired.refresh_decision(unlucky_core::auth::microsoft::now_ms()),
+        RefreshDecision::Refresh(RefreshReason::Expired)
+    );
+    let fresh = fresh_session();
+    assert_eq!(
+        fresh.refresh_decision(unlucky_core::auth::microsoft::now_ms()),
+        RefreshDecision::Reuse
+    );
+}
+
+#[tokio::test]
+async fn refresh_rotates_tokens_and_keeps_profile() {
+    let mock = AuthMock::start(refresh_routes(PROFILE_ID, true)).await;
+    let auth = auth_for(&mock.base());
+    let old = expired_session();
+    let (refreshed, reason) = auth.ensure_fresh(&old).await.expect("刷新成功");
+
+    assert_eq!(reason, Some(RefreshReason::Expired));
+    assert_eq!(refreshed.profile_id, PROFILE_ID);
+    // 轮换：access 与 refresh **都**换新（refresh 返回新 refresh_token）。
+    assert_eq!(refreshed.access_token.expose(), "mc-access-token-2");
+    assert_eq!(refreshed.refresh_token.expose(), "live-refresh-token-2");
+    assert_ne!(refreshed.access_token, old.access_token);
+    assert_ne!(refreshed.refresh_token, old.refresh_token);
+    assert!(refreshed.not_after_ms > old.not_after_ms);
+
+    // 刷新报文：拿旧 refresh_token 走 refresh_token grant。
+    let body = &mock.bodies_on("/token")[0];
+    assert!(body.contains("grant_type=refresh_token"), "{body}");
+    assert!(
+        body.contains("refresh_token=live-refresh-token-1"),
+        "{body}"
+    );
+    // 整链重跑：XBL 用的是**新的** Live access token。
+    let xbl = &mock.bodies_on("/xbl")[0];
+    assert!(xbl.contains("d=live-access-token-2"), "{xbl}");
+    mock.stop();
+}
+
+#[tokio::test]
+async fn fresh_session_needs_no_network() {
+    let mock = AuthMock::start(vec![("/token", vec![MockReply::status(500)])]).await;
+    let auth = auth_for(&mock.base());
+    let (session, reason) = auth.ensure_fresh(&fresh_session()).await.expect("直接复用");
+    assert!(reason.is_none());
+    assert_eq!(session.access_token.expose(), "mc-access-token-1");
+    assert!(mock.requests().is_empty(), "不该打网络");
+    mock.stop();
+}
+
+#[tokio::test]
+async fn refresh_that_changes_profile_is_rejected() {
+    let mock = AuthMock::start(refresh_routes(OTHER_PROFILE_ID, true)).await;
+    let auth = auth_for(&mock.base());
+    let error = auth.refresh(&expired_session()).await.expect_err("应拒绝");
+    assert_eq!(error.code(), "malformed");
+    assert!(error.message().contains("档案变了"), "{}", error.message());
+    mock.stop();
+}
+
+#[tokio::test]
+async fn revoked_refresh_token_requires_relogin() {
+    let mock = AuthMock::start(vec![(
+        "/token",
+        vec![MockReply::json_status(
+            400,
+            json!({
+                "error": "invalid_grant",
+                "error_description": "AADSTS70000: The grant is expired or revoked"
+            }),
+        )],
+    )])
+    .await;
+    let auth = auth_for(&mock.base());
+    let error = auth.refresh(&expired_session()).await.expect_err("应失败");
+    assert!(error.is_credential_expired(), "{error:?}");
+    mock.stop();
+}
+
+#[tokio::test]
+async fn validate_reports_token_state_without_swallowing_profile_errors() {
+    // 200 → 有效
+    let ok = AuthMock::start(vec![(
+        "/profile",
+        vec![MockReply::json(
+            json!({ "id": PROFILE_ID, "name": "Steve" }),
+        )],
+    )])
+    .await;
+    assert!(auth_for(&ok.base())
+        .validate(&fresh_session())
+        .await
+        .expect("有效"));
+    ok.stop();
+
+    // 401 → token 失效（返回值，不是错误）
+    let unauthorized = AuthMock::start(vec![("/profile", vec![MockReply::status(401)])]).await;
+    assert!(!auth_for(&unauthorized.base())
+        .validate(&fresh_session())
+        .await
+        .expect("失效"));
+    unauthorized.stop();
+
+    // 404 + 没有 game_minecraft → 「没买游戏」是真实错误，不当 token 失效
+    let no_license = AuthMock::start(vec![
+        ("/profile", vec![MockReply::status(404)]),
+        (
+            "/entitlements/license",
+            vec![MockReply::json(
+                json!({ "items": [{ "name": "product_minecraft" }] }),
+            )],
+        ),
+    ])
+    .await;
+    let error = auth_for(&no_license.base())
+        .validate(&fresh_session())
+        .await
+        .expect_err("应上抛");
+    assert_eq!(error.code(), "denied");
+    assert!(error.message().contains("没有购买"), "{}", error.message());
+    no_license.stop();
+
+    // 404 + 有 game_minecraft → 「买了没建档案」
+    let no_profile = AuthMock::start(vec![
+        ("/profile", vec![MockReply::status(404)]),
+        (
+            "/entitlements/license",
+            vec![MockReply::json(
+                json!({ "items": [{ "name": "game_minecraft" }] }),
+            )],
+        ),
+    ])
+    .await;
+    let error = auth_for(&no_profile.base())
+        .validate(&fresh_session())
+        .await
+        .expect_err("应上抛");
+    assert!(
+        error.message().contains("还没有创建档案"),
+        "{}",
+        error.message()
+    );
+    no_profile.stop();
+}
+
+#[tokio::test]
+async fn missing_entitlement_fails_the_chain_early() {
+    let mut routes = refresh_routes(PROFILE_ID, true);
+    routes[4].1 = vec![MockReply::status(404)];
+    let mock = AuthMock::start(routes).await;
+    let auth = auth_for(&mock.base());
+    let error = auth.refresh(&expired_session()).await.expect_err("应失败");
+    match error {
+        unlucky_core::auth::AuthError::Denied { code, .. } => assert_eq!(code, "no_entitlement"),
+        other => panic!("应是 Denied，实际 {other:?}"),
+    }
+    mock.stop();
+}
+
+#[tokio::test]
+async fn uhs_mismatch_between_xbl_and_xsts_is_malformed() {
+    let mut routes = refresh_routes(PROFILE_ID, true);
+    routes[2].1 = vec![MockReply::json(json!({
+        "Token": "xsts-token-2",
+        "DisplayClaims": { "xui": [{ "uhs": "uhs-diFFERENT" }] }
+    }))];
+    let mock = AuthMock::start(routes).await;
+    let auth = auth_for(&mock.base());
+    let error = auth.refresh(&expired_session()).await.expect_err("应失败");
+    assert_eq!(error.code(), "malformed");
+    assert!(error.message().contains("userhash"), "{}", error.message());
+    mock.stop();
+}
diff --git a/crates/core/tests/auth/offline_uuid.rs b/crates/core/tests/auth/offline_uuid.rs
new file mode 100644
index 0000000..eda7f7e
--- /dev/null
+++ b/crates/core/tests/auth/offline_uuid.rs
@@ -0,0 +1,105 @@
+//! 离线 UUID 与 **JDK 对拍**（这就是「HMCL 兼容」的定义）。
+//!
+//! 期望值不是我们算出来再抄回来的，而是用 JDK 25 跑
+//! `UUID.nameUUIDFromBytes(("OfflinePlayer:" + name).getBytes(UTF_8))`
+//! 生成的（驱动源码见下方注释里的等价 Java）。HMCL 的
+//! `OfflineAccountFactory.getUUIDFromUserName` 就是这一行，因此对拍 JDK 即对拍 HMCL。
+//!
+//! ```java
+//! UUID id = UUID.nameUUIDFromBytes(("OfflinePlayer:" + name).getBytes(StandardCharsets.UTF_8));
+//! System.out.println(id.toString().replace("-", ""));
+//! ```
+
+use unlucky_core::auth::offline::{offline_login, offline_meta, offline_uuid, offline_uuid_dashed};
+use unlucky_core::auth::AccountKind;
+
+/// `(名字, JDK 输出 32 位无连字符)`。
+const JDK_VECTORS: [(&str, &str); 7] = [
+    ("Notch", "b50ad385829d3141a2167e7d7539ba7f"),
+    ("jeb_", "a762f5604fce3236812ab80efff0b62b"),
+    ("Player", "a01e3843e5213998958af459800e4d11"),
+    ("Steve", "5627dd98e6be3c21b8a8e92344183641"),
+    // 非 ASCII：UTF-8 字节参与 MD5（中文名离线服常见）。
+    ("小明", "e1fa999fd9e93419bc012f51157a00e5"),
+    ("name with space", "46c02d33ff53313b813aa95508518305"),
+    ("AskaEth", "5c5918fb61303d6eb8d8eb2d1da6e439"),
+];
+
+#[test]
+fn matches_jdk_name_uuid_from_bytes() {
+    for (name, expected) in JDK_VECTORS {
+        assert_eq!(
+            offline_uuid(name),
+            expected,
+            "离线 UUID 与 JDK/HMCL 不一致：{name}"
+        );
+    }
+}
+
+#[test]
+fn dashed_form_is_the_same_uuid() {
+    for (name, expected) in JDK_VECTORS {
+        let dashed = offline_uuid_dashed(name);
+        assert_eq!(dashed.replace('-', ""), expected, "{name} 的连字符形式");
+        assert_eq!(dashed.len(), 36);
+        assert_eq!(dashed.matches('-').count(), 4);
+    }
+}
+
+#[test]
+fn version_is_3_and_variant_is_ietf() {
+    for (name, raw) in JDK_VECTORS {
+        let version_nibble = &raw[12..13];
+        assert_eq!(version_nibble, "3", "{name} 必须是 v3");
+        let variant = u8::from_str_radix(&raw[16..17], 16).expect("变体位");
+        assert!((0x8..=0xb).contains(&variant), "{name} 变体必须是 10xx");
+    }
+}
+
+#[test]
+fn uuid_depends_on_exact_bytes_not_case() {
+    // 大小写不同 → 不同身份（服务端就是按字节算的，别做「友好」归一化）。
+    assert_ne!(offline_uuid("Steve"), offline_uuid("steve"));
+    // 前缀也参与哈希：直接哈希名字会得到另一个 UUID。
+    assert_ne!(offline_uuid("Notch"), offline_uuid("OfflinePlayer:Notch"));
+}
+
+#[test]
+fn offline_login_matches_hmcl_behaviour() {
+    let meta = offline_meta("小明", 1).expect("建元数据");
+    assert_eq!(meta.kind, AccountKind::Offline);
+    assert_eq!(meta.profile_id, "e1fa999fd9e93419bc012f51157a00e5");
+    assert_eq!(meta.profile_name, "小明");
+
+    let placeholders = offline_login(&meta).expect("占位符");
+    // uuid 必须是**无连字符** 32 位（HMCL 的 UUIDs.toCompactString）。
+    assert_eq!(placeholders.uuid, meta.profile_id);
+    assert_eq!(placeholders.uuid.len(), 32);
+    assert!(!placeholders.uuid.contains('-'));
+    // accessToken = 随机 32 位十六进制（每次不同、非空：游戏不接受空 token）。
+    assert_eq!(placeholders.access_token.len(), 32);
+    assert!(placeholders
+        .access_token
+        .chars()
+        .all(|ch| ch.is_ascii_hexdigit()));
+    assert_ne!(
+        placeholders.access_token,
+        offline_login(&meta).expect("再来一次").access_token
+    );
+    // userType=msa、userProperties={}（承 OfflineAccount.logInWithoutSkin）。
+    assert_eq!(placeholders.user_type, "msa");
+    assert_eq!(placeholders.user_properties, "{}");
+}
+
+#[test]
+fn names_are_validated_before_hashing() {
+    assert!(offline_meta("   ", 1).is_err());
+    assert!(offline_meta("0123456789abcdefg", 1).is_err());
+    // 16 字符刚好合法。
+    assert!(offline_meta("0123456789abcdef", 1).is_ok());
+    // 首尾空白被去掉后哈希（避免「名字带空格」算出两套 UUID）。
+    assert_eq!(
+        offline_meta("  Steve  ", 1).expect("合法").profile_id,
+        offline_uuid("Steve")
+    );
+}
diff --git a/crates/core/tests/auth/store_separation.rs b/crates/core/tests/auth/store_separation.rs
new file mode 100644
index 0000000..cef9a06
--- /dev/null
+++ b/crates/core/tests/auth/store_separation.rs
@@ -0,0 +1,240 @@
+//! 存储契约：**分文件 / 原子写 / 写序 / 容错 / 孤儿清理**。
+//!
+//! 这些是「凭据红线」的落盘侧证据：元数据文件里永远搜不到 token（可安全备份/分享），
+//! 凭据文件只在需要发请求时才读，且写坏了也不会让账户列表整体打不开。
+
+use std::path::Path;
+
+use unlucky_core::auth::account::{AccountKind, AccountMeta, Credentials};
+use unlucky_core::auth::microsoft::MicrosoftSession;
+use unlucky_core::auth::offline::offline_meta;
+use unlucky_core::auth::{AccountStore, Secret};
+
+use crate::support::temp_dir;
+
+const MC_TOKEN: &str = "mc-access-token-value";
+const LIVE_REFRESH: &str = "live-refresh-token-value";
+
+fn microsoft_entry(created_at_ms: u64) -> (AccountMeta, Credentials) {
+    let meta = AccountMeta::new(
+        AccountKind::Microsoft,
+        "0f8fad5bd9cb469fa16570867728950e",
+        "Steve",
+        created_at_ms,
+    );
+    let session = MicrosoftSession::new(
+        "0f8fad5bd9cb469fa16570867728950e",
+        "Steve",
+        Secret::new(MC_TOKEN),
+        Secret::new(LIVE_REFRESH),
+        86_400,
+        1_000,
+        None,
+    );
+    (meta, Credentials::Microsoft(session))
+}
+
+fn read(path: &Path) -> String {
+    std::fs::read_to_string(path).expect("读文件")
+}
+
+fn tmp_leftovers(dir: &Path) -> Vec<String> {
+    std::fs::read_dir(dir)
+        .expect("列目录")
+        .filter_map(|entry| entry.ok())
+        .map(|entry| entry.file_name().to_string_lossy().into_owned())
+        .filter(|name| name.contains(".tmp"))
+        .collect()
+}
+
+#[test]
+fn metadata_and_credentials_live_in_separate_files() {
+    let dir = temp_dir("sep");
+    let mut store = AccountStore::open(&dir);
+    let (meta, credentials) = microsoft_entry(1);
+    store.insert(meta, credentials).expect("插入");
+    store.save().expect("落盘");
+
+    let accounts_text = read(&store.paths().accounts_file());
+    let credentials_text = read(&store.paths().credentials_file());
+
+    // 元数据：有身份、有轨道，但**没有任何 token**。
+    assert!(accounts_text.contains("0f8fad5bd9cb469fa16570867728950e"));
+    assert!(accounts_text.contains("\"kind\": \"microsoft\""));
+    assert!(!accounts_text.contains(MC_TOKEN), "{accounts_text}");
+    assert!(!accounts_text.contains(LIVE_REFRESH), "{accounts_text}");
+    // 凭据：有 token、有保护级别标记，但**没有**可公开的展示字段。
+    assert!(credentials_text.contains(MC_TOKEN));
+    assert!(credentials_text.contains(LIVE_REFRESH));
+    assert!(credentials_text.contains("\"protection\": \"plain-v1\""));
+    // 凭据文件里没有元数据那份「账户列表」结构（两个文件的 schema 各管各的）。
+    assert!(
+        !credentials_text.contains("\"accounts\""),
+        "{credentials_text}"
+    );
+
+    // 原子写不留 tmp 垃圾。
+    assert!(tmp_leftovers(&dir).is_empty(), "残留临时文件");
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn roundtrip_keeps_credentials_intact() {
+    let dir = temp_dir("roundtrip");
+    let mut store = AccountStore::open(&dir);
+    let (meta, credentials) = microsoft_entry(1);
+    let id = meta.id.clone();
+    store.insert(meta, credentials.clone()).expect("插入");
+    store.save().expect("落盘");
+
+    let reopened = AccountStore::open(&dir);
+    assert_eq!(reopened.accounts().len(), 1);
+    assert!(reopened.warnings().is_empty(), "{:?}", reopened.warnings());
+    assert_eq!(reopened.credentials(&id), Some(&credentials));
+    let placeholders = match reopened.credentials(&id).expect("凭据") {
+        Credentials::Microsoft(session) => session.to_placeholders().expect("占位符"),
+        other => panic!("应是微软凭据，实际 {other:?}"),
+    };
+    assert_eq!(placeholders.player_name, "Steve");
+    assert_eq!(placeholders.access_token, MC_TOKEN);
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn credentials_are_written_before_metadata() {
+    let dir = temp_dir("order");
+    let mut store = AccountStore::open(&dir);
+    store
+        .insert(offline_meta("First", 1).expect("甲"), Credentials::Offline)
+        .expect("插入甲");
+    store.save().expect("首次落盘");
+
+    // 把凭据文件的位置换成目录 → 凭据写必定失败。
+    let credentials_path = store.paths().credentials_file();
+    std::fs::remove_file(&credentials_path).expect("删凭据文件");
+    std::fs::create_dir_all(&credentials_path).expect("建同名目录");
+
+    store
+        .insert(offline_meta("Second", 2).expect("乙"), Credentials::Offline)
+        .expect("插入乙");
+    let error = store.save().expect_err("凭据写不进去时 save 必须失败");
+    assert_eq!(error.code(), "store");
+
+    // 关键断言：元数据没有被先写（写序正确才有的结果）。
+    let accounts_text = read(&store.paths().accounts_file());
+    assert!(!accounts_text.contains("Second"), "{accounts_text}");
+    assert!(tmp_leftovers(&dir).is_empty(), "残留临时文件");
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn corrupt_record_is_skipped_not_fatal() {
+    let dir = temp_dir("corrupt");
+    let store = AccountStore::open(&dir);
+    let good = offline_meta("Good", 1).expect("合法元数据");
+    let payload = serde_json::json!({
+        "schemaVersion": 1,
+        "accounts": [
+            { "id": good.id.as_str(), "kind": "offline",
+              "profileId": good.profile_id, "profileName": "Good", "createdAtMs": 1 },
+            { "id": "account:zzzz", "kind": "offline" },
+            { "id": "account:0123456789abcdef0123456789abcdef", "kind": "unknown-track" }
+        ]
+    });
+    std::fs::write(
+        store.paths().accounts_file(),
+        serde_json::to_string_pretty(&payload).expect("序列化"),
+    )
+    .expect("写元数据");
+
+    let reopened = AccountStore::open(&dir);
+    assert_eq!(reopened.accounts().len(), 1, "坏记录必须被跳过");
+    assert_eq!(reopened.accounts()[0].display_name(), "Good");
+    assert_eq!(reopened.warnings().len(), 2, "{:?}", reopened.warnings());
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn broken_metadata_file_still_allows_empty_store() {
+    let dir = temp_dir("broken");
+    let store = AccountStore::open(&dir);
+    std::fs::write(store.paths().accounts_file(), "{ this is not json").expect("写坏文件");
+    let reopened = AccountStore::open(&dir);
+    assert!(reopened.is_empty());
+    assert_eq!(reopened.warnings().len(), 1);
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn orphan_credentials_are_ignored_and_cleaned_on_save() {
+    let dir = temp_dir("orphan");
+    let store = AccountStore::open(&dir);
+    let orphan_id = "account:00000000000000000000000000000000";
+    let payload = serde_json::json!({
+        "schemaVersion": 1,
+        "protection": "plain-v1",
+        "entries": [{ "accountId": orphan_id, "data": { "kind": "offline" } }]
+    });
+    std::fs::write(
+        store.paths().credentials_file(),
+        serde_json::to_string_pretty(&payload).expect("序列化"),
+    )
+    .expect("写凭据");
+
+    let reopened = AccountStore::open(&dir);
+    assert!(reopened
+        .warnings()
+        .iter()
+        .any(|line| line.contains("没有对应账户")));
+    let unknown = unlucky_core::auth::AccountId::parse(orphan_id).expect("id");
+    assert!(reopened.credentials(&unknown).is_none());
+    reopened.save().expect("落盘");
+    let text = read(&reopened.paths().credentials_file());
+    assert!(!text.contains(orphan_id), "{text}");
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn unknown_protection_level_is_reported() {
+    let dir = temp_dir("protection");
+    let store = AccountStore::open(&dir);
+    std::fs::write(
+        store.paths().credentials_file(),
+        serde_json::to_string_pretty(&serde_json::json!({
+            "schemaVersion": 1,
+            "protection": "hmcl-obfuscated-v1",
+            "entries": []
+        }))
+        .expect("序列化"),
+    )
+    .expect("写凭据");
+    let reopened = AccountStore::open(&dir);
+    assert!(reopened
+        .warnings()
+        .iter()
+        .any(|line| line.contains("保护级别")));
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn remove_drops_credential_entry_on_disk() {
+    let dir = temp_dir("remove");
+    let mut store = AccountStore::open(&dir);
+    store
+        .insert(offline_meta("Keep", 1).expect("甲"), Credentials::Offline)
+        .expect("甲");
+    let (meta, credentials) = microsoft_entry(2);
+    let id = meta.id.clone();
+    store.insert(meta, credentials).expect("乙");
+    store.save().expect("落盘");
+
+    store.remove("Steve").expect("删乙");
+    store.save().expect("再落盘");
+    let text = read(&store.paths().credentials_file());
+    assert!(!text.contains(id.as_str()), "{text}");
+
+    let reopened = AccountStore::open(&dir);
+    assert_eq!(reopened.accounts().len(), 1);
+    assert_eq!(reopened.accounts()[0].display_name(), "Keep");
+    let _ = std::fs::remove_dir_all(&dir);
+}
diff --git a/crates/core/tests/auth/support/microsoft.rs b/crates/core/tests/auth/support/microsoft.rs
new file mode 100644
index 0000000..c57190a
--- /dev/null
+++ b/crates/core/tests/auth/support/microsoft.rs
@@ -0,0 +1,136 @@
+//! 微软轨的共用夹具：`MicrosoftAuth` 构造、五步链路由表、诊断断言助手。
+//!
+//! 从 `support/mod.rs` 拆出来（M38）：mock 服务器本体与「业务路由/断言」各自长大，
+//! 分文件后两边都不顶 400 行。路由表默认用 `[0]/[3]/[5]/[6]` 下标对应
+//! `xsts` / `login_with_xbox` / `entitlements/mcstore` / `profile`，用例按需替换。
+
+use serde_json::json;
+use unlucky_core::auth::microsoft::{
+    MicrosoftAuth, MicrosoftEndpoints, MicrosoftSession, PollPolicy,
+};
+use unlucky_core::auth::{AuthError, ResponseDetail, Secret};
+
+use super::MockReply;
+
+/// 测试用档案 UUID（32 位无连字符）。
+pub const PROFILE_ID: &str = "0f8fad5bd9cb469fa16570867728950e";
+/// 测试用 client id。
+pub const CLIENT_ID: &str = "test-client-id";
+/// 网关/风控拦截页（HTML 403 的典型正文）。
+pub const HTML_BLOCK_PAGE: &str = "<!DOCTYPE html><html><head><title>Service unavailable</title></head><body>blocked by gateway</body></html>";
+
+/// 小间隔轮询策略（设备码轮询在测试里要秒级跑完）。
+pub fn fast_poll() -> PollPolicy {
+    PollPolicy {
+        min_interval: std::time::Duration::from_millis(1),
+        slow_down_step: std::time::Duration::from_millis(1),
+        max_wait: std::time::Duration::from_secs(5),
+    }
+}
+
+/// 一台整表指向 mock 的 `MicrosoftAuth`。
+pub fn auth_for(base: &str) -> MicrosoftAuth {
+    MicrosoftAuth::new(CLIENT_ID)
+        .expect("构造")
+        .with_endpoints(MicrosoftEndpoints::all_on(base))
+        .with_poll_policy(fast_poll())
+}
+
+/// 一路通到 `login_with_xbox` 的路由表（后续步骤留给用例替换）。
+pub fn routes_until_login() -> Vec<(&'static str, Vec<MockReply>)> {
+    vec![
+        (
+            "/devicecode",
+            vec![MockReply::json(json!({
+                "user_code": "ABCD-1234",
+                "device_code": "device-code-secret-value",
+                "verification_uri": "https://www.microsoft.com/link",
+                "expires_in": 900,
+                "interval": 0
+            }))],
+        ),
+        (
+            "/token",
+            vec![MockReply::json(json!({
+                "access_token": "live-access-token-value",
+                "refresh_token": "live-refresh-token-value"
+            }))],
+        ),
+        (
+            "/xbl",
+            vec![MockReply::json(json!({
+                "Token": "xbl-token-value",
+                "DisplayClaims": { "xui": [{ "uhs": "uhs-1" }] }
+            }))],
+        ),
+        (
+            "/xsts",
+            vec![MockReply::json(json!({
+                "Token": "xsts-token-value",
+                "DisplayClaims": { "xui": [{ "uhs": "uhs-1" }] }
+            }))],
+        ),
+    ]
+}
+
+/// 整链（含 entitlements 与 profile），便于替换中间任意一步。
+pub fn full_routes() -> Vec<(&'static str, Vec<MockReply>)> {
+    let mut routes = routes_until_login();
+    routes.push((
+        "/login_with_xbox",
+        vec![MockReply::json(json!({
+            "username": "Steve",
+            "access_token": "mc-access-token-value",
+            "expires_in": 86_400
+        }))],
+    ));
+    routes.push((
+        "/entitlements/mcstore",
+        vec![MockReply::json(json!({ "items": [] }))],
+    ));
+    routes.push((
+        "/profile",
+        vec![MockReply::json(
+            json!({ "id": PROFILE_ID, "name": "Steve" }),
+        )],
+    ));
+    routes
+}
+
+/// 一个已过期的旧会话（刷新/校验用例用）。
+pub fn expired_session() -> MicrosoftSession {
+    MicrosoftSession::new(
+        PROFILE_ID,
+        "Steve",
+        Secret::new("mc-access-token-1"),
+        Secret::new("live-refresh-token-1"),
+        3_600,
+        0,
+        None,
+    )
+}
+
+/// 取 `AuthError::Response` 的诊断（不是这个变体就让用例炸掉，报出真实值）。
+pub fn response_of(error: &AuthError) -> &ResponseDetail {
+    match error {
+        AuthError::Response(detail) => detail,
+        other => panic!("应是 Response，实际 {other:?}"),
+    }
+}
+
+/// 断言一段文案/事件里没有任何测试 token。
+pub fn assert_no_credentials(text: &str) {
+    for forbidden in [
+        "xsts-token-value",
+        "xbl-token-value",
+        "live-access-token-value",
+        "live-refresh-token-value",
+        "device-code-secret-value",
+        "mc-access-token-value",
+    ] {
+        assert!(
+            !text.contains(forbidden),
+            "文案泄漏了凭据 {forbidden}：{text}"
+        );
+    }
+}
diff --git a/crates/core/tests/auth/support/mod.rs b/crates/core/tests/auth/support/mod.rs
new file mode 100644
index 0000000..7a32eb4
--- /dev/null
+++ b/crates/core/tests/auth/support/mod.rs
@@ -0,0 +1,279 @@
+//! `core::auth` 集成测试夹具：临时目录 + 进程内 HTTP 服务器（零额外依赖）。
+//!
+//! 为什么要 mock 服务器：微软/authlib 两条轨的正确性全在**报文级**（`XBL3.0 x=<uhs>;<xsts>`
+//! 的拼接、XSTS 401 带 `XErr`、`/minecraft/profile` 404 的二义复判、Yggdrasil 的
+//! `clientToken` 回传校验）——只有把整条链打到一个真实 socket 上，这些分支才被真的跑到。
+//!
+//! 服务器按 **path + 顺序队列**回应答：同一 path 的第 N 次请求用第 N 个应答
+//! （设备码轮询要靠这个：`authorization_pending` → `slow_down` → 成功）。
+//! 微软轨的 `MicrosoftAuth` / 路由表 / 断言助手拆在 [`microsoft`] 子模块里（M38）。
+
+#![allow(dead_code)]
+
+use std::collections::{HashMap, VecDeque};
+use std::net::SocketAddr;
+use std::sync::atomic::{AtomicUsize, Ordering};
+use std::sync::{Arc, Mutex};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+use tokio::net::{TcpListener, TcpStream};
+
+pub mod microsoft;
+pub use microsoft::{
+    assert_no_credentials, auth_for, expired_session, full_routes, response_of, routes_until_login,
+    HTML_BLOCK_PAGE,
+};
+
+/// 唯一临时目录（进程内计数 + 时间戳，避免并行测试互踩）。
+pub fn temp_dir(tag: &str) -> std::path::PathBuf {
+    static COUNTER: AtomicUsize = AtomicUsize::new(0);
+    let unique = COUNTER.fetch_add(1, Ordering::Relaxed);
+    let stamp = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map_or(0, |since| since.as_nanos());
+    let dir = std::env::temp_dir().join(format!("ull-auth-test-{tag}-{stamp}-{unique}"));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).expect("创建临时目录失败");
+    dir
+}
+
+/// 一次 mock 应答。
+#[derive(Debug, Clone)]
+pub struct MockReply {
+    /// HTTP 状态码。
+    pub status: u16,
+    /// 响应体（JSON 文本或空）。
+    pub body: String,
+    /// `Content-Type`（默认 `application/json`；拦截页场景可改成 `text/html`）。
+    pub content_type: &'static str,
+}
+
+impl MockReply {
+    /// 200 + JSON。
+    pub fn json(value: serde_json::Value) -> Self {
+        Self {
+            status: 200,
+            body: value.to_string(),
+            content_type: "application/json",
+        }
+    }
+
+    /// 指定状态码 + JSON。
+    pub fn json_status(status: u16, value: serde_json::Value) -> Self {
+        Self {
+            status,
+            body: value.to_string(),
+            content_type: "application/json",
+        }
+    }
+
+    /// 指定状态码 + 空体。
+    pub fn status(status: u16) -> Self {
+        Self {
+            status,
+            body: String::new(),
+            content_type: "application/json",
+        }
+    }
+
+    /// 指定状态码 + HTML 拦截页（`Content-Type: text/html`）——M38 的网络分流用。
+    pub fn html(status: u16, body: &str) -> Self {
+        Self {
+            status,
+            body: body.to_string(),
+            content_type: "text/html; charset=utf-8",
+        }
+    }
+
+    /// 指定状态码 + 纯文本（网关页的另一种常见形状）。
+    pub fn text(status: u16, body: &str) -> Self {
+        Self {
+            status,
+            body: body.to_string(),
+            content_type: "text/plain",
+        }
+    }
+}
+
+/// 收到的一次请求（断言报文形状用）。
+#[derive(Debug, Clone)]
+pub struct Recorded {
+    /// 方法（大写）。
+    pub method: String,
+    /// 路径（不含 query）。
+    pub path: String,
+    /// 请求体（表单或 JSON 原文）。
+    pub body: String,
+}
+
+/// 进程内 HTTP/1.1 服务器（按 path 排队回应答）。
+pub struct AuthMock {
+    addr: SocketAddr,
+    requests: Arc<Mutex<Vec<Recorded>>>,
+    handle: tokio::task::JoinHandle<()>,
+}
+
+impl AuthMock {
+    /// 启动服务器。`routes` 是 `(path, 该 path 依次使用的应答队列)`。
+    pub async fn start(routes: Vec<(&str, Vec<MockReply>)>) -> Self {
+        let listener = TcpListener::bind("127.0.0.1:0").await.expect("绑定端口");
+        let addr = listener.local_addr().expect("取地址");
+        let requests: Arc<Mutex<Vec<Recorded>>> = Arc::new(Mutex::new(Vec::new()));
+        let queues: Arc<Mutex<HashMap<String, VecDeque<MockReply>>>> = Arc::new(Mutex::new(
+            routes
+                .into_iter()
+                .map(|(path, replies)| (path.to_string(), replies.into()))
+                .collect(),
+        ));
+
+        let recorded = Arc::clone(&requests);
+        let queues_for_task = Arc::clone(&queues);
+        let handle = tokio::spawn(async move {
+            loop {
+                let Ok((stream, _)) = listener.accept().await else {
+                    break;
+                };
+                let recorded = Arc::clone(&recorded);
+                let queues = Arc::clone(&queues_for_task);
+                tokio::spawn(async move {
+                    let _ = serve(stream, recorded, queues).await;
+                });
+            }
+        });
+
+        Self {
+            addr,
+            requests,
+            handle,
+        }
+    }
+
+    /// 基址（喂给 `MicrosoftEndpoints::all_on` / `AuthlibEndpoints` 的根）。
+    pub fn base(&self) -> String {
+        format!("http://{}", self.addr)
+    }
+
+    /// 端口。
+    pub fn port(&self) -> u16 {
+        self.addr.port()
+    }
+
+    /// 已收到的请求（按到达顺序）。
+    pub fn requests(&self) -> Vec<Recorded> {
+        self.requests
+            .lock()
+            .unwrap_or_else(|error| error.into_inner())
+            .clone()
+    }
+
+    /// 找某 path 的请求体列表。
+    pub fn bodies_on(&self, path: &str) -> Vec<String> {
+        self.requests()
+            .into_iter()
+            .filter(|request| request.path == path)
+            .map(|request| request.body)
+            .collect()
+    }
+
+    /// 关停。
+    pub fn stop(self) {
+        self.handle.abort();
+    }
+}
+
+async fn serve(
+    mut stream: TcpStream,
+    recorded: Arc<Mutex<Vec<Recorded>>>,
+    queues: Arc<Mutex<HashMap<String, VecDeque<MockReply>>>>,
+) -> std::io::Result<()> {
+    let mut buffer = Vec::new();
+    let mut chunk = [0_u8; 2048];
+    // 读头
+    let header_end = loop {
+        let read = stream.read(&mut chunk).await?;
+        if read == 0 {
+            return Ok(());
+        }
+        buffer.extend_from_slice(&chunk[..read]);
+        if let Some(position) = find_headers_end(&buffer) {
+            break position;
+        }
+    };
+    let head = String::from_utf8_lossy(&buffer[..header_end]).to_string();
+    let content_length = head
+        .lines()
+        .find_map(|line| {
+            let (name, value) = line.split_once(':')?;
+            if name.trim().eq_ignore_ascii_case("content-length") {
+                value.trim().parse::<usize>().ok()
+            } else {
+                None
+            }
+        })
+        .unwrap_or(0);
+    while buffer.len() < header_end + content_length {
+        let read = stream.read(&mut chunk).await?;
+        if read == 0 {
+            break;
+        }
+        buffer.extend_from_slice(&chunk[..read]);
+    }
+    let body = String::from_utf8_lossy(
+        &buffer[header_end..(header_end + content_length).min(buffer.len())],
+    )
+    .to_string();
+
+    let mut first_line = head.lines().next().unwrap_or_default().split(' ');
+    let method = first_line.next().unwrap_or_default().to_ascii_uppercase();
+    let raw_path = first_line.next().unwrap_or("/");
+    let path = raw_path.split('?').next().unwrap_or("/").to_string();
+
+    recorded
+        .lock()
+        .unwrap_or_else(|error| error.into_inner())
+        .push(Recorded {
+            method,
+            path: path.clone(),
+            body,
+        });
+
+    let reply = queues
+        .lock()
+        .unwrap_or_else(|error| error.into_inner())
+        .get_mut(&path)
+        .and_then(VecDeque::pop_front)
+        .unwrap_or_else(|| MockReply::status(500));
+
+    let mut response = format!(
+        "HTTP/1.1 {} {}\r\nContent-Type: {}\r\nContent-Length: {}\r\nConnection: close\r\n\r\n",
+        reply.status,
+        reason(reply.status),
+        reply.content_type,
+        reply.body.len()
+    )
+    .into_bytes();
+    response.extend_from_slice(reply.body.as_bytes());
+    stream.write_all(&response).await?;
+    stream.flush().await?;
+    Ok(())
+}
+
+fn find_headers_end(buffer: &[u8]) -> Option<usize> {
+    buffer
+        .windows(4)
+        .position(|window| window == b"\r\n\r\n")
+        .map(|position| position + 4)
+}
+
+fn reason(status: u16) -> &'static str {
+    match status {
+        200 => "OK",
+        400 => "Bad Request",
+        401 => "Unauthorized",
+        403 => "Forbidden",
+        404 => "Not Found",
+        500 => "Internal Server Error",
+        _ => "Status",
+    }
+}
diff --git a/crates/core/tests/diagnose/collectors_probe.rs b/crates/core/tests/diagnose/collectors_probe.rs
new file mode 100644
index 0000000..1c81c7e
--- /dev/null
+++ b/crates/core/tests/diagnose/collectors_probe.rs
@@ -0,0 +1,233 @@
+//! 五类信号采集：环形缓冲语义 / 退出码分类 / 磁盘采集器 / 引擎输入拼装。
+
+use std::fs;
+use std::time::{Duration, SystemTime};
+
+use crate::prelude::*;
+
+#[test]
+fn log_buffer_keeps_key_lines_when_evicted() {
+    let mut buffer = LogBuffer::new(2);
+    buffer.push(SignalOrigin::Stdout, "java.lang.Exception: boom");
+    buffer.push(SignalOrigin::Stdout, "line 2");
+    buffer.push(SignalOrigin::Stdout, "line 3");
+    buffer.push(SignalOrigin::Stderr, "line 4");
+
+    assert_eq!(buffer.pushed(), 4);
+    assert_eq!(buffer.dropped(), 2);
+    assert_eq!(buffer.kept_key_lines(), 1, "关键行被淘汰后仍应保留");
+    assert_eq!(buffer.len(), 3, "保留 1 行关键历史 + 环形区 2 行");
+    let text = buffer.text();
+    assert!(text.contains("boom"), "根因行不该被挤出缓冲区");
+    assert!(text.contains("line 4"));
+    assert!(!text.contains("line 2"));
+    assert!(!buffer.is_empty());
+}
+
+#[test]
+fn exit_types_match_launch_contract() {
+    // 字符串值与 launch-接口约定.md §3 exit.exit_type 完全一致
+    let kill = ExitSignal::classify(Some(137), Some(60_000), 0, "");
+    assert_eq!(kill.exit_type, ExitType::Sigkill);
+    assert_eq!(kill.exit_type.as_str(), "sigkill");
+    assert_eq!(ExitType::from_name("sigkill"), ExitType::Sigkill);
+
+    let term = ExitSignal::classify(Some(143), Some(60_000), 1, "");
+    assert_eq!(term.exit_type, ExitType::Sigterm);
+
+    let jvm = ExitSignal::classify(
+        Some(1),
+        Some(800),
+        2,
+        "Error occurred during initialization of VM\nCould not create the Java Virtual Machine",
+    );
+    assert_eq!(jvm.exit_type, ExitType::JvmError);
+    assert!(!jvm.silent_failure);
+
+    let normal = ExitSignal::classify(Some(0), Some(600_000), 0, "Game started fine");
+    assert_eq!(normal.exit_type, ExitType::Normal);
+    assert!(!normal.silent_failure);
+    assert!(normal.status_hex().is_none());
+
+    // exit 0 + 短命 + 有错误行 → 静默失败（HMCL 会判 NORMAL 放过）
+    let silent = ExitSignal::classify(Some(0), Some(5_000), 4, "java.lang.Exception: boom");
+    assert_eq!(silent.exit_type, ExitType::Normal);
+    assert!(silent.silent_failure);
+
+    // Windows 访问违例：负的 i32 → 十六进制状态码
+    let access = ExitSignal::classify(Some(-1_073_741_819), Some(90_000), 0, "");
+    assert!(access.is_access_violation());
+    assert_eq!(access.status_hex().as_deref(), Some("0xc0000005"));
+
+    for exit_type in [
+        ExitType::Normal,
+        ExitType::ApplicationError,
+        ExitType::JvmError,
+        ExitType::Sigkill,
+        ExitType::Sigterm,
+        ExitType::Killed,
+        ExitType::Interrupted,
+    ] {
+        assert_eq!(ExitType::from_name(exit_type.as_str()), exit_type);
+    }
+}
+
+#[test]
+fn crash_report_collector_reads_newest_and_honours_started_at() {
+    let run_dir = temp_dir("collect-crash");
+    let reports = run_dir.join("crash-reports");
+    fs::create_dir_all(&reports).expect("建目录");
+    fs::write(
+        reports.join("crash-2026-10-29_12.00.00-client.txt"),
+        "---- Minecraft Crash Report ----\nDescription: Example\n",
+    )
+    .expect("写崩溃报告");
+
+    let collector = CrashReportCollector::new();
+    let collectors: [&dyn SignalCollector; 1] = [&collector];
+    let (bundle, errors) = collect_all(&collectors, &CollectionContext::new(&run_dir));
+    assert!(errors.is_empty());
+    let captured = bundle.crash_report.expect("应采到崩溃报告");
+    assert!(captured.text.contains("Description: Example"));
+    assert_eq!(bundle.sources.len(), 1);
+
+    // 只要「本次会话之后」的文件：把下界设到未来 → 不采
+    let future =
+        CollectionContext::new(&run_dir).since(SystemTime::now() + Duration::from_secs(3_600));
+    let (bundle, errors) = collect_all(&collectors, &future);
+    assert!(errors.is_empty());
+    assert!(bundle.crash_report.is_none(), "历史崩溃不该算进本次");
+}
+
+#[test]
+fn hs_err_collector_parses_newest_file() {
+    let run_dir = temp_dir("collect-hs-err");
+    fs::write(
+        run_dir.join("hs_err_pid4242.log"),
+        "#\n# A fatal error has been detected by the Java Runtime Environment:\n#\n#  EXCEPTION_ACCESS_VIOLATION (0xc0000005) at pc=0x1, pid=4242, tid=0x2\n# Problematic frame:\n# C  [nvoglv64.dll+0x10]\n",
+    )
+    .expect("写 hs_err");
+
+    let collector = HsErrCollector::new();
+    let collectors: [&dyn SignalCollector; 1] = [&collector];
+    let (bundle, errors) = collect_all(&collectors, &CollectionContext::new(&run_dir));
+    assert!(errors.is_empty());
+    let report = bundle.hs_err.expect("应解析 hs_err");
+    assert_eq!(report.kind, HsErrKind::AccessViolation);
+    assert_eq!(report.pid, Some(4242));
+    assert_eq!(bundle.sources.len(), 1);
+}
+
+#[test]
+fn latest_log_collector_tails_n_lines() {
+    let run_dir = temp_dir("collect-latest");
+    let logs = run_dir.join("logs");
+    fs::create_dir_all(&logs).expect("建目录");
+    let mut text = String::new();
+    for index in 0..10 {
+        text.push_str(&format!("line {index}\n"));
+    }
+    fs::write(logs.join("latest.log"), text).expect("写日志");
+
+    let collector = LatestLogCollector::new().with_max_lines(4);
+    let collectors: [&dyn SignalCollector; 1] = [&collector];
+    let (bundle, errors) = collect_all(&collectors, &CollectionContext::new(&run_dir));
+    assert!(errors.is_empty());
+    assert_eq!(bundle.log.pushed(), 4);
+    assert!(bundle.log.text().contains("line 9"));
+    assert!(!bundle.log.text().contains("line 5"));
+}
+
+#[test]
+fn collect_all_aggregates_pushed_and_disk_signals() {
+    let run_dir = temp_dir("collect-all");
+    let reports = run_dir.join("crash-reports");
+    fs::create_dir_all(&reports).expect("建目录");
+    fs::write(
+        reports.join("crash-a.txt"),
+        "---- Minecraft Crash Report ----\n",
+    )
+    .expect("写报告");
+
+    let snapshot = EnvironmentSnapshot {
+        java_major: Some(17),
+        java_bits: Some(64),
+        xmx_mb: Some(4096),
+        physical_memory_mb: Some(16_384),
+        mods: vec![ModRecord::from_file_name("sodium-fabric-0.5.8.jar")],
+        components: vec![unlucky_core::diagnose::collectors::ComponentVersion::new(
+            "fabric", "0.15.0",
+        )],
+        ..EnvironmentSnapshot::default()
+    };
+
+    let exit = ExitCollector::new(ExitSignal::classify(Some(1), Some(9_000), 1, "boom"));
+    let environment = EnvironmentCollector::new(snapshot);
+    let crash = CrashReportCollector::new();
+    let hs_err = HsErrCollector::new();
+    let collectors: [&dyn SignalCollector; 4] = [&exit, &environment, &crash, &hs_err];
+
+    let (bundle, errors) = collect_all(&collectors, &CollectionContext::new(&run_dir));
+    assert!(errors.is_empty(), "单源缺失不应报错：{errors:?}");
+    assert!(bundle.exit.is_some());
+    assert!(bundle.crash_report.is_some());
+    assert!(
+        bundle.hs_err.is_none(),
+        "没有 hs_err 文件时是 None（不是错误）"
+    );
+    let snapshot = bundle.environment.as_ref().expect("环境快照");
+    assert_eq!(snapshot.java_major, Some(17));
+    assert!(snapshot.summary().contains("Java 17"));
+    assert_eq!(bundle.mods.len(), 1);
+    assert!(bundle.mods[0].enabled);
+    assert!(!bundle.is_empty());
+}
+
+#[test]
+fn mod_record_parses_file_name() {
+    let record = ModRecord::from_file_name("jei-1.20.1-15.2.0.27.jar");
+    assert_eq!(record.id, "jei-1.20.1");
+    assert_eq!(record.version.as_deref(), Some("15.2.0.27"));
+    assert!(record.enabled);
+
+    let disabled = ModRecord::from_file_name("optifine.jar.disabled");
+    assert!(!disabled.enabled);
+    assert_eq!(disabled.id, "optifine");
+}
+
+#[test]
+fn bundle_input_groups_log_by_origin_and_carries_hs_err() {
+    let mut bundle = SignalBundle::new();
+    bundle.log.push(SignalOrigin::Stdout, "stdout line");
+    bundle.log.push(SignalOrigin::Stderr, "stderr line");
+    bundle.exit = Some(ExitSignal::classify(Some(1), Some(1_000), 1, "boom"));
+
+    let input = bundle.diagnosis_input();
+    assert!(input.exit.is_some());
+    let origins = input
+        .haystacks
+        .iter()
+        .map(|haystack| haystack.origin)
+        .collect::<Vec<_>>();
+    assert!(origins.contains(&SignalOrigin::Stdout));
+    assert!(origins.contains(&SignalOrigin::Stderr));
+    assert!(!input.is_empty());
+
+    let mut with_hs_err = SignalBundle::new();
+    with_hs_err.hs_err = Some(hs_err::parse(&read_sample(
+        "samples/hs_err/access_violation.log",
+    )));
+    let input = with_hs_err.diagnosis_input();
+    assert!(input.hs_err.is_some());
+    assert!(input
+        .haystacks
+        .iter()
+        .any(|haystack| haystack.origin == SignalOrigin::HsErr));
+}
+
+#[test]
+fn empty_bundle_produces_empty_input() {
+    let bundle = SignalBundle::new();
+    assert!(bundle.is_empty());
+    assert!(bundle.diagnosis_input().is_empty());
+}
diff --git a/crates/core/tests/diagnose/engine_rank.rs b/crates/core/tests/diagnose/engine_rank.rs
new file mode 100644
index 0000000..636e63f
--- /dev/null
+++ b/crates/core/tests/diagnose/engine_rank.rs
@@ -0,0 +1,233 @@
+//! 引擎行为：主因排序 / 抑制关系 / 去重 / 内置结论 / 动作物化。
+
+use crate::prelude::*;
+
+#[test]
+fn root_cause_outranks_secondary_error() {
+    // 一条日志里既 OOM 又 NoClassDefFoundError：OOM 是根因（priority 80 vs 40）。
+    let text = "\
+java.lang.OutOfMemoryError: Java heap space
+java.lang.NoClassDefFoundError: net/minecraftforge/fml/loading/FMLEnvironment
+";
+    let report = analyze_text(SignalOrigin::Stdout, text);
+    assert_eq!(
+        report.primary().expect("命中").rule_id,
+        "memory.out_of_memory"
+    );
+    assert!(
+        ids(&report).contains(&"integrity.no_class_def_found"),
+        "低级错误也应给出（哪怕是次生）：{:?}",
+        ids(&report)
+    );
+}
+
+#[test]
+fn suppress_moves_rule_into_secondary() {
+    // 32 位 Java 分配失败 + 次生 OutOfMemoryError
+    let text = "\
+Could not reserve enough space for 4194304KB object heap
+java.lang.OutOfMemoryError: Java heap space
+";
+    let report = analyze_text(SignalOrigin::Stdout, text);
+    assert_eq!(report.primary().expect("命中").rule_id, "jvm.32bit");
+    let secondary = report
+        .secondary
+        .iter()
+        .find(|finding| finding.rule_id == "memory.out_of_memory")
+        .expect("OOM 应被降级为次生结论而不是丢弃");
+    assert_eq!(secondary.suppressed_by.as_deref(), Some("jvm.32bit"));
+    assert!(
+        !ids(&report).contains(&"memory.out_of_memory"),
+        "被抑制的结论不应出现在主因列表"
+    );
+}
+
+#[test]
+fn same_rule_keeps_best_evidence_source() {
+    // 同一条文本在两个来源出现：只留一条结论，且优先崩溃报告。
+    let mut input = DiagnosisInput::new();
+    input.push_text(
+        SignalOrigin::Stdout,
+        "java.lang.OutOfMemoryError: Java heap space",
+    );
+    input.push_text(
+        SignalOrigin::CrashReport,
+        "---- Minecraft Crash Report ----\njava.lang.OutOfMemoryError: Java heap space",
+    );
+    let report = diagnoser().analyze(&input);
+    let hits = report
+        .findings
+        .iter()
+        .filter(|finding| finding.rule_id == "memory.out_of_memory")
+        .count();
+    assert_eq!(hits, 1, "同一规则只应报一次");
+    let finding = &report.findings[0];
+    assert_eq!(finding.evidence[0].origin, SignalOrigin::CrashReport);
+}
+
+#[test]
+fn access_violation_exit_is_diagnosed() {
+    let exit = ExitSignal::classify(Some(-1_073_741_819), Some(90_000), 0, "");
+    let mut input = DiagnosisInput::new();
+    input.exit = Some(exit);
+    let report = diagnoser().analyze(&input);
+    let finding = report
+        .findings
+        .iter()
+        .find(|finding| finding.rule_id == "signal.access_violation")
+        .expect("0xC0000005 应产出内置结论");
+    assert_eq!(finding.category, RuleCategory::Graphics);
+    let action = &finding.materialized_actions()[0];
+    assert_eq!(action.kind, FixActionKind::ChangeGraphics);
+    assert_eq!(action.tool, "graphics.set");
+    assert_eq!(
+        action.args.get("update_driver").map(String::as_str),
+        Some("true")
+    );
+}
+
+#[test]
+fn silent_failure_is_marked_on_exit_zero() {
+    // analyse/02 §7.10-10：exit 0 + 存活 <30s + 有错误行 → 静默失败，HMCL 会判 NORMAL 放过。
+    let exit = ExitSignal::classify(Some(0), Some(4_200), 3, "java.lang.Exception: boom");
+    assert_eq!(exit.exit_type, ExitType::Normal);
+    assert!(exit.silent_failure);
+    let mut input = DiagnosisInput::new();
+    input.exit = Some(exit);
+    let report = diagnoser().analyze(&input);
+    assert!(
+        ids(&report).contains(&"signal.silent_failure"),
+        "静默失败应单独打标：{:?}",
+        ids(&report)
+    );
+    // 低置信 → 交 AI 深化（PlanDoc/06 §2.3）
+    assert!(report.needs_more_info());
+}
+
+#[test]
+fn empty_input_asks_for_more_information() {
+    let report = diagnoser().analyze(&DiagnosisInput::new());
+    assert!(report.findings.is_empty());
+    assert!(report.needs_more_info());
+}
+
+#[test]
+fn conflict_rule_materializes_capture_groups() {
+    let text = read_sample("samples/fabric/mod_resolution_conflict.log");
+    let report = analyze_text(SignalOrigin::Stdout, &text);
+    let primary = report.primary().expect("命中");
+    assert_eq!(primary.rule_id, "fabric.mod_resolution_conflict");
+    let action = &primary.materialized_actions()[0];
+    assert_eq!(action.kind, FixActionKind::RemoveMod);
+    assert_eq!(action.tool, "mod.remove");
+    assert_eq!(
+        action.args.get("mod_ids").map(String::as_str),
+        Some("sodium,sodium-extra"),
+        "mod_ids 应已代入命名捕获组"
+    );
+}
+
+/// 回归（review P2-1）：OptiFine/Forge 兼容规则最后一个 alternative 必须是**前缀语义**，
+/// 既收裸 `(Reflector.java)` 也收真实的带行号形态 `(Reflector.java:455)`。
+#[test]
+fn optifine_forge_matches_both_frame_forms() {
+    for frame in [
+        "\tTRANSFORMER/net.optifine/net.optifine.reflect.Reflector.<clinit>(Reflector.java:455)",
+        "\tTRANSFORMER/net.optifine/net.optifine.reflect.Reflector.<clinit>(Reflector.java)",
+    ] {
+        let report = analyze_text(SignalOrigin::Stdout, frame);
+        assert!(
+            ids(&report).contains(&"conflict.optifine_forge"),
+            "真实栈帧形态应命中：{frame}（实际命中：{:?}）",
+            ids(&report)
+        );
+    }
+}
+
+#[test]
+fn too_old_java_converts_class_file_version() {
+    let text = read_sample("samples/jvm/too_old_java.log");
+    let report = analyze_text(SignalOrigin::Stdout, &text);
+    let primary = report.primary().expect("命中");
+    assert_eq!(primary.rule_id, "jvm.too_old_java");
+    let action = &primary.materialized_actions()[0];
+    assert_eq!(
+        action.args.get("required_major").map(String::as_str),
+        Some("17"),
+        "class file version 61 应换算成 Java 17"
+    );
+    assert_eq!(class_file_to_java_major(61), Some(17));
+    assert_eq!(class_file_to_java_major(52), Some(8));
+    assert_eq!(class_file_to_java_major(40), None);
+}
+
+#[test]
+fn fix_actions_are_deduplicated_across_findings() {
+    // 一条日志同时命中 OOM（adjust_memory）与 32bit（adjust_memory + change_java）
+    let text = "\
+Could not reserve enough space for 4194304KB object heap
+java.lang.OutOfMemoryError: Java heap space
+";
+    let report = analyze_text(SignalOrigin::Stdout, text);
+    let actions = report.fix_actions();
+    assert!(!actions.is_empty());
+    let mut unique = actions.clone();
+    unique.sort_by(|a, b| a.tool.cmp(b.tool).then(a.args.len().cmp(&b.args.len())));
+    unique.dedup();
+    assert_eq!(unique.len(), actions.len(), "fix_actions 应当已去重");
+}
+
+#[test]
+fn record_matches_launch_diagnosis_payload() {
+    let text = read_sample("samples/memory/out_of_memory.log");
+    let report = analyze_text(SignalOrigin::Stdout, &text);
+    let record = report.to_record();
+    assert_eq!(record.source, "rules");
+    assert!(!record.candidates.is_empty());
+    let candidate = &record.candidates[0];
+    assert_eq!(candidate.id, "memory.out_of_memory");
+    assert_eq!(candidate.severity, "critical");
+    assert_eq!(candidate.category, "memory");
+    assert_eq!(candidate.message_key, "diagnose.cause.memory.out_of_memory");
+    assert!(!candidate.message.is_empty(), "M16 需要渲染后的中文结论");
+    assert!(!candidate.evidence.is_empty());
+    assert_eq!(candidate.fix_actions[0].tool, "memory.set");
+}
+
+#[test]
+fn hs_err_report_feeds_builtin_findings() {
+    let report = hs_err::parse(&read_sample("samples/hs_err/access_violation.log"));
+    let mut input = DiagnosisInput::new();
+    input.push_hs_err(report);
+    let analysis = diagnoser().analyze(&input);
+    assert_eq!(
+        analysis.primary().expect("命中").rule_id,
+        "hs_err.access_violation"
+    );
+    // graphics.graphics_driver 会被内置结论 suppress 成次生（同一条证据、不同粒度）
+    assert!(
+        analysis
+            .secondary
+            .iter()
+            .any(|finding| finding.rule_id == "graphics.graphics_driver"),
+        "hs_err 原文也应命中图形规则，但被降级：{:?}",
+        analysis
+            .secondary
+            .iter()
+            .map(|finding| finding.rule_id.as_str())
+            .collect::<Vec<_>>()
+    );
+}
+
+#[test]
+fn file_scope_rules_survive_very_long_logs() {
+    // >1 MiB：首尾窗口扫描，尾部窗口里的签名仍应命中。
+    let mut text = String::from("noise line\n").repeat(120_000);
+    text.push_str("java.lang.OutOfMemoryError: Java heap space\n");
+    assert!(text.len() > 1024 * 1024);
+    let report = analyze_text(SignalOrigin::LatestLog, &text);
+    assert!(
+        ids(&report).contains(&"memory.out_of_memory"),
+        "超长日志的尾部窗口应被扫描"
+    );
+}
diff --git a/crates/core/tests/diagnose/hs_err_parse.rs b/crates/core/tests/diagnose/hs_err_parse.rs
new file mode 100644
index 0000000..a6df686
--- /dev/null
+++ b/crates/core/tests/diagnose/hs_err_parse.rs
@@ -0,0 +1,143 @@
+//! `hs_err_pid*.log` 解析器：标题行 / 线程段 / 内存段 / 失败帧。
+
+use crate::prelude::*;
+
+#[test]
+fn parses_access_violation_report() {
+    let text = read_sample("samples/hs_err/access_violation.log");
+    let report = hs_err::parse(&text);
+
+    assert_eq!(report.kind, HsErrKind::AccessViolation);
+    assert_eq!(
+        report.header.as_deref(),
+        Some("A fatal error has been detected by the Java Runtime Environment:")
+    );
+    assert_eq!(
+        report.exception.as_deref(),
+        Some("EXCEPTION_ACCESS_VIOLATION (0xc0000005)")
+    );
+    assert_eq!(report.pc.as_deref(), Some("0x00007ffb1a2b3c4d"));
+    assert_eq!(report.pid, Some(12344));
+    assert_eq!(report.tid.as_deref(), Some("0x0000000000002a1c"));
+
+    let frame = report.failed_frame.as_ref().expect("失败帧");
+    assert_eq!(frame.kind, FrameKind::Native);
+    assert_eq!(frame.module.as_deref(), Some("ig8d64.dll"));
+    assert_eq!(frame.offset.as_deref(), Some("0x9b3c4d"));
+
+    let thread = report.current_thread.as_deref().expect("当前线程");
+    assert!(thread.contains("Render thread"), "{thread}");
+    assert!(report
+        .jre_version
+        .as_deref()
+        .is_some_and(|line| line.contains("8.0_51")));
+    assert!(report
+        .java_vm
+        .as_deref()
+        .is_some_and(|line| line.contains("HotSpot")));
+
+    let memory = report.memory.as_ref().expect("内存段");
+    assert_eq!(memory.page_size.as_deref(), Some("4k"));
+    assert_eq!(memory.physical_kb, Some(16_741_480));
+    assert_eq!(memory.physical_free_kb, Some(4_716_856));
+    assert_eq!(memory.swap_kb, Some(18_672_384));
+    assert_eq!(memory.swap_free_kb, Some(9_433_608));
+    assert!(memory.summary().contains("GB"));
+
+    assert!(!report.heap.is_empty(), "Heap 段应被抽取");
+    assert!(report
+        .vm_arguments
+        .iter()
+        .any(|arg| arg.contains("-Xmx4096m")));
+    assert!(report
+        .command_line
+        .as_deref()
+        .is_some_and(|line| line.contains("net.minecraft.launchwrapper.Launch")));
+}
+
+#[test]
+fn digest_keeps_header_block_for_cross_line_rules() {
+    let report = hs_err::parse(&read_sample("samples/hs_err/access_violation.log"));
+    let digest = report.digest();
+    // 跨行图形规则依赖「EXCEPTION_ACCESS_VIOLATION … # C  [ig…」的相对位置
+    assert!(digest.contains("EXCEPTION_ACCESS_VIOLATION"));
+    assert!(digest.contains("# C  [ig8d64.dll"));
+    assert!(digest.contains("Current thread"));
+    assert!(digest.contains("Memory:"));
+}
+
+#[test]
+fn parses_out_of_memory_report() {
+    let report = hs_err::parse(&read_sample("samples/hs_err/out_of_memory.log"));
+    assert_eq!(report.kind, HsErrKind::OutOfMemory);
+    assert_eq!(report.pid, Some(9876));
+    assert_eq!(
+        report.exception, None,
+        "OOM 型 hs_err 没有 EXCEPTION_* 行，不该瞎猜"
+    );
+    assert!(report
+        .header
+        .as_deref()
+        .is_some_and(|header| header.contains("insufficient memory")));
+    let memory = report.memory.as_ref().expect("内存段");
+    assert_eq!(memory.physical_kb, Some(8_134_564));
+    assert!(report.summary().contains("out_of_memory"));
+}
+
+#[test]
+fn parse_never_fails_on_garbage() {
+    for text in ["", "\n\n", "随便一段中文", "#  EXCEPTION_ACCESS_VIOLATION"] {
+        let report = hs_err::parse(text);
+        // 不 panic 即可；字段可以全空
+        let _ = report.digest();
+        let _ = report.summary();
+    }
+    assert_eq!(hs_err::parse("").kind, HsErrKind::Other);
+}
+
+#[test]
+fn parse_file_attaches_path() {
+    let path = rules_dir().join("samples/hs_err/access_violation.log");
+    let report = hs_err::parse_file(&path).expect("读文件");
+    assert_eq!(report.path.as_deref(), Some(path.as_path()));
+    assert_eq!(report.kind, HsErrKind::AccessViolation);
+}
+
+#[test]
+fn missing_file_is_an_io_error() {
+    let path = temp_dir("hs-err-missing").join("hs_err_pid1.log");
+    assert!(hs_err::parse_file(&path).is_err());
+}
+
+#[test]
+fn java_frame_is_classified() {
+    let text = "\
+#  EXCEPTION_ACCESS_VIOLATION (0xc0000005) at pc=0x0000000000000000, pid=1, tid=0x2
+# Problematic frame:
+# J 123 c1 com.example.mod.Foo.bar(Ljava/lang/String;)V (12 bytes) @ 0x00007ffb
+";
+    let report = hs_err::parse(text);
+    let frame = report.failed_frame.as_ref().expect("失败帧");
+    assert_eq!(frame.kind, FrameKind::Java);
+    assert_eq!(frame.module, None);
+}
+
+#[test]
+fn engine_reports_hs_err_out_of_memory() {
+    let report = hs_err::parse(&read_sample("samples/hs_err/out_of_memory.log"));
+    let mut input = DiagnosisInput::new();
+    input.push_hs_err(report);
+    let analysis = diagnoser().analyze(&input);
+    let finding = analysis
+        .findings
+        .iter()
+        .find(|finding| finding.rule_id == "hs_err.out_of_memory")
+        .expect("hs_err OOM 应产出内置结论");
+    assert_eq!(finding.category, RuleCategory::Memory);
+    assert!(finding.message.contains("内存不足"));
+    assert_eq!(
+        finding.materialized_actions()[0].tool,
+        "memory.set",
+        "M16 需要能直接执行的工具 id"
+    );
+}
diff --git a/crates/core/tests/diagnose/loader_reload.rs b/crates/core/tests/diagnose/loader_reload.rs
new file mode 100644
index 0000000..f402a34
--- /dev/null
+++ b/crates/core/tests/diagnose/loader_reload.rs
@@ -0,0 +1,171 @@
+//! 规则库加载 / 热重载 / 坏文件的降级行为。
+
+use std::fs;
+
+use crate::prelude::*;
+
+const CUSTOM_MEMORY: &str = "\
+version: 1
+category: memory
+rules:
+  - id: memory.custom_only
+    severity: warning
+    pattern: 'CUSTOM TEST SIGNATURE'
+    confidence: 0.9
+    priority: 70
+    cause:
+      key: diagnose.cause.memory.custom_only
+      summary: '测试用自定义规则'
+    fix_action:
+      - kind: seek_help
+    sample: samples/memory/out_of_memory.log
+";
+
+#[test]
+fn embedded_library_is_complete() {
+    let loader = RuleLoader::embedded();
+    assert_eq!(EMBEDDED_RULES.len(), 10, "10 个根因分组各一个 YAML");
+    // 64 = HMCL 59 条全量平移 + 5 条 Vulkan 组（graphics.yaml 末尾的 4 个原因码
+    // + no_graphics_backend）。加规则要同时加样本并同步这个数。
+    assert_eq!(loader.rules().len(), 64);
+    assert!(loader.last_errors().is_empty());
+    assert!(loader.dir().is_none());
+}
+
+#[test]
+fn missing_directory_falls_back_to_embedded() {
+    let dir = temp_dir("loader-missing").join("nope");
+    let loader = RuleLoader::from_dir(&dir);
+    assert_eq!(loader.rules().len(), 64);
+    assert!(loader.last_errors().is_empty());
+}
+
+#[test]
+fn disk_file_replaces_embedded_group() {
+    let dir = temp_dir("loader-override");
+    fs::write(dir.join("memory.yaml"), CUSTOM_MEMORY).expect("写规则文件");
+    let loader = RuleLoader::from_dir(&dir);
+
+    assert_eq!(loader.rules().len(), 63, "memory.yaml 的 2 条被 1 条替换");
+    assert!(loader.last_errors().is_empty());
+    assert!(loader.rule_set().get("memory.custom_only").is_some());
+    assert!(
+        loader.rule_set().get("memory.out_of_memory").is_none(),
+        "同组文件被整份替换"
+    );
+}
+
+#[test]
+fn refresh_picks_up_edits() {
+    let dir = temp_dir("loader-refresh");
+    let mut loader = RuleLoader::from_dir(&dir);
+    assert_eq!(
+        loader.refresh(),
+        ReloadOutcome::Unchanged,
+        "没变就不该重解析"
+    );
+
+    fs::write(dir.join("memory.yaml"), CUSTOM_MEMORY).expect("写规则文件");
+    assert_eq!(
+        loader.refresh(),
+        ReloadOutcome::Reloaded { rules: 63 },
+        "指纹变了应重新加载"
+    );
+    assert!(loader.rule_set().get("memory.custom_only").is_some());
+}
+
+#[test]
+fn broken_yaml_keeps_last_good_rules() {
+    let dir = temp_dir("loader-broken");
+    fs::write(dir.join("memory.yaml"), CUSTOM_MEMORY).expect("写规则文件");
+    let mut loader = RuleLoader::from_dir(&dir);
+    assert_eq!(loader.rules().len(), 63);
+
+    // 用户手改坏了 YAML：保留上一份好规则 + 报错，而不是让诊断能力归零
+    fs::write(
+        dir.join("memory.yaml"),
+        "version: 1\ncategory: memory\nrules: [ oops\n",
+    )
+    .expect("写坏文件");
+    match loader.refresh() {
+        ReloadOutcome::Rejected { errors } => {
+            assert!(!errors.is_empty());
+            assert_eq!(
+                errors[0].kind,
+                unlucky_core::diagnose::loader::LoadErrorKind::Yaml
+            );
+        }
+        other => panic!("应被拒绝：{other:?}"),
+    }
+    assert_eq!(loader.rules().len(), 63, "坏文件不该清空规则库");
+    assert!(loader.rule_set().get("memory.custom_only").is_some());
+    assert!(!loader.last_errors().is_empty());
+}
+
+#[test]
+fn duplicate_rule_id_across_files_is_rejected() {
+    let dir = temp_dir("loader-duplicate");
+    let duplicated = "\
+version: 1
+category: other
+rules:
+  - id: memory.out_of_memory
+    pattern: 'dup'
+    cause:
+      key: diagnose.cause.dup
+      summary: '重复 id'
+";
+    fs::write(dir.join("other.yaml"), duplicated).expect("写规则文件");
+    let loader = RuleLoader::from_dir(&dir);
+
+    assert_eq!(loader.rules().len(), 64, "整体失败后回退内嵌规则集");
+    assert!(loader
+        .last_errors()
+        .iter()
+        .any(|error| error.kind == unlucky_core::diagnose::loader::LoadErrorKind::DuplicateId));
+}
+
+#[test]
+fn unknown_field_is_rejected() {
+    let dir = temp_dir("loader-typo");
+    let typo = "\
+version: 1
+category: other
+rules:
+  - id: other.typo
+    patternn: 'typo in field name'
+    cause:
+      key: diagnose.cause.typo
+      summary: '字段拼错'
+";
+    fs::write(dir.join("other.yaml"), typo).expect("写规则文件");
+    let loader = RuleLoader::from_dir(&dir);
+    assert_eq!(loader.rules().len(), 64);
+    assert!(
+        !loader.last_errors().is_empty(),
+        "deny_unknown_fields 应把拼错的字段报出来"
+    );
+}
+
+#[test]
+fn rule_set_rejects_invalid_regex() {
+    let sources = vec![(
+        "bad.yaml".to_owned(),
+        "\
+version: 1
+category: other
+rules:
+  - id: other.bad_regex
+    pattern: '(unclosed'
+    cause:
+      key: diagnose.cause.bad
+      summary: '坏正则'
+"
+        .to_owned(),
+    )];
+    let errors = RuleSet::from_sources(&sources).expect_err("坏正则应失败");
+    assert_eq!(
+        errors[0].kind,
+        unlucky_core::diagnose::loader::LoadErrorKind::Regex
+    );
+}
diff --git a/crates/core/tests/diagnose/main.rs b/crates/core/tests/diagnose/main.rs
new file mode 100644
index 0000000..8f423c1
--- /dev/null
+++ b/crates/core/tests/diagnose/main.rs
@@ -0,0 +1,83 @@
+//! `core::diagnose` 集成测试。
+//!
+//! 结构对齐 HMCL 的 `CrashReportAnalyzerTest` + `resources/logs`（analyse/02 §7.9）：
+//! **每条规则一个样本**（`src/diagnose/rules.d/samples/`），断言「样本命中它自己」。
+//! 规则库是数据不是代码，样本就是规则的验收标准——新增规则必须同时提交样本。
+//!
+//! 跑法：`cargo test -p unlucky-core --test diagnose`
+
+mod collectors_probe;
+mod engine_rank;
+mod hs_err_parse;
+mod loader_reload;
+mod rules_samples;
+
+/// 测试共用导入与辅助函数。
+pub mod prelude {
+    use std::path::{Path, PathBuf};
+
+    pub use unlucky_core::diagnose::collectors::{
+        collect_all, CollectionContext, CrashReportCollector, EnvironmentCollector,
+        EnvironmentSnapshot, ExitCollector, ExitSignal, ExitType, HsErrCollector,
+        LatestLogCollector, LogBuffer, ModRecord, SignalBundle, SignalCollector, SignalKind,
+        SignalOrigin,
+    };
+    pub use unlucky_core::diagnose::engine::{
+        Diagnoser, DiagnosisInput, DiagnosisReport, Evidence, Finding, CONCLUSIVE_CONFIDENCE,
+    };
+    pub use unlucky_core::diagnose::hs_err::{self, FrameKind, HsErrKind, HsErrReport};
+    pub use unlucky_core::diagnose::loader::{ReloadOutcome, RuleLoader, RuleSet, EMBEDDED_RULES};
+    pub use unlucky_core::diagnose::rules::{
+        class_file_to_java_major, ComponentKind, FixAction, FixActionKind, GraphicsSetting,
+        JavaVendor, ModAction, RuleCategory, Severity,
+    };
+
+    /// 规则目录（`crates/core/src/diagnose/rules.d`）。
+    #[must_use]
+    pub fn rules_dir() -> PathBuf {
+        Path::new(env!("CARGO_MANIFEST_DIR")).join("src/diagnose/rules.d")
+    }
+
+    /// 读样本（路径相对 `rules.d/`）。
+    pub fn read_sample(relative: &str) -> String {
+        let path = rules_dir().join(relative);
+        std::fs::read_to_string(&path)
+            .unwrap_or_else(|error| panic!("样本 {} 读不到：{error}", path.display()))
+    }
+
+    /// 用内嵌规则库跑一段文本。
+    pub fn analyze_text(origin: SignalOrigin, text: &str) -> DiagnosisReport {
+        let mut input = DiagnosisInput::new();
+        input.push_text(origin, text);
+        diagnoser().analyze(&input)
+    }
+
+    /// 内嵌规则库构造的引擎。
+    #[must_use]
+    pub fn diagnoser() -> Diagnoser {
+        Diagnoser::new(RuleLoader::embedded().rules().to_vec())
+    }
+
+    /// 结论 id 列表（断言失败时打印用）。
+    #[must_use]
+    pub fn ids(report: &DiagnosisReport) -> Vec<&str> {
+        report
+            .findings
+            .iter()
+            .map(|finding| finding.rule_id.as_str())
+            .collect()
+    }
+
+    /// 临时目录（进程 id + 计数器，不引 tempfile 依赖）。
+    #[must_use]
+    pub fn temp_dir(tag: &str) -> PathBuf {
+        use std::sync::atomic::{AtomicU32, Ordering};
+        static COUNTER: AtomicU32 = AtomicU32::new(0);
+        let index = COUNTER.fetch_add(1, Ordering::Relaxed);
+        let dir =
+            std::env::temp_dir().join(format!("ull-diagnose-{}-{tag}-{index}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        std::fs::create_dir_all(&dir).expect("创建临时目录");
+        dir
+    }
+}
diff --git a/crates/core/tests/diagnose/rules_samples.rs b/crates/core/tests/diagnose/rules_samples.rs
new file mode 100644
index 0000000..7573868
--- /dev/null
+++ b/crates/core/tests/diagnose/rules_samples.rs
@@ -0,0 +1,267 @@
+//! 规则库完整性 + 每条规则的样本回归（HMCL `CrashReportAnalyzerTest` 同构）。
+
+use std::collections::{BTreeMap, BTreeSet};
+use std::path::Path;
+
+use crate::prelude::*;
+
+#[test]
+fn every_rule_has_a_sample_that_hits_itself() {
+    let loader = RuleLoader::embedded();
+    let rules = loader.rules();
+    // 64 = HMCL 59 条全量平移 + 5 条 Vulkan 组（rules.d/graphics.yaml 末尾：
+    // vulkan_loader_missing / vulkan_device_version_too_low / vulkan_missing_extension /
+    // vulkan_missing_feature / no_graphics_backend）。加规则记得同时加样本并改这个数。
+    assert_eq!(rules.len(), 64, "HMCL 59 条 + Vulkan 5 条规则应全量在位");
+    for rule in rules {
+        let sample = rule
+            .rule()
+            .sample
+            .as_deref()
+            .unwrap_or_else(|| panic!("规则 {} 没有 sample 字段", rule.id()));
+        let text = read_sample(sample);
+        let report = analyze_text(SignalOrigin::Stdout, &text);
+        let hit = report
+            .findings
+            .iter()
+            .chain(report.secondary.iter())
+            .any(|finding| finding.rule_id == rule.id());
+        assert!(
+            hit,
+            "规则 {} 的样本 {} 没有命中它自己（实际命中：{:?}）",
+            rule.id(),
+            sample,
+            ids(&report)
+        );
+    }
+}
+
+#[test]
+fn rule_ids_are_unique_and_namespaced() {
+    let loader = RuleLoader::embedded();
+    let mut seen = BTreeSet::new();
+    for rule in loader.rules() {
+        assert!(seen.insert(rule.id()), "规则 id 重复：{}", rule.id());
+        let (namespace, name) = rule
+            .id()
+            .split_once('.')
+            .unwrap_or_else(|| panic!("规则 id 必须带命名空间：{}", rule.id()));
+        assert!(
+            !namespace.is_empty() && !name.is_empty(),
+            "规则 id 不合法：{}",
+            rule.id()
+        );
+    }
+}
+
+#[test]
+fn rules_carry_cause_actions_and_provenance() {
+    for rule in RuleLoader::embedded().rules() {
+        let rule = rule.rule();
+        assert!(
+            rule.cause.key.starts_with("diagnose.cause."),
+            "规则 {} 的 cause.key 应以 diagnose.cause. 开头",
+            rule.id
+        );
+        assert!(
+            !rule.cause.summary.is_empty(),
+            "规则 {} 缺结论文案",
+            rule.id
+        );
+        assert!(
+            !rule.fix_action.is_empty(),
+            "规则 {} 没有绑定六维修复动作（M16 一键修复要靠它）",
+            rule.id
+        );
+        assert!(
+            rule.source.is_some(),
+            "规则 {} 缺 source（HMCL 出处）",
+            rule.id
+        );
+        assert!(
+            (0.0..=1.0).contains(&rule.confidence),
+            "规则 {} 的 confidence 超出 0~1",
+            rule.id
+        );
+    }
+}
+
+#[test]
+fn every_reported_category_has_rules() {
+    let mut categories = BTreeSet::new();
+    for rule in RuleLoader::embedded().rules() {
+        categories.insert(rule.category());
+    }
+    for category in RuleCategory::all() {
+        assert!(
+            categories.contains(&category),
+            "分类 {category} 一条规则都没有（rules.d 里缺这个文件或为空）"
+        );
+    }
+}
+
+#[test]
+fn no_orphan_samples() {
+    let samples_root = rules_dir().join("samples");
+    let declared = RuleLoader::embedded()
+        .rules()
+        .iter()
+        .filter_map(|rule| rule.rule().sample.clone())
+        .collect::<BTreeSet<_>>();
+    let mut on_disk = BTreeSet::new();
+    for group in std::fs::read_dir(&samples_root).expect("samples 目录") {
+        let group = group.expect("目录项").path();
+        if !group.is_dir() {
+            continue;
+        }
+        collect(&samples_root, &group, &mut on_disk);
+    }
+    for path in &on_disk {
+        assert!(
+            declared.contains(path),
+            "样本 {path} 没有规则引用它（孤儿样本，或 sample: 路径写错）"
+        );
+    }
+}
+
+/// 递归收集 `.log` 样本，返回相对 `rules.d/` 的路径。
+fn collect(root: &Path, dir: &Path, out: &mut BTreeSet<String>) {
+    for entry in std::fs::read_dir(dir).expect("目录项") {
+        let path = entry.expect("目录项").path();
+        if path.is_dir() {
+            collect(root, &path, out);
+        } else if path.extension().is_some_and(|ext| ext == "log") {
+            let relative = path
+                .strip_prefix(root)
+                .expect("相对路径")
+                .to_string_lossy()
+                .replace('\\', "/");
+            // hs_err 样本是解析器测试素材，不对应规则。
+            if !relative.starts_with("hs_err/") {
+                out.insert(format!("samples/{relative}"));
+            }
+        }
+    }
+}
+
+#[test]
+fn decisive_rule_gives_evidence_message_and_actions() {
+    let text = read_sample("samples/integrity/mod_files_decompressed.log");
+    let report = analyze_text(SignalOrigin::Stdout, &text);
+    let primary = report.primary().expect("应当命中");
+    assert_eq!(primary.rule_id, "integrity.mod_files_decompressed");
+    assert!(!primary.message.is_empty());
+    assert_eq!(primary.severity, Severity::Critical);
+    let evidence = primary.evidence.first().expect("证据");
+    assert_eq!(evidence.origin, SignalOrigin::Stdout);
+    assert!(evidence.render().starts_with("stdout:"));
+    assert!(!primary.fix_actions.is_empty());
+
+    // 高置信结论不该再要求 AI 深化
+    assert!(
+        !report.needs_more_info(),
+        "0.95 置信度的结论被判成「需要更多信息」"
+    );
+    assert_eq!(report.rules_evaluated, 64);
+}
+
+/// Vulkan 组：语义是「Vulkan 后端起不来」，所以**成功的** Vulkan 日志不该命中任何一条。
+#[test]
+fn healthy_vulkan_startup_hits_no_vulkan_rule() {
+    let text = "\
+[12:00:21] [Render thread/INFO]: Backend library: LWJGL version 3.4.3+13
+[12:00:21] [Render thread/INFO]: Using graphics backend VULKAN, using drivers: AMD proprietary driver
+[12:00:21] [Render thread/INFO]: OpenGL debug message callback registered
+";
+    let report = analyze_text(SignalOrigin::Stdout, text);
+    let hit = report
+        .findings
+        .iter()
+        .chain(report.secondary.iter())
+        .map(|finding| finding.rule_id.as_str())
+        .filter(|id| id.starts_with("graphics.vulkan") || *id == "graphics.no_graphics_backend")
+        .collect::<Vec<_>>();
+    assert!(hit.is_empty(), "正常的 Vulkan 启动日志被判成故障：{hit:?}");
+}
+
+/// Vulkan 规则必须落在 `graphics_api` 这个新维度上（否则 agent 侧不知道该改哪一项）。
+#[test]
+fn vulkan_rules_point_at_the_graphics_api_setting() {
+    let loader = RuleLoader::embedded();
+    for id in [
+        "graphics.vulkan_loader_missing",
+        "graphics.vulkan_device_version_too_low",
+        "graphics.vulkan_missing_extension",
+        "graphics.vulkan_missing_feature",
+        "graphics.no_graphics_backend",
+    ] {
+        let compiled = loader
+            .rule_set()
+            .get(id)
+            .unwrap_or_else(|| panic!("规则 {id} 不存在"));
+        let rule = compiled.rule();
+        let settings = rule
+            .fix_action
+            .iter()
+            .map(|action| action.materialize(&BTreeMap::new()))
+            .filter(|action| {
+                action
+                    .args
+                    .get("setting")
+                    .is_some_and(|setting| setting == "graphics_api")
+            })
+            .count();
+        assert!(
+            settings > 0,
+            "规则 {id} 没有 change_graphics/graphics_api 动作"
+        );
+        assert!(
+            rule.fix_action
+                .iter()
+                .any(|action| action.kind().as_str() == "change_graphics"),
+            "规则 {id} 的修复动作应属于 change_graphics 维度"
+        );
+    }
+}
+
+/// 后端全挂（两个都失败）应当压过单条 vulkan_* 原因，避免同一个故障报五遍。
+#[test]
+fn no_graphics_backend_suppresses_single_reason_rules() {
+    let text = read_sample("samples/graphics/no_graphics_backend.log");
+    let report = analyze_text(SignalOrigin::Stdout, &text);
+    assert_eq!(
+        report.primary().expect("命中").rule_id,
+        "graphics.no_graphics_backend"
+    );
+}
+
+/// SDL 变体必须保持 macOS 特异性：`cocoa` 是 SDL 在 macOS 的视频驱动名，两者同现才算
+/// 本规则命中。否则 Windows/Linux 的 SDL_Init 失败会被误归因成「macOS 显示器问题」。
+#[test]
+fn sdl_display_failure_is_attributed_to_macos_only_with_cocoa() {
+    let hit = |text: &str| {
+        let report = analyze_text(SignalOrigin::Stdout, text);
+        report
+            .findings
+            .iter()
+            .chain(report.secondary.iter())
+            .any(|finding| finding.rule_id == "graphics.macos_display_port")
+    };
+
+    let macos = "\
+[12:00:21] [Render thread/ERROR]: java.lang.IllegalStateException: SDL_Init(SDL_INIT_VIDEO) failed: cocoa: Failed to create window
+";
+    assert!(hit(macos), "macOS（cocoa）的 SDL 初始化失败应命中原规则");
+
+    for other in [
+        // Windows：SDL 的 windows 驱动，文本里没有 cocoa。
+        "[12:00:21] [Render thread/ERROR]: SDL_Init(SDL_INIT_VIDEO) failed: No available video device\n",
+        // Linux：x11/wayland 驱动。
+        "[12:00:21] [Render thread/ERROR]: SDL_Init(SDL_INIT_VIDEO) failed: x11: Could not connect to display\n",
+    ] {
+        assert!(
+            !hit(other),
+            "非 macOS 的 SDL 初始化失败不该归因到 macOS 显示器规则：{other}"
+        );
+    }
+}
diff --git a/crates/core/tests/download/backoff_test.rs b/crates/core/tests/download/backoff_test.rs
new file mode 100644
index 0000000..fb4b5b0
--- /dev/null
+++ b/crates/core/tests/download/backoff_test.rs
@@ -0,0 +1,68 @@
+//! 指数退避与抖动的单测（纯函数，无网络）。
+
+use std::time::Duration;
+
+use unlucky_core::download::backoff::{BackoffPolicy, Jitter};
+
+#[test]
+fn exponential_growth_doubles_and_caps() {
+    let policy = BackoffPolicy::default();
+    assert_eq!(policy.delay(0), Duration::from_millis(1_000));
+    assert_eq!(policy.delay(1), Duration::from_millis(2_000));
+    assert_eq!(policy.delay(2), Duration::from_millis(4_000));
+    assert_eq!(policy.delay(3), Duration::from_millis(8_000));
+    // 上限封顶，不会涨到分钟级。
+    assert_eq!(policy.delay(10), Duration::from_millis(30_000));
+    assert_eq!(policy.delay(u32::MAX), Duration::from_millis(30_000));
+}
+
+#[test]
+fn no_retry_policy_waits_nothing() {
+    let policy = BackoffPolicy::none();
+    assert_eq!(policy.delay(0), Duration::ZERO);
+    assert_eq!(policy.max_attempts, 1);
+    assert_eq!(policy.delay_jittered(0, 0.5), Duration::ZERO);
+}
+
+#[test]
+fn jitter_stays_within_ratio_bounds() {
+    let policy = BackoffPolicy::default();
+    // base 1000ms ± 30% → [700, 1300]
+    let low = policy.delay_jittered(0, 0.0);
+    let high = policy.delay_jittered(0, 1.0);
+    assert_eq!(low, Duration::from_millis(700));
+    assert_eq!(high, Duration::from_millis(1_300));
+    // 抖动永不超过 max_ms。
+    for rng in [0.0, 0.25, 0.5, 0.75, 1.0] {
+        assert!(policy.delay_jittered(9, rng) <= Duration::from_millis(30_000));
+    }
+}
+
+#[test]
+fn jitter_without_ratio_is_deterministic() {
+    let policy = BackoffPolicy {
+        jitter_ratio: 0.0,
+        ..BackoffPolicy::default()
+    };
+    assert_eq!(
+        policy.delay_jittered(2, 0.0),
+        policy.delay_jittered(2, 0.99)
+    );
+}
+
+#[test]
+fn jitter_source_is_reproducible_and_in_range() {
+    let mut first = Jitter::new(42);
+    let mut second = Jitter::new(42);
+    for _ in 0..32 {
+        let a = first.next_fraction();
+        let b = second.next_fraction();
+        assert_eq!(a, b, "同种子的抖动序列必须一致");
+        assert!((0.0..1.0).contains(&a));
+    }
+
+    let mut other = Jitter::new(7);
+    assert_ne!(Jitter::new(1).next_u64(), other.next_u64());
+    // 种子 0 会被替换成固定非零种子，但仍然可用。
+    assert!((0.0..1.0).contains(&Jitter::new(0).next_fraction()));
+}
diff --git a/crates/core/tests/download/cache_test.rs b/crates/core/tests/download/cache_test.rs
new file mode 100644
index 0000000..5420372
--- /dev/null
+++ b/crates/core/tests/download/cache_test.rs
@@ -0,0 +1,149 @@
+//! 内容寻址缓存的单测：两级分片、记录信任（命中不重算）、损坏检测、索引持久化。
+
+mod support;
+
+use std::time::Duration;
+
+use unlucky_core::download::cache::ContentCache;
+use unlucky_core::download::types::{HashAlgo, Integrity};
+
+const NOW: u64 = 5_000_000;
+
+fn cache_dir(tag: &str) -> std::path::PathBuf {
+    support::temp_dir(tag)
+}
+
+#[test]
+fn sharded_path_follows_layout() {
+    let dir = cache_dir("cache-path");
+    let cache = ContentCache::open(&dir);
+    let integrity = Integrity::sha1("abcdef0123456789abcdef0123456789abcdef01");
+    let path = cache.path_for(integrity.algo, &integrity.hex);
+    assert!(path.ends_with("sha1/ab/abcdef0123456789abcdef0123456789abcdef01"));
+    assert!(path.starts_with(cache.root()));
+    // SHA-256 单独一棵子树。
+    let sha256_path = cache.path_for(HashAlgo::Sha256, "00112233445566778899aabbccddeeff");
+    assert!(sha256_path.ends_with("sha256/00/00112233445566778899aabbccddeeff"));
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn insert_then_lookup_hits_without_rehashing() {
+    let dir = cache_dir("cache-hit");
+    let cache = ContentCache::open(&dir);
+
+    let payload = b"hello unlucky launcher".to_vec();
+    let integrity = Integrity::sha1(support::sha1_hex(&payload));
+    let source = dir.join("download.bin");
+    std::fs::write(&source, &payload).unwrap();
+
+    let cached = cache
+        .insert(&source, &integrity, NOW)
+        .expect("写入缓存失败");
+    assert!(cached.is_file());
+    assert_eq!(cache.len(), 1);
+
+    // 第二次命中：size/mtime 未变 → 记录信任，直接返回（不重算摘要）。
+    let hit = cache.lookup(&integrity, NOW + 10).expect("应命中缓存");
+    assert_eq!(hit, cached);
+
+    // 文件被删 → 记录作废。
+    std::fs::remove_file(&cached).unwrap();
+    assert!(cache.lookup(&integrity, NOW + 20).is_none());
+    assert_eq!(cache.len(), 0);
+
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn truncated_cache_file_is_a_miss() {
+    let dir = cache_dir("cache-truncate");
+    let cache = ContentCache::open(&dir);
+
+    let payload = vec![7_u8; 256];
+    let integrity = Integrity::sha1(support::sha1_hex(&payload));
+    let source = dir.join("payload.bin");
+    std::fs::write(&source, &payload).unwrap();
+    let cached = cache.insert(&source, &integrity, NOW).unwrap();
+
+    // 半损坏（长度变了）必须立刻视为未命中。
+    std::fs::write(&cached, &payload[..128]).unwrap();
+    assert!(cache.lookup(&integrity, NOW + 1).is_none());
+
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn metadata_change_forces_a_rehash() {
+    let dir = cache_dir("cache-rehash");
+    let cache = ContentCache::open(&dir);
+
+    let payload = vec![3_u8; 128];
+    let integrity = Integrity::sha1(support::sha1_hex(&payload));
+    let source = dir.join("data.bin");
+    std::fs::write(&source, &payload).unwrap();
+    let cached = cache.insert(&source, &integrity, NOW).unwrap();
+    // 硬链接/复制都可能让源文件与缓存同 inode，先断开再改缓存内容。
+    let _ = std::fs::remove_file(&source);
+
+    // 等 mtime 变化（部分文件系统时间戳精度 10ms）。
+    std::thread::sleep(Duration::from_millis(30));
+    let mut tampered = payload.clone();
+    tampered[0] = 9;
+    std::fs::write(&cached, &tampered).unwrap();
+
+    // 内容变了 → 摘要不符 → 记录作废。
+    assert!(cache.lookup(&integrity, NOW + 100).is_none());
+    assert_eq!(cache.len(), 0);
+
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn lookup_verified_rejects_wrong_content_with_same_size() {
+    let dir = cache_dir("cache-verified");
+    let cache = ContentCache::open(&dir);
+
+    let payload = vec![1_u8; 64];
+    let integrity = Integrity::sha1(support::sha1_hex(&payload));
+    // 直接放到缓存位但内容是错的（模拟外部篡改 / 镜像写坏）。
+    let path = cache.path_for(integrity.algo, &integrity.hex);
+    std::fs::create_dir_all(path.parent().unwrap()).unwrap();
+    std::fs::write(&path, vec![2_u8; 64]).unwrap();
+    cache.register(&path, &integrity, NOW).unwrap();
+
+    assert!(
+        cache.lookup_verified(&integrity, NOW + 1).is_none(),
+        "强制校验必须发现内容不符"
+    );
+
+    // 内容对了就能通过。
+    std::fs::write(&path, &payload).unwrap();
+    cache.register(&path, &integrity, NOW).unwrap();
+    assert!(cache.lookup_verified(&integrity, NOW + 2).is_some());
+
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn index_persists_across_reopen() {
+    let dir = cache_dir("cache-persist");
+    let payload = vec![5_u8; 32];
+    let integrity = Integrity::sha1(support::sha1_hex(&payload));
+
+    {
+        let cache = ContentCache::open(&dir);
+        let source = dir.join("src.bin");
+        std::fs::write(&source, &payload).unwrap();
+        cache.insert(&source, &integrity, NOW).unwrap();
+        cache.persist().expect("持久化索引失败");
+        assert_eq!(cache.stats().entries, 1);
+        assert_eq!(cache.stats().total_bytes, 32);
+    }
+
+    let reopened = ContentCache::open(&dir);
+    assert_eq!(reopened.len(), 1);
+    assert!(reopened.lookup(&integrity, NOW + 1).is_some());
+
+    let _ = std::fs::remove_dir_all(&dir);
+}
diff --git a/crates/core/tests/download/chunked_test.rs b/crates/core/tests/download/chunked_test.rs
new file mode 100644
index 0000000..906baf3
--- /dev/null
+++ b/crates/core/tests/download/chunked_test.rs
@@ -0,0 +1,375 @@
+//! 分块规划与 Range 语义的单测（纯函数）+ 真跑 4 连接的端到端用例（mock 源）。
+
+mod support;
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use unlucky_core::download::backoff::BackoffPolicy;
+use unlucky_core::download::cache::ContentCache;
+use unlucky_core::download::chunked::{
+    content_range_matches, parse_content_range, plan, range_support, ByteRange, ChunkedConfig,
+    ContentRange, RangeSupport, MAX_CONNECTIONS,
+};
+use unlucky_core::download::config::EngineConfig;
+use unlucky_core::download::engine::DownloadEngine;
+use unlucky_core::download::health::HealthRegistry;
+use unlucky_core::download::mirrors::MirrorTable;
+use unlucky_core::download::region::RegionProfile;
+use unlucky_core::download::types::{DownloadRequest, ResourceKind};
+
+use support::{sha1_hex, temp_dir, MockResponse, MockServer};
+
+#[test]
+fn plan_partitions_whole_file_without_gaps() {
+    let cases = [
+        (1_u64, 4_usize),
+        (3, 4),
+        (100, 4),
+        (1000, 7),
+        (123_456_789, 4),
+    ];
+    for (total, connections) in cases {
+        let ranges = plan(total, connections);
+        assert!(!ranges.is_empty(), "total={total} 不能切出空集");
+        assert_eq!(ranges[0].start, 0, "必须从 0 开始");
+        assert_eq!(ranges.last().unwrap().end, total - 1, "必须覆盖到末尾");
+        let mut next = 0_u64;
+        for range in &ranges {
+            assert_eq!(range.start, next, "段之间不能有空洞或重叠");
+            assert!(!range.is_empty());
+            next = range.end + 1;
+        }
+        assert_eq!(next, total);
+        assert_eq!(ranges.iter().map(ByteRange::len).sum::<u64>(), total);
+    }
+}
+
+#[test]
+fn plan_caps_connections_and_handles_edge_cases() {
+    assert!(plan(0, 4).is_empty());
+    // 文件比连接数还小：每段 1 字节。
+    let tiny = plan(3, 4);
+    assert_eq!(tiny.len(), 3);
+    assert!(tiny.iter().all(|range| range.len() == 1));
+    // 连接数被夹到上限。
+    let many = plan(1_000_000, 100);
+    assert_eq!(many.len(), MAX_CONNECTIONS);
+    // 单连接。
+    assert_eq!(plan(120, 1), vec![ByteRange::new(0, 119)]);
+}
+
+#[test]
+fn byte_range_headers_are_closed_intervals() {
+    let range = ByteRange::new(100, 199);
+    assert_eq!(range.len(), 100);
+    assert_eq!(range.header_value(), "bytes=100-199");
+    assert!(ByteRange::new(10, 9).is_empty());
+    assert_eq!(ByteRange::new(10, 9).len(), 0);
+}
+
+#[test]
+fn parse_content_range_accepts_servers_forms() {
+    assert_eq!(
+        parse_content_range("bytes 0-99/1000"),
+        Some(ContentRange {
+            start: 0,
+            end: 99,
+            total: Some(1000)
+        })
+    );
+    assert_eq!(
+        parse_content_range("  bytes 100-199/*  "),
+        Some(ContentRange {
+            start: 100,
+            end: 199,
+            total: None
+        })
+    );
+    // 畸形一律 None：调用方据此退化。
+    assert_eq!(parse_content_range("bytes 100-99/1000"), None);
+    assert_eq!(parse_content_range("items 0-9/10"), None);
+    assert_eq!(parse_content_range("bytes 0-9"), None);
+    assert_eq!(parse_content_range(""), None);
+}
+
+#[test]
+fn range_support_matrix() {
+    assert_eq!(range_support(Some("bytes"), 200), RangeSupport::Supported);
+    assert_eq!(range_support(None, 206), RangeSupport::Supported);
+    assert_eq!(range_support(Some("none"), 200), RangeSupport::Unsupported);
+    assert_eq!(
+        range_support(Some("crumbs"), 200),
+        RangeSupport::Unsupported
+    );
+    assert_eq!(range_support(None, 200), RangeSupport::Unknown);
+}
+
+#[test]
+fn chunked_config_gate() {
+    let config = ChunkedConfig::default();
+    assert!(config.enabled);
+    assert_eq!(config.connections, 4);
+    // 只有大文件 + 大资源类型才分块。
+    assert!(config.applies_to(ResourceKind::JavaRuntime, Some(200 * 1024 * 1024)));
+    assert!(!config.applies_to(ResourceKind::JavaRuntime, Some(1024)));
+    assert!(!config.applies_to(ResourceKind::ClientJar, Some(200 * 1024 * 1024)));
+    assert!(!config.applies_to(ResourceKind::JavaRuntime, None));
+    // 设置项关掉后一律不分块。
+    assert!(!ChunkedConfig::disabled().applies_to(ResourceKind::JavaRuntime, Some(u64::MAX)));
+    assert_eq!(
+        ChunkedConfig {
+            connections: 999,
+            ..ChunkedConfig::default()
+        }
+        .effective_connections(),
+        MAX_CONNECTIONS
+    );
+}
+
+/// 端到端：`min_size` 调到 1KiB 后，20KiB 的 JDK 类资源真的被切成 4 段并行取。
+///
+/// 断言三件事：①mock 源收到 4 次带 `Range` 的请求（不是 1 次）②拼装后的文件逐字节正确
+/// ③流式 sha1 校验通过（证明分块乱序写没有错位）。
+#[tokio::test]
+async fn downloads_large_file_over_four_parallel_ranges() {
+    let payload: Vec<u8> = (0..20 * 1024).map(|index| (index % 251) as u8).collect();
+    let server = MockServer::start(vec![
+        MockResponse::ok(payload.clone()),
+        MockResponse::ok(payload.clone()),
+        MockResponse::ok(payload.clone()),
+        MockResponse::ok(payload.clone()),
+    ])
+    .await;
+    let url = server.url("/jdk.zip");
+    let dir = temp_dir("chunked-e2e");
+    let engine = DownloadEngine::new(
+        EngineConfig {
+            max_attempts_per_source: 1,
+            backoff: BackoffPolicy {
+                base_ms: 1,
+                max_ms: 2,
+                jitter_ratio: 0.0,
+                max_attempts: 1,
+            },
+            read_timeout: Duration::from_secs(5),
+            connect_timeout: Duration::from_secs(5),
+            // 真开分块：4 条连接，1KiB 以上就切。
+            chunked: ChunkedConfig {
+                enabled: true,
+                connections: 4,
+                min_size: 1024,
+            },
+            ..EngineConfig::default()
+        },
+        Arc::new(MirrorTable::builtin()),
+        Arc::new(RegionProfile::direct(0)),
+        Arc::new(HealthRegistry::in_memory()),
+        Arc::new(ContentCache::open(dir.join("cache"))),
+    );
+
+    let dest = dir.join("jdk.zip");
+    let outcome = engine
+        .download(
+            DownloadRequest::new(ResourceKind::JavaRuntime, url.as_str(), &dest)
+                .with_sha1(sha1_hex(&payload))
+                .with_size(payload.len() as u64),
+        )
+        .await
+        .expect("分块下载失败");
+
+    assert_eq!(outcome.bytes, payload.len() as u64);
+    assert_eq!(outcome.source, "official");
+    assert_eq!(
+        server.hits(),
+        4,
+        "4 条连接应各发一次带 Range 的请求（退化单连接会只有 1 次）"
+    );
+    assert_eq!(std::fs::read(&dest).expect("读回落盘文件失败"), payload);
+    assert!(
+        support::part_files(&dir).is_empty(),
+        "中间文件必须在提交后消失：{:?}",
+        support::part_files(&dir)
+    );
+    server.stop();
+}
+
+/// 端到端：目标目录**还不存在**时分块下载也要能落盘。
+///
+/// 回归用例。分块路径先 `OpenOptions` 预分配整文件（不走 `PartFile::open_append`
+/// 那层建目录），所以「下到新建目录」曾让所有候选源瞬间全部失败
+/// （现场：`data/java-managed/.cache/` 未创建时装 JDK 六个源全挂）。
+#[tokio::test]
+async fn chunked_download_creates_the_destination_directory() {
+    let payload: Vec<u8> = (0..8 * 1024).map(|index| (index % 31) as u8).collect();
+    let responses = vec![
+        MockResponse::ok(payload.clone()),
+        MockResponse::ok(payload.clone()),
+        MockResponse::ok(payload.clone()),
+        MockResponse::ok(payload.clone()),
+    ];
+    let server = MockServer::start(responses).await;
+    let url = server.url("/jdk.zip");
+    let dir = temp_dir("chunked-mkdir");
+    let engine = DownloadEngine::new(
+        EngineConfig {
+            max_attempts_per_source: 1,
+            backoff: BackoffPolicy {
+                base_ms: 1,
+                max_ms: 2,
+                jitter_ratio: 0.0,
+                max_attempts: 1,
+            },
+            read_timeout: Duration::from_secs(5),
+            connect_timeout: Duration::from_secs(5),
+            chunked: ChunkedConfig {
+                enabled: true,
+                connections: 4,
+                min_size: 1024,
+            },
+            ..EngineConfig::default()
+        },
+        Arc::new(MirrorTable::builtin()),
+        Arc::new(RegionProfile::direct(0)),
+        Arc::new(HealthRegistry::in_memory()),
+        Arc::new(ContentCache::open(dir.join("cache"))),
+    );
+
+    let dest = dir.join("java-managed/.cache/jdk.zip");
+    assert!(
+        !dest.parent().expect("父目录").exists(),
+        "前置条件：目录不存在"
+    );
+    let outcome = engine
+        .download(
+            DownloadRequest::new(ResourceKind::JavaRuntime, url.as_str(), &dest)
+                .with_sha1(sha1_hex(&payload))
+                .with_size(payload.len() as u64),
+        )
+        .await
+        .expect("分块下载应成功");
+    assert_eq!(outcome.bytes, payload.len() as u64);
+    assert_eq!(std::fs::read(&dest).expect("读回落盘文件失败"), payload);
+    server.stop();
+}
+
+/// 端到端：服务器声明支持 Range 但实际无视（返回 200）→ 自动退化单连接，结果仍然正确。
+#[tokio::test]
+async fn falls_back_to_single_connection_when_server_ignores_range() {
+    let payload: Vec<u8> = (0..8 * 1024).map(|index| (index % 97) as u8).collect();
+    // 每个请求都会拿到 200 + 整份内容（range_support = false）。
+    // 响应条数给足：4 个分块请求可能都发出去才被 abort，退化后的整份请求是第 5 条。
+    let no_range = || MockResponse::ok(payload.clone()).without_range();
+    let server = MockServer::start(vec![
+        no_range(),
+        no_range(),
+        no_range(),
+        no_range(),
+        no_range(),
+        no_range(),
+    ])
+    .await;
+    let url = server.url("/client.jar");
+    let dir = temp_dir("chunked-fallback");
+    let engine = DownloadEngine::new(
+        EngineConfig {
+            max_attempts_per_source: 1,
+            backoff: BackoffPolicy::none(),
+            chunked: ChunkedConfig {
+                enabled: true,
+                connections: 4,
+                min_size: 1024,
+            },
+            ..EngineConfig::default()
+        },
+        Arc::new(MirrorTable::builtin()),
+        Arc::new(RegionProfile::direct(0)),
+        Arc::new(HealthRegistry::in_memory()),
+        Arc::new(ContentCache::open(dir.join("cache"))),
+    );
+
+    let dest = dir.join("client.jar");
+    let outcome = engine
+        .download(
+            DownloadRequest::new(ResourceKind::JavaRuntime, url.as_str(), &dest)
+                .with_sha1(sha1_hex(&payload))
+                .with_size(payload.len() as u64),
+        )
+        .await
+        .expect("退化后应仍能下载成功");
+
+    assert_eq!(outcome.bytes, payload.len() as u64);
+    assert_eq!(std::fs::read(&dest).expect("读回落盘文件失败"), payload);
+    server.stop();
+}
+
+#[test]
+fn content_range_must_match_requested_segment() {
+    let requested = ByteRange::new(5120, 10239);
+    // 严格一致才放行。
+    assert!(content_range_matches(
+        requested,
+        Some("bytes 5120-10239/20480")
+    ));
+    // 起止任一不符 → 判失败（否则「长度恰好但位置错」的响应会拼出坏文件）。
+    assert!(!content_range_matches(
+        requested,
+        Some("bytes 0-5119/20480")
+    ));
+    assert!(!content_range_matches(
+        requested,
+        Some("bytes 5120-20479/20480")
+    ));
+    // 畸形头判失败。
+    assert!(!content_range_matches(requested, Some("garbage")));
+    // 缺头从宽（长度校验仍兜底）。
+    assert!(content_range_matches(requested, None));
+}
+
+/// 端到端：服务器回 206 但 `Content-Range` 谎报段位置 → 分块路径判不符、丢弃中间文件、
+/// 退化单连接重下，最终文件仍逐字节正确（不会交付拼错的文件）。
+#[tokio::test]
+async fn rejects_lying_content_range_and_falls_back() {
+    let payload: Vec<u8> = (0..8 * 1024).map(|index| (index % 89) as u8).collect();
+    let lying = || MockResponse::ok(payload.clone()).with_wrong_content_range();
+    let server = MockServer::start(vec![
+        lying(),
+        lying(),
+        lying(),
+        lying(),
+        MockResponse::ok(payload.clone()),
+    ])
+    .await;
+    let url = server.url("/jdk.zip");
+    let dir = temp_dir("chunked-lying-range");
+    let engine = DownloadEngine::new(
+        EngineConfig {
+            max_attempts_per_source: 1,
+            backoff: BackoffPolicy::none(),
+            chunked: ChunkedConfig {
+                enabled: true,
+                connections: 4,
+                min_size: 1024,
+            },
+            ..EngineConfig::default()
+        },
+        Arc::new(MirrorTable::builtin()),
+        Arc::new(RegionProfile::direct(0)),
+        Arc::new(HealthRegistry::in_memory()),
+        Arc::new(ContentCache::open(dir.join("cache"))),
+    );
+
+    let dest = dir.join("jdk.zip");
+    let outcome = engine
+        .download(
+            DownloadRequest::new(ResourceKind::JavaRuntime, url.as_str(), &dest)
+                .with_sha1(sha1_hex(&payload))
+                .with_size(payload.len() as u64),
+        )
+        .await
+        .expect("谎报 Content-Range 后应退化单连接成功");
+
+    assert_eq!(outcome.bytes, payload.len() as u64);
+    assert_eq!(std::fs::read(&dest).expect("读回落盘文件失败"), payload);
+    server.stop();
+}
diff --git a/crates/core/tests/download/engine_mock_test.rs b/crates/core/tests/download/engine_mock_test.rs
new file mode 100644
index 0000000..528e664
--- /dev/null
+++ b/crates/core/tests/download/engine_mock_test.rs
@@ -0,0 +1,350 @@
+//! 引擎端到端（mock 源）：成功 / 退避重试 / 换源 / 校验失败 / 缓存命中 / 断点续传。
+//!
+//! 用 `tests/download/support` 里的进程内 HTTP 服务器，不发真实网络请求。
+
+mod support;
+
+use std::path::PathBuf;
+use std::sync::Arc;
+use std::time::Duration;
+
+use unlucky_core::download::backoff::BackoffPolicy;
+use unlucky_core::download::cache::ContentCache;
+use unlucky_core::download::chunked::ChunkedConfig;
+use unlucky_core::download::config::EngineConfig;
+use unlucky_core::download::engine::DownloadEngine;
+use unlucky_core::download::error::DownloadErrorKind;
+use unlucky_core::download::health::HealthRegistry;
+use unlucky_core::download::mirrors::{MirrorTable, PrefixRule};
+use unlucky_core::download::progress::{ProgressEmitter, ProgressEvent};
+use unlucky_core::download::region::RegionProfile;
+use unlucky_core::download::resume::ResumeMeta;
+use unlucky_core::download::types::{DownloadRequest, HashAlgo, ResourceKind};
+
+use support::{sha1_hex, temp_dir, MockResponse, MockServer};
+
+fn fast_config(attempts: u32) -> EngineConfig {
+    EngineConfig {
+        max_attempts_per_source: attempts,
+        backoff: BackoffPolicy {
+            base_ms: 1,
+            max_ms: 2,
+            jitter_ratio: 0.0,
+            max_attempts: attempts,
+        },
+        connect_timeout: Duration::from_secs(5),
+        read_timeout: Duration::from_secs(5),
+        chunked: ChunkedConfig::disabled(),
+        ..EngineConfig::default()
+    }
+}
+
+struct Harness {
+    engine: DownloadEngine,
+    dir: PathBuf,
+}
+
+fn harness(cfg: EngineConfig, table: MirrorTable, region: RegionProfile, tag: &str) -> Harness {
+    let dir = temp_dir(tag);
+    let cache = Arc::new(ContentCache::open(dir.join("cache")));
+    let health = Arc::new(HealthRegistry::in_memory());
+    let engine = DownloadEngine::new(cfg, Arc::new(table), Arc::new(region), health, cache);
+    Harness { engine, dir }
+}
+
+fn direct_region() -> RegionProfile {
+    RegionProfile::direct(0)
+}
+
+#[tokio::test]
+async fn downloads_verifies_and_leaves_no_part_file() {
+    let payload = b"unlucky launcher payload".to_vec();
+    let server = MockServer::start(vec![MockResponse::ok(payload.clone())]).await;
+    let url = server.url("/client.jar");
+    let harness = harness(
+        fast_config(2),
+        MirrorTable::builtin(),
+        direct_region(),
+        "engine-ok",
+    );
+    let dest = harness.dir.join("versions/1.20.1/client.jar");
+
+    let request = DownloadRequest::new(ResourceKind::ClientJar, url.as_str(), &dest)
+        .with_sha1(sha1_hex(&payload))
+        .with_size(payload.len() as u64);
+    let outcome = harness.engine.download(request).await.expect("下载应成功");
+
+    assert_eq!(outcome.bytes, payload.len() as u64);
+    assert!(!outcome.from_cache);
+    assert_eq!(outcome.resumed_from, 0);
+    assert_eq!(std::fs::read(&dest).unwrap(), payload);
+    let version_dir = harness.dir.join("versions/1.20.1");
+    assert!(
+        support::part_files(&version_dir).is_empty(),
+        "中间文件必须被提交掉：{:?}",
+        support::part_files(&version_dir)
+    );
+    server.stop();
+}
+
+#[tokio::test]
+async fn retries_same_source_after_server_error() {
+    let payload = b"retry me".to_vec();
+    let server = MockServer::start(vec![
+        MockResponse::status(503),
+        MockResponse::ok(payload.clone()),
+    ])
+    .await;
+    let url = server.url("/lib.jar");
+    let harness = harness(
+        fast_config(3),
+        MirrorTable::builtin(),
+        direct_region(),
+        "engine-retry",
+    );
+    let dest = harness.dir.join("lib.jar");
+
+    let outcome = harness
+        .engine
+        .download(
+            DownloadRequest::new(ResourceKind::Library, url.as_str(), &dest)
+                .with_sha1(sha1_hex(&payload)),
+        )
+        .await
+        .expect("退避后应成功");
+    assert_eq!(outcome.bytes, payload.len() as u64);
+    assert_eq!(server.hits(), 2, "第一次 503 之后应重试一次");
+    server.stop();
+}
+
+#[tokio::test]
+async fn switches_to_official_when_mirror_keeps_failing() {
+    let payload = b"official wins".to_vec();
+    let official = MockServer::start(vec![MockResponse::ok(payload.clone())]).await;
+    let mirror = MockServer::start(vec![
+        MockResponse::status(500),
+        MockResponse::status(500),
+        MockResponse::status(500),
+    ])
+    .await;
+
+    let mut table = MirrorTable::builtin();
+    let official_prefix = format!("http://127.0.0.1:{}", official.port());
+    let mirror_prefix = format!("http://localhost:{}", mirror.port());
+    table.add_custom_rule(PrefixRule::new(
+        "mock-mirror",
+        official_prefix,
+        mirror_prefix,
+    ));
+
+    let harness = harness(
+        fast_config(2),
+        table,
+        RegionProfile::mirror_first(0),
+        "engine-switch",
+    );
+    let dest = harness.dir.join("client.jar");
+    let url = official.url("/client.jar");
+
+    let outcome = harness
+        .engine
+        .download(
+            DownloadRequest::new(ResourceKind::ClientJar, url.as_str(), &dest)
+                .with_sha1(sha1_hex(&payload)),
+        )
+        .await
+        .expect("镜像全挂后应切到官方");
+    assert_eq!(outcome.source, "official");
+    assert_eq!(std::fs::read(&dest).unwrap(), payload);
+    assert_eq!(mirror.hits(), 2, "每个源最多尝试 max_attempts 次");
+    official.stop();
+    mirror.stop();
+}
+
+#[tokio::test]
+async fn rejects_wrong_checksum_and_falls_back() {
+    let payload = b"the real jar".to_vec();
+    let official = MockServer::start(vec![MockResponse::ok(payload.clone())]).await;
+    let mirror = MockServer::start(vec![MockResponse::ok(b"tampered by mirror".to_vec())]).await;
+
+    let mut table = MirrorTable::builtin();
+    table.add_custom_rule(PrefixRule::new(
+        "mock-mirror",
+        format!("http://127.0.0.1:{}", official.port()),
+        format!("http://localhost:{}", mirror.port()),
+    ));
+
+    let harness = harness(
+        fast_config(1),
+        table,
+        RegionProfile::mirror_first(0),
+        "engine-checksum",
+    );
+    let dest = harness.dir.join("client.jar");
+    let url = official.url("/client.jar");
+
+    let outcome = harness
+        .engine
+        .download(
+            DownloadRequest::new(ResourceKind::ClientJar, url.as_str(), &dest)
+                .with_sha1(sha1_hex(&payload))
+                .with_size(payload.len() as u64),
+        )
+        .await
+        .expect("校验失败应换源而不是交付坏文件");
+    assert_eq!(outcome.source, "official");
+    assert_eq!(std::fs::read(&dest).unwrap(), payload);
+    assert!(mirror.hits() >= 1);
+    official.stop();
+    mirror.stop();
+}
+
+#[tokio::test]
+async fn second_download_hits_content_cache_without_network() {
+    let payload = b"cached payload".to_vec();
+    let server = MockServer::start(vec![
+        MockResponse::ok(payload.clone()),
+        MockResponse::ok(payload.clone()),
+    ])
+    .await;
+    let url = server.url("/lib.jar");
+    let harness = harness(
+        fast_config(2),
+        MirrorTable::builtin(),
+        direct_region(),
+        "engine-cache",
+    );
+    let integrity = sha1_hex(&payload);
+
+    let first = harness
+        .engine
+        .download(
+            DownloadRequest::new(
+                ResourceKind::Library,
+                url.as_str(),
+                harness.dir.join("a/lib.jar"),
+            )
+            .with_sha1(integrity.as_str()),
+        )
+        .await
+        .expect("首次下载失败");
+    assert!(!first.from_cache);
+
+    let hits_after_first = server.hits();
+    let second = harness
+        .engine
+        .download(
+            DownloadRequest::new(
+                ResourceKind::Library,
+                url.as_str(),
+                harness.dir.join("b/lib.jar"),
+            )
+            .with_sha1(integrity.as_str()),
+        )
+        .await
+        .expect("缓存命中失败");
+    assert!(second.from_cache);
+    assert_eq!(second.bytes, payload.len() as u64);
+    assert_eq!(server.hits(), hits_after_first, "缓存命中不能再发请求");
+    assert_eq!(
+        std::fs::read(harness.dir.join("b/lib.jar")).unwrap(),
+        payload
+    );
+    server.stop();
+}
+
+#[tokio::test]
+async fn resumes_from_existing_part_file() {
+    let payload = b"0123456789abcdefghij".to_vec();
+    let split = 8_usize;
+    let server = MockServer::start(vec![MockResponse::ok(payload.clone())]).await;
+    let url = server.url("/client.jar");
+    let harness = harness(
+        fast_config(2),
+        MirrorTable::builtin(),
+        direct_region(),
+        "engine-resume",
+    );
+    let dest = harness.dir.join("client.jar");
+    let part = harness.dir.join("client.jar.ullpart");
+    let meta_path = harness.dir.join("client.jar.ullpart.ullmeta.json");
+
+    std::fs::write(&part, &payload[..split]).unwrap();
+    ResumeMeta {
+        url: url.clone(),
+        etag: Some("\"v1\"".to_string()),
+        last_modified: None,
+        total: Some(payload.len() as u64),
+        algo: HashAlgo::Sha1,
+        hash: sha1_hex(&payload),
+        saved_at_ms: 1,
+    }
+    .save(&meta_path)
+    .expect("写续传元数据失败");
+
+    let outcome = harness
+        .engine
+        .download(
+            DownloadRequest::new(ResourceKind::ClientJar, url.as_str(), &dest)
+                .with_sha1(sha1_hex(&payload))
+                .with_size(payload.len() as u64),
+        )
+        .await
+        .expect("续传失败");
+
+    assert_eq!(outcome.resumed_from, split as u64, "应从已有偏移续传");
+    assert_eq!(std::fs::read(&dest).unwrap(), payload);
+    assert_eq!(server.hits(), 1);
+    server.stop();
+}
+
+#[tokio::test]
+async fn reports_progress_events_and_errors_when_all_sources_fail() {
+    let server = MockServer::start(vec![
+        MockResponse::status(500),
+        MockResponse::status(500),
+        MockResponse::status(500),
+        MockResponse::status(500),
+    ])
+    .await;
+    let url = server.url("/dead.jar");
+    let dir = temp_dir("engine-fail");
+    let cache = Arc::new(ContentCache::open(dir.join("cache")));
+    let (emitter, mut events) = ProgressEmitter::channel();
+    let engine = DownloadEngine::new(
+        fast_config(1),
+        Arc::new(MirrorTable::builtin()),
+        Arc::new(direct_region()),
+        Arc::new(HealthRegistry::in_memory()),
+        cache,
+    )
+    .with_progress(emitter);
+
+    let error = engine
+        .download(DownloadRequest::new(
+            ResourceKind::Library,
+            url.as_str(),
+            dir.join("dead.jar"),
+        ))
+        .await
+        .expect_err("所有源都 500 时必须失败");
+    assert_eq!(error.kind, DownloadErrorKind::AllSourcesFailed);
+
+    let mut started = false;
+    let mut failed_source = false;
+    while let Ok(event) = events.try_recv() {
+        match event {
+            ProgressEvent::Started { candidates, .. } => {
+                started = true;
+                assert!(candidates >= 1);
+            }
+            ProgressEvent::SourceFailed { will_retry, .. } => {
+                failed_source = true;
+                assert!(!will_retry, "单次尝试用尽后不应再声明重试");
+            }
+            _ => {}
+        }
+    }
+    assert!(started && failed_source, "进度事件缺失");
+    server.stop();
+}
diff --git a/crates/core/tests/download/health_test.rs b/crates/core/tests/download/health_test.rs
new file mode 100644
index 0000000..3899cb9
--- /dev/null
+++ b/crates/core/tests/download/health_test.rs
@@ -0,0 +1,268 @@
+//! 健康度记忆的单测：冷却、恢复探测、排序、持久化 + 引擎驱动的落盘接线。
+
+mod support;
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use unlucky_core::download::backoff::BackoffPolicy;
+use unlucky_core::download::cache::{now_ms, ContentCache};
+use unlucky_core::download::config::EngineConfig;
+use unlucky_core::download::engine::DownloadEngine;
+use unlucky_core::download::error::DownloadErrorKind;
+use unlucky_core::download::health::{
+    HealthRegistry, SourceHealth, COOLDOWN_MS, FAILURE_THRESHOLD,
+};
+use unlucky_core::download::mirrors::MirrorTable;
+use unlucky_core::download::region::RegionProfile;
+use unlucky_core::download::types::{Candidate, DownloadRequest, ResourceKind, SOURCE_OFFICIAL};
+
+use support::{MockResponse, MockServer};
+
+const NOW: u64 = 1_000_000;
+
+fn registry() -> HealthRegistry {
+    HealthRegistry::in_memory()
+}
+
+#[test]
+fn fresh_source_is_neutral_not_penalized() {
+    let health = SourceHealth::default();
+    assert!(!health.is_cooling_down(NOW));
+    assert_eq!(health.failure_rate(), 0.0);
+    // 未知源必须是中间分，不能比刚成功的源更优先。
+    let healthy = SourceHealth {
+        samples: 3,
+        successes: 3,
+        ema_rtt_ms: 120.0,
+        ..SourceHealth::default()
+    };
+    assert!(healthy.score(NOW) < health.score(NOW));
+}
+
+#[test]
+fn three_consecutive_failures_trigger_cooldown() {
+    let mut health = SourceHealth::default();
+    for _ in 0..FAILURE_THRESHOLD {
+        health.record_failure("HTTP 502", NOW);
+    }
+    assert!(health.is_cooling_down(NOW));
+    assert!(health.is_cooling_down(NOW + COOLDOWN_MS - 1));
+    // 冷却到期后不再是冷却态，而是「可以探测」。
+    assert!(!health.is_cooling_down(NOW + COOLDOWN_MS));
+    assert!(health.is_probe(NOW + COOLDOWN_MS));
+    // 冷却中的源排序惩罚要明显高于健康源。
+    assert!(health.score(NOW) >= 1_000.0);
+}
+
+#[test]
+fn missing_artifact_is_recorded_without_cooling_down() {
+    // 院校镜像只留最新补丁：请求旧补丁必然 404，不能把源判成「坏」。
+    let mut health = SourceHealth::default();
+    for _ in 0..(FAILURE_THRESHOLD * 2) {
+        health.record_missing("HTTP 404", NOW);
+    }
+    assert!(!health.is_cooling_down(NOW), "4xx 不进冷却");
+    assert!(!health.is_probe(NOW), "4xx 不该产生恢复探测状态");
+    assert_eq!(health.failures, 0, "4xx 不计失败次数");
+    assert_eq!(health.not_found, u64::from(FAILURE_THRESHOLD * 2));
+    assert_eq!(health.failure_rate(), 0.0);
+    assert!(health.last_error.is_some(), "诊断仍要留痕");
+    // 打分不应被 404 拉高（仍是未知源的中位分）。
+    assert_eq!(health.score(NOW), SourceHealth::default().score(NOW));
+    assert_eq!(
+        health.score(NOW),
+        unlucky_core::download::health::SCORE_UNKNOWN
+    );
+}
+
+#[test]
+fn not_found_ageing_does_not_persist_a_cooldown() {
+    let registry = HealthRegistry::in_memory();
+    for _ in 0..10 {
+        registry.record_missing("tuna", ResourceKind::JavaRuntime, "HTTP 404", NOW);
+    }
+    let health = registry.health_of("tuna", ResourceKind::JavaRuntime);
+    assert!(!health.is_cooling_down(NOW));
+    assert_eq!(health.not_found, 10);
+    assert_eq!(health.consecutive_failures, 0);
+}
+
+#[test]
+fn probe_failure_re_arms_cooldown_and_success_clears_it() {
+    let mut health = SourceHealth::default();
+    for _ in 0..FAILURE_THRESHOLD {
+        health.record_failure("timeout", NOW);
+    }
+    let after_cooldown = NOW + COOLDOWN_MS + 1;
+    assert!(!health.is_cooling_down(after_cooldown));
+    // 探测再一次失败 → 立即重新冷却。
+    health.record_failure("timeout again", after_cooldown);
+    assert!(health.is_cooling_down(after_cooldown));
+
+    // 成功则全部清零。
+    health.record_success(90, after_cooldown + 1);
+    assert!(!health.is_cooling_down(after_cooldown + 1));
+    assert!(!health.is_probe(after_cooldown + 1));
+    assert_eq!(health.consecutive_failures, 0);
+    assert_eq!(health.cooldown_until_ms, 0);
+    assert_eq!(health.last_error, None);
+}
+
+#[test]
+fn ema_smooths_latency_and_counts_samples() {
+    let mut health = SourceHealth::default();
+    health.record_success(100, NOW);
+    assert_eq!(health.ema_rtt_ms, 100.0);
+    health.record_success(200, NOW);
+    // 0.3 * 200 + 0.7 * 100 = 130
+    assert!((health.ema_rtt_ms - 130.0).abs() < 1e-9);
+    assert_eq!(health.samples, 2);
+    assert_eq!(health.successes, 2);
+}
+
+#[test]
+fn failure_rate_counts_both_sides() {
+    let mut health = SourceHealth::default();
+    health.record_success(50, NOW);
+    health.record_failure("boom", NOW);
+    assert!((health.failure_rate() - 0.5).abs() < 1e-9);
+}
+
+#[test]
+fn registry_ranks_healthy_first_and_cooling_last() {
+    let registry = registry();
+    for _ in 0..FAILURE_THRESHOLD {
+        registry.record_failure("mirror-b", ResourceKind::ClientJar, "HTTP 500", NOW);
+    }
+    registry.record_success(
+        "mirror-a",
+        ResourceKind::ClientJar,
+        Duration::from_millis(80),
+        NOW,
+    );
+
+    let candidates = vec![
+        Candidate::new("mirror-b", "https://b.example/file"),
+        Candidate::new("unknown", "https://u.example/file"),
+        Candidate::new("mirror-a", "https://a.example/file"),
+    ];
+    let ranked = registry.rank(&candidates, ResourceKind::ClientJar, NOW);
+    assert_eq!(ranked[0].source, "mirror-a");
+    assert_eq!(ranked[1].source, "unknown");
+    assert_eq!(
+        ranked[2].source, "mirror-b",
+        "冷却中的源排最后但仍保留为兜底"
+    );
+}
+
+#[test]
+fn health_is_tracked_per_resource_kind() {
+    let registry = registry();
+    for _ in 0..FAILURE_THRESHOLD {
+        registry.record_failure("bmclapi", ResourceKind::Asset, "404", NOW);
+    }
+    assert!(registry.is_cooling_down("bmclapi", ResourceKind::Asset, NOW));
+    // 另一种资源类型不受影响（资产挂了不代表 JDK 也挂）。
+    assert!(!registry.is_cooling_down("bmclapi", ResourceKind::JavaRuntime, NOW));
+}
+
+#[test]
+fn persistence_roundtrip_and_age_pruning() {
+    let dir = std::env::temp_dir().join(format!("ull-health-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).unwrap();
+    let path = dir.join("health.json");
+
+    let registry = HealthRegistry::open(&path, 7 * 24 * 3600 * 1000, NOW);
+    registry.record_failure("bmclapi", ResourceKind::Library, "HTTP 503", NOW);
+    registry.record_success(
+        "official",
+        ResourceKind::Library,
+        Duration::from_millis(55),
+        NOW,
+    );
+    registry.save().expect("持久化失败");
+
+    let reloaded = HealthRegistry::open(&path, 7 * 24 * 3600 * 1000, NOW + 1_000);
+    assert_eq!(reloaded.snapshot().len(), 2);
+    assert_eq!(
+        reloaded
+            .health_of("bmclapi", ResourceKind::Library)
+            .failures,
+        1
+    );
+    assert!(
+        reloaded
+            .health_of("official", ResourceKind::Library)
+            .ema_rtt_ms
+            > 0.0
+    );
+
+    // 超出最大保留期 → 丢弃旧记录（缓存目录被长时间放着的情况）。
+    let pruned = HealthRegistry::open(&path, 10, NOW + 60_000);
+    assert!(pruned.snapshot().is_empty());
+
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+/// P1 回归：健康度必须由**引擎的生产路径**落盘——下载→（模拟进程退出）→重开 registry，
+/// 冷却状态与失败计数都要还在，否则「连续 3 败冷却 10 分钟」每轮启动从零学起。
+#[tokio::test]
+async fn engine_persists_health_so_a_restart_keeps_the_cooldown() {
+    let failed = || MockResponse::status(500);
+    let server = MockServer::start(vec![failed(), failed(), failed(), failed()]).await;
+    let url = server.url("/lib.jar");
+    let dir = support::temp_dir("health-engine-persist");
+    let path = dir.join("cache/health.json");
+    let now = now_ms();
+    let max_age_ms = 7 * 24 * 3600 * 1000;
+
+    let registry = Arc::new(HealthRegistry::open(&path, max_age_ms, now));
+    let engine = DownloadEngine::new(
+        EngineConfig {
+            max_attempts_per_source: FAILURE_THRESHOLD,
+            backoff: BackoffPolicy {
+                base_ms: 1,
+                max_ms: 2,
+                jitter_ratio: 0.0,
+                max_attempts: FAILURE_THRESHOLD,
+            },
+            ..EngineConfig::default()
+        },
+        Arc::new(MirrorTable::builtin()),
+        Arc::new(RegionProfile::direct(0)),
+        Arc::clone(&registry),
+        Arc::new(ContentCache::open(dir.join("cache"))),
+    );
+
+    let error = engine
+        .download(DownloadRequest::new(
+            ResourceKind::Library,
+            url.as_str(),
+            dir.join("lib.jar"),
+        ))
+        .await
+        .expect_err("全 500 必须失败");
+    assert_eq!(error.kind, DownloadErrorKind::AllSourcesFailed);
+    server.stop();
+
+    // 第 3 次连续失败进入冷却时就该落盘（不等收尾 flush）。
+    assert!(path.is_file(), "健康度必须已经落盘到 cache/health.json");
+    let before = registry.health_of(SOURCE_OFFICIAL, ResourceKind::Library);
+    assert!(before.consecutive_failures >= FAILURE_THRESHOLD);
+    assert!(before.is_cooling_down(now_ms()));
+
+    // 「进程退出后重开」：从同一个文件恢复，冷却状态与失败计数都还在。
+    let reopened = HealthRegistry::open(&path, max_age_ms, now_ms());
+    let restored = reopened.health_of(SOURCE_OFFICIAL, ResourceKind::Library);
+    assert_eq!(restored.consecutive_failures, before.consecutive_failures);
+    assert_eq!(restored.failures, before.failures);
+    assert!(
+        restored.is_cooling_down(now_ms()),
+        "重开后仍应处于冷却：{restored:?}"
+    );
+    assert!(restored.last_error.is_some(), "失败原因也要持久化");
+
+    let _ = std::fs::remove_dir_all(&dir);
+}
diff --git a/crates/core/tests/download/mirrors_test.rs b/crates/core/tests/download/mirrors_test.rs
new file mode 100644
index 0000000..61c0696
--- /dev/null
+++ b/crates/core/tests/download/mirrors_test.rs
@@ -0,0 +1,281 @@
+//! 镜像清单与前缀重写的单测（纯字符串，无网络）。
+
+use unlucky_core::download::adoptium::{parse_adoptium_artifact, JdkFlavor};
+use unlucky_core::download::mirrors::{host_of, source_id_for, MirrorTable, PrefixRule};
+use unlucky_core::download::region::RegionProfile;
+use unlucky_core::download::types::ResourceKind;
+
+const LIBRARIES_URL: &str =
+    "https://libraries.minecraft.net/com/google/guava/guava/32.0.0/guava-32.0.0.jar";
+const ASSET_URL: &str = "https://resources.download.minecraft.net/ab/abcdef0123456789";
+const GITHUB_URL: &str =
+    "https://github.com/AskaEth/Unlucky-Launcher/releases/download/v1.0.0/ull-windows-x64.exe";
+const ADOPTIUM_URL: &str = "https://github.com/adoptium/temurin17-binaries/releases/download/JDK17.0.13%2B11/OpenJDK17U-jdk_x64_windows_hotspot_17.0.13_11.zip";
+
+#[test]
+fn builtin_table_is_embedded_and_complete() {
+    let table = MirrorTable::builtin();
+    assert!(table.version >= 1);
+    assert!(table.rules.len() >= 10, "内置规则太少");
+    assert!(table.adoptium.len() >= 3, "院校镜像至少要 TUNA/USTC/SJTU");
+    assert!(!table.gh_proxies.is_empty());
+    assert!(table.gh_proxies[0].prefix.starts_with("https://gh-proxy"));
+}
+
+#[test]
+fn prefix_rule_preserves_sub_path() {
+    let table = MirrorTable::builtin();
+    let rule = table
+        .prefix_rule_for(LIBRARIES_URL, ResourceKind::Library)
+        .expect("libraries 规则缺失");
+    let candidate = rule.apply(LIBRARIES_URL).expect("重写失败");
+    assert_eq!(candidate.source, "bmclapi");
+    assert_eq!(
+        candidate.url,
+        LIBRARIES_URL.replace(
+            "https://libraries.minecraft.net",
+            "https://bmclapi2.bangbang93.com"
+        )
+    );
+}
+
+#[test]
+fn asset_rule_injects_path_prefix() {
+    let table = MirrorTable::builtin();
+    let candidate = table
+        .prefix_rule_for(ASSET_URL, ResourceKind::Asset)
+        .and_then(|rule| rule.apply(ASSET_URL))
+        .expect("资源对象规则缺失");
+    assert_eq!(
+        candidate.url,
+        "https://bmclapi2.bangbang93.com/assets/ab/abcdef0123456789"
+    );
+}
+
+#[test]
+fn direct_mode_puts_official_first() {
+    let table = MirrorTable::builtin();
+    let region = RegionProfile::direct(0);
+    let candidates = table.expand(LIBRARIES_URL, ResourceKind::Library, &region);
+    assert_eq!(candidates[0].source, "official");
+    assert_eq!(candidates[0].url, LIBRARIES_URL);
+    // 镜像仍然保留为兜底（官方失败时能救回来）。
+    assert!(candidates
+        .iter()
+        .any(|candidate| candidate.source == "bmclapi"));
+}
+
+#[test]
+fn mirror_first_mode_puts_mirror_first() {
+    let table = MirrorTable::builtin();
+    let region = RegionProfile::mirror_first(0);
+    let candidates = table.expand(LIBRARIES_URL, ResourceKind::Library, &region);
+    assert_eq!(candidates[0].source, "bmclapi");
+    assert_eq!(
+        candidates.last().map(|c| c.source.as_str()),
+        Some("official")
+    );
+}
+
+#[test]
+fn gh_proxy_only_for_github_hosts_in_domestic_mode() {
+    let table = MirrorTable::builtin();
+    let domestic = RegionProfile::mirror_first(0);
+    let direct = RegionProfile::direct(0);
+
+    let github = table.expand(GITHUB_URL, ResourceKind::GitHubRelease, &domestic);
+    assert!(
+        github.iter().any(|candidate| candidate.source == "gh_proxy"
+            && candidate.url.starts_with("https://gh-proxy.com/")),
+        "国内模式下 GitHub 资源必须套 gh-proxy：{github:?}"
+    );
+
+    let non_github = table.expand(LIBRARIES_URL, ResourceKind::Library, &domestic);
+    assert!(
+        non_github
+            .iter()
+            .all(|candidate| candidate.source != "gh_proxy"),
+        "非 GitHub 资源不受 gh-proxy 影响"
+    );
+
+    let github_direct = table.expand(GITHUB_URL, ResourceKind::GitHubRelease, &direct);
+    assert!(github_direct
+        .iter()
+        .all(|candidate| candidate.source != "gh_proxy"));
+}
+
+#[test]
+fn pinned_or_disabled_gh_proxy_is_respected() {
+    let table = MirrorTable::builtin();
+
+    // 用户关掉：地区档案显式不带前缀 → 一条 gh_proxy 候选都不出。
+    let off = RegionProfile::mirror_first(0).with_gh_proxy(None);
+    let candidates = table.expand(GITHUB_URL, ResourceKind::GitHubRelease, &off);
+    assert!(candidates.iter().all(|c| c.source != "gh_proxy"));
+
+    // 自定义前缀（设置项写进地区档案）。
+    let custom = RegionProfile::mirror_first(0).with_gh_proxy(Some("https://proxy.example/"));
+    let candidates = table.expand(GITHUB_URL, ResourceKind::GitHubRelease, &custom);
+    let proxy = candidates
+        .iter()
+        .find(|candidate| candidate.source == "gh_proxy")
+        .expect("自定义前缀未生效");
+    assert_eq!(proxy.url, format!("https://proxy.example/{GITHUB_URL}"));
+
+    // 清单给设置做默认值。
+    assert_eq!(table.default_gh_proxy(), Some("https://gh-proxy.com/"));
+}
+
+#[test]
+fn adoptium_artifact_parsing_and_mirror_ordering() {
+    let parsed = parse_adoptium_artifact(ADOPTIUM_URL).expect("解析 Temurin 产物名失败");
+    assert_eq!(parsed.major, "17");
+    assert_eq!(parsed.flavor, JdkFlavor::Jdk);
+    assert_eq!(parsed.arch, "x64");
+    assert_eq!(parsed.os, "windows");
+    assert!(parsed.filename.starts_with("OpenJDK17U-jdk_x64_windows"));
+
+    let table = MirrorTable::builtin();
+    let region = RegionProfile::mirror_first(0);
+    let candidates = table.expand(ADOPTIUM_URL, ResourceKind::JavaRuntime, &region);
+    let first = &candidates[0];
+    assert_eq!(first.source, "tuna");
+    assert!(
+        first
+            .url
+            .starts_with("https://mirrors.tuna.tsinghua.edu.cn/Adoptium/17/jdk/x64/windows/"),
+        "院校镜像路径不符合模板：{}",
+        first.url
+    );
+    // 官方仍在候选里（全部镜像不可达时的兜底）。
+    assert!(candidates
+        .iter()
+        .any(|candidate| candidate.source == "official"));
+}
+
+/// JRE 产物必须落到镜像的 `/jre/` 子树（否则 4 个镜像全 404，加速白费）。
+#[test]
+fn adoptium_jre_uses_jre_path_segment() {
+    let jre_url = ADOPTIUM_URL.replace("OpenJDK17U-jdk_", "OpenJDK17U-jre_");
+    let parsed = parse_adoptium_artifact(&jre_url).expect("解析 JRE 产物名失败");
+    assert_eq!(parsed.flavor, JdkFlavor::Jre);
+    assert_eq!(
+        parsed.mirror_url("https://mirrors.tuna.tsinghua.edu.cn/Adoptium"),
+        format!(
+            "https://mirrors.tuna.tsinghua.edu.cn/Adoptium/17/jre/x64/windows/{}",
+            parsed.filename
+        )
+    );
+
+    let table = MirrorTable::builtin();
+    let candidates = table.expand(
+        &jre_url,
+        ResourceKind::JavaRuntime,
+        &RegionProfile::mirror_first(0),
+    );
+    let first = &candidates[0];
+    assert_eq!(first.source, "tuna");
+    assert!(
+        first.url.contains("/17/jre/x64/windows/"),
+        "JRE 必须走 /jre/ 子树：{}",
+        first.url
+    );
+
+    // `-jre-17…` 这种兜底形态同样识别。
+    let fallback = "https://github.com/adoptium/temurin21-binaries/releases/download/jre-21.0.5%2B11/OpenJDK21U-jre_x64_linux_hotspot_21.0.5_11.tar.gz";
+    assert_eq!(
+        parse_adoptium_artifact(fallback).map(|artifact| artifact.flavor),
+        Some(JdkFlavor::Jre)
+    );
+}
+
+#[test]
+fn custom_rules_take_precedence() {
+    let mut table = MirrorTable::builtin();
+    table.add_custom_rule(PrefixRule::new(
+        "my-mirror",
+        "https://libraries.minecraft.net",
+        "https://mirror.example/libraries",
+    ));
+    let candidate = table
+        .prefix_rule_for(LIBRARIES_URL, ResourceKind::Library)
+        .and_then(|rule| rule.apply(LIBRARIES_URL))
+        .expect("自定义规则未生效");
+    assert_eq!(candidate.source, "mirror.example");
+    assert_eq!(
+        candidate.url,
+        "https://mirror.example/libraries/com/google/guava/guava/32.0.0/guava-32.0.0.jar"
+    );
+}
+
+#[test]
+fn fallback_rule_keeps_official_first_even_in_domestic_mode() {
+    let mut table = MirrorTable {
+        version: 1,
+        notes: Vec::new(),
+        rules: vec![PrefixRule::new(
+            "modrinth-accelerator",
+            "https://api.modrinth.com",
+            "https://cdn.example",
+        )
+        .fallback()],
+        // v3 新增的三张 JDK 源表在这张夹具里必须为空（否则会混进别的候选）。
+        adoptium: Vec::new(),
+        oracle_openjdk: Vec::new(),
+        microsoft_openjdk: None,
+        zulu: None,
+        gh_proxies: Vec::new(),
+    };
+    let region = RegionProfile::mirror_first(0);
+    let candidates = table.expand(
+        "https://api.modrinth.com/v2/project/sodium",
+        ResourceKind::ModFile,
+        &region,
+    );
+    assert_eq!(
+        candidates[0].source, "official",
+        "「仅加速」规则不能顶掉官方"
+    );
+    assert_eq!(candidates[1].source, "cdn.example");
+
+    // 关掉规则后只剩官方一条。
+    table.rules.clear();
+    let candidates = table.expand(
+        "https://api.modrinth.com/v2/project/sodium",
+        ResourceKind::ModFile,
+        &region,
+    );
+    assert_eq!(candidates.len(), 1);
+}
+
+#[test]
+fn host_and_source_id_helpers() {
+    assert_eq!(
+        host_of("https://libraries.minecraft.net/a/b"),
+        Some("libraries.minecraft.net")
+    );
+    assert_eq!(
+        host_of("https://user:pass@mirror.example:8443/x/y"),
+        Some("mirror.example")
+    );
+    assert_eq!(host_of("http://127.0.0.1:8080/file"), Some("127.0.0.1"));
+    assert_eq!(host_of("not-a-url"), Some("not-a-url"));
+
+    assert_eq!(
+        source_id_for("https://bmclapi2.bangbang93.com/assets/ab/cd"),
+        "bmclapi"
+    );
+    assert_eq!(
+        source_id_for("https://mirrors.tuna.tsinghua.edu.cn/Adoptium/17/x.zip"),
+        "tuna"
+    );
+    assert_eq!(
+        source_id_for("https://mirrors.ustc.edu.cn/adoptium/17/x.zip"),
+        "ustc"
+    );
+    assert_eq!(
+        source_id_for("https://gh-proxy.com/https://github.com/a/b"),
+        "gh_proxy"
+    );
+    assert_eq!(source_id_for("https://example.org/file"), "example.org");
+}
diff --git a/crates/core/tests/download/partfile_test.rs b/crates/core/tests/download/partfile_test.rs
new file mode 100644
index 0000000..f267d79
--- /dev/null
+++ b/crates/core/tests/download/partfile_test.rs
@@ -0,0 +1,233 @@
+//! `download::atomic::PartFile`：中间文件的进程/实例隔离、续传收养与孤儿清理。
+//!
+//! 背景（M35 真机 finding）：中间文件路径原先只由目标路径决定，两个启动器进程装同一
+//! 数据根时共用一个 `.ullpart`，先提交的一方 `rename` 走，另一方 `os error 2`
+//! （实测两次 `ull install` 各失败 819 / 1116 个资源）。这里守住三条：名字带会话标识、
+//! 旧材料能收养、孤儿清理不许误删有人在用的中间文件。
+
+mod support;
+
+use std::fs;
+use std::io::Write;
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+use std::time::Duration;
+
+use unlucky_core::download::backoff::BackoffPolicy;
+use unlucky_core::download::cache::ContentCache;
+use unlucky_core::download::chunked::ChunkedConfig;
+use unlucky_core::download::config::EngineConfig;
+use unlucky_core::download::engine::DownloadEngine;
+use unlucky_core::download::health::HealthRegistry;
+use unlucky_core::download::mirrors::MirrorTable;
+use unlucky_core::download::region::RegionProfile;
+use unlucky_core::download::types::{DownloadRequest, ResourceKind};
+use unlucky_core::download::{PartFile, ADOPT_MIN_AGE, META_SUFFIX, ORPHAN_MAX_AGE, PART_SUFFIX};
+
+use support::{age_file, part_files, sha1_hex, temp_dir, MockResponse, MockServer};
+
+/// 另一个会话号（保证与本进程不同）。
+fn foreign_session() -> u32 {
+    std::process::id() ^ 1
+}
+
+fn part_name(name: &str, session: u32, seq: u64) -> String {
+    format!("{name}{PART_SUFFIX}-{session}-{seq}")
+}
+
+fn write_part(dir: &Path, name: &str) -> PathBuf {
+    let path = dir.join(name);
+    fs::write(&path, b"0123456789").expect("写中间文件失败");
+    path
+}
+
+#[test]
+fn part_file_names_carry_session_and_sequence() {
+    let dir = temp_dir("partfile-identity");
+    let dest = dir.join("client.jar");
+
+    let first = PartFile::for_dest(&dest);
+    let second = PartFile::for_dest(&dest);
+
+    assert_ne!(
+        first.path(),
+        second.path(),
+        "同一 dest 的两个守卫不能共用文件"
+    );
+    assert_eq!(first.path().parent(), Some(dir.as_path()));
+    let name = first.path().file_name().unwrap().to_string_lossy();
+    assert!(
+        name.starts_with(&format!("client.jar{PART_SUFFIX}-")),
+        "中间文件名要带进程标识：{name}"
+    );
+    assert!(
+        name.contains(&std::process::id().to_string()),
+        "进程号要在名字里（跨进程隔离的依据）：{name}"
+    );
+}
+
+#[test]
+fn two_threads_writing_the_same_dest_commit_independently() {
+    let dir = temp_dir("partfile-threads");
+    let dest = dir.join("client.jar");
+
+    let handles: Vec<_> = (0..2_u8)
+        .map(|index| {
+            let dest = dest.clone();
+            std::thread::spawn(move || {
+                let payload = vec![b'a' + index; 4096];
+                let part = PartFile::for_dest(&dest);
+                part.open_truncate()
+                    .expect("打开中间文件失败")
+                    .write_all(&payload)
+                    .expect("写中间文件失败");
+                part.commit(&dest).expect("原子落盘失败");
+                payload
+            })
+        })
+        .collect();
+
+    let payloads: Vec<Vec<u8>> = handles
+        .into_iter()
+        .map(|handle| handle.join().expect("下载线程 panic"))
+        .collect();
+    let written = fs::read(&dest).expect("读落盘文件失败");
+    assert!(
+        payloads.contains(&written),
+        "落盘内容必须是某个线程的完整产物"
+    );
+    assert!(
+        part_files(&dir).is_empty(),
+        "两线程各自的中间文件都要被提交掉：{:?}",
+        part_files(&dir)
+    );
+}
+
+#[test]
+fn legacy_part_file_is_adopted_for_resume() {
+    let dir = temp_dir("partfile-legacy");
+    let dest = dir.join("client.jar");
+    let legacy = write_part(&dir, &format!("client.jar{PART_SUFFIX}"));
+    let legacy_meta = dir.join(format!("client.jar{PART_SUFFIX}{META_SUFFIX}"));
+    fs::write(&legacy_meta, b"{}").expect("写元数据失败");
+
+    let part = PartFile::for_dest(&dest);
+
+    assert_ne!(part.path(), legacy.as_path(), "新守卫要换自己的名字");
+    assert_eq!(part.len(), 10, "旧版中间文件必须被收养（续传语义不变）");
+    assert!(!legacy.exists(), "收养后不许留下旧名字");
+    assert!(!legacy_meta.exists(), "元数据要跟着中间文件一起搬");
+    assert!(part.meta_path().is_file(), "收养后的元数据路径要就位");
+}
+
+#[test]
+fn foreign_part_file_is_adopted_only_after_it_cools_down() {
+    let dir = temp_dir("partfile-foreign");
+    let dest = dir.join("client.jar");
+    let foreign = write_part(&dir, &part_name("client.jar", foreign_session(), 1));
+
+    let fresh = PartFile::for_dest(&dest);
+    assert!(!fresh.exists(), "外进程刚写过的中间文件不能抢");
+    assert!(foreign.is_file(), "更不能删（可能正被那个进程写着）");
+
+    age_file(&foreign, ADOPT_MIN_AGE + Duration::from_secs(60));
+    let adopted = PartFile::for_dest(&dest);
+    assert_eq!(adopted.len(), 10, "静置够久的外来中间文件应被收养续传");
+    assert!(!foreign.exists(), "收养后旧名字应消失");
+}
+
+#[test]
+fn sweeps_ownerless_orphans_but_keeps_fresh_and_live_files() {
+    let dir = temp_dir("partfile-sweep");
+    let stale = write_part(&dir, &format!("other.jar{PART_SUFFIX}"));
+    let stale_meta = dir.join(format!("other.jar{PART_SUFFIX}{META_SUFFIX}"));
+    fs::write(&stale_meta, b"{}").expect("写元数据失败");
+    age_file(&stale, ORPHAN_MAX_AGE + Duration::from_secs(60));
+    let fresh = write_part(&dir, &format!("fresh.jar{PART_SUFFIX}"));
+
+    let _guard = PartFile::for_dest(&dir.join("client.jar"));
+
+    assert!(!stale.exists(), "无主且超龄的中间文件应被清理");
+    assert!(!stale_meta.exists(), "它的元数据也要一起清");
+    assert_eq!(
+        fs::read(&fresh).unwrap().len(),
+        10,
+        "还新鲜的无主文件不能删"
+    );
+}
+
+#[test]
+fn keeps_another_live_guard_of_the_same_dest() {
+    let dir = temp_dir("partfile-live");
+    let dest = dir.join("client.jar");
+    let running = PartFile::for_dest(&dest);
+    running
+        .open_truncate()
+        .expect("打开中间文件失败")
+        .write_all(&[b'x'; 1024])
+        .expect("写中间文件失败");
+
+    let other = PartFile::for_dest(&dest);
+
+    assert!(
+        running.path().is_file(),
+        "有人在用的中间文件不能被清理或收养"
+    );
+    assert_eq!(running.len(), 1024);
+    assert_ne!(other.path(), running.path());
+}
+
+fn fast_engine(cache: &Path) -> DownloadEngine {
+    DownloadEngine::new(
+        EngineConfig {
+            max_attempts_per_source: 1,
+            backoff: BackoffPolicy {
+                base_ms: 1,
+                max_ms: 2,
+                jitter_ratio: 0.0,
+                max_attempts: 1,
+            },
+            read_timeout: Duration::from_secs(5),
+            connect_timeout: Duration::from_secs(5),
+            chunked: ChunkedConfig::disabled(),
+            ..EngineConfig::default()
+        },
+        Arc::new(MirrorTable::builtin()),
+        Arc::new(RegionProfile::direct(0)),
+        Arc::new(HealthRegistry::in_memory()),
+        Arc::new(ContentCache::open(cache)),
+    )
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn two_engines_downloading_the_same_dest_do_not_share_parts() {
+    let payload = b"same destination payload".to_vec();
+    let server = MockServer::start(vec![
+        MockResponse::ok(payload.clone()),
+        MockResponse::ok(payload.clone()),
+    ])
+    .await;
+    let url = server.url("/client.jar");
+    let dir = temp_dir("partfile-engine");
+    let dest = dir.join("client.jar");
+    // 两份独立的缓存目录：否则后到的那次会直接吃内容缓存，绕过中间文件路径。
+    let left = fast_engine(&dir.join("cache-a"));
+    let right = fast_engine(&dir.join("cache-b"));
+    let request = || {
+        DownloadRequest::new(ResourceKind::ClientJar, url.as_str(), &dest)
+            .with_sha1(sha1_hex(&payload))
+            .with_size(payload.len() as u64)
+    };
+
+    let (first, second) = tokio::join!(left.download(request()), right.download(request()));
+
+    first.expect("并行下载 A 失败");
+    second.expect("并行下载 B 失败");
+    assert_eq!(fs::read(&dest).expect("读落盘文件失败"), payload);
+    assert!(
+        part_files(&dir).is_empty(),
+        "并发下载不能留下中间文件：{:?}",
+        part_files(&dir)
+    );
+    server.stop();
+}
diff --git a/crates/core/tests/download/region_test.rs b/crates/core/tests/download/region_test.rs
new file mode 100644
index 0000000..9f84b7d
--- /dev/null
+++ b/crates/core/tests/download/region_test.rs
@@ -0,0 +1,121 @@
+//! 地区判定的单测：只测纯判定与缓存，不真发探测请求。
+
+use unlucky_core::download::region::{
+    decide_from, load_cached, store_cached, RegionMode, RegionProfile, RegionTrigger, Signals,
+    DECISION_TTL_MS, DEFAULT_GH_PROXY,
+};
+
+fn signals(timezone: Option<&str>, language: Option<&str>, google: Option<bool>) -> Signals {
+    Signals {
+        timezone: timezone.map(str::to_string),
+        languages: language.map(str::to_string).into_iter().collect(),
+        google_reachable: google,
+        baidu_reachable: None,
+    }
+}
+
+#[test]
+fn timezone_signal_detects_greater_china() {
+    assert!(signals(Some("Asia/Shanghai"), None, None).is_greater_china());
+    assert!(signals(Some("Asia/Taipei"), None, None).is_greater_china());
+    // 大小写/空白容错。
+    assert!(signals(Some(" asia/hong_kong "), None, None).is_greater_china());
+    assert!(!signals(Some("Europe/Berlin"), None, None).is_greater_china());
+}
+
+#[test]
+fn language_signal_handles_posix_and_bcp47() {
+    assert!(signals(None, Some("zh_CN.UTF-8"), None).is_greater_china());
+    assert!(signals(None, Some("zh-Hant-TW"), None).is_greater_china());
+    assert!(!signals(None, Some("en_US.UTF-8"), None).is_greater_china());
+    // 时区不命中、语言命中也算。
+    assert!(signals(Some("UTC"), Some("zh_TW"), None).is_greater_china());
+}
+
+#[test]
+fn domestic_without_google_goes_mirror_first() {
+    let profile = decide_from(&signals(Some("Asia/Shanghai"), None, Some(false)), 1);
+    assert_eq!(profile.mode, RegionMode::MirrorFirst);
+    assert!(profile.greater_china);
+    assert_eq!(profile.trigger, RegionTrigger::Auto);
+    assert_eq!(profile.gh_proxy.as_deref(), Some(DEFAULT_GH_PROXY));
+    assert!(profile.gh_proxy_enabled());
+}
+
+#[test]
+fn domestic_with_google_reachable_stays_direct() {
+    // 已有全局代理：尊重用户代理，不再插镜像。
+    let profile = decide_from(&signals(Some("Asia/Shanghai"), None, Some(true)), 1);
+    assert_eq!(profile.mode, RegionMode::Direct);
+    assert!(profile.gh_proxy.is_none());
+    assert!(!profile.gh_proxy_enabled());
+}
+
+#[test]
+fn non_greater_china_is_always_direct() {
+    for google in [Some(true), Some(false), None] {
+        let profile = decide_from(&signals(Some("America/New_York"), Some("en-US"), google), 1);
+        assert_eq!(profile.mode, RegionMode::Direct, "google={google:?}");
+        assert!(!profile.greater_china);
+    }
+}
+
+#[test]
+fn probes_disabled_defaults_to_mirror_first_for_chinese_env() {
+    let profile = decide_from(&signals(None, Some("zh_CN.UTF-8"), None), 1);
+    assert_eq!(profile.mode, RegionMode::MirrorFirst);
+    assert!(!profile.probes_enabled);
+}
+
+#[test]
+fn pinned_mode_never_goes_stale() {
+    let pinned = RegionProfile::pinned(RegionMode::Direct, 10);
+    assert_eq!(pinned.trigger, RegionTrigger::UserPinned);
+    assert!(!pinned.is_stale(10 + DECISION_TTL_MS * 10));
+
+    let auto = decide_from(&signals(Some("Asia/Shanghai"), None, Some(false)), 10);
+    assert!(!auto.is_stale(10 + 1_000));
+    assert!(auto.is_stale(10 + DECISION_TTL_MS + 1));
+}
+
+#[test]
+fn gh_proxy_helpers() {
+    let mut profile = RegionProfile::mirror_first(0);
+    assert!(profile.gh_proxy_enabled());
+    profile = profile.with_gh_proxy(Some("   "));
+    assert!(!profile.gh_proxy_enabled(), "空白前缀视为不启用");
+    profile = profile.with_gh_proxy(Some("https://proxy.example/"));
+    assert!(profile.gh_proxy_enabled());
+
+    // 直连模式下即便配了前缀也不生效（gh-proxy 只在国内模式用）。
+    let direct = RegionProfile::direct(0).with_gh_proxy(Some("https://proxy.example/"));
+    assert!(!direct.gh_proxy_enabled());
+    assert_eq!(direct.label(), "直连");
+    assert_eq!(RegionProfile::mirror_first(0).label(), "镜像优先");
+}
+
+#[test]
+fn cache_roundtrip_and_ttl_expiry() {
+    let dir = std::env::temp_dir().join(format!("ull-region-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).unwrap();
+    let path = dir.join("region.json");
+
+    let profile = decide_from(&signals(Some("Asia/Shanghai"), None, Some(false)), 1_000);
+    store_cached(&path, &profile).expect("写缓存失败");
+
+    let cached = load_cached(&path, 1_000 + 60_000).expect("应有缓存");
+    assert_eq!(cached, profile);
+
+    // 过期 → 视为没有缓存。
+    assert!(load_cached(&path, 1_000 + DECISION_TTL_MS + 1).is_none());
+
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn missing_cache_file_is_not_an_error() {
+    let path = std::env::temp_dir().join("ull-region-does-not-exist.json");
+    let _ = std::fs::remove_file(&path);
+    assert!(load_cached(&path, 0).is_none());
+}
diff --git a/crates/core/tests/download/resume_test.rs b/crates/core/tests/download/resume_test.rs
new file mode 100644
index 0000000..5c966fd
--- /dev/null
+++ b/crates/core/tests/download/resume_test.rs
@@ -0,0 +1,223 @@
+//! 断点续传保守判定的单测：矩阵覆盖 + 416 处理。
+
+use unlucky_core::download::resume::{
+    decide, on_range_unsatisfiable, RestartReason, ResumeDecision, ResumeMeta, Validator,
+};
+use unlucky_core::download::types::{HashAlgo, ResumePolicy};
+
+const URL: &str = "https://bmclapi2.bangbang93.com/versions/1.20.1/client.jar";
+const HASH: &str = "0123456789abcdef0123456789abcdef01234567";
+
+fn meta(url: &str) -> ResumeMeta {
+    ResumeMeta {
+        url: url.to_string(),
+        etag: Some("\"abc\"".to_string()),
+        last_modified: None,
+        total: Some(1_000),
+        algo: HashAlgo::Sha1,
+        hash: HASH.to_string(),
+        saved_at_ms: 1,
+    }
+}
+
+fn resume_ok(part_len: u64, meta: &ResumeMeta) -> ResumeDecision {
+    decide(
+        ResumePolicy::Conservative,
+        part_len,
+        Some(meta),
+        URL,
+        Some((HashAlgo::Sha1, HASH)),
+        Some(1_000),
+    )
+}
+
+#[test]
+fn resumes_when_everything_matches() {
+    let decision = resume_ok(400, &meta(URL));
+    assert_eq!(
+        decision,
+        ResumeDecision::Resume {
+            offset: 400,
+            validator: Validator {
+                etag: Some("\"abc\"".to_string()),
+                last_modified: None,
+            },
+        }
+    );
+}
+
+#[test]
+fn never_policy_and_missing_files_restart() {
+    let meta = meta(URL);
+    assert_eq!(
+        decide(
+            ResumePolicy::Never,
+            400,
+            Some(&meta),
+            URL,
+            Some((HashAlgo::Sha1, HASH)),
+            Some(1_000)
+        ),
+        ResumeDecision::Restart {
+            reason: RestartReason::PolicyNever
+        }
+    );
+    assert_eq!(
+        resume_ok(0, &meta),
+        ResumeDecision::Restart {
+            reason: RestartReason::EmptyPart
+        }
+    );
+    // 没有元数据：无法证明中间文件是同一次下载的产物。
+    assert_eq!(
+        decide(
+            ResumePolicy::Conservative,
+            400,
+            None,
+            URL,
+            Some((HashAlgo::Sha1, HASH)),
+            Some(1_000)
+        ),
+        ResumeDecision::Restart {
+            reason: RestartReason::NoMeta
+        }
+    );
+}
+
+#[test]
+fn changed_url_or_hash_restarts() {
+    assert_eq!(
+        decide(
+            ResumePolicy::Conservative,
+            400,
+            Some(&meta("https://other.example/client.jar")),
+            URL,
+            Some((HashAlgo::Sha1, HASH)),
+            Some(1_000)
+        ),
+        ResumeDecision::Restart {
+            reason: RestartReason::UrlChanged
+        }
+    );
+    assert_eq!(
+        decide(
+            ResumePolicy::Conservative,
+            400,
+            Some(&meta(URL)),
+            URL,
+            Some((HashAlgo::Sha1, "ffffffffffffffffffffffffffffffffffffffff")),
+            Some(1_000)
+        ),
+        ResumeDecision::Restart {
+            reason: RestartReason::HashChanged
+        }
+    );
+}
+
+#[test]
+fn unknown_total_or_oversize_restarts() {
+    let mut unknown = meta(URL);
+    unknown.total = None;
+    assert_eq!(
+        decide(
+            ResumePolicy::Conservative,
+            400,
+            Some(&unknown),
+            URL,
+            None,
+            None
+        ),
+        ResumeDecision::Restart {
+            reason: RestartReason::TotalUnknown
+        }
+    );
+
+    assert_eq!(
+        resume_ok(2_000, &meta(URL)),
+        ResumeDecision::Restart {
+            reason: RestartReason::Oversize
+        }
+    );
+}
+
+#[test]
+fn complete_part_skips_transfer() {
+    assert_eq!(
+        resume_ok(1_000, &meta(URL)),
+        ResumeDecision::Complete { size: 1_000 }
+    );
+}
+
+#[test]
+fn missing_validator_restarts() {
+    let mut weak = meta(URL);
+    weak.etag = None;
+    weak.last_modified = None;
+    assert_eq!(
+        resume_ok(400, &weak),
+        ResumeDecision::Restart {
+            reason: RestartReason::NoValidator
+        }
+    );
+    // Last-Modified 单独也能当校验器。
+    weak.last_modified = Some("Wed, 21 Oct 2015 07:28:00 GMT".to_string());
+    assert!(matches!(
+        resume_ok(400, &weak),
+        ResumeDecision::Resume { offset: 400, .. }
+    ));
+}
+
+#[test]
+fn expected_size_can_stand_in_for_missing_total() {
+    let mut unknown = meta(URL);
+    unknown.total = None;
+    let decision = decide(
+        ResumePolicy::Conservative,
+        400,
+        Some(&unknown),
+        URL,
+        Some((HashAlgo::Sha1, HASH)),
+        Some(1_000),
+    );
+    assert!(matches!(
+        decision,
+        ResumeDecision::Resume { offset: 400, .. }
+    ));
+}
+
+#[test]
+fn range_not_satisfiable_handling() {
+    // 已下满：直接进入校验，不要白删一个好文件。
+    assert_eq!(
+        on_range_unsatisfiable(1_000, Some(1_000)),
+        ResumeDecision::Complete { size: 1_000 }
+    );
+    // 没下满却 416：中间文件不可信，丢掉重来。
+    let decision = on_range_unsatisfiable(400, Some(1_000));
+    assert_eq!(
+        decision,
+        ResumeDecision::Restart {
+            reason: RestartReason::RangeUnsatisfiable
+        }
+    );
+    assert!(decision.should_drop_part());
+    // 不允许丢掉「已完成」的中间文件。
+    assert!(!ResumeDecision::Complete { size: 1 }.should_drop_part());
+}
+
+#[test]
+fn resume_meta_roundtrip_and_removal() {
+    let dir = std::env::temp_dir().join(format!("ull-resume-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).unwrap();
+    let path = dir.join("client.jar.ullpart.ullmeta.json");
+
+    let original = meta(URL);
+    original.save(&path).expect("写元数据失败");
+    assert_eq!(ResumeMeta::load(&path), Some(original));
+
+    ResumeMeta::remove(&path);
+    assert!(ResumeMeta::load(&path).is_none());
+
+    let _ = std::fs::remove_dir_all(&dir);
+}
diff --git a/crates/core/tests/download/support/mod.rs b/crates/core/tests/download/support/mod.rs
new file mode 100644
index 0000000..fb9330d
--- /dev/null
+++ b/crates/core/tests/download/support/mod.rs
@@ -0,0 +1,278 @@
+//! 测试支撑：临时目录、摘要工具、进程内极简 HTTP 服务器（零额外依赖）。
+//!
+//! 为什么自己写 mock server 而不用 wiremock：P0 阶段控制依赖面（Win7 Tier-3 构建 +
+//! 单文件体积），一个 60 行的 `TcpListener` 足够表达「成功 / 500 / 校验不符 / 无视 Range」。
+
+#![allow(dead_code)]
+
+use std::net::SocketAddr;
+use std::sync::atomic::{AtomicUsize, Ordering};
+use std::sync::Arc;
+
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+use tokio::net::{TcpListener, TcpStream};
+
+/// 断言用的小工具：唯一临时目录（进程内计数 + 时间戳，避免并行测试互相踩）。
+pub fn temp_dir(tag: &str) -> std::path::PathBuf {
+    static COUNTER: AtomicUsize = AtomicUsize::new(0);
+    let unique = COUNTER.fetch_add(1, Ordering::Relaxed);
+    let stamp = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map_or(0, |since| since.as_nanos());
+    let dir = std::env::temp_dir().join(format!("ull-download-test-{tag}-{stamp}-{unique}"));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).expect("创建临时目录失败");
+    dir
+}
+
+/// 算一段字节的 SHA-1（测试断言用）。
+pub fn sha1_hex(bytes: &[u8]) -> String {
+    use sha1::Digest;
+    let digest = sha1::Sha1::digest(bytes);
+    let mut out = String::with_capacity(40);
+    for byte in digest {
+        out.push_str(&format!("{byte:02x}"));
+    }
+    out
+}
+
+/// 目录里（不含子目录）所有中间文件家族的名字（`.ullpart` 与 `.ullmeta.json`）。
+pub fn part_files(dir: &std::path::Path) -> Vec<String> {
+    let Ok(entries) = std::fs::read_dir(dir) else {
+        return Vec::new();
+    };
+    let mut names: Vec<String> = entries
+        .flatten()
+        .map(|entry| entry.file_name().to_string_lossy().into_owned())
+        .filter(|name| name.contains(unlucky_core::download::PART_SUFFIX))
+        .collect();
+    names.sort();
+    names
+}
+
+/// 把文件的修改时间挪到「`age` 之前」（清理/收养的年龄判定用）。
+pub fn age_file(path: &std::path::Path, age: std::time::Duration) {
+    let times = std::fs::FileTimes::new().set_modified(std::time::SystemTime::now() - age);
+    std::fs::File::options()
+        .write(true)
+        .open(path)
+        .expect("打开待改 mtime 的文件失败")
+        .set_times(times)
+        .expect("改 mtime 失败");
+}
+
+/// mock 服务器给一次请求的应答。
+#[derive(Debug, Clone)]
+pub struct MockResponse {
+    /// HTTP 状态码。
+    pub status: u16,
+    /// 响应体。
+    pub body: Vec<u8>,
+    /// 是否声明 `Accept-Ranges: bytes` 并在收到 `Range` 时真的切段。
+    pub range_support: bool,
+    /// `ETag`（续传测试用）。
+    pub etag: Option<String>,
+    /// 返回 206 时故意把 `Content-Range` 写成从 0 开始（模拟段错位的坏服务器）。
+    pub lie_content_range: bool,
+}
+
+impl MockResponse {
+    /// 200 + 完整内容（支持 Range）。
+    pub fn ok(body: impl Into<Vec<u8>>) -> Self {
+        Self {
+            status: 200,
+            body: body.into(),
+            range_support: true,
+            etag: Some("\"v1\"".to_string()),
+            lie_content_range: false,
+        }
+    }
+
+    /// 固定状态码 + 空体。
+    pub fn status(status: u16) -> Self {
+        Self {
+            status,
+            body: Vec::new(),
+            range_support: false,
+            etag: None,
+            lie_content_range: false,
+        }
+    }
+
+    /// 声明不支持 Range（模拟部分镜像）。
+    pub fn without_range(mut self) -> Self {
+        self.range_support = false;
+        self
+    }
+
+    /// 206 但 `Content-Range` 谎报（模拟段错位的坏 CDN）。
+    pub fn with_wrong_content_range(mut self) -> Self {
+        self.lie_content_range = true;
+        self
+    }
+}
+
+/// 进程内极简 HTTP/1.1 服务器：按脚本顺序返回响应，脚本用尽后一律 500。
+pub struct MockServer {
+    addr: SocketAddr,
+    hits: Arc<AtomicUsize>,
+    handle: tokio::task::JoinHandle<()>,
+}
+
+impl MockServer {
+    /// 启动服务器（脚本是「每次请求一个响应」的队列）。
+    pub async fn start(script: Vec<MockResponse>) -> Self {
+        let listener = TcpListener::bind("127.0.0.1:0")
+            .await
+            .expect("绑定端口失败");
+        let addr = listener.local_addr().expect("取本地地址失败");
+        let hits = Arc::new(AtomicUsize::new(0));
+        let script = Arc::new(std::sync::Mutex::new(script));
+        let counter = Arc::clone(&hits);
+
+        let handle = tokio::spawn(async move {
+            loop {
+                let Ok((stream, _)) = listener.accept().await else {
+                    break;
+                };
+                let script = Arc::clone(&script);
+                let counter = Arc::clone(&counter);
+                tokio::spawn(async move {
+                    let index = counter.fetch_add(1, Ordering::Relaxed);
+                    let response = {
+                        let script = script.lock().unwrap_or_else(|err| err.into_inner());
+                        script.get(index).cloned()
+                    };
+                    let response = response.unwrap_or_else(|| MockResponse::status(500));
+                    let _ = serve(stream, response).await;
+                });
+            }
+        });
+
+        Self { addr, hits, handle }
+    }
+
+    /// 第 `index` 个请求该用的 URL（换成不同路径可模拟「不同源」）。
+    pub fn url(&self, path: &str) -> String {
+        format!("http://{}{}", self.addr, path)
+    }
+
+    /// 换 host 拼 URL（用 `localhost` vs `127.0.0.1` 造出两个不同源）。
+    pub fn url_with(&self, host: &str, path: &str) -> String {
+        format!("http://{host}:{}{}", self.addr.port(), path)
+    }
+
+    /// 端口号。
+    pub fn port(&self) -> u16 {
+        self.addr.port()
+    }
+
+    /// 已收到的请求数。
+    pub fn hits(&self) -> usize {
+        self.hits.load(Ordering::Relaxed)
+    }
+
+    /// 关停。
+    pub fn stop(self) {
+        self.handle.abort();
+    }
+}
+
+async fn serve(mut stream: TcpStream, response: MockResponse) -> std::io::Result<()> {
+    let mut buffer = Vec::new();
+    let mut chunk = [0_u8; 1024];
+    loop {
+        let read = stream.read(&mut chunk).await?;
+        if read == 0 {
+            break;
+        }
+        buffer.extend_from_slice(&chunk[..read]);
+        if buffer.windows(4).any(|window| window == b"\r\n\r\n") {
+            break;
+        }
+    }
+    let request = String::from_utf8_lossy(&buffer).to_ascii_lowercase();
+    let range = request
+        .lines()
+        .find_map(|line| line.strip_prefix("range: bytes="))
+        .map(str::trim)
+        .and_then(parse_range_header);
+
+    let total = response.body.len() as u64;
+    let (status, headers, body) = match (range, response.range_support) {
+        (Some((start, requested_end)), true) if start < total => {
+            // 尊重请求里的结束偏移（分块下载必须逐段精确，否则组装后长度对不上）。
+            let end = requested_end.unwrap_or(total - 1).min(total - 1);
+            let slice = response.body[start as usize..=end as usize].to_vec();
+            // 谎报模式：body 仍是正确的那一段，但头部声称从 0 开始（长度恰好 → 只有
+            // 严格比对 Content-Range 才抓得住）。
+            let (claimed_start, claimed_end) = if response.lie_content_range {
+                (0, slice.len().saturating_sub(1) as u64)
+            } else {
+                (start, end)
+            };
+            (
+                206,
+                vec![
+                    format!("Content-Range: bytes {claimed_start}-{claimed_end}/{total}"),
+                    format!("Content-Length: {}", slice.len()),
+                    "Accept-Ranges: bytes".to_string(),
+                ],
+                slice,
+            )
+        }
+        (Some(_), true) => (
+            416,
+            vec![
+                format!("Content-Range: bytes */{total}"),
+                "Content-Length: 0".to_string(),
+            ],
+            Vec::new(),
+        ),
+        _ => {
+            let mut headers = vec![format!("Content-Length: {total}")];
+            if response.range_support {
+                headers.push("Accept-Ranges: bytes".to_string());
+            }
+            (response.status, headers, response.body.clone())
+        }
+    };
+    let mut head = format!("HTTP/1.1 {status} {}\r\n", reason(status));
+    if let Some(etag) = &response.etag {
+        head.push_str(&format!("ETag: {etag}\r\n"));
+    }
+    for header in headers {
+        head.push_str(&header);
+        head.push_str("\r\n");
+    }
+    head.push_str("Connection: close\r\n\r\n");
+    stream.write_all(head.as_bytes()).await?;
+    stream.write_all(&body).await?;
+    stream.flush().await?;
+    Ok(())
+}
+
+/// 解析 `Range: bytes=<start>-<end>`（`end` 可缺省 = 到文件末尾）。
+fn parse_range_header(value: &str) -> Option<(u64, Option<u64>)> {
+    let (start, end) = value.split_once('-')?;
+    let start = start.trim().parse::<u64>().ok()?;
+    let end = end.trim();
+    let end = if end.is_empty() {
+        None
+    } else {
+        Some(end.parse::<u64>().ok()?)
+    };
+    Some((start, end))
+}
+
+fn reason(status: u16) -> &'static str {
+    match status {
+        200 => "OK",
+        206 => "Partial Content",
+        404 => "Not Found",
+        416 => "Range Not Satisfiable",
+        500 => "Internal Server Error",
+        503 => "Service Unavailable",
+        _ => "Status",
+    }
+}
diff --git a/crates/core/tests/game/arguments_rules.rs b/crates/core/tests/game/arguments_rules.rs
new file mode 100644
index 0000000..b7350af
--- /dev/null
+++ b/crates/core/tests/game/arguments_rules.rs
@@ -0,0 +1,256 @@
+//! 规则求值、参数展开、natives 选择（launch 直接消费这些结果）。
+
+use std::collections::BTreeMap;
+
+use unlucky_core::game::arguments::{
+    matches_simple_pattern, rules_allow, Argument, ArgumentValue, ConditionalArgument, Environment,
+    OsRestriction, Rule, RuleAction,
+};
+use unlucky_core::game::library::Library;
+
+use crate::helpers::parse;
+
+fn env(os: &str, arch: &str) -> Environment {
+    Environment {
+        os: os.to_owned(),
+        os_version: "10.0".to_owned(),
+        arch: arch.to_owned(),
+        features: BTreeMap::new(),
+    }
+}
+
+fn allow_os(name: &str) -> Rule {
+    Rule {
+        action: RuleAction::Allow,
+        os: Some(OsRestriction {
+            name: Some(name.to_owned()),
+            ..OsRestriction::default()
+        }),
+        features: None,
+    }
+}
+
+fn disallow_os(name: &str) -> Rule {
+    Rule {
+        action: RuleAction::Disallow,
+        ..allow_os(name)
+    }
+}
+
+#[test]
+fn empty_rules_always_allow() {
+    assert!(rules_allow(&[], &env("linux", "x86_64")));
+}
+
+#[test]
+fn allow_rule_must_match_environment() {
+    let rules = [allow_os("windows")];
+    assert!(rules_allow(&rules, &env("windows", "x86_64")));
+    assert!(!rules_allow(&rules, &env("linux", "x86_64")));
+}
+
+#[test]
+fn later_rules_override_earlier_ones() {
+    // 白名单语义：列表非空时从 DISALLOW 起步。
+    let allow_after_disallow = [disallow_os("windows"), allow_os("windows")];
+    assert!(rules_allow(
+        &allow_after_disallow,
+        &env("windows", "x86_64")
+    ));
+
+    let disallow_after_allow = [allow_os("windows"), disallow_os("windows")];
+    assert!(!rules_allow(
+        &disallow_after_allow,
+        &env("windows", "x86_64")
+    ));
+}
+
+#[test]
+fn feature_gate_blocks_argument() {
+    let mut features = BTreeMap::new();
+    features.insert("has_custom_resolution".to_owned(), true);
+    let rule = Rule {
+        action: RuleAction::Allow,
+        os: None,
+        features: Some(features),
+    };
+
+    let enabled = env("windows", "x86_64").with_feature("has_custom_resolution", true);
+    let disabled = env("windows", "x86_64");
+
+    assert_eq!(rule.action_in(&enabled), Some(RuleAction::Allow));
+    assert_eq!(rule.action_in(&disabled), None);
+}
+
+#[test]
+fn host_environment_is_mojang_shaped() {
+    let host = Environment::host();
+    assert!(matches!(host.os.as_str(), "windows" | "osx" | "linux"));
+    assert!(!host.arch.is_empty());
+    assert!(!host.feature("has_custom_resolution"));
+    // 空串是「没探」，真值来自 platform::os_info::current()；只要探得到就不能再是空的。
+    let probed = unlucky_core::platform::os_info::current();
+    assert_eq!(host.os_version, probed.os_version());
+    assert_eq!(host.os, probed.family.manifest_name());
+    assert_eq!(host.arch, probed.arch);
+}
+
+#[test]
+fn environment_from_an_injected_os_snapshot_carries_os_version() {
+    use unlucky_core::platform::linux_caps::SessionKind;
+    use unlucky_core::platform::os_info::{support_level_for, OsFamily, OsInfo};
+    use unlucky_core::platform::vk_probe::VkProbe;
+
+    let fake = OsInfo {
+        family: OsFamily::Windows,
+        arch: "x86_64".to_string(),
+        major_minor: Some((10, 0)),
+        build: Some(19_045),
+        product: "Windows 10".to_string(),
+        version_string: "10.0.19045".to_string(),
+        session: SessionKind::Unknown,
+        gl: unlucky_core::platform::linux_caps::GlProbe::Unknown,
+        vk: VkProbe::Available,
+        kernel: None,
+        glibc: None,
+        support_level: support_level_for(OsFamily::Windows, Some((10, 0)), None, None),
+    };
+
+    let environment = Environment::from_os_info(&fake);
+    assert_eq!(environment.os, "windows");
+    assert_eq!(environment.os_version, "10.0.19045");
+    assert_eq!(environment.arch, "x86_64");
+    assert!(environment.features.is_empty(), "注入快照不该带特性开关");
+
+    // 系统版本真的参与规则求值（这正是不再用空串的原因）。
+    let rule = Rule {
+        os: Some(OsRestriction {
+            name: None,
+            version: Some("^10\\.".to_string()),
+            arch: None,
+        }),
+        ..Rule::default()
+    };
+    assert_eq!(rule.action_in(&environment), Some(RuleAction::Allow));
+
+    let mac_rule = Rule {
+        os: Some(OsRestriction {
+            name: None,
+            version: Some("^11\\.".to_string()),
+            arch: None,
+        }),
+        ..Rule::default()
+    };
+    assert_eq!(mac_rule.action_in(&environment), None);
+}
+
+#[test]
+fn os_version_patterns_match_conservatively() {
+    assert!(matches_simple_pattern("^10\\.", "10.0"));
+    assert!(!matches_simple_pattern("^10\\.", "11.0"));
+    assert!(matches_simple_pattern("x86_64", "x86_64"));
+    assert!(!matches_simple_pattern("x86_64", "x86"));
+    assert!(matches_simple_pattern("10\\.0$", "10.0"));
+    // 不认识的复杂正则放宽为匹配（宁可多带参数也不漏参数）。
+    assert!(matches_simple_pattern("^(10|11)\\.", "11.0"));
+}
+
+#[test]
+fn expand_arguments_by_environment() {
+    let version = parse(
+        r#"{
+          "id": "x",
+          "arguments": {
+            "game": [
+              "--username",
+              { "rules": [{ "action": "allow", "features": { "is_demo_user": true } }],
+                "value": "--demo" },
+              { "value": ["--pair", "1"] }
+            ],
+            "jvm": [ "-Dfoo=1" ]
+          }
+        }"#,
+    );
+    let arguments = version.arguments.as_ref().expect("arguments 应解析");
+
+    let plain = arguments.expand(&env("windows", "x86_64"));
+    assert_eq!(plain.game, vec!["--username", "--pair", "1"]);
+    assert_eq!(plain.jvm, vec!["-Dfoo=1"]);
+
+    let demo = env("windows", "x86_64").with_feature("is_demo_user", true);
+    assert!(arguments.expand(&demo).game.contains(&"--demo".to_owned()));
+}
+
+#[test]
+fn conditional_argument_expands_single_value() {
+    let argument = Argument::Conditional(ConditionalArgument {
+        rules: vec![allow_os("windows")],
+        value: ArgumentValue::One("--single".to_owned()),
+    });
+    let mut out = Vec::new();
+    argument.expand_into(&env("windows", "x86_64"), &mut out);
+    assert_eq!(out, vec!["--single"]);
+
+    let mut out = Vec::new();
+    argument.expand_into(&env("linux", "x86_64"), &mut out);
+    assert!(out.is_empty());
+}
+
+#[test]
+fn native_classifier_expands_arch() {
+    let version = parse(
+        r#"{ "id": "x",
+             "libraries": [{
+               "name": "org.lwjgl:lwjgl:3.3.2",
+               "natives": { "windows": "natives-windows-${arch}", "linux": "natives-linux" },
+               "downloads": {
+                 "artifact": { "path": "org/lwjgl/lwjgl/3.3.2/lwjgl-3.3.2.jar" },
+                 "classifiers": {
+                   "natives-windows-64": { "path": "org/lwjgl/lwjgl/3.3.2/lwjgl-3.3.2-natives-windows-64.jar" }
+                 }
+               }
+             }]
+           }"#,
+    );
+    let library = &version.libraries.as_ref().expect("libraries 应解析")[0];
+
+    assert_eq!(
+        library.native_classifier(&env("windows", "x86_64")),
+        Some("natives-windows-64".to_owned())
+    );
+    assert_eq!(
+        library.native_classifier(&env("windows", "x86")),
+        Some("natives-windows-".to_owned())
+    );
+    assert_eq!(
+        library.native_classifier(&env("linux", "x86_64")),
+        Some("natives-linux".to_owned())
+    );
+    assert_eq!(library.native_classifier(&env("osx", "arm64")), None);
+
+    let classifier = "natives-windows-64";
+    assert!(library.native_artifact(classifier).is_some());
+    assert_eq!(
+        library
+            .native_relative_path(classifier)
+            .expect("路径应可推导"),
+        std::path::PathBuf::from("org/lwjgl/lwjgl/3.3.2/lwjgl-3.3.2-natives-windows-64.jar")
+    );
+}
+
+#[test]
+fn library_rules_and_local_hint() {
+    let library = Library {
+        name: "com.example:inst:1".to_owned(),
+        rules: vec![allow_os("linux")],
+        hint: Some("local".to_owned()),
+        ..Library::default()
+    };
+    assert!(library.applies(&env("linux", "x86_64")));
+    assert!(!library.applies(&env("windows", "x86_64")));
+    assert!(library.is_local());
+    assert_eq!(
+        library.relative_path().expect("路径应可推导"),
+        std::path::PathBuf::from("com/example/inst/1/inst-1.jar")
+    );
+}
diff --git a/crates/core/tests/game/helpers.rs b/crates/core/tests/game/helpers.rs
new file mode 100644
index 0000000..59461e2
--- /dev/null
+++ b/crates/core/tests/game/helpers.rs
@@ -0,0 +1,66 @@
+//! 测试公用件：fixture 解析、内存父版本表、临时目录守卫。
+
+use std::collections::BTreeMap;
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use unlucky_core::game::manifest::VersionJson;
+
+/// 解析 fixture JSON（fixture 是测试常量，解析失败即 panic）。
+pub fn parse(json: &str) -> VersionJson {
+    VersionJson::from_json_str(json).expect("fixture 必须可解析")
+}
+
+/// 用 `(id, json)` 对建内存父版本表，喂给 `inherit::resolve`。
+pub fn source(pairs: &[(&str, &str)]) -> BTreeMap<String, VersionJson> {
+    pairs
+        .iter()
+        .map(|(id, json)| ((*id).to_owned(), parse(json)))
+        .collect()
+}
+
+/// 唯一临时目录守卫：`drop` 时递归删除。
+pub struct TempDir {
+    path: PathBuf,
+}
+
+impl TempDir {
+    /// 建一个唯一临时目录。
+    pub fn new(tag: &str) -> Self {
+        static COUNTER: AtomicU64 = AtomicU64::new(0);
+        let nanos = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .map_or(0, |d| d.as_nanos());
+        let seq = COUNTER.fetch_add(1, Ordering::Relaxed);
+        let path = std::env::temp_dir().join(format!(
+            "ull-game-{tag}-{}-{nanos}-{seq}",
+            std::process::id()
+        ));
+        std::fs::create_dir_all(&path).expect("临时目录应可创建");
+        Self { path }
+    }
+
+    /// 目录路径。
+    pub fn path(&self) -> &Path {
+        &self.path
+    }
+}
+
+impl Drop for TempDir {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.path);
+    }
+}
+
+/// 建一个游戏根布局（纯路径计算，不建目录）。
+pub fn layout(root: &Path) -> unlucky_core::game::GameLayout {
+    unlucky_core::game::GameLayout::new(root)
+}
+
+/// 造 `dir/<name>` 并写一个文件进去（模拟玩家内容：`mods`/`saves`/`config` 的条目）。
+pub fn seed(dir: &Path, name: &str) {
+    let target = dir.join(name);
+    std::fs::create_dir_all(&target).expect("建目录");
+    std::fs::write(target.join("entry.txt"), b"x").expect("写文件");
+}
diff --git a/crates/core/tests/game/inherit_chain.rs b/crates/core/tests/game/inherit_chain.rs
new file mode 100644
index 0000000..1172572
--- /dev/null
+++ b/crates/core/tests/game/inherit_chain.rs
@@ -0,0 +1,265 @@
+//! `inheritsFrom` 解析：逐字段 merge 语义、patch 优先级、环检测、缺失父版本。
+
+use unlucky_core::game::error::GameError;
+use unlucky_core::game::inherit::{apply_patches, merge, resolve, sorted_patches};
+use unlucky_core::game::version::ReleaseType;
+
+use crate::helpers::{parse, source};
+
+const VANILLA: &str = r#"{
+  "id": "1.20.1",
+  "type": "release",
+  "releaseTime": "2023-06-12T13:25:51+00:00",
+  "mainClass": "net.minecraft.client.main.Main",
+  "minecraftArguments": "--username ${auth_player_name}",
+  "assets": "5",
+  "assetIndex": { "id": "5" },
+  "complianceLevel": 1,
+  "minimumLauncherVersion": 21,
+  "javaVersion": { "component": "java-runtime-gamma", "majorVersion": 17 },
+  "libraries": [ { "name": "lib:a:1" }, { "name": "lib:b:1" } ],
+  "downloads": {
+    "client": { "url": "https://example.invalid/client.jar", "sha1": "c", "size": 1 },
+    "server": { "url": "https://example.invalid/server.jar", "sha1": "s", "size": 1 }
+  },
+  "arguments": { "game": ["--game-parent"], "jvm": ["-Dparent=1"] },
+  "logging": { "client": { "argument": "-Dlog4j", "file": { "id": "client-1.12.xml" } } }
+}"#;
+
+const FORGE: &str = r#"{
+  "id": "1.20.1-forge-47.2.0",
+  "inheritsFrom": "1.20.1",
+  "mainClass": "cpw.mods.bootstraplauncher.BootstrapLauncher",
+  "time": "2024-01-01T00:00:00+00:00",
+  "minimumLauncherVersion": 14,
+  "javaVersion": { "component": "java-runtime-delta", "majorVersion": 21 },
+  "libraries": [ { "name": "net.minecraftforge:forge:1" } ],
+  "downloads": { "server": { "url": "https://example.invalid/server2.jar" } },
+  "arguments": { "game": ["--game-child"], "jvm": ["-Dchild=1"] }
+}"#;
+
+fn vanilla_and_forge(
+) -> std::collections::BTreeMap<String, unlucky_core::game::manifest::VersionJson> {
+    source(&[("1.20.1", VANILLA), ("1.20.1-forge-47.2.0", FORGE)])
+}
+
+#[test]
+fn merge_table_follows_analyse_03() {
+    let sources = vanilla_and_forge();
+    let child = parse(FORGE);
+    let resolved = resolve(&sources, &child).expect("继承链应可解析");
+
+    // 子覆盖父。
+    assert_eq!(
+        resolved.main_class.as_deref(),
+        Some("cpw.mods.bootstraplauncher.BootstrapLauncher")
+    );
+    // 子没写就继承父。
+    assert_eq!(
+        resolved.minecraft_arguments.as_deref(),
+        Some("--username ${auth_player_name}")
+    );
+    assert_eq!(resolved.assets.as_deref(), Some("5"));
+    assert_eq!(resolved.version_type, Some(ReleaseType::Release));
+
+    // arguments 父在前、子在后追加。
+    let arguments = resolved.arguments.as_ref().expect("arguments 应保留");
+    assert_eq!(arguments.game.len(), 2);
+    assert_eq!(arguments.jvm.len(), 2);
+
+    // libraries 父在前、子在后。
+    let libraries = resolved.libraries.as_ref().expect("libraries 应保留");
+    let names: Vec<&str> = libraries.iter().map(|l| l.name.as_str()).collect();
+    assert_eq!(
+        names,
+        vec!["lib:a:1", "lib:b:1", "net.minecraftforge:forge:1"]
+    );
+
+    // downloads 整体覆盖：子只写 server，client 就没了（非直觉点 1，必须显式守门）。
+    let downloads = resolved.downloads.as_ref().expect("downloads 应存在");
+    assert!(downloads.client().is_none(), "整体覆盖会让父层 client 消失");
+    assert_eq!(
+        downloads.server().and_then(|s| s.url.as_deref()),
+        Some("https://example.invalid/server2.jar")
+    );
+
+    // complianceLevel 只取子（非直觉点 2）：父层 1 被丢弃。
+    assert_eq!(resolved.compliance_level, None);
+
+    // javaVersion 子覆盖父。
+    let java = resolved.java_version.as_ref().expect("javaVersion 应存在");
+    assert_eq!(java.major_version, Some(21));
+
+    // minimumLauncherVersion 取 max(21, 14)=21。
+    assert_eq!(resolved.minimum_launcher_version, Some(21));
+
+    // logging 子没有 → 继承父。
+    assert!(resolved.logging.is_some());
+
+    // 解析结果的不变量。
+    assert_eq!(resolved.jar.as_deref(), Some("1.20.1-forge-47.2.0"));
+    assert!(resolved.inherits_from.is_none());
+    assert!(resolved.patches.is_none());
+    assert_eq!(resolved.root, Some(true));
+    assert!(resolved.is_resolved());
+}
+
+#[test]
+fn three_level_chain_orders_ancestor_first() {
+    const A: &str = r#"{ "id": "a", "mainClass": "a.Main", "libraries": [{ "name": "l:a:1" }] }"#;
+    const B: &str = r#"{ "id": "b", "inheritsFrom": "a", "libraries": [{ "name": "l:b:1" }] }"#;
+    const C: &str = r#"{ "id": "c", "inheritsFrom": "b", "mainClass": "c.Main",
+                        "libraries": [{ "name": "l:c:1" }] }"#;
+    let sources = source(&[("a", A), ("b", B), ("c", C)]);
+
+    let resolved = resolve(&sources, &parse(C)).expect("三层链应可解析");
+
+    assert_eq!(resolved.main_class.as_deref(), Some("c.Main"));
+    let names: Vec<&str> = resolved
+        .libraries
+        .as_ref()
+        .expect("libraries 应存在")
+        .iter()
+        .map(|l| l.name.as_str())
+        .collect();
+    assert_eq!(names, vec!["l:a:1", "l:b:1", "l:c:1"]);
+}
+
+#[test]
+fn patch_priority_sorts_ascending() {
+    let root = parse(
+        r#"{
+          "id": "patched",
+          "inheritsFrom": "1.20.1",
+          "patches": [
+            { "id": "forge", "priority": 30000, "mainClass": "loader.Main",
+              "libraries": [{ "name": "loader:a:1" }] },
+            { "id": "base", "mainClass": "base.Main",
+              "arguments": { "game": ["--base"] } }
+          ]
+        }"#,
+    );
+    let resolved = resolve(&vanilla_and_forge(), &root).expect("带 patches 的清单应可解析");
+
+    // 无 priority 的补丁排最前（Integer.MIN_VALUE 语义），loader 后合并 → 覆盖 mainClass。
+    assert_eq!(resolved.main_class.as_deref(), Some("loader.Main"));
+    let libraries = resolved.libraries.as_ref().expect("libraries 应存在");
+    assert_eq!(
+        libraries.last().map(|l| l.name.as_str()),
+        Some("loader:a:1")
+    );
+
+    let arguments = resolved.arguments.as_ref().expect("arguments 应存在");
+    let flat: Vec<String> = arguments.game.iter().map(|a| format!("{a:?}")).collect();
+    assert!(flat.iter().any(|a| a.contains("--base")));
+}
+
+#[test]
+fn equal_priority_patches_keep_insertion_order() {
+    let root = parse(
+        r#"{
+          "id": "patched",
+          "patches": [
+            { "id": "first", "priority": 10, "mainClass": "first.Main" },
+            { "id": "second", "priority": 10, "mainClass": "second.Main" }
+          ]
+        }"#,
+    );
+    let resolved = resolve(&source(&[]), &root).expect("无继承的清单应可解析");
+    assert_eq!(
+        resolved.main_class.as_deref(),
+        Some("second.Main"),
+        "同优先级按插入顺序合并，后者覆盖前者"
+    );
+}
+
+#[test]
+fn sorted_patches_puts_missing_priority_first() {
+    let patches = vec![
+        parse(r#"{ "id": "loader", "priority": 30000 }"#),
+        parse(r#"{ "id": "base" }"#),
+        parse(r#"{ "id": "mc", "priority": 0 }"#),
+    ];
+    let order: Vec<&str> = sorted_patches(&patches)
+        .iter()
+        .filter_map(|p| p.id.as_deref())
+        .collect();
+    assert_eq!(order, vec!["base", "mc", "loader"]);
+}
+
+#[test]
+fn apply_patches_stacks_layers() {
+    let base =
+        parse(r#"{ "id": "root", "mainClass": "base.Main", "libraries": [{ "name": "l:a:1" }] }"#);
+    let patched = apply_patches(
+        base,
+        &[parse(
+            r#"{ "id": "loader", "priority": 30000, "mainClass": "loader.Main",
+                      "libraries": [{ "name": "l:loader:1" }] }"#,
+        )],
+    );
+    assert_eq!(patched.main_class.as_deref(), Some("loader.Main"));
+    let names: Vec<&str> = patched
+        .libraries
+        .as_ref()
+        .expect("libraries 应存在")
+        .iter()
+        .map(|l| l.name.as_str())
+        .collect();
+    assert_eq!(names, vec!["l:a:1", "l:loader:1"]);
+}
+
+#[test]
+fn circular_inheritance_is_reported() {
+    let sources = source(&[
+        ("a", r#"{ "id": "a", "inheritsFrom": "b" }"#),
+        ("b", r#"{ "id": "b", "inheritsFrom": "a" }"#),
+    ]);
+    let error = resolve(&sources, &parse(r#"{ "id": "a", "inheritsFrom": "b" }"#))
+        .expect_err("成环必须报错而不是静默降级");
+    match error {
+        GameError::CircularInheritance { chain } => {
+            assert_eq!(chain, vec!["a", "b", "a"], "链要能看出环的位置");
+        }
+        other => panic!("期望 CircularInheritance，得到 {other:?}"),
+    }
+}
+
+#[test]
+fn missing_parent_is_reported() {
+    let error = resolve(&source(&[]), &parse(FORGE)).expect_err("缺失父版本必须报错");
+    match error {
+        GameError::MissingParent {
+            parent,
+            required_by,
+        } => {
+            assert_eq!(parent, "1.20.1");
+            assert_eq!(required_by, "1.20.1-forge-47.2.0");
+        }
+        other => panic!("期望 MissingParent，得到 {other:?}"),
+    }
+}
+
+#[test]
+fn manifest_without_id_is_rejected() {
+    let error =
+        resolve(&source(&[]), &parse(r#"{ "mainClass": "a.B" }"#)).expect_err("缺 id 应报错");
+    assert!(matches!(error, GameError::MissingVersionId));
+}
+
+#[test]
+fn merge_preserves_unknown_fields_with_child_winning() {
+    let parent = parse(r#"{ "id": "p", "customParentOnly": 1, "shared": "parent" }"#);
+    let child = parse(r#"{ "id": "c", "shared": "child" }"#);
+    let merged = merge(&child, &parent);
+
+    assert_eq!(
+        merged.extra.get("customParentOnly"),
+        Some(&serde_json::json!(1))
+    );
+    assert_eq!(
+        merged.extra.get("shared"),
+        Some(&serde_json::json!("child"))
+    );
+    assert_eq!(merged.id.as_deref(), Some("c"));
+}
diff --git a/crates/core/tests/game/isolation.rs b/crates/core/tests/game/isolation.rs
new file mode 100644
index 0000000..7e0e96f
--- /dev/null
+++ b/crates/core/tests/game/isolation.rs
@@ -0,0 +1,194 @@
+//! D20 实例隔离：覆盖链派生、双侧切换检测、稀疏落盘不变量。
+//!
+//! 对应 mission 的验收点：三档派生 / 覆盖链优先级 / 切换检测（双侧空、单侧、双侧）/
+//! `inherit` 不落盘 / 恒共享层不可配。
+
+use std::path::Path;
+
+use unlucky_core::game::install::instance::{InstanceConfig, Isolation};
+use unlucky_core::game::isolation::{
+    derive_game_dir, probe_both_sides, probe_side, IsolationMode, IsolationSource,
+    PROBED_CONTENT_DIRS, SHARED_LAYERS,
+};
+use unlucky_core::game::GameError;
+
+use super::helpers::{layout, seed, TempDir};
+
+// ---------------------------------------------------------------- 派生（三档）
+
+#[test]
+fn isolated_mode_derives_version_dir() {
+    let temp = TempDir::new("iso-derived");
+    let game = layout(temp.path());
+    let derived = derive_game_dir(&game, "1.20.1", IsolationMode::Isolated, None, None)
+        .expect("isolated 一定能派生");
+    assert_eq!(derived.isolation, Isolation::Isolated);
+    assert_eq!(derived.game_dir, game.version_dir("1.20.1"));
+    assert_eq!(derived.source, IsolationSource::Global);
+}
+
+#[test]
+fn shared_mode_derives_game_root() {
+    let temp = TempDir::new("iso-shared");
+    let game = layout(temp.path());
+    let derived = derive_game_dir(&game, "1.20.1", IsolationMode::Shared, None, None)
+        .expect("shared 一定能派生");
+    assert_eq!(derived.isolation, Isolation::Shared);
+    assert_eq!(derived.game_dir, game.root());
+}
+
+#[test]
+fn custom_mode_uses_instance_game_dir() {
+    let temp = TempDir::new("iso-custom");
+    let game = layout(temp.path());
+    let custom = temp.path().join("elsewhere").join("farm");
+    let mut config = InstanceConfig::new("id-1", "1.20.1");
+    config.isolation = Some(Isolation::Custom);
+    config.game_dir = Some(custom.clone());
+    let derived = derive_game_dir(
+        &game,
+        "1.20.1",
+        IsolationMode::Isolated,
+        Some(&config),
+        None,
+    )
+    .expect("custom 有目录就能派生");
+    assert_eq!(derived.isolation, Isolation::Custom);
+    assert_eq!(derived.game_dir, custom);
+    assert_eq!(derived.source, IsolationSource::Instance);
+}
+
+#[test]
+fn custom_without_game_dir_is_an_error() {
+    let temp = TempDir::new("iso-custom-missing");
+    let game = layout(temp.path());
+    let mut config = InstanceConfig::new("id-missing", "1.20.1");
+    config.isolation = Some(Isolation::Custom);
+    let error = derive_game_dir(
+        &game,
+        "1.20.1",
+        IsolationMode::Isolated,
+        Some(&config),
+        None,
+    )
+    .expect_err("custom 缺目录必须报错，不许猜默认值");
+    assert!(matches!(error, GameError::CustomIsolationWithoutDir { .. }));
+    assert!(error.to_string().contains("id-missing"), "{error}");
+}
+
+// ------------------------------------------------------------ 覆盖链（优先级）
+
+#[test]
+fn instance_isolation_beats_global_mode() {
+    let temp = TempDir::new("iso-priority");
+    let game = layout(temp.path());
+    let mut config = InstanceConfig::new("id-2", "1.20.1");
+    config.isolation = Some(Isolation::Shared);
+    let derived = derive_game_dir(
+        &game,
+        "1.20.1",
+        IsolationMode::Isolated,
+        Some(&config),
+        None,
+    )
+    .expect("派生");
+    assert_eq!(derived.isolation, Isolation::Shared);
+    assert_eq!(derived.game_dir, game.root());
+    assert_eq!(derived.source, IsolationSource::Instance);
+}
+
+#[test]
+fn inherit_falls_back_to_global_mode() {
+    let temp = TempDir::new("iso-inherit");
+    let game = layout(temp.path());
+    let config = InstanceConfig::new("id-3", "1.20.1");
+    assert!(config.inherits_isolation(), "新实例默认 inherit");
+    for (mode, expected) in [
+        (IsolationMode::Isolated, game.version_dir("1.20.1")),
+        (IsolationMode::Shared, game.root().to_path_buf()),
+    ] {
+        let derived = derive_game_dir(&game, "1.20.1", mode, Some(&config), None).expect("派生");
+        assert_eq!(
+            derived.game_dir,
+            expected,
+            "全局 {} 应决定 inherit",
+            mode.as_str()
+        );
+        assert_eq!(derived.source, IsolationSource::Global);
+    }
+}
+
+#[test]
+fn temporary_override_wins_over_everything() {
+    let temp = TempDir::new("iso-temporary");
+    let game = layout(temp.path());
+    let mut config = InstanceConfig::new("id-4", "1.20.1");
+    config.isolation = Some(Isolation::Isolated);
+    let forced = temp.path().join("forced");
+    let derived = derive_game_dir(
+        &game,
+        "1.20.1",
+        IsolationMode::Shared,
+        Some(&config),
+        Some(&forced),
+    )
+    .expect("派生");
+    assert_eq!(derived.game_dir, forced);
+    assert_eq!(derived.source, IsolationSource::Temporary);
+    // 档位本身仍是实例档位（临时参数只改目录，不改语义）。
+    assert_eq!(derived.isolation, Isolation::Isolated);
+
+    // 空路径 = 没给临时参数。
+    let derived = derive_game_dir(
+        &game,
+        "1.20.1",
+        IsolationMode::Shared,
+        Some(&config),
+        Some(Path::new("")),
+    )
+    .expect("派生");
+    assert_eq!(derived.source, IsolationSource::Instance);
+}
+
+#[test]
+fn shared_layers_are_fixed_and_unconfigurable() {
+    assert_eq!(SHARED_LAYERS, ["versions", "assets", "libraries"]);
+    // natives 不在恒共享层里：它按实例解包（两家启动器一致）。
+    assert!(!SHARED_LAYERS.contains(&"natives"));
+    assert_eq!(PROBED_CONTENT_DIRS, ["mods", "saves", "config"]);
+}
+
+// -------------------------------------------------------------- 切换检测（探测）
+
+#[test]
+fn probe_counts_only_player_content() {
+    let temp = TempDir::new("iso-probe");
+    seed(temp.path(), "mods");
+    seed(temp.path(), "saves");
+    seed(temp.path(), "screenshots");
+    let side = probe_side(temp.path()).expect("探测");
+    assert_eq!(side.entries, 2, "screenshots 不算玩家内容");
+    assert!(side.occupied());
+}
+
+#[test]
+fn probe_missing_dir_counts_as_zero() {
+    let temp = TempDir::new("iso-probe-empty");
+    let side = probe_side(&temp.path().join("nope")).expect("目录不存在不算错误");
+    assert_eq!(side.entries, 0);
+    assert!(!side.occupied());
+}
+
+#[test]
+fn probe_both_sides_reads_isolated_and_shared() {
+    let temp = TempDir::new("iso-probe-both");
+    let game = layout(temp.path());
+    seed(&game.version_dir("1.20.1"), "saves");
+    seed(game.root(), "mods");
+    seed(game.root(), "config");
+    let (isolated, shared) = probe_both_sides(&game, "1.20.1").expect("探测");
+    assert_eq!(isolated.entries, 1);
+    assert_eq!(shared.entries, 2);
+    assert_eq!(isolated.path, game.version_dir("1.20.1"));
+    assert_eq!(shared.path, game.root());
+}
diff --git a/crates/core/tests/game/isolation_switch.rs b/crates/core/tests/game/isolation_switch.rs
new file mode 100644
index 0000000..80dba99
--- /dev/null
+++ b/crates/core/tests/game/isolation_switch.rs
@@ -0,0 +1,222 @@
+//! D20 切换检测与稀疏落盘：observe/warn 语义、`inherit` 与 `lastModeChange` 不落盘、
+//! 旧字面量读兼容（从 `isolation.rs` 拆出，保持单文件 ≤400 行）。
+
+use std::path::PathBuf;
+
+use unlucky_core::game::install::instance::{InstanceConfig, Isolation};
+use unlucky_core::game::isolation::{
+    derive_game_dir, observe_mode, IsolationMode, IsolationSource,
+};
+
+use super::helpers::{layout, seed, TempDir};
+
+// ------------------------------------------------- 切换记录（幂等 + 只提示一次）
+
+#[test]
+fn observe_mode_records_baseline_without_warning() {
+    let temp = TempDir::new("iso-observe-baseline");
+    let game = layout(temp.path());
+    seed(game.root(), "saves");
+    let mut config = InstanceConfig::new("id-5", "1.20.1");
+    let changed = observe_mode(
+        &mut config,
+        &game,
+        "2026-10-30T00:00:00Z",
+        Isolation::Isolated,
+    )
+    .expect("观察");
+    assert!(changed, "首次观察要建基线");
+    let change = config.last_mode_change.clone().expect("基线");
+    assert_eq!(change.from, change.to);
+    assert!(!change.is_real_change());
+    assert!(change.warned, "基线不该弹提示");
+    assert_eq!(change.probe.shared_side, 1);
+    assert!(
+        config.take_mode_change_warning().is_none(),
+        "基线即使两侧都有内容也不提示"
+    );
+}
+
+#[test]
+fn observe_mode_is_idempotent() {
+    let temp = TempDir::new("iso-observe-idempotent");
+    let game = layout(temp.path());
+    let mut config = InstanceConfig::new("id-6", "1.20.1");
+    assert!(
+        observe_mode(&mut config, &game, "t1", Isolation::Isolated).expect("观察"),
+        "首次写入"
+    );
+    assert!(
+        !observe_mode(&mut config, &game, "t2", Isolation::Isolated).expect("观察"),
+        "同一档位不重复记"
+    );
+    assert_eq!(
+        config.last_mode_change.expect("记录仍在").at,
+        "t1",
+        "时间戳不该被刷新"
+    );
+}
+
+#[test]
+fn mode_change_with_both_sides_warns_exactly_once() {
+    let temp = TempDir::new("iso-warn-once");
+    let game = layout(temp.path());
+    seed(&game.version_dir("1.20.1"), "saves");
+    seed(&game.version_dir("1.20.1"), "mods");
+    seed(game.root(), "saves");
+    let mut config = InstanceConfig::new("id-7", "1.20.1");
+    config.isolation = Some(Isolation::Shared);
+    observe_mode(&mut config, &game, "t0", Isolation::Shared).expect("基线");
+    config.isolation = Some(Isolation::Isolated);
+    assert!(
+        observe_mode(&mut config, &game, "t1", Isolation::Isolated).expect("记切换"),
+        "档位变了要写记录"
+    );
+    let change = config.last_mode_change.clone().expect("记录");
+    assert_eq!(change.from, Isolation::Shared);
+    assert_eq!(change.to, Isolation::Isolated);
+    assert!(change.is_real_change());
+    assert_eq!(change.probe.isolated_side, 2);
+    assert_eq!(change.probe.shared_side, 1);
+
+    let warning = config
+        .take_mode_change_warning()
+        .expect("两侧都有内容要提示");
+    assert!(warning.probe.both_occupied());
+    let message = warning.message();
+    assert!(message.contains("isolated"), "{message}");
+    assert!(
+        message.contains("不会自动搬"),
+        "文案必须说清不迁移：{message}"
+    );
+    assert!(
+        config.take_mode_change_warning().is_none(),
+        "同一次切换只提示一次"
+    );
+    assert!(config.last_mode_change.expect("记录").warned);
+}
+
+#[test]
+fn mode_change_with_one_empty_side_is_quiet() {
+    let temp = TempDir::new("iso-warn-single-side");
+    let game = layout(temp.path());
+    // 只有共享侧有内容：隔离侧空 → 不提示（切到共享还能看见存档，反之亦然）。
+    seed(game.root(), "saves");
+    let mut config = InstanceConfig::new("id-8", "1.20.1");
+    observe_mode(&mut config, &game, "t0", Isolation::Shared).expect("基线");
+    observe_mode(&mut config, &game, "t1", Isolation::Isolated).expect("记切换");
+    assert!(config.take_mode_change_warning().is_none());
+
+    // 两侧都空同样安静。
+    let empty = TempDir::new("iso-warn-both-empty");
+    let game = layout(empty.path());
+    let mut config = InstanceConfig::new("id-9", "1.20.1");
+    observe_mode(&mut config, &game, "t0", Isolation::Shared).expect("基线");
+    observe_mode(&mut config, &game, "t1", Isolation::Isolated).expect("记切换");
+    assert!(config.take_mode_change_warning().is_none());
+}
+
+// -------------------------------------------------------------- 稀疏落盘不变量
+
+#[test]
+fn inherit_and_no_change_stay_out_of_the_file() {
+    let config = InstanceConfig::new("id-10", "1.20.1");
+    let json = config.to_json_string().expect("序列化");
+    assert!(!json.contains("isolation"), "inherit 不许落盘：{json}");
+    assert!(!json.contains("lastModeChange"), "没切过就不写：{json}");
+    assert!(!json.contains("gameDir"), "没目录就不写：{json}");
+    let back = InstanceConfig::from_json_str(&json).expect("回读");
+    assert_eq!(back, config);
+}
+
+#[test]
+fn last_mode_change_round_trips_in_camel_case() {
+    let temp = TempDir::new("iso-roundtrip");
+    let game = layout(temp.path());
+    let mut config = InstanceConfig::new("id-11", "1.20.1");
+    observe_mode(&mut config, &game, "t0", Isolation::Shared).expect("基线");
+    let json = config.to_json_string().expect("序列化");
+    assert!(json.contains("\"lastModeChange\""), "{json}");
+    assert!(json.contains("\"isolatedSide\""), "{json}");
+    assert!(json.contains("\"sharedSide\""), "{json}");
+    let back = InstanceConfig::from_json_str(&json).expect("回读");
+    assert_eq!(back, config);
+}
+
+#[test]
+fn legacy_per_version_value_reads_as_isolated() {
+    let raw = r#"{
+        "id": "id-12",
+        "versionId": "1.20.1",
+        "isolation": "per_version"
+    }"#;
+    let config = InstanceConfig::from_json_str(raw).expect("旧字面量读兼容");
+    assert_eq!(config.isolation, Some(Isolation::Isolated));
+    assert_eq!(Isolation::parse("per_version"), Some(Isolation::Isolated));
+    assert_eq!(Isolation::parse("isolated"), Some(Isolation::Isolated));
+    assert_eq!(Isolation::parse("nonsense"), None);
+}
+
+#[test]
+fn effective_isolation_resolves_inherit() {
+    let config = InstanceConfig::new("id-13", "1.20.1");
+    assert_eq!(
+        config.effective_isolation(IsolationMode::Shared),
+        Isolation::Shared
+    );
+    let mut config = InstanceConfig::new("id-14", "1.20.1");
+    config.isolation = Some(Isolation::Custom);
+    assert_eq!(
+        config.effective_isolation(IsolationMode::Isolated),
+        Isolation::Custom
+    );
+}
+
+#[test]
+fn custom_dir_from_relative_path_is_kept_verbatim() {
+    // custom 目录不做规范化（可能是相对路径或系统符号链接），派生层只透传。
+    let temp = TempDir::new("iso-custom-relative");
+    let game = layout(temp.path());
+    let mut config = InstanceConfig::new("id-15", "1.20.1");
+    config.isolation = Some(Isolation::Custom);
+    config.game_dir = Some(PathBuf::from("relative/mc"));
+    let derived = derive_game_dir(
+        &game,
+        "1.20.1",
+        IsolationMode::Isolated,
+        Some(&config),
+        None,
+    )
+    .expect("派生");
+    assert_eq!(derived.game_dir, PathBuf::from("relative/mc"));
+}
+
+#[test]
+fn explicit_inherit_reads_back_as_absent() {
+    // 回归 P2-2（review r1）：schema 允许写 `"isolation": "inherit"`，
+    // 读路径必须把它折叠成「键不存在」，否则设置层写回默认值后启动会报 unknown variant。
+    let raw = r#"{
+        "id": "id-16",
+        "versionId": "1.20.1",
+        "isolation": "inherit"
+    }"#;
+    let config = InstanceConfig::from_json_str(raw).expect("显式 inherit 必须能读");
+    assert!(config.inherits_isolation());
+    assert_eq!(config.isolation, None);
+    let json = config.to_json_string().expect("序列化");
+    assert!(
+        !json.contains("isolation"),
+        "写回时把 inherit 落成键缺失：{json}"
+    );
+    // 走到派生层就是「跟随全局」，不再是错误路径。
+    let temp = TempDir::new("iso-inherit-explicit");
+    let game = layout(temp.path());
+    let derived =
+        derive_game_dir(&game, "1.20.1", IsolationMode::Shared, Some(&config), None).expect("派生");
+    assert_eq!(derived.isolation, Isolation::Shared);
+    assert_eq!(derived.source, IsolationSource::Global);
+
+    // 其他非法字面量仍然报错（不静默取默认值）。
+    let bad = r#"{ "id": "id-17", "versionId": "1.20.1", "isolation": "maybe" }"#;
+    assert!(InstanceConfig::from_json_str(bad).is_err());
+}
diff --git a/crates/core/tests/game/java_discover.rs b/crates/core/tests/game/java_discover.rs
new file mode 100644
index 0000000..dd18892
--- /dev/null
+++ b/crates/core/tests/game/java_discover.rs
@@ -0,0 +1,129 @@
+//! `core::game::java::discover`：标准安装位置扫描与来源优先级。
+//!
+//! 真机上扫到什么取决于本机装了什么，所以断言只钉**不变量**：
+//! 扫描结果形状、来源优先级（env 胜过扫盘）、去重保留高优先级、缺目录不报错。
+
+use unlucky_core::game::java::discover;
+use unlucky_core::game::java::mapping::{JavaRequirement, RequirementSource};
+use unlucky_core::game::java::{pick, JavaOrigin, JavaRuntime};
+
+fn runtime(path: &str, major: u32, origin: JavaOrigin) -> JavaRuntime {
+    JavaRuntime {
+        binary: std::path::PathBuf::from(path),
+        origin,
+        version: Some(format!("openjdk version \"{major}.0.1\"")),
+        major: Some(major),
+        bits: 64,
+        vendor: None,
+    }
+}
+
+fn at_least(minimum: u32) -> JavaRequirement {
+    JavaRequirement::new(minimum, None, RequirementSource::Table)
+}
+
+#[test]
+fn scanned_paths_always_point_at_a_java_binary() {
+    // 本机可能一个都没有（裸机/容器）——那也算通过，只是列表为空。
+    for binary in discover::scan_java_binaries() {
+        assert!(
+            binary.is_file(),
+            "扫描结果必须是真实存在的文件：{}",
+            binary.display()
+        );
+        assert_eq!(
+            binary
+                .file_name()
+                .map(|name| name.to_string_lossy().into_owned()),
+            Some(unlucky_core::game::java::java_binary_name().to_string()),
+            "扫描结果必须是 bin/java[.exe]：{}",
+            binary.display()
+        );
+    }
+}
+
+#[test]
+fn standard_roots_are_absolute_and_unique() {
+    let roots = discover::standard_roots();
+    for root in &roots {
+        assert!(
+            root.is_absolute(),
+            "候选根必须是绝对路径：{}",
+            root.display()
+        );
+    }
+    let mut keys: Vec<String> = roots.iter().map(|root| discover::path_key(root)).collect();
+    let total = keys.len();
+    keys.sort();
+    keys.dedup();
+    assert_eq!(keys.len(), total, "候选根不该重复");
+}
+
+#[test]
+fn environment_java_beats_scanned_java_when_both_satisfy() {
+    // D13 的「优先级链不变」：环境变量是用户意图，扫盘只是候选。
+    let candidates = [
+        runtime(
+            "C:/Program Files/Eclipse Adoptium/jdk-21/bin/java.exe",
+            21,
+            JavaOrigin::System,
+        ),
+        runtime(
+            "C:/Program Files/Microsoft/jdk-21/bin/java.exe",
+            21,
+            JavaOrigin::JavaHome,
+        ),
+    ];
+    let picked = pick(&candidates, &at_least(17)).expect("应有候选");
+    assert_eq!(picked.origin, JavaOrigin::JavaHome);
+}
+
+#[test]
+fn scanned_java_is_still_used_when_nothing_else_matches() {
+    // MSI 装了 Temurin 21、没设环境变量、PATH 上是 Java 8：1.20.5 只认扫盘那个。
+    let candidates = [
+        runtime("java", 8, JavaOrigin::Path),
+        runtime(
+            "C:/Program Files/Java/jdk-21/bin/java.exe",
+            21,
+            JavaOrigin::System,
+        ),
+    ];
+    let picked = pick(&candidates, &at_least(21)).expect("应有候选");
+    assert_eq!(picked.origin, JavaOrigin::System);
+}
+
+#[test]
+fn dedupe_collapses_one_install_found_twice() {
+    // `JAVA_HOME` 指向 Program Files 里的 JDK → 同一个 java 不应列两次。
+    // 第二条的「另一种写法」随平台给：Windows 上大小写和分隔符都可能不一致（NTFS 不区分
+    // 大小写），POSIX 上大小写是有效区别，只能靠分隔符拼出同一路径的第二种写法。
+    let duplicate = if cfg!(windows) {
+        "c:/program files/java/jdk-21/bin/java.exe"
+    } else {
+        "C:\\Program Files\\Java\\jdk-21/bin/java.exe"
+    };
+    let candidates = discover::dedupe(vec![
+        runtime(
+            "C:/Program Files/Java/jdk-21/bin/java.exe",
+            21,
+            JavaOrigin::JavaHome,
+        ),
+        runtime(duplicate, 21, JavaOrigin::System),
+    ]);
+    assert_eq!(candidates.len(), 1);
+    assert_eq!(candidates[0].origin, JavaOrigin::JavaHome);
+}
+
+#[test]
+fn registry_absence_is_tolerated() {
+    // 非 Windows 必然为空；Windows 上没装老 Oracle JDK 也是空。
+    let homes = discover::registry_homes();
+    for home in &homes {
+        assert!(
+            home.is_absolute(),
+            "注册表里的 JavaHome 应是绝对路径：{}",
+            home.display()
+        );
+    }
+}
diff --git a/crates/core/tests/game/java_install.rs b/crates/core/tests/game/java_install.rs
new file mode 100644
index 0000000..5d69239
--- /dev/null
+++ b/crates/core/tests/game/java_install.rs
@@ -0,0 +1,291 @@
+//! `core::game::java` 的安装侧集成测试：归档解压（幂等 / 顶层剥离 / 越界拒绝）、
+//! 托管目录命名、下载请求装配、平台归档形态。
+//!
+//! 镜像选源见 `java_mirrors.rs`，MC↔Java 映射见 `java_mapping.rs`。
+
+use std::fs::File;
+use std::io::Write;
+use std::path::{Path, PathBuf};
+
+use flate2::write::GzEncoder;
+use flate2::Compression;
+use unlucky_core::download::ResourceKind;
+use unlucky_core::game::java::{
+    self, extract, install, probe, AdoptiumTarget, JdkArchive, JdkRelease,
+};
+
+/// 64 位十六进制（解压戳记只当字符串比对，不校验内容）。
+const SHA_A: &str = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+/// 另一个「新版本」的摘要。
+const SHA_B: &str = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";
+
+fn temp_dir(tag: &str) -> PathBuf {
+    use std::sync::atomic::{AtomicU64, Ordering};
+    static COUNTER: AtomicU64 = AtomicU64::new(0);
+    let nanos = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map_or(0, |elapsed| elapsed.as_nanos());
+    let seq = COUNTER.fetch_add(1, Ordering::Relaxed);
+    let dir = std::env::temp_dir().join(format!(
+        "ull-java-{tag}-{}-{nanos}-{seq}",
+        std::process::id()
+    ));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).expect("建临时目录");
+    dir
+}
+/// 造一个 Temurin 形状的 zip（顶层 `jdk-21.0.13+9/`）。
+fn write_zip(path: &Path, entries: &[(&str, &[u8])]) {
+    let file = File::create(path).expect("建 zip");
+    let mut writer = zip::ZipWriter::new(file);
+    let options =
+        zip::write::SimpleFileOptions::default().compression_method(zip::CompressionMethod::Stored);
+    for (name, body) in entries {
+        writer.start_file(*name, options).expect("写 zip 条目");
+        writer.write_all(body).expect("写 zip 内容");
+    }
+    writer.finish().expect("收尾 zip");
+}
+
+/// 造一个 Temurin 形状的 tar.gz。
+fn write_tar_gz(path: &Path, entries: &[(&str, &[u8])]) {
+    let file = File::create(path).expect("建 tar.gz");
+    let encoder = GzEncoder::new(file, Compression::fast());
+    let mut builder = tar::Builder::new(encoder);
+    for (name, body) in entries {
+        let mut header = tar::Header::new_gnu();
+        header.set_size(body.len() as u64);
+        header.set_mode(0o755);
+        header.set_entry_type(tar::EntryType::Regular);
+        builder
+            .append_data(&mut header, name, *body)
+            .expect("写 tar 条目");
+    }
+    let encoder = builder.into_inner().expect("收尾 tar");
+    encoder.finish().expect("收尾 gzip");
+}
+
+fn java_bin(root: &Path) -> PathBuf {
+    root.join("bin").join(java::java_binary_name())
+}
+
+#[test]
+fn zip_archive_loses_the_temurin_top_level_directory() {
+    let dir = temp_dir("zip");
+    let archive = dir.join("jdk.zip");
+    let top = "jdk-21.0.13+9";
+    write_zip(
+        &archive,
+        &[
+            (
+                &format!("{top}/bin/{}", java::java_binary_name()),
+                b"#!/bin/true\n",
+            ),
+            (&format!("{top}/release"), b"JAVA_VERSION=\"21.0.13\"\n"),
+        ],
+    );
+    let dest = dir.join("jdk-21-temurin");
+    let report = extract::extract_archive(&archive, SHA_A, 21, &dest).expect("解压应成功");
+
+    assert!(!report.skipped);
+    assert_eq!(report.files, 2);
+    assert!(java_bin(&dest).is_file(), "bin/java 应在顶层");
+    assert!(!dest.join(top).exists(), "顶层目录必须被剥掉");
+    let stamp = extract::read_stamp(&dest).expect("应写戳记");
+    assert_eq!(stamp.major, 21);
+    assert_eq!(stamp.sha256, SHA_A);
+    assert_eq!(stamp.files, 2);
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn second_extract_with_same_sha_touches_nothing() {
+    let dir = temp_dir("idem");
+    let archive = dir.join("jdk.zip");
+    write_zip(
+        &archive,
+        &[(
+            &format!("jdk-21.0.13+9/bin/{}", java::java_binary_name()),
+            b"bin\n",
+        )],
+    );
+    let dest = dir.join("jdk-21-temurin");
+    extract::extract_archive(&archive, SHA_A, 21, &dest).expect("首解");
+
+    // 用户手工动过的痕迹：幂等命中时不能被抹掉。
+    let marker = dest.join("安装后手工放的.txt");
+    std::fs::write(&marker, b"keep").expect("写标记");
+
+    let again = extract::extract_archive(&archive, SHA_A, 21, &dest).expect("重解");
+    assert!(again.skipped, "同一 sha256 应整体跳过");
+    assert_eq!(again.files, 0);
+    assert!(marker.is_file(), "幂等命中时不应重写目录");
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn new_sha_replaces_the_managed_directory() {
+    let dir = temp_dir("upgrade");
+    let archive = dir.join("jdk.zip");
+    write_zip(
+        &archive,
+        &[(
+            &format!("jdk-21.0.13+9/bin/{}", java::java_binary_name()),
+            b"v1\n",
+        )],
+    );
+    let dest = dir.join("jdk-21-temurin");
+    extract::extract_archive(&archive, SHA_A, 21, &dest).expect("首解");
+    let marker = dest.join("旧版残留");
+    std::fs::write(&marker, b"old").expect("写标记");
+
+    let report = extract::extract_archive(&archive, SHA_B, 21, &dest).expect("新摘要重解");
+    assert!(!report.skipped);
+    assert!(!marker.exists(), "官方发新版后旧目录应被替换");
+    assert_eq!(
+        extract::read_stamp(&dest).map(|stamp| stamp.sha256),
+        Some(SHA_B.to_string())
+    );
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn tar_gz_archive_is_supported_for_linux_and_mac() {
+    let dir = temp_dir("targz");
+    let archive = dir.join("OpenJDK21U-jdk_x64_linux_hotspot_21.0.13_9.tar.gz");
+    let top = "jdk-21.0.13+9";
+    write_tar_gz(
+        &archive,
+        &[
+            (&format!("{top}/bin/{}", java::java_binary_name()), b"bin\n"),
+            (&format!("{top}/lib/modules"), b"modules\n"),
+        ],
+    );
+    let dest = dir.join("jdk-21-temurin");
+    let report = extract::extract_archive(&archive, SHA_A, 21, &dest).expect("解压 tar.gz");
+    assert_eq!(report.files, 2);
+    assert!(dest.join("bin").join(java::java_binary_name()).is_file());
+    assert!(dest.join("lib").join("modules").is_file());
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn archive_without_a_single_top_directory_is_promoted_as_is() {
+    // 有的魔改发行版直接把 bin/ 放在根上：不能硬剥一层。
+    let dir = temp_dir("flat");
+    let archive = dir.join("flat.zip");
+    write_zip(
+        &archive,
+        &[
+            (
+                &format!("bin/{}", java::java_binary_name()),
+                b"bin\n".as_slice(),
+            ),
+            ("release", b"x\n".as_slice()),
+        ],
+    );
+    let dest = dir.join("jdk-17-temurin");
+    extract::extract_archive(&archive, SHA_A, 17, &dest).expect("解压");
+    assert!(dest.join("bin").join(java::java_binary_name()).is_file());
+    assert!(dest.join("release").is_file());
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn foreign_directory_is_never_clobbered() {
+    let dir = temp_dir("foreign");
+    let archive = dir.join("jdk.zip");
+    write_zip(
+        &archive,
+        &[(
+            &format!("jdk-21.0.13+9/bin/{}", java::java_binary_name()),
+            b"bin\n",
+        )],
+    );
+    let dest = dir.join("jdk-21-temurin");
+    std::fs::create_dir_all(&dest).expect("建目标目录");
+    std::fs::write(dest.join("用户的文件.txt"), b"mine").expect("写用户文件");
+
+    let error = extract::extract_archive(&archive, SHA_A, 21, &dest).expect_err("应拒绝覆盖");
+    assert_eq!(error.kind(), java::JavaErrorKind::Io);
+    assert!(dest.join("用户的文件.txt").is_file(), "用户文件必须还在");
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn zip_slip_entries_do_not_escape_the_target_directory() {
+    let dir = temp_dir("slip");
+    let archive = dir.join("evil.zip");
+    write_zip(
+        &archive,
+        &[
+            (
+                &format!("jdk-21.0.13+9/bin/{}", java::java_binary_name()),
+                b"bin\n",
+            ),
+            ("../../escaped.txt", b"nope"),
+        ],
+    );
+    let dest = dir.join("jdk-21-temurin");
+    let report = extract::extract_archive(&archive, SHA_A, 21, &dest).expect("越界条目只跳过");
+    assert_eq!(report.files, 1, "越界条目不应被写盘");
+    assert!(!dir.join("escaped.txt").exists());
+    assert!(!dir.parent().unwrap_or(&dir).join("escaped.txt").exists());
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn managed_layout_names_carry_major_and_vendor() {
+    let root = Path::new("/tmp/java-managed");
+    let dest = install::managed_root_dir(root, 21, java::JDK_VENDOR);
+    assert_eq!(dest, root.join("jdk-21-temurin"));
+    assert_eq!(
+        probe::parse_managed_dir("jdk-21-temurin"),
+        Some((21, "temurin"))
+    );
+    assert_eq!(probe::managed_dir_name(8, "temurin"), "jdk-8-temurin");
+}
+
+#[test]
+fn archive_request_carries_sha256_and_the_java_runtime_kind() {
+    let release = JdkRelease {
+        vendor: java::JdkVendor::Temurin,
+        major: 21,
+        version: "21.0.13+9".to_string(),
+        semver: Some("21.0.13+9.0.LTS".to_string()),
+        release_name: "jdk-21.0.13+9".to_string(),
+        archive: JdkArchive {
+            name: "OpenJDK21U-jdk_x64_windows_hotspot_21.0.13_9.zip".to_string(),
+            url: "https://github.com/adoptium/temurin21-binaries/releases/download/x.zip"
+                .to_string(),
+            sha256: SHA_A.to_string(),
+            size: 1024,
+        },
+    };
+    let dest = Path::new("/tmp/x.zip");
+    let request = install::archive_request(&release, dest.to_path_buf());
+    assert_eq!(request.kind, ResourceKind::JavaRuntime);
+    assert_eq!(request.expected_size, Some(1024));
+    assert_eq!(
+        request
+            .integrity
+            .as_ref()
+            .map(|integrity| integrity.hex.as_str()),
+        Some(SHA_A)
+    );
+    assert!(request.validate().is_ok());
+    assert_eq!(
+        install::archive_path(Path::new("/tmp/java-managed"), &release),
+        Path::new("/tmp/java-managed/.cache/OpenJDK21U-jdk_x64_windows_hotspot_21.0.13_9.zip")
+    );
+}
+
+#[test]
+fn host_target_picks_the_platform_archive_shape() {
+    let target = AdoptiumTarget::host().expect("宿主应受支持");
+    assert_eq!(target.is_zip(), cfg!(windows));
+    assert_eq!(
+        target.archive_ext(),
+        if cfg!(windows) { "zip" } else { "tar.gz" }
+    );
+}
diff --git a/crates/core/tests/game/java_location.rs b/crates/core/tests/game/java_location.rs
new file mode 100644
index 0000000..55eaef3
--- /dev/null
+++ b/crates/core/tests/game/java_location.rs
@@ -0,0 +1,136 @@
+//! `core::game::java::location`：落点三模式（Portable / Standard / Custom）+ 孤儿目录清理。
+//!
+//! 三模式的口径来自 D23/D6：Portable 保持 v1 布局、Standard 走 OS 标准目录的
+//! `<发行方>/<版本>` 分层、Custom 由 `java.installRoot` 覆盖；清理只碰我们自己的形状。
+
+use std::path::PathBuf;
+
+use unlucky_core::game::java::location::{
+    cleanup_orphans, sanitize_version, standard_java_root, JavaInstallRoot, LocationMode,
+};
+use unlucky_core::game::java::JdkVendor;
+use unlucky_core::platform::layout::LauncherLayout;
+use unlucky_core::platform::paths::{MapEnv, Platform};
+
+fn temp_dir(tag: &str) -> PathBuf {
+    use std::sync::atomic::{AtomicU64, Ordering};
+    static COUNTER: AtomicU64 = AtomicU64::new(0);
+    let nanos = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map_or(0, |elapsed| elapsed.as_nanos());
+    let seq = COUNTER.fetch_add(1, Ordering::Relaxed);
+    let dir = std::env::temp_dir().join(format!(
+        "ull-java-loc-{tag}-{}-{nanos}-{seq}",
+        std::process::id()
+    ));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).expect("建临时目录");
+    dir
+}
+
+#[test]
+fn standard_root_follows_each_platform_convention() {
+    let env = MapEnv::new()
+        .with("APPDATA", "C:/Users/u/AppData/Roaming")
+        .with("HOME", "/home/u")
+        .with("USERPROFILE", "C:/Users/u");
+    // 期望值一律用 `join` 拼（Windows 上的分隔符与 `Path` 比较细节交给标准库）。
+    let unix_home = PathBuf::from("/home/u");
+    assert_eq!(
+        standard_java_root(Platform::Windows, &env),
+        Some(PathBuf::from("C:/Users/u/AppData/Roaming").join("Java")),
+        "Windows 用户原话：%APPDATA%\\Java"
+    );
+    assert_eq!(
+        standard_java_root(Platform::MacOs, &env),
+        Some(unix_home.join("Library/Application Support").join("Java"))
+    );
+    assert_eq!(
+        standard_java_root(Platform::Linux, &env),
+        Some(unix_home.join(".local/share").join("java")),
+        "Linux 走 XDG 约定（无 XDG_DATA_HOME 时回落 ~/.local/share）"
+    );
+    // `Path::is_absolute()` 的口径是编译目标决定的：Windows 上 `C:/data/u` 才是绝对路径，
+    // 而 `/data/u` 只是「rooted」。夹具按目标平台给，才能同时验到「绝对 → 采用」。
+    let xdg_root = if cfg!(windows) {
+        "C:/data/u"
+    } else {
+        "/data/u"
+    };
+    let xdg = MapEnv::new()
+        .with("HOME", "/home/u")
+        .with("XDG_DATA_HOME", xdg_root);
+    assert_eq!(
+        standard_java_root(Platform::Linux, &xdg),
+        Some(PathBuf::from(xdg_root).join("java"))
+    );
+    // 相对路径的 XDG_DATA_HOME 按规范忽略 → 回落 HOME。
+    let relative = MapEnv::new()
+        .with("HOME", "/home/u")
+        .with("XDG_DATA_HOME", "data/u");
+    assert_eq!(
+        standard_java_root(Platform::Linux, &relative),
+        Some(unix_home.join(".local/share").join("java"))
+    );
+    assert_eq!(standard_java_root(Platform::Linux, &MapEnv::new()), None);
+}
+
+#[test]
+fn portable_and_custom_modes_derive_the_documented_directories() {
+    let launcher = LauncherLayout::new("/data/.ULL");
+    let portable = JavaInstallRoot::portable(&launcher);
+    assert_eq!(portable.mode, LocationMode::Portable);
+    assert_eq!(
+        portable.jdk_dir(21, JdkVendor::Temurin, "21.0.13+9"),
+        PathBuf::from("/data/.ULL/data/java-managed/jdk-21-temurin"),
+        "便携模式必须保持 v1 布局（M33/M35 兼容）"
+    );
+    let custom = JavaInstallRoot::custom("/opt/java");
+    assert_eq!(custom.mode, LocationMode::Custom);
+    assert_eq!(
+        custom.jdk_dir(21, JdkVendor::Oracle, "21.0.2"),
+        PathBuf::from("/opt/java/oracle/21.0.2"),
+        "Custom 用 <vendor>/<version>（D23）"
+    );
+    assert_eq!(custom.cache_dir(), PathBuf::from("/opt/java/.cache"));
+    assert!(custom.describe().contains("custom"));
+}
+
+#[test]
+fn version_strings_are_sanitized_for_directory_names() {
+    assert_eq!(sanitize_version("21.0.13+9"), "21.0.13+9");
+    assert_eq!(sanitize_version("21.0.13.0.2"), "21.0.13.0.2");
+    assert_eq!(sanitize_version("21.0.13+3"), "21.0.13+3");
+    assert_eq!(sanitize_version(" 21.0.2 "), "21.0.2");
+    assert_eq!(sanitize_version("../evil"), ".._evil");
+    assert_eq!(sanitize_version(""), "unknown");
+}
+
+#[test]
+fn cleanup_removes_staging_and_empty_shells_but_never_foreign_dirs() {
+    let root = temp_dir("cleanup");
+    // 半成品：解压中断的暂存目录。
+    std::fs::create_dir_all(root.join(".staging-jdk-21-temurin")).expect("建暂存");
+    std::fs::write(root.join(".staging-jdk-21-temurin/bin"), b"x").expect("写暂存文件");
+    // 空壳 vendor 目录（Standard 布局的残留）。
+    std::fs::create_dir_all(root.join("oracle")).expect("建 vendor");
+    // 用户自己的目录（非空、无戳记）：绝不能删。
+    std::fs::create_dir_all(root.join("my-own-jdk")).expect("建用户目录");
+    std::fs::write(root.join("my-own-jdk/notes.txt"), b"mine").expect("写用户文件");
+    // 归档缓存目录：保留。
+    std::fs::create_dir_all(root.join(".cache")).expect("建缓存");
+
+    let report = cleanup_orphans(&root);
+    assert!(
+        !root.join(".staging-jdk-21-temurin").exists(),
+        "暂存目录应删"
+    );
+    assert!(!root.join("oracle").exists(), "空 vendor 目录应删");
+    assert!(
+        root.join("my-own-jdk/notes.txt").is_file(),
+        "用户目录必须还在"
+    );
+    assert!(root.join(".cache").is_dir(), "缓存目录不能删");
+    assert_eq!(report.removed.len(), 2, "{:?}", report.removed);
+    let _ = std::fs::remove_dir_all(&root);
+}
diff --git a/crates/core/tests/game/java_mapping.rs b/crates/core/tests/game/java_mapping.rs
new file mode 100644
index 0000000..8b98e66
--- /dev/null
+++ b/crates/core/tests/game/java_mapping.rs
@@ -0,0 +1,106 @@
+//! MC↔Java 映射：版本 JSON 的 `javaVersion` 优先（含继承链），上限取自静态表。
+
+use std::path::PathBuf;
+
+use unlucky_core::game::java::mapping;
+
+fn temp_dir(tag: &str) -> PathBuf {
+    use std::sync::atomic::{AtomicU64, Ordering};
+    static COUNTER: AtomicU64 = AtomicU64::new(0);
+    let nanos = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map_or(0, |elapsed| elapsed.as_nanos());
+    let seq = COUNTER.fetch_add(1, Ordering::Relaxed);
+    let dir = std::env::temp_dir().join(format!(
+        "ull-java-{tag}-{}-{nanos}-{seq}",
+        std::process::id()
+    ));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).expect("建临时目录");
+    dir
+}
+
+#[test]
+fn version_json_java_version_beats_the_static_table() {
+    let root = temp_dir("mapping");
+    let layout = unlucky_core::game::GameLayout::new(&root);
+    let write = |id: &str, json: serde_json::Value| {
+        let dir = root.join("versions").join(id);
+        std::fs::create_dir_all(&dir).expect("建版本目录");
+        std::fs::write(
+            dir.join(format!("{id}.json")),
+            serde_json::to_vec(&json).expect("序列化"),
+        )
+        .expect("写版本 JSON");
+    };
+
+    // 1.17 的清单自己说是 16（静态表也是 16，但来源必须标 manifest）。
+    write(
+        "1.17.1",
+        serde_json::json!({"id": "1.17.1", "javaVersion": {"component": "java-runtime-alpha", "majorVersion": 16}}),
+    );
+    let manifest = mapping::requirement_for_version(&layout, "1.17.1");
+    assert_eq!(manifest.minimum, 16);
+    assert_eq!(manifest.source.as_str(), "manifest");
+
+    // 魔改实例覆盖父版本：21 应当生效。
+    write("1.20.1", serde_json::json!({"id": "1.20.1"}));
+    write(
+        "1.20.1-forge",
+        serde_json::json!({"id": "1.20.1-forge", "inheritsFrom": "1.20.1", "javaVersion": {"majorVersion": 21}}),
+    );
+    assert_eq!(
+        mapping::requirement_for_version(&layout, "1.20.1-forge").minimum,
+        21
+    );
+
+    // 清单没写 javaVersion：父版本也没有 → 静态表兜底。
+    let table = mapping::requirement_for_version(&layout, "1.20.1");
+    assert_eq!(table.minimum, 17);
+    assert_eq!(table.source.as_str(), "table");
+
+    // 1.12.2：清单只说「最低 8」，但上限（LaunchWrapper 只能 Java 8）由静态表补上。
+    write(
+        "1.12.2",
+        serde_json::json!({"id": "1.12.2", "javaVersion": {"component": "jre-legacy", "majorVersion": 8}}),
+    );
+    let legacy = mapping::requirement_for_version(&layout, "1.12.2");
+    assert_eq!((legacy.minimum, legacy.maximum), (8, Some(8)));
+    assert_eq!(legacy.source.as_str(), "manifest");
+    assert!(
+        mapping::check(21, &legacy).is_some(),
+        "1.12.2 + Java 21 必须报不符"
+    );
+
+    // 版本根本没装：按 id 走静态表，不报错。
+    let missing = mapping::requirement_for_version(&layout, "26.3");
+    assert_eq!(missing.minimum, 25);
+    let _ = std::fs::remove_dir_all(&root);
+}
+
+#[test]
+fn parent_java_version_is_inherited() {
+    let root = temp_dir("inherit");
+    let layout = unlucky_core::game::GameLayout::new(&root);
+    let write = |id: &str, json: serde_json::Value| {
+        let dir = root.join("versions").join(id);
+        std::fs::create_dir_all(&dir).expect("建版本目录");
+        std::fs::write(
+            dir.join(format!("{id}.json")),
+            serde_json::to_vec(&json).expect("序列化"),
+        )
+        .expect("写版本 JSON");
+    };
+    write(
+        "1.20.5",
+        serde_json::json!({"id": "1.20.5", "javaVersion": {"component": "java-runtime-delta", "majorVersion": 21}}),
+    );
+    write(
+        "1.20.5-fabric",
+        serde_json::json!({"id": "1.20.5-fabric", "inheritsFrom": "1.20.5"}),
+    );
+    let requirement = mapping::requirement_for_version(&layout, "1.20.5-fabric");
+    assert_eq!(requirement.minimum, 21);
+    assert_eq!(requirement.source.as_str(), "manifest");
+    let _ = std::fs::remove_dir_all(&root);
+}
diff --git a/crates/core/tests/game/java_mirrors.rs b/crates/core/tests/game/java_mirrors.rs
new file mode 100644
index 0000000..0fbc484
--- /dev/null
+++ b/crates/core/tests/game/java_mirrors.rs
@@ -0,0 +1,96 @@
+//! 镜像选源（D7 地区策略注入样本）：国内镜像优先 / 国外官方优先，候选里都留兜底。
+
+use unlucky_core::download::mirrors::MirrorTable;
+use unlucky_core::download::region::RegionProfile;
+use unlucky_core::download::ResourceKind;
+
+#[test]
+fn domestic_region_puts_college_mirrors_first() {
+    let table = MirrorTable::builtin();
+    let url = "https://github.com/adoptium/temurin21-binaries/releases/download/jdk-21.0.13%2B9/OpenJDK21U-jdk_x64_windows_hotspot_21.0.13_9.zip";
+    let domestic = table.expand(
+        url,
+        ResourceKind::JavaRuntime,
+        &RegionProfile::mirror_first(0),
+    );
+    assert_eq!(
+        domestic.first().map(|candidate| candidate.source.as_str()),
+        Some("tuna")
+    );
+    assert_eq!(
+        domestic.first().map(|candidate| candidate.url.as_str()),
+        Some("https://mirrors.tuna.tsinghua.edu.cn/Adoptium/21/jdk/x64/windows/OpenJDK21U-jdk_x64_windows_hotspot_21.0.13_9.zip")
+    );
+    let sources: Vec<&str> = domestic
+        .iter()
+        .map(|candidate| candidate.source.as_str())
+        .collect();
+    // USTC/SJTU/BFSU 没有这套目录树（实测 404）、华为云是门户假阳性（M34 实测）
+    // → 清单里全停用，不该出现在候选里。
+    for dead in ["ustc", "sjtu", "bfsu", "huaweicloud"] {
+        assert!(!sources.contains(&dead), "{dead} 应已停用：{sources:?}");
+    }
+    assert_eq!(sources.last().copied(), Some("official"), "官方兜底在最后");
+}
+
+#[test]
+fn foreign_region_keeps_official_first_but_still_has_mirrors() {
+    let table = MirrorTable::builtin();
+    let url = "https://github.com/adoptium/temurin17-binaries/releases/download/jdk-17.0.13%2B11/OpenJDK17U-jdk_aarch64_linux_hotspot_17.0.13_11.tar.gz";
+    let abroad = table.expand(url, ResourceKind::JavaRuntime, &RegionProfile::direct(0));
+    assert_eq!(
+        abroad.first().map(|candidate| candidate.source.as_str()),
+        Some("official")
+    );
+    assert_eq!(
+        abroad.first().map(|candidate| candidate.url.as_str()),
+        Some(url)
+    );
+    // 镜像仍然排在后面（国外也可能是镜像更快；健康度会让它上位）。
+    assert!(abroad.len() > 1);
+    assert!(abroad
+        .iter()
+        .any(|candidate| candidate.url.contains("/Adoptium/17/jdk/aarch64/linux/")));
+}
+
+#[test]
+fn vendor_cdn_and_mirror_urls_are_labelled_by_their_real_host() {
+    let table = MirrorTable::builtin();
+    let direct = RegionProfile::direct(0);
+    // Oracle 走国内镜像时，直连 URL 就是华为云——不能标成 official（否则用户以为在啃官方 5.3KB/s）。
+    let oracle =
+        "https://mirrors.huaweicloud.com/openjdk/21.0.2/openjdk-21.0.2_windows-x64_bin.zip";
+    assert_eq!(
+        table
+            .expand(oracle, ResourceKind::JavaRuntime, &direct)
+            .first()
+            .map(|candidate| candidate.source.as_str()),
+        Some("huawei")
+    );
+    // MS 的 aka.ms 与 Zulu 的 CDN 同理。
+    let microsoft = "https://aka.ms/download-jdk/microsoft-jdk-21.0.13.0.2-windows-x64.zip";
+    assert_eq!(
+        table
+            .expand(microsoft, ResourceKind::JavaRuntime, &direct)
+            .first()
+            .map(|candidate| candidate.source.as_str()),
+        Some("microsoft")
+    );
+    let zulu = "https://cdn.azul.com/zulu/bin/zulu21.54.109-ca-jdk21.0.13.0.3-win_x64.zip";
+    assert_eq!(
+        table
+            .expand(zulu, ResourceKind::JavaRuntime, &direct)
+            .first()
+            .map(|candidate| candidate.source.as_str()),
+        Some("azul")
+    );
+    // Mojang 系资源仍是 official（别把官方源误标成厂商）。
+    let mojang = "https://piston-data.mojang.com/v1/objects/abc/client.jar";
+    assert_eq!(
+        table
+            .expand(mojang, ResourceKind::ClientJar, &direct)
+            .first()
+            .map(|candidate| candidate.source.as_str()),
+        Some("official")
+    );
+}
diff --git a/crates/core/tests/game/java_vendor_chain.rs b/crates/core/tests/game/java_vendor_chain.rs
new file mode 100644
index 0000000..0647e22
--- /dev/null
+++ b/crates/core/tests/game/java_vendor_chain.rs
@@ -0,0 +1,183 @@
+//! D23 发行版回退链：地区默认序、用户优先级覆盖、能力过滤、mirrors v3 三张新表。
+//!
+//! 全部离线：只跑纯函数与清单解析，不发一个请求。
+//! 真机验收（TUNA 装 17 / 华为云装 Oracle 21 / `%APPDATA%` 落点）见 mission 报告。
+
+use unlucky_core::download::MirrorTable;
+use unlucky_core::game::java::install::chain_order;
+use unlucky_core::game::java::release::{parse_sha256_text, JdkArchive, JdkRelease};
+use unlucky_core::game::java::vendor::{ids, order, parse_priority, JdkVendor, VENDOR_IDS};
+use unlucky_core::game::java::InstallRequest;
+
+fn vendors(items: &[&str]) -> Vec<JdkVendor> {
+    parse_priority(
+        &items
+            .iter()
+            .map(|item| (*item).to_string())
+            .collect::<Vec<_>>(),
+    )
+}
+
+#[test]
+fn domestic_default_is_temurin_oracle_microsoft_zulu() {
+    assert_eq!(
+        ids(&order(&[], true)),
+        vec!["temurin", "oracle", "microsoft", "zulu"],
+        "国内：Oracle 国内镜像 11.5MB/s vs MS 410KB/s（D23 实测修正）"
+    );
+    assert_eq!(
+        ids(&order(&[], false)),
+        vec!["temurin", "microsoft", "oracle", "zulu"],
+        "国外：维持用户原话 Temurin→MS→Oracle"
+    );
+}
+
+#[test]
+fn setting_priority_overrides_the_region_default_but_never_drops_a_vendor() {
+    let priority = vendors(&["microsoft"]);
+    assert_eq!(
+        ids(&order(&priority, true)),
+        vec!["microsoft", "temurin", "oracle", "zulu"]
+    );
+    // 写全四家也等于顺序覆盖。
+    let full = vendors(&["zulu", "microsoft", "oracle", "temurin"]);
+    assert_eq!(
+        ids(&order(&full, false)),
+        vec!["zulu", "microsoft", "oracle", "temurin"]
+    );
+    // 未知值被忽略（老配置里可能残留 graalvm 之类）。
+    let messy = vendors(&["graalvm", "oracle"]);
+    assert_eq!(
+        ids(&order(&messy, true)),
+        vec!["oracle", "temurin", "microsoft", "zulu"]
+    );
+}
+
+#[test]
+fn capability_filter_drops_microsoft_and_oracle_for_java_8() {
+    // Java 8：MS 已停发、Oracle archive 从 9 起 → 链里只剩 Temurin 与 Zulu。
+    assert_eq!(
+        ids(&chain_order(&InstallRequest::new(8), true)),
+        vec!["temurin", "zulu"]
+    );
+    // Java 21：四家都发，顺序完整。
+    assert_eq!(
+        ids(&chain_order(&InstallRequest::new(21), true)),
+        vec!["temurin", "oracle", "microsoft", "zulu"]
+    );
+    // 钉死一家：链里只放它，即使它不支持这个大版本（由 install 报明确原因，不偷偷换家）。
+    let pinned = InstallRequest::with_vendor(8, JdkVendor::Microsoft);
+    assert_eq!(
+        ids(&chain_order(&pinned, true)),
+        vec!["microsoft"],
+        "--vendor 不做能力过滤：用户点名的那家要显式失败"
+    );
+}
+
+#[test]
+fn pinned_vendor_wins_over_the_user_priority() {
+    let request =
+        InstallRequest::with_vendor(17, JdkVendor::Oracle).with_priority(vendors(&["zulu"]));
+    assert_eq!(ids(&request.order(true)), vec!["oracle"]);
+    let chained = InstallRequest::new(17).with_priority(vendors(&["zulu"]));
+    assert_eq!(
+        ids(&chained.order(true)),
+        vec!["zulu", "temurin", "oracle", "microsoft"]
+    );
+}
+
+#[test]
+fn mirror_table_v3_registers_all_four_source_families() {
+    let table = MirrorTable::builtin();
+    assert_eq!(table.version, 3);
+    // adoptium 收敛：只有 TUNA 启用，其余六家登记为 disabled。
+    assert_eq!(
+        table
+            .adoptium
+            .iter()
+            .filter(|mirror| mirror.enabled)
+            .map(|mirror| mirror.id.as_str())
+            .collect::<Vec<_>>(),
+        vec!["tuna"]
+    );
+    assert_eq!(table.adoptium.len(), 7, "TUNA + USTC/SJTU/BFSU/NJU/ZJU/163");
+    // 华为云的假阳性不再登记成 adoptium 源（它没有 Adoptium 镜像）。
+    assert!(table
+        .adoptium
+        .iter()
+        .all(|mirror| mirror.id != "huaweicloud"));
+    // Oracle：华为云在前、南大在后（顺序即默认尝试顺序）。
+    assert_eq!(
+        table
+            .oracle_mirrors()
+            .map(|mirror| mirror.id.as_str())
+            .collect::<Vec<_>>(),
+        vec!["huawei", "nju"]
+    );
+    // MS：模板 + 无国内镜像 + 四个大版本。
+    let microsoft = table.microsoft_openjdk().expect("MS 表");
+    assert!(microsoft.domestic_mirrors.is_empty());
+    assert_eq!(microsoft.majors, vec![25, 21, 17, 11]);
+    // Zulu：size 不可信，只信 sha256。
+    assert!(!table.zulu().expect("Zulu 表").size_field_reliable);
+}
+
+#[test]
+fn every_vendor_release_shape_carries_its_own_version_semantics() {
+    // 四家的版本串并列：目录名、戳记、--json 都直接用 vendor 原生串。
+    let samples = [
+        (JdkVendor::Temurin, "21.0.13+9"),
+        (JdkVendor::Oracle, "21.0.2"),
+        (JdkVendor::Microsoft, "21.0.13.0.2"),
+        (JdkVendor::Zulu, "21.0.13+3"),
+    ];
+    for (vendor, version) in samples {
+        let release = JdkRelease {
+            vendor,
+            major: 21,
+            version: version.to_string(),
+            semver: None,
+            release_name: version.to_string(),
+            archive: JdkArchive {
+                name: format!("{}-{version}.zip", vendor.id()),
+                url: format!("https://example.invalid/{}-{version}.zip", vendor.id()),
+                sha256: "a".repeat(64),
+                size: 0,
+            },
+        };
+        assert!(release.matches(vendor, 21));
+        assert!(release.summary().contains(version), "{}", release.summary());
+        assert_eq!(release.archive_json()["vendor"], vendor.id());
+        assert_eq!(
+            unlucky_core::game::java::sanitize_version(&release.version),
+            version,
+            "版本串要能直接当目录名"
+        );
+    }
+}
+
+#[test]
+fn sha256_texts_are_parsed_the_same_way_for_every_upstream() {
+    let hash = "b6c17e747ae78cdd6de4d7532b3164b277daee97c007d3eaa2b39cca99882664";
+    // 华为云 .sha256：纯哈希。
+    assert_eq!(parse_sha256_text(hash).as_deref(), Some(hash));
+    // MS .sha256sum.txt：`<hash>  <filename>`（大写 + CRLF）。
+    assert_eq!(
+        parse_sha256_text(&format!(
+            "{}  microsoft-jdk-21.0.13-windows-x64.zip\r\n",
+            hash.to_uppercase()
+        ))
+        .as_deref(),
+        Some(hash)
+    );
+    assert_eq!(parse_sha256_text("404 not found"), None);
+}
+
+#[test]
+fn vendor_ids_are_the_setting_whitelist() {
+    assert_eq!(VENDOR_IDS, &["temurin", "oracle", "microsoft", "zulu"]);
+    for id in VENDOR_IDS {
+        assert_eq!(JdkVendor::parse(id).map(|vendor| vendor.id()), Some(*id));
+    }
+    assert!(JdkVendor::parse("graalvm").is_none());
+}
diff --git a/crates/core/tests/game/layout.rs b/crates/core/tests/game/layout.rs
new file mode 100644
index 0000000..bd034ab
--- /dev/null
+++ b/crates/core/tests/game/layout.rs
@@ -0,0 +1,143 @@
+//! `.minecraft` 目录布局：路径规则、Maven 坐标、已安装版本枚举。
+
+use std::path::PathBuf;
+
+use unlucky_core::game::error::GameError;
+use unlucky_core::game::layout::GameLayout;
+use unlucky_core::game::library::MavenCoordinate;
+
+use crate::helpers::TempDir;
+
+fn layout() -> (TempDir, GameLayout) {
+    let temp = TempDir::new("layout");
+    let layout = GameLayout::new(temp.path().to_path_buf());
+    (temp, layout)
+}
+
+#[test]
+fn version_paths_follow_mojang_layout() {
+    let (_temp, layout) = layout();
+    let root = layout.root();
+
+    assert_eq!(layout.versions_dir(), root.join("versions"));
+    assert_eq!(layout.version_dir("1.20.1"), root.join("versions/1.20.1"));
+    assert_eq!(
+        layout.version_json("1.20.1"),
+        root.join("versions/1.20.1/1.20.1.json")
+    );
+    assert_eq!(
+        layout.version_jar("1.20.1"),
+        root.join("versions/1.20.1/1.20.1.jar")
+    );
+    // ULL 扩展：实例私有状态与 natives 解压目录。
+    assert_eq!(
+        layout.version_state_dir("1.20.1"),
+        root.join("versions/1.20.1/.ull")
+    );
+    assert_eq!(
+        layout.natives_dir("1.20.1"),
+        root.join("versions/1.20.1/natives")
+    );
+    assert_eq!(
+        layout.version_libraries_dir("1.20.1"),
+        root.join("versions/1.20.1/libraries")
+    );
+    assert_eq!(layout.ull_root(), root.join(".ull"));
+}
+
+#[test]
+fn asset_paths_use_two_level_sharding() {
+    let (_temp, layout) = layout();
+    let root = layout.root();
+
+    assert_eq!(layout.asset_index("5"), root.join("assets/indexes/5.json"));
+    let hash = "a3b3b1b0e0d8f2a8f0fbe1a4b0a8f6a1c6c6a7a2";
+    assert_eq!(
+        layout.asset_object(hash).expect("哈希合法"),
+        root.join("assets/objects/a3").join(hash)
+    );
+    assert_eq!(
+        layout.log_config("client-1.12.xml"),
+        root.join("assets/log_configs/client-1.12.xml")
+    );
+
+    let error = layout.asset_object("a").expect_err("短哈希应报错");
+    assert!(matches!(error, GameError::InvalidAssetHash { .. }));
+}
+
+#[test]
+fn maven_coordinates_parse_and_lay_out() {
+    let coordinate = MavenCoordinate::parse("org.lwjgl:lwjgl:3.3.2").expect("坐标应可解析");
+    assert_eq!(coordinate.group, "org.lwjgl");
+    assert_eq!(coordinate.group_path(), "org/lwjgl");
+    assert_eq!(coordinate.file_name(), "lwjgl-3.3.2.jar");
+    assert_eq!(
+        coordinate.relative_path(),
+        PathBuf::from("org/lwjgl/lwjgl/3.3.2/lwjgl-3.3.2.jar")
+    );
+
+    let natives =
+        MavenCoordinate::parse("org.lwjgl:lwjgl:3.3.2:natives-windows-64").expect("带分类器");
+    assert_eq!(
+        natives.relative_path(),
+        PathBuf::from("org/lwjgl/lwjgl/3.3.2/lwjgl-3.3.2-natives-windows-64.jar")
+    );
+
+    let non_jar = MavenCoordinate::parse("net.java:jinput:1.0.0@zip").expect("带扩展名");
+    assert_eq!(non_jar.file_name(), "jinput-1.0.0.zip");
+}
+
+#[test]
+fn invalid_coordinates_are_rejected() {
+    for raw in ["a:b", "a::1", "a:b:c:d:e"] {
+        let error = MavenCoordinate::parse(raw).expect_err("不合法坐标应报错");
+        assert!(
+            matches!(error, GameError::InvalidCoordinate { .. }),
+            "{raw}"
+        );
+    }
+}
+
+#[test]
+fn library_paths_land_under_libraries() {
+    let (_temp, layout) = layout();
+    let root = layout.root();
+    let coordinate = MavenCoordinate::parse("com.mojang:logging:1.1.1").expect("坐标应可解析");
+
+    assert_eq!(
+        layout.library(&coordinate),
+        root.join("libraries/com/mojang/logging/1.1.1/logging-1.1.1.jar")
+    );
+    assert_eq!(
+        layout.version_library("1.20.1", &coordinate),
+        root.join("versions/1.20.1/libraries/com/mojang/logging/1.1.1/logging-1.1.1.jar")
+    );
+}
+
+#[test]
+fn installed_versions_requires_manifest_file() {
+    let (_temp, layout) = layout();
+
+    assert!(
+        layout
+            .installed_versions()
+            .expect("缺目录视为空")
+            .is_empty(),
+        "目录不存在时不能报错"
+    );
+
+    let version_dir = layout.version_dir("1.20.1");
+    std::fs::create_dir_all(&version_dir).expect("建目录");
+    std::fs::write(layout.version_json("1.20.1"), "{}").expect("写清单");
+    // 只有 jar 没有 json 的目录不算已安装。
+    let broken = layout.version_dir("1.19.4");
+    std::fs::create_dir_all(&broken).expect("建目录");
+    std::fs::write(layout.version_jar("1.19.4"), b"jar").expect("写 jar");
+
+    assert!(layout.is_version_installed("1.20.1"));
+    assert!(!layout.is_version_installed("1.19.4"));
+    assert_eq!(
+        layout.installed_versions().expect("应可枚举"),
+        vec!["1.20.1".to_owned()]
+    );
+}
diff --git a/crates/core/tests/game/main.rs b/crates/core/tests/game/main.rs
new file mode 100644
index 0000000..25cc1de
--- /dev/null
+++ b/crates/core/tests/game/main.rs
@@ -0,0 +1,30 @@
+//! `core::game` 的集成测试入口（阶段 A：先写好，mod.rs 接线在阶段 B 完成）。
+//!
+//! 每个子模块对应 mission 清单里的一项：
+//! - `manifest_parse`：版本 JSON 解析与保真
+//! - `inherit_chain`：inheritsFrom 解析 / 环检测 / 缺失父 / merge 语义 / patch 优先级
+//! - `arguments_rules`：规则求值、参数展开、natives 选择
+//! - `version_list`：清单 v2 解析、分类、排序、unlisted 合并
+//! - `layout`：`.minecraft` 目录布局
+//! - `snapshot`：不可变快照 + 单写者草稿
+//! - `profiles`：实例清单与稳定 UUID
+//! - `vulkan_capability`：版本库表 → `has_vulkan_backend` 能力位
+
+mod arguments_rules;
+mod helpers;
+mod inherit_chain;
+mod isolation;
+mod isolation_switch;
+mod java_discover;
+mod java_install;
+mod java_location;
+mod java_mapping;
+mod java_mirrors;
+mod java_vendor_chain;
+mod layout;
+mod manifest_parse;
+mod profiles;
+mod snapshot;
+mod unlisted;
+mod version_list;
+mod vulkan_capability;
diff --git a/crates/core/tests/game/manifest_parse.rs b/crates/core/tests/game/manifest_parse.rs
new file mode 100644
index 0000000..83610fa
--- /dev/null
+++ b/crates/core/tests/game/manifest_parse.rs
@@ -0,0 +1,186 @@
+//! 版本 JSON 解析：宽松解析、未知字段保真、旧版字段并存。
+
+use unlucky_core::game::arguments::{Argument, ArgumentValue, RuleAction};
+use unlucky_core::game::manifest::VersionJson;
+use unlucky_core::game::version::ReleaseType;
+
+use crate::helpers::parse;
+
+const VANILLA_1_20_1: &str = r#"{
+  "id": "1.20.1",
+  "type": "release",
+  "time": "2023-06-12T13:25:51+00:00",
+  "releaseTime": "2023-06-12T13:25:51+00:00",
+  "complianceLevel": 1,
+  "minimumLauncherVersion": 21,
+  "mainClass": "net.minecraft.client.main.Main",
+  "assets": "5",
+  "assetIndex": {
+    "id": "5",
+    "sha1": "a3b3b1b0e0d8f2a8f0fbe1a4b0a8f6a1c6c6a7a2",
+    "size": 404297,
+    "totalSize": 598385820,
+    "url": "https://piston-meta.mojang.com/v1/packages/sha/5.json"
+  },
+  "javaVersion": { "component": "java-runtime-gamma", "majorVersion": 17 },
+  "downloads": {
+    "client": { "sha1": "abc", "size": 100, "url": "https://example.invalid/client.jar" },
+    "client_mappings": { "sha1": "def", "size": 50, "url": "https://example.invalid/mappings.txt" }
+  },
+  "arguments": {
+    "game": [
+      "--username",
+      "${auth_player_name}",
+      { "rules": [{ "action": "allow", "features": { "has_custom_resolution": true } }],
+        "value": ["--width", "${resolution_width}"] }
+    ],
+    "jvm": [
+      { "rules": [{ "action": "allow", "os": { "name": "windows", "version": "^10\\." } }],
+        "value": "-Dos.name=Windows 10" }
+    ]
+  },
+  "libraries": [
+    { "name": "com.mojang:logging:1.1.1",
+      "downloads": { "artifact": { "path": "com/mojang/logging/1.1.1/logging-1.1.1.jar",
+                                   "sha1": "aaa", "size": 10,
+                                   "url": "https://example.invalid/logging.jar" } } }
+  ],
+  "logging": {
+    "client": { "argument": "-Dlog4j.configurationFile=${path}",
+                "file": { "id": "client-1.12.xml", "sha1": "bbb", "size": 20,
+                          "url": "https://example.invalid/log4j.xml" },
+                "type": "log4j2-xml" }
+  },
+  "tlauncherVersion": 1,
+  "MMC-hint": "local"
+}"#;
+
+#[test]
+fn parses_full_version_json() {
+    let version = parse(VANILLA_1_20_1);
+
+    assert_eq!(version.id.as_deref(), Some("1.20.1"));
+    assert_eq!(version.version_type, Some(ReleaseType::Release));
+    assert_eq!(
+        version.main_class.as_deref(),
+        Some("net.minecraft.client.main.Main")
+    );
+    assert_eq!(version.compliance_level, Some(1));
+    assert_eq!(version.minimum_launcher_version, Some(21));
+    assert_eq!(version.assets_id(), "5");
+
+    let asset_index = version.asset_index.as_ref().expect("assetIndex 应解析");
+    assert_eq!(asset_index.id, "5");
+    assert_eq!(asset_index.total_size, Some(598_385_820));
+
+    let java = version.java_version.as_ref().expect("javaVersion 应解析");
+    assert_eq!(java.component.as_deref(), Some("java-runtime-gamma"));
+    assert_eq!(java.major_version, Some(17));
+
+    let downloads = version.downloads.as_ref().expect("downloads 应解析");
+    assert_eq!(downloads.len(), 2, "未知键也要保留在映射里");
+    assert_eq!(
+        downloads.client().and_then(|c| c.url.as_deref()),
+        Some("https://example.invalid/client.jar")
+    );
+    assert!(downloads.get("client_mappings").is_some());
+}
+
+#[test]
+fn keeps_unknown_fields_verbatim() {
+    let version = parse(VANILLA_1_20_1);
+    // 第三方启动器私有字段（rawJson 保真，analyse/03 §4.2）。
+    assert_eq!(
+        version.extra.get("tlauncherVersion"),
+        Some(&serde_json::json!(1))
+    );
+    assert_eq!(
+        version.extra.get("MMC-hint"),
+        Some(&serde_json::json!("local"))
+    );
+
+    let roundtrip = version.to_json_string().expect("应可序列化");
+    let reparsed = VersionJson::from_json_str(&roundtrip).expect("应可再解析");
+    assert_eq!(reparsed.extra, version.extra);
+}
+
+#[test]
+fn parses_arguments_with_rules() {
+    let version = parse(VANILLA_1_20_1);
+    let arguments = version.arguments.as_ref().expect("arguments 应解析");
+
+    assert_eq!(arguments.game.len(), 3);
+    assert_eq!(arguments.jvm.len(), 1);
+    assert!(matches!(&arguments.game[0], Argument::Plain(value) if value == "--username"));
+
+    let conditional = match &arguments.game[2] {
+        Argument::Conditional(cond) => cond,
+        Argument::Plain(_) => panic!("第三项应是条件参数"),
+    };
+    assert_eq!(conditional.rules.len(), 1);
+    assert_eq!(conditional.rules[0].action, RuleAction::Allow);
+    assert_eq!(
+        conditional.rules[0]
+            .features
+            .as_ref()
+            .and_then(|f| f.get("has_custom_resolution")),
+        Some(&true)
+    );
+    assert_eq!(
+        conditional.value,
+        ArgumentValue::Many(vec!["--width".into(), "${resolution_width}".into()])
+    );
+
+    // jvm 里的 os 限制带正则版本模式。
+    let jvm = match &arguments.jvm[0] {
+        Argument::Conditional(cond) => cond,
+        Argument::Plain(_) => panic!("jvm 第一项应是条件参数"),
+    };
+    let os = jvm.rules[0].os.as_ref().expect("应有 os 限制");
+    assert_eq!(os.name.as_deref(), Some("windows"));
+    assert_eq!(os.version.as_deref(), Some("^10\\."));
+}
+
+#[test]
+fn parses_libraries_and_logging() {
+    let version = parse(VANILLA_1_20_1);
+    let libraries = version.libraries.as_ref().expect("libraries 应解析");
+    assert_eq!(libraries.len(), 1);
+    let artifact = libraries[0].artifact().expect("应有 artifact");
+    assert_eq!(
+        artifact.path.as_deref(),
+        Some("com/mojang/logging/1.1.1/logging-1.1.1.jar")
+    );
+
+    let logging = version.logging.as_ref().expect("logging 应解析");
+    let client = logging.client().expect("应有 client 日志配置");
+    assert_eq!(client.kind.as_deref(), Some("log4j2-xml"));
+    assert_eq!(client.file.id.as_deref(), Some("client-1.12.xml"));
+}
+
+#[test]
+fn tolerant_defaults_for_minimal_json() {
+    let version = parse(r#"{ "id": "b1.7.3" }"#);
+    assert_eq!(version.id.as_deref(), Some("b1.7.3"));
+    assert_eq!(version.version_type, None, "未知 type 不报错");
+    assert_eq!(version.client_jar(), None, "老 JSON 没有 downloads.client");
+    assert_eq!(version.assets_id(), "legacy", "assets 缺失按 legacy");
+    assert!(!version.is_resolved());
+}
+
+#[test]
+fn unknown_type_value_falls_back_to_unknown() {
+    let version = parse(r#"{ "id": "x", "type": "some_new_kind" }"#);
+    assert_eq!(version.version_type, Some(ReleaseType::Unknown));
+}
+
+#[test]
+fn missing_id_is_reported() {
+    let version = parse(r#"{ "mainClass": "a.B" }"#);
+    let error = version.require_id().expect_err("缺 id 应报错");
+    assert_eq!(
+        error.to_string(),
+        "版本 JSON 缺少 id",
+        "错误文案要给用户看得懂"
+    );
+}
diff --git a/crates/core/tests/game/profiles.rs b/crates/core/tests/game/profiles.rs
new file mode 100644
index 0000000..76e0fa0
--- /dev/null
+++ b/crates/core/tests/game/profiles.rs
@@ -0,0 +1,109 @@
+//! 实例清单：稳定 UUID、增删查、落盘格式兼容。
+
+use unlucky_core::game::profiles::{
+    InstanceProfile, ProfileId, ProfileList, PROFILE_SCHEMA_VERSION,
+};
+
+#[test]
+fn generated_ids_are_unique_and_uuid_shaped() {
+    let ids: Vec<ProfileId> = (0..256).map(|_| ProfileId::generate()).collect();
+    for id in &ids {
+        assert!(id.is_uuid_shaped(), "id 形状不对: {id}");
+    }
+    let mut unique: Vec<&str> = ids.iter().map(ProfileId::as_str).collect();
+    let total = unique.len();
+    unique.sort_unstable();
+    unique.dedup();
+    assert_eq!(unique.len(), total, "同一批生成的 id 不能重复");
+}
+
+#[test]
+fn id_shape_validation_rejects_junk() {
+    assert!(!ProfileId::new("not-a-uuid").is_uuid_shaped());
+    assert!(!ProfileId::new("").is_uuid_shaped());
+    assert!(ProfileId::new("7c9e6679-7425-40de-944b-e07fc1f90ae7").is_uuid_shaped());
+}
+
+#[test]
+fn upsert_and_remove_keep_one_entry_per_id() {
+    let mut list = ProfileList::default();
+    assert_eq!(list.schema_version, PROFILE_SCHEMA_VERSION);
+    assert!(list.is_empty());
+
+    let mut profile = InstanceProfile::new("主世界", "1.20.1");
+    assert_eq!(list.upsert(profile.clone()), None, "首次插入没有旧值");
+    assert_eq!(list.len(), 1);
+
+    profile.name = "主世界（Fabric）".to_owned();
+    let replaced = list.upsert(profile.clone()).expect("同 id 应替换");
+    assert_eq!(replaced.name, "主世界");
+    assert_eq!(list.len(), 1);
+    assert_eq!(
+        list.get(&profile.id).map(|p| p.name.as_str()),
+        Some("主世界（Fabric）")
+    );
+
+    let removed = list.remove(&profile.id).expect("应可删除");
+    assert_eq!(removed.id, profile.id);
+    assert!(list.is_empty());
+    assert!(list.remove(&profile.id).is_none());
+}
+
+#[test]
+fn profiles_group_by_version() {
+    let mut list = ProfileList::default();
+    list.upsert(InstanceProfile::new("a", "1.20.1"));
+    list.upsert(InstanceProfile::new("b", "1.20.1"));
+    list.upsert(InstanceProfile::new("c", "1.19.4"));
+
+    assert_eq!(list.for_version("1.20.1").len(), 2);
+    assert_eq!(list.for_version("1.19.4").len(), 1);
+    assert!(list.for_version("1.18.2").is_empty());
+}
+
+#[test]
+fn roundtrips_profiles_json() {
+    let mut list = ProfileList::default();
+    let mut profile = InstanceProfile::new("整合包", "1.20.1-forge-47.2.0");
+    profile.running_dir = Some(std::path::PathBuf::from("D:/mc/runs/pack"));
+    profile
+        .extra
+        .insert("thirdPartyFlag".to_owned(), serde_json::json!(true));
+    list.upsert(profile.clone());
+
+    let json = list.to_json_string().expect("应可序列化");
+    let reparsed = ProfileList::from_json_str(&json).expect("应可再解析");
+    assert_eq!(reparsed, list);
+    assert_eq!(reparsed.schema_version, PROFILE_SCHEMA_VERSION);
+}
+
+#[test]
+fn reads_minimal_profile_file() {
+    // 用户手改/旧版本写下的最小档案：只有三个必填语义字段，其它缺省。
+    let list = ProfileList::from_json_str(
+        r#"{ "profiles": [ { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
+                             "name": "旧档案", "version_id": "1.12.2" } ] }"#,
+    )
+    .expect("最小档案应可解析");
+
+    assert_eq!(
+        list.schema_version, PROFILE_SCHEMA_VERSION,
+        "schemaVersion 缺省补齐"
+    );
+    assert_eq!(list.len(), 1);
+    let profile = &list.profiles[0];
+    assert_eq!(profile.name, "旧档案");
+    assert!(profile.running_dir.is_none());
+    assert!(profile.id.is_uuid_shaped());
+}
+
+#[test]
+fn invalid_profiles_json_reports_context() {
+    let error = ProfileList::from_json_str("{").expect_err("非法 JSON 应报错");
+    match error {
+        unlucky_core::game::error::GameError::Json { context, .. } => {
+            assert_eq!(context, "profiles")
+        }
+        other => panic!("期望 Json 错误，得到 {other:?}"),
+    }
+}
diff --git a/crates/core/tests/game/snapshot.rs b/crates/core/tests/game/snapshot.rs
new file mode 100644
index 0000000..b8876cc
--- /dev/null
+++ b/crates/core/tests/game/snapshot.rs
@@ -0,0 +1,75 @@
+//! 快照仓库：不可变读、单写者草稿、发布即指针交换。
+
+use std::sync::Arc;
+
+use unlucky_core::game::error::GameError;
+use unlucky_core::game::snapshot::{Snapshot, Store};
+
+#[test]
+fn snapshot_survives_draft_publish() {
+    let store = Store::new(vec!["1.20.1".to_owned()]);
+    let before = store.snapshot();
+
+    let mut draft = store.open_draft().expect("首个草稿应可打开");
+    draft.edit().push("1.20.2".to_owned());
+    let published = draft.commit();
+
+    // 旧快照不变（读端遍历时不会看到半新半旧的状态）。
+    assert_eq!(before.get().len(), 1);
+    assert_eq!(published.get().len(), 2);
+    assert_eq!(store.snapshot().get().len(), 2);
+}
+
+#[test]
+fn only_one_draft_at_a_time() {
+    let store = Store::new(0u32);
+    let draft = store.open_draft().expect("首个草稿应可打开");
+
+    match store.open_draft() {
+        Err(GameError::DraftBusy) => {}
+        other => panic!("第二个草稿必须被拒绝，得到 {other:?}"),
+    }
+
+    drop(draft);
+    let reopened = store.open_draft();
+    assert!(reopened.is_ok(), "放弃草稿后写权必须释放");
+}
+
+#[test]
+fn dropping_draft_discards_changes() {
+    let store = Store::new(vec![1u32]);
+    {
+        let mut draft = store.open_draft().expect("草稿应可打开");
+        draft.edit().push(2);
+    }
+    assert_eq!(store.snapshot().get(), &vec![1u32]);
+}
+
+#[test]
+fn replace_publishes_whole_table() {
+    let store = Store::new(vec!["old".to_owned()]);
+    let snapshot = store.replace(vec!["new".to_owned()]).expect("替换应成功");
+    assert_eq!(snapshot.get(), &vec!["new".to_owned()]);
+    assert_eq!(store.snapshot().get(), &vec!["new".to_owned()]);
+}
+
+#[test]
+fn clones_share_one_allocation() {
+    let store = Store::new(vec![1u32]);
+    let first = store.snapshot();
+    let second = first.clone();
+
+    assert!(Arc::ptr_eq(&first.shared(), &second.shared()));
+    assert_eq!(first, second);
+
+    let published = store.replace(vec![2u32]).expect("替换应成功");
+    assert!(!Arc::ptr_eq(&first.shared(), &published.shared()));
+    assert_eq!(first.get(), &vec![1u32], "旧快照保持旧内容");
+}
+
+#[test]
+fn snapshot_new_wraps_value() {
+    let snapshot = Snapshot::new("payload".to_owned());
+    assert_eq!(snapshot.get(), "payload");
+    assert_eq!(snapshot.clone().get(), "payload");
+}
diff --git a/crates/core/tests/game/unlisted.rs b/crates/core/tests/game/unlisted.rs
new file mode 100644
index 0000000..e891d29
--- /dev/null
+++ b/crates/core/tests/game/unlisted.rs
@@ -0,0 +1,90 @@
+//! 内嵌补充清单 `unlisted-versions.json`：条目数、分类分布、合并规则。
+//!
+//! 这些断言同时是**数据完整性守门**：内嵌数据换版本时如果条目数/分类崩了，
+//! 这里先红，而不是等用户在旧版列表里少看到几十个版本。
+
+use unlucky_core::game::unlisted::{self, EMBEDDED_VERSION_COUNT};
+use unlucky_core::game::version::{ReleaseType, RemoteVersion, VersionCategory, VersionList};
+
+#[test]
+fn embedded_list_has_expected_shape() {
+    let embedded = unlisted::versions();
+    assert_eq!(embedded.len(), EMBEDDED_VERSION_COUNT);
+    assert_eq!(
+        embedded.versions.len(),
+        unlisted::entries().len(),
+        "借用视图与清单一致"
+    );
+    assert!(embedded.latest.is_none(), "补充清单没有 latest 对象");
+
+    for entry in unlisted::entries() {
+        assert!(!entry.id.is_empty());
+        assert!(!entry.url.is_empty(), "每条都要有下载地址: {}", entry.id);
+        assert_ne!(
+            entry.version_type,
+            ReleaseType::Unknown,
+            "内嵌数据的 type 必须能归类: {}",
+            entry.id
+        );
+    }
+}
+
+#[test]
+fn embedded_categories_match_analysis() {
+    // analyse/03 §2.3 实测口径：old_alpha 88 / old_beta 16 / snapshot 70 /
+    // pending 20 / unobfuscated 11。
+    let counts = |category: VersionCategory| {
+        unlisted::entries()
+            .iter()
+            .filter(|v| v.version_type.category() == category)
+            .count()
+    };
+    assert_eq!(counts(VersionCategory::Old), 88 + 16);
+    assert_eq!(counts(VersionCategory::Snapshot), 70);
+    assert_eq!(counts(VersionCategory::Pending), 20);
+    assert_eq!(counts(VersionCategory::Unobfuscated), 11);
+    assert_eq!(counts(VersionCategory::Release), 0);
+}
+
+#[test]
+fn embedded_ids_are_unique() {
+    let mut ids: Vec<&str> = unlisted::entries().iter().map(|v| v.id.as_str()).collect();
+    let total = ids.len();
+    ids.sort_unstable();
+    ids.dedup();
+    assert_eq!(ids.len(), total, "同 id 重复会让合并结果不确定");
+}
+
+#[test]
+fn merge_adds_missing_entries_only() {
+    let mut official = VersionList {
+        latest: None,
+        versions: vec![RemoteVersion {
+            id: "a1.1.1".to_owned(),
+            version_type: ReleaseType::OldAlpha,
+            url: "https://example.invalid/official-a1.1.1.json".to_owned(),
+            time: None,
+            release_time: None,
+            sha1: Some("official".to_owned()),
+            size: Some(1),
+        }],
+    };
+
+    let added = unlisted::merge_into(&mut official);
+    assert_eq!(added, EMBEDDED_VERSION_COUNT - 1, "只补官方缺的条目");
+    assert_eq!(official.len(), EMBEDDED_VERSION_COUNT);
+
+    // 同 id 冲突时官方条目胜出（我们与 HMCL 的差异，见 unlisted 模块注释）。
+    assert_eq!(
+        official.find("a1.1.1").map(|v| v.url.as_str()),
+        Some("https://example.invalid/official-a1.1.1.json")
+    );
+}
+
+#[test]
+fn merge_into_empty_list_is_identity() {
+    let mut empty = VersionList::default();
+    assert!(empty.is_empty());
+    assert_eq!(unlisted::merge_into(&mut empty), EMBEDDED_VERSION_COUNT);
+    assert_eq!(empty, *unlisted::versions());
+}
diff --git a/crates/core/tests/game/version_list.rs b/crates/core/tests/game/version_list.rs
new file mode 100644
index 0000000..15407b3
--- /dev/null
+++ b/crates/core/tests/game/version_list.rs
@@ -0,0 +1,137 @@
+//! 版本清单（`version_manifest_v2.json`）：解析、分类、排序、与补充清单合并。
+
+use unlucky_core::game::error::GameError;
+use unlucky_core::game::version::{ReleaseType, RemoteVersion, VersionCategory, VersionList};
+
+const MANIFEST_V2: &str = r#"{
+  "latest": { "release": "1.20.1", "snapshot": "23w31a" },
+  "versions": [
+    { "id": "1.20.1", "type": "release", "url": "https://example.invalid/1.20.1.json",
+      "time": "2023-06-12T13:25:51+00:00", "releaseTime": "2023-06-12T13:25:51+00:00",
+      "sha1": "aaa", "size": 1000 },
+    { "id": "23w31a", "type": "snapshot", "url": "https://example.invalid/23w31a.json",
+      "time": "2023-08-02T12:00:00+00:00", "releaseTime": "2023-08-02T12:00:00+00:00",
+      "sha1": "bbb", "size": 900 },
+    { "id": "b1.7.3", "type": "old_beta", "url": "https://example.invalid/b1.7.3.json",
+      "time": "2011-07-08T00:00:00+00:00", "releaseTime": "2011-07-08T00:00:00+00:00" }
+  ]
+}"#;
+
+fn manifest() -> VersionList {
+    VersionList::from_json_str(MANIFEST_V2).expect("清单应可解析")
+}
+
+#[test]
+fn parses_manifest_v2_with_checksums() {
+    let list = manifest();
+    assert_eq!(list.len(), 3);
+
+    let latest = list.latest.as_ref().expect("latest 应解析");
+    assert_eq!(latest.release.as_deref(), Some("1.20.1"));
+    assert_eq!(latest.snapshot.as_deref(), Some("23w31a"));
+
+    let release = list.find("1.20.1").expect("1.20.1 应存在");
+    assert!(release.is_verifiable());
+    assert_eq!(release.size, Some(1000));
+    // 内嵌旧清单没有 sha1/size（v1 形态）。
+    assert!(!list.find("b1.7.3").expect("b1.7.3 应存在").is_verifiable());
+}
+
+#[test]
+fn classifies_release_types() {
+    assert_eq!(
+        ReleaseType::from_json_str("release").category(),
+        VersionCategory::Release
+    );
+    assert_eq!(
+        ReleaseType::from_json_str("old_beta").category(),
+        VersionCategory::Old
+    );
+    assert_eq!(
+        ReleaseType::from_json_str("old_alpha").category(),
+        VersionCategory::Old
+    );
+    assert_eq!(
+        ReleaseType::from_json_str("pending").category(),
+        VersionCategory::Pending
+    );
+    assert_eq!(
+        ReleaseType::from_json_str("unobfuscated").category(),
+        VersionCategory::Unobfuscated
+    );
+    assert_eq!(
+        ReleaseType::from_json_str("未见过").category(),
+        VersionCategory::Uncategorized
+    );
+    // 序列化回原始字符串，保证能原样写回清单。
+    assert_eq!(ReleaseType::OldBeta.as_json_str(), "old_beta");
+    assert_eq!(ReleaseType::Unknown.as_json_str(), "unknown");
+}
+
+#[test]
+fn sorts_newest_first() {
+    let mut list = manifest();
+    list.sort_newest_first();
+    let ids: Vec<&str> = list.versions.iter().map(|v| v.id.as_str()).collect();
+    assert_eq!(ids, vec!["23w31a", "1.20.1", "b1.7.3"]);
+}
+
+#[test]
+fn filters_by_ui_category() {
+    let list = manifest();
+    assert_eq!(list.filter_category(VersionCategory::Release).len(), 1);
+    assert_eq!(list.filter_category(VersionCategory::Snapshot).len(), 1);
+    assert_eq!(list.filter_category(VersionCategory::Old).len(), 1);
+    assert!(list.filter_category(VersionCategory::Pending).is_empty());
+}
+
+#[test]
+fn merging_keeps_existing_entries() {
+    let mut list = manifest();
+    let added = list.merge_missing(vec![
+        // 同 id 冲突：已有条目（官方）胜出，URL 不被覆盖。
+        RemoteVersion {
+            id: "1.20.1".to_owned(),
+            version_type: ReleaseType::Release,
+            url: "https://mirror.invalid/1.20.1.json".to_owned(),
+            time: None,
+            release_time: None,
+            sha1: None,
+            size: None,
+        },
+        RemoteVersion {
+            id: "a1.1.1".to_owned(),
+            version_type: ReleaseType::OldAlpha,
+            url: "https://mirror.invalid/a1.1.1.json".to_owned(),
+            time: None,
+            release_time: None,
+            sha1: None,
+            size: None,
+        },
+    ]);
+
+    assert_eq!(added, 1, "只应新增缺失条目");
+    assert_eq!(list.len(), 4);
+    assert_eq!(
+        list.find("1.20.1").map(|v| v.url.as_str()),
+        Some("https://example.invalid/1.20.1.json")
+    );
+    assert!(list.find("a1.1.1").is_some());
+}
+
+#[test]
+fn roundtrips_manifest_json() {
+    let list = manifest();
+    let json = list.to_json_string().expect("应可序列化");
+    let reparsed = VersionList::from_json_str(&json).expect("应可再解析");
+    assert_eq!(reparsed, list);
+}
+
+#[test]
+fn invalid_json_reports_context() {
+    let error = VersionList::from_json_str("not json").expect_err("非法 JSON 应报错");
+    match error {
+        GameError::Json { context, .. } => assert_eq!(context, "version_manifest"),
+        other => panic!("期望 Json 错误，得到 {other:?}"),
+    }
+}
diff --git a/crates/core/tests/game/vulkan_capability.rs b/crates/core/tests/game/vulkan_capability.rs
new file mode 100644
index 0000000..2f4fe6e
--- /dev/null
+++ b/crates/core/tests/game/vulkan_capability.rs
@@ -0,0 +1,125 @@
+//! 版本能力位：从版本 JSON 的库表推 `has_vulkan_backend`。
+//!
+//! 事实基线（`research/05-mc-vulkan.md` §2.2，piston-meta 921 个版本逐版扫过）：
+//! `org.lwjgl:lwjgl-vulkan` 从 **26.2-snapshot-1** 起出现，26.1 全线（含 `26w14a`）没有。
+//! 所以「库在不在」是判断版本带不带 Vulkan 后端的可靠依据。
+
+use unlucky_core::game::capability::{
+    is_vulkan_library, library_names_have_vulkan, VersionCapabilities,
+};
+use unlucky_core::game::manifest::VersionJson;
+
+use crate::helpers::parse;
+
+/// 26.2-snapshot-1 的库表形态（Vulkan 三件套 + 常规库，实测结构）。
+const VULKAN_ERA_JSON: &str = r#"{
+  "id": "26.2-snapshot-1",
+  "type": "snapshot",
+  "mainClass": "net.minecraft.client.main.Main",
+  "libraries": [
+    { "name": "org.lwjgl:lwjgl:3.4.1", "downloads": { "artifact": { "path": "org/lwjgl/lwjgl/3.4.1/lwjgl-3.4.1.jar" } } },
+    { "name": "org.lwjgl:lwjgl-vulkan:3.4.1", "downloads": { "artifact": { "path": "org/lwjgl/lwjgl-vulkan/3.4.1/lwjgl-vulkan-3.4.1.jar" } } },
+    { "name": "org.lwjgl:lwjgl-vulkan:3.4.1:natives-macos" },
+    { "name": "org.lwjgl:lwjgl-shaderc:3.4.1" },
+    { "name": "com.mojang:brigadier:1.3.10" }
+  ]
+}"#;
+
+/// 26.1（含 `26w14a` 周快照那一段）的库表：只有 opengl，没有 vulkan。
+const PRE_VULKAN_JSON: &str = r#"{
+  "id": "26.1",
+  "type": "release",
+  "mainClass": "net.minecraft.client.main.Main",
+  "libraries": [
+    { "name": "org.lwjgl:lwjgl:3.4.1" },
+    { "name": "org.lwjgl:lwjgl-glfw:3.4.1" },
+    { "name": "org.lwjgl:lwjgl-opengl:3.4.1" }
+  ]
+}"#;
+
+#[test]
+fn version_json_with_lwjgl_vulkan_carries_the_capability() {
+    let version = parse(VULKAN_ERA_JSON);
+    assert!(version.has_vulkan_backend());
+    let capabilities = VersionCapabilities::from_json(&version);
+    assert!(capabilities.has_vulkan_backend());
+}
+
+#[test]
+fn version_json_without_lwjgl_vulkan_lacks_the_capability() {
+    let version = parse(PRE_VULKAN_JSON);
+    assert!(!version.has_vulkan_backend());
+    assert_eq!(
+        VersionCapabilities::from_json(&version),
+        VersionCapabilities::default()
+    );
+}
+
+#[test]
+fn missing_libraries_field_is_not_a_capability() {
+    let version = parse(r#"{ "id": "custom", "mainClass": "a.B" }"#);
+    assert!(!version.has_vulkan_backend());
+}
+
+#[test]
+fn coordinate_forms_are_all_recognised() {
+    // 主构件、带 classifier 的 natives、带 @ext 的写法都算命中（只比对 group:artifact）。
+    assert!(is_vulkan_library("org.lwjgl:lwjgl-vulkan:3.4.3"));
+    assert!(is_vulkan_library(
+        "org.lwjgl:lwjgl-vulkan:3.4.3:natives-macos"
+    ));
+    assert!(is_vulkan_library("org.lwjgl:lwjgl-vulkan:3.4.3@jar"));
+
+    // 相邻但不该命中的（前缀相同 / group 不同）。
+    assert!(!is_vulkan_library("org.lwjgl:lwjgl-opengl:3.4.3"));
+    assert!(!is_vulkan_library("org.lwjgl:lwjgl:3.4.3"));
+    assert!(!is_vulkan_library("com.mojang:lwjgl-vulkan:1.0"));
+    assert!(!is_vulkan_library("lwjgl-vulkan"));
+    assert!(!is_vulkan_library(""));
+}
+
+#[test]
+fn library_name_slice_helper_matches_the_json_path() {
+    let names = ["org.lwjgl:lwjgl:3.4.1", "org.lwjgl:lwjgl-vulkan:3.4.1"];
+    assert!(library_names_have_vulkan(names));
+    assert!(!library_names_have_vulkan(["org.lwjgl:lwjgl:3.4.1"]));
+    assert!(!library_names_have_vulkan(std::iter::empty()));
+
+    // 与 game 侧的库表判定同源：同一份 JSON 两条路径给同一结论。
+    let version = parse(VULKAN_ERA_JSON);
+    assert_eq!(
+        library_names_have_vulkan(
+            version
+                .libraries
+                .as_deref()
+                .unwrap_or_default()
+                .iter()
+                .map(|l| l.name.as_str())
+        ),
+        version.has_vulkan_backend()
+    );
+}
+
+#[test]
+fn capability_bit_is_not_the_parameter_gate() {
+    // 26.2-snapshot-1 已经有库，却还没有 `--graphicsBackend`（实测差两天）。
+    // 能力位是「必要条件」，下发门限另有精确版本门（见 launch 侧
+    // `graphics_backend_allowed`），两者不能被压成一个判断。
+    let snapshot_one = parse(VULKAN_ERA_JSON);
+    assert!(
+        snapshot_one.has_vulkan_backend(),
+        "26.2-snapshot-1 有 Vulkan 库"
+    );
+    assert_eq!(snapshot_one.id.as_deref(), Some("26.2-snapshot-1"));
+}
+
+#[test]
+fn version_json_accessor_delegates_to_capability_module() {
+    for json in [VULKAN_ERA_JSON, PRE_VULKAN_JSON] {
+        let version: VersionJson = parse(json);
+        assert_eq!(
+            version.has_vulkan_backend(),
+            VersionCapabilities::from_json(&version).has_vulkan_backend()
+        );
+    }
+}
diff --git a/crates/core/tests/launch/adapter_cases.rs b/crates/core/tests/launch/adapter_cases.rs
new file mode 100644
index 0000000..ee7f73d
--- /dev/null
+++ b/crates/core/tests/launch/adapter_cases.rs
@@ -0,0 +1,166 @@
+//! game 快照 → `LaunchRequest` 适配层测试（缺失库显式记录、features 派生）。
+
+use crate::prelude::*;
+
+fn write_file(path: &std::path::Path, content: &str) {
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent).expect("建目录");
+    }
+    std::fs::write(path, content).expect("写文件");
+}
+
+fn jvm_tokens() -> Vec<String> {
+    vec![
+        "-Djava.library.path=${natives_directory}".to_string(),
+        "-cp".to_string(),
+        "${classpath}".to_string(),
+    ]
+}
+
+fn game_tokens() -> Vec<String> {
+    vec![
+        "--username".to_string(),
+        "${auth_player_name}".to_string(),
+        "--version".to_string(),
+        "${version_name}".to_string(),
+    ]
+}
+
+#[test]
+fn adapter_records_missing_libraries_and_fails_before_start() {
+    let dir = temp_dir("adapter-strict");
+    let lib_ok = dir.join("libraries/a.jar");
+    let lib_missing = dir.join("libraries/b.jar");
+    let primary = dir.join("versions/1.20.1/1.20.1.jar");
+    write_file(&lib_ok, "x");
+    write_file(&primary, "x");
+    let libraries = vec![
+        LibraryInput::new(lib_ok.clone(), "org.example:a:1"),
+        LibraryInput::new(lib_missing.clone(), "org.example:b:2"),
+    ];
+    let jvm = jvm_tokens();
+    let game = game_tokens();
+    let snapshot = SnapshotInput {
+        version_name: Some("1.20.1 Fabric"),
+        version_type: Some("release"),
+        game_version: Some("1.20.1"),
+        main_class: Some("net.fabricmc.loader.impl.launch.knot.KnotClient"),
+        jvm_arguments: &jvm,
+        game_arguments: &game,
+        libraries: &libraries,
+        primary_jar: primary.clone(),
+        game_dir: dir.clone(),
+        assets_index: Some("17"),
+        natives_dir: dir.join("versions/1.20.1/natives"),
+        library_dir: dir.join("libraries"),
+        assets_root: dir.join("assets"),
+        game_assets: dir.join("assets/virtual/legacy"),
+        ..SnapshotInput::minimal("1.20.1", "")
+    };
+    let mut options = AdapterOptions::strict();
+    options.java = JavaSelection::new("C:/java/bin/java.exe", 21, 64);
+    options.memory = MemoryOptions {
+        min_mb: Some(512),
+        max_mb: Some(2048),
+    };
+    options.resolution = Some(Resolution {
+        width: 1280,
+        height: 720,
+    });
+
+    let output = build_request(&snapshot, options);
+    assert_eq!(output.classpath_entries, 2, "a.jar + 主 jar");
+    assert_eq!(output.missing.len(), 1);
+    assert_eq!(output.missing[0].name, "org.example:b:2");
+    assert!(output.warnings.iter().any(|warning| matches!(
+        warning,
+        AdapterWarning::MissingLibrary { name, .. } if name == "org.example:b:2"
+    )));
+    // features 派生：给了分辨率就打开 has_custom_resolution；1.20.1 支持 QuickPlay。
+    assert!(output.request.features.has_custom_resolution);
+    assert!(output.request.features.has_quick_plays_support);
+    assert_eq!(output.request.instance.name, "1.20.1 Fabric");
+    assert_eq!(
+        output.request.manifest.main_class.as_deref(),
+        Some("net.fabricmc.loader.impl.launch.knot.KnotClient")
+    );
+
+    // 严格模式下缺失库 → 组装前显式失败（不再交给运行时 NoClassDefFoundError）。
+    let ctx = PlatformCtx::new(OsFamily::Windows, "x86_64");
+    match assemble(&output.request, &ctx) {
+        Err(LaunchError::Assembly(AssemblyError::MissingComponents(items))) => {
+            assert_eq!(items.len(), 1);
+        }
+        other => panic!("应因缺组件失败，实际：{other:?}"),
+    }
+}
+
+#[test]
+fn adapter_tolerant_mode_skips_missing_libraries() {
+    let dir = temp_dir("adapter-tolerant");
+    let lib_missing = dir.join("libraries/b.jar");
+    let libraries = vec![LibraryInput::new(lib_missing.clone(), "org.example:b:2")];
+    let jvm = jvm_tokens();
+    let snapshot = SnapshotInput {
+        main_class: Some("net.minecraft.client.main.Main"),
+        jvm_arguments: &jvm,
+        libraries: &libraries,
+        primary_jar: dir.join("client.jar"),
+        game_dir: dir.clone(),
+        assets_index: Some("5"),
+        ..SnapshotInput::minimal("1.12.2", "")
+    };
+    let mut options = AdapterOptions::strict();
+    options.check_classpath = false;
+    options.java = JavaSelection::new("java", 8, 64);
+
+    let output = build_request(&snapshot, options);
+    assert!(
+        !output.request.classpath.is_empty(),
+        "宽松模式仍保留库（交给启动期报错）"
+    );
+    assert!(output.request.missing_components.is_empty());
+    // 宽松模式不报缺失库（其它告警——如缺游戏参数——与本用例无关）。
+    assert!(!output
+        .warnings
+        .iter()
+        .any(|warning| matches!(warning, AdapterWarning::MissingLibrary { .. })));
+}
+
+#[test]
+fn adapter_warns_on_incomplete_manifest() {
+    let dir = temp_dir("adapter-incomplete");
+    let snapshot = SnapshotInput {
+        main_class: None,
+        ..SnapshotInput::minimal("1.7.10", "")
+    };
+    let output = build_request(&snapshot, AdapterOptions::strict());
+    let warnings = &output.warnings;
+    assert!(warnings.contains(&AdapterWarning::MissingMainClass));
+    assert!(warnings.contains(&AdapterWarning::MissingAssetsIndex));
+    assert!(warnings.contains(&AdapterWarning::MissingGameArguments));
+    // 1.7.10 < 1.20：不支持 QuickPlay。
+    assert!(!output.request.features.has_quick_plays_support);
+    assert_eq!(
+        output.request.dirs.assets_index, "legacy",
+        "缺索引时兜底 legacy"
+    );
+    let _ = dir;
+}
+
+#[test]
+fn adapter_legacy_arguments_are_passed_through() {
+    let dir = temp_dir("adapter-legacy");
+    let snapshot = SnapshotInput {
+        main_class: Some("net.minecraft.launchwrapper.Launch"),
+        legacy_arguments: Some("--username ${auth_player_name} --gameDir ${game_directory}"),
+        game_dir: dir.clone(),
+        ..SnapshotInput::minimal("1.12.2", "")
+    };
+    let output = build_request(&snapshot, AdapterOptions::strict());
+    assert!(output.request.manifest.is_legacy());
+    assert!(output.request.manifest.game.is_empty());
+    assert!(!output
+        .warnings
+        .contains(&AdapterWarning::MissingGameArguments));
+}
diff --git a/crates/core/tests/launch/cmdline_snapshot.rs b/crates/core/tests/launch/cmdline_snapshot.rs
new file mode 100644
index 0000000..906649f
--- /dev/null
+++ b/crates/core/tests/launch/cmdline_snapshot.rs
@@ -0,0 +1,338 @@
+//! 命令行组装快照测试（`analyse/02` §4.1 的 33 项顺序表 + §4.2 默认值抑制）。
+//!
+//! 期望值是手工核对过的**完整 argv**：一旦组装顺序变了，这里必须一起改——
+//! 顺序本身有语义（后加的默认值会被先加的显式值抑制）。
+
+use crate::prelude::*;
+
+#[test]
+fn legacy_forge_full_argv() {
+    let (mut request, ctx) = legacy_forge_request();
+    request.mod_loader = ModLoaderKind::Forge;
+    request.manifest.legacy_arguments = Some(
+        "--username ${auth_player_name} --version ${version_name} --gameDir ${game_directory} \
+         --assetsDir ${assets_root} --assetIndex ${assets_index_name} --uuid ${auth_uuid} \
+         --accessToken ${auth_session} --userType ${user_type} \
+         --tweakClass net.minecraftforge.fml.common.launcher.FMLTweaker"
+            .to_string(),
+    );
+    // 用户指定 GBK → 日志泵也必须用 GBK 解码（`analyse/02` §4.4）。
+    request.user.jvm = vec!["-Dfile.encoding=GBK".to_string()];
+
+    let command = assemble(&request, &ctx).expect("组装应成功");
+    assert_eq!(command.encoding, "GBK");
+    assert_eq!(command.main_class, "net.minecraft.launchwrapper.Launch");
+    assert_eq!(command.classpath.len(), 3, "主 jar 必须追加在末位");
+
+    assert_argv(
+        &command,
+        &[
+            "C:/java/bin/java.exe",
+            "-Xmx4096m",
+            "-Xms1024m",
+            "-XX:MetaspaceSize=64m",
+            "-Dfile.encoding=GBK",
+            "-Dsun.stdout.encoding=GBK",
+            "-Dsun.stderr.encoding=GBK",
+            "-Djava.rmi.server.useCodebaseOnly=true",
+            "-Dcom.sun.jndi.rmi.object.trustURLCodebase=false",
+            "-Dcom.sun.jndi.cosnaming.object.trustURLCodebase=false",
+            "-Dlog4j2.formatMsgNoLookups=true",
+            "-Dlog4j.configurationFile=C:/mc/log4j2.xml",
+            "-Dminecraft.client.jar=C:/mc/versions/1.12.2/1.12.2.jar",
+            "-Dfml.ignoreInvalidMinecraftCertificates=true",
+            "-Dfml.ignorePatchDiscrepancies=true",
+            "-Djava.library.path=C:/mc/versions/1.12.2/natives-windows-x86_64",
+            "-cp",
+            "C:/mc/libraries/a.jar;C:/mc/libraries/b.jar;C:/mc/versions/1.12.2/1.12.2.jar",
+            "net.minecraft.launchwrapper.Launch",
+            "--username",
+            "Steve",
+            "--version",
+            "1.12.2-Forge",
+            "--gameDir",
+            "C:/mc",
+            "--assetsDir",
+            "C:/mc/assets",
+            "--assetIndex",
+            "1.12",
+            "--uuid",
+            "0123456789abcdef0123456789abcdef",
+            "--accessToken",
+            "SECRET-TOKEN-123456",
+            "--userType",
+            "msa",
+            "--tweakClass",
+            "net.minecraftforge.fml.common.launcher.FMLTweaker",
+            "--width",
+            "854",
+            "--height",
+            "480",
+        ],
+    );
+}
+
+#[test]
+fn modern_fabric_full_argv_with_rules() {
+    let (mut request, ctx) = legacy_forge_request();
+    request.instance.name = "1.20.1-Fabric".to_string();
+    request.instance.version = GameVersion::parse("1.20.1");
+    request.manifest.main_class =
+        Some("net.fabricmc.loader.impl.launch.knot.KnotClient".to_string());
+    request.manifest.legacy_arguments = None;
+    request.manifest.jvm = vec![
+        ArgumentEntry::plain(["-Djava.library.path=${natives_directory}"]),
+        ArgumentEntry::plain(["-cp", "${classpath}"]),
+    ];
+    request.manifest.game = vec![
+        ArgumentEntry::plain(["--username", "${auth_player_name}"]),
+        ArgumentEntry::plain(["--version", "${version_name}"]),
+        ArgumentEntry::ruled(
+            vec![Rule::allow().with_os_name("windows")],
+            ["-Dos.windows=true"],
+        ),
+        ArgumentEntry::ruled(vec![Rule::allow().with_os_name("osx")], ["-Dos.macos=true"]),
+        ArgumentEntry::ruled(
+            vec![Rule::allow().with_feature("has_custom_resolution", true)],
+            [
+                "--width",
+                "${resolution_width}",
+                "--height",
+                "${resolution_height}",
+            ],
+        ),
+        // 先 allow 后 disallow：按“最后一个命中的 action”生效（`analyse/02` §4.7）。
+        ArgumentEntry::ruled(
+            vec![
+                Rule::allow().with_os_name("windows"),
+                Rule::disallow().with_feature("is_demo_user", true),
+            ],
+            ["--windows-only"],
+        ),
+    ];
+    request.resolution = Some(Resolution {
+        width: 1280,
+        height: 720,
+    });
+    request.user.game = vec!["--fullscreen".to_string()];
+
+    let command = assemble(&request, &ctx).expect("组装应成功");
+    // 主 jar 由组装器追加到最后，manifest 里的 `-cp` 只覆盖库。
+    assert_eq!(command.classpath.len(), 3);
+
+    assert_argv(
+        &command,
+        &[
+            "C:/java/bin/java.exe",
+            "-Xmx4096m",
+            "-Xms1024m",
+            "-XX:MetaspaceSize=64m",
+            "-Dfile.encoding=UTF-8",
+            "-Dsun.stdout.encoding=UTF-8",
+            "-Dsun.stderr.encoding=UTF-8",
+            "-Djava.rmi.server.useCodebaseOnly=true",
+            "-Dcom.sun.jndi.rmi.object.trustURLCodebase=false",
+            "-Dcom.sun.jndi.cosnaming.object.trustURLCodebase=false",
+            "-Dlog4j2.formatMsgNoLookups=true",
+            "-Dlog4j.configurationFile=C:/mc/log4j2.xml",
+            "-Dminecraft.client.jar=C:/mc/versions/1.12.2/1.12.2.jar",
+            "-Djava.library.path=C:/mc/versions/1.12.2/natives-windows-x86_64",
+            "-cp",
+            "C:/mc/libraries/a.jar;C:/mc/libraries/b.jar;C:/mc/versions/1.12.2/1.12.2.jar",
+            "net.fabricmc.loader.impl.launch.knot.KnotClient",
+            "--username",
+            "Steve",
+            "--version",
+            "1.20.1-Fabric",
+            "-Dos.windows=true",
+            "--width",
+            "1280",
+            "--height",
+            "720",
+            "--windows-only",
+            "--fullscreen",
+        ],
+    );
+    assert!(!command.args.iter().any(|arg| arg == "-Dos.macos=true"));
+}
+
+#[test]
+fn user_override_beats_defaults() {
+    let (mut request, ctx) = legacy_forge_request();
+    request.java = JavaSelection::new("C:/java8/bin/java.exe", 8, 32);
+    request.user.override_jvm = vec!["-Xmx8G".to_string(), "-XX:+UseSerialGC".to_string()];
+    request.user.jvm = vec!["-Xmx2G".to_string()];
+    request.optimization = OptimizationOptions {
+        enabled: true,
+        physical_memory_mb: Some(8192),
+    };
+    request.manifest.legacy_arguments = None;
+
+    let command = assemble(&request, &ctx).expect("组装应成功");
+    let args = command.args;
+    // override 的 -Xmx8G 生效，默认的 -Xmx4096m 被抑制。
+    assert!(args.iter().any(|arg| arg == "-Xmx8G"));
+    assert!(!args.iter().any(|arg| arg == "-Xmx4096m"));
+    // 用户 JVM 参数里的 -Xmx2G 属于“默认值”，被 override 抑制。
+    assert!(!args.iter().any(|arg| arg == "-Xmx2G"));
+    // 用户显式挑了 GC → 不注入 G1 整组，但诊断关键项照旧。
+    assert!(args.iter().any(|arg| arg == "-XX:+UseSerialGC"));
+    assert!(!args.iter().any(|arg| arg == "-XX:+UseG1GC"));
+    assert!(args
+        .iter()
+        .any(|arg| arg == "-XX:-OmitStackTraceInFastThrow"));
+    // 32 位老 Java → PermSize，且不因内存充裕注入 CodeCache 组。
+    assert!(args.iter().any(|arg| arg == "-XX:MetaspaceSize=64m"));
+    assert!(!args
+        .iter()
+        .any(|arg| arg.starts_with("-XX:ReservedCodeCacheSize")));
+}
+
+#[test]
+fn java8_uses_legacy_encoding_keys_and_keeps_xincgc() {
+    let (mut request, ctx) = legacy_forge_request();
+    request.java = JavaSelection::new("C:/java8/bin/java.exe", 8, 32);
+    request.user.jvm = vec!["-Xincgc".to_string()];
+    request.manifest.legacy_arguments = None;
+    let command = assemble(&request, &ctx).expect("组装应成功");
+    assert!(command
+        .args
+        .iter()
+        .any(|arg| arg == "-Dsun.stdout.encoding=UTF-8"));
+    assert!(!command
+        .args
+        .iter()
+        .any(|arg| arg == "-Dstdout.encoding=UTF-8"));
+    // Java 8 上 -Xincgc 仍合法（只在 ≥9 上被禁，`analyse/02` §4.1 #33）。
+    assert!(command.args.iter().any(|arg| arg == "-Xincgc"));
+
+    let mut modern = request.clone();
+    modern.java = JavaSelection::new("C:/java21/bin/java.exe", 21, 64);
+    let command = assemble(&modern, &ctx).expect("组装应成功");
+    assert!(command
+        .args
+        .iter()
+        .any(|arg| arg == "-Dstdout.encoding=UTF-8"));
+    assert!(
+        !command.args.iter().any(|arg| arg == "-Xincgc"),
+        "Java ≥9 必须删掉 -Xincgc"
+    );
+}
+
+#[test]
+fn quickplay_and_graphics_backend_are_version_gated() {
+    let (mut request, ctx) = legacy_forge_request();
+    request.manifest.legacy_arguments = None;
+    request.quick_play = Some(QuickPlay::Multiplayer {
+        address: "mc.example.com:25565".to_string(),
+    });
+    request.graphics_backend = Some("vulkan".to_string());
+
+    // 1.12.2：QuickPlay 退化成 --server/--port，--graphicsBackend 丢弃。
+    let legacy = assemble(&request, &ctx).expect("组装应成功");
+    let server = legacy
+        .args
+        .windows(2)
+        .any(|pair| pair[0] == "--server" && pair[1] == "mc.example.com");
+    assert!(server, "老版本应退化为 --server");
+    assert!(legacy
+        .args
+        .windows(2)
+        .any(|pair| pair[0] == "--port" && pair[1] == "25565"));
+    assert!(!legacy.args.iter().any(|arg| arg == "--graphicsBackend"));
+    assert!(legacy
+        .warnings
+        .contains(&AssemblyWarning::QuickPlayDegraded {
+            address: "mc.example.com:25565".to_string()
+        }));
+    assert!(legacy
+        .warnings
+        .iter()
+        .any(|warning| matches!(warning, AssemblyWarning::GraphicsBackendSkipped { .. })));
+
+    // 26.3：QuickPlay 直用，--graphicsBackend 允许。
+    let mut modern = request.clone();
+    modern.instance.version = GameVersion::parse("26.3");
+    let modern = assemble(&modern, &ctx).expect("组装应成功");
+    assert!(modern
+        .args
+        .windows(2)
+        .any(|pair| pair[0] == "--quickPlayMultiplayer" && pair[1] == "mc.example.com:25565"));
+    assert!(modern
+        .args
+        .windows(2)
+        .any(|pair| pair[0] == "--graphicsBackend" && pair[1] == "vulkan"));
+}
+
+#[test]
+fn assembly_fails_fast_on_missing_components() {
+    let (mut request, ctx) = legacy_forge_request();
+    request.missing_components = vec![
+        MissingComponent::named("org.lwjgl:lwjgl:3.3.1"),
+        MissingComponent::at_path("net.minecraft:client", "C:/mc/versions/1.12.2/1.12.2.jar"),
+    ];
+    let error = assemble(&request, &ctx).expect_err("缺组件必须启动前失败");
+    match error {
+        LaunchError::Assembly(AssemblyError::MissingComponents(items)) => {
+            assert_eq!(items.len(), 2);
+            assert_eq!(items[0].name, "org.lwjgl:lwjgl:3.3.1");
+        }
+        other => panic!("错误类型不对：{other}"),
+    }
+
+    let (mut request, ctx) = legacy_forge_request();
+    request.manifest.main_class = None;
+    assert!(matches!(
+        assemble(&request, &ctx),
+        Err(LaunchError::Assembly(AssemblyError::MissingMainClass))
+    ));
+
+    let (mut request, ctx) = legacy_forge_request();
+    request.classpath.clear();
+    request.dirs.primary_jar = std::path::PathBuf::new();
+    assert!(matches!(
+        assemble(&request, &ctx),
+        Err(LaunchError::Assembly(AssemblyError::EmptyClasspath))
+    ));
+}
+
+#[test]
+fn posix_gets_nice_and_colon_classpath() {
+    let mut ctx = PlatformCtx::new(OsFamily::Linux, "x86_64");
+    ctx.home_dir = Some(std::path::PathBuf::from("/home/aska"));
+    let (mut request, _) = legacy_forge_request();
+    request.nice = Some(5);
+    request.wrapper = vec!["prime-run".to_string()];
+    request.manifest.legacy_arguments = None;
+
+    let command = assemble(&request, &ctx).expect("组装应成功");
+    assert_eq!(command.argv()[0], "nice");
+    assert_eq!(command.argv()[1], "-n");
+    assert_eq!(command.argv()[2], "5");
+    assert_eq!(command.argv()[3], "prime-run");
+    assert_eq!(command.argv()[4], "C:/java/bin/java.exe");
+    assert!(command
+        .args
+        .iter()
+        .any(|arg| arg
+            == "C:/mc/libraries/a.jar:C:/mc/libraries/b.jar:C:/mc/versions/1.12.2/1.12.2.jar"));
+    // 非 Windows 才注入 -Duser.home。
+    assert!(command
+        .args
+        .iter()
+        .any(|arg| arg.starts_with("-Duser.home=")));
+}
+
+#[test]
+fn placeholder_table_is_complete() {
+    let (request, ctx) = legacy_forge_request();
+    let map = unlucky_core::launch::placeholders::PlaceholderMap::from_request(&request, &ctx);
+    for key in unlucky_core::launch::placeholders::PLACEHOLDER_KEYS {
+        assert!(map.get(key).is_some(), "占位符 ${key} 未登记");
+    }
+    assert_eq!(map.get("primary_jar_name"), Some("1.12.2.jar"));
+    assert_eq!(map.get("version_name"), Some("1.12.2-Forge"));
+    // 未定义的占位符原样保留（便于发现清单漏项）。
+    assert_eq!(map.render("${nope}"), "${nope}");
+    assert_eq!(map.render("a${version_name}b"), "a1.12.2-Forgeb");
+}
diff --git a/crates/core/tests/launch/command_builder_cases.rs b/crates/core/tests/launch/command_builder_cases.rs
new file mode 100644
index 0000000..22934e8
--- /dev/null
+++ b/crates/core/tests/launch/command_builder_cases.rs
@@ -0,0 +1,148 @@
+//! `CommandBuilder` 默认值抑制语义测试（`analyse/02` §4.2）。
+
+use crate::prelude::*;
+
+fn strings(items: &[&str]) -> Vec<String> {
+    items.iter().map(|item| (*item).to_string()).collect()
+}
+
+#[test]
+fn add_default_suppresses_when_prefix_exists() {
+    let mut builder = CommandBuilder::new();
+    builder.add("-Xmx8G");
+    let existing = builder.add_default("-Xmx", "4096m");
+    assert_eq!(existing.as_deref(), Some("-Xmx8G"));
+    assert_eq!(builder.args(), &strings(&["-Xmx8G"]));
+
+    let added = builder.add_default("-Xms", "1024m");
+    assert_eq!(added, None);
+    assert_eq!(builder.args(), &strings(&["-Xmx8G", "-Xms1024m"]));
+}
+
+#[test]
+fn unstable_flags_do_not_conflict() {
+    let mut builder = CommandBuilder::new();
+    builder.add("-XX:-UseG1GC");
+    // 用户已经用 `-XX:-UseG1GC` 关掉了 G1，就不再补 `-XX:+UseG1GC`。
+    assert!(builder.add_unstable_flag("UseG1GC", true).is_some());
+    assert!(!builder.contains_exact("-XX:+UseG1GC"));
+
+    let mut builder = CommandBuilder::new();
+    builder.add("-XX:MaxInlineLevel=20");
+    assert!(builder
+        .add_unstable_default("MaxInlineLevel", "15")
+        .is_some());
+    assert_eq!(builder.args(), &strings(&["-XX:MaxInlineLevel=20"]));
+}
+
+#[test]
+fn add_all_default_handles_each_shape() {
+    let mut builder = CommandBuilder::new();
+    builder.add("-Dfile.encoding=GBK");
+    builder.add("-XX:+UseSerialGC");
+    builder.add("-Xmx8G");
+    builder.add("-cp");
+    builder.add("user-cp");
+
+    builder.add_all_default(&strings(&[
+        "-Dfile.encoding=UTF-8",
+        "-Dsun.stdout.encoding=UTF-8",
+        "-XX:+UseG1GC",
+        "-XX:G1MixedGCCountTarget=5",
+        "-Xmx4096m",
+        "-Xss1m",
+        "-cp",
+        "default-cp",
+        "exact-arg",
+    ]));
+
+    assert_eq!(
+        builder.args(),
+        &strings(&[
+            "-Dfile.encoding=GBK",
+            "-XX:+UseSerialGC",
+            "-Xmx8G",
+            "-cp",
+            "user-cp",
+            "-Dsun.stdout.encoding=UTF-8",
+            "-XX:+UseG1GC",
+            "-XX:G1MixedGCCountTarget=5",
+            "-Xss1m",
+            "exact-arg",
+        ])
+    );
+}
+
+#[test]
+fn argfile_expansion_suppresses_later_defaults() {
+    let mut builder = CommandBuilder::new();
+    builder.add_all_without_parsing_and_read_external(
+        &strings(&["@options.txt"]),
+        &|path: &str| {
+            if path == "options.txt" {
+                Some("-Xmx12G\n-Dfile.encoding=COMPAT\n".to_string())
+            } else {
+                None
+            }
+        },
+    );
+    // @argfile 里的 -Xmx12G 已登记为外部参数，默认值必须被抑制。
+    assert!(builder.add_default("-Xmx", "4096m").is_some());
+    assert!(builder.add_default("-Dfile.encoding=", "UTF-8").is_some());
+    // 外部参数只参与判重，不进 argv。
+    assert!(!builder.contains_exact("-Xmx12G"));
+    assert_eq!(builder.args(), &strings(&["@options.txt"]));
+}
+
+#[test]
+fn tokenize_handles_quotes_and_escapes() {
+    assert_eq!(
+        command_builder::tokenize(r#"--username "a b" --path 'C:\x y' plain"#),
+        strings(&["--username", "a b", "--path", "C:\\x y", "plain"])
+    );
+    assert_eq!(
+        command_builder::tokenize(r#"-Dmsg="say \"hi\"""#),
+        strings(&[r#"-Dmsg=say "hi""#])
+    );
+    assert!(command_builder::tokenize("   ").is_empty());
+}
+
+#[test]
+fn parse_argfile_ignores_comments_and_blank_lines() {
+    let contents = "# 注释\n-Xmx2G\n\n-Xms512m -Dfoo=bar\n";
+    assert_eq!(
+        command_builder::parse_argfile(contents),
+        strings(&["-Xmx2G", "-Xms512m", "-Dfoo=bar"])
+    );
+}
+
+#[test]
+fn forbidden_args_are_removed_at_the_end() {
+    let mut builder = CommandBuilder::new();
+    builder.add_all(&strings(&["-Xincgc", "-Xmx1G", "-Xincgc"]));
+    let removed = builder.remove_forbidden(&["-Xincgc"]);
+    assert_eq!(removed.len(), 2);
+    assert_eq!(builder.args(), &strings(&["-Xmx1G"]));
+}
+
+#[test]
+fn placeholders_are_rendered_on_add_but_not_on_raw_add() {
+    let mut map = unlucky_core::launch::placeholders::PlaceholderMap::new();
+    map.insert("version_name", "1.20.1");
+    let mut builder = CommandBuilder::with_placeholders(map);
+    builder.add("--version");
+    builder.add("${version_name}");
+    builder.add_without_parsing("--raw ${version_name}");
+    assert_eq!(
+        builder.args(),
+        &strings(&["--version", "1.20.1", "--raw ${version_name}"])
+    );
+    // 人读形式给含空格的参数加引号（日志与快照测试用）。
+    assert_eq!(
+        builder.display_args(),
+        "--version 1.20.1 \"--raw ${version_name}\""
+    );
+    let mut quoted = CommandBuilder::new();
+    quoted.add("-Dmsg=hello world");
+    assert_eq!(quoted.display_args(), "\"-Dmsg=hello world\"");
+}
diff --git a/crates/core/tests/launch/exit_cases.rs b/crates/core/tests/launch/exit_cases.rs
new file mode 100644
index 0000000..c861b6b
--- /dev/null
+++ b/crates/core/tests/launch/exit_cases.rs
@@ -0,0 +1,169 @@
+//! 退出分析测试：退出码语义 + `exit 0` 静默失败（`analyse/02` §6.3 §7.2 §7.10-10）。
+
+use crate::prelude::*;
+
+fn line(stream: Stream, text: &str) -> LogLine {
+    LogLine::new(stream, text)
+}
+
+fn analyze(
+    code: i32,
+    uptime_ms: u64,
+    lines: &[LogLine],
+    posix: bool,
+) -> unlucky_core::launch::exit_analysis::ExitAnalysis {
+    let mut signals = exit_analysis::ExitSignals::new(code, uptime_ms, lines);
+    signals.is_posix = posix;
+    exit_analysis::analyze(&signals)
+}
+
+#[test]
+fn clean_long_run_is_normal() {
+    let lines = vec![line(
+        Stream::Stdout,
+        "[12:00:00] [Render thread/INFO]: started",
+    )];
+    let analysis = analyze(0, 120_000, &lines, true);
+    assert_eq!(analysis.exit_type, ExitType::Normal);
+    assert!(analysis.silent_failure.is_none());
+    assert!(!analysis.needs_diagnosis);
+}
+
+#[test]
+fn exit_zero_short_lived_is_silent_failure() {
+    let lines = vec![line(Stream::Stdout, "Stopping!")];
+    let analysis = analyze(0, 8_000, &lines, true);
+    assert_eq!(analysis.exit_type, ExitType::Normal);
+    let silent = analysis.silent_failure.expect("应标记静默失败");
+    assert!(silent.short_lived);
+    assert!(!silent.error_output);
+    assert!(analysis.needs_diagnosis, "静默失败必须进诊断流水线");
+}
+
+#[test]
+fn exit_zero_with_error_output_is_silent_failure() {
+    let lines = vec![
+        line(Stream::Stdout, "[12:00:00] [main/INFO]: loading"),
+        line(
+            Stream::Stderr,
+            "java.lang.RuntimeException: mixin apply failed",
+        ),
+    ];
+    let analysis = analyze(0, 90_000, &lines, true);
+    assert_eq!(analysis.exit_type, ExitType::Normal);
+    let silent = analysis.silent_failure.expect("应标记静默失败");
+    assert!(silent.error_output);
+    assert!(!silent.short_lived);
+    assert!(silent.describe().contains("错误特征"));
+    assert_eq!(analysis.error_lines, 1);
+}
+
+#[test]
+fn jvm_keywords_take_precedence() {
+    let lines = vec![line(
+        Stream::Stderr,
+        "Error occurred during initialization of VM",
+    )];
+    let analysis = analyze(1, 500, &lines, true);
+    assert_eq!(analysis.exit_type, ExitType::JvmError);
+    assert_eq!(analysis.jvm_keywords.len(), 1);
+    assert!(analysis.needs_diagnosis);
+}
+
+#[test]
+fn nonzero_without_keywords_is_application_error() {
+    let lines = vec![line(Stream::Stdout, "[12:00:00] [main/INFO]: hi")];
+    let analysis = analyze(1, 40_000, &lines, true);
+    assert_eq!(analysis.exit_type, ExitType::ApplicationError);
+    assert!(analysis.needs_diagnosis);
+}
+
+#[test]
+fn crash_keywords_promote_exit_zero() {
+    let lines = vec![line(
+        Stream::Stdout,
+        "[12:00:00] [Render thread/ERROR]: Crash report saved to ./crash-reports/crash-1.txt",
+    )];
+    let analysis = analyze(0, 60_000, &lines, true);
+    assert_eq!(analysis.exit_type, ExitType::ApplicationError);
+    assert_eq!(analysis.crash_keywords.len(), 1);
+    assert!(
+        analysis.silent_failure.is_none(),
+        "已判异常就不再是静默失败"
+    );
+}
+
+#[test]
+fn posix_signals_are_recognized() {
+    assert_eq!(analyze(137, 60_000, &[], true).exit_type, ExitType::SigKill);
+    assert_eq!(analyze(143, 60_000, &[], true).exit_type, ExitType::SigTerm);
+    // Windows 上 137 没有信号语义，按应用错误处理。
+    assert_eq!(
+        analyze(137, 60_000, &[], false).exit_type,
+        ExitType::ApplicationError
+    );
+}
+
+#[test]
+fn windows_ntstatus_is_explained() {
+    let analysis = analyze(-1_073_741_819, 60_000, &[], false);
+    assert_eq!(analysis.exit_type, ExitType::ApplicationError);
+    assert_eq!(
+        analysis.windows_status.as_deref(),
+        Some("0xC0000005 ACCESS_VIOLATION")
+    );
+
+    let dll = analyze(-1_073_741_515, 60_000, &[], false);
+    assert_eq!(
+        dll.windows_status.as_deref(),
+        Some("0xC0000135 DLL_NOT_FOUND")
+    );
+
+    // 0xC000013A = STATUS_CONTROL_C_EXIT（控制台 Ctrl+C / 关窗口），十进制 -1073741510。
+    let control_c = analyze(-1_073_741_510, 60_000, &[], false);
+    assert_eq!(
+        control_c.windows_status.as_deref(),
+        Some("0xC000013A CONTROL_C_EXIT")
+    );
+    // 回归：-1073741743 其实是 0xC0000051，不得被当成 CONTROL_C_EXIT。
+    assert!(analyze(-1_073_741_743, 60_000, &[], false)
+        .windows_status
+        .is_none());
+}
+
+#[test]
+fn killed_and_interrupted_override_exit_code() {
+    let mut signals = exit_analysis::ExitSignals::new(1, 5_000, &[]);
+    signals.killed = true;
+    assert_eq!(exit_analysis::analyze(&signals).exit_type, ExitType::Killed);
+
+    let mut signals = exit_analysis::ExitSignals::new(1, 5_000, &[]);
+    signals.interrupted = true;
+    assert_eq!(
+        exit_analysis::analyze(&signals).exit_type,
+        ExitType::Interrupted
+    );
+}
+
+#[test]
+fn exit_type_strings_match_contract() {
+    // 与 M15 刻意保持一致的字符串集合（`launch-接口约定.md` §3）。
+    assert_eq!(ExitType::Normal.as_str(), "normal");
+    assert_eq!(ExitType::ApplicationError.as_str(), "application_error");
+    assert_eq!(ExitType::JvmError.as_str(), "jvm_error");
+    assert_eq!(ExitType::SigKill.as_str(), "sigkill");
+    assert_eq!(ExitType::SigTerm.as_str(), "sigterm");
+    assert_eq!(ExitType::Killed.as_str(), "killed");
+    assert_eq!(ExitType::Interrupted.as_str(), "interrupted");
+    assert!(!ExitType::Normal.is_abnormal());
+    assert!(ExitType::JvmError.is_abnormal());
+}
+
+#[test]
+fn summary_is_human_readable() {
+    let analysis = analyze(-1_073_741_819, 61_500, &[], false);
+    let summary = analysis.summary();
+    assert!(summary.contains("-1073741819"));
+    assert!(summary.contains("61.5s"));
+    assert!(summary.contains("ACCESS_VIOLATION"));
+}
diff --git a/crates/core/tests/launch/graphics_backend_cases.rs b/crates/core/tests/launch/graphics_backend_cases.rs
new file mode 100644
index 0000000..d8c5759
--- /dev/null
+++ b/crates/core/tests/launch/graphics_backend_cases.rs
@@ -0,0 +1,147 @@
+//! `--graphicsBackend` 的两套判据（能力位 vs 精确版本门）与周快照放行。
+//!
+//! 事实基线（`research/05-mc-vulkan.md` §3.2/§4.2，实测）：
+//! - `--graphicsBackend` 从 **26.2-snapshot-2**（2026-04-09）才有；
+//! - `org.lwjgl:lwjgl-vulkan` 从 **26.2-snapshot-1**（2026-04-07）就有 —— 差两天；
+//! - 周快照（`26w14a`）无法与 `26.2-snapshot-N` 排序，只能靠库表判。
+//!
+//! 结论：能力位**不能**替代精确版本门，两者的分工是本文件的断言对象。
+
+use unlucky_core::launch::game_args::{graphics_backend_allowed, GRAPHICS_BACKEND_MIN_VERSION};
+
+use crate::prelude::*;
+
+#[test]
+fn known_versions_use_the_exact_threshold_and_ignore_the_capability_bit() {
+    // 26.2-snapshot-1：有 Vulkan 库却没有参数，绝不能因为能力位放行
+    // （jopt-simple 未开 allowsUnrecognizedOptions，未声明选项会让游戏直接起不来）。
+    assert!(!graphics_backend_allowed(
+        &GameVersion::parse("26.2-snapshot-1"),
+        true
+    ));
+    assert!(!graphics_backend_allowed(
+        &GameVersion::parse("26.2-snapshot-1"),
+        false
+    ));
+    // 门限上的那一版起放行（能力位无关）。
+    assert!(graphics_backend_allowed(
+        &GameVersion::parse(GRAPHICS_BACKEND_MIN_VERSION),
+        false
+    ));
+    assert!(graphics_backend_allowed(&GameVersion::parse("26.2"), false));
+    assert!(graphics_backend_allowed(&GameVersion::parse("26.3"), false));
+    // 可解析的老版本：能力位再真也不放行。
+    assert!(!graphics_backend_allowed(
+        &GameVersion::parse("1.20.1"),
+        true
+    ));
+}
+
+#[test]
+fn weekly_snapshots_fall_back_to_the_capability_bit() {
+    let weekly = GameVersion::parse("26w14a");
+    assert!(!weekly.is_known(), "周快照不做数字排序（不猜）");
+    assert!(weekly.is_weekly_snapshot());
+
+    // 26.1 线（含周快照）没有 lwjgl-vulkan → 丢弃，和以前一样。
+    assert!(!graphics_backend_allowed(&weekly, false));
+    // 带 Vulkan 库的周快照（26.2 之后的周快照）→ 不再一律丢弃（这就是被修的误伤）。
+    assert!(graphics_backend_allowed(&weekly, true));
+    assert!(graphics_backend_allowed(
+        &GameVersion::parse("26w30a"),
+        true
+    ));
+}
+
+#[test]
+fn non_weekly_unknown_versions_are_still_dropped() {
+    // 第三方自定义版本串没有可依据的语义，能力位为真也不猜。
+    let custom = GameVersion::parse("custom-build");
+    assert!(!custom.is_known());
+    assert!(!custom.is_weekly_snapshot());
+    assert!(!graphics_backend_allowed(&custom, true));
+    assert!(!graphics_backend_allowed(&GameVersion::default(), true));
+}
+
+#[test]
+fn weekly_snapshot_shape_is_parsed_narrowly() {
+    for shape in ["20w14a", "26w14a", "26W14A", "12w01a"] {
+        assert!(
+            GameVersion::parse(shape).is_weekly_snapshot(),
+            "{shape} 应识别为周快照"
+        );
+    }
+    for other in ["26.2-snapshot-1", "26w14", "26ww14a", "w14a", "26w14ab", ""] {
+        assert!(
+            !GameVersion::parse(other).is_weekly_snapshot(),
+            "{other} 不该被当成周快照"
+        );
+    }
+}
+
+#[test]
+fn assemble_lets_a_vulkan_weekly_snapshot_through() {
+    let (request, ctx) = weekly_request("26w30a", true);
+    let assembled = assemble(&request, &ctx).expect("组装应成功");
+    assert!(
+        assembled
+            .args
+            .windows(2)
+            .any(|pair| pair[0] == "--graphicsBackend" && pair[1] == "vulkan"),
+        "带 Vulkan 库的周快照应下发 --graphicsBackend：{:?}",
+        assembled.args
+    );
+    assert!(!assembled
+        .warnings
+        .iter()
+        .any(|warning| matches!(warning, AssemblyWarning::GraphicsBackendSkipped { .. })));
+}
+
+#[test]
+fn assemble_still_drops_it_for_a_pre_vulkan_weekly_snapshot() {
+    let (request, ctx) = weekly_request("26w14a", false);
+    let assembled = assemble(&request, &ctx).expect("组装应成功");
+    assert!(!assembled.args.iter().any(|arg| arg == "--graphicsBackend"));
+    assert!(assembled
+        .warnings
+        .iter()
+        .any(|warning| matches!(warning, AssemblyWarning::GraphicsBackendSkipped { .. })));
+}
+
+#[test]
+fn adapter_derives_the_capability_bit_from_the_library_names() {
+    let dir = temp_dir("adapter-vulkan-capability");
+    let with_vulkan = vec![
+        LibraryInput::new(dir.join("libraries/lwjgl.jar"), "org.lwjgl:lwjgl:3.4.3"),
+        LibraryInput::new(
+            dir.join("libraries/lwjgl-vulkan.jar"),
+            "org.lwjgl:lwjgl-vulkan:3.4.3",
+        ),
+    ];
+    let without_vulkan = vec![LibraryInput::new(
+        dir.join("libraries/lwjgl.jar"),
+        "org.lwjgl:lwjgl:3.4.3",
+    )];
+
+    for (libraries, expected) in [(&with_vulkan, true), (&without_vulkan, false)] {
+        let snapshot = SnapshotInput {
+            main_class: Some("net.minecraft.client.main.Main"),
+            libraries,
+            ..SnapshotInput::minimal("26.3", "")
+        };
+        let output = build_request(&snapshot, AdapterOptions::strict());
+        assert_eq!(
+            output.request.manifest.has_vulkan_backend, expected,
+            "库表 {libraries:?} 的能力位判定不对"
+        );
+    }
+}
+
+/// 一个只关心 `--graphicsBackend` 的请求（周快照版本 + 指定能力位）。
+fn weekly_request(version: &str, has_vulkan_backend: bool) -> (LaunchRequest, PlatformCtx) {
+    let (mut request, ctx) = legacy_forge_request();
+    request.instance.version = GameVersion::parse(version);
+    request.manifest.has_vulkan_backend = has_vulkan_backend;
+    request.graphics_backend = Some("vulkan".to_string());
+    (request, ctx)
+}
diff --git a/crates/core/tests/launch/main.rs b/crates/core/tests/launch/main.rs
new file mode 100644
index 0000000..f6d53ac
--- /dev/null
+++ b/crates/core/tests/launch/main.rs
@@ -0,0 +1,16 @@
+//! launch 模块集成测试入口（`cargo test --test launch`）。
+
+mod adapter_cases;
+mod cmdline_snapshot;
+mod command_builder_cases;
+mod exit_cases;
+mod graphics_backend_cases;
+mod natives_args_cases;
+mod natives_cases;
+mod pipeline_cases;
+mod prelude;
+mod process_smoke;
+mod pump_buffer;
+mod session_events;
+mod sink_cases;
+mod tree_kill_cases;
diff --git a/crates/core/tests/launch/natives_args_cases.rs b/crates/core/tests/launch/natives_args_cases.rs
new file mode 100644
index 0000000..027345a
--- /dev/null
+++ b/crates/core/tests/launch/natives_args_cases.rs
@@ -0,0 +1,136 @@
+//! natives 时代分界与参数接线：清单口径收集、`-Djava.library.path` 归属、1.19+ 四个目录属性。
+//!
+//! 抽取行为本身在 `natives_cases.rs`；这里只验「参数从哪来、收集口径对不对」。
+
+use unlucky_core::launch::natives;
+
+use crate::prelude::*;
+
+/// 参数接线：legacy 清单没有 `arguments.jvm`，`-Djava.library.path` 由启动器补且只补一次。
+#[test]
+fn legacy_manifest_gets_single_java_library_path() {
+    let (request, ctx) = legacy_forge_request();
+    let command = assemble(&request, &ctx).expect("组装应成功");
+    let natives = request.dirs.natives_dir.display().to_string();
+    let library_path: Vec<&String> = command
+        .args
+        .iter()
+        .filter(|arg| arg.starts_with("-Djava.library.path="))
+        .collect();
+    assert_eq!(library_path.len(), 1, "legacy 只该有一条：{library_path:?}");
+    assert_eq!(library_path[0], &format!("-Djava.library.path={natives}"));
+}
+
+/// 参数接线：1.13+ 清单自带 `-Djava.library.path=${natives_directory}`，启动器不得重复注入。
+#[test]
+fn modern_manifest_keeps_its_own_library_path_once() {
+    let (mut request, ctx) = legacy_forge_request();
+    let natives = request.dirs.natives_dir.display().to_string();
+    request.manifest.jvm = vec![
+        ArgumentEntry::plain(["-Djava.library.path=${natives_directory}".to_string()]),
+        ArgumentEntry::plain(["-cp".to_string(), "${classpath}".to_string()]),
+    ];
+    request.manifest.legacy_arguments = None;
+    let command = assemble(&request, &ctx).expect("组装应成功");
+    let library_path: Vec<&String> = command
+        .args
+        .iter()
+        .filter(|arg| arg.starts_with("-Djava.library.path="))
+        .collect();
+    assert_eq!(library_path.len(), 1, "清单 + 默认值不该叠加");
+    assert_eq!(library_path[0], &format!("-Djava.library.path={natives}"));
+}
+
+/// 参数接线：1.19+ 的四个目录属性都要渲染到同一目录（LWJGL 3.3 运行期往那里解压）。
+#[test]
+fn classpath_native_era_renders_all_four_directory_properties() {
+    let (mut request, ctx) = legacy_forge_request();
+    let natives = request.dirs.natives_dir.display().to_string();
+    request.manifest.jvm = vec![ArgumentEntry::plain([
+        "-Djava.library.path=${natives_directory}".to_string(),
+        "-Djna.tmpdir=${natives_directory}".to_string(),
+        "-Dorg.lwjgl.system.SharedLibraryExtractPath=${natives_directory}".to_string(),
+        "-Dio.netty.native.workdir=${natives_directory}".to_string(),
+    ])];
+    request.manifest.legacy_arguments = None;
+    let command = assemble(&request, &ctx).expect("组装应成功");
+    for key in [
+        "-Djava.library.path=",
+        "-Djna.tmpdir=",
+        "-Dorg.lwjgl.system.SharedLibraryExtractPath=",
+        "-Dio.netty.native.workdir=",
+    ] {
+        assert!(
+            command
+                .args
+                .iter()
+                .any(|arg| arg == &format!("{key}{natives}")),
+            "缺少 {key}{natives}：{:?}",
+            command.args
+        );
+    }
+}
+
+/// 收集口径：`natives` 表按 OS 命中 → 分类器 jar；1.19+ 无表 → 空；
+/// `hint=local` 走实例私有目录（HMCL `analyse/03` §6.8 口径）。
+///
+/// 注意：安装层当前的 natives 分类器分支**不认** `hint=local`（走共享 `libraries/`），
+/// 所以这一条断言测的是 `collect` 的正确行为，不是「与安装层一致」——见
+/// `collect` 文档里的已知缺口说明。
+#[test]
+fn collect_picks_classifier_jars_per_environment() {
+    use unlucky_core::game::{Environment, GameLayout, Library};
+
+    let libraries: Vec<Library> = serde_json::from_str(
+        r#"[
+            {"name":"org.lwjgl:lwjgl:3.2.2",
+             "natives":{"linux":"natives-linux","windows":"natives-windows"},
+             "extract":{"exclude":["META-INF/"]},
+             "downloads":{"artifact":{"path":"org/lwjgl/lwjgl/3.2.2/lwjgl-3.2.2.jar","url":"https://libraries.minecraft.net/a.jar"},
+                          "classifiers":{"natives-windows":{"path":"org/lwjgl/lwjgl/3.2.2/lwjgl-3.2.2-natives-windows.jar","url":"https://libraries.minecraft.net/b.jar"}}}},
+            {"name":"org.lwjgl:lwjgl-tinyfd:3.2.2","natives":{"windows":"natives-windows"},
+             "hint":"local",
+             "downloads":{"classifiers":{"natives-windows":{"path":"org/lwjgl/lwjgl-tinyfd/3.2.2/lwjgl-tinyfd-3.2.2-natives-windows.jar","url":"https://libraries.minecraft.net/c.jar"}}}},
+            {"name":"org.lwjgl:lwjgl:3.3.3:natives-linux",
+             "rules":[{"action":"allow","os":{"name":"linux"}}],
+             "downloads":{"artifact":{"path":"org/lwjgl/lwjgl/3.3.3/lwjgl-3.3.3-natives-linux.jar","url":"https://libraries.minecraft.net/d.jar"}}}
+        ]"#,
+    )
+    .expect("库 JSON 应可解析");
+    let layout = GameLayout::new("C:/mc");
+    let environment = Environment {
+        os: "windows".to_string(),
+        os_version: "10.0.19045".to_string(),
+        arch: "x86_64".to_string(),
+        ..Environment::default()
+    };
+
+    let natives = natives::collect(&layout, "1.16.5", &libraries, &environment);
+    assert_eq!(natives.len(), 2, "只该收 windows 分类器：{natives:?}");
+    assert!(
+        natives[0]
+            .path
+            .ends_with("libraries/org/lwjgl/lwjgl/3.2.2/lwjgl-3.2.2-natives-windows.jar"),
+        "{:?}",
+        natives[0].path
+    );
+    assert_eq!(natives[0].name, "org.lwjgl:lwjgl:3.2.2:natives-windows");
+    assert_eq!(natives[0].exclude, vec!["META-INF/".to_string()]);
+    // `hint=local`：按 HMCL 口径落实例私有目录（安装层尚未跟进，见函数文档）。
+    assert!(
+        natives[1]
+            .path
+            .ends_with("versions/1.16.5/libraries/org/lwjgl/lwjgl-tinyfd/3.2.2/lwjgl-tinyfd-3.2.2-natives-windows.jar"),
+        "{:?}",
+        natives[1].path
+    );
+
+    // 1.19+ 形态（无 natives 表）→ 空表（natives jar 在 classpath 上）。
+    let modern: Vec<Library> = serde_json::from_str(
+        r#"[{"name":"org.lwjgl:lwjgl:3.3.3:natives-windows",
+             "rules":[{"action":"allow","os":{"name":"windows"}}],
+             "downloads":{"artifact":{"path":"org/lwjgl/lwjgl/3.3.3/lwjgl-3.3.3-natives-windows.jar","url":"https://libraries.minecraft.net/e.jar"}}}]"#,
+    )
+    .expect("库 JSON 应可解析");
+    assert!(natives::collect(&layout, "1.20.1", &modern, &environment).is_empty());
+}
diff --git a/crates/core/tests/launch/natives_cases.rs b/crates/core/tests/launch/natives_cases.rs
new file mode 100644
index 0000000..d289cc2
--- /dev/null
+++ b/crates/core/tests/launch/natives_cases.rs
@@ -0,0 +1,281 @@
+//! natives 解压（`launch::natives`）的用例：解析正确性 / 排除项 / 幂等 / 时代参数 / 事件流。
+//!
+//! 假 jar 用 `zip` 的 Stored 模式现造（不依赖真下载），真机验收另有人工步骤。
+
+use std::fs::File;
+use std::io::Write;
+use std::path::{Path, PathBuf};
+
+use zip::write::SimpleFileOptions;
+use zip::{CompressionMethod, ZipWriter};
+
+use unlucky_core::launch::natives::{self, NativeJar, NativesEra, NativesPlan, STAMP_FILE};
+
+use crate::prelude::*;
+
+/// 造一个 natives jar：`entries` 是（条目名, 内容）。
+fn make_jar(path: &Path, entries: &[(&str, &[u8])]) {
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent).expect("建 jar 目录");
+    }
+    let file = File::create(path).expect("建 jar");
+    let mut writer = ZipWriter::new(file);
+    let options = SimpleFileOptions::default().compression_method(CompressionMethod::Stored);
+    for (name, bytes) in entries {
+        writer.start_file(*name, options).expect("写条目");
+        writer.write_all(bytes).expect("写条目内容");
+    }
+    writer.finish().expect("收尾 jar");
+}
+
+/// 一份 1.16.5 风格的 natives jar 的条目集（原生库 + 该被排除的噪音）。
+fn lwjgl_jar_entries() -> Vec<(&'static str, &'static [u8])> {
+    vec![
+        ("lwjgl.dll", b"DLL-BYTES".as_slice()),
+        ("OpenAL.dll", b"OPENAL-BYTES".as_slice()),
+        ("META-INF/MANIFEST.MF", b"manifest".as_slice()),
+        ("META-INF/LWJGL.SF", b"signature".as_slice()),
+        ("lwjgl.dll.sha1", b"deadbeef".as_slice()),
+        ("README.txt", b"noise".as_slice()),
+    ]
+}
+
+fn plan(jars: Vec<NativeJar>) -> NativesPlan {
+    NativesPlan::new(jars)
+}
+
+#[test]
+fn extracts_native_libraries_and_drops_noise() {
+    let root = temp_dir("natives-extract");
+    let jar = root.join("libraries/lwjgl-natives-windows.jar");
+    make_jar(&jar, &lwjgl_jar_entries());
+    let target = root.join("versions/1.16.5/natives");
+
+    let report =
+        natives::extract(&target, &plan(vec![NativeJar::new(&jar, "lwjgl")])).expect("解压应成功");
+
+    assert_eq!(report.files, 2, "只该解出两个原生库：{report:?}");
+    assert!(!report.up_to_date);
+    assert_eq!(report.jars, 1);
+    // META-INF/ 两条 + .sha1 + README.txt。
+    assert_eq!(report.ignored, 4, "噪音条目数：{report:?}");
+    assert_eq!(
+        std::fs::read(target.join("lwjgl.dll")).expect("读 dll"),
+        b"DLL-BYTES"
+    );
+    assert!(target.join("OpenAL.dll").is_file());
+    assert!(!target.join("META-INF").exists(), "META-INF/ 不该落地");
+    assert!(!target.join("lwjgl.dll.sha1").exists(), "签名文件不该落地");
+    assert!(!target.join("README.txt").exists(), "非原生库不该落地");
+    assert!(target.join(STAMP_FILE).is_file(), "应写戳记");
+}
+
+#[test]
+fn second_run_is_idempotent_and_source_change_reextracts() {
+    let root = temp_dir("natives-idempotent");
+    let jar = root.join("natives-windows.jar");
+    make_jar(&jar, &[("lwjgl.dll", b"V1".as_slice())]);
+    let target = root.join("natives");
+    let extract_plan = plan(vec![NativeJar::new(&jar, "lwjgl")]);
+
+    let first = natives::extract(&target, &extract_plan).expect("首次解压");
+    assert_eq!(first.files, 1);
+    assert!(!first.up_to_date);
+
+    // 第二次：戳记命中，零写盘（文件 mtime 不变）。
+    let before = std::fs::metadata(target.join("lwjgl.dll"))
+        .expect("stat")
+        .modified()
+        .expect("mtime");
+    let second = natives::extract(&target, &extract_plan).expect("二次解压");
+    assert!(second.up_to_date, "应判定目录已就绪：{second:?}");
+    assert_eq!(second.files, 0);
+    assert_eq!(second.skipped, 1);
+    let after = std::fs::metadata(target.join("lwjgl.dll"))
+        .expect("stat")
+        .modified()
+        .expect("mtime");
+    assert_eq!(before, after, "幂等路径不该重写文件");
+
+    // 源 jar 变了（内容 + 长度都变）：必须重解，且旧的原生库被清掉。
+    make_jar(&jar, &[("lwjgl.dll", b"V2-LONGER".as_slice())]);
+    let third = natives::extract(&target, &extract_plan).expect("三次解压");
+    assert!(!third.up_to_date, "源变了必须重解：{third:?}");
+    assert_eq!(
+        std::fs::read(target.join("lwjgl.dll")).expect("读 dll"),
+        b"V2-LONGER"
+    );
+}
+
+#[test]
+fn stale_native_libraries_are_cleaned_before_reextract() {
+    let root = temp_dir("natives-clean");
+    let jar = root.join("natives-windows.jar");
+    make_jar(&jar, &[("lwjgl.dll", b"NEW".as_slice())]);
+    let target = root.join("natives");
+    std::fs::create_dir_all(&target).expect("建目录");
+    // 上一代遗留（旧版本 / 旧 loader 解出来的），必须清掉，否则两代 dll 混在 java.library.path 里。
+    std::fs::write(target.join("old-lwjgl.dll"), b"stale").expect("写旧 dll");
+    std::fs::write(target.join("keep-me.txt"), b"user file").expect("写用户文件");
+
+    natives::extract(&target, &plan(vec![NativeJar::new(&jar, "lwjgl")])).expect("解压");
+
+    assert!(!target.join("old-lwjgl.dll").exists(), "旧原生库应被清理");
+    assert!(target.join("keep-me.txt").is_file(), "非原生库文件不该被删");
+    assert!(target.join("lwjgl.dll").is_file());
+}
+
+#[test]
+fn empty_plan_still_creates_directory_for_1_19() {
+    // 1.19+ 没有 natives 分类器：目录仍要存在（SharedLibraryExtractPath 指向它）。
+    let root = temp_dir("natives-empty");
+    let target = root.join("versions/1.21.4/natives");
+    let report = natives::extract(&target, &NativesPlan::default()).expect("建目录");
+    assert!(target.is_dir());
+    assert!(report.up_to_date);
+    assert_eq!(report.files, 0);
+    assert_eq!(report.jars, 0);
+    assert_eq!(
+        report.era,
+        NativesEra::ClasspathNative,
+        "默认时代（无 jar）"
+    );
+}
+
+#[test]
+fn missing_directory_is_an_error_not_a_silent_pass() {
+    let plan = NativesPlan::new(vec![NativeJar::new("x.jar", "x")]);
+    let err = natives::extract(Path::new(""), &plan).expect_err("空目录必须报错");
+    assert!(err.message().contains("natives 目录"), "{err}");
+}
+
+#[test]
+fn broken_jar_reports_zip_error() {
+    let root = temp_dir("natives-broken");
+    let jar = root.join("natives-broken.jar");
+    std::fs::write(&jar, b"not a zip at all").expect("写坏 jar");
+    let target = root.join("natives");
+    let err = natives::extract(&target, &plan(vec![NativeJar::new(&jar, "broken")]))
+        .expect_err("坏 jar 必须报错");
+    assert!(err.message().contains("zip"), "错误应点明 zip：{err}");
+}
+
+#[test]
+fn era_detect_covers_three_generations() {
+    assert_eq!(NativesEra::detect(0, 3), NativesEra::Legacy);
+    assert_eq!(NativesEra::detect(9, 3), NativesEra::Lwjgl3);
+    assert_eq!(NativesEra::detect(9, 0), NativesEra::ClasspathNative);
+    assert_eq!(NativesEra::Legacy.as_str(), "legacy");
+    assert_eq!(NativesEra::Lwjgl3.as_str(), "lwjgl3");
+    assert_eq!(NativesEra::ClasspathNative.as_str(), "classpath_native");
+}
+
+/// 事件流：`natives_extracted` 落盘字段与接口约定一致（dir/files/skipped/custom）。
+#[test]
+fn natives_extracted_event_carries_report_fields() {
+    let root = temp_dir("natives-event");
+    let jar = root.join("natives-windows.jar");
+    make_jar(&jar, &[("lwjgl.dll", b"DLL".as_slice())]);
+    let target = root.join("natives");
+    let report =
+        natives::extract(&target, &plan(vec![NativeJar::new(&jar, "lwjgl")])).expect("解压");
+
+    let sessions = temp_sessions_root("natives-event-sessions");
+    let mut writer = SessionWriter::create(
+        &sessions,
+        SessionMeta::new("inst", "1.16.5", "1.16.5"),
+        Redactor::new(),
+    )
+    .expect("建会话");
+    writer.natives_extracted(&report).expect("写事件");
+    let path = writer.path().to_path_buf();
+    writer.finish(EndReason::Exit).expect("收尾");
+
+    let events = read_events(&path);
+    let event = events
+        .iter()
+        .find(|event| event["kind"] == "natives_extracted")
+        .expect("应有 natives_extracted 事件");
+    let payload = &event["payload"];
+    assert_eq!(payload["files"], 1);
+    assert_eq!(payload["skipped"], 0);
+    assert_eq!(payload["custom"], false);
+    assert_eq!(payload["jars"], 1);
+    assert_eq!(payload["up_to_date"], false);
+    assert_eq!(payload["era"], "lwjgl3");
+    assert!(payload["dir"]
+        .as_str()
+        .expect("dir 是字符串")
+        .ends_with("natives"));
+}
+
+/// `--dry-run` 也做环境准备：第二次跑要看到 up_to_date（真机验收的判定依据）。
+#[test]
+fn dry_run_prepares_natives_and_is_idempotent() {
+    let root = temp_dir("natives-dry-run");
+    let jar = root.join("natives-windows.jar");
+    make_jar(&jar, &[("lwjgl.dll", b"DLL".as_slice())]);
+    let natives_dir: PathBuf = root.join("versions/1.16.5/natives");
+
+    let (mut request, _) = legacy_forge_request();
+    request.dirs.natives_dir = natives_dir.clone();
+    request.natives = NativesPlan::new(vec![NativeJar::new(&jar, "lwjgl")]);
+    request.manifest.legacy_arguments = Some("--username ${auth_player_name}".to_string());
+
+    let sessions = temp_sessions_root("natives-dry-run-sessions");
+    let launcher = Launcher::new(LauncherConfig::new(&sessions));
+
+    let first = launcher.dry_run(&request).expect("首次 dry-run");
+    let report = first.natives.expect("应有 natives 报告");
+    assert_eq!(report.files, 1, "{report:?}");
+    assert!(!report.up_to_date);
+    assert!(natives_dir.join("lwjgl.dll").is_file());
+
+    let second = launcher.dry_run(&request).expect("二次 dry-run");
+    let report = second.natives.expect("应有 natives 报告");
+    assert!(report.up_to_date, "第二次应命中戳记：{report:?}");
+    assert_eq!(report.skipped, 1);
+}
+
+/// 缺 natives jar：适配层当成组件缺失（组装前显式失败），而不是等到 UnsatisfiedLinkError。
+#[test]
+fn missing_native_jar_becomes_missing_component() {
+    let (mut request, ctx) = legacy_forge_request();
+    request.natives = NativesPlan::new(vec![NativeJar::new(
+        "C:/mc/libraries/missing-natives-windows.jar",
+        "org.lwjgl:lwjgl:3.2.2:natives-windows",
+    )]);
+    // 直接验证适配层：给一个不存在的 natives jar，严格模式应产出 MissingNativeJar 告警。
+    let libraries: Vec<LibraryInput> = request
+        .classpath
+        .iter()
+        .map(|path| LibraryInput::new(path.clone(), "x"))
+        .collect();
+    let natives = request.natives.jars.clone();
+    let snapshot = SnapshotInput {
+        version_id: "1.16.5",
+        main_class: Some("net.minecraft.client.main.Main"),
+        libraries: &libraries,
+        natives: &natives,
+        ..SnapshotInput::minimal("1.16.5", "net.minecraft.client.main.Main")
+    };
+    let options = AdapterOptions {
+        java: JavaSelection::new("C:/java/bin/java.exe", 17, 64),
+        ..AdapterOptions::strict()
+    };
+    let output = build_request(&snapshot, options);
+    assert!(
+        output
+            .warnings
+            .iter()
+            .any(|warning| matches!(warning, AdapterWarning::MissingNativeJar { .. })),
+        "应有 MissingNativeJar 告警：{:?}",
+        output.warnings
+    );
+    assert_eq!(output.request.natives.era, NativesEra::Legacy);
+    // 组装按既有语义直接失败（missing_components 非空）。
+    assert!(matches!(
+        assemble(&output.request, &ctx).err(),
+        Some(LaunchError::Assembly(AssemblyError::MissingComponents(_)))
+    ));
+}
diff --git a/crates/core/tests/launch/pipeline_cases.rs b/crates/core/tests/launch/pipeline_cases.rs
new file mode 100644
index 0000000..b14020f
--- /dev/null
+++ b/crates/core/tests/launch/pipeline_cases.rs
@@ -0,0 +1,347 @@
+//! 顶层启动管线测试：dry-run（D18）、完整会话、停止、组装失败、崩溃现场。
+//!
+//! 真进程来自 shell（`cmd /C` 或 `sh -c`），所以这些是端到端用例：
+//! 命令行组装 → 事件流落盘 → 退出判定 → 诊断挂钩 → 索引。
+
+use std::path::PathBuf;
+use std::sync::{Arc, Mutex};
+use std::time::Duration;
+
+use serde_json::json;
+
+use crate::prelude::*;
+
+/// 记录调用并返回固定结论的诊断挂钩。
+#[derive(Default)]
+struct RecordingHook {
+    calls: Mutex<Vec<String>>,
+}
+
+impl DiagnosisHook for RecordingHook {
+    fn analyze(&self, request: &DiagnosisRequest) -> Option<serde_json::Value> {
+        self.calls.lock().unwrap().push(request.summary());
+        Some(json!({
+            "source": "rules",
+            "needs_more_info": false,
+            "candidates": [{ "id": "stub_candidate", "severity": "high", "confidence": 0.9 }],
+        }))
+    }
+}
+
+fn launcher(sessions_root: &std::path::Path, hook: Option<Arc<RecordingHook>>) -> Launcher {
+    let mut config = LauncherConfig::new(sessions_root);
+    // 固定平台上下文，让命令行断言与运行平台无关。
+    config.platform = PlatformCtx::new(OsFamily::Windows, "x86_64");
+    config.process = ProcessConfig {
+        graceful_stop: Duration::from_millis(200),
+        ..ProcessConfig::default()
+    };
+    let launcher = Launcher::new(config);
+    match hook {
+        Some(hook) => launcher.with_diagnosis_hook(hook),
+        None => launcher,
+    }
+}
+
+/// 用 shell 冒充 java：只为验证管线，不验证 JVM 语义。
+fn shell_request(script: &str, run_dir: &std::path::Path) -> (LaunchRequest, LaunchRequest) {
+    let (mut request, ctx) = legacy_forge_request();
+    let _ = ctx;
+    #[cfg(windows)]
+    {
+        request.wrapper = vec!["cmd".to_string(), "/C".to_string(), script.to_string()];
+    }
+    #[cfg(not(windows))]
+    {
+        request.wrapper = vec!["/bin/sh".to_string(), "-c".to_string(), script.to_string()];
+    }
+    request.java = JavaSelection::new("fake-java", 17, 64);
+    request.manifest.legacy_arguments = None;
+    request.dirs.game_dir = run_dir.to_path_buf();
+    // natives 解压是管线第 6 段，会真写盘——指到临时目录，绝不碰 `C:/mc`。
+    request.dirs.natives_dir = run_dir.join("natives");
+    request.user.jvm = Vec::new();
+    request.user.game = Vec::new();
+    (request.clone(), request)
+}
+
+fn echo_script() -> String {
+    // 命令里带上 access_token 明文，用来验证“落盘前脱敏”。
+    #[cfg(windows)]
+    {
+        "echo LWJGL Version: 3.3.1 SECRET-TOKEN-123456".to_string()
+    }
+    #[cfg(not(windows))]
+    {
+        "echo 'LWJGL Version: 3.3.1 SECRET-TOKEN-123456'".to_string()
+    }
+}
+
+fn long_running_script() -> String {
+    #[cfg(windows)]
+    {
+        "ping -n 30 127.0.0.1 >nul".to_string()
+    }
+    #[cfg(not(windows))]
+    {
+        "sleep 30".to_string()
+    }
+}
+
+#[test]
+fn dry_run_returns_command_without_spawning_or_writing() {
+    let sessions = temp_sessions_root("dry");
+    let run_dir = temp_dir("dry-run");
+    let launcher = launcher(&sessions, None);
+    let (request, _) = shell_request(&echo_script(), &run_dir);
+
+    let dry: DryRun = launcher.dry_run(&request).expect("dry-run 应成功");
+    assert!(!dry.argv.is_empty());
+    assert!(
+        dry.display.contains("fake-java")
+            || dry.display.contains("cmd")
+            || dry.display.contains("/bin/sh")
+    );
+    assert!(
+        dry.display.contains("<redacted:token>"),
+        "命令行必须脱敏：{}",
+        dry.display
+    );
+    assert!(!dry.display.contains("SECRET-TOKEN-123456"));
+    assert_eq!(dry.classpath_entries, 3);
+    assert_eq!(dry.line(), dry.display.as_str());
+    // 不 spawn、不写会话文件。
+    assert!(!sessions.exists(), "dry-run 不能创建会话目录");
+}
+
+#[test]
+fn pipeline_records_session_events_diagnosis_and_index() {
+    let sessions = temp_sessions_root("pipeline");
+    let run_dir = temp_dir("pipeline-run");
+    let hook = Arc::new(RecordingHook::default());
+    let launcher = launcher(&sessions, Some(hook.clone()));
+    let (request, _) = shell_request(&echo_script(), &run_dir);
+
+    let handle: SessionHandle = launcher.launch(&request).expect("启动应成功");
+    assert_eq!(handle.exit.exit_type, ExitType::Normal);
+    assert_eq!(handle.exit.code, 0);
+    // 存活 <30s → 静默失败 + 需要诊断。
+    assert!(handle.exit.silent_failure.is_some());
+    assert!(handle.needs_diagnosis());
+    assert_eq!(hook.calls.lock().unwrap().len(), 1, "诊断挂钩应被调用一次");
+    assert_eq!(
+        handle
+            .diagnostics
+            .as_ref()
+            .and_then(|value| value["candidates"][0]["id"].as_str()),
+        Some("stub_candidate")
+    );
+    assert!(
+        handle.event_write_errors.is_empty(),
+        "{:?}",
+        handle.event_write_errors
+    );
+    // 对外展示的 argv 已是脱敏版本（脚本里带着 token 明文）。
+    assert!(handle
+        .redacted_argv()
+        .iter()
+        .any(|arg| arg.contains("<redacted:token>")));
+    assert!(!handle
+        .redacted_argv()
+        .iter()
+        .any(|arg| arg.contains("SECRET-TOKEN-123456")));
+    assert!(handle.redacted_display().contains("<redacted:token>"));
+    assert!(handle.index.is_some());
+    assert!(handle.uptime_ms < 30_000);
+
+    let events = read_events(&handle.log_path);
+    let kinds: Vec<&str> = events
+        .iter()
+        .filter_map(|event| event["kind"].as_str())
+        .collect();
+    for expected in [
+        "session_start",
+        "cmd_built",
+        "proc_start",
+        "stdout",
+        "window_detected",
+        "exit",
+        "diagnosis",
+        "session_end",
+    ] {
+        assert!(kinds.contains(&expected), "缺少事件 {expected}：{kinds:?}");
+    }
+
+    // 日志行里的 access_token 必须已脱敏。
+    let raw = std::fs::read_to_string(&handle.log_path).expect("读会话文件");
+    assert!(!raw.contains("SECRET-TOKEN-123456"), "事件流不得含凭据明文");
+
+    // 索引落盘且字段正确。
+    let index = session_index::read_all(&session_index::index_path(&sessions)).expect("读索引");
+    assert_eq!(index.len(), 1);
+    assert_eq!(index[0].session_id, handle.session_id);
+    assert!(index[0].silent_failure);
+    assert!(index[0].window_detected);
+    assert_eq!(index[0].exit_code, Some(0));
+    assert_eq!(index[0].diagnosis_top.as_deref(), Some("stub_candidate"));
+}
+
+#[test]
+fn pipeline_stop_records_killed_exit() {
+    let sessions = temp_sessions_root("killed");
+    let run_dir = temp_dir("killed-run");
+    let launcher = launcher(&sessions, None);
+    let (request, _) = shell_request(&long_running_script(), &run_dir);
+
+    let mut session = launcher.spawn(&request).expect("spawn 应成功");
+    assert!(session.pid() > 0);
+    session.stop().expect("停止应成功");
+    let handle = session.finish().expect("收尾应成功");
+
+    assert_eq!(handle.exit.exit_type, ExitType::Killed);
+    assert!(!handle.succeeded());
+    let events = read_events(&handle.log_path);
+    let kinds: Vec<&str> = events
+        .iter()
+        .filter_map(|event| event["kind"].as_str())
+        .collect();
+    assert!(kinds.contains(&"killed"), "应记录 killed 事件：{kinds:?}");
+    let index = session_index::read_all(&session_index::index_path(&sessions)).expect("读索引");
+    assert_eq!(index.len(), 1);
+    assert_eq!(index[0].exit_type.as_deref(), Some("killed"));
+}
+
+#[test]
+fn pipeline_assembly_failure_still_writes_evidence() {
+    let sessions = temp_sessions_root("assembly-fail");
+    let run_dir = temp_dir("assembly-fail-run");
+    let launcher = launcher(&sessions, None);
+    let (mut request, _) = shell_request(&echo_script(), &run_dir);
+    request.missing_components = vec![MissingComponent::named("org.lwjgl:lwjgl:3.3.1")];
+
+    let error = launcher.spawn(&request).expect_err("缺组件必须启动前失败");
+    assert!(matches!(
+        error,
+        LaunchError::Assembly(AssemblyError::MissingComponents(_))
+    ));
+
+    let game_dir = sessions.join("game");
+    let files: Vec<PathBuf> = std::fs::read_dir(&game_dir)
+        .expect("会话目录应存在")
+        .flatten()
+        .map(|entry| entry.path())
+        .filter(|path| path.extension().map(|ext| ext == "jsonl").unwrap_or(false))
+        .filter(|path| {
+            path.file_stem()
+                .map(|stem| stem != "index")
+                .unwrap_or(false)
+        })
+        .collect();
+    assert_eq!(files.len(), 1, "应留下一个会话文件");
+    let events = read_events(&files[0]);
+    let kinds: Vec<&str> = events
+        .iter()
+        .filter_map(|event| event["kind"].as_str())
+        .collect();
+    assert_eq!(
+        kinds,
+        vec![
+            "session_start",
+            "natives_extracted",
+            "assembly_failed",
+            "session_end"
+        ]
+    );
+    let missing = &events[2]["payload"]["missing_components"][0]["name"];
+    assert_eq!(missing.as_str(), Some("org.lwjgl:lwjgl:3.3.1"));
+
+    let index = session_index::read_all(&session_index::index_path(&sessions)).expect("读索引");
+    assert_eq!(index.len(), 1);
+    assert!(index[0].exit_type.is_none(), "没有进程就没有退出判定");
+}
+
+#[test]
+fn pipeline_records_crash_report_artifact() {
+    let sessions = temp_sessions_root("crash");
+    let run_dir = temp_dir("crash-run");
+    let crash_dir = run_dir.join("crash-reports");
+    std::fs::create_dir_all(&crash_dir).expect("建 crash-reports");
+    std::fs::write(
+        crash_dir.join("crash-2026-10-29.txt"),
+        "---- Minecraft Crash Report ----\nDescription: Rendering screen\n",
+    )
+    .expect("写崩溃报告");
+
+    let launcher = launcher(&sessions, None);
+    let (request, _) = shell_request(&echo_script(), &run_dir);
+    let handle = launcher.launch(&request).expect("启动应成功");
+
+    assert!(
+        handle
+            .artifacts
+            .iter()
+            .any(|artifact| artifact.source == CrashSource::CrashReport),
+        "应发现崩溃报告：{:?}",
+        handle.artifacts
+    );
+    let events = read_events(&handle.log_path);
+    let crash = events
+        .iter()
+        .find(|event| event["kind"] == "crash_found")
+        .expect("应有 crash_found 事件");
+    let path = crash["payload"]["path"].as_str().unwrap_or_default();
+    assert!(path.ends_with("crash-2026-10-29.txt"));
+    assert!(crash["payload"]["excerpt"]
+        .as_str()
+        .unwrap_or_default()
+        .contains("Minecraft Crash Report"));
+}
+
+#[test]
+fn pipeline_spawn_failure_writes_session_end() {
+    let sessions = temp_sessions_root("spawn-fail");
+    let run_dir = temp_dir("spawn-fail-run");
+    let launcher = launcher(&sessions, None);
+    let (mut request, _) = shell_request(&echo_script(), &run_dir);
+    // 包装器就是 program：给一个不存在的可执行文件，走派生失败分支。
+    request.wrapper = vec!["definitely-not-a-real-binary-ull".to_string()];
+
+    let error = launcher.spawn(&request).expect_err("程序不存在必须失败");
+    assert!(
+        matches!(error, LaunchError::Spawn { .. }),
+        "错误类型：{error:?}"
+    );
+
+    let game_dir = sessions.join("game");
+    let files: Vec<PathBuf> = std::fs::read_dir(&game_dir)
+        .expect("会话目录应存在")
+        .flatten()
+        .map(|entry| entry.path())
+        .filter(|path| path.extension().map(|ext| ext == "jsonl").unwrap_or(false))
+        .filter(|path| {
+            path.file_stem()
+                .map(|stem| stem != "index")
+                .unwrap_or(false)
+        })
+        .collect();
+    assert_eq!(files.len(), 1, "应留下一个会话文件");
+    let events = read_events(&files[0]);
+    let kinds: Vec<&str> = events
+        .iter()
+        .filter_map(|event| event["kind"].as_str())
+        .collect();
+    assert_eq!(
+        kinds,
+        vec![
+            "session_start",
+            "natives_extracted",
+            "cmd_built",
+            "session_end"
+        ]
+    );
+    assert_eq!(events[3]["payload"]["reason"], "spawn_failed");
+
+    let index = session_index::read_all(&session_index::index_path(&sessions)).expect("读索引");
+    assert_eq!(index.len(), 1, "派生失败也要进索引");
+    assert!(index[0].exit_type.is_none());
+}
diff --git a/crates/core/tests/launch/prelude.rs b/crates/core/tests/launch/prelude.rs
new file mode 100644
index 0000000..a24d2b5
--- /dev/null
+++ b/crates/core/tests/launch/prelude.rs
@@ -0,0 +1,149 @@
+//! 测试共用设施。
+//!
+//! **crate 名只在本文件出现**（tower 定案 `unlucky_core`；若 M11 改包名，只改这里）。
+
+use std::path::PathBuf;
+
+pub use unlucky_core::launch::args_table::{assemble, AssembledCommand, AssemblyWarning};
+pub use unlucky_core::launch::argument::{ArgumentEntry, Rule};
+pub use unlucky_core::launch::command_builder::{self, CommandBuilder};
+pub use unlucky_core::launch::error::{AssemblyError, LaunchError, MissingComponent};
+pub use unlucky_core::launch::exit_analysis::{self, ExitType};
+pub use unlucky_core::launch::game_version::GameVersion;
+pub use unlucky_core::launch::log_level::{self, Level};
+pub use unlucky_core::launch::platform::{OsFamily, PlatformCtx};
+pub use unlucky_core::launch::pump::{LineSink, LogLine, RingBuffer, RingBufferConfig, Stream};
+pub use unlucky_core::launch::redact::{Redactor, TOKEN_PLACEHOLDER};
+pub use unlucky_core::launch::request::*;
+pub use unlucky_core::launch::session::{EndReason, SessionMeta, SessionSink, SessionWriter};
+pub use unlucky_core::launch::session_index;
+pub use unlucky_core::launch::window_detect::WindowDetector;
+
+pub use unlucky_core::launch::adapter::{
+    build_request, AdapterOptions, AdapterWarning, LibraryInput, SnapshotInput,
+};
+pub use unlucky_core::launch::crash_scan::CrashSource;
+pub use unlucky_core::launch::diagnosis_hook::{DiagnosisHook, DiagnosisRequest};
+pub use unlucky_core::launch::launch_session::SessionHandle;
+pub use unlucky_core::launch::launcher::{DryRun, Launcher, LauncherConfig};
+pub use unlucky_core::launch::process::ProcessConfig;
+pub use unlucky_core::launch::sink::{CompositeSink, CountingSink, FnSink};
+
+/// 断言 argv 逐项相等，失败时打印全部实际值。
+pub fn assert_argv(command: &AssembledCommand, expected: &[&str]) {
+    let actual = command.argv();
+    if actual.len() != expected.len() {
+        panic!(
+            "argv 长度 {} != 期望 {}\n实际:\n{:#?}",
+            actual.len(),
+            expected.len(),
+            actual
+        );
+    }
+    for (index, (actual, expected)) in actual.iter().zip(expected.iter()).enumerate() {
+        assert_eq!(actual, expected, "第 {index} 个参数不同");
+    }
+}
+
+/// 一个“1.12.2 + Forge”的基准请求（Windows/x86_64）。
+pub fn legacy_forge_request() -> (LaunchRequest, PlatformCtx) {
+    let ctx = PlatformCtx::new(OsFamily::Windows, "x86_64");
+    let request = LaunchRequest {
+        instance: InstanceInfo {
+            id: "inst-1".to_string(),
+            name: "1.12.2-Forge".to_string(),
+            version: GameVersion::parse("1.12.2"),
+            version_type: "release".to_string(),
+        },
+        launcher: LauncherInfo {
+            name: "UnluckyLauncher".to_string(),
+            version: "0.1.0".to_string(),
+        },
+        java: JavaSelection::new("C:/java/bin/java.exe", 17, 64),
+        memory: MemoryOptions {
+            min_mb: Some(1024),
+            max_mb: Some(4096),
+        },
+        manifest: ManifestArgs {
+            main_class: Some("net.minecraft.launchwrapper.Launch".to_string()),
+            ..ManifestArgs::default()
+        },
+        dirs: LaunchDirs {
+            game_dir: PathBuf::from("C:/mc"),
+            assets_root: PathBuf::from("C:/mc/assets"),
+            game_assets: PathBuf::from("C:/mc/assets/virtual/legacy"),
+            assets_index: "1.12".to_string(),
+            natives_dir: PathBuf::from("C:/mc/versions/1.12.2/natives-windows-x86_64"),
+            library_dir: PathBuf::from("C:/mc/libraries"),
+            primary_jar: PathBuf::from("C:/mc/versions/1.12.2/1.12.2.jar"),
+        },
+        classpath: vec![
+            PathBuf::from("C:/mc/libraries/a.jar"),
+            PathBuf::from("C:/mc/libraries/b.jar"),
+        ],
+        auth: AuthPlaceholders {
+            player_name: "Steve".to_string(),
+            uuid: "0123456789abcdef0123456789abcdef".to_string(),
+            access_token: "SECRET-TOKEN-123456".to_string(),
+            user_type: "msa".to_string(),
+            user_properties: "{}".to_string(),
+        },
+        log4j: Log4jOptions {
+            enabled: true,
+            config_file: Some(PathBuf::from("C:/mc/log4j2.xml")),
+            debug: false,
+        },
+        // 大部分断言只关心“命令骨架”，优化参数会淹没差异；需要时单独打开。
+        optimization: OptimizationOptions {
+            enabled: false,
+            physical_memory_mb: None,
+        },
+        language: "zh-CN".to_string(),
+        features: FeatureSet {
+            has_custom_resolution: true,
+            ..FeatureSet::default()
+        },
+        resolution: Some(Resolution {
+            width: 854,
+            height: 480,
+        }),
+        ..LaunchRequest::default()
+    };
+    (request, ctx)
+}
+
+/// 一个唯一的临时目录（不自动清理，便于失败时排查；OS 会回收）。
+pub fn temp_dir(name: &str) -> PathBuf {
+    let nanos = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|value| value.as_nanos())
+        .unwrap_or_default();
+    let dir =
+        std::env::temp_dir().join(format!("ull-launch-{name}-{}-{nanos}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).expect("创建临时目录");
+    dir
+}
+
+/// 一个唯一的临时会话根目录（测试结束不自动清理，便于失败时排查；OS 会回收）。
+pub fn temp_sessions_root(name: &str) -> PathBuf {
+    let nanos = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|value| value.as_nanos())
+        .unwrap_or_default();
+    let root = std::env::temp_dir().join(format!(
+        "ull-launch-test-{name}-{}-{nanos}",
+        std::process::id()
+    ));
+    let _ = std::fs::remove_dir_all(&root);
+    root
+}
+
+/// 读回 jsonl 的每一行并解析成 JSON。
+pub fn read_events(path: &std::path::Path) -> Vec<serde_json::Value> {
+    let text = std::fs::read_to_string(path).expect("读取会话文件");
+    text.lines()
+        .filter(|line| !line.trim().is_empty())
+        .map(|line| serde_json::from_str(line).expect("解析事件行"))
+        .collect()
+}
diff --git a/crates/core/tests/launch/process_smoke.rs b/crates/core/tests/launch/process_smoke.rs
new file mode 100644
index 0000000..fcf959b
--- /dev/null
+++ b/crates/core/tests/launch/process_smoke.rs
@@ -0,0 +1,167 @@
+//! 进程冒烟测试：真实 spawn 一个 shell，验证泵、退出码、进程树 kill。
+//!
+//! 这些用例跑的是真进程（不是 mock），是“事件流 + 退出分析 + 树 kill”端到端的最小证据。
+
+use std::path::PathBuf;
+use std::sync::Arc;
+use std::time::Duration;
+
+use crate::prelude::*;
+
+use unlucky_core::launch::process::{self, ProcessConfig, RunningProcess};
+use unlucky_core::launch::pump::{LineSink, NullSink};
+
+fn shell_command(script: &str) -> AssembledCommand {
+    #[cfg(windows)]
+    let (program, args) = (
+        "cmd".to_string(),
+        vec!["/C".to_string(), script.to_string()],
+    );
+    #[cfg(not(windows))]
+    let (program, args) = (
+        "/bin/sh".to_string(),
+        vec!["-c".to_string(), script.to_string()],
+    );
+    AssembledCommand {
+        program: PathBuf::from(program),
+        args,
+        classpath: Vec::new(),
+        encoding: "UTF-8".to_string(),
+        memory: MemoryOptions::default(),
+        env: Vec::new(),
+        warnings: Vec::new(),
+        main_class: String::new(),
+    }
+}
+
+fn config() -> ProcessConfig {
+    ProcessConfig {
+        graceful_stop: Duration::from_millis(200),
+        ..ProcessConfig::default()
+    }
+}
+
+#[test]
+fn spawn_collects_both_streams_and_exit_code() {
+    let root = temp_sessions_root("smoke");
+    let meta = SessionMeta::new("inst-1", "smoke", "1.20.1");
+    let writer =
+        SessionWriter::create_with_id(&root, "smoke-1", meta, Redactor::new()).expect("创建会话");
+    let path = writer.path().to_path_buf();
+    let sink = Arc::new(SessionSink::new(writer));
+
+    let mut child = RunningProcess::spawn(
+        &shell_command("echo hello-from-stdout & echo hello-from-stderr 1>&2"),
+        None,
+        sink.clone(),
+        config(),
+    )
+    .expect("spawn 应成功");
+
+    let status = child.wait().expect("wait 应成功");
+    assert_eq!(process::exit_code(&status), 0);
+    assert!(child.pid() > 0);
+
+    let verdict = child.supervise();
+    assert!(verdict.is_complete(), "两条流都应在预算内结束");
+
+    let texts: Vec<String> = child.lines().into_iter().map(|line| line.text).collect();
+    assert!(
+        texts.iter().any(|text| text.contains("hello-from-stdout")),
+        "stdout 未收集到：{texts:?}"
+    );
+    assert!(
+        texts.iter().any(|text| text.contains("hello-from-stderr")),
+        "stderr 未收集到：{texts:?}"
+    );
+
+    // 事件流里应有 stdout/stderr 行事件。
+    let events = read_events(&path);
+    let stdout_lines = events
+        .iter()
+        .filter(|event| event["kind"] == "stdout")
+        .count();
+    let stderr_lines = events
+        .iter()
+        .filter(|event| event["kind"] == "stderr")
+        .count();
+    assert!(stdout_lines >= 1, "应有 stdout 事件");
+    assert!(stderr_lines >= 1, "应有 stderr 事件");
+}
+
+#[test]
+fn stop_kills_process_tree() {
+    #[cfg(windows)]
+    let script = "ping -n 30 127.0.0.1 >nul";
+    #[cfg(not(windows))]
+    let script = "sleep 30";
+
+    let mut child =
+        RunningProcess::spawn(&shell_command(script), None, Arc::new(NullSink), config())
+            .expect("spawn 应成功");
+    assert!(child.is_running());
+
+    child.stop().expect("停止应成功");
+    let status = child.wait().expect("wait 应成功");
+    assert_ne!(
+        process::exit_code(&status),
+        0,
+        "被结束的进程不应返回退出码 0"
+    );
+    assert!(!child.is_running());
+}
+
+#[cfg(target_os = "linux")]
+#[test]
+fn spawn_puts_child_in_its_own_process_group() {
+    /// `/proc/<pid>/stat` 里的 `pgrp` 字段。
+    fn pgid(pid: u32) -> u32 {
+        let stat = std::fs::read_to_string(format!("/proc/{pid}/stat")).expect("读 /proc stat");
+        let tail = &stat[stat.rfind(')').expect("stat 应有 comm 括号") + 1..];
+        tail.split_whitespace()
+            .nth(2)
+            .expect("stat 应有 pgrp 字段")
+            .parse()
+            .expect("pgrp 应是数字")
+    }
+
+    let mut child = RunningProcess::spawn(
+        &shell_command("sleep 30"),
+        None,
+        Arc::new(NullSink),
+        config(),
+    )
+    .expect("spawn 应成功");
+    let pid = child.pid();
+    let own_pgid = pgid(std::process::id());
+
+    assert_eq!(
+        pgid(pid),
+        pid,
+        "子进程应是自己的进程组组长（process_group(0)）"
+    );
+    assert_ne!(pgid(pid), own_pgid, "子进程不能挂在测试进程的进程组上");
+    assert_eq!(
+        unlucky_core::launch::tree_kill::group_kill_target(pid),
+        Some(pid),
+        "独立组的组长才是合法的组杀目标"
+    );
+
+    child.stop().expect("停止应成功");
+    let _ = child.wait();
+}
+
+#[test]
+fn spawn_reports_missing_program() {
+    let mut command = shell_command("echo hi");
+    command.program = PathBuf::from("definitely-not-a-real-binary-ull");
+    let error = RunningProcess::spawn(&command, None, Arc::new(NullSink), config())
+        .expect_err("程序不存在必须报错");
+    assert!(matches!(error, LaunchError::Spawn { .. }));
+}
+
+#[test]
+fn line_sink_trait_object_is_usable() {
+    let sink: Arc<dyn LineSink> = Arc::new(NullSink);
+    sink.on_line(&LogLine::new(Stream::Stdout, "ignored"));
+}
diff --git a/crates/core/tests/launch/pump_buffer.rs b/crates/core/tests/launch/pump_buffer.rs
new file mode 100644
index 0000000..9cd4523
--- /dev/null
+++ b/crates/core/tests/launch/pump_buffer.rs
@@ -0,0 +1,111 @@
+//! 环形缓冲 / 级别猜测 / 窗口检测。
+
+use crate::prelude::*;
+
+fn line(stream: Stream, text: &str) -> LogLine {
+    LogLine::new(stream, text)
+}
+
+#[test]
+fn ring_buffer_respects_line_limit() {
+    let mut buffer = RingBuffer::new(RingBufferConfig {
+        max_lines: 3,
+        max_bytes: 1024 * 1024,
+    });
+    for index in 0..5 {
+        buffer.push(line(Stream::Stdout, &format!("line-{index}")));
+    }
+    assert_eq!(buffer.len(), 3);
+    let texts: Vec<String> = buffer.lines().map(|item| item.text.clone()).collect();
+    assert_eq!(texts, vec!["line-2", "line-3", "line-4"]);
+    assert_eq!(buffer.total_pushed(), 5);
+}
+
+#[test]
+fn ring_buffer_keeeps_key_lines_after_eviction() {
+    let mut buffer = RingBuffer::new(RingBufferConfig {
+        max_lines: 2,
+        max_bytes: 1024 * 1024,
+    });
+    buffer.push(line(
+        Stream::Stderr,
+        "java.lang.ExceptionInInitializerError",
+    ));
+    buffer.push(line(Stream::Stdout, "noise-1"));
+    buffer.push(line(Stream::Stdout, "noise-2"));
+    buffer.push(line(Stream::Stdout, "noise-3"));
+
+    let texts: Vec<String> = buffer.lines().map(|item| item.text.clone()).collect();
+    assert!(texts
+        .iter()
+        .any(|text| text.contains("ExceptionInInitializer")));
+    assert!(texts.contains(&"noise-3".to_string()));
+    assert!(!texts.contains(&"noise-1".to_string()));
+    assert_eq!(buffer.error_lines().len(), 1);
+}
+
+#[test]
+fn ring_buffer_respects_byte_limit() {
+    let mut buffer = RingBuffer::new(RingBufferConfig {
+        max_lines: 1000,
+        max_bytes: 32,
+    });
+    buffer.push(line(Stream::Stdout, "0123456789"));
+    buffer.push(line(Stream::Stdout, "abcdefghij"));
+    buffer.push(line(Stream::Stdout, "ABCDEFGHIJ"));
+    assert!(buffer.len() < 4, "字节上限应触发淘汰");
+    assert!(buffer.text().contains("ABCDEFGHIJ"));
+}
+
+#[test]
+fn level_guessing_matches_hmcl_rules() {
+    assert_eq!(
+        log_level::guess(false, "[12:34:56] [Render thread/ERROR]: boom"),
+        Level::Error
+    );
+    assert_eq!(
+        log_level::guess(false, "[12:34:56] [main/INFO]: hi"),
+        Level::Info
+    );
+    assert_eq!(
+        log_level::guess(false, "[12:34:56] [Worker-Main-1/WARN] [mixin/]: careful"),
+        Level::Warn
+    );
+    assert_eq!(log_level::guess(false, "[SEVERE] java error"), Level::Error);
+    assert_eq!(log_level::guess(false, "plain text"), Level::Unknown);
+    // stderr 一律当错误，authlib-injector 例外。
+    assert_eq!(log_level::guess(true, "anything"), Level::Error);
+    assert_eq!(
+        log_level::guess(true, "[authlib-injector] loaded"),
+        Level::Info
+    );
+}
+
+#[test]
+fn line_level_uses_stream_and_text() {
+    assert_eq!(line(Stream::Stderr, "boom").level(), Level::Error);
+    assert_eq!(
+        line(Stream::Stdout, "[12:34:56] [main/DEBUG]: detail").level(),
+        Level::Debug
+    );
+}
+
+#[test]
+fn window_detector_reports_heuristic_once() {
+    let mut detector = WindowDetector::new();
+    assert!(detector
+        .observe("[12:00:00] [main/INFO]: Loading LWJGL")
+        .is_none());
+    let detection = detector
+        .observe("[12:00:01] [Render thread/INFO]: LWJGL Version: 3.3.1")
+        .expect("应命中 lwjgl version");
+    assert_eq!(detection.heuristic, "lwjgl_version");
+    assert!(detection.evidence.contains("LWJGL Version"));
+    assert!(detector.is_detected());
+    // 只报一次。
+    assert!(detector.observe("LWJGL Version: 3.3.1").is_none());
+    assert_eq!(
+        detector.detection().map(|d| d.heuristic.as_str()),
+        Some("lwjgl_version")
+    );
+}
diff --git a/crates/core/tests/launch/session_events.rs b/crates/core/tests/launch/session_events.rs
new file mode 100644
index 0000000..b6ffab4
--- /dev/null
+++ b/crates/core/tests/launch/session_events.rs
@@ -0,0 +1,257 @@
+//! 会话事件流（JSONL）与索引测试。
+//!
+//! 校验 `DevDocs/SubAgentsTalk/launch-接口约定.md` 的硬约定：
+//! `seq` 单调、写前脱敏、索引同 id 取最后一行。
+
+use std::sync::Arc;
+
+use serde_json::json;
+use unlucky_core::launch::pump::LineSink;
+
+use crate::prelude::*;
+
+fn command_with_token() -> AssembledCommand {
+    let (mut request, ctx) = legacy_forge_request();
+    request.manifest.legacy_arguments =
+        Some("--accessToken ${auth_session} --username ${auth_player_name}".to_string());
+    assemble(&request, &ctx).expect("组装应成功")
+}
+
+#[test]
+fn session_stream_records_all_event_kinds() {
+    let root = temp_sessions_root("events");
+    let ctx = PlatformCtx::new(OsFamily::Windows, "x86_64");
+    let meta = SessionMeta::new("inst-1", "1.12.2-Forge", "1.12.2")
+        .with_launcher("UnluckyLauncher", "0.1.0")
+        .with_platform(&ctx);
+    let redactor = Redactor::new().with_secret("SECRET-TOKEN-123456");
+    let mut writer = SessionWriter::create_with_id(&root, "20261029T120000-abcdef", meta, redactor)
+        .expect("创建会话");
+
+    writer.session_start().expect("session_start");
+    writer.cmd_built(&command_with_token()).expect("cmd_built");
+    writer.proc_start(4242).expect("proc_start");
+    writer
+        .line(&LogLine::new(Stream::Stdout, "LWJGL Version: 3.3.1"))
+        .expect("stdout");
+    writer
+        .line(&LogLine::new(
+            Stream::Stderr,
+            "java.lang.IllegalStateException: boom",
+        ))
+        .expect("stderr");
+    writer
+        .window_detected(&unlucky_core::launch::window_detect::Detection {
+            heuristic: "lwjgl_version".to_string(),
+            took_ms: 820,
+            evidence: "LWJGL Version: 3.3.1".to_string(),
+        })
+        .expect("window_detected");
+
+    let lines = vec![LogLine::new(Stream::Stderr, "java.lang.Exception: boom")];
+    let analysis = exit_analysis::analyze(&exit_analysis::ExitSignals::new(1, 40_000, &lines));
+    writer.exit(&analysis).expect("exit");
+    writer
+        .diagnosis(json!({
+            "source": "rules",
+            "needs_more_info": false,
+            "candidates": [{ "id": "mixin_apply_failed", "confidence": 0.9 }],
+        }))
+        .expect("diagnosis");
+
+    let entry = writer.finish(EndReason::Exit).expect("session_end");
+    assert!(writer.is_finished());
+    assert_eq!(entry.session_id, "20261029T120000-abcdef");
+    assert_eq!(entry.exit_code, Some(1));
+    assert_eq!(entry.exit_type.as_deref(), Some("application_error"));
+    assert!(entry.window_detected);
+    assert_eq!(entry.diagnosis_top.as_deref(), Some("mixin_apply_failed"));
+    assert_eq!(entry.log_path, "game/20261029T120000-abcdef.jsonl");
+
+    let events = read_events(writer.path());
+    let kinds: Vec<&str> = events
+        .iter()
+        .filter_map(|event| event.get("kind").and_then(|value| value.as_str()))
+        .collect();
+    assert_eq!(
+        kinds,
+        vec![
+            "session_start",
+            "cmd_built",
+            "proc_start",
+            "stdout",
+            "stderr",
+            "window_detected",
+            "exit",
+            "diagnosis",
+            "session_end",
+        ]
+    );
+
+    // seq 从 0 单调递增，v/ts/t_ms/session_id 齐全。
+    for (index, event) in events.iter().enumerate() {
+        assert_eq!(event["v"], 1);
+        assert_eq!(event["seq"], index as u64);
+        assert_eq!(event["session_id"], "20261029T120000-abcdef");
+        assert!(event["ts"].as_str().unwrap_or_default().ends_with('Z'));
+        assert!(event["t_ms"].is_u64());
+    }
+    assert_eq!(entry.event_count, events.len() as u64);
+
+    // 索引落盘且可读回。
+    let index = session_index::index_path(&root);
+    let listed = session_index::read_all(&index).expect("读索引");
+    assert_eq!(listed.len(), 1);
+    assert_eq!(listed[0].session_id, entry.session_id);
+}
+
+#[test]
+fn cmd_built_argv_is_redacted_before_writing() {
+    let root = temp_sessions_root("redact");
+    let meta = SessionMeta::new("inst-1", "1.12.2-Forge", "1.12.2");
+    let redactor = Redactor::new().with_secret("SECRET-TOKEN-123456");
+    let mut writer =
+        SessionWriter::create_with_id(&root, "redact-1", meta, redactor).expect("创建会话");
+    writer.cmd_built(&command_with_token()).expect("cmd_built");
+
+    let raw = std::fs::read_to_string(writer.path()).expect("读文件");
+    assert!(!raw.contains("SECRET-TOKEN-123456"), "命令行必须脱敏后落盘");
+    assert!(raw.contains(TOKEN_PLACEHOLDER));
+
+    let events = read_events(writer.path());
+    let argv = events[0]["payload"]["argv"]
+        .as_array()
+        .cloned()
+        .unwrap_or_default();
+    assert!(argv
+        .iter()
+        .any(|arg| arg.as_str() == Some(TOKEN_PLACEHOLDER)));
+}
+
+#[test]
+fn diagnosis_payload_is_redacted_before_writing() {
+    let root = temp_sessions_root("diagnosis-redact");
+    let meta = SessionMeta::new("inst-1", "1.20.1", "1.20.1");
+    let redactor = Redactor::new()
+        .with_secret("SECRET-TOKEN-123456")
+        .with_home_str("C:/Users/aska");
+    let mut writer =
+        SessionWriter::create_with_id(&root, "diag-redact-1", meta, redactor).expect("创建会话");
+    writer
+        .diagnosis(json!({
+            "source": "rules",
+            "needs_more_info": false,
+            "candidates": [{
+                "id": "mixin_failed",
+                "confidence": 0.9,
+                "message_key": "launch.crash.reason.mixin_failed",
+                "evidence": [
+                    "hs_err:C:/Users/aska/.minecraft/hs_err_pid123.log: java.lang.Exception",
+                    "token=SECRET-TOKEN-123456",
+                ],
+            }],
+        }))
+        .expect("写 diagnosis");
+
+    let raw = std::fs::read_to_string(writer.path()).expect("读文件");
+    assert!(!raw.contains("C:/Users/aska"), "诊断证据里的主目录必须脱敏");
+    assert!(
+        !raw.contains("SECRET-TOKEN-123456"),
+        "诊断证据里的凭据必须脱敏"
+    );
+    assert!(raw.contains("<home>"));
+    assert!(raw.contains("<redacted:token>"), "同一个值内也允许混合脱敏");
+
+    // 字段名/数值/布尔原样保留（launch 只脱敏、不改写字段）。
+    let events = read_events(writer.path());
+    let payload = &events[0]["payload"];
+    assert_eq!(payload["needs_more_info"], json!(false));
+    assert_eq!(payload["candidates"][0]["id"], json!("mixin_failed"));
+    assert_eq!(payload["candidates"][0]["confidence"], json!(0.9));
+    assert_eq!(
+        payload["candidates"][0]["message_key"],
+        json!("launch.crash.reason.mixin_failed")
+    );
+    assert_eq!(payload["source"], json!("rules"));
+    // diagnosis_top 仍能从脱敏后的 candidates 取出。
+    assert_eq!(
+        writer
+            .finish(EndReason::Exit)
+            .expect("结束会话")
+            .diagnosis_top
+            .as_deref(),
+        Some("mixin_failed")
+    );
+}
+
+#[test]
+fn index_keeps_last_line_per_session_id() {
+    let root = temp_sessions_root("index");
+    let mut entry = session_index::SessionIndexEntry {
+        v: 1,
+        session_id: "same-id".to_string(),
+        instance_id: "inst-1".to_string(),
+        instance_name: "one".to_string(),
+        game_version: "1.20.1".to_string(),
+        started_at: "2026-10-29T12:00:00.000Z".to_string(),
+        ended_at: "2026-10-29T12:01:00.000Z".to_string(),
+        duration_ms: 60_000,
+        exit_code: Some(0),
+        exit_type: Some("normal".to_string()),
+        ..session_index::SessionIndexEntry::default()
+    };
+    let index = session_index::index_path(&root);
+    session_index::append(&index, &entry).expect("第一次写索引");
+
+    // 崩溃重启后重写同一会话的索引行。
+    entry.exit_code = Some(1);
+    entry.exit_type = Some("application_error".to_string());
+    entry.duration_ms = 30_000;
+    session_index::append(&index, &entry).expect("第二次写索引");
+
+    let listed = session_index::read_all(&index).expect("读索引");
+    assert_eq!(listed.len(), 1, "同 id 只保留一条");
+    assert_eq!(listed[0].exit_code, Some(1));
+    assert_eq!(listed[0].duration_ms, 30_000);
+
+    // 追加另一实例的会话，按实例过滤生效。
+    let mut other = listed[0].clone();
+    other.session_id = "other-id".to_string();
+    other.instance_id = "inst-2".to_string();
+    other.started_at = "2026-10-30T12:00:00.000Z".to_string();
+    session_index::append(&index, &other).expect("第三次写索引");
+    let only = session_index::list(&index, 10, Some("inst-2")).expect("过滤");
+    assert_eq!(only.len(), 1);
+    assert_eq!(only[0].session_id, "other-id");
+    // 倒序：最新的在前。
+    let all = session_index::list(&index, 10, None).expect("全部");
+    assert_eq!(
+        all.first().map(|item| item.session_id.as_str()),
+        Some("other-id")
+    );
+}
+
+#[test]
+fn session_sink_writes_lines_and_detects_window() {
+    let root = temp_sessions_root("sink");
+    let meta = SessionMeta::new("inst-1", "1.20.1", "1.20.1");
+    let writer =
+        SessionWriter::create_with_id(&root, "sink-1", meta, Redactor::new()).expect("创建会话");
+    let path = writer.path().to_path_buf();
+    let sink = Arc::new(SessionSink::new(writer));
+
+    sink.on_line(&LogLine::new(Stream::Stdout, "preparing"));
+    sink.on_line(&LogLine::new(Stream::Stdout, "LWJGL Version: 3.3.1"));
+    sink.on_line(&LogLine::new(Stream::Stderr, "warn: something"));
+
+    let kinds: Vec<String> = read_events(&path)
+        .iter()
+        .filter_map(|event| event["kind"].as_str().map(str::to_string))
+        .collect();
+    assert!(
+        kinds.contains(&"window_detected".to_string()),
+        "sink 应自动检测窗口"
+    );
+    assert_eq!(kinds.iter().filter(|kind| *kind == "stdout").count(), 2);
+    assert_eq!(kinds.iter().filter(|kind| *kind == "stderr").count(), 1);
+}
diff --git a/crates/core/tests/launch/sink_cases.rs b/crates/core/tests/launch/sink_cases.rs
new file mode 100644
index 0000000..62887bf
--- /dev/null
+++ b/crates/core/tests/launch/sink_cases.rs
@@ -0,0 +1,73 @@
+//! sink 组合测试（复合 sink 是接 M15 采集器 / UI 日志页的接缝）。
+
+use std::sync::{Arc, Mutex};
+
+use crate::prelude::*;
+
+fn line(stream: Stream, text: &str) -> LogLine {
+    LogLine::new(stream, text)
+}
+
+#[test]
+fn composite_sink_broadcasts_in_registration_order() {
+    let order = Arc::new(Mutex::new(Vec::<String>::new()));
+    let first = {
+        let order = order.clone();
+        FnSink::new(move |line: &LogLine| {
+            order.lock().unwrap().push(format!("first:{}", line.text));
+        })
+    };
+    let second = {
+        let order = order.clone();
+        FnSink::new(move |line: &LogLine| {
+            order.lock().unwrap().push(format!("second:{}", line.text));
+        })
+    };
+    let composite = CompositeSink::new()
+        .with(first.shared())
+        .with(second.shared());
+    assert_eq!(composite.len(), 2);
+    composite.on_line(&line(Stream::Stdout, "hello"));
+
+    let recorded = order.lock().unwrap().clone();
+    assert_eq!(recorded, vec!["first:hello", "second:hello"]);
+}
+
+#[test]
+fn composite_sink_passes_stream_and_text() {
+    let seen = Arc::new(Mutex::new(Vec::<(Stream, String)>::new()));
+    let recorder = {
+        let seen = seen.clone();
+        FnSink::new(move |line: &LogLine| {
+            seen.lock().unwrap().push((line.stream, line.text.clone()));
+        })
+    };
+    // 模拟 diagnose 侧：只记文本 + 流标记（不解析 jsonl、不 import launch 类型）。
+    let mut composite = CompositeSink::new();
+    composite.push(recorder.shared());
+    composite.on_line(&line(Stream::Stdout, "out"));
+    composite.on_line(&line(Stream::Stderr, "err"));
+
+    let seen = seen.lock().unwrap().clone();
+    assert_eq!(seen.len(), 2);
+    assert_eq!(seen[0], (Stream::Stdout, "out".to_string()));
+    assert_eq!(seen[1], (Stream::Stderr, "err".to_string()));
+}
+
+#[test]
+fn counting_sink_counts_per_stream() {
+    let counter = Arc::new(CountingSink::new());
+    counter.on_line(&line(Stream::Stdout, "a"));
+    counter.on_line(&line(Stream::Stdout, "b"));
+    counter.on_line(&line(Stream::Stderr, "c"));
+    assert_eq!(counter.stdout_lines(), 2);
+    assert_eq!(counter.stderr_lines(), 1);
+    assert_eq!(counter.total_lines(), 3);
+}
+
+#[test]
+fn empty_composite_is_harmless() {
+    let composite = CompositeSink::new();
+    assert!(composite.is_empty());
+    composite.on_line(&line(Stream::Stdout, "ignored"));
+}
diff --git a/crates/core/tests/launch/tree_kill_cases.rs b/crates/core/tests/launch/tree_kill_cases.rs
new file mode 100644
index 0000000..052da5a
--- /dev/null
+++ b/crates/core/tests/launch/tree_kill_cases.rs
@@ -0,0 +1,201 @@
+//! 进程树回收的安全钉子：组杀只打“目标自己的独立进程组”，绝不命中我们所在的组。
+//!
+//! 这些用例钉的是 M48 的两条根因：
+//! - 子进程必须自成一个进程组（`process_group(0)`），否则 `kill -- -<pgid>` 没有可用的组；
+//! - 组杀前必须验组（[`tree_kill::group_kill_target`]），否则 CI 容器里“全体进程 pgid=1”
+//!   的那种环境会被一发组杀连测试进程一起带走。
+//!
+//! `/proc` 只有 Linux 有，进程组相关的用例都用 `#[cfg(target_os = "linux")]` 门住；
+//! `pid == 0` 的守卫与平台无关，各平台都跑。
+
+use std::time::Duration;
+
+use unlucky_core::launch::tree_kill;
+
+/// `pid` 0 在 POSIX `kill` 里表示“当前进程组”——绝不能顺手发出去。
+#[test]
+fn pid_zero_is_rejected() {
+    assert!(tree_kill::terminate(0).is_err(), "terminate(0) 必须拒绝");
+    assert!(tree_kill::force_kill(0).is_err(), "force_kill(0) 必须拒绝");
+    assert!(
+        tree_kill::kill_tree(0, Duration::ZERO).is_err(),
+        "kill_tree(0) 必须拒绝"
+    );
+}
+
+#[cfg(target_os = "linux")]
+mod linux {
+    use super::*;
+    use std::process::{Child, Command, Stdio};
+
+    use unlucky_core::launch::tree_kill::group_kill_target;
+
+    /// `/proc/<pid>/stat` 里 `)` 之后的字段（state ppid pgrp ...）。
+    fn stat_tail(pid: u32) -> Option<Vec<String>> {
+        let stat = std::fs::read_to_string(format!("/proc/{pid}/stat")).ok()?;
+        let tail = stat.get(stat.rfind(')')? + 1..)?;
+        Some(tail.split_whitespace().map(str::to_string).collect())
+    }
+
+    fn pgid(pid: u32) -> Option<u32> {
+        stat_tail(pid)?.get(2)?.parse().ok()
+    }
+
+    /// 还活着（僵尸不算：已经死了只是没人 wait）。
+    fn running(pid: u32) -> bool {
+        matches!(stat_tail(pid).as_deref().and_then(|fields| fields.first().map(String::as_str)), Some(state) if state != "Z")
+    }
+
+    fn wait_gone(pid: u32, budget: Duration) -> bool {
+        let deadline = std::time::Instant::now() + budget;
+        while std::time::Instant::now() < deadline {
+            if !running(pid) {
+                return true;
+            }
+            std::thread::sleep(Duration::from_millis(20));
+        }
+        !running(pid)
+    }
+
+    /// 组长的子进程（`process_group(0)`）：自带一个组。
+    fn spawn_grouped(script: &str) -> Child {
+        use std::os::unix::process::CommandExt;
+        Command::new("/bin/sh")
+            .arg("-c")
+            .arg(script)
+            .stdin(Stdio::null())
+            .stdout(Stdio::null())
+            .stderr(Stdio::null())
+            .process_group(0)
+            .spawn()
+            .expect("spawn 应成功")
+    }
+
+    /// 和测试进程同组的子进程（不调 `process_group`）：组长不是它。
+    fn spawn_in_our_group(script: &str) -> Child {
+        Command::new("/bin/sh")
+            .arg("-c")
+            .arg(script)
+            .stdin(Stdio::null())
+            .stdout(Stdio::null())
+            .stderr(Stdio::null())
+            .spawn()
+            .expect("spawn 应成功")
+    }
+
+    /// 测试失败时也别把 `sleep 30` 留在机器上。
+    struct KillOnDrop(u32);
+
+    impl Drop for KillOnDrop {
+        fn drop(&mut self) {
+            let _ = tree_kill::force_kill(self.0);
+        }
+    }
+
+    /// 自己的进程组号：组杀安全的基准。
+    fn self_pgid() -> u32 {
+        pgid(std::process::id()).expect("/proc/self/stat 应可读")
+    }
+
+    #[test]
+    fn group_kill_target_accepts_only_a_verified_own_group() {
+        let own_pgid = self_pgid();
+        // 我们自己所在的组永远不是合法目标（哪怕我们正好是组长）。
+        assert_eq!(
+            group_kill_target(std::process::id()),
+            None,
+            "自己的进程号绝不能成为组杀目标"
+        );
+        assert_eq!(
+            group_kill_target(own_pgid),
+            None,
+            "自己的进程组绝不能成为组杀目标"
+        );
+        assert_eq!(group_kill_target(0), None, "pid 0 不是合法目标");
+
+        // 同组的子进程：它不是组长，`-<pid>` 指向的不是“它的”组。
+        let mut child = spawn_in_our_group("sleep 30");
+        let pid = child.id();
+        let _guard = KillOnDrop(pid);
+        assert_eq!(pgid(pid), Some(own_pgid), "同组子进程应继承我们的 pgid");
+        assert_eq!(
+            group_kill_target(pid),
+            None,
+            "非组长子进程不能走组杀（`-<pid>` 会打到别人的组）"
+        );
+
+        // 独立组的子进程：合法的组杀目标。
+        let mut grouped = spawn_grouped("sleep 30");
+        let grouped_pid = grouped.id();
+        let _grouped_guard = KillOnDrop(grouped_pid);
+        assert_eq!(pgid(grouped_pid), Some(grouped_pid), "子进程应是组长");
+        assert_eq!(
+            group_kill_target(grouped_pid),
+            Some(grouped_pid),
+            "独立组的组长可以组杀"
+        );
+
+        let _ = child.kill();
+        let _ = child.wait();
+        let _ = grouped.kill();
+        let _ = grouped.wait();
+    }
+
+    #[test]
+    fn group_kill_reaps_grandchildren_without_touching_our_group() {
+        let mut child = spawn_grouped("sleep 30 & sleep 30");
+        let pid = child.id();
+        let _guard = KillOnDrop(pid);
+        std::thread::sleep(Duration::from_millis(300));
+
+        let children_of = || -> Vec<u32> {
+            std::fs::read_to_string(format!("/proc/{pid}/task/{pid}/children"))
+                .unwrap_or_default()
+                .split_whitespace()
+                .filter_map(|value| value.parse().ok())
+                .collect()
+        };
+        let grandchildren = children_of();
+        assert!(
+            !grandchildren.is_empty(),
+            "shell 应当先 fork 出一个 sleep 子进程：{grandchildren:?}"
+        );
+        for grandchild in &grandchildren {
+            assert_eq!(pgid(*grandchild), Some(pid), "后代必须落在子进程自己的组里");
+        }
+
+        tree_kill::terminate(pid).expect("组杀应送达");
+        assert!(wait_gone(pid, Duration::from_secs(3)), "组长应被组杀带走");
+        for grandchild in &grandchildren {
+            assert!(
+                wait_gone(*grandchild, Duration::from_secs(3)),
+                "组杀应覆盖后代 {grandchild}"
+            );
+        }
+
+        // 组杀没有溢出：我们自己还在原来的组里，而且没有被信号带走。
+        assert_eq!(self_pgid(), pgid(std::process::id()).expect("仍然可读"));
+        assert_ne!(pid, self_pgid(), "目标组和我们的组必须不同");
+
+        let _ = child.wait();
+    }
+
+    #[test]
+    fn terminate_still_kills_a_child_that_shares_our_group() {
+        let own_pgid = self_pgid();
+        let mut child = spawn_in_our_group("sleep 30");
+        let pid = child.id();
+        let _guard = KillOnDrop(pid);
+        assert_eq!(pgid(pid), Some(own_pgid));
+
+        tree_kill::terminate(pid).expect("单 pid 兜底应送达");
+        assert!(
+            wait_gone(pid, Duration::from_secs(3)),
+            "同组子进程也必须能被单 pid TERM 干掉"
+        );
+        // 走到这里本身就说明“组杀没有命中自身进程组”——否则测试进程已被 TERM。
+        assert_eq!(self_pgid(), pgid(std::process::id()).expect("仍然可读"));
+
+        let _ = child.wait();
+    }
+}
diff --git a/crates/core/tests/platform/linux_caps_cases.rs b/crates/core/tests/platform/linux_caps_cases.rs
new file mode 100644
index 0000000..9bab8f9
--- /dev/null
+++ b/crates/core/tests/platform/linux_caps_cases.rs
@@ -0,0 +1,136 @@
+//! Linux 探测：`/etc/os-release`、内核 release、会话类型、glibc 版本。
+
+use std::collections::HashMap;
+
+use crate::prelude::*;
+
+const UBUNTU_OS_RELEASE: &str = "\
+PRETTY_NAME=\"Ubuntu 24.04.1 LTS\"
+NAME=\"Ubuntu\"
+VERSION_ID=\"24.04\"
+ID=ubuntu
+";
+
+#[test]
+fn os_release_prefers_pretty_name() {
+    assert_eq!(
+        linux_caps::parse_os_release(UBUNTU_OS_RELEASE),
+        Some("Ubuntu 24.04.1 LTS".to_string())
+    );
+    // 没有 PRETTY_NAME 的裁剪发行版：NAME + VERSION_ID 拼一个（不够精确但够日志用）。
+    let minimal = "NAME=\"Alpine Linux\"\nVERSION_ID=3.19\n";
+    assert_eq!(
+        linux_caps::parse_os_release(minimal),
+        Some("Alpine Linux 3.19".to_string())
+    );
+    assert_eq!(linux_caps::parse_os_release(""), None);
+    assert_eq!(linux_caps::parse_os_release("ID=arch\n"), None);
+}
+
+#[test]
+fn kernel_release_yields_major_minor() {
+    assert_eq!(
+        linux_caps::parse_kernel_version("6.8.0-45-generic"),
+        Some((6, 8))
+    );
+    assert_eq!(linux_caps::parse_kernel_version("5.15.0"), Some((5, 15)));
+    assert_eq!(linux_caps::parse_kernel_version("3.2"), Some((3, 2)));
+    assert_eq!(linux_caps::parse_kernel_version("6.8"), Some((6, 8)));
+    assert_eq!(linux_caps::parse_kernel_version(""), None);
+    assert_eq!(linux_caps::parse_kernel_version("not-a-version"), None);
+}
+
+#[test]
+fn session_detection_order_is_wayland_then_x11_then_headless() {
+    fn detect(pairs: &[(&str, &str)]) -> SessionKind {
+        let map: HashMap<String, String> = pairs
+            .iter()
+            .map(|(key, value)| ((*key).to_string(), (*value).to_string()))
+            .collect();
+        linux_caps::session_from_env(|key| map.get(key).cloned())
+    }
+
+    assert_eq!(
+        detect(&[("WAYLAND_DISPLAY", "wayland-0")]),
+        SessionKind::Wayland
+    );
+    assert_eq!(
+        detect(&[("XDG_SESSION_TYPE", "wayland"), ("DISPLAY", ":0")]),
+        SessionKind::Wayland
+    );
+    assert_eq!(
+        detect(&[("XDG_SESSION_TYPE", "x11"), ("DISPLAY", ":0")]),
+        SessionKind::X11
+    );
+    assert_eq!(detect(&[("DISPLAY", ":0")]), SessionKind::X11);
+    // 空值不算有会话（SSH 转发里 `WAYLAND_DISPLAY=` 是常见的空串形态）。
+    assert_eq!(
+        detect(&[("WAYLAND_DISPLAY", "  "), ("DISPLAY", ":0")]),
+        SessionKind::X11
+    );
+    assert_eq!(detect(&[]), SessionKind::Headless);
+}
+
+#[test]
+fn session_kind_helpers() {
+    assert!(SessionKind::Wayland.has_display());
+    assert!(SessionKind::X11.has_display());
+    assert!(!SessionKind::Headless.has_display());
+    assert!(!SessionKind::Unknown.has_display());
+    assert_eq!(SessionKind::Wayland.as_str(), "wayland");
+    assert_eq!(SessionKind::Headless.as_str(), "headless");
+    assert_eq!(GlProbe::Unknown.as_str(), "unknown");
+    assert_eq!(GlProbe::Missing.as_str(), "missing");
+}
+
+#[test]
+fn glibc_version_comes_from_the_first_ldd_line() {
+    assert_eq!(
+        linux_caps::parse_glibc_version(
+            "ldd (Ubuntu GLIBC 2.39-0ubuntu8.3) 2.39\nCopyright (C) 2024\n"
+        ),
+        Some((2, 39))
+    );
+    assert_eq!(
+        linux_caps::parse_glibc_version("ldd (GNU libc) 2.31"),
+        Some((2, 31))
+    );
+    assert_eq!(
+        linux_caps::parse_glibc_version("ldd (Debian GLIBC 2.36-9+deb12u4) 2.36"),
+        Some((2, 36))
+    );
+    // musl / 命令不存在：不能瞎猜，交给上层「不阻塞」。
+    assert_eq!(linux_caps::parse_glibc_version("ldd: not found"), None);
+    assert_eq!(linux_caps::parse_glibc_version(""), None);
+}
+
+#[test]
+fn format_version_is_dotted() {
+    assert_eq!(linux_caps::format_version((2, 31)), "2.31");
+    assert_eq!(linux_caps::format_version((6, 8)), "6.8");
+}
+
+#[test]
+fn gl_probe_is_a_hook_returning_unknown_for_now() {
+    // P1 只留钩子：真探测要 dlopen（FFI），core 禁 unsafe，故恒为 Unknown 且不阻塞。
+    assert_eq!(linux_caps::probe_gl(), GlProbe::Unknown);
+}
+
+#[test]
+fn caps_probe_matches_the_host() {
+    let caps: LinuxCaps = linux_caps::probe();
+    if cfg!(target_os = "linux") {
+        // 容器里可能全空，但会话类型至少是「探过了」。
+        assert_ne!(caps.session, SessionKind::Unknown);
+        if let Some(kernel) = &caps.kernel {
+            assert!(
+                caps.kernel_version.is_some(),
+                "内核串 {kernel} 应能取 major.minor"
+            );
+        }
+    } else {
+        assert_eq!(caps.session, SessionKind::Unknown);
+        assert!(caps.kernel.is_none());
+        assert!(caps.distro.is_none());
+    }
+}
diff --git a/crates/core/tests/platform/macos_cases.rs b/crates/core/tests/platform/macos_cases.rs
new file mode 100644
index 0000000..f645fb3
--- /dev/null
+++ b/crates/core/tests/platform/macos_cases.rs
@@ -0,0 +1,58 @@
+//! macOS 探测：`sw_vers -productVersion` 与 `sysctl hw.optional.arm64`。
+
+use crate::prelude::*;
+
+#[test]
+fn product_version_parses_sw_vers_output() {
+    assert_eq!(
+        macos_version::parse_product_version("12.3.1\n"),
+        Some((12, 3, 1))
+    );
+    assert_eq!(
+        macos_version::parse_product_version("12.3"),
+        Some((12, 3, 0))
+    );
+    assert_eq!(macos_version::parse_product_version("12"), Some((12, 0, 0)));
+    assert_eq!(
+        macos_version::parse_product_version("  14.2.1  "),
+        Some((14, 2, 1))
+    );
+    assert_eq!(macos_version::parse_product_version(""), None);
+    assert_eq!(macos_version::parse_product_version("ProductVersion"), None);
+}
+
+#[test]
+fn sysctl_arm64_flag() {
+    assert!(macos_version::parse_sysctl_bool("1\n"));
+    assert!(!macos_version::parse_sysctl_bool("0\n"));
+    // Intel 机器上 sysctl 以非零码退出 → stdout 为空 → 不是 arm64。
+    assert!(!macos_version::parse_sysctl_bool(""));
+}
+
+#[test]
+fn version_strings_and_runtime_arch() {
+    let apple_silicon = MacOsVersion::new(12, 3, 1, true);
+    assert_eq!(apple_silicon.version_string(), "12.3.1");
+    assert_eq!(apple_silicon.runtime_arch(), "arm64");
+    assert_eq!(apple_silicon.display_name(), "macOS 12.3.1 (arm64)");
+
+    // Rosetta 2 下编译目标是 x86_64，但真实架构仍是 arm64：
+    // 探到 arm64 时 runtime_arch 必须是 arm64（MC 原生库与渲染路径都按它选）。
+    let rosetta = MacOsVersion::new(12, 3, 1, true);
+    assert_eq!(rosetta.runtime_arch(), "arm64");
+
+    let intel = MacOsVersion::new(15, 0, 0, false);
+    assert_eq!(intel.runtime_arch(), "x86_64");
+    assert_eq!(intel.display_name(), "macOS 15.0.0 (x86_64)");
+}
+
+#[test]
+fn probe_matches_the_host() {
+    let probed = macos_version::probe();
+    if cfg!(target_os = "macos") {
+        let version = probed.expect("macOS 宿主必须能探到产品版本");
+        assert!(version.major >= 10, "探到 {version:?}");
+    } else {
+        assert!(probed.is_none(), "非 macOS 平台不应探到 macOS 版本");
+    }
+}
diff --git a/crates/core/tests/platform/main.rs b/crates/core/tests/platform/main.rs
new file mode 100644
index 0000000..06767ae
--- /dev/null
+++ b/crates/core/tests/platform/main.rs
@@ -0,0 +1,17 @@
+//! platform 模块集成测试入口（`cargo test -p unlucky-core --test platform`）。
+//!
+//! 覆盖 D19（`PlanDoc/11-os-detection.md`）的运行期探测：
+//! - 等级映射 / 文案：注入式假数据，不改机器真实版本；
+//! - 各平台探测的**解析**（Windows 注册表与 `ver`、Linux `/etc/os-release`+内核+glibc、
+//!   macOS `sw_vers`+`sysctl`）：解析函数跨平台编译，所以能在任意宿主上单测；
+//! - `rules.os.version` 用真实探测值求值的接线；
+//! - 系统主题探测（`theme_probe`：注册表 / `defaults` / `gsettings` 解析 + 三态契约）。
+
+mod linux_caps_cases;
+mod macos_cases;
+mod os_info_cases;
+mod prelude;
+mod rules_wiring;
+mod theme_cases;
+mod vk_cases;
+mod windows_version_cases;
diff --git a/crates/core/tests/platform/os_info_cases.rs b/crates/core/tests/platform/os_info_cases.rs
new file mode 100644
index 0000000..ab5e107
--- /dev/null
+++ b/crates/core/tests/platform/os_info_cases.rs
@@ -0,0 +1,299 @@
+//! 支持等级映射与双语文案：全部用注入式假数据，不改机器真实版本。
+//!
+//! 基线（用户拍板）：Windows 10+ / macOS 12+ / Linux 达标 → 一等，其余一律不支持；
+//! Win8.1/8/7 也不承诺 CLI，所以没有中间档。
+
+use crate::prelude::*;
+
+fn windows_info(major_minor: Option<(u32, u32)>) -> OsInfo {
+    let product = match major_minor {
+        Some(version) if version >= os_info::MIN_WINDOWS => "Windows 10",
+        Some(_) => "Windows 7",
+        None => "Windows",
+    };
+    OsInfo {
+        family: OsFamily::Windows,
+        arch: "x86_64".to_string(),
+        major_minor,
+        build: Some(19_045),
+        product: product.to_string(),
+        version_string: "10.0.19045".to_string(),
+        session: SessionKind::Unknown,
+        gl: GlProbe::Unknown,
+        vk: VkProbe::Unknown,
+        kernel: None,
+        glibc: None,
+        support_level: os_info::support_level_for(OsFamily::Windows, major_minor, None, None),
+    }
+}
+
+fn linux_info(kernel: Option<(u32, u32)>, glibc: Option<(u32, u32)>) -> OsInfo {
+    OsInfo {
+        family: OsFamily::Linux,
+        arch: "x86_64".to_string(),
+        major_minor: kernel,
+        build: None,
+        product: "Ubuntu 24.04.1 LTS".to_string(),
+        version_string: "6.8.0-45-generic".to_string(),
+        session: SessionKind::Wayland,
+        gl: GlProbe::Unknown,
+        vk: VkProbe::Unknown,
+        kernel,
+        glibc,
+        support_level: os_info::support_level_for(OsFamily::Linux, kernel, kernel, glibc),
+    }
+}
+
+#[test]
+fn windows_levels_require_windows_10() {
+    // Win10 / Win11（都报 10.0，靠 build 区分产品名）→ 一等。
+    assert_eq!(os_info::windows_level(Some((10, 0))), SupportLevel::One);
+    // Win8.1 / Win8 / Win7：低于基线，GUI 与 CLI 都不承诺。
+    assert_eq!(
+        os_info::windows_level(Some((6, 3))),
+        SupportLevel::Unsupported
+    );
+    assert_eq!(
+        os_info::windows_level(Some((6, 2))),
+        SupportLevel::Unsupported
+    );
+    assert_eq!(
+        os_info::windows_level(Some((6, 1))),
+        SupportLevel::Unsupported
+    );
+    // Vista / XP。
+    assert_eq!(
+        os_info::windows_level(Some((6, 0))),
+        SupportLevel::Unsupported
+    );
+    assert_eq!(
+        os_info::windows_level(Some((5, 1))),
+        SupportLevel::Unsupported
+    );
+    // 探测失败 → 保守（无法确认 Win10+ 就不放行）。
+    assert_eq!(os_info::windows_level(None), SupportLevel::Unsupported);
+}
+
+#[test]
+fn macos_levels_use_twelve_as_the_floor() {
+    assert_eq!(os_info::macos_level(Some(12)), SupportLevel::One);
+    assert_eq!(os_info::macos_level(Some(15)), SupportLevel::One);
+    assert_eq!(os_info::macos_level(Some(11)), SupportLevel::Unsupported);
+    assert_eq!(os_info::macos_level(None), SupportLevel::Unsupported);
+}
+
+#[test]
+fn linux_levels_gate_on_kernel_and_glibc() {
+    assert_eq!(
+        os_info::linux_level(Some((6, 8)), Some((2, 39))),
+        SupportLevel::One
+    );
+    assert_eq!(
+        os_info::linux_level(Some((2, 6)), Some((2, 39))),
+        SupportLevel::Unsupported
+    );
+    assert_eq!(
+        os_info::linux_level(Some((6, 8)), Some((2, 16))),
+        SupportLevel::Unsupported
+    );
+    // musl / Termux / 容器里取不到 glibc 与内核 → 不阻塞。
+    assert_eq!(os_info::linux_level(None, None), SupportLevel::One);
+    assert_eq!(os_info::linux_level(Some((3, 2)), None), SupportLevel::One);
+    // 恰好等于下限也算支持。
+    assert_eq!(
+        os_info::linux_level(Some((6, 8)), Some(os_info::MIN_GLIBC)),
+        SupportLevel::One
+    );
+}
+
+#[test]
+fn support_level_for_dispatches_by_family() {
+    assert_eq!(
+        os_info::support_level_for(OsFamily::Windows, Some((10, 0)), None, None),
+        SupportLevel::One
+    );
+    assert_eq!(
+        os_info::support_level_for(OsFamily::Windows, Some((6, 1)), None, None),
+        SupportLevel::Unsupported
+    );
+    assert_eq!(
+        os_info::support_level_for(OsFamily::MacOs, Some((12, 3)), None, None),
+        SupportLevel::One
+    );
+    assert_eq!(
+        os_info::support_level_for(OsFamily::MacOs, Some((11, 7)), None, None),
+        SupportLevel::Unsupported
+    );
+    // Linux 的 major_minor 不参与判定，看 kernel/glibc。
+    assert_eq!(
+        os_info::support_level_for(OsFamily::Linux, Some((10, 0)), Some((2, 6)), None),
+        SupportLevel::Unsupported
+    );
+    assert_eq!(
+        os_info::support_level_for(OsFamily::Linux, None, Some((6, 8)), Some((2, 39))),
+        SupportLevel::One
+    );
+}
+
+#[test]
+fn windows_7_is_reported_as_unsupported_with_the_new_baseline() {
+    let info = windows_info(Some((6, 1)));
+    assert_eq!(info.support_level, SupportLevel::Unsupported);
+    let text = info.describe();
+    assert!(text.zh.contains("不支持"), "zh: {}", text.zh);
+    assert!(text.zh.contains("Windows 10"), "zh: {}", text.zh);
+    // 不再有「受限模式 / HeadlessOnly」文案。
+    assert!(!text.zh.contains("受限模式"), "zh: {}", text.zh);
+    assert!(text.en.contains("Unsupported"), "en: {}", text.en);
+    assert!(text.en.contains("Windows 10 or newer"), "en: {}", text.en);
+    // combined() 是 CLI 打印形态：中文在前、英文在后。
+    let combined = text.combined();
+    let (zh, en) = combined.split_once('\n').expect("两行");
+    assert!(zh.contains("不支持"));
+    assert!(en.contains("Unsupported"));
+}
+
+#[test]
+fn unsupported_macos_and_linux_name_their_own_minimums() {
+    let mac = OsInfo {
+        family: OsFamily::MacOs,
+        arch: "arm64".to_string(),
+        major_minor: Some((11, 7)),
+        build: None,
+        product: "macOS 11.7.0 (arm64)".to_string(),
+        version_string: "11.7.0".to_string(),
+        session: SessionKind::Unknown,
+        gl: GlProbe::Unknown,
+        vk: VkProbe::Unknown,
+        kernel: None,
+        glibc: None,
+        support_level: SupportLevel::Unsupported,
+    };
+    let text = mac.describe();
+    assert!(text.zh.contains("macOS 12"), "zh: {}", text.zh);
+    assert!(text.en.contains("macOS 12"), "en: {}", text.en);
+    assert!(!text.zh.contains("Windows"), "zh: {}", text.zh);
+
+    let linux = linux_info(Some((2, 6)), None);
+    assert_eq!(linux.support_level, SupportLevel::Unsupported);
+    let text = linux.describe();
+    assert!(text.zh.contains("内核"), "zh: {}", text.zh);
+    assert!(text.en.contains("kernel"), "en: {}", text.en);
+}
+
+#[test]
+fn unknown_windows_version_is_unsupported_and_says_so() {
+    let info = windows_info(None);
+    assert_eq!(info.support_level, SupportLevel::Unsupported);
+    let text = info.describe();
+    assert!(text.zh.contains("未能探测到系统版本"), "zh: {}", text.zh);
+    assert!(text.zh.contains("Windows 10"), "zh: {}", text.zh);
+}
+
+#[test]
+fn supported_linux_without_display_adds_a_hint() {
+    let mut info = linux_info(Some((6, 8)), Some((2, 39)));
+    info.session = SessionKind::Headless;
+    let text = info.describe();
+    assert!(text.zh.contains("图形会话"), "zh: {}", text.zh);
+    assert!(text.en.contains("graphical session"), "en: {}", text.en);
+
+    // 有显示服务器时不加提示。
+    let text = linux_info(Some((6, 8)), Some((2, 39))).describe();
+    assert!(!text.zh.contains("图形会话"), "zh: {}", text.zh);
+}
+
+#[test]
+fn summary_line_carries_the_diagnostic_fields() {
+    let line = linux_info(Some((6, 8)), Some((2, 39))).summary_line();
+    assert!(line.contains("os=linux"), "{line}");
+    assert!(line.contains("version=6.8.0-45-generic"), "{line}");
+    assert!(line.contains("arch=x86_64"), "{line}");
+    assert!(line.contains("level=one"), "{line}");
+    assert!(line.contains("session=wayland"), "{line}");
+    assert!(line.contains("gl=unknown"), "{line}");
+    assert!(line.contains("vk=unknown"), "{line}");
+}
+
+#[test]
+fn summary_line_reports_the_vulkan_probe() {
+    let mut info = linux_info(Some((6, 8)), Some((2, 39)));
+    info.vk = VkProbe::LoaderOnly;
+    assert!(info.summary_line().contains("vk=loader_only"));
+    info.vk = VkProbe::Available;
+    assert!(info.summary_line().contains("vk=available"));
+    info.vk = VkProbe::Missing;
+    assert!(info.summary_line().contains("vk=missing"));
+}
+
+#[test]
+fn summary_line_marks_missing_version_as_unknown() {
+    let mut info = windows_info(None);
+    info.version_string = String::new();
+    let line = info.summary_line();
+    assert!(line.contains("version=unknown"), "{line}");
+    assert!(line.contains("level=unsupported"), "{line}");
+}
+
+#[test]
+fn support_level_helpers() {
+    assert_eq!(SupportLevel::One.as_str(), "one");
+    assert_eq!(SupportLevel::Unsupported.as_str(), "unsupported");
+    assert!(SupportLevel::One.is_usable());
+    assert!(!SupportLevel::Unsupported.is_usable());
+}
+
+#[test]
+fn os_family_facts_and_launch_reexport_are_the_same_type() {
+    // launch::platform 只是把 OsFamily 从 platform::os_info 再导出（避免两套枚举）。
+    let family: unlucky_core::platform::os_info::OsFamily = OsFamily::Windows;
+    assert_eq!(family, OsFamily::Windows);
+    assert_eq!(OsFamily::Windows.manifest_name(), "windows");
+    assert_eq!(OsFamily::MacOs.manifest_name(), "osx");
+    assert_eq!(OsFamily::Linux.manifest_name(), "linux");
+    assert!(!OsFamily::Windows.is_posix());
+    assert!(OsFamily::Linux.is_posix());
+    assert!(!OsFamily::current().manifest_arch().is_empty());
+    assert_eq!(
+        OsFamily::current().manifest_arch(),
+        OsFamily::Linux.manifest_arch()
+    );
+}
+
+#[test]
+fn detect_reports_the_host_it_runs_on() {
+    let info = os_info::detect();
+    // 家族与当前编译目标一致。
+    assert_eq!(info.family, OsFamily::current());
+    assert!(!info.arch.is_empty());
+    assert!(!info.product.is_empty());
+    // 缓存入口返回同一份事实。
+    let cached = os_info::current();
+    assert_eq!(cached, &info);
+    assert_eq!(cached.family, info.family);
+}
+
+#[test]
+fn windows_host_probes_a_real_version() {
+    if !cfg!(target_os = "windows") {
+        return;
+    }
+    let info = os_info::detect();
+    let (major, _minor) = info.major_minor.expect("Windows 上必须探到 major.minor");
+    assert!(major >= 6, "探到的版本不合理: {:?}", info.major_minor);
+    assert!(!info.os_version().is_empty(), "os_version 不能是空串");
+    assert!(info.build.is_some(), "Windows 上应有 build 号");
+    // 非 Windows 分支的事实不应泄漏进来。
+    assert!(info.kernel.is_none());
+    assert!(info.glibc.is_none());
+    assert_eq!(info.session, SessionKind::Unknown);
+}
+
+#[test]
+fn check_returns_level_message_and_os_info() {
+    let check: SupportCheck = os_info::check();
+    assert_eq!(check.level, os_info::current().support_level);
+    assert_eq!(check.is_usable(), check.level.is_usable());
+    assert!(check.message.contains('\n'), "文案应为中英双语多行");
+    assert_eq!(check.message, check.os.describe().combined());
+}
diff --git a/crates/core/tests/platform/prelude.rs b/crates/core/tests/platform/prelude.rs
new file mode 100644
index 0000000..f22c9ff
--- /dev/null
+++ b/crates/core/tests/platform/prelude.rs
@@ -0,0 +1,53 @@
+//! 测试共用设施（crate 名只出现在这里）。
+
+use std::path::PathBuf;
+
+pub use unlucky_core::launch::args_table::assemble;
+pub use unlucky_core::launch::argument::{ArgumentEntry, OsRule, Rule, RuleContext};
+pub use unlucky_core::launch::game_version::GameVersion;
+pub use unlucky_core::launch::platform::{OsFamily, PlatformCtx};
+pub use unlucky_core::launch::request::*;
+pub use unlucky_core::platform::linux_caps::{self, GlProbe, LinuxCaps, SessionKind};
+pub use unlucky_core::platform::macos_version::{self, MacOsVersion};
+pub use unlucky_core::platform::os_info::{self, OsInfo, SupportCheck, SupportLevel};
+pub use unlucky_core::platform::vk_probe::{
+    classify, count_icd_manifests, env_icd_path, ldconfig_has_libvulkan, loader_candidates,
+    probe_vk, registry_has_driver_entry, VkEvidence, VkProbe, ICD_DIRS, ICD_ENV_VARS,
+    VULKAN_DRIVERS_KEY,
+};
+pub use unlucky_core::platform::windows_version::{self, WindowsVersion};
+
+/// 一个最小可组装请求：现代清单，游戏参数由调用方给。
+pub fn request_with_game(game: Vec<ArgumentEntry>) -> LaunchRequest {
+    LaunchRequest {
+        instance: InstanceInfo {
+            id: "inst-1".to_string(),
+            name: "1.20.1".to_string(),
+            version: GameVersion::parse("1.20.1"),
+            version_type: "release".to_string(),
+        },
+        launcher: LauncherInfo {
+            name: "UnluckyLauncher".to_string(),
+            version: "0.1.0".to_string(),
+        },
+        java: JavaSelection::new("C:/java/bin/java.exe", 17, 64),
+        manifest: ManifestArgs {
+            main_class: Some("net.minecraft.client.main.Main".to_string()),
+            game,
+            ..ManifestArgs::default()
+        },
+        classpath: vec![PathBuf::from("C:/mc/libraries/a.jar")],
+        ..LaunchRequest::default()
+    }
+}
+
+/// 一条带 `rules.os.version` 的游戏参数项。
+pub fn version_ruled_entry(pattern: &str, value: &str) -> ArgumentEntry {
+    let mut rule = Rule::allow();
+    rule.os = Some(OsRule {
+        name: None,
+        arch: None,
+        version: Some(pattern.to_string()),
+    });
+    ArgumentEntry::ruled(vec![rule], [value])
+}
diff --git a/crates/core/tests/platform/rules_wiring.rs b/crates/core/tests/platform/rules_wiring.rs
new file mode 100644
index 0000000..7b592f3
--- /dev/null
+++ b/crates/core/tests/platform/rules_wiring.rs
@@ -0,0 +1,96 @@
+//! 接线：`rules.os.version` 用真实探测值求值（D19 §2 —— 之前 `os_version` 是空串，
+//! 带版本规则的参数项永远命中不了）。
+
+use crate::prelude::*;
+
+fn argv_of(entries: Vec<ArgumentEntry>, ctx: &PlatformCtx) -> Vec<String> {
+    let request = request_with_game(entries);
+    assemble(&request, ctx).expect("组装失败").argv().to_vec()
+}
+
+#[test]
+fn windows_10_rule_hits_with_detected_version() {
+    let ctx = PlatformCtx::new(OsFamily::Windows, "x86_64").with_os_version("10.0.19045");
+    let entries = vec![version_ruled_entry(r"^10\.", "--demo-windows10")];
+    let argv = argv_of(entries, &ctx);
+    assert!(
+        argv.iter().any(|arg| arg == "--demo-windows10"),
+        "argv 应包含带版本规则的参数: {argv:?}"
+    );
+}
+
+#[test]
+fn same_rule_misses_when_version_is_empty() {
+    // 空版本串是修复前的常态：规则求值走保守分支（不放参数）。
+    let ctx = PlatformCtx::new(OsFamily::Windows, "x86_64");
+    assert!(ctx.os_version.is_empty());
+    let entries = vec![version_ruled_entry(r"^10\.", "--demo-windows10")];
+    let argv = argv_of(entries, &ctx);
+    assert!(
+        !argv.iter().any(|arg| arg == "--demo-windows10"),
+        "空版本串不该命中: {argv:?}"
+    );
+}
+
+#[test]
+fn escaped_dot_patterns_match_real_versions() {
+    // `^10\.15` 是 macOS 上常见的写法：反转义后按 `10.15` 前缀比较。
+    let ctx = PlatformCtx::new(OsFamily::MacOs, "x86_64").with_os_version("10.15.7");
+    let entries = vec![version_ruled_entry(r"^10\.15", "--demo-catalina")];
+    let argv = argv_of(entries, &ctx);
+    assert!(argv.iter().any(|arg| arg == "--demo-catalina"), "{argv:?}");
+}
+
+#[test]
+fn regex_shaped_patterns_stay_conservative() {
+    let ctx = PlatformCtx::new(OsFamily::Windows, "x86_64").with_os_version("10.0.19045");
+    // 需要真正则的模式：宁可少加参数，也不猜。
+    let entries = vec![version_ruled_entry(r"^10\.[0-9]+", "--demo-regex")];
+    let argv = argv_of(entries, &ctx);
+    assert!(!argv.iter().any(|arg| arg == "--demo-regex"), "{argv:?}");
+}
+
+#[test]
+fn rule_context_uses_the_injected_version() {
+    let features = FeatureSet::default();
+    let entry = version_ruled_entry(r"^6\.1\.", "--demo-win7");
+    assert!(entry.applies(&RuleContext::new(
+        "windows", "x86_64", "6.1.7601", &features
+    )));
+    assert!(!entry.applies(&RuleContext::new(
+        "windows",
+        "x86_64",
+        "10.0.19045",
+        &features
+    )));
+    // 空版本串：任何版本规则都不命中。
+    assert!(!entry.applies(&RuleContext::new("windows", "x86_64", "", &features)));
+}
+
+#[test]
+fn platform_ctx_current_carries_the_probed_version() {
+    let ctx = PlatformCtx::current();
+    let info = os_info::current();
+    assert_eq!(ctx.os, info.family);
+    assert_eq!(ctx.arch, info.arch);
+    assert_eq!(ctx.os_version, info.os_version());
+    if cfg!(target_os = "windows") {
+        assert!(!ctx.os_version.is_empty(), "Windows 上版本串不能为空");
+        // 版本串应能被规则前缀匹配到（形如 10.0.19045）。
+        assert!(
+            ctx.os_version.starts_with(|c: char| c.is_ascii_digit()),
+            "版本串形态异常: {}",
+            ctx.os_version
+        );
+    }
+}
+
+#[test]
+fn default_matches_current() {
+    let ctx = PlatformCtx::default();
+    assert_eq!(ctx.os_version, PlatformCtx::current().os_version);
+    assert_eq!(
+        ctx.path_separator(),
+        PlatformCtx::current().path_separator()
+    );
+}
diff --git a/crates/core/tests/platform/theme_cases.rs b/crates/core/tests/platform/theme_cases.rs
new file mode 100644
index 0000000..6fc20c5
--- /dev/null
+++ b/crates/core/tests/platform/theme_cases.rs
@@ -0,0 +1,102 @@
+//! 系统主题探测的解析与判定（`core::platform::theme_probe`）。
+//!
+//! 解析函数跨平台编译，所以本用例在任意宿主上都能跑；真实探测只是把同一份解析套到
+//! `reg query` / `defaults` / `gsettings` 的输出上（`probe()` 的非确定性不进断言）。
+
+use unlucky_core::platform::theme_probe::{
+    self, parse_apps_use_light_theme, parse_gsettings_color_scheme, parse_gtk_theme,
+    parse_macos_interface_style, SystemTheme, WINDOWS_PERSONALIZE_KEY,
+};
+
+#[test]
+fn windows_registry_apps_use_light_theme_maps_dword() {
+    // 真实 `reg query` 输出（REG_DWORD 以 0x 十六进制打印）。
+    let light = "HKEY_CURRENT_USER\\Software\\Microsoft\\Windows\\CurrentVersion\\Themes\\Personalize\n    \
+                 AppsUseLightTheme    REG_DWORD    0x1\n    SystemUsesLightTheme    REG_DWORD    0x0\n";
+    assert_eq!(parse_apps_use_light_theme(light), Some(SystemTheme::Light));
+
+    let dark = "    AppsUseLightTheme    REG_DWORD    0x0\n";
+    assert_eq!(parse_apps_use_light_theme(dark), Some(SystemTheme::Dark));
+
+    // 十进制形式的输出（某些区域设置/工具会把 DWORD 打成十进制）。
+    assert_eq!(
+        parse_apps_use_light_theme("    AppsUseLightTheme    REG_DWORD    1"),
+        Some(SystemTheme::Light)
+    );
+
+    // 键不存在（老系统 / 被策略删掉）与别的值都不猜。
+    assert_eq!(parse_apps_use_light_theme(""), None);
+    assert_eq!(
+        parse_apps_use_light_theme("    SystemUsesLightTheme    REG_DWORD    0x0"),
+        None
+    );
+    assert_eq!(
+        parse_apps_use_light_theme("    AppsUseLightTheme    REG_SZ    yes"),
+        None
+    );
+}
+
+#[test]
+fn windows_key_points_at_personalize_hive() {
+    assert!(WINDOWS_PERSONALIZE_KEY.contains("Themes\\Personalize"));
+}
+
+#[test]
+fn macos_interface_style_maps_dark_and_empty() {
+    assert_eq!(
+        parse_macos_interface_style("Dark\n"),
+        Some(SystemTheme::Dark)
+    );
+    assert_eq!(
+        parse_macos_interface_style("Light\n"),
+        Some(SystemTheme::Light)
+    );
+    // 浅色时 `AppleInterfaceStyle` 键不存在，defaults 无输出。
+    assert_eq!(parse_macos_interface_style(""), None);
+}
+
+#[test]
+fn gsettings_color_scheme_prefers_explicit_preference() {
+    assert_eq!(
+        parse_gsettings_color_scheme("'prefer-dark'\n"),
+        Some(SystemTheme::Dark)
+    );
+    assert_eq!(
+        parse_gsettings_color_scheme("'prefer-light'\n"),
+        Some(SystemTheme::Light)
+    );
+    // `default` = 未表态，交给 gtk-theme 名字兜底。
+    assert_eq!(parse_gsettings_color_scheme("'default'\n"), None);
+}
+
+#[test]
+fn gtk_theme_name_falls_back_to_dark_suffix() {
+    assert_eq!(parse_gtk_theme("'Yaru-dark'\n"), Some(SystemTheme::Dark));
+    assert_eq!(parse_gtk_theme("'Adwaita-dark'\n"), Some(SystemTheme::Dark));
+    assert_eq!(parse_gtk_theme("'Yaru'\n"), Some(SystemTheme::Light));
+    assert_eq!(parse_gtk_theme("''\n"), None);
+}
+
+#[test]
+fn system_theme_tristate_contract() {
+    assert_eq!(SystemTheme::Light.is_dark(), Some(false));
+    assert_eq!(SystemTheme::Dark.is_dark(), Some(true));
+    assert_eq!(
+        SystemTheme::Unknown.is_dark(),
+        None,
+        "Unknown 必须让调用方自己决定回落（不假装浅色）"
+    );
+    assert_eq!(SystemTheme::Light.as_str(), "light");
+    assert_eq!(SystemTheme::Dark.as_str(), "dark");
+    assert_eq!(SystemTheme::Unknown.as_str(), "unknown");
+}
+
+#[test]
+fn probe_never_panics_and_reports_one_of_three_states() {
+    // 真实探测（Windows 读注册表，其余平台问 DE）；不断言具体值，只要求落在三态内。
+    let probed = theme_probe::probe();
+    assert!(matches!(
+        probed,
+        SystemTheme::Light | SystemTheme::Dark | SystemTheme::Unknown
+    ));
+}
diff --git a/crates/core/tests/platform/vk_cases.rs b/crates/core/tests/platform/vk_cases.rs
new file mode 100644
index 0000000..44c9ae3
--- /dev/null
+++ b/crates/core/tests/platform/vk_cases.rs
@@ -0,0 +1,240 @@
+//! Vulkan 能力探测（`platform::vk_probe`）的三平台注入样本。
+//!
+//! 全部用 [`VkEvidence`] 注入，不读真机、不起子进程：
+//! 三平台解析函数是纯函数且跨平台编译，任意宿主都能跑这几个用例。
+//!
+//! 关键语义（`research/05-mc-vulkan.md` §4.3 的真机证据）：
+//! **Windows 注册表 `HKLM\SOFTWARE\Khronos\Vulkan\Drivers` 缺失不等于没有 Vulkan**
+//! （实测机 Vulkan 1.3.217 可用但该键不存在），所以只能降级到 `LoaderOnly`，不能判 `Missing`。
+
+use std::path::PathBuf;
+
+use crate::prelude::*;
+
+#[test]
+fn windows_loader_without_registry_key_is_only_loader_only() {
+    // 真机证据的复刻：vulkan-1.dll 在，注册表键缺失 → 只能说「loader 在、驱动未确认」。
+    let probe = classify(VkEvidence::new(OsFamily::Windows, true, false));
+    assert_eq!(probe, VkProbe::LoaderOnly);
+    assert!(probe.has_loader());
+    assert!(!probe.is_missing(), "注册表缺失被误判成没有 Vulkan");
+    assert!(!probe.is_available(), "没有驱动信号不该承诺可用");
+}
+
+#[test]
+fn windows_loader_plus_registry_entry_is_available() {
+    assert_eq!(
+        classify(VkEvidence::new(OsFamily::Windows, true, true)),
+        VkProbe::Available
+    );
+}
+
+#[test]
+fn windows_without_loader_is_missing() {
+    assert_eq!(
+        classify(VkEvidence::new(OsFamily::Windows, false, true)),
+        VkProbe::Missing
+    );
+}
+
+#[test]
+fn linux_loader_with_icd_manifests_is_available() {
+    assert_eq!(
+        classify(VkEvidence::new(OsFamily::Linux, true, true)),
+        VkProbe::Available
+    );
+    // 只有 loader、没有 ICD 目录/环境变量：同样不否定（驱动可能由 loader 自寻）。
+    assert_eq!(
+        classify(VkEvidence::new(OsFamily::Linux, true, false)),
+        VkProbe::LoaderOnly
+    );
+    assert_eq!(
+        classify(VkEvidence::new(OsFamily::Linux, false, false)),
+        VkProbe::Missing
+    );
+}
+
+#[test]
+fn macos_molten_vk_needs_no_separate_icd_signal() {
+    // macOS 没有系统 Vulkan：MoltenVK 既是 loader 又是 ICD，没有 LoaderOnly 这一档。
+    assert_eq!(
+        classify(VkEvidence::new(OsFamily::MacOs, true, false)),
+        VkProbe::Available
+    );
+    assert_eq!(
+        classify(VkEvidence::new(OsFamily::MacOs, false, true)),
+        VkProbe::Missing
+    );
+}
+
+#[test]
+fn probe_names_are_stable_and_lower_snake() {
+    assert_eq!(VkProbe::Unknown.as_str(), "unknown");
+    assert_eq!(VkProbe::LoaderOnly.as_str(), "loader_only");
+    assert_eq!(VkProbe::Available.as_str(), "available");
+    assert_eq!(VkProbe::Missing.as_str(), "missing");
+    assert_eq!(VkProbe::default(), VkProbe::Unknown);
+    assert!(!VkProbe::Unknown.has_loader());
+}
+
+#[test]
+fn loader_candidates_cover_each_platform_signature() {
+    let windows = loader_candidates(OsFamily::Windows);
+    assert!(
+        windows
+            .iter()
+            .any(|path| path.ends_with("System32/vulkan-1.dll")
+                || path.ends_with(r"System32\vulkan-1.dll")),
+        "Windows 判据应是 System32\\vulkan-1.dll：{windows:?}"
+    );
+
+    let linux = loader_candidates(OsFamily::Linux);
+    assert!(
+        linux
+            .iter()
+            .any(|path| path.to_string_lossy().contains("libvulkan.so.1")),
+        "Linux 判据应含 libvulkan.so.1：{linux:?}"
+    );
+
+    let macos = loader_candidates(OsFamily::MacOs);
+    let macos_names = macos
+        .iter()
+        .map(|path| {
+            path.file_name()
+                .unwrap_or_default()
+                .to_string_lossy()
+                .into_owned()
+        })
+        .collect::<Vec<_>>();
+    assert!(
+        macos_names.iter().any(|name| name == "libvulkan.1.dylib"),
+        "macOS 判据应含 libvulkan.1.dylib：{macos_names:?}"
+    );
+    assert!(
+        macos_names.iter().any(|name| name == "libMoltenVK.dylib"),
+        "macOS 判据应含 MoltenVK：{macos_names:?}"
+    );
+}
+
+#[test]
+fn registry_query_output_is_parsed_for_driver_entries() {
+    // 键不存在：只有本地化错误行（中英各一例，真机输出）。
+    let missing_en =
+        "ERROR: The system was unable to find the specified registry key or value.\r\n";
+    let missing_zh = "\r\n错误: 系统找不到指定的注册表项或值。\r\n";
+    assert!(!registry_has_driver_entry(missing_en));
+    assert!(!registry_has_driver_entry(missing_zh));
+    assert!(!registry_has_driver_entry(""));
+}
+
+#[test]
+fn registry_query_real_format_is_recognised() {
+    // 真实 `reg query KEY`（不带 /s）格式，本机实测：
+    //   空行 → 键头行（顶格、完整 hive 名、无尾反斜杠）→ 缩进的值行
+    //   `    <值名>    REG_DWORD    0x0`
+    // Vulkan 的 ICD 注册是「值名 = manifest 绝对路径」，名字里可能有空格，所以列宽不定。
+    let present = "\r\n\
+HKEY_LOCAL_MACHINE\\SOFTWARE\\Khronos\\Vulkan\\Drivers\r\n    \
+C:\\Windows\\System32\\DriverStore\\FileRepository\\amdvlk64.inf_amd64_1b2c\\amdvlk64.json    REG_DWORD    0x0\r\n    \
+C:\\vendor a\\vk_vendor_a.json    REG_DWORD    0x0\r\n";
+    assert!(registry_has_driver_entry(present));
+
+    // 值可能是 REG_SZ（第三方 loader/层注册的写法）。
+    let reg_sz = "\r\nHKEY_LOCAL_MACHINE\\SOFTWARE\\Khronos\\Vulkan\\Drivers\r\n    \
+C:\\vendor\\vk.json    REG_SZ    \r\n";
+    assert!(registry_has_driver_entry(reg_sz));
+}
+
+#[test]
+fn registry_key_without_values_is_not_a_driver_signal() {
+    // 键存在但没有任何值项：只有键头行。
+    let header_only = "\r\nHKEY_LOCAL_MACHINE\\SOFTWARE\\Khronos\\Vulkan\\Drivers\r\n";
+    assert!(!registry_has_driver_entry(header_only));
+
+    // 键存在但只有子键（无 /s 时子键也缩进打印，且不带 REG_ 类型标记）。
+    let subkeys_only = "\r\n\
+HKEY_LOCAL_MACHINE\\SOFTWARE\\Khronos\\Vulkan\\Drivers\r\n    \
+LayerOne\r\n    LayerTwo\r\n";
+    assert!(!registry_has_driver_entry(subkeys_only));
+
+    // 键头是**别的**键时，其值行不能算数（防止把上层/邻居键的值当成 ICD 注册）。
+    let other_key = "\r\n\
+HKEY_LOCAL_MACHINE\\SOFTWARE\\Khronos\\Vulkan\r\n    \
+ImplicitLayers    REG_DWORD    0x0\r\n";
+    assert!(!registry_has_driver_entry(other_key));
+}
+
+#[test]
+fn ldconfig_output_is_parsed_for_the_loader() {
+    let with_loader =
+        "\tlibvulkan.so.1 (libc6,x86-64) => /usr/lib/x86_64-linux-gnu/libvulkan.so.1\n\
+\tlibvulkan.so (libc6,x86-64) => /usr/lib/x86_64-linux-gnu/libvulkan.so\n";
+    assert!(ldconfig_has_libvulkan(with_loader));
+    assert!(!ldconfig_has_libvulkan(
+        "\tlibGL.so.1 (libc6,x86-64) => /usr/lib/libGL.so.1\n"
+    ));
+}
+
+#[test]
+fn icd_env_prefers_the_legacy_variable_and_skips_blanks() {
+    let vars = |pairs: &'static [(&'static str, &'static str)]| {
+        env_icd_path(move |key| {
+            pairs
+                .iter()
+                .find(|(name, _)| *name == key)
+                .map(|(_, value)| (*value).to_string())
+        })
+    };
+    assert_eq!(
+        vars(&[("VK_ICD_FILENAMES", "/a/nvidia_icd.json")]).as_deref(),
+        Some("/a/nvidia_icd.json")
+    );
+    assert_eq!(
+        vars(&[("VK_DRIVER_FILES", "/b/intel_icd.json")]).as_deref(),
+        Some("/b/intel_icd.json")
+    );
+    // 旧名优先（两者都设时 Khronos loader 也是旧名优先）。
+    assert_eq!(
+        vars(&[
+            ("VK_ICD_FILENAMES", "/a/one.json"),
+            ("VK_DRIVER_FILES", "/b/two.json"),
+        ])
+        .as_deref(),
+        Some("/a/one.json")
+    );
+    // 空白值当作没设。
+    assert_eq!(vars(&[("VK_ICD_FILENAMES", "   ")]), None);
+    assert_eq!(vars(&[]), None);
+    assert_eq!(ICD_ENV_VARS.len(), 2);
+    assert_eq!(ICD_DIRS.len(), 3);
+    assert!(VULKAN_DRIVERS_KEY.contains("Khronos"));
+}
+
+#[test]
+fn icd_manifest_count_ignores_non_json_and_missing_dirs() {
+    let dir = temp_dir("vk-icd");
+    assert_eq!(count_icd_manifests(&dir), 0);
+    std::fs::write(dir.join("nvidia_icd.json"), "{}").expect("写 json");
+    std::fs::write(dir.join("intel_icd.json"), "{}").expect("写 json");
+    std::fs::write(dir.join("README"), "x").expect("写非 json");
+    assert_eq!(count_icd_manifests(&dir), 2);
+    assert_eq!(count_icd_manifests(&dir.join("nope")), 0);
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+#[test]
+fn probe_vk_on_this_host_is_not_unknown() {
+    // 真探一次：只断言「给了确定结论」（本机有没有 Vulkan 都合法，不许恒 Unknown）。
+    assert_ne!(probe_vk(), VkProbe::Unknown);
+}
+
+/// 唯一临时目录（不引 tempfile 依赖）。
+fn temp_dir(tag: &str) -> PathBuf {
+    use std::sync::atomic::{AtomicU32, Ordering};
+    static COUNTER: AtomicU32 = AtomicU32::new(0);
+    let index = COUNTER.fetch_add(1, Ordering::Relaxed);
+    let dir = std::env::temp_dir().join(format!("ull-vk-{tag}-{}-{index}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).expect("创建临时目录");
+    dir
+}
diff --git a/crates/core/tests/platform/windows_version_cases.rs b/crates/core/tests/platform/windows_version_cases.rs
new file mode 100644
index 0000000..0a91068
--- /dev/null
+++ b/crates/core/tests/platform/windows_version_cases.rs
@@ -0,0 +1,179 @@
+//! Windows 版本探测：注册表 / `ver` 输出的解析 + 本机真实探测。
+
+use crate::prelude::*;
+
+/// Win11（`CurrentMajorVersionNumber` 是 REG_DWORD，`reg query` 输出 0x..）。
+const WIN11_REG: &str = "\
+HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion
+    CurrentBuildNumber    REG_SZ    22631
+    CurrentMajorVersionNumber    REG_DWORD    0xa
+    CurrentMinorVersionNumber    REG_DWORD    0x0
+    CurrentVersion    REG_SZ    6.3
+    ProductName    REG_SZ    Windows 10 Pro
+";
+
+/// Win10：数字键存在，`CurrentVersion` 是过期的 6.3，不能拿它当版本。
+const WIN10_REG: &str = "\
+HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion
+    CurrentBuildNumber    REG_SZ    19045
+    CurrentMajorVersionNumber    REG_DWORD    0xa
+    CurrentMinorVersionNumber    REG_DWORD    0x0
+    CurrentVersion    REG_SZ    6.3
+";
+
+/// Win7：没有数字键，只有 `CurrentVersion` 字符串（`CurrentBuildNumber` Win7 也有）。
+const WIN7_REG: &str = "\
+HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion
+    CurrentBuildNumber    REG_SZ    7601
+    CurrentVersion    REG_SZ    6.1
+    ProductName    REG_SZ    Windows 7 Ultimate
+";
+
+#[test]
+fn reg_query_parses_windows_11() {
+    let version = windows_version::parse_reg_query(WIN11_REG).expect("解析失败");
+    assert_eq!(version, WindowsVersion::new(10, 0, 22631));
+    assert_eq!(version.version_string(), "10.0.22631");
+    assert_eq!(version.display_name(), "Windows 11");
+}
+
+#[test]
+fn reg_query_prefers_numeric_keys_over_stale_current_version() {
+    let version = windows_version::parse_reg_query(WIN10_REG).expect("解析失败");
+    assert_eq!(version, WindowsVersion::new(10, 0, 19045));
+    assert_eq!(version.display_name(), "Windows 10");
+}
+
+#[test]
+fn reg_query_falls_back_to_current_version_on_windows_7() {
+    let version = windows_version::parse_reg_query(WIN7_REG).expect("解析失败");
+    assert_eq!(version, WindowsVersion::new(6, 1, 7601));
+    assert_eq!(version.major_minor(), (6, 1));
+    assert_eq!(version.display_name(), "Windows 7");
+}
+
+#[test]
+fn reg_query_without_build_number_is_unparsable() {
+    let text = "    CurrentVersion    REG_SZ    6.1\n";
+    assert_eq!(windows_version::parse_reg_query(text), None);
+    // 空输出（reg 不可用 / 被策略禁用）也不能崩。
+    assert_eq!(windows_version::parse_reg_query(""), None);
+    assert_eq!(
+        windows_version::parse_reg_query("ERROR: 找不到指定的注册表项"),
+        None
+    );
+}
+
+#[test]
+fn ver_output_parses_english_and_chinese() {
+    let english =
+        windows_version::parse_ver_output("Microsoft Windows [Version 10.0.19045.4046]\r\n")
+            .expect("解析失败");
+    assert_eq!(english, WindowsVersion::new(10, 0, 19045));
+
+    let chinese = windows_version::parse_ver_output(
+        "Microsoft Windows [\u{7248}\u{672c} 10.0.19045.4046]\r\n",
+    )
+    .expect("解析失败");
+    assert_eq!(chinese, english);
+
+    let win7 = windows_version::parse_ver_output("Microsoft Windows [Version 6.1.7601]")
+        .expect("解析失败");
+    assert_eq!(win7, WindowsVersion::new(6, 1, 7601));
+    assert_eq!(win7.display_name(), "Windows 7");
+}
+
+#[test]
+fn ver_output_rejects_garbage() {
+    assert_eq!(windows_version::parse_ver_output(""), None);
+    assert_eq!(windows_version::parse_ver_output("no brackets here"), None);
+    assert_eq!(
+        windows_version::parse_ver_output("Microsoft Windows [Version ]"),
+        None
+    );
+}
+
+#[test]
+fn build_number_maps_to_version_families() {
+    // 快路径：单值查询只给 build，major.minor 由 build 族反推。
+    assert_eq!(
+        windows_version::from_build(7601),
+        Some(WindowsVersion::new(6, 1, 7601))
+    );
+    assert_eq!(
+        windows_version::from_build(9200).map(|v| v.major_minor()),
+        Some((6, 2))
+    );
+    assert_eq!(
+        windows_version::from_build(9600).map(|v| v.major_minor()),
+        Some((6, 3))
+    );
+    assert_eq!(
+        windows_version::from_build(19045).map(|v| v.major_minor()),
+        Some((10, 0))
+    );
+    assert_eq!(
+        windows_version::from_build(22631).map(|v| v.display_name()),
+        Some("Windows 11")
+    );
+    assert_eq!(
+        windows_version::from_build(26100).map(|v| v.major_minor()),
+        Some((10, 0))
+    );
+    // Vista 之前不猜：交给整键/`ver` 解析兜底。
+    assert_eq!(windows_version::from_build(3790), None);
+    assert_eq!(windows_version::from_build(0), None);
+}
+
+#[test]
+fn single_value_query_yields_build_number() {
+    let text = "\
+HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion
+    CurrentBuildNumber    REG_SZ    26100
+";
+    assert_eq!(windows_version::parse_build_number(text), Some(26100));
+    assert_eq!(
+        windows_version::parse_build_number("ERROR: \u{627e}\u{4e0d}\u{5230}\u{6307}\u{5b9a}\u{7684}\u{6ce8}\u{518c}\u{8868}\u{9879}"),
+        None
+    );
+    assert_eq!(windows_version::parse_build_number(""), None);
+}
+
+#[test]
+fn display_name_covers_the_matrix() {
+    assert_eq!(
+        WindowsVersion::new(10, 0, 22_000).display_name(),
+        "Windows 11"
+    );
+    assert_eq!(
+        WindowsVersion::new(10, 0, 21_999).display_name(),
+        "Windows 10"
+    );
+    assert_eq!(
+        WindowsVersion::new(6, 3, 9600).display_name(),
+        "Windows 8.1"
+    );
+    assert_eq!(WindowsVersion::new(6, 2, 9200).display_name(), "Windows 8");
+    assert_eq!(WindowsVersion::new(6, 1, 7601).display_name(), "Windows 7");
+    assert_eq!(
+        WindowsVersion::new(6, 0, 6002).display_name(),
+        "Windows Vista"
+    );
+    assert_eq!(WindowsVersion::new(5, 1, 2600).display_name(), "Windows XP");
+}
+
+#[test]
+fn probe_matches_the_host() {
+    let probed = windows_version::probe();
+    if cfg!(target_os = "windows") {
+        let version = probed.expect("Windows 宿主必须能探到真实版本");
+        // 真实的 Windows 至少是 6.x（XP 是 5.x，不会被这个仓库支持）。
+        assert!(version.major >= 6, "探到 {version:?}");
+        assert!(!version.display_name().is_empty());
+        // 重新探一次结果稳定（reg 与 ver 两条路径应给同一个 major.minor）。
+        let again = windows_version::probe().expect("二次探测失败");
+        assert_eq!(again.major_minor(), version.major_minor());
+    } else {
+        assert!(probed.is_none(), "非 Windows 平台不应探到 Windows 版本");
+    }
+}
diff --git a/crates/core/tests/setting/appearance_keys.rs b/crates/core/tests/setting/appearance_keys.rs
new file mode 100644
index 0000000..c235bd9
--- /dev/null
+++ b/crates/core/tests/setting/appearance_keys.rs
@@ -0,0 +1,204 @@
+//! 「外观（高级）」键簇（`setting::appearance` + `keys::launcher_schema` 的 appearance.* 段）。
+//!
+//! 守三条设计约束（09-ui-layout §111）：
+//! 1. 一切高级特性**默认关闭**（出厂 Metro 纯色）——默认值即出厂态；
+//! 2. 全部走 D6 schema 且 **AI 可写**（白名单内，可被 agent 调节）；
+//! 3. 值域有硬边界（滑条夹取），坏值/手改配置不崩（回落默认）。
+
+use serde_json::json;
+use unlucky_core::setting::appearance::{
+    hex_to_rgb, normalize_hex, relative_luminance, Appearance, BgFill, DEFAULT_ACCENT,
+    PANEL_ALPHA_MIN,
+};
+use unlucky_core::setting::document::SettingDocument;
+use unlucky_core::setting::keys::{launcher_schema, launcher_version};
+use unlucky_core::setting::spec::ValueKind;
+
+fn doc(raw: serde_json::Value) -> SettingDocument {
+    SettingDocument::load(&launcher_schema(), &raw).0
+}
+
+#[test]
+fn factory_defaults_are_all_advanced_features_off() {
+    let appearance = Appearance::from_store(&unlucky_core::setting::store::SettingStore::load(
+        std::env::temp_dir().join(format!("ull-appearance-none-{}.json", std::process::id())),
+        launcher_schema(),
+    ));
+    assert_eq!(appearance.theme_mode, "auto", "D17：出厂跟随系统");
+    assert!(!appearance.bg_image_enabled, "背景图默认关");
+    assert!(!appearance.bg_image_active());
+    assert_eq!(appearance.bg_fill, BgFill::Cover);
+    assert_eq!(appearance.panel_alpha, 1.0, "出厂完全不透明（Metro 纯色）");
+    assert!(!appearance.glass, "玻璃拟态默认关");
+    assert_eq!(appearance.accent_color, "", "空串 = 未自定义");
+    assert_eq!(appearance.accent_or_default(), DEFAULT_ACCENT);
+}
+
+#[test]
+fn reading_a_configured_document_reflects_each_key() {
+    let document = doc(json!({
+        "appearance": {
+            "theme_mode": "dark",
+            "bg_image_enabled": true,
+            "bg_image": "D:/wall/paper.png",
+            "bg_fill": "tile",
+            "bg_dim": 0.6,
+            "panel_alpha": 0.8,
+            "glass": true,
+            "accent_color": "#ff5722",
+        }
+    }));
+    let appearance = Appearance::read(&document);
+    assert_eq!(appearance.theme_mode, "dark");
+    assert!(appearance.bg_image_active());
+    assert_eq!(appearance.bg_image, "D:/wall/paper.png");
+    assert_eq!(appearance.bg_fill, BgFill::Tile);
+    assert!((appearance.bg_dim - 0.6).abs() < 1e-9);
+    assert!((appearance.panel_alpha - 0.8).abs() < 1e-9);
+    assert!(appearance.glass);
+    assert_eq!(appearance.accent_color, "#FF5722", "读入即规范化大写");
+    assert_eq!(appearance.accent_or_default(), "#FF5722");
+}
+
+#[test]
+fn bad_values_fall_back_instead_of_panicking() {
+    // 手改坏的配置：枚举拼错 / 开关类型错 / accent 不是 #RRGGBB。
+    let document = doc(json!({
+        "appearance": {
+            "bg_fill": "stretch",
+            "bg_image_enabled": "yes",
+            "accent_color": "rebeccapurple",
+        }
+    }));
+    let appearance = Appearance::read(&document);
+    assert_eq!(appearance.bg_fill, BgFill::Cover);
+    assert!(!appearance.bg_image_enabled);
+    assert_eq!(appearance.accent_color, "");
+    assert_eq!(appearance.accent_or_default(), DEFAULT_ACCENT);
+}
+
+#[test]
+fn panel_alpha_is_clamped_to_the_contrast_floor() {
+    // schema 下限 0.4；读侧再夹一次（挡手改文件绕过 schema 的情况）。
+    let document = doc(json!({ "appearance": { "panel_alpha": 0.05 } }));
+    assert!((Appearance::read(&document).panel_alpha - PANEL_ALPHA_MIN).abs() < 1e-9);
+}
+
+#[test]
+fn appearance_keys_are_all_ai_writable_and_registered() {
+    let schema = launcher_schema();
+    // 主题三态是 D17 已定案的最轻量键（silent/Low），其余高级键留审计痕迹（audited/Medium）。
+    let audited_keys = [
+        "appearance.bg_image_enabled",
+        "appearance.bg_image",
+        "appearance.bg_fill",
+        "appearance.bg_dim",
+        "appearance.panel_alpha",
+        "appearance.glass",
+        "appearance.accent_color",
+        // M91（D36/D37/D38）的外观下层三键，同样 audited。
+        "appearance.window_opacity",
+        "appearance.titlebar_mode",
+        "appearance.palette_source",
+    ];
+    for key in audited_keys {
+        let spec = schema.spec(key).unwrap_or_else(|| panic!("{key} 必须登记"));
+        assert!(spec.ai.writable, "{key} 必须在 AI 可写白名单内");
+        // 纯视觉、可一键复原 → 不要求弹窗确认（High 级留给凭据/数据根/代理）。
+        assert!(
+            !spec.ai.sensitivity.requires_confirmation(),
+            "{key} 不该要确认"
+        );
+        assert_eq!(
+            spec.ai.sensitivity.as_str(),
+            "medium",
+            "{key} 要留审计痕迹（AI 改过什么可回看）"
+        );
+    }
+    // 主题三态仍是 silent（D17 已定案的最轻量键）。
+    assert_eq!(
+        schema
+            .spec("appearance.theme_mode")
+            .unwrap()
+            .ai
+            .sensitivity
+            .as_str(),
+        "low"
+    );
+}
+
+#[test]
+fn schema_registration_shape_is_right() {
+    assert_eq!(
+        launcher_version().minor,
+        5,
+        "1.5.0 登记 M116 的窗口圆角策略键"
+    );
+    let schema = launcher_schema();
+    assert_eq!(
+        schema.spec("appearance.bg_fill").unwrap().kind,
+        ValueKind::Enum(&["cover", "contain", "tile"])
+    );
+    assert!(matches!(
+        schema.spec("appearance.panel_alpha").unwrap().kind,
+        ValueKind::Float { min, max } if (min - PANEL_ALPHA_MIN).abs() < 1e-9 && (max - 1.0).abs() < 1e-9
+    ));
+    assert_eq!(
+        schema.spec("appearance.accent_color").unwrap().kind,
+        ValueKind::Text { max_len: 9 },
+        "#RRGGBB 最多 7 字符，留 9 容错带井号与空白"
+    );
+    // 默认值 = 出厂态
+    assert_eq!(
+        schema.spec("appearance.panel_alpha").unwrap().default,
+        serde_json::Value::from(1.0)
+    );
+    assert_eq!(
+        schema.spec("appearance.glass").unwrap().default,
+        serde_json::Value::from(false)
+    );
+}
+
+#[test]
+fn write_round_trips_through_the_store() {
+    let temp =
+        std::env::temp_dir().join(format!("ull-appearance-{}-{}", std::process::id(), line!()));
+    std::fs::create_dir_all(temp.join("config")).expect("临时目录");
+    let path = temp.join("config/launcher.json");
+    let _ = std::fs::remove_file(&path);
+
+    let mut store = unlucky_core::setting::store::SettingStore::load(&path, launcher_schema());
+    let mut appearance = Appearance::from_store(&store);
+    appearance.theme_mode = "dark".to_owned();
+    appearance.panel_alpha = 0.8;
+    appearance.bg_image_enabled = true;
+    appearance.bg_image = "D:/wall/p.png".to_owned();
+    appearance.accent_color = "#0f6cbd".to_owned();
+    appearance.write(&mut store).expect("写外观键");
+    store.save().expect("落盘");
+
+    let reloaded = Appearance::from_store(&unlucky_core::setting::store::SettingStore::load(
+        &path,
+        launcher_schema(),
+    ));
+    assert_eq!(reloaded.theme_mode, "dark");
+    assert!((reloaded.panel_alpha - 0.8).abs() < 1e-9);
+    assert!(reloaded.bg_image_active());
+    assert_eq!(reloaded.accent_color, "#0F6CBD");
+
+    std::fs::remove_dir_all(&temp).ok();
+}
+
+#[test]
+fn hex_helpers_validate_and_convert() {
+    assert_eq!(normalize_hex(" 0f6cbd "), Some("#0F6CBD".to_owned()));
+    assert_eq!(normalize_hex("#0F6CBD"), Some("#0F6CBD".to_owned()));
+    assert_eq!(normalize_hex("#0F6CB"), None);
+    assert_eq!(normalize_hex("#GGGGGG"), None);
+    assert_eq!(hex_to_rgb("#0078D4"), Some((0x00, 0x78, 0xD4)));
+    // WCAG 相对亮度：纯黑 0、纯白 1、Metro 蓝居中偏暗。
+    assert!(relative_luminance("#000000").unwrap().abs() < 1e-9);
+    assert!((relative_luminance("#FFFFFF").unwrap() - 1.0).abs() < 1e-9);
+    let metro = relative_luminance(DEFAULT_ACCENT).unwrap();
+    assert!(metro > 0.05 && metro < 0.3, "Metro 蓝亮度 {metro}");
+}
diff --git a/crates/core/tests/setting/atomic_write.rs b/crates/core/tests/setting/atomic_write.rs
new file mode 100644
index 0000000..bd39df2
--- /dev/null
+++ b/crates/core/tests/setting/atomic_write.rs
@@ -0,0 +1,49 @@
+//! 原子写：覆盖语义、父目录创建、不留临时文件、可选读。
+
+use unlucky_core::platform::atomic::{read_optional, tmp_path, write_atomic};
+
+use crate::common::{dir_entries, TempDir};
+
+#[test]
+fn writes_and_replaces_in_place() {
+    let temp = TempDir::new("atomic");
+    let path = temp.child("config/launcher.json");
+
+    write_atomic(&path, b"{\"a\":1}").expect("首次写");
+    assert_eq!(temp.read("config/launcher.json"), "{\"a\":1}");
+
+    write_atomic(&path, b"{\"a\":2}").expect("覆盖写");
+    assert_eq!(temp.read("config/launcher.json"), "{\"a\":2}");
+
+    // 目录里只该有目标文件，临时文件必须被改名掉。
+    assert_eq!(dir_entries(&temp.child("config")), vec!["launcher.json"]);
+}
+
+#[test]
+fn read_optional_distinguishes_missing_from_failure() {
+    let temp = TempDir::new("atomic-read");
+    let path = temp.child("nope.json");
+    assert!(read_optional(&path).expect("读缺失文件").is_none());
+
+    temp.write("here.json", "内容");
+    let bytes = read_optional(&temp.child("here.json"))
+        .expect("读文件")
+        .expect("有内容");
+    assert_eq!(bytes, "内容".as_bytes());
+}
+
+#[test]
+fn tmp_name_stays_in_same_directory() {
+    let temp = TempDir::new("atomic-tmp");
+    let path = temp.child("config/profiles.json");
+    let tmp = tmp_path(&path);
+    assert_eq!(
+        tmp.parent(),
+        path.parent(),
+        "临时文件必须同目录（rename 才原子）"
+    );
+    assert_ne!(tmp, path);
+    let first = tmp_path(&path);
+    let second = tmp_path(&path);
+    assert_ne!(first, second, "并发写要能拿到不同的临时名");
+}
diff --git a/crates/core/tests/setting/common.rs b/crates/core/tests/setting/common.rs
new file mode 100644
index 0000000..4975416
--- /dev/null
+++ b/crates/core/tests/setting/common.rs
@@ -0,0 +1,81 @@
+//! 测试公用小工具（临时目录 + 文件读写）。
+//!
+//! 不引 `tempfile`：M11 的依赖面只有 serde/serde_json，测试自己管临时目录。
+
+#![allow(dead_code)]
+
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+
+static COUNTER: AtomicU64 = AtomicU64::new(0);
+
+/// 进程内唯一的临时目录，`Drop` 时递归删除。
+pub struct TempDir {
+    path: PathBuf,
+}
+
+impl TempDir {
+    /// 建一个临时目录。
+    pub fn new(label: &str) -> Self {
+        let index = COUNTER.fetch_add(1, Ordering::Relaxed);
+        let path = std::env::temp_dir().join(format!(
+            "ull-setting-{label}-{}-{index}",
+            std::process::id()
+        ));
+        std::fs::remove_dir_all(&path).ok();
+        std::fs::create_dir_all(&path).expect("创建临时目录");
+        Self { path }
+    }
+
+    /// 根路径。
+    pub fn path(&self) -> &Path {
+        &self.path
+    }
+
+    /// 拼接子路径（不创建）。
+    pub fn child(&self, name: &str) -> PathBuf {
+        self.path.join(name)
+    }
+
+    /// 写一个文件（自动建父目录）。
+    pub fn write(&self, name: &str, contents: &str) -> PathBuf {
+        let path = self.child(name);
+        if let Some(parent) = path.parent() {
+            std::fs::create_dir_all(parent).expect("创建父目录");
+        }
+        std::fs::write(&path, contents).expect("写文件");
+        path
+    }
+
+    /// 读一个文件。
+    pub fn read(&self, name: &str) -> String {
+        std::fs::read_to_string(self.child(name)).expect("读文件")
+    }
+
+    /// 子路径是否存在。
+    pub fn exists(&self, name: &str) -> bool {
+        self.child(name).exists()
+    }
+}
+
+impl Drop for TempDir {
+    fn drop(&mut self) {
+        std::fs::remove_dir_all(&self.path).ok();
+    }
+}
+
+/// 目录里的文件名（排序后返回，便于断言没留下临时文件）。
+pub fn dir_entries(dir: &Path) -> Vec<String> {
+    let mut names: Vec<String> = std::fs::read_dir(dir)
+        .expect("读目录")
+        .map(|entry| {
+            entry
+                .expect("目录项")
+                .file_name()
+                .to_string_lossy()
+                .into_owned()
+        })
+        .collect();
+    names.sort();
+    names
+}
diff --git a/crates/core/tests/setting/debounce.rs b/crates/core/tests/setting/debounce.rs
new file mode 100644
index 0000000..be91d1c
--- /dev/null
+++ b/crates/core/tests/setting/debounce.rs
@@ -0,0 +1,128 @@
+//! 保存通道：200ms 去抖、同路径覆盖、攒批落盘、后台线程 flush/关停。
+
+use std::path::{Path, PathBuf};
+use std::sync::{Arc, Mutex};
+use std::time::{Duration, Instant};
+
+use unlucky_core::setting::error::SettingResult;
+use unlucky_core::setting::save::{CoalescingWriter, DebounceQueue, JobSink, DEFAULT_DEBOUNCE};
+use unlucky_core::setting::save_worker::SaveWorker;
+
+use crate::common::TempDir;
+
+/// 记录下来的 (路径, 内容) 列表。
+type Written = Vec<(PathBuf, Vec<u8>)>;
+
+#[derive(Clone, Default)]
+struct RecordingSink {
+    written: Arc<Mutex<Written>>,
+}
+
+impl RecordingSink {
+    fn entries(&self) -> Vec<(PathBuf, Vec<u8>)> {
+        self.written.lock().expect("锁").clone()
+    }
+}
+
+impl JobSink for RecordingSink {
+    fn write(&self, path: &Path, payload: &[u8]) -> SettingResult<()> {
+        self.written
+            .lock()
+            .expect("锁")
+            .push((path.to_path_buf(), payload.to_vec()));
+        Ok(())
+    }
+}
+
+#[test]
+fn default_debounce_is_200ms() {
+    assert_eq!(DEFAULT_DEBOUNCE, Duration::from_millis(200));
+}
+
+#[test]
+fn waits_for_the_window_before_writing() {
+    let start = Instant::now();
+    let mut queue = DebounceQueue::<String>::new(DEFAULT_DEBOUNCE);
+    assert!(queue.is_empty());
+
+    queue.enqueue("a".to_owned(), b"1".to_vec(), start);
+    queue.enqueue("b".to_owned(), b"2".to_vec(), start);
+    assert_eq!(queue.len(), 2);
+    assert!(queue.contains(&"a".to_owned()));
+    assert_eq!(queue.next_due(), Some(start + DEFAULT_DEBOUNCE));
+
+    assert!(queue
+        .drain_due(start + Duration::from_millis(100))
+        .is_empty());
+    let due = queue.drain_due(start + DEFAULT_DEBOUNCE);
+    assert_eq!(due.len(), 2);
+    assert_eq!(due[0].0, "a", "同一批按键排序，写盘顺序稳定");
+    assert!(queue.is_empty());
+}
+
+#[test]
+fn same_key_collapses_and_keeps_first_deadline() {
+    let start = Instant::now();
+    let mut queue = DebounceQueue::<String>::new(DEFAULT_DEBOUNCE);
+    queue.enqueue("a".to_owned(), b"1".to_vec(), start);
+    queue.enqueue(
+        "a".to_owned(),
+        b"2".to_vec(),
+        start + Duration::from_millis(150),
+    );
+
+    assert_eq!(queue.len(), 1);
+    assert_eq!(
+        queue.next_due(),
+        Some(start + DEFAULT_DEBOUNCE),
+        "窗口从首次改动开始算，避免连续改动无限推迟写盘"
+    );
+    assert_eq!(
+        queue.drain_due(start + DEFAULT_DEBOUNCE),
+        vec![("a".to_owned(), b"2".to_vec())]
+    );
+}
+
+#[test]
+fn coalescing_writer_batches_into_one_flush() {
+    let sink = RecordingSink::default();
+    let mut writer = CoalescingWriter::new(sink.clone(), DEFAULT_DEBOUNCE);
+    let start = Instant::now();
+
+    writer.queue("/tmp/a.json", b"1".to_vec(), start);
+    writer.queue(
+        "/tmp/a.json",
+        b"2".to_vec(),
+        start + Duration::from_millis(50),
+    );
+    writer.queue("/tmp/b.json", b"3".to_vec(), start);
+    assert_eq!(writer.pending_len(), 2);
+    assert!(!writer.is_empty());
+
+    assert_eq!(writer.flush_due(start).expect("未到窗口"), 0);
+    assert_eq!(
+        writer.flush_due(start + DEFAULT_DEBOUNCE).expect("到窗口"),
+        2
+    );
+    assert!(writer.is_empty());
+    assert_eq!(writer.flush_all().expect("空队列兜底"), 0);
+
+    let written = sink.entries();
+    assert_eq!(written.len(), 2);
+    assert_eq!(written[0].0, PathBuf::from("/tmp/a.json"));
+    assert_eq!(written[0].1, b"2".to_vec(), "只写最新内容");
+}
+
+#[test]
+fn save_worker_flushes_and_shuts_down() {
+    let temp = TempDir::new("save-worker");
+    let target = temp.child("config/launcher.json");
+    let mut worker = SaveWorker::spawn(Duration::from_millis(30)).expect("起线程");
+
+    worker.queue(&target, b"{\"a\":1}").expect("入队");
+    worker.queue(&target, b"{\"a\":2}").expect("入队");
+    worker.flush().expect("同步落盘");
+
+    assert_eq!(temp.read("config/launcher.json"), "{\"a\":2}");
+    worker.shutdown().expect("关停");
+}
diff --git a/crates/core/tests/setting/deprecated_keys.rs b/crates/core/tests/setting/deprecated_keys.rs
new file mode 100644
index 0000000..69845a7
--- /dev/null
+++ b/crates/core/tests/setting/deprecated_keys.rs
@@ -0,0 +1,142 @@
+//! 键废弃机制：`ui.theme` → `appearance.theme_mode`（tower 键冲突裁决）。
+//!
+//! 规则：**读兼容**（旧值按 `THEME_ALIASES` 映射，新键已在则新键优先）+ **写永远走新键**
+//! （`set` 旧键直接报错，落盘不含旧键，AI 白名单与工具 JSON Schema 也不含旧键）。
+
+use serde_json::{json, Value};
+use unlucky_core::setting::document::{LoadProblem, SettingDocument};
+use unlucky_core::setting::keys::{launcher_schema, LEGACY_THEMES, THEME_ALIASES, THEME_MODES};
+use unlucky_core::setting::schema::{SchemaId, SchemaRef, SchemaVersion, SCHEMA_KEY};
+use unlucky_core::setting::store::SettingStore;
+
+use crate::common::TempDir;
+
+fn legacy_file(raw_ui: Value) -> Value {
+    json!({
+        SCHEMA_KEY: SchemaRef::new(SchemaId::LAUNCHER, SchemaVersion::new(1, 0, 0)).url(),
+        "ui": raw_ui
+    })
+}
+
+fn deprecated_problem(problems: &[LoadProblem]) -> Option<&'static str> {
+    problems.iter().find_map(|problem| match problem {
+        LoadProblem::DeprecatedKey {
+            key, replaced_by, ..
+        } if key == "ui.theme" => Some(*replaced_by),
+        _ => None,
+    })
+}
+
+#[test]
+fn legacy_theme_values_are_translated_on_read() {
+    assert_eq!(THEME_MODES.len(), 3);
+    assert!(THEME_MODES.contains(&"auto") && THEME_MODES.contains(&"light"));
+    assert!(THEME_MODES.contains(&"dark"));
+    assert_eq!(
+        LEGACY_THEMES.len(),
+        THEME_ALIASES.len(),
+        "三个旧值都要有映射"
+    );
+
+    for (legacy, expected) in [
+        ("system", "auto"),
+        ("metro_light", "light"),
+        ("metro_dark", "dark"),
+    ] {
+        let (doc, problems) =
+            SettingDocument::load(&launcher_schema(), &legacy_file(json!({ "theme": legacy })));
+
+        assert_eq!(
+            doc.effective_str("appearance.theme_mode"),
+            Some(expected),
+            "旧值 {legacy} 应映射成 {expected}"
+        );
+        assert_eq!(
+            doc.legacy_value("ui.theme").and_then(Value::as_str),
+            Some(legacy),
+            "旧键原文要留着给 UI 提示/回滚"
+        );
+        assert_eq!(deprecated_problem(&problems), Some("appearance.theme_mode"));
+        assert!(!doc.is_dirty(), "读兼容不算用户改动");
+    }
+}
+
+#[test]
+fn new_key_wins_when_both_present() {
+    let raw = json!({
+        SCHEMA_KEY: SchemaRef::new(SchemaId::LAUNCHER, SchemaVersion::new(1, 0, 0)).url(),
+        "ui": { "theme": "metro_dark" },
+        "appearance": { "theme_mode": "light" }
+    });
+    let (doc, _) = SettingDocument::load(&launcher_schema(), &raw);
+    assert_eq!(doc.effective_str("appearance.theme_mode"), Some("light"));
+}
+
+#[test]
+fn unmapped_legacy_value_is_reported() {
+    let (doc, problems) =
+        SettingDocument::load(&launcher_schema(), &legacy_file(json!({ "theme": "neon" })));
+    assert_eq!(doc.effective_str("appearance.theme_mode"), Some("neon"));
+    assert!(
+        problems.iter().any(|problem| matches!(
+            problem,
+            LoadProblem::InvalidValue { key, .. } if key == "appearance.theme_mode"
+        )),
+        "映射不过去的旧值要报出来: {problems:?}"
+    );
+}
+
+#[test]
+fn writing_the_deprecated_key_is_refused() {
+    let (mut doc, _) = SettingDocument::load(&launcher_schema(), &json!({}));
+    let err = doc
+        .set("ui.theme", json!("metro_dark"))
+        .expect_err("旧键禁止写");
+    assert!(err.to_string().contains("appearance.theme_mode"), "{err}");
+    assert!(!doc.is_dirty());
+}
+
+#[test]
+fn save_drops_the_old_key_and_writes_the_new_one() {
+    let temp = TempDir::new("deprecated-save");
+    temp.write(
+        "config/launcher.json",
+        &legacy_file(json!({ "theme": "metro_dark", "language": "en_us" })).to_string(),
+    );
+
+    let mut store = SettingStore::load(temp.child("config/launcher.json"), launcher_schema());
+    assert_eq!(
+        store.effective("appearance.theme_mode"),
+        Some(&json!("dark"))
+    );
+
+    // 随便改一个别的键触发一次保存：旧键消失、新键（映射值）落盘。
+    store.set("ui.scale", json!(1.25)).expect("改缩放");
+    store.save().expect("保存");
+
+    let saved: Value = serde_json::from_str(&temp.read("config/launcher.json")).expect("JSON 合法");
+    assert_eq!(saved["appearance"]["theme_mode"], json!("dark"));
+    assert!(
+        saved["ui"].get("theme").is_none(),
+        "废弃键不再落盘: {saved}"
+    );
+    assert_eq!(saved["ui"]["language"], json!("en_us"));
+}
+
+#[test]
+fn whitelist_and_tool_schema_exclude_the_old_key() {
+    let schema = launcher_schema();
+    assert_eq!(schema.deprecated_keys(), vec!["ui.theme"]);
+    assert_eq!(
+        schema.replacement_of("ui.theme"),
+        Some("appearance.theme_mode")
+    );
+    assert_eq!(schema.replacement_of("appearance.theme_mode"), None);
+    assert!(!schema.accepts_ai_write("ui.theme"), "废弃键不许 AI 写");
+    assert!(!schema.ai_writable_keys().contains(&"ui.theme"));
+
+    let projected = schema.to_json_schema();
+    let properties = projected["properties"].as_object().expect("properties");
+    assert!(properties.contains_key("appearance.theme_mode"));
+    assert!(!properties.contains_key("ui.theme"));
+}
diff --git a/crates/core/tests/setting/dir_migration.rs b/crates/core/tests/setting/dir_migration.rs
new file mode 100644
index 0000000..8a0d0c0
--- /dev/null
+++ b/crates/core/tests/setting/dir_migration.rs
@@ -0,0 +1,185 @@
+//! 数据目录迁移：计划校验、逐分区搬动、收据 + 指针、失败逆序回滚。
+
+use std::path::{Path, PathBuf};
+
+use unlucky_core::platform::data_dir::{DataMode, ResolvedData};
+use unlucky_core::platform::dir_migration::{self, DirMigrationOptions};
+use unlucky_core::platform::error::PlatformError;
+use unlucky_core::platform::layout::{LauncherLayout, Partition};
+use unlucky_core::platform::receipt::{self, ReceiptKind};
+use unlucky_core::platform::redirect;
+
+use crate::common::TempDir;
+
+fn resolved(home: &Path) -> ResolvedData {
+    ResolvedData {
+        mode: DataMode::Custom,
+        launcher_home: home.to_path_buf(),
+        game_home: home.join(".minecraft"),
+        redirected_from: None,
+    }
+}
+
+fn seed(home: &Path) {
+    let layout = LauncherLayout::new(home.to_path_buf());
+    layout.ensure().expect("建四分区");
+    std::fs::create_dir_all(layout.auth_data()).expect("auth 目录");
+    std::fs::create_dir_all(layout.sha1_cache("ab")).expect("缓存分片");
+    std::fs::write(layout.launcher_config(), b"{\"x\":1}").expect("写配置");
+    std::fs::write(layout.auth_data().join("token.json"), b"{}").expect("写凭据");
+    std::fs::write(layout.sha1_cache("ab").join("hash"), b"payload").expect("写缓存");
+    std::fs::write(layout.logs().join("launcher.log"), b"log").expect("写日志");
+}
+
+#[test]
+fn plan_orders_partitions_and_skips_missing_ones() {
+    let temp = TempDir::new("dir-migration-plan");
+    seed(&temp.child("old/.ULL"));
+    let from = resolved(&temp.child("old/.ULL"));
+    let to = resolved(&temp.child("new/.ULL"));
+
+    let plan = dir_migration::plan(&from, &to, &DirMigrationOptions::default()).expect("计划");
+    let partitions: Vec<Partition> = plan.steps.iter().map(|step| step.partition).collect();
+    assert_eq!(
+        partitions,
+        vec![
+            Partition::Config,
+            Partition::Data,
+            Partition::Logs,
+            Partition::Cache
+        ],
+        "配置最先、缓存最后"
+    );
+
+    let cache_off = DirMigrationOptions {
+        migrate_cache: false,
+    };
+    let plan = dir_migration::plan(&from, &to, &cache_off).expect("计划");
+    assert_eq!(plan.steps.len(), 3);
+    assert!(plan
+        .steps
+        .iter()
+        .all(|step| step.partition != Partition::Cache));
+}
+
+#[test]
+fn execute_moves_everything_and_leaves_a_pointer() {
+    let temp = TempDir::new("dir-migration-run");
+    let old_home = temp.child("old/.ULL");
+    let new_home = temp.child("new/.ULL");
+    seed(&old_home);
+    let from = resolved(&old_home);
+    let to = resolved(&new_home);
+
+    let plan = dir_migration::plan(&from, &to, &DirMigrationOptions::default()).expect("计划");
+    let outcome = dir_migration::execute(&plan, 1_700_000_000_000).expect("执行");
+
+    assert_eq!(
+        outcome.moved,
+        vec![
+            Partition::Config,
+            Partition::Data,
+            Partition::Logs,
+            Partition::Cache
+        ]
+    );
+
+    let moved = LauncherLayout::new(new_home.clone());
+    assert!(moved.launcher_config().is_file(), "配置要搬过去");
+    assert!(moved.auth_data().join("token.json").is_file());
+    assert!(moved.logs().join("launcher.log").is_file());
+    assert!(moved.sha1_cache("ab").join("hash").is_file());
+    assert!(!LauncherLayout::new(old_home.clone()).config().exists());
+
+    let stored = receipt::read(&outcome.receipt_path)
+        .expect("读收据")
+        .expect("有收据");
+    assert_eq!(stored.kind, ReceiptKind::DataDirMove);
+    assert_eq!(stored.source, old_home);
+    assert_eq!(stored.target, new_home);
+    assert_eq!(stored.applied_at_ms, 1_700_000_000_000);
+
+    let pointer = redirect::read(&old_home)
+        .expect("读指针")
+        .expect("旧目录要留指针");
+    assert_eq!(pointer.launcher_home, new_home);
+    assert_eq!(pointer.mode, DataMode::Custom);
+    assert_eq!(outcome.pointer_path, old_home.join("redirect.json"));
+}
+
+#[test]
+fn refuses_same_source_and_target() {
+    let temp = TempDir::new("dir-migration-same");
+    seed(&temp.child("only/.ULL"));
+    let home = resolved(&temp.child("only/.ULL"));
+    let err = dir_migration::plan(&home, &home, &DirMigrationOptions::default())
+        .expect_err("源目标相同要拒绝");
+    assert!(
+        matches!(err, PlatformError::MigrationRefused { .. }),
+        "{err}"
+    );
+}
+
+#[test]
+fn refuses_missing_source_and_non_empty_target() {
+    let temp = TempDir::new("dir-migration-refuse");
+    let from = resolved(&temp.child("gone/.ULL"));
+    let to = resolved(&temp.child("new/.ULL"));
+    assert!(matches!(
+        dir_migration::plan(&from, &to, &DirMigrationOptions::default()).expect_err("源不存在"),
+        PlatformError::MigrationRefused { .. }
+    ));
+
+    seed(&temp.child("old/.ULL"));
+    let from = resolved(&temp.child("old/.ULL"));
+    std::fs::create_dir_all(to.launcher_home.clone()).expect("建目标");
+    std::fs::write(to.launcher_home.join("something"), b"x").expect("占位");
+    let err = dir_migration::plan(&from, &to, &DirMigrationOptions::default())
+        .expect_err("目标非空要拒绝");
+    assert!(err.to_string().contains("已有数据"), "{err}");
+}
+
+#[test]
+fn rolls_back_moved_partitions_when_a_later_step_fails() {
+    let temp = TempDir::new("dir-migration-rollback");
+    let old_home = temp.child("old/.ULL");
+    let new_home = temp.child("new/.ULL");
+    seed(&old_home);
+    let from = resolved(&old_home);
+    let to = resolved(&new_home);
+
+    let plan = dir_migration::plan(&from, &to, &DirMigrationOptions::default()).expect("计划");
+    // 计划之后在目标侧造障碍：data 位置先占成普通文件 → 搬 data 必失败。
+    std::fs::create_dir_all(&new_home).expect("建目标根");
+    std::fs::write(new_home.join("data"), b"obstruction").expect("造障碍");
+
+    let err = dir_migration::execute(&plan, 42).expect_err("应当失败");
+    assert!(
+        matches!(err, PlatformError::MigrationRefused { .. }),
+        "{err}"
+    );
+
+    let old = LauncherLayout::new(old_home);
+    assert!(old.launcher_config().is_file(), "config 必须被回滚搬回来");
+    assert!(old.auth_data().join("token.json").is_file());
+    assert!(!old.redirect_path().exists(), "失败不该留指针");
+    assert!(!new_home.join("config").exists(), "目标侧不该残留已搬分区");
+    assert!(!new_home.join("data").is_dir(), "障碍文件保持原样");
+}
+
+#[test]
+fn receipt_anti_replay_uses_source_target_signature() {
+    let temp = TempDir::new("dir-migration-receipt");
+    let receipt_path: PathBuf = temp.child("config/migration-receipt.json");
+    let receipt = receipt::MigrationReceipt::data_dir_move(
+        PathBuf::from("/old/.ULL"),
+        PathBuf::from("/new/.ULL"),
+        1_700_000_000_000,
+    );
+    receipt::write(&receipt_path, &receipt).expect("写收据");
+    let loaded = receipt::read(&receipt_path).expect("读").expect("有");
+    assert_eq!(
+        receipt::decide(Some(&loaded), &receipt.source_fingerprint),
+        receipt::ReplayDecision::SkipSameSource
+    );
+}
diff --git a/crates/core/tests/setting/dirs.rs b/crates/core/tests/setting/dirs.rs
new file mode 100644
index 0000000..8579a0a
--- /dev/null
+++ b/crates/core/tests/setting/dirs.rs
@@ -0,0 +1,205 @@
+//! 三模式数据目录解析：Portable / Standard / Custom + 平台落点 + 高级覆盖 + redirect 跟随。
+
+use std::path::PathBuf;
+
+use unlucky_core::platform::data_dir::{DataDirRequest, DataMode, ResolvedData, Resolver};
+use unlucky_core::platform::error::PlatformError;
+use unlucky_core::platform::paths::{standard_game_home, standard_launcher_home, MapEnv, Platform};
+use unlucky_core::platform::redirect::{self, RedirectPointer, REDIRECT_SCHEMA_VERSION};
+
+use crate::common::TempDir;
+
+#[test]
+fn portable_puts_dot_ull_and_minecraft_beside_exe() {
+    let env = MapEnv::new().with("APPDATA", "/roaming");
+    let resolver = Resolver::with_env(Platform::Windows, Some(PathBuf::from("/games/ULL")), &env);
+    assert_eq!(resolver.default_mode(), DataMode::Portable);
+
+    let resolved = resolver.resolve(&DataDirRequest::default()).expect("解析");
+    assert_eq!(resolved.mode, DataMode::Portable);
+    assert_eq!(resolved.launcher_home, PathBuf::from("/games/ULL/.ULL"));
+    assert_eq!(resolved.game_home, PathBuf::from("/games/ULL/.minecraft"));
+    assert!(resolved.redirected_from.is_none());
+}
+
+#[test]
+fn portable_without_exe_dir_errors() {
+    let env = MapEnv::new();
+    let resolver = Resolver::with_env(Platform::Linux, None, &env);
+    let err = resolver
+        .resolve(&DataDirRequest::default())
+        .expect_err("应当报错");
+    assert!(matches!(err, PlatformError::NoExecutableDir));
+}
+
+#[test]
+fn standard_uses_per_os_locations() {
+    let windows = MapEnv::new().with("APPDATA", "/roaming");
+    assert_eq!(
+        standard_launcher_home(Platform::Windows, &windows),
+        Some(PathBuf::from("/roaming/ULL"))
+    );
+    assert_eq!(
+        standard_game_home(Platform::Windows, &windows),
+        Some(PathBuf::from("/roaming/.minecraft"))
+    );
+
+    let mac = MapEnv::new().with("HOME", "/Users/u");
+    assert_eq!(
+        standard_launcher_home(Platform::MacOs, &mac),
+        Some(PathBuf::from("/Users/u/Library/Application Support/ULL"))
+    );
+    assert_eq!(
+        standard_game_home(Platform::MacOs, &mac),
+        Some(PathBuf::from(
+            "/Users/u/Library/Application Support/minecraft"
+        ))
+    );
+
+    // XDG 规范要求绝对路径；测试用 temp_dir（两种平台都算绝对路径）。
+    let xdg_root = std::env::temp_dir().join("ull-xdg");
+    let xdg_text = xdg_root.to_string_lossy().into_owned();
+    let linux = MapEnv::new()
+        .with("HOME", "/home/u")
+        .with("XDG_DATA_HOME", &xdg_text);
+    assert_eq!(
+        standard_launcher_home(Platform::Linux, &linux),
+        Some(xdg_root.join("ull"))
+    );
+    assert_eq!(
+        standard_game_home(Platform::Linux, &linux),
+        Some(PathBuf::from("/home/u/.minecraft"))
+    );
+
+    // 相对 XDG_DATA_HOME 不合法 → 回落 ~/.local/share/ull。
+    let relative_xdg = MapEnv::new()
+        .with("HOME", "/home/u")
+        .with("XDG_DATA_HOME", "relative/xdg");
+    assert_eq!(
+        standard_launcher_home(Platform::Linux, &relative_xdg),
+        Some(PathBuf::from("/home/u/.local/share/ull"))
+    );
+}
+
+#[test]
+fn standard_falls_back_when_env_missing() {
+    let env = MapEnv::new()
+        .with("HOME", "/home/u")
+        .with("USERPROFILE", "/home/u");
+    assert_eq!(
+        standard_launcher_home(Platform::Linux, &env),
+        Some(PathBuf::from("/home/u/.local/share/ull"))
+    );
+    assert_eq!(
+        standard_launcher_home(Platform::Windows, &env),
+        Some(PathBuf::from("/home/u/AppData/Roaming/ULL"))
+    );
+
+    let empty = MapEnv::new();
+    assert_eq!(standard_launcher_home(Platform::Windows, &empty), None);
+}
+
+#[test]
+fn standard_mode_resolution_and_macos_default() {
+    let env = MapEnv::new().with("HOME", "/Users/u");
+    let resolver = Resolver::with_env(Platform::MacOs, None, &env);
+    assert_eq!(resolver.default_mode(), DataMode::Standard);
+
+    let request = DataDirRequest {
+        mode: DataMode::Standard,
+        ..DataDirRequest::default()
+    };
+    let resolved = resolver.resolve(&request).expect("解析");
+    assert_eq!(
+        resolved.launcher_home,
+        PathBuf::from("/Users/u/Library/Application Support/ULL")
+    );
+    assert_eq!(
+        resolved.game_home,
+        PathBuf::from("/Users/u/Library/Application Support/minecraft")
+    );
+}
+
+#[test]
+fn custom_requires_absolute_existing_root_choice() {
+    let env = MapEnv::new();
+    let resolver = Resolver::with_env(Platform::Windows, Some(PathBuf::from("/games")), &env);
+    let root = std::env::temp_dir().join("ull-custom-root");
+
+    let ok = DataDirRequest {
+        mode: DataMode::Custom,
+        custom_root: Some(root.clone()),
+        ..DataDirRequest::default()
+    };
+    let resolved = resolver.resolve(&ok).expect("解析");
+    assert_eq!(resolved.launcher_home, root.join(".ULL"));
+    assert_eq!(resolved.game_home, root.join(".minecraft"));
+
+    let relative = DataDirRequest {
+        mode: DataMode::Custom,
+        custom_root: Some(PathBuf::from("relative/dir")),
+        ..DataDirRequest::default()
+    };
+    assert!(matches!(
+        resolver.resolve(&relative).expect_err("相对路径应报错"),
+        PlatformError::InvalidCustomRoot { .. }
+    ));
+
+    let missing = DataDirRequest {
+        mode: DataMode::Custom,
+        custom_root: None,
+        ..DataDirRequest::default()
+    };
+    assert!(resolver.resolve(&missing).is_err());
+}
+
+#[test]
+fn advanced_overrides_split_launcher_and_game_home() {
+    let env = MapEnv::new();
+    let resolver = Resolver::with_env(Platform::Windows, Some(PathBuf::from("/games")), &env);
+    let request = DataDirRequest {
+        launcher_home: Some(PathBuf::from("/config/ULL")),
+        game_home: Some(PathBuf::from("/bigdisk/.minecraft")),
+        ..DataDirRequest::default()
+    };
+    let resolved = resolver.resolve(&request).expect("解析");
+    assert_eq!(resolved.launcher_home, PathBuf::from("/config/ULL"));
+    assert_eq!(resolved.game_home, PathBuf::from("/bigdisk/.minecraft"));
+    assert!(!resolved.same_target(&ResolvedData {
+        mode: DataMode::Portable,
+        launcher_home: PathBuf::from("/other"),
+        game_home: PathBuf::from("/bigdisk/.minecraft"),
+        redirected_from: None,
+    }));
+}
+
+#[test]
+fn effective_resolution_follows_redirect_pointer() {
+    let temp = TempDir::new("data-dir-redirect");
+    let exe_dir = temp.child("portable");
+    let moved_to = temp.child("after-move");
+    std::fs::create_dir_all(&exe_dir).expect("建目录");
+
+    let pointer = RedirectPointer {
+        schema_version: REDIRECT_SCHEMA_VERSION,
+        mode: DataMode::Custom,
+        launcher_home: moved_to.clone(),
+        game_home: moved_to.join(".minecraft"),
+        migrated_at_ms: 1_700_000_000_000,
+    };
+    redirect::write(&exe_dir.join(".ULL"), &pointer).expect("写指针");
+
+    let env = MapEnv::new();
+    let resolver = Resolver::with_env(Platform::Windows, Some(exe_dir.clone()), &env);
+    let resolved = resolver
+        .resolve_default(&DataDirRequest::default())
+        .expect("解析");
+
+    assert_eq!(resolved.launcher_home, moved_to);
+    assert_eq!(resolved.mode, DataMode::Portable);
+    assert_eq!(
+        resolved.redirected_from,
+        Some(exe_dir.join(".ULL")),
+        "旧目录要留在记录里，便于 UI 提示「数据已迁走」"
+    );
+}
diff --git a/crates/core/tests/setting/document.rs b/crates/core/tests/setting/document.rs
new file mode 100644
index 0000000..c210dc3
--- /dev/null
+++ b/crates/core/tests/setting/document.rs
@@ -0,0 +1,221 @@
+//! 文档模型：脏字段、未知字段保留、默认值不落盘、嵌套点路径、坏值容错、`$schema` 保留。
+
+use serde_json::{json, Value};
+use unlucky_core::setting::document::{LoadProblem, RenderMode, SettingDocument};
+use unlucky_core::setting::keys::launcher_schema;
+use unlucky_core::setting::schema::{SchemaRef, SchemaVersion, SCHEMA_KEY, SCHEMA_VERSION_KEY};
+
+fn schema_url(version: SchemaVersion) -> String {
+    SchemaRef::new(unlucky_core::setting::schema::SchemaId::LAUNCHER, version).url()
+}
+
+fn loaded(raw: Value) -> (SettingDocument, Vec<LoadProblem>) {
+    SettingDocument::load(&launcher_schema(), &raw)
+}
+
+#[test]
+fn reads_nested_keys_and_keeps_unknown_subtrees() {
+    let raw = json!({
+        SCHEMA_KEY: schema_url(launcher_version()),
+        SCHEMA_VERSION_KEY: 1,
+        "download": { "concurrency": 16 },
+        "ui": { "language": "en_us", "unknown_ui": true },
+        "future_section": { "nested": { "flag": true } }
+    });
+
+    let (doc, problems) = loaded(raw);
+    assert_eq!(doc.effective_i64("download.concurrency"), Some(16));
+    assert_eq!(doc.effective_str("ui.language"), Some("en_us"));
+
+    let unknown: Vec<&str> = doc.unknown_keys().collect();
+    assert!(unknown.contains(&"ui.unknown_ui"), "{unknown:?}");
+    assert!(
+        unknown.contains(&"future_section.nested.flag"),
+        "未知键清单是叶子粒度: {unknown:?}"
+    );
+
+    let reported: Vec<&str> = problems
+        .iter()
+        .filter_map(|problem| match problem {
+            LoadProblem::UnknownKey { key } => Some(key.as_str()),
+            _ => None,
+        })
+        .collect();
+    assert!(reported.contains(&"ui.unknown_ui"), "{problems:?}");
+    assert!(
+        reported.contains(&"future_section"),
+        "陌生子树按最上层节点报一次，不做逐叶展开: {problems:?}"
+    );
+
+    let rendered = doc.to_value();
+    assert_eq!(rendered[SCHEMA_VERSION_KEY], json!(1));
+    assert_eq!(
+        rendered["future_section"]["nested"]["flag"],
+        json!(true),
+        "未知字段必须原样回写"
+    );
+    assert_eq!(rendered["ui"]["unknown_ui"], json!(true));
+}
+
+#[test]
+fn defaults_never_reach_the_file() {
+    let (doc, _) = loaded(json!({ SCHEMA_KEY: schema_url(launcher_version()) }));
+    // 生效值有默认，但落盘视图里没有这些键。
+    assert_eq!(doc.effective_i64("download.concurrency"), Some(8));
+    assert_eq!(doc.effective_bool("ai.enabled"), Some(true));
+    assert!(doc.get("download.concurrency").is_none());
+    let rendered = doc.to_value();
+    assert!(rendered.get("download").is_none(), "{rendered}");
+    // 无默认值的路径键 → None。
+    assert!(doc.effective_str("java.selected_path").is_none());
+}
+
+#[test]
+fn tracks_dirty_keys_and_renders_patches() {
+    let raw = json!({
+        SCHEMA_KEY: schema_url(launcher_version()),
+        "download": { "concurrency": 8, "retry_limit": 2 }
+    });
+    let (mut doc, _) = loaded(raw);
+    assert!(!doc.is_dirty());
+
+    doc.set("download.concurrency", json!(32)).expect("写");
+    doc.set("appearance.theme_mode", json!("dark")).expect("写");
+
+    let mut dirty: Vec<&str> = doc.dirty_keys().collect();
+    dirty.sort_unstable();
+    assert_eq!(dirty, vec!["appearance.theme_mode", "download.concurrency"]);
+
+    let patch = doc.dirty_patch();
+    assert_eq!(patch["download"]["concurrency"], json!(32));
+    assert_eq!(patch["appearance"]["theme_mode"], json!("dark"));
+    assert!(
+        patch["download"].get("retry_limit").is_none(),
+        "非脏字段不进补丁"
+    );
+
+    let dirty_view = doc.render(RenderMode::DirtyOnly);
+    assert_eq!(dirty_view["download"]["concurrency"], json!(32));
+    assert!(dirty_view["download"].get("retry_limit").is_none());
+
+    doc.mark_clean();
+    assert!(!doc.is_dirty());
+    assert_eq!(doc.dirty_patch(), json!({}));
+}
+
+#[test]
+fn invalid_values_are_preserved_with_a_problem() {
+    let raw = json!({
+        SCHEMA_KEY: schema_url(launcher_version()),
+        "download": { "concurrency": 9999, "retry_limit": "many" }
+    });
+    let (doc, problems) = loaded(raw);
+    assert_eq!(
+        doc.get("download.concurrency").and_then(Value::as_i64),
+        Some(9999),
+        "坏值原样保留（用户能看见自己写坏了什么）"
+    );
+    let invalid: Vec<&str> = problems
+        .iter()
+        .filter_map(|problem| match problem {
+            LoadProblem::InvalidValue { key, .. } => Some(key.as_str()),
+            _ => None,
+        })
+        .collect();
+    assert!(invalid.contains(&"download.concurrency"), "{problems:?}");
+    assert!(invalid.contains(&"download.retry_limit"), "{problems:?}");
+}
+
+#[test]
+fn schema_version_mirror_mismatch_is_reported_but_schema_wins() {
+    let raw = json!({
+        SCHEMA_KEY: schema_url(launcher_version()),
+        SCHEMA_VERSION_KEY: 7
+    });
+    let (doc, problems) = loaded(raw);
+    assert_eq!(doc.version(), launcher_version());
+    assert!(problems.iter().any(|problem| matches!(
+        problem,
+        LoadProblem::SchemaVersionMismatch {
+            declared: 7,
+            expected: 1
+        }
+    )));
+}
+
+#[test]
+fn newer_patch_preserves_original_schema_string() {
+    // 同 minor、更高 patch（**相对构造**：版本号涨了这条也不会假绿）。
+    let current = launcher_version();
+    let newer = SchemaVersion::new(current.major, current.minor, current.patch + 1);
+    let url = schema_url(newer);
+    let (doc, _) = loaded(json!({ SCHEMA_KEY: url.clone() }));
+    assert_eq!(
+        doc.preserve_schema(),
+        Some(url.as_str()),
+        "同 minor 更高 patch 要保留原 $schema"
+    );
+    assert_eq!(doc.to_value()[SCHEMA_KEY], json!(url));
+    assert_eq!(doc.version(), newer);
+}
+
+#[test]
+fn wrong_shape_for_known_prefix_is_reported() {
+    let raw = json!({
+        SCHEMA_KEY: schema_url(launcher_version()),
+        "download": "oops"
+    });
+    let (doc, problems) = loaded(raw);
+    assert!(
+        problems.iter().any(|problem| matches!(
+            problem,
+            LoadProblem::InvalidShape { key, .. } if key == "download"
+        )),
+        "{problems:?}"
+    );
+    assert!(doc.get("download").is_none());
+    // 原始坏结构不进 values，也不会被当成未知键回写。
+    assert!(doc.to_value().get("download").is_none());
+}
+
+#[test]
+fn non_object_json_yields_problem_and_empty_doc() {
+    let (doc, problems) = loaded(json!([1, 2, 3]));
+    assert!(!problems.is_empty());
+    assert_eq!(doc.effective_i64("download.concurrency"), Some(8));
+}
+
+#[test]
+fn set_rejects_unknown_keys_and_out_of_range_values() {
+    let (mut doc, _) = loaded(json!({}));
+    assert!(doc.set("nope.key", json!(1)).is_err());
+    assert!(doc.set("download.concurrency", json!(0)).is_err());
+    assert!(doc
+        .set("appearance.theme_mode", json!("solarized"))
+        .is_err());
+    assert!(!doc.is_dirty(), "校验失败不能标脏");
+}
+
+#[test]
+fn unknown_schema_prefix_reports_problem_and_keeps_values() {
+    let raw = json!({
+        SCHEMA_KEY: "https://unlucky-launcher.local/schema/launcher/1.2.0.json",
+        "core": { "data_mode": "standard" },
+    });
+    let (doc, problems) = loaded(raw);
+    // 值照读（旧实现按「没有声明」整份装默认值）。
+    assert_eq!(doc.effective_str("core.data_mode"), Some("standard"));
+    let found = problems.iter().find_map(|problem| match problem {
+        LoadProblem::UnknownSchema { url } => Some(url.as_str()),
+        _ => None,
+    });
+    assert_eq!(
+        found,
+        Some("https://unlucky-launcher.local/schema/launcher/1.2.0.json"),
+        "{problems:?}"
+    );
+}
+
+fn launcher_version() -> SchemaVersion {
+    unlucky_core::setting::keys::launcher_version()
+}
diff --git a/crates/core/tests/setting/isolation_keys.rs b/crates/core/tests/setting/isolation_keys.rs
new file mode 100644
index 0000000..eab24cd
--- /dev/null
+++ b/crates/core/tests/setting/isolation_keys.rs
@@ -0,0 +1,251 @@
+//! D20 隔离键的 schema 契约：全局 `instances.mode`、实例 `isolation`、`lastModeChange`、
+//! 恒共享层不可配、旧配置缺键即默认值（不需要迁移步骤）。
+
+use serde_json::json;
+use unlucky_core::game::install::instance::{InstanceConfig, Isolation, OverrideKey};
+use unlucky_core::game::isolation::{observe_mode, IsolationMode};
+use unlucky_core::game::GameLayout;
+use unlucky_core::setting::document::{LoadProblem, RenderMode, SettingDocument};
+use unlucky_core::setting::instance_keys::{
+    instance_schema, instance_version, ISOLATION_OVERRIDES, ISOLATION_RESOLVED, OVERRIDE_KEYS,
+};
+use unlucky_core::setting::keys::{launcher_schema, launcher_version, INSTANCE_MODES};
+use unlucky_core::setting::schema::{SchemaId, SchemaVersion};
+use unlucky_core::setting::spec::{Sensitivity, ValueKind};
+use unlucky_core::setting::store::SettingStore;
+
+use super::common::TempDir;
+
+#[test]
+fn global_mode_key_defaults_to_isolated() {
+    let schema = launcher_schema();
+    let spec = schema.spec("instances.mode").expect("instances.mode 键");
+    assert_eq!(spec.default, json!("isolated"), "D20 默认隔离");
+    assert_eq!(spec.kind, ValueKind::Enum(INSTANCE_MODES));
+    assert_eq!(
+        spec.ai.sensitivity,
+        Sensitivity::High,
+        "切档会改变存档可见性，AI 改必须弹窗确认"
+    );
+    assert!(schema.validate("instances.mode", &json!("shared")).is_ok());
+    assert!(schema
+        .validate("instances.mode", &json!("isolated"))
+        .is_ok());
+    assert!(schema
+        .validate("instances.mode", &json!("per_version"))
+        .is_err());
+    assert!(schema.validate("instances.mode", &json!("custom")).is_err());
+}
+
+#[test]
+fn shared_layers_are_not_configurable() {
+    let schema = launcher_schema();
+    for key in ["shared.versions", "shared.assets", "shared.libraries"] {
+        assert!(
+            !schema.is_known(key),
+            "{key} 是恒共享层，不该出现在可配键表里"
+        );
+    }
+}
+
+#[test]
+fn instance_isolation_defaults_to_inherit() {
+    let schema = instance_schema();
+    let spec = schema.spec("isolation").expect("isolation 键");
+    assert_eq!(spec.default, json!("inherit"));
+    assert_eq!(spec.kind, ValueKind::Enum(ISOLATION_OVERRIDES));
+    for value in ["inherit", "isolated", "shared", "custom"] {
+        assert!(
+            schema.validate("isolation", &json!(value)).is_ok(),
+            "{value}"
+        );
+    }
+    assert!(schema.validate("isolation", &json!("per_version")).is_err());
+}
+
+#[test]
+fn inherit_never_reaches_the_file() {
+    // 默认值不落盘：空文档渲染出来只应该有 $schema / schemaVersion。
+    let schema = instance_schema();
+    let (document, problems) = SettingDocument::load(&schema, &json!({}));
+    assert!(problems.is_empty(), "{problems:?}");
+    let rendered = document.render(RenderMode::Full);
+    assert!(rendered.get("isolation").is_none(), "{rendered}");
+    assert!(rendered.get("lastModeChange").is_none(), "{rendered}");
+    let dirty = document.render(RenderMode::DirtyOnly);
+    assert!(dirty.get("isolation").is_none(), "{dirty}");
+}
+
+#[test]
+fn last_mode_change_keys_are_bookkeeping_only() {
+    let schema = instance_schema();
+    for key in [
+        "lastModeChange.at",
+        "lastModeChange.from",
+        "lastModeChange.to",
+        "lastModeChange.probe.isolatedSide",
+        "lastModeChange.probe.sharedSide",
+        "lastModeChange.warned",
+    ] {
+        assert!(schema.is_known(key), "{key} 必须登记");
+        assert!(!schema.accepts_ai_write(key), "{key} 不许 AI 写");
+    }
+    assert!(schema
+        .validate("lastModeChange.probe.isolatedSide", &json!(12))
+        .is_ok());
+    assert!(schema
+        .validate("lastModeChange.probe.isolatedSide", &json!(-1))
+        .is_err());
+    assert!(schema
+        .validate("lastModeChange.warned", &json!(true))
+        .is_ok());
+    assert!(schema.validate("lastModeChange.warned", &json!(1)).is_err());
+    assert!(schema
+        .validate("lastModeChange.from", &json!("shared"))
+        .is_ok());
+    assert!(schema
+        .validate("lastModeChange.from", &json!("inherit"))
+        .is_err());
+    assert_eq!(ISOLATION_RESOLVED, ["isolated", "shared", "custom"]);
+}
+
+#[test]
+fn overrides_key_is_an_enum_whitelist() {
+    let schema = instance_schema();
+    assert!(schema.validate("overrides", &json!([])).is_ok());
+    assert!(schema
+        .validate("overrides", &json!(["maxMemory", "runningDirectory"]))
+        .is_ok());
+    assert!(
+        schema
+            .validate("overrides", &json!(["max_memory"]))
+            .is_err(),
+        "旧 snake_case 拼写不许过（拼错会静默失效）"
+    );
+    assert!(schema.validate("overrides", &json!([1])).is_err());
+    assert_eq!(OVERRIDE_KEYS, ["maxMemory", "javaType", "runningDirectory"]);
+}
+
+#[test]
+fn schema_versions_register_the_new_keys_without_migration() {
+    // 1.5.0 登记 M116 的窗口圆角策略键（1.4.0 = M91 外观下层三键，1.3.0 = D17「外观（高级）」，
+    // 1.2.0 = D23 的 JDK 落点/优先级键）。
+    assert_eq!(launcher_version(), SchemaVersion::new(1, 5, 0));
+    assert_eq!(instance_version(), SchemaVersion::new(1, 1, 0));
+    assert_eq!(launcher_schema().id(), SchemaId::LAUNCHER);
+    // major 仍是 1：迁移链（按 major 走）不需要新步骤，老文件缺键即默认值。
+    assert_eq!(launcher_version().major, 1);
+    assert_eq!(instance_version().major, 1);
+}
+
+#[test]
+fn old_launcher_file_without_new_keys_loads_with_defaults() {
+    let temp = std::env::temp_dir().join(format!(
+        "ull-setting-d20-{}-{}",
+        std::process::id(),
+        std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .map_or(0, |d| d.as_nanos())
+    ));
+    std::fs::create_dir_all(&temp).expect("临时目录");
+    let path = temp.join("launcher.json");
+    // 旧版本写的文件：只有 $schema 1.0.0 和一个老键，没有 instances.mode。
+    std::fs::write(
+        &path,
+        serde_json::to_vec_pretty(&json!({
+            "$schema": "https://schemas.unlucky-launcher.dev/ull/launcher/1.0.0",
+            "schemaVersion": 1,
+            "ui": { "scale": 1.25 }
+        }))
+        .expect("序列化"),
+    )
+    .expect("写文件");
+
+    let store = SettingStore::load(&path, launcher_schema());
+    assert!(store.access().can_read(), "1.0.0 文件必须可读");
+    assert!(store.problems().is_empty(), "{:?}", store.problems());
+    assert_eq!(
+        store.doc().effective_str("instances.mode"),
+        Some("isolated"),
+        "缺键取 D20 默认值"
+    );
+    assert_eq!(store.doc().effective_f64("ui.scale"), Some(1.25));
+    let _ = std::fs::remove_dir_all(&temp);
+}
+
+#[test]
+fn setting_lists_agree_with_the_game_enums() {
+    // schema 白名单与 game 侧枚举必须一一对应（两处字面量漂移就是静默不生效）。
+    let mut modes: Vec<&str> = [IsolationMode::Isolated, IsolationMode::Shared]
+        .iter()
+        .map(|mode| mode.as_str())
+        .collect();
+    modes.sort_unstable();
+    let mut declared = INSTANCE_MODES.to_vec();
+    declared.sort_unstable();
+    assert_eq!(modes, declared);
+
+    for value in ISOLATION_OVERRIDES
+        .iter()
+        .filter(|value| **value != "inherit")
+    {
+        assert!(
+            Isolation::parse(value).is_some(),
+            "{value} 在 game 侧解析不出来"
+        );
+        assert_eq!(Isolation::parse(value).map(Isolation::as_str), Some(*value));
+    }
+    for value in ISOLATION_RESOLVED {
+        assert!(Isolation::parse(value).is_some(), "{value}");
+    }
+}
+
+#[test]
+fn writer_output_loads_without_unknown_or_invalid_keys() {
+    // 回归 P2-1（review r1）：写入者（InstanceConfig + observe_mode）产出的键必须被 schema 全认。
+    // 之前 `lastModeChange.warned` 没登记，document 层会把真实文件标成 UnknownKey——
+    // 这正是「schema 只做写入者白名单视图」这条契约的裂缝。
+    let temp = TempDir::new("d20-writer-shape");
+    let game = GameLayout::new(temp.child("game"));
+    let mut config = InstanceConfig::new("11111111-2222-4333-8444-555555555555", "1.20.1");
+    config.isolation = Some(Isolation::Custom);
+    config.game_dir = Some(temp.child("elsewhere"));
+    config.overrides = vec![OverrideKey::MaxMemory];
+    observe_mode(
+        &mut config,
+        &game,
+        "2026-10-30T00:00:00Z",
+        Isolation::Custom,
+    )
+    .expect("观察");
+
+    let raw: serde_json::Value =
+        serde_json::from_str(&config.to_json_string().expect("序列化")).expect("合法 JSON");
+    // 写入者确实输出了 warned（P2-1 的前提）。
+    assert_eq!(raw["lastModeChange"]["warned"], json!(true));
+
+    let (document, problems) = SettingDocument::load(&instance_schema(), &raw);
+    let mut unknown: Vec<String> = Vec::new();
+    let mut invalid: Vec<String> = Vec::new();
+    for problem in &problems {
+        match problem {
+            LoadProblem::UnknownKey { key } => unknown.push(key.clone()),
+            LoadProblem::InvalidValue { key, reason } => invalid.push(format!("{key}: {reason}")),
+            _ => {}
+        }
+    }
+    assert!(unknown.is_empty(), "写入者的键没登记进 schema：{unknown:?}");
+    assert!(
+        invalid.is_empty(),
+        "写入者的值过不了 schema 校验：{invalid:?}"
+    );
+    assert_eq!(
+        document.get("lastModeChange.warned"),
+        Some(&json!(true)),
+        "记账键要能读回"
+    );
+    // 落盘视图不能把它当「未知键」重复输出。
+    let rendered = document.render(RenderMode::Full);
+    assert_eq!(rendered["lastModeChange"]["warned"], json!(true));
+    assert_eq!(rendered["overrides"], json!(["maxMemory"]));
+}
diff --git a/crates/core/tests/setting/java_install_keys.rs b/crates/core/tests/setting/java_install_keys.rs
new file mode 100644
index 0000000..90f2881
--- /dev/null
+++ b/crates/core/tests/setting/java_install_keys.rs
@@ -0,0 +1,119 @@
+//! D23 新增的两个设置键：`java.installRoot` / `java.vendorPriority`。
+//!
+//! 三件事要说清：
+//! 1. 两个键都登记在 launcher schema 里（`ull config get` 能看到、AI 白名单受策略约束）；
+//! 2. `java.vendorPriority` 的允许值集合与 `game::java::vendor::VENDOR_IDS` **同源**
+//!    （setting 层不依赖 game 层，靠这条契约测试固定，避免两处漂移）；
+//! 3. schema 版本推到 1.2.0 但 major 仍为 1 → 不需要迁移步骤（默认值不落盘）。
+
+use serde_json::json;
+use unlucky_core::game::java::vendor::VENDOR_IDS;
+use unlucky_core::setting::keys::{
+    launcher_schema, launcher_version, JAVA_INSTALL_ROOT_UNSET, JDK_VENDORS,
+};
+use unlucky_core::setting::schema::{SchemaId, SchemaRef, SchemaVersion};
+use unlucky_core::setting::store::SettingStore;
+
+#[test]
+fn both_d23_keys_are_registered_with_their_defaults() {
+    let schema = launcher_schema();
+    assert_eq!(
+        schema.default_value("java.installRoot"),
+        Some(&json!(JAVA_INSTALL_ROOT_UNSET))
+    );
+    assert_eq!(
+        schema.default_value("java.vendorPriority"),
+        Some(&json!([]))
+    );
+    // 空串/空数组都有明确语义：installRoot 空 = 按数据目录模式派生；
+    // vendorPriority 空 = 按地区默认序（国内 Temurin→Oracle→MS→Zulu）。
+    assert!(schema.spec("java.installRoot").is_some());
+    assert!(schema.spec("java.vendorPriority").is_some());
+}
+
+#[test]
+fn vendor_priority_whitelist_matches_the_vendor_module() {
+    assert_eq!(JDK_VENDORS, VENDOR_IDS, "两处必须同一份集合");
+    let schema = launcher_schema();
+    assert!(schema
+        .validate("java.vendorPriority", &json!(["oracle"]))
+        .is_ok());
+    assert!(schema
+        .validate("java.vendorPriority", &json!(["temurin", "zulu"]))
+        .is_ok());
+    assert!(schema
+        .validate("java.vendorPriority", &json!(["graalvm"]))
+        .is_err());
+    assert!(schema
+        .validate("java.vendorPriority", &json!([1, 2]))
+        .is_err());
+    assert!(schema
+        .validate("java.vendorPriority", &json!("microsoft"))
+        .is_err());
+}
+
+#[test]
+fn install_root_accepts_a_path_and_keeps_empty_as_unset() {
+    let schema = launcher_schema();
+    assert!(schema
+        .validate("java.installRoot", &json!("D:/jdk"))
+        .is_ok());
+    // 空串就是默认值，语义是「没设覆盖键」（不是错误）：所以类型是 text 而不是 path
+    // （Path 类型不接受空串，而这里需要一个合法的「未设置」值）。
+    assert!(schema.validate("java.installRoot", &json!("")).is_ok());
+    assert!(schema.validate("java.installRoot", &json!(5)).is_err());
+}
+
+#[test]
+fn schema_version_bumps_minor_only_so_no_migration_step_is_needed() {
+    assert_eq!(launcher_version(), SchemaVersion::new(1, 5, 0));
+    assert_eq!(
+        launcher_version().major,
+        1,
+        "major 不变 → 迁移链（按 major 走）不需要新步骤"
+    );
+}
+
+#[test]
+fn an_old_config_file_without_the_new_keys_still_loads() {
+    let dir = std::env::temp_dir().join(format!(
+        "ull-java-keys-{}-{}",
+        std::process::id(),
+        std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .map_or(0, |elapsed| elapsed.as_nanos())
+    ));
+    std::fs::create_dir_all(&dir).expect("建临时目录");
+    let path = dir.join("launcher.json");
+    // 1.1.0 的文件（真实 $schema 前缀）：没有 java.installRoot / java.vendorPriority，
+    // 且 core.data_mode 故意写非默认值 standard —— 证明值是「读出来的」不是「默认值撞上的」。
+    let old_url = SchemaRef::new(SchemaId::LAUNCHER, SchemaVersion::new(1, 1, 0)).url();
+    std::fs::write(
+        &path,
+        format!(r#"{{"$schema":"{old_url}","schemaVersion":1,"core":{{"data_mode":"standard"}}}}"#),
+    )
+    .expect("写旧配置");
+
+    let store = SettingStore::load(&path, launcher_schema());
+    assert_eq!(
+        store.doc().effective_str("core.data_mode"),
+        Some("standard"),
+        "旧文件的值必须照读（不是碰巧等于默认值）"
+    );
+    // 缺键取默认值，不报错、不写盘（「默认值不落盘」）。
+    assert_eq!(
+        store.doc().effective_str("java.installRoot"),
+        Some(JAVA_INSTALL_ROOT_UNSET)
+    );
+    assert_eq!(
+        store.effective("java.vendorPriority"),
+        Some(&json!([])),
+        "缺键 → 空数组 → 按地区默认序"
+    );
+    assert!(
+        store.problems().is_empty(),
+        "只缺新键不算问题：{:?}",
+        store.problems()
+    );
+    let _ = std::fs::remove_dir_all(&dir);
+}
diff --git a/crates/core/tests/setting/layout.rs b/crates/core/tests/setting/layout.rs
new file mode 100644
index 0000000..897099b
--- /dev/null
+++ b/crates/core/tests/setting/layout.rs
@@ -0,0 +1,128 @@
+//! 四分区布局、路径拼接、实例 id 白名单、可搬运路径字符串。
+
+use std::path::PathBuf;
+
+use unlucky_core::platform::layout::{
+    is_valid_instance_id, LauncherLayout, Partition, CONFIG_DIR, GAME_HOME_DIR, INSTANCES_DIR,
+    LAUNCHER_CONFIG_FILE, LAUNCHER_HOME_DIR, MIGRATION_RECEIPT_FILE, PROFILES_CONFIG_FILE,
+    REDIRECT_FILE,
+};
+
+use crate::common::TempDir;
+
+#[test]
+fn home_dir_names_match_design() {
+    assert_eq!(LAUNCHER_HOME_DIR, ".ULL");
+    assert_eq!(GAME_HOME_DIR, ".minecraft");
+    assert_eq!(CONFIG_DIR, "config");
+    assert_eq!(INSTANCES_DIR, "instances");
+    assert_eq!(LAUNCHER_CONFIG_FILE, "launcher.json");
+    assert_eq!(PROFILES_CONFIG_FILE, "profiles.json");
+    assert_eq!(REDIRECT_FILE, "redirect.json");
+    assert_eq!(MIGRATION_RECEIPT_FILE, "migration-receipt.json");
+}
+
+#[test]
+fn exposes_four_partitions() {
+    let layout = LauncherLayout::new("/home/u/.ULL");
+    assert_eq!(layout.home(), std::path::Path::new("/home/u/.ULL"));
+    assert_eq!(layout.config(), PathBuf::from("/home/u/.ULL/config"));
+    assert_eq!(layout.data(), PathBuf::from("/home/u/.ULL/data"));
+    assert_eq!(layout.cache(), PathBuf::from("/home/u/.ULL/cache"));
+    assert_eq!(layout.logs(), PathBuf::from("/home/u/.ULL/logs"));
+
+    assert_eq!(Partition::ALL.len(), 4);
+    assert_eq!(Partition::Config.dir_name(), "config");
+    assert!(Partition::Cache.is_disposable());
+    assert!(!Partition::Config.is_disposable());
+}
+
+#[test]
+fn builds_config_and_cache_paths() {
+    let layout = LauncherLayout::new("/home/u/.ULL");
+    assert_eq!(
+        layout.launcher_config(),
+        PathBuf::from("/home/u/.ULL/config/launcher.json")
+    );
+    assert_eq!(
+        layout.profiles_config(),
+        PathBuf::from("/home/u/.ULL/config/profiles.json")
+    );
+    assert_eq!(
+        layout.sha1_cache("ab"),
+        PathBuf::from("/home/u/.ULL/cache/sha1/ab")
+    );
+    assert_eq!(
+        layout.etag_cache(),
+        PathBuf::from("/home/u/.ULL/cache/etag.json")
+    );
+    assert_eq!(
+        layout.meta_cache(),
+        PathBuf::from("/home/u/.ULL/cache/meta")
+    );
+    assert_eq!(
+        layout.java_managed(),
+        PathBuf::from("/home/u/.ULL/data/java-managed")
+    );
+    assert_eq!(layout.auth_data(), PathBuf::from("/home/u/.ULL/data/auth"));
+    assert_eq!(
+        layout.agent_sessions(),
+        PathBuf::from("/home/u/.ULL/data/agent/sessions")
+    );
+    assert_eq!(
+        layout.redirect_path(),
+        PathBuf::from("/home/u/.ULL/redirect.json")
+    );
+    assert_eq!(
+        layout.migration_receipt(),
+        PathBuf::from("/home/u/.ULL/config/migration-receipt.json")
+    );
+}
+
+#[test]
+fn instance_config_rejects_path_traversal() {
+    let layout = LauncherLayout::new("/home/u/.ULL");
+    let id = "6f9619ff-8b86-d011-b42d-00c04fc964ff";
+    assert!(is_valid_instance_id(id));
+    assert_eq!(
+        layout.instance_config(id).expect("合法 id"),
+        PathBuf::from(format!("/home/u/.ULL/config/instances/{id}.json"))
+    );
+    assert!(layout.instance_config("../escape").is_err());
+    assert!(layout.instance_config("").is_err());
+    assert!(layout.instance_config("a/b").is_err());
+}
+
+#[test]
+fn ensure_creates_all_partitions() {
+    let temp = TempDir::new("layout");
+    let layout = LauncherLayout::new(temp.child(".ULL"));
+    layout.ensure().expect("建目录");
+    for partition in Partition::ALL {
+        assert!(
+            layout.partition(partition).is_dir(),
+            "{}",
+            partition.as_str()
+        );
+    }
+}
+
+#[test]
+fn portable_path_strings_keep_absolute_and_normalise_relative() {
+    use unlucky_core::platform::paths::{from_portable_string, to_portable_string};
+
+    assert_eq!(
+        to_portable_string(std::path::Path::new(".minecraft")),
+        ".minecraft"
+    );
+    assert_eq!(
+        to_portable_string(std::path::Path::new("versions\\1.20.1")),
+        "versions/1.20.1"
+    );
+    let absolute = std::env::temp_dir();
+    assert_eq!(to_portable_string(&absolute), absolute.to_string_lossy());
+    assert_eq!(
+        from_portable_string("versions/1.20.1"),
+        PathBuf::from("versions/1.20.1")
+    );
+}
diff --git a/crates/core/tests/setting/main.rs b/crates/core/tests/setting/main.rs
new file mode 100644
index 0000000..4f54b61
--- /dev/null
+++ b/crates/core/tests/setting/main.rs
@@ -0,0 +1,21 @@
+//! M12（core::setting + platform）集成测试入口。
+//!
+//! cargo 把 `tests/<name>/main.rs` 识别为独立的 test target（target 名 = `setting`），
+//! 因此本目录下每个子模块就是一个测试主题，避免单文件超过 400 行。
+
+mod appearance_keys;
+mod atomic_write;
+mod common;
+mod debounce;
+mod deprecated_keys;
+mod dir_migration;
+mod dirs;
+mod document;
+mod isolation_keys;
+mod java_install_keys;
+mod layout;
+mod migration_chain;
+mod redirect;
+mod schema_compat;
+mod spec_ai;
+mod store;
diff --git a/crates/core/tests/setting/migration_chain.rs b/crates/core/tests/setting/migration_chain.rs
new file mode 100644
index 0000000..3b03401
--- /dev/null
+++ b/crates/core/tests/setting/migration_chain.rs
@@ -0,0 +1,295 @@
+//! 迁移链：N→N+1 顺序校验、真实迁移跑通、收据闸门防重放、store 接线。
+
+use std::path::PathBuf;
+
+use serde_json::{json, Map, Value};
+use unlucky_core::platform::receipt::{
+    decide, fingerprint_bytes, fingerprint_file, read as read_receipt, MigrationReceipt,
+    ReceiptKind, ReplayDecision,
+};
+use unlucky_core::setting::catalog::SettingSchema;
+use unlucky_core::setting::migrate::{
+    MigrationChain, MigrationGate, MigrationReport, SettingMigration,
+};
+use unlucky_core::setting::schema::{
+    SchemaId, SchemaRef, SchemaVersion, SCHEMA_KEY, SCHEMA_VERSION_KEY,
+};
+use unlucky_core::setting::spec::{AiPolicy, SettingSpec};
+use unlucky_core::setting::store::SettingStore;
+
+use crate::common::TempDir;
+
+/// 1.0.0 → 2.0.0：`download.concurrency` 改名 `download.threads`。
+struct RenameThreads;
+
+impl SettingMigration for RenameThreads {
+    fn from(&self) -> SchemaVersion {
+        SchemaVersion::new(1, 0, 0)
+    }
+
+    fn to(&self) -> SchemaVersion {
+        SchemaVersion::new(2, 0, 0)
+    }
+
+    fn describe(&self) -> &'static str {
+        "download.concurrency → download.threads"
+    }
+
+    fn apply(&self, root: &mut Map<String, Value>) -> Result<(), String> {
+        let Some(download) = root.get_mut("download").and_then(Value::as_object_mut) else {
+            return Ok(());
+        };
+        if let Some(value) = download.remove("concurrency") {
+            download.insert("threads".to_owned(), value);
+        }
+        Ok(())
+    }
+}
+
+/// 2.0.0 → 3.0.0：补一个镜像偏好默认值。
+struct AddMirrorPreference;
+
+impl SettingMigration for AddMirrorPreference {
+    fn from(&self) -> SchemaVersion {
+        SchemaVersion::new(2, 0, 0)
+    }
+
+    fn to(&self) -> SchemaVersion {
+        SchemaVersion::new(3, 0, 0)
+    }
+
+    fn describe(&self) -> &'static str {
+        "补齐 download.mirror_preference"
+    }
+
+    fn apply(&self, root: &mut Map<String, Value>) -> Result<(), String> {
+        let Some(download) = root.get_mut("download").and_then(Value::as_object_mut) else {
+            return Err("缺少 download 对象".to_owned());
+        };
+        download
+            .entry("mirror_preference".to_owned())
+            .or_insert_with(|| json!("auto"));
+        Ok(())
+    }
+}
+
+fn two_step_chain() -> MigrationChain {
+    let mut chain = MigrationChain::new();
+    chain.push(Box::new(RenameThreads)).expect("第一环");
+    chain.push(Box::new(AddMirrorPreference)).expect("第二环");
+    chain
+}
+
+#[test]
+fn chain_requires_contiguous_major_steps() {
+    let mut chain = MigrationChain::new();
+    chain
+        .push(Box::new(AddMirrorPreference))
+        .expect("首环随意起点");
+    assert_eq!(chain.len(), 1);
+
+    let err = chain.push(Box::new(RenameThreads)).expect_err("逆序要报错");
+    assert!(err.to_string().contains("顺序错误"), "{err}");
+    assert_eq!(chain.latest(), Some(SchemaVersion::new(3, 0, 0)));
+    assert_eq!(chain.describe().len(), 1);
+    assert!(!chain.is_empty());
+}
+
+#[test]
+fn duplicate_and_skipping_steps_are_rejected() {
+    let mut chain = MigrationChain::new();
+    chain.push(Box::new(RenameThreads)).expect("首环");
+    assert!(chain.push(Box::new(RenameThreads)).is_err(), "重复起始版本");
+    assert!(chain.push(Box::new(AddMirrorPreference)).is_ok());
+
+    struct SkipMajor;
+    impl SettingMigration for SkipMajor {
+        fn from(&self) -> SchemaVersion {
+            SchemaVersion::new(3, 0, 0)
+        }
+        fn to(&self) -> SchemaVersion {
+            SchemaVersion::new(5, 0, 0)
+        }
+        fn describe(&self) -> &'static str {
+            "跳版本（非法）"
+        }
+        fn apply(&self, _root: &mut Map<String, Value>) -> Result<(), String> {
+            Ok(())
+        }
+    }
+    let err = chain
+        .push(Box::new(SkipMajor))
+        .expect_err("跨两个 major 要报错");
+    assert!(err.to_string().contains("major"), "{err}");
+}
+
+#[test]
+fn migrates_sequentially_and_bumps_schema_version() {
+    let chain = two_step_chain();
+    let mut root = json!({ "download": { "concurrency": 32 } })
+        .as_object()
+        .cloned()
+        .expect("对象");
+    root.insert(SCHEMA_VERSION_KEY.to_owned(), json!(1));
+
+    let report = chain
+        .migrate(SchemaVersion::new(1, 0, 0), &mut root)
+        .expect("迁移");
+    assert_eq!(
+        report,
+        MigrationReport {
+            from: SchemaVersion::new(1, 0, 0),
+            to: SchemaVersion::new(3, 0, 0),
+            applied: vec![
+                "download.concurrency → download.threads",
+                "补齐 download.mirror_preference",
+            ],
+        }
+    );
+    assert!(!report.is_noop());
+    assert_eq!(root["download"]["threads"], json!(32));
+    assert_eq!(root["download"]["mirror_preference"], json!("auto"));
+    assert!(root["download"].get("concurrency").is_none());
+    assert_eq!(root[SCHEMA_VERSION_KEY], json!(3));
+}
+
+#[test]
+fn unknown_start_version_breaks_the_chain() {
+    let chain = two_step_chain();
+    let mut root = Map::new();
+    let err = chain
+        .migrate(SchemaVersion::new(9, 0, 0), &mut root)
+        .expect_err("没有 9.0.0 起始步");
+    assert!(err.to_string().contains("链里没有"), "{err}");
+    assert!(chain.plan_from(SchemaVersion::new(2, 0, 0)).is_ok());
+}
+
+#[test]
+fn failing_step_reports_migration_error() {
+    let mut chain = MigrationChain::new();
+    chain.push(Box::new(RenameThreads)).expect("第一环");
+    chain.push(Box::new(AddMirrorPreference)).expect("第二环");
+
+    let mut root = json!({ "download": 3 }).as_object().cloned().expect("对象");
+    let err = chain
+        .migrate(SchemaVersion::new(1, 0, 0), &mut root)
+        .expect_err("download 不是对象");
+    assert!(err.to_string().contains("迁移"), "{err}");
+}
+
+#[test]
+fn receipt_gate_prevents_replay() {
+    let temp = TempDir::new("migration-gate");
+    let source = temp.write("legacy/hmcl.json", "{\"x\":1}");
+    let target = temp.child("config/launcher.json");
+    let fingerprint = fingerprint_file(&source).expect("算指纹").expect("文件在");
+
+    let receipt_path = temp.child("config/migration-receipt.json");
+    let gate = MigrationGate::new(&receipt_path, 1_700_000_000_000);
+    assert_eq!(gate.now_ms(), 1_700_000_000_000);
+    assert!(gate.should_run(&fingerprint).expect("无收据"));
+
+    let receipt =
+        MigrationReceipt::legacy_config(source, target, fingerprint.clone(), gate.now_ms());
+    gate.record(&receipt).expect("写收据");
+    assert!(!gate.should_run(&fingerprint).expect("同源指纹应跳过"));
+    assert_eq!(
+        gate.evaluate(&fingerprint).expect("评估"),
+        ReplayDecision::SkipSameSource
+    );
+    assert_eq!(
+        gate.evaluate("其他指纹").expect("评估"),
+        ReplayDecision::ReplayChangedSource
+    );
+
+    let stored = read_receipt(&receipt_path)
+        .expect("读收据")
+        .expect("有收据");
+    assert_eq!(stored.kind, ReceiptKind::LegacyConfig);
+    assert_eq!(stored.source_fingerprint, fingerprint);
+}
+
+#[test]
+fn receipt_decisions_and_fingerprints() {
+    let receipt = MigrationReceipt::legacy_config(
+        PathBuf::from("/a"),
+        PathBuf::from("/b"),
+        fingerprint_bytes(b"abc"),
+        7,
+    );
+    assert_eq!(decide(None, "x"), ReplayDecision::ReplayNoReceipt);
+    assert_eq!(
+        decide(Some(&receipt), &fingerprint_bytes(b"abc")),
+        ReplayDecision::SkipSameSource
+    );
+    assert_eq!(
+        decide(Some(&receipt), "changed"),
+        ReplayDecision::ReplayChangedSource
+    );
+    assert_eq!(ReplayDecision::SkipSameSource.as_str(), "skip_same_source");
+    assert!(!ReplayDecision::SkipSameSource.should_replay());
+    assert_eq!(fingerprint_bytes(b"abc").len(), 64);
+    assert_ne!(
+        unlucky_core::platform::receipt::fingerprint_data_dir_move(
+            &PathBuf::from("/a"),
+            &PathBuf::from("/b")
+        ),
+        unlucky_core::platform::receipt::fingerprint_data_dir_move(
+            &PathBuf::from("/a"),
+            &PathBuf::from("/c")
+        )
+    );
+}
+
+fn schema_v2() -> SettingSchema {
+    SettingSchema::new(SchemaId::LAUNCHER, SchemaVersion::new(2, 0, 0)).with(SettingSpec::int(
+        "download.threads",
+        8,
+        (1, 256),
+        AiPolicy::silent(),
+        "下载并发数（2.0.0 起的键名）",
+    ))
+}
+
+#[test]
+fn store_applies_chain_then_saves_new_version() {
+    let temp = TempDir::new("migration-store");
+    let old_url = SchemaRef::new(SchemaId::LAUNCHER, SchemaVersion::new(1, 0, 0)).url();
+    temp.write(
+        "config/launcher.json",
+        &json!({
+            SCHEMA_KEY: old_url,
+            SCHEMA_VERSION_KEY: 1,
+            "download": { "concurrency": 32 }
+        })
+        .to_string(),
+    );
+
+    let mut store = SettingStore::load(temp.child("config/launcher.json"), schema_v2());
+    assert_eq!(store.doc().version(), SchemaVersion::new(1, 0, 0));
+    assert!(!store.is_dirty(), "加载不是改动");
+
+    let mut chain = MigrationChain::new();
+    chain.push(Box::new(RenameThreads)).expect("一环足矣");
+    let report = store.apply_chain(&chain).expect("迁移").expect("有迁移");
+    assert_eq!(report.to, SchemaVersion::new(2, 0, 0));
+    assert_eq!(store.doc().version(), SchemaVersion::new(2, 0, 0));
+    assert_eq!(
+        store.effective("download.threads"),
+        Some(&json!(32)),
+        "值要跟着键名一起搬"
+    );
+    assert!(store.is_dirty(), "迁移结果必须回写");
+
+    store.save().expect("保存");
+    let saved: Value = serde_json::from_str(&temp.read("config/launcher.json")).expect("JSON");
+    assert_eq!(saved[SCHEMA_VERSION_KEY], json!(2));
+    assert!(saved[SCHEMA_KEY]
+        .as_str()
+        .expect("$schema")
+        .ends_with("launcher/2.0.0"));
+    assert_eq!(saved["download"]["threads"], json!(32));
+
+    let mut up_to_date = SettingStore::load(temp.child("config/launcher.json"), schema_v2());
+    assert!(up_to_date.apply_chain(&chain).expect("已最新").is_none());
+}
diff --git a/crates/core/tests/setting/redirect.rs b/crates/core/tests/setting/redirect.rs
new file mode 100644
index 0000000..1b30023
--- /dev/null
+++ b/crates/core/tests/setting/redirect.rs
@@ -0,0 +1,88 @@
+//! `redirect.json`：写/读/跟随/成环/损坏/版本更高。
+
+use std::path::PathBuf;
+
+use unlucky_core::platform::data_dir::DataMode;
+use unlucky_core::platform::error::PlatformError;
+use unlucky_core::platform::redirect::{
+    follow, read, redirect_path, remove, write, RedirectPointer, REDIRECT_SCHEMA_VERSION,
+};
+
+use crate::common::TempDir;
+
+fn pointer(target: &str) -> RedirectPointer {
+    RedirectPointer {
+        schema_version: REDIRECT_SCHEMA_VERSION,
+        mode: DataMode::Standard,
+        launcher_home: PathBuf::from(target),
+        game_home: PathBuf::from(target).join(".minecraft"),
+        migrated_at_ms: 1_700_000_000_000,
+    }
+}
+
+#[test]
+fn round_trips_pointer_file() {
+    let temp = TempDir::new("redirect");
+    let origin = temp.child(".ULL");
+    assert_eq!(read(&origin).expect("读空目录"), None);
+
+    let written = write(&origin, &pointer("/elsewhere/.ULL")).expect("写指针");
+    assert_eq!(written, redirect_path(&origin));
+    assert!(origin.join("redirect.json").is_file());
+
+    let loaded = read(&origin).expect("读指针").expect("有指针");
+    assert_eq!(loaded, pointer("/elsewhere/.ULL"));
+    assert!(remove(&origin).expect("删指针"));
+    assert!(!remove(&origin).expect("再删一次"));
+}
+
+#[test]
+fn follows_chain_to_final_target() {
+    let temp = TempDir::new("redirect-chain");
+    let first = temp.child("a");
+    let second = temp.child("b");
+    let third = temp.child("c");
+
+    write(&first, &pointer(&second.to_string_lossy())).expect("写 a");
+    write(&second, &pointer(&third.to_string_lossy())).expect("写 b");
+
+    let followed = follow(&first, 8).expect("跟随").expect("有指针");
+    assert_eq!(followed.hops, 2);
+    assert_eq!(followed.pointer.launcher_home, third);
+}
+
+#[test]
+fn detects_redirect_cycle() {
+    let temp = TempDir::new("redirect-cycle");
+    let first = temp.child("a");
+    let second = temp.child("b");
+    write(&first, &pointer(&second.to_string_lossy())).expect("写 a");
+    write(&second, &pointer(&first.to_string_lossy())).expect("写 b");
+
+    let err = follow(&first, 8).expect_err("应当成环报错");
+    assert!(matches!(err, PlatformError::RedirectCycle { .. }), "{err}");
+}
+
+#[test]
+fn rejects_corrupt_and_newer_pointer() {
+    let temp = TempDir::new("redirect-corrupt");
+    let dir = temp.child(".ULL");
+    std::fs::create_dir_all(&dir).expect("建目录");
+    std::fs::write(dir.join("redirect.json"), b"{not json").expect("写坏文件");
+    assert!(matches!(
+        read(&dir).expect_err("坏文件应报错"),
+        PlatformError::RedirectCorrupt { .. }
+    ));
+
+    let mut newer = pointer("/newer/.ULL");
+    newer.schema_version = REDIRECT_SCHEMA_VERSION + 1;
+    std::fs::write(
+        dir.join("redirect.json"),
+        serde_json::to_vec(&newer).expect("序列化"),
+    )
+    .expect("写文件");
+    assert!(matches!(
+        read(&dir).expect_err("新版本指针应报错"),
+        PlatformError::RedirectCorrupt { .. }
+    ));
+}
diff --git a/crates/core/tests/setting/schema_compat.rs b/crates/core/tests/setting/schema_compat.rs
new file mode 100644
index 0000000..96fdcfe
--- /dev/null
+++ b/crates/core/tests/setting/schema_compat.rs
@@ -0,0 +1,120 @@
+//! schema 版本标识、8 态兼容判定、三档访问权映射。
+
+use serde_json::json;
+use unlucky_core::setting::keys::launcher_schema;
+use unlucky_core::setting::schema::{
+    FileAccess, SchemaCompat, SchemaId, SchemaRef, SchemaVersion, SCHEMA_KEY,
+};
+
+fn expected() -> SchemaRef {
+    SchemaRef::new(SchemaId::LAUNCHER, SchemaVersion::new(1, 2, 3))
+}
+
+fn compat_of(version: SchemaVersion) -> SchemaCompat {
+    let url = SchemaRef::new(SchemaId::LAUNCHER, version).url();
+    SchemaCompat::check(&json!({ SCHEMA_KEY: url }), expected())
+}
+
+#[test]
+fn version_parsing_and_ordering() {
+    let version = SchemaVersion::parse("1.2.3").expect("解析");
+    assert_eq!(version, SchemaVersion::new(1, 2, 3));
+    assert_eq!(version.to_string(), "1.2.3");
+    assert_eq!(version.next_major(), SchemaVersion::new(2, 0, 0));
+    assert!(SchemaVersion::parse("1.2").is_none());
+    assert!(SchemaVersion::parse("1.2.3.4").is_none());
+    assert!(SchemaVersion::new(1, 2, 3) < SchemaVersion::new(1, 3, 0));
+}
+
+#[test]
+fn schema_url_round_trip() {
+    let reference = launcher_schema().schema_ref();
+    let url = reference.url();
+    assert!(
+        url.ends_with(&format!("launcher/{}", reference.version)),
+        "{url}"
+    );
+    assert_eq!(SchemaRef::parse_url(&url), Some(reference));
+    assert!(SchemaRef::parse_url("https://example.com/x").is_none());
+    assert!(SchemaRef::parse_url("garbage").is_none());
+    assert_eq!(SchemaId::parse("instance"), Some(SchemaId::INSTANCE));
+    assert!(SchemaId::parse("nope").is_none());
+}
+
+#[test]
+fn same_or_older_versions_are_read_write() {
+    assert_eq!(
+        compat_of(SchemaVersion::new(1, 2, 3)),
+        SchemaCompat::ReadWrite
+    );
+    assert_eq!(
+        compat_of(SchemaVersion::new(1, 2, 2)),
+        SchemaCompat::ReadWrite
+    );
+    assert_eq!(
+        compat_of(SchemaVersion::new(1, 0, 0)),
+        SchemaCompat::ReadWrite
+    );
+    assert_eq!(
+        compat_of(SchemaVersion::new(0, 9, 0)),
+        SchemaCompat::ReadWrite
+    );
+}
+
+#[test]
+fn newer_patch_keeps_original_schema() {
+    let compat = compat_of(SchemaVersion::new(1, 2, 4));
+    assert_eq!(compat, SchemaCompat::ReadWritePreserveSchema);
+    assert!(compat.preserve_schema());
+    assert_eq!(compat.access(), FileAccess::ReadWrite);
+}
+
+#[test]
+fn newer_minor_is_read_only() {
+    let compat = compat_of(SchemaVersion::new(1, 3, 0));
+    assert_eq!(compat, SchemaCompat::ReadOnlyPreserveSchema);
+    assert!(compat.preserve_schema());
+    assert_eq!(compat.access(), FileAccess::ReadOnly);
+    assert!(!compat.access().can_save());
+    assert!(compat.access().blocks_editing());
+}
+
+#[test]
+fn newer_major_is_unreadable() {
+    let compat = compat_of(SchemaVersion::new(2, 0, 0));
+    assert_eq!(compat, SchemaCompat::UnsupportedMajor);
+    assert!(!compat.readable());
+    assert_eq!(compat.access(), FileAccess::Unreadable);
+    assert!(!compat.access().can_read());
+}
+
+#[test]
+fn other_ids_and_broken_urls_are_rejected() {
+    let instance_url = SchemaRef::new(SchemaId::INSTANCE, SchemaVersion::new(1, 0, 0)).url();
+    assert_eq!(
+        SchemaCompat::check(&json!({ SCHEMA_KEY: instance_url }), expected()),
+        SchemaCompat::UnexpectedId
+    );
+    assert_eq!(
+        SchemaCompat::check(&json!({ SCHEMA_KEY: "not-a-url" }), expected()),
+        SchemaCompat::Invalid
+    );
+    assert_eq!(
+        SchemaCompat::check(&json!({ "schemaVersion": 1 }), expected()),
+        SchemaCompat::Missing
+    );
+    assert_eq!(SchemaCompat::Unparseable.access(), FileAccess::Unreadable);
+}
+
+#[test]
+fn access_three_tiers() {
+    assert!(FileAccess::ReadWrite.can_read() && FileAccess::ReadWrite.can_save());
+    assert!(FileAccess::ReadOnly.can_read() && !FileAccess::ReadOnly.can_save());
+    assert!(!FileAccess::Unreadable.can_read());
+    assert!(FileAccess::Unreadable.blocks_editing());
+    assert_eq!(FileAccess::ReadOnly.as_str(), "read_only");
+    assert_eq!(
+        SchemaCompat::ReadOnlyPreserveSchema.as_str(),
+        "read_only_preserve_schema"
+    );
+}
diff --git a/crates/core/tests/setting/spec_ai.rs b/crates/core/tests/setting/spec_ai.rs
new file mode 100644
index 0000000..92c2d19
--- /dev/null
+++ b/crates/core/tests/setting/spec_ai.rs
@@ -0,0 +1,178 @@
+//! 键元数据：AI 可写白名单、敏感分级、类型/范围校验、工具 JSON Schema。
+
+use serde_json::json;
+use unlucky_core::setting::catalog::SettingSchema;
+use unlucky_core::setting::instance_keys::{instance_schema, profiles_schema};
+use unlucky_core::setting::keys::launcher_schema;
+use unlucky_core::setting::schema::{SchemaId, SchemaVersion};
+use unlucky_core::setting::spec::{AiPolicy, Sensitivity, SettingSpec, ValueKind};
+
+#[test]
+fn ai_whitelist_excludes_credentials() {
+    let schema = launcher_schema();
+    let writable = schema.ai_writable_keys();
+    assert!(writable.contains(&"download.concurrency"));
+    assert!(writable.contains(&"appearance.theme_mode"));
+    assert!(!writable.contains(&"ai.api_key"), "凭据永不可写（D9）");
+
+    assert!(schema.accepts_ai_write("java.selected_path"));
+    assert!(!schema.accepts_ai_write("ai.api_key"));
+    assert!(!schema.accepts_ai_write("not.a.key"));
+}
+
+#[test]
+fn sensitivity_grades_are_flagged() {
+    let schema = launcher_schema();
+    assert_eq!(
+        schema.sensitivity("core.data_mode"),
+        Some(Sensitivity::High)
+    );
+    assert_eq!(
+        schema.sensitivity("download.concurrency"),
+        Some(Sensitivity::Low)
+    );
+    assert_eq!(schema.sensitivity("ai.model"), Some(Sensitivity::Medium));
+    assert_eq!(schema.sensitivity("ai.api_key"), Some(Sensitivity::High));
+    assert!(Sensitivity::High.requires_confirmation());
+    assert!(!Sensitivity::Low.requires_confirmation());
+    assert_eq!(Sensitivity::Medium.as_str(), "medium");
+}
+
+#[test]
+fn validates_types_ranges_and_enums() {
+    let schema = launcher_schema();
+    assert!(schema.validate("download.concurrency", &json!(8)).is_ok());
+    assert!(schema.validate("download.concurrency", &json!(0)).is_err());
+    assert!(schema
+        .validate("download.concurrency", &json!(257))
+        .is_err());
+    assert!(schema
+        .validate("download.concurrency", &json!("8"))
+        .is_err());
+    assert!(schema
+        .validate("appearance.theme_mode", &json!("dark"))
+        .is_ok());
+    assert!(schema
+        .validate("appearance.theme_mode", &json!("solarized"))
+        .is_err());
+    // 废弃键仍然「读兼容合法」——旧文件里的值不该被判成非法。
+    assert!(schema.validate("ui.theme", &json!("metro_dark")).is_ok());
+    assert!(schema.validate("ui.theme", &json!("auto")).is_err());
+    assert!(schema.validate("ui.scale", &json!(1.5)).is_ok());
+    assert!(schema.validate("ui.scale", &json!(9.0)).is_err());
+
+    let err = schema.validate("nope.key", &json!(1)).expect_err("未知键");
+    assert!(err.to_string().contains("nope.key"));
+}
+
+#[test]
+fn value_kinds_cover_all_variants() {
+    assert!(ValueKind::Int { min: 1, max: 2 }.check(&json!(2)).is_ok());
+    assert!(ValueKind::Int { min: 1, max: 2 }.check(&json!(3)).is_err());
+    assert!(ValueKind::Float { min: 0.0, max: 1.0 }
+        .check(&json!(0.5))
+        .is_ok());
+    assert!(ValueKind::Text { max_len: 2 }.check(&json!("ab")).is_ok());
+    assert!(ValueKind::Text { max_len: 2 }.check(&json!("abc")).is_err());
+    assert!(ValueKind::Path.check(&json!("  ")).is_err());
+    assert!(ValueKind::Path
+        .check(&json!("C:/java/bin/java.exe"))
+        .is_ok());
+    assert!(ValueKind::TextList.check(&json!(["a", "b"])).is_ok());
+    assert!(ValueKind::TextList.check(&json!([1])).is_err());
+    assert!(ValueKind::Any.check(&json!({"whatever": 1})).is_ok());
+}
+
+#[test]
+fn json_schema_projection_feeds_tool_specs() {
+    let schema = launcher_schema();
+    let projected = schema.to_json_schema();
+    assert_eq!(projected["type"], json!("object"));
+    assert_eq!(projected["additionalProperties"], json!(false));
+
+    let properties = projected["properties"].as_object().expect("properties");
+    assert!(properties.contains_key("download.concurrency"));
+    assert!(!properties.contains_key("ai.api_key"), "锁定键不进工具参数");
+    assert_eq!(properties["download.concurrency"]["type"], json!("integer"));
+    assert_eq!(properties["download.concurrency"]["default"], json!(8));
+    assert_eq!(
+        properties["download.concurrency"]["x-ai-sensitivity"],
+        json!("low")
+    );
+    assert_eq!(properties["appearance.theme_mode"]["type"], json!("string"));
+}
+
+#[test]
+fn top_level_keys_and_defaults() {
+    let schema = launcher_schema();
+    let tops = schema.top_level_keys();
+    for expected in ["core", "download", "java", "ai", "ui", "log"] {
+        assert!(tops.contains(expected), "缺少顶层键组 {expected}");
+    }
+    assert_eq!(
+        schema.default_value("download.concurrency"),
+        Some(&json!(8))
+    );
+    assert_eq!(
+        schema.default_value("java.selected_path"),
+        Some(&json!(null))
+    );
+    assert!(schema.spec("download.concurrency").is_some());
+    assert!(schema.has_prefix(&["download"]));
+    assert!(!schema.has_prefix(&["nope"]));
+}
+
+#[test]
+fn instance_and_profiles_schemas_are_usable() {
+    let instance = instance_schema();
+    assert_eq!(instance.id(), SchemaId::INSTANCE);
+    // D20：实例键表统一成 camelCase 扁平形态（与 game::install::instance 的 serde 逐键一致）。
+    assert!(instance.is_known("versionId"));
+    assert!(instance.is_known("isolation"));
+    assert!(instance.is_known("lastModeChange.probe.isolatedSide"));
+    assert!(instance.accepts_ai_write("isolation"));
+    assert!(
+        !instance.accepts_ai_write("lastModeChange.at"),
+        "切换记录由启动器写，AI 不许改"
+    );
+    assert!(instance.validate("isolation", &json!("isolated")).is_ok());
+    assert!(instance.validate("isolation", &json!("inherit")).is_ok());
+    assert!(instance.validate("isolation", &json!("maybe")).is_err());
+    assert!(
+        instance
+            .validate("isolation", &json!("per_version"))
+            .is_err(),
+        "旧字面量由 game 侧读兼容，schema 白名单只认新值"
+    );
+
+    let profiles = profiles_schema();
+    assert_eq!(profiles.id(), SchemaId::PROFILES);
+    assert_eq!(
+        profiles.spec("profiles").expect("profiles 键").kind,
+        ValueKind::Any
+    );
+    assert!(
+        !profiles.accepts_ai_write("profiles"),
+        "列表本体不许 AI 整体改写"
+    );
+    assert!(profiles.accepts_ai_write("selected_profile_id"));
+}
+
+#[test]
+#[should_panic(expected = "重复的配置键")]
+fn duplicate_key_is_a_table_bug() {
+    let schema = SettingSchema::new(SchemaId::LAUNCHER, SchemaVersion::new(9, 0, 0))
+        .with(SettingSpec::bool(
+            "dup.key",
+            true,
+            AiPolicy::silent(),
+            "第一次",
+        ))
+        .with(SettingSpec::bool(
+            "dup.key",
+            false,
+            AiPolicy::silent(),
+            "第二次",
+        ));
+    assert_eq!(schema.specs().len(), 2);
+}
diff --git a/crates/core/tests/setting/store.rs b/crates/core/tests/setting/store.rs
new file mode 100644
index 0000000..19f8974
--- /dev/null
+++ b/crates/core/tests/setting/store.rs
@@ -0,0 +1,259 @@
+//! 配置文件的加载降级、只写脏字段、坏文件备份、只读/不可读三档行为。
+
+use serde_json::{json, Value};
+use unlucky_core::setting::document::LoadProblem;
+use unlucky_core::setting::keys::{launcher_schema, launcher_version};
+use unlucky_core::setting::schema::{
+    FileAccess, SchemaCompat, SchemaId, SchemaRef, SchemaVersion, SCHEMA_KEY, SCHEMA_VERSION_KEY,
+};
+use unlucky_core::setting::store::{SaveOutcome, SettingStore, SkipReason};
+
+use crate::common::TempDir;
+
+fn schema_url(version: SchemaVersion) -> String {
+    SchemaRef::new(SchemaId::LAUNCHER, version).url()
+}
+
+fn read_json(temp: &TempDir, name: &str) -> Value {
+    serde_json::from_str(&temp.read(name)).expect("配置文件是合法 JSON")
+}
+
+#[test]
+fn first_run_starts_writable_with_defaults() {
+    let temp = TempDir::new("store-new");
+    let path = temp.child("config/launcher.json");
+    let store = SettingStore::load(&path, launcher_schema());
+
+    assert_eq!(store.access(), FileAccess::ReadWrite);
+    assert_eq!(store.compat(), SchemaCompat::Missing);
+    assert!(store.problems().is_empty());
+    assert_eq!(
+        store.effective("download.concurrency"),
+        Some(&json!(8)),
+        "首次运行用默认值"
+    );
+    assert!(!path.exists(), "只读加载不该创建文件");
+}
+
+#[test]
+fn saves_only_when_dirty_and_writes_schema_markers() {
+    let temp = TempDir::new("store-save");
+    let path = temp.child("config/launcher.json");
+    let mut store = SettingStore::load(&path, launcher_schema());
+
+    assert_eq!(
+        store.save().expect("空保存"),
+        SaveOutcome::Skipped(SkipReason::NotDirty)
+    );
+
+    store
+        .set("download.concurrency", json!(16))
+        .expect("改配置");
+    let outcome = store.save().expect("保存");
+    assert!(outcome.wrote());
+
+    let raw = read_json(&temp, "config/launcher.json");
+    assert_eq!(raw["download"]["concurrency"], json!(16));
+    assert_eq!(raw[SCHEMA_VERSION_KEY], json!(1));
+    assert!(
+        raw[SCHEMA_KEY]
+            .as_str()
+            .expect("$schema")
+            .ends_with(&format!("launcher/{}", launcher_schema().version())),
+        "保存写当前 schema 版本"
+    );
+    assert!(raw.get("ai").is_none(), "默认值不进文件");
+    assert!(!store.is_dirty(), "保存后清脏");
+
+    let reloaded = SettingStore::load(&path, launcher_schema());
+    assert_eq!(reloaded.effective("download.concurrency"), Some(&json!(16)));
+}
+
+#[test]
+fn preserves_unknown_keys_across_save() {
+    let temp = TempDir::new("store-unknown");
+    let raw = json!({
+        SCHEMA_KEY: schema_url(SchemaVersion::new(1, 0, 0)),
+        SCHEMA_VERSION_KEY: 1,
+        "download": { "concurrency": 4 },
+        "from_the_future": { "flag": true }
+    });
+    temp.write("config/launcher.json", &raw.to_string());
+
+    let mut store = SettingStore::load(temp.child("config/launcher.json"), launcher_schema());
+    assert!(
+        store.problems().iter().any(
+            |problem| matches!(problem, LoadProblem::UnknownKey { key } if key == "from_the_future")
+        ),
+        "陌生顶层子树按最上层节点报一次: {:?}",
+        store.problems()
+    );
+
+    store
+        .set("download.concurrency", json!(12))
+        .expect("改配置");
+    store.save().expect("保存");
+
+    let after = read_json(&temp, "config/launcher.json");
+    assert_eq!(after["download"]["concurrency"], json!(12));
+    assert_eq!(after["from_the_future"]["flag"], json!(true));
+}
+
+#[test]
+fn corrupt_file_is_backed_up_before_overwrite() {
+    let temp = TempDir::new("store-corrupt");
+    temp.write("config/launcher.json", "{ definitely not json");
+
+    let mut store = SettingStore::load(temp.child("config/launcher.json"), launcher_schema());
+    assert_eq!(store.compat(), SchemaCompat::Unparseable);
+    assert_eq!(
+        store.access(),
+        FileAccess::ReadWrite,
+        "坏文件要能修，否则用户被永久卡住"
+    );
+    assert_eq!(store.effective("download.concurrency"), Some(&json!(8)));
+
+    store.set("ui.language", json!("en_us")).expect("改配置");
+    store.save().expect("保存");
+
+    assert!(temp.exists("config/launcher.json.1"), "坏文件先备份成 .1");
+    let raw = read_json(&temp, "config/launcher.json");
+    assert_eq!(raw["ui"]["language"], json!("en_us"));
+}
+
+#[test]
+fn newer_minor_is_read_only_and_keeps_its_schema() {
+    let temp = TempDir::new("store-readonly");
+    // 比当前 schema 高一个 minor（**相对构造**：版本号涨了这条也不会假绿）：只读且保留原 $schema。
+    let current = launcher_version();
+    let url = schema_url(SchemaVersion::new(current.major, current.minor + 1, 0));
+    temp.write(
+        "config/launcher.json",
+        &json!({ SCHEMA_KEY: url, "download": { "concurrency": 32 } }).to_string(),
+    );
+
+    let mut store = SettingStore::load(temp.child("config/launcher.json"), launcher_schema());
+    assert_eq!(store.compat(), SchemaCompat::ReadOnlyPreserveSchema);
+    assert_eq!(store.access(), FileAccess::ReadOnly);
+    assert_eq!(
+        store.effective("download.concurrency"),
+        Some(&json!(32)),
+        "只读档的值照读"
+    );
+    assert!(store.set("download.concurrency", json!(1)).is_err());
+    assert_eq!(
+        store.save().expect("只读保存"),
+        SaveOutcome::Skipped(SkipReason::ReadOnly)
+    );
+
+    store.save_forced().expect("用户确认强写");
+    assert_eq!(store.access(), FileAccess::ReadWrite);
+    let raw = read_json(&temp, "config/launcher.json");
+    assert_eq!(
+        raw[SCHEMA_KEY].as_str().expect("$schema"),
+        url,
+        "更 minor 的文件强写后也要保留原 $schema（与构造出来的那个 url 逐字相同）"
+    );
+}
+
+#[test]
+fn higher_major_is_unreadable_until_forced() {
+    let temp = TempDir::new("store-unreadable");
+    let url = schema_url(SchemaVersion::new(2, 0, 0));
+    temp.write(
+        "config/launcher.json",
+        &json!({ SCHEMA_KEY: url, "brand_new": { "thing": 1 } }).to_string(),
+    );
+
+    let mut store = SettingStore::load(temp.child("config/launcher.json"), launcher_schema());
+    assert_eq!(store.compat(), SchemaCompat::UnsupportedMajor);
+    assert_eq!(store.access(), FileAccess::Unreadable);
+    assert!(
+        store.set("appearance.theme_mode", json!("dark")).is_err(),
+        "不可读档全程不写"
+    );
+    assert_eq!(
+        store.save().expect("不可读保存"),
+        SaveOutcome::Skipped(SkipReason::Unreadable)
+    );
+
+    store.save_forced().expect("用户确认强写");
+    assert!(temp.exists("config/launcher.json.1"));
+    assert_eq!(store.access(), FileAccess::ReadWrite);
+}
+
+#[test]
+fn reload_discards_in_memory_changes() {
+    let temp = TempDir::new("store-reload");
+    let path = temp.write(
+        "config/launcher.json",
+        &json!({ SCHEMA_KEY: schema_url(SchemaVersion::new(1, 0, 0)), "appearance": { "theme_mode": "light" } })
+            .to_string(),
+    );
+
+    let mut store = SettingStore::load(&path, launcher_schema());
+    store
+        .set("appearance.theme_mode", json!("dark"))
+        .expect("改配置");
+    assert!(store.is_dirty());
+    store.reload();
+    assert!(!store.is_dirty());
+    assert_eq!(
+        store.effective("appearance.theme_mode"),
+        Some(&json!("light"))
+    );
+}
+
+#[test]
+fn backup_paths_increment() {
+    let temp = TempDir::new("store-backup");
+    temp.write("config/launcher.json.1", "old");
+    temp.write("config/launcher.json.2", "older");
+    let store = SettingStore::load(temp.child("config/launcher.json"), launcher_schema());
+    let next = store.next_backup_path();
+    assert!(next.to_string_lossy().ends_with(".3"), "{next:?}");
+}
+
+/// finding 20261030-worker-java2-bug-schema-launcher-json-loadproblem：
+/// `$schema` 前缀写错（手写/脚本生成的配置最常见的错）曾让整份文件静默回落默认值。
+/// M40 起：值照读 + `UnknownSchema` 告警 + 文件只读（不悄悄改写我们看不懂的文件）。
+#[test]
+fn unknown_schema_prefix_warns_but_keeps_file_values() {
+    let temp = TempDir::new("store-unknown-schema");
+    let url = "https://unlucky-launcher.local/schema/launcher/1.2.0.json";
+    temp.write(
+        "config/launcher.json",
+        &json!({
+            SCHEMA_KEY: url,
+            "core": { "data_mode": "standard" },
+            "download": { "concurrency": 32 },
+        })
+        .to_string(),
+    );
+
+    let mut store = SettingStore::load(temp.child("config/launcher.json"), launcher_schema());
+    assert_eq!(store.compat(), SchemaCompat::Invalid);
+    assert_eq!(store.access(), FileAccess::ReadOnly);
+    assert_eq!(
+        store.effective("download.concurrency"),
+        Some(&json!(32)),
+        "认不出 $schema 也要读文件里的值"
+    );
+    assert!(
+        store.problems().iter().any(
+            |problem| matches!(problem, LoadProblem::UnknownSchema { url: found } if found == url)
+        ),
+        "{:?}",
+        store.problems()
+    );
+    assert!(
+        store.problems()[0].to_string().contains("$schema"),
+        "{}",
+        store.problems()[0]
+    );
+    assert!(store.set("download.concurrency", json!(1)).is_err());
+    assert_eq!(
+        store.save().expect("只读保存"),
+        SaveOutcome::Skipped(SkipReason::ReadOnly)
+    );
+}
diff --git a/crates/design/Cargo.toml b/crates/design/Cargo.toml
new file mode 100644
index 0000000..6fcad9a
--- /dev/null
+++ b/crates/design/Cargo.toml
@@ -0,0 +1,19 @@
+[package]
+name = "unlucky-design"
+description = "Unlucky-Launcher 设计令牌：M3 Expressive 色彩/排版/形状/高程/动效/图标，纯数据 + 纯函数，零 UI 依赖"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+publish.workspace = true
+
+# 零 UI 依赖是硬约束（D3 纪律 + M61）：本 crate 是渲染无关的**数据与纯函数**，
+# 不得出现 iced / slint / winit / wgpu / gtk / egui / tauri 等 UI 或渲染框架，
+# 也不引入任何第三方 crate（连 serde 都不加——序列化由消费方适配层自己做）。
+# 证据命令：cargo tree -p unlucky-design --edges normal
+[dependencies]
+
+[lints]
+workspace = true
diff --git a/crates/design/src/color/cam16.rs b/crates/design/src/color/cam16.rs
new file mode 100644
index 0000000..3a0650c
--- /dev/null
+++ b/crates/design/src/color/cam16.rs
@@ -0,0 +1,120 @@
+//! CAM16 正向换算：sRGB 色值 → CAM16 的 **hue**（色相角）与 **chroma**（彩度）。
+//!
+//! HCT = **H**ue / **C**hroma from CAM16 + **T**one from `L*`。这里只实现 M3 用到的方向
+//! （色值 → hue/chroma）；反向（hue/chroma/tone → 色值）在 [`super::hct_solver`] 里按官方
+//! 求解器内联实现——两边如果各写一份，数值会对不上。
+//!
+//! 照搬 `java/hct/Cam16.java`（Apache-2.0，见 `NOTICE`），逐行对应，包括 `Math.signum` 的
+//! 「零返回 0」这种 Java 语义差别（见 [`space::signum`]）。
+
+use super::space::{self, signum};
+use super::viewing_conditions::{default_conditions, ViewingConditions};
+use super::Color;
+
+/// XYZ → CAM16 的「锥体响应」矩阵。
+pub(crate) const XYZ_TO_CAM16_RGB: [[f64; 3]; 3] = [
+    [0.401_288, 0.650_173, -0.051_461],
+    [-0.250_268, 1.204_414, 0.045_854],
+    [-0.002_079, 0.048_952, 0.953_127],
+];
+
+/// CAM16 里 M3 真正用到的两个坐标（`J` 明度不参与 HCT，HCT 的 tone 走 `L*`）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub(crate) struct Cam16 {
+    /// 色相角（度，`0..360`）。
+    pub(crate) hue: f64,
+    /// 彩度（无上限；sRGB 立方体内最大值约 130）。
+    pub(crate) chroma: f64,
+}
+
+impl Cam16 {
+    /// 从色值取 CAM16 色相/彩度（默认 sRGB 观察条件）。
+    pub(crate) fn from_color(color: Color) -> Self {
+        Self::from_xyz(space::xyz_from_color(color), default_conditions())
+    }
+
+    /// 从 XYZ 取 CAM16 色相/彩度。
+    pub(crate) fn from_xyz(xyz: [f64; 3], vc: &ViewingConditions) -> Self {
+        let [r_t, g_t, b_t] = space::matrix_multiply(xyz, XYZ_TO_CAM16_RGB);
+
+        // 折扣光源（色适应）
+        let r_d = vc.rgb_d[0] * r_t;
+        let g_d = vc.rgb_d[1] * g_t;
+        let b_d = vc.rgb_d[2] * b_t;
+
+        // 非线性压缩（视觉响应）
+        let r_af = (vc.fl * r_d.abs() / 100.0).powf(0.42);
+        let g_af = (vc.fl * g_d.abs() / 100.0).powf(0.42);
+        let b_af = (vc.fl * b_d.abs() / 100.0).powf(0.42);
+        let r_a = signum(r_d) * 400.0 * r_af / (r_af + 27.13);
+        let g_a = signum(g_d) * 400.0 * g_af / (g_af + 27.13);
+        let b_a = signum(b_d) * 400.0 * b_af / (b_af + 27.13);
+
+        // 红绿 / 黄蓝对立通道
+        let a = (11.0 * r_a - 12.0 * g_a + b_a) / 11.0;
+        let b = (r_a + g_a - 2.0 * b_a) / 9.0;
+
+        // 辅助量
+        let u = (20.0 * r_a + 20.0 * g_a + 21.0 * b_a) / 20.0;
+        let p2 = (40.0 * r_a + 20.0 * g_a + b_a) / 20.0;
+
+        let hue = space::sanitize_degrees(b.atan2(a).to_degrees());
+        let ac = p2 * vc.nbb;
+        let j = 100.0 * (ac / vc.aw).powf(vc.c * vc.z);
+
+        // 彩度：eHue 的 20.14° 断点是官方原样（把橙红段挪到 0 附近做插值）
+        let hue_prime = if hue < 20.14 { hue + 360.0 } else { hue };
+        let e_hue = 0.25 * ((hue_prime.to_radians() + 2.0).cos() + 3.8);
+        let p1 = 50_000.0 / 13.0 * e_hue * vc.nc * vc.ncb;
+        let t = p1 * a.hypot(b) / (u + 0.305);
+        let alpha = (1.64 - 0.29_f64.powf(vc.n)).powf(0.73) * t.powf(0.9);
+        let chroma = alpha * (j / 100.0).sqrt();
+
+        Self { hue, chroma }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn primaries_have_the_official_hue_angles() {
+        // 官方 material-color-utilities 对纯红/绿/蓝解出的 CAM16 色相（Java 实测）。
+        let cases = [
+            (Color::rgb(255, 0, 0), 27.408_225, 113.357_887),
+            (Color::rgb(0, 255, 0), 142.139_894, 108.410_061),
+            (Color::rgb(0, 0, 255), 282.788_18, 87.230_694),
+        ];
+        for (color, hue, chroma) in cases {
+            let cam = Cam16::from_color(color);
+            assert!(
+                (cam.hue - hue).abs() < 1.0e-4,
+                "{} 的 hue 是 {}，官方 {hue}",
+                color.to_hex(),
+                cam.hue
+            );
+            assert!(
+                (cam.chroma - chroma).abs() < 1.0e-4,
+                "{} 的 chroma 是 {}，官方 {chroma}",
+                color.to_hex(),
+                cam.chroma
+            );
+        }
+    }
+
+    #[test]
+    fn gray_has_near_zero_chroma() {
+        for value in [16_u8, 64, 128, 200] {
+            let cam = Cam16::from_color(Color::rgb(value, value, value));
+            assert!(cam.chroma < 2.5, "灰 {value} 的彩度 {}", cam.chroma);
+        }
+    }
+
+    #[test]
+    fn black_is_finite() {
+        let cam = Cam16::from_color(Color::BLACK);
+        assert!(cam.hue.is_finite() && cam.chroma.is_finite());
+        assert_eq!(cam.chroma, 0.0);
+    }
+}
diff --git a/crates/design/src/color/critical_planes.rs b/crates/design/src/color/critical_planes.rs
new file mode 100644
index 0000000..46a72aa
--- /dev/null
+++ b/crates/design/src/color/critical_planes.rs
@@ -0,0 +1,77 @@
+//! 官方 `HctSolver.CRITICAL_PLANES` 表（255 项，**原样搬运**）。
+//!
+//! 这不是可以推导的常数集：它是 HCT 求解器在 sRGB 立方体上按 `Y` 找边界、再做色相二分时的
+//! 「关键平面」索引表，由 Google 的脚本一次性生成后冻结。逐值复制是唯一忠实的做法——
+//! 表错了，极端 tone（深色/浅色端）的颜色会偏一两个通道。
+//!
+//! 来源：`material-color-utilities/java/hct/HctSolver.java`（Apache-2.0），见仓库根 `NOTICE`。
+
+/// sRGB 立方体上按 `Y` 递增排序的关键平面（线性 RGB 0..=100 标度）。
+///
+/// 手写密度由 `#[rustfmt::skip]` 保住：这张表是数据，不是代码，一列一个数会撑到 266 行。
+#[rustfmt::skip]
+pub(crate) const CRITICAL_PLANES: [f64; 255] = [
+    0.015176349177441876, 0.045529047532325624, 0.07588174588720938, 0.10623444424209313,
+    0.13658714259697685, 0.16693984095186062, 0.19729253930674434, 0.2276452376616281,
+    0.2579979360165119, 0.28835063437139563, 0.3188300904430532, 0.350925934958123,
+    0.3848314933096426, 0.42057480301049466, 0.458183274052838, 0.4976837250274023,
+    0.5391024159806381, 0.5824650784040898, 0.6277969426914107, 0.6751227633498623,
+    0.7244668422128921, 0.775853049866786, 0.829304845476233, 0.8848452951698498,
+    0.942497089126609, 1.0022825574869039, 1.0642236851973577, 1.1283421258858297,
+    1.1946592148522128, 1.2631959812511864, 1.3339731595349034, 1.407011200216447,
+    1.4823302800086415, 1.5599503113873272, 1.6398909516233677, 1.7221716113234105,
+    1.8068114625156377, 1.8938294463134073, 1.9832442801866852, 2.075074464868551,
+    2.1693382909216234, 2.2660538449872063, 2.36523901573795, 2.4669114995532007,
+    2.5710888059345764, 2.6777882626779785, 2.7870270208169257, 2.898822059350997,
+    3.0131901897720907, 3.1301480604002863, 3.2497121605402226, 3.3718988244681087,
+    3.4967242352587946, 3.624204428461639, 3.754355295633311, 3.887192587735158,
+    4.022731918402185, 4.160988767090289, 4.301978482107941, 4.445716283538092,
+    4.592217266055746, 4.741496401646282, 4.893568542229298, 5.048448422192488,
+    5.20615066083972, 5.3666897647573375, 5.5300801301023865, 5.696336044816294,
+    5.865471690767354, 6.037501145825082, 6.212438385869475, 6.390297286737924,
+    6.571091626112461, 6.7548350853498045, 6.941541251256611, 7.131223617812143,
+    7.323895587840543, 7.5195704746346665, 7.7182615035334345, 7.919981813454504,
+    8.124744458384042, 8.332562408825165, 8.543448553206703, 8.757415699253682,
+    8.974476575321063, 9.194643831691977, 9.417930041841839, 9.644347703669503,
+    9.873909240696694, 10.106627003236781, 10.342513269534024, 10.58158024687427,
+    10.8238400726681, 11.069304815507364, 11.317986476196008, 11.569896988756009,
+    11.825048221409341, 12.083451977536606, 12.345119996613247, 12.610063955123938,
+    12.878295467455942, 13.149826086772048, 13.42466730586372, 13.702830557985108,
+    13.984327217668513, 14.269168601521828, 14.55736596900856, 14.848930523210871,
+    15.143873411576273, 15.44220572664832, 15.743938506781891, 16.04908273684337,
+    16.35764934889634, 16.66964922287304, 16.985093187232053, 17.30399201960269,
+    17.62635644741625, 17.95219714852476, 18.281524751807332, 18.614349837764564,
+    18.95068293910138, 19.290534541298456, 19.633915083172692, 19.98083495742689,
+    20.331304511189067, 20.685334046541502, 21.042933821039977, 21.404114048223256,
+    21.76888489811322, 22.137256497705877, 22.50923893145328, 22.884842241736916,
+    23.264076429332462, 23.6469514538663, 24.033477234264016, 24.42366364919083,
+    24.817520537484558, 25.21505769858089, 25.61628489293138, 26.021211842414342,
+    26.429848230738664, 26.842203703840827, 27.258287870275353, 27.678110301598522,
+    28.10168053274597, 28.529008062403893, 28.96010235337422, 29.39497283293396,
+    29.83362889318845, 30.276079891419332, 30.722335150426627, 31.172403958865512,
+    31.62629557157785, 32.08401920991837, 32.54558406207592, 33.010999283389665,
+    33.4802739966603, 33.953417292456834, 34.430438229418264, 34.911345834551085,
+    35.39614910352207, 35.88485700094671, 36.37747846067349, 36.87402238606382,
+    37.37449765026789, 37.87891309649659, 38.38727753828926, 38.89959975977785,
+    39.41588851594697, 39.93615253289054, 40.460400508064545, 40.98864111053629,
+    41.520882981230194, 42.05713473317016, 42.597404951718396, 43.141702194811224,
+    43.6900349931913, 44.24241185063697, 44.798841244188324, 45.35933162437017,
+    45.92389141541209, 46.49252901546552, 47.065252796817916, 47.64207110610409,
+    48.22299226451468, 48.808024568002054, 49.3971762874833, 49.9904556690408,
+    50.587870934119984, 51.189430279724725, 51.79514187861014, 52.40501387947288,
+    53.0190544071392, 53.637271562750364, 54.259673423945976, 54.88626804504493,
+    55.517063457223934, 56.15206766869424, 56.79128866487574, 57.43473440856916,
+    58.08241284012621, 58.734331877617365, 59.39049941699807, 60.05092333227251,
+    60.715611475655585, 61.38457167773311, 62.057811747619894, 62.7353394731159,
+    63.417162620860914, 64.10328893648692, 64.79372614476921, 65.48848194977529,
+    66.18756403501224, 66.89098006357258, 67.59873767827808, 68.31084450182222,
+    69.02730813691093, 69.74813616640164, 70.47333615344107, 71.20291564160104,
+    71.93688215501312, 72.67524319850172, 73.41800625771542, 74.16517879925733,
+    74.9167682708136, 75.67278210128072, 76.43322770089146, 77.1981124613393, 77.96744375590167,
+    78.74122893956174, 79.51947534912904, 80.30219030335869, 81.08938110306934,
+    81.88105503125999, 82.67721935322541, 83.4778813166706, 84.28304815182372,
+    85.09272707154808, 85.90692527145302, 86.72564993000343, 87.54890820862819,
+    88.3767072518277, 89.2090541872801, 90.04595612594655, 90.88742016217518, 91.73345337380438,
+    92.58406282226491, 93.43925555268066, 94.29903859396902, 95.16341895893969,
+    96.03240364439274, 96.9059996312159, 97.78421388448044, 98.6670533535366, 99.55452497210776,
+];
diff --git a/crates/design/src/color/hct.rs b/crates/design/src/color/hct.rs
new file mode 100644
index 0000000..228446d
--- /dev/null
+++ b/crates/design/src/color/hct.rs
@@ -0,0 +1,160 @@
+//! **HCT** 色彩空间：色相/彩度取自 CAM16，亮度取自 CIELAB 的 `L*`（即 M3 的 tone）。
+//!
+//! 为什么不是 OKLab/HSL：`L*` 与人眼感知线性的**对比度**直接挂钩（`Y` 是它的单调函数），
+//! 所以「tone 差 40 ⇒ 对比度 ≥ 3:1」「tone 差 50 ⇒ ≥ 4.5:1」这类性质在 HCT 里是恒等式，
+//! 换任何种子色都成立。CAM16 的色相/彩度则保证「同一条调色板只有一种色相」在感知上也是真的。
+//!
+//! 语义与官方 `java/hct/Hct.java` 一致：`Hct` 的真身是那个 **8 bit 色值**，`hue/chroma/tone`
+//! 是它的测量值。所以 [`Hct::from_components`] 解出来的 `tone` 可能比请求值差一点点
+//! （例如请求 tone 40、实测 40.08），官方也是这样——请求值只是求解目标。
+//!
+//! 来源：`material-color-utilities`（Apache-2.0），见仓库根 `NOTICE`。
+
+use super::space;
+use super::{cam16::Cam16, hct_solver, Color};
+
+/// 一个色值的 HCT 坐标。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Hct {
+    /// CAM16 色相角（度，`0..360`）。
+    pub hue: f64,
+    /// CAM16 彩度（无上限；sRGB 立方体内约 0..=130）。
+    pub chroma: f64,
+    /// CIELAB `L*`（0 = 黑 / 100 = 白）——M3 里叫 **tone**。
+    pub tone: f64,
+    /// 这个坐标对应的 8 bit 色值（HCT 的真身）。
+    color: Color,
+}
+
+impl Hct {
+    /// 量一个色值的 HCT 坐标。
+    pub fn from_color(color: Color) -> Self {
+        let cam = Cam16::from_color(color);
+        Self {
+            hue: cam.hue,
+            chroma: cam.chroma,
+            tone: space::lstar_from_color(color),
+            color,
+        }
+    }
+
+    /// 解 HCT 方程：给定色相/彩度/tone，求最接近的 sRGB 色值。
+    ///
+    /// 彩度装不下时**只压彩度**（色相与 tone 保住），这就是 M3 的 gamut 映射；
+    /// 返回值的 `tone` 是实测值，可能与 `tone` 参数相差千分之几。
+    pub fn from_components(hue: f64, chroma: f64, tone: f64) -> Self {
+        Self::from_color(hct_solver::solve_to_color(hue, chroma, tone))
+    }
+
+    /// 该坐标对应的色值。
+    pub fn to_color(self) -> Color {
+        self.color
+    }
+
+    /// 色相是否落在「黄」段（官方 `TonalPalette` 的 tone 99 特例用它）。
+    pub fn is_yellow(hue: f64) -> bool {
+        (105.0..125.0).contains(&hue)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// 官方 Java 实测的种子色 HCT 坐标（`hct.Count` 打印，APCA/CAM16 D65 默认条件）。
+    const SEED_HCT: [(&str, f64, f64, f64); 6] = [
+        ("#6750A4", 298.980_997, 47.856_526, 40.083_244),
+        ("#FF0000", 27.408_225, 113.357_887, 53.232_882),
+        ("#00FF00", 142.139_894, 108.410_061, 87.737_033),
+        ("#0000FF", 282.788_18, 87.230_694, 32.302_587),
+        ("#6E7C8A", 245.036_867, 14.675_86, 51.342_101),
+        ("#D000FF", 324.929_26, 99.544_477, 52.542_037),
+    ];
+
+    #[test]
+    fn seed_coordinates_match_official() {
+        for (hex, hue, chroma, tone) in SEED_HCT {
+            let hct = Hct::from_color(Color::from_hex(hex).expect("合法 hex"));
+            assert!((hct.hue - hue).abs() < 1.0e-4, "{hex} hue {}", hct.hue);
+            assert!(
+                (hct.chroma - chroma).abs() < 1.0e-4,
+                "{hex} chroma {}",
+                hct.chroma
+            );
+            assert!((hct.tone - tone).abs() < 1.0e-4, "{hex} tone {}", hct.tone);
+        }
+    }
+
+    #[test]
+    fn solver_reproduces_official_hexes() {
+        // 官方 Java 实测（`hct.Probe`）：同一组 (h, c, t) 必须解出同一个 hex。
+        let cases = [
+            (95.0, 36.0, 40.0, "#705D0D"),
+            (298.98, 36.0, 90.0, "#E9DDFF"),
+            (25.0, 84.0, 80.0, "#FFB4AB"),
+            (245.0, 16.0, 80.0, "#B8C8D9"),
+            (245.0, 42.0, 30.0, "#004B72"),
+            (10.0, 120.0, 5.0, "#2C000A"),
+            (245.0, 4.0, 30.0, "#45474A"),
+        ];
+        for (hue, chroma, tone, hex) in cases {
+            assert_eq!(
+                hct_solver::solve_to_color(hue, chroma, tone).to_hex(),
+                hex,
+                "HCT({hue}, {chroma}, {tone}) 与官方不一致"
+            );
+        }
+    }
+
+    #[test]
+    fn solver_keeps_hue_and_tone_when_chroma_is_available() {
+        for (hue, chroma, tone) in [
+            (95.0, 36.0, 40.0),
+            (298.98, 36.0, 90.0),
+            (245.0, 42.0, 30.0),
+            (25.0, 84.0, 80.0),
+            (245.0, 16.0, 80.0),
+        ] {
+            let solved = Hct::from_components(hue, chroma, tone);
+            assert_eq!(
+                solved.to_color(),
+                hct_solver::solve_to_color(hue, chroma, tone)
+            );
+            assert!(
+                (solved.tone - tone).abs() < 1.0,
+                "tone {} vs {tone}",
+                solved.tone
+            );
+            let delta = (solved.hue - hue)
+                .abs()
+                .min(360.0 - (solved.hue - hue).abs());
+            assert!(delta < 1.0, "色相 {} vs {hue}", solved.hue);
+            assert!(
+                solved.chroma <= chroma + 1.0,
+                "彩度反被拉高：{}",
+                solved.chroma
+            );
+        }
+    }
+
+    #[test]
+    fn low_chroma_hue_is_ill_conditioned_even_officially() {
+        // 彩度 8 在 tone 30 上，8 bit 量化会让 CAM16 色相跳 6°——官方同样如此
+        // （Java 实测 HCT(245,8,30) → #42474E / hue 251.5965）。这条钉的是「别去修它」。
+        let solved = Hct::from_components(245.0, 8.0, 30.0);
+        assert_eq!(solved.to_color().to_hex(), "#42474E");
+        assert!(
+            (solved.hue - 251.596_498).abs() < 1.0e-4,
+            "hue {}",
+            solved.hue
+        );
+    }
+
+    #[test]
+    fn yellow_band_matches_official_definition() {
+        assert!(Hct::is_yellow(105.0));
+        assert!(Hct::is_yellow(124.9));
+        assert!(!Hct::is_yellow(125.0));
+        assert!(!Hct::is_yellow(104.9));
+    }
+}
diff --git a/crates/design/src/color/hct_solver.rs b/crates/design/src/color/hct_solver.rs
new file mode 100644
index 0000000..02f11e2
--- /dev/null
+++ b/crates/design/src/color/hct_solver.rs
@@ -0,0 +1,311 @@
+//! HCT 求解器：给定 `(hue, chroma, tone)` 求 sRGB 色值——**这就是 M3 的 gamut 映射**。
+//!
+//! M3 不做「越界就硬裁」：它先假设色域足够，用 Newton 迭代解出线性 RGB；只有当解落进 sRGB
+//! 立方体之外时，才退到「在色调平面（`Y` 恒定）上沿色相二分」，把彩度压到该色相能取到的最大值，
+//! **色相与 tone 都保持不变**。所以深色/浅色端的颜色是「变灰」而不是「变色」。
+//!
+//! 照搬 `java/hct/HctSolver.java`（Apache-2.0，见 `NOTICE`）：两段（Newton + 二分）、
+//! 迭代次数、`100.01` 这类边界容差都一致。关键平面表见 [`super::critical_planes`]。
+
+use super::space::{self, signum};
+use super::viewing_conditions::default_conditions;
+use super::Color;
+
+/// 线性 RGB → 「折扣光源」标度的矩阵（求解器内联版，与 [`super::cam16`] 等价但省一次除法）。
+const SCALED_DISCOUNT_FROM_LINRGB: [[f64; 3]; 3] = [
+    [
+        0.001_200_833_568_784_504,
+        0.002_389_694_492_170_889,
+        0.000_279_574_288_586_112_4,
+    ],
+    [
+        0.000_589_108_665_137_599_9,
+        0.002_978_550_257_343_875_8,
+        0.000_327_066_610_400_839_8,
+    ],
+    [
+        0.000_101_466_924_916_405_72,
+        0.000_536_421_435_918_669_4,
+        0.003_297_940_177_071_207_6,
+    ],
+];
+
+/// 「折扣光源」标度 → 线性 RGB（[`SCALED_DISCOUNT_FROM_LINRGB`] 的逆）。
+const LINRGB_FROM_SCALED_DISCOUNT: [[f64; 3]; 3] = [
+    [
+        1_373.219_870_959_423_1,
+        -1_100.425_119_075_482_1,
+        -7.278_681_089_101_213,
+    ],
+    [
+        -271.815_969_077_903,
+        559.658_046_594_073_3,
+        -32.460_474_827_911_94,
+    ],
+    [
+        1.962_289_959_966_566_6,
+        -57.173_814_538_844_006,
+        308.723_319_781_238_5,
+    ],
+];
+
+/// 线性 RGB 的 `Y` 权重（Rec.709 亮度系数）。
+const Y_FROM_LINRGB: [f64; 3] = [0.2126, 0.7152, 0.0722];
+
+/// `(hue, chroma, tone)` → 色值。彩度取不到时压到该色相/色调下的最大值（色相与 tone 不变）。
+pub(crate) fn solve_to_color(hue_degrees: f64, chroma: f64, lstar: f64) -> Color {
+    // 端点与极低彩度直接走灰：官方用同一断点，保证 tone 0/100 是纯黑/纯白。
+    if chroma < 0.0001 || lstar < 0.0001 || lstar > 99.9999 {
+        return space::color_from_lstar(lstar);
+    }
+    let hue_radians = space::sanitize_degrees(hue_degrees).to_radians();
+    let y = space::y_from_lstar(lstar);
+    if let Some(exact) = find_result_by_j(hue_radians, chroma, y) {
+        return exact;
+    }
+    space::color_from_linrgb(bisect_to_limit(y, hue_radians))
+}
+
+/// 牛顿迭代直接解（色域内能解出来时，这条路径是精确解）。
+fn find_result_by_j(hue_radians: f64, chroma: f64, y: f64) -> Option<Color> {
+    let vc = default_conditions();
+    let mut j = y.sqrt() * 11.0;
+    let t_inner_coeff = 1.0 / (1.64 - 0.29_f64.powf(vc.n)).powf(0.73);
+    let e_hue = 0.25 * ((hue_radians + 2.0).cos() + 3.8);
+    let p1 = e_hue * (50_000.0 / 13.0) * vc.nc * vc.ncb;
+    let h_sin = hue_radians.sin();
+    let h_cos = hue_radians.cos();
+    for round in 0..5 {
+        let j_normalized = j / 100.0;
+        let alpha = if chroma == 0.0 || j == 0.0 {
+            0.0
+        } else {
+            chroma / j_normalized.sqrt()
+        };
+        let t = (alpha * t_inner_coeff).powf(1.0 / 0.9);
+        let ac = vc.aw * j_normalized.powf(1.0 / vc.c / vc.z);
+        let p2 = ac / vc.nbb;
+        let gamma = 23.0 * (p2 + 0.305) * t / (23.0 * p1 + 11.0 * t * h_cos + 108.0 * t * h_sin);
+        let a = gamma * h_cos;
+        let b = gamma * h_sin;
+        let r_a = (460.0 * p2 + 451.0 * a + 288.0 * b) / 1403.0;
+        let g_a = (460.0 * p2 - 891.0 * a - 261.0 * b) / 1403.0;
+        let b_a = (460.0 * p2 - 220.0 * a - 6300.0 * b) / 1403.0;
+        let linrgb = space::matrix_multiply(
+            [
+                inverse_chromatic_adaptation(r_a),
+                inverse_chromatic_adaptation(g_a),
+                inverse_chromatic_adaptation(b_a),
+            ],
+            LINRGB_FROM_SCALED_DISCOUNT,
+        );
+        if linrgb[0] < 0.0 || linrgb[1] < 0.0 || linrgb[2] < 0.0 {
+            return None;
+        }
+        let f_nj = Y_FROM_LINRGB[0] * linrgb[0]
+            + Y_FROM_LINRGB[1] * linrgb[1]
+            + Y_FROM_LINRGB[2] * linrgb[2];
+        if f_nj <= 0.0 {
+            return None;
+        }
+        if round == 4 || (f_nj - y).abs() < 0.002 {
+            if linrgb[0] > 100.01 || linrgb[1] > 100.01 || linrgb[2] > 100.01 {
+                return None;
+            }
+            return Some(space::color_from_linrgb(linrgb));
+        }
+        // Newton：用 2 * fn(j) / j 近似 fn'(j)
+        j -= (f_nj - y) * j / (2.0 * f_nj);
+    }
+    None
+}
+
+/// 色域外时的兜底：在 `Y` 恒定的平面上按色相二分，取边界上的颜色。
+fn bisect_to_limit(y: f64, target_hue: f64) -> [f64; 3] {
+    let (mut left, mut right) = bisect_to_segment(y, target_hue);
+    let mut left_hue = hue_of(left);
+    for axis in 0..3 {
+        if left[axis] == right[axis] {
+            continue;
+        }
+        let (mut l_plane, mut r_plane) = if left[axis] < right[axis] {
+            (
+                critical_plane_below(space::true_delinearized(left[axis])),
+                critical_plane_above(space::true_delinearized(right[axis])),
+            )
+        } else {
+            (
+                critical_plane_above(space::true_delinearized(left[axis])),
+                critical_plane_below(space::true_delinearized(right[axis])),
+            )
+        };
+        for _ in 0..8 {
+            if (r_plane - l_plane).abs() <= 1 {
+                break;
+            }
+            let m_plane = ((f64::from(l_plane) + f64::from(r_plane)) / 2.0).floor() as i32;
+            let coordinate = super::critical_planes::CRITICAL_PLANES[m_plane as usize];
+            let mid = set_coordinate(left, coordinate, right, axis);
+            let mid_hue = hue_of(mid);
+            if are_in_cyclic_order(left_hue, target_hue, mid_hue) {
+                right = mid;
+                r_plane = m_plane;
+            } else {
+                left = mid;
+                left_hue = mid_hue;
+                l_plane = m_plane;
+            }
+        }
+    }
+    midpoint(left, right)
+}
+
+/// 找到包含目标色相的边界线段（sRGB 立方体与 `Y` 平面的交是多边形）。
+fn bisect_to_segment(y: f64, target_hue: f64) -> ([f64; 3], [f64; 3]) {
+    let mut left = [-1.0_f64; 3];
+    let mut right = left;
+    let mut left_hue = 0.0;
+    let mut initialized = false;
+    let mut uncut = true;
+    for n in 0..12 {
+        let Some(mid) = nth_vertex(y, n) else {
+            continue;
+        };
+        let mid_hue = hue_of(mid);
+        if !initialized {
+            initialized = true;
+            left = mid;
+            right = mid;
+            left_hue = mid_hue;
+            continue;
+        }
+        if uncut || are_in_cyclic_order(left_hue, mid_hue, hue_of(right)) {
+            uncut = false;
+            if are_in_cyclic_order(left_hue, target_hue, mid_hue) {
+                right = mid;
+            } else {
+                left = mid;
+                left_hue = mid_hue;
+            }
+        }
+    }
+    (left, right)
+}
+
+/// `Y` 平面与立方体的第 `n` 个顶点（不在立方体内返回 `None`）。
+fn nth_vertex(y: f64, n: usize) -> Option<[f64; 3]> {
+    let [k_r, k_g, k_b] = Y_FROM_LINRGB;
+    let coord_a = if n % 4 <= 1 { 0.0 } else { 100.0 };
+    let coord_b = if n.is_multiple_of(2) { 0.0 } else { 100.0 };
+    let vertex = if n < 4 {
+        let (g, b) = (coord_a, coord_b);
+        [((y - g * k_g - b * k_b) / k_r), g, b]
+    } else if n < 8 {
+        let (b, r) = (coord_a, coord_b);
+        [r, ((y - r * k_r - b * k_b) / k_g), b]
+    } else {
+        let (r, g) = (coord_a, coord_b);
+        [r, g, ((y - r * k_r - g * k_g) / k_b)]
+    };
+    if vertex.iter().all(|c| (0.0..=100.0).contains(c)) {
+        Some(vertex)
+    } else {
+        None
+    }
+}
+
+/// 线性 RGB 的色相（弧度，未归一）。
+fn hue_of(linrgb: [f64; 3]) -> f64 {
+    let scaled = space::matrix_multiply(linrgb, SCALED_DISCOUNT_FROM_LINRGB);
+    let r_a = chromatic_adaptation(scaled[0]);
+    let g_a = chromatic_adaptation(scaled[1]);
+    let b_a = chromatic_adaptation(scaled[2]);
+    let a = (11.0 * r_a - 12.0 * g_a + b_a) / 11.0;
+    let b = (r_a + g_a - 2.0 * b_a) / 9.0;
+    b.atan2(a)
+}
+
+/// 角度上 `b` 是否落在 `a → c` 的前进区间内。
+fn are_in_cyclic_order(a: f64, b: f64, c: f64) -> bool {
+    space::sanitize_radians(b - a) < space::sanitize_radians(c - a)
+}
+
+/// 把线段 `source → target` 在 `axis` 上截到 `coordinate`。
+fn set_coordinate(source: [f64; 3], coordinate: f64, target: [f64; 3], axis: usize) -> [f64; 3] {
+    let t = (coordinate - source[axis]) / (target[axis] - source[axis]);
+    [
+        source[0] + (target[0] - source[0]) * t,
+        source[1] + (target[1] - source[1]) * t,
+        source[2] + (target[2] - source[2]) * t,
+    ]
+}
+
+/// 线段中点。
+fn midpoint(a: [f64; 3], b: [f64; 3]) -> [f64; 3] {
+    [
+        (a[0] + b[0]) / 2.0,
+        (a[1] + b[1]) / 2.0,
+        (a[2] + b[2]) / 2.0,
+    ]
+}
+
+/// 非线性压缩的正向（与 CAM16 里那段同公式）。
+fn chromatic_adaptation(component: f64) -> f64 {
+    let af = component.abs().powf(0.42);
+    signum(component) * 400.0 * af / (af + 27.13)
+}
+
+/// 非线性压缩的逆。
+fn inverse_chromatic_adaptation(adapted: f64) -> f64 {
+    let adapted_abs = adapted.abs();
+    let base = (27.13 * adapted_abs / (400.0 - adapted_abs)).max(0.0);
+    signum(adapted) * base.powf(1.0 / 0.42)
+}
+
+/// 关键平面索引：向下取（官方 `(int) Math.floor(x - 0.5)`）。
+fn critical_plane_below(x: f64) -> i32 {
+    (x - 0.5).floor() as i32
+}
+
+/// 关键平面索引：向上取（官方 `(int) Math.ceil(x - 0.5)`）。
+fn critical_plane_above(x: f64) -> i32 {
+    (x - 0.5).ceil() as i32
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn in_gamut_requests_are_met_exactly() {
+        // 官方 Java 实测：HCT(95, 36, 40) → #705D0D。
+        assert_eq!(solve_to_color(95.0, 36.0, 40.0).to_hex(), "#705D0D");
+        assert_eq!(solve_to_color(25.0, 84.0, 40.0).to_hex(), "#BA1A1A");
+        assert_eq!(solve_to_color(95.0, 36.0, 90.0).to_hex(), "#FCE186");
+    }
+
+    #[test]
+    fn out_of_gamut_requests_keep_hue_and_tone() {
+        // 请求 chroma 200（sRGB 装不下）：官方只在彩度上退让，色相与 tone 必须保住。
+        let color = solve_to_color(200.0, 200.0, 70.0);
+        assert_eq!(color.to_hex(), "#00BEC3");
+        let hct = super::super::Hct::from_color(color);
+        assert!((hct.tone - 70.0).abs() < 1.0, "tone 掉了：{}", hct.tone);
+        assert!(
+            (hct.hue - 200.0).abs() < 1.0,
+            "色相偏了：{}（应 ≈200）",
+            hct.hue
+        );
+        assert!(hct.chroma < 200.0);
+    }
+
+    #[test]
+    fn neutral_requests_return_exact_grays() {
+        for lstar in [0.0_f64, 4.0, 10.0, 50.0, 87.0, 98.0, 100.0] {
+            let color = solve_to_color(120.0, 0.0, lstar);
+            assert!(color.r == color.g && color.g == color.b, "{:?}", color);
+        }
+        assert_eq!(solve_to_color(0.0, 0.0, 0.0), Color::BLACK);
+        assert_eq!(solve_to_color(0.0, 0.0, 100.0), Color::WHITE);
+    }
+}
diff --git a/crates/design/src/color/mod.rs b/crates/design/src/color/mod.rs
new file mode 100644
index 0000000..ec027ef
--- /dev/null
+++ b/crates/design/src/color/mod.rs
@@ -0,0 +1,335 @@
+//! # 色彩令牌（M3 color roles）
+//!
+//! 49 个 M3 语义色角色 × light/dark 两套，全部由**一个种子色**派生（[`Palettes`]），
+//! 再按官方 tone 映射表解析成具体色值（[`Scheme`]）。
+//!
+//! ```no_run
+//! use unlucky_design::color::{Color, Role, Scheme, SchemeFlavor};
+//!
+//! let light = Scheme::baseline(SchemeFlavor::Light);
+//! let surface = light.get(Role::Surface);
+//! let on_surface = light.get(Role::OnSurface);
+//! assert!(on_surface.contrast_ratio(surface) > 4.5);
+//!
+//! // 用户自定义强调色：表面中性色不动，只换强调族。
+//! let custom = Scheme::from_accent(SchemeFlavor::Light, Color::from_hex("#006A5C").unwrap());
+//! assert_eq!(custom.get(Role::Surface), surface);
+//! ```
+//!
+//! ## 口径声明：真 HCT，不是近似
+//!
+//! 标准 M3 的调色板建在 **HCT**（CAM16 色相/彩度 + CIELAB 的 `L*`）上。本模块**就是**那套算法：
+//! CAM16 正换算（`cam16` 模块）取色相/彩度，`L*` 取 tone，色域外走官方的 `HctSolver`
+//! （`hct_solver` 模块：Newton 迭代 + 色调平面上的色相二分，**只压彩度、不硬裁**）。
+//!
+//! | 轴 | 标准 M3 | 本实现 | 一致性 |
+//! |---|---|---|---|
+//! | tone | CIELAB `L*` | CIELAB `L*`（同一个 `Y` 轴） | 逐值一致 |
+//! | 色相 / 彩度 | CAM16 | CAM16（D65 默认观察条件） | 逐值一致（误差 < 1e-4） |
+//! | gamut 映射 | `HctSolver` | 同一套两段求解器，关键平面表原样搬运 | 逐通道一致 |
+//! | 调色板彩度 | Tonal Spot 变体：36 / 16 / 24 / 6 / 8，error 25°/84 | 同（primary/secondary/tertiary/neutral-variant/error 逐值一致） | 逐值一致 |
+//! | 中性彩度 | 6（几乎无色） | 官方口径 6；**产品默认用 12**（有意偏离，见下节「出厂默认色」） | 仅此处偏离 |
+//! | 角色 tone 表 | ColorSpec2021 | 同（49 角色 × light/dark） | 逐值一致 |
+//!
+//! 对齐证据在 `tests/official_baseline.rs` 与 `tests/official_accent.rs`：期望值全部由
+//! `material-color-utilities`（官方 Java 实现，Apache-2.0）跑出来，**每通道误差 ≤1** 才通过。
+//! 所以本 crate 可以对外说「M3 动态取色（Tonal Spot 变体 / standard 对比度）」。
+//!
+//! ## 未实现的部分（gap 登记，别以为已经有）
+//!
+//! | 能力 | 官方叫什么 | 状态 |
+//! |---|---|---|
+//! | 对比度三档（default/medium/high） | `ContrastCurve` + `contrastLevel` | **未实现**：只做 `contrastLevel = 0`。在 0 档下官方那层「tone 差对 + 对比度修正」机制的输入全是常数，等价于本模块的静态 tone 表（已由对齐测试反证） |
+//! | 其他配色变体 | `Vibrant` / `Expressive` / `Fidelity` / `Content` / `Monochrome` / `Neutral` / `Rainbow` / `FruitSalad` / `CMF` | **未实现**：只有 `TonalSpot`（M3 默认、也是 Material Theme Builder 默认） |
+//! | 壁纸多色取色 | `QuantizerCelebi` / `Score` / 多 source 色 | **单种子部分已实现**：量化（5 bit 直方图 + CIELAB k-means）与 `Score` 挑主色在 [`crate::palette`]（M87）。**多 source 色**（一张图出 4 个种子、每个 `*_container` 换色相）仍未实现——产品口径是「一套主题一个强调色」（D38） |
+//! | 换观察条件 | `Hct.inViewingConditions` | **未实现**：只有 sRGB 屏的默认条件（D65 / 200 lux / 背景 `L* 50`） |
+//!
+//! ## 「自定义强调色」与官方 `from_seed` 的关系
+//!
+//! 官方 `SchemeTonalSpot(accent)` 会把**中性表面也染上**种子的色相；本项目的产品语义是
+//! 「换强调色不该让整个窗口底色变脏」，所以 [`Scheme::from_accent`] 只换 primary/secondary/
+//! tertiary 三族，中性色与 error 保持基线。强调族的色值与官方 `from_seed(accent)` 逐个对得上
+//! （`tests/official_accent.rs`，8 个种子 × 12 个强调族角色 × 2 模式 = 192 项）。
+//!
+//! ## 出厂默认色（M70：浅冷天蓝）——含**两处**有意偏离（同一处偏离的两半）
+//!
+//! 产品默认不走官方紫，而是「浅冷天蓝」。默认值收在两个常量里，**换默认只改这两行**
+//! （用户 2026-11-01 拍板采用候选 **④ 天蓝**；③ 浅冷天蓝 `#87CEEB` 留作备选，值仍 pin 在
+//! `tests/skyseed_candidates.rs`）：
+//!
+//! | 项 | 当前值 | 官方值 | 说明 |
+//! |---|---|---|---|
+//! | [`palettes::DEFAULT_SEED`] | `#3C8DBC`（CAM16 hue ≈ 240°） | `#6750A4`（[`palettes::BASELINE_SEED`]） | 种子只贡献**色相**（CAM16 240°）；种子彩度会被 Tonal Spot 丢掉 |
+//! | [`palettes::DEFAULT_NEUTRAL_CHROMA`]（neutral） | `12` | `6` | 让 surface / surface-container-* 带淡蓝调 |
+//! | 联动的 neutral-variant | `14` | `8`（**绝对值**；官方不是「neutral + 2」） | `outline` / `outline-variant` / `surface-variant` 一起偏蓝（light `outline` = `#6A7985` 就是 14 彩度的口径） |
+//!
+//! **定位（D38）**：这套默认只是「**莫奈关闭时的出厂预选色卡**」（首次启动、用户还没选过色卡时
+//! 用的那一套），**不是唯一的配色来源**。用户的配色来源有三级优先：① 启动器背景图取色（Monet）
+//! → ② 桌面壁纸取色 → ③ 莫奈关闭（默认）时从内置多套色卡里选。取色（量化 + 挑主色）、内置色卡库
+//! 与三级回落都在 [`crate::palette`]（M87 落地，D40 分层）；**本模块只负责**「给定种子 + 中性彩度，
+//! 派生出 49 个角色」，不碰像素、不碰路径、不碰回落决策。
+//!
+//! > ⚠️ **有意偏离登记（两处，同一处偏离的两半）**：
+//! >
+//! > 1. **neutral 彩度 `6 → 12`**。理由＝产品要「浅冷」的冷调表面：官方 6 的表面几乎无色，单靠换
+//! >    种子做不到「浅」——primary 的 tone 被官方钉在 40，种子再浅主色也还是中蓝，所以「浅」只能
+//! >    落在中性色上。
+//! > 2. **neutral-variant 彩度 `8 → 14`**。这是第 1 条的连带结果：官方
+//! >    `getNeutralVariantPalette` 写死的是**绝对值 8**（不是「neutral + 2」这种相对式），
+//! >    本实现为了让层次不倒挂，让它跟着 neutral 联动（`nv = neutral + 2`）。若把 nv 钉回 8，
+//! >    表面（12）会比中性变体（8）更「有色」，破坏官方的「neutral < neutral-variant」层次。
+//! >    影响面不只表面：`outline` / `outline-variant` / `surface-variant` 三个角色一起偏蓝。
+//! >
+//! > 除这两处外全部走官方常数（primary 36 / secondary 16 / tertiary 24 且色相 +60° /
+//! > error 25°·84），tone 表与 gamut 映射一行未动；[`Scheme::official_baseline`] 仍是官方的
+//! > 6（neutral）/ 8（neutral-variant）口径。
+//!
+//! 官方口径的锚点仍然完整保留：[`Scheme::official_baseline`]（种子 `#6750A4` + 中性 6）
+//! 是 `tests/official_baseline.rs` 的对账入口，98 项仍是每通道 ≤1；
+//! `tests/skyseed_candidates.rs` 把四档候选（保守蓝 / 冷调蓝 / 浅冷蓝 / 天蓝）的色值逐个 pin 住，
+//! 换默认时它会指着要改的行。
+//!
+//! ✅ 默认色已由用户 2026-11-01 拍板：**④ 天蓝 `#3C8DBC`**。备选 ③ 浅冷蓝 `#87CEEB`
+//! （主色偏青 `#0C6780`）仍在候选表里，换回去只需改 [`palettes::DEFAULT_SEED`] 一行。
+//!
+//! ## 对比度纪律（WCAG AA）
+//!
+//! - 所有 `on-*` 与其承载色（`*-container`、`primary`、`surface`）都满足 **≥ 4.5:1**；
+//!   这一条由 `tests/contrast_aa.rs` 全表验证，且因为 tone 轴固定，**换任何种子色都成立**
+//!   （WCAG 对比度只取决于相对亮度，而 tone 直接钉住 `L*`；中性彩度同理，
+//!   `sky_seed_candidates_meet_wcag_aa` 逐档验证了 M70 的四档候选：4 档 × 2 模式 × 26 对 = 208 项）。
+//! - 例外（显式登记，非缺陷）：
+//!   - [`Role::Outline`] 对 [`Role::Surface`]：M3 定义的**非文字**元素（输入框描边），
+//!     目标 3:1，实测 light 4.26:1 / dark 5.89:1；
+//!   - [`Role::OutlineVariant`] 对 [`Role::Surface`]：纯装饰分隔线，M3 不要求对比度下限；
+//!   - [`Role::SurfaceVariant`]：它是**容器**色（不是前景），不参与对比度门禁。
+//! - 禁用态按 M3 的 alpha 叠加（[`state::DISABLED_CONTENT_ALPHA`]），刻意低于 AA。
+
+pub mod hct;
+pub mod palettes;
+pub mod roles;
+pub mod scheme;
+pub mod state;
+pub mod tonal;
+
+mod cam16;
+mod critical_planes;
+mod hct_solver;
+// `pub(crate)`：取色量化（`crate::palette::quantize`）要在 CIELAB 里算簇距离，复用同一套换算。
+pub(crate) mod space;
+mod viewing_conditions;
+
+pub use hct::Hct;
+pub use palettes::{
+    PaletteSlot, Palettes, BASELINE_SEED, DEFAULT_NEUTRAL_CHROMA, DEFAULT_SEED, NEUTRAL_HUE_DEG,
+};
+pub use roles::Role;
+pub use scheme::{Scheme, SchemeFlavor, SCRIM_ALPHA, SHADOW_ALPHA};
+pub use state::StateLayer;
+pub use tonal::TonalPalette;
+
+/// sRGB 颜色（8 bit/通道 + alpha），刻意不用第三方颜色类型：本 crate 零依赖。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct Color {
+    /// 红通道。
+    pub r: u8,
+    /// 绿通道。
+    pub g: u8,
+    /// 蓝通道。
+    pub b: u8,
+    /// alpha（0 = 全透明，255 = 不透明）。
+    pub a: u8,
+}
+
+impl Color {
+    /// 不透明颜色。
+    pub const fn rgb(r: u8, g: u8, b: u8) -> Self {
+        Self { r, g, b, a: 255 }
+    }
+
+    /// 带 alpha 的颜色（`a` 为 0..=255）。
+    pub const fn rgba(r: u8, g: u8, b: u8, a: u8) -> Self {
+        Self { r, g, b, a }
+    }
+
+    /// 纯黑。
+    pub const BLACK: Color = Color::rgb(0, 0, 0);
+    /// 纯白。
+    pub const WHITE: Color = Color::rgb(255, 255, 255);
+
+    /// 从 `#RRGGBB` / `#RGB` / `#AARRGGBB` 解析（不合法返回 `None`）。
+    ///
+    /// 只给配置读取与测试用——UI 代码里**不许出现色字面量**，一律走 [`Role`]。
+    pub fn from_hex(text: &str) -> Option<Self> {
+        let hex = text.trim().trim_start_matches('#');
+        let parse = |s: &str| u8::from_str_radix(s, 16).ok();
+        match hex.len() {
+            3 => {
+                let d = |i: usize| {
+                    let v = parse(&hex[i..i + 1])?;
+                    Some(v * 17)
+                };
+                Some(Self::rgb(d(0)?, d(1)?, d(2)?))
+            }
+            6 => Some(Self::rgb(
+                parse(&hex[0..2])?,
+                parse(&hex[2..4])?,
+                parse(&hex[4..6])?,
+            )),
+            8 => Some(Self::rgba(
+                parse(&hex[2..4])?,
+                parse(&hex[4..6])?,
+                parse(&hex[6..8])?,
+                parse(&hex[0..2])?,
+            )),
+            _ => None,
+        }
+    }
+
+    /// 不透明部分转 `#RRGGBB`（alpha < 255 时附 `#AARRGGBB` 形式）。
+    pub fn to_hex(self) -> String {
+        if self.a == 255 {
+            format!("#{:02X}{:02X}{:02X}", self.r, self.g, self.b)
+        } else {
+            format!("#{:02X}{:02X}{:02X}{:02X}", self.a, self.r, self.g, self.b)
+        }
+    }
+
+    /// 改 alpha（`alpha` 0..1，越界夹取）。
+    pub fn with_alpha(self, alpha: f32) -> Self {
+        Self {
+            a: (alpha.clamp(0.0, 1.0) * 255.0).round() as u8,
+            ..self
+        }
+    }
+
+    /// alpha 归一化到 0..1。
+    pub fn alpha(self) -> f32 {
+        f32::from(self.a) / 255.0
+    }
+
+    /// 是否完全不透明。
+    pub fn is_opaque(self) -> bool {
+        self.a == 255
+    }
+
+    /// WCAG 相对亮度（0..1，即 XYZ 的 `Y` 除以 100）。
+    ///
+    /// 与 WCAG 2.x 的定义同一条 `Y` 轴（Rec.709 系数 0.2126/0.7152/0.0722），
+    /// 所以 [`Color::contrast_ratio`] 就是标准对比度公式。
+    pub fn relative_luminance(self) -> f32 {
+        (space::xyz_from_color(self)[1] / 100.0) as f32
+    }
+
+    /// CIELAB `L*`（0..100）——这就是 M3 的 **tone**。
+    ///
+    /// 调色板按这条轴生成，验收也按这条轴断言；想知道某个色值「是几号 tone」就用它。
+    pub fn lstar(self) -> f32 {
+        space::lstar_from_color(self) as f32
+    }
+
+    /// WCAG 对比度（1..21）。`self` 与 `other` 都不透明时才严格；带 alpha 时先算「不计 alpha」的值。
+    pub fn contrast_ratio(self, other: Self) -> f32 {
+        let a = self.relative_luminance();
+        let b = other.relative_luminance();
+        let (hi, lo) = if a > b { (a, b) } else { (b, a) };
+        (hi + 0.05) / (lo + 0.05)
+    }
+
+    /// alpha 合成：`self` 叠在 `bg` 之上，返回不透明结果。
+    ///
+    /// 这是 M3 状态层/禁用态/遮罩的唯一合成口径（非预乘 alpha）。
+    pub fn over(self, bg: Self) -> Self {
+        let sa = self.alpha();
+        if sa >= 1.0 {
+            return self;
+        }
+        let blend = |fg: u8, b: u8| {
+            let v = f32::from(fg) * sa + f32::from(b) * (1.0 - sa);
+            v.round().clamp(0.0, 255.0) as u8
+        };
+        let a = sa + bg.alpha() * (1.0 - sa);
+        Self {
+            r: blend(self.r, bg.r),
+            g: blend(self.g, bg.g),
+            b: blend(self.b, bg.b),
+            a: (a * 255.0).round().clamp(0.0, 255.0) as u8,
+        }
+    }
+
+    /// 两色线性插值（`t` 0..1），用于动画中间帧（GPU 路径的 shape morph 用得上）。
+    pub fn lerp(self, other: Self, t: f32) -> Self {
+        let t = t.clamp(0.0, 1.0);
+        let mix = |a: u8, b: u8| {
+            (f32::from(a) + (f32::from(b) - f32::from(a)) * t)
+                .round()
+                .clamp(0.0, 255.0) as u8
+        };
+        Self {
+            r: mix(self.r, other.r),
+            g: mix(self.g, other.g),
+            b: mix(self.b, other.b),
+            a: mix(self.a, other.a),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn hex_roundtrip() {
+        let c = Color::from_hex("#6750A4").expect("合法 hex");
+        assert_eq!(c, Color::rgb(0x67, 0x50, 0xA4));
+        assert_eq!(c.to_hex(), "#6750A4");
+        assert_eq!(Color::from_hex("6750a4"), Some(c));
+        assert_eq!(Color::from_hex("#FFF"), Some(Color::WHITE));
+        assert_eq!(Color::from_hex("#80FF0000").map(|c| c.a), Some(0x80));
+        assert_eq!(Color::from_hex("#12345"), None);
+        assert_eq!(Color::from_hex("zzzzzz"), None);
+    }
+
+    #[test]
+    fn contrast_extremes() {
+        assert!((Color::BLACK.contrast_ratio(Color::WHITE) - 21.0).abs() < 0.01);
+        assert!((Color::WHITE.contrast_ratio(Color::WHITE) - 1.0).abs() < 0.001);
+    }
+
+    #[test]
+    fn over_composites_correctly() {
+        let black_50 = Color::BLACK.with_alpha(0.5);
+        let got = black_50.over(Color::WHITE);
+        // with_alpha 量化到 128/255 = 0.50196，所以结果落在 127（不是 128）。
+        assert_eq!((got.r, got.a), (127, 255));
+    }
+
+    #[test]
+    fn lerp_hits_endpoints() {
+        let a = Color::rgb(0, 0, 0);
+        let b = Color::rgb(255, 255, 255);
+        assert_eq!(a.lerp(b, 0.0), a);
+        assert_eq!(a.lerp(b, 1.0), b);
+        assert_eq!(a.lerp(b, 0.5).r, 128);
+    }
+
+    #[test]
+    fn lstar_anchors_at_the_ends() {
+        assert!(Color::BLACK.lstar().abs() < 1.0e-3);
+        assert!((Color::WHITE.lstar() - 100.0).abs() < 1.0e-3);
+        // 中灰（sRGB 128）的 L* 是 53.6 左右，不是 50——这正是「L* 不是 sRGB 编码值」的证据。
+        let mid = Color::rgb(128, 128, 128).lstar();
+        assert!((mid - 53.585).abs() < 0.01, "中灰 L* = {mid}");
+    }
+
+    #[test]
+    fn tone_delta_implies_contrast_floor() {
+        // M3 的招牌性质：tone 差 50 ⇒ 对比度 ≥ 4.5:1（与色相/彩度无关）。
+        for (low, high) in [(10.0_f64, 60.0), (30.0, 80.0), (40.0, 90.0), (20.0, 70.0)] {
+            let a = space::color_from_lstar(low);
+            let b = space::color_from_lstar(high);
+            let ratio = a.contrast_ratio(b);
+            assert!(ratio >= 4.5, "tone {low}→{high} 只有 {ratio:.2}");
+        }
+    }
+}
diff --git a/crates/design/src/color/palettes.rs b/crates/design/src/color/palettes.rs
new file mode 100644
index 0000000..e2a492e
--- /dev/null
+++ b/crates/design/src/color/palettes.rs
@@ -0,0 +1,400 @@
+//! 六条 tone 调色板的集合（M3 scheme 的原料）。
+//!
+//! 角色 → 调色板槽位 → tone 的三段映射在 [`super::scheme`]；这里只负责「种子 → 六条调色板」，
+//! 以及**官方 Tonal Spot 变体**的彩度常数。
+//!
+//! 彩度值来自 `material-color-utilities` 的 `ColorSpec2021.get*Palette(Variant.TONAL_SPOT)`
+//! （Apache-2.0，见 `NOTICE`）：primary 恒定 **36**、secondary **16**、tertiary **24**
+//! （色相 +60°）、neutral **6**、neutral-variant **8**、error 固定色相 **25** 彩度 **84**。
+//! 注意 primary 的 36 与种子自身的彩度无关——这是官方口径：Tonal Spot 是「镇静」变体，
+//! 再鲜艳的种子也会被收到 36，再灰的种子也会被提到 36。
+//!
+//! ## 两个入口：官方口径 vs 产品默认（M70）
+//!
+//! | 入口 | 种子 | 中性彩度 | 用途 |
+//! |---|---|---|---|
+//! | [`Palettes::official_baseline`] / [`super::Scheme::official_baseline`] | [`BASELINE_SEED`]（`#6750A4`） | 6（官方） | 与官方 Java 实现逐角色对齐的**锚点**，`tests/official_baseline.rs` 用它 |
+//! | [`Palettes::baseline`] / [`super::Scheme::baseline`] | [`DEFAULT_SEED`] | [`DEFAULT_NEUTRAL_CHROMA`] | **产品出厂默认**（消费方拿到的就是它） |
+//!
+//! 换默认色只改 [`DEFAULT_SEED`] 与 [`DEFAULT_NEUTRAL_CHROMA`] 两行常量（中性彩度不动就只改一行），
+//! 然后重跑 `tests/skyseed_candidates.rs` 的 pin（它会打印新值并指出哪几行要同步）。
+//! 官方锚点不受影响——**算法没动，动的只是入参**。
+//!
+//! ⚠️ 中性彩度 6 → 12 是**有意偏离**官方 Tonal Spot（理由：产品要「浅冷」的冷调表面），
+//! 偏离登记见 [`super`] 模块文档的「出厂默认色」小节。
+
+use super::tonal::TonalPalette;
+use super::Color;
+
+/// M3 baseline 种子色（与 material-color-utilities 的默认基线同值）。
+///
+/// **不是**产品默认色——产品默认见 [`DEFAULT_SEED`]。
+pub const BASELINE_SEED: Color = Color::rgb(0x67, 0x50, 0xA4);
+
+/// 产品出厂默认种子色 —— M70 候选④「天蓝」，**用户 2026-11-01 拍板采用**。
+///
+/// `#3C8DBC`（CAM16 hue ≈ 239.5°，主色 `#236488`）。注意种子的彩度（42.6）会被 Tonal Spot
+/// 丢掉——主色板的彩度恒为 36，种子只贡献**色相**。
+///
+/// ## 定位（D38）：这是「莫奈关闭时的出厂预选色卡」，不是唯一的配色来源
+///
+/// 用户定了三级优先的配色来源：① 启动器背景图取色（Monet）→ ② 桌面壁纸取色 → ③ 莫奈关闭
+/// （默认）时用户从内置多套色卡里选。本常量 + [`DEFAULT_NEUTRAL_CHROMA`] 只定义**第三级里
+/// 出厂预选的那一套**（首次启动、用户没选过色卡时的那一套；`palette::DEFAULT_CARD` 的种子即本值）。
+///
+/// 取色（量化 + 挑主色）、内置色卡库与三级回落都在 [`crate::palette`]（M87，分层见 D40）；
+/// 本模块只负责「给定种子 + 中性彩度，派生出 49 个角色」。
+pub const DEFAULT_SEED: Color = Color::rgb(0x3C, 0x8D, 0xBC);
+
+/// 产品出厂默认的中性调色板彩度（官方 Tonal Spot 是 6，这里 12 = **有意偏离**）。
+///
+/// 官方 6 让表面几乎无色；12 让 surface / surface-container-* 带一层淡蓝调，
+/// 这是「浅冷天蓝」唯一能落在表面上的手段（primary 的 tone 被官方钉在 40，
+/// 种子再浅也变不成浅蓝）。
+///
+/// **数值安全区间 `6..=13`，产品取 12**：neutral-variant 跟 neutral 联动（`nv = neutral + 2`），
+/// 13 时 nv = 15 仍低于 secondary 的 16；**14 才会撞上**（nv = 16 = secondary），届时要一并改
+/// `NEUTRAL_VARIANT_OFFSET`（私有常量）的规则。nv 的那一半偏离见 `color` 模块文档的偏离登记。
+///
+/// 同样只服务于「出厂预选色卡」（D38 第三级），不约束将来的取色结果。
+/// 内置多套色卡落地时每张卡各带自己的中性彩度（`palette::Card::neutral_chroma`），八张卡
+/// 当前都取本值；再加上中性**色相**固定为 [`NEUTRAL_HUE_DEG`]（D43），八张卡的表面色因此
+/// 逐值相同——切卡只换强调色。
+pub const DEFAULT_NEUTRAL_CHROMA: f64 = 12.0;
+
+/// 中性调色板的**固定色相**（度）——内置色卡共用它，动态取色不用它（D43）。
+///
+/// ## 出处：这就是「天蓝」档当前用的那个中性色相
+///
+/// 值等于 [`DEFAULT_SEED`]（`#3C8DBC`）的 CAM16 色相 **239.51420577630955°**。天蓝档的中性
+/// 调色板本来就是这个色相（`from_seed_with_neutral_chroma` 让中性色跟着种子走），所以它是
+/// **沿用**，不是「另选一个冷调」：`Card::scheme` 换用它之后天蓝卡的 49 个角色必须逐值不变
+/// （`tests/card_neutral.rs` 钉着）。
+///
+/// ## 为什么要有这个常量（D43）
+///
+/// 八张卡原先走 TonalSpot 的「中性色也跟种子染色」，切卡连窗口底色一起换调子：浅色档
+/// `surface` 的实测 CAM16 彩度从 **1.29（rose）跨到 12.03（teal）**——tone 98 处暖相色域装
+/// 不下彩度 12，「请求值 12」在暖相上只能兑现 1.29，9 倍跳变让用户觉得「每张卡都像换了个
+/// 应用」。D43 的处置：**色卡固定中性色相、只换强调色**；动态取色（背景图 / 壁纸）保留逐色
+/// 染色，那才是用户要的 Monet 体验。所以本常量只服务色卡路径，**不要**传给 `Seed::scheme`。
+///
+/// ⚠️ 换 [`DEFAULT_SEED`] 时本常量会「过期」：`neutral_hue_is_the_default_seed_hue` 用
+/// 1e-9° 容差钉住两者的绑定（**不用 `to_bits` 位相等**——色相来自跨平台有末位差的 `atan2`），
+/// 改了种子它就红——那时要想清楚是「色卡跟着新默认色走」（照抄新色相）还是「色卡保持这条
+/// 冷调」（改成显式例外），别静默漂移。
+pub const NEUTRAL_HUE_DEG: f64 = 239.514_205_776_309_55;
+
+/// 调色板槽位（M3 的六条 tonal palette）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PaletteSlot {
+    /// 主调色板（种子色相，彩度 36）。
+    Primary,
+    /// 次调色板（同色相，彩度 16）。
+    Secondary,
+    /// 第三调色板（种子色相 +60°，彩度 24）。
+    Tertiary,
+    /// 中性调色板（色相跟种子；**色卡路径**例外——固定为 [`NEUTRAL_HUE_DEG`]，D43。
+    /// 官方彩度 6，产品默认 12——见 [`DEFAULT_NEUTRAL_CHROMA`]）。
+    Neutral,
+    /// 中性变体调色板（色相同 neutral，彩度 = neutral + 2；官方 8，产品默认 14）。
+    NeutralVariant,
+    /// 错误调色板（固定红相 25°，彩度 84）。
+    Error,
+}
+
+/// Tonal Spot 的 primary 彩度（官方常数，与种子彩度无关）。
+const PRIMARY_CHROMA: f64 = 36.0;
+/// secondary 彩度。
+const SECONDARY_CHROMA: f64 = 16.0;
+/// tertiary 彩度。
+const TERTIARY_CHROMA: f64 = 24.0;
+/// 官方 Tonal Spot 的 neutral 彩度（几乎是灰）。产品默认用 [`DEFAULT_NEUTRAL_CHROMA`]。
+const TONAL_SPOT_NEUTRAL_CHROMA: f64 = 6.0;
+/// neutral-variant 相对 neutral 的彩度偏移。
+///
+/// ⚠️ 官方 `getNeutralVariantPalette` 写死的是**绝对值 8**，**不是**「neutral + 2」这种相对式；
+/// 本实现选择让 neutral-variant 随 neutral 联动，于是产品默认（neutral 12）取到 **14**。
+/// 这是**有意偏离**的另一半（见 `color` 模块文档的偏离登记），不是官方口径——
+/// 官方的 6 / 8 由 [`Palettes::official_baseline`] 原样保留。
+const NEUTRAL_VARIANT_OFFSET: f64 = 2.0;
+/// error 的色相（HCT 红相）。
+const ERROR_HUE_DEG: f64 = 25.0;
+/// error 的彩度。
+const ERROR_CHROMA: f64 = 84.0;
+/// tertiary 相对种子的色相偏移。
+const TERTIARY_HUE_SHIFT_DEG: f64 = 60.0;
+
+/// 一套完整的六条调色板。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Palettes {
+    /// 主要调色板。
+    pub primary: TonalPalette,
+    /// 次要调色板。
+    pub secondary: TonalPalette,
+    /// 第三调色板。
+    pub tertiary: TonalPalette,
+    /// 中性调色板。
+    pub neutral: TonalPalette,
+    /// 中性变体调色板。
+    pub neutral_variant: TonalPalette,
+    /// 错误调色板。
+    pub error: TonalPalette,
+}
+
+impl Palettes {
+    /// **产品出厂默认**：种子 [`DEFAULT_SEED`] + 中性彩度 [`DEFAULT_NEUTRAL_CHROMA`]。
+    ///
+    /// 消费方（`DesignTokens::baseline`、iced 适配层）拿到的就是这套，所以产品默认色
+    /// 只需要改那两个常量。
+    pub fn baseline() -> Self {
+        Self::from_seed_with_neutral_chroma(DEFAULT_SEED, DEFAULT_NEUTRAL_CHROMA)
+    }
+
+    /// **官方基线的锚点**：种子 [`BASELINE_SEED`] + 官方中性彩度 6（等价官方
+    /// `SchemeTonalSpot(0xFF6750A4)`）。只给对齐测试与文档表格用。
+    pub fn official_baseline() -> Self {
+        Self::from_seed(BASELINE_SEED)
+    }
+
+    /// 从一个种子色派生全套调色板（官方 Tonal Spot 变体，中性彩度取官方 6）。
+    pub fn from_seed(seed: Color) -> Self {
+        Self::from_seed_with_neutral_chroma(seed, TONAL_SPOT_NEUTRAL_CHROMA)
+    }
+
+    /// 从一个种子色派生，并显式指定中性调色板彩度（`6.0` 即官方 Tonal Spot）。
+    ///
+    /// ⚠️ **调用方负责传 `6.0..=13.0`（产品取 12）**。本函数**不做范围校验**，越界的表现是
+    /// 静默退化而不是 panic：
+    /// - `neutral_chroma < 0` 或 `NaN` → 彩度被夹到 0（`TonalPalette::new` 里 `.max(0.0)`），
+    ///   得到一套纯灰的表面（surface ≈ `#F9F9F9`），**不报错**；
+    /// - `neutral_chroma >= 14` → neutral-variant（= neutral + 2）够到甚至超过 secondary 的 16，
+    ///   「中性 < 中性变体 < 次色」的层次被破坏（描边会明显发蓝）。
+    ///
+    /// 除 neutral / neutral-variant 外**全部走官方常数**：primary 恒定 36、secondary 16、
+    /// tertiary 24（色相 +60°）、error 固定 25°/84。所以这条入口不绕算法，只是把「官方写死在
+    /// `getNeutralPalette` / `getNeutralVariantPalette` 里的那两个数」变成可调入参
+    /// （neutral-variant 这里取相对式 `neutral + 2`，属**有意偏离**，见 `NEUTRAL_VARIANT_OFFSET`）。
+    pub fn from_seed_with_neutral_chroma(seed: Color, neutral_chroma: f64) -> Self {
+        let hue = super::Hct::from_color(seed).hue;
+        Self::tonal_spot(hue, neutral_chroma)
+    }
+
+    /// 只换强调色：primary/secondary/tertiary 跟着新强调色的色相走，
+    /// **表面中性色与错误色保持不变**。
+    ///
+    /// 这是本项目的产品语义（换强调色不该让整个窗口底色变脏，见 `DesignTokens::with_accent`）：
+    /// 强调族的色值与官方 `from_seed(accent)` 逐个对得上，中性表面则仍走基线——
+    /// 官方 `from_seed` 会把中性色也染上种子的色相，那是「整窗染色」，不是我们要的。
+    pub fn with_accent(self, accent: Color) -> Self {
+        let hue = super::Hct::from_color(accent).hue;
+        Self {
+            primary: TonalPalette::new(hue, PRIMARY_CHROMA),
+            secondary: TonalPalette::new(hue, SECONDARY_CHROMA),
+            tertiary: TonalPalette::new(hue + TERTIARY_HUE_SHIFT_DEG, TERTIARY_CHROMA),
+            ..self
+        }
+    }
+
+    /// **内置色卡的派生入口（D43）**：强调三族跟 `accent` 的色相走，中性族（含
+    /// neutral-variant）**固定在 `neutral_hue_deg`**。
+    ///
+    /// 与 [`Palettes::from_seed_with_neutral_chroma`]（TonalSpot，中性色跟着种子染色）的唯一
+    /// 差别是中性族色相；与 [`Palettes::with_accent`] 的差别是中性族可以整体搬到一个不属于
+    /// 基线的色相上（`with_accent` 只能沿用 `self` 的中性族）。
+    ///
+    /// 产品用法：色卡路径传 [`NEUTRAL_HUE_DEG`]（= 出厂默认种子的中性色相），于是八张卡的
+    /// 表面色完全相同，只有强调色在换。**取色路径不要用本函数**——D43 明确保留「按图像种子
+    /// 逐色染色」的 Monet 体验（见 [`crate::palette::resolve`]）。
+    pub fn accent_on_fixed_neutral(
+        accent: Color,
+        neutral_hue_deg: f64,
+        neutral_chroma: f64,
+    ) -> Self {
+        let hue = super::Hct::from_color(accent).hue;
+        Self::tonal_spot_with_neutral(hue, neutral_hue_deg, neutral_chroma)
+    }
+
+    /// 官方 Tonal Spot 的六条调色板（色相来自种子，彩度取官方常数，neutral 可调）。
+    fn tonal_spot(hue: f64, neutral_chroma: f64) -> Self {
+        Self::tonal_spot_with_neutral(hue, hue, neutral_chroma)
+    }
+
+    /// 同一套 Tonal Spot，但**中性族（neutral / neutral-variant）的色相可以与种子不同**。
+    ///
+    /// 这是 D43「内置色卡固定中性色相」的实现核心：强调三族跟 `accent_hue`，表面族跟
+    /// `neutral_hue`。其余彩度常数、error 族、tone 表一行未动。
+    fn tonal_spot_with_neutral(accent_hue: f64, neutral_hue: f64, neutral_chroma: f64) -> Self {
+        Self {
+            primary: TonalPalette::new(accent_hue, PRIMARY_CHROMA),
+            secondary: TonalPalette::new(accent_hue, SECONDARY_CHROMA),
+            tertiary: TonalPalette::new(accent_hue + TERTIARY_HUE_SHIFT_DEG, TERTIARY_CHROMA),
+            neutral: TonalPalette::new(neutral_hue, neutral_chroma),
+            neutral_variant: TonalPalette::new(
+                neutral_hue,
+                neutral_chroma + NEUTRAL_VARIANT_OFFSET,
+            ),
+            error: TonalPalette::new(ERROR_HUE_DEG, ERROR_CHROMA),
+        }
+    }
+
+    /// 按槽位取调色板。
+    pub fn slot(&self, slot: PaletteSlot) -> TonalPalette {
+        match slot {
+            PaletteSlot::Primary => self.primary,
+            PaletteSlot::Secondary => self.secondary,
+            PaletteSlot::Tertiary => self.tertiary,
+            PaletteSlot::Neutral => self.neutral,
+            PaletteSlot::NeutralVariant => self.neutral_variant,
+            PaletteSlot::Error => self.error,
+        }
+    }
+
+    /// 方案级取色：槽位 + tone → 色值。
+    pub fn tone(&self, slot: PaletteSlot, tone: f64) -> Color {
+        self.slot(slot).tone(tone)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn official_baseline_uses_the_official_tonal_spot_chromas() {
+        let palettes = Palettes::official_baseline();
+        assert_eq!(palettes.primary.chroma(), 36.0);
+        assert_eq!(palettes.secondary.chroma(), 16.0);
+        assert_eq!(palettes.tertiary.chroma(), 24.0);
+        assert_eq!(palettes.neutral.chroma(), 6.0);
+        assert_eq!(palettes.neutral_variant.chroma(), 8.0);
+        assert_eq!(palettes.error.hue_deg(), 25.0);
+        assert_eq!(palettes.error.chroma(), 84.0);
+    }
+
+    #[test]
+    fn product_default_only_moves_the_named_knobs() {
+        // 产品默认与官方锚点的差别必须**只**在种子色相与中性彩度两处：
+        // primary/secondary/tertiary/error 的取法一模一样（算法没动）。
+        let official = Palettes::official_baseline();
+        let product = Palettes::baseline();
+        assert_eq!(product.primary.chroma(), official.primary.chroma());
+        assert_eq!(product.secondary.chroma(), official.secondary.chroma());
+        assert_eq!(product.tertiary.chroma(), official.tertiary.chroma());
+        assert_eq!(product.error, official.error);
+        assert_eq!(product.neutral.chroma(), DEFAULT_NEUTRAL_CHROMA);
+        assert_eq!(
+            product.neutral_variant.chroma(),
+            DEFAULT_NEUTRAL_CHROMA + NEUTRAL_VARIANT_OFFSET
+        );
+        let seed = super::super::Hct::from_color(DEFAULT_SEED);
+        assert!((product.primary.hue_deg() - seed.hue).abs() < 1.0e-9);
+    }
+
+    #[test]
+    fn neutral_chroma_knob_keeps_the_official_ordering() {
+        // 官方关系 neutral(6) < neutral-variant(8) < secondary(16) 在安全区间里必须一直成立，
+        // 否则「表面比次色还艳」或两族撞色。
+        for neutral in [6.0, 8.0, 10.0, 12.0] {
+            let p = Palettes::from_seed_with_neutral_chroma(DEFAULT_SEED, neutral);
+            assert!(p.neutral.chroma() < p.neutral_variant.chroma());
+            assert!(p.neutral_variant.chroma() < p.secondary.chroma());
+            // 中性彩度不影响 tone 轴：tone 98 的 surface 仍是最亮的那个。
+            let surface = p.tone(PaletteSlot::Neutral, 98.0);
+            assert!(surface.relative_luminance() > 0.9);
+        }
+    }
+
+    #[test]
+    fn product_default_neutral_chroma_is_a_registered_deviation() {
+        // 官方 neutral / neutral-variant 是 6 / 8；产品默认是 12 / 14。
+        // 这**不是官方口径**，是「有意偏离」（见 `color` 模块文档的偏离登记）。
+        // 想把 nv 拉回官方绝对值 8 的人，请先改登记再改这里：直接钉成 8 会让表面（12）
+        // 比中性变体（8）更「有色」，破坏官方的 neutral < neutral-variant 层次。
+        let product = Palettes::baseline();
+        assert_eq!(product.neutral.chroma(), 12.0, "产品默认 neutral 彩度");
+        assert_eq!(
+            product.neutral_variant.chroma(),
+            14.0,
+            "产品默认的 neutral-variant 彩度 14 是**有意偏离**（官方绝对值 8），改前先更新偏离登记"
+        );
+        let official = Palettes::official_baseline();
+        assert_eq!(official.neutral.chroma(), 6.0, "官方锚点仍是 6");
+        assert_eq!(
+            official.neutral_variant.chroma(),
+            8.0,
+            "官方锚点仍是绝对值 8（不是 neutral + 2 的相对式）"
+        );
+    }
+
+    #[test]
+    fn baseline_hue_comes_from_the_seed() {
+        let palettes = Palettes::official_baseline();
+        let seed = super::super::Hct::from_color(BASELINE_SEED);
+        assert!((palettes.primary.hue_deg() - seed.hue).abs() < 1.0e-9);
+        assert!((palettes.neutral.hue_deg() - seed.hue).abs() < 1.0e-9);
+        assert!((palettes.tertiary.hue_deg() - (seed.hue + 60.0)).abs() < 1.0e-9);
+    }
+
+    #[test]
+    fn seed_chroma_never_leaks_into_the_primary_ramp() {
+        // 官方口径：Tonal Spot 的彩度是常数，纯灰种子也会得到彩度 36 的主色板。
+        let gray = Palettes::from_seed(Color::rgb(0x6E, 0x6E, 0x6E));
+        assert_eq!(gray.primary.chroma(), 36.0);
+        let hot = Palettes::from_seed(Color::rgb(0xFF, 0x00, 0x00));
+        assert_eq!(hot.primary.chroma(), 36.0);
+    }
+
+    #[test]
+    fn accent_override_keeps_surfaces_and_error() {
+        let base = Palettes::baseline();
+        let swapped = base.with_accent(Color::rgb(0x00, 0x6A, 0x5C));
+        assert_eq!(swapped.neutral, base.neutral);
+        assert_eq!(swapped.neutral_variant, base.neutral_variant);
+        assert_eq!(swapped.error, base.error);
+        assert_ne!(swapped.primary.hue_deg(), base.primary.hue_deg());
+        assert_eq!(swapped.primary.chroma(), 36.0);
+    }
+
+    #[test]
+    fn neutral_hue_is_the_default_seed_hue() {
+        // D43 的绑定器。用 1e-9° 容差而非 `to_bits()` 位相等：色相来自 `atan2()`，glibc 与
+        // UCRT 理论可差 1 ulp（~1e-14°），位相等会在另一个 OS 的 CI 上红；这条要抓的是「换了
+        // `DEFAULT_SEED` 却没复核常量」（偏几十度）。「逐值不变」的位相等钉子在同平台的
+        // `card_neutral.rs::sky_card_is_bit_identical_to_the_product_baseline`（两个算出的值
+        // 互比，不涉及跨平台字面量）。
+        let seed_hue = super::super::Hct::from_color(DEFAULT_SEED).hue;
+        assert!(
+            (NEUTRAL_HUE_DEG - seed_hue).abs() < 1.0e-9,
+            "NEUTRAL_HUE_DEG = {NEUTRAL_HUE_DEG:?} 与 DEFAULT_SEED 的色相 {seed_hue:?} \
+             相差超过 1e-9°（换默认种子时：要么照抄新色相，要么把这里改成显式例外）"
+        );
+    }
+
+    #[test]
+    fn accent_on_fixed_neutral_only_moves_the_neutral_hue() {
+        let official = Palettes::official_baseline();
+        // 中性色相 = 基线色相时，与官方的 from_seed 完全等价（不放宽算法）。
+        let same = Palettes::accent_on_fixed_neutral(DEFAULT_SEED, NEUTRAL_HUE_DEG, 12.0);
+        let per_seed = Palettes::from_seed_with_neutral_chroma(DEFAULT_SEED, 12.0);
+        assert_eq!(
+            same, per_seed,
+            "中性色相取种子色相时必须与 TonalSpot 逐项相同"
+        );
+
+        // 换一个中性色相：只有中性两族的色相动，彩度与强调族一律不动。
+        let moved = Palettes::accent_on_fixed_neutral(DEFAULT_SEED, 120.0, 12.0);
+        assert_eq!(moved.primary, per_seed.primary);
+        assert_eq!(moved.secondary, per_seed.secondary);
+        assert_eq!(moved.tertiary, per_seed.tertiary);
+        assert_eq!(moved.error, per_seed.error);
+        assert_eq!(moved.neutral.chroma(), per_seed.neutral.chroma());
+        assert_eq!(
+            moved.neutral_variant.chroma(),
+            per_seed.neutral_variant.chroma()
+        );
+        assert_eq!(moved.neutral.hue_deg(), 120.0);
+        assert_eq!(moved.neutral_variant.hue_deg(), 120.0);
+        assert_eq!(moved.primary.chroma(), official.primary.chroma());
+    }
+}
diff --git a/crates/design/src/color/roles.rs b/crates/design/src/color/roles.rs
new file mode 100644
index 0000000..4466cb7
--- /dev/null
+++ b/crates/design/src/color/roles.rs
@@ -0,0 +1,276 @@
+//! M3 语义色角色：`Role` 枚举是**唯一的名字清单**（49 个，M3 基础集全覆盖）。
+//!
+//! 后续 iced 页面不许另起名字（如 `bg-card` / `fg-primary`）——Fluent 时代的旧名到此为止，
+//! 要表达「卡片底」就用 [`Role::SurfaceContainerLow`]，要表达「次要文字」就用
+//! [`Role::OnSurfaceVariant`]（对应关系见 `DevDocs/SubAgentsTalk/design-令牌约定.md`）。
+
+/// M3 语义色角色（49 个）。
+///
+/// 顺序即 [`Role::ALL`] 的顺序，也是 [`super::Scheme`] 内部数组的下标：
+/// **只允许在末尾追加**，插到中间会静默改变已存盘的颜色映射。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub enum Role {
+    /// 主色：主操作填充、选中指示。
+    Primary,
+    /// 主色之上的前景（文字/图标）。
+    OnPrimary,
+    /// 主色容器：次级强调块、选中片。
+    PrimaryContainer,
+    /// 主色容器之上的前景。
+    OnPrimaryContainer,
+    /// 次色：低频强调、图表。
+    Secondary,
+    /// 次色之上的前景。
+    OnSecondary,
+    /// 次色容器。
+    SecondaryContainer,
+    /// 次色容器之上的前景。
+    OnSecondaryContainer,
+    /// 第三色：与主/次形成对比的装饰强调。
+    Tertiary,
+    /// 第三色之上的前景。
+    OnTertiary,
+    /// 第三色容器。
+    TertiaryContainer,
+    /// 第三色容器之上的前景。
+    OnTertiaryContainer,
+    /// 错误色：错误文字、危险操作填充。
+    Error,
+    /// 错误色之上的前景。
+    OnError,
+    /// 错误容器：错误提示底。
+    ErrorContainer,
+    /// 错误容器之上的前景。
+    OnErrorContainer,
+    /// 表面：窗口/内容底色（M3 最新口径里取代 background）。
+    Surface,
+    /// 表面之上的主体文字。
+    OnSurface,
+    /// 表面变体：中性分隔/次级容器（**不是**文字色）。
+    SurfaceVariant,
+    /// 表面变体之上的次级文字/图标。
+    OnSurfaceVariant,
+    /// 背景（M3 已并入 surface，保留以兼容旧值）。
+    Background,
+    /// 背景之上的文本（同上，保留兼容）。
+    OnBackground,
+    /// 变暗的表面（模态背后的压暗层）。
+    SurfaceDim,
+    /// 变亮的表面（深色下的抬高底）。
+    SurfaceBright,
+    /// 最低层容器（比 surface 更低）。
+    SurfaceContainerLowest,
+    /// 低层容器：卡片。
+    SurfaceContainerLow,
+    /// 标准容器：卡片/面板。
+    SurfaceContainer,
+    /// 高层容器：浮层。
+    SurfaceContainerHigh,
+    /// 最高层容器：对话框/菜单。
+    SurfaceContainerHighest,
+    /// 描边：输入框边框等（非文字，3:1 即可）。
+    Outline,
+    /// 弱描边：分隔线（纯装饰）。
+    OutlineVariant,
+    /// 反相表面：Snackbar / Tooltip 底。
+    InverseSurface,
+    /// 反相表面之上的文字。
+    InverseOnSurface,
+    /// 反相表面之上的强调。
+    InversePrimary,
+    /// 阴影色（通常带 alpha，见 [`super::Scheme::shadow`]）。
+    Shadow,
+    /// 遮罩色（模态背景，通常带 alpha）。
+    Scrim,
+    /// 表面着色（M3 旧规范的 elevation tint，现已被 surface container 取代）。
+    SurfaceTint,
+    /// 固定主色（深浅模式同值，用于需要跨模式稳定的块）。
+    PrimaryFixed,
+    /// 固定主色的暗档。
+    PrimaryFixedDim,
+    /// 固定主色之上的前景。
+    OnPrimaryFixed,
+    /// 固定主色暗档之上的前景。
+    OnPrimaryFixedVariant,
+    /// 固定次色。
+    SecondaryFixed,
+    /// 固定次色的暗档。
+    SecondaryFixedDim,
+    /// 固定次色之上的前景。
+    OnSecondaryFixed,
+    /// 固定次色暗档之上的前景。
+    OnSecondaryFixedVariant,
+    /// 固定第三色。
+    TertiaryFixed,
+    /// 固定第三色的暗档。
+    TertiaryFixedDim,
+    /// 固定第三色之上的前景。
+    OnTertiaryFixed,
+    /// 固定第三色暗档之上的前景。
+    OnTertiaryFixedVariant,
+}
+
+impl Role {
+    /// 全部 49 个角色，按 `Role as usize` 顺序排列。
+    pub const ALL: [Role; 49] = [
+        Role::Primary,
+        Role::OnPrimary,
+        Role::PrimaryContainer,
+        Role::OnPrimaryContainer,
+        Role::Secondary,
+        Role::OnSecondary,
+        Role::SecondaryContainer,
+        Role::OnSecondaryContainer,
+        Role::Tertiary,
+        Role::OnTertiary,
+        Role::TertiaryContainer,
+        Role::OnTertiaryContainer,
+        Role::Error,
+        Role::OnError,
+        Role::ErrorContainer,
+        Role::OnErrorContainer,
+        Role::Surface,
+        Role::OnSurface,
+        Role::SurfaceVariant,
+        Role::OnSurfaceVariant,
+        Role::Background,
+        Role::OnBackground,
+        Role::SurfaceDim,
+        Role::SurfaceBright,
+        Role::SurfaceContainerLowest,
+        Role::SurfaceContainerLow,
+        Role::SurfaceContainer,
+        Role::SurfaceContainerHigh,
+        Role::SurfaceContainerHighest,
+        Role::Outline,
+        Role::OutlineVariant,
+        Role::InverseSurface,
+        Role::InverseOnSurface,
+        Role::InversePrimary,
+        Role::Shadow,
+        Role::Scrim,
+        Role::SurfaceTint,
+        Role::PrimaryFixed,
+        Role::PrimaryFixedDim,
+        Role::OnPrimaryFixed,
+        Role::OnPrimaryFixedVariant,
+        Role::SecondaryFixed,
+        Role::SecondaryFixedDim,
+        Role::OnSecondaryFixed,
+        Role::OnSecondaryFixedVariant,
+        Role::TertiaryFixed,
+        Role::TertiaryFixedDim,
+        Role::OnTertiaryFixed,
+        Role::OnTertiaryFixedVariant,
+    ];
+
+    /// 稳定字符串名（kebab-case），用于日志、配置、快照对拍与文档表格。
+    pub const fn name(self) -> &'static str {
+        match self {
+            Role::Primary => "primary",
+            Role::OnPrimary => "on-primary",
+            Role::PrimaryContainer => "primary-container",
+            Role::OnPrimaryContainer => "on-primary-container",
+            Role::Secondary => "secondary",
+            Role::OnSecondary => "on-secondary",
+            Role::SecondaryContainer => "secondary-container",
+            Role::OnSecondaryContainer => "on-secondary-container",
+            Role::Tertiary => "tertiary",
+            Role::OnTertiary => "on-tertiary",
+            Role::TertiaryContainer => "tertiary-container",
+            Role::OnTertiaryContainer => "on-tertiary-container",
+            Role::Error => "error",
+            Role::OnError => "on-error",
+            Role::ErrorContainer => "error-container",
+            Role::OnErrorContainer => "on-error-container",
+            Role::Surface => "surface",
+            Role::OnSurface => "on-surface",
+            Role::SurfaceVariant => "surface-variant",
+            Role::OnSurfaceVariant => "on-surface-variant",
+            Role::Background => "background",
+            Role::OnBackground => "on-background",
+            Role::SurfaceDim => "surface-dim",
+            Role::SurfaceBright => "surface-bright",
+            Role::SurfaceContainerLowest => "surface-container-lowest",
+            Role::SurfaceContainerLow => "surface-container-low",
+            Role::SurfaceContainer => "surface-container",
+            Role::SurfaceContainerHigh => "surface-container-high",
+            Role::SurfaceContainerHighest => "surface-container-highest",
+            Role::Outline => "outline",
+            Role::OutlineVariant => "outline-variant",
+            Role::InverseSurface => "inverse-surface",
+            Role::InverseOnSurface => "inverse-on-surface",
+            Role::InversePrimary => "inverse-primary",
+            Role::Shadow => "shadow",
+            Role::Scrim => "scrim",
+            Role::SurfaceTint => "surface-tint",
+            Role::PrimaryFixed => "primary-fixed",
+            Role::PrimaryFixedDim => "primary-fixed-dim",
+            Role::OnPrimaryFixed => "on-primary-fixed",
+            Role::OnPrimaryFixedVariant => "on-primary-fixed-variant",
+            Role::SecondaryFixed => "secondary-fixed",
+            Role::SecondaryFixedDim => "secondary-fixed-dim",
+            Role::OnSecondaryFixed => "on-secondary-fixed",
+            Role::OnSecondaryFixedVariant => "on-secondary-fixed-variant",
+            Role::TertiaryFixed => "tertiary-fixed",
+            Role::TertiaryFixedDim => "tertiary-fixed-dim",
+            Role::OnTertiaryFixed => "on-tertiary-fixed",
+            Role::OnTertiaryFixedVariant => "on-tertiary-fixed-variant",
+        }
+    }
+
+    /// 该角色是否是「文字/图标前景色」（`on-*` 与 `inverse-on-surface` 一类）。
+    ///
+    /// 用于对比度门禁区分两类要求：前景对容器 ≥ 4.5:1（WCAG AA 正文），
+    /// 非文字元素 ≥ 3:1。
+    pub const fn is_foreground(self) -> bool {
+        matches!(
+            self,
+            Role::OnPrimary
+                | Role::OnPrimaryContainer
+                | Role::OnSecondary
+                | Role::OnSecondaryContainer
+                | Role::OnTertiary
+                | Role::OnTertiaryContainer
+                | Role::OnError
+                | Role::OnErrorContainer
+                | Role::OnSurface
+                | Role::OnSurfaceVariant
+                | Role::OnBackground
+                | Role::InverseOnSurface
+                | Role::InversePrimary
+                | Role::OnPrimaryFixed
+                | Role::OnPrimaryFixedVariant
+                | Role::OnSecondaryFixed
+                | Role::OnSecondaryFixedVariant
+                | Role::OnTertiaryFixed
+                | Role::OnTertiaryFixedVariant
+        )
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn all_is_in_enum_order() {
+        for (i, role) in Role::ALL.iter().enumerate() {
+            assert_eq!(*role as usize, i, "Role::ALL 顺序必须等于枚举声明顺序");
+        }
+    }
+
+    #[test]
+    fn names_are_unique_and_kebab() {
+        let mut seen = std::collections::BTreeSet::new();
+        for role in Role::ALL {
+            let name = role.name();
+            assert!(seen.insert(name), "角色名重复：{name}");
+            assert!(
+                name.chars()
+                    .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-'),
+                "角色名必须是 kebab-case：{name}"
+            );
+        }
+    }
+}
diff --git a/crates/design/src/color/scheme.rs b/crates/design/src/color/scheme.rs
new file mode 100644
index 0000000..68892f8
--- /dev/null
+++ b/crates/design/src/color/scheme.rs
@@ -0,0 +1,342 @@
+//! 一套完整的 M3 语义色方案（`Scheme`）：角色 → 调色板槽位 → tone 的三段映射。
+//!
+//! tone 表取自 **ColorSpec2021** 的官方映射（`MaterialDynamicColors` 的 light/dark 两列，
+//! 见 `NOTICE`）。固定角色（`*-fixed*`）深浅同值，因为它们的用途就是「跨模式稳定」。
+//!
+//! ## 只实现了 contrast level = 0（standard）
+//!
+//! 官方的 `ColorSpec2021.getTone()` 还有一层机制：`toneDeltaPair`（成对角色保持 tone 差）
+//! 与 `ContrastCurve`（按对比度等级修正 tone）。在 **contrastLevel = 0** 下这层机制的输入
+//! 全部是常数：`ContrastCurve.get(0)` 恒等于 normal 档的 tone，而「背景 tone」也都是本表里的
+//! 常数，所以它对 49 个角色的调整结果**就是这张表本身**。测试
+//! `tests/official_baseline.rs` 用官方 Java 实现的逐角色输出反证了这一点（每通道误差 ≤1）：
+//! 表错一格，对齐测试就会红。三档对比度（medium/high）不在本 crate 范围内，见
+//! [`super`] 的 gap 登记。
+
+use super::palettes::{PaletteSlot, Palettes};
+use super::roles::Role;
+use super::Color;
+
+/// 深浅模式。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum SchemeFlavor {
+    /// 浅色（亮底暗字）。
+    Light,
+    /// 深色（暗底亮字）。
+    Dark,
+}
+
+impl SchemeFlavor {
+    /// 是否深色模式。
+    pub const fn is_dark(self) -> bool {
+        matches!(self, SchemeFlavor::Dark)
+    }
+
+    /// 反过来那一个。
+    pub const fn toggled(self) -> Self {
+        match self {
+            SchemeFlavor::Light => SchemeFlavor::Dark,
+            SchemeFlavor::Dark => SchemeFlavor::Light,
+        }
+    }
+
+    /// 稳定字符串名（`light` / `dark`），写配置与日志用。
+    pub const fn name(self) -> &'static str {
+        match self {
+            SchemeFlavor::Light => "light",
+            SchemeFlavor::Dark => "dark",
+        }
+    }
+}
+
+/// 阴影色透明度（M3 阴影 = 纯黑 + 这个 alpha；绘制阴影时叠在背景上）。
+pub const SHADOW_ALPHA: f32 = 0.20;
+/// 遮罩色透明度（模态背景压暗层）。
+pub const SCRIM_ALPHA: f32 = 0.32;
+
+/// 一条「角色 → 槽位 + tone」映射。
+struct ToneRow {
+    role: Role,
+    slot: PaletteSlot,
+    light: f64,
+    dark: f64,
+}
+
+/// 49 个角色的 tone 映射表（ColorSpec2021），**下标必须等于 `Role as usize`**（由测试钉死）。
+const TONE_TABLE: [ToneRow; 49] = [
+    row(Role::Primary, PaletteSlot::Primary, 40.0, 80.0),
+    row(Role::OnPrimary, PaletteSlot::Primary, 100.0, 20.0),
+    row(Role::PrimaryContainer, PaletteSlot::Primary, 90.0, 30.0),
+    row(Role::OnPrimaryContainer, PaletteSlot::Primary, 30.0, 90.0),
+    row(Role::Secondary, PaletteSlot::Secondary, 40.0, 80.0),
+    row(Role::OnSecondary, PaletteSlot::Secondary, 100.0, 20.0),
+    row(Role::SecondaryContainer, PaletteSlot::Secondary, 90.0, 30.0),
+    row(
+        Role::OnSecondaryContainer,
+        PaletteSlot::Secondary,
+        30.0,
+        90.0,
+    ),
+    row(Role::Tertiary, PaletteSlot::Tertiary, 40.0, 80.0),
+    row(Role::OnTertiary, PaletteSlot::Tertiary, 100.0, 20.0),
+    row(Role::TertiaryContainer, PaletteSlot::Tertiary, 90.0, 30.0),
+    row(Role::OnTertiaryContainer, PaletteSlot::Tertiary, 30.0, 90.0),
+    row(Role::Error, PaletteSlot::Error, 40.0, 80.0),
+    row(Role::OnError, PaletteSlot::Error, 100.0, 20.0),
+    row(Role::ErrorContainer, PaletteSlot::Error, 90.0, 30.0),
+    row(Role::OnErrorContainer, PaletteSlot::Error, 30.0, 90.0),
+    row(Role::Surface, PaletteSlot::Neutral, 98.0, 6.0),
+    row(Role::OnSurface, PaletteSlot::Neutral, 10.0, 90.0),
+    row(
+        Role::SurfaceVariant,
+        PaletteSlot::NeutralVariant,
+        90.0,
+        30.0,
+    ),
+    row(
+        Role::OnSurfaceVariant,
+        PaletteSlot::NeutralVariant,
+        30.0,
+        80.0,
+    ),
+    row(Role::Background, PaletteSlot::Neutral, 98.0, 6.0),
+    row(Role::OnBackground, PaletteSlot::Neutral, 10.0, 90.0),
+    row(Role::SurfaceDim, PaletteSlot::Neutral, 87.0, 6.0),
+    row(Role::SurfaceBright, PaletteSlot::Neutral, 98.0, 24.0),
+    row(
+        Role::SurfaceContainerLowest,
+        PaletteSlot::Neutral,
+        100.0,
+        4.0,
+    ),
+    row(Role::SurfaceContainerLow, PaletteSlot::Neutral, 96.0, 10.0),
+    row(Role::SurfaceContainer, PaletteSlot::Neutral, 94.0, 12.0),
+    row(Role::SurfaceContainerHigh, PaletteSlot::Neutral, 92.0, 17.0),
+    row(
+        Role::SurfaceContainerHighest,
+        PaletteSlot::Neutral,
+        90.0,
+        22.0,
+    ),
+    row(Role::Outline, PaletteSlot::NeutralVariant, 50.0, 60.0),
+    row(
+        Role::OutlineVariant,
+        PaletteSlot::NeutralVariant,
+        80.0,
+        30.0,
+    ),
+    row(Role::InverseSurface, PaletteSlot::Neutral, 20.0, 90.0),
+    row(Role::InverseOnSurface, PaletteSlot::Neutral, 95.0, 20.0),
+    row(Role::InversePrimary, PaletteSlot::Primary, 80.0, 40.0),
+    row(Role::Shadow, PaletteSlot::Neutral, 0.0, 0.0),
+    row(Role::Scrim, PaletteSlot::Neutral, 0.0, 0.0),
+    row(Role::SurfaceTint, PaletteSlot::Primary, 40.0, 80.0),
+    row(Role::PrimaryFixed, PaletteSlot::Primary, 90.0, 90.0),
+    row(Role::PrimaryFixedDim, PaletteSlot::Primary, 80.0, 80.0),
+    row(Role::OnPrimaryFixed, PaletteSlot::Primary, 10.0, 10.0),
+    row(
+        Role::OnPrimaryFixedVariant,
+        PaletteSlot::Primary,
+        30.0,
+        30.0,
+    ),
+    row(Role::SecondaryFixed, PaletteSlot::Secondary, 90.0, 90.0),
+    row(Role::SecondaryFixedDim, PaletteSlot::Secondary, 80.0, 80.0),
+    row(Role::OnSecondaryFixed, PaletteSlot::Secondary, 10.0, 10.0),
+    row(
+        Role::OnSecondaryFixedVariant,
+        PaletteSlot::Secondary,
+        30.0,
+        30.0,
+    ),
+    row(Role::TertiaryFixed, PaletteSlot::Tertiary, 90.0, 90.0),
+    row(Role::TertiaryFixedDim, PaletteSlot::Tertiary, 80.0, 80.0),
+    row(Role::OnTertiaryFixed, PaletteSlot::Tertiary, 10.0, 10.0),
+    row(
+        Role::OnTertiaryFixedVariant,
+        PaletteSlot::Tertiary,
+        30.0,
+        30.0,
+    ),
+];
+
+/// `const` 友好的行构造器（数组初始化里不能调用非 const fn 之外的东西）。
+const fn row(role: Role, slot: PaletteSlot, light: f64, dark: f64) -> ToneRow {
+    ToneRow {
+        role,
+        slot,
+        light,
+        dark,
+    }
+}
+
+/// 一套语义色（49 个角色，全部已解析成具体颜色）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Scheme {
+    flavor: SchemeFlavor,
+    colors: [Color; 49],
+}
+
+impl Scheme {
+    /// **产品出厂默认方案**（种子 [`super::palettes::DEFAULT_SEED`] + 中性彩度
+    /// [`super::palettes::DEFAULT_NEUTRAL_CHROMA`]，见 [`Palettes::baseline`]）。
+    pub fn baseline(flavor: SchemeFlavor) -> Self {
+        Self::from_palettes(&Palettes::baseline(), flavor)
+    }
+
+    /// **官方基线锚点**（种子 `#6750A4` + 官方中性彩度 6，等价官方
+    /// `SchemeTonalSpot(0xFF6750A4)`）。
+    ///
+    /// 与 [`Scheme::baseline`] 的区别只有入参：算法、tone 表、gamut 映射完全同一条路径，
+    /// 所以 `tests/official_baseline.rs` 拿它跟官方 Java 输出逐角色对账。
+    pub fn official_baseline(flavor: SchemeFlavor) -> Self {
+        Self::from_palettes(&Palettes::official_baseline(), flavor)
+    }
+
+    /// 指定种子色的方案（表面色与强调色同源，等价官方 `SchemeTonalSpot`）。
+    pub fn from_seed(flavor: SchemeFlavor, seed: Color) -> Self {
+        Self::from_palettes(&Palettes::from_seed(seed), flavor)
+    }
+
+    /// 只覆盖强调色（表面中性色仍走基线，见 [`Palettes::with_accent`]）。
+    pub fn from_accent(flavor: SchemeFlavor, accent: Color) -> Self {
+        Self::from_palettes(&Palettes::baseline().with_accent(accent), flavor)
+    }
+
+    /// 直接从调色板集合构建（高级入口：整仓测试与自定义 scheme 用）。
+    pub fn from_palettes(palettes: &Palettes, flavor: SchemeFlavor) -> Self {
+        let colors = std::array::from_fn(|i| {
+            let entry = &TONE_TABLE[i];
+            palettes.tone(entry.slot, Scheme::tone_of(entry.role, flavor))
+        });
+        Self { flavor, colors }
+    }
+
+    /// 从 49 个已解析色值直接构造（**底层入口**，下标必须等于 `Role as usize`）。
+    ///
+    /// 只给两类调用方用：
+    /// 1. `palette::wcag` 的对比度收敛——它按角色替换个别色值后要重新组装成一套方案；
+    /// 2. 测试——要能构造「故意不达标」的方案，比较度校验器才有反证。
+    ///
+    /// 常规路径一律走 [`Scheme::from_palettes`]：那样色值才是 tone 表的推导结果，
+    /// 而不是随手塞进来的数。
+    pub fn from_colors(flavor: SchemeFlavor, colors: [Color; 49]) -> Self {
+        Self { flavor, colors }
+    }
+
+    /// 该角色在指定模式下的 tone 值（M3 语义；文档表格、调试与测试用）。
+    pub fn tone_of(role: Role, flavor: SchemeFlavor) -> f64 {
+        let entry = &TONE_TABLE[role as usize];
+        debug_assert_eq!(entry.role, role, "TONE_TABLE 下标必须等于角色序号");
+        match flavor {
+            SchemeFlavor::Light => entry.light,
+            SchemeFlavor::Dark => entry.dark,
+        }
+    }
+
+    /// 取角色色值。
+    pub fn get(&self, role: Role) -> Color {
+        self.colors[role as usize]
+    }
+
+    /// 当前模式。
+    pub fn flavor(&self) -> SchemeFlavor {
+        self.flavor
+    }
+
+    /// 按角色顺序遍历（`for (role, color) in scheme.iter()`）。
+    pub fn iter(&self) -> impl Iterator<Item = (Role, Color)> + '_ {
+        Role::ALL.iter().copied().map(|role| (role, self.get(role)))
+    }
+
+    /// 阴影色（纯黑 + [`SHADOW_ALPHA`]）。
+    pub fn shadow(&self) -> Color {
+        self.get(Role::Shadow).with_alpha(SHADOW_ALPHA)
+    }
+
+    /// 遮罩色（纯黑 + [`SCRIM_ALPHA`]）。
+    pub fn scrim(&self) -> Color {
+        self.get(Role::Scrim).with_alpha(SCRIM_ALPHA)
+    }
+
+    /// 两个角色的 WCAG 对比度（1..21）。
+    pub fn contrast(&self, fg: Role, bg: Role) -> f32 {
+        self.get(fg).contrast_ratio(self.get(bg))
+    }
+}
+
+impl std::ops::Index<Role> for Scheme {
+    type Output = Color;
+
+    fn index(&self, role: Role) -> &Color {
+        &self.colors[role as usize]
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn tone_table_matches_role_order() {
+        for (i, entry) in TONE_TABLE.iter().enumerate() {
+            assert_eq!(
+                entry.role as usize,
+                i,
+                "TONE_TABLE 第 {i} 行是 {}，顺序与 Role 枚举不一致",
+                entry.role.name()
+            );
+        }
+    }
+
+    #[test]
+    fn fixed_roles_are_identical_across_flavors() {
+        let light = Scheme::baseline(SchemeFlavor::Light);
+        let dark = Scheme::baseline(SchemeFlavor::Dark);
+        for role in [
+            Role::PrimaryFixed,
+            Role::PrimaryFixedDim,
+            Role::OnPrimaryFixed,
+            Role::OnPrimaryFixedVariant,
+            Role::SecondaryFixed,
+            Role::TertiaryFixedDim,
+        ] {
+            assert_eq!(
+                light.get(role),
+                dark.get(role),
+                "{} 应跨模式同值",
+                role.name()
+            );
+        }
+    }
+
+    #[test]
+    fn light_and_dark_differ_on_text_pairs() {
+        let light = Scheme::baseline(SchemeFlavor::Light);
+        let dark = Scheme::baseline(SchemeFlavor::Dark);
+        assert_ne!(light.get(Role::OnSurface), dark.get(Role::OnSurface));
+        assert!(light.get(Role::Surface).relative_luminance() > 0.8);
+        assert!(dark.get(Role::Surface).relative_luminance() < 0.05);
+    }
+
+    #[test]
+    fn shadow_and_scrim_carry_alpha() {
+        let scheme = Scheme::baseline(SchemeFlavor::Light);
+        assert_eq!(scheme.shadow().a, (SHADOW_ALPHA * 255.0).round() as u8);
+        assert_eq!(scheme.scrim().a, (SCRIM_ALPHA * 255.0).round() as u8);
+    }
+
+    #[test]
+    fn accent_override_changes_primary_only() {
+        let base = Scheme::baseline(SchemeFlavor::Light);
+        let teal = Scheme::from_accent(SchemeFlavor::Light, Color::rgb(0x00, 0x6A, 0x5C));
+        assert_ne!(base.get(Role::Primary), teal.get(Role::Primary));
+        assert_eq!(base.get(Role::Surface), teal.get(Role::Surface));
+        assert_eq!(
+            base.get(Role::Outline),
+            teal.get(Role::Outline),
+            "强调色覆盖不该动中性描边"
+        );
+        assert_eq!(base.get(Role::Error), teal.get(Role::Error));
+    }
+}
diff --git a/crates/design/src/color/space.rs b/crates/design/src/color/space.rs
new file mode 100644
index 0000000..e721235
--- /dev/null
+++ b/crates/design/src/color/space.rs
@@ -0,0 +1,217 @@
+//! 色彩空间底层换算：sRGB ↔ 线性 RGB ↔ CIE XYZ ↔ `L*`（tone 轴）。
+//!
+//! 只放**纯数学**，不认识任何语义色角色。数值口径逐函数照搬 Google
+//! `material-color-utilities` 的 `java/utils/ColorUtils.java`（Apache-2.0，见 `NOTICE`）：
+//! 矩阵、阈值、取整方式都一致——差一位小数，HCT 求解器就会与官方差一个通道。
+//!
+//! 内部一律用 `f64`（官方实现是 Java `double`）。公开 API 仍以 `u8` 通道与 `f32` 标量对外，
+//! 因为令牌消费方（绘制层）不需要比 8 bit 更高的精度。
+
+use super::Color;
+
+/// sRGB → XYZ（D65）。官方用的是 IEC 6-1 的舍入值，不是更精确的 sRGB 矩阵。
+const SRGB_TO_XYZ: [[f64; 3]; 3] = [
+    [0.412_338_95, 0.357_620_64, 0.180_510_42],
+    [0.2126, 0.7152, 0.0722],
+    [0.019_321_41, 0.119_163_82, 0.950_344_78],
+];
+
+/// D65 白点（XYZ，Y 归一化到 100）。
+pub(crate) const WHITE_POINT_D65: [f64; 3] = [95.047, 100.0, 108.883];
+
+/// 行向量 × 3×3 矩阵。
+pub(crate) fn matrix_multiply(row: [f64; 3], matrix: [[f64; 3]; 3]) -> [f64; 3] {
+    let mul = |m: [f64; 3]| row[0] * m[0] + row[1] * m[1] + row[2] * m[2];
+    [mul(matrix[0]), mul(matrix[1]), mul(matrix[2])]
+}
+
+/// sRGB 编码值（8 bit 通道）→ 线性光强（0..=100，官方标度）。
+pub(crate) fn linearized(component: u8) -> f64 {
+    let normalized = f64::from(component) / 255.0;
+    if normalized <= 0.040_449_936 {
+        normalized / 12.92 * 100.0
+    } else {
+        ((normalized + 0.055) / 1.055).powf(2.4) * 100.0
+    }
+}
+
+/// 线性光强（0..=100）→ sRGB 编码值，四舍五入并夹取到 0..=255。
+pub(crate) fn delinearized(component: f64) -> u8 {
+    let value = true_delinearized(component).round().clamp(0.0, 255.0);
+    value as u8
+}
+
+/// 同 [`delinearized`]，但不取整也不夹取（求解器二分时需要连续值）。
+pub(crate) fn true_delinearized(component: f64) -> f64 {
+    let normalized = component / 100.0;
+    let encoded = if normalized <= 0.003_130_8 {
+        normalized * 12.92
+    } else {
+        1.055 * normalized.powf(1.0 / 2.4) - 0.055
+    };
+    encoded * 255.0
+}
+
+/// 线性 RGB（0..=100）→ 不透明颜色。
+pub(crate) fn color_from_linrgb(linrgb: [f64; 3]) -> Color {
+    Color::rgb(
+        delinearized(linrgb[0]),
+        delinearized(linrgb[1]),
+        delinearized(linrgb[2]),
+    )
+}
+
+/// 色值 → XYZ（Y 在 0..=100 标度）。
+pub(crate) fn xyz_from_color(color: Color) -> [f64; 3] {
+    let linear = [
+        linearized(color.r),
+        linearized(color.g),
+        linearized(color.b),
+    ];
+    matrix_multiply(linear, SRGB_TO_XYZ)
+}
+
+/// `L*` 的比较函数（CIE 分段线性/立方根）。
+fn lab_f(t: f64) -> f64 {
+    const EPSILON: f64 = 216.0 / 24389.0;
+    const KAPPA: f64 = 24389.0 / 27.0;
+    if t > EPSILON {
+        t.powf(1.0 / 3.0)
+    } else {
+        (KAPPA * t + 16.0) / 116.0
+    }
+}
+
+/// [`lab_f`] 的逆。
+fn lab_invf(ft: f64) -> f64 {
+    const EPSILON: f64 = 216.0 / 24389.0;
+    const KAPPA: f64 = 24389.0 / 27.0;
+    let cubed = ft * ft * ft;
+    if cubed > EPSILON {
+        cubed
+    } else {
+        (116.0 * ft - 16.0) / KAPPA
+    }
+}
+
+/// `L*` → 相对亮度 Y（0..=100）。
+pub(crate) fn y_from_lstar(lstar: f64) -> f64 {
+    100.0 * lab_invf((lstar + 16.0) / 116.0)
+}
+
+/// 相对亮度 Y（0..=100）→ `L*`。
+pub(crate) fn lstar_from_y(y: f64) -> f64 {
+    lab_f(y / 100.0) * 116.0 - 16.0
+}
+
+/// 色值 → `L*`（即 M3 的 **tone**）。
+pub(crate) fn lstar_from_color(color: Color) -> f64 {
+    lstar_from_y(xyz_from_color(color)[1])
+}
+
+/// 色值 → CIELAB（`[L*, a*, b*]`）。
+///
+/// `L*` 与 [`lstar_from_color`] 逐值相同（同一个 `lab_f`）；`a*`/`b*` 走 D65 白点归一。
+/// 取色量化（`crate::palette::quantize`）用它在感知空间里算簇间距离——sRGB 欧氏距离会把
+/// 暗部差异放大、亮部差异压扁，分出来的簇不符合「看起来是一族颜色」。
+pub(crate) fn lab_from_color(color: Color) -> [f64; 3] {
+    let xyz = xyz_from_color(color);
+    let f = |component: f64, white: f64| lab_f(component / white);
+    let fx = f(xyz[0], WHITE_POINT_D65[0]);
+    let fy = f(xyz[1], WHITE_POINT_D65[1]);
+    let fz = f(xyz[2], WHITE_POINT_D65[2]);
+    [116.0 * fy - 16.0, 500.0 * (fx - fy), 200.0 * (fy - fz)]
+}
+
+/// `L*` → 中性灰色值（`L*` 与彩度无关，纯灰）。
+pub(crate) fn color_from_lstar(lstar: f64) -> Color {
+    let component = delinearized(y_from_lstar(lstar));
+    Color::rgb(component, component, component)
+}
+
+/// Java `Math.signum` 的口径：负数 −1、零 0、正数 1（**Rust 的 `f64::signum(0.0)` 是 1**，
+/// 直接换会改变中性色的求解结果）。
+pub(crate) fn signum(value: f64) -> f64 {
+    if value < 0.0 {
+        -1.0
+    } else if value == 0.0 {
+        0.0
+    } else {
+        1.0
+    }
+}
+
+/// 角度归一到 `0.0..360.0`。
+pub(crate) fn sanitize_degrees(degrees: f64) -> f64 {
+    let wrapped = degrees % 360.0;
+    if wrapped < 0.0 {
+        wrapped + 360.0
+    } else {
+        wrapped
+    }
+}
+
+/// 弧度归一到 `0.0..2π`（官方 `sanitizeRadians`，多加了 8π 保证非负）。
+pub(crate) fn sanitize_radians(angle: f64) -> f64 {
+    (angle + std::f64::consts::PI * 8.0) % (std::f64::consts::PI * 2.0)
+}
+
+/// 线性插值（官方 `lerp`）。
+pub(crate) fn lerp(start: f64, stop: f64, amount: f64) -> f64 {
+    (1.0 - amount) * start + amount * stop
+}
+
+/// 夹取到 `min..=max`。
+pub(crate) fn clamp(min: f64, max: f64, input: f64) -> f64 {
+    input.clamp(min, max)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn lstar_and_luminance_are_inverse() {
+        for lstar in [0.0_f64, 8.0, 20.0, 50.0, 87.0, 98.0, 100.0] {
+            let back = lstar_from_y(y_from_lstar(lstar));
+            assert!((back - lstar).abs() < 1.0e-9, "L* {lstar} 往返成 {back}");
+        }
+    }
+
+    #[test]
+    fn white_and_black_anchor_the_scale() {
+        assert_eq!(delinearized(100.0), 255);
+        assert_eq!(delinearized(0.0), 0);
+        assert_eq!(color_from_lstar(100.0), Color::WHITE);
+        assert_eq!(color_from_lstar(0.0), Color::BLACK);
+        assert!((lstar_from_color(Color::WHITE) - 100.0).abs() < 1.0e-6);
+        assert!(lstar_from_color(Color::BLACK).abs() < 1.0e-6);
+    }
+
+    #[test]
+    fn white_point_matches_d65() {
+        // 用官方那组舍入矩阵，纯白必须落在 D65 白点上（容差 1e-3 对应矩阵末位舍入）。
+        let xyz = xyz_from_color(Color::WHITE);
+        for (got, want) in xyz.iter().zip(WHITE_POINT_D65) {
+            assert!(
+                (got - want).abs() < 1.0e-3,
+                "{xyz:?} vs D65 {WHITE_POINT_D65:?}"
+            );
+        }
+        assert!(xyz_from_color(Color::BLACK).iter().all(|v| *v == 0.0));
+    }
+
+    #[test]
+    fn signum_matches_java_semantics() {
+        assert_eq!(signum(-1.5), -1.0);
+        assert_eq!(signum(0.0), 0.0);
+        assert_eq!(signum(-0.0), 0.0);
+        assert_eq!(signum(2.5), 1.0);
+    }
+
+    #[test]
+    fn degrees_sanitize_wraps_negatives() {
+        assert!((sanitize_degrees(-30.0) - 330.0).abs() < 1.0e-9);
+        assert!(sanitize_degrees(360.0).abs() < 1.0e-9);
+    }
+}
diff --git a/crates/design/src/color/state.rs b/crates/design/src/color/state.rs
new file mode 100644
index 0000000..9fbb3e5
--- /dev/null
+++ b/crates/design/src/color/state.rs
@@ -0,0 +1,164 @@
+//! M3 状态层（state layer）与禁用态透明度。
+//!
+//! M3 的 hover/pressed 不是「另一种灰」，而是**内容色自身 + 固定 alpha** 叠在容器上——
+//! 所以同一套令牌在任何底色上都成立，不必为每种底色各配一套（这条从 Fluent 时代沿用，
+//! 见 `DevDocs/SubAgentsTalk/ui-integration-contract.md` §2 的三态叠加层思路）。
+
+use super::Color;
+
+/// 状态层的四种状态与对应 alpha（M3 规范值）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum StateLayer {
+    /// 悬停：内容色 8%。
+    Hover,
+    /// 键盘焦点：内容色 10%。
+    Focus,
+    /// 按下：内容色 10%。
+    Pressed,
+    /// 拖拽中：内容色 16%。
+    Dragged,
+}
+
+impl StateLayer {
+    /// 叠加透明度（0..1）。
+    pub const fn alpha(self) -> f32 {
+        match self {
+            StateLayer::Hover => 0.08,
+            StateLayer::Focus | StateLayer::Pressed => 0.10,
+            StateLayer::Dragged => 0.16,
+        }
+    }
+
+    /// 把状态层叠到容器色上，得到**最终不透明色**。
+    ///
+    /// `content` 一般是容器上的前景角色（例如 FilledButton 用 `on-primary`，
+    /// 中性表面上的按钮用 `on-surface`）。
+    pub fn over(self, content: Color, container: Color) -> Color {
+        content.with_alpha(self.alpha()).over(container)
+    }
+}
+
+/// 禁用态的透明度（M3）：**按钮家族**容器 10%、内容 38%。
+///
+/// 别用「灰化」近似——深色模式下灰化会降低对比度，alpha 叠加两种模式都成立。
+///
+/// ## 取值依据（每个 token 的消费者都用 `javap -c ButtonDefaults` 数过）
+///
+/// - **按钮容器 10%**：`FilledButtonTokens` / `ElevatedButtonTokens` / `OutlinedButtonTokens` 的
+///   `DisabledContainerOpacity = 0.1f`，且 `ButtonDefaults.<clinit>` 里**真的调了**
+///   `getDisabledContainerOpacity()`（各 1 次）——活令牌。
+///   `TextButtonTokens` 同值但容器透明（`ButtonDefaults` 只读它的 `DisabledLabel*`）；
+///   `BaselineButtonTokens` 同值，它是**基准表**、运行时零消费者，只作参照。
+/// - ⚠️ `TonalButtonTokens` 也写 0.1f，但它在**整个 AAR 里零消费者**（`ButtonDefaults` 只引用
+///   `FilledTonalButtonTokens`；`grep` 命中的 `…TonalButtonTokens` 是后者的子串假象）。
+///   **别拿它当依据**——这正是本 mission 反复警告的死令牌坑（同 `ButtonSmallTokens.IconSize = 20`）。
+/// - **面状控件（chip 容器/描边、slider 轨道、switch 轨道）12%** 是另一类令牌，口径在
+///   `unlucky_app_iced::components::interaction::disabled_colors`。
+///
+/// ## ⚠️ 已知偏离：filled-tonal 的禁用容器**官方是 0.12f，我们走 0.10**
+///
+/// A 级事实（`javap -p -constants androidx.compose.material3.tokens.FilledTonalButtonTokens`）：
+/// `public static final float DisabledContainerOpacity = 0.12f;`
+/// ——它是**编译期常量**，被内联进 `ButtonDefaults.getDefaultFilledTonalButtonColors` 的字节码
+/// （所以那里看到的是 `ldc_w 0.12f`，`getDisabledContainerOpacity()` 根本不会被调用；
+/// 在 `<clinit>` 里也看不到它——那是「没在 clinit 里出现」，**不是「字段不存在」**）。
+///
+/// 我们的实现在 tonal 与 filled 之间**没有区分**，两者共用本常量 ⇒ **tonal 实际画的是 10%**。
+/// 这是**已登记的偏离，不是对齐**：要修得让 `disabled_button_colors` 知道「哪个变体」，
+/// 并同步 `gallery/probe` 的逐行断言；本轮（M86）只做令牌一致性收口，不扩到变体分派。
+///
+/// 曾经的缺陷不是「12 是错的」，而是**同一个常量同时服务这两类**：按钮那半边一直错、另半边一直对。
+pub const DISABLED_CONTAINER_ALPHA: f32 = 0.10;
+/// 禁用态内容（文字/图标）透明度。
+pub const DISABLED_CONTENT_ALPHA: f32 = 0.38;
+
+/// 禁用态的透明度（M3）：**面状控件族**容器与描边 12%。
+///
+/// 这一族是「一整面涂上去的容器或用它画出来的描边/轨道」，官方 token 各写一份但值统一是 `0.12f`：
+/// `AssistChipTokens.FlatDisabledOutlineOpacity`、`FilterChipTokens.FlatDisabledSelectedContainerOpacity`
+/// / `FlatDisabledUnselectedOutlineOpacity`、`SliderTokens.DisabledInactiveTrackOpacity`、
+/// `SwitchTokens.DisabledTrackOpacity`（AAR 字节码 `<clinit>`）。
+///
+/// **不适用于按钮容器**：按钮是 [`DISABLED_CONTAINER_ALPHA`]（10%，`*ButtonTokens.DisabledContainerOpacity`）。
+/// 更不适用于 TextField 的 Filled 容器——那是 `FilledTextFieldTokens.FieldDisabledContainerOpacity = 0.04f`，
+/// 我们仍在用 12%（既有 D10 偏离，未在本轮收口）。
+pub const DISABLED_SURFACE_ALPHA: f32 = 0.12;
+
+/// 禁用态容器色：`on_surface` 10%（按钮家族的 `DisabledContainerOpacity`）叠在 `surface` 上。
+pub fn disabled_container(scheme: &super::Scheme) -> Color {
+    scheme
+        .get(super::Role::OnSurface)
+        .with_alpha(DISABLED_CONTAINER_ALPHA)
+        .over(scheme.get(super::Role::Surface))
+}
+
+/// 禁用态内容色：`on_surface` 38% 叠在容器上。
+pub fn disabled_content(scheme: &super::Scheme, container: Color) -> Color {
+    scheme
+        .get(super::Role::OnSurface)
+        .with_alpha(DISABLED_CONTENT_ALPHA)
+        .over(container)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::color::{Role, Scheme, SchemeFlavor};
+
+    #[test]
+    fn hover_is_lighter_than_pressed_on_dark_container() {
+        let scheme = Scheme::baseline(SchemeFlavor::Dark);
+        let container = scheme.get(Role::SurfaceContainer);
+        let content = scheme.get(Role::OnSurface);
+        let hover = StateLayer::Hover.over(content, container);
+        let pressed = StateLayer::Pressed.over(content, container);
+        assert_eq!(hover.a, 255);
+        assert!(pressed.relative_luminance() > hover.relative_luminance());
+    }
+
+    #[test]
+    fn state_layer_alpha_matches_m3() {
+        assert!((StateLayer::Hover.alpha() - 0.08).abs() < f32::EPSILON);
+        assert!((StateLayer::Dragged.alpha() - 0.16).abs() < f32::EPSILON);
+    }
+
+    #[test]
+    fn disabled_content_stays_visible() {
+        let scheme = Scheme::baseline(SchemeFlavor::Light);
+        let container = disabled_container(&scheme);
+        let content = disabled_content(&scheme, container);
+        // 禁用态不追求 AA（规范就是这么定的），但必须仍可辨（> 1.5:1）。
+        let ratio = content.contrast_ratio(container);
+        assert!(ratio > 1.5, "禁用态对比度过低：{ratio}");
+        assert!(ratio < 4.5, "禁用态不该和正文一样醒目：{ratio}");
+    }
+
+    /// 两族 α 的**令牌层钉值**（M86）：期望值硬编码，不从被测常量取——否则改坏常量也照样绿。
+    ///
+    /// 出处（AAR `material3-android-1.4.0` 的 `<clinit>`）：
+    /// `*ButtonTokens.DisabledContainerOpacity = 0.1f`（按钮族）与
+    /// `AssistChipTokens.FlatDisabledOutlineOpacity` / `SliderTokens.DisabledInactiveTrackOpacity` /
+    /// `SwitchTokens.DisabledTrackOpacity = 0.12f`（面状控件族）。
+    #[test]
+    fn disabled_alpha_classes_are_pinned_at_the_token_layer() {
+        const EXPECTED_BUTTON: f32 = 0.10;
+        const EXPECTED_SURFACE: f32 = 0.12;
+        const EXPECTED_CONTENT: f32 = 0.38;
+        let button = DISABLED_CONTAINER_ALPHA;
+        let surface = DISABLED_SURFACE_ALPHA;
+        let content = DISABLED_CONTENT_ALPHA;
+        assert_eq!(
+            button, EXPECTED_BUTTON,
+            "按钮族禁用容器 α 必须是官方 0.1f（*ButtonTokens.DisabledContainerOpacity）"
+        );
+        assert_eq!(
+            surface, EXPECTED_SURFACE,
+            "面状控件族 α 必须是官方 0.12f（chip 描边 / slider 轨道 / switch 轨道）"
+        );
+        assert_eq!(content, EXPECTED_CONTENT, "禁用内容 0.38f");
+        assert!(
+            surface > button,
+            "两族必须可区分（{surface} > {button}）；合成一个数就是 M86 要防的回归"
+        );
+    }
+}
diff --git a/crates/design/src/color/tonal.rs b/crates/design/src/color/tonal.rs
new file mode 100644
index 0000000..f30e860
--- /dev/null
+++ b/crates/design/src/color/tonal.rs
@@ -0,0 +1,150 @@
+//! tone 调色板：**固定 HCT 色相 + 固定 HCT 彩度**，沿 tone 轴取色。
+//!
+//! 这就是 M3 的 `TonalPalette`：一条调色板只回答一个问题——「我的第 N 号 tone 是什么色」。
+//! 因为 HCT 的 tone 轴是 `L*`，同一条调色板上「tone 差 40 ⇒ 对比度 ≥ 3:1」天然成立；
+//! 又因为 hue 固定，整条调色板在感知上是同一个色相（这正是 OKLCh 近似做不到的那一点）。
+//!
+//! 语义对齐 `java/palettes/TonalPalette.java`（Apache-2.0，见 `NOTICE`）。
+
+use super::{Color, Hct};
+
+/// 一条 tone 调色板（HCT 色相 + 彩度上限）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct TonalPalette {
+    hue_deg: f64,
+    chroma: f64,
+}
+
+impl TonalPalette {
+    /// 直接给 HCT 色相（度）与 HCT 彩度建调色板（彩度 0 = 中性灰）。
+    pub fn new(hue_deg: f64, chroma: f64) -> Self {
+        Self {
+            hue_deg: hue_deg.rem_euclid(360.0),
+            chroma: chroma.max(0.0),
+        }
+    }
+
+    /// 从种子色取 HCT 色相与彩度（等价官方 `TonalPalette.fromInt`）。
+    pub fn from_color(seed: Color) -> Self {
+        let hct = Hct::from_color(seed);
+        Self::new(hct.hue, hct.chroma)
+    }
+
+    /// 固定色相，换彩度（M3 用它把种子的彩度压到 secondary/neutral 档）。
+    pub fn with_chroma(self, chroma: f64) -> Self {
+        Self::new(self.hue_deg, chroma)
+    }
+
+    /// 旋转色相（derived hue，例如 tertiary = 种子色相 +60°）。
+    pub fn rotated(self, deg: f64) -> Self {
+        Self::new(self.hue_deg + deg, self.chroma)
+    }
+
+    /// 该调色板的 HCT 色相（度）。
+    pub fn hue_deg(self) -> f64 {
+        self.hue_deg
+    }
+
+    /// 该调色板的 HCT 彩度。
+    pub fn chroma(self) -> f64 {
+        self.chroma
+    }
+
+    /// 取某个 tone 的颜色（tone 超出 0..=100 时自然夹到纯黑/纯白）。
+    ///
+    /// 彩度装不下时按官方的 gamut 映射**只压彩度**，色相与 tone 不变。
+    pub fn tone(self, tone: f64) -> Color {
+        self.hct(tone).to_color()
+    }
+
+    /// 取某个 tone 的 HCT 坐标（`TonalPalette.hct` / 官方 `getHct`）。
+    ///
+    /// 黄相（105°..125°）的 tone 99 是官方的特例：那里 `L*` 与 sRGB 平面不平滑，
+    /// 直接横向取自 tone 98 与 tone 100 的中点，避免出一格色带。
+    pub fn hct(self, tone: f64) -> Hct {
+        if tone == 99.0 && Hct::is_yellow(self.hue_deg) {
+            let low = self.hct(98.0).to_color();
+            let high = self.hct(100.0).to_color();
+            return Hct::from_color(average(low, high));
+        }
+        Hct::from_components(self.hue_deg, self.chroma, tone)
+    }
+}
+
+/// 两色的通道中点（官方 `averageArgb`，四舍五入）。
+fn average(a: Color, b: Color) -> Color {
+    let mid = |x: u8, y: u8| {
+        let sum = u16::from(x) + u16::from(y);
+        u8::try_from(sum.div_ceil(2)).unwrap_or(u8::MAX)
+    };
+    Color::rgb(mid(a.r, b.r), mid(a.g, b.g), mid(a.b, b.b))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const SEED: Color = Color::rgb(0x67, 0x50, 0xA4);
+
+    #[test]
+    fn tone_is_hit_within_quantisation_error() {
+        let palette = TonalPalette::from_color(SEED).with_chroma(36.0);
+        for tone in [
+            4.0_f64, 6.0, 10.0, 12.0, 17.0, 20.0, 30.0, 40.0, 50.0, 80.0, 87.0, 90.0, 92.0, 94.0,
+            95.0, 96.0, 98.0,
+        ] {
+            let got = Hct::from_color(palette.tone(tone)).tone;
+            assert!(
+                (got - tone).abs() <= 1.0,
+                "tone {tone} 的 L* 是 {got}，偏差超过 1（8 bit 量化上限）"
+            );
+        }
+    }
+
+    #[test]
+    fn extremes_are_pure_black_and_white() {
+        let palette = TonalPalette::from_color(SEED);
+        assert_eq!(palette.tone(0.0), Color::rgb(0, 0, 0));
+        assert_eq!(palette.tone(100.0), Color::rgb(255, 255, 255));
+        assert_eq!(palette.tone(-5.0), Color::rgb(0, 0, 0));
+        assert_eq!(palette.tone(120.0), Color::rgb(255, 255, 255));
+    }
+
+    #[test]
+    fn hue_is_preserved_across_the_whole_ramp() {
+        let palette = TonalPalette::new(298.980_997, 36.0);
+        for tone in [10.0_f64, 30.0, 50.0, 70.0, 90.0] {
+            let hct = palette.hct(tone);
+            let delta = (hct.hue - palette.hue_deg()).abs();
+            let delta = delta.min(360.0 - delta);
+            assert!(delta < 1.0, "tone {tone} 色相偏移 {delta}°");
+        }
+    }
+
+    #[test]
+    fn chroma_zero_is_neutral_gray() {
+        let neutral = TonalPalette::new(120.0, 0.0);
+        for tone in [6.0_f64, 30.0, 50.0, 90.0, 98.0] {
+            let color = neutral.tone(tone);
+            assert!(color.r == color.g && color.g == color.b, "{color:?}");
+        }
+    }
+
+    #[test]
+    fn yellow_tone_99_uses_the_official_average() {
+        let palette = TonalPalette::new(110.0, 40.0);
+        let expected = average(palette.tone(98.0), palette.tone(100.0));
+        assert_eq!(palette.tone(99.0), expected);
+        // 非黄相不触发特例：tone 99 走正常求解。
+        let normal = TonalPalette::new(300.0, 40.0);
+        assert_eq!(normal.tone(99.0), normal.hct(99.0).to_color());
+    }
+
+    #[test]
+    fn requested_chroma_is_respected_when_the_gamut_allows() {
+        // tone 50 是最「宽」的色调面，彩度 36 一定装得下。
+        let palette = TonalPalette::new(298.980_997, 36.0);
+        let hct = palette.hct(50.0);
+        assert!((hct.chroma - 36.0).abs() < 0.5, "彩度 {}", hct.chroma);
+    }
+}
diff --git a/crates/design/src/color/viewing_conditions.rs b/crates/design/src/color/viewing_conditions.rs
new file mode 100644
index 0000000..09f993b
--- /dev/null
+++ b/crates/design/src/color/viewing_conditions.rs
@@ -0,0 +1,165 @@
+//! CAM16 的**观察条件**（viewing conditions）。
+//!
+//! HCT 的色相/彩度来自 CAM16，而 CAM16 是「在外界光环境下看起来如何」的模型——同一个 hex，
+//! 换观察条件就是不同的 hue/chroma。M3 固定用 sRGB 默认条件：D65 白点、200 lux（适应亮度）、
+//! 背景 `L* = 50`、surround = 2.0、**不做**光源折扣（自发光屏幕）。
+//!
+//! 照搬 `java/hct/ViewingConditions.java`（Apache-2.0，见 `NOTICE`）。
+
+use super::space;
+
+/// CAM16 观察条件里与颜色无关的那堆中间量（只为避免重复计算）。
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct ViewingConditions {
+    /// 白点响应（achromatic response to the white point）。
+    pub(crate) aw: f64,
+    /// 背景亮度因子。
+    pub(crate) n: f64,
+    /// 亮度指数。
+    pub(crate) nbb: f64,
+    /// 彩度指数。
+    pub(crate) ncb: f64,
+    /// 环绕度决定的对比度系数。
+    pub(crate) c: f64,
+    /// 环绕度。
+    pub(crate) nc: f64,
+    /// 三通道的色适应折扣系数。
+    pub(crate) rgb_d: [f64; 3],
+    /// 亮度适应因子。
+    pub(crate) fl: f64,
+    /// 基函数。
+    pub(crate) z: f64,
+}
+
+// 与 XYZ 有关的常量矩阵在 CAM16 里也要用，从 space 引一次保持单一来源。
+use super::cam16::XYZ_TO_CAM16_RGB;
+
+impl ViewingConditions {
+    /// 按官方参数构造（`white_point` 是 XYZ，`adapting_luminance` 由 lux 换算）。
+    pub(crate) fn make(
+        white_point: [f64; 3],
+        adapting_luminance: f64,
+        background_lstar: f64,
+        surround: f64,
+        discounting_illuminant: bool,
+    ) -> Self {
+        // 纯黑背景是非物理的，会让「任何颜色都看不见」这类无穷大出现，官方取下限 0.1。
+        let background_lstar = background_lstar.max(0.1);
+        let [r_w, g_w, b_w] = space::matrix_multiply(white_point, XYZ_TO_CAM16_RGB);
+        let f = 0.8 + surround / 10.0;
+        let c = if f >= 0.9 {
+            space::lerp(0.59, 0.69, (f - 0.9) * 10.0)
+        } else {
+            space::lerp(0.525, 0.59, (f - 0.8) * 10.0)
+        };
+        let d = if discounting_illuminant {
+            1.0
+        } else {
+            let raw = f * (1.0 - (1.0 / 3.6) * ((-adapting_luminance - 42.0) / 92.0).exp());
+            space::clamp(0.0, 1.0, raw)
+        };
+        let nc = f;
+        let rgb_d = [
+            d * (100.0 / r_w) + 1.0 - d,
+            d * (100.0 / g_w) + 1.0 - d,
+            d * (100.0 / b_w) + 1.0 - d,
+        ];
+        let k = 1.0 / (5.0 * adapting_luminance + 1.0);
+        let k4 = k * k * k * k;
+        let k4_f = 1.0 - k4;
+        let fl = k4 * adapting_luminance + 0.1 * k4_f * k4_f * (5.0 * adapting_luminance).cbrt();
+        let n = space::y_from_lstar(background_lstar) / white_point[1];
+        let z = 1.48 + n.sqrt();
+        let nbb = 0.725 / n.powf(0.2);
+        let ncb = nbb;
+        let rgb_a_factors = [
+            (fl * rgb_d[0] * r_w / 100.0).powf(0.42),
+            (fl * rgb_d[1] * g_w / 100.0).powf(0.42),
+            (fl * rgb_d[2] * b_w / 100.0).powf(0.42),
+        ];
+        let rgb_a = [
+            400.0 * rgb_a_factors[0] / (rgb_a_factors[0] + 27.13),
+            400.0 * rgb_a_factors[1] / (rgb_a_factors[1] + 27.13),
+            400.0 * rgb_a_factors[2] / (rgb_a_factors[2] + 27.13),
+        ];
+        let aw = (2.0 * rgb_a[0] + rgb_a[1] + 0.05 * rgb_a[2]) * nbb;
+        Self {
+            aw,
+            n,
+            nbb,
+            ncb,
+            c,
+            nc,
+            rgb_d,
+            fl,
+            z,
+        }
+    }
+
+    /// 指定背景 `L*` 的 sRGB 默认条件。
+    pub(crate) fn default_with_background_lstar(background_lstar: f64) -> Self {
+        Self::make(
+            space::WHITE_POINT_D65,
+            200.0 / std::f64::consts::PI * space::y_from_lstar(50.0) / 100.0,
+            background_lstar,
+            2.0,
+            false,
+        )
+    }
+}
+
+/// 全仓共用的默认观察条件（sRGB 屏，背景 `L* = 50`）。
+pub(crate) fn default_conditions() -> &'static ViewingConditions {
+    static DEFAULT: std::sync::OnceLock<ViewingConditions> = std::sync::OnceLock::new();
+    DEFAULT.get_or_init(|| ViewingConditions::default_with_background_lstar(50.0))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn default_conditions_match_the_official_constants() {
+        // 官方 material-color-utilities 的 ViewingConditions.DEFAULT 解出来的值（Java 实测，
+        // `hct.Count` 打印）。
+        let vc = default_conditions();
+        assert!(
+            (vc.n - 0.184_186_518_512_444_16).abs() < 1.0e-12,
+            "n = {}",
+            vc.n
+        );
+        assert!(
+            (vc.aw - 29.980_997_194_447_333).abs() < 1.0e-12,
+            "aw = {}",
+            vc.aw
+        );
+        assert!(
+            (vc.nbb - 1.016_919_180_445_875_5).abs() < 1.0e-12,
+            "nbb = {}",
+            vc.nbb
+        );
+        assert!((vc.c - 0.69).abs() < 1.0e-12);
+        assert!((vc.nc - 1.0).abs() < 1.0e-12);
+        assert!(
+            (vc.fl - 0.388_481_453_780_035_3).abs() < 1.0e-12,
+            "fl = {}",
+            vc.fl
+        );
+        assert!(
+            (vc.z - 1.909_169_568_483_652).abs() < 1.0e-12,
+            "z = {}",
+            vc.z
+        );
+        assert!((vc.rgb_d[0] - 1.021_177_702_757_52).abs() < 1.0e-12);
+        assert!((vc.rgb_d[1] - 0.986_307_729_428_012_4).abs() < 1.0e-12);
+        assert!((vc.rgb_d[2] - 0.933_960_508_280_229_9).abs() < 1.0e-12);
+    }
+
+    #[test]
+    fn white_point_has_zero_chroma_in_cam16() {
+        // CAM16 的白点在默认条件下应当接近中性（这才是「色适应」的意义）。
+        use super::super::cam16::Cam16;
+        let white = Cam16::from_color(super::super::Color::WHITE);
+        assert!(white.chroma < 5.0, "白点彩度 {}", white.chroma);
+    }
+}
diff --git a/crates/design/src/component_map/metrics.rs b/crates/design/src/component_map/metrics.rs
new file mode 100644
index 0000000..add93f8
--- /dev/null
+++ b/crates/design/src/component_map/metrics.rs
@@ -0,0 +1,179 @@
+//! 组件级微度量（`ComponentMetrics`）：**单个控件内部的几何**，不是窗口骨架。
+//!
+//! 为什么要有这个结构（M69 / G10）：Checkbox 的 20×20、圆角 2、描边 2、状态层 Ø40 这类值，
+//! `ShapeScale`（刻度）装不了、`LayoutMetrics`（骨架）也不该装——M66 对账时它们只能写在组件
+//! 实现里，而 D30 禁止组件层自定义数值。这里给它们一个**唯一落点**。
+//!
+//! ## 与 `LayoutMetrics` 的分工（两把尺子，量不同的东西）
+//!
+//! | | [`crate::spacing::LayoutMetrics`] | `ComponentMetrics`（本模块） |
+//! |---|---|---|
+//! | 管什么 | 窗口骨架与布局节奏：标题栏/页头/行高、dock 宽度、命中区 | 单个控件方框内的几何：外框、微圆角、描边/环线宽、状态层、内点、图标偏移 |
+//! | 随什么变 | 窗口尺寸、列宽、用户折叠导航 | 只随组件自身规格变 |
+//! | 例子 | `nav_drawer_width = 240`、`search_bar_height = 56` | checkbox 20×20、描边 2、状态层 Ø40 |
+//! | 判据 | 决定「一块面板/一行占多宽多高」 | 决定「画进这个方框里的那几个像素」 |
+//!
+//! 冲突时的规则是**同一个量只许有一份**：搜索条高 56 属骨架级，所以
+//! [`ComponentMetrics::SEARCH_BAR`] 的 `height` 留 `0.0` 并在文档里指回 LM；drawer 宽同理。
+//! 测试 `component_metrics_never_duplicate_layout_metrics` 把这条钉死。
+//!
+//! 数值来源：`androidx.compose.material3:material3-android:1.4.0` 源码（A 级，M66 逐行核对，
+//! 见 `research/15` §18~§23）。逐字段的出处写在下面各组件的关联常量上；**团队口径**（官方没有
+//! token 的）单独注明。
+
+use super::Component;
+use crate::icons::IconSize;
+use crate::shape::ComponentRadius;
+use crate::spacing::Space;
+
+/// 单个控件的内部几何。
+///
+/// `0.0` 表示**该控件没有这一项**（不是「默认值 0」）——拿 `0.0` 反推数值一定错。
+/// 骨架级尺寸（条高、面板宽）不在这里，去 [`crate::spacing::LayoutMetrics`] 拿。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct ComponentMetrics {
+    /// 可见外框宽（dp；`0.0` = 由内容或骨架决定）。
+    pub width: f32,
+    /// 可见外框高（dp；`0.0` = 由内容或骨架决定）。
+    pub height: f32,
+    /// 微控件圆角（D32 第二层）。`None` = 该控件的圆角走 `ShapeScale`（见 `ComponentSpec::shape`）。
+    pub radius: Option<ComponentRadius>,
+    /// 描边 / 环线宽度（dp）。**禁用态也不许变细**——官方 disabled 只改透明度。
+    pub stroke: f32,
+    /// 状态层（hover / focus / pressed）圆的直径（dp；`0.0` = 不画状态层）。
+    pub state_layer: f32,
+    /// 内点直径（dp）：radio 选中时的实心点，其余控件 `0.0`。
+    pub inner_dot: f32,
+    /// 控件相对容器的外距（dp）：drawer 项 = 12，决定选中指示器左右各内缩 12。
+    pub inset: f32,
+    /// 内容起始侧内边距（dp）。**图标不算在内**：图标可视边 = `pad_start + icon_offset`。
+    pub pad_start: f32,
+    /// 内容结束侧内边距（dp）。同起始侧，图标可视边 = `pad_end + icon_offset`。
+    pub pad_end: f32,
+    /// 图标边长（dp；`0.0` = 无图标）。
+    pub icon: f32,
+    /// 图标相对内边距的**额外**偏移（dp）。图标可视边 = 内边距 + 本值（search bar：12 + 4 = 16），
+    /// **不要**把内边距本身当图标边用，也不要再手抄那个 12 / 16。
+    pub icon_offset: f32,
+    /// 图标与文字（或相邻元素）的间距（dp）。
+    pub gap: f32,
+}
+
+impl ComponentMetrics {
+    /// Checkbox（`research/15` §18 / §23）。
+    ///
+    /// A 级出处：`Checkbox.kt:737 CheckboxSize = 20.dp`、`:738 RadiusSize = 2.dp`（圆角走 D32 的
+    /// [`ComponentRadius::Micro`]）、`CheckboxTokens.UnselectedOutlineWidth = 2`、
+    /// `StateLayerSize = 40` + `StateLayerShape = CornerFull`。
+    /// 注意 `CheckboxTokens.ContainerWidth/Height = 18` 是**死值**（全仓 0 引用），Compose 实际画
+    /// 20（§26.2 矛盾 ①）——判据取 20。
+    /// 勾选控件 ↔ 标签间距 8 是**团队口径**：官方没有「框 + 标签」组合的 token（§18.9，估）。
+    pub const CHECKBOX: Self = Self {
+        width: 20.0,
+        height: 20.0,
+        radius: Some(ComponentRadius::Micro),
+        stroke: 2.0,
+        state_layer: 40.0,
+        inner_dot: 0.0,
+        inset: 0.0,
+        pad_start: 0.0,
+        pad_end: 0.0,
+        icon: 0.0,
+        icon_offset: 0.0,
+        gap: Space::X2.dp(),
+    };
+
+    /// Radio（`research/15` §19 / §23）。
+    ///
+    /// A 级出处：`RadioButtonTokens.IconSize = 20`、`RadioStrokeWidth = 2.dp`；内点名义
+    /// `RadioButtonDotSize = 12`，但绘制半径 = 12/2 − stroke/2 = 5 → **实际内点直径 10**
+    /// （§19.2：抄 12 会明显偏大）。圆角走 `ShapeScale::Full`（真圆），不是微半径。
+    /// 标签间距 8 同 Checkbox（团队口径）。
+    pub const RADIO: Self = Self {
+        width: 20.0,
+        height: 20.0,
+        radius: None,
+        stroke: 2.0,
+        state_layer: 40.0,
+        inner_dot: 10.0,
+        inset: 0.0,
+        pad_start: 0.0,
+        pad_end: 0.0,
+        icon: 0.0,
+        icon_offset: 0.0,
+        gap: Space::X2.dp(),
+    };
+
+    /// Search bar（`research/15` §20A / §23）。
+    ///
+    /// 高度与宽度**不在这里**：条高 56 是骨架级（`LayoutMetrics::search_bar_height`），
+    /// 最小宽 360 同样属骨架级（尚未进 LM，M69 报告里登记为待办）。这里只装画进 bar 里的几何：
+    /// 图标 24（`IconSize::Toolbar`）、**图标可视边 = `pad_start + icon_offset`** = 12 + 4 = **16**
+    /// （右侧同式为 16，§20.4）、圆角走 `ShapeScale::Full`（56 → 28 = 官方 `SearchBarCornerRadius`），
+    /// 所以 `radius` 是 `None`。
+    ///
+    /// 为什么要拆成 12 + 4 而不是直接写 16：官方 = 文本框内容内边距 **12**（`TextFieldImpl` 默认）
+    /// 加上 `SearchBarIconOffsetX = 4`。拆开才能让「文本从 12 起、图标从 16 起」都被消费方拿到；
+    /// 只写 16 的话文本内边距没有落点，消费方只能自己写 `12.0`——正是 G10 要消灭的字面量。
+    /// 图标位置一律按 `pad + icon_offset` 求和，不要单独把 `pad` 当图标边用。
+    pub const SEARCH_BAR: Self = Self {
+        width: 0.0,
+        height: 0.0,
+        radius: None,
+        stroke: 0.0,
+        state_layer: 0.0,
+        inner_dot: 0.0,
+        inset: 0.0,
+        pad_start: Space::X3.dp(),
+        pad_end: Space::X3.dp(),
+        icon: IconSize::Toolbar.px(),
+        icon_offset: 4.0,
+        // 图标 ↔ 文本 8 是**团队口径 [估]**：`research/15` §20.4 只给了图标尺寸/位置与 48 命中框，
+        // 没有「图标 ↔ 文字」的 token（Compose 由 `TextFieldImpl` 内部排版决定）。
+        gap: Space::X2.dp(),
+    };
+
+    /// Navigation drawer（`research/15` §21 / §23）。
+    ///
+    /// 宽度与项高**不在这里**：drawer 240 / rail 88 在 `LayoutMetrics`，项高 44 =
+    /// `LayoutMetrics::nav_item_height`。这里装项内几何（§21.6，A 级：
+    /// `NavigationDrawerItemDefaults.ItemPadding = 12`、项内 start 16 / end 24、
+    /// `IconSize = 24`、图标 ↔ label 12）。
+    /// 容器形状 `CornerLargeEnd`（只有靠内容那一侧两角 16）由 `ComponentSpec::shape` 的
+    /// `Large` + 组件实现按侧位决定哪两个角，度量层不表达「部分角」。
+    pub const NAVIGATION_DRAWER: Self = Self {
+        width: 0.0,
+        height: 0.0,
+        radius: None,
+        stroke: 0.0,
+        state_layer: 0.0,
+        inner_dot: 0.0,
+        inset: 12.0,
+        pad_start: Space::X4.dp(),
+        pad_end: Space::X6.dp(),
+        icon: IconSize::Toolbar.px(),
+        icon_offset: 0.0,
+        gap: Space::X3.dp(),
+    };
+
+    /// drawer 选中指示器宽度：容器宽 − 2 × [`ComponentMetrics::inset`]。
+    ///
+    /// 240 − 24 = **216**；官方 360 − 24 = 336 是同一个公式（§21.5）——写死 336 就是忘了推导。
+    pub fn indicator_width(&self, container_width: f32) -> f32 {
+        (container_width - self.inset * 2.0).max(0.0)
+    }
+}
+
+/// 组件 → 组件级微度量。`None` = 该组件没有控件内部几何（只有骨架值，去 LM 拿）。
+///
+/// Divider 是 `None` 的显式例子：它的唯一几何量是厚度，而厚度是**一像素线**
+/// （`LayoutMetrics::divider_thickness` = `stroke::HAIRLINE`），不是「控件内部」的东西。
+pub(super) const fn metrics_of(component: Component) -> Option<ComponentMetrics> {
+    match component {
+        Component::Checkbox => Some(ComponentMetrics::CHECKBOX),
+        Component::Radio => Some(ComponentMetrics::RADIO),
+        Component::Search => Some(ComponentMetrics::SEARCH_BAR),
+        Component::NavigationDrawer => Some(ComponentMetrics::NAVIGATION_DRAWER),
+        _ => None,
+    }
+}
diff --git a/crates/design/src/component_map/mod.rs b/crates/design/src/component_map/mod.rs
new file mode 100644
index 0000000..8a7629c
--- /dev/null
+++ b/crates/design/src/component_map/mod.rs
@@ -0,0 +1,212 @@
+//! 组件 → 档位映射表：哪个组件用哪档形状 / 高程 / 字体 / 动效。
+//!
+//! 目的不是「规定 M3 官方长什么样」（官方只给组件规格，不给启动器里的档位表），而是
+//! **给 iced 页面线一个不需要再谈判的默认值**：同一个组件在五个页面里长得一样，
+//! 才有用户要的「UI 整体性」。
+//!
+//! 口径：
+//! - 形状档位见 [`crate::shape::ShapeScale`]，高程见 [`crate::elevation::Elevation`]；
+//! - `text` 是主要文字角色，`support` 是辅助文字（没有就 `None`）；
+//! - `motion` + `duration` 是状态过渡（hover/press/展开），不是页面切换；
+//! - `morph` 是按下/选中时的形状形变（Expressive 特征），不需要就 `None`；
+//! - 圆角分两层（D32）：容器级查 [`crate::shape::ShapeScale`]，≤24dp 的微控件查
+//!   [`crate::shape::ComponentRadius`]（落在 [`ComponentSpec::micro_radius`]）。
+//!
+//! 档位（形状/高程/字级/动效）之外，**控件内部的微几何**（20×20、描边 2、状态层 Ø40 …）在
+//! [`ComponentMetrics`] 里，入口是 [`Component::metrics`]——两者分工见该项的文档
+//! （`component_map::metrics` 模块）。
+//!
+//! **改这里的值 = 改全站观感**，必须同步 `DevDocs/SubAgentsTalk/design-令牌约定.md`；
+//! 页面线不许在页面里覆盖这些档位。
+
+mod metrics;
+mod table;
+
+pub use metrics::ComponentMetrics;
+
+use crate::elevation::Elevation;
+use crate::motion::{DurationToken, Easing};
+use crate::shape::{ComponentRadius, ShapeMorph, ShapeScale};
+use crate::typography::TypeRole;
+
+/// 组件的排版 + 形状 + 动效档位。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct ComponentSpec {
+    /// 该档位属于哪个组件（表自描述，便于测试与文档生成）。
+    pub component: Component,
+    /// 圆角档位（容器级，[`ShapeScale`] 的严格刻度）。
+    pub shape: ShapeScale,
+    /// 微控件圆角（D32 第二层）。
+    ///
+    /// `Some` 时**本字段才是半径真源**，此时 [`ComponentSpec::shape`] 必须是
+    /// [`ShapeScale::None`]（占位、不参与渲染）——因为 2dp 不在 `ShapeScale` 刻度里，
+    /// 硬塞进 `shape` 会破坏「圆角只取刻度值」。这层配对由测试钉死。
+    pub micro_radius: Option<ComponentRadius>,
+    /// 高程级别（决定 surface container 角色与是否画阴影）。
+    pub elevation: Elevation,
+    /// 主要文字角色。**无文字的组件（如 `Divider`）这里是占位值**，消费方不得据此排版。
+    pub text: TypeRole,
+    /// 辅助文字角色。
+    pub support: Option<TypeRole>,
+    /// 状态过渡缓动。
+    ///
+    /// 该字段不是 `Option`，所以**没有动效语义的组件（如 `Divider`）这里是占位值**——
+    /// 读之前先确认组件本身有状态过渡，无过渡的组件不得据此排动效。
+    pub motion: Easing,
+    /// 状态过渡时长。
+    pub duration: DurationToken,
+    /// 按下/选中时的形状形变。
+    pub morph: Option<ShapeMorph>,
+}
+
+/// 需要固定档位的组件清单（M53 页面骨架 + M69 组件线补的 5 个）。
+///
+/// **冻结为只可末尾追加**：判别值当索引用（`table::SPECS[self as usize]`），改名/换位等于
+/// 让整张表错行。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Component {
+    /// 顶部标题栏（第一层 chrome）。
+    TopAppBar,
+    /// 导航项（侧栏一行）。
+    NavigationItem,
+    /// 主操作按钮（实心强调色，每屏最多一个）。
+    PrimaryButton,
+    /// 次操作按钮（tonal）。
+    SecondaryButton,
+    /// 文本按钮（低权重）。
+    TextButton,
+    /// 图标按钮。
+    IconButton,
+    /// 描边卡片。
+    OutlinedCard,
+    /// 填充卡片（层级高于描边卡）。
+    FilledCard,
+    /// 列表行。
+    ListItem,
+    /// 文本输入框。
+    TextField,
+    /// 分段按钮（磁贴/列表切换、小中大三档）。
+    SegmentedButton,
+    /// 贴片/徽标。
+    Chip,
+    /// 开关。
+    Switch,
+    /// 滑块。
+    Slider,
+    /// 进度条。
+    ProgressIndicator,
+    /// 对话框。
+    Dialog,
+    /// 下拉菜单。
+    Menu,
+    /// 底部提示条。
+    Snackbar,
+    /// 悬浮提示。
+    Tooltip,
+    /// 空态（图标 + 标题 + 说明 + 标准按钮）。
+    EmptyState,
+    /// 复选框（安装选项 / mod 启用 / 日志过滤 / Java 管理勾选）。
+    ///
+    /// 圆角 **2dp** 不在 `ShapeScale` 刻度里 → 走 [`ComponentSpec::micro_radius`]（D32 第二层）；
+    /// 20×20 / 描边 2 / 状态层 Ø40 见 [`ComponentMetrics::CHECKBOX`]。
+    Checkbox,
+    /// 单选框（Java 版本单选 / 安装模式选择）。
+    ///
+    /// 真圆（`ShapeScale::Full`）；20 / 环线 2 / 内点 10 / 状态层 Ø40 见 [`ComponentMetrics::RADIO`]。
+    Radio,
+    /// 搜索条（实例 / 版本 / mod 搜索，页级入口）。
+    ///
+    /// 高 56 是骨架级（`LayoutMetrics::search_bar_height`），圆角 `Full`（56 → 28）；
+    /// 图标 24 + 偏移 4 见 [`ComponentMetrics::SEARCH_BAR`]。高程取 **L0**（源码矛盾已登记）。
+    Search,
+    /// 导航抽屉（左侧常驻导航的展开形态，D33）。
+    ///
+    /// 形状 `CornerLargeEnd`（只有靠内容那侧两角 16），宽 240 = `LayoutMetrics::nav_drawer_width`；
+    /// 项内几何见 [`ComponentMetrics::NAVIGATION_DRAWER`]。
+    NavigationDrawer,
+    /// 分隔线（列表行分隔 / 区块分隔）。
+    ///
+    /// **无高程、无圆角**；厚度是一像素线（`LayoutMetrics::divider_thickness` = `stroke::HAIRLINE`），
+    /// 颜色 `OutlineVariant`（列表内）或 `Outline`（search view 头部分隔，见 §20.8）。
+    Divider,
+}
+
+impl Component {
+    /// 全部组件。
+    pub const ALL: [Component; 25] = [
+        Component::TopAppBar,
+        Component::NavigationItem,
+        Component::PrimaryButton,
+        Component::SecondaryButton,
+        Component::TextButton,
+        Component::IconButton,
+        Component::OutlinedCard,
+        Component::FilledCard,
+        Component::ListItem,
+        Component::TextField,
+        Component::SegmentedButton,
+        Component::Chip,
+        Component::Switch,
+        Component::Slider,
+        Component::ProgressIndicator,
+        Component::Dialog,
+        Component::Menu,
+        Component::Snackbar,
+        Component::Tooltip,
+        Component::EmptyState,
+        // M69 G9：末尾追加的 5 个（前 20 个次序不许动）。
+        Component::Checkbox,
+        Component::Radio,
+        Component::Search,
+        Component::NavigationDrawer,
+        Component::Divider,
+    ];
+
+    /// 该组件的档位。
+    pub fn spec(self) -> ComponentSpec {
+        table::SPECS[self as usize]
+    }
+
+    /// 该组件的**控件内部**微度量；`None` = 只有骨架值（去 `LayoutMetrics` 拿）。
+    ///
+    /// 这一条是 G10 的消费入口：组件线拿到 `Component::Checkbox.metrics()` 就有 20×20 / 圆角 2 /
+    /// 描边 2 / 状态层 Ø40，**不许再在实现里写这些字面量**。
+    pub fn metrics(self) -> Option<ComponentMetrics> {
+        metrics::metrics_of(self)
+    }
+
+    /// 稳定字符串名（kebab-case）。
+    pub const fn name(self) -> &'static str {
+        match self {
+            Component::TopAppBar => "top-app-bar",
+            Component::NavigationItem => "navigation-item",
+            Component::PrimaryButton => "primary-button",
+            Component::SecondaryButton => "secondary-button",
+            Component::TextButton => "text-button",
+            Component::IconButton => "icon-button",
+            Component::OutlinedCard => "outlined-card",
+            Component::FilledCard => "filled-card",
+            Component::ListItem => "list-item",
+            Component::TextField => "text-field",
+            Component::SegmentedButton => "segmented-button",
+            Component::Chip => "chip",
+            Component::Switch => "switch",
+            Component::Slider => "slider",
+            Component::ProgressIndicator => "progress-indicator",
+            Component::Dialog => "dialog",
+            Component::Menu => "menu",
+            Component::Snackbar => "snackbar",
+            Component::Tooltip => "tooltip",
+            Component::EmptyState => "empty-state",
+            // M69 G9：末尾追加（`name()` 是持久化字符串 id，同样只许末尾追加）。
+            Component::Checkbox => "checkbox",
+            Component::Radio => "radio",
+            Component::Search => "search",
+            Component::NavigationDrawer => "navigation-drawer",
+            Component::Divider => "divider",
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/design/src/component_map/table.rs b/crates/design/src/component_map/table.rs
new file mode 100644
index 0000000..26f846e
--- /dev/null
+++ b/crates/design/src/component_map/table.rs
@@ -0,0 +1,371 @@
+//! 组件档位数据表（**下标必须等于 `Component as usize`**，由测试钉死）。
+//!
+//! 一行一个组件。改值就是在改全站观感——同步协作文档再改。
+//!
+//! **末尾 5 行（M69 G9）** 的来源是 `research/15` §18~§23（同一套 `material3-android:1.4.0` 源码）：
+//! Checkbox / Radio / Search / NavigationDrawer / Divider。其中 Checkbox 的 **2dp** 圆角走
+//! [`ComponentRadius`]（D32 第二层，不塞进 `ShapeScale`），Divider 的厚度是一像素线（G12）而不在这张表里。
+//!
+//! **高程/形状取值来源（A 级）**：`androidx.compose.material3.tokens` 的各组件 `<X>Tokens.kt`
+//! （FilledCard/OutlinedCard/ElevatedCard/Menu/Dialog/Snackbar/AppBar/List）。已登记的两处偏离：
+//! - `Tooltip`：`PlainTooltipTokens.kt` 只有 Corner 行、**没有 Elevation 行**，Table 的 Level2 是
+//!   B 级（沿用 M3 旧规范「浮层 3dp」的直觉），有官方值后以官方为准；
+//! - `ListItem`：官方 `ListTokens` 用 `CornerNone`（直角行），本项目取 `Small(8)`——列表行在本
+//!   启动器里是**卡片内的独立可点块**（不是贴边通栏行），圆角与卡片同族更协调；偏差 8dp 已登记。
+
+use super::{Component, ComponentSpec};
+use crate::elevation::Elevation;
+use crate::motion::{
+    DurationToken, Easing, SPRING_EXPRESSIVE_SPATIAL_DEFAULT, SPRING_EXPRESSIVE_SPATIAL_FAST,
+};
+use crate::shape::{ComponentRadius, ShapeMorph, ShapeScale};
+use crate::typography::TypeRole;
+
+/// 一个组件的档位行（`const fn` 便捷构造，字段名在 [`ComponentSpec`] 里）。
+const fn spec(
+    component: Component,
+    shape: ShapeScale,
+    elevation: Elevation,
+    text: TypeRole,
+    support: Option<TypeRole>,
+    motion: Easing,
+    duration: DurationToken,
+    morph: Option<ShapeMorph>,
+) -> ComponentSpec {
+    ComponentSpec {
+        component,
+        shape,
+        micro_radius: None,
+        elevation,
+        text,
+        support,
+        motion,
+        duration,
+        morph,
+    }
+}
+
+/// 圆角走「微控件层」（D32）的档位行：`shape` 自动填占位 `None`，半径取白名单值。
+///
+/// 为什么单独一个构造器：`micro_radius` 与 `shape = None` 必须成对出现，用构造器保证配对，
+/// 不让 25 行表里出现「填了微半径忘了把 shape 清掉」。
+const fn spec_micro(
+    component: Component,
+    micro_radius: ComponentRadius,
+    elevation: Elevation,
+    text: TypeRole,
+    support: Option<TypeRole>,
+    motion: Easing,
+    duration: DurationToken,
+    morph: Option<ShapeMorph>,
+) -> ComponentSpec {
+    ComponentSpec {
+        component,
+        shape: ShapeScale::None,
+        micro_radius: Some(micro_radius),
+        elevation,
+        text,
+        support,
+        motion,
+        duration,
+        morph,
+    }
+}
+
+/// 25 个组件的档位表。
+pub(super) const SPECS: [ComponentSpec; 25] = [
+    spec(
+        Component::TopAppBar,
+        ShapeScale::None,
+        Elevation::Level0,
+        TypeRole::TitleLarge,
+        Some(TypeRole::BodySmall),
+        Easing::Standard,
+        DurationToken::Medium2,
+        None,
+    ),
+    spec(
+        Component::NavigationItem,
+        ShapeScale::Full,
+        Elevation::Level0,
+        TypeRole::LabelLarge,
+        None,
+        Easing::Emphasized,
+        DurationToken::Medium2,
+        Some(ShapeMorph::new(
+            ShapeScale::Large,
+            ShapeScale::Full,
+            SPRING_EXPRESSIVE_SPATIAL_FAST,
+        )),
+    ),
+    spec(
+        Component::PrimaryButton,
+        ShapeScale::Full,
+        Elevation::Level0,
+        TypeRole::LabelLarge,
+        None,
+        Easing::Emphasized,
+        DurationToken::Short4,
+        None,
+    ),
+    spec(
+        Component::SecondaryButton,
+        ShapeScale::Full,
+        Elevation::Level0,
+        TypeRole::LabelLarge,
+        None,
+        Easing::Standard,
+        DurationToken::Short4,
+        None,
+    ),
+    spec(
+        Component::TextButton,
+        ShapeScale::Full,
+        Elevation::Level0,
+        TypeRole::LabelLarge,
+        None,
+        Easing::Standard,
+        DurationToken::Short4,
+        None,
+    ),
+    spec(
+        Component::IconButton,
+        ShapeScale::Full,
+        Elevation::Level0,
+        TypeRole::LabelMedium,
+        None,
+        Easing::Standard,
+        DurationToken::Short3,
+        Some(ShapeMorph::new(
+            ShapeScale::Medium,
+            ShapeScale::Full,
+            SPRING_EXPRESSIVE_SPATIAL_FAST,
+        )),
+    ),
+    // FilledCardTokens.ContainerElevation = Level0（hover 才到 L1、dragged 到 L3）。
+    spec(
+        Component::OutlinedCard,
+        ShapeScale::Medium,
+        Elevation::Level0,
+        TypeRole::TitleMedium,
+        Some(TypeRole::BodySmall),
+        Easing::Standard,
+        DurationToken::Medium1,
+        None,
+    ),
+    spec(
+        Component::FilledCard,
+        ShapeScale::Medium,
+        Elevation::Level0,
+        TypeRole::TitleMedium,
+        Some(TypeRole::BodySmall),
+        Easing::Standard,
+        DurationToken::Medium1,
+        Some(ShapeMorph::new(
+            ShapeScale::Medium,
+            ShapeScale::Large,
+            SPRING_EXPRESSIVE_SPATIAL_DEFAULT,
+        )),
+    ),
+    spec(
+        Component::ListItem,
+        ShapeScale::Small,
+        Elevation::Level0,
+        TypeRole::BodyLarge,
+        Some(TypeRole::BodySmall),
+        Easing::Standard,
+        DurationToken::Short4,
+        None,
+    ),
+    spec(
+        Component::TextField,
+        ShapeScale::ExtraSmall,
+        Elevation::Level0,
+        TypeRole::BodyLarge,
+        Some(TypeRole::BodySmall),
+        Easing::Standard,
+        DurationToken::Short4,
+        None,
+    ),
+    spec(
+        Component::SegmentedButton,
+        ShapeScale::Full,
+        Elevation::Level0,
+        TypeRole::LabelLarge,
+        None,
+        Easing::Emphasized,
+        DurationToken::Medium2,
+        None,
+    ),
+    spec(
+        Component::Chip,
+        ShapeScale::Small,
+        Elevation::Level0,
+        TypeRole::LabelMedium,
+        None,
+        Easing::Standard,
+        DurationToken::Short3,
+        Some(ShapeMorph::new(
+            ShapeScale::ExtraSmall,
+            ShapeScale::Small,
+            SPRING_EXPRESSIVE_SPATIAL_FAST,
+        )),
+    ),
+    spec(
+        Component::Switch,
+        ShapeScale::Full,
+        Elevation::Level0,
+        TypeRole::BodyMedium,
+        Some(TypeRole::BodySmall),
+        Easing::Emphasized,
+        DurationToken::Medium2,
+        None,
+    ),
+    spec(
+        Component::Slider,
+        ShapeScale::Full,
+        Elevation::Level0,
+        TypeRole::BodyMedium,
+        Some(TypeRole::BodySmall),
+        Easing::Standard,
+        DurationToken::Short2,
+        None,
+    ),
+    spec(
+        Component::ProgressIndicator,
+        ShapeScale::Full,
+        Elevation::Level0,
+        TypeRole::LabelMedium,
+        None,
+        Easing::Linear,
+        DurationToken::Long2,
+        None,
+    ),
+    // DialogTokens.ContainerElevation = Level3，CornerExtraLarge = 28。
+    spec(
+        Component::Dialog,
+        ShapeScale::ExtraLarge,
+        Elevation::Level3,
+        TypeRole::HeadlineSmall,
+        Some(TypeRole::BodyMedium),
+        Easing::EmphasizedDecelerate,
+        DurationToken::Long4,
+        Some(ShapeMorph::new(
+            ShapeScale::Large,
+            ShapeScale::ExtraLarge,
+            SPRING_EXPRESSIVE_SPATIAL_DEFAULT,
+        )),
+    ),
+    // MenuTokens：CornerExtraSmall(4) + Level2。
+    spec(
+        Component::Menu,
+        ShapeScale::ExtraSmall,
+        Elevation::Level2,
+        TypeRole::BodyMedium,
+        None,
+        Easing::StandardDecelerate,
+        DurationToken::Short4,
+        None,
+    ),
+    spec(
+        Component::Snackbar,
+        ShapeScale::ExtraSmall,
+        Elevation::Level3,
+        TypeRole::BodyMedium,
+        None,
+        Easing::EmphasizedDecelerate,
+        DurationToken::Medium2,
+        None,
+    ),
+    spec(
+        Component::Tooltip,
+        ShapeScale::ExtraSmall,
+        Elevation::Level2,
+        TypeRole::BodySmall,
+        None,
+        Easing::StandardDecelerate,
+        DurationToken::Short2,
+        None,
+    ),
+    spec(
+        Component::EmptyState,
+        ShapeScale::Large,
+        Elevation::Level0,
+        TypeRole::HeadlineSmall,
+        Some(TypeRole::BodySmall),
+        Easing::Standard,
+        DurationToken::Medium2,
+        None,
+    ),
+    // ---- M69 G9：末尾追加的 5 个（`research/15` §18~§23；前 20 行次序不许动）----
+    // Checkbox：圆角 **2dp** 不在 `ShapeScale` 刻度里 → 走 `spec_micro`（D32 第二层）。
+    // 高程 L0：`CheckboxTokens` 没有 Elevation 行，容器是「描边/填充」两态而非浮层。
+    // 字级 `BodyLarge` 是**团队口径**：官方没有「框 + 标签」组合 token（§18.9），取列表行同一档。
+    // 动效取 M3 motion scheme 的 fast-effects（100ms standard）——[推导]，非 token 原文。
+    spec_micro(
+        Component::Checkbox,
+        ComponentRadius::Micro,
+        Elevation::Level0,
+        TypeRole::BodyLarge,
+        None,
+        Easing::Standard,
+        DurationToken::Short2,
+        None,
+    ),
+    // Radio：真圆（`RadioButtonTokens.IconSize = 20` + `CornerFull`），内点/环线宽见
+    // `ComponentMetrics::RADIO`。字级同 Checkbox（团队口径）。
+    spec(
+        Component::Radio,
+        ShapeScale::Full,
+        Elevation::Level0,
+        TypeRole::BodyLarge,
+        None,
+        Easing::Standard,
+        DurationToken::Short2,
+        None,
+    ),
+    // Search bar：圆角 `CornerFull` / `SearchBarCornerRadius = 56/2 = 28`。
+    // **高程取 L0**——`SearchBarTokens.ContainerElevation = Level3` 与
+    // `SearchBarDefaults.TonalElevation/ShadowElevation = Level0` 冲突（§26.2 矛盾 ②），
+    // 判据按观感取「无可见阴影 + tone 分层」，这条已在 `design-令牌约定` 登记。
+    // 无 shape morph：bar ⇄ docked 展开时**半径不变**（28 → 28），只长面积（§20C）。
+    spec(
+        Component::Search,
+        ShapeScale::Full,
+        Elevation::Level0,
+        TypeRole::BodyLarge,
+        Some(TypeRole::BodySmall),
+        Easing::Emphasized,
+        DurationToken::Medium2,
+        None,
+    ),
+    // Navigation drawer：官方 `ContainerShape = CornerLargeEnd`（只有靠内容那侧两角 16，
+    // 贴边侧直角）。`ShapeScale` 表达不了「部分角」，这里记内侧角的 `Large(16)`，
+    // 哪两个角由组件按侧位决定；写四角 16 = 变成浮动卡片（§21.2 判据）。
+    // 常驻形态 `Surface` + L0（模态才用 `SurfaceContainerLow` + scrim，本项目只在 <600 窗宽兜底）。
+    spec(
+        Component::NavigationDrawer,
+        ShapeScale::Large,
+        Elevation::Level0,
+        TypeRole::LabelLarge,
+        Some(TypeRole::TitleSmall),
+        Easing::Emphasized,
+        DurationToken::Medium2,
+        None,
+    ),
+    // Divider：无高程、无圆角、**无文字**（`text` 是占位值，消费方不得据此排版）；
+    // 厚度是一像素线 `LayoutMetrics::divider_thickness`，颜色 `OutlineVariant`
+    // （search view 头部分隔是 `Outline`，两个不同角色，§20.8）。
+    // **`motion` / `duration` 也是占位值**（`ComponentSpec.motion` 不是 `Option`）：Divider 没有
+    // 官方状态过渡令牌，消费方**不得据此排动效**；下轮把该字段改成 `Option` 更彻底。
+    spec(
+        Component::Divider,
+        ShapeScale::None,
+        Elevation::Level0,
+        TypeRole::BodySmall,
+        None,
+        Easing::Standard,
+        DurationToken::Short2,
+        None,
+    ),
+];
diff --git a/crates/design/src/component_map/tests.rs b/crates/design/src/component_map/tests.rs
new file mode 100644
index 0000000..47034c4
--- /dev/null
+++ b/crates/design/src/component_map/tests.rs
@@ -0,0 +1,202 @@
+//! `component_map` 的守门测试：表槽位 ↔ 枚举次序、官方高程/形状、圆角分层（D32）、微度量入口。
+//!
+//! 拆成独立文件是为了让 `mod.rs` 留出文档空间（项目硬约束：单文件 ≤400 行）。
+
+use super::*;
+
+#[test]
+fn table_matches_component_order() {
+    for (i, spec) in table::SPECS.iter().enumerate() {
+        assert_eq!(
+            spec.component as usize, i,
+            "SPECS 第 {i} 行顺序与枚举不一致"
+        );
+    }
+}
+
+#[test]
+fn every_component_resolves() {
+    assert_eq!(Component::ALL.len(), table::SPECS.len());
+    for component in Component::ALL {
+        let spec = component.spec();
+        assert_eq!(spec.component, component);
+        assert!(spec.text.style().size_px >= 11.0);
+    }
+}
+
+#[test]
+fn names_are_unique() {
+    let mut seen = std::collections::BTreeSet::new();
+    for component in Component::ALL {
+        assert!(
+            seen.insert(component.name()),
+            "组件名重复：{}",
+            component.name()
+        );
+    }
+}
+
+#[test]
+fn elevation_matches_official_component_tokens() {
+    // A 级来源（androidx.compose.material3.tokens）：
+    //   FilledCardTokens/OutlinedCardTokens.ContainerElevation = Level0
+    //   MenuTokens.ContainerElevation = Level2
+    //   DialogTokens.ContainerElevation = Level3
+    //   SnackbarTokens.ContainerElevation = Level3
+    //   AppBarTokens = Level0、ListTokens.ItemContainerElevation = Level0
+    // 偏离只允许出现在有登记的地方（Tooltip 是 B 级：token 文件里没有 Elevation 行）。
+    for (component, expect) in [
+        (Component::FilledCard, Elevation::Level0),
+        (Component::OutlinedCard, Elevation::Level0),
+        (Component::Menu, Elevation::Level2),
+        (Component::Dialog, Elevation::Level3),
+        (Component::Snackbar, Elevation::Level3),
+        (Component::TopAppBar, Elevation::Level0),
+        (Component::ListItem, Elevation::Level0),
+        (Component::TextField, Elevation::Level0),
+    ] {
+        assert_eq!(
+            component.spec().elevation,
+            expect,
+            "{} 的高程与官方组件令牌不一致",
+            component.name()
+        );
+    }
+    // R4「全屏都在飘」的守门：一屏常见元素里带阴影（>Level0）的只允许是浮层。
+    for component in Component::ALL {
+        if component.spec().elevation > Elevation::Level0 {
+            assert!(
+                matches!(
+                    component,
+                    Component::Menu | Component::Dialog | Component::Snackbar | Component::Tooltip
+                ),
+                "{} 不该有阴影（只有浮层允许）",
+                component.name()
+            );
+        }
+    }
+}
+
+#[test]
+fn shapes_match_official_component_tokens() {
+    // 官方：卡片 CornerMedium(12)、对话框 CornerExtraLarge(28)、菜单 CornerExtraSmall(4)、
+    // 按钮/导航指示条 CornerFull、chip CornerSmall(8)。
+    assert_eq!(Component::FilledCard.spec().shape, ShapeScale::Medium);
+    assert_eq!(Component::OutlinedCard.spec().shape, ShapeScale::Medium);
+    assert_eq!(Component::Dialog.spec().shape, ShapeScale::ExtraLarge);
+    assert_eq!(Component::Menu.spec().shape, ShapeScale::ExtraSmall);
+    assert_eq!(Component::PrimaryButton.spec().shape, ShapeScale::Full);
+    assert_eq!(Component::Chip.spec().shape, ShapeScale::Small);
+}
+
+#[test]
+fn only_primary_actions_use_filled_emphasis_and_one_dialog_layer() {
+    // 契约 §1：状态色不复用 accent、每屏最多一个实心 accent → 只有 primary-button 是
+    // 「实心强调」，其余按钮的形态由页面决定但不能是 Full + Level0 + Emphasized 的组合。
+    let primary = Component::PrimaryButton.spec();
+    assert_eq!(primary.shape, ShapeScale::Full);
+    assert_eq!(primary.text, TypeRole::LabelLarge);
+    // 浮层类必须比卡片层高。
+    assert!(Component::Dialog.spec().elevation > Component::OutlinedCard.spec().elevation);
+    assert!(Component::Menu.spec().elevation > Component::FilledCard.spec().elevation);
+}
+
+#[test]
+fn morphs_always_expand_upwards() {
+    for component in Component::ALL {
+        if let Some(morph) = component.spec().morph {
+            assert_ne!(
+                morph.from,
+                morph.to,
+                "{} 的形变起止不能相同",
+                component.name()
+            );
+            // 方向必须「沿阶梯胀开」（morph 对 `Full` 也没问题，rank 把它排在末尾），
+            // 不比较像素跨度：`Full` 的半径依赖边长，用固定边长比会被 `None` 之外的大档拉爆。
+            assert!(
+                morph.from.rank() < morph.to.rank(),
+                "{} 的形变方向反了：{:?} → {:?}",
+                component.name(),
+                morph.from,
+                morph.to
+            );
+        }
+    }
+}
+
+#[test]
+fn appended_variants_keep_the_frozen_order() {
+    // 枚举冻结为「只可末尾追加」：前 20 个的次序不能动（M69 只在末尾加 5 个）。
+    assert_eq!(Component::ALL.len(), 25);
+    assert_eq!(Component::ALL[0], Component::TopAppBar);
+    assert_eq!(Component::ALL[19], Component::EmptyState);
+    assert_eq!(Component::ALL[20], Component::Checkbox);
+    assert_eq!(Component::ALL[24], Component::Divider);
+    for (i, component) in Component::ALL.iter().enumerate() {
+        assert_eq!(*component as usize, i, "ALL 的次序与枚举判别值不一致");
+    }
+}
+
+#[test]
+fn micro_radius_only_on_micro_controls() {
+    // D32：微半径只能给 ≤24dp 的微控件，且此时 `shape` 必须是占位 None（不参与渲染）。
+    let mut owners = Vec::new();
+    for component in Component::ALL {
+        let spec = component.spec();
+        let Some(radius) = spec.micro_radius else {
+            continue;
+        };
+        owners.push(component);
+        assert_eq!(radius, ComponentRadius::Micro, "白名单外的微半径不许过表");
+        assert_eq!(
+            spec.shape,
+            ShapeScale::None,
+            "{} 有微半径时 shape 必须占位 None（2dp 不在刻度里）",
+            component.name()
+        );
+        let metrics = component
+            .metrics()
+            .expect("带微半径的组件必须有 ComponentMetrics");
+        assert!(
+            metrics.width <= crate::shape::MICRO_CONTROL_MAX_SIZE
+                && metrics.height <= crate::shape::MICRO_CONTROL_MAX_SIZE,
+            "{} 超出微控件尺寸上限",
+            component.name()
+        );
+        assert_eq!(
+            radius.radius_px(metrics.width),
+            Some(radius.dp()),
+            "{} 的微半径按自身尺寸取不到",
+            component.name()
+        );
+    }
+    assert_eq!(
+        owners,
+        vec![Component::Checkbox],
+        "当前只允许 Checkbox 用微半径"
+    );
+}
+
+#[test]
+fn metrics_resolve_only_for_controls_with_inner_geometry() {
+    for component in [
+        Component::Checkbox,
+        Component::Radio,
+        Component::Search,
+        Component::NavigationDrawer,
+    ] {
+        assert!(
+            component.metrics().is_some(),
+            "{} 缺 ComponentMetrics",
+            component.name()
+        );
+    }
+    // Divider 只有厚度，而厚度是一像素线（LM），不该出现在 CM 里。
+    assert!(Component::Divider.metrics().is_none());
+    // 骨架级尺寸不许在 CM 里重复一份（Single Source of Truth）。
+    for component in [Component::Search, Component::NavigationDrawer] {
+        let metrics = component.metrics().unwrap();
+        assert_eq!(metrics.width, 0.0, "{} 的宽度属骨架级", component.name());
+        assert_eq!(metrics.height, 0.0, "{} 的高度属骨架级", component.name());
+    }
+}
diff --git a/crates/design/src/elevation.rs b/crates/design/src/elevation.rs
new file mode 100644
index 0000000..80f2bf2
--- /dev/null
+++ b/crates/design/src/elevation.rs
@@ -0,0 +1,226 @@
+//! 高程令牌：elevation level、阴影参数、surface container 映射。
+//!
+//! M3 在 2024 之后改了「怎么表达高程」：**不再**往表面上叠半透明的 surface tint，
+//! 而是用 `surface-container-*` 这一族中性容器色表达层级（GPU 路径再叠阴影做空间感）。
+//! 本模块两种口径都给出，旧口径显式标为 deprecated，避免页面线混用。
+
+use crate::color::Role;
+
+/// M3 高程级别 0..5（对应 0 / 1 / 3 / 6 / 8 / 12 dp）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
+pub enum Elevation {
+    /// 0dp：贴底内容（窗口底、内联区）。
+    Level0,
+    /// 1dp：卡片、可抬起的列表项。
+    Level1,
+    /// 3dp：可交互卡片、导航栏。
+    Level2,
+    /// 6dp：FAB、侧栏、浮动工具条。
+    Level3,
+    /// 8dp：菜单、popover。
+    Level4,
+    /// 12dp：对话框、模态。
+    Level5,
+}
+
+impl Elevation {
+    /// 全部级别。
+    pub const ALL: [Elevation; 6] = [
+        Elevation::Level0,
+        Elevation::Level1,
+        Elevation::Level2,
+        Elevation::Level3,
+        Elevation::Level4,
+        Elevation::Level5,
+    ];
+
+    /// 标称高度（dp）。
+    pub const fn dp(self) -> f32 {
+        match self {
+            Elevation::Level0 => 0.0,
+            Elevation::Level1 => 1.0,
+            Elevation::Level2 => 3.0,
+            Elevation::Level3 => 6.0,
+            Elevation::Level4 => 8.0,
+            Elevation::Level5 => 12.0,
+        }
+    }
+
+    /// 该级别应使用的表面容器色角色（M3 现行口径）。
+    ///
+    /// 层级靠**换底色**表达，不靠 tint；浅深模式都成立。
+    pub const fn surface_role(self) -> Role {
+        match self {
+            Elevation::Level0 => Role::SurfaceContainerLowest,
+            Elevation::Level1 => Role::SurfaceContainerLow,
+            Elevation::Level2 => Role::SurfaceContainer,
+            Elevation::Level3 => Role::SurfaceContainerHigh,
+            Elevation::Level4 | Elevation::Level5 => Role::SurfaceContainerHighest,
+        }
+    }
+
+    /// 阴影参数（**占位值，待 M63 视觉规格** — 见下面的 TODO）。
+    ///
+    /// TODO(M63): 取值待视觉规格。官方只给 dp 与设计稿示意，没有可移植的 blur/alpha 公式；
+    /// 这里的 blur/offset/alpha 是临时占位（按「blur ≈ dp × 1.3 + 1.5」凑的数），
+    /// M63 的玻璃规格表落地后以那张表为准，别在页面里引用这些绝对值。
+    pub const fn shadow(self) -> ShadowSpec {
+        match self {
+            Elevation::Level0 => ShadowSpec {
+                blur_px: 0.0,
+                offset_y_px: 0.0,
+                alpha: 0.0,
+            },
+            Elevation::Level1 => ShadowSpec {
+                blur_px: 3.0,
+                offset_y_px: 1.0,
+                alpha: 0.12,
+            },
+            Elevation::Level2 => ShadowSpec {
+                blur_px: 6.0,
+                offset_y_px: 2.0,
+                alpha: 0.14,
+            },
+            Elevation::Level3 => ShadowSpec {
+                blur_px: 9.0,
+                offset_y_px: 4.0,
+                alpha: 0.16,
+            },
+            Elevation::Level4 => ShadowSpec {
+                blur_px: 12.0,
+                offset_y_px: 6.0,
+                alpha: 0.18,
+            },
+            Elevation::Level5 => ShadowSpec {
+                blur_px: 17.0,
+                offset_y_px: 8.0,
+                alpha: 0.20,
+            },
+        }
+    }
+
+    /// 旧口径（M3 2022）：把 `surface-tint` 按这个 alpha 叠在 `surface` 上表达高程。
+    ///
+    /// **deprecated**——现行 M3 用 [`Elevation::surface_role`]；保留只为读旧稿时能对上数，
+    /// 新代码不要用。
+    pub const fn deprecated_tint_alpha(self) -> f32 {
+        match self {
+            Elevation::Level0 => 0.0,
+            Elevation::Level1 => 0.05,
+            Elevation::Level2 => 0.08,
+            Elevation::Level3 => 0.11,
+            Elevation::Level4 => 0.12,
+            Elevation::Level5 => 0.14,
+        }
+    }
+}
+
+/// 一层阴影的绘制参数。
+///
+/// TODO(M63): 取值待视觉规格（这份结构只是「接口预留」，数值由 M63 的玻璃规格表填充）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct ShadowSpec {
+    /// 高斯模糊半径（px）。
+    pub blur_px: f32,
+    /// 向下偏移（px）。
+    pub offset_y_px: f32,
+    /// 阴影色 alpha（叠在 [`crate::color::Scheme::shadow`] 之上）。
+    pub alpha: f32,
+}
+
+impl ShadowSpec {
+    /// 是否可见（0 表示这一级不画阴影）。
+    pub fn is_visible(&self) -> bool {
+        self.alpha > 0.0 && self.blur_px > 0.0
+    }
+}
+
+/// 三个「材质层」的语义（沿用 `ui-integration-contract.md` §2 的三层，映射到 M3 令牌）。
+///
+/// 页面线按层取色，不许自己决定「这一层比那一层深一点」。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MaterialLayer {
+    /// 底层（canvas）：窗口底，永远不透明。
+    Canvas,
+    /// 卡片层：页面内容/设置分组/AI 面板。
+    Card,
+    /// 浮层：对话框、菜单、Toast。
+    Overlay,
+}
+
+impl MaterialLayer {
+    /// 该层的底色角色。
+    pub const fn surface_role(self) -> Role {
+        match self {
+            MaterialLayer::Canvas => Role::Surface,
+            MaterialLayer::Card => Role::SurfaceContainerLow,
+            MaterialLayer::Overlay => Role::SurfaceContainerHigh,
+        }
+    }
+
+    /// 该层的高程级别。
+    pub const fn elevation(self) -> Elevation {
+        match self {
+            MaterialLayer::Canvas => Elevation::Level0,
+            MaterialLayer::Card => Elevation::Level1,
+            MaterialLayer::Overlay => Elevation::Level3,
+        }
+    }
+
+    /// 该层是否允许半透明（D27：**只有 GPU 路径**才允许；CPU 路径一律纯色）。
+    pub const fn allows_translucency(self) -> bool {
+        matches!(self, MaterialLayer::Card | MaterialLayer::Overlay)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn elevation_dp_ladder() {
+        let ladder: Vec<f32> = Elevation::ALL.iter().map(|e| e.dp()).collect();
+        assert_eq!(ladder, vec![0.0, 1.0, 3.0, 6.0, 8.0, 12.0]);
+    }
+
+    #[test]
+    fn shadow_grows_with_elevation() {
+        let mut prev = Elevation::Level0.shadow();
+        for level in &Elevation::ALL[1..] {
+            let cur = level.shadow();
+            assert!(cur.blur_px > prev.blur_px, "{level:?} 的模糊应更大");
+            assert!(cur.offset_y_px >= prev.offset_y_px);
+            assert!(cur.alpha >= prev.alpha);
+            assert!(cur.is_visible());
+            prev = cur;
+        }
+        assert!(!Elevation::Level0.shadow().is_visible());
+    }
+
+    #[test]
+    fn higher_levels_use_higher_surface_containers() {
+        assert_eq!(
+            Elevation::Level5.surface_role(),
+            Role::SurfaceContainerHighest
+        );
+        assert_eq!(
+            Elevation::Level0.surface_role(),
+            Role::SurfaceContainerLowest
+        );
+    }
+
+    #[test]
+    fn material_layers_are_ordered() {
+        assert_eq!(MaterialLayer::Canvas.surface_role(), Role::Surface);
+        assert_eq!(
+            MaterialLayer::Card.surface_role(),
+            Role::SurfaceContainerLow
+        );
+        assert_eq!(
+            MaterialLayer::Overlay.surface_role(),
+            Role::SurfaceContainerHigh
+        );
+        assert!(!MaterialLayer::Canvas.allows_translucency());
+        assert!(MaterialLayer::Overlay.allows_translucency());
+    }
+}
diff --git a/crates/design/src/icons/glyphs.rs b/crates/design/src/icons/glyphs.rs
new file mode 100644
index 0000000..c692fa3
--- /dev/null
+++ b/crates/design/src/icons/glyphs.rs
@@ -0,0 +1,184 @@
+//! 图标几何数据：24 网格、1.5px 视觉描边的 SVG path 字符串。
+//!
+//! 源流：`DevDocs/ops/slint-reference/crates/app/ui/components/icons.slint`（M54 重画过一轮的
+//! Fluent 2 线性几何）。命令集沿用 `M/L/H/V/A/C/Q/Z`，与 SVG 路径语法一致，可直接交给
+//! 任何 SVG path 解析器（iced 侧是 `iced::widget::canvas` 的 `Path`/`lyon`）。
+//!
+//! 这里只有数据：不许在数据里写颜色、尺寸、dpi——那些由渲染层决定。
+
+use super::{Icon, IconKind, IconPaint};
+
+/// 全部图标几何，**下标必须等于 `IconKind as usize`**（由测试钉死）。
+pub(super) const GLYPHS: [Icon; 28] = [
+    // 实例：2×2 圆角方块（原 Slint 版是 4 个 Rectangle 描边，这里折成一条 path）
+    Icon::data(
+        IconKind::Instances,
+        "M 5 3 H 8 A 2 2 0 0 1 10 5 V 8 A 2 2 0 0 1 8 10 H 5 A 2 2 0 0 1 3 8 V 5 A 2 2 0 0 1 5 3 Z \
+         M 16 3 H 19 A 2 2 0 0 1 21 5 V 8 A 2 2 0 0 1 19 10 H 16 A 2 2 0 0 1 14 8 V 5 A 2 2 0 0 1 16 3 Z \
+         M 5 14 H 8 A 2 2 0 0 1 10 16 V 19 A 2 2 0 0 1 8 21 H 5 A 2 2 0 0 1 3 19 V 16 A 2 2 0 0 1 5 14 Z \
+         M 16 14 H 19 A 2 2 0 0 1 21 16 V 19 A 2 2 0 0 1 19 21 H 16 A 2 2 0 0 1 14 19 V 16 A 2 2 0 0 1 16 14 Z",
+        IconPaint::Stroke,
+    ),
+    // 下载：箭头入托盘
+    Icon::data(
+        IconKind::Download,
+        "M 12 3.5 V 15 M 7 10.5 L 12 15.5 L 17 10.5 M 4.5 20.5 H 19.5",
+        IconPaint::Stroke,
+    ),
+    // 日志：卷角文档 + 两行正文（不是三横——三横读作「菜单」）
+    Icon::data(
+        IconKind::Logs,
+        "M 6 3.5 H 14 L 18.5 8 V 20.5 H 6 Z M 14 3.5 V 8 H 18.5 M 9 12.5 H 15.5 M 9 16.5 H 15.5",
+        IconPaint::Stroke,
+    ),
+    // 设置：八齿齿轮 + 中心孔
+    Icon::data(
+        IconKind::Settings,
+        "M 18.89 14.11 L 21.51 13.34 L 21.51 10.66 L 18.89 9.89 A 7.2 7.2 0 0 1 18.36 8.62 \
+         L 19.67 6.22 L 17.78 4.33 L 15.38 5.64 A 7.2 7.2 0 0 1 14.11 5.11 L 13.34 2.49 L 10.66 2.49 \
+         L 9.89 5.11 A 7.2 7.2 0 0 1 8.62 5.64 L 6.22 4.33 L 4.33 6.22 L 5.64 8.62 A 7.2 7.2 0 0 1 5.11 9.89 \
+         L 2.49 10.66 L 2.49 13.34 L 5.11 14.11 A 7.2 7.2 0 0 1 5.64 15.38 L 4.33 17.78 L 6.22 19.67 \
+         L 8.62 18.36 A 7.2 7.2 0 0 1 9.89 18.89 L 10.66 21.51 L 13.34 21.51 L 14.11 18.89 A 7.2 7.2 0 0 1 15.38 18.36 \
+         L 17.78 19.67 L 19.67 17.78 L 18.36 15.38 A 7.2 7.2 0 0 1 18.89 14.11 Z \
+         M 8.8 12 A 3.2 3.2 0 1 0 15.2 12 A 3.2 3.2 0 1 0 8.8 12 Z",
+        IconPaint::Stroke,
+    ),
+    // AI：四角星（凹边四角星，不是直线菱形）
+    Icon::data(
+        IconKind::Ai,
+        "M 12 3 Q 13.6 10.4 21 12 Q 13.6 13.6 12 21 Q 10.4 13.6 3 12 Q 10.4 10.4 12 3 Z",
+        IconPaint::Stroke,
+    ),
+    // 播放 / 停止：实心（与文字并排时不至于太轻）
+    Icon::data(
+        IconKind::Play,
+        "M 7.5 4.5 L 19 12 L 7.5 19.5 Z",
+        IconPaint::Fill,
+    ),
+    Icon::data(
+        IconKind::Stop,
+        "M 8 7 H 16 A 1 1 0 0 1 17 8 V 16 A 1 1 0 0 1 16 17 H 8 A 1 1 0 0 1 7 16 V 8 A 1 1 0 0 1 8 7 Z",
+        IconPaint::Fill,
+    ),
+    // 搜索：放大镜
+    Icon::data(
+        IconKind::Search,
+        "M 10.5 4 A 6.5 6.5 0 1 0 10.5 17 A 6.5 6.5 0 1 0 10.5 4 Z M 15.4 15.4 L 20.5 20.5",
+        IconPaint::Stroke,
+    ),
+    Icon::data(
+        IconKind::Plus,
+        "M 12 5 V 19 M 5 12 H 19",
+        IconPaint::Stroke,
+    ),
+    Icon::data(
+        IconKind::Close,
+        "M 6.5 6.5 L 17.5 17.5 M 17.5 6.5 L 6.5 17.5",
+        IconPaint::Stroke,
+    ),
+    Icon::data(IconKind::Minimize, "M 6 12 H 18", IconPaint::Stroke),
+    Icon::data(
+        IconKind::Maximize,
+        "M 7.5 5.5 H 16.5 A 2 2 0 0 1 18.5 7.5 V 16.5 A 2 2 0 0 1 16.5 18.5 H 7.5 \
+         A 2 2 0 0 1 5.5 16.5 V 7.5 A 2 2 0 0 1 7.5 5.5 Z",
+        IconPaint::Stroke,
+    ),
+    Icon::data(
+        IconKind::ChevronLeft,
+        "M 14.5 5.5 L 8 12 L 14.5 18.5",
+        IconPaint::Stroke,
+    ),
+    Icon::data(
+        IconKind::ChevronRight,
+        "M 9.5 5.5 L 16 12 L 9.5 18.5",
+        IconPaint::Stroke,
+    ),
+    Icon::data(
+        IconKind::ChevronDown,
+        "M 5.5 9.5 L 12 16 L 18.5 9.5",
+        IconPaint::Stroke,
+    ),
+    // 展开为独立页：双对角外箭头
+    Icon::data(
+        IconKind::Expand,
+        "M 14 4 H 20 V 10 M 20 4 L 13.5 10.5 M 10 20 H 4 V 14 M 4 20 L 10.5 13.5",
+        IconPaint::Stroke,
+    ),
+    // 发送：纸飞机
+    Icon::data(
+        IconKind::Send,
+        "M 21 3 L 3 10.5 L 10.2 13.6 L 13.4 20.5 Z M 10.2 13.6 L 21 3",
+        IconPaint::Stroke,
+    ),
+    Icon::data(
+        IconKind::Check,
+        "M 5 12.5 L 9.8 17.3 L 19 6.5",
+        IconPaint::Stroke,
+    ),
+    Icon::data(
+        IconKind::Warn,
+        "M 12 4.5 L 20.5 19.5 H 3.5 Z M 12 9.5 V 14 M 12 16.6 V 17",
+        IconPaint::Stroke,
+    ),
+    Icon::data(
+        IconKind::Error,
+        "M 12 4 A 8 8 0 1 0 12 20 A 8 8 0 1 0 12 4 Z M 12 7.5 V 13 M 12 16.6 V 17",
+        IconPaint::Stroke,
+    ),
+    // 更多：三圆点（实心，原 Slint 版是三个 filled Rectangle）
+    Icon::data(
+        IconKind::More,
+        "M 7.5 12 A 1.5 1.5 0 1 0 4.5 12 A 1.5 1.5 0 1 0 7.5 12 Z \
+         M 13.5 12 A 1.5 1.5 0 1 0 10.5 12 A 1.5 1.5 0 1 0 13.5 12 Z \
+         M 19.5 12 A 1.5 1.5 0 1 0 16.5 12 A 1.5 1.5 0 1 0 19.5 12 Z",
+        IconPaint::Fill,
+    ),
+    // 侧栏：面板框 + 左侧分栏线
+    Icon::data(
+        IconKind::Sidebar,
+        "M 6 5 H 18 A 2 2 0 0 1 20 7 V 17 A 2 2 0 0 1 18 19 H 6 A 2 2 0 0 1 4 17 V 7 \
+         A 2 2 0 0 1 6 5 Z M 9.5 5.5 V 18.5",
+        IconPaint::Stroke,
+    ),
+    // 还原（已最大化时的标题栏按钮）：前后两层方框
+    Icon::data(
+        IconKind::Restore,
+        "M 9 4.5 H 19.5 V 15 M 15 8.5 H 4.5 V 19.5 H 15 Z",
+        IconPaint::Stroke,
+    ),
+    // 账户占位：头像剪影
+    Icon::data(
+        IconKind::User,
+        "M 12 5.3 A 3.7 3.7 0 1 0 12 12.7 A 3.7 3.7 0 1 0 12 5.3 Z \
+         M 4.5 20.5 C 4.5 16.9 8 15 12 15 C 16 15 19.5 16.9 19.5 20.5",
+        IconPaint::Stroke,
+    ),
+    // ── M61 新增（追加在末尾，不动既有次序；iced 页面需要而 Slint 版没有的）──
+    // 刷新：顺时针单圈 + 右上角箭头
+    Icon::data(
+        IconKind::Refresh,
+        "M 20 12 A 8 8 0 1 1 12 4 C 14.2 4 16.3 4.9 17.8 6.4 L 20 8.5 \
+         M 20 4.5 V 8.5 H 16",
+        IconPaint::Stroke,
+    ),
+    // 筛选：漏斗
+    Icon::data(
+        IconKind::Filter,
+        "M 4.5 5.5 H 19.5 L 14 12.5 V 19 L 10 16.5 V 12.5 Z",
+        IconPaint::Stroke,
+    ),
+    // 目录：文件夹（实例目录 / 日志目录入口）
+    Icon::data(
+        IconKind::Folder,
+        "M 4 7.5 A 2 2 0 0 1 6 5.5 H 9.5 L 11.5 7.5 H 18 A 2 2 0 0 1 20 9.5 V 17 \
+         A 2 2 0 0 1 18 19 H 6 A 2 2 0 0 1 4 17 Z",
+        IconPaint::Stroke,
+    ),
+    // 删除：垃圾桶
+    Icon::data(
+        IconKind::Trash,
+        "M 4.5 7 H 19.5 M 9.5 7 V 4.5 H 14.5 V 7 M 6.8 7 L 7.8 19.5 H 16.2 L 17.2 7 \
+         M 10.5 10.5 V 16 M 13.5 10.5 V 16",
+        IconPaint::Stroke,
+    ),
+];
diff --git a/crates/design/src/icons/kinds.rs b/crates/design/src/icons/kinds.rs
new file mode 100644
index 0000000..d736996
--- /dev/null
+++ b/crates/design/src/icons/kinds.rs
@@ -0,0 +1,208 @@
+//! `IconKind` 枚举：**API 已冻结，只允许在末尾追加**（序号即持久化 id，插到中间会静默换图）。
+
+use super::glyphs::GLYPHS;
+use super::Icon;
+
+/// 图标种类。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
+#[non_exhaustive]
+pub enum IconKind {
+    /// 实例（2×2 网格）。
+    Instances,
+    /// 下载。
+    Download,
+    /// 日志（文档 + 正文）。
+    Logs,
+    /// 设置（齿轮）。
+    Settings,
+    /// AI（四角星）。
+    Ai,
+    /// 播放（实心三角）。
+    Play,
+    /// 停止（实心圆角方）。
+    Stop,
+    /// 搜索（放大镜）。
+    Search,
+    /// 加号。
+    Plus,
+    /// 关闭（叉）。
+    Close,
+    /// 最小化（横线）。
+    Minimize,
+    /// 最大化（方框）。
+    Maximize,
+    /// 左尖角。
+    ChevronLeft,
+    /// 右尖角。
+    ChevronRight,
+    /// 下尖角。
+    ChevronDown,
+    /// 展开为独立页（双对角箭头）。
+    Expand,
+    /// 发送（纸飞机）。
+    Send,
+    /// 勾选。
+    Check,
+    /// 警告（三角感叹）。
+    Warn,
+    /// 错误（圆形感叹）。
+    Error,
+    /// 更多（三点，实心）。
+    More,
+    /// 侧栏开关。
+    Sidebar,
+    /// 还原窗口（双层方框）。
+    Restore,
+    /// 账户占位（头像剪影）。
+    User,
+    /// 刷新（M61 新增）。
+    Refresh,
+    /// 筛选（M61 新增）。
+    Filter,
+    /// 目录（M61 新增）。
+    Folder,
+    /// 删除（M61 新增）。
+    Trash,
+}
+
+impl IconKind {
+    /// 全部图标，按枚举声明顺序。
+    pub const ALL: [IconKind; 28] = [
+        IconKind::Instances,
+        IconKind::Download,
+        IconKind::Logs,
+        IconKind::Settings,
+        IconKind::Ai,
+        IconKind::Play,
+        IconKind::Stop,
+        IconKind::Search,
+        IconKind::Plus,
+        IconKind::Close,
+        IconKind::Minimize,
+        IconKind::Maximize,
+        IconKind::ChevronLeft,
+        IconKind::ChevronRight,
+        IconKind::ChevronDown,
+        IconKind::Expand,
+        IconKind::Send,
+        IconKind::Check,
+        IconKind::Warn,
+        IconKind::Error,
+        IconKind::More,
+        IconKind::Sidebar,
+        IconKind::Restore,
+        IconKind::User,
+        IconKind::Refresh,
+        IconKind::Filter,
+        IconKind::Folder,
+        IconKind::Trash,
+    ];
+
+    /// 取几何数据。
+    pub fn icon(self) -> Icon {
+        GLYPHS[self as usize]
+    }
+
+    /// 稳定字符串名（kebab-case）：写配置、日志、测试快照都用它，不要用 `Debug` 输出。
+    pub const fn name(self) -> &'static str {
+        match self {
+            IconKind::Instances => "instances",
+            IconKind::Download => "download",
+            IconKind::Logs => "logs",
+            IconKind::Settings => "settings",
+            IconKind::Ai => "ai",
+            IconKind::Play => "play",
+            IconKind::Stop => "stop",
+            IconKind::Search => "search",
+            IconKind::Plus => "plus",
+            IconKind::Close => "close",
+            IconKind::Minimize => "minimize",
+            IconKind::Maximize => "maximize",
+            IconKind::ChevronLeft => "chevron-left",
+            IconKind::ChevronRight => "chevron-right",
+            IconKind::ChevronDown => "chevron-down",
+            IconKind::Expand => "expand",
+            IconKind::Send => "send",
+            IconKind::Check => "check",
+            IconKind::Warn => "warn",
+            IconKind::Error => "error",
+            IconKind::More => "more",
+            IconKind::Sidebar => "sidebar",
+            IconKind::Restore => "restore",
+            IconKind::User => "user",
+            IconKind::Refresh => "refresh",
+            IconKind::Filter => "filter",
+            IconKind::Folder => "folder",
+            IconKind::Trash => "trash",
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::icons::IconPaint;
+
+    #[test]
+    fn glyph_table_matches_enum_order() {
+        for (i, icon) in GLYPHS.iter().enumerate() {
+            assert_eq!(
+                icon.kind as usize,
+                i,
+                "GLYPHS 第 {i} 项是 {}，与 IconKind 顺序不一致",
+                icon.kind.name()
+            );
+        }
+    }
+
+    #[test]
+    fn all_kinds_resolve() {
+        assert_eq!(IconKind::ALL.len(), GLYPHS.len());
+        for kind in IconKind::ALL {
+            let icon = kind.icon();
+            assert_eq!(icon.kind, kind);
+            assert!(!icon.path.is_empty());
+        }
+    }
+
+    #[test]
+    fn names_are_unique_and_kebab() {
+        let mut seen = std::collections::BTreeSet::new();
+        for kind in IconKind::ALL {
+            let name = kind.name();
+            assert!(seen.insert(name), "图标名重复：{name}");
+            assert!(name
+                .chars()
+                .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-'));
+        }
+    }
+
+    #[test]
+    fn migrated_kinds_keep_their_positions() {
+        // 前 24 个是 Slint 版迁移来的（次序必须原样），后 4 个是 M61 追加的。
+        assert_eq!(IconKind::ALL[0], IconKind::Instances);
+        assert_eq!(IconKind::ALL[4], IconKind::Ai);
+        assert_eq!(IconKind::ALL[20], IconKind::More);
+        assert_eq!(IconKind::ALL[23], IconKind::User);
+        assert_eq!(IconKind::ALL[24], IconKind::Refresh);
+        assert_eq!(IconKind::ALL[27], IconKind::Trash);
+    }
+
+    #[test]
+    fn only_solid_icons_are_filled() {
+        for kind in IconKind::ALL {
+            let icon = kind.icon();
+            let expect_fill = matches!(kind, IconKind::Play | IconKind::Stop | IconKind::More);
+            assert_eq!(
+                icon.paint,
+                if expect_fill {
+                    IconPaint::Fill
+                } else {
+                    IconPaint::Stroke
+                },
+                "{} 的 fill/stroke 判定不对",
+                kind.name()
+            );
+        }
+    }
+}
diff --git a/crates/design/src/icons/mod.rs b/crates/design/src/icons/mod.rs
new file mode 100644
index 0000000..c575ba3
--- /dev/null
+++ b/crates/design/src/icons/mod.rs
@@ -0,0 +1,342 @@
+//! 图标令牌：`IconKind`（一次冻结，只允许在末尾追加）+ 24 网格几何数据。
+//!
+//! ```no_run
+//! use unlucky_design::icons::{IconKind, IconSize};
+//!
+//! let icon = IconKind::Settings.icon();
+//! let w = icon.stroke_width(IconSize::Nav.px());
+//! assert!((w - 1.8).abs() < 1e-6);
+//! ```
+//!
+//! ## 几何口径（三线统一，M54 定稿）
+//!
+//! - **网格 24×24**（[`VIEWBOX`]），内容留 2~3 单位边距；
+//! - **视觉描边 1.5px**（[`VISUAL_STROKE_PX`]）：不管渲染多大，线宽看起来都是 1.5 逻辑像素；
+//! - **圆头端点 + 圆角连接**（`stroke-linecap: round` / `stroke-linejoin: round`），
+//!   适配层设这两个属性，数据里不表达；
+//! - **实心图形才用 fill**（播放/停止/三点），其余一律描边，保证与文字并排时重量一致；
+//! - 不用字体字符当图标（`+` `→` 一律禁止）。
+//!
+//! ## ⚠️ 描边语义差异：Slint 与 SVG **不是一回事**
+//!
+//! - Slint 的 `Path.stroke-width` 是**绝对像素**：只乘 DPI 缩放，**不乘 viewBox**。
+//!   所以老代码写 `stroke-width: 1.5px` 意味着「渲染出来就是 1.5px」，viewBox 缩放对它无影响
+//!   （实证：femtovg 后端 `PathItemRenderer::render` 里的
+//!   `paint.set_line_width(stroke_width * scale_factor)`——只有 DPI 缩放因子，没有 viewBox 项）。
+//! - SVG / iced canvas 的 `stroke-width` 是**用户单位**（viewBox 单位）：渲染时会被
+//!   `render_px / VIEWBOX` 缩放。同样的 `1.5` 在 20px 渲染下只有 1.25px 视觉宽度。
+//!
+//! 因此 iced 侧必须**按 SVG 语义重算**：要保持 1.5px 视觉线宽，viewBox 里的 stroke-width 得取
+//! `1.5 × 24 / render_px`（24px → 1.5、20px → 1.8、18px → 2.0、16px → 2.25）。[`Icon::stroke_width`]
+//! 就是这个换算的纯函数——**不要在适配层手抄 1.5 这个数**，那是 Slint 口径。
+
+mod glyphs;
+mod kinds;
+
+pub use kinds::IconKind;
+
+/// 图标网格边长（viewBox 宽高）。
+pub const VIEWBOX: f32 = 24.0;
+
+/// 视觉描边宽度（逻辑像素，与渲染尺寸无关）。
+pub const VISUAL_STROKE_PX: f32 = 1.5;
+
+/// 描边语义换算：给定渲染尺寸与目标视觉线宽，返回 **viewBox 单位**的 stroke-width。
+///
+/// `render_px <= 0` 时返回 `visual_px`（退化情形不产生除零/无穷大）。
+pub fn stroke_width_for(render_px: f32, visual_px: f32) -> f32 {
+    if render_px <= 0.0 {
+        return visual_px;
+    }
+    visual_px * VIEWBOX / render_px
+}
+
+/// 反向换算：viewBox 单位的 stroke-width 在实际渲染尺寸下的视觉线宽。
+pub fn visual_stroke_px(render_px: f32, stroke_width: f32) -> f32 {
+    stroke_width * render_px / VIEWBOX
+}
+
+/// 图标的绘制方式。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum IconPaint {
+    /// 只描边（默认，绝大多数图标）。
+    Stroke,
+    /// 填充（播放/停止/三点这类实心图形）。
+    Fill,
+}
+
+/// 图标的标准渲染尺寸（页面只从这几档里取，不许自定义零散值）。
+///
+/// ## 每一档服务于哪个规格（出处全部是 A 级：`material3-android-1.4.0.aar` 的字节码）
+///
+/// 判据顺序固定为：**先看官方组件实际消费哪个值，再看 token 类里写了什么**。两者冲突时以
+/// 「有消费者的那个」为准——1.4.0 里 `ButtonSmallTokens.IconSize = 20` 就是**零消费者**的死令牌
+/// （`javap` 全 AAR 搜 `getIconSize` 调用，没有任何类读它；`ButtonDefaults` 只借了同一
+/// token 类的 `IconLabelSpace` / `ContainerHeight` / `ContainerShapeRound`）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum IconSize {
+    /// 12px：行内小图标（徽标内）。
+    Inline,
+    /// 16px：**控件内微字形**——Switch 滑块内的勾/图标。
+    ///
+    /// A 级：`SwitchTokens.SelectedIconSize = 16.0d` / `UnselectedIconSize = 16.0d`。
+    /// 别拿它当按钮图标用：按钮是 18（见 [`IconSize::Button`]），两者在官方是两个 token。
+    SwitchThumb,
+    /// 18px：**按钮内前置/后置图标**，也用于 Chip 图标。
+    ///
+    /// A 级：`ButtonDefaults.<clinit>` 里 `bipush 18` → `IconSize = 18.dp`（12b 1.6 引的
+    /// `ButtonDefaults.IconSize=18` 就是这一行）；`AssistChipTokens.IconSize = 18.0d`（12b 13.4）。
+    /// 死令牌说明：`BaselineButtonTokens.IconSize` / `ButtonSmallTokens.IconSize` 都写 20，
+    /// 但 AAR 里没有任何类调用它们的 `getIconSize`（`FilledTonalButtonTokens` 反而是 18）。
+    Button,
+    /// 20px：**目录档，当前无消费**。
+    ///
+    /// ⚠️ 别按名字拿它当导航/列表图标：官方导航轨与列表行的图标是 **24**
+    /// （`AppBarTokens.IconSize = 24.0d`、12b 5.5 / 4.4），实现侧也一直是 24（[`IconSize::Toolbar`]）。
+    /// 标题栏 caption 按钮的 20 不是这一档，见 [`TITLEBAR_CAPTION_ICON_PX`]（那是项目偏离）。
+    Nav,
+    /// 24px：卡片头、工具栏、IconButton、标题栏 caption（官方口径）。
+    ///
+    /// A 级：`SmallIconButtonTokens.IconSize = 24.0d`（12b 2.2 / 16.5）、`AppBarTokens.IconSize = 24.0d`。
+    Toolbar,
+    /// 32px：空态图标块。
+    Empty,
+}
+
+impl IconSize {
+    /// 像素值。
+    pub const fn px(self) -> f32 {
+        match self {
+            IconSize::Inline => 12.0,
+            IconSize::SwitchThumb => 16.0,
+            IconSize::Button => 18.0,
+            IconSize::Nav => 20.0,
+            IconSize::Toolbar => 24.0,
+            IconSize::Empty => 32.0,
+        }
+    }
+
+    /// 全部档位，由小到大。
+    pub const ALL: [IconSize; 6] = [
+        IconSize::Inline,
+        IconSize::SwitchThumb,
+        IconSize::Button,
+        IconSize::Nav,
+        IconSize::Toolbar,
+        IconSize::Empty,
+    ];
+}
+
+/// 标题栏 caption 按钮（最小化 / 最大化 / 关闭）的图标边长——**用户点名的项目偏离**。
+///
+/// 官方 `SmallIconButtonTokens.IconSize = 24.0d`（AAR 字节码，12b 16.5 同值），我们的 24
+/// **本来就是对的**，所以这条不是「对齐规范」，是业主主观调整：用户原话「右上角三个金刚键的
+/// 图标显示稍大了些，能不能在**保持其容器尺寸不变**的前提下把图标改小些」。
+///
+/// 约束：**容器不动**（46×48 仍来自 `LayoutMetrics::titlebar_button_width` /
+/// `titlebar_height`），只缩图标；且这条**只适用于 caption 三键**，不许扩散到导航/卡片/表单的
+/// 24px 图标（那些是 12b 2.2 / 4.4 / 5.5 / 9.6 / 16.5 的判据）。
+pub const TITLEBAR_CAPTION_ICON_PX: f32 = 20.0;
+
+/// 一个图标的几何数据。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Icon {
+    /// 图标种类。
+    pub kind: IconKind,
+    /// SVG path 数据（viewBox `0 0 24 24`，可能含多个子路径）。
+    pub path: &'static str,
+    /// 描边还是填充。
+    pub paint: IconPaint,
+}
+
+impl Icon {
+    /// 表项构造器（只在 [`glyphs`] 的数据表里用）。
+    pub(super) const fn data(kind: IconKind, path: &'static str, paint: IconPaint) -> Self {
+        Self { kind, path, paint }
+    }
+
+    /// 该图标在 `render_px` 下的 **viewBox 单位** stroke-width（[`IconPaint::Fill`] 返回 0）。
+    pub fn stroke_width(self, render_px: f32) -> f32 {
+        match self.paint {
+            IconPaint::Fill => 0.0,
+            IconPaint::Stroke => stroke_width_for(render_px, VISUAL_STROKE_PX),
+        }
+    }
+
+    /// 是否实心填充。
+    pub fn is_filled(self) -> bool {
+        self.paint == IconPaint::Fill
+    }
+
+    /// 路径里是否含曲线命令（适配层可选：纯直线路径走不走曲线细分）。
+    pub fn has_curves(self) -> bool {
+        self.path
+            .bytes()
+            .any(|b| matches!(b, b'C' | b'Q' | b'A' | b'c' | b'q' | b'a'))
+    }
+
+    /// 子路径个数（`M` 命令计数）：适配层可以据此一次性分配 `lyon` 的缓冲区。
+    pub fn subpath_count(self) -> usize {
+        self.path.matches('M').count() + self.path.matches('m').count()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn paths_use_only_svg_commands() {
+        const ALLOWED: &str = "MmLlHhVvAaCcQqZz0123456789 .,-";
+        for kind in IconKind::ALL {
+            let path = kind.icon().path;
+            assert!(path.starts_with('M'), "{} 的路径必须以 M 开头", kind.name());
+            for byte in path.bytes() {
+                assert!(
+                    byte.is_ascii(),
+                    "{} 的路径含非 ASCII（不许用字体字符/中文）",
+                    kind.name()
+                );
+            }
+            for ch in path.chars() {
+                assert!(
+                    ALLOWED.contains(ch),
+                    "{} 的路径含非法字符 {ch:?}",
+                    kind.name()
+                );
+            }
+            // 不许出现科学计数法（能解析但可读性差、易手误）。
+            assert!(
+                !path.contains('e') && !path.contains('E'),
+                "{} 用了科学计数法",
+                kind.name()
+            );
+            assert!(
+                path.matches(' ').count() >= 2,
+                "{} 的坐标分隔异常",
+                kind.name()
+            );
+        }
+    }
+
+    #[test]
+    fn coordinates_stay_inside_the_grid() {
+        for kind in IconKind::ALL {
+            for token in kind.icon().path.split([' ', ',']) {
+                if let Ok(value) = token.parse::<f32>() {
+                    assert!(
+                        (-1.0..=VIEWBOX + 1.0).contains(&value),
+                        "{} 出现 {value}：超出 24 网格（弧半径/控制点也受这条约束）",
+                        kind.name()
+                    );
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn subpaths_are_counted() {
+        assert_eq!(IconKind::Plus.icon().subpath_count(), 2);
+        assert_eq!(IconKind::Instances.icon().subpath_count(), 4);
+        assert_eq!(IconKind::Play.icon().subpath_count(), 1);
+    }
+
+    #[test]
+    fn filled_icons_have_no_stroke() {
+        for kind in IconKind::ALL {
+            let icon = kind.icon();
+            if icon.is_filled() {
+                assert_eq!(icon.stroke_width(20.0), 0.0, "{}", kind.name());
+            } else {
+                assert!(icon.stroke_width(20.0) > 1.0, "{}", kind.name());
+            }
+        }
+    }
+
+    #[test]
+    fn stroke_width_follows_svg_semantics() {
+        // SVG 语义：viewBox 单位 × (render/24) = 视觉像素。
+        assert!((stroke_width_for(20.0, VISUAL_STROKE_PX) - 1.8).abs() < 1.0e-6);
+        assert!((stroke_width_for(16.0, VISUAL_STROKE_PX) - 2.25).abs() < 1.0e-6);
+        assert!((stroke_width_for(24.0, VISUAL_STROKE_PX) - 1.5).abs() < 1.0e-6);
+        assert!((stroke_width_for(48.0, VISUAL_STROKE_PX) - 0.75).abs() < 1.0e-6);
+        // 退化输入不炸、不产生无穷大（Slint 口径的 1.5 绝对值这里不能照抄）。
+        assert_eq!(stroke_width_for(0.0, VISUAL_STROKE_PX), VISUAL_STROKE_PX);
+        assert_eq!(stroke_width_for(-4.0, VISUAL_STROKE_PX), VISUAL_STROKE_PX);
+        // 往返一致。
+        for size in IconSize::ALL {
+            let w = stroke_width_for(size.px(), VISUAL_STROKE_PX);
+            assert!((visual_stroke_px(size.px(), w) - VISUAL_STROKE_PX).abs() < 1.0e-6);
+        }
+    }
+
+    #[test]
+    fn icon_sizes_are_ordered() {
+        let px: Vec<f32> = IconSize::ALL.iter().map(|s| s.px()).collect();
+        for pair in px.windows(2) {
+            assert!(pair[0] < pair[1]);
+        }
+    }
+
+    #[test]
+    fn curve_flags_are_reported() {
+        assert!(IconKind::Settings.icon().has_curves());
+        assert!(!IconKind::Plus.icon().has_curves());
+        assert!(!IconKind::ChevronDown.icon().has_curves());
+    }
+
+    /// 每一档的像素值都被**钉在官方出处**上：改值必须同时改这条测试，改的人会看到出处。
+    ///
+    /// 这不是「断言一个常量等于它自己」——它断言的是「我们读到的官方值」，
+    /// 所以下一个人按 `research/12b` 或按某个 token 类把 18 改回 16/20 时，这条会红并打印出处。
+    #[test]
+    fn icon_sizes_are_pinned_to_their_official_sources() {
+        // A 级：ButtonDefaults.<clinit> 的 `bipush 18` → IconSize = 18.dp
+        //       （`AssistChipTokens.IconSize = 18.0d` 同值）。
+        assert_eq!(
+            IconSize::Button.px(),
+            18.0,
+            "按钮/Chip 图标 18：AAR ButtonDefaults.IconSize（12b 1.6 同值）。\
+             ButtonSmallTokens.IconSize=20 是零消费者的死令牌，不要按它改回去"
+        );
+        // A 级：SwitchTokens.SelectedIconSize / UnselectedIconSize = 16.0d
+        assert_eq!(
+            IconSize::SwitchThumb.px(),
+            16.0,
+            "Switch 滑块图标 16：AAR SwitchTokens.Selected/UnselectedIconSize"
+        );
+        // A 级：SmallIconButtonTokens.IconSize / AppBarTokens.IconSize = 24.0d
+        assert_eq!(
+            IconSize::Toolbar.px(),
+            24.0,
+            "IconButton/标题栏/卡片头 24：AAR SmallIconButtonTokens / AppBarTokens"
+        );
+        // 目录档（当前无消费）：不许被当成 nav 图标用（nav 是 24）。
+        assert_eq!(IconSize::Nav.px(), 20.0, "目录档 20（无消费）");
+        assert_eq!(IconSize::Inline.px(), 12.0);
+        assert_eq!(IconSize::Empty.px(), 32.0);
+    }
+
+    /// 标题栏 caption 的 20 是**项目偏离**，不是规范值；这条把「偏离的是哪两个数」钉住。
+    #[test]
+    fn titlebar_caption_icon_is_a_registered_deviation() {
+        assert_eq!(
+            TITLEBAR_CAPTION_ICON_PX, 20.0,
+            "用户点名的偏离：官方 SmallIconButtonTokens.IconSize = 24，caption 三键缩到 20"
+        );
+        // 绑定成局部变量再过断言：直接比两个常量会被 clippy 判成「常量断言」（assertions_on_constants）。
+        let caption = TITLEBAR_CAPTION_ICON_PX;
+        let official = IconSize::Toolbar.px();
+        assert!(
+            caption < official,
+            "偏离方向是「更小」：{caption} 应 < 官方 {official}；若哪天反了，那就不是用户要的那件事了"
+        );
+        // 20px 渲染时视觉线宽仍是 1.5（SVG 语义），这条防「缩图标顺手把线宽也带细」。
+        let stroke = stroke_width_for(caption, VISUAL_STROKE_PX);
+        assert!(
+            (stroke - 1.8).abs() < 1.0e-6,
+            "20px 渲染应取 1.8 个 viewBox 单位"
+        );
+        assert!((visual_stroke_px(caption, stroke) - VISUAL_STROKE_PX).abs() < 1.0e-6);
+    }
+}
diff --git a/crates/design/src/lib.rs b/crates/design/src/lib.rs
new file mode 100644
index 0000000..f479ac1
--- /dev/null
+++ b/crates/design/src/lib.rs
@@ -0,0 +1,147 @@
+//! # unlucky-design · ULL 设计令牌唯一真源
+//!
+//! 视觉基线 = **Material 3 Expressive**（D26 锁定，风格与框架不再更换）。这个 crate 只装
+//! **渲染无关的数据与纯函数**：色彩角色、排版 ramp、形状刻度、高程、动效参数、图标几何。
+//! 它不依赖任何 UI / 渲染框架（iced / slint / winit / wgpu / gtk …），也不依赖任何第三方 crate，
+//! 因此 iced 迁移、CLI、甚至离屏截图工具都能吃同一套值——这是「UI 整体性」的地基。
+//!
+//! ## 边界（谁负责什么）
+//!
+//! | 层 | 负责 | 不负责 |
+//! |---|---|---|
+//! | `unlucky-design`（本 crate） | 令牌的值与它们之间的纯函数关系（tone→色、type role→字号/行高/字重、shape→半径、spring→时长） | 布局、控件、绘制、字体加载、图片、动画驱动 |
+//! | iced 适配层（后续 mission） | 把令牌翻成 iced 的类型（`Color` / `Length` / `Font` / 动画时钟） | 自己发明新令牌名或新取值 |
+//! | 页面 mission | 消费令牌与 [`component_map`] 的档位约定 | 硬编码色值 / 字号 / 半径 / 时长 |
+//!
+//! ## 分模块
+//!
+//! - [`color`]：M3 语义色角色（49 个）× light/dark 双套 + tone 调色板（**真 HCT**：CAM16 色相/彩度
+//!   + CIELAB `L*`，官方 `ColorSpec2021` tone 表，与官方 Java 实现逐通道对齐——口径见模块文档）
+//! - [`palette`]：配色来源（D38/D40）——图片像素 → 种子 → 完整方案（Monet 式量化 + 打分）、
+//!   内置色卡、三级优先与失败回落、对比度收敛。**只吃已解码的像素**，解码在 `crates/palette-extract`
+//! - [`typography`]：M3 type scale 15 档 + 三平台字体族回退栈
+//! - [`shape`]：M3 Expressive 形状刻度 + shape morph 数据 + [`shape::ComponentRadius`]（微控件圆角层，D32）
+//! - [`elevation`]：elevation level 与 surface tint / surface container 规则
+//! - [`motion`]：时长、easing（可采样）、Expressive 弹簧参数
+//! - [`spacing`]：4px 栅格、骨架尺寸（原 `metrics.slint` 的框架无关部分）、[`stroke::HAIRLINE`]（一像素线）
+//! - [`icons`]：24 网格图标几何（SVG path 字符串）+ 描边语义
+//! - [`component_map`]：组件 → 档位映射表（哪个组件用哪档形状/高程/动效/字体）
+//!   + [`component_map::ComponentMetrics`]（控件内部微几何，与 `LayoutMetrics` 分工见该模块文档）
+//!
+//! ## 最小用法
+//!
+//! ```
+//! use unlucky_design::color::{Role, Scheme, SchemeFlavor};
+//! use unlucky_design::typography::{FontFamily, Platform, TypeRole};
+//!
+//! let light = Scheme::baseline(SchemeFlavor::Light);
+//! let ratio = light.contrast(Role::OnSurface, Role::Surface);
+//! assert!(ratio >= 4.5, "正文对表面必须满足 WCAG AA");
+//!
+//! let title = TypeRole::TitleLarge.style();
+//! assert_eq!(title.size_px, 22.0);
+//! let stack = Platform::current().font_stack(FontFamily::Display);
+//! assert!(!stack.is_empty());
+//! ```
+//!
+//! ## baseline MD3 vs M3 Expressive 差异清单
+//!
+//! 「M3 Expressive」不是「M3 换皮」——它真的加了一批令牌。本 crate 两代都提供，差异如下
+//! （来源等级：**A** = androidx 源码 / 官方 token 文件；**B** = m3.material.io 文档表格；**C** = 社区转述）。
+//!
+//! | 领域 | baseline MD3 | M3 Expressive 新增/不同 | 本 crate 落点 | 等级 |
+//! |---|---|---|---|---|
+//! | 排版 | 15 档 type role，只有 Regular/Medium 两种字重档 | **每档多一条 `*Emphasized`**：字号/行高不变，字重升到 Medium(500) 或 Bold(700)，字距按表微调（display-large −0.2→0、body-large 0.5→0.15、title-medium 0.2→0.15、body-medium 0.2→0.25） | [`typography::TypeRole::emphasized`]（官方值）；[`typography::TypeRole::emphasized_simplified`] 是我们的「只加一档字重」简化规则，**非官方** | A |
+//! | 形状 | ExtraSmall 4 / Small 8 / Medium 12 / Large 16 / **ExtraLarge 28** / Full | 多出 **LargeIncreased 20 / ExtraLargeIncreased 32 / ExtraExtraLarge 48**，并引入 **shape morph**（按下/选中时档位之间弹性过渡） | [`shape::ShapeScale`]（10 档）+ [`shape::ShapeMorph`] + [`component_map`] 的 `morph` 列 | A |
+//! | 动效 | 16 档 duration + 7 条 cubic-bezier easing（时间驱动） | 把弹簧打包成 **standard / expressive 两套方案**，每套各有 spatial（位移，会回弹）与 effects（颜色/透明度，不回弹）× fast/default/slow。standard spatial ζ=0.9（k 1400/700/300），expressive spatial ζ=0.6~0.8（k 800/380/200），effects 两套同值 ζ=1.0（k 3800/1600/800） | [`motion::spring`] 的 **方案 × 类别 × 速度**二维表（12 格，`StandardMotionTokens`/`ExpressiveMotionTokens` 原值）+ 9 个具名常量；duration/easing 两代共用 | A |
+//! | 组件尺寸 | 触控目标 48dp（无障碍下限本来就是 48） | Expressive 把按钮/列表的整体节奏放大（列表项 56/72/88），并明确 48dp 为**可点下限** | [`spacing::LayoutMetrics::DESKTOP`]：`touch_target = 48`（照规范）+ `control_height = 40`（可见高度，上下各 4px 内边距凑满 48）+ `row_height`/`nav_item_height` = 44、`titlebar_height` = 48（M63 §1.4+R13 的桌面档） | A/B |
+//! | 字体 | 只有 400/500/700 的「概念」字重，没规定字体族要覆盖几档 | Expressive 的强调档**真的会要 700**（label-*、title-medium/small），中文字体覆盖差异巨大：雅黑只有 400/700（无 500）、苹方到 600 断（无 700）、Noto/思源可变字体全覆盖 | [`typography::FontFace`] 的 `WeightCoverage`（可变区间 / 静态表）+ [`typography::Platform::resolve_weight`] 纯函数给出「原生 / 最近档 / 合成加粗」三档结论 | B |
+//! | 色彩 | 49 个角色（primary/secondary/tertiary/error 族、surface-container 系、`*-fixed*` 系、outline、inverse、scrim/shadow） | **没有新增颜色角色**；变化在用法：surface-container 系（Lowest…Highest）取代旧的 elevation tint 叠色，表达层级 | [`color::Role`] 全 49 个；[`elevation::Elevation::surface_role`] 给出层级映射，`deprecated_tint_alpha` 保留旧口径作对照 | A |
+//! | 高程 | Level0..5 = 0/1/3/6/8/12dp | 数值不变；组件默认值不同（卡片 L0、菜单 L2、对话框 L3，见 [`component_map`]） | [`elevation::Elevation`] | A |
+//!
+//! ### 两条由此衍生的项目纪律
+//!
+//! 1. **shape morph 是克制的状态信号，不是每屏装饰**：Expressive 官方鼓励「形状即状态」，但
+//!    桌面端信息密度高，圆角到处变会显得凌乱（社区已有人批评控制中心这么做）。本项目的约束是
+//!    **一屏最多 1 处形变、且只用于状态切换信号**；静态元素一律用 [`shape::ShapeScale`] 的固定档。
+//!    [`component_map`] 的 `morph` 列就是允许清单——不在表里的组件不许自己加形变。
+//! 2. **中文字重必须真的有三档**：Expressive 的 700 落在中文字体上，雅黑缺 500、苹方缺 700，
+//!    缺档就走「合成加粗」= 观感廉价。所以字体栈带 `WeightCoverage`，并在
+//!    [`typography::Platform::resolve_weight`] 里把降级路径显式化（合成加粗是最后一档）。
+//!
+//! 已知与文档的 0.05px 级差异：Compose 这一代 `TypeScaleTokens` 的 tracking 与 m3.material.io
+//! 网页表格不同（display-large −0.2 vs −0.25、body-medium 0.2 vs 0.25、title-medium 0.2 vs 0.15），
+//! 本项目**跟 Compose**（那是真正渲染出来的值，A 级）。
+//!
+//! ## 未支持的官方能力（gap 登记，不要以为已经有了）
+//!
+//! - **对比度等级**：Android 16 的「默认 / 中 / 高」三档对比度本 crate **不支持**。将来扩法是
+//!   **按等级偏移角色 tone 表**（例如高对比把 `on-*` 与承载色的 tone 差拉大 5~10），
+//!   而不是新增一批角色——`Role` 的数量保持 49 不变，`Scheme` 多一个 `contrast_level` 维度。
+//!   （M63 的 G4 只说「高对比模式走 CPU 档」，那是渲染档位，不等价于支持对比度等级。）
+//! - **动态壁纸取色**：M3 的多色种子派生（一张图出 4 个 source color、`*_container` 各自换色相）
+//!   未实现。本模块只取**一个**主色种子（D38 的产品口径：整套主题一个强调色），
+//!   实现落在 [`palette`]。
+//! - **M3 的 elevation tint 叠色**：现行 M3 已改用 surface-container 表达层级，旧的
+//!   `deprecated_tint_alpha()` 只为读旧稿保留。
+
+#![forbid(unsafe_code)]
+
+pub mod color;
+pub mod component_map;
+pub mod elevation;
+pub mod icons;
+pub mod motion;
+pub mod palette;
+pub mod shape;
+pub mod spacing;
+pub mod typography;
+
+pub use color::{Color, Role, Scheme, SchemeFlavor};
+pub use motion::MotionScale;
+pub use palette::{Card, CardKey, Level as SourceLevel, Provenance, Seed};
+pub use spacing::stroke;
+pub use typography::TypeRole;
+
+/// 设计令牌的整体入口：一份「当前该长什么样」的聚合快照。
+///
+/// iced 适配层只持有这个结构（深浅切换 = 重新 `DesignTokens::baseline(mode)`），
+/// 不要在适配层里缓存散装色值——那样深浅热切会有一半画对一半画错。
+#[derive(Debug, Clone, Copy)]
+pub struct DesignTokens {
+    /// 当前深浅模式。
+    pub flavor: SchemeFlavor,
+    /// 当前模式的 M3 语义色角色全表。
+    pub colors: Scheme,
+    /// 动效时长的全局缩放（`1.0` = 标准；用户关掉动画时适配层传 `0.0`）。
+    pub motion_scale: MotionScale,
+}
+
+impl DesignTokens {
+    /// 按模式给一套**产品默认**令牌：种子 `#3C8DBC`（M70 ④ 天蓝，用户 2026-11-01 拍板）
+    /// + 中性彩度 12，即 `color::palettes::DEFAULT_SEED` / `DEFAULT_NEUTRAL_CHROMA`。
+    ///
+    /// 想要**官方 M3 baseline** 口径（种子 `#6750A4` + 中性彩度 6 / neutral-variant 8）请走
+    /// `color::Scheme::official_baseline(flavor)`——两条路径的算法完全相同，只差入参。
+    pub fn baseline(flavor: SchemeFlavor) -> Self {
+        Self {
+            flavor,
+            colors: Scheme::baseline(flavor),
+            motion_scale: MotionScale::STANDARD,
+        }
+    }
+
+    /// 按用户强调色重建一套令牌（表面中性色仍走 baseline，强调色只驱动 primary/secondary/tertiary）。
+    pub fn with_accent(flavor: SchemeFlavor, accent: Color) -> Self {
+        Self {
+            flavor,
+            colors: Scheme::from_accent(flavor, accent),
+            motion_scale: MotionScale::STANDARD,
+        }
+    }
+
+    /// 便捷取色：`tokens.color(Role::Surface)`。
+    pub fn color(&self, role: Role) -> Color {
+        self.colors.get(role)
+    }
+}
diff --git a/crates/design/src/motion/mod.rs b/crates/design/src/motion/mod.rs
new file mode 100644
index 0000000..df59e11
--- /dev/null
+++ b/crates/design/src/motion/mod.rs
@@ -0,0 +1,308 @@
+//! 动效令牌：时长、缓动（可采样）、M3 Expressive 弹簧参数。
+//!
+//! 三件东西分开表达，因为适配层要的接口不同：
+//! - [`DurationToken`]：M3 的 short/medium/long/extra-long 十六档，给「固定时长 + easing」用；
+//! - [`Easing`]：cubic-bezier 曲线，纯函数采样（适配层自己决定帧率）；
+//! - [`Spring`]（见 [`spring`]）：Expressive 的物理参数（stiffness/damping/mass），
+//!   可用于实时求解或预估时长。
+//!
+//! **CPU / 减少动效路径**：把 [`MotionScale`] 设成 [`MotionScale::NONE`]，
+//! 所有时长归零、`Easing::sample` 仍返回 0/1 端值（适配层按 `t >= 1` 直接落终态）。
+
+mod spring;
+
+pub use spring::{
+    spring, MotionScale, MotionSchemeKind, Spring, SpringCategory, SpringSpeed,
+    SPRING_EFFECTS_DEFAULT, SPRING_EFFECTS_FAST, SPRING_EFFECTS_SLOW,
+    SPRING_EXPRESSIVE_SPATIAL_DEFAULT, SPRING_EXPRESSIVE_SPATIAL_FAST,
+    SPRING_EXPRESSIVE_SPATIAL_SLOW, SPRING_STANDARD_SPATIAL_DEFAULT, SPRING_STANDARD_SPATIAL_FAST,
+    SPRING_STANDARD_SPATIAL_SLOW,
+};
+
+/// 动效时长档位（M3 动效令牌，单位毫秒）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum DurationToken {
+    /// 50ms：最小状态回弹。
+    Short1,
+    /// 100ms：小图标/勾选。
+    Short2,
+    /// 150ms：开关、小尺寸 fade。
+    Short3,
+    /// 200ms：按钮状态、hover。
+    Short4,
+    /// 250ms：小卡片展开。
+    Medium1,
+    /// 300ms：导航指示条、tab 切换。
+    Medium2,
+    /// 350ms：卡片展开、列表重排。
+    Medium3,
+    /// 400ms：面板开合。
+    Medium4,
+    /// 450ms：页面切换。
+    Long1,
+    /// 500ms：大面板进出。
+    Long2,
+    /// 550ms：全屏浮层。
+    Long3,
+    /// 600ms：对话框进出。
+    Long4,
+    /// 700ms：结构化过渡。
+    ExtraLong1,
+    /// 800ms：结构化过渡。
+    ExtraLong2,
+    /// 900ms：结构化过渡。
+    ExtraLong3,
+    /// 1000ms：整屏形变（shape morph 的慢档）。
+    ExtraLong4,
+}
+
+impl DurationToken {
+    /// 毫秒值。
+    pub const fn ms(self) -> u32 {
+        match self {
+            DurationToken::Short1 => 50,
+            DurationToken::Short2 => 100,
+            DurationToken::Short3 => 150,
+            DurationToken::Short4 => 200,
+            DurationToken::Medium1 => 250,
+            DurationToken::Medium2 => 300,
+            DurationToken::Medium3 => 350,
+            DurationToken::Medium4 => 400,
+            DurationToken::Long1 => 450,
+            DurationToken::Long2 => 500,
+            DurationToken::Long3 => 550,
+            DurationToken::Long4 => 600,
+            DurationToken::ExtraLong1 => 700,
+            DurationToken::ExtraLong2 => 800,
+            DurationToken::ExtraLong3 => 900,
+            DurationToken::ExtraLong4 => 1000,
+        }
+    }
+
+    /// 稳定字符串名（`short1` … `extra-long4`），写配置与日志用。
+    pub const fn name(self) -> &'static str {
+        match self {
+            DurationToken::Short1 => "short1",
+            DurationToken::Short2 => "short2",
+            DurationToken::Short3 => "short3",
+            DurationToken::Short4 => "short4",
+            DurationToken::Medium1 => "medium1",
+            DurationToken::Medium2 => "medium2",
+            DurationToken::Medium3 => "medium3",
+            DurationToken::Medium4 => "medium4",
+            DurationToken::Long1 => "long1",
+            DurationToken::Long2 => "long2",
+            DurationToken::Long3 => "long3",
+            DurationToken::Long4 => "long4",
+            DurationToken::ExtraLong1 => "extra-long1",
+            DurationToken::ExtraLong2 => "extra-long2",
+            DurationToken::ExtraLong3 => "extra-long3",
+            DurationToken::ExtraLong4 => "extra-long4",
+        }
+    }
+}
+
+/// 三次贝塞尔缓动曲线（CSS `cubic-bezier` 同样的参数含义）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct CubicBezier {
+    /// 控制点 1 的 x（0..1）。
+    pub x1: f32,
+    /// 控制点 1 的 y。
+    pub y1: f32,
+    /// 控制点 2 的 x（0..1）。
+    pub x2: f32,
+    /// 控制点 2 的 y。
+    pub y2: f32,
+}
+
+impl CubicBezier {
+    /// 线性。
+    pub const LINEAR: Self = Self {
+        x1: 0.0,
+        y1: 0.0,
+        x2: 1.0,
+        y2: 1.0,
+    };
+
+    /// 给定时间参数 `t`（0..1），返回进度（0..1，标准曲线不越界）。
+    pub fn sample(self, t: f32) -> f32 {
+        let t = t.clamp(0.0, 1.0);
+        if t == 0.0 || t == 1.0 {
+            return t;
+        }
+        // 二分求 x(s) = t 的曲线参数 s，再取 y(s)。
+        let mut lo = 0.0_f32;
+        let mut hi = 1.0_f32;
+        let mut s = t;
+        for _ in 0..24 {
+            s = 0.5 * (lo + hi);
+            let x = bezier_axis(self.x1, self.x2, s);
+            if x < t {
+                lo = s;
+            } else {
+                hi = s;
+            }
+        }
+        bezier_axis(self.y1, self.y2, s)
+    }
+}
+
+/// 一维三次贝塞尔：端点固定为 0/1，控制点为 `c1`/`c2`。
+fn bezier_axis(c1: f32, c2: f32, s: f32) -> f32 {
+    let u = 1.0 - s;
+    3.0 * u * u * s * c1 + 3.0 * u * s * s * c2 + s * s * s
+}
+
+/// M3 缓动档位（值取自 Material 动效令牌）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Easing {
+    /// 线性（进度指示器）。
+    Linear,
+    /// 标准：起止都平滑。
+    Standard,
+    /// 标准减速：进场（出现在屏幕上）。
+    StandardDecelerate,
+    /// 标准加速：退场。
+    StandardAccelerate,
+    /// 强调：注意力转移的主曲线。
+    Emphasized,
+    /// 强调减速：强调类进场。
+    EmphasizedDecelerate,
+    /// 强调加速：强调类退场。
+    EmphasizedAccelerate,
+}
+
+impl Easing {
+    /// 曲线参数。
+    pub const fn curve(self) -> CubicBezier {
+        match self {
+            Easing::Linear => CubicBezier::LINEAR,
+            Easing::Standard | Easing::Emphasized => CubicBezier {
+                x1: 0.2,
+                y1: 0.0,
+                x2: 0.0,
+                y2: 1.0,
+            },
+            Easing::StandardDecelerate => CubicBezier {
+                x1: 0.0,
+                y1: 0.0,
+                x2: 0.0,
+                y2: 1.0,
+            },
+            Easing::StandardAccelerate => CubicBezier {
+                x1: 0.3,
+                y1: 0.0,
+                x2: 1.0,
+                y2: 1.0,
+            },
+            Easing::EmphasizedDecelerate => CubicBezier {
+                x1: 0.05,
+                y1: 0.7,
+                x2: 0.1,
+                y2: 1.0,
+            },
+            Easing::EmphasizedAccelerate => CubicBezier {
+                x1: 0.3,
+                y1: 0.0,
+                x2: 0.8,
+                y2: 0.15,
+            },
+        }
+    }
+
+    /// 采样：`t` 0..1 → 进度 0..1。
+    pub fn sample(self, t: f32) -> f32 {
+        self.curve().sample(t)
+    }
+
+    /// 该曲线搭配的常用时长（我们的组件映射口径，非规范值）。
+    pub const fn default_duration(self) -> DurationToken {
+        match self {
+            Easing::Linear => DurationToken::Long2,
+            _ => DurationToken::Medium2,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const ALL_EASINGS: [Easing; 7] = [
+        Easing::Linear,
+        Easing::Standard,
+        Easing::StandardDecelerate,
+        Easing::StandardAccelerate,
+        Easing::Emphasized,
+        Easing::EmphasizedDecelerate,
+        Easing::EmphasizedAccelerate,
+    ];
+
+    #[test]
+    fn durations_are_monotone() {
+        let ladder = [
+            DurationToken::Short1,
+            DurationToken::Short2,
+            DurationToken::Short3,
+            DurationToken::Short4,
+            DurationToken::Medium1,
+            DurationToken::Medium2,
+            DurationToken::Medium3,
+            DurationToken::Medium4,
+            DurationToken::Long1,
+            DurationToken::Long2,
+            DurationToken::Long3,
+            DurationToken::Long4,
+            DurationToken::ExtraLong1,
+            DurationToken::ExtraLong2,
+            DurationToken::ExtraLong3,
+            DurationToken::ExtraLong4,
+        ];
+        assert_eq!(ladder.len(), 16);
+        for pair in ladder.windows(2) {
+            assert!(pair[0].ms() < pair[1].ms());
+        }
+        assert_eq!(DurationToken::Short1.ms(), 50);
+        assert_eq!(DurationToken::ExtraLong4.ms(), 1000);
+        // 名字唯一
+        let mut names = std::collections::BTreeSet::new();
+        for token in ladder {
+            assert!(names.insert(token.name()), "时长名重复：{}", token.name());
+        }
+    }
+
+    #[test]
+    fn easing_hits_endpoints_and_stays_in_range() {
+        for easing in ALL_EASINGS {
+            assert!(
+                (easing.sample(0.0) - 0.0).abs() < 1.0e-6,
+                "{easing:?} 起点不为 0"
+            );
+            assert!(
+                (easing.sample(1.0) - 1.0).abs() < 1.0e-6,
+                "{easing:?} 终点不为 1"
+            );
+            let mut prev = 0.0;
+            for step in 1..=20 {
+                let v = easing.sample(step as f32 / 20.0);
+                assert!((-0.001..=1.001).contains(&v), "{easing:?} 采样越界：{v}");
+                assert!(v + 1.0e-3 >= prev, "{easing:?} 采样非单调：{prev} → {v}");
+                prev = v;
+            }
+        }
+    }
+
+    #[test]
+    fn emphasized_decelerate_is_faster_early_than_accelerate() {
+        let early_decel = Easing::EmphasizedDecelerate.sample(0.25);
+        let early_accel = Easing::EmphasizedAccelerate.sample(0.25);
+        assert!(early_decel > early_accel);
+    }
+
+    #[test]
+    fn default_durations_are_registered_tokens() {
+        for easing in ALL_EASINGS {
+            assert!(easing.default_duration().ms() >= 250);
+        }
+    }
+}
diff --git a/crates/design/src/motion/spring.rs b/crates/design/src/motion/spring.rs
new file mode 100644
index 0000000..6baa0c0
--- /dev/null
+++ b/crates/design/src/motion/spring.rs
@@ -0,0 +1,380 @@
+//! 弹簧参数（M3 Expressive 动效的物理表达）与动效时长缩放。
+//!
+//! **来源 A 级**：`androidx.compose.material3.tokens.ExpressiveMotionTokens`（v0_14_0）给出六组
+//! `Spring{Damping, Stiffness}`——注意 Compose 的 `Damping` 是**阻尼比 ζ**（不是绝对阻尼系数），
+//! 所以本模块的 [`Spring`] 也按 (stiffness, damping_ratio, mass) 存，两者可直接对照。
+//! 阶跃响应用标准二阶系统闭式解（欠阻尼 / 临界 / 过阻尼三分支），是纯数学、无状态。
+
+/// 弹簧参数（Compose 口径：刚度 + 阻尼比 + 质量）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Spring {
+    /// 刚度 k（越大越快）。
+    pub stiffness: f32,
+    /// 阻尼比 ζ（1.0 = 临界阻尼，< 1 会轻微弹过）。
+    pub damping_ratio: f32,
+    /// 质量 m。
+    pub mass: f32,
+}
+
+impl Spring {
+    /// 按 M3 令牌口径构造（刚度 + 阻尼比 + 质量）。
+    pub const fn from_ratio(stiffness: f32, damping_ratio: f32, mass: f32) -> Self {
+        Self {
+            stiffness,
+            damping_ratio,
+            mass,
+        }
+    }
+
+    /// 自然角频率 ωn（rad/s）。
+    pub fn natural_frequency(self) -> f32 {
+        (self.stiffness / self.mass).sqrt()
+    }
+
+    /// 绝对阻尼系数 c = 2·ζ·√(k·m)（需要喂给「阻尼系数」式积分器时用）。
+    pub fn damping_coefficient(self) -> f32 {
+        2.0 * self.damping_ratio * (self.stiffness * self.mass).sqrt()
+    }
+
+    /// 阶跃响应：`t_ms` 毫秒后的进度（0..1，欠阻尼时会轻微超过 1 = 回弹）。
+    pub fn sample(self, t_ms: f32) -> f32 {
+        if t_ms <= 0.0 {
+            return 0.0;
+        }
+        let t = t_ms / 1000.0;
+        let wn = self.natural_frequency();
+        let zeta = self.damping_ratio;
+        if wn <= 0.0 {
+            return 1.0;
+        }
+        if zeta < 1.0 {
+            let wd = wn * (1.0 - zeta * zeta).sqrt();
+            let decay = (-zeta * wn * t).exp();
+            1.0 - decay * ((wd * t).cos() + (zeta * wn / wd) * (wd * t).sin())
+        } else if (zeta - 1.0).abs() < 1.0e-4 {
+            let decay = (-wn * t).exp();
+            1.0 - decay * (1.0 + wn * t)
+        } else {
+            let root = (zeta * zeta - 1.0).sqrt();
+            let r1 = -wn * (zeta - root);
+            let r2 = -wn * (zeta + root);
+            let denom = r2 - r1;
+            if denom.abs() < f32::EPSILON {
+                return 1.0;
+            }
+            1.0 - (r2 * (r1 * t).exp() - r1 * (r2 * t).exp()) / denom
+        }
+    }
+
+    /// 收敛到 `threshold`（0.1% 是常用的「停下来」判定）所需毫秒数。
+    pub fn settle_ms(self, threshold: f32) -> f32 {
+        let wn = self.natural_frequency();
+        let zeta = self.damping_ratio;
+        if wn <= 0.0 {
+            return 0.0;
+        }
+        let thr = threshold.clamp(1.0e-6, 0.5);
+        let seconds = if zeta < 1.0 {
+            let wd = (1.0 - zeta * zeta).sqrt().max(1.0e-4);
+            -(thr * wd).ln() / (zeta * wn)
+        } else if (zeta - 1.0).abs() < 1.0e-4 {
+            -(thr).ln() / wn
+        } else {
+            let root = (zeta * zeta - 1.0).sqrt();
+            let slow = wn * (zeta - root);
+            -(thr).ln() / slow
+        };
+        (seconds * 1000.0).max(0.0)
+    }
+}
+
+/// 动效方案（Expressive 把弹簧打包成 standard / expressive **两套**，不是一组）。
+///
+/// - [`MotionSchemeKind::Standard`]：保守、几乎不弹（spatial ζ=0.9）；
+/// - [`MotionSchemeKind::Expressive`]：D26 的视觉基线，回弹明显（spatial ζ=0.6~0.8）。
+///
+/// `effects`（透明度/颜色类）在两套方案里数值相同——效应类不该有可见回弹。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum MotionSchemeKind {
+    /// 标准方案（保守）。
+    Standard,
+    /// Expressive 方案（本项目默认）。
+    Expressive,
+}
+
+/// 弹簧类别：空间类管**位移/尺寸**，效应类管**颜色/透明度**。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum SpringCategory {
+    /// 位移/尺寸（会产生可见回弹）。
+    Spatial,
+    /// 颜色/透明度（不允许过冲）。
+    Effects,
+}
+
+/// 弹簧速度档。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum SpringSpeed {
+    /// 快速：hover/press、小元素。
+    Fast,
+    /// 默认：面板、卡片、按下形变。
+    Default,
+    /// 慢速：大位移（>120px 的面板/抽屉）。
+    Slow,
+}
+
+/// 二维表查询：`方案 × 类别 × 速度 → 弹簧`（A 级：`StandardMotionTokens` 与
+/// `ExpressiveMotionTokens`，经 `MotionScheme.standard()/expressive()` 组装）。
+pub const fn spring(
+    scheme: MotionSchemeKind,
+    category: SpringCategory,
+    speed: SpringSpeed,
+) -> Spring {
+    use MotionSchemeKind::{Expressive, Standard};
+    use SpringCategory::{Effects, Spatial};
+    use SpringSpeed::{Default, Fast, Slow};
+    match (scheme, category, speed) {
+        (Standard, Spatial, Fast) => Spring::from_ratio(1400.0, 0.9, 1.0),
+        (Standard, Spatial, Default) => Spring::from_ratio(700.0, 0.9, 1.0),
+        (Standard, Spatial, Slow) => Spring::from_ratio(300.0, 0.9, 1.0),
+        (Expressive, Spatial, Fast) => Spring::from_ratio(800.0, 0.6, 1.0),
+        (Expressive, Spatial, Default) => Spring::from_ratio(380.0, 0.8, 1.0),
+        (Expressive, Spatial, Slow) => Spring::from_ratio(200.0, 0.8, 1.0),
+        // effects 两套同值：ζ=1.0（临界阻尼，不过冲）。
+        (_, Effects, Fast) => Spring::from_ratio(3800.0, 1.0, 1.0),
+        (_, Effects, Default) => Spring::from_ratio(1600.0, 1.0, 1.0),
+        (_, Effects, Slow) => Spring::from_ratio(800.0, 1.0, 1.0),
+    }
+}
+
+/// 标准方案 · 空间 · 快速。
+pub const SPRING_STANDARD_SPATIAL_FAST: Spring = spring(
+    MotionSchemeKind::Standard,
+    SpringCategory::Spatial,
+    SpringSpeed::Fast,
+);
+/// 标准方案 · 空间 · 默认。
+pub const SPRING_STANDARD_SPATIAL_DEFAULT: Spring = spring(
+    MotionSchemeKind::Standard,
+    SpringCategory::Spatial,
+    SpringSpeed::Default,
+);
+/// 标准方案 · 空间 · 慢速。
+pub const SPRING_STANDARD_SPATIAL_SLOW: Spring = spring(
+    MotionSchemeKind::Standard,
+    SpringCategory::Spatial,
+    SpringSpeed::Slow,
+);
+/// Expressive 方案 · 空间 · 快速（D26 基线的默认选择）。
+pub const SPRING_EXPRESSIVE_SPATIAL_FAST: Spring = spring(
+    MotionSchemeKind::Expressive,
+    SpringCategory::Spatial,
+    SpringSpeed::Fast,
+);
+/// Expressive 方案 · 空间 · 默认：面板、卡片、按下形变。
+pub const SPRING_EXPRESSIVE_SPATIAL_DEFAULT: Spring = spring(
+    MotionSchemeKind::Expressive,
+    SpringCategory::Spatial,
+    SpringSpeed::Default,
+);
+/// Expressive 方案 · 空间 · 慢速：大位移（>120px）。
+pub const SPRING_EXPRESSIVE_SPATIAL_SLOW: Spring = spring(
+    MotionSchemeKind::Expressive,
+    SpringCategory::Spatial,
+    SpringSpeed::Slow,
+);
+/// 效应类 · 快速（两套方案同值）：hover/press 颜色。
+pub const SPRING_EFFECTS_FAST: Spring = spring(
+    MotionSchemeKind::Expressive,
+    SpringCategory::Effects,
+    SpringSpeed::Fast,
+);
+/// 效应类 · 默认（两套方案同值）。
+pub const SPRING_EFFECTS_DEFAULT: Spring = spring(
+    MotionSchemeKind::Expressive,
+    SpringCategory::Effects,
+    SpringSpeed::Default,
+);
+/// 效应类 · 慢速（两套方案同值）。
+pub const SPRING_EFFECTS_SLOW: Spring = spring(
+    MotionSchemeKind::Expressive,
+    SpringCategory::Effects,
+    SpringSpeed::Slow,
+);
+
+/// 动效时长的全局缩放（用户「减少动效」/CPU 路径关动画时用）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct MotionScale {
+    factor: f32,
+}
+
+impl MotionScale {
+    /// 标准（1.0）。
+    pub const STANDARD: MotionScale = MotionScale { factor: 1.0 };
+    /// 关闭动效（时长归零；适配层应直接落终态）。
+    pub const NONE: MotionScale = MotionScale { factor: 0.0 };
+    /// 半速（弱动效机器/低帧率兜底）。
+    pub const HALF: MotionScale = MotionScale { factor: 0.5 };
+
+    /// 自定义缩放（夹取到 0.0..=1.0；不放大，避免慢到不可用）。
+    pub fn new(factor: f32) -> Self {
+        Self {
+            factor: factor.clamp(0.0, 1.0),
+        }
+    }
+
+    /// 缩放系数。
+    pub fn factor(self) -> f32 {
+        self.factor
+    }
+
+    /// 是否完全关闭（适配层据此跳过动画）。
+    pub fn is_off(self) -> bool {
+        self.factor <= 0.0
+    }
+
+    /// 把某一档时长换算成实际毫秒。
+    pub fn ms(self, token: super::DurationToken) -> f32 {
+        token.ms() as f32 * self.factor
+    }
+
+    /// 把弹簧的收敛时间换算成实际毫秒。
+    pub fn spring_ms(self, spring: Spring) -> f32 {
+        spring.settle_ms(0.001) * self.factor
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::motion::DurationToken;
+
+    const PRESETS: [Spring; 9] = [
+        SPRING_STANDARD_SPATIAL_FAST,
+        SPRING_STANDARD_SPATIAL_DEFAULT,
+        SPRING_STANDARD_SPATIAL_SLOW,
+        SPRING_EXPRESSIVE_SPATIAL_FAST,
+        SPRING_EXPRESSIVE_SPATIAL_DEFAULT,
+        SPRING_EXPRESSIVE_SPATIAL_SLOW,
+        SPRING_EFFECTS_FAST,
+        SPRING_EFFECTS_DEFAULT,
+        SPRING_EFFECTS_SLOW,
+    ];
+
+    #[test]
+    fn every_cell_of_the_two_dimensional_table_resolves() {
+        for scheme in [MotionSchemeKind::Standard, MotionSchemeKind::Expressive] {
+            for category in [SpringCategory::Spatial, SpringCategory::Effects] {
+                for speed in [SpringSpeed::Fast, SpringSpeed::Default, SpringSpeed::Slow] {
+                    let spring = spring(scheme, category, speed);
+                    assert!(spring.stiffness > 0.0);
+                    assert!(spring.damping_ratio > 0.0);
+                }
+            }
+        }
+        // effects 两套方案同值（效应类不该有可见回弹差异）。
+        for speed in [SpringSpeed::Fast, SpringSpeed::Default, SpringSpeed::Slow] {
+            assert_eq!(
+                spring(MotionSchemeKind::Standard, SpringCategory::Effects, speed),
+                spring(MotionSchemeKind::Expressive, SpringCategory::Effects, speed)
+            );
+        }
+        // expressive 的空间类更弹（阻尼比更低）。
+        for speed in [SpringSpeed::Fast, SpringSpeed::Default, SpringSpeed::Slow] {
+            assert!(
+                spring(MotionSchemeKind::Expressive, SpringCategory::Spatial, speed).damping_ratio
+                    < spring(MotionSchemeKind::Standard, SpringCategory::Spatial, speed)
+                        .damping_ratio
+            );
+        }
+    }
+
+    #[test]
+    fn spring_presets_behave() {
+        for spring in PRESETS {
+            assert_eq!(spring.sample(0.0), 0.0);
+            let settle = spring.settle_ms(0.001);
+            assert!(
+                (60.0..1500.0).contains(&settle),
+                "收敛时间 {settle}ms 不合理（k={} ζ={}）",
+                spring.stiffness,
+                spring.damping_ratio
+            );
+            let end = spring.sample(settle);
+            assert!((end - 1.0).abs() < 0.01, "收敛后应回到 1.0，实测 {end}");
+        }
+    }
+
+    #[test]
+    fn effects_presets_are_critically_damped_and_never_overshoot() {
+        for spring in [
+            SPRING_EFFECTS_FAST,
+            SPRING_EFFECTS_DEFAULT,
+            SPRING_EFFECTS_SLOW,
+        ] {
+            assert!((spring.damping_ratio - 1.0).abs() < 1.0e-6);
+            for step in 1..=60 {
+                let v = spring.sample(step as f32 * 5.0);
+                assert!(v <= 1.0 + 1.0e-3, "效应类弹簧不应过冲：{v}");
+            }
+        }
+    }
+
+    #[test]
+    fn spatial_presets_overdamp_into_settle_without_wild_overshoot() {
+        for spring in [
+            SPRING_EXPRESSIVE_SPATIAL_FAST,
+            SPRING_EXPRESSIVE_SPATIAL_DEFAULT,
+            SPRING_EXPRESSIVE_SPATIAL_SLOW,
+        ] {
+            assert!(
+                spring.damping_ratio < 1.0,
+                "空间类弹簧欠阻尼（允许轻微过冲）"
+            );
+            let mut peak: f32 = 0.0;
+            for step in 1..=200 {
+                peak = peak.max(spring.sample(step as f32 * 2.0));
+            }
+            assert!(peak < 1.15, "过冲 {peak} 太大");
+        }
+    }
+
+    #[test]
+    fn critically_damped_spring_does_not_overshoot() {
+        let wn = SPRING_EXPRESSIVE_SPATIAL_DEFAULT.natural_frequency();
+        let critical = Spring::from_ratio(wn * wn, 1.0, 1.0);
+        for step in 1..=40 {
+            let v = critical.sample(step as f32 * 5.0);
+            assert!(v <= 1.0 + 1.0e-3, "临界阻尼不应过冲：{v}");
+        }
+    }
+
+    #[test]
+    fn overdamped_spring_converges_slowly_without_overshoot() {
+        let wn = SPRING_EXPRESSIVE_SPATIAL_DEFAULT.natural_frequency();
+        let over = Spring::from_ratio(wn * wn, 2.0, 1.0);
+        let settle = over.settle_ms(0.001);
+        assert!((over.sample(settle) - 1.0).abs() < 0.01);
+        for step in 1..=40 {
+            assert!(over.sample(step as f32 * 10.0) <= 1.0 + 1.0e-3);
+        }
+    }
+
+    #[test]
+    fn damping_coefficient_matches_ratio() {
+        let spring = SPRING_EXPRESSIVE_SPATIAL_DEFAULT;
+        let c = spring.damping_coefficient();
+        let zeta = c / (2.0 * (spring.stiffness * spring.mass).sqrt());
+        assert!((zeta - spring.damping_ratio).abs() < 1.0e-5);
+    }
+
+    #[test]
+    fn motion_scale_scales_or_kills_duration() {
+        assert_eq!(MotionScale::STANDARD.ms(DurationToken::Medium2), 300.0);
+        assert_eq!(MotionScale::HALF.ms(DurationToken::Medium2), 150.0);
+        assert_eq!(MotionScale::NONE.ms(DurationToken::Medium2), 0.0);
+        assert!(MotionScale::NONE.is_off());
+        assert_eq!(MotionScale::new(5.0).factor(), 1.0);
+        assert_eq!(MotionScale::new(-1.0).factor(), 0.0);
+        assert!(MotionScale::STANDARD.spring_ms(SPRING_EXPRESSIVE_SPATIAL_DEFAULT) > 0.0);
+    }
+}
diff --git a/crates/design/src/palette/card.rs b/crates/design/src/palette/card.rs
new file mode 100644
index 0000000..30104aa
--- /dev/null
+++ b/crates/design/src/palette/card.rs
@@ -0,0 +1,340 @@
+//! 内置色卡（D38 第三级）：用户在「关闭莫奈取色」时手动选的那几张。
+//!
+//! ## `key` 是持久化键，命名就此定死
+//!
+//! 每张卡的 [`Card::key`] 会被写进用户设置（settings 里存字符串），**改了就等于把用户的选择
+//! 抹成出厂默认**。所以：
+//!
+//! - 只用小写 ASCII + 单段单词，不带动词、不带颜色数值（`sky`，不是 `blue_3c8dbc`）；
+//! - 显示名（[`Card::name`]）可以改、可以本地化，`key` 不许改；
+//! - 新卡只能**追加**，旧卡永不删除（删了老用户的选择会静默失效 → 见
+//!   [`CardKey::from_key`] 的回落口径）；
+//! - `card.rs` 的 `card_keys_are_stable_and_unique` 把 8 个 key 逐字钉住——谁改谁红
+//!   （测试就在本文件末尾的 `tests` 模块里，没有独立的 `palette/tests.rs`）。
+//!
+//! ## 换卡只换强调色：中性色相固定（D43）
+//!
+//! 八张卡共用**一个**中性色相 [`NEUTRAL_HUE_DEG`]（= 出厂默认种子 `#3C8DBC` 的 CAM16 色相
+//! 239.51°，出处见该常量的文档），中性彩度都取 [`DEFAULT_NEUTRAL_CHROMA`]（12，M70 的「浅冷」口径）。
+//! 于是这份契约是逐值可验的：
+//!
+//! - **表面与描边**（`surface` / `surface-container-*` / `background` / `inverse-surface` /
+//!   `outline` / `outline-variant` / `surface-variant`）**八张卡逐值相同**——切卡不动窗口底色；
+//! - **只有强调族**（`primary` / `secondary` / `tertiary` 及其 container、`on-*`、`inverse-primary`、
+//!   `*-fixed*`、`surface-tint`）跟着卡走；
+//! - **天蓝卡（出厂默认）与 [`crate::color::Scheme::baseline`] 逐值相同**：固定的中性色相本来
+//!   就等于天蓝档的中性色相，所以这是「沿用」而非「另选一个冷调」（M70 定案的不动点）。
+//!
+//! 为什么不再让中性色跟着种子染色：TonalSpot 下八张卡的中性色相 = 种子色相，浅色档 `surface`
+//! 实测 CAM16 彩度从 **1.29（rose）跨到 12.03（teal）**——tone 98 处暖相色域装不下彩度 12，
+//! 同一个「请求值」在暖相上只兑现 1.29。9 倍的底色跳变让用户在设置页逐张试色时觉得「每张卡
+//! 都像换了个应用」（M87 实测，D43 据此定案）。现在八张卡的 `surface` 是同一个色值，
+//! 那 9 倍差由 `tests/card_neutral.rs` 断言为 1 倍。
+//!
+//! ⚠️ **只对色卡路径成立**：动态取色（启动器背景图 / 桌面壁纸）仍然让中性色跟着图像种子染色，
+//! 那是用户要的 Monet 体验（D38）。见 [`super::resolve`] 的 `try_level`：两条路径刻意不同，
+//! 别「统一处理」（`tests/card_neutral.rs` 有反证用例）。
+//!
+//! ## 卡与取色的关系（D38）
+//!
+//! 取色成功时，**当前选中的卡仍然参与生成**，但只贡献中性**彩度**（表面色的浓淡）；
+//! 色相由图像种子决定。所以卡片不是「只在第三级才用到」的备胎，它的固定中性色相
+//! **不会**出现在取色方案里。
+
+use super::wcag;
+use crate::color::{
+    Color, Palettes, Scheme, SchemeFlavor, DEFAULT_NEUTRAL_CHROMA, NEUTRAL_HUE_DEG,
+};
+
+/// 一张内置色卡。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Card {
+    /// 持久化键（写进用户设置，**不许改**）。
+    pub key: &'static str,
+    /// 显示名（可改、可本地化）。
+    pub name: &'static str,
+    /// 种子色（只贡献色相；Tonal Spot 会把彩度收到 36）。
+    pub seed: Color,
+    /// 中性调色板彩度（表面色的浓淡；色相固定为 [`NEUTRAL_HUE_DEG`]，见模块文档的 D43 契约）。
+    pub neutral_chroma: f64,
+}
+
+impl Card {
+    /// 用这张卡生成一套方案（与取色路径同一条生成器，只差两处入参：中性色相固定为
+    /// [`NEUTRAL_HUE_DEG`]、强调色来自卡而不是图像）。
+    pub fn scheme(self, flavor: SchemeFlavor) -> Scheme {
+        Scheme::from_palettes(
+            &Palettes::accent_on_fixed_neutral(self.seed, NEUTRAL_HUE_DEG, self.neutral_chroma),
+            flavor,
+        )
+    }
+
+    /// 这张卡的 `on-primary` 对 `primary` 的实测对比度。
+    ///
+    /// 设置页可以直接显示成「对比度 {:.2}:1」。**2026-11 实测（8 张卡）**：
+    /// 浅色档 **6.43~6.49**、深色档 **7.70~7.75**——两种模式都远高于 WCAG AA 的 4.5:1。
+    ///
+    /// 这两个区间**被测试钉住**（不是口头声明）：`every_card_scheme_meets_wcag_aa` 对每张卡
+    /// 断言「下限 [`wcag::AA_TEXT`] + 落在上述区间内」，所以将来改种子/调色板常数把比值
+    /// 拖出区间会当场红——文档里的数字与测试同源。要改数值请连测试区间一起改。
+    pub fn primary_contrast(self, flavor: SchemeFlavor) -> f32 {
+        let scheme = self.scheme(flavor);
+        scheme.contrast(crate::color::Role::OnPrimary, crate::color::Role::Primary)
+    }
+}
+
+/// 全部内置色卡（下标 0 = 出厂默认）。
+///
+/// 色相在 CAM16 色环上大致均匀铺开（蓝 240 / 紫 299 / 绿 155 / 橙 65 / 红 10 / 青 185 /
+/// 暮蓝 ~275 / 橄榄绿 ~110），让用户「随便挑一张都不会撞色」。`palette::card` 的单测
+/// `cards_are_visually_distinct` 钉住「相邻色相间隔 ≥ 20°」。
+pub const CARDS: [Card; 8] = [
+    Card {
+        key: "sky",
+        name: "天蓝",
+        // M70 定案 ④（`palettes::DEFAULT_SEED` 同值）。改这张卡 = 改产品默认色，见 M70 文档。
+        seed: Color::rgb(0x3C, 0x8D, 0xBC),
+        neutral_chroma: DEFAULT_NEUTRAL_CHROMA,
+    },
+    Card {
+        key: "lavender",
+        name: "薰衣草紫",
+        // 官方 M3 baseline 种子，和 `Scheme::official_baseline` 同色，便于对照官方截图。
+        seed: Color::rgb(0x67, 0x50, 0xA4),
+        neutral_chroma: DEFAULT_NEUTRAL_CHROMA,
+    },
+    Card {
+        key: "forest",
+        name: "森林绿",
+        seed: Color::rgb(0x2E, 0x7D, 0x4F),
+        neutral_chroma: DEFAULT_NEUTRAL_CHROMA,
+    },
+    Card {
+        key: "amber",
+        name: "琥珀橙",
+        seed: Color::rgb(0xB2, 0x6A, 0x00),
+        neutral_chroma: DEFAULT_NEUTRAL_CHROMA,
+    },
+    Card {
+        key: "rose",
+        name: "玫瑰红",
+        seed: Color::rgb(0xB2, 0x3A, 0x48),
+        neutral_chroma: DEFAULT_NEUTRAL_CHROMA,
+    },
+    Card {
+        key: "teal",
+        name: "青碧",
+        seed: Color::rgb(0x00, 0x79, 0x6B),
+        neutral_chroma: DEFAULT_NEUTRAL_CHROMA,
+    },
+    Card {
+        key: "dusk",
+        name: "暮蓝",
+        seed: Color::rgb(0x4A, 0x5A, 0x9C),
+        neutral_chroma: DEFAULT_NEUTRAL_CHROMA,
+    },
+    Card {
+        key: "olive",
+        name: "橄榄绿",
+        // 刻意**没有**「纯灰/石板灰」卡：D40 已实测，零彩度种子的 CAM16 色相恒为 209.49°
+        // （不是「无色」，而是固定的青），极低彩度段色相还是噪声放大器。所以「想要无彩色界面」
+        // 不能靠一张灰卡实现——那需要一个饱和度/对比度维度（未来若做，是另一条轴，不是色卡）。
+        seed: Color::rgb(0x5F, 0x6B, 0x2E),
+        neutral_chroma: DEFAULT_NEUTRAL_CHROMA,
+    },
+];
+
+/// 出厂默认卡（首次启动、用户没选过卡时的那一张）。
+pub const DEFAULT_CARD: Card = CARDS[0];
+
+/// 色卡的类型化键（`Card::key` 的枚举形态）。
+///
+/// 加了它是因为「存字符串」这件事必须只有一处口径：设置读回来时走 [`CardKey::from_key`]，
+/// 写出去时走 [`CardKey::key`]，两边不会漂。新卡追加在末尾，**不重排**。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
+pub enum CardKey {
+    /// 天蓝（出厂默认，M70 ④）。
+    Sky,
+    /// 薰衣草紫（官方 M3 baseline）。
+    Lavender,
+    /// 森林绿。
+    Forest,
+    /// 琥珀橙。
+    Amber,
+    /// 玫瑰红。
+    Rose,
+    /// 青碧。
+    Teal,
+    /// 暮蓝。
+    Dusk,
+    /// 橄榄绿。
+    Olive,
+}
+
+impl CardKey {
+    /// 全部键（顺序与 [`CARDS`] 一致）。
+    pub const ALL: [CardKey; 8] = [
+        CardKey::Sky,
+        CardKey::Lavender,
+        CardKey::Forest,
+        CardKey::Amber,
+        CardKey::Rose,
+        CardKey::Teal,
+        CardKey::Dusk,
+        CardKey::Olive,
+    ];
+
+    /// 持久化键（与 [`Card::key`] 逐字相同）。
+    pub const fn key(self) -> &'static str {
+        CARDS[self.index()].key
+    }
+
+    /// 这张卡。
+    pub const fn card(self) -> Card {
+        CARDS[self.index()]
+    }
+
+    /// 显示名。
+    pub const fn name(self) -> &'static str {
+        CARDS[self.index()].name
+    }
+
+    const fn index(self) -> usize {
+        match self {
+            CardKey::Sky => 0,
+            CardKey::Lavender => 1,
+            CardKey::Forest => 2,
+            CardKey::Amber => 3,
+            CardKey::Rose => 4,
+            CardKey::Teal => 5,
+            CardKey::Dusk => 6,
+            CardKey::Olive => 7,
+        }
+    }
+
+    /// 从持久化键解析；**未知键返回 `None`**（调用方回落 [`DEFAULT_CARD`] 并可以提示
+    /// 「设置里的色卡名已失效」——绝不静默当成默认卡用掉，那样用户会以为设置没保存）。
+    pub fn from_key(key: &str) -> Option<Self> {
+        Self::ALL.into_iter().find(|card| card.key() == key)
+    }
+}
+
+impl From<CardKey> for Card {
+    fn from(key: CardKey) -> Self {
+        key.card()
+    }
+}
+
+/// 卡片方案是否过 WCAG（给测试与设置页复用；正常路径由 [`super::resolve`] 兜底）。
+pub fn card_scheme_is_readable(card: Card, flavor: SchemeFlavor) -> bool {
+    wcag::check(&card.scheme(flavor)).is_clean()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn at_least_six_cards_and_default_is_sky() {
+        assert!(CARDS.len() >= 6, "只有 {} 张卡", CARDS.len());
+        assert_eq!(DEFAULT_CARD.key, "sky");
+        assert_eq!(CARDS[0].seed, crate::color::palettes::DEFAULT_SEED);
+    }
+
+    #[test]
+    fn card_keys_are_stable_and_unique() {
+        // ⚠️ 这些字符串是持久化键：改一个就等于把老用户的选择抹成出厂默认。
+        const EXPECTED: [&str; 8] = [
+            "sky", "lavender", "forest", "amber", "rose", "teal", "dusk", "olive",
+        ];
+        for (card, expected) in CARDS.iter().zip(EXPECTED) {
+            assert_eq!(card.key, expected);
+        }
+        let mut keys: Vec<&str> = CARDS.iter().map(|card| card.key).collect();
+        keys.sort_unstable();
+        keys.dedup();
+        assert_eq!(keys.len(), CARDS.len(), "key 有重复");
+        for card in CARDS {
+            assert!(
+                card.key.chars().all(|c| c.is_ascii_lowercase()),
+                "{} 不是小写 ASCII",
+                card.key
+            );
+            assert!(!card.name.is_empty());
+        }
+    }
+
+    #[test]
+    fn card_key_roundtrips_and_rejects_unknown() {
+        for key in CardKey::ALL {
+            assert_eq!(CardKey::from_key(key.key()), Some(key));
+            assert_eq!(key.card().key, key.key());
+        }
+        assert_eq!(CardKey::from_key("no-such-card"), None);
+        assert_eq!(CardKey::from_key("SKY"), None, "key 大小写敏感");
+    }
+
+    #[test]
+    fn every_card_scheme_meets_wcag_aa() {
+        for card in CARDS {
+            for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+                assert!(
+                    card_scheme_is_readable(card, flavor),
+                    "{} / {flavor:?} 未过门禁",
+                    card.key
+                );
+                let ratio = card.primary_contrast(flavor);
+                assert!(
+                    ratio >= wcag::AA_TEXT,
+                    "{} / {flavor:?} primary 对 {} 只有 {ratio:.2}",
+                    card.key,
+                    card.name
+                );
+                // 上半区间：文档（`Card::primary_contrast`）向用户承诺的就是这两个区间，
+                // 只钉「≥ 4.5」等于没钉——比值掉到 5.0 也全绿，而文档会继续说 6.43~6.49。
+                // 边界取实测极值 ±0.01：浅色 6.4324~6.4906、深色 7.7024~7.7504。
+                let (low, high) = match flavor {
+                    SchemeFlavor::Light => (6.43, 6.50),
+                    SchemeFlavor::Dark => (7.70, 7.76),
+                };
+                assert!(
+                    (low..=high).contains(&ratio),
+                    "{} / {flavor:?} primary 对比度 {ratio:.4} 超出文档区间 {low}~{high}",
+                    card.key
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn cards_are_visually_distinct() {
+        // 色相间隔 ≥ 20°：八张卡的种子在两套方案里都不该撞成同一套配色。
+        let mut hues: Vec<f64> = CARDS
+            .iter()
+            .map(|card| crate::color::Hct::from_color(card.seed).hue)
+            .collect();
+        hues.sort_by(|a, b| a.partial_cmp(b).expect("有限色相"));
+        for pair in hues.windows(2) {
+            let gap = pair[1] - pair[0];
+            assert!(gap >= 20.0, "色相挤在一起：{pair:?}");
+        }
+        // 色相是环：排序后「最大 − 最小」不是真实间隔，**回绕那一侧**也要检查。
+        // 漏了这条的话，将来加一张 350° 的卡（与 rose 15.85° 实际只差 25.7°）会被算成
+        // 334.2° 而静默通过。
+        let wrap_gap = 360.0 - (hues[hues.len() - 1] - hues[0]);
+        assert!(
+            wrap_gap >= 20.0,
+            "色相环回绕处挤在一起：{:.2}° ↔ {:.2}°（间隔 {wrap_gap:.2}°）",
+            hues[hues.len() - 1],
+            hues[0]
+        );
+        for card in CARDS {
+            let light = card.scheme(SchemeFlavor::Light);
+            let dark = card.scheme(SchemeFlavor::Dark);
+            assert_ne!(
+                light.get(crate::color::Role::Primary),
+                dark.get(crate::color::Role::Primary)
+            );
+        }
+    }
+}
diff --git a/crates/design/src/palette/mod.rs b/crates/design/src/palette/mod.rs
new file mode 100644
index 0000000..c5e2f39
--- /dev/null
+++ b/crates/design/src/palette/mod.rs
@@ -0,0 +1,60 @@
+//! # 配色来源（D38 / D40）：图片取色 · 内置色卡 · 三级回落 · WCAG 收敛
+//!
+//! 用户在 2026-11-01 定的配色来源是三级（D38）：
+//!
+//! ```text
+//! ① 启动器背景图取色（用户设了背景图时）
+//!    ↓ 没有背景图 / 取色失败
+//! ② 桌面壁纸取色（用户开了「莫奈取色」但没设背景图时）
+//!    ↓ 没有壁纸 / 取色失败 / 对比度收敛失败
+//! ③ 内置色卡（用户手动选的那张；没选过就是出厂默认「天蓝」）
+//! ```
+//!
+//! 取色失败**不静默**：本模块的 [`Provenance`] 会把「最终用了哪一级」和「前几级为什么没用」
+//! 都带回来，设置页据此显示提示；解码失败也在里面（它不在这里发生，但原因是这里记录的）。
+//! 契约（UI 怎么调、文案怎么映射）见 `DevDocs/SubAgentsTalk/palette-source-contract.md`。
+//!
+//! ## 分层（D40）：本模块只做纯数学
+//!
+//! | 层 | 在哪 | 职责 | 依赖 |
+//! |---|---|---|---|
+//! | 纯数学 | **本模块**（`crates/design`） | 像素 → 种子 → 49 角色；色卡；回落决策；对比度收敛 | 无（零第三方依赖） |
+//! | 解码 | `crates/palette-extract` | 路径/字节 → RGBA 像素 | `image`（唯一引入处） |
+//! | 调用侧 | 后续 appearance/settings mission | 拿路径、把 [`Provenance`] 变文案 | UI 框架 |
+//!
+//! 所以本模块的「图片输入」永远是**已经解码好的像素**，从来没有路径、没有 IO。
+//!
+//! ## 四个部分
+//!
+//! - [`seed`]：`seed_from_rgba(pixels, w, h)`（D40 的入口形状）。量化在 [`quantize`]，
+//!   挑主色在 [`score`]——**不是取平均色**，理由见 [`quantize`] 的模块文档。
+//! - [`card`]：内置色卡（≥6 张，含出厂默认「天蓝」）。卡的 `key` 是**持久化键**，写进用户设置。
+//! - [`wcag`]：对任意一套方案跑对比度断言；不达标就沿 tone 轴修正，并记录「改了什么」。
+//! - [`resolve`]：纯函数 `resolve_source(...) -> (Scheme, Provenance)`，实现三级优先与回落。
+//!
+//! ## D40 的两条实测事实（不是风格偏好，是物理事实）
+//!
+//! 1. **零彩度种子的 CAM16 色相是常数 209.49°**，不是 NaN。所以「灰白壁纸」硬取色会得到
+//!    一个凭空上色的青色（`#006874`），且极低彩度段色相是噪声放大器（`#808080` → 209.5°、
+//!    `#7A7C7E` → 231.2°）。→ [`seed::MIN_SEED_CHROMA`] = 8 的种子彩度门槛，低于它就回落色卡。
+//! 2. **动态色也必须过 WCAG**。候选色卡的 208 项门禁（`tests/contrast_aa.rs`）不覆盖取色结果，
+//!    所以 [`wcag`] 对**任何**来源的方案都跑同一套检查，不达标就收敛或回落。
+
+pub mod card;
+pub mod resolve;
+pub mod seed;
+pub mod wcag;
+
+mod quantize;
+mod score;
+
+pub use card::{Card, CardKey, CARDS, DEFAULT_CARD};
+pub use resolve::{resolve_source, ImageInput, ImageSource, Level, Outcome, Provenance, Skip};
+pub use seed::{
+    analyze_rgba, seed_from_rgba, Failure, Seed, MAX_SAMPLES, MIN_PIXELS, MIN_SEED_CHROMA,
+    MUTED_SEED_CHROMA,
+};
+pub use wcag::{converge, Adjustment, WcagReport, AA_NON_TEXT, AA_TEXT, TEXT_PAIRS};
+
+/// 一套方案的来源层级（[`Level`] 的别名，读起来更清楚）。
+pub use resolve::Level as SourceLevel;
diff --git a/crates/design/src/palette/quantize.rs b/crates/design/src/palette/quantize.rs
new file mode 100644
index 0000000..365cd93
--- /dev/null
+++ b/crates/design/src/palette/quantize.rs
@@ -0,0 +1,338 @@
+//! 像素 → 主色簇：Monet（Material You）取色管线里**量化那一半**（打分那一半在 [`super::score`]）。
+//!
+//! ## 为什么不是「取平均色」
+//!
+//! 平均色是两个独立错误的合成：
+//!
+//! 1. **它不存在的颜色**。平均会把「天空 60% + 树叶 30% + 纯白 10%」混成一块脏灰绿，
+//!    这个色值在图上**一个像素都不是**，拿它当种子，用户看到的整套配色跟壁纸不像。
+//! 2. **它没有「主色」概念**。一张 95% 是米白、5% 是珊瑚的图，平均色几乎等于米白，
+//!    而人眼记住的、能当强调色用的是那 5%。官方 Monet 的立场正好相反：**按面积 + 彩度
+//!    挑一个「有人气又有色」的代表色**（`Score`），不是把整体摊平。
+//!
+//! ## 采用的策略（三层）
+//!
+//! | 步 | 做什么 | 官方对应 | 等级 |
+//! |---|---|---|---|
+//! | 1 | 5 bit/通道直方图（32³ = 32768 桶），桶内记像素数与各通道原值和 | `QuantizerWu` 的 `INDEX_BITS = 5` | A |
+//! | 2 | 桶当带权点，在 **CIELAB** 里跑 k-means（≤10 轮；簇心用线性 RGB 加权均值更新） | `QuantizerWsmeans`（`MAX_ITERATIONS = 10`、`MIN_DELTA_E = 3.0`） | A（结构）/ B（用直方图桶代替 Wu 的分割盒播种） |
+//! | 3 | 每簇的代表色 = 簇内像素最多的那个桶里**像素的原值平均** | `QuantizerCelebi` = 量化 + `Score` | A（管线）/ B（代表色取桶内均值） |
+//!
+//! 也就是说：本模块 = `QuantizerCelebi` 的形状（直方图量化 + k-means 精修），
+//! 与官方的差别在**播种方式**——官方用 `QuantizerWu` 的动态规划分割盒当初始簇心，
+//! 这里用「像素数最多的 24 个桶」。差别可测量（见各模块单测：5% 面积的强调色簇不会被
+//! 95% 的底色吞掉），换来的是一条可全单测、零依赖、确定性的实现。
+//!
+//! ## 代表色为什么要「桶内原值平均」而不是桶中心
+//!
+//! 只取桶中心（5 bit 量化点）会让纯色 `#3C8DBC` 的图取出 `#3B8BBB`——量化误差 1~3/通道。
+//! 单看数字无所谓，但这是**用户能看出来**的：「我选的是这个蓝，凭什么给我的强调色差一点？」
+//! 桶内原值平均对纯色图精确等于输入色（误差 0），对复杂图就是该桶的真实均值，
+//! 仍然不是「全图平均色」（只有一个桶那么多像素参与）。
+//!
+//! ## 来源等级
+//!
+//! - **A**：`material-color-utilities`（Apache-2.0）里确实有 `QuantizerWu` / `QuantizerWsmeans` /
+//!   `QuantizerCelebi` / `Score` 四个类，且 `INDEX_BITS = 5`、`MAX_ITERATIONS = 10`、
+//!   `MIN_DELTA_E = 3.0` 是官方常数——这些是「照抄口径」的部分。
+//! - **B**：用「top-N 桶」代替 Wu 的分割盒当播种；代表色取桶内原值均值。
+//! - **C**：不做。拿不准的常数一律写成带注释的「我们的选择」，不假装是官方值。
+
+use crate::color::space;
+use crate::color::Color;
+
+/// 每通道保留的位数：官方 `QuantizerWu` 用 5 bit/通道。
+pub(crate) const INDEX_BITS: u32 = 5;
+/// 直方图桶数（32³）。
+const BIN_COUNT: usize = 1 << (INDEX_BITS as usize * 3);
+/// 每通道的右移量（8 − 5 = 3）。
+const SHIFT: u32 = 8 - INDEX_BITS;
+/// k-means 最多迭代轮数（官方 `QuantizerWsmeans.MAX_ITERATIONS`）。
+const MAX_ITERATIONS: usize = 10;
+/// 收敛阈值：簇心在 CIELAB 里移动小于这个距离就停（官方 `MIN_DELTA_E`）。
+const MIN_DELTA_E: f64 = 3.0;
+/// 最多保留的簇数（喂给打分的候选数量）。官方 `Score` 通常拿到 256 个候选；
+/// 24 个足够覆盖「底色 + 两三个强调色簇」，也让色相直方图不被噪声塞满。
+pub(crate) const MAX_CLUSTERS: usize = 24;
+
+/// 一个主色簇：图里**真实存在**的颜色 + 被归到它名下的像素数。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) struct Cluster {
+    /// 簇的代表色（簇内像素最多的桶里，像素原值的平均）。
+    pub color: Color,
+    /// 归到这个簇的采样像素数。
+    pub population: u32,
+}
+
+/// 一个非空桶。
+#[derive(Debug, Clone, Copy)]
+struct Bin {
+    index: usize,
+    color: Color,
+    count: u32,
+}
+
+/// 把采样像素量化成主色簇（按像素数降序，同数按色值排序 → 结果确定）。
+pub(crate) fn quantize(samples: &[Color]) -> Vec<Cluster> {
+    let bins = histogram(samples);
+    if bins.is_empty() {
+        return Vec::new();
+    }
+    let mut clusters = if bins.len() <= MAX_CLUSTERS {
+        bins.iter()
+            .map(|bin| Cluster {
+                color: bin.color,
+                population: bin.count,
+            })
+            .collect()
+    } else {
+        kmeans(&bins)
+    };
+    clusters.sort_by(|a, b| {
+        b.population
+            .cmp(&a.population)
+            .then_with(|| packed(a.color).cmp(&packed(b.color)))
+    });
+    clusters
+}
+
+/// 直方图（按桶下标升序，空的桶不出现）。
+fn histogram(samples: &[Color]) -> Vec<Bin> {
+    let mut counts = vec![0u32; BIN_COUNT];
+    // 每桶各通道的原值和（`u32` 够用：单桶最多 65536 个采样点 × 255 < 2^32）。
+    let mut sums = vec![[0u32; 3]; BIN_COUNT];
+    for color in samples {
+        let index = bin_index(*color);
+        counts[index] = counts[index].saturating_add(1);
+        for (channel, value) in [color.r, color.g, color.b].into_iter().enumerate() {
+            sums[index][channel] = sums[index][channel].saturating_add(u32::from(value));
+        }
+    }
+    counts
+        .iter()
+        .zip(&sums)
+        .enumerate()
+        .filter(|(_, (count, _))| **count > 0)
+        .map(|(index, (count, sum))| Bin {
+            index,
+            color: average_color(*count, *sum),
+            count: *count,
+        })
+        .collect()
+}
+
+fn average_color(count: u32, sum: [u32; 3]) -> Color {
+    let channel = |value: u32| ((f64::from(value) / f64::from(count)).round()) as u8;
+    Color::rgb(channel(sum[0]), channel(sum[1]), channel(sum[2]))
+}
+
+fn bin_index(color: Color) -> usize {
+    (usize::from(color.r >> SHIFT) << (INDEX_BITS * 2))
+        | (usize::from(color.g >> SHIFT) << INDEX_BITS)
+        | usize::from(color.b >> SHIFT)
+}
+
+/// CIELAB 欧氏距离的平方。
+fn distance_squared(a: [f64; 3], b: [f64; 3]) -> f64 {
+    let dl = a[0] - b[0];
+    let da = a[1] - b[1];
+    let db = a[2] - b[2];
+    dl * dl + da * da + db * db
+}
+
+/// 带权 k-means（在 CIELAB 里分配、在线性 RGB 里更新簇心）。
+fn kmeans(bins: &[Bin]) -> Vec<Cluster> {
+    let mut by_population: Vec<usize> = (0..bins.len()).collect();
+    by_population.sort_by(|&a, &b| {
+        bins[b]
+            .count
+            .cmp(&bins[a].count)
+            .then_with(|| bins[a].index.cmp(&bins[b].index))
+    });
+    by_population.truncate(MAX_CLUSTERS);
+
+    let mut centers: Vec<Color> = by_population.iter().map(|&i| bins[i].color).collect();
+    let mut assignments = vec![usize::MAX; bins.len()];
+
+    for _ in 0..MAX_ITERATIONS {
+        let center_lab: Vec<[f64; 3]> = centers.iter().map(|c| space::lab_from_color(*c)).collect();
+        let mut changed = false;
+        for (i, bin) in bins.iter().enumerate() {
+            let lab = space::lab_from_color(bin.color);
+            let mut best = 0;
+            let mut best_distance = f64::INFINITY;
+            for (k, center) in center_lab.iter().enumerate() {
+                let distance = distance_squared(lab, *center);
+                if distance < best_distance {
+                    best_distance = distance;
+                    best = k;
+                }
+            }
+            if assignments[i] != best {
+                changed = true;
+                assignments[i] = best;
+            }
+        }
+
+        let mut sums = vec![[0.0_f64; 3]; centers.len()];
+        let mut weights = vec![0.0_f64; centers.len()];
+        for (i, bin) in bins.iter().enumerate() {
+            let weight = f64::from(bin.count);
+            let linear = [
+                space::linearized(bin.color.r),
+                space::linearized(bin.color.g),
+                space::linearized(bin.color.b),
+            ];
+            let k = assignments[i];
+            for channel in 0..3 {
+                sums[k][channel] += linear[channel] * weight;
+            }
+            weights[k] += weight;
+        }
+
+        let mut shift = 0.0_f64;
+        for (k, center) in centers.iter_mut().enumerate() {
+            if weights[k] <= 0.0 {
+                continue;
+            }
+            let mean = [
+                sums[k][0] / weights[k],
+                sums[k][1] / weights[k],
+                sums[k][2] / weights[k],
+            ];
+            let next = space::color_from_linrgb(mean);
+            shift = shift.max(distance_squared(space::lab_from_color(next), center_lab[k]).sqrt());
+            *center = next;
+        }
+        if !changed || shift < MIN_DELTA_E {
+            break;
+        }
+    }
+
+    // 代表色取「簇内像素数最多的真实桶」，**不是**簇心均值：均值色往往在图上不存在，
+    // 用它当种子会让色卡与壁纸看起来不像（见模块文档第 1 条理由）。
+    let mut representatives: Vec<Option<(u32, Color)>> = vec![None; centers.len()];
+    for (i, bin) in bins.iter().enumerate() {
+        let k = assignments[i];
+        let better = match representatives[k] {
+            None => true,
+            Some((best, _)) => bin.count > best,
+        };
+        if better {
+            representatives[k] = Some((bin.count, bin.color));
+        }
+    }
+
+    let mut totals = vec![0u32; centers.len()];
+    for (i, bin) in bins.iter().enumerate() {
+        totals[assignments[i]] = totals[assignments[i]].saturating_add(bin.count);
+    }
+
+    let mut clusters: Vec<Cluster> = representatives
+        .iter()
+        .enumerate()
+        .filter_map(|(k, entry)| {
+            entry.map(|(_, color)| Cluster {
+                color,
+                population: totals[k],
+            })
+        })
+        .collect();
+    // 不同簇可能选出同一个代表桶（极少见），合并以免重复喂给打分。
+    clusters.sort_by_key(|cluster| packed(cluster.color));
+    clusters.dedup_by(|a, b| {
+        if a.color == b.color {
+            b.population = b.population.saturating_add(a.population);
+            true
+        } else {
+            false
+        }
+    });
+    clusters
+}
+
+fn packed(color: Color) -> u32 {
+    (u32::from(color.r) << 16) | (u32::from(color.g) << 8) | u32::from(color.b)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn bin_index_groups_neighbours() {
+        // 同一个 5 bit 桶内的像素共享桶下标（桶宽 8）。
+        assert_eq!(
+            bin_index(Color::rgb(0x50, 0x80, 0x10)),
+            bin_index(Color::rgb(0x57, 0x87, 0x17))
+        );
+        assert_ne!(
+            bin_index(Color::rgb(0x50, 0x80, 0x10)),
+            bin_index(Color::rgb(0x60, 0x80, 0x10))
+        );
+    }
+
+    #[test]
+    fn solid_color_keeps_its_exact_value() {
+        // 桶内原值平均 → 纯色图取回的种子与输入色**逐通道相等**（量化误差被平均消掉）。
+        for hex in ["#3C8DBC", "#C0392B", "#00F0FF", "#123456"] {
+            let color = Color::from_hex(hex).expect("合法 hex");
+            let clusters = quantize(&[color; 500]);
+            assert_eq!(clusters.len(), 1);
+            assert_eq!(clusters[0].color, color, "{hex}");
+            assert_eq!(clusters[0].population, 500);
+        }
+    }
+
+    #[test]
+    fn empty_input_has_no_cluster() {
+        assert!(quantize(&[]).is_empty());
+    }
+
+    #[test]
+    fn cluster_populations_add_up() {
+        let mut samples = Vec::new();
+        for i in 0..60 {
+            let shade = (i * 4) as u8;
+            samples.push(Color::rgb(shade, 40, 200));
+            samples.push(Color::rgb(200, shade, 40));
+            samples.push(Color::rgb(40, 200, shade));
+        }
+        let clusters = quantize(&samples);
+        let total: u32 = clusters.iter().map(|c| c.population).sum();
+        assert_eq!(total, samples.len() as u32);
+        assert!(clusters.len() <= MAX_CLUSTERS, "{} 簇", clusters.len());
+    }
+
+    #[test]
+    fn kmeans_split_is_deterministic() {
+        let mut samples = Vec::new();
+        for i in 0..90 {
+            let shade = (i * 2) as u8;
+            samples.push(Color::rgb(shade, 40, 200));
+            samples.push(Color::rgb(200, shade, 40));
+            samples.push(Color::rgb(40, 200, shade));
+        }
+        assert_eq!(quantize(&samples), quantize(&samples));
+    }
+
+    #[test]
+    fn kmeans_keeps_a_small_distinct_cluster() {
+        // 3% 面积的红点 + 97% 的蓝底：k-means 不能把红点并进蓝簇。
+        let mut samples = vec![Color::rgb(0x20, 0x40, 0xC0); 970];
+        samples.extend(vec![Color::rgb(0xD0, 0x30, 0x20); 30]);
+        let clusters = quantize(&samples);
+        assert!(
+            clusters
+                .iter()
+                .any(|c| c.color.r > 0xB0 && c.color.b < 0x60),
+            "{clusters:?}"
+        );
+        assert!(
+            clusters
+                .iter()
+                .any(|c| c.color.b > 0xA0 && c.color.r < 0x60),
+            "{clusters:?}"
+        );
+    }
+}
diff --git a/crates/design/src/palette/resolve/mod.rs b/crates/design/src/palette/resolve/mod.rs
new file mode 100644
index 0000000..917b6da
--- /dev/null
+++ b/crates/design/src/palette/resolve/mod.rs
@@ -0,0 +1,205 @@
+//! 三级来源编排：**纯函数**，一次调用算完「用哪一级的颜色、为什么不是别的级」。
+//!
+//! D38 的优先序：① 启动器背景图 → ② 桌面壁纸 → ③ 内置色卡。
+//! 本模块不做任何 IO：像素是调用方解码好传进来的（D40 分层），壁纸路径探测是 M73 的事。
+//!
+//! ```no_run
+//! use unlucky_design::palette::{resolve_source, CardKey, ImageInput, ImageSource, Level};
+//! use unlucky_design::color::SchemeFlavor;
+//!
+//! let pixels = [0x3C, 0x8D, 0xBC, 0xFF].repeat(16); // 4×4 天蓝图（示例）
+//! let bg = ImageInput::Pixels(ImageSource { pixels: &pixels, width: 4, height: 4 });
+//! let (scheme, provenance) = resolve_source(Some(bg), None, Some(CardKey::Forest), SchemeFlavor::Light);
+//! assert_eq!(provenance.level, Level::BackgroundImage);
+//! assert!(provenance.hint_key().is_none(), "一级成功时没有提示");
+//! ```
+//!
+//! ## 失败链：每一级都可能「有输入但不合格」
+//!
+//! | 情形 | 结果 | `Provenance` 里留下 |
+//! |---|---|---|
+//! | 没有背景图 | 跳到 ② | `Outcome::Absent` |
+//! | 更高级已经成功 | 不再看这一级 | `Outcome::NotReached`（**不等于**「用户没提供」） |
+//! | 背景图解码失败 | 跳到 ② | `Outcome::Failed(Skip::Undecodable)` |
+//! | 背景图太小 / 像素缓冲不对 / 全透明 | 跳到 ② | `… TooSmall / BadDimensions / NoOpaquePixels` |
+//! | 背景图彩度不足（D40 的 `< 8`） | 跳到 ② | `… LowChroma { chroma }` |
+//! | 背景图取色成功但对比度收敛失败 | 跳到 ② | `… Contrast { failures }`（理论上不会发生，仍要留） |
+//! | 三级都不成立 | 用色卡，**一定**有结果 | `Level::Preset` |
+//!
+//! 三条纪律：
+//!
+//! 1. **不许静默**。任何一次回落都在 `Provenance` 里留下原因码，[`Provenance::hint_key`]
+//!    给 UI 一个稳定的提示键（文案映射见 `DevDocs/SubAgentsTalk/palette-source-contract.md`）。
+//! 2. **不许静默变黑白**。彩度不足的图**不**会被「压成灰方案」，而是直接回落到用户选的那张色卡。
+//! 3. **不许静默换成默认卡**。回落的落点是「用户当前选中的卡」（参数 `preset`），
+//!    只有用户从没选过卡（`None`）才用 [`super::DEFAULT_CARD`]。
+//!
+//! ## 文件划分
+//!
+//! [`provenance`] 放「结果解释」的数据类型（`Level` / `Outcome` / `Skip` / `Provenance`），
+//! 本文件放编排函数与测试。拆开只是为了单文件 ≤400 行的纪律，对外路径仍是
+//! `palette::resolve::*`。
+
+use super::card::{Card, CardKey, DEFAULT_CARD};
+use super::seed::{analyze_rgba, Seed};
+use super::wcag::{check, converge, Adjustment};
+use crate::color::{Scheme, SchemeFlavor};
+
+mod provenance;
+
+pub use provenance::{Level, Outcome, Provenance, Skip};
+
+/// 已解码的图片：借用像素，不拷贝（解码在 `crates/palette-extract`）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ImageSource<'a> {
+    /// RGBA8 像素，`width × height × 4` 字节。
+    pub pixels: &'a [u8],
+    /// 宽（像素）。
+    pub width: u32,
+    /// 高（像素）。
+    pub height: u32,
+}
+
+/// 某一级来源的输入。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ImageInput<'a> {
+    /// 解码好的像素。
+    Pixels(ImageSource<'a>),
+    /// 有这张图，但解码失败（文件损坏 / 格式不支持 / 读不到）。
+    ///
+    /// 这个状态由适配层传进来——不传就等于「没有这张图」，UI 会说错话。
+    Undecodable,
+}
+
+impl<'a> ImageInput<'a> {
+    /// 便捷构造：从像素缓冲包一个输入。
+    pub fn pixels(pixels: &'a [u8], width: u32, height: u32) -> Self {
+        ImageInput::Pixels(ImageSource {
+            pixels,
+            width,
+            height,
+        })
+    }
+}
+/// 三级来源编排（纯函数）。
+///
+/// 参数：
+/// - `background`：用户设的启动器背景图（`None` = 没设）。解码失败传
+///   [`ImageInput::Undecodable`]，**不要**传 `None`（那样 UI 分不清「没设」和「坏了」）。
+/// - `wallpaper`：桌面壁纸（`None` = 没开莫奈 / 探测不到壁纸文件）。
+/// - `preset`：用户当前选中的色卡（`None` = 从没选过 → 用 [`super::DEFAULT_CARD`]）。
+/// - `flavor`：深浅模式。
+///
+/// 返回值永远有一套可用方案：三级全失败时落到色卡，并带上原因。
+pub fn resolve_source(
+    background: Option<ImageInput<'_>>,
+    wallpaper: Option<ImageInput<'_>>,
+    preset: Option<CardKey>,
+    flavor: SchemeFlavor,
+) -> (Scheme, Provenance) {
+    let card = preset.map(Card::from).unwrap_or(DEFAULT_CARD);
+    // 先假定「没轮到」，逐级评估时再改成 Absent / Failed / Used。
+    let mut outcomes = [Outcome::NotReached; 3];
+
+    for (level, input) in [
+        (Level::BackgroundImage, background),
+        (Level::Wallpaper, wallpaper),
+    ] {
+        match try_level(input, card, flavor) {
+            Attempt::Absent => outcomes[level.index()] = Outcome::Absent,
+            Attempt::Failed(skip) => outcomes[level.index()] = Outcome::Failed(skip),
+            Attempt::Used {
+                scheme,
+                seed,
+                adjustments,
+            } => {
+                outcomes[level.index()] = Outcome::Used;
+                return (
+                    *scheme,
+                    Provenance {
+                        level,
+                        card: card_key(card),
+                        seed: Some(seed),
+                        flavor,
+                        adjustments,
+                        outcomes,
+                    },
+                );
+            }
+        }
+    }
+
+    // 第三级：色卡。收敛仍然要跑（色卡也可能因为将来改常数而越线），但落点是它自己。
+    let (scheme, adjustments) = converge(card.scheme(flavor));
+    let report = check(&scheme);
+    outcomes[Level::Preset.index()] = if report.is_clean() {
+        Outcome::Used
+    } else {
+        Outcome::Failed(Skip::Contrast {
+            failures: report.failures.len(),
+        })
+    };
+    (
+        scheme,
+        Provenance {
+            level: Level::Preset,
+            card: card_key(card),
+            seed: None,
+            flavor,
+            adjustments,
+            outcomes,
+        },
+    )
+}
+
+/// 单级的处理结果。
+///
+/// `scheme` 装箱只是为了枚举大小（`Scheme` 是 49 个色值 ≈ 200 字节，逐级在栈上传会白白拷两次）；
+/// 这条路径每次配色只走一次，堆分配的开销可忽略。
+enum Attempt {
+    Absent,
+    Failed(Skip),
+    Used {
+        scheme: Box<Scheme>,
+        seed: Seed,
+        adjustments: Vec<Adjustment>,
+    },
+}
+
+fn try_level(input: Option<ImageInput<'_>>, card: Card, flavor: SchemeFlavor) -> Attempt {
+    let source = match input {
+        None => return Attempt::Absent,
+        Some(ImageInput::Undecodable) => return Attempt::Failed(Skip::Undecodable),
+        Some(ImageInput::Pixels(source)) => source,
+    };
+
+    let seed = match analyze_rgba(source.pixels, source.width, source.height) {
+        Ok(seed) => seed,
+        Err(failure) => return Attempt::Failed(Skip::from(failure)),
+    };
+
+    // 取色方案的表面色**跟着图像种子染色**，只借当前色卡的中性彩度定浓淡（D43）：
+    // 这是与色卡路径刻意不同的一处——色卡固定中性色相、只换强调色，取色保留整幅染色
+    // （那是用户要的 Monet 体验）。别把两条路径「统一处理」：这条接线的守护测试是
+    // `tests/card_neutral.rs::resolved_image_scheme_keeps_tinting_from_the_seed`（走的就是
+    // 本函数所在的 `resolve_source`；只测 `Seed::scheme` 的那条覆盖不到这里，复审 r1 p1-1）。
+    let (scheme, adjustments) = converge(seed.scheme(flavor, card.neutral_chroma));
+    let report = check(&scheme);
+    if !report.is_clean() {
+        return Attempt::Failed(Skip::Contrast {
+            failures: report.failures.len(),
+        });
+    }
+    Attempt::Used {
+        scheme: Box::new(scheme),
+        seed,
+        adjustments,
+    }
+}
+
+fn card_key(card: Card) -> CardKey {
+    CardKey::from_key(card.key).unwrap_or(CardKey::Sky)
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/design/src/palette/resolve/provenance.rs b/crates/design/src/palette/resolve/provenance.rs
new file mode 100644
index 0000000..d3ea5ad
--- /dev/null
+++ b/crates/design/src/palette/resolve/provenance.rs
@@ -0,0 +1,261 @@
+//! 一次配色的「结果解释」：最终用了哪一级、前几级为什么没用、对比度被改了什么。
+//!
+//! 这些类型是**给 UI 看的契约**（[`Provenance::hint_key`] 的键 → 文案的映射见
+//! `DevDocs/SubAgentsTalk/palette-source-contract.md`），所以刻意做得比内部需要更细：
+//! 每一种失败都带足以写出一句具体提示的数据（彩度是多少、图有多小、哪一级坏了）。
+//!
+//! 与 [`super`] 拆开只为单文件 ≤400 行；对外路径仍是 `palette::resolve::*`。
+
+use super::super::card::CardKey;
+use super::super::seed::{Failure, Seed};
+use super::super::wcag::Adjustment;
+use crate::color::{Color, SchemeFlavor};
+
+/// 方案的来源层级（D38 的三级）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Level {
+    /// ① 启动器背景图取色。
+    BackgroundImage,
+    /// ② 桌面壁纸取色。
+    Wallpaper,
+    /// ③ 内置色卡。
+    Preset,
+}
+
+impl Level {
+    /// 稳定码（日志/设置里用，别用 `Debug` 输出）。
+    pub const fn code(self) -> &'static str {
+        match self {
+            Level::BackgroundImage => "background-image",
+            Level::Wallpaper => "wallpaper",
+            Level::Preset => "preset",
+        }
+    }
+
+    /// 在本模块内部当索引用（0 = ①）。
+    ///
+    /// `pub(super)`：`resolve` 的编排函数要按下标填 `Provenance` 的三个格子，
+    /// 但它不该出现在对外 API 里（外部只该问「哪一级」，不该拿索引当协议）。
+    pub(super) const fn index(self) -> usize {
+        match self {
+            Level::BackgroundImage => 0,
+            Level::Wallpaper => 1,
+            Level::Preset => 2,
+        }
+    }
+}
+
+/// 某一级的处置结果。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub enum Outcome {
+    /// 用了这一级。
+    Used,
+    /// 用户没提供这一级（没设背景图 / 没开莫奈取色）。
+    ///
+    /// 注意与 [`Outcome::NotReached`] 的区别：`Absent` 是「用户没有这一级的输入」，
+    /// 而「用户提供了、但更高级已经成功所以没轮到」是 `NotReached`。两者对 UI 的含义完全不同——
+    /// 把后者说成「未选择」，用户明明选了卡却被告知「色卡：未选择」。
+    Absent,
+    /// 有输入、但因为更高级已经成功，**没轮到**这一级。
+    ///
+    /// 只可能出现在低优先级那一侧：背景图成功 → 壁纸与色卡都是 `NotReached`。
+    /// 色卡即使 `NotReached` 也可能参与生成（它的中性彩度决定表面色温），所以 UI 要看
+    /// [`Provenance::card`] 而不是把 `NotReached` 当成「没用它」。
+    NotReached,
+    /// 有输入但不合格，已跳过。
+    Failed(Skip),
+}
+
+/// 「有输入但不合格」的具体原因——每一条都要能变成一句人话。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub enum Skip {
+    /// 解码失败（原因在适配层，这里只知道失败）。
+    Undecodable,
+    /// 图太小（< 4 像素）。
+    TooSmall {
+        /// 宽。
+        width: u32,
+        /// 高。
+        height: u32,
+    },
+    /// 像素缓冲长度与宽高不符（调用方给错了数据）。
+    BadDimensions {
+        /// 期望字节数。
+        expected: usize,
+        /// 实际字节数。
+        actual: usize,
+    },
+    /// 全是透明像素。
+    NoOpaquePixels,
+    /// 彩度不足（D40：`< MIN_SEED_CHROMA`），硬取色会凭空上色。
+    LowChroma {
+        /// 实测彩度。
+        chroma: f64,
+        /// 最接近的候选色（提示文案里显示成色块）。
+        color: Color,
+    },
+    /// 取色成功但对比度收敛后仍不达标。
+    Contrast {
+        /// 仍不达标的对数。
+        failures: usize,
+    },
+}
+
+impl Skip {
+    /// 稳定原因码（`Provenance::hint_key` 的后半段）。
+    pub const fn code(self) -> &'static str {
+        match self {
+            Skip::Undecodable => "undecodable",
+            Skip::TooSmall { .. } => "too-small",
+            Skip::BadDimensions { .. } => "bad-dimensions",
+            Skip::NoOpaquePixels => "no-opaque-pixels",
+            Skip::LowChroma { .. } => "low-chroma",
+            Skip::Contrast { .. } => "contrast",
+        }
+    }
+}
+
+impl From<Failure> for Skip {
+    fn from(failure: Failure) -> Self {
+        match failure {
+            Failure::BadDimensions {
+                expected, actual, ..
+            } => Skip::BadDimensions { expected, actual },
+            Failure::TooSmall { width, height } => Skip::TooSmall { width, height },
+            Failure::NoOpaquePixels => Skip::NoOpaquePixels,
+            Failure::LowChroma { color, chroma } => Skip::LowChroma { color, chroma },
+        }
+    }
+}
+
+/// 这次配色「最后用了什么、前几级为什么没用」。
+#[derive(Debug, Clone, PartialEq)]
+pub struct Provenance {
+    /// 最终生效的层级。
+    pub level: Level,
+    /// 当前生效的色卡（取色成功时它仍然参与：中性彩度来自它）。
+    pub card: CardKey,
+    /// 取色成功时的种子（色卡档为 `None`）。
+    pub seed: Option<Seed>,
+    /// 深浅模式。
+    pub flavor: SchemeFlavor,
+    /// 对比度收敛改了哪些角色（空 = 没动）。
+    pub adjustments: Vec<Adjustment>,
+    /// 三级各自的处置结果（`pub(super)`：只能由 `resolve::resolve_source` 填，
+    /// 外部一律通过 [`Provenance::outcome`] / [`Provenance::background`] 等访问器读）。
+    pub(super) outcomes: [Outcome; 3],
+}
+
+impl Provenance {
+    /// 某一级发生了什么。
+    pub fn outcome(&self, level: Level) -> Outcome {
+        self.outcomes[level.index()]
+    }
+
+    /// 背景图那一级。
+    pub fn background(&self) -> Outcome {
+        self.outcome(Level::BackgroundImage)
+    }
+
+    /// 壁纸那一级。
+    pub fn wallpaper(&self) -> Outcome {
+        self.outcome(Level::Wallpaper)
+    }
+
+    /// 色卡那一级。
+    pub fn preset(&self) -> Outcome {
+        self.outcome(Level::Preset)
+    }
+
+    /// 这次配色是否发生过回落（用了 `level` 以下的层级）。
+    pub fn did_fall_back(&self) -> bool {
+        (0..self.level.index()).any(|i| !matches!(self.outcomes[i], Outcome::Absent))
+    }
+
+    /// 第一个「有输入但不合格」的层级（提示文案优先说它）。
+    pub fn first_failure(&self) -> Option<(Level, Skip)> {
+        const LEVELS: [Level; 3] = [Level::BackgroundImage, Level::Wallpaper, Level::Preset];
+        LEVELS
+            .into_iter()
+            .find_map(|level| match self.outcome(level) {
+                Outcome::Failed(skip) => Some((level, skip)),
+                _ => None,
+            })
+    }
+
+    /// UI 提示键（`None` = 无需提示）。
+    ///
+    /// 形如 `palette.hint.background.low-chroma`，`key` 稳定、可持久化进日志；
+    /// 本 crate 不产出人话文案（文案属于 UI 层，D40 的分层纪律），UI 只做查表：
+    ///
+    /// | 键 | 建议文案（`{card}` = `provenance.card.name()`） |
+    /// |---|---|
+    /// | `palette.hint.background.undecodable` | 背景图读取失败，已改用{card}配色 |
+    /// | `palette.hint.background.too-small` | 背景图太小，无法取色，已改用{card}配色 |
+    /// | `palette.hint.background.bad-dimensions` | 背景图数据异常，已改用{card}配色 |
+    /// | `palette.hint.background.no-opaque-pixels` | 背景图几乎全透明，无法取色，已改用{card}配色 |
+    /// | `palette.hint.background.low-chroma` | 背景图颜色太淡，取不出主题色，已改用{card}配色 |
+    /// | `palette.hint.background.contrast` | 背景图配色达不到可读性要求，已改用{card}配色 |
+    /// | `palette.hint.wallpaper.*` | 同上，把「背景图」换成「桌面壁纸」 |
+    /// | `palette.hint.preset.contrast` | 当前配色可读性不足，已自动微调 |
+    /// | `palette.hint.adjusted` | 为可读性微调了少量颜色（`adjustments` 非空但无失败） |
+    ///
+    /// 完整契约（含可选补充提示、持久化纪律、性能账）见
+    /// `DevDocs/SubAgentsTalk/palette-source-contract.md`（该目录是本地文档，不入库）。
+    ///
+    /// 优先级：① 先解释「为什么回落」（第一个失败的层级）→ ② 再说「微调过对比度」。
+    /// 前者对用户更重要：用户看到的是「我的壁纸怎么没生效」，而不是「颜色被调了 2%」。
+    pub fn hint_key(&self) -> Option<&'static str> {
+        if let Some((level, skip)) = self.first_failure() {
+            return Some(match (level, skip) {
+                (Level::BackgroundImage, Skip::Undecodable) => {
+                    "palette.hint.background.undecodable"
+                }
+                (Level::BackgroundImage, Skip::TooSmall { .. }) => {
+                    "palette.hint.background.too-small"
+                }
+                (Level::BackgroundImage, Skip::BadDimensions { .. }) => {
+                    "palette.hint.background.bad-dimensions"
+                }
+                (Level::BackgroundImage, Skip::NoOpaquePixels) => {
+                    "palette.hint.background.no-opaque-pixels"
+                }
+                (Level::BackgroundImage, Skip::LowChroma { .. }) => {
+                    "palette.hint.background.low-chroma"
+                }
+                (Level::BackgroundImage, Skip::Contrast { .. }) => {
+                    "palette.hint.background.contrast"
+                }
+                (Level::Wallpaper, Skip::Undecodable) => "palette.hint.wallpaper.undecodable",
+                (Level::Wallpaper, Skip::TooSmall { .. }) => "palette.hint.wallpaper.too-small",
+                (Level::Wallpaper, Skip::BadDimensions { .. }) => {
+                    "palette.hint.wallpaper.bad-dimensions"
+                }
+                (Level::Wallpaper, Skip::NoOpaquePixels) => {
+                    "palette.hint.wallpaper.no-opaque-pixels"
+                }
+                (Level::Wallpaper, Skip::LowChroma { .. }) => "palette.hint.wallpaper.low-chroma",
+                (Level::Wallpaper, Skip::Contrast { .. }) => "palette.hint.wallpaper.contrast",
+                (Level::Preset, Skip::Contrast { .. }) => "palette.hint.preset.contrast",
+                // 色卡档不存在「解码/彩度」问题；落到这里说明是将来新增的原因，别乱编键。
+                (Level::Preset, _) => "palette.hint.preset.unavailable",
+            });
+        }
+        if !self.adjustments.is_empty() {
+            return Some("palette.hint.adjusted");
+        }
+        None
+    }
+
+    /// 原因码列表（`[级别码, 原因码]`），写日志/上报用；给不了键的细节都在这里。
+    pub fn reason_codes(&self) -> Vec<(&'static str, &'static str)> {
+        const LEVELS: [Level; 3] = [Level::BackgroundImage, Level::Wallpaper, Level::Preset];
+        LEVELS
+            .into_iter()
+            .filter_map(|level| match self.outcome(level) {
+                Outcome::Failed(skip) => Some((level.code(), skip.code())),
+                _ => None,
+            })
+            .collect()
+    }
+}
diff --git a/crates/design/src/palette/resolve/tests.rs b/crates/design/src/palette/resolve/tests.rs
new file mode 100644
index 0000000..36ef697
--- /dev/null
+++ b/crates/design/src/palette/resolve/tests.rs
@@ -0,0 +1,242 @@
+//! `resolve` 的单测：三级优先序、失败回落、以及「回落落点是用户选的卡」这三类断言。
+//!
+//! 与 `mod.rs` 拆开只为单文件 ≤400 行；测试仍属于 `palette::resolve::tests`。
+
+use super::*;
+use crate::color::Color;
+
+fn solid(color: Color, width: u32, height: u32) -> Vec<u8> {
+    let mut out = Vec::with_capacity((width * height * 4) as usize);
+    for _ in 0..(width * height) {
+        out.extend_from_slice(&[color.r, color.g, color.b, color.a]);
+    }
+    out
+}
+
+#[test]
+fn level_one_wins_when_background_is_good() {
+    let pixels = solid(Color::rgb(0xC0, 0x39, 0x2B), 4, 4);
+    let (scheme, provenance) = resolve_source(
+        Some(ImageInput::pixels(&pixels, 4, 4)),
+        None,
+        Some(CardKey::Forest),
+        SchemeFlavor::Light,
+    );
+    assert_eq!(provenance.level, Level::BackgroundImage);
+    assert_eq!(provenance.background(), Outcome::Used);
+    assert_eq!(provenance.preset(), Outcome::NotReached);
+    assert!(provenance.hint_key().is_none());
+    assert!(check(&scheme).is_clean());
+    assert!(provenance.seed.is_some());
+    // 取色方案的表面色温来自当前色卡（森林绿），不是默认卡。
+    assert_eq!(provenance.card, CardKey::Forest);
+}
+
+#[test]
+fn gray_background_falls_back_to_wallpaper_with_reason() {
+    // 反证 1：灰白背景图 → 不许凭空上色，必须带着 low-chroma 原因回落。
+    let gray = solid(Color::rgb(0xF2, 0xF2, 0xF0), 8, 8);
+    let teal = solid(Color::rgb(0x00, 0x79, 0x6B), 8, 8);
+    let (_, provenance) = resolve_source(
+        Some(ImageInput::pixels(&gray, 8, 8)),
+        Some(ImageInput::pixels(&teal, 8, 8)),
+        Some(CardKey::Sky),
+        SchemeFlavor::Light,
+    );
+    assert_eq!(provenance.level, Level::Wallpaper);
+    match provenance.background() {
+        Outcome::Failed(Skip::LowChroma { chroma, .. }) => assert!(chroma < 8.0),
+        other => panic!("背景图应当是低彩度失败，实际 {other:?}"),
+    }
+    assert_eq!(
+        provenance.hint_key(),
+        Some("palette.hint.background.low-chroma")
+    );
+    assert!(provenance.did_fall_back());
+    assert_eq!(
+        provenance.reason_codes(),
+        vec![("background-image", "low-chroma")]
+    );
+}
+
+#[test]
+fn undecodable_and_tiny_inputs_are_distinguished_from_absent() {
+    let tiny = solid(Color::rgb(0xFF, 0x00, 0x00), 1, 2);
+    let (_, provenance) = resolve_source(
+        Some(ImageInput::Undecodable),
+        Some(ImageInput::pixels(&tiny, 1, 2)),
+        None,
+        SchemeFlavor::Dark,
+    );
+    assert_eq!(provenance.level, Level::Preset);
+    assert_eq!(provenance.background(), Outcome::Failed(Skip::Undecodable));
+    assert_eq!(
+        provenance.wallpaper(),
+        Outcome::Failed(Skip::TooSmall {
+            width: 1,
+            height: 2
+        })
+    );
+    assert_eq!(
+        provenance.hint_key(),
+        Some("palette.hint.background.undecodable")
+    );
+    // 从没选过卡 → 出厂默认。
+    assert_eq!(provenance.card, CardKey::Sky);
+}
+
+#[test]
+fn nothing_provided_uses_default_card_without_hint() {
+    let (scheme, provenance) = resolve_source(None, None, None, SchemeFlavor::Light);
+    assert_eq!(provenance.level, Level::Preset);
+    assert_eq!(provenance.preset(), Outcome::Used);
+    assert!(!provenance.did_fall_back());
+    assert!(provenance.adjustments.is_empty());
+    assert!(provenance.hint_key().is_none());
+    assert_eq!(scheme, DEFAULT_CARD.scheme(SchemeFlavor::Light));
+}
+
+#[test]
+fn preset_selection_decides_the_fallback_colour() {
+    // 反证 2：回落落点是「用户选的那张卡」，不是默认卡。
+    let gray = solid(Color::rgb(0x80, 0x80, 0x80), 4, 4);
+    let (scheme, provenance) = resolve_source(
+        Some(ImageInput::pixels(&gray, 4, 4)),
+        None,
+        Some(CardKey::Rose),
+        SchemeFlavor::Light,
+    );
+    assert_eq!(provenance.level, Level::Preset);
+    assert_eq!(provenance.card, CardKey::Rose);
+    assert_eq!(scheme, CardKey::Rose.card().scheme(SchemeFlavor::Light));
+}
+
+#[test]
+fn background_beats_wallpaper_when_both_work() {
+    let bg = solid(Color::rgb(0xB2, 0x6A, 0x00), 8, 8);
+    let wp = solid(Color::rgb(0x00, 0x79, 0x6B), 8, 8);
+    let (_, provenance) = resolve_source(
+        Some(ImageInput::pixels(&bg, 8, 8)),
+        Some(ImageInput::pixels(&wp, 8, 8)),
+        Some(CardKey::Teal),
+        SchemeFlavor::Dark,
+    );
+    assert_eq!(provenance.level, Level::BackgroundImage);
+    assert_eq!(
+        provenance.wallpaper(),
+        Outcome::NotReached,
+        "② 有输入但根本没轮到——不等于「没提供」"
+    );
+    assert!(!provenance.did_fall_back());
+}
+
+#[test]
+fn transparent_background_reports_its_own_reason() {
+    let transparent = solid(Color::rgba(0x3C, 0x8D, 0xBC, 0), 4, 4);
+    let (_, provenance) = resolve_source(
+        Some(ImageInput::pixels(&transparent, 4, 4)),
+        None,
+        None,
+        SchemeFlavor::Light,
+    );
+    assert_eq!(
+        provenance.background(),
+        Outcome::Failed(Skip::NoOpaquePixels)
+    );
+    assert_eq!(
+        provenance.hint_key(),
+        Some("palette.hint.background.no-opaque-pixels")
+    );
+}
+
+#[test]
+fn faint_colour_falls_back_to_the_selected_card() {
+    // 复审 p2-3：D40 的门槛是 8，落在 6~8 之间的图必须**回落**，且落点是用户选中的那张卡。
+    // 变异反证：`MIN_SEED_CHROMA` 8.0 → 6.0 时，这个种子会通过门槛，
+    // `level` 变成 `BackgroundImage`，本条的第一条断言变红。
+    let faint = Color::rgb(0x7E, 0x84, 0x89); // CAM16 chroma ≈ 7.23
+    let pixels = solid(faint, 16, 16);
+    let (scheme, provenance) = resolve_source(
+        Some(ImageInput::pixels(&pixels, 16, 16)),
+        None,
+        Some(CardKey::Amber),
+        SchemeFlavor::Light,
+    );
+
+    assert_eq!(provenance.level, Level::Preset, "低彩度图必须回落");
+    assert_eq!(provenance.card, CardKey::Amber, "落点是用户选中的卡");
+    assert_eq!(
+        scheme,
+        CardKey::Amber.card().scheme(SchemeFlavor::Light),
+        "方案必须逐值等于选中卡"
+    );
+    match provenance.background() {
+        Outcome::Failed(Skip::LowChroma { chroma, .. }) => {
+            assert!((6.0..8.0).contains(&chroma), "实测彩度 {chroma}");
+        }
+        other => panic!("应当是低彩度失败，实际 {other:?}"),
+    }
+}
+
+#[test]
+fn a_five_percent_accent_drives_level_one() {
+    // 端到端反证（与 `palette::seed::tests::end_to_end_picks_the_five_percent_accent` 配对）：
+    // 95% 米白 + 5% 珊瑚的背景图**必须**在一级取色成功，且种子里就是那 5% 的珊瑚。
+    // 若 `analyze_rgba` 退化成「不透明像素求算术平均」，这条会变成「回落色卡」而红。
+    let beige = Color::rgb(0xF5, 0xF1, 0xEA);
+    let coral = Color::rgb(0xFF, 0x6B, 0x5A);
+    let mut pixels = Vec::with_capacity(40 * 40 * 4);
+    for index in 0..40 * 40 {
+        let color = if index < 40 * 40 - 80 { beige } else { coral };
+        pixels.extend_from_slice(&[color.r, color.g, color.b, color.a]);
+    }
+
+    let (scheme, provenance) = resolve_source(
+        Some(ImageInput::pixels(&pixels, 40, 40)),
+        None,
+        Some(CardKey::Rose),
+        SchemeFlavor::Light,
+    );
+    assert_eq!(provenance.level, Level::BackgroundImage, "{provenance:?}");
+    assert_eq!(provenance.background(), Outcome::Used);
+    let seed = provenance.seed.expect("一级成功必须带种子");
+    assert_eq!(seed.color, coral, "种子应当是 5% 的珊瑚");
+    assert!(provenance.hint_key().is_none());
+    // 方案来自珊瑚，而不是「回落到用户选的 Rose 卡」——两者 primary 不同。
+    assert_ne!(scheme, CardKey::Rose.card().scheme(SchemeFlavor::Light));
+    assert!(crate::palette::wcag::check(&scheme).is_clean());
+}
+
+#[test]
+fn not_reached_is_distinguishable_from_not_provided() {
+    // 复审（色彩 r1 p2-2）：`Absent` 曾同时表示「用户没提供」和「更高级成功所以没轮到」，
+    // UI 照字面写「色卡：未选择」就会与事实相反（用户明明选了卡，而且它的中性彩度参与了生成）。
+    let pixels = solid(Color::rgb(0xC0, 0x39, 0x2B), 4, 4);
+
+    // 一级成功：壁纸与色卡都是「没轮到」，但 card 仍然是用户选的那张。
+    let (_, provenance) = resolve_source(
+        Some(ImageInput::pixels(&pixels, 4, 4)),
+        Some(ImageInput::Undecodable), // 壁纸**提供了**，只是没轮到
+        Some(CardKey::Forest),
+        SchemeFlavor::Light,
+    );
+    assert_eq!(provenance.level, Level::BackgroundImage);
+    assert_eq!(provenance.wallpaper(), Outcome::NotReached);
+    assert_eq!(provenance.preset(), Outcome::NotReached);
+    assert_eq!(provenance.card, CardKey::Forest, "没轮到 ≠ 没选择");
+
+    // 真的没提供：背景图 `None` → Absent；壁纸成功 → 色卡 NotReached。
+    let (_, provenance) = resolve_source(
+        None,
+        Some(ImageInput::pixels(&pixels, 4, 4)),
+        Some(CardKey::Forest),
+        SchemeFlavor::Light,
+    );
+    assert_eq!(provenance.background(), Outcome::Absent);
+    assert_eq!(provenance.preset(), Outcome::NotReached);
+    assert_eq!(
+        provenance.reason_codes(),
+        Vec::<(&'static str, &'static str)>::new(),
+        "没提供 / 没轮到都不是「失败」，不该进原因码"
+    );
+}
diff --git a/crates/design/src/palette/score.rs b/crates/design/src/palette/score.rs
new file mode 100644
index 0000000..30445ca
--- /dev/null
+++ b/crates/design/src/palette/score.rs
@@ -0,0 +1,207 @@
+//! 主色簇 → 排序后的候选种子：官方 `Score` 的口径。
+//!
+//! ## 官方怎么挑「最好的那个颜色」
+//!
+//! `Score` 不是「像素最多的颜色」，而是三件事的加权：
+//!
+//! 1. **有人气**：颜色所在**色相桶**（1 度一桶）占全图的像素比例要够大
+//!    （`CUTOFF_EXCITED_PROPORTION = 1%` 以下的色相直接出局）。用色相桶而不是单色占比，
+//!    是为了把「同一个色相的一族明暗」合成人气，而不是让它们互相拆票。
+//! 2. **有颜色**：`CUTOFF_CHROMA = 5` 以下的颜色出局——灰、白、黑再多也不该当种子。
+//! 3. **彩度越高越优先**，但**封顶**：`TARGET_CHROMA = 48` 以上不再加分（否则一张荧光图会被
+//!    推到色域边缘，整套配色的 on-color 会难看得像报警灯）。
+//!
+//! 打分式（官方形状）：
+//!
+//! ```text
+//! excited = 该色所在色相桶的像素占比
+//! chroma_weight = clamp((chroma − 5) / (48 − 5), 0, 1)
+//! score = 0.7 × excited + 0.3 × chroma_weight
+//! ```
+//!
+//! ## 来源等级
+//!
+//! - **A**：四个常数（`CUTOFF_CHROMA = 5`、`CUTOFF_EXCITED_PROPORTION = 0.01`、
+//!   `TARGET_CHROMA = 48`、`WEIGHT_PROPORTION/WEIGHT_CHROMA = 0.7/0.3`）与「按色相桶计人气」
+//!   的做法都来自 `material-color-utilities` 的 `score/Score.java`。
+//! - **B**：把 `excited` 直接当 `proportion` 项用（官方的 `Score` 内部还有一层
+//!   `hueOffset`/`huePopulation` 的除法归一，口径相同、写法不同）。本实现的选择是
+//!   「只看色相桶占比」，因为它是能全单测的最简形式，且与官方在样例图上选出同一个色相。
+//!
+//! 注意与 D40 的彩度门槛（[`super::MIN_SEED_CHROMA`] = 8）的分工：
+//! **这里的 5 是「要不要把它当候选」，那里的 8 是「这个结果够不够格当种子」**。
+//! 一张偏灰的图会有一堆彩度 5~7 的候选通过 `Score`，然后被 8 的门槛挡下并回落到色卡——
+//! 这正是 D40 要的行为（宁可回落，不许凭空上色）。
+
+use super::quantize::Cluster;
+use crate::color::Hct;
+
+/// 彩度下限：低于它的颜色不参与打分（官方 `Score.CUTOFF_CHROMA`）。
+pub(crate) const CUTOFF_CHROMA: f64 = 5.0;
+/// 色相桶人气下限（官方 `Score.CUTOFF_EXCITED_PROPORTION`）。
+pub(crate) const CUTOFF_EXCITED_PROPORTION: f64 = 0.01;
+/// 彩度加分封顶（官方 `Score.TARGET_CHROMA`）。
+pub(crate) const TARGET_CHROMA: f64 = 48.0;
+/// 人气项的权重（官方 `Score.WEIGHT_PROPORTION`）。
+const WEIGHT_PROPORTION: f64 = 0.7;
+/// 彩度项的权重（官方 `Score.WEIGHT_CHROMA`）。
+const WEIGHT_CHROMA: f64 = 0.3;
+
+/// 一个候选种子（含打分所需的中间量，方便测试与提示文案）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub(crate) struct Ranked {
+    /// 候选簇。
+    pub cluster: Cluster,
+    /// 全图像素占比（0..1）。
+    pub share: f64,
+    /// 所在色相桶的像素占比（0..1，官方所谓 excited proportion）。
+    pub excited: f64,
+    /// CAM16 彩度。
+    pub chroma: f64,
+    /// CAM16 色相角。
+    pub hue: f64,
+    /// 最终打分（越大越优先）。
+    pub score: f64,
+}
+
+/// 按官方 `Score` 口径排序候选；被过滤掉的簇不出现在结果里。
+pub(crate) fn rank(clusters: &[Cluster]) -> Vec<Ranked> {
+    let total: u64 = clusters.iter().map(|c| u64::from(c.population)).sum();
+    if total == 0 {
+        return Vec::new();
+    }
+
+    let hcts: Vec<Hct> = clusters.iter().map(|c| Hct::from_color(c.color)).collect();
+    let mut hue_population = [0u64; 360];
+    for (cluster, hct) in clusters.iter().zip(&hcts) {
+        hue_population[hue_bucket(hct.hue)] += u64::from(cluster.population);
+    }
+
+    let mut ranked: Vec<Ranked> = clusters
+        .iter()
+        .zip(&hcts)
+        .filter_map(|(cluster, hct)| {
+            if hct.chroma < CUTOFF_CHROMA {
+                return None;
+            }
+            let share = f64::from(cluster.population) / total as f64;
+            let excited = hue_population[hue_bucket(hct.hue)] as f64 / total as f64;
+            if excited < CUTOFF_EXCITED_PROPORTION {
+                return None;
+            }
+            let chroma_weight =
+                ((hct.chroma - CUTOFF_CHROMA) / (TARGET_CHROMA - CUTOFF_CHROMA)).clamp(0.0, 1.0);
+            Some(Ranked {
+                cluster: *cluster,
+                share,
+                excited,
+                chroma: hct.chroma,
+                hue: hct.hue,
+                score: WEIGHT_PROPORTION * excited + WEIGHT_CHROMA * chroma_weight,
+            })
+        })
+        .collect();
+
+    ranked.sort_by(|a, b| {
+        b.score
+            .partial_cmp(&a.score)
+            .unwrap_or(std::cmp::Ordering::Equal)
+            // 同分时像素多的优先，再同则按色值定序 → 结果完全确定。
+            .then_with(|| b.cluster.population.cmp(&a.cluster.population))
+            .then_with(|| a.cluster.color.r.cmp(&b.cluster.color.r))
+            .then_with(|| a.cluster.color.g.cmp(&b.cluster.color.g))
+            .then_with(|| a.cluster.color.b.cmp(&b.cluster.color.b))
+    });
+    ranked
+}
+
+/// 彩度最高的那个簇——被 `Score` 全部过滤时用它报「这张图最鲜艳的颜色」。
+///
+/// ⚠️ 它**不是**「最接近及格的那一族」：`Score` 的过滤有两道（彩度 ≥5、色相桶人气 ≥1%），
+/// 面积不足 1% 的高彩度颜料会被**人气**刷掉——例如 1592 个米白 + 8 个纯红的图，
+/// 候选为空而这里的「最鲜艳」彩度是 **113.36**。所以调用方的文案要按
+/// 「全图最鲜艳的那一族」，不是「差一点就及格的那一族」。
+///
+/// 取色失败（`Failure::LowChroma`）时**色值与彩度都从这一个簇取**，保证二者成对：
+/// 之前的两条路径一条报 `Score` 榜首、一条报「彩度最高」，而后者还拿着**另一个**簇的色值，
+/// 于是同一个 `LowChroma` 里的 `color` 与 `chroma` 可能不是一回事（复审 r1 p2-4.2）。
+///
+/// 同彩度时取像素多的那一个（结果确定，不受簇顺序影响）。
+pub(crate) fn most_chromatic(clusters: &[Cluster]) -> Option<&Cluster> {
+    clusters.iter().max_by(|a, b| {
+        let key = |cluster: &Cluster| (Hct::from_color(cluster.color).chroma, cluster.population);
+        let (ca, pa) = key(a);
+        let (cb, pb) = key(b);
+        ca.partial_cmp(&cb)
+            .unwrap_or(std::cmp::Ordering::Equal)
+            .then_with(|| pa.cmp(&pb))
+    })
+}
+
+fn hue_bucket(hue: f64) -> usize {
+    let wrapped = hue.rem_euclid(360.0);
+    (wrapped.round() as usize) % 360
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::color::Color;
+
+    fn cluster(hex: &str, population: u32) -> Cluster {
+        Cluster {
+            color: Color::from_hex(hex).expect("合法 hex"),
+            population,
+        }
+    }
+
+    #[test]
+    fn accent_with_small_area_but_high_chroma_transfers_to_seed() {
+        // 95% 米白 + 5% 珊瑚：米白被彩度门槛挡掉，珊瑚当种子。
+        let clusters = [cluster("#F5F1EA", 950), cluster("#FF6B5A", 50)];
+        let ranked = rank(&clusters);
+        assert_eq!(ranked.len(), 1, "{ranked:?}");
+        assert_eq!(ranked[0].cluster.color.to_hex(), "#FF6B5A");
+    }
+
+    #[test]
+    fn grayscale_clusters_are_all_filtered() {
+        let clusters = [
+            cluster("#FFFFFF", 1000),
+            cluster("#808080", 400),
+            cluster("#0A0A0A", 300),
+        ];
+        assert!(rank(&clusters).is_empty());
+        let most = most_chromatic(&clusters).expect("灰图也有簇");
+        assert!(Hct::from_color(most.color).chroma < CUTOFF_CHROMA);
+    }
+
+    #[test]
+    fn tie_break_is_deterministic() {
+        let clusters = [cluster("#3366CC", 100), cluster("#2B6DD0", 100)];
+        let first = rank(&clusters);
+        let second = rank(&clusters);
+        assert_eq!(first.len(), 2);
+        assert_eq!(
+            first.iter().map(|r| r.cluster.color).collect::<Vec<_>>(),
+            second.iter().map(|r| r.cluster.color).collect::<Vec<_>>()
+        );
+    }
+
+    #[test]
+    fn tiny_population_hue_is_ignored() {
+        // 0.5% 的青绿被 excited proportion 门槛（1%）挡掉。
+        let clusters = [cluster("#FF0000", 995), cluster("#00C8B4", 5)];
+        let ranked = rank(&clusters);
+        assert_eq!(ranked.len(), 1);
+        assert_eq!(ranked[0].cluster.color.to_hex(), "#FF0000");
+    }
+
+    #[test]
+    fn hue_bucket_wraps() {
+        assert_eq!(hue_bucket(0.0), 0);
+        assert_eq!(hue_bucket(359.6), 0);
+        assert_eq!(hue_bucket(-1.0), 359);
+        assert_eq!(hue_bucket(720.4), 0);
+    }
+}
diff --git a/crates/design/src/palette/seed/mod.rs b/crates/design/src/palette/seed/mod.rs
new file mode 100644
index 0000000..a2c577a
--- /dev/null
+++ b/crates/design/src/palette/seed/mod.rs
@@ -0,0 +1,267 @@
+//! 已解码的 RGBA 像素 → 一个**种子色**（D38 第一/二级的入口，D40 的 `crates/design` 半边）。
+//!
+//! 这是整个取色链在 `crates/design` 里的**唯一公开入口**：零 IO、零第三方依赖，
+//! 只吃「调用方已经解码好的像素」。解码（PNG/JPEG/WebP…）在 `crates/palette-extract`，
+//! 分层理由见 D40。
+//!
+//! ```no_run
+//! use unlucky_design::color::{Scheme, SchemeFlavor};
+//! use unlucky_design::palette::seed_from_rgba;
+//!
+//! // 一张 2×2 的天蓝图（调用方负责解码）
+//! let pixels: [u8; 16] = [
+//!     0x3C, 0x8D, 0xBC, 0xFF, 0x3C, 0x8D, 0xBC, 0xFF,
+//!     0x3C, 0x8D, 0xBC, 0xFF, 0x3C, 0x8D, 0xBC, 0xFF,
+//! ];
+//! let seed = seed_from_rgba(&pixels, 2, 2).expect("纯色图有确定的种子");
+//! let scheme = seed.scheme(SchemeFlavor::Light, 12.0);
+//! assert!(scheme.contrast(unlucky_design::color::Role::OnPrimary, unlucky_design::color::Role::Primary) >= 4.5);
+//! ```
+//!
+//! ## 五类输入的处置（每类都有单测）
+//!
+//! | 输入 | 处置 | 为什么 |
+//! |---|---|---|
+//! | 过小图（< 4 像素） | [`Failure::TooSmall`] | 1~3 个像素没有「主色」概念，任一个噪点都会变成整套配色 |
+//! | 纯色图（有彩度） | 正常取色 | 单色图只要够鲜艳就是合格的种子（不做特殊化） |
+//! | 灰度/灰白图 | [`Failure::LowChroma`]（**不是**返回青灰色） | D40 实测：零彩度种子的 CAM16 色相恒为 209.49°，硬取色会把灰白壁纸「凭空上色」成青色 `#006874`；极低彩度段色相还是噪声放大器（`#808080` → 209.5°、`#7A7C7E` → 231.2°，摆 22°） |
+//! | 超大图（>65536 像素） | 先按 4^n 块做**块平均**降采样，再量化 | 取色只需要「色彩分布」，不需要分辨率；块平均能保住细纹理的平均色，避免等距抽样在条纹/网格图上走样 |
+//! | 混合透明度（一半不透明一半全透明） | **先按 alpha 过滤、再块平均**（整块全透明则跳过） | 「先平均再比门槛」会把 `255/2 = 127 < 128` 判成全透明，于是 13 万个不透明像素被报成 `NoOpaquePixels`——复审实测踩到的坑 |
+//! | 解码失败 | 不在本 crate：见 `crates/palette-extract` | D40 分层 |
+//!
+//! 阈值 [`MIN_SEED_CHROMA`] = 8 是 **D40 的定案值**（`seed chroma < ~8 视为无信息量`），
+//! 与 [`super::score::CUTOFF_CHROMA`] = 5 分工不同：5 决定「能不能当候选」，8 决定
+//! 「这个候选够不够格当种子」。落在这条缝里（5~8）的图会有一堆候选，最终仍然回落色卡。
+
+use super::quantize;
+use super::score;
+use crate::color::{Color, Palettes, Scheme, SchemeFlavor};
+
+/// 最小像素数：低于它的图没有「主色」可言。
+pub const MIN_PIXELS: u32 = 4;
+/// 参与量化的最大采样点数（块的边长按它反推）。
+pub const MAX_SAMPLES: usize = 65_536;
+/// D40 的种子彩度门槛：低于它视为「这张图没有可用的颜色信息」。
+pub const MIN_SEED_CHROMA: f64 = 8.0;
+/// 「低彩度但可用」的第二道线：落在这条线下的种子会被标成 [`Seed::is_muted`]，
+/// UI 可以提示「从这张图取到的颜色偏灰」。
+pub const MUTED_SEED_CHROMA: f64 = 16.0;
+/// alpha 低于它的像素不参与取色（半透明叠加会让颜色变成「混了背景的假色」）。
+const ALPHA_THRESHOLD: u8 = 128;
+
+/// 取色结果：种子色 + 足以让 UI 解释「为什么是这个颜色」的观感数据。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Seed {
+    /// 种子色。
+    ///
+    /// **只对「传进 [`analyze_rgba`] 的那个缓冲」作保证**：像素数 ≤ [`MAX_SAMPLES`] 时不做块
+    /// 平均，种子是缓冲里真实存在的颜色（代表色取「簇内像素最多的桶里像素原值平均」，
+    /// 纯色图逐通道精确）；更大的缓冲会先块平均，此时可能是平均出来的新颜色。
+    ///
+    /// ⚠️ 整条链上**任何一次缩放**都会破坏「真实颜色」，不只是这一层：`crates/palette-extract`
+    /// 在超过 `MAX_EDGE` 时先用 `thumbnail` 缩放。实测 400×400 红蓝棋盘（每像素交替）：
+    /// `MAX_EDGE = 256`（适配层缩放）与 `MAX_EDGE = 512`（本层块平均）都取到 `#704070`，
+    /// 这个色值在原图上**一个像素都不是**。降采样本来就要平均（顺带降噪），所以这是
+    /// **有意的行为**；不要把它当「绝不出现平均色」的保证，也别拿它判断「这个色在壁纸里存在」。
+    pub color: Color,
+    /// 种子的 CAM16 色相角（度）。
+    pub hue: f64,
+    /// 种子的 CAM16 彩度。
+    pub chroma: f64,
+    /// 该色所在色相族占**有效采样点**的比例（0..1）。
+    ///
+    /// 分母是采样点（块平均后的点、且已剔除透明像素），不是全图像素数。所以只有
+    /// 「无透明 + 像素数 ≤ [`MAX_SAMPLES`]」时它才等于「占全图比例」；大图（有降采样）
+    /// 或有透明区域时只能说「占有效采样点的比例」。
+    pub share: f64,
+}
+
+impl Seed {
+    /// 种子彩度偏低（可用但发灰）——UI 可提示「这张图颜色较淡」。
+    pub fn is_muted(self) -> bool {
+        self.chroma < MUTED_SEED_CHROMA
+    }
+
+    /// 用这个种子生成一套完整调色板（中性彩度由调用方给，通常沿用用户当前选中色卡的取值）。
+    pub fn palettes(self, neutral_chroma: f64) -> Palettes {
+        Palettes::from_seed_with_neutral_chroma(self.color, neutral_chroma)
+    }
+
+    /// 用这个种子生成一套完整方案（49 个角色）。
+    pub fn scheme(self, flavor: SchemeFlavor, neutral_chroma: f64) -> Scheme {
+        Scheme::from_palettes(&self.palettes(neutral_chroma), flavor)
+    }
+}
+
+/// 取色失败的原因。**每一种都要能变成一句人话**（Provenance 用它生成提示）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub enum Failure {
+    /// 像素缓冲长度与 `width × height × 4` 不符（调用方给错了数据）。
+    BadDimensions {
+        /// 宽。
+        width: u32,
+        /// 高。
+        height: u32,
+        /// 期望的字节数（`width × height × 4`）。
+        expected: usize,
+        /// 实际拿到的字节数。
+        actual: usize,
+    },
+    /// 图太小（< [`MIN_PIXELS`] 像素）。
+    TooSmall {
+        /// 宽。
+        width: u32,
+        /// 高。
+        height: u32,
+    },
+    /// 全是透明/半透明像素，没有可用的不透明像素。
+    NoOpaquePixels,
+    /// 彩度不足：`chroma < MIN_SEED_CHROMA`，硬取色会凭空上色。
+    ///
+    /// `color` 与 `chroma` **永远来自同一个簇**（复审 r1 p2-4.2 定的口径）：
+    /// - 有候选（通过 `Score` 的彩度 ≥5 与人气 ≥1% 过滤）但最强候选仍 `< 8` →
+    ///   报 `Score` **榜首**的色值与彩度（它是「本次能拿到的最好候选」）；
+    /// - 一个候选都没有 → 报**彩度最高**的那一簇。
+    ///   这条**不是「灰图专属」**：`Score` 除了彩度 ≥5 还要求所在色相桶的人气 ≥1%，
+    ///   所以「高彩度但面积太小」也会走到这里。实测（复审探针）：40×40、1592 个米白
+    ///   `#F5F1EA` + 8 个纯红 `#FF0000`（0.5% 面积）→ 报回来的彩度是 **113.36**
+    ///   （`#FF0000` 的 CAM16 彩度，见 `color::hct` 的对账表）。
+    ///
+    /// ⚠️ 因此这个数字**不受候选门槛 5 约束**，可能远高于 8。UI 别把它写成
+    /// 「彩度 X < 门槛 8」：真正的失败原因是「没有一族**面积够大**的颜色」。文案用
+    /// 「颜色太淡 / 太杂」即可；要显示数字也只在 `chroma < CUTOFF_CHROMA(5)` 时显示
+    /// （那时的含义才是「整张图没颜色」，即纯灰图）。
+    LowChroma {
+        /// 取色失败时最接近可用的候选色（提示文案里可以显示成一个小色块）。
+        ///
+        /// 注意它不一定「能用」：高彩度但面积很小的颜料（如 0.5% 面积的纯红）也会出现在这里，
+        /// 见 [`Failure::LowChroma`] 的说明。
+        color: Color,
+        /// 该色的实测 CAM16 彩度（与 `color` 成对）。
+        chroma: f64,
+    },
+}
+
+impl Failure {
+    /// 稳定原因码（写日志 / 存设置 / 做提示映射的键，别用 `Debug` 输出）。
+    pub const fn code(self) -> &'static str {
+        match self {
+            Failure::BadDimensions { .. } => "bad-dimensions",
+            Failure::TooSmall { .. } => "too-small",
+            Failure::NoOpaquePixels => "no-opaque-pixels",
+            Failure::LowChroma { .. } => "low-chroma",
+        }
+    }
+}
+
+/// 取色并给出**完整原因**（推荐入口：失败时能生成提示）。
+pub fn analyze_rgba(pixels: &[u8], width: u32, height: u32) -> Result<Seed, Failure> {
+    let total = (width as usize).saturating_mul(height as usize);
+    if total < MIN_PIXELS as usize {
+        return Err(Failure::TooSmall { width, height });
+    }
+    let expected = total.saturating_mul(4);
+    if pixels.len() != expected {
+        return Err(Failure::BadDimensions {
+            width,
+            height,
+            expected,
+            actual: pixels.len(),
+        });
+    }
+
+    // 采样点已经是「只由不透明像素算出的块平均」（见 [`sample_blocks`]），这里不再按 alpha 过滤。
+    let samples = sample_blocks(pixels, width as usize, height as usize);
+    if samples.is_empty() {
+        return Err(Failure::NoOpaquePixels);
+    }
+
+    let clusters = quantize::quantize(&samples);
+    let ranked = score::rank(&clusters);
+    match ranked.first() {
+        Some(best) if best.chroma >= MIN_SEED_CHROMA => Ok(Seed {
+            color: best.cluster.color,
+            hue: best.hue,
+            chroma: best.chroma,
+            share: best.excited,
+        }),
+        // 有候选但都不够鲜艳：报 `Score` 榜首的色值与彩度（`Score` 已经按人气 × 彩度排过序，
+        // 它就是「本次能拿到的最好候选」）。
+        Some(best) => Err(Failure::LowChroma {
+            color: best.cluster.color,
+            chroma: best.chroma,
+        }),
+        // 一个候选都没有：报**彩度最高**的那一族，色值与彩度成对。
+        // 这不等于「整张图没颜色」——1592 米白 + 8 个纯红的图也走这里（红色面积 0.5% 被人气
+        // 门槛淘汰），报回来的彩度是 113.36。真实失败原因是「没有一族面积够大的颜色」。
+        None => {
+            let closest = score::most_chromatic(&clusters);
+            Err(Failure::LowChroma {
+                color: closest
+                    .map(|cluster| cluster.color)
+                    .unwrap_or(Color::rgb(0x80, 0x80, 0x80)),
+                chroma: closest
+                    .map(|cluster| crate::color::Hct::from_color(cluster.color).chroma)
+                    .unwrap_or(0.0),
+            })
+        }
+    }
+}
+
+/// D40 的入口形状：`Option<Seed>`（`None` = 这张图没有可用的颜色信息）。
+///
+/// 需要知道「为什么没有」就用 [`analyze_rgba`]。
+pub fn seed_from_rgba(pixels: &[u8], width: u32, height: u32) -> Option<Seed> {
+    analyze_rgba(pixels, width, height).ok()
+}
+
+/// 块平均降采样：块边长按「不超过 [`MAX_SAMPLES`] 个采样点」反推，小图不降采样（块边长 1）。
+///
+/// **先按 alpha 过滤、再求平均**：块内只累加 `a >= ALPHA_THRESHOLD` 的像素，整块没有有效像素
+/// 就直接跳过（不产出采样点）。
+///
+/// 为什么不能「先平均、再拿平均 alpha 跟门槛比」：块内 alpha 用整数除法截断，
+/// 一半不透明一半透明的块平均下来是 `255/2 = 127 < 128`，于是**整张图被判成「没有不透明像素」**
+/// （复审实测：512×512 里 131072 个完全不透明像素 → `Err(NoOpaquePixels)`）。
+/// 副作用是「半透明像素的颜色」也被排除在外——这是有意的：半透明像素的 RGB 常常是
+/// 未预乘的原始值（有些解码器给的是 0,0,0），混进来会把种子拽向黑色。
+fn sample_blocks(pixels: &[u8], width: usize, height: usize) -> Vec<Color> {
+    let mut block = 1usize;
+    while width.div_ceil(block) * height.div_ceil(block) > MAX_SAMPLES {
+        block += 1;
+    }
+
+    let mut samples = Vec::with_capacity(width.div_ceil(block) * height.div_ceil(block));
+    let mut top = 0usize;
+    while top < height {
+        let bottom = (top + block).min(height);
+        let mut left = 0usize;
+        while left < width {
+            let right = (left + block).min(width);
+            let mut sum = [0u64; 3];
+            let mut count = 0u64;
+            for y in top..bottom {
+                for x in left..right {
+                    let offset = (y * width + x) * 4;
+                    if pixels[offset + 3] < ALPHA_THRESHOLD {
+                        continue;
+                    }
+                    for channel in 0..3 {
+                        sum[channel] += u64::from(pixels[offset + channel]);
+                    }
+                    count += 1;
+                }
+            }
+            if count > 0 {
+                let average = |channel: usize| (sum[channel] / count) as u8;
+                samples.push(Color::rgb(average(0), average(1), average(2)));
+            }
+            left = right;
+        }
+        top = bottom;
+    }
+    samples
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/design/src/palette/seed/tests.rs b/crates/design/src/palette/seed/tests.rs
new file mode 100644
index 0000000..1a65375
--- /dev/null
+++ b/crates/design/src/palette/seed/tests.rs
@@ -0,0 +1,254 @@
+//! `seed` 模块的单测：五类输入各自的处置 + **端到端反证**（不许退化成平均色）。
+//!
+//! 为什么端到端测试必须在这里（而不是只测 `quantize`/`score`）：那两条单测手工构造
+//! `Cluster` 直接喂中间层，**绕过了 `analyze_rgba` 的接线**。把 `analyze_rgba` 换成
+//! 「不透明像素求算术平均」时，中间层单测照样绿，只有这里会红。
+
+use super::*;
+
+/// 生成 `width × height` 的全 `color` 图。
+fn solid(color: Color, width: u32, height: u32) -> Vec<u8> {
+    let mut out = Vec::with_capacity((width * height * 4) as usize);
+    for _ in 0..(width * height) {
+        out.extend_from_slice(&[color.r, color.g, color.b, color.a]);
+    }
+    out
+}
+
+/// 生成「其余是 `base`，`accent_pixels` 个像素是 `accent`」的图（强调色排在末尾）。
+///
+/// 这是**反证「不许取平均色」**的输入构造器：强调色面积小到平均色会被底色吃掉，
+/// 但它是人眼会记住、能当强调色用的那一小撮。
+fn two_tone(width: u32, height: u32, base: Color, accent: Color, accent_pixels: usize) -> Vec<u8> {
+    let total = (width * height) as usize;
+    assert!(accent_pixels <= total);
+    let mut out = Vec::with_capacity(total * 4);
+    for index in 0..total {
+        let color = if index < total - accent_pixels {
+            base
+        } else {
+            accent
+        };
+        out.extend_from_slice(&[color.r, color.g, color.b, color.a]);
+    }
+    out
+}
+
+#[test]
+fn end_to_end_picks_the_five_percent_accent() {
+    // ⚠️ 端到端反证：这条必须走 `analyze_rgba` 的**完整管线**（量化 → 打分 → 彩度门槛），
+    // 不许像 `quantize`/`score` 的单测那样手工构造 `Cluster` 直接喂中间层。
+    // 如果 `analyze_rgba` 被改成「不透明像素求算术平均」，平均值会是米白（chroma ≈4）→
+    // 返回 `LowChroma` 而不是种子，这条立刻红。
+    let beige = Color::from_hex("#F5F1EA").expect("合法 hex");
+    let coral = Color::from_hex("#FF6B5A").expect("合法 hex");
+    let pixels = two_tone(40, 40, beige, coral, 80); // 95% 米白 + 5% 珊瑚
+
+    let seed = analyze_rgba(&pixels, 40, 40).expect("5% 的珊瑚应当被选中当种子");
+    assert_eq!(
+        seed.color,
+        coral,
+        "种子必须是珊瑚（实际 {}）；米白占比 95% 但它不是「主色」",
+        seed.color.to_hex()
+    );
+    assert!(seed.chroma > 40.0, "珊瑚彩度应当很高，实测 {}", seed.chroma);
+    // 与「平均色」泾渭分明：原图的算术平均值是米白，色相/彩度都差一整个量级。
+    assert!(!seed.is_muted());
+}
+
+#[test]
+fn end_to_end_picks_the_three_percent_accent() {
+    // 面积再降到 3%（48/1600）：`Score` 的 1% 人气门槛仍然放行，平均色更不可能靠巧合命中。
+    let beige = Color::from_hex("#F5F1EA").expect("合法 hex");
+    let orange = Color::from_hex("#FF8800").expect("合法 hex");
+    let pixels = two_tone(40, 40, beige, orange, 48);
+
+    let seed = analyze_rgba(&pixels, 40, 40).expect("3% 的橙应当被选中当种子");
+    assert_eq!(seed.color, orange, "实际 {}", seed.color.to_hex());
+    assert!(seed.chroma > 40.0, "彩度 {}", seed.chroma);
+}
+
+#[test]
+fn solid_vivid_image_yields_seed() {
+    let pixels = solid(Color::rgb(0x3C, 0x8D, 0xBC), 4, 4);
+    let seed = analyze_rgba(&pixels, 4, 4).expect("天蓝纯色图有种子");
+    assert_eq!(seed.color, Color::from_hex("#3C8DBC").expect("合法 hex"));
+    assert!(seed.chroma > MIN_SEED_CHROMA);
+    assert!((seed.share - 1.0).abs() < 1.0e-6);
+    assert!(!seed.is_muted());
+}
+
+#[test]
+fn gray_white_image_is_rejected_with_measured_chroma() {
+    // D40 的反证：灰白壁纸硬取色会得到青色 #006874，这里必须拒绝并报出彩度。
+    let pixels = solid(Color::rgb(0xF2, 0xF2, 0xF0), 8, 8);
+    match analyze_rgba(&pixels, 8, 8) {
+        Err(Failure::LowChroma { chroma, .. }) => {
+            assert!(chroma < MIN_SEED_CHROMA, "彩度 {chroma} 不该过门槛");
+        }
+        other => panic!("灰白图必须被拒，实际 {other:?}"),
+    }
+    assert_eq!(seed_from_rgba(&pixels, 8, 8), None);
+}
+
+#[test]
+fn neutral_gray_hash_rejects_instead_of_inventing_cyan() {
+    // 与 M70 复审实测的坏味道对齐：#808080 的 CAM16 色相 209.5°，硬取色会得到青色。
+    let pixels = solid(Color::rgb(0x80, 0x80, 0x80), 4, 4);
+    assert_eq!(seed_from_rgba(&pixels, 4, 4), None);
+}
+
+#[test]
+fn tiny_images_are_too_small() {
+    let pixels = solid(Color::rgb(0xFF, 0x00, 0x00), 1, 3);
+    assert_eq!(
+        analyze_rgba(&pixels, 1, 3),
+        Err(Failure::TooSmall {
+            width: 1,
+            height: 3
+        })
+    );
+    assert_eq!(
+        Failure::TooSmall {
+            width: 1,
+            height: 3
+        }
+        .code(),
+        "too-small"
+    );
+}
+
+#[test]
+fn wrong_buffer_length_is_reported() {
+    let pixels = solid(Color::rgb(0xFF, 0x00, 0x00), 2, 2);
+    match analyze_rgba(&pixels[..12], 2, 2) {
+        Err(Failure::BadDimensions {
+            expected, actual, ..
+        }) => {
+            assert_eq!((expected, actual), (16, 12));
+        }
+        other => panic!("应当报维度错误，实际 {other:?}"),
+    }
+}
+
+#[test]
+fn fully_transparent_image_has_no_seed() {
+    let pixels = solid(Color::rgba(0x3C, 0x8D, 0xBC, 0), 4, 4);
+    assert_eq!(analyze_rgba(&pixels, 4, 4), Err(Failure::NoOpaquePixels));
+}
+
+#[test]
+fn half_transparent_image_keeps_its_opaque_colour() {
+    // 复审 p2-1 的反证：512×512、一半完全不透明砖红、一半全透明（RGB=0）交错。
+    // 修复前「先块平均、再拿平均 alpha 比 128」：块内 255 与 0 平均被整数除法截成 127 < 128，
+    // 于是全部 131072 个不透明像素被判成「没有不透明像素」→ Err(NoOpaquePixels)。
+    // 修复后（先过滤再平均）必须取到砖红本身。
+    let (width, height) = (512usize, 512usize);
+    let mut pixels = Vec::with_capacity(width * height * 4);
+    for index in 0..width * height {
+        if index % 2 == 0 {
+            pixels.extend_from_slice(&[0xC0, 0x39, 0x2B, 0xFF]);
+        } else {
+            pixels.extend_from_slice(&[0x00, 0x00, 0x00, 0x00]);
+        }
+    }
+    let seed = analyze_rgba(&pixels, 512, 512).expect("一半不透明像素必须能取色");
+    assert_eq!(seed.color, Color::rgb(0xC0, 0x39, 0x2B));
+    assert!(seed.chroma > 40.0, "彩度 {}", seed.chroma);
+}
+
+#[test]
+fn mostly_transparent_image_still_samples_the_visible_part() {
+    // 90% 全透明 + 10% 不透明绿：可见部分够鲜艳就该取到它，而不是报「没有不透明像素」。
+    let (width, height) = (64usize, 64usize);
+    let mut pixels = Vec::with_capacity(width * height * 4);
+    for index in 0..width * height {
+        if index % 10 == 0 {
+            pixels.extend_from_slice(&[0x2E, 0x7D, 0x4F, 0xFF]);
+        } else {
+            pixels.extend_from_slice(&[0x00, 0x00, 0x00, 0x00]);
+        }
+    }
+    let seed = analyze_rgba(&pixels, 64, 64).expect("10% 可见像素必须能取色");
+    assert_eq!(seed.color, Color::rgb(0x2E, 0x7D, 0x4F));
+}
+
+#[test]
+fn large_image_is_downsampled_and_still_deterministic() {
+    let (width, height) = (512_u32, 512_u32);
+    let mut pixels = Vec::with_capacity((width * height * 4) as usize);
+    for y in 0..height {
+        for x in 0..width {
+            // 细网格：等距抽样会走样，块平均能得到稳定的底色。
+            let checker = (x + y) % 2 == 0;
+            pixels.extend_from_slice(if checker {
+                &[0xD2, 0x3B, 0x2A, 0xFF]
+            } else {
+                &[0x2A, 0x3B, 0xD2, 0xFF]
+            });
+        }
+    }
+    let first = analyze_rgba(&pixels, width, height).expect("大图有种子");
+    let second = analyze_rgba(&pixels, width, height).expect("可复现");
+    assert_eq!(first, second);
+    let samples = sample_blocks(&pixels, width as usize, height as usize);
+    assert!(
+        samples.len() <= MAX_SAMPLES,
+        "采样点 {} 超标",
+        samples.len()
+    );
+    // 块平均把红蓝网格合成偏紫的中间色，而不是撞上纯红或纯蓝之一。
+    assert!(first.chroma > MIN_SEED_CHROMA, "{first:?}");
+}
+
+#[test]
+fn block_sampling_averages_instead_of_picking() {
+    // 2×2 红蓝棋盘，块边长 1（图很小）→ 4 个采样点；只验证采样点数量与顺序稳定。
+    let pixels = [
+        0xFF, 0x00, 0x00, 0xFF, 0x00, 0x00, 0xFF, 0xFF, 0x00, 0x00, 0xFF, 0xFF, 0xFF, 0x00, 0x00,
+        0xFF,
+    ];
+    let samples = sample_blocks(&pixels, 2, 2);
+    assert_eq!(samples.len(), 4);
+    assert_eq!(samples[0], Color::rgb(0xFF, 0x00, 0x00));
+    assert_eq!(samples[1], Color::rgb(0x00, 0x00, 0xFF));
+}
+
+#[test]
+fn seed_scheme_meets_wcag_on_the_primary_pair() {
+    let pixels = solid(Color::rgb(0xC0, 0x39, 0x2B), 4, 4);
+    let seed = analyze_rgba(&pixels, 4, 4).expect("砖红有种子");
+    for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+        let scheme = seed.scheme(flavor, 12.0);
+        let ratio = scheme.contrast(crate::color::Role::OnPrimary, crate::color::Role::Primary);
+        assert!(ratio >= 4.5, "{flavor:?} 只有 {ratio}");
+    }
+}
+
+#[test]
+fn chroma_just_below_the_gate_is_rejected() {
+    // 把 D40 的口径（`MIN_SEED_CHROMA` = 8，「< ~8 视为无信息量」）钉成可执行的断言：
+    // 图里的颜色实测 chroma ≈7.23 —— 落在 `Score` 的候选门槛（5）之上、D40 的种子门槛（8）之下。
+    // 这类图必须**回落**，而不是「勉强取一个低彩度种子」。
+    //
+    // 变异反证：把 `MIN_SEED_CHROMA` 从 8.0 改成 6.0，这个种子会通过门槛 → 本条变红。
+    let faint = Color::from_hex("#7E8489").expect("合法 hex");
+    let chroma = crate::color::Hct::from_color(faint).chroma;
+    assert!(
+        (6.0..8.0).contains(&chroma),
+        "这条测试依赖「彩度落在 6~8 之间」，实测 {chroma}"
+    );
+
+    let pixels = solid(faint, 16, 16);
+    match analyze_rgba(&pixels, 16, 16) {
+        Err(Failure::LowChroma {
+            chroma: measured, ..
+        }) => {
+            assert!(
+                (6.0..MIN_SEED_CHROMA).contains(&measured),
+                "报回来的彩度 {measured} 应当仍在门槛之下"
+            );
+        }
+        other => panic!("彩度 {chroma} 必须回落，实际 {other:?}"),
+    }
+}
diff --git a/crates/design/src/palette/wcag.rs b/crates/design/src/palette/wcag.rs
new file mode 100644
index 0000000..2830239
--- /dev/null
+++ b/crates/design/src/palette/wcag.rs
@@ -0,0 +1,281 @@
+//! 对比度校验与**收敛**：任意一套方案（不管种子来自图片还是色卡）都要过同一道门。
+//!
+//! 为什么需要这一层：`tests/contrast_aa.rs` 的 208 项门禁只覆盖**候选色卡**（它拿 6 个手挑的
+//! 种子逐对断言）。D38/D40 之后「方案生成」还可能吃图片来的种子，而远程证据不能只靠
+//! 「tone 轴固定所以一定达标」这句话——那条性质对本 crate 的生成器成立，但一旦有人手动改角色、
+//! 或者将来接别的生成器（比如非 TonalSpot 变体），门禁必须当场发现。所以：
+//!
+//! 1. [`check`] 对**任何** [`Scheme`] 跑全表（26 对文字/图标对，AA ≥ 4.5:1）；
+//! 2. [`converge`] 不达标就**沿 tone 轴修正前景色**（保住色相，只动明度），并把每一处修正
+//!    连同「改前/改后的实测对比度」记进 [`Adjustment`]，让 UI 能说「为了可读性微调了强调色」；
+//! 3. 修正后仍然不达标的方案，由 [`super::resolve`] 回落到色卡并在 `Provenance` 里登记原因。
+//!
+//! ## 为什么只改前景、不改背景
+//!
+//! 背景（`surface` / `*-container`）决定整个界面的骨架与层级，改它会让「同一套方案的两个页面
+//! 底色不一样」；前景（`on-*`）本来就是为可读性服务的，动它代价最小。方向也不是猜的：
+//! 背景 tone ≥ 50（浅底）就压暗前景，否则提亮前景——修正方向永远朝着「离背景更远」的那一侧。
+//!
+//! ## 只做 4.5:1 这一档，`outline` 不在门禁里
+//!
+//! M3 里 `outline` 是非文字元素（输入框描边），规范目标是 3:1，且它按设计就贴着 surface；
+//! `outline-variant` 是纯装饰分隔线。这两个的例外登记在 `crates/design/src/color/mod.rs` 的
+//! 「对比度纪律」小节，本模块不重复断言（重复断言只会让两边口径打架）。
+
+use crate::color::{Color, Hct, Role, Scheme};
+
+/// 正文/图标对的 AA 门槛（WCAG 2.x：普通文字 4.5:1）。
+pub const AA_TEXT: f32 = 4.5;
+/// 非文字元素的门槛（描边/图标块 3:1）——本模块不自动收敛这一档，只提供常量给调用方参考。
+pub const AA_NON_TEXT: f32 = 3.0;
+
+/// 文字/图标对（前景, 承载色）。与 `tests/contrast_aa.rs` 的 `TEXT_PAIRS` 同表。
+pub const TEXT_PAIRS: [(Role, Role); 26] = [
+    (Role::OnPrimary, Role::Primary),
+    (Role::OnPrimaryContainer, Role::PrimaryContainer),
+    (Role::OnSecondary, Role::Secondary),
+    (Role::OnSecondaryContainer, Role::SecondaryContainer),
+    (Role::OnTertiary, Role::Tertiary),
+    (Role::OnTertiaryContainer, Role::TertiaryContainer),
+    (Role::OnError, Role::Error),
+    (Role::OnErrorContainer, Role::ErrorContainer),
+    (Role::OnSurface, Role::Surface),
+    (Role::OnSurfaceVariant, Role::SurfaceVariant),
+    (Role::OnBackground, Role::Background),
+    (Role::InverseOnSurface, Role::InverseSurface),
+    (Role::InversePrimary, Role::InverseSurface),
+    (Role::OnPrimaryFixed, Role::PrimaryFixed),
+    (Role::OnPrimaryFixedVariant, Role::PrimaryFixedDim),
+    (Role::OnSecondaryFixed, Role::SecondaryFixed),
+    (Role::OnSecondaryFixedVariant, Role::SecondaryFixedDim),
+    (Role::OnTertiaryFixed, Role::TertiaryFixed),
+    (Role::OnTertiaryFixedVariant, Role::TertiaryFixedDim),
+    (Role::OnSurface, Role::SurfaceContainerLowest),
+    (Role::OnSurface, Role::SurfaceContainerLow),
+    (Role::OnSurface, Role::SurfaceContainer),
+    (Role::OnSurface, Role::SurfaceContainerHigh),
+    (Role::OnSurface, Role::SurfaceContainerHighest),
+    (Role::OnSurfaceVariant, Role::SurfaceContainerHighest),
+    (Role::OnSurfaceVariant, Role::SurfaceContainerLow),
+];
+
+/// 一处不达标。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Failure {
+    /// 前景角色。
+    pub fg: Role,
+    /// 承载色角色。
+    pub bg: Role,
+    /// 实测对比度。
+    pub ratio: f32,
+    /// 要求的下限（目前恒为 [`AA_TEXT`]）。
+    pub required: f32,
+}
+
+/// 一套方案的对比度体检结果。
+#[derive(Debug, Clone, PartialEq)]
+pub struct WcagReport {
+    /// 全部不达标项（空 = 通过）。
+    pub failures: Vec<Failure>,
+    /// 全表里最低的对比度（用来观察「刚好卡线」的方案）。
+    pub worst: f32,
+}
+
+impl WcagReport {
+    /// 是否全部达标。
+    pub fn is_clean(&self) -> bool {
+        self.failures.is_empty()
+    }
+}
+
+/// 对任意方案跑全表断言。
+pub fn check(scheme: &Scheme) -> WcagReport {
+    let mut failures = Vec::new();
+    let mut worst = f32::INFINITY;
+    for (fg, bg) in TEXT_PAIRS {
+        let ratio = scheme.contrast(fg, bg);
+        worst = worst.min(ratio);
+        if ratio < AA_TEXT {
+            failures.push(Failure {
+                fg,
+                bg,
+                ratio,
+                required: AA_TEXT,
+            });
+        }
+    }
+    WcagReport { failures, worst }
+}
+
+/// 一处自动修正的记录（UI 可以拿去写「为可读性微调了强调色」）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Adjustment {
+    /// 被改的角色。
+    pub role: Role,
+    /// 为了跟谁达标而改的（承载色角色）。
+    pub against: Role,
+    /// 改前的色值。
+    pub before: Color,
+    /// 改后的色值。
+    pub after: Color,
+    /// 改前的对比度。
+    pub before_ratio: f32,
+    /// 改后的对比度。
+    pub after_ratio: f32,
+}
+
+/// 不达标就沿 tone 轴修正，返回（修正后的方案, 修正记录）。
+///
+/// 最多三遍：一遍修正后可能让「同一个前景对另一个承载色」变得不达标（例如 `on-surface`
+/// 同时压在 6 个 surface-container 上），多遍保证收敛。修不动的情况（理论上不存在：纯黑/纯白
+/// 对任意背景都 ≥ 4.58:1）会保留原值，由调用方用 [`check`] 复核后决定是否回落。
+pub fn converge(scheme: Scheme) -> (Scheme, Vec<Adjustment>) {
+    let mut colors = [Color::BLACK; 49];
+    for (role, color) in scheme.iter() {
+        colors[role as usize] = color;
+    }
+
+    let mut adjustments = Vec::new();
+    for _ in 0..3 {
+        let mut changed = false;
+        for (fg, bg) in TEXT_PAIRS {
+            let before = colors[fg as usize];
+            let background = colors[bg as usize];
+            let before_ratio = before.contrast_ratio(background);
+            if before_ratio >= AA_TEXT {
+                continue;
+            }
+            let Some(after) = shift_away_from(before, background, AA_TEXT) else {
+                continue;
+            };
+            colors[fg as usize] = after;
+            adjustments.push(Adjustment {
+                role: fg,
+                against: bg,
+                before,
+                after,
+                before_ratio,
+                after_ratio: after.contrast_ratio(background),
+            });
+            changed = true;
+        }
+        if !changed {
+            break;
+        }
+    }
+
+    (Scheme::from_colors(scheme.flavor(), colors), adjustments)
+}
+
+/// 保住色相、压掉彩度地往「离背景更远」的 tone 走，直到达标或到尽头。
+fn shift_away_from(foreground: Color, background: Color, min_ratio: f32) -> Option<Color> {
+    let hct = Hct::from_color(foreground);
+    let darken = background.lstar() >= 50.0;
+    let step = if darken { -4.0 } else { 4.0 };
+    let mut tone = hct.tone.round();
+    for _ in 0..=25 {
+        tone += step;
+        if !(0.0..=100.0).contains(&tone) {
+            break;
+        }
+        // 修正是「为了可读性」而不是「换个品牌色」：色相不动，彩度让求解器自己压到色域内。
+        let candidate = Hct::from_components(hct.hue, hct.chroma, tone).to_color();
+        if candidate.contrast_ratio(background) >= min_ratio {
+            return Some(candidate);
+        }
+    }
+    // 尽头兜底：纯黑/纯白对任何背景都在 4.58:1 以上（中灰处的理论最低点）。
+    let extreme = if darken { Color::BLACK } else { Color::WHITE };
+    (extreme.contrast_ratio(background) >= min_ratio).then_some(extreme)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::color::SchemeFlavor;
+
+    #[test]
+    fn baseline_is_clean() {
+        for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+            let report = check(&Scheme::baseline(flavor));
+            assert!(report.is_clean(), "{flavor:?}: {:?}", report.failures);
+            assert!(report.worst >= AA_TEXT, "{flavor:?} worst {}", report.worst);
+        }
+    }
+
+    #[test]
+    fn hostile_scheme_is_detected() {
+        // 反证：把 on-surface 换成 surface（对比度 1:1），校验器必须报出来。
+        let base = Scheme::baseline(SchemeFlavor::Light);
+        let mut colors = [Color::BLACK; 49];
+        for (role, color) in base.iter() {
+            colors[role as usize] = color;
+        }
+        colors[Role::OnSurface as usize] = base.get(Role::Surface);
+        let hostile = Scheme::from_colors(SchemeFlavor::Light, colors);
+        let report = check(&hostile);
+        assert!(!report.is_clean());
+        assert!(report
+            .failures
+            .iter()
+            .any(|failure| failure.fg == Role::OnSurface && failure.bg == Role::Surface));
+    }
+
+    #[test]
+    fn converge_repairs_a_hostile_scheme() {
+        let base = Scheme::baseline(SchemeFlavor::Light);
+        let mut colors = [Color::BLACK; 49];
+        for (role, color) in base.iter() {
+            colors[role as usize] = color;
+        }
+        colors[Role::OnSurface as usize] = base.get(Role::Surface);
+        colors[Role::OnPrimary as usize] = base.get(Role::Primary);
+        let hostile = Scheme::from_colors(SchemeFlavor::Light, colors);
+
+        let (fixed, adjustments) = converge(hostile);
+        assert!(!adjustments.is_empty(), "应当记录了修正");
+        assert!(check(&fixed).is_clean(), "{:?}", check(&fixed).failures);
+        for adjustment in &adjustments {
+            assert!(adjustment.after_ratio >= AA_TEXT);
+            assert!(adjustment.after_ratio > adjustment.before_ratio);
+        }
+    }
+
+    #[test]
+    fn converge_is_a_no_op_on_a_healthy_scheme() {
+        let clean = Scheme::baseline(SchemeFlavor::Dark);
+        let (fixed, adjustments) = converge(clean);
+        assert!(adjustments.is_empty());
+        assert_eq!(fixed, clean);
+    }
+
+    #[test]
+    fn shift_darkens_on_light_background_and_lightens_on_dark() {
+        let light_bg = Scheme::baseline(SchemeFlavor::Light);
+        let surface = light_bg.get(Role::Surface);
+        let fixed = shift_away_from(surface, surface, 4.5).expect("浅底上前景可以压暗");
+        assert!(
+            fixed.lstar() < surface.lstar() - 20.0,
+            "压暗后 tone = {}",
+            fixed.lstar()
+        );
+        assert!(fixed.contrast_ratio(surface) >= 4.5);
+
+        let dark_bg = Scheme::baseline(SchemeFlavor::Dark);
+        let surface = dark_bg.get(Role::Surface);
+        let fixed = shift_away_from(surface, surface, 4.5).expect("深底上前景可以提亮");
+        assert!(
+            fixed.lstar() > surface.lstar() + 20.0,
+            "提亮后 tone = {}",
+            fixed.lstar()
+        );
+        assert!(fixed.contrast_ratio(surface) >= 4.5);
+        // 色相不跟着动：修正只动明度（改前改后的 CAM16 色相差 < 2°）。
+        let before = Hct::from_color(surface);
+        let after = Hct::from_color(fixed);
+        let delta = (before.hue - after.hue)
+            .abs()
+            .min(360.0 - (before.hue - after.hue).abs());
+        assert!(delta < 2.0, "色相被改了 {delta}°");
+    }
+}
diff --git a/crates/design/src/shape.rs b/crates/design/src/shape.rs
new file mode 100644
index 0000000..fe2e4a1
--- /dev/null
+++ b/crates/design/src/shape.rs
@@ -0,0 +1,313 @@
+//! M3 Expressive 形状刻度 + shape morph 数据。
+//!
+//! 形状是「唯一真源」的一部分：组件不许写裸半径（`border_radius(8)`），一律引用
+//! [`ShapeScale`]；需要动起来的（按下、选中、展开）用 [`ShapeMorph`] 的 from→to 数据。
+//!
+//! ## 圆角分两层（D32）
+//!
+//! 官方实现与官方刻度表并不总一致：Checkbox 的圆角是 **2dp**，但 `ShapeScale` 的刻度是
+//! `{0,4,8,12,16,20,28,32,48,full}`——2 不在里面。D32 的判决是**分层**而不是放宽判据：
+//!
+//! - **容器级**（卡片、弹窗、抽屉、按钮、面板、输入框外壳）只许用 [`ShapeScale`] 的刻度值；
+//! - **微控件级**（≤24dp 的 Checkbox 等）用 [`ComponentRadius`] 的白名单值。
+//!
+//! 一个元素该查哪一层由 [`radius_layer_for`] 判定（按尺寸，唯一入口）；微控件层取值走
+//! [`ComponentRadius::radius_px`]，**尺寸超界时返回 `None`**——这不是文档约定，是签名保证。
+//!
+//! ## 窗口**外框**圆角不在这里（M116）
+//!
+//! `ShapeScale` 管的是**我们画的东西**：卡片、按钮、浮层、面板。窗口的最外层圆角由操作系统
+//! 决定（Win11 / Server 2025 走 DWM 合成器，macOS 走 `layer.cornerRadius`，X11/Wayland 看合成器），
+//! 系统**不暴露**那个半径值，我们也不自己定一个数字（用户定案：不做 8/12/16 档）。
+//! 所以窗口圆角没有令牌：判据在 `unlucky-app-iced` 的 `platform::plan_corner`，
+//! 落点在 `platform/win32/transparency`。
+//!
+//! 反过来说：**别**为了「让窗口看起来是圆的」去给根容器加 `ShapeScale::ExtraLarge`——那会把
+//! 四角裁掉内容（背景图/标题栏底色露出方角），而外框仍然是方的。
+
+use crate::motion::Spring;
+
+/// M3 形状刻度（含 Expressive 新增档）。
+///
+/// 基础档（M3）：none 0 / extra-small 4 / small 8 / medium 12 / large 16 / extra-large 28 / full。
+/// Expressive 新增档：`large-increased` 20 / `extra-large-increased` 32 / `extra-extra-large` 48。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum ShapeScale {
+    /// 直角（0dp）：仅用于贴边容器/分隔。
+    None,
+    /// 4dp：小控件（chip、小徽标）。
+    ExtraSmall,
+    /// 8dp：控件（按钮、输入框、菜单项）。
+    Small,
+    /// 12dp：卡片、列表容器（Expressive 里卡片默认升到这一档）。
+    Medium,
+    /// 16dp：大卡片、面板。
+    Large,
+    /// 20dp（Expressive）：按下/选中时的「胀开」档。
+    LargeIncreased,
+    /// 28dp：浮层、对话框。
+    ExtraLarge,
+    /// 32dp（Expressive）：大浮层、FAB 展开态。
+    ExtraLargeIncreased,
+    /// 48dp（Expressive）：超大容器、模态全屏卡。
+    ExtraExtraLarge,
+    /// 药丸/圆：按边长取半径一半（导航指示条、头像、switch 轨道）。
+    Full,
+}
+
+impl ShapeScale {
+    /// 半径（dp；[`ShapeScale::Full`] 返回 `f32::INFINITY`，由 [`ShapeScale::radius_px`] 折算）。
+    pub const fn dp(self) -> f32 {
+        match self {
+            ShapeScale::None => 0.0,
+            ShapeScale::ExtraSmall => 4.0,
+            ShapeScale::Small => 8.0,
+            ShapeScale::Medium => 12.0,
+            ShapeScale::Large => 16.0,
+            ShapeScale::LargeIncreased => 20.0,
+            ShapeScale::ExtraLarge => 28.0,
+            ShapeScale::ExtraLargeIncreased => 32.0,
+            ShapeScale::ExtraExtraLarge => 48.0,
+            ShapeScale::Full => f32::INFINITY,
+        }
+    }
+
+    /// 实际渲染半径：`Full` 取边长一半，其余不超过边长一半（避免方角变圆角溢出）。
+    pub fn radius_px(self, size_px: f32) -> f32 {
+        let half = size_px.max(0.0) / 2.0;
+        if self == ShapeScale::Full {
+            half
+        } else {
+            self.dp().min(half)
+        }
+    }
+
+    /// 是否是 Expressive 才有的档位（基础 M3 没有）。
+    pub const fn is_expressive(self) -> bool {
+        matches!(
+            self,
+            ShapeScale::LargeIncreased
+                | ShapeScale::ExtraLargeIncreased
+                | ShapeScale::ExtraExtraLarge
+        )
+    }
+
+    /// 在形状阶梯上的序号（0 = None，9 = Full），用于断言形变方向是「胀开」而不是「收紧」。
+    pub const fn rank(self) -> u8 {
+        match self {
+            ShapeScale::None => 0,
+            ShapeScale::ExtraSmall => 1,
+            ShapeScale::Small => 2,
+            ShapeScale::Medium => 3,
+            ShapeScale::Large => 4,
+            ShapeScale::LargeIncreased => 5,
+            ShapeScale::ExtraLarge => 6,
+            ShapeScale::ExtraLargeIncreased => 7,
+            ShapeScale::ExtraExtraLarge => 8,
+            ShapeScale::Full => 9,
+        }
+    }
+}
+
+/// 微控件（≤24dp）的尺寸上限（dp）。
+///
+/// 超过这条线的元素属**容器级**，圆角必须查 [`ShapeScale`] 的严格刻度；[`ComponentRadius`]
+/// 只在这条线以内有效——由 [`ComponentRadius::radius_px`] 在运行期拦住（传大尺寸拿不到微半径）。
+/// 24 这个门槛不是官方数字，是 D32 给「微控件」划的界（Checkbox 20、指示点、徽标都在以内）。
+pub const MICRO_CONTROL_MAX_SIZE: f32 = 24.0;
+
+/// 微控件圆角（D32 第二层）：**来源官方组件实现，不是 [`ShapeScale`] 的成员**。
+///
+/// 为什么要有这一层：官方 Checkbox 的圆角是 **2dp**（`Checkbox.kt:738 RadiusSize = 2.dp`，
+/// `CheckboxTokens.ContainerShape = RoundedCornerShape(2)`），而 M3 形状刻度只有
+/// `{0,4,8,12,16,20,28,32,48,full}`。把 2 塞进刻度会废掉「无任意圆角」这条守门（D30 rubric K1），
+/// 不收又只能在组件里抄 `2.0` 字面量。D32 的判决是**分层**，不是放宽：
+///
+/// | 层 | 管什么 | 取值 |
+/// |---|---|---|
+/// | [`ShapeScale`] | 容器级：卡片/弹窗/抽屉/按钮/面板/输入框外壳 | 严格刻度，不许自造 |
+/// | `ComponentRadius` | 微控件级：Checkbox 等 ≤24dp 的元素 | 白名单，当前只有 [`ComponentRadius::Micro`] |
+///
+/// 用法：先 [`radius_layer_for`] 判层，微控件再 `radius_px(size)`。**返回 `None` 说明尺寸超界，
+/// 必须改查 [`ShapeScale`]**，不许把微半径硬套到容器上。
+///
+/// 公开的**唯一取值口是 [`ComponentRadius::radius_px`]**（带尺寸闸）：本类型的 `dp()` 是
+/// `pub(crate)`，故意不对外开放——否则任何调用方都能无条件拿到 `2.0`，「只许 ≤24dp」就成了
+/// 自觉而不是约束（D32 的原意是拦住，不是提醒）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum ComponentRadius {
+    /// 2dp：官方 Checkbox 容器圆角。
+    Micro,
+}
+
+impl ComponentRadius {
+    /// 白名单里的全部微半径（D32 当前只有一项；加值必须先在 `design-令牌约定` 登记）。
+    ///
+    /// 枚举得出的只是**变体**（`Micro` 这个名字），拿不到数值——取值必须走 [`Self::radius_px`]。
+    pub const ALL: [ComponentRadius; 1] = [ComponentRadius::Micro];
+
+    /// 半径（dp）。**`pub(crate)`：crate 内推导与自己用，不对外开放。**
+    ///
+    /// 对任何尺寸都返回同一个数，所以它天然绕开 D32 的尺寸闸；对外只留
+    /// [`Self::radius_px`]（`Option<f32>`，>24dp 返回 `None`）。
+    pub(crate) const fn dp(self) -> f32 {
+        match self {
+            ComponentRadius::Micro => 2.0,
+        }
+    }
+
+    /// 微控件的实际半径：尺寸超过 [`MICRO_CONTROL_MAX_SIZE`] 时返回 **`None`**。
+    ///
+    /// 这是 D32 里「能编译期拦住就别靠自觉」的落点——文档约定拦不住，签名拦得住：
+    /// 拿到 `None` 的调用点没法「顺手用一下 2dp」，只能改查 [`ShapeScale`]。
+    /// 另外半径不超过边长一半（2dp 半径放到更小的元素上会溢成圆）。
+    pub fn radius_px(self, size_px: f32) -> Option<f32> {
+        if size_px > 0.0 && size_px <= MICRO_CONTROL_MAX_SIZE {
+            Some(self.dp().min(size_px / 2.0))
+        } else {
+            None
+        }
+    }
+}
+
+/// 一个元素的圆角该查哪一层（[`radius_layer_for`] 的返回）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum RadiusLayer {
+    /// 容器级：查 [`ShapeScale`] 的严格刻度。
+    Scale,
+    /// 微控件级（≤24dp）：查 [`ComponentRadius`] 的白名单。
+    Component,
+}
+
+/// 纯函数：按元素尺寸判定圆角该查哪一层。
+///
+/// 「某尺寸的元素该查哪一个」是 D32 里唯一需要判断的地方，所以只留这一个入口——
+/// 组件层不许自己写 `if size <= 24.0`，那等于把阈值抄了第二份。
+pub fn radius_layer_for(size_px: f32) -> RadiusLayer {
+    if size_px > 0.0 && size_px <= MICRO_CONTROL_MAX_SIZE {
+        RadiusLayer::Component
+    } else {
+        RadiusLayer::Scale
+    }
+}
+
+/// 一次形状形变（Expressive 的「按下胀开」「展开成药丸」等）。
+///
+/// 数据形态是纯的：起止档位 + 弹簧参数。适配层负责跑时钟，`progress` 由弹簧/缓动给出。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct ShapeMorph {
+    /// 静息档位。
+    pub from: ShapeScale,
+    /// 目标档位。
+    pub to: ShapeScale,
+    /// 驱动这次形变的弹簧。
+    pub spring: Spring,
+}
+
+impl ShapeMorph {
+    /// 恒定弹簧的形变。
+    pub const fn new(from: ShapeScale, to: ShapeScale, spring: Spring) -> Self {
+        Self { from, to, spring }
+    }
+
+    /// 在 `progress`（0..1，已含缓动）处的半径。`Full` 端点按 `size_px` 折算。
+    pub fn radius_px(&self, size_px: f32, progress: f32) -> f32 {
+        let t = progress.clamp(0.0, 1.0);
+        let a = self.from.radius_px(size_px);
+        let b = self.to.radius_px(size_px);
+        a + (b - a) * t
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::motion::SPRING_EXPRESSIVE_SPATIAL_DEFAULT;
+
+    #[test]
+    fn scale_ladder_is_monotone() {
+        let ladder = [
+            ShapeScale::None,
+            ShapeScale::ExtraSmall,
+            ShapeScale::Small,
+            ShapeScale::Medium,
+            ShapeScale::Large,
+            ShapeScale::LargeIncreased,
+            ShapeScale::ExtraLarge,
+            ShapeScale::ExtraLargeIncreased,
+            ShapeScale::ExtraExtraLarge,
+        ];
+        for pair in ladder.windows(2) {
+            assert!(
+                pair[0].dp() < pair[1].dp(),
+                "{:?} 应小于 {:?}",
+                pair[0],
+                pair[1]
+            );
+        }
+    }
+
+    #[test]
+    fn full_is_half_of_edge_and_clamped() {
+        assert_eq!(ShapeScale::Full.radius_px(48.0), 24.0);
+        assert_eq!(ShapeScale::ExtraLarge.radius_px(20.0), 10.0);
+        assert_eq!(ShapeScale::ExtraLarge.radius_px(200.0), 28.0);
+        assert_eq!(ShapeScale::None.radius_px(200.0), 0.0);
+    }
+
+    #[test]
+    fn morph_hits_both_endpoints() {
+        let morph = ShapeMorph::new(
+            ShapeScale::Small,
+            ShapeScale::LargeIncreased,
+            SPRING_EXPRESSIVE_SPATIAL_DEFAULT,
+        );
+        assert_eq!(morph.radius_px(200.0, 0.0), 8.0);
+        assert_eq!(morph.radius_px(200.0, 1.0), 20.0);
+        assert_eq!(morph.radius_px(200.0, 0.5), 14.0);
+        // 越界 progress 夹取，不产生负半径/超大半径。
+        assert_eq!(morph.radius_px(200.0, -2.0), 8.0);
+        assert_eq!(morph.radius_px(200.0, 3.0), 20.0);
+    }
+
+    #[test]
+    fn component_radius_is_whitelisted_and_refuses_containers() {
+        // D32：微半径白名单当前只有 2dp，且永远不是 ShapeScale 的成员。
+        assert_eq!(ComponentRadius::ALL.len(), 1);
+        assert_eq!(ComponentRadius::Micro.dp(), 2.0);
+        for scale in [
+            ShapeScale::None,
+            ShapeScale::ExtraSmall,
+            ShapeScale::Small,
+            ShapeScale::Medium,
+            ShapeScale::Large,
+            ShapeScale::LargeIncreased,
+            ShapeScale::ExtraLarge,
+            ShapeScale::ExtraLargeIncreased,
+            ShapeScale::ExtraExtraLarge,
+        ] {
+            assert_ne!(scale.dp(), 2.0, "{scale:?} 不该等于微半径（2 不在刻度里）");
+        }
+
+        // 20×20 的 checkbox 拿 2dp；超 24 的元素必须拿不到。
+        assert_eq!(ComponentRadius::Micro.radius_px(20.0), Some(2.0));
+        assert_eq!(ComponentRadius::Micro.radius_px(24.0), Some(2.0));
+        assert_eq!(ComponentRadius::Micro.radius_px(24.5), None);
+        assert_eq!(ComponentRadius::Micro.radius_px(200.0), None);
+        assert_eq!(ComponentRadius::Micro.radius_px(0.0), None);
+        // 半径不超过边长一半。
+        assert_eq!(ComponentRadius::Micro.radius_px(2.0), Some(1.0));
+    }
+
+    #[test]
+    fn radius_layer_follows_the_size_threshold() {
+        assert_eq!(radius_layer_for(20.0), RadiusLayer::Component);
+        assert_eq!(
+            radius_layer_for(MICRO_CONTROL_MAX_SIZE),
+            RadiusLayer::Component
+        );
+        assert_eq!(radius_layer_for(24.5), RadiusLayer::Scale);
+        assert_eq!(radius_layer_for(320.0), RadiusLayer::Scale);
+        assert_eq!(radius_layer_for(0.0), RadiusLayer::Scale);
+    }
+}
diff --git a/crates/design/src/spacing.rs b/crates/design/src/spacing.rs
new file mode 100644
index 0000000..618a471
--- /dev/null
+++ b/crates/design/src/spacing.rs
@@ -0,0 +1,290 @@
+//! 形状 / 高程 / 动效之外的「尺子」：4px 栅格、骨架尺寸、一像素线。
+//!
+//! 源流有两条：`DevDocs/ops/slint-reference/crates/app/ui/theme/metrics.slint`（M52 定稿的骨架节奏），
+//! 以及 `ui-integration-contract.md` §3「间距只允许 4/8/12/16/24/32」。M3 同样用 4dp 栅格，
+//! 所以这层**不用改口径**，只是把值搬进唯一真源。
+//!
+//! ## 职责边界：`LayoutMetrics` vs `ComponentMetrics`（M69 / G10）
+//!
+//! | 结构 | 管什么 | 例子 |
+//! |---|---|---|
+//! | [`LayoutMetrics`] | **窗口骨架与布局节奏**：标题栏/页头/行的节奏、dock 宽度（导航、AI 面板）、命中区 | [`LayoutMetrics::nav_drawer_width`] / [`LayoutMetrics::search_bar_height`] / `touch_target` |
+//! | `component_map::ComponentMetrics` | **单个控件内部几何**：外框尺寸、微圆角、描边/环线宽、状态层直径、内点、图标偏移 | checkbox 20×20 + 描边 2 + 状态层 Ø40 |
+//! | [`stroke::HAIRLINE`] | **一像素线**的唯一真源：分隔线厚度、容器描边、聚焦指示 | [`LayoutMetrics::divider_thickness`] |
+//!
+//! 判据：一个值若随窗口/列宽变化、或决定一块面板占多宽，归 LM；若它只在某个控件自己的方框
+//! 内起作用（画进去的那几个像素），归 CM。**同一个值不许两边各写一份**。
+
+/// 一像素线（G12）：全站 1px 线的**唯一真源**。
+///
+/// 为什么要单独开一个命名空间：`1.0` 在项目里同时承担三种语义——分隔线厚度、容器描边宽度、
+/// 聚焦指示描边宽度。各自抄字面量就会漂成 1.0 / 1.5 / 2.0 混排（M66 的 G12 正是这么来的）。
+/// 从这里取，语义和数值只有一个落点。
+///
+/// iced 侧怎么落地（适配层照此抄，别再自己定 `STROKE_PX`）：
+/// - **容器描边**：`Border { width: unlucky_design::stroke::HAIRLINE, .. }`（卡片/输入框/chip/菜单）；
+/// - **分隔线**：[`LayoutMetrics::divider_thickness`]（数值就是 [`stroke::HAIRLINE`]）——
+///   横向分隔线是容器高度、纵向是宽度，都取它；
+/// - **聚焦环**：内描边与外描边**都用**它（M3 的聚焦指示是 1dp，做成 2dp 就是加粗）；
+/// - **不用于**：elevation 的 blur / offset（那是 [`crate::elevation`] 的量）、
+///   图标描边（图标走 SVG 的 viewBox 单位，见 [`crate::icons::stroke_width_for`]）。
+pub mod stroke {
+    /// 一像素线宽度（逻辑 px @100% DPI = 1dp；DividerTokens.Thickness）。
+    pub const HAIRLINE: f32 = 1.0;
+}
+
+/// 栅格基数（dp）。
+pub const GRID: f32 = 4.0;
+
+/// 间距档位（M3/M2 通用 4px 栅格）。禁止 6/10/14 这类非整倍数值。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Space {
+    /// 4dp：图标与文字之间。
+    X1,
+    /// 8dp：控件内边距、行内元素间距。
+    X2,
+    /// 12dp：控件间距。
+    X3,
+    /// 16dp：区块内行距、卡片内边距下限。
+    X4,
+    /// 24dp：区块间距、页面内边距。
+    X6,
+    /// 32dp：页级大留白。
+    X8,
+}
+
+impl Space {
+    /// 间距值（dp）。
+    pub const fn dp(self) -> f32 {
+        match self {
+            Space::X1 => 4.0,
+            Space::X2 => 8.0,
+            Space::X3 => 12.0,
+            Space::X4 => 16.0,
+            Space::X6 => 24.0,
+            Space::X8 => 32.0,
+        }
+    }
+
+    /// 全部档位，由小到大。
+    pub const ALL: [Space; 6] = [
+        Space::X1,
+        Space::X2,
+        Space::X3,
+        Space::X4,
+        Space::X6,
+        Space::X8,
+    ];
+}
+
+/// 把任意数值对齐到 4px 栅格（最近档）。
+pub fn snap_to_grid(value: f32) -> f32 {
+    (value / GRID).round() * GRID
+}
+
+/// 骨架尺寸：窗口结构（标题栏、导航、页头、行高）的单一来源。
+///
+/// 这些值不是 M3 规范值（M3 只规定组件内部节奏），而是本启动器的**布局契约**，
+/// 由页面/组件两条线共同消费——任何页面自己写 `56px` 都是重复定义。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct LayoutMetrics {
+    /// 标题栏高度。
+    pub titlebar_height: f32,
+    /// 标题栏按钮宽度（关闭/最大化/最小化）。
+    pub titlebar_button_width: f32,
+    /// 展开态导航（drawer 形态）宽度。
+    ///
+    /// **G11 语义修正（M69 / D33）**：D16「左侧固定、允许折叠」落地为**同一个常驻容器**的两种
+    /// 宽度——展开 240（drawer）、折叠 88（rail）。旧字段 `nav_expanded_width = 88` 的名字与值
+    /// 相反（88 其实是 rail），已删除，**不留别名**：两个名字指同一个量等于把选择权还给组件层。
+    ///
+    /// 官方 `NavigationDrawerTokens.ContainerWidth = 360`、`MinimumDrawerWidth = 240`；
+    /// 本项目取官方下限 240——360 + AI 面板 320 = 680 = 1180 窗宽的 58%，内容区只剩 500 放不下两列卡片。
+    pub nav_drawer_width: f32,
+    /// 折叠态导航（rail 形态）宽度。
+    ///
+    /// 88 = 12b §5.1 对官方 rail 96 的登记偏离（−8）：指示器宽 88 − 2×16 = 56 仍成立，
+    /// 再窄就装不下 56 宽的选中指示器。
+    pub nav_rail_width: f32,
+    /// 搜索条高度（G11）。
+    ///
+    /// 官方 `SearchBarTokens.ContainerHeight = 56`。**不走 [`LayoutMetrics::control_height`]（40）**：
+    /// 搜索条是页级入口而不是密集行控件；56 也顺带 ≥ 命中下限 48。圆角由 `ShapeScale::Full`
+    /// 按边长折算（56 → 28，正好等于官方 `SearchBarCornerRadius`）。
+    pub search_bar_height: f32,
+    /// 分隔线厚度（G11 + G12）。
+    ///
+    /// 官方 `DividerTokens.Thickness = 1.0.dp`。值就是 [`stroke::HAIRLINE`]——**一像素线不受 4px
+    /// 栅格约束**，所以它不在栅格测试的表里（测试里显式豁免并写明原因）。
+    pub divider_thickness: f32,
+    /// 导航项高度。
+    pub nav_item_height: f32,
+    /// 导航项间距。
+    pub nav_item_gap: f32,
+    /// 单行页头高度。
+    pub page_header_height: f32,
+    /// 两行页头高度（日志页）。
+    pub page_header_tall_height: f32,
+    /// 运行中状态条高度。
+    pub running_strip_height: f32,
+    /// 列表行高（桌面密集列表；见模块文档的「触控目标」说明）。
+    pub row_height: f32,
+    /// 标准控件可见高度（按钮/输入框）。
+    pub control_height: f32,
+    /// 最小**命中**区域（M3 Expressive 的无障碍下限）。
+    pub touch_target: f32,
+    /// 卡片内边距。
+    pub card_padding: f32,
+    /// AI 面板宽度。
+    pub ai_panel_width: f32,
+}
+
+impl LayoutMetrics {
+    /// 桌面基线（1180×760 窗口）。
+    ///
+    /// **触控目标的换算依据**（reviewer P3-1：不许和 `metrics.slint` 沉默地不一致）：
+    /// - 规范：M3 Expressive 要求可点目标 ≥**48dp**（无障碍下限，手机与桌面同标准）。
+    /// - 我们取 `touch_target = 48`（照规范），`control_height = 40`（**可见**高度）：
+    ///   两者差 8，正好由控件上下各 4px 的内边距补足，于是「看起来 40 高的按钮」有 48 的命中区。
+    /// - `row_height = 44` / `nav_item_height = 44` 是 M63 §R13 + §1.4 表定的桌面密集档
+    ///   （`metrics.slint` 的导航 56 是 Fluent 2 时代的旧节奏，D25 已终止）：可见高度 44，
+    ///   点击命中也按 `touch_target`（48）判定，不靠行高本身。
+    /// - `titlebar_height = 48` 取自 M63 §1.4 的 S2 面板表（旧值 40 是 Fluent 口径）。
+    pub const DESKTOP: Self = Self {
+        titlebar_height: 48.0,
+        titlebar_button_width: 46.0,
+        // G11 / D33：展开 = drawer 240，折叠 = rail 88（旧 `nav_expanded_width=88` /
+        // `nav_collapsed_width=48` 的名字与值相反，已删）。
+        nav_drawer_width: 240.0,
+        nav_rail_width: 88.0,
+        // G11：官方 SearchBarTokens.ContainerHeight = 56。
+        search_bar_height: 56.0,
+        // G11/G12：官方 DividerTokens.Thickness = 1.0dp → 一像素线的唯一真源。
+        divider_thickness: stroke::HAIRLINE,
+        nav_item_height: 44.0,
+        nav_item_gap: 4.0,
+        page_header_height: 56.0,
+        page_header_tall_height: 84.0,
+        running_strip_height: 32.0,
+        row_height: 44.0,
+        control_height: 40.0,
+        touch_target: 48.0,
+        card_padding: 20.0,
+        ai_panel_width: 320.0,
+    };
+}
+
+impl LayoutMetrics {
+    /// 页头是否两行（日志页），决定主区与 AI 面板分隔线对齐的高度。
+    pub fn header_height(&self, two_line: bool) -> f32 {
+        if two_line {
+            self.page_header_tall_height
+        } else {
+            self.page_header_height
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn every_space_is_on_the_grid() {
+        for space in Space::ALL {
+            assert_eq!(space.dp() % GRID, 0.0, "{space:?} 不在 4px 栅格上");
+        }
+    }
+
+    #[test]
+    fn layout_values_are_on_the_grid() {
+        let m = LayoutMetrics::DESKTOP;
+        // 受 4px 栅格约束的字段（间距/高度/宽度类）。
+        // `titlebar_button_width` 刻意不在表内：46 对齐 Windows 11 原生 caption 按钮宽度，
+        // 属 OS 惯例值，单列一条断言钉住，不让它静默漂移。
+        // `divider_thickness` 同理不在表内：它是**一像素线**（1 不是 4 的倍数），
+        // 归 `stroke::HAIRLINE` 那条规则管，下面单独断言。
+        for (name, value) in [
+            ("titlebar_height", m.titlebar_height),
+            ("nav_drawer_width", m.nav_drawer_width),
+            ("nav_rail_width", m.nav_rail_width),
+            ("search_bar_height", m.search_bar_height),
+            ("nav_item_height", m.nav_item_height),
+            ("nav_item_gap", m.nav_item_gap),
+            ("page_header_height", m.page_header_height),
+            ("page_header_tall_height", m.page_header_tall_height),
+            ("running_strip_height", m.running_strip_height),
+            ("row_height", m.row_height),
+            ("control_height", m.control_height),
+            ("touch_target", m.touch_target),
+            ("card_padding", m.card_padding),
+            ("ai_panel_width", m.ai_panel_width),
+        ] {
+            assert_eq!(value % GRID, 0.0, "{name} = {value} 不在 4px 栅格上");
+        }
+        assert_eq!(
+            m.titlebar_button_width, 46.0,
+            "标题栏按钮宽度应对齐 Win11 原生 caption"
+        );
+        // 一像素线的显式豁免（不是「忘了加进表」，是它本来就不受栅格约束）。
+        assert_eq!(m.divider_thickness, stroke::HAIRLINE);
+        assert_ne!(m.divider_thickness % GRID, 0.0);
+    }
+
+    #[test]
+    fn nav_widths_follow_the_two_form_decision() {
+        // D33：左侧导航是同一容器的两种宽度，展开（drawer）必须比折叠（rail）宽。
+        let m = LayoutMetrics::DESKTOP;
+        assert_eq!(m.nav_drawer_width, 240.0, "展开 drawer 取官方下限 240");
+        assert_eq!(m.nav_rail_width, 88.0, "折叠 rail 为 88（登记偏离官方 96）");
+        assert!(m.nav_rail_width < m.nav_drawer_width);
+        // rail 里的选中指示器 = 容器宽 − 2×16；88 − 32 = 56，再窄就装不下 56 宽指示器。
+        assert_eq!(m.nav_rail_width - Space::X4.dp() * 2.0, 56.0);
+        // 内容区下限：1180 窗宽 − drawer − AI 面板 仍 ≥600（够放两列卡片）。
+        assert!(1180.0 - m.nav_drawer_width - m.ai_panel_width >= 600.0);
+    }
+
+    #[test]
+    fn search_bar_height_is_a_page_level_entry() {
+        let m = LayoutMetrics::DESKTOP;
+        assert_eq!(m.search_bar_height, 56.0, "官方 ContainerHeight = 56");
+        assert!(
+            m.search_bar_height >= m.touch_target,
+            "页级入口必须 ≥ 命中下限"
+        );
+        // 圆角走 ShapeScale::Full，56 → 28，正好是官方 SearchBarCornerRadius。
+        assert_eq!(
+            crate::shape::ShapeScale::Full.radius_px(m.search_bar_height),
+            28.0
+        );
+    }
+
+    #[test]
+    fn touch_target_meets_the_expressive_48dp_minimum() {
+        let m = LayoutMetrics::DESKTOP;
+        // M3 Expressive 无障碍下限：可点目标 ≥48dp。
+        assert_eq!(m.touch_target, 48.0);
+        // 可见控件高 + 上下各 4px 内边距 = 命中区。
+        assert_eq!(m.control_height + 2.0 * Space::X1.dp(), m.touch_target);
+        // 密集行（M63 §1.4/R13 的桌面档）可见高度 44，命中仍按 touch_target。
+        assert_eq!(m.row_height, 44.0);
+        assert_eq!(m.nav_item_height, 44.0);
+        assert!(m.row_height <= m.touch_target);
+        // M63 §1.4 的 S2 面板表：标题栏 48。
+        assert_eq!(m.titlebar_height, 48.0);
+    }
+
+    #[test]
+    fn snap_rounds_to_nearest_grid_step() {
+        assert_eq!(snap_to_grid(5.0), 4.0);
+        assert_eq!(snap_to_grid(6.5), 8.0);
+        assert_eq!(snap_to_grid(0.0), 0.0);
+    }
+
+    #[test]
+    fn header_height_follows_line_count() {
+        let m = LayoutMetrics::DESKTOP;
+        assert_eq!(m.header_height(false), 56.0);
+        assert_eq!(m.header_height(true), 84.0);
+    }
+}
diff --git a/crates/design/src/typography/emphasized.rs b/crates/design/src/typography/emphasized.rs
new file mode 100644
index 0000000..c7c2974
--- /dev/null
+++ b/crates/design/src/typography/emphasized.rs
@@ -0,0 +1,88 @@
+//! 官方 M3 **Expressive** 强调排版表（15 档，A 级来源）。
+//!
+//! 来源：`androidx.compose.material3.tokens.TypeScaleTokens` v0_103 的
+//! `<Role>Emphasized{Size,LineHeight,Tracking,Weight}` 四元组。要点：
+//!
+//! - **字号与行高与 baseline 完全相同**（Expressive 的强调不改变排版高度）；
+//! - 只动**字重**与**字距**：display/headline/title-large/body-* → Medium(500)；
+//!   title-medium / title-small / label-* → Bold(700)（baseline 是 500）；
+//! - display-large 的字距从 −0.2 回 0；body-large 0.5 → 0.15；title-medium 0.2 → 0.15；
+//!   body-medium 0.2 → 0.25（唯一一个「强调后字距变大」的档）。
+
+use super::{style, FontFamily, TypeRole, TypeStyle, Weight};
+
+/// 取某档的官方强调样式。非 [`TypeRole`] 的每个变体都有值（15/15，无缺口）。
+pub(super) const fn style_of(role: TypeRole) -> TypeStyle {
+    match role {
+        TypeRole::DisplayLarge => style(57.0, 64.0, Weight::Medium, 0.0, FontFamily::Display),
+        TypeRole::DisplayMedium => style(45.0, 52.0, Weight::Medium, 0.0, FontFamily::Display),
+        TypeRole::DisplaySmall => style(36.0, 44.0, Weight::Medium, 0.0, FontFamily::Display),
+        TypeRole::HeadlineLarge => style(32.0, 40.0, Weight::Medium, 0.0, FontFamily::Display),
+        TypeRole::HeadlineMedium => style(28.0, 36.0, Weight::Medium, 0.0, FontFamily::Display),
+        TypeRole::HeadlineSmall => style(24.0, 32.0, Weight::Medium, 0.0, FontFamily::Display),
+        // TitleLarge 官方用 Brand 族（与 Display 同栈）。
+        TypeRole::TitleLarge => style(22.0, 28.0, Weight::Medium, 0.0, FontFamily::Display),
+        TypeRole::TitleMedium => style(16.0, 24.0, Weight::Bold, 0.15, FontFamily::Text),
+        TypeRole::TitleSmall => style(14.0, 20.0, Weight::Bold, 0.1, FontFamily::Text),
+        TypeRole::BodyLarge => style(16.0, 24.0, Weight::Medium, 0.15, FontFamily::Text),
+        TypeRole::BodyMedium => style(14.0, 20.0, Weight::Medium, 0.25, FontFamily::Text),
+        TypeRole::BodySmall => style(12.0, 16.0, Weight::Medium, 0.4, FontFamily::Text),
+        TypeRole::LabelLarge => style(14.0, 20.0, Weight::Bold, 0.1, FontFamily::Text),
+        TypeRole::LabelMedium => style(12.0, 16.0, Weight::Bold, 0.5, FontFamily::Text),
+        TypeRole::LabelSmall => style(11.0, 16.0, Weight::Bold, 0.5, FontFamily::Text),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn emphasized_keeps_size_and_line_height() {
+        for role in TypeRole::ALL {
+            let base = role.style();
+            let emph = style_of(role);
+            assert_eq!(
+                base.size_px,
+                emph.size_px,
+                "{} 强调档不该改字号",
+                role.name()
+            );
+            assert_eq!(
+                base.line_height_px,
+                emph.line_height_px,
+                "{} 强调档不该改行高",
+                role.name()
+            );
+        }
+    }
+
+    #[test]
+    fn emphasized_weights_follow_the_official_split() {
+        // 官方两档：正文/展示类 → Medium(500)；小标题与标签类 → Bold(700)。
+        for role in TypeRole::ALL {
+            let expect = match role {
+                TypeRole::TitleMedium
+                | TypeRole::TitleSmall
+                | TypeRole::LabelLarge
+                | TypeRole::LabelMedium
+                | TypeRole::LabelSmall => Weight::Bold,
+                _ => Weight::Medium,
+            };
+            assert_eq!(
+                style_of(role).weight,
+                expect,
+                "{} 强调档字重不对",
+                role.name()
+            );
+        }
+    }
+
+    #[test]
+    fn display_large_tracking_returns_to_zero() {
+        assert_eq!(TypeRole::DisplayLarge.style().letter_spacing_px, -0.2);
+        assert_eq!(TypeRole::DisplayLarge.emphasized().letter_spacing_px, 0.0);
+        assert_eq!(TypeRole::BodyLarge.style().letter_spacing_px, 0.5);
+        assert_eq!(TypeRole::BodyLarge.emphasized().letter_spacing_px, 0.15);
+    }
+}
diff --git a/crates/design/src/typography/fonts.rs b/crates/design/src/typography/fonts.rs
new file mode 100644
index 0000000..f1ceede
--- /dev/null
+++ b/crates/design/src/typography/fonts.rs
@@ -0,0 +1,304 @@
+//! 三平台字体族回退栈（Win10+ / macOS 12+ / Linux）+ **字重覆盖**模型。
+//!
+//! 只写族名，不写文件路径、不内嵌字体（D14 + D28）。每条栈的**最后一项必须是通用族名**，
+//! 否则干净安装的系统上会退化成豆腐块。
+//!
+//! ## 为什么要表达「这个族有哪几档字重」
+//!
+//! M3 Expressive 的强调档会要 **700**（title-medium/title-small/label-*）与 **500**
+//! （display/headline/body-*）。而中文字体的字重覆盖差别很大：
+//! **Windows 的 Microsoft YaHei UI 只有 400 / 700 两档**，没有 500；macOS 苹方到 600 就断了、
+//! 没有 700；只有 Linux 常见的 Noto Sans CJK / 思源黑体（可变字体）才 100~900 全覆盖。
+//!
+//! 所以栈项不是「一个族名」，而是 `(族名, 字重覆盖)`（[`FontFace`]），并且提供一个纯函数
+//! [`Platform::resolve_weight`] 说明「这一档字重最终落到哪个族、是原生还是降级」：
+//!
+//! | 结果 | 含义 |
+//! |---|---|
+//! | [`WeightMatch::Native`] | 该族有这一档（可变字体在区间内也算原生） |
+//! | [`WeightMatch::Nearest`] | 该族没有这一档，取最近的静态档（视觉上是「淡一点/粗一点」，不假） |
+//! | [`WeightMatch::Synthetic`] | 最近的档差 ≥2 级（如只有 400 却要 700）→ 引擎**合成加粗**，观感廉价 |
+//!
+//! **合成加粗是降级，不是正常路径**（用户令：不许拿合成加粗当「还原到位」）。
+//! iced/cosmic-text 侧机制：`Font { family, weight, .. }` 由 cosmic-text 按 (family, weight)
+//! 选面，同族缺档时选最近字重；glyphon 另可用 swash 的合成（fake bold）兜底。
+//! 中文缺档时的降级顺序：**① 换下一个有该档的族 → ② 用可变字体的 weight 轴 → ③ 最近静态档
+//! → ④ 最后才是合成加粗**（并且不要用 700 排长中文正文）。
+//!
+//! ## 待确认（D28 联动，不在本 mission 拍板）
+//!
+//! 将来从 CDN 下载中文字体时，「一个 Regular 文件」不够——至少要 400/500/700 三档子集，
+//! 或者一个可变字体（体积更大）。这个差异登记在这里，等 D28 的字体下载 mission 决定。
+
+#[cfg(test)]
+mod tests;
+
+/// 平台（决定字体族回退栈）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Platform {
+    /// Windows 10/11。
+    Windows,
+    /// macOS 12+。
+    MacOs,
+    /// Linux（X11/Wayland，桌面发行版）。
+    Linux,
+}
+
+/// 字重覆盖（一个族实际提供了哪些字重）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum WeightCoverage {
+    /// 可变字体：一个连续区间（weight 轴）。
+    Variable {
+        /// 最细一档。
+        min: u16,
+        /// 最粗一档。
+        max: u16,
+    },
+    /// 静态字体：离散字重表。
+    Static(&'static [u16]),
+}
+
+impl WeightCoverage {
+    /// 是否原生覆盖某档字重。
+    pub fn supports(&self, weight: u16) -> bool {
+        match self {
+            WeightCoverage::Variable { min, max } => (*min..=*max).contains(&weight),
+            WeightCoverage::Static(list) => list.contains(&weight),
+        }
+    }
+
+    /// 最近的可选字重（静态表取绝对值最近；可变字体夹取到区间内）。
+    pub fn nearest(&self, weight: u16) -> u16 {
+        match self {
+            WeightCoverage::Variable { min, max } => weight.clamp(*min, *max),
+            WeightCoverage::Static(list) => {
+                let mut best = list[0];
+                let mut best_delta = u16::MAX;
+                for candidate in *list {
+                    let delta = candidate.abs_diff(weight);
+                    if delta < best_delta {
+                        best = *candidate;
+                        best_delta = delta;
+                    }
+                }
+                best
+            }
+        }
+    }
+}
+
+/// 一条字体栈项：族名 + 字重覆盖。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct FontFace {
+    /// 族名（只写名字，不带路径/文件名）。
+    pub family: &'static str,
+    /// 该族提供的字重。
+    pub weights: WeightCoverage,
+}
+
+impl FontFace {
+    /// 构造。
+    pub const fn new(family: &'static str, weights: WeightCoverage) -> Self {
+        Self { family, weights }
+    }
+
+    /// 该族是否原生覆盖某档字重。
+    pub fn supports(&self, weight: crate::typography::Weight) -> bool {
+        self.weights.supports(weight.value())
+    }
+}
+
+/// 字重匹配的质量。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum WeightMatch {
+    /// 原生有这一档。
+    Native,
+    /// 同族最近档（差 <2 级）。
+    Nearest,
+    /// 差 ≥2 级，引擎只能合成加粗/减细（降级）。
+    Synthetic,
+}
+
+/// 字重解析结果：最终用哪个族、哪个字重、是原生还是降级。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct FontChoice {
+    /// 选中的族名。
+    pub family: &'static str,
+    /// 请求的字重。
+    pub requested: u16,
+    /// 实际可用的字重。
+    pub available: u16,
+    /// 匹配质量。
+    pub quality: WeightMatch,
+}
+
+impl FontChoice {
+    /// 是否走了合成加粗（降级路径）。
+    pub fn is_synthetic(&self) -> bool {
+        self.quality == WeightMatch::Synthetic
+    }
+}
+
+/// 字体族的用途分类（决定取哪条栈）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum FontFamily {
+    /// 大字号展示（display/headline/title-large）：光学尺寸更大。
+    Display,
+    /// 正文（title/body/label）。
+    Text,
+    /// 等宽（日志、代码、版本号）。
+    Mono,
+}
+
+// 字重覆盖来源等级：**B**（各平台字体规格/厂商文档；没有一份官方 token 文件能一次给全，
+// 所以按「常见安装」标定，并用测试钉死——改值要连带改测试与协作文档）。
+const W_VARIABLE_SEGOE: WeightCoverage = WeightCoverage::Variable { min: 300, max: 700 };
+const W_VARIABLE_SF: WeightCoverage = WeightCoverage::Variable { min: 100, max: 900 };
+const W_VARIABLE_NOTO: WeightCoverage = WeightCoverage::Variable { min: 100, max: 900 };
+const W_VARIABLE_CASCADIA: WeightCoverage = WeightCoverage::Variable { min: 200, max: 700 };
+const W_VARIABLE_JETBRAINS: WeightCoverage = WeightCoverage::Variable { min: 100, max: 800 };
+const W_STATIC_SEGOE: WeightCoverage = WeightCoverage::Static(&[300, 400, 600, 700]);
+const W_STATIC_YAHEI: WeightCoverage = WeightCoverage::Static(&[400, 700]);
+const W_STATIC_HELVETICA: WeightCoverage = WeightCoverage::Static(&[300, 400, 500, 700]);
+const W_STATIC_PINGFANG: WeightCoverage = WeightCoverage::Static(&[100, 200, 300, 400, 500, 600]);
+const W_STATIC_MENLO: WeightCoverage = WeightCoverage::Static(&[400, 700]);
+const W_STATIC_DEJAVU: WeightCoverage = WeightCoverage::Static(&[400, 700]);
+
+// 各平台字体栈（写成 const 数组，好让 `font_stack` 的 `const fn` 直接返回 `&'static [_]`）。
+const WIN_DISPLAY: [FontFace; 5] = [
+    FontFace::new("Segoe UI Variable Display", W_VARIABLE_SEGOE),
+    FontFace::new("Segoe UI", W_STATIC_SEGOE),
+    FontFace::new("Microsoft YaHei UI", W_STATIC_YAHEI),
+    FontFace::new("Microsoft YaHei", W_STATIC_YAHEI),
+    FontFace::new("sans-serif", W_VARIABLE_NOTO),
+];
+const WIN_TEXT: [FontFace; 5] = [
+    FontFace::new("Segoe UI Variable Text", W_VARIABLE_SEGOE),
+    FontFace::new("Segoe UI", W_STATIC_SEGOE),
+    FontFace::new("Microsoft YaHei UI", W_STATIC_YAHEI),
+    FontFace::new("Microsoft YaHei", W_STATIC_YAHEI),
+    FontFace::new("sans-serif", W_VARIABLE_NOTO),
+];
+const WIN_MONO: [FontFace; 4] = [
+    FontFace::new("Cascadia Mono", W_VARIABLE_CASCADIA),
+    FontFace::new("Consolas", W_STATIC_SEGOE),
+    FontFace::new("Courier New", W_STATIC_MENLO),
+    FontFace::new("monospace", W_STATIC_DEJAVU),
+];
+const MAC_DISPLAY: [FontFace; 4] = [
+    FontFace::new("SF Pro Display", W_VARIABLE_SF),
+    FontFace::new("Helvetica Neue", W_STATIC_HELVETICA),
+    FontFace::new("PingFang SC", W_STATIC_PINGFANG),
+    FontFace::new("sans-serif", W_VARIABLE_NOTO),
+];
+const MAC_TEXT: [FontFace; 4] = [
+    FontFace::new("SF Pro Text", W_VARIABLE_SF),
+    FontFace::new("Helvetica Neue", W_STATIC_HELVETICA),
+    FontFace::new("PingFang SC", W_STATIC_PINGFANG),
+    FontFace::new("sans-serif", W_VARIABLE_NOTO),
+];
+const MAC_MONO: [FontFace; 4] = [
+    FontFace::new("SF Mono", W_VARIABLE_SF),
+    FontFace::new("Menlo", W_STATIC_MENLO),
+    FontFace::new("Monaco", W_STATIC_MENLO),
+    FontFace::new("monospace", W_STATIC_DEJAVU),
+];
+const LINUX_SANS: [FontFace; 5] = [
+    FontFace::new("Roboto", W_VARIABLE_NOTO),
+    FontFace::new("Noto Sans", W_VARIABLE_NOTO),
+    FontFace::new("Noto Sans CJK SC", W_VARIABLE_NOTO),
+    FontFace::new("DejaVu Sans", W_STATIC_DEJAVU),
+    FontFace::new("sans-serif", W_VARIABLE_NOTO),
+];
+const LINUX_MONO: [FontFace; 4] = [
+    FontFace::new("JetBrains Mono", W_VARIABLE_JETBRAINS),
+    FontFace::new("Noto Sans Mono", W_VARIABLE_NOTO),
+    FontFace::new("DejaVu Sans Mono", W_STATIC_DEJAVU),
+    FontFace::new("monospace", W_STATIC_DEJAVU),
+];
+
+impl Platform {
+    /// 当前编译目标对应的平台（运行时用户覆盖请显式传 [`Platform`]）。
+    pub const fn current() -> Self {
+        if cfg!(target_os = "windows") {
+            Platform::Windows
+        } else if cfg!(target_os = "macos") {
+            Platform::MacOs
+        } else {
+            Platform::Linux
+        }
+    }
+
+    /// 稳定字符串名。
+    pub const fn name(self) -> &'static str {
+        match self {
+            Platform::Windows => "windows",
+            Platform::MacOs => "macos",
+            Platform::Linux => "linux",
+        }
+    }
+
+    /// 字体族回退栈（由首选到兜底，最后一项是通用族名）。
+    pub const fn font_stack(self, family: FontFamily) -> &'static [FontFace] {
+        match (self, family) {
+            // Win10 起 Segoe UI 一定在；Win11 有光学尺寸分离的 Variable 版。
+            (Platform::Windows, FontFamily::Display) => &WIN_DISPLAY,
+            (Platform::Windows, FontFamily::Text) => &WIN_TEXT,
+            (Platform::Windows, FontFamily::Mono) => &WIN_MONO,
+            // macOS 12+：SF Pro 分 Display/Text 光学尺寸；中文走苹方（只到 600）。
+            (Platform::MacOs, FontFamily::Display) => &MAC_DISPLAY,
+            (Platform::MacOs, FontFamily::Text) => &MAC_TEXT,
+            (Platform::MacOs, FontFamily::Mono) => &MAC_MONO,
+            // Linux：不假设发行版预装什么，Roboto/Noto 是最常见的两套（Display 与 Text 同栈）。
+            (Platform::Linux, FontFamily::Display | FontFamily::Text) => &LINUX_SANS,
+            (Platform::Linux, FontFamily::Mono) => &LINUX_MONO,
+        }
+    }
+
+    /// 该平台的**中文**兜底族（CJK 字形实际落到的那个）。
+    ///
+    /// 注意：栈里的 CJK 族只是「缺字形时的候选」，最终由文本引擎逐字形回退决定；
+    /// 这个函数把它单独暴露出来，好让调用方按模块文档的降级顺序处理字重。
+    pub const fn cjk_face(self) -> FontFace {
+        match self {
+            Platform::Windows => FontFace::new("Microsoft YaHei UI", W_STATIC_YAHEI),
+            Platform::MacOs => FontFace::new("PingFang SC", W_STATIC_PINGFANG),
+            Platform::Linux => FontFace::new("Noto Sans CJK SC", W_VARIABLE_NOTO),
+        }
+    }
+
+    /// 按栈顺序解析某档字重的落点（纯函数，不查系统）。
+    ///
+    /// 规则：**优先原生**（栈里第一个真有的族）→ 都做不到时取首选族的最近档，
+    /// 差距 ≥200 判为 [`WeightMatch::Synthetic`]。
+    pub fn resolve_weight(
+        self,
+        family: FontFamily,
+        weight: crate::typography::Weight,
+    ) -> FontChoice {
+        let stack = self.font_stack(family);
+        let requested = weight.value();
+        for face in stack {
+            if face.weights.supports(requested) {
+                return FontChoice {
+                    family: face.family,
+                    requested,
+                    available: requested,
+                    quality: WeightMatch::Native,
+                };
+            }
+        }
+        let first = stack[0];
+        let available = first.weights.nearest(requested);
+        FontChoice {
+            family: first.family,
+            requested,
+            available,
+            quality: if available.abs_diff(requested) >= 200 {
+                WeightMatch::Synthetic
+            } else {
+                WeightMatch::Nearest
+            },
+        }
+    }
+}
diff --git a/crates/design/src/typography/fonts/tests.rs b/crates/design/src/typography/fonts/tests.rs
new file mode 100644
index 0000000..638e976
--- /dev/null
+++ b/crates/design/src/typography/fonts/tests.rs
@@ -0,0 +1,149 @@
+//! 字体栈与字重解析的测试（独立文件是为了守住单文件 ≤400 行的硬约束）。
+
+use super::*;
+use crate::typography::Weight;
+
+const PLATFORMS: [Platform; 3] = [Platform::Windows, Platform::MacOs, Platform::Linux];
+const FAMILIES: [FontFamily; 3] = [FontFamily::Display, FontFamily::Text, FontFamily::Mono];
+
+#[test]
+fn font_stacks_are_well_formed() {
+    for platform in PLATFORMS {
+        for family in FAMILIES {
+            let stack = platform.font_stack(family);
+            assert!(
+                !stack.is_empty(),
+                "{} 的 {family:?} 栈为空",
+                platform.name()
+            );
+            let last = stack[stack.len() - 1].family;
+            let generic = match family {
+                FontFamily::Mono => "monospace",
+                _ => "sans-serif",
+            };
+            assert_eq!(
+                last,
+                generic,
+                "{} 的 {family:?} 栈必须以通用族名兜底",
+                platform.name()
+            );
+            for face in stack {
+                assert!(!face.family.is_empty());
+                assert!(
+                    !face.family.contains(['/', '\\', '.', ':']),
+                    "字体栈只允许族名，不得出现路径/文件名：{}",
+                    face.family
+                );
+                assert!(
+                    face.family.is_ascii(),
+                    "族名应为 ASCII（非 ASCII 名交给系统匹配）：{}",
+                    face.family
+                );
+                // 每条栈项都必须声明字重覆盖（连 400 都没有的族写进栈没有意义）。
+                assert!(
+                    face.supports(Weight::Regular),
+                    "{} 连 400 都没有，写它没意义",
+                    face.family
+                );
+            }
+        }
+    }
+}
+
+#[test]
+fn display_and_text_stacks_differ_on_windows_and_macos() {
+    assert_ne!(
+        Platform::Windows.font_stack(FontFamily::Display)[0].family,
+        Platform::Windows.font_stack(FontFamily::Text)[0].family
+    );
+    assert_ne!(
+        Platform::MacOs.font_stack(FontFamily::Display)[0].family,
+        Platform::MacOs.font_stack(FontFamily::Text)[0].family
+    );
+}
+
+#[test]
+fn chinese_fallback_is_present_but_not_first() {
+    // 中文族名必须在栈里，但不能排第一（纯英文环境不加载中文字体，D28）。
+    for platform in PLATFORMS {
+        let stack = platform.font_stack(FontFamily::Text);
+        let cjk = ["Microsoft YaHei UI", "PingFang SC", "Noto Sans CJK SC"];
+        assert!(
+            stack.iter().any(|face| cjk.contains(&face.family)),
+            "{} 的正文栈缺 CJK 兜底",
+            platform.name()
+        );
+        assert!(
+            !cjk.contains(&stack[0].family),
+            "{} 的首选字体不该是 CJK 族",
+            platform.name()
+        );
+    }
+}
+
+#[test]
+fn cjk_weight_coverage_is_registered() {
+    // 用户点名的坑：中文字重覆盖三平台差别很大。
+    let win = Platform::Windows.cjk_face();
+    assert!(win.supports(Weight::Regular) && win.supports(Weight::Bold));
+    assert!(
+        !win.supports(Weight::Medium),
+        "雅黑没有 500——这条断言就是「中文 500 会掉到降级路径」的登记"
+    );
+    let mac = Platform::MacOs.cjk_face();
+    assert!(mac.supports(Weight::Medium));
+    assert!(
+        !mac.supports(Weight::Bold),
+        "苹方到 600 为止，700 要合成/换族"
+    );
+    let linux = Platform::Linux.cjk_face();
+    for weight in [Weight::Regular, Weight::Medium, Weight::Bold] {
+        assert!(
+            linux.supports(weight),
+            "思源黑体/Noto CJK 应覆盖 400/500/700"
+        );
+    }
+}
+
+#[test]
+fn resolve_prefers_native_and_flags_synthetic() {
+    // Windows 正文 700：Segoe UI Variable 覆盖 → 原生。
+    let bold = Platform::Windows.resolve_weight(FontFamily::Text, Weight::Bold);
+    assert_eq!(bold.quality, WeightMatch::Native);
+    assert_eq!(bold.available, 700);
+    assert!(!bold.is_synthetic());
+    // Linux 正文 500：Roboto 可变 → 原生。
+    assert_eq!(
+        Platform::Linux
+            .resolve_weight(FontFamily::Text, Weight::Medium)
+            .quality,
+        WeightMatch::Native
+    );
+    // 静态族缺档：只有 400 的族请求 700 → nearest 400，差 300 → 判为合成降级。
+    let only_regular = FontFace::new("Courier New", WeightCoverage::Static(&[400]));
+    assert_eq!(only_regular.weights.nearest(700), 400);
+    let synthetic = FontChoice {
+        family: only_regular.family,
+        requested: 700,
+        available: only_regular.weights.nearest(700),
+        quality: WeightMatch::Synthetic,
+    };
+    assert!(synthetic.is_synthetic());
+}
+
+#[test]
+fn nearest_picks_closest_static_weight() {
+    let coverage = WeightCoverage::Static(&[300, 400, 600, 700]);
+    assert_eq!(coverage.nearest(500), 400);
+    assert_eq!(coverage.nearest(650), 600);
+    assert_eq!(coverage.nearest(900), 700);
+    let variable = WeightCoverage::Variable { min: 100, max: 900 };
+    assert_eq!(variable.nearest(500), 500);
+    assert_eq!(variable.nearest(50), 100);
+}
+
+#[test]
+fn current_platform_returns_a_stack() {
+    let platform = Platform::current();
+    assert!(!platform.font_stack(FontFamily::Text).is_empty());
+}
diff --git a/crates/design/src/typography/mod.rs b/crates/design/src/typography/mod.rs
new file mode 100644
index 0000000..45e5153
--- /dev/null
+++ b/crates/design/src/typography/mod.rs
@@ -0,0 +1,346 @@
+//! M3 type scale（15 档，baseline + Expressive 强调两套）+ 三平台字体族回退栈。
+//!
+//! **数值来源 A 级**：`androidx.compose.material3.tokens.TypeScaleTokens`（v0_103）。
+//! baseline 四元组取 `<Role>{Size,LineHeight,Tracking,Weight}`，Expressive 强调档取
+//! `<Role>Emphasized{...}`（见 [`emphasized`] 模块）。注意 Compose 这一代 token 的 tracking 与
+//! m3.material.io 网页表格有 0.05px 级别的差异（display-large −0.2 vs −0.25、body-medium 0.2 vs
+//! 0.25、title-medium 0.2 vs 0.15），本项目跟 **Compose（实际渲染值）**，差异登记在
+//! crate 文档「baseline vs Expressive 差异清单」里。
+//!
+//! **只写字体族名，不内嵌任何字体文件**（Segoe UI / SF Pro / Roboto 都受各自许可约束，
+//! 内嵌再分发是违规的；引用系统已安装的族名是合规且体积为零的做法——这是 D14 与 D28 的共同要求）。
+//! 中文由系统字体匹配：栈里显式列出 CJK 族名，纯英文环境不会去加载任何中文字体（D28）。
+
+mod emphasized;
+mod fonts;
+
+pub use fonts::{FontChoice, FontFace, FontFamily, Platform, WeightCoverage, WeightMatch};
+
+/// 字重（M3 只用这四档；可变字体按连续值渲染时取 [`Weight::value`]）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Weight {
+    /// 400：正文。
+    Regular,
+    /// 500：label / title-medium / Expressive 强调的正文与展示类。
+    Medium,
+    /// 600：本项目的「区块标题」档（介于 Medium 与 Bold 之间）。
+    SemiBold,
+    /// 700：页面标题 / 空态主文案 / Expressive 强调的 label 与 title-small-medium。
+    Bold,
+}
+
+impl Weight {
+    /// 数值字重（CSS/OpenType 口径）。
+    pub const fn value(self) -> u16 {
+        match self {
+            Weight::Regular => 400,
+            Weight::Medium => 500,
+            Weight::SemiBold => 600,
+            Weight::Bold => 700,
+        }
+    }
+
+    /// 再重一档（最重封顶 Bold）。
+    pub const fn heavier(self) -> Self {
+        match self {
+            Weight::Regular => Weight::Medium,
+            Weight::Medium => Weight::SemiBold,
+            Weight::SemiBold | Weight::Bold => Weight::Bold,
+        }
+    }
+}
+
+/// 一条排版样式（已解析成渲染要用的四个数）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct TypeStyle {
+    /// 字号（px；1.0 缩放时与 dp 同值）。
+    pub size_px: f32,
+    /// 行高（px）。
+    pub line_height_px: f32,
+    /// 字重。
+    pub weight: Weight,
+    /// 字间距（px；M3 的 type scale 用 px 表达，中文场景下正字距更易读）。
+    pub letter_spacing_px: f32,
+    /// 用哪条字体栈。
+    pub family: FontFamily,
+}
+
+impl TypeStyle {
+    /// 按用户字号缩放（`factor` 1.0 = 标准；行高与字距同比例，夹取到 0.5..2.0）。
+    pub fn scaled(self, factor: f32) -> Self {
+        let f = factor.clamp(0.5, 2.0);
+        Self {
+            size_px: self.size_px * f,
+            line_height_px: self.line_height_px * f,
+            letter_spacing_px: self.letter_spacing_px * f,
+            ..self
+        }
+    }
+
+    /// 该样式的字体族回退栈（栈项带字重覆盖，见 [`FontFace`]）。
+    pub fn font_stack(self, platform: Platform) -> &'static [FontFace] {
+        platform.font_stack(self.family)
+    }
+
+    /// 该样式在这台平台上「字重最终落到哪个族」——中文缺档时看它判断是否走降级。
+    pub fn resolve(self, platform: Platform) -> FontChoice {
+        platform.resolve_weight(self.family, self.weight)
+    }
+}
+
+/// M3 type scale 的 15 个角色。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum TypeRole {
+    /// 57/64：落地页大标题（本启动器基本不用）。
+    DisplayLarge,
+    /// 45/52。
+    DisplayMedium,
+    /// 36/44。
+    DisplaySmall,
+    /// 32/40：空态主标题的大档。
+    HeadlineLarge,
+    /// 28/36。
+    HeadlineMedium,
+    /// 24/32。
+    HeadlineSmall,
+    /// 22/28：页面标题（导航栏下的主标题）。
+    TitleLarge,
+    /// 16/24：卡片标题。
+    TitleMedium,
+    /// 14/20：行标题。
+    TitleSmall,
+    /// 16/24：正文大档（说明文字）。
+    BodyLarge,
+    /// 14/20：默认正文。
+    BodyMedium,
+    /// 12/16：辅助说明。
+    BodySmall,
+    /// 14/20：按钮文字。
+    LabelLarge,
+    /// 12/16：标签、徽标。
+    LabelMedium,
+    /// 11/16：最小标签（谨慎使用，中文 11px 可读性差）。
+    LabelSmall,
+}
+
+impl TypeRole {
+    /// 全部 15 档，按 M3 的族序排列。
+    pub const ALL: [TypeRole; 15] = [
+        TypeRole::DisplayLarge,
+        TypeRole::DisplayMedium,
+        TypeRole::DisplaySmall,
+        TypeRole::HeadlineLarge,
+        TypeRole::HeadlineMedium,
+        TypeRole::HeadlineSmall,
+        TypeRole::TitleLarge,
+        TypeRole::TitleMedium,
+        TypeRole::TitleSmall,
+        TypeRole::BodyLarge,
+        TypeRole::BodyMedium,
+        TypeRole::BodySmall,
+        TypeRole::LabelLarge,
+        TypeRole::LabelMedium,
+        TypeRole::LabelSmall,
+    ];
+
+    /// 稳定字符串名（`display-large` … `label-small`）。
+    pub const fn name(self) -> &'static str {
+        match self {
+            TypeRole::DisplayLarge => "display-large",
+            TypeRole::DisplayMedium => "display-medium",
+            TypeRole::DisplaySmall => "display-small",
+            TypeRole::HeadlineLarge => "headline-large",
+            TypeRole::HeadlineMedium => "headline-medium",
+            TypeRole::HeadlineSmall => "headline-small",
+            TypeRole::TitleLarge => "title-large",
+            TypeRole::TitleMedium => "title-medium",
+            TypeRole::TitleSmall => "title-small",
+            TypeRole::BodyLarge => "body-large",
+            TypeRole::BodyMedium => "body-medium",
+            TypeRole::BodySmall => "body-small",
+            TypeRole::LabelLarge => "label-large",
+            TypeRole::LabelMedium => "label-medium",
+            TypeRole::LabelSmall => "label-small",
+        }
+    }
+
+    /// **baseline MD3** 样式（官方 type scale 值：字号 / 行高 / 字重 / 字距 + 字体族分类）。
+    pub const fn style(self) -> TypeStyle {
+        match self {
+            TypeRole::DisplayLarge => style(57.0, 64.0, Weight::Regular, -0.2, FontFamily::Display),
+            TypeRole::DisplayMedium => style(45.0, 52.0, Weight::Regular, 0.0, FontFamily::Display),
+            TypeRole::DisplaySmall => style(36.0, 44.0, Weight::Regular, 0.0, FontFamily::Display),
+            TypeRole::HeadlineLarge => style(32.0, 40.0, Weight::Regular, 0.0, FontFamily::Display),
+            TypeRole::HeadlineMedium => {
+                style(28.0, 36.0, Weight::Regular, 0.0, FontFamily::Display)
+            }
+            TypeRole::HeadlineSmall => style(24.0, 32.0, Weight::Regular, 0.0, FontFamily::Display),
+            // 官方 TitleLarge 用 Brand 族（与 Display 同栈），其余 title 用 Plain（Text）。
+            TypeRole::TitleLarge => style(22.0, 28.0, Weight::Regular, 0.0, FontFamily::Display),
+            TypeRole::TitleMedium => style(16.0, 24.0, Weight::Medium, 0.2, FontFamily::Text),
+            TypeRole::TitleSmall => style(14.0, 20.0, Weight::Medium, 0.1, FontFamily::Text),
+            TypeRole::BodyLarge => style(16.0, 24.0, Weight::Regular, 0.5, FontFamily::Text),
+            TypeRole::BodyMedium => style(14.0, 20.0, Weight::Regular, 0.2, FontFamily::Text),
+            TypeRole::BodySmall => style(12.0, 16.0, Weight::Regular, 0.4, FontFamily::Text),
+            TypeRole::LabelLarge => style(14.0, 20.0, Weight::Medium, 0.1, FontFamily::Text),
+            TypeRole::LabelMedium => style(12.0, 16.0, Weight::Medium, 0.5, FontFamily::Text),
+            TypeRole::LabelSmall => style(11.0, 16.0, Weight::Medium, 0.5, FontFamily::Text),
+        }
+    }
+
+    /// **M3 Expressive** 官方强调档（15/15 全有值，A 级来源）。
+    ///
+    /// 规则（官方）：字号与行高不变；字重升到 500（展示/正文类）或 700（label 与小标题）；
+    /// 字距按官方表微调（display-large −0.2→0、body-large 0.5→0.15、title-medium 0.2→0.15、
+    /// body-medium 0.2→0.25）。这是**官方值，不是我们的近似**。
+    pub const fn emphasized(self) -> TypeStyle {
+        emphasized::style_of(self)
+    }
+
+    /// **简化强调规则（非官方）**：只把字重升一级，字号/行高/字距全不动。
+    ///
+    /// 用途：需要在「同一 role 内加强语气但不想引入任何字距变化」的场合（例如同屏多行标题
+    /// 需要严格对齐基线网格时）。**优先用 [`TypeRole::emphasized`]**——那才是 Expressive 的定义。
+    pub const fn emphasized_simplified(self) -> TypeStyle {
+        let base = self.style();
+        TypeStyle {
+            weight: base.weight.heavier(),
+            ..base
+        }
+    }
+}
+
+/// `const fn` 用的构造器。
+const fn style(
+    size: f32,
+    line_height: f32,
+    weight: Weight,
+    tracking_px: f32,
+    family: FontFamily,
+) -> TypeStyle {
+    TypeStyle {
+        size_px: size,
+        line_height_px: line_height,
+        weight,
+        letter_spacing_px: tracking_px,
+        family,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn every_role_has_sane_metrics() {
+        for role in TypeRole::ALL {
+            let s = role.style();
+            assert!(s.size_px >= 11.0, "{} 字号过小", role.name());
+            assert!(
+                s.line_height_px >= s.size_px,
+                "{} 行高小于字号（{} < {}）",
+                role.name(),
+                s.line_height_px,
+                s.size_px
+            );
+            assert!(
+                (1.1..=1.8).contains(&(s.line_height_px / s.size_px)),
+                "{} 行高倍数 {} 超出 1.1..1.8（M3 的行高是 1.12~1.5 量级）",
+                role.name(),
+                s.line_height_px / s.size_px
+            );
+            assert!(s.letter_spacing_px.abs() < 1.0, "{} 字距过大", role.name());
+        }
+    }
+
+    #[test]
+    fn each_family_is_monotone_by_size() {
+        // M3 的 type scale 是「五族 × 三档」，跨族不保证单调（title-small 14 → body-large 16），
+        // 但族内必须由大到小。
+        for family in [
+            [
+                TypeRole::DisplayLarge,
+                TypeRole::DisplayMedium,
+                TypeRole::DisplaySmall,
+            ],
+            [
+                TypeRole::HeadlineLarge,
+                TypeRole::HeadlineMedium,
+                TypeRole::HeadlineSmall,
+            ],
+            [
+                TypeRole::TitleLarge,
+                TypeRole::TitleMedium,
+                TypeRole::TitleSmall,
+            ],
+            [
+                TypeRole::BodyLarge,
+                TypeRole::BodyMedium,
+                TypeRole::BodySmall,
+            ],
+            [
+                TypeRole::LabelLarge,
+                TypeRole::LabelMedium,
+                TypeRole::LabelSmall,
+            ],
+        ] {
+            for pair in family.windows(2) {
+                assert!(
+                    pair[0].style().size_px > pair[1].style().size_px,
+                    "{} 应大于 {}",
+                    pair[0].name(),
+                    pair[1].name()
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn names_are_unique_and_kebab() {
+        let mut seen = std::collections::BTreeSet::new();
+        for role in TypeRole::ALL {
+            let name = role.name();
+            assert!(seen.insert(name), "排版角色名重复：{name}");
+            assert!(name.chars().all(|c| c.is_ascii_lowercase() || c == '-'));
+        }
+    }
+
+    #[test]
+    fn simplified_emphasis_only_bumps_weight() {
+        for role in TypeRole::ALL {
+            let base = role.style();
+            let emph = role.emphasized_simplified();
+            assert_eq!(base.size_px, emph.size_px);
+            assert_eq!(base.line_height_px, emph.line_height_px);
+            assert_eq!(base.letter_spacing_px, emph.letter_spacing_px);
+            assert!(emph.weight.value() > base.weight.value() || base.weight == Weight::Bold);
+        }
+    }
+
+    #[test]
+    fn official_emphasis_is_at_least_as_heavy_as_baseline() {
+        for role in TypeRole::ALL {
+            assert!(
+                role.emphasized().weight.value() >= role.style().weight.value(),
+                "{} 的官方强调档不该比 baseline 更轻",
+                role.name()
+            );
+            assert_ne!(
+                role.emphasized(),
+                role.style(),
+                "{} 强调档与 baseline 相同",
+                role.name()
+            );
+        }
+    }
+
+    #[test]
+    fn scaling_is_proportional_and_bounded() {
+        let base = TypeRole::BodyMedium.style();
+        let big = base.scaled(1.25);
+        assert!((big.size_px - 17.5).abs() < 1.0e-4);
+        assert!((big.line_height_px - 25.0).abs() < 1.0e-4);
+        assert_eq!(base.scaled(10.0).size_px, base.size_px * 2.0);
+        assert_eq!(base.scaled(0.1).size_px, base.size_px * 0.5);
+    }
+}
diff --git a/crates/design/tests/card_neutral.rs b/crates/design/tests/card_neutral.rs
new file mode 100644
index 0000000..fe858b7
--- /dev/null
+++ b/crates/design/tests/card_neutral.rs
@@ -0,0 +1,400 @@
+//! D43：内置色卡的**固定中性色相**——切卡只换强调色，窗口底色的冷暖不跟着换。
+//!
+//! ## 这条测试要钉住的五件事
+//!
+//! 1. **天蓝卡（出厂默认）逐值不变**：固定的中性色相等于天蓝档的中性色相，所以天蓝卡必须与
+//!    [`Scheme::baseline`] 的 49 个角色**逐个相等**（M70 定案的不动点，p1 级硬约束）。
+//! 2. **八张卡的表面色完全相同**：`surface` 的 CAM16 色相一致（±1°）、实测彩度落在窄带内
+//!    （±1.5），且改前那条「9 倍差」被同时量出来当反证（见 `the_old_per_card_tinting...`）。
+//! 3. **动态路径不许被顺手改成固定中性**：这条必须走 **`resolve_source` 公开入口**测——
+//!    `Card::scheme` 那一层根本没有「取色」这回事，测它等于测空气（复审 r1 p1-1 就是这个：
+//!    把 `resolve::try_level` 的取色分支改成固定中性，8 条测试全绿）。见
+//!    `resolved_image_scheme_keeps_tinting_from_the_seed`。
+//! 4. **WCAG 不因换中性色相而掉档**：8 张卡 × 浅/深两套 × 26 对文字/图标对全部 ≥ 4.5:1。
+//! 5. 想让「八卡同底色」的带宽松掉，`the_old_per_card_tinting...` 会红（它量的是改前路径）。
+//!
+//! ## 为什么容差是这个带宽（不是随手取整）
+//!
+//! - **色相 ±1°**：八张卡现在共用一个中性调色板，`surface` 是**同一个 hex**，跨卡差实测 0.00°。
+//!   容差留 1° 是为了挡住「将来某张卡偷偷换回 TonalSpot」——那种回退的最小偏离是 **43°**
+//!   （dusk 280.31° vs 236.86°），1° 的带宽足以把 0 与 43° 分开，同时不误报 8 bit 量化。
+//! - **彩度 ±1.5（CAM16，单位与请求值 12 同刻度）**：tone 98 的 8 bit 量化会把「请求 12」
+//!   读回成 6.41（浅）/11.70（深），这层压缩是**同一个 hex 的常数偏移**，跨卡比较时抵消；
+//!   真正的危险是暖相回退——rose 1.29、amber 1.89，比基线低 4.5~5.1，远超 1.5 的带宽；
+//!   紫相（lavender 5.87）只低 0.54，靠上面的色相断言抓（298° 偏 61°）。带宽取 1.5 = 请求
+//!   彩度的 1/8，比「改前最小的一张卡偏离基线」还小，所以「9 倍差回来了」一定红。
+//!
+//! 改前/改后的 `surface` 实测表在子模块 [`dump`]（那里同时是验收图的数据源）。
+
+// 子模块放在 `tests/card_neutral/` 目录里（cargo 只把 `tests/*.rs` 顶层文件当一个 target，
+// 目录里的文件不会被当成独立 target；crate 根的子模块默认在 `tests/` 下找，所以显式 `#[path]`）。
+#[path = "card_neutral/common.rs"]
+mod common;
+#[path = "card_neutral/dump.rs"]
+mod dump;
+
+use common::{before_d43, flavors, hue_gap};
+use unlucky_design::color::{
+    Hct, Role, Scheme, SchemeFlavor, DEFAULT_NEUTRAL_CHROMA, NEUTRAL_HUE_DEG,
+};
+use unlucky_design::palette::card::card_scheme_is_readable;
+use unlucky_design::palette::{
+    resolve_source, Card, CardKey, ImageInput, Level, CARDS, DEFAULT_CARD, TEXT_PAIRS,
+};
+
+/// 天蓝卡就是产品默认色：固定的中性色相**沿用**它，所以 49 个角色必须一位不差。
+///
+/// 这条是 M88 的 p1 级硬约束。它红了只说明一件事：把「沿用天蓝的中性」实现成了「另选一个中性」。
+#[test]
+fn sky_card_is_bit_identical_to_the_product_baseline() {
+    for flavor in flavors() {
+        let baseline = Scheme::baseline(flavor);
+        let sky = DEFAULT_CARD.scheme(flavor);
+        for (role, got) in sky.iter() {
+            assert_eq!(
+                got,
+                baseline.get(role),
+                "天蓝卡（出厂默认）的 {} / {} 变了：{} → {}",
+                role.name(),
+                flavor.name(),
+                baseline.get(role).to_hex(),
+                got.to_hex()
+            );
+        }
+    }
+}
+
+/// 八张卡的 `surface` 共用同一个中性调色板：色相一致（±1°）、彩度落在窄带（±1.5）。
+#[test]
+fn preset_cards_share_one_neutral_hue_and_chroma() {
+    for flavor in flavors() {
+        let hcts: Vec<(&str, Hct)> = CARDS
+            .iter()
+            .map(|card| {
+                (
+                    card.key,
+                    Hct::from_color(card.scheme(flavor).get(Role::Surface)),
+                )
+            })
+            .collect();
+        let reference = hcts[0].1;
+        for (key, hct) in &hcts {
+            assert!(
+                hue_gap(hct.hue, reference.hue) <= 1.0,
+                "{key} / {} 的 surface 色相 {:.2}° 偏离基线 {:.2}° 超过 ±1°",
+                flavor.name(),
+                hct.hue,
+                reference.hue
+            );
+            assert!(
+                (hct.chroma - reference.chroma).abs() <= 1.5,
+                "{key} / {} 的 surface 实测彩度 {:.2} 偏离基线 {:.2} 超过 ±1.5",
+                flavor.name(),
+                hct.chroma,
+                reference.chroma
+            );
+        }
+        // 更强的口径：八张卡的 surface 是**同一个色值**（不只是「相近」）。
+        let surfaces: Vec<String> = CARDS
+            .iter()
+            .map(|card| card.scheme(flavor).get(Role::Surface).to_hex())
+            .collect();
+        assert!(
+            surfaces.iter().all(|hex| hex == &surfaces[0]),
+            "{} 模式下八张卡的 surface 不再逐值相同：{surfaces:?}",
+            flavor.name()
+        );
+    }
+}
+
+/// 反证：上面那条断言**量得出**问题。改前的路径浅色档彩度差 9 倍，改成固定中性后只剩 1 倍。
+///
+/// 没有这条的话，「±1.5 的带宽」只是一句自我声明：谁把断言写松（比如改成 ±20），
+/// `preset_cards_share_one_neutral_hue_and_chroma` 照样绿，而窗口又开始逐卡染色。
+///
+/// ⚠️ **9 倍差只出现在浅色档**：tone 98（近白）的暖相色域装不下彩度 12，rose 只兑现到 1.29；
+/// 深色档的 tone 6 反而每张卡都装得下（11.63~12.45，只差 1.07 倍）。深色档的问题不是彩度，
+/// 而是**色相**（14.66°~300.57°，整整一个色环）——它在深底上表现为「有的卡偏紫、有的偏绿」。
+/// 所以两个模式的反证分开断言，别用一条 `> 8` 覆盖两个模式（那样深色档会红，且说不清为什么）。
+#[test]
+fn the_old_per_card_tinting_really_was_a_ninefold_gap() {
+    let surface_hct = |scheme: &dyn Fn(Card) -> Scheme| {
+        CARDS
+            .iter()
+            .map(|card| Hct::from_color(scheme(*card).get(Role::Surface)))
+            .collect::<Vec<_>>()
+    };
+    let chroma_ratio = |hcts: &[Hct]| {
+        let max = hcts.iter().map(|h| h.chroma).fold(f64::MIN, f64::max);
+        let min = hcts.iter().map(|h| h.chroma).fold(f64::MAX, f64::min);
+        max / min
+    };
+    let hue_span = |hcts: &[Hct]| {
+        // 色相是环：这里只关心「跨了多少」，用最大凸包跨度（简单排序后首尾差）就够粗判。
+        let mut hues: Vec<f64> = hcts.iter().map(|h| h.hue).collect();
+        hues.sort_by(|a, b| a.partial_cmp(b).expect("有限色相"));
+        hues[hues.len() - 1] - hues[0]
+    };
+
+    // 浅色档：彩度 9 倍差（改前）→ 1 倍（改后）。
+    let old_light = surface_hct(&|card| before_d43(card, SchemeFlavor::Light));
+    assert!(
+        chroma_ratio(&old_light) > 8.0,
+        "改前（浅色）的 surface 彩度差应当能量出「9 倍级」跳变，实测 {:.2} 倍——\
+         这条反证已经失效，上面的 ±1.5 带宽就不可信了",
+        chroma_ratio(&old_light)
+    );
+    let new_light = surface_hct(&|card| card.scheme(SchemeFlavor::Light));
+    assert!(
+        chroma_ratio(&new_light) < 1.5,
+        "固定中性后（浅色）八张卡的 surface 彩度差还有 {:.2} 倍",
+        chroma_ratio(&new_light)
+    );
+
+    // 深色档：彩度本来就一致，问题是色相跨了整个环 → 改后色相跨度收敛到 0。
+    let old_dark = surface_hct(&|card| before_d43(card, SchemeFlavor::Dark));
+    assert!(
+        hue_span(&old_dark) > 180.0,
+        "改前（深色）的 surface 色相应当横跨大半个色环，实测 {:.2}°",
+        hue_span(&old_dark)
+    );
+    assert!(
+        chroma_ratio(&old_dark) < 1.5,
+        "改前（深色）的彩度本来就一致（tone 6 装得下彩度 12），实测 {:.2} 倍",
+        chroma_ratio(&old_dark)
+    );
+    let new_dark = surface_hct(&|card| card.scheme(SchemeFlavor::Dark));
+    assert!(
+        hue_span(&new_dark) < 1.0,
+        "改后（深色）色相跨度 {:.2}°",
+        hue_span(&new_dark)
+    );
+    assert!(chroma_ratio(&new_dark) < 1.5);
+}
+
+/// 换卡只换强调族：不随强调色变的角色必须逐值相同，强调族必须真的换。
+///
+/// 「哪些角色属于强调族」不靠手抄清单，而是**实测**：拿另一个强调色再生成一套方案，值会变的
+/// 那些角色就是强调族（primary/secondary/tertiary 全族 + `surface-tint` + `inverse-primary` +
+/// 12 个 `*-fixed*` = 26 个），不随强调色变的 23 个（中性表面、描边、error、shadow/scrim）
+/// 则必须留在基线——这样将来往 tone 表里加角色也不会漏掉分类。
+///
+/// ⚠️ 浅色档只有 **23** 个会变：`on-primary` / `on-secondary` / `on-tertiary` 的 tone 是 100，
+/// 任何色相都解析成纯白，所以强调色换了它们也不变（深色档的 tone 是 20，会变）。
+#[test]
+fn cards_only_change_the_accent_families() {
+    for flavor in flavors() {
+        let baseline = Scheme::baseline(flavor);
+        let recolored = Scheme::from_accent(flavor, CardKey::Teal.card().seed);
+        let (mut accent_roles, mut neutral_roles) = (Vec::new(), Vec::new());
+        for role in Role::ALL {
+            if recolored.get(role) == baseline.get(role) {
+                neutral_roles.push(role);
+            } else {
+                accent_roles.push(role);
+            }
+        }
+        assert_eq!(
+            (accent_roles.len(), neutral_roles.len()),
+            if flavor.is_dark() { (26, 23) } else { (23, 26) },
+            "强调族 / 中性族的划分变了（{} 模式下换强调色会动 {} 个）",
+            flavor.name(),
+            accent_roles.len()
+        );
+
+        let sky = DEFAULT_CARD.scheme(flavor);
+        for card in CARDS {
+            let scheme = card.scheme(flavor);
+            for role in &neutral_roles {
+                assert_eq!(
+                    scheme.get(*role),
+                    sky.get(*role),
+                    "{} / {} 的 {}（不随强调色变的角色）不该跟着卡变",
+                    card.key,
+                    flavor.name(),
+                    role.name()
+                );
+            }
+            if card.key != DEFAULT_CARD.key {
+                assert_ne!(
+                    scheme.get(Role::Primary),
+                    sky.get(Role::Primary),
+                    "{} / {} 的主色与天蓝卡相同：卡没生效",
+                    card.key,
+                    flavor.name()
+                );
+            }
+        }
+    }
+}
+
+/// 卡方案 = 用该卡种子做「自定义强调色」：中性表面留在基线，强调族与官方 `from_seed` 对得上。
+///
+/// 这条把 D43 接到已有的 `tests/official_accent.rs`（192 项官方对账）上：色卡的强调族不是
+/// 另一套算法，就是那条已经对过账的路径。
+#[test]
+fn card_scheme_matches_from_accent_when_chroma_is_the_default() {
+    for card in CARDS {
+        if card.neutral_chroma != DEFAULT_NEUTRAL_CHROMA {
+            continue; // 将来的卡可以带别的中性彩度；那时它的表面色与 baseline 不同是有意的
+        }
+        for flavor in flavors() {
+            assert_eq!(
+                card.scheme(flavor),
+                Scheme::from_accent(flavor, card.seed),
+                "{} / {} 的色卡方案与 from_accent 不一致",
+                card.key,
+                flavor.name()
+            );
+        }
+    }
+}
+
+/// **生成器层**：同一张图，两张不同色卡下强调色相同、底色由图像 seed 决定。
+///
+/// ⚠️ 只测 `Seed::scheme` 这一层，**不覆盖接线**：取色分支在实际入口
+/// `palette::resolve::try_level` 里，接线由 `resolved_image_scheme_keeps_tinting_from_the_seed`
+/// 守（复审 r1 p1-1 的病根就是这条用例看着像守护、其实测不到接线）。
+#[test]
+fn image_scheme_ignores_the_preset_neutral_hue() {
+    // 4×4 纯 `#B23A48`（rose 卡的种子色）——色相远离固定的 239.5°，好坏都能分辨。
+    let pixels = [0xB2u8, 0x3A, 0x48, 0xFF].repeat(16);
+    let seed = unlucky_design::palette::seed_from_rgba(&pixels, 4, 4).expect("纯色图有种子");
+
+    let cards = [CardKey::Sky.card(), CardKey::Teal.card()];
+    let schemes: Vec<Scheme> = cards
+        .iter()
+        .map(|card| seed.scheme(SchemeFlavor::Light, card.neutral_chroma))
+        .collect();
+
+    assert_eq!(
+        schemes[0].get(Role::Primary),
+        schemes[1].get(Role::Primary),
+        "取色方案的主色只由图像种子决定，不该跟着当前色卡变"
+    );
+    assert_eq!(
+        schemes[0].get(Role::Surface),
+        schemes[1].get(Role::Surface),
+        "取色方案的底色由图像种子决定（当前八张卡的中性彩度相同，所以两套方案的表面色相同）"
+    );
+    let surface_hue = Hct::from_color(schemes[0].get(Role::Surface)).hue;
+    // 精确口径：中性**调色板**的色相必须来自图像种子（不是量化后的表面色——tone 98 的
+    // 8 bit 量化会让实测色相漂 2.7°~7°，见模块文档；拿它做等式断言只会引入假红）。
+    for card in cards {
+        let neutral_hue = seed.palettes(card.neutral_chroma).neutral.hue_deg();
+        assert!(
+            (neutral_hue - seed.hue).abs() < 1.0e-9,
+            "取色路径的中性色相 {neutral_hue:.2}° 没有跟着图像种子 {:.2}° 走",
+            seed.hue
+        );
+        assert!(
+            hue_gap(neutral_hue, NEUTRAL_HUE_DEG) > 100.0,
+            "取色路径的中性色相被拉到了色卡的固定中性色相——动态路径的逐色染色被弄丢了（D43 保留它）"
+        );
+    }
+    // 观感层：实测的表面色相明显靠近图像种子，而不是靠色卡的冷调中性色相。
+    assert!(
+        hue_gap(surface_hue, seed.hue) < hue_gap(surface_hue, NEUTRAL_HUE_DEG),
+        "取色方案的 surface 色相 {surface_hue:.2}° 更接近色卡中性色相而不是图像种子 {:.2}°",
+        seed.hue
+    );
+    for card in cards {
+        assert_ne!(
+            schemes[0].get(Role::Surface),
+            card.scheme(SchemeFlavor::Light).get(Role::Surface),
+            "取色方案的表面色与色卡路径相同，说明取色路径没在按图染色"
+        );
+    }
+}
+
+/// **接线的**守护测试（复审 r1 p1-1）：走产品公开入口 [`resolve_source`]，不是 `Card::scheme`。
+///
+/// 上一版只有生成器层那条用例：实测把 `palette::resolve::try_level` 的取色分支改成固定中性
+/// 时**8 条测试全绿**，而同一张 `#B23A48` 图的 `surface` 已从 `#FFF8F7`（暖白，跟着图走）
+/// 退化成 `#F6FAFF`（色卡冷白）。断言测 A 层、接线在 B 层——这条把整条链跑通。
+#[test]
+fn resolved_image_scheme_keeps_tinting_from_the_seed() {
+    // 4×4 纯 `#B23A48`：种子色相 15.5°（底色 8 bit 量化后读回 22.09°），离 239.51° 很远。
+    let pixels = [0xB2u8, 0x3A, 0x48, 0xFF].repeat(16);
+    let flavor = SchemeFlavor::Light;
+    let mut resolved: Vec<(CardKey, Scheme)> = Vec::new();
+    for key in [CardKey::Sky, CardKey::Teal] {
+        let (scheme, provenance) = resolve_source(
+            Some(ImageInput::pixels(&pixels, 4, 4)),
+            None,
+            Some(key),
+            flavor,
+        );
+        assert_eq!(
+            provenance.level,
+            Level::BackgroundImage,
+            "{key:?}：背景图这一级没被用上（回落链本身变了）"
+        );
+        resolved.push((key, scheme));
+    }
+
+    let surface = resolved[0].1.get(Role::Surface);
+    // ① 底色在按图染色：必须是暖白，而不是色卡那条冷调中性。这一格就是「变异检测器」。
+    assert_eq!(
+        surface.to_hex(),
+        "#FFF8F7",
+        "取色方案的 surface 被拉回了色卡中性色相"
+    );
+    let surface_hue = Hct::from_color(surface).hue;
+    assert!(
+        hue_gap(surface_hue, 22.0) < 5.0,
+        "surface 色相 {surface_hue:.2}° 没跟着图走"
+    );
+    assert!(
+        hue_gap(surface_hue, NEUTRAL_HUE_DEG) > 100.0,
+        "surface 色相 {surface_hue:.2}° 贴到了色卡固定的 {NEUTRAL_HUE_DEG:.2}°"
+    );
+    // ② 两张卡下强调色与底色都相同：底色只由图像决定，色卡只贡献中性彩度。
+    assert_eq!(
+        (resolved[0].1.get(Role::Primary), surface),
+        (
+            resolved[1].1.get(Role::Primary),
+            resolved[1].1.get(Role::Surface)
+        ),
+        "同一张图在两张卡下的主色与底色都该相同（八张卡的中性彩度都是 12）"
+    );
+    // ③ 与色卡路径明确不同：否则「取色」就等于「色卡 + 换强调色」。
+    assert_ne!(
+        surface,
+        DEFAULT_CARD.scheme(flavor).get(Role::Surface),
+        "取色方案的 surface 与天蓝卡的相同——取色路径退化成色卡路径了"
+    );
+}
+
+/// 8 张卡 × 浅/深 × 26 对：换中性色相后仍全部过 WCAG AA（`wcag::check` 全表），
+/// 并把最受中性色相影响的一对（on-surface / surface）钉在实测量级上。
+#[test]
+fn every_card_scheme_meets_wcag_aa_under_the_fixed_neutral() {
+    for card in CARDS {
+        for flavor in flavors() {
+            let scheme = card.scheme(flavor);
+            assert!(
+                card_scheme_is_readable(card, flavor),
+                "{} / {} 未过 WCAG AA 全表（{} 对逐对断言在 `palette::wcag::check`）",
+                card.key,
+                flavor.name(),
+                TEXT_PAIRS.len()
+            );
+            // 中性色相变了，最受影响的一对是 on-surface / surface（改前逐卡 16.23~16.44 浅 /
+            // 14.30~14.42 深）。改后八张卡同一个底色，这一对也逐卡相同，钉住量级免得漂移。
+            // 区间按模式分开：写成 `(浅区间) || (深区间)` 会让浅/深两个值互换也照样绿。
+            let body = scheme.contrast(Role::OnSurface, Role::Surface);
+            let band = match flavor {
+                SchemeFlavor::Light => 16.30..=16.40,
+                SchemeFlavor::Dark => 14.28..=14.36,
+            };
+            assert!(
+                band.contains(&body),
+                "{} / {}：on-surface/surface = {body:.3}，超出 {} 模式的实测区间 {band:?}",
+                card.key,
+                flavor.name(),
+                flavor.name()
+            );
+        }
+    }
+}
diff --git a/crates/design/tests/card_neutral/common.rs b/crates/design/tests/card_neutral/common.rs
new file mode 100644
index 0000000..f3a0c8e
--- /dev/null
+++ b/crates/design/tests/card_neutral/common.rs
@@ -0,0 +1,27 @@
+//! `card_neutral` 测试组共用的帮手：改前路径的复原、模式列表、色相环距离。
+//!
+//! 拆成子模块是为了单文件 ≤400 行的纪律（`card_neutral.rs` 是 crate 根，`common` / `dump`
+//! 只是它的子模块；cargo 只把 `tests/card_neutral.rs` 当一个 test target）。
+
+use unlucky_design::color::{Palettes, Scheme, SchemeFlavor};
+use unlucky_design::palette::Card;
+
+/// 改前的路径（M87 及之前）：中性调色板跟着种子染色（官方 TonalSpot）。
+///
+/// 产品代码已经不用它了，但公开 API 仍在（取色路径就靠它逐色染色），所以这里能原样复现「改前」。
+pub fn before_d43(card: Card, flavor: SchemeFlavor) -> Scheme {
+    Scheme::from_palettes(
+        &Palettes::from_seed_with_neutral_chroma(card.seed, card.neutral_chroma),
+        flavor,
+    )
+}
+
+pub fn flavors() -> [SchemeFlavor; 2] {
+    [SchemeFlavor::Light, SchemeFlavor::Dark]
+}
+
+/// 色相环上的最短距离（度）。
+pub fn hue_gap(a: f64, b: f64) -> f64 {
+    let raw = (a - b).abs();
+    raw.min(360.0 - raw)
+}
diff --git a/crates/design/tests/card_neutral/dump.rs b/crates/design/tests/card_neutral/dump.rs
new file mode 100644
index 0000000..8ff0339
--- /dev/null
+++ b/crates/design/tests/card_neutral/dump.rs
@@ -0,0 +1,68 @@
+//! 出图脚本读的 hex 行（无断言，纯打印）+ D43 的实测表（本文件就是那张表的来源）。
+//!
+//! 跑法：`cargo test -p unlucky-design --test card_neutral -- --nocapture`
+//!
+//! ## 改前 / 改后 `surface` 实测（2026-11）
+//!
+//! | 卡 | 改前 `surface`(浅) | 改后 `surface`(浅) | 改前 HCT(浅) | 改后 HCT(浅) |
+//! |---|---|---|---|---|
+//! | sky | `#F6FAFF` | `#F6FAFF` | 236.86° / 6.41 | 236.86° / 6.41 |
+//! | lavender | `#FDF7FF` | `#F6FAFF` | 298.10° / 5.87 | 236.86° / 6.41 |
+//! | forest | `#EEFDEE` | `#F6FAFF` | 157.01° / 11.77 | 236.86° / 6.41 |
+//! | amber | `#FFF8F4` | `#F6FAFF` | 71.48° / 1.89 | 236.86° / 6.41 |
+//! | rose | `#FFF8F7` | `#F6FAFF` | 22.09° / 1.29 | 236.86° / 6.41 |
+//! | teal | `#EBFEF8` | `#F6FAFF` | 182.42° / 12.03 | 236.86° / 6.41 |
+//! | dusk | `#FBF8FF` | `#F6FAFF` | 280.31° / 5.44 | 236.86° / 6.41 |
+//! | olive | `#F9FBE1` | `#F6FAFF` | 120.99° / 11.84 | 236.86° / 6.41 |
+//!
+//! 深色档同理：改前 `#09151C`~`#1F0F10`、彩度 11.63~12.45，改后八张卡统一 `#09151C`
+//! （235.70° / 11.70）。
+//!
+//! ## 这条用例为什么没有断言
+//!
+//! 它是**数据导出**（`CARD|` 行给 `/d/tmp/m88/render.py` 排版成验收图），断言在同目录的
+//! `card_neutral.rs` 里。放这里是为了让根文件留在 ≤400 行以内。
+
+use super::common::{before_d43, flavors};
+use unlucky_design::color::Role;
+use unlucky_design::palette::CARDS;
+
+/// 出图脚本读的 hex 行（改前 + 改后并排），跑法：
+/// `cargo test -p unlucky-design --test card_neutral -- --nocapture`。
+///
+/// 格式 `CARD|key|flavor|before|role=hex;role=hex;…`（承接那张「8 张卡 surface 色块并排 +
+/// 切 sky→teal 窗口底色」的验收图；渲染脚本 `/d/tmp/m88/render.py` 只做排版，数据全在这里）。
+#[test]
+fn dump_card_palette_for_the_color_card() {
+    const SHOWN: [Role; 10] = [
+        Role::Surface,
+        Role::OnSurface,
+        Role::OnSurfaceVariant,
+        Role::SurfaceVariant,
+        Role::SurfaceContainer,
+        Role::SurfaceContainerHigh,
+        Role::Outline,
+        Role::Primary,
+        Role::OnPrimary,
+        Role::PrimaryContainer,
+    ];
+    for card in CARDS {
+        for flavor in flavors() {
+            for (tag, scheme) in [
+                ("before", before_d43(card, flavor)),
+                ("after", card.scheme(flavor)),
+            ] {
+                let pairs: Vec<String> = SHOWN
+                    .iter()
+                    .map(|role| format!("{}={}", role.name(), scheme.get(*role).to_hex()))
+                    .collect();
+                println!(
+                    "CARD|{}|{}|{tag}|{}",
+                    card.key,
+                    flavor.name(),
+                    pairs.join(";")
+                );
+            }
+        }
+    }
+}
diff --git a/crates/design/tests/contrast_aa.rs b/crates/design/tests/contrast_aa.rs
new file mode 100644
index 0000000..f4bc124
--- /dev/null
+++ b/crates/design/tests/contrast_aa.rs
@@ -0,0 +1,255 @@
+//! WCAG AA 对比度门禁（M61 任务：「on-* 与其承载色至少满足 4.5:1，不达标的角色要显式标注例外」）。
+//!
+//! 三个性质让这条门禁可以做到「**换任何种子色都成立**」，而不是只对出厂紫成立：
+//! 1. 颜色建在 CIELAB `L*`（tone）轴上，`TonalPalette::tone` 精确命中 tone（误差 ≤1）；
+//! 2. WCAG 相对亮度只取决于同一条 Y 轴（`L*` ↔ Y 是双射）；
+//! 3. 角色 → tone 的映射与色相/彩度无关。
+//!
+//! 所以对比度主要由「两个角色的 tone 差」决定，与 user 选的强调色无关——下面对多组种子
+//! 逐一验证，就是在钉这个性质。
+
+use unlucky_design::color::{Color, Role, Scheme, SchemeFlavor};
+
+/// 正文文字：要求 ≥ 4.5:1（WCAG AA normal text）。
+const AA_TEXT: f32 = 4.5;
+/// 非文字元素（描边、图标块）：要求 ≥ 3:1（WCAG AA non-text）。
+const AA_NON_TEXT: f32 = 3.0;
+
+/// 文字/图标对（前景, 承载色）。两个模式都要过。
+const TEXT_PAIRS: [(Role, Role); 26] = [
+    (Role::OnPrimary, Role::Primary),
+    (Role::OnPrimaryContainer, Role::PrimaryContainer),
+    (Role::OnSecondary, Role::Secondary),
+    (Role::OnSecondaryContainer, Role::SecondaryContainer),
+    (Role::OnTertiary, Role::Tertiary),
+    (Role::OnTertiaryContainer, Role::TertiaryContainer),
+    (Role::OnError, Role::Error),
+    (Role::OnErrorContainer, Role::ErrorContainer),
+    (Role::OnSurface, Role::Surface),
+    (Role::OnSurfaceVariant, Role::SurfaceVariant),
+    (Role::OnBackground, Role::Background),
+    (Role::InverseOnSurface, Role::InverseSurface),
+    (Role::InversePrimary, Role::InverseSurface),
+    (Role::OnPrimaryFixed, Role::PrimaryFixed),
+    (Role::OnPrimaryFixedVariant, Role::PrimaryFixedDim),
+    (Role::OnSecondaryFixed, Role::SecondaryFixed),
+    (Role::OnSecondaryFixedVariant, Role::SecondaryFixedDim),
+    (Role::OnTertiaryFixed, Role::TertiaryFixed),
+    (Role::OnTertiaryFixedVariant, Role::TertiaryFixedDim),
+    // 卡片/浮层容器上的文字（M3 现行口径：层级靠 surface-container-* 表达）
+    (Role::OnSurface, Role::SurfaceContainerLowest),
+    (Role::OnSurface, Role::SurfaceContainerLow),
+    (Role::OnSurface, Role::SurfaceContainer),
+    (Role::OnSurface, Role::SurfaceContainerHigh),
+    (Role::OnSurface, Role::SurfaceContainerHighest),
+    (Role::OnSurfaceVariant, Role::SurfaceContainerHighest),
+    (Role::OnSurfaceVariant, Role::SurfaceContainerLow),
+];
+
+/// 显式登记的例外：`(前景, 承载色, 目标阈值, 原因)`。
+///
+/// 这些不是缺陷，是 M3 定义决定的（非文字元素 3:1、装饰件无要求）。
+const EXCEPTIONS: [(Role, Role, f32, &str); 3] = [
+    (
+        Role::Outline,
+        Role::Surface,
+        AA_NON_TEXT,
+        "输入框/卡片描边是 M3 定义的非文字元素，规范目标 3:1（light 实测 4.26:1、dark 5.89:1 已高于目标）",
+    ),
+    (
+        Role::OutlineVariant,
+        Role::Surface,
+        AA_NON_TEXT * 0.5,
+        "分隔线是纯装饰，M3 不要求对比度下限；light 1.62:1 / dark 1.99:1 是「几乎看不见但要能数出层级」的取值",
+    ),
+    (
+        Role::SurfaceVariant,
+        Role::Surface,
+        1.0,
+        "surface-variant 是容器色而不是前景色，不参与对比度门禁（M3 已不推荐用它做容器，保留仅为兼容旧值）",
+    ),
+];
+
+fn seeds() -> Vec<Color> {
+    vec![
+        // 出厂基线（M3 baseline 紫）
+        Color::from_hex("#6750A4").expect("基线种子"),
+        // 冷蓝（原 Fluent 强调色，用户大概率会选这一族）
+        Color::from_hex("#0078D4").expect("蓝"),
+        // 青绿
+        Color::from_hex("#006A5C").expect("青"),
+        // 暖橙（高彩度，gamut 压力大）
+        Color::from_hex("#E8710A").expect("橙"),
+        // 亮黄（最容易被白字吃掉的极端）
+        Color::from_hex("#FFD400").expect("黄"),
+        // 近灰（低彩度种子，检验 neutral 不塌）
+        Color::from_hex("#6E6E6E").expect("灰"),
+    ]
+}
+
+#[test]
+fn text_pairs_meet_wcag_aa_for_every_seed_and_flavor() {
+    let mut failures = Vec::new();
+    for seed in seeds() {
+        for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+            let scheme = Scheme::from_seed(flavor, seed);
+            for (fg, bg) in TEXT_PAIRS {
+                let ratio = scheme.contrast(fg, bg);
+                if ratio < AA_TEXT {
+                    failures.push(format!(
+                        "seed {} / {} / {} on {} = {ratio:.2}",
+                        seed.to_hex(),
+                        flavor.name(),
+                        fg.name(),
+                        bg.name()
+                    ));
+                }
+            }
+        }
+    }
+    assert!(
+        failures.is_empty(),
+        "以下角色对未达 WCAG AA（4.5:1）：\n{}",
+        failures.join("\n")
+    );
+}
+
+#[test]
+fn exception_list_is_honest_about_its_thresholds() {
+    // 例外必须**真的**是「非文字级」，不能悄悄把低于 3:1 的文字对塞进来。
+    for seed in seeds() {
+        for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+            let scheme = Scheme::from_seed(flavor, seed);
+            for (fg, bg, threshold, reason) in EXCEPTIONS {
+                assert!(
+                    !fg.is_foreground(),
+                    "例外 {} 不该是文字前景色（{reason}）",
+                    fg.name()
+                );
+                let ratio = scheme.contrast(fg, bg);
+                assert!(
+                    ratio >= threshold,
+                    "例外 {} on {} 实测 {ratio:.2}，低于登记阈值 {threshold}（seed {} / {}）",
+                    fg.name(),
+                    bg.name(),
+                    seed.to_hex(),
+                    flavor.name()
+                );
+            }
+        }
+    }
+}
+
+#[test]
+fn baseline_light_and_dark_both_pass() {
+    for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+        let scheme = Scheme::baseline(flavor);
+        for (fg, bg) in TEXT_PAIRS {
+            let ratio = scheme.contrast(fg, bg);
+            assert!(
+                ratio >= AA_TEXT,
+                "baseline {} 的 {} on {} 只有 {ratio:.2}",
+                flavor.name(),
+                fg.name(),
+                bg.name()
+            );
+        }
+    }
+}
+
+#[test]
+fn sky_seed_candidates_meet_wcag_aa() {
+    // M70：四档默认色候选（种子 + 中性彩度）必须过同一条 26 组门禁。
+    // 中性彩度改变只影响色相/彩度，不影响 tone 轴，所以理论上恒过——这里就是要**证明**它恒过，
+    // 而不是相信它。任何一档不达标，该档直接判为不可用（不许为了好看放宽阈值）。
+    let candidates = [
+        ("① 保守蓝", "#2196F3", 6.0_f64),
+        ("② 冷调蓝", "#2196F3", 12.0),
+        ("③ 浅冷蓝", "#87CEEB", 12.0),
+        ("④ 天蓝", "#3C8DBC", 12.0),
+    ];
+    let mut failures = Vec::new();
+    let mut worst = (f32::MAX, String::new());
+    let mut checked = 0;
+    for (title, seed_hex, neutral_chroma) in candidates {
+        let seed = Color::from_hex(seed_hex).expect("候选种子");
+        let palettes =
+            unlucky_design::color::Palettes::from_seed_with_neutral_chroma(seed, neutral_chroma);
+        for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+            let scheme = Scheme::from_palettes(&palettes, flavor);
+            for (fg, bg) in TEXT_PAIRS {
+                let ratio = scheme.contrast(fg, bg);
+                checked += 1;
+                if ratio < worst.0 {
+                    worst = (
+                        ratio,
+                        format!(
+                            "{title}/{} 的 {} on {}",
+                            flavor.name(),
+                            fg.name(),
+                            bg.name()
+                        ),
+                    );
+                }
+                if ratio < AA_TEXT {
+                    failures.push(format!(
+                        "{title}（{seed_hex} / 中性 {neutral_chroma}）/ {} / {} on {} = {ratio:.2}",
+                        flavor.name(),
+                        fg.name(),
+                        bg.name()
+                    ));
+                }
+            }
+        }
+    }
+    println!(
+        "候选 WCAG：{checked} 项，最紧的一对 {} = {:.2}:1（阈值 {AA_TEXT}）",
+        worst.1, worst.0
+    );
+    assert!(
+        failures.is_empty(),
+        "以下候选未达 WCAG AA（4.5:1），该档不可用：\n{}",
+        failures.join("\n")
+    );
+}
+
+#[test]
+fn accent_override_cannot_break_contrast() {
+    // 换了强调色之后，primary 族仍必须过 AA——这是「tone 轴固定」带来的结构性保证。
+    let base = Scheme::baseline(SchemeFlavor::Light);
+    for seed in seeds() {
+        let custom = Scheme::from_accent(SchemeFlavor::Light, seed);
+        for (fg, bg) in [
+            (Role::OnPrimary, Role::Primary),
+            (Role::OnPrimaryContainer, Role::PrimaryContainer),
+            (Role::OnSecondary, Role::Secondary),
+            (Role::OnTertiary, Role::Tertiary),
+        ] {
+            let ratio = custom.contrast(fg, bg);
+            assert!(
+                ratio >= AA_TEXT,
+                "强调色 {} 下 {} on {} 只有 {ratio:.2}",
+                seed.to_hex(),
+                fg.name(),
+                bg.name()
+            );
+        }
+        // 表面色不受强调色影响（这条同时是 `from_accent` 的语义断言）。
+        assert_eq!(custom.get(Role::Surface), base.get(Role::Surface));
+    }
+}
+
+#[test]
+fn outline_is_registered_as_non_text_exception() {
+    // 把「为什么 outline 不是 AA 例外失败项」钉死：它在 light 下 4.29:1（低于 4.5 但高于 3:1）。
+    let light = Scheme::baseline(SchemeFlavor::Light);
+    let ratio = light.contrast(Role::Outline, Role::Surface);
+    assert!(
+        ratio < AA_TEXT,
+        "light 的 outline 若已达 4.5 应把例外删掉：{ratio:.2}"
+    );
+    assert!(
+        ratio >= AA_NON_TEXT,
+        "light 的 outline 低于非文字 3:1：{ratio:.2}"
+    );
+}
diff --git a/crates/design/tests/official_accent.rs b/crates/design/tests/official_accent.rs
new file mode 100644
index 0000000..8481ad5
--- /dev/null
+++ b/crates/design/tests/official_accent.rs
@@ -0,0 +1,307 @@
+//! 自定义强调色 × 官方算法的**逐角色对齐**（`Scheme::from_accent`）。
+//!
+//! 期望值来自官方 Java 实现：`SchemeTonalSpot(seed, isDark, 0, SPEC_2021)` 的强调族角色。
+//! 判据：每通道误差 ≤1（见 `official_baseline.rs` 的说明）。
+//!
+//! 为什么只比强调族（primary/secondary/tertiary 共 12 个角色）：本项目的产品语义是
+//! 「换强调色不动底色」——中性表面与 error 刻意留在 baseline（见 `Palettes::with_accent`），
+//! 而官方 `from_seed` 会把中性色也染上种子色相。中性派生的正确性由本文件末尾的
+//! `from_seed_*` 用例单独验证（那一处必须与官方完全一致）。
+
+use unlucky_design::color::{Color, Role, Scheme, SchemeFlavor};
+
+/// 每通道允许的最大误差。
+const CHANNEL_TOLERANCE: i16 = 1;
+
+/// 一条官方期望值：角色 + light 色值 + dark 色值。
+type RoleRow = (Role, &'static str, &'static str);
+
+/// 一个种子 + 它 12 个强调族角色的官方色值。
+type SeedRows = (&'static str, [RoleRow; 12]);
+
+/// 八个种子：官方基线紫、纯红/绿/蓝、低彩度灰蓝、高彩度紫，外加纯黑与纯白两个边缘用例
+/// （无彩色种子的色相是病态的，官方的处理方式见 `Hct`：黑 → 色相 0、白 → 色相 209.5）。
+/// 每个种子带 12 个强调族角色的官方色值（light, dark）。
+const ACCENT_SEEDS: [SeedRows; 8] = [
+    (
+        "#6750A4",
+        [
+            (Role::Primary, "#65558F", "#CFBDFE"),
+            (Role::OnPrimary, "#FFFFFF", "#36275D"),
+            (Role::PrimaryContainer, "#E9DDFF", "#4D3D75"),
+            (Role::OnPrimaryContainer, "#4D3D75", "#E9DDFF"),
+            (Role::Secondary, "#625B71", "#CBC2DB"),
+            (Role::OnSecondary, "#FFFFFF", "#332D41"),
+            (Role::SecondaryContainer, "#E8DEF8", "#4A4458"),
+            (Role::OnSecondaryContainer, "#4A4458", "#E8DEF8"),
+            (Role::Tertiary, "#7E5260", "#EFB8C8"),
+            (Role::OnTertiary, "#FFFFFF", "#4A2532"),
+            (Role::TertiaryContainer, "#FFD9E3", "#633B48"),
+            (Role::OnTertiaryContainer, "#633B48", "#FFD9E3"),
+        ],
+    ),
+    (
+        "#FF0000",
+        [
+            (Role::Primary, "#904B40", "#FFB4A8"),
+            (Role::OnPrimary, "#FFFFFF", "#561E16"),
+            (Role::PrimaryContainer, "#FFDAD4", "#73342A"),
+            (Role::OnPrimaryContainer, "#73342A", "#FFDAD4"),
+            (Role::Secondary, "#775651", "#E7BDB6"),
+            (Role::OnSecondary, "#FFFFFF", "#442925"),
+            (Role::SecondaryContainer, "#FFDAD4", "#5D3F3B"),
+            (Role::OnSecondaryContainer, "#5D3F3B", "#FFDAD4"),
+            (Role::Tertiary, "#705C2E", "#DEC48C"),
+            (Role::OnTertiary, "#FFFFFF", "#3E2E04"),
+            (Role::TertiaryContainer, "#FBDFA6", "#564419"),
+            (Role::OnTertiaryContainer, "#564419", "#FBDFA6"),
+        ],
+    ),
+    (
+        "#00FF00",
+        [
+            (Role::Primary, "#406836", "#A5D395"),
+            (Role::OnPrimary, "#FFFFFF", "#11380B"),
+            (Role::PrimaryContainer, "#C0EFB0", "#285020"),
+            (Role::OnPrimaryContainer, "#285020", "#C0EFB0"),
+            (Role::Secondary, "#54634D", "#BBCBB2"),
+            (Role::OnSecondary, "#FFFFFF", "#263422"),
+            (Role::SecondaryContainer, "#D7E8CD", "#3C4B37"),
+            (Role::OnSecondaryContainer, "#3C4B37", "#D7E8CD"),
+            (Role::Tertiary, "#386568", "#A0CFD2"),
+            (Role::OnTertiary, "#FFFFFF", "#003739"),
+            (Role::TertiaryContainer, "#BCEBEE", "#1E4D50"),
+            (Role::OnTertiaryContainer, "#1E4D50", "#BCEBEE"),
+        ],
+    ),
+    (
+        "#0000FF",
+        [
+            (Role::Primary, "#555992", "#BEC2FF"),
+            (Role::OnPrimary, "#FFFFFF", "#272B60"),
+            (Role::PrimaryContainer, "#E0E0FF", "#3E4278"),
+            (Role::OnPrimaryContainer, "#3E4278", "#E0E0FF"),
+            (Role::Secondary, "#5C5D72", "#C5C4DD"),
+            (Role::OnSecondary, "#FFFFFF", "#2E2F42"),
+            (Role::SecondaryContainer, "#E1E0F9", "#444559"),
+            (Role::OnSecondaryContainer, "#444559", "#E1E0F9"),
+            (Role::Tertiary, "#78536B", "#E8B9D5"),
+            (Role::OnTertiary, "#FFFFFF", "#46263B"),
+            (Role::TertiaryContainer, "#FFD8EE", "#5E3C52"),
+            (Role::OnTertiaryContainer, "#5E3C52", "#FFD8EE"),
+        ],
+    ),
+    (
+        "#6E7C8A",
+        [
+            (Role::Primary, "#2B638B", "#98CCF9"),
+            (Role::OnPrimary, "#FFFFFF", "#003350"),
+            (Role::PrimaryContainer, "#CCE5FF", "#044B71"),
+            (Role::OnPrimaryContainer, "#044B71", "#CCE5FF"),
+            (Role::Secondary, "#50606F", "#B8C8D9"),
+            (Role::OnSecondary, "#FFFFFF", "#23323F"),
+            (Role::SecondaryContainer, "#D4E4F6", "#394856"),
+            (Role::OnSecondaryContainer, "#394856", "#D4E4F6"),
+            (Role::Tertiary, "#66587B", "#D1BFE7"),
+            (Role::OnTertiary, "#FFFFFF", "#372A4A"),
+            (Role::TertiaryContainer, "#ECDCFF", "#4E4162"),
+            (Role::OnTertiaryContainer, "#4E4162", "#ECDCFF"),
+        ],
+    ),
+    (
+        "#D000FF",
+        [
+            (Role::Primary, "#794F81", "#E9B5EF"),
+            (Role::OnPrimary, "#FFFFFF", "#472150"),
+            (Role::PrimaryContainer, "#FDD6FF", "#603768"),
+            (Role::OnPrimaryContainer, "#603768", "#FDD6FF"),
+            (Role::Secondary, "#6A596C", "#D6C0D6"),
+            (Role::OnSecondary, "#FFFFFF", "#3A2B3C"),
+            (Role::SecondaryContainer, "#F3DBF2", "#524153"),
+            (Role::OnSecondaryContainer, "#524153", "#F3DBF2"),
+            (Role::Tertiary, "#82524C", "#F5B7B0"),
+            (Role::OnTertiary, "#FFFFFF", "#4C2521"),
+            (Role::TertiaryContainer, "#FFDAD6", "#673B36"),
+            (Role::OnTertiaryContainer, "#673B36", "#FFDAD6"),
+        ],
+    ),
+    (
+        "#000000",
+        [
+            (Role::Primary, "#8C4A60", "#FFB1C8"),
+            (Role::OnPrimary, "#FFFFFF", "#541D32"),
+            (Role::PrimaryContainer, "#FFD9E2", "#703348"),
+            (Role::OnPrimaryContainer, "#703348", "#FFD9E2"),
+            (Role::Secondary, "#74565F", "#E3BDC6"),
+            (Role::OnSecondary, "#FFFFFF", "#422931"),
+            (Role::SecondaryContainer, "#FFD9E2", "#5A3F47"),
+            (Role::OnSecondaryContainer, "#5A3F47", "#FFD9E2"),
+            (Role::Tertiary, "#7C5635", "#EFBD94"),
+            (Role::OnTertiary, "#FFFFFF", "#48290B"),
+            (Role::TertiaryContainer, "#FFDCC1", "#623F20"),
+            (Role::OnTertiaryContainer, "#623F20", "#FFDCC1"),
+        ],
+    ),
+    (
+        "#FFFFFF",
+        [
+            (Role::Primary, "#006874", "#82D3E0"),
+            (Role::OnPrimary, "#FFFFFF", "#00363D"),
+            (Role::PrimaryContainer, "#9EEFFD", "#004F58"),
+            (Role::OnPrimaryContainer, "#004F58", "#9EEFFD"),
+            (Role::Secondary, "#4A6267", "#B1CBD0"),
+            (Role::OnSecondary, "#FFFFFF", "#1C3438"),
+            (Role::SecondaryContainer, "#CDE7EC", "#334B4F"),
+            (Role::OnSecondaryContainer, "#334B4F", "#CDE7EC"),
+            (Role::Tertiary, "#525E7D", "#BAC6EA"),
+            (Role::OnTertiary, "#FFFFFF", "#24304D"),
+            (Role::TertiaryContainer, "#DAE2FF", "#3B4664"),
+            (Role::OnTertiaryContainer, "#3B4664", "#DAE2FF"),
+        ],
+    ),
+];
+
+/// 官方 `SchemeTonalSpot(seed)` 的中性表面（surface 与 surface-container-highest，light/dark）。
+const SEED_NEUTRALS: [(&str, &str, &str, &str, &str); 8] = [
+    ("#6750A4", "#FDF7FF", "#141218", "#E6E0E9", "#36343A"),
+    ("#FF0000", "#FFF8F6", "#1A1110", "#F1DFDC", "#3D3230"),
+    ("#00FF00", "#F8FBF1", "#11140F", "#E1E4DA", "#32362F"),
+    ("#0000FF", "#FBF8FF", "#131318", "#E4E1E9", "#34343A"),
+    ("#6E7C8A", "#F7F9FF", "#101418", "#E0E2E8", "#313539"),
+    ("#D000FF", "#FFF7FA", "#171217", "#EAE0E7", "#393338"),
+    ("#000000", "#FFF8F8", "#191113", "#EFDFE1", "#3C3235"),
+    ("#FFFFFF", "#F5FAFB", "#0E1415", "#DEE3E5", "#303637"),
+];
+
+fn worst_channel(got: Color, want: Color) -> i16 {
+    [(got.r, want.r), (got.g, want.g), (got.b, want.b)]
+        .iter()
+        .map(|(a, b)| (i16::from(*a) - i16::from(*b)).abs())
+        .max()
+        .unwrap_or(0)
+}
+
+#[test]
+fn accent_schemes_match_official_on_the_accent_families() {
+    let mut worst = 0;
+    let mut off_by_one = 0;
+    let mut checked = 0;
+    let mut failures = Vec::new();
+    for (seed_hex, roles) in ACCENT_SEEDS {
+        let accent = Color::from_hex(seed_hex).expect("合法 hex");
+        for (flavor, is_dark) in [(SchemeFlavor::Light, false), (SchemeFlavor::Dark, true)] {
+            let scheme = Scheme::from_accent(flavor, accent);
+            for (role, want_light, want_dark) in roles {
+                let want_hex = if is_dark { want_dark } else { want_light };
+                let got = scheme.get(role);
+                let want = Color::from_hex(want_hex).expect("官方 hex 必须合法");
+                let delta = worst_channel(got, want);
+                worst = worst.max(delta);
+                checked += 1;
+                if delta > 0 {
+                    off_by_one += 1;
+                }
+                if delta > CHANNEL_TOLERANCE {
+                    failures.push(format!(
+                        "{seed_hex}/{}/{} 是 {}，官方 {want_hex}（差 {delta}）",
+                        flavor.name(),
+                        role.name(),
+                        got.to_hex()
+                    ));
+                }
+            }
+        }
+    }
+    assert!(
+        failures.is_empty(),
+        "{} 项强调色与官方不一致（容差 {CHANNEL_TOLERANCE}）：\n{}",
+        failures.len(),
+        failures.join("\n")
+    );
+    println!("强调色对齐：{checked} 项，最大通道误差 {worst}，非零误差 {off_by_one} 项");
+}
+
+#[test]
+fn accent_scheme_keeps_baseline_surfaces() {
+    // 产品语义：换强调色不许让底色变脏（这是 `from_accent` 与官方 `from_seed` 的唯一差别）。
+    let base = Scheme::baseline(SchemeFlavor::Light);
+    for (seed_hex, _) in ACCENT_SEEDS {
+        let accent = Color::from_hex(seed_hex).expect("合法 hex");
+        let custom = Scheme::from_accent(SchemeFlavor::Light, accent);
+        assert_eq!(custom.get(Role::Surface), base.get(Role::Surface));
+        assert_eq!(custom.get(Role::Outline), base.get(Role::Outline));
+        assert_eq!(custom.get(Role::Error), base.get(Role::Error));
+    }
+}
+
+#[test]
+fn from_seed_matches_official_neutrals() {
+    // 全量 `from_seed` 的中性派生必须与官方一致（否则「整窗染色」的色相就是错的）。
+    for (seed_hex, light_surface, dark_surface, light_highest, dark_highest) in SEED_NEUTRALS {
+        let seed = Color::from_hex(seed_hex).expect("合法 hex");
+        for (flavor, want_surface, want_highest) in [
+            (SchemeFlavor::Light, light_surface, light_highest),
+            (SchemeFlavor::Dark, dark_surface, dark_highest),
+        ] {
+            let scheme = Scheme::from_seed(flavor, seed);
+            for (role, want_hex) in [
+                (Role::Surface, want_surface),
+                (Role::SurfaceContainerHighest, want_highest),
+            ] {
+                let got = scheme.get(role);
+                let want = Color::from_hex(want_hex).expect("官方 hex 必须合法");
+                assert!(
+                    worst_channel(got, want) <= CHANNEL_TOLERANCE,
+                    "{seed_hex}/{}/{} 是 {}，官方 {want_hex}",
+                    flavor.name(),
+                    role.name(),
+                    got.to_hex()
+                );
+            }
+        }
+    }
+}
+
+#[test]
+fn from_seed_and_from_accent_agree_on_the_accent_families() {
+    // 两个入口的强调族应当逐像素相同：换种子时中性色不同，强调色只取决于种子色相。
+    for (seed_hex, _) in ACCENT_SEEDS {
+        let seed = Color::from_hex(seed_hex).expect("合法 hex");
+        for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+            let by_seed = Scheme::from_seed(flavor, seed);
+            let by_accent = Scheme::from_accent(flavor, seed);
+            for role in [
+                Role::Primary,
+                Role::OnPrimary,
+                Role::PrimaryContainer,
+                Role::OnPrimaryContainer,
+                Role::Secondary,
+                Role::SecondaryContainer,
+                Role::Tertiary,
+                Role::TertiaryContainer,
+            ] {
+                assert_eq!(
+                    by_seed.get(role),
+                    by_accent.get(role),
+                    "{seed_hex}/{} 的 {} 两个入口不一致",
+                    flavor.name(),
+                    role.name()
+                );
+            }
+        }
+    }
+}
+
+#[test]
+fn accent_hue_is_not_clipped_away() {
+    // 旧缺陷②：强调色色相被 gamut 硬裁导致偏移。现在色相由 HCT 保住（只压彩度）。
+    use unlucky_design::color::Hct;
+    for (seed_hex, _) in ACCENT_SEEDS {
+        let seed = Color::from_hex(seed_hex).expect("合法 hex");
+        let seed_hue = Hct::from_color(seed).hue;
+        let primary = Scheme::from_accent(SchemeFlavor::Light, seed).get(Role::Primary);
+        let got = Hct::from_color(primary).hue;
+        let delta = (got - seed_hue).abs().min(360.0 - (got - seed_hue).abs());
+        assert!(delta < 1.0, "{seed_hex} 的 primary 色相偏了 {delta}°");
+    }
+}
diff --git a/crates/design/tests/official_baseline.rs b/crates/design/tests/official_baseline.rs
new file mode 100644
index 0000000..2f15715
--- /dev/null
+++ b/crates/design/tests/official_baseline.rs
@@ -0,0 +1,198 @@
+//! 与官方 `material-color-utilities` 的**逐角色对齐**（baseline 方案）。
+//!
+//! 期望值不是「我们觉得对的颜色」，而是把官方 Java 实现（Apache-2.0）编译跑出来的结果：
+//! `new SchemeTonalSpot(Hct.fromInt(0xFF6750A4), isDark, 0.0, SpecVersion.SPEC_2021, Platform.PHONE)`
+//! 配上 `ColorSpec2021` 的 49 个动态色。跑法见 `NOTICE` 的归属声明——期望值表就是那份输出的
+//! 抄本（`seed,flavor,role,hex`）。
+//!
+//! 判据是**每通道误差 ≤1**：8 bit 量化本身就有半格误差，再加上 Java `double` 与 Rust `f64`
+//! 的末位差异，1 是「同一个算法」的合理上限；2 以上就是实现真的不一样了。
+
+use unlucky_design::color::{Color, Hct, Role, Scheme, SchemeFlavor, BASELINE_SEED};
+
+/// 每通道允许的最大误差。
+const CHANNEL_TOLERANCE: i16 = 1;
+
+/// 官方 baseline 输出（seed `#6750A4`，Tonal Spot，ColorSpec2021，contrastLevel 0）。
+const BASELINE: [(Role, &str, &str); 49] = [
+    (Role::Primary, "#65558F", "#CFBDFE"),
+    (Role::OnPrimary, "#FFFFFF", "#36275D"),
+    (Role::PrimaryContainer, "#E9DDFF", "#4D3D75"),
+    (Role::OnPrimaryContainer, "#4D3D75", "#E9DDFF"),
+    (Role::Secondary, "#625B71", "#CBC2DB"),
+    (Role::OnSecondary, "#FFFFFF", "#332D41"),
+    (Role::SecondaryContainer, "#E8DEF8", "#4A4458"),
+    (Role::OnSecondaryContainer, "#4A4458", "#E8DEF8"),
+    (Role::Tertiary, "#7E5260", "#EFB8C8"),
+    (Role::OnTertiary, "#FFFFFF", "#4A2532"),
+    (Role::TertiaryContainer, "#FFD9E3", "#633B48"),
+    (Role::OnTertiaryContainer, "#633B48", "#FFD9E3"),
+    (Role::Error, "#BA1A1A", "#FFB4AB"),
+    (Role::OnError, "#FFFFFF", "#690005"),
+    (Role::ErrorContainer, "#FFDAD6", "#93000A"),
+    (Role::OnErrorContainer, "#93000A", "#FFDAD6"),
+    (Role::Surface, "#FDF7FF", "#141218"),
+    (Role::OnSurface, "#1D1B20", "#E6E0E9"),
+    (Role::SurfaceVariant, "#E7E0EB", "#49454E"),
+    (Role::OnSurfaceVariant, "#49454E", "#CAC4CF"),
+    (Role::Background, "#FDF7FF", "#141218"),
+    (Role::OnBackground, "#1D1B20", "#E6E0E9"),
+    (Role::SurfaceDim, "#DED8E0", "#141218"),
+    (Role::SurfaceBright, "#FDF7FF", "#3B383E"),
+    (Role::SurfaceContainerLowest, "#FFFFFF", "#0F0D13"),
+    (Role::SurfaceContainerLow, "#F8F2FA", "#1D1B20"),
+    (Role::SurfaceContainer, "#F2ECF4", "#211F24"),
+    (Role::SurfaceContainerHigh, "#ECE6EE", "#2B292F"),
+    (Role::SurfaceContainerHighest, "#E6E0E9", "#36343A"),
+    (Role::Outline, "#7A757F", "#948F99"),
+    (Role::OutlineVariant, "#CAC4CF", "#49454E"),
+    (Role::InverseSurface, "#322F35", "#E6E0E9"),
+    (Role::InverseOnSurface, "#F5EFF7", "#322F35"),
+    (Role::InversePrimary, "#CFBDFE", "#65558F"),
+    (Role::Shadow, "#000000", "#000000"),
+    (Role::Scrim, "#000000", "#000000"),
+    (Role::SurfaceTint, "#65558F", "#CFBDFE"),
+    (Role::PrimaryFixed, "#E9DDFF", "#E9DDFF"),
+    (Role::PrimaryFixedDim, "#CFBDFE", "#CFBDFE"),
+    (Role::OnPrimaryFixed, "#201047", "#201047"),
+    (Role::OnPrimaryFixedVariant, "#4D3D75", "#4D3D75"),
+    (Role::SecondaryFixed, "#E8DEF8", "#E8DEF8"),
+    (Role::SecondaryFixedDim, "#CBC2DB", "#CBC2DB"),
+    (Role::OnSecondaryFixed, "#1E192B", "#1E192B"),
+    (Role::OnSecondaryFixedVariant, "#4A4458", "#4A4458"),
+    (Role::TertiaryFixed, "#FFD9E3", "#FFD9E3"),
+    (Role::TertiaryFixedDim, "#EFB8C8", "#EFB8C8"),
+    (Role::OnTertiaryFixed, "#31101D", "#31101D"),
+    (Role::OnTertiaryFixedVariant, "#633B48", "#633B48"),
+];
+
+/// 官方 `Hct.from(hue, chroma, tone)` 的色值（求解器与 gamut 映射的直接证据）。
+const HCT_PROBES: [(f64, f64, f64, &str); 12] = [
+    (95.0, 36.0, 40.0, "#705D0D"),
+    (95.0, 36.0, 90.0, "#FCE186"),
+    (95.0, 16.0, 90.0, "#F0E2BB"),
+    (96.0, 24.0, 80.0, "#D7C68D"),
+    (25.0, 84.0, 40.0, "#BA1A1A"),
+    (0.0, 0.0, 50.0, "#777777"),
+    (200.0, 120.0, 70.0, "#00BEC3"),
+    (30.0, 0.5, 98.0, "#FDF8F7"),
+    (270.0, 200.0, 10.0, "#001847"),
+    (120.0, 60.0, 99.0, "#FCFFDD"),
+    (60.0, 6.0, 6.0, "#19120C"),
+    (95.0, 36.0, 30.0, "#554500"),
+];
+
+/// 三通道里最大的绝对误差。
+fn worst_channel(got: Color, want: Color) -> i16 {
+    let pairs = [(got.r, want.r), (got.g, want.g), (got.b, want.b)];
+    pairs
+        .iter()
+        .map(|(a, b)| (i16::from(*a) - i16::from(*b)).abs())
+        .max()
+        .unwrap_or(0)
+}
+
+#[test]
+fn baseline_matches_official_on_all_forty_nine_roles() {
+    // 注意：对齐的是**官方锚点**（种子 #6750A4 + 中性彩度 6），不是产品默认（M70 起是浅冷蓝）。
+    let light = Scheme::official_baseline(SchemeFlavor::Light);
+    let dark = Scheme::official_baseline(SchemeFlavor::Dark);
+    let mut worst = 0;
+    let mut off_by_one = 0;
+    let mut failures = Vec::new();
+    for (role, want_light, want_dark) in BASELINE {
+        for (flavor, scheme, want_hex) in [
+            (SchemeFlavor::Light, light, want_light),
+            (SchemeFlavor::Dark, dark, want_dark),
+        ] {
+            let got = scheme.get(role);
+            let want = Color::from_hex(want_hex).expect("官方 hex 必须合法");
+            let delta = worst_channel(got, want);
+            worst = worst.max(delta);
+            if delta > 0 {
+                off_by_one += 1;
+            }
+            if delta > CHANNEL_TOLERANCE {
+                failures.push(format!(
+                    "{}/{} 是 {}，官方 {want_hex}（差 {delta}）",
+                    flavor.name(),
+                    role.name(),
+                    got.to_hex()
+                ));
+            }
+        }
+    }
+    assert!(
+        failures.is_empty(),
+        "{} 个角色与官方不一致（容差 {CHANNEL_TOLERANCE}）：\n{}",
+        failures.len(),
+        failures.join("\n")
+    );
+    // 把误差统计打出来（`cargo test -- --nocapture` 可见），报告里要引用。
+    println!("baseline 对齐：98 项，最大通道误差 {worst}，非零误差 {off_by_one} 项");
+}
+
+#[test]
+fn hct_solver_matches_official_color_spec_2021() {
+    for (hue, chroma, tone, want_hex) in HCT_PROBES {
+        let got = Hct::from_components(hue, chroma, tone).to_color();
+        let want = Color::from_hex(want_hex).expect("官方 hex 必须合法");
+        assert!(
+            worst_channel(got, want) <= CHANNEL_TOLERANCE,
+            "HCT({hue}, {chroma}, {tone}) 是 {}，官方 {want_hex}",
+            got.to_hex()
+        );
+    }
+}
+
+#[test]
+fn baseline_primary_is_not_the_seed_and_that_is_official() {
+    // 常见误解：官方基线的 primary 应该等于种子 #6750A4。官方不是——Tonal Spot 变体把
+    // primary 的彩度固定成 36，而 #6750A4 的 HCT 彩度是 47.86，所以 primary 被收到 #65558F。
+    // 这也是 Flutter `ColorScheme.fromSeed(0xFF6750A4)` 的 primary 值。
+    let seed = Hct::from_color(BASELINE_SEED);
+    assert!(
+        (seed.chroma - 47.856_526).abs() < 1.0e-4,
+        "种子彩度 {}",
+        seed.chroma
+    );
+    let primary = Scheme::official_baseline(SchemeFlavor::Light).get(Role::Primary);
+    assert_eq!(primary.to_hex(), "#65558F");
+    assert_ne!(primary, BASELINE_SEED);
+}
+
+#[test]
+fn baseline_tone_axis_is_still_exact_lstar() {
+    // gamut 映射只动彩度，不动 tone：每个角色的实测 L* 与它声明的 tone 相差 ≤1。
+    for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+        let scheme = Scheme::official_baseline(flavor);
+        for (role, color) in scheme.iter() {
+            let tone = Scheme::tone_of(role, flavor);
+            let got = f64::from(color.lstar());
+            assert!(
+                (got - tone).abs() <= 1.0,
+                "{}/{} 的 tone 声明 {tone}、实测 {got}",
+                flavor.name(),
+                role.name()
+            );
+        }
+    }
+}
+
+#[test]
+fn same_family_containers_are_separated_by_hct_chroma() {
+    // 旧缺陷①：light 下 primary-container 与 secondary-container 撞色。
+    // 现在两者彩度不同（36 vs 16），在 tone 90 上都不会被色域裁到同一个上限。
+    let light = Scheme::official_baseline(SchemeFlavor::Light);
+    let primary = light.get(Role::PrimaryContainer);
+    let secondary = light.get(Role::SecondaryContainer);
+    assert_ne!(primary, secondary);
+    let c_primary = Hct::from_color(primary).chroma;
+    let c_secondary = Hct::from_color(secondary).chroma;
+    assert!(
+        c_secondary < c_primary,
+        "secondary-container 彩度 {c_secondary} 应低于 primary-container {c_primary}"
+    );
+    // 深层原因：tone 90 上彩度 36 装得下，所以容器色是「真的有彩度的浅色」而不是被裁到灰。
+    assert!(c_primary > 12.0, "primary-container 彩度只剩 {c_primary}");
+}
diff --git a/crates/design/tests/skyseed_candidates.rs b/crates/design/tests/skyseed_candidates.rs
new file mode 100644
index 0000000..22744f3
--- /dev/null
+++ b/crates/design/tests/skyseed_candidates.rs
@@ -0,0 +1,341 @@
+//! M70：默认色候选（保守蓝 / 冷调蓝 / 浅冷蓝 / 天蓝）——四档的**唯一真源**与 pin。
+//!
+//! ## 这档候选到底改了什么
+//!
+//! 四档走的是**同一条** HCT 管道（`Palettes::from_seed_with_neutral_chroma` → `ColorSpec2021`
+//! tone 表 → `HctSolver` gamut 映射），差别只有两个入参：
+//!
+//! | 档 | 种子 | 种子 HCT 色相 | 中性调色板彩度 | 表面 | 主色观感 |
+//! |---|---|---|---|---|---|
+//! | ① 保守蓝 | `#2196F3` | 253.7° | 6（官方） | 近白/近黑，几乎无色 | 钢蓝 |
+//! | ② 冷调蓝 | `#2196F3` | 253.7° | 12 | 冷白/冷黑，带淡蓝调 | 钢蓝 |
+//! | ③ 浅冷蓝（备选） | `#87CEEB`（CSS `skyblue`） | 225.7° | 12 | 浅天蓝 | 偏青（teal） |
+//! | ④ 天蓝（**出厂默认，用户 2026-11-01 拍板**） | `#3C8DBC` | 239.5° | 12 | 浅天蓝 | 偏蓝的天蓝 |
+//!
+//! ③ 与 ④ 是同一件事的两种「蓝」：色相越低越偏青（teal），越高越偏钢蓝；
+//! 239.5° 正好夹在中间，主色从 ③ 的 `#0C6780` 变成 `#236488`。
+//!
+//! 两条必须知道的物理事实（写在测试里，免得下次又有人想「把主色调浅一点」）：
+//!
+//! 1. **种子彩度是废参数**：Tonal Spot 把 primary 彩度钉在 36，种子只贡献色相。
+//!    所以「低彩度天蓝种子」得到的色板与「高彩度天蓝种子」**逐像素相同**
+//!    （`seed_chroma_never_leaks_into_the_primary_ramp` 在 `palettes.rs` 里也钉了这条）。
+//!    ③ 与 ② 的真正差别是**色相**（226° vs 254°），不是彩度。
+//! 2. **primary 的 tone 被钉在 40**，所以四档主色都是「中蓝」，不会更浅。
+//!    「浅」只能落在中性色上——这就是②/③/④提高中性彩度的原因，也是本项目唯一一处
+//!    对官方 Tonal Spot 的**有意偏离**（登记在 `color` 模块文档的「出厂默认色」小节）。
+//!
+//! ## 换默认色要动哪里
+//!
+//! `palettes::DEFAULT_SEED` / `palettes::DEFAULT_NEUTRAL_CHROMA` 两行常量，
+//! 然后重跑本文件：pin 表会逐角色告诉你哪几个 hex 变了，照抄即可（pin 是**抄本**，不是推导）。
+
+use unlucky_design::color::{
+    Color, Hct, Palettes, Role, Scheme, SchemeFlavor, DEFAULT_NEUTRAL_CHROMA, DEFAULT_SEED,
+};
+
+/// 一档候选：只有两个变量（种子 + 中性彩度），其余全是官方常数。
+struct Candidate {
+    /// 短标签（色卡与 CSV 用）。
+    tag: &'static str,
+    /// 中文档名。
+    title: &'static str,
+    /// 种子 hex。
+    seed_hex: &'static str,
+    /// 中性调色板彩度（官方 Tonal Spot 是 6）。
+    neutral_chroma: f64,
+    /// 9 个展示角色的 **(角色, light, dark)** 抄本。
+    pins: [(Role, &'static str, &'static str); 9],
+}
+
+/// 四档候选（色卡 `DevDocs/ops/skyseed-candidates/` 用的就是这份数据）。
+const CANDIDATES: [Candidate; 4] = [
+    Candidate {
+        tag: "C1",
+        title: "① 保守蓝（中性彩度 6 = 官方）",
+        seed_hex: "#2196F3",
+        neutral_chroma: 6.0,
+        pins: [
+            (Role::Primary, "#36618E", "#A0CAFD"),
+            (Role::OnPrimary, "#FFFFFF", "#003258"),
+            (Role::PrimaryContainer, "#D1E4FF", "#194975"),
+            (Role::Secondary, "#535F70", "#BBC7DB"),
+            (Role::Tertiary, "#6B5778", "#D6BEE4"),
+            (Role::Surface, "#F8F9FF", "#111418"),
+            (Role::SurfaceContainerLow, "#F2F3FA", "#191C20"),
+            (Role::SurfaceContainerHighest, "#E1E2E8", "#32353A"),
+            (Role::Outline, "#73777F", "#8D9199"),
+        ],
+    },
+    Candidate {
+        tag: "C2",
+        title: "② 冷调蓝（中性彩度 12）",
+        seed_hex: "#2196F3",
+        neutral_chroma: 12.0,
+        pins: [
+            (Role::Primary, "#36618E", "#A0CAFD"),
+            (Role::OnPrimary, "#FFFFFF", "#003258"),
+            (Role::PrimaryContainer, "#D1E4FF", "#194975"),
+            (Role::Secondary, "#535F70", "#BBC7DB"),
+            (Role::Tertiary, "#6B5778", "#D6BEE4"),
+            (Role::Surface, "#F8F9FF", "#0C141E"),
+            (Role::SurfaceContainerLow, "#EEF4FF", "#141C26"),
+            (Role::SurfaceContainerHighest, "#DBE3F1", "#2D3540"),
+            (Role::Outline, "#6D7887", "#8791A1"),
+        ],
+    },
+    Candidate {
+        tag: "C3",
+        title: "③ 浅冷蓝（中性彩度 12 + 偏青天蓝种子）",
+        seed_hex: "#87CEEB",
+        neutral_chroma: 12.0,
+        pins: [
+            (Role::Primary, "#0C6780", "#89D0ED"),
+            (Role::OnPrimary, "#FFFFFF", "#003544"),
+            (Role::PrimaryContainer, "#BAEAFF", "#004D62"),
+            (Role::Secondary, "#4C626B", "#B3CAD5"),
+            (Role::Tertiary, "#5B5B7E", "#C4C3EB"),
+            (Role::Surface, "#F3FAFF", "#07151B"),
+            (Role::SurfaceContainerLow, "#E7F6FE", "#0F1D23"),
+            (Role::SurfaceContainerHighest, "#D6E5ED", "#29373D"),
+            (Role::Outline, "#687A82", "#81949C"),
+        ],
+    },
+    Candidate {
+        tag: "C4",
+        title: "④ 天蓝（中性彩度 12 + 夹在中间的天蓝种子）",
+        seed_hex: "#3C8DBC",
+        neutral_chroma: 12.0,
+        pins: [
+            (Role::Primary, "#236488", "#93CDF6"),
+            (Role::OnPrimary, "#FFFFFF", "#00344C"),
+            (Role::PrimaryContainer, "#C8E6FF", "#004C6D"),
+            (Role::Secondary, "#4F616E", "#B7C9D8"),
+            (Role::Tertiary, "#63597C", "#CDC0E9"),
+            (Role::Surface, "#F6FAFF", "#09151C"),
+            (Role::SurfaceContainerLow, "#EBF5FF", "#111D25"),
+            (Role::SurfaceContainerHighest, "#D8E4EF", "#2B363F"),
+            (Role::Outline, "#6A7985", "#84939F"),
+        ],
+    },
+];
+
+/// 四档共同点：种子的 HCT 坐标（色相是候选之间**唯一**有效的差别）。
+fn seed_hct(candidate: &Candidate) -> Hct {
+    Hct::from_color(Color::from_hex(candidate.seed_hex).expect("候选种子必须是合法 hex"))
+}
+
+/// 按候选参数走**产品同一条**派生路径。
+fn scheme(candidate: &Candidate, flavor: SchemeFlavor) -> Scheme {
+    Scheme::from_palettes(
+        &Palettes::from_seed_with_neutral_chroma(
+            seed_hct(candidate).to_color(),
+            candidate.neutral_chroma,
+        ),
+        flavor,
+    )
+}
+
+#[test]
+fn candidates_match_their_pins() {
+    let mut drift = Vec::new();
+    for candidate in &CANDIDATES {
+        for (role, want_light, want_dark) in candidate.pins {
+            for (flavor, want_hex) in [
+                (SchemeFlavor::Light, want_light),
+                (SchemeFlavor::Dark, want_dark),
+            ] {
+                let got = scheme(candidate, flavor).get(role).to_hex();
+                if got != want_hex {
+                    drift.push(format!(
+                        "{}{} / {}/{} 实测 {got}，pin {want_hex}",
+                        candidate.tag,
+                        if flavor.is_dark() { "-dark" } else { "" },
+                        candidate.title,
+                        role.name()
+                    ));
+                }
+            }
+        }
+    }
+    assert!(
+        drift.is_empty(),
+        "候选色值漂了（换默认色后请照抄下面这些 hex 到 pin 表）：\n{}",
+        drift.join("\n")
+    );
+}
+
+#[test]
+fn candidates_only_move_the_two_declared_inputs() {
+    // 「不绕算法」的证据：四档的调色板彩度与官方 Tonal Spot 逐项一致，
+    // 唯一的差别是中性彩度的入参（以及种子色相）。
+    let official = Palettes::official_baseline();
+    for candidate in &CANDIDATES {
+        let p = Palettes::from_seed_with_neutral_chroma(
+            seed_hct(candidate).to_color(),
+            candidate.neutral_chroma,
+        );
+        assert_eq!(p.primary.chroma(), official.primary.chroma());
+        assert_eq!(p.secondary.chroma(), official.secondary.chroma());
+        assert_eq!(p.tertiary.chroma(), official.tertiary.chroma());
+        assert_eq!(p.error, official.error, "error 族不该被候选影响");
+        assert_eq!(p.neutral.chroma(), candidate.neutral_chroma);
+        assert!(
+            (p.tertiary.hue_deg() - (p.primary.hue_deg() + 60.0)).abs() < 1.0e-9,
+            "{} 的 tertiary 不再是 +60°",
+            candidate.tag
+        );
+    }
+}
+
+#[test]
+fn the_candidates_are_actually_distinguishable() {
+    // 「四档不像同一档」的机器判据。注意 light 的 surface（tone 98）在 8 bit 下已经贴顶，
+    // 中性彩度 6→12 会量化到同一个 #F8F9FF——所以 ①② 的判据落在 container 系与 dark 模式上，
+    // 这也是色卡上 ①② 的差别主要体现在卡片/浮层与深色模式的原因。
+    let light = |c: &Candidate| scheme(c, SchemeFlavor::Light);
+    let dark = |c: &Candidate| scheme(c, SchemeFlavor::Dark);
+    let (c1, c2, c3, c4) = (
+        light(&CANDIDATES[0]),
+        light(&CANDIDATES[1]),
+        light(&CANDIDATES[2]),
+        light(&CANDIDATES[3]),
+    );
+    for role in [Role::SurfaceContainerLow, Role::SurfaceContainerHighest] {
+        assert_ne!(
+            c1.get(role),
+            c2.get(role),
+            "①与②的 {} 相同：中性彩度没起作用",
+            role.name()
+        );
+        assert_ne!(c2.get(role), c3.get(role), "②与③的 {} 相同", role.name());
+        // ③④ 的中性彩度相同，差别只允许来自色相
+        assert_ne!(c3.get(role), c4.get(role), "③与④的 {} 相同", role.name());
+    }
+    assert_ne!(
+        c3.get(Role::Primary),
+        c4.get(Role::Primary),
+        "③与④的主色必须真的不同（否则第 4 档白加）"
+    );
+    assert_ne!(
+        dark(&CANDIDATES[0]).get(Role::Surface),
+        dark(&CANDIDATES[1]).get(Role::Surface),
+        "深色模式的 surface 应当能看出中性彩度差别"
+    );
+    let hue_gap = |a: &Candidate, b: &Candidate| {
+        let (x, y) = (seed_hct(a).hue, seed_hct(b).hue);
+        (x - y).abs().min(360.0 - (x - y).abs())
+    };
+    assert!(
+        hue_gap(&CANDIDATES[0], &CANDIDATES[1]) < 0.01,
+        "①② 应当只差中性彩度"
+    );
+    // ③ 偏青 / ④ 居中的分界靠色相：②→③ 与 ③→④ 都要肉眼可分的量级。
+    for (i, j) in [(1, 2), (2, 3)] {
+        assert!(
+            (10.0..=40.0).contains(&hue_gap(&CANDIDATES[i], &CANDIDATES[j])),
+            "{}→{} 的色相差应当明显（10°~40°），实测 {}",
+            CANDIDATES[i].tag,
+            CANDIDATES[j].tag,
+            hue_gap(&CANDIDATES[i], &CANDIDATES[j])
+        );
+    }
+}
+
+#[test]
+fn product_default_is_the_adopted_candidate() {
+    // 用户 2026-11-01 拍板采用 **④ 天蓝**。这条用例就是「默认值 ↔ 候选表」的绑定器：
+    // 谁改了 `DEFAULT_SEED`/`DEFAULT_NEUTRAL_CHROMA` 却没同步这里（或反过来），它会立刻红。
+    // 断言一律比 **hex / 数值**，这样失败信息里直接能读到「期望 ④、实测几」。
+    let adopted = &CANDIDATES[3];
+    assert_eq!(
+        DEFAULT_SEED.to_hex(),
+        "#3C8DBC",
+        "DEFAULT_SEED 必须仍是已采用的 ④ 天蓝：期望 #3C8DBC（④），实测 {}（{}）",
+        DEFAULT_SEED.to_hex(),
+        if DEFAULT_SEED.to_hex() == CANDIDATES[2].seed_hex {
+            "③ 浅冷蓝——要改回 ③ 请连偏离登记与 pin 一起改"
+        } else {
+            "不是候选表里的任何一个种子"
+        }
+    );
+    assert_eq!(
+        DEFAULT_SEED.to_hex(),
+        adopted.seed_hex,
+        "DEFAULT_SEED（{}）与已采用档 {} 的种子（{}）不一致",
+        DEFAULT_SEED.to_hex(),
+        adopted.tag,
+        adopted.seed_hex
+    );
+    assert_eq!(
+        DEFAULT_NEUTRAL_CHROMA, 12.0,
+        "DEFAULT_NEUTRAL_CHROMA 必须仍是已采用的 12，实测 {}",
+        DEFAULT_NEUTRAL_CHROMA
+    );
+    assert_eq!(
+        DEFAULT_NEUTRAL_CHROMA, adopted.neutral_chroma,
+        "DEFAULT_NEUTRAL_CHROMA（{}）与已采用档 {} 的中性彩度（{}）不一致",
+        DEFAULT_NEUTRAL_CHROMA, adopted.tag, adopted.neutral_chroma
+    );
+    for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+        let product = Scheme::baseline(flavor);
+        let expected = scheme(adopted, flavor);
+        for (role, got) in product.iter() {
+            assert_eq!(
+                got.to_hex(),
+                expected.get(role).to_hex(),
+                "产品默认与已采用档 {} 的 {}（{} 模式）不一致",
+                adopted.tag,
+                role.name(),
+                flavor.name()
+            );
+        }
+    }
+}
+
+#[test]
+fn surface_tint_stays_a_tint() {
+    // 门禁：中性彩度提高是「淡蓝调」不是「把窗口染成蓝纸」。surface 的 HCT 彩度必须
+    // 明显低于 primary 的 36，且 surface 的 Y 仍 > 0.85（浅色模式还是浅底）。
+    for candidate in &CANDIDATES {
+        let light = scheme(candidate, SchemeFlavor::Light);
+        let surface = light.get(Role::Surface);
+        let chroma = Hct::from_color(surface).chroma;
+        assert!(
+            chroma <= 1.2 * candidate.neutral_chroma,
+            "{} 的 surface 彩度 {chroma} 超过中性彩度入参的两倍",
+            candidate.tag
+        );
+        assert!(surface.relative_luminance() > 0.85);
+    }
+}
+
+#[test]
+fn dump_candidates_for_the_color_card() {
+    // 色卡脚本读的就是这两行格式（`SEED|` / `ROLE|`）。跑法：
+    //   cargo test -p unlucky-design --test skyseed_candidates -- --nocapture
+    for candidate in &CANDIDATES {
+        let hct = seed_hct(candidate);
+        println!(
+            "SEED|{}|{}|{}|{}|hue={:.2}|chroma={:.2}",
+            candidate.tag,
+            candidate.title,
+            candidate.seed_hex,
+            candidate.neutral_chroma,
+            hct.hue,
+            hct.chroma
+        );
+        for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+            let s = scheme(candidate, flavor);
+            for role in Role::ALL {
+                println!(
+                    "ROLE|{}|{}|{}|{}",
+                    candidate.tag,
+                    flavor.name(),
+                    role.name(),
+                    s.get(role).to_hex().trim_start_matches('#')
+                );
+            }
+        }
+    }
+}
diff --git a/crates/design/tests/token_contract.rs b/crates/design/tests/token_contract.rs
new file mode 100644
index 0000000..0f1b50f
--- /dev/null
+++ b/crates/design/tests/token_contract.rs
@@ -0,0 +1,246 @@
+//! 令牌契约测试：从**消费方视角**（只用公开 API）钉住 M61 承诺的那些性质。
+//!
+//! 这份测试的作用是「冻结」：`IconKind`/`Role` 的次序与个数、type scale 的取值、形状/高程阶梯、
+//! 描边的 SVG 语义换算。后续 iced 页面线靠它保证不会因为一次「顺手改动」而悄悄换观感。
+
+use unlucky_design::color::{Role, Scheme, SchemeFlavor, TonalPalette};
+use unlucky_design::component_map::Component;
+use unlucky_design::elevation::{Elevation, MaterialLayer};
+use unlucky_design::icons::{
+    stroke_width_for, visual_stroke_px, IconKind, IconPaint, IconSize, VIEWBOX,
+};
+use unlucky_design::motion::{
+    DurationToken, Easing, MotionScale, SPRING_EXPRESSIVE_SPATIAL_DEFAULT,
+};
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::{LayoutMetrics, Space};
+use unlucky_design::typography::{FontFamily, Platform, TypeRole, Weight};
+use unlucky_design::DesignTokens;
+
+#[test]
+fn color_role_table_is_frozen() {
+    assert_eq!(Role::ALL.len(), 49, "M3 基础角色集共 49 个");
+    assert_eq!(Role::ALL[0], Role::Primary);
+    assert_eq!(Role::ALL[16], Role::Surface);
+    assert_eq!(Role::ALL[48], Role::OnTertiaryFixedVariant);
+    // 每个角色都能从两套 scheme 里取到值，且前景角色都带 on- 语义。
+    let light = Scheme::baseline(SchemeFlavor::Light);
+    let dark = Scheme::baseline(SchemeFlavor::Dark);
+    for role in Role::ALL {
+        assert!(
+            light.get(role).is_opaque(),
+            "{} 应当是不透明色",
+            role.name()
+        );
+        assert!(dark.get(role).is_opaque());
+        if role.name().starts_with("on-") {
+            assert!(role.is_foreground(), "{} 应被判为前景色", role.name());
+        }
+    }
+    assert!(light.get(Role::Primary).is_opaque());
+}
+
+#[test]
+fn tone_mapping_is_the_m3_table() {
+    // 抽查几行关键映射（light / dark），防止有人改 tone 表时静默换观感。
+    assert_eq!(Scheme::tone_of(Role::Primary, SchemeFlavor::Light), 40.0);
+    assert_eq!(Scheme::tone_of(Role::Surface, SchemeFlavor::Light), 98.0);
+    assert_eq!(Scheme::tone_of(Role::Surface, SchemeFlavor::Dark), 6.0);
+    assert_eq!(
+        Scheme::tone_of(Role::OnPrimaryContainer, SchemeFlavor::Dark),
+        90.0
+    );
+    assert_eq!(Scheme::tone_of(Role::Outline, SchemeFlavor::Light), 50.0);
+}
+
+#[test]
+fn type_scale_values_are_the_m3_baseline() {
+    assert_eq!(TypeRole::ALL.len(), 15);
+    let title = TypeRole::TitleLarge.style();
+    assert_eq!((title.size_px, title.line_height_px), (22.0, 28.0));
+    let body = TypeRole::BodyMedium.style();
+    assert_eq!((body.size_px, body.line_height_px), (14.0, 20.0));
+    assert_eq!(body.weight, Weight::Regular);
+    let label = TypeRole::LabelLarge.style();
+    assert_eq!(label.weight, Weight::Medium);
+    assert_eq!(TypeRole::BodySmall.style().size_px, 12.0);
+    // 强调档只动字重。
+    assert_eq!(TypeRole::TitleLarge.emphasized().size_px, 22.0);
+    assert!(TypeRole::TitleMedium.emphasized().weight.value() > Weight::Medium.value());
+}
+
+#[test]
+fn font_stacks_never_embed_font_files() {
+    for platform in [Platform::Windows, Platform::MacOs, Platform::Linux] {
+        for family in [FontFamily::Display, FontFamily::Text, FontFamily::Mono] {
+            let stack = platform.font_stack(family);
+            assert!(!stack.is_empty());
+            for face in stack {
+                let lower = face.family.to_ascii_lowercase();
+                for banned in [".ttf", ".otf", ".ttc", "woff", "file"] {
+                    assert!(
+                        !lower.contains(banned),
+                        "{} 的字体栈出现文件引用 {}（只允许族名，禁止内嵌受限字体）",
+                        platform.name(),
+                        face.family
+                    );
+                }
+            }
+        }
+    }
+}
+
+#[test]
+fn cjk_weight_gap_is_registered() {
+    // 中文 700（Expressive 强调档要用的）在三平台都要能找到原生落点，否则就是合成加粗降级。
+    use unlucky_design::typography::{Weight, WeightMatch};
+    // Windows：Segoe UI Variable 覆盖 700（原生）；CJK 落点是雅黑 700（原生，雅黑有 Bold）。
+    let win = Platform::Windows.resolve_weight(FontFamily::Text, Weight::Bold);
+    assert_eq!(win.quality, WeightMatch::Native);
+    assert!(Platform::Windows.cjk_face().supports(Weight::Bold));
+    // macOS：苹方只到 600 → CJK 的 700 只能合成/换族，这条 gap 已在文档登记。
+    assert!(!Platform::MacOs.cjk_face().supports(Weight::Bold));
+    // Linux：Noto Sans CJK 可变字体全覆盖。
+    for weight in [Weight::Regular, Weight::Medium, Weight::Bold] {
+        assert!(Platform::Linux.cjk_face().supports(weight));
+    }
+}
+
+#[test]
+fn icon_kind_is_frozen_and_append_only() {
+    assert_eq!(IconKind::ALL.len(), 28, "M61 冻结 28 个图标");
+    // 迁移来的 24 个必须保持原次序（序号即持久化 id）。
+    assert_eq!(IconKind::ALL[0], IconKind::Instances);
+    assert_eq!(IconKind::ALL[4], IconKind::Ai);
+    assert_eq!(IconKind::ALL[20], IconKind::More);
+    assert_eq!(IconKind::ALL[23], IconKind::User);
+    // 新增的 4 个追加在末尾。
+    assert_eq!(IconKind::ALL[24], IconKind::Refresh);
+    assert_eq!(IconKind::ALL[27], IconKind::Trash);
+    for kind in IconKind::ALL {
+        assert!(kind.icon().path.starts_with('M'));
+        assert_eq!(kind.icon().kind, kind);
+    }
+}
+
+#[test]
+fn icon_stroke_follows_svg_semantics_not_slint() {
+    // 派生式（**这条测试钉的就是它**）：`stroke = 1.5 × 24 / render_px`，1.5 是视觉线宽、24 是 viewBox。
+    //
+    // 两个锚点，一个不随本次收敛变化、一个随令牌取值：
+    // - 20px（`IconSize::Nav`，本轮没动）→ 1.5 × 24 / 20 = **1.8**
+    // - 18px（`IconSize::Button`，M86 由 16 收敛到官方 18）→ 1.5 × 24 / 18 = **2.0**
+    //
+    // ⚠️ **这条只保证「烘焙路径」**（`crates/app-iced/src/icons.rs::view_at`：按盒尺寸烘焙 SVG，
+    // 于是一个 viewBox 单位的 stroke 落到盒子后正好是 1.5 视觉像素）。
+    // 它**不**保证「24 烘焙 + 布局缩到 18」那条路径——那条会得到 `1.5 × 18/24 = 1.125px`，
+    // 正是复审 r1 P2-2 实测到的 1.04~1.25px 缺陷。所以组件侧凡是盒 ≠ `RENDER_PX`(24) 的调用点
+    // 都必须走 `view_at`（见 `icons.rs::tests::view_at_bakes_the_requested_size` 与
+    // `crates/app-iced/src/components/gate.rs` 的 Q9 扫描）。
+    //
+    // 之所以写死字面量而不写成 `stroke_width_for(IconSize::Nav.px(), 1.5)`：后者等于拿实现算实现，
+    // 派生式一旦被改坏（例如把 ×24 写成 ×20）它照样绿。写死才会红。
+    // Slint 口径（绝对 1.5px，不乘 viewBox）在这两档都会得到 1.5 —— 那正是这条要防的错。
+    let nav_width = IconKind::Settings.icon().stroke_width(IconSize::Nav.px());
+    assert!(
+        (nav_width - 1.8).abs() < 1.0e-6,
+        "20px 渲染应取 1.8 个 viewBox 单位（锚点，不随 IconSize 收敛变化）"
+    );
+    let button_width = IconKind::Settings
+        .icon()
+        .stroke_width(IconSize::Button.px());
+    assert!(
+        (button_width - 2.0).abs() < 1.0e-6,
+        "18px 渲染应取 2.0 个 viewBox 单位（M86：Button 由 16→18，旧期望 2.25 是 16px 的派生值）"
+    );
+    // 视觉宽度的往返一致性（这条是「别照抄 Slint 的 1.5」的守门测试）。
+    for size in IconSize::ALL {
+        let w = stroke_width_for(size.px(), 1.5);
+        assert!((visual_stroke_px(size.px(), w) - 1.5).abs() < 1.0e-6);
+    }
+    assert!((VIEWBOX - 24.0).abs() < f32::EPSILON);
+    // 实心图标不描边。
+    assert_eq!(IconKind::Play.icon().paint, IconPaint::Fill);
+    assert_eq!(IconKind::Play.icon().stroke_width(24.0), 0.0);
+}
+
+#[test]
+fn shape_and_elevation_ladders() {
+    assert_eq!(ShapeScale::ExtraSmall.dp(), 4.0);
+    assert_eq!(ShapeScale::Medium.dp(), 12.0);
+    assert_eq!(ShapeScale::ExtraLarge.dp(), 28.0);
+    assert_eq!(ShapeScale::Full.radius_px(40.0), 20.0);
+    assert!(ShapeScale::ExtraLargeIncreased.is_expressive());
+
+    let dp: Vec<f32> = Elevation::ALL.iter().map(|e| e.dp()).collect();
+    assert_eq!(dp, vec![0.0, 1.0, 3.0, 6.0, 8.0, 12.0]);
+    assert_eq!(
+        MaterialLayer::Card.surface_role(),
+        Role::SurfaceContainerLow
+    );
+}
+
+#[test]
+fn motion_tokens_are_usable_as_data() {
+    assert_eq!(DurationToken::Medium2.ms(), 300);
+    assert!((Easing::Standard.sample(0.0)).abs() < 1.0e-6);
+    assert!((Easing::Standard.sample(1.0) - 1.0).abs() < 1.0e-6);
+    let settle = SPRING_EXPRESSIVE_SPATIAL_DEFAULT.settle_ms(0.001);
+    assert!(settle > 0.0 && settle < 2000.0);
+    assert_eq!(MotionScale::NONE.ms(DurationToken::Long4), 0.0);
+}
+
+#[test]
+fn spacing_and_layout_metrics_are_shared() {
+    assert_eq!(Space::X4.dp(), 16.0);
+    let metrics = LayoutMetrics::DESKTOP;
+    assert_eq!(metrics.header_height(false), 56.0);
+    assert_eq!(metrics.header_height(true), 84.0);
+}
+
+#[test]
+fn component_map_covers_the_page_skeleton() {
+    // M69（G9）在末尾追加 Checkbox/Radio/Search/NavigationDrawer/Divider：20 → 25。
+    assert_eq!(Component::ALL.len(), 25);
+    for component in Component::ALL {
+        let spec = component.spec();
+        assert_eq!(spec.component, component);
+        assert!(spec.text.style().size_px >= 11.0);
+    }
+    assert_eq!(Component::PrimaryButton.spec().shape, ShapeScale::Full);
+    // 浮层必须高于卡片层。
+    assert!(Component::Dialog.spec().elevation > Component::OutlinedCard.spec().elevation);
+    // 末尾追加的 5 个不许改动既有次序。
+    assert_eq!(Component::ALL[0], Component::TopAppBar);
+    assert_eq!(Component::ALL[19], Component::EmptyState);
+}
+
+#[test]
+fn design_tokens_entry_point() {
+    let light = DesignTokens::baseline(SchemeFlavor::Light);
+    let dark = DesignTokens::baseline(SchemeFlavor::Dark);
+    assert_eq!(light.flavor, SchemeFlavor::Light);
+    assert!(light.color(Role::Surface).relative_luminance() > 0.8);
+    assert!(dark.color(Role::Surface).relative_luminance() < 0.05);
+    assert!(!light.motion_scale.is_off());
+
+    let accent = DesignTokens::with_accent(
+        SchemeFlavor::Light,
+        unlucky_design::Color::from_hex("#006A5C").unwrap(),
+    );
+    assert_ne!(accent.color(Role::Primary), light.color(Role::Primary));
+    assert_eq!(accent.color(Role::Surface), light.color(Role::Surface));
+}
+
+#[test]
+fn tonal_palette_hits_requested_tones() {
+    let palette = TonalPalette::new(150.0, 36.0);
+    for tone in [20.0_f64, 40.0, 60.0, 80.0] {
+        let color = palette.tone(tone);
+        assert!(
+            (f64::from(color.lstar()) - tone).abs() <= 1.0,
+            "tone {tone} 实际 {}",
+            color.lstar()
+        );
+    }
+}
diff --git a/crates/design/tests/token_pins.rs b/crates/design/tests/token_pins.rs
new file mode 100644
index 0000000..29c580d
--- /dev/null
+++ b/crates/design/tests/token_pins.rs
@@ -0,0 +1,252 @@
+//! 官方数值钉死（二）：**色彩 tone 表 49 条**、7 条 easing 曲线、16 档时长、28 个图标下标、
+//! 形状阶梯，以及「同族容器不撞色」的回归（reviewer P3-2）。
+//!
+//! 期望值全部独立于实现重写；实现改一个数、表不改，这里就红。
+
+use unlucky_design::color::{Role, Scheme, SchemeFlavor};
+use unlucky_design::icons::IconKind;
+use unlucky_design::motion::{DurationToken, Easing};
+use unlucky_design::shape::ShapeScale;
+
+fn expect_tone(role: Role, light: f64, dark: f64) {
+    assert_eq!(
+        Scheme::tone_of(role, SchemeFlavor::Light),
+        light,
+        "{} 的 light tone 被改动了",
+        role.name()
+    );
+    assert_eq!(
+        Scheme::tone_of(role, SchemeFlavor::Dark),
+        dark,
+        "{} 的 dark tone 被改动了",
+        role.name()
+    );
+}
+
+#[test]
+fn all_forty_nine_tones_are_pinned() {
+    expect_tone(Role::Primary, 40.0, 80.0);
+    expect_tone(Role::OnPrimary, 100.0, 20.0);
+    expect_tone(Role::PrimaryContainer, 90.0, 30.0);
+    expect_tone(Role::OnPrimaryContainer, 30.0, 90.0);
+    expect_tone(Role::Secondary, 40.0, 80.0);
+    expect_tone(Role::OnSecondary, 100.0, 20.0);
+    expect_tone(Role::SecondaryContainer, 90.0, 30.0);
+    expect_tone(Role::OnSecondaryContainer, 30.0, 90.0);
+    expect_tone(Role::Tertiary, 40.0, 80.0);
+    expect_tone(Role::OnTertiary, 100.0, 20.0);
+    expect_tone(Role::TertiaryContainer, 90.0, 30.0);
+    expect_tone(Role::OnTertiaryContainer, 30.0, 90.0);
+    expect_tone(Role::Error, 40.0, 80.0);
+    expect_tone(Role::OnError, 100.0, 20.0);
+    expect_tone(Role::ErrorContainer, 90.0, 30.0);
+    expect_tone(Role::OnErrorContainer, 30.0, 90.0);
+    expect_tone(Role::Surface, 98.0, 6.0);
+    expect_tone(Role::OnSurface, 10.0, 90.0);
+    expect_tone(Role::SurfaceVariant, 90.0, 30.0);
+    expect_tone(Role::OnSurfaceVariant, 30.0, 80.0);
+    expect_tone(Role::Background, 98.0, 6.0);
+    expect_tone(Role::OnBackground, 10.0, 90.0);
+    expect_tone(Role::SurfaceDim, 87.0, 6.0);
+    expect_tone(Role::SurfaceBright, 98.0, 24.0);
+    expect_tone(Role::SurfaceContainerLowest, 100.0, 4.0);
+    expect_tone(Role::SurfaceContainerLow, 96.0, 10.0);
+    expect_tone(Role::SurfaceContainer, 94.0, 12.0);
+    expect_tone(Role::SurfaceContainerHigh, 92.0, 17.0);
+    expect_tone(Role::SurfaceContainerHighest, 90.0, 22.0);
+    expect_tone(Role::Outline, 50.0, 60.0);
+    expect_tone(Role::OutlineVariant, 80.0, 30.0);
+    expect_tone(Role::InverseSurface, 20.0, 90.0);
+    expect_tone(Role::InverseOnSurface, 95.0, 20.0);
+    expect_tone(Role::InversePrimary, 80.0, 40.0);
+    expect_tone(Role::Shadow, 0.0, 0.0);
+    expect_tone(Role::Scrim, 0.0, 0.0);
+    expect_tone(Role::SurfaceTint, 40.0, 80.0);
+    expect_tone(Role::PrimaryFixed, 90.0, 90.0);
+    expect_tone(Role::PrimaryFixedDim, 80.0, 80.0);
+    expect_tone(Role::OnPrimaryFixed, 10.0, 10.0);
+    expect_tone(Role::OnPrimaryFixedVariant, 30.0, 30.0);
+    expect_tone(Role::SecondaryFixed, 90.0, 90.0);
+    expect_tone(Role::SecondaryFixedDim, 80.0, 80.0);
+    expect_tone(Role::OnSecondaryFixed, 10.0, 10.0);
+    expect_tone(Role::OnSecondaryFixedVariant, 30.0, 30.0);
+    expect_tone(Role::TertiaryFixed, 90.0, 90.0);
+    expect_tone(Role::TertiaryFixedDim, 80.0, 80.0);
+    expect_tone(Role::OnTertiaryFixed, 10.0, 10.0);
+    expect_tone(Role::OnTertiaryFixedVariant, 30.0, 30.0);
+}
+
+#[test]
+fn easing_curves_are_pinned() {
+    let cases: [(Easing, f32, f32, f32, f32); 7] = [
+        (Easing::Linear, 0.0, 0.0, 1.0, 1.0),
+        (Easing::Standard, 0.2, 0.0, 0.0, 1.0),
+        (Easing::StandardDecelerate, 0.0, 0.0, 0.0, 1.0),
+        (Easing::StandardAccelerate, 0.3, 0.0, 1.0, 1.0),
+        (Easing::Emphasized, 0.2, 0.0, 0.0, 1.0),
+        (Easing::EmphasizedDecelerate, 0.05, 0.7, 0.1, 1.0),
+        (Easing::EmphasizedAccelerate, 0.3, 0.0, 0.8, 0.15),
+    ];
+    for (easing, x1, y1, x2, y2) in cases {
+        let curve = easing.curve();
+        assert_eq!(
+            (curve.x1, curve.y1, curve.x2, curve.y2),
+            (x1, y1, x2, y2),
+            "{easing:?} 的曲线参数被改动了"
+        );
+    }
+}
+
+#[test]
+fn durations_are_pinned() {
+    let cases: [(DurationToken, u32); 16] = [
+        (DurationToken::Short1, 50),
+        (DurationToken::Short2, 100),
+        (DurationToken::Short3, 150),
+        (DurationToken::Short4, 200),
+        (DurationToken::Medium1, 250),
+        (DurationToken::Medium2, 300),
+        (DurationToken::Medium3, 350),
+        (DurationToken::Medium4, 400),
+        (DurationToken::Long1, 450),
+        (DurationToken::Long2, 500),
+        (DurationToken::Long3, 550),
+        (DurationToken::Long4, 600),
+        (DurationToken::ExtraLong1, 700),
+        (DurationToken::ExtraLong2, 800),
+        (DurationToken::ExtraLong3, 900),
+        (DurationToken::ExtraLong4, 1000),
+    ];
+    for (token, ms) in cases {
+        assert_eq!(token.ms(), ms, "{} 的毫秒值被改动了", token.name());
+    }
+}
+
+#[test]
+fn spring_presets_are_pinned() {
+    use unlucky_design::motion::{
+        spring, MotionSchemeKind, Spring, SpringCategory, SpringSpeed, SPRING_EFFECTS_DEFAULT,
+        SPRING_EFFECTS_FAST, SPRING_EFFECTS_SLOW, SPRING_EXPRESSIVE_SPATIAL_DEFAULT,
+        SPRING_EXPRESSIVE_SPATIAL_FAST, SPRING_EXPRESSIVE_SPATIAL_SLOW,
+        SPRING_STANDARD_SPATIAL_DEFAULT, SPRING_STANDARD_SPATIAL_FAST,
+        SPRING_STANDARD_SPATIAL_SLOW,
+    };
+    // A 级：StandardMotionTokens / ExpressiveMotionTokens（damping = 阻尼比 ζ，stiffness = k）。
+    let cases: [(Spring, f32, f32); 9] = [
+        // standard 方案 spatial：ζ=0.9（保守）
+        (SPRING_STANDARD_SPATIAL_FAST, 1400.0, 0.9),
+        (SPRING_STANDARD_SPATIAL_DEFAULT, 700.0, 0.9),
+        (SPRING_STANDARD_SPATIAL_SLOW, 300.0, 0.9),
+        // expressive 方案 spatial：ζ=0.6/0.8（回弹明显）
+        (SPRING_EXPRESSIVE_SPATIAL_FAST, 800.0, 0.6),
+        (SPRING_EXPRESSIVE_SPATIAL_DEFAULT, 380.0, 0.8),
+        (SPRING_EXPRESSIVE_SPATIAL_SLOW, 200.0, 0.8),
+        // effects 两套同值：ζ=1.0（不过冲）
+        (SPRING_EFFECTS_FAST, 3800.0, 1.0),
+        (SPRING_EFFECTS_DEFAULT, 1600.0, 1.0),
+        (SPRING_EFFECTS_SLOW, 800.0, 1.0),
+    ];
+    for (entry, stiffness, damping_ratio) in cases {
+        assert_eq!(entry.stiffness, stiffness, "弹簧刚度被改动");
+        assert_eq!(entry.damping_ratio, damping_ratio, "弹簧阻尼比被改动");
+    }
+    // 二维表查询与常量必须一致（改了表结构也别想绕过 pin）。
+    assert_eq!(
+        spring(
+            MotionSchemeKind::Expressive,
+            SpringCategory::Spatial,
+            SpringSpeed::Default
+        ),
+        SPRING_EXPRESSIVE_SPATIAL_DEFAULT
+    );
+    assert_eq!(
+        spring(
+            MotionSchemeKind::Standard,
+            SpringCategory::Spatial,
+            SpringSpeed::Fast
+        ),
+        SPRING_STANDARD_SPATIAL_FAST
+    );
+}
+
+#[test]
+fn icon_indices_are_pinned() {
+    let names = [
+        "instances",
+        "download",
+        "logs",
+        "settings",
+        "ai",
+        "play",
+        "stop",
+        "search",
+        "plus",
+        "close",
+        "minimize",
+        "maximize",
+        "chevron-left",
+        "chevron-right",
+        "chevron-down",
+        "expand",
+        "send",
+        "check",
+        "warn",
+        "error",
+        "more",
+        "sidebar",
+        "restore",
+        "user",
+        "refresh",
+        "filter",
+        "folder",
+        "trash",
+    ];
+    assert_eq!(IconKind::ALL.len(), names.len());
+    for (i, kind) in IconKind::ALL.iter().enumerate() {
+        assert_eq!(
+            kind.name(),
+            names[i],
+            "第 {i} 个图标被换位/改名了（序号即持久化 id）"
+        );
+    }
+}
+
+#[test]
+fn shape_ladder_is_pinned() {
+    let cases: [(ShapeScale, f32); 9] = [
+        (ShapeScale::None, 0.0),
+        (ShapeScale::ExtraSmall, 4.0),
+        (ShapeScale::Small, 8.0),
+        (ShapeScale::Medium, 12.0),
+        (ShapeScale::Large, 16.0),
+        (ShapeScale::LargeIncreased, 20.0),
+        (ShapeScale::ExtraLarge, 28.0),
+        (ShapeScale::ExtraLargeIncreased, 32.0),
+        (ShapeScale::ExtraExtraLarge, 48.0),
+    ];
+    for (scale, dp) in cases {
+        assert_eq!(scale.dp(), dp, "{scale:?} 的半径档位被改动了");
+    }
+    assert_eq!(ShapeScale::Full.radius_px(64.0), 32.0);
+}
+
+#[test]
+fn same_family_containers_do_not_collide() {
+    // P3-2 回归：light 模式下 primary-container / secondary-container 曾经被 gamut 裁剪成同色。
+    let light = Scheme::baseline(SchemeFlavor::Light);
+    let primary = light.get(Role::PrimaryContainer);
+    let secondary = light.get(Role::SecondaryContainer);
+    assert_ne!(
+        primary, secondary,
+        "同族容器撞色（彩度压缩没生效）：{primary:?}"
+    );
+    // secondary-container 必须比 primary-container 更灰（M3 的「次级」语义）。
+    let c_primary = unlucky_design::color::Hct::from_color(primary).chroma;
+    let c_secondary = unlucky_design::color::Hct::from_color(secondary).chroma;
+    assert!(
+        c_secondary < c_primary,
+        "secondary-container 彩度 {c_secondary} 应低于 primary-container {c_primary}"
+    );
+    // tertiary 与 primary 也该可区分（不同色相）。
+    assert_ne!(light.get(Role::TertiaryContainer), primary);
+}
diff --git a/crates/design/tests/tokext_pins.rs b/crates/design/tests/tokext_pins.rs
new file mode 100644
index 0000000..3f3b32e
--- /dev/null
+++ b/crates/design/tests/tokext_pins.rs
@@ -0,0 +1,297 @@
+//! M69（TOKEXT）的数值钉死：G9~G13 五项缺口逐条关门。
+//!
+//! 期望值全部**独立于实现重写**（照 `research/15` §18~§23 与 `00-decision-log.md` D32/D33 抄），
+//! 实现改一个数、这里不改就红。覆盖：
+//! - **G13** `ComponentRadius` 白名单 + 尺寸闸（2 不在 `ShapeScale` 里，刻度不许被加宽）；
+//! - **G11** `LayoutMetrics` 的 4 个新骨架值 + nav 语义修正；
+//! - **G10** `ComponentMetrics` 逐字段；
+//! - **G9** `Component` 25 个变体与档位表一行对一行；
+//! - **G12** 一像素线单一真源。
+
+use unlucky_design::component_map::{Component, ComponentMetrics};
+use unlucky_design::elevation::Elevation;
+use unlucky_design::icons::IconSize;
+use unlucky_design::shape::{radius_layer_for, ComponentRadius, RadiusLayer, ShapeScale};
+use unlucky_design::spacing::{stroke, LayoutMetrics, Space};
+use unlucky_design::typography::TypeRole;
+
+// ---------- G13：圆角分层（D32） ----------
+
+#[test]
+fn shape_scale_is_unchanged_and_never_contains_two() {
+    // 刻度一个字都不许动（D32 第 1 条：ShapeScale 保持严格）。
+    let ladder: [(ShapeScale, f32); 9] = [
+        (ShapeScale::None, 0.0),
+        (ShapeScale::ExtraSmall, 4.0),
+        (ShapeScale::Small, 8.0),
+        (ShapeScale::Medium, 12.0),
+        (ShapeScale::Large, 16.0),
+        (ShapeScale::LargeIncreased, 20.0),
+        (ShapeScale::ExtraLarge, 28.0),
+        (ShapeScale::ExtraLargeIncreased, 32.0),
+        (ShapeScale::ExtraExtraLarge, 48.0),
+    ];
+    for (scale, dp) in ladder {
+        assert_eq!(scale.dp(), dp, "{scale:?} 的刻度被改动了");
+        // 2 是官方 Checkbox 的圆角，但它**不在**刻度里——加进来就等于废掉 K1 守门。
+        assert_ne!(dp, 2.0, "2dp 不许进 ShapeScale（走 ComponentRadius）");
+    }
+    assert_eq!(ShapeScale::Full.radius_px(64.0), 32.0);
+}
+
+#[test]
+fn component_radius_is_a_one_item_whitelist() {
+    assert_eq!(ComponentRadius::ALL, [ComponentRadius::Micro]);
+    // 2dp 只能通过带尺寸闸的 `radius_px` 拿到（`dp()` 是 crate 内部口，外部看不见）。
+    assert_eq!(
+        ComponentRadius::Micro.radius_px(20.0),
+        Some(2.0),
+        "官方 Checkbox RadiusSize = 2.dp"
+    );
+    // 尺寸闸：>24dp 一律拿不到微半径（D32 的「只允许 ≤24dp 微控件」）。
+    assert_eq!(ComponentRadius::Micro.radius_px(24.0), Some(2.0));
+    assert_eq!(ComponentRadius::Micro.radius_px(25.0), None);
+    assert_eq!(ComponentRadius::Micro.radius_px(240.0), None);
+    assert_eq!(ComponentRadius::Micro.radius_px(0.0), None);
+    // 边长小于两倍半径时按边长一半折算（2dp 元素不能有 2dp 圆角）。
+    assert_eq!(ComponentRadius::Micro.radius_px(2.0), Some(1.0));
+}
+
+#[test]
+fn radius_layer_for_routes_by_size() {
+    assert_eq!(radius_layer_for(20.0), RadiusLayer::Component);
+    assert_eq!(radius_layer_for(24.0), RadiusLayer::Component);
+    assert_eq!(radius_layer_for(28.0), RadiusLayer::Scale);
+    assert_eq!(radius_layer_for(360.0), RadiusLayer::Scale);
+    // 抽屉/面板这类容器永远不该被判成微控件。
+    for container in [
+        LayoutMetrics::DESKTOP.nav_drawer_width,
+        LayoutMetrics::DESKTOP.ai_panel_width,
+    ] {
+        assert_eq!(radius_layer_for(container), RadiusLayer::Scale);
+    }
+}
+
+// ---------- G11：骨架值 + nav 语义修正 ----------
+
+#[test]
+fn layout_metrics_new_skeleton_values_are_pinned() {
+    let m = LayoutMetrics::DESKTOP;
+    // A 级：SearchBarTokens.ContainerHeight = 56。
+    assert_eq!(m.search_bar_height, 56.0);
+    // A 级：NavigationDrawer 下限 240（官方 ContainerWidth = 360，1180 窗下过宽，D33 取 240）。
+    assert_eq!(m.nav_drawer_width, 240.0);
+    // 12b §5.1 登记偏离：官方 rail 96 → 本项目 88。
+    assert_eq!(m.nav_rail_width, 88.0);
+    // A 级：DividerTokens.Thickness = 1.0dp（一像素线，不受 4px 栅格约束）。
+    assert_eq!(m.divider_thickness, 1.0);
+}
+
+#[test]
+fn nav_widths_mean_what_their_names_say() {
+    // D33：展开（drawer）比折叠（rail）宽；旧字段 nav_expanded_width=88 / nav_collapsed_width=48
+    // 的名字与值相反，已在 M69 改名并删除，这里钉住「新名字不会再次反向」。
+    let m = LayoutMetrics::DESKTOP;
+    assert!(
+        m.nav_drawer_width > m.nav_rail_width,
+        "展开态（drawer {}）必须比折叠态（rail {}）宽",
+        m.nav_drawer_width,
+        m.nav_rail_width
+    );
+    // rail 里 56 宽的选中指示器要放得下（88 − 2×16）。
+    assert_eq!(m.nav_rail_width - Space::X4.dp() * 2.0, 56.0);
+    // drawer 里 216 宽的指示器同样由「宽 − 2×12」推出（见 ComponentMetrics::indicator_width）。
+    assert_eq!(
+        ComponentMetrics::NAVIGATION_DRAWER.indicator_width(m.nav_drawer_width),
+        216.0
+    );
+}
+
+// ---------- G10：组件级微度量 ----------
+
+#[test]
+fn checkbox_metrics_are_pinned() {
+    let cm = ComponentMetrics::CHECKBOX;
+    // 20×20（不是 token 文件里那个死值 18，见 research/15 §26.2 矛盾 ①）。
+    assert_eq!((cm.width, cm.height), (20.0, 20.0));
+    assert_eq!(
+        cm.radius,
+        Some(ComponentRadius::Micro),
+        "圆角 2dp 走 D32 第二层"
+    );
+    assert_eq!(cm.stroke, 2.0, "CheckboxTokens.UnselectedOutlineWidth = 2");
+    assert_eq!(cm.state_layer, 40.0, "StateLayerSize = 40");
+    assert_eq!(cm.inner_dot, 0.0);
+    assert_eq!(cm.gap, Space::X2.dp(), "框 ↔ 标签 8（团队口径）");
+    assert_eq!(
+        Component::Checkbox.metrics(),
+        Some(ComponentMetrics::CHECKBOX)
+    );
+}
+
+#[test]
+fn radio_metrics_are_pinned() {
+    let cm = ComponentMetrics::RADIO;
+    assert_eq!(
+        (cm.width, cm.height),
+        (20.0, 20.0),
+        "RadioButtonTokens.IconSize = 20"
+    );
+    assert_eq!(cm.stroke, 2.0, "RadioStrokeWidth = 2.dp");
+    // 内点 10 不是 12：12 是含描边前的名义值（绘制半径 = 6 − 1 = 5）。
+    assert_eq!(cm.inner_dot, 10.0);
+    assert_eq!(cm.state_layer, 40.0);
+    assert_eq!(cm.radius, None, "radio 是真圆，圆角走 ShapeScale::Full");
+    assert_eq!(Component::Radio.spec().shape, ShapeScale::Full);
+}
+
+#[test]
+fn search_bar_metrics_are_pinned() {
+    let cm = ComponentMetrics::SEARCH_BAR;
+    // 高 56 属骨架级：CM 里必须留 0，不许重复一份。
+    assert_eq!((cm.width, cm.height), (0.0, 0.0));
+    assert_eq!(cm.icon, IconSize::Toolbar.px(), "leading/trailing 图标 24");
+    // A 级（§20.4）：图标可视左缘 16 = 文本框内容内边距 12 + `SearchBarIconOffsetX = 4`。
+    assert_eq!(cm.pad_start, Space::X3.dp(), "内容内边距 12");
+    assert_eq!(cm.icon_offset, 4.0, "SearchBarIconOffsetX = 4");
+    assert_eq!(cm.pad_start + cm.icon_offset, 16.0, "图标可视左缘必须是 16");
+    // 右侧同式：图标右缘也是 16。
+    assert_eq!(cm.pad_end, Space::X3.dp());
+    assert_eq!(cm.pad_end + cm.icon_offset, 16.0, "图标可视右缘必须是 16");
+    // 守门：不许把 pad 本身写成 16（否则 pad + offset = 20，越过 rubric 的 ±2px）。
+    assert_ne!(cm.pad_start, 16.0);
+    assert_ne!(cm.pad_end, 16.0);
+    // 搜索条圆角 = 高/2 = 28，等于官方 SearchBarCornerRadius。
+    assert_eq!(
+        ShapeScale::Full.radius_px(LayoutMetrics::DESKTOP.search_bar_height),
+        28.0
+    );
+}
+
+#[test]
+fn navigation_drawer_metrics_are_pinned() {
+    let cm = ComponentMetrics::NAVIGATION_DRAWER;
+    assert_eq!((cm.width, cm.height), (0.0, 0.0), "宽/项高属骨架级");
+    assert_eq!(
+        cm.inset, 12.0,
+        "NavigationDrawerItemDefaults.ItemPadding = 12"
+    );
+    assert_eq!(cm.pad_start, Space::X4.dp(), "项内 start 16");
+    assert_eq!(cm.pad_end, Space::X6.dp(), "项内 end 24");
+    assert_eq!(cm.icon, IconSize::Toolbar.px());
+    // 与 search bar 同一条公式：图标边 = pad + icon_offset（抽屉的 offset 是 0）。
+    assert_eq!(cm.pad_start + cm.icon_offset, 16.0, "图标起点 = 项内 start");
+    assert_eq!(cm.gap, Space::X3.dp(), "图标 ↔ label 12");
+    // 指示器宽 = 容器宽 − 24；官方 360 − 24 = 336，本项目 240 − 24 = 216。
+    assert_eq!(cm.indicator_width(360.0), 336.0);
+    assert_eq!(cm.indicator_width(240.0), 216.0);
+}
+
+#[test]
+fn component_metrics_never_duplicate_layout_metrics() {
+    // 同一量只许一份：CM 里出现的骨架级尺寸必须留 0。
+    let m = LayoutMetrics::DESKTOP;
+    for component in [Component::Search, Component::NavigationDrawer] {
+        let cm = component.metrics().expect("这两个控件必须有 CM");
+        assert_eq!(cm.width, 0.0, "{} 的宽度属 LM", component.name());
+        assert_eq!(cm.height, 0.0, "{} 的高度属 LM", component.name());
+        assert_ne!(cm.height, m.search_bar_height);
+        assert_ne!(cm.width, m.nav_drawer_width);
+    }
+    // Divider 的厚度也是 LM（一像素线）→ 它没有 CM。
+    assert_eq!(Component::Divider.metrics(), None);
+    assert_eq!(m.divider_thickness, stroke::HAIRLINE);
+}
+
+// ---------- G12：一像素线 ----------
+
+#[test]
+fn hairline_is_the_single_source_of_one_pixel_lines() {
+    assert_eq!(stroke::HAIRLINE, 1.0);
+    // 分隔线厚度直接引用它，不是另写一个字面量。
+    assert_eq!(LayoutMetrics::DESKTOP.divider_thickness, stroke::HAIRLINE);
+    // 一像素线不受 4px 栅格约束（栅格测试里显式豁免，这里反向钉一次）。
+    assert_ne!(stroke::HAIRLINE % unlucky_design::spacing::GRID, 0.0);
+}
+
+// ---------- G9：枚举 25 变体 ↔ 表槽位 ----------
+
+#[test]
+fn component_enum_is_the_frozen_twenty_five() {
+    let names = [
+        "top-app-bar",
+        "navigation-item",
+        "primary-button",
+        "secondary-button",
+        "text-button",
+        "icon-button",
+        "outlined-card",
+        "filled-card",
+        "list-item",
+        "text-field",
+        "segmented-button",
+        "chip",
+        "switch",
+        "slider",
+        "progress-indicator",
+        "dialog",
+        "menu",
+        "snackbar",
+        "tooltip",
+        "empty-state",
+        // M69 末尾追加的 5 个
+        "checkbox",
+        "radio",
+        "search",
+        "navigation-drawer",
+        "divider",
+    ];
+    assert_eq!(Component::ALL.len(), names.len(), "M66 的 G9：20 → 25");
+    for (i, component) in Component::ALL.iter().enumerate() {
+        assert_eq!(component.name(), names[i], "第 {i} 个组件被换位/改名了");
+        // 表槽位与枚举判别值一一对应（`spec()` 就是按下标取的）。
+        assert_eq!(*component as usize, i);
+        assert_eq!(component.spec().component, *component);
+    }
+}
+
+#[test]
+fn new_components_carry_the_official_elevation_and_shape() {
+    // Checkbox / Radio / Search / NavigationDrawer / Divider：全部 L0（都不是浮层）。
+    for component in [
+        Component::Checkbox,
+        Component::Radio,
+        Component::Search,
+        Component::NavigationDrawer,
+        Component::Divider,
+    ] {
+        assert_eq!(
+            component.spec().elevation,
+            Elevation::Level0,
+            "{} 不该有阴影（R4：只有浮层允许）",
+            component.name()
+        );
+    }
+    // Checkbox 的圆角真源是 micro_radius，shape 只是占位 None。
+    let checkbox = Component::Checkbox.spec();
+    assert_eq!(checkbox.micro_radius, Some(ComponentRadius::Micro));
+    assert_eq!(checkbox.shape, ShapeScale::None);
+    // 其余 4 个不碰微半径层。
+    for component in [
+        Component::Radio,
+        Component::Search,
+        Component::NavigationDrawer,
+        Component::Divider,
+    ] {
+        assert_eq!(component.spec().micro_radius, None, "{}", component.name());
+    }
+    // NavigationDrawer = CornerLargeEnd 的内侧角 16；Divider 无圆角。
+    assert_eq!(Component::NavigationDrawer.spec().shape, ShapeScale::Large);
+    assert_eq!(Component::Divider.spec().shape, ShapeScale::None);
+    // Checkbox / Radio 的标签字级是团队口径（官方无「框 + 标签」token）。
+    assert_eq!(Component::Checkbox.spec().text, TypeRole::BodyLarge);
+    assert_eq!(Component::Radio.spec().text, TypeRole::BodyLarge);
+    // Search 的字级：输入 BodyLarge、占位/辅助 BodySmall。
+    assert_eq!(Component::Search.spec().text, TypeRole::BodyLarge);
+    assert_eq!(Component::Search.spec().support, Some(TypeRole::BodySmall));
+}
diff --git a/crates/design/tests/type_scale_pins.rs b/crates/design/tests/type_scale_pins.rs
new file mode 100644
index 0000000..990537f
--- /dev/null
+++ b/crates/design/tests/type_scale_pins.rs
@@ -0,0 +1,106 @@
+//! 官方数值钉死（一）：**排版两张表**（baseline 15 档 + Expressive 强调 15 档）。
+//!
+//! 表的来源是 A 级 `androidx.compose.material3.tokens.TypeScaleTokens`（v0_103）。这里的期望值是
+//! **独立于实现重写的一份**：任何人改动 `TypeRole::style()` / `emphasized()` 的数值，都必须同时改
+//! 这张表才会同时绿——这就是「冻结」的含义（reviewer P2-1 的变异测试就是打这里）。
+
+use unlucky_design::typography::{FontFamily, TypeRole, Weight};
+
+/// baseline 单档对拍。
+fn expect_baseline(
+    role: TypeRole,
+    size: f32,
+    line_height: f32,
+    weight: Weight,
+    tracking: f32,
+    family: FontFamily,
+) {
+    let got = role.style();
+    assert_eq!(
+        (
+            got.size_px,
+            got.line_height_px,
+            got.weight,
+            got.letter_spacing_px,
+            got.family
+        ),
+        (size, line_height, weight, tracking, family),
+        "{} 的 baseline 值被改动了（官方 TypeScaleTokens）",
+        role.name()
+    );
+}
+
+/// Expressive 强调档单档对拍。
+fn expect_emphasized(role: TypeRole, size: f32, line_height: f32, weight: Weight, tracking: f32) {
+    let got = role.emphasized();
+    assert_eq!(
+        (
+            got.size_px,
+            got.line_height_px,
+            got.weight,
+            got.letter_spacing_px
+        ),
+        (size, line_height, weight, tracking),
+        "{} 的 Expressive 强调档值被改动了（官方 TypeScaleTokens *Emphasized*）",
+        role.name()
+    );
+}
+
+#[test]
+fn baseline_type_scale_matches_official_tokens() {
+    use FontFamily::{Display, Text};
+    use Weight::{Bold, Medium, Regular};
+    expect_baseline(TypeRole::DisplayLarge, 57.0, 64.0, Regular, -0.2, Display);
+    expect_baseline(TypeRole::DisplayMedium, 45.0, 52.0, Regular, 0.0, Display);
+    expect_baseline(TypeRole::DisplaySmall, 36.0, 44.0, Regular, 0.0, Display);
+    expect_baseline(TypeRole::HeadlineLarge, 32.0, 40.0, Regular, 0.0, Display);
+    expect_baseline(TypeRole::HeadlineMedium, 28.0, 36.0, Regular, 0.0, Display);
+    expect_baseline(TypeRole::HeadlineSmall, 24.0, 32.0, Regular, 0.0, Display);
+    expect_baseline(TypeRole::TitleLarge, 22.0, 28.0, Regular, 0.0, Display);
+    expect_baseline(TypeRole::TitleMedium, 16.0, 24.0, Medium, 0.2, Text);
+    expect_baseline(TypeRole::TitleSmall, 14.0, 20.0, Medium, 0.1, Text);
+    expect_baseline(TypeRole::BodyLarge, 16.0, 24.0, Regular, 0.5, Text);
+    expect_baseline(TypeRole::BodyMedium, 14.0, 20.0, Regular, 0.2, Text);
+    expect_baseline(TypeRole::BodySmall, 12.0, 16.0, Regular, 0.4, Text);
+    expect_baseline(TypeRole::LabelLarge, 14.0, 20.0, Medium, 0.1, Text);
+    expect_baseline(TypeRole::LabelMedium, 12.0, 16.0, Medium, 0.5, Text);
+    expect_baseline(TypeRole::LabelSmall, 11.0, 16.0, Medium, 0.5, Text);
+    let _ = Bold;
+}
+
+#[test]
+fn expressive_emphasis_matches_official_tokens() {
+    use Weight::{Bold, Medium};
+    // 展示/正文类强调 → Medium(500)；label 与小标题 → Bold(700)。
+    expect_emphasized(TypeRole::DisplayLarge, 57.0, 64.0, Medium, 0.0);
+    expect_emphasized(TypeRole::DisplayMedium, 45.0, 52.0, Medium, 0.0);
+    expect_emphasized(TypeRole::DisplaySmall, 36.0, 44.0, Medium, 0.0);
+    expect_emphasized(TypeRole::HeadlineLarge, 32.0, 40.0, Medium, 0.0);
+    expect_emphasized(TypeRole::HeadlineMedium, 28.0, 36.0, Medium, 0.0);
+    expect_emphasized(TypeRole::HeadlineSmall, 24.0, 32.0, Medium, 0.0);
+    expect_emphasized(TypeRole::TitleLarge, 22.0, 28.0, Medium, 0.0);
+    expect_emphasized(TypeRole::TitleMedium, 16.0, 24.0, Bold, 0.15);
+    expect_emphasized(TypeRole::TitleSmall, 14.0, 20.0, Bold, 0.1);
+    expect_emphasized(TypeRole::BodyLarge, 16.0, 24.0, Medium, 0.15);
+    expect_emphasized(TypeRole::BodyMedium, 14.0, 20.0, Medium, 0.25);
+    expect_emphasized(TypeRole::BodySmall, 12.0, 16.0, Medium, 0.4);
+    expect_emphasized(TypeRole::LabelLarge, 14.0, 20.0, Bold, 0.1);
+    expect_emphasized(TypeRole::LabelMedium, 12.0, 16.0, Bold, 0.5);
+    expect_emphasized(TypeRole::LabelSmall, 11.0, 16.0, Bold, 0.5);
+}
+
+#[test]
+fn both_tables_cover_all_fifteen_roles() {
+    // 防止「表里少写一档」：15 个角色都必须被上面两张表摸到。
+    let mut names = std::collections::BTreeSet::new();
+    for role in TypeRole::ALL {
+        names.insert(role.name());
+        assert_ne!(
+            role.style(),
+            role.emphasized(),
+            "{} 强调档等同 baseline",
+            role.name()
+        );
+    }
+    assert_eq!(names.len(), 15);
+}
diff --git a/crates/i18n/Cargo.toml b/crates/i18n/Cargo.toml
new file mode 100644
index 0000000..c7cbdc8
--- /dev/null
+++ b/crates/i18n/Cargo.toml
@@ -0,0 +1,20 @@
+[package]
+name = "unlucky-i18n"
+description = "Unlucky-Launcher 国际化地基（D28）：语言探测 / 中英消息目录 + 编译期 key 校验 / 缺译诊断 / 中文字体策略与注入式下载器接口"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+publish.workspace = true
+
+# 依赖面必须保持**空**（与 `unlucky-design` 同一条纪律）：
+# 1. 它要被 UI 层（iced / 将来的任何壳）与 `presenter` 同时依赖，一旦引入 iced/slint 就锁死了渲染框架；
+# 2. 它是**纯数据 + 纯函数**：消息目录是 `&'static str` 常量表，探测与字体扫描全部靠**注入**拿外部世界；
+# 3. 语言探测/字体策略是启动路径上的第一件事，不该为了一句 "en"/"zh-CN" 拉进任何运行时。
+# 证据命令：cargo tree -p unlucky-i18n --edges normal（应当只打印它自己）。
+[dependencies]
+
+[lints]
+workspace = true
diff --git a/crates/i18n/src/bridge.rs b/crates/i18n/src/bridge.rs
new file mode 100644
index 0000000..1c095dd
--- /dev/null
+++ b/crates/i18n/src/bridge.rs
@@ -0,0 +1,184 @@
+//! 文案边界（示例契约）：core / presenter 的**状态**怎么进 UI。
+//!
+//! ## 现状（为什么需要这份契约）
+//!
+//! UI 文案硬编码英文，而 `core` / `presenter` 产出的状态串是中文，于是界面上已经出现
+//! `Launch failed · exit0 静默失败` 这种**一句话里中英混排**的东西，加载器徽标也在 `原版` / `Fabric`
+//! 之间混用。根因不是「译文不够」，是**边界没划**：谁产出文案、谁负责翻译，没有规则。
+//!
+//! ## 三条规则
+//!
+//! **R1 · UI 侧不产生文案，只翻译 key。**
+//!    UI 不许把片段拼成句子（`"Launch failed · " + reason`），也不许写中文字面量。
+//!    一句话 = 一个 key（[`crate::catalog`]），带变量的用 `{name}` 交给
+//!    [`crate::catalog::Catalog::render`]。拼接一旦发生，任何一套语言都拼不对（语序、标点、
+//!    量词都不一样），而且混排会立刻出现在截图里。
+//!
+//! **R2 · core 的中文串不进 UI。**
+//!    core / presenter 的中文（`原版`、`静默失败（exit 0 但游戏没起来）`、
+//!    `缺少库文件 foo.jar（…）`）是**日志 / CLI / 诊断报告**的文案，不是界面文案。
+//!    界面只能通过两条合法通道拿到「要显示什么」：
+//!    1. **结构化出口**（首选）：枚举 / DTO 字段 → 映射到 [`crate::Key`]。
+//!       例：`presenter::dto::LoaderKind::as_str()` 的稳定 id（`vanilla` / `fabric`）→
+//!       [`crate::Key::LoaderVanilla`]；`LogOutcome` 三态 → `LaunchOutcome*` 三 key。
+//!       好处是**新增一个枚举变体时编译器会逼你补映射**（`match` 非穷尽即报错）。
+//!    2. **过渡表**（[`classify`]）：只覆盖「已知会漏到界面的少数几个串」，逐条硬编码。
+//!       它是**债**，不是终点——新出现的未知串一律走第三条。
+//!
+//! **R3 · 认不出的串，不许画原文。**
+//!    [`CoreText::Untranslated`] 就是那种情况：UI 只许显示 [`crate::Key::CoreTextUntranslated`]
+//!    这个**故意难看**的兜底（`[system text not translated]`），并把原文写进日志。
+//!    这条比「先画上去以后再翻」严格，是因为后者永远不会被回头修——难看才会被修。
+//!    同时它是一件**上游缺陷的证据**：说明 core 欠一个结构化出口，应当报 finding 而不是在 UI 贴创可贴。
+//!
+//! ## 品牌专名（唯一的豁免）
+//!
+//! `Fabric` / `Forge` / `NeoForge` / `Quilt` / `OptiFine` / `LiteLoader` 是专有名词，**不翻译**
+//! （翻成「锻造」就没人认识了）。它们可以原样显示，但必须经 [`CoreText::Brand`] 判定——
+//! 也就是说「原样显示」是一个**显式决定**，不是「反正没译文就画原文」的默认行为。
+//!
+//! ## 诚实边界（抓得住什么 / 抓不住什么）
+//!
+//! - **抓得住**：本表里列到的串（映射正确、未知串不被放行）；
+//! - **抓不住**：core 明天新加一句中文——本 crate 不依赖 core（零依赖纪律），没有跨 crate 的一致性检查。
+//!   那条只能靠「core 侧只给枚举」的纪律 + 后续在 `crates/presenter` 里加一条守门测试
+//!   （例如：`*_view` 的字符串字段不许含 CJK 字符）。
+
+use crate::catalog::Key;
+
+/// 一段来自 `core` / `presenter` 的显示文本该怎么处理。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CoreText {
+    /// 品牌专名：原样显示（不翻译，见模块文档的豁免）。
+    Brand(&'static str),
+    /// 有对应 key：按当前语言取词。
+    Key(Key),
+    /// 不认识：只许显示 [`Key::CoreTextUntranslated`]，原文进日志。
+    Untranslated,
+}
+
+/// 已知会漏到界面的中文状态串 → key。
+///
+/// 每一条都得在 `crates/presenter` / `crates/core` 里找得到出处（注释里给位置），
+/// 不许凭想象加——凭空加的条目会让 [`classify`] 假装覆盖了实际没覆盖的东西。
+const LEGACY_STATUS: &[(&str, Key)] = &[
+    // `presenter::dto::instances::LoaderKind::label()` / `host::launch::loader_label()`
+    ("原版", Key::LoaderVanilla),
+    // `presenter::host::job.rs`：`LogOutcome::SilentFail` 的展示文字
+    ("静默失败（exit 0 但游戏没起来）", Key::LaunchOutcomeSilent),
+    // `presenter::mock_data.rs` 里的演示数据
+    ("exit0 静默失败", Key::LaunchOutcomeSilent),
+];
+
+/// 品牌专名（原样显示；**不得**翻译或拼进句子，UI 拼装仍然禁止）。
+const BRANDS: &[&str] = &[
+    "Fabric",
+    "Forge",
+    "NeoForge",
+    "Quilt",
+    "OptiFine",
+    "LiteLoader",
+];
+
+/// 契约总入口：core / presenter 的显示文本 → 该画什么。
+///
+/// 这是**示例契约**：形状（三分类 + 未知不放行）比表里的具体条目重要，接线 mission 按这个形状
+/// 把每条 UI 路径改过来，条目随上游结构化出口的落地逐条删掉。
+#[must_use]
+pub fn classify(text: &str) -> CoreText {
+    let trimmed = text.trim();
+    if trimmed.is_empty() {
+        return CoreText::Untranslated;
+    }
+
+    if let Some((_, key)) = LEGACY_STATUS.iter().find(|(legacy, _)| *legacy == trimmed) {
+        return CoreText::Key(*key);
+    }
+
+    if let Some(brand) = BRANDS.iter().find(|brand| **brand == trimmed) {
+        return CoreText::Brand(brand);
+    }
+
+    // `Fabric 0.16.5` 这类「品牌 + 版本号」也是合法显示：品牌之后只跟一个版本号时放行。
+    // 注意这里是**保守**放行：只有「一个词 + 空格 + 版本号」的形状才算，含中文的串绝不会进来。
+    if let Some((head, tail)) = trimmed.split_once(' ') {
+        if let Some(brand) = BRANDS.iter().find(|brand| **brand == head) {
+            if !tail.is_empty() && !tail.contains(char::is_whitespace) && !tail.chars().any(is_cjk)
+            {
+                return CoreText::Brand(brand);
+            }
+        }
+    }
+
+    CoreText::Untranslated
+}
+
+/// 是否 CJK 字符（`classify` 的保守放行判据用）。
+fn is_cjk(ch: char) -> bool {
+    // 0x2E80..=0x9FFF 已含 CJK 部首 / 假名 / 统一表意文字与 0x3000 段的中文标点，不再单列。
+    matches!(ch as u32, 0x2E80..=0x9FFF | 0xF900..=0xFAFF | 0xFF00..=0xFFEF)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn known_chinese_status_strings_map_to_keys() {
+        // 抓得住：过渡表条目的映射写错（把「原版」映到别的 key），以及「同一段意思两个 key」的漂移。
+        // 抓不住：core 那边改了这个中文串的措辞——那时这里会落到 Untranslated（**故意的**，
+        //         让漏译可见，而不是继续拿旧文案糊过去）。
+        assert_eq!(classify("原版"), CoreText::Key(Key::LoaderVanilla));
+        assert_eq!(
+            classify("静默失败（exit 0 但游戏没起来）"),
+            CoreText::Key(Key::LaunchOutcomeSilent)
+        );
+        assert_eq!(
+            classify("exit0 静默失败"),
+            CoreText::Key(Key::LaunchOutcomeSilent)
+        );
+        assert_eq!(
+            classify(" 原版 "),
+            CoreText::Key(Key::LoaderVanilla),
+            "前后空白要吃掉"
+        );
+    }
+
+    #[test]
+    fn brands_pass_through_and_are_never_translated() {
+        // 抓得住：品牌名被当成待翻译文案（`Fabric` → 某个 key 的译文就没人认识它了），
+        //         以及「品牌 + 版本号」这种合法徽标被判成未翻译。
+        // 抓不住：品牌名与版本号之间该用什么分隔（M3 令牌 / 排版层的事，不是本契约的事）。
+        assert_eq!(classify("Fabric"), CoreText::Brand("Fabric"));
+        assert_eq!(classify("Fabric 0.16.5"), CoreText::Brand("Fabric"));
+        assert_eq!(classify("NeoForge 21.1.72"), CoreText::Brand("NeoForge"));
+        assert_eq!(classify("Fabric 中文"), CoreText::Untranslated);
+        assert_eq!(classify("Fabric 0.16.5 beta"), CoreText::Untranslated);
+        assert_eq!(classify("FabricX"), CoreText::Untranslated);
+    }
+
+    #[test]
+    fn unknown_core_prose_is_refused_instead_of_printed_raw() {
+        // 抓得住：R3——未知中文（core 的诊断prose、`describe_warning` 的拼句）被放行到界面，
+        //         那正是 `Launch failed · exit0 静默失败` 这类混排的来源。
+        // 抓不住：UI 拿到 Untranslated 之后有没有真的只显示兜底（页面侧测试 + 截图验收）。
+        let leaks = [
+            "缺少库文件 lwjgl.jar（C:\\Users\\x\\.minecraft\\libs\\lwjgl.jar）",
+            "版本 JSON 没有 mainClass",
+            "退出码为 0 但疑似静默失败（3 条错误行）：游戏可能刚起来就被 mod 异常终止",
+            "",
+            "   ",
+        ];
+        for leak in leaks {
+            assert_eq!(classify(leak), CoreText::Untranslated, "{leak}");
+        }
+    }
+
+    #[test]
+    fn classify_never_returns_a_raw_unknown_string() {
+        // 抓得住：将来给 `CoreText` 加了「原样字符串」变体（那等于把 R3 废掉）。
+        // 抓不住：枚举里已有变体被误用——那要靠调用点 review。
+        let odd = "some untranslated english";
+        assert_eq!(classify(odd), CoreText::Untranslated);
+    }
+}
diff --git a/crates/i18n/src/catalog.rs b/crates/i18n/src/catalog.rs
new file mode 100644
index 0000000..3f76194
--- /dev/null
+++ b/crates/i18n/src/catalog.rs
@@ -0,0 +1,342 @@
+//! 消息目录：`Key` 枚举 + 中英两套常量表 + 取词 / 占位符渲染 / 缺译诊断。
+//!
+//! ## 为什么 key 是枚举而不是字符串
+//!
+//! 字符串 key（`"nav.instances"`）拼错了编译器一声不响，运行时才知道——本仓的说法是「运行时静默回落」。
+//! 枚举 key 把这类错误前移到**编译期**：`Key::NavInstance`（真名是 `NavInstances`）直接
+//! `error[E0599]`，不可能跑到运行时。
+//!
+//! **这里没有守卫测试**：曾经写过一个 `compile_fail` 文档测试想守这条，但复审实测它对
+//! 「把 `Key` 换成字符串包装类型」这类变异仍然全绿——它守的是「这段代码编译不过」，而不是
+//! 「编译期校验还在」。说不清真假的守卫比没有更糟，所以删了；这条纪律只靠枚举这个事实本身。
+//!
+//! ## 为什么两套译文写在**同一行**
+//!
+//! ```ignore
+//! NavInstances => ("Instances", "实例"),
+//! ```
+//!
+//! 一行就是「一个 key 的全部语言」。于是「加了 key 忘了译文」在结构上不可能发生——这比「运行时发现
+//! 缺译再诊断」更强。缺译诊断（[`Catalog::diagnose`]）因此有两个真实用途：
+//!
+//! 1. **注入目录**：后续 mission 用 [`Catalog::from_entries`] 加第三套（繁体 / 更多语言）时，
+//!    表格是手写的，缺条目的风险回来了；
+//! 2. **回归守门**：万一有人把这张表改回「两套各写一遍」，[`Catalog::missing`] 的守卫测试立刻红。
+//!
+//! ## 按域拆开（M99 `SETTINGSFRAME`）
+//!
+//! 条目表原先整张写在本文件里，而**设置页正文接下来由四条 mission 并行接**（java / download /
+//! language+appearance / ai+about），每条都要往这张表里加一批 key——同一张表就是四条线的冲突点。
+//! 现在一个域一个文件（`catalog/<域>.rs`），本文件只留：`catalog!` 宏、装配链、[`Catalog`] 与对外 API。
+//!
+//! | 文件 | 域 | 谁会长它 |
+//! |---|---|---|
+//! | [`nav`] / [`instances`] / [`loader`] / [`launch`] / [`font`] / [`core_text`] | 页面与运行时文案 | 各自页面 |
+//! | [`download`] / [`logs`] | 下载页 / 日志页（M94 / M95） | 那两页 |
+//! | `settings/`（`general` / `appearance` / `java` / `download` / `ai`） | 设置页，**一个分组一个文件** | 设置页四条线 |
+//! | [`general`] | 设置页 General 分组的**真控件**文案（语言选择器三档 + 主题/启动页/关闭三行） | M106 `I18NFOLLOW`（挂在链尾，既有顺序不动） |
+//!
+//! ### 域文件的形状（加 key 时照抄）
+//!
+//! ```ignore
+//! macro_rules! <域>_entries {
+//!     ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+//!         $next! { $($rest,)* {
+//!             $($acc)*
+//!             NavInstances => ("Instances", "实例"),
+//!         } }
+//!     };
+//! }
+//! pub(super) use <域>_entries;
+//! ```
+//!
+//! 它把本域条目**追加**到累积表 `$acc` 之后，再把「还没装配的域」原样交给 `$next`——最后交给
+//! [`finish`]，由它把整张表喂给 [`catalog!`]。**为什么非得这么绕**：`macro_rules!` 不能在
+//! 宏参数里展开另一个宏（`catalog! { nav_entries!() }` 只会把 `nav_entries!()` 当成普通 token），
+//! 也不能用元变量当宏名（`macro_rules! $name` 非法），所以只能「回调链」式累积。代价是每个域文件
+//! 都要重抄上面那 6 行签名——这是 `macro_rules!` 的固有成本，不是可以省掉的样板。
+//!
+//! ### 拆开之后仍然只有一个真相源
+//!
+//! 装配顺序写在下面那条调用里，**它等于 `Key` 的声明顺序**；[`golden`] 把拆分前那份
+//! `key -> (en, zh-CN)` 全量逐字节钉住（连顺序一起钉），所以「搬丢一条 / 两条互抄 / 顺序被调换」
+//! 都会红。
+//!
+//! ## 缺译时给什么
+//!
+//! **不回落**（绝不拿另一种语言顶替，用户会看到「一半英文一半中文」的界面而不自知）：
+//!
+//! - [`Catalog::get`] → `None`（严格调用方用它）；
+//! - [`Catalog::text`] → [`MISSING`]（`⟪missing⟫`，UI 上刺眼但一眼可辨）；
+//! - [`Catalog::render`] → `⟪missing:KeyName⟫`（带上 key 名，方便照着日志补译）。
+
+use crate::lang::Lang;
+
+/// 缺译占位符（`text()` 的返回；故意刺眼——宁可难看，也不许静默顶替）。
+pub const MISSING: &str = "⟪missing⟫";
+
+/// 生成 `Key` 枚举 + 两套常量表（一行 = 一个 key 的全部语言）。
+macro_rules! catalog {
+    ($($variant:ident => ($en:literal, $zh:literal)),+ $(,)?) => {
+        /// 可翻译文案的 key。**不存在时编译失败**（枚举变体名即契约）。
+        #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
+        pub enum Key {
+            $(
+                #[doc = concat!("en: `", $en, "` / zh-CN: `", $zh, "`")]
+                $variant,
+            )+
+        }
+
+        impl Key {
+            /// 全部 key（缺译诊断与完整性测试的遍历源）。
+            pub const ALL: &'static [Key] = &[$(Key::$variant),+];
+
+            /// 变体名（日志 / 缺译诊断里用来指认 key；不是文案）。
+            #[must_use]
+            pub const fn name(self) -> &'static str {
+                match self {
+                    $(Key::$variant => stringify!($variant),)+
+                }
+            }
+        }
+
+        const EN: &[(Key, &str)] = &[$((Key::$variant, $en)),+];
+        const ZH_CN: &[(Key, &str)] = &[$((Key::$variant, $zh)),+];
+    };
+}
+
+// --------------------------------------------------------------- 域装配
+
+/// 链的终点：把累积起来的所有条目交给 [`catalog!`]，生成 `Key` 与两张表。
+macro_rules! finish {
+    ({ $($acc:tt)* }) => { catalog! { $($acc)* } };
+}
+
+mod account;
+mod agent;
+mod content;
+mod core_text;
+mod download;
+mod font;
+mod general;
+mod instances;
+mod launch;
+mod loader;
+mod logs;
+mod nav;
+mod settings;
+
+/// 拆分前的 `key -> (en, zh-CN)` **逐字快照**（金表）。
+///
+/// ## 它是什么
+///
+/// M99 把 `catalog.rs` 的单张条目表按域拆到 `catalog/<域>.rs` 之后，这 72 行就是「拆分前那一份」
+/// 的原样导出：由拆分前的 `Catalog::of(En)` / `Catalog::of(ZhCn)` 逐条 `println!` 出来，
+/// 再原封不动抄进来（生成方式见 `tests.rs` 里 `split_keeps_every_translation` 的注释）。
+/// M108 在它上面改了 3 条（`NavDownload` / `DownloadTitle` / `DownloadSubtitle`）、追加了 1 条
+/// （`NavDownloadExpanded`）；M105/M106/M107 各自追加的条目也都在，整表现在是 138 条。
+///
+/// ## 为什么不是「数条数」
+///
+/// 条数相等抓不住任何一种真会发生的坏法：某条译文在搬移时被漏掉、另一条被复制两次，条数照旧。
+/// 这张表比的是**全量、逐字节、按声明顺序**的三元组，于是下面四种坏法都会红：
+///
+/// | 坏法 | 红在哪 |
+/// |---|---|
+/// | 某个 key 整条被搬丢 | 条数不等 / 该行 key 名对不上 |
+/// | 两条 key 的译文互抄（同 key 被覆盖到别的译文） | 该行 en 或 zh 不等 |
+/// | 某条译文改了一个字符 | 该行不等（`assert_eq!` 带原文） |
+/// | 域的顺序被调换（`Key` 的 `Ord` 与导出表顺序都靠它） | 该行 key 名对不上 |
+///
+/// **抓不住**：译文本身翻得对不对（金表是「拆分前」的快照，它只能证明「没变」）。
+///
+/// ## M108 更新了三条、新增了一条（版本管理改名）
+///
+/// 用户令（2026-11-04）把这页的显示名从「下载 / Downloads」改成「版本管理 / Version management」：
+/// [`Key::NavDownload`] / [`Key::DownloadTitle`] / [`Key::DownloadSubtitle`]
+/// 三条译文按令改掉，并**新增** [`Key::NavDownloadExpanded`]（240 展开态的全标签，
+/// 88 轨放不下 18 字符的英文，见 `catalog/nav.rs` 的「两条 key」一节）。
+///
+/// 其余各行仍逐字节等于拆分前那份快照——也就是说这张表现在证明的是「除这几条按令改过的，
+/// 其余一字未动」，不再是「整表一字未动」。
+///
+/// ## M120 动了实例页那一族（1 条改译文 + 1 条删除 + 28 条新增）
+///
+/// 实例页的文案以前是英文基线字面量，M120 全搬进 `catalog/instances.rs`。那一族在装配链
+/// **第 2 位**（紧跟 nav），所以这批行是**插在中间**的，不是文件末尾追加：
+///
+/// | 动作 | 条目 |
+/// |---|---|
+/// | 改译文 | [`Key::InstancesEmptyBody`]（换成详情列真正画的那句） |
+/// | 删除 | `InstancesLastPlayed`（M117 加的整句，从未接线；页面是「标签 + 值」的元信息卡） |
+/// | 新增 | `InstancesTitle` … `InstancesStageWindow`（页头 / 动作 / 空态 / 元信息标签与值 / 隔离档位 / 运行状态 / 阶段，共 28 条） |
+///
+/// 位置跟着族走这个事实本身就是判据：金表是 `Key::ALL` 的逐 index 镜像，
+/// 「为把新 key 排到文件末尾而去重排别人的族」会让这里整片红。
+#[cfg(test)]
+mod golden;
+
+#[cfg(test)]
+mod tests;
+
+use account::account_entries;
+use agent::agent_entries;
+use content::content_entries;
+use core_text::core_text_entries;
+use download::{download_entries, version_entries};
+use font::font_entries;
+use general::general_entries;
+use instances::instances_entries;
+use launch::launch_entries;
+use loader::loader_entries;
+use logs::logs_entries;
+use nav::nav_entries;
+use settings::{
+    settings_ai_entries, settings_appearance_entries, settings_download_entries,
+    settings_general_entries, settings_java_entries,
+};
+
+// 装配顺序 = `Key` 的声明顺序。**与拆分前逐条一致**，动它等于动 `Key` 的 `Ord` 与导出表顺序，
+// 金表（`catalog/golden.rs`）会红。设置页那五个域按页面上的分组顺序排，中间三个现在是空的。
+nav_entries! {
+    instances_entries,
+    loader_entries,
+    launch_entries,
+    font_entries,
+    settings_general_entries,
+    settings_appearance_entries,
+    settings_java_entries,
+    settings_download_entries,
+    settings_ai_entries,
+    core_text_entries,
+    download_entries,
+    logs_entries,
+    agent_entries,
+    general_entries,
+    // M107：版本管理页的侧栏 / 搜索文案**追加在链尾**（金表只追加不重排，理由见
+    // `catalog/download.rs` 里 `version_entries` 的文档）。M104 的 `agent_entries` 与 M106 的
+    // `general_entries` 已经在 main 上占了链尾，所以本域排在它们**之后**：
+    // `Key::ALL` 顺序 = 金表顺序 = 先 main 的全部域，再 version。
+    version_entries,
+    // M109：内容库页。与 M107 同一条纪律——本域排在 main 已占住的链尾**之后**，
+    // 于是 `Key::ALL` 顺序 = 金表顺序 = 先 main 的全部域，再 version，最后 content。
+    content_entries,
+    // M114：账户页。同理**追加在 main 已占住的链尾之后**（先 content 再 account），
+    // 金表只追加不重排。
+    account_entries,
+    finish,
+    {}
+}
+
+/// 一套语言的目录（不可变；`Copy`，随手传值）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Catalog {
+    lang: Lang,
+    entries: &'static [(Key, &'static str)],
+}
+
+impl Catalog {
+    /// 内置目录。
+    #[must_use]
+    pub const fn of(lang: Lang) -> Catalog {
+        let entries: &'static [(Key, &'static str)] = match lang {
+            Lang::En => EN,
+            Lang::ZhCn => ZH_CN,
+        };
+        Catalog { lang, entries }
+    }
+
+    /// 用外部表构造目录（给后续 mission 的第三套语言 / 测试注入用）。
+    #[must_use]
+    pub const fn from_entries(lang: Lang, entries: &'static [(Key, &'static str)]) -> Catalog {
+        Catalog { lang, entries }
+    }
+
+    /// 这套目录是哪种语言。
+    #[must_use]
+    pub const fn lang(&self) -> Lang {
+        self.lang
+    }
+
+    /// 严格取词：缺译就是 `None`（**不回落**到别的语言）。
+    #[must_use]
+    pub fn get(&self, key: Key) -> Option<&'static str> {
+        self.entries
+            .iter()
+            .find(|(entry, _)| *entry == key)
+            .map(|(_, text)| *text)
+    }
+
+    /// 这套目录的全部条目（声明顺序）。给导出 / 校对工具与完整性守门测试用。
+    #[must_use]
+    pub const fn entries(&self) -> &'static [(Key, &'static str)] {
+        self.entries
+    }
+
+    /// 取词（UI 便利路径）：缺译返回 [`MISSING`]。
+    #[must_use]
+    pub fn text(&self, key: Key) -> &'static str {
+        self.get(key).unwrap_or(MISSING)
+    }
+
+    /// 带变量的句子：把 `{name}` 换掉。
+    ///
+    /// 参数没给全时**占位符原样留在文案里**（`Launch failed (exit {code})`），不 panic、不猜空串——
+    /// 缺参在截图上一眼可见，比静默变成 `exit ` 好查。
+    #[must_use]
+    pub fn render(&self, key: Key, args: &[(&str, &str)]) -> String {
+        let Some(template) = self.get(key) else {
+            return format!("⟪missing:{}⟫", key.name());
+        };
+
+        let mut out = template.to_owned();
+        for (name, value) in args {
+            out = out.replace(&format!("{{{name}}}"), value);
+        }
+        out
+    }
+
+    /// 缺译的 key（自带语言里从来是空；注入目录与回归守门才用得上）。
+    #[must_use]
+    pub fn missing(&self) -> Vec<Key> {
+        Key::ALL
+            .iter()
+            .copied()
+            .filter(|key| self.get(*key).is_none())
+            .collect()
+    }
+
+    /// 人话诊断（`None` = 没有缺译）。一条缺译一行，附带英文原文当参考。
+    #[must_use]
+    pub fn diagnose(&self) -> Option<String> {
+        let missing = self.missing();
+        if missing.is_empty() {
+            return None;
+        }
+
+        let mut out = format!("{} 缺 {} 条译文：", self.lang.tag(), missing.len());
+        for key in missing {
+            let reference = Catalog::of(Lang::En)
+                .get(key)
+                .map_or_else(|| "<en 也缺>".to_owned(), |text| format!("\"{text}\""));
+            out.push_str(&format!("\n  - {} · en={reference}", key.name()));
+        }
+        Some(out)
+    }
+}
+
+/// 抽取文案里的 `{name}` 占位符（守门测试用：同一 key 的两套译文占位符必须一致）。
+#[must_use]
+pub fn placeholders(text: &str) -> Vec<&str> {
+    let mut found = Vec::new();
+    let mut rest = text;
+    while let Some(open) = rest.find('{') {
+        let after = &rest[open + 1..];
+        let Some(close) = after.find('}') else {
+            break;
+        };
+        found.push(&after[..close]);
+        rest = &after[close + 1..];
+    }
+    found
+}
diff --git a/crates/i18n/src/catalog/account.rs b/crates/i18n/src/catalog/account.rs
new file mode 100644
index 0000000..a597fa8
--- /dev/null
+++ b/crates/i18n/src/catalog/account.rs
@@ -0,0 +1,113 @@
+//! 账户页文案（M114 三轨：微软正版 / 第三方皮肤站 / 本地档案）。
+//!
+//! 域文件的形状见 [`crate::catalog`] 的「域装配」一节。本域**追加在装配链末尾**，
+//! 所以金表（`catalog::golden`）里这批 key 也排在最后。
+//!
+//! ## 口径（不许改写成别的说法）
+//!
+//! 本地档案的说明必须带「仅本地/隔离网络测试用，无法连接启用正版验证的服务器」——
+//! 这是 README 已定的口径（`AccountTrackOfflineBody` / `AccountOfflineWarning` 两处都写全），
+//! 不许写成「兼容旧启动器迁移」这种暗示能进正版服的说法。
+//!
+//! 文案里**没有任何 token 字样**：账户页从不展示凭据（M114 审核红线），
+//! 「密码只用于这一次登录」这条提示是唯一提到密码的地方。
+
+macro_rules! account_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // ── 页头 / 列表
+            AccountTitle => ("Accounts", "账户"),
+            AccountSubtitle => ("Microsoft, third-party skin servers and local profiles", "微软正版、第三方皮肤站与本地档案"),
+            AccountListTitle => ("All accounts", "全部账户"),
+            AccountAddedOn => ("Added {date}", "添加于 {date}"),
+            AccountActiveChip => ("Active", "当前"),
+            AccountSwitch => ("Use for launch", "切换为启动账户"),
+            AccountRelogin => ("Sign in again", "重新登录"),
+            AccountRemove => ("Remove", "删除"),
+            AccountKindMicrosoft => ("Microsoft", "微软正版"),
+            AccountKindAuthlib => ("Third-party skin server", "第三方皮肤站"),
+            AccountKindOffline => ("Local profile", "本地档案"),
+            AccountServer => ("Server {server}", "服务器 {server}"),
+            // ── 空态
+            AccountEmptyTitle => ("No accounts yet", "还没有账户"),
+            AccountEmptyBody => ("Add a Microsoft account, a third-party skin server account, or a local profile.", "添加微软正版账户、第三方皮肤站账户，或建一个本地档案。"),
+            AccountEmptyAction => ("Add an account", "添加账户"),
+            // ── 三条轨道的入口卡
+            AccountTrackMicrosoftTitle => ("Microsoft account", "微软正版"),
+            AccountTrackMicrosoftBody => ("Sign in with a device code or in your browser. Online servers require this kind of account.", "用设备码或浏览器登录。联机服务器必须用这种账户。"),
+            AccountTrackAuthlibTitle => ("Third-party skin server", "第三方皮肤站"),
+            AccountTrackAuthlibBody => ("An authlib-injector compatible server (LittleSkin and friends) brings its own skins and capes.", "兼容 authlib-injector 的皮肤站（如 LittleSkin）自带皮肤与披风。"),
+            AccountTrackOfflineTitle => ("Local profile", "本地档案"),
+            AccountTrackOfflineBody => ("Local / isolated-network testing only — it cannot join servers that require a genuine Minecraft account.", "仅本地/隔离网络测试用，无法连接启用正版验证的服务器。"),
+            AccountTrackOpen => ("Sign in", "登录"),
+            AccountTrackCreate => ("Create profile", "创建档案"),
+            AccountDialogClose => ("Close", "关闭"),
+            // ── 本地档案表单
+            AccountOfflineNameLabel => ("Profile name", "档案名"),
+            AccountOfflineNameHint => ("3–16 letters, digits or underscore", "3–16 位字母、数字或下划线"),
+            AccountOfflineSubmit => ("Create profile", "创建档案"),
+            AccountOfflineWarning => ("Local / isolated-network testing only — it cannot join servers that require a genuine Minecraft account.", "仅本地/隔离网络测试用，无法连接启用正版验证的服务器。"),
+            // ── 微软登录面板（设备码 / 授权码）
+            AccountDeviceCodeLabel => ("Enter this code", "输入这个用户码"),
+            AccountDeviceCodeCopy => ("Copy code", "复制用户码"),
+            AccountDeviceLinkCopy => ("Copy link", "复制链接"),
+            AccountDeviceCountdown => ("{time} left", "剩 {time}"),
+            AccountDeviceExpired => ("This code has expired. Start again for a fresh one.", "这个用户码已过期，重新开始换一个新的。"),
+            AccountDeviceRetry => ("Try again", "重试"),
+            AccountDeviceCancel => ("Cancel", "取消"),
+            AccountDeviceBrowser => ("Sign in with browser", "用浏览器登录"),
+            AccountDeviceUseCode => ("Use a device code instead", "改用设备码"),
+            // ── 第三方站表单
+            AccountServerLabel => ("Server address", "服务器地址"),
+            AccountServerHint => ("API root, e.g. https://littleskin.cn/api/yggdrasil/", "API 根，例：https://littleskin.cn/api/yggdrasil/"),
+            AccountServerProbe => ("Check server", "校验服务器"),
+            AccountLoginNameLabel => ("Email or username", "邮箱或用户名"),
+            AccountPasswordLabel => ("Password", "密码"),
+            AccountPasswordHint => ("Used once for this sign-in. It is never stored.", "只在这次登录里用一次，不会保存。"),
+            AccountAuthlibSubmit => ("Sign in", "登录"),
+            AccountAuthlibIdleHint => ("The server is checked automatically when you sign in; Check server only does it up front.", "登录时会自动校验服务器；「校验服务器」只是提前跑一遍。"),
+            // ── 皮肤区
+            AccountSkinTitle => ("Skin", "皮肤"),
+            AccountSkinNone => ("No skin available", "没有可用皮肤"),
+            AccountSkinHint => ("Skins come from the account's own server; nothing is generated locally.", "皮肤来自账户自己的服务器，本地不生成任何假皮肤。"),
+            // ── 导航轨底部头像
+            AccountRailSignedOut => ("Not signed in", "未登录"),
+            AccountDeviceHint => ("Open the link in your browser and enter the code above.", "在浏览器里打开链接，输入上面的用户码。"),
+            AccountDeviceBrowserHint => ("Finish the sign-in in the browser window we just opened; the link below also works.", "在我们刚打开的浏览器窗口里完成登录；下面的链接也能手动打开。"),
+            AccountServerChecking => ("Checking the server…", "正在校验服务器…"),
+            AccountServerOk => ("Server {server} is ready", "服务器 {server} 可用"),
+            AccountLoginFailed => ("Sign-in failed", "登录失败"),
+            AccountCurrentTitle => ("Current account", "当前账户"),
+            // ── 失败原因码（M114 r2：后端只给码，文案在这里；原文只进日志）
+            AccountFailureCode => ("Code: {code}", "代码：{code}"),
+            AccountFailureDenied => ("The server refused this sign-in (access denied).", "服务器拒绝了这次登录（拒绝访问）。"),
+            AccountFailureWhitelist => ("Microsoft has not approved this launcher's app registration yet. An administrator has to accept the app, then try again.", "微软还没批准本启动器的应用注册：需要管理员同意该应用后再试。"),
+            AccountFailureUnreachable => ("Could not reach the server. Check the network connection or the address, then try again.", "连不上服务器：检查网络或地址后重试。"),
+            AccountFailureNotAuthlib => ("This address does not look like an authlib-injector server (the API root usually ends with /api/yggdrasil/).", "这个地址不像 authlib-injector 服务器（API 根通常以 /api/yggdrasil/ 结尾）。"),
+            AccountFailureBadCredentials => ("The server rejected the username or password.", "服务器不认这个用户名或密码。"),
+            AccountFailureNoProfile => ("The account has no Minecraft profile on this server yet. Create the character on the server first.", "这个账号在该服务器上还没有角色：先在皮肤站里创建角色。"),
+            AccountFailureStore => ("Could not save the account to disk.", "账户没能写到磁盘上。"),
+            AccountFailureOther => ("The sign-in failed. The full reason is in the launcher log.", "登录失败，完整原因在启动器日志里。"),
+            AccountDeviceRequesting => ("Contacting Microsoft…", "正在联系微软…"),
+            AccountLoginSucceeded => ("Signed in as {name}", "已登录 {name}"),
+            // ── 账户页横幅（添加/删除/切换的结果；页面上真实可见，不是 toast）
+            AccountNoticeAdded => ("Added {name}", "已添加 {name}"),
+            AccountNoticeRemoved => ("Removed {name}", "已删除 {name}"),
+            AccountNoticeSwitched => ("{name} will be used for the next launch", "{name} 将作为下次启动的账户"),
+            AccountNoticeOfflineNameInvalid => ("Profile names must be 3–16 letters, digits or underscores.", "档案名必须是 3–16 位字母、数字或下划线。"),
+            AccountNoticeAccountExists => ("An account with that name already exists.", "同名账户已经存在。"),
+            AccountNoticeStoreFailed => ("Could not save the account store. Check the disk and try again.", "账户库写不进去：检查磁盘后重试。"),
+            AccountNoticeNotFound => ("That account no longer exists.", "这个账户已经不在了。"),
+            AccountNoticeOther => ("The account action failed. The full reason is in the launcher log.", "账户操作失败，完整原因在启动器日志里。"),
+            AccountNoticeDismiss => ("Dismiss", "关闭"),
+            AccountNoticeTitleFailed => ("Account action failed", "账户操作失败"),
+            AccountNoticeTitleDone => ("Account updated", "账户已更新"),
+            // ── 重新登录的引导
+            AccountHintAuthlibReauth => ("Enter the password again for {server}.", "请输入 {server} 的密码。"),
+            AccountHintOfflineNoRelogin => ("Local profiles have no server account to sign in again — create a new profile instead.", "本地档案没有可重新登录的服务器账户，请新建一个档案。"),
+        } }
+    };
+}
+
+pub(crate) use account_entries;
diff --git a/crates/i18n/src/catalog/agent.rs b/crates/i18n/src/catalog/agent.rs
new file mode 100644
index 0000000..22dac43
--- /dev/null
+++ b/crates/i18n/src/catalog/agent.rs
@@ -0,0 +1,66 @@
+//! AI 助手栏 / AI 独立页的文案（M104 `AGENTRAIL`）。
+//!
+//! 这两处**共用同一套会话视图**（`crates/app-iced/src/pages/agent/`），所以文案也只在这里出现一次：
+//! 栏上的折叠/拆出、页上的收回、两处都要的发送/中断/空会话引导。
+//!
+//! 域文件的形状见 [`crate::catalog`] 的「域装配」一节：本宏把条目**追加**到 `$acc` 之后，
+//! 再把「还没装配的域」原样交给 `$next`。条目顺序 = `Key` 的声明顺序（金表 `catalog::golden` 守门）。
+//!
+//! **新增 key 时按顺序追加在最后**：金表是「拆分前那份表的逐字快照」，重排既有行会让它红。
+
+macro_rules! agent_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // ── AI 助手（右栗 + 独立页共用）
+            AgentTitle => ("Assistant", "助手"),
+            // M119 r1 复审 P2-1：这条一度被改成中性的「会话」，理由是「跑什么后端由端点标签说」——
+            // 但端点标签在壳里根本不存在，于是默认配置下用户看到的是一个像是接上了模型的助手。
+            // 现在把诚实的话写回来，而且它是**常驻**的（标题下就一行，不点也能看到）。
+            AgentSubtitle => ("Simulated assistant · no real model is connected", "模拟助手 · 还没接真实模型"),
+            AgentCollapse => ("Collapse", "收起"),
+            AgentDetach => ("Pop out", "拆出"),
+            AgentDock => ("Dock back", "收回"),
+            AgentOpen => ("Open assistant", "打开助手"),
+            AgentStripLabel => ("AI", "助手"),
+            AgentSend => ("Send", "发送"),
+            AgentStop => ("Stop", "中断"),
+            // 输入框上再说一次：用户真要动手的位置就在这儿
+            AgentPlaceholder => ("Message the simulated assistant…", "给模拟助手发消息…"),
+            AgentEmptyTitle => ("Nothing in this session yet", "这个会话还没有内容"),
+            // 空会话是最容易被误读的一屏（没有人说过话，很容易以为是「连上了但还没问」）
+            AgentEmptyBody => ("Ask about instances, downloads or logs. This assistant is simulated: no real model is connected.", "可以问实例、下载或日志。当前是模拟助手，没有接真实模型。"),
+            AgentNotePending => ("Placeholder shell: your message is kept here, nothing was sent to a model.", "占位外壳：消息留在这里，没有发给任何模型。"),
+            AgentNoteStopped => ("Stopped by you.", "你中断了这次回复。"),
+            AgentUnread => ("{count} unread", "{count} 条未读"),
+            AgentResize => ("Drag to resize the assistant rail", "拖动调整助手栏宽度"),
+            AgentWidthLabel => ("Width {width}", "宽度 {width}"),
+            AgentRoleYou => ("You", "你"),
+            AgentRoleAssistant => ("Assistant", "助手"),
+            AgentRoleNotice => ("Notice", "提示"),
+            // ── M119：失败态与写操作确认（接线后才有；`AgentRail::error` / `rail.confirm`）
+            //
+            // 为什么必须成 key：任务要求「presenter 出错时 UI 显示**具名**错误」，
+            // 而 M106 立的规矩是界面文案一律走 catalog——没有键就只能硬编码中英。
+            AgentErrorTitle => ("Assistant error", "助手出错"),
+            AgentErrorUnavailable => ("Couldn't reach the assistant backend. Check the endpoint, then try again.", "连不上助手后端：检查端点后重试。"),
+            AgentErrorNotImplemented => ("This assistant request isn't wired up yet.", "这个助手请求还没接线。"),
+            AgentConfirmRequest => ("The assistant wants to change something: {summary}", "助手想改一项设置：{summary}"),
+            AgentConfirmAllow => ("Allow", "允许"),
+            AgentConfirmDeny => ("Deny", "拒绝"),
+            // 头部常驻小标记（P2-1）：与副标题/占位符互为冗余，三个位置都能看到「这是模拟」
+            AgentSimulated => ("Simulated", "模拟"),
+            // ── M119 r2：三处文案的**真实态**配对（模拟态用上面那三条已有的 key）
+            //
+            // 复审 r2 的 P2-1：上一轮只有标题胶囊由 `simulated` 驱动，副标题/占位符/空态正文是
+            // 无条件取词，而那三条译文里写着「模拟 / 没接真实模型」——接上真 transport 之后
+            // 这三句会**反方向**地留着。现在配成对：`simulated == true` 走模拟态，
+            // `false` 走这三条中性话（`pages/agent/tests/disclaimer.rs` 钉住四处一起变）。
+            AgentSubtitleReal => ("Conversation", "会话"),
+            AgentPlaceholderReal => ("Message the assistant…", "给助手发消息…"),
+            AgentEmptyBodyReal => ("Ask about instances, downloads or logs.", "可以问实例、下载或日志。"),
+        } }
+    };
+}
+
+pub(crate) use agent_entries;
diff --git a/crates/i18n/src/catalog/content.rs b/crates/i18n/src/catalog/content.rs
new file mode 100644
index 0000000..0f492a8
--- /dev/null
+++ b/crates/i18n/src/catalog/content.rs
@@ -0,0 +1,269 @@
+//! 内容库文案（M109 `CONTENTDL`）。
+//!
+//! 一句话一个 key：带变量的句子用 `{name}`，页面只做 [`crate::Catalog::render`]，不拼片段。
+//!
+//! ## 三条口径
+//!
+//! 1. **只说能做的事**：整合包那条写的是「要等导入管线」，不是「稍后自动支持」；
+//! 2. **站名也进词表**：`Modrinth` / `CurseForge` 的**中文译文必须与英文不同**
+//!    （`catalog/tests.rs` 的 `chinese_catalog_is_actually_chinese` 会红），所以中文写成「Modrinth 源」；
+//! 3. **禁用态要能解释自己**：`ContentIncompatible*` / `ContentModpackNotReady` 就是禁用按钮旁边那几句话——
+//!    没有它们，禁用就等于「点了没反应」。
+//!
+//! 域文件的形状见 `crate::catalog` 的「域装配」一节。
+
+macro_rules! content_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // --- content library page (M109) ---
+            ContentTitle => ("Content", "内容库"),
+            ContentSubtitle => (
+                "Modpacks, mods, resource packs and shaders",
+                "整合包、Mod、资源包与光影"
+            ),
+            ContentSectionVersions => ("Version management", "版本管理"),
+            ContentSectionContent => ("Content library", "内容库"),
+            ContentKindModpack => ("Modpacks", "整合包"),
+            ContentKindMod => ("Mods", "Mod"),
+            ContentKindResourcepack => ("Resource packs", "资源包"),
+            ContentKindShader => ("Shaders", "光影"),
+            ContentSourceModrinth => ("Modrinth", "Modrinth 源"),
+            ContentSourceCurseforge => ("CurseForge", "CurseForge 源"),
+            ContentSortRelevance => ("Relevance", "相关度"),
+            ContentSortDownloads => ("Downloads", "下载量"),
+            ContentSortNewest => ("Newest", "最新发布"),
+            ContentSortUpdated => ("Recently updated", "最近更新"),
+            ContentSearchPlaceholder => ("Search content…", "搜索内容…"),
+            ContentSearch => ("Search", "搜索"),
+            ContentFilterVersion => ("Game version", "游戏版本"),
+            ContentFilterLoader => ("Loader", "加载器"),
+            ContentFilterAny => ("Any", "不限"),
+            ContentCount => ("{count} results", "{count} 个结果"),
+            ContentLoading => ("Loading content…", "正在加载内容…"),
+            ContentLoadingHint => (
+                "Results come from the network; nothing is cached offline yet.",
+                "结果来自网络，暂时没有离线缓存。"
+            ),
+            ContentEmptyTitle => ("Nothing matched", "没有匹配的内容"),
+            ContentEmptyBody => (
+                "Try another keyword, or clear a filter.",
+                "换个关键词，或清掉一个筛选条件。"
+            ),
+            ContentFailedTitle => ("Could not load content", "内容加载失败"),
+            ContentFailedBody => ("Check the network, then retry.", "检查网络后重试。"),
+            ContentRetry => ("Retry", "重试"),
+            ContentLoadMore => ("Load more", "加载更多"),
+            ContentNoMore => ("No more results", "没有更多了"),
+            ContentDetailEmpty => (
+                "Pick an item to see what it supports.",
+                "选一个项目看它支持什么。"
+            ),
+            ContentDetailDownloads => ("{count} downloads", "下载量 {count}"),
+            ContentDetailUpdated => ("Updated {date}", "更新于 {date}"),
+            ContentDetailLoaders => ("Loaders: {list}", "加载器：{list}"),
+            ContentDetailVersions => ("Game versions: {list}", "游戏版本：{list}"),
+            ContentInstall => ("Install into instance", "装入实例"),
+            ContentTargetInstance => ("Target instance", "目标实例"),
+            ContentNoInstances => ("No instance to install into", "没有可装入的实例"),
+            ContentIncompatibleVersion => (
+                "Needs {version}; this instance runs {actual}",
+                "需要 {version}，该实例运行的是 {actual}"
+            ),
+            ContentIncompatibleLoader => ("Not built for {loader}", "不支持 {loader}"),
+            ContentModpackNotReady => (
+                "Installing modpacks from the library into an instance is not available yet",
+                "从内容库一键安装整合包到实例还没做（本地的包可以直接导入）"
+            ),
+            ContentSourceUnavailable => (
+                "CurseForge needs an API key: add one in Settings",
+                "CurseForge 需要在设置里配置密钥才能搜索"
+            ),
+            ContentSourceNotWired => (
+                "Installing from CurseForge is not available yet",
+                "CurseForge 来源的安装尚未开放"
+            ),
+            // --- M113: pack import / export（PACKUI）---
+            PackTitle => ("Modpack import & export", "整合包导入 / 导出"),
+            PackImportTitle => ("Import a modpack", "导入整合包"),
+            PackDropHint => (
+                "Drop a .mrpack, .zip or a MultiMC/Prism instance folder here",
+                "把 .mrpack / .zip 或 MultiMC·Prism 实例目录拖到这里"
+            ),
+            PackDropActive => ("Release to probe the pack", "松手开始探测"),
+            PackNoDialog => (
+                "This build has no system file picker: drag the file in, or paste its path below.",
+                "本版没有系统文件选择框：请把文件拖进来，或在下面粘贴路径。"
+            ),
+            PackPathLabel => ("Pack path", "整合包路径"),
+            PackPathPlaceholder => (
+                "D:\\packs\\Better MC.mrpack",
+                "D:\\整合包\\更好的MC.mrpack"
+            ),
+            PackImportAction => ("Import", "导入"),
+            PackCancel => ("Cancel import", "取消导入"),
+            PackDismiss => ("Dismiss", "关闭"),
+            PackTargetLabel => ("Install into", "装到实例"),
+            PackTargetNew => ("New instance", "新建实例"),
+            PackInstanceName => ("Instance name", "实例名"),
+            PackStageLine => ("Step {index}/{total} · {stage}", "步骤 {index}/{total} · {stage}"),
+            PackStageProbe => ("Reading the manifest", "读取清单"),
+            PackStageExtract => ("Unpacking overrides", "解包覆盖内容"),
+            PackStageFetch => ("Fetching missing files", "补下载文件"),
+            PackStageCommit => ("Writing files", "落地写盘"),
+            PackStageRegister => ("Registering the instance", "登记实例"),
+            PackProbeTitle => (
+                "This pack is almost a known format",
+                "这个包差一点就是已知格式"
+            ),
+            PackProbeLooksLike => (
+                "Looks like {format}, but missing: {missing}",
+                "看起来像 {format}，但缺：{missing}"
+            ),
+            PackProbeUnknown => (
+                "No known format claims this pack",
+                "没有任何已知格式认领这个包"
+            ),
+            PackProbeSaw => ("Found in the pack: {saw}", "包里看到：{saw}"),
+            PackProbeNothing => ("nothing recognisable", "没有可识别的东西"),
+            PackStatusSuccess => ("Imported", "已导入"),
+            PackStatusPartial => ("Imported with gaps", "导入完成，但有缺口"),
+            PackStatusFailed => ("Import failed — rolled back", "导入失败 —— 已整包回滚"),
+            PackReportWritten => ("Files written: {count} · {bytes}", "{count} 个文件已写盘 · {bytes}"),
+            PackReportMissing => (
+                "Could not fetch (tolerated): {count}",
+                "有 {count} 个文件没搞到（可容忍）"
+            ),
+            PackReportConflicts => (
+                "Conflicts: {count}",
+                "冲突：{count} 个"
+            ),
+            PackReportRejected => (
+                "The client does not support these: {count}",
+                "这些组件客户端不支持：{count} 个"
+            ),
+            PackReportRejectedNote => ("not supported by the client", "客户端不支持"),
+            PackCancelled => (
+                "Import keeps running in the background — this result is discarded. Files already written stay.",
+                "导入会在后台继续跑完 —— 本次结果作废；已经写下的文件会留下。"
+            ),
+            PackOverwriteAction => ("Re-import, the pack wins", "以包为准重新导入"),
+            PackOverwriteNote => (
+                "Keeping both (renamed) is not supported yet: the import pipeline has one global conflict policy and no per-file decision channel.",
+                "「两者都留（改名）」暂不支持：导入管线只有一套全局冲突策略，没有逐文件决策通道。"
+            ),
+            PackMissingOffline => ("offline import", "离线导入"),
+            PackMissingNoSource => (
+                "no download source available yet",
+                "暂时拿不到下载地址"
+            ),
+            PackMissingFetchFailed => ("download failed: {detail}", "下载失败：{detail}"),
+            PackFatalTitle => (
+                "Rolled back — nothing was left behind",
+                "已回滚 —— 目标目录零残留"
+            ),
+            PackFatalHint => ("What to try next", "下一步可以试"),
+            PackConflictUserModified => ("you changed it", "你改过"),
+            PackConflictUserDeleted => ("you deleted it", "你删过"),
+            PackConflictPreExisting => ("was already there", "本来就在"),
+            PackChoiceKeepUser => ("kept yours", "保留我的"),
+            PackChoiceOverwrite => ("pack version used", "用包里的"),
+            PackConflictHashes => (
+                "pack {pack} · base {base} · disk {disk}",
+                "包内 {pack} · 基线 {base} · 磁盘 {disk}"
+            ),
+            PackConflictDetail => ("Hashes", "三方哈希"),
+            PackFormatModrinth => ("Modrinth .mrpack", "Modrinth 的 .mrpack"),
+            PackFormatCurseforge => ("CurseForge manifest", "CurseForge 清单"),
+            PackFormatMultimc => ("MultiMC / Prism instance", "MultiMC·Prism 实例"),
+            PackExportTitle => ("Export this instance", "导出这个实例"),
+            PackExportOpen => ("Export…", "导出…"),
+            PackExportFormat => ("Format", "格式"),
+            PackExportName => ("Pack name", "包名"),
+            PackExportVersion => ("Version", "版本"),
+            PackExportOutput => ("Save to", "保存到"),
+            PackExportOutputPlaceholder => (
+                "empty = suggested path",
+                "留空 = 自动给一个路径"
+            ),
+            PackExportPrecheck => ("Dry run", "预检"),
+            PackExportConfirm => ("Write the pack", "确认写盘"),
+            PackExportAbort => ("Back", "返回"),
+            PackExportMultimcNote => (
+                "MultiMC/Prism can only be imported, not exported (by design).",
+                "MultiMC·Prism 只能导入、不能导出（有意省略）。"
+            ),
+            PackExportDone => ("Wrote {path} · {bytes}", "已写出 {path} · {bytes}"),
+            PackExportFailed => ("Export failed: {reason}", "导出失败：{reason}"),
+            PackExportPending => ("Scanning the instance…", "正在扫描实例…"),
+            PackPreviewHead => (
+                "Will inline {inline} files · cannot export: {skipped}",
+                "将内联 {inline} 个文件 · 无法导出 {skipped} 项"
+            ),
+            PackPreviewRemote => (
+                "{count} files can be referenced remotely",
+                "{count} 个文件可走远程引用"
+            ),
+            PackPreviewInlineBytes => (
+                "{bytes} copied into overrides/",
+                "{bytes} 会原样拷进 overrides/"
+            ),
+            PackPreviewInlineTitle => (
+                "Copied into overrides/ (first {shown}):",
+                "原样拷进 overrides/（只列前 {shown} 个）："
+            ),
+            PackPreviewSkippedTitle => (
+                "Not in the pack: {count}",
+                "没进包：{count} 项"
+            ),
+            PackPreviewNotes => ("Known losses", "已知损失"),
+            PackPreviewTarget => ("Will be written to {path}", "将写到 {path}"),
+            PackPreviewMore => (
+                "…and {count} more files (not shown here)",
+                "…还有 {count} 个文件（这里不展开）"
+            ),
+            PackPreviewComplete => ("Nothing is left out", "没有遗漏任何文件"),
+            PackPreviewIncomplete => (
+                "Some files will not be in the pack",
+                "有文件不会进包"
+            ),
+            PackReasonModrinthSha1 => ("Modrinth match (SHA-1)", "Modrinth 命中（SHA-1）"),
+            PackReasonCurseFingerprint => (
+                "CurseForge match (fingerprint)",
+                "CurseForge 命中（文件指纹）"
+            ),
+            PackReasonNoRemoteMatch => (
+                "unknown to both catalogs, inlined",
+                "两个目录都不认识，已内联"
+            ),
+            PackReasonCurseOnly => (
+                "only CurseForge knows it, this format cannot use it, inlined",
+                "只有 CF 认识，目标格式用不上，已内联"
+            ),
+            PackReasonModrinthOnly => (
+                "only Modrinth knows it, the CF manifest cannot use it, inlined",
+                "只有 Modrinth 认识，CF 清单用不上，已内联"
+            ),
+            PackReasonMissingSha512 => (
+                "the catalogue entry has no sha512 hash, inlined",
+                "命中缺 sha512，已内联"
+            ),
+            PackReasonMissingCurseIds => (
+                "the catalogue entry has no CurseForge ids, inlined",
+                "命中缺 projectID/fileID，已内联"
+            ),
+            PackReasonDisabled => (
+                "disabled file, this format cannot express it (.disabled kept)",
+                "禁用文件，目标格式表达不了（保留 .disabled）"
+            ),
+            PackReasonSymlink => ("symbolic link, skipped", "符号链接，已跳过"),
+            PackReasonUnsafePath => (
+                "path fails the pack path rules, skipped",
+                "路径过不了包内规整，已跳过"
+            ),
+            PackReasonUnreadable => ("cannot read it, skipped", "读不出来，已跳过"),
+        } }
+    };
+}
+
+pub(crate) use content_entries;
diff --git a/crates/i18n/src/catalog/core_text.rs b/crates/i18n/src/catalog/core_text.rs
new file mode 100644
index 0000000..e7ad863
--- /dev/null
+++ b/crates/i18n/src/catalog/core_text.rs
@@ -0,0 +1,15 @@
+//! core / presenter 只给了中文串、UI 又不许画原文时的兜底文案（口径见 [`crate::bridge`]）。
+//!
+//! 域文件的形状见 [`crate::catalog`] 的「域装配」一节。
+
+macro_rules! core_text_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // ── core / presenter 只给了中文串、UI 又不许画原文时的兜底（见 `bridge`）
+            CoreTextUntranslated => ("[system text not translated]", "［未翻译的系统文案］"),
+        } }
+    };
+}
+
+pub(crate) use core_text_entries;
diff --git a/crates/i18n/src/catalog/download.rs b/crates/i18n/src/catalog/download.rs
new file mode 100644
index 0000000..b6614e4
--- /dev/null
+++ b/crates/i18n/src/catalog/download.rs
@@ -0,0 +1,150 @@
+//! 版本管理页文案（M94 建页时叫「下载页」，M108 起显示名改成「版本管理」）。
+//!
+//! 一句话一个 key：带变量的句子用 `{name}`，页面只做 [`crate::Catalog::render`]，不拼片段
+//! （[`crate::bridge`] 的规矩 1）。
+//!
+//! 文案口径（M94 r1 / P2-2）：**只说这个页面真能做到的动作**（切分类、刷新、看日志），
+//! 不写「稍后会自动重试」这类 UI 没有的能力，也不拿文案去补功能。
+//!
+//! **「下载」字样不许再指向这一页**（M108 用户令）：这一页管的是「版本与加载器」，用户点它
+//! 不是为了下载点什么。唯一的例外是 [`Key::DownloadStageDownloading`]——那是安装流程里**真在
+//! 传文件**的那一步，说的不是页面身份而是当时的动作，留着才对（守门见 `pages/tests.rs` 的
+//! `the_download_route_is_presented_as_version_management`，它把本域每条 key 的两种语言都扫一遍）。
+//!
+//! 域文件的形状见 [`crate::catalog`] 的「域装配」一节。
+
+macro_rules! download_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // --- version management page (M94; renamed in M108) ---
+            DownloadTitle => ("Version management", "版本管理"),
+            // 例外说明（M108 复审 p3）：副标题承诺「安装、升级、修复」，但页面目前只有
+            // 「选版本 → 安装」一条路，「修复」与「加载器选择」都还没有入口
+            // （`InstallView::of` 连 `InstallProgressView.loader` 都没读）。
+            // 这是用户令（2026-11-04）定的口径，能力由 M105 / M113 补齐；
+            // 补齐之前不许拿这句话当已实现功能宣传。
+            DownloadSubtitle => (
+                "Manage versions and loaders: install, upgrade, repair",
+                "管理版本与加载器：安装、升级、修复"
+            ),
+            DownloadRefresh => ("Refresh", "刷新"),
+            DownloadInstall => ("Install", "安装"),
+            DownloadCancel => ("Cancel install", "取消安装"),
+            DownloadInstalled => ("Installed", "已安装"),
+            DownloadCount => ("{count} versions", "{count} 个版本"),
+            DownloadRowSupporting => ("{kind} · released {date}", "{kind} · 发布于 {date}"),
+            DownloadSelectHint => ("Pick a version, then install", "选一个版本再安装"),
+            DownloadLoading => ("Loading versions…", "正在加载版本列表…"),
+            DownloadLoadingHint => (
+                "If this stays here, press Refresh in the top right.",
+                "如果一直停在这里，点右上角的刷新。"
+            ),
+            DownloadEmptyTitle => ("No versions to show", "没有可显示的版本"),
+            DownloadEmptyBody => (
+                "Pick another category, or refresh the list.",
+                "换一个分类，或刷新一次列表。"
+            ),
+            DownloadCategoryAll => ("All", "全部"),
+            DownloadCategoryRelease => ("Release", "正式版"),
+            DownloadCategorySnapshot => ("Snapshot", "预览版"),
+            DownloadCategoryAncient => ("Ancient", "远古版"),
+            DownloadStagePlanning => ("Planning", "解析版本"),
+            DownloadStageDownloading => ("Downloading files", "下载文件"),
+            DownloadStageInstalling => ("Building the version", "生成版本"),
+            DownloadStageRegistering => ("Registering the instance", "登记实例"),
+            DownloadStageDone => ("Done", "已完成"),
+            DownloadStageFailed => ("Install failed", "安装失败"),
+            DownloadStageCancelled => ("Install cancelled", "安装已取消"),
+            DownloadProgress => (
+                "{done}/{total} files",
+                "{done}/{total} 文件"
+            ),
+            DownloadProgressUnknown => ("Waiting for the first file…", "等第一个文件…"),
+            // 速率与剩余时间是两个独立短语，各占一个 key（`DownloadRate` 只负责把它们排成一行）
+            DownloadRate => ("{speed} · {eta}", "{speed}，{eta}"),
+            DownloadEtaSecs => ("{secs}s left", "剩 {secs}s"),
+            DownloadEtaMins => ("{mins}m{secs}s left", "剩 {mins}m{secs}s"),
+            DownloadFailedHint => (
+                "The Logs page has the full reason.",
+                "完整原因在日志页。"
+            ),
+            DownloadOpenLogs => ("Open logs", "打开日志"),
+            DownloadDismiss => ("Dismiss", "关闭"),
+            // --- 安装选项（M105）---
+            DownloadOptionsTitle => ("Install options", "安装选项"),
+            DownloadOptionsLoaderVersion => ("Loader version", "加载器版本"),
+            DownloadOptionsLoaderVersionsLoading => (
+                "Fetching loader versions…",
+                "正在获取加载器版本…"
+            ),
+            DownloadOptionsLoaderVersionsFailed => (
+                "Could not fetch loader versions: {reason}",
+                "取不到加载器版本：{reason}"
+            ),
+            DownloadOptionsLoaderVersionsEmpty => (
+                "No loader builds published for {version}",
+                "官方没有为 {version} 发布加载器版本"
+            ),
+            DownloadOptionsInstanceName => ("Instance name", "实例名"),
+            DownloadOptionsInstanceNameHint => (
+                "Empty = use the version id",
+                "留空就用版本号"
+            ),
+            DownloadOptionsIncompatible => (
+                "{loader} has no builds for {version}",
+                "{loader} 没有适配 {version} 的构建"
+            ),
+            DownloadOptionsNeedsAtLeast => (
+                "{loader} needs Minecraft {min} or newer",
+                "{loader} 需要 Minecraft {min} 或更新"
+            ),
+            DownloadCancelled => (
+                "Install cancelled — finished files are kept, the instance was not created",
+                "安装已取消 —— 已下好的文件保留，实例未登记"
+            ),
+        } }
+    };
+}
+
+pub(crate) use download_entries;
+
+/// **M107 版本管理页**的侧栏 / 搜索文案。
+///
+/// 为什么单独一个宏、并**接在装配链最后**：`catalog/golden.rs` 是「`Key` 声明顺序 × 译文」的逐字节
+/// 快照，M107 的纪律是**只追加不重排**。把新 key 插在 `download_entries` 中间会让 `Key::ALL`
+/// 的顺序在 `DownloadDismiss` 与 `LogsSubtitleIdle` 之间断开，金表就得整体重排（那正是要避免的
+/// 风险）。追加在链尾 ⇒ 新 key 落在 `Key::ALL` 末尾 ⇒ 金表末尾追加同样几行即可。
+macro_rules! version_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // --- version management page (M107) ---
+            VersionRailTitle => ("Version type", "版本类型"),
+            VersionMajorTitle => ("Major version", "主版本"),
+            VersionMajorAll => ("All versions", "全部版本"),
+            VersionSearchPlaceholder => ("Search version numbers", "搜版本号"),
+            VersionSearchClear => ("Clear search", "清空搜索"),
+            VersionSearchHits => ("{count} matches", "{count} 个匹配"),
+            VersionSearchEmptyTitle => ("No matching versions", "没有匹配的版本"),
+            VersionSearchEmptyBody => (
+                "Try a shorter piece of the number — 1.21, 24w, a1.",
+                "试试更短的片段 — 1.21、24w、a1。"
+            ),
+            VersionSearchElsewhere => (
+                "{count} versions match, but they are in another type.",
+                "有 {count} 个版本匹配，但它们在别的类型里。"
+            ),
+            VersionSearchElsewhereAction => ("Show all types", "看全部类型"),
+            // --- M107 r2：复数口径与「在别处」的标题（追加在域尾 ⇒ `Key::ALL` 顺序只增不动） ---
+            VersionSearchHitsOne => ("1 match", "1 个匹配"),
+            VersionSearchElsewhereTitle => ("Found in another type", "在别的类型里找到了"),
+            VersionSearchElsewhereOne => (
+                "1 version matches, but it is in another type.",
+                "有 1 个版本匹配，但它在别的类型里。"
+            ),
+        } }
+    };
+}
+
+pub(crate) use version_entries;
diff --git a/crates/i18n/src/catalog/font.rs b/crates/i18n/src/catalog/font.rs
new file mode 100644
index 0000000..4fc8f70
--- /dev/null
+++ b/crates/i18n/src/catalog/font.rs
@@ -0,0 +1,24 @@
+//! 中文字体文案（D28）：中文环境缺字体时的下载提示 / 失败回退。
+//!
+//! 域文件的形状见 [`crate::catalog`] 的「域装配」一节。
+
+macro_rules! font_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // ── 中文字体（D28：中文环境缺字体时的下载提示 / 失败回退）
+            FontCjkNeedsDownload => (
+                "No Chinese font found on this system. Download an open-source (OFL) Chinese font?",
+                "系统里没找到中文字体。要下载一套开源（OFL）中文字体吗？"
+            ),
+            FontCjkDownloading => ("Downloading Chinese font… {percent}%", "正在下载中文字体… {percent}%"),
+            FontCjkDownloadFailed => (
+                "Chinese font download failed; the interface stays in English.",
+                "中文字体下载失败，界面暂时保持英文。"
+            ),
+            FontCjkReady => ("Chinese font ready: {family}", "中文字体已就绪：{family}"),
+        } }
+    };
+}
+
+pub(crate) use font_entries;
diff --git a/crates/i18n/src/catalog/general.rs b/crates/i18n/src/catalog/general.rs
new file mode 100644
index 0000000..8724c3a
--- /dev/null
+++ b/crates/i18n/src/catalog/general.rs
@@ -0,0 +1,60 @@
+//! 设置页 General 分组**真控件**的文案（M106 `I18NFOLLOW`）：语言选择器 + 其余三行。
+//!
+//! ## 与 `catalog/settings/general.rs` 的分工
+//!
+//! `catalog/settings/general.rs`（M99 建的）只有两条**标题**（[`SettingsLanguage`] /
+//! [`SettingsLanguageHint`]），是设置页五域装配的一部分；本文件是 M106 接真控件时新增的
+//! **选择器文案**：三档选项名、选中后的「界面当前使用」回显，以及 General 分组里另外三行
+//! （主题 / 启动页 / 关闭按钮）。
+//!
+//! 为什么要分两个文件：`catalog.rs` 的装配链是**追加**式的，新域挂在链尾就不会动到既有
+//! `Key` 的顺序（= `catalog/golden.rs` 那张逐字节金表）。两个文件同属 General 分组，读代码时
+//! 按「标题 vs 选项」区分即可；真要合并也是一个文件搬十行的活，不急着在接线的 mission 里做。
+//!
+//! ## 选项名为什么不是「语言自称」
+//!
+//! 常见做法是三档都写 `简体中文` / `English` 这样的自称。这里没有：`catalog/tests.rs` 有一条
+//! `chinese_catalog_is_actually_chinese`（英文表与中文表逐 key 必须不同），自称会让「中文表里
+//! 写着 English」被判成漏译。所以选项名**跟着界面语言走**：中文界面「跟随系统 / 简体中文 / 英文」，
+//! 英文界面 "Follow system / Chinese (Simplified) / English"——这也是多数启动器的做法。
+//!
+//! 域文件的形状见 [`crate::catalog`] 的「域装配」一节。
+
+macro_rules! general_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // ── General 分组（语言选择器 + 其余三行）
+            SettingsLanguageFollowSystem => ("Follow system", "跟随系统"),
+            SettingsLanguageZhCn => ("Chinese (Simplified)", "简体中文"),
+            SettingsLanguageEn => ("English", "英文"),
+            SettingsLanguageEffective => ("Interface right now: {language}", "界面当前使用：{language}"),
+            SettingsTheme => ("Theme", "主题"),
+            SettingsThemeFollowSystem => ("Follow system", "跟随系统"),
+            SettingsStartupPage => ("Startup page", "启动页"),
+            SettingsStartupInstances => ("Instances", "实例"),
+            SettingsCloseButton => ("Close button", "关闭按钮"),
+            SettingsCloseToTray => ("Exit to tray", "退出到托盘"),
+            // 设置页页头（M106）：标题复用 `NavSettings`，这三条是副标题与两个动作。
+            SettingsSubtitle => ("Launcher behaviour, Java runtimes and download sources", "启动器行为、Java 运行时与下载源"),
+            SettingsResetSection => ("Reset section", "重置本组"),
+            SettingsSave => ("Save", "保存"),
+            // 第五条导航项（M106 给导航轨补的最后一条）。放在本域而不是 `catalog/nav.rs`：
+            // 金表按**位置**逐字节比，插进 nav 域会把既有 4 条导航行整体平移一位。
+            NavAi => ("Assistant", "助手"),
+            // 设置页左列的分组名（M106）。`Group.name` 是**id**（测试按它认组），显示名走这里。
+            SettingsGroupGeneral => ("General", "通用"),
+            SettingsGroupAppearance => ("Appearance", "外观"),
+            SettingsGroupJava => ("Java", "Java 运行时"),
+            SettingsGroupDownloads => ("Downloads", "下载"),
+            // 逐实例覆盖的空态（M106）
+            SettingsOverridesEmptyTitle => ("No per-instance overrides", "没有逐实例覆盖"),
+            SettingsOverridesEmptyBody => ("Overrides let one instance keep its own Java runtime, memory or JVM flags while the rest of the launcher keeps the defaults above.", "逐实例覆盖让某个实例保留自己的 Java 运行时、内存或 JVM 参数，其余实例沿用上面的默认值。"),
+            SettingsOverridesAdd => ("Add override", "新增覆盖"),
+            // `Route::Agent` 的回退卡正文（M106：`app/view.rs` 里最后一条硬编码英文）
+            AgentFallbackBody => ("The assistant page is not built yet. Chat lives in the docked panel once the AI mission lands; this screen is the M68 skeleton fallback.", "助手页还没做。AI 接线落地后对话会出现在右侧停靠面板；这一屏是 M68 的骨架回退。"),
+        } }
+    };
+}
+
+pub(super) use general_entries;
diff --git a/crates/i18n/src/catalog/golden.rs b/crates/i18n/src/catalog/golden.rs
new file mode 100644
index 0000000..9b24afb
--- /dev/null
+++ b/crates/i18n/src/catalog/golden.rs
@@ -0,0 +1,399 @@
+//! 金表的**表数据**（`Key::ALL` 顺序 × (en, zh-CN) 的逐字快照）。「为什么有这张表、它抓得住
+//! 什么」全在 `catalog.rs` 的 `mod golden;` 文档里——本文件只放数据，是因为每加一条 key 就多一行。
+
+/// 拆分前 `Key::ALL` 的顺序 × (en, zh-CN)。第一列是变体名（`Key::name()` 的返回值）。
+pub(super) const GOLDEN: &[(&str, &str, &str)] = &[
+    ("NavInstances", "Instances", "实例"),
+    ("NavDownload", "Versions", "版本管理"),
+    ("NavDownloadExpanded", "Version management", "版本管理"),
+    ("NavLogs", "Logs", "日志"),
+    ("NavSettings", "Settings", "设置"),
+    ("InstancesNew", "New instance", "新建实例"),
+    ("InstancesImport", "Import", "导入"),
+    ("InstancesBack", "Back to instances", "返回实例列表"),
+    ("InstancesPlay", "Play", "启动"),
+    ("InstancesEmptyTitle", "No instance selected", "未选择实例"),
+    ("InstancesEmptyBody", "Pick an instance on the left to see its version, loader and launch options.", "在左侧选择一个实例，查看它的版本、加载器与启动选项。"),
+    ("InstancesTitle", "Instances", "实例"),
+    ("InstancesSubtitle", "Local versions and their mod loaders", "本地版本与它们的模组加载器"),
+    ("InstancesAllTitle", "ALL INSTANCES", "全部实例"),
+    ("InstancesStop", "Stop", "停止"),
+    ("InstancesDuplicate", "Duplicate", "复制"),
+    ("InstancesOpenFolder", "Open folder", "打开文件夹"),
+    ("InstancesDelete", "Delete", "删除"),
+    ("InstancesNarrowNote", "Below 840 px the list and the detail share one column, so opening an instance replaces this screen (full-page switch). Widen the window to see both panes again.", "窗口窄于 840 像素时，列表与详情共用一列：打开一个实例会整页替换这一屏（整页切换）。把窗口拉宽就能重新同时看见两栏。"),
+    ("InstancesMetaVersion", "VERSION", "版本"),
+    ("InstancesMetaLoader", "LOADER", "加载器"),
+    ("InstancesMetaMemory", "MEMORY", "内存"),
+    ("InstancesMetaJava", "JAVA", "Java"),
+    ("InstancesMetaMods", "MODS", "模组"),
+    ("InstancesMetaIsolation", "ISOLATION", "隔离方式"),
+    ("InstancesMetaVersionId", "VERSION ID", "版本标识"),
+    ("InstancesMetaFiles", "FILES", "文件"),
+    ("InstancesMetaLastPlayed", "LAST PLAYED", "上次游玩"),
+    ("InstancesPresentOnDisk", "Present on disk", "已在磁盘上"),
+    ("InstancesMissing", "Missing", "缺失"),
+    ("InstancesNeverPlayed", "Never", "从未游玩"),
+    ("InstancesIsolationIsolated", "Isolated", "独立目录"),
+    ("InstancesIsolationShared", "Shared", "共用目录"),
+    ("InstancesRunning", "Running · pid {pid}", "运行中 · pid {pid}"),
+    ("InstancesFailed", "Launch failed · {reason}", "启动失败 · {reason}"),
+    ("InstancesStageDownload", "Downloading", "下载中"),
+    ("InstancesStageVerify", "Verifying", "校验中"),
+    ("InstancesStageLaunch", "Starting", "启动中"),
+    ("InstancesStageWindow", "Waiting for window", "等待游戏窗口"),
+    ("LoaderVanilla", "Vanilla", "原版"),
+    ("LaunchOutcomeNormal", "Finished normally", "正常结束"),
+    ("LaunchOutcomeCrash", "The game crashed", "游戏崩溃"),
+    ("LaunchOutcomeSilent", "Suspected silent failure: exit code 0, but the game never really started", "疑似静默失败：退出码 0，但游戏没真正跑起来"),
+    ("LaunchFailedWithCode", "Launch failed (exit {code}): {reason}", "启动失败（退出码 {code}）：{reason}"),
+    ("LaunchMsaNotConfigured", "Microsoft sign-in is not configured: it needs an Azure public client id (the login flow itself is implemented). Build with ULL_MSA_CLIENT_ID=<id>, or set that environment variable before launching.", "微软登录未配置：缺少 Azure 公共客户端 id（登录功能已实现，只差这一项配置）。构建时注入：ULL_MSA_CLIENT_ID=<id> cargo build；或启动前设置同名环境变量 ULL_MSA_CLIENT_ID=<id>。"),
+    ("FontCjkNeedsDownload", "No Chinese font found on this system. Download an open-source (OFL) Chinese font?", "系统里没找到中文字体。要下载一套开源（OFL）中文字体吗？"),
+    ("FontCjkDownloading", "Downloading Chinese font… {percent}%", "正在下载中文字体… {percent}%"),
+    ("FontCjkDownloadFailed", "Chinese font download failed; the interface stays in English.", "中文字体下载失败，界面暂时保持英文。"),
+    ("FontCjkReady", "Chinese font ready: {family}", "中文字体已就绪：{family}"),
+    ("SettingsLanguage", "Language", "界面语言"),
+    ("SettingsLanguageHint", "Switches the interface language. Chinese text needs a Chinese font.", "切换界面语言。显示中文需要中文字体。"),
+    ("SettingsAppearanceCorner", "Window corners", "窗口圆角"),
+    ("SettingsAppearanceCornerSystem", "Follow system", "跟随系统"),
+    ("SettingsAppearanceCornerSquare", "Square", "直角"),
+    ("SettingsAppearanceCornerHint", "On Windows 11 and Server 2025 we ask the system for rounded corners; Windows 10 keeps square corners. On macOS and Linux the desktop's own rules apply. We never draw corners ourselves.", "Windows 11 与 Windows Server 2025 上我们请求系统处理外框圆角；Windows 10 保持直角；macOS 与 Linux 交给桌面合成器自己的规则；我们不自己画圆角。"),
+    ("SettingsAppearanceCornerSuspended", "Not in effect right now: window transparency is below 100%. Setting it back to 100% restores the rounded corners.", "当前因整窗透明度不生效：把整窗透明度调回 100% 圆角即恢复。"),
+    ("CoreTextUntranslated", "[system text not translated]", "［未翻译的系统文案］"),
+    ("DownloadTitle", "Version management", "版本管理"),
+    ("DownloadSubtitle", "Manage versions and loaders: install, upgrade, repair", "管理版本与加载器：安装、升级、修复"),
+    ("DownloadRefresh", "Refresh", "刷新"),
+    ("DownloadInstall", "Install", "安装"),
+    ("DownloadCancel", "Cancel install", "取消安装"),
+    ("DownloadInstalled", "Installed", "已安装"),
+    ("DownloadCount", "{count} versions", "{count} 个版本"),
+    ("DownloadRowSupporting", "{kind} · released {date}", "{kind} · 发布于 {date}"),
+    ("DownloadSelectHint", "Pick a version, then install", "选一个版本再安装"),
+    ("DownloadLoading", "Loading versions…", "正在加载版本列表…"),
+    ("DownloadLoadingHint", "If this stays here, press Refresh in the top right.", "如果一直停在这里，点右上角的刷新。"),
+    ("DownloadEmptyTitle", "No versions to show", "没有可显示的版本"),
+    ("DownloadEmptyBody", "Pick another category, or refresh the list.", "换一个分类，或刷新一次列表。"),
+    ("DownloadCategoryAll", "All", "全部"),
+    ("DownloadCategoryRelease", "Release", "正式版"),
+    ("DownloadCategorySnapshot", "Snapshot", "预览版"),
+    ("DownloadCategoryAncient", "Ancient", "远古版"),
+    ("DownloadStagePlanning", "Planning", "解析版本"),
+    ("DownloadStageDownloading", "Downloading files", "下载文件"),
+    ("DownloadStageInstalling", "Building the version", "生成版本"),
+    ("DownloadStageRegistering", "Registering the instance", "登记实例"),
+    ("DownloadStageDone", "Done", "已完成"),
+    ("DownloadStageFailed", "Install failed", "安装失败"),
+    ("DownloadStageCancelled", "Install cancelled", "安装已取消"),
+    ("DownloadProgress", "{done}/{total} files", "{done}/{total} 文件"),
+    ("DownloadProgressUnknown", "Waiting for the first file…", "等第一个文件…"),
+    ("DownloadRate", "{speed} · {eta}", "{speed}，{eta}"),
+    ("DownloadEtaSecs", "{secs}s left", "剩 {secs}s"),
+    ("DownloadEtaMins", "{mins}m{secs}s left", "剩 {mins}m{secs}s"),
+    ("DownloadFailedHint", "The Logs page has the full reason.", "完整原因在日志页。"),
+    ("DownloadOpenLogs", "Open logs", "打开日志"),
+    ("DownloadDismiss", "Dismiss", "关闭"),
+    ("DownloadOptionsTitle", "Install options", "安装选项"),
+    ("DownloadOptionsLoaderVersion", "Loader version", "加载器版本"),
+    ("DownloadOptionsLoaderVersionsLoading", "Fetching loader versions…", "正在获取加载器版本…"),
+    ("DownloadOptionsLoaderVersionsFailed", "Could not fetch loader versions: {reason}", "取不到加载器版本：{reason}"),
+    ("DownloadOptionsLoaderVersionsEmpty", "No loader builds published for {version}", "官方没有为 {version} 发布加载器版本"),
+    ("DownloadOptionsInstanceName", "Instance name", "实例名"),
+    ("DownloadOptionsInstanceNameHint", "Empty = use the version id", "留空就用版本号"),
+    ("DownloadOptionsIncompatible", "{loader} has no builds for {version}", "{loader} 没有适配 {version} 的构建"),
+    ("DownloadOptionsNeedsAtLeast", "{loader} needs Minecraft {min} or newer", "{loader} 需要 Minecraft {min} 或更新"),
+    ("DownloadCancelled", "Install cancelled — finished files are kept, the instance was not created", "安装已取消 —— 已下好的文件保留，实例未登记"),
+    ("LogsSubtitleIdle", "Nothing is running right now", "当前没有运行中的实例"),
+    ("LogsStatus", "{instance} · {when} · {outcome}", "{instance}｜{when}｜{outcome}"),
+    ("LogsOpenFolder", "Open folder", "打开目录"),
+    ("LogsClear", "Clear", "清空"),
+    ("LogsOutputTitle", "OUTPUT", "输出"),
+    ("LogsDiagnosisTitle", "DIAGNOSIS", "诊断"),
+    ("LogsConfidenceHigh", "HIGH CONFIDENCE", "高置信度"),
+    ("LogsConfidenceMedium", "MEDIUM CONFIDENCE", "中置信度"),
+    ("LogsConfidenceLow", "LOW CONFIDENCE", "低置信度"),
+    ("LogsSubtitleLive", "Running now — logs stream as they arrive", "正在运行 — 日志实时滚动"),
+    ("LogsConfidence", "Confidence {percent}%", "置信度 {percent}%"),
+    ("LogsSuggestedFix", "Suggested fix", "建议动作"),
+    ("LogsSummaryLabel", "One-line summary", "一行摘要"),
+    ("LogsCopySummary", "Copy summary", "复制摘要"),
+    ("LogsEmptyTitle", "No output yet", "还没有输出"),
+    ("LogsEmptyBody", "Logs stream here while the launcher or the game is running. Pick an instance and start it to see the first lines.", "启动器或游戏运行时，日志会实时出现在这里。选择一个实例并启动，就能看到第一批日志。"),
+    ("LogsEmptyAction", "Choose an instance", "选择实例"),
+    ("AgentTitle", "Assistant", "助手"),
+    ("AgentSubtitle", "Simulated assistant · no real model is connected", "模拟助手 · 还没接真实模型"),
+    ("AgentCollapse", "Collapse", "收起"),
+    ("AgentDetach", "Pop out", "拆出"),
+    ("AgentDock", "Dock back", "收回"),
+    ("AgentOpen", "Open assistant", "打开助手"),
+    ("AgentStripLabel", "AI", "助手"),
+    ("AgentSend", "Send", "发送"),
+    ("AgentStop", "Stop", "中断"),
+    ("AgentPlaceholder", "Message the simulated assistant…", "给模拟助手发消息…"),
+    ("AgentEmptyTitle", "Nothing in this session yet", "这个会话还没有内容"),
+    ("AgentEmptyBody", "Ask about instances, downloads or logs. This assistant is simulated: no real model is connected.", "可以问实例、下载或日志。当前是模拟助手，没有接真实模型。"),
+    ("AgentNotePending", "Placeholder shell: your message is kept here, nothing was sent to a model.", "占位外壳：消息留在这里，没有发给任何模型。"),
+    ("AgentNoteStopped", "Stopped by you.", "你中断了这次回复。"),
+    ("AgentUnread", "{count} unread", "{count} 条未读"),
+    ("AgentResize", "Drag to resize the assistant rail", "拖动调整助手栏宽度"),
+    ("AgentWidthLabel", "Width {width}", "宽度 {width}"),
+    ("AgentRoleYou", "You", "你"),
+    ("AgentRoleAssistant", "Assistant", "助手"),
+    ("AgentRoleNotice", "Notice", "提示"),
+    ("AgentErrorTitle", "Assistant error", "助手出错"),
+    ("AgentErrorUnavailable", "Couldn't reach the assistant backend. Check the endpoint, then try again.", "连不上助手后端：检查端点后重试。"),
+    ("AgentErrorNotImplemented", "This assistant request isn't wired up yet.", "这个助手请求还没接线。"),
+    ("AgentConfirmRequest", "The assistant wants to change something: {summary}", "助手想改一项设置：{summary}"),
+    ("AgentConfirmAllow", "Allow", "允许"),
+    ("AgentConfirmDeny", "Deny", "拒绝"),
+    ("AgentSimulated", "Simulated", "模拟"),
+    ("AgentSubtitleReal", "Conversation", "会话"),
+    ("AgentPlaceholderReal", "Message the assistant…", "给助手发消息…"),
+    ("AgentEmptyBodyReal", "Ask about instances, downloads or logs.", "可以问实例、下载或日志。"),
+    // ── M106 `I18NFOLLOW`：General 分组真控件（语言选择器 + 其余三行）。**只追加在链尾**，
+    //    上一行到 `LogsEmptyAction` 的既有顺序一字未动（金表要证明的正是这件事）。
+    ("SettingsLanguageFollowSystem", "Follow system", "跟随系统"),
+    ("SettingsLanguageZhCn", "Chinese (Simplified)", "简体中文"),
+    ("SettingsLanguageEn", "English", "英文"),
+    ("SettingsLanguageEffective", "Interface right now: {language}", "界面当前使用：{language}"),
+    ("SettingsTheme", "Theme", "主题"),
+    ("SettingsThemeFollowSystem", "Follow system", "跟随系统"),
+    ("SettingsStartupPage", "Startup page", "启动页"),
+    ("SettingsStartupInstances", "Instances", "实例"),
+    ("SettingsCloseButton", "Close button", "关闭按钮"),
+    ("SettingsCloseToTray", "Exit to tray", "退出到托盘"),
+    ("SettingsSubtitle", "Launcher behaviour, Java runtimes and download sources", "启动器行为、Java 运行时与下载源"),
+    ("SettingsResetSection", "Reset section", "重置本组"),
+    ("SettingsSave", "Save", "保存"),
+    ("NavAi", "Assistant", "助手"),
+    ("SettingsGroupGeneral", "General", "通用"),
+    ("SettingsGroupAppearance", "Appearance", "外观"),
+    ("SettingsGroupJava", "Java", "Java 运行时"),
+    ("SettingsGroupDownloads", "Downloads", "下载"),
+    ("SettingsOverridesEmptyTitle", "No per-instance overrides", "没有逐实例覆盖"),
+    ("SettingsOverridesEmptyBody", "Overrides let one instance keep its own Java runtime, memory or JVM flags while the rest of the launcher keeps the defaults above.", "逐实例覆盖让某个实例保留自己的 Java 运行时、内存或 JVM 参数，其余实例沿用上面的默认值。"),
+    ("SettingsOverridesAdd", "Add override", "新增覆盖"),
+    ("AgentFallbackBody", "The assistant page is not built yet. Chat lives in the docked panel once the AI mission lands; this screen is the M68 skeleton fallback.", "助手页还没做。AI 接线落地后对话会出现在右侧停靠面板；这一屏是 M68 的骨架回退。"),
+    // --- M107 版本管理页（追加在链尾：`Key::ALL` 顺序 = 金表顺序） ---
+    ("VersionRailTitle", "Version type", "版本类型"),
+    ("VersionMajorTitle", "Major version", "主版本"),
+    ("VersionMajorAll", "All versions", "全部版本"),
+    ("VersionSearchPlaceholder", "Search version numbers", "搜版本号"),
+    ("VersionSearchClear", "Clear search", "清空搜索"),
+    ("VersionSearchHits", "{count} matches", "{count} 个匹配"),
+    ("VersionSearchEmptyTitle", "No matching versions", "没有匹配的版本"),
+    ("VersionSearchEmptyBody", "Try a shorter piece of the number — 1.21, 24w, a1.", "试试更短的片段 — 1.21、24w、a1。"),
+    ("VersionSearchElsewhere", "{count} versions match, but they are in another type.", "有 {count} 个版本匹配，但它们在别的类型里。"),
+    ("VersionSearchElsewhereAction", "Show all types", "看全部类型"),
+    // --- M107 r2（追加在末尾：`Key::ALL` 顺序 = 金表顺序） ---
+    ("VersionSearchHitsOne", "1 match", "1 个匹配"),
+    ("VersionSearchElsewhereTitle", "Found in another type", "在别的类型里找到了"),
+    ("VersionSearchElsewhereOne", "1 version matches, but it is in another type.", "有 1 个版本匹配，但它在别的类型里。"),
+    // --- M109 内容库页（同样追加在链尾：`Key::ALL` 顺序 = 金表顺序） ---
+    ("ContentTitle", "Content", "内容库"),
+    ("ContentSubtitle", "Modpacks, mods, resource packs and shaders", "整合包、Mod、资源包与光影"),
+    ("ContentSectionVersions", "Version management", "版本管理"),
+    ("ContentSectionContent", "Content library", "内容库"),
+    ("ContentKindModpack", "Modpacks", "整合包"),
+    ("ContentKindMod", "Mods", "Mod"),
+    ("ContentKindResourcepack", "Resource packs", "资源包"),
+    ("ContentKindShader", "Shaders", "光影"),
+    ("ContentSourceModrinth", "Modrinth", "Modrinth 源"),
+    ("ContentSourceCurseforge", "CurseForge", "CurseForge 源"),
+    ("ContentSortRelevance", "Relevance", "相关度"),
+    ("ContentSortDownloads", "Downloads", "下载量"),
+    ("ContentSortNewest", "Newest", "最新发布"),
+    ("ContentSortUpdated", "Recently updated", "最近更新"),
+    ("ContentSearchPlaceholder", "Search content…", "搜索内容…"),
+    ("ContentSearch", "Search", "搜索"),
+    ("ContentFilterVersion", "Game version", "游戏版本"),
+    ("ContentFilterLoader", "Loader", "加载器"),
+    ("ContentFilterAny", "Any", "不限"),
+    ("ContentCount", "{count} results", "{count} 个结果"),
+    ("ContentLoading", "Loading content…", "正在加载内容…"),
+    ("ContentLoadingHint", "Results come from the network; nothing is cached offline yet.", "结果来自网络，暂时没有离线缓存。"),
+    ("ContentEmptyTitle", "Nothing matched", "没有匹配的内容"),
+    ("ContentEmptyBody", "Try another keyword, or clear a filter.", "换个关键词，或清掉一个筛选条件。"),
+    ("ContentFailedTitle", "Could not load content", "内容加载失败"),
+    ("ContentFailedBody", "Check the network, then retry.", "检查网络后重试。"),
+    ("ContentRetry", "Retry", "重试"),
+    ("ContentLoadMore", "Load more", "加载更多"),
+    ("ContentNoMore", "No more results", "没有更多了"),
+    ("ContentDetailEmpty", "Pick an item to see what it supports.", "选一个项目看它支持什么。"),
+    ("ContentDetailDownloads", "{count} downloads", "下载量 {count}"),
+    ("ContentDetailUpdated", "Updated {date}", "更新于 {date}"),
+    ("ContentDetailLoaders", "Loaders: {list}", "加载器：{list}"),
+    ("ContentDetailVersions", "Game versions: {list}", "游戏版本：{list}"),
+    ("ContentInstall", "Install into instance", "装入实例"),
+    ("ContentTargetInstance", "Target instance", "目标实例"),
+    ("ContentNoInstances", "No instance to install into", "没有可装入的实例"),
+    ("ContentIncompatibleVersion", "Needs {version}; this instance runs {actual}", "需要 {version}，该实例运行的是 {actual}"),
+    ("ContentIncompatibleLoader", "Not built for {loader}", "不支持 {loader}"),
+    ("ContentModpackNotReady", "Installing modpacks from the library into an instance is not available yet", "从内容库一键安装整合包到实例还没做（本地的包可以直接导入）"),
+    ("ContentSourceUnavailable", "CurseForge needs an API key: add one in Settings", "CurseForge 需要在设置里配置密钥才能搜索"),
+    ("ContentSourceNotWired", "Installing from CurseForge is not available yet", "CurseForge 来源的安装尚未开放"),
+    ("PackTitle", "Modpack import & export", "整合包导入 / 导出"),
+    ("PackImportTitle", "Import a modpack", "导入整合包"),
+    ("PackDropHint", "Drop a .mrpack, .zip or a MultiMC/Prism instance folder here", "把 .mrpack / .zip 或 MultiMC·Prism 实例目录拖到这里"),
+    ("PackDropActive", "Release to probe the pack", "松手开始探测"),
+    ("PackNoDialog", "This build has no system file picker: drag the file in, or paste its path below.", "本版没有系统文件选择框：请把文件拖进来，或在下面粘贴路径。"),
+    ("PackPathLabel", "Pack path", "整合包路径"),
+    ("PackPathPlaceholder", "D:\\packs\\Better MC.mrpack", "D:\\整合包\\更好的MC.mrpack"),
+    ("PackImportAction", "Import", "导入"),
+    ("PackCancel", "Cancel import", "取消导入"),
+    ("PackDismiss", "Dismiss", "关闭"),
+    ("PackTargetLabel", "Install into", "装到实例"),
+    ("PackTargetNew", "New instance", "新建实例"),
+    ("PackInstanceName", "Instance name", "实例名"),
+    ("PackStageLine", "Step {index}/{total} · {stage}", "步骤 {index}/{total} · {stage}"),
+    ("PackStageProbe", "Reading the manifest", "读取清单"),
+    ("PackStageExtract", "Unpacking overrides", "解包覆盖内容"),
+    ("PackStageFetch", "Fetching missing files", "补下载文件"),
+    ("PackStageCommit", "Writing files", "落地写盘"),
+    ("PackStageRegister", "Registering the instance", "登记实例"),
+    ("PackProbeTitle", "This pack is almost a known format", "这个包差一点就是已知格式"),
+    ("PackProbeLooksLike", "Looks like {format}, but missing: {missing}", "看起来像 {format}，但缺：{missing}"),
+    ("PackProbeUnknown", "No known format claims this pack", "没有任何已知格式认领这个包"),
+    ("PackProbeSaw", "Found in the pack: {saw}", "包里看到：{saw}"),
+    ("PackProbeNothing", "nothing recognisable", "没有可识别的东西"),
+    ("PackStatusSuccess", "Imported", "已导入"),
+    ("PackStatusPartial", "Imported with gaps", "导入完成，但有缺口"),
+    ("PackStatusFailed", "Import failed — rolled back", "导入失败 —— 已整包回滚"),
+    ("PackReportWritten", "Files written: {count} · {bytes}", "{count} 个文件已写盘 · {bytes}"),
+    ("PackReportMissing", "Could not fetch (tolerated): {count}", "有 {count} 个文件没搞到（可容忍）"),
+    ("PackReportConflicts", "Conflicts: {count}", "冲突：{count} 个"),
+    ("PackReportRejected", "The client does not support these: {count}", "这些组件客户端不支持：{count} 个"),
+    ("PackReportRejectedNote", "not supported by the client", "客户端不支持"),
+    ("PackCancelled", "Import keeps running in the background — this result is discarded. Files already written stay.", "导入会在后台继续跑完 —— 本次结果作废；已经写下的文件会留下。"),
+    ("PackOverwriteAction", "Re-import, the pack wins", "以包为准重新导入"),
+    ("PackOverwriteNote", "Keeping both (renamed) is not supported yet: the import pipeline has one global conflict policy and no per-file decision channel.", "「两者都留（改名）」暂不支持：导入管线只有一套全局冲突策略，没有逐文件决策通道。"),
+    ("PackMissingOffline", "offline import", "离线导入"),
+    ("PackMissingNoSource", "no download source available yet", "暂时拿不到下载地址"),
+    ("PackMissingFetchFailed", "download failed: {detail}", "下载失败：{detail}"),
+    ("PackFatalTitle", "Rolled back — nothing was left behind", "已回滚 —— 目标目录零残留"),
+    ("PackFatalHint", "What to try next", "下一步可以试"),
+    ("PackConflictUserModified", "you changed it", "你改过"),
+    ("PackConflictUserDeleted", "you deleted it", "你删过"),
+    ("PackConflictPreExisting", "was already there", "本来就在"),
+    ("PackChoiceKeepUser", "kept yours", "保留我的"),
+    ("PackChoiceOverwrite", "pack version used", "用包里的"),
+    ("PackConflictHashes", "pack {pack} · base {base} · disk {disk}", "包内 {pack} · 基线 {base} · 磁盘 {disk}"),
+    ("PackConflictDetail", "Hashes", "三方哈希"),
+    ("PackFormatModrinth", "Modrinth .mrpack", "Modrinth 的 .mrpack"),
+    ("PackFormatCurseforge", "CurseForge manifest", "CurseForge 清单"),
+    ("PackFormatMultimc", "MultiMC / Prism instance", "MultiMC·Prism 实例"),
+    ("PackExportTitle", "Export this instance", "导出这个实例"),
+    ("PackExportOpen", "Export…", "导出…"),
+    ("PackExportFormat", "Format", "格式"),
+    ("PackExportName", "Pack name", "包名"),
+    ("PackExportVersion", "Version", "版本"),
+    ("PackExportOutput", "Save to", "保存到"),
+    ("PackExportOutputPlaceholder", "empty = suggested path", "留空 = 自动给一个路径"),
+    ("PackExportPrecheck", "Dry run", "预检"),
+    ("PackExportConfirm", "Write the pack", "确认写盘"),
+    ("PackExportAbort", "Back", "返回"),
+    ("PackExportMultimcNote", "MultiMC/Prism can only be imported, not exported (by design).", "MultiMC·Prism 只能导入、不能导出（有意省略）。"),
+    ("PackExportDone", "Wrote {path} · {bytes}", "已写出 {path} · {bytes}"),
+    ("PackExportFailed", "Export failed: {reason}", "导出失败：{reason}"),
+    ("PackExportPending", "Scanning the instance…", "正在扫描实例…"),
+    ("PackPreviewHead", "Will inline {inline} files · cannot export: {skipped}", "将内联 {inline} 个文件 · 无法导出 {skipped} 项"),
+    ("PackPreviewRemote", "{count} files can be referenced remotely", "{count} 个文件可走远程引用"),
+    ("PackPreviewInlineBytes", "{bytes} copied into overrides/", "{bytes} 会原样拷进 overrides/"),
+    ("PackPreviewInlineTitle", "Copied into overrides/ (first {shown}):", "原样拷进 overrides/（只列前 {shown} 个）："),
+    ("PackPreviewSkippedTitle", "Not in the pack: {count}", "没进包：{count} 项"),
+    ("PackPreviewNotes", "Known losses", "已知损失"),
+    ("PackPreviewTarget", "Will be written to {path}", "将写到 {path}"),
+    ("PackPreviewMore", "…and {count} more files (not shown here)", "…还有 {count} 个文件（这里不展开）"),
+    ("PackPreviewComplete", "Nothing is left out", "没有遗漏任何文件"),
+    ("PackPreviewIncomplete", "Some files will not be in the pack", "有文件不会进包"),
+    ("PackReasonModrinthSha1", "Modrinth match (SHA-1)", "Modrinth 命中（SHA-1）"),
+    ("PackReasonCurseFingerprint", "CurseForge match (fingerprint)", "CurseForge 命中（文件指纹）"),
+    ("PackReasonNoRemoteMatch", "unknown to both catalogs, inlined", "两个目录都不认识，已内联"),
+    ("PackReasonCurseOnly", "only CurseForge knows it, this format cannot use it, inlined", "只有 CF 认识，目标格式用不上，已内联"),
+    ("PackReasonModrinthOnly", "only Modrinth knows it, the CF manifest cannot use it, inlined", "只有 Modrinth 认识，CF 清单用不上，已内联"),
+    ("PackReasonMissingSha512", "the catalogue entry has no sha512 hash, inlined", "命中缺 sha512，已内联"),
+    ("PackReasonMissingCurseIds", "the catalogue entry has no CurseForge ids, inlined", "命中缺 projectID/fileID，已内联"),
+    ("PackReasonDisabled", "disabled file, this format cannot express it (.disabled kept)", "禁用文件，目标格式表达不了（保留 .disabled）"),
+    ("PackReasonSymlink", "symbolic link, skipped", "符号链接，已跳过"),
+    ("PackReasonUnsafePath", "path fails the pack path rules, skipped", "路径过不了包内规整，已跳过"),
+    ("PackReasonUnreadable", "cannot read it, skipped", "读不出来，已跳过"),
+    // ── M114 账户页：追加在 main 的全部域之后（金表只追加不重排）
+    ("AccountTitle", "Accounts", "账户"),
+    ("AccountSubtitle", "Microsoft, third-party skin servers and local profiles", "微软正版、第三方皮肤站与本地档案"),
+    ("AccountListTitle", "All accounts", "全部账户"),
+    ("AccountAddedOn", "Added {date}", "添加于 {date}"),
+    ("AccountActiveChip", "Active", "当前"),
+    ("AccountSwitch", "Use for launch", "切换为启动账户"),
+    ("AccountRelogin", "Sign in again", "重新登录"),
+    ("AccountRemove", "Remove", "删除"),
+    ("AccountKindMicrosoft", "Microsoft", "微软正版"),
+    ("AccountKindAuthlib", "Third-party skin server", "第三方皮肤站"),
+    ("AccountKindOffline", "Local profile", "本地档案"),
+    ("AccountServer", "Server {server}", "服务器 {server}"),
+    ("AccountEmptyTitle", "No accounts yet", "还没有账户"),
+    ("AccountEmptyBody", "Add a Microsoft account, a third-party skin server account, or a local profile.", "添加微软正版账户、第三方皮肤站账户，或建一个本地档案。"),
+    ("AccountEmptyAction", "Add an account", "添加账户"),
+    ("AccountTrackMicrosoftTitle", "Microsoft account", "微软正版"),
+    ("AccountTrackMicrosoftBody", "Sign in with a device code or in your browser. Online servers require this kind of account.", "用设备码或浏览器登录。联机服务器必须用这种账户。"),
+    ("AccountTrackAuthlibTitle", "Third-party skin server", "第三方皮肤站"),
+    ("AccountTrackAuthlibBody", "An authlib-injector compatible server (LittleSkin and friends) brings its own skins and capes.", "兼容 authlib-injector 的皮肤站（如 LittleSkin）自带皮肤与披风。"),
+    ("AccountTrackOfflineTitle", "Local profile", "本地档案"),
+    ("AccountTrackOfflineBody", "Local / isolated-network testing only — it cannot join servers that require a genuine Minecraft account.", "仅本地/隔离网络测试用，无法连接启用正版验证的服务器。"),
+    ("AccountTrackOpen", "Sign in", "登录"),
+    ("AccountTrackCreate", "Create profile", "创建档案"),
+    ("AccountDialogClose", "Close", "关闭"),
+    ("AccountOfflineNameLabel", "Profile name", "档案名"),
+    ("AccountOfflineNameHint", "3–16 letters, digits or underscore", "3–16 位字母、数字或下划线"),
+    ("AccountOfflineSubmit", "Create profile", "创建档案"),
+    ("AccountOfflineWarning", "Local / isolated-network testing only — it cannot join servers that require a genuine Minecraft account.", "仅本地/隔离网络测试用，无法连接启用正版验证的服务器。"),
+    ("AccountDeviceCodeLabel", "Enter this code", "输入这个用户码"),
+    ("AccountDeviceCodeCopy", "Copy code", "复制用户码"),
+    ("AccountDeviceLinkCopy", "Copy link", "复制链接"),
+    ("AccountDeviceCountdown", "{time} left", "剩 {time}"),
+    ("AccountDeviceExpired", "This code has expired. Start again for a fresh one.", "这个用户码已过期，重新开始换一个新的。"),
+    ("AccountDeviceRetry", "Try again", "重试"),
+    ("AccountDeviceCancel", "Cancel", "取消"),
+    ("AccountDeviceBrowser", "Sign in with browser", "用浏览器登录"),
+    ("AccountDeviceUseCode", "Use a device code instead", "改用设备码"),
+    ("AccountServerLabel", "Server address", "服务器地址"),
+    ("AccountServerHint", "API root, e.g. https://littleskin.cn/api/yggdrasil/", "API 根，例：https://littleskin.cn/api/yggdrasil/"),
+    ("AccountServerProbe", "Check server", "校验服务器"),
+    ("AccountLoginNameLabel", "Email or username", "邮箱或用户名"),
+    ("AccountPasswordLabel", "Password", "密码"),
+    ("AccountPasswordHint", "Used once for this sign-in. It is never stored.", "只在这次登录里用一次，不会保存。"),
+    ("AccountAuthlibSubmit", "Sign in", "登录"),
+    ("AccountAuthlibIdleHint", "The server is checked automatically when you sign in; Check server only does it up front.", "登录时会自动校验服务器；「校验服务器」只是提前跑一遍。"),
+    ("AccountSkinTitle", "Skin", "皮肤"),
+    ("AccountSkinNone", "No skin available", "没有可用皮肤"),
+    ("AccountSkinHint", "Skins come from the account's own server; nothing is generated locally.", "皮肤来自账户自己的服务器，本地不生成任何假皮肤。"),
+    ("AccountRailSignedOut", "Not signed in", "未登录"),
+    ("AccountDeviceHint", "Open the link in your browser and enter the code above.", "在浏览器里打开链接，输入上面的用户码。"),
+    ("AccountDeviceBrowserHint", "Finish the sign-in in the browser window we just opened; the link below also works.", "在我们刚打开的浏览器窗口里完成登录；下面的链接也能手动打开。"),
+    ("AccountServerChecking", "Checking the server…", "正在校验服务器…"),
+    ("AccountServerOk", "Server {server} is ready", "服务器 {server} 可用"),
+    ("AccountLoginFailed", "Sign-in failed", "登录失败"),
+    ("AccountCurrentTitle", "Current account", "当前账户"),
+    ("AccountFailureCode", "Code: {code}", "代码：{code}"),
+    ("AccountFailureDenied", "The server refused this sign-in (access denied).", "服务器拒绝了这次登录（拒绝访问）。"),
+    ("AccountFailureWhitelist", "Microsoft has not approved this launcher's app registration yet. An administrator has to accept the app, then try again.", "微软还没批准本启动器的应用注册：需要管理员同意该应用后再试。"),
+    ("AccountFailureUnreachable", "Could not reach the server. Check the network connection or the address, then try again.", "连不上服务器：检查网络或地址后重试。"),
+    ("AccountFailureNotAuthlib", "This address does not look like an authlib-injector server (the API root usually ends with /api/yggdrasil/).", "这个地址不像 authlib-injector 服务器（API 根通常以 /api/yggdrasil/ 结尾）。"),
+    ("AccountFailureBadCredentials", "The server rejected the username or password.", "服务器不认这个用户名或密码。"),
+    ("AccountFailureNoProfile", "The account has no Minecraft profile on this server yet. Create the character on the server first.", "这个账号在该服务器上还没有角色：先在皮肤站里创建角色。"),
+    ("AccountFailureStore", "Could not save the account to disk.", "账户没能写到磁盘上。"),
+    ("AccountFailureOther", "The sign-in failed. The full reason is in the launcher log.", "登录失败，完整原因在启动器日志里。"),
+    ("AccountDeviceRequesting", "Contacting Microsoft…", "正在联系微软…"),
+    ("AccountLoginSucceeded", "Signed in as {name}", "已登录 {name}"),
+    ("AccountNoticeAdded", "Added {name}", "已添加 {name}"),
+    ("AccountNoticeRemoved", "Removed {name}", "已删除 {name}"),
+    ("AccountNoticeSwitched", "{name} will be used for the next launch", "{name} 将作为下次启动的账户"),
+    ("AccountNoticeOfflineNameInvalid", "Profile names must be 3–16 letters, digits or underscores.", "档案名必须是 3–16 位字母、数字或下划线。"),
+    ("AccountNoticeAccountExists", "An account with that name already exists.", "同名账户已经存在。"),
+    ("AccountNoticeStoreFailed", "Could not save the account store. Check the disk and try again.", "账户库写不进去：检查磁盘后重试。"),
+    ("AccountNoticeNotFound", "That account no longer exists.", "这个账户已经不在了。"),
+    ("AccountNoticeOther", "The account action failed. The full reason is in the launcher log.", "账户操作失败，完整原因在启动器日志里。"),
+    ("AccountNoticeDismiss", "Dismiss", "关闭"),
+    ("AccountNoticeTitleFailed", "Account action failed", "账户操作失败"),
+    ("AccountNoticeTitleDone", "Account updated", "账户已更新"),
+    ("AccountHintAuthlibReauth", "Enter the password again for {server}.", "请输入 {server} 的密码。"),
+    ("AccountHintOfflineNoRelogin", "Local profiles have no server account to sign in again — create a new profile instead.", "本地档案没有可重新登录的服务器账户，请新建一个档案。"),
+];
diff --git a/crates/i18n/src/catalog/instances.rs b/crates/i18n/src/catalog/instances.rs
new file mode 100644
index 0000000..9bbb84f
--- /dev/null
+++ b/crates/i18n/src/catalog/instances.rs
@@ -0,0 +1,85 @@
+//! 实例页文案：页头、列表列头、详情动作、元信息卡的标签与值、运行状态与启动阶段。
+//!
+//! 域文件的形状见 [`crate::catalog`] 的「域装配」一节。
+//!
+//! ## 这一族在装配链的**第 2 位**（M120 钉住）
+//!
+//! `instances_entries!` 紧跟 `nav_entries!`，所以本族的 key 落在 `Key::ALL` 的前段、
+//! `LoaderVanilla` 之前。M120 的新 key 因此**追加在本域末尾**（= `InstancesEmptyBody` 之后），
+//! 既没插到别的族中间，也没为了「排在文件末尾」去重排别人的族：
+//! 金表（[`crate::catalog::golden`]）是 `Key::ALL` 的逐 index 镜像，位置跟着族走。
+//!
+//! ## M120 之前这七条全是**死 key**
+//!
+//! M117 加 `InstancesNew` / `InstancesImport` / `InstancesBack` / `InstancesPlay` /
+//! `InstancesLastPlayed` / `InstancesEmptyTitle` / `InstancesEmptyBody` 时，实例页并没有接它们
+//! ——页面上还是英文基线字面量（`"New instance"` / `"ALL INSTANCES"` / `"Present on disk"`…）。
+//! M120 一次接完，同时：
+//!
+//! - `InstancesEmptyBody` 的译文换成详情列真正画的那句（原来那句是「看详情」的泛说）；
+//! - **`InstancesLastPlayed` 删掉**：它的形状是「上一次游玩 {when}」这种整句，而页面上是
+//!   元信息卡（标签 `LAST PLAYED` + 值 `2026-10-29 19:22 UTC`，或值 `Never`）。留着它只会
+//!   多出一条没人用的 key，所以拆成 [`Key::InstancesMetaLastPlayed`]（标签）与
+//!   [`Key::InstancesNeverPlayed`]（值）。
+//!
+//! ## 两条口径（复审会盯）
+//!
+//! 1. **品牌与技术标识不翻译**：`Java`（元信息标签的值域）与 `pid`（进程号）原样保留两套语言；
+//! 2. **数字与分隔符不随语言变形**：[`Key::InstancesRunning`] 的中英都写成
+//!    `… · pid {pid}`，只有前半句换了；`{pid}` 之外一个字都不许动（`pages/instances/tests/i18n.rs`
+//!    用「中英同位置取占位符 + 数字原样」的断言钉这条）。
+
+macro_rules! instances_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // ── 实例页（M117 的七条：其中 `InstancesLastPlayed` 见模块文档，M120 删除）
+            InstancesNew => ("New instance", "新建实例"),
+            InstancesImport => ("Import", "导入"),
+            InstancesBack => ("Back to instances", "返回实例列表"),
+            InstancesPlay => ("Play", "启动"),
+            InstancesEmptyTitle => ("No instance selected", "未选择实例"),
+            InstancesEmptyBody => ("Pick an instance on the left to see its version, loader and launch options.", "在左侧选择一个实例，查看它的版本、加载器与启动选项。"),
+            // ── 页头与列表列头（M120）
+            InstancesTitle => ("Instances", "实例"),
+            InstancesSubtitle => ("Local versions and their mod loaders", "本地版本与它们的模组加载器"),
+            InstancesAllTitle => ("ALL INSTANCES", "全部实例"),
+            // ── 详情动作（M120）
+            InstancesStop => ("Stop", "停止"),
+            InstancesDuplicate => ("Duplicate", "复制"),
+            InstancesOpenFolder => ("Open folder", "打开文件夹"),
+            InstancesDelete => ("Delete", "删除"),
+            InstancesNarrowNote => (
+                "Below 840 px the list and the detail share one column, so opening an instance replaces this screen (full-page switch). Widen the window to see both panes again.",
+                "窗口窄于 840 像素时，列表与详情共用一列：打开一个实例会整页替换这一屏（整页切换）。把窗口拉宽就能重新同时看见两栏。"
+            ),
+            // ── 元信息卡的标签（M120；`Java` 是品牌名，两套语言都写 Java）
+            InstancesMetaVersion => ("VERSION", "版本"),
+            InstancesMetaLoader => ("LOADER", "加载器"),
+            InstancesMetaMemory => ("MEMORY", "内存"),
+            InstancesMetaJava => ("JAVA", "Java"),
+            InstancesMetaMods => ("MODS", "模组"),
+            InstancesMetaIsolation => ("ISOLATION", "隔离方式"),
+            InstancesMetaVersionId => ("VERSION ID", "版本标识"),
+            InstancesMetaFiles => ("FILES", "文件"),
+            InstancesMetaLastPlayed => ("LAST PLAYED", "上次游玩"),
+            // ── 元信息卡的值（M120）
+            InstancesPresentOnDisk => ("Present on disk", "已在磁盘上"),
+            InstancesMissing => ("Missing", "缺失"),
+            InstancesNeverPlayed => ("Never", "从未游玩"),
+            // 隔离档位的两个稳定 id（`core::game::IsolationMode::as_str`）→ 人话。
+            // 白名单只覆盖真实存在的这两档；`inherit` / `custom` / 未知值原样上屏（不猜）。
+            InstancesIsolationIsolated => ("Isolated", "独立目录"),
+            InstancesIsolationShared => ("Shared", "共用目录"),
+            // ── 运行状态与启动阶段（M120；数字与分隔符不随语言变形）
+            InstancesRunning => ("Running · pid {pid}", "运行中 · pid {pid}"),
+            InstancesFailed => ("Launch failed · {reason}", "启动失败 · {reason}"),
+            InstancesStageDownload => ("Downloading", "下载中"),
+            InstancesStageVerify => ("Verifying", "校验中"),
+            InstancesStageLaunch => ("Starting", "启动中"),
+            InstancesStageWindow => ("Waiting for window", "等待游戏窗口"),
+        } }
+    };
+}
+
+pub(crate) use instances_entries;
diff --git a/crates/i18n/src/catalog/launch.rs b/crates/i18n/src/catalog/launch.rs
new file mode 100644
index 0000000..1559355
--- /dev/null
+++ b/crates/i18n/src/catalog/launch.rs
@@ -0,0 +1,59 @@
+//! 启动结局文案：一句话 = 一个 key（原来 UI 把 `"Launch failed"` 与 core 的「静默失败」拼成一句话）。
+//!
+//! 域文件的形状见 [`crate::catalog`] 的「域装配」一节。
+
+macro_rules! launch_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // ── 启动结局（原来 UI 把 "Launch failed" 与 core 的「静默失败」拼成一句话，现在一句话 = 一个 key）
+            LaunchOutcomeNormal => ("Finished normally", "正常结束"),
+            LaunchOutcomeCrash => ("The game crashed", "游戏崩溃"),
+            LaunchOutcomeSilent => (
+                "Suspected silent failure: exit code 0, but the game never really started",
+                "疑似静默失败：退出码 0，但游戏没真正跑起来"
+            ),
+            LaunchFailedWithCode => ("Launch failed (exit {code}): {reason}", "启动失败（退出码 {code}）：{reason}"),
+            // M117：微软轨的 client id 没配是**配置缺失**，不是「本期未支持」。这句话是那条
+            // 启动失败文案的**双语口径**（真源在 `core::auth::microsoft` 的
+            // `MISSING_CLIENT_ID_MESSAGE`，中文逐字一致；英文这条给 En 界面用）。
+            // 判据：中英都点名 `ULL_MSA_CLIENT_ID` 并给出构建期注入这条路，且**不许**出现
+            // 「unsupported / 未支持」——用户实跑就是被那句误导读成「功能没做」。
+            LaunchMsaNotConfigured => (
+                "Microsoft sign-in is not configured: it needs an Azure public client id (the login flow itself is implemented). Build with ULL_MSA_CLIENT_ID=<id>, or set that environment variable before launching.",
+                "微软登录未配置：缺少 Azure 公共客户端 id（登录功能已实现，只差这一项配置）。构建时注入：ULL_MSA_CLIENT_ID=<id> cargo build；或启动前设置同名环境变量 ULL_MSA_CLIENT_ID=<id>。"
+            ),
+        } }
+    };
+}
+
+pub(crate) use launch_entries;
+
+#[cfg(test)]
+mod tests {
+    use crate::{Catalog, Key, Lang};
+
+    #[test]
+    fn msa_not_configured_copy_is_accurate_in_both_languages() {
+        // 抓得住：文案退回「本期未支持」这类说法（M117 用户实跑踩到的原 bug），
+        //         以及两条译文只剩一句「需要 id」却不给怎么配。
+        // 抓不住：读起来顺不顺——那要靠 review 与截图。
+        let en = Catalog::of(Lang::En).text(Key::LaunchMsaNotConfigured);
+        let zh = Catalog::of(Lang::ZhCn).text(Key::LaunchMsaNotConfigured);
+
+        for (tag, text) in [("en", en), ("zh-CN", zh)] {
+            assert!(text.contains("ULL_MSA_CLIENT_ID"), "{tag}: {text}");
+        }
+        assert!(en.contains("client id"), "{en}");
+        assert!(en.contains("not configured"), "{en}");
+        assert!(!en.to_lowercase().contains("unsupported"), "{en}");
+        assert!(!en.to_lowercase().contains("not implemented"), "{en}");
+
+        assert!(zh.contains("客户端 id"), "{zh}");
+        assert!(zh.contains("未配置"), "{zh}");
+        assert!(!zh.contains("未支持"), "{zh}");
+        assert!(!zh.contains("未实现"), "{zh}");
+        // 硬约束：词条里只许出现 `<id>` 占位，不出现真 id（repo 任何文件都不许带）。
+        assert!(en.contains("<id>") && zh.contains("<id>"));
+    }
+}
diff --git a/crates/i18n/src/catalog/loader.rs b/crates/i18n/src/catalog/loader.rs
new file mode 100644
index 0000000..01947b1
--- /dev/null
+++ b/crates/i18n/src/catalog/loader.rs
@@ -0,0 +1,15 @@
+//! 加载器文案：品牌名不翻译（Fabric / Forge / Quilt 一律原样），只有「原版」是一个词。
+//!
+//! 域文件的形状见 [`crate::catalog`] 的「域装配」一节。
+
+macro_rules! loader_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // ── 加载器（品牌名不翻译：Fabric / Forge / Quilt 一律原样，只有「原版」是词）
+            LoaderVanilla => ("Vanilla", "原版"),
+        } }
+    };
+}
+
+pub(crate) use loader_entries;
diff --git a/crates/i18n/src/catalog/logs.rs b/crates/i18n/src/catalog/logs.rs
new file mode 100644
index 0000000..14716b3
--- /dev/null
+++ b/crates/i18n/src/catalog/logs.rs
@@ -0,0 +1,40 @@
+//! 日志页文案（M95）。
+//!
+//! 日志页的**界面文案**（标题 / 按钮 / 分组名 / 空态）。诊断结论的正文不在这里：
+//! 那是规则表 `rules.d/*.yaml` 的输出（数据），见 `pages/logs/diagnostic.rs` 的模块文档。
+//!
+//! `LogsStatus` 是**模板**：中英差别落在分隔符上（中文用全角竖线——`·` 是外来符号，
+//! 中文正文里偏挤；这也让「中文目录必须与英文不同」这条守卫成立，不是为过测试硬造差异）。
+//!
+//! 域文件的形状见 [`crate::catalog`] 的「域装配」一节。
+
+macro_rules! logs_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // --- logs page (M95) ---
+            LogsSubtitleIdle => ("Nothing is running right now", "当前没有运行中的实例"),
+            LogsStatus => ("{instance} · {when} · {outcome}", "{instance}｜{when}｜{outcome}"),
+            LogsOpenFolder => ("Open folder", "打开目录"),
+            LogsClear => ("Clear", "清空"),
+            LogsOutputTitle => ("OUTPUT", "输出"),
+            LogsDiagnosisTitle => ("DIAGNOSIS", "诊断"),
+            LogsConfidenceHigh => ("HIGH CONFIDENCE", "高置信度"),
+            LogsConfidenceMedium => ("MEDIUM CONFIDENCE", "中置信度"),
+            LogsConfidenceLow => ("LOW CONFIDENCE", "低置信度"),
+            LogsSubtitleLive => ("Running now — logs stream as they arrive", "正在运行 — 日志实时滚动"),
+            LogsConfidence => ("Confidence {percent}%", "置信度 {percent}%"),
+            LogsSuggestedFix => ("Suggested fix", "建议动作"),
+            LogsSummaryLabel => ("One-line summary", "一行摘要"),
+            LogsCopySummary => ("Copy summary", "复制摘要"),
+            LogsEmptyTitle => ("No output yet", "还没有输出"),
+            LogsEmptyBody => (
+                "Logs stream here while the launcher or the game is running. Pick an instance and start it to see the first lines.",
+                "启动器或游戏运行时，日志会实时出现在这里。选择一个实例并启动，就能看到第一批日志。"
+            ),
+            LogsEmptyAction => ("Choose an instance", "选择实例"),
+        } }
+    };
+}
+
+pub(crate) use logs_entries;
diff --git a/crates/i18n/src/catalog/nav.rs b/crates/i18n/src/catalog/nav.rs
new file mode 100644
index 0000000..4b48360
--- /dev/null
+++ b/crates/i18n/src/catalog/nav.rs
@@ -0,0 +1,42 @@
+//! 导航文案：四个一级页。AI 独立页没有导航高亮项（`Route::Agent.nav()` 是 `None`），所以没有 key。
+//!
+//! 域文件的形状见 [`crate::catalog`] 的「域装配」一节：本宏把条目**追加**到 `$acc` 之后，
+//! 再把「还没装配的域」原样交给 `$next`。条目顺序 = `Key` 的声明顺序（金表 `catalog::golden` 守门）。
+//!
+//! **显示名与标识符不同名**（M108）：`NavDownload` 这条说的是「版本管理」，而它指向的仍是
+//! `Route::Download` / `NavSection::Download`。用户令（2026-11-04）只改**显示层**：全仓重命名
+//! 标识符会与在途的多条线全面撞车，收益只在观感，所以标识符改名后置。
+//!
+//! ## 为什么「版本管理」有两条 key（M108）
+//!
+//! D33 定死了导航两态：**88 收起轨 ⇄ 240 展开抽屉**。88px 里塞得下中文「版本管理」（4 字 ≈48px），
+//! 但塞不下英文 `Version management`（18 字符 ≈101px > 88）——那会变成截断或两行，两个都是视觉缺陷
+//! （两行还要把项高从 52 抬到 68，等于为一个词改全局导航节奏）。
+//!
+//! 所以按**容器宽度**分两条：
+//!
+//! | key | 用在哪 | en | zh-CN |
+//! |---|---|---|---|
+//! | [`NavDownload`] | 88 收起轨（`shell/nav.rs` / `pages/nav.rs`） | `Versions` | 版本管理 |
+//! | [`NavDownloadExpanded`] | 240 展开抽屉（D33 的展开态） | `Version management` | 版本管理 |
+//!
+//! 中文两条**故意同值**：48px 放得下就没有理由为「对称」砍短（那是视觉缺陷，不是风格）。
+//! 英文短名选 `Versions` 而不是 `Versions list` / `Downloads`：单一词最省宽度，且不与「下载」
+//! （真在传文件的动作、设置页的下载分组）混淆。切换点只有 [`crate::catalog`] 的调用方一处，
+//! 见 `pages/nav.rs` 的 `label_key`。
+
+macro_rules! nav_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // ── 导航轨（`pages::Route` 的四项）
+            NavInstances => ("Instances", "实例"),
+            NavDownload => ("Versions", "版本管理"),
+            NavDownloadExpanded => ("Version management", "版本管理"),
+            NavLogs => ("Logs", "日志"),
+            NavSettings => ("Settings", "设置"),
+        } }
+    };
+}
+
+pub(crate) use nav_entries;
diff --git a/crates/i18n/src/catalog/settings/ai.rs b/crates/i18n/src/catalog/settings/ai.rs
new file mode 100644
index 0000000..17f2514
--- /dev/null
+++ b/crates/i18n/src/catalog/settings/ai.rs
@@ -0,0 +1,13 @@
+//! 设置页「AI / About」分组文案：**预留**（页面上还没有这个分组，见 `pages/settings/mod.rs` 的
+//! 分组注册表）。
+//!
+//! 加 key 时把条目写进 `$($acc)*` 后面即可（形状见 [`crate::catalog`] 的「域装配」一节）。
+//! 现在没有条目，所以本宏是**空转移器**：只把累积表原样交给下一个域。
+
+macro_rules! settings_ai_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* { $($acc)* } }
+    };
+}
+
+pub(crate) use settings_ai_entries;
diff --git a/crates/i18n/src/catalog/settings/appearance.rs b/crates/i18n/src/catalog/settings/appearance.rs
new file mode 100644
index 0000000..907e9a2
--- /dev/null
+++ b/crates/i18n/src/catalog/settings/appearance.rs
@@ -0,0 +1,35 @@
+//! 设置页「Appearance」分组文案（M116 首次落地：窗口圆角一档）。
+//!
+//! 加 key 时把条目写进 `$($acc)*` 后面即可（形状见 [`crate::catalog`] 的「域装配」一节）。
+//!
+//! ## 为什么只有圆角这一组的 key
+//!
+//! 本分组的既有控件（整窗/面板透明度、背景图、配色来源……）是 M93 落的，文案是英文基线字面量
+//! （`pages/appearance/section.rs`）。M116 新增的圆角档位**从一开始就走词表**（tower 口径：
+//! 设置项文案不许硬编码），所以这里先只有它这一组；老控件接词表归 i18n 接线 mission。
+//!
+//! ## 文案口径（不许暗示所有平台一致）
+//!
+//! 用户定案：Win11 / Server 2025 开系统圆角，Win10 可以不开，其他系统按窗口合成器的默认规则。
+//! 所以说明句必须写清「谁负责画圆」而不是「我们支持圆角」——后半句在 Win10 上是假的。
+
+macro_rules! settings_appearance_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            SettingsAppearanceCorner => ("Window corners", "窗口圆角"),
+            SettingsAppearanceCornerSystem => ("Follow system", "跟随系统"),
+            SettingsAppearanceCornerSquare => ("Square", "直角"),
+            SettingsAppearanceCornerHint => (
+                "On Windows 11 and Server 2025 we ask the system for rounded corners; Windows 10 keeps square corners. On macOS and Linux the desktop's own rules apply. We never draw corners ourselves.",
+                "Windows 11 与 Windows Server 2025 上我们请求系统处理外框圆角；Windows 10 保持直角；macOS 与 Linux 交给桌面合成器自己的规则；我们不自己画圆角。"
+            ),
+            SettingsAppearanceCornerSuspended => (
+                "Not in effect right now: window transparency is below 100%. Setting it back to 100% restores the rounded corners.",
+                "当前因整窗透明度不生效：把整窗透明度调回 100% 圆角即恢复。"
+            ),
+        } }
+    };
+}
+
+pub(crate) use settings_appearance_entries;
diff --git a/crates/i18n/src/catalog/settings/download.rs b/crates/i18n/src/catalog/settings/download.rs
new file mode 100644
index 0000000..49163e3
--- /dev/null
+++ b/crates/i18n/src/catalog/settings/download.rs
@@ -0,0 +1,12 @@
+//! 设置页「Downloads」分组文案：**预留**（页面侧的真控件还没接）。
+//!
+//! 加 key 时把条目写进 `$($acc)*` 后面即可（形状见 [`crate::catalog`] 的「域装配」一节）。
+//! 现在没有条目，所以本宏是**空转移器**：只把累积表原样交给下一个域。
+
+macro_rules! settings_download_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* { $($acc)* } }
+    };
+}
+
+pub(crate) use settings_download_entries;
diff --git a/crates/i18n/src/catalog/settings/general.rs b/crates/i18n/src/catalog/settings/general.rs
new file mode 100644
index 0000000..ba523cf
--- /dev/null
+++ b/crates/i18n/src/catalog/settings/general.rs
@@ -0,0 +1,19 @@
+//! 设置页「General」分组文案：语言（Theme / Startup page / Close button 的 key 还没建）。
+//!
+//! 域文件的形状见 [`crate::catalog`] 的「域装配」一节。
+
+macro_rules! settings_general_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // ── 设置
+            SettingsLanguage => ("Language", "界面语言"),
+            SettingsLanguageHint => (
+                "Switches the interface language. Chinese text needs a Chinese font.",
+                "切换界面语言。显示中文需要中文字体。"
+            ),
+        } }
+    };
+}
+
+pub(crate) use settings_general_entries;
diff --git a/crates/i18n/src/catalog/settings/java.rs b/crates/i18n/src/catalog/settings/java.rs
new file mode 100644
index 0000000..db75b75
--- /dev/null
+++ b/crates/i18n/src/catalog/settings/java.rs
@@ -0,0 +1,12 @@
+//! 设置页「Java」分组文案：**预留**（页面侧的真控件还没接）。
+//!
+//! 加 key 时把条目写进 `$($acc)*` 后面即可（形状见 [`crate::catalog`] 的「域装配」一节）。
+//! 现在没有条目，所以本宏是**空转移器**：只把累积表原样交给下一个域。
+
+macro_rules! settings_java_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* { $($acc)* } }
+    };
+}
+
+pub(crate) use settings_java_entries;
diff --git a/crates/i18n/src/catalog/settings/mod.rs b/crates/i18n/src/catalog/settings/mod.rs
new file mode 100644
index 0000000..b2746d9
--- /dev/null
+++ b/crates/i18n/src/catalog/settings/mod.rs
@@ -0,0 +1,28 @@
+//! 设置页文案：**一个分组一个文件**，与页面侧的 `pages/settings/**` 同构。
+//!
+//! 为什么拆到这个粒度：设置页正文接下来由四条并行 mission 分别接（java / download /
+//! language+appearance / ai+about），它们都会往设置页加 key。一个分组一个文件之后，每条线只改
+//! 自己那个文件，`catalog.rs` 的装配链一行都不用动（链里已经把这五个域接好了）。
+//!
+//! | 文件 | 分组（`pages/settings` 的 `GROUPS`） | 现状 |
+//! |---|---|---|
+//! | [`general`] | General（Language / Theme / Startup page / Close button） | 2 条 key（语言） |
+//! | [`appearance`] | Appearance（Density / Corner style / Motion / Text scale） | 预留，暂无 key |
+//! | [`java`] | Java（Runtime / Default memory / JVM arguments） | 预留，暂无 key |
+//! | [`download`] | Downloads（Preferred source / Concurrency / Verify checksums） | 预留，暂无 key |
+//! | [`ai`] | AI / About（页面上还没有这个分组） | 预留，暂无 key |
+//!
+//! 「预留」的文件里是**空转移器**（只把累积表原样交给下一个域）：加 key 时把条目写进它
+//! `$($acc)*` 后面即可——签名不用改，`catalog.rs` 不用碰，跨线零冲突。
+
+mod ai;
+mod appearance;
+mod download;
+mod general;
+mod java;
+
+pub(crate) use ai::settings_ai_entries;
+pub(crate) use appearance::settings_appearance_entries;
+pub(crate) use download::settings_download_entries;
+pub(crate) use general::settings_general_entries;
+pub(crate) use java::settings_java_entries;
diff --git a/crates/i18n/src/catalog/tests.rs b/crates/i18n/src/catalog/tests.rs
new file mode 100644
index 0000000..1518e4c
--- /dev/null
+++ b/crates/i18n/src/catalog/tests.rs
@@ -0,0 +1,203 @@
+//! `Catalog` 的守门测试（从 `catalog.rs` 原样搬出来：那边已经贴着 400 行硬上限，
+//! 而页面每加一批 key 都要在这个模块里占一行）。
+//!
+//! **零改动搬运**：用例、注释、断言一字未动；`use super::*` 指向的仍是 `crate::catalog`。
+//! M94（下载页）与 M95（日志页）几乎同时撞到这堵墙、各自搬了一次：两条 branch 的**用例部分
+//! 逐字相同**（解冲突时按 M94 那份合并，测试数量 7 条不变）。
+
+use super::*;
+
+/// 手写一套**故意缺条**的目录（不经过 `catalog!`，模拟后续 mission 的注入表）。
+const PARTIAL_ZH: &[(Key, &str)] = &[
+    (Key::NavInstances, "实例"),
+    (Key::NavLogs, "日志"),
+    (Key::NavSettings, "设置"),
+    (Key::NavDownload, "下载"),
+    (Key::InstancesNew, "新建实例"),
+    (Key::InstancesImport, "导入"),
+    (Key::InstancesBack, "返回实例列表"),
+    (Key::InstancesPlay, "启动"),
+    (Key::InstancesEmptyTitle, "未选择实例"),
+    (
+        Key::InstancesEmptyBody,
+        "在左侧选择一个实例，查看它的版本、加载器与启动选项。",
+    ),
+    (Key::LoaderVanilla, "原版"),
+    (Key::LaunchOutcomeNormal, "正常结束"),
+    (Key::LaunchOutcomeCrash, "游戏崩溃"),
+    // 缺：LaunchOutcomeSilent / LaunchFailedWithCode / FontCjk* / Settings* / CoreTextUntranslated
+];
+
+#[test]
+fn built_in_catalogs_have_every_key() {
+    // 抓得住：`catalog!` 的成对生成被绕开（有人改回「两套各写一遍」并漏了一条 / 抄重了一条）。
+    //         判据是**集合相等**：`Key` 枚举拦住了「表里有、枚举没有」，这里拦反方向。
+    // 抓不住：译文对不对（这只能是人工 / 后续的语言审查）。
+    for lang in Lang::ALL {
+        let catalog = Catalog::of(*lang);
+        assert_eq!(catalog.missing(), Vec::new(), "{}", catalog.lang().tag());
+        assert_eq!(catalog.diagnose(), None);
+
+        let mut keys = catalog
+            .entries()
+            .iter()
+            .map(|(key, _)| *key)
+            .collect::<Vec<_>>();
+        let total = keys.len();
+        keys.sort_unstable();
+        keys.dedup();
+        assert_eq!(keys.len(), total, "{} 目录里有重复条目", lang.tag());
+        assert_eq!(
+            keys.len(),
+            Key::ALL.len(),
+            "{} 条目数与 key 数不等",
+            lang.tag()
+        );
+
+        for key in Key::ALL {
+            assert!(
+                catalog.get(*key).is_some(),
+                "{} 缺 {}",
+                lang.tag(),
+                key.name()
+            );
+        }
+    }
+    assert!(!Key::ALL.is_empty());
+}
+
+#[test]
+fn key_names_are_unique_and_stable() {
+    // 抓得住：同一个 key 被写成两个变体（名字重复会让日志/诊断指认失准）。
+    // 抓不住：重命名变体对下游源码的影响（那是编译错误，本来就跑不过）。
+    let mut names = Key::ALL.iter().map(|key| key.name()).collect::<Vec<_>>();
+    let total = names.len();
+    names.sort_unstable();
+    names.dedup();
+    assert_eq!(names.len(), total);
+    assert_eq!(Key::NavInstances.name(), "NavInstances");
+}
+
+#[test]
+fn chinese_catalog_is_actually_chinese() {
+    // 抓得住：整句漏译（英文被抄进中文表）；一条都没有说明这张表是真翻过的。
+    // 抓不住：语义翻错、语气不合（机器能查的只有「与英文不同」这一层）。
+    let en = Catalog::of(Lang::En);
+    let zh = Catalog::of(Lang::ZhCn);
+    for key in Key::ALL {
+        let english = en.text(*key);
+        assert_ne!(english, zh.text(*key), "{} 未翻译", key.name());
+        assert!(!english.is_empty() && !zh.text(*key).is_empty());
+    }
+}
+
+#[test]
+fn placeholder_sets_match_across_languages() {
+    // 抓得住：一处文案的 `{code}` / `{when}` 在另一套译文里丢了或写错名——
+    //         那会让 render() 输出半截句子，或让参数静默失效。
+    // 抓不住：占位符本身是不是正确的变量（那是调用方的职责，由页面侧测试守）。
+    let en = Catalog::of(Lang::En);
+    let zh = Catalog::of(Lang::ZhCn);
+    for key in Key::ALL {
+        let mut left = placeholders(en.text(*key));
+        let mut right = placeholders(zh.text(*key));
+        left.sort_unstable();
+        right.sort_unstable();
+        assert_eq!(left, right, "{}", key.name());
+    }
+    assert_eq!(placeholders("exit {code} at {when}"), vec!["code", "when"]);
+    assert_eq!(placeholders("没有占位符"), Vec::<&str>::new());
+}
+
+#[test]
+fn missing_rows_are_diagnosed_in_plain_words() {
+    // 抓得住：缺译诊断的**可读性**（必须点名语言、key 名与英文原文）——注入目录缺条时靠它定位。
+    // 抓不住：内置目录真的缺译（内置表由 catalog! 结构保证，见上一条测试）。
+    let partial = Catalog::from_entries(Lang::ZhCn, PARTIAL_ZH);
+    assert_eq!(partial.missing().len(), Key::ALL.len() - PARTIAL_ZH.len());
+
+    let report = partial.diagnose().expect("应当报缺译");
+    assert!(report.starts_with("zh-CN 缺 "), "{report}");
+    assert!(report.contains("LaunchOutcomeSilent"), "{report}");
+    assert!(
+        report.contains("Suspected silent failure"),
+        "诊断要带上英文原文当参考：{report}"
+    );
+    assert!(
+        !report.contains("NavInstances"),
+        "已译的 key 不该出现在报告里：{report}"
+    );
+}
+
+#[test]
+fn missing_translation_never_falls_back_silently() {
+    // 抓得住：缺译被静默顶替（回落英文 / 回落中文 / 返回空串）——那会产出「半句中文半句英文」的界面。
+    // 抓不住：MISSING 标记真的被画到屏幕上（那是 UI 侧截图验收的事）。
+    let partial = Catalog::from_entries(Lang::ZhCn, PARTIAL_ZH);
+    assert_eq!(partial.get(Key::LaunchOutcomeSilent), None);
+    assert_eq!(partial.text(Key::LaunchOutcomeSilent), MISSING);
+    assert_eq!(
+        partial.render(
+            Key::LaunchFailedWithCode,
+            &[("code", "0"), ("reason", "JVM 拒绝启动")]
+        ),
+        "⟪missing:LaunchFailedWithCode⟫"
+    );
+}
+
+#[test]
+fn render_substitutes_and_keeps_unfilled_placeholders_visible() {
+    // 抓得住：占位符替换的回归（漏参时**保留** `{code}` 而不是清空、不 panic）。
+    // 抓不住：调用方传没传对值（`("code", "0")` 是不是真的退出码）。
+    let zh = Catalog::of(Lang::ZhCn);
+    assert_eq!(
+        zh.render(
+            Key::LaunchFailedWithCode,
+            &[("code", "0"), ("reason", "mod 冲突")]
+        ),
+        "启动失败（退出码 0）：mod 冲突"
+    );
+    assert_eq!(
+        zh.render(Key::LaunchFailedWithCode, &[("code", "0")]),
+        "启动失败（退出码 0）：{reason}"
+    );
+    assert_eq!(zh.text(Key::InstancesNew), "新建实例");
+    assert_eq!(zh.lang(), Lang::ZhCn);
+}
+
+/// M99：把单张条目表按域拆到 `catalog/<域>.rs` 之后，`key -> (en, zh-CN)` 必须**逐条逐字节**不变。
+///
+/// **抓得住**：① 某个 key 整条被搬丢（金表有、现在没有 ⇒ 条数或 key 名对不上）；② 两条 key 的译文
+/// 互抄 / 同 key 被覆盖成别人的译文（该行 en 或 zh 不等）；③ 某条译文改了一个字符（逐字节比，
+/// **不是**数条数——「A 丢了一条、B 复制成两条」条数照旧）；④ 域的顺序被调换（`Key` 的 `Ord` 与
+/// `entries()` 的声明顺序都靠它，金表按原顺序比）。
+/// **抓不住**：译文本身翻得对不对——金表是「拆分前那一份」的快照，只能证明没变，不能证明翻得好。
+///
+/// 金表怎么来的：拆分前在这里临时加过一条 `println!("GOLD\t{}\t{}\t{}", …)` 的用例，把
+/// `Key::ALL` ×（`Catalog::of(En)`, `Catalog::of(ZhCn)`）导出成 72 行 TSV，再原样抄成
+/// `catalog/golden.rs`；那条导出用例随后已删除（不在提交里）。
+#[test]
+fn split_keeps_every_translation() {
+    let en = Catalog::of(Lang::En);
+    let zh = Catalog::of(Lang::ZhCn);
+    let actual = Key::ALL
+        .iter()
+        .map(|key| (key.name(), en.text(*key), zh.text(*key)))
+        .collect::<Vec<_>>();
+
+    assert_eq!(
+        actual.len(),
+        super::golden::GOLDEN.len(),
+        "key 条数与拆分前不一致（某条被搬丢，或多出来一条）"
+    );
+
+    for (index, expected) in super::golden::GOLDEN.iter().enumerate() {
+        let got = actual[index];
+        assert_eq!(
+            got.0, expected.0,
+            "第 {index} 条的 key 变了：拆分的域顺序被打乱，或某条被搬到了别处"
+        );
+        assert_eq!(got.1, expected.1, "{} 的英文译文变了", expected.0);
+        assert_eq!(got.2, expected.2, "{} 的中文译文变了", expected.0);
+    }
+}
diff --git a/crates/i18n/src/choice.rs b/crates/i18n/src/choice.rs
new file mode 100644
index 0000000..f503a01
--- /dev/null
+++ b/crates/i18n/src/choice.rs
@@ -0,0 +1,258 @@
+//! 设置页的**界面语言档位**（M106 `I18NFOLLOW`）：跟随系统 / 手选某一门。
+//!
+//! ## 为什么单独一个文件
+//!
+//! `lang.rs` 讲的是「系统说哪种语言」（locale → [`Lang`] 的探测，M92），本文件讲的是「用户要哪种
+//! 语言」——两者的判据不一样：探测只能尽量理解别人给的字符串，档位是我们自己写进配置的，写错就该
+//! 暴露。放在一起会让 `lang.rs` 顶破 400 行（任务书那条硬线要求按功能拆文件）。
+//!
+//! ## D28 的判定顺序（整条挂在 [`LangChoice::resolve`] 上）
+//!
+//! **手选 > 系统语言 > 环境变量 > 英文**。最后一级「英文」不是偷懒：纯英文环境不扫、不下载中文
+//! 字体（零额外体积 / 零网络），这条由 [`crate::font::decide`] 兜住，真值表见下面
+//! `english_never_needs_a_chinese_font_and_chinese_always_resolves_one`。
+//!
+//! ## 「跟随系统」怎么表达
+//!
+//! **不写 `ui.language` 这个键**（[`LangChoice::setting_value`] 返回 `None`）。不写哨兵值是因为
+//! 两件事：① schema 的允许值只有 `zh_cn` / `en_us`（`core::setting::keys::LANGUAGES`），写别的
+//! 会被枚举校验拒掉；② 读的那一头（`SettingBridge::load_ui_language`）只认显式值，所以「键不存在」
+//! 与「用户选了跟随系统」本来就是同一件事。
+
+use crate::catalog::Key;
+use crate::lang::{resolve, Detection, Lang, LocaleSource, ORIGIN_SETTING};
+
+/// 设置页「界面语言」的三档选择。
+///
+/// 为什么不是 `Option<Lang>`：`None` 与「用户明确勾了跟随系统」在类型上分不开，而设置页要把那一档
+/// **画成选中**。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum LangChoice {
+    /// 跟随系统（= 配置里没有 `ui.language`）。
+    System,
+    /// 用户手选的固定语言。
+    Fixed(Lang),
+}
+
+impl LangChoice {
+    /// 全部档位（顺序即设置页语言行的按钮顺序）。
+    pub const ALL: &'static [LangChoice] = &[
+        LangChoice::System,
+        LangChoice::Fixed(Lang::ZhCn),
+        LangChoice::Fixed(Lang::En),
+    ];
+
+    /// 配置里 `ui.language` 的原文 → 档位。
+    ///
+    /// `None`（键不存在）与**不认识的值**都算「跟随系统」——与 [`resolve`] 跳过坏值的行为同源：
+    /// 配置被 AI / CLI 写脏时退回系统语言，而不是猜成某一种。
+    #[must_use]
+    pub fn from_setting(value: Option<&str>) -> LangChoice {
+        value
+            .and_then(Lang::from_setting)
+            .map_or(LangChoice::System, LangChoice::Fixed)
+    }
+
+    /// 落盘用：跟随系统 = `None`（**删掉那个键**，不写哨兵值——哨兵会让「跟随系统」永远失效）。
+    #[must_use]
+    pub const fn setting_value(self) -> Option<&'static str> {
+        match self {
+            LangChoice::System => None,
+            LangChoice::Fixed(lang) => Some(lang.setting_value()),
+        }
+    }
+
+    /// 这一档在设置页上的名字（key 在 `catalog/general.rs` 域）。
+    #[must_use]
+    pub const fn label_key(self) -> Key {
+        match self {
+            LangChoice::System => Key::SettingsLanguageFollowSystem,
+            LangChoice::Fixed(Lang::ZhCn) => Key::SettingsLanguageZhCn,
+            LangChoice::Fixed(Lang::En) => Key::SettingsLanguageEn,
+        }
+    }
+
+    /// 这一档最终生效的语言 + 来源（日志与设置页回显都用它）。
+    ///
+    /// 跟随系统 → 走 [`resolve`] 的三级链；手选 → 直接赢，`origin = setting`
+    /// （`raw` 写配置值，日志里能看出「这是用户手选的」）。
+    #[must_use]
+    pub fn resolve(self, platform: &dyn LocaleSource, env: &dyn LocaleSource) -> Detection {
+        match self {
+            LangChoice::System => resolve(None, platform, env),
+            LangChoice::Fixed(lang) => Detection {
+                lang,
+                raw: Some(lang.setting_value().to_owned()),
+                origin: ORIGIN_SETTING,
+            },
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::lang::ORIGIN_DEFAULT;
+
+    #[test]
+    fn choice_round_trips_through_the_config_value() {
+        // 抓得住：①「跟随系统」被写成哨兵值——那会让 `Lang::from_setting` 认不出、下次启动退回
+        //        系统语言，「手选」这件事静默丢失；②档位顺序被调换（设置页按钮顺序）。
+        // 抓不住：配置文件里到底有没有这个键（那是 `SettingsBridge` 的读写，见 presenter 侧测试）。
+        assert_eq!(LangChoice::from_setting(None), LangChoice::System);
+        assert_eq!(
+            LangChoice::from_setting(Some("zh_cn")),
+            LangChoice::Fixed(Lang::ZhCn)
+        );
+        assert_eq!(
+            LangChoice::from_setting(Some("en_us")),
+            LangChoice::Fixed(Lang::En)
+        );
+        for bogus in ["zh-CN", "system", "", "fr_fr"] {
+            assert_eq!(
+                LangChoice::from_setting(Some(bogus)),
+                LangChoice::System,
+                "{bogus}"
+            );
+        }
+
+        assert_eq!(LangChoice::System.setting_value(), None, "跟随系统不写键");
+        for choice in LangChoice::ALL {
+            assert_eq!(
+                LangChoice::from_setting(choice.setting_value()),
+                *choice,
+                "{} 落盘后读不回来",
+                choice.setting_value().unwrap_or("<跟随系统>")
+            );
+        }
+        assert_eq!(
+            LangChoice::ALL,
+            &[
+                LangChoice::System,
+                LangChoice::Fixed(Lang::ZhCn),
+                LangChoice::Fixed(Lang::En)
+            ][..]
+        );
+    }
+
+    #[test]
+    fn choice_resolution_truth_table() {
+        // D28 的四级优先级，**逐档逐源**列出来：手选 > 系统 > 环境变量 > 英文。
+        // 抓得住：优先级顺序被改（例如手选的英文被中文系统盖掉）、或「跟随系统」直接落英文。
+        // 抓不住：这些源在真机上读到什么（`SystemLocale` 的真机行为在 `app-iced` 侧）。
+        struct Named(&'static str, Option<&'static str>);
+
+        impl LocaleSource for Named {
+            fn locale(&self) -> Option<String> {
+                self.1.map(str::to_owned)
+            }
+            fn label(&self) -> &'static str {
+                self.0
+            }
+        }
+
+        let registry_zh = Named("registry", Some("zh-CN"));
+        let registry_en = Named("registry", Some("en-US"));
+        let nothing = Named("registry", None);
+        let env_zh = Named("env", Some("zh_CN.UTF-8"));
+        let env_en = Named("env", Some("en_US.UTF-8"));
+        let env_none = Named("env", None);
+
+        let follow = LangChoice::System;
+        let en_choice = LangChoice::Fixed(Lang::En);
+        let zh = LangChoice::Fixed(Lang::ZhCn);
+
+        // (档位, 平台源, 环境变量源) -> (生效语言, 来源)
+        let table: &[(LangChoice, &dyn LocaleSource, &dyn LocaleSource, Lang, &str)] = &[
+            // ① 手选压过一切（系统是中文、环境是中文，手选英文就画英文）
+            (en_choice, &registry_zh, &env_zh, Lang::En, ORIGIN_SETTING),
+            (zh, &registry_en, &env_en, Lang::ZhCn, ORIGIN_SETTING),
+            // ② 跟随系统 → 系统源
+            (follow, &registry_zh, &env_en, Lang::ZhCn, "registry"),
+            (follow, &registry_en, &env_zh, Lang::En, "registry"),
+            // ③ 系统源取不到 → 环境变量
+            (follow, &nothing, &env_zh, Lang::ZhCn, "env"),
+            (follow, &nothing, &env_en, Lang::En, "env"),
+            // ④ 都没有 → 英文 + default（D28：纯英文环境不用管）
+            (follow, &nothing, &env_none, Lang::En, ORIGIN_DEFAULT),
+        ];
+
+        for (choice, platform, env, lang, origin) in table {
+            let detection = choice.resolve(*platform, *env);
+            assert_eq!(
+                (detection.lang, detection.origin),
+                (*lang, *origin),
+                "{choice:?} platform={:?} env={:?}",
+                platform.locale(),
+                env.locale()
+            );
+        }
+
+        // 手选档的 `raw` 是配置值（日志一眼看出「用户手选的」），跟随系统档的 `raw` 是系统原文。
+        assert_eq!(
+            zh.resolve(&registry_en, &env_en).describe(),
+            "lang=zh-CN locale=zh_cn source=setting"
+        );
+        assert_eq!(
+            follow.resolve(&registry_zh, &env_en).describe(),
+            "lang=zh-CN locale=zh-CN source=registry"
+        );
+    }
+
+    #[test]
+    fn english_never_needs_a_chinese_font_and_chinese_always_resolves_one() {
+        // D28 字体那一级的真值表（`font::decide` 是纯函数，这里把语言 × 系统字体库全组合扫一遍）：
+        // 抓得住：①英文环境被接上中文字体/下载（「零额外体积/零网络」的直接违约）；②中文环境扫不到
+        //        字体却不给下载信号（会白块）；③扫到了却不用系统字体（会白下 20 MB）。
+        // 抓不住：本机到底装没装这些族（`app-iced` 的 `fonts/cjk.rs` 把真字体库喂进来）。
+        use crate::font::{self, Strategy, CJK_FAMILIES, NOTO_SANS_SC};
+
+        let has_font =
+            |families: &'static [&'static str]| move |family: &str| families.contains(&family);
+
+        for installed in [
+            has_font(&[]),
+            has_font(&["Segoe UI"]),
+            has_font(CJK_FAMILIES),
+        ] {
+            assert_eq!(
+                font::decide(Lang::En, &installed),
+                Strategy::NotNeeded,
+                "英文环境不许要中文字体"
+            );
+        }
+
+        assert_eq!(
+            font::decide(Lang::ZhCn, &has_font(&["Segoe UI"])),
+            Strategy::NeedsDownload(&NOTO_SANS_SC)
+        );
+        let first = CJK_FAMILIES[0];
+        let installed = has_font(&["Segoe UI", "Microsoft YaHei UI"]);
+        assert_eq!(first, "Microsoft YaHei UI");
+        assert_eq!(
+            font::decide(Lang::ZhCn, &installed),
+            Strategy::System { family: first }
+        );
+    }
+
+    #[test]
+    fn every_choice_has_a_label_in_both_catalogs() {
+        // 抓得住：设置页语言行接了一个 catalog 里不存在的 key（画出来是 `⟪missing:…⟫`）。
+        // 抓不住：译文翻得对不对（金表 + `chinese_catalog_is_actually_chinese` 管那一层）。
+        let mut keys = Vec::new();
+        for choice in LangChoice::ALL {
+            let key = choice.label_key();
+            for lang in Lang::ALL {
+                assert!(
+                    lang.catalog().get(key).is_some(),
+                    "{key:?} 在 {} 目录里缺词",
+                    lang.tag()
+                );
+            }
+            keys.push(key);
+        }
+        keys.sort_unstable();
+        keys.dedup();
+        assert_eq!(keys.len(), LangChoice::ALL.len(), "两档用了同一个 key");
+    }
+}
diff --git a/crates/i18n/src/font.rs b/crates/i18n/src/font.rs
new file mode 100644
index 0000000..fb04985
--- /dev/null
+++ b/crates/i18n/src/font.rs
@@ -0,0 +1,331 @@
+//! 中文字体策略（D28 后半）：**只做判据，不联网**。
+//!
+//! ## 三句话
+//!
+//! 1. **英文环境不要字体**：`Lang::En` → [`Strategy::NotNeeded`]，与系统里装了什么无关。
+//!    D28 原话是「纯英文环境不用管（零额外体积/零网络）」，这条是本模块最重要的断言。
+//! 2. **中文环境先扫系统**：候选族名单见 [`CJK_FAMILIES`]，命中即用（[`Strategy::System`]）。
+//! 3. **扫不到才说要下载**：[`Strategy::NeedsDownload`] 是一个**信号**，不是动作——
+//!    真正下载由注入的 [`Fetcher`] 实现，本 mission 不写网络实现（D28 的 CDN 下载是后续 mission）。
+//!
+//! ## 扫描为什么在 UI 壳层而不是这里
+//!
+//! 真扫系统字体要 FontConfig / DirectWrite / iced 的 `font_system()`——任何一条都会把 iced 或平台
+//! SDK 拉进本 crate，破掉零依赖纪律。所以本模块只收一个 `installed: &dyn Fn(&str) -> bool`
+//! （iced 版实现在 `crates/app-iced/src/fonts/cjk.rs`），单测用假闭包，脱机可跑。
+//!
+//! ## 诚实边界（抓得住什么 / 抓不住什么）
+//!
+//! - **抓得住**：语言 → 是否需要中文 → 系统里有没有候选族 → 要不要下载 这条链路的判定；
+//! - **抓不住**：①**族名存在 ≠ 字形覆盖**——`fontdb` 里挂着一个叫 `SimSun` 的族也可能是个残缺子集，
+//!   真判据要用 `ttf-parser` 查 cmap（M60 Q3 的 spike 做过，本 mission 不引依赖）；
+//!   ②下载下来的字节怎么注册进 iced 的字体系统——iced 0.14 有 `iced::font::load(bytes) -> Task`
+//!   可在运行时注册（已核对上游源码），但「什么时候调、失败怎么回退、和启动日志怎么对账」
+//!   属于下载 mission，本 crate 不碰。
+
+use crate::lang::Lang;
+
+/// 已知的系统 CJK 族（Windows / macOS / Linux，按「观感优先」排序，命中第一个就用）。
+///
+/// 只收**简体**优先的常见族；`Microsoft JhengHei` 这类繁体族留在名单里垫底——
+/// 仓内只有一套中文目录（简体），繁体用户看简体的观感仍好过看英文。
+pub const CJK_FAMILIES: &[&str] = &[
+    // Windows 10/11
+    "Microsoft YaHei UI",
+    "Microsoft YaHei",
+    "DengXian",
+    "SimHei",
+    "SimSun",
+    "Microsoft JhengHei",
+    // macOS
+    "PingFang SC",
+    "Hiragino Sans GB",
+    "Heiti SC",
+    "Songti SC",
+    // Linux
+    "Noto Sans CJK SC",
+    "Noto Sans SC",
+    "Source Han Sans SC",
+    "Source Han Sans CN",
+    "Sarasa Gothic SC",
+    "WenQuanYi Micro Hei",
+    "Droid Sans Fallback",
+];
+
+/// 中文字体必须覆盖的字重（M-决定日志 ③：Android 16 的可变思源黑体缺 100–400，
+/// 而 M3 Expressive 的 emphasized 档要 700 ⇒ 「400 / 500 / 700 至少三档」）。
+pub const REQUIRED_WEIGHTS: &[u16] = &[400, 500, 700];
+
+/// 可下载字体的来源。本 mission **不 pin URL/哈希**——见 [`Source::PendingPin`]。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Source {
+    /// 待下载 mission 钉死：确切 URL + `sha256` + 子集范围（简体常用字 + 标点），
+    /// 并按 [`REQUIRED_WEIGHTS`] 覆盖 400/500/700。**故意不写一个随手想出来的 URL**：
+    /// 猜错的 CDN 路径会被后面所有人当事实用。
+    PendingPin,
+}
+
+/// 一套可下载的 CJK 字体描述（不含 URL / 哈希，原因见 [`Source`]）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct CjkFont {
+    /// 族名（下载并注册后，`Font` 用它取字）。
+    pub family: &'static str,
+    /// 许可证（必须是 OFL / Apache 这类可再分发的；D28 明令不得内置 Segoe）。
+    pub license: &'static str,
+    /// 这套字体可用的字重。
+    pub weights: &'static [u16],
+    /// 下载源（尚未钉死）。
+    pub source: Source,
+}
+
+/// 缺字体时的默认方案：Noto Sans SC（OFL-1.1）。
+pub const NOTO_SANS_SC: CjkFont = CjkFont {
+    family: "Noto Sans SC",
+    license: "OFL-1.1",
+    weights: &[300, 400, 500, 700, 900],
+    source: Source::PendingPin,
+};
+
+/// 字体策略结论。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Strategy {
+    /// 不需要中文字体（英文环境）。
+    NotNeeded,
+    /// 系统里已有可用族，直接用。
+    System {
+        /// 命中的族名。
+        family: &'static str,
+    },
+    /// 需要下载（本模块只发信号，不联网）。
+    NeedsDownload(&'static CjkFont),
+    /// 探测不出（拿不到系统字体库）——**不等于**「需下载」：不许凭猜测去下载。
+    Unprobeable,
+}
+
+impl Strategy {
+    /// 一行日志片段（`cjk=system:"Microsoft YaHei"` / `cjk=needs-download(Noto Sans SC)` …）。
+    #[must_use]
+    pub fn describe(&self) -> String {
+        match self {
+            Strategy::NotNeeded => "cjk=not-needed".to_owned(),
+            Strategy::System { family } => format!("cjk=system:\"{family}\""),
+            Strategy::NeedsDownload(font) => format!("cjk=needs-download({})", font.family),
+            Strategy::Unprobeable => "cjk=unprobeable".to_owned(),
+        }
+    }
+}
+
+/// 判据（纯函数）：语言 + 「某族装没装」→ 策略。
+///
+/// `installed` 由调用方提供（iced 版查系统字体库，单测给假闭包）。
+#[must_use]
+pub fn decide(lang: Lang, installed: &dyn Fn(&str) -> bool) -> Strategy {
+    if lang != Lang::ZhCn {
+        // D28：纯英文环境不加载任何中文字体，也不下载。
+        return Strategy::NotNeeded;
+    }
+
+    CJK_FAMILIES
+        .iter()
+        .copied()
+        .find(|family| installed(family))
+        .map_or(Strategy::NeedsDownload(&NOTO_SANS_SC), |family| {
+            Strategy::System { family }
+        })
+}
+
+/// 字体下载器接口（**注入式**；本 mission 没有网络实现）。
+pub trait Fetcher {
+    /// 取一套字体（返回原始字节，装进字体系统是调用方的事）。
+    ///
+    /// # Errors
+    /// 网络失败 / 校验失败等人话错误。
+    fn fetch(&self, font: &'static CjkFont) -> Result<Vec<u8>, FetchError>;
+}
+
+/// 下载失败的分类（给 UI 决定要不要重试；分类少是故意的）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum FetchError {
+    /// 网络层失败（超时 / 连不上 / 非 2xx）。
+    Network(String),
+    /// 校验失败（哈希 / 长度不符，或不是字体文件）。
+    Integrity(String),
+}
+
+/// [`ensure`] 的结局。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Fetched {
+    /// 本来就不需要（英文环境）。
+    NothingToDo,
+    /// 系统已有，直接用。
+    AlreadySystem {
+        /// 命中的族名。
+        family: &'static str,
+    },
+    /// 下载成功，拿到字节（交给调用方注册）。
+    Downloaded(Vec<u8>),
+    /// 探测不出，什么都没做。
+    Unknown,
+}
+
+/// 按策略执行：需要下载时才碰 [`Fetcher`]。
+///
+/// # Errors
+/// 下载器返回的错误原样透出（不吞、不改写分类）。
+pub fn ensure(strategy: Strategy, fetcher: &dyn Fetcher) -> Result<Fetched, FetchError> {
+    match strategy {
+        Strategy::NotNeeded => Ok(Fetched::NothingToDo),
+        Strategy::System { family } => Ok(Fetched::AlreadySystem { family }),
+        Strategy::Unprobeable => Ok(Fetched::Unknown),
+        Strategy::NeedsDownload(font) => fetcher.fetch(font).map(Fetched::Downloaded),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::cell::Cell;
+
+    fn only(installed: &'static [&'static str]) -> impl Fn(&str) -> bool {
+        move |family| installed.contains(&family)
+    }
+
+    /// 假下载器：记录调用次数，避免「悄悄联网」这种事在单测里被放过。
+    struct FakeFetcher {
+        calls: Cell<usize>,
+        result: Result<Vec<u8>, FetchError>,
+        seen: Cell<Option<&'static str>>,
+    }
+
+    impl FakeFetcher {
+        fn new(result: Result<Vec<u8>, FetchError>) -> Self {
+            FakeFetcher {
+                calls: Cell::new(0),
+                result,
+                seen: Cell::new(None),
+            }
+        }
+    }
+
+    impl Fetcher for FakeFetcher {
+        fn fetch(&self, font: &'static CjkFont) -> Result<Vec<u8>, FetchError> {
+            self.calls.set(self.calls.get() + 1);
+            self.seen.set(Some(font.family));
+            self.result.clone()
+        }
+    }
+
+    #[test]
+    fn english_never_wants_a_cjk_font() {
+        // 抓得住：D28 的核心承诺——英文环境不加载/不下载中文字体（D28 说「零额外体积/零网络」）。
+        // 抓不住：程序真的没去读那个字体文件（那是加载器的行为，本 crate 只管判据）。
+        assert_eq!(decide(Lang::En, &only(&[])), Strategy::NotNeeded);
+        assert_eq!(
+            decide(Lang::En, &only(&["Microsoft YaHei"])),
+            Strategy::NotNeeded,
+            "装了中文字体也不该进入中文分支"
+        );
+    }
+
+    #[test]
+    fn chinese_prefers_the_first_installed_candidate() {
+        // 抓得住：候选顺序（YaHei UI > YaHei > SimSun…）被调换，或命中判断写成了「装了任意字面就 ok」。
+        // 抓不住：命中的族是否真有简体字形覆盖（族名存在 ≠ cmap 覆盖，见模块文档）。
+        assert_eq!(
+            decide(
+                Lang::ZhCn,
+                &only(&["Segoe UI", "Microsoft YaHei", "SimSun"])
+            ),
+            Strategy::System {
+                family: "Microsoft YaHei"
+            }
+        );
+        assert_eq!(
+            decide(Lang::ZhCn, &only(&["PingFang SC"])),
+            Strategy::System {
+                family: "PingFang SC"
+            }
+        );
+        assert_eq!(
+            decide(Lang::ZhCn, &only(&["Noto Sans CJK SC", "Noto Sans SC"])),
+            Strategy::System {
+                family: "Noto Sans CJK SC"
+            }
+        );
+    }
+
+    #[test]
+    fn chinese_without_cjk_fonts_emits_the_download_signal() {
+        // 抓得住：中文环境 + 系统无 CJK 时**给信号**（而不是静默回英文、也不是自己联网）。
+        // 抓不住：信号之后 UI 有没有把提示画出来（页面侧 / 截图验收）。
+        let strategy = decide(Lang::ZhCn, &only(&["Segoe UI", "Roboto", "Cascadia Mono"]));
+        let Strategy::NeedsDownload(font) = strategy else {
+            panic!("应当要求下载：{strategy:?}");
+        };
+        assert_eq!(font.family, "Noto Sans SC");
+        assert_eq!(font.license, "OFL-1.1");
+        assert_eq!(font.source, Source::PendingPin, "URL/哈希留给下载 mission");
+        assert_eq!(strategy.describe(), "cjk=needs-download(Noto Sans SC)");
+    }
+
+    #[test]
+    fn download_fonts_cover_the_required_weights() {
+        // 抓得住：将来换了字体却没覆盖 400/500/700（M3 Expressive 的 emphasized 档要 700）。
+        // 抓不住：字重是可变轴还是静态子集（那要看下载 mission 选的文件，本 crate 只有元数据）。
+        for weight in REQUIRED_WEIGHTS {
+            assert!(
+                NOTO_SANS_SC.weights.contains(weight),
+                "缺 {weight} 档：{:?}",
+                NOTO_SANS_SC.weights
+            );
+        }
+    }
+
+    #[test]
+    fn ensure_only_touches_the_fetcher_when_download_is_needed() {
+        // 抓得住：英文环境/系统已有字体时**仍然调了下载器**（= 偷跑网络请求）；
+        // 也抓得住下载失败被吞掉（错误必须原样透出）。
+        // 抓不住：真实现的网络行为（本 crate 没有网络实现，这正是不联网的证据）。
+        let idle = FakeFetcher::new(Ok(vec![1, 2, 3]));
+        assert_eq!(ensure(Strategy::NotNeeded, &idle), Ok(Fetched::NothingToDo));
+        assert_eq!(
+            ensure(Strategy::System { family: "SimSun" }, &idle),
+            Ok(Fetched::AlreadySystem { family: "SimSun" })
+        );
+        assert_eq!(ensure(Strategy::Unprobeable, &idle), Ok(Fetched::Unknown));
+        assert_eq!(idle.calls.get(), 0, "这三种情况都不许联网");
+
+        let ok = FakeFetcher::new(Ok(vec![9; 4]));
+        assert_eq!(
+            ensure(Strategy::NeedsDownload(&NOTO_SANS_SC), &ok),
+            Ok(Fetched::Downloaded(vec![9; 4]))
+        );
+        assert_eq!(ok.calls.get(), 1);
+        assert_eq!(ok.seen.get(), Some("Noto Sans SC"));
+
+        let broken = FakeFetcher::new(Err(FetchError::Network("超时".to_owned())));
+        assert_eq!(
+            ensure(Strategy::NeedsDownload(&NOTO_SANS_SC), &broken),
+            Err(FetchError::Network("超时".to_owned()))
+        );
+    }
+
+    #[test]
+    fn strategy_describe_is_one_line_for_every_case() {
+        // 抓得住：日志片段里混进换行（启动日志是按行解析的）。
+        // 抓不住：这些片段是否真的被打印（app-iced 的启动路径在那边测）。
+        let cases = [
+            Strategy::NotNeeded,
+            Strategy::System { family: "SimSun" },
+            Strategy::NeedsDownload(&NOTO_SANS_SC),
+            Strategy::Unprobeable,
+        ];
+        for case in cases {
+            let line = case.describe();
+            assert_eq!(line.lines().count(), 1, "{line}");
+            assert!(line.starts_with("cjk="), "{line}");
+        }
+        assert_eq!(Strategy::NotNeeded.describe(), "cjk=not-needed");
+        assert_eq!(Strategy::Unprobeable.describe(), "cjk=unprobeable");
+    }
+}
diff --git a/crates/i18n/src/lang.rs b/crates/i18n/src/lang.rs
new file mode 100644
index 0000000..a38fcc0
--- /dev/null
+++ b/crates/i18n/src/lang.rs
@@ -0,0 +1,387 @@
+//! 语言与系统 locale 探测（D28 前半）。
+//!
+//! ## 判据只有两条
+//!
+//! 1. **中文环境**（`zh*` 任意变体）→ [`Lang::ZhCn`]；
+//! 2. **其它一切**（`en*`、`ja*`、`fr*`、`C`、`POSIX`、变量缺失、解析不了）→ [`Lang::En`]。
+//!
+//! 「其它一切 → 英文」不是偷懒：D28 的原话是「纯英文环境不用管」，而把 ja/fr/de 猜成中文才是真错
+//! （会连带触发中文字体下载）。宁可给一个英文界面，也不给一个语种错误的中文界面。
+//!
+//! ## 为什么 locale 源要能注入
+//!
+//! [`detect`] 的形状是 `detect(&dyn LocaleSource)`，[`EnvLocale`] 只是其中一个实现。这样
+//! **单测不依赖跑测试那台机器的 locale**（真值表测试在 [`lang`] 自己的 `tests` 里跑固定输入），
+//! 后续 mission 加「Win32 `GetUserDefaultLocaleName`」或「读配置里的 `ui.language`」也只是再实现一遍
+//! 这个 trait。
+//!
+//! ## 优先级（[`resolve`]）
+//!
+//! **`ui.language` 显式值 > 平台源 > POSIX 环境变量 > 英文**。本 crate 只有 [`EnvLocale`]
+//! 一个具体实现——平台真值源（Windows 注册表那一路）在 UI 壳层，因为读注册表要开子进程，
+//! 而本 crate 的纪律是不碰外部世界。
+//!
+//! ## 诚实边界（抓得住什么 / 抓不住什么）
+//!
+//! - **抓得住**：环境变量字符串 → 语言的映射（含 `zh_CN.UTF-8` / `zh-Hans-CN` / 大小写 / 修饰符）；
+//!   变量优先级（`LC_ALL` > `LC_MESSAGES` > `LANG`）；[`resolve`] 的四级优先级；
+//! - **抓不住**：**Windows 上这三个变量通常都不存在**——那条路的真值源是
+//!   `crates/app-iced/src/platform/locale.rs`（`reg.exe` 读注册表，零 FFI），
+//!   它不在本 crate 里（本 crate 零依赖、不 spawn 进程）。所以「Windows 上拿不到语言」
+//!   这件事只在**没有接线平台源**时成立，接线后由 `resolve` 的二级兜住。
+//!   配置里的 `ui.language` 读取属于设置层接线（本 crate 只提供 [`Lang::from_setting`] 与
+//!   [`resolve`] 的形状）。
+
+use std::env;
+
+use crate::catalog::Catalog;
+
+/// 界面语言。目前只有中英两套（D28 的「至少 zh-CN / en-US」）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
+pub enum Lang {
+    /// 英文（默认；未知 locale 也落在这里）。
+    En,
+    /// 简体中文。
+    ZhCn,
+}
+
+impl Lang {
+    /// 全部语言（顺序即设置页下拉框的顺序）。
+    pub const ALL: &'static [Lang] = &[Lang::En, Lang::ZhCn];
+
+    /// BCP-47 标签（日志 / 字体请求里用；`zh-CN` 是本 crate 唯一的中文标识）。
+    #[must_use]
+    pub const fn tag(self) -> &'static str {
+        match self {
+            Lang::En => "en",
+            Lang::ZhCn => "zh-CN",
+        }
+    }
+
+    /// 配置值（`core::setting::keys::LANGUAGES` 的同一份词表）。
+    #[must_use]
+    pub const fn setting_value(self) -> &'static str {
+        match self {
+            Lang::En => "en_us",
+            Lang::ZhCn => "zh_cn",
+        }
+    }
+
+    /// 解析**配置值**（严格）：只认 [`Lang::setting_value`] 那两个字符串。
+    ///
+    /// 与宽松的 [`Lang::from_locale`] 分工明确：配置是我们自己写进去的，写错就该暴露（`None` 让设置层
+    /// 报错），而不是悄悄换成别的语言；系统 locale 是别人给的，只能尽量理解。
+    #[must_use]
+    pub fn from_setting(value: &str) -> Option<Lang> {
+        Lang::ALL
+            .iter()
+            .copied()
+            .find(|lang| lang.setting_value() == value)
+    }
+
+    /// 解析 **locale / 语言标签**（宽松）：`zh`、`zh_CN.UTF-8`、`zh-Hans-CN`、`ZH_cn` 都是中文。
+    ///
+    /// 只看**主语言子标签**：`zh-TW` / `zh-Hant` 也归 [`Lang::ZhCn`]——仓内只有一套中文目录，
+    /// 繁体用户看简体比看英文更有用；真要繁体得加第三套目录（见 `bridge` 的上游约定）。
+    #[must_use]
+    pub fn from_locale(tag: &str) -> Lang {
+        let trimmed = tag.trim();
+        // `zh_CN.UTF-8@euro`：codeset 与修饰符与语种无关，先切掉。
+        let without_codeset = trimmed.split('.').next().unwrap_or("");
+        let without_modifier = without_codeset.split('@').next().unwrap_or("");
+        let primary = without_modifier
+            .split(['-', '_'])
+            .next()
+            .unwrap_or("")
+            .to_ascii_lowercase();
+
+        if primary == "zh" {
+            Lang::ZhCn
+        } else {
+            Lang::En
+        }
+    }
+
+    /// 本语言的消息目录。
+    #[must_use]
+    pub const fn catalog(self) -> Catalog {
+        Catalog::of(self)
+    }
+}
+
+/// 没有任何 locale 信息时的落点（D28：纯英文环境不用管）。
+impl Default for Lang {
+    fn default() -> Self {
+        Lang::En
+    }
+}
+
+/// locale 的来源。实现方负责回答「这台机器说哪种语言」。
+pub trait LocaleSource {
+    /// 原始 locale 标签（`None` = 取不到，不是「英文」的断言）。
+    fn locale(&self) -> Option<String>;
+
+    /// 这个源在启动日志里的名字（`registry` / `env` / …）。默认 `injected`（测试用）。
+    fn label(&self) -> &'static str {
+        "injected"
+    }
+}
+
+/// [`Detection::origin`]：结论来自 `ui.language` 的显式值。
+pub const ORIGIN_SETTING: &str = "setting";
+/// [`Detection::origin`]：结论来自环境变量（[`EnvLocale`]）。
+pub const ORIGIN_ENV: &str = "env";
+/// [`Detection::origin`]：一个源都没取到，落到默认英文。
+pub const ORIGIN_DEFAULT: &str = "default";
+
+/// 进程环境变量式 locale 源（POSIX 语义；Windows 上基本取不到，见模块文档）。
+#[derive(Debug, Clone, Copy, Default)]
+pub struct EnvLocale;
+
+impl LocaleSource for EnvLocale {
+    fn locale(&self) -> Option<String> {
+        // POSIX 优先级：LC_ALL > LC_MESSAGES > LANG。空串按「没设置」处理。
+        ["LC_ALL", "LC_MESSAGES", "LANG"]
+            .iter()
+            .find_map(|name| env::var(name).ok().filter(|value| !value.trim().is_empty()))
+    }
+
+    fn label(&self) -> &'static str {
+        ORIGIN_ENV
+    }
+}
+
+/// 探测结论（`raw` 与 `origin` 一起带出来，是为了日志能解释「为什么是英文」）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Detection {
+    /// 结论。
+    pub lang: Lang,
+    /// 原始 locale 标签（`None` = 一个源都没取到）。
+    pub raw: Option<String>,
+    /// 结论的来源（`setting` / 平台源自己的 [`LocaleSource::label`] / `env` / `default`）。
+    pub origin: &'static str,
+}
+
+impl Detection {
+    /// 一行日志（`lang=zh-CN locale=zh-CN source=registry` / `lang=en locale=<未设置> source=default`）。
+    #[must_use]
+    pub fn describe(&self) -> String {
+        format!(
+            "lang={} locale={} source={}",
+            self.lang.tag(),
+            self.raw.as_deref().unwrap_or("<未设置>"),
+            self.origin
+        )
+    }
+}
+
+/// 用给定来源探测语言。
+#[must_use]
+pub fn detect(source: &dyn LocaleSource) -> Detection {
+    match source.locale() {
+        Some(raw) => Detection {
+            lang: Lang::from_locale(&raw),
+            raw: Some(raw),
+            origin: source.label(),
+        },
+        None => Detection {
+            lang: Lang::En,
+            raw: None,
+            origin: ORIGIN_DEFAULT,
+        },
+    }
+}
+
+/// 用进程环境变量探测语言。
+#[must_use]
+pub fn detect_env() -> Detection {
+    detect(&EnvLocale)
+}
+
+/// 全量优先级：**`ui.language` 显式值 > 平台源 > POSIX 环境变量 > 英文**。
+///
+/// - `setting`：配置里 `ui.language` 的原文（`zh_cn` / `en_us`）。给了但不认识 → **跳过**
+///   （当作「没配」继续往下走，而不是把它猜成某种语言）；
+/// - `platform`：平台真值源（Windows 上是 `app-iced::platform::locale` 读注册表；其它平台没有）；
+/// - `env`：`LC_ALL > LC_MESSAGES > LANG`（[`EnvLocale`]）；
+/// - 都不给 → [`Lang::En`]，`origin = default`。
+///
+/// 这正是 D28 要的顺序：**用户手选的**压过系统，系统压过环境变量，都没有就英文。
+#[must_use]
+pub fn resolve(
+    setting: Option<&str>,
+    platform: &dyn LocaleSource,
+    env: &dyn LocaleSource,
+) -> Detection {
+    if let Some(value) = setting {
+        if let Some(lang) = Lang::from_setting(value) {
+            return Detection {
+                lang,
+                raw: Some(value.to_owned()),
+                origin: ORIGIN_SETTING,
+            };
+        }
+    }
+
+    let from_platform = detect(platform);
+    if from_platform.raw.is_some() {
+        return from_platform;
+    }
+
+    detect(env)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    struct Fixed(Option<&'static str>);
+
+    impl LocaleSource for Fixed {
+        fn locale(&self) -> Option<String> {
+            self.0.map(str::to_owned)
+        }
+    }
+
+    #[test]
+    fn locale_truth_table() {
+        // 抓得住：主语言子标签的解析（分隔符 / 大小写 / codeset / 修饰符 / 变体）。
+        // 抓不住：这些字符串是否真的是这台机器的 locale——真值来自 LocaleSource 实现。
+        let zh = [
+            "zh",
+            "zh_CN",
+            "zh_CN.UTF-8",
+            "zh-CN",
+            "zh-Hans-CN",
+            "zh_hans_cn",
+            "ZH_cn",
+            "  zh_TW  ",
+            "zh_CN.GB18030@euro",
+        ];
+        for tag in zh {
+            assert_eq!(Lang::from_locale(tag), Lang::ZhCn, "{tag}");
+        }
+
+        let en = [
+            "",
+            "C",
+            "POSIX",
+            "en",
+            "en_US.UTF-8",
+            "en-GB",
+            "ja_JP.UTF-8",
+            "fr_FR@euro",
+            "de",
+            // 不是中文但含 zh 之外的字：必须落英文，不许猜成中文
+            "zhuang",
+        ];
+        for tag in en {
+            assert_eq!(Lang::from_locale(tag), Lang::En, "{tag}");
+        }
+    }
+
+    #[test]
+    fn detect_falls_back_to_english_without_a_locale() {
+        // 抓得住：取不到 locale 时**不 panic、不猜中文**（D28 的「纯英文环境不用管」）。
+        // 抓不住：Windows 上「环境变量取不到」是否等于用户真的说英文——那是平台源的活
+        // （`app-iced::platform::locale`），见下面 resolve 的优先级测试。
+        let detection = detect(&Fixed(None));
+        assert_eq!(detection.lang, Lang::En);
+        assert_eq!(detection.raw, None);
+        assert_eq!(detection.origin, ORIGIN_DEFAULT);
+        assert_eq!(
+            detection.describe(),
+            "lang=en locale=<未设置> source=default"
+        );
+        assert_eq!(Lang::default(), Lang::En);
+    }
+
+    #[test]
+    fn detect_uses_the_injected_source_verbatim() {
+        // 抓得住：探测结论确实来自注入源（不会被本机环境变量污染），且 origin 取自源自报的名字。
+        // 抓不住：EnvLocale 到底读了哪几个变量（那条路径只能靠人工/集成测试看日志）。
+        let detection = detect(&Fixed(Some("zh_CN.UTF-8")));
+        assert_eq!(detection.lang, Lang::ZhCn);
+        assert_eq!(detection.raw.as_deref(), Some("zh_CN.UTF-8"));
+        assert_eq!(detection.origin, "injected");
+        assert_eq!(
+            detection.describe(),
+            "lang=zh-CN locale=zh_CN.UTF-8 source=injected"
+        );
+        assert_eq!(EnvLocale.label(), "env");
+    }
+
+    #[test]
+    fn resolve_priority_is_setting_then_platform_then_env_then_english() {
+        // 抓得住：四级优先级的顺序本身（用户手选压过系统，系统压过环境变量，都没有才英文）；
+        //         以及「配置值不认识时不当成任何一种语言，继续往下走」。
+        // 抓不住：这些源在真机上到底读到什么（平台源的真机行为在 app-iced 侧测）。
+        struct Named(&'static str, Option<&'static str>);
+
+        impl LocaleSource for Named {
+            fn locale(&self) -> Option<String> {
+                self.1.map(str::to_owned)
+            }
+            fn label(&self) -> &'static str {
+                self.0
+            }
+        }
+
+        let registry_zh = Named("registry", Some("zh-CN"));
+        let env_en = Named("env", Some("en_US.UTF-8"));
+        let nothing = Named("registry", None);
+
+        // ① 配置显式值压过一切
+        let detection = resolve(Some("en_us"), &registry_zh, &env_en);
+        assert_eq!(
+            (detection.lang, detection.origin),
+            (Lang::En, ORIGIN_SETTING)
+        );
+        // ② 没配置（或配置不认识）→ 平台源
+        for setting in [None, Some("zh-CN"), Some("")] {
+            let detection = resolve(setting, &registry_zh, &env_en);
+            assert_eq!(
+                (detection.lang, detection.raw.as_deref(), detection.origin),
+                (Lang::ZhCn, Some("zh-CN"), "registry"),
+                "setting={setting:?}"
+            );
+        }
+        // ③ 平台源没有 → 环境变量
+        let detection = resolve(None, &nothing, &env_en);
+        assert_eq!(
+            (detection.lang, detection.origin),
+            (Lang::En, "env"),
+            "环境变量说是英文，但来源必须是 env"
+        );
+        // ④ 全没有 → 英文 + default
+        let detection = resolve(None, &nothing, &Named("env", None));
+        assert_eq!(
+            (detection.lang, detection.origin),
+            (Lang::En, ORIGIN_DEFAULT)
+        );
+    }
+
+    #[test]
+    fn setting_values_match_the_config_vocabulary() {
+        // 抓得住：本 crate 的配置词表被改动（改名会让已落盘的 ui.language 读不出来）。
+        // 抓不住：`core::setting::keys::LANGUAGES` 那边先改了——本 crate 不依赖 core（零依赖纪律），
+        // 所以这条只能靠接线 mission 写一条跨 crate 的 pin 测试，或让 core 反向引用这份词表。
+        let values = Lang::ALL
+            .iter()
+            .map(|lang| lang.setting_value())
+            .collect::<Vec<_>>();
+        assert_eq!(values, vec!["en_us", "zh_cn"]);
+        assert_eq!(Lang::from_setting("zh_cn"), Some(Lang::ZhCn));
+        assert_eq!(Lang::from_setting("en_us"), Some(Lang::En));
+    }
+
+    #[test]
+    fn setting_parsing_is_strict_where_locale_parsing_is_lenient() {
+        // 抓得住：宽松解析被误用到配置值上（`zh-CN` 是合法 locale 但不是合法配置值）。
+        // 抓不住：有人把非法值直接塞进配置（那是设置层的 schema 校验与该键的 enumeration 约束）。
+        for bogus in ["zh-CN", "ZH_CN", "zh", "", "en"] {
+            assert_eq!(Lang::from_setting(bogus), None, "{bogus}");
+        }
+        assert_eq!(Lang::from_locale("zh-CN"), Lang::ZhCn);
+    }
+}
diff --git a/crates/i18n/src/lib.rs b/crates/i18n/src/lib.rs
new file mode 100644
index 0000000..55c194e
--- /dev/null
+++ b/crates/i18n/src/lib.rs
@@ -0,0 +1,45 @@
+//! # unlucky-i18n · 国际化地基（D28）
+//!
+//! 本 crate 只做**地基**，不接任何页面：语言探测、两套消息目录、缺译诊断、中文字体策略、
+//! 以及「core 的中文状态串怎么进 UI」的契约。页面侧接线的 mission 用它，而不是各自硬编码英文
+//! （先硬编码再全量重写就是本 crate 要避免的那条路）。
+//!
+//! | 模块 | 职责 | 不负责 |
+//! |---|---|---|
+//! | [`lang`] | `Lang`（en / zh-CN）+ locale 探测（源可注入）+ **四级优先级** [`lang::resolve`] | 读注册表 / 读配置 / spawn 进程 |
+//! | [`choice`] | `LangChoice`（跟随系统 / 手选）：设置页那一档 + 它到生效语言的映射 | 落盘（那是 `presenter::settings_bridge`） |
+//! | [`catalog`] | `Key` 枚举 + 中英两套常量表 + 取词 / 占位符渲染 + 缺译诊断 | 排版、字号、断行 |
+//! | [`font`] | 中文环境扫系统 CJK 字体的**判据** + 缺字体时的「需下载」信号 + 注入式下载器接口 | 联网、写文件、装字体 |
+//! | [`bridge`] | core / presenter 的状态串 → `Key` 的**示例契约**（文案边界规则全文在这里） | 改 core 的产出 |
+//!
+//! 语言从哪来的优先级写在 [`lang::resolve`]：**`ui.language` 显式值 > 平台源 > POSIX 环境变量 > 英文**。
+//! 平台源（Windows 上 `reg.exe` 读注册表，零 FFI）在 UI 壳层实现并注入——本 crate 不认平台。
+//!
+//! ## 三条硬规矩（细则见 [`bridge`]）
+//!
+//! 1. **一句话 = 一个 key**。UI 侧不得把片段拼成一句话，尤其不得拼中文：
+//!    `"Launch failed · exit0 静默失败"` 这种混排就是拼接的后果。带变量的句子用 `{name}` 占位符，
+//!    由 [`catalog::Catalog::render`] 统一替换。
+//! 2. **core 的中文串不是文案**。core / presenter 里的中文状态串（`原版` / `静默失败（…）`）只用于
+//!    日志与 CLI；UI 要么走结构化出口（枚举）映射到 key，要么走 [`bridge::key_of_legacy_status`] 的
+//!    过渡表。**任何情况下都不许把未知中文串直接画到界面上。**
+//! 3. **英文环境零中文负担**（D28 原话）：`Lang::En` 下不要求任何中文字体、不触发任何下载；
+//!    判据在 [`font::decide`]，是纯函数，可脱机单测。
+//!
+//! ## 与别处的关系
+//!
+//! - **不依赖 iced / slint / presenter / core**：`cargo tree -p unlucky-i18n --edges normal` 只应打印它自己。
+//!   系统字体扫描由 UI 壳层做（iced 版在 `crates/app-iced/src/fonts/cjk.rs`），扫出来的族名喂给
+//!   [`font::decide`]；
+//! - 配置里的 `ui.language` 允许值 `zh_cn` / `en_us`（见 `core::setting::keys::LANGUAGES`）与
+//!   [`lang::Lang::setting_value`] 必须是同一份词表，由 [`lang`] 的 pin 测试守门。
+
+pub mod bridge;
+pub mod catalog;
+pub mod choice;
+pub mod font;
+pub mod lang;
+
+pub use catalog::{Catalog, Key};
+pub use choice::LangChoice;
+pub use lang::Lang;
diff --git a/crates/palette-extract/Cargo.toml b/crates/palette-extract/Cargo.toml
new file mode 100644
index 0000000..1177c1f
--- /dev/null
+++ b/crates/palette-extract/Cargo.toml
@@ -0,0 +1,32 @@
+[package]
+name = "unlucky-palette-extract"
+description = "配色取色的解码适配层（D40 第 2 层）：图片路径/字节 → RGBA 像素 → unlucky-design 的种子"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+publish.workspace = true
+
+# 分层纪律（D40）：`crates/design` 保持零第三方依赖，**图片解码只能在这里**。
+# 本 crate 的职责边界很窄：解码 + 限尺寸 + 把像素交给 design，不碰 UI、不碰设置、不碰壁纸探测。
+[dependencies]
+unlucky-design = { path = "../design", version = "0.2" }
+
+# 只开两个编解码器（MIT OR Apache-2.0，deny.toml 白名单内）：
+# - png：启动器背景图最常见的无损格式，也是截图通道用的格式；
+# - jpeg：Windows 壁纸与用户照片的绝对主力（不引它等于「取色对一半用户不可用」）；
+# - bmp：Windows 壁纸的真会出现（M73 的探测只读注册表/`.theme` 里的路径，**不筛扩展名**），
+#   而 `image` 的 `bmp` 是独立 feature 且**无额外传递依赖**（`bmp = []`），代价≈0。
+# 不开 `default-features`（默认会拖进 rayon + avif/ravif + webp + tiff + gif + exr + qoi
+# 等一整套编码器，体积与审计面都翻倍）；不开 webp/tiff/avif 是因为 M73 拿到的格式只有
+# png/jpg/bmp 三类，等真有人需要再单开一个 feature。
+image = { workspace = true, default-features = false, features = [
+    "png",
+    "jpeg",
+    "bmp",
+] }
+
+[lints]
+workspace = true
diff --git a/crates/palette-extract/src/lib.rs b/crates/palette-extract/src/lib.rs
new file mode 100644
index 0000000..ab38838
--- /dev/null
+++ b/crates/palette-extract/src/lib.rs
@@ -0,0 +1,217 @@
+//! # 配色取色的解码适配层（D40 三层里的第 2 层）
+//!
+//! 本 crate 只做一件事：**图片路径 / 字节 → RGBA 像素 → `unlucky_design` 的种子色**。
+//!
+//! ```no_run
+//! use unlucky_palette_extract::{input, load};
+//! use unlucky_design::palette::{resolve_source, CardKey};
+//! use unlucky_design::color::SchemeFlavor;
+//!
+//! // ① 读用户设的启动器背景图（失败不 panic，失败状态会原样进 Provenance）
+//! let background = load("D:/Pictures/bg.png");
+//! let (scheme, provenance) = resolve_source(
+//!     Some(input(&background)),
+//!     None,                       // ② 桌面壁纸：本次不启用
+//!     Some(CardKey::Sky),         // ③ 用户选中的色卡 = 回落目标
+//!     SchemeFlavor::Light,
+//! );
+//! println!("{:?} / {:?}", provenance.level, provenance.hint_key());
+//! ```
+//!
+//! ## 为什么解码要单独成 crate（D40）
+//!
+//! `crates/design` 的卖点是「零第三方依赖」（`cargo tree -p unlucky-design` 单行），而图片解码
+//! 必然拉依赖。把 `image` 塞进 design 会让那句卖点变成假话，所以：
+//!
+//! | 层 | crate | 依赖 | 职责 |
+//! |---|---|---|---|
+//! | 1 纯数学 | `unlucky-design` | 无 | 像素/种子 → 49 角色方案、色卡、回落决策、对比度收敛 |
+//! | 2 解码 | **本 crate** | `image`（png + jpeg） | 路径/字节 → RGBA 像素；限尺寸；错误分类 |
+//! | 3 调用侧 | 后续 appearance/settings mission | UI 框架 | 拿路径、把 `Provenance` 变文案 |
+//!
+//! ## 为什么选 `image`（而不是 `png` + `zune-jpeg` 各接一个）
+//!
+//! 1. **仓库里已经有它**：`crates/app-iced` 的截图通道用 `image`（png）。同一份依赖只编译一次，
+//!    版本由 workspace 的 `image = "0.25"` 统一钉住，`cargo deny` 的许可面不新增条目。
+//! 2. **格式嗅探现成**：`ImageReader::with_guessed_format()` 按魔数判格式，用户把 `.jpg`
+//!    改成 `.png` 也能读（壁纸文件被改名的概率不低）。
+//! 3. **有 `Limits`**：可以在解码前拒绝「头里写着 40000×40000」的 PNG（压缩炸弹），
+//!    单接 `png` crate 也要自己写这层判断。
+//!
+//! 许可：`image` 是 `MIT OR Apache-2.0`，在 `deny.toml` 白名单内（`[licenses].allow`）。
+//!
+//! ## 体积影响（`image` 只开 png + jpeg + bmp，关掉 default-features）
+//!
+//! 拉进的传递依赖就这几个：`png`（+ `fdeflate`/`miniz_oxide`/`crc32fast`/`flate2` 已在树里）、
+//! `zune-jpeg` + `zune-core`、`byteorder-lite`、`num-traits`、`moxcms`/`pxfm`（色彩转换）。
+//! `bmp` 是 `image` 的独立 feature 且**不带任何传递依赖**（`bmp = []`），加它只是因为
+//! M73 的 Windows 壁纸探测不筛扩展名、`.bmp` 壁纸真会出现。
+//! 关掉的默认特性里有 `rayon`（省一个线程池）、`avif`/`ravif`（最大的一个，编解码器整套）、
+//! `webp`/`tiff`/`gif`/`exr`/`qoi`/`hdr`/`dds`/`ff`。实测增量见 M87 报告（`cargo tree` 前后对比）。
+//!
+//! ## 两条硬纪律
+//!
+//! 1. **解码后才交出去**：送进 `unlucky_design` 的像素最多 [`MAX_EDGE`] 边长（默认 256）。
+//!    取色只需要色彩分布，不需要分辨率；一张 4K 壁纸缩到 256×144 后量化结果与全分辨率
+//!    在肉眼层面一致，内存却从 33MB 掉到 147KB。`crates/design` 里还有第二道块平均降采样
+//!    （防御式：直接调 design 的调用方也能拿到有界开销）。
+//! 2. **失败不 panic、不 return 默认色**：解码失败只变成 [`ExtractError`]，
+//!    [`input`] 把它翻成 `ImageInput::Undecodable` 交给 `resolve_source`，
+//!    由后者回落色卡并在 `Provenance` 里留下原因。**不许**在这里「读不到就给个蓝色」。
+
+use std::io::Cursor;
+use std::path::Path;
+
+use unlucky_design::palette::{self, ImageInput, ImageSource, Seed};
+
+/// 交给 `unlucky_design` 前允许的最大边长（像素）。
+///
+/// 256 的依据：量化器自己只采 65536 个点（≈256²），再大的图在 `crates/design` 里也会被
+/// 块平均降采样；提前缩小只是省内存与解码时间。可预测、可测试（见 `tests.rs`）。
+pub const MAX_EDGE: u32 = 256;
+
+/// 解码**之前**允许的图片头尺寸上限。
+///
+/// 4K 壁纸是 3840×2160，8K 是 7680×4320；16384 留出 2 倍余量，同时挡住「头里写着
+/// 40000×40000」的解压炸弹（否则解码器会先按头分配几十 GB）。
+const MAX_SOURCE_EDGE: u32 = 16_384;
+
+/// 解码后的 RGBA8 图像（行主序，`width × height × 4` 字节）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Rgba8 {
+    width: u32,
+    height: u32,
+    pixels: Vec<u8>,
+}
+
+impl Rgba8 {
+    /// 宽（像素）。
+    pub fn width(&self) -> u32 {
+        self.width
+    }
+
+    /// 高（像素）。
+    pub fn height(&self) -> u32 {
+        self.height
+    }
+
+    /// 原始 RGBA8 字节（`width × height × 4`）。
+    pub fn pixels(&self) -> &[u8] {
+        &self.pixels
+    }
+
+    /// 包成 `unlucky_design` 的借用视图（零拷贝，供 `resolve_source` 用）。
+    pub fn view(&self) -> ImageSource<'_> {
+        ImageSource {
+            pixels: &self.pixels,
+            width: self.width,
+            height: self.height,
+        }
+    }
+}
+
+/// 解码/取色失败的原因。
+#[derive(Debug)]
+pub enum ExtractError {
+    /// 读文件失败（不存在、无权限、被占用）。
+    Io(std::io::Error),
+    /// 解码失败（格式不认识、文件截断、超出 [`MAX_SOURCE_EDGE`] 限制）。
+    Decode(image::ImageError),
+    /// 解码成功但取色失败（图太小、全透明、彩度不足……原因在 `unlucky_design`）。
+    Palette(palette::Failure),
+}
+
+impl std::fmt::Display for ExtractError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            ExtractError::Io(error) => write!(f, "读取图片失败：{error}"),
+            ExtractError::Decode(error) => write!(f, "解码图片失败：{error}"),
+            ExtractError::Palette(failure) => {
+                write!(f, "取色失败（{}）：{failure:?}", failure.code())
+            }
+        }
+    }
+}
+
+impl std::error::Error for ExtractError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            ExtractError::Io(error) => Some(error),
+            ExtractError::Decode(error) => Some(error),
+            ExtractError::Palette(_) => None,
+        }
+    }
+}
+
+/// 从内存字节解码（格式按魔数嗅探，不看扩展名）。
+pub fn decode_bytes(bytes: &[u8]) -> Result<Rgba8, ExtractError> {
+    let reader = image::ImageReader::new(Cursor::new(bytes))
+        .with_guessed_format()
+        .map_err(ExtractError::Io)?;
+    finish(reader)
+}
+
+/// 从文件路径解码（格式按魔数嗅探，不看扩展名）。
+pub fn load(path: impl AsRef<Path>) -> Result<Rgba8, ExtractError> {
+    let reader = image::ImageReader::open(path).map_err(ExtractError::Io)?;
+    let reader = reader.with_guessed_format().map_err(ExtractError::Io)?;
+    finish(reader)
+}
+
+/// 路径 → 种子色（解码 + 量化一步到位；只需要 bool「能不能取」时用 [`input`]）。
+pub fn extract_seed(path: impl AsRef<Path>) -> Result<Seed, ExtractError> {
+    seed_from_rgba8(&load(path)?)
+}
+
+/// 字节 → 种子色（与 [`extract_seed`] 同一条路径，测试与「内存里的图」用）。
+pub fn seed_from_bytes(bytes: &[u8]) -> Result<Seed, ExtractError> {
+    seed_from_rgba8(&decode_bytes(bytes)?)
+}
+
+fn seed_from_rgba8(image: &Rgba8) -> Result<Seed, ExtractError> {
+    palette::analyze_rgba(image.pixels(), image.width(), image.height())
+        .map_err(ExtractError::Palette)
+}
+
+/// 把「读到了 / 没读到」翻成 `resolve_source` 的输入。
+///
+/// 这是本 crate 与编排层之间**唯一**的接线点：`Err` → `ImageInput::Undecodable`
+/// （回落链会据此写 `Skip::Undecodable` 而不是 `Skip::Absent`——两者对用户的含义不同：
+/// 「你没设背景图」 vs 「你的背景图坏了」）。
+pub fn input<'a>(loaded: &'a Result<Rgba8, ExtractError>) -> ImageInput<'a> {
+    match loaded {
+        Ok(image) => ImageInput::Pixels(image.view()),
+        Err(_) => ImageInput::Undecodable,
+    }
+}
+
+fn finish<R: std::io::BufRead + std::io::Seek>(
+    mut reader: image::ImageReader<R>,
+) -> Result<Rgba8, ExtractError> {
+    let mut limits = image::Limits::default();
+    limits.max_image_width = Some(MAX_SOURCE_EDGE);
+    limits.max_image_height = Some(MAX_SOURCE_EDGE);
+    reader.limits(limits);
+
+    let decoded = reader.decode().map_err(ExtractError::Decode)?;
+    let rgba = decoded.to_rgba8();
+    let (width, height) = (rgba.width(), rgba.height());
+    let scaled = if width.max(height) > MAX_EDGE {
+        // 等比缩到长边 = MAX_EDGE。`thumbnail` 是整数快速采样，对取色（只关心色彩分布）
+        // 足够，且比 Lanczos 快一个量级。
+        let factor = f64::from(MAX_EDGE) / f64::from(width.max(height));
+        let target_width = ((f64::from(width) * factor).round() as u32).max(1);
+        let target_height = ((f64::from(height) * factor).round() as u32).max(1);
+        image::imageops::thumbnail(&rgba, target_width, target_height)
+    } else {
+        rgba
+    };
+    Ok(Rgba8 {
+        width: scaled.width(),
+        height: scaled.height(),
+        pixels: scaled.into_raw(),
+    })
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/palette-extract/src/tests.rs b/crates/palette-extract/src/tests.rs
new file mode 100644
index 0000000..dc17050
--- /dev/null
+++ b/crates/palette-extract/src/tests.rs
@@ -0,0 +1,189 @@
+//! 解码适配层的单测：真 PNG / 真 JPEG 字节进，种子或**具体错误**出。
+//!
+//! 这里刻意不 mock 解码器：本 crate 存在的意义就是「真解码」，mock 掉它等于不测。
+//! 测试用内存里的字节（`encode_*` 现造），不依赖任何外部素材文件。
+
+use std::io::Cursor;
+
+use super::*;
+use image::{DynamicImage, ImageFormat, Rgba, RgbaImage};
+
+fn solid_image(width: u32, height: u32, rgb: [u8; 3]) -> RgbaImage {
+    RgbaImage::from_pixel(width, height, Rgba([rgb[0], rgb[1], rgb[2], 0xFF]))
+}
+
+fn encode_png(image: &RgbaImage) -> Vec<u8> {
+    let mut bytes = Cursor::new(Vec::new());
+    DynamicImage::ImageRgba8(image.clone())
+        .write_to(&mut bytes, ImageFormat::Png)
+        .expect("PNG 编码应当成功");
+    bytes.into_inner()
+}
+
+fn encode_jpeg(image: &RgbaImage, quality: u8) -> Vec<u8> {
+    let mut bytes = Cursor::new(Vec::new());
+    let mut encoder = image::codecs::jpeg::JpegEncoder::new_with_quality(&mut bytes, quality);
+    encoder
+        .encode_image(&DynamicImage::ImageRgba8(image.clone()))
+        .expect("JPEG 编码应当成功");
+    bytes.into_inner()
+}
+
+#[test]
+fn solid_png_keeps_the_exact_seed_colour() {
+    let png = encode_png(&solid_image(32, 32, [0xC0, 0x39, 0x2B]));
+    let seed = seed_from_bytes(&png).expect("砖红纯色图应当有种子");
+    // 32×32 不触发缩放；design 侧对纯色图做桶内原值平均 → 逐通道相等。
+    assert_eq!(seed.color.r, 0xC0);
+    assert_eq!(seed.color.g, 0x39);
+    assert_eq!(seed.color.b, 0x2B);
+    assert!(seed.chroma > 8.0);
+}
+
+#[test]
+fn jpeg_decoding_is_wired_up() {
+    // 只验证「jpeg feature 真的接上了」：JPEG 会动色，只要求色相别跑偏太多。
+    let jpeg = encode_jpeg(&solid_image(48, 48, [0xC0, 0x39, 0x2B]), 92);
+    let seed = seed_from_bytes(&jpeg).expect("JPEG 应当能解码并取色");
+    assert!(seed.chroma > 8.0, "彩度 {}", seed.chroma);
+    assert!(
+        (seed.hue - 30.0).abs() < 25.0,
+        "砖红的 CAM16 色相应当在 30° 附近，实际 {}",
+        seed.hue
+    );
+}
+
+#[test]
+fn extension_is_ignored_and_format_is_sniffed() {
+    // 用户把 .jpg 改成 .png 的情况很常见：按魔数判断，不按扩展名。
+    let jpeg = encode_jpeg(&solid_image(16, 16, [0x2E, 0x7D, 0x4F]), 95);
+    let decoded = decode_bytes(&jpeg).expect("魔数嗅探应当认得 JPEG");
+    assert_eq!((decoded.width(), decoded.height()), (16, 16));
+}
+
+#[test]
+fn bmp_is_supported() {
+    // M73 的 Windows 壁纸探测不筛扩展名，`.bmp` 壁纸会真的出现在取色路径上。
+    // BMP 编码不是无损于色的（24 bit 存 RGB，这里是 32 bit Rgba），所以逐通道比对即可。
+    let mut bytes = Cursor::new(Vec::new());
+    DynamicImage::ImageRgba8(solid_image(32, 32, [0xB2, 0x3A, 0x48]))
+        .write_to(&mut bytes, ImageFormat::Bmp)
+        .expect("BMP 编码应当成功");
+    let seed = seed_from_bytes(&bytes.into_inner()).expect("BMP 应当能解码并取色");
+    assert_eq!(
+        seed.color,
+        unlucky_design::color::Color::rgb(0xB2, 0x3A, 0x48)
+    );
+    assert!(seed.chroma > 8.0);
+}
+
+#[test]
+fn garbage_bytes_fail_and_map_to_undecodable() {
+    let loaded = decode_bytes(b"this is definitely not an image");
+    assert!(
+        matches!(
+            loaded,
+            Err(ExtractError::Decode(_)) | Err(ExtractError::Io(_))
+        ),
+        "非图片字节应当解码失败"
+    );
+    assert_eq!(input(&loaded), ImageInput::Undecodable);
+}
+
+#[test]
+fn truncated_png_fails_instead_of_returning_half_an_image() {
+    let png = encode_png(&solid_image(64, 64, [0x3C, 0x8D, 0xBC]));
+    let truncated = &png[..png.len() / 2];
+    let loaded = decode_bytes(truncated);
+    assert!(loaded.is_err(), "截断的 PNG 不许当成有效图");
+    assert_eq!(input(&loaded), ImageInput::Undecodable);
+}
+
+#[test]
+fn missing_file_is_an_io_error() {
+    let loaded = load("Z:/definitely/not/here/background.png");
+    match loaded {
+        Err(ExtractError::Io(_)) => {}
+        other => panic!("应当报 IO 错误，实际 {other:?}"),
+    }
+}
+
+#[test]
+fn one_pixel_image_is_reported_as_too_small() {
+    let png = encode_png(&solid_image(1, 1, [0xC0, 0x39, 0x2B]));
+    match seed_from_bytes(&png) {
+        Err(ExtractError::Palette(palette::Failure::TooSmall { width, height })) => {
+            assert_eq!((width, height), (1, 1));
+        }
+        other => panic!("1×1 图应当取色失败，实际 {other:?}"),
+    }
+}
+
+#[test]
+fn gray_png_falls_back_instead_of_inventing_a_colour() {
+    // D40 的反证：灰白图**不许**变成青色。这里必须报低彩度，而不是返回一个种子。
+    let png = encode_png(&solid_image(24, 24, [0xEE, 0xEE, 0xEC]));
+    match seed_from_bytes(&png) {
+        Err(ExtractError::Palette(palette::Failure::LowChroma { chroma, .. })) => {
+            assert!(chroma < 8.0, "彩度 {chroma}");
+        }
+        other => panic!("灰白图应当报低彩度，实际 {other:?}"),
+    }
+}
+
+#[test]
+fn large_image_is_scaled_to_the_max_edge() {
+    let png = encode_png(&solid_image(1024, 512, [0xB2, 0x6A, 0x00]));
+    let decoded = decode_bytes(&png).expect("大图应当解码成功");
+    assert_eq!(decoded.width(), MAX_EDGE);
+    assert_eq!(decoded.height(), MAX_EDGE / 2);
+    assert_eq!(
+        decoded.pixels().len(),
+        (MAX_EDGE * MAX_EDGE / 2 * 4) as usize
+    );
+    // 缩放后仍是那个橙色：取色的结论不该被「缩了多少」改变。
+    let seed = seed_from_rgba8(&decoded).expect("琥珀橙有种子");
+    assert!(seed.chroma > 8.0);
+}
+
+#[test]
+fn absurd_dimensions_are_rejected_before_allocating() {
+    // 头里写着 20000 宽的 PNG：超过 MAX_SOURCE_EDGE，必须在解码前拒掉。
+    let png = encode_png(&solid_image(20_000, 1, [0x3C, 0x8D, 0xBC]));
+    match decode_bytes(&png) {
+        Err(ExtractError::Decode(_)) => {}
+        other => panic!("超限尺寸应当被拒，实际 {other:?}"),
+    }
+}
+
+#[test]
+fn max_edge_stays_within_the_design_sample_budget() {
+    // 结构性防线（复审 r2 要求）：`unlucky_design` 只在「像素数 ≤ MAX_SAMPLES」时才不做块平均。
+    // 当前 256² = 65536 = MAX_SAMPLES，**余量为零**：谁把 MAX_EDGE 调到 512，本适配层交出去的
+    // 缓冲就会超过 design 的采样预算，design 会**在适配层已经缩过之后再叠一层块平均**
+    // （色彩被二次抹平），而这条退化没有任何测试会报错——两个常数此前是各写各的。
+    //
+    // 注意别把这条读成「≤ 预算 ⇒ 种子一定是原图真实颜色」：本适配层的 `thumbnail` 本身就会平均
+    // （400×400 红蓝棋盘在 MAX_EDGE=256 下取到的 `#704070` 也不在原图上）。这条只保证
+    // 「design 侧不再叠第二层平均」，逐像素语义见 `Seed::color` 的文档。
+    let budget = unlucky_design::palette::MAX_SAMPLES;
+    let edge = MAX_EDGE as usize;
+    assert!(
+        edge * edge <= budget,
+        "MAX_EDGE={MAX_EDGE} 的平方（{}）超过 design 的采样预算 {budget}：         调大它之前先读 `unlucky_design::palette::Seed::color` 的文档——超过预算后 design 会在本适配层缩放之上再叠一层块平均",
+        edge * edge
+    );
+}
+
+#[test]
+fn input_borrows_without_copying() {
+    let loaded = decode_bytes(&encode_png(&solid_image(4, 4, [0x67, 0x50, 0xA4])));
+    match input(&loaded) {
+        ImageInput::Pixels(source) => {
+            assert_eq!((source.width, source.height), (4, 4));
+            // 零拷贝：视图指向的就是 `Rgba8` 自己的缓冲。
+            assert_eq!(source.pixels, loaded.as_ref().expect("解码成功").pixels());
+        }
+        ImageInput::Undecodable => panic!("刚解码成功却报了 undecodable"),
+    }
+}
diff --git a/crates/presenter/Cargo.toml b/crates/presenter/Cargo.toml
new file mode 100644
index 0000000..38160c4
--- /dev/null
+++ b/crates/presenter/Cargo.toml
@@ -0,0 +1,28 @@
+[package]
+name = "unlucky-presenter"
+description = "Unlucky-Launcher 的 UI 框架无关宿主层：DTO / 状态 reducer / host 业务装配，Slint 版与 iced 版共用"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+publish.workspace = true
+
+# 零 UI 框架依赖是硬约束（M85 / D26）：本 crate 是 Slint 版（`crates/app`）与 iced 版
+# （`crates/app-iced`）共用的宿主层，任何时候都不得出现 Slint / iced / winit / gtk / egui 等
+# UI 或渲染框架，也不得出现「把窗口属性灌进去」这种绑定代码。
+# 证据命令写在 `crates/app/Cargo.toml` 的注释里（那个文件允许出现框架名，本 crate 的守门
+# 命令本身在自家 grep 范围内会把自己抓出来，所以那两条命令刻意不放在这里）。
+[dependencies]
+# 跨边界 DTO 必须可序列化（AGENTS §6）：事件与快照是 IPC 契约，序列化能力由 derive 钉住。
+serde.workspace = true
+# host 层要读 core 设置/事件里的 JSON 值。
+serde_json.workspace = true
+
+# 边界（01c §5 / D3）：presenter 只经 DTO 消费 core，**不 import core 的领域类型到 DTO 里**。
+# host 是 core 的快照/事件流与本 crate DTO 之间的唯一翻译层，所以它需要 core。
+unlucky-core = { path = "../core", version = "0.2" }
+
+[lints]
+workspace = true
diff --git a/crates/presenter/src/agent.rs b/crates/presenter/src/agent.rs
new file mode 100644
index 0000000..ef0c3cd
--- /dev/null
+++ b/crates/presenter/src/agent.rs
@@ -0,0 +1,311 @@
+//! AI 助手（D16 双形态）的 presenter 门面：视图模型 + 提交/确认 + 裁决审计。
+//!
+//! # 1. 这一层为什么单独存在
+//!
+//! UI 壳（右侧常驻栏 = AGENTRAIL）只做两件事：读 [`AgentRail`] 画、把点击翻成这五个方法。
+//! 会话怎么攒、未读怎么算、YOLO 怎么裁决、审计记什么，全在这里与
+//! [`crate::state::AppState::apply_agent`]，壳里不重复实现——否则两形态（栏 / 页）会各写一套
+//! 而漂移。
+//!
+//! ```text
+//! UI 壳 ──agent_submit/agent_confirm/agent_mark_read──► Presenter ──AgentTransport──► 后端
+//!    ▲                                                     │
+//!    └────────── agent_rail()（只读视图模型）◄──────────────┘  events → AppState::apply
+//! ```
+//!
+//! # 2. 与 UI 壳的契约（签名已定，改名要先报 tower）
+//!
+//! ```text
+//! Presenter::agent_rail(&self) -> &AgentRail
+//! Presenter::agent_submit(&mut self, text: String) -> Result<(), String>
+//! Presenter::agent_mark_read(&mut self)
+//! Presenter::agent_confirm(&mut self, accept: bool)
+//! ```
+//!
+//! # 3. 铁律落点（AGENTS §6）
+//!
+//! - **AI 永不接触账户凭据**：事件里没有凭据字段；文本一律过 [`rail::scrub_text`]（第二道防线）。
+//! - **写配置受 schema 白名单约束**：白名单在 agent 侧工具层，presenter 只负责「把确认问出来」。
+//! - **敏感键分级确认，YOLO 只跳确认且审计照记**：[`Presenter::agent_confirm`] 在 YOLO 下
+//!   一律放行，但**照样**记一条 [`AuditEntry`]（`yolo = true, confirmed = false`）——不静默跳过。
+//!
+//! # 4. 没做的事（P1 再接）
+//!
+//! - 真实后端：本模块只认 [`AgentTransport`] 端口，`rig` 那侧由 host 装配时实现；
+//! - 落盘审计：agent 侧 `brain::exec` → `audit` 才是权威记录，这里的 [`AuditEntry`] 只是
+//!   本进程内、给 UI 看的裁决镜像（`presenter.audit()`）；
+//! - 流式时序：端口是同步返回事件分片的（便于单测），真实实现是异步推流。
+
+use crate::dto::{AppEvent, Sensitivity};
+use crate::prefs::UiPrefs;
+use crate::router::Route;
+use crate::state::AppState;
+
+pub mod mock;
+pub mod rail;
+
+use rail::scrub_text;
+pub use rail::AgentRail;
+
+#[cfg(test)]
+mod tests;
+#[cfg(test)]
+#[path = "agent/tests_red_line.rs"]
+mod tests_red_line;
+
+/// 裁决记录上限（只留最近若干条；权威审计不在这里）。
+pub const MAX_AUDIT_ENTRIES: usize = 256;
+
+/// 一次确认的结局。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ConfirmVerdict {
+    /// 放行（用户点了允许，或 YOLO 自动放行）
+    Approved,
+    /// 拒绝（工具调用会带「用户拒绝」回到模型）
+    Denied,
+}
+
+impl ConfirmVerdict {
+    /// 是否放行。
+    #[must_use]
+    pub fn is_approved(self) -> bool {
+        matches!(self, Self::Approved)
+    }
+}
+
+/// 一条确认裁决的审计记录。
+///
+/// `yolo` 与 `confirmed` 必须分开记：`yolo = true, confirmed = false`（自动放行）与
+/// `yolo = false, confirmed = true`（用户亲手点的允许）在事故复盘里是完全不同的两件事。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AuditEntry {
+    /// 请求 id（与 `AgentEvent::ConfirmRequested` 同一个）
+    pub request_id: String,
+    /// 工具名
+    pub tool: String,
+    /// 敏感等级
+    pub sensitivity: Sensitivity,
+    /// 结局
+    pub verdict: ConfirmVerdict,
+    /// 是否运行在 YOLO 模式
+    pub yolo: bool,
+    /// 是否经过用户确认（YOLO 下恒为 false）
+    pub confirmed: bool,
+}
+
+/// agent 后端端口：presenter 不认 `rig` / 异步运行时的具体类型（依赖方向见 crate 文档）。
+///
+/// 方法同步返回事件分片是刻意的：真实后端在后台线程里跑，事件经
+/// [`crate::dto::Backend::drain_events`] 回流；端口这层只表达「一轮输入会产生哪些事件」，
+/// 这样单测可以不碰定时器与网络。
+pub trait AgentTransport {
+    /// 用户提交一句话。
+    ///
+    /// `history` 是当前 rail 的只读快照（真实后端要靠它拼上下文，mock 靠它算消息下标）。
+    /// 返回的事件分片由 [`Presenter`] 顺序 `apply`；`Err` 表示这一轮根本没起来（不产生事件）。
+    fn submit(&mut self, text: &str, history: &AgentRail) -> Result<Vec<AppEvent>, String>;
+
+    /// 用户对写操作做了决定（`accept = false` 表示拒绝）。
+    fn confirm(&mut self, request_id: &str, accept: bool) -> Vec<AppEvent>;
+}
+
+/// AI 助手的 presenter 门面：持有一份 [`AppState`] 与一个后端端口。
+///
+/// 事件仍走 [`AppState::apply`]（唯一状态变更入口）——[`Presenter::apply`] 只是转发，
+/// 不在这一层另做投影。
+pub struct Presenter {
+    state: AppState,
+    transport: Box<dyn AgentTransport>,
+    audit: Vec<AuditEntry>,
+}
+
+impl std::fmt::Debug for Presenter {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("Presenter")
+            .field("rail", self.agent_rail())
+            .field("audit_len", &self.audit.len())
+            .finish_non_exhaustive()
+    }
+}
+
+impl Presenter {
+    /// 空状态 + 指定后端端口。
+    #[must_use]
+    pub fn new(transport: Box<dyn AgentTransport>) -> Self {
+        Self::with_state(AppState::new(), transport)
+    }
+
+    /// 接管一份已有状态（UI 壳先建 `AppState` 再交给 presenter 时用）。
+    #[must_use]
+    pub fn with_state(state: AppState, transport: Box<dyn AgentTransport>) -> Self {
+        Self {
+            state,
+            transport,
+            audit: Vec::new(),
+        }
+    }
+
+    /// 只读状态（UI 画其它页面用）。
+    #[must_use]
+    pub fn state(&self) -> &AppState {
+        &self.state
+    }
+
+    /// 可写状态——**只在测试构建里存在**。
+    ///
+    /// 非测试代码没有这个后门：`AppState::ai` 的字段全是 pub，返回 `&mut AppState` 就等于
+    /// 让调用方绕开 [`AgentRail::ingest`] 的脱敏与 `busy` 不变量。需要写状态时走下面这些
+    /// 窄入口（prefs / 导航 / rail 的那几个字段），rail 的内容一律走四个契约方法。
+    #[cfg(test)]
+    pub fn state_mut(&mut self) -> &mut AppState {
+        &mut self.state
+    }
+
+    /// 导航（一级页替换、子页压栈；去 AI 独立页会展开栏并清未读）。
+    pub fn navigate(&mut self, route: Route) {
+        self.state.navigate(route);
+    }
+
+    /// 回退一层（子页面）；已在根页面时返回 `false`。
+    pub fn back(&mut self) -> bool {
+        self.state.back()
+    }
+
+    /// 折叠/展开 AI 栏（独立页形态下等价于收回侧栏；展开时清未读）。
+    pub fn toggle_ai(&mut self) {
+        self.state.toggle_ai();
+    }
+
+    /// UI 偏好（主题、磁贴尺寸、栏折叠位…）。**不含** rail 字段。
+    pub fn prefs_mut(&mut self) -> &mut UiPrefs {
+        &mut self.state.prefs
+    }
+
+    /// YOLO 开关（设置 → AI 的那一项）。
+    ///
+    /// 只翻开关不裁决：若此刻正有待确认请求，调用方仍要走一次
+    /// [`Presenter::agent_confirm`]（YOLO 下它会自动放行并记审计）。
+    pub fn agent_set_yolo(&mut self, on: bool) {
+        self.state.ai.yolo = on;
+    }
+
+    /// 输入框草稿（用户打字时同步进来，切形态不丢）。
+    ///
+    /// 草稿**是** rail 上唯一能合法躺着凭据原文的字段：它是「还没发出去的字」，写进来时不过
+    /// 脱敏（UI 要能原样显示用户正在打的字）。安全性靠另一条：`agent_submit` 脱敏的是**入参**
+    /// 而不是草稿，所以原文既不会进会话历史，也不会被发给后端。
+    pub fn agent_set_draft(&mut self, text: String) {
+        self.state.ai.draft = text;
+    }
+
+    /// 喂一条事件（纯转发给 [`AppState::apply`]）。
+    pub fn apply(&mut self, event: AppEvent) {
+        self.state.apply(event);
+    }
+
+    /// 当前会话的视图模型（唯一读入口；两形态共享同一份）。
+    #[must_use]
+    pub fn agent_rail(&self) -> &AgentRail {
+        &self.state.ai
+    }
+
+    /// 提交一句话。
+    ///
+    /// 拒绝的三种情形都不改状态（草稿保留，用户能接着改）：
+    /// 空文本、上一轮还在跑、有写操作待确认。
+    ///
+    /// 成功时清空草稿、立刻把 `busy` 置真（**然后**才投影后端返回的事件分片），最后按消息
+    /// 重算一次 `streaming`——异步后端在「提交成功 → 第一个事件到达」之间的空窗因此不会
+    /// 让用户再点一次发送（那会产生两条 user 消息、两轮回复）。
+    /// 用户气泡**由事件产生**（不在本地乐观回显，见 `lib.rs` §3）。
+    pub fn agent_submit(&mut self, text: String) -> Result<(), String> {
+        let trimmed = text.trim();
+        if trimmed.is_empty() {
+            return Err("请输入内容".to_string());
+        }
+        if self.state.ai.confirm.is_some() {
+            return Err("有写操作待确认：先允许或拒绝，再继续对话".to_string());
+        }
+        if self.state.ai.busy {
+            return Err("上一轮回复还没结束".to_string());
+        }
+        // 用户输入也过脱敏：他可能顺手把 token 粘进对话框，而这段文本会进会话历史、
+        // 会作为 prompt **发到模型服务商**、也会进导出。这道是**出站**闸门（rail 侧那道是
+        // 显示闸门，两者不能互相替代：删掉这道，界面照样干净，但凭据已经出去了）。
+        // 守卫见 agent/tests_red_line.rs::outbound_prompt_is_scrubbed_before_it_reaches_the_backend。
+        let text = scrub_text(trimmed);
+        let events = self
+            .transport
+            .submit(&text, &self.state.ai)
+            // 失败原因同样可能回显 key（provider 的 401 常把 key 抄进 message），
+            // 这条 Err 会直接显示在 UI 上，守卫见 outbound_error_text_is_scrubbed。
+            .map_err(|error| scrub_text(&error))?;
+        self.state.ai.draft.clear();
+        self.state.ai.error = None;
+        self.state.ai.begin_turn();
+        for event in events {
+            self.state.apply(event);
+        }
+        self.state.ai.settle_streaming();
+        Ok(())
+    }
+
+    /// 未读清零（UI 在「用户打开栏 / 停在独立页」时调用）。
+    pub fn agent_mark_read(&mut self) {
+        self.state.ai.mark_read();
+    }
+
+    /// 对当前待确认的写操作做决定。
+    ///
+    /// - 没有待确认：no-op（不记审计，不 panic）；
+    /// - YOLO 下：`accept` 被忽略，一律放行，审计记 `yolo = true, confirmed = false`；
+    /// - 非 YOLO：按 `accept` 裁决，审计记 `confirmed = true`。
+    ///
+    /// 两种情形都走同一条事件回流（后端返回的工具收尾事件），所以会话里看到的工具条目
+    /// 与审计记录不会各行其是。
+    ///
+    /// # UI 壳的义务
+    ///
+    /// 看到 `rail.confirm.is_some()` 就要给出决定：非 YOLO 弹确认框，YOLO 直接调
+    /// `agent_confirm(true)`（不弹窗，但**必须**调——否则 `busy` 一直锁着输入）。
+    /// 真实后端在 YOLO 下不会发 `ConfirmRequested`（agent 侧 ConfirmGate 已自动放行），
+    /// 这条路径是防御性的；另一条收敛途径是后端发 `AgentEvent::ConfirmResolved`。
+    pub fn agent_confirm(&mut self, accept: bool) {
+        let Some(request) = self.state.ai.take_confirm() else {
+            return;
+        };
+        let yolo = self.state.ai.yolo;
+        let verdict = if yolo || accept {
+            ConfirmVerdict::Approved
+        } else {
+            ConfirmVerdict::Denied
+        };
+        self.record(AuditEntry {
+            request_id: request.id.clone(),
+            tool: request.tool.clone(),
+            sensitivity: request.sensitivity,
+            verdict,
+            yolo,
+            confirmed: !yolo,
+        });
+        let events = self.transport.confirm(&request.id, verdict.is_approved());
+        for event in events {
+            self.state.apply(event);
+        }
+    }
+
+    /// 本进程内的裁决记录（最旧在前；权威审计在 agent 侧）。
+    #[must_use]
+    pub fn audit(&self) -> &[AuditEntry] {
+        &self.audit
+    }
+
+    /// 记一条裁决，超出 [`MAX_AUDIT_ENTRIES`] 时丢最旧的。
+    fn record(&mut self, entry: AuditEntry) {
+        if self.audit.len() == MAX_AUDIT_ENTRIES {
+            self.audit.remove(0);
+        }
+        self.audit.push(entry);
+    }
+}
diff --git a/crates/presenter/src/agent/mock.rs b/crates/presenter/src/agent/mock.rs
new file mode 100644
index 0000000..8a78d5b
--- /dev/null
+++ b/crates/presenter/src/agent/mock.rs
@@ -0,0 +1,165 @@
+//! mock 版 agent 后端：四条路径的脚本化事件流（正常问答 / 流式中途出错 / 需确认的写操作 /
+//! 未读计数）。
+//!
+//! 与 [`crate::mock::MockBackend`] 的分工：那个是**整机演示后端**（按 tick 推进剧情，带定时器）；
+//! 这个是 [`crate::agent::AgentTransport`] 的最小实现，**同步返回整轮事件分片**，专供 presenter
+//! 单测与 UI 壳的回归预览（没有真实 LLM 也能把栏画全）。
+//!
+//! 抓得住什么：事件顺序、投影结果（消息/工具/确认/未读/审计）、脱敏闸门。
+//! 抓不住什么：真实时序（这里一次性返回，真实后端是逐帧推流）、真实模型的措辞与工具选择、
+//! 网络/超时/取消语义——那些要接 rig 之后跑回放回归。
+
+use crate::agent::{AgentRail, AgentTransport};
+use crate::dto::{AgentEvent, AppEvent, ChatMessage, ChatRole, ConfirmRequest, Sensitivity};
+
+/// 脚本：一轮输入会产生哪种剧情。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Script {
+    /// 正常问答：流式增量收敛成一条完整助手消息
+    Qa,
+    /// 流式中途断流：已到的增量保留，整轮以 `Failed` 收尾
+    FailsMidStream,
+    /// 需确认的写操作：工具调用开始后挂一个 High 级确认请求
+    WriteOp,
+}
+
+/// 脚本化后端。
+#[derive(Debug, Clone)]
+pub struct MockAgentTransport {
+    script: Script,
+    /// 已发起过几轮（mock 用它算消息下标；真实后端自己维护会话）
+    turns: usize,
+    /// 当前待确认的写操作（`None` = 没有）
+    pending: Option<ConfirmRequest>,
+}
+
+impl MockAgentTransport {
+    /// 指定脚本。
+    #[must_use]
+    pub fn new(script: Script) -> Self {
+        Self {
+            script,
+            turns: 0,
+            pending: None,
+        }
+    }
+
+    /// 正常问答。
+    #[must_use]
+    pub fn qa() -> Self {
+        Self::new(Script::Qa)
+    }
+
+    /// 流式中途出错。
+    #[must_use]
+    pub fn fails_mid_stream() -> Self {
+        Self::new(Script::FailsMidStream)
+    }
+
+    /// 需确认的写操作（改下载并发，High 级）。
+    #[must_use]
+    pub fn write_op() -> Self {
+        Self::new(Script::WriteOp)
+    }
+
+    /// 当前待确认请求（测试断言用）。
+    #[must_use]
+    pub fn pending(&self) -> Option<&ConfirmRequest> {
+        self.pending.as_ref()
+    }
+}
+
+impl AgentTransport for MockAgentTransport {
+    fn submit(&mut self, text: &str, history: &AgentRail) -> Result<Vec<AppEvent>, String> {
+        self.turns += 1;
+        // 后端自己算下标：用户气泡先到，助手流式占位紧随其后。
+        let assistant_index = history.messages.len() + 1;
+        let mut events = vec![
+            agent_event(AgentEvent::MessageAppended(ChatMessage::user(text))),
+            agent_event(AgentEvent::MessageAppended(ChatMessage::assistant_stream())),
+        ];
+        match self.script {
+            Script::Qa => {
+                for delta in [
+                    "先确认版本：",
+                    "官方 1.20.4 是正式版，",
+                    "装完再加 Fabric。",
+                ] {
+                    events.push(agent_event(AgentEvent::MessageDelta {
+                        index: assistant_index,
+                        delta: delta.to_string(),
+                    }));
+                }
+                events.push(agent_event(AgentEvent::MessageFinished {
+                    index: assistant_index,
+                }));
+            }
+            Script::FailsMidStream => {
+                events.push(agent_event(AgentEvent::MessageDelta {
+                    index: assistant_index,
+                    delta: "我先读一下最近的日志".to_string(),
+                }));
+                events.push(agent_event(AgentEvent::Failed {
+                    message: "provider 断流：read timeout".to_string(),
+                }));
+            }
+            Script::WriteOp => {
+                events.push(agent_event(AgentEvent::MessageDelta {
+                    index: assistant_index,
+                    delta: "我准备把下载并发从 64 改成 16。".to_string(),
+                }));
+                events.push(agent_event(AgentEvent::MessageFinished {
+                    index: assistant_index,
+                }));
+                events.push(agent_event(AgentEvent::ToolCallStarted {
+                    name: "set_config".to_string(),
+                    summary: "修改 download.concurrency".to_string(),
+                }));
+                let request = ConfirmRequest {
+                    id: format!("req-{}", self.turns),
+                    tool: "set_config".to_string(),
+                    summary: "把下载并发 64 → 16".to_string(),
+                    details: serde_json::json!({
+                        "path": "download.concurrency",
+                        "old": 64,
+                        "new": 16,
+                    }),
+                    sensitivity: Sensitivity::High,
+                };
+                self.pending = Some(request.clone());
+                events.push(agent_event(AgentEvent::ConfirmRequested { request }));
+            }
+        }
+        Ok(events)
+    }
+
+    fn confirm(&mut self, request_id: &str, accept: bool) -> Vec<AppEvent> {
+        self.pending = None;
+        let (ok, summary, reply) = if accept {
+            (true, "已写入 download.concurrency = 16", "改好了。")
+        } else {
+            (false, "用户拒绝，未写入", "那就不改了。")
+        };
+        vec![
+            agent_event(AgentEvent::ToolCallFinished {
+                name: "set_config".to_string(),
+                ok,
+                summary: summary.to_string(),
+            }),
+            agent_event(AgentEvent::ConfirmResolved {
+                id: request_id.to_string(),
+            }),
+            agent_event(AgentEvent::MessageAppended(ChatMessage {
+                role: ChatRole::Assistant,
+                text: reply.to_string(),
+                tool: None,
+                streaming: false,
+            })),
+        ]
+    }
+}
+
+/// 包一层 [`AppEvent::Agent`]（presenter 的事件队列只认顶层事件）。
+fn agent_event(event: AgentEvent) -> AppEvent {
+    AppEvent::Agent(event)
+}
diff --git a/crates/presenter/src/agent/rail.rs b/crates/presenter/src/agent/rail.rs
new file mode 100644
index 0000000..557d97a
--- /dev/null
+++ b/crates/presenter/src/agent/rail.rs
@@ -0,0 +1,393 @@
+//! AI 助手栏（D16 双形态：右侧常驻栏 / 独立页）的**唯一**视图模型。
+//!
+//! 两形态共用同一份 [`AgentRail`]：折叠/展开、停靠/拆页都只是换渲染位置，切形态不丢会话。
+//!
+//! # 1. 事件从哪里来、到哪里去
+//!
+//! ```text
+//! agent/host 后端 ──AgentEvent──► AppState::apply ──► AgentRail::ingest ──► 字段
+//!                                       └──► unread（栏不可见时累加）
+//! ```
+//!
+//! 投影规则（四类事件各归各位）：
+//!
+//! | 事件 | 落到哪 |
+//! | ---- | ------ |
+//! | `MessageAppended` | 追加一条消息；`streaming` 的置 `rail.streaming` |
+//! | `MessageDelta` | 追加到最后一条 assistant 消息的正文（**累积在一条上**，不是每条一个气泡） |
+//! | `MessageFinished` | 清掉该条（以及全部）流式标记，`streaming` 由消息重算 |
+//! | `ToolCallStarted` / `ToolCallFinished` | 生成 / 收敛 [`ToolCallView`] 条目（D4：工具调用会话可见） |
+//! | `Failed` | 收敛流式 + 立横幅 + 追加系统条目（错误也要能回翻） |
+//! | `ConfirmRequested` / `ConfirmResolved` | `rail.confirm` 置位 / 清除 |
+//!
+//! # 2. 红线：凭据不得进 rail，也不得**出站**
+//!
+//! 两道闸门，各守一侧，**不能互相替代**：
+//!
+//! | 闸门 | 位置 | 守什么 |
+//! | ---- | ---- | ------ |
+//! | 出站 | [`crate::agent::Presenter::agent_submit`] 的 `scrub_text(trimmed)` / `map_err` | 发给后端的 prompt、回给 UI 的 `Err` 文案 |
+//! | 显示 | [`AgentRail::ingest`] 这里 | 进入 rail 的所有事件文本（消息正文 / 工具名与摘要 / 错误 / 确认请求） |
+//!
+//! 只留出站闸门 → 后端事件里的凭据会直接显示在聊天栏；只留显示闸门 → 界面一片干净而
+//! **凭据已经发出去了**。两边各有独立守卫（`agent/tests_red_line.rs`）。
+//!
+//! [`AgentRail::ingest`] 逐字段过 [`scrub_text`] / [`scrub_details`]。凭据字段（`token` /
+//! `refresh_token` / `password` / `access_token` …）本就不该出现在事件里（AGENTS §6：AI 永不
+//! 接触账户凭据），这里的脱敏是**第二道**防线：万一实现方把 JWT 塞进了工具摘要或错误文案，
+//! rail 上也不会出现原文。
+//!
+//! 规则来源（刻意不另写一套正则）：
+//! - 内容侧：复用 `unlucky_core::launch::redact`（M40 上提的「带点 token」+ ≥64 不透明串）；
+//! - 上下文侧：照 `unlucky_agent::redact` 补两条——`Bearer <短令牌>` 掩码、
+//!   `{"path": 敏感键}` 时 `value`/`old`/`new` 一并掩码（`set_config` 的 details 正是它）。
+//!
+//! 与 `unlucky_agent::redact` 的实际关系（**别读成「已无差异」，也别读成「已经漂移」**）：
+//! - 键名名单（8 条 needle）：**逐字相同**；
+//! - path 规则：**语义相同**（presenter 额外对字符串值跑 `scrub_text`，比 `redact_args` 更严）；
+//! - [`mask_bearer`]：**行为不完全等价的自写迁移**——停字符集 presenter 8 个（含 `;`，
+//!   不含 `/` `\`）vs agent `segment_end` 9 个（含 `/` `\`，不含 `;`），占位符也不同
+//!   （`<redacted:token>` vs `***`）。`Bearer abc;def` presenter 掩得更少（`abc` 被掩、
+//!   `;def` 留着），`Bearer abc/def` 掩得更多。方向安全（多掩不漏；少掩只发生在 `;` 上），
+//!   右边界由 `tests::bearer_right_boundary_is_pinned` 钉住。
+//! - 两处重复实现（键名名单 + Bearer）是**已知欠账**：上提一份公共实现要单开 mission
+//!   （presenter 不能依赖 `unlucky-agent`，那会拖进 rig / tokio / rmcp）。
+//!
+//! # 3. 刻意不做的事
+//!
+//! - **不裁剪 `messages`**：`MessageDelta` 用下标寻址，从头丢弃会让下标漂移。会话长度由后端
+//!   的轮次上限控制；这里只保证下标稳定。
+//! - **不持有后端**：rail 是纯数据 + 投影，提交/确认在 [`crate::agent::Presenter`]。
+
+use serde_json::{Map, Value};
+use unlucky_core::launch::redact::{Redactor, TOKEN_PLACEHOLDER};
+
+use crate::dto::{AgentEvent, ChatMessage, ChatRole, ConfirmRequest, ToolCallView};
+
+/// 键名命中即整值打码（与 `unlucky_agent::redact::is_sensitive_key` 同一份名单）。
+///
+/// 为什么在这里再写一遍：presenter 不依赖 `unlucky-agent`（那会把 rig / tokio / rmcp 整棵树
+/// 拖进共用宿主层）。名单漂移的风险已记进 M103 报告，长期该由 core 出一份公共实现。
+const SENSITIVE_KEY_NEEDLES: [&str; 8] = [
+    "api_key",
+    "apikey",
+    "token",
+    "password",
+    "passwd",
+    "secret",
+    "authorization",
+    "credential",
+];
+
+/// 文本是否像凭据键名（`access_token` / `refresh_token` / `microsoft.password` …）。
+#[must_use]
+pub fn is_sensitive_key(key: &str) -> bool {
+    let lower = key.to_ascii_lowercase();
+    SENSITIVE_KEY_NEEDLES
+        .iter()
+        .any(|needle| lower.contains(needle))
+}
+
+/// 文本脱敏：内容规则三件套。
+///
+/// 1. JWT 形状（带点 token）/ ≥64 不透明串 —— 复用 core 的 `Redactor`（M40 上提的那份）；
+/// 2. `Bearer` 后面的短令牌 —— core 没有这条，照 `unlucky_agent::redact::mask_bearer` 补；
+/// 3. 主目录不登记：rail 不持有数据根，`<home>` 掩码是 host 侧的职责。
+#[must_use]
+pub fn scrub_text(text: &str) -> String {
+    mask_bearer(&Redactor::new().scrub(text))
+}
+
+/// 结构化细节脱敏：按**键名**、按**值随 path 敏感**、按内容三道（见模块文档 §2）。
+///
+/// 同样对齐 `unlucky_agent::redact::redact_args` 的两条上下文规则：键名命中即掩码，
+/// 以及 `{"path": "ai.api_key", "old": …, "new": …}` 这种「值随路径敏感」的形状
+/// （`set_config` 的 details 正是它）——否则 API key 会原样躺在确认弹窗的 diff 里。
+#[must_use]
+pub fn scrub_details(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 (key, child) in map {
+                let masked = is_sensitive_key(key)
+                    || (sensitive_path && matches!(key.as_str(), "value" | "old" | "new"));
+                let child = if masked {
+                    Value::String(TOKEN_PLACEHOLDER.to_string())
+                } else {
+                    scrub_details(child)
+                };
+                out.insert(key.clone(), child);
+            }
+            Value::Object(out)
+        }
+        Value::Array(items) => Value::Array(items.iter().map(scrub_details).collect()),
+        Value::String(text) => Value::String(scrub_text(text)),
+        other => other.clone(),
+    }
+}
+
+/// `Bearer` 之后的分隔符（令牌到此为止）。与 agent `segment_end` 的差异见模块文档 §2：
+/// 多 `;`、少 `/` `\`（方向安全：多掩不漏），右边界由 `tests::bearer_right_boundary_is_pinned` 钉住。
+const BEARER_STOPS: [char; 8] = [' ', '\t', '\n', '\r', '"', '\'', ',', ';'];
+
+/// `Bearer <token>` → `Bearer <redacted:token>`。
+///
+/// core 的 `Redactor` 只认「点号 token / ≥64 不透明串」，短令牌（`Bearer abcdef123456`）
+/// 会原样放过——这条规则照 `unlucky_agent::redact::mask_bearer` 的意图补上（实现是自写的，
+/// 见模块文档 §2 的差异说明）。幂等：已经是 `<redacted:token>` 的再跑一遍结果不变。
+fn mask_bearer(text: &str) -> String {
+    const MARKER: &str = "Bearer ";
+    let mut out = String::with_capacity(text.len());
+    let mut cursor = 0usize;
+    while let Some(position) = text[cursor..].find(MARKER) {
+        let token_start = cursor + position + MARKER.len();
+        let token_end = bearer_token_end(text, token_start);
+        out.push_str(&text[cursor..token_start]);
+        if token_end > token_start {
+            out.push_str(TOKEN_PLACEHOLDER);
+        }
+        cursor = token_end;
+    }
+    out.push_str(&text[cursor..]);
+    out
+}
+
+/// 从 `from` 起取到下一个分隔符为止（令牌的右边界）。
+fn bearer_token_end(text: &str, from: usize) -> usize {
+    text[from..]
+        .find(BEARER_STOPS)
+        .map_or(text.len(), |offset| from + offset)
+}
+
+/// AI 助手栏视图模型（UI 壳只读它，不自己攒会话状态）。
+#[derive(Debug, Clone, PartialEq)]
+pub struct AgentRail {
+    /// 会话消息（user / assistant / tool / system），下标稳定
+    pub messages: Vec<ChatMessage>,
+    /// 栏不可见期间攒下的未读条数（`agent_mark_read` 清零）
+    pub unread: usize,
+    /// 是否该禁用输入（一轮回复进行中，或有写操作待确认）
+    pub busy: bool,
+    /// 输入框草稿（切形态不丢）
+    pub draft: String,
+    /// 待确认的写操作（`Some` = 弹确认框；非 YOLO 下 `busy` 必为 true）
+    pub confirm: Option<ConfirmRequest>,
+    /// 是否有流式消息在跑（Slint 壳读它切换「发送/停止」；新壳用 `busy` 即可）
+    pub streaming: bool,
+    /// YOLO 开关（跳过确认，审计照记）
+    pub yolo: bool,
+    /// 端点标签（栏顶显示）
+    pub endpoint_label: String,
+    /// 最近一次错误（横幅；下一次提交或 ingest 到新消息时清掉）
+    pub error: Option<String>,
+}
+
+impl Default for AgentRail {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl AgentRail {
+    /// 空会话。默认端点标签是 P0 的本地 llama.cpp（P1 由设置页决定）。
+    #[must_use]
+    pub fn new() -> Self {
+        Self {
+            messages: Vec::new(),
+            unread: 0,
+            busy: false,
+            draft: String::new(),
+            confirm: None,
+            streaming: false,
+            yolo: false,
+            endpoint_label: "llama.cpp · 本地".to_string(),
+            error: None,
+        }
+    }
+
+    /// 流式收敛：清掉全部流式标记并按消息重算 `streaming` / `busy`。
+    pub fn finish_stream(&mut self) {
+        for message in &mut self.messages {
+            message.streaming = false;
+        }
+        self.settle_streaming();
+    }
+
+    /// 提交成功、后端还没回事件时先把「一轮在跑」点亮。
+    ///
+    /// 异步后端在「提交成功 → 第一个事件到达」之间有空窗；不先置忙的话用户能再点一次发送，
+    /// 于是两条 user 消息、两轮回复并行。反正事件流收敛时会用
+    /// [`AgentRail::settle_streaming`] 按消息重算，不会留下假忙。
+    pub fn begin_turn(&mut self) {
+        self.streaming = true;
+        self.sync_busy();
+    }
+
+    /// 按消息重算 `streaming`（有任一条还在流式即为真）并同步 `busy`。
+    pub fn settle_streaming(&mut self) {
+        self.streaming = self.messages.iter().any(|message| message.streaming);
+        self.sync_busy();
+    }
+
+    /// 清零未读（用户正在看 / 主动点掉红点）。
+    pub fn mark_read(&mut self) {
+        self.unread = 0;
+    }
+
+    /// 取走待确认请求（`confirm` 置空并按需重算 `busy`）；没有则返回 `None`。
+    pub fn take_confirm(&mut self) -> Option<ConfirmRequest> {
+        let request = self.confirm.take();
+        self.sync_busy();
+        request
+    }
+
+    /// 投影一条 agent 事件。
+    ///
+    /// 返回 `true` 表示这是一条「用户不在栏前也会想知道」的新内容（未读计数的原料）：
+    /// 助手/工具消息、错误、确认请求算；用户自己说的话与纯增量不算。
+    pub fn ingest(&mut self, event: &AgentEvent) -> bool {
+        match event {
+            AgentEvent::MessageAppended(message) => {
+                let message = scrub_message(message);
+                let fresh = matches!(message.role, ChatRole::Assistant | ChatRole::Tool);
+                if message.streaming {
+                    self.streaming = true;
+                }
+                if fresh {
+                    self.error = None;
+                }
+                self.messages.push(message);
+                self.sync_busy();
+                fresh
+            }
+            AgentEvent::MessageDelta { index, delta } => {
+                // 只追加正文，不动流式标记：迟到的尾增量（`Failed` 之后）不该把
+                // 「一轮在跑」重新点亮，否则输入框会一直禁用。
+                match self.messages.get_mut(*index) {
+                    Some(message) => message.text.push_str(&scrub_text(delta)),
+                    // 分片乱序/重放时正文会无声消失（用户只看到半截话）：开发期吵起来，
+                    // 发布期宁可丢这一片也不去猜该拼到哪条上。
+                    None => debug_assert!(
+                        false,
+                        "MessageDelta 指向不存在的消息下标 {index}（会话 {} 条）",
+                        self.messages.len()
+                    ),
+                }
+                self.sync_busy();
+                false
+            }
+            AgentEvent::MessageFinished { index } => {
+                if let Some(message) = self.messages.get_mut(*index) {
+                    message.streaming = false;
+                }
+                // 以消息为准重算：并发工具条目没收敛时 `streaming` 不能提前熄
+                self.settle_streaming();
+                false
+            }
+            AgentEvent::ToolCallStarted { name, summary } => {
+                let summary = scrub_text(summary);
+                self.streaming = true;
+                self.error = None;
+                self.messages.push(ChatMessage {
+                    role: ChatRole::Tool,
+                    text: summary.clone(),
+                    tool: Some(ToolCallView {
+                        name: scrub_text(name),
+                        ok: false,
+                        summary,
+                    }),
+                    streaming: true,
+                });
+                self.sync_busy();
+                true
+            }
+            AgentEvent::ToolCallFinished { name, ok, summary } => {
+                let name = scrub_text(name);
+                let summary = scrub_text(summary);
+                // 只收敛「还在跑的同名调用」。找不到就**忽略**，绝不退回改写已收敛的旧条目
+                // ——那会把历史结果覆盖掉（重放、重复结束事件、丢过 ToolCallStarted 都会命中）。
+                let pending = self
+                    .messages
+                    .iter()
+                    .rposition(|message| message.streaming && tool_named(message, &name));
+                if let Some(index) = pending {
+                    let message = &mut self.messages[index];
+                    message.streaming = false;
+                    message.text.clone_from(&summary);
+                    if let Some(tool) = &mut message.tool {
+                        tool.ok = *ok;
+                        tool.summary = summary;
+                    }
+                }
+                self.settle_streaming();
+                false
+            }
+            AgentEvent::Failed { message } => {
+                let text = scrub_text(message);
+                self.finish_stream();
+                self.error = Some(text.clone());
+                self.messages.push(ChatMessage::system(text));
+                true
+            }
+            AgentEvent::ConfirmRequested { request } => {
+                self.confirm = Some(scrub_confirm(request));
+                self.sync_busy();
+                true
+            }
+            AgentEvent::ConfirmResolved { id } => {
+                if self
+                    .confirm
+                    .as_ref()
+                    .is_some_and(|pending| &pending.id == id)
+                {
+                    self.confirm = None;
+                }
+                self.sync_busy();
+                false
+            }
+        }
+    }
+
+    /// `busy` 的唯一写入口：`busy == streaming || confirm.is_some()`。
+    ///
+    /// UI 靠 `busy` 禁用输入框，所以「等确认」必须算忙——否则用户能在一轮写操作中间再发一句，
+    /// 两个工具调用会踩同一份配置。
+    fn sync_busy(&mut self) {
+        self.busy = self.streaming || self.confirm.is_some();
+    }
+}
+
+/// 消息脱敏（正文 + 工具摘要；工具名也过一遍，防止实现方把凭据塞进名字）。
+fn scrub_message(message: &ChatMessage) -> ChatMessage {
+    let tool = message.tool.as_ref().map(|tool| ToolCallView {
+        name: scrub_text(&tool.name),
+        ok: tool.ok,
+        summary: scrub_text(&tool.summary),
+    });
+    ChatMessage {
+        role: message.role,
+        text: scrub_text(&message.text),
+        tool,
+        streaming: message.streaming,
+    }
+}
+
+/// 确认请求脱敏：摘要按内容、细节按键名 + 内容双道。
+fn scrub_confirm(request: &ConfirmRequest) -> ConfirmRequest {
+    ConfirmRequest {
+        id: request.id.clone(),
+        tool: scrub_text(&request.tool),
+        summary: scrub_text(&request.summary),
+        details: scrub_details(&request.details),
+        sensitivity: request.sensitivity,
+    }
+}
+
+/// 这条消息是不是指定名字的工具条目。
+fn tool_named(message: &ChatMessage, name: &str) -> bool {
+    message.tool.as_ref().is_some_and(|tool| tool.name == name)
+}
diff --git a/crates/presenter/src/agent/tests.rs b/crates/presenter/src/agent/tests.rs
new file mode 100644
index 0000000..cc8796e
--- /dev/null
+++ b/crates/presenter/src/agent/tests.rs
@@ -0,0 +1,362 @@
+//! `agent` 模块的单元测试：四条路径（正常问答 / 流式中途出错 / 需确认的写操作 / 未读计数）+
+//! YOLO 语义 + 提交前置条件 + 投影健壮性。
+//!
+//! 红线（凭据形状的串不得进 rail）单列在 `agent/tests_red_line.rs`（单文件 ≤400 行）。
+//! 断言口径照 M103 的要求写清「抓得住什么 / 抓不住什么」：这些测试盯的是**投影与裁决**，
+//! 不盯真实模型的措辞、真实时序与网络错误——那些要接 rig 之后跑回放回归。
+
+use super::mock::{MockAgentTransport, Script};
+use super::{AgentTransport, ConfirmVerdict, Presenter};
+use crate::agent::rail::scrub_text;
+use crate::agent::AgentRail;
+use crate::dto::{AgentEvent, AppEvent, ChatMessage, ChatRole, ConfirmRequest, Sensitivity};
+
+fn presenter(script: Script) -> Presenter {
+    Presenter::new(Box::new(MockAgentTransport::new(script)))
+}
+
+// ───────────────────────── 路径 1：正常问答 ─────────────────────────
+
+#[test]
+fn normal_answer_accumulates_into_one_assistant_message() {
+    let mut presenter = presenter(Script::Qa);
+    assert!(presenter.agent_submit("怎么装 1.20.4".to_string()).is_ok());
+
+    let rail = presenter.agent_rail();
+    // 抓得住：用户气泡 + 一条助手消息（增量累积在同一条上，不是一个字一个气泡）
+    assert_eq!(rail.messages.len(), 2);
+    assert_eq!(rail.messages[0].role, ChatRole::User);
+    assert_eq!(rail.messages[0].text, "怎么装 1.20.4");
+    assert_eq!(rail.messages[1].role, ChatRole::Assistant);
+    assert_eq!(
+        rail.messages[1].text,
+        "先确认版本：官方 1.20.4 是正式版，装完再加 Fabric。"
+    );
+    assert!(!rail.messages[1].streaming);
+    assert!(!rail.streaming);
+    assert!(!rail.busy);
+    assert!(rail.confirm.is_none());
+    assert!(rail.error.is_none());
+    // 抓不住：不校验助手措辞是否正确（那是工具/模型的事）
+}
+
+// ─────────────────── 路径 2：流式中途出错 ───────────────────
+
+#[test]
+fn mid_stream_error_keeps_partial_text_and_flags_the_turn() {
+    let mut presenter = presenter(Script::FailsMidStream);
+    assert!(presenter.agent_submit("日志里有错吗".to_string()).is_ok());
+
+    let rail = presenter.agent_rail();
+    // 抓得住：已到的增量不丢、流式收敛（不会永远转圈）、错误进横幅也进会话历史
+    assert_eq!(rail.messages[1].role, ChatRole::Assistant);
+    assert_eq!(rail.messages[1].text, "我先读一下最近的日志");
+    assert!(!rail.streaming);
+    assert!(!rail.busy, "出错后输入框必须重新可用");
+    assert_eq!(rail.error.as_deref(), Some("provider 断流：read timeout"));
+    assert_eq!(rail.messages[2].role, ChatRole::System);
+    assert_eq!(rail.messages[2].text, "provider 断流：read timeout");
+    // 抓不住：不判断这是网络问题还是模型问题（归因在 core::diagnose）
+}
+
+// ───────────── 路径 3a/3b：需确认的写操作（接受 / 拒绝）─────────────
+
+#[test]
+fn write_op_accept_applies_and_audits() {
+    let mut presenter = presenter(Script::WriteOp);
+    assert!(presenter.agent_submit("并发调小点".to_string()).is_ok());
+
+    // 确认之前：rail 挂着请求，且 UI 靠 busy 禁用输入
+    {
+        let rail = presenter.agent_rail();
+        assert!(rail.busy);
+        let request = rail.confirm.as_ref().expect("应当有待确认请求");
+        assert_eq!(request.tool, "set_config");
+        assert_eq!(request.details["path"], "download.concurrency");
+        assert!(request.sensitivity.needs_confirm());
+        assert_eq!(rail.messages.len(), 3); // user / assistant / tool
+        assert_eq!(rail.messages[2].role, ChatRole::Tool);
+    }
+
+    presenter.agent_confirm(true);
+    let rail = presenter.agent_rail();
+    assert!(rail.confirm.is_none());
+    assert!(!rail.busy);
+    assert_eq!(rail.messages[2].text, "已写入 download.concurrency = 16");
+    assert!(rail.messages[2].tool.as_ref().is_some_and(|tool| tool.ok));
+    assert_eq!(
+        rail.messages.last().map(|message| message.role),
+        Some(ChatRole::Assistant)
+    );
+
+    let audit = presenter.audit();
+    assert_eq!(audit.len(), 1);
+    assert_eq!(audit[0].verdict, ConfirmVerdict::Approved);
+    assert!(!audit[0].yolo && audit[0].confirmed, "用户亲手点的允许");
+    assert_eq!(audit[0].sensitivity, Sensitivity::High);
+}
+
+#[test]
+fn write_op_reject_denies_and_audits() {
+    let mut presenter = presenter(Script::WriteOp);
+    assert!(presenter.agent_submit("并发调小点".to_string()).is_ok());
+    presenter.agent_confirm(false);
+
+    let rail = presenter.agent_rail();
+    assert!(rail.confirm.is_none());
+    assert!(!rail.busy);
+    assert_eq!(rail.messages[2].text, "用户拒绝，未写入");
+    assert!(rail.messages[2].tool.as_ref().is_some_and(|tool| !tool.ok));
+    assert_eq!(
+        rail.messages.last().map(|text| text.text.clone()),
+        Some("那就不改了。".to_string())
+    );
+
+    let audit = presenter.audit();
+    assert_eq!(audit[0].verdict, ConfirmVerdict::Denied);
+    assert!(!audit[0].yolo && audit[0].confirmed);
+}
+
+// ─────────────────────── 路径 4：未读计数 ───────────────────────
+
+#[test]
+fn unread_grows_while_collapsed_and_mark_read_clears() {
+    let mut presenter = presenter(Script::WriteOp);
+    presenter.state_mut().prefs.ai_collapsed = true; // 收成 icon 轨 = 用户离开了栏
+    presenter
+        .agent_submit("并发调小点".to_string())
+        .expect("提交应当成功");
+
+    // 抓得住：助手消息 + 工具条目 + 待确认各算一条；用户自己的话与纯增量不算
+    assert_eq!(presenter.agent_rail().unread, 3);
+
+    presenter.agent_confirm(true);
+    // 工具收尾不是新内容，收尾的助手消息算一条
+    assert_eq!(presenter.agent_rail().unread, 4);
+
+    presenter.agent_mark_read();
+    assert_eq!(presenter.agent_rail().unread, 0);
+}
+
+// ───────────────────────── YOLO 语义 ─────────────────────────
+
+#[test]
+fn yolo_auto_accepts_but_still_records_the_verdict() {
+    let mut presenter = presenter(Script::WriteOp);
+    presenter.state_mut().ai.yolo = true;
+    presenter
+        .agent_submit("并发调小点".to_string())
+        .expect("提交应当成功");
+
+    // 用户点了「拒绝」，但 YOLO 下自动放行
+    presenter.agent_confirm(false);
+
+    let rail = presenter.agent_rail();
+    assert!(rail.confirm.is_none());
+    assert_eq!(rail.messages[2].text, "已写入 download.concurrency = 16");
+
+    // 不得静默跳过：审计里必须有这一条，且两种标记分开记
+    let audit = presenter.audit();
+    assert_eq!(audit.len(), 1);
+    assert_eq!(audit[0].verdict, ConfirmVerdict::Approved);
+    assert!(audit[0].yolo, "YOLO 自动放行要留痕");
+    assert!(!audit[0].confirmed, "自动放行不是「用户确认」");
+}
+
+#[test]
+fn pending_confirm_forces_busy_without_yolo() {
+    let mut presenter = presenter(Script::WriteOp);
+    assert!(!presenter.agent_rail().yolo);
+    presenter
+        .agent_submit("并发调小点".to_string())
+        .expect("提交应当成功");
+    assert!(presenter.agent_rail().confirm.is_some());
+
+    // 先把流式标记清干净：否则 `busy` 可能只是「streaming 顺手置真」，
+    // 这条测试就钉不住「待确认算忙」这条规则（r1 P2-2：变异掉 `confirm.is_some()`
+    // 之后这里必须变红）。
+    presenter.state_mut().ai.finish_stream();
+    let rail = presenter.agent_rail();
+    assert!(!rail.streaming, "此刻没有流式消息在跑");
+    assert!(rail.busy, "非 YOLO 下待确认必须算忙，UI 靠它禁用输入");
+}
+
+#[test]
+fn begin_turn_marks_busy_before_any_event_arrives() {
+    // 提交成功到第一个事件之间异步后端有空窗：这段时间必须已经算忙，
+    // 否则用户能再点一次发送（两条 user 消息、两轮回复）。
+    let mut rail = AgentRail::new();
+    rail.begin_turn();
+    assert!(rail.busy && rail.streaming);
+
+    // 空事件流也不会把输入框永久锁死：收敛时按消息重算
+    rail.settle_streaming();
+    assert!(!rail.busy && !rail.streaming);
+}
+
+#[test]
+fn submit_with_a_silent_backend_does_not_leave_the_shell_busy() {
+    let mut presenter = Presenter::new(Box::new(SilentTransport));
+    presenter
+        .agent_submit("在吗".to_string())
+        .expect("提交应当成功");
+    assert!(
+        !presenter.agent_rail().busy,
+        "后端一个事件都没回，输入框必须重新可用"
+    );
+}
+
+/// 工具收尾事件早于开始事件（或重复投递）：不许覆盖已收敛的历史条目（r1 P2-3）。
+#[test]
+fn tool_call_finished_without_a_pending_call_never_rewrites_history() {
+    let mut presenter = presenter(Script::Qa);
+    presenter.apply(AppEvent::Agent(AgentEvent::ToolCallStarted {
+        name: "set_config".to_string(),
+        summary: "修改 download.concurrency".to_string(),
+    }));
+    presenter.apply(AppEvent::Agent(AgentEvent::ToolCallFinished {
+        name: "set_config".to_string(),
+        ok: true,
+        summary: "并发已改成 16".to_string(),
+    }));
+    // 重放 / 乱序：没有 pending 的收尾事件只能被忽略
+    presenter.apply(AppEvent::Agent(AgentEvent::ToolCallFinished {
+        name: "set_config".to_string(),
+        ok: false,
+        summary: "另一次失败".to_string(),
+    }));
+
+    let tool = presenter.agent_rail().messages[0]
+        .tool
+        .as_ref()
+        .expect("工具条目");
+    assert_eq!(tool.summary, "并发已改成 16", "历史条目被改写了");
+    assert!(tool.ok);
+}
+
+// ────────────────── scrub_text 的 Bearer 右边界 ──────────────────
+
+/// 钉住 `mask_bearer` 的**右边界**（r2 P2-2：停字符集收窄或换字符都必须让这条红）。
+///
+/// 方向说明：停字符越少 = 吞得越多（安全）；放宽才会裸奔。所以句点故意不在停字符集里
+/// （吞掉句点，换「短 JWT 只掩前半段」是不划算的）。
+#[test]
+fn bearer_right_boundary_is_pinned() {
+    // 空白 / 逗号 / 分号 / 引号是停字符：令牌之后的内容原样保留
+    assert_eq!(
+        scrub_text("Authorization: Bearer abc123, retry=1"),
+        "Authorization: Bearer <redacted:token>, retry=1"
+    );
+    assert_eq!(
+        scrub_text("Bearer abc123; rest"),
+        "Bearer <redacted:token>; rest"
+    );
+    assert_eq!(
+        scrub_text("\"Bearer abc123\""),
+        "\"Bearer <redacted:token>\""
+    );
+    assert_eq!(scrub_text("Bearer abc123"), "Bearer <redacted:token>");
+    // 句点不是停字符：整段吞掉（宁可多掩，也不让短 JWT 只掩前半段）
+    assert_eq!(scrub_text("Bearer abc123."), "Bearer <redacted:token>");
+    assert_eq!(scrub_text("Bearer eyJ.abc.def"), "Bearer <redacted:token>");
+}
+
+// ─────────────────────── 提交前置条件 ───────────────────────
+
+#[test]
+fn submit_rejects_empty_busy_and_pending_confirm() {
+    let mut presenter = presenter(Script::Qa);
+    assert!(presenter.agent_submit("   \n ".to_string()).is_err());
+    assert!(presenter.agent_rail().messages.is_empty());
+
+    // 上一轮还在跑
+    presenter.apply(AppEvent::Agent(AgentEvent::MessageAppended(
+        ChatMessage::assistant_stream(),
+    )));
+    assert!(presenter.agent_submit("再说一句".to_string()).is_err());
+
+    // 有写操作待确认
+    presenter.apply(AppEvent::Agent(AgentEvent::Failed {
+        message: "断流".to_string(),
+    }));
+    presenter.apply(AppEvent::Agent(AgentEvent::ConfirmRequested {
+        request: ConfirmRequest {
+            id: "req-1".to_string(),
+            tool: "set_config".to_string(),
+            summary: "改内存".to_string(),
+            details: serde_json::json!({}),
+            sensitivity: Sensitivity::High,
+        },
+    }));
+    let error = presenter.agent_submit("再说一句".to_string());
+    assert!(error.is_err(), "待确认时不许再提交");
+}
+
+#[test]
+fn submit_keeps_the_draft_when_the_backend_fails() {
+    let mut presenter = Presenter::new(Box::new(BrokenTransport));
+    presenter.state_mut().ai.draft = "还没发出去的话".to_string();
+    assert!(presenter
+        .agent_submit("还没发出去的话".to_string())
+        .is_err());
+    // 抓得住：起不来的一轮不产生事件、草稿保留（用户能改完再发）
+    assert!(presenter.agent_rail().messages.is_empty());
+    assert_eq!(presenter.agent_rail().draft, "还没发出去的话");
+}
+
+#[test]
+fn draft_is_cleared_only_on_successful_submit() {
+    let mut presenter = presenter(Script::Qa);
+    presenter.state_mut().ai.draft = " 怎么装 ".to_string();
+    presenter
+        .agent_submit(" 怎么装 ".to_string())
+        .expect("提交应当成功");
+    assert!(presenter.agent_rail().draft.is_empty());
+}
+
+#[test]
+fn confirm_without_pending_is_a_noop() {
+    let mut presenter = presenter(Script::Qa);
+    presenter.agent_confirm(true);
+    presenter.agent_confirm(false);
+    assert!(presenter.audit().is_empty());
+    assert!(presenter.agent_rail().messages.is_empty());
+}
+
+#[test]
+fn apply_forwards_every_event_to_app_state() {
+    let mut presenter = presenter(Script::Qa);
+    presenter.apply(AppEvent::Agent(AgentEvent::MessageAppended(
+        ChatMessage::assistant_stream(),
+    )));
+    assert_eq!(presenter.state().ai.messages.len(), 1);
+    assert_eq!(presenter.agent_rail(), &presenter.state().ai);
+}
+
+// ───────────────────────── 测试替身 ─────────────────────────
+
+/// 起不来的后端（返回 `Err`，不产生任何事件）。
+struct BrokenTransport;
+
+impl AgentTransport for BrokenTransport {
+    fn submit(&mut self, _text: &str, _history: &AgentRail) -> Result<Vec<AppEvent>, String> {
+        Err("本地模型还没加载".to_string())
+    }
+
+    fn confirm(&mut self, _request_id: &str, _accept: bool) -> Vec<AppEvent> {
+        Vec::new()
+    }
+}
+
+/// 收下输入但一个事件都不回的后端（异步推流的极端形态：这一拍还没到）。
+struct SilentTransport;
+
+impl AgentTransport for SilentTransport {
+    fn submit(&mut self, _text: &str, _history: &AgentRail) -> Result<Vec<AppEvent>, String> {
+        Ok(Vec::new())
+    }
+
+    fn confirm(&mut self, _request_id: &str, _accept: bool) -> Vec<AppEvent> {
+        Vec::new()
+    }
+}
diff --git a/crates/presenter/src/agent/tests_red_line.rs b/crates/presenter/src/agent/tests_red_line.rs
new file mode 100644
index 0000000..4790ac7
--- /dev/null
+++ b/crates/presenter/src/agent/tests_red_line.rs
@@ -0,0 +1,380 @@
+//! 红线测试：凭据形状的串不得进 [`crate::agent::AgentRail`]，也不得**出站**。
+//!
+//! 与 `agent/tests.rs` 同源、拆文件只为守「单文件 ≤400 行」。这一组测试的目标是**守住闸门**：
+//! 两道闸门（出站 [`Presenter::agent_submit`] 的 prompt/Err、显示 [`crate::agent::rail`] 的
+//! ingest 投影）与每条具体入口各自注入一次，任何一条把脱敏摘掉都必须变红。
+//! r1 / r2 复审都是靠「逐入口造变异」抓出假绿的，改动这里时请照做自证。
+//!
+//! 注入的凭据形状两类：
+//! - JWT（`header.payload.signature`，靠 core `Redactor` 的「带点 token」规则拦）；
+//! - 非 JWT 形状（`{"password":"hunter2"}`、短 `Bearer abcdef123456`，靠键名与 Bearer 规则拦）。
+//!
+//! **`rail.draft` 不在这组断言的覆盖范围**：草稿是「还没发出去的字」，UI 要原样显示，
+//! 它按设计可以躺着凭据原文；安全性由「`agent_submit` 脱敏的是入参而非草稿」保证。
+//! 所以本文件的 `rail_text()` 刻意不含 draft——别把「rail 全文无 JWT」读成覆盖了 draft。
+
+use std::cell::RefCell;
+use std::rc::Rc;
+
+use super::mock::{MockAgentTransport, Script};
+use super::{AgentTransport, Presenter};
+use crate::agent::rail::scrub_text;
+use crate::agent::AgentRail;
+use crate::dto::{
+    AgentEvent, AppEvent, ChatMessage, ChatRole, ConfirmRequest, Sensitivity, ToolCallView,
+};
+
+/// 真实形状的 JWT（header.payload.signature，三段各 ≥8）。
+const JWT: &str = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.c2lnbmF0dXJlLXZhbHVlLXRoYXQtaXMtbG9uZy1lbm91Z2g";
+
+fn presenter(script: Script) -> Presenter {
+    Presenter::new(Box::new(MockAgentTransport::new(script)))
+}
+
+#[test]
+fn jwt_shaped_text_never_reaches_the_rail() {
+    let mut presenter = presenter(Script::Qa);
+    // 五个入口各注入一次：用户提交、增量、工具摘要、错误、确认请求细节
+    presenter
+        .agent_submit(format!("我的 token 是 {JWT}"))
+        .expect("提交应当成功");
+    presenter.apply(AppEvent::Agent(AgentEvent::MessageDelta {
+        index: 1,
+        delta: format!("顺手贴一个 {JWT}"),
+    }));
+    presenter.apply(AppEvent::Agent(AgentEvent::ToolCallStarted {
+        name: "read_game_log".to_string(),
+        summary: format!("Authorization: Bearer {JWT}"),
+    }));
+    presenter.apply(AppEvent::Agent(AgentEvent::Failed {
+        message: format!("401: access_token={JWT}"),
+    }));
+    presenter.apply(AppEvent::Agent(AgentEvent::ConfirmRequested {
+        request: ConfirmRequest {
+            id: "req-jwt".to_string(),
+            tool: "set_config".to_string(),
+            summary: format!("把 access_token 改成 {JWT}"),
+            details: serde_json::json!({ "access_token": JWT, "note": JWT }),
+            sensitivity: Sensitivity::High,
+        },
+    }));
+
+    let rail = presenter.agent_rail();
+    let text = rail_text(rail);
+    assert!(
+        !text.contains("eyJhbGci"),
+        "rail 上不得出现 JWT 原文：{text}"
+    );
+    assert!(
+        text.contains("<redacted:token>"),
+        "应当被脱敏成占位符：{text}"
+    );
+    // 凭据键名的值整段打码（不只是靠内容规则）
+    let details = &rail.confirm.as_ref().expect("确认请求仍在").details;
+    assert_eq!(details["access_token"], "<redacted:token>");
+    assert!(!details["note"]
+        .as_str()
+        .unwrap_or_default()
+        .contains("eyJhbGci"));
+}
+
+/// 上一条测试里 `MessageAppended` 走的是 `agent_submit`（已先 scrub），踩不到 rail 自己的
+/// `scrub_message`。这条**绕过 submit** 直接投递，钉住那条入口（r1 P1 变异 A）。
+#[test]
+fn message_appended_from_the_backend_is_scrubbed_inside_the_rail() {
+    let mut presenter = presenter(Script::Qa);
+    presenter.apply(AppEvent::Agent(AgentEvent::MessageAppended(
+        ChatMessage::user(format!("access_token={JWT}")),
+    )));
+    presenter.apply(AppEvent::Agent(AgentEvent::MessageAppended(ChatMessage {
+        role: ChatRole::Assistant,
+        text: format!("听到你贴了 {JWT}"),
+        tool: None,
+        streaming: false,
+    })));
+    presenter.apply(AppEvent::Agent(AgentEvent::MessageAppended(
+        ChatMessage::system(format!("refresh_token={JWT}")),
+    )));
+
+    let text = rail_text(presenter.agent_rail());
+    assert!(
+        !text.contains("eyJhbGci"),
+        "MessageAppended 入口未脱敏：{text}"
+    );
+    assert_eq!(
+        presenter.agent_rail().messages.len(),
+        3,
+        "三条消息都要在（脱敏不等于丢消息）"
+    );
+}
+
+/// 工具**收尾**事件（`ToolCallFinished`）同样带 name + summary，必须过闸门（r1 P1 变异 C2）。
+///
+/// 两边用同一个「名字里带 JWT」的工具名：脱敏后仍然相等，所以**只要有一侧没脱敏**，
+/// 名字就对不上（条目收敛不了、`ok` 仍是 false），断言会红。
+#[test]
+fn tool_call_finished_summary_is_scrubbed_inside_the_rail() {
+    let mut presenter = presenter(Script::Qa);
+    let name = format!("set_config_{JWT}");
+    presenter.apply(AppEvent::Agent(AgentEvent::ToolCallStarted {
+        name: name.clone(),
+        summary: "修改 download.concurrency".to_string(),
+    }));
+    presenter.apply(AppEvent::Agent(AgentEvent::ToolCallFinished {
+        name,
+        ok: true,
+        summary: format!("写进去了：Authorization: Bearer {JWT}"),
+    }));
+
+    let text = rail_text(presenter.agent_rail());
+    assert!(
+        !text.contains("eyJhbGci"),
+        "ToolCallFinished 入口未脱敏：{text}"
+    );
+    let tool = presenter.agent_rail().messages[0]
+        .tool
+        .as_ref()
+        .expect("工具条目");
+    assert!(tool.ok, "结论位要照实写");
+    assert!(!tool.name.contains("eyJhbGci"), "工具名也要过闸门");
+}
+
+/// 非 JWT 形状的凭据（`{"password":"hunter2"}`）只能靠**键名**规则拦（r1 P1 变异 H）。
+///
+/// 同时钉住「值随 path 敏感」这条上下文规则（`set_config` 的 details 形状）。
+#[test]
+fn sensitive_keys_in_confirm_details_are_masked_without_jwt_shape() {
+    let mut presenter = presenter(Script::Qa);
+    presenter.apply(AppEvent::Agent(AgentEvent::ConfirmRequested {
+        request: ConfirmRequest {
+            id: "req-keys".to_string(),
+            tool: "set_config".to_string(),
+            summary: "改几个设置".to_string(),
+            details: serde_json::json!({
+                "password": "hunter2",
+                "api_key": "short-key-123",
+                "nested": { "refresh_token": "rt-1" },
+                "list": [{ "token": "xyz" }],
+                "plain": "nothing here",
+                "path": "ai.api_key",
+                "old": "",
+                "new": "sk-proj-abcdefghijklmnop",
+            }),
+            sensitivity: Sensitivity::High,
+        },
+    }));
+
+    let details = &presenter
+        .agent_rail()
+        .confirm
+        .as_ref()
+        .expect("确认请求")
+        .details;
+    let placeholder = serde_json::json!("<redacted:token>");
+    // 键名命中：对象 / 嵌套 / 数组各一
+    assert_eq!(details["password"], placeholder);
+    assert_eq!(details["api_key"], placeholder);
+    assert_eq!(details["nested"]["refresh_token"], placeholder);
+    assert_eq!(details["list"][0]["token"], placeholder);
+    // 值随 path 敏感：old/new 一并掩码（不然 API key 就躺在确认弹窗的 diff 里）
+    assert_eq!(details["new"], placeholder);
+    assert_eq!(details["old"], placeholder);
+    // 无关键原样保留（审计要看得出改的是什么）
+    assert_eq!(details["plain"], serde_json::json!("nothing here"));
+    assert_eq!(details["path"], serde_json::json!("ai.api_key"));
+
+    let text = rail_text(presenter.agent_rail());
+    for leak in [
+        "hunter2",
+        "short-key-123",
+        "rt-1",
+        "xyz",
+        "sk-proj-abcdefghijklmnop",
+    ] {
+        assert!(!text.contains(leak), "凭据泄漏到 rail：{leak} / {text}");
+    }
+}
+
+/// 短 `Bearer` 令牌不是 JWT 形状，core 的 `Redactor` 会放过它（r1 P2-1）。
+#[test]
+fn short_bearer_token_is_masked() {
+    let mut presenter = presenter(Script::Qa);
+    presenter.apply(AppEvent::Agent(AgentEvent::ToolCallStarted {
+        name: "read_game_log".to_string(),
+        summary: "Authorization: Bearer abcdef123456".to_string(),
+    }));
+    let text = rail_text(presenter.agent_rail());
+    assert!(
+        !text.contains("abcdef123456"),
+        "短 Bearer 令牌要掩码：{text}"
+    );
+    assert!(text.contains("Bearer <redacted:token>"), "{text}");
+}
+
+#[test]
+fn scrub_text_is_idempotent_on_already_redacted_text() {
+    let once = scrub_text(JWT);
+    assert_eq!(scrub_text(&once), once);
+    let bearer = scrub_text("Authorization: Bearer abcdef123456");
+    assert_eq!(scrub_text(&bearer), bearer);
+}
+
+// ───────────────── 出站闸门：发给后端的那份 payload ─────────────────
+
+/// 记录 `submit` 实参的后端替身：红线里最重要的是「**真正发出去的是什么**」，
+/// 而不是 rail 上显示成什么（显示层自己还会再脱一次，会把出站的漏洞盖住）。
+#[derive(Clone, Default)]
+struct RecordingTransport {
+    seen: Rc<RefCell<Vec<String>>>,
+}
+
+impl AgentTransport for RecordingTransport {
+    fn submit(&mut self, text: &str, _history: &AgentRail) -> Result<Vec<AppEvent>, String> {
+        self.seen.borrow_mut().push(text.to_string());
+        // 照常回一条用户气泡，让整轮流程跟真实后端一致（rail 会再脱一次，所以
+        // 只断言 rail 干净是抓不住出站泄漏的）
+        Ok(vec![AppEvent::Agent(AgentEvent::MessageAppended(
+            ChatMessage::user(text),
+        ))])
+    }
+
+    fn confirm(&mut self, _request_id: &str, _accept: bool) -> Vec<AppEvent> {
+        Vec::new()
+    }
+}
+
+/// 一律报错的后端替身（用来守 Err 文案那道 scrub）。
+struct ErrorTransport(String);
+
+impl AgentTransport for ErrorTransport {
+    fn submit(&mut self, _text: &str, _history: &AgentRail) -> Result<Vec<AppEvent>, String> {
+        Err(self.0.clone())
+    }
+
+    fn confirm(&mut self, _request_id: &str, _accept: bool) -> Vec<AppEvent> {
+        Vec::new()
+    }
+}
+
+/// 出站守卫（r2 P1）：`agent_submit` 送去后端的那句 prompt 必须已经脱敏。
+///
+/// 关键在**看后端收到什么**：rail 侧也会脱敏，所以「界面上没有 JWT」证明不了出站安全。
+#[test]
+fn outbound_prompt_is_scrubbed_before_it_reaches_the_backend() {
+    let seen = Rc::new(RefCell::new(Vec::new()));
+    let mut presenter = Presenter::new(Box::new(RecordingTransport {
+        seen: Rc::clone(&seen),
+    }));
+    presenter
+        .agent_submit(format!("帮我看看这个 token：{JWT}"))
+        .expect("提交应当成功");
+
+    let seen = seen.borrow();
+    assert_eq!(seen.len(), 1, "一轮输入只该发一次");
+    assert!(
+        !seen[0].contains("eyJhbGci"),
+        "出站 prompt 里还有 JWT 原文：{}",
+        seen[0]
+    );
+    assert!(
+        seen[0].contains("<redacted:token>"),
+        "出站 prompt 应当带占位符：{}",
+        seen[0]
+    );
+}
+
+/// 失败原因（provider 的 401 常把 key 抄进 message）同样是 UI 可见文本（r2 P2-1 / N）。
+#[test]
+fn outbound_error_text_is_scrubbed() {
+    let mut presenter = Presenter::new(Box::new(ErrorTransport(format!(
+        "401 Unauthorized: key={JWT}"
+    ))));
+    let error = presenter
+        .agent_submit("随便问一句".to_string())
+        .expect_err("后端报错时应当返回 Err");
+    assert!(!error.contains("eyJhbGci"), "Err 文案里还有 JWT：{error}");
+    assert!(error.contains("<redacted:token>"), "{error}");
+}
+
+// ─────────── 显示闸门：另三处 scrub 站点（r2 P2-1 / K、M）───────────
+
+/// `ConfirmRequest.tool` 也过闸门（工具名来自注册表，凭据落名字不现实，但「删了没人发现」）。
+#[test]
+fn confirm_tool_name_is_scrubbed() {
+    let mut presenter = presenter(Script::Qa);
+    presenter.apply(AppEvent::Agent(AgentEvent::ConfirmRequested {
+        request: ConfirmRequest {
+            id: "req-tool".to_string(),
+            tool: format!("set_config_{JWT}"),
+            summary: "改设置".to_string(),
+            details: serde_json::json!({}),
+            sensitivity: Sensitivity::High,
+        },
+    }));
+
+    let tool = &presenter
+        .agent_rail()
+        .confirm
+        .as_ref()
+        .expect("确认请求")
+        .tool;
+    assert!(!tool.contains("eyJhbGci"), "confirm.tool 未脱敏：{tool}");
+    assert!(!rail_text(presenter.agent_rail()).contains("eyJhbGci"));
+}
+
+/// `MessageAppended` 里带 `ToolCallView` 的那条分支（role = Tool）也要脱敏——
+/// mock 只会发 user，只有真实后端会走到，所以必须单独钉住。
+#[test]
+fn tool_message_from_the_backend_has_its_tool_view_scrubbed() {
+    let mut presenter = presenter(Script::Qa);
+    presenter.apply(AppEvent::Agent(AgentEvent::MessageAppended(ChatMessage {
+        role: ChatRole::Tool,
+        text: format!("工具摘要：{JWT}"),
+        tool: Some(ToolCallView {
+            name: format!("read_game_log_{JWT}"),
+            ok: true,
+            summary: format!("Authorization: Bearer {JWT}"),
+        }),
+        streaming: false,
+    })));
+
+    let tool = presenter.agent_rail().messages[0]
+        .tool
+        .as_ref()
+        .expect("工具条目");
+    assert!(
+        !tool.name.contains("eyJhbGci"),
+        "tool.name 未脱敏：{}",
+        tool.name
+    );
+    assert!(
+        !tool.summary.contains("eyJhbGci"),
+        "tool.summary 未脱敏：{}",
+        tool.summary
+    );
+    assert!(!rail_text(presenter.agent_rail()).contains("eyJhbGci"));
+}
+
+// ───────────────────────── 断言辅助 ─────────────────────────
+
+/// 把 rail 上所有对用户可见的文本拼起来（红线断言用）。
+///
+/// **不含 `draft`**（见模块文档：草稿按设计可以存原文）。
+fn rail_text(rail: &AgentRail) -> String {
+    let mut out = String::new();
+    for message in &rail.messages {
+        out.push_str(&message.text);
+        if let Some(tool) = &message.tool {
+            out.push_str(&tool.name);
+            out.push_str(&tool.summary);
+        }
+    }
+    out.push_str(rail.error.as_deref().unwrap_or_default());
+    out.push_str(&rail.endpoint_label);
+    if let Some(confirm) = &rail.confirm {
+        out.push_str(&confirm.tool);
+        out.push_str(&confirm.summary);
+        out.push_str(&confirm.details.to_string());
+    }
+    out
+}
diff --git a/crates/presenter/src/backend.rs b/crates/presenter/src/backend.rs
new file mode 100644
index 0000000..1669aec
--- /dev/null
+++ b/crates/presenter/src/backend.rs
@@ -0,0 +1,36 @@
+//! 后端选择与启动选项：真实 core host 优先，解析不出数据根时退回 mock。
+
+use std::path::{Path, PathBuf};
+
+use crate::dto::Backend;
+use crate::host::CoreHost;
+use crate::host::HostEnv;
+use crate::mock::MockBackend;
+
+/// 启动选项（截图/演示通道用；正常启动全用默认值）。
+#[derive(Debug, Clone, Default)]
+pub struct AppOptions {
+    /// 钉死数据根（`<root>/.ULL` + `<root>/.minecraft`）；None = 按便携配置解析
+    pub data_root: Option<PathBuf>,
+    /// 强制 mock 后端（UI 回归/无数据根演示）
+    pub mock: bool,
+}
+
+/// `<root>/.ULL/config/launcher.json`（与 `SettingsBridge::open` 同落点）。
+pub fn config_path(root: &Path) -> PathBuf {
+    root.join(".ULL").join("config").join("launcher.json")
+}
+
+/// 选后端：真实 host 优先；数据根解析不出来或显式 `--mock` 时退回假后端。
+pub fn build_backend(options: &AppOptions) -> Box<dyn Backend> {
+    if options.mock {
+        return Box::new(MockBackend::new());
+    }
+    match &options.data_root {
+        Some(root) => Box::new(CoreHost::new(HostEnv::at_root(root))),
+        None => match CoreHost::open() {
+            Some(host) => Box::new(host),
+            None => Box::new(MockBackend::new()),
+        },
+    }
+}
diff --git a/crates/presenter/src/dialogs.rs b/crates/presenter/src/dialogs.rs
new file mode 100644
index 0000000..542eb8b
--- /dev/null
+++ b/crates/presenter/src/dialogs.rs
@@ -0,0 +1,305 @@
+//! 对话框队列（HMCL 队列语义 + Metro 化，09 §3）。
+//!
+//! 语义：**一次只显示一条**。新请求按来源插队（用户操作 > 后台任务 > 提示），同来源 FIFO；
+//! 当前条被确认/取消后由 [`DialogQueue::advance`] 推进到下一条，UI 只渲染 `current`。
+//! 非阻塞提示走 [`crate::toast`]，不占模态队列。
+
+use serde::{Deserialize, Serialize};
+
+/// 对话框标识。
+pub type DialogId = u64;
+
+/// 对话框来源：决定插队优先级。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+pub enum DialogSource {
+    /// 提示类（教程、首次使用说明）
+    Hint = 0,
+    /// 后台任务（下载完成、需要选择镜像源）
+    BackgroundTask = 1,
+    /// 用户操作触发（AI 敏感写操作的二次确认）
+    UserAction = 2,
+}
+
+impl DialogSource {
+    /// 数值越大越优先。
+    pub fn priority(self) -> u8 {
+        self as u8
+    }
+}
+
+/// 对话框类型（09 §3：确认 / 进度 / 输入 / 错误）。
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub enum DialogKind {
+    /// 确认：主按钮 + 次按钮
+    Confirm {
+        /// 主按钮文字（如「允许」）
+        primary: String,
+        /// 次按钮文字（如「拒绝」）
+        secondary: String,
+    },
+    /// 输入：单行文本
+    Input {
+        /// 输入框标签
+        label: String,
+        /// 初始值
+        value: String,
+        /// 主按钮文字
+        primary: String,
+    },
+    /// 进度：不可点主按钮（任务结束后由 [`crate::dto::AppEvent::DialogClosed`] 收起）
+    Progress {
+        /// 阶段文案
+        label: String,
+        /// 0.0~1.0
+        progress: f32,
+    },
+    /// 错误：含诊断入口提示
+    Error {
+        /// 主按钮文字
+        primary: String,
+        /// 诊断/修复提示
+        hint: Option<String>,
+    },
+}
+
+impl DialogKind {
+    /// 主按钮文字。
+    pub fn primary_label(&self) -> &str {
+        match self {
+            Self::Confirm { primary, .. }
+            | Self::Input { primary, .. }
+            | Self::Error { primary, .. } => primary,
+            Self::Progress { .. } => "取消",
+        }
+    }
+
+    /// 次按钮文字（None 表示不显示次按钮）。
+    pub fn secondary_label(&self) -> Option<&str> {
+        match self {
+            Self::Confirm { secondary, .. } => Some(secondary),
+            Self::Error { .. } => Some("忽略"),
+            Self::Input { .. } | Self::Progress { .. } => None,
+        }
+    }
+
+    /// 是否可交互（进度条不可点主按钮）。
+    pub fn is_blocking_progress(&self) -> bool {
+        matches!(self, Self::Progress { .. })
+    }
+}
+
+/// 一条对话框请求。
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct DialogRequest {
+    /// 队列内唯一 id（由 [`DialogQueue::push_request`] 重新编号）
+    pub id: DialogId,
+    /// 来源（决定插队优先级）
+    pub source: DialogSource,
+    /// 标题
+    pub title: String,
+    /// 正文
+    pub body: String,
+    /// 类型与按钮
+    pub kind: DialogKind,
+}
+
+/// 模态队列：一次一条 + 来源插队。
+#[derive(Debug, Default)]
+pub struct DialogQueue {
+    current: Option<DialogRequest>,
+    pending: Vec<DialogRequest>,
+    next_id: DialogId,
+}
+
+impl DialogQueue {
+    /// 新建空队列。
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// 当前应显示的对话框。
+    pub fn current(&self) -> Option<&DialogRequest> {
+        self.current.as_ref()
+    }
+
+    /// 排队中（不含当前）条数。
+    pub fn pending_len(&self) -> usize {
+        self.pending.len()
+    }
+
+    /// 是否完全没有对话框（当前 + 排队）。
+    pub fn is_empty(&self) -> bool {
+        self.current.is_none() && self.pending.is_empty()
+    }
+
+    /// 入队一条请求（UI 内部调用方用，id 由队列自增分配）。没有当前条时立即成为当前条。
+    ///
+    /// 返回值用于后续 [`Self::close`] / 进度更新。
+    pub fn push(
+        &mut self,
+        source: DialogSource,
+        title: impl Into<String>,
+        body: impl Into<String>,
+        kind: DialogKind,
+    ) -> DialogId {
+        self.next_id += 1;
+        self.push_request(DialogRequest {
+            id: self.next_id,
+            source,
+            title: title.into(),
+            body: body.into(),
+            kind,
+        })
+    }
+
+    /// 入队一条已经组装好的请求（事件通道用）。
+    ///
+    /// **id 归生产者**：这里原样保留 `request.id`（不重编号），因为关闭事件
+    /// [`crate::dto::AppEvent::DialogClosed`] 携带的是生产者 id；重编号会让
+    /// 「任务完成 → 自动收起进度框」在多来源弹框时静默失配。生产者负责自身 id 唯一。
+    pub fn push_request(&mut self, request: DialogRequest) -> DialogId {
+        let id = request.id;
+        let source = request.source;
+        if self.current.is_none() {
+            self.current = Some(request);
+        } else {
+            let at = self
+                .pending
+                .iter()
+                .position(|queued| queued.source < source)
+                .unwrap_or(self.pending.len());
+            self.pending.insert(at, request);
+        }
+        id
+    }
+
+    /// 关闭指定对话框：若是当前条则推进到下一条，否则从队列移除。
+    ///
+    /// 返回 `true` 表示确实移除了。
+    pub fn close(&mut self, id: DialogId) -> bool {
+        if self
+            .current
+            .as_ref()
+            .is_some_and(|current| current.id == id)
+        {
+            self.advance();
+            return true;
+        }
+        if let Some(at) = self.pending.iter().position(|queued| queued.id == id) {
+            self.pending.remove(at);
+            return true;
+        }
+        false
+    }
+
+    /// 推进到下一条排队请求（当前条已被处理）。
+    pub fn advance(&mut self) {
+        self.current = if self.pending.is_empty() {
+            None
+        } else {
+            Some(self.pending.remove(0))
+        };
+    }
+
+    /// 关闭当前条并推进到下一条（确认 / 取消 / 点遮罩都走这里）。
+    ///
+    /// 返回 `false` 表示本来就没有当前条（幂等，双击不会误推进队列）。
+    pub fn close_current(&mut self) -> bool {
+        if self.current.is_none() {
+            return false;
+        }
+        self.advance();
+        true
+    }
+
+    /// 更新进度对话框的进度（任务回调直接喂进来）。
+    pub fn update_progress(&mut self, id: DialogId, progress: f32) {
+        let Some(current) = &mut self.current else {
+            return;
+        };
+        if current.id != id {
+            return;
+        }
+        if let DialogKind::Progress {
+            progress: value, ..
+        } = &mut current.kind
+        {
+            *value = progress.clamp(0.0, 1.0);
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{DialogKind, DialogQueue, DialogSource};
+
+    fn confirm() -> DialogKind {
+        DialogKind::Confirm {
+            primary: "确定".into(),
+            secondary: "取消".into(),
+        }
+    }
+
+    #[test]
+    fn shows_one_dialog_at_a_time() {
+        let mut queue = DialogQueue::new();
+        let first = queue.push(DialogSource::BackgroundTask, "A", "", confirm());
+        let second = queue.push(DialogSource::BackgroundTask, "B", "", confirm());
+
+        assert_eq!(queue.current().map(|d| d.id), Some(first));
+        assert_eq!(queue.pending_len(), 1);
+
+        queue.advance();
+        assert_eq!(queue.current().map(|d| d.id), Some(second));
+        assert_eq!(queue.pending_len(), 0);
+
+        queue.advance();
+        assert!(queue.is_empty());
+    }
+
+    #[test]
+    fn user_action_jumps_the_queue() {
+        let mut queue = DialogQueue::new();
+        queue.push(DialogSource::Hint, "提示", "", confirm());
+        queue.push(DialogSource::Hint, "提示2", "", confirm());
+        queue.push(DialogSource::BackgroundTask, "后台", "", confirm());
+        let urgent = queue.push(DialogSource::UserAction, "确认删除", "", confirm());
+
+        // 当前仍是队首（一次一条），但排队里用户操作插到最前 → 关掉当前条后立刻轮到它
+        queue.advance();
+        assert_eq!(queue.current().map(|d| d.id), Some(urgent));
+    }
+
+    #[test]
+    fn closing_non_current_dialog_removes_it_from_pending() {
+        let mut queue = DialogQueue::new();
+        let first = queue.push(DialogSource::Hint, "A", "", confirm());
+        let second = queue.push(DialogSource::Hint, "B", "", confirm());
+
+        assert!(queue.close(second));
+        assert_eq!(queue.pending_len(), 0);
+        assert_eq!(queue.current().map(|d| d.id), Some(first));
+        assert!(!queue.close(999));
+    }
+
+    #[test]
+    fn progress_dialog_can_be_updated() {
+        let mut queue = DialogQueue::new();
+        let id = queue.push(
+            DialogSource::BackgroundTask,
+            "下载中",
+            "",
+            DialogKind::Progress {
+                label: "资源".into(),
+                progress: 0.0,
+            },
+        );
+        queue.update_progress(id, 1.7);
+        match queue.current().map(|d| &d.kind) {
+            Some(DialogKind::Progress { progress, .. }) => {
+                assert!((*progress - 1.0).abs() < f32::EPSILON);
+            }
+            other => panic!("unexpected dialog kind: {other:?}"),
+        }
+    }
+}
diff --git a/crates/presenter/src/dto/accounts.rs b/crates/presenter/src/dto/accounts.rs
new file mode 100644
index 0000000..eda6885
--- /dev/null
+++ b/crates/presenter/src/dto/accounts.rs
@@ -0,0 +1,395 @@
+//! 账户页 DTO：三条轨道的统一抽象 + 微软登录（设备码 / 授权码浏览器）的可见状态。
+//!
+//! **凭据红线**：本模块（以及整个 `crate::dto`）只有 [`AccountView`] 这种公开字段视图。
+//! `core::auth` 的 `Credentials` / `MicrosoftSession` / token 永远不进 app 层——
+//! host 侧在拿到账户快照的那一刻就丢掉凭据，只留「能显示什么」。
+//!
+//! | 文件 | 职责 |
+//! |---|---|
+//! | 本文件 | 账户/登录**可见状态**（全部是可上屏字段） |
+//! | [`redact`] | 形状脱敏：JWT / 不透明串 / `token=...` 一律抹掉（第二道脱敏器） |
+//! | `tests` | 契约 round-trip + 凭据红线的入口断言 |
+
+mod failure;
+mod kind;
+mod name;
+mod redact;
+#[cfg(test)]
+#[path = "accounts/tests.rs"]
+mod tests;
+
+pub use failure::{AccountNotice, AccountNoticeCode, LoginFailure};
+pub use kind::AccountKind;
+pub use name::valid_offline_name;
+pub use redact::{looks_like_jwt, redact, REDACTED};
+
+use serde::{Deserialize, Serialize};
+
+/// 账户列表行（**只含可公开字段**）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AccountView {
+    /// 稳定 id（`account:...`）
+    pub id: String,
+    /// 展示名
+    pub name: String,
+    /// 轨道
+    pub kind: AccountKind,
+    /// 档案 UUID（公开）
+    pub profile_id: String,
+    /// 登录名（微软轨才有；可空）
+    pub login_name: String,
+    /// 创建时间展示串（`2026-10-31 20:12`）
+    ///
+    /// 口径：core 的 `AccountMeta` 只有 `created_at_ms`，**没有 last-used**，所以列表上贴的是
+    /// 「添加于 {created}」，不伪造「最近使用」（缺口登记在 M114 报告）。
+    pub created: String,
+    /// 是否是当前启动使用的账户
+    pub active: bool,
+    /// 第三方轨的认证服务器 API 根（其余轨为空串）
+    #[serde(default)]
+    pub server_url: String,
+    /// 皮肤原图（第三方轨才可能有；`None` = 没有/没取到，UI 退回首字母块）
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub skin: Option<SkinImage>,
+}
+
+impl AccountView {
+    /// 首字母块上的字：展示名第一个非空字符（大写化），空名字回落 `?`。
+    ///
+    /// 放在 DTO 而不是页面里，是为了「没有皮肤时画什么」这件事只有一处判据，两个 UI 版一致。
+    #[must_use]
+    pub fn monogram(&self) -> String {
+        self.name
+            .chars()
+            .find(|c| !c.is_whitespace())
+            .map(|c| c.to_uppercase().to_string())
+            .unwrap_or_else(|| "?".to_string())
+    }
+
+    /// 首字母块的取色索引（0..6）：由 `profile_id` 稳定推导，同一个人每次都是同一个色块。
+    #[must_use]
+    pub fn monogram_tone(&self) -> u8 {
+        let mut hash: u32 = 2_166_136_261;
+        for byte in self.profile_id.as_bytes() {
+            hash ^= u32::from(*byte);
+            hash = hash.wrapping_mul(16_777_619);
+        }
+        u8::try_from(hash % 6).unwrap_or(0)
+    }
+}
+
+/// 一张皮肤原图。
+///
+/// **停在「原图」这一层是刻意的**：presenter 不引入图片解码依赖（`presenter-no-ui` +
+/// 依赖极简），裁剪/缩放/取首字母块都由 UI 层自己做。离线轨永远没有它——没有皮肤就不给假皮肤。
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct SkinImage {
+    /// PNG 字节（Minecraft 皮肤：64×64 或旧版 64×32）
+    pub png: Vec<u8>,
+    /// 来源 URL（**只进取证日志，不上屏**）
+    pub source: String,
+}
+
+impl SkinImage {
+    /// 是否有可用字节（0 字节等同没有皮肤）。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.png.is_empty()
+    }
+}
+
+/// 微软登录阶段（UI 据此切换面板；两条流共用）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum DeviceLoginPhase {
+    /// 没有登录在进行
+    Idle,
+    /// 正在向微软申请设备码（短暂）
+    Requesting,
+    /// 已拿到用户码，等待用户在浏览器完成
+    Waiting,
+    /// 成功（账户已入库）
+    Succeeded,
+    /// 失败（原因在 `message`，已脱敏）
+    Failed,
+}
+
+impl DeviceLoginPhase {
+    /// 面板是否要显示（非 Idle 都显示）。
+    pub fn visible(self) -> bool {
+        !matches!(self, Self::Idle)
+    }
+
+    /// 是否还在跑（Requesting / Waiting）。
+    pub fn busy(self) -> bool {
+        matches!(self, Self::Requesting | Self::Waiting)
+    }
+}
+
+/// 设备码登录的可见状态。
+///
+/// `user_code` / `verification_uri` 来自 `core::auth::microsoft::DeviceCodePrompt`——
+/// 它们本来就是给用户看的，不是凭据。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct DeviceLoginView {
+    /// 阶段
+    pub phase: DeviceLoginPhase,
+    /// 用户码（`ABCD-EFGH`）
+    pub user_code: String,
+    /// 验证地址（`https://www.microsoft.com/link`）
+    pub verification_uri: String,
+    /// 二维码内容（= 带码的链接；GUI 用文本展示，终端可直接打开）
+    pub qr_link: String,
+    /// 有效期（秒；0 = 未知）
+    pub expires_in: u64,
+    /// 状态/错误文案（**失败时是原始诊断，只进日志，不上屏**）
+    pub message: String,
+    /// 失败原因码（`None` = 不是失败态 / 未分类）
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub failure: Option<LoginFailure>,
+    /// 成功后入库的账户展示名
+    pub account_name: String,
+}
+
+impl Default for DeviceLoginView {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl DeviceLoginView {
+    /// 空闲态。
+    pub fn new() -> Self {
+        Self {
+            phase: DeviceLoginPhase::Idle,
+            user_code: String::new(),
+            verification_uri: String::new(),
+            qr_link: String::new(),
+            expires_in: 0,
+            message: String::new(),
+            failure: None,
+            account_name: String::new(),
+        }
+    }
+
+    /// 已拿到用户码（`present` 回调时刻）。
+    pub fn waiting(
+        user_code: &str,
+        verification_uri: &str,
+        expires_in: u64,
+        qr_hint: &str,
+    ) -> Self {
+        let qr_link = if qr_hint.is_empty() {
+            format!("{verification_uri}?code={user_code}")
+        } else {
+            qr_hint.to_string()
+        };
+        Self {
+            phase: DeviceLoginPhase::Waiting,
+            user_code: user_code.to_string(),
+            verification_uri: verification_uri.to_string(),
+            qr_link,
+            expires_in,
+            message: format!(
+                "在浏览器打开 {verification_uri} 并输入用户码 {user_code}（{} 秒内有效）",
+                expires_in
+            ),
+            failure: None,
+            account_name: String::new(),
+        }
+    }
+
+    /// 授权码流：本地回调已就绪、浏览器已拉起（`present` 回调时刻）。
+    ///
+    /// 面板不展示用户码，改展示**可复制的授权链接**（用户可能需要在另一台设备/
+    /// 另一个浏览器里手动打开）；`warning` 是「浏览器没拉起来」这类非致命提示。
+    pub fn browser_waiting(
+        authorization_url: &str,
+        expires_in: u64,
+        warning: Option<&str>,
+    ) -> Self {
+        let mut message = format!(
+            "已在系统浏览器打开微软登录页，请完成授权（{} 秒内有效）；没弹出就把下面的链接粘到浏览器里",
+            expires_in.max(1)
+        );
+        if let Some(warning) = warning {
+            message.push_str(&format!("（{}）", redact(warning)));
+        }
+        Self {
+            phase: DeviceLoginPhase::Waiting,
+            user_code: String::new(),
+            verification_uri: authorization_url.to_string(),
+            qr_link: authorization_url.to_string(),
+            expires_in,
+            message,
+            failure: None,
+            account_name: String::new(),
+        }
+    }
+
+    /// 失败态（文案在入口就脱敏：错误原文里可能带着服务端回显的 token）。
+    pub fn failed(message: impl Into<String>) -> Self {
+        Self::failed_as(LoginFailure::Other, message)
+    }
+
+    /// 带**原因码**的失败态（页面据码出 i18n；原文只进日志）。
+    pub fn failed_as(failure: LoginFailure, message: impl Into<String>) -> Self {
+        Self {
+            phase: DeviceLoginPhase::Failed,
+            message: redact(&message.into()),
+            failure: Some(failure),
+            ..Self::new()
+        }
+    }
+
+    /// 成功态。
+    pub fn succeeded(account_name: impl Into<String>) -> Self {
+        let account_name = account_name.into();
+        Self {
+            phase: DeviceLoginPhase::Succeeded,
+            message: format!("已登录：{account_name}"),
+            failure: None,
+            account_name,
+            ..Self::new()
+        }
+    }
+}
+
+/// 第三方轨（authlib-injector）登录请求。
+///
+/// **凭据红线**：`password` 只是「用户这一次输入的请求值」，从页面流到 host 的
+/// `AuthlibAuth::authenticate` 调用栈里，host 取走即弃——不入账户库、不进日志、
+/// 不进任何回程 DTO。所以本类型只有一个方向（UI → host），回程只有 [`AuthlibLoginView`]。
+#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AuthlibRequest {
+    /// 认证服务器地址（用户原样输入；host 侧 `normalize_api_root` 规范化）
+    pub server: String,
+    /// 登录名（邮箱或用户名）
+    pub login: String,
+    /// 密码（只在本调用栈里出现）
+    pub password: String,
+}
+
+/// **手写 `Debug`**：任何 `{:?}`（日志/panic 消息/测试失败输出）都不得带出明文密码。
+impl std::fmt::Debug for AuthlibRequest {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("AuthlibRequest")
+            .field("server", &redact(&self.server))
+            .field("login", &redact(&self.login))
+            .field("password", &REDACTED)
+            .finish()
+    }
+}
+
+impl AuthlibRequest {
+    /// 构造。
+    pub fn new(
+        server: impl Into<String>,
+        login: impl Into<String>,
+        password: impl Into<String>,
+    ) -> Self {
+        Self {
+            server: server.into(),
+            login: login.into(),
+            password: password.into(),
+        }
+    }
+
+    /// 可打印形态（日志/诊断/错误路径用）：**密码恒被抹掉**。
+    #[must_use]
+    pub fn redacted(&self) -> String {
+        format!(
+            "server={} login={} password={REDACTED}",
+            redact(&self.server),
+            redact(&self.login)
+        )
+    }
+}
+
+/// 第三方轨登录的可见状态（阶段复用 [`DeviceLoginPhase`]：都是「申请 → 等待 → 成/败」）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AuthlibLoginView {
+    /// 阶段
+    pub phase: DeviceLoginPhase,
+    /// 认证服务器地址（规范化后的 API 根）
+    pub server: String,
+    /// 服务发现里的服务器名（校验通过后才有；空 = 没校验/没名字）
+    pub server_name: String,
+    /// 状态/错误文案（**失败时是原始诊断，只进日志，不上屏**）
+    pub message: String,
+    /// 失败原因码（`None` = 不是失败态 / 未分类）
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub failure: Option<LoginFailure>,
+    /// 成功后入库的账户展示名
+    pub account_name: String,
+}
+
+impl Default for AuthlibLoginView {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl AuthlibLoginView {
+    /// 空闲态。
+    pub fn new() -> Self {
+        Self {
+            phase: DeviceLoginPhase::Idle,
+            server: String::new(),
+            server_name: String::new(),
+            message: String::new(),
+            failure: None,
+            account_name: String::new(),
+        }
+    }
+
+    /// 进行中（校验服务器地址 / 换 token）。
+    pub fn running(server: &str, message: &str) -> Self {
+        Self {
+            phase: DeviceLoginPhase::Requesting,
+            server: server.to_string(),
+            server_name: String::new(),
+            message: redact(message),
+            failure: None,
+            account_name: String::new(),
+        }
+    }
+
+    /// 地址校验通过（服务发现拿到了服务器名）。
+    pub fn reachable(server: &str, server_name: &str) -> Self {
+        Self {
+            phase: DeviceLoginPhase::Waiting,
+            server: server.to_string(),
+            server_name: redact(server_name),
+            message: format!("服务器可用：{}", server_name.trim()),
+            failure: None,
+            account_name: String::new(),
+        }
+    }
+
+    /// 失败态（文案在入口就脱敏）。
+    pub fn failed(message: impl Into<String>) -> Self {
+        Self::failed_as(LoginFailure::Other, message)
+    }
+
+    /// 带**原因码**的失败态（页面据码出 i18n；原文只进日志）。
+    pub fn failed_as(failure: LoginFailure, message: impl Into<String>) -> Self {
+        Self {
+            phase: DeviceLoginPhase::Failed,
+            message: redact(&message.into()),
+            failure: Some(failure),
+            ..Self::new()
+        }
+    }
+
+    /// 成功态。
+    pub fn succeeded(server_name: &str, account_name: impl Into<String>) -> Self {
+        let account_name = account_name.into();
+        Self {
+            phase: DeviceLoginPhase::Succeeded,
+            server_name: server_name.to_string(),
+            message: format!("已登录：{account_name}"),
+            account_name,
+            ..Self::new()
+        }
+    }
+}
diff --git a/crates/presenter/src/dto/accounts/failure.rs b/crates/presenter/src/dto/accounts/failure.rs
new file mode 100644
index 0000000..3d60ffe
--- /dev/null
+++ b/crates/presenter/src/dto/accounts/failure.rs
@@ -0,0 +1,132 @@
+//! 失败原因码与账户页横幅（M114 r2 / 复审 P1-1、P2-2）。
+//!
+//! ## 为什么这一层必须有
+//!
+//! core/presenter 的诊断串是中文人话。把它们直接画到英文界面上，就是复审 r1 那条 p1
+//! （「全英文界面里整句中文」）。根因不是 catalog 缺条目，而是**后端诊断串没有结构**：
+//! 页面除了原样画没有别的选择。
+//!
+//! 这里补的就是那个缺环——把「失败属于哪一类」「这次操作的结果是什么」变成**枚举**。
+//! 页面据 `code()` 选 i18n key 出标题 + 正文 + 一行 `Code: …`；原始诊断留在 `message` /
+//! `detail` 里，**只进日志与详细信息，不上屏**。
+//!
+//! 约束：`code()` 一律 ascii 且**不随语言变**（日志、测试、用户报障都靠它对齐）。
+
+use serde::{Deserialize, Serialize};
+
+use super::redact;
+
+/// 登录失败的**结构化原因码**（M114 r2 / 复审 P1-1）。
+///
+/// 为什么要有它：core/presenter 的诊断串是中文人话，**直接上屏**会让英文界面里出现整句中文
+/// （复审 r1 的 p1）。这里把「失败属于哪一类」变成**可判据的枚举**，页面据码选 i18n key 出
+/// 标题 + 正文 + 一个稳定 code；原始诊断只留在 `message` 里进日志/详细信息，**不上屏**。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum LoginFailure {
+    /// 服务器/微软明确拒绝（403、OAuth `error`、XErr）
+    Denied,
+    /// 应用注册还没获批（AADSTS7000218 一类「白名单未批」）
+    NotWhitelisted,
+    /// 网络不可达 / 超时
+    Unreachable,
+    /// 目标地址不是 authlib-injector 服务器（响应不是服务发现 JSON）
+    NotAuthlibServer,
+    /// 服务器拒绝了这个账号（密码错 / 账号不存在）
+    BadCredentials,
+    /// 服务器没有返回角色（账号还没创建角色）
+    NoProfile,
+    /// 落盘失败（账户库读写）
+    StoreFailed,
+    /// 其它（未知原因；原文只在 `message`）
+    Other,
+}
+
+impl LoginFailure {
+    /// 稳定的 ascii code（日志 / 页面「Code: …」/ 测试断言都用它，**不随语言变**）。
+    #[must_use]
+    pub const fn code(self) -> &'static str {
+        match self {
+            Self::Denied => "denied",
+            Self::NotWhitelisted => "whitelist_pending",
+            Self::Unreachable => "unreachable",
+            Self::NotAuthlibServer => "not_authlib_server",
+            Self::BadCredentials => "bad_credentials",
+            Self::NoProfile => "no_profile",
+            Self::StoreFailed => "store_failed",
+            Self::Other => "other",
+        }
+    }
+}
+
+/// 账户页的**一次性横幅**（添加/删除/切换的结果；页面据 `code` 选 i18n）。
+///
+/// 为什么不是 toast：app-iced 不渲染 toast（复审 r1 P2-2 实锤），发 toast 等于用户什么都看不到。
+/// 横幅是页面上的真实控件，用户点了「Create profile」失败后一定看得见。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AccountNotice {
+    /// 结果码（决定标题/正文/颜色）
+    pub code: AccountNoticeCode,
+    /// 涉及的账户名或服务器（拼进文案；可为空）
+    pub subject: String,
+    /// 原始诊断（已脱敏；**只进日志/详细信息，不上屏**）
+    pub detail: String,
+}
+
+impl AccountNotice {
+    /// 构造。
+    pub fn new(
+        code: AccountNoticeCode,
+        subject: impl Into<String>,
+        detail: impl Into<String>,
+    ) -> Self {
+        Self {
+            code,
+            subject: subject.into(),
+            detail: redact(&detail.into()),
+        }
+    }
+}
+
+/// 横幅的结果码。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum AccountNoticeCode {
+    /// 已添加
+    Added,
+    /// 已删除
+    Removed,
+    /// 已切换
+    Switched,
+    /// 名字不合法（长度/字符集）
+    OfflineNameInvalid,
+    /// 同名账户已存在
+    AccountExists,
+    /// 落盘失败
+    StoreFailed,
+    /// 找不到这个账户
+    NotFound,
+    /// 其它（原文在 `detail`）
+    Other,
+}
+
+impl AccountNoticeCode {
+    /// 是否是一个「失败」结果（决定横幅配色）。
+    #[must_use]
+    pub const fn is_failure(self) -> bool {
+        !matches!(self, Self::Added | Self::Removed | Self::Switched)
+    }
+
+    /// 稳定 ascii code（日志/测试用）。
+    #[must_use]
+    pub const fn code(self) -> &'static str {
+        match self {
+            Self::Added => "added",
+            Self::Removed => "removed",
+            Self::Switched => "switched",
+            Self::OfflineNameInvalid => "offline_name_invalid",
+            Self::AccountExists => "account_exists",
+            Self::StoreFailed => "store_failed",
+            Self::NotFound => "not_found",
+            Self::Other => "other",
+        }
+    }
+}
diff --git a/crates/presenter/src/dto/accounts/kind.rs b/crates/presenter/src/dto/accounts/kind.rs
new file mode 100644
index 0000000..e2e27a3
--- /dev/null
+++ b/crates/presenter/src/dto/accounts/kind.rs
@@ -0,0 +1,43 @@
+//! 账户轨道（三轨统一抽象，`09 §G6` / `D9`）。
+
+use serde::{Deserialize, Serialize};
+
+/// 账户轨道（三轨统一抽象，`09 §G6` / `D9`）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum AccountKind {
+    /// 离线账户（HMCL 兼容 UUID）
+    Offline,
+    /// 微软正版
+    Microsoft,
+    /// authlib-injector（第三方皮肤站）
+    Authlib,
+}
+
+impl AccountKind {
+    /// 徽标文字（CLI/终端用；GUI 走 i18n 词表，不读这里的中文）。
+    pub fn label(self) -> &'static str {
+        match self {
+            Self::Offline => "离线",
+            Self::Microsoft => "微软",
+            Self::Authlib => "第三方",
+        }
+    }
+
+    /// 稳定 id（事件/持久化用；与 core 的 `kind.as_str()` 同词表）。
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Offline => "offline",
+            Self::Microsoft => "microsoft",
+            Self::Authlib => "authlib_injector",
+        }
+    }
+
+    /// 从 core 的稳定 id 解析（未知轨道按离线处理，不让一个坏条目毁掉整个列表）。
+    pub fn parse(raw: &str) -> Self {
+        match raw {
+            "microsoft" => Self::Microsoft,
+            "authlib_injector" => Self::Authlib,
+            _ => Self::Offline,
+        }
+    }
+}
diff --git a/crates/presenter/src/dto/accounts/name.rs b/crates/presenter/src/dto/accounts/name.rs
new file mode 100644
index 0000000..1eb48e9
--- /dev/null
+++ b/crates/presenter/src/dto/accounts/name.rs
@@ -0,0 +1,29 @@
+//! 离线档案的名字契约（**UI 与 host 共用的同一个判据**）。
+//!
+//! 放在 `dto` 而不是 host 里：UI 用它决定「创建档案」按钮亮不亮，host 用它做写盘前校验。
+//! 两处各写一遍，迟早会漂成「按钮亮着但必然失败」——那正是复审 r1 P2-2 的一半。
+//! core 侧还有一道同名规则做兜底（`auth::offline::offline_meta`），这里只管界面这条。
+
+/// 3–16 位 ascii 字母 / 数字 / 下划线。
+#[must_use]
+pub fn valid_offline_name(name: &str) -> bool {
+    let len = name.chars().count();
+    (3..=16).contains(&len) && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_')
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn the_rule_is_three_to_sixteen_ascii_word_chars() {
+        assert!(valid_offline_name("Steve"));
+        assert!(valid_offline_name("a_1"));
+        assert!(valid_offline_name("abcdefghijklmnop"), "16 位是上限");
+        assert!(!valid_offline_name("ab"), "太短");
+        assert!(!valid_offline_name("abcdefghijklmnopq"), "太长");
+        assert!(!valid_offline_name("has space"));
+        assert!(!valid_offline_name("中文名字"), "非 ascii");
+        assert!(!valid_offline_name(""));
+    }
+}
diff --git a/crates/presenter/src/dto/accounts/redact.rs b/crates/presenter/src/dto/accounts/redact.rs
new file mode 100644
index 0000000..c855d25
--- /dev/null
+++ b/crates/presenter/src/dto/accounts/redact.rs
@@ -0,0 +1,144 @@
+//! 凭据红线的**形状脱敏**：把 JWT / 不透明 token / `token=...` 这类串从任何要上屏的文案里抹掉。
+//!
+//! ## 为什么还要第二道脱敏器
+//!
+//! `core::launch::redact` 是**按已知明文值**替换的（拿着会话里的 token 原串去抹）。这里要挡的是
+//! **没登记过的**字符串：服务端在错误响应里回显一个 token、HTTP 库把 header 拼进错误文案、
+//! 某段调试串被画到面板上。两者互补，缺一不可：
+//!
+//! | 场景 | `core::launch::redact` | 本模块 |
+//! |---|---|---|
+//! | 已知会话 token 出现在日志里 | ✅ | ❌（不知道明文） |
+//! | 服务端回包里的陌生 JWT 被画到错误面板 | ❌ | ✅ |
+//!
+//! 走形状识别（三段 base64url / 超长不透明串 / 敏感键名）就够拦住「一眼能看出是凭据」的串，
+//! 而普通文案（URL、用户码 `ABCD-EFGH`、服务器名）**一个字都不动**——脱敏器本身不能变成噪音源。
+
+/// 脱敏占位符（**故意刺眼**：宁可难看，也不许静默把凭据画到屏幕上）。
+pub const REDACTED: &str = "⟪redacted⟫";
+
+/// 把一段要上屏的文案里的凭据形状串抹掉（空白与其余字符**原样保留**）。
+#[must_use]
+pub fn redact(text: &str) -> String {
+    let mut out = String::with_capacity(text.len());
+    for piece in text.split_inclusive(char::is_whitespace) {
+        let split = piece.find(char::is_whitespace).unwrap_or(piece.len());
+        let (chunk, space) = piece.split_at(split);
+        out.push_str(&redact_chunk(chunk));
+        out.push_str(space);
+    }
+    out
+}
+
+/// 单个「词」的脱敏：① 敏感键名的值 ② 整个词本身就是凭据形状。
+fn redact_chunk(chunk: &str) -> String {
+    if let Some((key, _value)) = chunk.split_once('=') {
+        if is_sensitive_key(key) || looks_opaque(chunk) {
+            return format!("{key}={REDACTED}");
+        }
+    }
+    if looks_opaque(chunk) {
+        return REDACTED.to_string();
+    }
+    chunk.to_string()
+}
+
+/// 键名是否属于「它的值一定是凭据」（`accessToken` / `refresh_token` / `password` …）。
+fn is_sensitive_key(key: &str) -> bool {
+    let key = key
+        .trim_matches(|c: char| !c.is_alphanumeric() && c != '_' && c != '-')
+        .to_lowercase();
+    [
+        "token",
+        "secret",
+        "password",
+        "passwd",
+        "authorization",
+        "bearer",
+        "session",
+    ]
+    .iter()
+    .any(|needle| key.contains(needle))
+}
+
+/// 词的形状是否像凭据：① 三段 base64url（JWT）② 长度 ≥40 的不透明串。
+fn looks_opaque(chunk: &str) -> bool {
+    let trimmed = chunk.trim_matches(|c: char| {
+        !c.is_ascii_alphanumeric() && c != '_' && c != '-' && c != '.' && c != '+'
+    });
+    looks_like_jwt(trimmed) || (trimmed.len() >= 40 && trimmed.chars().all(is_base64url))
+}
+
+/// 是否是 JWT 形状：`header.payload.signature`，三段都非空且够长、全是 base64url 字符。
+///
+/// 公开是为了单测能直接钉这条判据（UI 侧「注入 JWT 必须被抹掉」的测试也用它）。
+#[must_use]
+pub fn looks_like_jwt(token: &str) -> bool {
+    let parts: Vec<&str> = token.split('.').collect();
+    parts.len() == 3
+        && parts
+            .iter()
+            .all(|part| part.len() >= 8 && part.chars().all(is_base64url))
+}
+
+/// base64url 字母表（含 `=` 填充与 `+`/`/` 的宽容分支）。
+fn is_base64url(c: char) -> bool {
+    c.is_ascii_alphanumeric() || matches!(c, '-' | '_' | '+' | '/' | '=' | '.')
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// 标准 JWT 形状（2 段 header/payload + 1 段签名）。
+    const JWT: &str =
+        "eyJhbGciOiJSUzI1NiIsIng1dCI6IkFCQyJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.c2lnbmF0dXJlLXZhbHVl";
+
+    #[test]
+    fn the_jwt_shape_judgement_is_not_a_length_heuristic() {
+        assert!(looks_like_jwt(JWT));
+        assert!(!looks_like_jwt("not.a.jwt"), "短段不算 JWT");
+        assert!(!looks_like_jwt("a.b.c.d"), "四段不算 JWT");
+        assert!(!looks_like_jwt("ABCD-EFGH"), "设备码不是 JWT");
+    }
+
+    #[test]
+    fn bare_jwts_and_sensitive_pairs_are_redacted() {
+        assert_eq!(redact(JWT), REDACTED);
+        assert_eq!(
+            redact(&format!("Bearer {JWT}")),
+            format!("Bearer {REDACTED}")
+        );
+        assert_eq!(
+            redact(&format!("accessToken={JWT}")),
+            format!("accessToken={REDACTED}")
+        );
+        // 敏感键名 + 短值（真实 refresh token 常常很短，靠键名兜）
+        assert_eq!(redact("password=hunter2"), format!("password={REDACTED}"));
+        assert_eq!(
+            redact("refresh_token=abc"),
+            format!("refresh_token={REDACTED}")
+        );
+    }
+
+    #[test]
+    fn ordinary_copy_is_left_byte_for_byte() {
+        for text in [
+            "在浏览器打开 https://www.microsoft.com/link 并输入 ABCD-EFGH",
+            "服务器不可达：dns error",
+            "HTTP 403 Forbidden — 该服务器要求白名单",
+            "",
+        ] {
+            assert_eq!(redact(text), text, "普通文案被改了：{text}");
+        }
+    }
+
+    #[test]
+    fn whitespace_and_line_breaks_survive() {
+        let text = format!("第一行 token={JWT}\n\n第二行  缩进");
+        let out = redact(&text);
+        assert!(out.contains("\n\n"), "{out}");
+        assert!(out.contains("  缩进"), "{out}");
+        assert!(!out.contains(JWT), "{out}");
+    }
+}
diff --git a/crates/presenter/src/dto/accounts/tests.rs b/crates/presenter/src/dto/accounts/tests.rs
new file mode 100644
index 0000000..e97f9cf
--- /dev/null
+++ b/crates/presenter/src/dto/accounts/tests.rs
@@ -0,0 +1,167 @@
+//! 账户 DTO 的契约测试（凭据红线的主要断言都在这里）。
+
+use super::*;
+
+#[test]
+fn kind_round_trips_through_stable_ids() {
+    for kind in [
+        AccountKind::Offline,
+        AccountKind::Microsoft,
+        AccountKind::Authlib,
+    ] {
+        assert_eq!(AccountKind::parse(kind.as_str()), kind);
+        assert!(!kind.label().is_empty());
+    }
+}
+
+#[test]
+fn device_login_view_never_carries_tokens() {
+    let view = DeviceLoginView::waiting("ABCD-EFGH", "https://www.microsoft.com/link", 900, "");
+    assert_eq!(view.phase, DeviceLoginPhase::Waiting);
+    assert!(view.phase.busy());
+    assert!(view.qr_link.contains("ABCD-EFGH"));
+    let json = serde_json::to_string(&view).expect("序列化");
+    for forbidden in ["token", "secret", "password", "refresh"] {
+        assert!(
+            !json.to_lowercase().contains(forbidden),
+            "视图里不该出现 {forbidden}"
+        );
+    }
+}
+
+#[test]
+fn browser_waiting_shows_a_copyable_link_instead_of_a_user_code() {
+    let view = DeviceLoginView::browser_waiting(
+        "https://login.microsoftonline.com/consumers/oauth2/v2.0/authorize?client_id=x",
+        300,
+        Some("拉起浏览器失败"),
+    );
+    assert_eq!(view.phase, DeviceLoginPhase::Waiting);
+    assert!(view.phase.busy());
+    assert!(view.user_code.is_empty(), "授权码流没有用户码");
+    assert_eq!(view.qr_link, view.verification_uri);
+    assert!(view.message.contains("浏览器"));
+    assert!(view.message.contains("拉起浏览器失败"), "{}", view.message);
+    let json = serde_json::to_string(&view).expect("序列化");
+    for forbidden in ["refresh", "mc-access"] {
+        assert!(!json.contains(forbidden), "视图里不该出现 {forbidden}");
+    }
+}
+
+#[test]
+fn succeeded_and_failed_clear_the_code() {
+    let ok = DeviceLoginView::succeeded("Steve");
+    assert_eq!(ok.phase, DeviceLoginPhase::Succeeded);
+    assert!(ok.user_code.is_empty());
+    let bad = DeviceLoginView::failed("网络超时");
+    assert_eq!(bad.phase, DeviceLoginPhase::Failed);
+    assert_eq!(bad.message, "网络超时");
+}
+
+/// 凭据红线（审核项）：JWT 形状串从**任何**入口进来都必须被抹掉。
+///
+/// 抓得住：`redact` 被摘掉、判据被放宽成「长度 ≥40 就行」、或者某个构造器绕过它。
+/// 抓不住：真实凭据的明文值（那是 `core::launch::redact` 的活儿，按已知值替换）。
+#[test]
+fn jwt_shaped_text_is_redacted_at_every_entry_point() {
+    let jwt =
+        "eyJhbGciOiJSUzI1NiIsIng1dCI6IkFCQyJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.c2lnbmF0dXJlLXZhbHVl";
+
+    let device = DeviceLoginView::failed(format!("登录失败：accessToken={jwt}"));
+    assert!(!device.message.contains(jwt), "{}", device.message);
+    assert!(device.message.contains(REDACTED), "{}", device.message);
+
+    let authlib = AuthlibLoginView::failed(format!("服务器回包异常 {jwt}"));
+    assert!(!authlib.message.contains(jwt), "{}", authlib.message);
+    assert!(authlib.message.contains(REDACTED), "{}", authlib.message);
+
+    let ready = AuthlibLoginView::reachable("https://littleskin.cn/", "LittleSkin");
+    assert!(!ready.message.contains(jwt));
+}
+
+#[test]
+fn authlib_request_never_prints_the_password() {
+    let request = AuthlibRequest::new(
+        "https://littleskin.cn/api/yggdrasil/",
+        "me@example.com",
+        "hunter2",
+    );
+    let shown = request.redacted();
+    assert!(!shown.contains("hunter2"), "{shown}");
+    assert!(shown.contains("littleskin"), "{shown}");
+    assert!(shown.contains(REDACTED), "{shown}");
+}
+
+/// `Debug` 也不许带出密码（复审 r1 P3-5）：日志一行 `{:?}` 就破红线。
+#[test]
+fn authlib_request_debug_never_prints_the_password() {
+    let request = AuthlibRequest::new("https://littleskin.cn/api/yggdrasil/", "me", "hunter2");
+    let shown = format!("{request:?}");
+    assert!(!shown.contains("hunter2"), "{shown}");
+    assert!(shown.contains(REDACTED), "{shown}");
+    assert!(shown.contains("littleskin"), "{shown}");
+}
+
+#[test]
+fn authlib_view_carries_the_server_name_and_no_tokens() {
+    let view = AuthlibLoginView::reachable("https://littleskin.cn/api/yggdrasil/", "LittleSkin");
+    assert_eq!(view.phase, DeviceLoginPhase::Waiting);
+    assert_eq!(view.server_name, "LittleSkin");
+    assert!(view.message.contains("LittleSkin"));
+
+    let ok = AuthlibLoginView::succeeded("LittleSkin", "Steve");
+    assert_eq!(ok.phase, DeviceLoginPhase::Succeeded);
+    assert_eq!(ok.account_name, "Steve");
+    let json = serde_json::to_string(&ok).expect("序列化");
+    for forbidden in ["accessToken", "clientToken", "refresh", "password"] {
+        assert!(!json.contains(forbidden), "视图里不该出现 {forbidden}");
+    }
+}
+
+#[test]
+fn account_view_serializes_without_credentials() {
+    let view = AccountView {
+        id: "account:a".to_string(),
+        name: "Steve".to_string(),
+        kind: AccountKind::Authlib,
+        profile_id: "0f8f".to_string(),
+        login_name: "me@example.com".to_string(),
+        created: "2026-10-31 20:12".to_string(),
+        active: true,
+        server_url: "https://littleskin.cn/api/yggdrasil/".to_string(),
+        skin: Some(SkinImage {
+            png: vec![1, 2, 3],
+            source: "textures".to_string(),
+        }),
+    };
+    let json = serde_json::to_string(&view).expect("序列化");
+    for forbidden in ["token", "secret", "password", "refresh"] {
+        assert!(
+            !json.to_lowercase().contains(forbidden),
+            "账户视图里不该出现 {forbidden}"
+        );
+    }
+    assert!(json.contains("\"png\""));
+}
+
+#[test]
+fn monogram_is_stable_and_never_empty() {
+    let mut view = AccountView {
+        id: "account:a".to_string(),
+        name: "  steve".to_string(),
+        kind: AccountKind::Microsoft,
+        profile_id: "0f8f".to_string(),
+        login_name: String::new(),
+        created: String::new(),
+        active: false,
+        server_url: String::new(),
+        skin: None,
+    };
+    assert_eq!(view.monogram(), "S");
+    let tone = view.monogram_tone();
+    assert!(tone < 6);
+    view.profile_id = "0f8f".to_string();
+    assert_eq!(view.monogram_tone(), tone, "同一个人每次同一个色块");
+    view.name = String::new();
+    assert_eq!(view.monogram(), "?", "空名字也要有字，不能画白块");
+}
diff --git a/crates/presenter/src/dto/agent.rs b/crates/presenter/src/dto/agent.rs
new file mode 100644
index 0000000..3dd6e28
--- /dev/null
+++ b/crates/presenter/src/dto/agent.rs
@@ -0,0 +1,179 @@
+//! AI 会话 DTO：消息、工具调用可视化、确认请求与 agent 事件。
+//!
+//! 与 agent 侧的对应关系（`crates/agent/src/event.rs` / `confirm.rs`）：这里是**扁平镜像**，
+//! 不 import `unlucky_agent::*`（dto 是 IPC 边界，见 `dto/mod.rs` 的纪律）。字段口径刻意逐字
+//! 对齐，翻译在接线层做：`AgentEvent::ConfirmRequested` ← `confirm::ConfirmRequest`。
+
+use serde::{Deserialize, Serialize};
+
+/// 会话消息角色。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ChatRole {
+    /// 用户
+    User,
+    /// 助手（可流式）
+    Assistant,
+    /// 工具调用（会话里可见，D4 要求）
+    Tool,
+    /// 系统提示（弱化展示）
+    System,
+}
+
+/// 工具调用可视化条目。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ToolCallView {
+    /// 工具名（与 ToolSpec 注册表同名）
+    pub name: String,
+    /// 是否成功
+    pub ok: bool,
+    /// 一行结果摘要
+    pub summary: String,
+}
+
+/// 一条会话消息。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ChatMessage {
+    /// 角色
+    pub role: ChatRole,
+    /// 正文（流式时持续追加）
+    pub text: String,
+    /// role == Tool 时带上工具调用详情
+    pub tool: Option<ToolCallView>,
+    /// 流式未收敛
+    pub streaming: bool,
+}
+
+impl ChatMessage {
+    /// 用户消息。
+    pub fn user(text: impl Into<String>) -> Self {
+        Self {
+            role: ChatRole::User,
+            text: text.into(),
+            tool: None,
+            streaming: false,
+        }
+    }
+
+    /// 助手流式消息起点（空文本 + streaming）。
+    pub fn assistant_stream() -> Self {
+        Self {
+            role: ChatRole::Assistant,
+            text: String::new(),
+            tool: None,
+            streaming: true,
+        }
+    }
+
+    /// 系统提示（弱化展示；错误横幅也进会话历史，用户回翻时看得到）。
+    pub fn system(text: impl Into<String>) -> Self {
+        Self {
+            role: ChatRole::System,
+            text: text.into(),
+            tool: None,
+            streaming: false,
+        }
+    }
+}
+
+/// 敏感等级（与 agent 侧 `confirm::Sensitivity` 逐字一致）。
+///
+/// | 等级 | 语义 |
+/// |------|------|
+/// | `Low` | 静默生效 |
+/// | `Medium` | 静默生效，审计里能查到 |
+/// | `High` | 必须用户确认（YOLO 可跳过确认，但**仍受白名单约束**） |
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum Sensitivity {
+    /// 静默生效。
+    #[default]
+    Low,
+    /// 静默生效但审计标记。
+    Medium,
+    /// 必须用户确认。
+    High,
+}
+
+impl Sensitivity {
+    /// 是否会触发确认弹窗（非 YOLO 时）。
+    #[must_use]
+    pub fn needs_confirm(self) -> bool {
+        self == Self::High
+    }
+}
+
+/// 一次待确认的写操作（确认弹窗的原料；与 agent 侧 `confirm::ConfirmRequest` 对齐）。
+///
+/// 构造时**不要**放凭据：`details` 会按键名与内容双道脱敏（[`crate::agent::rail`]），
+/// 但白名单之外的键本来就不该出现在这里。
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct ConfirmRequest {
+    /// 请求 id（编排层生成，UI 回填决定时原样带回）
+    pub id: String,
+    /// 工具名（与 ToolSpec 注册表同名）
+    pub tool: String,
+    /// 一句话请求（「AI 请求把下载并发 64 改为 16」）
+    pub summary: String,
+    /// 结构化细节（`{"path":…, "old":…, "new":…}`），UI 画 diff 用
+    pub details: serde_json::Value,
+    /// 敏感等级
+    pub sensitivity: Sensitivity,
+}
+
+/// agent 侧事件。
+///
+/// 四类都投到 [`crate::agent::AgentRail`] 上：流式增量 → 最后一条 assistant 消息；工具调用 →
+/// 会话里可见的 tool 条目（D4）；错误 → 系统条目 + 横幅；确认请求 → `rail.confirm`。
+///
+/// 注意这里**没有** `Eq`：`ConfirmRequest::details` 是 `serde_json::Value`（可含浮点）。
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub enum AgentEvent {
+    /// 追加一条完整消息
+    MessageAppended(ChatMessage),
+    /// 给指定序号的流式消息追加增量
+    MessageDelta {
+        /// 目标消息在会话里的序号
+        index: usize,
+        /// 增量文本
+        delta: String,
+    },
+    /// 流式收敛
+    MessageFinished {
+        /// 目标消息序号
+        index: usize,
+    },
+    /// 开始一次工具调用（会话里插入工具条目）
+    ToolCallStarted {
+        /// 工具名
+        name: String,
+        /// 调用参数摘要
+        summary: String,
+    },
+    /// 工具调用结束
+    ToolCallFinished {
+        /// 工具名
+        name: String,
+        /// 是否成功
+        ok: bool,
+        /// 结果摘要
+        summary: String,
+    },
+    /// 循环级错误（provider 断流、AI 被禁用、工具内部异常）。
+    ///
+    /// 与 `ToolCallFinished { ok: false }` 的分工：那个是**某一次工具调用**失败，对话继续；
+    /// 这个是**这一轮回复**中止，rail 要收敛掉所有流式标记并立一个错误横幅。
+    Failed {
+        /// 人类可读原因
+        message: String,
+    },
+    /// 需要用户确认（分级确认：写操作先问再改）。
+    ConfirmRequested {
+        /// 待确认请求
+        request: ConfirmRequest,
+    },
+    /// 确认请求已收敛（重放/超时/别处已裁决）：把 rail 上同 id 的待确认清掉，避免僵尸弹窗。
+    ConfirmResolved {
+        /// 请求 id
+        id: String,
+    },
+}
diff --git a/crates/presenter/src/dto/content.rs b/crates/presenter/src/dto/content.rs
new file mode 100644
index 0000000..8693d57
--- /dev/null
+++ b/crates/presenter/src/dto/content.rs
@@ -0,0 +1,366 @@
+//! 内容库 DTO（M109 `CONTENTDL`）：Modrinth / CurseForge 上「整合包 / Mod / 资源包 / 光影」的
+//! **检索**与**装入指定实例**。
+//!
+//! ## 为什么这些类型在 presenter 而不是 core
+//!
+//! D3 / 01c §5：UI 只经 `crate::dto` 消费后端，跨边界类型必须可序列化。而**检索本身**
+//! （HTTP + 两个站点的 JSON 方言）今天落在 `crate::host::addon`：`crates/core` 的 `addon` 模块
+//! 只有加载器安装与整合包**格式**解析，没有 CF / Modrinth 的 API 客户端（M111 才做导入管线）。
+//! 所以这是「宿主层临时落点」的契约面——长期应下沉到 `core::addon`，届时这里只留薄 DTO。
+//!
+//! 两个形状是**故意**的：
+//!
+//! - [`ContentHit::game_versions`] / [`ContentHit::loaders`] 来自检索结果的 facets ⇒ 页面在用户
+//!   **点之前**就能判「装不装得上」（任务书第 3 条），不用点完才报错；
+//! - [`ContentKind::dir`] 的 `None`（整合包）是「按钮禁用」的**唯一**判据，不是一个文案开关。
+//!
+//! ## 密钥纪律（任务书第 5 条）
+//!
+//! CurseForge 的 `X-API-KEY` 从环境变量 `ULL_CF_API_KEY` 读，**不进仓库、不进 DTO、不进日志**。
+//! 这里只有 [`ContentResults::curseforge`] 一个 `bool`：源可用与否。
+//! 于是「密钥泄漏」在类型层就不可能——本 crate 没有任何字段能装下它。
+
+use serde::{Deserialize, Serialize};
+
+use crate::dto::{InstanceId, LoaderKind};
+
+/// 内容类型（内容库页左侧那四条一级侧栏）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum ContentKind {
+    /// 整合包（Modpack）
+    Modpack,
+    /// Mod
+    Mod,
+    /// 资源包（Resource pack）
+    Resourcepack,
+    /// 光影（Shader pack）
+    Shader,
+}
+
+impl ContentKind {
+    /// 四条侧栏的声明顺序（= 画出来的顺序）。
+    pub const ALL: [ContentKind; 4] = [
+        ContentKind::Modpack,
+        ContentKind::Mod,
+        ContentKind::Resourcepack,
+        ContentKind::Shader,
+    ];
+
+    /// 稳定 slug（日志 / 文件名 / 命令行参数用，**不要改名**）。
+    #[must_use]
+    pub const fn slug(self) -> &'static str {
+        match self {
+            Self::Modpack => "modpack",
+            Self::Mod => "mod",
+            Self::Resourcepack => "resourcepack",
+            Self::Shader => "shader",
+        }
+    }
+
+    /// Modrinth 的 `project_type` facet 值。
+    #[must_use]
+    pub const fn modrinth_type(self) -> &'static str {
+        match self {
+            Self::Modpack => "modpack",
+            Self::Mod => "mod",
+            Self::Resourcepack => "resourcepack",
+            Self::Shader => "shader",
+        }
+    }
+
+    /// 装入实例时的落盘目录（相对运行目录）；`None` = 不是「一个文件进一个目录」这种语义。
+    ///
+    /// 整合包没有目录：它要走 core 的导入管线（解压 + 补全 + 登记实例），那是 M111 的活，
+    /// 所以这里是 `None`——**按钮禁用由这个 `None` 驱动**，不是靠一句文案。
+    #[must_use]
+    pub const fn dir(self) -> Option<&'static str> {
+        match self {
+            Self::Modpack => None,
+            Self::Mod => Some("mods"),
+            Self::Resourcepack => Some("resourcepacks"),
+            Self::Shader => Some("shaderpacks"),
+        }
+    }
+
+    /// CurseForge 的 `classId`（CF API 的类目字段；数值是官方文档里的固定值）。
+    #[must_use]
+    pub const fn curseforge_class(self) -> u32 {
+        match self {
+            Self::Modpack => 4471,
+            Self::Mod => 6,
+            Self::Resourcepack => 12,
+            Self::Shader => 6552,
+        }
+    }
+}
+
+/// 内容来源。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum ContentSource {
+    /// Modrinth（无需 API key，默认源）
+    Modrinth,
+    /// CurseForge（需要 `ULL_CF_API_KEY`）
+    Curseforge,
+}
+
+impl ContentSource {
+    /// 两个来源的声明顺序（= 筛选条顺序）。
+    pub const ALL: [ContentSource; 2] = [ContentSource::Modrinth, ContentSource::Curseforge];
+
+    /// 稳定 slug。
+    #[must_use]
+    pub const fn slug(self) -> &'static str {
+        match self {
+            Self::Modrinth => "modrinth",
+            Self::Curseforge => "curseforge",
+        }
+    }
+}
+
+/// 排序方式（两个站点的官方排序项，口径对齐后再映射到各自参数）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum ContentSort {
+    /// 相关度（Modrinth `relevance`；CF 没有对应项，退回热度）
+    Relevance,
+    /// 下载量
+    Downloads,
+    /// 最新发布
+    Newest,
+    /// 最近更新
+    Updated,
+}
+
+impl ContentSort {
+    /// 四种排序的声明顺序。
+    pub const ALL: [ContentSort; 4] = [
+        ContentSort::Relevance,
+        ContentSort::Downloads,
+        ContentSort::Newest,
+        ContentSort::Updated,
+    ];
+
+    /// Modrinth `/v2/search` 的 `index` 参数值。
+    #[must_use]
+    pub const fn modrinth_index(self) -> &'static str {
+        match self {
+            Self::Relevance => "relevance",
+            Self::Downloads => "downloads",
+            Self::Newest => "newest",
+            Self::Updated => "updated",
+        }
+    }
+
+    /// CurseForge 的 `sortField`（1 = 热度，2 = 更新，3 = 发布，4 = 名称）。
+    #[must_use]
+    pub const fn curseforge_field(self) -> u32 {
+        match self {
+            Self::Relevance | Self::Downloads => 1,
+            Self::Newest => 3,
+            Self::Updated => 2,
+        }
+    }
+}
+
+/// 加载器 → Modrinth 的 loader facet 值；`None` = 该加载器没有对应 facet（原版等）。
+#[must_use]
+pub const fn loader_facet(loader: LoaderKind) -> Option<&'static str> {
+    match loader {
+        LoaderKind::Fabric => Some("fabric"),
+        LoaderKind::Quilt => Some("quilt"),
+        LoaderKind::Forge => Some("forge"),
+        LoaderKind::NeoForge => Some("neoforge"),
+        LoaderKind::Vanilla | LoaderKind::OptiFine | LoaderKind::LiteLoader => None,
+    }
+}
+
+/// 一次检索请求（**页面把它整份发出去**，不做本地过滤之外的乐观处理）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ContentQuery {
+    /// 内容类型
+    pub kind: ContentKind,
+    /// 来源
+    pub source: ContentSource,
+    /// 关键词（空串 = 不带 `query` 参数，即「按热度浏览」）
+    pub text: String,
+    /// 游戏版本过滤（`None` = 不过滤）
+    pub game_version: Option<String>,
+    /// 加载器过滤（`None` = 不过滤；对资源包 / 光影也照发——静默丢掉会让筛选条撒谎）
+    pub loader: Option<LoaderKind>,
+    /// 排序
+    pub sort: ContentSort,
+    /// 偏移（分页游标）
+    pub offset: u32,
+    /// 每页条数
+    pub limit: u32,
+}
+
+impl ContentQuery {
+    /// 每页条数（20 = Modrinth 默认上限的一半，翻页手感与请求量折中）。
+    pub const PAGE: u32 = 20;
+
+    /// 某个类型的首页（来源 Modrinth、无关键词、无过滤、按相关度）。
+    #[must_use]
+    pub fn first(kind: ContentKind) -> Self {
+        Self {
+            kind,
+            source: ContentSource::Modrinth,
+            text: String::new(),
+            game_version: None,
+            loader: None,
+            sort: ContentSort::Relevance,
+            offset: 0,
+            limit: Self::PAGE,
+        }
+    }
+
+    /// 换一批（保留全部筛选条件，只把游标往后挪一页）。
+    #[must_use]
+    pub fn next_page(&self) -> Self {
+        Self {
+            offset: self.offset.saturating_add(self.limit),
+            ..self.clone()
+        }
+    }
+
+    /// 筛选条件是否与另一份相同（**不含游标**：判「结果是不是同一批条件拉回来的」用它）。
+    #[must_use]
+    pub fn same_filters(&self, other: &Self) -> bool {
+        self.kind == other.kind
+            && self.source == other.source
+            && self.text == other.text
+            && self.game_version == other.game_version
+            && self.loader == other.loader
+            && self.sort == other.sort
+    }
+}
+
+/// 一条检索结果（一个项目，不是文件）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ContentHit {
+    /// 项目 id（Modrinth 的 base62 id / CF 的 modId；装入指令的载荷）
+    pub id: String,
+    /// 人读 slug（`sodium`；链接与日志里更可读）
+    pub slug: String,
+    /// 标题
+    pub title: String,
+    /// 一句话说明（站点原文，不翻译：它是用户内容，不是界面文案）
+    pub summary: String,
+    /// 作者（Modrinth 只有团队 id 时给空串）
+    pub author: String,
+    /// 下载量
+    pub downloads: u64,
+    /// 最近更新时间（ISO-8601 的日期部分；未知给空串）
+    pub updated: String,
+    /// 来源
+    pub source: ContentSource,
+    /// 支持的游戏版本（升序由站点给；页面只做「包不包含」判断）
+    pub game_versions: Vec<String>,
+    /// 支持的加载器（`fabric` / `forge` / `neoforge` / `quilt`）
+    pub loaders: Vec<String>,
+    /// 图标 URL（`None` = 没有；页面不拉图，只把主机名画成占位标记）
+    pub icon: Option<String>,
+}
+
+impl ContentHit {
+    /// 这个项目支持某个游戏版本吗（空列表 = 站点没给，按「未知」处理 ⇒ 不拦）。
+    #[must_use]
+    pub fn supports_version(&self, version: &str) -> bool {
+        self.game_versions.is_empty() || self.game_versions.iter().any(|item| item == version)
+    }
+
+    /// 这个项目支持某个加载器吗（空列表 = 站点没给，按「未知」处理 ⇒ 不拦）。
+    #[must_use]
+    pub fn supports_loader(&self, loader: LoaderKind) -> bool {
+        let Some(facet) = loader_facet(loader) else {
+            return true;
+        };
+        self.loaders.is_empty() || self.loaders.iter().any(|item| item == facet)
+    }
+}
+
+/// 一批检索结果。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ContentResults {
+    /// 这份结果对应的请求（页面据此判断「这批还算不算当前条件」）
+    pub query: ContentQuery,
+    /// 命中项（顺序 = 站点顺序）
+    pub hits: Vec<ContentHit>,
+    /// 命中总数（站点给的分页总数；`0` = 站点没给）
+    pub total: u32,
+    /// CurseForge 源此刻是否可用（`false` = 没有 `ULL_CF_API_KEY`）
+    pub curseforge: bool,
+}
+
+impl ContentResults {
+    /// 还有下一页吗。
+    ///
+    /// 判据是「本页装满了」而不是 `offset + len < total`：站点给的 `total` 有时是估算值，
+    /// 用「装满」判定最多多请求一次空页，不会出现「明明还有却翻不到」。
+    #[must_use]
+    pub fn has_more(&self) -> bool {
+        self.hits.len() as u32 >= self.query.limit
+    }
+}
+
+/// 「装入指定实例」的请求（UI 侧只发意图；选哪个文件由 host 按版本 + 加载器选）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ContentInstallRequest {
+    /// 项目 id
+    pub project: String,
+    /// 项目标题（进度面板上显示的那一行；**不是** i18n 文案）
+    pub title: String,
+    /// 内容类型（决定落盘目录与「能不能装」）
+    pub kind: ContentKind,
+    /// 来源
+    pub source: ContentSource,
+    /// 目标实例
+    pub instance: InstanceId,
+    /// 目标实例的游戏版本（选文件用）
+    pub game_version: String,
+    /// 目标实例的加载器（选文件用）
+    pub loader: LoaderKind,
+}
+
+/// 内容库页的状态（M109）：**检索条件 + 最近一批结果 + 请求态**。
+///
+/// 条件为什么也存在这里：页面层不持有业务状态是老纪律（同 `download_query`）；换页只挪游标、
+/// 条件只有一份，才不会出现「筛选条说的是 A、列表画的是 B」。
+#[derive(Debug, Clone, PartialEq)]
+pub struct ContentState {
+    /// 当前检索条件（游标也在里面：换页就是换一份 `query`）
+    pub query: ContentQuery,
+    /// 最近一批结果（`None` = 还没拉过）
+    pub results: Option<ContentResults>,
+    /// 有请求在飞（页面画加载态的依据；命中项只由事件写进来，不做乐观回显）
+    pub pending: bool,
+    /// 最近一次失败的原文（`None` = 没失败）
+    pub failed: Option<String>,
+    /// **最近一页**是否装满（`hits.len() >= limit`）。
+    ///
+    /// 为什么不是「累计条数够一页」：分页是**累加**到 `results.hits` 里的，累计值在第 2 页之后
+    /// 必然 ≥ limit ⇒ 用累计判会得到「has_more 恒真」：加载更多永不消失、「没有更多了」在真实
+    /// 翻页路径上不可达，而且每点一次白发一次网络请求（复审 P1-2）。所以这一位单独记。
+    pub last_page_filled: bool,
+}
+
+impl Default for ContentState {
+    fn default() -> Self {
+        Self {
+            query: ContentQuery::first(ContentKind::Mod),
+            results: None,
+            pending: false,
+            failed: None,
+            last_page_filled: false,
+        }
+    }
+}
+
+impl ContentState {
+    /// 这批结果还算当前条件吗（`false` = 迟到的事件，丢掉，不许覆盖新的筛选结果）。
+    #[must_use]
+    pub fn accepts(&self, results: &ContentResults) -> bool {
+        results.query.same_filters(&self.query)
+    }
+}
+#[cfg(test)]
+mod tests;
diff --git a/crates/presenter/src/dto/content/tests.rs b/crates/presenter/src/dto/content/tests.rs
new file mode 100644
index 0000000..daed624
--- /dev/null
+++ b/crates/presenter/src/dto/content/tests.rs
@@ -0,0 +1,87 @@
+//! 内容库 DTO 的守门测试（M109）。从 `dto/content.rs` 拆出：那个文件已贴 400 行硬上限。
+
+use super::*;
+
+fn hit(game_versions: Vec<String>, loaders: Vec<String>) -> ContentHit {
+    ContentHit {
+        id: "1".to_string(),
+        slug: "s".to_string(),
+        title: "t".to_string(),
+        summary: String::new(),
+        author: String::new(),
+        downloads: 0,
+        updated: String::new(),
+        source: ContentSource::Modrinth,
+        game_versions,
+        loaders,
+        icon: None,
+    }
+}
+
+#[test]
+fn only_file_kinds_have_install_directories() {
+    // 抓得住：把整合包也塞一个目录（那等于把「解压+补全+登记实例」偷偷降级成「拷一个文件进 mods」，
+    // 正是任务书第 3 条禁止的事）。
+    assert_eq!(ContentKind::Modpack.dir(), None);
+    assert_eq!(ContentKind::Mod.dir(), Some("mods"));
+    assert_eq!(ContentKind::Resourcepack.dir(), Some("resourcepacks"));
+    assert_eq!(ContentKind::Shader.dir(), Some("shaderpacks"));
+}
+
+#[test]
+fn kinds_map_to_the_official_facets_and_class_ids() {
+    assert_eq!(ContentKind::Modpack.modrinth_type(), "modpack");
+    assert_eq!(ContentKind::Shader.modrinth_type(), "shader");
+    // CF 的四个 classId 是官方固定值，抄错就搜不到东西（而且不会报错，只会空列表）
+    assert_eq!(ContentKind::Mod.curseforge_class(), 6);
+    assert_eq!(ContentKind::Resourcepack.curseforge_class(), 12);
+    assert_eq!(ContentKind::Modpack.curseforge_class(), 4471);
+    assert_eq!(ContentKind::Shader.curseforge_class(), 6552);
+    for kind in ContentKind::ALL {
+        assert!(!kind.slug().is_empty());
+    }
+}
+
+#[test]
+fn a_page_keeps_its_filters_and_only_moves_the_cursor() {
+    let mut query = ContentQuery::first(ContentKind::Mod);
+    query.game_version = Some("1.20.1".to_string());
+    query.text = "sodium".to_string();
+
+    let next = query.next_page();
+    assert_eq!(next.offset, ContentQuery::PAGE, "游标按一页走");
+    assert!(next.same_filters(&query), "换页不改筛选条件");
+
+    let mut other = next.clone();
+    other.text = "lithium".to_string();
+    assert!(!other.same_filters(&query), "关键词变了就不是同一批条件");
+}
+
+#[test]
+fn compatibility_checks_treat_missing_site_data_as_unknown_not_incompatible() {
+    let empty = hit(Vec::new(), Vec::new());
+    // 站点没给数据时不许拦人（否则「不知道」会被画成「不兼容」）
+    assert!(empty.supports_version("1.20.1"));
+    assert!(empty.supports_loader(LoaderKind::Fabric));
+
+    let filled = hit(vec!["1.20.1".to_string()], vec!["fabric".to_string()]);
+    assert!(filled.supports_version("1.20.1"));
+    assert!(!filled.supports_version("1.21.9"));
+    assert!(filled.supports_loader(LoaderKind::Fabric));
+    assert!(!filled.supports_loader(LoaderKind::Forge));
+    // 原版没有 facet：不该被加载器过滤误伤
+    assert!(filled.supports_loader(LoaderKind::Vanilla));
+}
+
+#[test]
+fn has_more_is_driven_by_a_full_page() {
+    let mut results = ContentResults {
+        query: ContentQuery::first(ContentKind::Mod),
+        hits: Vec::new(),
+        total: 999,
+        curseforge: false,
+    };
+    assert!(!results.has_more(), "空页 = 没有更多了");
+    results.hits = vec![hit(Vec::new(), Vec::new()); ContentQuery::PAGE as usize];
+    assert!(results.has_more(), "装满一页 = 还有下一页");
+}
diff --git a/crates/presenter/src/dto/events.rs b/crates/presenter/src/dto/events.rs
new file mode 100644
index 0000000..c4508a7
--- /dev/null
+++ b/crates/presenter/src/dto/events.rs
@@ -0,0 +1,338 @@
+//! 事件与指令：core/agent → app 的事件队列，app → core/agent 的用户意图。
+//!
+//! 三条通道（01c §5）：①不可变快照发布（`*Changed` 整体替换）②事件流（`LogAppended` /
+//! `InstallProgress` / `DeviceLoginChanged`）③注入的显示服务（先落成事件，见 `DialogRequested`）。
+//! 全部类型 `Serialize + Deserialize`：这是 IPC 契约（AGENTS §6）。
+
+use serde::{Deserialize, Serialize};
+
+use crate::dialogs::{DialogId, DialogRequest};
+use crate::dto::CreateRequest;
+use crate::dto::{
+    // 主线（M109 的 Content* / M113 的 Pack*）与 M114 的 Authlib*/AccountNotice 的并集。
+    AccountNotice,
+    AccountView,
+    AgentEvent,
+    AuthlibLoginView,
+    AuthlibRequest,
+    ContentInstallRequest,
+    ContentQuery,
+    ContentResults,
+    DeviceLoginView,
+    DiagnosisReport,
+    InstallProgressView,
+    InstanceId,
+    InstanceRuntime,
+    InstanceSummary,
+    JavaPageView,
+    LoaderKind,
+    LogLine,
+    LogOutcome,
+    LogSession,
+    NoticeView,
+    PackCommand,
+    PackEvent,
+    SessionId,
+    SettingGroupView,
+    VersionCategory,
+    VersionSummary,
+};
+use crate::toast::Toast;
+
+/// 启动会话的一段实时日志（host 尾随 JSONL 后按批次发）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct LiveLogBatch {
+    /// 会话 id
+    pub session: SessionId,
+    /// 新增行
+    pub lines: Vec<LogLine>,
+    /// 会话是否还在跑（false = 收尾，可以触发诊断/刷新列表）
+    pub running: bool,
+}
+
+/// 一次启动收尾（磁贴状态回写 + 日志页会话列表刷新）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct LaunchFinished {
+    /// 实例 id
+    pub id: InstanceId,
+    /// 会话 id
+    pub session: SessionId,
+    /// 结局
+    pub outcome: LogOutcome,
+    /// 一句人读结论（`正常退出` / `崩溃（exit 1）` / `启动失败：…`）
+    pub summary: String,
+}
+
+/// core 侧事件（不可变快照发布 + 事件流，01c §5 的三条通道之二）。
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub enum CoreEvent {
+    /// 实例列表整体刷新
+    InstancesChanged(Vec<InstanceSummary>),
+    /// 单个实例运行时状态变化（启动进度/运行中/失败）
+    InstanceRuntimeChanged {
+        /// 实例 id
+        id: InstanceId,
+        /// 新状态
+        runtime: InstanceRuntime,
+    },
+    /// 下载页版本列表刷新
+    VersionListChanged(Vec<VersionSummary>),
+    /// 日志会话列表刷新
+    LogSessionsChanged(Vec<LogSession>),
+    /// 当前会话日志行刷新（整批替换）
+    LogLinesChanged(Vec<LogLine>),
+    /// 实时日志增量（启动中尾随 JSONL；`running=false` 表示会话收尾）
+    LogAppended(LiveLogBatch),
+    /// 启动收尾（磁贴状态回写 + toast）
+    LaunchFinished(LaunchFinished),
+    /// 诊断结论产出
+    DiagnosisReady(DiagnosisReport),
+    /// 账户列表刷新
+    AccountsChanged(Vec<AccountView>),
+    /// 微软登录状态刷新
+    DeviceLoginChanged(DeviceLoginView),
+    /// 第三方轨（authlib-injector）登录/校验状态刷新
+    AuthlibLoginChanged(AuthlibLoginView),
+    /// 账户页横幅（添加/删除/切换的结果；`None` = 清掉横幅）
+    AccountNoticeChanged(Option<AccountNotice>),
+    /// Java 页快照（发行版/回退链/运行时）
+    JavaChanged(JavaPageView),
+    /// 安装进度（`None` = 清掉进度面板）
+    InstallProgress(Option<InstallProgressView>),
+    /// 用户取消了安装（**不带人读文案**）
+    ///
+    /// 为什么只有信号没有文本：`presenter` 不依赖 `unlucky-i18n`，任何写死的中文都会和
+    /// 页面语言打架（下载页目前渲染英文，一条中文 Toast 会**同屏一中一英**，复审 P2-2）。
+    /// 文案由 app 层按 `Key` 现求：见 `pages::download::cancelled_toast`。
+    InstallCancelled,
+    /// 某 (加载器, 原版版本) 可用的加载器版本列表（下载页「安装选项」的版本下拉）。
+    ///
+    /// `result` 用 `Result` 而不是空列表：**取不到**与**确实没有**是两件事，
+    /// 前者要给具名错误（不许让下拉显示成空还以为能装），后者是「这个组合官方就没有版本」。
+    LoaderVersions {
+        /// 加载器种类
+        kind: LoaderKind,
+        /// 目标原版版本
+        mc_version: String,
+        /// `Ok(最新在前)` / `Err(人读原因)`
+        result: Result<Vec<String>, String>,
+    },
+    /// 设置分组刷新（设置页右栏）
+    SettingsChanged(Vec<SettingGroupView>),
+    /// 横幅通知刷新（隔离切换提示/启动失败等）
+    NoticesChanged(Vec<NoticeView>),
+    /// 内容库检索结果（M109）：**整批替换**（同一份 `query` 的命中项，含分页游标）
+    ContentResults(Box<ContentResults>),
+    /// 内容库检索失败（M109）：一句人读原因（没网 / 站点限速 / 缺密钥）
+    ContentFailed(String),
+    // M113: import/export
+    /// 导入/导出（M113）：进度、结果、探测诊断、导出预检（子枚举见 [`PackEvent`]）
+    Pack(Box<PackEvent>),
+}
+
+/// 统一事件队列的元素：core / agent / UI 自产（对话框、Toast）都走这一条路，
+/// 这样 [`crate::state::AppState::apply`] 是唯一的状态变更入口。
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub enum AppEvent {
+    /// 来自 core
+    Core(CoreEvent),
+    /// 来自 agent
+    Agent(AgentEvent),
+    /// core/agent 请求弹对话框（会进队列，一次一条）
+    DialogRequested(DialogRequest),
+    /// 关闭指定对话框（任务完成收起进度条）
+    DialogClosed(DialogId),
+    /// 右下角 Toast
+    Toast(Toast),
+}
+
+/// app → core/agent 的用户意图。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum AppCommand {
+    /// 重新扫描实例目录 + 全部页面快照（启动时与手改文件后）
+    RefreshAll,
+    /// 启动实例
+    LaunchInstance(InstanceId),
+    /// 停止实例（含取消启动中的管线）
+    StopInstance(InstanceId),
+    /// 拉取某分类的版本列表
+    ListVersions(VersionCategory),
+    /// 安装指定版本（下载页行内「安装」按钮；原版）
+    InstallVersion(String),
+    /// 取消安装（阶段边界生效：当前阶段跑完就停，不再进下一阶段）
+    CancelInstall,
+    /// 新建实例（向导提交：版本 + 加载器 + 名字）
+    CreateInstance(CreateRequest),
+    /// 拉取某原版版本可用的加载器版本（下载页「安装选项」的版本下拉）
+    ListLoaderVersions {
+        /// 加载器种类
+        kind: LoaderKind,
+        /// 目标原版版本（`1.20.1`）
+        mc_version: String,
+    },
+    /// 修改实例隔离档位（写实例设置文件）
+    SetIsolation {
+        /// 实例 id
+        id: InstanceId,
+        /// `isolated` / `shared`
+        mode: String,
+    },
+    /// 刷新日志会话列表
+    RefreshLogSessions,
+    /// 打开某个会话（拉取日志行 + 触发诊断）
+    OpenLogSession(SessionId),
+    /// 导入崩溃日志文件做规则分析（`hs_err_pid*.log` / `latest.log`）
+    ImportCrashLog(String),
+    /// 加一个离线账户
+    AddOfflineAccount(String),
+    /// 删除账户（按 id 或名字）
+    RemoveAccount(String),
+    /// 切换当前启动账户
+    SwitchAccount(String),
+    /// 开始微软设备码登录（CLI/无浏览器场景、备用通道）
+    StartDeviceLogin,
+    /// 开始微软授权码登录（拉起系统默认浏览器 + 本地回调，GUI 的默认入口）
+    StartBrowserLogin,
+    /// 取消/关掉微软登录面板（已发出的请求会在收尾时丢弃结果）
+    CancelDeviceLogin,
+    /// 加一个第三方皮肤站（authlib-injector）账户：校验服务器 + 密码登录
+    ///
+    /// **凭据红线**：`request.password` 只是这一次的请求值，host 用完即弃，绝不进回程 DTO。
+    AddAuthlibAccount(AuthlibRequest),
+    /// 只校验第三方皮肤站地址（服务发现）：结果走 `AuthlibLoginChanged`
+    ProbeAuthlibServer(String),
+    /// 关掉账户页横幅（页面上的 × / Dismiss）
+    DismissAccountNotice,
+    /// 安装指定发行版的托管 JDK（`temurin` / `oracle` / `microsoft` / `zulu`）
+    InstallJava(String),
+    /// 写一条设置（`key` 必须是 core schema 里的键）
+    SetSetting {
+        /// schema 键
+        key: String,
+        /// 新值（字符串形态；host 按 schema 类型转换）
+        value: String,
+    },
+    /// 关掉一条横幅通知
+    DismissNotice(String),
+    /// 向 AI 提问（会话状态在 app 侧，agent 只回事件）
+    AskAgent(String),
+    /// 中断当前 AI 流
+    StopAgent,
+    /// YOLO 开关（跳过确认，审计照记）
+    SetYolo(bool),
+    /// 检索内容库（M109；结果经 [`CoreEvent::ContentResults`] 回来）
+    SearchContent(ContentQuery),
+    /// 把某个内容项目装进指定实例（M109；整合包不支持，host 会拒绝并给原因）
+    InstallContent(Box<ContentInstallRequest>),
+    // M113: import/export
+    /// 整合包导入/导出（M113）：导入 / 预检 / 确认写盘 / 关面板（子枚举见 [`PackCommand`]）
+    Pack(Box<PackCommand>),
+}
+
+impl AppCommand {
+    /// 构造「切换隔离档位」指令（磁贴/详情页共用）。
+    pub fn set_isolation(id: &str, mode: &str) -> Self {
+        Self::SetIsolation {
+            id: id.to_string(),
+            mode: mode.to_string(),
+        }
+    }
+}
+
+/// 后端通道：core/agent host 实现它；[`crate::mock::MockBackend`] 验证通道语义。
+///
+/// 轮询模型（而非回调）是为了让 Slint 的定时器成为唯一调度者，
+/// 避免跨线程回调里碰 Slint 模型。
+pub trait Backend {
+    /// 取走自上次调用以来积压的事件（FIFO，不可丢序号）。
+    fn drain_events(&mut self) -> Vec<AppEvent>;
+
+    /// 下发一条用户意图。
+    fn dispatch(&mut self, command: AppCommand);
+
+    /// 时间推进（真实后端在这里收后台线程的结果并尾随日志）。
+    fn tick(&mut self, elapsed: std::time::Duration) {
+        let _ = elapsed;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::dto::{AccountKind, DeviceLoginPhase, InstallStage};
+
+    #[test]
+    fn events_are_serializable_ipc_contracts() {
+        let event = AppEvent::Core(CoreEvent::InstallProgress(Some(InstallProgressView {
+            stage: InstallStage::Downloading,
+            files_done: 3,
+            files_total: 9,
+            ..InstallProgressView::new()
+        })));
+        let text = serde_json::to_string(&event).expect("序列化");
+        let back: AppEvent = serde_json::from_str(&text).expect("反序列化");
+        assert_eq!(back, event);
+
+        let account = AppEvent::Core(CoreEvent::AccountsChanged(vec![AccountView {
+            id: "account:1".to_string(),
+            name: "Steve".to_string(),
+            kind: AccountKind::Offline,
+            profile_id: "0f8f".to_string(),
+            login_name: String::new(),
+            created: "2026-10-31 20:12".to_string(),
+            active: true,
+            server_url: String::new(),
+            skin: None,
+        }]));
+        let text = serde_json::to_string(&account).expect("序列化");
+        let back: AppEvent = serde_json::from_str(&text).expect("反序列化");
+        assert_eq!(back, account);
+        // 凭据永不跨界：序列化文本里没有 token 类字段
+        assert!(!text.to_lowercase().contains("token"));
+    }
+
+    #[test]
+    fn commands_round_trip() {
+        let command = AppCommand::CreateInstance(CreateRequest {
+            version: "1.20.4".to_string(),
+            loader: crate::dto::LoaderKind::Fabric,
+            loader_version: "0.16.5".to_string(),
+            name: "生存".to_string(),
+        });
+        let text = serde_json::to_string(&command).expect("序列化");
+        let back: AppCommand = serde_json::from_str(&text).expect("反序列化");
+        assert_eq!(back, command);
+
+        let login = AppCommand::StartDeviceLogin;
+        assert_eq!(
+            serde_json::from_str::<AppCommand>(&serde_json::to_string(&login).expect("序列化"))
+                .expect("反序列化"),
+            login
+        );
+        assert!(DeviceLoginPhase::Waiting.busy());
+
+        // 第三方轨（M114）：请求进、状态出，两边都不带 token 字段
+        let authlib = AppCommand::AddAuthlibAccount(AuthlibRequest::new(
+            "https://littleskin.cn/api/yggdrasil/",
+            "me@example.com",
+            "hunter2",
+        ));
+        let text = serde_json::to_string(&authlib).expect("序列化");
+        assert_eq!(
+            serde_json::from_str::<AppCommand>(&text).expect("反序列化"),
+            authlib
+        );
+
+        let view = AppEvent::Core(CoreEvent::AuthlibLoginChanged(AuthlibLoginView::reachable(
+            "https://littleskin.cn/api/yggdrasil/",
+            "LittleSkin",
+        )));
+        let text = serde_json::to_string(&view).expect("序列化");
+        let back: AppEvent = serde_json::from_str(&text).expect("反序列化");
+        assert_eq!(back, view);
+        assert!(
+            !text.to_lowercase().contains("token"),
+            "回程视图里不该有 token"
+        );
+    }
+}
diff --git a/crates/presenter/src/dto/install.rs b/crates/presenter/src/dto/install.rs
new file mode 100644
index 0000000..a960a22
--- /dev/null
+++ b/crates/presenter/src/dto/install.rs
@@ -0,0 +1,249 @@
+//! 安装进度 DTO：下载页与新建向导共用的「一个安装任务」视图。
+//!
+//! 只放聚合量（文件计数 / 字节 / 速度 / 剩余时间）+ 一行状态文案：
+//! 逐文件的明细留在 core 的 `InstallReport`，UI 不需要也不该持有。
+//! 速度与 ETA 由 host 依据相邻两次字节数差分算（core 的事件只给绝对值）。
+
+use serde::{Deserialize, Serialize};
+
+/// 安装阶段。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum InstallStage {
+    /// 解析版本清单 / 规划文件（联网取 metadata）
+    Planning,
+    /// 下载并校验文件
+    Downloading,
+    /// 落版本 JSON / 跑安装器
+    Installing,
+    /// 登记实例
+    Registering,
+    /// 完成
+    Done,
+    /// 失败
+    Failed,
+    /// 用户取消
+    Cancelled,
+}
+
+impl InstallStage {
+    /// 阶段文案。
+    pub fn label(self) -> &'static str {
+        match self {
+            Self::Planning => "解析版本",
+            Self::Downloading => "下载文件",
+            Self::Installing => "生成版本",
+            Self::Registering => "登记实例",
+            Self::Done => "已完成",
+            Self::Failed => "失败",
+            Self::Cancelled => "已取消",
+        }
+    }
+
+    /// 是否已经收尾（Done/Failed/Cancelled）。
+    pub fn is_terminal(self) -> bool {
+        matches!(self, Self::Done | Self::Failed | Self::Cancelled)
+    }
+}
+
+/// 一次安装的进度快照。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct InstallProgressView {
+    /// 目标版本 id
+    pub version: String,
+    /// 实例名（默认 = 版本 id）
+    pub instance: String,
+    /// 加载器徽标文字（`原版` / `Fabric 0.16.5`）
+    pub loader: String,
+    /// 阶段
+    pub stage: InstallStage,
+    /// 已完成文件数
+    pub files_done: u64,
+    /// 文件总数
+    pub files_total: u64,
+    /// 已下载字节
+    pub bytes_done: u64,
+    /// 总字节（0 = 未知）
+    pub bytes_total: u64,
+    /// 当前速度（字节/秒；0 = 未知）
+    pub speed_bps: u64,
+    /// 剩余秒数（0 = 未知）
+    pub eta_secs: u64,
+    /// 状态/错误文案
+    pub message: String,
+}
+
+impl Default for InstallProgressView {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl InstallProgressView {
+    /// 规划中的空快照。
+    pub fn new() -> Self {
+        Self {
+            version: String::new(),
+            instance: String::new(),
+            loader: String::new(),
+            stage: InstallStage::Planning,
+            files_done: 0,
+            files_total: 0,
+            bytes_done: 0,
+            bytes_total: 0,
+            speed_bps: 0,
+            eta_secs: 0,
+            message: String::new(),
+        }
+    }
+
+    /// 起一个任务的快照。
+    pub fn start(version: &str, instance: &str, loader: &str) -> Self {
+        Self {
+            version: version.to_string(),
+            instance: instance.to_string(),
+            loader: loader.to_string(),
+            stage: InstallStage::Planning,
+            message: "正在解析版本清单…".to_string(),
+            ..Self::new()
+        }
+    }
+
+    /// 整体进度 0.0~1.0（优先文件计数，其次字节；都没有时 0）。
+    pub fn ratio(&self) -> f32 {
+        if self.files_total > 0 {
+            (self.files_done as f32 / self.files_total as f32).clamp(0.0, 1.0)
+        } else if self.bytes_total > 0 {
+            (self.bytes_done as f32 / self.bytes_total as f32).clamp(0.0, 1.0)
+        } else {
+            0.0
+        }
+    }
+
+    /// 进度是否已知（未知时进度条转不确定态）。
+    pub fn is_known(&self) -> bool {
+        self.files_total > 0 || self.bytes_total > 0
+    }
+
+    /// 速度文案（`1.2 MB/s`；未知给空串）。
+    pub fn speed_label(&self) -> String {
+        if self.speed_bps == 0 {
+            return String::new();
+        }
+        format!("{}/s", human_bytes(self.speed_bps))
+    }
+
+    /// 剩余时间文案（`剩 12s`；未知给空串）。
+    pub fn eta_label(&self) -> String {
+        if self.eta_secs == 0 {
+            return String::new();
+        }
+        if self.eta_secs >= 60 {
+            format!("剩 {}m{:02}s", self.eta_secs / 60, self.eta_secs % 60)
+        } else {
+            format!("剩 {}s", self.eta_secs)
+        }
+    }
+
+    /// 文件计数文案（`128/512 文件`）。
+    pub fn files_label(&self) -> String {
+        if self.files_total == 0 {
+            return String::new();
+        }
+        format!("{}/{} 文件", self.files_done, self.files_total)
+    }
+}
+
+/// 字节数 → 人读（`1.2 MB`）。
+pub fn human_bytes(bytes: u64) -> String {
+    const UNITS: [&str; 5] = ["B", "KB", "MB", "GB", "TB"];
+    let mut value = bytes as f64;
+    let mut unit = 0;
+    while value >= 1024.0 && unit + 1 < UNITS.len() {
+        value /= 1024.0;
+        unit += 1;
+    }
+    if unit == 0 {
+        format!("{bytes} B")
+    } else {
+        format!("{value:.1} {}", UNITS[unit])
+    }
+}
+
+/// 用相邻两次采样算速度与 ETA（`None` = 本次无法计算，保持上次值）。
+pub fn derive_speed(
+    previous: (u64, std::time::Instant),
+    current: (u64, std::time::Instant),
+    bytes_total: u64,
+) -> Option<(u64, u64)> {
+    let elapsed = current.1.saturating_duration_since(previous.1);
+    if elapsed.as_millis() < 50 {
+        return None;
+    }
+    let delta = current.0.saturating_sub(previous.0);
+    if delta == 0 {
+        return None;
+    }
+    let elapsed_ms = u64::try_from(elapsed.as_millis()).unwrap_or(u64::MAX);
+    let speed = delta.saturating_mul(1000) / elapsed_ms.max(1);
+    let eta = if bytes_total > current.0 && speed > 0 {
+        (bytes_total - current.0) / speed
+    } else {
+        0
+    };
+    Some((speed, eta))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::time::{Duration, Instant};
+
+    #[test]
+    fn ratio_prefers_file_counts() {
+        let mut view = InstallProgressView::start("1.20.4", "1.20.4", "原版");
+        assert_eq!(view.ratio(), 0.0);
+        assert!(!view.is_known());
+
+        view.files_total = 4;
+        view.files_done = 1;
+        view.bytes_total = 1000;
+        view.bytes_done = 900;
+        assert!((view.ratio() - 0.25).abs() < f32::EPSILON);
+        assert!(view.is_known());
+        assert_eq!(view.files_label(), "1/4 文件");
+    }
+
+    #[test]
+    fn speed_and_eta_labels_are_human_readable() {
+        let view = InstallProgressView {
+            speed_bps: 1_258_291,
+            eta_secs: 75,
+            ..InstallProgressView::new()
+        };
+        assert_eq!(view.speed_label(), "1.2 MB/s");
+        assert_eq!(view.eta_label(), "剩 1m15s");
+        assert_eq!(InstallProgressView::new().speed_label(), "");
+    }
+
+    #[test]
+    fn derive_speed_needs_a_measurable_delta() {
+        let start = Instant::now();
+        let previous = (0, start);
+        // 间隔太短 → 不算
+        assert!(derive_speed(previous, (500, start + Duration::from_millis(10)), 1000).is_none());
+        // 正常差分：1s 下 500 字节 → 500 B/s，剩 500 字节 → 1s
+        let (speed, eta) =
+            derive_speed(previous, (500, start + Duration::from_secs(1)), 1000).expect("应能算");
+        assert_eq!(speed, 500);
+        assert_eq!(eta, 1);
+    }
+
+    #[test]
+    fn terminal_stages() {
+        assert!(InstallStage::Done.is_terminal());
+        assert!(InstallStage::Failed.is_terminal());
+        assert!(!InstallStage::Downloading.is_terminal());
+        assert_eq!(human_bytes(512), "512 B");
+        assert_eq!(human_bytes(2048), "2.0 KB");
+    }
+}
diff --git a/crates/presenter/src/dto/instances.rs b/crates/presenter/src/dto/instances.rs
new file mode 100644
index 0000000..47b9078
--- /dev/null
+++ b/crates/presenter/src/dto/instances.rs
@@ -0,0 +1,296 @@
+//! 实例相关 DTO：磁贴与列表视图的唯一数据源。
+
+use serde::{Deserialize, Serialize};
+
+use std::path::PathBuf;
+
+/// 实例标识：core::game 生成的稳定 id，app 视为不透明字符串。
+pub type InstanceId = String;
+
+/// 加载器种类（磁贴徽标 + 详情页版本链）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum LoaderKind {
+    /// 原版（无加载器）
+    Vanilla,
+    /// Fabric
+    Fabric,
+    /// Quilt
+    Quilt,
+    /// Forge
+    Forge,
+    /// NeoForge
+    NeoForge,
+    /// OptiFine
+    OptiFine,
+    /// LiteLoader
+    LiteLoader,
+}
+
+impl LoaderKind {
+    /// 徽标显示文字。
+    pub fn label(self) -> &'static str {
+        match self {
+            Self::Vanilla => "原版",
+            Self::Fabric => "Fabric",
+            Self::Quilt => "Quilt",
+            Self::Forge => "Forge",
+            Self::NeoForge => "NeoForge",
+            Self::OptiFine => "OptiFine",
+            Self::LiteLoader => "LiteLoader",
+        }
+    }
+
+    /// 稳定 id（`vanilla` / `fabric` / …；GUI 与 CLI 的 `--loader` 同词表）。
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Vanilla => "vanilla",
+            Self::Fabric => "fabric",
+            Self::Quilt => "quilt",
+            Self::Forge => "forge",
+            Self::NeoForge => "neoforge",
+            Self::OptiFine => "optifine",
+            Self::LiteLoader => "liteloader",
+        }
+    }
+
+    /// 从稳定 id 解析（未知给 `None`，由调用方决定报错文案）。
+    pub fn parse(raw: &str) -> Option<Self> {
+        Some(match raw.trim().to_ascii_lowercase().as_str() {
+            "vanilla" | "none" | "" => Self::Vanilla,
+            "fabric" => Self::Fabric,
+            "quilt" => Self::Quilt,
+            "forge" => Self::Forge,
+            "neoforge" => Self::NeoForge,
+            "optifine" => Self::OptiFine,
+            "liteloader" => Self::LiteLoader,
+            _ => return None,
+        })
+    }
+
+    /// 向导里的可选加载器（顺序即展示顺序）。
+    pub fn wizard_choices() -> [Self; 5] {
+        [
+            Self::Vanilla,
+            Self::Fabric,
+            Self::Quilt,
+            Self::Forge,
+            Self::NeoForge,
+        ]
+    }
+}
+
+/// 加载器 + 版本（例如 Fabric 0.16.5）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct LoaderInfo {
+    /// 加载器种类
+    pub kind: LoaderKind,
+    /// 加载器版本号；原版为空串
+    pub version: String,
+}
+
+impl Default for LoaderInfo {
+    fn default() -> Self {
+        Self {
+            kind: LoaderKind::Vanilla,
+            version: String::new(),
+        }
+    }
+}
+
+impl LoaderInfo {
+    /// 徽标文字：原版只写「原版」，装加载器时写「Fabric 0.16.5」。
+    pub fn badge(&self) -> String {
+        if self.kind == LoaderKind::Vanilla || self.version.is_empty() {
+            self.kind.label().to_string()
+        } else {
+            format!("{} {}", self.kind.label(), self.version)
+        }
+    }
+}
+
+/// 字节进度；`total == 0` 表示总量未知（UI 转不确定态）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
+pub struct Progress {
+    /// 已完成量
+    pub done: u64,
+    /// 总量；0 = 未知
+    pub total: u64,
+}
+
+impl Progress {
+    /// 0.0~1.0；未知总量返回 0.0。
+    pub fn ratio(self) -> f32 {
+        if self.total == 0 {
+            0.0
+        } else {
+            (self.done as f32 / self.total as f32).clamp(0.0, 1.0)
+        }
+    }
+
+    /// 总量是否已知。
+    pub fn is_known(self) -> bool {
+        self.total > 0
+    }
+}
+
+/// 启动管线阶段（磁贴进度环的文案来源；D8 的 10 阶段在 P1 细化）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum LaunchStage {
+    /// 下载资源
+    Download,
+    /// 校验文件
+    Verify,
+    /// 组装命令行并拉起进程
+    Launch,
+    /// 进程已起、等待游戏窗口（M28 的窗口检测阶段）
+    Window,
+}
+
+impl LaunchStage {
+    /// 磁贴上的阶段文案。
+    pub fn label(self) -> &'static str {
+        match self {
+            Self::Download => "下载资源",
+            Self::Verify => "校验文件",
+            Self::Launch => "组装命令行",
+            Self::Window => "等待窗口",
+        }
+    }
+}
+
+/// 实例运行时状态（磁贴的四种外观）。
+#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
+pub enum InstanceRuntime {
+    /// 空闲
+    #[default]
+    Idle,
+    /// 启动管线进行中
+    Busy {
+        /// 当前阶段
+        stage: LaunchStage,
+        /// 该阶段进度
+        progress: Progress,
+    },
+    /// 游戏进程存活
+    Running {
+        /// 进程号（停止/诊断用）
+        pid: u32,
+    },
+    /// 上次启动失败（磁贴显示「重试」）
+    Failed {
+        /// 失败原因（用户可见文案）
+        reason: String,
+    },
+}
+
+/// 实例摘要：磁贴/列表视图唯一数据源。
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct InstanceSummary {
+    /// 稳定 id
+    pub id: InstanceId,
+    /// 显示名
+    pub name: String,
+    /// 游戏版本（如 1.20.4）
+    pub mc_version: String,
+    /// 加载器信息
+    pub loader: LoaderInfo,
+    /// ISO-8601 UTC 最后游玩时间；None = 从未启动
+    pub last_played: Option<String>,
+    /// 运行时状态
+    pub runtime: InstanceRuntime,
+    /// 实例图标路径（P0 直接给路径；P1 换成 core 提供的图像句柄）
+    pub icon: Option<PathBuf>,
+    /// 隔离档位（`isolated` / `shared` / `custom`；未知为空）
+    pub isolation: String,
+    /// 该实例绑定的版本 id（详情页/启动用）
+    pub version_id: String,
+    /// 版本本体是否在盘上（缺载荷时磁贴亮黄条）
+    pub version_present: bool,
+}
+
+/// 新建实例向导提交给 host 的请求（已通过向导校验）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct CreateRequest {
+    /// 目标原版版本 id（`1.20.4`）
+    pub version: String,
+    /// 加载器
+    pub loader: LoaderKind,
+    /// 加载器版本（空 = 让 core 取最新）
+    pub loader_version: String,
+    /// 实例名（空 = 用版本 id / 加载器版本 id）
+    pub name: String,
+}
+
+impl CreateRequest {
+    /// 实际使用的实例名。
+    pub fn instance_name(&self) -> String {
+        if self.name.trim().is_empty() {
+            self.version.clone()
+        } else {
+            self.name.trim().to_string()
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn loader_badges_and_ids() {
+        let vanilla = LoaderInfo::default();
+        assert_eq!(vanilla.badge(), "原版");
+        let fabric = LoaderInfo {
+            kind: LoaderKind::Fabric,
+            version: "0.16.5".to_string(),
+        };
+        assert_eq!(fabric.badge(), "Fabric 0.16.5");
+        for kind in LoaderKind::wizard_choices() {
+            assert_eq!(LoaderKind::parse(kind.as_str()), Some(kind));
+        }
+        assert_eq!(LoaderKind::parse("fabric"), Some(LoaderKind::Fabric));
+        assert_eq!(LoaderKind::parse("unknown"), None);
+    }
+
+    #[test]
+    fn progress_ratio_handles_unknown_total() {
+        assert_eq!(Progress { done: 1, total: 0 }.ratio(), 0.0);
+        assert!((Progress { done: 1, total: 4 }.ratio() - 0.25).abs() < f32::EPSILON);
+    }
+
+    #[test]
+    fn create_request_defaults_name_to_version() {
+        let request = CreateRequest {
+            version: "1.20.4".to_string(),
+            loader: LoaderKind::Vanilla,
+            loader_version: String::new(),
+            name: "  ".to_string(),
+        };
+        assert_eq!(request.instance_name(), "1.20.4");
+    }
+
+    #[test]
+    fn instance_summary_is_serde_round_trip_safe() {
+        let instance = InstanceSummary {
+            id: "inst-1".to_string(),
+            name: "生存".to_string(),
+            mc_version: "1.20.4".to_string(),
+            loader: LoaderInfo {
+                kind: LoaderKind::Fabric,
+                version: "0.16.5".to_string(),
+            },
+            last_played: Some("2026-10-31T12:00:00.000Z".to_string()),
+            runtime: InstanceRuntime::Busy {
+                stage: LaunchStage::Window,
+                progress: Progress { done: 1, total: 2 },
+            },
+            icon: None,
+            isolation: "isolated".to_string(),
+            version_id: "1.20.4".to_string(),
+            version_present: true,
+        };
+        let text = serde_json::to_string(&instance).expect("序列化");
+        let back: InstanceSummary = serde_json::from_str(&text).expect("反序列化");
+        assert_eq!(back, instance);
+    }
+}
diff --git a/crates/presenter/src/dto/java.rs b/crates/presenter/src/dto/java.rs
new file mode 100644
index 0000000..dad588f
--- /dev/null
+++ b/crates/presenter/src/dto/java.rs
@@ -0,0 +1,234 @@
+//! Java 页 DTO：四家发行版、回退链可视化与本地运行时清单（D23/D13）。
+//!
+//! 回退链是「可观测性」的载体：安装失败时用户要能看见「Temurin 跳过 → Oracle 失败 →
+//! Microsoft 命中」这条链，而不是只拿到一句「下载失败」。链的每一步由 host 从
+//! `core::game::java::source::ChainLog` 翻译过来。
+
+use serde::{Deserialize, Serialize};
+
+/// 一家发行版的展示行。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct JavaVendorView {
+    /// 稳定 id（`temurin` / `oracle` / `microsoft` / `zulu`）
+    pub id: String,
+    /// 展示名
+    pub display: String,
+    /// 优先级序号（1 起）
+    pub rank: u32,
+    /// 支持的 Java 大版本摘要（`21/17/11`）
+    pub majors: String,
+    /// 可用源（镜像 + 吞吐备注）
+    pub sources: Vec<String>,
+    /// 是否已装过这家（托管目录里有现成的）
+    pub installed: bool,
+}
+
+/// 回退链一步的结局。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum JavaChainOutcome {
+    /// 还没尝试（安装前的计划链）
+    Pending,
+    /// 跳过（不支持目标大版本）
+    Skip,
+    /// 尝试过但失败
+    Failed,
+    /// 命中（下载/安装成功）
+    Hit,
+}
+
+impl JavaChainOutcome {
+    /// 徽标文字。
+    pub fn label(self) -> &'static str {
+        match self {
+            Self::Pending => "待尝试",
+            Self::Skip => "跳过",
+            Self::Failed => "失败",
+            Self::Hit => "命中",
+        }
+    }
+
+    /// 从 core 的 `VendorAttempt` 结局字符串解析。
+    pub fn parse(raw: &str) -> Self {
+        match raw {
+            "hit" => Self::Hit,
+            "failed" => Self::Failed,
+            "skip" | "skipped" => Self::Skip,
+            _ => Self::Pending,
+        }
+    }
+}
+
+/// 回退链一步。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct JavaChainStep {
+    /// 发行版 id
+    pub vendor: String,
+    /// 结局
+    pub outcome: JavaChainOutcome,
+    /// 细节（跳过原因 / 失败摘要 / 命中的下载源）
+    pub detail: String,
+}
+
+/// 本地已发现的 Java 运行时。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct JavaRuntimeView {
+    /// 可执行文件路径
+    pub binary: String,
+    /// 版本串（`17.0.9`）
+    pub version: String,
+    /// 大版本
+    pub major: u32,
+    /// 发行方
+    pub vendor: String,
+    /// 来源分类（system / managed / instance）
+    pub origin: String,
+}
+
+/// Java 页快照（一次事件整体替换）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct JavaPageView {
+    /// 地区判定（`domestic` / `global`）
+    pub region: String,
+    /// 优先级的来源（`region_default` / `java.vendorPriority`）
+    pub priority_source: String,
+    /// 生效顺序（`temurin → oracle → microsoft → zulu`）
+    pub order_text: String,
+    /// 四家展示行（按生效顺序）
+    pub vendors: Vec<JavaVendorView>,
+    /// 回退链（计划链或上一次安装的真实链）
+    pub chain: Vec<JavaChainStep>,
+    /// 本地运行时
+    pub runtimes: Vec<JavaRuntimeView>,
+    /// 托管目录
+    pub managed_roots: Vec<String>,
+    /// 是否有 Java 安装在跑
+    pub busy: bool,
+    /// 状态/错误文案
+    pub message: String,
+}
+
+impl Default for JavaPageView {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl JavaPageView {
+    /// 空态（托管目录还没扫到东西）。
+    pub fn new() -> Self {
+        Self {
+            region: "global".to_string(),
+            priority_source: "region_default".to_string(),
+            order_text: String::new(),
+            vendors: Vec::new(),
+            chain: Vec::new(),
+            runtimes: Vec::new(),
+            managed_roots: Vec::new(),
+            busy: false,
+            message: String::new(),
+        }
+    }
+
+    /// 计划链：按生效顺序铺一排「待尝试」（安装前的可视化）。
+    pub fn planned_chain(vendors: &[JavaVendorView]) -> Vec<JavaChainStep> {
+        vendors
+            .iter()
+            .map(|vendor| JavaChainStep {
+                vendor: vendor.id.clone(),
+                outcome: JavaChainOutcome::Pending,
+                detail: String::new(),
+            })
+            .collect()
+    }
+
+    /// 命中的那一家的展示名（`None` = 链上还没命中）。
+    pub fn hit_vendor(&self) -> Option<&str> {
+        self.chain
+            .iter()
+            .find(|step| step.outcome == JavaChainOutcome::Hit)
+            .map(|step| step.vendor.as_str())
+    }
+
+    /// 已安装的大版本列表（去重升序）。
+    pub fn majors(&self) -> Vec<u32> {
+        let mut majors: Vec<u32> = self.runtimes.iter().map(|runtime| runtime.major).collect();
+        majors.sort_unstable();
+        majors.dedup();
+        majors
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn vendor(id: &str, rank: u32) -> JavaVendorView {
+        JavaVendorView {
+            id: id.to_string(),
+            display: id.to_uppercase(),
+            rank,
+            majors: "21/17".to_string(),
+            sources: Vec::new(),
+            installed: false,
+        }
+    }
+
+    #[test]
+    fn planned_chain_is_all_pending_in_rank_order() {
+        let vendors = vec![vendor("temurin", 1), vendor("oracle", 2)];
+        let chain = JavaPageView::planned_chain(&vendors);
+        assert_eq!(chain.len(), 2);
+        assert!(chain
+            .iter()
+            .all(|step| step.outcome == JavaChainOutcome::Pending));
+        assert_eq!(chain[0].vendor, "temurin");
+    }
+
+    #[test]
+    fn hit_vendor_finds_the_hit_step() {
+        let mut page = JavaPageView::new();
+        page.chain = vec![
+            JavaChainStep {
+                vendor: "temurin".to_string(),
+                outcome: JavaChainOutcome::Skip,
+                detail: "不支持 8".to_string(),
+            },
+            JavaChainStep {
+                vendor: "oracle".to_string(),
+                outcome: JavaChainOutcome::Hit,
+                detail: "BMCLAPI".to_string(),
+            },
+        ];
+        assert_eq!(page.hit_vendor(), Some("oracle"));
+    }
+
+    #[test]
+    fn outcome_parses_core_words() {
+        assert_eq!(JavaChainOutcome::parse("hit"), JavaChainOutcome::Hit);
+        assert_eq!(JavaChainOutcome::parse("failed"), JavaChainOutcome::Failed);
+        assert_eq!(JavaChainOutcome::parse("skip"), JavaChainOutcome::Skip);
+        assert_eq!(JavaChainOutcome::parse("?"), JavaChainOutcome::Pending);
+    }
+
+    #[test]
+    fn majors_are_deduped_and_sorted() {
+        let mut page = JavaPageView::new();
+        page.runtimes = vec![
+            JavaRuntimeView {
+                binary: "a".to_string(),
+                version: "17".to_string(),
+                major: 17,
+                vendor: "Temurin".to_string(),
+                origin: "managed".to_string(),
+            },
+            JavaRuntimeView {
+                binary: "b".to_string(),
+                version: "17".to_string(),
+                major: 17,
+                vendor: "Oracle".to_string(),
+                origin: "system".to_string(),
+            },
+        ];
+        assert_eq!(page.majors(), vec![17]);
+    }
+}
diff --git a/crates/presenter/src/dto/logs.rs b/crates/presenter/src/dto/logs.rs
new file mode 100644
index 0000000..6166bd6
--- /dev/null
+++ b/crates/presenter/src/dto/logs.rs
@@ -0,0 +1,78 @@
+//! 日志页 DTO：会话列表、日志行与 D8 诊断结论。
+
+use serde::{Deserialize, Serialize};
+
+/// 一次启动会话（日志页左栏单位）标识。
+pub type SessionId = String;
+
+/// 一次运行的结局（G3 左栏图标：✓ 正常 / ✗ 崩溃 / ⚠ 静默失败）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum LogOutcome {
+    /// 正常退出
+    Ok,
+    /// 崩溃（非零退出码或 hs_err_pid）
+    Crashed,
+    /// exit0 但游戏没起来（D8 新增检测）
+    SilentFail,
+}
+
+/// 会话摘要。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct LogSession {
+    /// 会话 id
+    pub id: SessionId,
+    /// 实例名（会话属于哪个实例）
+    pub instance: String,
+    /// 展示用时间（`10-29 19:22`）
+    pub when: String,
+    /// 结局
+    pub outcome: LogOutcome,
+    /// 时长（秒）
+    pub duration_secs: u64,
+}
+
+/// 日志行等级（错误行高亮）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum LogLevel {
+    /// debug
+    Debug,
+    /// info
+    Info,
+    /// warn
+    Warn,
+    /// error
+    Error,
+}
+
+/// 一行日志。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct LogLine {
+    /// 原始文本（含时间戳前缀）
+    pub text: String,
+    /// 等级
+    pub level: LogLevel,
+}
+
+/// D8 规则引擎结论（日志页崩溃诊断卡片）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Diagnosis {
+    /// 命中规则 id（`gpu.driver_old`）
+    pub rule: String,
+    /// 结论标题
+    pub title: String,
+    /// 0~100 置信度
+    pub confidence: u8,
+    /// 建议文案
+    pub hint: String,
+    /// 可一键执行的修复动作（无则只给建议）
+    pub fix: Option<String>,
+}
+
+/// 诊断结论 + 归属会话（UI 用它决定卡片显隐）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct DiagnosisReport {
+    /// 归属会话
+    pub session: SessionId,
+    /// 诊断内容
+    pub diagnosis: Diagnosis,
+}
diff --git a/crates/presenter/src/dto/mod.rs b/crates/presenter/src/dto/mod.rs
new file mode 100644
index 0000000..7c6f7ed
--- /dev/null
+++ b/crates/presenter/src/dto/mod.rs
@@ -0,0 +1,59 @@
+//! presenter ↔ core/agent 的 IPC 边界（01c §5 纪律）。
+//!
+//! 这里只允许出现「扁平 DTO / 事件 / 指令」：本 crate 的 DTO 里不得出现 `unlucky_core::*`
+//! 或 `use unlucky_agent::*` 的内部类型。core/agent 侧的 host 层负责把自身类型翻译成本模块的类型，
+//! 反向的 [`AppCommand`] 也一样。P0 阶段由 [`crate::mock`] 的假后端实现 [`Backend`] 驱动骨架，
+//! P3 起由 [`crate::host`] 的真实后端驱动全部页面。
+//!
+//! 结构：**按领域拆子模块**（instances / versions / logs / agent / accounts / java /
+//! settings / install / notices / content / events），全量 `pub use` 出去，调用方依旧写
+//! `crate::dto::InstanceSummary` 这类路径。
+//! 契约说明（字段口径、事件顺序、错误语义）见 `DevDocs/SubAgentsTalk/app-DTO通道约定.md`；
+//! UI 侧的唯一入口与 iced 接线用法见 crate 文档（`src/lib.rs`）。
+//!
+//! 全部跨界类型 `Serialize + Deserialize`（AGENTS §6）：事件与快照是 IPC 契约，
+//! 序列化能力由 derive 钉住，`dto` 的单测做 round-trip 断言。
+
+mod accounts;
+mod agent;
+mod content;
+mod events;
+mod install;
+mod instances;
+mod java;
+mod logs;
+mod notices;
+// M113: import/export —— 整合包导入/导出的 DTO（M111/M112 管线的 IPC 面）
+mod pack;
+mod settings;
+mod versions;
+
+pub use accounts::{
+    looks_like_jwt, redact, valid_offline_name, AccountKind, AccountNotice, AccountNoticeCode,
+    AccountView, AuthlibLoginView, AuthlibRequest, DeviceLoginPhase, DeviceLoginView, LoginFailure,
+    SkinImage, REDACTED,
+};
+pub use agent::{AgentEvent, ChatMessage, ChatRole, ConfirmRequest, Sensitivity, ToolCallView};
+pub use content::{
+    loader_facet, ContentHit, ContentInstallRequest, ContentKind, ContentQuery, ContentResults,
+    ContentSort, ContentSource, ContentState,
+};
+pub use events::{AppCommand, AppEvent, Backend, CoreEvent, LaunchFinished, LiveLogBatch};
+pub use install::{derive_speed, human_bytes, InstallProgressView, InstallStage};
+pub use instances::{
+    CreateRequest, InstanceId, InstanceRuntime, InstanceSummary, LaunchStage, LoaderInfo,
+    LoaderKind, Progress,
+};
+pub use java::{JavaChainOutcome, JavaChainStep, JavaPageView, JavaRuntimeView, JavaVendorView};
+pub use logs::{Diagnosis, DiagnosisReport, LogLevel, LogLine, LogOutcome, LogSession, SessionId};
+pub use notices::{NoticeLevel, NoticeView};
+// M113: import/export
+pub use pack::{
+    ConflictChoiceView, ConflictFileView, ConflictReasonView, ExportClassView, ExportDoneView,
+    ExportFileView, ExportPreviewView, ExportReasonView, ExportRequestView, ExportState,
+    FileActionView, ImportErrorView, ImportProgressView, ImportReportView, ImportRequestView,
+    ImportStageView, ImportState, ImportStatusView, ImportedFileView, MissingFileView,
+    MissingReasonView, PackCommand, PackEvent, PackFormatView, PackState, ProbeView,
+};
+pub use settings::{SettingControl, SettingGroupView, SettingRowView};
+pub use versions::{AncientKind, VersionCategory, VersionKind, VersionSummary};
diff --git a/crates/presenter/src/dto/notices.rs b/crates/presenter/src/dto/notices.rs
new file mode 100644
index 0000000..36e0ac4
--- /dev/null
+++ b/crates/presenter/src/dto/notices.rs
@@ -0,0 +1,73 @@
+//! 横幅通知 DTO：实例页/下载页顶部的「需要注意」提示条。
+//!
+//! 与 Toast 的分工：Toast 是「刚才发生了什么」（3 秒消失），通知条是
+//! 「现在需要你处理」（用户点了才收）。隔离模式切换提示（M30 `ModeChangeWarning`）
+//! 与启动失败都用它。
+
+use serde::{Deserialize, Serialize};
+
+/// 通知级别。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum NoticeLevel {
+    /// 一般信息
+    Info,
+    /// 需要留意（黄条）
+    Warn,
+    /// 失败（红条）
+    Error,
+}
+
+impl NoticeLevel {
+    /// 级别文案（无障碍/测试用）。
+    pub fn label(self) -> &'static str {
+        match self {
+            Self::Info => "信息",
+            Self::Warn => "注意",
+            Self::Error => "错误",
+        }
+    }
+}
+
+/// 一条通知。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct NoticeView {
+    /// 稳定 id（关闭时按它移除）
+    pub id: String,
+    /// 级别
+    pub level: NoticeLevel,
+    /// 标题
+    pub title: String,
+    /// 正文
+    pub body: String,
+}
+
+impl NoticeView {
+    /// 建一条。
+    pub fn new(id: &str, level: NoticeLevel, title: &str, body: &str) -> Self {
+        Self {
+            id: id.to_string(),
+            level,
+            title: title.to_string(),
+            body: body.to_string(),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn notices_are_serde_round_trip_safe() {
+        let notice = NoticeView::new(
+            "isolation:demo",
+            NoticeLevel::Warn,
+            "隔离模式已切换",
+            "旧目录里还有 mods/saves",
+        );
+        let text = serde_json::to_string(&notice).expect("序列化");
+        let back: NoticeView = serde_json::from_str(&text).expect("反序列化");
+        assert_eq!(back, notice);
+        assert_eq!(back.level.label(), "注意");
+    }
+}
diff --git a/crates/presenter/src/dto/pack.rs b/crates/presenter/src/dto/pack.rs
new file mode 100644
index 0000000..7fbd1fb
--- /dev/null
+++ b/crates/presenter/src/dto/pack.rs
@@ -0,0 +1,51 @@
+//! 整合包导入/导出 DTO（M113 `PACKUI`）：把 M111/M112 的管线结果搬过 IPC 边界。
+//!
+//! ## 为什么这里几乎是 core 报告的逐字段镜像
+//!
+//! `crate::dto` 的规矩（见 `dto/mod.rs`）：**不得出现 `unlucky_core::*` 类型**，跨边界类型必须
+//! `Serialize + Deserialize`。所以这里一面不引 core，一面又不许「按 UI 方便重新发明一套语义」——
+//! 三态、阶段、分类、原因全部**逐条对应** `core::addon::import::report` 与
+//! `core::addon::export::report`，只把 `&'static str` 的稳定码换成人读串、把 `PathBuf` 落成
+//! 页面能显示的形态。翻译（core 类型 → 本模块）发生在 `host::addon`，页面侧不认识 core。
+//!
+//! 三条不许在翻译时丢的东西：
+//!
+//! 1. **三态**（[`ImportStatusView`]）：`Partial` 不是 `Success`。把「缺了 3 个文件」说成成功，
+//!    用户会在启动后才发现缺依赖；
+//! 2. **容忍 / 致命的分野**：[`MissingFileView`] 是「搞不到某个文件」（实例可用），
+//!    [`ImportErrorView`] 是「已整包回滚」（实例零残留）。UI 必须让这两类**视觉可区分**；
+//! 3. **导出的三分类**（[`ExportClassView`]）：`Inline` 是「证明不了可被远程替代，原字节进
+//!    `overrides/`」，`Skipped` 是「压根没进包」。`skipped > 0` 意味着包**不完整**。
+//!
+//! ## 文件分工（守 400 行）
+//!
+//! | 文件 | 职责 |
+//! |---|---|
+//! | [`format`] | [`PackFormatView`]（三个格式 + slug 对齐） |
+//! | [`import`] | 请求 / 进度 / 三态 / 逐项原因 / 探测诊断 |
+//! | [`conflict`] | 冲突成因、处置、三方哈希 |
+//! | [`export`] | 三分类 / 逐条原因 / 预检 |
+//!
+//! ## 冲突：默认一侧永远是用户那一侧
+//!
+//! [`ImportRequestView::overwrite`] 缺省 `false` = `ConflictPolicy::KeepUser`。这是 M113 的硬线：
+//! **绝不默认覆盖用户改过的文件**。
+
+mod conflict;
+mod event;
+mod export;
+mod format;
+mod import;
+
+pub use conflict::{ConflictChoiceView, ConflictFileView, ConflictReasonView};
+pub use event::{PackCommand, PackEvent, PackState};
+pub use export::{
+    ExportClassView, ExportDoneView, ExportFileView, ExportPreviewView, ExportReasonView,
+    ExportRequestView, ExportState,
+};
+pub use format::PackFormatView;
+pub use import::{
+    FileActionView, ImportErrorView, ImportProgressView, ImportReportView, ImportRequestView,
+    ImportStageView, ImportState, ImportStatusView, ImportedFileView, MissingFileView,
+    MissingReasonView, ProbeView,
+};
diff --git a/crates/presenter/src/dto/pack/conflict.rs b/crates/presenter/src/dto/pack/conflict.rs
new file mode 100644
index 0000000..e5c07f1
--- /dev/null
+++ b/crates/presenter/src/dto/pack/conflict.rs
@@ -0,0 +1,71 @@
+//! 冲突的 DTO：成因、本次处置、以及三方哈希的那一条账。
+//!
+//! 三条判据与 core 的 `ConflictReason` 一一对应；`choice` 是**事后记录**（本次实际怎么处置的），
+//! 不是「逐文件决策通道」——core 今天没有那种通道（`ConflictPolicy` 是整次导入一个全局档）。
+//! 「默认保留用户那一侧」这条硬线在 `ImportRequestView::overwrite` 缺省 `false` 上。
+
+use serde::{Deserialize, Serialize};
+
+/// 冲突成因（core 的三条判据）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ConflictReasonView {
+    /// 基线里记过，磁盘内容与基线不同 ⇒ 用户改过。
+    UserModified,
+    /// 基线里记过，磁盘上却没了 ⇒ 用户删过。
+    UserDeleted,
+    /// 没有基线可判，磁盘上本来就有同名文件。
+    PreExisting,
+}
+
+impl ConflictReasonView {
+    /// 从 core 的 id 反解。
+    #[must_use]
+    pub fn from_slug(slug: &str) -> Option<Self> {
+        match slug {
+            "user_modified" => Some(Self::UserModified),
+            "user_deleted" => Some(Self::UserDeleted),
+            "pre_existing" => Some(Self::PreExisting),
+            _ => None,
+        }
+    }
+}
+
+/// 冲突本次实际采用的处置。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ConflictChoiceView {
+    /// 保留用户侧（**默认**）。
+    KeepUser,
+    /// 用包内内容覆盖（用户显式要求「整合包说了算」）。
+    Overwrite,
+}
+
+impl ConflictChoiceView {
+    /// 从 core 的 id 反解。
+    #[must_use]
+    pub fn from_slug(slug: &str) -> Option<Self> {
+        match slug {
+            "keep_user" => Some(Self::KeepUser),
+            "overwrite" => Some(Self::Overwrite),
+            _ => None,
+        }
+    }
+}
+
+/// 一条冲突（**事后账**：本次实际怎么处置的）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ConflictFileView {
+    /// 实例内相对路径。
+    pub path: String,
+    /// 成因。
+    pub reason: ConflictReasonView,
+    /// 本次实际采用的处置。
+    pub choice: ConflictChoiceView,
+    /// 包内声明的 SHA-1。
+    pub pack_sha1: String,
+    /// 上次导入写下的 SHA-1（没有基线时 `None`）。
+    pub base_sha1: Option<String>,
+    /// 磁盘现状的 SHA-1（文件不存在时 `None`）。
+    pub disk_sha1: Option<String>,
+    /// 包内声明的字节数。
+    pub pack_size: u64,
+}
diff --git a/crates/presenter/src/dto/pack/event.rs b/crates/presenter/src/dto/pack/event.rs
new file mode 100644
index 0000000..61b0038
--- /dev/null
+++ b/crates/presenter/src/dto/pack/event.rs
@@ -0,0 +1,128 @@
+//! 导入/导出的**指令、事件与面板状态**（M113）：`AppCommand::Pack` / `CoreEvent::Pack` 的载荷。
+//!
+//! ## 为什么整条流程只占一个枚举变体
+//!
+//! `AppCommand` / `CoreEvent` / `HostTask` 是这条装配链上最拥挤的三个枚举（M106/M107/M108/M109/M114
+//! 都在往里加变体）。所以导入导出**不各占一个变体**，而是各自一个 [`PackCommand`] / [`PackEvent`]
+//! 子枚举、外面只多一层包装：共享枚举里只多一行，rebase 时不用替别人定序。
+//!
+//! ## 取消是**界面级**的，不是管线级的（如实写）
+//!
+//! core 的 `import_pack` 没有取消令牌（`ImportRequest` 里没有 cancel 字段，`progress` 回调是
+//! 纯通知、拿不到控制流）。所以「取消导入」在本轮的含义是：
+//!
+//! 1. 立刻把面板收回（[`PackEvent::Progress`] 传 `None`）；
+//! 2. **丢弃**这一次运行之后回来的事件（代次比较，与 M105 的安装取消同一套做法）；
+//! 3. 后台那次导入会继续跑到结束——**它不会因为点了取消而停手**。
+//!
+//! 这条必须在报告里如实登记：把它写成「真的停下来了」就是撒谎。
+//!
+//! ## 事件 → 状态只有一条路
+//!
+//! [`PackState::apply`] 是**唯一**的写入点（与 `AppState::apply` 同一条纪律）：页面读到的进度、
+//! 报告、预检都只能从事件来，页面自己不做乐观回显。
+
+use serde::{Deserialize, Serialize};
+
+use crate::dto::pack::{
+    ExportDoneView, ExportPreviewView, ExportRequestView, ExportState, ImportProgressView,
+    ImportReportView, ImportRequestView, ImportState, ProbeView,
+};
+
+/// app → host 的导入/导出意图。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum PackCommand {
+    /// 开始导入（目标实例已选好；`instance` 为 `None` = 按 `instance_name` 新建目录）
+    Import(Box<ImportRequestView>),
+    /// 跑**预检**（只扫描分类，**不写盘**）
+    Export(Box<ExportRequestView>),
+    /// 确认写盘。载荷是**预检时那一份请求**，不是页面当前字段——否则「预检 A、写 B」。
+    Confirm(Box<ExportRequestView>),
+    /// 关掉面板（导入结果 / 探测诊断 / 导出预检都收起来，回到入口态）
+    Dismiss,
+}
+
+/// host → app 的导入/导出事件。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum PackEvent {
+    /// 导入进度（`None` = 收回面板：取消，或流程已经给出结果）
+    Progress(Option<Box<ImportProgressView>>),
+    /// 导入结果（三态 + 逐项原因；致命失败也走它，`report.error` 里有原因）
+    Report(Box<ImportReportView>),
+    /// 探测失败：这个包看起来像什么、缺哪个标记文件
+    Probe(Box<ProbeView>),
+    /// 导出预检结果
+    Preview(Box<ExportPreviewView>),
+    /// 导出写盘完成
+    Exported(Box<ExportDoneView>),
+    /// 导出/预检在 host 侧失败（实例找不到、目录派生失败……一句人读原因）
+    ExportFailed(String),
+    /// 用户取消了导入：面板收回，但后台那次导入会跑完（core 没有取消令牌），
+    /// 所以留一位给界面说清「还在跑、结果作废」。
+    Cancelled,
+    /// 关掉所有面板
+    Cleared,
+}
+
+/// 导入/导出两个面板的状态（`AppState::pack` 的全部内容）。
+#[derive(Debug, Clone, PartialEq, Default)]
+pub struct PackState {
+    /// 导入侧（进度 / 结果 / 探测诊断）
+    pub import: ImportState,
+    /// 导出侧（预检 / 完成 / 失败）
+    pub export: ExportState,
+}
+
+impl PackState {
+    /// 事件 → 状态（**唯一**写入点）。
+    pub fn apply(&mut self, event: PackEvent) {
+        match event {
+            PackEvent::Progress(progress) => {
+                self.import.progress = progress.map(|progress| *progress);
+            }
+            PackEvent::Report(report) => {
+                // 结果到了：进度面板让位，探测诊断作废（这一轮已经有结论了）
+                self.import.progress = None;
+                self.import.probe = None;
+                self.import.report = Some(*report);
+            }
+            PackEvent::Probe(probe) => {
+                self.import.progress = None;
+                self.import.report = None;
+                self.import.probe = Some(*probe);
+            }
+            PackEvent::Preview(preview) => {
+                self.export.pending = false;
+                self.export.failed = None;
+                self.export.done = None;
+                self.export.preview = Some(*preview);
+            }
+            PackEvent::Exported(done) => {
+                self.export.pending = false;
+                self.export.failed = None;
+                // 写完之后预检就过期了：留着会让用户以为「还能再点一次确认」
+                self.export.preview = None;
+                self.export.done = Some(*done);
+            }
+            PackEvent::ExportFailed(reason) => {
+                self.export.pending = false;
+                self.export.failed = Some(reason);
+            }
+            PackEvent::Cancelled => {
+                self.import.progress = None;
+                self.import.cancelled = true;
+            }
+            PackEvent::Cleared => {
+                self.import = ImportState::default();
+                self.export = ExportState::default();
+            }
+        }
+    }
+
+    /// 记下「这次预检是对着哪份请求做的」（确认写盘时原样发回）。
+    pub fn set_export_request(&mut self, request: ExportRequestView) {
+        self.export.request = Some(request);
+        self.export.pending = true;
+        self.export.failed = None;
+    }
+}
diff --git a/crates/presenter/src/dto/pack/export.rs b/crates/presenter/src/dto/pack/export.rs
new file mode 100644
index 0000000..3ec6941
--- /dev/null
+++ b/crates/presenter/src/dto/pack/export.rs
@@ -0,0 +1,221 @@
+//! 导出侧 DTO：三分类 + 逐条原因 + **预检**（不写盘）。
+//!
+//! `ExportReasonView::class()` 是「原因 → 归类」的**唯一**映射处（与 core 同一条判据）；
+//! 预检（[`ExportPreviewView`]）与写盘结果用同一套计数方法，于是「将内联 N / 无法导出 M」
+//! 与最终报告的 N/M 同源。
+
+use std::path::PathBuf;
+
+use serde::{Deserialize, Serialize};
+
+use crate::dto::InstanceId;
+
+use super::format::PackFormatView;
+
+/// 导出时一条文件的归类。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ExportClassView {
+    /// 写进清单 `files[]`（靠远端引用代替本地字节）。
+    Remote,
+    /// 写进 `overrides/`（原字节照搬）。
+    Inline,
+    /// 没进包（读不了 / 符号链接 / 路径不安全）。
+    Skipped,
+}
+
+impl ExportClassView {
+    /// 从 core 的 id 反解。
+    #[must_use]
+    pub fn from_slug(slug: &str) -> Option<Self> {
+        match slug {
+            "remote" => Some(Self::Remote),
+            "inline" => Some(Self::Inline),
+            "skipped" => Some(Self::Skipped),
+            _ => None,
+        }
+    }
+}
+
+/// 一条文件为什么归到那个类里（与 core 的 `FileReason` 一一对应）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ExportReasonView {
+    /// 远程引用：Modrinth SHA-1 命中。
+    ModrinthSha1,
+    /// 远程引用：CurseForge 指纹命中。
+    CurseForgeFingerprint,
+    /// 内联：两个目录都不认识它。
+    NoRemoteMatch,
+    /// 内联：只有 CF 认识，目标格式用不上。
+    CurseOnlyMatch,
+    /// 内联：只有 Modrinth 认识，CF 清单用不上。
+    ModrinthOnlyMatch,
+    /// 内联：命中缺 `sha512`。
+    MissingSha512,
+    /// 内联：命中缺 `projectID`/`fileID`。
+    MissingCurseIds,
+    /// 内联：禁用文件，目标格式表达不了禁用位。
+    DisabledNotExpressible,
+    /// 跳过：符号链接。
+    SymbolicLink,
+    /// 跳过：路径过不了包内规整。
+    UnsafePath,
+    /// 跳过：读盘或算摘要失败。
+    Unreadable,
+}
+
+impl ExportReasonView {
+    /// 从 core 的 id 反解。
+    #[must_use]
+    pub fn from_slug(slug: &str) -> Option<Self> {
+        match slug {
+            "modrinth_sha1" => Some(Self::ModrinthSha1),
+            "curseforge_fingerprint" => Some(Self::CurseForgeFingerprint),
+            "no_remote_match" => Some(Self::NoRemoteMatch),
+            "curse_only_match" => Some(Self::CurseOnlyMatch),
+            "modrinth_only_match" => Some(Self::ModrinthOnlyMatch),
+            "missing_sha512" => Some(Self::MissingSha512),
+            "missing_curse_ids" => Some(Self::MissingCurseIds),
+            "disabled_not_expressible" => Some(Self::DisabledNotExpressible),
+            "symbolic_link" => Some(Self::SymbolicLink),
+            "unsafe_path" => Some(Self::UnsafePath),
+            "unreadable" => Some(Self::Unreadable),
+            _ => None,
+        }
+    }
+
+    /// 这个原因属于哪一类（**唯一映射处**，与 core 的 `FileReason::class` 同一条判据）。
+    #[must_use]
+    pub const fn class(self) -> ExportClassView {
+        match self {
+            Self::ModrinthSha1 | Self::CurseForgeFingerprint => ExportClassView::Remote,
+            Self::NoRemoteMatch
+            | Self::CurseOnlyMatch
+            | Self::ModrinthOnlyMatch
+            | Self::MissingSha512
+            | Self::MissingCurseIds
+            | Self::DisabledNotExpressible => ExportClassView::Inline,
+            Self::SymbolicLink | Self::UnsafePath | Self::Unreadable => ExportClassView::Skipped,
+        }
+    }
+}
+
+/// 一条文件的导出预检结果。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ExportFileView {
+    /// 实例内相对路径（含 `.disabled` 后缀）。
+    pub path: String,
+    /// 归类。
+    pub class: ExportClassView,
+    /// 原因。
+    pub reason: ExportReasonView,
+    /// 字节数。
+    pub bytes: u64,
+    /// 是否禁用态（`.disabled`）。
+    pub disabled: bool,
+}
+
+/// **预检**：还没有写盘，先把「会怎样」摊开给用户看。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ExportPreviewView {
+    /// 目标格式。
+    pub format: PackFormatView,
+    /// 源实例。
+    pub instance: InstanceId,
+    /// 包名。
+    pub name: String,
+    /// 包版本。
+    pub version: String,
+    /// 预定的落盘路径（确认之后写这里）。
+    pub target: PathBuf,
+    /// 逐文件结果（按路径排序）。
+    pub files: Vec<ExportFileView>,
+    /// 已知的表达不了的差异 / 取舍（core 的 `notes`）。
+    pub notes: Vec<String>,
+}
+
+impl ExportPreviewView {
+    /// 某一类的条数。
+    #[must_use]
+    pub fn count(&self, class: ExportClassView) -> usize {
+        self.files.iter().filter(|file| file.class == class).count()
+    }
+
+    /// 远程引用条数。
+    #[must_use]
+    pub fn remote_count(&self) -> usize {
+        self.count(ExportClassView::Remote)
+    }
+
+    /// 内联条数（「将内联 N 个文件」的那个 N）。
+    #[must_use]
+    pub fn inline_count(&self) -> usize {
+        self.count(ExportClassView::Inline)
+    }
+
+    /// 跳过条数（「无法导出 M 项」的那个 M）。
+    #[must_use]
+    pub fn skipped_count(&self) -> usize {
+        self.count(ExportClassView::Skipped)
+    }
+
+    /// 内联文件总字节数。
+    #[must_use]
+    pub fn inline_bytes(&self) -> u64 {
+        self.files
+            .iter()
+            .filter(|file| file.class == ExportClassView::Inline)
+            .map(|file| file.bytes)
+            .sum()
+    }
+
+    /// 包会完整吗（`false` = 有文件压根没进包，必须单独列给用户）。
+    #[must_use]
+    pub fn is_complete(&self) -> bool {
+        self.skipped_count() == 0
+    }
+}
+
+/// 导出格式选择 + 一次导出请求。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ExportRequestView {
+    /// 源实例。
+    pub instance: InstanceId,
+    /// 目标格式（只能是 [`PackFormatView::EXPORTABLE`] 里的两个）。
+    pub format: PackFormatView,
+    /// 包名（写进清单 `name`）。
+    pub name: String,
+    /// 包版本（写进清单 `version` / `versionId`）。
+    pub version: String,
+    /// 落盘路径（`None` = host 按「下载目录 + 包名 + 扩展名」给一个缺省）。
+    pub target: Option<PathBuf>,
+}
+
+/// 导出完成（写盘之后的账）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ExportDoneView {
+    /// 产出的包路径。
+    pub path: PathBuf,
+    /// 包的字节数（写完量的，不是估算）。
+    pub bytes: u64,
+    /// 远程引用条数。
+    pub remote: u32,
+    /// 内联条数。
+    pub inline: u32,
+    /// 跳过条数。
+    pub skipped: u32,
+}
+
+/// 导出侧的宿主状态（`AppState::export` 的全部内容）。
+#[derive(Debug, Clone, PartialEq, Default)]
+pub struct ExportState {
+    /// 预检结果（`None` = 还没预检）。
+    pub preview: Option<ExportPreviewView>,
+    /// **这次预检是对着哪份请求做的**（确认写盘时原样发回，防「预检 A、写 B」）。
+    pub request: Option<ExportRequestView>,
+    /// 预检在飞。
+    pub pending: bool,
+    /// 最近一次写盘的结果。
+    pub done: Option<ExportDoneView>,
+    /// 失败原因（预检或写盘）。
+    pub failed: Option<String>,
+}
diff --git a/crates/presenter/src/dto/pack/format.rs b/crates/presenter/src/dto/pack/format.rs
new file mode 100644
index 0000000..98583e2
--- /dev/null
+++ b/crates/presenter/src/dto/pack/format.rs
@@ -0,0 +1,47 @@
+//! 整合包格式：探测结果与导出目标共用一个枚举。
+//!
+//! `slug()` 与 core 的格式 id **逐字一致**（`curseforge` / `modrinth` / `multimc`），
+//! `from_slug` 是反向唯一入口——翻译发生在 `host::addon`，页面侧只认这两个函数。
+
+use serde::{Deserialize, Serialize};
+
+/// 整合包格式（探测结果与导出目标共用一个枚举）。
+///
+/// MultiMC / Prism 只**导入**不导出（core 的有意省略），所以导出侧两个入口是
+/// [`Self::Modrinth`] / [`Self::Curseforge`]。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum PackFormatView {
+    /// CurseForge：`manifest.json` + `overrides/`。
+    Curseforge,
+    /// Modrinth：`.mrpack`（`modrinth.index.json` + `overrides/`）。
+    Modrinth,
+    /// MultiMC / Prism：`mmc-pack.json` + `.minecraft/`（**只读**）。
+    Multimc,
+}
+
+impl PackFormatView {
+    /// 导出菜单里可选的两个（顺序 = 画出来的顺序）。
+    pub const EXPORTABLE: [PackFormatView; 2] =
+        [PackFormatView::Modrinth, PackFormatView::Curseforge];
+
+    /// 稳定 slug（与 core 的格式 id 逐字一致，**不要改名**）。
+    #[must_use]
+    pub const fn slug(self) -> &'static str {
+        match self {
+            Self::Curseforge => "curseforge",
+            Self::Modrinth => "modrinth",
+            Self::Multimc => "multimc",
+        }
+    }
+
+    /// 从 core 的格式 id 反解（`None` = 不认识的 id，调用方按「未知」处理，别猜）。
+    #[must_use]
+    pub fn from_slug(slug: &str) -> Option<Self> {
+        match slug {
+            "curseforge" => Some(Self::Curseforge),
+            "modrinth" => Some(Self::Modrinth),
+            "multimc" => Some(Self::Multimc),
+            _ => None,
+        }
+    }
+}
diff --git a/crates/presenter/src/dto/pack/import.rs b/crates/presenter/src/dto/pack/import.rs
new file mode 100644
index 0000000..2109558
--- /dev/null
+++ b/crates/presenter/src/dto/pack/import.rs
@@ -0,0 +1,341 @@
+//! 导入侧 DTO：请求、进度、三态、逐项原因、探测诊断。
+//!
+//! 三态（`Success` / `Partial` / `Failed`）与 core 一一对应，**`Partial` 不是 `Success`**；
+//! 容忍域（[`MissingFileView`]）与致命域（[`ImportErrorView`]）分属不同类型，UI 不可能混成一个列表。
+
+use std::path::PathBuf;
+
+use serde::{Deserialize, Serialize};
+
+use crate::dto::InstanceId;
+
+use super::conflict::ConflictFileView;
+use super::format::PackFormatView;
+
+/// 导入阶段（与 core 的 `ImportStage` 一一对应）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+pub enum ImportStageView {
+    /// 读取清单（开包 + 安全四检 + 探测）。
+    Probe,
+    /// 解压 / 三方合并覆盖内容。
+    Extract,
+    /// 补全并下载远端文件。
+    Fetch,
+    /// 落地。
+    Commit,
+    /// 登记实例。
+    Register,
+}
+
+impl ImportStageView {
+    /// 五个阶段的声明顺序（= 进度条上的先后）。
+    pub const ALL: [ImportStageView; 5] = [
+        ImportStageView::Probe,
+        ImportStageView::Extract,
+        ImportStageView::Fetch,
+        ImportStageView::Commit,
+        ImportStageView::Register,
+    ];
+
+    /// 稳定 slug。
+    #[must_use]
+    pub const fn slug(self) -> &'static str {
+        match self {
+            Self::Probe => "probe",
+            Self::Extract => "extract",
+            Self::Fetch => "fetch",
+            Self::Commit => "commit",
+            Self::Register => "register",
+        }
+    }
+
+    /// 从 core 的 id 反解。
+    #[must_use]
+    pub fn from_slug(slug: &str) -> Option<Self> {
+        Self::ALL.into_iter().find(|stage| stage.slug() == slug)
+    }
+
+    /// 这一阶段有没有「逐文件」的进度（`Probe` 只看清单，没条目可数）。
+    #[must_use]
+    pub const fn counts_files(self) -> bool {
+        !matches!(self, Self::Probe)
+    }
+}
+
+/// 导入三态（`Partial` **不是** `Success`）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ImportStatusView {
+    /// 全部落地、无冲突。
+    Success,
+    /// 有缺文件或有冲突（内容不完整，但实例可用）。
+    Partial,
+    /// 致命失败，**已整包回滚**。
+    Failed,
+}
+
+impl ImportStatusView {
+    /// 稳定 slug。
+    #[must_use]
+    pub const fn slug(self) -> &'static str {
+        match self {
+            Self::Success => "success",
+            Self::Partial => "partial",
+            Self::Failed => "failed",
+        }
+    }
+
+    /// 从 core 的 id 反解。
+    #[must_use]
+    pub fn from_slug(slug: &str) -> Option<Self> {
+        match slug {
+            "success" => Some(Self::Success),
+            "partial" => Some(Self::Partial),
+            "failed" => Some(Self::Failed),
+            _ => None,
+        }
+    }
+
+    /// 实例可用吗（`Success` / `Partial` 都是「装上了」）。
+    #[must_use]
+    pub const fn installed(self) -> bool {
+        !matches!(self, Self::Failed)
+    }
+}
+
+/// 一条落地文件本次被怎么处理。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum FileActionView {
+    /// 新写入。
+    Installed,
+    /// 覆盖写入（用户没改过）。
+    Replaced,
+    /// 与包内一致，没动。
+    SkippedIdentical,
+    /// 用户改过 / 删过，按策略保留了用户那一侧。
+    KeptUser,
+}
+
+impl FileActionView {
+    /// 从 core 的 id 反解。
+    #[must_use]
+    pub fn from_slug(slug: &str) -> Option<Self> {
+        match slug {
+            "installed" => Some(Self::Installed),
+            "replaced" => Some(Self::Replaced),
+            "skipped_identical" => Some(Self::SkippedIdentical),
+            "kept_user" => Some(Self::KeptUser),
+            _ => None,
+        }
+    }
+
+    /// 是否真的写了盘。
+    #[must_use]
+    pub const fn wrote(self) -> bool {
+        matches!(self, Self::Installed | Self::Replaced)
+    }
+}
+
+/// 一次导入的请求。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ImportRequestView {
+    /// 包路径：zip（`.zip` / `.mrpack`）或 MultiMC 实例目录。
+    pub pack: PathBuf,
+    /// 目标实例（`None` = 按包名新建一个）。
+    pub instance: Option<InstanceId>,
+    /// 新实例的展示名（`None` = 用包名）。
+    pub instance_name: Option<String>,
+    /// 冲突翻档：`false`（**默认**）= 保留用户那一侧；`true` = 以包为准覆盖。
+    ///
+    /// 页面上把 `true` 那条写成「以包为准重新导入」，并且**只在用户显式点过之后**才发。
+    pub overwrite: bool,
+}
+
+/// 一条导入进度。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ImportProgressView {
+    /// 阶段。
+    pub stage: ImportStageView,
+    /// 阶段内已完成条目数。
+    pub done: u32,
+    /// 阶段内总条目数（`0` = 未知）。
+    pub total: u32,
+    /// 当前条目的实例内路径（阶段刚开始时为 `None`）。
+    pub current: Option<String>,
+    /// 包名（面板标题那一行）。
+    pub pack: String,
+}
+
+impl ImportProgressView {
+    /// 空进度（刚派发，后端还没回第一条）。
+    #[must_use]
+    pub fn new(pack: impl Into<String>) -> Self {
+        Self {
+            stage: ImportStageView::Probe,
+            done: 0,
+            total: 0,
+            current: None,
+            pack: pack.into(),
+        }
+    }
+
+    /// 计数已知吗（`false` = 不画确定态进度条，避免「静止的假进度」）。
+    #[must_use]
+    pub const fn is_known(&self) -> bool {
+        self.total > 0
+    }
+
+    /// 阶段内完成比例 0.0~1.0（未知时 `0.0`）。
+    #[must_use]
+    pub fn ratio(&self) -> f32 {
+        if self.total == 0 {
+            return 0.0;
+        }
+        (self.done as f32 / self.total as f32).clamp(0.0, 1.0)
+    }
+}
+
+/// 一条落地文件。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ImportedFileView {
+    /// 实例内相对路径。
+    pub path: String,
+    /// 本次处置。
+    pub action: FileActionView,
+    /// 字节数。
+    pub bytes: u64,
+}
+
+/// 一个文件「搞不到」的成因（**容忍**域）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum MissingReasonView {
+    /// 调用方没给 fetcher（离线导入）。
+    Offline,
+    /// 条目补不出下载地址（CF 缺 API 客户端 / `downloads` 为空）。
+    NoSource,
+    /// 尝试过但失败（404 / 网络）。
+    FetchFailed,
+}
+
+impl MissingReasonView {
+    /// 从 core 的 id 反解。
+    #[must_use]
+    pub fn from_slug(slug: &str) -> Option<Self> {
+        match slug {
+            "offline" => Some(Self::Offline),
+            "no_source" => Some(Self::NoSource),
+            "fetch_failed" => Some(Self::FetchFailed),
+            _ => None,
+        }
+    }
+}
+
+/// 一个「搞不到」的文件（容忍，但逐条列出）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct MissingFileView {
+    /// 实例内路径（CF 补全失败时没有）。
+    pub path: Option<String>,
+    /// 人读标识（CF 条目是 `projectID:fileID`，其余是路径）。
+    pub display: String,
+    /// 为什么搞不到。
+    pub reason: MissingReasonView,
+    /// 细节（错误原文）。
+    pub detail: String,
+}
+
+/// 一次**已整包回滚**的致命失败。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ImportErrorView {
+    /// 稳定码（`pack_traversal` / `import_integrity` …，进日志与 `--json`）。
+    pub code: String,
+    /// 人读大类名。
+    pub label: String,
+    /// 具体是什么。
+    pub message: String,
+    /// 补救建议（core 有就给）。
+    pub hint: Option<String>,
+}
+
+/// 一次导入的完整结果。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ImportReportView {
+    /// 三态。
+    pub status: ImportStatusView,
+    /// 命中的格式（`None` = 探测都没过）。
+    pub format: Option<PackFormatView>,
+    /// 包名。
+    pub pack_name: Option<String>,
+    /// 包版本。
+    pub pack_version: Option<String>,
+    /// 游戏版本。
+    pub game_version: Option<String>,
+    /// 加载器（人读串，如 `fabric-loader 0.15.11`）。
+    pub loader: Option<String>,
+    /// 实例绑定的版本 id。
+    pub version_id: Option<String>,
+    /// 目标实例目录。
+    pub target: PathBuf,
+    /// 落地的文件。
+    pub files: Vec<ImportedFileView>,
+    /// 冲突清单。
+    pub conflicts: Vec<ConflictFileView>,
+    /// 缺文件清单（容忍）。
+    pub missing: Vec<MissingFileView>,
+    /// MultiMC 不支持的 component（逐项）。
+    pub rejected: Vec<String>,
+    /// 注记。
+    pub warnings: Vec<String>,
+    /// 致命错误（`status == Failed` 时必有）。
+    pub error: Option<ImportErrorView>,
+    /// 登记的实例名。
+    pub registered: Option<String>,
+    /// 本次写入的字节数。
+    pub bytes_written: u64,
+    /// 回滚是否完整（`false` = 目标目录可能与导入前不一致，逐条在 `warnings` 里）。
+    pub rolled_back: bool,
+}
+
+impl ImportReportView {
+    /// 真正写盘的文件条数。
+    #[must_use]
+    pub fn written(&self) -> usize {
+        self.files.iter().filter(|file| file.action.wrote()).count()
+    }
+
+    /// 要用户看一眼的东西条数（冲突 + 缺文件 + 被拒 component）。
+    #[must_use]
+    pub fn issue_count(&self) -> usize {
+        self.conflicts.len() + self.missing.len() + self.rejected.len()
+    }
+}
+
+/// 探测失败的**具名**诊断：「看起来像 X，但缺 Y」。
+///
+/// 为什么不由 core 给：core 的 `detect` 只回答「谁认领」，一个都不认领时只回一句
+/// `pack_unsupported` + 试过哪些格式。而用户手里那个包往往**差一点点**就是某个已知格式
+/// （CF 导出漏了 `manifest.json`、mrpack 被浏览器改名成 `.zip` 后解压丢了 index）。
+/// 判断「像哪个」要看包内到底有哪些标记文件，这是宿主层拿着 `PackArchive` 才看得见的事。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ProbeView {
+    /// 最像哪个格式（`None` = 三个都不像）。
+    pub looks_like: Option<PackFormatView>,
+    /// 该格式**缺**的标记文件（逐条，按判据顺序）。
+    pub missing: Vec<String>,
+    /// 包里实际看到的标记（逐条）。
+    pub saw: Vec<String>,
+    /// 一句兜底说明（也是 core 的原文：试过哪些格式）。
+    pub detail: String,
+}
+
+/// 导入侧的宿主状态（`AppState::import` 的全部内容）。
+#[derive(Debug, Clone, PartialEq, Default)]
+pub struct ImportState {
+    /// 正在跑的进度（`None` = 没在跑）。
+    pub progress: Option<ImportProgressView>,
+    /// 用户点了取消（M113 r1）：**面板收回但后台还在跑**，所以这一位要留在界面上——
+    /// 否则用户会以为「没建成」，回头再导一次就撞「directory already exists」。
+    pub cancelled: bool,
+    /// 最近一次的结果（`None` = 还没导过）。
+    pub report: Option<ImportReportView>,
+    /// 探测失败的具名诊断（有它就让用户看清「像 X 缺 Y」，而不是一句「无法识别」）。
+    pub probe: Option<ProbeView>,
+}
diff --git a/crates/presenter/src/dto/settings.rs b/crates/presenter/src/dto/settings.rs
new file mode 100644
index 0000000..428decc
--- /dev/null
+++ b/crates/presenter/src/dto/settings.rs
@@ -0,0 +1,220 @@
+//! 设置页 DTO：设置分组的通用行模型。
+//!
+//! 「行」是 UI 与 `core::setting` schema 之间的唯一形状：一行 = 一个键 + 一种控件 +
+//! 当前值。写回走 [`crate::dto::AppCommand::SetSetting`]，由 host 用 `SettingStore::set`
+//! 落盘（不自己拼 JSON、不另立配置文件，`AGENTS §6`）。
+
+use serde::{Deserialize, Serialize};
+
+/// 控件类型（决定设置页画什么）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum SettingControl {
+    /// 开关
+    Toggle,
+    /// 分段单选（`options` + `selected`）
+    Choice,
+    /// 单行文本（`value_text`）
+    Text,
+    /// 只读展示（当前路径/当前版本这类）
+    ReadOnly,
+    /// 动作按钮（`action` 给回调 id）
+    Action,
+}
+
+/// 一行设置。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct SettingRowView {
+    /// schema 键（`download.concurrency`）
+    pub key: String,
+    /// 行标题
+    pub label: String,
+    /// 说明/当前值附注
+    pub description: String,
+    /// 控件
+    pub control: SettingControl,
+    /// 开关值
+    pub flag: bool,
+    /// 单选序号
+    pub selected: i32,
+    /// 单选项文案
+    pub options: Vec<String>,
+    /// 文本值
+    pub value_text: String,
+    /// 动作 id（`detect_region` 这类）
+    pub action: String,
+}
+
+impl SettingRowView {
+    /// 开关行。
+    pub fn toggle(key: &str, label: &str, description: &str, value: bool) -> Self {
+        Self {
+            key: key.to_string(),
+            label: label.to_string(),
+            description: description.to_string(),
+            control: SettingControl::Toggle,
+            flag: value,
+            selected: 0,
+            options: Vec::new(),
+            value_text: String::new(),
+            action: String::new(),
+        }
+    }
+
+    /// 单选行。
+    pub fn choice(
+        key: &str,
+        label: &str,
+        description: &str,
+        options: &[&str],
+        selected: i32,
+    ) -> Self {
+        Self {
+            key: key.to_string(),
+            label: label.to_string(),
+            description: description.to_string(),
+            control: SettingControl::Choice,
+            flag: false,
+            selected,
+            options: options.iter().map(|item| (*item).to_string()).collect(),
+            value_text: String::new(),
+            action: String::new(),
+        }
+    }
+
+    /// 文本行。
+    pub fn text(key: &str, label: &str, description: &str, value: &str) -> Self {
+        Self {
+            key: key.to_string(),
+            label: label.to_string(),
+            description: description.to_string(),
+            control: SettingControl::Text,
+            flag: false,
+            selected: 0,
+            options: Vec::new(),
+            value_text: value.to_string(),
+            action: String::new(),
+        }
+    }
+
+    /// 只读行。
+    pub fn read_only(label: &str, value: &str) -> Self {
+        Self {
+            key: String::new(),
+            label: label.to_string(),
+            description: value.to_string(),
+            control: SettingControl::ReadOnly,
+            flag: false,
+            selected: 0,
+            options: Vec::new(),
+            value_text: value.to_string(),
+            action: String::new(),
+        }
+    }
+
+    /// 动作行。
+    pub fn action(key: &str, label: &str, description: &str, action: &str) -> Self {
+        Self {
+            key: key.to_string(),
+            label: label.to_string(),
+            description: description.to_string(),
+            control: SettingControl::Action,
+            flag: false,
+            selected: 0,
+            options: Vec::new(),
+            value_text: String::new(),
+            action: action.to_string(),
+        }
+    }
+}
+
+/// 一个设置分组（设置页右栏的一段）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct SettingGroupView {
+    /// 分组 id（与设置页子导航的 `SettingSection` 同名：download / java / data / ai / mcp）
+    pub id: String,
+    /// 分组标题
+    pub title: String,
+    /// 行
+    pub rows: Vec<SettingRowView>,
+}
+
+impl SettingGroupView {
+    /// 建组。
+    pub fn new(id: &str, title: &str) -> Self {
+        Self {
+            id: id.to_string(),
+            title: title.to_string(),
+            rows: Vec::new(),
+        }
+    }
+
+    /// 追加一行（链式）。
+    pub fn with(mut self, row: SettingRowView) -> Self {
+        self.rows.push(row);
+        self
+    }
+}
+
+/// 在分组快照里找一个键的当前值（设置页回填用）。
+pub fn find_row<'a>(groups: &'a [SettingGroupView], key: &str) -> Option<&'a SettingRowView> {
+    groups
+        .iter()
+        .flat_map(|group| group.rows.iter())
+        .find(|row| row.key == key)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn rows_carry_exactly_one_control_kind() {
+        let toggle = SettingRowView::toggle("agent.mcp.enabled", "MCP", "", true);
+        assert_eq!(toggle.control, SettingControl::Toggle);
+        assert!(toggle.flag);
+
+        let choice = SettingRowView::choice("download.region", "地区", "", &["auto", "cn"], 1);
+        assert_eq!(choice.options, vec!["auto", "cn"]);
+        assert_eq!(choice.selected, 1);
+
+        let action = SettingRowView::action("java.action", "检测", "", "detect_region");
+        assert_eq!(action.action, "detect_region");
+    }
+
+    #[test]
+    fn find_row_scans_all_groups() {
+        let groups = vec![
+            SettingGroupView::new("download", "下载").with(SettingRowView::text(
+                "download.proxy_url",
+                "代理",
+                "",
+                "",
+            )),
+            SettingGroupView::new("mcp", "MCP").with(SettingRowView::toggle(
+                "agent.mcp.enabled",
+                "开关",
+                "",
+                false,
+            )),
+        ];
+        assert_eq!(
+            find_row(&groups, "agent.mcp.enabled").map(|row| row.label.as_str()),
+            Some("开关")
+        );
+        assert!(find_row(&groups, "nope").is_none());
+    }
+
+    #[test]
+    fn rows_are_serde_round_trip_safe() {
+        let group = SettingGroupView::new("download", "下载").with(SettingRowView::choice(
+            "download.concurrency",
+            "并发",
+            "",
+            &["4", "8", "16"],
+            1,
+        ));
+        let text = serde_json::to_string(&group).expect("序列化");
+        let back: SettingGroupView = serde_json::from_str(&text).expect("反序列化");
+        assert_eq!(back, group);
+    }
+}
diff --git a/crates/presenter/src/dto/versions.rs b/crates/presenter/src/dto/versions.rs
new file mode 100644
index 0000000..844c6e6
--- /dev/null
+++ b/crates/presenter/src/dto/versions.rs
@@ -0,0 +1,62 @@
+//! 下载页 DTO：版本列表与分类（含远古版子类，D16/Q24-4）。
+
+use serde::{Deserialize, Serialize};
+
+/// 版本类型（远古版按 unlisted-versions 的分类拆开）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum VersionKind {
+    /// 正式版
+    Release,
+    /// 预览版（snapshot）
+    Snapshot,
+    /// 远古版（带子类）
+    Ancient(AncientKind),
+}
+
+/// 远古版子类。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum AncientKind {
+    /// classic（rd-*）
+    Classic,
+    /// old_alpha（a1.*）
+    OldAlpha,
+    /// old_beta（b1.*）
+    OldBeta,
+    /// 未列入官方清单的远古版汇总
+    Unlisted,
+}
+
+impl VersionKind {
+    /// 是否属于「远古版」——列表行要加警示徽标。
+    pub fn is_ancient(self) -> bool {
+        matches!(self, Self::Ancient(_))
+    }
+}
+
+/// 下载页版本行。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct VersionSummary {
+    /// 版本 id（如 `1.20.4` / `rd-132211`）
+    pub id: String,
+    /// 版本类型
+    pub kind: VersionKind,
+    /// 发布日期（ISO-8601 日期部分）
+    pub released: String,
+    /// 本地是否已安装（行尾显示「已装」）
+    pub installed: bool,
+}
+
+/// 下载页左侧分类（页内常驻侧栏的选中项）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum VersionCategory {
+    /// 正式版
+    Release,
+    /// 预览版
+    Snapshot,
+    /// 远古版某子类
+    Ancient(AncientKind),
+    /// 整合包（P1）
+    Modpack,
+    /// Mod（P1）
+    Mod,
+}
diff --git a/crates/presenter/src/host/accounts.rs b/crates/presenter/src/host/accounts.rs
new file mode 100644
index 0000000..8e3b613
--- /dev/null
+++ b/crates/presenter/src/host/accounts.rs
@@ -0,0 +1,382 @@
+//! 账户：三轨统一列表（只读公开字段）+ 离线新增 + 删除/切换 + 微软登录（两条流）。
+//!
+//! 凭据红线（D9）：`Credentials` / `MicrosoftSession` 只在本模块与 `launch.rs` 里出现，
+//! 出口一律是 [`AccountView`] / [`DeviceLoginView`]。
+//!
+//! 两条登录流：授权码（[`start_browser_login`]，GUI 默认：拉起系统浏览器 + 本地回调，
+//! `research/08` §3 方案 A）与设备码（[`start_login`]，无浏览器/CLI 场景）。除了「怎么拿到
+//! MS access_token」之外完全共用：同一个取消槽位、同一段账户入库、同一个刷新链。
+//!
+//! 取消语义：轮询/等回调都跑在 `core` 里、没有取消钩子，所以取消只把面板收回；线程收尾时
+//! 若发现「已取消」就不入库（避免用户点了取消却凭空多出一个账户）。
+
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+
+use unlucky_core::auth::account::Credentials;
+use unlucky_core::auth::microsoft::{now_ms, MicrosoftAuth, MicrosoftSession};
+use unlucky_core::auth::offline::offline_meta;
+use unlucky_core::auth::{AccountStore, AuthResult};
+use unlucky_core::download::blocking::block_on;
+
+use crate::dto::CoreEvent;
+use crate::dto::{
+    valid_offline_name, AccountKind, AccountNotice, AccountNoticeCode, AccountView,
+    DeviceLoginView, LoginFailure,
+};
+
+use super::env::HostEnv;
+use super::job::{spawn, HostTask, JobSender};
+use super::opener;
+
+/// 第三方轨（服务发现 / 密码登录 / 皮肤抓取）。
+pub mod authlib;
+
+mod refresh;
+
+mod failure;
+
+pub use failure::AccountFailure;
+
+use failure::classify;
+
+pub use authlib::{fetch_skin, spawn_probe, start_login as start_authlib_login};
+
+impl super::CoreHost {
+    /// 推一条账户页横幅（一次性操作结果；页面渲染后由用户关掉）。
+    pub(super) fn notice(&mut self, code: AccountNoticeCode, subject: &str, detail: &str) {
+        self.send(CoreEvent::AccountNoticeChanged(Some(AccountNotice::new(
+            code, subject, detail,
+        ))));
+    }
+
+    /// 账户写操作失败：**原文进日志**，页面只拿结构化码 + 主题名。
+    pub(super) fn notice_failure(&mut self, failure: AccountFailure, subject: &str) {
+        eprintln!(
+            "[accounts] 操作失败（{}，subject={subject}）：{}",
+            failure.code.code(),
+            failure.detail
+        );
+        self.notice(failure.code, subject, &failure.detail);
+    }
+}
+
+/// 账户列表（公开字段）。
+pub fn accounts(env: &HostEnv, active: Option<&str>) -> Vec<AccountView> {
+    let store = AccountStore::open(env.layout.auth_data());
+    store
+        .accounts()
+        .iter()
+        .map(|meta| AccountView {
+            id: meta.id.as_str().to_string(),
+            name: meta.display_name().to_string(),
+            kind: AccountKind::parse(meta.kind.as_str()),
+            profile_id: meta.profile_id.clone(),
+            login_name: meta.login_name.clone().unwrap_or_default(),
+            created: display_ms(meta.created_at_ms),
+            active: active.is_some_and(|id| id == meta.id.as_str()),
+            server_url: meta.server_url.clone().unwrap_or_default(),
+            // 皮肤是网络产物：列表先给 `None`，host 抓到之后按账户 id 盖回去（见 `CoreHost`）
+            skin: None,
+        })
+        .collect()
+}
+
+/// 毫秒时间戳 → `2026-10-31 20:12`（UTC；账户列表只用来排序/辨认）。
+pub fn display_ms(ms: u64) -> String {
+    if ms == 0 {
+        return String::new();
+    }
+    let total_secs = ms / 1000;
+    let days = total_secs / 86_400;
+    let rem = total_secs % 86_400;
+    let (year, month, day) = civil_from_days(i64::try_from(days).unwrap_or(0));
+    format!(
+        "{year:04}-{month:02}-{day:02} {:02}:{:02}",
+        rem / 3_600,
+        (rem % 3_600) / 60
+    )
+}
+
+/// Howard Hinnant 的 `civil_from_days`（1970-01-01 为 0）。
+fn civil_from_days(days: i64) -> (i64, u32, u32) {
+    let z = days + 719_468;
+    let era = if z >= 0 { z } else { z - 146_096 } / 146_097;
+    let doe = z - era * 146_097;
+    let yoe = (doe - doe / 1_460 + doe / 36_524 - doe / 146_096) / 365;
+    let y = yoe + era * 400;
+    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
+    let mp = (5 * doy + 2) / 153;
+    let d = doy - (153 * mp + 2) / 5 + 1;
+    let m = if mp < 10 { mp + 3 } else { mp - 9 };
+    (if m <= 2 { y + 1 } else { y }, m as u32, d as u32)
+}
+
+/// 加一个离线账户。
+///
+/// # Errors
+///
+/// 名字不合法、同名冲突、落盘失败时返回 [`AccountFailure`]（带结构化码）。
+pub fn add_offline(env: &HostEnv, name: &str) -> Result<String, AccountFailure> {
+    let name = name.trim();
+    if !valid_offline_name(name) {
+        return Err(AccountFailure {
+            code: AccountNoticeCode::OfflineNameInvalid,
+            detail: format!("离线名字必须是 3–16 位字母/数字/下划线，收到 {name:?}"),
+        });
+    }
+    let meta = offline_meta(name, now_ms())
+        .map_err(|error| AccountFailure::classify(error, AccountNoticeCode::OfflineNameInvalid))?;
+    let display = meta.display_name().to_string();
+    let mut store = AccountStore::open(env.layout.auth_data());
+    store
+        .insert(meta, Credentials::Offline)
+        .map_err(|error| AccountFailure::classify(error, AccountNoticeCode::AccountExists))?;
+    store
+        .save()
+        .map_err(|error| AccountFailure::classify(error, AccountNoticeCode::StoreFailed))?;
+    Ok(display)
+}
+
+/// 删除账户（按 id 或名字）。
+///
+/// # Errors
+///
+/// 找不到、落盘失败时返回 [`AccountFailure`]。
+pub fn remove(env: &HostEnv, key: &str) -> Result<String, AccountFailure> {
+    let mut store = AccountStore::open(env.layout.auth_data());
+    let meta = store
+        .remove(key)
+        .map_err(|error| AccountFailure::classify(error, AccountNoticeCode::NotFound))?;
+    store
+        .save()
+        .map_err(|error| AccountFailure::classify(error, AccountNoticeCode::StoreFailed))?;
+    Ok(meta.display_name().to_string())
+}
+
+/// 微软登录任务句柄（取消标志 + 账户名回执；两条流共用）。
+#[derive(Debug, Clone, Default)]
+pub struct LoginJob {
+    /// 用户点了取消（线程收尾时据此丢弃结果）
+    pub cancelled: Arc<AtomicBool>,
+}
+
+impl LoginJob {
+    /// 新建一个未取消的句柄。
+    pub fn new() -> Self {
+        Self {
+            cancelled: Arc::new(AtomicBool::new(false)),
+        }
+    }
+
+    /// 取消。
+    pub fn cancel(&self) {
+        self.cancelled.store(true, Ordering::SeqCst);
+    }
+
+    /// 是否已取消。
+    pub fn is_cancelled(&self) -> bool {
+        self.cancelled.load(Ordering::SeqCst)
+    }
+}
+
+/// 起一次设备码登录（后台线程；`present` 时刻发 Waiting 事件）。
+pub fn start_login(env: HostEnv, tx: JobSender, job: LoginJob) {
+    spawn("msa-login", move || {
+        let auth = match microsoft_auth(&env) {
+            Ok(auth) => auth,
+            Err(message) => return fail(&tx, LoginFailure::Other, message),
+        };
+        let tx_prompt = tx.clone();
+        let result = block_on(auth.device_code_login(|prompt| {
+            let _ = tx_prompt.send(HostTask::Login(Box::new(DeviceLoginView::waiting(
+                &prompt.user_code,
+                &prompt.verification_uri,
+                prompt.expires_in.as_secs(),
+                &format!("{}#{}", prompt.verification_uri, prompt.user_code),
+            ))));
+        }));
+        finish(&env, &tx, &job, result);
+    });
+}
+
+/// 起一次授权码登录（后台线程：绑本地端口 → 拉起系统默认浏览器 → 等回调 → 换链）。
+///
+/// 与设备码流共用同一个 [`LoginJob`] 取消槽位、同一段账户入库逻辑，所以两条流的
+/// 凭据/刷新语义完全一致（`core` 侧也共用 [`unlucky_core::auth::MicrosoftSession`]）。
+pub fn start_browser_login(env: HostEnv, tx: JobSender, job: LoginJob) {
+    spawn("msa-authcode", move || {
+        let auth = match microsoft_auth(&env) {
+            Ok(auth) => auth,
+            Err(message) => return fail(&tx, LoginFailure::Other, message),
+        };
+        let tx_prompt = tx.clone();
+        let result = block_on(auth.authcode_login(|prompt| {
+            // 浏览器拉不起来不是致命错误：面板里还有可复制的授权链接。
+            let opened = opener::open_url(&prompt.authorization_url);
+            let _ = tx_prompt.send(HostTask::Login(Box::new(DeviceLoginView::browser_waiting(
+                &prompt.authorization_url,
+                prompt.timeout.as_secs(),
+                opened.err().as_deref(),
+            ))));
+        }));
+        finish(&env, &tx, &job, result);
+    });
+}
+
+/// 生产入口的 `MicrosoftAuth`：client id 取环境/构建期，失败日志落 `<数据根>/logs/`。
+fn microsoft_auth(env: &HostEnv) -> Result<MicrosoftAuth, String> {
+    MicrosoftAuth::from_env()
+        .map(|auth| {
+            auth.with_journal(Some(unlucky_core::auth::AuthJournal::in_logs_dir(
+                env.layout.logs(),
+            )))
+        })
+        .map_err(|error| error.to_string())
+}
+
+/// 失败收尾（带**原因码**）：原文进日志，页面据码出 i18n（复审 r1 P1-1）。
+fn fail(tx: &JobSender, failure: LoginFailure, detail: impl Into<String>) {
+    let detail = detail.into();
+    eprintln!("[auth] 微软登录失败（{}）：{detail}", failure.code());
+    let _ = tx.send(HostTask::Login(Box::new(DeviceLoginView::failed_as(
+        failure, detail,
+    ))));
+}
+
+/// 收尾：取消就吞掉结果；成功入库；失败带 core 的诊断文案（M38 的 403 也走这条）。
+fn finish(env: &HostEnv, tx: &JobSender, job: &LoginJob, result: AuthResult<MicrosoftSession>) {
+    if job.is_cancelled() {
+        let _ = tx.send(HostTask::Login(Box::default()));
+        return;
+    }
+    match result {
+        Ok(session) => match store_session(env, session) {
+            Ok(name) => {
+                let _ = tx.send(HostTask::Login(Box::new(DeviceLoginView::succeeded(&name))));
+                let _ = tx.send(HostTask::Accounts(accounts(env, None)));
+            }
+            Err(message) => fail(tx, LoginFailure::StoreFailed, message),
+        },
+        Err(error) => {
+            let failure = classify(&error);
+            fail(tx, failure, error.to_string());
+        }
+    }
+}
+
+/// 微软会话入库（元数据 + 凭据分文件，见 `core::auth::AccountStore`）。
+fn store_session(env: &HostEnv, session: MicrosoftSession) -> Result<String, String> {
+    let meta = unlucky_core::auth::account::AccountMeta::new(
+        unlucky_core::auth::account::AccountKind::Microsoft,
+        session.profile_id.clone(),
+        session.profile_name.clone(),
+        now_ms(),
+    );
+    let name = meta.display_name().to_string();
+    let mut store = AccountStore::open(env.layout.auth_data());
+    store
+        .insert(meta, Credentials::Microsoft(session))
+        .and_then(|()| store.save())
+        .map_err(|error| format!("账户入库失败：{error}"))?;
+    Ok(name)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use unlucky_core::auth::AuthError;
+
+    use super::failure::mentions_whitelist;
+
+    #[test]
+    fn time_display_matches_known_timestamps() {
+        assert_eq!(display_ms(0), "");
+        // 1_769_000_000_000 ms = 2026-01-21T12:53:20Z（取整到分钟）
+        assert_eq!(display_ms(1_769_000_000_000), "2026-01-21 12:53");
+    }
+
+    #[test]
+    fn offline_add_list_remove_round_trips() {
+        let dir = std::env::temp_dir().join(format!("ull-host-accounts-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        let env = HostEnv::at_root(&dir);
+        std::fs::create_dir_all(env.layout.auth_data()).expect("auth 目录");
+
+        let name = add_offline(&env, "Steve").expect("加账户");
+        assert_eq!(name, "Steve");
+        let list = accounts(&env, None);
+        assert_eq!(list.len(), 1);
+        assert_eq!(list[0].kind, AccountKind::Offline);
+        assert!(!list[0].active);
+
+        let active = accounts(&env, Some(list[0].id.as_str()));
+        assert!(active[0].active);
+
+        let removed = remove(&env, "Steve").expect("删账户");
+        assert_eq!(removed, "Steve");
+        assert!(accounts(&env, None).is_empty());
+        assert!(add_offline(&env, "  ").is_err());
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn failure_codes_are_classified_from_variants_not_chinese_text() {
+        assert_eq!(
+            classify(&AuthError::Network {
+                url: "https://x".to_string(),
+                detail: "dns".to_string()
+            }),
+            LoginFailure::Unreachable
+        );
+        assert_eq!(
+            classify(&AuthError::Denied {
+                code: "AADSTS7000218".to_string(),
+                description: "request body must contain client_assertion".to_string(),
+            }),
+            LoginFailure::NotWhitelisted
+        );
+        assert_eq!(
+            classify(&AuthError::Denied {
+                code: "invalid_grant".to_string(),
+                description: "bad".to_string(),
+            }),
+            LoginFailure::Denied
+        );
+        assert_eq!(classify(&AuthError::Canceled), LoginFailure::Other);
+        assert!(mentions_whitelist("AADSTS7000218"));
+        assert!(!mentions_whitelist("invalid_grant"));
+    }
+
+    #[test]
+    fn offline_name_rule_matches_the_ui_contract() {
+        assert!(valid_offline_name("Steve"));
+        assert!(valid_offline_name("a_1"));
+        assert!(!valid_offline_name("ab"), "太短");
+        assert!(!valid_offline_name("中文名字"), "非 ascii");
+        assert!(!valid_offline_name("has space"));
+        assert!(!valid_offline_name("x"));
+    }
+
+    #[test]
+    fn a_bad_offline_name_is_classified_not_stringified() {
+        let dir =
+            std::env::temp_dir().join(format!("ull-host-accounts-name-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        let env = HostEnv::at_root(&dir);
+        std::fs::create_dir_all(env.layout.auth_data()).expect("auth 目录");
+        let failure = add_offline(&env, "ab").expect_err("太短要报错");
+        assert_eq!(failure.code, AccountNoticeCode::OfflineNameInvalid);
+        assert!(!failure.detail.is_empty());
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn login_job_cancel_flag_is_shared() {
+        let job = LoginJob::new();
+        let clone = job.clone();
+        assert!(!clone.is_cancelled());
+        job.cancel();
+        assert!(clone.is_cancelled());
+    }
+}
diff --git a/crates/presenter/src/host/accounts/authlib.rs b/crates/presenter/src/host/accounts/authlib.rs
new file mode 100644
index 0000000..6f708b4
--- /dev/null
+++ b/crates/presenter/src/host/accounts/authlib.rs
@@ -0,0 +1,337 @@
+//! 第三方轨（authlib-injector）：服务发现校验、密码登录、皮肤原图抓取。
+//!
+//! 全部跑在后台线程里（网络），出口只有 [`AuthlibLoginView`] / [`SkinImage`]——
+//! 密码与 accessToken 在调用栈里就地丢弃，永不进 DTO 回程（M114 凭据红线）。
+//!
+//! ## 三条流的坐标
+//!
+//! | 动作 | 端点 | 产出 |
+//! |---|---|---|
+//! | 服务发现（「校验」按钮） | `GET {apiRoot}` | 服务器名 / skinDomains（`meta` 缺失即判「不是认证服务器」） |
+//! | 登录 | `POST {apiRoot}authserver/authenticate` | `AuthlibSession`（入库，不外传） |
+//! | 皮肤 | `GET {apiRoot}sessionserver/session/minecraft/profile/{uuid}` → textures → 皮肤 URL | 皮肤 PNG 原图 |
+//!
+//! `core::download::http::build_client` 是唯一的 HTTP 基座（复用下载器的客户端配置），
+//! 所以本 crate **不新增任何依赖**（`presenter-no-ui` 与依赖最小化同时成立）。
+
+use unlucky_core::auth::account::{AccountKind as CoreAccountKind, AccountMeta, Credentials};
+use unlucky_core::auth::authlib::{
+    normalize_api_root, AuthlibAuth, AuthlibServerMeta, AuthlibSession,
+};
+use unlucky_core::auth::microsoft::now_ms;
+use unlucky_core::auth::{AccountStore, Secret};
+use unlucky_core::download::blocking::block_on;
+
+use crate::dto::{AuthlibLoginView, AuthlibRequest, LoginFailure, SkinImage};
+
+mod util;
+
+pub use util::scrub_known;
+
+use util::{base64_decode, client_token, get_bytes, get_text};
+
+use super::super::env::HostEnv;
+use super::super::job::{spawn, HostTask, JobSender};
+use super::LoginJob;
+
+/// 校验认证服务器地址（「校验」按钮的后端）。
+///
+/// # Errors
+///
+/// 地址不合法、网络不可达、HTTP 非 2xx、响应不是 authlib-injector 的服务发现 JSON 时，
+/// 返回**具名**的用户可读文案（这是任务要求的「失败态 + 具名错误」）。
+pub fn probe_authlib(env: &HostEnv, input: &str) -> Result<(String, AuthlibServerMeta), Failure> {
+    let api_root = normalize_api_root(input)
+        .map_err(|error| Failure::new(LoginFailure::Other, error.to_string()))?;
+    let (status, text) =
+        get_text(env, &api_root).map_err(|error| Failure::new(LoginFailure::Unreachable, error))?;
+    if !(200..300).contains(&status) {
+        return Err(Failure::new(
+            LoginFailure::NotAuthlibServer,
+            format!("服务器返回 HTTP {status}（{api_root} 不像可用的 authlib 认证服务器）"),
+        ));
+    }
+    let value: serde_json::Value = serde_json::from_str(&text).map_err(|_| {
+        Failure::new(
+            LoginFailure::NotAuthlibServer,
+            format!("响应不是 JSON：{api_root} —— 可能填成了网页地址，而不是 API 根（通常以 /api/yggdrasil/ 结尾）"),
+        )
+    })?;
+    if value.get("meta").is_none() && value.get("skinDomains").is_none() {
+        return Err(Failure::new(
+            LoginFailure::NotAuthlibServer,
+            "响应里没有 meta / skinDomains：这看起来不是 authlib-injector 服务器",
+        ));
+    }
+    let meta = AuthlibServerMeta::from_value(&value);
+    Ok((api_root, meta))
+}
+
+/// 第三方轨的失败：**原因码 + 原文**（原文进日志，页面据码出 i18n）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Failure {
+    /// 原因码
+    pub code: LoginFailure,
+    /// 原始诊断（已脱敏）
+    pub detail: String,
+}
+
+impl Failure {
+    fn new(code: LoginFailure, detail: impl Into<String>) -> Self {
+        Self {
+            code,
+            detail: detail.into(),
+        }
+    }
+
+    /// `AuthError` → 原因码（只看变体）。
+    fn from_error(error: &unlucky_core::auth::AuthError) -> Self {
+        use unlucky_core::auth::AuthError;
+        let code = match error {
+            AuthError::Network { .. } | AuthError::Timeout { .. } => LoginFailure::Unreachable,
+            AuthError::Denied { .. } => LoginFailure::BadCredentials,
+            AuthError::Store { .. } => LoginFailure::StoreFailed,
+            _ => LoginFailure::Other,
+        };
+        Self::new(code, error.to_string())
+    }
+}
+
+/// 起一次第三方轨登录（后台线程）。
+pub fn start_login(env: HostEnv, tx: JobSender, job: LoginJob, request: AuthlibRequest) {
+    spawn("authlib-login", move || {
+        let mut request = request;
+        // 日志只打脱敏形态；密码在下面用完立刻丢弃。
+        eprintln!("[auth] authlib 登录开始（{}）", request.redacted());
+        stage(&tx, &request.server, "正在校验服务器地址…");
+
+        let (api_root, meta) = match probe_authlib(&env, &request.server) {
+            Ok(found) => found,
+            Err(failure) => return fail(&tx, failure),
+        };
+        let server_name = meta
+            .name
+            .clone()
+            .filter(|name| !name.trim().is_empty())
+            .unwrap_or_else(|| api_root.clone());
+        stage(
+            &tx,
+            &api_root,
+            &format!("服务器 {server_name} 可用，正在登录…"),
+        );
+
+        let auth = match AuthlibAuth::new() {
+            Ok(auth) => auth,
+            Err(error) => return fail(&tx, Failure::new(LoginFailure::Other, error.to_string())),
+        };
+        let client_token = Secret::new(client_token());
+        let password_text = std::mem::take(&mut request.password);
+        let password = Secret::new(password_text.clone());
+        let login_name = request.login.clone();
+        let result = block_on(auth.authenticate(&api_root, &login_name, &password, &client_token));
+        drop(password);
+
+        if job.is_cancelled() {
+            let _ = tx.send(HostTask::Authlib(Box::default()));
+            return;
+        }
+        match result {
+            Ok(session) => match store(&env, session, &api_root, &login_name) {
+                Ok(account) => {
+                    let _ = tx.send(HostTask::Authlib(Box::new(AuthlibLoginView::succeeded(
+                        &server_name,
+                        &account,
+                    ))));
+                    let _ = tx.send(HostTask::Accounts(super::accounts(
+                        &env,
+                        Some(account.as_str()),
+                    )));
+                }
+                Err(failure) => fail(&tx, failure),
+            },
+            // 错误原文里可能有服务端回显的凭据：先按**形状**脱敏（`AuthlibLoginView::failed`），
+            // 再按**已知值**兜一遍（万一服务端把密码原样回显）。
+            Err(error) => {
+                let failure = Failure::from_error(&error);
+                fail(
+                    &tx,
+                    Failure::new(failure.code, scrub_known(&failure.detail, &password_text)),
+                );
+            }
+        }
+        drop(password_text);
+    });
+}
+
+/// 只校验服务器地址（「校验服务器」按钮）；结果走同一条 `AuthlibLoginChanged`。
+pub fn spawn_probe(env: HostEnv, tx: JobSender, server: String) {
+    spawn("authlib-probe", move || {
+        stage(&tx, &server, "正在校验服务器地址…");
+        match probe_authlib(&env, &server) {
+            Ok((api_root, meta)) => {
+                let name = meta
+                    .name
+                    .as_deref()
+                    .map(str::trim)
+                    .filter(|name| !name.is_empty())
+                    .map_or_else(|| api_root.clone(), str::to_string);
+                let _ = tx.send(HostTask::Authlib(Box::new(AuthlibLoginView::reachable(
+                    &api_root, &name,
+                ))));
+            }
+            Err(failure) => fail(&tx, failure),
+        }
+    });
+}
+
+/// 抓第三方轨账户的皮肤原图（`profile_id` → textures → 皮肤 URL → PNG 字节）。
+///
+/// # Errors
+///
+/// 服务器不可达、响应缺 textures、纹理不是 PNG 时返回原因（调用方按「没有皮肤」处理）。
+pub fn fetch_skin(env: &HostEnv, api_root: &str, profile_id: &str) -> Result<SkinImage, String> {
+    let base = normalize_api_root(api_root).map_err(|error| error.to_string())?;
+    let url = format!("{base}sessionserver/session/minecraft/profile/{profile_id}");
+    let (status, text) = get_text(env, &url)?;
+    if !(200..300).contains(&status) {
+        return Err(format!("皮肤接口返回 HTTP {status}"));
+    }
+    let value: serde_json::Value =
+        serde_json::from_str(&text).map_err(|error| format!("皮肤接口响应不是 JSON：{error}"))?;
+    let encoded = value
+        .get("properties")
+        .and_then(|properties| properties.as_array())
+        .and_then(|properties| {
+            properties
+                .iter()
+                .find(|entry| entry.get("name").and_then(|name| name.as_str()) == Some("textures"))
+        })
+        .and_then(|entry| entry.get("value"))
+        .and_then(|value| value.as_str())
+        .ok_or_else(|| "档案里没有 textures 属性".to_string())?;
+    let raw = base64_decode(encoded)?;
+    let textures: serde_json::Value =
+        serde_json::from_slice(&raw).map_err(|error| format!("textures 属性解不开：{error}"))?;
+    let skin_url = textures
+        .get("textures")
+        .and_then(|textures| textures.get("SKIN"))
+        .and_then(|skin| skin.get("url"))
+        .and_then(|url| url.as_str())
+        .ok_or_else(|| "textures 里没有 SKIN 条目".to_string())?;
+    let (status, bytes) = get_bytes(env, skin_url)?;
+    if !(200..300).contains(&status) {
+        return Err(format!("皮肤图片返回 HTTP {status}"));
+    }
+    if !bytes.starts_with(b"\x89PNG") {
+        return Err("皮肤图片不是 PNG".to_string());
+    }
+    Ok(SkinImage {
+        png: bytes,
+        source: skin_url.to_string(),
+    })
+}
+
+/// 入库（元数据 + 凭据分文件）；返回展示名。
+fn store(
+    env: &HostEnv,
+    session: AuthlibSession,
+    api_root: &str,
+    login_name: &str,
+) -> Result<String, Failure> {
+    let profile = session
+        .selected_profile
+        .clone()
+        .filter(|profile| !profile.name.trim().is_empty() && !profile.id.is_empty())
+        .ok_or_else(|| Failure::new(LoginFailure::NoProfile, "服务器没有返回角色"))?;
+    let mut meta = AccountMeta::new(
+        CoreAccountKind::AuthlibInjector,
+        profile.id,
+        profile.name,
+        now_ms(),
+    );
+    meta.login_name = Some(login_name.to_string());
+    meta.server_url = Some(api_root.to_string());
+    let name = meta.display_name().to_string();
+    let mut account_store = AccountStore::open(env.layout.auth_data());
+    account_store
+        .insert(meta, Credentials::AuthlibInjector(session))
+        .and_then(|()| account_store.save())
+        .map_err(|error| Failure::new(LoginFailure::StoreFailed, error.to_string()))?;
+    Ok(name)
+}
+
+/// 发一条「进行中」状态（UI 据此只转圈不误报）。
+fn stage(tx: &JobSender, server: &str, message: &str) {
+    let _ = tx.send(HostTask::Authlib(Box::new(AuthlibLoginView::running(
+        server, message,
+    ))));
+}
+
+/// 失败收尾：**先脱敏再上屏**（服务端错误原文里可能带 token）。
+/// 失败收尾：原文进日志，页面拿**原因码**（复审 r1 P1-1）。
+fn fail(tx: &JobSender, failure: Failure) {
+    eprintln!(
+        "[auth] authlib 失败（{}）：{}",
+        failure.code.code(),
+        failure.detail
+    );
+    let _ = tx.send(HostTask::Authlib(Box::new(AuthlibLoginView::failed_as(
+        failure.code,
+        failure.detail,
+    ))));
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn base64_decodes_textures_payload() {
+        // `{"textures":{}}` 的 base64
+        let encoded = "eyJ0ZXh0dXJlcyI6e319";
+        assert_eq!(base64_decode(encoded).expect("解码"), br#"{"textures":{}}"#);
+        // URL-safe 变体 + 填充 + 换行都要吃
+        assert_eq!(
+            base64_decode("eyJ0ZXh0dXJlcyI6e319\n").expect("解码"),
+            br#"{"textures":{}}"#
+        );
+        assert!(base64_decode("!!!").is_err());
+        assert!(base64_decode("").is_err());
+    }
+
+    #[test]
+    fn client_token_is_stable_length_and_unique() {
+        let a = client_token();
+        let b = client_token();
+        assert_eq!(a.len(), 32);
+        assert_ne!(
+            a, b,
+            "两次生成的 clientToken 不能相同（会被服务端当成重放）"
+        );
+        assert!(a.chars().all(|c| c.is_ascii_hexdigit()));
+    }
+
+    use crate::dto::REDACTED;
+
+    #[test]
+    fn known_secret_is_scrubbed_from_error_text() {
+        let text = scrub_known("登录失败：hunter2 被拒绝", "hunter2");
+        assert!(!text.contains("hunter2"), "{text}");
+        assert!(text.contains(REDACTED));
+        assert_eq!(scrub_known("普通错误", ""), "普通错误");
+    }
+
+    #[test]
+    fn a_web_page_address_is_rejected_with_a_named_error() {
+        // 不发网络请求：只测「规范化 + 空输入」这条不联网的分支
+        let dir = std::env::temp_dir().join(format!("ull-authlib-probe-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        let env = HostEnv::at_root(&dir);
+        std::fs::create_dir_all(env.layout.cache()).expect("cache");
+        let failure = probe_authlib(&env, "   ").expect_err("空地址必须报错");
+        assert!(failure.detail.contains("不能为空"), "{failure:?}");
+        let failure = probe_authlib(&env, "https://").expect_err("只给协议头也必须报错");
+        assert!(!failure.detail.is_empty());
+        std::fs::remove_dir_all(&dir).ok();
+    }
+}
diff --git a/crates/presenter/src/host/accounts/authlib/util.rs b/crates/presenter/src/host/accounts/authlib/util.rs
new file mode 100644
index 0000000..fdba67d
--- /dev/null
+++ b/crates/presenter/src/host/accounts/authlib/util.rs
@@ -0,0 +1,129 @@
+//! authlib 轨的 HTTP 基座与纯函数小工具：`clientToken` 生成、GET 文本/字节、base64 解码、按已知值脱敏。
+//!
+//! 从 `authlib.rs` 拆出来守 400 行硬线。网络只走**既有下载引擎**的客户端
+//! （`host::engine::engine(env).client()`）：代理/超时/证书栈与下载器同源，本 crate 不新增依赖。
+
+use unlucky_core::auth::microsoft::now_ms;
+use unlucky_core::download::blocking::block_on;
+
+use crate::dto::REDACTED;
+
+use super::super::super::engine;
+use super::super::super::env::HostEnv;
+
+/// 一次 GET 的超时上限（秒）：服务器不可达时要能失败，而不是挂住 UI 的登录面板。
+pub(super) const HTTP_TIMEOUT_SECS: u64 = 15;
+
+/// 单次 GET 的响应体上限（字节）：用户能填任意 URL，服务发现 JSON/皮肤 PNG 都远小于它。
+pub(super) const MAX_BODY_BYTES: usize = 512 * 1024;
+/// base64 解码输出上限（textures 属性是个小 JSON）。
+pub(super) const MAX_BASE64_BYTES: usize = 64 * 1024;
+
+/// 启动器侧生成的 `clientToken`（Yggdrasil 要求刷新/校验都带，且服务端回传必须一致）。
+pub(super) fn client_token() -> String {
+    use std::hash::{BuildHasher, Hasher};
+    let mut out = String::with_capacity(32);
+    for salt in 0..2u64 {
+        // `RandomState` 每个实例自带随机种子（标准库给的是进程级随机），不引第三方随机库。
+        let mut hasher = std::collections::hash_map::RandomState::new().build_hasher();
+        hasher.write_u64(now_ms() ^ salt);
+        hasher.write_u32(std::process::id());
+        out.push_str(&format!("{:016x}", hasher.finish()));
+    }
+    out
+}
+
+/// GET 文本（状态码 + 正文）。
+///
+/// 客户端来自**既有的下载引擎**（`host::engine::engine`）：代理/超时/证书栈与本仓的下载器
+/// 完全同源，不在这里另起一套 HTTP 配置（本 crate 也没有 reqwest 依赖，拿到的只是它的 `&Client`）。
+pub(super) fn get_text(env: &HostEnv, url: &str) -> Result<(u16, String), String> {
+    let engine = engine::engine(env);
+    let client = engine.client();
+    let url = url.to_string();
+    block_on(async move {
+        let reply = client
+            .get(&url)
+            .timeout(std::time::Duration::from_secs(HTTP_TIMEOUT_SECS))
+            .send()
+            .await
+            .map_err(|error| format!("服务器不可达：{error}"))?;
+        let status = reply.status().as_u16();
+        let text = reply
+            .text()
+            .await
+            .map_err(|error| format!("读取响应失败：{error}"))?;
+        Ok((status, text))
+    })
+}
+
+/// GET 字节（皮肤图片）。
+pub(super) fn get_bytes(env: &HostEnv, url: &str) -> Result<(u16, Vec<u8>), String> {
+    let engine = engine::engine(env);
+    let client = engine.client();
+    let url = url.to_string();
+    block_on(async move {
+        let reply = client
+            .get(&url)
+            .timeout(std::time::Duration::from_secs(HTTP_TIMEOUT_SECS))
+            .send()
+            .await
+            .map_err(|error| format!("皮肤图片不可达：{error}"))?;
+        let status = reply.status().as_u16();
+        let bytes = reply
+            .bytes()
+            .await
+            .map_err(|error| format!("读取皮肤图片失败：{error}"))?
+            .to_vec();
+        if bytes.len() > MAX_BODY_BYTES {
+            return Err(format!(
+                "图片过大（{} 字节，上限 {MAX_BODY_BYTES}）",
+                bytes.len()
+            ));
+        }
+        Ok((status, bytes))
+    })
+}
+
+/// base64 解码（标准字母表，容忍 URL-safe 变体与缺失填充）。
+///
+/// 为什么自己写：textures 属性是 base64 编码的 JSON，而本 crate 不能引第三方解码库
+/// （依赖最小化）；这段是 40 行的确定性算法，配单测比拖一个依赖更划算。
+pub(super) fn base64_decode(input: &str) -> Result<Vec<u8>, String> {
+    let mut out = Vec::with_capacity(input.len() / 4 * 3);
+    let mut buffer: u32 = 0;
+    let mut bits = 0u32;
+    for byte in input.bytes() {
+        let value = match byte {
+            b'A'..=b'Z' => byte - b'A',
+            b'a'..=b'z' => byte - b'a' + 26,
+            b'0'..=b'9' => byte - b'0' + 52,
+            b'+' | b'-' => 62,
+            b'/' | b'_' => 63,
+            b'=' | b'\n' | b'\r' | b' ' => continue,
+            other => return Err(format!("base64 里有非法字符：{:?}", other as char)),
+        };
+        buffer = (buffer << 6) | u32::from(value);
+        bits += 6;
+        if bits >= 8 {
+            bits -= 8;
+            out.push(u8::try_from((buffer >> bits) & 0xFF).unwrap_or(0));
+        }
+        if out.len() > MAX_BASE64_BYTES {
+            return Err(format!("base64 输出超过上限 {MAX_BASE64_BYTES} 字节"));
+        }
+    }
+    if out.is_empty() {
+        return Err("base64 内容为空".to_string());
+    }
+    Ok(out)
+}
+
+/// 错误文案里可能混进已知凭据值：按值再兜一遍（形状脱敏由 `AuthlibLoginView::failed` 做）。
+#[must_use]
+pub fn scrub_known(message: &str, secret: &str) -> String {
+    if secret.is_empty() {
+        return message.to_string();
+    }
+    message.replace(secret, REDACTED)
+}
diff --git a/crates/presenter/src/host/accounts/failure.rs b/crates/presenter/src/host/accounts/failure.rs
new file mode 100644
index 0000000..b04833e
--- /dev/null
+++ b/crates/presenter/src/host/accounts/failure.rs
@@ -0,0 +1,126 @@
+//! 账户写操作的失败分类 + 离线名字契约（M114 r2）。
+//!
+//! 分类**只看 `AuthError` 的变体与 ascii 码**，不看中文文案——文案随时会改，
+//! 而页面据 `AccountNoticeCode` 选 i18n，两边必须能独立演进。
+
+use unlucky_core::auth::AuthError;
+
+use unlucky_core::auth::BodyKind;
+
+use crate::dto::{AccountNoticeCode, LoginFailure};
+
+/// 账户写操作的失败：**结构化码 + 原文**（原文只进日志/详细信息，不上屏）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountFailure {
+    /// 结果码（页面据此选 i18n）
+    pub code: AccountNoticeCode,
+    /// 原始诊断（已脱敏）
+    pub detail: String,
+}
+
+impl AccountFailure {
+    /// 按 core 的错误类型分类（不看中文文案，只看变体）。
+    pub(super) fn classify(error: AuthError, fallback: AccountNoticeCode) -> Self {
+        let code = match &error {
+            unlucky_core::auth::AuthError::Conflict { .. } => AccountNoticeCode::AccountExists,
+            unlucky_core::auth::AuthError::NotFound { .. } => AccountNoticeCode::NotFound,
+            unlucky_core::auth::AuthError::Malformed(_) => AccountNoticeCode::OfflineNameInvalid,
+            unlucky_core::auth::AuthError::Store { .. } => AccountNoticeCode::StoreFailed,
+            _ => fallback,
+        };
+        Self {
+            code,
+            detail: error.to_string(),
+        }
+    }
+}
+
+/// `AuthError` → 原因码（**只看变体与 ascii 码，不看中文文案**）。
+pub(super) fn classify(error: &AuthError) -> LoginFailure {
+    match error {
+        AuthError::Network { .. } | AuthError::Timeout { .. } => LoginFailure::Unreachable,
+        AuthError::Denied { code, description } => {
+            if mentions_whitelist(code) || mentions_whitelist(description) {
+                LoginFailure::NotWhitelisted
+            } else {
+                LoginFailure::Denied
+            }
+        }
+        // 只看 `ResponseDetail` 的**结构化字段**（status / kind / server_message），
+        // 不把整条错误 Debug 成字符串再去扫——那会把中文 `what`/`digest` 也算进判据里。
+        AuthError::Response(detail) => {
+            let server = detail.server_message.as_deref().unwrap_or_default();
+            let digest = detail.digest.as_str();
+            if mentions_whitelist(server) || mentions_whitelist(digest) {
+                LoginFailure::NotWhitelisted
+            } else if detail.status >= 500 || matches!(detail.kind, BodyKind::Html | BodyKind::Text)
+            {
+                // 5xx / 拦截页：服务器或链路出了问题，不是「它拒绝了你」。
+                LoginFailure::Unreachable
+            } else {
+                LoginFailure::Denied
+            }
+        }
+        AuthError::Xbox { .. } | AuthError::CredentialExpired => LoginFailure::Denied,
+        AuthError::Store { .. } => LoginFailure::StoreFailed,
+        _ => LoginFailure::Other,
+    }
+}
+
+/// 是否属于「应用注册未获批」这一类（AADSTS7000218 / consent required / whitelist）。
+pub(super) fn mentions_whitelist(text: &str) -> bool {
+    let lowered = text.to_lowercase();
+    lowered.contains("aadsts7000218")
+        || lowered.contains("aadsts65001")
+        || lowered.contains("consent")
+        || lowered.contains("whitelist")
+        || lowered.contains("not approved")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use unlucky_core::auth::body::ResponseDetail;
+
+    fn response(status: u16, kind: BodyKind, server_message: Option<&str>) -> AuthError {
+        AuthError::Response(Box::new(ResponseDetail {
+            step: "xsts".to_string(),
+            what: "XSTS 授权".to_string(),
+            status,
+            content_type: None,
+            kind,
+            server_message: server_message.map(str::to_string),
+            digest: "digest".to_string(),
+        }))
+    }
+
+    /// 403 带 AADSTS 码 → 白名单未批；403 不带 → 一般性拒绝。
+    #[test]
+    fn aadsts_markers_win_over_the_generic_denial() {
+        assert_eq!(
+            classify(&response(
+                403,
+                BodyKind::Json,
+                Some("AADSTS7000218: app not approved")
+            )),
+            LoginFailure::NotWhitelisted
+        );
+        assert_eq!(
+            classify(&response(403, BodyKind::Json, Some("invalid_grant"))),
+            LoginFailure::Denied
+        );
+    }
+
+    /// 5xx 与「拦截页」（HTML/纯文本）归「连不上」，不是「服务器拒绝了你」。
+    #[test]
+    fn upstream_failures_and_intercept_pages_are_unreachable() {
+        assert_eq!(
+            classify(&response(503, BodyKind::Json, None)),
+            LoginFailure::Unreachable
+        );
+        assert_eq!(
+            classify(&response(200, BodyKind::Html, None)),
+            LoginFailure::Unreachable
+        );
+    }
+}
diff --git a/crates/presenter/src/host/accounts/refresh.rs b/crates/presenter/src/host/accounts/refresh.rs
new file mode 100644
index 0000000..cb805d6
--- /dev/null
+++ b/crates/presenter/src/host/accounts/refresh.rs
@@ -0,0 +1,66 @@
+//! 账户列表的刷新与皮肤抓取（`impl CoreHost` 的这一段，从 `host/mod.rs` 拆出来守 400 行）。
+//!
+//! 为什么在这里：`host/mod.rs` 在 M109/M113 之后已经贴着 400 行硬线，而这三段是**账户专属**
+//! 的编排（读账户库 → 盖皮肤 → 起抓取线程）。放回 `host/accounts.rs` 也不行——那个文件同样
+//! 380 行。归属仍是 accounts（`mod accounts { mod refresh; }`），只是按功能再分一层。
+
+use crate::dto::{AccountKind, CoreEvent};
+
+use super::super::{accounts, job, CoreHost, HostTask};
+
+impl CoreHost {
+    pub(in crate::host) fn refresh_accounts(&mut self) {
+        self.accounts = accounts::accounts(&self.env, self.active_account.as_deref());
+        if self.active_account.is_none() {
+            // 默认选中第一个账户（没有账户时保持 None = 离线占位）
+            self.active_account = self.accounts.first().map(|account| account.id.clone());
+            self.accounts = accounts::accounts(&self.env, self.active_account.as_deref());
+        }
+        self.attach_skins();
+        self.request_skins();
+        self.send(CoreEvent::AccountsChanged(self.accounts.clone()));
+    }
+
+    /// 把已抓到的皮肤盖到账户视图上。
+    ///
+    /// 只盖第三方轨：离线档案没有皮肤，微软轨不做真头像（M114 口径）——
+    /// 「没有皮肤就画首字母块」，绝不给假皮肤/白块。
+    pub(in crate::host) fn attach_skins(&mut self) {
+        for account in &mut self.accounts {
+            if account.kind != AccountKind::Authlib {
+                account.skin = None;
+                continue;
+            }
+            if let Some(skin) = self.skins.get(&account.id) {
+                account.skin = skin.clone();
+            }
+        }
+    }
+
+    /// 给还没抓过皮肤的第三方轨账户起后台抓取（每个账户只抓一次）。
+    ///
+    /// 抓不到就记 `None`：错误在面板上不显示（皮肤是装饰，不是业务失败），但也不会重试刷屏。
+    fn request_skins(&mut self) {
+        let mut pending = Vec::new();
+        for account in &self.accounts {
+            if account.kind != AccountKind::Authlib || account.server_url.trim().is_empty() {
+                continue;
+            }
+            if self.skin_requested.insert(account.id.clone()) {
+                pending.push((
+                    account.id.clone(),
+                    account.server_url.clone(),
+                    account.profile_id.clone(),
+                ));
+            }
+        }
+        for (id, server, profile) in pending {
+            let tx = self.tx.clone();
+            let env = self.env.clone();
+            job::spawn("account-skin", move || {
+                let skin = accounts::fetch_skin(&env, &server, &profile).ok();
+                let _ = tx.send(HostTask::Avatar { id, skin });
+            });
+        }
+    }
+}
diff --git a/crates/presenter/src/host/addon.rs b/crates/presenter/src/host/addon.rs
new file mode 100644
index 0000000..37e3b58
--- /dev/null
+++ b/crates/presenter/src/host/addon.rs
@@ -0,0 +1,106 @@
+//! 内容库的宿主实现（M109 `CONTENTDL`）：**检索** + **装进指定实例**。
+//!
+//! ## 为什么这些代码在 presenter 而不是 core（临时落点，必须写清）
+//!
+//! `crates/core` 的 `addon` 模块今天只有两件事：加载器安装（`addon::loader`）与整合包**格式**
+//! 解析（`addon::pack`，M110）。它**没有** CurseForge / Modrinth 的 API 客户端，也没有
+//! 「远程整合包一键装进实例」的管线（M111/M112 才做）。而任务书的硬约束是「UI 层不许自己发
+//! HTTP，新增能力一律经 presenter 的 host 转发」——所以本轮把客户端放在这里。
+//!
+//! **长期应下沉到 `core::addon`**（已报 finding）：那时本模块只剩「DTO ↔ 领域类型」的翻译，
+//! 与 `host/versions.rs` 现在的角色一样。
+//!
+//! ## 三条纪律
+//!
+//! | 纪律 | 落点 |
+//! |---|---|
+//! | 网络只在后台线程 | [`spawn_search`] / [`spawn_install`] 走 `job::spawn`，UI 线程只收事件 |
+//! | Modrinth 走 core 的下载引擎 | `addon/http.rs` 的 `download_bytes` 路径带**信号量限流 + 源健康度 + 指数退避**，不另写重试循环 |
+//! | 密钥不进仓库 / 日志 | CF 的 `X-API-KEY` 只从 `ULL_CF_API_KEY` 读，日志只打 `set`/`unset`，DTO 里只有一个 `bool` |
+//!
+//! ## 模块
+//!
+//! | 文件 | 职责 |
+//! |---|---|
+//! | [`sources`] | 两个站点的 JSON 方言 → [`crate::dto::ContentHit`] |
+//! | `http` | 取文本：无 header 走引擎、带 header 走 client + 退避、百分号编码 |
+//! | `install` | 一键装入：解析文件 → 下载到实例目录 → 进度回流 |
+//!
+//! ## 整合包与 CF 的边界（都写进报告）
+//!
+//! - 整合包**不做**「一键装入」：`ContentKind::Modpack.dir()` 是 `None`，UI 侧按钮禁用带原因，
+//!   host 侧再挡一次（就算绕过 UI 发指令也只回一条 `Failed`）。真流程是 M111 的导入管线。
+//! - CurseForge 本轮只做**检索**（需要用户配 `ULL_CF_API_KEY`），文件解析未接通。
+
+mod http;
+mod install;
+// M113: import/export —— 整合包导入/导出（拆成子目录：父文件只留既有内容 + mod）
+mod pack;
+mod sources;
+
+pub(super) use pack::{cancel_pack, pack_epoch};
+
+#[cfg(test)]
+mod tests;
+
+use std::sync::atomic::AtomicBool;
+use std::sync::Arc;
+
+use crate::dto::{ContentQuery, ContentResults};
+
+use super::env::HostEnv;
+use super::job::{spawn, HostTask, JobSender};
+
+/// 日志里只出现这两种状态，**永远不打密钥本身**。
+const KEY_UNSET: &str = "ULL_CF_API_KEY unset（CurseForge 源不可用）";
+const KEY_SET: &str = "ULL_CF_API_KEY set（CurseForge 源可用）";
+
+/// CurseForge 的密钥（环境变量；空串 / 空白按「没配」处理）。
+///
+/// 为什么不放设置项：core 的 `setting` schema 不在本 mission 的 scope（已登记 finding）。
+/// 环境变量这条路至少满足「不进仓库、不进日志」两条硬要求。
+fn curseforge_key() -> Option<String> {
+    std::env::var("ULL_CF_API_KEY")
+        .ok()
+        .map(|key| key.trim().to_string())
+        .filter(|key| !key.is_empty())
+}
+
+/// CF 源此刻可用吗（页面据此禁用那条来源）。
+#[must_use]
+pub fn curseforge_ready() -> bool {
+    curseforge_key().is_some()
+}
+
+/// 打一行「配没配」的日志（**不含**密钥内容；host 装配时调一次）。
+pub fn log_curseforge_state() {
+    eprintln!(
+        "[content] {}",
+        if curseforge_ready() {
+            KEY_SET
+        } else {
+            KEY_UNSET
+        }
+    );
+}
+
+/// 后台检索（网络在后台线程，UI 不卡）。
+pub fn spawn_search(env: HostEnv, tx: JobSender, query: ContentQuery) {
+    spawn("content", move || {
+        let result: Result<ContentResults, String> = sources::search(&env, &query);
+        let _ = tx.send(HostTask::Content(Box::new(result)));
+    });
+}
+
+/// 后台「装进指定实例」。
+pub fn spawn_install(
+    env: HostEnv,
+    tx: JobSender,
+    request: crate::dto::ContentInstallRequest,
+    cancel: Arc<AtomicBool>,
+    epoch: u64,
+) {
+    spawn("content-install", move || {
+        install::install(&env, &tx, &request, &cancel, epoch);
+    });
+}
diff --git a/crates/presenter/src/host/addon/http.rs b/crates/presenter/src/host/addon/http.rs
new file mode 100644
index 0000000..07d73ec
--- /dev/null
+++ b/crates/presenter/src/host/addon/http.rs
@@ -0,0 +1,123 @@
+//! HTTP 取文本（内容库唯一的网络出口）。
+//!
+//! ## 两条路径，为什么不是一条
+//!
+//! | 请求 | 走哪 | 拿到什么 |
+//! |---|---|---|
+//! | 无自定义 header（Modrinth 的全部请求） | [`DownloadEngine::download_bytes`] | **信号量限流 + 源健康度 + 指数退避 + 分类错误**，全是 core 现成的 |
+//! | 带 header（只有 CurseForge 的 `X-API-KEY`） | `engine.client()` 直发 | 引擎的请求体没有 header 字段，只能自己发；代价是这条路径自己带一个 429/5xx 退避 |
+//!
+//! ## 密钥纪律
+//!
+//! 带 header 的那条路径**只把 header 值喂给请求**：不进日志、不进错误串。错误串里只有 URL
+//! （CF 的 URL 不含密钥）与状态码。
+
+use std::time::Duration;
+
+use unlucky_core::download::blocking::block_on;
+use unlucky_core::download::{DownloadRequest, ResourceKind};
+
+use super::super::env::HostEnv;
+
+/// 站点要求的 User-Agent（Modrinth 明文要求带联系方式，否则限流）。
+pub(super) const USER_AGENT: &str =
+    "Unlucky-Launcher/0.1 (+https://github.com/AskaEth/Unlucky-Launcher)";
+
+/// 最多重试次数（含首次）。
+const ATTEMPTS: u32 = 3;
+
+/// 取一段文本（JSON 原文）。
+pub(super) fn get(env: &HostEnv, url: &str, headers: &[(&str, &str)]) -> Result<String, String> {
+    if headers.is_empty() {
+        get_via_engine(env, url)
+    } else {
+        get_with_headers(env, url, headers)
+    }
+}
+
+/// core 的下载引擎：限流与退避都在里面，这里只负责「URL → 文本」。
+fn get_via_engine(env: &HostEnv, url: &str) -> Result<String, String> {
+    let engine = super::super::engine::engine(env);
+    let dir = env.layout.cache().join("content");
+    std::fs::create_dir_all(&dir).map_err(|error| format!("建缓存目录失败：{error}"))?;
+    let request = DownloadRequest::new(ResourceKind::Other, url, dir.join("response.json"));
+    let bytes = block_on(engine.download_bytes(request))
+        .map_err(|error| format!("请求 {url} 失败：{error}"))?;
+    String::from_utf8(bytes).map_err(|error| format!("响应不是 UTF-8：{error}"))
+}
+
+/// 带 header 的请求（只有 CF 走这条）：429 / 5xx / 连接类失败按退避重试。
+fn get_with_headers(env: &HostEnv, url: &str, headers: &[(&str, &str)]) -> Result<String, String> {
+    let engine = super::super::engine::engine(env);
+    let owned: Vec<(String, String)> = headers
+        .iter()
+        .map(|(name, value)| ((*name).to_string(), (*value).to_string()))
+        .collect();
+
+    for attempt in 0..ATTEMPTS {
+        let result = block_on(async {
+            let mut builder = engine.client().get(url).header("User-Agent", USER_AGENT);
+            for (name, value) in &owned {
+                builder = builder.header(name.as_str(), value.as_str());
+            }
+            let response = builder.send().await.map_err(|error| error.to_string())?;
+            let status = response.status();
+            if status.is_success() {
+                return response.text().await.map_err(|error| error.to_string());
+            }
+            let retry = response
+                .headers()
+                .get("retry-after")
+                .and_then(|value| value.to_str().ok())
+                .and_then(|value| value.parse::<u64>().ok());
+            Err(format!("HTTP {} (retry_after={retry:?})", status.as_u16()))
+        });
+
+        match result {
+            Ok(body) => return Ok(body),
+            Err(reason) if attempt + 1 < ATTEMPTS && retryable(&reason) => {
+                std::thread::sleep(retry_after(&reason, attempt));
+            }
+            Err(reason) => return Err(format!("请求 {url} 失败：{reason}")),
+        }
+    }
+    Err(format!("请求 {url} 失败：重试用尽"))
+}
+
+/// 这个失败值得再试一次吗（429 / 5xx / 连接类；**401/403/404 一律不重试**，重试只会更糟）。
+pub(super) fn retryable(reason: &str) -> bool {
+    reason.contains("HTTP 429")
+        || reason.contains("HTTP 500")
+        || reason.contains("HTTP 502")
+        || reason.contains("HTTP 503")
+        || reason.contains("HTTP 504")
+        || reason.contains("error sending request")
+        || reason.contains("timed out")
+}
+
+/// 退避时长：优先吃服务端给的 `Retry-After`（封顶 30s），否则指数退避（1s、2s、4s）。
+pub(super) fn retry_after(reason: &str, attempt: u32) -> Duration {
+    let parsed = reason
+        .split("retry_after=Some(")
+        .nth(1)
+        .and_then(|rest| rest.split(')').next())
+        .and_then(|value| value.parse::<u64>().ok());
+    match parsed {
+        Some(secs) => Duration::from_secs(secs.min(30)),
+        None => Duration::from_secs(1u64 << attempt.min(4)),
+    }
+}
+
+/// 最小百分号编码（query 串用；不为一件小事引第三方 crate）。
+pub(super) fn encode(raw: &str) -> String {
+    let mut out = String::with_capacity(raw.len());
+    for byte in raw.bytes() {
+        match byte {
+            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'.' | b'_' | b'~' => {
+                out.push(char::from(byte));
+            }
+            _ => out.push_str(&format!("%{byte:02X}")),
+        }
+    }
+    out
+}
diff --git a/crates/presenter/src/host/addon/install.rs b/crates/presenter/src/host/addon/install.rs
new file mode 100644
index 0000000..be4d5db
--- /dev/null
+++ b/crates/presenter/src/host/addon/install.rs
@@ -0,0 +1,252 @@
+//! 「一键装入指定实例」（M109）。
+//!
+//! ## 它到底做了什么（诚实版）
+//!
+//! | 内容类型 | 做什么 | 状态 |
+//! |---|---|---|
+//! | Mod / 资源包 / 光影 | 解析「该项目下匹配目标实例（版本 + 加载器）的那个文件」→ core 下载引擎下载到实例运行目录的 `mods/` `resourcepacks/` `shaderpacks/` → 进度经 `InstallProgressView` 回流（**复用下载页那块面板**） | 已接 |
+//! | 整合包 | 一律 `Failed` + 一句原因 | **未做**：core 没有「远程整合包装进实例」的管线（M111） |
+//! | CurseForge 文件解析 | 一律 `Failed` + 一句原因 | **未做**：需要带 key 的文件端点，本轮只做了 CF 的**检索** |
+//!
+//! ## 为什么进度只有阶段级，没有字节条
+//!
+//! 字节级进度要走 `ProgressEmitter`（core 的 tokio 广播），而 presenter 的依赖表里没有
+//! `tokio` / `futures-util`（`Cargo.toml` 不在本 mission 的 scope），拿不到接收端的 `recv()`。
+//! 所以这里给的是**阶段 + 文件名**（`Planning` → `Downloading` → `Done`/`Failed`），
+//! 面板在「进度未知」时本来就只画一行说明、不画条（`download/install.rs` 的既定口径）。
+//! 已登记为后续项：presenter 补 `futures-util` 之后换成字节级。
+
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicBool, Ordering};
+
+use unlucky_core::download::blocking::block_on;
+use unlucky_core::download::{DownloadRequest, ResourceKind};
+use unlucky_core::game::install::instance::read_instance_config;
+use unlucky_core::game::isolation::derive_game_dir;
+
+use crate::dto::{
+    loader_facet, ContentInstallRequest, ContentSource, InstallProgressView, InstallStage,
+    InstanceSummary,
+};
+
+use super::super::env::HostEnv;
+use super::super::job::{HostTask, JobSender};
+use super::http::{encode, get};
+use super::sources::MODRINTH;
+
+/// 跑一次装入（同步；由 [`super::spawn_install`] 放进后台线程）。
+pub(super) fn install(
+    env: &HostEnv,
+    tx: &JobSender,
+    request: &ContentInstallRequest,
+    cancel: &AtomicBool,
+    epoch: u64,
+) {
+    let mut progress = InstallProgressView {
+        version: request.title.clone(),
+        instance: request.instance.clone(),
+        loader: request.loader.label().to_string(),
+        files_total: 1,
+        ..InstallProgressView::new()
+    };
+
+    // 整合包：core 没有这条管线（M111），**不**假装能装。UI 侧按钮本来就是禁用的，
+    // 这里再挡一次是为了「绕过 UI 直接发指令」也不会静默做半件事。
+    if request.kind.dir().is_none() {
+        fail(
+            tx,
+            progress,
+            "整合包安装尚未开放；内容库对整合包只做检索",
+            epoch,
+        );
+        return;
+    }
+
+    let _ = tx.send(HostTask::Install {
+        progress: Box::new(progress.clone()),
+        epoch,
+    });
+    match run(env, request, cancel, &mut progress, tx, epoch) {
+        Ok(done) => {
+            progress.stage = InstallStage::Done;
+            progress.files_done = 1;
+            progress.message = done;
+            let _ = tx.send(HostTask::InstallDone {
+                progress: Box::new(progress),
+                result: Ok(request.title.clone()),
+                epoch,
+            });
+        }
+        Err(reason) => {
+            progress.stage = if cancel.load(Ordering::SeqCst) {
+                InstallStage::Cancelled
+            } else {
+                InstallStage::Failed
+            };
+            let _ = tx.send(HostTask::InstallDone {
+                progress: Box::new(progress),
+                result: Err(reason),
+                epoch,
+            });
+        }
+    }
+}
+
+fn fail(tx: &JobSender, mut progress: InstallProgressView, reason: &str, epoch: u64) {
+    progress.stage = InstallStage::Failed;
+    progress.message = reason.to_string();
+    let _ = tx.send(HostTask::InstallDone {
+        progress: Box::new(progress),
+        result: Err(reason.to_string()),
+        epoch,
+    });
+}
+
+/// 真正干活的那一段，返回一句人读的落盘描述。
+fn run(
+    env: &HostEnv,
+    request: &ContentInstallRequest,
+    cancel: &AtomicBool,
+    progress: &mut InstallProgressView,
+    tx: &JobSender,
+    epoch: u64,
+) -> Result<String, String> {
+    let instance = find_instance(env, &request.instance)?;
+    let game_dir = game_dir_of(env, &instance)?;
+    let dir = request
+        .kind
+        .dir()
+        .ok_or_else(|| "该内容类型不支持单文件装入".to_string())?;
+    let target_dir = game_dir.join(dir);
+    std::fs::create_dir_all(&target_dir)
+        .map_err(|error| format!("建目录 {} 失败：{error}", target_dir.display()))?;
+
+    let file = resolve_file(env, request)?;
+    if cancel.load(Ordering::SeqCst) {
+        return Err("已取消（下载开始前）".to_string());
+    }
+    progress.stage = InstallStage::Downloading;
+    progress.message = file.name.clone();
+    let _ = tx.send(HostTask::Install {
+        progress: Box::new(progress.clone()),
+        epoch,
+    });
+
+    let dest = target_dir.join(&file.name);
+    let mut download = DownloadRequest::new(ResourceKind::ModFile, file.url, dest.clone());
+    if let Some(sha1) = file.sha1.as_deref().filter(|hex| !hex.is_empty()) {
+        download = download.with_sha1(sha1);
+    }
+    block_on(super::super::engine::engine(env).download(download))
+        .map_err(|error| format!("下载失败：{error}"))?;
+    Ok(format!("{}（{}）", file.name, dest.display()))
+}
+
+fn find_instance(env: &HostEnv, id: &str) -> Result<InstanceSummary, String> {
+    super::super::game::instances(env)
+        .into_iter()
+        .find(|instance| instance.id == id)
+        .ok_or_else(|| format!("找不到实例 {id}"))
+}
+
+/// 实例的运行目录（D20 覆盖链：实例 `isolation` > 全局 `instances.mode`）。
+fn game_dir_of(env: &HostEnv, instance: &InstanceSummary) -> Result<PathBuf, String> {
+    let global = super::super::game::global_mode(env);
+    let config = read_instance_config(&env.layout, &instance.id)
+        .map_err(|error| format!("读实例设置失败：{error}"))?;
+    derive_game_dir(
+        &env.game,
+        &instance.version_id,
+        global,
+        config.as_ref(),
+        None,
+    )
+    .map(|derivation| derivation.game_dir)
+    .map_err(|error| format!("隔离目录派生失败：{error}"))
+}
+
+/// 要下载的那个文件。
+struct RemoteFile {
+    url: String,
+    name: String,
+    sha1: Option<String>,
+}
+
+/// 解析「这个项目下最适合目标实例的那个文件」。
+fn resolve_file(env: &HostEnv, request: &ContentInstallRequest) -> Result<RemoteFile, String> {
+    match request.source {
+        ContentSource::Modrinth => modrinth_file(env, request),
+        ContentSource::Curseforge => Err(
+            "CurseForge 的文件解析未接通（要带 key 的文件端点；见报告「没验的部分」）".to_string(),
+        ),
+    }
+}
+
+fn modrinth_file(env: &HostEnv, request: &ContentInstallRequest) -> Result<RemoteFile, String> {
+    let mut url = format!(
+        "{MODRINTH}/project/{}/version?game_versions={}",
+        request.project,
+        encode(&format!("[\"{}\"]", request.game_version))
+    );
+    if let Some(facet) = loader_facet(request.loader) {
+        url.push_str(&format!("&loaders={}", encode(&format!("[\"{facet}\"]"))));
+    }
+    let body = get(env, &url, &[])?;
+    let json: serde_json::Value = serde_json::from_str(&body)
+        .map_err(|error| format!("Modrinth 版本列表不是合法 JSON：{error}"))?;
+    let versions = json
+        .as_array()
+        .ok_or_else(|| "Modrinth 版本列表不是数组".to_string())?;
+    let first = versions
+        .first()
+        .ok_or_else(|| "这个项目没有匹配目标实例（版本 / 加载器）的文件".to_string())?;
+    let files = first
+        .get("files")
+        .and_then(serde_json::Value::as_array)
+        .ok_or_else(|| "版本里没有 files".to_string())?;
+    // 显式选 `primary: true`（Modrinth 官方口径）：取第一个会拿到 sources jar 这类坑
+    let file = files
+        .iter()
+        .find(|file| {
+            file.get("primary")
+                .and_then(serde_json::Value::as_bool)
+                .unwrap_or(false)
+        })
+        .or_else(|| files.first())
+        .ok_or_else(|| "版本里没有可用文件".to_string())?;
+
+    let url = file
+        .get("url")
+        .and_then(serde_json::Value::as_str)
+        .ok_or_else(|| "文件没有 url".to_string())?;
+    let name = file
+        .get("filename")
+        .and_then(serde_json::Value::as_str)
+        .ok_or_else(|| "文件没有 filename".to_string())?;
+    let sha1 = file
+        .get("hashes")
+        .and_then(|hashes| hashes.get("sha1"))
+        .and_then(serde_json::Value::as_str)
+        .map(ToString::to_string);
+    Ok(RemoteFile {
+        url: url.to_string(),
+        name: safe_file_name(name),
+        sha1,
+    })
+}
+
+/// 只留文件名本身：站点给的名字可能带路径分隔符，落盘前必须砍掉
+/// （与 `core::addon::pack::path` 的穿越双检同一条纪律）。
+pub(super) fn safe_file_name(raw: &str) -> String {
+    let name = raw
+        .rsplit(['/', '\\'])
+        .next()
+        .unwrap_or(raw)
+        .trim()
+        .to_string();
+    if name.is_empty() || name == "." || name == ".." {
+        "download.bin".to_string()
+    } else {
+        name
+    }
+}
diff --git a/crates/presenter/src/host/addon/pack.rs b/crates/presenter/src/host/addon/pack.rs
new file mode 100644
index 0000000..3137a4b
--- /dev/null
+++ b/crates/presenter/src/host/addon/pack.rs
@@ -0,0 +1,290 @@
+//! 整合包**导入 / 导出**（M113 `PACKUI`）：把 M111/M112 的管线接到内容库页上。
+//!
+//! ## 这里只做「解析目标 + 翻译 + 转发」
+//!
+//! 真正的活全在 core：`addon::import::import_pack`（三种格式 → 实例目录）与
+//! `addon::export::{scan_instance, export_instance}`（实例目录 → `.mrpack` / CF 清单）。
+//! 本模块不重新判定任何东西——三态、逐项原因、三分类全部**逐字段照搬** core 的报告
+//! （[`convert`]），于是「UI 说的」与「管线干的」是同一份事实。
+//!
+//! ## 文件分工（守 400 行）
+//!
+//! | 文件 | 职责 |
+//! |---|---|
+//! | 本文件 | `CoreHost::pack` 落点 + 取消标记 + 三条 spawn 共用的目标解析 |
+//! | [`import`] | 后台导入（探测 → 目标目录 → 管线 → 报告） |
+//! | [`export`] | 后台预检（不写盘）与后台写盘 |
+//! | [`convert`] | core 报告 → DTO（逐字段照搬）+ 小工具 |
+//! | [`diagnose`] | 探测诊断：「看起来像 X，但缺 Y」 |
+//!
+//! ## 导出预检与写盘用同一套判据
+//!
+//! core 的 `export_instance` 没有 dry-run 入口（已报 finding）。预检用 `scan_instance` +
+//! 「离线目录 ⇒ 一律内联」这条事实拼出来：`RemoteCatalog` 目前只有 `OfflineCatalog`，
+//! 所以每个可扫文件都证明不了可被远程替代 ⇒ 内联；`SkippedLocal` 就是「无法导出」。
+//! `tests::preview_counts_match_the_written_report` 用真管线钉住这个等式。
+//!
+//! ## 取消是**界面级**的
+//!
+//! [`cancel_pack`] 置模块级标记 + `dispatch` 里的 `CancelInstall` 把代次 +1：
+//!
+//! 1. 面板立刻收回（不是等后台回一句话）；
+//! 2. 这一轮之后回来的事件因代次不符被 `handle` 丢掉；
+//! 3. **后台那次导入会继续跑到结束**——core 的 `ImportRequest` 没有取消令牌，进度回调也拿不到
+//!    控制流。所以「取消」的真实含义是「不再显示、结果作废」，不是「把它停手」。要真停必须给
+//!    core 加 cancel token（已登记 finding，报告里同样划出来）；
+//! 4. **提示语不能借用安装那条**（复审 r1 P1-2）：下载页的取消 toast 写着「实例未创建」，
+//!    而导入会把实例**登记上**。所以 `cancel_pack()` 回一个「刚才有没有导入在跑」，
+//!    `dispatch` 据此改发 [`crate::dto::PackEvent::Cancelled`]，界面上换成
+//!    「导入会在后台继续跑完 —— 本次结果作废」这句。
+
+mod convert;
+mod diagnose;
+mod export;
+mod import;
+
+#[cfg(test)]
+mod tests;
+
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex};
+
+use unlucky_core::addon::export::{read_instance_snapshot, InstanceSnapshot};
+use unlucky_core::addon::pack::PackFormat;
+use unlucky_core::game::install::instance::read_instance_config;
+use unlucky_core::game::isolation::derive_game_dir;
+
+use crate::dto::{
+    CoreEvent, ExportRequestView, ImportProgressView, InstanceId, PackCommand, PackEvent,
+    PackFormatView,
+};
+
+use super::super::env::HostEnv;
+use super::super::job::{HostTask, JobSender};
+
+/// pack 的**每 host** 状态：代次 + 在跑计数 + 本次运行的取消标记。
+///
+/// ## 为什么不是裸静态量（复审 r2 P3-6 要的那句回答）
+///
+/// 裸静态量是**跨 host 共享**的。生产路径只有一个 host 所以看不出来，但测试里两个 host 会互相
+/// 干扰 —— 本轮实测撞到过：`host/cancel_tests` 派一次 `CancelInstall` 就把我这条用例在飞的导入
+/// 事件按代次丢了。键取 `LauncherLayout::home()`（每个测试的临时根都不同），于是各自独立：
+///
+/// - **代次**：每个 host 一条，`handle` 只跟**自己这个 host** 的当前值比；
+/// - **在跑计数**：一张计数表（每个 host 一格），由 [`InFlight`] 的 `Drop` 维护；
+/// - **取消标记**：每个 host 一份 `Arc<AtomicBool>`，导入线程拿克隆，`cancel_pack` 置位。
+///
+/// 为什么不挪进 `CoreHost`：那要给 `host/mod.rs` 加字段（不在本 mission 的 scope）。这张表等价，
+/// 只是把「每 host 的字段」放在模块里；`host/mod.rs` 一旦进 scope，搬过去只是把这张表删掉。
+#[derive(Default, Clone, Copy)]
+struct HostPackState {
+    epoch: u64,
+    in_flight: usize,
+}
+
+static PACK_STATE: Mutex<Vec<(PathBuf, HostPackState)>> = Mutex::new(Vec::new());
+static PACK_CANCEL: Mutex<Vec<(PathBuf, Arc<AtomicBool>)>> = Mutex::new(Vec::new());
+
+/// 这张表的键（数据根；`HostEnv::at_root` 的每个测试根都不同）。
+fn host_key(env: &HostEnv) -> PathBuf {
+    env.layout.home().to_path_buf()
+}
+
+fn with_state<T>(env: &HostEnv, body: impl FnOnce(&mut HostPackState) -> T) -> T {
+    let key = host_key(env);
+    let mut table = PACK_STATE
+        .lock()
+        .unwrap_or_else(|poison| poison.into_inner());
+    if let Some(index) = table.iter().position(|(name, _)| *name == key) {
+        return body(&mut table[index].1);
+    }
+    table.push((key, HostPackState::default()));
+    body(&mut table.last_mut().expect("刚插入").1)
+}
+
+/// 这个 host 当前的 pack 代次（`handle` 用它判断事件是否已被取消/关面板作废）。
+pub(in crate::host) fn pack_epoch(env: &HostEnv) -> u64 {
+    with_state(env, |state| state.epoch)
+}
+
+/// 作废这个 host 在飞的一切 pack 事件（取消 / 关面板都走它）。
+pub(in crate::host) fn bump_pack_epoch(env: &HostEnv) -> u64 {
+    with_state(env, |state| {
+        state.epoch = state.epoch.wrapping_add(1);
+        state.epoch
+    })
+}
+
+/// 这个 host 现在有几条导入在跑。
+pub(in crate::host) fn in_flight(env: &HostEnv) -> usize {
+    with_state(env, |state| state.in_flight)
+}
+
+/// 「这次导入还在跑」的 **RAII 句柄**。
+///
+/// 复审 r2 P2-1 的教训：手工 `finished()` 只在 `block_on(import_pack(..))` 之后调用，
+/// 而失败早退（探测失败 / 目标目录不可用）都在它之前 ⇒ 计数永远留在「在跑」，于是下一次
+/// **下载页**的「取消安装」不再发 `InstallCancelled`，还给内容库画一句「导入还在后台跑」的假话。
+///
+/// 现在计数由句柄的 `Drop` 负责：**任何**退出路径（早退、报错、`?`、panic 展开）都会减一。
+pub(super) struct InFlight {
+    env: HostEnv,
+}
+
+impl InFlight {
+    /// 计一次「在跑」。句柄活多久，这次导入就算跑多久。
+    pub(super) fn begin(env: &HostEnv) -> Self {
+        with_state(env, |state| state.in_flight += 1);
+        Self { env: env.clone() }
+    }
+}
+
+impl Drop for InFlight {
+    fn drop(&mut self) {
+        with_state(&self.env, |state| {
+            state.in_flight = state.in_flight.saturating_sub(1);
+        });
+    }
+}
+
+/// 取消这个 host 正在跑的导入（`CancelInstall` 与「关面板」都走它；没在跑时是 no-op）。
+///
+/// 返回值 = 「刚才确实有一次导入在跑」。调用方据此决定提示语：**导入的取消不是 install 的取消**
+/// （后台会跑完并登记实例，见模块文档），所以不能复用下载页那条「安装已取消、实例未创建」。
+pub(in crate::host) fn cancel_pack(env: &HostEnv) -> bool {
+    let key = host_key(env);
+    {
+        let table = PACK_CANCEL
+            .lock()
+            .unwrap_or_else(|poison| poison.into_inner());
+        if let Some((_, cancel)) = table.iter().find(|(name, _)| *name == key) {
+            cancel.store(true, Ordering::SeqCst);
+        }
+    }
+    bump_pack_epoch(env);
+    in_flight(env) > 0
+}
+
+/// 这个 host 新一次导入的取消标记（挂进表里供 [`cancel_pack`] 用）。
+fn fresh_cancel(env: &HostEnv) -> Arc<AtomicBool> {
+    let cancel = Arc::new(AtomicBool::new(false));
+    let key = host_key(env);
+    let mut table = PACK_CANCEL
+        .lock()
+        .unwrap_or_else(|poison| poison.into_inner());
+    match table.iter_mut().find(|(name, _)| *name == key) {
+        Some((_, slot)) => *slot = Arc::clone(&cancel),
+        None => table.push((key, Arc::clone(&cancel))),
+    }
+    cancel
+}
+
+/// `AppCommand::Pack` 的落点（M113）。
+impl super::super::CoreHost {
+    pub(crate) fn pack(&mut self, command: PackCommand) {
+        let epoch = pack_epoch(&self.env);
+        match command {
+            PackCommand::Import(request) => {
+                let cancel = fresh_cancel(&self.env);
+                // 句柄在**派发点**就计上，随线程一起结束（含早退与 panic）
+                let guard = InFlight::begin(&self.env);
+                // 先把面板点亮：用户点了就有反应，不等后台回第一条进度
+                let name = request
+                    .instance_name
+                    .clone()
+                    .or_else(|| request.instance.clone())
+                    .unwrap_or_default();
+                self.send(CoreEvent::Pack(Box::new(PackEvent::Progress(Some(
+                    Box::new(ImportProgressView::new(name)),
+                )))));
+                import::spawn_import(
+                    self.env.clone(),
+                    self.tx.clone(),
+                    *request,
+                    epoch,
+                    cancel,
+                    guard,
+                );
+            }
+            PackCommand::Export(request) => {
+                export::spawn_preview(self.env.clone(), self.tx.clone(), *request, epoch);
+            }
+            PackCommand::Confirm(request) => {
+                export::spawn_write(self.env.clone(), self.tx.clone(), *request, epoch);
+            }
+            PackCommand::Dismiss => {
+                // 只作废 pack 自己的代次：**不碰** `install_epoch`（那是下载页安装的命门）
+                cancel_pack(&self.env);
+                self.send(CoreEvent::Pack(Box::new(PackEvent::Cleared)));
+            }
+        }
+    }
+}
+
+/// 后台任务 → host 的一跳（三个 spawn 共用）。
+pub(super) fn send(tx: &JobSender, epoch: u64, event: PackEvent) {
+    let _ = tx.send(HostTask::Pack {
+        event: Box::new(event),
+        epoch,
+    });
+}
+
+/// 实例 → 运行目录（与 `addon/install.rs` 同一条派生：实例隔离档 > 全局档）。
+pub(super) fn instance_root(env: &HostEnv, id: &InstanceId) -> Result<PathBuf, String> {
+    let instance = super::super::game::instances(env)
+        .into_iter()
+        .find(|instance| &instance.id == id)
+        .ok_or_else(|| format!("instance not found: {id}"))?;
+    let global = super::super::game::global_mode(env);
+    let config = read_instance_config(&env.layout, &instance.id)
+        .map_err(|error| format!("read instance config failed: {error}"))?;
+    derive_game_dir(
+        &env.game,
+        &instance.version_id,
+        global,
+        config.as_ref(),
+        None,
+    )
+    .map(|derivation| derivation.game_dir)
+    .map_err(|error| format!("derive game dir failed: {error}"))
+}
+
+/// 实例快照（清单的 `game` + `dependencies` 从它来）。读不出来就返回 `None`，
+/// 由 core 自己按 `root/versions/` 再试一次（失败会给具名错误）。
+pub(super) fn snapshot_of(env: &HostEnv, id: &InstanceId) -> Option<InstanceSnapshot> {
+    let instance = super::super::game::instances(env)
+        .into_iter()
+        .find(|instance| &instance.id == id)?;
+    // 隔离实例的 `versions/` 在全局根下，所以试全局根
+    read_instance_snapshot(env.game.root(), Some(&instance.version_id)).ok()
+}
+
+/// 格式视图 → core 的静态格式（MultiMC 只读，不能当导出目标）。
+pub(super) fn format_of(format: PackFormatView) -> Result<&'static dyn PackFormat, String> {
+    use unlucky_core::addon::pack::{curseforge, modrinth};
+    match format {
+        PackFormatView::Modrinth => Ok(&modrinth::MODRINTH),
+        PackFormatView::Curseforge => Ok(&curseforge::CURSEFORGE),
+        PackFormatView::Multimc => {
+            Err("MultiMC / Prism can only be imported, not exported".to_string())
+        }
+    }
+}
+
+/// 缺省落盘路径：`<data>/exports/<name>-<version>.<ext>`。
+pub(super) fn default_export_path(env: &HostEnv, request: &ExportRequestView) -> PathBuf {
+    let ext = match request.format {
+        PackFormatView::Curseforge => "zip",
+        _ => "mrpack",
+    };
+    let name = format!(
+        "{}-{}",
+        convert::slug(&request.name),
+        convert::slug(&request.version)
+    );
+    env.layout
+        .data()
+        .join("exports")
+        .join(format!("{name}.{ext}"))
+}
diff --git a/crates/presenter/src/host/addon/pack/convert.rs b/crates/presenter/src/host/addon/pack/convert.rs
new file mode 100644
index 0000000..ec19cbf
--- /dev/null
+++ b/crates/presenter/src/host/addon/pack/convert.rs
@@ -0,0 +1,256 @@
+//! core 报告 → DTO（M113）：**逐字段照搬，不重算任何结论**。
+//!
+//! 这一层的唯一职责是翻译：三态、五阶段、四种处置、三种冲突成因、十一种导出原因，
+//! 全部一一对应。任何一个「顺手换算一下」都会让 UI 说的和管线干的不是一回事，
+//! 所以这里没有一处 re-derive（唯一例外是把 `&'static str` 的稳定码换成人读串）。
+//!
+//! 翻译用的是 core 的稳定 slug（`as_str()`）+ DTO 的 `from_slug()`，
+//! 于是「翻译表」本身就是一份可审计的清单：core 加了新变体，`from_slug` 返回 `None`
+//! 时这里会落到一个有名字的兜底，而不是悄悄画成别的意思。
+
+use std::path::{Path, PathBuf};
+
+use unlucky_core::addon::export::{ExportReport, FileClass, FileReason};
+use unlucky_core::addon::import::{
+    ConflictChoice, ConflictFile, ConflictReason, FileAction, ImportError, ImportProgress,
+    ImportReport, LoaderTarget, MissingReason,
+};
+
+use crate::dto::{
+    ConflictChoiceView, ConflictFileView, ConflictReasonView, ExportClassView, ExportDoneView,
+    ExportReasonView, FileActionView, ImportErrorView, ImportProgressView, ImportReportView,
+    ImportStageView, ImportStatusView, ImportedFileView, MissingFileView, MissingReasonView,
+    PackFormatView,
+};
+
+/// 一次导入结果 → DTO。
+pub(super) fn report_view(report: &ImportReport, target: &Path) -> ImportReportView {
+    ImportReportView {
+        status: ImportStatusView::from_slug(report.status.as_str())
+            .unwrap_or(ImportStatusView::Failed),
+        format: report.format.as_deref().and_then(PackFormatView::from_slug),
+        pack_name: report.pack_name.clone(),
+        pack_version: report.pack_version.clone(),
+        game_version: report.game_version.clone(),
+        loader: report.loader.as_ref().map(loader_label),
+        version_id: report.version_id.clone(),
+        target: target.to_path_buf(),
+        files: report
+            .files
+            .iter()
+            .map(|file| ImportedFileView {
+                path: file.path.clone(),
+                action: action_view(file.action),
+                bytes: file.bytes,
+            })
+            .collect(),
+        conflicts: report.conflicts.iter().map(conflict_view).collect(),
+        missing: report
+            .missing
+            .iter()
+            .map(|file| MissingFileView {
+                path: file.path.clone(),
+                display: file.display.clone(),
+                reason: missing_view(file.reason),
+                detail: file.detail.clone(),
+            })
+            .collect(),
+        rejected: report
+            .rejected_components
+            .iter()
+            .map(|component| match &component.version {
+                Some(version) => format!("{} {version}", component.uid),
+                None => component.uid.clone(),
+            })
+            .collect(),
+        warnings: report
+            .warnings
+            .iter()
+            .map(|issue| issue.message.clone())
+            .collect(),
+        error: report.error.as_ref().map(error_view),
+        registered: report
+            .registered
+            .as_ref()
+            .map(|registered| registered.name.clone()),
+        bytes_written: report.bytes_written,
+        rolled_back: report.rolled_back,
+    }
+}
+
+/// 一次导出结果 → DTO。
+pub(super) fn done_view(report: &ExportReport) -> ExportDoneView {
+    ExportDoneView {
+        path: report.path.clone(),
+        bytes: report.bytes,
+        remote: u32::try_from(report.remote_count()).unwrap_or(u32::MAX),
+        inline: u32::try_from(report.inline_count()).unwrap_or(u32::MAX),
+        skipped: u32::try_from(report.skipped_count()).unwrap_or(u32::MAX),
+    }
+}
+
+/// 一条导入进度 → DTO。
+pub(super) fn progress_view(progress: &ImportProgress, pack: &str) -> ImportProgressView {
+    ImportProgressView {
+        stage: ImportStageView::from_slug(progress.stage.as_str())
+            .unwrap_or(ImportStageView::Probe),
+        done: u32::try_from(progress.done).unwrap_or(u32::MAX),
+        total: u32::try_from(progress.total).unwrap_or(u32::MAX),
+        current: progress.current.clone(),
+        pack: pack.to_string(),
+    }
+}
+
+/// 致命失败 → DTO（稳定码原样带走，日志与 `--json` 用的是同一串）。
+fn error_view(error: &ImportError) -> ImportErrorView {
+    ImportErrorView {
+        code: error.kind().as_str().to_string(),
+        label: error.kind().label().to_string(),
+        message: error.message().to_string(),
+        hint: error.hint().map(str::to_string),
+    }
+}
+
+fn conflict_view(file: &ConflictFile) -> ConflictFileView {
+    ConflictFileView {
+        path: file.path.clone(),
+        reason: match file.reason {
+            ConflictReason::UserModified => ConflictReasonView::UserModified,
+            ConflictReason::UserDeleted => ConflictReasonView::UserDeleted,
+            ConflictReason::PreExisting => ConflictReasonView::PreExisting,
+        },
+        choice: match file.choice {
+            ConflictChoice::KeepUser => ConflictChoiceView::KeepUser,
+            ConflictChoice::Overwrite => ConflictChoiceView::Overwrite,
+        },
+        pack_sha1: file.pack_sha1.clone(),
+        base_sha1: file.base_sha1.clone(),
+        disk_sha1: file.disk_sha1.clone(),
+        pack_size: file.pack_size,
+    }
+}
+
+const fn action_view(action: FileAction) -> FileActionView {
+    match action {
+        FileAction::Installed => FileActionView::Installed,
+        FileAction::Replaced => FileActionView::Replaced,
+        FileAction::SkippedIdentical => FileActionView::SkippedIdentical,
+        FileAction::KeptUser => FileActionView::KeptUser,
+    }
+}
+
+const fn missing_view(reason: MissingReason) -> MissingReasonView {
+    match reason {
+        MissingReason::Offline => MissingReasonView::Offline,
+        MissingReason::NoSource => MissingReasonView::NoSource,
+        MissingReason::FetchFailed => MissingReasonView::FetchFailed,
+    }
+}
+
+pub(super) fn reason_view(reason: FileReason) -> ExportReasonView {
+    ExportReasonView::from_slug(reason.as_str()).unwrap_or(ExportReasonView::Unreadable)
+}
+
+pub(super) fn class_view(class: FileClass) -> ExportClassView {
+    match class {
+        FileClass::Remote => ExportClassView::Remote,
+        FileClass::Inline => ExportClassView::Inline,
+        FileClass::Skipped => ExportClassView::Skipped,
+    }
+}
+
+/// 加载器 → 人读串（`fabric-loader 0.15.11` / `vanilla 1.20.1`）。
+fn loader_label(target: &LoaderTarget) -> String {
+    format!("{} {}", target.kind.as_str(), target.loader_version)
+}
+
+/// 「命令跑起来了，但目标实例不可用」这类**host 侧**失败的报告。
+///
+/// 仍然走三态里的 `Failed`：界面只有一种失败形状，用户不用学第二套。
+/// `target` 是**目标实例目录**（不知道就给空路径），不是包路径（复审 r1 P2-9 顺手纠的 DTO 语义）。
+pub(super) fn failed_report(
+    target: PathBuf,
+    pack: &Path,
+    code: &str,
+    label: &str,
+    message: &str,
+) -> ImportReportView {
+    ImportReportView {
+        status: ImportStatusView::Failed,
+        format: None,
+        pack_name: Some(pack_stem(pack)),
+        pack_version: None,
+        game_version: None,
+        loader: None,
+        version_id: None,
+        target,
+        files: Vec::new(),
+        conflicts: Vec::new(),
+        missing: Vec::new(),
+        rejected: Vec::new(),
+        warnings: Vec::new(),
+        error: Some(ImportErrorView {
+            code: code.to_string(),
+            label: label.to_string(),
+            message: message.to_string(),
+            hint: None,
+        }),
+        registered: None,
+        bytes_written: 0,
+        rolled_back: true,
+    }
+}
+
+/// 包文件名（`Better MC.mrpack` → `Better MC`）。
+pub(super) fn pack_stem(pack: &Path) -> String {
+    pack.file_stem()
+        .map(|stem| stem.to_string_lossy().to_string())
+        .unwrap_or_else(|| "imported-pack".to_string())
+}
+
+/// **实例目录名**：ASCII 化 + 必要时补一段内容哈希。
+///
+/// 判据（复审 r2 P2-2 之后与注释对齐）：名字里**只含** ASCII 字母数字、空格、`-`、`_` 时
+/// 保持原样（空格折成 `-`，`Better MC` → `Better-MC`）；**一旦折过别的字符**（中文、`.`、
+/// 括号……）就补 `-<hash8>`，用原名的哈希保住区分度 —— 否则「我的整合包」「另一个整合包」
+/// 都会得到 `pack`，第二个中文名导入直接撞「directory already exists」。
+pub(super) fn dir_name(name: &str) -> String {
+    let base = slug(name);
+    let faithful = !name.is_empty()
+        && name
+            .chars()
+            .all(|ch| ch.is_ascii_alphanumeric() || ch == '-' || ch == '_' || ch == ' ');
+    if faithful {
+        base
+    } else {
+        format!("{base}-{}", hash8(name))
+    }
+}
+
+/// FNV-1a 64 → 8 位十六进制（只要稳定、短、不需要密码学强度）。
+fn hash8(text: &str) -> String {
+    let mut hash: u64 = 0xcbf2_9ce4_8422_2325;
+    for byte in text.as_bytes() {
+        hash ^= u64::from(*byte);
+        hash = hash.wrapping_mul(0x0000_0100_0000_01b3);
+    }
+    format!("{:08x}", hash as u32)
+}
+
+/// 目录/文件名用的 slug（只留 ASCII 字母数字与 `-` / `_`，其余折成 `-`）。
+pub(super) fn slug(text: &str) -> String {
+    let mut out = String::new();
+    for ch in text.chars() {
+        if ch.is_ascii_alphanumeric() || ch == '-' || ch == '_' {
+            out.push(ch);
+        } else if !out.ends_with('-') {
+            out.push('-');
+        }
+    }
+    let trimmed = out.trim_matches('-').to_string();
+    if trimmed.is_empty() {
+        "pack".to_string()
+    } else {
+        trimmed
+    }
+}
diff --git a/crates/presenter/src/host/addon/pack/diagnose.rs b/crates/presenter/src/host/addon/pack/diagnose.rs
new file mode 100644
index 0000000..ca178cb
--- /dev/null
+++ b/crates/presenter/src/host/addon/pack/diagnose.rs
@@ -0,0 +1,104 @@
+//! 探测诊断（M113）：「这个包**看起来像** X，但**缺** Y」。
+//!
+//! ## 为什么由 host 判，不引 core 改动
+//!
+//! core 的 `PackRegistry::detect` 只回答「谁认领」，一个都不认领时只给一句
+//! `pack_unsupported` + 「试过哪些格式」。而用户手里那个包往往**差一点点**就是某个已知格式
+//! （CF 导出漏了 `manifest.json`、mrpack 被浏览器改名成 `.zip` 后解压丢了 index）。
+//! 判断「像哪个」要看包内到底有哪些标记文件，这是宿主层拿着 `PackArchive` 才看得见的事。
+//!
+//! ## 判据只有标记文件的有无（不看文件名）
+//!
+//! | 格式 | 标记 | 邻居（有它但没标记 ⇒ 「像它」） |
+//! |---|---|---|
+//! | CurseForge | `manifest.json` | `overrides/` · `mods/` |
+//! | Modrinth | `modrinth.index.json` | `overrides/` |
+//! | MultiMC / Prism | `mmc-pack.json` | `instance.cfg` · `.minecraft/` |
+//!
+//! `saw` 只留前 5 条有代表性的标记：长路径往界面里倒会把版面撑破（塔台复审提过）。
+//! 一个标记都没认出来时 `saw` 为空，由界面显示「nothing recognisable」而不是一行空白。
+
+use std::path::Path;
+
+use unlucky_core::addon::pack::{PackArchive, PackLimits, PackRegistry};
+
+use crate::dto::{PackFormatView, ProbeView};
+
+/// 诊断一个包（`None` = 有个格式认领它，正常走管线）。
+pub(super) fn of(pack: &Path) -> Option<ProbeView> {
+    let archive = match PackArchive::open(pack, PackLimits::default()) {
+        Ok(archive) => archive,
+        Err(error) => {
+            // 连 zip 都打不开（选错文件 / 下了一半）：也要说清楚是哪一步失败的
+            return Some(ProbeView {
+                looks_like: None,
+                missing: Vec::new(),
+                saw: Vec::new(),
+                detail: format!("could not open the archive: {error}"),
+            });
+        }
+    };
+    let registry = PackRegistry::builtin();
+    if registry.detect(&archive).is_ok() {
+        return None;
+    }
+
+    // (格式, 标记文件, 邻居标记)
+    let rules: [(PackFormatView, &str, &[&str]); 3] = [
+        (
+            PackFormatView::Curseforge,
+            "manifest.json",
+            &["overrides/", "mods/"],
+        ),
+        (
+            PackFormatView::Modrinth,
+            "modrinth.index.json",
+            &["overrides/"],
+        ),
+        (
+            PackFormatView::Multimc,
+            "mmc-pack.json",
+            &["instance.cfg", ".minecraft/"],
+        ),
+    ];
+
+    // 目录输入的条目名**没有尾斜杠**（`overrides` 而不是 `overrides/`），zip 里目录条目也可能缺；
+    // 所以匹配同时认「精确 / 前缀 / 去掉尾斜杠」三种写法，判据仍然只有标记文件的有无。
+    let names: Vec<&str> = archive.entries().iter().map(|entry| entry.name()).collect();
+    let has = |needle: &str| {
+        names.iter().any(|name| {
+            *name == needle || name.starts_with(needle) || *name == needle.trim_end_matches('/')
+        })
+    };
+
+    let mut saw: Vec<String> = Vec::new();
+    let mut best: Option<(PackFormatView, String)> = None;
+    for (format, marker, neighbours) in rules {
+        let hits: Vec<&str> = neighbours
+            .iter()
+            .copied()
+            .filter(|entry| has(entry))
+            .collect();
+        if hits.is_empty() {
+            continue;
+        }
+        if !has(marker) {
+            // 有邻居、没标记 ⇒ 「像它，但缺那个标记」
+            saw.extend(hits.iter().map(|entry| (*entry).to_string()));
+            if best.is_none() {
+                best = Some((format, marker.to_string()));
+            }
+        }
+    }
+    saw.sort();
+    saw.dedup();
+    saw.truncate(5);
+
+    let detail = format!("tried: {}", registry.ids().join(" / "));
+    Some(ProbeView {
+        looks_like: best.as_ref().map(|(format, _)| *format),
+        missing: best.map(|(_, marker)| vec![marker]).unwrap_or_default(),
+        saw,
+        detail,
+    })
+}
diff --git a/crates/presenter/src/host/addon/pack/export.rs b/crates/presenter/src/host/addon/pack/export.rs
new file mode 100644
index 0000000..1556e84
--- /dev/null
+++ b/crates/presenter/src/host/addon/pack/export.rs
@@ -0,0 +1,132 @@
+//! 导出（M113）：**预检不写盘**，写盘是另一次调用，两次用同一套判据。
+//!
+//! 预检的全部依据就是 core 的 `scan_instance` + 「没有远程目录 ⇒ 一律内联」：
+//! `RemoteCatalog` 目前只有 `OfflineCatalog`，任何文件都证明不了可被远程替代。所以
+//! 「将内联 N / 无法导出 M」里的 N 是扫到的文件数、M 是 `SkippedLocal`（符号链接 / 路径不安全 /
+//! 读不出来）。写盘走 `export_instance`（同样注入离线目录），
+//! `tests::preview_counts_match_the_written_report` 用真管线钉住两边相等。
+
+use unlucky_core::addon::export::{
+    export_instance, scan_instance, ExportRequest, OfflineCatalog, DEFAULT_CONTENT_ROOTS,
+};
+
+use crate::dto::{
+    ExportClassView, ExportFileView, ExportPreviewView, ExportReasonView, ExportRequestView,
+    PackEvent,
+};
+
+use super::super::super::env::HostEnv;
+use super::super::super::job::{spawn, JobSender};
+use super::convert::{class_view, done_view, reason_view};
+use super::send;
+
+/// 起一个后台预检线程（**不写盘**）。
+pub(super) fn spawn_preview(env: HostEnv, tx: JobSender, request: ExportRequestView, epoch: u64) {
+    spawn("pack-export-preview", move || {
+        let root = match super::instance_root(&env, &request.instance) {
+            Ok(root) => root,
+            Err(reason) => {
+                send(&tx, epoch, PackEvent::ExportFailed(reason));
+                return;
+            }
+        };
+        send(
+            &tx,
+            epoch,
+            PackEvent::Preview(Box::new(preview_of(&root, &env, &request))),
+        );
+    });
+}
+
+/// 预检的**纯函数部分**（不起线程、不写盘）：扫描 → 三分类计数。
+///
+/// 抽出来是为了能测：`tests::preview_counts_match_the_written_report` 用它和
+/// `export_instance` 的真实报告对数字，等式不成立就红。
+pub(super) fn preview_of(
+    root: &std::path::Path,
+    env: &HostEnv,
+    request: &ExportRequestView,
+) -> ExportPreviewView {
+    let target = request
+        .target
+        .clone()
+        .unwrap_or_else(|| super::default_export_path(env, request));
+    let roots: Vec<String> = DEFAULT_CONTENT_ROOTS
+        .iter()
+        .map(|entry| (*entry).to_string())
+        .collect();
+    let (files, skipped) = scan_instance(root, &roots);
+
+    let mut rows: Vec<ExportFileView> = files
+        .iter()
+        .map(|file| ExportFileView {
+            path: file.path.clone(),
+            class: ExportClassView::Inline,
+            reason: ExportReasonView::NoRemoteMatch,
+            bytes: file.bytes,
+            disabled: file.disabled,
+        })
+        .collect();
+    rows.extend(skipped.iter().map(|file| ExportFileView {
+        path: file.path.clone(),
+        class: class_view(file.reason.class()),
+        reason: reason_view(file.reason),
+        bytes: 0,
+        disabled: false,
+    }));
+    // 与 `ExportReport::files` 同一条顺序（按路径）
+    rows.sort_by(|left, right| left.path.cmp(&right.path));
+
+    ExportPreviewView {
+        format: request.format,
+        instance: request.instance.clone(),
+        name: request.name.clone(),
+        version: request.version.clone(),
+        target,
+        files: rows,
+        notes: vec![
+            "No remote catalogue yet: every file has to be inlined into overrides/".to_string(),
+            "Unreadable files, symlinks and unsafe paths are listed below, one by one".to_string(),
+        ],
+    }
+}
+
+/// 起一个后台写盘线程。
+pub(super) fn spawn_write(env: HostEnv, tx: JobSender, request: ExportRequestView, epoch: u64) {
+    spawn("pack-export", move || {
+        let root = match super::instance_root(&env, &request.instance) {
+            Ok(root) => root,
+            Err(reason) => {
+                send(&tx, epoch, PackEvent::ExportFailed(reason));
+                return;
+            }
+        };
+        let format = match super::format_of(request.format) {
+            Ok(format) => format,
+            Err(reason) => {
+                send(&tx, epoch, PackEvent::ExportFailed(reason));
+                return;
+            }
+        };
+        let target = request
+            .target
+            .clone()
+            .unwrap_or_else(|| super::default_export_path(&env, &request));
+        let snapshot = super::snapshot_of(&env, &request.instance);
+        let mut core_request = ExportRequest::new(&root, &target, format)
+            .with_name(request.name.clone())
+            .with_version(request.version.clone())
+            .with_catalog(&OfflineCatalog);
+        if let Some(snapshot) = &snapshot {
+            core_request = core_request.with_snapshot(snapshot);
+        }
+        match export_instance(&core_request) {
+            Ok(report) => send(
+                &tx,
+                epoch,
+                PackEvent::Exported(Box::new(done_view(&report))),
+            ),
+            Err(error) => send(&tx, epoch, PackEvent::ExportFailed(format!("{error}"))),
+        }
+    });
+}
diff --git a/crates/presenter/src/host/addon/pack/import.rs b/crates/presenter/src/host/addon/pack/import.rs
new file mode 100644
index 0000000..10f5c2c
--- /dev/null
+++ b/crates/presenter/src/host/addon/pack/import.rs
@@ -0,0 +1,176 @@
+//! 后台导入（M113）：探测 → 目标目录 → core 的 `import_pack` → 报告。
+//!
+//! 三条纪律：
+//!
+//! 1. **探测失败不空跑管线**：先做具名诊断（[`super::diagnose`]），失败就只回 `Probe` 事件；
+//! 2. **默认档永远是 `KeepUser`**：只有 `request.overwrite == true` 才换成 `Overwrite`；
+//! 3. **取消后不再打扰界面**：进度回调与最终报告都先看取消标记。
+
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+
+use unlucky_core::addon::import::{
+    import_pack, ConflictPolicy, DownloadEngineFetcher, ImportProgress, ImportProgressSink,
+    ImportRequest,
+};
+use unlucky_core::download::blocking::block_on;
+
+use crate::dto::{ImportRequestView, PackEvent};
+use unlucky_core::addon::import::ImportStatus;
+
+use super::super::super::env::HostEnv;
+use super::super::super::job::{spawn, JobSender};
+use super::convert;
+use super::send;
+
+/// 起一个后台导入线程。
+pub(super) fn spawn_import(
+    env: HostEnv,
+    tx: JobSender,
+    request: ImportRequestView,
+    epoch: u64,
+    cancel: Arc<AtomicBool>,
+    inflight: super::InFlight,
+) {
+    spawn("pack-import", move || {
+        // 句柄跟着这次运行走到**出口**：正常收尾、两条早退、panic 展开都会 drop ⇒ 计数减一。
+        // 以前是手工 `finished()` 放在 `block_on()` 之后，两条早退路径直接漏掉（复审 r2 P2-1）。
+        let _inflight = inflight;
+        run(&env, &tx, &request, epoch, cancel);
+    });
+}
+
+pub(super) fn run(
+    env: &HostEnv,
+    tx: &JobSender,
+    request: &ImportRequestView,
+    epoch: u64,
+    cancel: Arc<AtomicBool>,
+) {
+    // 探测先过一遍：失败就只给具名诊断（「看起来像 X，但缺 Y」），不空跑一遍管线
+    if let Some(probe) = super::diagnose::of(&request.pack) {
+        send(tx, epoch, PackEvent::Probe(Box::new(probe)));
+        return;
+    }
+    let (target, register) = match target_of(env, request) {
+        Ok(target) => target,
+        Err(reason) => {
+            send(
+                tx,
+                epoch,
+                PackEvent::Report(Box::new(convert::failed_report(
+                    // 目标目录不可用 ⇒ 如实给空路径（不把包路径冒充成实例目录）
+                    PathBuf::new(),
+                    &request.pack,
+                    "import_host",
+                    "Target instance is not usable",
+                    &reason,
+                ))),
+            );
+            return;
+        }
+    };
+
+    let pack_name = request
+        .instance_name
+        .clone()
+        .unwrap_or_else(|| convert::pack_stem(&request.pack));
+    let progress_tx = tx.clone();
+    let progress_name = pack_name.clone();
+    let cancel_flag = Arc::clone(&cancel);
+    let sink: ImportProgressSink = Arc::new(move |progress: &ImportProgress| {
+        if cancel_flag.load(Ordering::SeqCst) {
+            return;
+        }
+        send(
+            &progress_tx,
+            epoch,
+            PackEvent::Progress(Some(Box::new(convert::progress_view(
+                progress,
+                &progress_name,
+            )))),
+        );
+    });
+
+    let engine = super::super::super::engine::engine(env);
+    let fetcher = DownloadEngineFetcher::new(&engine);
+    let mut core_request = ImportRequest::new(&request.pack, &target)
+        .with_fetcher(&fetcher)
+        .with_progress(sink);
+    if request.overwrite {
+        core_request = core_request.with_conflict_policy(ConflictPolicy::Overwrite);
+    }
+    if register {
+        core_request = core_request.with_registration(&env.layout, Some(&pack_name));
+    }
+
+    let report = block_on(import_pack(&core_request));
+    if report.status == ImportStatus::Failed && register {
+        // 失败已回滚，但**目录是我们建的**、core 只清文件不清目录 ⇒ 不清掉的话
+        // 下一次重试会撞「directory already exists」（复审 r1 P2-9）。
+        remove_if_empty(&target);
+    }
+    if cancel.load(Ordering::SeqCst) {
+        // 取消之后不再打扰界面（面板已经收回，代次也已经作废）。
+        // 注意：后台这一步**已经跑完**（core 没有取消令牌），实例可能已被登记 ——
+        // 所以取消的提示语必须说「还在后台跑」，不能说「实例未创建」。
+        return;
+    }
+    send(
+        tx,
+        epoch,
+        PackEvent::Report(Box::new(convert::report_view(&report, &target))),
+    );
+}
+
+/// 目录里没有东西就删掉（失败回滚后的收尾；非空一律不动）。
+fn remove_if_empty(dir: &std::path::Path) {
+    let empty = std::fs::read_dir(dir)
+        .map(|mut entries| entries.next().is_none())
+        .unwrap_or(false);
+    if empty {
+        let _ = std::fs::remove_dir(dir);
+    }
+}
+
+/// 导入目标：`(目录, 是否登记新实例)`。
+///
+/// - 选了实例 ⇒ 它的运行目录，**不登记**（已经是一条实例记录）；
+/// - 没选实例 ⇒ `<data>/instances/<dir_name>` 新目录 + 登记（实例名 = 用户给的名字或包名）。
+///   注意 M111 的既有边界：导入**不装加载器**，所以新实例报告的 `版本 id` 还要另外装。
+pub(super) fn target_of(
+    env: &HostEnv,
+    request: &ImportRequestView,
+) -> Result<(PathBuf, bool), String> {
+    match &request.instance {
+        Some(id) => super::instance_root(env, id).map(|root| (root, false)),
+        None => {
+            let name = request
+                .instance_name
+                .clone()
+                .filter(|name| !name.trim().is_empty())
+                .unwrap_or_else(|| convert::pack_stem(&request.pack));
+            let target = env
+                .layout
+                .data()
+                .join("instances")
+                .join(convert::dir_name(&name));
+            if target.exists() {
+                // 空目录（多半是上一次失败的残留）**可以复用**，否则重试永远报「已存在」
+                let mut entries = std::fs::read_dir(&target)
+                    .map_err(|error| format!("read instance dir failed: {error}"))?;
+                if entries.next().is_some() {
+                    return Err(format!(
+                        "directory already exists and is not empty: {}",
+                        target.display()
+                    ));
+                }
+            } else {
+                std::fs::create_dir_all(&target)
+                    .map_err(|error| format!("create dir failed: {error}"))?;
+            }
+            Ok((target, true))
+        }
+    }
+}
diff --git a/crates/presenter/src/host/addon/pack/tests.rs b/crates/presenter/src/host/addon/pack/tests.rs
new file mode 100644
index 0000000..b9127fe
--- /dev/null
+++ b/crates/presenter/src/host/addon/pack/tests.rs
@@ -0,0 +1,389 @@
+//! M113 的证据（都跑真管线 / 真 host，不用假数据）：
+//!
+//! | 用例 | 钉住什么 |
+//! |---|---|
+//! | [`bad_packs_get_a_named_diagnosis`] | 坏包必须有具名失败，不是静默、不是 panic |
+//! | [`preview_counts_match_the_written_report`] | 预检的 N/M 与最终报告**逐项相等** |
+//! | [`a_real_pack_runs_through_the_pipeline_end_to_end`] | 正常包能走完管线并落盘 |
+//! | [`chinese_instance_names_get_distinct_directories`] | 中文实例名不会塌成同一个目录 |
+//! | [`a_failed_new_instance_directory_can_be_reused_for_retry`] | 失败残留的空目录不挡重试 |
+//! | [`pack_epoch_is_per_host_and_is_its_own_counter`] | 代次按 host 分开，不再跨 host 串扰 |
+//! | [`a_failed_import_releases_the_in_flight_flag_and_keeps_install_cancel_intact`] | 早退路径放回「在跑」计数，取消安装仍是安装的取消 |
+//!
+//! 夹具（临时目录、写文件、泵 host）在 [`harness`]。
+
+mod harness;
+
+use harness::{pack_events, pump, pump_until, temp_dir, write};
+
+use unlucky_core::addon::export::{
+    export_instance, scan_instance, ExportRequest, InstanceSnapshot, OfflineCatalog,
+    DEFAULT_CONTENT_ROOTS,
+};
+
+use crate::dto::{ExportClassView, ExportRequestView, PackFormatView};
+
+#[test]
+fn bad_packs_get_a_named_diagnosis() {
+    let dir = temp_dir("badpack");
+
+    // ① 把文本文件改名成 .mrpack：连 zip 都不是
+    let fake = dir.join("fake.mrpack");
+    write(&fake, b"this is not a zip");
+    let probe = super::diagnose::of(&fake).expect("打不开的包必须有诊断");
+    assert!(
+        !probe.detail.is_empty(),
+        "诊断要给一句具体原因（不是空字符串）"
+    );
+    assert!(
+        probe.detail.to_lowercase().contains("archive") || probe.detail.contains("zip"),
+        "诊断要说清是哪一步失败：{}",
+        probe.detail
+    );
+
+    // ② 目录形态：有 overrides/、没有 manifest.json ⇒ 「像 CF，缺 manifest.json」
+    let dir_pack = dir.join("half");
+    write(&dir_pack.join("overrides").join("options.txt"), b"fov=90\n");
+    if let Some(probe) = super::diagnose::of(&dir_pack) {
+        assert!(
+            !probe.saw.is_empty(),
+            "看到了 overrides/ 就该说出来（saw 不能为空）"
+        );
+        if probe.looks_like.is_some() {
+            assert!(
+                !probe.missing.is_empty(),
+                "说「像某个格式」就必须说出缺哪个标记文件"
+            );
+        }
+    }
+}
+
+#[test]
+fn preview_counts_match_the_written_report() {
+    let dir = temp_dir("export-eq");
+    let root = dir.join("instance");
+    write(&root.join("mods").join("sodium.jar"), &[0x11; 4096]);
+    write(&root.join("mods").join("lithium.jar"), &[0x22; 2048]);
+    write(&root.join("mods").join("old.jar.disabled"), &[0x33; 512]);
+    write(&root.join("config").join("options.txt"), b"fov=90\n");
+    // 白名单之外的目录不该被扫（否则「将内联 N」会虚高）
+    write(&root.join("logs").join("latest.log"), b"noise\n");
+
+    let request = ExportRequestView {
+        instance: "survival".to_string(),
+        format: PackFormatView::Modrinth,
+        name: "Survival".to_string(),
+        version: "1.0.0".to_string(),
+        target: Some(dir.join("out.mrpack")),
+    };
+    let env_root = dir.join("data");
+    std::fs::create_dir_all(&env_root).expect("env");
+    let env = crate::host::HostEnv::at_root(&env_root);
+
+    // 预检（不写盘）
+    let preview = super::export::preview_of(&root, &env, &request);
+
+    // 真写盘：用同一套判据（离线目录 + 默认内容目录 + 直接给的快照）
+    let snapshot = InstanceSnapshot {
+        game_version: "1.20.1".to_string(),
+        loaders: Vec::new(),
+    };
+    let target = dir.join("out.mrpack");
+    let core_request = ExportRequest::new(
+        &root,
+        &target,
+        &unlucky_core::addon::pack::modrinth::MODRINTH,
+    )
+    .with_name("Survival")
+    .with_version("1.0.0")
+    .with_catalog(&OfflineCatalog)
+    .with_snapshot(&snapshot);
+    let report = export_instance(&core_request).expect("导出应当成功");
+
+    // 三个计数逐项相等（塔台要求：不是「大致对」）
+    assert_eq!(
+        preview.inline_count(),
+        report.inline_count(),
+        "内联条数不一致：预检 {} vs 报告 {}",
+        preview.inline_count(),
+        report.inline_count()
+    );
+    assert_eq!(
+        preview.skipped_count(),
+        report.skipped_count(),
+        "无法导出条数不一致"
+    );
+    assert_eq!(
+        preview.remote_count(),
+        report.remote_count(),
+        "远程引用条数不一致"
+    );
+
+    // 逐条：同一个路径在两边必须是同一个类
+    for file in &preview.files {
+        let written = report
+            .files
+            .iter()
+            .find(|candidate| candidate.path == file.path)
+            .unwrap_or_else(|| panic!("预检多出一条：{}", file.path));
+        let expected = match file.class {
+            ExportClassView::Remote => unlucky_core::addon::export::FileClass::Remote,
+            ExportClassView::Inline => unlucky_core::addon::export::FileClass::Inline,
+            ExportClassView::Skipped => unlucky_core::addon::export::FileClass::Skipped,
+        };
+        assert_eq!(written.class, expected, "{} 的归类不一致", file.path);
+    }
+
+    // 白名单外的 logs/ 不许进包（防「扫太宽」把预检数字弄虚）
+    assert!(
+        !report
+            .files
+            .iter()
+            .any(|file| file.path.starts_with("logs/")),
+        "logs/ 不该被扫进整合包"
+    );
+
+    // 同时钉一条：`scan_instance` 的口径就是预览用的那一套
+    let roots: Vec<String> = DEFAULT_CONTENT_ROOTS
+        .iter()
+        .map(|entry| (*entry).to_string())
+        .collect();
+    let (files, skipped) = scan_instance(&root, &roots);
+    assert_eq!(files.len(), preview.inline_count());
+    assert_eq!(skipped.len(), preview.skipped_count());
+
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn a_real_pack_runs_through_the_pipeline_end_to_end() {
+    // 真管线端到端：造一个 MultiMC 实例目录当「包」（目录形态不需要 zip 写入器），
+    // 走 `import::run` 的**真**路径，看事件流里有没有「进度 + 结果」、文件有没有落地。
+    let dir = temp_dir("import-e2e");
+    let source = dir.join("Better MC");
+    write(
+        &source.join("mmc-pack.json"),
+        br#"{"formatVersion": 1, "components": [
+            {"uid": "net.minecraft", "version": "1.20.1"},
+            {"uid": "net.fabricmc.fabric-loader", "version": "0.15.11"}]}"#,
+    );
+    write(&source.join(".minecraft/mods/sodium.jar"), &[0x11; 1024]);
+    write(&source.join(".minecraft/config/options.txt"), b"fov=90\n");
+
+    let data = dir.join("data");
+    std::fs::create_dir_all(&data).expect("data root");
+    let env = crate::host::HostEnv::at_root(&data);
+
+    let (tx, rx) = crate::host::job::channel();
+    let request = crate::dto::ImportRequestView {
+        pack: source,
+        instance: None,
+        instance_name: Some("Imported Pack".to_string()),
+        overwrite: false,
+    };
+    super::import::run(
+        &env,
+        &tx,
+        &request,
+        7,
+        std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false)),
+    );
+    drop(tx);
+
+    let mut progress = 0usize;
+    let mut report = None;
+    for task in rx.iter() {
+        match task {
+            crate::host::job::HostTask::Pack { event, epoch } => {
+                assert_eq!(epoch, 7, "代次必须原样带回（取消判定靠它）");
+                match *event {
+                    crate::dto::PackEvent::Progress(Some(_)) => progress += 1,
+                    crate::dto::PackEvent::Report(view) => report = Some(*view),
+                    other => panic!("意料之外的事件：{other:?}"),
+                }
+            }
+            other => panic!("意料之外的任务：{other:?}"),
+        }
+    }
+
+    assert!(progress > 0, "至少要有一条进度事件");
+    let report = report.expect("必须有结果事件");
+    assert_ne!(
+        report.status,
+        crate::dto::ImportStatusView::Failed,
+        "正常包不该失败：{:?}",
+        report.error
+    );
+    assert_eq!(
+        report.format,
+        Some(crate::dto::PackFormatView::Multimc),
+        "应当认成 MultiMC 格式"
+    );
+    assert!(
+        report.written() > 0,
+        "报告里要至少有写盘的文件：{:?}",
+        report.files
+    );
+    // 落盘位置以**报告里的 target** 为准（那是 host 真算出来的目录，界面显示的也是它）
+    let landed = &report.target;
+    assert!(
+        landed.join("mods/sodium.jar").is_file(),
+        "文件没有落到实例目录：{}",
+        landed.display()
+    );
+
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn chinese_instance_names_get_distinct_directories() {
+    // 复审 r1 P2-8：slug() 只留 ASCII，中文名会全塌成 `pack`，第二个就撞目录
+    let first = super::convert::dir_name("我的整合包");
+    let second = super::convert::dir_name("另一个整合包");
+    assert_ne!(first, second, "两个不同的中文名必须得到不同目录");
+    assert_eq!(
+        first,
+        super::convert::dir_name("我的整合包"),
+        "同一个名字要稳定（不然重试会漂到新目录）"
+    );
+    assert!(first.starts_with("pack-"), "退化时要留可读前缀：{first}");
+
+    // 判据与注释对齐（复审 r2 P2-2）：只含 ASCII 字母数字/空格/`-`/`_` ⇒ 保持原样
+    assert_eq!(super::convert::dir_name("Better-MC"), "Better-MC");
+    assert_eq!(
+        super::convert::dir_name("Better MC"),
+        "Better-MC",
+        "空格折成 `-`、**不加**哈希"
+    );
+    assert_eq!(
+        super::convert::dir_name("pack"),
+        "pack",
+        "名字就叫 pack 也保留"
+    );
+
+    // 折过**别的**字符（这里是 `.`）就必须补哈希，否则不同名字会撞同一个目录
+    let versioned = super::convert::dir_name("Survival 1.20.1");
+    assert!(versioned.starts_with("Survival-1-20-1-"), "{versioned}");
+    assert_ne!(versioned, "Survival-1-20-1", "折过 `.` 就要补哈希");
+}
+
+#[test]
+fn a_failed_new_instance_directory_can_be_reused_for_retry() {
+    // 复审 r1 P2-9：失败回滚留下空目录时会挡住重试
+    let dir = temp_dir("retry");
+    let data = dir.join("data");
+    std::fs::create_dir_all(&data).expect("data root");
+    let env = crate::host::HostEnv::at_root(&data);
+
+    let request = crate::dto::ImportRequestView {
+        pack: dir.join("whatever.mrpack"),
+        instance: None,
+        instance_name: Some("Retry Me".to_string()),
+        overwrite: false,
+    };
+
+    // 第一次：目录不存在 ⇒ 建出来
+    let (first, register) = super::import::target_of(&env, &request).expect("首次应当可以建目录");
+    assert!(register);
+    assert!(first.is_dir());
+
+    // 第二次（模拟上一次失败留下的空目录）⇒ 复用，而不是报「已存在」
+    let (second, _) = super::import::target_of(&env, &request).expect("空目录应当可复用");
+    assert_eq!(first, second);
+
+    // 目录里已经有东西 ⇒ 拒绝（不能往别人的实例里倒）
+    std::fs::write(second.join("marker.txt"), b"x").expect("write");
+    assert!(
+        super::import::target_of(&env, &request).is_err(),
+        "非空目录必须拒绝"
+    );
+
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn pack_epoch_is_per_host_and_is_its_own_counter() {
+    // 复审 r2 P3-6：代次**按 host** 分开（不再是跨 host 共享的裸静态量）。
+    // 两个 host（两个临时根）各 bump 一次，互不影响 —— 这正是并行测试串扰的根因。
+    let one = temp_dir("epoch-one");
+    let two = temp_dir("epoch-two");
+    let env_one = crate::host::HostEnv::at_root(one.join("data"));
+    let env_two = crate::host::HostEnv::at_root(two.join("data"));
+
+    let before_one = super::pack_epoch(&env_one);
+    let before_two = super::pack_epoch(&env_two);
+    super::bump_pack_epoch(&env_one);
+    assert_eq!(
+        super::pack_epoch(&env_one),
+        before_one.wrapping_add(1),
+        "自己这个 host 的代次 +1"
+    );
+    assert_eq!(
+        super::pack_epoch(&env_two),
+        before_two,
+        "**另一个** host 的代次不受影响（P3-6 的根因）"
+    );
+    assert_eq!(super::in_flight(&env_two), 0, "在跑计数也是每 host 一份");
+
+    let _ = std::fs::remove_dir_all(&one);
+    let _ = std::fs::remove_dir_all(&two);
+}
+
+#[test]
+fn a_failed_import_releases_the_in_flight_flag_and_keeps_install_cancel_intact() {
+    // 复审 r2 P2-1 的护栏：早退路径必须把「在跑」计数放回去，否则之后**下载页**的
+    // 「取消安装」会被当成导入取消（不发 `InstallCancelled`，还给内容库画一句假话）。
+    use crate::dto::{
+        AppCommand, AppEvent, Backend, CoreEvent, ImportRequestView, PackCommand, PackEvent,
+    };
+
+    let dir = temp_dir("inflight-guard");
+    let data = dir.join("data");
+    std::fs::create_dir_all(&data).expect("data root");
+    let host_env = crate::host::HostEnv::at_root(&data);
+    let mut host = crate::host::CoreHost::headless(host_env.clone());
+
+    // ① 派一次**必然早退**的导入：包文件不存在 ⇒ 探测当场失败，根本不进管线
+    host.dispatch(AppCommand::Pack(Box::new(PackCommand::Import(Box::new(
+        ImportRequestView {
+            pack: dir.join("missing.mrpack"),
+            instance: None,
+            instance_name: Some("Guess".to_string()),
+            overwrite: false,
+        },
+    )))));
+    let events = pump_until(&mut host, |all| {
+        pack_events(all)
+            .iter()
+            .any(|event| matches!(event, PackEvent::Probe(_)))
+    });
+    assert!(
+        pack_events(&events)
+            .iter()
+            .any(|event| matches!(event, PackEvent::Probe(_))),
+        "坏包必须给出探测诊断（而不是静默）；实际收到 {events:?}"
+    );
+    assert_eq!(
+        super::in_flight(&host_env),
+        0,
+        "早退之后「在跑」计数必须归零（RAII guard 负责，不靠手工 finished）"
+    );
+
+    // ② 此后下载页的「取消安装」必须照常发 `InstallCancelled`，且**不能**冒出 pack 的取消
+    host.dispatch(AppCommand::CancelInstall);
+    let events = pump(&mut host);
+    assert!(
+        events
+            .iter()
+            .any(|event| matches!(event, AppEvent::Core(CoreEvent::InstallCancelled))),
+        "没有导入在跑时，取消安装必须照常给回执（否则用户点了取消毫无反应）"
+    );
+    assert!(
+        !pack_events(&events)
+            .iter()
+            .any(|event| matches!(event, PackEvent::Cancelled)),
+        "此刻没有导入在跑，不该给内容库发「导入还在后台跑」"
+    );
+
+    let _ = std::fs::remove_dir_all(&dir);
+}
diff --git a/crates/presenter/src/host/addon/pack/tests/harness.rs b/crates/presenter/src/host/addon/pack/tests/harness.rs
new file mode 100644
index 0000000..4376f32
--- /dev/null
+++ b/crates/presenter/src/host/addon/pack/tests/harness.rs
@@ -0,0 +1,56 @@
+//! pack 用例的共用夹具：临时目录、文件写入、host 泵。
+//!
+//! 拆出去只为一件事：`tests.rs` 已经 429 行（超 400 硬线），而这些 helper 与任何一条断言无关。
+//! `tests.rs` 里各条用例的「抓得住什么」写在用例自己的注释里，这里只放机械动作。
+
+use std::path::PathBuf;
+
+/// 每个用例一个独立临时目录（用完删）。
+pub(super) fn temp_dir(name: &str) -> PathBuf {
+    let dir = std::env::temp_dir().join(format!("ull-m113-{name}-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).expect("temp dir");
+    dir
+}
+
+pub(super) fn write(path: &std::path::Path, bytes: &[u8]) {
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent).expect("parent");
+    }
+    std::fs::write(path, bytes).expect("write");
+}
+
+/// 泵一次 host：把后台任务收成事件并取走。
+pub(super) fn pump(host: &mut crate::host::CoreHost) -> Vec<crate::dto::AppEvent> {
+    use crate::dto::Backend;
+    host.tick(std::time::Duration::from_millis(1));
+    host.drain_events()
+}
+
+/// 泵到 `done` 为真（最多 ~3 s），返回期间收到的全部事件。
+pub(super) fn pump_until(
+    host: &mut crate::host::CoreHost,
+    done: impl Fn(&[crate::dto::AppEvent]) -> bool,
+) -> Vec<crate::dto::AppEvent> {
+    let mut all = Vec::new();
+    for _ in 0..600 {
+        all.extend(pump(host));
+        if done(&all) {
+            break;
+        }
+        std::thread::sleep(std::time::Duration::from_millis(5));
+    }
+    all
+}
+
+pub(super) fn pack_events(events: &[crate::dto::AppEvent]) -> Vec<crate::dto::PackEvent> {
+    events
+        .iter()
+        .filter_map(|event| match event {
+            crate::dto::AppEvent::Core(crate::dto::CoreEvent::Pack(inner)) => {
+                Some((**inner).clone())
+            }
+            _ => None,
+        })
+        .collect()
+}
diff --git a/crates/presenter/src/host/addon/sources.rs b/crates/presenter/src/host/addon/sources.rs
new file mode 100644
index 0000000..19bfd40
--- /dev/null
+++ b/crates/presenter/src/host/addon/sources.rs
@@ -0,0 +1,262 @@
+//! 两个站点的检索方言（M109）：把各自的 JSON 翻成 [`ContentHit`]。
+//!
+//! 两个站点在**同一件事上用的字段名完全不同**，所以这里每个站点一段、各自带注释：
+//!
+//! | 语义 | Modrinth `/v2/search` | CurseForge `/v1/mods/search` |
+//! |---|---|---|
+//! | 项目 id | `project_id`（base62） | `id`（数字） |
+//! | 标题 / 简介 | `title` / `description` | `name` / `summary` |
+//! | 下载量 | `downloads` | `downloadCount` |
+//! | 游戏版本 | `versions` | `latestFilesIndexes[].gameVersion` |
+//! | 加载器 | `categories` 里混着的 `fabric`/`forge`/… | `latestFilesIndexes[].modLoader`（数字枚举） |
+//!
+//! 加载器那一行是最容易抄错的地方：Modrinth 的 `categories` 同时装着 `optimization` 这种**分类标签**，
+//! 直接整份当加载器用，画面上就会多出「optimization」这种假加载器（`sources/tests` 钉住了这一条）。
+
+use serde_json::Value;
+
+use crate::dto::{
+    loader_facet, ContentHit, ContentKind, ContentQuery, ContentResults, ContentSource,
+};
+
+use super::super::env::HostEnv;
+use super::curseforge_ready;
+use super::http::{encode, get};
+
+/// Modrinth v2 的根（无需 key）。
+pub(super) const MODRINTH: &str = "https://api.modrinth.com/v2";
+/// CurseForge v1 的根（需要 `X-API-KEY`）。
+pub(super) const CURSEFORGE: &str = "https://api.curseforge.com/v1";
+/// CurseForge 的「Minecraft」gameId（官方固定值）。
+const CF_MINECRAFT: u32 = 432;
+
+/// 检索分派。
+pub(super) fn search(env: &HostEnv, query: &ContentQuery) -> Result<ContentResults, String> {
+    match query.source {
+        ContentSource::Modrinth => modrinth(env, query),
+        ContentSource::Curseforge => curseforge(env, query),
+    }
+}
+
+// --------------------------------------------------------------- Modrinth
+
+fn modrinth(env: &HostEnv, query: &ContentQuery) -> Result<ContentResults, String> {
+    let mut facets = vec![format!("[\"project_type:{}\"]", query.kind.modrinth_type())];
+    if let Some(version) = &query.game_version {
+        facets.push(format!("[\"versions:{version}\"]"));
+    }
+    if let Some(facet) = query.loader.and_then(loader_facet) {
+        facets.push(format!("[\"categories:{facet}\"]"));
+    }
+
+    let mut url = format!(
+        "{MODRINTH}/search?limit={}&offset={}&index={}&facets={}",
+        query.limit.min(100),
+        query.offset,
+        query.sort.modrinth_index(),
+        encode(&format!("[{}]", facets.join(",")))
+    );
+    if !query.text.trim().is_empty() {
+        url.push_str(&format!("&query={}", encode(query.text.trim())));
+    }
+
+    let body = get(env, &url, &[])?;
+    let json: Value = serde_json::from_str(&body)
+        .map_err(|error| format!("Modrinth 返回的不是合法 JSON：{error}"))?;
+    let hits = json
+        .get("hits")
+        .and_then(Value::as_array)
+        .ok_or_else(|| "Modrinth 返回里没有 hits 字段".to_string())?
+        .iter()
+        .map(modrinth_hit)
+        .collect::<Vec<_>>();
+
+    Ok(ContentResults {
+        query: query.clone(),
+        hits,
+        total: u32_of(&json, "total_hits"),
+        curseforge: curseforge_ready(),
+    })
+}
+
+/// 一条 Modrinth 命中项 → DTO（缺字段一律给空/零，**不**编造）。
+fn modrinth_hit(value: &Value) -> ContentHit {
+    let loaders = strings(value, "categories")
+        .into_iter()
+        // `categories` 混着加载器与分类标签：只留已知的四个加载器
+        .filter(|tag| matches!(tag.as_str(), "fabric" | "forge" | "neoforge" | "quilt"))
+        .collect();
+
+    ContentHit {
+        id: text(value, "project_id"),
+        slug: text(value, "slug"),
+        title: text(value, "title"),
+        summary: text(value, "description"),
+        author: text(value, "author"),
+        downloads: u64_of(value, "downloads"),
+        updated: date_part(&text(value, "updated")),
+        source: ContentSource::Modrinth,
+        game_versions: strings(value, "versions"),
+        loaders,
+        icon: optional_text(value, "icon_url"),
+    }
+}
+
+// --------------------------------------------------------------- CurseForge
+
+fn curseforge(env: &HostEnv, query: &ContentQuery) -> Result<ContentResults, String> {
+    let Some(key) = super::curseforge_key() else {
+        return Err("CurseForge 需要 API key（ULL_CF_API_KEY 未设置）".to_string());
+    };
+    let mut url = format!(
+        "{CURSEFORGE}/mods/search?gameId={CF_MINECRAFT}&classId={}&index={}&pageSize={}&sortField={}&sortOrder=desc",
+        query.kind.curseforge_class(),
+        query.offset,
+        query.limit.min(50),
+        query.sort.curseforge_field()
+    );
+    if !query.text.trim().is_empty() {
+        url.push_str(&format!("&searchFilter={}", encode(query.text.trim())));
+    }
+    if let Some(version) = &query.game_version {
+        url.push_str(&format!("&gameVersion={}", encode(version)));
+    }
+
+    let body = get(env, &url, &[("x-api-key", key.as_str())])?;
+    let json: Value = serde_json::from_str(&body)
+        .map_err(|error| format!("CurseForge 返回的不是合法 JSON：{error}"))?;
+    let hits = json
+        .get("data")
+        .and_then(Value::as_array)
+        .ok_or_else(|| "CurseForge 返回里没有 data 字段".to_string())?
+        .iter()
+        .map(curseforge_hit)
+        .collect::<Vec<_>>();
+
+    Ok(ContentResults {
+        query: query.clone(),
+        hits,
+        total: json
+            .get("pagination")
+            .map(|pagination| u64_of(pagination, "totalCount"))
+            .and_then(|value| u32::try_from(value).ok())
+            .unwrap_or(0),
+        curseforge: true,
+    })
+}
+
+/// 一条 CF 命中项 → DTO。加载器只能从 `latestFilesIndexes[].modLoader` 的数字枚举反推。
+fn curseforge_hit(value: &Value) -> ContentHit {
+    let mut game_versions: Vec<String> = Vec::new();
+    let mut loaders: Vec<String> = Vec::new();
+    if let Some(indexes) = value.get("latestFilesIndexes").and_then(Value::as_array) {
+        for entry in indexes {
+            if let Some(version) = entry.get("gameVersion").and_then(Value::as_str) {
+                if !game_versions.iter().any(|item| item == version) {
+                    game_versions.push(version.to_string());
+                }
+            }
+            if let Some(loader) = entry
+                .get("modLoader")
+                .and_then(Value::as_u64)
+                .and_then(curseforge_loader)
+            {
+                if !loaders.iter().any(|item| item == loader) {
+                    loaders.push(loader.to_string());
+                }
+            }
+        }
+    }
+    let author = value
+        .get("authors")
+        .and_then(Value::as_array)
+        .and_then(|items| items.first())
+        .map(|entry| text(entry, "name"))
+        .unwrap_or_default();
+
+    ContentHit {
+        id: value
+            .get("id")
+            .and_then(Value::as_u64)
+            .map(|id| id.to_string())
+            .unwrap_or_default(),
+        slug: text(value, "slug"),
+        title: text(value, "name"),
+        summary: text(value, "summary"),
+        author,
+        downloads: u64_of(value, "downloadCount"),
+        updated: date_part(&text(value, "dateModified")),
+        source: ContentSource::Curseforge,
+        game_versions,
+        loaders,
+        icon: value
+            .get("logo")
+            .and_then(|logo| logo.get("url"))
+            .and_then(Value::as_str)
+            .map(ToString::to_string),
+    }
+}
+
+/// CF 的 `modLoader` 枚举 → Modrinth 口径的 loader 名（1 Forge / 4 Fabric / 5 Quilt / 6 NeoForge）。
+pub(super) fn curseforge_loader(raw: u64) -> Option<&'static str> {
+    match raw {
+        1 => Some("forge"),
+        4 => Some("fabric"),
+        5 => Some("quilt"),
+        6 => Some("neoforge"),
+        _ => None,
+    }
+}
+
+// --------------------------------------------------------------- 小工具
+
+/// 取字符串字段（缺 / 类型不对 ⇒ 空串）。
+fn text(value: &Value, key: &str) -> String {
+    value
+        .get(key)
+        .and_then(Value::as_str)
+        .unwrap_or_default()
+        .to_string()
+}
+
+/// 取可选字符串字段（空串也当没有——站点会给 `""` 表示没图）。
+fn optional_text(value: &Value, key: &str) -> Option<String> {
+    value
+        .get(key)
+        .and_then(Value::as_str)
+        .filter(|text| !text.is_empty())
+        .map(ToString::to_string)
+}
+
+/// 取字符串数组（缺 / 类型不对 ⇒ 空 vec）。
+fn strings(value: &Value, key: &str) -> Vec<String> {
+    value
+        .get(key)
+        .and_then(Value::as_array)
+        .map(|items| {
+            items
+                .iter()
+                .filter_map(|item| item.as_str().map(ToString::to_string))
+                .collect()
+        })
+        .unwrap_or_default()
+}
+
+fn u64_of(value: &Value, key: &str) -> u64 {
+    value.get(key).and_then(Value::as_u64).unwrap_or(0)
+}
+
+fn u32_of(value: &Value, key: &str) -> u32 {
+    u32::try_from(u64_of(value, key)).unwrap_or(0)
+}
+
+/// ISO-8601 → 日期部分（`2024-05-01T…` → `2024-05-01`；短串原样返回）。
+pub(super) fn date_part(raw: &str) -> String {
+    raw.get(..10).unwrap_or(raw).to_string()
+}
+
+/// 类型名只用来钉住「四条侧栏都在」的常量没被改乱（检索本身按 `kind` 走 facet）。
+#[must_use]
+pub(super) fn all_kinds() -> [ContentKind; 4] {
+    ContentKind::ALL
+}
diff --git a/crates/presenter/src/host/addon/tests.rs b/crates/presenter/src/host/addon/tests.rs
new file mode 100644
index 0000000..0d4a135
--- /dev/null
+++ b/crates/presenter/src/host/addon/tests.rs
@@ -0,0 +1,85 @@
+//! 内容库宿主的守门测试（M109）：编码、文件名穿越、退避判定、两个站点的方言映射。
+
+use std::time::Duration;
+
+use super::http::{encode, retry_after, retryable};
+use super::install::safe_file_name;
+use super::sources::{all_kinds, curseforge_loader, date_part};
+use crate::dto::ContentKind;
+
+#[test]
+fn percent_encoding_keeps_the_query_readable_and_escapes_the_rest() {
+    assert_eq!(encode("1.20.1"), "1.20.1");
+    assert_eq!(
+        encode("[\"versions:1.20.1\"]"),
+        "%5B%22versions%3A1.20.1%22%5D"
+    );
+    assert_eq!(encode("中文"), "%E4%B8%AD%E6%96%87");
+    assert_eq!(encode("a b"), "a%20b");
+}
+
+#[test]
+fn file_names_never_carry_a_path() {
+    // 抓得住：站点给的 `../../evil.jar` 落到实例目录之外（穿越）。
+    assert_eq!(safe_file_name("sodium.jar"), "sodium.jar");
+    assert_eq!(safe_file_name("../../evil.jar"), "evil.jar");
+    assert_eq!(safe_file_name("mods\\jei.jar"), "jei.jar");
+    assert_eq!(safe_file_name(".."), "download.bin");
+    assert_eq!(safe_file_name(""), "download.bin");
+}
+
+#[test]
+fn dates_are_sliced_not_guessed() {
+    assert_eq!(date_part("2024-05-01T12:00:00Z"), "2024-05-01");
+    assert_eq!(date_part("2024-05"), "2024-05");
+    assert_eq!(date_part(""), "");
+}
+
+#[test]
+fn only_rate_limited_and_transient_failures_are_retried() {
+    assert!(retryable("HTTP 429 (retry_after=Some(3))"));
+    assert!(retryable("HTTP 503 (retry_after=None)"));
+    assert!(!retryable("HTTP 404 (retry_after=None)"));
+    assert!(
+        !retryable("HTTP 401 (retry_after=None)"),
+        "密钥错重试只会更糟"
+    );
+}
+
+#[test]
+fn retry_after_prefers_the_server_and_falls_back_to_exponential() {
+    assert_eq!(
+        retry_after("HTTP 429 (retry_after=Some(7))", 0),
+        Duration::from_secs(7)
+    );
+    assert_eq!(
+        retry_after("HTTP 429 (retry_after=None)", 0),
+        Duration::from_secs(1)
+    );
+    assert_eq!(
+        retry_after("HTTP 429 (retry_after=None)", 2),
+        Duration::from_secs(4)
+    );
+    // 服务端要得再多也不等超过 30s（交互与截图不能被一次退避挂死）
+    assert_eq!(
+        retry_after("HTTP 429 (retry_after=Some(900))", 0),
+        Duration::from_secs(30)
+    );
+}
+
+#[test]
+fn curseforge_loader_ids_follow_the_official_enum() {
+    assert_eq!(curseforge_loader(1), Some("forge"));
+    assert_eq!(curseforge_loader(4), Some("fabric"));
+    assert_eq!(curseforge_loader(5), Some("quilt"));
+    assert_eq!(curseforge_loader(6), Some("neoforge"));
+    assert_eq!(curseforge_loader(99), None);
+}
+
+#[test]
+fn the_four_content_kinds_are_the_four_side_entries() {
+    assert_eq!(
+        all_kinds().map(ContentKind::slug),
+        ["modpack", "mod", "resourcepack", "shader"]
+    );
+}
diff --git a/crates/presenter/src/host/cancel_tests.rs b/crates/presenter/src/host/cancel_tests.rs
new file mode 100644
index 0000000..c044e1b
--- /dev/null
+++ b/crates/presenter/src/host/cancel_tests.rs
@@ -0,0 +1,344 @@
+//! 取消安装的**实测装置**（M105）。
+//!
+//! ## 为什么这条测试要真起一次安装
+//!
+//! 「点取消没反应」有三种可能的断点，读码分不出来：
+//! ① 按钮/消息链断了（不派 `AppCommand::CancelInstall`）；
+//! ② host 收下取消后，**还在跑的任务**继续发进度事件，把面板又点亮（面板闪一下又回来）；
+//! ③ 取消根本停不下传输（M105 之前 core 的 `execute` 没有取消入参，下载线程会跑到段尾）。
+//!
+//! ①② 能靠单测的假事件流抓；③ 只有真起一次安装、真取消、真量「取消之后还在发生什么」才抓得到。
+//! 修完之后 ①②③ 都有守门：① 是 app 层的消息测试，② 是下面那条 CI 可跑的
+//! [`progress_from_a_cancelled_job_is_dropped`]，③ 就是本用例（真网络）。
+//!
+//! 所以这一条是**真网络**用例：`#[ignore]` 守着（CI 不跑），人工跑：
+//!
+//! ```text
+//! cargo test -p unlucky-presenter --test '' -- real_install --ignored --nocapture
+//! # 或（等价，本用例在 lib 测试里）
+//! cargo test -p unlucky-presenter real_install_cancel -- --ignored --nocapture
+//! ```
+//!
+//! ## 它量什么（三样里能抓住的两样）
+//!
+//! | 现象 | 怎么量 | 抓住什么 / 抓不住什么 |
+//! |---|---|---|
+//! | 进度还在推进 | 取消后收到的 `InstallProgress(Some)` 条数与 `files_done` 增量 | 抓得住「UI 侧还在被事件喂」；抓不住事件之外的后台动作 |
+//! | 断点文件 | `<game>/**/*.ullpart*` 的总字节：取消时 vs 取消后 20 s，**并且**绝对值必须是 0 | 抓得住「还在写」与「留了半截垃圾」；抓不住「线程还活着」（`.ullpart` 不再长也可能是卡在等响应） |
+//! | 半成品变成品 | `<game>/versions/<id>/<id>.json`（版本清单）与 `<launcher_home>/config/profiles.json`（**实例登记的唯一真相源**，`LauncherLayout::profiles_config()`） | 抓得住「取消后仍然落了成品 / 登记了实例」；抓不住「用户看不到的临时目录」 |
+//!
+//! 线程与 socket 两样**抓不住**（没有可移植的查询口，见 `probe` 一节），所以这里不用它当判据。
+
+use std::path::{Path, PathBuf};
+use std::time::{Duration, Instant};
+
+use crate::dto::{AppCommand, AppEvent, Backend, CoreEvent, InstallProgressView, InstallStage};
+
+use super::job::HostTask;
+use super::{env::HostEnv, CoreHost};
+
+/// 实测用的数据根（放在固定位置而不是系统 temp：便于人工复跑时留着看）。
+fn root() -> PathBuf {
+    std::env::temp_dir().join("ull-m105-cancel")
+}
+
+/// 递归数 `.ullpart` 家族（中间文件 + 续传元数据）的总字节。
+///
+/// 目录很小（只有本次安装写的那几层），所以裸递归够用；读不动的一律当 0
+/// （量的是趋势，不是精确值）。
+fn part_bytes(dir: &Path) -> u64 {
+    let Ok(entries) = std::fs::read_dir(dir) else {
+        return 0;
+    };
+    let mut total = 0;
+    for entry in entries.flatten() {
+        let path = entry.path();
+        let Ok(meta) = entry.metadata() else {
+            continue;
+        };
+        if meta.is_dir() {
+            total += part_bytes(&path);
+        } else if let Some(name) = path.file_name().and_then(|name| name.to_str()) {
+            // 中间文件 `<name>.ullpart[-<pid>-<seq>]` 与它的元数据 `.ullmeta.json`
+            if name.contains(".ullpart") {
+                total += meta.len();
+            }
+        }
+    }
+    total
+}
+
+/// 一次 tick 后抽干事件，返回本轮的全部事件。
+fn pump(host: &mut CoreHost, wait: Duration) -> Vec<AppEvent> {
+    host.tick(wait);
+    host.drain_events()
+}
+
+/// 事件里的安装进度（别的变体一概忽略）。
+fn progress(event: &AppEvent) -> Option<&crate::dto::InstallProgressView> {
+    match event {
+        AppEvent::Core(CoreEvent::InstallProgress(Some(progress))) => Some(progress),
+        _ => None,
+    }
+}
+
+/// **实测主用例**：真起一次安装 → 取消 → 量取消之后还在发生什么。
+///
+/// 版本用环境变量 `ULL_CANCEL_VERSION` 覆盖（默认 `1.20.1`：文件多、总量够大，
+/// 取消点之后还有一大截没下完，于是「取消后还在跑」一眼可见）。
+#[test]
+#[ignore = "真网络：真起一次安装再取消（需要 ULL_CANCEL_VERSION 指定的版本可下载）"]
+fn real_install_cancel_stops_progress_and_leaves_no_half_product() {
+    let version = std::env::var("ULL_CANCEL_VERSION").unwrap_or_else(|_| "1.20.1".to_string());
+    let root = root();
+    std::fs::remove_dir_all(&root).ok();
+
+    let env = HostEnv::at_root(&root);
+    let game = env.game.root().to_path_buf();
+    // 实例登记的真相源是 `<launcher_home>/config/profiles.json`（`LauncherLayout::profiles_config()`），
+    // 不是 `<game>/instances` —— 后者根本不存在，探它等于什么都没探（复审 P2-3 第 2 点）。
+    let launcher = env.layout.clone();
+    let mut host = CoreHost::headless(env);
+
+    // ---- 起点：取消之前 ----
+    host.dispatch(AppCommand::InstallVersion(version.clone()));
+    let started = Instant::now();
+    let mut before_cancel_progress = 0_usize;
+    let mut done_at_cancel = 0_u64;
+    // 等到「真在下载」（files_done ≥ 2）再取消：取消得太早会落在 Planning/解析阶段，
+    // 那种取消本来就只是阶段边界停，证明不了下载中取消的行为。
+    while started.elapsed() < Duration::from_secs(180) {
+        for event in pump(&mut host, Duration::from_millis(100)) {
+            if let Some(progress) = progress(&event) {
+                before_cancel_progress += 1;
+                done_at_cancel = done_at_cancel.max(progress.files_done);
+            }
+        }
+        if done_at_cancel >= 2 {
+            break;
+        }
+    }
+    assert!(
+        done_at_cancel >= 2,
+        "180 s 内没进到下载阶段（files_done={done_at_cancel}）：网络或版本号有问题，先让这条能跑起来"
+    );
+    let parts_at_cancel = part_bytes(&game);
+
+    // ---- 取消 ----
+    host.dispatch(AppCommand::CancelInstall);
+    let cancelled = Instant::now();
+    let mut after: Vec<(f32, u64, InstallStage, u64)> = Vec::new();
+    for event in host.drain_events() {
+        if let Some(progress) = progress(&event) {
+            after.push((
+                cancelled.elapsed().as_secs_f32(),
+                progress.files_done,
+                progress.stage,
+                part_bytes(&game),
+            ));
+        }
+    }
+
+    // ---- 取消之后 20 s：还会不会被喂进度、断点文件还会不会长 ----
+    //
+    // 每秒采一次 `.ullpart` 总字节：判据不是「取消那一刻的瞬时值」，而是**它在 5 s 之后
+    // 不再变高**——在飞的那个文件本来就要多活一个数据块（取消延迟的定义），
+    // 5 s 是给它留的余量（远超一个数据块）。
+    let settle = Duration::from_secs(5);
+    let mut latest = None;
+    let mut samples: Vec<(f32, u64)> = Vec::new();
+    let mut next_sample = Duration::from_secs(1);
+    while cancelled.elapsed() < Duration::from_secs(20) {
+        for event in pump(&mut host, Duration::from_millis(100)) {
+            if let Some(progress) = progress(&event) {
+                latest = Some(progress.clone());
+                after.push((
+                    cancelled.elapsed().as_secs_f32(),
+                    progress.files_done,
+                    progress.stage,
+                    part_bytes(&game),
+                ));
+            }
+        }
+        let elapsed = cancelled.elapsed();
+        if elapsed >= next_sample {
+            samples.push((elapsed.as_secs_f32(), part_bytes(&game)));
+            next_sample += Duration::from_secs(1);
+        }
+        std::thread::sleep(Duration::from_millis(20));
+    }
+    let parts_after = part_bytes(&game);
+    let done_after = latest
+        .as_ref()
+        .map_or(done_at_cancel, |view| view.files_done);
+
+    // ---- 取证：日志行 ----
+    eprintln!("[cancel-test] root={}", root.display());
+    eprintln!(
+        "[cancel-test] 取消前：进度事件 {before_cancel_progress} 条，files_done={done_at_cancel}，.ullpart 合计 {parts_at_cancel} 字节"
+    );
+    eprintln!(
+        "[cancel-test] 取消后 20 s：进度事件 {} 条，files_done={done_after}（+{} 个文件），.ullpart 合计 {parts_after} 字节（{:+}）",
+        after.len(),
+        done_after.saturating_sub(done_at_cancel),
+        i64::try_from(parts_after).unwrap_or(i64::MAX) - i64::try_from(parts_at_cancel).unwrap_or(i64::MAX)
+    );
+    for (at, parts) in &samples {
+        eprintln!("[cancel-test]   t={at:>5.1}s ullpart={parts}");
+    }
+    for (index, (at, done, stage, parts)) in after.iter().enumerate().take(12) {
+        eprintln!(
+            "[cancel-test]   #{index} +{at:.2}s files_done={done} stage={stage:?} ullpart={parts}"
+        );
+    }
+    if after.len() > 12 {
+        eprintln!("[cancel-test]   …（另有 {} 条）", after.len() - 12);
+    }
+
+    // ---- 断点文件 / 临时目录 / 成品三样 ----
+    // 版本 JSON 只在「全量就绪」才落盘（`execute` 的 complete 判定）；
+    // 实例登记在 `run()` 的最后一步，取消后不该登记（读 profiles.json 这份唯一真相源）。
+    let version_json = game
+        .join("versions")
+        .join(&version)
+        .join(format!("{version}.json"));
+    let profiles = unlucky_core::game::install::instance::read_profiles(&launcher)
+        .expect("profiles.json 应可读（不存在 = 空清单）");
+    eprintln!(
+        "[cancel-test] 版本清单{} / profiles.json 里 {} 条实例",
+        if version_json.is_file() {
+            "已落盘"
+        } else {
+            "未落盘"
+        },
+        profiles.profiles.len()
+    );
+
+    // ---- 判据（修好之后必须成立的三条） ----
+    assert!(
+        after.is_empty(),
+        "取消之后还在被喂进度事件（{} 条）：面板会被重新点亮 = 用户看到的「点了没反应」",
+        after.len()
+    );
+    let settled = samples
+        .iter()
+        .find(|(at, _)| Duration::from_secs_f32(*at) >= settle)
+        .map(|(_, parts)| *parts)
+        .unwrap_or(parts_at_cancel);
+    let grew = samples
+        .iter()
+        .filter(|(at, _)| Duration::from_secs_f32(*at) >= settle)
+        .map(|(_, parts)| *parts)
+        .max()
+        .map_or(0, |peak| peak.saturating_sub(settled));
+    assert_eq!(
+        grew, 0,
+        "取消 {settle:?} 之后断点文件还在长（+{grew} 字节）：下载没有真的停"
+    );
+    assert_eq!(
+        parts_after, 0,
+        "取消之后还留着 {parts_after} 字节的 `.ullpart`：半截垃圾没清掉（D21 要的就是「清掉或标清楚」）"
+    );
+    assert!(
+        profiles.profiles.is_empty(),
+        "取消之后仍然登记了实例（profiles.json 有 {} 条）：半成品被记成成品",
+        profiles.profiles.len()
+    );
+    assert!(
+        !version_json.is_file(),
+        "取消之后仍然落了版本清单：半成品被记成「已安装」"
+    );
+
+    std::fs::remove_dir_all(&root).ok();
+}
+
+// --------------------------------------------------------------- CI 可跑的守门
+
+/// 一条安装进度快照（够画面板就行）。
+fn progress_snapshot(files_done: u64) -> InstallProgressView {
+    InstallProgressView {
+        version: "1.20.1".to_string(),
+        stage: InstallStage::Downloading,
+        files_done,
+        files_total: 512,
+        ..InstallProgressView::new()
+    }
+}
+
+/// **「点了取消没反应」的真根因**：取消之后旧任务的进度事件还在往回灌。
+///
+/// 现场：用户点「取消安装」→ host 收下取消、清 `install`、发 `InstallProgress(None)`（面板回弹），
+/// 但**后台线程还在跑**（core 的下载段不是瞬停的），它每下完一个文件就发一条
+/// `HostTask::Install`。没有代次的话这条事件照样被翻译成 `InstallProgress(Some(..))`，
+/// 面板立刻又被点亮 —— 用户看到的就是「取消按钮点了没反应」。
+///
+/// 抓得住：代次不符的 `Install` / `InstallDone` 被丢掉（面板不复燃、也不清掉新一轮的取消句柄）。
+/// 抓不住：真网络的取消延迟（那条在 `real_install_cancel_*`，`#[ignore]` 守着要手动跑）。
+#[test]
+fn progress_from_a_cancelled_job_is_dropped() {
+    let dir = std::env::temp_dir().join(format!("ull-cancel-epoch-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    let mut host = CoreHost::headless(HostEnv::at_root(&dir));
+
+    // 开工：拿当代次
+    let epoch = host.next_install_epoch();
+    host.handle(HostTask::Install {
+        progress: Box::new(progress_snapshot(3)),
+        epoch,
+    });
+    let live: Vec<AppEvent> = host.drain_events();
+    assert!(
+        live.iter()
+            .any(|event| matches!(event, AppEvent::Core(CoreEvent::InstallProgress(Some(_))))),
+        "当代次的事件必须照常点亮面板"
+    );
+
+    // 取消
+    host.dispatch(AppCommand::CancelInstall);
+    let cancelled: Vec<AppEvent> = host.drain_events();
+    assert!(
+        cancelled
+            .iter()
+            .any(|event| matches!(event, AppEvent::Core(CoreEvent::InstallProgress(None)))),
+        "取消要立刻把面板收回（不等后台）"
+    );
+    assert!(
+        !cancelled
+            .iter()
+            .any(|event| matches!(event, AppEvent::Core(CoreEvent::InstallProgress(Some(_))))),
+        "取消本身不该重新点亮面板"
+    );
+
+    // 旧任务继续发进度（现场就是这样）——必须被丢掉
+    host.handle(HostTask::Install {
+        progress: Box::new(progress_snapshot(4)),
+        epoch,
+    });
+    host.handle(HostTask::InstallDone {
+        progress: Box::new(progress_snapshot(512)),
+        result: Err("已取消".to_string()),
+        epoch,
+    });
+    let after: Vec<AppEvent> = host.drain_events();
+    assert!(
+        after.is_empty(),
+        "取消之后旧任务的事件必须一条都不出（实际 {} 条）：出了就会把面板重新点亮",
+        after.len()
+    );
+
+    // 新一轮安装的代次是新的：它的进度照常生效
+    let fresh = host.next_install_epoch();
+    assert_ne!(fresh, epoch, "新一轮开工必须换代次");
+    host.handle(HostTask::Install {
+        progress: Box::new(progress_snapshot(1)),
+        epoch: fresh,
+    });
+    assert!(
+        host.drain_events()
+            .iter()
+            .any(|event| matches!(event, AppEvent::Core(CoreEvent::InstallProgress(Some(_))))),
+        "新一轮的进度要能点亮面板（不能把代次守卫写成「一律丢弃」）"
+    );
+
+    std::fs::remove_dir_all(&dir).ok();
+}
diff --git a/crates/presenter/src/host/dispatch.rs b/crates/presenter/src/host/dispatch.rs
new file mode 100644
index 0000000..533f15c
--- /dev/null
+++ b/crates/presenter/src/host/dispatch.rs
@@ -0,0 +1,248 @@
+//! `CoreHost::dispatch` 的指令实现（从 `host/mod.rs` 拆出，守 400 行上限）。
+//!
+//! 父模块的私有字段对子模块可见，所以这里直接读写 `self.env` / `self.tx` 等。
+
+use crate::dto::{
+    AccountNoticeCode, AppCommand, Backend, CoreEvent, CreateRequest, LoaderKind, PackEvent,
+};
+use crate::toast::ToastKind;
+
+use super::accounts::{self, LoginJob};
+use super::{
+    addon, game, install, java, launch, loader_versions, logs, settings, versions, CoreHost,
+};
+
+impl CoreHost {
+    /// 下发一条用户意图（`Backend::dispatch` 的实现体）。
+    pub(super) fn dispatch_command(&mut self, command: AppCommand) {
+        self.dispatch_inner(command);
+    }
+}
+impl CoreHost {
+    /// 指令分发（见 `dispatch_command`）。
+    fn dispatch_inner(&mut self, command: AppCommand) {
+        match command {
+            AppCommand::RefreshAll => self.refresh_all(),
+            AppCommand::LaunchInstance(id) => self.start_launch(&id),
+            AppCommand::StopInstance(id) => match self.running_pid(&id) {
+                Some(pid) => match launch::stop(pid) {
+                    Ok(()) => self.toast(ToastKind::Info, "已请求停止游戏进程"),
+                    Err(reason) => self.toast(ToastKind::Error, reason),
+                },
+                None => self.toast(ToastKind::Warn, "这个实例当前没有在跑"),
+            },
+            AppCommand::ListVersions(_) => versions::spawn_list(self.env.clone(), self.tx.clone()),
+            AppCommand::ListLoaderVersions { kind, mc_version } => {
+                loader_versions::spawn_list(self.env.clone(), self.tx.clone(), kind, mc_version);
+            }
+            AppCommand::InstallVersion(version) => {
+                let cancel = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
+                self.install_cancel = Some(std::sync::Arc::clone(&cancel));
+                let epoch = self.next_install_epoch();
+                install::spawn_install(
+                    self.env.clone(),
+                    self.tx.clone(),
+                    CreateRequest {
+                        name: version.clone(),
+                        version,
+                        loader: LoaderKind::Vanilla,
+                        loader_version: String::new(),
+                    },
+                    cancel,
+                    epoch,
+                );
+            }
+            AppCommand::CreateInstance(request) => {
+                let cancel = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
+                self.install_cancel = Some(std::sync::Arc::clone(&cancel));
+                let epoch = self.next_install_epoch();
+                install::spawn_install(self.env.clone(), self.tx.clone(), request, cancel, epoch);
+            }
+            AppCommand::CancelInstall => {
+                // 取消的三级语义（M105 实测后定稿，见 `install::CANCELLED`）：
+                // ① **面板立刻收回**（不等后台，用户点了就有反应）；
+                // ② **作废旧任务的代次**：后台线程是异步停的（取消延迟 = 一个数据块），
+                //    它带回来的进度事件一律因代次不符被 `handle` 丢掉——面板不会被重新点亮。
+                //    这是「点了没反应」的真根因：以前生效了又被旧事件盖回去；
+                // ③ 后台线程经 `install::run` 的取消检查停在段边界、**绝不登记实例**，
+                //    core 的 `execute_with_cancel` 还会就地掐断在飞的那个文件。
+                //
+                // 为什么不在这里 join 后台线程：UI 线程绝不能为了「等它停」而阻塞
+                // （一个数据块的延迟在人眼下就是「立刻」，但足以让 UI 卡住一帧以上）。
+                if let Some(cancel) = &self.install_cancel {
+                    cancel.store(true, std::sync::atomic::Ordering::SeqCst);
+                }
+                // M113: import/export —— 同一块面板的「取消」对导入也生效：立标记 + 作废 pack 代次
+                // 返回值告诉我们「刚才有没有导入在跑」：有的话**不能**再发 install 那条取消信号
+                // （它说的是「安装已取消、实例未创建」，而导入会在后台跑完并登记实例）。
+                let pack_was_running = addon::cancel_pack(&self.env);
+                if pack_was_running {
+                    self.send(CoreEvent::Pack(Box::new(PackEvent::Cancelled)));
+                }
+                self.install_epoch = self.install_epoch.wrapping_add(1);
+                self.install = None;
+                self.send(CoreEvent::InstallProgress(None));
+                // 只发信号、不发文案（复审 P2-2）：presenter 没有 i18n 依赖，
+                // 写死的中文会和页面语言打架。提示语由 app 层按 `Key` 现求。
+                // 导入在跑时不发这条：下载页那条文案说的是「实例未创建」，对导入是撒谎。
+                if !pack_was_running {
+                    self.send(CoreEvent::InstallCancelled);
+                }
+            }
+            AppCommand::SetIsolation { id, mode } => {
+                match game::set_isolation(&self.env, &id, &mode) {
+                    Ok(()) => {
+                        self.toast(ToastKind::Success, "隔离档位已更新");
+                        self.refresh_instances();
+                    }
+                    Err(reason) => self.toast(ToastKind::Error, reason),
+                }
+            }
+            AppCommand::RefreshLogSessions => {
+                self.send(CoreEvent::LogSessionsChanged(logs::sessions(&self.env)));
+            }
+            AppCommand::OpenLogSession(id) => self.open_session(&id),
+            AppCommand::ImportCrashLog(path) => match logs::analyze_crash_file(&path) {
+                Ok((label, report)) => {
+                    self.send(CoreEvent::DiagnosisReady(report));
+                    self.toast(ToastKind::Info, label);
+                }
+                Err(reason) => self.toast(ToastKind::Warn, reason),
+            },
+            // 账户增删切：结果走**页面横幅**（`AccountNoticeChanged`），不发 toast——
+            // app-iced 不渲染 toast，发出去等于用户什么都看不到（复审 r1 P2-2）。
+            AppCommand::AddOfflineAccount(name) => match accounts::add_offline(&self.env, &name) {
+                Ok(display) => {
+                    self.notice(AccountNoticeCode::Added, &display, "");
+                    self.refresh_accounts();
+                }
+                Err(failure) => {
+                    self.notice_failure(failure, &name);
+                    self.refresh_accounts();
+                }
+            },
+            AppCommand::RemoveAccount(key) => match accounts::remove(&self.env, &key) {
+                Ok(display) => {
+                    if self.active_account.as_deref() == Some(key.as_str()) {
+                        self.active_account = None;
+                    }
+                    self.notice(AccountNoticeCode::Removed, &display, "");
+                    self.refresh_accounts();
+                }
+                Err(failure) => {
+                    self.notice_failure(failure, &key);
+                    self.refresh_accounts();
+                }
+            },
+            AppCommand::SwitchAccount(id) => {
+                let name = self
+                    .accounts
+                    .iter()
+                    .find(|account| account.id == id)
+                    .map_or_else(|| id.clone(), |account| account.name.clone());
+                self.active_account = Some(id);
+                self.refresh_accounts();
+                self.notice(AccountNoticeCode::Switched, &name, "");
+            }
+            AppCommand::DismissAccountNotice => {
+                self.send(CoreEvent::AccountNoticeChanged(None));
+            }
+            AppCommand::StartDeviceLogin => {
+                self.login = Some(LoginJob::new());
+                let job = self.login.clone().unwrap_or_default();
+                self.send(CoreEvent::DeviceLoginChanged(crate::dto::DeviceLoginView {
+                    phase: crate::dto::DeviceLoginPhase::Requesting,
+                    message: "正在向微软申请设备码…".to_string(),
+                    ..crate::dto::DeviceLoginView::new()
+                }));
+                accounts::start_login(self.env.clone(), self.tx.clone(), job);
+            }
+            AppCommand::StartBrowserLogin => {
+                self.login = Some(LoginJob::new());
+                let job = self.login.clone().unwrap_or_default();
+                self.send(CoreEvent::DeviceLoginChanged(crate::dto::DeviceLoginView {
+                    phase: crate::dto::DeviceLoginPhase::Requesting,
+                    message: "正在准备浏览器登录（本地回调端口）…".to_string(),
+                    ..crate::dto::DeviceLoginView::new()
+                }));
+                accounts::start_browser_login(self.env.clone(), self.tx.clone(), job);
+            }
+            AppCommand::CancelDeviceLogin => {
+                if let Some(job) = &self.login {
+                    job.cancel();
+                }
+                self.login = None;
+                // 第三方轨的面板也归这条「关掉登录面板」：两条轨都不该留一个转不完的圈
+                if let Some(job) = &self.authlib {
+                    job.cancel();
+                }
+                self.authlib = None;
+                self.send(CoreEvent::DeviceLoginChanged(
+                    crate::dto::DeviceLoginView::new(),
+                ));
+                self.send(CoreEvent::AuthlibLoginChanged(
+                    crate::dto::AuthlibLoginView::new(),
+                ));
+            }
+            AppCommand::AddAuthlibAccount(request) => {
+                self.authlib = Some(LoginJob::new());
+                let job = self.authlib.clone().unwrap_or_default();
+                self.send(CoreEvent::AuthlibLoginChanged(
+                    crate::dto::AuthlibLoginView::running(&request.server, "正在校验服务器地址…"),
+                ));
+                accounts::start_authlib_login(self.env.clone(), self.tx.clone(), job, request);
+            }
+            AppCommand::ProbeAuthlibServer(server) => {
+                // 只探活：后台线程跑服务发现，结果回到同一条 `AuthlibLoginChanged`
+                let env = self.env.clone();
+                let tx = self.tx.clone();
+                accounts::spawn_probe(env, tx, server);
+            }
+            AppCommand::InstallJava(vendor) => {
+                self.java_busy = true;
+                self.java_message = format!("正在安装 Java（{vendor}）…");
+                self.refresh_java();
+                java::spawn_install(
+                    self.env.clone(),
+                    self.tx.clone(),
+                    unlucky_core::game::java::JdkVendor::parse(&vendor),
+                );
+            }
+            AppCommand::SetSetting { key, value } => match settings::set(&self.env, &key, &value) {
+                Ok(()) => {
+                    self.send(CoreEvent::SettingsChanged(settings::groups(&self.env)));
+                    self.java_chain.clear();
+                    self.refresh_java();
+                }
+                Err(reason) => self.toast(ToastKind::Error, reason),
+            },
+            AppCommand::DismissNotice(id) => {
+                self.notices.retain(|notice| notice.id != id);
+                self.send(CoreEvent::NoticesChanged(self.notices.clone()));
+            }
+            // M109：内容库检索（网络在后台线程，结果经 `HostTask::Content` 回来）
+            AppCommand::SearchContent(query) => {
+                addon::spawn_search(self.env.clone(), self.tx.clone(), query);
+            }
+            // M109：把某个内容项目装进指定实例。取消标记与安装面板共用同一条路
+            // （`CancelInstall` 会把标记置位，下载在阶段边界收尾）。
+            // M113: import/export —— 导入 / 预检 / 确认写盘 / 关面板
+            AppCommand::Pack(command) => self.pack(*command),
+            AppCommand::InstallContent(request) => {
+                let cancel = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
+                self.install_cancel = Some(std::sync::Arc::clone(&cancel));
+                // 代次与版本安装共用同一条路（M105 的形状）：取消/被顶掉之后，旧任务带回来的
+                // 进度事件一律被 `handle` 丢掉，内容库种的这次安装不会把面板重新点亮。
+                let epoch = self.next_install_epoch();
+                addon::spawn_install(self.env.clone(), self.tx.clone(), *request, cancel, epoch);
+            }
+            // AI 对话：agent 的 GUI host 未落地前用脚本回复（不接真实模型）
+            other @ (AppCommand::AskAgent(_) | AppCommand::StopAgent | AppCommand::SetYolo(_)) => {
+                self.chat.dispatch(other);
+                for event in self.chat.drain_events() {
+                    self.events.push_back(event);
+                }
+            }
+        }
+    }
+}
diff --git a/crates/presenter/src/host/engine.rs b/crates/presenter/src/host/engine.rs
new file mode 100644
index 0000000..03bf98d
--- /dev/null
+++ b/crates/presenter/src/host/engine.rs
@@ -0,0 +1,126 @@
+//! 下载引擎与 Java 落点的装配（versions / install / java 三个任务共用）。
+//!
+//! 与 CLI `install::build_engine` 同源：内容寻址缓存落 `.ULL/cache/`，地区判定走
+//! 24h 缓存 + 环境信号（**不做网络探测**，与 D7 的「不探测时」约定一致）。
+
+use std::path::PathBuf;
+use std::sync::Arc;
+
+use unlucky_core::download::cache::now_ms;
+use unlucky_core::download::region::{decide_from, load_cached, store_cached};
+use unlucky_core::download::region_system::detect_signals;
+use unlucky_core::download::{
+    ContentCache, DownloadEngine, EngineConfig, HealthRegistry, MirrorTable,
+};
+use unlucky_core::game::java::vendor::JdkVendor;
+use unlucky_core::game::java::{self, JavaInstallRoot};
+use unlucky_core::platform::paths::ProcessEnv;
+
+use super::env::HostEnv;
+
+/// 建下载引擎（缓存/健康度/地区判定都在数据根里）。
+pub fn engine(env: &HostEnv) -> DownloadEngine {
+    let cache_root = env.layout.cache();
+    let now = now_ms();
+    let region_path = cache_root.join("region.json");
+    let region = load_cached(&region_path, now).unwrap_or_else(|| {
+        let profile = decide_from(&detect_signals(), now);
+        let _ = store_cached(&region_path, &profile);
+        profile
+    });
+    DownloadEngine::new(
+        EngineConfig::default(),
+        Arc::new(MirrorTable::builtin()),
+        Arc::new(region),
+        Arc::new(HealthRegistry::open_in(&cache_root, now)),
+        Arc::new(ContentCache::open(&cache_root)),
+    )
+}
+
+/// 是否国内网络（决定默认发行版顺序与镜像优先级）。
+pub fn domestic(env: &HostEnv) -> bool {
+    engine(env).region().is_domestic()
+}
+
+/// 设置里的 `java.vendorPriority`（空 = 按地区默认序）。
+pub fn java_priority(env: &HostEnv) -> Vec<JdkVendor> {
+    env.store()
+        .effective("java.vendorPriority")
+        .and_then(serde_json::Value::as_array)
+        .map(|items| {
+            let texts: Vec<String> = items
+                .iter()
+                .filter_map(serde_json::Value::as_str)
+                .map(str::to_string)
+                .collect();
+            unlucky_core::game::java::vendor::parse_priority(&texts)
+        })
+        .unwrap_or_default()
+}
+
+/// 设置里的 `java.installRoot`（空 = 按数据目录模式派生）。
+pub fn java_install_override(env: &HostEnv) -> Option<PathBuf> {
+    env.store()
+        .doc()
+        .effective_str("java.installRoot")
+        .map(str::trim)
+        .filter(|text| !text.is_empty())
+        .map(PathBuf::from)
+}
+
+/// 托管 JDK 落点（解析失败 → 用户可读文案）。
+pub fn java_install_root(env: &HostEnv) -> Result<JavaInstallRoot, String> {
+    let override_root = java_install_override(env);
+    JavaInstallRoot::resolve(
+        env.mode(),
+        &env.layout,
+        override_root.as_deref(),
+        env.platform,
+        &ProcessEnv,
+    )
+    .map_err(|error| error.to_string())
+}
+
+/// 托管 JDK 可能存在的全部安装根（扫描运行时用）。
+pub fn java_scan_roots(env: &HostEnv) -> Vec<PathBuf> {
+    java::location::scan_roots(
+        env.mode(),
+        &env.layout,
+        java_install_override(env).as_deref(),
+        env.platform,
+        &ProcessEnv,
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn engine_uses_the_data_root_cache() {
+        let dir = std::env::temp_dir().join(format!("ull-host-engine-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        let env = HostEnv::at_root(&dir);
+        std::fs::create_dir_all(env.layout.cache()).expect("cache");
+        let engine = engine(&env);
+        assert_eq!(engine.config().max_concurrency, 64);
+        // 地区判定不联网：只读缓存/信号
+        let _ = domestic(&env);
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn java_merge_priority_reads_settings() {
+        let dir = std::env::temp_dir().join(format!("ull-host-engine-p-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        let env = HostEnv::at_root(&dir);
+        std::fs::create_dir_all(env.layout.config()).expect("config");
+        std::fs::write(
+            env.launcher_config(),
+            r#"{"java":{"vendorPriority":["zulu"]}}"#,
+        )
+        .expect("写配置");
+        assert_eq!(java_priority(&env), vec![JdkVendor::Zulu]);
+        std::fs::remove_dir_all(&dir).ok();
+    }
+}
diff --git a/crates/presenter/src/host/env.rs b/crates/presenter/src/host/env.rs
new file mode 100644
index 0000000..a1b6fd7
--- /dev/null
+++ b/crates/presenter/src/host/env.rs
@@ -0,0 +1,170 @@
+//! host 的环境快照：一份 `ResolvedData` + 由其派生的布局视图。
+//!
+//! app 自己不解析三模式数据根（那是 `core::platform::data_dir` 的活）；这里只做两件事：
+//! ①按「exe 同级便携 `launcher.json` 的 `core.*` 四键」拼请求；②把解析结果与
+//! `Platform` / `DataMode` 打成一个可克隆的结构，交给后台线程。
+//!
+//! 截图/演示通道用 [`HostEnv::at_root`] 直接钉一个根（`<root>/.ULL` + `<root>/.minecraft`）。
+
+use std::path::{Path, PathBuf};
+
+use unlucky_core::game::GameLayout;
+use unlucky_core::platform::data_dir::{DataDirRequest, DataMode, ResolvedData, Resolver};
+use unlucky_core::platform::layout::LauncherLayout;
+use unlucky_core::platform::paths::Platform;
+use unlucky_core::setting::keys::launcher_schema;
+use unlucky_core::setting::store::SettingStore;
+
+/// 数据根决定键（与 CLI 的 `DATA_ROOT_KEYS` 同源同义）。
+pub(crate) const DATA_ROOT_KEYS: [&str; 4] = [
+    "core.data_mode",
+    "core.data_custom_root",
+    "core.launcher_home",
+    "core.game_home",
+];
+
+/// host 运行期需要的一切路径/平台信息（可克隆进线程）。
+#[derive(Debug, Clone)]
+pub struct HostEnv {
+    /// 数据根解析结果
+    pub data: ResolvedData,
+    /// `.ULL/` 布局
+    pub layout: LauncherLayout,
+    /// `.minecraft/` 布局
+    pub game: GameLayout,
+    /// 平台
+    pub platform: Platform,
+}
+
+impl HostEnv {
+    /// 按便携目录的 `core.*` 解析真实数据根；解析不出来返回 `None`（host 退回 mock）。
+    pub fn resolve() -> Option<Self> {
+        let exe_dir = std::env::current_exe()
+            .ok()
+            .and_then(|path| path.parent().map(Path::to_path_buf))?;
+        let request = request_from_portable(&exe_dir);
+        let resolver = Resolver::new(Platform::current(), Some(exe_dir));
+        let data = resolver.resolve_default(&request).ok()?.clone();
+        Some(Self::from_data(data))
+    }
+
+    /// 直接钉一个根：`<root>/.ULL` + `<root>/.minecraft`（截图/演示通道）。
+    ///
+    /// 根下已有 `config/launcher.json` 时**尊重其中的 `core.game_home` / `core.launcher_home`**：
+    /// 演示根常用它把游戏目录指到既有真数据上（避免复制几 GB 的 assets/libraries）。
+    pub fn at_root(root: impl AsRef<Path>) -> Self {
+        let root = root.as_ref();
+        let request = request_from_portable(root);
+        let absolute = |path: Option<PathBuf>| path.filter(|path| path.is_absolute());
+        Self::from_data(ResolvedData {
+            mode: DataMode::Portable,
+            launcher_home: absolute(request.launcher_home).unwrap_or_else(|| root.join(".ULL")),
+            game_home: absolute(request.game_home).unwrap_or_else(|| root.join(".minecraft")),
+            redirected_from: None,
+        })
+    }
+
+    /// 由解析结果建环境。
+    pub fn from_data(data: ResolvedData) -> Self {
+        Self {
+            layout: data.layout(),
+            game: GameLayout::new(data.game_home.clone()),
+            platform: Platform::current(),
+            data,
+        }
+    }
+
+    /// `config/launcher.json` 路径。
+    pub fn launcher_config(&self) -> PathBuf {
+        self.layout.launcher_config()
+    }
+
+    /// 设置存储（每次现读一份；写操作自己 save）。
+    pub fn store(&self) -> SettingStore {
+        SettingStore::load(self.launcher_config(), launcher_schema())
+    }
+
+    /// 启动会话根（`.ULL/data/agent/sessions`）。
+    pub fn sessions_root(&self) -> PathBuf {
+        self.layout.agent_sessions()
+    }
+
+    /// 数据目录模式。
+    pub fn mode(&self) -> DataMode {
+        self.data.mode
+    }
+
+    /// 人读一行（设置页「数据」分组展示）。
+    pub fn data_line(&self) -> String {
+        format!(
+            "{} · 启动器 {} · 游戏 {}",
+            self.data.mode,
+            self.data.launcher_home.display(),
+            self.data.game_home.display()
+        )
+    }
+}
+
+/// 便携目录那份 `launcher.json` → 数据根请求（只读 `core.*` 四键）。
+pub(crate) fn request_from_portable(exe_dir: &Path) -> DataDirRequest {
+    let mut request = DataDirRequest::default();
+    let path = portable_config_path(exe_dir);
+    if !path.is_file() {
+        return request;
+    }
+    let store = SettingStore::load(&path, launcher_schema());
+    let text = |key: &str| store.doc().effective_str(key).map(str::to_string);
+    if let Some(mode) = text(DATA_ROOT_KEYS[0]).as_deref().and_then(DataMode::parse) {
+        request.mode = mode;
+    }
+    if let Some(root) = text(DATA_ROOT_KEYS[1]) {
+        request.custom_root = Some(PathBuf::from(root));
+    }
+    if let Some(home) = text(DATA_ROOT_KEYS[2]) {
+        request.launcher_home = Some(PathBuf::from(home));
+    }
+    if let Some(home) = text(DATA_ROOT_KEYS[3]) {
+        request.game_home = Some(PathBuf::from(home));
+    }
+    request
+}
+
+/// `<exe 目录>/.ULL/config/launcher.json`。
+pub(crate) fn portable_config_path(exe_dir: &Path) -> PathBuf {
+    LauncherLayout::new(exe_dir.join(".ULL")).launcher_config()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn at_root_splits_launcher_and_game_homes() {
+        let env = HostEnv::at_root("D:/tmp/ull-demo");
+        assert_eq!(env.layout.home(), Path::new("D:/tmp/ull-demo/.ULL"));
+        assert_eq!(env.game.root(), Path::new("D:/tmp/ull-demo/.minecraft"));
+        assert_eq!(env.mode(), DataMode::Portable);
+        assert!(env.data_line().contains("portable"));
+    }
+
+    #[test]
+    fn portable_request_reads_core_keys_only_when_file_exists() {
+        let dir = std::env::temp_dir().join(format!("ull-host-env-{}", std::process::id()));
+        std::fs::create_dir_all(dir.join(".ULL/config")).expect("建目录");
+        let request = request_from_portable(&dir);
+        assert_eq!(request, DataDirRequest::default());
+
+        std::fs::write(
+            portable_config_path(&dir),
+            r#"{"core":{"data_mode":"custom","data_custom_root":"D:/data/ull"}}"#,
+        )
+        .expect("写配置");
+        let request = request_from_portable(&dir);
+        assert_eq!(request.mode, DataMode::Custom);
+        assert_eq!(
+            request.custom_root.as_deref(),
+            Some(Path::new("D:/data/ull"))
+        );
+        std::fs::remove_dir_all(&dir).ok();
+    }
+}
diff --git a/crates/presenter/src/host/game.rs b/crates/presenter/src/host/game.rs
new file mode 100644
index 0000000..7960b3b
--- /dev/null
+++ b/crates/presenter/src/host/game.rs
@@ -0,0 +1,260 @@
+//! 实例快照：`profiles.json` + 版本 JSON + 会话索引 + 实例设置 → [`InstanceSummary`]。
+//!
+//! 「磁贴上的每个字」都在这里翻译完：版本号取自继承链根、加载器取自版本 id 前缀、
+//! 最后游玩时间取自会话索引、隔离档位取自实例设置（缺省跟全局 `instances.mode`）。
+
+use std::collections::BTreeMap;
+use std::path::Path;
+
+use unlucky_core::game::install::instance::{
+    read_instance_config, read_profiles, write_instance_config,
+};
+use unlucky_core::game::isolation::IsolationMode;
+use unlucky_core::game::{ProfileList, VersionJson};
+use unlucky_core::launch::session_index;
+
+use crate::dto::{
+    InstanceRuntime, InstanceSummary, LoaderInfo, LoaderKind, NoticeLevel, NoticeView,
+};
+
+use super::env::HostEnv;
+
+/// 全局默认隔离档位（`instances.mode`；缺键/坏值按 D20 默认 `isolated`）。
+pub fn global_mode(env: &HostEnv) -> IsolationMode {
+    env.store()
+        .doc()
+        .effective_str("instances.mode")
+        .and_then(IsolationMode::parse)
+        .unwrap_or_default()
+}
+
+/// 读实例清单（文件缺失 = 空列表，不是错误）。
+pub fn profiles(env: &HostEnv) -> ProfileList {
+    read_profiles(&env.layout).unwrap_or_default()
+}
+
+/// 全会话索引里「每个实例最近一次启动」的时间串。
+pub fn last_played(env: &HostEnv) -> BTreeMap<String, String> {
+    let index = session_index::index_path(&env.sessions_root());
+    let entries = session_index::read_all(&index).unwrap_or_default();
+    let mut map: BTreeMap<String, String> = BTreeMap::new();
+    for entry in entries {
+        if entry.instance_id.is_empty() || entry.started_at.is_empty() {
+            continue;
+        }
+        let current = map.get(&entry.instance_id);
+        if current.is_none_or(|existing| existing.as_str() < entry.started_at.as_str()) {
+            map.insert(entry.instance_id.clone(), entry.started_at);
+        }
+    }
+    map
+}
+
+/// 版本 JSON 的继承链根 id + 加载器（读不到返回 `(version_id, 原版)`）。
+pub fn describe_version(env: &HostEnv, version_id: &str) -> (String, LoaderInfo) {
+    let loader = loader_from_id(version_id);
+    let mut current = version_id.to_string();
+    let mut seen = 0;
+    while seen < 16 {
+        seen += 1;
+        let path = env.game.version_json(&current);
+        let Ok(text) = std::fs::read_to_string(&path) else {
+            break;
+        };
+        let Ok(json) = VersionJson::from_json_str(&text) else {
+            break;
+        };
+        match json.inherits_from {
+            Some(parent) if !parent.is_empty() => current = parent,
+            _ => break,
+        }
+    }
+    (current, loader)
+}
+
+/// 版本 id → 加载器（HMCL 同款命名口径：`1.20.1-forge-47.2.0` / `fabric-loader-0.16.5-1.20.1`）。
+pub fn loader_from_id(version_id: &str) -> LoaderInfo {
+    let lower = version_id.to_ascii_lowercase();
+    let grab = |marker: &str| -> String {
+        lower
+            .split_once(marker)
+            .map(|(_, rest)| rest.trim_start_matches('-').to_string())
+            .unwrap_or_default()
+    };
+    let (kind, version) = if lower.contains("neoforge") {
+        (LoaderKind::NeoForge, grab("neoforge-"))
+    } else if lower.contains("fabric-loader") {
+        (LoaderKind::Fabric, grab("fabric-loader-"))
+    } else if lower.contains("quilt-loader") {
+        (LoaderKind::Quilt, grab("quilt-loader-"))
+    } else if lower.contains("forge") {
+        (LoaderKind::Forge, grab("forge-"))
+    } else if lower.contains("optifine") {
+        (LoaderKind::OptiFine, grab("optifine"))
+    } else if lower.contains("liteloader") {
+        (LoaderKind::LiteLoader, grab("liteloader-"))
+    } else {
+        (LoaderKind::Vanilla, String::new())
+    };
+    LoaderInfo { kind, version }
+}
+
+/// 实例的隔离档位（实例文件优先，缺省显示全局档位）。
+pub fn isolation_of(env: &HostEnv, id: &str) -> String {
+    let global = global_mode(env);
+    match read_instance_config(&env.layout, id) {
+        Ok(Some(config)) => config.effective_isolation(global).as_str().to_string(),
+        _ => global.as_str().to_string(),
+    }
+}
+
+/// 实例快照。
+pub fn instances(env: &HostEnv) -> Vec<InstanceSummary> {
+    let profiles = profiles(env);
+    let played = last_played(env);
+    profiles
+        .profiles
+        .iter()
+        .map(|profile| {
+            let version_id = profile.version_id.clone();
+            let (mc_version, loader) = describe_version(env, &version_id);
+            InstanceSummary {
+                id: profile.id.as_str().to_string(),
+                name: profile.name.clone(),
+                mc_version,
+                loader,
+                last_played: played.get(profile.id.as_str()).cloned(),
+                runtime: InstanceRuntime::Idle,
+                icon: None,
+                isolation: isolation_of(env, profile.id.as_str()),
+                version_present: env.game.is_version_installed(&version_id),
+                version_id,
+            }
+        })
+        .collect()
+}
+
+/// 改实例隔离档位（写实例设置文件；不动任何数据）。
+///
+/// # Errors
+///
+/// 实例不存在、文件读不了/写不了时返回用户可读文案。
+pub fn set_isolation(env: &HostEnv, id: &str, mode: &str) -> Result<(), String> {
+    let parsed = IsolationMode::parse(mode)
+        .ok_or_else(|| format!("未知隔离档位 `{mode}`（isolated / shared）"))?;
+    let profiles = profiles(env);
+    let profile = profiles
+        .profiles
+        .iter()
+        .find(|profile| profile.id.as_str() == id)
+        .ok_or_else(|| format!("找不到实例 `{id}`"))?;
+    let mut config = read_instance_config(&env.layout, id)
+        .map_err(|error| format!("读实例设置失败：{error}"))?
+        .unwrap_or_else(|| {
+            unlucky_core::game::install::instance::InstanceConfig::new(
+                profile.id.as_str(),
+                &profile.version_id,
+            )
+        });
+    config.isolation = Some(match parsed {
+        IsolationMode::Isolated => unlucky_core::game::install::instance::Isolation::Isolated,
+        IsolationMode::Shared => unlucky_core::game::install::instance::Isolation::Shared,
+    });
+    write_instance_config(&env.layout, &config)
+        .map(|_| ())
+        .map_err(|error| format!("写实例设置失败：{error}"))
+}
+
+/// 启动前的切换检测：把 M30 的 `ModeChangeWarning` 翻成横幅通知。
+///
+/// 只在真启动时调用（会写 `lastModeChange.warned`，保证同一次切换只提示一次）。
+pub fn mode_change_notice(env: &HostEnv, id: &str) -> Option<NoticeView> {
+    let mut config = read_instance_config(&env.layout, id).ok()??;
+    let warning = config.take_mode_change_warning()?;
+    let _ = write_instance_config(&env.layout, &config);
+    Some(NoticeView::new(
+        &format!("isolation:{id}"),
+        NoticeLevel::Warn,
+        "隔离档位已切换",
+        &warning.message(),
+    ))
+}
+
+/// 建目录（数据根首次运行时）。
+pub fn ensure_root(env: &HostEnv) {
+    let _ = env.layout.ensure();
+    let _ = std::fs::create_dir_all(env.game.root());
+}
+
+/// 版本本体目录是否存在（启动前快速判断）。
+pub fn version_present(env: &HostEnv, version_id: &str) -> bool {
+    env.game.is_version_installed(version_id)
+}
+
+/// 路径显示成短串（通知/错误文案用）。
+pub fn short_path(path: &Path) -> String {
+    path.display().to_string()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn loader_parsing_covers_all_shapes() {
+        let cases = [
+            ("1.20.4", LoaderKind::Vanilla, ""),
+            (
+                "fabric-loader-0.16.5-1.20.1",
+                LoaderKind::Fabric,
+                "0.16.5-1.20.1",
+            ),
+            (
+                "quilt-loader-0.24.0-1.20.1",
+                LoaderKind::Quilt,
+                "0.24.0-1.20.1",
+            ),
+            ("1.20.1-forge-47.2.0", LoaderKind::Forge, "47.2.0"),
+            ("1.21.1-neoforge-21.1.80", LoaderKind::NeoForge, "21.1.80"),
+        ];
+        for (id, kind, version) in cases {
+            let info = loader_from_id(id);
+            assert_eq!(info.kind, kind, "{id}");
+            assert_eq!(info.version, version, "{id}");
+            assert!(!info.badge().is_empty());
+        }
+    }
+
+    #[test]
+    fn isolation_write_then_read_round_trips() {
+        let dir = std::env::temp_dir().join(format!("ull-host-game-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        let env = HostEnv::at_root(&dir);
+        std::fs::create_dir_all(env.layout.config()).expect("config 目录");
+
+        // 直接建一份 profiles.json（register 需要版本本体，这里只测隔离写读）
+        let profiles = ProfileList {
+            profiles: vec![unlucky_core::game::InstanceProfile {
+                id: unlucky_core::game::ProfileId::generate(),
+                name: "demo".to_string(),
+                version_id: "1.20.1".to_string(),
+                game_dir: None,
+                running_dir: None,
+                java_path: None,
+                created_at: None,
+                last_played_at: None,
+                extra: BTreeMap::new(),
+            }],
+            ..ProfileList::default()
+        };
+        unlucky_core::game::install::instance::write_profiles(&env.layout, &profiles)
+            .expect("写清单");
+        let id = profiles.profiles[0].id.as_str().to_string();
+
+        assert_eq!(isolation_of(&env, &id), "isolated");
+        set_isolation(&env, &id, "shared").expect("切档位");
+        assert_eq!(isolation_of(&env, &id), "shared");
+        assert!(set_isolation(&env, &id, "nope").is_err());
+        std::fs::remove_dir_all(&dir).ok();
+    }
+}
diff --git a/crates/presenter/src/host/handle.rs b/crates/presenter/src/host/handle.rs
new file mode 100644
index 0000000..d203296
--- /dev/null
+++ b/crates/presenter/src/host/handle.rs
@@ -0,0 +1,206 @@
+//! `HostTask` → `CoreEvent` 的翻译（从 `host/mod.rs` 拆出，守 400 行硬限）。
+//!
+//! 父模块的私有字段对子模块可见，所以这里直接读写 `self.tx` / `self.launches` 等。
+
+use crate::dto::{AppEvent, CoreEvent, InstanceRuntime, LogOutcome, PackEvent};
+use crate::toast::ToastKind;
+
+use super::{addon, logs, CoreHost, HostTask, LiveLaunch};
+
+impl CoreHost {
+    /// 后台消息 → 事件。
+    pub(super) fn handle(&mut self, task: HostTask) {
+        match task {
+            HostTask::Versions(Ok(versions)) => self.send(CoreEvent::VersionListChanged(versions)),
+            HostTask::Versions(Err(reason)) => {
+                self.toast(ToastKind::Warn, format!("拉取版本清单失败：{reason}"));
+            }
+            HostTask::LoaderVersions {
+                kind,
+                mc_version,
+                result,
+            } => {
+                // 失败既要落进快照（页面禁用确认 + 显示具名原因），也要一条 Toast：
+                // 用户可能正盯着上面的版本列表，下拉那一行的红字容易被忽略。
+                if let Err(reason) = &result {
+                    self.toast(
+                        ToastKind::Warn,
+                        format!("取不到 {} 的加载器版本：{reason}", kind.label()),
+                    );
+                }
+                self.send(CoreEvent::LoaderVersions {
+                    kind,
+                    mc_version,
+                    result,
+                });
+            }
+            // M109：内容库检索。`Err` 不弹 toast——页面自己有失败态（四态之一），
+            // toast 只做「顺手提一句」会把可重试的错误变成一次性噪音。
+            HostTask::Content(result) => match *result {
+                Ok(results) => self.send(CoreEvent::ContentResults(Box::new(results))),
+                Err(reason) => self.send(CoreEvent::ContentFailed(reason)),
+            },
+            // M113: import/export —— 导入/导出事件带代次，取消后回来的旧事件一律丢掉
+            HostTask::Pack { event, epoch } => {
+                // pack 用**自己**的代次（复审 r1 P2-7）：共用安装的计数器会让
+                // 「关一次导入面板」把下载页正在跑的安装静默丢掉。
+                if epoch != addon::pack_epoch(&self.env) {
+                    return;
+                }
+                // 导入成功可能登记了新实例：与 `InstallDone` 同一条刷新（复审 r1 P2-1），
+                // 否则新实例要等下一次无关的 `RefreshAll` 才出现在实例页与目标 chips 里。
+                if matches!(*event, PackEvent::Report(_)) {
+                    self.refresh_instances();
+                }
+                self.send(CoreEvent::Pack(event));
+            }
+            // M105 的形状（代次丢包）为准：旧任务（已取消 / 被下一轮顶掉）的进度一律丢掉。
+            // 这是「点了取消没反应」的根因：取消时 `InstallProgress(None)` 刚把面板收回，
+            // 旧任务的下一条「下载中」事件立刻又把它点亮。
+            HostTask::Install { progress, epoch } => {
+                if epoch != self.install_epoch {
+                    return;
+                }
+                self.install = Some(*progress.clone());
+                self.send(CoreEvent::InstallProgress(Some(*progress)));
+            }
+            HostTask::InstallDone {
+                progress,
+                result,
+                epoch,
+            } => {
+                // 收尾同样看代次：取消之后那次「已取消」的收尾不该再动面板（面板早就回弹了），
+                // 也不该清掉**新一轮**安装的取消句柄。
+                if epoch != self.install_epoch {
+                    return;
+                }
+                self.install_cancel = None;
+                self.install = Some(*progress.clone());
+                self.send(CoreEvent::InstallProgress(Some(*progress)));
+                match result {
+                    Ok(_) => {
+                        self.refresh_instances();
+                        self.send(CoreEvent::LogSessionsChanged(logs::sessions(&self.env)));
+                    }
+                    Err(reason) => self.toast(ToastKind::Error, reason),
+                }
+            }
+            HostTask::Accounts(accounts) => {
+                self.accounts = accounts.clone();
+                self.send(CoreEvent::AccountsChanged(accounts));
+                self.refresh_instances();
+            }
+            HostTask::Login(view) => self.send(CoreEvent::DeviceLoginChanged(*view)),
+            HostTask::Authlib(view) => self.send(CoreEvent::AuthlibLoginChanged(*view)),
+            HostTask::Avatar { id, skin } => {
+                // 抓到/没抓到都记下来（`None` = 试过了，不再重试），再把列表盖好发出去
+                self.skins.insert(id, skin);
+                self.attach_skins();
+                self.send(CoreEvent::AccountsChanged(self.accounts.clone()));
+            }
+            HostTask::Java(page) => self.send(CoreEvent::JavaChanged(*page)),
+            HostTask::Logs {
+                sessions,
+                lines,
+                diagnosis,
+            } => {
+                self.send(CoreEvent::LogSessionsChanged(sessions));
+                self.send(CoreEvent::LogLinesChanged(lines));
+                if let Some(report) = diagnosis {
+                    self.send(CoreEvent::DiagnosisReady(report));
+                }
+            }
+            HostTask::Sessions(sessions) => self.send(CoreEvent::LogSessionsChanged(sessions)),
+            HostTask::Tail(batch) => {
+                if batch.running {
+                    self.send(CoreEvent::LogLinesChanged(batch.lines));
+                } else {
+                    self.send(CoreEvent::LogAppended(*batch));
+                }
+            }
+            HostTask::LaunchStarted {
+                id,
+                session_id,
+                pid,
+            } => {
+                self.pending.remove(&id);
+                self.failed.remove(&id);
+                self.launches.retain(|live| live.instance != id);
+                self.launches.push(LiveLaunch {
+                    instance: id.clone(),
+                    session: session_id.clone(),
+                    pid,
+                });
+                // 实时尾随一次只跟一场（下载页/日志页共用一个滚动窗口）；
+                // 已有别的实例在尾随时不抢占——它的日志仍在 JSONL 里，收尾后可回放。
+                if self.tail.session().is_none() {
+                    self.tail.attach(
+                        self.env
+                            .sessions_root()
+                            .join("game")
+                            .join(format!("{session_id}.jsonl")),
+                        &session_id,
+                    );
+                }
+                self.send(CoreEvent::InstanceRuntimeChanged {
+                    id,
+                    runtime: InstanceRuntime::Running { pid },
+                });
+            }
+            HostTask::Runtime { id, runtime } => {
+                self.send(CoreEvent::InstanceRuntimeChanged { id, runtime });
+            }
+            HostTask::LaunchEnd(finished) => {
+                // 收尾可能发生在 LaunchStarted 之前（build_request / spawn 失败只发
+                // LaunchEnd）：pending 必须在这里也清掉，否则 in_flight 恒真、该实例
+                // 本会话内再也起不来。
+                self.pending.remove(&finished.id);
+                self.launches.retain(|live| live.instance != finished.id);
+                let runtime = if finished.outcome == LogOutcome::Ok {
+                    self.failed.remove(&finished.id);
+                    InstanceRuntime::Idle
+                } else {
+                    // 记住失败原因：随后的 refresh_instances 会重建快照，
+                    // 不记的话磁贴的「失败/重试」外观会被 Idle 盖掉。
+                    self.failed
+                        .insert(finished.id.clone(), finished.summary.clone());
+                    InstanceRuntime::Failed {
+                        reason: finished.summary.clone(),
+                    }
+                };
+                self.send(CoreEvent::InstanceRuntimeChanged {
+                    id: finished.id.clone(),
+                    runtime,
+                });
+                self.send(CoreEvent::LaunchFinished((*finished).clone()));
+                // 只拆自己那场的尾随：并发时另一实例的实时日志不该被这次收尾掐掉。
+                if self.tail.session() == Some(finished.session.as_str()) {
+                    self.tail.detach();
+                }
+                self.send(CoreEvent::LogSessionsChanged(logs::sessions(&self.env)));
+                self.refresh_instances();
+            }
+            HostTask::Crash(report) => {
+                self.send(CoreEvent::DiagnosisReady(*report));
+            }
+            HostTask::Notice(notice) => self.push_notice(*notice),
+            HostTask::Toast(toast) => self.events.push_back(AppEvent::Toast(*toast)),
+        }
+    }
+
+    /// 尾随运行中会话（每 `TAIL_POLL_TICKS` 拍一次）。
+    pub(super) fn poll_tail(&mut self) {
+        let Some((session, lines)) = self.tail.poll() else {
+            return;
+        };
+        if lines.is_empty() {
+            return;
+        }
+        let running = self.launches.iter().any(|live| live.session == session);
+        self.send(CoreEvent::LogAppended(crate::dto::LiveLogBatch {
+            session,
+            lines,
+            running,
+        }));
+    }
+}
diff --git a/crates/presenter/src/host/identity.rs b/crates/presenter/src/host/identity.rs
new file mode 100644
index 0000000..fd5df29
--- /dev/null
+++ b/crates/presenter/src/host/identity.rs
@@ -0,0 +1,103 @@
+//! 启动身份：选中账户 → `AuthPlaceholders`（**凭据只在这里读，读完即丢**）+ 收尾结局映射。
+//!
+//! 与 CLI `commands/identity.rs` 同源：微软轨过期就静默续期并回写凭据（refresh_token 轮换，
+//! 旧值作废）；零账户回落离线占位，保证没有账户时照样能启动。
+
+use unlucky_core::auth::account::{AccountKind, Credentials};
+use unlucky_core::auth::microsoft::MicrosoftAuth;
+use unlucky_core::auth::offline::offline_login;
+use unlucky_core::auth::AccountStore;
+use unlucky_core::download::blocking::block_on;
+use unlucky_core::game::ProfileId;
+use unlucky_core::launch::request::AuthPlaceholders;
+
+use crate::dto::LogOutcome;
+
+use super::env::HostEnv;
+
+/// 把选中账户翻成启动占位符（**凭据只在这里读，读完即丢**）。
+///
+/// 微软轨：过期就静默续期并回写凭据（refresh_token 轮换，旧值作废）。
+///
+/// # Errors
+///
+/// 账户不存在/凭据类型不符/令牌过期且刷新失败时返回用户可读文案。
+pub fn resolve(env: &HostEnv, account: Option<&str>) -> Result<(AuthPlaceholders, String), String> {
+    let store = AccountStore::open(env.layout.auth_data());
+    let chosen = match account {
+        Some(key) => store
+            .find(key)
+            .cloned()
+            .ok_or_else(|| format!("找不到账户 `{key}`"))?,
+        None => match store.accounts() {
+            [] => {
+                let uuid = ProfileId::generate().as_str().replace('-', "");
+                return Ok((
+                    AuthPlaceholders {
+                        player_name: "Player".to_string(),
+                        uuid,
+                        user_type: "legacy".to_string(),
+                        user_properties: "{}".to_string(),
+                        ..AuthPlaceholders::default()
+                    },
+                    "未登录账户，按离线占位启动".to_string(),
+                ));
+            }
+            [only] => only.clone(),
+            many => return Err(format!("有 {} 个账户，请在账户页选一个再启动", many.len())),
+        },
+    };
+    let line = format!("账户 {}（{}）", chosen.display_name(), chosen.kind.label());
+    match chosen.kind {
+        AccountKind::Offline => {
+            let placeholders =
+                offline_login(&chosen).map_err(|error| format!("离线账户解析失败：{error}"))?;
+            Ok((placeholders, line))
+        }
+        AccountKind::Microsoft => {
+            let Some(Credentials::Microsoft(session)) = store.credentials(&chosen.id) else {
+                return Err(format!(
+                    "账户 {} 的微软凭据缺失或类型不符，请重新登录",
+                    chosen.display_name()
+                ));
+            };
+            let auth =
+                MicrosoftAuth::from_env().map_err(|error| format!("微软登录不可用：{error}"))?;
+            let (fresh, _) = block_on(auth.ensure_fresh(session))
+                .map_err(|error| format!("微软令牌刷新失败：{error}"))?;
+            if &fresh != session {
+                // refresh_token 已轮换：立刻回写，旧值作废。
+                let mut store = AccountStore::open(env.layout.auth_data());
+                let _ = store.update_credentials(&chosen.id, Credentials::Microsoft(fresh.clone()));
+                let _ = store.save();
+            }
+            let placeholders = fresh
+                .to_placeholders()
+                .map_err(|error| format!("微软身份转换失败：{error}"))?;
+            Ok((placeholders, line))
+        }
+        AccountKind::AuthlibInjector => {
+            let Some(Credentials::AuthlibInjector(session)) = store.credentials(&chosen.id) else {
+                return Err(format!(
+                    "账户 {} 的第三方凭据缺失或类型不符",
+                    chosen.display_name()
+                ));
+            };
+            let placeholders = session
+                .to_placeholders()
+                .map_err(|error| format!("第三方身份转换失败：{error}"))?;
+            Ok((placeholders, line))
+        }
+    }
+}
+
+/// `SessionHandle` → 日志页的三种结局。
+pub fn outcome_of(handle: &unlucky_core::launch::SessionHandle) -> LogOutcome {
+    if handle.exit.silent_failure.is_some() {
+        LogOutcome::SilentFail
+    } else if handle.succeeded() {
+        LogOutcome::Ok
+    } else {
+        LogOutcome::Crashed
+    }
+}
diff --git a/crates/presenter/src/host/install.rs b/crates/presenter/src/host/install.rs
new file mode 100644
index 0000000..a8f404d
--- /dev/null
+++ b/crates/presenter/src/host/install.rs
@@ -0,0 +1,283 @@
+//! 安装：新建实例向导 / 下载页「安装」→ core 安装管线 → 登记实例。
+//!
+//! 与 CLI `ull install` 同序：`RemoteSource::resolve → InstallPlan::build → execute → register`。
+//! Forge/NeoForge 多一段 installer processors（[`super::install_processors`]）：
+//! `ProcessorPlan::build → 依赖库下载 → 选 Java → 串行 java -cp`，**跑完才写版本 JSON**。
+//! 差异只在线程模型：进度经 [`super::job::HostTask::Install`] 回流（文件计数 + 字节 + 速度/ETA），
+//! 且整段跑在后台线程里（`block_on` 不占 UI 线程）。
+//!
+//! 加载器范围：原版 + Fabric/Quilt/Forge/NeoForge（四家，与 CLI 对齐）。OptiFine/LiteLoader
+//! 两家 core 侧都还没有安装管线，仍在 GUI 里显式拒装并说清去哪装。
+//! 失败一律落 `.ULL/logs/install.log`（[`super::install_journal`]），文案里带日志路径。
+
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+
+use unlucky_core::game::install::{InstallError, InstallReport};
+
+use crate::dto::{CreateRequest, InstallStage, LoaderKind};
+use crate::toast::{Toast, ToastKind};
+
+use super::env::HostEnv;
+use super::install_journal::Journal;
+use super::install_processors;
+use super::job::{spawn, HostTask, JobSender};
+use super::meter::Meter;
+
+mod routes;
+
+use routes::{install_loader, install_vanilla};
+
+/// 文件级并发上限（与 CLI 同值：16 路压满带宽又不至于打爆镜像）。
+pub const CONCURRENCY: usize = 16;
+
+/// 用户取消的稳定文案。
+///
+/// 三件事一句话说清（D21 的口径：半成品不许冒充成品，断点材料不留在半截状态）：
+/// ① 怎么停的（`execute_with_cancel` 不再起新文件，在飞的那个就地掐断）；
+/// ② 什么被留着（**已经下完**的文件，重装续用）；
+/// ③ 什么一定没发生（实例未登记、版本清单没落盘；在飞文件的 `.ullpart` 由 `PartFile::Drop` 清掉）。
+pub const CANCELLED: &str =
+    "已取消：剩下的文件没有开始下载，已下好的文件保留（重装续用），实例未登记";
+
+/// 一次安装任务的运行上下文（后台线程内一路传下去，免得每个函数排七八个参数）。
+struct Job<'a> {
+    env: &'a HostEnv,
+    tx: &'a JobSender,
+    meter: &'a Arc<std::sync::Mutex<Meter>>,
+    cancel: &'a Arc<AtomicBool>,
+    journal: &'a Journal,
+}
+
+impl Job<'_> {
+    /// processor 段的进度出口（同一套 channel/meter/journal）。
+    fn reporter(&self) -> install_processors::Reporter<'_> {
+        install_processors::Reporter {
+            tx: self.tx,
+            meter: self.meter,
+            journal: self.journal,
+        }
+    }
+}
+
+/// 加载器徽标（`原版` / `Fabric 0.16.5`）。
+pub fn loader_label(kind: LoaderKind, version: &str) -> String {
+    if kind == LoaderKind::Vanilla || version.trim().is_empty() {
+        kind.label().to_string()
+    } else {
+        format!("{} {}", kind.label(), version)
+    }
+}
+
+/// GUI 侧支持的加载器（五选：原版 + 四家加载器，与 CLI 的 `--loader` 词表一致）。
+///
+/// 写成穷举 `matches!` 而不是 `true`：将来 core 加了第六种加载器，这里默认拒绝，
+/// 由 [`unsupported_reason`] 给出明确说法，而不是让它走进不属于它的安装分支。
+pub fn supported(kind: LoaderKind) -> bool {
+    matches!(
+        kind,
+        LoaderKind::Vanilla
+            | LoaderKind::Fabric
+            | LoaderKind::Quilt
+            | LoaderKind::Forge
+            | LoaderKind::NeoForge
+    )
+}
+
+/// 不支持的加载器 → 给用户的可执行建议。
+pub fn unsupported_reason(kind: LoaderKind) -> String {
+    format!(
+        "{} 还没有接入安装管线（目前支持原版 + Fabric/Quilt/Forge/NeoForge）；请先在实例页导入已有版本，或换成受支持的加载器。",
+        kind.label()
+    )
+}
+
+/// 后台安装（向导提交 / 下载页行内安装共用）。
+///
+/// `epoch` 是本次任务的代次（[`super::CoreHost`] 的 `install_epoch`）：它随每条进度回流，
+/// 让 host 丢掉「已被取消 / 被下一轮顶掉」的旧任务的后续事件。
+pub fn spawn_install(
+    env: HostEnv,
+    tx: JobSender,
+    request: CreateRequest,
+    cancel: Arc<AtomicBool>,
+    epoch: u64,
+) {
+    spawn("install", move || {
+        let meter = Arc::new(std::sync::Mutex::new(Meter::new(&request, epoch)));
+        let journal = Journal::open(&env);
+        journal.line(&format!(
+            "—— 开始安装 {}（{} {}）——",
+            request.instance_name(),
+            loader_label(request.loader, ""),
+            request.version
+        ));
+        let job = Job {
+            env: &env,
+            tx: &tx,
+            meter: &meter,
+            cancel: &cancel,
+            journal: &journal,
+        };
+        let result = run(&job, &request);
+        let mut progress = meter
+            .lock()
+            .map(|guard| guard.progress.clone())
+            .unwrap_or_else(|_| Meter::new(&request, epoch).progress);
+        match result {
+            Ok(name) => {
+                journal.line(&format!("完成：实例 {name} 已登记"));
+                progress.stage = InstallStage::Done;
+                progress.files_done = progress.files_total;
+                progress.message = format!("已安装 {name}（{}）", progress.loader);
+                let _ = tx.send(HostTask::InstallDone {
+                    progress: Box::new(progress),
+                    result: Ok(name),
+                    epoch,
+                });
+                let _ = tx.send(HostTask::Toast(Box::new(Toast {
+                    id: 0,
+                    kind: ToastKind::Success,
+                    text: "安装完成，实例已登记".to_string(),
+                    remaining_ms: 0,
+                })));
+            }
+            Err(reason) => {
+                let cancelled = reason == CANCELLED;
+                progress.stage = if cancelled {
+                    InstallStage::Cancelled
+                } else {
+                    InstallStage::Failed
+                };
+                // 失败文案带上日志路径：面板只有一行、Toast 4 秒就消失，
+                // 装日志是用户事后能自己回看的唯一渠道（进度板之外）。
+                let text = if cancelled {
+                    journal.line(CANCELLED);
+                    reason
+                } else {
+                    journal.line(&format!("安装未完成：{reason}"));
+                    format!("{reason}（日志：{}）", journal.path().display())
+                };
+                progress.message.clone_from(&text);
+                let _ = tx.send(HostTask::InstallDone {
+                    progress: Box::new(progress),
+                    result: Err(text),
+                    epoch,
+                });
+            }
+        }
+    });
+}
+
+/// 真安装（同步跑完，调用方在后台线程里）。
+fn run(job: &Job<'_>, request: &CreateRequest) -> Result<String, String> {
+    if request.version.trim().is_empty() {
+        return Err("没有选择版本".to_string());
+    }
+    if !supported(request.loader) {
+        return Err(unsupported_reason(request.loader));
+    }
+    let name = request.instance_name();
+    let env = job.env;
+    let engine = super::engine::engine(env);
+    {
+        let mut guard = job.meter.lock().map_err(|_| "进度锁失效".to_string())?;
+        guard.stage(InstallStage::Planning, "正在解析版本清单…");
+        let _ = job.tx.send(HostTask::Install {
+            progress: Box::new(guard.progress.clone()),
+            epoch: guard.epoch,
+        });
+    }
+
+    // 段边界检查（M105）：`execute_with_cancel` 自己会掐断在飞的文件，这里管的是**段与段之间**
+    // ——原版段与加载器段、文件段与登记之间，取消都必须在下一段开工前生效。
+    if job.cancel.load(Ordering::SeqCst) {
+        return Err(CANCELLED.to_string());
+    }
+    let version_id = if request.loader == LoaderKind::Vanilla {
+        install_vanilla(job, &engine, request)?
+    } else {
+        install_loader(job, &engine, request)?
+    };
+
+    // **取消之后绝不登记实例**（M105）：文件段已经在跑了，下完那一刻用户可能早已点了取消；
+    // 这里不拦的话，取消会留下一个「用户以为没装、其实已经装好并登记」的实例——
+    // 那正是「半成品污染」里最难解释的一种（列表里凭空多一条）。
+    if job.cancel.load(Ordering::SeqCst) {
+        job.journal
+            .line("已取消：文件段跑完但用户已取消，不登记实例（版本清单是否落盘见上）");
+        return Err(CANCELLED.to_string());
+    }
+
+    {
+        let mut guard = job.meter.lock().map_err(|_| "进度锁失效".to_string())?;
+        guard.stage(InstallStage::Registering, "正在登记实例…");
+        let _ = job.tx.send(HostTask::Install {
+            progress: Box::new(guard.progress.clone()),
+            epoch: guard.epoch,
+        });
+    }
+    let created_at =
+        unlucky_core::launch::time::format_rfc3339_millis(unlucky_core::launch::time::now());
+    unlucky_core::game::install::instance::register(
+        &env.layout,
+        &name,
+        &version_id,
+        Some(&created_at),
+    )
+    .map_err(|error| format!("登记实例失败：{error}"))?;
+    Ok(name)
+}
+
+/// 安装错误 → 用户可读文案（**取消不算失败**：给那句稳定文案，不给「失败 + 日志路径」）。
+///
+/// 判据用 job 自己的取消标志而不是错误大类：core 的 `execute_with_cancel` 只在阶段边界与
+/// 每个文件开工前看标志，取消与「最后一个文件刚好失败」可能同时成立——那种情况下用户点了取消，
+/// 文案就该说取消（否则他会以为取消导致了失败）。
+fn job_error(job: &Job<'_>, error: InstallError) -> String {
+    if job.cancel.load(Ordering::SeqCst) {
+        return CANCELLED.to_string();
+    }
+    install_error(error)
+}
+
+/// 安装错误 → 用户可读文案。
+fn install_error(error: InstallError) -> String {
+    match error.hint() {
+        Some(hint) => format!("{}（{hint}）", error.message()),
+        None => error.message().to_string(),
+    }
+}
+
+/// 有文件失败就报错（列前三条明细）。
+fn ensure_complete(report: &InstallReport) -> Result<(), String> {
+    if report.is_complete() {
+        return Ok(());
+    }
+    let details: Vec<String> = report
+        .failures(3)
+        .iter()
+        .filter_map(|outcome| {
+            outcome
+                .failure
+                .as_ref()
+                .map(|failure| format!("{}：{}", outcome.name, failure.message))
+        })
+        .collect();
+    Err(format!(
+        "{} 个文件没下成（共 {} 个）：{}",
+        report.failed(),
+        report.files.len(),
+        details.join("；")
+    ))
+}
+
+/// 安装目录的短显示（诊断/Toast 用）。
+pub fn game_root(env: &HostEnv) -> PathBuf {
+    env.game.root().to_path_buf()
+}
+
+#[cfg(test)]
+#[path = "install_tests.rs"]
+mod tests;
diff --git a/crates/presenter/src/host/install/routes.rs b/crates/presenter/src/host/install/routes.rs
new file mode 100644
index 0000000..22f00bf
--- /dev/null
+++ b/crates/presenter/src/host/install/routes.rs
@@ -0,0 +1,183 @@
+//! 两条安装路线（原版 / 加载器）——M105 从 `install.rs` 搬出，守 400 行硬线。
+//!
+//! 搬移是**纯搬移**：函数体一行没改，只多了本文件自己的 `use`。
+//! 父模块（`install`）的私有项对子模块可见，所以 `Job` / `CANCELLED` / `job_error` /
+//! `ensure_complete` / `sink_for` 一律不重新导出，直接用。
+
+use std::sync::atomic::Ordering;
+use std::sync::Arc;
+
+use unlucky_core::addon::loader::{
+    LoaderInstallPlan, LoaderKind as CoreLoaderKind, LoaderPlanInput, LoaderSource,
+};
+use unlucky_core::download::blocking::block_on;
+use unlucky_core::download::cache::now_ms;
+use unlucky_core::download::DownloadEngine;
+use unlucky_core::game::arguments::Environment;
+use unlucky_core::game::install::{execute_with_cancel, InstallPlan, PlanInput, RemoteSource};
+
+use crate::dto::{CreateRequest, InstallStage, LoaderKind};
+
+use super::super::install_processors::{self, StageInput};
+use super::super::meter::sink_for;
+use super::{ensure_complete, install_error, job_error, Job, CANCELLED, CONCURRENCY};
+
+/// 原版安装（`resolve → plan → [prefetch 资源索引] → execute`）。
+pub(super) fn install_vanilla(
+    job: &Job<'_>,
+    engine: &DownloadEngine,
+    request: &CreateRequest,
+) -> Result<String, String> {
+    let env = job.env;
+    let version = request.version.trim();
+    let meta_cache = env.layout.meta_cache();
+    let now = now_ms();
+    let sink = sink_for(job.tx.clone(), Arc::clone(job.meter));
+    block_on(async {
+        let source = RemoteSource::new(engine, &env.game, &meta_cache, now);
+        let resolved = source.resolve(version).await.map_err(install_error)?;
+        let fetched = match resolved
+            .asset_index
+            .as_ref()
+            .filter(|index| index.url.is_some())
+        {
+            Some(reference) => {
+                let (index, bytes) = source.asset_index(reference).await.map_err(install_error)?;
+                Some((index, env.game.asset_index(&reference.id), bytes))
+            }
+            None => None,
+        };
+        let mut plan = InstallPlan::build(PlanInput {
+            layout: &env.game,
+            version_id: version,
+            resolved: &resolved,
+            asset_index: fetched.as_ref().map(|(index, _, _)| index),
+            environment: &Environment::host(),
+        })
+        .map_err(|error| error.to_string())?;
+        if let Some((_, dest, bytes)) = fetched {
+            plan.prefetch(dest, bytes);
+        }
+        if !plan.is_installable() {
+            return Err(format!(
+                "版本 {version} 装不全：{}",
+                plan.warnings.join("；")
+            ));
+        }
+        let (bytes_total, _) = plan.total_bytes();
+        {
+            let mut guard = job.meter.lock().map_err(|_| "进度锁失效".to_string())?;
+            guard.progress.files_total = u64::try_from(plan.file_count()).unwrap_or(u64::MAX);
+            guard.progress.bytes_total = bytes_total;
+            guard.stage(
+                InstallStage::Downloading,
+                &format!("开始下载 {} 个文件…", plan.file_count()),
+            );
+        }
+        if job.cancel.load(Ordering::SeqCst) {
+            return Err(CANCELLED.to_string());
+        }
+        let report = execute_with_cancel(
+            engine,
+            &plan,
+            CONCURRENCY,
+            Some(sink),
+            Some(job.cancel.as_ref()),
+        )
+        .await
+        .map_err(|error| job_error(job, error))?;
+        ensure_complete(&report)?;
+        Ok::<String, String>(version.to_string())
+    })
+}
+
+/// 加载器安装（原版前置 → installer processors → 加载器库 → 版本 JSON 落盘）。
+pub(super) fn install_loader(
+    job: &Job<'_>,
+    engine: &DownloadEngine,
+    request: &CreateRequest,
+) -> Result<String, String> {
+    let env = job.env;
+    let version = request.version.trim();
+    let kind = CoreLoaderKind::parse(request.loader.as_str())
+        .ok_or_else(|| format!("未知加载器 `{}`", request.loader.as_str()))?;
+    let meta_cache = env.layout.meta_cache();
+    let loader_version = request.loader_version.trim().to_string();
+    let explicit = (!loader_version.is_empty()).then_some(loader_version.as_str());
+    let release = block_on(async {
+        LoaderSource::new(engine, &meta_cache)
+            .resolve(kind, version, explicit)
+            .await
+    })
+    .map_err(|error| error.to_string())?;
+    job.journal.line(&format!(
+        "加载器解析：{} {} → {}",
+        release.kind.label(),
+        release.loader_version,
+        release.version_id
+    ));
+
+    let plan = LoaderInstallPlan::build(LoaderPlanInput {
+        layout: &env.game,
+        release: &release,
+        environment: &Environment::host(),
+        vanilla_installed: env.game.is_version_installed(version),
+    });
+    if plan.vanilla_install_needed {
+        let mut vanilla = request.clone();
+        vanilla.loader = LoaderKind::Vanilla;
+        install_vanilla(job, engine, &vanilla)?;
+    }
+    // 两段（加载器库 + 处理器依赖库）在动手前一次预记账：进度条只走一条单调曲线，
+    // 处理器依赖库下完不会先满格、再在加载器库开始时回落到一半。
+    {
+        let mut guard = job.meter.lock().map_err(|_| "进度锁失效".to_string())?;
+        let (bytes, _) = plan.install.total_bytes();
+        guard.expect(plan.files().len(), bytes);
+    }
+    // Forge/NeoForge：installer processors 必须先跑完，`execute` 才允许写版本 JSON。
+    if release.requires_installer() {
+        let input = StageInput {
+            kind: release.kind,
+            mc_version: &release.mc_version,
+            version_id: &release.version_id,
+            profile: release.install_profile.as_ref(),
+            installer: release.installer.as_deref(),
+            installed: env.game.is_version_installed(&release.version_id),
+        };
+        // `None` = 这一版不需要跑处理器（版本 JSON 已在盘上 / profile 没有 client 侧步骤），
+        // 进度与日志都由处理器段自己写全，这里只消费返回值。
+        let _ = install_processors::stage(
+            env,
+            engine,
+            &input,
+            &install_processors::CORE,
+            &job.reporter(),
+            job.cancel,
+        )?;
+    }
+    {
+        let mut guard = job.meter.lock().map_err(|_| "进度锁失效".to_string())?;
+        guard.stage(
+            InstallStage::Downloading,
+            &format!("开始下载加载器库（{} 个文件）…", plan.files().len()),
+        );
+    }
+    if job.cancel.load(Ordering::SeqCst) {
+        return Err(CANCELLED.to_string());
+    }
+    let sink = sink_for(job.tx.clone(), Arc::clone(job.meter));
+    let report = block_on(async {
+        execute_with_cancel(
+            engine,
+            &plan.install,
+            CONCURRENCY,
+            Some(sink),
+            Some(job.cancel.as_ref()),
+        )
+        .await
+    })
+    .map_err(|error| job_error(job, error))?;
+    ensure_complete(&report)?;
+    Ok(release.version_id)
+}
diff --git a/crates/presenter/src/host/install_journal.rs b/crates/presenter/src/host/install_journal.rs
new file mode 100644
index 0000000..37d3776
--- /dev/null
+++ b/crates/presenter/src/host/install_journal.rs
@@ -0,0 +1,79 @@
+//! 安装过程的可回溯日志（`.ULL/logs/install.log`，一轮一行）。
+//!
+//! 起因（M45）：Forge/NeoForge 装失败时，GUI 只有一行 Toast，processor 的 stderr 尾部
+//! 与「哪一步挂了」在面板一关就没了。这里把安装过程按行追加到 `.ULL/logs/`
+//! （与 `auth.jsonl` 同一分区），失败文案里带上日志路径，用户能自己回看。
+//!
+//! 三条纪律（与 auth 日志同源）：
+//! 1. **只追加**，不轮转、不截断（体积由「一行一条、只记诊断字段」控制）；
+//! 2. **只记诊断字段**：阶段、processor 坐标、退出码、已脱敏的 stderr 尾部（core 侧脱敏）；
+//! 3. **写盘尽力而为**：开不了文件就静默跳过，绝不让日志失败连累安装。
+
+use std::io::Write;
+use std::path::{Path, PathBuf};
+
+use unlucky_core::launch::time;
+
+use super::env::HostEnv;
+
+/// 日志文件名（在 `.ULL/logs/` 下）。
+pub const INSTALL_LOG_FILE: &str = "install.log";
+
+/// 一轮安装的日志句柄（`Clone` 很便宜：只有一个路径）。
+#[derive(Debug, Clone)]
+pub struct Journal {
+    path: PathBuf,
+}
+
+impl Journal {
+    /// 按数据根打开（`logs/` 不存在就补建；建不出来只是没有日志）。
+    pub fn open(env: &HostEnv) -> Self {
+        let dir = env.layout.logs();
+        let _ = std::fs::create_dir_all(&dir);
+        Self {
+            path: dir.join(INSTALL_LOG_FILE),
+        }
+    }
+
+    /// 日志路径（失败文案里给用户看）。
+    pub fn path(&self) -> &Path {
+        &self.path
+    }
+
+    /// 追加一行（自动补 RFC3339 时间戳；写失败静默）。
+    pub fn line(&self, text: &str) {
+        let Ok(mut file) = std::fs::OpenOptions::new()
+            .create(true)
+            .append(true)
+            .open(&self.path)
+        else {
+            return;
+        };
+        let _ = writeln!(
+            file,
+            "[{}] {text}",
+            time::format_rfc3339_millis(time::now())
+        );
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn lines_are_appended_with_a_timestamp() {
+        let root = std::env::temp_dir().join(format!("ull-install-journal-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&root);
+        let env = HostEnv::at_root(&root);
+        let journal = Journal::open(&env);
+        journal.line("第一行");
+        journal.line("第二行");
+        let text = std::fs::read_to_string(journal.path()).expect("日志存在");
+        assert!(text.contains("第一行") && text.contains("第二行"), "{text}");
+        assert_eq!(text.lines().count(), 2);
+        assert!(text.starts_with("[2"), "带时间戳：{text}");
+        assert_eq!(journal.path(), env.layout.logs().join(INSTALL_LOG_FILE));
+        std::fs::remove_dir_all(&root).ok();
+    }
+}
diff --git a/crates/presenter/src/host/install_processors.rs b/crates/presenter/src/host/install_processors.rs
new file mode 100644
index 0000000..8e47554
--- /dev/null
+++ b/crates/presenter/src/host/install_processors.rs
@@ -0,0 +1,382 @@
+//! Forge / NeoForge 的 installer processors 段（M45：GUI 与 CLI 行为对齐）。
+//!
+//! 顺序与 CLI `ull install --loader forge` 完全一致（`crates/cli/src/commands/install/
+//! loader_processors.rs`），只是把进度接到 GUI 的回流通道上：
+//!
+//! ```text
+//! ProcessorPlan::build（纯计算：变量表 + 每步 java -cp + 依赖库清单）
+//!   → download_libraries（M27 引擎；进度回流 HostTask::Install）
+//!   → select_java（M33 解析链：托管 > JAVA_HOME > PATH > 扫盘）
+//!   → run（串行 java -cp；每步一条面板文案 + 一行装日志）
+//! ```
+//!
+//! 四条硬约束（与 CLI 同源，GUI 侧一条都不放宽）：
+//!
+//! 1. **processors 跑完才允许写版本 JSON**：版本清单存在 = 这版装完了，抢在 processors
+//!    前写会留下启动必崩却被报成"已安装"的实例（顺序由 `install_loader` 保证）；
+//! 2. **幂等**：版本 JSON 已在盘上 = 上一轮跑完了，整段跳过；
+//! 3. **取消在阶段边界生效**：处理器阶段是原子段（串行外调 java，进程内没有取消钩子），
+//!    进入前与退出后各查一次 `cancel`；
+//! 4. **失败不静默**：结构化文案（带 `processor_*` 大类码）+ 装日志一行一条，由调用方
+//!    再补 Toast（`HostTask::InstallDone` 的既有通路）。
+//!
+//! 执行后端走 [`Backend`]：真实实现 [`CoreBackend`] 直接转调 core，单测注入 fake，
+//! 因此「计划怎么组、Java 找不到怎么说、依赖库下漏怎么报」都能在没有网络/没有 JDK
+//! 的机器上断言。
+
+use std::path::Path;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex};
+
+use unlucky_core::addon::loader::forge::InstallProfile;
+use unlucky_core::addon::loader::processors::{
+    self, ProcessorError, ProcessorPlan, ProcessorPlanInput, ProcessorRun, StepOutcome, StepSink,
+    StepStatus,
+};
+use unlucky_core::addon::loader::LoaderKind as CoreLoaderKind;
+use unlucky_core::download::blocking::block_on;
+use unlucky_core::download::DownloadEngine;
+use unlucky_core::game::arguments::Environment;
+use unlucky_core::game::install::{InstallReport, PlanFile, ProgressSink};
+use unlucky_core::game::java::{JavaRequirement, JavaRuntime};
+
+use crate::dto::InstallStage;
+
+use super::env::HostEnv;
+use super::install::{CANCELLED, CONCURRENCY};
+use super::install_journal::Journal;
+use super::job::{HostTask, JobSender};
+use super::meter::{sink_for, Meter};
+
+/// 真实后端（无状态，可以放静态里复用）。
+pub(super) const CORE: CoreBackend = CoreBackend;
+
+/// processors 段需要的输入（从 `LoaderRelease` 摘出来，便于单测构造）。
+pub(super) struct StageInput<'a> {
+    /// 加载器种类（补库时 maven 基址的兜底来源）。
+    pub kind: CoreLoaderKind,
+    /// 目标原版版本。
+    pub mc_version: &'a str,
+    /// loader 版本 id（依赖库落点 + 临时目录名）。
+    pub version_id: &'a str,
+    /// installer 里读出来的 install profile（`requires_installer` 为真时必须有）。
+    pub profile: Option<&'a InstallProfile>,
+    /// installer jar 的磁盘路径。
+    pub installer: Option<&'a Path>,
+    /// 版本 JSON 已在盘上 = 上一轮跑完了，整段跳过（幂等）。
+    pub installed: bool,
+}
+
+/// processors 段的执行后端（真实实现转调 core；单测注入 fake）。
+pub(super) trait Backend {
+    /// 下载 processor 依赖库（M27 引擎：镜像/健康度/退避/校验）。
+    fn download_libraries(
+        &self,
+        engine: &DownloadEngine,
+        files: &[PlanFile],
+        sink: Option<ProgressSink>,
+    ) -> InstallReport;
+    /// 按 M33 的解析链挑一个能跑 installer 的 Java。
+    fn select_java(&self, managed: &Path, requirement: &JavaRequirement) -> Option<JavaRuntime>;
+    /// 串行跑 processors。
+    fn run(
+        &self,
+        plan: &ProcessorPlan,
+        java: &JavaRuntime,
+        sink: Option<StepSink>,
+    ) -> Result<ProcessorRun, ProcessorError>;
+}
+
+/// 真实后端：三件事全部转调 core 的同一个执行器（CLI 用的就是它）。
+pub(super) struct CoreBackend;
+
+impl Backend for CoreBackend {
+    fn download_libraries(
+        &self,
+        engine: &DownloadEngine,
+        files: &[PlanFile],
+        sink: Option<ProgressSink>,
+    ) -> InstallReport {
+        block_on(processors::download_libraries(
+            engine,
+            files,
+            CONCURRENCY,
+            sink,
+        ))
+    }
+
+    fn select_java(&self, managed: &Path, requirement: &JavaRequirement) -> Option<JavaRuntime> {
+        processors::select_java(managed, requirement)
+    }
+
+    fn run(
+        &self,
+        plan: &ProcessorPlan,
+        java: &JavaRuntime,
+        sink: Option<StepSink>,
+    ) -> Result<ProcessorRun, ProcessorError> {
+        processors::run(plan, java, sink)
+    }
+}
+
+/// 段内的进度出口：进度面板（`HostTask::Install`）+ 装日志。
+pub(super) struct Reporter<'a> {
+    /// 后台线程 → host 的通道。
+    pub tx: &'a JobSender,
+    /// 进度记账器。
+    pub meter: &'a Arc<Mutex<Meter>>,
+    /// 装日志。
+    pub journal: &'a Journal,
+}
+
+impl Reporter<'_> {
+    /// 换阶段并推一条进度。
+    fn stage(&self, stage: InstallStage, message: &str) {
+        let Ok(mut guard) = self.meter.lock() else {
+            return;
+        };
+        guard.stage(stage, message);
+        let _ = self.tx.send(HostTask::Install {
+            progress: Box::new(guard.progress.clone()),
+            epoch: guard.epoch,
+        });
+    }
+
+    /// 先把待下的库记账（文件数 + 已知字节），下载回调再逐个累加。
+    fn expect(&self, files: usize, bytes: u64) {
+        let Ok(mut guard) = self.meter.lock() else {
+            return;
+        };
+        guard.expect(files, bytes);
+    }
+
+    /// 失败留痕（文案由调用方决定怎么呈现；这里只保证日志里有一条）。
+    fn fail(&self, reason: String) -> String {
+        self.journal.line(&format!("失败：{reason}"));
+        reason
+    }
+}
+
+/// 跑 Forge / NeoForge 的 installer processors（`Ok(None)` = 这一轮不需要跑）。
+///
+/// # Errors
+///
+/// 元数据缺 profile/installer、依赖库没下全、找不到可用 Java、processor 非零退出、
+/// 产物没落盘、用户取消时返回给 UI 的文案（已写进装日志）。
+pub(super) fn stage(
+    env: &HostEnv,
+    engine: &DownloadEngine,
+    input: &StageInput<'_>,
+    backend: &dyn Backend,
+    reporter: &Reporter<'_>,
+    cancel: &Arc<AtomicBool>,
+) -> Result<Option<ProcessorRun>, String> {
+    if input.installed {
+        reporter.journal.line(&format!(
+            "{} 的版本 JSON 已在盘上，跳过 installer processors",
+            input.version_id
+        ));
+        return Ok(None);
+    }
+    let (Some(profile), Some(installer)) = (input.profile, input.installer) else {
+        return Err(reporter.fail(metadata_missing(input)));
+    };
+    reporter.stage(InstallStage::Installing, "正在组 installer 处理器计划…");
+    let scratch = env
+        .layout
+        .cache()
+        .join("processors")
+        .join(safe_name(input.version_id));
+    let plan = ProcessorPlan::build(ProcessorPlanInput {
+        kind: input.kind,
+        mc_version: input.mc_version,
+        version_id: input.version_id,
+        profile,
+        layout: &env.game,
+        installer,
+        scratch: &scratch,
+        environment: &Environment::host(),
+    })
+    .map_err(|error| reporter.fail(diagnostic(&error)))?;
+    for warning in &plan.warnings {
+        reporter.journal.line(&format!("规划告警：{warning}"));
+    }
+    if plan.is_empty() {
+        reporter
+            .journal
+            .line("install profile 没有 client 侧 processor，跳过这一段");
+        return Ok(None);
+    }
+
+    let total = plan.step_count();
+    let bytes = plan.libraries.iter().filter_map(|file| file.size).sum();
+    reporter.expect(plan.libraries.len(), bytes);
+    reporter.stage(
+        InstallStage::Downloading,
+        &format!("下载 installer 依赖库（{} 个文件）…", plan.libraries.len()),
+    );
+    if cancel.load(Ordering::SeqCst) {
+        return Err(CANCELLED.to_string());
+    }
+    let sink = sink_for(reporter.tx.clone(), Arc::clone(reporter.meter));
+    let libraries = backend.download_libraries(engine, &plan.libraries, Some(sink));
+    if !libraries.is_complete() {
+        return Err(reporter.fail(libraries_failed(&libraries)));
+    }
+
+    let managed = env.layout.java_managed();
+    let Some(java) = backend.select_java(&managed, &plan.java_requirement) else {
+        return Err(reporter.fail(java_missing(&plan.java_requirement, &managed)));
+    };
+    reporter.journal.line(&format!(
+        "用 {}（{}）跑 {total} 步 processor",
+        java.binary.display(),
+        java_label(&java)
+    ));
+    reporter.stage(
+        InstallStage::Installing,
+        &format!("运行 installer 处理器 0/{total}（{}）…", java_label(&java)),
+    );
+    if cancel.load(Ordering::SeqCst) {
+        return Err(CANCELLED.to_string());
+    }
+
+    let steps = step_sink(
+        reporter.tx.clone(),
+        Arc::clone(reporter.meter),
+        reporter.journal.clone(),
+        total,
+    );
+    let run = backend
+        .run(&plan, &java, Some(steps))
+        .map_err(|error| reporter.fail(diagnostic(&error)))?;
+    for warning in &run.warnings {
+        reporter.journal.line(&format!("执行告警：{warning}"));
+    }
+    reporter.journal.line(&format!(
+        "processors 完成：执行 {} 步、跳过 {} 步",
+        run.executed(),
+        run.skipped()
+    ));
+    reporter.stage(
+        InstallStage::Installing,
+        &format!(
+            "installer 处理器完成（执行 {} 步、跳过 {} 步），正在写入版本清单…",
+            run.executed(),
+            run.skipped()
+        ),
+    );
+    if cancel.load(Ordering::SeqCst) {
+        return Err(CANCELLED.to_string());
+    }
+    Ok(Some(run))
+}
+
+/// 每步完成的回调：面板一行 + 装日志一行。
+///
+/// `StepSink` 要求 `'static`，所以这里全持所有权（通道/记账器/日志都是克隆）。
+fn step_sink(tx: JobSender, meter: Arc<Mutex<Meter>>, journal: Journal, total: usize) -> StepSink {
+    Arc::new(move |outcome: &StepOutcome| {
+        let line = step_line(outcome, total);
+        journal.line(&line);
+        let Ok(mut guard) = meter.lock() else {
+            return;
+        };
+        guard.stage(InstallStage::Installing, &line);
+        let _ = tx.send(HostTask::Install {
+            progress: Box::new(guard.progress.clone()),
+            epoch: guard.epoch,
+        });
+    })
+}
+
+/// 一步的进度/日志文案（纯函数，单测直接断言）。
+pub(super) fn step_line(outcome: &StepOutcome, total: usize) -> String {
+    let suffix = match outcome.status {
+        StepStatus::Skipped => "（产物已就绪，跳过）".to_string(),
+        StepStatus::Executed => format!("（{} ms）", outcome.elapsed_ms),
+    };
+    format!(
+        "installer 处理器 {}/{}：{}{suffix}",
+        outcome.index, total, outcome.label
+    )
+}
+
+/// processor 错误 → 用户可读文案（保留 `processor_*` 大类码，便于按码搜日志）。
+pub(super) fn diagnostic(error: &ProcessorError) -> String {
+    let mut text = format!("{}（{}）", error.message(), error.kind().as_str());
+    if let Some(hint) = error.hint() {
+        text.push_str("；建议：");
+        text.push_str(hint);
+    }
+    text
+}
+
+/// 缺 Java 运行时的专用文案（比通用错误多给一条「去哪装」）。
+pub(super) fn java_missing(requirement: &JavaRequirement, managed: &Path) -> String {
+    format!(
+        "跑 installer 需要 {}，但一个可用的 Java 运行时都没找到；请到「Java」页安装托管 JDK，或把 JAVA_HOME 指向可用的 JDK（托管目录 {}）",
+        requirement.describe(),
+        managed.display()
+    )
+}
+
+/// 依赖库没下全 → 列前三条失败明细。
+pub(super) fn libraries_failed(report: &InstallReport) -> String {
+    let details: Vec<String> = report
+        .failures(3)
+        .iter()
+        .filter_map(|outcome| {
+            outcome
+                .failure
+                .as_ref()
+                .map(|failure| format!("{}：{}", outcome.name, failure.message))
+        })
+        .collect();
+    format!(
+        "installer 依赖库没下全（{} 个失败，共 {} 个）：{}",
+        report.failed(),
+        report.files.len(),
+        details.join("；")
+    )
+}
+
+/// 需要 installer 但元数据不全（缓存半截 / 换线路重解析过）。
+fn metadata_missing(input: &StageInput<'_>) -> String {
+    format!(
+        "{} {} 需要跑 installer processors，但没拿到 install profile / installer 路径；重跑一次即可（元数据缓存可能不完整）",
+        input.kind.label(),
+        input.version_id
+    )
+}
+
+/// Java 的一行短标识（`Java 21 · managed`）。
+fn java_label(java: &JavaRuntime) -> String {
+    match java.major {
+        Some(major) => format!("Java {major} · {}", java.origin.as_str()),
+        None => format!("Java 主版本未知 · {}", java.origin.as_str()),
+    }
+}
+
+/// 版本 id → 可做目录名的片段（`+` 与路径分隔符都换掉，与 CLI 同规则）。
+fn safe_name(raw: &str) -> String {
+    raw.chars()
+        .map(|ch| {
+            if ch.is_ascii_alphanumeric() || matches!(ch, '.' | '-' | '_') {
+                ch
+            } else {
+                '_'
+            }
+        })
+        .collect::<String>()
+        .trim_end_matches('.')
+        .to_string()
+}
+
+#[cfg(test)]
+#[path = "install_processors_fixture.rs"]
+mod fixture;
+
+#[cfg(test)]
+#[path = "install_processors_tests.rs"]
+mod tests;
diff --git a/crates/presenter/src/host/install_processors_fixture.rs b/crates/presenter/src/host/install_processors_fixture.rs
new file mode 100644
index 0000000..83ae946
--- /dev/null
+++ b/crates/presenter/src/host/install_processors_fixture.rs
@@ -0,0 +1,272 @@
+//! installer processors 段的单测夹具（拆文件守 400 行上限）。
+//!
+//! 不需要网络、不需要 JDK、不真的起 java：`Harness` 给一个临时数据根 + 进度通道，
+//! `Fake` 回放预置的下载/Java/执行结果并记录被调顺序与组出来的命令行。
+
+use std::cell::RefCell;
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
+use std::sync::mpsc::Receiver;
+use std::sync::{Arc, Mutex};
+
+use unlucky_core::addon::loader::forge::{InstallProfile, Processor};
+use unlucky_core::addon::loader::processors::{
+    ProcessorError, ProcessorPlan, ProcessorRun, StepOutcome, StepSink, StepStatus,
+};
+use unlucky_core::addon::loader::LoaderKind as CoreLoaderKind;
+use unlucky_core::download::{DownloadEngine, DownloadErrorKind};
+use unlucky_core::game::install::{
+    FileFailure, FileOutcome, FileStatus, InstallReport, PlanFile, ProgressSink,
+};
+use unlucky_core::game::java::{JavaOrigin, JavaRequirement, JavaRuntime};
+
+use super::{Backend, Reporter, StageInput};
+use crate::dto::{CreateRequest, LoaderKind};
+use crate::host::env::HostEnv;
+use crate::host::install_journal::Journal;
+use crate::host::job::{channel, HostTask, JobSender};
+use crate::host::meter::Meter;
+
+static SEQ: AtomicUsize = AtomicUsize::new(0);
+
+/// 一步的计划视图（序号 / 坐标 / 参数 / classpath 条数）。
+pub(super) type StepView = (usize, String, Vec<String>, usize);
+
+/// 一段 cases 的公共环境：临时数据根 + 引擎 + 进度通道。
+pub(super) struct Harness {
+    dir: PathBuf,
+    pub(super) env: HostEnv,
+    pub(super) engine: DownloadEngine,
+    tx: JobSender,
+    rx: Receiver<HostTask>,
+    pub(super) meter: Arc<Mutex<Meter>>,
+    pub(super) journal: Journal,
+    pub(super) cancel: Arc<AtomicBool>,
+}
+
+impl Harness {
+    pub(super) fn new() -> Self {
+        let seq = SEQ.fetch_add(1, Ordering::SeqCst);
+        let dir = std::env::temp_dir().join(format!("ull-proc-{}-{seq}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        let env = HostEnv::at_root(&dir);
+        let engine = crate::host::engine::engine(&env);
+        let request = CreateRequest {
+            version: "1.20.1".to_string(),
+            loader: LoaderKind::Forge,
+            loader_version: "47.2.0".to_string(),
+            name: "proc".to_string(),
+        };
+        let (tx, rx) = channel();
+        Self {
+            journal: Journal::open(&env),
+            meter: Arc::new(Mutex::new(Meter::new(&request, 1))),
+            cancel: Arc::new(AtomicBool::new(false)),
+            dir,
+            env,
+            engine,
+            tx,
+            rx,
+        }
+    }
+
+    pub(super) fn reporter(&self) -> Reporter<'_> {
+        Reporter {
+            tx: &self.tx,
+            meter: &self.meter,
+            journal: &self.journal,
+        }
+    }
+
+    /// 进度面板收到的所有文案。
+    pub(super) fn messages(&self) -> Vec<String> {
+        self.rx
+            .try_iter()
+            .filter_map(|task| match task {
+                HostTask::Install { progress, .. } => Some(progress.message.clone()),
+                _ => None,
+            })
+            .collect()
+    }
+
+    /// 装日志全文。
+    pub(super) fn log(&self) -> String {
+        std::fs::read_to_string(self.journal.path()).unwrap_or_default()
+    }
+}
+
+impl Drop for Harness {
+    fn drop(&mut self) {
+        std::fs::remove_dir_all(&self.dir).ok();
+    }
+}
+
+/// 注入用的假后端：回放预置结果 + 记录调用顺序与被组出来的命令行。
+pub(super) struct Fake {
+    pub(super) libraries_ok: bool,
+    pub(super) java: Option<JavaRuntime>,
+    pub(super) run_error: Option<ProcessorError>,
+    calls: RefCell<Vec<&'static str>>,
+    steps: RefCell<Vec<StepView>>,
+}
+
+impl Fake {
+    pub(super) fn new() -> Self {
+        Self {
+            libraries_ok: true,
+            java: Some(java()),
+            run_error: None,
+            calls: RefCell::new(Vec::new()),
+            steps: RefCell::new(Vec::new()),
+        }
+    }
+
+    pub(super) fn calls(&self) -> Vec<&'static str> {
+        self.calls.borrow().clone()
+    }
+
+    /// 被组出来的每步（序号 / 坐标 / 参数 / classpath 条数）。
+    pub(super) fn steps(&self) -> Vec<StepView> {
+        self.steps.borrow().clone()
+    }
+}
+
+impl Backend for Fake {
+    fn download_libraries(
+        &self,
+        _engine: &DownloadEngine,
+        files: &[PlanFile],
+        _sink: Option<ProgressSink>,
+    ) -> InstallReport {
+        self.calls.borrow_mut().push("libraries");
+        let ok = self.libraries_ok;
+        let outcomes = files
+            .iter()
+            .map(|file| FileOutcome {
+                role: file.role,
+                name: file.name.clone(),
+                dest: file.dest.clone(),
+                status: if ok {
+                    FileStatus::Skipped
+                } else {
+                    FileStatus::Failed
+                },
+                bytes: 0,
+                source: None,
+                failure: (!ok).then(|| FileFailure {
+                    kind: DownloadErrorKind::Network,
+                    message: "连接超时".to_string(),
+                }),
+            })
+            .collect();
+        InstallReport {
+            files: outcomes,
+            version_json: None,
+            warnings: Vec::new(),
+        }
+    }
+
+    fn select_java(&self, _managed: &Path, _requirement: &JavaRequirement) -> Option<JavaRuntime> {
+        self.calls.borrow_mut().push("java");
+        self.java.clone()
+    }
+
+    fn run(
+        &self,
+        plan: &ProcessorPlan,
+        java: &JavaRuntime,
+        sink: Option<StepSink>,
+    ) -> Result<ProcessorRun, ProcessorError> {
+        self.calls.borrow_mut().push("run");
+        *self.steps.borrow_mut() = plan
+            .steps
+            .iter()
+            .map(|step| {
+                (
+                    step.index,
+                    step.label.clone(),
+                    step.args.clone(),
+                    step.classpath.len(),
+                )
+            })
+            .collect();
+        if let Some(error) = &self.run_error {
+            return Err(error.clone());
+        }
+        let outcomes: Vec<StepOutcome> = plan
+            .steps
+            .iter()
+            .map(|step| StepOutcome {
+                index: step.index,
+                label: step.label.clone(),
+                status: StepStatus::Executed,
+                outputs: step.outputs.len(),
+                elapsed_ms: 12,
+                stdout_tail: None,
+                stderr_tail: None,
+            })
+            .collect();
+        if let Some(sink) = &sink {
+            for outcome in &outcomes {
+                sink(outcome);
+            }
+        }
+        Ok(ProcessorRun {
+            java: java.clone(),
+            steps: outcomes,
+            warnings: Vec::new(),
+        })
+    }
+}
+
+/// 一个主版本已知的假 Java。
+pub(super) fn java() -> JavaRuntime {
+    JavaRuntime {
+        binary: PathBuf::from("java"),
+        origin: JavaOrigin::Managed,
+        version: Some("21.0.4".to_string()),
+        major: Some(21),
+        bits: 64,
+        vendor: Some("temurin".to_string()),
+    }
+}
+
+/// 一个最小可用的 install profile：一个 client 侧 processor、两个字面量参数。
+pub(super) fn profile() -> InstallProfile {
+    let mut profile = InstallProfile::default();
+    profile.processors.push(Processor {
+        sides: vec!["client".to_string()],
+        jar: Some("net.minecraftforge:installertools:1.3.0".to_string()),
+        classpath: vec!["net.minecraftforge:jarsplitter:1.1.4".to_string()],
+        args: vec!["--task".to_string(), "'MCP_DATA'".to_string()],
+        ..Processor::default()
+    });
+    profile
+}
+
+pub(super) fn input<'a>(profile: &'a InstallProfile, installer: &'a Path) -> StageInput<'a> {
+    StageInput {
+        kind: CoreLoaderKind::Forge,
+        mc_version: "1.20.1",
+        version_id: "1.20.1-forge-47.2.0",
+        profile: Some(profile),
+        installer: Some(installer),
+        installed: false,
+    }
+}
+
+pub(super) fn installer() -> PathBuf {
+    PathBuf::from("cache/meta/forge-installer.jar")
+}
+
+pub(super) fn outcome(status: StepStatus) -> StepOutcome {
+    StepOutcome {
+        index: 3,
+        label: "net.minecraftforge:installertools:1.3.0".to_string(),
+        status,
+        outputs: 2,
+        elapsed_ms: 1234,
+        stdout_tail: None,
+        stderr_tail: None,
+    }
+}
diff --git a/crates/presenter/src/host/install_processors_tests.rs b/crates/presenter/src/host/install_processors_tests.rs
new file mode 100644
index 0000000..dc22eed
--- /dev/null
+++ b/crates/presenter/src/host/install_processors_tests.rs
@@ -0,0 +1,213 @@
+//! host/install_processors.rs 的单测（拆文件守 400 行上限）。
+//!
+//! 夹具在 [`super::fixture`]：这里只断言「计划怎么组」「找不到 Java 怎么说」
+//! 「哪一步挂了怎么报」「进度文案长什么样」。
+
+use std::path::PathBuf;
+
+use unlucky_core::addon::loader::forge::InstallProfile;
+use unlucky_core::addon::loader::processors::{ProcessorError, StepStatus};
+use unlucky_core::addon::loader::LoaderKind as CoreLoaderKind;
+use unlucky_core::download::DownloadErrorKind;
+use unlucky_core::game::install::{FileFailure, FileOutcome, FileRole, FileStatus, InstallReport};
+use unlucky_core::game::java::JavaRequirement;
+
+use super::fixture::{input, installer, outcome, profile, Fake, Harness};
+use super::{diagnostic, java_missing, libraries_failed, stage, step_line, StageInput};
+
+#[test]
+fn step_line_names_the_step_and_marks_the_outcome() {
+    let executed = step_line(&outcome(StepStatus::Executed), 9);
+    assert_eq!(
+        executed,
+        "installer 处理器 3/9：net.minecraftforge:installertools:1.3.0（1234 ms）"
+    );
+    let skipped = step_line(&outcome(StepStatus::Skipped), 9);
+    assert!(skipped.contains("产物已就绪"), "{skipped}");
+}
+
+#[test]
+fn diagnostic_keeps_the_stable_code_and_the_hint() {
+    let failed = ProcessorError::failed("net.minecraftforge:installertools:1.3.0", "1", "boom")
+        .with_hint("确认 Java 版本与磁盘权限");
+    let text = diagnostic(&failed);
+    assert!(text.contains("processor_failed"), "{text}");
+    assert!(text.contains("退出码 1"), "{text}");
+    assert!(text.contains("boom"), "stderr 尾部要留：{text}");
+    assert!(text.contains("建议：确认 Java 版本"), "{text}");
+
+    let plan = diagnostic(&ProcessorError::plan("install profile 缺 `jar`"));
+    assert!(plan.contains("processor_plan"), "{plan}");
+}
+
+#[test]
+fn java_missing_points_at_the_java_page() {
+    let managed = PathBuf::from("/tmp/.ULL/java");
+    let text = java_missing(&JavaRequirement::table(21, None), &managed);
+    assert!(text.contains("Java 21+"), "{text}");
+    assert!(text.contains("Java」页"), "{text}");
+    assert!(text.contains("JAVA_HOME"), "{text}");
+    assert!(text.contains(&managed.display().to_string()), "{text}");
+}
+
+#[test]
+fn libraries_failed_lists_at_most_three() {
+    let files: Vec<FileOutcome> = (0..4)
+        .map(|index| FileOutcome {
+            role: FileRole::Library,
+            name: format!("lib{index}.jar"),
+            dest: PathBuf::from(format!("lib{index}.jar")),
+            status: FileStatus::Failed,
+            bytes: 0,
+            source: None,
+            failure: Some(FileFailure {
+                kind: DownloadErrorKind::Network,
+                message: "连接超时".to_string(),
+            }),
+        })
+        .collect();
+    let report = InstallReport {
+        files,
+        version_json: None,
+        warnings: Vec::new(),
+    };
+    let text = libraries_failed(&report);
+    assert!(text.contains("4 个失败，共 4 个"), "{text}");
+    assert!(text.contains("lib0.jar"), "{text}");
+    assert!(!text.contains("lib3.jar"), "最多列三条：{text}");
+}
+
+#[test]
+fn stage_skips_when_the_version_json_is_already_there() {
+    let h = Harness::new();
+    let installer = installer();
+    let profile = profile();
+    let mut input = input(&profile, &installer);
+    input.installed = true;
+    let fake = Fake::new();
+    let result = stage(&h.env, &h.engine, &input, &fake, &h.reporter(), &h.cancel);
+    assert!(matches!(result, Ok(None)));
+    assert!(fake.calls().is_empty(), "已装完就不该再动网络/Java");
+    assert!(h.log().contains("跳过 installer processors"), "{}", h.log());
+}
+
+#[test]
+fn stage_skips_an_empty_processor_list() {
+    let h = Harness::new();
+    let installer = installer();
+    let profile = InstallProfile::default();
+    let input = input(&profile, &installer);
+    let fake = Fake::new();
+    let result = stage(&h.env, &h.engine, &input, &fake, &h.reporter(), &h.cancel);
+    assert!(matches!(result, Ok(None)), "没有 processor 就没这段");
+    assert!(fake.calls().is_empty());
+}
+
+#[test]
+fn stage_reports_missing_installer_metadata() {
+    let h = Harness::new();
+    let input = StageInput {
+        kind: CoreLoaderKind::Forge,
+        mc_version: "1.20.1",
+        version_id: "1.20.1-forge-47.2.0",
+        profile: None,
+        installer: None,
+        installed: false,
+    };
+    let fake = Fake::new();
+    let err = stage(&h.env, &h.engine, &input, &fake, &h.reporter(), &h.cancel).unwrap_err();
+    assert!(err.contains("install profile"), "{err}");
+    assert!(h.log().contains("失败："), "{}", h.log());
+}
+
+#[test]
+fn stage_builds_the_command_line_from_the_install_profile() {
+    let h = Harness::new();
+    let installer = installer();
+    let profile = profile();
+    let input = input(&profile, &installer);
+    let fake = Fake::new();
+    let run = stage(&h.env, &h.engine, &input, &fake, &h.reporter(), &h.cancel)
+        .expect("stage 成功")
+        .expect("应当真的跑了 processors");
+    assert_eq!(run.executed(), 1);
+    let steps = fake.steps();
+    assert_eq!(steps.len(), 1);
+    let (index, label, args, classpath) = &steps[0];
+    assert_eq!(*index, 1);
+    assert_eq!(label, "net.minecraftforge:installertools:1.3.0");
+    assert_eq!(args, &vec!["--task".to_string(), "MCP_DATA".to_string()]);
+    assert_eq!(*classpath, 1, "jar 自己不在 -cp 里（拼命令行时才补）");
+    assert_eq!(fake.calls(), vec!["libraries", "java", "run"]);
+    let messages = h.messages();
+    assert!(
+        messages.iter().any(|m| m.contains("installer 处理器 1/1")),
+        "面板要看到当前处理器：{messages:?}"
+    );
+    assert!(
+        messages
+            .last()
+            .is_some_and(|m| m.contains("正在写入版本清单")),
+        "{messages:?}"
+    );
+    assert!(
+        h.log().contains("processors 完成：执行 1 步"),
+        "{}",
+        h.log()
+    );
+}
+
+#[test]
+fn stage_fails_loudly_without_a_usable_java() {
+    let h = Harness::new();
+    let installer = installer();
+    let profile = profile();
+    let input = input(&profile, &installer);
+    let mut fake = Fake::new();
+    fake.java = None;
+    let err = stage(&h.env, &h.engine, &input, &fake, &h.reporter(), &h.cancel).unwrap_err();
+    assert!(err.contains("Java"), "{err}");
+    assert!(err.contains("托管目录"), "{err}");
+    assert_eq!(
+        fake.calls(),
+        vec!["libraries", "java"],
+        "没 Java 就不该起进程"
+    );
+    assert!(h.log().contains("失败："), "{}", h.log());
+}
+
+#[test]
+fn stage_fails_loudly_when_a_processor_exits_nonzero() {
+    let h = Harness::new();
+    let installer = installer();
+    let profile = profile();
+    let input = input(&profile, &installer);
+    let mut fake = Fake::new();
+    fake.run_error = Some(ProcessorError::failed(
+        "net.minecraftforge:installertools:1.3.0",
+        "1",
+        "java.lang.NoSuchMethodError",
+    ));
+    let err = stage(&h.env, &h.engine, &input, &fake, &h.reporter(), &h.cancel).unwrap_err();
+    assert!(err.contains("processor_failed"), "{err}");
+    assert!(err.contains("NoSuchMethodError"), "{err}");
+    let log = h.log();
+    assert!(log.contains("失败："), "{log}");
+    assert!(log.contains("NoSuchMethodError"), "日志要能回溯：{log}");
+}
+
+#[test]
+fn stage_reports_incomplete_library_downloads() {
+    let h = Harness::new();
+    let installer = installer();
+    let profile = profile();
+    let input = input(&profile, &installer);
+    let mut fake = Fake::new();
+    fake.libraries_ok = false;
+    let err = stage(&h.env, &h.engine, &input, &fake, &h.reporter(), &h.cancel).unwrap_err();
+    assert!(err.contains("依赖库没下全"), "{err}");
+    assert!(err.contains("连接超时"), "{err}");
+    assert_eq!(fake.calls(), vec!["libraries"], "库没下全就别去选 Java");
+    let progress = h.meter.lock().expect("进度锁").progress.clone();
+    assert!(progress.files_total >= 2, "依赖库要计入文件总数");
+}
diff --git a/crates/presenter/src/host/install_tests.rs b/crates/presenter/src/host/install_tests.rs
new file mode 100644
index 0000000..06dacbd
--- /dev/null
+++ b/crates/presenter/src/host/install_tests.rs
@@ -0,0 +1,218 @@
+//! host/install.rs 的单测（拆文件守 400 行上限）。
+
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
+use std::sync::{Arc, Mutex};
+
+use unlucky_core::game::install::{FileOutcome, FileRole, FileStatus};
+
+use super::{loader_label, run, supported, unsupported_reason, Job};
+use crate::dto::{CreateRequest, LoaderKind};
+use crate::host::env::HostEnv;
+use crate::host::install_journal::Journal;
+use crate::host::job::{channel, JobSender};
+use crate::host::meter::Meter;
+
+static SEQ: AtomicUsize = AtomicUsize::new(0);
+
+/// 一个装在临时根里的任务上下文（只走「联网前就返回」的用例）。
+struct Fixture {
+    dir: PathBuf,
+    env: HostEnv,
+    tx: JobSender,
+    meter: Arc<Mutex<Meter>>,
+    cancel: Arc<AtomicBool>,
+    journal: Journal,
+}
+
+impl Fixture {
+    fn new(request: &CreateRequest) -> Self {
+        let seq = SEQ.fetch_add(1, Ordering::SeqCst);
+        let dir =
+            std::env::temp_dir().join(format!("ull-host-install-{}-{seq}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        let env = HostEnv::at_root(&dir);
+        let journal = Journal::open(&env);
+        Self {
+            dir,
+            env,
+            tx: channel().0,
+            meter: Arc::new(Mutex::new(Meter::new(request, 1))),
+            cancel: Arc::new(AtomicBool::new(false)),
+            journal,
+        }
+    }
+
+    fn job(&self) -> Job<'_> {
+        Job {
+            env: &self.env,
+            tx: &self.tx,
+            meter: &self.meter,
+            cancel: &self.cancel,
+            journal: &self.journal,
+        }
+    }
+}
+
+impl Drop for Fixture {
+    fn drop(&mut self) {
+        std::fs::remove_dir_all(&self.dir).ok();
+    }
+}
+
+fn request(loader: LoaderKind, version: &str) -> CreateRequest {
+    CreateRequest {
+        version: version.to_string(),
+        loader,
+        loader_version: String::new(),
+        name: String::new(),
+    }
+}
+
+/// 一个「刚下完」的文件结局（记账用）。
+fn downloaded(bytes: u64) -> FileOutcome {
+    FileOutcome {
+        role: FileRole::Library,
+        name: "lib.jar".to_string(),
+        dest: PathBuf::from("lib.jar"),
+        status: FileStatus::Downloaded,
+        bytes,
+        source: None,
+        failure: None,
+    }
+}
+
+#[test]
+fn progress_is_pre_accounted_across_segments_so_the_bar_never_snaps_to_full() {
+    // M45 r1 P2-2 的回归：处理器依赖库下完那一刻，面板曾显示 36/36 满格 + 3.4MB/10MB，
+    // 之后加载器库的 29 个文件才被计入 → 进度条从 100% 回落到 55% 再涨回去。
+    let request = request(LoaderKind::Forge, "1.20.1");
+    let mut meter = Meter::new(&request, 1);
+
+    // 原版段：30 个文件全下完（install_vanilla 对总量是赋值，不是累加）
+    meter.progress.files_total = 30;
+    meter.progress.bytes_total = 3_000_000;
+    for _ in 0..30 {
+        meter.note(&downloaded(100_000));
+    }
+    assert!((meter.progress.ratio() - 1.0).abs() < f32::EPSILON);
+
+    // install_loader 的顺序：加载器库与处理器依赖库都在动手前一次预记账
+    meter.expect(29, 10_000_000);
+    meter.expect(36, 4_000_000);
+    assert_eq!(meter.progress.files_total, 95, "两段之和一次到位");
+    assert_eq!(
+        meter.progress.bytes_total, 17_000_000,
+        "字节是相加不是取最大"
+    );
+    assert!(
+        meter.progress.ratio() < 0.7,
+        "预记账后不能还停在满格：{}",
+        meter.progress.ratio()
+    );
+
+    // 处理器依赖库 36 个下完 → 仍没满格（加载器库还在后面）
+    for _ in 0..36 {
+        meter.note(&downloaded(110_000));
+    }
+    let ratio = meter.progress.ratio();
+    assert!(
+        (0.6..1.0).contains(&ratio),
+        "回落到中间态而不是满格：{ratio}"
+    );
+    assert!(
+        meter.progress.bytes_done < meter.progress.bytes_total,
+        "字节总量要覆盖已下载量：{}/{}",
+        meter.progress.bytes_done,
+        meter.progress.bytes_total
+    );
+
+    // 加载器库也下完 → 这时候才该是满格
+    for _ in 0..29 {
+        meter.note(&downloaded(340_000));
+    }
+    assert!((meter.progress.ratio() - 1.0).abs() < f32::EPSILON);
+}
+
+#[test]
+fn loader_support_matrix_is_explicit() {
+    // M45 语义变更：Forge/NeoForge 从「GUI 显式拒装」扩进受支持集合（走 installer processors）。
+    for kind in [
+        LoaderKind::Vanilla,
+        LoaderKind::Fabric,
+        LoaderKind::Quilt,
+        LoaderKind::Forge,
+        LoaderKind::NeoForge,
+    ] {
+        assert!(supported(kind), "{} 应当受支持", kind.label());
+    }
+    // 这两家 core 侧还没有安装管线，仍然显式拒装并说清去哪装。
+    for kind in [LoaderKind::OptiFine, LoaderKind::LiteLoader] {
+        assert!(!supported(kind), "{} 不该被当成可装", kind.label());
+        let reason = unsupported_reason(kind);
+        assert!(reason.contains(kind.label()), "{reason}");
+        assert!(reason.contains("还没有接入"), "{reason}");
+    }
+}
+
+#[test]
+fn forge_install_is_no_longer_refused_at_the_door() {
+    // 旧文案是把用户赶去终端跑 `ull install`；M45 之后 GUI 与 CLI 同一条路径。
+    assert!(supported(LoaderKind::Forge));
+    assert!(supported(LoaderKind::NeoForge));
+    assert_eq!(loader_label(LoaderKind::Forge, "47.2.0"), "Forge 47.2.0");
+    assert_eq!(
+        loader_label(LoaderKind::NeoForge, "21.1.80"),
+        "NeoForge 21.1.80"
+    );
+}
+
+#[test]
+fn meter_counts_files_and_skips_skipped_bytes() {
+    let request = CreateRequest {
+        version: "1.20.4".to_string(),
+        loader: LoaderKind::Fabric,
+        loader_version: "0.16.5".to_string(),
+        name: "生存".to_string(),
+    };
+    let mut meter = Meter::new(&request, 1);
+    assert_eq!(meter.progress.loader, "Fabric 0.16.5");
+    assert_eq!(meter.progress.instance, "生存");
+    meter.progress.files_total = 2;
+
+    let mut outcome = FileOutcome {
+        role: FileRole::Library,
+        name: "a.jar".to_string(),
+        dest: PathBuf::from("a.jar"),
+        status: FileStatus::Downloaded,
+        bytes: 100,
+        source: Some("bmclapi".to_string()),
+        failure: None,
+    };
+    meter.note(&outcome);
+    assert_eq!(meter.progress.files_done, 1);
+    assert_eq!(meter.progress.bytes_done, 100);
+
+    outcome.status = FileStatus::Skipped;
+    outcome.bytes = 500;
+    meter.note(&outcome);
+    assert_eq!(meter.progress.files_done, 2);
+    assert_eq!(meter.progress.bytes_done, 100, "跳过的文件不计入已下载字节");
+    assert!((meter.progress.ratio() - 1.0).abs() < f32::EPSILON);
+}
+
+#[test]
+fn empty_version_is_rejected_before_network() {
+    let request = request(LoaderKind::Vanilla, "");
+    let fixture = Fixture::new(&request);
+    let err = run(&fixture.job(), &request).unwrap_err();
+    assert!(err.contains("没有选择版本"), "{err}");
+}
+
+#[test]
+fn unsupported_loader_is_rejected_before_network() {
+    let request = request(LoaderKind::OptiFine, "1.20.1");
+    let fixture = Fixture::new(&request);
+    let err = run(&fixture.job(), &request).unwrap_err();
+    assert!(err.contains("还没有接入"), "{err}");
+}
diff --git a/crates/presenter/src/host/java.rs b/crates/presenter/src/host/java.rs
new file mode 100644
index 0000000..71229bb
--- /dev/null
+++ b/crates/presenter/src/host/java.rs
@@ -0,0 +1,304 @@
+//! Java 页：四家发行版 + 回退链可视化 + 本地运行时 + 托管 JDK 安装。
+//!
+//! 回退链的两态：
+//! - **计划链**（还没装）：按生效顺序铺一排「待尝试」，让用户先看清会按什么顺序找；
+//! - **真实链**（装过一次/装失败）：`core::game::java::ChainLog` 的每跳结局与原因。
+//!
+//! 安装走 `java::install`（core 自己跑回退链），host 只负责把 `ChainLog` 翻成 DTO。
+
+use unlucky_core::game::java::probe::JavaOrigin;
+use unlucky_core::game::java::source::ChainLog;
+use unlucky_core::game::java::{self, JdkVendor};
+
+use crate::dto::{JavaChainOutcome, JavaChainStep, JavaPageView, JavaRuntimeView, JavaVendorView};
+
+use super::env::HostEnv;
+use super::job::{spawn, HostTask, JobSender};
+
+/// 托管 JDK 的默认目标大版本（D13 基准 JDK17）。
+pub const DEFAULT_JDK_MAJOR: u32 = 17;
+
+/// 该装哪个大版本：取第一个实例版本的要求，没有实例就给 17。
+pub fn target_major(env: &HostEnv) -> u32 {
+    let profiles = super::game::profiles(env);
+    profiles
+        .profiles
+        .first()
+        .map(|profile| {
+            java::requirement_for_version(&env.game, &profile.version_id)
+                .minimum
+                .max(8)
+        })
+        .unwrap_or(DEFAULT_JDK_MAJOR)
+}
+
+/// 四家发行版的展示行（镜像与吞吐口径与 CLI `ull java vendors` 一致）。
+pub fn vendors(env: &HostEnv, installed_vendors: &[String]) -> Vec<JavaVendorView> {
+    let domestic = super::engine::domestic(env);
+    let order = java::vendor::order(&super::engine::java_priority(env), domestic);
+    let table = unlucky_core::download::MirrorTable::builtin();
+    order
+        .iter()
+        .enumerate()
+        .map(|(index, vendor)| {
+            let id = vendor.id();
+            JavaVendorView {
+                id: id.to_string(),
+                display: vendor.display().to_string(),
+                rank: u32::try_from(index + 1).unwrap_or(u32::MAX),
+                majors: vendor
+                    .hint_majors()
+                    .iter()
+                    .map(u32::to_string)
+                    .collect::<Vec<_>>()
+                    .join("/"),
+                sources: sources_of(&table, *vendor),
+                installed: installed_vendors.iter().any(|known| known == id),
+            }
+        })
+        .collect()
+}
+
+/// 一家的源清单（与 CLI 展示同形）。
+fn sources_of(table: &unlucky_core::download::MirrorTable, vendor: JdkVendor) -> Vec<String> {
+    match vendor {
+        JdkVendor::Temurin => table
+            .adoptium
+            .iter()
+            .filter(|mirror| mirror.enabled)
+            .map(|mirror| mirror.name.clone())
+            .chain(std::iter::once(
+                "GitHub 官方（国内套 gh-proxy）".to_string(),
+            ))
+            .collect(),
+        JdkVendor::Oracle => table
+            .oracle_mirrors()
+            .map(|mirror| format!("{} {}", mirror.name, mirror.base()))
+            .collect(),
+        JdkVendor::Microsoft => vec!["aka.ms → VS CDN（无国内镜像）".to_string()],
+        JdkVendor::Zulu => table
+            .zulu()
+            .map(|zulu| vec![format!("{}（{}）", zulu.api, zulu.measured_speed)])
+            .unwrap_or_default(),
+    }
+}
+
+/// 本地运行时（托管 / JAVA_HOME / PATH / 系统安装位置，同一路径只留优先级高者）。
+pub fn runtimes(env: &HostEnv) -> Vec<JavaRuntimeView> {
+    let roots = super::engine::java_scan_roots(env);
+    let candidates = java::discover::dedupe(java::candidates_in_roots(&roots));
+    candidates
+        .iter()
+        .map(|runtime| JavaRuntimeView {
+            binary: runtime.binary.display().to_string(),
+            version: runtime
+                .version
+                .clone()
+                .unwrap_or_else(|| "版本未知".to_string()),
+            major: runtime.major.unwrap_or(java::DEFAULT_MAJOR),
+            vendor: runtime.vendor.clone().unwrap_or_else(|| "—".to_string()),
+            origin: runtime.origin.category().to_string(),
+        })
+        .collect()
+}
+
+/// 托管目录（展示「装到哪」）。
+pub fn managed_roots(env: &HostEnv) -> Vec<String> {
+    super::engine::java_scan_roots(env)
+        .iter()
+        .map(|root| root.display().to_string())
+        .collect()
+}
+
+/// 计划链（按生效顺序铺「待尝试」）。
+pub fn planned_chain(env: &HostEnv) -> Vec<JavaChainStep> {
+    let domestic = super::engine::domestic(env);
+    let order = java::vendor::order(&super::engine::java_priority(env), domestic);
+    order
+        .iter()
+        .map(|vendor| JavaChainStep {
+            vendor: vendor.id().to_string(),
+            outcome: JavaChainOutcome::Pending,
+            detail: String::new(),
+        })
+        .collect()
+}
+
+/// 真实链（`ChainLog` → DTO）。
+pub fn chain_steps(log: &ChainLog) -> Vec<JavaChainStep> {
+    log.attempts()
+        .iter()
+        .map(|attempt| JavaChainStep {
+            vendor: attempt.vendor.id().to_string(),
+            outcome: if attempt.ok {
+                JavaChainOutcome::Hit
+            } else if attempt.detail.contains("不支持") {
+                JavaChainOutcome::Skip
+            } else {
+                JavaChainOutcome::Failed
+            },
+            detail: attempt.detail.clone(),
+        })
+        .collect()
+}
+
+/// 整页快照。
+pub fn page(env: &HostEnv, chain: Vec<JavaChainStep>, busy: bool, message: &str) -> JavaPageView {
+    let runtimes = runtimes(env);
+    let installed_vendors: Vec<String> = runtimes
+        .iter()
+        .filter(|runtime| runtime.origin == JavaOrigin::Managed.category())
+        .map(|runtime| runtime.vendor.clone())
+        .collect();
+    let vendor_rows = vendors(env, &installed_vendors);
+    let domestic = super::engine::domestic(env);
+    let priority_set = !super::engine::java_priority(env).is_empty();
+    let chain = if chain.is_empty() {
+        planned_chain(env)
+    } else {
+        chain
+    };
+    JavaPageView {
+        region: if domestic { "domestic" } else { "global" }.to_string(),
+        priority_source: if priority_set {
+            "java.vendorPriority"
+        } else {
+            "region_default"
+        }
+        .to_string(),
+        order_text: vendor_rows
+            .iter()
+            .map(|vendor| vendor.display.clone())
+            .collect::<Vec<_>>()
+            .join(" → "),
+        vendors: vendor_rows,
+        chain,
+        runtimes,
+        managed_roots: managed_roots(env),
+        busy,
+        message: message.to_string(),
+    }
+}
+
+/// 后台装一个托管 JDK（`vendor` 为空 = 按回退链自己选）。
+pub fn spawn_install(env: HostEnv, tx: JobSender, vendor: Option<JdkVendor>) {
+    spawn("java-install", move || {
+        let major = target_major(&env);
+        let mut busy = page(&env, Vec::new(), true, &format!("正在安装 Java {major}…"));
+        busy.busy = true;
+        let _ = tx.send(HostTask::Java(Box::new(busy)));
+
+        let engine = super::engine::engine(&env);
+        let root = match super::engine::java_install_root(&env) {
+            Ok(root) => root,
+            Err(reason) => {
+                let _ = tx.send(HostTask::Java(Box::new(page(
+                    &env,
+                    Vec::new(),
+                    false,
+                    &format!("解析 Java 安装位置失败：{reason}"),
+                ))));
+                return;
+            }
+        };
+        let request = match vendor {
+            Some(vendor) => java::InstallRequest::with_vendor(major, vendor)
+                .with_priority(super::engine::java_priority(&env)),
+            None => {
+                java::InstallRequest::new(major).with_priority(super::engine::java_priority(&env))
+            }
+        };
+        let result =
+            unlucky_core::download::blocking::block_on(java::install(&engine, &root, request));
+        match result {
+            Ok(installed) => {
+                let message = if installed.reused() {
+                    format!(
+                        "Java {}（{}）已就绪：{}",
+                        installed.major,
+                        installed.vendor.id(),
+                        installed.root.display()
+                    )
+                } else {
+                    format!(
+                        "已安装 Java {}（{}）→ {} · {} 个文件",
+                        installed.major,
+                        installed.vendor.display(),
+                        installed.root.display(),
+                        installed.files
+                    )
+                };
+                let chain = chain_steps(&installed.chain);
+                let _ = tx.send(HostTask::Java(Box::new(page(&env, chain, false, &message))));
+            }
+            Err(error) => {
+                let _ = tx.send(HostTask::Java(Box::new(page(
+                    &env,
+                    Vec::new(),
+                    false,
+                    &format!("Java 安装失败：{error}"),
+                ))));
+            }
+        }
+    });
+}
+
+/// 「安装一个 Java」的 UI 文案（下载页 Java 分组的按钮说明）。
+pub fn install_hint(env: &HostEnv) -> String {
+    let major = target_major(env);
+    format!("按回退链取一个 Java {major}（托管目录，装完自动被启动链选中）")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn planned_chain_covers_four_vendors() {
+        let dir = std::env::temp_dir().join(format!("ull-host-java-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        let env = HostEnv::at_root(&dir);
+        std::fs::create_dir_all(env.layout.config()).expect("config");
+        let chain = planned_chain(&env);
+        assert_eq!(chain.len(), 4);
+        assert!(chain
+            .iter()
+            .all(|step| step.outcome == JavaChainOutcome::Pending));
+        assert_eq!(chain[0].vendor, "temurin", "国内/国外默认都是 Temurin 第一");
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn chain_log_maps_to_steps() {
+        let mut log = ChainLog::new();
+        log.skip(
+            JdkVendor::Microsoft,
+            "不支持 Java 8（microsoft 只发 11/17/21/25）",
+        );
+        log.hit(JdkVendor::Temurin, "命中 Adoptium 17");
+        let steps = chain_steps(&log);
+        assert_eq!(steps.len(), 2);
+        assert_eq!(steps[0].outcome, JavaChainOutcome::Skip);
+        assert_eq!(steps[1].outcome, JavaChainOutcome::Hit);
+    }
+
+    #[test]
+    fn page_reports_region_and_priority_source() {
+        let dir = std::env::temp_dir().join(format!("ull-host-java-page-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        let env = HostEnv::at_root(&dir);
+        std::fs::create_dir_all(env.layout.config()).expect("config");
+        std::fs::write(
+            env.launcher_config(),
+            r#"{"java":{"vendorPriority":["zulu"]}}"#,
+        )
+        .expect("写配置");
+        let page = page(&env, Vec::new(), false, "");
+        assert_eq!(page.priority_source, "java.vendorPriority");
+        assert_eq!(page.vendors[0].id, "zulu");
+        assert_eq!(page.vendors[0].rank, 1);
+        assert!(page.order_text.contains("Azul Zulu"));
+        assert_eq!(page.vendors.len(), 4);
+        std::fs::remove_dir_all(&dir).ok();
+    }
+}
diff --git a/crates/presenter/src/host/job.rs b/crates/presenter/src/host/job.rs
new file mode 100644
index 0000000..74b497c
--- /dev/null
+++ b/crates/presenter/src/host/job.rs
@@ -0,0 +1,198 @@
+//! 后台任务的回流消息：`HostTask` 是唯一「线程 → host」的载荷。
+//!
+//! 线程只做 core 调用（网络/磁盘），产出的都是 `crate::dto` 的 DTO；
+//! host 的 `tick` 把它们翻成 [`crate::dto::CoreEvent`]。
+//! 这样「跨线程传的是什么」在一处看全，也不会出现半成品领域类型漏回 UI。
+
+use std::sync::mpsc::{Receiver, Sender};
+
+use crate::dto::{
+    // 主线（M109 ContentResults / M105 LoaderKind / M113 PackEvent）与 M114 的账户轨并集。
+    AccountView,
+    AuthlibLoginView,
+    ContentResults,
+    DeviceLoginView,
+    DiagnosisReport,
+    InstallProgressView,
+    InstanceId,
+    InstanceRuntime,
+    JavaPageView,
+    LaunchFinished,
+    LiveLogBatch,
+    LoaderKind,
+    LogLine,
+    LogOutcome,
+    LogSession,
+    NoticeView,
+    PackEvent,
+    SessionId,
+    SkinImage,
+    VersionSummary,
+};
+use crate::toast::Toast;
+
+/// 后台任务 → host 的消息。
+#[derive(Debug, Clone, PartialEq)]
+pub enum HostTask {
+    /// 版本清单（下载页）
+    Versions(Result<Vec<VersionSummary>, String>),
+    /// 加载器版本清单（下载页「安装选项」的下拉）
+    LoaderVersions {
+        /// 加载器种类
+        kind: LoaderKind,
+        /// 目标原版版本（缓存键的一部分，回传原样）
+        mc_version: String,
+        /// `Ok(最新在前)` / `Err(人读原因)`
+        result: Result<Vec<String>, String>,
+    },
+    /// 内容库检索（M109；`Err` = 一句人读原因）
+    Content(Box<Result<ContentResults, String>>),
+    // M113: import/export
+    /// 导入/导出（M113）：一条事件 + 任务代次
+    ///
+    /// 代次是 **pack 自己的一条**（`host::addon::pack` 的 `pack_epoch()`，按 host 分开），**不**与
+    /// [`HostTask::Install`] 的 `CoreHost::install_epoch` 共用 —— 共用会让「关一次导入面板」
+    /// 把下载页正在跑的安装静默丢掉（复审 r1 P2-7）。取消/关面板之后回来的旧事件按这条代次
+    /// 丢掉，面板不会被重新点亮。
+    Pack {
+        /// 事件载荷（进度 / 结果 / 探测诊断 / 预检 / 完成）
+        event: Box<PackEvent>,
+        /// 任务代次
+        epoch: u64,
+    },
+    /// 安装进度（高频，host 只做聚合与转发）
+    Install {
+        /// 进度快照
+        progress: Box<InstallProgressView>,
+        /// 任务代次（[`super::CoreHost`] 的 `install_epoch`）
+        ///
+        /// 取消/重新开工都会把代次 +1，于是**旧任务还在飞的事件**带着旧代次回来，
+        /// host 一眼就能认出来并丢掉。没有这一层的话：取消后 `InstallProgress(None)` 刚把面板
+        /// 收回，下一条「下载中」事件立刻把它点亮——用户看到的就是「点了取消没反应」（M105 实测）。
+        epoch: u64,
+    },
+    /// 安装收尾（成功带实例名，失败带文案）
+    InstallDone {
+        /// 最终进度快照
+        progress: Box<InstallProgressView>,
+        /// 成功时为 `Ok(实例名)`
+        result: Result<String, String>,
+        /// 任务代次（语义同 [`HostTask::Install`] 的 `epoch`）
+        epoch: u64,
+    },
+    /// 账户列表
+    Accounts(Vec<AccountView>),
+    /// 设备码登录状态
+    Login(Box<DeviceLoginView>),
+    /// 第三方轨（authlib-injector）登录/校验状态
+    Authlib(Box<AuthlibLoginView>),
+    /// 账户皮肤抓取结果（`skin = None` = 没取到；UI 退回首字母块）
+    Avatar {
+        /// 账户 id
+        id: String,
+        /// 皮肤原图
+        skin: Option<SkinImage>,
+    },
+    /// Java 页（发行版/回退链/运行时）
+    Java(Box<JavaPageView>),
+    /// 日志页快照（会话列表 + 选中会话的行 + 诊断）
+    Logs {
+        /// 会话列表
+        sessions: Vec<LogSession>,
+        /// 选中会话的行
+        lines: Vec<LogLine>,
+        /// 诊断结论
+        diagnosis: Option<DiagnosisReport>,
+    },
+    /// 实时日志增量
+    Tail(Box<LiveLogBatch>),
+    /// 启动开始（pid + 会话 id）
+    LaunchStarted {
+        /// 实例 id
+        id: InstanceId,
+        /// 会话 id
+        session_id: SessionId,
+        /// 进程号
+        pid: u32,
+    },
+    /// 启动阶段推进（磁贴进度环）
+    Runtime {
+        /// 实例 id
+        id: InstanceId,
+        /// 阶段状态
+        runtime: InstanceRuntime,
+    },
+    /// 启动收尾
+    LaunchEnd(Box<LaunchFinished>),
+    /// 崩溃日志导入的分析结论
+    Crash(Box<DiagnosisReport>),
+    /// 横幅通知（隔离切换提示等）
+    Notice(Box<NoticeView>),
+    /// Toast
+    Toast(Box<Toast>),
+    /// 会话列表刷新（只换左栏）
+    Sessions(Vec<LogSession>),
+}
+
+/// 后台线程用的发送端（`Sender` 克隆即可）。
+pub type JobSender = Sender<HostTask>;
+
+/// host 侧的接收端。
+pub type JobReceiver = Receiver<HostTask>;
+
+/// 建一对通道。
+pub fn channel() -> (JobSender, JobReceiver) {
+    std::sync::mpsc::channel()
+}
+
+/// 起一个带名字的后台线程（名字只进 panic 信息，方便定位）。
+pub fn spawn(name: &str, job: impl FnOnce() + Send + 'static) -> std::thread::JoinHandle<()> {
+    std::thread::Builder::new()
+        .name(format!("ull-host-{name}"))
+        .spawn(job)
+        .unwrap_or_else(|error| panic!("起不来后台线程 {name}: {error}"))
+}
+
+/// 人读一行「启动结束」。
+pub fn launch_summary(outcome: LogOutcome, exit_code: Option<i32>) -> String {
+    match outcome {
+        LogOutcome::Ok => "正常退出".to_string(),
+        LogOutcome::Crashed => match exit_code {
+            Some(code) => format!("崩溃（exit {code}）"),
+            None => "崩溃".to_string(),
+        },
+        LogOutcome::SilentFail => "静默失败（exit 0 但游戏没起来）".to_string(),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn channel_carries_tasks_across_threads() {
+        let (tx, rx) = channel();
+        let handle = spawn("test", move || {
+            tx.send(HostTask::Toast(Box::new(Toast {
+                id: 1,
+                kind: crate::toast::ToastKind::Info,
+                text: "hi".to_string(),
+                remaining_ms: 0,
+            })))
+            .expect("发送");
+        });
+        handle.join().expect("线程结束");
+        let task = rx.recv().expect("收到");
+        assert!(matches!(task, HostTask::Toast(toast) if toast.text == "hi"));
+    }
+
+    #[test]
+    fn launch_summary_names_the_outcome() {
+        assert_eq!(launch_summary(LogOutcome::Ok, Some(0)), "正常退出");
+        assert_eq!(
+            launch_summary(LogOutcome::Crashed, Some(1)),
+            "崩溃（exit 1）"
+        );
+        assert!(launch_summary(LogOutcome::SilentFail, Some(0)).contains("静默"));
+    }
+}
diff --git a/crates/presenter/src/host/launch.rs b/crates/presenter/src/host/launch.rs
new file mode 100644
index 0000000..48b2175
--- /dev/null
+++ b/crates/presenter/src/host/launch.rs
@@ -0,0 +1,353 @@
+//! 启动全链：实例 → `LaunchRequest` → 子进程 → JSONL 事件流（GUI 版）。
+//!
+//! 与 CLI `ull launch` 同源同序（`core` 的 `game::resolve` / `arguments.expand` /
+//! `launch::adapter::build_request` / `Launcher::spawn`），差异只有两处：
+//! - **不阻塞 UI**：装配与等待都在后台线程里，进度/日志经 [`super::job::HostTask`] 回流；
+//! - **身份来自 GUI 选中的账户**（`AccountStore` → `AuthPlaceholders`），凭据只在
+//!   本模块内被读一次，绝不进 DTO。
+//!
+//! 停止：`kill_tree(pid)`（core 的三段式进程树回收），`finish()` 会照常收尾写索引。
+
+use std::path::PathBuf;
+
+use unlucky_core::game::arguments::Environment;
+use unlucky_core::game::install::instance::read_instance_config;
+use unlucky_core::game::isolation::{derive_game_dir, observe_mode, IsolationMode};
+use unlucky_core::game::{self, VersionJson};
+use unlucky_core::launch::adapter::{
+    self, AdapterOptions, AdapterWarning, LibraryInput, SnapshotInput,
+};
+use unlucky_core::launch::request::{JavaSelection, LaunchRequest, MemoryOptions};
+use unlucky_core::launch::time::{format_rfc3339_millis, now};
+use unlucky_core::launch::tree_kill;
+use unlucky_core::launch::{Launcher, LauncherConfig};
+use unlucky_core::platform::paths::ProcessEnv;
+
+use crate::dto::{
+    InstanceId, InstanceRuntime, LaunchFinished, LaunchStage, LoaderKind, LogOutcome, Progress,
+};
+
+use super::env::HostEnv;
+use super::job::{launch_summary, HostTask, JobSender};
+
+/// 启动器名（与 CLI `meta::LAUNCHER_NAME` 同值）。
+pub const LAUNCHER_NAME: &str = "Unlucky Launcher";
+
+/// 一次启动需要的实例信息。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LaunchTarget {
+    /// 实例 id
+    pub id: InstanceId,
+    /// 实例名
+    pub name: String,
+    /// 绑定的版本 id
+    pub version_id: String,
+    /// 账户 id（`None` = 离线占位）
+    pub account: Option<String>,
+}
+
+/// 选中并用起来的 Java（`summary` 给 UI 一行提示）。
+pub struct JavaPick {
+    /// 交给 adapter 的选择
+    pub selection: JavaSelection,
+    /// 人读一行
+    pub summary: String,
+}
+
+/// 选一个能用的 Java：托管 > JAVA_HOME > PATH（`core::game::java` 的探测与优先级）。
+pub fn pick_java(env: &HostEnv, version_id: &str) -> JavaPick {
+    let store = env.store();
+    let install_root = store
+        .doc()
+        .effective_str("java.installRoot")
+        .map(str::trim)
+        .filter(|text| !text.is_empty())
+        .map(PathBuf::from);
+    let roots = unlucky_core::game::java::location::scan_roots(
+        env.mode(),
+        &env.layout,
+        install_root.as_deref(),
+        env.platform,
+        &ProcessEnv,
+    );
+    let candidates = unlucky_core::game::java::candidates_in_roots(&roots);
+    let required = unlucky_core::game::java::requirement_for_version(&env.game, version_id);
+    let picked = unlucky_core::game::java::pick(&candidates, &required).cloned();
+    match picked {
+        Some(runtime) => {
+            let major = runtime
+                .major
+                .unwrap_or(unlucky_core::game::java::DEFAULT_MAJOR);
+            let summary = format!(
+                "Java {}（{}{}）",
+                runtime.version.clone().unwrap_or_else(|| major.to_string()),
+                runtime.origin.category(),
+                runtime
+                    .vendor
+                    .as_ref()
+                    .map(|vendor| format!(" · {vendor}"))
+                    .unwrap_or_default()
+            );
+            JavaPick {
+                selection: JavaSelection::new(runtime.binary, major, runtime.bits),
+                summary,
+            }
+        }
+        None => {
+            let binary = PathBuf::from(unlucky_core::game::java::java_binary_name());
+            let major = required.minimum;
+            JavaPick {
+                selection: JavaSelection::new(binary, major, 64),
+                summary: format!("PATH 上的 Java（未探测到版本，按 Java {major} 启动）"),
+            }
+        }
+    }
+}
+
+/// 装配 [`LaunchRequest`]（与 CLI `snapshot::prepare` 同序）。
+///
+/// # Errors
+///
+/// 版本 JSON 缺失/非法、继承链断裂、隔离派生失败时返回用户可读文案。
+pub fn build_request(
+    env: &HostEnv,
+    target: &LaunchTarget,
+) -> Result<(LaunchRequest, Vec<String>), String> {
+    let version_id = target.version_id.clone();
+    let manifest_path = env.game.version_json(&version_id);
+    let text = std::fs::read_to_string(&manifest_path)
+        .map_err(|error| format!("读版本 JSON 失败 {}：{error}", manifest_path.display()))?;
+    let manifest =
+        VersionJson::from_json_str(&text).map_err(|error| format!("版本 JSON 非法：{error}"))?;
+    let source = |id: &str| -> Option<VersionJson> {
+        std::fs::read_to_string(env.game.version_json(id))
+            .ok()
+            .and_then(|text| VersionJson::from_json_str(&text).ok())
+    };
+    let resolved =
+        game::resolve(&source, &manifest).map_err(|error| format!("解析继承链失败：{error}"))?;
+
+    let environment = Environment::host();
+    let expanded = resolved
+        .arguments
+        .as_ref()
+        .map(|arguments| arguments.expand(&environment))
+        .unwrap_or_default();
+
+    let mut libraries: Vec<LibraryInput> = Vec::new();
+    for library in resolved.libraries.as_deref().unwrap_or_default() {
+        if !library.applies(&environment) || library.native_classifier(&environment).is_some() {
+            continue;
+        }
+        let Ok(coordinate) = library.coordinate() else {
+            continue;
+        };
+        let path = if library.is_local() {
+            env.game.version_library(&version_id, &coordinate)
+        } else {
+            env.game.library(&coordinate)
+        };
+        libraries.push(LibraryInput::new(path, library.name.clone()));
+    }
+    let natives = unlucky_core::launch::natives::collect(
+        &env.game,
+        &version_id,
+        resolved.libraries.as_deref().unwrap_or_default(),
+        &environment,
+    );
+
+    let game_dir = run_dir(env, target)?;
+    let jar_id = resolved.jar.clone().unwrap_or_else(|| version_id.clone());
+    let assets_root = env.game.assets_dir();
+    let assets_index = resolved
+        .assets
+        .clone()
+        .or_else(|| resolved.asset_index.as_ref().map(|index| index.id.clone()));
+    let snapshot = SnapshotInput {
+        version_id: &version_id,
+        version_name: Some(&target.name),
+        version_type: None,
+        game_version: None,
+        main_class: resolved.main_class.as_deref(),
+        jvm_arguments: &expanded.jvm,
+        game_arguments: &expanded.game,
+        legacy_arguments: resolved.minecraft_arguments.as_deref(),
+        libraries: &libraries,
+        natives: &natives,
+        primary_jar: env.game.version_jar(&jar_id),
+        game_dir,
+        assets_index: assets_index.as_deref(),
+        natives_dir: env.game.natives_dir(&version_id),
+        library_dir: env.game.libraries_dir(),
+        assets_root: assets_root.clone(),
+        game_assets: assets_root,
+    };
+
+    let java = pick_java(env, &version_id);
+    let (auth, identity_line) = super::identity::resolve(env, target.account.as_deref())?;
+    let memory = env
+        .store()
+        .effective("java.default_memory_mb")
+        .and_then(serde_json::Value::as_u64)
+        .and_then(|value| u32::try_from(value).ok());
+    let options = AdapterOptions {
+        java: java.selection,
+        memory: MemoryOptions {
+            min_mb: None,
+            max_mb: memory,
+        },
+        auth,
+        launcher_name: LAUNCHER_NAME.to_string(),
+        launcher_version: env!("CARGO_PKG_VERSION").to_string(),
+        language: "zh-CN".to_string(),
+        ..AdapterOptions::strict()
+    };
+    let output = adapter::build_request(&snapshot, options);
+    let mut warnings: Vec<String> = output.warnings.iter().map(describe_warning).collect();
+    warnings.push(java.summary);
+    warnings.push(identity_line);
+    let mut request = output.request;
+    request.instance.id = target.id.clone();
+    request.instance.name = target.name.clone();
+    Ok((request, warnings))
+}
+
+/// 派生运行目录（D20 覆盖链：实例 `isolation` > 全局 `instances.mode`）。
+fn run_dir(env: &HostEnv, target: &LaunchTarget) -> Result<PathBuf, String> {
+    let global = super::game::global_mode(env);
+    let config = read_instance_config(&env.layout, &target.id)
+        .map_err(|error| format!("读实例设置失败：{error}"))?;
+    let derivation = derive_game_dir(&env.game, &target.version_id, global, config.as_ref(), None)
+        .map_err(|error| format!("隔离目录派生失败：{error}"))?;
+    if let Some(mut config) = config {
+        let at = format_rfc3339_millis(now());
+        if observe_mode(&mut config, &env.game, &at, derivation.isolation).unwrap_or(false) {
+            let _ =
+                unlucky_core::game::install::instance::write_instance_config(&env.layout, &config);
+        }
+    }
+    Ok(derivation.game_dir)
+}
+
+/// 起一次启动（后台线程；进度/日志/收尾全部走 `HostTask`）。
+pub fn start(env: HostEnv, tx: JobSender, target: LaunchTarget) {
+    let id = target.id.clone();
+    let tx_progress = tx.clone();
+    super::job::spawn("launch", move || {
+        let _ = tx_progress.send(HostTask::Runtime {
+            id: id.clone(),
+            runtime: InstanceRuntime::Busy {
+                stage: LaunchStage::Launch,
+                progress: Progress { done: 0, total: 1 },
+            },
+        });
+        let (request, warnings) = match build_request(&env, &target) {
+            Ok(ok) => ok,
+            Err(reason) => {
+                let _ = tx.send(HostTask::LaunchEnd(Box::new(LaunchFinished {
+                    id,
+                    session: String::new(),
+                    outcome: LogOutcome::Crashed,
+                    summary: format!("启动失败：{reason}"),
+                })));
+                return;
+            }
+        };
+        for warning in &warnings {
+            let _ = tx.send(HostTask::Notice(Box::new(crate::dto::NoticeView::new(
+                &format!("launch-warn:{}", target.id),
+                crate::dto::NoticeLevel::Info,
+                "启动提示",
+                warning,
+            ))));
+        }
+        let config = LauncherConfig::new(env.sessions_root())
+            .with_launcher(LAUNCHER_NAME, env!("CARGO_PKG_VERSION"));
+        let session = match Launcher::new(config).spawn(&request) {
+            Ok(session) => session,
+            Err(error) => {
+                let _ = tx.send(HostTask::LaunchEnd(Box::new(LaunchFinished {
+                    id,
+                    session: String::new(),
+                    outcome: LogOutcome::Crashed,
+                    summary: format!("启动失败：{error}"),
+                })));
+                return;
+            }
+        };
+        let session_id = session.session_id().to_string();
+        let pid = session.pid();
+        let _ = tx.send(HostTask::LaunchStarted {
+            id: id.clone(),
+            session_id: session_id.clone(),
+            pid,
+        });
+        let _ = tx.send(HostTask::Runtime {
+            id: id.clone(),
+            runtime: InstanceRuntime::Running { pid },
+        });
+        match session.finish() {
+            Ok(handle) => {
+                let outcome = super::identity::outcome_of(&handle);
+                let _ = tx.send(HostTask::LaunchEnd(Box::new(LaunchFinished {
+                    id,
+                    session: session_id,
+                    outcome,
+                    summary: format!(
+                        "{}（{}，{:.1}s）",
+                        launch_summary(outcome, Some(handle.exit.code)),
+                        handle.exit.exit_type.as_str(),
+                        handle.uptime_ms as f64 / 1000.0
+                    ),
+                })));
+            }
+            Err(error) => {
+                let _ = tx.send(HostTask::LaunchEnd(Box::new(LaunchFinished {
+                    id,
+                    session: session_id,
+                    outcome: LogOutcome::SilentFail,
+                    summary: format!("启动收尾失败：{error}"),
+                })));
+            }
+        }
+    });
+}
+
+/// 停止一次启动（按 pid 回收进程树；`finish()` 会在后台线程里照常收尾）。
+pub fn stop(pid: u32) -> Result<(), String> {
+    tree_kill::kill_tree(pid, std::time::Duration::from_secs(3))
+        .map_err(|error| format!("停止进程 {pid} 失败：{error}"))
+}
+
+/// 适配层告警 → 人读一行。
+fn describe_warning(warning: &AdapterWarning) -> String {
+    match warning {
+        AdapterWarning::MissingLibrary { name, path } => {
+            format!("缺少库文件 {name}（{}）", path.display())
+        }
+        AdapterWarning::MissingGameArguments => "版本 JSON 没有游戏参数".to_string(),
+        AdapterWarning::MissingAssetsIndex => "版本 JSON 没有资源索引".to_string(),
+        AdapterWarning::MissingMainClass => "版本 JSON 没有 mainClass".to_string(),
+        AdapterWarning::MissingNativeJar { name, path } => {
+            format!("缺少 natives 构件 {name}（{}）", path.display())
+        }
+    }
+}
+
+/// 加载器 → 适配层的模组加载器标记（GUI 只用于显示，不改命令行）。
+pub fn loader_label(kind: LoaderKind) -> &'static str {
+    match kind {
+        LoaderKind::Vanilla => "原版",
+        LoaderKind::Fabric => "Fabric",
+        LoaderKind::Quilt => "Quilt",
+        LoaderKind::Forge => "Forge",
+        LoaderKind::NeoForge => "NeoForge",
+        LoaderKind::OptiFine => "OptiFine",
+        LoaderKind::LiteLoader => "LiteLoader",
+    }
+}
+
+/// 隔离档位的展示串（`isolated` / `shared`）。
+pub fn isolation_label(mode: IsolationMode) -> &'static str {
+    mode.as_str()
+}
diff --git a/crates/presenter/src/host/launch_state_tests.rs b/crates/presenter/src/host/launch_state_tests.rs
new file mode 100644
index 0000000..bbb230d
--- /dev/null
+++ b/crates/presenter/src/host/launch_state_tests.rs
@@ -0,0 +1,267 @@
+//! host 启动状态机单测（P2-1/P2-2 的回归网）。
+//!
+//! 覆盖三件事：
+//! 1. `running_pid` 按实例 id 取 pid（并发启动不会把 A 的停止键指到 B）；
+//! 2. 重复启动守卫（`launches` 已落盘 + `pending` 窗口两态都要挡）；
+//! 3. `refresh_instances` 重建快照后仍保留真实运行时（Running / Busy / Failed）。
+
+use unlucky_core::game::install::instance::write_profiles;
+use unlucky_core::game::{InstanceProfile, ProfileId, ProfileList};
+
+use super::*;
+use crate::dto::{LaunchFinished, LogOutcome};
+use crate::toast::ToastKind;
+
+/// 临时数据根守卫：测试结束（含断言 panic）时把目录删掉，不留空壳。
+struct TempRoot(std::path::PathBuf);
+
+impl Drop for TempRoot {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.0);
+    }
+}
+
+/// 建一个只有一条实例档案的数据根，返回 `(host, instance_id, 守卫)`。
+fn host_with_instance(label: &str) -> (CoreHost, String, TempRoot) {
+    let dir = std::env::temp_dir().join(format!(
+        "ull-host-launch-{label}-{}-{}",
+        std::process::id(),
+        line!()
+    ));
+    let _ = std::fs::remove_dir_all(&dir);
+    let env = HostEnv::at_root(&dir);
+    std::fs::create_dir_all(env.layout.config()).expect("config 目录");
+
+    let profile = InstanceProfile {
+        id: ProfileId::generate(),
+        name: "demo".to_string(),
+        version_id: "1.20.1".to_string(),
+        game_dir: None,
+        running_dir: None,
+        java_path: None,
+        created_at: None,
+        last_played_at: None,
+        extra: std::collections::BTreeMap::new(),
+    };
+    let id = profile.id.as_str().to_string();
+    let profiles = ProfileList {
+        profiles: vec![profile],
+        ..ProfileList::default()
+    };
+    write_profiles(&env.layout, &profiles).expect("写 profiles");
+    (CoreHost::headless(env), id, TempRoot(dir))
+}
+
+fn live(instance: &str, session: &str, pid: u32) -> LiveLaunch {
+    LiveLaunch {
+        instance: instance.to_string(),
+        session: session.to_string(),
+        pid,
+    }
+}
+
+#[test]
+fn running_pid_is_per_instance_not_a_single_slot() {
+    let (mut host, id, _root) = host_with_instance("pid");
+    host.launches.push(live("a", "s-a", 111));
+    host.launches.push(live("b", "s-b", 222));
+
+    assert_eq!(host.running_pid("a"), Some(111));
+    assert_eq!(host.running_pid("b"), Some(222));
+    assert_eq!(
+        host.running_pid("c"),
+        None,
+        "没启动过的实例不该拿到别人的 pid"
+    );
+
+    // A 收尾后只影响 A：这正是 review r1 P2-1 的场景（旧实现共用一个槽位）。
+    host.launches.retain(|entry| entry.instance != "a");
+    assert_eq!(host.running_pid("a"), None);
+    assert_eq!(host.running_pid("b"), Some(222));
+
+    // 落盘实例默认是 Idle，兜底分支不误报。
+    assert_eq!(host.running_pid(&id), None);
+}
+
+#[test]
+fn duplicate_launch_is_rejected_before_spawning() {
+    let (mut host, id, _root) = host_with_instance("dup");
+    let _ = host.drain_events();
+    host.launches.push(live(&id, "s", 111));
+
+    host.start_launch(&id);
+
+    let events = host.drain_events();
+    assert!(
+        !events.iter().any(|event| matches!(
+            event,
+            AppEvent::Core(CoreEvent::InstanceRuntimeChanged { .. })
+        )),
+        "已在运行/启动中的实例不该再发 Busy（那会起第二个进程）"
+    );
+    assert!(
+        events
+            .iter()
+            .any(|event| matches!(event, AppEvent::Toast(toast) if toast.kind == ToastKind::Warn)),
+        "至少要给用户一条「已经在启动/运行中」的提示"
+    );
+    assert_eq!(host.launches.len(), 1, "启动表不该被重复启动污染");
+}
+
+#[test]
+fn pending_window_also_blocks_a_second_launch() {
+    let (mut host, id, _root) = host_with_instance("pending");
+    // 走 start_launch 用的同一个入口，模拟「已受理、后台线程还没回报 LaunchStarted」。
+    host.mark_pending(&id);
+    assert!(host.in_flight(&id));
+
+    let _ = host.drain_events();
+    host.start_launch(&id);
+    let events = host.drain_events();
+    assert!(
+        !events.iter().any(|event| matches!(
+            event,
+            AppEvent::Core(CoreEvent::InstanceRuntimeChanged { .. })
+        )),
+        "pending 窗口内重复点启动必须被挡住"
+    );
+    assert_eq!(host.pending.len(), 1);
+}
+
+#[test]
+fn launch_started_registers_and_launch_end_clears() {
+    let (mut host, id, _root) = host_with_instance("cycle");
+    host.mark_pending(&id);
+
+    host.handle(HostTask::LaunchStarted {
+        id: id.clone(),
+        session_id: "20261031T120000-abcd12".to_string(),
+        pid: 4_242,
+    });
+    assert!(!host.pending.contains(&id), "回报后 pending 要清掉");
+    assert_eq!(host.running_pid(&id), Some(4_242));
+
+    host.handle(HostTask::LaunchEnd(Box::new(LaunchFinished {
+        id: id.clone(),
+        session: "20261031T120000-abcd12".to_string(),
+        outcome: LogOutcome::Ok,
+        summary: "正常退出".to_string(),
+    })));
+    assert!(host.launches.is_empty(), "收尾后启动表要清空");
+    assert!(!host.failed.contains_key(&id));
+    assert_eq!(host.running_pid(&id), None);
+}
+
+#[test]
+fn refresh_keeps_running_instances_running() {
+    let (mut host, id, _root) = host_with_instance("refresh-run");
+    host.launches.push(live(&id, "s", 4_242));
+    let _ = host.drain_events();
+
+    host.refresh_instances();
+
+    let instance = instances_from_events(host.drain_events())
+        .into_iter()
+        .find(|instance| instance.id == id)
+        .expect("刷新后应有该实例");
+    assert_eq!(
+        instance.runtime,
+        InstanceRuntime::Running { pid: 4_242 },
+        "刷新（装版本/账户变更/别的实例收尾）不能把在跑实例打回 Idle"
+    );
+}
+
+#[test]
+fn refresh_keeps_pending_as_busy_and_failed_as_failed() {
+    let (mut host, id, _root) = host_with_instance("refresh-busy");
+
+    // Busy：走 start_launch 用的同一个入口（mark_pending），而不是直接改字段。
+    host.mark_pending(&id);
+    let pending = instances_from_events({
+        host.refresh_instances();
+        host.drain_events()
+    })
+    .into_iter()
+    .find(|instance| instance.id == id)
+    .expect("实例存在");
+    assert!(matches!(
+        pending.runtime,
+        InstanceRuntime::Busy {
+            stage: crate::dto::LaunchStage::Launch,
+            ..
+        }
+    ));
+
+    // Failed：走唯一真实写入路径 LaunchEnd（不是手动塞 failed 表）。
+    host.handle(HostTask::LaunchEnd(Box::new(LaunchFinished {
+        id: id.clone(),
+        session: "20261031T120000-dead01".to_string(),
+        outcome: LogOutcome::Crashed,
+        summary: "崩溃（exit 1）".to_string(),
+    })));
+    assert!(!host.pending.contains(&id), "LaunchEnd 必须清 pending");
+    assert!(!host.in_flight(&id), "收尾后该实例要能被重新启动");
+
+    let failed = instances_from_events({
+        host.refresh_instances();
+        host.drain_events()
+    })
+    .into_iter()
+    .find(|instance| instance.id == id)
+    .expect("实例存在");
+    assert_eq!(
+        failed.runtime,
+        InstanceRuntime::Failed {
+            reason: "崩溃（exit 1）".to_string()
+        },
+        "失败原因要经得住一次刷新（否则磁贴的「重试」外观会被 Idle 盖掉）"
+    );
+}
+
+#[test]
+fn launch_end_before_launch_started_still_releases_the_instance() {
+    let (mut host, id, _root) = host_with_instance("fail-early");
+    // build_request / spawn 失败的现场：start_launch 已标 pending、后台线程只发 LaunchEnd。
+    host.mark_pending(&id);
+    assert!(host.in_flight(&id));
+
+    host.handle(HostTask::LaunchEnd(Box::new(LaunchFinished {
+        id: id.clone(),
+        session: String::new(),
+        outcome: LogOutcome::Crashed,
+        summary: "启动失败：找不到 Java".to_string(),
+    })));
+
+    assert!(
+        !host.pending.contains(&id),
+        "LaunchEnd 早于 LaunchStarted 时也必须清 pending（否则该实例本会话再也起不来）"
+    );
+    assert!(!host.in_flight(&id), "失败后要能重试");
+
+    let failed = instances_from_events({
+        host.refresh_instances();
+        host.drain_events()
+    })
+    .into_iter()
+    .find(|instance| instance.id == id)
+    .expect("实例存在");
+    assert_eq!(
+        failed.runtime,
+        InstanceRuntime::Failed {
+            reason: "启动失败：找不到 Java".to_string()
+        },
+        "早失败也要在磁贴上留下「失败/重试」，不能被 Idle 盖掉"
+    );
+}
+
+/// 从事件队列里取最后一次 `InstancesChanged`。
+fn instances_from_events(events: Vec<AppEvent>) -> Vec<crate::dto::InstanceSummary> {
+    events
+        .into_iter()
+        .rev()
+        .find_map(|event| match event {
+            AppEvent::Core(CoreEvent::InstancesChanged(instances)) => Some(instances),
+            _ => None,
+        })
+        .unwrap_or_default()
+}
diff --git a/crates/presenter/src/host/loader_versions.rs b/crates/presenter/src/host/loader_versions.rs
new file mode 100644
index 0000000..e6de126
--- /dev/null
+++ b/crates/presenter/src/host/loader_versions.rs
@@ -0,0 +1,120 @@
+//! 加载器版本清单（下载页「安装选项」的版本下拉，M105）。
+//!
+//! ## 为什么要有这一支
+//!
+//! core 早就有现成能力：[`unlucky_core::addon::loader::LoaderSource::loader_versions`] 按
+//! `(加载器, 原版版本)` 给出**官方那份**可用版本表（Fabric/Quilt 走 fabric meta 的 loader 列表，
+//! Forge/NeoForge 走 maven 的 `maven-metadata.xml` 再按 `matches_mc` 过滤）。
+//! 缺的从来不是能力，是 presenter 到 UI 的那一跳——于是用户在下载页只能装原版，
+//! 「自己有的能力不接出来」是 M105 要收的口子。
+//!
+//! ## 一次查询只回答一个问题
+//!
+//! 事件里带 `(kind, mc_version)` 原样回传，`state.rs` 拿它当缓存键：**切原版版本 = 换键**，
+//! 于是 A 版本的 Fabric 列表不可能挂到 B 版本下面（这条是 M105 复审明确要求的）。
+//! 取不到（网络/该组合官方没有版本）走 `Err(人读原因)`，页面据此**禁掉确认**并给具名错误，
+//! 绝不静默显示成空列表。
+
+use unlucky_core::addon::loader::{LoaderKind as CoreLoaderKind, LoaderSource};
+use unlucky_core::download::blocking::block_on;
+
+use crate::dto::LoaderKind;
+
+use super::env::HostEnv;
+use super::job::{spawn, HostTask, JobSender};
+
+/// 拉一份加载器版本列表（网络在后台线程里，UI 不卡）。
+pub fn spawn_list(env: HostEnv, tx: JobSender, kind: LoaderKind, mc_version: String) {
+    spawn("loader-versions", move || {
+        let result = fetch(&env, kind, &mc_version);
+        let _ = tx.send(HostTask::LoaderVersions {
+            kind,
+            mc_version,
+            result,
+        });
+    });
+}
+
+/// 同步拉取（后台线程里跑）：DTO 的加载器词表 → core 的加载器词表 → 官方清单。
+///
+/// 原版（`Vanilla`）没有「加载器版本」这回事，直接给空列表而不是报错：调用方（页面）
+/// 在选了原版时根本不画这个下拉，这里是防守。
+pub fn fetch(env: &HostEnv, kind: LoaderKind, mc_version: &str) -> Result<Vec<String>, String> {
+    if kind == LoaderKind::Vanilla {
+        return Ok(Vec::new());
+    }
+    let Some(kind) = CoreLoaderKind::parse(kind.as_str()) else {
+        return Err(format!("未知加载器 `{}`", kind.as_str()));
+    };
+    if mc_version.trim().is_empty() {
+        return Err("没有选择原版版本".to_string());
+    }
+    let engine = super::engine::engine(env);
+    let meta_cache = env.layout.meta_cache();
+    block_on(async {
+        LoaderSource::new(&engine, &meta_cache)
+            .loader_versions(kind, mc_version.trim())
+            .await
+    })
+    .map_err(|error| error.to_string())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    use crate::dto::{AppEvent, CoreEvent};
+    use crate::state::AppState;
+
+    /// **缓存键必须是 `(加载器, 原版版本)`**（M105 的硬要求，复审点名的那条）。
+    ///
+    /// 现场：在 1.20.1 上查过 Fabric 的列表，接着点 1.21.9；键里若没有原版版本，1.21.9 会直接
+    /// 显示 1.20.1 那份列表 —— 用户选了个「1.21.9 上不存在」的加载器版本，直到点安装才失败。
+    #[test]
+    fn cache_is_keyed_per_loader_and_minecraft_version() {
+        let mut state = AppState::new();
+        state.apply(AppEvent::Core(CoreEvent::LoaderVersions {
+            kind: LoaderKind::Fabric,
+            mc_version: "1.20.1".to_string(),
+            result: Ok(vec!["0.16.5".to_string()]),
+        }));
+        assert!(state
+            .loader_versions_for(LoaderKind::Fabric, "1.20.1")
+            .is_some());
+        assert!(state
+            .loader_versions_for(LoaderKind::Fabric, "1.21.9")
+            .is_none());
+        assert!(state
+            .loader_versions_for(LoaderKind::Quilt, "1.20.1")
+            .is_none());
+
+        // 失败也是「查过了」：页面据此显示具名原因并禁掉确认，不再无限重试
+        state.apply(AppEvent::Core(CoreEvent::LoaderVersions {
+            kind: LoaderKind::Quilt,
+            mc_version: "1.20.1".to_string(),
+            result: Err("network down".to_string()),
+        }));
+        assert!(state
+            .loader_versions_for(LoaderKind::Quilt, "1.20.1")
+            .is_some());
+    }
+
+    /// 原版没有加载器版本：给空表而不是报错（页面不画这个下拉，防守而已）。
+    #[test]
+    fn vanilla_has_no_loader_versions() {
+        let dir = std::env::temp_dir().join(format!("ull-loader-versions-{}", std::process::id()));
+        let env = HostEnv::at_root(&dir);
+        assert_eq!(fetch(&env, LoaderKind::Vanilla, "1.20.1"), Ok(Vec::new()));
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    /// 空版本号在联网前就被拒（不做无意义的请求，也给出人读原因）。
+    #[test]
+    fn empty_mc_version_is_rejected_before_network() {
+        let dir = std::env::temp_dir().join(format!("ull-loader-empty-{}", std::process::id()));
+        let env = HostEnv::at_root(&dir);
+        let err = fetch(&env, LoaderKind::Fabric, " ").unwrap_err();
+        assert!(err.contains("没有选择原版版本"), "{err}");
+        std::fs::remove_dir_all(&dir).ok();
+    }
+}
diff --git a/crates/presenter/src/host/logs.rs b/crates/presenter/src/host/logs.rs
new file mode 100644
index 0000000..f9fd901
--- /dev/null
+++ b/crates/presenter/src/host/logs.rs
@@ -0,0 +1,342 @@
+//! 日志 / 诊断：会话索引 → 会话列表，事件 JSONL → 日志行，规则引擎 → 诊断卡片。
+//!
+//! 与 CLI `ull logs` / `ull diagnose` 同源（`launch::session_index` + `diagnose` 规则引擎）：
+//! 「同一份 jsonl 的两种读法」只有这一处实现（M39 ports/events.rs 的设计）。
+//! 实时滚动 = host 每拍尾随启动会话的 JSONL（只读新增字节），不额外开第二条事件通道。
+
+use std::io::{Read, Seek, SeekFrom};
+use std::path::{Path, PathBuf};
+
+use serde_json::Value;
+use unlucky_core::diagnose::collectors::{ExitSignal, SignalOrigin};
+use unlucky_core::diagnose::engine::{Diagnoser, DiagnosisInput};
+use unlucky_core::diagnose::loader::RuleLoader;
+use unlucky_core::launch::session_index::{self, SessionIndexEntry};
+
+use crate::dto::{
+    Diagnosis, DiagnosisReport, LogLevel, LogLine, LogOutcome, LogSession, SessionId,
+};
+
+use super::env::HostEnv;
+
+/// 送进规则引擎的默认尾巴行数（与 CLI 同值，避免两条路看到不同证据）。
+pub const DEFAULT_TAIL: usize = 2000;
+
+/// 日志页一次最多渲染的行数（超出的截断，避免大文件把 UI 拖死）。
+pub const MAX_RENDERED_LINES: usize = 2_000;
+
+/// 会话索引目录（`.ULL/data/agent/sessions`）。
+pub fn root(env: &HostEnv) -> PathBuf {
+    env.sessions_root()
+}
+
+/// 会话列表（新→旧）。
+pub fn sessions(env: &HostEnv) -> Vec<LogSession> {
+    let index = session_index::index_path(&root(env));
+    let mut entries = session_index::read_all(&index).unwrap_or_default();
+    entries.sort_by(|a, b| b.started_at.cmp(&a.started_at));
+    entries.iter().map(session_of).collect()
+}
+
+/// 索引条目 → 左栏会话行。
+pub fn session_of(entry: &SessionIndexEntry) -> LogSession {
+    LogSession {
+        id: entry.session_id.clone(),
+        instance: if entry.instance_name.is_empty() {
+            entry.instance_id.clone()
+        } else {
+            entry.instance_name.clone()
+        },
+        when: display_time(&entry.started_at),
+        outcome: outcome_of(entry),
+        duration_secs: entry.duration_ms / 1000,
+    }
+}
+
+/// 结局：静默失败 > 崩溃（非 0 / crash_found） > 正常。
+pub fn outcome_of(entry: &SessionIndexEntry) -> LogOutcome {
+    if entry.silent_failure {
+        LogOutcome::SilentFail
+    } else if entry.crash_found
+        || entry.exit_code.is_some_and(|code| code != 0)
+        || (entry.exit_code.is_none() && !entry.ended_at.is_empty())
+    {
+        LogOutcome::Crashed
+    } else {
+        LogOutcome::Ok
+    }
+}
+
+/// `2026-10-29T19:22:45.123Z` → `10-29 19:22`。
+pub fn display_time(started_at: &str) -> String {
+    let body = started_at.trim_end_matches('Z');
+    let Some((date, time)) = body.split_once('T') else {
+        return started_at.to_string();
+    };
+    let date = date.get(5..).unwrap_or(date);
+    let time = time.get(..5).unwrap_or(time);
+    format!("{date} {time}")
+}
+
+/// 事件流文件路径（`<sessions>/game/<log_path>`）。
+pub fn event_path(env: &HostEnv, entry: &SessionIndexEntry) -> PathBuf {
+    root(env).join("game").join(&entry.log_path)
+}
+
+/// 会话 id 或唯一前缀 → 索引条目。
+fn find(env: &HostEnv, key: &str) -> Option<SessionIndexEntry> {
+    let index = session_index::index_path(&root(env));
+    let entries = session_index::read_all(&index).ok()?;
+    if let Some(exact) = entries.iter().find(|entry| entry.session_id == key) {
+        return Some(exact.clone());
+    }
+    entries
+        .iter()
+        .find(|entry| entry.session_id.starts_with(key))
+        .cloned()
+}
+
+/// 事件 JSON → 一行日志（`stdout`/`stderr` 的 `payload.line`）。
+pub fn line_of(event: &Value) -> Option<LogLine> {
+    let text = event.pointer("/payload/line").and_then(Value::as_str)?;
+    let kind = event
+        .get("kind")
+        .and_then(Value::as_str)
+        .unwrap_or_default();
+    let level = match event
+        .pointer("/payload/level")
+        .and_then(Value::as_str)
+        .unwrap_or_default()
+    {
+        "error" => LogLevel::Error,
+        "warn" | "warning" => LogLevel::Warn,
+        "debug" | "trace" => LogLevel::Debug,
+        _ => {
+            if kind == "stderr" {
+                LogLevel::Warn
+            } else {
+                LogLevel::Info
+            }
+        }
+    };
+    Some(LogLine {
+        text: text.to_string(),
+        level,
+    })
+}
+
+/// 整个事件流 → 日志行（解析失败的行跳过，容忍被 kill 时截断的尾行）。
+pub fn read_lines(path: &Path) -> Vec<LogLine> {
+    let Ok(text) = std::fs::read_to_string(path) else {
+        return Vec::new();
+    };
+    text.lines()
+        .filter(|line| !line.trim().is_empty())
+        .filter_map(|line| serde_json::from_str::<Value>(line).ok())
+        .filter_map(|event| line_of(&event))
+        .collect()
+}
+
+/// 打开一个会话：日志行 + 规则引擎结论。
+pub fn open(env: &HostEnv, key: &str) -> (Vec<LogLine>, Option<DiagnosisReport>) {
+    let Some(entry) = find(env, key) else {
+        return (Vec::new(), None);
+    };
+    let path = event_path(env, &entry);
+    let lines = read_lines(&path);
+    let diagnosis = diagnose_lines(&entry, &lines);
+    (lines, diagnosis)
+}
+
+/// 规则引擎跑一遍（**规则先跑，模型补位**：这里只出规则结论）。
+pub fn diagnose_lines(entry: &SessionIndexEntry, lines: &[LogLine]) -> Option<DiagnosisReport> {
+    let stderr_text: String = lines
+        .iter()
+        .filter(|line| line.level == LogLevel::Error || line.level == LogLevel::Warn)
+        .map(|line| line.text.as_str())
+        .collect::<Vec<_>>()
+        .join("\n");
+    let body: String = lines
+        .iter()
+        .rev()
+        .take(DEFAULT_TAIL)
+        .map(|line| line.text.as_str())
+        .collect::<Vec<_>>()
+        .into_iter()
+        .rev()
+        .collect::<Vec<_>>()
+        .join("\n");
+    if body.is_empty() {
+        return None;
+    }
+    let error_lines = u32::try_from(
+        lines
+            .iter()
+            .filter(|line| line.level == LogLevel::Error)
+            .count(),
+    )
+    .unwrap_or(u32::MAX);
+    let exit = ExitSignal::classify(
+        entry.exit_code,
+        Some(entry.duration_ms),
+        error_lines,
+        &stderr_text,
+    );
+    let mut input = DiagnosisInput::new().with_exit(exit);
+    input.push_text(SignalOrigin::Stderr, body);
+    let loader = RuleLoader::embedded();
+    let report = Diagnoser::new(loader.rule_set().rules().to_vec()).analyze(&input);
+    let finding = report
+        .findings
+        .first()
+        .or_else(|| report.secondary.first())?;
+    Some(DiagnosisReport {
+        session: entry.session_id.clone(),
+        diagnosis: Diagnosis {
+            rule: finding.rule_id.clone(),
+            title: finding.message.clone(),
+            confidence: confidence_percent(finding.confidence),
+            hint: finding.detail.clone().unwrap_or_else(|| {
+                report
+                    .exit
+                    .as_ref()
+                    .map(|exit| exit.exit_type.as_str().to_string())
+                    .unwrap_or_else(|| "未知退出".to_string())
+            }),
+            fix: finding
+                .materialized_actions()
+                .first()
+                .map(|action| action.tool.to_string()),
+        },
+    })
+}
+
+/// 0.0~1.0 → 0~100（四舍五入）。
+pub fn confidence_percent(confidence: f32) -> u8 {
+    let percent = (confidence.clamp(0.0, 1.0) * 100.0).round();
+    u8::try_from(percent as u32).unwrap_or(100)
+}
+
+/// 导入崩溃日志（`hs_err_pid*.log` / `crash-*.txt` / `latest.log`）做规则分析。
+///
+/// 文件名含 `hs_err` 时先走 `hs_err::parse`（结构化字段进规则引擎），否则整份文本当信号喂进去。
+pub fn analyze_crash_file(path: &str) -> Result<(String, DiagnosisReport), String> {
+    let path = Path::new(path);
+    if !path.is_file() {
+        return Err(format!("找不到崩溃日志：{}", path.display()));
+    }
+    let text = std::fs::read_to_string(path).map_err(|error| format!("读崩溃日志失败：{error}"))?;
+    let name = path
+        .file_name()
+        .map(|name| name.to_string_lossy().to_string())
+        .unwrap_or_else(|| "crash.log".to_string());
+    let is_hs_err = name.contains("hs_err");
+    let mut input = DiagnosisInput::new();
+    if is_hs_err {
+        input.push_hs_err(unlucky_core::diagnose::hs_err::parse(&text));
+    }
+    input.push_text(
+        if is_hs_err {
+            SignalOrigin::HsErr
+        } else if name.contains("crash") {
+            SignalOrigin::CrashReport
+        } else {
+            SignalOrigin::LatestLog
+        },
+        text,
+    );
+    let loader = RuleLoader::embedded();
+    let report = Diagnoser::new(loader.rule_set().rules().to_vec()).analyze(&input);
+    let finding = report
+        .findings
+        .first()
+        .or_else(|| report.secondary.first())
+        .ok_or_else(|| "规则引擎没有从这份日志里认出已知问题".to_string())?;
+    Ok((
+        format!("导入的日志：{name}"),
+        DiagnosisReport {
+            session: format!("file:{name}"),
+            diagnosis: Diagnosis {
+                rule: finding.rule_id.clone(),
+                title: finding.message.clone(),
+                confidence: confidence_percent(finding.confidence),
+                hint: finding
+                    .detail
+                    .clone()
+                    .unwrap_or_else(|| "规则引擎命中（详见证据行）".to_string()),
+                fix: finding
+                    .materialized_actions()
+                    .first()
+                    .map(|action| action.tool.to_string()),
+            },
+        },
+    ))
+}
+
+/// 实时尾随器：只读文件新增的字节，解析出完整的 JSON 行。
+#[derive(Debug, Default)]
+pub struct Tail {
+    path: Option<PathBuf>,
+    session: Option<SessionId>,
+    offset: u64,
+}
+
+impl Tail {
+    /// 开始尾随一个会话。
+    pub fn attach(&mut self, path: PathBuf, session: &str) {
+        self.path = Some(path);
+        self.session = Some(session.to_string());
+        self.offset = 0;
+    }
+
+    /// 停止尾随。
+    pub fn detach(&mut self) {
+        self.path = None;
+        self.session = None;
+        self.offset = 0;
+    }
+
+    /// 当前尾随的会话。
+    pub fn session(&self) -> Option<&str> {
+        self.session.as_deref()
+    }
+
+    /// 读新行（返回 `(会话 id, 新行)`；没有新内容返回 `None`）。
+    pub fn poll(&mut self) -> Option<(String, Vec<LogLine>)> {
+        let path = self.path.clone()?;
+        let session = self.session.clone()?;
+        let file = std::fs::File::open(&path).ok()?;
+        let len = file.metadata().ok()?.len();
+        if len <= self.offset {
+            return None;
+        }
+        let mut file = file;
+        file.seek(SeekFrom::Start(self.offset)).ok()?;
+        let mut buffer = String::new();
+        file.read_to_string(&mut buffer).ok()?;
+        // 只吃到最后一个换行：半行留到下一拍（避免把 JSON 截断解析成脏行）
+        let last_newline = buffer.rfind('\n')?;
+        let complete = &buffer[..=last_newline];
+        self.offset += u64::try_from(complete.len()).unwrap_or(u64::MAX);
+        let lines: Vec<LogLine> = complete
+            .lines()
+            .filter(|line| !line.trim().is_empty())
+            .filter_map(|line| serde_json::from_str::<Value>(line).ok())
+            .filter_map(|event| line_of(&event))
+            .collect();
+        Some((session, lines))
+    }
+}
+
+/// 会话是否已收尾（索引里出现 `ended_at` 或文件停止增长超过一拍）。
+pub fn session_finished(env: &HostEnv, session: &str) -> bool {
+    let index = session_index::index_path(&root(env));
+    session_index::read_all(&index)
+        .unwrap_or_default()
+        .iter()
+        .any(|entry| entry.session_id == session && !entry.ended_at.is_empty())
+}
+
+#[cfg(test)]
+#[path = "logs_tests.rs"]
+mod tests;
diff --git a/crates/presenter/src/host/logs_tests.rs b/crates/presenter/src/host/logs_tests.rs
new file mode 100644
index 0000000..ccbb6a3
--- /dev/null
+++ b/crates/presenter/src/host/logs_tests.rs
@@ -0,0 +1,86 @@
+//! host/logs.rs 的单测（拆文件守 400 行上限）。
+
+use super::*;
+
+#[test]
+fn time_display_and_outcomes() {
+    assert_eq!(display_time("2026-10-29T19:22:45.123Z"), "10-29 19:22");
+    assert_eq!(display_time("nope"), "nope");
+    let mut entry = SessionIndexEntry {
+        v: 1,
+        session_id: "s".to_string(),
+        instance_id: String::new(),
+        instance_name: String::new(),
+        game_version: String::new(),
+        started_at: String::new(),
+        ended_at: "2026-10-29T19:22:45Z".to_string(),
+        duration_ms: 1000,
+        exit_code: Some(0),
+        exit_type: Some("normal".to_string()),
+        silent_failure: false,
+        window_detected: true,
+        event_count: 1,
+        log_path: "s.jsonl".to_string(),
+        crash_found: false,
+        diagnosis_top: None,
+    };
+    assert_eq!(outcome_of(&entry), LogOutcome::Ok);
+    entry.exit_code = Some(1);
+    assert_eq!(outcome_of(&entry), LogOutcome::Crashed);
+    entry.silent_failure = true;
+    assert_eq!(outcome_of(&entry), LogOutcome::SilentFail);
+}
+
+#[test]
+fn lines_map_levels_and_skip_non_line_events() {
+    let stdout = serde_json::json!({"kind":"stdout","payload":{"line":"hi","level":"info"}});
+    assert_eq!(line_of(&stdout).unwrap().level, LogLevel::Info);
+    let stderr = serde_json::json!({"kind":"stderr","payload":{"line":"boom","level":"error"}});
+    assert_eq!(line_of(&stderr).unwrap().level, LogLevel::Error);
+    let other = serde_json::json!({"kind":"cmd_built","payload":{"argv":[]}});
+    assert!(line_of(&other).is_none());
+}
+
+#[test]
+fn tail_only_consumes_complete_lines() {
+    let dir = std::env::temp_dir().join(format!("ull-host-tail-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).expect("目录");
+    let path = dir.join("s.jsonl");
+    std::fs::write(
+        &path,
+        "{\"kind\":\"stdout\",\"payload\":{\"line\":\"one\"}}\n",
+    )
+    .expect("写");
+    let mut tail = Tail::default();
+    tail.attach(path.clone(), "s");
+    let (session, lines) = tail.poll().expect("首拍有新行");
+    assert_eq!(session, "s");
+    assert_eq!(lines.len(), 1);
+    assert!(tail.poll().is_none(), "没有新增就不该再产出");
+
+    // 半行不消费
+    let mut text = std::fs::read_to_string(&path).expect("读");
+    text.push_str("{\"kind\":\"stdout\",\"payload\":{\"line\":\"tw");
+    std::fs::write(&path, text).expect("写");
+    assert!(tail.poll().is_none(), "半个 JSON 行不能解析");
+    let mut text = std::fs::read_to_string(&path).expect("读");
+    text.push_str("o\"}}\n");
+    std::fs::write(&path, text).expect("写");
+    let (_, lines) = tail.poll().expect("补全后应产出");
+    assert_eq!(lines[0].text, "two");
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+#[test]
+fn crash_import_reports_missing_file() {
+    let err = analyze_crash_file("D:/definitely/missing/hs_err_pid1.log").unwrap_err();
+    assert!(err.contains("找不到崩溃日志"), "{err}");
+}
+
+#[test]
+fn confidence_percent_is_rounded_and_clamped() {
+    assert_eq!(confidence_percent(0.923), 92);
+    assert_eq!(confidence_percent(-1.0), 0);
+    assert_eq!(confidence_percent(2.0), 100);
+}
diff --git a/crates/presenter/src/host/meter.rs b/crates/presenter/src/host/meter.rs
new file mode 100644
index 0000000..d42c0c5
--- /dev/null
+++ b/crates/presenter/src/host/meter.rs
@@ -0,0 +1,89 @@
+//! 安装进度的记账器（文件计数 / 字节 / 速度 / ETA）。
+//!
+//! `execute` 的文件级回调已经把每个文件的结局给了我们，这里只做聚合；
+//! 速度用相邻两次采样的字节差算（core 的事件只给绝对值）。
+
+use std::sync::Arc;
+use std::time::Instant;
+
+use unlucky_core::game::install::{FileOutcome, FileStatus, ProgressSink};
+
+use crate::dto::{derive_speed, CreateRequest, InstallProgressView, InstallStage};
+
+use super::install::loader_label;
+use super::job::{HostTask, JobSender};
+/// 一次安装的上下文（进度回调共享）。
+pub(super) struct Meter {
+    pub(super) progress: InstallProgressView,
+    /// 任务代次：随每条进度一起回流，让 host 能丢掉「已被取消/被顶掉的旧任务」的事件。
+    ///
+    /// 记在记账器上而不是每条 `HostTask` 现传：所有发送点都已经持有这把锁并读 `progress`，
+    /// 于是代次与它描述的那份进度**永远同源**（不会出现「新代次的进度配旧代次的标签」）。
+    pub(super) epoch: u64,
+    previous: Option<(u64, Instant)>,
+}
+
+impl Meter {
+    pub(super) fn new(request: &CreateRequest, epoch: u64) -> Self {
+        Self {
+            progress: InstallProgressView::start(
+                &request.version,
+                &request.instance_name(),
+                &loader_label(request.loader, &request.loader_version),
+            ),
+            epoch,
+            previous: None,
+        }
+    }
+
+    /// 换阶段（重置速度采样）。
+    pub(super) fn stage(&mut self, stage: InstallStage, message: &str) {
+        self.progress.stage = stage;
+        self.progress.message = message.to_string();
+        self.previous = None;
+    }
+
+    /// 预记账一段待下载的文件（文件数 + 字节）。
+    ///
+    /// 一次安装可能分几段（原版 / 处理器依赖库 / 加载器库）：每段开工前都先记账，
+    /// 整条进度曲线才是单调的——某一段下完不会先到 100%，再因为下一段的文件被计入而回落。
+    pub(super) fn expect(&mut self, files: usize, bytes: u64) {
+        let files = u64::try_from(files).unwrap_or(u64::MAX);
+        self.progress.files_total = self.progress.files_total.saturating_add(files);
+        self.progress.bytes_total = self.progress.bytes_total.saturating_add(bytes);
+    }
+
+    /// 记账一个文件的结局。
+    pub(super) fn note(&mut self, outcome: &FileOutcome) {
+        self.progress.files_done += 1;
+        if outcome.status != FileStatus::Skipped {
+            self.progress.bytes_done = self.progress.bytes_done.saturating_add(outcome.bytes);
+        }
+        let now = Instant::now();
+        if let Some(previous) = self.previous {
+            if let Some((speed, eta)) = derive_speed(
+                previous,
+                (self.progress.bytes_done, now),
+                self.progress.bytes_total,
+            ) {
+                self.progress.speed_bps = speed;
+                self.progress.eta_secs = eta;
+            }
+        }
+        self.previous = Some((self.progress.bytes_done, now));
+    }
+}
+
+/// 进度 sink（`execute` 的文件级回调）。
+pub(super) fn sink_for(tx: JobSender, meter: Arc<std::sync::Mutex<Meter>>) -> ProgressSink {
+    Arc::new(move |outcome: &FileOutcome| {
+        let Ok(mut meter) = meter.lock() else {
+            return;
+        };
+        meter.note(outcome);
+        let _ = tx.send(HostTask::Install {
+            progress: Box::new(meter.progress.clone()),
+            epoch: meter.epoch,
+        });
+    })
+}
diff --git a/crates/presenter/src/host/mod.rs b/crates/presenter/src/host/mod.rs
new file mode 100644
index 0000000..ed55b51
--- /dev/null
+++ b/crates/presenter/src/host/mod.rs
@@ -0,0 +1,366 @@
+//! 真实后端：把 core（game/launch/install/auth/java/diagnose/setting）装配成 GUI 的 host。
+//!
+//! 边界：本模块是**整个 presenter crate 里唯一**允许 `use unlucky_core::…` 的地方（连同
+//! `settings_bridge`）；出口只有 [`crate::dto`] 的快照/事件。线程模型：
+//!
+//! ```text
+//! dispatch(AppCommand) ──► 立即动作（读盘/写设置）或 spawn 后台线程
+//! 后台线程 ──HostTask──► rx ──tick()──► CoreEvent ──► state.apply()
+//! tick() 另外每 ~600ms 尾随一次运行中会话的 JSONL（实时日志滚动）
+//! ```
+//!
+//! AI 对话暂时仍由 [`MockBackend`] 提供脚本回复（agent 的 GUI host 是后续 mission）；
+//! 其余页面全部走真实 core。
+
+mod accounts;
+mod addon;
+mod dispatch;
+mod engine;
+pub mod env;
+mod game;
+mod handle;
+mod identity;
+mod install;
+mod install_journal;
+mod install_processors;
+mod java;
+mod job;
+mod launch;
+mod loader_versions;
+mod logs;
+mod meter;
+mod opener;
+mod settings;
+mod versions;
+
+use std::collections::{BTreeMap, BTreeSet, VecDeque};
+use std::time::Duration;
+
+use crate::dto::{
+    AccountView, AppCommand, AppEvent, Backend, CoreEvent, DiagnosisReport, InstallProgressView,
+    InstanceRuntime, JavaChainStep, NoticeView, SkinImage,
+};
+use crate::mock::MockBackend;
+use crate::toast::{Toast, ToastKind};
+
+use accounts::LoginJob;
+pub use env::HostEnv;
+use job::{HostTask, JobReceiver, JobSender};
+
+/// 每拍最多处理的后台消息数（防止一次 tick 吃掉整帧预算）。
+const MAX_TASKS_PER_TICK: usize = 64;
+
+/// 实时日志尾随间隔（拍数，33ms/拍 → 约 600ms 一次）。
+const TAIL_POLL_TICKS: u64 = 18;
+
+/// 一次在跑的启动（并发启动时按实例 id 区分，停止/尾随都不会串到别的实例）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct LiveLaunch {
+    instance: String,
+    session: String,
+    pid: u32,
+}
+
+/// 真实 host。
+pub struct CoreHost {
+    env: HostEnv,
+    events: VecDeque<AppEvent>,
+    tx: JobSender,
+    rx: JobReceiver,
+    ticks: u64,
+    /// 当前启动账户 id（内存态；跨会话持久化要 core schema 增键，见 handoff）
+    active_account: Option<String>,
+    accounts: Vec<AccountView>,
+    login: Option<LoginJob>,
+    /// 第三方轨（authlib）登录任务句柄（与微软两条流共用取消语义，但**不复用槽位**：
+    /// 两条轨同时点「登录」时各自的结果不能互相踩）
+    authlib: Option<LoginJob>,
+    /// 已抓到的皮肤（账户 id → 原图；`None` = 试过但没取到，不再重试）
+    skins: BTreeMap<String, Option<SkinImage>>,
+    /// 已经发起过皮肤抓取的账户 id（防每次刷新都重新抓一遍）
+    skin_requested: BTreeSet<String>,
+    java_chain: Vec<JavaChainStep>,
+    java_busy: bool,
+    java_message: String,
+    install: Option<InstallProgressView>,
+    notices: Vec<NoticeView>,
+    /// 在跑的启动（实例 → 会话 → pid；支持多个实例同时启动，停止按 id 找正确的 pid）
+    launches: Vec<LiveLaunch>,
+    /// 已受理但后台线程还没回报 `LaunchStarted` 的实例（防「启动中重复点启动」起第二个进程）
+    pending: BTreeSet<String>,
+    /// 上次启动失败的实例与原因（刷新快照时保住磁贴的「失败/重试」外观）
+    failed: BTreeMap<String, String>,
+    /// 实时日志尾随器
+    tail: logs::Tail,
+    /// AI 对话的临时后端（agent GUI host 落地前的占位）
+    chat: MockBackend,
+    /// 当前安装任务的取消标记（`execute_with_cancel` 与段边界检查共同消费）
+    install_cancel: Option<std::sync::Arc<std::sync::atomic::AtomicBool>>,
+    /// 当前安装任务的代次。
+    ///
+    /// 开工（`InstallVersion` / `CreateInstance`）与取消都 +1：还在飞的后台线程把事件带回来时
+    /// 一眼能看出「这是旧任务的」，于是既不会被取消掉的安装重新点亮面板，也不会串到下一轮安装
+    /// （两轮安装同时存在时，旧任务的事件曾经把新任务的进度条顶掉）。
+    install_epoch: u64,
+}
+
+impl CoreHost {
+    /// 按便携数据根装配；解析不出数据根返回 `None`（调用方退回 mock）。
+    pub fn open() -> Option<Self> {
+        HostEnv::resolve().map(Self::new)
+    }
+
+    /// 用给定环境装配（截图/单测通道）。
+    pub fn new(env: HostEnv) -> Self {
+        Self::build(env, true)
+    }
+
+    /// 单测用：不跑 `refresh_all`（不起版本清单网络线程），其余装配一致。
+    #[cfg(test)]
+    pub(crate) fn headless(env: HostEnv) -> Self {
+        Self::build(env, false)
+    }
+
+    fn build(env: HostEnv, refresh: bool) -> Self {
+        let (tx, rx) = job::channel();
+        game::ensure_root(&env);
+        let mut host = Self {
+            env,
+            events: VecDeque::new(),
+            tx,
+            rx,
+            ticks: 0,
+            active_account: None,
+            accounts: Vec::new(),
+            login: None,
+            authlib: None,
+            skins: BTreeMap::new(),
+            skin_requested: BTreeSet::new(),
+            java_chain: Vec::new(),
+            java_busy: false,
+            java_message: String::new(),
+            install: None,
+            notices: Vec::new(),
+            launches: Vec::new(),
+            pending: BTreeSet::new(),
+            failed: BTreeMap::new(),
+            tail: logs::Tail::default(),
+            chat: MockBackend::default(),
+            install_cancel: None,
+            install_epoch: 0,
+        };
+        if refresh {
+            host.refresh_all();
+        }
+        // M109：CF 源可用与否只在装配时打一行（**不含密钥内容**，见 `addon` 模块文档）。
+        addon::log_curseforge_state();
+        host
+    }
+
+    /// 数据根（截图/诊断展示用）。
+    pub fn env(&self) -> &HostEnv {
+        &self.env
+    }
+
+    fn send(&mut self, event: CoreEvent) {
+        self.events.push_back(AppEvent::Core(event));
+    }
+
+    /// 开一轮安装：代次 +1 并把新代次交出去（后台线程随每条进度带回来）。
+    ///
+    /// 返回**新**代次而不是旧代次：调用方拿它去 `spawn_install`，于是「谁是新任务」只有一处答案。
+    fn next_install_epoch(&mut self) -> u64 {
+        self.install_epoch = self.install_epoch.wrapping_add(1);
+        self.install_epoch
+    }
+
+    fn toast(&mut self, kind: ToastKind, text: impl Into<String>) {
+        self.events.push_back(AppEvent::Toast(Toast {
+            id: 0,
+            kind,
+            text: text.into(),
+            remaining_ms: 0,
+        }));
+    }
+
+    /// 全量刷新：实例 / 会话 / 账户 / 设置 / Java，并触发一次版本清单拉取。
+    pub fn refresh_all(&mut self) {
+        self.refresh_instances();
+        self.send(CoreEvent::LogSessionsChanged(logs::sessions(&self.env)));
+        self.refresh_accounts();
+        self.send(CoreEvent::SettingsChanged(settings::groups(&self.env)));
+        self.refresh_java();
+        versions::spawn_list(self.env.clone(), self.tx.clone());
+    }
+
+    /// 重建实例快照，并把**真实运行时**盖回去。
+    ///
+    /// `game::instances` 只读盘（每条都是 `Idle`），所以在跑的实例必须在重建后按
+    /// host 自己的启动表覆写 `Running{pid}`/`Busy`，否则任意一次刷新（装版本成功、
+    /// 加删账户、另一实例收尾）都会把磁贴打回 Idle：停止键与「运行中」条消失，
+    /// 进程还在跑却再也停不下来。
+    fn refresh_instances(&mut self) {
+        let mut instances = game::instances(&self.env);
+        for instance in &mut instances {
+            if let Some(live) = self
+                .launches
+                .iter()
+                .find(|live| live.instance == instance.id)
+            {
+                instance.runtime = InstanceRuntime::Running { pid: live.pid };
+            } else if self.pending.contains(&instance.id) {
+                instance.runtime = InstanceRuntime::Busy {
+                    stage: crate::dto::LaunchStage::Launch,
+                    progress: crate::dto::Progress { done: 0, total: 1 },
+                };
+            } else if let Some(reason) = self.failed.get(&instance.id) {
+                instance.runtime = InstanceRuntime::Failed {
+                    reason: reason.clone(),
+                };
+            }
+        }
+        self.send(CoreEvent::InstancesChanged(instances));
+    }
+
+    fn refresh_java(&mut self) {
+        let page = java::page(
+            &self.env,
+            self.java_chain.clone(),
+            self.java_busy,
+            &self.java_message,
+        );
+        self.send(CoreEvent::JavaChanged(page));
+    }
+
+    fn push_notice(&mut self, notice: NoticeView) {
+        self.notices.retain(|existing| existing.id != notice.id);
+        self.notices.push(notice);
+        self.send(CoreEvent::NoticesChanged(self.notices.clone()));
+    }
+
+    /// 打开一个会话（日志行 + 诊断）。
+    fn open_session(&mut self, id: &str) {
+        let (lines, diagnosis) = logs::open(&self.env, id);
+        self.send(CoreEvent::LogLinesChanged(lines));
+        self.send(CoreEvent::DiagnosisReady(diagnosis.unwrap_or(
+            DiagnosisReport {
+                session: id.to_string(),
+                diagnosis: crate::dto::Diagnosis {
+                    rule: String::new(),
+                    title: "该会话没有命中已知规则".to_string(),
+                    confidence: 0,
+                    hint: "可点「让 AI 详解」把日志交给模型进一步分析".to_string(),
+                    fix: None,
+                },
+            },
+        )));
+    }
+
+    /// 由实例名/版本 id 找启动目标。
+    fn launch_target(&self, id: &str) -> Option<launch::LaunchTarget> {
+        let instance = game::instances(&self.env)
+            .into_iter()
+            .find(|instance| instance.id == id || instance.name == id)?;
+        Some(launch::LaunchTarget {
+            id: instance.id,
+            name: instance.name,
+            version_id: instance.version_id,
+            account: self.active_account.clone(),
+        })
+    }
+
+    /// 某实例是否已在启动/运行（`pending` 与 `launches` 的并集）。
+    ///
+    /// 只查 `launches` 不够：`launch::start` 到后台线程回报 `LaunchStarted` 之间有窗口，
+    /// 这期间重复点启动会起第二个进程、并把旧 pid 在启动表里顶掉（旧进程变孤儿）。
+    fn in_flight(&self, key: &str) -> bool {
+        self.pending.contains(key) || self.launches.iter().any(|live| live.instance == key)
+    }
+
+    /// 标记「已受理、等后台线程回报」（`launch::start` 之后的窗口）。
+    ///
+    /// 单测也走这个入口而不是直接改 `pending`，保证测的是真实状态流转。
+    fn mark_pending(&mut self, id: &str) {
+        self.pending.insert(id.to_string());
+        self.failed.remove(id);
+    }
+
+    fn start_launch(&mut self, id: &str) {
+        if self.in_flight(id) {
+            self.toast(ToastKind::Warn, "这个实例已经在启动/运行中");
+            return;
+        }
+        let Some(target) = self.launch_target(id) else {
+            self.toast(ToastKind::Error, format!("找不到实例 {id}"));
+            return;
+        };
+        let instance_id = target.id.clone();
+        if self.in_flight(&instance_id) {
+            self.toast(ToastKind::Warn, "这个实例已经在启动/运行中");
+            return;
+        }
+        self.mark_pending(&instance_id);
+        if let Some(notice) = game::mode_change_notice(&self.env, &instance_id) {
+            self.push_notice(notice);
+        }
+        self.send(CoreEvent::InstanceRuntimeChanged {
+            id: instance_id.clone(),
+            runtime: InstanceRuntime::Busy {
+                stage: crate::dto::LaunchStage::Launch,
+                progress: crate::dto::Progress { done: 0, total: 1 },
+            },
+        });
+        launch::start(self.env.clone(), self.tx.clone(), target);
+    }
+
+    /// 某实例在跑的 pid（按实例 id 查启动表；不再有「最近一次启动」这种单槽）。
+    ///
+    /// 兜底分支读实例快照的 `Running { pid }`：host 自己发的运行时事件会写回快照，
+    /// 但快照是重建的（`game::instances` 每次 Idle），所以这层只是给将来留的口。
+    fn running_pid(&self, id: &str) -> Option<u32> {
+        if let Some(live) = self.launches.iter().find(|live| live.instance == id) {
+            return Some(live.pid);
+        }
+        game::instances(&self.env)
+            .into_iter()
+            .find(|instance| instance.id == id)
+            .and_then(|instance| match instance.runtime {
+                InstanceRuntime::Running { pid } => Some(pid),
+                _ => None,
+            })
+    }
+}
+
+impl Backend for CoreHost {
+    fn drain_events(&mut self) -> Vec<AppEvent> {
+        self.events.drain(..).collect()
+    }
+
+    fn dispatch(&mut self, command: AppCommand) {
+        self.dispatch_command(command);
+    }
+
+    fn tick(&mut self, elapsed: Duration) {
+        self.chat.tick(elapsed);
+        for event in self.chat.drain_events() {
+            self.events.push_back(event);
+        }
+        for _ in 0..MAX_TASKS_PER_TICK {
+            let Ok(task) = self.rx.try_recv() else {
+                break;
+            };
+            self.handle(task);
+        }
+        self.ticks += 1;
+        if self.ticks.is_multiple_of(TAIL_POLL_TICKS) {
+            self.poll_tail();
+        }
+    }
+}
+
+#[cfg(test)]
+#[path = "cancel_tests.rs"]
+mod cancel_tests;
+#[cfg(test)]
+#[path = "launch_state_tests.rs"]
+mod launch_state_tests;
diff --git a/crates/presenter/src/host/opener.rs b/crates/presenter/src/host/opener.rs
new file mode 100644
index 0000000..65157e3
--- /dev/null
+++ b/crates/presenter/src/host/opener.rs
@@ -0,0 +1,72 @@
+//! 用系统默认浏览器打开授权 URL（授权码流唯一需要宿主做的事）。
+//!
+//! core 只负责拼授权 URL 与等本地回调（`core::auth::microsoft::authcode`）；
+//! 「谁来打开浏览器」是宿主的决定：GUI 走这里，CLI/无浏览器场景仍用设备码流。
+//!
+//! 平台差异收在 [`launcher`] 一处，不往业务代码里散写 `cfg` 补丁（`AGENTS.md` §7）。
+
+use std::process::Command;
+
+/// 拉起系统默认浏览器打开 `url`（只接受 http/https）。
+///
+/// 不等待浏览器退出：用户可能在浏览器里停留几分钟，宿主只关心「有没有拉起来」。
+///
+/// # Errors
+///
+/// URL 不是 http/https，或进程拉不起来时返回用户可读文案。
+pub fn open_url(url: &str) -> Result<(), String> {
+    if !url.starts_with("https://") && !url.starts_with("http://") {
+        return Err(format!("不是可打开的网址：{url}"));
+    }
+    let (program, args) = launcher(url);
+    Command::new(program)
+        .args(args)
+        .spawn()
+        .map(|_child| ())
+        .map_err(|error| format!("拉起浏览器失败（{program}）：{error}"))
+}
+
+#[cfg(target_os = "windows")]
+fn launcher(url: &str) -> (&'static str, Vec<String>) {
+    // `rundll32` 不用 shell，URL 里的 `&` 不会被当成命令分隔符（`cmd /C start` 会）。
+    (
+        "rundll32",
+        vec!["url.dll,FileProtocolHandler".to_string(), url.to_string()],
+    )
+}
+
+#[cfg(target_os = "macos")]
+fn launcher(url: &str) -> (&'static str, Vec<String>) {
+    ("open", vec![url.to_string()])
+}
+
+#[cfg(not(any(target_os = "windows", target_os = "macos")))]
+fn launcher(url: &str) -> (&'static str, Vec<String>) {
+    ("xdg-open", vec![url.to_string()])
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{launcher, open_url};
+
+    #[test]
+    fn rejects_non_http_urls() {
+        assert!(open_url("javascript:alert(1)").is_err());
+        assert!(open_url("").is_err());
+        // 合法 URL 只验命令形态，不在单测里真去拉浏览器。
+        let (program, args) = launcher("http://localhost:1234/auth?code=a&state=b");
+        assert!(!program.is_empty());
+        assert!(args
+            .iter()
+            .any(|arg| arg.contains("http://localhost:1234/auth")));
+    }
+
+    #[cfg(target_os = "windows")]
+    #[test]
+    fn windows_uses_the_file_protocol_handler() {
+        let (program, args) = launcher("https://example.invalid/");
+        assert_eq!(program, "rundll32");
+        assert_eq!(args[0], "url.dll,FileProtocolHandler");
+        assert_eq!(args[1], "https://example.invalid/");
+    }
+}
diff --git a/crates/presenter/src/host/settings.rs b/crates/presenter/src/host/settings.rs
new file mode 100644
index 0000000..5e45361
--- /dev/null
+++ b/crates/presenter/src/host/settings.rs
@@ -0,0 +1,399 @@
+//! 设置页分组：按 `core::setting` schema 的键生成行，写回走 `SettingStore::set`。
+//!
+//! 三件纪律（AGENTS §6）：
+//! 1. 读写同一份 `<数据根>/config/launcher.json`（与 `ull config set` / AI `set_config` 同源）；
+//! 2. 不自己拼 JSON，也不绕 schema（非法键/越界值由 `store.set` 拒绝）；
+//! 3. 这里只认「键名 + 字符串值」，领域语义留在 core。
+//!
+//! 分组 id 与设置页子导航同名：`download` / `java` / `data` / `ai` / `mcp`。
+
+use serde_json::Value;
+use unlucky_core::game::java::JdkVendor;
+use unlucky_core::setting::spec::ValueKind;
+
+use crate::dto::{SettingGroupView, SettingRowView};
+
+use super::env::HostEnv;
+
+/// 全部设置分组（设置页右栏一次拿全，切分组不再请求）。
+pub fn groups(env: &HostEnv) -> Vec<SettingGroupView> {
+    vec![
+        download_group(env),
+        java_group(env),
+        data_group(env),
+        ai_group(env),
+        mcp_group(env),
+    ]
+}
+
+/// 读一个键的字符串值（缺省给空串）。
+fn text(env: &HostEnv, key: &str) -> String {
+    env.store()
+        .doc()
+        .effective_str(key)
+        .unwrap_or_default()
+        .to_string()
+}
+
+/// 读一个键的整数（缺省给 `fallback`）。
+fn int(env: &HostEnv, key: &str, fallback: i64) -> i64 {
+    env.store()
+        .effective(key)
+        .and_then(Value::as_i64)
+        .unwrap_or(fallback)
+}
+
+/// 读一个键的布尔（缺省给 `fallback`）。
+fn flag(env: &HostEnv, key: &str, fallback: bool) -> bool {
+    env.store()
+        .effective(key)
+        .and_then(Value::as_bool)
+        .unwrap_or(fallback)
+}
+
+/// 枚举值在选项表里的序号（找不到给 0）。
+fn selected(options: &[&str], value: &str) -> i32 {
+    options
+        .iter()
+        .position(|option| *option == value)
+        .map(|index| i32::try_from(index).unwrap_or(0))
+        .unwrap_or(0)
+}
+
+/// 下载（D7）：并发/重试/地区/镜像偏好/代理。
+fn download_group(env: &HostEnv) -> SettingGroupView {
+    let concurrency = int(env, "download.concurrency", 8).to_string();
+    let retry = int(env, "download.retry_limit", 3).to_string();
+    let concurrency_options = ["4", "8", "16"];
+    let retry_options = ["0", "1", "3", "5"];
+    let regions = ["auto", "cn", "global"];
+    let mirrors = ["auto", "official", "mirror"];
+    let proxies = ["none", "system", "manual"];
+    let region_value = text(env, "download.region");
+    let mirror_value = text(env, "download.mirror_preference");
+    let proxy_value = text(env, "download.proxy_mode");
+    SettingGroupView::new("download", "下载与镜像（D7）")
+        .with(SettingRowView::choice(
+            "download.concurrency",
+            "并发数",
+            "同时下载的文件数（海量小文件，16 路足够压满带宽）",
+            &concurrency_options,
+            selected(&concurrency_options, &concurrency),
+        ))
+        .with(SettingRowView::choice(
+            "download.retry_limit",
+            "单文件重试次数",
+            "失败后换源重试的上限",
+            &retry_options,
+            selected(&retry_options, &retry),
+        ))
+        .with(SettingRowView::choice(
+            "download.region",
+            "地区判定",
+            "auto = 时区+语言+探测；决定是否优先国内镜像",
+            &regions,
+            selected(
+                &regions,
+                if region_value.is_empty() {
+                    "auto"
+                } else {
+                    &region_value
+                },
+            ),
+        ))
+        .with(SettingRowView::choice(
+            "download.mirror_preference",
+            "镜像偏好",
+            "auto = 按健康度评分；official = 官方源优先",
+            &mirrors,
+            selected(
+                &mirrors,
+                if mirror_value.is_empty() {
+                    "auto"
+                } else {
+                    &mirror_value
+                },
+            ),
+        ))
+        .with(SettingRowView::choice(
+            "download.proxy_mode",
+            "代理模式",
+            "none / system（跟随系统）/ manual（下面填地址）",
+            &proxies,
+            selected(
+                &proxies,
+                if proxy_value.is_empty() {
+                    "none"
+                } else {
+                    &proxy_value
+                },
+            ),
+        ))
+        .with(SettingRowView::text(
+            "download.proxy_url",
+            "HTTP 代理",
+            "manual 模式生效；留空则用系统代理",
+            &text(env, "download.proxy_url"),
+        ))
+        .with(SettingRowView::action(
+            "download.action.detect_region",
+            "重新检测地区",
+            "清掉 24h 地区缓存，下次下载重新判定",
+            "detect_region",
+        ))
+}
+
+/// Java（D13/D23）：自动安装/内存/选路/发行版优先级。
+fn java_group(env: &HostEnv) -> SettingGroupView {
+    let memory = int(env, "java.default_memory_mb", 2048).to_string();
+    let memory_options = ["1024", "2048", "4096", "8192"];
+    let priority: Vec<String> = env
+        .store()
+        .effective("java.vendorPriority")
+        .and_then(Value::as_array)
+        .map(|items| {
+            items
+                .iter()
+                .filter_map(Value::as_str)
+                .map(str::to_string)
+                .collect()
+        })
+        .unwrap_or_default();
+    let priority_text = if priority.is_empty() {
+        "地区默认序（Temurin → …）".to_string()
+    } else {
+        priority.join(" → ")
+    };
+    let roots = super::engine::java_scan_roots(env);
+    SettingGroupView::new("java", "Java（D13）")
+        .with(SettingRowView::toggle(
+            "java.auto_install",
+            "缺 Java 时自动下载",
+            "按回退链装一个托管 JDK（基准 JDK17）",
+            flag(env, "java.auto_install", true),
+        ))
+        .with(SettingRowView::choice(
+            "java.default_memory_mb",
+            "默认最大堆内存",
+            "实例没单独指定时用这个值（MB）",
+            &memory_options,
+            selected(&memory_options, &memory),
+        ))
+        .with(SettingRowView::text(
+            "java.selected_path",
+            "指定 Java 可执行文件",
+            "留空 = 自动挑（托管 > JAVA_HOME > PATH）",
+            &text(env, "java.selected_path"),
+        ))
+        .with(SettingRowView::text(
+            "java.installRoot",
+            "托管 JDK 安装根",
+            "留空 = 按数据目录模式派生（portable 进数据根 / standard 进系统目录）",
+            &text(env, "java.installRoot"),
+        ))
+        .with(SettingRowView::text(
+            "java.extra_args",
+            "附加 JVM 参数",
+            "原样拼到命令行尾部",
+            &text(env, "java.extra_args"),
+        ))
+        .with(SettingRowView::read_only(
+            "发行版优先级（java.vendorPriority）",
+            &priority_text,
+        ))
+        .with(SettingRowView::read_only(
+            "托管根",
+            &roots
+                .iter()
+                .map(|root| root.display().to_string())
+                .collect::<Vec<_>>()
+                .join(" · "),
+        ))
+}
+
+/// 数据目录（D6 三模式）。
+fn data_group(env: &HostEnv) -> SettingGroupView {
+    let modes = ["portable", "standard", "custom"];
+    let mode = env.mode().as_str().to_string();
+    SettingGroupView::new("data", "数据目录（D6 三模式）")
+        .with(SettingRowView::choice(
+            "core.data_mode",
+            "存储模式",
+            "便携（运行目录）/ 标准（系统应用数据目录）/ 自定义",
+            &modes,
+            selected(&modes, &mode),
+        ))
+        .with(SettingRowView::text(
+            "core.data_custom_root",
+            "自定义根目录",
+            "custom 模式生效（绝对路径）",
+            &text(env, "core.data_custom_root"),
+        ))
+        .with(SettingRowView::read_only(
+            "启动器数据目录",
+            &env.data.launcher_home.display().to_string(),
+        ))
+        .with(SettingRowView::read_only(
+            "游戏目录",
+            &env.data.game_home.display().to_string(),
+        ))
+        .with(SettingRowView::read_only(
+            "生效模式",
+            &format!("{}（改数据根需重启启动器）", env.mode()),
+        ))
+}
+
+/// AI（D4）：开关/端点/模型/YOLO。
+fn ai_group(env: &HostEnv) -> SettingGroupView {
+    let providers = ["openai_compatible", "anthropic", "ollama"];
+    let provider = text(env, "ai.provider");
+    SettingGroupView::new("ai", "AI 助手（D4）")
+        .with(SettingRowView::toggle(
+            "ai.enabled",
+            "启用 AI 助手",
+            "关闭后规则引擎诊断仍可用",
+            flag(env, "ai.enabled", true),
+        ))
+        .with(SettingRowView::choice(
+            "ai.provider",
+            "模型端点",
+            "OpenAI 兼容（含本地 llama.cpp）/ Anthropic / Ollama",
+            &providers,
+            selected(
+                &providers,
+                if provider.is_empty() {
+                    "openai_compatible"
+                } else {
+                    &provider
+                },
+            ),
+        ))
+        .with(SettingRowView::text(
+            "ai.base_url",
+            "端点 base_url",
+            "如 http://127.0.0.1:8080/v1",
+            &text(env, "ai.base_url"),
+        ))
+        .with(SettingRowView::text(
+            "ai.model",
+            "模型名",
+            "如 deepseek-chat",
+            &text(env, "ai.model"),
+        ))
+        .with(SettingRowView::toggle(
+            "ai.yolo",
+            "YOLO 模式",
+            "跳过确认弹窗（审计照记；账户/凭据操作永不 YOLO）",
+            flag(env, "ai.yolo", false),
+        ))
+}
+
+/// M39 的对外 MCP server（默认关、默认只读）。
+fn mcp_group(env: &HostEnv) -> SettingGroupView {
+    let port = int(env, "agent.mcp.port", 47_823);
+    SettingGroupView::new("mcp", "MCP server（M39）")
+        .with(SettingRowView::toggle(
+            "agent.mcp.enabled",
+            "对外提供 MCP server",
+            "127.0.0.1 上的 Streamable HTTP（stdio 需显式启动）",
+            flag(env, "agent.mcp.enabled", false),
+        ))
+        .with(SettingRowView::text(
+            "agent.mcp.port",
+            "端口",
+            "1024~65535，只绑 127.0.0.1",
+            &port.to_string(),
+        ))
+        .with(SettingRowView::toggle(
+            "agent.mcp.allow_write",
+            "允许外部客户端写配置",
+            "默认只读；写仍受 schema 白名单与分级确认约束",
+            flag(env, "agent.mcp.allow_write", false),
+        ))
+        .with(SettingRowView::read_only(
+            "客户端地址",
+            &format!("http://127.0.0.1:{port}/mcp（令牌见 agent.mcp.token，AI 不可写）"),
+        ))
+}
+
+/// 写一条设置。`value` 是字符串形态，按 schema 键的类型转换后交 `store.set`。
+///
+/// # Errors
+///
+/// 未知键、值类型不符、越界、落盘失败时返回用户可读文案。
+pub fn set(env: &HostEnv, key: &str, value: &str) -> Result<(), String> {
+    if key == "download.action.detect_region" {
+        return detect_region(env);
+    }
+    let parsed = parse_value(key, value)?;
+    let mut store = env.store();
+    store
+        .set(key, parsed)
+        .map_err(|error| format!("设置 {key} 失败：{error}"))?;
+    store
+        .save()
+        .map_err(|error| format!("保存设置失败：{error}"))?;
+    Ok(())
+}
+
+/// 键 → 正确类型的 JSON 值（schema 会再校验范围/枚举）。
+///
+/// **按 schema 的 `ValueKind` 取类型，不硬编码键名**（复审 P1-1）：原先是「硬编码 Int/Bool
+/// 键名，其余当字符串」，于是 `appearance.window_opacity`（Float）被当 String 送进 `store.set`，
+/// schema 的 `as_f64()` 返回 `None` ⇒ `InvalidValue` ⇒ **`save()` 不执行**（重启回旧值 + 弹 toast）。
+/// 现在新增任何 Float/Int/Bool 键都自动正确；集合级守门是
+/// `every_float_key_in_the_schema_can_be_written_back`。
+fn parse_value(key: &str, value: &str) -> Result<Value, String> {
+    let schema = unlucky_core::setting::keys::launcher_schema();
+    let Some(spec) = schema.spec(key) else {
+        // 未知键：原样交下去，由 `store.set` 用 schema 报「未知键」（这里不猜类型）。
+        return Ok(Value::String(value.to_string()));
+    };
+
+    let trimmed = value.trim();
+    match &spec.kind {
+        ValueKind::Bool => match trimmed.to_ascii_lowercase().as_str() {
+            "1" | "true" | "on" | "yes" => Ok(Value::Bool(true)),
+            "0" | "false" | "off" | "no" => Ok(Value::Bool(false)),
+            _ => Err(format!("{key} 需要布尔值：{value}")),
+        },
+        ValueKind::Int { .. } => trimmed
+            .parse::<i64>()
+            .map(Value::from)
+            .map_err(|_| format!("{key} 需要整数：{value}")),
+        ValueKind::Float { .. } => match trimmed.parse::<f64>() {
+            Ok(number) if number.is_finite() => Ok(Value::from(number)),
+            _ => Err(format!("{key} 需要有限数字：{value}")),
+        },
+        // 文本 / 枚举 / 路径 / 列表 / 任意 JSON：字符串原样交下去（越界与词表由 schema 判）。
+        _ => Ok(Value::String(value.to_string())),
+    }
+}
+
+/// 清掉 24h 地区缓存（下次建引擎重新判定）。
+fn detect_region(env: &HostEnv) -> Result<(), String> {
+    let path = env.layout.cache().join("region.json");
+    if path.is_file() {
+        std::fs::remove_file(&path).map_err(|error| format!("清地区缓存失败：{error}"))?;
+    }
+    Ok(())
+}
+
+/// 设置页「重置发行版优先级」用（清空 enum_list）。
+///
+/// # Errors
+///
+/// 落盘失败时返回用户可读文案。
+pub fn clear_vendor_priority(env: &HostEnv) -> Result<(), String> {
+    let mut store = env.store();
+    store
+        .set("java.vendorPriority", Value::Array(Vec::new()))
+        .and_then(|()| store.save())
+        .map_err(|error| format!("清空发行版优先级失败：{error}"))?;
+    let _ = JdkVendor::ALL;
+    Ok(())
+}
+
+#[cfg(test)]
+#[path = "settings_tests.rs"]
+mod tests;
diff --git a/crates/presenter/src/host/settings_tests.rs b/crates/presenter/src/host/settings_tests.rs
new file mode 100644
index 0000000..0cabb39
--- /dev/null
+++ b/crates/presenter/src/host/settings_tests.rs
@@ -0,0 +1,163 @@
+//! host/settings.rs 的单测（拆文件守 400 行上限）。
+
+use super::*;
+
+fn env_in(dir: &std::path::Path) -> HostEnv {
+    std::fs::create_dir_all(dir.join(".ULL/config")).expect("config");
+    HostEnv::at_root(dir)
+}
+
+#[test]
+fn groups_cover_the_six_required_areas() {
+    let dir = std::env::temp_dir().join(format!("ull-host-settings-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    let env = env_in(&dir);
+    let groups = groups(&env);
+    let ids: Vec<&str> = groups.iter().map(|group| group.id.as_str()).collect();
+    assert_eq!(ids, vec!["download", "java", "data", "ai", "mcp"]);
+    let keys: Vec<&str> = groups
+        .iter()
+        .flat_map(|group| group.rows.iter())
+        .map(|row| row.key.as_str())
+        .collect();
+    for key in [
+        "download.region",
+        "download.mirror_preference",
+        "java.default_memory_mb",
+        "core.data_mode",
+        "agent.mcp.enabled",
+        "agent.mcp.port",
+        "ai.base_url",
+    ] {
+        assert!(keys.contains(&key), "缺少 {key}");
+    }
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+#[test]
+fn set_parses_types_and_persists() {
+    let dir = std::env::temp_dir().join(format!("ull-host-settings-w-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    let env = env_in(&dir);
+
+    set(&env, "download.concurrency", "16").expect("写并发");
+    set(&env, "agent.mcp.enabled", "true").expect("写开关");
+    set(&env, "agent.mcp.port", "48000").expect("写端口");
+    set(&env, "download.region", "cn").expect("写地区");
+
+    let groups = groups(&env);
+    let row = |key: &str| {
+        groups
+            .iter()
+            .flat_map(|g| g.rows.iter())
+            .find(|r| r.key == key)
+            .cloned()
+    };
+    assert_eq!(row("download.concurrency").unwrap().selected, 2);
+    assert!(row("agent.mcp.enabled").unwrap().flag);
+    assert_eq!(row("agent.mcp.port").unwrap().value_text, "48000");
+    assert_eq!(row("download.region").unwrap().selected, 1);
+
+    assert!(set(&env, "download.concurrency", "abc").is_err());
+    assert!(set(&env, "agent.mcp.enabled", "maybe").is_err());
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+#[test]
+fn detect_region_action_removes_cache() {
+    let dir = std::env::temp_dir().join(format!("ull-host-settings-r-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    let env = env_in(&dir);
+    let path = env.layout.cache().join("region.json");
+    std::fs::create_dir_all(env.layout.cache()).expect("cache");
+    std::fs::write(&path, "{}").expect("写缓存");
+    set(&env, "download.action.detect_region", "").expect("检测");
+    assert!(!path.exists());
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+/// **P1-1 的回归**：整窗透明度是 `ValueKind::Float` 的键，`SetSetting` 的载荷是字符串。
+///
+/// 历史（复审 r1 P1-1）：`parse_value` 只认硬编码的 Int/Bool 键名，Float 键被当成字符串交给
+/// `store.set`，schema 的 `as_f64()` 对 String 返回 None ⇒ `InvalidValue` ⇒ **`save()` 不执行**，
+/// 于是 α 只在内存生效、重启回旧值，且每次拖动弹一条 Error toast。
+///
+/// 抓得住：`set` → 落盘 → **新开一个 store（= 模拟重启）** 读回同一值。
+/// 抓不住：UI 侧是否真的把滑块接到 `SetSetting`（由 `app` 侧的 `on_appearance` 测试管）。
+#[test]
+fn float_key_round_trips_through_set_setting() {
+    let dir = std::env::temp_dir().join(format!("ull-host-settings-float-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    let env = env_in(&dir);
+
+    set(&env, "appearance.window_opacity", "0.8").expect("写整窗透明度");
+    set(&env, "appearance.panel_alpha", "0.55").expect("写面板透明度");
+
+    // 新开一个 store：从磁盘重新加载（等价「重启进程」）。
+    let reopened = env.store();
+    assert_eq!(
+        reopened.doc().effective_f64("appearance.window_opacity"),
+        Some(0.8)
+    );
+    assert_eq!(
+        reopened.doc().effective_f64("appearance.panel_alpha"),
+        Some(0.55)
+    );
+
+    // 越界仍然被 schema 拒绝（钳位在 core 的读侧，写侧是拒绝）。
+    assert!(set(&env, "appearance.window_opacity", "0.0").is_err());
+    // 非数字报人话，而不是「期望数字，实际是 \"abc\"」这种 schema 原话。
+    assert!(set(&env, "appearance.window_opacity", "abc").is_err());
+    assert!(set(&env, "appearance.window_opacity", "NaN").is_err());
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+/// **集合级守门（复审 P1-1 要求的那条）**：schema 里**每一个** `ValueKind::Float` 的键都必须
+/// 能被 `SetSetting` 写回，而不只是 `window_opacity`。
+///
+/// 为什么这条比单键测试重要：下次谁再加一个 Float 键（比如玻璃强度、模糊半径），
+/// 只要 `parse_value` 又退化成「硬编码表」，这里立刻红——单键测试抓不住新键。
+///
+/// 抓得住：类型解析与 `save()` 是否真的执行（读回是**新开 store**，走磁盘）。
+/// 抓不住：UI 控件是否接上了这些键（那是各页面的接线测试）。
+#[test]
+fn every_float_key_in_the_schema_can_be_written_back() {
+    let dir =
+        std::env::temp_dir().join(format!("ull-host-settings-allfloat-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    let env = env_in(&dir);
+
+    let schema = unlucky_core::setting::keys::launcher_schema();
+    let mut checked = 0_usize;
+    for spec in schema.specs() {
+        let unlucky_core::setting::spec::ValueKind::Float { min, max } = spec.kind else {
+            continue;
+        };
+        // 取一个落在 [min, max] 内的值（0.5 是多数区间的好选择，落不进时取中点）。
+        let target = if (min..=max).contains(&0.5) {
+            0.5
+        } else {
+            (min + max) / 2.0
+        };
+        set(&env, spec.key, &format!("{target}"))
+            .unwrap_or_else(|error| panic!("Float 键 {} 写不回：{error}", spec.key));
+        let reread = env
+            .store()
+            .doc()
+            .effective_f64(spec.key)
+            .unwrap_or_else(|| panic!("Float 键 {} 写完后读不到", spec.key));
+        assert!(
+            (reread - target).abs() < 1e-9,
+            "Float 键 {} 写 {target} 读回 {reread}",
+            spec.key
+        );
+        checked += 1;
+    }
+
+    assert!(
+        checked >= 3,
+        "schema 里 Float 键只剩 {checked} 个：本断言要求 ≥3（window_opacity / panel_alpha / bg_dim / ui.scale）。\
+         若是有意删减，请同步更新这条断言"
+    );
+    std::fs::remove_dir_all(&dir).ok();
+}
diff --git a/crates/presenter/src/host/versions.rs b/crates/presenter/src/host/versions.rs
new file mode 100644
index 0000000..32ddde4
--- /dev/null
+++ b/crates/presenter/src/host/versions.rs
@@ -0,0 +1,173 @@
+//! 版本清单（下载页）：远端 manifest（12h 缓存）+ 内嵌 unlisted 清单 → 分类好的行。
+//!
+//! 分类口径抄 analyse/03 §2.4：官方 `type` 决定 release/snapshot/远古；远古再按 id
+//! 前缀拆 classic（`rd-*`）/ old_alpha（`a*`）/ old_beta（`b*`），其余归 unlisted 汇总。
+//! 拉取失败但有旧缓存时用旧缓存（离线可用），全无才报错。
+
+use std::collections::BTreeSet;
+
+use unlucky_core::download::blocking::block_on;
+use unlucky_core::download::cache::now_ms;
+use unlucky_core::game::install::RemoteSource;
+use unlucky_core::game::unlisted;
+use unlucky_core::game::version::{ReleaseType, RemoteVersion};
+
+use crate::dto::{AncientKind, VersionKind, VersionSummary};
+
+use super::env::HostEnv;
+use super::job::{spawn, HostTask, JobSender};
+
+/// 版本 id / 官方类型 → 下载页的四种归类。
+pub fn kind_of(id: &str, release_type: ReleaseType) -> VersionKind {
+    match release_type {
+        ReleaseType::Release => VersionKind::Release,
+        ReleaseType::Snapshot | ReleaseType::Pending | ReleaseType::Unobfuscated => {
+            VersionKind::Snapshot
+        }
+        ReleaseType::OldAlpha | ReleaseType::OldBeta | ReleaseType::Modified => {
+            VersionKind::Ancient(ancient_kind(id))
+        }
+        ReleaseType::Unknown => {
+            if id.starts_with("rd-") || id.starts_with("a") || id.starts_with("b") {
+                VersionKind::Ancient(ancient_kind(id))
+            } else {
+                VersionKind::Release
+            }
+        }
+    }
+}
+
+/// 远古版子类（`rd-*` → classic；`a1.*` → old_alpha；`b1.*` → old_beta；其余 unlisted）。
+pub fn ancient_kind(id: &str) -> AncientKind {
+    if id.starts_with("rd-") || id.starts_with("inf-") {
+        AncientKind::Classic
+    } else if id.starts_with("a1.") || id.starts_with("a0.") || id.starts_with('a') {
+        AncientKind::OldAlpha
+    } else if id.starts_with("b1.") || id.starts_with('b') {
+        AncientKind::OldBeta
+    } else {
+        AncientKind::Unlisted
+    }
+}
+
+/// 发布日期取 `releaseTime` 的日期部分（缺失时退回 `time`，再退回空串）。
+fn released_of(version: &RemoteVersion) -> String {
+    version
+        .release_time
+        .as_deref()
+        .or(version.time.as_deref())
+        .map(|text| text.get(..10).unwrap_or(text).to_string())
+        .unwrap_or_default()
+}
+
+/// 拉清单并翻译成 DTO（安装状态按盘上版本判定）。
+fn fetch(env: &HostEnv) -> Result<Vec<VersionSummary>, String> {
+    let engine = super::engine::engine(env);
+    let meta_cache = env.layout.meta_cache();
+    let now = now_ms();
+    let (mut list, _freshness) = block_on(async {
+        RemoteSource::new(&engine, &env.game, &meta_cache, now)
+            .manifest(false)
+            .await
+    })
+    .map_err(|error| format!("拉取版本清单失败：{error}"))?;
+    // 内嵌 unlisted 清单先合（同 id 先插入者胜），保证远古版显式可达（09 §G2）。
+    unlisted::merge_into(&mut list);
+    list.sort_newest_first();
+
+    let installed: BTreeSet<String> = env
+        .game
+        .installed_versions()
+        .unwrap_or_default()
+        .into_iter()
+        .collect();
+    Ok(list
+        .versions
+        .iter()
+        .map(|version| VersionSummary {
+            id: version.id.clone(),
+            kind: kind_of(&version.id, version.version_type),
+            released: released_of(version),
+            installed: installed.contains(&version.id),
+        })
+        .collect())
+}
+
+/// 后台拉清单（网络在后台线程里，UI 不卡）。
+pub fn spawn_list(env: HostEnv, tx: JobSender) {
+    spawn("versions", move || {
+        let result = fetch(&env);
+        let _ = tx.send(HostTask::Versions(result));
+    });
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn kinds_follow_official_types() {
+        assert_eq!(
+            kind_of("1.21.9", ReleaseType::Release),
+            VersionKind::Release
+        );
+        assert_eq!(
+            kind_of("1.21.9-pre3", ReleaseType::Snapshot),
+            VersionKind::Snapshot
+        );
+        assert_eq!(
+            kind_of("rd-132211", ReleaseType::OldAlpha),
+            VersionKind::Ancient(AncientKind::Classic)
+        );
+        assert_eq!(
+            kind_of("a1.1.1", ReleaseType::OldAlpha),
+            VersionKind::Ancient(AncientKind::OldAlpha)
+        );
+        assert_eq!(
+            kind_of("b1.7.3", ReleaseType::OldBeta),
+            VersionKind::Ancient(AncientKind::OldBeta)
+        );
+        assert_eq!(
+            kind_of("x-modified", ReleaseType::Modified),
+            VersionKind::Ancient(AncientKind::Unlisted)
+        );
+    }
+
+    #[test]
+    fn released_uses_date_part() {
+        let version = RemoteVersion {
+            id: "1.20.4".to_string(),
+            version_type: ReleaseType::Release,
+            url: String::new(),
+            time: None,
+            release_time: Some("2023-12-07T12:00:00+00:00".to_string()),
+            sha1: None,
+            size: None,
+        };
+        assert_eq!(released_of(&version), "2023-12-07");
+        let empty = RemoteVersion {
+            id: "x".to_string(),
+            version_type: ReleaseType::Unknown,
+            url: String::new(),
+            time: None,
+            release_time: None,
+            sha1: None,
+            size: None,
+        };
+        assert_eq!(released_of(&empty), "");
+    }
+
+    #[test]
+    fn unlisted_merge_keeps_ancient_versions_reachable() {
+        // core 的内嵌清单里一定有远古版（`rd-*` / `a1.*` / `b1.*`）
+        let mut list = unlucky_core::game::version::VersionList::default();
+        let added = unlisted::merge_into(&mut list);
+        assert!(added > 0, "内嵌 unlisted 清单不该为空");
+        assert!(
+            list.versions.iter().any(|v| v.id.starts_with("a1.")
+                || v.id.starts_with("b1.")
+                || v.id.starts_with("rd-")),
+            "远古版必须显式可达"
+        );
+    }
+}
diff --git a/crates/presenter/src/lib.rs b/crates/presenter/src/lib.rs
new file mode 100644
index 0000000..8c8d669
--- /dev/null
+++ b/crates/presenter/src/lib.rs
@@ -0,0 +1,120 @@
+//! Unlucky-Launcher 的 **UI 框架无关宿主层**（presenter）。
+//!
+//! # 1. 这层为什么存在
+//!
+//! D26 的技术路线是「用 iced 重写 UI」。重写只应该换掉**渲染**，不该重写业务装配——
+//! 本 crate 就是被两个 UI 版共用的那一半：Slint 版（`crates/app`）与 iced 版
+//! （`crates/app-iced`）都从这里取 DTO、状态 reducer 与 host。Slint 退役后只剩 iced
+//! 依赖它，本 crate 不受影响。
+//!
+//! 判据（M85 已核）：这套代码原本住在 `crates/app/src`，但 `host/`（25 个文件）、
+//! `state.rs`、`settings_bridge.rs`、`dto/` 里**没有一处** UI 框架符号；它们依赖的只有
+//! 标准库、serde 与 `unlucky-core`。把它们留在 UI crate 里等于让 iced 重写跟着重写一遍
+//! 约 5400 行，白担行为漂移的风险。
+//!
+//! # 2. 对外表面（UI 侧的唯一入口）
+//!
+//! ```text
+//! host::CoreHost ──impl Backend──► dto::AppEvent ──► state::AppState::apply ──► dto 快照
+//!        ▲                                              │
+//!        └──────────── dto::AppCommand ◄────────────────┘
+//! ```
+//!
+//! | 模块 | 入口 | UI 侧怎么用 |
+//! | ---- | ---- | ----------- |
+//! | [`dto`] | [`dto::Backend`] / [`dto::AppCommand`] / [`dto::AppEvent`] / 各 `*View` 快照 | 派发指令、消费事件、把快照字段映射成视图模型 |
+//! | [`host`] | [`host::CoreHost`]（实现 [`dto::Backend`]）、[`host::HostEnv`] | 进程启动时构造一次，之后只当 `Box<dyn Backend>` 用 |
+//! | [`state`] | [`state::AppState`]（`apply` / `navigate` / 各页面字段） | **唯一**状态入口：事件进来先 `apply`，再从字段取值画 |
+//! | [`agent`] | `Presenter`（`agent_rail` / `agent_submit` / `agent_mark_read` / `agent_confirm`）、`AgentRail` | AI 助手的唯一状态入口：读 rail 画、把点击翻成这四个方法 |
+//! | [`prefs`] | `UiPrefs` / `ThemeMode` / `TileSize` / `AppearancePrefs` / `keys` | 读字段做展示；不自己写盘 |
+//! | [`settings_bridge`] | `SettingsBridge`（`open` / `load` / `persist` / `reload_if_changed`） | 启动读一次、变更时写回、每拍问一次「变了吗」 |
+//! | [`theme`] | `CONFIG_POLL_TICKS` / `BACKGROUND_KEY` 一类纯判据、`tile_viewport` / `system_theme_value` | 「这一拍该不该重读/重建」由它回答，UI 只执行 |
+//! | [`router`] | `Route` / `Router` / `AiPanelMode` | 导航状态 |
+//! | [`dialogs`] | `DialogQueue` / `DialogRequest` | 模态队列 |
+//! | [`toast`] | `ToastCenter` / `Toast` | 非阻塞提示 |
+//! | [`wizard`] | `WizardState` | 新建实例向导的纯状态机 |
+//! | [`mock`] / [`mock_data`] | `MockBackend` / 样例数据 | 无数据根时的演示后端、UI 回归 |
+//! | [`backend`] | `AppOptions` / `build_backend` / `config_path` | 启动时选真实 host 还是 mock |
+//!
+//! # 3. UI 侧允许做什么、禁止做什么
+//!
+//! 允许（**只做展示与转发**）：
+//!
+//! - 把本 crate 的值翻译成框架类型（视图模型、颜色、图标、字符串）并灌进属性/`Element`；
+//! - 回调里把用户动作翻成 [`dto::AppCommand`] 交给 [`dto::Backend::dispatch`]，再 `drain_events()` 喂
+//!   [`state::AppState::apply`]——**不要**在本地做乐观回显（会话气泡/磁贴状态都以事件为准）；
+//! - 框架能力：窗口、定时器/订阅、图片解码与模糊层、截图落盘、字体加载。
+//!
+//! 禁止：
+//!
+//! - 在本 crate 里出现 Slint / iced / winit 类型（守门命令见 `crates/app/Cargo.toml` 的注释：
+//!   自指问题让那条命令不能写在本 crate 里，否则它自己就被抓出来了）；
+//! - UI 侧绕过 [`state::AppState::apply`] 直接改状态字段（会与事件流打架，磁贴/日志会漂）；
+//! - UI 侧直接 `use unlucky_core::…` 组装业务（读盘、起进程、拼路径、写设置一律走 host/bridge）；
+//! - UI 侧自己造 `<data root>` 路径：路径只从 [`host::HostEnv`] / [`settings_bridge`] 拿。
+//!
+//! # 4. iced 接线的推荐用法（骨架，伪代码）
+//!
+//! ```ignore
+//! // 1) 启动：选后端（数据根解析不出来自动退回 mock）
+//! let backend: Box<dyn Backend> = build_backend(&AppOptions::default());
+//! let bridge = SettingsBridge::open();          // 读盘一次，主题/外观看这里
+//! let state = AppState::new();
+//!
+//! // 2) 订阅：iced 的 30fps 订阅里推进一拍
+//! fn subscription() -> Subscription<Message> { iced::time::every(TICK).map(|_| Message::Tick) }
+//! fn update(&mut self, Message::Tick) {
+//!     backend.tick(TICK);                        // 后台线程的消息在这里汇聚
+//!     for event in backend.drain_events() { self.state.apply(event); }   // 唯一的写状态入口
+//!     if config_poll_due(self.ticks) {           // presenter 的纯判据
+//!         if let Some((appearance, theme)) = self.bridge.reload_if_changed() { … }
+//!     }
+//!     self.view = ViewModel::from(&self.state);  // 展示转换在 iced 侧做
+//! }
+//!
+//! // 3) 回调：用户动作 → AppCommand → 事件回流（不本地回显）
+//! fn update(&mut self, Message::Launch(id)) { self.dispatch(AppCommand::Launch(id)); }
+//! ```
+//!
+//! 要点：`state` / `bridge` / `backend` 三件由 UI 侧持有并驱动，`presenter` 不持有定时器也不
+//! 知道帧率；事件顺序以 `drain_events()` 的顺序为准（host 侧保证配对：`Install` 之后必有
+//! `InstallDone`、`LaunchStarted` 之后必有 `LaunchEnd`）。
+//!
+//! # 5. 留在 `crates/app`（Slint 侧）的东西，以及为什么
+//!
+//! | 留在 app | 为什么不能进 presenter |
+//! | -------- | ---------------------- |
+//! | `conv/` | 把 DTO 转成 **Slint 结构体**（UI 侧生成的视图模型类型），是 Slint 专属转换层 |
+//! | `ui_bind.rs` / `page_sync.rs` / `callbacks*.rs` | 持有 `MainWindow`、`ModelRc`、回调闭包，全是框架绑定 |
+//! | `theme_runtime.rs` / `appearance_bind.rs` | `impl Inner` 的方法，读写窗口属性与图片属性；其中的**纯判据**已抽到 [`theme`] |
+//! | `bg_image.rs` / `png.rs` | 解码/模糊/编码产出框架图片类型与像素缓冲，属渲染侧 |
+//! | `screenshot.rs` | Slint 快照通道（`Window::take_snapshot`） |
+//! | `main.rs` | `include_modules!()` 与窗口拉起 |
+//!
+//! # 6. 零 UI 依赖的证据命令
+//!
+//! 两条命令（`grep` 与 `cargo tree`）的原文与实测输出见 `crates/app/Cargo.toml` 的注释与 M85
+//! 的完成报告：本 crate 的依赖树里只有 serde / serde_json / unlucky-core（及其自身依赖）。
+
+// 关于 dead_code：host 里有一批「已定义、由单测覆盖、等 iced 页面接线才调用」的辅助函数
+// （`host::logs::session_finished`、`host::settings::clear_vendor_priority`、`loader_label`
+// 等）。它们原本住在 `crates/app` 里，由那边的 crate 级 `#![allow(dead_code)]` 一并放开；
+// 搬进 lib 之后「pub 但模块私有」会被判成死码。逐条 `#[allow]` 会把噪音藏进实现细节，
+// 这里沿用同一条策略统一放开，接线完成后再删掉本行暴露真死码。
+#![allow(dead_code)]
+
+pub mod agent;
+pub mod backend;
+pub mod dialogs;
+pub mod dto;
+pub mod host;
+pub mod mock;
+pub mod mock_data;
+pub mod prefs;
+pub mod router;
+pub mod settings_bridge;
+mod settings_bridge_lang;
+pub mod state;
+pub mod theme;
+pub mod toast;
+pub mod wizard;
diff --git a/crates/presenter/src/mock.rs b/crates/presenter/src/mock.rs
new file mode 100644
index 0000000..9ad3ea7
--- /dev/null
+++ b/crates/presenter/src/mock.rs
@@ -0,0 +1,399 @@
+//! P0 假后端：用脚本化事件驱动骨架，验证 app ↔ core/agent 通道语义。
+//!
+//! 覆盖四条通道：实例运行状态（磁贴进度环）、AI 流式会话（含工具调用）、
+//! 对话框队列（进度对话框）、Toast。阶段 B 里由真正的 core/agent host 替换
+//! [`MockBackend`]，[`crate::dto::Backend`] 之上的 state/reducer 不动。
+//! 假数据本体在 [`crate::mock_data`]。
+
+use std::collections::VecDeque;
+use std::time::Duration;
+
+use crate::dialogs::{DialogKind, DialogRequest, DialogSource};
+use crate::dto::{
+    AgentEvent, AppCommand, AppEvent, Backend, ChatMessage, ChatRole, CoreEvent, InstanceId,
+    InstanceRuntime, LaunchStage, Progress,
+};
+use crate::mock_data::{mock_log_lines, mock_log_sessions, mock_versions};
+use crate::toast::{Toast, ToastKind};
+
+#[path = "mock/accounts.rs"]
+mod accounts_screen;
+#[path = "mock/instances.rs"]
+mod instances_screen;
+
+/// 启动脚本：按时间推进 download → verify → launch → running。
+#[derive(Debug)]
+struct LaunchScript {
+    id: InstanceId,
+    elapsed_ms: u64,
+}
+
+/// AI 流式脚本：每条提问回一段可切分的话 + 一次工具调用。
+#[derive(Debug)]
+struct ChatScript {
+    elapsed_ms: u64,
+    chunks: VecDeque<String>,
+    /// 流式助手消息在 app 会话里的序号
+    message_index: usize,
+}
+
+/// 假后端。
+#[derive(Debug, Default)]
+pub struct MockBackend {
+    events: VecDeque<AppEvent>,
+    launch: Option<LaunchScript>,
+    chat: Option<ChatScript>,
+    /// 已投递给 app 的会话消息条数（用来给 MessageDelta 算序号）
+    emitted_messages: usize,
+    next_dialog: u64,
+}
+
+impl MockBackend {
+    /// 预置一批假数据事件（实例/版本/日志会话）。
+    pub fn new() -> Self {
+        let mut backend = Self::default();
+        backend.seed();
+        backend
+    }
+
+    fn seed(&mut self) {
+        // 实例的截图矩阵（`ULL_INSTANCE_STATE=empty|demo|running`，见 `mock/instances.rs`）。
+        // 缺省与 `mock_data::mock_instances()` 逐字段相同——这里的开关只给出图用。
+        self.emit(AppEvent::Core(CoreEvent::InstancesChanged(
+            instances_screen::instances(&instances_screen::scenario()),
+        )));
+        // 三条都走 `emit`（同一个队尾），与上面那条实例事件的形状一致
+        self.emit(AppEvent::Core(CoreEvent::VersionListChanged(
+            mock_versions(),
+        )));
+        self.emit(AppEvent::Core(CoreEvent::LogSessionsChanged(
+            mock_log_sessions(),
+        )));
+        self.emit(AppEvent::Core(CoreEvent::LogLinesChanged(mock_log_lines())));
+        self.seed_accounts();
+    }
+
+    /// 账户页的截图矩阵（`ULL_ACCOUNT_STATE`，见 [`accounts_screen`]）。
+    fn seed_accounts(&mut self) {
+        let scenario = accounts_screen::scenario();
+        self.emit(AppEvent::Core(CoreEvent::AccountsChanged(
+            accounts_screen::accounts(&scenario),
+        )));
+        if let Some(view) = accounts_screen::device_login(&scenario) {
+            self.emit(AppEvent::Core(CoreEvent::DeviceLoginChanged(view)));
+        }
+        if let Some(view) = accounts_screen::authlib_login(&scenario) {
+            self.emit(AppEvent::Core(CoreEvent::AuthlibLoginChanged(view)));
+        }
+        if let Some(notice) = accounts_screen::notice(&scenario) {
+            self.emit(AppEvent::Core(CoreEvent::AccountNoticeChanged(Some(
+                notice,
+            ))));
+        }
+    }
+
+    fn emit(&mut self, event: AppEvent) {
+        self.events.push_back(event);
+    }
+
+    fn next_dialog_id(&mut self) -> u64 {
+        self.next_dialog += 1;
+        self.next_dialog
+    }
+
+    fn script_launch(&mut self, id: InstanceId) {
+        self.emit(AppEvent::Core(CoreEvent::InstanceRuntimeChanged {
+            id: id.clone(),
+            runtime: InstanceRuntime::Busy {
+                stage: LaunchStage::Download,
+                progress: Progress {
+                    done: 0,
+                    total: 1_500,
+                },
+            },
+        }));
+        self.launch = Some(LaunchScript { id, elapsed_ms: 0 });
+    }
+
+    fn step_launch(&mut self, elapsed: Duration) {
+        let Some((id, elapsed_ms)) = self.launch.as_mut().map(|script| {
+            script.elapsed_ms += u64::try_from(elapsed.as_millis()).unwrap_or(u64::MAX);
+            (script.id.clone(), script.elapsed_ms)
+        }) else {
+            return;
+        };
+
+        // 0~1.5s 下载、1.5~2.5s 校验、2.5~3s 启动、3s 后转为运行中
+        let runtime = if elapsed_ms < 1_500 {
+            InstanceRuntime::Busy {
+                stage: LaunchStage::Download,
+                progress: Progress {
+                    done: elapsed_ms,
+                    total: 1_500,
+                },
+            }
+        } else if elapsed_ms < 2_500 {
+            InstanceRuntime::Busy {
+                stage: LaunchStage::Verify,
+                progress: Progress {
+                    done: elapsed_ms - 1_500,
+                    total: 1_000,
+                },
+            }
+        } else if elapsed_ms < 3_000 {
+            InstanceRuntime::Busy {
+                stage: LaunchStage::Launch,
+                progress: Progress {
+                    done: elapsed_ms - 2_500,
+                    total: 500,
+                },
+            }
+        } else {
+            self.launch = None;
+            self.emit(AppEvent::Toast(Toast {
+                id: 0,
+                kind: ToastKind::Success,
+                text: "游戏已启动".to_string(),
+                remaining_ms: 0,
+            }));
+            InstanceRuntime::Running { pid: 12_345 }
+        };
+
+        self.emit(AppEvent::Core(CoreEvent::InstanceRuntimeChanged {
+            id,
+            runtime,
+        }));
+    }
+
+    fn script_chat(&mut self, text: String) {
+        let user_index = self.emitted_messages;
+        self.emit(AppEvent::Agent(AgentEvent::MessageAppended(
+            ChatMessage::user(text),
+        )));
+        self.emit(AppEvent::Agent(AgentEvent::MessageAppended(
+            ChatMessage::assistant_stream(),
+        )));
+        self.emitted_messages += 2;
+        self.chat = Some(ChatScript {
+            elapsed_ms: 0,
+            chunks: VecDeque::from(vec![
+                "先确认版本：".to_string(),
+                "官方 1.20.4 是正式版，".to_string(),
+                "装完再用 Fabric 加加载器。".to_string(),
+            ]),
+            message_index: user_index + 1,
+        });
+    }
+
+    fn step_chat(&mut self, elapsed: Duration) {
+        let Some(chat) = self.chat.as_mut() else {
+            return;
+        };
+        chat.elapsed_ms += u64::try_from(elapsed.as_millis()).unwrap_or(u64::MAX);
+        if chat.elapsed_ms < 300 {
+            return;
+        }
+        chat.elapsed_ms = 0;
+        let index = chat.message_index;
+        let chunk = chat.chunks.pop_front();
+
+        if let Some(delta) = chunk {
+            self.emit(AppEvent::Agent(AgentEvent::MessageDelta { index, delta }));
+            return;
+        }
+
+        // 流结束后补一次工具调用（工具执行在会话里可见）+ 收尾消息
+        self.emit(AppEvent::Agent(AgentEvent::ToolCallStarted {
+            name: "read_game_log".to_string(),
+            summary: "读取最近一次崩溃日志".to_string(),
+        }));
+        self.emit(AppEvent::Agent(AgentEvent::ToolCallFinished {
+            name: "read_game_log".to_string(),
+            ok: true,
+            summary: "读到 128 行，无 ERROR".to_string(),
+        }));
+        self.emit(AppEvent::Agent(AgentEvent::MessageFinished { index }));
+        self.emit(AppEvent::Agent(AgentEvent::MessageAppended(ChatMessage {
+            role: ChatRole::Assistant,
+            text: "日志没有 ERROR，问题更可能在 Java 版本。".to_string(),
+            tool: None,
+            streaming: false,
+        })));
+        self.emitted_messages += 2;
+        self.chat = None;
+    }
+
+    fn script_install(&mut self, version: String) {
+        let id = self.next_dialog_id();
+        self.emit(AppEvent::DialogRequested(DialogRequest {
+            id,
+            source: DialogSource::BackgroundTask,
+            title: format!("正在安装 {version}"),
+            body: String::new(),
+            kind: DialogKind::Progress {
+                label: "下载资源".to_string(),
+                progress: 0.0,
+            },
+        }));
+        self.emit(AppEvent::DialogClosed(id));
+        self.emit(AppEvent::Toast(Toast {
+            id: 0,
+            kind: ToastKind::Success,
+            text: format!("{version} 安装完成"),
+            remaining_ms: 0,
+        }));
+    }
+}
+
+impl Backend for MockBackend {
+    fn drain_events(&mut self) -> Vec<AppEvent> {
+        self.events.drain(..).collect()
+    }
+
+    fn dispatch(&mut self, command: AppCommand) {
+        match command {
+            AppCommand::LaunchInstance(id) => self.script_launch(id),
+            AppCommand::StopInstance(id) => {
+                self.launch = None;
+                self.emit(AppEvent::Core(CoreEvent::InstanceRuntimeChanged {
+                    id,
+                    runtime: InstanceRuntime::Idle,
+                }));
+            }
+            AppCommand::AskAgent(text) => self.script_chat(text),
+            AppCommand::InstallVersion(version) => self.script_install(version),
+            AppCommand::SetYolo(enabled) => self.emit(AppEvent::Toast(Toast {
+                id: 0,
+                kind: ToastKind::Info,
+                text: if enabled {
+                    "YOLO 已开启（审计照记）"
+                } else {
+                    "YOLO 已关闭"
+                }
+                .to_string(),
+                remaining_ms: 0,
+            })),
+            AppCommand::ListVersions(category) => {
+                self.emit(AppEvent::Core(CoreEvent::VersionListChanged(
+                    crate::mock_data::mock_versions_for(category),
+                )));
+            }
+            AppCommand::OpenLogSession(id) => {
+                // P0：换会话 = 换一批假日志行 + 一条诊断结论（日志页诊断卡片可见）
+                self.emit(AppEvent::Core(CoreEvent::LogLinesChanged(mock_log_lines())));
+                self.emit(AppEvent::Core(CoreEvent::DiagnosisReady(
+                    crate::mock_data::mock_diagnosis(id),
+                )));
+            }
+            AppCommand::RefreshAll => self.seed_accounts(),
+            // 与真 host 同一契约：取消登录把两条轨都收回 Idle（否则 Close 在 mock 下「没反应」）
+            AppCommand::CancelDeviceLogin => self.cancel_login(),
+            AppCommand::RefreshLogSessions | AppCommand::StopAgent => {}
+            // 其余指令（安装向导/账户/Java/设置/通知）由真实 host 承接：mock 不模拟
+            _ => {}
+        }
+    }
+
+    fn tick(&mut self, elapsed: Duration) {
+        self.step_launch(elapsed);
+        self.step_chat(elapsed);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::MockBackend;
+    use crate::dto::{AgentEvent, AppCommand, AppEvent, Backend, CoreEvent, InstanceRuntime};
+
+    #[test]
+    fn seeds_instances_and_versions() {
+        let mut backend = MockBackend::new();
+        let events = backend.drain_events();
+        // 实例 / 版本 / 会话 / 日志行 **+ 账户页的种子**（M114：账户列表 + 可选的登录面板态）
+        assert!(
+            events.len() >= 5,
+            "至少含账户列表，实际 {} 条",
+            events.len()
+        );
+        assert!(events
+            .iter()
+            .all(|event| matches!(event, AppEvent::Core(_))));
+        assert!(backend.drain_events().is_empty());
+    }
+
+    #[test]
+    fn launching_emits_progress_then_running() {
+        let mut backend = MockBackend::new();
+        backend.drain_events();
+        backend.dispatch(AppCommand::LaunchInstance("survival".to_string()));
+
+        let first = backend.drain_events();
+        assert!(matches!(
+            first[0],
+            AppEvent::Core(CoreEvent::InstanceRuntimeChanged { .. })
+        ));
+
+        backend.tick(std::time::Duration::from_millis(1_600));
+        let verify = backend.drain_events();
+        match &verify[0] {
+            AppEvent::Core(CoreEvent::InstanceRuntimeChanged {
+                runtime: InstanceRuntime::Busy { stage, .. },
+                ..
+            }) => assert_eq!(*stage, crate::dto::LaunchStage::Verify),
+            other => panic!("unexpected event: {other:?}"),
+        }
+
+        backend.tick(std::time::Duration::from_millis(2_000));
+        let done = backend.drain_events();
+        assert!(done.iter().any(|event| matches!(
+            event,
+            AppEvent::Core(CoreEvent::InstanceRuntimeChanged {
+                runtime: InstanceRuntime::Running { .. },
+                ..
+            })
+        )));
+    }
+
+    #[test]
+    fn stopping_cancels_the_launch_script() {
+        let mut backend = MockBackend::new();
+        backend.drain_events();
+        backend.dispatch(AppCommand::LaunchInstance("a".to_string()));
+        backend.drain_events();
+
+        backend.dispatch(AppCommand::StopInstance("a".to_string()));
+        let events = backend.drain_events();
+        assert!(matches!(
+            events[0],
+            AppEvent::Core(CoreEvent::InstanceRuntimeChanged {
+                runtime: InstanceRuntime::Idle,
+                ..
+            })
+        ));
+
+        // 脚本已取消：再推进时间也不会再产出事件
+        backend.tick(std::time::Duration::from_millis(5_000));
+        assert!(backend.drain_events().is_empty());
+    }
+
+    #[test]
+    fn asking_the_agent_streams_and_finishes() {
+        let mut backend = MockBackend::new();
+        backend.drain_events();
+        backend.dispatch(AppCommand::AskAgent("装哪个版本".to_string()));
+
+        let start = backend.drain_events();
+        assert_eq!(start.len(), 2);
+
+        let mut deltas = 0;
+        for _ in 0..6 {
+            backend.tick(std::time::Duration::from_millis(400));
+            let events = backend.drain_events();
+            deltas += events
+                .iter()
+                .filter(|event| matches!(event, AppEvent::Agent(AgentEvent::MessageDelta { .. })))
+                .count();
+        }
+        assert_eq!(deltas, 3);
+    }
+}
diff --git a/crates/presenter/src/mock/accounts.rs b/crates/presenter/src/mock/accounts.rs
new file mode 100644
index 0000000..668fc01
--- /dev/null
+++ b/crates/presenter/src/mock/accounts.rs
@@ -0,0 +1,177 @@
+//! 截图/演示用的账户矩阵（**只在 mock 后端**里被调用）。
+//!
+//! D30 要求账户页出五态 × 浅深：空态 / 多账号列表 / 设备码进行中 / 登录失败 / 第三方站表单。
+//! 截图通道强制 mock 后端（`AppOptions::mock`），所以这五态的**数据**必须由 mock 造：
+//! 走 `ULL_ACCOUNT_STATE` 选场景，与 `ULL_START_ROUTE` / `ULL_APPEARANCE_*` 同一套取证开关。
+//!
+//! ## 造的是什么、不造什么
+//!
+//! - 列表行造的是**公开字段**（名字 / 轨道 / 创建时间 / 服务器），与真 host 的
+//!   `AccountView` 同构；
+//! - **不造皮肤字节**：第三方轨的真图来自服务器，mock 里没有（伪造一张「假皮肤」正好违反
+//!   M114 的口径）。所以截图里皮肤区显示的是首字母块 + 「没有可用皮肤」。
+
+use crate::dto::{
+    AccountKind, AccountNotice, AccountNoticeCode, AccountView, AuthlibLoginView, DeviceLoginView,
+    LoginFailure,
+};
+
+impl super::MockBackend {
+    /// 取消登录：两条轨都发 Idle（真 host 的 `CancelDeviceLogin` 就是这么做的）。
+    ///
+    /// 为什么放在 mock 里也要认真做：M114 的 `Close` 回归闸与「关掉之后」的取证图都走这条
+    /// 通道——mock 用 `_ => {}` 兜底的话，Close 会看起来「点了没反应」，断言会假红/假绿。
+    pub(super) fn cancel_login(&mut self) {
+        self.emit(crate::dto::AppEvent::Core(
+            crate::dto::CoreEvent::DeviceLoginChanged(DeviceLoginView::new()),
+        ));
+        self.emit(crate::dto::AppEvent::Core(
+            crate::dto::CoreEvent::AuthlibLoginChanged(AuthlibLoginView::new()),
+        ));
+    }
+}
+
+/// 场景名（`ULL_ACCOUNT_STATE`；未知值按 `list` 处理）。
+pub(super) fn scenario() -> String {
+    std::env::var("ULL_ACCOUNT_STATE")
+        .unwrap_or_else(|_| "list".to_string())
+        .trim()
+        .to_lowercase()
+}
+
+/// 场景对应的账户列表（`empty` 场景是空表 ⇒ 空态）。
+pub(super) fn accounts(scenario: &str) -> Vec<AccountView> {
+    if scenario == "empty" {
+        return Vec::new();
+    }
+    vec![
+        account(
+            "account:mock-msa",
+            "Steve",
+            AccountKind::Microsoft,
+            "8f2f1d3c4b5a69788796a5b4c3d2e1f0",
+            "steve@outlook.com",
+            "2026-10-28 20:12",
+            true,
+            "",
+        ),
+        account(
+            "account:mock-authlib",
+            "Alex",
+            AccountKind::Authlib,
+            "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
+            "alex@example.com",
+            "2026-10-30 09:40",
+            false,
+            "https://littleskin.cn/api/yggdrasil/",
+        ),
+        account(
+            "account:mock-offline",
+            "Herobrine",
+            AccountKind::Offline,
+            "3c4d5e6f708192a3b4c5d6e7f8091a2b",
+            "",
+            "2026-10-31 21:05",
+            false,
+            "",
+        ),
+    ]
+}
+
+/// 场景对应的登录面板状态（`None` = 没有面板）。
+pub(super) fn device_login(scenario: &str) -> Option<DeviceLoginView> {
+    match scenario {
+        "device" | "expired" => Some(DeviceLoginView::waiting(
+            "ABCD-EFGH",
+            "https://www.microsoft.com/link",
+            900,
+            "",
+        )),
+        // 带**原因码**的失败：原文（中文诊断）留在 detail 里只进日志，页面画 i18n + Code
+        // `closed` 用同一份种子，再由 `force_account_state` 按一次「关闭」，出「关掉之后」的图。
+        "failed" | "closed" => Some(DeviceLoginView::failed_as(
+            LoginFailure::NotWhitelisted,
+            "微软拒绝了这次登录：AADSTS7000218（HTTP 403）—— 应用白名单还没批准，或网络被拦截",
+        )),
+        _ => None,
+    }
+}
+
+/// 场景对应的**第三方站**登录状态（`authlib-failed` = 地址不是 authlib 服务器）。
+///
+/// 原文（中文诊断）只进日志；页面据 `failure` 码出 i18n（复审 r1 P1-1 的第三方轨那一半）。
+pub(super) fn authlib_login(scenario: &str) -> Option<AuthlibLoginView> {
+    match scenario {
+        "authlib-failed" => Some(AuthlibLoginView {
+            phase: crate::dto::DeviceLoginPhase::Failed,
+            server: "https://example.invalid/api/yggdrasil/".to_string(),
+            server_name: String::new(),
+            message: "服务器返回 HTTP 404（不像可用的 authlib 认证服务器）".to_string(),
+            failure: Some(LoginFailure::NotAuthlibServer),
+            account_name: String::new(),
+        }),
+        _ => None,
+    }
+}
+
+/// 场景对应的横幅（`notice` = 离线名字不合法那条；`added` = 添加成功的正向样例）。
+pub(super) fn notice(scenario: &str) -> Option<AccountNotice> {
+    match scenario {
+        "notice" => Some(AccountNotice::new(
+            AccountNoticeCode::OfflineNameInvalid,
+            "ab",
+            "离线名字必须是 3–16 位字母/数字/下划线",
+        )),
+        "added" => Some(AccountNotice::new(AccountNoticeCode::Added, "Alex", "")),
+        _ => None,
+    }
+}
+
+#[allow(clippy::too_many_arguments)]
+fn account(
+    id: &str,
+    name: &str,
+    kind: AccountKind,
+    profile_id: &str,
+    login_name: &str,
+    created: &str,
+    active: bool,
+    server_url: &str,
+) -> AccountView {
+    AccountView {
+        id: id.to_string(),
+        name: name.to_string(),
+        kind,
+        profile_id: profile_id.to_string(),
+        login_name: login_name.to_string(),
+        created: created.to_string(),
+        active,
+        server_url: server_url.to_string(),
+        skin: None,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn the_empty_scenario_has_no_rows_and_the_list_scenario_covers_all_three_tracks() {
+        assert!(accounts("empty").is_empty());
+        let rows = accounts("list");
+        assert_eq!(rows.len(), 3);
+        assert!(rows.iter().any(|row| row.kind == AccountKind::Microsoft));
+        assert!(rows.iter().any(|row| row.kind == AccountKind::Authlib));
+        assert!(rows.iter().any(|row| row.kind == AccountKind::Offline));
+        assert_eq!(rows.iter().filter(|row| row.active).count(), 1);
+        assert!(rows.iter().all(|row| row.skin.is_none()), "mock 不伪造皮肤");
+    }
+
+    #[test]
+    fn the_device_states_are_renderable() {
+        assert!(device_login("device").is_some_and(|view| !view.user_code.is_empty()));
+        assert!(device_login("failed")
+            .is_some_and(|view| view.phase == crate::dto::DeviceLoginPhase::Failed));
+        assert!(device_login("list").is_none());
+    }
+}
diff --git a/crates/presenter/src/mock/instances.rs b/crates/presenter/src/mock/instances.rs
new file mode 100644
index 0000000..e320005
--- /dev/null
+++ b/crates/presenter/src/mock/instances.rs
@@ -0,0 +1,122 @@
+//! 截图/演示用的**实例场景**（只在 mock 后端里被调用）。
+//!
+//! D30 要求实例页出状态矩阵：空态 / 有实例 / 运行中（带 pid）/ 启动中（带百分比）。
+//! 截图通道强制 mock 后端（`AppOptions::mock`），所以这四态的**数据**必须由 mock 造：
+//! 走 `ULL_INSTANCE_STATE` 选场景，与 `ULL_ACCOUNT_STATE`（M114）/ `ULL_CONTENT_STATE`（M116）
+//! 同一套取证开关。
+//!
+//! ## 三个约束（塔台 M120 批的）
+//!
+//! 1. **不设变量 = 今天那 4 条**（Idle×3 + Failed×1）——[`crate::mock_data::mock_instances`]
+//!    原样返回，产品/单测的行为一字未变；
+//! 2. **这个开关只影响 mock 通道**：真 host 的实例来自 `core::game` 的快照，读不到这里；
+//! 3. `running` 的 pid 是**写死的 mock 值**（`1234`），不是真进程 pid——它证明的是
+//!    「`运行中 · pid {pid}` 这条文案的数字与分隔符不随语言变形」，不是「我能读到真 pid」。
+//!
+//! ```text
+//! ULL_INSTANCE_STATE=empty ULL_START_ROUTE=instances ULL_LANG=zh_cn \
+//!   unlucky-launcher-iced --screenshot=instances-empty-zh.png --software-renderer
+//! ```
+
+use crate::dto::{InstanceRuntime, InstanceSummary, LaunchStage, Progress};
+use crate::mock_data::mock_instances;
+
+/// 挑演示场景的环境变量。
+pub(crate) const STATE_ENV: &str = "ULL_INSTANCE_STATE";
+
+/// 场景名（未知值按 `demo` 处理，与 `ULL_ACCOUNT_STATE` 同一条兜底口径）。
+pub(super) fn scenario() -> String {
+    std::env::var(STATE_ENV)
+        .unwrap_or_else(|_| "demo".to_string())
+        .trim()
+        .to_lowercase()
+}
+
+/// 场景对应的实例列表。
+///
+/// | 场景 | 列表 | 页面看起来 |
+/// |---|---|---|
+/// | `empty` | 空表 | 空列表 + 「未选择实例」空态（`detail: None`） |
+/// | `demo`（缺省 / 未知值） | 4 条 Idle×3 + Failed×1 | 今天的样子（M90 起的基线） |
+/// | `running` | 4 条，其中 1 条 `Running{pid}`、1 条 `Busy{42%}` | 列表 overline 与详情状态行都带运行态 |
+pub(super) fn instances(scenario: &str) -> Vec<InstanceSummary> {
+    match scenario {
+        "empty" => Vec::new(),
+        "running" => running(),
+        _ => mock_instances(),
+    }
+}
+
+/// 运行态矩阵：同一批实例换 runtime（名字/版本/加载器都还是 `mock_data` 那一份）。
+///
+/// 三种态各留一条，是为了**一屏看完**状态文案的三种形状：正在跑（`pid`）、启动中（百分比）、
+/// 启动失败（原因）。少一条就得再出一张图，而图多一张就多一处可以撒谎的地方。
+fn running() -> Vec<InstanceSummary> {
+    let mut list = mock_instances();
+    for instance in &mut list {
+        match instance.id.as_str() {
+            "survival" => instance.runtime = InstanceRuntime::Running { pid: 1234 },
+            "vanilla-latest" => {
+                instance.runtime = InstanceRuntime::Busy {
+                    stage: LaunchStage::Download,
+                    progress: Progress {
+                        done: 630,
+                        total: 1_500,
+                    },
+                };
+            }
+            _ => {}
+        }
+    }
+    list
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// **默认行为不变**（塔台三条约束的第 1 条）：不设变量就是 `mock_data` 那一份。
+    ///
+    /// 抓得住：有人把 `demo` 分支改成了「顺手多造几条」——那会让所有既有截图与断言漂。
+    #[test]
+    fn the_demo_scenario_is_exactly_the_old_mock_list() {
+        for unknown in ["demo", "", "bogus"] {
+            let got = instances(unknown);
+            let want = mock_instances();
+            assert_eq!(got.len(), want.len(), "{unknown:?}");
+            assert_eq!(got, want, "{unknown:?} 必须与 mock_data 逐字段相同");
+        }
+    }
+
+    #[test]
+    fn the_empty_scenario_has_no_instances() {
+        assert!(instances("empty").is_empty());
+    }
+
+    /// 运行态矩阵：`Running` / `Busy` 各一条，且**名字与版本没被动手脚**（它们不是场景的一部分）。
+    #[test]
+    fn the_running_scenario_covers_running_and_busy() {
+        let list = instances("running");
+        assert_eq!(list.len(), mock_instances().len());
+        assert!(
+            list.iter().any(
+                |item| matches!(item.runtime, InstanceRuntime::Running { pid } if pid == 1234)
+            ),
+            "要有一条带固定 pid 的运行中实例"
+        );
+        assert!(list.iter().any(|item| matches!(
+            item.runtime,
+            InstanceRuntime::Busy {
+                stage: LaunchStage::Download,
+                ..
+            }
+        )));
+        assert_eq!(list[0].name, mock_instances()[0].name);
+    }
+
+    /// 环境变量名是**契约**（出图脚本与报告都写它，改名等于让文档说谎）。
+    #[test]
+    fn the_scenario_variable_is_named() {
+        assert_eq!(STATE_ENV, "ULL_INSTANCE_STATE");
+    }
+}
diff --git a/crates/presenter/src/mock_data.rs b/crates/presenter/src/mock_data.rs
new file mode 100644
index 0000000..edc1fd9
--- /dev/null
+++ b/crates/presenter/src/mock_data.rs
@@ -0,0 +1,238 @@
+//! P0 假数据：实例 / 版本 / 日志 / 诊断 / 工具调用样例。
+//!
+//! 只被 [`crate::mock`] 与阶段 B 的 main.rs 使用；真实后端接入后整文件可删。
+
+use crate::dto::{
+    AncientKind, ChatMessage, ChatRole, Diagnosis, DiagnosisReport, InstanceRuntime,
+    InstanceSummary, LoaderInfo, LoaderKind, LogLevel, LogLine, LogOutcome, LogSession, SessionId,
+    ToolCallView, VersionCategory, VersionKind, VersionSummary,
+};
+
+/// P0 演示实例：覆盖空闲 / 失败两种磁贴状态（运行中由启动脚本产生）。
+pub fn mock_instances() -> Vec<InstanceSummary> {
+    vec![
+        InstanceSummary {
+            id: "survival".to_string(),
+            name: "生存整合包".to_string(),
+            mc_version: "1.20.4".to_string(),
+            loader: LoaderInfo {
+                kind: LoaderKind::Fabric,
+                version: "0.16.5".to_string(),
+            },
+            last_played: Some("2026-10-29T19:22:00Z".to_string()),
+            runtime: InstanceRuntime::Idle,
+            icon: None,
+            isolation: "isolated".to_string(),
+            version_id: "1.20.4".to_string(),
+            version_present: true,
+        },
+        InstanceSummary {
+            id: "vanilla-latest".to_string(),
+            name: "原版最新".to_string(),
+            mc_version: "1.21.9".to_string(),
+            loader: LoaderInfo {
+                kind: LoaderKind::Vanilla,
+                version: String::new(),
+            },
+            last_played: Some("2026-10-28T21:03:00Z".to_string()),
+            runtime: InstanceRuntime::Idle,
+            icon: None,
+            isolation: "isolated".to_string(),
+            version_id: "1.21.9".to_string(),
+            version_present: true,
+        },
+        InstanceSummary {
+            id: "ancient-1.7.10".to_string(),
+            name: "远古 1.7.10".to_string(),
+            mc_version: "1.7.10".to_string(),
+            loader: LoaderInfo {
+                kind: LoaderKind::Forge,
+                version: "10.13.4.1614".to_string(),
+            },
+            last_played: None,
+            runtime: InstanceRuntime::Idle,
+            icon: None,
+            isolation: "shared".to_string(),
+            version_id: "1.7.10".to_string(),
+            version_present: false,
+        },
+        InstanceSummary {
+            id: "modded-dev".to_string(),
+            name: "开发测试".to_string(),
+            mc_version: "1.21.1".to_string(),
+            loader: LoaderInfo {
+                kind: LoaderKind::NeoForge,
+                version: "21.1.72".to_string(),
+            },
+            last_played: Some("2026-10-27T12:40:00Z".to_string()),
+            runtime: InstanceRuntime::Failed {
+                reason: "exit0 静默失败".to_string(),
+            },
+            icon: None,
+            isolation: "isolated".to_string(),
+            version_id: "1.21.1-neoforge-21.1.72".to_string(),
+            version_present: true,
+        },
+    ]
+}
+
+/// P0 演示版本列表（含远古版三子类，验证分类侧栏与警示徽标）。
+pub fn mock_versions() -> Vec<VersionSummary> {
+    fn row(id: &str, kind: VersionKind, released: &str, installed: bool) -> VersionSummary {
+        VersionSummary {
+            id: id.to_string(),
+            kind,
+            released: released.to_string(),
+            installed,
+        }
+    }
+    vec![
+        row("1.21.9", VersionKind::Release, "2026-09-20", false),
+        row("1.21.8", VersionKind::Release, "2026-07-11", true),
+        row("1.20.4", VersionKind::Release, "2023-12-07", true),
+        row("1.21.9-pre3", VersionKind::Snapshot, "2026-09-01", false),
+        row(
+            "rd-132211",
+            VersionKind::Ancient(AncientKind::Classic),
+            "2009-05-13",
+            false,
+        ),
+        row(
+            "a1.2.6",
+            VersionKind::Ancient(AncientKind::OldAlpha),
+            "2010-08-11",
+            false,
+        ),
+        row(
+            "b1.7.3",
+            VersionKind::Ancient(AncientKind::OldBeta),
+            "2011-07-08",
+            false,
+        ),
+    ]
+}
+
+/// 日志会话样例（✓ / ✗ / ⚠ 三种结局各一条）。
+pub fn mock_log_sessions() -> Vec<LogSession> {
+    vec![
+        LogSession {
+            id: "s-1029-1922".to_string(),
+            instance: "生存整合包".to_string(),
+            when: "10-29 19:22".to_string(),
+            outcome: LogOutcome::Ok,
+            duration_secs: 3_780,
+        },
+        LogSession {
+            id: "s-1029-1840".to_string(),
+            instance: "开发测试".to_string(),
+            when: "10-29 18:40".to_string(),
+            outcome: LogOutcome::Crashed,
+            duration_secs: 62,
+        },
+        LogSession {
+            id: "s-1029-1755".to_string(),
+            instance: "原版最新".to_string(),
+            when: "10-29 17:55".to_string(),
+            outcome: LogOutcome::SilentFail,
+            duration_secs: 8,
+        },
+    ]
+}
+
+/// 日志行样例（含一条 ERROR 供高亮验证）。
+pub fn mock_log_lines() -> Vec<LogLine> {
+    fn line(text: &str, level: LogLevel) -> LogLine {
+        LogLine {
+            text: text.to_string(),
+            level,
+        }
+    }
+    vec![
+        line(
+            "[19:22:01] [main/INFO] Launching Minecraft 1.20.4",
+            LogLevel::Info,
+        ),
+        line("[19:22:02] [main/INFO] Loading 42 mods", LogLevel::Info),
+        line(
+            "[19:22:03] [Render thread/WARN] GL vendor: unknown",
+            LogLevel::Warn,
+        ),
+        line(
+            "[19:22:05] [Render thread/ERROR] OpenGL 2.1 not supported",
+            LogLevel::Error,
+        ),
+        line("[19:22:05] [main/INFO] Stopping!", LogLevel::Info),
+    ]
+}
+
+/// 崩溃诊断样例（验证日志页诊断卡片 + 「让 AI 详解」入口）。
+pub fn mock_diagnosis(session: SessionId) -> DiagnosisReport {
+    DiagnosisReport {
+        session,
+        diagnosis: Diagnosis {
+            rule: "gpu.driver_old".to_string(),
+            title: "显卡驱动过旧（OpenGL 版本不足）".to_string(),
+            confidence: 92,
+            hint: "升级显卡驱动，或在启动参数里改用软件渲染".to_string(),
+            fix: Some("switch_software_renderer".to_string()),
+        },
+    }
+}
+
+/// 工具调用条目样例（AI 面板静态填充用）。
+pub fn mock_tool_message() -> ChatMessage {
+    ChatMessage {
+        role: ChatRole::Tool,
+        text: "读到 128 行，无 ERROR".to_string(),
+        tool: Some(ToolCallView {
+            name: "read_game_log".to_string(),
+            ok: true,
+            summary: "读到 128 行，无 ERROR".to_string(),
+        }),
+        streaming: false,
+    }
+}
+
+/// 分类 → 该分类下的假版本（下载页切换分类时用）。
+pub fn mock_versions_for(category: VersionCategory) -> Vec<VersionSummary> {
+    mock_versions()
+        .into_iter()
+        .filter(|version| match category {
+            VersionCategory::Release => version.kind == VersionKind::Release,
+            VersionCategory::Snapshot => version.kind == VersionKind::Snapshot,
+            VersionCategory::Ancient(kind) => version.kind == VersionKind::Ancient(kind),
+            VersionCategory::Modpack | VersionCategory::Mod => false,
+        })
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::dto::{AncientKind, VersionCategory, VersionKind};
+    use crate::mock_data::{mock_instances, mock_versions_for};
+
+    #[test]
+    fn mock_instances_cover_the_tile_states() {
+        let instances = mock_instances();
+        assert_eq!(instances.len(), 4);
+        assert!(instances.iter().any(|instance| matches!(
+            instance.runtime,
+            crate::dto::InstanceRuntime::Failed { .. }
+        )));
+    }
+
+    #[test]
+    fn versions_are_filtered_by_category() {
+        let release = mock_versions_for(VersionCategory::Release);
+        assert!(release
+            .iter()
+            .all(|version| version.kind == VersionKind::Release));
+        assert_eq!(release.len(), 3);
+
+        let classic = mock_versions_for(VersionCategory::Ancient(AncientKind::Classic));
+        assert_eq!(classic.len(), 1);
+        assert_eq!(classic[0].id, "rd-132211");
+
+        assert!(mock_versions_for(VersionCategory::Mod).is_empty());
+    }
+}
diff --git a/crates/presenter/src/prefs.rs b/crates/presenter/src/prefs.rs
new file mode 100644
index 0000000..a0dc13a
--- /dev/null
+++ b/crates/presenter/src/prefs.rs
@@ -0,0 +1,333 @@
+//! UI 偏好项与持久化键登记（导航折叠、AI 栏折叠、磁贴尺寸、视图、主题三态与外观四件、下载分类）。
+//!
+//! 偏好不自己写盘：core::setting 的 schema 按 [`keys::ALL`] 登记这些键，
+//! app 启动时读一次、变更时写回（跨模块约定见 `DevDocs/SubAgentsTalk/app-DTO通道约定.md`）。
+//! 落盘实现是 [`crate::settings_bridge`]（同一份 `config/launcher.json`，与 `ull config set` 同源），
+//! 主题三态 + `appearance.*` 高级键已接（M41）；其余 UI 偏好键仍只在内存里（后续 mission 接）。
+
+/// 背景图填充模式（09 §101）。直接复用 core 的枚举：取值与落盘词表只有一处真相。
+pub use unlucky_core::setting::appearance::BgFill;
+
+pub use unlucky_core::setting::appearance::PALETTE_SOURCES;
+/// 外观下层的三张表/常量（D36·D37·D38）：复用 core 的定义，一处真相。
+///
+/// [`WINDOW_ALPHA_MIN`] 还要给 `unlucky-app-iced` 的 win32 α 层用（它只依赖本 crate，不直接依赖
+/// core）：窗口 α 的硬底必须与设置侧同源，两边各写一个 `0.08` 迟早会漂。
+///
+/// 同理 [`PANEL_ALPHA_MIN`]（0.4）与 [`BG_DIM_MAX`]（0.95）也在这里重导出：M93 的 UI 侧要按它们
+/// 钳位滑块与暗化，而 `app-iced` 不直接依赖 core——不重导出就只能各抄一份字面量。
+pub use unlucky_core::setting::appearance::{
+    PaletteSource, TitlebarMode, WindowCorner, BG_DIM_MAX, PANEL_ALPHA_MIN, WINDOW_ALPHA_MIN,
+    WINDOW_CORNERS,
+};
+
+/// 系统版本探测（M116）：Windows 侧「能不能用 DWM 圆角」的判据要 build 号，而
+/// `unlucky-app-iced` 不直接依赖 `unlucky-core`（分层：UI → presenter → core），
+/// 所以在这里做**唯一一次**重导出，`platform` 只认 [`WindowsVersion`]。
+///
+/// [`WIN11_MIN_BUILD`] = 22000：Win11 与 Server 2025 共用同一内核判据（M116 实测本机
+/// Server 2025 build 26100 落在这条线之上）。
+pub use unlucky_core::platform::windows_version::{
+    probe as probe_windows_version, WindowsVersion, WIN11_MIN_BUILD,
+};
+
+use crate::dto::VersionCategory;
+
+/// 预设强调色板（09 §104）。**必须**与 UI 侧设置页「外观」分组的色板控件同序同值：
+/// UI 侧只回传索引，十六进制串由这张表给出（一处真相）。
+pub const ACCENT_PRESETS: [&str; 8] = [
+    "#0078D4", "#0F6CBD", "#107C10", "#9D5D00", "#C42B1C", "#8764B8", "#C239B3", "#00B7C3",
+];
+
+/// 磁贴尺寸（Q24-3：小 6 列 / 中 4 列 / 大 3 列）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum TileSize {
+    /// 小：6 列，只留图标/名字/启动键
+    Small,
+    /// 中：4 列（D16 默认）
+    #[default]
+    Medium,
+    /// 大：3 列，显示完整徽标与最后游玩时间
+    Large,
+}
+
+impl TileSize {
+    /// 该尺寸对应的网格列数。
+    pub fn columns(self) -> usize {
+        match self {
+            Self::Small => 6,
+            Self::Medium => 4,
+            Self::Large => 3,
+        }
+    }
+
+    /// 设置页/实例页分段控件的文案。
+    pub fn label(self) -> &'static str {
+        match self {
+            Self::Small => "小",
+            Self::Medium => "中",
+            Self::Large => "大",
+        }
+    }
+}
+
+/// 实例页视图模式。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum InstanceView {
+    /// 磁贴网格（默认）
+    #[default]
+    Tiles,
+    /// 紧凑列表
+    List,
+}
+
+/// 主题三态（D17，P0 交付）：`appearance.theme_mode ∈ {light, dark, auto}`，出厂 auto。
+///
+/// `auto` = 跟随系统（由 UI 侧的令牌层读系统调色板，随 OS 热更；探测口径见
+/// [`crate::theme::system_theme_value`]）；`light` / `dark` 钉死**自绘体系**的取值。
+/// 三个取值怎么变成框架颜色是 UI 侧的事，本 crate 只给语义。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum ThemeMode {
+    /// 跟随系统（默认）
+    #[default]
+    Auto,
+    /// 强制浅色
+    Light,
+    /// 强制深色
+    Dark,
+}
+
+impl ThemeMode {
+    /// 落盘取值（`appearance.theme_mode`）：`auto` / `light` / `dark`。
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Auto => "auto",
+            Self::Light => "light",
+            Self::Dark => "dark",
+        }
+    }
+
+    /// 从落盘取值解析；未知值按 `auto` 兜底（配置被手改坏也不崩）。
+    pub fn from_key_value(value: &str) -> Self {
+        match value {
+            "light" => Self::Light,
+            "dark" => Self::Dark,
+            _ => Self::Auto,
+        }
+    }
+}
+
+/// 09 §101-104「外观（高级）」四件的取值快照（出厂全部关闭）。
+///
+/// 与 `unlucky_core::setting::appearance::Appearance` 一一对应，但字段类型是 UI 侧好用的
+/// `f32`/`String`；落盘由 [`crate::settings_bridge`] 转成 schema 键。
+#[derive(Debug, Clone, PartialEq, Default)]
+pub struct AppearancePrefs {
+    /// 背景图总开关
+    pub bg_image_enabled: bool,
+    /// 背景图路径（PNG；空 = 未设置）
+    pub bg_image: String,
+    /// 填充模式
+    pub bg_fill: BgFill,
+    /// 暗化层强度 0.0~0.9
+    pub bg_dim: f32,
+    /// 面板半透明度 0.4~1.0
+    pub panel_alpha: f32,
+    /// 玻璃拟态卡片
+    pub glass: bool,
+    /// 自定义强调色 `#RRGGBB`；空 = 出厂 [#0078D4]
+    pub accent_color: String,
+}
+
+impl AppearancePrefs {
+    /// 出厂态：Metro 纯色，四个高级特性全关。
+    pub fn factory() -> Self {
+        Self {
+            bg_image_enabled: false,
+            bg_image: String::new(),
+            bg_fill: BgFill::Cover,
+            bg_dim: 0.35,
+            panel_alpha: 1.0,
+            glass: false,
+            accent_color: String::new(),
+        }
+    }
+
+    /// 背景图是否真的生效（开关打开且路径非空）。
+    pub fn bg_active(&self) -> bool {
+        self.bg_image_enabled && !self.bg_image.trim().is_empty()
+    }
+
+    /// 规范化写入强调色：`#RRGGBB` 才接受（空串 = 恢复出厂）。
+    ///
+    /// 返回 `false` 表示输入不合法（调用方据此亮设置页的 warn 行，不改现状）。
+    pub fn set_accent(&mut self, text: &str) -> bool {
+        let trimmed = text.trim();
+        if trimmed.is_empty() {
+            self.accent_color.clear();
+            return true;
+        }
+        match unlucky_core::setting::appearance::normalize_hex(trimmed) {
+            Some(hex) => {
+                self.accent_color = hex;
+                true
+            }
+            None => false,
+        }
+    }
+
+    /// 用预设色板第 `index` 个颜色（越界忽略）。
+    pub fn set_accent_preset(&mut self, index: usize) -> bool {
+        match ACCENT_PRESETS.get(index) {
+            Some(hex) => self.set_accent(hex),
+            None => false,
+        }
+    }
+}
+
+/// 外观下层的**只读**快照：整窗 α / 标题栏三态 / 配色来源 / 窗口圆角（D36·D37·D38 · M116）。
+///
+/// 不并进 [`AppearancePrefs`] 的两个理由：那个结构体由 `settings_bridge` 逐字段字面量
+/// 构造（加字段就得改那边），且这**四个**键只读不写——落盘仍走 core 的 `Appearance::write`。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct AppearanceBase {
+    /// 整窗透明度 [`WINDOW_ALPHA_MIN`]~1.0（1.0 = 完全不透明）
+    pub window_opacity: f32,
+    /// 标题栏三态（`auto` 的具体判定属于 UI 侧，本 crate 只给值）
+    pub titlebar_mode: TitlebarMode,
+    /// 配色来源档（三级编排在 `unlucky-design`，本 crate 只给值）
+    pub palette_source: PaletteSource,
+    /// 窗口外框圆角策略（M116：`system` / `square`；能不能圆由平台决定）
+    pub window_corner: WindowCorner,
+}
+
+impl AppearanceBase {
+    /// 出厂态：不透明 / `auto` / 内置色卡 / 跟随系统圆角。
+    #[must_use]
+    pub fn factory() -> Self {
+        Self {
+            window_opacity: 1.0,
+            titlebar_mode: TitlebarMode::Auto,
+            palette_source: PaletteSource::Preset,
+            window_corner: WindowCorner::System,
+        }
+    }
+
+    /// 从配置文档读一份快照：缺键 → 出厂默认、越界 → 钳位、非法枚举 → 回落。
+    ///
+    /// 三条语义都在 core 里落地（本函数只搬运，不重新判一遍）。
+    #[must_use]
+    pub fn from_document(doc: &unlucky_core::setting::document::SettingDocument) -> Self {
+        let appearance = unlucky_core::setting::appearance::Appearance::read(doc);
+        Self {
+            window_opacity: appearance.window_opacity as f32,
+            titlebar_mode: appearance.titlebar_mode,
+            palette_source: appearance.palette_source,
+            window_corner: appearance.window_corner,
+        }
+    }
+
+    /// 整窗 α 是否需要真的落到窗口上（1.0 = 不透明，调 FFI 纯属多余）。
+    #[must_use]
+    pub fn is_transparent(&self) -> bool {
+        self.window_opacity < 1.0
+    }
+}
+
+/// 需要跨会话记忆的 UI 偏好。
+///
+/// 注意：`Eq` 不成立（[`AppearancePrefs`] 带 `f32` 滑条值），用到的地方按 `PartialEq` 比。
+#[derive(Debug, Clone, PartialEq)]
+pub struct UiPrefs {
+    /// 左侧导航栏折叠成图标条
+    pub nav_collapsed: bool,
+    /// 右侧 AI 栏折叠成 icon 轨
+    pub ai_collapsed: bool,
+    /// 磁贴尺寸
+    pub tile_size: TileSize,
+    /// 实例页视图
+    pub instance_view: InstanceView,
+    /// 主题模式
+    pub theme: ThemeMode,
+    /// 外观（高级）四件（09 §101-104）
+    pub appearance: AppearancePrefs,
+    /// 下载页选中的分类
+    pub download_category: VersionCategory,
+}
+
+impl Default for UiPrefs {
+    fn default() -> Self {
+        Self {
+            nav_collapsed: false,
+            ai_collapsed: false,
+            // D16 默认中磁贴（4 列）
+            tile_size: TileSize::Medium,
+            instance_view: InstanceView::Tiles,
+            theme: ThemeMode::Auto,
+            appearance: AppearancePrefs::factory(),
+            download_category: VersionCategory::Release,
+        }
+    }
+}
+
+/// 持久化键名登记（core::setting schema 按此注册；改名等于迁移，慎动）。
+pub mod keys {
+    /// 导航栏折叠
+    pub const NAV_COLLAPSED: &str = "ui.nav.collapsed";
+    /// AI 栏折叠
+    pub const AI_COLLAPSED: &str = "ui.ai.collapsed";
+    /// 磁贴尺寸
+    pub const TILE_SIZE: &str = "ui.instances.tile_size";
+    /// 实例页视图（磁贴/列表）
+    pub const INSTANCE_VIEW: &str = "ui.instances.view";
+    /// 主题三态（D17；与设置页「外观」分组同名，取值见 [`super::ThemeMode::as_str`]）
+    pub const THEME_MODE: &str = "appearance.theme_mode";
+    /// 背景图开关（09 §101）
+    pub const BG_IMAGE_ENABLED: &str = "appearance.bg_image_enabled";
+    /// 背景图路径
+    pub const BG_IMAGE: &str = "appearance.bg_image";
+    /// 背景图填充模式
+    pub const BG_FILL: &str = "appearance.bg_fill";
+    /// 暗化层强度
+    pub const BG_DIM: &str = "appearance.bg_dim";
+    /// 面板半透明度（09 §102）
+    pub const PANEL_ALPHA: &str = "appearance.panel_alpha";
+    /// 玻璃拟态卡片（09 §103）
+    pub const GLASS: &str = "appearance.glass";
+    /// 自定义强调色（09 §104）
+    pub const ACCENT_COLOR: &str = "appearance.accent_color";
+    /// 下载页分类
+    pub const DOWNLOAD_CATEGORY: &str = "ui.download.category";
+    /// 整窗透明度（D36；下限见 [`super::WINDOW_ALPHA_MIN`]）
+    pub const WINDOW_OPACITY: &str = "appearance.window_opacity";
+    /// 标题栏三态（D37）
+    pub const TITLEBAR_MODE: &str = "appearance.titlebar_mode";
+    /// 配色来源档（D38）
+    pub const PALETTE_SOURCE: &str = "appearance.palette_source";
+    /// 窗口圆角策略（M116；`system` / `square`）
+    pub const WINDOW_CORNER: &str = "appearance.window_corner";
+
+    /// 本模块登记的全部键（自检/迁移用）。
+    pub const ALL: [&str; 17] = [
+        NAV_COLLAPSED,
+        AI_COLLAPSED,
+        TILE_SIZE,
+        INSTANCE_VIEW,
+        THEME_MODE,
+        BG_IMAGE_ENABLED,
+        BG_IMAGE,
+        BG_FILL,
+        BG_DIM,
+        PANEL_ALPHA,
+        GLASS,
+        ACCENT_COLOR,
+        DOWNLOAD_CATEGORY,
+        WINDOW_OPACITY,
+        TITLEBAR_MODE,
+        PALETTE_SOURCE,
+        WINDOW_CORNER,
+    ];
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/presenter/src/prefs/tests.rs b/crates/presenter/src/prefs/tests.rs
new file mode 100644
index 0000000..2cb058d
--- /dev/null
+++ b/crates/presenter/src/prefs/tests.rs
@@ -0,0 +1,109 @@
+//! `prefs` 的单测（拆文件守 400 行上限；结构体与 re-export 一律留在 `prefs.rs`）。
+
+use super::{
+    keys, AppearanceBase, InstanceView, PaletteSource, ThemeMode, TileSize, TitlebarMode, UiPrefs,
+    WindowCorner, WINDOW_ALPHA_MIN,
+};
+
+#[test]
+fn defaults_match_d16() {
+    let prefs = UiPrefs::default();
+    assert_eq!(prefs.tile_size, TileSize::Medium);
+    assert_eq!(prefs.tile_size.columns(), 4);
+    assert_eq!(prefs.instance_view, InstanceView::Tiles);
+    assert_eq!(prefs.theme, ThemeMode::Auto);
+    assert_eq!(prefs.theme.as_str(), "auto");
+    assert!(!prefs.nav_collapsed);
+    assert!(!prefs.ai_collapsed);
+}
+
+#[test]
+fn tile_size_columns_follow_q24() {
+    assert_eq!(TileSize::Small.columns(), 6);
+    assert_eq!(TileSize::Medium.columns(), 4);
+    assert_eq!(TileSize::Large.columns(), 3);
+}
+
+#[test]
+fn theme_mode_round_trips_through_key_values() {
+    for mode in [ThemeMode::Auto, ThemeMode::Light, ThemeMode::Dark] {
+        assert_eq!(ThemeMode::from_key_value(mode.as_str()), mode);
+    }
+    // 坏值兜底
+    assert_eq!(ThemeMode::from_key_value("solarized"), ThemeMode::Auto);
+}
+
+#[test]
+fn pref_keys_are_unique() {
+    let mut keys = keys::ALL.to_vec();
+    let total = keys.len();
+    keys.sort_unstable();
+    keys.dedup();
+    assert_eq!(keys.len(), total);
+}
+
+fn base_of(raw: serde_json::Value) -> AppearanceBase {
+    let schema = unlucky_core::setting::keys::launcher_schema();
+    let (doc, _) = unlucky_core::setting::document::SettingDocument::load(&schema, &raw);
+    AppearanceBase::from_document(&doc)
+}
+
+#[test]
+fn appearance_base_missing_keys_use_factory() {
+    let base = base_of(serde_json::json!({}));
+    assert_eq!(
+        base,
+        AppearanceBase::factory(),
+        "缺键 → 出厂态（不透明 / auto / preset）"
+    );
+    assert!(!base.is_transparent(), "出厂不透明 → 不下发窗口 α");
+}
+
+#[test]
+fn appearance_base_clamps_out_of_range_opacity() {
+    for raw in [0.0, 0.02, -1.0] {
+        let base = base_of(serde_json::json!({ "appearance": { "window_opacity": raw } }));
+        assert_eq!(
+            base.window_opacity, WINDOW_ALPHA_MIN as f32,
+            "raw={raw} 应夹到下限"
+        );
+    }
+    for (raw, want) in [(0.6, 0.6), (3.0, 1.0)] {
+        let base = base_of(serde_json::json!({ "appearance": { "window_opacity": raw } }));
+        assert_eq!(base.window_opacity, want, "raw={raw}");
+    }
+}
+
+#[test]
+fn appearance_base_illegal_enums_fall_back_and_legal_ones_read_through() {
+    let bad = base_of(serde_json::json!({
+        "appearance": { "titlebar_mode": "allways", "palette_source": "desktop" }
+    }));
+    assert_eq!(bad.titlebar_mode, TitlebarMode::Auto, "非法 → auto");
+    assert_eq!(bad.palette_source, PaletteSource::Preset, "非法 → preset");
+    // 合法值必须照读：否则「回落」测试会因为实现恒回默认而假绿。
+    let good = base_of(serde_json::json!({
+        "appearance": { "titlebar_mode": "never", "palette_source": "wallpaper" }
+    }));
+    assert_eq!(good.titlebar_mode, TitlebarMode::Never);
+    assert_eq!(good.palette_source, PaletteSource::Wallpaper);
+}
+
+/// **M116**：`appearance.window_corner` 的读侧——缺键 = 跟随系统、写 `square` 读回 `square`。
+///
+/// 抓得住：`AppearanceBase::from_document` 漏搬这一格（那会让设置页永远显示「跟随系统」，
+/// 用户点了直角重启后又变回去）。
+/// 抓不住：这台机器能不能真圆（`app-iced` 的 `platform::plan_corner` 管）。
+#[test]
+fn window_corner_round_trips_through_the_document() {
+    assert_eq!(
+        base_of(serde_json::json!({})).window_corner,
+        WindowCorner::System,
+        "缺键 → 出厂跟随系统"
+    );
+    let square = base_of(serde_json::json!({ "appearance": { "window_corner": "square" } }));
+    assert_eq!(square.window_corner, WindowCorner::Square);
+    // 坏值：core 侧落到 system（并留诊断），这里只钉 UI 侧看到的值。
+    let broken = base_of(serde_json::json!({ "appearance": { "window_corner": "rounded" } }));
+    assert_eq!(broken.window_corner, WindowCorner::System);
+}
diff --git a/crates/presenter/src/router.rs b/crates/presenter/src/router.rs
new file mode 100644
index 0000000..5a38e21
--- /dev/null
+++ b/crates/presenter/src/router.rs
@@ -0,0 +1,200 @@
+//! 页面路由与 AI 助手栏形态（09 §1 / D16）。
+//!
+//! 栈语义抄 HMCL 的导航栈：**顶层页面互相替换**（实例/下载/日志/设置），
+//! 子页面（实例详情、AI 独立页）压栈，`back()` 逐层回退。
+//! 本模块刻意不依赖 Slint 类型，便于单元测试；UI 侧枚举映射在 main.rs 的转换层做。
+
+use crate::dto::InstanceId;
+
+/// 一级导航项（左侧导航栏高亮单位）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum NavSection {
+    /// 实例
+    Instances,
+    /// 下载 / 版本管理 + 内容库（M109：内容库复用这一项，不新增第 6 个图标）
+    Download,
+    /// 日志
+    Logs,
+    /// 设置
+    Settings,
+}
+
+/// 页面路由。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Route {
+    /// G1 实例页（主页）
+    Instances,
+    /// G2 下载页（M107/M108 起是「版本管理」）
+    Download,
+    /// 内容库（M109）：整合包 / Mod / 资源包 / 光影，来源 Modrinth / CurseForge
+    ///
+    /// 它是**顶层页**（跟版本管理一样整栈替换），但高亮复用 [`NavSection::Download`]：
+    /// 用户令「下载页只负责下载整合包和Mod/光影」⇒ 同一入口下两块内容，不是一个新图标。
+    Content,
+    /// G3 日志页
+    Logs,
+    /// G6 设置页
+    Settings,
+    /// G7 账户页（三轨登录：微软正版 / 第三方皮肤站 / 本地档案）
+    ///
+    /// 一级页，但**不进主序列**：入口是导航轨底部的头像位（`shell/nav.rs`），
+    /// 所以 [`Route::nav`] 对它返回 `None`（不点亮四个主项中的任何一个）。
+    Accounts,
+    /// 实例详情（G4）：从磁贴点进来，返回时回到实例页
+    Detail(InstanceId),
+    /// AI 助手独立页（D16 双形态之一）
+    Agent,
+}
+
+impl Route {
+    /// 是否是一级导航页（互相替换，不进栈）。
+    pub fn is_top_level(&self) -> bool {
+        matches!(
+            self,
+            // M109 的 `Content` 与 M114 的 `Accounts` 都是一级页：两个都留。
+            Self::Instances
+                | Self::Download
+                | Self::Content
+                | Self::Logs
+                | Self::Settings
+                | Self::Accounts
+        )
+    }
+
+    /// 该路由高亮哪个导航项（None = 没有导航项高亮，如 AI 独立页）。
+    pub fn nav(&self) -> Option<NavSection> {
+        match self {
+            Self::Instances | Self::Detail(_) => Some(NavSection::Instances),
+            Self::Download | Self::Content => Some(NavSection::Download),
+            Self::Logs => Some(NavSection::Logs),
+            Self::Settings => Some(NavSection::Settings),
+            Self::Accounts | Self::Agent => None,
+        }
+    }
+}
+
+/// AI 栏形态：右侧栏 / 独立全宽页（两形态共享同一份会话状态）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AiPanelMode {
+    /// 右侧常驻栏
+    Docked,
+    /// 拆出的独立全宽页
+    Page,
+}
+
+/// 导航栈。
+#[derive(Debug, Clone)]
+pub struct Router {
+    stack: Vec<Route>,
+}
+
+impl Default for Router {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl Router {
+    /// 启动时停在实例页。
+    pub fn new() -> Self {
+        Self {
+            stack: vec![Route::Instances],
+        }
+    }
+
+    /// 当前页面。
+    pub fn route(&self) -> &Route {
+        // 栈不变量：构造后永远非空（navigate/back 都不允许清空）
+        self.stack.last().expect("router stack is never empty")
+    }
+
+    /// 栈深度（1 表示没有可回退的子页面）。
+    pub fn depth(&self) -> usize {
+        self.stack.len()
+    }
+
+    /// 是否能回退。
+    pub fn can_go_back(&self) -> bool {
+        self.stack.len() > 1
+    }
+
+    /// 跳转到某路由：一级页替换整栈，子页面压栈（重复目标不重复压栈）。
+    pub fn navigate(&mut self, route: Route) {
+        if route.is_top_level() {
+            self.stack.clear();
+            self.stack.push(route);
+            return;
+        }
+        if self.stack.last() == Some(&route) {
+            return;
+        }
+        self.stack.push(route);
+    }
+
+    /// 回退一层；已在根页面时返回 `false`。
+    pub fn back(&mut self) -> bool {
+        if self.stack.len() <= 1 {
+            return false;
+        }
+        self.stack.pop();
+        true
+    }
+
+    /// 当前 AI 栏形态（栈顶是 Agent 页即为独立页形态）。
+    pub fn ai_mode(&self) -> AiPanelMode {
+        if self.route() == &Route::Agent {
+            AiPanelMode::Page
+        } else {
+            AiPanelMode::Docked
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{AiPanelMode, NavSection, Route, Router};
+
+    #[test]
+    fn top_level_navigation_replaces_the_stack() {
+        let mut router = Router::new();
+        router.navigate(Route::Detail("a".into()));
+        assert_eq!(router.depth(), 2);
+
+        router.navigate(Route::Download);
+        assert_eq!(router.depth(), 1);
+        assert_eq!(router.route(), &Route::Download);
+    }
+
+    #[test]
+    fn detail_pushes_and_back_pops_to_instances() {
+        let mut router = Router::new();
+        router.navigate(Route::Detail("survival".into()));
+        assert!(router.can_go_back());
+        assert_eq!(router.route().nav(), Some(NavSection::Instances));
+
+        assert!(router.back());
+        assert_eq!(router.route(), &Route::Instances);
+        assert!(!router.back());
+    }
+
+    #[test]
+    fn agent_page_switches_ai_panel_mode() {
+        let mut router = Router::new();
+        assert_eq!(router.ai_mode(), AiPanelMode::Docked);
+
+        router.navigate(Route::Agent);
+        assert_eq!(router.ai_mode(), AiPanelMode::Page);
+
+        router.back();
+        assert_eq!(router.ai_mode(), AiPanelMode::Docked);
+    }
+
+    #[test]
+    fn navigating_to_the_same_sub_route_does_not_grow_the_stack() {
+        let mut router = Router::new();
+        router.navigate(Route::Agent);
+        router.navigate(Route::Agent);
+        assert_eq!(router.depth(), 2);
+        assert_eq!(router.route().nav(), None);
+    }
+}
diff --git a/crates/presenter/src/settings_bridge.rs b/crates/presenter/src/settings_bridge.rs
new file mode 100644
index 0000000..3b9021c
--- /dev/null
+++ b/crates/presenter/src/settings_bridge.rs
@@ -0,0 +1,352 @@
+//! 设置持久化桥：把 UI 偏好落到 `core::setting` 的 schema 文件里，并支持**外部热改热切**。
+//!
+//! 三条纪律（`DevDocs/SubAgentsTalk/app-DTO通道约定.md` §6 / AGENTS §6）：
+//!
+//! 1. **不另立配置文件**：读写的就是 `ull config set/get` 与 AI `set_config` 用的那一份
+//!    `<data root>/config/launcher.json`（`core::platform::data_dir` 解析数据根、`layout` 给路径）；
+//! 2. **不自己拼 JSON**：一律过 `core::setting::store::SettingStore`（schema 校验 + 原子写）；
+//! 3. **不 import 领域类型**：跨边界只看「键名 + 取值」，领域模型留在 core。
+//!
+//! 热切：文件 `mtime` 变了就整份重读（AI / CLI 改完下一拍即生效），见 [`SettingsBridge::reload_if_changed`]。
+
+use std::path::{Path, PathBuf};
+use std::time::SystemTime;
+
+use unlucky_core::platform::data_dir::{DataDirRequest, DataMode, Resolver};
+use unlucky_core::platform::layout::LauncherLayout;
+use unlucky_core::platform::paths::Platform;
+use unlucky_core::setting::appearance::Appearance;
+use unlucky_core::setting::keys::launcher_schema;
+use unlucky_core::setting::store::SettingStore;
+
+use crate::prefs::{AppearanceBase, AppearancePrefs, ThemeMode};
+
+/// 数据根配置键（决定 `launcher.json` 落在哪个数据目录；与 CLI 的 `DATA_ROOT_KEYS` 同源同义）。
+const DATA_ROOT_KEYS: [&str; 4] = [
+    "core.data_mode",
+    "core.data_custom_root",
+    "core.launcher_home",
+    "core.game_home",
+];
+
+/// 设置文件桥（一个进程一份）。
+#[derive(Debug)]
+pub struct SettingsBridge {
+    /// `config/launcher.json`；`None` = 数据根解析不出来（内存态运行，不落盘）
+    pub(super) path: Option<PathBuf>,
+    /// 设置文档（schema 校验 + 原子写的唯一入口）
+    pub(super) store: Option<SettingStore>,
+    /// 上次读/写之后的文件 `mtime`（热切探测用）
+    pub(super) last_mtime: Option<SystemTime>,
+}
+
+impl SettingsBridge {
+    /// 按三模式数据根打开真实配置文件（启动时调用一次）。
+    #[must_use]
+    pub fn open() -> Self {
+        match resolve_config_path() {
+            Some(path) => Self::with_path(path),
+            None => Self::memory_only(),
+        }
+    }
+
+    /// 指定路径打开（测试与特殊数据根用）。
+    #[must_use]
+    pub fn with_path(path: impl Into<PathBuf>) -> Self {
+        let path = path.into();
+        let store = SettingStore::load(&path, launcher_schema());
+        let last_mtime = mtime(&path);
+        Self {
+            path: Some(path),
+            store: Some(store),
+            last_mtime,
+        }
+    }
+
+    /// 不落盘（数据根解析失败 / 单测）。
+    #[must_use]
+    pub fn memory_only() -> Self {
+        Self {
+            path: None,
+            store: None,
+            last_mtime: None,
+        }
+    }
+
+    /// 配置文件路径（诊断/日志用）。
+    #[must_use]
+    pub fn path(&self) -> Option<&Path> {
+        self.path.as_deref()
+    }
+
+    /// 当前生效的外观配置与主题模式。
+    #[must_use]
+    pub fn load(&self) -> (AppearancePrefs, ThemeMode) {
+        let Some(store) = &self.store else {
+            return (AppearancePrefs::factory(), ThemeMode::Auto);
+        };
+        let appearance = Appearance::from_store(store);
+        let theme = ThemeMode::from_key_value(&appearance.theme_mode);
+        (
+            AppearancePrefs {
+                bg_image_enabled: appearance.bg_image_enabled,
+                bg_image: appearance.bg_image,
+                bg_fill: appearance.bg_fill,
+                bg_dim: appearance.bg_dim as f32,
+                panel_alpha: appearance.panel_alpha as f32,
+                glass: appearance.glass,
+                accent_color: appearance.accent_color,
+            },
+            theme,
+        )
+    }
+
+    /// 外观**下层**的只读快照（D36·D37·D38 · M116）：整窗 α / 标题栏三态 / 配色来源档 /
+    /// 窗口圆角策略（`AppearanceBase` 的**四个**字段）。
+    ///
+    /// 为什么不并进 [`SettingsBridge::load`] 的返回值：那个结构体（`AppearancePrefs`）是
+    /// **UI 写入用**的（每个字段都会被 `persist` 回写），而这**四个**键**只读不写**——
+    /// 落盘走 core 的 `Appearance::write`。并进去会让每个 `AppearancePrefs` 构造点都要补字段，
+    /// 还会让「这四项只读」这件事在类型上消失。
+    ///
+    /// UI 侧（`crates/app-iced`）拿它读启动值：`app-iced` 不直接依赖 `unlucky-core`，
+    /// 所以「把 core 的 `SettingDocument` 翻译成只读快照」这一步必须留在本 crate。
+    #[must_use]
+    pub fn load_base(&self) -> AppearanceBase {
+        match &self.store {
+            Some(store) => AppearanceBase::from_document(store.doc()),
+            None => AppearanceBase::factory(),
+        }
+    }
+
+    /// 落盘（只写出现过的键；失败静默——配置写不进去不该把 UI 卡住，诊断走日志）。
+    pub fn persist(&mut self, appearance: &AppearancePrefs, theme: ThemeMode) {
+        let Some(store) = self.store.as_mut() else {
+            return;
+        };
+        let mut snapshot = Appearance::from_store(store);
+        snapshot.theme_mode = theme.as_str().to_owned();
+        snapshot.bg_image_enabled = appearance.bg_image_enabled;
+        snapshot.bg_image = appearance.bg_image.clone();
+        snapshot.bg_fill = appearance.bg_fill;
+        snapshot.bg_dim = f64::from(appearance.bg_dim);
+        snapshot.panel_alpha = f64::from(appearance.panel_alpha);
+        snapshot.glass = appearance.glass;
+        snapshot.accent_color = appearance.accent_color.clone();
+        if snapshot.write(store).is_err() {
+            return;
+        }
+        let _ = store.save();
+        if let Some(path) = self.path() {
+            self.last_mtime = mtime(path);
+        }
+    }
+
+    /// 文件被外部（AI / `ull config set`）改过就重读；返回新的生效值。
+    ///
+    /// `mtime` 采样不到（某些文件系统精度/权限）时返回 `None`，退化为「只在启动时读一次」。
+    pub fn reload_if_changed(&mut self) -> Option<(AppearancePrefs, ThemeMode)> {
+        let path = self.path.clone()?;
+        let current = mtime(&path);
+        if current.is_none() || current == self.last_mtime {
+            return None;
+        }
+        self.last_mtime = current;
+        let store = self.store.as_mut()?;
+        store.reload();
+        Some(self.load())
+    }
+}
+
+/// 数据根解析 → `config/launcher.json`。
+///
+/// 与 CLI 同一套语义：先读便携目录那份 `launcher.json` 的 `core.*`（数据根决定键），
+/// 再交 `Resolver` 解析（含 `redirect.json` 跟随）。任何一步失败都退回内存态。
+fn resolve_config_path() -> Option<PathBuf> {
+    let exe_dir = std::env::current_exe()
+        .ok()
+        .and_then(|path| path.parent().map(Path::to_path_buf));
+    let exe_dir = exe_dir?;
+    let request = request_from_portable(&exe_dir);
+    let resolver = Resolver::new(Platform::current(), Some(exe_dir.clone()));
+    match resolver.resolve_default(&request) {
+        Ok(resolved) => Some(resolved.layout().launcher_config()),
+        // 连 exe 目录都解析不了（极端情况）：仍旧用便携落点，至少设置能存下来
+        Err(_) => Some(LauncherLayout::new(exe_dir.join(".ULL")).launcher_config()),
+    }
+}
+
+/// 便携目录那份 `launcher.json` → 三模式请求（只读 `core.*` 四个键）。
+fn request_from_portable(exe_dir: &Path) -> DataDirRequest {
+    let mut request = DataDirRequest::default();
+    let path = portable_config_path(exe_dir);
+    if !path.is_file() {
+        return request;
+    }
+    let store = SettingStore::load(&path, launcher_schema());
+    let text = |key: &str| store.doc().effective_str(key).map(str::to_string);
+    if let Some(mode) = text(DATA_ROOT_KEYS[0]).as_deref().and_then(DataMode::parse) {
+        request.mode = mode;
+    }
+    if let Some(root) = text(DATA_ROOT_KEYS[1]) {
+        request.custom_root = Some(PathBuf::from(root));
+    }
+    if let Some(home) = text(DATA_ROOT_KEYS[2]) {
+        request.launcher_home = Some(PathBuf::from(home));
+    }
+    if let Some(home) = text(DATA_ROOT_KEYS[3]) {
+        request.game_home = Some(PathBuf::from(home));
+    }
+    request
+}
+
+/// `<exe 目录>/.ULL/config/launcher.json`。
+fn portable_config_path(exe_dir: &Path) -> PathBuf {
+    LauncherLayout::new(exe_dir.join(".ULL")).launcher_config()
+}
+
+fn mtime(path: &Path) -> Option<SystemTime> {
+    std::fs::metadata(path).ok()?.modified().ok()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::prefs::PaletteSource;
+    use unlucky_core::setting::appearance::BgFill;
+
+    fn temp_config(label: &str) -> PathBuf {
+        let dir = std::env::temp_dir().join(format!(
+            "ull-bridge-{label}-{}-{}",
+            std::process::id(),
+            line!()
+        ));
+        std::fs::create_dir_all(dir.join("config")).expect("临时目录");
+        let path = dir.join("config/launcher.json");
+        let _ = std::fs::remove_file(&path);
+        path
+    }
+
+    #[test]
+    fn factory_defaults_when_file_missing() {
+        let path = temp_config("factory");
+        let bridge = SettingsBridge::with_path(&path);
+        let (appearance, theme) = bridge.load();
+        assert_eq!(appearance, AppearancePrefs::factory());
+        assert_eq!(theme, ThemeMode::Auto);
+        assert!(!path.exists(), "只读不写：缺文件不该被创建");
+        std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap()).ok();
+    }
+
+    #[test]
+    fn persist_then_reload_round_trips() {
+        let path = temp_config("roundtrip");
+        let mut bridge = SettingsBridge::with_path(&path);
+        let mut appearance = AppearancePrefs::factory();
+        appearance.bg_image_enabled = true;
+        appearance.bg_image = "D:/wall/p.png".to_owned();
+        appearance.bg_fill = BgFill::Contain;
+        appearance.bg_dim = 0.5;
+        appearance.panel_alpha = 0.8;
+        appearance.glass = true;
+        assert!(appearance.set_accent("#0f6cbd"));
+        bridge.persist(&appearance, ThemeMode::Dark);
+
+        let reloaded = SettingsBridge::with_path(&path);
+        let (value, theme) = reloaded.load();
+        assert_eq!(value, appearance);
+        assert_eq!(theme, ThemeMode::Dark);
+        std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap()).ok();
+    }
+
+    #[test]
+    fn external_edit_is_picked_up_by_reload() {
+        let path = temp_config("hotreload");
+        let mut bridge = SettingsBridge::with_path(&path);
+        // 先落一份（建立 mtime 基线）
+        bridge.persist(&AppearancePrefs::factory(), ThemeMode::Light);
+        assert!(bridge.reload_if_changed().is_none(), "自己写完不该报告变更");
+
+        // 模拟外部写入（AI / `ull config set`）：改主题 + 打开背景图
+        let mut external = SettingsBridge::with_path(&path);
+        let mut appearance = AppearancePrefs::factory();
+        appearance.bg_image_enabled = true;
+        appearance.bg_image = "D:/wall/x.png".to_owned();
+        external.persist(&appearance, ThemeMode::Dark);
+
+        // mtime 精度：有的文件系统 1s 粒度，这里显式等到时间戳变化
+        for _ in 0..50 {
+            if let Some((value, theme)) = bridge.reload_if_changed() {
+                assert_eq!(theme, ThemeMode::Dark);
+                assert!(value.bg_image_enabled);
+                assert_eq!(value.bg_image, "D:/wall/x.png");
+                std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap()).ok();
+                return;
+            }
+            std::thread::sleep(std::time::Duration::from_millis(20));
+        }
+        panic!("外部修改没有被 mtime 热切捕获");
+    }
+
+    #[test]
+    fn accent_preset_and_validation() {
+        let mut appearance = AppearancePrefs::factory();
+        assert_eq!(appearance.accent_color, "");
+        assert!(appearance.set_accent_preset(1));
+        assert_eq!(appearance.accent_color, "#0F6CBD");
+        assert!(!appearance.set_accent("not-a-color"), "非法输入不改现状");
+        assert_eq!(appearance.accent_color, "#0F6CBD");
+        assert!(appearance.set_accent(""), "空串恢复出厂");
+        assert_eq!(appearance.accent_color, "");
+        assert!(!appearance.set_accent_preset(99));
+    }
+
+    #[test]
+    fn bg_active_needs_both_switch_and_path() {
+        let mut appearance = AppearancePrefs::factory();
+        appearance.bg_image = "D:/wall/p.png".to_owned();
+        assert!(!appearance.bg_active(), "开关没开不算生效");
+        appearance.bg_image_enabled = true;
+        assert!(appearance.bg_active());
+        appearance.bg_image.clear();
+        assert!(!appearance.bg_active(), "路径空也不算生效");
+    }
+
+    /// `load_base()` 是「重启后读回整窗 α / 配色来源 / 窗口圆角」的唯一通道（M93 · M116）。
+    ///
+    /// 抓得住：①文件里写着 `window_opacity=0.6` / `palette_source=wallpaper` 时能被**新开的**
+    /// bridge 读到（= 重启语义）；②缺键时回出厂（1.0 / preset），而不是 `0.0` 或随机档。
+    /// 抓不住：UI 侧是否真的用它来下发窗口 α（那由 `app-iced` 的日志与单测证明）。
+    #[test]
+    fn load_base_reads_the_four_read_only_keys_and_defaults_when_missing() {
+        let path = temp_config("base");
+        // 文件由「外部写者」（CLI / AI / 设置页的 SetSetting）产生，这里直接落 JSON。
+        std::fs::write(
+            &path,
+            r#"{"appearance":{"theme_mode":"dark","window_opacity":0.6,"palette_source":"wallpaper","panel_alpha":0.5}}"#,
+        )
+        .expect("写配置文件");
+
+        let bridge = SettingsBridge::with_path(&path);
+        let base = bridge.load_base();
+        assert_eq!(base.window_opacity, 0.6, "重启后读回整窗 α");
+        assert_eq!(base.palette_source, PaletteSource::Wallpaper);
+        assert!(base.is_transparent());
+
+        // 缺键 → 出厂值（与 `AppearanceBase::factory()` 逐字段相等）。
+        let empty = path.with_file_name("launcher-empty.json");
+        std::fs::write(&empty, "{}").expect("写空配置");
+        let factory = SettingsBridge::with_path(&empty).load_base();
+        assert_eq!(factory, AppearanceBase::factory());
+        assert_eq!(factory.window_opacity, 1.0);
+        assert_eq!(factory.palette_source, PaletteSource::Preset);
+
+        // 数据根解析不出来的内存态桥也要给得出出厂值（不 panic、不返回 0）。
+        assert_eq!(
+            SettingsBridge::memory_only().load_base(),
+            AppearanceBase::factory()
+        );
+
+        std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap()).ok();
+    }
+}
diff --git a/crates/presenter/src/settings_bridge_lang.rs b/crates/presenter/src/settings_bridge_lang.rs
new file mode 100644
index 0000000..b433302
--- /dev/null
+++ b/crates/presenter/src/settings_bridge_lang.rs
@@ -0,0 +1,150 @@
+//! 界面语言这一个键的读写（M106）：`ui.language` 的**显式值**。
+//!
+//! ## 为什么单独一个文件
+//!
+//! `settings_bridge.rs` 是外观 / 主题 / 数据根那一摊的落点，已经贴着 400 行硬线；语言的读写只有
+//! 两个方法 + 一个「删键」辅助，独立出来之后两边都还能长。`impl SettingsBridge` 写在别的模块是
+//! Rust 允许的（同一 crate 的固有实现），只需要主文件把三个字段放成 `pub(super)`。
+//!
+//! ## 两条判据（都跟 schema 的默认值有关）
+//!
+//! 1. **读的是显式值**，不是 `effective_str`：`ui.language` 的 schema 默认值是 `zh_cn`，用它会把
+//!    「没配过」读成「用户手选中文」——英文机器一启动就被强行切成中文（D28 违约）。
+//! 2. **「跟随系统」= 删掉这个键**，不是写哨兵值：允许值只有 `zh_cn` / `en_us`（枚举校验会拒别的），
+//!    而「跟随系统」的语义本来就是「没有显式选择」。
+//!
+//! 这两条都在 `.tower/comms/findings/` 里登了记（建议把 schema 默认值改成 `null` 或加
+//! `follow_system` 取值，那时本文件的删键路径可以简化成一次 `store.set`）。
+
+use unlucky_core::setting::document::SettingDocument;
+use unlucky_core::setting::keys::launcher_schema;
+use unlucky_core::setting::store::SettingStore;
+
+use crate::settings_bridge::SettingsBridge;
+
+/// 界面语言键（M106）：`zh_cn` / `en_us`（允许值见 `core::setting::keys::LANGUAGES`）。
+///
+/// **不写这个键 = 跟随系统**，所以它没有「system」这种取值，见 [`SettingsBridge::persist_ui_language`]。
+const UI_LANGUAGE: &str = "ui.language";
+
+impl SettingsBridge {
+    /// 配置里 `ui.language` 的**显式值**（M106）：`None` = 没写过 = **跟随系统**。
+    ///
+    /// 不用 `effective_str`：那会把 schema 默认值（`zh_cn`）当成「用户手选中文」，于是**没配过**
+    /// 的英文机器会一启动就被强行切成中文（D28 的「纯英文环境不用管」直接违约）。
+    #[must_use]
+    pub fn load_ui_language(&self) -> Option<String> {
+        let store = self.store.as_ref()?;
+        store
+            .doc()
+            .get(UI_LANGUAGE)
+            .and_then(serde_json::Value::as_str)
+            .map(str::to_owned)
+    }
+
+    /// 写 `ui.language`：`Some("zh_cn")` / `Some("en_us")` 手选，`None` = **跟随系统 = 删键**。
+    ///
+    /// 返回是否真的落盘（只读 / 内存态时是 `false`，配置写不进去不该把 UI 卡住）。
+    pub fn persist_ui_language(&mut self, value: Option<&str>) -> bool {
+        let Some(store) = self.store.as_mut() else {
+            return false;
+        };
+        let changed = match value {
+            Some(language) => store
+                .set(UI_LANGUAGE, serde_json::Value::String(language.to_owned()))
+                .is_ok(),
+            None => store.doc().get(UI_LANGUAGE).is_some() && remove_ui_language(store),
+        };
+        if !changed {
+            return false;
+        }
+        let saved = store.save().is_ok();
+        if let Some(path) = self.path() {
+            self.last_mtime = std::fs::metadata(path)
+                .ok()
+                .and_then(|meta| meta.modified().ok());
+        }
+        saved
+    }
+}
+
+/// 把 `ui.language` 从文档里摘掉：`SettingDocument` 没有 remove API，而落盘写的是**全量视图**，
+/// 所以把全量视图里的那个键去掉再 load 回一份文档就等价于删键（用户手写的未知键也原样带回）。
+fn remove_ui_language(store: &mut SettingStore) -> bool {
+    let mut value = store.doc().to_value();
+    let removed = value
+        .get_mut("ui")
+        .and_then(serde_json::Value::as_object_mut)
+        .and_then(|ui| ui.remove("language"))
+        .is_some();
+    if !removed {
+        return false;
+    }
+
+    let (mut doc, _problems) = SettingDocument::load(&launcher_schema(), &value);
+    // 落盘的闸门是 `is_dirty()`（`write_document` 写全量视图，不是脏字段补丁）。
+    doc.mark_all_dirty();
+    *store.doc_mut() = doc;
+    true
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::path::PathBuf;
+
+    fn temp_config(label: &str) -> PathBuf {
+        let dir = std::env::temp_dir().join(format!(
+            "ull-bridge-lang-{label}-{}-{}",
+            std::process::id(),
+            line!()
+        ));
+        std::fs::create_dir_all(dir.join("config")).expect("临时目录");
+        let path = dir.join("config/launcher.json");
+        let _ = std::fs::remove_file(&path);
+        path
+    }
+
+    /// 抓得住：①把 `effective_str` 当读法（英文机器没配过 → 被默认值 `zh_cn` 强行切成中文）；
+    /// ②「跟随系统」写成哨兵值（枚举校验会拒、下次启动会撒谎）；③删键时连别的键一起删。
+    /// 抓不住：UI 是否真的按这个值选目录（那是 `app-iced/src/ui/lang.rs` 的往返测试）。
+    #[test]
+    fn ui_language_round_trips_and_follow_system_removes_only_that_key() {
+        let path = temp_config("roundtrip");
+        std::fs::write(
+            &path,
+            r#"{"appearance":{"theme_mode":"dark"},"custom":{"keep":true}}"#,
+        )
+        .expect("写配置");
+
+        // 没写过 = 跟随系统（不是默认值 zh_cn）
+        let bridge = SettingsBridge::with_path(&path);
+        assert_eq!(bridge.load_ui_language(), None);
+
+        // 手选落盘 → 新开的 bridge（= 重启）读得回
+        let mut bridge = SettingsBridge::with_path(&path);
+        assert!(bridge.persist_ui_language(Some("zh_cn")));
+        assert_eq!(
+            SettingsBridge::with_path(&path)
+                .load_ui_language()
+                .as_deref(),
+            Some("zh_cn")
+        );
+
+        // 切回跟随系统 = 删键，且别的键一个不动
+        let mut bridge = SettingsBridge::with_path(&path);
+        assert!(bridge.persist_ui_language(None));
+        assert_eq!(SettingsBridge::with_path(&path).load_ui_language(), None);
+        let text = std::fs::read_to_string(&path).expect("读配置");
+        assert!(text.contains("theme_mode"), "外观键被删了：{text}");
+        assert!(text.contains("custom"), "用户手写的未知键被删了：{text}");
+
+        // 幂等：没有键可删 = 没有落盘
+        let mut bridge = SettingsBridge::with_path(&path);
+        assert!(!bridge.persist_ui_language(None));
+
+        // 内存态桥不许 panic
+        assert_eq!(SettingsBridge::memory_only().load_ui_language(), None);
+        std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap()).ok();
+    }
+}
diff --git a/crates/presenter/src/state.rs b/crates/presenter/src/state.rs
new file mode 100644
index 0000000..a3b6518
--- /dev/null
+++ b/crates/presenter/src/state.rs
@@ -0,0 +1,387 @@
+//! UI 状态与 reducer：UI 框架只负责渲染，所有状态变更都汇聚到 [`AppState::apply`]。
+//!
+//! 数据流向：mock/host 后端 → [`crate::dto::AppEvent`] 队列 → `apply` → 状态字段 → UI 属性。
+//! 偏好项在 [`crate::prefs`] 里登记了持久化键名，core::setting 的 schema 落地后按这些键读写。
+
+use crate::agent::AgentRail;
+use crate::dialogs::DialogQueue;
+use crate::dto::{
+    // 主线（M105 的 `LoaderKind` / M113 的 `PackState`）与 M114 的 `AuthlibLoginView` 并集。
+    AccountView,
+    AgentEvent,
+    AppEvent,
+    AuthlibLoginView,
+    CoreEvent,
+    DeviceLoginView,
+    DiagnosisReport,
+    InstallProgressView,
+    InstanceRuntime,
+    InstanceSummary,
+    JavaPageView,
+    LoaderKind,
+    LogLine,
+    LogSession,
+    NoticeView,
+    PackState,
+    Progress,
+    SettingGroupView,
+    VersionSummary,
+};
+use crate::prefs::UiPrefs;
+// 内容库的视图态与其 DTO 放一起（`dto/content.rs`），路径 `state::ContentState` 不变。
+pub use crate::dto::ContentState;
+use crate::router::{AiPanelMode, Route, Router};
+use crate::toast::{ToastCenter, ToastKind};
+use crate::wizard::WizardState;
+
+// 账户/登录状态（倒计时、上屏前二次脱敏）拆在 `state/accounts.rs`，守 400 行硬线。
+//
+// `AiSession` 不再存在：M104 把它换成了 `crate::agent::AgentRail`（agent 栏的视图模型），
+// 所以这里没有 `mod ai;` / `pub use ai::AiSession;`——M114 r1 曾把旧结构搬到 `state/ai.rs`，
+// 该文件已随 rebase 删除，**以 main 的 agent 契约为准**。
+mod accounts;
+mod live;
+mod tiles;
+
+pub use live::MAX_LIVE_LINES;
+pub use tiles::{grid_positions, TileCell};
+
+/// 一份加载器版本清单查询的结果（`Ok` = 最新在前；`Err` = 人读原因）。
+pub type LoaderVersions = Result<Vec<String>, String>;
+
+/// 应用全局状态。
+#[derive(Debug)]
+pub struct AppState {
+    /// UI 偏好（记忆项）
+    pub prefs: UiPrefs,
+    /// 导航栈
+    pub router: Router,
+    /// 实例列表快照
+    pub instances: Vec<InstanceSummary>,
+    /// 当前分类的版本列表
+    pub versions: Vec<VersionSummary>,
+    /// 日志会话列表
+    pub log_sessions: Vec<LogSession>,
+    /// 当前会话日志行
+    pub log_lines: Vec<LogLine>,
+    /// 最近一次诊断结论
+    pub diagnosis: Option<DiagnosisReport>,
+    /// 选中的日志会话
+    pub selected_session: Option<String>,
+    /// AI 会话状态（右侧栏与独立页共享同一份，切换不丢）
+    pub ai: AgentRail,
+    /// 对话框队列（一次一条）
+    pub dialogs: DialogQueue,
+    /// Toast 中心
+    pub toasts: ToastCenter,
+    /// 实例页搜索词
+    pub instance_query: String,
+    /// 下载页「仅已装」过滤
+    pub installed_only: bool,
+    /// 下载页版本号筛选词
+    pub download_query: String,
+    /// 账户列表（三轨统一视图；凭据不在其中）
+    pub accounts: Vec<AccountView>,
+    /// 微软登录状态
+    pub device_login: DeviceLoginView,
+    /// 第三方轨（authlib-injector）登录/校验状态
+    pub authlib_login: AuthlibLoginView,
+    /// 设备码等待态的开始时刻（倒计时；`None` = 没有在等）
+    pub device_login_started: Option<std::time::Instant>,
+    /// 账户页横幅（一次性操作结果；页面渲染后由用户关掉）
+    pub account_notice: Option<crate::dto::AccountNotice>,
+    /// Java 页快照（发行版 / 回退链 / 运行时）
+    pub java: JavaPageView,
+    /// 安装进度（None = 没有安装任务）
+    pub install: Option<InstallProgressView>,
+    /// 用户取消安装的**次数**（M105）：每次 `CoreEvent::InstallCancelled` +1。
+    ///
+    /// 只是信号，不带文案：app 层比对前后值决定「要不要弹一条 i18n Toast」，
+    /// 于是取消提示和页面用同一种语言（复审 P2-2）。
+    pub install_cancelled: u64,
+    /// 加载器版本清单（下载页「安装选项」的下拉；M105）
+    ///
+    /// 两段键：外层是加载器的**稳定 id**（`LoaderKind::as_str`，`LoaderKind` 没派生 `Hash`，
+    /// 而 `as_str` 本来就是它在 CLI/GUI 两边的身份），内层是原版版本。
+    /// **原版版本进键**，所以切到另一个 MC 版本时拿到的是另一条缓存，
+    /// 不会把 A 版本的 Fabric 列表挂到 B 版本下面（M105 复审的硬要求）。
+    /// 值是 `Result`：「取不到」与「官方没有版本」是两件事，前者要在页面上说清原因
+    /// （并禁掉确认），不许显示成空列表。
+    pub loader_versions:
+        std::collections::HashMap<&'static str, std::collections::HashMap<String, LoaderVersions>>,
+    /// 设置分组（设置页右栏）
+    pub settings_groups: Vec<SettingGroupView>,
+    /// 当前选中的设置分组（download / java / data / ai / mcp）
+    pub settings_tab: String,
+    /// 横幅通知
+    pub notices: Vec<NoticeView>,
+    /// 新建实例向导
+    pub wizard: WizardState,
+    /// 正在实时尾随的会话
+    pub live_session: Option<String>,
+    /// 内容库（M109）：条件 / 结果 / 请求态
+    pub content: ContentState,
+    /// 整合包导入/导出：进度 / 结果 / 探测诊断 / 导出预检（M113）
+    pub pack: PackState,
+}
+
+impl Default for AppState {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl AppState {
+    /// 空状态（数据由后端事件填充，P0 是 mock）。
+    pub fn new() -> Self {
+        Self {
+            prefs: UiPrefs::default(),
+            router: Router::new(),
+            instances: Vec::new(),
+            versions: Vec::new(),
+            log_sessions: Vec::new(),
+            log_lines: Vec::new(),
+            diagnosis: None,
+            selected_session: None,
+            ai: AgentRail::new(),
+            dialogs: DialogQueue::new(),
+            toasts: ToastCenter::new(),
+            instance_query: String::new(),
+            installed_only: false,
+            download_query: String::new(),
+            accounts: Vec::new(),
+            device_login: DeviceLoginView::new(),
+            authlib_login: AuthlibLoginView::new(),
+            device_login_started: None,
+            account_notice: None,
+            java: JavaPageView::new(),
+            install: None,
+            install_cancelled: 0,
+            loader_versions: std::collections::HashMap::new(),
+            settings_groups: Vec::new(),
+            settings_tab: "download".to_string(),
+            notices: Vec::new(),
+            wizard: WizardState::new(),
+            live_session: None,
+            content: ContentState::default(),
+            pack: PackState::default(),
+        }
+    }
+
+    /// 某 (加载器, 原版版本) 的加载器版本清单。
+    ///
+    /// `None` = 还没查过（页面据此派一次 `AppCommand::ListLoaderVersions` 并显示「正在获取…」）；
+    /// `Some(Err(..))` = 查过但拿不到（页面显示具名原因并**禁掉确认**）。
+    #[must_use]
+    pub fn loader_versions_for(
+        &self,
+        kind: LoaderKind,
+        mc_version: &str,
+    ) -> Option<&LoaderVersions> {
+        self.loader_versions.get(kind.as_str())?.get(mc_version)
+    }
+
+    /// 当前页面。
+    pub fn route(&self) -> &Route {
+        self.router.route()
+    }
+
+    /// 跳转（一级页替换、子页面压栈；去 AI 独立页时自动展开 AI 栏偏好）。
+    pub fn navigate(&mut self, route: Route) {
+        if route == Route::Agent {
+            self.prefs.ai_collapsed = false;
+            // 用户正在看 AI 页：攒下的未读立刻算已读（红点不该在眼前亮着）
+            self.ai.mark_read();
+        }
+        self.router.navigate(route);
+    }
+
+    /// 回退一层。
+    pub fn back(&mut self) -> bool {
+        self.router.back()
+    }
+
+    /// AI 栏当前形态（跟着路由走）。
+    pub fn ai_mode(&self) -> AiPanelMode {
+        self.router.ai_mode()
+    }
+
+    /// 应用一条事件（唯一状态变更入口）。
+    pub fn apply(&mut self, event: AppEvent) {
+        match event {
+            AppEvent::Core(core) => self.apply_core(core),
+            AppEvent::Agent(agent) => self.apply_agent(agent),
+            AppEvent::DialogRequested(request) => {
+                self.dialogs.push_request(request);
+            }
+            AppEvent::DialogClosed(id) => {
+                self.dialogs.close(id);
+            }
+            AppEvent::Toast(toast) => {
+                self.toasts.push_request(toast);
+            }
+        }
+    }
+
+    /// core 事件。
+    pub fn apply_core(&mut self, event: CoreEvent) {
+        match event {
+            CoreEvent::InstancesChanged(instances) => self.instances = instances,
+            CoreEvent::InstanceRuntimeChanged { id, runtime } => {
+                if let Some(instance) = self.instances.iter_mut().find(|item| item.id == id) {
+                    instance.runtime = runtime;
+                }
+            }
+            CoreEvent::VersionListChanged(versions) => self.versions = versions,
+            CoreEvent::LogSessionsChanged(sessions) => self.log_sessions = sessions,
+            CoreEvent::LogLinesChanged(lines) => {
+                self.log_lines = lines;
+                self.live_session = None;
+            }
+            CoreEvent::LogAppended(batch) => self.append_live_lines(&batch),
+            CoreEvent::LaunchFinished(finished) => {
+                self.live_session = None;
+                self.selected_session = Some(finished.session.clone());
+                let kind = if finished.outcome == crate::dto::LogOutcome::Ok {
+                    ToastKind::Success
+                } else {
+                    ToastKind::Error
+                };
+                self.toasts.push(kind, finished.summary);
+            }
+            CoreEvent::DiagnosisReady(report) => self.diagnosis = Some(report),
+            CoreEvent::AccountsChanged(accounts) => self.accounts = accounts,
+            CoreEvent::DeviceLoginChanged(view) => self.apply_device_login(view),
+            CoreEvent::AuthlibLoginChanged(view) => self.apply_authlib_login(view),
+            CoreEvent::AccountNoticeChanged(notice) => self.account_notice = notice,
+            CoreEvent::JavaChanged(page) => self.java = page,
+            CoreEvent::InstallProgress(progress) => match progress {
+                Some(progress) => {
+                    let terminal = progress.stage.is_terminal();
+                    self.install = Some(progress);
+                    if terminal {
+                        self.wizard.open = false;
+                        self.wizard.submitting = false;
+                    }
+                }
+                None => self.install = None,
+            },
+            CoreEvent::InstallCancelled => {
+                self.install_cancelled = self.install_cancelled.saturating_add(1);
+            }
+            CoreEvent::SettingsChanged(groups) => self.settings_groups = groups,
+            CoreEvent::LoaderVersions {
+                kind,
+                mc_version,
+                result,
+            } => {
+                self.loader_versions
+                    .entry(kind.as_str())
+                    .or_default()
+                    .insert(mc_version, result);
+            }
+            CoreEvent::NoticesChanged(notices) => self.notices = notices,
+            // M113: import/export
+            CoreEvent::Pack(event) => self.pack.apply(*event),
+            CoreEvent::ContentResults(results) => self.apply_content(*results),
+            CoreEvent::ContentFailed(reason) => {
+                self.content.pending = false;
+                self.content.failed = Some(reason);
+            }
+        }
+    }
+
+    /// agent 事件 → AI 栏视图模型（投影规则见 [`crate::agent::rail`]）。
+    ///
+    /// 未读规则：栏不可见时，助手侧新内容（助手/工具消息、错误、待确认请求）逐条累加 `unread`；
+    /// 用户自己说的话与纯增量不算。栏可见时到达的内容直接算已读（红点不该在眼前亮着）。
+    pub fn apply_agent(&mut self, event: AgentEvent) {
+        let visible = self.agent_rail_visible();
+        let fresh = self.ai.ingest(&event);
+        if fresh {
+            if visible {
+                self.ai.mark_read();
+            } else {
+                self.ai.unread = self.ai.unread.saturating_add(1);
+            }
+        }
+    }
+
+    /// AI 栏此刻是否「在用户眼前」。
+    ///
+    /// 独立页形态（栈顶是 `Route::Agent`）必然可见；停靠形态下只有收成 icon 轨才算离开——
+    /// 右侧常驻栏在任何一级页面都挂着，用户扫一眼就能看到。
+    #[must_use]
+    pub fn agent_rail_visible(&self) -> bool {
+        self.ai_mode() == AiPanelMode::Page || !self.prefs.ai_collapsed
+    }
+
+    /// 按搜索词过滤后的磁贴网格（顺序稳定 = 实例列表顺序）。
+    pub fn tiles(&self) -> Vec<TileCell<'_>> {
+        let query = self.instance_query.trim().to_lowercase();
+        let filtered: Vec<&InstanceSummary> = self
+            .instances
+            .iter()
+            .filter(|instance| query.is_empty() || instance.name.to_lowercase().contains(&query))
+            .collect();
+        let positions = grid_positions(filtered.len(), self.prefs.tile_size.columns());
+        filtered
+            .into_iter()
+            .zip(positions)
+            .map(|(instance, (row, col))| TileCell { instance, row, col })
+            .collect()
+    }
+
+    /// 运行中的实例（实例页顶部迷你状态条）。
+    pub fn running(&self) -> Vec<&InstanceSummary> {
+        self.instances
+            .iter()
+            .filter(|instance| {
+                matches!(
+                    instance.runtime,
+                    InstanceRuntime::Running { .. } | InstanceRuntime::Busy { .. }
+                )
+            })
+            .collect()
+    }
+
+    /// 覆盖某实例的启动进度（mock / 真实后端共用同一入口）。
+    pub fn set_progress(&mut self, id: &str, progress: Progress) {
+        if let Some(instance) = self.instances.iter_mut().find(|item| item.id == id) {
+            if let InstanceRuntime::Busy {
+                progress: current, ..
+            } = &mut instance.runtime
+            {
+                *current = progress;
+            }
+        }
+    }
+
+    /// 折叠/展开导航栏。
+    pub fn toggle_nav(&mut self) {
+        self.prefs.nav_collapsed = !self.prefs.nav_collapsed;
+    }
+
+    /// 折叠/展开 AI 栏；若正处在独立页形态则先收回侧栏。
+    pub fn toggle_ai(&mut self) {
+        if self.route() == &Route::Agent {
+            self.router.back();
+            self.prefs.ai_collapsed = false;
+            return;
+        }
+        self.prefs.ai_collapsed = !self.prefs.ai_collapsed;
+        if !self.prefs.ai_collapsed {
+            // 展开常驻栏 = 用户在看它
+            self.ai.mark_read();
+        }
+    }
+}
+
+#[cfg(test)]
+#[path = "state_tests.rs"]
+mod tests;
+
+mod content;
+
+#[cfg(test)]
+mod content_tests;
diff --git a/crates/presenter/src/state/accounts.rs b/crates/presenter/src/state/accounts.rs
new file mode 100644
index 0000000..df78016
--- /dev/null
+++ b/crates/presenter/src/state/accounts.rs
@@ -0,0 +1,193 @@
+//! 账户/登录状态：事件落地（含**上屏前再脱敏**）、设备码倒计时、当前账户查询。
+//!
+//! 从 `state.rs` 拆出来守 400 行硬线；`AppState` 的字段仍在那个文件里，
+//! 这里只加它的 `impl`（同一个 crate 的固有 impl 可以拆在多个文件）。
+
+use std::time::Instant;
+
+use crate::dto::{AccountView, AuthlibLoginView, DeviceLoginPhase, DeviceLoginView, REDACTED};
+
+use super::AppState;
+
+impl AppState {
+    /// 微软登录状态落地。
+    ///
+    /// **凭据红线（M114）**：这里对 `message` 再做一次形状脱敏。DTO 的构造器已经脱过一遍，
+    /// 但状态层是**所有**事件都要过的唯一闸口——将来谁新加一个构造器忘了脱敏，也不会把
+    /// 服务端回显的 token 画到面板上。脱敏是幂等的，重复做没有代价。
+    pub fn apply_device_login(&mut self, mut view: DeviceLoginView) {
+        view.message = crate::dto::redact(&view.message);
+        view.account_name = crate::dto::redact(&view.account_name);
+        // 这里**不发 toast**：presenter 是共享宿主层，写什么语言都不对（复审 r1 P1-1）。
+        // 成败反馈由页面自己画（登录面板的 Succeeded/Failed 态 + 账户页横幅），文案走 i18n。
+        match view.phase {
+            DeviceLoginPhase::Succeeded => {
+                self.device_login_started = None;
+            }
+            DeviceLoginPhase::Failed => {
+                self.device_login_started = None;
+            }
+            DeviceLoginPhase::Waiting => {
+                // 每次进入等待态都重记起点：换流/重试之后倒计时必须从头算
+                if self.device_login.phase != DeviceLoginPhase::Waiting
+                    || self.device_login.user_code != view.user_code
+                {
+                    self.device_login_started = Some(Instant::now());
+                }
+            }
+            DeviceLoginPhase::Idle | DeviceLoginPhase::Requesting => {
+                self.device_login_started = None;
+            }
+        }
+        self.device_login = view;
+    }
+
+    /// 第三方轨登录状态落地（同样在状态层再脱敏一遍）。
+    pub fn apply_authlib_login(&mut self, mut view: AuthlibLoginView) {
+        view.message = crate::dto::redact(&view.message);
+        view.server_name = crate::dto::redact(&view.server_name);
+        // 同 `apply_device_login`：不发 toast，成败由页面按 i18n 画。
+        self.authlib_login = view;
+    }
+
+    /// 设备码/授权码还剩几秒（`None` = 没有在等 / 不知道有效期）。
+    ///
+    /// 纯计算 + 一个起点，UI 侧每秒重问一次就能画出倒计时——这也让「过期」成为**可观测**的
+    /// 状态（任务要求：设备码不得只转圈，过期要显示「已过期，重试」）。
+    pub fn device_code_remaining(&self) -> Option<u64> {
+        self.device_code_remaining_at(Instant::now())
+    }
+
+    /// [`Self::device_code_remaining`] 的可注入时钟版本（单测用）。
+    pub fn device_code_remaining_at(&self, now: Instant) -> Option<u64> {
+        if self.device_login.phase != DeviceLoginPhase::Waiting {
+            return None;
+        }
+        let expires = self.device_login.expires_in;
+        if expires == 0 {
+            return None;
+        }
+        let started = self.device_login_started?;
+        let elapsed = now.saturating_duration_since(started).as_secs();
+        Some(expires.saturating_sub(elapsed))
+    }
+
+    /// 当前启动账户（列表里 `active == true` 的那条）。
+    pub fn active_account(&self) -> Option<&AccountView> {
+        self.accounts.iter().find(|account| account.active)
+    }
+
+    /// 面板要显示的脱敏占位符（守门测试用：值不该出现在任何可见文案里）。
+    pub const REDACTED: &'static str = REDACTED;
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const JWT: &str =
+        "eyJhbGciOiJSUzI1NiIsIng1dCI6IkFCQyJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.c2lnbmF0dXJlLXZhbHVl";
+
+    fn state() -> AppState {
+        AppState::new()
+    }
+
+    /// 凭据红线：**绕过构造器**直接塞一个带 JWT 的事件，状态层必须把它抹掉。
+    ///
+    /// 抓得住：`apply_device_login` / `apply_authlib_login` 里的脱敏被删（那是「最后一个闸口」）。
+    /// 抓不住：恶意的 UI 层（如果有人绕过 `AppState` 直接画 DTO）。
+    #[test]
+    fn a_token_injected_into_events_never_reaches_the_state() {
+        let mut state = state();
+        state.apply_device_login(DeviceLoginView {
+            phase: DeviceLoginPhase::Failed,
+            message: format!("登录失败：accessToken={JWT}"),
+            ..DeviceLoginView::new()
+        });
+        assert!(
+            !state.device_login.message.contains(JWT),
+            "{}",
+            state.device_login.message
+        );
+        assert!(state.device_login.message.contains(REDACTED));
+
+        state.apply_authlib_login(AuthlibLoginView {
+            phase: DeviceLoginPhase::Failed,
+            message: format!("服务器回包 {JWT}"),
+            ..AuthlibLoginView::new()
+        });
+        assert!(
+            !state.authlib_login.message.contains(JWT),
+            "{}",
+            state.authlib_login.message
+        );
+    }
+
+    #[test]
+    fn the_device_code_countdown_is_derived_from_a_start_instant() {
+        let mut state = state();
+        state.apply_device_login(DeviceLoginView::waiting(
+            "ABCD-EFGH",
+            "https://www.microsoft.com/link",
+            900,
+            "",
+        ));
+        let started = state.device_login_started.expect("等待态要记起点");
+        assert_eq!(state.device_code_remaining_at(started), Some(900));
+        let later = started + std::time::Duration::from_secs(120);
+        assert_eq!(state.device_code_remaining_at(later), Some(780));
+        let expired = started + std::time::Duration::from_secs(901);
+        assert_eq!(
+            state.device_code_remaining_at(expired),
+            Some(0),
+            "过期后是 0，不是 None"
+        );
+
+        // 没有在等的时候不画倒计时
+        state.apply_device_login(DeviceLoginView::failed("网络超时"));
+        assert_eq!(state.device_code_remaining_at(started), None);
+    }
+
+    #[test]
+    fn a_new_waiting_view_restarts_the_countdown() {
+        let mut state = state();
+        state.apply_device_login(DeviceLoginView::waiting("AAAA-AAAA", "https://a", 900, ""));
+        let first = state.device_login_started.expect("起点");
+        state.apply_device_login(DeviceLoginView::waiting("BBBB-BBBB", "https://a", 900, ""));
+        let second = state.device_login_started.expect("起点");
+        assert!(second >= first, "换了一个用户码就要重算倒计时");
+    }
+
+    #[test]
+    fn the_active_account_is_the_one_marked_active() {
+        let mut state = state();
+        state.accounts = vec![
+            AccountView {
+                id: "account:a".to_string(),
+                name: "Steve".to_string(),
+                kind: crate::dto::AccountKind::Microsoft,
+                profile_id: "0f8f".to_string(),
+                login_name: String::new(),
+                created: String::new(),
+                active: false,
+                server_url: String::new(),
+                skin: None,
+            },
+            AccountView {
+                id: "account:b".to_string(),
+                name: "Alex".to_string(),
+                kind: crate::dto::AccountKind::Offline,
+                profile_id: "1a2b".to_string(),
+                login_name: String::new(),
+                created: String::new(),
+                active: true,
+                server_url: String::new(),
+                skin: None,
+            },
+        ];
+        assert_eq!(
+            state.active_account().map(|a| a.name.as_str()),
+            Some("Alex")
+        );
+    }
+}
diff --git a/crates/presenter/src/state/content.rs b/crates/presenter/src/state/content.rs
new file mode 100644
index 0000000..d4ca6c7
--- /dev/null
+++ b/crates/presenter/src/state/content.rs
@@ -0,0 +1,45 @@
+//! 内容库的状态机（M109）：结果落地与条件提交两件事。
+//!
+//! 从 `state.rs` 拆出（那个文件重新合流 M105 之后贴着 400 行上限）。放在 `impl AppState` 的
+//! **另一个 impl 块**里，路径与可见性都不变：`apply_core` 直接调 `self.apply_content(..)`。
+
+use crate::dto::{ContentQuery, ContentResults};
+
+use super::AppState;
+
+impl AppState {
+    /// 内容库结果落地（M109）：同条件换页 ⇒ **追加**；换条件 ⇒ **整批替换**；迟到 ⇒ 丢掉。
+    ///
+    /// 这三条就是「列表画的永远是当前筛选条件」的全部保证——页面自己没有过滤逻辑，也没有第二份真相。
+    pub(super) fn apply_content(&mut self, results: ContentResults) {
+        self.content.pending = false;
+        self.content.failed = None;
+        if !self.content.accepts(&results) {
+            // 迟到的一批：用户已经改了条件，覆盖上去就会出现「筛选条说 A、列表是 B」。
+            return;
+        }
+        // **先**按「这一页装没装满」记一位，再把它并进累计列表（复审 P1-2：判据不能读累计值）。
+        self.content.last_page_filled = results.has_more();
+        match &mut self.content.results {
+            Some(current) if results.query.offset > 0 => {
+                current.hits.extend(results.hits);
+                current.total = results.total;
+                current.curseforge = results.curseforge;
+                current.query = results.query;
+            }
+            _ => self.content.results = Some(results),
+        }
+    }
+
+    /// 记下新的检索条件并进入「请求在飞」态（指令由调用方随后 dispatch）。
+    pub fn set_content_query(&mut self, query: ContentQuery) {
+        self.content.pending = true;
+        self.content.failed = None;
+        if query.offset == 0 {
+            self.content.last_page_filled = false;
+            // 换条件（不是换页）：先把旧结果清掉，否则加载态会画出上一批命中项。
+            self.content.results = None;
+        }
+        self.content.query = query;
+    }
+}
diff --git a/crates/presenter/src/state/content_tests.rs b/crates/presenter/src/state/content_tests.rs
new file mode 100644
index 0000000..e2c612b
--- /dev/null
+++ b/crates/presenter/src/state/content_tests.rs
@@ -0,0 +1,130 @@
+//! 内容库状态机的守门测试（M109；复审 P1-2 的补课）。
+//!
+//! 从 `state.rs` 拆出（那个文件贴 400 行硬上限）。钉的是**翻页判据**：
+//! `has_more` 必须读「最近一页是否装满」，不能读累计条数——否则第 2 页之后恒真。
+
+use crate::dto::{
+    AppEvent, ContentHit, ContentKind, ContentQuery, ContentResults, ContentSource, CoreEvent,
+};
+
+use super::AppState;
+
+fn hit(index: usize) -> ContentHit {
+    ContentHit {
+        id: format!("p{index}"),
+        slug: format!("p{index}"),
+        title: format!("Project {index}"),
+        summary: "s".to_string(),
+        author: "a".to_string(),
+        downloads: 0,
+        updated: "2026-01-01".to_string(),
+        source: ContentSource::Modrinth,
+        game_versions: vec!["1.20.1".to_string()],
+        loaders: vec!["fabric".to_string()],
+        icon: None,
+    }
+}
+
+/// 造一页结果：`offset` 是游标，`count` 是这一页实际回来几条。
+fn page(offset: u32, count: u32) -> ContentResults {
+    let mut query = ContentQuery::first(ContentKind::Mod);
+    query.offset = offset;
+    ContentResults {
+        query,
+        hits: (0..count)
+            .map(|index| hit(offset as usize + index as usize))
+            .collect(),
+        total: 999,
+        curseforge: false,
+    }
+}
+
+fn apply(state: &mut AppState, results: ContentResults) {
+    state.apply(AppEvent::Core(CoreEvent::ContentResults(Box::new(results))));
+}
+
+/// 复审 P1-2 的第一条：装满一页 ⇒ 还有更多；下一（末）页不满 ⇒ 没有了。
+#[test]
+fn a_short_last_page_clears_has_more() {
+    let mut state = AppState::new();
+    let limit = ContentQuery::first(ContentKind::Mod).limit;
+
+    apply(&mut state, page(0, limit));
+    assert!(state.content.last_page_filled, "首页装满 ⇒ 还有下一页");
+    assert_eq!(
+        state.content.results.as_ref().map_or(0, |r| r.hits.len()),
+        limit as usize
+    );
+
+    // 末页只回来 3 条：累计 23 条「够一页了」，但**这一页**没装满 ⇒ 没有更多
+    apply(&mut state, page(limit, 3));
+    assert!(
+        !state.content.last_page_filled,
+        "末页不满 ⇒ 不许说还有更多（判据不能读累计条数）"
+    );
+    assert_eq!(
+        state.content.results.as_ref().map_or(0, |r| r.hits.len()),
+        limit as usize + 3,
+        "命中项仍然要累加"
+    );
+}
+
+/// 复审 P1-2 的第二条：再点一次，回来的空页仍然是「没有更多」。
+#[test]
+fn an_empty_last_page_keeps_has_more_false() {
+    let mut state = AppState::new();
+    let limit = ContentQuery::first(ContentKind::Mod).limit;
+
+    apply(&mut state, page(0, limit));
+    apply(&mut state, page(limit, 0));
+    assert!(!state.content.last_page_filled, "空页 ⇒ 没有更多");
+
+    // 用户又点了一次「加载更多」：空页不会把状态翻回真
+    apply(&mut state, page(limit + limit, 0));
+    assert!(
+        !state.content.last_page_filled,
+        "再点一次空页 ⇒ 仍然没有更多"
+    );
+    assert_eq!(
+        state.content.results.as_ref().map_or(0, |r| r.hits.len()),
+        limit as usize,
+        "空页不改变列表内容"
+    );
+}
+
+/// 换条件（offset 回到 0）时把「最近一页装满」清掉：不然新条件的第一帧就会画「没有更多了」。
+#[test]
+fn changing_the_query_resets_the_page_flag() {
+    let mut state = AppState::new();
+    let limit = ContentQuery::first(ContentKind::Mod).limit;
+
+    apply(&mut state, page(0, limit));
+    assert!(state.content.last_page_filled);
+
+    let mut query = ContentQuery::first(ContentKind::Mod);
+    query.text = "sodium".to_string();
+    state.set_content_query(query);
+    assert!(!state.content.last_page_filled, "换条件 ⇒ 清掉上一批的判据");
+    assert!(state.content.pending);
+    assert!(
+        state.content.results.is_none(),
+        "换条件要清列表（不然加载态画旧命中项）"
+    );
+}
+
+/// 迟到的一批不许改写判据（用户已经换了条件）。
+#[test]
+fn a_stale_batch_does_not_touch_the_page_flag() {
+    let mut state = AppState::new();
+    let limit = ContentQuery::first(ContentKind::Mod).limit;
+
+    apply(&mut state, page(0, limit));
+    let mut query = ContentQuery::first(ContentKind::Mod);
+    query.text = "sodium".to_string();
+    state.set_content_query(query);
+
+    // 旧条件的一页这时才回来：既不改结果，也不改「还有更多」
+    apply(&mut state, page(limit, 5));
+    assert!(!state.content.last_page_filled);
+    assert!(state.content.results.is_none(), "迟到的一批被丢掉");
+}
diff --git a/crates/presenter/src/state/live.rs b/crates/presenter/src/state/live.rs
new file mode 100644
index 0000000..15d2a57
--- /dev/null
+++ b/crates/presenter/src/state/live.rs
@@ -0,0 +1,30 @@
+//! 实时日志的滚动窗口（从 `state.rs` 搬出，守 400 行硬线）。
+//!
+//! 纯搬移：常量与 `append_live_lines` 一字未改；`state.rs` 用 `pub use` 再导出
+//! [`MAX_LIVE_LINES`]，老路径 `crate::state::MAX_LIVE_LINES` 继续可用。
+
+use super::AppState;
+
+/// 实时日志最多保留的行数（滚动窗口；更多行由日志页的筛选/历史会话承担）。
+pub const MAX_LIVE_LINES: usize = 2_000;
+
+impl AppState {
+    /// 实时日志增量：只追加，封顶 [`MAX_LIVE_LINES`] 行（滚动窗口）。
+    pub(super) fn append_live_lines(&mut self, batch: &crate::dto::LiveLogBatch) {
+        if self
+            .live_session
+            .as_deref()
+            .is_some_and(|session| session != batch.session)
+        {
+            // 换了一个会话在跑：清掉上一场的行，避免两场日志混在一起
+            self.log_lines.clear();
+        }
+        self.live_session = batch.running.then(|| batch.session.clone());
+        self.selected_session = Some(batch.session.clone());
+        self.log_lines.extend(batch.lines.iter().cloned());
+        if self.log_lines.len() > MAX_LIVE_LINES {
+            let drop = self.log_lines.len() - MAX_LIVE_LINES;
+            self.log_lines.drain(..drop);
+        }
+    }
+}
diff --git a/crates/presenter/src/state/tiles.rs b/crates/presenter/src/state/tiles.rs
new file mode 100644
index 0000000..da8988b
--- /dev/null
+++ b/crates/presenter/src/state/tiles.rs
@@ -0,0 +1,27 @@
+//! 磁贴网格的纯函数与单元类型（从 `state.rs` 原样搬出，守 400 行硬线）。
+//!
+//! **纯搬移**：类型、函数、文档一字未改，只是换了文件；`state.rs` 用 `pub use` 再导出，
+//! 于是 `crate::state::{TileCell, grid_positions}` 这两个老路径继续可用。
+
+use crate::dto::InstanceSummary;
+
+/// 磁贴网格单元：位置由 [`grid_positions`] 算好，UI 侧只消费 row/col。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct TileCell<'a> {
+    /// 实例数据
+    pub instance: &'a InstanceSummary,
+    /// 网格行号（0 起）
+    pub row: usize,
+    /// 网格列号（0 起）
+    pub col: usize,
+}
+
+/// 纯函数：把 n 个磁贴摊到 `columns` 列的网格上，返回 `(row, col)`。
+///
+/// 特意放在 Rust 侧：声明式 UI 的表达式里做整数除法容易引出隐式浮点，且这段逻辑可以单测。
+pub fn grid_positions(count: usize, columns: usize) -> Vec<(usize, usize)> {
+    let columns = columns.max(1);
+    (0..count)
+        .map(|index| (index / columns, index % columns))
+        .collect()
+}
diff --git a/crates/presenter/src/state_tests.rs b/crates/presenter/src/state_tests.rs
new file mode 100644
index 0000000..e1a4358
--- /dev/null
+++ b/crates/presenter/src/state_tests.rs
@@ -0,0 +1,371 @@
+//! state.rs 的单元测试（拆文件保持单文件 ≤400 行）。
+
+use super::{grid_positions, AppState};
+use crate::agent::AgentRail;
+use crate::dialogs::{DialogKind, DialogRequest, DialogSource};
+use crate::dto::{
+    AgentEvent, AppEvent, ChatMessage, ChatRole, CoreEvent, Diagnosis, DiagnosisReport,
+    InstanceRuntime, InstanceSummary, LoaderInfo, LoaderKind,
+};
+use crate::prefs::TileSize;
+use crate::router::Route;
+use crate::toast::Toast;
+use crate::toast::ToastKind;
+
+fn instance(id: &str, name: &str) -> InstanceSummary {
+    InstanceSummary {
+        id: id.to_string(),
+        name: name.to_string(),
+        mc_version: "1.20.4".to_string(),
+        loader: LoaderInfo {
+            kind: LoaderKind::Fabric,
+            version: "0.16.5".to_string(),
+        },
+        last_played: None,
+        runtime: InstanceRuntime::Idle,
+        icon: None,
+        isolation: "isolated".to_string(),
+        version_id: "1.20.4".to_string(),
+        version_present: true,
+    }
+}
+
+#[test]
+fn grid_positions_wrap_by_column_count() {
+    assert_eq!(grid_positions(0, 4), vec![]);
+    assert_eq!(grid_positions(3, 2), vec![(0, 0), (0, 1), (1, 0)]);
+    // columns == 0 时按 1 列兜底，不允许除零
+    assert_eq!(grid_positions(2, 0), vec![(0, 0), (1, 0)]);
+}
+
+#[test]
+fn tiles_follow_tile_size_and_search() {
+    let mut state = AppState::new();
+    state.instances = vec![
+        instance("a", "生存"),
+        instance("b", "创造"),
+        instance("c", "Demo"),
+    ];
+
+    assert_eq!(state.tiles().len(), 3);
+    assert_eq!((state.tiles()[2].row, state.tiles()[2].col), (0, 2));
+
+    state.prefs.tile_size = TileSize::Large;
+    assert_eq!((state.tiles()[2].row, state.tiles()[2].col), (0, 2));
+
+    state.prefs.tile_size = TileSize::Small;
+    assert_eq!(state.tiles().len(), 3);
+
+    state.instance_query = "demo".to_string();
+    let tiles = state.tiles();
+    assert_eq!(tiles.len(), 1);
+    assert_eq!(tiles[0].instance.id, "c");
+    assert_eq!((tiles[0].row, tiles[0].col), (0, 0));
+}
+
+#[test]
+fn tiles_reflow_when_tile_size_shrinks() {
+    let mut state = AppState::new();
+    state.instances = (0..8)
+        .map(|i| instance(&format!("i{i}"), &format!("实例{i}")))
+        .collect();
+
+    state.prefs.tile_size = TileSize::Medium;
+    let medium_rows = state.tiles().iter().map(|cell| cell.row).max();
+
+    state.prefs.tile_size = TileSize::Small;
+    let small_rows = state.tiles().iter().map(|cell| cell.row).max();
+
+    assert_eq!(medium_rows, Some(1)); // 8 / 4 列 = 2 行
+    assert_eq!(small_rows, Some(1)); // 8 / 6 列 = 2 行
+}
+
+#[test]
+fn runtime_events_update_the_matching_instance() {
+    let mut state = AppState::new();
+    state.instances = vec![instance("a", "生存"), instance("b", "创造")];
+
+    state.apply(AppEvent::Core(CoreEvent::InstanceRuntimeChanged {
+        id: "b".to_string(),
+        runtime: InstanceRuntime::Running { pid: 42 },
+    }));
+
+    assert_eq!(state.instances[0].runtime, InstanceRuntime::Idle);
+    assert_eq!(
+        state.instances[1].runtime,
+        InstanceRuntime::Running { pid: 42 }
+    );
+    assert_eq!(state.running().len(), 1);
+    assert_eq!(state.running()[0].id, "b");
+}
+
+#[test]
+fn progress_events_only_touch_busy_instances() {
+    let mut state = AppState::new();
+    state.instances = vec![instance("a", "生存")];
+    state.instances[0].runtime = InstanceRuntime::Busy {
+        stage: crate::dto::LaunchStage::Download,
+        progress: crate::dto::Progress {
+            done: 0,
+            total: 100,
+        },
+    };
+
+    state.set_progress(
+        "a",
+        crate::dto::Progress {
+            done: 50,
+            total: 100,
+        },
+    );
+    match &state.instances[0].runtime {
+        InstanceRuntime::Busy { progress, .. } => {
+            assert!((progress.ratio() - 0.5).abs() < f32::EPSILON);
+        }
+        other => panic!("unexpected runtime: {other:?}"),
+    }
+
+    // 不存在的 id / 非 Busy 状态不改变任何东西
+    state.set_progress("missing", crate::dto::Progress { done: 1, total: 1 });
+    assert_eq!(state.instances.len(), 1);
+}
+
+#[test]
+fn ai_stream_deltas_accumulate_and_finish() {
+    let mut state = AppState::new();
+    state.apply(AppEvent::Agent(AgentEvent::MessageAppended(
+        ChatMessage::user("怎么装 1.20.4"),
+    )));
+    state.apply(AppEvent::Agent(AgentEvent::MessageAppended(
+        ChatMessage::assistant_stream(),
+    )));
+    assert_eq!(state.ai.messages.len(), 2);
+    assert!(state.ai.streaming);
+    assert_eq!(state.ai.messages[1].role, ChatRole::Assistant);
+
+    state.apply(AppEvent::Agent(AgentEvent::MessageDelta {
+        index: 1,
+        delta: "先".to_string(),
+    }));
+    state.apply(AppEvent::Agent(AgentEvent::MessageDelta {
+        index: 1,
+        delta: "下载".to_string(),
+    }));
+    state.apply(AppEvent::Agent(AgentEvent::MessageFinished { index: 1 }));
+
+    assert_eq!(state.ai.messages[1].text, "先下载");
+    assert!(!state.ai.messages[1].streaming);
+    assert!(!state.ai.streaming);
+}
+
+#[test]
+fn ai_session_finish_stream_clears_every_flag() {
+    let mut session = AgentRail::new();
+    session.messages.push(ChatMessage::user("hi"));
+    session.messages.push(ChatMessage::assistant_stream());
+    session.finish_stream();
+    assert!(session.messages.iter().all(|message| !message.streaming));
+    assert!(!session.streaming);
+    assert!(!session.busy);
+}
+
+#[test]
+fn tool_call_finish_updates_the_last_matching_message() {
+    let mut state = AppState::new();
+    state.apply(AppEvent::Agent(AgentEvent::ToolCallStarted {
+        name: "get_config".to_string(),
+        summary: "读取设置".to_string(),
+    }));
+    state.apply(AppEvent::Agent(AgentEvent::ToolCallFinished {
+        name: "get_config".to_string(),
+        ok: true,
+        summary: "读取到 3 项".to_string(),
+    }));
+
+    let tool = &state.ai.messages[0];
+    assert_eq!(tool.role, ChatRole::Tool);
+    assert_eq!(tool.text, "读取到 3 项");
+    assert!(!tool.streaming);
+    assert!(tool.tool.as_ref().is_some_and(|call| call.ok));
+}
+
+#[test]
+fn dialogs_and_toasts_flow_through_apply() {
+    let mut state = AppState::new();
+    state.apply(AppEvent::DialogRequested(DialogRequest {
+        id: 42,
+        source: DialogSource::UserAction,
+        title: "AI 想修改内存".to_string(),
+        body: "改为 8G".to_string(),
+        kind: DialogKind::Confirm {
+            primary: "允许".to_string(),
+            secondary: "拒绝".to_string(),
+        },
+    }));
+    state.apply(AppEvent::Toast(Toast {
+        id: 0,
+        kind: ToastKind::Success,
+        text: "下载完成".to_string(),
+        remaining_ms: 0,
+    }));
+
+    assert_eq!(state.dialogs.pending_len(), 0);
+    // id 归生产者：队列原样保留，DialogClosed(42) 才能命中同一条
+    assert_eq!(state.dialogs.current().map(|dialog| dialog.id), Some(42));
+    assert_eq!(state.toasts.len(), 1);
+
+    state.apply(AppEvent::DialogClosed(42));
+    assert!(state.dialogs.is_empty());
+}
+
+#[test]
+fn navigate_to_agent_page_expands_the_ai_panel() {
+    let mut state = AppState::new();
+    state.prefs.ai_collapsed = true;
+    state.navigate(Route::Agent);
+    assert_eq!(state.route(), &Route::Agent);
+    assert_eq!(state.ai_mode(), crate::router::AiPanelMode::Page);
+    assert!(!state.prefs.ai_collapsed);
+}
+
+#[test]
+fn toggling_ai_from_the_page_form_docks_it_again() {
+    let mut state = AppState::new();
+    state.navigate(Route::Agent);
+    state.toggle_ai();
+    assert_eq!(state.route(), &Route::Instances);
+    assert_eq!(state.ai_mode(), crate::router::AiPanelMode::Docked);
+    assert!(!state.prefs.ai_collapsed);
+
+    state.toggle_ai();
+    assert!(state.prefs.ai_collapsed);
+}
+
+#[test]
+fn failed_event_settles_streaming_and_keeps_the_evidence() {
+    let mut state = AppState::new();
+    state.apply(AppEvent::Agent(AgentEvent::MessageAppended(
+        ChatMessage::assistant_stream(),
+    )));
+    state.apply(AppEvent::Agent(AgentEvent::MessageDelta {
+        index: 0,
+        delta: "我先读一下".to_string(),
+    }));
+    state.apply(AppEvent::Agent(AgentEvent::Failed {
+        message: "provider 断流：read timeout".to_string(),
+    }));
+
+    // 抓得住：已到的增量不丢、流式标记收敛、错误进横幅也进会话历史
+    assert_eq!(state.ai.messages[0].text, "我先读一下");
+    assert!(!state.ai.messages[0].streaming);
+    assert!(!state.ai.streaming);
+    assert!(!state.ai.busy);
+    assert_eq!(
+        state.ai.error.as_deref(),
+        Some("provider 断流：read timeout")
+    );
+    assert_eq!(state.ai.messages[1].role, ChatRole::System);
+    // 抓不住：这里不判断错误归因（那是 core::diagnose 的事）
+}
+
+#[test]
+fn confirm_request_keeps_the_shell_busy_until_it_resolves() {
+    // 分工：这条钉 state 层的「待确认 ⇒ busy」与 `ConfirmResolved` 收敛；
+    // presenter 层的同名守卫是 `agent::tests::pending_confirm_forces_busy_without_yolo`
+    // （r1 P2-2：那条曾因 ToolCallStarted 顺手置真而空过，已改成先 finish_stream 再断言）。
+    let mut state = AppState::new();
+    state.apply(AppEvent::Agent(AgentEvent::ConfirmRequested {
+        request: confirm_request("req-1"),
+    }));
+    assert!(state.ai.busy, "有待确认时 UI 必须禁用输入");
+    assert_eq!(
+        state.ai.confirm.as_ref().map(|request| request.id.as_str()),
+        Some("req-1")
+    );
+
+    // 别处已裁决（重放/超时）：僵尸弹窗必须收掉
+    state.apply(AppEvent::Agent(AgentEvent::ConfirmResolved {
+        id: "req-1".to_string(),
+    }));
+    assert!(!state.ai.busy);
+    assert!(state.ai.confirm.is_none());
+}
+
+#[test]
+fn unread_counts_only_while_the_rail_is_out_of_sight() {
+    let mut state = AppState::new();
+    // 展开的常驻栏在任何页面都挂着：到达即已读
+    assert!(state.agent_rail_visible());
+    state.apply(AppEvent::Agent(AgentEvent::MessageAppended(
+        ChatMessage::assistant_stream(),
+    )));
+    assert_eq!(state.ai.unread, 0);
+
+    // 收成 icon 轨 = 用户看不见
+    state.prefs.ai_collapsed = true;
+    assert!(!state.agent_rail_visible());
+    state.apply(AppEvent::Agent(AgentEvent::MessageDelta {
+        index: 0,
+        delta: "长回复".to_string(),
+    }));
+    assert_eq!(state.ai.unread, 0, "增量属于同一条消息，不重复计数");
+    state.apply(AppEvent::Agent(AgentEvent::ToolCallStarted {
+        name: "read_game_log".to_string(),
+        summary: "读取日志".to_string(),
+    }));
+    assert_eq!(state.ai.unread, 1);
+
+    // 展开栏 = 用户在看它，未读立刻归零
+    state.toggle_ai();
+    assert_eq!(state.ai.unread, 0);
+
+    // 独立页形态永远算可见
+    state.navigate(Route::Agent);
+    assert!(state.agent_rail_visible());
+}
+
+#[test]
+fn user_messages_never_count_as_unread() {
+    let mut state = AppState::new();
+    state.prefs.ai_collapsed = true;
+    state.apply(AppEvent::Agent(AgentEvent::MessageAppended(
+        ChatMessage::user("我自己说的话"),
+    )));
+    assert_eq!(state.ai.unread, 0);
+}
+
+/// 待确认请求样例（High 级写操作）。
+fn confirm_request(id: &str) -> crate::dto::ConfirmRequest {
+    crate::dto::ConfirmRequest {
+        id: id.to_string(),
+        tool: "set_config".to_string(),
+        summary: "把下载并发 64 → 16".to_string(),
+        details: serde_json::json!({ "path": "download.concurrency" }),
+        sensitivity: crate::dto::Sensitivity::High,
+    }
+}
+
+#[test]
+fn toggle_nav_flips_the_pref() {
+    let mut state = AppState::new();
+    state.toggle_nav();
+    assert!(state.prefs.nav_collapsed);
+    state.toggle_nav();
+    assert!(!state.prefs.nav_collapsed);
+}
+
+#[test]
+fn diagnosis_report_lands_on_state() {
+    let mut state = AppState::new();
+    state.apply(AppEvent::Core(CoreEvent::DiagnosisReady(DiagnosisReport {
+        session: "s1".to_string(),
+        diagnosis: Diagnosis {
+            rule: "gpu.driver_old".to_string(),
+            title: "显卡驱动过旧".to_string(),
+            confidence: 92,
+            hint: "升级驱动".to_string(),
+            fix: Some("open_driver_page".to_string()),
+        },
+    })));
+    assert!(state.diagnosis.is_some());
+}
diff --git a/crates/presenter/src/theme.rs b/crates/presenter/src/theme.rs
new file mode 100644
index 0000000..08c798c
--- /dev/null
+++ b/crates/presenter/src/theme.rs
@@ -0,0 +1,165 @@
+//! 主题与外观的**纯**判据：轮询节拍、背景图缓存键与量化、系统主题取值。
+//!
+//! 这一层原本混在 `crates/app` 的 `ui_bind.rs` / `theme_runtime.rs` 里，与「把值灌进窗口属性」
+//! 的绑定代码缠在一起，于是两个 UI 版都得各写一遍。抽到这里的只有**判据**：什么时候该重读配置、
+//! 什么时候该重建背景图、系统主题该报哪个值。灌属性仍然由 UI 侧做，本模块不碰任何框架类型。
+
+use crate::prefs::BgFill;
+
+/// 配置热切轮询间隔（拍数，33ms/拍 → 约 1s 一次 `mtime` 比对，AI/CLI 改完下一拍即生效）。
+pub const CONFIG_POLL_TICKS: u64 = 30;
+
+/// 系统主题兜底轮询间隔（拍数）：只在 `auto` 且后端不认识系统主题时启动（约 3s）。
+pub const SYSTEM_THEME_POLL_TICKS: u64 = 90;
+
+/// tile 模式重建画布的窗口尺寸粒度（像素）：避免拖动窗口时反复重算平铺画布。
+pub const TILE_REGENERATE_STEP: u32 = 128;
+
+/// 系统主题取值（UI 侧根组件属性就用这三个值：0 未知 / 1 浅色 / 2 深色）。
+pub const SYSTEM_THEME_UNKNOWN: i32 = 0;
+/// 浅色。
+pub const SYSTEM_THEME_LIGHT: i32 = 1;
+/// 深色。
+pub const SYSTEM_THEME_DARK: i32 = 2;
+
+/// 背景图加工输入（值相同就不重新解码）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BackgroundKey {
+    /// 背景图路径
+    pub path: String,
+    /// 填充模式
+    pub fill: BgFill,
+    /// tile 用的窗口尺寸（按 [`TILE_REGENERATE_STEP`] 量化；cover/contain 恒为 (0, 0)）
+    pub viewport: (u32, u32),
+}
+
+/// 本拍是否该比对一次配置文件 `mtime`（热切的采样点）。
+pub fn config_poll_due(ticks: u64) -> bool {
+    ticks.is_multiple_of(CONFIG_POLL_TICKS)
+}
+
+/// 本拍是否该兜底探测系统主题。
+///
+/// 启动时先探一次（`probed == false`），之后只在「主题是 auto + 后端不认识系统主题」时
+/// 按 [`SYSTEM_THEME_POLL_TICKS`] 兜底轮询。
+pub fn system_theme_poll_due(probed: bool, auto: bool, backend_known: bool, ticks: u64) -> bool {
+    !probed || (auto && !backend_known && ticks.is_multiple_of(SYSTEM_THEME_POLL_TICKS))
+}
+
+/// 系统主题取值（纯映射，便于单测）。
+pub fn system_theme_code(theme: unlucky_core::platform::theme_probe::SystemTheme) -> i32 {
+    use unlucky_core::platform::theme_probe::SystemTheme;
+    match theme {
+        SystemTheme::Light => SYSTEM_THEME_LIGHT,
+        SystemTheme::Dark => SYSTEM_THEME_DARK,
+        SystemTheme::Unknown => SYSTEM_THEME_UNKNOWN,
+    }
+}
+
+/// 探测本机系统主题并给出 UI 侧属性值。
+pub fn system_theme_value() -> i32 {
+    system_theme_code(unlucky_core::platform::theme_probe::probe())
+}
+
+/// tile 画布的窗口尺寸（量化到 [`TILE_REGENERATE_STEP`]，避免拖动窗口时反复重算）。
+///
+/// 非 tile 模式恒为 (0, 0)：cover/contain 不依赖窗口尺寸，缩放只让渲染器拉伸。
+pub fn tile_viewport(fill: BgFill, size: (u32, u32)) -> (u32, u32) {
+    if fill != BgFill::Tile {
+        return (0, 0);
+    }
+    (
+        size.0 / TILE_REGENERATE_STEP * TILE_REGENERATE_STEP,
+        size.1 / TILE_REGENERATE_STEP * TILE_REGENERATE_STEP,
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{
+        config_poll_due, system_theme_code, system_theme_poll_due, tile_viewport, BackgroundKey,
+        CONFIG_POLL_TICKS, SYSTEM_THEME_DARK, SYSTEM_THEME_LIGHT, SYSTEM_THEME_POLL_TICKS,
+        SYSTEM_THEME_UNKNOWN, TILE_REGENERATE_STEP,
+    };
+    use crate::prefs::BgFill;
+    use unlucky_core::platform::theme_probe::SystemTheme;
+
+    #[test]
+    fn config_poll_fires_every_interval() {
+        assert!(config_poll_due(0));
+        assert!(!config_poll_due(1));
+        assert!(config_poll_due(CONFIG_POLL_TICKS));
+        assert!(!config_poll_due(CONFIG_POLL_TICKS + 1));
+    }
+
+    #[test]
+    fn system_theme_probe_backs_off_after_first_read() {
+        // 启动时无条件探一次
+        assert!(system_theme_poll_due(false, false, true, 1));
+        // 探过、主题非 auto：不再轮询
+        assert!(!system_theme_poll_due(
+            true,
+            false,
+            false,
+            SYSTEM_THEME_POLL_TICKS
+        ));
+        // 探过、auto、后端认识系统主题：不再轮询
+        assert!(!system_theme_poll_due(
+            true,
+            true,
+            true,
+            SYSTEM_THEME_POLL_TICKS
+        ));
+        // 探过、auto、后端不认识：按间隔兜底
+        assert!(!system_theme_poll_due(
+            true,
+            true,
+            false,
+            SYSTEM_THEME_POLL_TICKS - 1
+        ));
+        assert!(system_theme_poll_due(
+            true,
+            true,
+            false,
+            SYSTEM_THEME_POLL_TICKS
+        ));
+    }
+
+    #[test]
+    fn system_theme_codes_are_stable() {
+        assert_eq!(
+            system_theme_code(SystemTheme::Unknown),
+            SYSTEM_THEME_UNKNOWN
+        );
+        assert_eq!(system_theme_code(SystemTheme::Light), SYSTEM_THEME_LIGHT);
+        assert_eq!(system_theme_code(SystemTheme::Dark), SYSTEM_THEME_DARK);
+    }
+
+    #[test]
+    fn tile_viewport_quantizes_and_ignores_other_fills() {
+        assert_eq!(tile_viewport(BgFill::Cover, (1180, 760)), (0, 0));
+        assert_eq!(tile_viewport(BgFill::Contain, (1180, 760)), (0, 0));
+        let (width, height) = tile_viewport(BgFill::Tile, (1180, 760));
+        assert_eq!(width % TILE_REGENERATE_STEP, 0);
+        assert_eq!(height % TILE_REGENERATE_STEP, 0);
+        assert_eq!((width, height), (1152, 640));
+    }
+
+    #[test]
+    fn background_key_compares_by_value() {
+        let key = BackgroundKey {
+            path: "a.png".to_string(),
+            fill: BgFill::Tile,
+            viewport: (256, 256),
+        };
+        assert_eq!(key.clone(), key);
+        assert_ne!(
+            key,
+            BackgroundKey {
+                path: "a.png".to_string(),
+                fill: BgFill::Tile,
+                viewport: (128, 256),
+            }
+        );
+    }
+}
diff --git a/crates/presenter/src/toast.rs b/crates/presenter/src/toast.rs
new file mode 100644
index 0000000..d2d9bd3
--- /dev/null
+++ b/crates/presenter/src/toast.rs
@@ -0,0 +1,154 @@
+//! Toast 中心：右下角非阻塞提示（下载完成 / 复制成功 / 后台任务结论）。
+//!
+//! 与模态对话框队列（[`crate::dialogs`]）分开：Toast 不阻塞、不排序、可叠加，
+//! 只做「先进先出 + 上限裁剪 + TTL 到期」。UI 侧由 Rust 定时器每帧调用 [`ToastCenter::expire`]。
+
+use serde::{Deserialize, Serialize};
+
+/// Toast 标识。
+pub type ToastId = u64;
+
+/// Toast 语义色。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ToastKind {
+    /// 一般信息
+    Info,
+    /// 成功
+    Success,
+    /// 警告
+    Warn,
+    /// 错误
+    Error,
+}
+
+/// 一条 Toast；`remaining_ms` 由 [`ToastCenter::expire`] 递减。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Toast {
+    /// 队列内唯一 id（由 [`ToastCenter::push_request`] 重新编号）
+    pub id: ToastId,
+    /// 语义色
+    pub kind: ToastKind,
+    /// 提示文案
+    pub text: String,
+    /// 剩余存活毫秒（0 = 用默认 TTL，入队时补）
+    pub remaining_ms: u64,
+}
+
+/// Toast 中心：先进先出，超出上限丢最旧的。
+#[derive(Debug)]
+pub struct ToastCenter {
+    items: Vec<Toast>,
+    next_id: ToastId,
+    ttl_ms: u64,
+}
+
+impl Default for ToastCenter {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl ToastCenter {
+    /// 默认 4s 后自动消失。
+    pub fn new() -> Self {
+        Self {
+            items: Vec::new(),
+            next_id: 0,
+            ttl_ms: 4_000,
+        }
+    }
+
+    /// 同时最多显示的条数。
+    pub const MAX_VISIBLE: usize = 4;
+
+    /// 入队一条 Toast。
+    pub fn push(&mut self, kind: ToastKind, text: impl Into<String>) -> ToastId {
+        self.push_request(Toast {
+            id: 0,
+            kind,
+            text: text.into(),
+            remaining_ms: 0,
+        })
+    }
+
+    /// 入队一条已组装好的 Toast（事件通道用）；id 重新编号，`remaining_ms == 0` 视为用默认 TTL。
+    pub fn push_request(&mut self, mut toast: Toast) -> ToastId {
+        self.next_id += 1;
+        toast.id = self.next_id;
+        if toast.remaining_ms == 0 {
+            toast.remaining_ms = self.ttl_ms;
+        }
+        let id = toast.id;
+        self.items.push(toast);
+        while self.items.len() > Self::MAX_VISIBLE {
+            self.items.remove(0);
+        }
+        id
+    }
+
+    /// 当前显示列表（UI 模型来源）。
+    pub fn items(&self) -> &[Toast] {
+        &self.items
+    }
+
+    /// 手动关闭（点了关闭按钮）。
+    pub fn dismiss(&mut self, id: ToastId) -> bool {
+        if let Some(at) = self.items.iter().position(|toast| toast.id == id) {
+            self.items.remove(at);
+            true
+        } else {
+            false
+        }
+    }
+
+    /// 时间推进：移除到期 Toast。
+    pub fn expire(&mut self, elapsed_ms: u64) {
+        for toast in &mut self.items {
+            toast.remaining_ms = toast.remaining_ms.saturating_sub(elapsed_ms);
+        }
+        self.items.retain(|toast| toast.remaining_ms > 0);
+    }
+
+    /// 当前条数。
+    pub fn len(&self) -> usize {
+        self.items.len()
+    }
+
+    /// 是否没有 Toast。
+    pub fn is_empty(&self) -> bool {
+        self.items.is_empty()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{ToastCenter, ToastKind};
+
+    #[test]
+    fn toasts_expire_and_cap_the_stack() {
+        let mut center = ToastCenter::new();
+        center.push(ToastKind::Info, "a");
+        center.push(ToastKind::Info, "b");
+        assert_eq!(center.len(), 2);
+
+        for i in 0..10 {
+            center.push(ToastKind::Success, format!("t{i}"));
+        }
+        assert_eq!(center.len(), ToastCenter::MAX_VISIBLE);
+
+        center.expire(3_000);
+        assert_eq!(center.len(), ToastCenter::MAX_VISIBLE);
+        center.expire(1_001);
+        assert!(center.is_empty());
+    }
+
+    #[test]
+    fn dismiss_removes_one_toast() {
+        let mut center = ToastCenter::new();
+        let first = center.push(ToastKind::Info, "a");
+        center.push(ToastKind::Warn, "b");
+        assert!(center.dismiss(first));
+        assert!(!center.dismiss(first));
+        assert_eq!(center.len(), 1);
+    }
+}
diff --git a/crates/presenter/src/wizard.rs b/crates/presenter/src/wizard.rs
new file mode 100644
index 0000000..2d8322b
--- /dev/null
+++ b/crates/presenter/src/wizard.rs
@@ -0,0 +1,275 @@
+//! 新建实例向导（09 §G5）的纯状态机：版本 → 加载器 → 实例名 → 确认 → 进度。
+//!
+//! 放纯 Rust 而不是 Slint 里：步骤推进、名字合法性、加载器约束都能单测，
+//! Slint 只负责画。提交时由 host 转成 [`crate::dto::CreateRequest`] 走安装管线。
+
+use crate::dto::LoaderKind;
+
+/// 向导步骤。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum WizardStep {
+    /// 选版本
+    #[default]
+    Version,
+    /// 选加载器
+    Loader,
+    /// 起名
+    Name,
+    /// 确认（显示将下载的项）
+    Confirm,
+    /// 进度（提交后由安装进度接管）
+    Progress,
+}
+
+impl WizardStep {
+    /// 步骤序号（0 起，用于「第 N 步」文案）。
+    pub fn index(self) -> usize {
+        match self {
+            Self::Version => 0,
+            Self::Loader => 1,
+            Self::Name => 2,
+            Self::Confirm => 3,
+            Self::Progress => 4,
+        }
+    }
+
+    /// 步骤标题。
+    pub fn title(self) -> &'static str {
+        match self {
+            Self::Version => "选择版本",
+            Self::Loader => "选择加载器",
+            Self::Name => "实例名",
+            Self::Confirm => "确认",
+            Self::Progress => "安装中",
+        }
+    }
+
+    /// 下一步（进度是终点）。
+    pub fn next(self) -> Self {
+        match self {
+            Self::Version | Self::Progress => {
+                if self == Self::Progress {
+                    Self::Progress
+                } else {
+                    Self::Loader
+                }
+            }
+            Self::Loader => Self::Name,
+            Self::Name => Self::Confirm,
+            Self::Confirm => Self::Progress,
+        }
+    }
+
+    /// 上一步（版本是起点）。
+    pub fn back(self) -> Self {
+        match self {
+            Self::Version | Self::Progress => Self::Version,
+            Self::Loader => Self::Version,
+            Self::Name => Self::Loader,
+            Self::Confirm => Self::Name,
+        }
+    }
+}
+
+/// 向导状态。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct WizardState {
+    /// 是否打开（全屏模态）
+    pub open: bool,
+    /// 当前步骤
+    pub step: WizardStep,
+    /// 选中的版本 id
+    pub version: String,
+    /// 选中的加载器
+    pub loader: LoaderKind,
+    /// 加载器版本（空 = 最新）
+    pub loader_version: String,
+    /// 实例名草稿
+    pub name: String,
+    /// 校验错误（显示在向导内，不弹 Toast）
+    pub error: String,
+    /// 已提交（防重复点）
+    pub submitting: bool,
+}
+
+impl Default for WizardState {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl WizardState {
+    /// 关闭态。
+    pub fn new() -> Self {
+        Self {
+            open: false,
+            step: WizardStep::Version,
+            version: String::new(),
+            loader: LoaderKind::Vanilla,
+            loader_version: String::new(),
+            name: String::new(),
+            error: String::new(),
+            submitting: false,
+        }
+    }
+
+    /// 打开向导并复位。
+    pub fn open() -> Self {
+        Self {
+            open: true,
+            ..Self::new()
+        }
+    }
+
+    /// 选了版本：自动把实例名填成版本号（用户不改就用它）。
+    pub fn select_version(&mut self, version: &str) {
+        self.version = version.to_string();
+        if self.name.trim().is_empty() {
+            self.name = version.to_string();
+        }
+        self.error.clear();
+    }
+
+    /// 选加载器（原版会清掉加载器版本）。
+    pub fn select_loader(&mut self, loader: LoaderKind) {
+        self.loader = loader;
+        if loader == LoaderKind::Vanilla {
+            self.loader_version.clear();
+        }
+        self.error.clear();
+    }
+
+    /// 推进到下一步；校验不通过时留在原地并写 `error`。
+    pub fn advance(&mut self) -> bool {
+        match self.step {
+            WizardStep::Version => {
+                if self.version.trim().is_empty() {
+                    self.error = "请先选择一个版本".to_string();
+                    return false;
+                }
+            }
+            WizardStep::Name => {
+                if let Err(error) = validate_name(&self.name) {
+                    self.error = error;
+                    return false;
+                }
+            }
+            WizardStep::Loader | WizardStep::Confirm | WizardStep::Progress => {}
+        }
+        self.error.clear();
+        self.step = self.step.next();
+        true
+    }
+
+    /// 回退一步。
+    pub fn step_back(&mut self) {
+        self.error.clear();
+        self.step = self.step.back();
+    }
+
+    /// 提交前的最后校验（Confirm 步）。
+    pub fn ready_to_submit(&self) -> Result<(), String> {
+        if self.version.trim().is_empty() {
+            return Err("版本为空".to_string());
+        }
+        validate_name(&self.name)?;
+        Ok(())
+    }
+
+    /// 提交成功后进入进度步（关掉可编辑态）。
+    pub fn submitted(&mut self) {
+        self.submitting = true;
+        self.step = WizardStep::Progress;
+        self.error.clear();
+    }
+}
+
+/// 实例名合法性（不能空、不能含路径分隔符/控制字符、长度上限 64）。
+pub fn validate_name(name: &str) -> Result<(), String> {
+    let trimmed = name.trim();
+    if trimmed.is_empty() {
+        return Err("实例名不能为空".to_string());
+    }
+    if trimmed.chars().count() > 64 {
+        return Err("实例名最多 64 个字符".to_string());
+    }
+    if trimmed.contains(['/', '\\', ':', '*', '?', '"', '<', '>', '|']) {
+        return Err("实例名不能包含 / \\ : * ? \" < > |".to_string());
+    }
+    if trimmed.chars().any(|ch| ch.is_control()) {
+        return Err("实例名不能包含控制字符".to_string());
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn steps_walk_forward_and_back() {
+        assert_eq!(WizardStep::Version.next(), WizardStep::Loader);
+        assert_eq!(WizardStep::Loader.next(), WizardStep::Name);
+        assert_eq!(WizardStep::Name.next(), WizardStep::Confirm);
+        assert_eq!(WizardStep::Confirm.next(), WizardStep::Progress);
+        assert_eq!(WizardStep::Progress.next(), WizardStep::Progress);
+        assert_eq!(WizardStep::Confirm.back(), WizardStep::Name);
+        assert_eq!(WizardStep::Version.back(), WizardStep::Version);
+        assert_eq!(WizardStep::Progress.index(), 4);
+    }
+
+    #[test]
+    fn version_selection_fills_name_but_does_not_overwrite() {
+        let mut wizard = WizardState::open();
+        assert!(wizard.open);
+        wizard.select_version("1.20.4");
+        assert_eq!(wizard.name, "1.20.4");
+        wizard.name = "生存".to_string();
+        wizard.select_version("1.21");
+        assert_eq!(wizard.name, "生存", "用户改过的名字不该被覆盖");
+    }
+
+    #[test]
+    fn advance_requires_a_version_and_a_valid_name() {
+        let mut wizard = WizardState::open();
+        assert!(!wizard.advance(), "没有版本不能进下一步");
+        assert_eq!(wizard.error, "请先选择一个版本");
+
+        wizard.select_version("1.20.4");
+        assert!(wizard.advance());
+        assert_eq!(wizard.step, WizardStep::Loader);
+        assert!(wizard.advance());
+        assert_eq!(wizard.step, WizardStep::Name);
+
+        wizard.name = "a/b".to_string();
+        assert!(!wizard.advance(), "非法名字不能确认");
+        assert!(wizard.error.contains("不能包含"));
+
+        wizard.name = "生存".to_string();
+        assert!(wizard.advance());
+        assert_eq!(wizard.step, WizardStep::Confirm);
+        assert!(wizard.ready_to_submit().is_ok());
+        wizard.submitted();
+        assert_eq!(wizard.step, WizardStep::Progress);
+        assert!(wizard.submitting);
+    }
+
+    #[test]
+    fn loader_selection_clears_loader_version_for_vanilla() {
+        let mut wizard = WizardState::open();
+        wizard.loader_version = "0.16.5".to_string();
+        wizard.select_loader(LoaderKind::Fabric);
+        assert_eq!(wizard.loader_version, "0.16.5");
+        wizard.select_loader(LoaderKind::Vanilla);
+        assert_eq!(wizard.loader, LoaderKind::Vanilla);
+        assert!(wizard.loader_version.is_empty());
+    }
+
+    #[test]
+    fn name_validation_rejects_long_and_control_input() {
+        assert!(validate_name("生存").is_ok());
+        assert!(validate_name("").is_err());
+        assert!(validate_name(&"x".repeat(65)).is_err());
+        assert!(validate_name("a\u{7}b").is_err());
+    }
+}
diff --git a/deny.toml b/deny.toml
new file mode 100644
index 0000000..e9b0a59
--- /dev/null
+++ b/deny.toml
@@ -0,0 +1,54 @@
+# cargo-deny 配置（D15：Apache-2.0 主干，GPL 依赖不得进主干）。
+# CI 侧的安装与执行见 .github/workflows/guards.yml（licenses job）。
+# 参考：https://embarkstudios.github.io/cargo-deny/  ·  决策：DevDocs/PlanDoc/00-decision-log.md D15
+
+[graph]
+all-features = true
+
+[advisories]
+version = 2
+yanked = "deny"
+# 注意：cargo-deny 0.20 移除了 severity-threshold（见 PR #611），严重度改由
+# [advisories] 的 ignore 清单 + 后续安全轮次单独把关；这里只做「yanked 依赖禁止」。
+
+[licenses]
+version = 2
+# 白名单：Apache-2.0 / MIT / BSD / Zlib 系（用户要求）＋ 实际依赖树需要的宽松许可。
+# GPL / AGPL / LGPL / SSPL 一律不在列 → 直接 fail，不进主干。
+#
+# 补充项及来源（均为宽松、与 Apache-2.0 兼容，不改变「拒绝 copyleft」的立场）：
+# - BSL-1.0（Boost）：clipboard-win / error-code（winit/arboard 的 Windows 依赖）
+# - Unlicense：ksni（Slint 系统托盘）
+# - CDLA-Permissive-2.0：webpki-roots（Mozilla CA 根证书数据）
+# - Unicode-3.0：unicode-ident；CC0-1.0 / MIT-0 / ISC：生态常见宽松项
+confidence-threshold = 0.92
+allow = [
+    "Apache-2.0",
+    "Apache-2.0 WITH LLVM-exception",
+    "MIT",
+    "MIT-0",
+    "BSD-2-Clause",
+    "BSD-3-Clause",
+    "Zlib",
+    "BSL-1.0",
+    "ISC",
+    "CC0-1.0",
+    "Unlicense",
+    "Unicode-3.0",
+    "CDLA-Permissive-2.0",
+    # Slint（D2）走 Royalty-Free 2.0 轨道：其 crates 的 SPDX 表达为
+    # "GPL-3.0-only OR LicenseRef-Slint-Royalty-free-2.0 OR LicenseRef-Slint-Software-3.0"，
+    # 允许多选一即通过；这里显式放行 RF 分支，GPL 分支仍是拒绝的。
+    # 主义务：关于页放 AboutSlint 部件（见 NOTICE 与 DevDocs/PlanDoc/01c-native-gui-options.md §8）。
+    "LicenseRef-Slint-Royalty-free-2.0",
+]
+
+[bans]
+multiple-versions = "warn"
+wildcards = "deny"
+highlight = "all"
+
+[sources]
+unknown-registry = "deny"
+unknown-git = "deny"
+allow-registry = ["https://github.com/rust-lang/crates.io-index"]
diff --git a/packaging/README.md b/packaging/README.md
new file mode 100644
index 0000000..0408af6
--- /dev/null
+++ b/packaging/README.md
@@ -0,0 +1,401 @@
+# 打包与发布工程（packaging/）
+
+单一真相源：**单文件产物矩阵 + 发布契约**。`.github/workflows/release.yml` 按本文实现，
+`packaging/make_artifacts.py` 是本地与 CI **共用**的打包脚本（同一份代码 → 同一套目录布局）。
+本目录只放发布工程资产（脚本 / 说明 / 发布说明模板），不参与任何 crate 的编译。
+
+## 1. 产物矩阵
+
+| 槽位 | 产物文件名 | 形态 | 归档内容 |
+|------|-----------|------|---------|
+| `windows-x64` | `unlucky-launcher_<ver>_windows_x64.exe` | **裸 exe**（双击即用） | exe 单文件；三份合规文本作为并列 Release 资产 |
+| `windows-arm64` | `unlucky-launcher_<ver>_windows_arm64.exe` | **裸 exe**（同 x64 策略） | 同上；在 x64 宿主上交叉编译到 `aarch64-pc-windows-msvc` |
+| `linux-x64` | `unlucky-launcher_<ver>_linux_x64.tar.gz` | 单二进制归档 | `unlucky-launcher` + `LICENSE` + `NOTICE` + `README.md` |
+| `linux-arm64` | `unlucky-launcher_<ver>_linux_arm64.tar.gz` | 单二进制归档（原生 ARM64 runner 构建） | 同上 |
+| `macos-arm64` | `unlucky-launcher_<ver>_macos_arm64.tar.gz` | 单二进制归档 | 同上 |
+| `macos-x64` | `unlucky-launcher_<ver>_macos_x64.tar.gz` | 单二进制归档 | 同上 |
+| 每槽位 | `ull_<ver>_<平台>_<架构>[.exe]` | **裸 CLI 文件**（独立资产，不进 tar.gz） | 零 UI 依赖的 `ull` 本体，进同一份 `SHA256SUMS.txt` |
+| 全平台 | `SHA256SUMS.txt` | 校验清单 | 每行 `<sha256>␠␠<文件名>`（`sha256sum -c` 可直吃） |
+
+约定细节：
+
+- **产物命名**：`<名字>_<版本号>_<平台>_<架构>`，下划线分段、**不带实现细节字样**（不出现 `iced`）；真相源是 `make_artifacts.py::asset_stem()`。
+- **"单文件"指可执行文件本身零运行时依赖**（无 WebView、无 JRE、无 sidecar、无 DLL 旁挂）；归档里的三份合规文本是许可义务、不是运行时依赖，Windows 因为"一个 exe 装不下文本"，
+  把 `LICENSE` / `NOTICE` / `README.md` 作为 Release 的并列资产分发，条款同样随下载走。
+- 归档解压后是**一个顶层目录** `unlucky-launcher_<ver>_<平台>_<架构>/`，用户不会解压出一堆散文件。
+- **`ull` 是并列的裸资产，不塞进 tar.gz**：headless 用户要的就是「下一个小文件直接跑」；归档里放
+  LICENSE/NOTICE/README.md 是许可义务，而这三份本来就作为并列 Release 资产分发，裸 `ull` 不缺条款。
+- `unlucky-launcher` 本体也认全部 CLI 子命令（M82），`ull` 不是第二个界面，而是**不链接图形栈**的同一套命令（差异见 §4 与 §7.4），两者不是重复品。
+  M118：GUI 的**构建产物**名是 `unlucky-launcher-iced`（`crates/app` 已被 workspace `exclude`，不再产出 `unlucky-launcher`）；对外文件名仍是 `unlucky-launcher`，改名在 `make_artifacts.py` 落盘时（`LAUNCHER_BIN` 找产物 / `LAUNCHER_ASSET` 定对外名），所以下载链接 / `SHA256SUMS` / 本文矩阵不变。
+- `<ver>` 不带前导 `v`（tag 是 `v0.2.0`，文件名是 `0.2.0`）——由脚本统一裁剪。
+- UNIX 归档内 `mtime`/`uid`/`gid` 归零、权限固定（二进制 0755、文本 0644），
+  同源构建的 sha256 不受打包时刻影响。
+- **架构不靠猜**：脚本打包前回读二进制的可执行文件头（PE 机器码 / ELF `e_machine` /
+  Mach-O `cputype`），与槽位声明的架构不符即失败——交叉槽位（x64 宿主产 arm64 exe）不会
+  出现"名字是 arm64、内容还是 x64"的假产物。
+
+## 2. 版本来源（唯一真相源）
+
+版本号只有一个来源：**`Cargo.toml` 的 `[workspace.package] version`**。
+
+- `<ver>` 由 `make_artifacts.py` 通过 `cargo metadata --no-deps` 读出（不是正则扒文件），
+  任何一个 workspace member 版本不一致时直接失败。
+- 带 tag 构建时（CI）额外传 `--version "$TAG"`：脚本裁剪 `v` 后与 `Cargo.toml` 交叉校验，
+  **不一致即失败**——避免出现 tag 说 0.2.0、产物里写 0.1.0 的发布事故。
+- `ull --version` 必报同一版本（脚本打包前跑一次冒烟 `ull --version` 断言版本串在其中），
+  这是 `env!("CARGO_PKG_VERSION")` 的实际输出，不是估算。
+- 发布流程：先改 `Cargo.toml` 版本 + 提交 → `git tag v<ver>` → 推送 tag 触发流水线。
+
+## 3. 怎么构建
+
+### 本地（当前平台）
+
+```bash
+cargo build --release --locked                 # 产出 target/release/{unlucky-launcher-iced,ull}（M118：Slint 版不再进 workspace）
+cargo build --profile fast --bins              # 只是想快点看到画面/跑测试：快档（§6），产物在 target/fast/
+python packaging/make_artifacts.py --out dist  # 产物落在 dist/，含 SHA256SUMS.txt
+python packaging/make_artifacts.py --version v0.2.0   # 顺带校验版本一致性
+python packaging/make_artifacts.py --no-smoke         # 跳过 ull --version 冒烟
+```
+
+脚本按宿主自动判定槽位（Windows x64 / Windows arm64 / Linux x64 / Linux arm64 / macOS arm64 /
+macOS x64），其它组合直接报错退出——不在矩阵里的平台不出"凑合能跑"的产物。
+
+交叉构建（例如在 x64 宿主上产 Windows arm64 产物）靠两个参数把"产物根"和"槽位"显式喂进去，
+脚本不去猜宿主与产物是不是同一架构：
+
+```bash
+rustup target add aarch64-pc-windows-msvc
+cargo build --release --locked --target aarch64-pc-windows-msvc \
+  --bin unlucky-launcher-iced --bin ull   # 不用 --bins：矩阵只发 GUI + ull；GUI 的构建产物名是 iced 的 bin（M118）
+python packaging/make_artifacts.py --slot windows-arm64 \
+  --build-dir target/aarch64-pc-windows-msvc/release --out dist
+```
+
+`--slot` 与宿主槽位不一致时，`ull --version` 冒烟会**自动跳过并打印原因**（arm64 产物在 x64
+宿主机上根本执行不了；拿"跳过"当通过是假证据，所以跳过永远带原因）——那条路径的验证只能落在
+CI 真机上：`windows-arm64` 由 cross 构建产物 + M50 的 dumpbin 导入表门禁覆盖，`linux-arm64`
+由 `ubuntu-22.04-arm` 原生 runner 上真跑冒烟覆盖。
+
+### CI（四平台六槽位矩阵）
+
+`.github/workflows/release.yml`：
+
+- 触发：`push` tag `v*`；`workflow_dispatch` 只构建不发布（验证矩阵仍编得过）。
+  `inputs.prerelease` **只在 tag ref 上 dispatch 才可达**——Actions 页面的 "Run workflow" 只能选分支，
+  要跑 tag 得 `gh workflow run release.yml --ref v0.2.0`。分支 ref 的 dispatch 与 push 一样被
+  `release` job 的 `if: github.ref_type == 'tag'` 挡在发布之外，所以「dispatch 只构建不发布」
+  与「dispatch 能关 pre-release」是两条互不冲突的规则。
+- 矩阵（六槽位；`matrix.build_dir` 参数化产物根，脚本不再假设产物一定在 `target/release`）：
+  `windows-latest` x64（MSVC + `-C target-feature=+crt-static`）、`windows-latest` **交叉编译**到
+  `aarch64-pc-windows-msvc`（产物在 `target/aarch64-pc-windows-msvc/release`）、`ubuntu-22.04`
+  （glibc 2.35 地板）、`ubuntu-22.04-arm`（原生 ARM64 runner，**与 x64 同 2.35 地板**）、`macos-latest`（arm64）、
+  `macos-15-intel`（Intel x64；`macos-13` 已下线，`macos-26-intel` 为更新替位）。
+- 每个槽位 `cargo build --release --locked`（交叉槽位多两步：`rustup target add` + ARM64 库体检
+  ——查 VC 的 `lib/arm64/libcmt.lib`（`+crt-static` 靠它）与 SDK 的 `um/arm64/kernel32.lib`，
+  缺了直接给出"给 VS 加 `VC.Tools.ARM64` 或改用原生 `windows-11-arm`"的可执行提示）→
+  `make_artifacts.py --slot … --build-dir …` → 归档内容自检 → 上传 artifact。
+- `release` job：下载全部 artifact → 重算一份全量 `SHA256SUMS.txt` → 用 `packaging/release-notes.md`
+  模板渲染支持矩阵 → `gh release create`（**pre-release 默认开**：首建时 `push` 触发按 pre-release，`workflow_dispatch` 可关）。
+- **同一 tag 重跑幂等**：`gh release view` 命中已存在的 Release 时改走 `gh release upload --clobber`
+  + `gh release edit`，覆盖资产与说明而不是再 `create`（`create` 遇已存在会失败，把流水线最后一步染红）。
+- **pre-release 标记只按显式输入断言**：`gh release edit` 分支在默认重跑（`push` 触发的 Re-run，
+  `inputs.prerelease` 为空）时**不传** `--prerelease`，所以重跑**不会**翻转标记；只有 tag ref 上的
+  `workflow_dispatch` 显式给了输入才断言——`prerelease=true` → `--prerelease`，`prerelease=false` →
+  `--prerelease=false`。要改标记两条路等价且互不打架：① 走流水线
+  `gh workflow run release.yml --ref v0.2.0 -f prerelease=false`（会落到 edit 分支显式断言）
+  ② 直接 `gh release edit <tag> --prerelease=false`（不经流水线；后续默认重跑不碰该标记，
+  不会被翻回去）。首建（`create`）仍保持「pre-release 默认开」的老契约，空输入按 `true` 处理。
+
+Windows 为什么用 MSVC 静态 CRT 而不是本机这套 GNU 工具链：两者都属"标准工具链"（D21），
+但发布产物要**不依赖 VC++ 可再发行包**，`+crt-static` 把 CRT 静态链进 exe，Win10+ 的 UCRT 本身是
+系统组件，于是 exe 真正单文件可拷走。GNU 交叉产物在 CI 上还要拉 MinGW 链接器，收益为零。
+
+## 4. 每平台运行时依赖
+
+### Windows x64（Win10/11）
+
+| 依赖 | 来源 | 说明 |
+|------|------|------|
+| `KERNEL32` / `USER32` / `GDI32` / `ADVAPI32` / `SHELL32` / `ole32` / `WS2_32` … | 系统 | Win10+ 一律自带 |
+| `ucrtbase` / `api-ms-win-crt-*`（UCRT） | 系统 | Win10+ 内置，**不需要** VC++ 可再发行包 |
+| MSVC 运行时（`VCRUNTIME140` / `MSVCP140`） | **无** | `+crt-static` 静态链接，故不需要可再发行包 |
+| OpenGL（`opengl32`） | 系统 | 只在 GL 渲染路径用；缺失走软渲染 |
+
+本机（GNU 工具链）实测导入表证据见 §7。
+
+### Windows ARM64（Win11 on ARM）
+
+产物形态与门禁跟 x64 一模一样（裸 exe + 静态 CRT + dumpbin 导入表硬门禁），差别只在**怎么编**：
+CI 在 `windows-latest`（x64 宿主）上交叉编译到 `aarch64-pc-windows-msvc`，产物落在
+`target/aarch64-pc-windows-msvc/release`（由 `matrix.build_dir` 注入，脚本不硬编码路径）。
+GitHub 文档（2026）已把 `windows-11-arm` / `windows-11-vs2026-arm` 列为公开仓库**免费**的标准
+arm64 runner，原生路线可行；本流水线仍选交叉编译，因为①双 Windows 槽位共用同一套已验证镜像与
+工具链、②M50 的 dumpbin 定位链取的是 `Hostx64/x64/dumpbin.exe`（读 ARM64 PE 的导入表没问题），
+原生 ARM 宿主上那条链得再补 `Hostarm64` 分支——不为一个槽位放宽刚立的门禁。
+
+运行时依赖与 x64 同表（UCRT 是 Win11 ARM 的系统组件，`+crt-static` 静态链 CRT，不需要可再发行包）。
+游戏侧如实说：**启动器原生运行**；Temurin 没有 windows-aarch64 产物，Microsoft OpenJDK 有该
+发行版（core 的 `microsoft` 源按 `<os>-<arch>` 拼名，命名已覆盖），但 Minecraft 本体没有
+Windows ARM64 原生库（Mojang/LWJGL 只发 x64/x86），实际游玩仍走系统 x64 模拟层 + x64 JDK。
+所以本槽位只承诺「启动器产物」支持，不替 Java/游戏管理做架构级承诺。
+
+### Linux x64
+
+| 依赖 | 说明 |
+|------|------|
+| glibc ≥ 2.35 | 由 `ubuntu-22.04` 构建决定；更老的发行版请自行重建或等 musl 版 |
+| `libxkbcommon.so.0` | winit 键盘处理 |
+| `libfontconfig.so.1` + `libfreetype.so.6` | 文本渲染 |
+| `libGL.so.1` / `libEGL.so.1` | Slint 版：femtovg 的 GL 渲染；iced 版：wgpu 的 GL/EGL 后端（**推断，未实测**）。两者缺失都退到 CPU 软渲染（tiny-skia） |
+| `libxcb.so.1` / `libX11.so.6` | X11 后端（Wayland 会话下也需 XWayland 相关库） |
+| `libwayland-client.so.0` | Wayland 后端 |
+
+Debian/Ubuntu 一行：`sudo apt install libxkbcommon0 fontconfig libgl1 libegl1 libxcb1 libx11-6 libwayland-client0`。
+运行期**不需要** `-dev` 包、不需要 Java（Java 是启动游戏时才由启动器自己管理的东西）。
+
+**M118（D26）口径**：除上表里标注「推断，未实测」的那一行外，这张表与下面这条结论都是 **Slint 版 GUI** 的实测记录（M82：`readelf -d` + `ldd` + `nm -D`）；iced 版（`crates/app-iced`）的 `DT_NEEDED` / `dlopen` 集合**尚未重测**，请按「同一族库、细节待验」读，别当成 iced 版的实测承诺。
+仍然成立的部分：上表是**开窗**要用的库，不是进程启动门槛——实测（§7.4，Slint 版）除 `libfontconfig.so.1` 外它们**都不在** ELF 的 `DT_NEEDED` 里，由 `dlopen` 在开窗那一刻才加载，所以没有 X11 / Wayland / GL 的机器上 `unlucky-launcher instances list` 照样跑得起来，`ull` 连 fontconfig 都不需要。
+arm64 侧同理（同一份依赖树；历史口径里的「winit + femtovg」中 femtovg 只属于 Slint 版）。
+
+### Linux arm64（aarch64）
+
+依赖与 x64 完全同一套（`libxkbcommon` / `fontconfig` / `libGL` / `libxcb` / `libwayland-client`），
+**glibc 地板也相同**：arm64 槽位跑在原生 `ubuntu-22.04-arm` runner 上，地板 = **2.35**，与 x64
+用的 `ubuntu-22.04` 一致。选 22.04 而不是 24.04 就是为了这个地板——24.04 的 glibc 更高，会把
+Debian 12（2.36）、Raspberry Pi OS Bookworm（2.36）这些实际在跑的 ARM 发行版挡在门外。
+要抬地板（例如将来 ARM 生态整体上移）换 `release.yml` 里那个槽位的 `os` 即可，脚本与产物名都不用动；
+`ubuntu-24.04-arm` / `ubuntu-26.04-arm` 都是同一家族的标准公开仓库标签（4C/16GB、免费不限量）。
+
+### macOS 12+
+
+| 依赖 | 说明 |
+|------|------|
+| 系统框架（Cocoa / Metal / IOKit / Security …） | 由操作系统提供，无第三方动态库 |
+| `libSystem` | 系统 |
+
+macOS 产物是**裸二进制**而非 `.app` bundle：符合单文件承诺，但没有 Dock 图标、Finder 双击不生效，
+从终端启动（README 里给了 `xattr -d com.apple.quarantine` 的 Gatekeeper 解法）。
+签名/公证（需 Apple Developer 账号）与 `.app` 打包是后续工作，不做假承诺。
+
+## 5. 软渲染兜底（无 GPU / 老驱动 / 远程桌面）
+
+M118（D26）：以下是**历史实现（Slint 版，默认 `renderer-femtovg`/GL）**的兜底路径，已不在默认构建与发布矩阵内（`crates/app` 被 workspace `exclude`，源码仅作参考、不编译）。现役 GUI 是 iced 版：`unlucky-launcher-iced --software-renderer`（= `ICED_BACKEND=tiny-skia`）走 tiny-skia 光栅化。v0.1.0 的产物仍认下面两条：
+
+```bash
+unlucky-launcher --software-renderer                     # 启动参数（本仓库解析后设 SLINT_BACKEND）
+SLINT_BACKEND=winit-software unlucky-launcher            # 环境变量（Slint 原生开关）
+```
+
+- 参数解析在 `crates/app/src/main.rs` 的 `apply_renderer_flag()`，只认完全相等的 `--software-renderer`。
+- 软渲染是 CPU 光栅化，无 GPU 也能出图；代价是动画与大窗口重绘更慢（Metro 纯色界面影响有限）。
+- 截图通道 `--screenshot <png>`：历史实现 `crates/app/src/screenshot.rs`，现役 `crates/app-iced/src/shot/`；
+  软渲染下照样出图，是 CI 与远程机唯一可靠的"真出图"证据（发布冒烟见 §7，本机实跑 `--software-renderer --screenshot`）。
+
+## 6. Cargo 构建档位（release 体积档 / fast 速度档）
+
+| 档位 | 用在哪 | opt-level | lto | codegen-units | panic |
+|------|--------|-----------|-----|---------------|-------|
+| `release` | 发布 / 验收产物 | `"z"`（workspace 自身 crate） | `fat` | 1 | `abort` |
+| `release.package."*"` | 同上，**只作用于依赖** | `"z"` | 不可覆盖 | 16 | 继承 |
+| `fast` | 日常迭代、本机跑测试 | 2 | `thin` | 16 | `unwind` |
+
+- **`release` 是体积档**：`fat` + 单 CGU 换来实测 GUI −10.8% / CLI −18.7%（§7.1）。变慢的根源在 `codegen-units = 1`
+  （单 CGU → LTO 只一个线程可跑；`fat` 只管"跨 crate 全量参与"，不等于单线程），375 个 crate 排队链接就是十几分钟的量。
+- **`release.package."*"` 放宽的只有并行度，不是 opt-level**：实测把依赖 opt-level 抬到 3 反而**又慢 29.6%
+  又大 19~24%**（§7.1），所以保持 `"z"`、只把 `codegen-units` 放到 16。package 覆盖**只允许调优化强度**：
+  `panic` / `lto` / `rpath` 写进去 cargo 直接报错，`strip` 会改变整个二进制的运行时行为——都不许出现。
+- **`fast` 是速度档，不是发布物**：`thin` LTO + 16 CGU 可并行，`opt-level = 2` 介于 `z` 与 3 之间。
+  `panic = "unwind"` 是给**编出来的二进制**留的（`release` 是 `abort`，`inherits` 会照抄）；`cargo test`
+  **不**依赖它——cargo 对 test 目标自己强制 unwind（实测 release/abort 档下 `cargo test --profile release`
+  照跑、23 个测试全过，test 单元的 rustc 参数里没有 `-Cpanic=`）。要看这行是否生效，比 `cargo build -v`
+  的 rustc 参数：release 有 `panic=abort`、fast 没有。它继承 `strip="symbols"`，所以能 unwind 但**没有符号
+  回溯**——要栈回溯就给 fast 档加 `strip = false`，代价是体积再涨。
+- **`fast` 在机械盘机器上冷编译并无收益**（比 release 还慢、体积 2.3 倍，§7.1），价值在 SSD 机器与增量重编。
+- **`[profile.fast.package."*"]` 是承重墙**：`inherits` 会把 release 的 package 覆盖一起带过来（实测：删掉它，fast 档外部依赖静默退回 `"z"`），必须存在。
+- 本地开发迭代走 `cargo build`（dev profile）不受影响，但 **`ci.yml` 每次 push/PR 都跑
+  `cargo build --workspace --release`**，会实打实吃这份 fat LTO 的链接时间——CI 慢的一部分是 release 档构建。
+
+## 7. 实测（本机，不是估算）
+
+构建环境：rustc 1.99.1 stable / `x86_64-pc-windows-gnu`（MinGW 链接器）。§7.2/§7.3 的早数字是另有 worker 并发做全量 debug 构建时测的（偏悲观）；§7.1 的三行 M96 数据是空载冷编译。
+
+**本节以下所有输出里的 `0.1.0` 都是当时那次运行的真实输出（workspace 版本那时是 `0.1.0`），属实测记录，不随后续版本号改动而回填**；当前版本见 `Cargo.toml` 的 `[workspace.package] version`。§2 的校验机制不依赖任何写死的数字，改版本号不会让它失效。
+
+### 7.1 体积与冷构建耗时（实测字节数，不是估算）
+
+| 档位 | `unlucky-launcher.exe` | `unlucky-launcher-iced.exe` | `ull.exe` | 冷构建耗时 |
+|------|-----------------------|----------------------------|-----------|-----------|
+| `release`，`thin`（M46 前） | 16,366,080 B = 15.61 MiB | 未测（当时无 iced 版） | 7,572,992 B = 7.22 MiB | 11m52s |
+| `release`，`fat`，依赖全 `"z"`（M46，改前） | **14,595,584 B = 13.92 MiB** | 未测 | **6,157,824 B = 5.87 MiB** | 9m27s（增量） |
+| `release`，`fat` + 依赖 opt-3 / cu16（M96 试过的那版，**已否**） | 20,407,296 B = 19.46 MiB | 18,371,584 B = 17.52 MiB | 7,743,488 B = 7.38 MiB | 22m45s（冷） |
+| `release`，`fat` + 依赖 `"z"` / cu16（**M96 起，发布档**） | **16,479,232 B = 15.72 MiB** | **13,910,528 B = 13.27 MiB** | **6,256,128 B = 5.97 MiB** | **16m01s（冷）** |
+| `fast`，`thin` + cu16（M96 起，日常档） | 38,182,400 B = 36.41 MiB | 33,570,304 B = 32.02 MiB | 15,967,744 B = 15.23 MiB | 24m27s（冷） |
+
+测量条件（M96 三行）：12 核 / `x86_64-pc-windows-gnu` / `-j 4`，源码机械盘、`CARGO_TARGET_DIR` 在 SSD，均为**删空 target 后的
+冷编译**、同机同晚无并发负载；M46 两行是更早提交上的数字（依赖已热 / 另有并发），**跨行比耗时没意义**。
+① **依赖 opt-level 从 3 退回 `"z"` 又快 29.6% 又小 19~24%**（两臂同为 cu16，唯一自变量是 opt-level）——抬 opt-level 是拿编译时间和体积换运行期；
+`cu1 → cu16` 的收益本轮**没有同条件对照**，未归因。② `fast` **冷编译比 `release` 还慢**（24m27s vs 16m01s）、体积 2.3 倍，瓶颈在两个大 UI
+crate + 链接 + 机械盘 IO——定位是 **SSD 机器与增量重编**，不是冷编译加速。体积归因：GUI 相对旧基线 +12.9%（13.92 → 15.72 MiB）里
+「代码增长」与「依赖 cu16」**未分离**；`ull` 只 +1.7%，在 +1~3% 口径内。体积构成（**M118 前的 Slint 版，历史数**）：Slint 运行时（双渲染器 + winit/accesskit/托盘）+ rustls/reqwest + rig/rmcp/axum 为主，`ull` 更小是 D18（CLI 零 UI 依赖）的结果。
+
+### 7.2 冒烟（真跑，2026-10-31 夜间 + 11-01 早，本机 Win11 26100）
+
+| 命令 | 实测结果 |
+|------|---------|
+| `ull.exe --version` | 输出 `ull 0.1.0（unlucky-cli）` + `os: Windows 11 · 10.0.26100（x86_64）· 满足最低要求`，exit 0 —— 版本与 workspace `0.1.0` 一致 |
+| `unlucky-launcher.exe --software-renderer --screenshot … --data-dir …`（Slint 版，历史实测） | exit 0，产出 1180×760 PNG（3,588,298 B）；看图确认 Metro 实例页（侧栏/搜索/空态/AI 助手面板）正常渲染 → **软渲染路径真的能出图**，不依赖 GL |
+| `unlucky-launcher.exe --version` | **无输出**，8 秒后被 timeout 杀掉（exit 124）——GUI 当时不解析 `--version`，会直接开窗口。M82 后已修（走 CLI 分发，见 §10-1）|
+
+### 7.3 打包验证（本机 Windows 槽位真跑）
+
+```
+smoke: ull.exe --version -> 0.1.0 (ok)
+artifact: unlucky-launcher-0.1.0-windows-x64.exe  13.92 MiB  sha256=d4954c62…c3570
+sums:     SHA256SUMS.txt
+$ sha256sum -c SHA256SUMS.txt
+unlucky-launcher-0.1.0-windows-x64.exe: OK
+```
+
+版本守卫也实测过：`--version v9.9.9` 时脚本以 `tag/version mismatch: requested 9.9.9, Cargo.toml says 0.1.0` 失败退出（exit 1）。
+
+UNIX 归档的可复现性单独取证（本机 Windows 槽位只走裸 exe 分支，tar 路径要另测）：
+reviewer-packaging 在 M46 review 里连续调 `stage_archive()` 两次 → **两次 sha256 完全一致**
+`a99d6e9e727cd7e390434c566a15978451f340858fa89836e2f63790bbc392f8`；成员 `mtime=0`、
+`uid=gid=0`、`uname/gname` 为空、`mode` 0755（二进制）/ 0644（文本），gzip header 的 mtime 字段是
+`00000000`，归档内单顶层目录且含 `LICENSE`/`NOTICE`/`README.md`。
+即"同源构建 → 同 sha256"在 tar 路径上成立，不随打包时刻漂移（见 §1 的约定细节）。
+
+### 7.4 运行时依赖证据（PE 导入表 / ELF `DT_NEEDED`）
+
+`objdump -p target/release/unlucky-launcher.exe` 共 42 条 DLL 导入记录、33 个不同名字（大小写各记一次），全部是 Windows 自带：
+`KERNEL32/USER32/GDI32/ADVAPI32/SHELL32/SHLWAPI/ole32/oleaut32/combase/comctl32/dwmapi/dwrite/imm32/
+uxtheme/uiautomationcore/opengl32/ws2_32/bcrypt/bcryptprimitives/ntdll` + 一组 `api-ms-win-crt-*`（UCRT API set）。
+
+**没有** `VCRUNTIME140.dll` / `MSVCP140.dll` 这类 MSVC 可再发行包依赖，也没有 `libwinpthread-1.dll` /
+`libgcc_s_*.dll` 之类 MinGW 运行时 —— 即"拷走一个 exe 就能跑"（Win10+ 自带 UCRT）。
+CI 的 MSVC `+crt-static` 产物同理（静态 CRT）；`release.yml` 里用 `dumpbin -dependents` 把这条变成硬门禁，
+两侧都 fail、没有降级分支：**出现 VCRUNTIME/MSVCP/ucrtbase 就 fail**，**找不到 dumpbin 同样 fail**
+（`windows-latest` 自带 VS 工具链，基本找得到；"找不到就跳过"等于让门禁在最需要它的时候失效）。
+总之不允许"悄悄要用户装可再发行包"。
+注意：本机只装了 GNU 工具链，MSVC 那个槽位的产物本身**没有在本机验证过**，由 CI 首跑验证。
+
+Linux 侧同一件事的对照（M82 实测：`readelf -d` + `ldd` + `nm -D`，容器内 Debian 12 glibc 2.36；被测的是 **Slint 版 GUI，历史实测**）：Slint
+GUI 的 ELF `DT_NEEDED` 只有 `libfontconfig.so.1` / `libgcc_s.so.1` / `libm.so.6` / `libc.so.6` /
+`ld-linux-x86-64.so.2`；`libX11` / `libxcb` / `libxkbcommon` / `libwayland-client` / `libGL` / `libEGL`
+**都不在**导入表里，而是以字符串形式由 `dlopen` 在开窗那一刻加载（`nm -D` 可见 `U dlopen@GLIBC_2.34` /
+`dlsym` / `dlclose`）。所以 §4 那张「开窗要的库」不是启动前提，缺了也不影响进程起来跑 CLI；
+`ull` 的 `DT_NEEDED` 连 fontconfig 都没有，只剩 glibc 那一组。
+
+**补一次真跑（M82 复审在 `debian:bookworm-slim` 上做的）**：镜像里 X11 / wayland / GL / EGL / xkbcommon /
+libxcb 条目数 = 0，只把 fontconfig 那 7 个 `.so` 放进 `LD_LIBRARY_PATH`，跑**改动后**的二进制 → `--version`
+与 `--help` exit 0、`instances list --json` 合法 JSON exit 0、`lst` exit 1 且带提示；`readelf -d` 复核仍是
+恰好 5 条 `DT_NEEDED`（无 `libstdc++`、无任何图形库），`ull` 4 条 —— 即「能跑完子命令」是实测，不是推论。
+
+### 7.5 arm64 槽位的本机验证（脚本层取证，不假装跑得动 arm64 二进制）
+
+本机没有 ARM 机器，也不具备 MSVC ARM64 链接库组合，所以只做**能真实证明的东西**（`python` 直接加载
+`packaging/make_artifacts.py` 调函数 + 走 CLI 全流程，证据见下）：
+
+| 取证项 | 结果 |
+|--------|------|
+| 宿主判定注入 | `win32/AMD64`→`windows-x64`、`win32/ARM64`→`windows-arm64`、`linux/x86_64`→`linux-x64`、`linux/aarch64`→`linux-arm64`、`linux/arm64`→`linux-arm64`、`darwin/arm64`→`macos-arm64`、`darwin/x86_64`→`macos-x64`、`freebsd/riscv64`→exit 1 |
+| 文件头架构识别 | 真 `unlucky-launcher.exe`→`x64`；合成 PE `0xAA64`→`arm64` / `0x8664`→`x64`；ELF `0xB7`→`arm64` / `0x3E`→`x64`；Mach-O `0x0100000C`→`arm64` / `0x01000007`→`x64`；垃圾字节→`None`（拒绝出包） |
+| `windows-arm64` stub 全流程 | 把真 exe 的 PE 机器码改成 ARM64 当 stub：`arch: … -> arm64 (ok for windows-arm64)`、`smoke: skipped (host is windows-x64, artifact is windows-arm64)`、产物 `unlucky-launcher-0.1.0-windows-arm64.exe` 14.01 MiB，`SHA256SUMS.txt` 行名一致 |
+| 架构守卫真拦 | x64 二进制冒充 `--slot windows-arm64` → exit 1：`is a x64 binary but slot windows-arm64 says arm64` |
+| `linux-arm64` stub 归档 | 成员 `unlucky-launcher-0.1.0-linux-arm64/{LICENSE,NOTICE,README.md,unlucky-launcher}`，权限 0644/0755、`uid=gid=0`、mtime 0、gzip 头 mtime 字段 `00 00 00 00`；连调两次 sha256 完全一致（`f949d0f5…`）→ 可复现规则与 x64 同源 |
+| `windows-x64` 原生回归 | `arch: … -> x64`、`smoke: ull.exe --version -> 0.1.0 (ok)`、产物 14.01 MiB、`sha256sum -c SHA256SUMS.txt` OK（这一次用的是当前工作树的二进制，与 §7.3 那次不是同一次构建，sha256 自然不同） |
+
+**没在本地验证、只能由 CI 补的**：`windows-arm64` 的交叉链接与真实 ARM64 导入表、`linux-arm64` 在
+原生 arm64 runner 上的真跑。本机连 `raw.githubusercontent.com` 都解析不了，所以 runner 镜像里到底装没装
+ARM64 的 MSVC 库**没法在这里查证**——`release.yml` 为此加了一道链接前的体检（查 `libcmt.lib` 与
+`um/arm64/kernel32.lib`，缺了直接给"加 `VC.Tools.ARM64` 组件或改原生 runner"的提示），首跑即见分晓。
+merge 后由 tower 重指 tag 重跑流水线，两槽位进 `SHA256SUMS.txt` 即算闭环。
+
+## 8. 发行合规
+
+- `LICENSE`（Apache-2.0 全文）与 `NOTICE`（含 Slint Royalty-Free 2.0 义务说明）随包分发，
+  三份文本在 UNIX 归档内、在 Windows 侧作为并列 Release 资产。
+- Slint 的 RF 2.0 义务：关于页保留 `AboutSlint` 部件（已在 UI 内），不得移除；
+  选 RF 分支即不触发 GPL 分支义务（见 `deny.toml` 的许可证白名单注释）。
+- **M118 后这条义务只跟着已发布的 `v0.1.0` 资产走**：`crates/app` 已被 workspace `exclude`，发布矩阵里再没有链接 Slint 的二进制，新的 iced 版产物不链接 Slint；`deny.toml` 那条 RF-2.0 allow 因此暂时是死条目（不删，留给将来真有别的路径引入 Slint 时兜底）。
+- `README.md`（英文主版）随包分发；中文版 `README.zh-CN.md` 留在仓库不进包（避免包体噪音）。
+- 依赖许可门禁不变：`deny.toml` 白名单（Apache-2.0 / MIT / BSD / Zlib / BSL-1.0 / ISC / CC0 / Unlicense /
+  Unicode-3.0 / CDLA-Permissive-2.0 / Slint-RF-2.0）。发布任务不新增任何依赖。
+- 发布产物不含游戏本体、不含 JRE、不含任何账号数据；`ull`/GUI 的数据目录在用户侧生成。
+
+## 9. 支持矩阵（对外口径，与 release-notes 模板逐行一致）
+
+| 平台 | 级别 | 运行时要求 |
+|------|------|-----------|
+| Windows 10/11 x64 | 一等 | 无（UCRT 系统自带） |
+| Windows 11 ARM64 | 一等（启动器产物） | 无额外库；启动器原生运行，游戏本体走系统 x64 模拟层 + x64 JDK |
+| macOS 12+（arm64 / x64） | 一等 | 无第三方库；未签名需去 quarantine |
+| Linux x64 X11 | 一等 | glibc 2.35+、xkbcommon、fontconfig、libGL、xcb |
+| Linux x64 Wayland | 支持 | 上述 + wayland-client |
+| Linux arm64 X11 | 一等 | glibc 2.35+（`ubuntu-22.04-arm` 原生构建，**与 x64 同地板**）、xkbcommon、fontconfig、libGL、xcb |
+| Linux arm64 Wayland | 支持 | 上述 + wayland-client |
+| Windows 8.1/8/7 | 不支持 | 基线已上调（D21） |
+| Android Termux + X11 | 试验级（不承诺） | 仅 CLI（源码自建），GUI 未验证，不在本发布矩阵内 |
+
+`packaging/release-notes.md` 的 "Support matrix" 表与上表逐行对应（英文版，Termux 行同样标注
+experimental / not part of this release matrix）——改一边必须同步另一边，否则标题里的"一致"就是假话。
+
+两个 arm64 槽位都是**正式发布槽位**（产物进 Release、进 `SHA256SUMS.txt`、release job 的六槽位齐全性
+检查会拦下缺失），不要跟 Termux 那行混为一谈：Termux 是"源码自建的实验级旁路"，Linux arm64 是
+"原生 runner 编、原生跑"的一等产物。
+
+## 10. 已知边界 / 后续
+
+1. **GUI 的 `--version` 已解决**（M82）：`unlucky-launcher --version` 现在命中子命令分发，输出与
+   `ull --version` 同一条版本 + 系统摘要后退出，不再开窗。§7.2 里「无输出、8 秒后被 timeout 杀掉」那行
+   是**改之前**的实测记录，留作对照。版本自证的另外两条（产物名里的 `<ver>`、tag 交叉校验）不变。
+2. **签名/公证**：Windows 无 Authenticode、macOS 无 codesign/notarize（都要证书/开发者账号），
+   当前以 SHA256SUMS + Release 说明作为完整性参考。
+3. **macOS `.app` bundle / `.dmg`**：与单文件承诺冲突，暂不做；若用户要 Dock 图标再单开 mission。
+4. **Linux musl 静态版**：可彻底摆脱 glibc 地板，但 Slint 在 musl 上需额外验证，未纳入本矩阵。
+5. **`ull` 已随包**（M82 起）：每个槽位与 GUI 并列发一份裸 `ull`，进同一份 `SHA256SUMS.txt`，矩阵
+   完整性检查按「GUI 与 CLI 各自都要有」分开查（`release.yml`）。等 CI 首跑确认这条在真流水线上有效。
+6. **本机 GNU 链接器的已知无害告警**：`cargo build --release`（GNU 工具链）会打一行
+   `warning: linker stderr: corrupt .drectve at end of def file`，来自 MinGW `ld` 对 `.drectve` 段的
+   老式抱怨，不影响产物（体积/导入表/冒烟均已实测正常）；CI 的 MSVC 槽位不会出现这条。
+7. **两个 arm64 槽位本机跑不了**：本机是 x64 Windows，既没有 ARM 机器也没有 MSVC 的 ARM64 链接库
+   组合，`windows-arm64` / `linux-arm64` 的**真实产物只能由 CI 出**：前者靠 `dumpbin -dependents`
+   的静态 CRT 门禁 + 架构校验，后者在 `ubuntu-22.04-arm` 上真跑 `ull --version` 冒烟。
+   本机能做且已做的是脚本层取证（见 §7.5）：宿主判定注入（`win32/ARM64`、`linux/aarch64` 等全槽位）、
+   可执行文件头架构识别（真 x64 exe + 合成 PE/ELF/Mach-O 头）、以及把真 exe 的 PE 机器码改成 ARM64
+   当 stub 走完命名/校验/归档全流程 —— 不假装能在 x64 上执行 arm64 二进制。
+8. **M82 的体积/首帧没重量**：改的时候本机三个 worker 同时在编（全量 release profile 要 400+ crate），
+   这两个数留给空闲窗口补。结构性判断（**不是实测**）：分发发生在 `MainWindow::new()` 与后端探测之前，
+   GUI 路径只多一次 argv 解析，所以首帧成本没有增加的理由；CLI 路径的耗时则天然与首帧无关。
+
+## 11. CI 运行时冒烟（Linux 真渲染一帧）
+
+**细节与依据在 [`packaging/ci-runtime-smoke.md`](ci-runtime-smoke.md)**（本节再增长也往那里写，两个文件都必须 ≤400 行）。
+
+`ci.yml` 的 `runtime-smoke` job 在 `ubuntu-latest` 上补第一份**真实图形环境**运行证据：装 `xvfb` + 软渲染
+依赖 + 字体，用 `xvfb-run` 起 GUI 进程，走既有进程内截图通道渲出一帧 PNG，再对**像素本身**断言
+（退出码 0 / PNG 尺寸 / 非空白三项，artifact `runtime-smoke-screenshot`）。
+
+要点三条：
+
+- 只看退出码不够：PNG 是进程自己编码写出的，「合法 PNG + 退出码 0」不等于画面有内容，像素断言是纵深防御；
+  而「完全没有字体」与「非软渲染」这两种失效都是**硬失败**（panic / 报错，不产生 PNG；review 实测），运行步就红。
+- 闸门下限 ≈「至少画出一条标题栏」（review 实测切片仍 pass）：证明「场景被真实渲染过」，**不证明界面元素齐全，
+  更不证明视觉正确**——视觉靠人眼看 artifact。
+- 只覆盖 Linux x64；macOS 是 dispatch-only 探针（无实测证据），Windows 已有本机人眼验收。
+
+**本地复跑**：`bash packaging/linux-smoke-docker.sh . D:/tmp/ull-smoke`（输出目录别写 `/tmp`，Git Bash 下会静默落进 Docker VM；脚本内部用 `cygpath -m` 归一并回显真实路径）。**M118 提醒**：该脚本仍按 Slint 版 bin `unlucky-launcher` 编译与启动（`linux-smoke-docker.sh:81/83/88`），而 `crates/app` 已被 workspace `exclude`，**这条命令现在会失败**。
+在它把 bin 换成 `unlucky-launcher-iced` 之前，本地要复刻请直接照 `ci.yml` 的 runtime-smoke 三步手跑：`cargo build --bin unlucky-launcher-iced --locked` → `xvfb-run … --software-renderer --screenshot <png> --data-dir <dir>` → `python3 packaging/check_screenshot.py <png> --json`。
+
+## 12. 文件清单
+
+| 文件 | 作用 | 行数上限 |
+|------|------|---------|
+| `packaging/README.md` | 本文：矩阵/依赖/版本/合规契约 | ≤400 |
+| `packaging/make_artifacts.py` | 打包与校验（本地 + CI 共用） | ≤400 |
+| `packaging/release-notes.md` | GitHub Release 说明模板（`{{VERSION}}` / `{{SUMS}}` 占位） | ≤400 |
+| `packaging/check_screenshot.py` | 截图非空白判定（CI 门禁 + 本地手动跑，零第三方依赖） | ≤400 |
+| `packaging/ci-runtime-smoke.md` | §11 的细节：断言口径/阈值依据/失效模式/复跑 | ≤400 |
+| `packaging/linux-smoke-docker.sh` | 本地复跑 `runtime-smoke`（Docker + xvfb） | ≤400 |
+| `.github/workflows/release.yml` | tag 触发 → 矩阵构建 → Release | ≤400 |
diff --git a/packaging/check_screenshot.py b/packaging/check_screenshot.py
new file mode 100644
index 0000000..4f02b7f
--- /dev/null
+++ b/packaging/check_screenshot.py
@@ -0,0 +1,317 @@
+#!/usr/bin/env python3
+"""截图「不是一帧空白」判定：CI 运行时冒烟的门禁脚本（零第三方依赖）。
+
+为什么需要它：`--screenshot` 的 PNG 是进程自己编码写出的，只要流程走到 `take_snapshot` 就会得到
+「合法 PNG + 退出码 0」；像素断言是**纵深防御**，守的是「进程活着、写出合法 PNG，但场景几乎没画」这一档。
+本机可复现的两种失效都是硬失败（运行步就红，不必等像素断言）：①完全没有字体 → fontique panic
+（退出码 101，不产生 PNG）；②不是软渲染（默认 femtovg）→ `take_snapshot is not supported by this
+FemtoVG backend`（退出码 1）。其余「渲染器出图但内容没上去」的情形本机暂无样本，属防御性设计。
+
+三个判据（阈值依据见 `--selftest` 与 packaging/ci-runtime-smoke.md）：
+
+- `unique_colors`：唯一色数。全白 / 全黑图 = 1；真实 UI 数百到上千。
+- `luma_stddev`：亮度标准差。纯色图 = 0；真实 UI 有面板/文字/渐变的明暗层次。
+- `edge_ratio`：**强边缘像素占比**——水平相邻像素对里亮度差 ≥8 的比例。纯色图 = 0；真实 UI 的文字与
+  边框占千分之几到百分之几。用它而不是「平均亮度差」：空数据目录的主界面 57% 是同一片底色，
+  平均差会被大片平面稀释（实测只有 0.4），而强边缘占比只数真正的边界，跨主题/跨字体都稳定。
+
+只用 Python 标准库：`zlib` 解压 PNG 的 deflate 流，自己反过滤（filter 0~4）。
+不引 Pillow 是因为 CI 不该为了「看一张图」多装一套图像栈（也符合项目的依赖白名单纪律）。
+
+用法::
+
+    python packaging/check_screenshot.py shot.png            # 判定，退出码 0/1
+    python packaging/check_screenshot.py shot.png --json     # 机器可读（CI 日志用）
+    python packaging/check_screenshot.py --selftest          # 打印阈值依据的两组数值
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import struct
+import sys
+import tempfile
+import zlib
+from collections import Counter
+from pathlib import Path
+
+PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
+
+# 判定阈值。两侧数值实测（M62 本机 Docker + xvfb + Windows 历史截图）：
+# - 真实帧：唯一色 342~2352、亮度σ 19.45~27.46、强边缘占比 0.0076~0.0433（最弱是 Linux 空数据主界面）；
+# - 人为纯色帧：1 / 0.0 / 0.0。
+# 阈值取在两者之间、贴近真实下限的 1/5~1/8：换主题/换字体/换窗口尺寸都不会误报，空白帧一定红。
+DEFAULT_MIN_UNIQUE = 64
+DEFAULT_MIN_STDDEV = 3.0
+DEFAULT_MIN_EDGE_RATIO = 0.001
+
+# 「强边缘」的亮度差门槛：≥8/255 肉眼即视为一条边界；抗锯齿造成的 1~2 级抖动不算。
+EDGE_LUMA_DELTA = 8
+
+# PNG 颜色类型 → 每像素通道数（调色板 3 走索引，需要 PLTE，本脚本不解）
+CHANNELS_BY_COLOR_TYPE = {0: 1, 2: 3, 4: 2, 6: 4}
+
+
+class PngError(Exception):
+    """PNG 结构不受支持或损坏。"""
+
+
+def _iter_chunks(data: bytes):
+    """按 PNG 规范切块：长度(4) + 类型(4) + 数据 + CRC(4)。"""
+    offset = len(PNG_SIGNATURE)
+    while offset + 12 <= len(data):
+        (length,) = struct.unpack(">I", data[offset : offset + 4])
+        yield data[offset + 4 : offset + 8], data[offset + 8 : offset + 8 + length]
+        offset += 12 + length
+
+
+def _unfilter(kind: int, line: bytearray, prev: bytearray, bpp: int) -> None:
+    """就地把一条扫描线反过滤（PNG 规范 §9.2 的五个过滤类型）。"""
+    if kind == 0:
+        return
+    if kind == 1:  # Sub：加上左边
+        for index in range(bpp, len(line)):
+            line[index] = (line[index] + line[index - bpp]) & 0xFF
+    elif kind == 2:  # Up：加上正上方
+        for index in range(len(line)):
+            line[index] = (line[index] + prev[index]) & 0xFF
+    elif kind == 3:  # Average：加上 (左 + 上) // 2
+        for index in range(len(line)):
+            left = line[index - bpp] if index >= bpp else 0
+            line[index] = (line[index] + ((left + prev[index]) >> 1)) & 0xFF
+    elif kind == 4:  # Paeth：加上 Paeth 预测子
+        for index in range(len(line)):
+            left = line[index - bpp] if index >= bpp else 0
+            up = prev[index]
+            upper_left = prev[index - bpp] if index >= bpp else 0
+            estimate = left + up - upper_left
+            dist_left = abs(estimate - left)
+            dist_up = abs(estimate - up)
+            dist_corner = abs(estimate - upper_left)
+            if dist_left <= dist_up and dist_left <= dist_corner:
+                predictor = left
+            elif dist_up <= dist_corner:
+                predictor = up
+            else:
+                predictor = upper_left
+            line[index] = (line[index] + predictor) & 0xFF
+    else:
+        raise PngError(f"未知的行过滤类型 {kind}")
+
+
+def decode_png(path: Path) -> tuple[int, int, list[bytearray], int]:
+    """读 8bit 非隔行 PNG，返回 (宽, 高, 每行原始字节, 通道数)。"""
+    data = path.read_bytes()
+    if not data.startswith(PNG_SIGNATURE):
+        raise PngError(f"{path} 不是 PNG（签名不符，可能是 0 字节文件或半截写入）")
+
+    width = height = depth = color_type = interlace = None
+    compressed = bytearray()
+    for kind, body in _iter_chunks(data):
+        if kind == b"IHDR":
+            width, height, depth, color_type, _, _, interlace = struct.unpack(">IIBBBBB", body)
+        elif kind == b"IDAT":
+            compressed.extend(body)
+        elif kind == b"IEND":
+            break
+
+    if width is None or height is None:
+        raise PngError("缺 IHDR 块")
+    if interlace:
+        raise PngError("不支持隔行（Adam7）PNG")
+    if depth != 8:
+        raise PngError(f"只支持 8bit PNG，实际 {depth}bit")
+    channels = CHANNELS_BY_COLOR_TYPE.get(color_type)
+    if channels is None:
+        raise PngError(f"不支持的颜色类型 {color_type}（调色板 PNG 请先转成 RGB/RGBA）")
+
+    raw = zlib.decompress(bytes(compressed))
+    stride = width * channels
+    if len(raw) < (stride + 1) * height:
+        raise PngError(f"像素数据不足：期望 {(stride + 1) * height} 字节，实际 {len(raw)}")
+
+    rows: list[bytearray] = []
+    previous = bytearray(stride)
+    offset = 0
+    for _ in range(height):
+        kind = raw[offset]
+        offset += 1
+        line = bytearray(raw[offset : offset + stride])
+        offset += stride
+        _unfilter(kind, line, previous, channels)
+        rows.append(line)
+        previous = line
+    return width, height, rows, channels
+
+
+def measure(width: int, height: int, rows: list[bytearray], channels: int) -> dict:
+    """统计「这帧图里有没有信息」的三项指标。"""
+    colors: Counter[int] = Counter()
+    luma_sum = 0
+    luma_square_sum = 0
+    strong_edges = 0
+    pair_count = 0
+
+    for row in rows:
+        previous_luma = None
+        for x in range(width):
+            base = x * channels
+            if channels >= 3:
+                red, green, blue = row[base], row[base + 1], row[base + 2]
+            else:
+                red = green = blue = row[base]
+            colors[(red << 16) | (green << 8) | blue] += 1
+            # 整数亮度（ITU-R BT.601 系数），避免浮点误差影响阈值比较
+            luma = (red * 299 + green * 587 + blue * 114) // 1000
+            luma_sum += luma
+            luma_square_sum += luma * luma
+            if previous_luma is not None:
+                pair_count += 1
+                if abs(luma - previous_luma) >= EDGE_LUMA_DELTA:
+                    strong_edges += 1
+            previous_luma = luma
+
+    total = width * height
+    mean = luma_sum / total if total else 0.0
+    variance = max(luma_square_sum / total - mean * mean, 0.0) if total else 0.0
+    top_color, top_count = colors.most_common(1)[0] if colors else (0, 0)
+    return {
+        "width": width,
+        "height": height,
+        "pixels": total,
+        "unique_colors": len(colors),
+        "top_color": f"#{top_color:06x}",
+        "top_color_share": round(top_count / total, 4) if total else 0.0,
+        "luma_mean": round(mean, 2),
+        "luma_stddev": round(math.sqrt(variance), 2),
+        "edge_ratio": round(strong_edges / pair_count, 5) if pair_count else 0.0,
+    }
+
+
+def verdict(
+    stats: dict, min_unique: int, min_stddev: float, min_edge_ratio: float
+) -> list[str]:
+    """把指标折成「失败原因清单」；空清单 = 通过。"""
+    problems = []
+    if stats["pixels"] <= 0:
+        problems.append("图像尺寸为 0（宽或高是 0）")
+        return problems
+    if stats["unique_colors"] < min_unique:
+        problems.append(
+            f"唯一色数 {stats['unique_colors']} < 阈值 {min_unique}（像纯色/空白帧）"
+        )
+    if stats["luma_stddev"] < min_stddev:
+        problems.append(
+            f"亮度标准差 {stats['luma_stddev']} < 阈值 {min_stddev}（整帧明暗无层次）"
+        )
+    if stats["edge_ratio"] < min_edge_ratio:
+        problems.append(
+            f"强边缘占比 {stats['edge_ratio']} < 阈值 {min_edge_ratio}（没有边界/文字的迹象）"
+        )
+    return problems
+
+
+def encode_png(width: int, height: int, rgb_row) -> bytes:
+    """最小 PNG 编码器（8bit RGB、filter 0、zlib 压缩）——只给 `--selftest` 造样图。"""
+    raw = bytearray()
+    for y in range(height):
+        raw.append(0)
+        raw.extend(rgb_row(y))
+    out = bytearray(PNG_SIGNATURE)
+    for kind, body in (
+        (b"IHDR", struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0)),
+        (b"IDAT", zlib.compress(bytes(raw), 6)),
+        (b"IEND", b""),
+    ):
+        out.extend(struct.pack(">I", len(body)))
+        out.extend(kind)
+        out.extend(body)
+        out.extend(struct.pack(">I", zlib.crc32(kind + body) & 0xFFFFFFFF))
+    return bytes(out)
+
+
+def selftest() -> int:
+    """造两张对照样图跑一遍，打印阈值依据的两组数值。
+
+    - 全白 / 全黑：模拟「窗口起来了但一个像素都没画」的空白帧；
+    - 一像素黑边框 + 中部一条横线：最弱的「有内容」下限（远弱于真实 UI）。
+    """
+    width, height = 1180, 760
+    cases = {
+        "flat-white": lambda y: b"\xff" * (width * 3),
+        "flat-black": lambda y: b"\x00" * (width * 3),
+        "border-line": lambda y: b"".join(
+            b"\x00\x00\x00"
+            if (y in (0, height - 1) or x in (0, width - 1) or y == height // 2)
+            else b"\xff\xff\xff"
+            for x in range(width)
+        ),
+    }
+    with tempfile.TemporaryDirectory() as tmp:
+        for name, describe in cases.items():
+            path = Path(tmp) / f"{name}.png"
+            path.write_bytes(encode_png(width, height, describe))
+            stats = measure(*decode_png(path))
+            failed = verdict(
+                stats, DEFAULT_MIN_UNIQUE, DEFAULT_MIN_STDDEV, DEFAULT_MIN_EDGE_RATIO
+            )
+            print(
+                json.dumps(
+                    {
+                        "case": name,
+                        "unique_colors": stats["unique_colors"],
+                        "luma_stddev": stats["luma_stddev"],
+                        "edge_ratio": stats["edge_ratio"],
+                        "verdict": "fail" if failed else "pass",
+                    },
+                    ensure_ascii=False,
+                )
+            )
+    return 0
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description="截图非空白判定（CI 运行时冒烟门禁）")
+    parser.add_argument("png", nargs="?", type=Path, help="待判定的 PNG 路径")
+    parser.add_argument("--json", action="store_true", help="以 JSON 输出统计结果")
+    parser.add_argument("--min-unique", type=int, default=DEFAULT_MIN_UNIQUE, help="唯一色数下限")
+    parser.add_argument("--min-stddev", type=float, default=DEFAULT_MIN_STDDEV, help="亮度标准差下限")
+    parser.add_argument(
+        "--min-edge-ratio", type=float, default=DEFAULT_MIN_EDGE_RATIO, help="强边缘占比下限"
+    )
+    parser.add_argument("--selftest", action="store_true", help="打印阈值依据的对照数值后退出")
+    args = parser.parse_args(argv)
+
+    if args.selftest:
+        return selftest()
+    if args.png is None:
+        parser.error("需要给出 PNG 路径（或 --selftest）")
+
+    try:
+        stats = measure(*decode_png(args.png))
+    except (PngError, OSError, zlib.error) as error:
+        print(f"[fail] 读不出截图 {args.png}: {error}", file=sys.stderr)
+        return 1
+
+    problems = verdict(stats, args.min_unique, args.min_stddev, args.min_edge_ratio)
+    if args.json:
+        print(json.dumps({**stats, "problems": problems}, ensure_ascii=False))
+    else:
+        print(
+            f"{args.png}: {stats['width']}x{stats['height']} "
+            f"唯一色 {stats['unique_colors']} 亮度σ {stats['luma_stddev']} "
+            f"强边缘 {stats['edge_ratio']} 主色 {stats['top_color']}"
+            f"({stats['top_color_share'] * 100:.1f}%)"
+        )
+    if problems:
+        for problem in problems:
+            print(f"[fail] {problem}", file=sys.stderr)
+        return 1
+    print("[ok] 截图非空白")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
diff --git a/packaging/ci-runtime-smoke.md b/packaging/ci-runtime-smoke.md
new file mode 100644
index 0000000..c0de61b
--- /dev/null
+++ b/packaging/ci-runtime-smoke.md
@@ -0,0 +1,78 @@
+# CI 运行时冒烟（Linux 真渲染一帧）
+
+`packaging/README.md` §11 是本节的索引；细节在这里。为什么拆：本节要写阈值依据、失效模式与复跑口径，
+塞回 README 会撞 400 行硬门禁——**两文件都必须 ≤400 行**，任一边再增长就再拆一节。
+
+「编得过」≠「跑得起来」。`ci.yml` 的 `runtime-smoke` job 在 `ubuntu-latest` 上补第一份**真实图形环境**
+运行证据：装 `xvfb`（虚拟 X 服务器）+ 软渲染依赖 + 字体，用 `xvfb-run` 把 GUI 进程拉起来，走既有的
+进程内截图通道（`--software-renderer --screenshot <png> --data-dir <tmp>`）渲出一帧 PNG，再对**像素本身**断言。
+
+## 1. 三道断言
+
+`packaging/check_screenshot.py` 退出码 0 才算过；artifact 名 `runtime-smoke-screenshot`。
+
+1. 进程退出码 0（截图通道失败会以非 0 退出，不留半张图）；
+2. PNG 存在、可解析、宽高 > 0（0 字节 / 非 PNG / 路径不存在都是硬失败，脚本 exit 1）；
+3. **非空白**：唯一色数 / 亮度标准差 / 强边缘占比三项同时过阈值。
+
+为什么不能只看退出码：`--screenshot` 的 PNG 是进程自己编码写出的，只要流程走到 `take_snapshot` 就会得到
+「合法 PNG + 退出码 0」；像素断言是**纵深防御**，守的是「进程活着、写出合法 PNG，但场景几乎没画」这一档。
+本机可复现的两种失效都是硬失败（运行步就红，不必等像素断言）：①完全没有字体 → fontique panic
+（退出码 101，不产生 PNG）；②不是软渲染（默认 femtovg）→ `take_snapshot is not supported by this
+FemtoVG backend`（退出码 1）。这两条由 M62 review 实测复现（本 mission 未自己跑这两种破坏性实验）。
+其余「渲染器出图但内容没上去」的情形本机暂无样本，属防御性设计，不宣称已复现。
+
+## 2. 阈值与依据
+
+`python packaging/check_screenshot.py --selftest` 可复现后三行：
+
+| 样本 | 唯一色数 | 亮度σ | 强边缘占比 | 判定 |
+|------|---------|-------|-----------|------|
+| 本机 Docker 真截图（xvfb + 软渲染，1180x760，空数据目录） | 342 | 19.45 | 0.00761 | pass |
+| Windows 历史截图（M45/M52，同一界面深浅两套，1180x760） | 529~699 | 20.29~27.46 | 0.0186~0.0433 | pass |
+| 人为纯白 / 纯黑（空白帧） | 1 | 0.0 | 0.0 | fail |
+| 最弱内容（1 像素黑边框 + 一条中线） | 2 | 19.09 | 0.00169 | fail（卡唯一色数） |
+| **阈值** | ≥64 | ≥3.0 | ≥0.001 | — |
+
+阈值留 **5~8 倍**余量（342/64 = 5.3×、19.45/3.0 = 6.5×、0.00761/0.001 = 7.6×）：换主题/换字体不会误报，
+空白帧一定红。
+
+第三项用**强边缘占比**（水平相邻像素亮度差 ≥8 的比例）而不是平均亮度差：空数据目录的主界面 57% 是同一片
+底色，平均差被稀释到 0.4，强边缘只数真正的边界，跨主题稳定（同一界面深浅两套差 2 倍，仍都过线）。
+
+**这道闸门的下限 ≈「至少画出一条标题栏」**（review 实测切片）：只画 1180×40 标题栏的切片（174 / 35.10 /
+0.02623）仍 pass，右下 400×300 的切片也 pass。所以它证明的是「场景被真实渲染过」，**不证明界面元素齐全、
+更不证明视觉正确**；视觉正确只能靠人眼看 artifact。
+
+## 3. 覆盖哪个平台
+
+只有 Linux x64（X11 + Xvfb + 软渲染）。
+
+- **macOS**：`runtime-smoke-macos` 只在 `workflow_dispatch` 触发且 `continue-on-error: true`。官方 macOS
+  runner 处于 LaunchDaemon 上下文、无登录 WindowServer 会话，winit 大概率建不了窗口；本机没有 macOS
+  且 worker 禁 push，这条路径**尚无实测证据**，故不拿它卡 PR 门禁。首跑定去留：绿 → 删 `if` 与
+  `continue-on-error` 升常驻；红 → 错误原文进 progress，按 D26 归入 iced 重写再规划。
+- **Windows**：不新增 job——`--software-renderer --screenshot` 已在本机验收里多次人眼验证（M45/M52）。
+
+## 4. 本地复跑
+
+```bash
+bash packaging/linux-smoke-docker.sh . D:/tmp/ull-smoke
+```
+
+用 Docker（`rust:1-bookworm` + TUNA apt/rustup 源）复刻同一套步骤，截图落在 `<输出目录>/runtime-smoke.png`。
+**输出目录别写 `/tmp/...`**：Git Bash 里 `/tmp` 是 MSYS 虚拟路径，`docker -v` 会把它当 Linux VM 内的路径，
+结果是「脚本说成功、宿主机什么都没有」。脚本对 `out_dir`/`repo_root` 统一做 `cygpath -m` 归一，并回显真实
+路径；没有 `cygpath` 的平台（Linux/macOS）按原样用。
+
+诚实边界：本机容器是 Debian 12（glibc 2.36），官方 runner 是 Ubuntu 24.04（glibc 2.39），图形栈来源不同，
+容器绿只证明「这条通道能跑」，官方 runner 首跑仍要单独看。
+
+## 5. 已知跳过项与迁移风险
+
+**跳过项**（D26 收窄，本条只做「框架无关的最小运行时冒烟」）：Wayland（`weston --headless`）、
+`--screenshot-page` 子页覆盖、gsettings 主题探测回退都不在本 job 内，随 iced 重写另行规划。
+
+**迁移风险**：本 job 绑死 Slint 的截图通道（`Window::take_snapshot`）。**UI 迁 iced 后必须重新验证**——
+iced 没有等价快照 API，届时要提供「离屏渲染出一帧 PNG」的等价通道，否则本 job 会静默退化成「能起进程」
+而不是「能出图」（它本来也只证明「能出图」，不证明视觉正确）。
diff --git a/packaging/linux-smoke-docker.sh b/packaging/linux-smoke-docker.sh
new file mode 100644
index 0000000..9d08aff
--- /dev/null
+++ b/packaging/linux-smoke-docker.sh
@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# 本地复跑 `.github/workflows/ci.yml` 的 `runtime-smoke` job：Linux + Xvfb + 软渲染截图。
+#
+# 为什么要有这条脚本：CI 的 runtime-smoke 在 GitHub 的 ubuntu-latest 上跑，
+# 但「改动这个 job 的人」需要在没有 Linux 桌面的开发机上先自证一遍——否则改的就是没人验过的 YAML。
+# 本脚本在 Docker 里复刻 job 的步骤（同样的 apt 依赖、同样的构建、同样的 xvfb-run 命令），
+# 并把截图与判定结果留在宿主目录，供人眼与 `check_screenshot.py` 复核。
+#
+# 用法：
+#   bash packaging/linux-smoke-docker.sh [仓库根目录] [输出目录]
+#   ULL_SMOKE_SKIP_BUILD=1 bash packaging/linux-smoke-docker.sh   # 复用缓存的二进制
+#
+# 说明（诚实边界）：
+# - 基础镜像 `rust:1-bookworm` 是 **Debian 12（glibc 2.36）**，官方 runner 是 **Ubuntu 24.04（glibc 2.39）**。
+#   两者图形栈（X11/xvfb/Mesa 软渲染）来源不同，因此本脚本证明的是「Linux 上这条通道能真跑出图」，
+#   不能代替官方 runner 的首跑验证。
+# - 国内网络慢时可换 TUNA 镜像：脚本默认就用 TUNA 的 Debian 源（`ULL_APT_MIRROR` 可覆盖）。
+
+set -euo pipefail
+
+repo_root=$(cd "${1:-.}" && pwd)
+out_dir=${2:-ull-smoke}
+image=${ULL_SMOKE_IMAGE:-ull-linux-smoke:bookworm}
+cargo_volume=${ULL_CARGO_VOLUME:-ull-cargo-reg}
+target_volume=${ULL_CARGO_TARGET_VOLUME:-ull-linux-target}
+apt_mirror=${ULL_APT_MIRROR:-https://mirrors.tuna.tsinghua.edu.cn}
+rustup_mirror=${ULL_RUSTUP_MIRROR:-https://mirrors.tuna.tsinghua.edu.cn/rustup}
+
+mkdir -p "$out_dir"
+out_dir=$(cd "$out_dir" && pwd)
+# Git Bash 里 /tmp、/d/x 都是 MSYS 虚拟路径：直接喂给 `docker -v` 会被当成 Linux VM 内的路径，
+# 结果「脚本说成功、宿主机什么都没有」。有 cygpath 就统一转成 Windows 混合路径（D:/x）并回显真实位置。
+if command -v cygpath >/dev/null 2>&1; then
+  repo_root=$(cygpath -m "$repo_root")
+  out_dir=$(cygpath -m "$out_dir")
+fi
+echo "== 仓库: $repo_root"
+echo "== 输出: $out_dir（截图 $out_dir/runtime-smoke.png）"
+
+# 1) 构建镜像：rust 工具链 + xvfb + 图形栈编译依赖 + 字体（软渲染器要从系统字体库取字形）
+if ! docker image inspect "$image" >/dev/null 2>&1 || [ "${ULL_SMOKE_REBUILD_IMAGE:-0}" = "1" ]; then
+  context=$(mktemp -d)
+  trap 'rm -rf "$context"' EXIT
+  cat >"$context/Dockerfile" <<EOF
+FROM rust:1-bookworm
+# 工具链组件（rustfmt/clippy）在 rust-toolchain.toml 里是必备项，rustup 会去补齐；
+# 默认 dist 服务器在国内会挂成「rustc 0.6% CPU 睡 12 分钟」的假死（M62 实测），所以走 TUNA。
+ENV RUSTUP_DIST_SERVER=$rustup_mirror \\
+    RUSTUP_UPDATE_ROOT=$rustup_mirror/rustup
+RUN sed -i 's|http://deb.debian.org|$apt_mirror|g' /etc/apt/sources.list.d/debian.sources \\
+ && apt-get update \\
+ && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \\
+      xvfb xauth python3 \\
+      libxkbcommon-dev libxkbcommon-x11-0 libfontconfig1-dev \\
+      libgl1-mesa-dev libegl1-mesa-dev libwayland-dev libxcb1-dev \\
+      libx11-6 libxcursor1 libxrandr2 libxi6 \\
+      fonts-dejavu-core fonts-liberation2 \\
+ && rm -rf /var/lib/apt/lists/*
+RUN rustup component add rustfmt clippy && rustup toolchain list
+WORKDIR /src
+EOF
+  docker build -t "$image" "$context"
+fi
+
+# 2) 跑容器：构建 → xvfb 截图 → 像素判定
+# 注意缓存卷要挂到 `registry` 子目录：直接挂 /usr/local/cargo 会把镜像里的 `bin/`（cargo 本体）盖掉，
+# 变成 `cargo: command not found`（M62 实测踩到）。
+MSYS_NO_PATHCONV=1 docker run --rm \
+  -v "$repo_root:/src" \
+  -v "$cargo_volume:/usr/local/cargo/registry" \
+  -v "$target_volume:/target" \
+  -v "$out_dir:/out" \
+  -w /src \
+  -e CARGO_TARGET_DIR=/target \
+  -e ULL_SMOKE_SKIP_BUILD="${ULL_SMOKE_SKIP_BUILD:-0}" \
+  -e CARGO_TERM_COLOR=never \
+  "$image" bash -euo pipefail -c '
+    rustc --version && cargo --version && cat /etc/debian_version
+    if [ "$ULL_SMOKE_SKIP_BUILD" != "1" ]; then
+      # 共享热缓存卷可能喂陈旧产物（踩坑记录 N7）：先清掉受检 crate 再编
+      # 清不掉就算了（N7 兜底用）；CI 里**没有**对应两行，别误抄进 ci.yml —— 那边每次都是干净 runner
+      cargo clean -p unlucky-app || true
+      cargo build --bin unlucky-launcher --locked -j 6
+    fi
+    mkdir -p /out/data
+    set +e
+    xvfb-run -a --server-args="-screen 0 1280x1024x24" \
+      /target/debug/unlucky-launcher --software-renderer \
+      --screenshot /out/runtime-smoke.png --data-dir /out/data
+    code=$?
+    set -e
+    echo "exit=$code"
+    python3 packaging/check_screenshot.py /out/runtime-smoke.png
+    exit $code
+  '
+
+echo "== 截图与数据目录已留在 $out_dir"
diff --git a/packaging/make_artifacts.py b/packaging/make_artifacts.py
new file mode 100644
index 0000000..78fd048
--- /dev/null
+++ b/packaging/make_artifacts.py
@@ -0,0 +1,317 @@
+#!/usr/bin/env python3
+"""Build the single-file release artifacts for the current platform.
+
+Release matrix (see `packaging/README.md` for the full contract):
+
+    Windows x64     unlucky-launcher_<ver>_windows_x64.exe      (bare exe, no zip)
+    Windows arm64   unlucky-launcher_<ver>_windows_arm64.exe    (bare exe, cross-built)
+    Linux x64       unlucky-launcher_<ver>_linux_x64.tar.gz
+    Linux arm64     unlucky-launcher_<ver>_linux_arm64.tar.gz
+    macOS arm64     unlucky-launcher_<ver>_macos_arm64.tar.gz
+    macOS x64       unlucky-launcher_<ver>_macos_x64.tar.gz
+    every slot      ull_<ver>_<platform>_<arch>[.exe]           (bare CLI binary, no archive)
+    all             SHA256SUMS.txt
+
+Naming rule (user's call, 2026-11-05): `<name>_<version>_<platform>_<arch>`, underscore
+separated, and **no implementation detail in the file name** — the asset never says which UI
+framework produced it. `asset_stem()` is the single source of truth for that.
+
+`--version` is taken from the cargo workspace so a tag can never drift away from
+`Cargo.toml`; pass `--version` to cross-check a tag against it (mismatch is fatal).
+The archives carry the launcher binary plus LICENSE / NOTICE / README.md, which is
+what the license obligations ask for; Windows ships the bare `.exe` (the single-file
+selling point) and the same three documents are attached to the Release next to it.
+
+The CLI ships as its **own bare asset** on every platform rather than inside the tar.gz:
+the point of `ull` is a small single file you download and run on a machine with no
+display, and an archive it has to be extracted from adds a step for that user. The
+launcher is the archive because it needs the license texts beside it; the Release
+carries LICENSE / NOTICE / README.md anyway, so a bare `ull` loses nothing.
+
+The launcher binary also answers every CLI subcommand, so `ull` is not a second
+interface — it is the version of it that links no graphics stack at all.
+
+Slot and build directory are overridable because a cross build's binaries live in
+`target/<triple>/release` and the build host (x64) is not the artifact (arm64): CI
+passes both from its matrix, and the executable header is read back so a binary can
+never be shipped under a slot name it was not built for.
+
+Usage:
+    cargo build --release --locked
+    python3 packaging/make_artifacts.py [--version v0.2.0] [--out dist] [--no-smoke]
+    # cross build (arm64 exe from an x64 host):
+    python3 packaging/make_artifacts.py --slot windows-arm64 \\
+        --build-dir target/aarch64-pc-windows-msvc/release
+"""
+
+from __future__ import annotations
+
+import argparse
+import gzip
+import hashlib
+import json
+import platform
+import shutil
+import subprocess
+import sys
+import tarfile
+from pathlib import Path
+from typing import NoReturn
+
+# M118（D26）：GUI 的**构建产物**名是 iced 版的 `unlucky-launcher-iced`。旧值 `unlucky-launcher`
+# 是 `crates/app`（Slint 退役树）的 bin —— 那棵树已被根 Cargo.toml `exclude`，再也不产出它了。
+# **对外**文件名仍叫 `unlucky-launcher`：下载链接 / SHA256SUMS / README 都绑着这个名字，
+# 改名是「翻牌」那一步的事，不是打包这一步的事。所以刻意拆成两个常量：
+# 找文件用 LAUNCHER_BIN，落盘（tar 内文件名 / exe 资产名）用 LAUNCHER_ASSET。
+LAUNCHER_BIN = "unlucky-launcher-iced"
+LAUNCHER_ASSET = "unlucky-launcher"
+CLI_BIN = "ull"
+# 随包分发的合规文本（仓库根目录）；英文主版 README 是对外分发口径。
+COMPLIANCE_DOCS = ("LICENSE", "NOTICE", "README.md")
+SUMS_NAME = "SHA256SUMS.txt"
+DEFAULT_BUILD_DIR = "target/release"
+
+# 发布矩阵：槽位 -> (OS 家族, 架构, 产物形态)。键名即产物文件名里的槽位段，
+# 单一真相源是 packaging/README.md §1；未知槽位一律拒绝，不出"凑合能跑"的产物。
+SLOTS = {
+    "windows-x64": ("windows", "x64", "exe"),
+    "windows-arm64": ("windows", "arm64", "exe"),
+    "linux-x64": ("linux", "x64", "tar"),
+    "linux-arm64": ("linux", "arm64", "tar"),
+    "macos-arm64": ("macos", "arm64", "tar"),
+    "macos-x64": ("macos", "x64", "tar"),
+}
+# `sys.platform` / `platform.machine()` 的别名归一（aarch64 与 arm64 是同一架构的两种叫法）。
+OS_FAMILIES = (("win", "windows"), ("linux", "linux"), ("darwin", "macos"))
+MACHINE_ALIASES = {"amd64": "x64", "x86_64": "x64", "aarch64": "arm64", "arm64": "arm64"}
+# 可执行文件头里的机器码 -> 架构（PE / ELF / Mach-O）。
+IMAGE_ARCH = {
+    ("pe", 0x8664): "x64",
+    ("pe", 0xAA64): "arm64",
+    ("elf", 0x3E): "x64",
+    ("elf", 0xB7): "arm64",
+    ("macho", 0x01000007): "x64",
+    ("macho", 0x0100000C): "arm64",
+}
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+
+def fail(message: str) -> NoReturn:
+    print(f"error: {message}", file=sys.stderr)
+    raise SystemExit(1)
+
+
+def workspace_version() -> str:
+    """Read `[workspace.package] version` through cargo itself (single source of truth)."""
+    try:
+        raw = subprocess.run(
+            ["cargo", "metadata", "--no-deps", "--format-version", "1"],
+            cwd=REPO_ROOT,
+            check=True,
+            capture_output=True,
+            text=True,
+            # Windows 默认 GBK：cargo 的 package description 是中文，不显式指定会解码失败。
+            encoding="utf-8",
+            errors="replace",
+        ).stdout
+    except (OSError, subprocess.CalledProcessError) as exc:
+        fail(f"cargo metadata failed: {exc}")
+    packages = json.loads(raw)["packages"]
+    versions = {pkg["version"] for pkg in packages}
+    if len(versions) != 1:
+        fail(f"workspace members disagree on version: {sorted(versions)}")
+    return versions.pop()
+
+
+def host_slot(os_name: str | None = None, machine: str | None = None) -> str:
+    """Map the build host to a matrix slot.
+
+    Both arguments are injectable so the mapping can be exercised for a host we do not
+    own (no ARM machine here); they default to the real ones.
+    """
+    os_name = (sys.platform if os_name is None else os_name).lower()
+    raw_machine = platform.machine() if machine is None else machine
+    arch = MACHINE_ALIASES.get(raw_machine.lower())
+    family = next((fam for prefix, fam in OS_FAMILIES if os_name.startswith(prefix)), None)
+    for slot, (slot_os, slot_arch, _) in SLOTS.items():
+        if (slot_os, slot_arch) == (family, arch):
+            return slot
+    # 报错带**原始**取值而不是归一后的 None：`riscv64` 这类不认识的架构得在诊断里看得见。
+    fail(f"unsupported build host {os_name}/{raw_machine}; matrix is {' / '.join(SLOTS)}")
+
+
+def binary(name: str, build_dir: Path, family: str) -> Path:
+    path = build_dir / (f"{name}.exe" if family == "windows" else name)
+    if not path.is_file():
+        fail(f"missing {path}; run `cargo build --release --locked` first")
+    return path
+
+
+def image_arch(path: Path) -> str | None:
+    """Architecture stamped into the executable header, or `None` if unreadable."""
+    with path.open("rb") as handle:
+        head = handle.read(0x40)
+        if head[:4] == b"\x7fELF":
+            order = "little" if head[5] == 1 else "big"
+            return IMAGE_ARCH.get(("elf", int.from_bytes(head[18:20], order)))
+        if head[:2] == b"MZ":
+            handle.seek(int.from_bytes(head[0x3C:0x40], "little"))
+            pe = handle.read(6)
+            if pe[:4] == b"PE\0\0":
+                return IMAGE_ARCH.get(("pe", int.from_bytes(pe[4:6], "little")))
+            return None
+        if head[:4] == b"\xcf\xfa\xed\xfe":  # thin 64-bit little-endian Mach-O
+            return IMAGE_ARCH.get(("macho", int.from_bytes(head[4:8], "little")))
+    return None
+
+
+def verify_arch(path: Path, slot: str) -> None:
+    """Prove the binary really is built for the slot it is about to be named after."""
+    want = SLOTS[slot][1]
+    got = image_arch(path)
+    if got is None:
+        fail(f"cannot read the machine type of {path}; refusing to ship an unverified binary")
+    if got != want:
+        fail(f"{path} is a {got} binary but slot {slot} says {want}")
+    print(f"arch:     {path.name} -> {got} (ok for {slot})")
+
+
+def smoke_version(cli: Path, version: str) -> None:
+    """`ull --version` must report the workspace version (guards tag/version drift)."""
+    proc = subprocess.run(
+        [str(cli), "--version"],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    out = (proc.stdout or "") + (proc.stderr or "")
+    if proc.returncode != 0:
+        fail(f"`{cli.name} --version` exited {proc.returncode}: {out.strip()}")
+    if version not in out:
+        fail(f"`{cli.name} --version` does not report {version}: {out.strip()}")
+    print(f"smoke:    {cli.name} --version -> {version} (ok)")
+
+
+def sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def write_sums(out_dir: Path, assets: list[Path]) -> Path:
+    sums = out_dir / SUMS_NAME
+    lines = [f"{sha256(path)}  {path.name}" for path in sorted(assets)]
+    sums.write_text("\n".join(lines) + "\n", encoding="utf-8", newline="\n")
+    return sums
+
+
+def asset_stem(name: str, version: str, slot: str) -> str:
+    """`<name>_<version>_<platform>_<arch>` — 产物命名的唯一真相源。
+
+    用户令（2026-11-05）：产物名按 `名字_版本号_平台_架构` 下划线分段，且**不得出现 `iced`
+    这类实现细节字样** —— 下载的人不该关心我们内部用哪个 UI 框架。槽位键（`windows-x64`）
+    仍是脚本内部的写法，落到文件名时拆成 `windows_x64` 两段。
+    """
+    family, arch, _kind = SLOTS[slot]
+    return f"{name}_{version}_{family}_{arch}"
+
+
+def stage_cli(out_dir: Path, version: str, slot: str, cli: Path) -> Path:
+    """Copy the CLI out as its own bare asset (`ull_<ver>_<platform>_<arch>[.exe]`)."""
+    name = asset_stem(CLI_BIN, version, slot) + (".exe" if cli.suffix == ".exe" else "")
+    asset = out_dir / name
+    shutil.copy2(cli, asset)
+    # 裸文件下载即可运行：Windows 宿主机上源文件没有 x 位，这里补上（UNIX 侧才有意义）。
+    asset.chmod(0o755)
+    return asset
+
+
+def stage_archive(out_dir: Path, tag: str, version: str, launcher: Path) -> Path:
+    """tar.gz with one top-level dir holding the binary + compliance docs."""
+    stem = asset_stem(LAUNCHER_ASSET, version, tag)
+    stage = out_dir / stem
+    if stage.exists():
+        shutil.rmtree(stage)
+    stage.mkdir(parents=True)
+    shutil.copy2(launcher, stage / LAUNCHER_ASSET)
+    for doc in COMPLIANCE_DOCS:
+        source = REPO_ROOT / doc
+        if not source.is_file():
+            fail(f"compliance file {source} is missing")
+        shutil.copy2(source, stage / doc)
+    # tar 内的 mtime/uid/mode 与 gzip 头的 mtime 全部归零 → 同源构建的 sha256 与打包时刻无关。
+    archive = out_dir / f"{stem}.tar.gz"
+    with archive.open("wb") as raw, gzip.GzipFile(
+        fileobj=raw, mode="wb", compresslevel=9, mtime=0
+    ) as gz, tarfile.open(fileobj=gz, mode="w") as tar:
+        for entry in sorted(stage.iterdir()):
+            info = tar.gettarinfo(str(entry), arcname=f"{stem}/{entry.name}")
+            info.mtime = 0
+            info.uid = info.gid = 0
+            info.uname = info.gname = ""
+            info.mode = 0o755 if entry.name == LAUNCHER_ASSET else 0o644
+            with entry.open("rb") as handle:
+                tar.addfile(info, handle)
+    shutil.rmtree(stage)
+    return archive
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--version", help="expected version (a leading 'v' is stripped); cross-checks Cargo.toml")
+    parser.add_argument("--out", default="dist", help="output directory (default: dist/)")
+    parser.add_argument("--slot", choices=list(SLOTS), help="matrix slot; defaults to the one derived from the host")
+    parser.add_argument("--build-dir", default=DEFAULT_BUILD_DIR, help=f"directory holding the built binaries (default: {DEFAULT_BUILD_DIR})")
+    parser.add_argument("--no-smoke", action="store_true", help="skip the `ull --version` smoke run")
+    args = parser.parse_args()
+
+    version = workspace_version()
+    if args.version:
+        expected = args.version[1:] if args.version.startswith("v") else args.version
+        if expected != version:
+            fail(f"tag/version mismatch: requested {expected}, Cargo.toml says {version}")
+    native = host_slot()
+    slot = args.slot or native
+    family, _, kind = SLOTS[slot]
+    build_dir = Path(args.build_dir)
+    if not build_dir.is_absolute():
+        build_dir = REPO_ROOT / build_dir
+    launcher = binary(LAUNCHER_BIN, build_dir, family)
+    verify_arch(launcher, slot)
+    # 跨槽位产物（宿主 x64 / 目标 arm64）在本机根本执行不了，冒烟只能等 CI 真机；
+    # 拿"跳过了"当通过是假证据，所以把跳过原因原样打出来。
+    if args.no_smoke or slot != native:
+        reason = "--no-smoke" if args.no_smoke else f"host is {native}, artifact is {slot}"
+        print(f"smoke:    skipped ({reason})")
+    else:
+        smoke_version(binary(CLI_BIN, build_dir, family), version)
+
+    out_dir = Path(args.out)
+    if not out_dir.is_absolute():
+        out_dir = REPO_ROOT / out_dir
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    if kind == "exe":
+        asset = out_dir / f"{asset_stem(LAUNCHER_ASSET, version, slot)}.exe"
+        shutil.copy2(launcher, asset)
+    else:
+        asset = stage_archive(out_dir, slot, version, launcher)
+    # CLI 与 GUI 同一矩阵槽位、各自独立资产：架构同样回读文件头校验，不给 arm64 槽位混进 x64 的 ull。
+    cli = binary(CLI_BIN, build_dir, family)
+    verify_arch(cli, slot)
+    cli_asset = stage_cli(out_dir, version, slot, cli)
+
+    sums = write_sums(out_dir, [asset, cli_asset])
+    for item in (asset, cli_asset):
+        size_mb = item.stat().st_size / (1024 * 1024)
+        print(f"artifact: {item.name}  {size_mb:.2f} MiB  sha256={sha256(item)}")
+    print(f"sums:     {sums.name}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/packaging/release-notes.md b/packaging/release-notes.md
new file mode 100644
index 0000000..7d6c63b
--- /dev/null
+++ b/packaging/release-notes.md
@@ -0,0 +1,124 @@
+# Unlucky Launcher {{VERSION}}
+
+Rust-native **single-file** Minecraft launcher: iced 0.14 + Material 3 Expressive UI, built-in AI agent
+(chat / config edits / crash diagnosis) and an MCP server other agent tools can attach to.
+No WebView, no bundled runtime, no JRE download needed to start the launcher itself.
+
+## Downloads
+
+| Platform | Asset | Notes |
+| --- | --- | --- |
+| Windows 10/11 x64 | `unlucky-launcher-{{VERSION}}-windows-x64.exe` | single exe, double-click to run |
+| Windows 11 ARM64 | `unlucky-launcher-{{VERSION}}-windows-arm64.exe` | single exe, runs natively on ARM64 Windows |
+| Linux x64 (X11/Wayland) | `unlucky-launcher-{{VERSION}}-linux-x64.tar.gz` | single binary inside, no installer |
+| Linux arm64 (X11/Wayland) | `unlucky-launcher-{{VERSION}}-linux-arm64.tar.gz` | single binary inside; needs glibc 2.35+ |
+| macOS 12+ Apple Silicon | `unlucky-launcher-{{VERSION}}-macos-arm64.tar.gz` | single binary inside, no installer |
+| macOS 12+ Intel | `unlucky-launcher-{{VERSION}}-macos-x64.tar.gz` | single binary inside, no installer |
+
+`LICENSE`, `NOTICE` and `README.md` ship in every archive; on Windows they are attached to
+this release next to the `.exe` (a lone exe cannot carry them), so the license terms travel
+with the download on every platform.
+
+Every slot also ships the command line as its own small asset — `ull-{{VERSION}}-<slot>`
+(`.exe` on Windows):
+
+```bash
+chmod +x ull-{{VERSION}}-linux-x64             # Release 资产不带可执行位，先补上
+./ull-{{VERSION}}-linux-x64 instances list     # servers / CI / Termux: no graphics stack needed
+unlucky-launcher instances list                # desktops: the GUI binary answers the same commands
+```
+
+`ull` runs `instances`, `install`, `launch`, `accounts`, `sessions`, `logs`, `diag`, `config`,
+`java` and `agent`, and links no graphics library at all. The GUI binary accepts the same set
+before it ever opens a window, so on a machine with a desktop you do not need `ull`.
+
+## Support matrix
+
+| Platform | Level | Runtime requirements |
+| --- | --- | --- |
+| Windows 10/11 x64 | first class | nothing beyond the OS (UCRT is part of Win10+) |
+| Windows 11 ARM64 | first class (launcher artifact) | nothing extra; launcher runs natively, the game itself runs through the OS x64 emulation layer with an x64 JDK |
+| macOS 12+ (arm64 / x64) | first class | nothing; unsigned build, see Gatekeeper note |
+| Linux x64, X11 | first class | `libxkbcommon`, `fontconfig`, `libGL` (or software renderer), `libxcb` |
+| Linux x64, Wayland | supported | `wayland-client`, `libxkbcommon`, plus the X11 set for XWayland apps |
+| Linux arm64, X11 | first class | glibc 2.35+ (built on `ubuntu-22.04-arm`, same floor as x64), `libxkbcommon`, `fontconfig`, `libGL`, `libxcb` |
+| Linux arm64, Wayland | supported | the above plus `wayland-client` |
+| Windows 8.1/8/7 | unsupported | baseline was raised to Win10 (decision D21) |
+| Android — Termux + X11 | experimental, not promised | CLI only (the `ull` asset, or build from source), GUI unverified; not part of this release matrix |
+
+Both arm64 rows are **formally released slots** (the assets ship in this release and in
+`SHA256SUMS.txt`), not the experimental Termux path: Linux arm64 is built and smoke-tested on a
+native ARM64 runner, Windows ARM64 is cross-built with the same static-CRT gate as x64.
+
+## Install
+
+**Windows** — put the `.exe` anywhere and run it (pick `-windows-arm64.exe` on ARM64 Windows,
+`-windows-x64.exe` everywhere else). Portable data lives next to the exe when a
+`portable.marker` file is present, otherwise under `%APPDATA%`.
+
+**Linux**
+
+```bash
+tar -xzf unlucky-launcher-{{VERSION}}-linux-x64.tar.gz   # use linux-arm64 on aarch64
+cd unlucky-launcher-{{VERSION}}-linux-x64                # ditto
+chmod +x unlucky-launcher && ./unlucky-launcher
+```
+
+**macOS**
+
+```bash
+tar -xzf unlucky-launcher-{{VERSION}}-macos-arm64.tar.gz
+cd unlucky-launcher-{{VERSION}}-macos-arm64
+xattr -d com.apple.quarantine unlucky-launcher   # unsigned build, Gatekeeper quarantine
+chmod +x unlucky-launcher && ./unlucky-launcher
+```
+
+## No GPU? Software renderer
+
+The UI renders through `wgpu` (GPU) and falls back to the `tiny-skia` CPU rasteriser when no usable
+adapter is present. Force the CPU path on any machine with:
+
+```bash
+unlucky-launcher --software-renderer          # the documented switch
+unlucky-launcher --renderer=cpu               # equivalent: pick the CPU renderer explicitly
+```
+
+## Verify the download
+
+```bash
+# Linux / macOS
+sha256sum -c SHA256SUMS.txt --ignore-missing
+# Windows (PowerShell)
+Get-FileHash .\unlucky-launcher-{{VERSION}}-windows-x64.exe -Algorithm SHA256
+```
+
+## Checksums
+
+```
+{{SUMS}}
+```
+
+## Known limitations of this build
+
+- Microsoft (MSA) account login depends on a Mojang app-id whitelist that is still pending;
+  until it is granted, use offline accounts or authlib-injector (the 403 is reported with a
+  readable diagnostic instead of a silent failure).
+- Binaries are not code-signed / notarized yet: Windows SmartScreen and macOS Gatekeeper warn
+  on first launch. Checksums above are the integrity reference for now.
+- macOS ships the bare binary (single-file promise), not a `.app` bundle: no Dock icon or
+  Finder double-click — launch it from a terminal.
+
+## License
+
+Apache-2.0. Third-party notices are in `NOTICE`. Unlucky Launcher is not affiliated with Mojang or
+Microsoft; it does not ship game files.
+
+## UI framework in this build
+
+Every asset in this release is built from the iced UI (`crates/app-iced`, iced 0.14, MIT) — no Slint
+code is linked into it. The earlier Slint UI (`crates/app`) stays in the repository as historical
+source only: excluded from the cargo workspace, not built, not part of any asset here and not part of
+the release matrix. It did ship in the previous `v0.1.0` release; that release's Slint Royalty-Free
+2.0 attribution remains where it was published, and no asset in this build carries that obligation.
+There is deliberately no "Made with Slint" badge on this page: the obligation follows a Slint-linked
+binary, and this release has none.
diff --git a/rust-toolchain.toml b/rust-toolchain.toml
new file mode 100644
index 0000000..ab71de3
--- /dev/null
+++ b/rust-toolchain.toml
@@ -0,0 +1,6 @@
+[toolchain]
+# 全仓统一 stable，不在仓库内钉死具体小版本（CI 与本地同样走 stable 解析）。
+# 各平台（Win10+ / macOS / Linux）共用本文件，不按平台另起工具链。
+channel = "stable"
+profile = "minimal"
+components = ["rustfmt", "clippy"]